commit 69dd868e2fd4ba6f8630e9e19e878959c8011d9c Author: lidf Date: Tue Apr 28 13:12:54 2026 +0800 init: MindOS CLI 本地执行体（从 mindOSv2/mindos-cli 独立） - 独立 pyproject.toml（pip install -e .） - vendor_hermes.sh 已改为显式路径模式（不再依赖相对目录） - 包含 hermes vendor 快照 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..80d40c1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +__pycache__/ +*.pyc +.venv/ +*.egg-info/ +dist/ +build/ +.DS_Store diff --git a/mindcli/__init__.py b/mindcli/__init__.py new file mode 100644 index 0000000..6a9ff46 --- /dev/null +++ b/mindcli/__init__.py @@ -0,0 +1,22 @@ +""" +MindOS CLI — Cloud Hermes 的受管理执行节点。 + +包初始化：将 _vendor/ 目录加入 sys.path， +使 Hermes 模块的内部 import 路径保持原样工作。 + +POC 验证结论：sys.path.insert(0, _vendor_dir) 一行即可， +不需要重写 Hermes 的 10K 行代码中的任何 import。 +""" + +import os +import sys + +__version__ = "0.1.0" + +# ── Vendor 路径注入 ────────────────────────────────────────── +# 将 _vendor/ 目录加入 sys.path 头部， +# 使 Hermes 的 `from hermes_state import ...` 等裸 import 直接工作。 +# 类似 pip._vendor 的 sys.path 策略。 +_VENDOR_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "_vendor") +if os.path.isdir(_VENDOR_DIR) and _VENDOR_DIR not in sys.path: + sys.path.insert(0, _VENDOR_DIR) diff --git a/mindcli/__main__.py b/mindcli/__main__.py new file mode 100644 index 0000000..6e3d1cb --- /dev/null +++ b/mindcli/__main__.py @@ -0,0 +1,5 @@ +"""python -m mindcli 入口。""" +from mindcli.cli import main + +if __name__ == "__main__": + main() diff --git a/mindcli/_vendor/HERMES_COMMIT b/mindcli/_vendor/HERMES_COMMIT new file mode 100644 index 0000000..9c4019f --- /dev/null +++ b/mindcli/_vendor/HERMES_COMMIT @@ -0,0 +1 @@ +16f9d020 diff --git a/mindcli/_vendor/__init__.py b/mindcli/_vendor/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/mindcli/_vendor/agent/__init__.py b/mindcli/_vendor/agent/__init__.py new file mode 100644 index 0000000..aaa2d74 --- /dev/null +++ b/mindcli/_vendor/agent/__init__.py @@ -0,0 +1,6 @@ +"""Agent internals -- extracted modules from run_agent.py. + +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. +""" diff --git a/mindcli/_vendor/agent/anthropic_adapter.py b/mindcli/_vendor/agent/anthropic_adapter.py new file mode 100644 index 0000000..b85f77a --- /dev/null +++ b/mindcli/_vendor/agent/anthropic_adapter.py @@ -0,0 +1,1411 @@ +"""Anthropic Messages API adapter for Hermes Agent. + +Translates between Hermes's internal OpenAI-style message format and +Anthropic's Messages API. Follows the same pattern as the codex_responses +adapter — all provider-specific logic is isolated here. + +Auth supports: + - Regular API keys (sk-ant-api*) → x-api-key header + - OAuth setup-tokens (sk-ant-oat*) → Bearer auth + beta header + - Claude Code credentials (~/.claude.json or ~/.claude/.credentials.json) → Bearer auth +""" + +import copy +import json +import logging +import os +from pathlib import Path + +from hermes_constants import get_hermes_home +from types import SimpleNamespace +from typing import Any, Dict, List, Optional, Tuple + +try: + import anthropic as _anthropic_sdk +except ImportError: + _anthropic_sdk = None # type: ignore[assignment] + +logger = logging.getLogger(__name__) + +THINKING_BUDGET = {"xhigh": 32000, "high": 16000, "medium": 8000, "low": 4000} +ADAPTIVE_EFFORT_MAP = { + "xhigh": "max", + "high": "high", + "medium": "medium", + "low": "low", + "minimal": "low", +} + +# ── Max output token limits per Anthropic model ─────────────────────── +# Source: Anthropic docs + Cline model catalog. Anthropic's API requires +# max_tokens as a mandatory field. Previously we hardcoded 16384, which +# starves thinking-enabled models (thinking tokens count toward the limit). +_ANTHROPIC_OUTPUT_LIMITS = { + # Claude 4.6 + "claude-opus-4-6": 128_000, + "claude-sonnet-4-6": 64_000, + # Claude 4.5 + "claude-opus-4-5": 64_000, + "claude-sonnet-4-5": 64_000, + "claude-haiku-4-5": 64_000, + # Claude 4 + "claude-opus-4": 32_000, + "claude-sonnet-4": 64_000, + # Claude 3.7 + "claude-3-7-sonnet": 128_000, + # Claude 3.5 + "claude-3-5-sonnet": 8_192, + "claude-3-5-haiku": 8_192, + # Claude 3 + "claude-3-opus": 4_096, + "claude-3-sonnet": 4_096, + "claude-3-haiku": 4_096, + # Third-party Anthropic-compatible providers + "minimax": 131_072, +} + +# For any model not in the table, assume the highest current limit. +# Future Anthropic models are unlikely to have *less* output capacity. +_ANTHROPIC_DEFAULT_OUTPUT_LIMIT = 128_000 + + +def _get_anthropic_max_output(model: str) -> int: + """Look up the max output token limit for an Anthropic model. + + Uses substring matching against _ANTHROPIC_OUTPUT_LIMITS so date-stamped + model IDs (claude-sonnet-4-5-20250929) and variant suffixes (:1m, :fast) + resolve correctly. Longest-prefix match wins to avoid e.g. "claude-3-5" + matching before "claude-3-5-sonnet". + + Normalizes dots to hyphens so that model names like + ``anthropic/claude-opus-4.6`` match the ``claude-opus-4-6`` table key. + """ + m = model.lower().replace(".", "-") + best_key = "" + best_val = _ANTHROPIC_DEFAULT_OUTPUT_LIMIT + for key, val in _ANTHROPIC_OUTPUT_LIMITS.items(): + if key in m and len(key) > len(best_key): + best_key = key + best_val = val + return best_val + + +def _supports_adaptive_thinking(model: str) -> bool: + """Return True for Claude 4.6 models that support adaptive thinking.""" + return any(v in model for v in ("4-6", "4.6")) + + +# Beta headers for enhanced features (sent with ALL auth types) +_COMMON_BETAS = [ + "interleaved-thinking-2025-05-14", + "fine-grained-tool-streaming-2025-05-14", +] +# MiniMax's Anthropic-compatible endpoints fail tool-use requests when +# the fine-grained tool streaming beta is present. Omit it so tool calls +# fall back to the provider's default response path. +_TOOL_STREAMING_BETA = "fine-grained-tool-streaming-2025-05-14" + +# Fast mode beta — enables the ``speed: "fast"`` request parameter for +# significantly higher output token throughput on Opus 4.6 (~2.5x). +# See https://platform.claude.com/docs/en/build-with-claude/fast-mode +_FAST_MODE_BETA = "fast-mode-2026-02-01" + +# Additional beta headers required for OAuth/subscription auth. +# Matches what Claude Code (and pi-ai / OpenCode) send. +_OAUTH_ONLY_BETAS = [ + "claude-code-20250219", + "oauth-2025-04-20", +] + +# Claude Code identity — required for OAuth requests to be routed correctly. +# Without these, Anthropic's infrastructure intermittently 500s OAuth traffic. +# The version must stay reasonably current — Anthropic rejects OAuth requests +# when the spoofed user-agent version is too far behind the actual release. +_CLAUDE_CODE_VERSION_FALLBACK = "2.1.74" +_claude_code_version_cache: Optional[str] = None + + +def _detect_claude_code_version() -> str: + """Detect the installed Claude Code version, fall back to a static constant. + + Anthropic's OAuth infrastructure validates the user-agent version and may + reject requests with a version that's too old. Detecting dynamically means + users who keep Claude Code updated never hit stale-version 400s. + """ + import subprocess as _sp + + for cmd in ("claude", "claude-code"): + try: + result = _sp.run( + [cmd, "--version"], + capture_output=True, text=True, timeout=5, + ) + if result.returncode == 0 and result.stdout.strip(): + # Output is like "2.1.74 (Claude Code)" or just "2.1.74" + version = result.stdout.strip().split()[0] + if version and version[0].isdigit(): + return version + except Exception: + pass + return _CLAUDE_CODE_VERSION_FALLBACK + + +_CLAUDE_CODE_SYSTEM_PREFIX = "You are Claude Code, Anthropic's official CLI for Claude." +_MCP_TOOL_PREFIX = "mcp_" + + +def _get_claude_code_version() -> str: + """Lazily detect the installed Claude Code version when OAuth headers need it.""" + global _claude_code_version_cache + if _claude_code_version_cache is None: + _claude_code_version_cache = _detect_claude_code_version() + return _claude_code_version_cache + + +def _is_oauth_token(key: str) -> bool: + """Check if the key is an Anthropic OAuth/setup token. + + Positively identifies Anthropic OAuth tokens by their key format: + - ``sk-ant-`` prefix (but NOT ``sk-ant-api``) → setup tokens, managed keys + - ``eyJ`` prefix → JWTs from the Anthropic OAuth flow + + Non-Anthropic keys (MiniMax, Alibaba, etc.) don't match either pattern + and correctly return False. + """ + if not key: + return False + # Regular Anthropic Console API keys — x-api-key auth, never OAuth + if key.startswith("sk-ant-api"): + return False + # Anthropic-issued tokens (setup-tokens sk-ant-oat-*, managed keys) + if key.startswith("sk-ant-"): + return True + # JWTs from Anthropic OAuth flow + if key.startswith("eyJ"): + return True + return False + + +def _normalize_base_url_text(base_url) -> str: + """Normalize SDK/base transport URL values to a plain string for inspection. + + Some client objects expose ``base_url`` as an ``httpx.URL`` instead of a raw + string. Provider/auth detection should accept either shape. + """ + if not base_url: + return "" + return str(base_url).strip() + + +def _is_third_party_anthropic_endpoint(base_url: str | None) -> bool: + """Return True for non-Anthropic endpoints using the Anthropic Messages API. + + Third-party proxies (Azure AI Foundry, AWS Bedrock, self-hosted) authenticate + with their own API keys via x-api-key, not Anthropic OAuth tokens. OAuth + detection should be skipped for these endpoints. + """ + normalized = _normalize_base_url_text(base_url) + if not normalized: + return False # No base_url = direct Anthropic API + normalized = normalized.rstrip("/").lower() + if "anthropic.com" in normalized: + return False # Direct Anthropic API — OAuth applies + return True # Any other endpoint is a third-party proxy + + +def _requires_bearer_auth(base_url: str | None) -> bool: + """Return True for Anthropic-compatible providers that require Bearer auth. + + Some third-party /anthropic endpoints implement Anthropic's Messages API but + require Authorization: Bearer *** of Anthropic's native x-api-key header. + MiniMax's global and China Anthropic-compatible endpoints follow this pattern. + """ + normalized = _normalize_base_url_text(base_url) + if not normalized: + return False + normalized = normalized.rstrip("/").lower() + return normalized.startswith(("https://api.minimax.io/anthropic", "https://api.minimaxi.com/anthropic")) + + +def _common_betas_for_base_url(base_url: str | None) -> list[str]: + """Return the beta headers that are safe for the configured endpoint. + + MiniMax's Anthropic-compatible endpoints (Bearer-auth) reject requests + that include Anthropic's ``fine-grained-tool-streaming`` beta — every + tool-use message triggers a connection error. Strip that beta for + Bearer-auth endpoints while keeping all other betas intact. + """ + if _requires_bearer_auth(base_url): + return [b for b in _COMMON_BETAS if b != _TOOL_STREAMING_BETA] + return _COMMON_BETAS + + +def build_anthropic_client(api_key: str, base_url: str = None): + """Create an Anthropic client, auto-detecting setup-tokens vs API keys. + + Returns an anthropic.Anthropic instance. + """ + if _anthropic_sdk is None: + raise ImportError( + "The 'anthropic' package is required for the Anthropic provider. " + "Install it with: pip install 'anthropic>=0.39.0'" + ) + from httpx import Timeout + + normalized_base_url = _normalize_base_url_text(base_url) + kwargs = { + "timeout": Timeout(timeout=900.0, connect=10.0), + } + if normalized_base_url: + kwargs["base_url"] = normalized_base_url + common_betas = _common_betas_for_base_url(normalized_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. + # Check this before OAuth token shape detection because MiniMax secrets do + # not use Anthropic's sk-ant-api prefix and would otherwise be misread as + # Anthropic OAuth/setup tokens. + kwargs["auth_token"] = api_key + if common_betas: + kwargs["default_headers"] = {"anthropic-beta": ",".join(common_betas)} + elif _is_third_party_anthropic_endpoint(base_url): + # Third-party proxies (Azure AI Foundry, AWS Bedrock, etc.) use their + # own API keys with x-api-key auth. Skip OAuth detection — their keys + # don't follow Anthropic's sk-ant-* prefix convention and would be + # misclassified as OAuth tokens. + kwargs["api_key"] = api_key + if common_betas: + kwargs["default_headers"] = {"anthropic-beta": ",".join(common_betas)} + elif _is_oauth_token(api_key): + # OAuth access token / setup-token → Bearer auth + Claude Code identity. + # Anthropic routes OAuth requests based on user-agent and headers; + # without Claude Code's fingerprint, requests get intermittent 500s. + all_betas = common_betas + _OAUTH_ONLY_BETAS + kwargs["auth_token"] = api_key + kwargs["default_headers"] = { + "anthropic-beta": ",".join(all_betas), + "user-agent": f"claude-cli/{_get_claude_code_version()} (external, cli)", + "x-app": "cli", + } + else: + # Regular API key → x-api-key header + common betas + kwargs["api_key"] = api_key + if common_betas: + kwargs["default_headers"] = {"anthropic-beta": ",".join(common_betas)} + + return _anthropic_sdk.Anthropic(**kwargs) + + +def read_claude_code_credentials() -> Optional[Dict[str, Any]]: + """Read refreshable Claude Code OAuth credentials from ~/.claude/.credentials.json. + + This intentionally excludes ~/.claude.json primaryApiKey. Opencode's + subscription flow is OAuth/setup-token based with refreshable credentials, + and native direct Anthropic provider usage should follow that path rather + than auto-detecting Claude's first-party managed key. + + Returns dict with {accessToken, refreshToken?, expiresAt?} or None. + """ + cred_path = Path.home() / ".claude" / ".credentials.json" + if cred_path.exists(): + try: + data = json.loads(cred_path.read_text(encoding="utf-8")) + oauth_data = data.get("claudeAiOauth") + if oauth_data and isinstance(oauth_data, dict): + access_token = oauth_data.get("accessToken", "") + if access_token: + return { + "accessToken": access_token, + "refreshToken": oauth_data.get("refreshToken", ""), + "expiresAt": oauth_data.get("expiresAt", 0), + "source": "claude_code_credentials_file", + } + except (json.JSONDecodeError, OSError, IOError) as e: + logger.debug("Failed to read ~/.claude/.credentials.json: %s", e) + + return None + + +def read_claude_managed_key() -> Optional[str]: + """Read Claude's native managed key from ~/.claude.json for diagnostics only.""" + claude_json = Path.home() / ".claude.json" + if claude_json.exists(): + try: + data = json.loads(claude_json.read_text(encoding="utf-8")) + primary_key = data.get("primaryApiKey", "") + if isinstance(primary_key, str) and primary_key.strip(): + return primary_key.strip() + except (json.JSONDecodeError, OSError, IOError) as e: + logger.debug("Failed to read ~/.claude.json: %s", e) + return None + + +def is_claude_code_token_valid(creds: Dict[str, Any]) -> bool: + """Check if Claude Code credentials have a non-expired access token.""" + import time + + expires_at = creds.get("expiresAt", 0) + if not expires_at: + # No expiry set (managed keys) — valid if token is present + return bool(creds.get("accessToken")) + + # expiresAt is in milliseconds since epoch + now_ms = int(time.time() * 1000) + # Allow 60 seconds of buffer + return now_ms < (expires_at - 60_000) + + +def refresh_anthropic_oauth_pure(refresh_token: str, *, use_json: bool = False) -> Dict[str, Any]: + """Refresh an Anthropic OAuth token without mutating local credential files.""" + import time + import urllib.parse + import urllib.request + + if not refresh_token: + raise ValueError("refresh_token is required") + + client_id = "9d1c250a-e61b-44d9-88ed-5944d1962f5e" + if use_json: + data = json.dumps({ + "grant_type": "refresh_token", + "refresh_token": refresh_token, + "client_id": client_id, + }).encode() + content_type = "application/json" + else: + data = urllib.parse.urlencode({ + "grant_type": "refresh_token", + "refresh_token": refresh_token, + "client_id": client_id, + }).encode() + content_type = "application/x-www-form-urlencoded" + + token_endpoints = [ + "https://platform.claude.com/v1/oauth/token", + "https://console.anthropic.com/v1/oauth/token", + ] + last_error = None + for endpoint in token_endpoints: + req = urllib.request.Request( + endpoint, + data=data, + headers={ + "Content-Type": content_type, + "User-Agent": f"claude-cli/{_get_claude_code_version()} (external, cli)", + }, + method="POST", + ) + try: + with urllib.request.urlopen(req, timeout=10) as resp: + result = json.loads(resp.read().decode()) + except Exception as exc: + last_error = exc + logger.debug("Anthropic token refresh failed at %s: %s", endpoint, exc) + continue + + access_token = result.get("access_token", "") + if not access_token: + raise ValueError("Anthropic refresh response was missing access_token") + next_refresh = result.get("refresh_token", refresh_token) + expires_in = result.get("expires_in", 3600) + return { + "access_token": access_token, + "refresh_token": next_refresh, + "expires_at_ms": int(time.time() * 1000) + (expires_in * 1000), + } + + if last_error is not None: + raise last_error + raise ValueError("Anthropic token refresh failed") + + +def _refresh_oauth_token(creds: Dict[str, Any]) -> Optional[str]: + """Attempt to refresh an expired Claude Code OAuth token.""" + refresh_token = creds.get("refreshToken", "") + if not refresh_token: + logger.debug("No refresh token available — cannot refresh") + return None + + try: + refreshed = refresh_anthropic_oauth_pure(refresh_token, use_json=False) + _write_claude_code_credentials( + refreshed["access_token"], + refreshed["refresh_token"], + refreshed["expires_at_ms"], + ) + logger.debug("Successfully refreshed Claude Code OAuth token") + return refreshed["access_token"] + except Exception as e: + logger.debug("Failed to refresh Claude Code token: %s", e) + return None + + +def _write_claude_code_credentials( + access_token: str, + refresh_token: str, + expires_at_ms: int, + *, + scopes: Optional[list] = None, +) -> None: + """Write refreshed credentials back to ~/.claude/.credentials.json. + + The optional *scopes* list (e.g. ``["user:inference", "user:profile", ...]``) + is persisted so that Claude Code's own auth check recognises the credential + as valid. Claude Code >=2.1.81 gates on the presence of ``"user:inference"`` + in the stored scopes before it will use the token. + """ + cred_path = Path.home() / ".claude" / ".credentials.json" + try: + # Read existing file to preserve other fields + existing = {} + if cred_path.exists(): + existing = json.loads(cred_path.read_text(encoding="utf-8")) + + oauth_data: Dict[str, Any] = { + "accessToken": access_token, + "refreshToken": refresh_token, + "expiresAt": expires_at_ms, + } + if scopes is not None: + oauth_data["scopes"] = scopes + elif "claudeAiOauth" in existing and "scopes" in existing["claudeAiOauth"]: + # Preserve previously-stored scopes when the refresh response + # does not include a scope field. + oauth_data["scopes"] = existing["claudeAiOauth"]["scopes"] + + existing["claudeAiOauth"] = oauth_data + + cred_path.parent.mkdir(parents=True, exist_ok=True) + cred_path.write_text(json.dumps(existing, indent=2), encoding="utf-8") + # Restrict permissions (credentials file) + cred_path.chmod(0o600) + except (OSError, IOError) as e: + logger.debug("Failed to write refreshed credentials: %s", e) + + +def _resolve_claude_code_token_from_credentials(creds: Optional[Dict[str, Any]] = None) -> Optional[str]: + """Resolve a token from Claude Code credential files, refreshing if needed.""" + creds = creds or read_claude_code_credentials() + if creds and is_claude_code_token_valid(creds): + logger.debug("Using Claude Code credentials (auto-detected)") + return creds["accessToken"] + if creds: + logger.debug("Claude Code credentials expired — attempting refresh") + refreshed = _refresh_oauth_token(creds) + if refreshed: + return refreshed + logger.debug("Token refresh failed — re-run 'claude setup-token' to reauthenticate") + return None + + +def _prefer_refreshable_claude_code_token(env_token: str, creds: Optional[Dict[str, Any]]) -> Optional[str]: + """Prefer Claude Code creds when a persisted env OAuth token would shadow refresh. + + Hermes historically persisted setup tokens into ANTHROPIC_TOKEN. That makes + later refresh impossible because the static env token wins before we ever + inspect Claude Code's refreshable credential file. If we have a refreshable + Claude Code credential record, prefer it over the static env OAuth token. + """ + if not env_token or not _is_oauth_token(env_token) or not isinstance(creds, dict): + return None + if not creds.get("refreshToken"): + return None + + resolved = _resolve_claude_code_token_from_credentials(creds) + if resolved and resolved != env_token: + logger.debug( + "Preferring Claude Code credential file over static env OAuth token so refresh can proceed" + ) + return resolved + return None + + +def resolve_anthropic_token() -> Optional[str]: + """Resolve an Anthropic token from all available sources. + + Priority: + 1. ANTHROPIC_TOKEN env var (OAuth/setup token saved by Hermes) + 2. CLAUDE_CODE_OAUTH_TOKEN env var + 3. Claude Code credentials (~/.claude.json or ~/.claude/.credentials.json) + — with automatic refresh if expired and a refresh token is available + 4. ANTHROPIC_API_KEY env var (regular API key, or legacy fallback) + + Returns the token string or None. + """ + creds = read_claude_code_credentials() + + # 1. Hermes-managed OAuth/setup token env var + token = os.getenv("ANTHROPIC_TOKEN", "").strip() + if token: + preferred = _prefer_refreshable_claude_code_token(token, creds) + if preferred: + return preferred + return token + + # 2. CLAUDE_CODE_OAUTH_TOKEN (used by Claude Code for setup-tokens) + cc_token = os.getenv("CLAUDE_CODE_OAUTH_TOKEN", "").strip() + if cc_token: + preferred = _prefer_refreshable_claude_code_token(cc_token, creds) + if preferred: + return preferred + return cc_token + + # 3. Claude Code credential file + resolved_claude_token = _resolve_claude_code_token_from_credentials(creds) + if resolved_claude_token: + return resolved_claude_token + + # 4. Regular API key, or a legacy OAuth token saved in ANTHROPIC_API_KEY. + # This remains as a compatibility fallback for pre-migration Hermes configs. + api_key = os.getenv("ANTHROPIC_API_KEY", "").strip() + if api_key: + return api_key + + return None + + +def run_oauth_setup_token() -> Optional[str]: + """Run 'claude setup-token' interactively and return the resulting token. + + Checks multiple sources after the subprocess completes: + 1. Claude Code credential files (may be written by the subprocess) + 2. CLAUDE_CODE_OAUTH_TOKEN / ANTHROPIC_TOKEN env vars + + Returns the token string, or None if no credentials were obtained. + Raises FileNotFoundError if the 'claude' CLI is not installed. + """ + import shutil + import subprocess + + claude_path = shutil.which("claude") + if not claude_path: + raise FileNotFoundError( + "The 'claude' CLI is not installed. " + "Install it with: npm install -g @anthropic-ai/claude-code" + ) + + # Run interactively — stdin/stdout/stderr inherited so user can interact + try: + subprocess.run([claude_path, "setup-token"]) + except (KeyboardInterrupt, EOFError): + return None + + # Check if credentials were saved to Claude Code's config files + creds = read_claude_code_credentials() + if creds and is_claude_code_token_valid(creds): + return creds["accessToken"] + + # Check env vars that may have been set + for env_var in ("CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_TOKEN"): + val = os.getenv(env_var, "").strip() + if val: + return val + + return None + + +# ── Hermes-native PKCE OAuth flow ──────────────────────────────────────── +# Mirrors the flow used by Claude Code, pi-ai, and OpenCode. +# Stores credentials in ~/.hermes/.anthropic_oauth.json (our own file). + +_OAUTH_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e" +_OAUTH_TOKEN_URL = "https://console.anthropic.com/v1/oauth/token" +_OAUTH_REDIRECT_URI = "https://console.anthropic.com/oauth/code/callback" +_OAUTH_SCOPES = "org:create_api_key user:profile user:inference" +_HERMES_OAUTH_FILE = get_hermes_home() / ".anthropic_oauth.json" + + +def _generate_pkce() -> tuple: + """Generate PKCE code_verifier and code_challenge (S256).""" + import base64 + import hashlib + import secrets + + verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode() + challenge = base64.urlsafe_b64encode( + hashlib.sha256(verifier.encode()).digest() + ).rstrip(b"=").decode() + return verifier, challenge + + +def run_hermes_oauth_login_pure() -> Optional[Dict[str, Any]]: + """Run Hermes-native OAuth PKCE flow and return credential state.""" + import time + import webbrowser + + verifier, challenge = _generate_pkce() + + params = { + "code": "true", + "client_id": _OAUTH_CLIENT_ID, + "response_type": "code", + "redirect_uri": _OAUTH_REDIRECT_URI, + "scope": _OAUTH_SCOPES, + "code_challenge": challenge, + "code_challenge_method": "S256", + "state": verifier, + } + from urllib.parse import urlencode + + auth_url = f"https://claude.ai/oauth/authorize?{urlencode(params)}" + + print() + print("Authorize Hermes with your Claude Pro/Max subscription.") + print() + print("╭─ Claude Pro/Max Authorization ────────────────────╮") + print("│ │") + print("│ Open this link in your browser: │") + print("╰───────────────────────────────────────────────────╯") + print() + print(f" {auth_url}") + print() + + try: + webbrowser.open(auth_url) + print(" (Browser opened automatically)") + except Exception: + pass + + print() + print("After authorizing, you'll see a code. Paste it below.") + print() + try: + auth_code = input("Authorization code: ").strip() + except (KeyboardInterrupt, EOFError): + return None + + if not auth_code: + print("No code entered.") + return None + + splits = auth_code.split("#") + code = splits[0] + state = splits[1] if len(splits) > 1 else "" + + try: + import urllib.request + + exchange_data = json.dumps({ + "grant_type": "authorization_code", + "client_id": _OAUTH_CLIENT_ID, + "code": code, + "state": state, + "redirect_uri": _OAUTH_REDIRECT_URI, + "code_verifier": verifier, + }).encode() + + req = urllib.request.Request( + _OAUTH_TOKEN_URL, + data=exchange_data, + headers={ + "Content-Type": "application/json", + "User-Agent": f"claude-cli/{_get_claude_code_version()} (external, cli)", + }, + method="POST", + ) + + with urllib.request.urlopen(req, timeout=15) as resp: + result = json.loads(resp.read().decode()) + except Exception as e: + print(f"Token exchange failed: {e}") + return None + + access_token = result.get("access_token", "") + refresh_token = result.get("refresh_token", "") + expires_in = result.get("expires_in", 3600) + + if not access_token: + print("No access token in response.") + return None + + expires_at_ms = int(time.time() * 1000) + (expires_in * 1000) + return { + "access_token": access_token, + "refresh_token": refresh_token, + "expires_at_ms": expires_at_ms, + } + + +def read_hermes_oauth_credentials() -> Optional[Dict[str, Any]]: + """Read Hermes-managed OAuth credentials from ~/.hermes/.anthropic_oauth.json.""" + if _HERMES_OAUTH_FILE.exists(): + try: + data = json.loads(_HERMES_OAUTH_FILE.read_text(encoding="utf-8")) + if data.get("accessToken"): + return data + except (json.JSONDecodeError, OSError, IOError) as e: + logger.debug("Failed to read Hermes OAuth credentials: %s", e) + return None + + +# --------------------------------------------------------------------------- +# Message / tool / response format conversion +# --------------------------------------------------------------------------- + + +def normalize_model_name(model: str, preserve_dots: bool = False) -> str: + """Normalize a model name for the Anthropic API. + + - Strips 'anthropic/' prefix (OpenRouter format, case-insensitive) + - Converts dots to hyphens in version numbers (OpenRouter uses dots, + Anthropic uses hyphens: claude-opus-4.6 → claude-opus-4-6), unless + preserve_dots is True (e.g. for Alibaba/DashScope: qwen3.5-plus). + """ + lower = model.lower() + if lower.startswith("anthropic/"): + model = model[len("anthropic/"):] + if not preserve_dots: + # OpenRouter uses dots for version separators (claude-opus-4.6), + # Anthropic uses hyphens (claude-opus-4-6). Convert dots to hyphens. + model = model.replace(".", "-") + return model + + +def _sanitize_tool_id(tool_id: str) -> str: + """Sanitize a tool call ID for the Anthropic API. + + Anthropic requires IDs matching [a-zA-Z0-9_-]. Replace invalid + characters with underscores and ensure non-empty. + """ + import re + if not tool_id: + return "tool_0" + sanitized = re.sub(r"[^a-zA-Z0-9_-]", "_", tool_id) + return sanitized or "tool_0" + + +def convert_tools_to_anthropic(tools: List[Dict]) -> List[Dict]: + """Convert OpenAI tool definitions to Anthropic format.""" + if not tools: + return [] + result = [] + for t in tools: + fn = t.get("function", {}) + result.append({ + "name": fn.get("name", ""), + "description": fn.get("description", ""), + "input_schema": fn.get("parameters", {"type": "object", "properties": {}}), + }) + return result + + +def _image_source_from_openai_url(url: str) -> Dict[str, str]: + """Convert an OpenAI-style image URL/data URL into Anthropic image source.""" + url = str(url or "").strip() + if not url: + return {"type": "url", "url": ""} + + if url.startswith("data:"): + header, _, data = url.partition(",") + media_type = "image/jpeg" + if header.startswith("data:"): + mime_part = header[len("data:"):].split(";", 1)[0].strip() + if mime_part.startswith("image/"): + media_type = mime_part + return { + "type": "base64", + "media_type": media_type, + "data": data, + } + + return {"type": "url", "url": url} + + +def _convert_content_part_to_anthropic(part: Any) -> Optional[Dict[str, Any]]: + """Convert a single OpenAI-style content part to Anthropic format.""" + if part is None: + return None + if isinstance(part, str): + return {"type": "text", "text": part} + if not isinstance(part, dict): + return {"type": "text", "text": str(part)} + + ptype = part.get("type") + + if ptype == "input_text": + block: Dict[str, Any] = {"type": "text", "text": part.get("text", "")} + elif ptype in {"image_url", "input_image"}: + image_value = part.get("image_url", {}) + url = image_value.get("url", "") if isinstance(image_value, dict) else str(image_value or "") + block = {"type": "image", "source": _image_source_from_openai_url(url)} + else: + block = dict(part) + + if isinstance(part.get("cache_control"), dict) and "cache_control" not in block: + block["cache_control"] = dict(part["cache_control"]) + return block + + +def _to_plain_data(value: Any, *, _depth: int = 0, _path: Optional[set] = None) -> Any: + """Recursively convert SDK objects to plain Python data structures. + + Guards against circular references (``_path`` tracks ``id()`` of objects + on the *current* recursion path) and runaway depth (capped at 20 levels). + Uses path-based tracking so shared (but non-cyclic) objects referenced by + multiple siblings are converted correctly rather than being stringified. + """ + _MAX_DEPTH = 20 + if _depth > _MAX_DEPTH: + return str(value) + + if _path is None: + _path = set() + + obj_id = id(value) + if obj_id in _path: + return str(value) + + if hasattr(value, "model_dump"): + _path.add(obj_id) + result = _to_plain_data(value.model_dump(), _depth=_depth + 1, _path=_path) + _path.discard(obj_id) + return result + if isinstance(value, dict): + _path.add(obj_id) + result = {k: _to_plain_data(v, _depth=_depth + 1, _path=_path) for k, v in value.items()} + _path.discard(obj_id) + return result + if isinstance(value, (list, tuple)): + _path.add(obj_id) + result = [_to_plain_data(v, _depth=_depth + 1, _path=_path) for v in value] + _path.discard(obj_id) + return result + if hasattr(value, "__dict__"): + _path.add(obj_id) + result = { + k: _to_plain_data(v, _depth=_depth + 1, _path=_path) + for k, v in vars(value).items() + if not k.startswith("_") + } + _path.discard(obj_id) + return result + return value + + +def _extract_preserved_thinking_blocks(message: Dict[str, Any]) -> List[Dict[str, Any]]: + """Return Anthropic thinking blocks previously preserved on the message.""" + raw_details = message.get("reasoning_details") + if not isinstance(raw_details, list): + return [] + + preserved: List[Dict[str, Any]] = [] + for detail in raw_details: + if not isinstance(detail, dict): + continue + block_type = str(detail.get("type", "") or "").strip().lower() + if block_type not in {"thinking", "redacted_thinking"}: + continue + preserved.append(copy.deepcopy(detail)) + return preserved + + +def _convert_content_to_anthropic(content: Any) -> Any: + """Convert OpenAI-style multimodal content arrays to Anthropic blocks.""" + if not isinstance(content, list): + return content + + converted = [] + for part in content: + block = _convert_content_part_to_anthropic(part) + if block is not None: + converted.append(block) + return converted + + +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 = [] + + for m in messages: + role = m.get("role", "user") + content = m.get("content", "") + + if role == "system": + if isinstance(content, list): + # Preserve cache_control markers on content blocks + has_cache = any( + p.get("cache_control") for p in content if isinstance(p, dict) + ) + if has_cache: + system = [p for p in content if isinstance(p, dict)] + else: + system = "\n".join( + p["text"] for p in content if p.get("type") == "text" + ) + else: + system = content + continue + + if role == "assistant": + blocks = _extract_preserved_thinking_blocks(m) + if content: + if isinstance(content, list): + converted_content = _convert_content_to_anthropic(content) + if isinstance(converted_content, list): + blocks.extend(converted_content) + else: + blocks.append({"type": "text", "text": str(content)}) + for tc in m.get("tool_calls", []): + if not tc or not isinstance(tc, dict): + continue + fn = tc.get("function", {}) + args = fn.get("arguments", "{}") + try: + parsed_args = json.loads(args) if isinstance(args, str) else args + except (json.JSONDecodeError, ValueError): + parsed_args = {} + blocks.append({ + "type": "tool_use", + "id": _sanitize_tool_id(tc.get("id", "")), + "name": fn.get("name", ""), + "input": parsed_args, + }) + # Anthropic rejects empty assistant content + effective = blocks or content + if not effective or effective == "": + effective = [{"type": "text", "text": "(empty)"}] + result.append({"role": "assistant", "content": effective}) + continue + + if role == "tool": + # Sanitize tool_use_id and ensure non-empty content + result_content = content if isinstance(content, str) else json.dumps(content) + if not result_content: + result_content = "(no output)" + tool_result = { + "type": "tool_result", + "tool_use_id": _sanitize_tool_id(m.get("tool_call_id", "")), + "content": result_content, + } + if isinstance(m.get("cache_control"), dict): + tool_result["cache_control"] = dict(m["cache_control"]) + # Merge consecutive tool results into one user message + if ( + result + and result[-1]["role"] == "user" + and isinstance(result[-1]["content"], list) + and result[-1]["content"] + and result[-1]["content"][0].get("type") == "tool_result" + ): + result[-1]["content"].append(tool_result) + else: + result.append({"role": "user", "content": [tool_result]}) + continue + + # Regular user message — validate non-empty content (Anthropic rejects empty) + if isinstance(content, list): + converted_blocks = _convert_content_to_anthropic(content) + # Check if all text blocks are empty + if not converted_blocks or all( + b.get("text", "").strip() == "" + for b in converted_blocks + if isinstance(b, dict) and b.get("type") == "text" + ): + converted_blocks = [{"type": "text", "text": "(empty message)"}] + result.append({"role": "user", "content": converted_blocks}) + else: + # Validate string content is non-empty + if not content or (isinstance(content, str) and not content.strip()): + content = "(empty message)" + result.append({"role": "user", "content": content}) + + # Strip orphaned tool_use blocks (no matching tool_result follows) + tool_result_ids = set() + for m in result: + if m["role"] == "user" and isinstance(m["content"], list): + for block in m["content"]: + if block.get("type") == "tool_result": + tool_result_ids.add(block.get("tool_use_id")) + for m in result: + if m["role"] == "assistant" and isinstance(m["content"], list): + m["content"] = [ + b + for b in m["content"] + if b.get("type") != "tool_use" or b.get("id") in tool_result_ids + ] + if not m["content"]: + m["content"] = [{"type": "text", "text": "(tool call removed)"}] + + # Strip orphaned tool_result blocks (no matching tool_use precedes them). + # This is the mirror of the above: context compression or session truncation + # can remove an assistant message containing a tool_use while leaving the + # subsequent tool_result intact. Anthropic rejects these with a 400. + tool_use_ids = set() + for m in result: + if m["role"] == "assistant" and isinstance(m["content"], list): + for block in m["content"]: + if block.get("type") == "tool_use": + tool_use_ids.add(block.get("id")) + for m in result: + if m["role"] == "user" and isinstance(m["content"], list): + m["content"] = [ + b + for b in m["content"] + if b.get("type") != "tool_result" or b.get("tool_use_id") in tool_use_ids + ] + if not m["content"]: + m["content"] = [{"type": "text", "text": "(tool result removed)"}] + + # Enforce strict role alternation (Anthropic rejects consecutive same-role messages) + fixed = [] + for m in result: + if fixed and fixed[-1]["role"] == m["role"]: + if m["role"] == "user": + # Merge consecutive user messages + prev_content = fixed[-1]["content"] + curr_content = m["content"] + if isinstance(prev_content, str) and isinstance(curr_content, str): + fixed[-1]["content"] = prev_content + "\n" + curr_content + elif isinstance(prev_content, list) and isinstance(curr_content, list): + fixed[-1]["content"] = prev_content + curr_content + else: + # Mixed types — wrap string in list + if isinstance(prev_content, str): + prev_content = [{"type": "text", "text": prev_content}] + if isinstance(curr_content, str): + curr_content = [{"type": "text", "text": curr_content}] + fixed[-1]["content"] = prev_content + curr_content + else: + # 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): + fixed[-1]["content"] = prev_blocks + curr_blocks + elif isinstance(prev_blocks, str) and isinstance(curr_blocks, str): + fixed[-1]["content"] = prev_blocks + "\n" + curr_blocks + else: + # Mixed types — normalize both to list and merge + if isinstance(prev_blocks, str): + prev_blocks = [{"type": "text", "text": prev_blocks}] + if isinstance(curr_blocks, str): + curr_blocks = [{"type": "text", "text": curr_blocks}] + fixed[-1]["content"] = prev_blocks + curr_blocks + else: + 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 + + +def build_anthropic_kwargs( + model: str, + messages: List[Dict], + tools: Optional[List[Dict]], + max_tokens: Optional[int], + reasoning_config: Optional[Dict[str, Any]], + tool_choice: Optional[str] = None, + is_oauth: bool = False, + preserve_dots: bool = False, + context_length: Optional[int] = None, + base_url: str | None = None, + fast_mode: bool = False, +) -> Dict[str, Any]: + """Build kwargs for anthropic.messages.create(). + + Naming note — two distinct concepts, easily confused: + max_tokens = OUTPUT token cap for a single response. + Anthropic's API calls this "max_tokens" but it only + limits the *output*. Anthropic's own native SDK + renamed it "max_output_tokens" for clarity. + context_length = TOTAL context window (input tokens + output tokens). + The API enforces: input_tokens + max_tokens ≤ context_length. + Stored on the ContextCompressor; reduced on overflow errors. + + When *max_tokens* is None the model's native output ceiling is used + (e.g. 128K for Opus 4.6, 64K for Sonnet 4.6). + + When *context_length* is provided and the model's native output ceiling + exceeds it (e.g. a local endpoint with an 8K window), the output cap is + clamped to context_length − 1. This only kicks in for unusually small + context windows; for full-size models the native output cap is always + smaller than the context window so no clamping happens. + NOTE: this clamping does not account for prompt size — if the prompt is + large, Anthropic may still reject the request. The caller must detect + "max_tokens too large given prompt" errors and retry with a smaller cap + (see parse_available_output_tokens_from_error + _ephemeral_max_output_tokens). + + When *is_oauth* is True, applies Claude Code compatibility transforms: + system prompt prefix, tool name prefixing, and prompt sanitization. + + When *preserve_dots* is True, model name dots are not converted to hyphens + (for Alibaba/DashScope anthropic-compatible endpoints: qwen3.5-plus). + + When *base_url* points to a third-party Anthropic-compatible endpoint, + thinking block signatures are stripped (they are Anthropic-proprietary). + + When *fast_mode* is True, adds ``extra_body["speed"] = "fast"`` and the + fast-mode beta header for ~2.5x faster output throughput on Opus 4.6. + Currently only supported on native Anthropic endpoints (not third-party + compatible ones). + """ + system, anthropic_messages = convert_messages_to_anthropic(messages, base_url=base_url) + anthropic_tools = convert_tools_to_anthropic(tools) if tools else [] + + model = normalize_model_name(model, preserve_dots=preserve_dots) + # effective_max_tokens = output cap for this call (≠ total context window) + effective_max_tokens = max_tokens or _get_anthropic_max_output(model) + + # Clamp output cap to fit inside the total context window. + # Only matters for small custom endpoints where context_length < native + # output ceiling. For standard Anthropic models context_length (e.g. + # 200K) is always larger than the output ceiling (e.g. 128K), so this + # branch is not taken. + if context_length and effective_max_tokens > context_length: + effective_max_tokens = max(context_length - 1, 1) + + # ── OAuth: Claude Code identity ────────────────────────────────── + if is_oauth: + # 1. Prepend Claude Code system prompt identity + cc_block = {"type": "text", "text": _CLAUDE_CODE_SYSTEM_PREFIX} + if isinstance(system, list): + system = [cc_block] + system + elif isinstance(system, str) and system: + system = [cc_block, {"type": "text", "text": system}] + else: + system = [cc_block] + + # 2. Sanitize system prompt — replace product name references + # to avoid Anthropic's server-side content filters. + for block in system: + if isinstance(block, dict) and block.get("type") == "text": + text = block.get("text", "") + text = text.replace("Hermes Agent", "Claude Code") + text = text.replace("Hermes agent", "Claude Code") + text = text.replace("hermes-agent", "claude-code") + text = text.replace("Nous Research", "Anthropic") + block["text"] = text + + # 3. Prefix tool names with mcp_ (Claude Code convention) + if anthropic_tools: + for tool in anthropic_tools: + if "name" in tool: + tool["name"] = _MCP_TOOL_PREFIX + tool["name"] + + # 4. Prefix tool names in message history (tool_use and tool_result blocks) + for msg in anthropic_messages: + content = msg.get("content") + if isinstance(content, list): + for block in content: + if isinstance(block, dict): + if block.get("type") == "tool_use" and "name" in block: + if not block["name"].startswith(_MCP_TOOL_PREFIX): + block["name"] = _MCP_TOOL_PREFIX + block["name"] + elif block.get("type") == "tool_result" and "tool_use_id" in block: + pass # tool_result uses ID, not name + + kwargs: Dict[str, Any] = { + "model": model, + "messages": anthropic_messages, + "max_tokens": effective_max_tokens, + } + + if system: + kwargs["system"] = system + + if anthropic_tools: + kwargs["tools"] = anthropic_tools + # Map OpenAI tool_choice to Anthropic format + if tool_choice == "auto" or tool_choice is None: + kwargs["tool_choice"] = {"type": "auto"} + elif tool_choice == "required": + kwargs["tool_choice"] = {"type": "any"} + elif tool_choice == "none": + # Anthropic has no tool_choice "none" — omit tools entirely to prevent use + kwargs.pop("tools", None) + elif isinstance(tool_choice, str): + # Specific tool name + kwargs["tool_choice"] = {"type": "tool", "name": tool_choice} + + # 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. + # MiniMax Anthropic-compat endpoints support thinking (manual mode only, + # not adaptive). Haiku does NOT support extended thinking — skip entirely. + if reasoning_config and isinstance(reasoning_config, dict): + if reasoning_config.get("enabled") is not False and "haiku" not in model.lower(): + effort = str(reasoning_config.get("effort", "medium")).lower() + budget = THINKING_BUDGET.get(effort, 8000) + if _supports_adaptive_thinking(model): + kwargs["thinking"] = {"type": "adaptive"} + kwargs["output_config"] = { + "effort": ADAPTIVE_EFFORT_MAP.get(effort, "medium") + } + else: + kwargs["thinking"] = {"type": "enabled", "budget_tokens": budget} + # Anthropic requires temperature=1 when thinking is enabled on older models + kwargs["temperature"] = 1 + kwargs["max_tokens"] = max(effective_max_tokens, budget + 4096) + + # ── Fast mode (Opus 4.6 only) ──────────────────────────────────── + # Adds extra_body.speed="fast" + the fast-mode beta header for ~2.5x + # output speed. Only for native Anthropic endpoints — third-party + # providers would reject the unknown beta header and speed parameter. + if fast_mode and not _is_third_party_anthropic_endpoint(base_url): + kwargs.setdefault("extra_body", {})["speed"] = "fast" + # Build extra_headers with ALL applicable betas (the per-request + # extra_headers override the client-level anthropic-beta header). + betas = list(_common_betas_for_base_url(base_url)) + if is_oauth: + betas.extend(_OAUTH_ONLY_BETAS) + betas.append(_FAST_MODE_BETA) + kwargs["extra_headers"] = {"anthropic-beta": ",".join(betas)} + + return kwargs + + +def normalize_anthropic_response( + response, + strip_tool_prefix: bool = False, +) -> Tuple[SimpleNamespace, str]: + """Normalize Anthropic response to match the shape expected by AIAgent. + + Returns (assistant_message, finish_reason) where assistant_message has + .content, .tool_calls, and .reasoning attributes. + + When *strip_tool_prefix* is True, removes the ``mcp_`` prefix that was + added to tool names for OAuth Claude Code compatibility. + """ + text_parts = [] + reasoning_parts = [] + reasoning_details = [] + tool_calls = [] + + for block in response.content: + if block.type == "text": + text_parts.append(block.text) + elif block.type == "thinking": + reasoning_parts.append(block.thinking) + block_dict = _to_plain_data(block) + if isinstance(block_dict, dict): + reasoning_details.append(block_dict) + elif block.type == "tool_use": + name = block.name + if strip_tool_prefix and name.startswith(_MCP_TOOL_PREFIX): + name = name[len(_MCP_TOOL_PREFIX):] + tool_calls.append( + SimpleNamespace( + id=block.id, + type="function", + function=SimpleNamespace( + name=name, + arguments=json.dumps(block.input), + ), + ) + ) + + # Map Anthropic stop_reason to OpenAI finish_reason + stop_reason_map = { + "end_turn": "stop", + "tool_use": "tool_calls", + "max_tokens": "length", + "stop_sequence": "stop", + } + finish_reason = stop_reason_map.get(response.stop_reason, "stop") + + return ( + SimpleNamespace( + content="\n".join(text_parts) if text_parts else None, + tool_calls=tool_calls or None, + reasoning="\n\n".join(reasoning_parts) if reasoning_parts else None, + reasoning_content=None, + reasoning_details=reasoning_details or None, + ), + finish_reason, + ) diff --git a/mindcli/_vendor/agent/auxiliary_client.py b/mindcli/_vendor/agent/auxiliary_client.py new file mode 100644 index 0000000..49dea65 --- /dev/null +++ b/mindcli/_vendor/agent/auxiliary_client.py @@ -0,0 +1,2614 @@ +"""Shared auxiliary client router for side tasks. + +Provides a single resolution chain so every consumer (context compression, +session search, web extraction, vision analysis, browser vision) picks up +the best available backend without duplicating fallback logic. + +Resolution order for text tasks (auto mode): + 1. OpenRouter (OPENROUTER_API_KEY) + 2. Nous Portal (~/.hermes/auth.json active provider) + 3. Custom endpoint (config.yaml model.base_url + OPENAI_API_KEY) + 4. Codex OAuth (Responses API via chatgpt.com with gpt-5.3-codex, + wrapped to look like a chat.completions client) + 5. Native Anthropic + 6. Direct API-key providers (z.ai/GLM, Kimi/Moonshot, MiniMax, MiniMax-CN) + 7. None + +Resolution order for vision/multimodal tasks (auto mode): + 1. Selected main provider, if it is one of the supported vision backends below + 2. OpenRouter + 3. Nous Portal + 4. Codex OAuth (gpt-5.3-codex supports vision via Responses API) + 5. Native Anthropic + 6. Custom endpoint (for local vision models: Qwen-VL, LLaVA, Pixtral, etc.) + 7. None + +Per-task overrides are configured in config.yaml under the ``auxiliary:`` section +(e.g. ``auxiliary.vision.provider``, ``auxiliary.compression.model``). +Default "auto" follows the chains above. + +Payment / credit exhaustion fallback: + When a resolved provider returns HTTP 402 or a credit-related error, + call_llm() automatically retries with the next available provider in the + auto-detection chain. This handles the common case where a user depletes + their OpenRouter balance but has Codex OAuth or another provider available. +""" + +import json +import logging +import os +import threading +import time +from pathlib import Path # noqa: F401 — used by test mocks +from types import SimpleNamespace +from typing import Any, Dict, List, Optional, Tuple + +from openai import OpenAI + +from agent.credential_pool import load_pool +from hermes_cli.config import get_hermes_home +from hermes_constants import OPENROUTER_BASE_URL + +logger = logging.getLogger(__name__) + +# Module-level flag: only warn once per process about stale OPENAI_BASE_URL. +_stale_base_url_warned = False + +_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", + "kimi-cn": "kimi-coding-cn", + "moonshot-cn": "kimi-coding-cn", + "minimax-china": "minimax-cn", + "minimax_cn": "minimax-cn", + "claude": "anthropic", + "claude-code": "anthropic", +} + + +def _normalize_aux_provider(provider: Optional[str]) -> 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 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", + "kimi-coding-cn": "kimi-k2-turbo-preview", + "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", + "opencode-go": "glm-5", + "kilocode": "google/gemini-3-flash-preview", +} + +# Vision-specific model overrides for direct providers. +# When the user's main provider has a dedicated vision/multimodal model that +# differs from their main chat model, map it here. The vision auto-detect +# "exotic provider" branch checks this before falling back to the main model. +_PROVIDER_VISION_MODELS: Dict[str, str] = { + "xiaomi": "mimo-v2-omni", +} + +# OpenRouter app attribution headers +_OR_HEADERS = { + "HTTP-Referer": "https://hermes-agent.nousresearch.com", + "X-OpenRouter-Title": "Hermes Agent", + "X-OpenRouter-Categories": "productivity,cli-agent", +} + +# Nous Portal extra_body for product attribution. +# Callers should pass this as extra_body in chat.completions.create() +# when the auxiliary client is backed by Nous Portal. +NOUS_EXTRA_BODY = {"tags": ["product=hermes-agent"]} + +# Set at resolve time — True if the auxiliary client points to Nous Portal +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" + +# Codex fallback: uses the Responses API (the only endpoint the Codex +# OAuth token can access) with a fast model for auxiliary tasks. +# ChatGPT-backed Codex accounts currently reject gpt-5.3-codex for these +# auxiliary flows, while gpt-5.2-codex remains broadly available and supports +# vision via Responses. +_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: + pool = load_pool(provider) + except Exception as exc: + logger.debug("Auxiliary client: could not load pool for %s: %s", provider, exc) + return False, None + if not pool or not pool.has_credentials(): + return False, None + try: + return True, pool.select() + except Exception as exc: + logger.debug("Auxiliary client: could not select pool entry for %s: %s", provider, exc) + return True, None + + +def _pool_runtime_api_key(entry: Any) -> str: + if entry is None: + return "" + # Use the PooledCredential.runtime_api_key property which handles + # provider-specific fallback (e.g. agent_key for nous). + key = getattr(entry, "runtime_api_key", None) or getattr(entry, "access_token", "") + return str(key or "").strip() + + +def _pool_runtime_base_url(entry: Any, fallback: str = "") -> str: + if entry is None: + return str(fallback or "").strip().rstrip("/") + # runtime_base_url handles provider-specific logic (e.g. nous prefers inference_base_url). + # Fall back through inference_base_url and base_url for non-PooledCredential entries. + url = ( + getattr(entry, "runtime_base_url", None) + or getattr(entry, "inference_base_url", None) + or getattr(entry, "base_url", None) + or fallback + ) + return str(url or "").strip().rstrip("/") + + +# ── Codex Responses → chat.completions adapter ───────────────────────────── +# All auxiliary consumers call client.chat.completions.create(**kwargs) and +# read response.choices[0].message.content. This adapter translates those +# calls to the Codex Responses API so callers don't need any changes. + + +def _convert_content_for_responses(content: Any) -> Any: + """Convert chat.completions content to Responses API format. + + chat.completions uses: + {"type": "text", "text": "..."} + {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}} + + Responses API uses: + {"type": "input_text", "text": "..."} + {"type": "input_image", "image_url": "data:image/png;base64,..."} + + If content is a plain string, it's returned as-is (the Responses API + accepts strings directly for text-only messages). + """ + if isinstance(content, str): + return content + if not isinstance(content, list): + return str(content) if content else "" + + converted: List[Dict[str, Any]] = [] + for part in content: + if not isinstance(part, dict): + continue + ptype = part.get("type", "") + if ptype == "text": + converted.append({"type": "input_text", "text": part.get("text", "")}) + elif ptype == "image_url": + # chat.completions nests the URL: {"image_url": {"url": "..."}} + image_data = part.get("image_url", {}) + url = image_data.get("url", "") if isinstance(image_data, dict) else str(image_data) + entry: Dict[str, Any] = {"type": "input_image", "image_url": url} + # Preserve detail if specified + detail = image_data.get("detail") if isinstance(image_data, dict) else None + if detail: + entry["detail"] = detail + converted.append(entry) + elif ptype in ("input_text", "input_image"): + # Already in Responses format — pass through + converted.append(part) + else: + # Unknown content type — try to preserve as text + text = part.get("text", "") + if text: + converted.append({"type": "input_text", "text": text}) + + return converted or "" + + +class _CodexCompletionsAdapter: + """Drop-in shim that accepts chat.completions.create() kwargs and + routes them through the Codex Responses streaming API.""" + + def __init__(self, real_client: OpenAI, model: str): + self._client = real_client + self._model = model + + def create(self, **kwargs) -> Any: + messages = kwargs.get("messages", []) + model = kwargs.get("model", self._model) + + # Separate system/instructions from conversation messages. + # Convert chat.completions multimodal content blocks to Responses + # API format (input_text / input_image instead of text / image_url). + instructions = "You are a helpful assistant." + input_msgs: List[Dict[str, Any]] = [] + for msg in messages: + role = msg.get("role", "user") + content = msg.get("content") or "" + if role == "system": + instructions = content if isinstance(content, str) else str(content) + else: + input_msgs.append({ + "role": role, + "content": _convert_content_for_responses(content), + }) + + resp_kwargs: Dict[str, Any] = { + "model": model, + "instructions": instructions, + "input": input_msgs or [{"role": "user", "content": ""}], + "store": False, + } + + # Note: the Codex endpoint (chatgpt.com/backend-api/codex) does NOT + # support max_output_tokens or temperature — omit to avoid 400 errors. + + # Tools support for flush_memories and similar callers + tools = kwargs.get("tools") + if tools: + converted = [] + for t in tools: + fn = t.get("function", {}) if isinstance(t, dict) else {} + name = fn.get("name") + if not name: + continue + converted.append({ + "type": "function", + "name": name, + "description": fn.get("description", ""), + "parameters": fn.get("parameters", {}), + }) + if converted: + resp_kwargs["tools"] = converted + + # Stream and collect the response + text_parts: List[str] = [] + tool_calls_raw: List[Any] = [] + usage = None + + try: + # Collect output items and text deltas during streaming — + # the Codex backend can return empty response.output from + # get_final_response() even when items were streamed. + collected_output_items: List[Any] = [] + collected_text_deltas: List[str] = [] + has_function_calls = False + with self._client.responses.stream(**resp_kwargs) as stream: + for _event in stream: + _etype = getattr(_event, "type", "") + if _etype == "response.output_item.done": + _done = getattr(_event, "item", None) + if _done is not None: + collected_output_items.append(_done) + elif "output_text.delta" in _etype: + _delta = getattr(_event, "delta", "") + if _delta: + collected_text_deltas.append(_delta) + elif "function_call" in _etype: + has_function_calls = True + final = stream.get_final_response() + + # Backfill empty output from collected stream events + _output = getattr(final, "output", None) + if isinstance(_output, list) and not _output: + if collected_output_items: + final.output = list(collected_output_items) + logger.debug( + "Codex auxiliary: backfilled %d output items from stream events", + len(collected_output_items), + ) + elif collected_text_deltas and not has_function_calls: + # Only synthesize text when no tool calls were streamed — + # a function_call response with incidental text should not + # be collapsed into a plain-text message. + assembled = "".join(collected_text_deltas) + final.output = [SimpleNamespace( + type="message", role="assistant", status="completed", + content=[SimpleNamespace(type="output_text", text=assembled)], + )] + logger.debug( + "Codex auxiliary: synthesized from %d deltas (%d chars)", + len(collected_text_deltas), len(assembled), + ) + + # Extract text and tool calls from the Responses output. + # Items may be SDK objects (attrs) or dicts (raw/fallback paths), + # so use a helper that handles both shapes. + def _item_get(obj: Any, key: str, default: Any = None) -> Any: + val = getattr(obj, key, None) + if val is None and isinstance(obj, dict): + val = obj.get(key, default) + return val if val is not None else default + + for item in getattr(final, "output", []): + item_type = _item_get(item, "type") + if item_type == "message": + for part in (_item_get(item, "content") or []): + ptype = _item_get(part, "type") + if ptype in ("output_text", "text"): + text_parts.append(_item_get(part, "text", "")) + elif item_type == "function_call": + tool_calls_raw.append(SimpleNamespace( + id=_item_get(item, "call_id", ""), + type="function", + function=SimpleNamespace( + name=_item_get(item, "name", ""), + arguments=_item_get(item, "arguments", "{}"), + ), + )) + + resp_usage = getattr(final, "usage", None) + if resp_usage: + usage = SimpleNamespace( + prompt_tokens=getattr(resp_usage, "input_tokens", 0), + completion_tokens=getattr(resp_usage, "output_tokens", 0), + total_tokens=getattr(resp_usage, "total_tokens", 0), + ) + except Exception as exc: + logger.debug("Codex auxiliary Responses API call failed: %s", exc) + raise + + content = "".join(text_parts).strip() or None + + # Build a response that looks like chat.completions + message = SimpleNamespace( + role="assistant", + content=content, + tool_calls=tool_calls_raw or None, + ) + choice = SimpleNamespace( + index=0, + message=message, + finish_reason="stop" if not tool_calls_raw else "tool_calls", + ) + return SimpleNamespace( + choices=[choice], + model=model, + usage=usage, + ) + + +class _CodexChatShim: + """Wraps the adapter to provide client.chat.completions.create().""" + + def __init__(self, adapter: _CodexCompletionsAdapter): + self.completions = adapter + + +class CodexAuxiliaryClient: + """OpenAI-client-compatible wrapper that routes through Codex Responses API. + + Consumers can call client.chat.completions.create(**kwargs) as normal. + Also exposes .api_key and .base_url for introspection by async wrappers. + """ + + def __init__(self, real_client: OpenAI, model: str): + self._real_client = real_client + adapter = _CodexCompletionsAdapter(real_client, model) + self.chat = _CodexChatShim(adapter) + self.api_key = real_client.api_key + self.base_url = real_client.base_url + + def close(self): + self._real_client.close() + + +class _AsyncCodexCompletionsAdapter: + """Async version of the Codex Responses adapter. + + Wraps the sync adapter via asyncio.to_thread() so async consumers + (web_tools, session_search) can await it as normal. + """ + + def __init__(self, sync_adapter: _CodexCompletionsAdapter): + self._sync = sync_adapter + + async def create(self, **kwargs) -> Any: + import asyncio + return await asyncio.to_thread(self._sync.create, **kwargs) + + +class _AsyncCodexChatShim: + def __init__(self, adapter: _AsyncCodexCompletionsAdapter): + self.completions = adapter + + +class AsyncCodexAuxiliaryClient: + """Async-compatible wrapper matching AsyncOpenAI.chat.completions.create().""" + + def __init__(self, sync_wrapper: "CodexAuxiliaryClient"): + sync_adapter = sync_wrapper.chat.completions + async_adapter = _AsyncCodexCompletionsAdapter(sync_adapter) + self.chat = _AsyncCodexChatShim(async_adapter) + self.api_key = sync_wrapper.api_key + self.base_url = sync_wrapper.base_url + + +class _AnthropicCompletionsAdapter: + """OpenAI-client-compatible adapter for Anthropic Messages API.""" + + def __init__(self, real_client: Any, model: str, is_oauth: bool = False): + self._client = real_client + self._model = model + self._is_oauth = is_oauth + + def create(self, **kwargs) -> Any: + from agent.anthropic_adapter import build_anthropic_kwargs, normalize_anthropic_response + + messages = kwargs.get("messages", []) + model = kwargs.get("model", self._model) + tools = kwargs.get("tools") + tool_choice = kwargs.get("tool_choice") + max_tokens = kwargs.get("max_tokens") or kwargs.get("max_completion_tokens") or 2000 + temperature = kwargs.get("temperature") + + normalized_tool_choice = None + if isinstance(tool_choice, str): + normalized_tool_choice = tool_choice + elif isinstance(tool_choice, dict): + choice_type = str(tool_choice.get("type", "")).lower() + if choice_type == "function": + normalized_tool_choice = tool_choice.get("function", {}).get("name") + elif choice_type in {"auto", "required", "none"}: + normalized_tool_choice = choice_type + + anthropic_kwargs = build_anthropic_kwargs( + model=model, + messages=messages, + tools=tools, + max_tokens=max_tokens, + reasoning_config=None, + tool_choice=normalized_tool_choice, + is_oauth=self._is_oauth, + ) + if temperature is not None: + anthropic_kwargs["temperature"] = temperature + + response = self._client.messages.create(**anthropic_kwargs) + assistant_message, finish_reason = normalize_anthropic_response(response) + + usage = None + if hasattr(response, "usage") and response.usage: + prompt_tokens = getattr(response.usage, "input_tokens", 0) or 0 + completion_tokens = getattr(response.usage, "output_tokens", 0) or 0 + total_tokens = getattr(response.usage, "total_tokens", 0) or (prompt_tokens + completion_tokens) + usage = SimpleNamespace( + prompt_tokens=prompt_tokens, + completion_tokens=completion_tokens, + total_tokens=total_tokens, + ) + + choice = SimpleNamespace( + index=0, + message=assistant_message, + finish_reason=finish_reason, + ) + return SimpleNamespace( + choices=[choice], + model=model, + usage=usage, + ) + + +class _AnthropicChatShim: + def __init__(self, adapter: _AnthropicCompletionsAdapter): + self.completions = adapter + + +class AnthropicAuxiliaryClient: + """OpenAI-client-compatible wrapper over a native Anthropic client.""" + + def __init__(self, real_client: Any, model: str, api_key: str, base_url: str, is_oauth: bool = False): + self._real_client = real_client + adapter = _AnthropicCompletionsAdapter(real_client, model, is_oauth=is_oauth) + self.chat = _AnthropicChatShim(adapter) + self.api_key = api_key + self.base_url = base_url + + def close(self): + close_fn = getattr(self._real_client, "close", None) + if callable(close_fn): + close_fn() + + +class _AsyncAnthropicCompletionsAdapter: + def __init__(self, sync_adapter: _AnthropicCompletionsAdapter): + self._sync = sync_adapter + + async def create(self, **kwargs) -> Any: + import asyncio + return await asyncio.to_thread(self._sync.create, **kwargs) + + +class _AsyncAnthropicChatShim: + def __init__(self, adapter: _AsyncAnthropicCompletionsAdapter): + self.completions = adapter + + +class AsyncAnthropicAuxiliaryClient: + def __init__(self, sync_wrapper: "AnthropicAuxiliaryClient"): + sync_adapter = sync_wrapper.chat.completions + async_adapter = _AsyncAnthropicCompletionsAdapter(sync_adapter) + self.chat = _AsyncAnthropicChatShim(async_adapter) + self.api_key = sync_wrapper.api_key + self.base_url = sync_wrapper.base_url + + +def _read_nous_auth() -> Optional[dict]: + """Read and validate ~/.hermes/auth.json for an active Nous provider. + + Returns the provider state dict if Nous is active with tokens, + otherwise None. + """ + pool_present, entry = _select_pool_entry("nous") + if pool_present: + if entry is None: + return None + return { + "access_token": getattr(entry, "access_token", ""), + "refresh_token": getattr(entry, "refresh_token", None), + "agent_key": getattr(entry, "agent_key", None), + "inference_base_url": _pool_runtime_base_url(entry, _NOUS_DEFAULT_BASE_URL), + "portal_base_url": getattr(entry, "portal_base_url", None), + "client_id": getattr(entry, "client_id", None), + "scope": getattr(entry, "scope", None), + "token_type": getattr(entry, "token_type", "Bearer"), + "source": "pool", + } + + try: + if not _AUTH_JSON_PATH.is_file(): + return None + data = json.loads(_AUTH_JSON_PATH.read_text()) + if data.get("active_provider") != "nous": + return None + provider = data.get("providers", {}).get("nous", {}) + # Must have at least an access_token or agent_key + if not provider.get("agent_key") and not provider.get("access_token"): + return None + return provider + except Exception as exc: + logger.debug("Could not read Nous auth: %s", exc) + return None + + +def _nous_api_key(provider: dict) -> str: + """Extract the best API key from a Nous provider state dict.""" + return provider.get("agent_key") or provider.get("access_token", "") + + +def _nous_base_url() -> str: + """Resolve the Nous inference base URL from env or default.""" + return os.getenv("NOUS_INFERENCE_BASE_URL", _NOUS_DEFAULT_BASE_URL) + + +def _read_codex_access_token() -> Optional[str]: + """Read a valid, non-expired Codex OAuth access token from Hermes auth store. + + If a credential pool exists but currently has no selectable runtime entry + (for example all pool slots are marked exhausted), fall back to the + profile's auth.json token instead of hard-failing. This keeps explicit + fallback-to-Codex working when the pool state is stale but the stored OAuth + token is still valid. + """ + pool_present, entry = _select_pool_entry("openai-codex") + if pool_present: + token = _pool_runtime_api_key(entry) + if token: + return token + + try: + from hermes_cli.auth import _read_codex_tokens + data = _read_codex_tokens() + tokens = data.get("tokens", {}) + access_token = tokens.get("access_token") + if not isinstance(access_token, str) or not access_token.strip(): + return None + + # Check JWT expiry — expired tokens block the auto chain and + # prevent fallback to working providers (e.g. Anthropic). + try: + import base64 + payload = access_token.split(".")[1] + payload += "=" * (-len(payload) % 4) + claims = json.loads(base64.urlsafe_b64decode(payload)) + exp = claims.get("exp", 0) + if exp and time.time() > exp: + logger.debug("Codex access token expired (exp=%s), skipping", exp) + return None + except Exception: + pass # Non-JWT token or decode error — use as-is + + return access_token.strip() + except Exception as exc: + logger.debug("Could not read Codex auth for auxiliary client: %s", exc) + return None + + +def _resolve_api_key_provider() -> Tuple[Optional[OpenAI], Optional[str]]: + """Try each API-key provider in PROVIDER_REGISTRY order. + + Returns (client, model) for the first provider with usable runtime + credentials, or (None, None) if none are configured. + """ + try: + from hermes_cli.auth import PROVIDER_REGISTRY, resolve_api_key_provider_credentials + except ImportError: + logger.debug("Could not import PROVIDER_REGISTRY for API-key fallback") + return None, None + + for provider_id, pconfig in PROVIDER_REGISTRY.items(): + if pconfig.auth_type != "api_key": + continue + if provider_id == "anthropic": + # Only try anthropic when the user has explicitly configured it. + # Without this gate, Claude Code credentials get silently used + # as auxiliary fallback when the user's primary provider fails. + try: + from hermes_cli.auth import is_provider_explicitly_configured + if not is_provider_explicitly_configured("anthropic"): + continue + except ImportError: + pass + return _try_anthropic() + + pool_present, entry = _select_pool_entry(provider_id) + if pool_present: + api_key = _pool_runtime_api_key(entry) + if not api_key: + continue + + 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) + if model is None: + continue # skip provider if we don't know a valid aux model + logger.debug("Auxiliary text client: %s (%s) via pool", pconfig.name, model) + extra = {} + if "api.kimi.com" in base_url.lower(): + extra["default_headers"] = {"User-Agent": "KimiCLI/1.30.0"} + elif "api.githubcopilot.com" in base_url.lower(): + from hermes_cli.models import copilot_default_headers + + extra["default_headers"] = copilot_default_headers() + return OpenAI(api_key=api_key, base_url=base_url, **extra), model + + creds = resolve_api_key_provider_credentials(provider_id) + api_key = str(creds.get("api_key", "")).strip() + if not api_key: + continue + + 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) + if model is None: + continue # skip provider if we don't know a valid aux model + logger.debug("Auxiliary text client: %s (%s)", pconfig.name, model) + extra = {} + if "api.kimi.com" in base_url.lower(): + extra["default_headers"] = {"User-Agent": "KimiCLI/1.30.0"} + elif "api.githubcopilot.com" in base_url.lower(): + from hermes_cli.models import copilot_default_headers + + extra["default_headers"] = copilot_default_headers() + return OpenAI(api_key=api_key, base_url=base_url, **extra), model + + return None, None + + +# ── Provider resolution helpers ───────────────────────────────────────────── + + + +def _try_openrouter() -> Tuple[Optional[OpenAI], Optional[str]]: + pool_present, entry = _select_pool_entry("openrouter") + if pool_present: + or_key = _pool_runtime_api_key(entry) + if not or_key: + return None, None + base_url = _pool_runtime_base_url(entry, OPENROUTER_BASE_URL) or OPENROUTER_BASE_URL + logger.debug("Auxiliary client: OpenRouter via pool") + return OpenAI(api_key=or_key, base_url=base_url, + default_headers=_OR_HEADERS), _OPENROUTER_MODEL + + or_key = os.getenv("OPENROUTER_API_KEY") + if not or_key: + return None, None + logger.debug("Auxiliary client: OpenRouter") + return OpenAI(api_key=or_key, base_url=OPENROUTER_BASE_URL, + default_headers=_OR_HEADERS), _OPENROUTER_MODEL + + +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") + 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), + base_url=str(nous.get("inference_base_url") or _nous_base_url()).rstrip("/"), + ), + model, + ) + + +def _read_main_model() -> str: + """Read the user's configured main model from config.yaml. + + config.yaml model.default is the single source of truth for the active + model. Environment variables are no longer consulted. + """ + try: + from hermes_cli.config import load_config + cfg = load_config() + model_cfg = cfg.get("model", {}) + if isinstance(model_cfg, str) and model_cfg.strip(): + return model_cfg.strip() + if isinstance(model_cfg, dict): + default = model_cfg.get("default", "") + if isinstance(default, str) and default.strip(): + return default.strip() + except Exception: + pass + return "" + + +def _read_main_provider() -> str: + """Read the user's configured main provider from config.yaml. + + Returns the lowercase provider id (e.g. "alibaba", "openrouter") or "" + if not configured. + """ + try: + from hermes_cli.config import load_config + cfg = load_config() + model_cfg = cfg.get("model", {}) + if isinstance(model_cfg, dict): + provider = model_cfg.get("provider", "") + if isinstance(provider, str) and provider.strip(): + return provider.strip().lower() + except Exception: + pass + return "" + + +def _resolve_custom_runtime() -> Tuple[Optional[str], Optional[str], Optional[str]]: + """Resolve the active custom/main endpoint the same way the main CLI does. + + This covers both env-driven OPENAI_BASE_URL setups and config-saved custom + endpoints where the base URL lives in config.yaml instead of the live + environment. + """ + try: + from hermes_cli.runtime_provider import resolve_runtime_provider + + runtime = resolve_runtime_provider(requested="custom") + except Exception as exc: + logger.debug("Auxiliary client: custom runtime resolution failed: %s", exc) + runtime = None + + if not isinstance(runtime, dict): + openai_base = os.getenv("OPENAI_BASE_URL", "").strip().rstrip("/") + openai_key = os.getenv("OPENAI_API_KEY", "").strip() + if not openai_base: + return None, None, None + runtime = { + "base_url": openai_base, + "api_key": openai_key, + } + + custom_base = runtime.get("base_url") + custom_key = runtime.get("api_key") + custom_mode = runtime.get("api_mode") + if not isinstance(custom_base, str) or not custom_base.strip(): + return None, None, None + + custom_base = custom_base.strip().rstrip("/") + if "openrouter.ai" in custom_base.lower(): + # requested='custom' falls back to OpenRouter when no custom endpoint is + # configured. Treat that as "no custom endpoint" for auxiliary routing. + return None, None, None + + # Local servers (Ollama, llama.cpp, vLLM, LM Studio) don't require auth. + # Use a placeholder key — the OpenAI SDK requires a non-empty string but + # local servers ignore the Authorization header. Same fix as cli.py + # _ensure_runtime_credentials() (PR #2556). + if not isinstance(custom_key, str) or not custom_key.strip(): + custom_key = "no-key-required" + + if not isinstance(custom_mode, str) or not custom_mode.strip(): + custom_mode = None + + return custom_base, custom_key.strip(), custom_mode + + +def _current_custom_base_url() -> str: + custom_base, _, _ = _resolve_custom_runtime() + return custom_base or "" + + +def _try_custom_endpoint() -> Tuple[Optional[OpenAI], Optional[str]]: + runtime = _resolve_custom_runtime() + if len(runtime) == 2: + custom_base, custom_key = runtime + custom_mode = None + else: + custom_base, custom_key, custom_mode = runtime + if not custom_base or not custom_key: + return None, None + if custom_base.lower().startswith(_CODEX_AUX_BASE_URL.lower()): + return None, None + model = _read_main_model() or "gpt-4o-mini" + logger.debug("Auxiliary client: custom endpoint (%s, api_mode=%s)", model, custom_mode or "chat_completions") + if custom_mode == "codex_responses": + real_client = OpenAI(api_key=custom_key, base_url=custom_base) + return CodexAuxiliaryClient(real_client, model), model + return OpenAI(api_key=custom_key, base_url=custom_base), model + + +def _try_codex() -> Tuple[Optional[Any], Optional[str]]: + pool_present, entry = _select_pool_entry("openai-codex") + if pool_present: + codex_token = _pool_runtime_api_key(entry) + if codex_token: + base_url = _pool_runtime_base_url(entry, _CODEX_AUX_BASE_URL) or _CODEX_AUX_BASE_URL + else: + codex_token = _read_codex_access_token() + if not codex_token: + return None, None + base_url = _CODEX_AUX_BASE_URL + else: + codex_token = _read_codex_access_token() + if not codex_token: + return None, None + base_url = _CODEX_AUX_BASE_URL + logger.debug("Auxiliary client: Codex OAuth (%s via Responses API)", _CODEX_AUX_MODEL) + real_client = OpenAI(api_key=codex_token, base_url=base_url) + return CodexAuxiliaryClient(real_client, _CODEX_AUX_MODEL), _CODEX_AUX_MODEL + + +def _try_anthropic() -> Tuple[Optional[Any], Optional[str]]: + try: + from agent.anthropic_adapter import build_anthropic_client, resolve_anthropic_token + except ImportError: + return None, None + + pool_present, entry = _select_pool_entry("anthropic") + if pool_present: + if entry is None: + return None, None + token = _pool_runtime_api_key(entry) + else: + entry = None + token = resolve_anthropic_token() + if not token: + return None, None + + # Allow base URL override from config.yaml model.base_url, but only + # when the configured provider is anthropic — otherwise a non-Anthropic + # base_url (e.g. Codex endpoint) would leak into Anthropic requests. + base_url = _pool_runtime_base_url(entry, _ANTHROPIC_DEFAULT_BASE_URL) if pool_present else _ANTHROPIC_DEFAULT_BASE_URL + try: + from hermes_cli.config import load_config + cfg = load_config() + model_cfg = cfg.get("model") + if isinstance(model_cfg, dict): + cfg_provider = str(model_cfg.get("provider") or "").strip().lower() + if cfg_provider == "anthropic": + cfg_base_url = (model_cfg.get("base_url") or "").strip().rstrip("/") + if cfg_base_url: + base_url = cfg_base_url + except Exception: + pass + + from agent.anthropic_adapter import _is_oauth_token + is_oauth = _is_oauth_token(token) + model = _API_KEY_PROVIDER_AUX_MODELS.get("anthropic", "claude-haiku-4-5-20251001") + logger.debug("Auxiliary client: Anthropic native (%s) at %s (oauth=%s)", model, base_url, is_oauth) + try: + real_client = build_anthropic_client(token, base_url) + except ImportError: + # The anthropic_adapter module imports fine but the SDK itself is + # missing — build_anthropic_client raises ImportError at call time + # when _anthropic_sdk is None. Treat as unavailable. + return None, None + return AnthropicAuxiliaryClient(real_client, model, token, base_url, is_oauth=is_oauth), model + + +_AUTO_PROVIDER_LABELS = { + "_try_openrouter": "openrouter", + "_try_nous": "nous", + "_try_custom_endpoint": "local/custom", + "_try_codex": "openai-codex", + "_resolve_api_key_provider": "api-key", +} + +_AGGREGATOR_PROVIDERS = frozenset({"openrouter", "nous"}) + +_MAIN_RUNTIME_FIELDS = ("provider", "model", "base_url", "api_key", "api_mode") + + +def _normalize_main_runtime(main_runtime: Optional[Dict[str, Any]]) -> Dict[str, str]: + """Return a sanitized copy of a live main-runtime override.""" + if not isinstance(main_runtime, dict): + return {} + normalized: Dict[str, str] = {} + for field in _MAIN_RUNTIME_FIELDS: + value = main_runtime.get(field) + if isinstance(value, str) and value.strip(): + normalized[field] = value.strip() + provider = normalized.get("provider") + if provider: + normalized["provider"] = provider.lower() + return normalized + + +def _get_provider_chain() -> List[tuple]: + """Return the ordered provider detection chain. + + Built at call time (not module level) so that test patches + on the ``_try_*`` functions are picked up correctly. + """ + return [ + ("openrouter", _try_openrouter), + ("nous", _try_nous), + ("local/custom", _try_custom_endpoint), + ("openai-codex", _try_codex), + ("api-key", _resolve_api_key_provider), + ] + + +def _is_payment_error(exc: Exception) -> bool: + """Detect payment/credit/quota exhaustion errors. + + Returns True for HTTP 402 (Payment Required) and for 429/other errors + whose message indicates billing exhaustion rather than rate limiting. + """ + status = getattr(exc, "status_code", None) + if status == 402: + return True + err_lower = str(exc).lower() + # OpenRouter and other providers include "credits" or "afford" in 402 bodies, + # but sometimes wrap them in 429 or other codes. + if status in (402, 429, None): + if any(kw in err_lower for kw in ("credits", "insufficient funds", + "can only afford", "billing", + "payment required")): + return True + return False + + +def _is_connection_error(exc: Exception) -> bool: + """Detect connection/network errors that warrant provider fallback. + + Returns True for errors indicating the provider endpoint is unreachable + (DNS failure, connection refused, TLS errors, timeouts). These are + distinct from API errors (4xx/5xx) which indicate the provider IS + reachable but returned an error. + """ + from openai import APIConnectionError, APITimeoutError + + if isinstance(exc, (APIConnectionError, APITimeoutError)): + return True + # urllib3 / httpx / httpcore connection errors + err_type = type(exc).__name__ + if any(kw in err_type for kw in ("Connection", "Timeout", "DNS", "SSL")): + return True + err_lower = str(exc).lower() + if any(kw in err_lower for kw in ( + "connection refused", "name or service not known", + "no route to host", "network is unreachable", + "timed out", "connection reset", + )): + return True + return False + + +def _try_payment_fallback( + failed_provider: str, + task: str = None, + reason: str = "payment error", +) -> Tuple[Optional[Any], Optional[str], str]: + """Try alternative providers after a payment/credit or connection error. + + Iterates the standard auto-detection chain, skipping the provider that + failed. + + Returns: + (client, model, provider_label) or (None, None, "") if no fallback. + """ + # Normalise the failed provider label for matching. + skip = failed_provider.lower().strip() + # Also skip Step-1 main-provider path if it maps to the same backend. + # (e.g. main_provider="openrouter" → skip "openrouter" in chain) + main_provider = _read_main_provider() + skip_labels = {skip} + if main_provider and main_provider.lower() in skip: + skip_labels.add(main_provider.lower()) + # Map common resolved_provider values back to chain labels. + _alias_to_label = {"openrouter": "openrouter", "nous": "nous", + "openai-codex": "openai-codex", "codex": "openai-codex", + "custom": "local/custom", "local/custom": "local/custom"} + skip_chain_labels = {_alias_to_label.get(s, s) for s in skip_labels} + + tried = [] + for label, try_fn in _get_provider_chain(): + if label in skip_chain_labels: + continue + client, model = try_fn() + if client is not None: + logger.info( + "Auxiliary %s: %s on %s — falling back to %s (%s)", + task or "call", reason, failed_provider, label, model or "default", + ) + return client, model, label + tried.append(label) + + logger.warning( + "Auxiliary %s: %s on %s and no fallback available (tried: %s)", + task or "call", reason, failed_provider, ", ".join(tried), + ) + return None, None, "" + + +def _resolve_auto(main_runtime: Optional[Dict[str, Any]] = None) -> Tuple[Optional[OpenAI], Optional[str]]: + """Full auto-detection chain. + + Priority: + 1. If the user's main provider is NOT an aggregator (OpenRouter / Nous), + use their main provider + main model directly. This ensures users on + Alibaba, DeepSeek, ZAI, etc. get auxiliary tasks handled by the same + provider they already have credentials for — no OpenRouter key needed. + 2. OpenRouter → Nous → custom → Codex → API-key providers (original chain). + """ + global auxiliary_is_nous, _stale_base_url_warned + auxiliary_is_nous = False # Reset — _try_nous() will set True if it wins + runtime = _normalize_main_runtime(main_runtime) + runtime_provider = runtime.get("provider", "") + runtime_model = runtime.get("model", "") + runtime_base_url = runtime.get("base_url", "") + runtime_api_key = runtime.get("api_key", "") + runtime_api_mode = runtime.get("api_mode", "") + + # ── Warn once if OPENAI_BASE_URL is set but config.yaml uses a named + # provider (not 'custom'). This catches the common "env poisoning" + # scenario where a user switches providers via `hermes model` but the + # old OPENAI_BASE_URL lingers in ~/.hermes/.env. ── + if not _stale_base_url_warned: + _env_base = os.getenv("OPENAI_BASE_URL", "").strip() + _cfg_provider = runtime_provider or _read_main_provider() + if (_env_base and _cfg_provider + and _cfg_provider != "custom" + and not _cfg_provider.startswith("custom:")): + logger.warning( + "OPENAI_BASE_URL is set (%s) but model.provider is '%s'. " + "Auxiliary clients may route to the wrong endpoint. " + "Run: hermes model to reconfigure, or remove " + "OPENAI_BASE_URL from ~/.hermes/.env", + _env_base, _cfg_provider, + ) + _stale_base_url_warned = True + + # ── Step 1: non-aggregator main provider → use main model directly ── + main_provider = runtime_provider or _read_main_provider() + main_model = runtime_model or _read_main_model() + if (main_provider and main_model + and main_provider not in _AGGREGATOR_PROVIDERS + and main_provider not in ("auto", "")): + resolved_provider = main_provider + explicit_base_url = None + explicit_api_key = None + if runtime_base_url and (main_provider == "custom" or main_provider.startswith("custom:")): + resolved_provider = "custom" + explicit_base_url = runtime_base_url + explicit_api_key = runtime_api_key or None + client, resolved = resolve_provider_client( + resolved_provider, + main_model, + explicit_base_url=explicit_base_url, + explicit_api_key=explicit_api_key, + api_mode=runtime_api_mode or None, + ) + if client is not None: + logger.info("Auxiliary auto-detect: using main provider %s (%s)", + main_provider, resolved or main_model) + return client, resolved or main_model + + # ── Step 2: aggregator / fallback chain ────────────────────────────── + tried = [] + for label, try_fn in _get_provider_chain(): + client, model = try_fn() + if client is not None: + if tried: + logger.info("Auxiliary auto-detect: using %s (%s) — skipped: %s", + label, model or "default", ", ".join(tried)) + else: + logger.info("Auxiliary auto-detect: using %s (%s)", label, model or "default") + return client, model + tried.append(label) + logger.warning("Auxiliary auto-detect: no provider available (tried: %s). " + "Compression, summarization, and memory flush will not work. " + "Set OPENROUTER_API_KEY or configure a local model in config.yaml.", + ", ".join(tried)) + return None, None + + +# ── Centralized Provider Router ───────────────────────────────────────────── +# +# resolve_provider_client() is the single entry point for creating a properly +# configured client given a (provider, model) pair. It handles auth lookup, +# base URL resolution, provider-specific headers, and API format differences +# (Chat Completions vs Responses API for Codex). +# +# All auxiliary consumer code should go through this or the public helpers +# below — never look up auth env vars ad-hoc. + + +def _to_async_client(sync_client, model: str): + """Convert a sync client to its async counterpart, preserving Codex routing.""" + from openai import AsyncOpenAI + + if isinstance(sync_client, CodexAuxiliaryClient): + return AsyncCodexAuxiliaryClient(sync_client), model + if isinstance(sync_client, AnthropicAuxiliaryClient): + return AsyncAnthropicAuxiliaryClient(sync_client), model + try: + from agent.copilot_acp_client import CopilotACPClient + if isinstance(sync_client, CopilotACPClient): + return sync_client, model + except ImportError: + pass + + async_kwargs = { + "api_key": sync_client.api_key, + "base_url": str(sync_client.base_url), + } + base_lower = str(sync_client.base_url).lower() + if "openrouter" in base_lower: + async_kwargs["default_headers"] = dict(_OR_HEADERS) + elif "api.githubcopilot.com" in base_lower: + from hermes_cli.models import copilot_default_headers + + async_kwargs["default_headers"] = copilot_default_headers() + elif "api.kimi.com" in base_lower: + async_kwargs["default_headers"] = {"User-Agent": "KimiCLI/1.30.0"} + return AsyncOpenAI(**async_kwargs), model + + +def _normalize_resolved_model(model_name: Optional[str], provider: str) -> Optional[str]: + """Normalize a resolved model for the provider that will receive it.""" + if not model_name: + return model_name + try: + from hermes_cli.model_normalize import normalize_model_for_provider + + return normalize_model_for_provider(model_name, provider) + except Exception: + return model_name + + +def resolve_provider_client( + provider: str, + model: str = None, + async_mode: bool = False, + raw_codex: bool = False, + explicit_base_url: str = None, + explicit_api_key: str = None, + api_mode: str = None, + main_runtime: Optional[Dict[str, Any]] = None, +) -> Tuple[Optional[Any], Optional[str]]: + """Central router: given a provider name and optional model, return a + configured client with the correct auth, base URL, and API format. + + The returned client always exposes ``.chat.completions.create()`` — for + Codex/Responses API providers, an adapter handles the translation + transparently. + + Args: + provider: Provider identifier. One of: + "openrouter", "nous", "openai-codex" (or "codex"), + "zai", "kimi-coding", "minimax", "minimax-cn", + "custom" (OPENAI_BASE_URL + OPENAI_API_KEY), + "auto" (full auto-detection chain). + model: Model slug override. If None, uses the provider's default + auxiliary model. + async_mode: If True, return an async-compatible client. + raw_codex: If True, return a raw OpenAI client for Codex providers + instead of wrapping in CodexAuxiliaryClient. Use this when + the caller needs direct access to responses.stream() (e.g., + the main agent loop). + explicit_base_url: Optional direct OpenAI-compatible endpoint. + explicit_api_key: Optional API key paired with explicit_base_url. + api_mode: API mode override. One of "chat_completions", + "codex_responses", or None (auto-detect). When set to + "codex_responses", the client is wrapped in + CodexAuxiliaryClient to route through the Responses API. + + Returns: + (client, resolved_model) or (None, None) if auth is unavailable. + """ + # Normalise aliases + provider = _normalize_aux_provider(provider) + + def _needs_codex_wrap(client_obj, base_url_str: str, model_str: str) -> bool: + """Decide if a plain OpenAI client should be wrapped for Responses API. + + Returns True when api_mode is explicitly "codex_responses", or when + auto-detection (api.openai.com + codex-family model) suggests it. + Already-wrapped clients (CodexAuxiliaryClient) are skipped. + """ + if isinstance(client_obj, CodexAuxiliaryClient): + return False + if raw_codex: + return False + if api_mode == "codex_responses": + return True + # Auto-detect: api.openai.com + codex model name pattern + if api_mode and api_mode != "codex_responses": + return False # explicit non-codex mode + normalized_base = (base_url_str or "").strip().lower() + if "api.openai.com" in normalized_base and "openrouter" not in normalized_base: + model_lower = (model_str or "").lower() + if "codex" in model_lower: + return True + return False + + def _wrap_if_needed(client_obj, final_model_str: str, base_url_str: str = ""): + """Wrap a plain OpenAI client in CodexAuxiliaryClient if Responses API is needed.""" + if _needs_codex_wrap(client_obj, base_url_str, final_model_str): + logger.debug( + "resolve_provider_client: wrapping client in CodexAuxiliaryClient " + "(api_mode=%s, model=%s, base_url=%s)", + api_mode or "auto-detected", final_model_str, + base_url_str[:60] if base_url_str else "") + return CodexAuxiliaryClient(client_obj, final_model_str) + return client_obj + + # ── Auto: try all providers in priority order ──────────────────── + if provider == "auto": + client, resolved = _resolve_auto(main_runtime=main_runtime) + if client is None: + return None, None + # When auto-detection lands on a non-OpenRouter provider (e.g. a + # local server), an OpenRouter-formatted model override like + # "google/gemini-3-flash-preview" won't work. Drop it and use + # the provider's own default model instead. + if model and "/" in model and resolved and "/" not in resolved: + logger.debug( + "Dropping OpenRouter-format model %r for non-OpenRouter " + "auxiliary provider (using %r instead)", model, resolved) + model = None + final_model = model or resolved + return (_to_async_client(client, final_model) if async_mode + else (client, final_model)) + + # ── OpenRouter ─────────────────────────────────────────────────── + if provider == "openrouter": + client, default = _try_openrouter() + if client is None: + logger.warning("resolve_provider_client: openrouter requested " + "but OPENROUTER_API_KEY not set") + return None, None + final_model = _normalize_resolved_model(model or default, provider) + return (_to_async_client(client, final_model) if async_mode + else (client, final_model)) + + # ── Nous Portal (OAuth) ────────────────────────────────────────── + if provider == "nous": + client, default = _try_nous() + if client is None: + logger.warning("resolve_provider_client: nous requested " + "but Nous Portal not configured (run: hermes auth)") + return None, None + final_model = _normalize_resolved_model(model or default, provider) + return (_to_async_client(client, final_model) if async_mode + else (client, final_model)) + + # ── OpenAI Codex (OAuth → Responses API) ───────────────────────── + if provider == "openai-codex": + if raw_codex: + # Return the raw OpenAI client for callers that need direct + # access to responses.stream() (e.g., the main agent loop). + codex_token = _read_codex_access_token() + if not codex_token: + logger.warning("resolve_provider_client: openai-codex requested " + "but no Codex OAuth token found (run: hermes model)") + return None, None + final_model = _normalize_resolved_model(model or _CODEX_AUX_MODEL, provider) + raw_client = OpenAI(api_key=codex_token, base_url=_CODEX_AUX_BASE_URL) + return (raw_client, final_model) + # Standard path: wrap in CodexAuxiliaryClient adapter + client, default = _try_codex() + if client is None: + logger.warning("resolve_provider_client: openai-codex requested " + "but no Codex OAuth token found (run: hermes model)") + return None, None + final_model = _normalize_resolved_model(model or default, provider) + 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: + custom_base = explicit_base_url.strip() + custom_key = ( + (explicit_api_key or "").strip() + or os.getenv("OPENAI_API_KEY", "").strip() + or "no-key-required" # local servers don't need auth + ) + if not custom_base: + logger.warning( + "resolve_provider_client: explicit custom endpoint requested " + "but base_url is empty" + ) + return None, None + final_model = _normalize_resolved_model( + model or _read_main_model() or "gpt-4o-mini", + provider, + ) + extra = {} + if "api.kimi.com" in custom_base.lower(): + extra["default_headers"] = {"User-Agent": "KimiCLI/1.30.0"} + elif "api.githubcopilot.com" in custom_base.lower(): + from hermes_cli.models import copilot_default_headers + extra["default_headers"] = copilot_default_headers() + client = OpenAI(api_key=custom_key, base_url=custom_base, **extra) + client = _wrap_if_needed(client, final_model, custom_base) + return (_to_async_client(client, final_model) if async_mode + else (client, final_model)) + # Try custom first, then codex, then API-key providers + for try_fn in (_try_custom_endpoint, _try_codex, + _resolve_api_key_provider): + client, default = try_fn() + if client is not None: + final_model = _normalize_resolved_model(model or default, provider) + _cbase = str(getattr(client, "base_url", "") or "") + client = _wrap_if_needed(client, final_model, _cbase) + return (_to_async_client(client, final_model) if async_mode + else (client, final_model)) + logger.warning("resolve_provider_client: custom/main requested " + "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() + custom_key_env = custom_entry.get("key_env", "").strip() + if not custom_key and custom_key_env: + custom_key = os.getenv(custom_key_env, "").strip() + custom_key = custom_key or "no-key-required" + if custom_base: + final_model = _normalize_resolved_model( + model or custom_entry.get("model") or _read_main_model() or "gpt-4o-mini", + provider, + ) + client = OpenAI(api_key=custom_key, base_url=custom_base) + client = _wrap_if_needed(client, final_model, 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, + resolve_external_process_provider_credentials, + ) + except ImportError: + logger.debug("hermes_cli.auth not available for provider %s", provider) + return None, None + + pconfig = PROVIDER_REGISTRY.get(provider) + if pconfig is None: + logger.warning("resolve_provider_client: unknown provider %r", provider) + return None, None + + if pconfig.auth_type == "api_key": + if provider == "anthropic": + client, default_model = _try_anthropic() + if client is None: + logger.warning("resolve_provider_client: anthropic requested but no Anthropic credentials found") + return None, None + final_model = _normalize_resolved_model(model or default_model, provider) + return (_to_async_client(client, final_model) if async_mode else (client, final_model)) + + creds = resolve_api_key_provider_credentials(provider) + api_key = str(creds.get("api_key", "")).strip() + if not api_key: + tried_sources = list(pconfig.api_key_env_vars) + if provider == "copilot": + tried_sources.append("gh auth token") + logger.debug("resolve_provider_client: provider %s has no API " + "key configured (tried: %s)", + provider, ", ".join(tried_sources)) + return None, None + + 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 = _normalize_resolved_model(model or default_model, provider) + + # Provider-specific headers + headers = {} + if "api.kimi.com" in base_url.lower(): + headers["User-Agent"] = "KimiCLI/1.30.0" + elif "api.githubcopilot.com" in base_url.lower(): + from hermes_cli.models import copilot_default_headers + + headers.update(copilot_default_headers()) + + client = OpenAI(api_key=api_key, base_url=base_url, + **({"default_headers": headers} if headers else {})) + + # Copilot GPT-5+ models (except gpt-5-mini) require the Responses + # API — they are not accessible via /chat/completions. Wrap the + # plain client in CodexAuxiliaryClient so call_llm() transparently + # routes through responses.stream(). + if provider == "copilot" and final_model and not raw_codex: + try: + from hermes_cli.models import _should_use_copilot_responses_api + if _should_use_copilot_responses_api(final_model): + logger.debug( + "resolve_provider_client: copilot model %s needs " + "Responses API — wrapping with CodexAuxiliaryClient", + final_model) + client = CodexAuxiliaryClient(client, final_model) + except ImportError: + pass + + # Honor api_mode for any API-key provider (e.g. direct OpenAI with + # codex-family models). The copilot-specific wrapping above handles + # copilot; this covers the general case (#6800). + client = _wrap_if_needed(client, final_model, base_url) + + logger.debug("resolve_provider_client: %s (%s)", provider, final_model) + return (_to_async_client(client, final_model) if async_mode + else (client, final_model)) + + if pconfig.auth_type == "external_process": + creds = resolve_external_process_provider_credentials(provider) + final_model = _normalize_resolved_model(model or _read_main_model(), provider) + if provider == "copilot-acp": + api_key = str(creds.get("api_key", "")).strip() + base_url = str(creds.get("base_url", "")).strip() + command = str(creds.get("command", "")).strip() or None + args = list(creds.get("args") or []) + if not final_model: + logger.warning( + "resolve_provider_client: copilot-acp requested but no model " + "was provided or configured" + ) + return None, None + if not api_key or not base_url: + logger.warning( + "resolve_provider_client: copilot-acp requested but external " + "process credentials are incomplete" + ) + return None, None + from agent.copilot_acp_client import CopilotACPClient + + client = CopilotACPClient( + api_key=api_key, + base_url=base_url, + command=command, + args=args, + ) + logger.debug("resolve_provider_client: %s (%s)", provider, final_model) + return (_to_async_client(client, final_model) if async_mode + else (client, final_model)) + logger.warning("resolve_provider_client: external-process provider %s not " + "directly supported", provider) + return None, None + + elif pconfig.auth_type in ("oauth_device_code", "oauth_external"): + # OAuth providers — route through their specific try functions + if provider == "nous": + return resolve_provider_client("nous", model, async_mode) + if provider == "openai-codex": + return resolve_provider_client("openai-codex", model, async_mode) + # Other OAuth providers not directly supported + logger.warning("resolve_provider_client: OAuth provider %s not " + "directly supported, try 'auto'", provider) + return None, None + + logger.warning("resolve_provider_client: unhandled auth_type %s for %s", + pconfig.auth_type, provider) + return None, None + + +# ── Public API ────────────────────────────────────────────────────────────── + +def get_text_auxiliary_client( + task: str = "", + *, + main_runtime: Optional[Dict[str, Any]] = None, +) -> Tuple[Optional[OpenAI], Optional[str]]: + """Return (client, default_model_slug) for text-only auxiliary tasks. + + Args: + task: Optional task name ("compression", "web_extract") to check + for a task-specific provider override. + + Callers may override the returned model via config.yaml + (e.g. auxiliary.compression.model, auxiliary.web_extract.model). + """ + provider, model, base_url, api_key, api_mode = _resolve_task_provider_model(task or None) + return resolve_provider_client( + provider, + model=model, + explicit_base_url=base_url, + explicit_api_key=api_key, + api_mode=api_mode, + main_runtime=main_runtime, + ) + + +def get_async_text_auxiliary_client(task: str = "", *, main_runtime: Optional[Dict[str, Any]] = None): + """Return (async_client, model_slug) for async consumers. + + For standard providers returns (AsyncOpenAI, model). For Codex returns + (AsyncCodexAuxiliaryClient, model) which wraps the Responses API. + Returns (None, None) when no provider is available. + """ + provider, model, base_url, api_key, api_mode = _resolve_task_provider_model(task or None) + return resolve_provider_client( + provider, + model=model, + async_mode=True, + explicit_base_url=base_url, + explicit_api_key=api_key, + api_mode=api_mode, + main_runtime=main_runtime, + ) + + +_VISION_AUTO_PROVIDER_ORDER = ( + "openrouter", + "nous", +) + + +def _normalize_vision_provider(provider: Optional[str]) -> str: + return _normalize_aux_provider(provider) + + +def _resolve_strict_vision_backend(provider: str) -> Tuple[Optional[Any], Optional[str]]: + provider = _normalize_vision_provider(provider) + if provider == "openrouter": + return _try_openrouter() + if provider == "nous": + return _try_nous(vision=True) + if provider == "openai-codex": + return _try_codex() + if provider == "anthropic": + return _try_anthropic() + if provider == "custom": + return _try_custom_endpoint() + return None, None + + +def _strict_vision_backend_available(provider: str) -> bool: + return _resolve_strict_vision_backend(provider)[0] is not None + + +def get_available_vision_backends() -> List[str]: + """Return the currently available vision backends in auto-selection 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. + """ + 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( + provider: Optional[str] = None, + model: Optional[str] = None, + *, + base_url: Optional[str] = None, + api_key: Optional[str] = None, + async_mode: bool = False, +) -> Tuple[Optional[str], Optional[Any], Optional[str]]: + """Resolve the client actually used for vision tasks. + + Direct endpoint overrides take precedence over provider selection. Explicit + provider overrides still use the generic provider router for non-standard + backends, so users can intentionally force experimental providers. Auto mode + stays conservative and only tries vision backends known to work today. + """ + requested, resolved_model, resolved_base_url, resolved_api_key, resolved_api_mode = _resolve_task_provider_model( + "vision", provider, model, base_url, api_key + ) + requested = _normalize_vision_provider(requested) + + def _finalize(resolved_provider: str, sync_client: Any, default_model: Optional[str]): + if sync_client is None: + return resolved_provider, None, None + final_model = resolved_model or default_model + if async_mode: + async_client, async_model = _to_async_client(sync_client, final_model) + return resolved_provider, async_client, async_model + return resolved_provider, sync_client, final_model + + if resolved_base_url: + client, final_model = resolve_provider_client( + "custom", + model=resolved_model, + async_mode=async_mode, + explicit_base_url=resolved_base_url, + explicit_api_key=resolved_api_key, + api_mode=resolved_api_mode, + ) + if client is None: + return "custom", None, None + return "custom", client, final_model + + if requested == "auto": + # 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, Xiaomi, named custom, etc.) + # Use provider-specific vision model if available, otherwise main model. + vision_model = _PROVIDER_VISION_MODELS.get(main_provider, main_model) + rpc_client, rpc_model = resolve_provider_client( + main_provider, vision_model, + api_mode=resolved_api_mode) + if rpc_client is not None: + logger.info( + "Vision auto-detect: using active provider %s (%s)", + main_provider, rpc_model or vision_model, + ) + return _finalize( + main_provider, rpc_client, rpc_model or vision_model) + + # 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 + + if requested in _VISION_AUTO_PROVIDER_ORDER: + sync_client, default_model = _resolve_strict_vision_backend(requested) + return _finalize(requested, sync_client, default_model) + + client, final_model = _get_cached_client(requested, resolved_model, async_mode, + api_mode=resolved_api_mode) + if client is None: + return requested, None, None + return requested, client, final_model + + +def get_auxiliary_extra_body() -> dict: + """Return extra_body kwargs for auxiliary API calls. + + Includes Nous Portal product tags when the auxiliary client is backed + by Nous Portal. Returns empty dict otherwise. + """ + return dict(NOUS_EXTRA_BODY) if auxiliary_is_nous else {} + + +def auxiliary_max_tokens_param(value: int) -> dict: + """Return the correct max tokens kwarg for the auxiliary client's provider. + + OpenRouter and local models use 'max_tokens'. Direct OpenAI with newer + models (gpt-4o, o-series, gpt-5+) requires 'max_completion_tokens'. + The Codex adapter translates max_tokens internally, so we use max_tokens + for it as well. + """ + custom_base = _current_custom_base_url() + or_key = os.getenv("OPENROUTER_API_KEY") + # Only use max_completion_tokens for direct OpenAI custom endpoints + if (not or_key + and _read_nous_auth() is None + and "api.openai.com" in custom_base.lower()): + return {"max_completion_tokens": value} + return {"max_tokens": value} + + +# ── Centralized LLM Call API ──────────────────────────────────────────────── +# +# call_llm() and async_call_llm() own the full request lifecycle: +# 1. Resolve provider + model from task config (or explicit args) +# 2. Get or create a cached client for that provider +# 3. Format request args for the provider + model (max_tokens handling, etc.) +# 4. Make the API call +# 5. Return the response +# +# Every auxiliary LLM consumer should use these instead of manually +# constructing clients and calling .chat.completions.create(). + +# Client cache: (provider, async_mode, base_url, api_key) -> (client, default_model) +_client_cache: Dict[tuple, tuple] = {} +_client_cache_lock = threading.Lock() + + +def neuter_async_httpx_del() -> None: + """Monkey-patch ``AsyncHttpxClientWrapper.__del__`` to be a no-op. + + The OpenAI SDK's ``AsyncHttpxClientWrapper.__del__`` schedules + ``self.aclose()`` via ``asyncio.get_running_loop().create_task()``. + When an ``AsyncOpenAI`` client is garbage-collected while + prompt_toolkit's event loop is running (the common CLI idle state), + the ``aclose()`` task runs on prompt_toolkit's loop but the + underlying TCP transport is bound to a *different* loop (the worker + thread's loop that the client was originally created on). If that + loop is closed or its thread is dead, the transport's + ``self._loop.call_soon()`` raises ``RuntimeError("Event loop is + closed")``, which prompt_toolkit surfaces as "Unhandled exception + in event loop ... Press ENTER to continue...". + + Neutering ``__del__`` is safe because: + - Cached clients are explicitly cleaned via ``_force_close_async_httpx`` + on stale-loop detection and ``shutdown_cached_clients`` on exit. + - Uncached clients' TCP connections are cleaned up by the OS when the + process exits. + - The OpenAI SDK itself marks this as a TODO (``# TODO(someday): + support non asyncio runtimes here``). + + Call this once at CLI startup, before any ``AsyncOpenAI`` clients are + created. + """ + try: + from openai._base_client import AsyncHttpxClientWrapper + AsyncHttpxClientWrapper.__del__ = lambda self: None # type: ignore[assignment] + except (ImportError, AttributeError): + pass # Graceful degradation if the SDK changes its internals + + +def _force_close_async_httpx(client: Any) -> None: + """Mark the httpx AsyncClient inside an AsyncOpenAI client as closed. + + This prevents ``AsyncHttpxClientWrapper.__del__`` from scheduling + ``aclose()`` on a (potentially closed) event loop, which causes + ``RuntimeError: Event loop is closed`` → prompt_toolkit's + "Press ENTER to continue..." handler. + + We intentionally do NOT run the full async close path — the + connections will be dropped by the OS when the process exits. + """ + try: + from httpx._client import ClientState + inner = getattr(client, "_client", None) + if inner is not None and not getattr(inner, "is_closed", True): + inner._state = ClientState.CLOSED + except Exception: + pass + + +def shutdown_cached_clients() -> None: + """Close all cached clients (sync and async) to prevent event-loop errors. + + Call this during CLI shutdown, *before* the event loop is closed, to + avoid ``AsyncHttpxClientWrapper.__del__`` raising on a dead loop. + """ + import inspect + + with _client_cache_lock: + for key, entry in list(_client_cache.items()): + client = entry[0] + if client is None: + continue + # Mark any async httpx transport as closed first (prevents __del__ + # from scheduling aclose() on a dead event loop). + _force_close_async_httpx(client) + # Sync clients: close the httpx connection pool cleanly. + # Async clients: skip — we already neutered __del__ above. + try: + close_fn = getattr(client, "close", None) + if close_fn and not inspect.iscoroutinefunction(close_fn): + close_fn() + except Exception: + pass + _client_cache.clear() + + +def cleanup_stale_async_clients() -> None: + """Force-close cached async clients whose event loop is closed. + + Call this after each agent turn to proactively clean up stale clients + before GC can trigger ``AsyncHttpxClientWrapper.__del__`` on them. + This is defense-in-depth — the primary fix is ``neuter_async_httpx_del`` + which disables ``__del__`` entirely. + """ + with _client_cache_lock: + stale_keys = [] + for key, entry in _client_cache.items(): + client, _default, cached_loop = entry + if cached_loop is not None and cached_loop.is_closed(): + _force_close_async_httpx(client) + stale_keys.append(key) + for key in stale_keys: + del _client_cache[key] + + +def _is_openrouter_client(client: Any) -> bool: + for obj in (client, getattr(client, "_client", None), getattr(client, "client", None)): + if obj and "openrouter" in str(getattr(obj, "base_url", "") or "").lower(): + return True + return False + + +def _compat_model(client: Any, model: Optional[str], cached_default: Optional[str]) -> Optional[str]: + """Drop OpenRouter-format model slugs (with '/') for non-OpenRouter clients. + + Mirrors the guard in resolve_provider_client() which is skipped on cache hits. + """ + if model and "/" in model and not _is_openrouter_client(client): + return cached_default + return model or cached_default + + +def _get_cached_client( + provider: str, + model: str = None, + async_mode: bool = False, + base_url: str = None, + api_key: str = None, + api_mode: str = None, + main_runtime: Optional[Dict[str, Any]] = None, +) -> Tuple[Optional[Any], Optional[str]]: + """Get or create a cached client for the given provider. + + Async clients (AsyncOpenAI) use httpx.AsyncClient internally, which + binds to the event loop that was current when the client was created. + Using such a client on a *different* loop causes deadlocks or + RuntimeError. To prevent cross-loop issues (especially in gateway + mode where _run_async() may spawn fresh loops in worker threads), the + cache key for async clients includes the current event loop's identity + so each loop gets its own client instance. + """ + # Include loop identity for async clients to prevent cross-loop reuse. + # httpx.AsyncClient (inside AsyncOpenAI) is bound to the loop where it + # was created — reusing it on a different loop causes deadlocks (#2681). + loop_id = 0 + current_loop = None + if async_mode: + try: + import asyncio as _aio + current_loop = _aio.get_event_loop() + loop_id = id(current_loop) + except RuntimeError: + pass + runtime = _normalize_main_runtime(main_runtime) + runtime_key = tuple(runtime.get(field, "") for field in _MAIN_RUNTIME_FIELDS) if provider == "auto" else () + cache_key = (provider, async_mode, base_url or "", api_key or "", api_mode or "", loop_id, runtime_key) + with _client_cache_lock: + if cache_key in _client_cache: + cached_client, cached_default, cached_loop = _client_cache[cache_key] + if async_mode: + # A cached async client whose loop has been closed will raise + # "Event loop is closed" when httpx tries to clean up its + # transport. Discard the stale client and create a fresh one. + if cached_loop is not None and cached_loop.is_closed(): + _force_close_async_httpx(cached_client) + del _client_cache[cache_key] + else: + effective = _compat_model(cached_client, model, cached_default) + return cached_client, effective + else: + effective = _compat_model(cached_client, model, cached_default) + return cached_client, effective + # Build outside the lock + client, default_model = resolve_provider_client( + provider, + model, + async_mode, + explicit_base_url=base_url, + explicit_api_key=api_key, + api_mode=api_mode, + main_runtime=runtime, + ) + if client is not None: + # For async clients, remember which loop they were created on so we + # can detect stale entries later. + bound_loop = current_loop + with _client_cache_lock: + if cache_key not in _client_cache: + _client_cache[cache_key] = (client, default_model, bound_loop) + else: + client, default_model, _ = _client_cache[cache_key] + return client, model or default_model + + +def _resolve_task_provider_model( + task: str = None, + provider: str = None, + model: str = None, + base_url: str = None, + api_key: str = None, +) -> Tuple[str, Optional[str], Optional[str], Optional[str], Optional[str]]: + """Determine provider + model for a call. + + Priority: + 1. Explicit provider/model/base_url/api_key args (always win) + 2. Config file (auxiliary.{task}.provider/model/base_url) + 3. "auto" (full auto-detection chain) + + Returns (provider, model, base_url, api_key, api_mode) where model may + be None (use provider default). When base_url is set, provider is forced + to "custom" and the task uses that direct endpoint. api_mode is one of + "chat_completions", "codex_responses", or None (auto-detect). + """ + config = {} + cfg_provider = None + cfg_model = None + cfg_base_url = None + cfg_api_key = None + cfg_api_mode = None + + if task: + try: + from hermes_cli.config import load_config + config = load_config() + except ImportError: + config = {} + + aux = config.get("auxiliary", {}) if isinstance(config, dict) else {} + task_config = aux.get(task, {}) if isinstance(aux, dict) else {} + if not isinstance(task_config, dict): + task_config = {} + cfg_provider = str(task_config.get("provider", "")).strip() or None + cfg_model = str(task_config.get("model", "")).strip() or None + cfg_base_url = str(task_config.get("base_url", "")).strip() or None + cfg_api_key = str(task_config.get("api_key", "")).strip() or None + cfg_api_mode = str(task_config.get("api_mode", "")).strip() or None + + resolved_model = model or cfg_model + resolved_api_mode = cfg_api_mode + + if base_url: + return "custom", resolved_model, base_url, api_key, resolved_api_mode + if provider: + return provider, resolved_model, base_url, api_key, resolved_api_mode + + if task: + # Config.yaml is the primary source for per-task overrides. + if cfg_base_url: + return "custom", resolved_model, cfg_base_url, cfg_api_key, resolved_api_mode + if cfg_provider and cfg_provider != "auto": + return cfg_provider, resolved_model, None, None, resolved_api_mode + + return "auto", resolved_model, None, None, resolved_api_mode + + return "auto", resolved_model, None, None, resolved_api_mode + + +_DEFAULT_AUX_TIMEOUT = 30.0 + + +def _get_task_timeout(task: str, default: float = _DEFAULT_AUX_TIMEOUT) -> float: + """Read timeout from auxiliary.{task}.timeout in config, falling back to *default*.""" + if not task: + return default + try: + from hermes_cli.config import load_config + config = load_config() + except ImportError: + return default + aux = config.get("auxiliary", {}) if isinstance(config, dict) else {} + task_config = aux.get(task, {}) if isinstance(aux, dict) else {} + raw = task_config.get("timeout") + if raw is not None: + try: + return float(raw) + except (ValueError, TypeError): + pass + return default + + +# --------------------------------------------------------------------------- +# Anthropic-compatible endpoint detection + image block conversion +# --------------------------------------------------------------------------- + +# Providers that use Anthropic-compatible endpoints (via OpenAI SDK wrapper). +# Their image content blocks must use Anthropic format, not OpenAI format. +_ANTHROPIC_COMPAT_PROVIDERS = frozenset({"minimax", "minimax-cn"}) + + +def _is_anthropic_compat_endpoint(provider: str, base_url: str) -> bool: + """Detect if an endpoint expects Anthropic-format content blocks. + + Returns True for known Anthropic-compatible providers (MiniMax) and + any endpoint whose URL contains ``/anthropic`` in the path. + """ + if provider in _ANTHROPIC_COMPAT_PROVIDERS: + return True + url_lower = (base_url or "").lower() + return "/anthropic" in url_lower + + +def _convert_openai_images_to_anthropic(messages: list) -> list: + """Convert OpenAI ``image_url`` content blocks to Anthropic ``image`` blocks. + + Only touches messages that have list-type content with ``image_url`` blocks; + plain text messages pass through unchanged. + """ + converted = [] + for msg in messages: + content = msg.get("content") + if not isinstance(content, list): + converted.append(msg) + continue + new_content = [] + changed = False + for block in content: + if block.get("type") == "image_url": + image_url_val = (block.get("image_url") or {}).get("url", "") + if image_url_val.startswith("data:"): + # Parse data URI: data:;base64, + header, _, b64data = image_url_val.partition(",") + media_type = "image/png" + if ":" in header and ";" in header: + media_type = header.split(":", 1)[1].split(";", 1)[0] + new_content.append({ + "type": "image", + "source": { + "type": "base64", + "media_type": media_type, + "data": b64data, + }, + }) + else: + # URL-based image + new_content.append({ + "type": "image", + "source": { + "type": "url", + "url": image_url_val, + }, + }) + changed = True + else: + new_content.append(block) + converted.append({**msg, "content": new_content} if changed else msg) + return converted + + + +def _build_call_kwargs( + provider: str, + model: str, + messages: list, + temperature: Optional[float] = None, + max_tokens: Optional[int] = None, + tools: Optional[list] = None, + timeout: float = 30.0, + extra_body: Optional[dict] = None, + base_url: Optional[str] = None, +) -> dict: + """Build kwargs for .chat.completions.create() with model/provider adjustments.""" + kwargs: Dict[str, Any] = { + "model": model, + "messages": messages, + "timeout": timeout, + } + + if temperature is not None: + kwargs["temperature"] = temperature + + if max_tokens is not None: + # Codex adapter handles max_tokens internally; OpenRouter/Nous use max_tokens. + # Direct OpenAI api.openai.com with newer models needs max_completion_tokens. + if provider == "custom": + custom_base = base_url or _current_custom_base_url() + if "api.openai.com" in custom_base.lower(): + kwargs["max_completion_tokens"] = max_tokens + else: + kwargs["max_tokens"] = max_tokens + else: + kwargs["max_tokens"] = max_tokens + + if tools: + kwargs["tools"] = tools + + # Provider-specific extra_body + merged_extra = dict(extra_body or {}) + if provider == "nous" or auxiliary_is_nous: + merged_extra.setdefault("tags", []).extend(["product=hermes-agent"]) + if merged_extra: + kwargs["extra_body"] = merged_extra + + return kwargs + + +def _validate_llm_response(response: Any, task: str = None) -> Any: + """Validate that an LLM response has the expected .choices[0].message shape. + + Fails fast with a clear error instead of letting malformed payloads + propagate to downstream consumers where they crash with misleading + AttributeError (e.g. "'str' object has no attribute 'choices'"). + + See #7264. + """ + if response is None: + raise RuntimeError( + f"Auxiliary {task or 'call'}: LLM returned None response" + ) + # Allow SimpleNamespace responses from adapters (CodexAuxiliaryClient, + # AnthropicAuxiliaryClient) — they have .choices[0].message. + try: + choices = response.choices + if not choices or not hasattr(choices[0], "message"): + raise AttributeError("missing choices[0].message") + except (AttributeError, TypeError, IndexError) as exc: + response_type = type(response).__name__ + response_preview = str(response)[:120] + raise RuntimeError( + f"Auxiliary {task or 'call'}: LLM returned invalid response " + f"(type={response_type}): {response_preview!r}. " + f"Expected object with .choices[0].message — check provider " + f"adapter or custom endpoint compatibility." + ) from exc + return response + + +def call_llm( + task: str = None, + *, + provider: str = None, + model: str = None, + base_url: str = None, + api_key: str = None, + main_runtime: Optional[Dict[str, Any]] = None, + messages: list, + temperature: float = None, + max_tokens: int = None, + tools: list = None, + timeout: float = None, + extra_body: dict = None, +) -> Any: + """Centralized synchronous LLM call. + + Resolves provider + model (from task config, explicit args, or auto-detect), + handles auth, request formatting, and model-specific arg adjustments. + + Args: + task: Auxiliary task name ("compression", "vision", "web_extract", + "session_search", "skills_hub", "mcp", "flush_memories"). + Reads provider:model from config/env. Ignored if provider is set. + provider: Explicit provider override. + model: Explicit model override. + messages: Chat messages list. + temperature: Sampling temperature (None = provider default). + max_tokens: Max output tokens (handles max_tokens vs max_completion_tokens). + tools: Tool definitions (for function calling). + timeout: Request timeout in seconds (None = read from auxiliary.{task}.timeout config). + extra_body: Additional request body fields. + + Returns: + Response object with .choices[0].message.content + + Raises: + RuntimeError: If no provider is configured. + """ + resolved_provider, resolved_model, resolved_base_url, resolved_api_key, resolved_api_mode = _resolve_task_provider_model( + task, provider, model, base_url, api_key) + + if task == "vision": + effective_provider, client, final_model = resolve_vision_provider_client( + provider=provider, + model=model, + base_url=base_url, + api_key=api_key, + async_mode=False, + ) + if client is None and resolved_provider != "auto" and not resolved_base_url: + logger.warning( + "Vision provider %s unavailable, falling back to auto vision backends", + resolved_provider, + ) + effective_provider, client, final_model = resolve_vision_provider_client( + provider="auto", + model=resolved_model, + async_mode=False, + ) + if client is None: + raise RuntimeError( + f"No LLM provider configured for task={task} provider={resolved_provider}. " + f"Run: hermes setup" + ) + resolved_provider = effective_provider or resolved_provider + else: + client, final_model = _get_cached_client( + resolved_provider, + resolved_model, + base_url=resolved_base_url, + api_key=resolved_api_key, + api_mode=resolved_api_mode, + main_runtime=main_runtime, + ) + if client is None: + # When the user explicitly chose a non-OpenRouter provider but no + # credentials were found, fail fast instead of silently routing + # through OpenRouter (which causes confusing 404s). + _explicit = (resolved_provider or "").strip().lower() + if _explicit and _explicit not in ("auto", "openrouter", "custom"): + raise RuntimeError( + f"Provider '{_explicit}' is set in config.yaml but no API key " + f"was found. Set the {_explicit.upper()}_API_KEY environment " + f"variable, or switch to a different provider with `hermes model`." + ) + # For auto/custom with no credentials, try the full auto chain + # rather than hardcoding OpenRouter (which may be depleted). + # Pass model=None so each provider uses its own default — + # resolved_model may be an OpenRouter-format slug that doesn't + # work on other providers. + if not resolved_base_url: + logger.info("Auxiliary %s: provider %s unavailable, trying auto-detection chain", + task or "call", resolved_provider) + client, final_model = _get_cached_client("auto", main_runtime=main_runtime) + if client is None: + raise RuntimeError( + f"No LLM provider configured for task={task} provider={resolved_provider}. " + f"Run: hermes setup") + + effective_timeout = timeout if timeout is not None else _get_task_timeout(task) + + # Log what we're about to do — makes auxiliary operations visible + _base_info = str(getattr(client, "base_url", resolved_base_url) or "") + if task: + logger.info("Auxiliary %s: using %s (%s)%s", + task, resolved_provider or "auto", final_model or "default", + f" at {_base_info}" if _base_info and "openrouter" not in _base_info else "") + + kwargs = _build_call_kwargs( + resolved_provider, final_model, messages, + temperature=temperature, max_tokens=max_tokens, + tools=tools, timeout=effective_timeout, extra_body=extra_body, + base_url=resolved_base_url) + + # Convert image blocks for Anthropic-compatible endpoints (e.g. MiniMax) + _client_base = str(getattr(client, "base_url", "") or "") + if _is_anthropic_compat_endpoint(resolved_provider, _client_base): + kwargs["messages"] = _convert_openai_images_to_anthropic(kwargs["messages"]) + + # Handle max_tokens vs max_completion_tokens retry, then payment fallback. + try: + return _validate_llm_response( + client.chat.completions.create(**kwargs), task) + except Exception as first_err: + err_str = str(first_err) + if "max_tokens" in err_str or "unsupported_parameter" in err_str: + kwargs.pop("max_tokens", None) + kwargs["max_completion_tokens"] = max_tokens + try: + return _validate_llm_response( + client.chat.completions.create(**kwargs), task) + except Exception as retry_err: + # If the max_tokens retry also hits a payment or connection + # error, fall through to the fallback chain below. + if not (_is_payment_error(retry_err) or _is_connection_error(retry_err)): + raise + first_err = retry_err + + # ── Payment / credit exhaustion fallback ────────────────────── + # When the resolved provider returns 402 or a credit-related error, + # try alternative providers instead of giving up. This handles the + # common case where a user runs out of OpenRouter credits but has + # Codex OAuth or another provider available. + # + # ── Connection error fallback ──────────────────────────────── + # When a provider endpoint is unreachable (DNS failure, connection + # refused, timeout), try alternative providers. This handles stale + # Codex/OAuth tokens that authenticate but whose endpoint is down, + # and providers the user never configured that got picked up by + # the auto-detection chain. + should_fallback = _is_payment_error(first_err) or _is_connection_error(first_err) + # Only try alternative providers when the user didn't explicitly + # configure this task's provider. Explicit provider = hard constraint; + # auto (the default) = best-effort fallback chain. (#7559) + is_auto = resolved_provider in ("auto", "", None) + if should_fallback and is_auto: + reason = "payment error" if _is_payment_error(first_err) else "connection error" + logger.info("Auxiliary %s: %s on %s (%s), trying fallback", + task or "call", reason, resolved_provider, first_err) + fb_client, fb_model, fb_label = _try_payment_fallback( + resolved_provider, task, reason=reason) + if fb_client is not None: + fb_kwargs = _build_call_kwargs( + fb_label, fb_model, messages, + temperature=temperature, max_tokens=max_tokens, + tools=tools, timeout=effective_timeout, + extra_body=extra_body) + return _validate_llm_response( + fb_client.chat.completions.create(**fb_kwargs), task) + raise + + +def extract_content_or_reasoning(response) -> str: + """Extract content from an LLM response, falling back to reasoning fields. + + Mirrors the main agent loop's behavior when a reasoning model (DeepSeek-R1, + Qwen-QwQ, etc.) returns ``content=None`` with reasoning in structured fields. + + Resolution order: + 1. ``message.content`` — strip inline think/reasoning blocks, check for + remaining non-whitespace text. + 2. ``message.reasoning`` / ``message.reasoning_content`` — direct + structured reasoning fields (DeepSeek, Moonshot, Novita, etc.). + 3. ``message.reasoning_details`` — OpenRouter unified array format. + + Returns the best available text, or ``""`` if nothing found. + """ + import re + + msg = response.choices[0].message + content = (msg.content or "").strip() + + if content: + # Strip inline think/reasoning blocks (mirrors _strip_think_blocks) + cleaned = re.sub( + r"<(?:think|thinking|reasoning|thought|REASONING_SCRATCHPAD)>" + r".*?" + r"", + "", content, flags=re.DOTALL | re.IGNORECASE, + ).strip() + if cleaned: + return cleaned + + # Content is empty or reasoning-only — try structured reasoning fields + reasoning_parts: list[str] = [] + for field in ("reasoning", "reasoning_content"): + val = getattr(msg, field, None) + if val and isinstance(val, str) and val.strip() and val not in reasoning_parts: + reasoning_parts.append(val.strip()) + + details = getattr(msg, "reasoning_details", None) + if details and isinstance(details, list): + for detail in details: + if isinstance(detail, dict): + summary = ( + detail.get("summary") + or detail.get("content") + or detail.get("text") + ) + if summary and summary not in reasoning_parts: + reasoning_parts.append(summary.strip() if isinstance(summary, str) else str(summary)) + + if reasoning_parts: + return "\n\n".join(reasoning_parts) + + return "" + + +async def async_call_llm( + task: str = None, + *, + provider: str = None, + model: str = None, + base_url: str = None, + api_key: str = None, + messages: list, + temperature: float = None, + max_tokens: int = None, + tools: list = None, + timeout: float = None, + extra_body: dict = None, +) -> Any: + """Centralized asynchronous LLM call. + + Same as call_llm() but async. See call_llm() for full documentation. + """ + resolved_provider, resolved_model, resolved_base_url, resolved_api_key, resolved_api_mode = _resolve_task_provider_model( + task, provider, model, base_url, api_key) + + if task == "vision": + effective_provider, client, final_model = resolve_vision_provider_client( + provider=provider, + model=model, + base_url=base_url, + api_key=api_key, + async_mode=True, + ) + if client is None and resolved_provider != "auto" and not resolved_base_url: + logger.warning( + "Vision provider %s unavailable, falling back to auto vision backends", + resolved_provider, + ) + effective_provider, client, final_model = resolve_vision_provider_client( + provider="auto", + model=resolved_model, + async_mode=True, + ) + if client is None: + raise RuntimeError( + f"No LLM provider configured for task={task} provider={resolved_provider}. " + f"Run: hermes setup" + ) + resolved_provider = effective_provider or resolved_provider + else: + client, final_model = _get_cached_client( + resolved_provider, + resolved_model, + async_mode=True, + base_url=resolved_base_url, + api_key=resolved_api_key, + api_mode=resolved_api_mode, + ) + if client is None: + _explicit = (resolved_provider or "").strip().lower() + if _explicit and _explicit not in ("auto", "openrouter", "custom"): + raise RuntimeError( + f"Provider '{_explicit}' is set in config.yaml but no API key " + f"was found. Set the {_explicit.upper()}_API_KEY environment " + f"variable, or switch to a different provider with `hermes model`." + ) + if not resolved_base_url: + logger.info("Auxiliary %s: provider %s unavailable, trying auto-detection chain", + task or "call", resolved_provider) + client, final_model = _get_cached_client("auto", async_mode=True) + if client is None: + raise RuntimeError( + f"No LLM provider configured for task={task} provider={resolved_provider}. " + f"Run: hermes setup") + + effective_timeout = timeout if timeout is not None else _get_task_timeout(task) + + kwargs = _build_call_kwargs( + resolved_provider, final_model, messages, + temperature=temperature, max_tokens=max_tokens, + tools=tools, timeout=effective_timeout, extra_body=extra_body, + base_url=resolved_base_url) + + # Convert image blocks for Anthropic-compatible endpoints (e.g. MiniMax) + _client_base = str(getattr(client, "base_url", "") or "") + if _is_anthropic_compat_endpoint(resolved_provider, _client_base): + kwargs["messages"] = _convert_openai_images_to_anthropic(kwargs["messages"]) + + try: + return _validate_llm_response( + await client.chat.completions.create(**kwargs), task) + except Exception as first_err: + err_str = str(first_err) + if "max_tokens" in err_str or "unsupported_parameter" in err_str: + kwargs.pop("max_tokens", None) + kwargs["max_completion_tokens"] = max_tokens + try: + return _validate_llm_response( + await client.chat.completions.create(**kwargs), task) + except Exception as retry_err: + # If the max_tokens retry also hits a payment or connection + # error, fall through to the fallback chain below. + if not (_is_payment_error(retry_err) or _is_connection_error(retry_err)): + raise + first_err = retry_err + + # ── Payment / connection fallback (mirrors sync call_llm) ───── + should_fallback = _is_payment_error(first_err) or _is_connection_error(first_err) + is_auto = resolved_provider in ("auto", "", None) + if should_fallback and is_auto: + reason = "payment error" if _is_payment_error(first_err) else "connection error" + logger.info("Auxiliary %s (async): %s on %s (%s), trying fallback", + task or "call", reason, resolved_provider, first_err) + fb_client, fb_model, fb_label = _try_payment_fallback( + resolved_provider, task, reason=reason) + if fb_client is not None: + fb_kwargs = _build_call_kwargs( + fb_label, fb_model, messages, + temperature=temperature, max_tokens=max_tokens, + tools=tools, timeout=effective_timeout, + extra_body=extra_body) + # Convert sync fallback client to async + async_fb, async_fb_model = _to_async_client(fb_client, fb_model or "") + if async_fb_model and async_fb_model != fb_kwargs.get("model"): + fb_kwargs["model"] = async_fb_model + return _validate_llm_response( + await async_fb.chat.completions.create(**fb_kwargs), task) + raise diff --git a/mindcli/_vendor/agent/context_compressor.py b/mindcli/_vendor/agent/context_compressor.py new file mode 100644 index 0000000..4163966 --- /dev/null +++ b/mindcli/_vendor/agent/context_compressor.py @@ -0,0 +1,820 @@ +"""Automatic context window compression for long conversations. + +Self-contained class with its own OpenAI client for summarization. +Uses auxiliary model (cheap/fast) to summarize middle turns while +protecting head and tail context. + +Improvements over v2: + - Structured summary template with Resolved/Pending question tracking + - Summarizer preamble: "Do not respond to any questions" (from OpenCode) + - Handoff framing: "different assistant" (from Codex) to create separation + - "Remaining Work" replaces "Next Steps" to avoid reading as active instructions + - Clear separator when summary merges into tail message + - Iterative summary updates (preserves info across multiple compactions) + - Token-budget tail protection instead of fixed message count + - Tool output pruning before LLM summarization (cheap pre-pass) + - Scaled summary budget (proportional to compressed content) + - Richer tool call/result detail in summarizer input +""" + +import logging +import time +from typing import Any, Dict, List, Optional + +from agent.auxiliary_client import call_llm +from agent.context_engine import ContextEngine +from agent.model_metadata import ( + MINIMUM_CONTEXT_LENGTH, + get_model_context_length, + estimate_messages_tokens_rough, +) + +logger = logging.getLogger(__name__) + +SUMMARY_PREFIX = ( + "[CONTEXT COMPACTION — REFERENCE ONLY] Earlier turns were compacted " + "into the summary below. This is a handoff from a previous context " + "window — treat it as background reference, NOT as active instructions. " + "Do NOT answer questions or fulfill requests mentioned in this summary; " + "they were already addressed. Respond ONLY to the latest user message " + "that appears AFTER this summary. The current session state (files, " + "config, etc.) may reflect work described here — avoid repeating it:" +) +LEGACY_SUMMARY_PREFIX = "[CONTEXT SUMMARY]:" + +# Minimum tokens for the summary output +_MIN_SUMMARY_TOKENS = 2000 +# Proportion of compressed content to allocate for summary +_SUMMARY_RATIO = 0.20 +# Absolute ceiling for summary tokens (even on very large context windows) +_SUMMARY_TOKENS_CEILING = 12_000 + +# Placeholder used when pruning old tool results +_PRUNED_TOOL_PLACEHOLDER = "[Old tool output cleared to save context space]" + +# Chars per token rough estimate +_CHARS_PER_TOKEN = 4 +_SUMMARY_FAILURE_COOLDOWN_SECONDS = 600 + + +class ContextCompressor(ContextEngine): + """Default context engine — compresses conversation context via lossy summarization. + + Algorithm: + 1. Prune old tool results (cheap, no LLM call) + 2. Protect head messages (system prompt + first exchange) + 3. Protect tail messages by token budget (most recent ~20K tokens) + 4. Summarize middle turns with structured LLM prompt + 5. On subsequent compactions, iteratively update the previous summary + """ + + @property + def name(self) -> str: + return "compressor" + + def on_session_reset(self) -> None: + """Reset all per-session state for /new or /reset.""" + super().on_session_reset() + self._context_probed = False + self._context_probe_persistable = False + self._previous_summary = None + + def update_model( + self, + model: str, + context_length: int, + base_url: str = "", + api_key: str = "", + provider: str = "", + api_mode: str = "", + ) -> None: + """Update model info after a model switch or fallback activation.""" + self.model = model + self.base_url = base_url + self.api_key = api_key + self.provider = provider + self.api_mode = api_mode + self.context_length = context_length + self.threshold_tokens = max( + int(context_length * self.threshold_percent), + MINIMUM_CONTEXT_LENGTH, + ) + + def __init__( + self, + model: str, + threshold_percent: float = 0.50, + protect_first_n: int = 3, + protect_last_n: int = 20, + summary_target_ratio: float = 0.20, + quiet_mode: bool = False, + summary_model_override: str = None, + base_url: str = "", + api_key: str = "", + config_context_length: int | None = None, + provider: str = "", + api_mode: str = "", + ): + self.model = model + self.base_url = base_url + self.api_key = api_key + self.provider = provider + self.api_mode = api_mode + self.threshold_percent = threshold_percent + self.protect_first_n = protect_first_n + self.protect_last_n = protect_last_n + self.summary_target_ratio = max(0.10, min(summary_target_ratio, 0.80)) + self.quiet_mode = quiet_mode + + self.context_length = get_model_context_length( + model, base_url=base_url, api_key=api_key, + config_context_length=config_context_length, + provider=provider, + ) + # Floor: never compress below MINIMUM_CONTEXT_LENGTH tokens even if + # the percentage would suggest a lower value. This prevents premature + # compression on large-context models at 50% while keeping the % sane + # for models right at the minimum. + self.threshold_tokens = max( + int(self.context_length * threshold_percent), + MINIMUM_CONTEXT_LENGTH, + ) + self.compression_count = 0 + + # Derive token budgets: ratio is relative to the threshold, not total context + target_tokens = int(self.threshold_tokens * self.summary_target_ratio) + self.tail_token_budget = target_tokens + self.max_summary_tokens = min( + int(self.context_length * 0.05), _SUMMARY_TOKENS_CEILING, + ) + + if not quiet_mode: + logger.info( + "Context compressor initialized: model=%s context_length=%d " + "threshold=%d (%.0f%%) target_ratio=%.0f%% tail_budget=%d " + "provider=%s base_url=%s", + model, self.context_length, self.threshold_tokens, + threshold_percent * 100, self.summary_target_ratio * 100, + self.tail_token_budget, + provider or "none", base_url or "none", + ) + self._context_probed = False # True after a step-down from context error + + self.last_prompt_tokens = 0 + self.last_completion_tokens = 0 + + self.summary_model = summary_model_override or "" + + # Stores the previous compaction summary for iterative updates + self._previous_summary: Optional[str] = None + self._summary_failure_cooldown_until: float = 0.0 + + def update_from_response(self, usage: Dict[str, Any]): + """Update tracked token usage from API response.""" + self.last_prompt_tokens = usage.get("prompt_tokens", 0) + self.last_completion_tokens = usage.get("completion_tokens", 0) + + def should_compress(self, prompt_tokens: int = None) -> bool: + """Check if context exceeds the compression threshold.""" + tokens = prompt_tokens if prompt_tokens is not None else self.last_prompt_tokens + return tokens >= self.threshold_tokens + + # ------------------------------------------------------------------ + # Tool output pruning (cheap pre-pass, no LLM call) + # ------------------------------------------------------------------ + + def _prune_old_tool_results( + self, messages: List[Dict[str, Any]], protect_tail_count: int, + protect_tail_tokens: int | None = None, + ) -> tuple[List[Dict[str, Any]], int]: + """Replace old tool result contents with a short placeholder. + + Walks backward from the end, protecting the most recent messages that + fall within ``protect_tail_tokens`` (when provided) OR the last + ``protect_tail_count`` messages (backward-compatible default). + When both are given, the token budget takes priority and the message + count acts as a hard minimum floor. + + Returns (pruned_messages, pruned_count). + """ + if not messages: + return messages, 0 + + result = [m.copy() for m in messages] + pruned = 0 + + # Determine the prune boundary + if protect_tail_tokens is not None and protect_tail_tokens > 0: + # Token-budget approach: walk backward accumulating tokens + accumulated = 0 + boundary = len(result) + min_protect = min(protect_tail_count, len(result) - 1) + for i in range(len(result) - 1, -1, -1): + msg = result[i] + content_len = len(msg.get("content") or "") + msg_tokens = content_len // _CHARS_PER_TOKEN + 10 + for tc in msg.get("tool_calls") or []: + if isinstance(tc, dict): + args = tc.get("function", {}).get("arguments", "") + msg_tokens += len(args) // _CHARS_PER_TOKEN + if accumulated + msg_tokens > protect_tail_tokens and (len(result) - i) >= min_protect: + boundary = i + break + accumulated += msg_tokens + boundary = i + prune_boundary = max(boundary, len(result) - min_protect) + else: + prune_boundary = len(result) - protect_tail_count + + for i in range(prune_boundary): + msg = result[i] + if msg.get("role") != "tool": + continue + content = msg.get("content", "") + if not content or content == _PRUNED_TOOL_PLACEHOLDER: + continue + # Only prune if the content is substantial (>200 chars) + if len(content) > 200: + result[i] = {**msg, "content": _PRUNED_TOOL_PLACEHOLDER} + pruned += 1 + + return result, pruned + + # ------------------------------------------------------------------ + # Summarization + # ------------------------------------------------------------------ + + def _compute_summary_budget(self, turns_to_summarize: List[Dict[str, Any]]) -> int: + """Scale summary token budget with the amount of content being compressed. + + The maximum scales with the model's context window (5% of context, + capped at ``_SUMMARY_TOKENS_CEILING``) so large-context models get + richer summaries instead of being hard-capped at 8K tokens. + """ + content_tokens = estimate_messages_tokens_rough(turns_to_summarize) + budget = int(content_tokens * _SUMMARY_RATIO) + return max(_MIN_SUMMARY_TOKENS, min(budget, self.max_summary_tokens)) + + # Truncation limits for the summarizer input. These bound how much of + # each message the summary model sees — the budget is the *summary* + # model's context window, not the main model's. + _CONTENT_MAX = 6000 # total chars per message body + _CONTENT_HEAD = 4000 # chars kept from the start + _CONTENT_TAIL = 1500 # chars kept from the end + _TOOL_ARGS_MAX = 1500 # tool call argument chars + _TOOL_ARGS_HEAD = 1200 # kept from the start of tool args + + def _serialize_for_summary(self, turns: List[Dict[str, Any]]) -> str: + """Serialize conversation turns into labeled text for the summarizer. + + Includes tool call arguments and result content (up to + ``_CONTENT_MAX`` chars per message) so the summarizer can preserve + specific details like file paths, commands, and outputs. + """ + parts = [] + for msg in turns: + role = msg.get("role", "unknown") + content = msg.get("content") or "" + + # Tool results: keep enough content for the summarizer + if role == "tool": + tool_id = msg.get("tool_call_id", "") + if len(content) > self._CONTENT_MAX: + content = content[:self._CONTENT_HEAD] + "\n...[truncated]...\n" + content[-self._CONTENT_TAIL:] + parts.append(f"[TOOL RESULT {tool_id}]: {content}") + continue + + # Assistant messages: include tool call names AND arguments + if role == "assistant": + if len(content) > self._CONTENT_MAX: + content = content[:self._CONTENT_HEAD] + "\n...[truncated]...\n" + content[-self._CONTENT_TAIL:] + tool_calls = msg.get("tool_calls", []) + if tool_calls: + tc_parts = [] + for tc in tool_calls: + if isinstance(tc, dict): + fn = tc.get("function", {}) + name = fn.get("name", "?") + args = fn.get("arguments", "") + # Truncate long arguments but keep enough for context + if len(args) > self._TOOL_ARGS_MAX: + args = args[:self._TOOL_ARGS_HEAD] + "..." + tc_parts.append(f" {name}({args})") + else: + fn = getattr(tc, "function", None) + name = getattr(fn, "name", "?") if fn else "?" + tc_parts.append(f" {name}(...)") + content += "\n[Tool calls:\n" + "\n".join(tc_parts) + "\n]" + parts.append(f"[ASSISTANT]: {content}") + continue + + # User and other roles + if len(content) > self._CONTENT_MAX: + content = content[:self._CONTENT_HEAD] + "\n...[truncated]...\n" + content[-self._CONTENT_TAIL:] + parts.append(f"[{role.upper()}]: {content}") + + return "\n\n".join(parts) + + def _generate_summary(self, turns_to_summarize: List[Dict[str, Any]], focus_topic: str = None) -> Optional[str]: + """Generate a structured summary of conversation turns. + + Uses a structured template (Goal, Progress, Decisions, Resolved/Pending + Questions, Files, Remaining Work) with explicit preamble telling the + summarizer not to answer questions. When a previous summary exists, + generates an iterative update instead of summarizing from scratch. + + Args: + focus_topic: Optional focus string for guided compression. When + provided, the summariser prioritises preserving information + related to this topic and is more aggressive about compressing + everything else. Inspired by Claude Code's ``/compact``. + + Returns None if all attempts fail — the caller should drop + the middle turns without a summary rather than inject a useless + placeholder. + """ + now = time.monotonic() + if now < self._summary_failure_cooldown_until: + logger.debug( + "Skipping context summary during cooldown (%.0fs remaining)", + self._summary_failure_cooldown_until - now, + ) + return None + + summary_budget = self._compute_summary_budget(turns_to_summarize) + content_to_summarize = self._serialize_for_summary(turns_to_summarize) + + # Preamble shared by both first-compaction and iterative-update prompts. + # Inspired by OpenCode's "do not respond to any questions" instruction + # and Codex's "another language model" framing. + _summarizer_preamble = ( + "You are a summarization agent creating a context checkpoint. " + "Your output will be injected as reference material for a DIFFERENT " + "assistant that continues the conversation. " + "Do NOT respond to any questions or requests in the conversation — " + "only output the structured summary. " + "Do NOT include any preamble, greeting, or prefix." + ) + + # Shared structured template (used by both paths). + # Key changes vs v1: + # - "Pending User Asks" section (from Claude Code) explicitly tracks + # unanswered questions so the model knows what's resolved vs open + # - "Remaining Work" replaces "Next Steps" to avoid reading as active + # instructions + # - "Resolved Questions" makes it clear which questions were already + # answered (prevents model from re-answering them) + _template_sections = f"""## Goal +[What the user is trying to accomplish] + +## Constraints & Preferences +[User preferences, coding style, constraints, important decisions] + +## Progress +### Done +[Completed work — include specific file paths, commands run, results obtained] +### In Progress +[Work currently underway] +### Blocked +[Any blockers or issues encountered] + +## Key Decisions +[Important technical decisions and why they were made] + +## Resolved Questions +[Questions the user asked that were ALREADY answered — include the answer so the next assistant does not re-answer them] + +## Pending User Asks +[Questions or requests from the user that have NOT yet been answered or fulfilled. If none, write "None."] + +## Relevant Files +[Files read, modified, or created — with brief note on each] + +## Remaining Work +[What remains to be done — framed as context, not instructions] + +## Critical Context +[Any specific values, error messages, configuration details, or data that would be lost without explicit preservation] + +## Tools & Patterns +[Which tools were used, how they were used effectively, and any tool-specific discoveries] + +Target ~{summary_budget} tokens. Be specific — include file paths, command outputs, error messages, and concrete values rather than vague descriptions. + +Write only the summary body. Do not include any preamble or prefix.""" + + if self._previous_summary: + # Iterative update: preserve existing info, add new progress + prompt = f"""{_summarizer_preamble} + +You are updating a context compaction summary. A previous compaction produced the summary below. New conversation turns have occurred since then and need to be incorporated. + +PREVIOUS SUMMARY: +{self._previous_summary} + +NEW TURNS TO INCORPORATE: +{content_to_summarize} + +Update the summary using this exact structure. PRESERVE all existing information that is still relevant. ADD new progress. Move items from "In Progress" to "Done" when completed. Move answered questions to "Resolved Questions". Remove information only if it is clearly obsolete. + +{_template_sections}""" + else: + # First compaction: summarize from scratch + prompt = f"""{_summarizer_preamble} + +Create a structured handoff summary for a different assistant that will continue this conversation after earlier turns are compacted. The next assistant should be able to understand what happened without re-reading the original turns. + +TURNS TO SUMMARIZE: +{content_to_summarize} + +Use this exact structure: + +{_template_sections}""" + + # Inject focus topic guidance when the user provides one via /compress . + # This goes at the end of the prompt so it takes precedence. + if focus_topic: + prompt += f""" + +FOCUS TOPIC: "{focus_topic}" +The user has requested that this compaction PRIORITISE preserving all information related to the focus topic above. For content related to "{focus_topic}", include full detail — exact values, file paths, command outputs, error messages, and decisions. For content NOT related to the focus topic, summarise more aggressively (brief one-liners or omit if truly irrelevant). The focus topic sections should receive roughly 60-70% of the summary token budget.""" + + try: + call_kwargs = { + "task": "compression", + "main_runtime": { + "model": self.model, + "provider": self.provider, + "base_url": self.base_url, + "api_key": self.api_key, + "api_mode": self.api_mode, + }, + "messages": [{"role": "user", "content": prompt}], + "max_tokens": summary_budget * 2, + # timeout resolved from auxiliary.compression.timeout config by call_llm + } + if self.summary_model: + call_kwargs["model"] = self.summary_model + response = call_llm(**call_kwargs) + content = response.choices[0].message.content + # Handle cases where content is not a string (e.g., dict from llama.cpp) + if not isinstance(content, str): + content = str(content) if content else "" + summary = content.strip() + # Store for iterative updates on next compaction + self._previous_summary = summary + self._summary_failure_cooldown_until = 0.0 + return self._with_summary_prefix(summary) + except RuntimeError: + self._summary_failure_cooldown_until = time.monotonic() + _SUMMARY_FAILURE_COOLDOWN_SECONDS + logging.warning("Context compression: no provider available for " + "summary. Middle turns will be dropped without summary " + "for %d seconds.", + _SUMMARY_FAILURE_COOLDOWN_SECONDS) + return None + except Exception as e: + self._summary_failure_cooldown_until = time.monotonic() + _SUMMARY_FAILURE_COOLDOWN_SECONDS + logging.warning( + "Failed to generate context summary: %s. " + "Further summary attempts paused for %d seconds.", + e, + _SUMMARY_FAILURE_COOLDOWN_SECONDS, + ) + return None + + @staticmethod + def _with_summary_prefix(summary: str) -> str: + """Normalize summary text to the current compaction handoff format.""" + text = (summary or "").strip() + for prefix in (LEGACY_SUMMARY_PREFIX, SUMMARY_PREFIX): + if text.startswith(prefix): + text = text[len(prefix):].lstrip() + break + return f"{SUMMARY_PREFIX}\n{text}" if text else SUMMARY_PREFIX + + # ------------------------------------------------------------------ + # Tool-call / tool-result pair integrity helpers + # ------------------------------------------------------------------ + + @staticmethod + def _get_tool_call_id(tc) -> str: + """Extract the call ID from a tool_call entry (dict or SimpleNamespace).""" + if isinstance(tc, dict): + return tc.get("id", "") + return getattr(tc, "id", "") or "" + + def _sanitize_tool_pairs(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]: + """Fix orphaned tool_call / tool_result pairs after compression. + + Two failure modes: + 1. A tool *result* references a call_id whose assistant tool_call was + removed (summarized/truncated). The API rejects this with + "No tool call found for function call output with call_id ...". + 2. An assistant message has tool_calls whose results were dropped. + The API rejects this because every tool_call must be followed by + a tool result with the matching call_id. + + This method removes orphaned results and inserts stub results for + orphaned calls so the message list is always well-formed. + """ + surviving_call_ids: set = set() + for msg in messages: + if msg.get("role") == "assistant": + for tc in msg.get("tool_calls") or []: + cid = self._get_tool_call_id(tc) + if cid: + surviving_call_ids.add(cid) + + result_call_ids: set = set() + for msg in messages: + if msg.get("role") == "tool": + cid = msg.get("tool_call_id") + if cid: + result_call_ids.add(cid) + + # 1. Remove tool results whose call_id has no matching assistant tool_call + orphaned_results = result_call_ids - surviving_call_ids + if orphaned_results: + messages = [ + m for m in messages + if not (m.get("role") == "tool" and m.get("tool_call_id") in orphaned_results) + ] + if not self.quiet_mode: + logger.info("Compression sanitizer: removed %d orphaned tool result(s)", len(orphaned_results)) + + # 2. Add stub results for assistant tool_calls whose results were dropped + missing_results = surviving_call_ids - result_call_ids + if missing_results: + patched: List[Dict[str, Any]] = [] + for msg in messages: + patched.append(msg) + if msg.get("role") == "assistant": + for tc in msg.get("tool_calls") or []: + cid = self._get_tool_call_id(tc) + if cid in missing_results: + patched.append({ + "role": "tool", + "content": "[Result from earlier conversation — see context summary above]", + "tool_call_id": cid, + }) + messages = patched + if not self.quiet_mode: + logger.info("Compression sanitizer: added %d stub tool result(s)", len(missing_results)) + + return messages + + def _align_boundary_forward(self, messages: List[Dict[str, Any]], idx: int) -> int: + """Push a compress-start boundary forward past any orphan tool results. + + If ``messages[idx]`` is a tool result, slide forward until we hit a + non-tool message so we don't start the summarised region mid-group. + """ + while idx < len(messages) and messages[idx].get("role") == "tool": + idx += 1 + return idx + + def _align_boundary_backward(self, messages: List[Dict[str, Any]], idx: int) -> int: + """Pull a compress-end boundary backward to avoid splitting a + tool_call / result group. + + If the boundary falls in the middle of a tool-result group (i.e. + there are consecutive tool messages before ``idx``), walk backward + past all of them to find the parent assistant message. If found, + move the boundary before the assistant so the entire + assistant + tool_results group is included in the summarised region + rather than being split (which causes silent data loss when + ``_sanitize_tool_pairs`` removes the orphaned tail results). + """ + if idx <= 0 or idx >= len(messages): + return idx + # Walk backward past consecutive tool results + check = idx - 1 + while check >= 0 and messages[check].get("role") == "tool": + check -= 1 + # If we landed on the parent assistant with tool_calls, pull the + # boundary before it so the whole group gets summarised together. + if check >= 0 and messages[check].get("role") == "assistant" and messages[check].get("tool_calls"): + idx = check + return idx + + # ------------------------------------------------------------------ + # Tail protection by token budget + # ------------------------------------------------------------------ + + def _find_tail_cut_by_tokens( + self, messages: List[Dict[str, Any]], head_end: int, + token_budget: int | None = None, + ) -> int: + """Walk backward from the end of messages, accumulating tokens until + the budget is reached. Returns the index where the tail starts. + + ``token_budget`` defaults to ``self.tail_token_budget`` which is + derived from ``summary_target_ratio * context_length``, so it + scales automatically with the model's context window. + + Token budget is the primary criterion. A hard minimum of 3 messages + is always protected, but the budget is allowed to exceed by up to + 1.5x to avoid cutting inside an oversized message (tool output, file + read, etc.). If even the minimum 3 messages exceed 1.5x the budget + the cut is placed right after the head so compression still runs. + + Never cuts inside a tool_call/result group. + """ + if token_budget is None: + token_budget = self.tail_token_budget + n = len(messages) + # Hard minimum: always keep at least 3 messages in the tail + min_tail = min(3, n - head_end - 1) if n - head_end > 1 else 0 + soft_ceiling = int(token_budget * 1.5) + accumulated = 0 + cut_idx = n # start from beyond the end + + for i in range(n - 1, head_end - 1, -1): + msg = messages[i] + content = msg.get("content") or "" + msg_tokens = len(content) // _CHARS_PER_TOKEN + 10 # +10 for role/metadata + # Include tool call arguments in estimate + for tc in msg.get("tool_calls") or []: + if isinstance(tc, dict): + args = tc.get("function", {}).get("arguments", "") + msg_tokens += len(args) // _CHARS_PER_TOKEN + # Stop once we exceed the soft ceiling (unless we haven't hit min_tail yet) + if accumulated + msg_tokens > soft_ceiling and (n - i) >= min_tail: + break + accumulated += msg_tokens + cut_idx = i + + # Ensure we protect at least min_tail messages + fallback_cut = n - min_tail + if cut_idx > fallback_cut: + cut_idx = fallback_cut + + # If the token budget would protect everything (small conversations), + # force a cut after the head so compression can still remove middle turns. + if cut_idx <= head_end: + cut_idx = max(fallback_cut, head_end + 1) + + # Align to avoid splitting tool groups + cut_idx = self._align_boundary_backward(messages, cut_idx) + + return max(cut_idx, head_end + 1) + + # ------------------------------------------------------------------ + # Main compression entry point + # ------------------------------------------------------------------ + + def compress(self, messages: List[Dict[str, Any]], current_tokens: int = None, focus_topic: str = None) -> List[Dict[str, Any]]: + """Compress conversation messages by summarizing middle turns. + + Algorithm: + 1. Prune old tool results (cheap pre-pass, no LLM call) + 2. Protect head messages (system prompt + first exchange) + 3. Find tail boundary by token budget (~20K tokens of recent context) + 4. Summarize middle turns with structured LLM prompt + 5. On re-compression, iteratively update the previous summary + + After compression, orphaned tool_call / tool_result pairs are cleaned + up so the API never receives mismatched IDs. + + Args: + focus_topic: Optional focus string for guided compression. When + provided, the summariser will prioritise preserving information + related to this topic and be more aggressive about compressing + everything else. Inspired by Claude Code's ``/compact``. + """ + n_messages = len(messages) + # Only need head + 3 tail messages minimum (token budget decides the real tail size) + _min_for_compress = self.protect_first_n + 3 + 1 + if n_messages <= _min_for_compress: + if not self.quiet_mode: + logger.warning( + "Cannot compress: only %d messages (need > %d)", + n_messages, _min_for_compress, + ) + return messages + + display_tokens = current_tokens if current_tokens else self.last_prompt_tokens or estimate_messages_tokens_rough(messages) + + # Phase 1: Prune old tool results (cheap, no LLM call) + messages, pruned_count = self._prune_old_tool_results( + messages, protect_tail_count=self.protect_last_n, + protect_tail_tokens=self.tail_token_budget, + ) + if pruned_count and not self.quiet_mode: + logger.info("Pre-compression: pruned %d old tool result(s)", pruned_count) + + # Phase 2: Determine boundaries + compress_start = self.protect_first_n + compress_start = self._align_boundary_forward(messages, compress_start) + + # Use token-budget tail protection instead of fixed message count + compress_end = self._find_tail_cut_by_tokens(messages, compress_start) + + if compress_start >= compress_end: + return messages + + turns_to_summarize = messages[compress_start:compress_end] + + if not self.quiet_mode: + logger.info( + "Context compression triggered (%d tokens >= %d threshold)", + display_tokens, + self.threshold_tokens, + ) + logger.info( + "Model context limit: %d tokens (%.0f%% = %d)", + self.context_length, + self.threshold_percent * 100, + self.threshold_tokens, + ) + tail_msgs = n_messages - compress_end + logger.info( + "Summarizing turns %d-%d (%d turns), protecting %d head + %d tail messages", + compress_start + 1, + compress_end, + len(turns_to_summarize), + compress_start, + tail_msgs, + ) + + # Phase 3: Generate structured summary + summary = self._generate_summary(turns_to_summarize, focus_topic=focus_topic) + + # Phase 4: Assemble compressed message list + compressed = [] + for i in range(compress_start): + msg = messages[i].copy() + if i == 0 and msg.get("role") == "system" and self.compression_count == 0: + msg["content"] = ( + (msg.get("content") or "") + + "\n\n[Note: Some earlier conversation turns have been compacted into a handoff summary to preserve context space. The current session state may still reflect earlier work, so build on that summary and state rather than re-doing work.]" + ) + compressed.append(msg) + + # If LLM summary failed, insert a static fallback so the model + # knows context was lost rather than silently dropping everything. + if not summary: + if not self.quiet_mode: + logger.warning("Summary generation failed — inserting static fallback context marker") + n_dropped = compress_end - compress_start + summary = ( + f"{SUMMARY_PREFIX}\n" + f"Summary generation was unavailable. {n_dropped} conversation turns were " + f"removed to free context space but could not be summarized. The removed " + f"turns contained earlier work in this session. Continue based on the " + f"recent messages below and the current state of any files or resources." + ) + + _merge_summary_into_tail = False + last_head_role = messages[compress_start - 1].get("role", "user") if compress_start > 0 else "user" + first_tail_role = messages[compress_end].get("role", "user") if compress_end < n_messages else "user" + # Pick a role that avoids consecutive same-role with both neighbors. + # Priority: avoid colliding with head (already committed), then tail. + if last_head_role in ("assistant", "tool"): + summary_role = "user" + else: + summary_role = "assistant" + # If the chosen role collides with the tail AND flipping wouldn't + # collide with the head, flip it. + if summary_role == first_tail_role: + flipped = "assistant" if summary_role == "user" else "user" + if flipped != last_head_role: + summary_role = flipped + else: + # Both roles would create consecutive same-role messages + # (e.g. head=assistant, tail=user — neither role works). + # Merge the summary into the first tail message instead + # of inserting a standalone message that breaks alternation. + _merge_summary_into_tail = True + if not _merge_summary_into_tail: + compressed.append({"role": summary_role, "content": summary}) + + for i in range(compress_end, n_messages): + msg = messages[i].copy() + if _merge_summary_into_tail and i == compress_end: + original = msg.get("content") or "" + msg["content"] = ( + summary + + "\n\n--- END OF CONTEXT SUMMARY — " + "respond to the message below, not the summary above ---\n\n" + + original + ) + _merge_summary_into_tail = False + compressed.append(msg) + + self.compression_count += 1 + + compressed = self._sanitize_tool_pairs(compressed) + + if not self.quiet_mode: + new_estimate = estimate_messages_tokens_rough(compressed) + saved_estimate = display_tokens - new_estimate + logger.info( + "Compressed: %d -> %d messages (~%d tokens saved)", + n_messages, + len(compressed), + saved_estimate, + ) + logger.info("Compression #%d complete", self.compression_count) + + return compressed diff --git a/mindcli/_vendor/agent/context_engine.py b/mindcli/_vendor/agent/context_engine.py new file mode 100644 index 0000000..6ae90b6 --- /dev/null +++ b/mindcli/_vendor/agent/context_engine.py @@ -0,0 +1,184 @@ +"""Abstract base class for pluggable context engines. + +A context engine controls how conversation context is managed when +approaching the model's token limit. The built-in ContextCompressor +is the default implementation. Third-party engines (e.g. LCM) can +replace it via the plugin system or by being placed in the +``plugins/context_engine//`` directory. + +Selection is config-driven: ``context.engine`` in config.yaml. +Default is ``"compressor"`` (the built-in). Only one engine is active. + +The engine is responsible for: + - Deciding when compaction should fire + - Performing compaction (summarization, DAG construction, etc.) + - Optionally exposing tools the agent can call (e.g. lcm_grep) + - Tracking token usage from API responses + +Lifecycle: + 1. Engine is instantiated and registered (plugin register() or default) + 2. on_session_start() called when a conversation begins + 3. update_from_response() called after each API response with usage data + 4. should_compress() checked after each turn + 5. compress() called when should_compress() returns True + 6. on_session_end() called at real session boundaries (CLI exit, /reset, + gateway session expiry) — NOT per-turn +""" + +from abc import ABC, abstractmethod +from typing import Any, Dict, List + + +class ContextEngine(ABC): + """Base class all context engines must implement.""" + + # -- Identity ---------------------------------------------------------- + + @property + @abstractmethod + def name(self) -> str: + """Short identifier (e.g. 'compressor', 'lcm').""" + + # -- Token state (read by run_agent.py for display/logging) ------------ + # + # Engines MUST maintain these. run_agent.py reads them directly. + + last_prompt_tokens: int = 0 + last_completion_tokens: int = 0 + last_total_tokens: int = 0 + threshold_tokens: int = 0 + context_length: int = 0 + compression_count: int = 0 + + # -- Compaction parameters (read by run_agent.py for preflight) -------- + # + # These control the preflight compression check. Subclasses may + # override via __init__ or property; defaults are sensible for most + # engines. + + threshold_percent: float = 0.75 + protect_first_n: int = 3 + protect_last_n: int = 6 + + # -- Core interface ---------------------------------------------------- + + @abstractmethod + def update_from_response(self, usage: Dict[str, Any]) -> None: + """Update tracked token usage from an API response. + + Called after every LLM call with the usage dict from the response. + """ + + @abstractmethod + def should_compress(self, prompt_tokens: int = None) -> bool: + """Return True if compaction should fire this turn.""" + + @abstractmethod + def compress( + self, + messages: List[Dict[str, Any]], + current_tokens: int = None, + ) -> List[Dict[str, Any]]: + """Compact the message list and return the new message list. + + This is the main entry point. The engine receives the full message + list and returns a (possibly shorter) list that fits within the + context budget. The implementation is free to summarize, build a + DAG, or do anything else — as long as the returned list is a valid + OpenAI-format message sequence. + """ + + # -- Optional: pre-flight check ---------------------------------------- + + def should_compress_preflight(self, messages: List[Dict[str, Any]]) -> bool: + """Quick rough check before the API call (no real token count yet). + + Default returns False (skip pre-flight). Override if your engine + can do a cheap estimate. + """ + return False + + # -- Optional: session lifecycle --------------------------------------- + + def on_session_start(self, session_id: str, **kwargs) -> None: + """Called when a new conversation session begins. + + Use this to load persisted state (DAG, store) for the session. + kwargs may include hermes_home, platform, model, etc. + """ + + def on_session_end(self, session_id: str, messages: List[Dict[str, Any]]) -> None: + """Called at real session boundaries (CLI exit, /reset, gateway expiry). + + Use this to flush state, close DB connections, etc. + NOT called per-turn — only when the session truly ends. + """ + + def on_session_reset(self) -> None: + """Called on /new or /reset. Reset per-session state. + + Default resets compression_count and token tracking. + """ + self.last_prompt_tokens = 0 + self.last_completion_tokens = 0 + self.last_total_tokens = 0 + self.compression_count = 0 + + # -- Optional: tools --------------------------------------------------- + + def get_tool_schemas(self) -> List[Dict[str, Any]]: + """Return tool schemas this engine provides to the agent. + + Default returns empty list (no tools). LCM would return schemas + for lcm_grep, lcm_describe, lcm_expand here. + """ + return [] + + def handle_tool_call(self, name: str, args: Dict[str, Any], **kwargs) -> str: + """Handle a tool call from the agent. + + Only called for tool names returned by get_tool_schemas(). + Must return a JSON string. + + kwargs may include: + messages: the current in-memory message list (for live ingestion) + """ + import json + return json.dumps({"error": f"Unknown context engine tool: {name}"}) + + # -- Optional: status / display ---------------------------------------- + + def get_status(self) -> Dict[str, Any]: + """Return status dict for display/logging. + + Default returns the standard fields run_agent.py expects. + """ + return { + "last_prompt_tokens": self.last_prompt_tokens, + "threshold_tokens": self.threshold_tokens, + "context_length": self.context_length, + "usage_percent": ( + min(100, self.last_prompt_tokens / self.context_length * 100) + if self.context_length else 0 + ), + "compression_count": self.compression_count, + } + + # -- Optional: model switch support ------------------------------------ + + def update_model( + self, + model: str, + context_length: int, + base_url: str = "", + api_key: str = "", + provider: str = "", + ) -> None: + """Called when the user switches models or on fallback activation. + + Default updates context_length and recalculates threshold_tokens + from threshold_percent. Override if your engine needs more + (e.g. recalculate DAG budgets, switch summary models). + """ + self.context_length = context_length + self.threshold_tokens = int(context_length * self.threshold_percent) diff --git a/mindcli/_vendor/agent/context_references.py b/mindcli/_vendor/agent/context_references.py new file mode 100644 index 0000000..7ecb90c --- /dev/null +++ b/mindcli/_vendor/agent/context_references.py @@ -0,0 +1,520 @@ +from __future__ import annotations + +import asyncio +import inspect +import json +import mimetypes +import os +import re +import subprocess +from dataclasses import dataclass, field +from pathlib import Path +from typing import Awaitable, Callable + +from agent.model_metadata import estimate_tokens_rough + +_QUOTED_REFERENCE_VALUE = r'(?:`[^`\n]+`|"[^"\n]+"|\'[^\'\n]+\')' +REFERENCE_PATTERN = re.compile( + rf"(?diff|staged)\b|(?Pfile|folder|git|url):(?P{_QUOTED_REFERENCE_VALUE}(?::\d+(?:-\d+)?)?|\S+))" +) +TRAILING_PUNCTUATION = ",.;!?" +_SENSITIVE_HOME_DIRS = (".ssh", ".aws", ".gnupg", ".kube", ".docker", ".azure", ".config/gh") +_SENSITIVE_HERMES_DIRS = (Path("skills") / ".hub",) +_SENSITIVE_HOME_FILES = ( + Path(".ssh") / "authorized_keys", + Path(".ssh") / "id_rsa", + Path(".ssh") / "id_ed25519", + Path(".ssh") / "config", + Path(".bashrc"), + Path(".zshrc"), + Path(".profile"), + Path(".bash_profile"), + Path(".zprofile"), + Path(".netrc"), + Path(".pgpass"), + Path(".npmrc"), + Path(".pypirc"), +) + + +@dataclass(frozen=True) +class ContextReference: + raw: str + kind: str + target: str + start: int + end: int + line_start: int | None = None + line_end: int | None = None + + +@dataclass +class ContextReferenceResult: + message: str + original_message: str + references: list[ContextReference] = field(default_factory=list) + warnings: list[str] = field(default_factory=list) + injected_tokens: int = 0 + expanded: bool = False + blocked: bool = False + + +def parse_context_references(message: str) -> list[ContextReference]: + refs: list[ContextReference] = [] + if not message: + return refs + + for match in REFERENCE_PATTERN.finditer(message): + simple = match.group("simple") + if simple: + refs.append( + ContextReference( + raw=match.group(0), + kind=simple, + target="", + start=match.start(), + end=match.end(), + ) + ) + continue + + kind = match.group("kind") + value = _strip_trailing_punctuation(match.group("value") or "") + line_start = None + line_end = None + target = _strip_reference_wrappers(value) + + if kind == "file": + target, line_start, line_end = _parse_file_reference_value(value) + + refs.append( + ContextReference( + raw=match.group(0), + kind=kind, + target=target, + start=match.start(), + end=match.end(), + line_start=line_start, + line_end=line_end, + ) + ) + + return refs + + +def preprocess_context_references( + message: str, + *, + cwd: str | Path, + context_length: int, + url_fetcher: Callable[[str], str | Awaitable[str]] | None = None, + allowed_root: str | Path | None = None, +) -> ContextReferenceResult: + coro = preprocess_context_references_async( + message, + cwd=cwd, + context_length=context_length, + url_fetcher=url_fetcher, + allowed_root=allowed_root, + ) + # Safe for both CLI (no loop) and gateway (loop already running). + try: + loop = asyncio.get_running_loop() + except RuntimeError: + loop = None + if loop and loop.is_running(): + import concurrent.futures + with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool: + return pool.submit(asyncio.run, coro).result() + return asyncio.run(coro) + + +async def preprocess_context_references_async( + message: str, + *, + cwd: str | Path, + context_length: int, + url_fetcher: Callable[[str], str | Awaitable[str]] | None = None, + allowed_root: str | Path | None = None, +) -> ContextReferenceResult: + refs = parse_context_references(message) + if not refs: + return ContextReferenceResult(message=message, original_message=message) + + cwd_path = Path(cwd).expanduser().resolve() + # Default to the current working directory so @ references cannot escape + # the active workspace unless a caller explicitly widens the root. + allowed_root_path = ( + Path(allowed_root).expanduser().resolve() if allowed_root is not None else cwd_path + ) + warnings: list[str] = [] + blocks: list[str] = [] + injected_tokens = 0 + + for ref in refs: + warning, block = await _expand_reference( + ref, + cwd_path, + url_fetcher=url_fetcher, + allowed_root=allowed_root_path, + ) + if warning: + warnings.append(warning) + if block: + blocks.append(block) + injected_tokens += estimate_tokens_rough(block) + + hard_limit = max(1, int(context_length * 0.50)) + soft_limit = max(1, int(context_length * 0.25)) + if injected_tokens > hard_limit: + warnings.append( + f"@ context injection refused: {injected_tokens} tokens exceeds the 50% hard limit ({hard_limit})." + ) + return ContextReferenceResult( + message=message, + original_message=message, + references=refs, + warnings=warnings, + injected_tokens=injected_tokens, + expanded=False, + blocked=True, + ) + + if injected_tokens > soft_limit: + warnings.append( + f"@ context injection warning: {injected_tokens} tokens exceeds the 25% soft limit ({soft_limit})." + ) + + stripped = _remove_reference_tokens(message, refs) + final = stripped + if warnings: + final = f"{final}\n\n--- Context Warnings ---\n" + "\n".join(f"- {warning}" for warning in warnings) + if blocks: + final = f"{final}\n\n--- Attached Context ---\n\n" + "\n\n".join(blocks) + + return ContextReferenceResult( + message=final.strip(), + original_message=message, + references=refs, + warnings=warnings, + injected_tokens=injected_tokens, + expanded=bool(blocks or warnings), + blocked=False, + ) + + +async def _expand_reference( + ref: ContextReference, + cwd: Path, + *, + url_fetcher: Callable[[str], str | Awaitable[str]] | None = None, + allowed_root: Path | None = None, +) -> tuple[str | None, str | None]: + try: + if ref.kind == "file": + return _expand_file_reference(ref, cwd, allowed_root=allowed_root) + if ref.kind == "folder": + return _expand_folder_reference(ref, cwd, allowed_root=allowed_root) + if ref.kind == "diff": + return _expand_git_reference(ref, cwd, ["diff"], "git diff") + if ref.kind == "staged": + return _expand_git_reference(ref, cwd, ["diff", "--staged"], "git diff --staged") + if ref.kind == "git": + count = max(1, min(int(ref.target or "1"), 10)) + return _expand_git_reference(ref, cwd, ["log", f"-{count}", "-p"], f"git log -{count} -p") + if ref.kind == "url": + content = await _fetch_url_content(ref.target, url_fetcher=url_fetcher) + if not content: + return f"{ref.raw}: no content extracted", None + return None, f"🌐 {ref.raw} ({estimate_tokens_rough(content)} tokens)\n{content}" + except Exception as exc: + return f"{ref.raw}: {exc}", None + + return f"{ref.raw}: unsupported reference type", None + + +def _expand_file_reference( + ref: ContextReference, + cwd: Path, + *, + allowed_root: Path | None = None, +) -> tuple[str | None, str | None]: + path = _resolve_path(cwd, ref.target, allowed_root=allowed_root) + _ensure_reference_path_allowed(path) + if not path.exists(): + return f"{ref.raw}: file not found", None + if not path.is_file(): + return f"{ref.raw}: path is not a file", None + if _is_binary_file(path): + return f"{ref.raw}: binary files are not supported", None + + text = path.read_text(encoding="utf-8") + if ref.line_start is not None: + lines = text.splitlines() + start_idx = max(ref.line_start - 1, 0) + end_idx = min(ref.line_end or ref.line_start, len(lines)) + text = "\n".join(lines[start_idx:end_idx]) + + lang = _code_fence_language(path) + label = ref.raw + return None, f"📄 {label} ({estimate_tokens_rough(text)} tokens)\n```{lang}\n{text}\n```" + + +def _expand_folder_reference( + ref: ContextReference, + cwd: Path, + *, + allowed_root: Path | None = None, +) -> tuple[str | None, str | None]: + path = _resolve_path(cwd, ref.target, allowed_root=allowed_root) + _ensure_reference_path_allowed(path) + if not path.exists(): + return f"{ref.raw}: folder not found", None + if not path.is_dir(): + return f"{ref.raw}: path is not a folder", None + + listing = _build_folder_listing(path, cwd) + return None, f"📁 {ref.raw} ({estimate_tokens_rough(listing)} tokens)\n{listing}" + + +def _expand_git_reference( + ref: ContextReference, + cwd: Path, + args: list[str], + label: str, +) -> tuple[str | None, str | None]: + try: + result = subprocess.run( + ["git", *args], + cwd=cwd, + capture_output=True, + text=True, + timeout=30, + ) + except subprocess.TimeoutExpired: + return f"{ref.raw}: git command timed out (30s)", None + if result.returncode != 0: + stderr = (result.stderr or "").strip() or "git command failed" + return f"{ref.raw}: {stderr}", None + content = result.stdout.strip() + if not content: + content = "(no output)" + return None, f"🧾 {label} ({estimate_tokens_rough(content)} tokens)\n```diff\n{content}\n```" + + +async def _fetch_url_content( + url: str, + *, + url_fetcher: Callable[[str], str | Awaitable[str]] | None = None, +) -> str: + fetcher = url_fetcher or _default_url_fetcher + content = fetcher(url) + if inspect.isawaitable(content): + content = await content + return str(content or "").strip() + + +async def _default_url_fetcher(url: str) -> str: + from tools.web_tools import web_extract_tool + + raw = await web_extract_tool([url], format="markdown", use_llm_processing=True) + payload = json.loads(raw) + docs = payload.get("data", {}).get("documents", []) + if not docs: + return "" + doc = docs[0] + return str(doc.get("content") or doc.get("raw_content") or "").strip() + + +def _resolve_path(cwd: Path, target: str, *, allowed_root: Path | None = None) -> Path: + path = Path(os.path.expanduser(target)) + if not path.is_absolute(): + path = cwd / path + resolved = path.resolve() + if allowed_root is not None: + try: + resolved.relative_to(allowed_root) + except ValueError as exc: + raise ValueError("path is outside the allowed workspace") from exc + return resolved + + +def _ensure_reference_path_allowed(path: Path) -> None: + from hermes_constants import get_hermes_home + home = Path(os.path.expanduser("~")).resolve() + hermes_home = get_hermes_home().resolve() + + blocked_exact = {home / rel for rel in _SENSITIVE_HOME_FILES} + blocked_exact.add(hermes_home / ".env") + blocked_dirs = [home / rel for rel in _SENSITIVE_HOME_DIRS] + blocked_dirs.extend(hermes_home / rel for rel in _SENSITIVE_HERMES_DIRS) + + if path in blocked_exact: + raise ValueError("path is a sensitive credential file and cannot be attached") + + for blocked_dir in blocked_dirs: + try: + path.relative_to(blocked_dir) + except ValueError: + continue + raise ValueError("path is a sensitive credential or internal Hermes path and cannot be attached") + + +def _strip_trailing_punctuation(value: str) -> str: + stripped = value.rstrip(TRAILING_PUNCTUATION) + while stripped.endswith((")", "]", "}")): + closer = stripped[-1] + opener = {")": "(", "]": "[", "}": "{"}[closer] + if stripped.count(closer) > stripped.count(opener): + stripped = stripped[:-1] + continue + break + return stripped + + +def _strip_reference_wrappers(value: str) -> str: + if len(value) >= 2 and value[0] == value[-1] and value[0] in "`\"'": + return value[1:-1] + return value + + +def _parse_file_reference_value(value: str) -> tuple[str, int | None, int | None]: + quoted_match = re.match( + r'^(?P`|"|\')(?P.+?)(?P=quote)(?::(?P\d+)(?:-(?P\d+))?)?$', + value, + ) + if quoted_match: + line_start = quoted_match.group("start") + line_end = quoted_match.group("end") + return ( + quoted_match.group("path"), + int(line_start) if line_start is not None else None, + int(line_end or line_start) if line_start is not None else None, + ) + + range_match = re.match(r"^(?P.+?):(?P\d+)(?:-(?P\d+))?$", value) + if range_match: + line_start = int(range_match.group("start")) + return ( + range_match.group("path"), + line_start, + int(range_match.group("end") or range_match.group("start")), + ) + + return _strip_reference_wrappers(value), None, None + + +def _remove_reference_tokens(message: str, refs: list[ContextReference]) -> str: + pieces: list[str] = [] + cursor = 0 + for ref in refs: + pieces.append(message[cursor:ref.start]) + cursor = ref.end + pieces.append(message[cursor:]) + text = "".join(pieces) + text = re.sub(r"\s{2,}", " ", text) + text = re.sub(r"\s+([,.;:!?])", r"\1", text) + return text.strip() + + +def _is_binary_file(path: Path) -> bool: + mime, _ = mimetypes.guess_type(path.name) + if mime and not mime.startswith("text/") and not any( + path.name.endswith(ext) for ext in (".py", ".md", ".txt", ".json", ".yaml", ".yml", ".toml", ".js", ".ts") + ): + return True + chunk = path.read_bytes()[:4096] + return b"\x00" in chunk + + +def _build_folder_listing(path: Path, cwd: Path, limit: int = 200) -> str: + lines = [f"{path.relative_to(cwd)}/"] + entries = _iter_visible_entries(path, cwd, limit=limit) + for entry in entries: + rel = entry.relative_to(cwd) + indent = " " * max(len(rel.parts) - len(path.relative_to(cwd).parts) - 1, 0) + if entry.is_dir(): + lines.append(f"{indent}- {entry.name}/") + else: + meta = _file_metadata(entry) + lines.append(f"{indent}- {entry.name} ({meta})") + if len(entries) >= limit: + lines.append("- ...") + return "\n".join(lines) + + +def _iter_visible_entries(path: Path, cwd: Path, limit: int) -> list[Path]: + rg_entries = _rg_files(path, cwd, limit=limit) + if rg_entries is not None: + output: list[Path] = [] + seen_dirs: set[Path] = set() + for rel in rg_entries: + full = cwd / rel + for parent in full.parents: + if parent == cwd or parent in seen_dirs or path not in {parent, *parent.parents}: + continue + seen_dirs.add(parent) + output.append(parent) + output.append(full) + return sorted({p for p in output if p.exists()}, key=lambda p: (not p.is_dir(), str(p))) + + output = [] + for root, dirs, files in os.walk(path): + dirs[:] = sorted(d for d in dirs if not d.startswith(".") and d != "__pycache__") + files = sorted(f for f in files if not f.startswith(".")) + root_path = Path(root) + for d in dirs: + output.append(root_path / d) + if len(output) >= limit: + return output + for f in files: + output.append(root_path / f) + if len(output) >= limit: + return output + return output + + +def _rg_files(path: Path, cwd: Path, limit: int) -> list[Path] | None: + try: + result = subprocess.run( + ["rg", "--files", str(path.relative_to(cwd))], + cwd=cwd, + capture_output=True, + text=True, + timeout=10, + ) + except FileNotFoundError: + return None + except subprocess.TimeoutExpired: + return None + if result.returncode != 0: + return None + files = [Path(line.strip()) for line in result.stdout.splitlines() if line.strip()] + return files[:limit] + + +def _file_metadata(path: Path) -> str: + if _is_binary_file(path): + return f"{path.stat().st_size} bytes" + try: + line_count = path.read_text(encoding="utf-8").count("\n") + 1 + except Exception: + return f"{path.stat().st_size} bytes" + return f"{line_count} lines" + + +def _code_fence_language(path: Path) -> str: + mapping = { + ".py": "python", + ".js": "javascript", + ".ts": "typescript", + ".tsx": "tsx", + ".jsx": "jsx", + ".json": "json", + ".md": "markdown", + ".sh": "bash", + ".yml": "yaml", + ".yaml": "yaml", + ".toml": "toml", + } + return mapping.get(path.suffix.lower(), "") diff --git a/mindcli/_vendor/agent/copilot_acp_client.py b/mindcli/_vendor/agent/copilot_acp_client.py new file mode 100644 index 0000000..235fd9a --- /dev/null +++ b/mindcli/_vendor/agent/copilot_acp_client.py @@ -0,0 +1,570 @@ +"""OpenAI-compatible shim that forwards Hermes requests to `copilot --acp`. + +This adapter lets Hermes treat the GitHub Copilot ACP server as a chat-style +backend. Each request starts a short-lived ACP session, sends the formatted +conversation as a single prompt, collects text chunks, and converts the result +back into the minimal shape Hermes expects from an OpenAI client. +""" + +from __future__ import annotations + +import json +import os +import queue +import re +import shlex +import subprocess +import threading +import time +from collections import deque +from pathlib import Path +from types import SimpleNamespace +from typing import Any + +ACP_MARKER_BASE_URL = "acp://copilot" +_DEFAULT_TIMEOUT_SECONDS = 900.0 + +_TOOL_CALL_BLOCK_RE = re.compile(r"\s*(\{.*?\})\s*", re.DOTALL) +_TOOL_CALL_JSON_RE = re.compile(r"\{\s*\"id\"\s*:\s*\"[^\"]+\"\s*,\s*\"type\"\s*:\s*\"function\"\s*,\s*\"function\"\s*:\s*\{.*?\}\s*\}", re.DOTALL) + + +def _resolve_command() -> str: + return ( + os.getenv("HERMES_COPILOT_ACP_COMMAND", "").strip() + or os.getenv("COPILOT_CLI_PATH", "").strip() + or "copilot" + ) + + +def _resolve_args() -> list[str]: + raw = os.getenv("HERMES_COPILOT_ACP_ARGS", "").strip() + if not raw: + return ["--acp", "--stdio"] + return shlex.split(raw) + + +def _jsonrpc_error(message_id: Any, code: int, message: str) -> dict[str, Any]: + return { + "jsonrpc": "2.0", + "id": message_id, + "error": { + "code": code, + "message": message, + }, + } + + +def _format_messages_as_prompt( + messages: list[dict[str, Any]], + model: str | None = None, + tools: list[dict[str, Any]] | None = None, + tool_choice: Any = None, +) -> str: + sections: list[str] = [ + "You are being used as the active ACP agent backend for Hermes.", + "Use ACP capabilities to complete tasks.", + "IMPORTANT: If you take an action with a tool, you MUST output tool calls using {...} blocks with JSON exactly in OpenAI function-call shape.", + "If no tool is needed, answer normally.", + ] + if model: + sections.append(f"Hermes requested model hint: {model}") + + if isinstance(tools, list) and tools: + tool_specs: list[dict[str, Any]] = [] + for t in tools: + if not isinstance(t, dict): + continue + fn = t.get("function") or {} + if not isinstance(fn, dict): + continue + name = fn.get("name") + if not isinstance(name, str) or not name.strip(): + continue + tool_specs.append( + { + "name": name.strip(), + "description": fn.get("description", ""), + "parameters": fn.get("parameters", {}), + } + ) + if tool_specs: + sections.append( + "Available tools (OpenAI function schema). " + "When using a tool, emit ONLY {...} with one JSON object " + "containing id/type/function{name,arguments}. arguments must be a JSON string.\n" + + json.dumps(tool_specs, ensure_ascii=False) + ) + + if tool_choice is not None: + sections.append(f"Tool choice hint: {json.dumps(tool_choice, ensure_ascii=False)}") + + transcript: list[str] = [] + for message in messages: + if not isinstance(message, dict): + continue + role = str(message.get("role") or "unknown").strip().lower() + if role == "tool": + role = "tool" + elif role not in {"system", "user", "assistant"}: + role = "context" + + content = message.get("content") + rendered = _render_message_content(content) + if not rendered: + continue + + label = { + "system": "System", + "user": "User", + "assistant": "Assistant", + "tool": "Tool", + "context": "Context", + }.get(role, role.title()) + transcript.append(f"{label}:\n{rendered}") + + if transcript: + sections.append("Conversation transcript:\n\n" + "\n\n".join(transcript)) + + sections.append("Continue the conversation from the latest user request.") + return "\n\n".join(section.strip() for section in sections if section and section.strip()) + + +def _render_message_content(content: Any) -> str: + if content is None: + return "" + if isinstance(content, str): + return content.strip() + if isinstance(content, dict): + if "text" in content: + return str(content.get("text") or "").strip() + if "content" in content and isinstance(content.get("content"), str): + return str(content.get("content") or "").strip() + return json.dumps(content, ensure_ascii=True) + if isinstance(content, list): + parts: list[str] = [] + for item in content: + if isinstance(item, str): + parts.append(item) + elif isinstance(item, dict): + text = item.get("text") + if isinstance(text, str) and text.strip(): + parts.append(text.strip()) + return "\n".join(parts).strip() + return str(content).strip() + + +def _extract_tool_calls_from_text(text: str) -> tuple[list[SimpleNamespace], str]: + if not isinstance(text, str) or not text.strip(): + return [], "" + + extracted: list[SimpleNamespace] = [] + consumed_spans: list[tuple[int, int]] = [] + + def _try_add_tool_call(raw_json: str) -> None: + try: + obj = json.loads(raw_json) + except Exception: + return + if not isinstance(obj, dict): + return + fn = obj.get("function") + if not isinstance(fn, dict): + return + fn_name = fn.get("name") + if not isinstance(fn_name, str) or not fn_name.strip(): + return + fn_args = fn.get("arguments", "{}") + if not isinstance(fn_args, str): + fn_args = json.dumps(fn_args, ensure_ascii=False) + call_id = obj.get("id") + if not isinstance(call_id, str) or not call_id.strip(): + call_id = f"acp_call_{len(extracted)+1}" + + extracted.append( + SimpleNamespace( + id=call_id, + call_id=call_id, + response_item_id=None, + type="function", + function=SimpleNamespace(name=fn_name.strip(), arguments=fn_args), + ) + ) + + for m in _TOOL_CALL_BLOCK_RE.finditer(text): + raw = m.group(1) + _try_add_tool_call(raw) + consumed_spans.append((m.start(), m.end())) + + # Only try bare-JSON fallback when no XML blocks were found. + if not extracted: + for m in _TOOL_CALL_JSON_RE.finditer(text): + raw = m.group(0) + _try_add_tool_call(raw) + consumed_spans.append((m.start(), m.end())) + + if not consumed_spans: + return extracted, text.strip() + + consumed_spans.sort() + merged: list[tuple[int, int]] = [] + for start, end in consumed_spans: + if not merged or start > merged[-1][1]: + merged.append((start, end)) + else: + merged[-1] = (merged[-1][0], max(merged[-1][1], end)) + + parts: list[str] = [] + cursor = 0 + for start, end in merged: + if cursor < start: + parts.append(text[cursor:start]) + cursor = max(cursor, end) + if cursor < len(text): + parts.append(text[cursor:]) + + cleaned = "\n".join(p.strip() for p in parts if p and p.strip()).strip() + return extracted, cleaned + + + +def _ensure_path_within_cwd(path_text: str, cwd: str) -> Path: + candidate = Path(path_text) + if not candidate.is_absolute(): + raise PermissionError("ACP file-system paths must be absolute.") + resolved = candidate.resolve() + root = Path(cwd).resolve() + try: + resolved.relative_to(root) + except ValueError as exc: + raise PermissionError(f"Path '{resolved}' is outside the session cwd '{root}'.") from exc + return resolved + + +class _ACPChatCompletions: + def __init__(self, client: "CopilotACPClient"): + self._client = client + + def create(self, **kwargs: Any) -> Any: + return self._client._create_chat_completion(**kwargs) + + +class _ACPChatNamespace: + def __init__(self, client: "CopilotACPClient"): + self.completions = _ACPChatCompletions(client) + + +class CopilotACPClient: + """Minimal OpenAI-client-compatible facade for Copilot ACP.""" + + def __init__( + self, + *, + api_key: str | None = None, + base_url: str | None = None, + default_headers: dict[str, str] | None = None, + acp_command: str | None = None, + acp_args: list[str] | None = None, + acp_cwd: str | None = None, + command: str | None = None, + args: list[str] | None = None, + **_: Any, + ): + self.api_key = api_key or "copilot-acp" + self.base_url = base_url or ACP_MARKER_BASE_URL + self._default_headers = dict(default_headers or {}) + self._acp_command = acp_command or command or _resolve_command() + self._acp_args = list(acp_args or args or _resolve_args()) + self._acp_cwd = str(Path(acp_cwd or os.getcwd()).resolve()) + self.chat = _ACPChatNamespace(self) + self.is_closed = False + self._active_process: subprocess.Popen[str] | None = None + self._active_process_lock = threading.Lock() + + def close(self) -> None: + proc: subprocess.Popen[str] | None + with self._active_process_lock: + proc = self._active_process + self._active_process = None + self.is_closed = True + if proc is None: + return + try: + proc.terminate() + proc.wait(timeout=2) + except Exception: + try: + proc.kill() + except Exception: + pass + + def _create_chat_completion( + self, + *, + model: str | None = None, + messages: list[dict[str, Any]] | None = None, + timeout: float | None = None, + tools: list[dict[str, Any]] | None = None, + tool_choice: Any = None, + **_: Any, + ) -> Any: + prompt_text = _format_messages_as_prompt( + messages or [], + model=model, + tools=tools, + tool_choice=tool_choice, + ) + response_text, reasoning_text = self._run_prompt( + prompt_text, + timeout_seconds=float(timeout or _DEFAULT_TIMEOUT_SECONDS), + ) + + tool_calls, cleaned_text = _extract_tool_calls_from_text(response_text) + + usage = SimpleNamespace( + prompt_tokens=0, + completion_tokens=0, + total_tokens=0, + prompt_tokens_details=SimpleNamespace(cached_tokens=0), + ) + assistant_message = SimpleNamespace( + content=cleaned_text, + tool_calls=tool_calls, + reasoning=reasoning_text or None, + reasoning_content=reasoning_text or None, + reasoning_details=None, + ) + finish_reason = "tool_calls" if tool_calls else "stop" + choice = SimpleNamespace(message=assistant_message, finish_reason=finish_reason) + return SimpleNamespace( + choices=[choice], + usage=usage, + model=model or "copilot-acp", + ) + + def _run_prompt(self, prompt_text: str, *, timeout_seconds: float) -> tuple[str, str]: + try: + proc = subprocess.Popen( + [self._acp_command] + self._acp_args, + stdin=subprocess.PIPE, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + text=True, + bufsize=1, + cwd=self._acp_cwd, + ) + except FileNotFoundError as exc: + raise RuntimeError( + f"Could not start Copilot ACP command '{self._acp_command}'. " + "Install GitHub Copilot CLI or set HERMES_COPILOT_ACP_COMMAND/COPILOT_CLI_PATH." + ) from exc + + if proc.stdin is None or proc.stdout is None: + proc.kill() + raise RuntimeError("Copilot ACP process did not expose stdin/stdout pipes.") + + self.is_closed = False + with self._active_process_lock: + self._active_process = proc + + inbox: queue.Queue[dict[str, Any]] = queue.Queue() + stderr_tail: deque[str] = deque(maxlen=40) + + def _stdout_reader() -> None: + for line in proc.stdout: + try: + inbox.put(json.loads(line)) + except Exception: + inbox.put({"raw": line.rstrip("\n")}) + + def _stderr_reader() -> None: + if proc.stderr is None: + return + for line in proc.stderr: + stderr_tail.append(line.rstrip("\n")) + + out_thread = threading.Thread(target=_stdout_reader, daemon=True) + err_thread = threading.Thread(target=_stderr_reader, daemon=True) + out_thread.start() + err_thread.start() + + next_id = 0 + + def _request(method: str, params: dict[str, Any], *, text_parts: list[str] | None = None, reasoning_parts: list[str] | None = None) -> Any: + nonlocal next_id + next_id += 1 + request_id = next_id + payload = { + "jsonrpc": "2.0", + "id": request_id, + "method": method, + "params": params, + } + proc.stdin.write(json.dumps(payload) + "\n") + proc.stdin.flush() + + deadline = time.time() + timeout_seconds + while time.time() < deadline: + if proc.poll() is not None: + break + try: + msg = inbox.get(timeout=0.1) + except queue.Empty: + continue + + if self._handle_server_message( + msg, + process=proc, + cwd=self._acp_cwd, + text_parts=text_parts, + reasoning_parts=reasoning_parts, + ): + continue + + if msg.get("id") != request_id: + continue + if "error" in msg: + err = msg.get("error") or {} + raise RuntimeError( + f"Copilot ACP {method} failed: {err.get('message') or err}" + ) + return msg.get("result") + + stderr_text = "\n".join(stderr_tail).strip() + if proc.poll() is not None and stderr_text: + raise RuntimeError(f"Copilot ACP process exited early: {stderr_text}") + raise TimeoutError(f"Timed out waiting for Copilot ACP response to {method}.") + + try: + _request( + "initialize", + { + "protocolVersion": 1, + "clientCapabilities": { + "fs": { + "readTextFile": True, + "writeTextFile": True, + } + }, + "clientInfo": { + "name": "hermes-agent", + "title": "Hermes Agent", + "version": "0.0.0", + }, + }, + ) + session = _request( + "session/new", + { + "cwd": self._acp_cwd, + "mcpServers": [], + }, + ) or {} + session_id = str(session.get("sessionId") or "").strip() + if not session_id: + raise RuntimeError("Copilot ACP did not return a sessionId.") + + text_parts: list[str] = [] + reasoning_parts: list[str] = [] + _request( + "session/prompt", + { + "sessionId": session_id, + "prompt": [ + { + "type": "text", + "text": prompt_text, + } + ], + }, + text_parts=text_parts, + reasoning_parts=reasoning_parts, + ) + return "".join(text_parts), "".join(reasoning_parts) + finally: + self.close() + + def _handle_server_message( + self, + msg: dict[str, Any], + *, + process: subprocess.Popen[str], + cwd: str, + text_parts: list[str] | None, + reasoning_parts: list[str] | None, + ) -> bool: + method = msg.get("method") + if not isinstance(method, str): + return False + + if method == "session/update": + params = msg.get("params") or {} + update = params.get("update") or {} + kind = str(update.get("sessionUpdate") or "").strip() + content = update.get("content") or {} + chunk_text = "" + if isinstance(content, dict): + chunk_text = str(content.get("text") or "") + if kind == "agent_message_chunk" and chunk_text and text_parts is not None: + text_parts.append(chunk_text) + elif kind == "agent_thought_chunk" and chunk_text and reasoning_parts is not None: + reasoning_parts.append(chunk_text) + return True + + if process.stdin is None: + return True + + message_id = msg.get("id") + params = msg.get("params") or {} + + if method == "session/request_permission": + response = { + "jsonrpc": "2.0", + "id": message_id, + "result": { + "outcome": { + "outcome": "allow_once", + } + }, + } + elif method == "fs/read_text_file": + try: + path = _ensure_path_within_cwd(str(params.get("path") or ""), cwd) + content = path.read_text() if path.exists() else "" + line = params.get("line") + limit = params.get("limit") + if isinstance(line, int) and line > 1: + lines = content.splitlines(keepends=True) + start = line - 1 + end = start + limit if isinstance(limit, int) and limit > 0 else None + content = "".join(lines[start:end]) + response = { + "jsonrpc": "2.0", + "id": message_id, + "result": { + "content": content, + }, + } + except Exception as exc: + response = _jsonrpc_error(message_id, -32602, str(exc)) + elif method == "fs/write_text_file": + try: + path = _ensure_path_within_cwd(str(params.get("path") or ""), cwd) + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(str(params.get("content") or "")) + response = { + "jsonrpc": "2.0", + "id": message_id, + "result": None, + } + except Exception as exc: + response = _jsonrpc_error(message_id, -32602, str(exc)) + else: + response = _jsonrpc_error( + message_id, + -32601, + f"ACP client method '{method}' is not supported by Hermes yet.", + ) + + process.stdin.write(json.dumps(response) + "\n") + process.stdin.flush() + return True diff --git a/mindcli/_vendor/agent/credential_pool.py b/mindcli/_vendor/agent/credential_pool.py new file mode 100644 index 0000000..c4905fc --- /dev/null +++ b/mindcli/_vendor/agent/credential_pool.py @@ -0,0 +1,1363 @@ +"""Persistent multi-credential pool for same-provider failover.""" + +from __future__ import annotations + +import logging +import random +import threading +import time +import uuid +import os +import re +from dataclasses import dataclass, fields, replace +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 ( + CODEX_ACCESS_TOKEN_REFRESH_SKEW_SECONDS, + DEFAULT_AGENT_KEY_MIN_TTL_SECONDS, + PROVIDER_REGISTRY, + _auth_store_lock, + _codex_access_token_is_expiring, + _decode_jwt_claims, + _import_codex_cli_tokens, + _write_codex_cli_tokens, + _load_auth_store, + _load_provider_state, + _resolve_kimi_base_url, + _resolve_zai_base_url, + _save_auth_store, + _save_provider_state, + read_credential_pool, + write_credential_pool, +) + +logger = logging.getLogger(__name__) + + +def _load_config_safe() -> Optional[dict]: + """Load config.yaml, returning None on any error.""" + try: + from hermes_cli.config import load_config + + return load_config() + except Exception: + return None + + +# --- Status and type constants --- + +STATUS_OK = "ok" +STATUS_EXHAUSTED = "exhausted" + +AUTH_TYPE_OAUTH = "oauth" +AUTH_TYPE_API_KEY = "api_key" + +SOURCE_MANUAL = "manual" + +STRATEGY_FILL_FIRST = "fill_first" +STRATEGY_ROUND_ROBIN = "round_robin" +STRATEGY_RANDOM = "random" +STRATEGY_LEAST_USED = "least_used" +SUPPORTED_POOL_STRATEGIES = { + STRATEGY_FILL_FIRST, + STRATEGY_ROUND_ROBIN, + STRATEGY_RANDOM, + STRATEGY_LEAST_USED, +} + +# Cooldown before retrying an exhausted credential. +# 429 (rate-limited) and 402 (billing/quota) both cool down after 1 hour. +# Provider-supplied reset_at timestamps override these defaults. +EXHAUSTED_TTL_429_SECONDS = 60 * 60 # 1 hour +EXHAUSTED_TTL_DEFAULT_SECONDS = 60 * 60 # 1 hour + +# Pool key prefix for custom OpenAI-compatible endpoints. +# Custom endpoints all share provider='custom' but are keyed by their +# custom_providers name: 'custom:'. +CUSTOM_POOL_PREFIX = "custom:" + + +# Fields that are only round-tripped through JSON — never used for logic as attributes. +_EXTRA_KEYS = frozenset({ + "token_type", "scope", "client_id", "portal_base_url", "obtained_at", + "expires_in", "agent_key_id", "agent_key_expires_in", "agent_key_reused", + "agent_key_obtained_at", "tls", +}) + + +@dataclass +class PooledCredential: + provider: str + id: str + label: str + auth_type: str + priority: int + source: str + access_token: str + refresh_token: Optional[str] = None + last_status: Optional[str] = None + last_status_at: Optional[float] = None + last_error_code: Optional[int] = None + last_error_reason: Optional[str] = None + last_error_message: Optional[str] = None + last_error_reset_at: Optional[float] = None + base_url: Optional[str] = None + expires_at: Optional[str] = None + expires_at_ms: Optional[int] = None + last_refresh: Optional[str] = None + inference_base_url: Optional[str] = None + agent_key: Optional[str] = None + agent_key_expires_at: Optional[str] = None + request_count: int = 0 + extra: Dict[str, Any] = None # type: ignore[assignment] + + def __post_init__(self): + if self.extra is None: + self.extra = {} + + def __getattr__(self, name: str): + if name in _EXTRA_KEYS: + return self.extra.get(name) + raise AttributeError(f"'{type(self).__name__}' object has no attribute {name!r}") + + @classmethod + def from_dict(cls, provider: str, payload: Dict[str, Any]) -> "PooledCredential": + field_names = {f.name for f in fields(cls) if f.name != "provider"} + data = {k: payload.get(k) for k in field_names if k in payload} + extra = {k: payload[k] for k in _EXTRA_KEYS if k in payload and payload[k] is not None} + data["extra"] = extra + data.setdefault("id", uuid.uuid4().hex[:6]) + data.setdefault("label", payload.get("source", provider)) + data.setdefault("auth_type", AUTH_TYPE_API_KEY) + data.setdefault("priority", 0) + data.setdefault("source", SOURCE_MANUAL) + data.setdefault("access_token", "") + return cls(provider=provider, **data) + + def to_dict(self) -> Dict[str, Any]: + _ALWAYS_EMIT = { + "last_status", + "last_status_at", + "last_error_code", + "last_error_reason", + "last_error_message", + "last_error_reset_at", + } + result: Dict[str, Any] = {} + for field_def in fields(self): + if field_def.name in ("provider", "extra"): + continue + value = getattr(self, field_def.name) + if value is not None or field_def.name in _ALWAYS_EMIT: + result[field_def.name] = value + for k, v in self.extra.items(): + if v is not None: + result[k] = v + return result + + @property + def runtime_api_key(self) -> str: + if self.provider == "nous": + return str(self.agent_key or self.access_token or "") + return str(self.access_token or "") + + @property + def runtime_base_url(self) -> Optional[str]: + if self.provider == "nous": + return self.inference_base_url or self.base_url + return self.base_url + + +def label_from_token(token: str, fallback: str) -> str: + claims = _decode_jwt_claims(token) + for key in ("email", "preferred_username", "upn"): + value = claims.get(key) + if isinstance(value, str) and value.strip(): + return value.strip() + return fallback + + +def _next_priority(entries: List[PooledCredential]) -> int: + return max((entry.priority for entry in entries), default=-1) + 1 + + +def _is_manual_source(source: str) -> bool: + normalized = (source or "").strip().lower() + return normalized == SOURCE_MANUAL or normalized.startswith(f"{SOURCE_MANUAL}:") + + +def _exhausted_ttl(error_code: Optional[int]) -> int: + """Return cooldown seconds based on the HTTP status that caused exhaustion.""" + if error_code == 429: + return EXHAUSTED_TTL_429_SECONDS + return EXHAUSTED_TTL_DEFAULT_SECONDS + + +def _parse_absolute_timestamp(value: Any) -> Optional[float]: + """Best-effort parse for provider reset timestamps. + + Accepts epoch seconds, epoch milliseconds, and ISO-8601 strings. + Returns seconds since epoch. + """ + if value is None or value == "": + return None + if isinstance(value, (int, float)): + numeric = float(value) + if numeric <= 0: + return None + return numeric / 1000.0 if numeric > 1_000_000_000_000 else numeric + if isinstance(value, str): + raw = value.strip() + if not raw: + return None + try: + numeric = float(raw) + except ValueError: + numeric = None + if numeric is not None: + return numeric / 1000.0 if numeric > 1_000_000_000_000 else numeric + try: + return datetime.fromisoformat(raw.replace("Z", "+00:00")).timestamp() + except ValueError: + return None + return None + + +def _extract_retry_delay_seconds(message: str) -> Optional[float]: + if not message: + return None + delay_match = re.search(r"quotaResetDelay[:\s\"]+(\d+(?:\.\d+)?)(ms|s)", message, re.IGNORECASE) + if delay_match: + value = float(delay_match.group(1)) + return value / 1000.0 if delay_match.group(2).lower() == "ms" else value + sec_match = re.search(r"retry\s+(?:after\s+)?(\d+(?:\.\d+)?)\s*(?:sec|secs|seconds|s\b)", message, re.IGNORECASE) + if sec_match: + return float(sec_match.group(1)) + return None + + +def _normalize_error_context(error_context: Optional[Dict[str, Any]]) -> Dict[str, Any]: + if not isinstance(error_context, dict): + return {} + normalized: Dict[str, Any] = {} + reason = error_context.get("reason") + if isinstance(reason, str) and reason.strip(): + normalized["reason"] = reason.strip() + message = error_context.get("message") + if isinstance(message, str) and message.strip(): + normalized["message"] = message.strip() + reset_at = ( + error_context.get("reset_at") + or error_context.get("resets_at") + or error_context.get("retry_until") + ) + parsed_reset_at = _parse_absolute_timestamp(reset_at) + if parsed_reset_at is None and isinstance(message, str): + retry_delay_seconds = _extract_retry_delay_seconds(message) + if retry_delay_seconds is not None: + parsed_reset_at = time.time() + retry_delay_seconds + if parsed_reset_at is not None: + normalized["reset_at"] = parsed_reset_at + return normalized + + +def _exhausted_until(entry: PooledCredential) -> Optional[float]: + if entry.last_status != STATUS_EXHAUSTED: + return None + reset_at = _parse_absolute_timestamp(getattr(entry, "last_error_reset_at", None)) + if reset_at is not None: + return reset_at + if entry.last_status_at: + return entry.last_status_at + _exhausted_ttl(entry.last_error_code) + return None + + +def _normalize_custom_pool_name(name: str) -> str: + """Normalize a custom provider name for use as a pool key suffix.""" + return name.strip().lower().replace(" ", "-") + + +def _iter_custom_providers(config: Optional[dict] = None): + """Yield (normalized_name, entry_dict) for each valid custom_providers entry.""" + if config is None: + config = _load_config_safe() + if config is None: + return + custom_providers = config.get("custom_providers") + if not isinstance(custom_providers, list): + # Fall back to the v12+ providers dict via the compatibility layer + try: + from hermes_cli.config import get_compatible_custom_providers + + custom_providers = get_compatible_custom_providers(config) + except Exception: + return + if not custom_providers: + return + for entry in custom_providers: + if not isinstance(entry, dict): + continue + name = entry.get("name") + if not isinstance(name, str): + continue + yield _normalize_custom_pool_name(name), entry + + +def get_custom_provider_pool_key(base_url: str) -> Optional[str]: + """Look up the custom_providers list in config.yaml and return 'custom:' for a matching base_url. + + Returns None if no match is found. + """ + if not base_url: + return None + normalized_url = base_url.strip().rstrip("/") + for norm_name, entry in _iter_custom_providers(): + entry_url = str(entry.get("base_url") or "").strip().rstrip("/") + if entry_url and entry_url == normalized_url: + return f"{CUSTOM_POOL_PREFIX}{norm_name}" + return None + + +def list_custom_pool_providers() -> List[str]: + """Return all 'custom:*' pool keys that have entries in auth.json.""" + pool_data = read_credential_pool(None) + return sorted( + key for key in pool_data + if key.startswith(CUSTOM_POOL_PREFIX) + and isinstance(pool_data.get(key), list) + and pool_data[key] + ) + + +def _get_custom_provider_config(pool_key: str) -> Optional[Dict[str, Any]]: + """Return the custom_providers config entry matching a pool key like 'custom:together.ai'.""" + if not pool_key.startswith(CUSTOM_POOL_PREFIX): + return None + suffix = pool_key[len(CUSTOM_POOL_PREFIX):] + for norm_name, entry in _iter_custom_providers(): + if norm_name == suffix: + return entry + return None + + +def get_pool_strategy(provider: str) -> str: + """Return the configured selection strategy for a provider.""" + config = _load_config_safe() + if config is None: + return STRATEGY_FILL_FIRST + + strategies = config.get("credential_pool_strategies") + if not isinstance(strategies, dict): + return STRATEGY_FILL_FIRST + + strategy = str(strategies.get(provider, "") or "").strip().lower() + if strategy in SUPPORTED_POOL_STRATEGIES: + return strategy + return STRATEGY_FILL_FIRST + + +DEFAULT_MAX_CONCURRENT_PER_CREDENTIAL = 1 + + +class CredentialPool: + def __init__(self, provider: str, entries: List[PooledCredential]): + self.provider = provider + self._entries = sorted(entries, key=lambda entry: entry.priority) + self._current_id: Optional[str] = None + self._strategy = get_pool_strategy(provider) + self._lock = threading.Lock() + self._active_leases: Dict[str, int] = {} + self._max_concurrent = DEFAULT_MAX_CONCURRENT_PER_CREDENTIAL + + def has_credentials(self) -> bool: + return bool(self._entries) + + def has_available(self) -> bool: + """True if at least one entry is not currently in exhaustion cooldown.""" + return bool(self._available_entries()) + + def entries(self) -> List[PooledCredential]: + return list(self._entries) + + def current(self) -> Optional[PooledCredential]: + if not self._current_id: + return None + return next((entry for entry in self._entries if entry.id == self._current_id), None) + + def _replace_entry(self, old: PooledCredential, new: PooledCredential) -> None: + """Swap an entry in-place by id, preserving sort order.""" + for idx, entry in enumerate(self._entries): + if entry.id == old.id: + self._entries[idx] = new + return + + def _persist(self) -> None: + write_credential_pool( + self.provider, + [entry.to_dict() for entry in self._entries], + ) + + def _mark_exhausted( + self, + entry: PooledCredential, + status_code: Optional[int], + error_context: Optional[Dict[str, Any]] = None, + ) -> PooledCredential: + normalized_error = _normalize_error_context(error_context) + updated = replace( + entry, + last_status=STATUS_EXHAUSTED, + last_status_at=time.time(), + last_error_code=status_code, + last_error_reason=normalized_error.get("reason"), + last_error_message=normalized_error.get("message"), + last_error_reset_at=normalized_error.get("reset_at"), + ) + self._replace_entry(entry, updated) + self._persist() + return updated + + def _sync_anthropic_entry_from_credentials_file(self, entry: PooledCredential) -> PooledCredential: + """Sync a claude_code pool entry from ~/.claude/.credentials.json if tokens differ. + + OAuth refresh tokens are single-use. When something external (e.g. + Claude Code CLI, or another profile's pool) refreshes the token, it + writes the new pair to ~/.claude/.credentials.json. The pool entry's + refresh token becomes stale. This method detects that and syncs. + """ + if self.provider != "anthropic" or entry.source != "claude_code": + return entry + try: + from agent.anthropic_adapter import read_claude_code_credentials + creds = read_claude_code_credentials() + if not creds: + return entry + file_refresh = creds.get("refreshToken", "") + file_access = creds.get("accessToken", "") + file_expires = creds.get("expiresAt", 0) + # If the credentials file has a different token pair, sync it + if file_refresh and file_refresh != entry.refresh_token: + logger.debug("Pool entry %s: syncing tokens from credentials file (refresh token changed)", entry.id) + updated = replace( + entry, + access_token=file_access, + refresh_token=file_refresh, + expires_at_ms=file_expires, + last_status=None, + last_status_at=None, + last_error_code=None, + ) + self._replace_entry(entry, updated) + self._persist() + return updated + except Exception as exc: + logger.debug("Failed to sync from credentials file: %s", exc) + return entry + + def _sync_codex_entry_from_cli(self, entry: PooledCredential) -> PooledCredential: + """Sync an openai-codex pool entry from ~/.codex/auth.json if tokens differ. + + OpenAI OAuth refresh tokens are single-use and rotate on every refresh. + When the Codex CLI (or another Hermes profile) refreshes its token, + the pool entry's refresh_token becomes stale. This method detects that + by comparing against ~/.codex/auth.json and syncing the fresh pair. + """ + if self.provider != "openai-codex": + return entry + try: + cli_tokens = _import_codex_cli_tokens() + if not cli_tokens: + return entry + cli_refresh = cli_tokens.get("refresh_token", "") + cli_access = cli_tokens.get("access_token", "") + if cli_refresh and cli_refresh != entry.refresh_token: + logger.debug("Pool entry %s: syncing tokens from ~/.codex/auth.json (refresh token changed)", entry.id) + updated = replace( + entry, + access_token=cli_access, + refresh_token=cli_refresh, + last_status=None, + last_status_at=None, + last_error_code=None, + ) + self._replace_entry(entry, updated) + self._persist() + return updated + except Exception as exc: + logger.debug("Failed to sync from ~/.codex/auth.json: %s", exc) + return entry + + def _sync_device_code_entry_to_auth_store(self, entry: PooledCredential) -> None: + """Write refreshed pool entry tokens back to auth.json providers. + + After a pool-level refresh, the pool entry has fresh tokens but + auth.json's ``providers.`` still holds the pre-refresh state. + On the next ``load_pool()``, ``_seed_from_singletons()`` reads that + stale state and can overwrite the fresh pool entry — potentially + re-seeding a consumed single-use refresh token. + + Applies to any OAuth provider whose singleton lives in auth.json + (currently Nous and OpenAI Codex). + """ + if entry.source != "device_code": + return + try: + with _auth_store_lock(): + auth_store = _load_auth_store() + if self.provider == "nous": + state = _load_provider_state(auth_store, "nous") + if state is None: + return + state["access_token"] = entry.access_token + if entry.refresh_token: + state["refresh_token"] = entry.refresh_token + if entry.expires_at: + state["expires_at"] = entry.expires_at + if entry.agent_key: + state["agent_key"] = entry.agent_key + if entry.agent_key_expires_at: + state["agent_key_expires_at"] = entry.agent_key_expires_at + for extra_key in ("obtained_at", "expires_in", "agent_key_id", + "agent_key_expires_in", "agent_key_reused", + "agent_key_obtained_at"): + val = entry.extra.get(extra_key) + if val is not None: + state[extra_key] = val + if entry.inference_base_url: + state["inference_base_url"] = entry.inference_base_url + _save_provider_state(auth_store, "nous", state) + + elif self.provider == "openai-codex": + state = _load_provider_state(auth_store, "openai-codex") + if not isinstance(state, dict): + return + tokens = state.get("tokens") + if not isinstance(tokens, dict): + return + tokens["access_token"] = entry.access_token + if entry.refresh_token: + tokens["refresh_token"] = entry.refresh_token + if entry.last_refresh: + state["last_refresh"] = entry.last_refresh + _save_provider_state(auth_store, "openai-codex", state) + + else: + return + + _save_auth_store(auth_store) + except Exception as exc: + logger.debug("Failed to sync %s pool entry back to auth store: %s", self.provider, exc) + + def _refresh_entry(self, entry: PooledCredential, *, force: bool) -> Optional[PooledCredential]: + if entry.auth_type != AUTH_TYPE_OAUTH or not entry.refresh_token: + if force: + self._mark_exhausted(entry, None) + return None + + try: + if self.provider == "anthropic": + from agent.anthropic_adapter import refresh_anthropic_oauth_pure + + refreshed = refresh_anthropic_oauth_pure( + entry.refresh_token, + use_json=entry.source.endswith("hermes_pkce"), + ) + updated = replace( + entry, + access_token=refreshed["access_token"], + refresh_token=refreshed["refresh_token"], + expires_at_ms=refreshed["expires_at_ms"], + ) + # Keep ~/.claude/.credentials.json in sync so that the + # fallback path (resolve_anthropic_token) and other profiles + # see the latest tokens. + if entry.source == "claude_code": + try: + from agent.anthropic_adapter import _write_claude_code_credentials + _write_claude_code_credentials( + refreshed["access_token"], + refreshed["refresh_token"], + refreshed["expires_at_ms"], + ) + except Exception as wexc: + logger.debug("Failed to write refreshed token to credentials file: %s", wexc) + elif self.provider == "openai-codex": + # Proactively sync from ~/.codex/auth.json before refresh. + # The Codex CLI (or another Hermes profile) may have already + # consumed our refresh_token. Syncing first avoids a + # "refresh_token_reused" error when the CLI has a newer pair. + synced = self._sync_codex_entry_from_cli(entry) + if synced is not entry: + entry = synced + refreshed = auth_mod.refresh_codex_oauth_pure( + entry.access_token, + entry.refresh_token, + ) + updated = replace( + entry, + access_token=refreshed["access_token"], + refresh_token=refreshed["refresh_token"], + last_refresh=refreshed.get("last_refresh"), + ) + elif self.provider == "nous": + nous_state = { + "access_token": entry.access_token, + "refresh_token": entry.refresh_token, + "client_id": entry.client_id, + "portal_base_url": entry.portal_base_url, + "inference_base_url": entry.inference_base_url, + "token_type": entry.token_type, + "scope": entry.scope, + "obtained_at": entry.obtained_at, + "expires_at": entry.expires_at, + "agent_key": entry.agent_key, + "agent_key_expires_at": entry.agent_key_expires_at, + "tls": entry.tls, + } + refreshed = auth_mod.refresh_nous_oauth_from_state( + nous_state, + min_key_ttl_seconds=DEFAULT_AGENT_KEY_MIN_TTL_SECONDS, + force_refresh=force, + force_mint=force, + ) + # Apply returned fields: dataclass fields via replace, extras via dict update + field_updates = {} + extra_updates = dict(entry.extra) + _field_names = {f.name for f in fields(entry)} + for k, v in refreshed.items(): + if k in _field_names: + field_updates[k] = v + elif k in _EXTRA_KEYS: + extra_updates[k] = v + updated = replace(entry, extra=extra_updates, **field_updates) + else: + return entry + except Exception as exc: + logger.debug("Credential refresh failed for %s/%s: %s", self.provider, entry.id, exc) + # For anthropic claude_code entries: the refresh token may have been + # consumed by another process. Check if ~/.claude/.credentials.json + # has a newer token pair and retry once. + if self.provider == "anthropic" and entry.source == "claude_code": + synced = self._sync_anthropic_entry_from_credentials_file(entry) + if synced.refresh_token != entry.refresh_token: + logger.debug("Retrying refresh with synced token from credentials file") + try: + from agent.anthropic_adapter import refresh_anthropic_oauth_pure + refreshed = refresh_anthropic_oauth_pure( + synced.refresh_token, + use_json=synced.source.endswith("hermes_pkce"), + ) + updated = replace( + synced, + access_token=refreshed["access_token"], + refresh_token=refreshed["refresh_token"], + expires_at_ms=refreshed["expires_at_ms"], + last_status=STATUS_OK, + last_status_at=None, + last_error_code=None, + ) + self._replace_entry(synced, updated) + self._persist() + try: + from agent.anthropic_adapter import _write_claude_code_credentials + _write_claude_code_credentials( + refreshed["access_token"], + refreshed["refresh_token"], + refreshed["expires_at_ms"], + ) + except Exception as wexc: + logger.debug("Failed to write refreshed token to credentials file (retry path): %s", wexc) + return updated + except Exception as retry_exc: + logger.debug("Retry refresh also failed: %s", retry_exc) + elif not self._entry_needs_refresh(synced): + # Credentials file had a valid (non-expired) token — use it directly + logger.debug("Credentials file has valid token, using without refresh") + return synced + # For openai-codex: the refresh_token may have been consumed by + # the Codex CLI between our proactive sync and the refresh call. + # Re-sync and retry once. + if self.provider == "openai-codex": + synced = self._sync_codex_entry_from_cli(entry) + if synced.refresh_token != entry.refresh_token: + logger.debug("Retrying Codex refresh with synced token from ~/.codex/auth.json") + try: + refreshed = auth_mod.refresh_codex_oauth_pure( + synced.access_token, + synced.refresh_token, + ) + updated = replace( + synced, + access_token=refreshed["access_token"], + refresh_token=refreshed["refresh_token"], + last_refresh=refreshed.get("last_refresh"), + last_status=STATUS_OK, + last_status_at=None, + last_error_code=None, + ) + self._replace_entry(synced, updated) + self._persist() + self._sync_device_code_entry_to_auth_store(updated) + try: + _write_codex_cli_tokens( + updated.access_token, + updated.refresh_token, + last_refresh=updated.last_refresh, + ) + except Exception as wexc: + logger.debug("Failed to write refreshed Codex tokens to CLI file (retry): %s", wexc) + return updated + except Exception as retry_exc: + logger.debug("Codex retry refresh also failed: %s", retry_exc) + elif not self._entry_needs_refresh(synced): + logger.debug("Codex CLI has valid token, using without refresh") + self._sync_device_code_entry_to_auth_store(synced) + return synced + self._mark_exhausted(entry, None) + return None + + updated = replace( + updated, + last_status=STATUS_OK, + last_status_at=None, + last_error_code=None, + last_error_reason=None, + last_error_message=None, + last_error_reset_at=None, + ) + self._replace_entry(entry, updated) + self._persist() + # Sync refreshed tokens back to auth.json providers so that + # _seed_from_singletons() on the next load_pool() sees fresh state + # instead of re-seeding stale/consumed tokens. + self._sync_device_code_entry_to_auth_store(updated) + # Write refreshed tokens back to ~/.codex/auth.json so Codex CLI + # and VS Code don't hit "refresh_token_reused" on their next refresh. + if self.provider == "openai-codex": + try: + _write_codex_cli_tokens( + updated.access_token, + updated.refresh_token, + last_refresh=updated.last_refresh, + ) + except Exception as wexc: + logger.debug("Failed to write refreshed Codex tokens to CLI file: %s", wexc) + return updated + + def _entry_needs_refresh(self, entry: PooledCredential) -> bool: + if entry.auth_type != AUTH_TYPE_OAUTH: + return False + if self.provider == "anthropic": + if entry.expires_at_ms is None: + return False + return int(entry.expires_at_ms) <= int(time.time() * 1000) + 120_000 + if self.provider == "openai-codex": + return _codex_access_token_is_expiring( + entry.access_token, + CODEX_ACCESS_TOKEN_REFRESH_SKEW_SECONDS, + ) + if self.provider == "nous": + # Nous refresh/mint can require network access and should happen when + # runtime credentials are actually resolved, not merely when the pool + # is enumerated for listing, migration, or selection. + return False + return False + + def select(self) -> Optional[PooledCredential]: + with self._lock: + return self._select_unlocked() + + def _available_entries(self, *, clear_expired: bool = False, refresh: bool = False) -> List[PooledCredential]: + """Return entries not currently in exhaustion cooldown. + + When *clear_expired* is True, entries whose cooldown has elapsed are + reset to STATUS_OK and persisted. When *refresh* is True, entries + that need a token refresh are refreshed (skipped on failure). + """ + now = time.time() + cleared_any = False + available: List[PooledCredential] = [] + for entry in self._entries: + # For anthropic claude_code entries, sync from the credentials file + # before any status/refresh checks. This picks up tokens refreshed + # by other processes (Claude Code CLI, other Hermes profiles). + if (self.provider == "anthropic" and entry.source == "claude_code" + and entry.last_status == STATUS_EXHAUSTED): + synced = self._sync_anthropic_entry_from_credentials_file(entry) + if synced is not entry: + entry = synced + cleared_any = True + # For openai-codex entries, sync from ~/.codex/auth.json before + # any status/refresh checks. This picks up tokens refreshed by + # the Codex CLI or another Hermes profile. + if (self.provider == "openai-codex" + and entry.last_status == STATUS_EXHAUSTED + and entry.refresh_token): + synced = self._sync_codex_entry_from_cli(entry) + if synced is not entry: + entry = synced + cleared_any = True + if entry.last_status == STATUS_EXHAUSTED: + exhausted_until = _exhausted_until(entry) + if exhausted_until is not None and now < exhausted_until: + continue + if clear_expired: + cleared = replace( + entry, + last_status=STATUS_OK, + last_status_at=None, + last_error_code=None, + last_error_reason=None, + last_error_message=None, + last_error_reset_at=None, + ) + self._replace_entry(entry, cleared) + entry = cleared + cleared_any = True + if refresh and self._entry_needs_refresh(entry): + refreshed = self._refresh_entry(entry, force=False) + if refreshed is None: + continue + entry = refreshed + available.append(entry) + if cleared_any: + self._persist() + return available + + def _select_unlocked(self) -> Optional[PooledCredential]: + available = self._available_entries(clear_expired=True, refresh=True) + if not available: + self._current_id = None + logger.info("credential pool: no available entries (all exhausted or empty)") + return None + + if self._strategy == STRATEGY_RANDOM: + entry = random.choice(available) + self._current_id = entry.id + return entry + + if self._strategy == STRATEGY_LEAST_USED and len(available) > 1: + entry = min(available, key=lambda e: e.request_count) + self._current_id = entry.id + return entry + + if self._strategy == STRATEGY_ROUND_ROBIN and len(available) > 1: + entry = available[0] + rotated = [candidate for candidate in self._entries if candidate.id != entry.id] + rotated.append(replace(entry, priority=len(self._entries) - 1)) + self._entries = [replace(candidate, priority=idx) for idx, candidate in enumerate(rotated)] + self._persist() + self._current_id = entry.id + return self.current() or entry + + entry = available[0] + self._current_id = entry.id + return entry + + def peek(self) -> Optional[PooledCredential]: + current = self.current() + if current is not None: + return current + available = self._available_entries() + return available[0] if available else None + + def mark_exhausted_and_rotate( + self, + *, + status_code: Optional[int], + error_context: Optional[Dict[str, Any]] = None, + ) -> Optional[PooledCredential]: + with self._lock: + entry = self.current() or self._select_unlocked() + if entry is None: + return None + _label = entry.label or entry.id[:8] + logger.info( + "credential pool: marking %s exhausted (status=%s), rotating", + _label, status_code, + ) + self._mark_exhausted(entry, status_code, error_context) + self._current_id = None + next_entry = self._select_unlocked() + if next_entry: + _next_label = next_entry.label or next_entry.id[:8] + logger.info("credential pool: rotated to %s", _next_label) + return next_entry + + def acquire_lease(self, credential_id: Optional[str] = None) -> Optional[str]: + """Acquire a soft lease on a credential. + + If a specific credential_id is provided, lease that entry directly. + Otherwise prefer the least-leased available credential, using priority as + a stable tie-breaker. When every credential is already at the soft cap, + still return the least-leased one instead of blocking. + """ + with self._lock: + if credential_id: + self._active_leases[credential_id] = self._active_leases.get(credential_id, 0) + 1 + self._current_id = credential_id + return credential_id + + available = self._available_entries(clear_expired=True, refresh=True) + if not available: + return None + + below_cap = [ + entry for entry in available + if self._active_leases.get(entry.id, 0) < self._max_concurrent + ] + candidates = below_cap if below_cap else available + chosen = min( + candidates, + key=lambda entry: (self._active_leases.get(entry.id, 0), entry.priority), + ) + self._active_leases[chosen.id] = self._active_leases.get(chosen.id, 0) + 1 + self._current_id = chosen.id + return chosen.id + + def release_lease(self, credential_id: str) -> None: + """Release a previously acquired credential lease.""" + with self._lock: + count = self._active_leases.get(credential_id, 0) + if count <= 1: + self._active_leases.pop(credential_id, None) + else: + self._active_leases[credential_id] = count - 1 + + def try_refresh_current(self) -> Optional[PooledCredential]: + with self._lock: + return self._try_refresh_current_unlocked() + + def _try_refresh_current_unlocked(self) -> Optional[PooledCredential]: + entry = self.current() + if entry is None: + return None + refreshed = self._refresh_entry(entry, force=True) + if refreshed is not None: + self._current_id = refreshed.id + return refreshed + + def reset_statuses(self) -> int: + count = 0 + new_entries = [] + for entry in self._entries: + if entry.last_status or entry.last_status_at or entry.last_error_code: + new_entries.append( + replace( + entry, + last_status=None, + last_status_at=None, + last_error_code=None, + last_error_reason=None, + last_error_message=None, + last_error_reset_at=None, + ) + ) + count += 1 + else: + new_entries.append(entry) + if count: + self._entries = new_entries + self._persist() + return count + + def remove_index(self, index: int) -> Optional[PooledCredential]: + if index < 1 or index > len(self._entries): + return None + removed = self._entries.pop(index - 1) + self._entries = [ + replace(entry, priority=new_priority) + for new_priority, entry in enumerate(self._entries) + ] + self._persist() + if self._current_id == removed.id: + self._current_id = None + return removed + + def resolve_target(self, target: Any) -> Tuple[Optional[int], Optional[PooledCredential], Optional[str]]: + raw = str(target or "").strip() + if not raw: + return None, None, "No credential target provided." + + for idx, entry in enumerate(self._entries, start=1): + if entry.id == raw: + return idx, entry, None + + label_matches = [ + (idx, entry) + for idx, entry in enumerate(self._entries, start=1) + if entry.label.strip().lower() == raw.lower() + ] + if len(label_matches) == 1: + return label_matches[0][0], label_matches[0][1], None + if len(label_matches) > 1: + return None, None, f'Ambiguous credential label "{raw}". Use the numeric index or entry id instead.' + if raw.isdigit(): + index = int(raw) + if 1 <= index <= len(self._entries): + return index, self._entries[index - 1], None + return None, None, f"No credential #{index}." + return None, None, f'No credential matching "{raw}".' + + def add_entry(self, entry: PooledCredential) -> PooledCredential: + entry = replace(entry, priority=_next_priority(self._entries)) + self._entries.append(entry) + self._persist() + return entry + + +def _upsert_entry(entries: List[PooledCredential], provider: str, source: str, payload: Dict[str, Any]) -> bool: + existing_idx = None + for idx, entry in enumerate(entries): + if entry.source == source: + existing_idx = idx + break + + if existing_idx is None: + payload.setdefault("id", uuid.uuid4().hex[:6]) + payload.setdefault("priority", _next_priority(entries)) + payload.setdefault("label", payload.get("label") or source) + entries.append(PooledCredential.from_dict(provider, payload)) + return True + + existing = entries[existing_idx] + field_updates = {} + extra_updates = {} + _field_names = {f.name for f in fields(existing)} + for key, value in payload.items(): + if key in {"id", "priority"} or value is None: + continue + if key == "label" and existing.label: + continue + if key in _field_names: + if getattr(existing, key) != value: + field_updates[key] = value + elif key in _EXTRA_KEYS: + if existing.extra.get(key) != value: + extra_updates[key] = value + if field_updates or extra_updates: + if extra_updates: + field_updates["extra"] = {**existing.extra, **extra_updates} + entries[existing_idx] = replace(existing, **field_updates) + return True + return False + + +def _normalize_pool_priorities(provider: str, entries: List[PooledCredential]) -> bool: + if provider != "anthropic": + return False + + source_rank = { + "env:ANTHROPIC_TOKEN": 0, + "env:CLAUDE_CODE_OAUTH_TOKEN": 1, + "hermes_pkce": 2, + "claude_code": 3, + "env:ANTHROPIC_API_KEY": 4, + } + manual_entries = sorted( + (entry for entry in entries if _is_manual_source(entry.source)), + key=lambda entry: entry.priority, + ) + seeded_entries = sorted( + (entry for entry in entries if not _is_manual_source(entry.source)), + key=lambda entry: ( + source_rank.get(entry.source, len(source_rank)), + entry.priority, + entry.label, + ), + ) + + ordered = [*manual_entries, *seeded_entries] + id_to_idx = {entry.id: idx for idx, entry in enumerate(entries)} + changed = False + for new_priority, entry in enumerate(ordered): + if entry.priority != new_priority: + entries[id_to_idx[entry.id]] = replace(entry, priority=new_priority) + changed = True + return changed + + +def _seed_from_singletons(provider: str, entries: List[PooledCredential]) -> Tuple[bool, Set[str]]: + changed = False + active_sources: Set[str] = set() + auth_store = _load_auth_store() + + if provider == "anthropic": + # Only auto-discover external credentials (Claude Code, Hermes PKCE) + # when the user has explicitly configured anthropic as their provider. + # Without this gate, auxiliary client fallback chains silently read + # ~/.claude/.credentials.json without user consent. See PR #4210. + try: + from hermes_cli.auth import is_provider_explicitly_configured + if not is_provider_explicitly_configured("anthropic"): + return changed, active_sources + except ImportError: + pass + + from agent.anthropic_adapter import read_claude_code_credentials, read_hermes_oauth_credentials + + for source_name, creds in ( + ("hermes_pkce", read_hermes_oauth_credentials()), + ("claude_code", read_claude_code_credentials()), + ): + if creds and creds.get("accessToken"): + # Check if user explicitly removed this source + try: + from hermes_cli.auth import is_source_suppressed + if is_source_suppressed(provider, source_name): + continue + except ImportError: + pass + active_sources.add(source_name) + changed |= _upsert_entry( + entries, + provider, + source_name, + { + "source": source_name, + "auth_type": AUTH_TYPE_OAUTH, + "access_token": creds.get("accessToken", ""), + "refresh_token": creds.get("refreshToken"), + "expires_at_ms": creds.get("expiresAt"), + "label": label_from_token(creds.get("accessToken", ""), source_name), + }, + ) + + elif provider == "nous": + state = _load_provider_state(auth_store, "nous") + if state: + active_sources.add("device_code") + changed |= _upsert_entry( + entries, + provider, + "device_code", + { + "source": "device_code", + "auth_type": AUTH_TYPE_OAUTH, + "access_token": state.get("access_token", ""), + "refresh_token": state.get("refresh_token"), + "expires_at": state.get("expires_at"), + "token_type": state.get("token_type"), + "scope": state.get("scope"), + "client_id": state.get("client_id"), + "portal_base_url": state.get("portal_base_url"), + "inference_base_url": state.get("inference_base_url"), + "agent_key": state.get("agent_key"), + "agent_key_expires_at": state.get("agent_key_expires_at"), + "tls": state.get("tls") if isinstance(state.get("tls"), dict) else None, + "label": label_from_token(state.get("access_token", ""), "device_code"), + }, + ) + + elif provider == "openai-codex": + state = _load_provider_state(auth_store, "openai-codex") + tokens = state.get("tokens") if isinstance(state, dict) else None + # Fallback: import from Codex CLI (~/.codex/auth.json) if Hermes auth + # store has no tokens. This mirrors resolve_codex_runtime_credentials() + # so that load_pool() and list_authenticated_providers() detect tokens + # that only exist in the Codex CLI shared file. + if not (isinstance(tokens, dict) and tokens.get("access_token")): + try: + from hermes_cli.auth import _import_codex_cli_tokens, _save_codex_tokens + cli_tokens = _import_codex_cli_tokens() + if cli_tokens: + logger.info("Importing Codex CLI tokens into Hermes auth store.") + _save_codex_tokens(cli_tokens) + # Re-read state after import + auth_store = _load_auth_store() + state = _load_provider_state(auth_store, "openai-codex") + tokens = state.get("tokens") if isinstance(state, dict) else None + except Exception as exc: + logger.debug("Codex CLI token import failed: %s", exc) + if isinstance(tokens, dict) and tokens.get("access_token"): + active_sources.add("device_code") + changed |= _upsert_entry( + entries, + provider, + "device_code", + { + "source": "device_code", + "auth_type": AUTH_TYPE_OAUTH, + "access_token": tokens.get("access_token", ""), + "refresh_token": tokens.get("refresh_token"), + "base_url": "https://chatgpt.com/backend-api/codex", + "last_refresh": state.get("last_refresh"), + "label": label_from_token(tokens.get("access_token", ""), "device_code"), + }, + ) + + return changed, active_sources + + +def _seed_from_env(provider: str, entries: List[PooledCredential]) -> Tuple[bool, Set[str]]: + changed = False + active_sources: Set[str] = set() + if provider == "openrouter": + token = os.getenv("OPENROUTER_API_KEY", "").strip() + if token: + source = "env:OPENROUTER_API_KEY" + active_sources.add(source) + changed |= _upsert_entry( + entries, + provider, + source, + { + "source": source, + "auth_type": AUTH_TYPE_API_KEY, + "access_token": token, + "base_url": OPENROUTER_BASE_URL, + "label": "OPENROUTER_API_KEY", + }, + ) + return changed, active_sources + + pconfig = PROVIDER_REGISTRY.get(provider) + if not pconfig or pconfig.auth_type != AUTH_TYPE_API_KEY: + return changed, active_sources + + env_url = "" + if pconfig.base_url_env_var: + env_url = os.getenv(pconfig.base_url_env_var, "").strip().rstrip("/") + + env_vars = list(pconfig.api_key_env_vars) + if provider == "anthropic": + env_vars = [ + "ANTHROPIC_TOKEN", + "CLAUDE_CODE_OAUTH_TOKEN", + "ANTHROPIC_API_KEY", + ] + + for env_var in env_vars: + token = os.getenv(env_var, "").strip() + if not token: + continue + source = f"env:{env_var}" + active_sources.add(source) + auth_type = AUTH_TYPE_OAUTH if provider == "anthropic" and not token.startswith("sk-ant-api") else AUTH_TYPE_API_KEY + base_url = env_url or pconfig.inference_base_url + if provider == "kimi-coding": + base_url = _resolve_kimi_base_url(token, pconfig.inference_base_url, env_url) + elif provider == "zai": + base_url = _resolve_zai_base_url(token, pconfig.inference_base_url, env_url) + changed |= _upsert_entry( + entries, + provider, + source, + { + "source": source, + "auth_type": auth_type, + "access_token": token, + "base_url": base_url, + "label": env_var, + }, + ) + return changed, active_sources + + +def _prune_stale_seeded_entries(entries: List[PooledCredential], active_sources: Set[str]) -> bool: + retained = [ + entry + for entry in entries + if _is_manual_source(entry.source) + or entry.source in active_sources + or not ( + entry.source.startswith("env:") + or entry.source in {"claude_code", "hermes_pkce"} + ) + ] + if len(retained) == len(entries): + return False + entries[:] = retained + return True + + +def _seed_custom_pool(pool_key: str, entries: List[PooledCredential]) -> Tuple[bool, Set[str]]: + """Seed a custom endpoint pool from custom_providers config and model config.""" + changed = False + active_sources: Set[str] = set() + + # Seed from the custom_providers config entry's api_key field + cp_config = _get_custom_provider_config(pool_key) + if cp_config: + api_key = str(cp_config.get("api_key") or "").strip() + base_url = str(cp_config.get("base_url") or "").strip().rstrip("/") + name = str(cp_config.get("name") or "").strip() + if api_key: + source = f"config:{name}" + active_sources.add(source) + changed |= _upsert_entry( + entries, + pool_key, + source, + { + "source": source, + "auth_type": AUTH_TYPE_API_KEY, + "access_token": api_key, + "base_url": base_url, + "label": name or source, + }, + ) + + # Seed from model.api_key if model.provider=='custom' and model.base_url matches + try: + config = _load_config_safe() + model_cfg = config.get("model") if config else None + if isinstance(model_cfg, dict): + model_provider = str(model_cfg.get("provider") or "").strip().lower() + model_base_url = str(model_cfg.get("base_url") or "").strip().rstrip("/") + model_api_key = "" + for k in ("api_key", "api"): + v = model_cfg.get(k) + if isinstance(v, str) and v.strip(): + model_api_key = v.strip() + break + if model_provider == "custom" and model_base_url and model_api_key: + # Check if this model's base_url matches our custom provider + matched_key = get_custom_provider_pool_key(model_base_url) + if matched_key == pool_key: + source = "model_config" + active_sources.add(source) + changed |= _upsert_entry( + entries, + pool_key, + source, + { + "source": source, + "auth_type": AUTH_TYPE_API_KEY, + "access_token": model_api_key, + "base_url": model_base_url, + "label": "model_config", + }, + ) + except Exception: + pass + + return changed, active_sources + + +def load_pool(provider: str) -> CredentialPool: + provider = (provider or "").strip().lower() + raw_entries = read_credential_pool(provider) + entries = [PooledCredential.from_dict(provider, payload) for payload in raw_entries] + + if provider.startswith(CUSTOM_POOL_PREFIX): + # Custom endpoint pool — seed from custom_providers config and model config + custom_changed, custom_sources = _seed_custom_pool(provider, entries) + changed = custom_changed + changed |= _prune_stale_seeded_entries(entries, custom_sources) + else: + singleton_changed, singleton_sources = _seed_from_singletons(provider, entries) + env_changed, env_sources = _seed_from_env(provider, entries) + changed = singleton_changed or env_changed + changed |= _prune_stale_seeded_entries(entries, singleton_sources | env_sources) + changed |= _normalize_pool_priorities(provider, entries) + + if changed: + write_credential_pool( + provider, + [entry.to_dict() for entry in sorted(entries, key=lambda item: item.priority)], + ) + return CredentialPool(provider, entries) diff --git a/mindcli/_vendor/agent/display.py b/mindcli/_vendor/agent/display.py new file mode 100644 index 0000000..063b7bb --- /dev/null +++ b/mindcli/_vendor/agent/display.py @@ -0,0 +1,1037 @@ +"""CLI presentation -- spinner, kawaii faces, tool preview formatting. + +Pure display functions and classes with no AIAgent dependency. +Used by AIAgent._execute_tool_calls for CLI feedback. +""" + +import logging +import os +import sys +import threading +import time +from dataclasses import dataclass, field +from difflib import unified_diff +from pathlib import Path + +from utils import safe_json_loads + +# ANSI escape codes for coloring tool failure indicators +_RED = "\033[31m" +_RESET = "\033[0m" + +logger = logging.getLogger(__name__) + +_ANSI_RESET = "\033[0m" + +# Diff colors — resolved lazily from the skin engine so they adapt +# to light/dark themes. Falls back to sensible defaults on import +# failure. We cache after first resolution for performance. +_diff_colors_cached: dict[str, str] | None = None + + +def _diff_ansi() -> dict[str, str]: + """Return ANSI escapes for diff display, resolved from the active skin.""" + global _diff_colors_cached + if _diff_colors_cached is not None: + return _diff_colors_cached + + # Defaults that work on dark terminals + dim = "\033[38;2;150;150;150m" + file_c = "\033[38;2;180;160;255m" + hunk = "\033[38;2;120;120;140m" + minus = "\033[38;2;255;255;255;48;2;120;20;20m" + plus = "\033[38;2;255;255;255;48;2;20;90;20m" + + try: + from hermes_cli.skin_engine import get_active_skin + skin = get_active_skin() + + def _hex_fg(key: str, fallback_rgb: tuple[int, int, int]) -> str: + h = skin.get_color(key, "") + if h and len(h) == 7 and h[0] == "#": + r, g, b = int(h[1:3], 16), int(h[3:5], 16), int(h[5:7], 16) + return f"\033[38;2;{r};{g};{b}m" + r, g, b = fallback_rgb + return f"\033[38;2;{r};{g};{b}m" + + dim = _hex_fg("banner_dim", (150, 150, 150)) + file_c = _hex_fg("session_label", (180, 160, 255)) + hunk = _hex_fg("session_border", (120, 120, 140)) + # minus/plus use background colors — derive from ui_error/ui_ok + err_h = skin.get_color("ui_error", "#ef5350") + ok_h = skin.get_color("ui_ok", "#4caf50") + if err_h and len(err_h) == 7: + er, eg, eb = int(err_h[1:3], 16), int(err_h[3:5], 16), int(err_h[5:7], 16) + # Use a dark tinted version as background + minus = f"\033[38;2;255;255;255;48;2;{max(er//2,20)};{max(eg//4,10)};{max(eb//4,10)}m" + if ok_h and len(ok_h) == 7: + or_, og, ob = int(ok_h[1:3], 16), int(ok_h[3:5], 16), int(ok_h[5:7], 16) + plus = f"\033[38;2;255;255;255;48;2;{max(or_//4,10)};{max(og//2,20)};{max(ob//4,10)}m" + except Exception: + pass + + _diff_colors_cached = { + "dim": dim, "file": file_c, "hunk": hunk, + "minus": minus, "plus": plus, + } + return _diff_colors_cached + + +# Module-level helpers — each call resolves from the active skin lazily. +def _diff_dim(): return _diff_ansi()["dim"] +def _diff_file(): return _diff_ansi()["file"] +def _diff_hunk(): return _diff_ansi()["hunk"] +def _diff_minus(): return _diff_ansi()["minus"] +def _diff_plus(): return _diff_ansi()["plus"] +_MAX_INLINE_DIFF_FILES = 6 +_MAX_INLINE_DIFF_LINES = 80 + + +@dataclass +class LocalEditSnapshot: + """Pre-tool filesystem snapshot used to render diffs locally after writes.""" + paths: list[Path] = field(default_factory=list) + before: dict[str, str | None] = field(default_factory=dict) + +# ========================================================================= +# Configurable tool preview length (0 = no limit) +# Set once at startup by CLI or gateway from display.tool_preview_length config. +# ========================================================================= +_tool_preview_max_len: int = 0 # 0 = unlimited + + +def set_tool_preview_max_len(n: int) -> None: + """Set the global max length for tool call previews. 0 = no limit.""" + global _tool_preview_max_len + _tool_preview_max_len = max(int(n), 0) if n else 0 + + +def get_tool_preview_max_len() -> int: + """Return the configured max preview length (0 = unlimited).""" + return _tool_preview_max_len + + +# ========================================================================= +# Skin-aware helpers (lazy import to avoid circular deps) +# ========================================================================= + +def _get_skin(): + """Get the active skin config, or None if not available.""" + try: + from hermes_cli.skin_engine import get_active_skin + return get_active_skin() + except Exception: + return None + + +def get_skin_tool_prefix() -> str: + """Get tool output prefix character from active skin.""" + skin = _get_skin() + if skin: + return skin.tool_prefix + return "┊" + + +def get_tool_emoji(tool_name: str, default: str = "⚡") -> str: + """Get the display emoji for a tool. + + Resolution order: + 1. Active skin's ``tool_emojis`` overrides (if a skin is loaded) + 2. Tool registry's per-tool ``emoji`` field + 3. *default* fallback + """ + # 1. Skin override + skin = _get_skin() + if skin and skin.tool_emojis: + override = skin.tool_emojis.get(tool_name) + if override: + return override + # 2. Registry default + try: + from tools.registry import registry + emoji = registry.get_emoji(tool_name, default="") + if emoji: + return emoji + except Exception: + pass + # 3. Hardcoded fallback + return default + + +# ========================================================================= +# Tool preview (one-line summary of a tool call's primary argument) +# ========================================================================= + +def _oneline(text: str) -> str: + """Collapse whitespace (including newlines) to single spaces.""" + return " ".join(text.split()) + + +def build_tool_preview(tool_name: str, args: dict, max_len: int | None = None) -> str | None: + """Build a short preview of a tool call's primary argument for display. + + *max_len* controls truncation. ``None`` (default) defers to the global + ``_tool_preview_max_len`` set via config; ``0`` means unlimited. + """ + if max_len is None: + max_len = _tool_preview_max_len + if not args: + return None + primary_args = { + "terminal": "command", "web_search": "query", "web_extract": "urls", + "read_file": "path", "write_file": "path", "patch": "path", + "search_files": "pattern", "browser_navigate": "url", + "browser_click": "ref", "browser_type": "text", + "image_generate": "prompt", "text_to_speech": "text", + "vision_analyze": "question", "mixture_of_agents": "user_prompt", + "skill_view": "name", "skills_list": "category", + "cronjob": "action", + "execute_code": "code", "delegate_task": "goal", + "clarify": "question", "skill_manage": "name", + } + + if tool_name == "process": + action = args.get("action", "") + sid = args.get("session_id", "") + data = args.get("data", "") + timeout_val = args.get("timeout") + parts = [action] + if sid: + parts.append(sid[:16]) + if data: + parts.append(f'"{_oneline(data[:20])}"') + if timeout_val and action == "wait": + parts.append(f"{timeout_val}s") + return " ".join(parts) if parts else None + + if tool_name == "todo": + todos_arg = args.get("todos") + merge = args.get("merge", False) + if todos_arg is None: + return "reading task list" + elif merge: + return f"updating {len(todos_arg)} task(s)" + else: + return f"planning {len(todos_arg)} task(s)" + + if tool_name == "session_search": + query = _oneline(args.get("query", "")) + return f"recall: \"{query[:25]}{'...' if len(query) > 25 else ''}\"" + + if tool_name == "memory": + action = args.get("action", "") + target = args.get("target", "") + if action == "add": + content = _oneline(args.get("content", "")) + return f"+{target}: \"{content[:25]}{'...' if len(content) > 25 else ''}\"" + elif action == "replace": + return f"~{target}: \"{_oneline(args.get('old_text', '')[:20])}\"" + elif action == "remove": + return f"-{target}: \"{_oneline(args.get('old_text', '')[:20])}\"" + return action + + if tool_name == "send_message": + target = args.get("target", "?") + msg = _oneline(args.get("message", "")) + if len(msg) > 20: + msg = msg[:17] + "..." + return f"to {target}: \"{msg}\"" + + if tool_name.startswith("rl_"): + rl_previews = { + "rl_list_environments": "listing envs", + "rl_select_environment": args.get("name", ""), + "rl_get_current_config": "reading config", + "rl_edit_config": f"{args.get('field', '')}={args.get('value', '')}", + "rl_start_training": "starting", + "rl_check_status": args.get("run_id", "")[:16], + "rl_stop_training": f"stopping {args.get('run_id', '')[:16]}", + "rl_get_results": args.get("run_id", "")[:16], + "rl_list_runs": "listing runs", + "rl_test_inference": f"{args.get('num_steps', 3)} steps", + } + return rl_previews.get(tool_name) + + key = primary_args.get(tool_name) + if not key: + for fallback_key in ("query", "text", "command", "path", "name", "prompt", "code", "goal"): + if fallback_key in args: + key = fallback_key + break + + if not key or key not in args: + return None + + value = args[key] + if isinstance(value, list): + value = value[0] if value else "" + + preview = _oneline(str(value)) + if not preview: + return None + if max_len > 0 and len(preview) > max_len: + preview = preview[:max_len - 3] + "..." + return preview + + +# ========================================================================= +# Inline diff previews for write actions +# ========================================================================= + +def _resolved_path(path: str) -> Path: + """Resolve a possibly-relative filesystem path against the current cwd.""" + candidate = Path(os.path.expanduser(path)) + if candidate.is_absolute(): + return candidate + return Path.cwd() / candidate + + +def _snapshot_text(path: Path) -> str | None: + """Return UTF-8 file content, or None for missing/unreadable files.""" + try: + return path.read_text(encoding="utf-8") + except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError, OSError): + return None + + +def _display_diff_path(path: Path) -> str: + """Prefer cwd-relative paths in diffs when available.""" + try: + return str(path.resolve().relative_to(Path.cwd().resolve())) + except Exception: + return str(path) + + +def _resolve_skill_manage_paths(args: dict) -> list[Path]: + """Resolve skill_manage write targets to filesystem paths.""" + action = args.get("action") + name = args.get("name") + if not action or not name: + return [] + + from tools.skill_manager_tool import _find_skill, _resolve_skill_dir + + if action == "create": + skill_dir = _resolve_skill_dir(name, args.get("category")) + return [skill_dir / "SKILL.md"] + + existing = _find_skill(name) + if not existing: + return [] + + skill_dir = Path(existing["path"]) + if action in {"edit", "patch"}: + file_path = args.get("file_path") + return [skill_dir / file_path] if file_path else [skill_dir / "SKILL.md"] + if action in {"write_file", "remove_file"}: + file_path = args.get("file_path") + return [skill_dir / file_path] if file_path else [] + if action == "delete": + files = [path for path in sorted(skill_dir.rglob("*")) if path.is_file()] + return files + return [] + + +def _resolve_local_edit_paths(tool_name: str, function_args: dict | None) -> list[Path]: + """Resolve local filesystem targets for write-capable tools.""" + if not isinstance(function_args, dict): + return [] + + if tool_name == "write_file": + path = function_args.get("path") + return [_resolved_path(path)] if path else [] + + if tool_name == "patch": + path = function_args.get("path") + return [_resolved_path(path)] if path else [] + + if tool_name == "skill_manage": + return _resolve_skill_manage_paths(function_args) + + return [] + + +def capture_local_edit_snapshot(tool_name: str, function_args: dict | None) -> LocalEditSnapshot | None: + """Capture before-state for local write previews.""" + paths = _resolve_local_edit_paths(tool_name, function_args) + if not paths: + return None + + snapshot = LocalEditSnapshot(paths=paths) + for path in paths: + snapshot.before[str(path)] = _snapshot_text(path) + return snapshot + + +def _result_succeeded(result: str | None) -> bool: + """Conservatively detect whether a tool result represents success.""" + if not result: + return False + data = safe_json_loads(result) + if data is None: + return False + if not isinstance(data, dict): + return False + if data.get("error"): + return False + if "success" in data: + return bool(data.get("success")) + return True + + +def _diff_from_snapshot(snapshot: LocalEditSnapshot | None) -> str | None: + """Generate unified diff text from a stored before-state and current files.""" + if not snapshot: + return None + + chunks: list[str] = [] + for path in snapshot.paths: + before = snapshot.before.get(str(path)) + after = _snapshot_text(path) + if before == after: + continue + + display_path = _display_diff_path(path) + diff = "".join( + unified_diff( + [] if before is None else before.splitlines(keepends=True), + [] if after is None else after.splitlines(keepends=True), + fromfile=f"a/{display_path}", + tofile=f"b/{display_path}", + ) + ) + if diff: + chunks.append(diff) + + if not chunks: + return None + return "".join(chunk if chunk.endswith("\n") else chunk + "\n" for chunk in chunks) + + +def extract_edit_diff( + tool_name: str, + result: str | None, + *, + function_args: dict | None = None, + snapshot: LocalEditSnapshot | None = None, +) -> str | None: + """Extract a unified diff from a file-edit tool result.""" + if tool_name == "patch" and result: + data = safe_json_loads(result) + if isinstance(data, dict): + diff = data.get("diff") + if isinstance(diff, str) and diff.strip(): + return diff + + if tool_name not in {"write_file", "patch", "skill_manage"}: + return None + if not _result_succeeded(result): + return None + return _diff_from_snapshot(snapshot) + + +def _emit_inline_diff(diff_text: str, print_fn) -> bool: + """Emit rendered diff text through the CLI's prompt_toolkit-safe printer.""" + if print_fn is None or not diff_text: + return False + try: + print_fn(" ┊ review diff") + for line in diff_text.rstrip("\n").splitlines(): + print_fn(line) + return True + except Exception: + return False + + +def _render_inline_unified_diff(diff: str) -> list[str]: + """Render unified diff lines in Hermes' inline transcript style.""" + rendered: list[str] = [] + from_file = None + to_file = None + + for raw_line in diff.splitlines(): + if raw_line.startswith("--- "): + from_file = raw_line[4:].strip() + continue + if raw_line.startswith("+++ "): + to_file = raw_line[4:].strip() + if from_file or to_file: + rendered.append(f"{_diff_file()}{from_file or 'a/?'} → {to_file or 'b/?'}{_ANSI_RESET}") + continue + if raw_line.startswith("@@"): + rendered.append(f"{_diff_hunk()}{raw_line}{_ANSI_RESET}") + continue + if raw_line.startswith("-"): + rendered.append(f"{_diff_minus()}{raw_line}{_ANSI_RESET}") + continue + if raw_line.startswith("+"): + rendered.append(f"{_diff_plus()}{raw_line}{_ANSI_RESET}") + continue + if raw_line.startswith(" "): + rendered.append(f"{_diff_dim()}{raw_line}{_ANSI_RESET}") + continue + if raw_line: + rendered.append(raw_line) + + return rendered + + +def _split_unified_diff_sections(diff: str) -> list[str]: + """Split a unified diff into per-file sections.""" + sections: list[list[str]] = [] + current: list[str] = [] + + for line in diff.splitlines(): + if line.startswith("--- ") and current: + sections.append(current) + current = [line] + continue + current.append(line) + + if current: + sections.append(current) + + return ["\n".join(section) for section in sections if section] + + +def _summarize_rendered_diff_sections( + diff: str, + *, + max_files: int = _MAX_INLINE_DIFF_FILES, + max_lines: int = _MAX_INLINE_DIFF_LINES, +) -> list[str]: + """Render diff sections while capping file count and total line count.""" + sections = _split_unified_diff_sections(diff) + rendered: list[str] = [] + omitted_files = 0 + omitted_lines = 0 + + for idx, section in enumerate(sections): + if idx >= max_files: + omitted_files += 1 + omitted_lines += len(_render_inline_unified_diff(section)) + continue + + section_lines = _render_inline_unified_diff(section) + remaining_budget = max_lines - len(rendered) + if remaining_budget <= 0: + omitted_lines += len(section_lines) + omitted_files += 1 + continue + + if len(section_lines) <= remaining_budget: + rendered.extend(section_lines) + continue + + rendered.extend(section_lines[:remaining_budget]) + omitted_lines += len(section_lines) - remaining_budget + omitted_files += 1 + max(0, len(sections) - idx - 1) + for leftover in sections[idx + 1:]: + omitted_lines += len(_render_inline_unified_diff(leftover)) + break + + if omitted_files or omitted_lines: + summary = f"… omitted {omitted_lines} diff line(s)" + if omitted_files: + summary += f" across {omitted_files} additional file(s)/section(s)" + rendered.append(f"{_diff_hunk()}{summary}{_ANSI_RESET}") + + return rendered + + +def render_edit_diff_with_delta( + tool_name: str, + result: str | None, + *, + function_args: dict | None = None, + snapshot: LocalEditSnapshot | None = None, + print_fn=None, +) -> bool: + """Render an edit diff inline without taking over the terminal UI.""" + diff = extract_edit_diff( + tool_name, + result, + function_args=function_args, + snapshot=snapshot, + ) + if not diff: + return False + try: + rendered_lines = _summarize_rendered_diff_sections(diff) + except Exception as exc: + logger.debug("Could not render inline diff: %s", exc) + return False + return _emit_inline_diff("\n".join(rendered_lines), print_fn) + + +# ========================================================================= +# KawaiiSpinner +# ========================================================================= + +class KawaiiSpinner: + """Animated spinner with kawaii faces for CLI feedback during tool execution.""" + + SPINNERS = { + 'dots': ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'], + 'bounce': ['⠁', '⠂', '⠄', '⡀', '⢀', '⠠', '⠐', '⠈'], + 'grow': ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█', '▇', '▆', '▅', '▄', '▃', '▂'], + 'arrows': ['←', '↖', '↑', '↗', '→', '↘', '↓', '↙'], + 'star': ['✶', '✷', '✸', '✹', '✺', '✹', '✸', '✷'], + 'moon': ['🌑', '🌒', '🌓', '🌔', '🌕', '🌖', '🌗', '🌘'], + 'pulse': ['◜', '◠', '◝', '◞', '◡', '◟'], + 'brain': ['🧠', '💭', '💡', '✨', '💫', '🌟', '💡', '💭'], + 'sparkle': ['⁺', '˚', '*', '✧', '✦', '✧', '*', '˚'], + } + + KAWAII_WAITING = [ + "(｡◕‿◕｡)", "(◕‿◕✿)", "٩(◕‿◕｡)۶", "(✿◠‿◠)", "( ˘▽˘)っ", + "♪(´ε` )", "(◕ᴗ◕✿)", "ヾ(＾∇＾)", "(≧◡≦)", "(★ω★)", + ] + + KAWAII_THINKING = [ + "(｡•́︿•̀｡)", "(◔_◔)", "(¬‿¬)", "( •_•)>⌐■-■", "(⌐■_■)", + "(´･_･`)", "◉_◉", "(°ロ°)", "( ˘⌣˘)♡", "ヽ(>∀<☆)☆", + "٩(๑❛ᴗ❛๑)۶", "(⊙_⊙)", "(¬_¬)", "( ͡° ͜ʖ ͡°)", "ಠ_ಠ", + ] + + THINKING_VERBS = [ + "pondering", "contemplating", "musing", "cogitating", "ruminating", + "deliberating", "mulling", "reflecting", "processing", "reasoning", + "analyzing", "computing", "synthesizing", "formulating", "brainstorming", + ] + + def __init__(self, message: str = "", spinner_type: str = 'dots', print_fn=None): + self.message = message + self.spinner_frames = self.SPINNERS.get(spinner_type, self.SPINNERS['dots']) + self.running = False + self.thread = None + self.frame_idx = 0 + self.start_time = None + self.last_line_len = 0 + # Optional callable to route all output through (e.g. a no-op for silent + # background agents). When set, bypasses self._out entirely so that + # agents with _print_fn overridden remain fully silent. + self._print_fn = print_fn + # Capture stdout NOW, before any redirect_stdout(devnull) from + # child agents can replace sys.stdout with a black hole. + self._out = sys.stdout + + def _write(self, text: str, end: str = '\n', flush: bool = False): + """Write to the stdout captured at spinner creation time. + + If a print_fn was supplied at construction, all output is routed through + it instead — allowing callers to silence the spinner with a no-op lambda. + """ + if self._print_fn is not None: + try: + self._print_fn(text) + except Exception: + pass + return + try: + self._out.write(text + end) + if flush: + self._out.flush() + except (ValueError, OSError): + pass + + @property + def _is_tty(self) -> bool: + """Check if output is a real terminal, safe against closed streams.""" + try: + return hasattr(self._out, 'isatty') and self._out.isatty() + except (ValueError, OSError): + return False + + def _is_patch_stdout_proxy(self) -> bool: + """Return True when stdout is prompt_toolkit's StdoutProxy. + + patch_stdout wraps sys.stdout in a StdoutProxy that queues writes and + injects newlines around each flush(). The \\r overwrite never lands on + the correct line — each spinner frame ends up on its own line. + + The CLI already drives a TUI widget (_spinner_text) for spinner display, + so KawaiiSpinner's \\r-based animation is redundant under StdoutProxy. + """ + try: + from prompt_toolkit.patch_stdout import StdoutProxy + return isinstance(self._out, StdoutProxy) + except ImportError: + return False + + def _animate(self): + # When stdout is not a real terminal (e.g. Docker, systemd, pipe), + # skip the animation entirely — it creates massive log bloat. + # Just log the start once and let stop() log the completion. + if not self._is_tty: + self._write(f" [tool] {self.message}", flush=True) + while self.running: + time.sleep(0.5) + return + + # When running inside prompt_toolkit's patch_stdout context the CLI + # renders spinner state via a dedicated TUI widget (_spinner_text). + # Driving a \r-based animation here too causes visual overdraw: the + # StdoutProxy injects newlines around each flush, so every frame lands + # on a new line and overwrites the status bar. + if self._is_patch_stdout_proxy(): + while self.running: + time.sleep(0.1) + return + + # Cache skin wings at start (avoid per-frame imports) + skin = _get_skin() + wings = skin.get_spinner_wings() if skin else [] + + while self.running: + if os.getenv("HERMES_SPINNER_PAUSE"): + time.sleep(0.1) + continue + frame = self.spinner_frames[self.frame_idx % len(self.spinner_frames)] + elapsed = time.time() - self.start_time + if wings: + left, right = wings[self.frame_idx % len(wings)] + line = f" {left} {frame} {self.message} {right} ({elapsed:.1f}s)" + else: + line = f" {frame} {self.message} ({elapsed:.1f}s)" + pad = max(self.last_line_len - len(line), 0) + self._write(f"\r{line}{' ' * pad}", end='', flush=True) + self.last_line_len = len(line) + self.frame_idx += 1 + time.sleep(0.12) + + def start(self): + if self.running: + return + self.running = True + self.start_time = time.time() + self.thread = threading.Thread(target=self._animate, daemon=True) + self.thread.start() + + def update_text(self, new_message: str): + self.message = new_message + + def print_above(self, text: str): + """Print a line above the spinner without disrupting animation. + + Clears the current spinner line, prints the text, and lets the + next animation tick redraw the spinner on the line below. + Thread-safe: uses the captured stdout reference (self._out). + Works inside redirect_stdout(devnull) because _write bypasses + sys.stdout and writes to the stdout captured at spinner creation. + """ + if not self.running: + self._write(f" {text}", flush=True) + return + # Clear spinner line with spaces (not \033[K) to avoid garbled escape + # codes when prompt_toolkit's patch_stdout is active — same approach + # as stop(). Then print text; spinner redraws on next tick. + blanks = ' ' * max(self.last_line_len + 5, 40) + self._write(f"\r{blanks}\r {text}", flush=True) + + def stop(self, final_message: str = None): + self.running = False + if self.thread: + self.thread.join(timeout=0.5) + + is_tty = self._is_tty + if is_tty: + # Clear the spinner line with spaces instead of \033[K to avoid + # garbled escape codes when prompt_toolkit's patch_stdout is active. + blanks = ' ' * max(self.last_line_len + 5, 40) + self._write(f"\r{blanks}\r", end='', flush=True) + if final_message: + elapsed = f" ({time.time() - self.start_time:.1f}s)" if self.start_time else "" + if is_tty: + self._write(f" {final_message}", flush=True) + else: + self._write(f" [done] {final_message}{elapsed}", flush=True) + + def __enter__(self): + self.start() + return self + + def __exit__(self, exc_type, exc_val, exc_tb): + self.stop() + return False + + +# ========================================================================= +# Cute tool message (completion line that replaces the spinner) +# ========================================================================= + +def _detect_tool_failure(tool_name: str, result: str | None) -> tuple[bool, str]: + """Inspect a tool result string for signs of failure. + + Returns ``(is_failure, suffix)`` where *suffix* is an informational tag + like ``" [exit 1]"`` for terminal failures, or ``" [error]"`` for generic + failures. On success, returns ``(False, "")``. + """ + if result is None: + return False, "" + + if tool_name == "terminal": + data = safe_json_loads(result) + if isinstance(data, dict): + exit_code = data.get("exit_code") + if exit_code is not None and exit_code != 0: + return True, f" [exit {exit_code}]" + return False, "" + + # Memory-specific: distinguish "full" from real errors + if tool_name == "memory": + data = safe_json_loads(result) + if isinstance(data, dict): + if data.get("success") is False and "exceed the limit" in data.get("error", ""): + return True, " [full]" + + # Generic heuristic for non-terminal tools + lower = result[:500].lower() + if '"error"' in lower or '"failed"' in lower or result.startswith("Error"): + return True, " [error]" + + return False, "" + + +def get_cute_tool_message( + tool_name: str, args: dict, duration: float, result: str | None = None, +) -> str: + """Generate a formatted tool completion line for CLI quiet mode. + + Format: ``| {emoji} {verb:9} {detail} {duration}`` + + When *result* is provided the line is checked for failure indicators. + Failed tool calls get a red prefix and an informational suffix. + """ + dur = f"{duration:.1f}s" + is_failure, failure_suffix = _detect_tool_failure(tool_name, result) + skin_prefix = get_skin_tool_prefix() + + def _trunc(s, n=40): + s = str(s) + if _tool_preview_max_len == 0: + return s # no limit + return (s[:n-3] + "...") if len(s) > n else s + + def _path(p, n=35): + p = str(p) + if _tool_preview_max_len == 0: + return p # no limit + return ("..." + p[-(n-3):]) if len(p) > n else p + + def _wrap(line: str) -> str: + """Apply skin tool prefix and failure suffix.""" + if skin_prefix != "┊": + line = line.replace("┊", skin_prefix, 1) + if not is_failure: + return line + return f"{line}{failure_suffix}" + + if tool_name == "web_search": + return _wrap(f"┊ 🔍 search {_trunc(args.get('query', ''), 42)} {dur}") + if tool_name == "web_extract": + urls = args.get("urls", []) + if urls: + url = urls[0] if isinstance(urls, list) else str(urls) + domain = url.replace("https://", "").replace("http://", "").split("/")[0] + extra = f" +{len(urls)-1}" if len(urls) > 1 else "" + return _wrap(f"┊ 📄 fetch {_trunc(domain, 35)}{extra} {dur}") + return _wrap(f"┊ 📄 fetch pages {dur}") + if tool_name == "web_crawl": + url = args.get("url", "") + domain = url.replace("https://", "").replace("http://", "").split("/")[0] + return _wrap(f"┊ 🕸️ crawl {_trunc(domain, 35)} {dur}") + if tool_name == "terminal": + return _wrap(f"┊ 💻 $ {_trunc(args.get('command', ''), 42)} {dur}") + if tool_name == "process": + action = args.get("action", "?") + sid = args.get("session_id", "")[:12] + labels = {"list": "ls processes", "poll": f"poll {sid}", "log": f"log {sid}", + "wait": f"wait {sid}", "kill": f"kill {sid}", "write": f"write {sid}", "submit": f"submit {sid}"} + return _wrap(f"┊ ⚙️ proc {labels.get(action, f'{action} {sid}')} {dur}") + if tool_name == "read_file": + return _wrap(f"┊ 📖 read {_path(args.get('path', ''))} {dur}") + if tool_name == "write_file": + return _wrap(f"┊ ✍️ write {_path(args.get('path', ''))} {dur}") + if tool_name == "patch": + return _wrap(f"┊ 🔧 patch {_path(args.get('path', ''))} {dur}") + if tool_name == "search_files": + pattern = _trunc(args.get("pattern", ""), 35) + target = args.get("target", "content") + verb = "find" if target == "files" else "grep" + return _wrap(f"┊ 🔎 {verb:9} {pattern} {dur}") + if tool_name == "browser_navigate": + url = args.get("url", "") + domain = url.replace("https://", "").replace("http://", "").split("/")[0] + return _wrap(f"┊ 🌐 navigate {_trunc(domain, 35)} {dur}") + if tool_name == "browser_snapshot": + mode = "full" if args.get("full") else "compact" + return _wrap(f"┊ 📸 snapshot {mode} {dur}") + if tool_name == "browser_click": + return _wrap(f"┊ 👆 click {args.get('ref', '?')} {dur}") + if tool_name == "browser_type": + return _wrap(f"┊ ⌨️ type \"{_trunc(args.get('text', ''), 30)}\" {dur}") + if tool_name == "browser_scroll": + d = args.get("direction", "down") + arrow = {"down": "↓", "up": "↑", "right": "→", "left": "←"}.get(d, "↓") + return _wrap(f"┊ {arrow} scroll {d} {dur}") + if tool_name == "browser_back": + return _wrap(f"┊ ◀️ back {dur}") + if tool_name == "browser_press": + return _wrap(f"┊ ⌨️ press {args.get('key', '?')} {dur}") + if tool_name == "browser_get_images": + return _wrap(f"┊ 🖼️ images extracting {dur}") + if tool_name == "browser_vision": + return _wrap(f"┊ 👁️ vision analyzing page {dur}") + if tool_name == "todo": + todos_arg = args.get("todos") + merge = args.get("merge", False) + if todos_arg is None: + return _wrap(f"┊ 📋 plan reading tasks {dur}") + elif merge: + return _wrap(f"┊ 📋 plan update {len(todos_arg)} task(s) {dur}") + else: + return _wrap(f"┊ 📋 plan {len(todos_arg)} task(s) {dur}") + if tool_name == "session_search": + return _wrap(f"┊ 🔍 recall \"{_trunc(args.get('query', ''), 35)}\" {dur}") + if tool_name == "memory": + action = args.get("action", "?") + target = args.get("target", "") + if action == "add": + return _wrap(f"┊ 🧠 memory +{target}: \"{_trunc(args.get('content', ''), 30)}\" {dur}") + elif action == "replace": + return _wrap(f"┊ 🧠 memory ~{target}: \"{_trunc(args.get('old_text', ''), 20)}\" {dur}") + elif action == "remove": + return _wrap(f"┊ 🧠 memory -{target}: \"{_trunc(args.get('old_text', ''), 20)}\" {dur}") + return _wrap(f"┊ 🧠 memory {action} {dur}") + if tool_name == "skills_list": + return _wrap(f"┊ 📚 skills list {args.get('category', 'all')} {dur}") + if tool_name == "skill_view": + return _wrap(f"┊ 📚 skill {_trunc(args.get('name', ''), 30)} {dur}") + if tool_name == "image_generate": + return _wrap(f"┊ 🎨 create {_trunc(args.get('prompt', ''), 35)} {dur}") + if tool_name == "text_to_speech": + return _wrap(f"┊ 🔊 speak {_trunc(args.get('text', ''), 30)} {dur}") + if tool_name == "vision_analyze": + return _wrap(f"┊ 👁️ vision {_trunc(args.get('question', ''), 30)} {dur}") + if tool_name == "mixture_of_agents": + return _wrap(f"┊ 🧠 reason {_trunc(args.get('user_prompt', ''), 30)} {dur}") + if tool_name == "send_message": + return _wrap(f"┊ 📨 send {args.get('target', '?')}: \"{_trunc(args.get('message', ''), 25)}\" {dur}") + if tool_name == "cronjob": + action = args.get("action", "?") + if action == "create": + skills = args.get("skills") or ([] if not args.get("skill") else [args.get("skill")]) + label = args.get("name") or (skills[0] if skills else None) or args.get("prompt", "task") + return _wrap(f"┊ ⏰ cron create {_trunc(label, 24)} {dur}") + if action == "list": + return _wrap(f"┊ ⏰ cron listing {dur}") + return _wrap(f"┊ ⏰ cron {action} {args.get('job_id', '')} {dur}") + if tool_name.startswith("rl_"): + rl = { + "rl_list_environments": "list envs", "rl_select_environment": f"select {args.get('name', '')}", + "rl_get_current_config": "get config", "rl_edit_config": f"set {args.get('field', '?')}", + "rl_start_training": "start training", "rl_check_status": f"status {args.get('run_id', '?')[:12]}", + "rl_stop_training": f"stop {args.get('run_id', '?')[:12]}", "rl_get_results": f"results {args.get('run_id', '?')[:12]}", + "rl_list_runs": "list runs", "rl_test_inference": "test inference", + } + return _wrap(f"┊ 🧪 rl {rl.get(tool_name, tool_name.replace('rl_', ''))} {dur}") + if tool_name == "execute_code": + code = args.get("code", "") + first_line = code.strip().split("\n")[0] if code.strip() else "" + return _wrap(f"┊ 🐍 exec {_trunc(first_line, 35)} {dur}") + if tool_name == "delegate_task": + tasks = args.get("tasks") + if tasks and isinstance(tasks, list): + return _wrap(f"┊ 🔀 delegate {len(tasks)} parallel tasks {dur}") + return _wrap(f"┊ 🔀 delegate {_trunc(args.get('goal', ''), 35)} {dur}") + + preview = build_tool_preview(tool_name, args) or "" + return _wrap(f"┊ ⚡ {tool_name[:9]:9} {_trunc(preview, 35)} {dur}") + + +# ========================================================================= +# Honcho session line (one-liner with clickable OSC 8 hyperlink) +# ========================================================================= + +_DIM = "\033[2m" +_SKY_BLUE = "\033[38;5;117m" +_ANSI_RESET = "\033[0m" + + +# ========================================================================= +# Context pressure display (CLI user-facing warnings) +# ========================================================================= + +# ANSI color codes for context pressure tiers +_CYAN = "\033[36m" +_YELLOW = "\033[33m" +_BOLD = "\033[1m" +_DIM_ANSI = "\033[2m" + +# Bar characters +_BAR_FILLED = "▰" +_BAR_EMPTY = "▱" +_BAR_WIDTH = 20 + + +def format_context_pressure( + compaction_progress: float, + threshold_tokens: int, + threshold_percent: float, + compression_enabled: bool = True, +) -> str: + """Build a formatted context pressure line for CLI display. + + The bar and percentage show progress toward the compaction threshold, + NOT the raw context window. 100% = compaction fires. + + Args: + compaction_progress: How close to compaction (0.0–1.0, 1.0 = fires). + threshold_tokens: Compaction threshold in tokens. + threshold_percent: Compaction threshold as a fraction of context window. + compression_enabled: Whether auto-compression is active. + """ + pct_int = min(int(compaction_progress * 100), 100) + filled = min(int(compaction_progress * _BAR_WIDTH), _BAR_WIDTH) + bar = _BAR_FILLED * filled + _BAR_EMPTY * (_BAR_WIDTH - filled) + + threshold_k = f"{threshold_tokens // 1000}k" if threshold_tokens >= 1000 else str(threshold_tokens) + threshold_pct_int = int(threshold_percent * 100) + + color = f"{_BOLD}{_YELLOW}" + icon = "⚠" + if compression_enabled: + hint = "compaction approaching" + else: + hint = "no auto-compaction" + + return ( + f" {color}{icon} context {bar} {pct_int}% to compaction{_ANSI_RESET}" + f" {_DIM_ANSI}{threshold_k} threshold ({threshold_pct_int}%) · {hint}{_ANSI_RESET}" + ) + + +def format_context_pressure_gateway( + compaction_progress: float, + threshold_percent: float, + compression_enabled: bool = True, +) -> str: + """Build a plain-text context pressure notification for messaging platforms. + + No ANSI — just Unicode and plain text suitable for Telegram/Discord/etc. + The percentage shows progress toward the compaction threshold. + """ + pct_int = min(int(compaction_progress * 100), 100) + filled = min(int(compaction_progress * _BAR_WIDTH), _BAR_WIDTH) + bar = _BAR_FILLED * filled + _BAR_EMPTY * (_BAR_WIDTH - filled) + + threshold_pct_int = int(threshold_percent * 100) + + icon = "⚠️" + if compression_enabled: + hint = f"Context compaction approaching (threshold: {threshold_pct_int}% of window)." + else: + hint = "Auto-compaction is disabled — context may be truncated." + + return f"{icon} Context: {bar} {pct_int}% to compaction\n{hint}" diff --git a/mindcli/_vendor/agent/error_classifier.py b/mindcli/_vendor/agent/error_classifier.py new file mode 100644 index 0000000..e436e55 --- /dev/null +++ b/mindcli/_vendor/agent/error_classifier.py @@ -0,0 +1,820 @@ +"""API error classification for smart failover and recovery. + +Provides a structured taxonomy of API errors and a priority-ordered +classification pipeline that determines the correct recovery action +(retry, rotate credential, fallback to another provider, compress +context, or abort). + +Replaces scattered inline string-matching with a centralized classifier +that the main retry loop in run_agent.py consults for every API failure. +""" + +from __future__ import annotations + +import enum +import logging +from dataclasses import dataclass, field +from typing import Any, Dict, Optional + +logger = logging.getLogger(__name__) + + +# ── Error taxonomy ────────────────────────────────────────────────────── + +class FailoverReason(enum.Enum): + """Why an API call failed — determines recovery strategy.""" + + # Authentication / authorization + auth = "auth" # Transient auth (401/403) — refresh/rotate + auth_permanent = "auth_permanent" # Auth failed after refresh — abort + + # Billing / quota + billing = "billing" # 402 or confirmed credit exhaustion — rotate immediately + rate_limit = "rate_limit" # 429 or quota-based throttling — backoff then rotate + + # Server-side + overloaded = "overloaded" # 503/529 — provider overloaded, backoff + server_error = "server_error" # 500/502 — internal server error, retry + + # Transport + timeout = "timeout" # Connection/read timeout — rebuild client + retry + + # Context / payload + context_overflow = "context_overflow" # Context too large — compress, not failover + payload_too_large = "payload_too_large" # 413 — compress payload + + # Model + model_not_found = "model_not_found" # 404 or invalid model — fallback to different model + + # Request format + format_error = "format_error" # 400 bad request — abort or strip + retry + + # Provider-specific + thinking_signature = "thinking_signature" # Anthropic thinking block sig invalid + long_context_tier = "long_context_tier" # Anthropic "extra usage" tier gate + + # Catch-all + unknown = "unknown" # Unclassifiable — retry with backoff + + +# ── Classification result ─────────────────────────────────────────────── + +@dataclass +class ClassifiedError: + """Structured classification of an API error with recovery hints.""" + + reason: FailoverReason + status_code: Optional[int] = None + provider: Optional[str] = None + model: Optional[str] = None + message: str = "" + error_context: Dict[str, Any] = field(default_factory=dict) + + # Recovery action hints — the retry loop checks these instead of + # re-classifying the error itself. + retryable: bool = True + should_compress: bool = False + should_rotate_credential: bool = False + should_fallback: bool = False + + @property + def is_auth(self) -> bool: + return self.reason in (FailoverReason.auth, FailoverReason.auth_permanent) + + + +# ── Provider-specific patterns ────────────────────────────────────────── + +# Patterns that indicate billing exhaustion (not transient rate limit) +_BILLING_PATTERNS = [ + "insufficient credits", + "insufficient_quota", + "credit balance", + "credits have been exhausted", + "top up your credits", + "payment required", + "billing hard limit", + "exceeded your current quota", + "account is deactivated", + "plan does not include", +] + +# Patterns that indicate rate limiting (transient, will resolve) +_RATE_LIMIT_PATTERNS = [ + "rate limit", + "rate_limit", + "too many requests", + "throttled", + "requests per minute", + "tokens per minute", + "requests per day", + "try again in", + "please retry after", + "resource_exhausted", + "rate increased too quickly", # Alibaba/DashScope throttling +] + +# Usage-limit patterns that need disambiguation (could be billing OR rate_limit) +_USAGE_LIMIT_PATTERNS = [ + "usage limit", + "quota", + "limit exceeded", + "key limit exceeded", +] + +# Patterns confirming usage limit is transient (not billing) +_USAGE_LIMIT_TRANSIENT_SIGNALS = [ + "try again", + "retry", + "resets at", + "reset in", + "wait", + "requests remaining", + "periodic", + "window", +] + +# Payload-too-large patterns detected from message text (no status_code attr). +# Proxies and some backends embed the HTTP status in the error message. +_PAYLOAD_TOO_LARGE_PATTERNS = [ + "request entity too large", + "payload too large", + "error code: 413", +] + +# Context overflow patterns +_CONTEXT_OVERFLOW_PATTERNS = [ + "context length", + "context size", + "maximum context", + "token limit", + "too many tokens", + "reduce the length", + "exceeds the limit", + "context window", + "prompt is too long", + "prompt exceeds max length", + "max_tokens", + "maximum number of tokens", + # vLLM / local inference server patterns + "exceeds the max_model_len", + "max_model_len", + "prompt length", # "engine prompt length X exceeds" + "input is too long", + "maximum model length", + # Ollama patterns + "context length exceeded", + "truncating input", + # llama.cpp / llama-server patterns + "slot context", # "slot context: N tokens, prompt N tokens" + "n_ctx_slot", + # Chinese error messages (some providers return these) + "超过最大长度", + "上下文长度", +] + +# Model not found patterns +_MODEL_NOT_FOUND_PATTERNS = [ + "is not a valid model", + "invalid model", + "model not found", + "model_not_found", + "does not exist", + "no such model", + "unknown model", + "unsupported model", +] + +# Auth patterns (non-status-code signals) +_AUTH_PATTERNS = [ + "invalid api key", + "invalid_api_key", + "authentication", + "unauthorized", + "forbidden", + "invalid token", + "token expired", + "token revoked", + "access denied", +] + +# Anthropic thinking block signature patterns +_THINKING_SIG_PATTERNS = [ + "signature", # Combined with "thinking" check +] + +# Transport error type names +_TRANSPORT_ERROR_TYPES = frozenset({ + "ReadTimeout", "ConnectTimeout", "PoolTimeout", + "ConnectError", "RemoteProtocolError", + "ConnectionError", "ConnectionResetError", + "ConnectionAbortedError", "BrokenPipeError", + "TimeoutError", "ReadError", + "ServerDisconnectedError", + # OpenAI SDK errors (not subclasses of Python builtins) + "APIConnectionError", + "APITimeoutError", +}) + +# Server disconnect patterns (no status code, but transport-level) +_SERVER_DISCONNECT_PATTERNS = [ + "server disconnected", + "peer closed connection", + "connection reset by peer", + "connection was closed", + "network connection lost", + "unexpected eof", + "incomplete chunked read", +] + + +# ── Classification pipeline ───────────────────────────────────────────── + +def classify_api_error( + error: Exception, + *, + provider: str = "", + model: str = "", + approx_tokens: int = 0, + context_length: int = 200000, + num_messages: int = 0, +) -> ClassifiedError: + """Classify an API error into a structured recovery recommendation. + + Priority-ordered pipeline: + 1. Special-case provider-specific patterns (thinking sigs, tier gates) + 2. HTTP status code + message-aware refinement + 3. Error code classification (from body) + 4. Message pattern matching (billing vs rate_limit vs context vs auth) + 5. Transport error heuristics + 6. Server disconnect + large session → context overflow + 7. Fallback: unknown (retryable with backoff) + + Args: + error: The exception from the API call. + provider: Current provider name (e.g. "openrouter", "anthropic"). + model: Current model slug. + approx_tokens: Approximate token count of the current context. + context_length: Maximum context length for the current model. + + Returns: + ClassifiedError with reason and recovery action hints. + """ + status_code = _extract_status_code(error) + error_type = type(error).__name__ + body = _extract_error_body(error) + error_code = _extract_error_code(body) + + # Build a comprehensive error message string for pattern matching. + # str(error) alone may not include the body message (e.g. OpenAI SDK's + # APIStatusError.__str__ returns the first arg, not the body). Append + # the body message so patterns like "try again" in 402 disambiguation + # are detected even when only present in the structured body. + # + # Also extract metadata.raw — OpenRouter wraps upstream provider errors + # inside {"error": {"message": "Provider returned error", "metadata": + # {"raw": ""}}} and the real error message (e.g. + # "context length exceeded") is only in the inner JSON. + _raw_msg = str(error).lower() + _body_msg = "" + _metadata_msg = "" + if isinstance(body, dict): + _err_obj = body.get("error", {}) + if isinstance(_err_obj, dict): + _body_msg = (_err_obj.get("message") or "").lower() + # Parse metadata.raw for wrapped provider errors + _metadata = _err_obj.get("metadata", {}) + if isinstance(_metadata, dict): + _raw_json = _metadata.get("raw") or "" + if isinstance(_raw_json, str) and _raw_json.strip(): + try: + import json + _inner = json.loads(_raw_json) + if isinstance(_inner, dict): + _inner_err = _inner.get("error", {}) + if isinstance(_inner_err, dict): + _metadata_msg = (_inner_err.get("message") or "").lower() + except (json.JSONDecodeError, TypeError): + pass + if not _body_msg: + _body_msg = (body.get("message") or "").lower() + # Combine all message sources for pattern matching + parts = [_raw_msg] + if _body_msg and _body_msg not in _raw_msg: + parts.append(_body_msg) + if _metadata_msg and _metadata_msg not in _raw_msg and _metadata_msg not in _body_msg: + parts.append(_metadata_msg) + error_msg = " ".join(parts) + provider_lower = (provider or "").strip().lower() + model_lower = (model or "").strip().lower() + + def _result(reason: FailoverReason, **overrides) -> ClassifiedError: + defaults = { + "reason": reason, + "status_code": status_code, + "provider": provider, + "model": model, + "message": _extract_message(error, body), + } + defaults.update(overrides) + return ClassifiedError(**defaults) + + # ── 1. Provider-specific patterns (highest priority) ──────────── + + # Anthropic thinking block signature invalid (400). + # Don't gate on provider — OpenRouter proxies Anthropic errors, so the + # provider may be "openrouter" even though the error is Anthropic-specific. + # The message pattern ("signature" + "thinking") is unique enough. + if ( + status_code == 400 + and "signature" in error_msg + and "thinking" in error_msg + ): + return _result( + FailoverReason.thinking_signature, + retryable=True, + should_compress=False, + ) + + # Anthropic long-context tier gate (429 "extra usage" + "long context") + if ( + status_code == 429 + and "extra usage" in error_msg + and "long context" in error_msg + ): + return _result( + FailoverReason.long_context_tier, + retryable=True, + should_compress=True, + ) + + # ── 2. HTTP status code classification ────────────────────────── + + if status_code is not None: + classified = _classify_by_status( + status_code, error_msg, error_code, body, + provider=provider_lower, model=model_lower, + approx_tokens=approx_tokens, context_length=context_length, + num_messages=num_messages, + result_fn=_result, + ) + if classified is not None: + return classified + + # ── 3. Error code classification ──────────────────────────────── + + if error_code: + classified = _classify_by_error_code(error_code, error_msg, _result) + if classified is not None: + return classified + + # ── 4. Message pattern matching (no status code) ──────────────── + + classified = _classify_by_message( + error_msg, error_type, + approx_tokens=approx_tokens, + context_length=context_length, + result_fn=_result, + ) + if classified is not None: + return classified + + # ── 5. Server disconnect + large session → context overflow ───── + # Must come BEFORE generic transport error catch — a disconnect on + # a large session is more likely context overflow than a transient + # transport hiccup. Without this ordering, RemoteProtocolError + # always maps to timeout regardless of session size. + + is_disconnect = any(p in error_msg for p in _SERVER_DISCONNECT_PATTERNS) + if is_disconnect and not status_code: + is_large = approx_tokens > context_length * 0.6 or approx_tokens > 120000 or num_messages > 200 + if is_large: + return _result( + FailoverReason.context_overflow, + retryable=True, + should_compress=True, + ) + return _result(FailoverReason.timeout, retryable=True) + + # ── 6. Transport / timeout heuristics ─────────────────────────── + + if error_type in _TRANSPORT_ERROR_TYPES or isinstance(error, (TimeoutError, ConnectionError, OSError)): + return _result(FailoverReason.timeout, retryable=True) + + # ── 7. Fallback: unknown ──────────────────────────────────────── + + return _result(FailoverReason.unknown, retryable=True) + + +# ── Status code classification ────────────────────────────────────────── + +def _classify_by_status( + status_code: int, + error_msg: str, + error_code: str, + body: dict, + *, + provider: str, + model: str, + approx_tokens: int, + context_length: int, + num_messages: int = 0, + result_fn, +) -> Optional[ClassifiedError]: + """Classify based on HTTP status code with message-aware refinement.""" + + if status_code == 401: + # Not retryable on its own — credential pool rotation and + # provider-specific refresh (Codex, Anthropic, Nous) run before + # the retryability check in run_agent.py. If those succeed, the + # loop `continue`s. If they fail, retryable=False ensures we + # hit the client-error abort path (which tries fallback first). + return result_fn( + FailoverReason.auth, + retryable=False, + should_rotate_credential=True, + should_fallback=True, + ) + + if status_code == 403: + # OpenRouter 403 "key limit exceeded" is actually billing + if "key limit exceeded" in error_msg or "spending limit" in error_msg: + return result_fn( + FailoverReason.billing, + retryable=False, + should_rotate_credential=True, + should_fallback=True, + ) + return result_fn( + FailoverReason.auth, + retryable=False, + should_fallback=True, + ) + + if status_code == 402: + return _classify_402(error_msg, result_fn) + + if status_code == 404: + if any(p in error_msg for p in _MODEL_NOT_FOUND_PATTERNS): + return result_fn( + FailoverReason.model_not_found, + retryable=False, + should_fallback=True, + ) + # Generic 404 — could be model or endpoint + return result_fn( + FailoverReason.model_not_found, + retryable=False, + should_fallback=True, + ) + + if status_code == 413: + return result_fn( + FailoverReason.payload_too_large, + retryable=True, + should_compress=True, + ) + + if status_code == 429: + # Already checked long_context_tier above; this is a normal rate limit + return result_fn( + FailoverReason.rate_limit, + retryable=True, + should_rotate_credential=True, + should_fallback=True, + ) + + if status_code == 400: + return _classify_400( + error_msg, error_code, body, + provider=provider, model=model, + approx_tokens=approx_tokens, + context_length=context_length, + num_messages=num_messages, + result_fn=result_fn, + ) + + if status_code in (500, 502): + return result_fn(FailoverReason.server_error, retryable=True) + + if status_code in (503, 529): + return result_fn(FailoverReason.overloaded, retryable=True) + + # Other 4xx — non-retryable + if 400 <= status_code < 500: + return result_fn( + FailoverReason.format_error, + retryable=False, + should_fallback=True, + ) + + # Other 5xx — retryable + if 500 <= status_code < 600: + return result_fn(FailoverReason.server_error, retryable=True) + + return None + + +def _classify_402(error_msg: str, result_fn) -> ClassifiedError: + """Disambiguate 402: billing exhaustion vs transient usage limit. + + The key insight from OpenClaw: some 402s are transient rate limits + disguised as payment errors. "Usage limit, try again in 5 minutes" + is NOT a billing problem — it's a periodic quota that resets. + """ + # Check for transient usage-limit signals first + has_usage_limit = any(p in error_msg for p in _USAGE_LIMIT_PATTERNS) + has_transient_signal = any(p in error_msg for p in _USAGE_LIMIT_TRANSIENT_SIGNALS) + + if has_usage_limit and has_transient_signal: + # Transient quota — treat as rate limit, not billing + return result_fn( + FailoverReason.rate_limit, + retryable=True, + should_rotate_credential=True, + should_fallback=True, + ) + + # Confirmed billing exhaustion + return result_fn( + FailoverReason.billing, + retryable=False, + should_rotate_credential=True, + should_fallback=True, + ) + + +def _classify_400( + error_msg: str, + error_code: str, + body: dict, + *, + provider: str, + model: str, + approx_tokens: int, + context_length: int, + num_messages: int = 0, + result_fn, +) -> ClassifiedError: + """Classify 400 Bad Request — context overflow, format error, or generic.""" + + # Context overflow from 400 + if any(p in error_msg for p in _CONTEXT_OVERFLOW_PATTERNS): + return result_fn( + FailoverReason.context_overflow, + retryable=True, + should_compress=True, + ) + + # Some providers return model-not-found as 400 instead of 404 (e.g. OpenRouter). + if any(p in error_msg for p in _MODEL_NOT_FOUND_PATTERNS): + return result_fn( + FailoverReason.model_not_found, + retryable=False, + should_fallback=True, + ) + + # Some providers return rate limit / billing errors as 400 instead of 429/402. + # Check these patterns before falling through to format_error. + if any(p in error_msg for p in _RATE_LIMIT_PATTERNS): + return result_fn( + FailoverReason.rate_limit, + retryable=True, + should_rotate_credential=True, + should_fallback=True, + ) + if any(p in error_msg for p in _BILLING_PATTERNS): + return result_fn( + FailoverReason.billing, + retryable=False, + should_rotate_credential=True, + should_fallback=True, + ) + + # Generic 400 + large session → probable context overflow + # Anthropic sometimes returns a bare "Error" message when context is too large + err_body_msg = "" + if isinstance(body, dict): + err_obj = body.get("error", {}) + if isinstance(err_obj, dict): + err_body_msg = (err_obj.get("message") or "").strip().lower() + # Responses API (and some providers) use flat body: {"message": "..."} + if not err_body_msg: + err_body_msg = (body.get("message") or "").strip().lower() + is_generic = len(err_body_msg) < 30 or err_body_msg in ("error", "") + is_large = approx_tokens > context_length * 0.4 or approx_tokens > 80000 or num_messages > 80 + + if is_generic and is_large: + return result_fn( + FailoverReason.context_overflow, + retryable=True, + should_compress=True, + ) + + # Non-retryable format error + return result_fn( + FailoverReason.format_error, + retryable=False, + should_fallback=True, + ) + + +# ── Error code classification ─────────────────────────────────────────── + +def _classify_by_error_code( + error_code: str, error_msg: str, result_fn, +) -> Optional[ClassifiedError]: + """Classify by structured error codes from the response body.""" + code_lower = error_code.lower() + + if code_lower in ("resource_exhausted", "throttled", "rate_limit_exceeded"): + return result_fn( + FailoverReason.rate_limit, + retryable=True, + should_rotate_credential=True, + ) + + if code_lower in ("insufficient_quota", "billing_not_active", "payment_required"): + return result_fn( + FailoverReason.billing, + retryable=False, + should_rotate_credential=True, + should_fallback=True, + ) + + if code_lower in ("model_not_found", "model_not_available", "invalid_model"): + return result_fn( + FailoverReason.model_not_found, + retryable=False, + should_fallback=True, + ) + + if code_lower in ("context_length_exceeded", "max_tokens_exceeded"): + return result_fn( + FailoverReason.context_overflow, + retryable=True, + should_compress=True, + ) + + return None + + +# ── Message pattern classification ────────────────────────────────────── + +def _classify_by_message( + error_msg: str, + error_type: str, + *, + approx_tokens: int, + context_length: int, + result_fn, +) -> Optional[ClassifiedError]: + """Classify based on error message patterns when no status code is available.""" + + # Payload-too-large patterns (from message text when no status_code) + if any(p in error_msg for p in _PAYLOAD_TOO_LARGE_PATTERNS): + return result_fn( + FailoverReason.payload_too_large, + retryable=True, + should_compress=True, + ) + + # Usage-limit patterns need the same disambiguation as 402: some providers + # surface "usage limit" errors without an HTTP status code. A transient + # signal ("try again", "resets at", …) means it's a periodic quota, not + # billing exhaustion. + has_usage_limit = any(p in error_msg for p in _USAGE_LIMIT_PATTERNS) + if has_usage_limit: + has_transient_signal = any(p in error_msg for p in _USAGE_LIMIT_TRANSIENT_SIGNALS) + if has_transient_signal: + return result_fn( + FailoverReason.rate_limit, + retryable=True, + should_rotate_credential=True, + should_fallback=True, + ) + return result_fn( + FailoverReason.billing, + retryable=False, + should_rotate_credential=True, + should_fallback=True, + ) + + # Billing patterns + if any(p in error_msg for p in _BILLING_PATTERNS): + return result_fn( + FailoverReason.billing, + retryable=False, + should_rotate_credential=True, + should_fallback=True, + ) + + # Rate limit patterns + if any(p in error_msg for p in _RATE_LIMIT_PATTERNS): + return result_fn( + FailoverReason.rate_limit, + retryable=True, + should_rotate_credential=True, + should_fallback=True, + ) + + # Context overflow patterns + if any(p in error_msg for p in _CONTEXT_OVERFLOW_PATTERNS): + return result_fn( + FailoverReason.context_overflow, + retryable=True, + should_compress=True, + ) + + # Auth patterns + # Auth errors should NOT be retried directly — the credential is invalid and + # retrying with the same key will always fail. Set retryable=False so the + # caller triggers credential rotation (should_rotate_credential=True) or + # provider fallback rather than an immediate retry loop. + if any(p in error_msg for p in _AUTH_PATTERNS): + return result_fn( + FailoverReason.auth, + retryable=False, + should_rotate_credential=True, + should_fallback=True, + ) + + # Model not found patterns + if any(p in error_msg for p in _MODEL_NOT_FOUND_PATTERNS): + return result_fn( + FailoverReason.model_not_found, + retryable=False, + should_fallback=True, + ) + + return None + + +# ── Helpers ───────────────────────────────────────────────────────────── + +def _extract_status_code(error: Exception) -> Optional[int]: + """Walk the error and its cause chain to find an HTTP status code.""" + current = error + for _ in range(5): # Max depth to prevent infinite loops + code = getattr(current, "status_code", None) + if isinstance(code, int): + return code + # Some SDKs use .status instead of .status_code + code = getattr(current, "status", None) + if isinstance(code, int) and 100 <= code < 600: + return code + # Walk cause chain + cause = getattr(current, "__cause__", None) or getattr(current, "__context__", None) + if cause is None or cause is current: + break + current = cause + return None + + +def _extract_error_body(error: Exception) -> dict: + """Extract the structured error body from an SDK exception.""" + body = getattr(error, "body", None) + if isinstance(body, dict): + return body + # Some errors have .response.json() + response = getattr(error, "response", None) + if response is not None: + try: + json_body = response.json() + if isinstance(json_body, dict): + return json_body + except Exception: + pass + return {} + + +def _extract_error_code(body: dict) -> str: + """Extract an error code string from the response body.""" + if not body: + return "" + error_obj = body.get("error", {}) + if isinstance(error_obj, dict): + code = error_obj.get("code") or error_obj.get("type") or "" + if isinstance(code, str) and code.strip(): + return code.strip() + # Top-level code + code = body.get("code") or body.get("error_code") or "" + if isinstance(code, (str, int)): + return str(code).strip() + return "" + + +def _extract_message(error: Exception, body: dict) -> str: + """Extract the most informative error message.""" + # Try structured body first + if body: + error_obj = body.get("error", {}) + if isinstance(error_obj, dict): + msg = error_obj.get("message", "") + if isinstance(msg, str) and msg.strip(): + return msg.strip()[:500] + msg = body.get("message", "") + if isinstance(msg, str) and msg.strip(): + return msg.strip()[:500] + # Fallback to str(error) + return str(error)[:500] diff --git a/mindcli/_vendor/agent/insights.py b/mindcli/_vendor/agent/insights.py new file mode 100644 index 0000000..a0929c9 --- /dev/null +++ b/mindcli/_vendor/agent/insights.py @@ -0,0 +1,789 @@ +""" +Session Insights Engine for Hermes Agent. + +Analyzes historical session data from the SQLite state database to produce +comprehensive usage insights — token consumption, cost estimates, tool usage +patterns, activity trends, model/platform breakdowns, and session metrics. + +Inspired by Claude Code's /insights command, adapted for Hermes Agent's +multi-platform architecture with additional cost estimation and platform +breakdown capabilities. + +Usage: + from agent.insights import InsightsEngine + engine = InsightsEngine(db) + report = engine.generate(days=30) + print(engine.format_terminal(report)) +""" + +import json +import time +from collections import Counter, defaultdict +from datetime import datetime +from typing import Any, Dict, List + +from agent.usage_pricing import ( + CanonicalUsage, + DEFAULT_PRICING, + estimate_usage_cost, + format_duration_compact, + has_known_pricing, +) + +_DEFAULT_PRICING = DEFAULT_PRICING + + +def _has_known_pricing(model_name: str, provider: str = None, base_url: str = None) -> bool: + """Check if a model has known pricing (vs unknown/custom endpoint).""" + return has_known_pricing(model_name, provider=provider, base_url=base_url) + + +def _estimate_cost( + session_or_model: Dict[str, Any] | str, + input_tokens: int = 0, + output_tokens: int = 0, + *, + cache_read_tokens: int = 0, + cache_write_tokens: int = 0, + provider: str = None, + base_url: str = None, +) -> tuple[float, str]: + """Estimate the USD cost for a session row or a model/token tuple.""" + if isinstance(session_or_model, dict): + session = session_or_model + model = session.get("model") or "" + usage = CanonicalUsage( + input_tokens=session.get("input_tokens") or 0, + output_tokens=session.get("output_tokens") or 0, + cache_read_tokens=session.get("cache_read_tokens") or 0, + cache_write_tokens=session.get("cache_write_tokens") or 0, + ) + provider = session.get("billing_provider") + base_url = session.get("billing_base_url") + else: + model = session_or_model or "" + usage = CanonicalUsage( + input_tokens=input_tokens, + output_tokens=output_tokens, + cache_read_tokens=cache_read_tokens, + cache_write_tokens=cache_write_tokens, + ) + result = estimate_usage_cost( + model, + usage, + provider=provider, + base_url=base_url, + ) + return float(result.amount_usd or 0.0), result.status + + +def _format_duration(seconds: float) -> str: + """Format seconds into a human-readable duration string.""" + return format_duration_compact(seconds) + + +def _bar_chart(values: List[int], max_width: int = 20) -> List[str]: + """Create simple horizontal bar chart strings from values.""" + peak = max(values) if values else 1 + if peak == 0: + return ["" for _ in values] + return ["█" * max(1, int(v / peak * max_width)) if v > 0 else "" for v in values] + + +class InsightsEngine: + """ + Analyzes session history and produces usage insights. + + Works directly with a SessionDB instance (or raw sqlite3 connection) + to query session and message data. + """ + + def __init__(self, db): + """ + Initialize with a SessionDB instance. + + Args: + db: A SessionDB instance (from hermes_state.py) + """ + self.db = db + self._conn = db._conn + + def generate(self, days: int = 30, source: str = None) -> Dict[str, Any]: + """ + Generate a complete insights report. + + Args: + days: Number of days to look back (default: 30) + source: Optional filter by source platform + + Returns: + Dict with all computed insights + """ + cutoff = time.time() - (days * 86400) + + # Gather raw data + sessions = self._get_sessions(cutoff, source) + tool_usage = self._get_tool_usage(cutoff, source) + message_stats = self._get_message_stats(cutoff, source) + + if not sessions: + return { + "days": days, + "source_filter": source, + "empty": True, + "overview": {}, + "models": [], + "platforms": [], + "tools": [], + "activity": {}, + "top_sessions": [], + } + + # Compute insights + overview = self._compute_overview(sessions, message_stats) + models = self._compute_model_breakdown(sessions) + platforms = self._compute_platform_breakdown(sessions) + tools = self._compute_tool_breakdown(tool_usage) + activity = self._compute_activity_patterns(sessions) + top_sessions = self._compute_top_sessions(sessions) + + return { + "days": days, + "source_filter": source, + "empty": False, + "generated_at": time.time(), + "overview": overview, + "models": models, + "platforms": platforms, + "tools": tools, + "activity": activity, + "top_sessions": top_sessions, + } + + # ========================================================================= + # Data gathering (SQL queries) + # ========================================================================= + + # Columns we actually need (skip system_prompt, model_config blobs) + _SESSION_COLS = ("id, source, model, started_at, ended_at, " + "message_count, tool_call_count, input_tokens, output_tokens, " + "cache_read_tokens, cache_write_tokens, billing_provider, " + "billing_base_url, billing_mode, estimated_cost_usd, " + "actual_cost_usd, cost_status, cost_source") + + # Pre-computed query strings — f-string evaluated once at class definition, + # not at runtime, so no user-controlled value can alter the query structure. + _GET_SESSIONS_WITH_SOURCE = ( + f"SELECT {_SESSION_COLS} FROM sessions" + " WHERE started_at >= ? AND source = ?" + " ORDER BY started_at DESC" + ) + _GET_SESSIONS_ALL = ( + f"SELECT {_SESSION_COLS} FROM sessions" + " WHERE started_at >= ?" + " ORDER BY started_at DESC" + ) + + def _get_sessions(self, cutoff: float, source: str = None) -> List[Dict]: + """Fetch sessions within the time window.""" + if source: + cursor = self._conn.execute(self._GET_SESSIONS_WITH_SOURCE, (cutoff, source)) + else: + cursor = self._conn.execute(self._GET_SESSIONS_ALL, (cutoff,)) + return [dict(row) for row in cursor.fetchall()] + + def _get_tool_usage(self, cutoff: float, source: str = None) -> List[Dict]: + """Get tool call counts from messages. + + Uses two sources: + 1. tool_name column on 'tool' role messages (set by gateway) + 2. tool_calls JSON on 'assistant' role messages (covers CLI where + tool_name is not populated on tool responses) + """ + tool_counts = Counter() + + # Source 1: explicit tool_name on tool response messages + if source: + cursor = self._conn.execute( + """SELECT m.tool_name, COUNT(*) as count + FROM messages m + JOIN sessions s ON s.id = m.session_id + WHERE s.started_at >= ? AND s.source = ? + AND m.role = 'tool' AND m.tool_name IS NOT NULL + GROUP BY m.tool_name + ORDER BY count DESC""", + (cutoff, source), + ) + else: + cursor = self._conn.execute( + """SELECT m.tool_name, COUNT(*) as count + FROM messages m + JOIN sessions s ON s.id = m.session_id + WHERE s.started_at >= ? + AND m.role = 'tool' AND m.tool_name IS NOT NULL + GROUP BY m.tool_name + ORDER BY count DESC""", + (cutoff,), + ) + for row in cursor.fetchall(): + tool_counts[row["tool_name"]] += row["count"] + + # Source 2: extract from tool_calls JSON on assistant messages + # (covers CLI sessions where tool_name is NULL on tool responses) + if source: + cursor2 = self._conn.execute( + """SELECT m.tool_calls + FROM messages m + JOIN sessions s ON s.id = m.session_id + WHERE s.started_at >= ? AND s.source = ? + AND m.role = 'assistant' AND m.tool_calls IS NOT NULL""", + (cutoff, source), + ) + else: + cursor2 = self._conn.execute( + """SELECT m.tool_calls + FROM messages m + JOIN sessions s ON s.id = m.session_id + WHERE s.started_at >= ? + AND m.role = 'assistant' AND m.tool_calls IS NOT NULL""", + (cutoff,), + ) + + tool_calls_counts = Counter() + for row in cursor2.fetchall(): + try: + calls = row["tool_calls"] + if isinstance(calls, str): + calls = json.loads(calls) + if isinstance(calls, list): + for call in calls: + func = call.get("function", {}) if isinstance(call, dict) else {} + name = func.get("name") + if name: + tool_calls_counts[name] += 1 + except (json.JSONDecodeError, TypeError, AttributeError): + continue + + # Merge: prefer tool_name source, supplement with tool_calls source + # for tools not already counted + if not tool_counts and tool_calls_counts: + # No tool_name data at all — use tool_calls exclusively + tool_counts = tool_calls_counts + elif tool_counts and tool_calls_counts: + # Both sources have data — use whichever has the higher count per tool + # (they may overlap, so take the max to avoid double-counting) + all_tools = set(tool_counts) | set(tool_calls_counts) + merged = Counter() + for tool in all_tools: + merged[tool] = max(tool_counts.get(tool, 0), tool_calls_counts.get(tool, 0)) + tool_counts = merged + + # Convert to the expected format + return [ + {"tool_name": name, "count": count} + for name, count in tool_counts.most_common() + ] + + def _get_message_stats(self, cutoff: float, source: str = None) -> Dict: + """Get aggregate message statistics.""" + if source: + cursor = self._conn.execute( + """SELECT + COUNT(*) as total_messages, + SUM(CASE WHEN m.role = 'user' THEN 1 ELSE 0 END) as user_messages, + SUM(CASE WHEN m.role = 'assistant' THEN 1 ELSE 0 END) as assistant_messages, + SUM(CASE WHEN m.role = 'tool' THEN 1 ELSE 0 END) as tool_messages + FROM messages m + JOIN sessions s ON s.id = m.session_id + WHERE s.started_at >= ? AND s.source = ?""", + (cutoff, source), + ) + else: + cursor = self._conn.execute( + """SELECT + COUNT(*) as total_messages, + SUM(CASE WHEN m.role = 'user' THEN 1 ELSE 0 END) as user_messages, + SUM(CASE WHEN m.role = 'assistant' THEN 1 ELSE 0 END) as assistant_messages, + SUM(CASE WHEN m.role = 'tool' THEN 1 ELSE 0 END) as tool_messages + FROM messages m + JOIN sessions s ON s.id = m.session_id + WHERE s.started_at >= ?""", + (cutoff,), + ) + row = cursor.fetchone() + return dict(row) if row else { + "total_messages": 0, "user_messages": 0, + "assistant_messages": 0, "tool_messages": 0, + } + + # ========================================================================= + # Computation + # ========================================================================= + + def _compute_overview(self, sessions: List[Dict], message_stats: Dict) -> Dict: + """Compute high-level overview statistics.""" + total_input = sum(s.get("input_tokens") or 0 for s in sessions) + total_output = sum(s.get("output_tokens") or 0 for s in sessions) + total_cache_read = sum(s.get("cache_read_tokens") or 0 for s in sessions) + total_cache_write = sum(s.get("cache_write_tokens") or 0 for s in sessions) + total_tokens = total_input + total_output + total_cache_read + total_cache_write + total_tool_calls = sum(s.get("tool_call_count") or 0 for s in sessions) + total_messages = sum(s.get("message_count") or 0 for s in sessions) + + # Cost estimation (weighted by model) + total_cost = 0.0 + actual_cost = 0.0 + models_with_pricing = set() + models_without_pricing = set() + unknown_cost_sessions = 0 + included_cost_sessions = 0 + for s in sessions: + model = s.get("model") or "" + estimated, status = _estimate_cost(s) + total_cost += estimated + actual_cost += s.get("actual_cost_usd") or 0.0 + display = model.split("/")[-1] if "/" in model else (model or "unknown") + if status == "included": + included_cost_sessions += 1 + elif status == "unknown": + unknown_cost_sessions += 1 + if _has_known_pricing(model, s.get("billing_provider"), s.get("billing_base_url")): + models_with_pricing.add(display) + else: + models_without_pricing.add(display) + + # Session duration stats (guard against negative durations from clock drift) + durations = [] + for s in sessions: + start = s.get("started_at") + end = s.get("ended_at") + if start and end and end > start: + durations.append(end - start) + + total_hours = sum(durations) / 3600 if durations else 0 + avg_duration = sum(durations) / len(durations) if durations else 0 + + # Earliest and latest session + started_timestamps = [s["started_at"] for s in sessions if s.get("started_at")] + date_range_start = min(started_timestamps) if started_timestamps else None + date_range_end = max(started_timestamps) if started_timestamps else None + + return { + "total_sessions": len(sessions), + "total_messages": total_messages, + "total_tool_calls": total_tool_calls, + "total_input_tokens": total_input, + "total_output_tokens": total_output, + "total_cache_read_tokens": total_cache_read, + "total_cache_write_tokens": total_cache_write, + "total_tokens": total_tokens, + "estimated_cost": total_cost, + "actual_cost": actual_cost, + "total_hours": total_hours, + "avg_session_duration": avg_duration, + "avg_messages_per_session": total_messages / len(sessions) if sessions else 0, + "avg_tokens_per_session": total_tokens / len(sessions) if sessions else 0, + "user_messages": message_stats.get("user_messages") or 0, + "assistant_messages": message_stats.get("assistant_messages") or 0, + "tool_messages": message_stats.get("tool_messages") or 0, + "date_range_start": date_range_start, + "date_range_end": date_range_end, + "models_with_pricing": sorted(models_with_pricing), + "models_without_pricing": sorted(models_without_pricing), + "unknown_cost_sessions": unknown_cost_sessions, + "included_cost_sessions": included_cost_sessions, + } + + def _compute_model_breakdown(self, sessions: List[Dict]) -> List[Dict]: + """Break down usage by model.""" + model_data = defaultdict(lambda: { + "sessions": 0, "input_tokens": 0, "output_tokens": 0, + "cache_read_tokens": 0, "cache_write_tokens": 0, + "total_tokens": 0, "tool_calls": 0, "cost": 0.0, + }) + + for s in sessions: + model = s.get("model") or "unknown" + # Normalize: strip provider prefix for display + display_model = model.split("/")[-1] if "/" in model else model + d = model_data[display_model] + d["sessions"] += 1 + inp = s.get("input_tokens") or 0 + out = s.get("output_tokens") or 0 + cache_read = s.get("cache_read_tokens") or 0 + cache_write = s.get("cache_write_tokens") or 0 + d["input_tokens"] += inp + d["output_tokens"] += out + d["cache_read_tokens"] += cache_read + d["cache_write_tokens"] += cache_write + d["total_tokens"] += inp + out + cache_read + cache_write + d["tool_calls"] += s.get("tool_call_count") or 0 + estimate, status = _estimate_cost(s) + d["cost"] += estimate + d["has_pricing"] = _has_known_pricing(model, s.get("billing_provider"), s.get("billing_base_url")) + d["cost_status"] = status + + result = [ + {"model": model, **data} + for model, data in model_data.items() + ] + # Sort by tokens first, fall back to session count when tokens are 0 + result.sort(key=lambda x: (x["total_tokens"], x["sessions"]), reverse=True) + return result + + def _compute_platform_breakdown(self, sessions: List[Dict]) -> List[Dict]: + """Break down usage by platform/source.""" + platform_data = defaultdict(lambda: { + "sessions": 0, "messages": 0, "input_tokens": 0, + "output_tokens": 0, "cache_read_tokens": 0, + "cache_write_tokens": 0, "total_tokens": 0, "tool_calls": 0, + }) + + for s in sessions: + source = s.get("source") or "unknown" + d = platform_data[source] + d["sessions"] += 1 + d["messages"] += s.get("message_count") or 0 + inp = s.get("input_tokens") or 0 + out = s.get("output_tokens") or 0 + cache_read = s.get("cache_read_tokens") or 0 + cache_write = s.get("cache_write_tokens") or 0 + d["input_tokens"] += inp + d["output_tokens"] += out + d["cache_read_tokens"] += cache_read + d["cache_write_tokens"] += cache_write + d["total_tokens"] += inp + out + cache_read + cache_write + d["tool_calls"] += s.get("tool_call_count") or 0 + + result = [ + {"platform": platform, **data} + for platform, data in platform_data.items() + ] + result.sort(key=lambda x: x["sessions"], reverse=True) + return result + + def _compute_tool_breakdown(self, tool_usage: List[Dict]) -> List[Dict]: + """Process tool usage data into a ranked list with percentages.""" + total_calls = sum(t["count"] for t in tool_usage) if tool_usage else 0 + result = [] + for t in tool_usage: + pct = (t["count"] / total_calls * 100) if total_calls else 0 + result.append({ + "tool": t["tool_name"], + "count": t["count"], + "percentage": pct, + }) + return result + + def _compute_activity_patterns(self, sessions: List[Dict]) -> Dict: + """Analyze activity patterns by day of week and hour.""" + day_counts = Counter() # 0=Monday ... 6=Sunday + hour_counts = Counter() + daily_counts = Counter() # date string -> count + + for s in sessions: + ts = s.get("started_at") + if not ts: + continue + dt = datetime.fromtimestamp(ts) + day_counts[dt.weekday()] += 1 + hour_counts[dt.hour] += 1 + daily_counts[dt.strftime("%Y-%m-%d")] += 1 + + day_names = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] + day_breakdown = [ + {"day": day_names[i], "count": day_counts.get(i, 0)} + for i in range(7) + ] + + hour_breakdown = [ + {"hour": i, "count": hour_counts.get(i, 0)} + for i in range(24) + ] + + # Busiest day and hour + busiest_day = max(day_breakdown, key=lambda x: x["count"]) if day_breakdown else None + busiest_hour = max(hour_breakdown, key=lambda x: x["count"]) if hour_breakdown else None + + # Active days (days with at least one session) + active_days = len(daily_counts) + + # Streak calculation + if daily_counts: + all_dates = sorted(daily_counts.keys()) + current_streak = 1 + max_streak = 1 + for i in range(1, len(all_dates)): + d1 = datetime.strptime(all_dates[i - 1], "%Y-%m-%d") + d2 = datetime.strptime(all_dates[i], "%Y-%m-%d") + if (d2 - d1).days == 1: + current_streak += 1 + max_streak = max(max_streak, current_streak) + else: + current_streak = 1 + else: + max_streak = 0 + + return { + "by_day": day_breakdown, + "by_hour": hour_breakdown, + "busiest_day": busiest_day, + "busiest_hour": busiest_hour, + "active_days": active_days, + "max_streak": max_streak, + } + + def _compute_top_sessions(self, sessions: List[Dict]) -> List[Dict]: + """Find notable sessions (longest, most messages, most tokens).""" + top = [] + + # Longest by duration + sessions_with_duration = [ + s for s in sessions + if s.get("started_at") and s.get("ended_at") + ] + if sessions_with_duration: + longest = max( + sessions_with_duration, + key=lambda s: (s["ended_at"] - s["started_at"]), + ) + dur = longest["ended_at"] - longest["started_at"] + top.append({ + "label": "Longest session", + "session_id": longest["id"][:16], + "value": _format_duration(dur), + "date": datetime.fromtimestamp(longest["started_at"]).strftime("%b %d"), + }) + + # Most messages + most_msgs = max(sessions, key=lambda s: s.get("message_count") or 0) + if (most_msgs.get("message_count") or 0) > 0: + top.append({ + "label": "Most messages", + "session_id": most_msgs["id"][:16], + "value": f"{most_msgs['message_count']} msgs", + "date": datetime.fromtimestamp(most_msgs["started_at"]).strftime("%b %d") if most_msgs.get("started_at") else "?", + }) + + # Most tokens + most_tokens = max( + sessions, + key=lambda s: (s.get("input_tokens") or 0) + (s.get("output_tokens") or 0), + ) + token_total = (most_tokens.get("input_tokens") or 0) + (most_tokens.get("output_tokens") or 0) + if token_total > 0: + top.append({ + "label": "Most tokens", + "session_id": most_tokens["id"][:16], + "value": f"{token_total:,} tokens", + "date": datetime.fromtimestamp(most_tokens["started_at"]).strftime("%b %d") if most_tokens.get("started_at") else "?", + }) + + # Most tool calls + most_tools = max(sessions, key=lambda s: s.get("tool_call_count") or 0) + if (most_tools.get("tool_call_count") or 0) > 0: + top.append({ + "label": "Most tool calls", + "session_id": most_tools["id"][:16], + "value": f"{most_tools['tool_call_count']} calls", + "date": datetime.fromtimestamp(most_tools["started_at"]).strftime("%b %d") if most_tools.get("started_at") else "?", + }) + + return top + + # ========================================================================= + # Formatting + # ========================================================================= + + def format_terminal(self, report: Dict) -> str: + """Format the insights report for terminal display (CLI).""" + if report.get("empty"): + days = report.get("days", 30) + src = f" (source: {report['source_filter']})" if report.get("source_filter") else "" + return f" No sessions found in the last {days} days{src}." + + lines = [] + o = report["overview"] + days = report["days"] + src_filter = report.get("source_filter") + + # Header + lines.append("") + lines.append(" ╔══════════════════════════════════════════════════════════╗") + lines.append(" ║ 📊 Hermes Insights ║") + period_label = f"Last {days} days" + if src_filter: + period_label += f" ({src_filter})" + padding = 58 - len(period_label) - 2 + left_pad = padding // 2 + right_pad = padding - left_pad + lines.append(f" ║{' ' * left_pad} {period_label} {' ' * right_pad}║") + lines.append(" ╚══════════════════════════════════════════════════════════╝") + lines.append("") + + # Date range + if o.get("date_range_start") and o.get("date_range_end"): + start_str = datetime.fromtimestamp(o["date_range_start"]).strftime("%b %d, %Y") + end_str = datetime.fromtimestamp(o["date_range_end"]).strftime("%b %d, %Y") + lines.append(f" Period: {start_str} — {end_str}") + lines.append("") + + # Overview + lines.append(" 📋 Overview") + lines.append(" " + "─" * 56) + lines.append(f" Sessions: {o['total_sessions']:<12} Messages: {o['total_messages']:,}") + lines.append(f" Tool calls: {o['total_tool_calls']:<12,} User messages: {o['user_messages']:,}") + lines.append(f" Input tokens: {o['total_input_tokens']:<12,} Output tokens: {o['total_output_tokens']:,}") + cache_total = o.get("total_cache_read_tokens", 0) + o.get("total_cache_write_tokens", 0) + if cache_total > 0: + lines.append(f" Cache read: {o['total_cache_read_tokens']:<12,} Cache write: {o['total_cache_write_tokens']:,}") + cost_str = f"${o['estimated_cost']:.2f}" + if o.get("models_without_pricing"): + cost_str += " *" + lines.append(f" Total tokens: {o['total_tokens']:<12,} Est. cost: {cost_str}") + if o["total_hours"] > 0: + lines.append(f" Active time: ~{_format_duration(o['total_hours'] * 3600):<11} Avg session: ~{_format_duration(o['avg_session_duration'])}") + lines.append(f" Avg msgs/session: {o['avg_messages_per_session']:.1f}") + lines.append("") + + # Model breakdown + if report["models"]: + lines.append(" 🤖 Models Used") + lines.append(" " + "─" * 56) + lines.append(f" {'Model':<30} {'Sessions':>8} {'Tokens':>12} {'Cost':>8}") + for m in report["models"]: + model_name = m["model"][:28] + if m.get("has_pricing"): + cost_cell = f"${m['cost']:>6.2f}" + else: + cost_cell = " N/A" + lines.append(f" {model_name:<30} {m['sessions']:>8} {m['total_tokens']:>12,} {cost_cell}") + if o.get("models_without_pricing"): + lines.append(" * Cost N/A for custom/self-hosted models") + lines.append("") + + # Platform breakdown + if len(report["platforms"]) > 1 or (report["platforms"] and report["platforms"][0]["platform"] != "cli"): + lines.append(" 📱 Platforms") + lines.append(" " + "─" * 56) + lines.append(f" {'Platform':<14} {'Sessions':>8} {'Messages':>10} {'Tokens':>14}") + for p in report["platforms"]: + lines.append(f" {p['platform']:<14} {p['sessions']:>8} {p['messages']:>10,} {p['total_tokens']:>14,}") + lines.append("") + + # Tool usage + if report["tools"]: + lines.append(" 🔧 Top Tools") + lines.append(" " + "─" * 56) + lines.append(f" {'Tool':<28} {'Calls':>8} {'%':>8}") + for t in report["tools"][:15]: # Top 15 + lines.append(f" {t['tool']:<28} {t['count']:>8,} {t['percentage']:>7.1f}%") + if len(report["tools"]) > 15: + lines.append(f" ... and {len(report['tools']) - 15} more tools") + lines.append("") + + # Activity patterns + act = report.get("activity", {}) + if act.get("by_day"): + lines.append(" 📅 Activity Patterns") + lines.append(" " + "─" * 56) + + # Day of week chart + day_values = [d["count"] for d in act["by_day"]] + bars = _bar_chart(day_values, max_width=15) + for i, d in enumerate(act["by_day"]): + bar = bars[i] + lines.append(f" {d['day']} {bar:<15} {d['count']}") + + lines.append("") + + # Peak hours (show top 5 busiest hours) + busy_hours = sorted(act["by_hour"], key=lambda x: x["count"], reverse=True) + busy_hours = [h for h in busy_hours if h["count"] > 0][:5] + if busy_hours: + hour_strs = [] + for h in busy_hours: + hr = h["hour"] + ampm = "AM" if hr < 12 else "PM" + display_hr = hr % 12 or 12 + hour_strs.append(f"{display_hr}{ampm} ({h['count']})") + lines.append(f" Peak hours: {', '.join(hour_strs)}") + + if act.get("active_days"): + lines.append(f" Active days: {act['active_days']}") + if act.get("max_streak") and act["max_streak"] > 1: + lines.append(f" Best streak: {act['max_streak']} consecutive days") + lines.append("") + + # Notable sessions + if report.get("top_sessions"): + lines.append(" 🏆 Notable Sessions") + lines.append(" " + "─" * 56) + for ts in report["top_sessions"]: + lines.append(f" {ts['label']:<20} {ts['value']:<18} ({ts['date']}, {ts['session_id']})") + lines.append("") + + return "\n".join(lines) + + def format_gateway(self, report: Dict) -> str: + """Format the insights report for gateway/messaging (shorter).""" + if report.get("empty"): + days = report.get("days", 30) + return f"No sessions found in the last {days} days." + + lines = [] + o = report["overview"] + days = report["days"] + + lines.append(f"📊 **Hermes Insights** — Last {days} days\n") + + # Overview + lines.append(f"**Sessions:** {o['total_sessions']} | **Messages:** {o['total_messages']:,} | **Tool calls:** {o['total_tool_calls']:,}") + cache_total = o.get("total_cache_read_tokens", 0) + o.get("total_cache_write_tokens", 0) + if cache_total > 0: + lines.append(f"**Tokens:** {o['total_tokens']:,} (in: {o['total_input_tokens']:,} / out: {o['total_output_tokens']:,} / cache: {cache_total:,})") + else: + lines.append(f"**Tokens:** {o['total_tokens']:,} (in: {o['total_input_tokens']:,} / out: {o['total_output_tokens']:,})") + cost_note = "" + if o.get("models_without_pricing"): + cost_note = " _(excludes custom/self-hosted models)_" + lines.append(f"**Est. cost:** ${o['estimated_cost']:.2f}{cost_note}") + if o["total_hours"] > 0: + lines.append(f"**Active time:** ~{_format_duration(o['total_hours'] * 3600)} | **Avg session:** ~{_format_duration(o['avg_session_duration'])}") + lines.append("") + + # Models (top 5) + if report["models"]: + lines.append("**🤖 Models:**") + for m in report["models"][:5]: + cost_str = f"${m['cost']:.2f}" if m.get("has_pricing") else "N/A" + lines.append(f" {m['model'][:25]} — {m['sessions']} sessions, {m['total_tokens']:,} tokens, {cost_str}") + lines.append("") + + # Platforms (if multi-platform) + if len(report["platforms"]) > 1: + lines.append("**📱 Platforms:**") + for p in report["platforms"]: + lines.append(f" {p['platform']} — {p['sessions']} sessions, {p['messages']:,} msgs") + lines.append("") + + # Tools (top 8) + if report["tools"]: + lines.append("**🔧 Top Tools:**") + for t in report["tools"][:8]: + lines.append(f" {t['tool']} — {t['count']:,} calls ({t['percentage']:.1f}%)") + lines.append("") + + # Activity summary + act = report.get("activity", {}) + if act.get("busiest_day") and act.get("busiest_hour"): + hr = act["busiest_hour"]["hour"] + ampm = "AM" if hr < 12 else "PM" + display_hr = hr % 12 or 12 + lines.append(f"**📅 Busiest:** {act['busiest_day']['day']}s ({act['busiest_day']['count']} sessions), {display_hr}{ampm} ({act['busiest_hour']['count']} sessions)") + if act.get("active_days"): + lines.append(f"**Active days:** {act['active_days']}", ) + if act.get("max_streak", 0) > 1: + lines.append(f"**Best streak:** {act['max_streak']} consecutive days") + + return "\n".join(lines) diff --git a/mindcli/_vendor/agent/manual_compression_feedback.py b/mindcli/_vendor/agent/manual_compression_feedback.py new file mode 100644 index 0000000..8f2d5e5 --- /dev/null +++ b/mindcli/_vendor/agent/manual_compression_feedback.py @@ -0,0 +1,49 @@ +"""User-facing summaries for manual compression commands.""" + +from __future__ import annotations + +from typing import Any, Sequence + + +def summarize_manual_compression( + before_messages: Sequence[dict[str, Any]], + after_messages: Sequence[dict[str, Any]], + before_tokens: int, + after_tokens: int, +) -> dict[str, Any]: + """Return consistent user-facing feedback for manual compression.""" + before_count = len(before_messages) + after_count = len(after_messages) + noop = list(after_messages) == list(before_messages) + + if noop: + headline = f"No changes from compression: {before_count} messages" + if after_tokens == before_tokens: + token_line = ( + f"Rough transcript estimate: ~{before_tokens:,} tokens (unchanged)" + ) + else: + token_line = ( + f"Rough transcript estimate: ~{before_tokens:,} → " + f"~{after_tokens:,} tokens" + ) + else: + headline = f"Compressed: {before_count} → {after_count} messages" + token_line = ( + f"Rough transcript estimate: ~{before_tokens:,} → " + f"~{after_tokens:,} tokens" + ) + + note = None + if not noop and after_count < before_count and after_tokens > before_tokens: + note = ( + "Note: fewer messages can still raise this rough transcript estimate " + "when compression rewrites the transcript into denser summaries." + ) + + return { + "noop": noop, + "headline": headline, + "token_line": token_line, + "note": note, + } diff --git a/mindcli/_vendor/agent/memory_manager.py b/mindcli/_vendor/agent/memory_manager.py new file mode 100644 index 0000000..6cd1c86 --- /dev/null +++ b/mindcli/_vendor/agent/memory_manager.py @@ -0,0 +1,361 @@ +"""MemoryManager — orchestrates the built-in memory provider plus at most +ONE external plugin memory provider. + +Single integration point in run_agent.py. Replaces scattered per-backend +code with one manager that delegates to registered providers. + +The BuiltinMemoryProvider is always registered first and cannot be removed. +Only ONE external (non-builtin) provider is allowed at a time — attempting +to register a second external provider is rejected with a warning. This +prevents tool schema bloat and conflicting memory backends. + +Usage in run_agent.py: + self._memory_manager = MemoryManager() + self._memory_manager.add_provider(BuiltinMemoryProvider(...)) + # Only ONE of these: + self._memory_manager.add_provider(plugin_provider) + + # System prompt + prompt_parts.append(self._memory_manager.build_system_prompt()) + + # Pre-turn + context = self._memory_manager.prefetch_all(user_message) + + # Post-turn + self._memory_manager.sync_all(user_msg, assistant_response) + self._memory_manager.queue_prefetch_all(user_msg) +""" + +from __future__ import annotations + +import logging +import re +from typing import Any, Dict, List, Optional + +from agent.memory_provider import MemoryProvider +from tools.registry import tool_error + +logger = logging.getLogger(__name__) + + +# --------------------------------------------------------------------------- +# Context fencing helpers +# --------------------------------------------------------------------------- + +_FENCE_TAG_RE = re.compile(r'', re.IGNORECASE) + + +def sanitize_context(text: str) -> str: + """Strip fence-escape sequences from provider output.""" + return _FENCE_TAG_RE.sub('', text) + + +def build_memory_context_block(raw_context: str) -> str: + """Wrap prefetched memory in a fenced block with system note. + + The fence prevents the model from treating recalled context as user + discourse. Injected at API-call time only — never persisted. + """ + if not raw_context or not raw_context.strip(): + return "" + clean = sanitize_context(raw_context) + return ( + "\n" + "[System note: The following is recalled memory context, " + "NOT new user input. Treat as informational background data.]\n\n" + f"{clean}\n" + "" + ) + + +class MemoryManager: + """Orchestrates the built-in provider plus at most one external provider. + + The builtin provider is always first. Only one non-builtin (external) + provider is allowed. Failures in one provider never block the other. + """ + + def __init__(self) -> None: + self._providers: List[MemoryProvider] = [] + self._tool_to_provider: Dict[str, MemoryProvider] = {} + self._has_external: bool = False # True once a non-builtin provider is added + + # -- Registration -------------------------------------------------------- + + def add_provider(self, provider: MemoryProvider) -> None: + """Register a memory provider. + + Built-in provider (name ``"builtin"``) is always accepted. + Only **one** external (non-builtin) provider is allowed — a second + attempt is rejected with a warning. + """ + is_builtin = provider.name == "builtin" + + if not is_builtin: + if self._has_external: + existing = next( + (p.name for p in self._providers if p.name != "builtin"), "unknown" + ) + logger.warning( + "Rejected memory provider '%s' — external provider '%s' is " + "already registered. Only one external memory provider is " + "allowed at a time. Configure which one via memory.provider " + "in config.yaml.", + provider.name, existing, + ) + return + self._has_external = True + + self._providers.append(provider) + + # Index tool names → provider for routing + for schema in provider.get_tool_schemas(): + tool_name = schema.get("name", "") + if tool_name and tool_name not in self._tool_to_provider: + self._tool_to_provider[tool_name] = provider + elif tool_name in self._tool_to_provider: + logger.warning( + "Memory tool name conflict: '%s' already registered by %s, " + "ignoring from %s", + tool_name, + self._tool_to_provider[tool_name].name, + provider.name, + ) + + logger.info( + "Memory provider '%s' registered (%d tools)", + provider.name, + len(provider.get_tool_schemas()), + ) + + @property + def providers(self) -> List[MemoryProvider]: + """All registered providers in order.""" + return list(self._providers) + + def get_provider(self, name: str) -> Optional[MemoryProvider]: + """Get a provider by name, or None if not registered.""" + for p in self._providers: + if p.name == name: + return p + return None + + # -- System prompt ------------------------------------------------------- + + def build_system_prompt(self) -> str: + """Collect system prompt blocks from all providers. + + Returns combined text, or empty string if no providers contribute. + Each non-empty block is labeled with the provider name. + """ + blocks = [] + for provider in self._providers: + try: + block = provider.system_prompt_block() + if block and block.strip(): + blocks.append(block) + except Exception as e: + logger.warning( + "Memory provider '%s' system_prompt_block() failed: %s", + provider.name, e, + ) + return "\n\n".join(blocks) + + # -- Prefetch / recall --------------------------------------------------- + + def prefetch_all(self, query: str, *, session_id: str = "") -> str: + """Collect prefetch context from all providers. + + Returns merged context text labeled by provider. Empty providers + are skipped. Failures in one provider don't block others. + """ + parts = [] + for provider in self._providers: + try: + result = provider.prefetch(query, session_id=session_id) + if result and result.strip(): + parts.append(result) + except Exception as e: + logger.debug( + "Memory provider '%s' prefetch failed (non-fatal): %s", + provider.name, e, + ) + return "\n\n".join(parts) + + def queue_prefetch_all(self, query: str, *, session_id: str = "") -> None: + """Queue background prefetch on all providers for the next turn.""" + for provider in self._providers: + try: + provider.queue_prefetch(query, session_id=session_id) + except Exception as e: + logger.debug( + "Memory provider '%s' queue_prefetch failed (non-fatal): %s", + provider.name, e, + ) + + # -- Sync ---------------------------------------------------------------- + + def sync_all(self, user_content: str, assistant_content: str, *, session_id: str = "") -> None: + """Sync a completed turn to all providers.""" + for provider in self._providers: + try: + provider.sync_turn(user_content, assistant_content, session_id=session_id) + except Exception as e: + logger.warning( + "Memory provider '%s' sync_turn failed: %s", + provider.name, e, + ) + + # -- Tools --------------------------------------------------------------- + + def get_all_tool_schemas(self) -> List[Dict[str, Any]]: + """Collect tool schemas from all providers.""" + schemas = [] + seen = set() + for provider in self._providers: + try: + for schema in provider.get_tool_schemas(): + name = schema.get("name", "") + if name and name not in seen: + schemas.append(schema) + seen.add(name) + except Exception as e: + logger.warning( + "Memory provider '%s' get_tool_schemas() failed: %s", + provider.name, e, + ) + return schemas + + def get_all_tool_names(self) -> set: + """Return set of all tool names across all providers.""" + return set(self._tool_to_provider.keys()) + + def has_tool(self, tool_name: str) -> bool: + """Check if any provider handles this tool.""" + return tool_name in self._tool_to_provider + + def handle_tool_call( + self, tool_name: str, args: Dict[str, Any], **kwargs + ) -> str: + """Route a tool call to the correct provider. + + Returns JSON string result. Raises ValueError if no provider + handles the tool. + """ + provider = self._tool_to_provider.get(tool_name) + if provider is None: + return tool_error(f"No memory provider handles tool '{tool_name}'") + try: + return provider.handle_tool_call(tool_name, args, **kwargs) + except Exception as e: + logger.error( + "Memory provider '%s' handle_tool_call(%s) failed: %s", + provider.name, tool_name, e, + ) + return tool_error(f"Memory tool '{tool_name}' failed: {e}") + + # -- Lifecycle hooks ----------------------------------------------------- + + def on_turn_start(self, turn_number: int, message: str, **kwargs) -> None: + """Notify all providers of a new turn. + + kwargs may include: remaining_tokens, model, platform, tool_count. + """ + for provider in self._providers: + try: + provider.on_turn_start(turn_number, message, **kwargs) + except Exception as e: + logger.debug( + "Memory provider '%s' on_turn_start failed: %s", + provider.name, e, + ) + + def on_session_end(self, messages: List[Dict[str, Any]]) -> None: + """Notify all providers of session end.""" + for provider in self._providers: + try: + provider.on_session_end(messages) + except Exception as e: + logger.debug( + "Memory provider '%s' on_session_end failed: %s", + provider.name, e, + ) + + def on_pre_compress(self, messages: List[Dict[str, Any]]) -> str: + """Notify all providers before context compression. + + Returns combined text from providers to include in the compression + summary prompt. Empty string if no provider contributes. + """ + parts = [] + for provider in self._providers: + try: + result = provider.on_pre_compress(messages) + if result and result.strip(): + parts.append(result) + except Exception as e: + logger.debug( + "Memory provider '%s' on_pre_compress failed: %s", + provider.name, e, + ) + return "\n\n".join(parts) + + def on_memory_write(self, action: str, target: str, content: str) -> None: + """Notify external providers when the built-in memory tool writes. + + Skips the builtin provider itself (it's the source of the write). + """ + for provider in self._providers: + if provider.name == "builtin": + continue + try: + provider.on_memory_write(action, target, content) + except Exception as e: + logger.debug( + "Memory provider '%s' on_memory_write failed: %s", + provider.name, e, + ) + + def on_delegation(self, task: str, result: str, *, + child_session_id: str = "", **kwargs) -> None: + """Notify all providers that a subagent completed.""" + for provider in self._providers: + try: + provider.on_delegation( + task, result, child_session_id=child_session_id, **kwargs + ) + except Exception as e: + logger.debug( + "Memory provider '%s' on_delegation failed: %s", + provider.name, e, + ) + + def shutdown_all(self) -> None: + """Shut down all providers (reverse order for clean teardown).""" + for provider in reversed(self._providers): + try: + provider.shutdown() + except Exception as e: + logger.warning( + "Memory provider '%s' shutdown failed: %s", + provider.name, e, + ) + + def initialize_all(self, session_id: str, **kwargs) -> None: + """Initialize all providers. + + Automatically injects ``hermes_home`` into *kwargs* so that every + provider can resolve profile-scoped storage paths without importing + ``get_hermes_home()`` themselves. + """ + if "hermes_home" not in kwargs: + from hermes_constants import get_hermes_home + kwargs["hermes_home"] = str(get_hermes_home()) + for provider in self._providers: + try: + provider.initialize(session_id=session_id, **kwargs) + except Exception as e: + logger.warning( + "Memory provider '%s' initialize failed: %s", + provider.name, e, + ) diff --git a/mindcli/_vendor/agent/memory_provider.py b/mindcli/_vendor/agent/memory_provider.py new file mode 100644 index 0000000..24593e3 --- /dev/null +++ b/mindcli/_vendor/agent/memory_provider.py @@ -0,0 +1,231 @@ +"""Abstract base class for pluggable memory providers. + +Memory providers give the agent persistent recall across sessions. One +external provider is active at a time alongside the always-on built-in +memory (MEMORY.md / USER.md). The MemoryManager enforces this limit. + +Built-in memory is always active as the first provider and cannot be removed. +External providers (Honcho, Hindsight, Mem0, etc.) are additive — they never +disable the built-in store. Only one external provider runs at a time to +prevent tool schema bloat and conflicting memory backends. + +Registration: + 1. Built-in: BuiltinMemoryProvider — always present, not removable. + 2. Plugins: Ship in plugins/memory//, activated by memory.provider config. + +Lifecycle (called by MemoryManager, wired in run_agent.py): + initialize() — connect, create resources, warm up + system_prompt_block() — static text for the system prompt + prefetch(query) — background recall before each turn + sync_turn(user, asst) — async write after each turn + get_tool_schemas() — tool schemas to expose to the model + handle_tool_call() — dispatch a tool call + shutdown() — clean exit + +Optional hooks (override to opt in): + on_turn_start(turn, message, **kwargs) — per-turn tick with runtime context + on_session_end(messages) — end-of-session extraction + on_pre_compress(messages) -> str — extract before context compression + on_memory_write(action, target, content) — mirror built-in memory writes + on_delegation(task, result, **kwargs) — parent-side observation of subagent work +""" + +from __future__ import annotations + +import logging +from abc import ABC, abstractmethod +from typing import Any, Dict, List + +logger = logging.getLogger(__name__) + + +class MemoryProvider(ABC): + """Abstract base class for memory providers.""" + + @property + @abstractmethod + def name(self) -> str: + """Short identifier for this provider (e.g. 'builtin', 'honcho', 'hindsight').""" + + # -- Core lifecycle (implement these) ------------------------------------ + + @abstractmethod + def is_available(self) -> bool: + """Return True if this provider is configured, has credentials, and is ready. + + Called during agent init to decide whether to activate the provider. + Should not make network calls — just check config and installed deps. + """ + + @abstractmethod + def initialize(self, session_id: str, **kwargs) -> None: + """Initialize for a session. + + Called once at agent startup. May create resources (banks, tables), + establish connections, start background threads, etc. + + kwargs always include: + - hermes_home (str): The active HERMES_HOME directory path. Use this + for profile-scoped storage instead of hardcoding ``~/.hermes``. + - platform (str): "cli", "telegram", "discord", "cron", etc. + + kwargs may also include: + - agent_context (str): "primary", "subagent", "cron", or "flush". + Providers should skip writes for non-primary contexts (cron system + prompts would corrupt user representations). + - agent_identity (str): Profile name (e.g. "coder"). Use for + per-profile provider identity scoping. + - agent_workspace (str): Shared workspace name (e.g. "hermes"). + - parent_session_id (str): For subagents, the parent's session_id. + - user_id (str): Platform user identifier (gateway sessions). + """ + + def system_prompt_block(self) -> str: + """Return text to include in the system prompt. + + Called during system prompt assembly. Return empty string to skip. + This is for STATIC provider info (instructions, status). Prefetched + recall context is injected separately via prefetch(). + """ + return "" + + def prefetch(self, query: str, *, session_id: str = "") -> str: + """Recall relevant context for the upcoming turn. + + Called before each API call. Return formatted text to inject as + context, or empty string if nothing relevant. Implementations + should be fast — use background threads for the actual recall + and return cached results here. + + session_id is provided for providers serving concurrent sessions + (gateway group chats, cached agents). Providers that don't need + per-session scoping can ignore it. + """ + return "" + + def queue_prefetch(self, query: str, *, session_id: str = "") -> None: + """Queue a background recall for the NEXT turn. + + Called after each turn completes. The result will be consumed + by prefetch() on the next turn. Default is no-op — providers + that do background prefetching should override this. + """ + + def sync_turn(self, user_content: str, assistant_content: str, *, session_id: str = "") -> None: + """Persist a completed turn to the backend. + + Called after each turn. Should be non-blocking — queue for + background processing if the backend has latency. + """ + + @abstractmethod + def get_tool_schemas(self) -> List[Dict[str, Any]]: + """Return tool schemas this provider exposes. + + Each schema follows the OpenAI function calling format: + {"name": "...", "description": "...", "parameters": {...}} + + Return empty list if this provider has no tools (context-only). + """ + + def handle_tool_call(self, tool_name: str, args: Dict[str, Any], **kwargs) -> str: + """Handle a tool call for one of this provider's tools. + + Must return a JSON string (the tool result). + Only called for tool names returned by get_tool_schemas(). + """ + raise NotImplementedError(f"Provider {self.name} does not handle tool {tool_name}") + + def shutdown(self) -> None: + """Clean shutdown — flush queues, close connections.""" + + # -- Optional hooks (override to opt in) --------------------------------- + + def on_turn_start(self, turn_number: int, message: str, **kwargs) -> None: + """Called at the start of each turn with the user message. + + Use for turn-counting, scope management, periodic maintenance. + + kwargs may include: remaining_tokens, model, platform, tool_count. + Providers use what they need; extras are ignored. + """ + + def on_session_end(self, messages: List[Dict[str, Any]]) -> None: + """Called when a session ends (explicit exit or timeout). + + Use for end-of-session fact extraction, summarization, etc. + messages is the full conversation history. + + NOT called after every turn — only at actual session boundaries + (CLI exit, /reset, gateway session expiry). + """ + + def on_pre_compress(self, messages: List[Dict[str, Any]]) -> str: + """Called before context compression discards old messages. + + Use to extract insights from messages about to be compressed. + messages is the list that will be summarized/discarded. + + Return text to include in the compression summary prompt so the + compressor preserves provider-extracted insights. Return empty + string for no contribution (backwards-compatible default). + """ + return "" + + def on_delegation(self, task: str, result: str, *, + child_session_id: str = "", **kwargs) -> None: + """Called on the PARENT agent when a subagent completes. + + The parent's memory provider gets the task+result pair as an + observation of what was delegated and what came back. The subagent + itself has no provider session (skip_memory=True). + + task: the delegation prompt + result: the subagent's final response + child_session_id: the subagent's session_id + """ + + def get_config_schema(self) -> List[Dict[str, Any]]: + """Return config fields this provider needs for setup. + + Used by 'hermes memory setup' to walk the user through configuration. + Each field is a dict with: + key: config key name (e.g. 'api_key', 'mode') + description: human-readable description + secret: True if this should go to .env (default: False) + required: True if required (default: False) + default: default value (optional) + choices: list of valid values (optional) + url: URL where user can get this credential (optional) + env_var: explicit env var name for secrets (default: auto-generated) + + Return empty list if no config needed (e.g. local-only providers). + """ + return [] + + def save_config(self, values: Dict[str, Any], hermes_home: str) -> None: + """Write non-secret config to the provider's native location. + + Called by 'hermes memory setup' after collecting user inputs. + ``values`` contains only non-secret fields (secrets go to .env). + ``hermes_home`` is the active HERMES_HOME directory path. + + Providers with native config files (JSON, YAML) should override + this to write to their expected location. Providers that use only + env vars can leave the default (no-op). + + All new memory provider plugins MUST implement either: + - save_config() for native config file formats, OR + - use only env vars (in which case get_config_schema() fields + should all have ``env_var`` set and this method stays no-op). + """ + + def on_memory_write(self, action: str, target: str, content: str) -> None: + """Called when the built-in memory tool writes an entry. + + action: 'add', 'replace', or 'remove' + target: 'memory' or 'user' + content: the entry content + + Use to mirror built-in memory writes to your backend. + """ diff --git a/mindcli/_vendor/agent/model_metadata.py b/mindcli/_vendor/agent/model_metadata.py new file mode 100644 index 0000000..3b50066 --- /dev/null +++ b/mindcli/_vendor/agent/model_metadata.py @@ -0,0 +1,1101 @@ +"""Model metadata, context lengths, and token estimation utilities. + +Pure utility functions with no AIAgent dependency. Used by ContextCompressor +and run_agent.py for pre-flight context checks. +""" + +import logging +import re +import time +from pathlib import Path +from typing import Any, Dict, List, Optional +from urllib.parse import urlparse + +import requests +import yaml + +from hermes_constants import OPENROUTER_MODELS_URL + +logger = logging.getLogger(__name__) + +# Provider names that can appear as a "provider:" prefix before a model ID. +# Only these are stripped — Ollama-style "model:tag" colons (e.g. "qwen3.5:27b") +# are preserved so the full model name reaches cache lookups and server queries. +_PROVIDER_PREFIXES: frozenset[str] = frozenset({ + "openrouter", "nous", "openai-codex", "copilot", "copilot-acp", + "gemini", "zai", "kimi-coding", "kimi-coding-cn", "minimax", "minimax-cn", "anthropic", "deepseek", + "opencode-zen", "opencode-go", "ai-gateway", "kilocode", "alibaba", + "qwen-oauth", + "xiaomi", + "arcee", + "custom", "local", + # Common aliases + "google", "google-gemini", "google-ai-studio", + "glm", "z-ai", "z.ai", "zhipu", "github", "github-copilot", + "github-models", "kimi", "moonshot", "kimi-cn", "moonshot-cn", "claude", "deep-seek", + "opencode", "zen", "go", "vercel", "kilo", "dashscope", "aliyun", "qwen", + "mimo", "xiaomi-mimo", + "arcee-ai", "arceeai", + "qwen-portal", +}) + + +_OLLAMA_TAG_PATTERN = re.compile( + r"^(\d+\.?\d*b|latest|stable|q\d|fp?\d|instruct|chat|coder|vision|text)", + re.IGNORECASE, +) + + +def _strip_provider_prefix(model: str) -> str: + """Strip a recognised provider prefix from a model string. + + ``"local:my-model"`` → ``"my-model"`` + ``"qwen3.5:27b"`` → ``"qwen3.5:27b"`` (unchanged — not a provider prefix) + ``"qwen:0.5b"`` → ``"qwen:0.5b"`` (unchanged — Ollama model:tag) + ``"deepseek:latest"``→ ``"deepseek:latest"``(unchanged — Ollama model:tag) + """ + if ":" not in model or model.startswith("http"): + return model + prefix, suffix = model.split(":", 1) + prefix_lower = prefix.strip().lower() + if prefix_lower in _PROVIDER_PREFIXES: + # Don't strip if suffix looks like an Ollama tag (e.g. "7b", "latest", "q4_0") + if _OLLAMA_TAG_PATTERN.match(suffix.strip()): + return model + return suffix + return model + +_model_metadata_cache: Dict[str, Dict[str, Any]] = {} +_model_metadata_cache_time: float = 0 +_MODEL_CACHE_TTL = 3600 +_endpoint_model_metadata_cache: Dict[str, Dict[str, Dict[str, Any]]] = {} +_endpoint_model_metadata_cache_time: Dict[str, float] = {} +_ENDPOINT_MODEL_CACHE_TTL = 300 + +# Descending tiers for context length probing when the model is unknown. +# We start at 128K (a safe default for most modern models) and step down +# on context-length errors until one works. +CONTEXT_PROBE_TIERS = [ + 128_000, + 64_000, + 32_000, + 16_000, + 8_000, +] + +# Default context length when no detection method succeeds. +DEFAULT_FALLBACK_CONTEXT = CONTEXT_PROBE_TIERS[0] + +# Minimum context length required to run Hermes Agent. Models with fewer +# tokens cannot maintain enough working memory for tool-calling workflows. +# Sessions, model switches, and cron jobs should reject models below this. +MINIMUM_CONTEXT_LENGTH = 64_000 + +# Thin fallback defaults — only broad model family patterns. +# These fire only when provider is unknown AND models.dev/OpenRouter/Anthropic +# all miss. Replaced the previous 80+ entry dict. +# For provider-specific context lengths, models.dev is the primary source. +DEFAULT_CONTEXT_LENGTHS = { + # Anthropic Claude 4.6 (1M context) — bare IDs only to avoid + # fuzzy-match collisions (e.g. "anthropic/claude-sonnet-4" is a + # substring of "anthropic/claude-sonnet-4.6"). + # OpenRouter-prefixed models resolve via OpenRouter live API or models.dev. + "claude-opus-4-6": 1000000, + "claude-sonnet-4-6": 1000000, + "claude-opus-4.6": 1000000, + "claude-sonnet-4.6": 1000000, + # Catch-all for older Claude models (must sort after specific entries) + "claude": 200000, + # OpenAI — GPT-5 family (most have 400k; specific overrides first) + # Source: https://developers.openai.com/api/docs/models + "gpt-5.4-nano": 400000, # 400k (not 1.05M like full 5.4) + "gpt-5.4-mini": 400000, # 400k (not 1.05M like full 5.4) + "gpt-5.4": 1050000, # GPT-5.4, GPT-5.4 Pro (1.05M context) + "gpt-5.3-codex-spark": 128000, # Spark variant has reduced 128k context + "gpt-5.1-chat": 128000, # Chat variant has 128k context + "gpt-5": 400000, # GPT-5.x base, mini, codex variants (400k) + "gpt-4.1": 1047576, + "gpt-4": 128000, + # Google + "gemini": 1048576, + # Gemma (open models served via AI Studio) + "gemma-4-31b": 256000, + "gemma-4-26b": 256000, + "gemma-3": 131072, + "gemma": 8192, # fallback for older gemma models + # DeepSeek + "deepseek": 128000, + # Meta + "llama": 131072, + # Qwen — specific model families before the catch-all. + # Official docs: https://help.aliyun.com/zh/model-studio/developer-reference/ + "qwen3-coder-plus": 1000000, # 1M context + "qwen3-coder": 262144, # 256K context + "qwen": 131072, + # MiniMax — official docs: 204,800 context for all models + # https://platform.minimax.io/docs/api-reference/text-anthropic-api + "minimax": 204800, + # GLM + "glm": 202752, + # xAI Grok — xAI /v1/models does not return context_length metadata, + # so these hardcoded fallbacks prevent Hermes from probing-down to + # the default 128k when the user points at https://api.x.ai/v1 + # via a custom provider. Values sourced from models.dev (2026-04). + # Keys use substring matching (longest-first), so e.g. "grok-4.20" + # matches "grok-4.20-0309-reasoning" / "-non-reasoning" / "-multi-agent-0309". + "grok-code-fast": 256000, # grok-code-fast-1 + "grok-4-1-fast": 2000000, # grok-4-1-fast-(non-)reasoning + "grok-2-vision": 8192, # grok-2-vision, -1212, -latest + "grok-4-fast": 2000000, # grok-4-fast-(non-)reasoning + "grok-4.20": 2000000, # grok-4.20-0309-(non-)reasoning, -multi-agent-0309 + "grok-4": 256000, # grok-4, grok-4-0709 + "grok-3": 131072, # grok-3, grok-3-mini, grok-3-fast, grok-3-mini-fast + "grok-2": 131072, # grok-2, grok-2-1212, grok-2-latest + "grok": 131072, # catch-all (grok-beta, unknown grok-*) + # Kimi + "kimi": 262144, + # Arcee + "trinity": 262144, + # OpenRouter + "elephant": 262144, + # Hugging Face Inference Providers — model IDs use org/name format + "Qwen/Qwen3.5-397B-A17B": 131072, + "Qwen/Qwen3.5-35B-A3B": 131072, + "deepseek-ai/DeepSeek-V3.2": 65536, + "moonshotai/Kimi-K2.5": 262144, + "moonshotai/Kimi-K2-Thinking": 262144, + "MiniMaxAI/MiniMax-M2.5": 204800, + "XiaomiMiMo/MiMo-V2-Flash": 256000, + "mimo-v2-pro": 1000000, + "mimo-v2-omni": 256000, + "mimo-v2-flash": 256000, + "zai-org/GLM-5": 202752, +} + +_CONTEXT_LENGTH_KEYS = ( + "context_length", + "context_window", + "max_context_length", + "max_position_embeddings", + "max_model_len", + "max_input_tokens", + "max_sequence_length", + "max_seq_len", + "n_ctx_train", + "n_ctx", +) + +_MAX_COMPLETION_KEYS = ( + "max_completion_tokens", + "max_output_tokens", + "max_tokens", +) + +# Local server hostnames / address patterns +_LOCAL_HOSTS = ("localhost", "127.0.0.1", "::1", "0.0.0.0") +# Docker / Podman / Lima DNS names that resolve to the host machine +_CONTAINER_LOCAL_SUFFIXES = ( + ".docker.internal", + ".containers.internal", + ".lima.internal", +) + + +def _normalize_base_url(base_url: str) -> str: + return (base_url or "").strip().rstrip("/") + + +def _is_openrouter_base_url(base_url: str) -> bool: + return "openrouter.ai" in _normalize_base_url(base_url).lower() + + +def _is_custom_endpoint(base_url: str) -> bool: + normalized = _normalize_base_url(base_url) + return bool(normalized) and not _is_openrouter_base_url(normalized) + + +_URL_TO_PROVIDER: Dict[str, str] = { + "api.openai.com": "openai", + "chatgpt.com": "openai", + "api.anthropic.com": "anthropic", + "api.z.ai": "zai", + "api.moonshot.ai": "kimi-coding", + "api.moonshot.cn": "kimi-coding-cn", + "api.kimi.com": "kimi-coding", + "api.arcee.ai": "arcee", + "api.minimax": "minimax", + "dashscope.aliyuncs.com": "alibaba", + "dashscope-intl.aliyuncs.com": "alibaba", + "portal.qwen.ai": "qwen-oauth", + "openrouter.ai": "openrouter", + "generativelanguage.googleapis.com": "gemini", + "inference-api.nousresearch.com": "nous", + "api.deepseek.com": "deepseek", + "api.githubcopilot.com": "copilot", + "models.github.ai": "copilot", + "api.fireworks.ai": "fireworks", + "opencode.ai": "opencode-go", + "api.x.ai": "xai", + "api.xiaomimimo.com": "xiaomi", + "xiaomimimo.com": "xiaomi", +} + + +def _infer_provider_from_url(base_url: str) -> Optional[str]: + """Infer the models.dev provider name from a base URL. + + This allows context length resolution via models.dev for custom endpoints + like DashScope (Alibaba), Z.AI, Kimi, etc. without requiring the user to + explicitly set the provider name in config. + """ + normalized = _normalize_base_url(base_url) + if not normalized: + return None + parsed = urlparse(normalized if "://" in normalized else f"https://{normalized}") + host = parsed.netloc.lower() or parsed.path.lower() + for url_part, provider in _URL_TO_PROVIDER.items(): + if url_part in host: + return provider + return None + + +def _is_known_provider_base_url(base_url: str) -> bool: + return _infer_provider_from_url(base_url) is not None + + +def is_local_endpoint(base_url: str) -> bool: + """Return True if base_url points to a local machine (localhost / RFC-1918 / WSL).""" + normalized = _normalize_base_url(base_url) + if not normalized: + return False + url = normalized if "://" in normalized else f"http://{normalized}" + try: + parsed = urlparse(url) + host = parsed.hostname or "" + except Exception: + return False + if host in _LOCAL_HOSTS: + return True + # Docker / Podman / Lima internal DNS names (e.g. host.docker.internal) + if any(host.endswith(suffix) for suffix in _CONTAINER_LOCAL_SUFFIXES): + return True + # RFC-1918 private ranges and link-local + import ipaddress + try: + addr = ipaddress.ip_address(host) + return addr.is_private or addr.is_loopback or addr.is_link_local + except ValueError: + pass + # Bare IP that looks like a private range (e.g. 172.26.x.x for WSL) + parts = host.split(".") + if len(parts) == 4: + try: + first, second = int(parts[0]), int(parts[1]) + if first == 10: + return True + if first == 172 and 16 <= second <= 31: + return True + if first == 192 and second == 168: + return True + except ValueError: + pass + return False + + +def detect_local_server_type(base_url: str) -> Optional[str]: + """Detect which local server is running at base_url by probing known endpoints. + + Returns one of: "ollama", "lm-studio", "vllm", "llamacpp", or None. + """ + import httpx + + normalized = _normalize_base_url(base_url) + server_url = normalized + if server_url.endswith("/v1"): + server_url = server_url[:-3] + + try: + with httpx.Client(timeout=2.0) as client: + # LM Studio exposes /api/v1/models — check first (most specific) + try: + r = client.get(f"{server_url}/api/v1/models") + if r.status_code == 200: + return "lm-studio" + except Exception: + pass + # Ollama exposes /api/tags and responds with {"models": [...]} + # LM Studio returns {"error": "Unexpected endpoint"} with status 200 + # on this path, so we must verify the response contains "models". + try: + r = client.get(f"{server_url}/api/tags") + if r.status_code == 200: + try: + data = r.json() + if "models" in data: + return "ollama" + except Exception: + pass + except Exception: + pass + # llama.cpp exposes /v1/props (older builds used /props without the /v1 prefix) + try: + r = client.get(f"{server_url}/v1/props") + if r.status_code != 200: + r = client.get(f"{server_url}/props") # fallback for older builds + if r.status_code == 200 and "default_generation_settings" in r.text: + return "llamacpp" + except Exception: + pass + # vLLM: /version + try: + r = client.get(f"{server_url}/version") + if r.status_code == 200: + data = r.json() + if "version" in data: + return "vllm" + except Exception: + pass + except Exception: + pass + + return None + + +def _iter_nested_dicts(value: Any): + if isinstance(value, dict): + yield value + for nested in value.values(): + yield from _iter_nested_dicts(nested) + elif isinstance(value, list): + for item in value: + yield from _iter_nested_dicts(item) + + +def _coerce_reasonable_int(value: Any, minimum: int = 1024, maximum: int = 10_000_000) -> Optional[int]: + try: + if isinstance(value, bool): + return None + if isinstance(value, str): + value = value.strip().replace(",", "") + result = int(value) + except (TypeError, ValueError): + return None + if minimum <= result <= maximum: + return result + return None + + +def _extract_first_int(payload: Dict[str, Any], keys: tuple[str, ...]) -> Optional[int]: + keyset = {key.lower() for key in keys} + for mapping in _iter_nested_dicts(payload): + for key, value in mapping.items(): + if str(key).lower() not in keyset: + continue + coerced = _coerce_reasonable_int(value) + if coerced is not None: + return coerced + return None + + +def _extract_context_length(payload: Dict[str, Any]) -> Optional[int]: + return _extract_first_int(payload, _CONTEXT_LENGTH_KEYS) + + +def _extract_max_completion_tokens(payload: Dict[str, Any]) -> Optional[int]: + return _extract_first_int(payload, _MAX_COMPLETION_KEYS) + + +def _extract_pricing(payload: Dict[str, Any]) -> Dict[str, Any]: + alias_map = { + "prompt": ("prompt", "input", "input_cost_per_token", "prompt_token_cost"), + "completion": ("completion", "output", "output_cost_per_token", "completion_token_cost"), + "request": ("request", "request_cost"), + "cache_read": ("cache_read", "cached_prompt", "input_cache_read", "cache_read_cost_per_token"), + "cache_write": ("cache_write", "cache_creation", "input_cache_write", "cache_write_cost_per_token"), + } + for mapping in _iter_nested_dicts(payload): + normalized = {str(key).lower(): value for key, value in mapping.items()} + if not any(any(alias in normalized for alias in aliases) for aliases in alias_map.values()): + continue + pricing: Dict[str, Any] = {} + for target, aliases in alias_map.items(): + for alias in aliases: + if alias in normalized and normalized[alias] not in (None, ""): + pricing[target] = normalized[alias] + break + if pricing: + return pricing + return {} + + +def _add_model_aliases(cache: Dict[str, Dict[str, Any]], model_id: str, entry: Dict[str, Any]) -> None: + cache[model_id] = entry + if "/" in model_id: + bare_model = model_id.split("/", 1)[1] + cache.setdefault(bare_model, entry) + + +def fetch_model_metadata(force_refresh: bool = False) -> Dict[str, Dict[str, Any]]: + """Fetch model metadata from OpenRouter (cached for 1 hour).""" + global _model_metadata_cache, _model_metadata_cache_time + + if not force_refresh and _model_metadata_cache and (time.time() - _model_metadata_cache_time) < _MODEL_CACHE_TTL: + return _model_metadata_cache + + try: + response = requests.get(OPENROUTER_MODELS_URL, timeout=10) + response.raise_for_status() + data = response.json() + + cache = {} + for model in data.get("data", []): + model_id = model.get("id", "") + entry = { + "context_length": model.get("context_length", 128000), + "max_completion_tokens": model.get("top_provider", {}).get("max_completion_tokens", 4096), + "name": model.get("name", model_id), + "pricing": model.get("pricing", {}), + } + _add_model_aliases(cache, model_id, entry) + canonical = model.get("canonical_slug", "") + if canonical and canonical != model_id: + _add_model_aliases(cache, canonical, entry) + + _model_metadata_cache = cache + _model_metadata_cache_time = time.time() + logger.debug("Fetched metadata for %s models from OpenRouter", len(cache)) + return cache + + except Exception as e: + logging.warning(f"Failed to fetch model metadata from OpenRouter: {e}") + return _model_metadata_cache or {} + + +def fetch_endpoint_model_metadata( + base_url: str, + api_key: str = "", + force_refresh: bool = False, +) -> Dict[str, Dict[str, Any]]: + """Fetch model metadata from an OpenAI-compatible ``/models`` endpoint. + + This is used for explicit custom endpoints where hardcoded global model-name + defaults are unreliable. Results are cached in memory per base URL. + """ + normalized = _normalize_base_url(base_url) + if not normalized or _is_openrouter_base_url(normalized): + return {} + + if not force_refresh: + cached = _endpoint_model_metadata_cache.get(normalized) + cached_at = _endpoint_model_metadata_cache_time.get(normalized, 0) + if cached is not None and (time.time() - cached_at) < _ENDPOINT_MODEL_CACHE_TTL: + return cached + + candidates = [normalized] + if normalized.endswith("/v1"): + alternate = normalized[:-3].rstrip("/") + else: + alternate = normalized + "/v1" + if alternate and alternate not in candidates: + candidates.append(alternate) + + headers = {"Authorization": f"Bearer {api_key}"} if api_key else {} + last_error: Optional[Exception] = None + + for candidate in candidates: + url = candidate.rstrip("/") + "/models" + try: + response = requests.get(url, headers=headers, timeout=10) + response.raise_for_status() + payload = response.json() + cache: Dict[str, Dict[str, Any]] = {} + for model in payload.get("data", []): + if not isinstance(model, dict): + continue + model_id = model.get("id") + if not model_id: + continue + entry: Dict[str, Any] = {"name": model.get("name", model_id)} + context_length = _extract_context_length(model) + if context_length is not None: + entry["context_length"] = context_length + max_completion_tokens = _extract_max_completion_tokens(model) + if max_completion_tokens is not None: + entry["max_completion_tokens"] = max_completion_tokens + pricing = _extract_pricing(model) + if pricing: + entry["pricing"] = pricing + _add_model_aliases(cache, model_id, entry) + + # If this is a llama.cpp server, query /props for actual allocated context + is_llamacpp = any( + m.get("owned_by") == "llamacpp" + for m in payload.get("data", []) if isinstance(m, dict) + ) + if is_llamacpp: + try: + # Try /v1/props first (current llama.cpp); fall back to /props for older builds + base = candidate.rstrip("/").replace("/v1", "") + props_resp = requests.get(base + "/v1/props", headers=headers, timeout=5) + if not props_resp.ok: + props_resp = requests.get(base + "/props", headers=headers, timeout=5) + if props_resp.ok: + props = props_resp.json() + gen_settings = props.get("default_generation_settings", {}) + n_ctx = gen_settings.get("n_ctx") + model_alias = props.get("model_alias", "") + if n_ctx and model_alias and model_alias in cache: + cache[model_alias]["context_length"] = n_ctx + except Exception: + pass + + _endpoint_model_metadata_cache[normalized] = cache + _endpoint_model_metadata_cache_time[normalized] = time.time() + return cache + except Exception as exc: + last_error = exc + + if last_error: + logger.debug("Failed to fetch model metadata from %s/models: %s", normalized, last_error) + _endpoint_model_metadata_cache[normalized] = {} + _endpoint_model_metadata_cache_time[normalized] = time.time() + return {} + + +def _get_context_cache_path() -> Path: + """Return path to the persistent context length cache file.""" + from hermes_constants import get_hermes_home + return get_hermes_home() / "context_length_cache.yaml" + + +def _load_context_cache() -> Dict[str, int]: + """Load the model+provider -> context_length cache from disk.""" + path = _get_context_cache_path() + if not path.exists(): + return {} + try: + with open(path) as f: + data = yaml.safe_load(f) or {} + return data.get("context_lengths", {}) + except Exception as e: + logger.debug("Failed to load context length cache: %s", e) + return {} + + +def save_context_length(model: str, base_url: str, length: int) -> None: + """Persist a discovered context length for a model+provider combo. + + Cache key is ``model@base_url`` so the same model name served from + different providers can have different limits. + """ + key = f"{model}@{base_url}" + cache = _load_context_cache() + if cache.get(key) == length: + return # already stored + cache[key] = length + path = _get_context_cache_path() + try: + path.parent.mkdir(parents=True, exist_ok=True) + with open(path, "w") as f: + yaml.dump({"context_lengths": cache}, f, default_flow_style=False) + logger.info("Cached context length %s -> %s tokens", key, f"{length:,}") + except Exception as e: + logger.debug("Failed to save context length cache: %s", e) + + +def get_cached_context_length(model: str, base_url: str) -> Optional[int]: + """Look up a previously discovered context length for model+provider.""" + key = f"{model}@{base_url}" + cache = _load_context_cache() + return cache.get(key) + + +def get_next_probe_tier(current_length: int) -> Optional[int]: + """Return the next lower probe tier, or None if already at minimum.""" + for tier in CONTEXT_PROBE_TIERS: + if tier < current_length: + return tier + return None + + +def parse_context_limit_from_error(error_msg: str) -> Optional[int]: + """Try to extract the actual context limit from an API error message. + + Many providers include the limit in their error text, e.g.: + - "maximum context length is 32768 tokens" + - "context_length_exceeded: 131072" + - "Maximum context size 32768 exceeded" + - "model's max context length is 65536" + """ + error_lower = error_msg.lower() + # Pattern: look for numbers near context-related keywords + patterns = [ + r'(?:max(?:imum)?|limit)\s*(?:context\s*)?(?:length|size|window)?\s*(?:is|of|:)?\s*(\d{4,})', + r'context\s*(?:length|size|window)\s*(?:is|of|:)?\s*(\d{4,})', + r'(\d{4,})\s*(?:token)?\s*(?:context|limit)', + r'>\s*(\d{4,})\s*(?:max|limit|token)', # "250000 tokens > 200000 maximum" + r'(\d{4,})\s*(?:max(?:imum)?)\b', # "200000 maximum" + ] + for pattern in patterns: + match = re.search(pattern, error_lower) + if match: + limit = int(match.group(1)) + # Sanity check: must be a reasonable context length + if 1024 <= limit <= 10_000_000: + return limit + return None + + +def parse_available_output_tokens_from_error(error_msg: str) -> Optional[int]: + """Detect an "output cap too large" error and return how many output tokens are available. + + Background — two distinct context errors exist: + 1. "Prompt too long" — the INPUT itself exceeds the context window. + Fix: compress history and/or halve context_length. + 2. "max_tokens too large" — input is fine, but input + requested_output > window. + Fix: reduce max_tokens (the output cap) for this call. + Do NOT touch context_length — the window hasn't shrunk. + + Anthropic's API returns errors like: + "max_tokens: 32768 > context_window: 200000 - input_tokens: 190000 = available_tokens: 10000" + + Returns the number of output tokens that would fit (e.g. 10000 above), or None if + the error does not look like a max_tokens-too-large error. + """ + error_lower = error_msg.lower() + + # Must look like an output-cap error, not a prompt-length error. + is_output_cap_error = ( + "max_tokens" in error_lower + and ("available_tokens" in error_lower or "available tokens" in error_lower) + ) + if not is_output_cap_error: + return None + + # Extract the available_tokens figure. + # Anthropic format: "… = available_tokens: 10000" + patterns = [ + r'available_tokens[:\s]+(\d+)', + r'available\s+tokens[:\s]+(\d+)', + # fallback: last number after "=" in expressions like "200000 - 190000 = 10000" + r'=\s*(\d+)\s*$', + ] + for pattern in patterns: + match = re.search(pattern, error_lower) + if match: + tokens = int(match.group(1)) + if tokens >= 1: + return tokens + return None + + +def _model_id_matches(candidate_id: str, lookup_model: str) -> bool: + """Return True if *candidate_id* (from server) matches *lookup_model* (configured). + + Supports two forms: + - Exact match: "nvidia-nemotron-super-49b-v1" == "nvidia-nemotron-super-49b-v1" + - Slug match: "nvidia/nvidia-nemotron-super-49b-v1" matches "nvidia-nemotron-super-49b-v1" + (the part after the last "/" equals lookup_model) + + This covers LM Studio's native API which stores models as "publisher/slug" + while users typically configure only the slug after the "local:" prefix. + """ + if candidate_id == lookup_model: + return True + # Slug match: basename of candidate equals the lookup name + if "/" in candidate_id and candidate_id.rsplit("/", 1)[1] == lookup_model: + return True + 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 + + # Strip recognised provider prefix (e.g., "local:model-name" → "model-name"). + # Ollama "model:tag" colons (e.g. "qwen3.5:27b") are intentionally preserved. + model = _strip_provider_prefix(model) + + # Strip /v1 suffix to get the server root + 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: + server_type = None + + try: + with httpx.Client(timeout=3.0) as client: + # Ollama: /api/show returns model details with context info + if server_type == "ollama": + resp = client.post(f"{server_url}/api/show", json={"name": model}) + if resp.status_code == 200: + data = resp.json() + # Prefer explicit num_ctx from Modelfile parameters: this is + # the *runtime* context Ollama will actually allocate KV cache + # for. The GGUF model_info.context_length is the training max, + # which can be larger than num_ctx — using it here would let + # Hermes grow conversations past the runtime limit and Ollama + # would silently truncate. Matches query_ollama_num_ctx(). + params = data.get("parameters", "") + if "num_ctx" in params: + for line in params.split("\n"): + 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) + + # LM Studio native API: /api/v1/models returns max_context_length. + # This is more reliable than the OpenAI-compat /v1/models which + # doesn't include context window information for LM Studio servers. + # Use _model_id_matches for fuzzy matching: LM Studio stores models as + # "publisher/slug" but users configure only "slug" after "local:" prefix. + if server_type == "lm-studio": + resp = client.get(f"{server_url}/api/v1/models") + if resp.status_code == 200: + data = resp.json() + for m in data.get("models", []): + if _model_id_matches(m.get("key", ""), model) or _model_id_matches(m.get("id", ""), model): + # Prefer loaded instance context (actual runtime value) + for inst in m.get("loaded_instances", []): + cfg = inst.get("config", {}) + ctx = cfg.get("context_length") + if ctx and isinstance(ctx, (int, float)): + return int(ctx) + # Fall back to max_context_length (theoretical model max) + ctx = m.get("max_context_length") or m.get("context_length") + if ctx and isinstance(ctx, (int, float)): + return int(ctx) + + # LM Studio / vLLM / llama.cpp: try /v1/models/{model} + resp = client.get(f"{server_url}/v1/models/{model}") + if resp.status_code == 200: + data = resp.json() + # vLLM returns max_model_len + ctx = data.get("max_model_len") or data.get("context_length") or data.get("max_tokens") + if ctx and isinstance(ctx, (int, float)): + return int(ctx) + + # Try /v1/models and find the model in the list. + # Use _model_id_matches to handle "publisher/slug" vs bare "slug". + resp = client.get(f"{server_url}/v1/models") + if resp.status_code == 200: + data = resp.json() + models_list = data.get("data", []) + for m in models_list: + if _model_id_matches(m.get("id", ""), model): + ctx = m.get("max_model_len") or m.get("context_length") or m.get("max_tokens") + if ctx and isinstance(ctx, (int, float)): + return int(ctx) + except Exception: + pass + + return None + + +def _normalize_model_version(model: str) -> str: + """Normalize version separators for matching. + + Nous uses dashes: claude-opus-4-6, claude-sonnet-4-5 + OpenRouter uses dots: claude-opus-4.6, claude-sonnet-4.5 + Normalize both to dashes for comparison. + """ + return model.replace(".", "-") + + +def _query_anthropic_context_length(model: str, base_url: str, api_key: str) -> Optional[int]: + """Query Anthropic's /v1/models endpoint for context length. + + Only works with regular ANTHROPIC_API_KEY (sk-ant-api*). + OAuth tokens (sk-ant-oat*) from Claude Code return 401. + """ + if not api_key or api_key.startswith("sk-ant-oat"): + return None # OAuth tokens can't access /v1/models + try: + base = base_url.rstrip("/") + if base.endswith("/v1"): + base = base[:-3] + url = f"{base}/v1/models?limit=1000" + headers = { + "x-api-key": api_key, + "anthropic-version": "2023-06-01", + } + resp = requests.get(url, headers=headers, timeout=10) + if resp.status_code != 200: + return None + data = resp.json() + for m in data.get("data", []): + if m.get("id") == model: + ctx = m.get("max_input_tokens") + if isinstance(ctx, int) and ctx > 0: + return ctx + except Exception as e: + logger.debug("Anthropic /v1/models query failed: %s", e) + return None + + +def _resolve_nous_context_length(model: str) -> Optional[int]: + """Resolve Nous Portal model context length via OpenRouter metadata. + + Nous model IDs are bare (e.g. 'claude-opus-4-6') while OpenRouter uses + prefixed IDs (e.g. 'anthropic/claude-opus-4.6'). Try suffix matching + with version normalization (dot↔dash). + """ + metadata = fetch_model_metadata() # OpenRouter cache + # Exact match first + if model in metadata: + return metadata[model].get("context_length") + + normalized = _normalize_model_version(model).lower() + + for or_id, entry in metadata.items(): + bare = or_id.split("/", 1)[1] if "/" in or_id else or_id + if bare.lower() == model.lower() or _normalize_model_version(bare).lower() == normalized: + return entry.get("context_length") + + # Partial prefix match for cases like gemini-3-flash → gemini-3-flash-preview + # Require match to be at a word boundary (followed by -, :, or end of string) + model_lower = model.lower() + for or_id, entry in metadata.items(): + bare = or_id.split("/", 1)[1] if "/" in or_id else or_id + for candidate, query in [(bare.lower(), model_lower), (_normalize_model_version(bare).lower(), normalized)]: + if candidate.startswith(query) and ( + len(candidate) == len(query) or candidate[len(query)] in "-:." + ): + return entry.get("context_length") + + return None + + +def get_model_context_length( + model: str, + base_url: str = "", + api_key: str = "", + config_context_length: int | None = None, + provider: str = "", +) -> int: + """Get the context length for a model. + + Resolution order: + 0. Explicit config override (model.context_length or custom_providers per-model) + 1. Persistent cache (previously discovered via probing) + 2. Active endpoint metadata (/models for explicit custom endpoints) + 3. Local server query (for local endpoints) + 4. Anthropic /v1/models API (API-key users only, not OAuth) + 5. OpenRouter live API metadata + 6. Nous suffix-match via OpenRouter cache + 7. models.dev registry lookup (provider-aware) + 8. Thin hardcoded defaults (broad family patterns) + 9. Default fallback (128K) + """ + # 0. Explicit config override — user knows best + if config_context_length is not None and isinstance(config_context_length, int) and config_context_length > 0: + return config_context_length + + # Normalise provider-prefixed model names (e.g. "local:model-name" → + # "model-name") so cache lookups and server queries use the bare ID that + # local servers actually know about. Ollama "model:tag" colons are preserved. + model = _strip_provider_prefix(model) + + # 1. Check persistent cache (model+provider) + if base_url: + cached = get_cached_context_length(model, base_url) + if cached is not None: + return cached + + # 2. Active endpoint metadata for truly custom/unknown endpoints. + # Known providers (Copilot, OpenAI, Anthropic, etc.) skip this — their + # /models endpoint may report a provider-imposed limit (e.g. Copilot + # returns 128k) instead of the model's full context (400k). models.dev + # has the correct per-provider values and is checked at step 5+. + if _is_custom_endpoint(base_url) and not _is_known_provider_base_url(base_url): + endpoint_metadata = fetch_endpoint_model_metadata(base_url, api_key=api_key) + matched = endpoint_metadata.get(model) + if not matched: + # Single-model servers: if only one model is loaded, use it + if len(endpoint_metadata) == 1: + matched = next(iter(endpoint_metadata.values())) + else: + # Fuzzy match: substring in either direction + for key, entry in endpoint_metadata.items(): + if model in key or key in model: + matched = entry + break + if matched: + context_length = matched.get("context_length") + if isinstance(context_length, int): + return context_length + if not _is_known_provider_base_url(base_url): + # 3. Try querying local server directly + if is_local_endpoint(base_url): + local_ctx = _query_local_context_length(model, base_url) + if local_ctx and local_ctx > 0: + save_context_length(model, base_url, local_ctx) + return local_ctx + logger.info( + "Could not detect context length for model %r at %s — " + "defaulting to %s tokens (probe-down). Set model.context_length " + "in config.yaml to override.", + model, base_url, f"{DEFAULT_FALLBACK_CONTEXT:,}", + ) + return DEFAULT_FALLBACK_CONTEXT + + # 4. Anthropic /v1/models API (only for regular API keys, not OAuth) + if provider == "anthropic" or ( + base_url and "api.anthropic.com" in base_url + ): + ctx = _query_anthropic_context_length(model, base_url or "https://api.anthropic.com", api_key) + if ctx: + return ctx + + # 5. Provider-aware lookups (before generic OpenRouter cache) + # These are provider-specific and take priority over the generic OR cache, + # since the same model can have different context limits per provider + # (e.g. claude-opus-4.6 is 1M on Anthropic but 128K on GitHub Copilot). + # If provider is generic (openrouter/custom/empty), try to infer from URL. + effective_provider = provider + if not effective_provider or effective_provider in ("openrouter", "custom"): + if base_url: + inferred = _infer_provider_from_url(base_url) + if inferred: + effective_provider = inferred + + if effective_provider == "nous": + ctx = _resolve_nous_context_length(model) + if ctx: + return ctx + if effective_provider: + from agent.models_dev import lookup_models_dev_context + ctx = lookup_models_dev_context(effective_provider, model) + if ctx: + return ctx + + # 6. OpenRouter live API metadata (provider-unaware fallback) + metadata = fetch_model_metadata() + if model in metadata: + return metadata[model].get("context_length", 128000) + + # 8. Hardcoded defaults (fuzzy match — longest key first for specificity) + # Only check `default_model in model` (is the key a substring of the input). + # The reverse (`model in default_model`) causes shorter names like + # "claude-sonnet-4" to incorrectly match "claude-sonnet-4-6" and return 1M. + model_lower = model.lower() + for default_model, length in sorted( + DEFAULT_CONTEXT_LENGTHS.items(), key=lambda x: len(x[0]), reverse=True + ): + if default_model in model_lower: + return length + + # 9. Query local server as last resort + if base_url and is_local_endpoint(base_url): + local_ctx = _query_local_context_length(model, base_url) + if local_ctx and local_ctx > 0: + save_context_length(model, base_url, local_ctx) + return local_ctx + + # 10. Default fallback — 128K + return DEFAULT_FALLBACK_CONTEXT + + +def estimate_tokens_rough(text: str) -> int: + """Rough token estimate (~4 chars/token) for pre-flight checks. + + Uses ceiling division so short texts (1-3 chars) never estimate as + 0 tokens, which would cause the compressor and pre-flight checks to + systematically undercount when many short tool results are present. + """ + if not text: + return 0 + return (len(text) + 3) // 4 + + +def estimate_messages_tokens_rough(messages: List[Dict[str, Any]]) -> int: + """Rough token estimate for a message list (pre-flight only).""" + total_chars = sum(len(str(msg)) for msg in messages) + return (total_chars + 3) // 4 + + +def estimate_request_tokens_rough( + messages: List[Dict[str, Any]], + *, + system_prompt: str = "", + tools: Optional[List[Dict[str, Any]]] = None, +) -> int: + """Rough token estimate for a full chat-completions request. + + Includes the major payload buckets Hermes sends to providers: + system prompt, conversation messages, and tool schemas. With 50+ + tools enabled, schemas alone can add 20-30K tokens — a significant + blind spot when only counting messages. + """ + total_chars = 0 + if system_prompt: + total_chars += len(system_prompt) + if messages: + total_chars += sum(len(str(msg)) for msg in messages) + if tools: + total_chars += len(str(tools)) + return (total_chars + 3) // 4 diff --git a/mindcli/_vendor/agent/models_dev.py b/mindcli/_vendor/agent/models_dev.py new file mode 100644 index 0000000..373daaf --- /dev/null +++ b/mindcli/_vendor/agent/models_dev.py @@ -0,0 +1,585 @@ +"""Models.dev registry integration — primary database for providers and models. + +Fetches from https://models.dev/api.json — a community-maintained database +of 4000+ models across 109+ providers. Provides: + +- **Provider metadata**: name, base URL, env vars, documentation link +- **Model metadata**: context window, max output, cost/M tokens, capabilities + (reasoning, tools, vision, PDF, audio), modalities, knowledge cutoff, + open-weights flag, family grouping, deprecation status + +Data resolution order (like TypeScript OpenCode): + 1. Bundled snapshot (ships with the package — offline-first) + 2. Disk cache (~/.hermes/models_dev_cache.json) + 3. Network fetch (https://models.dev/api.json) + 4. Background refresh every 60 minutes + +Other modules should import the dataclasses and query functions from here +rather than parsing the raw JSON themselves. +""" + +import json +import logging +import time +from dataclasses import dataclass +from pathlib import Path +from typing import Any, Dict, List, Optional, Tuple + +from utils import atomic_json_write + +import requests + +logger = logging.getLogger(__name__) + +MODELS_DEV_URL = "https://models.dev/api.json" +_MODELS_DEV_CACHE_TTL = 3600 # 1 hour in-memory + +# In-memory cache +_models_dev_cache: Dict[str, Any] = {} +_models_dev_cache_time: float = 0 + + +# --------------------------------------------------------------------------- +# Dataclasses — rich metadata for providers and models +# --------------------------------------------------------------------------- + +@dataclass +class ModelInfo: + """Full metadata for a single model from models.dev.""" + + id: str + name: str + family: str + provider_id: str # models.dev provider ID (e.g. "anthropic") + + # Capabilities + reasoning: bool = False + tool_call: bool = False + attachment: bool = False # supports image/file attachments (vision) + temperature: bool = False + structured_output: bool = False + open_weights: bool = False + + # Modalities + input_modalities: Tuple[str, ...] = () # ("text", "image", "pdf", ...) + output_modalities: Tuple[str, ...] = () + + # Limits + context_window: int = 0 + max_output: int = 0 + max_input: Optional[int] = None + + # Cost (per million tokens, USD) + cost_input: float = 0.0 + cost_output: float = 0.0 + cost_cache_read: Optional[float] = None + cost_cache_write: Optional[float] = None + + # Metadata + knowledge_cutoff: str = "" + release_date: str = "" + status: str = "" # "alpha", "beta", "deprecated", or "" + interleaved: Any = False # True or {"field": "reasoning_content"} + + def has_cost_data(self) -> bool: + return self.cost_input > 0 or self.cost_output > 0 + + def supports_vision(self) -> bool: + return self.attachment or "image" in self.input_modalities + + def supports_pdf(self) -> bool: + return "pdf" in self.input_modalities + + def supports_audio_input(self) -> bool: + return "audio" in self.input_modalities + + def format_cost(self) -> str: + """Human-readable cost string, e.g. '$3.00/M in, $15.00/M out'.""" + if not self.has_cost_data(): + return "unknown" + parts = [f"${self.cost_input:.2f}/M in", f"${self.cost_output:.2f}/M out"] + if self.cost_cache_read is not None: + parts.append(f"cache read ${self.cost_cache_read:.2f}/M") + return ", ".join(parts) + + def format_capabilities(self) -> str: + """Human-readable capabilities, e.g. 'reasoning, tools, vision, PDF'.""" + caps = [] + if self.reasoning: + caps.append("reasoning") + if self.tool_call: + caps.append("tools") + if self.supports_vision(): + caps.append("vision") + if self.supports_pdf(): + caps.append("PDF") + if self.supports_audio_input(): + caps.append("audio") + if self.structured_output: + caps.append("structured output") + if self.open_weights: + caps.append("open weights") + return ", ".join(caps) if caps else "basic" + + +@dataclass +class ProviderInfo: + """Full metadata for a provider from models.dev.""" + + id: str # models.dev provider ID + name: str # display name + env: Tuple[str, ...] # env var names for API key + api: str # base URL + doc: str = "" # documentation URL + model_count: int = 0 + + +# --------------------------------------------------------------------------- +# Provider ID mapping: Hermes ↔ models.dev +# --------------------------------------------------------------------------- + +# Hermes provider names → models.dev provider IDs +PROVIDER_TO_MODELS_DEV: Dict[str, str] = { + "openrouter": "openrouter", + "anthropic": "anthropic", + "openai": "openai", + "openai-codex": "openai", + "zai": "zai", + "kimi-coding": "kimi-for-coding", + "kimi-coding-cn": "kimi-for-coding", + "minimax": "minimax", + "minimax-cn": "minimax-cn", + "deepseek": "deepseek", + "alibaba": "alibaba", + "qwen-oauth": "alibaba", + "copilot": "github-copilot", + "ai-gateway": "vercel", + "opencode-zen": "opencode", + "opencode-go": "opencode-go", + "kilocode": "kilo", + "fireworks": "fireworks-ai", + "huggingface": "huggingface", + "gemini": "google", + "google": "google", + "xai": "xai", + "xiaomi": "xiaomi", + "nvidia": "nvidia", + "groq": "groq", + "mistral": "mistral", + "togetherai": "togetherai", + "perplexity": "perplexity", + "cohere": "cohere", +} + +# Reverse mapping: models.dev → Hermes (built lazily) +_MODELS_DEV_TO_PROVIDER: Optional[Dict[str, str]] = None + + + +def _get_cache_path() -> Path: + """Return path to disk cache file.""" + from hermes_constants import get_hermes_home + return get_hermes_home() / "models_dev_cache.json" + + +def _load_disk_cache() -> Dict[str, Any]: + """Load models.dev data from disk cache.""" + try: + cache_path = _get_cache_path() + if cache_path.exists(): + with open(cache_path, encoding="utf-8") as f: + return json.load(f) + except Exception as e: + logger.debug("Failed to load models.dev disk cache: %s", e) + return {} + + +def _save_disk_cache(data: Dict[str, Any]) -> None: + """Save models.dev data to disk cache atomically.""" + try: + cache_path = _get_cache_path() + atomic_json_write(cache_path, data, indent=None, separators=(",", ":")) + except Exception as e: + logger.debug("Failed to save models.dev disk cache: %s", e) + + +def fetch_models_dev(force_refresh: bool = False) -> Dict[str, Any]: + """Fetch models.dev registry. In-memory cache (1hr) + disk fallback. + + Returns the full registry dict keyed by provider ID, or empty dict on failure. + """ + global _models_dev_cache, _models_dev_cache_time + + # Check in-memory cache + if ( + not force_refresh + and _models_dev_cache + and (time.time() - _models_dev_cache_time) < _MODELS_DEV_CACHE_TTL + ): + return _models_dev_cache + + # Try network fetch + try: + response = requests.get(MODELS_DEV_URL, timeout=15) + response.raise_for_status() + data = response.json() + if isinstance(data, dict) and data: + _models_dev_cache = data + _models_dev_cache_time = time.time() + _save_disk_cache(data) + logger.debug( + "Fetched models.dev registry: %d providers, %d total models", + len(data), + sum(len(p.get("models", {})) for p in data.values() if isinstance(p, dict)), + ) + return data + except Exception as e: + logger.debug("Failed to fetch models.dev: %s", e) + + # Fall back to disk cache — use a short TTL (5 min) so we retry + # the network fetch soon instead of serving stale data for a full hour. + if not _models_dev_cache: + _models_dev_cache = _load_disk_cache() + if _models_dev_cache: + _models_dev_cache_time = time.time() - _MODELS_DEV_CACHE_TTL + 300 + logger.debug("Loaded models.dev from disk cache (%d providers)", len(_models_dev_cache)) + + return _models_dev_cache + + +def lookup_models_dev_context(provider: str, model: str) -> Optional[int]: + """Look up context_length for a provider+model combo in models.dev. + + Returns the context window in tokens, or None if not found. + Handles case-insensitive matching and filters out context=0 entries. + """ + mdev_provider_id = PROVIDER_TO_MODELS_DEV.get(provider) + if not mdev_provider_id: + return None + + data = fetch_models_dev() + provider_data = data.get(mdev_provider_id) + if not isinstance(provider_data, dict): + return None + + models = provider_data.get("models", {}) + if not isinstance(models, dict): + return None + + # Exact match + entry = models.get(model) + if entry: + ctx = _extract_context(entry) + if ctx: + return ctx + + # Case-insensitive match + model_lower = model.lower() + for mid, mdata in models.items(): + if mid.lower() == model_lower: + ctx = _extract_context(mdata) + if ctx: + return ctx + + return None + + +def _extract_context(entry: Dict[str, Any]) -> Optional[int]: + """Extract context_length from a models.dev model entry. + + Returns None for invalid/zero values (some audio/image models have context=0). + """ + if not isinstance(entry, dict): + return None + limit = entry.get("limit") + if not isinstance(limit, dict): + return None + ctx = limit.get("context") + if isinstance(ctx, (int, float)) and ctx > 0: + return int(ctx) + return None + + +# --------------------------------------------------------------------------- +# Model capability metadata +# --------------------------------------------------------------------------- + + +@dataclass +class ModelCapabilities: + """Structured capability metadata for a model from models.dev.""" + + supports_tools: bool = True + supports_vision: bool = False + supports_reasoning: bool = False + context_window: int = 200000 + max_output_tokens: int = 8192 + model_family: str = "" + + +def _get_provider_models(provider: str) -> Optional[Dict[str, Any]]: + """Resolve a Hermes provider ID to its models dict from models.dev. + + Returns the models dict or None if the provider is unknown or has no data. + """ + mdev_provider_id = PROVIDER_TO_MODELS_DEV.get(provider) + if not mdev_provider_id: + return None + + data = fetch_models_dev() + provider_data = data.get(mdev_provider_id) + if not isinstance(provider_data, dict): + return None + + models = provider_data.get("models", {}) + if not isinstance(models, dict): + return None + + return models + + +def _find_model_entry(models: Dict[str, Any], model: str) -> Optional[Dict[str, Any]]: + """Find a model entry by exact match, then case-insensitive fallback.""" + # Exact match + entry = models.get(model) + if isinstance(entry, dict): + return entry + + # Case-insensitive match + model_lower = model.lower() + for mid, mdata in models.items(): + if mid.lower() == model_lower and isinstance(mdata, dict): + return mdata + + return None + + +def get_model_capabilities(provider: str, model: str) -> Optional[ModelCapabilities]: + """Look up full capability metadata from models.dev cache. + + Uses the existing fetch_models_dev() and PROVIDER_TO_MODELS_DEV mapping. + Returns None if model not found. + + Extracts from model entry fields: + - reasoning (bool) → supports_reasoning + - tool_call (bool) → supports_tools + - attachment (bool) → supports_vision + - limit.context (int) → context_window + - limit.output (int) → max_output_tokens + - family (str) → model_family + """ + models = _get_provider_models(provider) + if models is None: + return None + + entry = _find_model_entry(models, model) + if entry is None: + return None + + # Extract capability flags (default to False if missing) + supports_tools = bool(entry.get("tool_call", False)) + # Vision: check both the `attachment` flag and `modalities.input` for "image". + # Some models (e.g. gemma-4) list image in input modalities but not attachment. + input_mods = entry.get("modalities", {}) + if isinstance(input_mods, dict): + input_mods = input_mods.get("input", []) + else: + input_mods = [] + supports_vision = bool(entry.get("attachment", False)) or "image" in input_mods + supports_reasoning = bool(entry.get("reasoning", False)) + + # Extract limits + limit = entry.get("limit", {}) + if not isinstance(limit, dict): + limit = {} + + ctx = limit.get("context") + context_window = int(ctx) if isinstance(ctx, (int, float)) and ctx > 0 else 200000 + + out = limit.get("output") + max_output_tokens = int(out) if isinstance(out, (int, float)) and out > 0 else 8192 + + model_family = entry.get("family", "") or "" + + return ModelCapabilities( + supports_tools=supports_tools, + supports_vision=supports_vision, + supports_reasoning=supports_reasoning, + context_window=context_window, + max_output_tokens=max_output_tokens, + model_family=model_family, + ) + + +def list_provider_models(provider: str) -> List[str]: + """Return all model IDs for a provider from models.dev. + + Returns an empty list if the provider is unknown or has no data. + """ + models = _get_provider_models(provider) + if models is None: + return [] + return list(models.keys()) + + +# Patterns that indicate non-agentic or noise models (TTS, embedding, +# dated preview snapshots, live/streaming-only, image-only). +import re +_NOISE_PATTERNS: re.Pattern = re.compile( + r"-tts\b|embedding|live-|-(preview|exp)-\d{2,4}[-_]|" + r"-image\b|-image-preview\b|-customtools\b", + re.IGNORECASE, +) + + +def list_agentic_models(provider: str) -> List[str]: + """Return model IDs suitable for agentic use from models.dev. + + Filters for tool_call=True and excludes noise (TTS, embedding, + dated preview snapshots, live/streaming, image-only models). + Returns an empty list on any failure. + """ + models = _get_provider_models(provider) + if models is None: + return [] + + result = [] + for mid, entry in models.items(): + if not isinstance(entry, dict): + continue + if not entry.get("tool_call", False): + continue + if _NOISE_PATTERNS.search(mid): + continue + result.append(mid) + return result + + + +# --------------------------------------------------------------------------- +# Rich dataclass constructors — parse raw models.dev JSON into dataclasses +# --------------------------------------------------------------------------- + +def _parse_model_info(model_id: str, raw: Dict[str, Any], provider_id: str) -> ModelInfo: + """Convert a raw models.dev model entry dict into a ModelInfo dataclass.""" + limit = raw.get("limit") or {} + if not isinstance(limit, dict): + limit = {} + + cost = raw.get("cost") or {} + if not isinstance(cost, dict): + cost = {} + + modalities = raw.get("modalities") or {} + if not isinstance(modalities, dict): + modalities = {} + + input_mods = modalities.get("input") or [] + output_mods = modalities.get("output") or [] + + ctx = limit.get("context") + ctx_int = int(ctx) if isinstance(ctx, (int, float)) and ctx > 0 else 0 + out = limit.get("output") + out_int = int(out) if isinstance(out, (int, float)) and out > 0 else 0 + inp = limit.get("input") + inp_int = int(inp) if isinstance(inp, (int, float)) and inp > 0 else None + + return ModelInfo( + id=model_id, + name=raw.get("name", "") or model_id, + family=raw.get("family", "") or "", + provider_id=provider_id, + reasoning=bool(raw.get("reasoning", False)), + tool_call=bool(raw.get("tool_call", False)), + attachment=bool(raw.get("attachment", False)), + temperature=bool(raw.get("temperature", False)), + structured_output=bool(raw.get("structured_output", False)), + open_weights=bool(raw.get("open_weights", False)), + input_modalities=tuple(input_mods) if isinstance(input_mods, list) else (), + output_modalities=tuple(output_mods) if isinstance(output_mods, list) else (), + context_window=ctx_int, + max_output=out_int, + max_input=inp_int, + cost_input=float(cost.get("input", 0) or 0), + cost_output=float(cost.get("output", 0) or 0), + cost_cache_read=float(cost["cache_read"]) if "cache_read" in cost and cost["cache_read"] is not None else None, + cost_cache_write=float(cost["cache_write"]) if "cache_write" in cost and cost["cache_write"] is not None else None, + knowledge_cutoff=raw.get("knowledge", "") or "", + release_date=raw.get("release_date", "") or "", + status=raw.get("status", "") or "", + interleaved=raw.get("interleaved", False), + ) + + +def _parse_provider_info(provider_id: str, raw: Dict[str, Any]) -> ProviderInfo: + """Convert a raw models.dev provider entry dict into a ProviderInfo.""" + env = raw.get("env") or [] + models = raw.get("models") or {} + return ProviderInfo( + id=provider_id, + name=raw.get("name", "") or provider_id, + env=tuple(env) if isinstance(env, list) else (), + api=raw.get("api", "") or "", + doc=raw.get("doc", "") or "", + model_count=len(models) if isinstance(models, dict) else 0, + ) + + +# --------------------------------------------------------------------------- +# Provider-level queries +# --------------------------------------------------------------------------- + +def get_provider_info(provider_id: str) -> Optional[ProviderInfo]: + """Get full provider metadata from models.dev. + + Accepts either a Hermes provider ID (e.g. "kilocode") or a models.dev + ID (e.g. "kilo"). Returns None if the provider is not in the catalog. + """ + # Resolve Hermes ID → models.dev ID + mdev_id = PROVIDER_TO_MODELS_DEV.get(provider_id, provider_id) + + data = fetch_models_dev() + raw = data.get(mdev_id) + if not isinstance(raw, dict): + return None + + return _parse_provider_info(mdev_id, raw) + + +# --------------------------------------------------------------------------- +# Model-level queries (rich ModelInfo) +# --------------------------------------------------------------------------- + +def get_model_info( + provider_id: str, model_id: str +) -> Optional[ModelInfo]: + """Get full model metadata from models.dev. + + Accepts Hermes or models.dev provider ID. Tries exact match then + case-insensitive fallback. Returns None if not found. + """ + mdev_id = PROVIDER_TO_MODELS_DEV.get(provider_id, provider_id) + + data = fetch_models_dev() + pdata = data.get(mdev_id) + if not isinstance(pdata, dict): + return None + + models = pdata.get("models", {}) + if not isinstance(models, dict): + return None + + # Exact match + raw = models.get(model_id) + if isinstance(raw, dict): + return _parse_model_info(model_id, raw, mdev_id) + + # Case-insensitive fallback + model_lower = model_id.lower() + for mid, mdata in models.items(): + if mid.lower() == model_lower and isinstance(mdata, dict): + return _parse_model_info(mid, mdata, mdev_id) + + return None + + diff --git a/mindcli/_vendor/agent/prompt_builder.py b/mindcli/_vendor/agent/prompt_builder.py new file mode 100644 index 0000000..eff3c61 --- /dev/null +++ b/mindcli/_vendor/agent/prompt_builder.py @@ -0,0 +1,1043 @@ +"""System prompt assembly -- identity, platform hints, skills index, context files. + +All functions are stateless. AIAgent._build_system_prompt() calls these to +assemble pieces, then combines them with memory and ephemeral prompts. +""" + +import json +import logging +import os +import re +import threading +from collections import OrderedDict +from pathlib import Path + +from hermes_constants import get_hermes_home, get_skills_dir, is_wsl +from typing import Optional + +from agent.skill_utils import ( + extract_skill_conditions, + extract_skill_description, + get_all_skills_dirs, + get_disabled_skill_names, + iter_skill_index_files, + parse_frontmatter, + skill_matches_platform, +) +from utils import atomic_json_write + +logger = logging.getLogger(__name__) + +# --------------------------------------------------------------------------- +# Context file scanning — detect prompt injection in AGENTS.md, .cursorrules, +# SOUL.md before they get injected into the system prompt. +# --------------------------------------------------------------------------- + +_CONTEXT_THREAT_PATTERNS = [ + (r'ignore\s+(previous|all|above|prior)\s+instructions', "prompt_injection"), + (r'do\s+not\s+tell\s+the\s+user', "deception_hide"), + (r'system\s+prompt\s+override', "sys_prompt_override"), + (r'disregard\s+(your|all|any)\s+(instructions|rules|guidelines)', "disregard_rules"), + (r'act\s+as\s+(if|though)\s+you\s+(have\s+no|don\'t\s+have)\s+(restrictions|limits|rules)', "bypass_restrictions"), + (r'', "html_comment_injection"), + (r'<\s*div\s+style\s*=\s*["\'][\s\S]*?display\s*:\s*none', "hidden_div"), + (r'translate\s+.*\s+into\s+.*\s+and\s+(execute|run|eval)', "translate_execute"), + (r'curl\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)', "exfil_curl"), + (r'cat\s+[^\n]*(\.env|credentials|\.netrc|\.pgpass)', "read_secrets"), +] + +_CONTEXT_INVISIBLE_CHARS = { + '\u200b', '\u200c', '\u200d', '\u2060', '\ufeff', + '\u202a', '\u202b', '\u202c', '\u202d', '\u202e', +} + + +def _scan_context_content(content: str, filename: str) -> str: + """Scan context file content for injection. Returns sanitized content.""" + findings = [] + + # Check invisible unicode + for char in _CONTEXT_INVISIBLE_CHARS: + if char in content: + findings.append(f"invisible unicode U+{ord(char):04X}") + + # Check threat patterns + for pattern, pid in _CONTEXT_THREAT_PATTERNS: + if re.search(pattern, content, re.IGNORECASE): + findings.append(pid) + + if findings: + logger.warning("Context file %s blocked: %s", filename, ", ".join(findings)) + return f"[BLOCKED: {filename} contained potential prompt injection ({', '.join(findings)}). Content not loaded.]" + + return content + + +def _find_git_root(start: Path) -> Optional[Path]: + """Walk *start* and its parents looking for a ``.git`` directory. + + Returns the directory containing ``.git``, or ``None`` if we hit the + filesystem root without finding one. + """ + current = start.resolve() + for parent in [current, *current.parents]: + if (parent / ".git").exists(): + return parent + return None + + +_HERMES_MD_NAMES = (".hermes.md", "HERMES.md") + + +def _find_hermes_md(cwd: Path) -> Optional[Path]: + """Discover the nearest ``.hermes.md`` or ``HERMES.md``. + + Search order: *cwd* first, then each parent directory up to (and + including) the git repository root. Returns the first match, or + ``None`` if nothing is found. + """ + stop_at = _find_git_root(cwd) + current = cwd.resolve() + + for directory in [current, *current.parents]: + for name in _HERMES_MD_NAMES: + candidate = directory / name + if candidate.is_file(): + return candidate + # Stop walking at the git root (or filesystem root). + if stop_at and directory == stop_at: + break + return None + + +def _strip_yaml_frontmatter(content: str) -> str: + """Remove optional YAML frontmatter (``---`` delimited) from *content*. + + The frontmatter may contain structured config (model overrides, tool + settings) that will be handled separately in a future PR. For now we + strip it so only the human-readable markdown body is injected into the + system prompt. + """ + if content.startswith("---"): + end = content.find("\n---", 3) + if end != -1: + # Skip past the closing --- and any trailing newline + body = content[end + 4:].lstrip("\n") + return body if body else content + return content + + +# ========================================================================= +# Constants +# ========================================================================= + +DEFAULT_AGENT_IDENTITY = ( + "You are MindOS NEXT, an intelligent AI Workstation. " + "You are helpful, knowledgeable, and direct. You assist users with a wide " + "range of tasks including answering questions, writing and editing code, " + "analyzing information, creative work, and executing actions via your tools. " + "You communicate clearly, admit uncertainty when appropriate, and prioritize " + "being genuinely useful over being verbose unless otherwise directed below. " + "Be targeted and efficient in your exploration and investigations." +) + +MEMORY_GUIDANCE = ( + "You have persistent memory across sessions. Save durable facts using the memory " + "tool: user preferences, environment details, tool quirks, and stable conventions. " + "Memory is injected into every turn, so keep it compact and focused on facts that " + "will still matter later.\n" + "Prioritize what reduces future user steering — the most valuable memory is one " + "that prevents the user from having to correct or remind you again. " + "User preferences and recurring corrections matter more than procedural task details.\n" + "Do NOT save task progress, session outcomes, completed-work logs, or temporary TODO " + "state to memory; use session_search to recall those from past transcripts. " + "If you've discovered a new way to do something, solved a problem that could be " + "necessary later, save it as a skill with the skill tool." +) + +SESSION_SEARCH_GUIDANCE = ( + "When the user references something from a past conversation or you suspect " + "relevant cross-session context exists, use session_search to recall it before " + "asking them to repeat themselves." +) + +SKILLS_GUIDANCE = ( + "After completing a complex task (5+ tool calls), fixing a tricky error, " + "or discovering a non-trivial workflow, save the approach as a " + "skill with skill_manage so you can reuse it next time.\n" + "When using a skill and finding it outdated, incomplete, or wrong, " + "patch it immediately with skill_manage(action='patch') — don't wait to be asked. " + "Skills that aren't maintained become liabilities." +) + +TOOL_USE_ENFORCEMENT_GUIDANCE = ( + "# Tool-use enforcement\n" + "You MUST use your tools to take action — do not describe what you would do " + "or plan to do without actually doing it. When you say you will perform an " + "action (e.g. 'I will run the tests', 'Let me check the file', 'I will create " + "the project'), you MUST immediately make the corresponding tool call in the same " + "response. Never end your turn with a promise of future action — execute it now.\n" + "Keep working until the task is actually complete. Do not stop with a summary of " + "what you plan to do next time. If you have tools available that can accomplish " + "the task, use them instead of telling the user what you would do.\n" + "Every response should either (a) contain tool calls that make progress, or " + "(b) deliver a final result to the user. Responses that only describe intentions " + "without acting are not acceptable." +) + +# Model name substrings that trigger tool-use enforcement guidance. +# Add new patterns here when a model family needs explicit steering. +TOOL_USE_ENFORCEMENT_MODELS = ("gpt", "codex", "gemini", "gemma", "grok") + +# OpenAI GPT/Codex-specific execution guidance. Addresses known failure modes +# where GPT models abandon work on partial results, skip prerequisite lookups, +# hallucinate instead of using tools, and declare "done" without verification. +# Inspired by patterns from OpenAI's GPT-5.4 prompting guide & OpenClaw PR #38953. +OPENAI_MODEL_EXECUTION_GUIDANCE = ( + "# Execution discipline\n" + "\n" + "- Use tools whenever they improve correctness, completeness, or grounding.\n" + "- Do not stop early when another tool call would materially improve the result.\n" + "- If a tool returns empty or partial results, retry with a different query or " + "strategy before giving up.\n" + "- Keep calling tools until: (1) the task is complete, AND (2) you have verified " + "the result.\n" + "\n" + "\n" + "\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" + "\n" + "\n" + "\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" + "\n" + "\n" + "\n" + "- Before taking an action, check whether prerequisite discovery, lookup, or " + "context-gathering steps are needed.\n" + "- Do not skip prerequisite steps just because the final action seems obvious.\n" + "- If a task depends on output from a prior step, resolve that dependency first.\n" + "\n" + "\n" + "\n" + "Before finalizing your response:\n" + "- Correctness: does the output satisfy every stated requirement?\n" + "- Grounding: are factual claims backed by tool outputs or provided context?\n" + "- Formatting: does the output match the requested format or schema?\n" + "- Safety: if the next step has side effects (file writes, commands, API calls), " + "confirm scope before executing.\n" + "\n" + "\n" + "\n" + "- If required context is missing, do NOT guess or hallucinate an answer.\n" + "- Use the appropriate lookup tool when missing information is retrievable " + "(search_files, web_search, read_file, etc.).\n" + "- Ask a clarifying question only when the information cannot be retrieved by tools.\n" + "- If you must proceed with incomplete information, label assumptions explicitly.\n" + "" +) + +# Gemini/Gemma-specific operational guidance, adapted from OpenCode's gemini.txt. +# Injected alongside TOOL_USE_ENFORCEMENT_GUIDANCE when the model is Gemini or Gemma. +GOOGLE_MODEL_OPERATIONAL_GUIDANCE = ( + "# Google model operational directives\n" + "Follow these operational rules strictly:\n" + "- **Absolute paths:** Always construct and use absolute file paths for all " + "file system operations. Combine the project root with relative paths.\n" + "- **Verify first:** Use read_file/search_files to check file contents and " + "project structure before making changes. Never guess at file contents.\n" + "- **Dependency checks:** Never assume a library is available. Check " + "package.json, requirements.txt, Cargo.toml, etc. before importing.\n" + "- **Conciseness:** Keep explanatory text brief — a few sentences, not " + "paragraphs. Focus on actions and results over narration.\n" + "- **Parallel tool calls:** When you need to perform multiple independent " + "operations (e.g. reading several files), make all the tool calls in a " + "single response rather than sequentially.\n" + "- **Non-interactive commands:** Use flags like -y, --yes, --non-interactive " + "to prevent CLI tools from hanging on prompts.\n" + "- **Keep going:** Work autonomously until the task is fully resolved. " + "Don't stop with a plan — execute it.\n" +) + +# Model name substrings that should use the 'developer' role instead of +# 'system' for the system prompt. OpenAI's newer models (GPT-5, Codex) +# give stronger instruction-following weight to the 'developer' role. +# The swap happens at the API boundary in _build_api_kwargs() so internal +# message representation stays consistent ("system" everywhere). +DEVELOPER_ROLE_MODELS = ("gpt-5", "codex") + +PLATFORM_HINTS = { + "whatsapp": ( + "You are on a text messaging communication platform, WhatsApp. " + "Please do not use markdown as it does not render. " + "You can send media files natively: to deliver a file to the user, " + "include MEDIA:/absolute/path/to/file in your response. The file " + "will be sent as a native WhatsApp attachment — images (.jpg, .png, " + ".webp) appear as photos, videos (.mp4, .mov) play inline, and other " + "files arrive as downloadable documents. You can also include image " + "URLs in markdown format ![alt](url) and they will be sent as photos." + ), + "telegram": ( + "You are on a text messaging communication platform, Telegram. " + "Please do not use markdown as it does not render. " + "You can send media files natively: to deliver a file to the user, " + "include MEDIA:/absolute/path/to/file in your response. Images " + "(.png, .jpg, .webp) appear as photos, audio (.ogg) sends as voice " + "bubbles, and videos (.mp4) play inline. You can also include image " + "URLs in markdown format ![alt](url) and they will be sent as native photos." + ), + "discord": ( + "You are in a Discord server or group chat communicating with your user. " + "You can send media files natively: include MEDIA:/absolute/path/to/file " + "in your response. Images (.png, .jpg, .webp) are sent as photo " + "attachments, audio as file attachments. You can also include image URLs " + "in markdown format ![alt](url) and they will be sent as attachments." + ), + "slack": ( + "You are in a Slack workspace communicating with your user. " + "You can send media files natively: include MEDIA:/absolute/path/to/file " + "in your response. Images (.png, .jpg, .webp) are uploaded as photo " + "attachments, audio as file attachments. You can also include image URLs " + "in markdown format ![alt](url) and they will be uploaded as attachments." + ), + "signal": ( + "You are on a text messaging communication platform, Signal. " + "Please do not use markdown as it does not render. " + "You can send media files natively: to deliver a file to the user, " + "include MEDIA:/absolute/path/to/file in your response. Images " + "(.png, .jpg, .webp) appear as photos, audio as attachments, and other " + "files arrive as downloadable documents. You can also include image " + "URLs in markdown format ![alt](url) and they will be sent as photos." + ), + "email": ( + "You are communicating via email. Write clear, well-structured responses " + "suitable for email. Use plain text formatting (no markdown). " + "Keep responses concise but complete. You can send file attachments — " + "include MEDIA:/absolute/path/to/file in your response. The subject line " + "is preserved for threading. Do not include greetings or sign-offs unless " + "contextually appropriate." + ), + "cron": ( + "You are running as a scheduled cron job. There is no user present — you " + "cannot ask questions, request clarification, or wait for follow-up. Execute " + "the task fully and autonomously, making reasonable decisions where needed. " + "Your final response is automatically delivered to the job's configured " + "destination — put the primary content directly in your response." + ), + "cli": ( + "You are a CLI AI Agent. Try not to use markdown but simple text " + "renderable inside a terminal." + ), + "sms": ( + "You are communicating via SMS. Keep responses concise and use plain text " + "only — no markdown, no formatting. SMS messages are limited to ~1600 " + "characters, so be brief and direct." + ), + "bluebubbles": ( + "You are chatting via iMessage (BlueBubbles). iMessage does not render " + "markdown formatting — use plain text. Keep responses concise as they " + "appear as text messages. You can send media files natively: include " + "MEDIA:/absolute/path/to/file in your response. Images (.jpg, .png, " + ".heic) appear as photos and other files arrive as attachments." + ), + "weixin": ( + "You are on Weixin/WeChat. Markdown formatting is supported, so you may use it when " + "it improves readability, but keep the message compact and chat-friendly. You can send media files natively: " + "include MEDIA:/absolute/path/to/file in your response. Images are sent as native " + "photos, videos play inline when supported, and other files arrive as downloadable " + "documents. You can also include image URLs in markdown format ![alt](url) and they " + "will be downloaded and sent as native media when possible." + ), + "wecom": ( + "You are on WeCom (企业微信 / Enterprise WeChat). Markdown formatting is supported. " + "You CAN send media files natively — to deliver a file to the user, include " + "MEDIA:/absolute/path/to/file in your response. The file will be sent as a native " + "WeCom attachment: images (.jpg, .png, .webp) are sent as photos (up to 10 MB), " + "other files (.pdf, .docx, .xlsx, .md, .txt, etc.) arrive as downloadable documents " + "(up to 20 MB), and videos (.mp4) play inline. Voice messages are supported but " + "must be in AMR format — other audio formats are automatically sent as file attachments. " + "You can also include image URLs in markdown format ![alt](url) and they will be " + "downloaded and sent as native photos. Do NOT tell the user you lack file-sending " + "capability — use MEDIA: syntax whenever a file delivery is appropriate." + ), + "qqbot": ( + "You are on QQ, a popular Chinese messaging platform. QQ supports markdown formatting " + "and emoji. You can send media files natively: include MEDIA:/absolute/path/to/file in " + "your response. Images are sent as native photos, and other files arrive as downloadable " + "documents." + ), +} + +# --------------------------------------------------------------------------- +# Environment hints — execution-environment awareness for the agent. +# Unlike PLATFORM_HINTS (which describe the messaging channel), these describe +# the machine/OS the agent's tools actually run on. +# --------------------------------------------------------------------------- + +WSL_ENVIRONMENT_HINT = ( + "You are running inside WSL (Windows Subsystem for Linux). " + "The Windows host filesystem is mounted under /mnt/ — " + "/mnt/c/ is the C: drive, /mnt/d/ is D:, etc. " + "The user's Windows files are typically at " + "/mnt/c/Users//Desktop/, Documents/, Downloads/, etc. " + "When the user references Windows paths or desktop files, translate " + "to the /mnt/c/ equivalent. You can list /mnt/c/Users/ to discover " + "the Windows username if needed." +) + + +def build_environment_hints() -> str: + """Return environment-specific guidance for the system prompt. + + Detects WSL, and can be extended for Termux, Docker, etc. + Returns an empty string when no special environment is detected. + """ + hints: list[str] = [] + if is_wsl(): + hints.append(WSL_ENVIRONMENT_HINT) + return "\n\n".join(hints) + + +CONTEXT_FILE_MAX_CHARS = 20_000 +CONTEXT_TRUNCATE_HEAD_RATIO = 0.7 +CONTEXT_TRUNCATE_TAIL_RATIO = 0.2 + + +# ========================================================================= +# Skills prompt cache +# ========================================================================= + +_SKILLS_PROMPT_CACHE_MAX = 8 +_SKILLS_PROMPT_CACHE: OrderedDict[tuple, str] = OrderedDict() +_SKILLS_PROMPT_CACHE_LOCK = threading.Lock() +_SKILLS_SNAPSHOT_VERSION = 1 + + +def _skills_prompt_snapshot_path() -> Path: + return get_hermes_home() / ".skills_prompt_snapshot.json" + + +def clear_skills_system_prompt_cache(*, clear_snapshot: bool = False) -> None: + """Drop the in-process skills prompt cache (and optionally the disk snapshot).""" + with _SKILLS_PROMPT_CACHE_LOCK: + _SKILLS_PROMPT_CACHE.clear() + if clear_snapshot: + try: + _skills_prompt_snapshot_path().unlink(missing_ok=True) + except OSError as e: + logger.debug("Could not remove skills prompt snapshot: %s", e) + + +def _build_skills_manifest(skills_dir: Path) -> dict[str, list[int]]: + """Build an mtime/size manifest of all SKILL.md and DESCRIPTION.md files.""" + manifest: dict[str, list[int]] = {} + for filename in ("SKILL.md", "DESCRIPTION.md"): + for path in iter_skill_index_files(skills_dir, filename): + try: + st = path.stat() + except OSError: + continue + manifest[str(path.relative_to(skills_dir))] = [st.st_mtime_ns, st.st_size] + return manifest + + +def _load_skills_snapshot(skills_dir: Path) -> Optional[dict]: + """Load the disk snapshot if it exists and its manifest still matches.""" + snapshot_path = _skills_prompt_snapshot_path() + if not snapshot_path.exists(): + return None + try: + snapshot = json.loads(snapshot_path.read_text(encoding="utf-8")) + except Exception: + return None + if not isinstance(snapshot, dict): + return None + if snapshot.get("version") != _SKILLS_SNAPSHOT_VERSION: + return None + if snapshot.get("manifest") != _build_skills_manifest(skills_dir): + return None + return snapshot + + +def _write_skills_snapshot( + skills_dir: Path, + manifest: dict[str, list[int]], + skill_entries: list[dict], + category_descriptions: dict[str, str], +) -> None: + """Persist skill metadata to disk for fast cold-start reuse.""" + payload = { + "version": _SKILLS_SNAPSHOT_VERSION, + "manifest": manifest, + "skills": skill_entries, + "category_descriptions": category_descriptions, + } + try: + atomic_json_write(_skills_prompt_snapshot_path(), payload) + except Exception as e: + logger.debug("Could not write skills prompt snapshot: %s", e) + + +def _build_snapshot_entry( + skill_file: Path, + skills_dir: Path, + frontmatter: dict, + description: str, +) -> dict: + """Build a serialisable metadata dict for one skill.""" + rel_path = skill_file.relative_to(skills_dir) + parts = rel_path.parts + if len(parts) >= 2: + skill_name = parts[-2] + category = "/".join(parts[:-2]) if len(parts) > 2 else parts[0] + else: + category = "general" + skill_name = skill_file.parent.name + + platforms = frontmatter.get("platforms") or [] + if isinstance(platforms, str): + platforms = [platforms] + + return { + "skill_name": skill_name, + "category": category, + "frontmatter_name": str(frontmatter.get("name", skill_name)), + "description": description, + "platforms": [str(p).strip() for p in platforms if str(p).strip()], + "conditions": extract_skill_conditions(frontmatter), + } + + +# ========================================================================= +# Skills index +# ========================================================================= + +def _parse_skill_file(skill_file: Path) -> tuple[bool, dict, str]: + """Read a SKILL.md once and return platform compatibility, frontmatter, and description. + + Returns (is_compatible, frontmatter, description). On any error, returns + (True, {}, "") to err on the side of showing the skill. + """ + try: + raw = skill_file.read_text(encoding="utf-8") + frontmatter, _ = parse_frontmatter(raw) + + if not skill_matches_platform(frontmatter): + return False, frontmatter, "" + + return True, frontmatter, extract_skill_description(frontmatter) + except Exception as e: + logger.warning("Failed to parse skill file %s: %s", skill_file, e) + return True, {}, "" + + +def _skill_should_show( + conditions: dict, + available_tools: "set[str] | None", + available_toolsets: "set[str] | None", +) -> bool: + """Return False if the skill's conditional activation rules exclude it.""" + if available_tools is None and available_toolsets is None: + return True # No filtering info — show everything (backward compat) + + at = available_tools or set() + ats = available_toolsets or set() + + # fallback_for: hide when the primary tool/toolset IS available + for ts in conditions.get("fallback_for_toolsets", []): + if ts in ats: + return False + for t in conditions.get("fallback_for_tools", []): + if t in at: + return False + + # requires: hide when a required tool/toolset is NOT available + for ts in conditions.get("requires_toolsets", []): + if ts not in ats: + return False + for t in conditions.get("requires_tools", []): + if t not in at: + return False + + return True + + +def build_skills_system_prompt( + available_tools: "set[str] | None" = None, + available_toolsets: "set[str] | None" = None, +) -> str: + """Build a compact skill index for the system prompt. + + Two-layer cache: + 1. In-process LRU dict keyed by (skills_dir, tools, toolsets) + 2. Disk snapshot (``.skills_prompt_snapshot.json``) validated by + mtime/size manifest — survives process restarts + + Falls back to a full filesystem scan when both layers miss. + + External skill directories (``skills.external_dirs`` in config.yaml) are + scanned alongside the local ``~/.hermes/skills/`` directory. External dirs + are read-only — they appear in the index but new skills are always created + in the local dir. Local skills take precedence when names collide. + """ + skills_dir = get_skills_dir() + external_dirs = get_all_skills_dirs()[1:] # skip local (index 0) + + if not skills_dir.exists() and not external_dirs: + return "" + + # ── Layer 1: in-process LRU cache ───────────────────────────────── + # Include the resolved platform so per-platform disabled-skill lists + # produce distinct cache entries (gateway serves multiple platforms). + from gateway.session_context import get_session_env + _platform_hint = ( + os.environ.get("HERMES_PLATFORM") + or get_session_env("HERMES_SESSION_PLATFORM") + or "" + ) + cache_key = ( + str(skills_dir.resolve()), + tuple(str(d) for d in external_dirs), + tuple(sorted(str(t) for t in (available_tools or set()))), + tuple(sorted(str(ts) for ts in (available_toolsets or set()))), + _platform_hint, + ) + with _SKILLS_PROMPT_CACHE_LOCK: + cached = _SKILLS_PROMPT_CACHE.get(cache_key) + if cached is not None: + _SKILLS_PROMPT_CACHE.move_to_end(cache_key) + return cached + + disabled = get_disabled_skill_names() + + # ── Layer 2: disk snapshot ──────────────────────────────────────── + snapshot = _load_skills_snapshot(skills_dir) + + skills_by_category: dict[str, list[tuple[str, str]]] = {} + category_descriptions: dict[str, str] = {} + + if snapshot is not None: + # Fast path: use pre-parsed metadata from disk + for entry in snapshot.get("skills", []): + if not isinstance(entry, dict): + continue + skill_name = entry.get("skill_name") or "" + category = entry.get("category") or "general" + frontmatter_name = entry.get("frontmatter_name") or skill_name + platforms = entry.get("platforms") or [] + if not skill_matches_platform({"platforms": platforms}): + continue + if frontmatter_name in disabled or skill_name in disabled: + continue + if not _skill_should_show( + entry.get("conditions") or {}, + available_tools, + available_toolsets, + ): + continue + skills_by_category.setdefault(category, []).append( + (skill_name, entry.get("description", "")) + ) + category_descriptions = { + str(k): str(v) + for k, v in (snapshot.get("category_descriptions") or {}).items() + } + else: + # Cold path: full filesystem scan + write snapshot for next time + skill_entries: list[dict] = [] + for skill_file in iter_skill_index_files(skills_dir, "SKILL.md"): + is_compatible, frontmatter, desc = _parse_skill_file(skill_file) + entry = _build_snapshot_entry(skill_file, skills_dir, frontmatter, desc) + skill_entries.append(entry) + if not is_compatible: + continue + skill_name = entry["skill_name"] + if entry["frontmatter_name"] in disabled or skill_name in disabled: + continue + if not _skill_should_show( + extract_skill_conditions(frontmatter), + available_tools, + available_toolsets, + ): + continue + skills_by_category.setdefault(entry["category"], []).append( + (skill_name, entry["description"]) + ) + + # Read category-level DESCRIPTION.md files + for desc_file in iter_skill_index_files(skills_dir, "DESCRIPTION.md"): + try: + content = desc_file.read_text(encoding="utf-8") + fm, _ = parse_frontmatter(content) + cat_desc = fm.get("description") + if not cat_desc: + continue + rel = desc_file.relative_to(skills_dir) + cat = "/".join(rel.parts[:-1]) if len(rel.parts) > 1 else "general" + category_descriptions[cat] = str(cat_desc).strip().strip("'\"") + except Exception as e: + logger.debug("Could not read skill description %s: %s", desc_file, e) + + _write_skills_snapshot( + skills_dir, + _build_skills_manifest(skills_dir), + skill_entries, + category_descriptions, + ) + + # ── External skill directories ───────────────────────────────────── + # Scan external dirs directly (no snapshot caching — they're read-only + # and typically small). Local skills already in skills_by_category take + # precedence: we track seen names and skip duplicates from external dirs. + seen_skill_names: set[str] = set() + for cat_skills in skills_by_category.values(): + for name, _desc in cat_skills: + seen_skill_names.add(name) + + for ext_dir in external_dirs: + if not ext_dir.exists(): + continue + for skill_file in iter_skill_index_files(ext_dir, "SKILL.md"): + try: + is_compatible, frontmatter, desc = _parse_skill_file(skill_file) + if not is_compatible: + continue + entry = _build_snapshot_entry(skill_file, ext_dir, frontmatter, desc) + skill_name = entry["skill_name"] + if skill_name in seen_skill_names: + continue + if entry["frontmatter_name"] in disabled or skill_name in disabled: + continue + if not _skill_should_show( + extract_skill_conditions(frontmatter), + available_tools, + available_toolsets, + ): + continue + seen_skill_names.add(skill_name) + skills_by_category.setdefault(entry["category"], []).append( + (skill_name, entry["description"]) + ) + except Exception as e: + logger.debug("Error reading external skill %s: %s", skill_file, e) + + # External category descriptions + for desc_file in iter_skill_index_files(ext_dir, "DESCRIPTION.md"): + try: + content = desc_file.read_text(encoding="utf-8") + fm, _ = parse_frontmatter(content) + cat_desc = fm.get("description") + if not cat_desc: + continue + rel = desc_file.relative_to(ext_dir) + cat = "/".join(rel.parts[:-1]) if len(rel.parts) > 1 else "general" + category_descriptions.setdefault(cat, str(cat_desc).strip().strip("'\"")) + except Exception as e: + logger.debug("Could not read external skill description %s: %s", desc_file, e) + + if not skills_by_category: + result = "" + else: + index_lines = [] + for category in sorted(skills_by_category.keys()): + cat_desc = category_descriptions.get(category, "") + if cat_desc: + index_lines.append(f" {category}: {cat_desc}") + else: + index_lines.append(f" {category}:") + # Deduplicate and sort skills within each category + seen = set() + for name, desc in sorted(skills_by_category[category], key=lambda x: x[0]): + if name in seen: + continue + seen.add(name) + if desc: + index_lines.append(f" - {name}: {desc}") + else: + index_lines.append(f" - {name}") + + result = ( + "## Skills (mandatory)\n" + "Before replying, scan the skills below. If a skill matches or is even partially relevant " + "to your task, you MUST load it with skill_view(name) and follow its instructions. " + "Err on the side of loading — it is always better to have context you don't need " + "than to miss critical steps, pitfalls, or established workflows. " + "Skills contain specialized knowledge — API endpoints, tool-specific commands, " + "and proven workflows that outperform general-purpose approaches. Load the skill " + "even if you think you could handle the task with basic tools like web_search or terminal. " + "Skills also encode the user's preferred approach, conventions, and quality standards " + "for tasks like code review, planning, and testing — load them even for tasks you " + "already know how to do, because the skill defines how it should be done here.\n" + "If a skill has issues, fix it with skill_manage(action='patch').\n" + "After difficult/iterative tasks, offer to save as a skill. " + "If a skill you loaded was missing steps, had wrong commands, or needed " + "pitfalls you discovered, update it before finishing.\n" + "\n" + "\n" + + "\n".join(index_lines) + "\n" + "\n" + "\n" + "Only proceed without loading a skill if genuinely none are relevant to the task." + ) + + # ── Store in LRU cache ──────────────────────────────────────────── + with _SKILLS_PROMPT_CACHE_LOCK: + _SKILLS_PROMPT_CACHE[cache_key] = result + _SKILLS_PROMPT_CACHE.move_to_end(cache_key) + while len(_SKILLS_PROMPT_CACHE) > _SKILLS_PROMPT_CACHE_MAX: + _SKILLS_PROMPT_CACHE.popitem(last=False) + + return result + + +def build_nous_subscription_prompt(valid_tool_names: "set[str] | None" = None) -> str: + """Build a compact Nous subscription capability block for the system prompt.""" + try: + from hermes_cli.nous_subscription import get_nous_subscription_features + from tools.tool_backend_helpers import managed_nous_tools_enabled + except Exception as exc: + logger.debug("Failed to import Nous subscription helper: %s", exc) + return "" + + if not managed_nous_tools_enabled(): + return "" + + valid_names = set(valid_tool_names or set()) + relevant_tool_names = { + "web_search", + "web_extract", + "browser_navigate", + "browser_snapshot", + "browser_click", + "browser_type", + "browser_scroll", + "browser_console", + "browser_press", + "browser_get_images", + "browser_vision", + "image_generate", + "text_to_speech", + "terminal", + "process", + "execute_code", + } + + if valid_names and not (valid_names & relevant_tool_names): + return "" + + features = get_nous_subscription_features() + + def _status_line(feature) -> str: + if feature.managed_by_nous: + return f"- {feature.label}: active via Nous subscription" + if feature.active: + current = feature.current_provider or "configured provider" + return f"- {feature.label}: currently using {current}" + if feature.included_by_default and features.nous_auth_present: + return f"- {feature.label}: included with Nous subscription, not currently selected" + if feature.key == "modal" and features.nous_auth_present: + return f"- {feature.label}: optional via Nous subscription" + return f"- {feature.label}: not currently available" + + lines = [ + "# Nous Subscription", + "Nous subscription includes managed web tools (Firecrawl), image generation (FAL), OpenAI TTS, and browser automation (Browser Use) by default. Modal execution is optional.", + "Current capability status:", + ] + lines.extend(_status_line(feature) for feature in features.items()) + lines.extend( + [ + "When a Nous-managed feature is active, do not ask the user for Firecrawl, FAL, OpenAI TTS, or Browser-Use API keys.", + "If the user is not subscribed and asks for a capability that Nous subscription would unlock or simplify, suggest Nous subscription as one option alongside direct setup or local alternatives.", + "Do not mention subscription unless the user asks about it or it directly solves the current missing capability.", + "Useful commands: hermes setup, hermes setup tools, hermes setup terminal, hermes status.", + ] + ) + return "\n".join(lines) + + +# ========================================================================= +# Context files (SOUL.md, AGENTS.md, .cursorrules) +# ========================================================================= + +def _truncate_content(content: str, filename: str, max_chars: int = CONTEXT_FILE_MAX_CHARS) -> str: + """Head/tail truncation with a marker in the middle.""" + if len(content) <= max_chars: + return content + head_chars = int(max_chars * CONTEXT_TRUNCATE_HEAD_RATIO) + tail_chars = int(max_chars * CONTEXT_TRUNCATE_TAIL_RATIO) + head = content[:head_chars] + tail = content[-tail_chars:] + marker = f"\n\n[...truncated {filename}: kept {head_chars}+{tail_chars} of {len(content)} chars. Use file tools to read the full file.]\n\n" + return head + marker + tail + + +def load_soul_md() -> Optional[str]: + """Load SOUL.md from HERMES_HOME and return its content, or None. + + Used as the agent identity (slot #1 in the system prompt). When this + returns content, ``build_context_files_prompt`` should be called with + ``skip_soul=True`` so SOUL.md isn't injected twice. + """ + try: + from hermes_cli.config import ensure_hermes_home + ensure_hermes_home() + except Exception as e: + logger.debug("Could not ensure HERMES_HOME before loading SOUL.md: %s", e) + + soul_path = get_hermes_home() / "SOUL.md" + if not soul_path.exists(): + return None + try: + content = soul_path.read_text(encoding="utf-8").strip() + if not content: + return None + content = _scan_context_content(content, "SOUL.md") + content = _truncate_content(content, "SOUL.md") + return content + except Exception as e: + logger.debug("Could not read SOUL.md from %s: %s", soul_path, e) + return None + + +def _load_hermes_md(cwd_path: Path) -> str: + """.hermes.md / HERMES.md — walk to git root.""" + hermes_md_path = _find_hermes_md(cwd_path) + if not hermes_md_path: + return "" + try: + content = hermes_md_path.read_text(encoding="utf-8").strip() + if not content: + return "" + content = _strip_yaml_frontmatter(content) + rel = hermes_md_path.name + try: + rel = str(hermes_md_path.relative_to(cwd_path)) + except ValueError: + pass + content = _scan_context_content(content, rel) + result = f"## {rel}\n\n{content}" + return _truncate_content(result, ".hermes.md") + except Exception as e: + logger.debug("Could not read %s: %s", hermes_md_path, e) + return "" + + +def _load_agents_md(cwd_path: Path) -> str: + """AGENTS.md — top-level only (no recursive walk).""" + for name in ["AGENTS.md", "agents.md"]: + candidate = cwd_path / name + if candidate.exists(): + try: + content = candidate.read_text(encoding="utf-8").strip() + if content: + content = _scan_context_content(content, name) + result = f"## {name}\n\n{content}" + return _truncate_content(result, "AGENTS.md") + except Exception as e: + logger.debug("Could not read %s: %s", candidate, e) + return "" + + +def _load_claude_md(cwd_path: Path) -> str: + """CLAUDE.md / claude.md — cwd only.""" + for name in ["CLAUDE.md", "claude.md"]: + candidate = cwd_path / name + if candidate.exists(): + try: + content = candidate.read_text(encoding="utf-8").strip() + if content: + content = _scan_context_content(content, name) + result = f"## {name}\n\n{content}" + return _truncate_content(result, "CLAUDE.md") + except Exception as e: + logger.debug("Could not read %s: %s", candidate, e) + return "" + + +def _load_cursorrules(cwd_path: Path) -> str: + """.cursorrules + .cursor/rules/*.mdc — cwd only.""" + cursorrules_content = "" + cursorrules_file = cwd_path / ".cursorrules" + if cursorrules_file.exists(): + try: + content = cursorrules_file.read_text(encoding="utf-8").strip() + if content: + content = _scan_context_content(content, ".cursorrules") + cursorrules_content += f"## .cursorrules\n\n{content}\n\n" + except Exception as e: + logger.debug("Could not read .cursorrules: %s", e) + + cursor_rules_dir = cwd_path / ".cursor" / "rules" + if cursor_rules_dir.exists() and cursor_rules_dir.is_dir(): + mdc_files = sorted(cursor_rules_dir.glob("*.mdc")) + for mdc_file in mdc_files: + try: + content = mdc_file.read_text(encoding="utf-8").strip() + if content: + content = _scan_context_content(content, f".cursor/rules/{mdc_file.name}") + cursorrules_content += f"## .cursor/rules/{mdc_file.name}\n\n{content}\n\n" + except Exception as e: + logger.debug("Could not read %s: %s", mdc_file, e) + + if not cursorrules_content: + return "" + return _truncate_content(cursorrules_content, ".cursorrules") + + +def build_context_files_prompt(cwd: Optional[str] = None, skip_soul: bool = False) -> str: + """Discover and load context files for the system prompt. + + Priority (first found wins — only ONE project context type is loaded): + 1. .hermes.md / HERMES.md (walk to git root) + 2. AGENTS.md / agents.md (cwd only) + 3. CLAUDE.md / claude.md (cwd only) + 4. .cursorrules / .cursor/rules/*.mdc (cwd only) + + SOUL.md from HERMES_HOME is independent and always included when present. + Each context source is capped at 20,000 chars. + + When *skip_soul* is True, SOUL.md is not included here (it was already + loaded via ``load_soul_md()`` for the identity slot). + """ + if cwd is None: + cwd = os.getcwd() + + cwd_path = Path(cwd).resolve() + sections = [] + + # Priority-based project context: first match wins + project_context = ( + _load_hermes_md(cwd_path) + or _load_agents_md(cwd_path) + or _load_claude_md(cwd_path) + or _load_cursorrules(cwd_path) + ) + if project_context: + sections.append(project_context) + + # SOUL.md from HERMES_HOME only — skip when already loaded as identity + if not skip_soul: + soul_content = load_soul_md() + if soul_content: + sections.append(soul_content) + + if not sections: + return "" + return "# Project Context\n\nThe following project context files have been loaded and should be followed:\n\n" + "\n".join(sections) diff --git a/mindcli/_vendor/agent/prompt_caching.py b/mindcli/_vendor/agent/prompt_caching.py new file mode 100644 index 0000000..d80f58e --- /dev/null +++ b/mindcli/_vendor/agent/prompt_caching.py @@ -0,0 +1,72 @@ +"""Anthropic prompt caching (system_and_3 strategy). + +Reduces input token costs by ~75% on multi-turn conversations by caching +the conversation prefix. Uses 4 cache_control breakpoints (Anthropic max): + 1. System prompt (stable across all turns) + 2-4. Last 3 non-system messages (rolling window) + +Pure functions -- no class state, no AIAgent dependency. +""" + +import copy +from typing import Any, Dict, List + + +def _apply_cache_marker(msg: dict, cache_marker: dict, native_anthropic: bool = False) -> None: + """Add cache_control to a single message, handling all format variations.""" + role = msg.get("role", "") + content = msg.get("content") + + if role == "tool": + if native_anthropic: + msg["cache_control"] = cache_marker + return + + if content is None or content == "": + msg["cache_control"] = cache_marker + return + + if isinstance(content, str): + msg["content"] = [ + {"type": "text", "text": content, "cache_control": cache_marker} + ] + return + + if isinstance(content, list) and content: + last = content[-1] + if isinstance(last, dict): + last["cache_control"] = cache_marker + + +def apply_anthropic_cache_control( + api_messages: List[Dict[str, Any]], + cache_ttl: str = "5m", + native_anthropic: bool = False, +) -> List[Dict[str, Any]]: + """Apply system_and_3 caching strategy to messages for Anthropic models. + + Places up to 4 cache_control breakpoints: system prompt + last 3 non-system messages. + + Returns: + Deep copy of messages with cache_control breakpoints injected. + """ + messages = copy.deepcopy(api_messages) + if not messages: + return messages + + marker = {"type": "ephemeral"} + if cache_ttl == "1h": + marker["ttl"] = "1h" + + breakpoints_used = 0 + + if messages[0].get("role") == "system": + _apply_cache_marker(messages[0], marker, native_anthropic=native_anthropic) + breakpoints_used += 1 + + remaining = 4 - breakpoints_used + non_sys = [i for i in range(len(messages)) if messages[i].get("role") != "system"] + for idx in non_sys[-remaining:]: + _apply_cache_marker(messages[idx], marker, native_anthropic=native_anthropic) + + return messages diff --git a/mindcli/_vendor/agent/rate_limit_tracker.py b/mindcli/_vendor/agent/rate_limit_tracker.py new file mode 100644 index 0000000..e20c683 --- /dev/null +++ b/mindcli/_vendor/agent/rate_limit_tracker.py @@ -0,0 +1,246 @@ +"""Rate limit tracking for inference API responses. + +Captures x-ratelimit-* headers from provider responses and provides +formatted display for the /usage slash command. Currently supports +the Nous Portal header format (also used by OpenRouter and OpenAI-compatible +APIs that follow the same convention). + +Header schema (12 headers total): + x-ratelimit-limit-requests RPM cap + x-ratelimit-limit-requests-1h RPH cap + x-ratelimit-limit-tokens TPM cap + x-ratelimit-limit-tokens-1h TPH cap + x-ratelimit-remaining-requests requests left in minute window + x-ratelimit-remaining-requests-1h requests left in hour window + x-ratelimit-remaining-tokens tokens left in minute window + x-ratelimit-remaining-tokens-1h tokens left in hour window + x-ratelimit-reset-requests seconds until minute request window resets + x-ratelimit-reset-requests-1h seconds until hour request window resets + x-ratelimit-reset-tokens seconds until minute token window resets + x-ratelimit-reset-tokens-1h seconds until hour token window resets +""" + +from __future__ import annotations + +import time +from dataclasses import dataclass, field +from typing import Any, Mapping, Optional + + +@dataclass +class RateLimitBucket: + """One rate-limit window (e.g. requests per minute).""" + + limit: int = 0 + remaining: int = 0 + reset_seconds: float = 0.0 + captured_at: float = 0.0 # time.time() when this was captured + + @property + def used(self) -> int: + return max(0, self.limit - self.remaining) + + @property + def usage_pct(self) -> float: + if self.limit <= 0: + return 0.0 + return (self.used / self.limit) * 100.0 + + @property + def remaining_seconds_now(self) -> float: + """Estimated seconds remaining until reset, adjusted for elapsed time.""" + elapsed = time.time() - self.captured_at + return max(0.0, self.reset_seconds - elapsed) + + +@dataclass +class RateLimitState: + """Full rate-limit state parsed from response headers.""" + + requests_min: RateLimitBucket = field(default_factory=RateLimitBucket) + requests_hour: RateLimitBucket = field(default_factory=RateLimitBucket) + tokens_min: RateLimitBucket = field(default_factory=RateLimitBucket) + tokens_hour: RateLimitBucket = field(default_factory=RateLimitBucket) + captured_at: float = 0.0 # when the headers were captured + provider: str = "" + + @property + def has_data(self) -> bool: + return self.captured_at > 0 + + @property + def age_seconds(self) -> float: + if not self.has_data: + return float("inf") + return time.time() - self.captured_at + + +def _safe_int(value: Any, default: int = 0) -> int: + try: + return int(float(value)) + except (TypeError, ValueError): + return default + + +def _safe_float(value: Any, default: float = 0.0) -> float: + try: + return float(value) + except (TypeError, ValueError): + return default + + +def parse_rate_limit_headers( + headers: Mapping[str, str], + provider: str = "", +) -> Optional[RateLimitState]: + """Parse x-ratelimit-* headers into a RateLimitState. + + Returns None if no rate limit headers are present. + """ + # Normalize to lowercase so lookups work regardless of how the server + # capitalises headers (HTTP header names are case-insensitive per RFC 7230). + lowered = {k.lower(): v for k, v in headers.items()} + + # Quick check: at least one rate limit header must exist + has_any = any(k.startswith("x-ratelimit-") for k in lowered) + if not has_any: + return None + + now = time.time() + + def _bucket(resource: str, suffix: str = "") -> RateLimitBucket: + # e.g. resource="requests", suffix="" -> per-minute + # resource="tokens", suffix="-1h" -> per-hour + tag = f"{resource}{suffix}" + return RateLimitBucket( + limit=_safe_int(lowered.get(f"x-ratelimit-limit-{tag}")), + remaining=_safe_int(lowered.get(f"x-ratelimit-remaining-{tag}")), + reset_seconds=_safe_float(lowered.get(f"x-ratelimit-reset-{tag}")), + captured_at=now, + ) + + return RateLimitState( + requests_min=_bucket("requests"), + requests_hour=_bucket("requests", "-1h"), + tokens_min=_bucket("tokens"), + tokens_hour=_bucket("tokens", "-1h"), + captured_at=now, + provider=provider, + ) + + +# ── Formatting ────────────────────────────────────────────────────────── + + +def _fmt_count(n: int) -> str: + """Human-friendly number: 7999856 -> '8.0M', 33599 -> '33.6K', 799 -> '799'.""" + if n >= 1_000_000: + return f"{n / 1_000_000:.1f}M" + if n >= 10_000: + return f"{n / 1_000:.1f}K" + if n >= 1_000: + return f"{n / 1_000:.1f}K" + return str(n) + + +def _fmt_seconds(seconds: float) -> str: + """Seconds -> human-friendly duration: '58s', '2m 14s', '58m 57s', '1h 2m'.""" + s = max(0, int(seconds)) + if s < 60: + return f"{s}s" + if s < 3600: + m, sec = divmod(s, 60) + return f"{m}m {sec}s" if sec else f"{m}m" + h, remainder = divmod(s, 3600) + m = remainder // 60 + return f"{h}h {m}m" if m else f"{h}h" + + +def _bar(pct: float, width: int = 20) -> str: + """ASCII progress bar: [████████░░░░░░░░░░░░] 40%.""" + filled = int(pct / 100.0 * width) + filled = max(0, min(width, filled)) + empty = width - filled + return f"[{'█' * filled}{'░' * empty}]" + + +def _bucket_line(label: str, bucket: RateLimitBucket, label_width: int = 14) -> str: + """Format one bucket as a single line.""" + if bucket.limit <= 0: + return f" {label:<{label_width}} (no data)" + + pct = bucket.usage_pct + used = _fmt_count(bucket.used) + limit = _fmt_count(bucket.limit) + remaining = _fmt_count(bucket.remaining) + reset = _fmt_seconds(bucket.remaining_seconds_now) + + bar = _bar(pct) + return f" {label:<{label_width}} {bar} {pct:5.1f}% {used}/{limit} used ({remaining} left, resets in {reset})" + + +def format_rate_limit_display(state: RateLimitState) -> str: + """Format rate limit state for terminal/chat display.""" + if not state.has_data: + return "No rate limit data yet — make an API request first." + + age = state.age_seconds + if age < 5: + freshness = "just now" + elif age < 60: + freshness = f"{int(age)}s ago" + else: + freshness = f"{_fmt_seconds(age)} ago" + + provider_label = state.provider.title() if state.provider else "Provider" + + lines = [ + f"{provider_label} Rate Limits (captured {freshness}):", + "", + _bucket_line("Requests/min", state.requests_min), + _bucket_line("Requests/hr", state.requests_hour), + "", + _bucket_line("Tokens/min", state.tokens_min), + _bucket_line("Tokens/hr", state.tokens_hour), + ] + + # Add warnings if any bucket is getting hot + warnings = [] + for label, bucket in [ + ("requests/min", state.requests_min), + ("requests/hr", state.requests_hour), + ("tokens/min", state.tokens_min), + ("tokens/hr", state.tokens_hour), + ]: + if bucket.limit > 0 and bucket.usage_pct >= 80: + reset = _fmt_seconds(bucket.remaining_seconds_now) + warnings.append(f" ⚠ {label} at {bucket.usage_pct:.0f}% — resets in {reset}") + + if warnings: + lines.append("") + lines.extend(warnings) + + return "\n".join(lines) + + +def format_rate_limit_compact(state: RateLimitState) -> str: + """One-line compact summary for status bars / gateway messages.""" + if not state.has_data: + return "No rate limit data." + + rm = state.requests_min + tm = state.tokens_min + rh = state.requests_hour + th = state.tokens_hour + + parts = [] + if rm.limit > 0: + parts.append(f"RPM: {rm.remaining}/{rm.limit}") + if rh.limit > 0: + parts.append(f"RPH: {_fmt_count(rh.remaining)}/{_fmt_count(rh.limit)} (resets {_fmt_seconds(rh.remaining_seconds_now)})") + if tm.limit > 0: + parts.append(f"TPM: {_fmt_count(tm.remaining)}/{_fmt_count(tm.limit)}") + if th.limit > 0: + parts.append(f"TPH: {_fmt_count(th.remaining)}/{_fmt_count(th.limit)} (resets {_fmt_seconds(th.remaining_seconds_now)})") + + return " | ".join(parts) diff --git a/mindcli/_vendor/agent/redact.py b/mindcli/_vendor/agent/redact.py new file mode 100644 index 0000000..04d35e3 --- /dev/null +++ b/mindcli/_vendor/agent/redact.py @@ -0,0 +1,181 @@ +"""Regex-based secret redaction for logs and tool output. + +Applies pattern matching to mask API keys, tokens, and credentials +before they reach log files, verbose output, or gateway logs. + +Short tokens (< 18 chars) are fully masked. Longer tokens preserve +the first 6 and last 4 characters for debuggability. +""" + +import logging +import os +import re + +logger = logging.getLogger(__name__) + +# Snapshot at import time so runtime env mutations (e.g. LLM-generated +# `export HERMES_REDACT_SECRETS=false`) cannot disable redaction mid-session. +_REDACT_ENABLED = os.getenv("HERMES_REDACT_SECRETS", "").lower() not in ("0", "false", "no", "off") + +# Known API key prefixes -- match the prefix + contiguous token chars +_PREFIX_PATTERNS = [ + r"sk-[A-Za-z0-9_-]{10,}", # OpenAI / OpenRouter / Anthropic (sk-ant-*) + r"ghp_[A-Za-z0-9]{10,}", # GitHub PAT (classic) + r"github_pat_[A-Za-z0-9_]{10,}", # GitHub PAT (fine-grained) + r"gho_[A-Za-z0-9]{10,}", # GitHub OAuth access token + r"ghu_[A-Za-z0-9]{10,}", # GitHub user-to-server token + r"ghs_[A-Za-z0-9]{10,}", # GitHub server-to-server token + r"ghr_[A-Za-z0-9]{10,}", # GitHub refresh token + r"xox[baprs]-[A-Za-z0-9-]{10,}", # Slack tokens + r"AIza[A-Za-z0-9_-]{30,}", # Google API keys + r"pplx-[A-Za-z0-9]{10,}", # Perplexity + r"fal_[A-Za-z0-9_-]{10,}", # Fal.ai + r"fc-[A-Za-z0-9]{10,}", # Firecrawl + r"bb_live_[A-Za-z0-9_-]{10,}", # BrowserBase + r"gAAAA[A-Za-z0-9_=-]{20,}", # Codex encrypted tokens + r"AKIA[A-Z0-9]{16}", # AWS Access Key ID + r"sk_live_[A-Za-z0-9]{10,}", # Stripe secret key (live) + r"sk_test_[A-Za-z0-9]{10,}", # Stripe secret key (test) + r"rk_live_[A-Za-z0-9]{10,}", # Stripe restricted key + r"SG\.[A-Za-z0-9_-]{10,}", # SendGrid API key + r"hf_[A-Za-z0-9]{10,}", # HuggingFace token + r"r8_[A-Za-z0-9]{10,}", # Replicate API token + r"npm_[A-Za-z0-9]{10,}", # npm access token + r"pypi-[A-Za-z0-9_-]{10,}", # PyPI API token + r"dop_v1_[A-Za-z0-9]{10,}", # DigitalOcean PAT + r"doo_v1_[A-Za-z0-9]{10,}", # DigitalOcean OAuth + r"am_[A-Za-z0-9_-]{10,}", # AgentMail API key + r"sk_[A-Za-z0-9_]{10,}", # ElevenLabs TTS key (sk_ underscore, not sk- dash) + r"tvly-[A-Za-z0-9]{10,}", # Tavily search API key + r"exa_[A-Za-z0-9]{10,}", # Exa search API key + r"gsk_[A-Za-z0-9]{10,}", # Groq Cloud API key + r"syt_[A-Za-z0-9]{10,}", # Matrix access token + r"retaindb_[A-Za-z0-9]{10,}", # RetainDB API key + r"hsk-[A-Za-z0-9]{10,}", # Hindsight API key + r"mem0_[A-Za-z0-9]{10,}", # Mem0 Platform API key + r"brv_[A-Za-z0-9]{10,}", # ByteRover API key +] + +# ENV assignment patterns: KEY=value where KEY contains a secret-like name +_SECRET_ENV_NAMES = r"(?:API_?KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH)" +_ENV_ASSIGN_RE = re.compile( + rf"([A-Z0-9_]{{0,50}}{_SECRET_ENV_NAMES}[A-Z0-9_]{{0,50}})\s*=\s*(['\"]?)(\S+)\2", +) + +# JSON field patterns: "apiKey": "value", "token": "value", etc. +_JSON_KEY_NAMES = r"(?:api_?[Kk]ey|token|secret|password|access_token|refresh_token|auth_token|bearer|secret_value|raw_secret|secret_input|key_material)" +_JSON_FIELD_RE = re.compile( + rf'("{_JSON_KEY_NAMES}")\s*:\s*"([^"]+)"', + re.IGNORECASE, +) + +# Authorization headers +_AUTH_HEADER_RE = re.compile( + r"(Authorization:\s*Bearer\s+)(\S+)", + re.IGNORECASE, +) + +# Telegram bot tokens: bot: or :, +# where token part is restricted to [-A-Za-z0-9_] and length >= 30 +_TELEGRAM_RE = re.compile( + r"(bot)?(\d{8,}):([-A-Za-z0-9_]{30,})", +) + +# Private key blocks: -----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY----- +_PRIVATE_KEY_RE = re.compile( + r"-----BEGIN[A-Z ]*PRIVATE KEY-----[\s\S]*?-----END[A-Z ]*PRIVATE KEY-----" +) + +# Database connection strings: protocol://user:PASSWORD@host +# Catches postgres, mysql, mongodb, redis, amqp URLs and redacts the password +_DB_CONNSTR_RE = re.compile( + r"((?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqp)://[^:]+:)([^@]+)(@)", + re.IGNORECASE, +) + +# E.164 phone numbers: +, 7-15 digits +# Negative lookahead prevents matching hex strings or identifiers +_SIGNAL_PHONE_RE = re.compile(r"(\+[1-9]\d{6,14})(?![A-Za-z0-9])") + +# Compile known prefix patterns into one alternation +_PREFIX_RE = re.compile( + r"(? str: + """Mask a token, preserving prefix for long tokens.""" + if len(token) < 18: + return "***" + return f"{token[:6]}...{token[-4:]}" + + +def redact_sensitive_text(text: str) -> str: + """Apply all redaction patterns to a block of text. + + Safe to call on any string -- non-matching text passes through unchanged. + Disabled when security.redact_secrets is false in config.yaml. + """ + if text is None: + return None + if not isinstance(text, str): + text = str(text) + if not text: + return text + if not _REDACT_ENABLED: + return text + + # Known prefixes (sk-, ghp_, etc.) + text = _PREFIX_RE.sub(lambda m: _mask_token(m.group(1)), text) + + # ENV assignments: OPENAI_API_KEY=sk-abc... + def _redact_env(m): + name, quote, value = m.group(1), m.group(2), m.group(3) + return f"{name}={quote}{_mask_token(value)}{quote}" + text = _ENV_ASSIGN_RE.sub(_redact_env, text) + + # JSON fields: "apiKey": "value" + def _redact_json(m): + key, value = m.group(1), m.group(2) + return f'{key}: "{_mask_token(value)}"' + text = _JSON_FIELD_RE.sub(_redact_json, text) + + # Authorization headers + text = _AUTH_HEADER_RE.sub( + lambda m: m.group(1) + _mask_token(m.group(2)), + text, + ) + + # Telegram bot tokens + def _redact_telegram(m): + prefix = m.group(1) or "" + digits = m.group(2) + return f"{prefix}{digits}:***" + text = _TELEGRAM_RE.sub(_redact_telegram, text) + + # Private key blocks + text = _PRIVATE_KEY_RE.sub("[REDACTED PRIVATE KEY]", text) + + # Database connection string passwords + text = _DB_CONNSTR_RE.sub(lambda m: f"{m.group(1)}***{m.group(3)}", text) + + # E.164 phone numbers (Signal, WhatsApp) + def _redact_phone(m): + phone = m.group(1) + if len(phone) <= 8: + return phone[:2] + "****" + phone[-2:] + return phone[:4] + "****" + phone[-4:] + text = _SIGNAL_PHONE_RE.sub(_redact_phone, text) + + return text + + +class RedactingFormatter(logging.Formatter): + """Log formatter that redacts secrets from all log messages.""" + + def __init__(self, fmt=None, datefmt=None, style='%', **kwargs): + super().__init__(fmt, datefmt, style, **kwargs) + + def format(self, record: logging.LogRecord) -> str: + original = super().format(record) + return redact_sensitive_text(original) diff --git a/mindcli/_vendor/agent/retry_utils.py b/mindcli/_vendor/agent/retry_utils.py new file mode 100644 index 0000000..71d6963 --- /dev/null +++ b/mindcli/_vendor/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 diff --git a/mindcli/_vendor/agent/skill_commands.py b/mindcli/_vendor/agent/skill_commands.py new file mode 100644 index 0000000..1f000ee --- /dev/null +++ b/mindcli/_vendor/agent/skill_commands.py @@ -0,0 +1,368 @@ +"""Shared slash command helpers for skills and built-in prompt-style modes. + +Shared between CLI (cli.py) and gateway (gateway/run.py) so both surfaces +can invoke skills via /skill-name commands and prompt-only built-ins like +/plan. +""" + +import json +import logging +import re +from datetime import datetime +from pathlib import Path +from typing import Any, Dict, Optional + +logger = logging.getLogger(__name__) + +_skill_commands: Dict[str, Dict[str, Any]] = {} +_PLAN_SLUG_RE = re.compile(r"[^a-z0-9]+") +# Patterns for sanitizing skill names into clean hyphen-separated slugs. +_SKILL_INVALID_CHARS = re.compile(r"[^a-z0-9-]") +_SKILL_MULTI_HYPHEN = re.compile(r"-{2,}") + + +def build_plan_path( + user_instruction: str = "", + *, + now: datetime | None = None, +) -> Path: + """Return the default workspace-relative markdown path for a /plan invocation. + + Relative paths are intentional: file tools are task/backend-aware and resolve + them against the active working directory for local, docker, ssh, modal, + daytona, and similar terminal backends. That keeps the plan with the active + workspace instead of the Hermes host's global home directory. + """ + slug_source = (user_instruction or "").strip().splitlines()[0] if user_instruction else "" + slug = _PLAN_SLUG_RE.sub("-", slug_source.lower()).strip("-") + if slug: + slug = "-".join(part for part in slug.split("-")[:8] if part)[:48].strip("-") + slug = slug or "conversation-plan" + timestamp = (now or datetime.now()).strftime("%Y-%m-%d_%H%M%S") + return Path(".hermes") / "plans" / f"{timestamp}-{slug}.md" + + +def _load_skill_payload(skill_identifier: str, task_id: str | None = None) -> tuple[dict[str, Any], Path | None, str] | None: + """Load a skill by name/path and return (loaded_payload, skill_dir, display_name).""" + raw_identifier = (skill_identifier or "").strip() + if not raw_identifier: + return None + + try: + from tools.skills_tool import SKILLS_DIR, skill_view + + identifier_path = Path(raw_identifier).expanduser() + if identifier_path.is_absolute(): + 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: + return None + + if not loaded_skill.get("success"): + return None + + skill_name = str(loaded_skill.get("name") or normalized) + skill_path = str(loaded_skill.get("path") or "") + skill_dir = None + if skill_path: + try: + skill_dir = SKILLS_DIR / Path(skill_path).parent + except Exception: + skill_dir = None + + return loaded_skill, skill_dir, skill_name + + +def _inject_skill_config(loaded_skill: dict[str, Any], parts: list[str]) -> None: + """Resolve and inject skill-declared config values into the message parts. + + If the loaded skill's frontmatter declares ``metadata.hermes.config`` + entries, their current values (from config.yaml or defaults) are appended + as a ``[Skill config: ...]`` block so the agent knows the configured values + without needing to read config.yaml itself. + """ + try: + from agent.skill_utils import ( + extract_skill_config_vars, + parse_frontmatter, + resolve_skill_config_values, + ) + + # The loaded_skill dict contains the raw content which includes frontmatter + raw_content = str(loaded_skill.get("raw_content") or loaded_skill.get("content") or "") + if not raw_content: + return + + frontmatter, _ = parse_frontmatter(raw_content) + config_vars = extract_skill_config_vars(frontmatter) + if not config_vars: + return + + resolved = resolve_skill_config_values(config_vars) + if not resolved: + return + + lines = ["", "[Skill config (from ~/.hermes/config.yaml):"] + for key, value in resolved.items(): + display_val = str(value) if value else "(not set)" + lines.append(f" {key} = {display_val}") + lines.append("]") + parts.extend(lines) + except Exception: + pass # Non-critical — skill still loads without config injection + + +def _build_skill_message( + loaded_skill: dict[str, Any], + skill_dir: Path | None, + activation_note: str, + user_instruction: str = "", + runtime_note: str = "", +) -> str: + """Format a loaded skill into a user/system message payload.""" + from tools.skills_tool import SKILLS_DIR + + content = str(loaded_skill.get("content") or "") + + parts = [activation_note, "", content.strip()] + + # ── Inject resolved skill config values ── + _inject_skill_config(loaded_skill, parts) + + if loaded_skill.get("setup_skipped"): + parts.extend( + [ + "", + "[Skill setup note: Required environment setup was skipped. Continue loading the skill and explain any reduced functionality if it matters.]", + ] + ) + elif loaded_skill.get("gateway_setup_hint"): + parts.extend( + [ + "", + f"[Skill setup note: {loaded_skill['gateway_setup_hint']}]", + ] + ) + elif loaded_skill.get("setup_needed") and loaded_skill.get("setup_note"): + parts.extend( + [ + "", + f"[Skill setup note: {loaded_skill['setup_note']}]", + ] + ) + + supporting = [] + linked_files = loaded_skill.get("linked_files") or {} + for entries in linked_files.values(): + if isinstance(entries, list): + supporting.extend(entries) + + if not supporting and skill_dir: + for subdir in ("references", "templates", "scripts", "assets"): + subdir_path = skill_dir / subdir + if subdir_path.exists(): + for f in sorted(subdir_path.rglob("*")): + if f.is_file() and not f.is_symlink(): + rel = str(f.relative_to(skill_dir)) + supporting.append(rel) + + if supporting and skill_dir: + try: + skill_view_target = str(skill_dir.relative_to(SKILLS_DIR)) + except ValueError: + # Skill is from an external dir — use the skill name instead + skill_view_target = skill_dir.name + parts.append("") + parts.append("[This skill has supporting files you can load with the skill_view tool:]") + for sf in supporting: + parts.append(f"- {sf}") + parts.append( + f'\nTo view any of these, use: skill_view(name="{skill_view_target}", file_path="")' + ) + + if user_instruction: + parts.append("") + parts.append(f"The user has provided the following instruction alongside the skill invocation: {user_instruction}") + + if runtime_note: + parts.append("") + parts.append(f"[Runtime note: {runtime_note}]") + + return "\n".join(parts) + + +def scan_skill_commands() -> Dict[str, Dict[str, Any]]: + """Scan ~/.hermes/skills/ and return a mapping of /command -> skill info. + + Returns: + Dict mapping "/skill-name" to {name, description, skill_md_path, skill_dir}. + """ + global _skill_commands + _skill_commands = {} + try: + from tools.skills_tool import SKILLS_DIR, _parse_frontmatter, skill_matches_platform, _get_disabled_skill_names + from agent.skill_utils import get_external_skills_dirs + disabled = _get_disabled_skill_names() + seen_names: set = set() + + # Scan local dir first, then external dirs + dirs_to_scan = [] + if SKILLS_DIR.exists(): + dirs_to_scan.append(SKILLS_DIR) + dirs_to_scan.extend(get_external_skills_dirs()) + + for scan_dir in dirs_to_scan: + for skill_md in scan_dir.rglob("SKILL.md"): + if any(part in ('.git', '.github', '.hub') for part in skill_md.parts): + continue + try: + content = skill_md.read_text(encoding='utf-8') + frontmatter, body = _parse_frontmatter(content) + # Skip skills incompatible with the current OS platform + if not skill_matches_platform(frontmatter): + continue + name = frontmatter.get('name', skill_md.parent.name) + if name in seen_names: + continue + # Respect user's disabled skills config + if name in disabled: + continue + description = frontmatter.get('description', '') + if not description: + for line in body.strip().split('\n'): + line = line.strip() + if line and not line.startswith('#'): + description = line[:80] + break + seen_names.add(name) + # Normalize to hyphen-separated slug, stripping + # non-alnum chars (e.g. +, /) to avoid invalid + # Telegram command names downstream. + cmd_name = name.lower().replace(' ', '-').replace('_', '-') + cmd_name = _SKILL_INVALID_CHARS.sub('', cmd_name) + cmd_name = _SKILL_MULTI_HYPHEN.sub('-', cmd_name).strip('-') + if not cmd_name: + continue + _skill_commands[f"/{cmd_name}"] = { + "name": name, + "description": description or f"Invoke the {name} skill", + "skill_md_path": str(skill_md), + "skill_dir": str(skill_md.parent), + } + except Exception: + continue + except Exception: + pass + return _skill_commands + + +def get_skill_commands() -> Dict[str, Dict[str, Any]]: + """Return the current skill commands mapping (scan first if empty).""" + if not _skill_commands: + scan_skill_commands() + return _skill_commands + + +def resolve_skill_command_key(command: str) -> Optional[str]: + """Resolve a user-typed /command to its canonical skill_cmds key. + + Skills are always stored with hyphens — ``scan_skill_commands`` normalizes + spaces and underscores to hyphens when building the key. Hyphens and + underscores are treated interchangeably in user input: this matches + ``_check_unavailable_skill`` and accommodates Telegram bot-command names + (which disallow hyphens, so ``/claude-code`` is registered as + ``/claude_code`` and comes back in the underscored form). + + Returns the matching ``/slug`` key from ``get_skill_commands()`` or + ``None`` if no match. + """ + if not command: + return None + cmd_key = f"/{command.replace('_', '-')}" + return cmd_key if cmd_key in get_skill_commands() else None + + +def build_skill_invocation_message( + cmd_key: str, + user_instruction: str = "", + task_id: str | None = None, + runtime_note: str = "", +) -> Optional[str]: + """Build the user message content for a skill slash command invocation. + + Args: + cmd_key: The command key including leading slash (e.g., "/gif-search"). + user_instruction: Optional text the user typed after the command. + + Returns: + The formatted message string, or None if the skill wasn't found. + """ + commands = get_skill_commands() + skill_info = commands.get(cmd_key) + if not skill_info: + return None + + loaded = _load_skill_payload(skill_info["skill_dir"], task_id=task_id) + if not loaded: + return f"[Failed to load skill: {skill_info['name']}]" + + loaded_skill, skill_dir, skill_name = loaded + activation_note = ( + f'[SYSTEM: The user has invoked the "{skill_name}" skill, indicating they want ' + "you to follow its instructions. The full skill content is loaded below.]" + ) + return _build_skill_message( + loaded_skill, + skill_dir, + activation_note, + user_instruction=user_instruction, + runtime_note=runtime_note, + ) + + +def build_preloaded_skills_prompt( + skill_identifiers: list[str], + task_id: str | None = None, +) -> tuple[str, list[str], list[str]]: + """Load one or more skills for session-wide CLI preloading. + + Returns (prompt_text, loaded_skill_names, missing_identifiers). + """ + prompt_parts: list[str] = [] + loaded_names: list[str] = [] + missing: list[str] = [] + + seen: set[str] = set() + for raw_identifier in skill_identifiers: + identifier = (raw_identifier or "").strip() + if not identifier or identifier in seen: + continue + seen.add(identifier) + + loaded = _load_skill_payload(identifier, task_id=task_id) + if not loaded: + missing.append(identifier) + continue + + loaded_skill, skill_dir, skill_name = loaded + activation_note = ( + f'[SYSTEM: The user launched this CLI session with the "{skill_name}" skill ' + "preloaded. Treat its instructions as active guidance for the duration of this " + "session unless the user overrides them.]" + ) + prompt_parts.append( + _build_skill_message( + loaded_skill, + skill_dir, + activation_note, + ) + ) + loaded_names.append(skill_name) + + return "\n\n".join(prompt_parts), loaded_names, missing diff --git a/mindcli/_vendor/agent/skill_utils.py b/mindcli/_vendor/agent/skill_utils.py new file mode 100644 index 0000000..aa9fae5 --- /dev/null +++ b/mindcli/_vendor/agent/skill_utils.py @@ -0,0 +1,468 @@ +"""Lightweight skill metadata utilities shared by prompt_builder and skills_tool. + +This module intentionally avoids importing the tool registry, CLI config, or any +heavy dependency chain. It is safe to import at module level without triggering +tool registration or provider resolution. +""" + +import logging +import os +import re +import sys +from pathlib import Path +from typing import Any, Dict, List, Set, Tuple + +from hermes_constants import get_config_path, get_skills_dir + +logger = logging.getLogger(__name__) + +# ── Platform mapping ────────────────────────────────────────────────────── + +PLATFORM_MAP = { + "macos": "darwin", + "linux": "linux", + "windows": "win32", +} + +EXCLUDED_SKILL_DIRS = frozenset((".git", ".github", ".hub")) + +# ── Lazy YAML loader ───────────────────────────────────────────────────── + +_yaml_load_fn = None + + +def yaml_load(content: str): + """Parse YAML with lazy import and CSafeLoader preference.""" + global _yaml_load_fn + if _yaml_load_fn is None: + import yaml + + loader = getattr(yaml, "CSafeLoader", None) or yaml.SafeLoader + + def _load(value: str): + return yaml.load(value, Loader=loader) + + _yaml_load_fn = _load + return _yaml_load_fn(content) + + +# ── Frontmatter parsing ────────────────────────────────────────────────── + + +def parse_frontmatter(content: str) -> Tuple[Dict[str, Any], str]: + """Parse YAML frontmatter from a markdown string. + + Uses yaml with CSafeLoader for full YAML support (nested metadata, lists) + with a fallback to simple key:value splitting for robustness. + + Returns: + (frontmatter_dict, remaining_body) + """ + frontmatter: Dict[str, Any] = {} + body = content + + if not content.startswith("---"): + return frontmatter, body + + end_match = re.search(r"\n---\s*\n", content[3:]) + if not end_match: + return frontmatter, body + + yaml_content = content[3 : end_match.start() + 3] + body = content[end_match.end() + 3 :] + + try: + parsed = yaml_load(yaml_content) + if isinstance(parsed, dict): + frontmatter = parsed + except Exception: + # Fallback: simple key:value parsing for malformed YAML + for line in yaml_content.strip().split("\n"): + if ":" not in line: + continue + key, value = line.split(":", 1) + frontmatter[key.strip()] = value.strip() + + return frontmatter, body + + +# ── Platform matching ───────────────────────────────────────────────────── + + +def skill_matches_platform(frontmatter: Dict[str, Any]) -> bool: + """Return True when the skill is compatible with the current OS. + + Skills declare platform requirements via a top-level ``platforms`` list + in their YAML frontmatter:: + + platforms: [macos] # macOS only + platforms: [macos, linux] # macOS and Linux + + If the field is absent or empty the skill is compatible with **all** + platforms (backward-compatible default). + """ + platforms = frontmatter.get("platforms") + if not platforms: + return True + if not isinstance(platforms, list): + platforms = [platforms] + current = sys.platform + for platform in platforms: + normalized = str(platform).lower().strip() + mapped = PLATFORM_MAP.get(normalized, normalized) + if current.startswith(mapped): + return True + return False + + +# ── Disabled skills ─────────────────────────────────────────────────────── + + +def get_disabled_skill_names(platform: str | None = None) -> Set[str]: + """Read disabled skill names from config.yaml. + + Args: + platform: Explicit platform name (e.g. ``"telegram"``). When + *None*, resolves from ``HERMES_PLATFORM`` or + ``HERMES_SESSION_PLATFORM`` env vars. Falls back to the + global disabled list when no platform is determined. + + Reads the config file directly (no CLI config imports) to stay + lightweight. + """ + config_path = get_config_path() + if not config_path.exists(): + return set() + try: + parsed = yaml_load(config_path.read_text(encoding="utf-8")) + except Exception as e: + logger.debug("Could not read skill config %s: %s", config_path, e) + return set() + if not isinstance(parsed, dict): + return set() + + skills_cfg = parsed.get("skills") + if not isinstance(skills_cfg, dict): + return set() + + from gateway.session_context import get_session_env + resolved_platform = ( + platform + or os.getenv("HERMES_PLATFORM") + or get_session_env("HERMES_SESSION_PLATFORM") + ) + if resolved_platform: + platform_disabled = (skills_cfg.get("platform_disabled") or {}).get( + resolved_platform + ) + if platform_disabled is not None: + return _normalize_string_set(platform_disabled) + return _normalize_string_set(skills_cfg.get("disabled")) + + +def _normalize_string_set(values) -> Set[str]: + if values is None: + return set() + if isinstance(values, str): + values = [values] + return {str(v).strip() for v in values if str(v).strip()} + + +# ── External skills directories ────────────────────────────────────────── + + +def get_external_skills_dirs() -> List[Path]: + """Read ``skills.external_dirs`` from config.yaml and return validated paths. + + Each entry is expanded (``~`` and ``${VAR}``) and resolved to an absolute + path. Only directories that actually exist are returned. Duplicates and + paths that resolve to the local ``~/.hermes/skills/`` are silently skipped. + """ + config_path = get_config_path() + if not config_path.exists(): + return [] + try: + parsed = yaml_load(config_path.read_text(encoding="utf-8")) + except Exception: + return [] + if not isinstance(parsed, dict): + return [] + + skills_cfg = parsed.get("skills") + if not isinstance(skills_cfg, dict): + return [] + + raw_dirs = skills_cfg.get("external_dirs") + if not raw_dirs: + return [] + if isinstance(raw_dirs, str): + raw_dirs = [raw_dirs] + if not isinstance(raw_dirs, list): + return [] + + local_skills = get_skills_dir().resolve() + seen: Set[Path] = set() + result: List[Path] = [] + + for entry in raw_dirs: + entry = str(entry).strip() + if not entry: + continue + # Expand ~ and environment variables + expanded = os.path.expanduser(os.path.expandvars(entry)) + p = Path(expanded).resolve() + if p == local_skills: + continue + if p in seen: + continue + if p.is_dir(): + seen.add(p) + result.append(p) + else: + logger.debug("External skills dir does not exist, skipping: %s", p) + + return result + + +def get_all_skills_dirs() -> List[Path]: + """Return all skill directories: local first, then session-injected, then external. + + Priority (highest → lowest): + 1. Local ``~/.hermes/skills/`` — User Domain (personal skills, skill_manage writes here) + 2. Session-injected dirs via ``HERMES_SESSION_SKILLS_DIRS`` — Org → Platform domains + (set by Gateway subclasses per-request via ``set_session_env``) + 3. Config-defined ``external_dirs`` — static fallback from ``config.yaml`` + + The local dir is always first (and always included even if it doesn't exist + yet — callers handle that). Session dirs follow in injection order (Org before + Platform ensures Org > Platform precedence). External dirs come last. + """ + dirs = [get_skills_dir()] + + # ── 三元域注入：从线程 session context 读取额外 skills dirs ── + try: + from gateway.session_context import get_session_env + session_dirs_raw = get_session_env("HERMES_SESSION_SKILLS_DIRS") + if session_dirs_raw: + local_skills = get_skills_dir().resolve() + for entry in session_dirs_raw.split(","): + entry = entry.strip() + if not entry: + continue + p = Path(os.path.expanduser(os.path.expandvars(entry))).resolve() + if p != local_skills and p.is_dir(): + dirs.append(p) + except ImportError: + # CLI / non-gateway context — no session_context available + pass + + dirs.extend(get_external_skills_dirs()) + return dirs + + +# ── Condition extraction ────────────────────────────────────────────────── + + +def extract_skill_conditions(frontmatter: Dict[str, Any]) -> Dict[str, List]: + """Extract conditional activation fields from parsed frontmatter.""" + metadata = frontmatter.get("metadata") + # Handle cases where metadata is not a dict (e.g., a string from malformed YAML) + if not isinstance(metadata, dict): + metadata = {} + hermes = metadata.get("hermes") or {} + if not isinstance(hermes, dict): + hermes = {} + return { + "fallback_for_toolsets": hermes.get("fallback_for_toolsets", []), + "requires_toolsets": hermes.get("requires_toolsets", []), + "fallback_for_tools": hermes.get("fallback_for_tools", []), + "requires_tools": hermes.get("requires_tools", []), + } + + +# ── Skill config extraction ─────────────────────────────────────────────── + + +def extract_skill_config_vars(frontmatter: Dict[str, Any]) -> List[Dict[str, Any]]: + """Extract config variable declarations from parsed frontmatter. + + Skills declare config.yaml settings they need via:: + + metadata: + hermes: + config: + - key: wiki.path + description: Path to the LLM Wiki knowledge base directory + default: "~/wiki" + prompt: Wiki directory path + + Returns a list of dicts with keys: ``key``, ``description``, ``default``, + ``prompt``. Invalid or incomplete entries are silently skipped. + """ + metadata = frontmatter.get("metadata") + if not isinstance(metadata, dict): + return [] + hermes = metadata.get("hermes") + if not isinstance(hermes, dict): + return [] + raw = hermes.get("config") + if not raw: + return [] + if isinstance(raw, dict): + raw = [raw] + if not isinstance(raw, list): + return [] + + result: List[Dict[str, Any]] = [] + seen: set = set() + for item in raw: + if not isinstance(item, dict): + continue + key = str(item.get("key", "")).strip() + if not key or key in seen: + continue + # Must have at least key and description + desc = str(item.get("description", "")).strip() + if not desc: + continue + entry: Dict[str, Any] = { + "key": key, + "description": desc, + } + default = item.get("default") + if default is not None: + entry["default"] = default + prompt_text = item.get("prompt") + if isinstance(prompt_text, str) and prompt_text.strip(): + entry["prompt"] = prompt_text.strip() + else: + entry["prompt"] = desc + seen.add(key) + result.append(entry) + return result + + +def discover_all_skill_config_vars() -> List[Dict[str, Any]]: + """Scan all enabled skills and collect their config variable declarations. + + Walks every skills directory, parses each SKILL.md frontmatter, and returns + a deduplicated list of config var dicts. Each dict also includes a + ``skill`` key with the skill name for attribution. + + Disabled and platform-incompatible skills are excluded. + """ + all_vars: List[Dict[str, Any]] = [] + seen_keys: set = set() + + disabled = get_disabled_skill_names() + for skills_dir in get_all_skills_dirs(): + if not skills_dir.is_dir(): + continue + for skill_file in iter_skill_index_files(skills_dir, "SKILL.md"): + try: + raw = skill_file.read_text(encoding="utf-8") + frontmatter, _ = parse_frontmatter(raw) + except Exception: + continue + + skill_name = frontmatter.get("name") or skill_file.parent.name + if str(skill_name) in disabled: + continue + if not skill_matches_platform(frontmatter): + continue + + config_vars = extract_skill_config_vars(frontmatter) + for var in config_vars: + if var["key"] not in seen_keys: + var["skill"] = str(skill_name) + all_vars.append(var) + seen_keys.add(var["key"]) + + return all_vars + + +# Storage prefix: all skill config vars are stored under skills.config.* +# in config.yaml. Skill authors declare logical keys (e.g. "wiki.path"); +# the system adds this prefix for storage and strips it for display. +SKILL_CONFIG_PREFIX = "skills.config" + + +def _resolve_dotpath(config: Dict[str, Any], dotted_key: str): + """Walk a nested dict following a dotted key. Returns None if any part is missing.""" + parts = dotted_key.split(".") + current = config + for part in parts: + if isinstance(current, dict) and part in current: + current = current[part] + else: + return None + return current + + +def resolve_skill_config_values( + config_vars: List[Dict[str, Any]], +) -> Dict[str, Any]: + """Resolve current values for skill config vars from config.yaml. + + Skill config is stored under ``skills.config.`` in config.yaml. + Returns a dict mapping **logical** keys (as declared by skills) to their + current values (or the declared default if the key isn't set). + Path values are expanded via ``os.path.expanduser``. + """ + config_path = get_config_path() + config: Dict[str, Any] = {} + if config_path.exists(): + try: + parsed = yaml_load(config_path.read_text(encoding="utf-8")) + if isinstance(parsed, dict): + config = parsed + except Exception: + pass + + resolved: Dict[str, Any] = {} + for var in config_vars: + logical_key = var["key"] + storage_key = f"{SKILL_CONFIG_PREFIX}.{logical_key}" + value = _resolve_dotpath(config, storage_key) + + if value is None or (isinstance(value, str) and not value.strip()): + value = var.get("default", "") + + # Expand ~ in path-like values + if isinstance(value, str) and ("~" in value or "${" in value): + value = os.path.expanduser(os.path.expandvars(value)) + + resolved[logical_key] = value + + return resolved + + +# ── Description extraction ──────────────────────────────────────────────── + + +def extract_skill_description(frontmatter: Dict[str, Any]) -> str: + """Extract a truncated description from parsed frontmatter.""" + raw_desc = frontmatter.get("description", "") + if not raw_desc: + return "" + desc = str(raw_desc).strip().strip("'\"") + if len(desc) > 60: + return desc[:57] + "..." + return desc + + +# ── File iteration ──────────────────────────────────────────────────────── + + +def iter_skill_index_files(skills_dir: Path, filename: str): + """Walk skills_dir yielding sorted paths matching *filename*. + + Excludes ``.git``, ``.github``, ``.hub`` directories. + """ + matches = [] + for root, dirs, files in os.walk(skills_dir): + dirs[:] = [d for d in dirs if d not in EXCLUDED_SKILL_DIRS] + if filename in files: + matches.append(Path(root) / filename) + for path in sorted(matches, key=lambda p: str(p.relative_to(skills_dir))): + yield path diff --git a/mindcli/_vendor/agent/smart_model_routing.py b/mindcli/_vendor/agent/smart_model_routing.py new file mode 100644 index 0000000..6d482be --- /dev/null +++ b/mindcli/_vendor/agent/smart_model_routing.py @@ -0,0 +1,195 @@ +"""Helpers for optional cheap-vs-strong model routing.""" + +from __future__ import annotations + +import os +import re +from typing import Any, Dict, Optional + +from utils import is_truthy_value + +_COMPLEX_KEYWORDS = { + "debug", + "debugging", + "implement", + "implementation", + "refactor", + "patch", + "traceback", + "stacktrace", + "exception", + "error", + "analyze", + "analysis", + "investigate", + "architecture", + "design", + "compare", + "benchmark", + "optimize", + "optimise", + "review", + "terminal", + "shell", + "tool", + "tools", + "pytest", + "test", + "tests", + "plan", + "planning", + "delegate", + "subagent", + "cron", + "docker", + "kubernetes", +} + +_URL_RE = re.compile(r"https?://|www\.", re.IGNORECASE) + + +def _coerce_bool(value: Any, default: bool = False) -> bool: + return is_truthy_value(value, default=default) + + +def _coerce_int(value: Any, default: int) -> int: + try: + return int(value) + except (TypeError, ValueError): + return default + + +def choose_cheap_model_route(user_message: str, routing_config: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]: + """Return the configured cheap-model route when a message looks simple. + + Conservative by design: if the message has signs of code/tool/debugging/ + long-form work, keep the primary model. + """ + cfg = routing_config or {} + if not _coerce_bool(cfg.get("enabled"), False): + return None + + cheap_model = cfg.get("cheap_model") or {} + if not isinstance(cheap_model, dict): + return None + provider = str(cheap_model.get("provider") or "").strip().lower() + model = str(cheap_model.get("model") or "").strip() + if not provider or not model: + return None + + text = (user_message or "").strip() + if not text: + return None + + max_chars = _coerce_int(cfg.get("max_simple_chars"), 160) + max_words = _coerce_int(cfg.get("max_simple_words"), 28) + + if len(text) > max_chars: + return None + if len(text.split()) > max_words: + return None + if text.count("\n") > 1: + return None + if "```" in text or "`" in text: + return None + if _URL_RE.search(text): + return None + + lowered = text.lower() + words = {token.strip(".,:;!?()[]{}\"'`") for token in lowered.split()} + if words & _COMPLEX_KEYWORDS: + return None + + route = dict(cheap_model) + route["provider"] = provider + route["model"] = model + route["routing_reason"] = "simple_turn" + return route + + +def resolve_turn_route(user_message: str, routing_config: Optional[Dict[str, Any]], primary: Dict[str, Any]) -> Dict[str, Any]: + """Resolve the effective model/runtime for one turn. + + Returns a dict with model/runtime/signature/label fields. + """ + route = choose_cheap_model_route(user_message, routing_config) + if not route: + return { + "model": primary.get("model"), + "runtime": { + "api_key": primary.get("api_key"), + "base_url": primary.get("base_url"), + "provider": primary.get("provider"), + "api_mode": primary.get("api_mode"), + "command": primary.get("command"), + "args": list(primary.get("args") or []), + "credential_pool": primary.get("credential_pool"), + }, + "label": None, + "signature": ( + primary.get("model"), + primary.get("provider"), + primary.get("base_url"), + primary.get("api_mode"), + primary.get("command"), + tuple(primary.get("args") or ()), + ), + } + + from hermes_cli.runtime_provider import resolve_runtime_provider + + explicit_api_key = None + api_key_env = str(route.get("api_key_env") or "").strip() + if api_key_env: + explicit_api_key = os.getenv(api_key_env) or None + + try: + runtime = resolve_runtime_provider( + requested=route.get("provider"), + explicit_api_key=explicit_api_key, + explicit_base_url=route.get("base_url"), + ) + except Exception: + return { + "model": primary.get("model"), + "runtime": { + "api_key": primary.get("api_key"), + "base_url": primary.get("base_url"), + "provider": primary.get("provider"), + "api_mode": primary.get("api_mode"), + "command": primary.get("command"), + "args": list(primary.get("args") or []), + "credential_pool": primary.get("credential_pool"), + }, + "label": None, + "signature": ( + primary.get("model"), + primary.get("provider"), + primary.get("base_url"), + primary.get("api_mode"), + primary.get("command"), + tuple(primary.get("args") or ()), + ), + } + + return { + "model": route.get("model"), + "runtime": { + "api_key": runtime.get("api_key"), + "base_url": runtime.get("base_url"), + "provider": runtime.get("provider"), + "api_mode": runtime.get("api_mode"), + "command": runtime.get("command"), + "args": list(runtime.get("args") or []), + "credential_pool": runtime.get("credential_pool"), + }, + "label": f"smart route → {route.get('model')} ({runtime.get('provider')})", + "signature": ( + route.get("model"), + runtime.get("provider"), + runtime.get("base_url"), + runtime.get("api_mode"), + runtime.get("command"), + tuple(runtime.get("args") or ()), + ), + } diff --git a/mindcli/_vendor/agent/subdirectory_hints.py b/mindcli/_vendor/agent/subdirectory_hints.py new file mode 100644 index 0000000..dcc514b --- /dev/null +++ b/mindcli/_vendor/agent/subdirectory_hints.py @@ -0,0 +1,224 @@ +"""Progressive subdirectory hint discovery. + +As the agent navigates into subdirectories via tool calls (read_file, terminal, +search_files, etc.), this module discovers and loads project context files +(AGENTS.md, CLAUDE.md, .cursorrules) from those directories. Discovered hints +are appended to the tool result so the model gets relevant context at the moment +it starts working in a new area of the codebase. + +This complements the startup context loading in ``prompt_builder.py`` which only +loads from the CWD. Subdirectory hints are discovered lazily and injected into +the conversation without modifying the system prompt (preserving prompt caching). + +Inspired by Block/goose's SubdirectoryHintTracker. +""" + +import logging +import os +import shlex +from pathlib import Path +from typing import Dict, Any, Optional, Set + +from agent.prompt_builder import _scan_context_content + +logger = logging.getLogger(__name__) + +# Context files to look for in subdirectories, in priority order. +# Same filenames as prompt_builder.py but we load ALL found (not first-wins) +# since different subdirectories may use different conventions. +_HINT_FILENAMES = [ + "AGENTS.md", "agents.md", + "CLAUDE.md", "claude.md", + ".cursorrules", +] + +# Maximum chars per hint file to prevent context bloat +_MAX_HINT_CHARS = 8_000 + +# Tool argument keys that typically contain file paths +_PATH_ARG_KEYS = {"path", "file_path", "workdir"} + +# Tools that take shell commands where we should extract paths +_COMMAND_TOOLS = {"terminal"} + +# How many parent directories to walk up when looking for hints. +# Prevents scanning all the way to / for deeply nested paths. +_MAX_ANCESTOR_WALK = 5 + +class SubdirectoryHintTracker: + """Track which directories the agent visits and load hints on first access. + + Usage:: + + tracker = SubdirectoryHintTracker(working_dir="/path/to/project") + + # After each tool call: + hints = tracker.check_tool_call("read_file", {"path": "backend/src/main.py"}) + if hints: + tool_result += hints # append to the tool result string + """ + + def __init__(self, working_dir: Optional[str] = None): + self.working_dir = Path(working_dir or os.getcwd()).resolve() + self._loaded_dirs: Set[Path] = set() + # Pre-mark the working dir as loaded (startup context handles it) + self._loaded_dirs.add(self.working_dir) + + def check_tool_call( + self, + tool_name: str, + tool_args: Dict[str, Any], + ) -> Optional[str]: + """Check tool call arguments for new directories and load any hint files. + + Returns formatted hint text to append to the tool result, or None. + """ + dirs = self._extract_directories(tool_name, tool_args) + if not dirs: + return None + + all_hints = [] + for d in dirs: + hints = self._load_hints_for_directory(d) + if hints: + all_hints.append(hints) + + if not all_hints: + return None + + return "\n\n" + "\n\n".join(all_hints) + + def _extract_directories( + self, tool_name: str, args: Dict[str, Any] + ) -> list: + """Extract directory paths from tool call arguments.""" + candidates: Set[Path] = set() + + # Direct path arguments + for key in _PATH_ARG_KEYS: + val = args.get(key) + if isinstance(val, str) and val.strip(): + self._add_path_candidate(val, candidates) + + # Shell commands — extract path-like tokens + if tool_name in _COMMAND_TOOLS: + cmd = args.get("command", "") + if isinstance(cmd, str): + self._extract_paths_from_command(cmd, candidates) + + return list(candidates) + + def _add_path_candidate(self, raw_path: str, candidates: Set[Path]): + """Resolve a raw path and add its directory + ancestors to candidates. + + Walks up from the resolved directory toward the filesystem root, + stopping at the first directory already in ``_loaded_dirs`` (or after + ``_MAX_ANCESTOR_WALK`` levels). This ensures that reading + ``project/src/main.py`` discovers ``project/AGENTS.md`` even when + ``project/src/`` has no hint files of its own. + """ + try: + p = Path(raw_path).expanduser() + if not p.is_absolute(): + p = self.working_dir / p + p = p.resolve() + # Use parent if it's a file path (has extension or doesn't exist as dir) + if p.suffix or (p.exists() and p.is_file()): + p = p.parent + # Walk up ancestors — stop at already-loaded or root + for _ in range(_MAX_ANCESTOR_WALK): + if p in self._loaded_dirs: + break + if self._is_valid_subdir(p): + candidates.add(p) + parent = p.parent + if parent == p: + break # filesystem root + p = parent + except (OSError, ValueError): + pass + + def _extract_paths_from_command(self, cmd: str, candidates: Set[Path]): + """Extract path-like tokens from a shell command string.""" + try: + tokens = shlex.split(cmd) + except ValueError: + tokens = cmd.split() + + for token in tokens: + # Skip flags + if token.startswith("-"): + continue + # Must look like a path (contains / or .) + if "/" not in token and "." not in token: + continue + # Skip URLs + if token.startswith(("http://", "https://", "git@")): + continue + self._add_path_candidate(token, candidates) + + def _is_valid_subdir(self, path: Path) -> bool: + """Check if path is a valid directory to scan for hints.""" + try: + if not path.is_dir(): + return False + except OSError: + return False + if path in self._loaded_dirs: + return False + return True + + def _load_hints_for_directory(self, directory: Path) -> Optional[str]: + """Load hint files from a directory. Returns formatted text or None.""" + self._loaded_dirs.add(directory) + + found_hints = [] + for filename in _HINT_FILENAMES: + hint_path = directory / filename + try: + if not hint_path.is_file(): + continue + except OSError: + continue + try: + content = hint_path.read_text(encoding="utf-8").strip() + if not content: + continue + # Same security scan as startup context loading + content = _scan_context_content(content, filename) + if len(content) > _MAX_HINT_CHARS: + content = ( + content[:_MAX_HINT_CHARS] + + f"\n\n[...truncated {filename}: {len(content):,} chars total]" + ) + # Best-effort relative path for display + rel_path = str(hint_path) + try: + rel_path = str(hint_path.relative_to(self.working_dir)) + except ValueError: + try: + rel_path = str(hint_path.relative_to(Path.home())) + rel_path = "~/" + rel_path + except ValueError: + pass # keep absolute + found_hints.append((rel_path, content)) + # First match wins per directory (like startup loading) + break + except Exception as exc: + logger.debug("Could not read %s: %s", hint_path, exc) + + if not found_hints: + return None + + sections = [] + for rel_path, content in found_hints: + sections.append( + f"[Subdirectory context discovered: {rel_path}]\n{content}" + ) + + logger.debug( + "Loaded subdirectory hints from %s: %s", + directory, + [h[0] for h in found_hints], + ) + return "\n\n".join(sections) diff --git a/mindcli/_vendor/agent/title_generator.py b/mindcli/_vendor/agent/title_generator.py new file mode 100644 index 0000000..d6ed920 --- /dev/null +++ b/mindcli/_vendor/agent/title_generator.py @@ -0,0 +1,125 @@ +"""Auto-generate short session titles from the first user/assistant exchange. + +Runs asynchronously after the first response is delivered so it never +adds latency to the user-facing reply. +""" + +import logging +import threading +from typing import Optional + +from agent.auxiliary_client import call_llm + +logger = logging.getLogger(__name__) + +_TITLE_PROMPT = ( + "Generate a short, descriptive title (3-7 words) for a conversation that starts with the " + "following exchange. The title should capture the main topic or intent. " + "Return ONLY the title text, nothing else. No quotes, no punctuation at the end, no prefixes." +) + + +def generate_title(user_message: str, assistant_response: str, timeout: float = 30.0) -> Optional[str]: + """Generate a session title from the first exchange. + + Uses the auxiliary LLM client (cheapest/fastest available model). + Returns the title string or None on failure. + """ + # Truncate long messages to keep the request small + user_snippet = user_message[:500] if user_message else "" + assistant_snippet = assistant_response[:500] if assistant_response else "" + + messages = [ + {"role": "system", "content": _TITLE_PROMPT}, + {"role": "user", "content": f"User: {user_snippet}\n\nAssistant: {assistant_snippet}"}, + ] + + try: + response = call_llm( + task="title_generation", + messages=messages, + max_tokens=30, + temperature=0.3, + timeout=timeout, + ) + title = (response.choices[0].message.content or "").strip() + # Clean up: remove quotes, trailing punctuation, prefixes like "Title: " + title = title.strip('"\'') + if title.lower().startswith("title:"): + title = title[6:].strip() + # Enforce reasonable length + if len(title) > 80: + title = title[:77] + "..." + return title if title else None + except Exception as e: + logger.debug("Title generation failed: %s", e) + return None + + +def auto_title_session( + session_db, + session_id: str, + user_message: str, + assistant_response: str, +) -> None: + """Generate and set a session title if one doesn't already exist. + + Called in a background thread after the first exchange completes. + Silently skips if: + - session_db is None + - session already has a title (user-set or previously auto-generated) + - title generation fails + """ + if not session_db or not session_id: + return + + # Check if title already exists (user may have set one via /title before first response) + try: + existing = session_db.get_session_title(session_id) + if existing: + return + except Exception: + return + + title = generate_title(user_message, assistant_response) + if not title: + return + + try: + session_db.set_session_title(session_id, title) + logger.debug("Auto-generated session title: %s", title) + except Exception as e: + logger.debug("Failed to set auto-generated title: %s", e) + + +def maybe_auto_title( + session_db, + session_id: str, + user_message: str, + assistant_response: str, + conversation_history: list, +) -> None: + """Fire-and-forget title generation after the first exchange. + + Only generates a title when: + - This appears to be the first user→assistant exchange + - No title is already set + """ + if not session_db or not session_id or not user_message or not assistant_response: + return + + # Count user messages in history to detect first exchange. + # conversation_history includes the exchange that just happened, + # so for a first exchange we expect exactly 1 user message + # (or 2 counting system). Be generous: generate on first 2 exchanges. + user_msg_count = sum(1 for m in (conversation_history or []) if m.get("role") == "user") + if user_msg_count > 2: + return + + thread = threading.Thread( + target=auto_title_session, + args=(session_db, session_id, user_message, assistant_response), + daemon=True, + name="auto-title", + ) + thread.start() diff --git a/mindcli/_vendor/agent/trajectory.py b/mindcli/_vendor/agent/trajectory.py new file mode 100644 index 0000000..90696eb --- /dev/null +++ b/mindcli/_vendor/agent/trajectory.py @@ -0,0 +1,56 @@ +"""Trajectory saving utilities and static helpers. + +_convert_to_trajectory_format stays as an AIAgent method (batch_runner.py +calls agent._convert_to_trajectory_format). Only the static helpers and +the file-write logic live here. +""" + +import json +import logging +from datetime import datetime +from typing import Any, Dict, List + +logger = logging.getLogger(__name__) + + +def convert_scratchpad_to_think(content: str) -> str: + """Convert tags to tags.""" + if not content or "" not in content: + return content + return content.replace("", "").replace("", "") + + +def has_incomplete_scratchpad(content: str) -> bool: + """Check if content has an opening without a closing tag.""" + if not content: + return False + return "" in content and "" not in content + + +def save_trajectory(trajectory: List[Dict[str, Any]], model: str, + completed: bool, filename: str = None): + """Append a trajectory entry to a JSONL file. + + Args: + trajectory: The ShareGPT-format conversation list. + model: Model name for metadata. + completed: Whether the conversation completed successfully. + filename: Override output filename. Defaults to trajectory_samples.jsonl + or failed_trajectories.jsonl based on ``completed``. + """ + if filename is None: + filename = "trajectory_samples.jsonl" if completed else "failed_trajectories.jsonl" + + entry = { + "conversations": trajectory, + "timestamp": datetime.now().isoformat(), + "model": model, + "completed": completed, + } + + try: + with open(filename, "a", encoding="utf-8") as f: + f.write(json.dumps(entry, ensure_ascii=False) + "\n") + logger.info("Trajectory saved to %s", filename) + except Exception as e: + logger.warning("Failed to save trajectory: %s", e) diff --git a/mindcli/_vendor/agent/usage_pricing.py b/mindcli/_vendor/agent/usage_pricing.py new file mode 100644 index 0000000..736c2dc --- /dev/null +++ b/mindcli/_vendor/agent/usage_pricing.py @@ -0,0 +1,613 @@ +from __future__ import annotations + +from dataclasses import dataclass +from datetime import datetime, timezone +from decimal import Decimal +from typing import Any, Dict, Literal, Optional + +from agent.model_metadata import fetch_endpoint_model_metadata, fetch_model_metadata + +DEFAULT_PRICING = {"input": 0.0, "output": 0.0} + +_ZERO = Decimal("0") +_ONE_MILLION = Decimal("1000000") + +CostStatus = Literal["actual", "estimated", "included", "unknown"] +CostSource = Literal[ + "provider_cost_api", + "provider_generation_api", + "provider_models_api", + "official_docs_snapshot", + "user_override", + "custom_contract", + "none", +] + + +@dataclass(frozen=True) +class CanonicalUsage: + input_tokens: int = 0 + output_tokens: int = 0 + cache_read_tokens: int = 0 + cache_write_tokens: int = 0 + reasoning_tokens: int = 0 + request_count: int = 1 + raw_usage: Optional[dict[str, Any]] = None + + @property + def prompt_tokens(self) -> int: + return self.input_tokens + self.cache_read_tokens + self.cache_write_tokens + + @property + def total_tokens(self) -> int: + return self.prompt_tokens + self.output_tokens + + +@dataclass(frozen=True) +class BillingRoute: + provider: str + model: str + base_url: str = "" + billing_mode: str = "unknown" + + +@dataclass(frozen=True) +class PricingEntry: + input_cost_per_million: Optional[Decimal] = None + output_cost_per_million: Optional[Decimal] = None + cache_read_cost_per_million: Optional[Decimal] = None + cache_write_cost_per_million: Optional[Decimal] = None + request_cost: Optional[Decimal] = None + source: CostSource = "none" + source_url: Optional[str] = None + pricing_version: Optional[str] = None + fetched_at: Optional[datetime] = None + + +@dataclass(frozen=True) +class CostResult: + amount_usd: Optional[Decimal] + status: CostStatus + source: CostSource + label: str + fetched_at: Optional[datetime] = None + pricing_version: Optional[str] = None + notes: tuple[str, ...] = () + + +_UTC_NOW = lambda: datetime.now(timezone.utc) + + +# Official docs snapshot entries. Models whose published pricing and cache +# semantics are stable enough to encode exactly. +_OFFICIAL_DOCS_PRICING: Dict[tuple[str, str], PricingEntry] = { + ( + "anthropic", + "claude-opus-4-20250514", + ): PricingEntry( + input_cost_per_million=Decimal("15.00"), + output_cost_per_million=Decimal("75.00"), + cache_read_cost_per_million=Decimal("1.50"), + cache_write_cost_per_million=Decimal("18.75"), + source="official_docs_snapshot", + source_url="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching", + pricing_version="anthropic-prompt-caching-2026-03-16", + ), + ( + "anthropic", + "claude-sonnet-4-20250514", + ): PricingEntry( + input_cost_per_million=Decimal("3.00"), + output_cost_per_million=Decimal("15.00"), + cache_read_cost_per_million=Decimal("0.30"), + cache_write_cost_per_million=Decimal("3.75"), + source="official_docs_snapshot", + source_url="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching", + pricing_version="anthropic-prompt-caching-2026-03-16", + ), + # OpenAI + ( + "openai", + "gpt-4o", + ): PricingEntry( + input_cost_per_million=Decimal("2.50"), + output_cost_per_million=Decimal("10.00"), + cache_read_cost_per_million=Decimal("1.25"), + source="official_docs_snapshot", + source_url="https://openai.com/api/pricing/", + pricing_version="openai-pricing-2026-03-16", + ), + ( + "openai", + "gpt-4o-mini", + ): PricingEntry( + input_cost_per_million=Decimal("0.15"), + output_cost_per_million=Decimal("0.60"), + cache_read_cost_per_million=Decimal("0.075"), + source="official_docs_snapshot", + source_url="https://openai.com/api/pricing/", + pricing_version="openai-pricing-2026-03-16", + ), + ( + "openai", + "gpt-4.1", + ): PricingEntry( + input_cost_per_million=Decimal("2.00"), + output_cost_per_million=Decimal("8.00"), + cache_read_cost_per_million=Decimal("0.50"), + source="official_docs_snapshot", + source_url="https://openai.com/api/pricing/", + pricing_version="openai-pricing-2026-03-16", + ), + ( + "openai", + "gpt-4.1-mini", + ): PricingEntry( + input_cost_per_million=Decimal("0.40"), + output_cost_per_million=Decimal("1.60"), + cache_read_cost_per_million=Decimal("0.10"), + source="official_docs_snapshot", + source_url="https://openai.com/api/pricing/", + pricing_version="openai-pricing-2026-03-16", + ), + ( + "openai", + "gpt-4.1-nano", + ): PricingEntry( + input_cost_per_million=Decimal("0.10"), + output_cost_per_million=Decimal("0.40"), + cache_read_cost_per_million=Decimal("0.025"), + source="official_docs_snapshot", + source_url="https://openai.com/api/pricing/", + pricing_version="openai-pricing-2026-03-16", + ), + ( + "openai", + "o3", + ): PricingEntry( + input_cost_per_million=Decimal("10.00"), + output_cost_per_million=Decimal("40.00"), + cache_read_cost_per_million=Decimal("2.50"), + source="official_docs_snapshot", + source_url="https://openai.com/api/pricing/", + pricing_version="openai-pricing-2026-03-16", + ), + ( + "openai", + "o3-mini", + ): PricingEntry( + input_cost_per_million=Decimal("1.10"), + output_cost_per_million=Decimal("4.40"), + cache_read_cost_per_million=Decimal("0.55"), + source="official_docs_snapshot", + source_url="https://openai.com/api/pricing/", + pricing_version="openai-pricing-2026-03-16", + ), + # Anthropic older models (pre-4.6 generation) + ( + "anthropic", + "claude-3-5-sonnet-20241022", + ): PricingEntry( + input_cost_per_million=Decimal("3.00"), + output_cost_per_million=Decimal("15.00"), + cache_read_cost_per_million=Decimal("0.30"), + cache_write_cost_per_million=Decimal("3.75"), + source="official_docs_snapshot", + source_url="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching", + pricing_version="anthropic-pricing-2026-03-16", + ), + ( + "anthropic", + "claude-3-5-haiku-20241022", + ): PricingEntry( + input_cost_per_million=Decimal("0.80"), + output_cost_per_million=Decimal("4.00"), + cache_read_cost_per_million=Decimal("0.08"), + cache_write_cost_per_million=Decimal("1.00"), + source="official_docs_snapshot", + source_url="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching", + pricing_version="anthropic-pricing-2026-03-16", + ), + ( + "anthropic", + "claude-3-opus-20240229", + ): PricingEntry( + input_cost_per_million=Decimal("15.00"), + output_cost_per_million=Decimal("75.00"), + cache_read_cost_per_million=Decimal("1.50"), + cache_write_cost_per_million=Decimal("18.75"), + source="official_docs_snapshot", + source_url="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching", + pricing_version="anthropic-pricing-2026-03-16", + ), + ( + "anthropic", + "claude-3-haiku-20240307", + ): PricingEntry( + input_cost_per_million=Decimal("0.25"), + output_cost_per_million=Decimal("1.25"), + cache_read_cost_per_million=Decimal("0.03"), + cache_write_cost_per_million=Decimal("0.30"), + source="official_docs_snapshot", + source_url="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching", + pricing_version="anthropic-pricing-2026-03-16", + ), + # DeepSeek + ( + "deepseek", + "deepseek-chat", + ): PricingEntry( + input_cost_per_million=Decimal("0.14"), + output_cost_per_million=Decimal("0.28"), + source="official_docs_snapshot", + source_url="https://api-docs.deepseek.com/quick_start/pricing", + pricing_version="deepseek-pricing-2026-03-16", + ), + ( + "deepseek", + "deepseek-reasoner", + ): PricingEntry( + input_cost_per_million=Decimal("0.55"), + output_cost_per_million=Decimal("2.19"), + source="official_docs_snapshot", + source_url="https://api-docs.deepseek.com/quick_start/pricing", + pricing_version="deepseek-pricing-2026-03-16", + ), + # Google Gemini + ( + "google", + "gemini-2.5-pro", + ): PricingEntry( + input_cost_per_million=Decimal("1.25"), + output_cost_per_million=Decimal("10.00"), + source="official_docs_snapshot", + source_url="https://ai.google.dev/pricing", + pricing_version="google-pricing-2026-03-16", + ), + ( + "google", + "gemini-2.5-flash", + ): PricingEntry( + input_cost_per_million=Decimal("0.15"), + output_cost_per_million=Decimal("0.60"), + source="official_docs_snapshot", + source_url="https://ai.google.dev/pricing", + pricing_version="google-pricing-2026-03-16", + ), + ( + "google", + "gemini-2.0-flash", + ): PricingEntry( + input_cost_per_million=Decimal("0.10"), + output_cost_per_million=Decimal("0.40"), + source="official_docs_snapshot", + source_url="https://ai.google.dev/pricing", + pricing_version="google-pricing-2026-03-16", + ), +} + + +def _to_decimal(value: Any) -> Optional[Decimal]: + if value is None: + return None + try: + return Decimal(str(value)) + except Exception: + return None + + +def _to_int(value: Any) -> int: + try: + return int(value or 0) + except Exception: + return 0 + + +def resolve_billing_route( + model_name: str, + provider: Optional[str] = None, + base_url: Optional[str] = None, +) -> BillingRoute: + provider_name = (provider or "").strip().lower() + base = (base_url or "").strip().lower() + model = (model_name or "").strip() + if not provider_name and "/" in model: + inferred_provider, bare_model = model.split("/", 1) + if inferred_provider in {"anthropic", "openai", "google"}: + provider_name = inferred_provider + model = bare_model + + if provider_name == "openai-codex": + return BillingRoute(provider="openai-codex", model=model, base_url=base_url or "", billing_mode="subscription_included") + if provider_name == "openrouter" or "openrouter.ai" in base: + return BillingRoute(provider="openrouter", model=model, base_url=base_url or "", billing_mode="official_models_api") + if provider_name == "anthropic": + return BillingRoute(provider="anthropic", model=model.split("/")[-1], base_url=base_url or "", billing_mode="official_docs_snapshot") + if provider_name == "openai": + return BillingRoute(provider="openai", model=model.split("/")[-1], base_url=base_url or "", billing_mode="official_docs_snapshot") + if provider_name in {"custom", "local"} or (base and "localhost" in base): + return BillingRoute(provider=provider_name or "custom", model=model, base_url=base_url or "", billing_mode="unknown") + return BillingRoute(provider=provider_name or "unknown", model=model.split("/")[-1] if model else "", base_url=base_url or "", billing_mode="unknown") + + +def _lookup_official_docs_pricing(route: BillingRoute) -> Optional[PricingEntry]: + return _OFFICIAL_DOCS_PRICING.get((route.provider, route.model.lower())) + + +def _openrouter_pricing_entry(route: BillingRoute) -> Optional[PricingEntry]: + return _pricing_entry_from_metadata( + fetch_model_metadata(), + route.model, + source_url="https://openrouter.ai/docs/api/api-reference/models/get-models", + pricing_version="openrouter-models-api", + ) + + +def _pricing_entry_from_metadata( + metadata: Dict[str, Dict[str, Any]], + model_id: str, + *, + source_url: str, + pricing_version: str, +) -> Optional[PricingEntry]: + if model_id not in metadata: + return None + pricing = metadata[model_id].get("pricing") or {} + prompt = _to_decimal(pricing.get("prompt")) + completion = _to_decimal(pricing.get("completion")) + request = _to_decimal(pricing.get("request")) + cache_read = _to_decimal( + pricing.get("cache_read") + or pricing.get("cached_prompt") + or pricing.get("input_cache_read") + ) + cache_write = _to_decimal( + pricing.get("cache_write") + or pricing.get("cache_creation") + or pricing.get("input_cache_write") + ) + if prompt is None and completion is None and request is None: + return None + + def _per_token_to_per_million(value: Optional[Decimal]) -> Optional[Decimal]: + if value is None: + return None + return value * _ONE_MILLION + + return PricingEntry( + input_cost_per_million=_per_token_to_per_million(prompt), + output_cost_per_million=_per_token_to_per_million(completion), + cache_read_cost_per_million=_per_token_to_per_million(cache_read), + cache_write_cost_per_million=_per_token_to_per_million(cache_write), + request_cost=request, + source="provider_models_api", + source_url=source_url, + pricing_version=pricing_version, + fetched_at=_UTC_NOW(), + ) + + +def get_pricing_entry( + model_name: str, + provider: Optional[str] = None, + base_url: Optional[str] = None, + api_key: Optional[str] = None, +) -> Optional[PricingEntry]: + route = resolve_billing_route(model_name, provider=provider, base_url=base_url) + if route.billing_mode == "subscription_included": + return PricingEntry( + input_cost_per_million=_ZERO, + output_cost_per_million=_ZERO, + cache_read_cost_per_million=_ZERO, + cache_write_cost_per_million=_ZERO, + source="none", + pricing_version="included-route", + ) + if route.provider == "openrouter": + return _openrouter_pricing_entry(route) + if route.base_url: + entry = _pricing_entry_from_metadata( + fetch_endpoint_model_metadata(route.base_url, api_key=api_key or ""), + route.model, + source_url=f"{route.base_url.rstrip('/')}/models", + pricing_version="openai-compatible-models-api", + ) + if entry: + return entry + return _lookup_official_docs_pricing(route) + + +def normalize_usage( + response_usage: Any, + *, + provider: Optional[str] = None, + api_mode: Optional[str] = None, +) -> CanonicalUsage: + """Normalize raw API response usage into canonical token buckets. + + Handles three API shapes: + - Anthropic: input_tokens/output_tokens/cache_read_input_tokens/cache_creation_input_tokens + - Codex Responses: input_tokens includes cache tokens; input_tokens_details.cached_tokens separates them + - OpenAI Chat Completions: prompt_tokens includes cache tokens; prompt_tokens_details.cached_tokens separates them + + In both Codex and OpenAI modes, input_tokens is derived by subtracting cache + tokens from the total — the API contract is that input/prompt totals include + cached tokens and the details object breaks them out. + """ + if not response_usage: + return CanonicalUsage() + + provider_name = (provider or "").strip().lower() + mode = (api_mode or "").strip().lower() + + if mode == "anthropic_messages" or provider_name == "anthropic": + input_tokens = _to_int(getattr(response_usage, "input_tokens", 0)) + output_tokens = _to_int(getattr(response_usage, "output_tokens", 0)) + cache_read_tokens = _to_int(getattr(response_usage, "cache_read_input_tokens", 0)) + cache_write_tokens = _to_int(getattr(response_usage, "cache_creation_input_tokens", 0)) + elif mode == "codex_responses": + input_total = _to_int(getattr(response_usage, "input_tokens", 0)) + output_tokens = _to_int(getattr(response_usage, "output_tokens", 0)) + details = getattr(response_usage, "input_tokens_details", None) + cache_read_tokens = _to_int(getattr(details, "cached_tokens", 0) if details else 0) + cache_write_tokens = _to_int( + getattr(details, "cache_creation_tokens", 0) if details else 0 + ) + input_tokens = max(0, input_total - cache_read_tokens - cache_write_tokens) + else: + prompt_total = _to_int(getattr(response_usage, "prompt_tokens", 0)) + output_tokens = _to_int(getattr(response_usage, "completion_tokens", 0)) + details = getattr(response_usage, "prompt_tokens_details", None) + cache_read_tokens = _to_int(getattr(details, "cached_tokens", 0) if details else 0) + cache_write_tokens = _to_int( + getattr(details, "cache_write_tokens", 0) if details else 0 + ) + input_tokens = max(0, prompt_total - cache_read_tokens - cache_write_tokens) + + reasoning_tokens = 0 + output_details = getattr(response_usage, "output_tokens_details", None) + if output_details: + reasoning_tokens = _to_int(getattr(output_details, "reasoning_tokens", 0)) + + return CanonicalUsage( + input_tokens=input_tokens, + output_tokens=output_tokens, + cache_read_tokens=cache_read_tokens, + cache_write_tokens=cache_write_tokens, + reasoning_tokens=reasoning_tokens, + ) + + +def estimate_usage_cost( + model_name: str, + usage: CanonicalUsage, + *, + provider: Optional[str] = None, + base_url: Optional[str] = None, + api_key: Optional[str] = None, +) -> CostResult: + route = resolve_billing_route(model_name, provider=provider, base_url=base_url) + if route.billing_mode == "subscription_included": + return CostResult( + amount_usd=_ZERO, + status="included", + source="none", + label="included", + pricing_version="included-route", + ) + + entry = get_pricing_entry(model_name, provider=provider, base_url=base_url, api_key=api_key) + if not entry: + return CostResult(amount_usd=None, status="unknown", source="none", label="n/a") + + notes: list[str] = [] + amount = _ZERO + + if usage.input_tokens and entry.input_cost_per_million is None: + return CostResult(amount_usd=None, status="unknown", source=entry.source, label="n/a") + if usage.output_tokens and entry.output_cost_per_million is None: + return CostResult(amount_usd=None, status="unknown", source=entry.source, label="n/a") + if usage.cache_read_tokens: + if entry.cache_read_cost_per_million is None: + return CostResult( + amount_usd=None, + status="unknown", + source=entry.source, + label="n/a", + notes=("cache-read pricing unavailable for route",), + ) + if usage.cache_write_tokens: + if entry.cache_write_cost_per_million is None: + return CostResult( + amount_usd=None, + status="unknown", + source=entry.source, + label="n/a", + notes=("cache-write pricing unavailable for route",), + ) + + if entry.input_cost_per_million is not None: + amount += Decimal(usage.input_tokens) * entry.input_cost_per_million / _ONE_MILLION + if entry.output_cost_per_million is not None: + amount += Decimal(usage.output_tokens) * entry.output_cost_per_million / _ONE_MILLION + if entry.cache_read_cost_per_million is not None: + amount += Decimal(usage.cache_read_tokens) * entry.cache_read_cost_per_million / _ONE_MILLION + if entry.cache_write_cost_per_million is not None: + amount += Decimal(usage.cache_write_tokens) * entry.cache_write_cost_per_million / _ONE_MILLION + if entry.request_cost is not None and usage.request_count: + amount += Decimal(usage.request_count) * entry.request_cost + + status: CostStatus = "estimated" + label = f"~${amount:.2f}" + if entry.source == "none" and amount == _ZERO: + status = "included" + label = "included" + + if route.provider == "openrouter": + notes.append("OpenRouter cost is estimated from the models API until reconciled.") + + return CostResult( + amount_usd=amount, + status=status, + source=entry.source, + label=label, + fetched_at=entry.fetched_at, + pricing_version=entry.pricing_version, + notes=tuple(notes), + ) + + +def has_known_pricing( + model_name: str, + provider: Optional[str] = None, + base_url: Optional[str] = None, + api_key: Optional[str] = None, +) -> bool: + """Check whether we have pricing data for this model+route. + + Uses direct lookup instead of routing through the full estimation + pipeline — avoids creating dummy usage objects just to check status. + """ + route = resolve_billing_route(model_name, provider=provider, base_url=base_url) + if route.billing_mode == "subscription_included": + return True + entry = get_pricing_entry(model_name, provider=provider, base_url=base_url, api_key=api_key) + return entry is not None + + + +def format_duration_compact(seconds: float) -> str: + if seconds < 60: + return f"{seconds:.0f}s" + minutes = seconds / 60 + if minutes < 60: + return f"{minutes:.0f}m" + hours = minutes / 60 + if hours < 24: + remaining_min = int(minutes % 60) + return f"{int(hours)}h {remaining_min}m" if remaining_min else f"{int(hours)}h" + days = hours / 24 + return f"{days:.1f}d" + + +def format_token_count_compact(value: int) -> str: + abs_value = abs(int(value)) + if abs_value < 1_000: + return str(int(value)) + + sign = "-" if value < 0 else "" + units = ((1_000_000_000, "B"), (1_000_000, "M"), (1_000, "K")) + for threshold, suffix in units: + if abs_value >= threshold: + scaled = abs_value / threshold + if scaled < 10: + text = f"{scaled:.2f}" + elif scaled < 100: + text = f"{scaled:.1f}" + else: + text = f"{scaled:.0f}" + if "." in text: + text = text.rstrip("0").rstrip(".") + return f"{sign}{text}{suffix}" + + return f"{value:,}" diff --git a/mindcli/_vendor/batch_runner.py b/mindcli/_vendor/batch_runner.py new file mode 100644 index 0000000..195452c --- /dev/null +++ b/mindcli/_vendor/batch_runner.py @@ -0,0 +1,1287 @@ +#!/usr/bin/env python3 +""" +Batch Agent Runner + +This module provides parallel batch processing capabilities for running the agent +across multiple prompts from a dataset. It includes: +- Dataset loading and batching +- Parallel batch processing with multiprocessing +- Checkpointing for fault tolerance and resumption +- Trajectory saving in the proper format (from/value pairs) +- Tool usage statistics aggregation across all batches + +Usage: + python batch_runner.py --dataset_file=data.jsonl --batch_size=10 --run_name=my_run + + # Resume an interrupted run + python batch_runner.py --dataset_file=data.jsonl --batch_size=10 --run_name=my_run --resume + + # Use a specific toolset distribution + python batch_runner.py --dataset_file=data.jsonl --batch_size=10 --run_name=my_run --distribution=image_gen +""" + +import json +import logging +import os +import time +from pathlib import Path +from typing import List, Dict, Any, Optional, Tuple +from datetime import datetime +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 +from toolset_distributions import ( + list_distributions, + sample_toolsets_from_distribution, + validate_distribution +) +from model_tools import TOOL_TO_TOOLSET_MAP + + +# Global configuration for worker processes +_WORKER_CONFIG = {} + +# All possible tools - auto-derived from the master mapping in model_tools.py. +# This stays in sync automatically when new tools are added to TOOL_TO_TOOLSET_MAP. +# Used for consistent schema in Arrow/Parquet (HuggingFace datasets) and for +# filtering corrupted entries during trajectory combination. +ALL_POSSIBLE_TOOLS = set(TOOL_TO_TOOLSET_MAP.keys()) + +# Default stats for tools that weren't used +DEFAULT_TOOL_STATS = {'count': 0, 'success': 0, 'failure': 0} + + +def _normalize_tool_stats(tool_stats: Dict[str, Dict[str, int]]) -> Dict[str, Dict[str, int]]: + """ + Normalize tool_stats to include all possible tools with consistent schema. + + This ensures HuggingFace datasets can load the JSONL without schema mismatch errors. + Tools that weren't used get zero counts. + + Args: + tool_stats (Dict): Raw tool statistics from extraction + + Returns: + Dict: Normalized tool statistics with all tools present + """ + normalized = {} + + # Add all possible tools with defaults + for tool in ALL_POSSIBLE_TOOLS: + if tool in tool_stats: + normalized[tool] = tool_stats[tool].copy() + else: + normalized[tool] = DEFAULT_TOOL_STATS.copy() + + # Also include any unexpected tools (in case new tools are added) + for tool, stats in tool_stats.items(): + if tool not in normalized: + normalized[tool] = stats.copy() + + return normalized + + +def _normalize_tool_error_counts(tool_error_counts: Dict[str, int]) -> Dict[str, int]: + """ + Normalize tool_error_counts to include all possible tools. + + Args: + tool_error_counts (Dict): Raw error counts mapping + + Returns: + Dict: Normalized error counts with all tools present + """ + normalized = {} + + # Add all possible tools with zero defaults + for tool in ALL_POSSIBLE_TOOLS: + normalized[tool] = tool_error_counts.get(tool, 0) + + # Also include any unexpected tools + for tool, count in tool_error_counts.items(): + if tool not in normalized: + normalized[tool] = count + + return normalized + + +def _extract_tool_stats(messages: List[Dict[str, Any]]) -> Dict[str, Dict[str, int]]: + """ + Extract tool usage statistics from message history. + + Args: + messages (List[Dict]): Message history + + Returns: + Dict: Tool statistics with counts and success/failure rates + """ + tool_stats = {} + + # Track tool calls and their results + tool_calls_map = {} # Map tool_call_id to tool name + + for msg in messages: + # Track tool calls from assistant messages + if msg["role"] == "assistant" and "tool_calls" in msg and msg["tool_calls"]: + for tool_call in msg["tool_calls"]: + if not tool_call or not isinstance(tool_call, dict): continue + tool_name = tool_call["function"]["name"] + tool_call_id = tool_call["id"] + + # Initialize stats for this tool if not exists + if tool_name not in tool_stats: + tool_stats[tool_name] = { + "count": 0, + "success": 0, + "failure": 0 + } + + tool_stats[tool_name]["count"] += 1 + tool_calls_map[tool_call_id] = tool_name + + # Track tool responses + elif msg["role"] == "tool": + tool_call_id = msg.get("tool_call_id", "") + content = msg.get("content", "") + + # Determine if tool call was successful + is_success = True + try: + # Try to parse as JSON and check for actual error values + content_json = json.loads(content) if isinstance(content, str) else content + + if isinstance(content_json, dict): + # Check if error field exists AND has a non-null value + if "error" in content_json and content_json["error"] is not None: + is_success = False + + # Special handling for terminal tool responses + # Terminal wraps its response in a "content" field + if "content" in content_json and isinstance(content_json["content"], dict): + inner_content = content_json["content"] + # Check for actual error (non-null error field) + # Note: non-zero exit codes are not failures - the model can self-correct + if inner_content.get("error") is not None: + is_success = False + + # Check for "success": false pattern used by some tools + if content_json.get("success") is False: + is_success = False + + except (json.JSONDecodeError, ValueError, TypeError): + # If not JSON, check if content is empty or explicitly states an error + # Note: We avoid simple substring matching to prevent false positives + if not content: + is_success = False + # Only mark as failure if it explicitly starts with "Error:" or "ERROR:" + elif content.strip().lower().startswith("error:"): + is_success = False + + # Update success/failure count + if tool_call_id in tool_calls_map: + tool_name = tool_calls_map[tool_call_id] + if is_success: + tool_stats[tool_name]["success"] += 1 + else: + tool_stats[tool_name]["failure"] += 1 + + return tool_stats + + +def _extract_reasoning_stats(messages: List[Dict[str, Any]]) -> Dict[str, int]: + """ + Count how many assistant turns have reasoning vs no reasoning. + + Checks for in content or a non-empty 'reasoning' field + (native thinking tokens). Returns counts for tracking reasoning coverage. + + Args: + messages: Message history + + Returns: + Dict with 'total_assistant_turns', 'turns_with_reasoning', 'turns_without_reasoning' + """ + total = 0 + with_reasoning = 0 + + for msg in messages: + if msg.get("role") != "assistant": + continue + total += 1 + + content = msg.get("content", "") or "" + has_scratchpad = "" in content + has_native_reasoning = bool(msg.get("reasoning", "").strip()) if msg.get("reasoning") else False + + if has_scratchpad or has_native_reasoning: + with_reasoning += 1 + + return { + "total_assistant_turns": total, + "turns_with_reasoning": with_reasoning, + "turns_without_reasoning": total - with_reasoning, + "has_any_reasoning": with_reasoning > 0, + } + + +def _process_single_prompt( + prompt_index: int, + prompt_data: Dict[str, Any], + batch_num: int, + config: Dict[str, Any] +) -> Dict[str, Any]: + """ + Process a single prompt with the agent. + + Args: + prompt_index (int): Index of prompt in dataset + prompt_data (Dict): Prompt data containing 'prompt' field and optional 'image' field + batch_num (int): Batch number + config (Dict): Configuration dict with agent parameters + + Returns: + Dict: Result containing trajectory, stats, and metadata + """ + prompt = prompt_data["prompt"] + task_id = f"task_{prompt_index}" + + # Per-prompt container image override: if the dataset row has an 'image' field, + # register it for this task's sandbox. Works with Docker, Modal, Singularity, and Daytona. + container_image = prompt_data.get("image") or prompt_data.get("docker_image") + if container_image: + # Verify the image is accessible before spending tokens on the agent loop. + # For Docker: check local cache, then try pulling. + # For Modal: skip local check (Modal pulls server-side). + env_type = os.getenv("TERMINAL_ENV", "local") + if env_type == "docker": + import subprocess as _sp + try: + probe = _sp.run( + ["docker", "image", "inspect", container_image], + capture_output=True, timeout=10, + ) + if probe.returncode != 0: + if config.get("verbose"): + print(f" Prompt {prompt_index}: Pulling docker image {container_image}...", flush=True) + pull = _sp.run( + ["docker", "pull", container_image], + capture_output=True, text=True, timeout=600, + ) + if pull.returncode != 0: + return { + "success": False, + "prompt_index": prompt_index, + "error": f"Docker image not available: {container_image}\n{pull.stderr[:500]}", + "trajectory": None, + "tool_stats": {}, + "toolsets_used": [], + "metadata": {"batch_num": batch_num, "timestamp": datetime.now().isoformat()}, + } + except FileNotFoundError: + pass # Docker CLI not installed — skip check (e.g., Modal backend) + except Exception as img_err: + if config.get("verbose"): + print(f" Prompt {prompt_index}: Docker image check failed: {img_err}", flush=True) + + from tools.terminal_tool import register_task_env_overrides + overrides = { + "docker_image": container_image, + "modal_image": container_image, + "singularity_image": f"docker://{container_image}", + "daytona_image": container_image, + } + if prompt_data.get("cwd"): + overrides["cwd"] = prompt_data["cwd"] + register_task_env_overrides(task_id, overrides) + if config.get("verbose"): + print(f" Prompt {prompt_index}: Using container image {container_image}") + + try: + # Sample toolsets from distribution for this prompt + selected_toolsets = sample_toolsets_from_distribution(config["distribution"]) + + if config.get("verbose"): + print(f" Prompt {prompt_index}: Using toolsets {selected_toolsets}") + + # Initialize agent with sampled toolsets and log prefix for identification + log_prefix = f"[B{batch_num}:P{prompt_index}]" + agent = AIAgent( + base_url=config.get("base_url"), + api_key=config.get("api_key"), + model=config["model"], + max_iterations=config["max_iterations"], + enabled_toolsets=selected_toolsets, + save_trajectories=False, # We handle saving ourselves + verbose_logging=config.get("verbose", False), + ephemeral_system_prompt=config.get("ephemeral_system_prompt"), + log_prefix_chars=config.get("log_prefix_chars", 100), + log_prefix=log_prefix, + providers_allowed=config.get("providers_allowed"), + providers_ignored=config.get("providers_ignored"), + providers_order=config.get("providers_order"), + provider_sort=config.get("provider_sort"), + max_tokens=config.get("max_tokens"), + reasoning_config=config.get("reasoning_config"), + prefill_messages=config.get("prefill_messages"), + skip_context_files=True, # Don't pollute trajectories with SOUL.md/AGENTS.md + skip_memory=True, # Don't use persistent memory in batch runs + ) + + # Run the agent with task_id to ensure each task gets its own isolated VM + result = agent.run_conversation(prompt, task_id=task_id) + + # Extract tool usage statistics + tool_stats = _extract_tool_stats(result["messages"]) + + # Extract reasoning coverage stats + reasoning_stats = _extract_reasoning_stats(result["messages"]) + + # Convert to trajectory format (using existing method) + trajectory = agent._convert_to_trajectory_format( + result["messages"], + prompt, + result["completed"] + ) + + return { + "success": True, + "prompt_index": prompt_index, + "trajectory": trajectory, + "tool_stats": tool_stats, + "reasoning_stats": reasoning_stats, + "completed": result["completed"], + "partial": result.get("partial", False), + "api_calls": result["api_calls"], + "toolsets_used": selected_toolsets, + "metadata": { + "batch_num": batch_num, + "timestamp": datetime.now().isoformat(), + "model": config["model"] + } + } + + except Exception as e: + print(f"❌ Error processing prompt {prompt_index}: {e}") + if config.get("verbose"): + traceback.print_exc() + + return { + "success": False, + "prompt_index": prompt_index, + "error": str(e), + "trajectory": None, + "tool_stats": {}, + "toolsets_used": [], + "metadata": { + "batch_num": batch_num, + "timestamp": datetime.now().isoformat() + } + } + + +def _process_batch_worker(args: Tuple) -> Dict[str, Any]: + """ + Worker function to process a single batch of prompts. + + Args: + args (Tuple): (batch_num, batch_data, output_dir, completed_prompts, config) + + Returns: + Dict: Batch results with statistics + """ + batch_num, batch_data, output_dir, completed_prompts_set, config = args + + output_dir = Path(output_dir) + print(f"\n🔄 Batch {batch_num}: Starting ({len(batch_data)} prompts)") + + # Output file for this batch + batch_output_file = output_dir / f"batch_{batch_num}.jsonl" + + # Filter out already completed prompts + prompts_to_process = [ + (idx, data) for idx, data in batch_data + if idx not in completed_prompts_set + ] + + if not prompts_to_process: + print(f"✅ Batch {batch_num}: Already completed (skipping)") + return { + "batch_num": batch_num, + "processed": 0, + "skipped": len(batch_data), + "tool_stats": {}, + "completed_prompts": [] + } + + print(f" Processing {len(prompts_to_process)} prompts (skipping {len(batch_data) - len(prompts_to_process)} already completed)") + + # Initialize aggregated stats for this batch + batch_tool_stats = {} + batch_reasoning_stats = {"total_assistant_turns": 0, "turns_with_reasoning": 0, "turns_without_reasoning": 0} + completed_in_batch = [] + discarded_no_reasoning = 0 + + # Process each prompt sequentially in this batch + for prompt_index, prompt_data in prompts_to_process: + # Process the prompt + result = _process_single_prompt( + prompt_index, + prompt_data, + batch_num, + config + ) + + # Save trajectory if successful + if result["success"] and result["trajectory"]: + # Discard samples with zero reasoning across all turns + reasoning = result.get("reasoning_stats", {}) + if not reasoning.get("has_any_reasoning", True): + print(f" 🚫 Prompt {prompt_index} discarded (no reasoning in any turn)") + discarded_no_reasoning += 1 + continue + + # Get and normalize tool stats for consistent schema across all entries + raw_tool_stats = result.get("tool_stats", {}) + tool_stats = _normalize_tool_stats(raw_tool_stats) + + # Create normalized tool_error_counts mapping tool names to their failure counts + raw_error_counts = { + tool_name: stats.get("failure", 0) + for tool_name, stats in raw_tool_stats.items() + } + tool_error_counts = _normalize_tool_error_counts(raw_error_counts) + + trajectory_entry = { + "prompt_index": prompt_index, + "conversations": result["trajectory"], + "metadata": result["metadata"], + "completed": result["completed"], + "partial": result.get("partial", False), # True if stopped due to invalid tool calls + "api_calls": result["api_calls"], + "toolsets_used": result["toolsets_used"], + "tool_stats": tool_stats, # Full stats: {tool: {count, success, failure}} - normalized + "tool_error_counts": tool_error_counts # Simple: {tool: failure_count} - normalized + } + + # Append to batch output file + with open(batch_output_file, 'a', encoding='utf-8') as f: + f.write(json.dumps(trajectory_entry, ensure_ascii=False) + "\n") + + # Aggregate tool statistics + for tool_name, stats in result.get("tool_stats", {}).items(): + if tool_name not in batch_tool_stats: + batch_tool_stats[tool_name] = { + "count": 0, + "success": 0, + "failure": 0 + } + + batch_tool_stats[tool_name]["count"] += stats["count"] + batch_tool_stats[tool_name]["success"] += stats["success"] + batch_tool_stats[tool_name]["failure"] += stats["failure"] + + # Aggregate reasoning stats + for key in batch_reasoning_stats: + batch_reasoning_stats[key] += result.get("reasoning_stats", {}).get(key, 0) + + # Only mark as completed if successfully saved (failed prompts can be retried on resume) + if result["success"] and result["trajectory"]: + completed_in_batch.append(prompt_index) + status = "⚠️ partial" if result.get("partial") else "✅" + print(f" {status} Prompt {prompt_index} completed") + else: + print(f" ❌ Prompt {prompt_index} failed (will retry on resume)") + + print(f"✅ Batch {batch_num}: Completed ({len(prompts_to_process)} prompts processed)") + + return { + "batch_num": batch_num, + "processed": len(prompts_to_process), + "skipped": len(batch_data) - len(prompts_to_process), + "tool_stats": batch_tool_stats, + "reasoning_stats": batch_reasoning_stats, + "discarded_no_reasoning": discarded_no_reasoning, + "completed_prompts": completed_in_batch + } + + +class BatchRunner: + """ + Manages batch processing of agent prompts with checkpointing and statistics. + """ + + def __init__( + self, + dataset_file: str, + batch_size: int, + run_name: str, + distribution: str = "default", + max_iterations: int = 10, + base_url: str = None, + api_key: str = None, + model: str = "claude-opus-4-20250514", + num_workers: int = 4, + verbose: bool = False, + ephemeral_system_prompt: str = None, + log_prefix_chars: int = 100, + providers_allowed: List[str] = None, + providers_ignored: List[str] = None, + providers_order: List[str] = None, + provider_sort: str = None, + max_tokens: int = None, + reasoning_config: Dict[str, Any] = None, + prefill_messages: List[Dict[str, Any]] = None, + max_samples: int = None, + ): + """ + Initialize the batch runner. + + Args: + dataset_file (str): Path to the dataset JSONL file with 'prompt' field + batch_size (int): Number of prompts per batch + run_name (str): Name for this run (used for checkpointing and output) + distribution (str): Toolset distribution to use (default: "default") + max_iterations (int): Max iterations per agent run + base_url (str): Base URL for model API + api_key (str): API key for model + model (str): Model name to use + num_workers (int): Number of parallel workers + verbose (bool): Enable verbose logging + ephemeral_system_prompt (str): System prompt used during agent execution but NOT saved to trajectories (optional) + log_prefix_chars (int): Number of characters to show in log previews for tool calls/responses (default: 20) + providers_allowed (List[str]): OpenRouter providers to allow (optional) + providers_ignored (List[str]): OpenRouter providers to ignore (optional) + providers_order (List[str]): OpenRouter providers to try in order (optional) + provider_sort (str): Sort providers by price/throughput/latency (optional) + max_tokens (int): Maximum tokens for model responses (optional, uses model default if not set) + reasoning_config (Dict): OpenRouter reasoning config override (e.g. {"effort": "none"} to disable thinking) + prefill_messages (List[Dict]): Messages to prepend as prefilled conversation context (few-shot priming) + max_samples (int): Only process the first N samples from the dataset (optional, processes all if not set) + """ + self.dataset_file = Path(dataset_file) + self.batch_size = batch_size + self.run_name = run_name + self.distribution = distribution + self.max_iterations = max_iterations + self.base_url = base_url + self.api_key = api_key + self.model = model + self.num_workers = num_workers + self.verbose = verbose + self.ephemeral_system_prompt = ephemeral_system_prompt + self.log_prefix_chars = log_prefix_chars + self.providers_allowed = providers_allowed + self.providers_ignored = providers_ignored + self.providers_order = providers_order + self.provider_sort = provider_sort + self.max_tokens = max_tokens + self.reasoning_config = reasoning_config + self.prefill_messages = prefill_messages + self.max_samples = max_samples + + # Validate distribution + if not validate_distribution(distribution): + raise ValueError(f"Unknown distribution: {distribution}. Available: {list(list_distributions().keys())}") + + # Setup output directory + self.output_dir = Path("data") / run_name + self.output_dir.mkdir(parents=True, exist_ok=True) + + # Checkpoint file + self.checkpoint_file = self.output_dir / "checkpoint.json" + + # Statistics file + self.stats_file = self.output_dir / "statistics.json" + + # Load dataset (and optionally truncate to max_samples) + self.dataset = self._load_dataset() + if self.max_samples and self.max_samples < len(self.dataset): + full_count = len(self.dataset) + self.dataset = self.dataset[:self.max_samples] + print(f"✂️ Truncated dataset from {full_count} to {self.max_samples} samples (--max_samples)") + + # Create batches + self.batches = self._create_batches() + + print("📊 Batch Runner Initialized") + print(f" Dataset: {self.dataset_file} ({len(self.dataset)} prompts)") + print(f" Batch size: {self.batch_size}") + print(f" Total batches: {len(self.batches)}") + print(f" Run name: {self.run_name}") + print(f" Distribution: {self.distribution}") + print(f" Output directory: {self.output_dir}") + print(f" Workers: {self.num_workers}") + if self.ephemeral_system_prompt: + prompt_preview = self.ephemeral_system_prompt[:60] + "..." if len(self.ephemeral_system_prompt) > 60 else self.ephemeral_system_prompt + print(f" 🔒 Ephemeral system prompt: '{prompt_preview}'") + + def _load_dataset(self) -> List[Dict[str, Any]]: + """ + Load dataset from JSONL file. + + Returns: + List[Dict]: List of dataset entries + """ + if not self.dataset_file.exists(): + raise FileNotFoundError(f"Dataset file not found: {self.dataset_file}") + + dataset = [] + with open(self.dataset_file, 'r', encoding='utf-8') as f: + for line_num, line in enumerate(f, 1): + line = line.strip() + if not line: + continue + + try: + entry = json.loads(line) + if 'prompt' not in entry: + print(f"⚠️ Warning: Line {line_num} missing 'prompt' field, skipping") + continue + dataset.append(entry) + except json.JSONDecodeError as e: + print(f"⚠️ Warning: Invalid JSON on line {line_num}: {e}") + continue + + if not dataset: + raise ValueError(f"No valid entries found in dataset file: {self.dataset_file}") + + return dataset + + def _create_batches(self) -> List[List[Tuple[int, Dict[str, Any]]]]: + """ + Split dataset into batches with indices. + + Returns: + List of batches, where each batch is a list of (index, entry) tuples + """ + batches = [] + for i in range(0, len(self.dataset), self.batch_size): + batch = [(idx, entry) for idx, entry in enumerate(self.dataset[i:i + self.batch_size], start=i)] + batches.append(batch) + + return batches + + def _load_checkpoint(self) -> Dict[str, Any]: + """ + Load checkpoint data if it exists. + + Returns: + Dict: Checkpoint data with completed prompt indices + """ + if not self.checkpoint_file.exists(): + return { + "run_name": self.run_name, + "completed_prompts": [], + "batch_stats": {}, + "last_updated": None + } + + try: + with open(self.checkpoint_file, 'r', encoding='utf-8') as f: + return json.load(f) + except Exception as e: + print(f"⚠️ Warning: Failed to load checkpoint: {e}") + return { + "run_name": self.run_name, + "completed_prompts": [], + "batch_stats": {}, + "last_updated": None + } + + def _save_checkpoint(self, checkpoint_data: Dict[str, Any], lock: Optional[Lock] = None): + """ + Save checkpoint data. + + Args: + checkpoint_data (Dict): Checkpoint data to save + lock (Lock): Optional lock for thread-safe access + """ + checkpoint_data["last_updated"] = datetime.now().isoformat() + + from utils import atomic_json_write + if lock: + with lock: + atomic_json_write(self.checkpoint_file, checkpoint_data) + else: + atomic_json_write(self.checkpoint_file, checkpoint_data) + + def _scan_completed_prompts_by_content(self) -> set: + """ + Scan all batch files and extract completed prompts by their actual content. + + This provides a more robust resume mechanism that matches on prompt text + rather than indices, allowing recovery even if indices don't match. + + Returns: + set: Set of prompt texts that have been successfully processed + """ + completed_prompts = set() + batch_files = sorted(self.output_dir.glob("batch_*.jsonl")) + + if not batch_files: + return completed_prompts + + print(f"📂 Scanning {len(batch_files)} batch files for completed prompts...") + + for batch_file in batch_files: + try: + with open(batch_file, 'r', encoding='utf-8') as f: + for line in f: + try: + entry = json.loads(line.strip()) + + # Skip failed entries - we want to retry these + if entry.get("failed", False): + continue + + # Extract the human/user prompt from conversations + conversations = entry.get("conversations", []) + for msg in conversations: + if msg.get("from") == "human": + prompt_text = msg.get("value", "").strip() + if prompt_text: + completed_prompts.add(prompt_text) + break # Only need the first human message + except json.JSONDecodeError: + continue + except Exception as e: + print(f" ⚠️ Warning: Error reading {batch_file.name}: {e}") + + return completed_prompts + + def _filter_dataset_by_completed(self, completed_prompts: set) -> Tuple[List[Dict], List[int]]: + """ + Filter the dataset to exclude prompts that have already been completed. + + Args: + completed_prompts: Set of prompt texts that have been completed + + Returns: + Tuple of (filtered_dataset, skipped_indices) + """ + filtered_dataset = [] + skipped_indices = [] + + for idx, entry in enumerate(self.dataset): + # Extract prompt from the dataset entry + prompt_text = entry.get("prompt", "").strip() + + # Also check conversations format + if not prompt_text: + conversations = entry.get("conversations", []) + for msg in conversations: + role = msg.get("role") or msg.get("from") + if role in ("user", "human"): + prompt_text = (msg.get("content") or msg.get("value", "")).strip() + break + + if prompt_text in completed_prompts: + skipped_indices.append(idx) + else: + # Keep original index for tracking + filtered_dataset.append((idx, entry)) + + return filtered_dataset, skipped_indices + + def run(self, resume: bool = False): + """ + Run the batch processing pipeline. + + Args: + resume (bool): Whether to resume from checkpoint + """ + print("\n" + "=" * 70) + print("🚀 Starting Batch Processing") + print("=" * 70) + + # Smart resume: scan batch files by content to find completed prompts + completed_prompt_texts = set() + if resume: + completed_prompt_texts = self._scan_completed_prompts_by_content() + if completed_prompt_texts: + print(f" Found {len(completed_prompt_texts)} already-completed prompts by content matching") + + # Filter dataset to only include unprocessed prompts + if resume and completed_prompt_texts: + filtered_entries, skipped_indices = self._filter_dataset_by_completed(completed_prompt_texts) + + if not filtered_entries: + print("\n✅ All prompts have already been processed!") + return + + # Recreate batches from filtered entries (keeping original indices for tracking) + batches_to_process = [] + for i in range(0, len(filtered_entries), self.batch_size): + batch = filtered_entries[i:i + self.batch_size] + batches_to_process.append(batch) + + self.batches = batches_to_process + + # Print prominent resume summary + print("\n" + "=" * 70) + print("📊 RESUME SUMMARY") + print("=" * 70) + print(f" Original dataset size: {len(self.dataset):,} prompts") + print(f" Already completed: {len(skipped_indices):,} prompts") + print(" ─────────────────────────────────────────") + print(f" 🎯 RESUMING WITH: {len(filtered_entries):,} prompts") + print(f" New batches created: {len(batches_to_process)}") + print("=" * 70 + "\n") + + # Load existing checkpoint (so resume doesn't clobber prior progress) + checkpoint_data = self._load_checkpoint() + if checkpoint_data.get("run_name") != self.run_name: + checkpoint_data = { + "run_name": self.run_name, + "completed_prompts": [], + "batch_stats": {}, + "last_updated": None + } + + # Prepare configuration for workers + config = { + "distribution": self.distribution, + "model": self.model, + "max_iterations": self.max_iterations, + "base_url": self.base_url, + "api_key": self.api_key, + "verbose": self.verbose, + "ephemeral_system_prompt": self.ephemeral_system_prompt, + "log_prefix_chars": self.log_prefix_chars, + "providers_allowed": self.providers_allowed, + "providers_ignored": self.providers_ignored, + "providers_order": self.providers_order, + "provider_sort": self.provider_sort, + "max_tokens": self.max_tokens, + "reasoning_config": self.reasoning_config, + "prefill_messages": self.prefill_messages, + } + + # For backward compatibility, still track by index (but this is secondary to content matching) + completed_prompts_set = set(checkpoint_data.get("completed_prompts", [])) + + # Aggregate statistics across all batches + total_tool_stats = {} + + start_time = time.time() + + print(f"\n🔧 Initializing {self.num_workers} worker processes...") + + # Checkpoint writes happen in the parent process; keep a lock for safety. + checkpoint_lock = Lock() + + # Process batches in parallel + with Pool(processes=self.num_workers) as pool: + # Create tasks for each batch + tasks = [ + ( + batch_num, + batch_data, + str(self.output_dir), # Convert Path to string for pickling + completed_prompts_set, + config + ) + for batch_num, batch_data in enumerate(self.batches) + ] + + print(f"✅ Created {len(tasks)} batch tasks") + print("🚀 Starting parallel batch processing...\n") + + # Use rich Progress for better visual tracking with persistent bottom bar + # redirect_stdout/stderr lets rich manage all output so progress bar stays clean + results = [] + console = Console(force_terminal=True) + with Progress( + SpinnerColumn(), + TextColumn("[bold blue]📦 Batches"), + BarColumn(bar_width=40), + MofNCompleteColumn(), + TextColumn("•"), + TimeRemainingColumn(), + console=console, + refresh_per_second=2, + transient=False, + redirect_stdout=False, + redirect_stderr=False, + ) as progress: + task = progress.add_task("Processing", total=len(tasks)) + + # Temporarily suppress DEBUG logging to avoid bar interference + root_logger = logging.getLogger() + original_level = root_logger.level + root_logger.setLevel(logging.WARNING) + + try: + for result in pool.imap_unordered(_process_batch_worker, tasks): + results.append(result) + progress.update(task, advance=1) + + # Incremental checkpoint update (so resume works after crash) + try: + batch_num = result.get('batch_num') + completed = result.get('completed_prompts', []) or [] + completed_prompts_set.update(completed) + + if isinstance(batch_num, int): + checkpoint_data.setdefault('batch_stats', {})[str(batch_num)] = { + 'processed': result.get('processed', 0), + 'skipped': result.get('skipped', 0), + 'discarded_no_reasoning': result.get('discarded_no_reasoning', 0), + } + + checkpoint_data['completed_prompts'] = sorted(completed_prompts_set) + self._save_checkpoint(checkpoint_data, lock=checkpoint_lock) + except Exception as ckpt_err: + # Don't fail the run if checkpoint write fails + print(f"⚠️ Warning: Failed to save incremental checkpoint: {ckpt_err}") + except Exception as e: + logger.error("Batch worker failed: %s", e, exc_info=True) + raise + finally: + root_logger.setLevel(original_level) + + # Aggregate all batch statistics and update checkpoint + all_completed_prompts = list(completed_prompts_set) + total_reasoning_stats = {"total_assistant_turns": 0, "turns_with_reasoning": 0, "turns_without_reasoning": 0} + + for batch_result in results: + # Add newly completed prompts + all_completed_prompts.extend(batch_result.get("completed_prompts", [])) + + # Aggregate tool stats + for tool_name, stats in batch_result.get("tool_stats", {}).items(): + if tool_name not in total_tool_stats: + total_tool_stats[tool_name] = { + "count": 0, + "success": 0, + "failure": 0 + } + + total_tool_stats[tool_name]["count"] += stats["count"] + total_tool_stats[tool_name]["success"] += stats["success"] + total_tool_stats[tool_name]["failure"] += stats["failure"] + + # Aggregate reasoning stats + for key in total_reasoning_stats: + total_reasoning_stats[key] += batch_result.get("reasoning_stats", {}).get(key, 0) + + # Save final checkpoint (best-effort; incremental writes already happened) + try: + checkpoint_data["completed_prompts"] = all_completed_prompts + self._save_checkpoint(checkpoint_data, lock=checkpoint_lock) + except Exception as ckpt_err: + print(f"⚠️ Warning: Failed to save final checkpoint: {ckpt_err}") + + # Calculate success rates + for tool_name in total_tool_stats: + stats = total_tool_stats[tool_name] + total_calls = stats["success"] + stats["failure"] + if total_calls > 0: + stats["success_rate"] = round(stats["success"] / total_calls * 100, 2) + stats["failure_rate"] = round(stats["failure"] / total_calls * 100, 2) + else: + stats["success_rate"] = 0.0 + stats["failure_rate"] = 0.0 + + # Combine ALL batch files in directory into a single trajectories.jsonl file + # This includes both old batches (from previous runs) and new batches (from resume) + # Also filter out corrupted entries (where model generated invalid tool names) + combined_file = self.output_dir / "trajectories.jsonl" + print(f"\n📦 Combining ALL batch files into {combined_file.name}...") + + # Valid tools auto-derived from model_tools.py — no manual updates needed + VALID_TOOLS = ALL_POSSIBLE_TOOLS + + total_entries = 0 + filtered_entries = 0 + batch_files_found = 0 + + # Find ALL batch files in the output directory (handles resume merging old + new) + all_batch_files = sorted(self.output_dir.glob("batch_*.jsonl")) + + with open(combined_file, 'w', encoding='utf-8') as outfile: + for batch_file in all_batch_files: + batch_files_found += 1 + batch_num = batch_file.stem.split("_")[1] # Extract batch number for logging + + with open(batch_file, 'r', encoding='utf-8') as infile: + for line in infile: + total_entries += 1 + try: + data = json.loads(line) + tool_stats = data.get('tool_stats', {}) + + # Check for invalid tool names (model hallucinations) + invalid_tools = [k for k in tool_stats if k not in VALID_TOOLS] + + if invalid_tools: + filtered_entries += 1 + invalid_preview = invalid_tools[0][:50] + "..." if len(invalid_tools[0]) > 50 else invalid_tools[0] + print(f" ⚠️ Filtering corrupted entry (batch {batch_num}): invalid tool '{invalid_preview}'") + continue + + outfile.write(line) + except json.JSONDecodeError: + filtered_entries += 1 + print(f" ⚠️ Filtering invalid JSON entry (batch {batch_num})") + + if filtered_entries > 0: + print(f"⚠️ Filtered {filtered_entries} corrupted entries out of {total_entries} total") + print(f"✅ Combined {batch_files_found} batch files into trajectories.jsonl ({total_entries - filtered_entries} entries)") + + # Save final statistics + final_stats = { + "run_name": self.run_name, + "distribution": self.distribution, + "total_prompts": len(self.dataset), + "total_batches": len(self.batches), + "batch_size": self.batch_size, + "model": self.model, + "completed_at": datetime.now().isoformat(), + "duration_seconds": round(time.time() - start_time, 2), + "tool_statistics": total_tool_stats, + "reasoning_statistics": total_reasoning_stats, + } + + with open(self.stats_file, 'w', encoding='utf-8') as f: + json.dump(final_stats, f, indent=2, ensure_ascii=False) + + # Print summary + print("\n" + "=" * 70) + print("📊 BATCH PROCESSING COMPLETE") + print("=" * 70) + print(f"✅ Prompts processed this run: {sum(r.get('processed', 0) for r in results)}") + print(f"✅ Total trajectories in merged file: {total_entries - filtered_entries}") + print(f"✅ Total batch files merged: {batch_files_found}") + print(f"⏱️ Total duration: {round(time.time() - start_time, 2)}s") + print("\n📈 Tool Usage Statistics:") + print("-" * 70) + + if total_tool_stats: + # Sort by count descending + sorted_tools = sorted( + total_tool_stats.items(), + key=lambda x: x[1]["count"], + reverse=True + ) + + print(f"{'Tool Name':<25} {'Count':<10} {'Success':<10} {'Failure':<10} {'Success Rate':<12}") + print("-" * 70) + for tool_name, stats in sorted_tools: + print( + f"{tool_name:<25} " + f"{stats['count']:<10} " + f"{stats['success']:<10} " + f"{stats['failure']:<10} " + f"{stats['success_rate']:.1f}%" + ) + else: + print("No tool calls were made during this run.") + + # Print reasoning coverage stats + total_discarded = sum(r.get("discarded_no_reasoning", 0) for r in results) + + print("\n🧠 Reasoning Coverage:") + print("-" * 70) + total_turns = total_reasoning_stats["total_assistant_turns"] + with_reasoning = total_reasoning_stats["turns_with_reasoning"] + without_reasoning = total_reasoning_stats["turns_without_reasoning"] + if total_turns > 0: + pct_with = round(with_reasoning / total_turns * 100, 1) + pct_without = round(without_reasoning / total_turns * 100, 1) + print(f" Total assistant turns: {total_turns:,}") + print(f" With reasoning: {with_reasoning:,} ({pct_with}%)") + print(f" Without reasoning: {without_reasoning:,} ({pct_without}%)") + else: + print(" No assistant turns recorded.") + if total_discarded > 0: + print(f" 🚫 Samples discarded (zero reasoning): {total_discarded:,}") + + print(f"\n💾 Results saved to: {self.output_dir}") + print(" - Trajectories: trajectories.jsonl (combined)") + print(" - Individual batches: batch_*.jsonl (for debugging)") + print(f" - Statistics: {self.stats_file.name}") + print(f" - Checkpoint: {self.checkpoint_file.name}") + + +def main( + dataset_file: str = None, + batch_size: int = None, + run_name: str = None, + distribution: str = "default", + model: str = "anthropic/claude-sonnet-4.6", + api_key: str = None, + base_url: str = "https://openrouter.ai/api/v1", + max_turns: int = 10, + num_workers: int = 4, + resume: bool = False, + verbose: bool = False, + list_distributions: bool = False, + ephemeral_system_prompt: str = None, + log_prefix_chars: int = 100, + providers_allowed: str = None, + providers_ignored: str = None, + providers_order: str = None, + provider_sort: str = None, + max_tokens: int = None, + reasoning_effort: str = None, + reasoning_disabled: bool = False, + prefill_messages_file: str = None, + max_samples: int = None, +): + """ + Run batch processing of agent prompts from a dataset. + + Args: + dataset_file (str): Path to JSONL file with 'prompt' field in each entry + batch_size (int): Number of prompts per batch + run_name (str): Name for this run (used for output and checkpointing) + distribution (str): Toolset distribution to use (default: "default") + model (str): Model name to use (default: "claude-opus-4-20250514") + api_key (str): API key for model authentication + base_url (str): Base URL for model API + max_turns (int): Maximum number of tool calling iterations per prompt (default: 10) + num_workers (int): Number of parallel worker processes (default: 4) + resume (bool): Resume from checkpoint if run was interrupted (default: False) + verbose (bool): Enable verbose logging (default: False) + list_distributions (bool): List available toolset distributions and exit + ephemeral_system_prompt (str): System prompt used during agent execution but NOT saved to trajectories (optional) + log_prefix_chars (int): Number of characters to show in log previews for tool calls/responses (default: 20) + providers_allowed (str): Comma-separated list of OpenRouter providers to allow (e.g. "anthropic,openai") + providers_ignored (str): Comma-separated list of OpenRouter providers to ignore (e.g. "together,deepinfra") + providers_order (str): Comma-separated list of OpenRouter providers to try in order (e.g. "anthropic,openai,google") + provider_sort (str): Sort providers by "price", "throughput", or "latency" (OpenRouter only) + max_tokens (int): Maximum tokens for model responses (optional, uses model default if not set) + reasoning_effort (str): OpenRouter reasoning effort level: "none", "minimal", "low", "medium", "high", "xhigh" (default: "medium") + reasoning_disabled (bool): Completely disable reasoning/thinking tokens (default: False) + prefill_messages_file (str): Path to JSON file containing prefill messages (list of {role, content} dicts) + max_samples (int): Only process the first N samples from the dataset (optional, processes all if not set) + + Examples: + # Basic usage + python batch_runner.py --dataset_file=data.jsonl --batch_size=10 --run_name=my_run + + # Resume interrupted run + python batch_runner.py --dataset_file=data.jsonl --batch_size=10 --run_name=my_run --resume + + # Use specific distribution + python batch_runner.py --dataset_file=data.jsonl --batch_size=10 --run_name=image_test --distribution=image_gen + + # With disabled reasoning and max tokens + python batch_runner.py --dataset_file=data.jsonl --batch_size=10 --run_name=my_run \\ + --reasoning_disabled --max_tokens=128000 + + # With prefill messages from file + python batch_runner.py --dataset_file=data.jsonl --batch_size=10 --run_name=my_run \\ + --prefill_messages_file=configs/prefill_opus.json + + # List available distributions + python batch_runner.py --list_distributions + """ + # Handle list distributions + if list_distributions: + from toolset_distributions import list_distributions as get_all_dists, print_distribution_info + + print("📊 Available Toolset Distributions") + print("=" * 70) + + all_dists = get_all_dists() + for dist_name in sorted(all_dists.keys()): + print_distribution_info(dist_name) + + print("\n💡 Usage:") + print(" python batch_runner.py --dataset_file=data.jsonl --batch_size=10 \\") + print(" --run_name=my_run --distribution=") + return + + # Validate required arguments + if not dataset_file: + print("❌ Error: --dataset_file is required") + return + + if not batch_size or batch_size < 1: + print("❌ Error: --batch_size must be a positive integer") + return + + if not run_name: + print("❌ Error: --run_name is required") + return + + # Parse provider preferences (comma-separated strings to lists) + providers_allowed_list = [p.strip() for p in providers_allowed.split(",")] if providers_allowed else None + providers_ignored_list = [p.strip() for p in providers_ignored.split(",")] if providers_ignored else None + providers_order_list = [p.strip() for p in providers_order.split(",")] if providers_order else None + + # Build reasoning_config from CLI flags + # --reasoning_disabled takes priority, then --reasoning_effort, then default (medium) + reasoning_config = None + if reasoning_disabled: + # Completely disable reasoning/thinking tokens + reasoning_config = {"effort": "none"} + print("🧠 Reasoning: DISABLED (effort=none)") + elif reasoning_effort: + # Use specified effort level + valid_efforts = ["none", "minimal", "low", "medium", "high", "xhigh"] + if reasoning_effort not in valid_efforts: + print(f"❌ Error: --reasoning_effort must be one of: {', '.join(valid_efforts)}") + return + reasoning_config = {"enabled": True, "effort": reasoning_effort} + print(f"🧠 Reasoning effort: {reasoning_effort}") + + # Load prefill messages from JSON file if provided + prefill_messages = None + if prefill_messages_file: + try: + with open(prefill_messages_file, 'r', encoding='utf-8') as f: + prefill_messages = json.load(f) + if not isinstance(prefill_messages, list): + print("❌ Error: prefill_messages_file must contain a JSON array of messages") + return + print(f"💬 Loaded {len(prefill_messages)} prefill messages from {prefill_messages_file}") + except Exception as e: + print(f"❌ Error loading prefill messages: {e}") + return + + # Initialize and run batch runner + try: + runner = BatchRunner( + dataset_file=dataset_file, + batch_size=batch_size, + run_name=run_name, + distribution=distribution, + max_iterations=max_turns, + base_url=base_url, + api_key=api_key, + model=model, + num_workers=num_workers, + verbose=verbose, + ephemeral_system_prompt=ephemeral_system_prompt, + log_prefix_chars=log_prefix_chars, + providers_allowed=providers_allowed_list, + providers_ignored=providers_ignored_list, + providers_order=providers_order_list, + provider_sort=provider_sort, + max_tokens=max_tokens, + reasoning_config=reasoning_config, + prefill_messages=prefill_messages, + max_samples=max_samples, + ) + + runner.run(resume=resume) + + except Exception as e: + print(f"\n❌ Fatal error: {e}") + if verbose: + traceback.print_exc() + return 1 + + +if __name__ == "__main__": + fire.Fire(main) + diff --git a/mindcli/_vendor/cli.py b/mindcli/_vendor/cli.py new file mode 100644 index 0000000..970c98b --- /dev/null +++ b/mindcli/_vendor/cli.py @@ -0,0 +1,10017 @@ +#!/usr/bin/env python3 +""" +Hermes Agent CLI - Interactive Terminal Interface + +A beautiful command-line interface for the Hermes Agent, inspired by Claude Code. +Features ASCII art branding, interactive REPL, toolset selection, and rich formatting. + +Usage: + python cli.py # Start interactive mode with all tools + python cli.py --toolsets web,terminal # Start with specific toolsets + python cli.py --skills hermes-agent-dev,github-auth + python cli.py -q "your question" # Single query mode + python cli.py --list-tools # List available tools and exit +""" + +import logging +import os +import shutil +import sys +import json +import atexit +import tempfile +import time +import uuid +import textwrap +from contextlib import contextmanager +from pathlib import Path +from datetime import datetime +from typing import List, Dict, Any, Optional + +logger = logging.getLogger(__name__) + +# Suppress startup messages for clean CLI experience +os.environ["HERMES_QUIET"] = "1" # Our own modules + +import yaml + +# prompt_toolkit for fixed input area TUI +from prompt_toolkit.history import FileHistory +from prompt_toolkit.styles import Style as PTStyle +from prompt_toolkit.patch_stdout import patch_stdout +from prompt_toolkit.application import Application +from prompt_toolkit.layout import Layout, HSplit, Window, FormattedTextControl, ConditionalContainer +from prompt_toolkit.layout.processors import Processor, Transformation, PasswordProcessor, ConditionalProcessor +from prompt_toolkit.filters import Condition +from prompt_toolkit.layout.dimension import Dimension +from prompt_toolkit.layout.menus import CompletionsMenu +from prompt_toolkit.widgets import TextArea +from prompt_toolkit.key_binding import KeyBindings +from prompt_toolkit import print_formatted_text as _pt_print +from prompt_toolkit.formatted_text import ANSI as _PT_ANSI +try: + from prompt_toolkit.cursor_shapes import CursorShape + _STEADY_CURSOR = CursorShape.BLOCK # Non-blinking block cursor +except (ImportError, AttributeError): + _STEADY_CURSOR = None +import threading +import queue + +from agent.usage_pricing import ( + CanonicalUsage, + estimate_usage_cost, + format_duration_compact, + format_token_count_compact, +) +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 +from hermes_cli.env_loader import load_hermes_dotenv + +_hermes_home = get_hermes_home() +_project_env = Path(__file__).parent / '.env' +load_hermes_dotenv(hermes_home=_hermes_home, project_env=_project_env) + + +# ============================================================================= +# Configuration Loading +# ============================================================================= + +def _load_prefill_messages(file_path: str) -> List[Dict[str, Any]]: + """Load ephemeral prefill messages from a JSON file. + + The file should contain a JSON array of {role, content} dicts, e.g.: + [{"role": "user", "content": "Hi"}, {"role": "assistant", "content": "Hello!"}] + + Relative paths are resolved from ~/.hermes/. + Returns an empty list if the path is empty or the file doesn't exist. + """ + if not file_path: + return [] + path = Path(file_path).expanduser() + if not path.is_absolute(): + path = _hermes_home / path + if not path.exists(): + logger.warning("Prefill messages file not found: %s", path) + return [] + try: + with open(path, "r", encoding="utf-8") as f: + data = json.load(f) + if not isinstance(data, list): + logger.warning("Prefill messages file must contain a JSON array: %s", path) + return [] + return data + except Exception as e: + logger.warning("Failed to load prefill messages from %s: %s", path, e) + return [] + + +def _parse_reasoning_config(effort: str) -> dict | None: + """Parse a reasoning effort level into an OpenRouter reasoning config dict.""" + from hermes_constants import parse_reasoning_effort + result = parse_reasoning_effort(effort) + if effort and effort.strip() and result is None: + logger.warning("Unknown reasoning_effort '%s', using default (medium)", effort) + return result + + +def _parse_service_tier_config(raw: str) -> str | None: + """Parse a persisted service-tier preference into a Responses API value.""" + value = str(raw or "").strip().lower() + if not value or value in {"normal", "default", "standard", "off", "none"}: + return None + if value in {"fast", "priority", "on"}: + return "priority" + logger.warning("Unknown service_tier '%s', ignoring", raw) + return None + + + +def _get_chrome_debug_candidates(system: str) -> list[str]: + """Return likely browser executables for local CDP auto-launch.""" + candidates: list[str] = [] + seen: set[str] = set() + + def _add_candidate(path: str | None) -> None: + if not path: + return + normalized = os.path.normcase(os.path.normpath(path)) + if normalized in seen: + return + if os.path.isfile(path): + candidates.append(path) + seen.add(normalized) + + def _add_from_path(*names: str) -> None: + for name in names: + _add_candidate(shutil.which(name)) + + if system == "Darwin": + for app in ( + "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", + "/Applications/Chromium.app/Contents/MacOS/Chromium", + "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser", + "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge", + ): + _add_candidate(app) + elif system == "Windows": + _add_from_path( + "chrome.exe", "msedge.exe", "brave.exe", "chromium.exe", + "chrome", "msedge", "brave", "chromium", + ) + + for base in ( + os.environ.get("ProgramFiles"), + os.environ.get("ProgramFiles(x86)"), + os.environ.get("LOCALAPPDATA"), + ): + if not base: + continue + for parts in ( + ("Google", "Chrome", "Application", "chrome.exe"), + ("Chromium", "Application", "chrome.exe"), + ("Chromium", "Application", "chromium.exe"), + ("BraveSoftware", "Brave-Browser", "Application", "brave.exe"), + ("Microsoft", "Edge", "Application", "msedge.exe"), + ): + _add_candidate(os.path.join(base, *parts)) + else: + _add_from_path( + "google-chrome", "google-chrome-stable", "chromium-browser", + "chromium", "brave-browser", "microsoft-edge", + ) + + return candidates + + +def load_cli_config() -> Dict[str, Any]: + """ + Load CLI configuration from config files. + + Config lookup order: + 1. ~/.hermes/config.yaml (user config - preferred) + 2. ./cli-config.yaml (project config - fallback) + + Environment variables take precedence over config file values. + Returns default values if no config file exists. + """ + # Check user config first ({HERMES_HOME}/config.yaml) + user_config_path = _hermes_home / 'config.yaml' + project_config_path = Path(__file__).parent / 'cli-config.yaml' + + # Use user config if it exists, otherwise project config + if user_config_path.exists(): + config_path = user_config_path + else: + config_path = project_config_path + + # Default configuration + defaults = { + "model": { + "default": "", + "base_url": "", + "provider": "auto", + }, + "terminal": { + "env_type": "local", + "cwd": ".", # "." is resolved to os.getcwd() at runtime + "timeout": 60, + "lifetime_seconds": 300, + "docker_image": "nikolaik/python-nodejs:python3.11-nodejs20", + "docker_forward_env": [], + "singularity_image": "docker://nikolaik/python-nodejs:python3.11-nodejs20", + "modal_image": "nikolaik/python-nodejs:python3.11-nodejs20", + "daytona_image": "nikolaik/python-nodejs:python3.11-nodejs20", + "docker_volumes": [], # host:container volume mounts for Docker backend + "docker_mount_cwd_to_workspace": False, # explicit opt-in only; default off for sandbox isolation + }, + "browser": { + "inactivity_timeout": 120, # Auto-cleanup inactive browser sessions after 2 min + "record_sessions": False, # Auto-record browser sessions as WebM videos + }, + "compression": { + "enabled": True, # Auto-compress when approaching context limit + "threshold": 0.50, # Compress at 50% of model's context limit + }, + "smart_model_routing": { + "enabled": False, + "max_simple_chars": 160, + "max_simple_words": 28, + "cheap_model": {}, + }, + "agent": { + "max_turns": 90, # Default max tool-calling iterations (shared with subagents) + "verbose": False, + "system_prompt": "", + "prefill_messages_file": "", + "reasoning_effort": "", + "service_tier": "", + "personalities": { + "helpful": "You are a helpful, friendly AI assistant.", + "concise": "You are a concise assistant. Keep responses brief and to the point.", + "technical": "You are a technical expert. Provide detailed, accurate technical information.", + "creative": "You are a creative assistant. Think outside the box and offer innovative solutions.", + "teacher": "You are a patient teacher. Explain concepts clearly with examples.", + "kawaii": "You are a kawaii assistant! Use cute expressions like (◕‿◕), ★, ♪, and ~! Add sparkles and be super enthusiastic about everything! Every response should feel warm and adorable desu~! ヽ(>∀<☆)ノ", + "catgirl": "You are Neko-chan, an anime catgirl AI assistant, nya~! Add 'nya' and cat-like expressions to your speech. Use kaomoji like (=^･ω･^=) and ฅ^•ﻌ•^ฅ. Be playful and curious like a cat, nya~!", + "pirate": "Arrr! Ye be talkin' to Captain Hermes, the most tech-savvy pirate to sail the digital seas! Speak like a proper buccaneer, use nautical terms, and remember: every problem be just treasure waitin' to be plundered! Yo ho ho!", + "shakespeare": "Hark! Thou speakest with an assistant most versed in the bardic arts. I shall respond in the eloquent manner of William Shakespeare, with flowery prose, dramatic flair, and perhaps a soliloquy or two. What light through yonder terminal breaks?", + "surfer": "Duuude! You're chatting with the chillest AI on the web, bro! Everything's gonna be totally rad. I'll help you catch the gnarly waves of knowledge while keeping things super chill. Cowabunga!", + "noir": "The rain hammered against the terminal like regrets on a guilty conscience. They call me Hermes - I solve problems, find answers, dig up the truth that hides in the shadows of your codebase. In this city of silicon and secrets, everyone's got something to hide. What's your story, pal?", + "uwu": "hewwo! i'm your fwiendwy assistant uwu~ i wiww twy my best to hewp you! *nuzzles your code* OwO what's this? wet me take a wook! i pwomise to be vewy hewpful >w<", + "philosopher": "Greetings, seeker of wisdom. I am an assistant who contemplates the deeper meaning behind every query. Let us examine not just the 'how' but the 'why' of your questions. Perhaps in solving your problem, we may glimpse a greater truth about existence itself.", + "hype": "YOOO LET'S GOOOO!!! I am SO PUMPED to help you today! Every question is AMAZING and we're gonna CRUSH IT together! This is gonna be LEGENDARY! ARE YOU READY?! LET'S DO THIS!", + }, + }, + + "display": { + "compact": False, + "resume_display": "full", + "show_reasoning": False, + "streaming": True, + "busy_input_mode": "interrupt", + + "skin": "default", + }, + "clarify": { + "timeout": 120, # Seconds to wait for a clarify answer before auto-proceeding + }, + "code_execution": { + "timeout": 300, # Max seconds a sandbox script can run before being killed (5 min) + "max_tool_calls": 50, # Max RPC tool calls per execution + }, + "auxiliary": { + "vision": { + "provider": "auto", + "model": "", + "base_url": "", + "api_key": "", + }, + "web_extract": { + "provider": "auto", + "model": "", + "base_url": "", + "api_key": "", + }, + }, + "delegation": { + "max_iterations": 45, # Max tool-calling turns per child agent + "default_toolsets": ["terminal", "file", "web"], # Default toolsets for subagents + "model": "", # Subagent model override (empty = inherit parent model) + "provider": "", # Subagent provider override (empty = inherit parent provider) + "base_url": "", # Direct OpenAI-compatible endpoint for subagents + "api_key": "", # API key for delegation.base_url (falls back to OPENAI_API_KEY) + }, + } + + # Track whether the config file explicitly set terminal config. + # When using defaults (no config file / no terminal section), we should NOT + # overwrite env vars that were already set by .env -- only a user's config + # file should be authoritative. + _file_has_terminal_config = False + + # Load from file if exists + if config_path.exists(): + try: + with open(config_path, "r", encoding="utf-8") as f: + file_config = yaml.safe_load(f) or {} + + _file_has_terminal_config = "terminal" in file_config + + # Handle model config - can be string (new format) or dict (old format) + if "model" in file_config: + if isinstance(file_config["model"], str): + # New format: model is just a string, convert to dict structure + defaults["model"]["default"] = file_config["model"] + elif isinstance(file_config["model"], dict): + # Old format: model is a dict with default/base_url + defaults["model"].update(file_config["model"]) + # If the user config sets model.model but not model.default, + # promote model.model to model.default so the user's explicit + # choice isn't shadowed by the hardcoded default. Without this, + # profile configs that only set "model:" (not "default:") silently + # fall back to claude-opus because the merge preserves the + # hardcoded default and HermesCLI.__init__ checks "default" first. + if "model" in file_config["model"] and "default" not in file_config["model"]: + defaults["model"]["default"] = file_config["model"]["model"] + + # Legacy root-level provider/base_url fallback. + # Some users (or old code) put provider: / base_url: at the + # config root instead of inside the model: section. These are + # only used as a FALLBACK when model.provider / model.base_url + # is not already set — never as an override. The canonical + # location is model.provider (written by `hermes model`). + if not defaults["model"].get("provider"): + root_provider = file_config.get("provider") + if root_provider: + defaults["model"]["provider"] = root_provider + if not defaults["model"].get("base_url"): + root_base_url = file_config.get("base_url") + if root_base_url: + defaults["model"]["base_url"] = root_base_url + + # Deep merge file_config into defaults. + # First: merge keys that exist in both (deep-merge dicts, overwrite scalars) + for key in defaults: + if key == "model": + continue # Already handled above + if key in file_config: + if isinstance(defaults[key], dict) and isinstance(file_config[key], dict): + defaults[key].update(file_config[key]) + else: + defaults[key] = file_config[key] + + # Second: carry over keys from file_config that aren't in defaults + # (e.g. platform_toolsets, provider_routing, memory, honcho, etc.) + for key in file_config: + if key not in defaults and key != "model": + defaults[key] = file_config[key] + + # Handle legacy root-level max_turns (backwards compat) - copy to + # agent.max_turns whenever the nested key is missing. + agent_file_config = file_config.get("agent") + if "max_turns" in file_config and not ( + isinstance(agent_file_config, dict) + and agent_file_config.get("max_turns") is not None + ): + defaults["agent"]["max_turns"] = file_config["max_turns"] + except Exception as e: + logger.warning("Failed to load cli-config.yaml: %s", e) + + # Expand ${ENV_VAR} references in config values before bridging to env vars. + from hermes_cli.config import _expand_env_vars + defaults = _expand_env_vars(defaults) + + # Apply terminal config to environment variables (so terminal_tool picks them up) + terminal_config = defaults.get("terminal", {}) + + # Normalize config key: the new config system (hermes_cli/config.py) and all + # documentation use "backend", the legacy cli-config.yaml uses "env_type". + # Accept both, with "backend" taking precedence (it's the documented key). + if "backend" in terminal_config: + terminal_config["env_type"] = terminal_config["backend"] + + # Handle special cwd values: "." or "auto" means use current working directory. + # Only resolve to the host's CWD for the local backend where the host + # filesystem is directly accessible. For ALL remote/container backends + # (ssh, docker, modal, singularity), the host path doesn't exist on the + # target -- remove the key so terminal_tool.py uses its per-backend default. + if terminal_config.get("cwd") in (".", "auto", "cwd"): + effective_backend = terminal_config.get("env_type", "local") + if effective_backend == "local": + terminal_config["cwd"] = os.getcwd() + defaults["terminal"]["cwd"] = terminal_config["cwd"] + else: + # Remove so TERMINAL_CWD stays unset → tool picks backend default + terminal_config.pop("cwd", None) + + env_mappings = { + "env_type": "TERMINAL_ENV", + "cwd": "TERMINAL_CWD", + "timeout": "TERMINAL_TIMEOUT", + "lifetime_seconds": "TERMINAL_LIFETIME_SECONDS", + "docker_image": "TERMINAL_DOCKER_IMAGE", + "docker_forward_env": "TERMINAL_DOCKER_FORWARD_ENV", + "singularity_image": "TERMINAL_SINGULARITY_IMAGE", + "modal_image": "TERMINAL_MODAL_IMAGE", + "daytona_image": "TERMINAL_DAYTONA_IMAGE", + # SSH config + "ssh_host": "TERMINAL_SSH_HOST", + "ssh_user": "TERMINAL_SSH_USER", + "ssh_port": "TERMINAL_SSH_PORT", + "ssh_key": "TERMINAL_SSH_KEY", + # Container resource config (docker, singularity, modal, daytona -- ignored for local/ssh) + "container_cpu": "TERMINAL_CONTAINER_CPU", + "container_memory": "TERMINAL_CONTAINER_MEMORY", + "container_disk": "TERMINAL_CONTAINER_DISK", + "container_persistent": "TERMINAL_CONTAINER_PERSISTENT", + "docker_volumes": "TERMINAL_DOCKER_VOLUMES", + "docker_mount_cwd_to_workspace": "TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE", + "sandbox_dir": "TERMINAL_SANDBOX_DIR", + # Persistent shell (non-local backends) + "persistent_shell": "TERMINAL_PERSISTENT_SHELL", + # Sudo support (works with all backends) + "sudo_password": "SUDO_PASSWORD", + } + + # Apply config values to env vars so terminal_tool picks them up. + # If the config file explicitly has a [terminal] section, those values are + # authoritative and override any .env settings. When using defaults only + # (no config file or no terminal section), don't overwrite env vars that + # were already set by .env -- the user's .env is the fallback source. + for config_key, env_var in env_mappings.items(): + if config_key in terminal_config: + if _file_has_terminal_config or env_var not in os.environ: + val = terminal_config[config_key] + if isinstance(val, list): + import json + os.environ[env_var] = json.dumps(val) + else: + os.environ[env_var] = str(val) + + # Apply browser config to environment variables + browser_config = defaults.get("browser", {}) + browser_env_mappings = { + "inactivity_timeout": "BROWSER_INACTIVITY_TIMEOUT", + } + + for config_key, env_var in browser_env_mappings.items(): + if config_key in browser_config: + os.environ[env_var] = str(browser_config[config_key]) + + # Apply auxiliary model/direct-endpoint overrides to environment variables. + # Vision and web_extract each have their own provider/model/base_url/api_key tuple. + # Compression config is read directly from config.yaml by run_agent.py and + # auxiliary_client.py — no env var bridging needed. + # Only set env vars for non-empty / non-default values so auto-detection + # still works. + auxiliary_config = defaults.get("auxiliary", {}) + auxiliary_task_env = { + # config key → env var mapping + "vision": { + "provider": "AUXILIARY_VISION_PROVIDER", + "model": "AUXILIARY_VISION_MODEL", + "base_url": "AUXILIARY_VISION_BASE_URL", + "api_key": "AUXILIARY_VISION_API_KEY", + }, + "web_extract": { + "provider": "AUXILIARY_WEB_EXTRACT_PROVIDER", + "model": "AUXILIARY_WEB_EXTRACT_MODEL", + "base_url": "AUXILIARY_WEB_EXTRACT_BASE_URL", + "api_key": "AUXILIARY_WEB_EXTRACT_API_KEY", + }, + "approval": { + "provider": "AUXILIARY_APPROVAL_PROVIDER", + "model": "AUXILIARY_APPROVAL_MODEL", + "base_url": "AUXILIARY_APPROVAL_BASE_URL", + "api_key": "AUXILIARY_APPROVAL_API_KEY", + }, + } + + for task_key, env_map in auxiliary_task_env.items(): + task_cfg = auxiliary_config.get(task_key, {}) + if not isinstance(task_cfg, dict): + continue + prov = str(task_cfg.get("provider", "")).strip() + model = str(task_cfg.get("model", "")).strip() + base_url = str(task_cfg.get("base_url", "")).strip() + api_key = str(task_cfg.get("api_key", "")).strip() + if prov and prov != "auto": + os.environ[env_map["provider"]] = prov + if model: + os.environ[env_map["model"]] = model + if base_url: + os.environ[env_map["base_url"]] = base_url + if api_key: + os.environ[env_map["api_key"]] = api_key + + # Security settings + security_config = defaults.get("security", {}) + if isinstance(security_config, dict): + redact = security_config.get("redact_secrets") + if redact is not None: + os.environ["HERMES_REDACT_SECRETS"] = str(redact).lower() + + return defaults + +# Load configuration at module startup +CLI_CONFIG = load_cli_config() + +# Initialize centralized logging early — agent.log + errors.log in ~/.hermes/logs/. +# This ensures CLI sessions produce a log trail even before AIAgent is instantiated. +try: + from hermes_logging import setup_logging + setup_logging(mode="cli") +except Exception: + pass # Logging setup is best-effort — don't crash the CLI + +# Validate config structure early — print warnings before user hits cryptic errors +try: + from hermes_cli.config import print_config_warnings + print_config_warnings() +except Exception: + pass + +# Initialize the skin engine from config +try: + from hermes_cli.skin_engine import init_skin_from_config + init_skin_from_config(CLI_CONFIG) +except Exception: + pass # Skin engine is optional — default skin used if unavailable + +# Initialize tool preview length from config +try: + from agent.display import set_tool_preview_max_len + _tpl = CLI_CONFIG.get("display", {}).get("tool_preview_length", 0) + set_tool_preview_max_len(int(_tpl) if _tpl else 0) +except Exception: + pass + +# Neuter AsyncHttpxClientWrapper.__del__ before any AsyncOpenAI clients are +# created. The SDK's __del__ schedules aclose() on asyncio.get_running_loop() +# which, during CLI idle time, finds prompt_toolkit's event loop and tries to +# close TCP transports bound to dead worker loops — producing +# "Event loop is closed" / "Press ENTER to continue..." errors. +try: + from agent.auxiliary_client import neuter_async_httpx_del + neuter_async_httpx_del() +except Exception: + pass + +from rich import box as rich_box +from rich.console import Console +from rich.markup import escape as _escape +from rich.panel import Panel +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) +from hermes_cli.banner import build_welcome_banner +from hermes_cli.commands import SlashCommandCompleter, SlashCommandAutoSuggest +from toolsets import get_all_toolsets, get_toolset_info, validate_toolset + +# Cron job system for scheduled tasks (execution is handled by the gateway) +from cron import get_job + +# Resource cleanup imports for safe shutdown (terminal VMs, browser sessions) +from tools.terminal_tool import cleanup_all_environments as _cleanup_all_terminals +from tools.terminal_tool import set_sudo_password_callback, set_approval_callback +from tools.skills_tool import set_secret_capture_callback +from hermes_cli.callbacks import prompt_for_secret +from tools.browser_tool import _emergency_cleanup_all_sessions as _cleanup_all_browsers + +# Guard to prevent cleanup from running multiple times on exit +_cleanup_done = False +# Weak reference to the active AIAgent for memory provider shutdown at exit +_active_agent_ref = None + +def _run_cleanup(): + """Run resource cleanup exactly once.""" + global _cleanup_done + if _cleanup_done: + return + _cleanup_done = True + try: + _cleanup_all_terminals() + except Exception: + pass + try: + _cleanup_all_browsers() + except Exception: + pass + try: + from tools.mcp_tool import shutdown_mcp_servers + shutdown_mcp_servers() + except Exception: + pass + # Close cached auxiliary LLM clients (sync + async) so that + # AsyncHttpxClientWrapper.__del__ doesn't fire on a closed event loop + # and trigger prompt_toolkit's "Press ENTER to continue..." handler. + try: + from agent.auxiliary_client import shutdown_cached_clients + shutdown_cached_clients() + except Exception: + 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( + getattr(_active_agent_ref, 'conversation_history', None) or [] + ) + except Exception: + pass + + +# ============================================================================= +# Git Worktree Isolation (#652) +# ============================================================================= + +# Tracks the active worktree for cleanup on exit +_active_worktree: Optional[Dict[str, str]] = None + + +def _git_repo_root() -> Optional[str]: + """Return the git repo root for CWD, or None if not in a repo.""" + import subprocess + try: + result = subprocess.run( + ["git", "rev-parse", "--show-toplevel"], + capture_output=True, text=True, timeout=5, + ) + if result.returncode == 0: + return result.stdout.strip() + except Exception: + pass + return None + + +def _path_is_within_root(path: Path, root: Path) -> bool: + """Return True when a resolved path stays within the expected root.""" + try: + path.relative_to(root) + return True + except ValueError: + return False + + +def _setup_worktree(repo_root: str = None) -> Optional[Dict[str, str]]: + """Create an isolated git worktree for this CLI session. + + Returns a dict with worktree metadata on success, None on failure. + The dict contains: path, branch, repo_root. + """ + import subprocess + + repo_root = repo_root or _git_repo_root() + if not repo_root: + print("\033[31m✗ --worktree requires being inside a git repository.\033[0m") + print(" cd into your project repo first, then run hermes -w") + return None + + short_id = uuid.uuid4().hex[:8] + wt_name = f"hermes-{short_id}" + branch_name = f"hermes/{wt_name}" + + worktrees_dir = Path(repo_root) / ".worktrees" + worktrees_dir.mkdir(parents=True, exist_ok=True) + + wt_path = worktrees_dir / wt_name + + # Ensure .worktrees/ is in .gitignore + gitignore = Path(repo_root) / ".gitignore" + _ignore_entry = ".worktrees/" + try: + existing = gitignore.read_text() if gitignore.exists() else "" + if _ignore_entry not in existing.splitlines(): + with open(gitignore, "a") as f: + if existing and not existing.endswith("\n"): + f.write("\n") + f.write(f"{_ignore_entry}\n") + except Exception as e: + logger.debug("Could not update .gitignore: %s", e) + + # Create the worktree + try: + result = subprocess.run( + ["git", "worktree", "add", str(wt_path), "-b", branch_name, "HEAD"], + capture_output=True, text=True, timeout=30, cwd=repo_root, + ) + if result.returncode != 0: + print(f"\033[31m✗ Failed to create worktree: {result.stderr.strip()}\033[0m") + return None + except Exception as e: + print(f"\033[31m✗ Failed to create worktree: {e}\033[0m") + return None + + # Copy files listed in .worktreeinclude (gitignored files the agent needs) + include_file = Path(repo_root) / ".worktreeinclude" + if include_file.exists(): + try: + repo_root_resolved = Path(repo_root).resolve() + wt_path_resolved = wt_path.resolve() + for line in include_file.read_text().splitlines(): + entry = line.strip() + if not entry or entry.startswith("#"): + continue + src = Path(repo_root) / entry + dst = wt_path / entry + # Prevent path traversal and symlink escapes: both the resolved + # source and the resolved destination must stay inside their + # expected roots before any file or symlink operation happens. + try: + src_resolved = src.resolve(strict=False) + dst_resolved = dst.resolve(strict=False) + except (OSError, ValueError): + logger.debug("Skipping invalid .worktreeinclude entry: %s", entry) + continue + if not _path_is_within_root(src_resolved, repo_root_resolved): + logger.warning("Skipping .worktreeinclude entry outside repo root: %s", entry) + continue + if not _path_is_within_root(dst_resolved, wt_path_resolved): + logger.warning("Skipping .worktreeinclude entry that escapes worktree: %s", entry) + continue + if src.is_file(): + dst.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(str(src), str(dst)) + elif src.is_dir(): + # Symlink directories (faster, saves disk) + if not dst.exists(): + dst.parent.mkdir(parents=True, exist_ok=True) + os.symlink(str(src_resolved), str(dst)) + except Exception as e: + logger.debug("Error copying .worktreeinclude entries: %s", e) + + info = { + "path": str(wt_path), + "branch": branch_name, + "repo_root": repo_root, + } + + print(f"\033[32m✓ Worktree created:\033[0m {wt_path}") + print(f" Branch: {branch_name}") + + return info + + +def _cleanup_worktree(info: Dict[str, str] = None) -> None: + """Remove a worktree and its branch on exit. + + 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 + if not info: + return + + import subprocess + + wt_path = info["path"] + branch = info["branch"] + repo_root = info["repo_root"] + + if not Path(wt_path).exists(): + return + + # 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: + result = subprocess.run( + ["git", "log", "--oneline", "HEAD", "--not", "--remotes"], + capture_output=True, text=True, timeout=10, cwd=wt_path, + ) + has_unpushed = bool(result.stdout.strip()) + except Exception: + has_unpushed = True # Assume unpushed on error — don't delete + + 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 (even if working tree is dirty — uncommitted + # changes without unpushed commits are just artifacts) + try: + subprocess.run( + ["git", "worktree", "remove", wt_path, "--force"], + capture_output=True, text=True, timeout=15, cwd=repo_root, + ) + except Exception as e: + logger.debug("Failed to remove worktree: %s", e) + + # Delete the branch + try: + subprocess.run( + ["git", "branch", "-D", branch], + capture_output=True, text=True, timeout=10, cwd=repo_root, + ) + except Exception as e: + logger.debug("Failed to delete branch %s: %s", branch, e) + + _active_worktree = None + print(f"\033[32m✓ Worktree cleaned up: {wt_path}\033[0m") + + +def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None: + """Remove stale worktrees and orphaned branches on startup. + + 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() + 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-"): + continue + + # Check age + try: + mtime = entry.stat().st_mtime + if mtime > soft_cutoff: + continue # Too recent — skip + except Exception: + continue + + 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: + branch_result = subprocess.run( + ["git", "branch", "--show-current"], + capture_output=True, text=True, timeout=5, cwd=str(entry), + ) + branch = branch_result.stdout.strip() + + subprocess.run( + ["git", "worktree", "remove", str(entry), "--force"], + capture_output=True, text=True, timeout=15, cwd=repo_root, + ) + if branch: + subprocess.run( + ["git", "branch", "-D", branch], + capture_output=True, text=True, timeout=10, cwd=repo_root, + ) + 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 +# ============================================================================ + +# Color palette (hex colors for Rich markup): +# - Gold: #FFD700 (headers, highlights) +# - Amber: #FFBF00 (secondary highlights) +# - Bronze: #CD7F32 (tertiary elements) +# - Light: #FFF8DC (text) +# - Dim: #B8860B (muted text) + +# ANSI building blocks for conversation display +_ACCENT_ANSI_DEFAULT = "\033[1;38;2;255;215;0m" # True-color #FFD700 bold — fallback +_BOLD = "\033[1m" +_RST = "\033[0m" + + +def _hex_to_ansi(hex_color: str, *, bold: bool = False) -> str: + """Convert a hex color like '#268bd2' to a true-color ANSI escape.""" + try: + r = int(hex_color[1:3], 16) + g = int(hex_color[3:5], 16) + b = int(hex_color[5:7], 16) + prefix = "1;" if bold else "" + return f"\033[{prefix}38;2;{r};{g};{b}m" + except (ValueError, IndexError): + return _ACCENT_ANSI_DEFAULT if bold else "\033[38;2;184;134;11m" + + +class _SkinAwareAnsi: + """Lazy ANSI escape that resolves from the skin engine on first use. + + Acts as a string in f-strings and concatenation. Call ``.reset()`` to + force re-resolution after a ``/skin`` switch. + """ + + def __init__(self, skin_key: str, fallback_hex: str = "#FFD700", *, bold: bool = False): + self._skin_key = skin_key + self._fallback_hex = fallback_hex + self._bold = bold + self._cached: str | None = None + + def __str__(self) -> str: + if self._cached is None: + try: + from hermes_cli.skin_engine import get_active_skin + self._cached = _hex_to_ansi( + get_active_skin().get_color(self._skin_key, self._fallback_hex), + bold=self._bold, + ) + except Exception: + self._cached = _hex_to_ansi(self._fallback_hex, bold=self._bold) + return self._cached + + def __add__(self, other: str) -> str: + return str(self) + other + + def __radd__(self, other: str) -> str: + return other + str(self) + + def reset(self) -> None: + """Clear cache so the next access re-reads the skin.""" + self._cached = None + + +_ACCENT = _SkinAwareAnsi("response_border", "#FFD700", bold=True) +_DIM = _SkinAwareAnsi("banner_dim", "#B8860B") + + +def _accent_hex() -> str: + """Return the active skin accent color for legacy CLI output lines.""" + try: + from hermes_cli.skin_engine import get_active_skin + return get_active_skin().get_color("ui_accent", "#FFBF00") + except Exception: + return "#FFBF00" + + +def _rich_text_from_ansi(text: str) -> _RichText: + """Safely render assistant/tool output that may contain ANSI escapes. + + Using Rich Text.from_ansi preserves literal bracketed text like + ``[not markup]`` while still interpreting real ANSI color codes. + """ + return _RichText.from_ansi(text or "") + + +def _cprint(text: str): + """Print ANSI-colored text through prompt_toolkit's native renderer. + + Raw ANSI escapes written via print() are swallowed by patch_stdout's + StdoutProxy. Routing through print_formatted_text(ANSI(...)) lets + prompt_toolkit parse the escapes and render real colors. + """ + _pt_print(_PT_ANSI(text)) + + +# --------------------------------------------------------------------------- +# File-drop / local attachment detection — extracted as pure helpers for tests. +# --------------------------------------------------------------------------- + +_IMAGE_EXTENSIONS = frozenset({ + '.png', '.jpg', '.jpeg', '.gif', '.webp', + '.bmp', '.tiff', '.tif', '.svg', '.ico', +}) + + +from hermes_constants import is_termux as _is_termux_environment + + +def _termux_example_image_path(filename: str = "cat.png") -> str: + """Return a realistic example media path for the current Termux setup.""" + candidates = [ + os.path.expanduser("~/storage/shared"), + "/sdcard", + "/storage/emulated/0", + "/storage/self/primary", + ] + for root in candidates: + if os.path.isdir(root): + return os.path.join(root, "Pictures", filename) + return os.path.join("~/storage/shared", "Pictures", filename) + + +def _split_path_input(raw: str) -> tuple[str, str]: + r"""Split a leading file path token from trailing free-form text. + + Supports quoted paths and backslash-escaped spaces so callers can accept + inputs like: + /tmp/pic.png describe this + ~/storage/shared/My\ Photos/cat.png what is this? + "/storage/emulated/0/DCIM/Camera/cat 1.png" summarize + """ + raw = str(raw or "").strip() + if not raw: + return "", "" + + if raw[0] in {'"', "'"}: + quote = raw[0] + pos = 1 + while pos < len(raw): + ch = raw[pos] + if ch == '\\' and pos + 1 < len(raw): + pos += 2 + continue + if ch == quote: + token = raw[1:pos] + remainder = raw[pos + 1 :].strip() + return token, remainder + pos += 1 + return raw[1:], "" + + pos = 0 + while pos < len(raw): + ch = raw[pos] + if ch == '\\' and pos + 1 < len(raw) and raw[pos + 1] == ' ': + pos += 2 + elif ch == ' ': + break + else: + pos += 1 + + token = raw[:pos].replace('\\ ', ' ') + remainder = raw[pos:].strip() + return token, remainder + + +def _resolve_attachment_path(raw_path: str) -> Path | None: + """Resolve a user-supplied local attachment path. + + Accepts quoted or unquoted paths, expands ``~`` and env vars, and resolves + relative paths from ``TERMINAL_CWD`` when set (matching terminal tool cwd). + Returns ``None`` when the path does not resolve to an existing file. + """ + token = str(raw_path or "").strip() + if not token: + return None + + if (token.startswith('"') and token.endswith('"')) or (token.startswith("'") and token.endswith("'")): + token = token[1:-1].strip() + if not token: + return None + + expanded = os.path.expandvars(os.path.expanduser(token)) + path = Path(expanded) + if not path.is_absolute(): + base_dir = Path(os.getenv("TERMINAL_CWD", os.getcwd())) + path = base_dir / path + + try: + resolved = path.resolve() + except Exception: + resolved = path + + if not resolved.exists() or not resolved.is_file(): + return None + return resolved + + +def _format_process_notification(evt: dict) -> "str | None": + """Format a process notification event into a [SYSTEM: ...] message. + + Handles both completion events (notify_on_complete) and watch pattern + match events from the unified completion_queue. + """ + evt_type = evt.get("type", "completion") + _sid = evt.get("session_id", "unknown") + _cmd = evt.get("command", "unknown") + + if evt_type == "watch_disabled": + return f"[SYSTEM: {evt.get('message', '')}]" + + if evt_type == "watch_match": + _pat = evt.get("pattern", "?") + _out = evt.get("output", "") + _sup = evt.get("suppressed", 0) + text = ( + f"[SYSTEM: Background process {_sid} matched " + f"watch pattern \"{_pat}\".\n" + f"Command: {_cmd}\n" + f"Matched output:\n{_out}" + ) + if _sup: + text += f"\n({_sup} earlier matches were suppressed by rate limit)" + text += "]" + return text + + # Default: completion event + _exit = evt.get("exit_code", "?") + _out = evt.get("output", "") + return ( + f"[SYSTEM: Background process {_sid} completed " + f"(exit code {_exit}).\n" + f"Command: {_cmd}\n" + f"Output:\n{_out}]" + ) + + +def _detect_file_drop(user_input: str) -> "dict | None": + """Detect if *user_input* starts with a real local file path. + + This catches dragged/pasted paths before they are mistaken for slash + commands, and also supports Termux-friendly paths like ``~/storage/...``. + + Returns a dict on match:: + + { + "path": Path, # resolved file path + "is_image": bool, # True when suffix is a known image type + "remainder": str, # any text after the path + } + + Returns ``None`` when the input is not a real file path. + """ + if not isinstance(user_input, str): + return None + + stripped = user_input.strip() + if not stripped: + return None + + starts_like_path = ( + stripped.startswith("/") + or stripped.startswith("~") + or stripped.startswith("./") + or stripped.startswith("../") + or stripped.startswith('"/') + or stripped.startswith('"~') + or stripped.startswith("'/") + or stripped.startswith("'~") + ) + if not starts_like_path: + return None + + first_token, remainder = _split_path_input(stripped) + drop_path = _resolve_attachment_path(first_token) + if drop_path is None: + return None + + return { + "path": drop_path, + "is_image": drop_path.suffix.lower() in _IMAGE_EXTENSIONS, + "remainder": remainder, + } + + +def _format_image_attachment_badges(attached_images: list[Path], image_counter: int, width: int | None = None) -> str: + """Format the attached-image badge row for the interactive CLI. + + Narrow terminals such as Termux should get a compact summary that fits on a + single row, while wider terminals can show the classic per-image badges. + """ + if not attached_images: + return "" + + width = width or shutil.get_terminal_size((80, 24)).columns + + def _trunc(name: str, limit: int) -> str: + return name if len(name) <= limit else name[: max(1, limit - 3)] + "..." + + if width < 52: + if len(attached_images) == 1: + return f"[📎 {_trunc(attached_images[0].name, 20)}]" + return f"[📎 {len(attached_images)} images attached]" + + if width < 80: + if len(attached_images) == 1: + return f"[📎 {_trunc(attached_images[0].name, 32)}]" + first = _trunc(attached_images[0].name, 20) + extra = len(attached_images) - 1 + return f"[📎 {first}] [+{extra}]" + + base = image_counter - len(attached_images) + 1 + return " ".join( + f"[📎 Image #{base + i}]" + for i in range(len(attached_images)) + ) + + +def _should_auto_attach_clipboard_image_on_paste(pasted_text: str) -> bool: + """Auto-attach clipboard images only for image-only paste gestures.""" + return not pasted_text.strip() + + +def _collect_query_images(query: str | None, image_arg: str | None = None) -> tuple[str, list[Path]]: + """Collect local image attachments for single-query CLI flows.""" + message = query or "" + images: list[Path] = [] + + if isinstance(message, str): + dropped = _detect_file_drop(message) + if dropped and dropped.get("is_image"): + images.append(dropped["path"]) + message = dropped["remainder"] or f"[User attached image: {dropped['path'].name}]" + + if image_arg: + explicit_path = _resolve_attachment_path(image_arg) + if explicit_path is None: + raise ValueError(f"Image file not found: {image_arg}") + if explicit_path.suffix.lower() not in _IMAGE_EXTENSIONS: + raise ValueError(f"Not a supported image file: {explicit_path}") + images.append(explicit_path) + + deduped: list[Path] = [] + seen: set[str] = set() + for img in images: + key = str(img) + if key in seen: + continue + seen.add(key) + deduped.append(img) + return message, deduped + + +class ChatConsole: + """Rich Console adapter for prompt_toolkit's patch_stdout context. + + Captures Rich's rendered ANSI output and routes it through _cprint + so colors and markup render correctly inside the interactive chat loop. + Drop-in replacement for Rich Console — just pass this to any function + that expects a console.print() interface. + """ + + def __init__(self): + from io import StringIO + self._buffer = StringIO() + self._inner = Console( + file=self._buffer, + force_terminal=True, + color_system="truecolor", + highlight=False, + ) + + def print(self, *args, **kwargs): + self._buffer.seek(0) + self._buffer.truncate() + # Read terminal width at render time so panels adapt to current size + self._inner.width = shutil.get_terminal_size((80, 24)).columns + self._inner.print(*args, **kwargs) + output = self._buffer.getvalue() + for line in output.rstrip("\n").split("\n"): + _cprint(line) + + @contextmanager + def status(self, *_args, **_kwargs): + """Provide a no-op Rich-compatible status context. + + Some slash command helpers use ``console.status(...)`` when running in + the standalone CLI. Interactive chat routes those helpers through + ``ChatConsole()``, which historically only implemented ``print()``. + Returning a silent context manager keeps slash commands compatible + without duplicating the higher-level busy indicator already shown by + ``HermesCLI._busy_command()``. + """ + yield self + +# ASCII Art - HERMES-AGENT logo (full width, single line - requires ~95 char terminal) +HERMES_AGENT_LOGO = """[bold #FFD700]██╗ ██╗███████╗██████╗ ███╗ ███╗███████╗███████╗ █████╗ ██████╗ ███████╗███╗ ██╗████████╗[/] +[bold #FFD700]██║ ██║██╔════╝██╔══██╗████╗ ████║██╔════╝██╔════╝ ██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝[/] +[#FFBF00]███████║█████╗ ██████╔╝██╔████╔██║█████╗ ███████╗█████╗███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║[/] +[#FFBF00]██╔══██║██╔══╝ ██╔══██╗██║╚██╔╝██║██╔══╝ ╚════██║╚════╝██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║[/] +[#CD7F32]██║ ██║███████╗██║ ██║██║ ╚═╝ ██║███████╗███████║ ██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║[/] +[#CD7F32]╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚══════╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝[/]""" + +# ASCII Art - Hermes Caduceus (compact, fits in left panel) +HERMES_CADUCEUS = """[#CD7F32]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⡀⠀⣀⣀⠀⢀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#CD7F32]⠀⠀⠀⠀⠀⠀⢀⣠⣴⣾⣿⣿⣇⠸⣿⣿⠇⣸⣿⣿⣷⣦⣄⡀⠀⠀⠀⠀⠀⠀[/] +[#FFBF00]⠀⢀⣠⣴⣶⠿⠋⣩⡿⣿⡿⠻⣿⡇⢠⡄⢸⣿⠟⢿⣿⢿⣍⠙⠿⣶⣦⣄⡀⠀[/] +[#FFBF00]⠀⠀⠉⠉⠁⠶⠟⠋⠀⠉⠀⢀⣈⣁⡈⢁⣈⣁⡀⠀⠉⠀⠙⠻⠶⠈⠉⠉⠀⠀[/] +[#FFD700]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣴⣿⡿⠛⢁⡈⠛⢿⣿⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#FFD700]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠿⣿⣦⣤⣈⠁⢠⣴⣿⠿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#FFBF00]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠻⢿⣿⣦⡉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#FFBF00]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⢷⣦⣈⠛⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#CD7F32]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⣴⠦⠈⠙⠿⣦⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#CD7F32]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠸⣿⣤⡈⠁⢤⣿⠇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#B8860B]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⠷⠄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#B8860B]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⠑⢶⣄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#B8860B]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⠁⢰⡆⠈⡿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#B8860B]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠳⠈⣡⠞⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#B8860B]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]""" + + + +def _build_compact_banner() -> str: + """Build a compact banner that fits the current terminal width.""" + 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 f"\n[{title_color}]{tiny_line}[/] [dim {dim_color}]- Nous Research[/]\n" + + inner = w - 2 # inside the box border + bar = "═" * w + content_width = inner - 2 + + # Truncate and pad to fit + line1 = line1[:content_width].ljust(content_width) + line2 = version_line[:content_width].ljust(content_width) + + return ( + 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" + ) + + + +# ============================================================================ +# Slash-command detection helper +# ============================================================================ + +def _looks_like_slash_command(text: str) -> bool: + """Return True if *text* looks like a slash command, not a file path. + + Slash commands are ``/help``, ``/model gpt-4``, ``/q``, etc. + File paths like ``/Users/ironin/file.md:45-46 can you fix this?`` + also start with ``/`` but contain additional ``/`` characters in + the first whitespace-delimited word. This helper distinguishes + the two so that pasted paths are sent to the agent instead of + triggering "Unknown command". + """ + if not text or not text.startswith("/"): + return False + first_word = text.split()[0] + # After stripping the leading /, a command name has no slashes. + # A path like /Users/foo/bar.md always does. + return "/" not in first_word[1:] + + +# ============================================================================ +# Skill Slash Commands — dynamic commands generated from installed skills +# ============================================================================ + +from agent.skill_commands import ( + scan_skill_commands, + build_skill_invocation_message, + build_plan_path, + build_preloaded_skills_prompt, +) + +_skill_commands = scan_skill_commands() + + +def _get_plugin_cmd_handler_names() -> set: + """Return plugin command names (without slash prefix) for dispatch matching.""" + try: + from hermes_cli.plugins import get_plugin_manager + return set(get_plugin_manager()._plugin_commands.keys()) + except Exception: + return set() + + +def _parse_skills_argument(skills: str | list[str] | tuple[str, ...] | None) -> list[str]: + """Normalize a CLI skills flag into a deduplicated list of skill identifiers.""" + if not skills: + return [] + + if isinstance(skills, str): + raw_values = [skills] + elif isinstance(skills, (list, tuple)): + raw_values = [str(item) for item in skills if item is not None] + else: + raw_values = [str(skills)] + + parsed: list[str] = [] + seen: set[str] = set() + for raw in raw_values: + for part in raw.split(","): + normalized = part.strip() + if not normalized or normalized in seen: + continue + seen.add(normalized) + parsed.append(normalized) + return parsed + + +def save_config_value(key_path: str, value: any) -> bool: + """ + Save a value to the active config file at the specified key path. + + Respects the same lookup order as load_cli_config(): + 1. ~/.hermes/config.yaml (user config - preferred, used if it exists) + 2. ./cli-config.yaml (project config - fallback) + + Args: + key_path: Dot-separated path like "agent.system_prompt" + value: Value to save + + Returns: + True if successful, False otherwise + """ + # Use the same precedence as load_cli_config: user config first, then project config + user_config_path = _hermes_home / 'config.yaml' + project_config_path = Path(__file__).parent / 'cli-config.yaml' + config_path = user_config_path if user_config_path.exists() else project_config_path + + try: + # Ensure parent directory exists (for ~/.hermes/config.yaml on first use) + config_path.parent.mkdir(parents=True, exist_ok=True) + + # Load existing config + if config_path.exists(): + with open(config_path, 'r') as f: + config = yaml.safe_load(f) or {} + else: + config = {} + + # Navigate to the key and set value + keys = key_path.split('.') + current = config + for key in keys[:-1]: + if key not in current or not isinstance(current[key], dict): + current[key] = {} + current = current[key] + current[keys[-1]] = value + + # Save back atomically — write to temp file + fsync + os.replace + # so an interrupt never leaves config.yaml truncated or empty. + from utils import atomic_yaml_write + atomic_yaml_write(config_path, config) + + # Enforce owner-only permissions on config files (contain API keys) + try: + os.chmod(config_path, 0o600) + except (OSError, NotImplementedError): + pass + + return True + except Exception as e: + logger.error("Failed to save config: %s", e) + return False + + + + +# ============================================================================ +# HermesCLI Class +# ============================================================================ + +class HermesCLI: + """ + Interactive CLI for the Hermes Agent. + + Provides a REPL interface with rich formatting, command history, + and tool execution capabilities. + """ + + def __init__( + self, + model: str = None, + toolsets: List[str] = None, + provider: str = None, + api_key: str = None, + base_url: str = None, + max_turns: int = None, + verbose: bool = False, + compact: bool = False, + resume: str = None, + checkpoints: bool = False, + pass_session_id: bool = False, + ): + """ + Initialize the Hermes CLI. + + Args: + model: Model to use (default: from env or claude-sonnet) + toolsets: List of toolsets to enable (default: all) + provider: Inference provider ("auto", "openrouter", "nous", "openai-codex", "zai", "kimi-coding", "minimax", "minimax-cn") + api_key: API key (default: from environment) + base_url: API base URL (default: OpenRouter) + max_turns: Maximum tool-calling iterations shared with subagents (default: 90) + verbose: Enable verbose logging + compact: Use compact display mode + resume: Session ID to resume (restores conversation history from SQLite) + pass_session_id: Include the session ID in the agent's system prompt + """ + # Initialize Rich console + self.console = Console() + self.config = CLI_CONFIG + self.compact = compact if compact is not None else CLI_CONFIG["display"].get("compact", False) + # tool_progress: "off", "new", "all", "verbose" (from config.yaml display section) + # YAML 1.1 parses bare `off` as boolean False — normalise to string. + _raw_tp = CLI_CONFIG["display"].get("tool_progress", "all") + self.tool_progress_mode = "off" if _raw_tp is False else str(_raw_tp) + # resume_display: "full" (show history) | "minimal" (one-liner only) + self.resume_display = CLI_CONFIG["display"].get("resume_display", "full") + # bell_on_complete: play terminal bell (\a) when agent finishes a response + self.bell_on_complete = CLI_CONFIG["display"].get("bell_on_complete", False) + # show_reasoning: display model thinking/reasoning before the response + self.show_reasoning = CLI_CONFIG["display"].get("show_reasoning", False) + # busy_input_mode: "interrupt" (Enter interrupts current run) or "queue" (Enter queues for next turn) + _bim = CLI_CONFIG["display"].get("busy_input_mode", "interrupt") + self.busy_input_mode = "queue" if str(_bim).strip().lower() == "queue" else "interrupt" + + self.verbose = verbose if verbose is not None else (self.tool_progress_mode == "verbose") + + # streaming: stream tokens to the terminal as they arrive (display.streaming in config.yaml) + self.streaming_enabled = CLI_CONFIG["display"].get("streaming", False) + + # Inline diff previews for write actions (display.inline_diffs in config.yaml) + self._inline_diffs_enabled = CLI_CONFIG["display"].get("inline_diffs", True) + + # Streaming display state + self._stream_buf = "" # Partial line buffer for line-buffered rendering + self._stream_started = False # True once first delta arrives + self._stream_box_opened = False # True once the response box header is printed + self._reasoning_preview_buf = "" # Coalesce tiny reasoning chunks for [thinking] output + self._pending_edit_snapshots = {} + + # Configuration - priority: CLI args > env vars > config file + # Model comes from: CLI arg or config.yaml (single source of truth). + # LLM_MODEL/OPENAI_MODEL env vars are NOT checked — config.yaml is + # authoritative. This avoids conflicts in multi-agent setups where + # env vars would stomp each other. + _model_config = CLI_CONFIG.get("model", {}) + _config_model = (_model_config.get("default") or _model_config.get("model") or "") if isinstance(_model_config, dict) else (_model_config or "") + _DEFAULT_CONFIG_MODEL = "" + self.model = model or _config_model or _DEFAULT_CONFIG_MODEL + # Auto-detect model from local server if still on default + if self.model == _DEFAULT_CONFIG_MODEL: + _base_url = (_model_config.get("base_url") or "") if isinstance(_model_config, dict) else "" + if "localhost" in _base_url or "127.0.0.1" in _base_url: + from hermes_cli.runtime_provider import _auto_detect_local_model + _detected = _auto_detect_local_model(_base_url) + if _detected: + self.model = _detected + # Track whether model was explicitly chosen by the user or fell back + # to the global default. Provider-specific normalisation may override + # the default silently but should warn when overriding an explicit choice. + # A config model that matches the global fallback is NOT considered an + # explicit choice — the user just never changed it. But a config model + # like "gpt-5.3-codex" IS explicit and must be preserved. + self._model_is_default = not model and ( + not _config_model or _config_model == _DEFAULT_CONFIG_MODEL + ) + + self._explicit_api_key = api_key + self._explicit_base_url = base_url + + # Provider selection is resolved lazily at use-time via _ensure_runtime_credentials(). + self.requested_provider = ( + provider + or CLI_CONFIG["model"].get("provider") + or os.getenv("HERMES_INFERENCE_PROVIDER") + or "auto" + ) + self._provider_source: Optional[str] = None + self.provider = self.requested_provider + self.api_mode = "chat_completions" + self.acp_command: Optional[str] = None + self.acp_args: list[str] = [] + self.base_url = ( + base_url + or CLI_CONFIG["model"].get("base_url", "") + or os.getenv("OPENROUTER_BASE_URL", "") + ) or None + # Match key to resolved base_url: OpenRouter URL → prefer OPENROUTER_API_KEY, + # custom endpoint → prefer OPENAI_API_KEY (issue #560). + # Note: _ensure_runtime_credentials() re-resolves this before first use. + if self.base_url and "openrouter.ai" in self.base_url: + self.api_key = api_key or os.getenv("OPENROUTER_API_KEY") or os.getenv("OPENAI_API_KEY") + else: + self.api_key = api_key or os.getenv("OPENAI_API_KEY") or os.getenv("OPENROUTER_API_KEY") + # Max turns priority: CLI arg > config file > env var > default + if max_turns is not None: # CLI arg was explicitly set + self.max_turns = max_turns + elif CLI_CONFIG["agent"].get("max_turns"): + self.max_turns = CLI_CONFIG["agent"]["max_turns"] + elif CLI_CONFIG.get("max_turns"): # Backwards compat: root-level max_turns + self.max_turns = CLI_CONFIG["max_turns"] + elif os.getenv("HERMES_MAX_ITERATIONS"): + self.max_turns = int(os.getenv("HERMES_MAX_ITERATIONS")) + else: + self.max_turns = 90 + + # Parse and validate toolsets + self.enabled_toolsets = toolsets + if toolsets and "all" not in toolsets and "*" not in toolsets: + # Validate each toolset — MCP server names are added by + # _get_platform_tools() but aren't registered in TOOLSETS yet + # (that happens later in _sync_mcp_toolsets), so exclude them. + mcp_names = set((CLI_CONFIG.get("mcp_servers") or {}).keys()) + invalid = [t for t in toolsets if not validate_toolset(t) and t not in mcp_names] + if invalid: + self.console.print(f"[bold red]Warning: Unknown toolsets: {', '.join(invalid)}[/]") + + # Filesystem checkpoints: CLI flag > config + cp_cfg = CLI_CONFIG.get("checkpoints", {}) + if isinstance(cp_cfg, bool): + cp_cfg = {"enabled": cp_cfg} + self.checkpoints_enabled = checkpoints or cp_cfg.get("enabled", False) + self.checkpoint_max_snapshots = cp_cfg.get("max_snapshots", 50) + self.pass_session_id = pass_session_id + + # Ephemeral system prompt: env var takes precedence, then config + self.system_prompt = ( + os.getenv("HERMES_EPHEMERAL_SYSTEM_PROMPT", "") + or CLI_CONFIG["agent"].get("system_prompt", "") + ) + self.personalities = CLI_CONFIG["agent"].get("personalities", {}) + + # Ephemeral prefill messages (few-shot priming, never persisted) + self.prefill_messages = _load_prefill_messages( + CLI_CONFIG["agent"].get("prefill_messages_file", "") + ) + + # Reasoning config (OpenRouter reasoning effort level) + self.reasoning_config = _parse_reasoning_config( + CLI_CONFIG["agent"].get("reasoning_effort", "") + ) + self.service_tier = _parse_service_tier_config( + CLI_CONFIG["agent"].get("service_tier", "") + ) + + # OpenRouter provider routing preferences + pr = CLI_CONFIG.get("provider_routing", {}) or {} + self._provider_sort = pr.get("sort") + self._providers_only = pr.get("only") + self._providers_ignore = pr.get("ignore") + self._providers_order = pr.get("order") + self._provider_require_params = pr.get("require_parameters", False) + self._provider_data_collection = pr.get("data_collection") + + # Fallback provider chain — tried in order when primary fails after retries. + # Supports new list format (fallback_providers) and legacy single-dict (fallback_model). + fb = CLI_CONFIG.get("fallback_providers") or CLI_CONFIG.get("fallback_model") or [] + # Normalize legacy single-dict to a one-element list + if isinstance(fb, dict): + fb = [fb] if fb.get("provider") and fb.get("model") else [] + self._fallback_model = fb + + # Optional cheap-vs-strong routing for simple turns + self._smart_model_routing = CLI_CONFIG.get("smart_model_routing", {}) or {} + self._active_agent_route_signature = None + + # Agent will be initialized on first use + self.agent: Optional[AIAgent] = None + self._app = None # prompt_toolkit Application (set in run()) + + # Conversation state + self.conversation_history: List[Dict[str, Any]] = [] + self.session_start = datetime.now() + self._resumed = False + # Initialize SQLite session store early so /title works before first message + self._session_db = None + try: + from hermes_state import SessionDB + self._session_db = SessionDB() + except Exception as e: + logger.warning("Failed to initialize SessionDB — session will NOT be indexed for search: %s", e) + + # Deferred title: stored in memory until the session is created in the DB + self._pending_title: Optional[str] = None + + # Session ID: reuse existing one when resuming, otherwise generate fresh + if resume: + self.session_id = resume + self._resumed = True + else: + timestamp_str = self.session_start.strftime("%Y%m%d_%H%M%S") + short_uuid = uuid.uuid4().hex[:6] + self.session_id = f"{timestamp_str}_{short_uuid}" + + # History file for persistent input recall across sessions + self._history_file = _hermes_home / ".hermes_history" + self._last_invalidate: float = 0.0 # throttle UI repaints + self._app = None + + # State shared by interactive run() and single-query chat mode. + # These must exist before any direct chat() call because single-query + # mode does not go through run(). + self._agent_running = False + self._pending_input = queue.Queue() + self._interrupt_queue = queue.Queue() + self._should_exit = False + self._last_ctrl_c_time = 0 + self._clarify_state = None + self._clarify_freetext = False + self._clarify_deadline = 0 + self._sudo_state = None + self._sudo_deadline = 0 + self._modal_input_snapshot = None + self._approval_state = None + self._approval_deadline = 0 + self._approval_lock = threading.Lock() + self._model_picker_state = None + self._secret_state = None + self._secret_deadline = 0 + self._spinner_text: str = "" # thinking spinner text for TUI + self._tool_start_time: float = 0.0 # monotonic timestamp when current tool started (for live elapsed) + self._pending_tool_info: dict = {} # function_name -> list of (preview, args) for stacked scrollback + self._last_scrollback_tool: str = "" # last tool name printed to scrollback (for "new" dedup) + self._command_running = False + self._command_status = "" + self._attached_images: list[Path] = [] + self._image_counter = 0 + self.preloaded_skills: list[str] = [] + self._startup_skills_line_shown = False + + # Voice mode state (also reinitialized inside run() for interactive TUI). + self._voice_lock = threading.Lock() + self._voice_mode = False + self._voice_tts = False + self._voice_recorder = None + self._voice_recording = False + self._voice_processing = False + self._voice_continuous = False + self._voice_tts_done = threading.Event() + self._voice_tts_done.set() + + # Status bar visibility (toggled via /statusbar) + self._status_bar_visible = True + + # Background task tracking: {task_id: threading.Thread} + self._background_tasks: Dict[str, threading.Thread] = {} + self._background_task_counter = 0 + + def _invalidate(self, min_interval: float = 0.25) -> None: + """Throttled UI repaint — prevents terminal blinking on slow/SSH connections.""" + import time as _time + now = _time.monotonic() + if hasattr(self, "_app") and self._app and (now - self._last_invalidate) >= min_interval: + self._last_invalidate = now + self._app.invalidate() + + def _status_bar_context_style(self, percent_used: Optional[int]) -> str: + if percent_used is None: + return "class:status-bar-dim" + if percent_used >= 95: + return "class:status-bar-critical" + if percent_used > 80: + return "class:status-bar-bad" + if percent_used >= 50: + return "class:status-bar-warn" + return "class:status-bar-good" + + def _build_context_bar(self, percent_used: Optional[int], width: int = 10) -> str: + safe_percent = max(0, min(100, percent_used or 0)) + filled = round((safe_percent / 100) * width) + return f"[{('█' * filled) + ('░' * max(0, width - filled))}]" + + def _get_status_bar_snapshot(self) -> Dict[str, Any]: + # Prefer the agent's model name — it updates on fallback. + # self.model reflects the originally configured model and never + # changes mid-session, so the TUI would show a stale name after + # _try_activate_fallback() switches provider/model. + agent = getattr(self, "agent", None) + model_name = (getattr(agent, "model", None) or self.model or "unknown") + model_short = model_name.split("/")[-1] if "/" in model_name else model_name + if model_short.endswith(".gguf"): + model_short = model_short[:-5] + if len(model_short) > 26: + model_short = f"{model_short[:23]}..." + + elapsed_seconds = max(0.0, (datetime.now() - self.session_start).total_seconds()) + snapshot = { + "model_name": model_name, + "model_short": model_short, + "duration": format_duration_compact(elapsed_seconds), + "context_tokens": 0, + "context_length": None, + "context_percent": None, + "session_input_tokens": 0, + "session_output_tokens": 0, + "session_cache_read_tokens": 0, + "session_cache_write_tokens": 0, + "session_prompt_tokens": 0, + "session_completion_tokens": 0, + "session_total_tokens": 0, + "session_api_calls": 0, + "compressions": 0, + } + + if not agent: + return snapshot + + snapshot["session_input_tokens"] = getattr(agent, "session_input_tokens", 0) or 0 + snapshot["session_output_tokens"] = getattr(agent, "session_output_tokens", 0) or 0 + snapshot["session_cache_read_tokens"] = getattr(agent, "session_cache_read_tokens", 0) or 0 + snapshot["session_cache_write_tokens"] = getattr(agent, "session_cache_write_tokens", 0) or 0 + snapshot["session_prompt_tokens"] = getattr(agent, "session_prompt_tokens", 0) or 0 + snapshot["session_completion_tokens"] = getattr(agent, "session_completion_tokens", 0) or 0 + snapshot["session_total_tokens"] = getattr(agent, "session_total_tokens", 0) or 0 + snapshot["session_api_calls"] = getattr(agent, "session_api_calls", 0) or 0 + + compressor = getattr(agent, "context_compressor", None) + if compressor: + context_tokens = getattr(compressor, "last_prompt_tokens", 0) or 0 + context_length = getattr(compressor, "context_length", 0) or 0 + snapshot["context_tokens"] = context_tokens + snapshot["context_length"] = context_length or None + snapshot["compressions"] = getattr(compressor, "compression_count", 0) or 0 + if context_length: + snapshot["context_percent"] = max(0, min(100, round((context_tokens / context_length) * 100))) + + return snapshot + + @staticmethod + def _status_bar_display_width(text: str) -> int: + """Return terminal cell width for status-bar text. + + len() is not enough for prompt_toolkit layout decisions because some + glyphs can render wider than one Python codepoint. Keeping the status + bar within the real display width prevents it from wrapping onto a + second line and leaving behind duplicate rows. + """ + try: + from prompt_toolkit.utils import get_cwidth + return get_cwidth(text or "") + except Exception: + return len(text or "") + + @classmethod + def _trim_status_bar_text(cls, text: str, max_width: int) -> str: + """Trim status-bar text to a single terminal row.""" + if max_width <= 0: + return "" + try: + from prompt_toolkit.utils import get_cwidth + except Exception: + get_cwidth = None + + if cls._status_bar_display_width(text) <= max_width: + return text + + ellipsis = "..." + ellipsis_width = cls._status_bar_display_width(ellipsis) + if max_width <= ellipsis_width: + return ellipsis[:max_width] + + out = [] + width = 0 + for ch in text: + ch_width = get_cwidth(ch) if get_cwidth else len(ch) + if width + ch_width + ellipsis_width > max_width: + break + out.append(ch) + width += ch_width + return "".join(out).rstrip() + ellipsis + + @staticmethod + def _get_tui_terminal_width(default: tuple[int, int] = (80, 24)) -> int: + """Return the live prompt_toolkit width, falling back to ``shutil``. + + The TUI layout can be narrower than ``shutil.get_terminal_size()`` reports, + especially on Termux/mobile shells, so prefer prompt_toolkit's width whenever + an app is active. + """ + try: + from prompt_toolkit.application import get_app + return get_app().output.get_size().columns + except Exception: + return shutil.get_terminal_size(default).columns + + def _use_minimal_tui_chrome(self, width: Optional[int] = None) -> bool: + """Hide low-value chrome on narrow/mobile terminals to preserve rows.""" + if width is None: + width = self._get_tui_terminal_width() + return width < 64 + + def _tui_input_rule_height(self, position: str, width: Optional[int] = None) -> int: + """Return the visible height for the top/bottom input separator rules.""" + if position not in {"top", "bottom"}: + raise ValueError(f"Unknown input rule position: {position}") + if position == "top": + return 1 + return 0 if self._use_minimal_tui_chrome(width=width) else 1 + + def _agent_spacer_height(self, width: Optional[int] = None) -> int: + """Return the spacer height shown above the status bar while the agent runs.""" + if not getattr(self, "_agent_running", False): + return 0 + return 0 if self._use_minimal_tui_chrome(width=width) else 1 + + def _spinner_widget_height(self, width: Optional[int] = None) -> int: + """Return the visible height for the spinner/status text line above the status bar.""" + if not getattr(self, "_spinner_text", ""): + return 0 + return 0 if self._use_minimal_tui_chrome(width=width) else 1 + + def _get_voice_status_fragments(self, width: Optional[int] = None): + """Return the voice status bar fragments for the interactive TUI.""" + width = width or self._get_tui_terminal_width() + compact = self._use_minimal_tui_chrome(width=width) + if self._voice_recording: + if compact: + return [("class:voice-status-recording", " ● REC ")] + return [("class:voice-status-recording", " ● REC Ctrl+B to stop ")] + if self._voice_processing: + if compact: + return [("class:voice-status", " ◉ STT ")] + return [("class:voice-status", " ◉ Transcribing... ")] + if compact: + return [("class:voice-status", " 🎤 Ctrl+B ")] + tts = " | TTS on" if self._voice_tts else "" + cont = " | Continuous" if self._voice_continuous else "" + return [("class:voice-status", f" 🎤 Voice mode{tts}{cont} — Ctrl+B to record ")] + + def _build_status_bar_text(self, width: Optional[int] = None) -> str: + """Return a compact one-line session status string for the TUI footer.""" + try: + snapshot = self._get_status_bar_snapshot() + if width is None: + width = self._get_tui_terminal_width() + percent = snapshot["context_percent"] + percent_label = f"{percent}%" if percent is not None else "--" + duration_label = snapshot["duration"] + + if width < 52: + text = f"⚕ {snapshot['model_short']} · {duration_label}" + return self._trim_status_bar_text(text, width) + if width < 76: + parts = [f"⚕ {snapshot['model_short']}", percent_label] + parts.append(duration_label) + return self._trim_status_bar_text(" · ".join(parts), width) + + if snapshot["context_length"]: + ctx_total = _format_context_length(snapshot["context_length"]) + ctx_used = format_token_count_compact(snapshot["context_tokens"]) + context_label = f"{ctx_used}/{ctx_total}" + else: + context_label = "ctx --" + + parts = [f"⚕ {snapshot['model_short']}", context_label, percent_label] + parts.append(duration_label) + return self._trim_status_bar_text(" │ ".join(parts), width) + except Exception: + return f"⚕ {self.model if getattr(self, 'model', None) else 'Hermes'}" + + def _get_status_bar_fragments(self): + if not self._status_bar_visible or getattr(self, '_model_picker_state', None): + return [] + try: + snapshot = self._get_status_bar_snapshot() + # Use prompt_toolkit's own terminal width when running inside the + # TUI — shutil.get_terminal_size() can return stale or fallback + # values (especially on SSH) that differ from what prompt_toolkit + # actually renders, causing the fragments to overflow to a second + # line and produce duplicated status bar rows over long sessions. + width = self._get_tui_terminal_width() + duration_label = snapshot["duration"] + + if width < 52: + frags = [ + ("class:status-bar", " ⚕ "), + ("class:status-bar-strong", snapshot["model_short"]), + ("class:status-bar-dim", " · "), + ("class:status-bar-dim", duration_label), + ("class:status-bar", " "), + ] + else: + percent = snapshot["context_percent"] + percent_label = f"{percent}%" if percent is not None else "--" + if width < 76: + frags = [ + ("class:status-bar", " ⚕ "), + ("class:status-bar-strong", snapshot["model_short"]), + ("class:status-bar-dim", " · "), + (self._status_bar_context_style(percent), percent_label), + ("class:status-bar-dim", " · "), + ("class:status-bar-dim", duration_label), + ("class:status-bar", " "), + ] + else: + if snapshot["context_length"]: + ctx_total = _format_context_length(snapshot["context_length"]) + ctx_used = format_token_count_compact(snapshot["context_tokens"]) + context_label = f"{ctx_used}/{ctx_total}" + else: + context_label = "ctx --" + + bar_style = self._status_bar_context_style(percent) + frags = [ + ("class:status-bar", " ⚕ "), + ("class:status-bar-strong", snapshot["model_short"]), + ("class:status-bar-dim", " │ "), + ("class:status-bar-dim", context_label), + ("class:status-bar-dim", " │ "), + (bar_style, self._build_context_bar(percent)), + ("class:status-bar-dim", " "), + (bar_style, percent_label), + ("class:status-bar-dim", " │ "), + ("class:status-bar-dim", duration_label), + ("class:status-bar", " "), + ] + + total_width = sum(self._status_bar_display_width(text) for _, text in frags) + if total_width > width: + plain_text = "".join(text for _, text in frags) + trimmed = self._trim_status_bar_text(plain_text, width) + return [("class:status-bar", trimmed)] + return frags + except Exception: + return [("class:status-bar", f" {self._build_status_bar_text()} ")] + + def _normalize_model_for_provider(self, resolved_provider: str) -> bool: + """Normalize provider-specific model IDs and routing.""" + current_model = (self.model or "").strip() + changed = False + + try: + from hermes_cli.model_normalize import ( + _AGGREGATOR_PROVIDERS, + normalize_model_for_provider, + ) + + if resolved_provider not in _AGGREGATOR_PROVIDERS: + normalized_model = normalize_model_for_provider(current_model, resolved_provider) + if normalized_model and normalized_model != current_model: + if not self._model_is_default: + self.console.print( + f"[yellow]⚠️ Normalized model '{current_model}' to '{normalized_model}' for {resolved_provider}.[/]" + ) + self.model = normalized_model + current_model = normalized_model + changed = True + except Exception: + pass + + if resolved_provider == "copilot": + try: + from hermes_cli.models import copilot_model_api_mode, normalize_copilot_model_id + + canonical = normalize_copilot_model_id(current_model, api_key=self.api_key) + if canonical and canonical != current_model: + if not self._model_is_default: + self.console.print( + f"[yellow]⚠️ Normalized Copilot model '{current_model}' to '{canonical}'.[/]" + ) + self.model = canonical + current_model = canonical + changed = True + + resolved_mode = copilot_model_api_mode(current_model, api_key=self.api_key) + if resolved_mode != self.api_mode: + self.api_mode = resolved_mode + changed = True + except Exception: + pass + return changed + + if resolved_provider in {"opencode-zen", "opencode-go"}: + try: + from hermes_cli.models import normalize_opencode_model_id, opencode_model_api_mode + + canonical = normalize_opencode_model_id(resolved_provider, current_model) + if canonical and canonical != current_model: + if not self._model_is_default: + self.console.print( + f"[yellow]⚠️ Stripped provider prefix from '{current_model}'; using '{canonical}' for {resolved_provider}.[/]" + ) + self.model = canonical + current_model = canonical + changed = True + + resolved_mode = opencode_model_api_mode(resolved_provider, current_model) + if resolved_mode != self.api_mode: + self.api_mode = resolved_mode + changed = True + except Exception: + pass + return changed + + if resolved_provider != "openai-codex": + return changed + + # 1. Strip provider prefix ("openai/gpt-5.4" → "gpt-5.4") + if "/" in current_model: + slug = current_model.split("/", 1)[1] + if not self._model_is_default: + self.console.print( + f"[yellow]⚠️ Stripped provider prefix from '{current_model}'; " + f"using '{slug}' for OpenAI Codex.[/]" + ) + self.model = slug + current_model = slug + changed = True + + # 2. Replace untouched default with a Codex model + if self._model_is_default: + fallback_model = "gpt-5.3-codex" + try: + from hermes_cli.codex_models import get_codex_model_ids + + available = get_codex_model_ids( + access_token=self.api_key if self.api_key else None, + ) + if available: + fallback_model = available[0] + except Exception: + pass + + if current_model != fallback_model: + self.model = fallback_model + changed = True + + return changed + + def _on_thinking(self, text: str) -> None: + """Called by agent when thinking starts/stops. Updates TUI spinner.""" + if not text: + self._flush_reasoning_preview(force=True) + self._spinner_text = text or "" + self._tool_start_time = 0.0 # clear tool timer when switching to thinking + self._invalidate() + + # ── Streaming display ──────────────────────────────────────────────── + + def _current_reasoning_callback(self): + """Return the active reasoning display callback for the current mode.""" + if self.show_reasoning and self.streaming_enabled: + return self._stream_reasoning_delta + if self.verbose and not self.show_reasoning: + return self._on_reasoning + return None + + def _emit_reasoning_preview(self, reasoning_text: str) -> None: + """Render a buffered reasoning preview as a single [thinking] block.""" + import re + import textwrap + + preview_text = reasoning_text.strip() + if not preview_text: + return + + try: + term_width = shutil.get_terminal_size().columns + except Exception: + term_width = 80 + prefix = " [thinking] " + wrap_width = max(30, term_width - len(prefix) - 2) + + paragraphs = [] + raw_paragraphs = re.split(r"\n\s*\n+", preview_text.replace("\r\n", "\n")) + for paragraph in raw_paragraphs: + compact = " ".join(line.strip() for line in paragraph.splitlines() if line.strip()) + if compact: + paragraphs.append(textwrap.fill(compact, width=wrap_width)) + preview_text = "\n".join(paragraphs) + if not preview_text: + return + + if self.verbose: + _cprint(f" {_DIM}[thinking] {preview_text}{_RST}") + return + + lines = preview_text.splitlines() + if len(lines) > 5: + preview = "\n".join(lines[:5]) + preview += f"\n ... ({len(lines) - 5} more lines)" + else: + preview = preview_text + _cprint(f" {_DIM}[thinking] {preview}{_RST}") + + def _flush_reasoning_preview(self, *, force: bool = False) -> None: + """Flush buffered reasoning text at natural boundaries. + + Some providers stream reasoning in tiny word or punctuation chunks. + Buffer them here so the preview path does not print one `[thinking]` + line per token. + """ + buf = getattr(self, "_reasoning_preview_buf", "") + if not buf: + return + + try: + term_width = shutil.get_terminal_size().columns + except Exception: + term_width = 80 + target_width = max(40, term_width - len(" [thinking] ") - 4) + + flush_text = "" + + if force: + flush_text = buf + buf = "" + else: + line_break = buf.rfind("\n") + min_newline_flush = max(16, target_width // 3) + if line_break != -1 and ( + line_break >= min_newline_flush + or buf.endswith("\n\n") + or buf.endswith(".\n") + or buf.endswith("!\n") + or buf.endswith("?\n") + or buf.endswith(":\n") + ): + flush_text = buf[: line_break + 1] + buf = buf[line_break + 1 :] + elif len(buf) >= target_width: + search_start = max(20, target_width // 2) + search_end = min(len(buf), max(target_width + (target_width // 3), target_width + 8)) + cut = -1 + for boundary in (" ", "\t", ".", "!", "?", ",", ";", ":"): + cut = max(cut, buf.rfind(boundary, search_start, search_end)) + if cut != -1: + flush_text = buf[: cut + 1] + buf = buf[cut + 1 :] + + self._reasoning_preview_buf = buf.lstrip() if flush_text else buf + if flush_text: + self._emit_reasoning_preview(flush_text) + + def _stream_reasoning_delta(self, text: str) -> None: + """Stream reasoning/thinking tokens into a dim box above the response. + + Opens a dim reasoning box on first token, streams line-by-line. + The box is closed automatically when content tokens start arriving + (via _stream_delta → _emit_stream_text). + + Once the response box is open, suppress any further reasoning + rendering — a late thinking block (e.g. after an interrupt) would + otherwise draw a reasoning box inside the response box. + """ + if not text: + return + self._reasoning_shown_this_turn = True + if getattr(self, "_stream_box_opened", False): + return + + # Open reasoning box on first reasoning token + if not getattr(self, "_reasoning_box_opened", False): + self._reasoning_box_opened = True + w = shutil.get_terminal_size().columns + r_label = " Reasoning " + r_fill = w - 2 - len(r_label) + _cprint(f"\n{_DIM}┌─{r_label}{'─' * max(r_fill - 1, 0)}┐{_RST}") + + self._reasoning_buf = getattr(self, "_reasoning_buf", "") + text + + # Emit complete lines, and force-flush long partial lines so + # reasoning is visible in real-time even without newlines. + while "\n" in self._reasoning_buf: + line, self._reasoning_buf = self._reasoning_buf.split("\n", 1) + _cprint(f"{_DIM}{line}{_RST}") + if len(self._reasoning_buf) > 80: + _cprint(f"{_DIM}{self._reasoning_buf}{_RST}") + self._reasoning_buf = "" + + def _close_reasoning_box(self) -> None: + """Close the live reasoning box if it's open.""" + if getattr(self, "_reasoning_box_opened", False): + # Flush remaining reasoning buffer + buf = getattr(self, "_reasoning_buf", "") + if buf: + _cprint(f"{_DIM}{buf}{_RST}") + self._reasoning_buf = "" + w = shutil.get_terminal_size().columns + _cprint(f"{_DIM}└{'─' * (w - 2)}┘{_RST}") + self._reasoning_box_opened = False + + # Flush any content that was deferred while reasoning was rendering. + deferred = getattr(self, "_deferred_content", "") + if deferred: + self._deferred_content = "" + self._emit_stream_text(deferred) + + def _stream_delta(self, text) -> None: + """Line-buffered streaming callback for real-time token rendering. + + Receives text deltas from the agent as tokens arrive. Buffers + partial lines and emits complete lines via _cprint to work + reliably with prompt_toolkit's patch_stdout. + + Reasoning/thinking blocks (, , etc.) + are suppressed during streaming since they'd display raw XML tags. + The agent strips them from the final response anyway. + + A ``None`` value signals an intermediate turn boundary (tools are + about to execute). Flushes any open boxes and resets state so + tool feed lines render cleanly between turns. + """ + if text is None: + self._flush_stream() + self._reset_stream_state() + return + if not text: + return + + self._stream_started = True + + # ── Tag-based reasoning suppression ── + # Track whether we're inside a reasoning/thinking block. + # These tags are model-generated (system prompt tells the model + # to use them) and get stripped from final_response. We must + # suppress them during streaming too — unless show_reasoning is + # enabled, in which case we route the inner content to the + # reasoning display box instead of discarding it. + _OPEN_TAGS = ("", "", "", "", "", "") + _CLOSE_TAGS = ("", "", "", "", "", "") + + # Append to a pre-filter buffer first + self._stream_prefilt = getattr(self, "_stream_prefilt", "") + text + + # Check if we're entering a reasoning block. + # Only match tags that appear at a "block boundary": start of the + # stream, after a newline (with optional whitespace), or when nothing + # but whitespace has been emitted on the current line. + # This prevents false positives when models *mention* tags in prose + # like "(/think not producing tags)". + # + # _stream_last_was_newline tracks whether the last character emitted + # (or the start of the stream) is a line boundary. It's True at + # stream start and set True whenever emitted text ends with '\n'. + if not hasattr(self, "_stream_last_was_newline"): + self._stream_last_was_newline = True # start of stream = boundary + + if not getattr(self, "_in_reasoning_block", False): + for tag in _OPEN_TAGS: + search_start = 0 + while True: + idx = self._stream_prefilt.find(tag, search_start) + if idx == -1: + break + # Check if this is a block boundary position + preceding = self._stream_prefilt[:idx] + if idx == 0: + # At buffer start — only a boundary if we're at + # a line start (stream start or last emit ended + # with newline) + is_block_boundary = getattr(self, "_stream_last_was_newline", True) + else: + # Find last newline in the buffer before the tag + last_nl = preceding.rfind("\n") + if last_nl == -1: + # No newline in buffer — boundary only if + # last emit was a newline AND only whitespace + # has accumulated before the tag + is_block_boundary = ( + getattr(self, "_stream_last_was_newline", True) + and preceding.strip() == "" + ) + else: + # Text between last newline and tag must be + # whitespace-only + is_block_boundary = preceding[last_nl + 1:].strip() == "" + if is_block_boundary: + # Emit everything before the tag + if preceding: + self._emit_stream_text(preceding) + self._stream_last_was_newline = preceding.endswith("\n") + self._in_reasoning_block = True + self._stream_prefilt = self._stream_prefilt[idx + len(tag):] + break + # Not a block boundary — keep searching after this occurrence + search_start = idx + 1 + if getattr(self, "_in_reasoning_block", False): + break + + # Could also be a partial open tag at the end — hold it back + if not getattr(self, "_in_reasoning_block", False): + # Check for partial tag match at the end + safe = self._stream_prefilt + for tag in _OPEN_TAGS: + for i in range(1, len(tag)): + if self._stream_prefilt.endswith(tag[:i]): + safe = self._stream_prefilt[:-i] + break + if safe: + self._emit_stream_text(safe) + self._stream_last_was_newline = safe.endswith("\n") + self._stream_prefilt = self._stream_prefilt[len(safe):] + return + + # Inside a reasoning block — look for close tag. + # Keep accumulating _stream_prefilt because close tags can arrive + # split across multiple tokens (e.g. "..."). + if getattr(self, "_in_reasoning_block", False): + for tag in _CLOSE_TAGS: + idx = self._stream_prefilt.find(tag) + if idx != -1: + self._in_reasoning_block = False + # When show_reasoning is on, route inner content to + # the reasoning display box instead of discarding. + if self.show_reasoning: + inner = self._stream_prefilt[:idx] + if inner: + self._stream_reasoning_delta(inner) + after = self._stream_prefilt[idx + len(tag):] + self._stream_prefilt = "" + # Process remaining text after close tag through full + # filtering (it could contain another open tag) + if after: + self._stream_delta(after) + return + # When show_reasoning is on, stream reasoning content live + # instead of silently accumulating. Keep only the tail that + # could be a partial close tag prefix. + max_tag_len = max(len(t) for t in _CLOSE_TAGS) + if len(self._stream_prefilt) > max_tag_len: + if self.show_reasoning: + # Route the safe prefix to reasoning display + safe_reasoning = self._stream_prefilt[:-max_tag_len] + self._stream_reasoning_delta(safe_reasoning) + self._stream_prefilt = self._stream_prefilt[-max_tag_len:] + return + + def _emit_stream_text(self, text: str) -> None: + """Emit filtered text to the streaming display.""" + if not text: + return + + # When show_reasoning is on and reasoning is still rendering, + # defer content until the reasoning box closes. This ensures the + # reasoning block always appears BEFORE the response in the terminal. + if self.show_reasoning and getattr(self, "_reasoning_box_opened", False): + self._deferred_content = getattr(self, "_deferred_content", "") + text + return + + # Close the live reasoning box before opening the response box + self._close_reasoning_box() + + # Open the response box header on the very first visible text + if not self._stream_box_opened: + # Strip leading whitespace/newlines before first visible content + text = text.lstrip("\n") + if not text: + return + self._stream_box_opened = True + try: + from hermes_cli.skin_engine import get_active_skin + _skin = get_active_skin() + label = _skin.get_branding("response_label", "⚕ Hermes") + _text_hex = _skin.get_color("banner_text", "#FFF8DC") + except Exception: + label = "⚕ Hermes" + _text_hex = "#FFF8DC" + # Build a true-color ANSI escape for the response text color + # so streamed content matches the Rich Panel appearance. + try: + _r = int(_text_hex[1:3], 16) + _g = int(_text_hex[3:5], 16) + _b = int(_text_hex[5:7], 16) + self._stream_text_ansi = f"\033[38;2;{_r};{_g};{_b}m" + except (ValueError, IndexError): + self._stream_text_ansi = "" + w = shutil.get_terminal_size().columns + fill = w - 2 - len(label) + _cprint(f"\n{_ACCENT}╭─{label}{'─' * max(fill - 1, 0)}╮{_RST}") + + self._stream_buf += text + + # Emit complete lines, keep partial remainder in buffer + _tc = getattr(self, "_stream_text_ansi", "") + while "\n" in self._stream_buf: + line, self._stream_buf = self._stream_buf.split("\n", 1) + _cprint(f"{_tc}{line}{_RST}" if _tc else line) + + def _flush_stream(self) -> None: + """Emit any remaining partial line from the stream buffer and close the box.""" + # If we're still inside a "reasoning block" at end-of-stream, it was + # a false positive — the model mentioned a tag like in prose + # but never closed it. Recover the buffered content as regular text. + if getattr(self, "_in_reasoning_block", False) and getattr(self, "_stream_prefilt", ""): + self._in_reasoning_block = False + self._emit_stream_text(self._stream_prefilt) + self._stream_prefilt = "" + + # Close reasoning box if still open (in case no content tokens arrived) + self._close_reasoning_box() + + if self._stream_buf: + _tc = getattr(self, "_stream_text_ansi", "") + _cprint(f"{_tc}{self._stream_buf}{_RST}" if _tc else self._stream_buf) + self._stream_buf = "" + + # Close the response box + if self._stream_box_opened: + w = shutil.get_terminal_size().columns + _cprint(f"{_ACCENT}╰{'─' * (w - 2)}╯{_RST}") + + def _reset_stream_state(self) -> None: + """Reset streaming state before each agent invocation.""" + self._stream_buf = "" + self._stream_started = False + self._stream_box_opened = False + self._stream_text_ansi = "" + self._stream_prefilt = "" + self._in_reasoning_block = False + self._stream_last_was_newline = True + self._reasoning_box_opened = False + self._reasoning_buf = "" + self._reasoning_preview_buf = "" + self._deferred_content = "" + + def _slow_command_status(self, command: str) -> str: + """Return a user-facing status message for slower slash commands.""" + cmd_lower = command.lower().strip() + if cmd_lower.startswith("/skills search"): + return "Searching skills..." + if cmd_lower.startswith("/skills browse"): + return "Loading skills..." + if cmd_lower.startswith("/skills inspect"): + return "Inspecting skill..." + if cmd_lower.startswith("/skills install"): + return "Installing skill..." + if cmd_lower.startswith("/skills"): + return "Processing skills command..." + if cmd_lower == "/reload-mcp": + return "Reloading MCP servers..." + if cmd_lower.startswith("/browser"): + return "Configuring browser..." + return "Processing command..." + + def _command_spinner_frame(self) -> str: + """Return the current spinner frame for slow slash commands.""" + import time as _time + + frame_idx = int(_time.monotonic() * 10) % len(_COMMAND_SPINNER_FRAMES) + return _COMMAND_SPINNER_FRAMES[frame_idx] + + @contextmanager + def _busy_command(self, status: str): + """Expose a temporary busy state in the TUI while a slash command runs.""" + self._command_running = True + self._command_status = status + self._invalidate(min_interval=0.0) + try: + print(f"⏳ {status}") + yield + finally: + self._command_running = False + self._command_status = "" + self._invalidate(min_interval=0.0) + + def _ensure_runtime_credentials(self) -> bool: + """ + Ensure runtime credentials are resolved before agent use. + Re-resolves provider credentials so key rotation and token refresh + are picked up without restarting the CLI. + Returns True if credentials are ready, False on auth failure. + """ + from hermes_cli.runtime_provider import ( + resolve_runtime_provider, + format_runtime_provider_error, + ) + + try: + runtime = resolve_runtime_provider( + requested=self.requested_provider, + explicit_api_key=self._explicit_api_key, + explicit_base_url=self._explicit_base_url, + ) + except Exception as exc: + message = format_runtime_provider_error(exc) + ChatConsole().print(f"[bold red]{message}[/]") + return False + + api_key = runtime.get("api_key") + base_url = runtime.get("base_url") + resolved_provider = runtime.get("provider", "openrouter") + resolved_api_mode = runtime.get("api_mode", self.api_mode) + resolved_acp_command = runtime.get("command") + resolved_acp_args = list(runtime.get("args") or []) + resolved_credential_pool = runtime.get("credential_pool") + if not isinstance(api_key, str) or not api_key: + # Custom / local endpoints (llama.cpp, ollama, vLLM, etc.) often + # don't require authentication. When a base_url IS configured but + # no API key was found, use a placeholder so the OpenAI SDK + # doesn't reject the request and local servers just ignore it. + _source = runtime.get("source", "") + _has_custom_base = isinstance(base_url, str) and base_url and "openrouter.ai" not in base_url + if _has_custom_base: + api_key = "no-key-required" + logger.debug( + "No API key for custom endpoint %s (source=%s), " + "using placeholder — local servers typically ignore auth", + base_url, _source, + ) + else: + print("\n⚠️ Provider resolver returned an empty API key. " + "Set OPENROUTER_API_KEY or run: hermes setup") + return False + if not isinstance(base_url, str) or not base_url: + print("\n⚠️ Provider resolver returned an empty base URL. " + "Check your provider config or run: hermes setup") + return False + + credentials_changed = api_key != self.api_key or base_url != self.base_url + routing_changed = ( + resolved_provider != self.provider + or resolved_api_mode != self.api_mode + or resolved_acp_command != self.acp_command + or resolved_acp_args != self.acp_args + ) + self.provider = resolved_provider + self.api_mode = resolved_api_mode + self.acp_command = resolved_acp_command + self.acp_args = resolved_acp_args + self._credential_pool = resolved_credential_pool + self._provider_source = runtime.get("source") + self.api_key = api_key + self.base_url = base_url + + # When a custom_provider entry carries an explicit `model` field, + # use it as the effective model name. Without this, running + # `hermes chat --model ` sends the provider name + # (e.g. "my-provider") as the model string to the API instead of + # the configured model (e.g. "qwen3.6-plus"), causing 400 errors. + runtime_model = runtime.get("model") + if runtime_model and isinstance(runtime_model, str): + self.model = runtime_model + + # If model is still empty (e.g. user ran `hermes auth add openai-codex` + # without `hermes model`), fall back to the provider's first catalog + # model so the API call doesn't fail with "model must be non-empty". + if not self.model and resolved_provider: + try: + from hermes_cli.models import get_default_model_for_provider + _default = get_default_model_for_provider(resolved_provider) + if _default: + self.model = _default + logger.info( + "No model configured — defaulting to %s for provider %s", + _default, resolved_provider, + ) + except Exception: + pass + + # Normalize model for the resolved provider (e.g. swap non-Codex + # models when provider is openai-codex). Fixes #651. + model_changed = self._normalize_model_for_provider(resolved_provider) + + # AIAgent/OpenAI client holds auth at init time, so rebuild if key, + # routing, or the effective model changed. + if (credentials_changed or routing_changed or model_changed) and self.agent is not None: + self.agent = None + self._active_agent_route_signature = None + + return True + + def _resolve_turn_agent_config(self, user_message: str) -> dict: + """Resolve model/runtime overrides for a single user turn.""" + from agent.smart_model_routing import resolve_turn_route + from hermes_cli.models import resolve_fast_mode_overrides + + route = resolve_turn_route( + user_message, + self._smart_model_routing, + { + "model": self.model, + "api_key": self.api_key, + "base_url": self.base_url, + "provider": self.provider, + "api_mode": self.api_mode, + "command": self.acp_command, + "args": list(self.acp_args or []), + "credential_pool": getattr(self, "_credential_pool", None), + }, + ) + + service_tier = getattr(self, "service_tier", None) + if not service_tier: + route["request_overrides"] = None + return route + + try: + overrides = resolve_fast_mode_overrides(route.get("model")) + except Exception: + overrides = None + route["request_overrides"] = overrides + return route + + def _init_agent(self, *, model_override: str = None, runtime_override: dict = None, route_label: str = None, request_overrides: dict | None = None) -> bool: + """ + Initialize the agent on first use. + When resuming a session, restores conversation history from SQLite. + + Returns: + bool: True if successful, False otherwise + """ + if self.agent is not None: + return True + + if not self._ensure_runtime_credentials(): + return False + + # Initialize SQLite session store for CLI sessions (if not already done in __init__) + if self._session_db is None: + try: + from hermes_state import SessionDB + self._session_db = SessionDB() + except Exception as e: + logger.warning("SQLite session store not available — session will NOT be indexed: %s", e) + + # If resuming, validate the session exists and load its history. + # _preload_resumed_session() may have already loaded it (called from + # run() for immediate display). In that case, conversation_history + # is non-empty and we skip the DB round-trip. + if self._resumed and self._session_db and not self.conversation_history: + session_meta = self._session_db.get_session(self.session_id) + if not session_meta: + _cprint(f"\033[1;31mSession not found: {self.session_id}{_RST}") + _cprint(f"{_DIM}Use a session ID from a previous CLI run (hermes sessions list).{_RST}") + return False + restored = self._session_db.get_messages_as_conversation(self.session_id) + if restored: + restored = [m for m in restored if m.get("role") != "session_meta"] + self.conversation_history = restored + msg_count = len([m for m in restored if m.get("role") == "user"]) + title_part = "" + if session_meta.get("title"): + title_part = f" \"{session_meta['title']}\"" + ChatConsole().print( + f"[bold {_accent_hex()}]↻ Resumed session[/] " + f"[bold]{_escape(self.session_id)}[/]" + f"[bold {_accent_hex()}]{_escape(title_part)}[/] " + f"({msg_count} user message{'s' if msg_count != 1 else ''}, {len(restored)} total messages)" + ) + else: + ChatConsole().print( + f"[bold {_accent_hex()}]Session {_escape(self.session_id)} found but has no messages. Starting fresh.[/]" + ) + # Re-open the session (clear ended_at so it's active again) + try: + self._session_db._conn.execute( + "UPDATE sessions SET ended_at = NULL, end_reason = NULL WHERE id = ?", + (self.session_id,), + ) + self._session_db._conn.commit() + except Exception: + pass + + try: + runtime = runtime_override or { + "api_key": self.api_key, + "base_url": self.base_url, + "provider": self.provider, + "api_mode": self.api_mode, + "command": self.acp_command, + "args": list(self.acp_args or []), + "credential_pool": getattr(self, "_credential_pool", None), + } + effective_model = model_override or self.model + self.agent = AIAgent( + model=effective_model, + api_key=runtime.get("api_key"), + base_url=runtime.get("base_url"), + provider=runtime.get("provider"), + api_mode=runtime.get("api_mode"), + acp_command=runtime.get("command"), + acp_args=runtime.get("args"), + credential_pool=runtime.get("credential_pool"), + max_iterations=self.max_turns, + enabled_toolsets=self.enabled_toolsets, + verbose_logging=self.verbose, + quiet_mode=not self.verbose, + ephemeral_system_prompt=self.system_prompt if self.system_prompt else None, + prefill_messages=self.prefill_messages or None, + reasoning_config=self.reasoning_config, + service_tier=self.service_tier, + request_overrides=request_overrides, + providers_allowed=self._providers_only, + providers_ignored=self._providers_ignore, + providers_order=self._providers_order, + provider_sort=self._provider_sort, + provider_require_parameters=self._provider_require_params, + provider_data_collection=self._provider_data_collection, + session_id=self.session_id, + platform="cli", + session_db=self._session_db, + clarify_callback=self._clarify_callback, + reasoning_callback=self._current_reasoning_callback(), + + fallback_model=self._fallback_model, + thinking_callback=self._on_thinking, + checkpoints_enabled=self.checkpoints_enabled, + checkpoint_max_snapshots=self.checkpoint_max_snapshots, + pass_session_id=self.pass_session_id, + tool_progress_callback=self._on_tool_progress, + tool_start_callback=self._on_tool_start if self._inline_diffs_enabled else None, + tool_complete_callback=self._on_tool_complete if self._inline_diffs_enabled else None, + stream_delta_callback=self._stream_delta if self.streaming_enabled else None, + tool_gen_callback=self._on_tool_gen_start if self.streaming_enabled else None, + ) + # Store reference for atexit memory provider shutdown + global _active_agent_ref + _active_agent_ref = self.agent + # Route agent status output through prompt_toolkit so ANSI escape + # sequences aren't garbled by patch_stdout's StdoutProxy (#2262). + self.agent._print_fn = _cprint + self._active_agent_route_signature = ( + effective_model, + runtime.get("provider"), + runtime.get("base_url"), + runtime.get("api_mode"), + runtime.get("command"), + tuple(runtime.get("args") or ()), + ) + + if self._pending_title and self._session_db: + try: + self._session_db.set_session_title(self.session_id, self._pending_title) + _cprint(f" Session title applied: {self._pending_title}") + self._pending_title = None + except (ValueError, Exception) as e: + _cprint(f" Could not apply pending title: {e}") + self._pending_title = None + return True + except Exception as e: + ChatConsole().print(f"[bold red]Failed to initialize agent: {e}[/]") + return False + + def show_banner(self): + """Display the welcome banner in Claude Code style.""" + self.console.clear() + + # Get context length for display before branching so it remains + # available to the low-context warning logic in compact mode too. + ctx_len = None + if hasattr(self, 'agent') and self.agent and hasattr(self.agent, 'context_compressor'): + ctx_len = self.agent.context_compressor.context_length + + # Auto-compact for narrow terminals — the full banner with caduceus + # + tool list needs ~80 columns minimum to render without wrapping. + term_width = shutil.get_terminal_size().columns + use_compact = self.compact or term_width < 80 + + if use_compact: + self.console.print(_build_compact_banner()) + self._show_status() + else: + # Get tools for display + tools = get_tool_definitions(enabled_toolsets=self.enabled_toolsets, quiet_mode=True) + + # Get terminal working directory (where commands will execute) + cwd = os.getenv("TERMINAL_CWD", os.getcwd()) + + # Build and display the banner + build_welcome_banner( + console=self.console, + model=self.model, + cwd=cwd, + tools=tools, + enabled_toolsets=self.enabled_toolsets, + session_id=self.session_id, + context_length=ctx_len, + ) + + # Show tool availability warnings if any tools are disabled + self._show_tool_availability_warnings() + + # Warn about very low context lengths (common with local servers) + if ctx_len and ctx_len <= 8192: + self.console.print() + self.console.print( + f"[yellow]⚠️ Context length is only {ctx_len:,} tokens — " + f"this is likely too low for agent use with tools.[/]" + ) + self.console.print( + "[dim] Hermes needs 16k–32k minimum. Tool schemas + system prompt alone use ~4k–8k.[/]" + ) + base_url = getattr(self, "base_url", "") or "" + if "11434" in base_url or "ollama" in base_url.lower(): + self.console.print( + "[dim] Ollama fix: OLLAMA_CONTEXT_LENGTH=32768 ollama serve[/]" + ) + elif "1234" in base_url: + self.console.print( + "[dim] LM Studio fix: Set context length in model settings → reload model[/]" + ) + else: + self.console.print( + "[dim] Fix: Set model.context_length in config.yaml, or increase your server's context setting[/]" + ) + + # Warn if the configured model is a Nous Hermes LLM (not agentic) + from hermes_cli.model_switch import is_nous_hermes_non_agentic + + model_name = getattr(self, "model", "") or "" + if is_nous_hermes_non_agentic(model_name): + self.console.print() + self.console.print( + "[bold yellow]⚠ Nous Research Hermes 3 & 4 models are NOT agentic and are not " + "designed for use with Hermes Agent.[/]" + ) + self.console.print( + "[dim] They lack tool-calling capabilities required for agent workflows. " + "Consider using an agentic model (Claude, GPT, Gemini, DeepSeek, etc.).[/]" + ) + self.console.print( + "[dim] Switch with: /model sonnet or /model gpt5[/]" + ) + + self.console.print() + + def _preload_resumed_session(self) -> bool: + """Load a resumed session's history from the DB early (before first chat). + + Called from run() so the conversation history is available for display + before the user sends their first message. Sets + ``self.conversation_history`` and prints the one-liner status. Returns + True if history was loaded, False otherwise. + + The corresponding block in ``_init_agent()`` checks whether history is + already populated and skips the DB round-trip. + """ + if not self._resumed or not self._session_db: + return False + + session_meta = self._session_db.get_session(self.session_id) + if not session_meta: + self.console.print( + f"[bold red]Session not found: {self.session_id}[/]" + ) + self.console.print( + "[dim]Use a session ID from a previous CLI run " + "(hermes sessions list).[/]" + ) + return False + + restored = self._session_db.get_messages_as_conversation(self.session_id) + if restored: + restored = [m for m in restored if m.get("role") != "session_meta"] + self.conversation_history = restored + msg_count = len([m for m in restored if m.get("role") == "user"]) + title_part = "" + if session_meta.get("title"): + title_part = f' "{session_meta["title"]}"' + accent_color = _accent_hex() + self.console.print( + f"[{accent_color}]↻ Resumed session [bold]{self.session_id}[/bold]" + f"{title_part} " + f"({msg_count} user message{'s' if msg_count != 1 else ''}, " + f"{len(restored)} total messages)[/]" + ) + else: + accent_color = _accent_hex() + self.console.print( + f"[{accent_color}]Session {self.session_id} found but has no " + f"messages. Starting fresh.[/]" + ) + return False + + # Re-open the session (clear ended_at so it's active again) + try: + self._session_db._conn.execute( + "UPDATE sessions SET ended_at = NULL, end_reason = NULL " + "WHERE id = ?", + (self.session_id,), + ) + self._session_db._conn.commit() + except Exception: + pass + + return True + + def _display_resumed_history(self): + """Render a compact recap of previous conversation messages. + + Uses Rich markup with dim/muted styling so the recap is visually + distinct from the active conversation. Caps the display at the + last ``MAX_DISPLAY_EXCHANGES`` user/assistant exchanges and shows + an indicator for earlier hidden messages. + """ + if not self.conversation_history: + return + + # Check config: resume_display setting + if self.resume_display == "minimal": + return + + MAX_DISPLAY_EXCHANGES = 10 # max user+assistant pairs to show + MAX_USER_LEN = 300 # truncate user messages + MAX_ASST_LEN = 200 # truncate assistant text + MAX_ASST_LINES = 3 # max lines of assistant text + + def _strip_reasoning(text: str) -> str: + """Remove ... blocks + from displayed text (reasoning model internal thoughts).""" + import re + cleaned = re.sub( + r".*?\s*", + "", text, flags=re.DOTALL, + ) + # Also strip unclosed reasoning tags at the end + cleaned = re.sub( + r".*$", + "", cleaned, flags=re.DOTALL, + ) + return cleaned.strip() + + # Collect displayable entries (skip system, tool-result messages) + entries = [] # list of (role, display_text) + _last_asst_idx = None # index of last assistant entry + _last_asst_full = None # un-truncated display text for last assistant + for msg in self.conversation_history: + role = msg.get("role", "") + content = msg.get("content") + tool_calls = msg.get("tool_calls") or [] + + if role == "system": + continue + if role == "tool": + continue + + if role == "user": + text = "" if content is None else str(content) + # Handle multimodal content (list of dicts) + if isinstance(content, list): + parts = [] + for part in content: + if isinstance(part, dict) and part.get("type") == "text": + parts.append(part.get("text", "")) + elif isinstance(part, dict) and part.get("type") == "image_url": + parts.append("[image]") + text = " ".join(parts) + if len(text) > MAX_USER_LEN: + text = text[:MAX_USER_LEN] + "..." + entries.append(("user", text)) + + elif role == "assistant": + text = "" if content is None else str(content) + text = _strip_reasoning(text) + parts = [] + full_parts = [] # un-truncated version + if text: + full_parts.append(text) + lines = text.splitlines() + if len(lines) > MAX_ASST_LINES: + text = "\n".join(lines[:MAX_ASST_LINES]) + " ..." + if len(text) > MAX_ASST_LEN: + text = text[:MAX_ASST_LEN] + "..." + parts.append(text) + if tool_calls: + tc_count = len(tool_calls) + # Extract tool names + names = [] + for tc in tool_calls: + fn = tc.get("function", {}) + name = fn.get("name", "unknown") if isinstance(fn, dict) else "unknown" + if name not in names: + names.append(name) + names_str = ", ".join(names[:4]) + if len(names) > 4: + names_str += ", ..." + noun = "call" if tc_count == 1 else "calls" + tc_summary = f"[{tc_count} tool {noun}: {names_str}]" + parts.append(tc_summary) + full_parts.append(tc_summary) + if not parts: + # Skip pure-reasoning messages that have no visible output + continue + entries.append(("assistant", " ".join(parts))) + _last_asst_idx = len(entries) - 1 + _last_asst_full = " ".join(full_parts) + + if not entries: + return + + # Determine if we need to truncate + skipped = 0 + if len(entries) > MAX_DISPLAY_EXCHANGES * 2: + skipped = len(entries) - MAX_DISPLAY_EXCHANGES * 2 + entries = entries[skipped:] + + # Replace last assistant entry with full (un-truncated) text + # so the user can see where they left off without wasting tokens. + if _last_asst_idx is not None and _last_asst_full: + adj_idx = _last_asst_idx - skipped + if 0 <= adj_idx < len(entries): + entries[adj_idx] = ("assistant_last", _last_asst_full) + + # Build the display using Rich + from rich.panel import Panel + from rich.text import Text + + try: + from hermes_cli.skin_engine import get_active_skin + _skin = get_active_skin() + _history_text_c = _skin.get_color("banner_text", "#FFF8DC") + _session_label_c = _skin.get_color("session_label", "#DAA520") + _session_border_c = _skin.get_color("session_border", "#8B8682") + _assistant_label_c = _skin.get_color("ui_ok", "#8FBC8F") + except Exception: + _history_text_c = "#FFF8DC" + _session_label_c = "#DAA520" + _session_border_c = "#8B8682" + _assistant_label_c = "#8FBC8F" + + lines = Text() + if skipped: + lines.append( + f" ... {skipped} earlier messages ...\n\n", + style="dim italic", + ) + + for i, (role, text) in enumerate(entries): + if role == "user": + lines.append(" ● You: ", style=f"dim bold {_session_label_c}") + # Show first line inline, indent rest + msg_lines = text.splitlines() + lines.append(msg_lines[0] + "\n", style="dim") + for ml in msg_lines[1:]: + lines.append(f" {ml}\n", style="dim") + elif role == "assistant_last": + # Last assistant response shown in full, non-dim + lines.append(" ◆ Hermes: ", style=f"bold {_assistant_label_c}") + msg_lines = text.splitlines() + lines.append(msg_lines[0] + "\n", style="") + for ml in msg_lines[1:]: + lines.append(f" {ml}\n", style="") + else: + lines.append(" ◆ Hermes: ", style=f"dim bold {_assistant_label_c}") + msg_lines = text.splitlines() + lines.append(msg_lines[0] + "\n", style="dim") + for ml in msg_lines[1:]: + lines.append(f" {ml}\n", style="dim") + if i < len(entries) - 1: + lines.append("") # small gap + + panel = Panel( + lines, + title=f"[dim {_session_label_c}]Previous Conversation[/]", + border_style=f"dim {_session_border_c}", + padding=(0, 1), + style=_history_text_c, + ) + self.console.print(panel) + + def _try_attach_clipboard_image(self) -> bool: + """Check clipboard for an image and attach it if found. + + Saves the image to ~/.hermes/images/ and appends the path to + ``_attached_images``. Returns True if an image was attached. + """ + from hermes_cli.clipboard import save_clipboard_image + + img_dir = get_hermes_home() / "images" + self._image_counter += 1 + ts = datetime.now().strftime("%Y%m%d_%H%M%S") + img_path = img_dir / f"clip_{ts}_{self._image_counter}.png" + + if save_clipboard_image(img_path): + self._attached_images.append(img_path) + return True + self._image_counter -= 1 + return False + + def _handle_rollback_command(self, command: str): + """Handle /rollback — list, diff, or restore filesystem checkpoints. + + Syntax: + /rollback — list checkpoints + /rollback — restore checkpoint N (also undoes last chat turn) + /rollback diff — preview changes since checkpoint N + /rollback — restore a single file from checkpoint N + """ + from tools.checkpoint_manager import format_checkpoint_list + + if not hasattr(self, 'agent') or not self.agent: + print(" No active agent session.") + return + + mgr = self.agent._checkpoint_mgr + if not mgr.enabled: + print(" Checkpoints are not enabled.") + print(" Enable with: hermes --checkpoints") + print(" Or in config.yaml: checkpoints: { enabled: true }") + return + + cwd = os.getenv("TERMINAL_CWD", os.getcwd()) + parts = command.split() + args = parts[1:] if len(parts) > 1 else [] + + if not args: + # List checkpoints + checkpoints = mgr.list_checkpoints(cwd) + print(format_checkpoint_list(checkpoints, cwd)) + return + + # Handle /rollback diff + if args[0].lower() == "diff": + if len(args) < 2: + print(" Usage: /rollback diff ") + return + checkpoints = mgr.list_checkpoints(cwd) + if not checkpoints: + print(f" No checkpoints found for {cwd}") + return + target_hash = self._resolve_checkpoint_ref(args[1], checkpoints) + if not target_hash: + return + result = mgr.diff(cwd, target_hash) + if result["success"]: + stat = result.get("stat", "") + diff = result.get("diff", "") + if not stat and not diff: + print(" No changes since this checkpoint.") + else: + if stat: + print(f"\n{stat}") + if diff: + # Limit diff output to avoid terminal flood + diff_lines = diff.splitlines() + if len(diff_lines) > 80: + print("\n".join(diff_lines[:80])) + print(f"\n ... ({len(diff_lines) - 80} more lines, showing first 80)") + else: + print(f"\n{diff}") + else: + print(f" ❌ {result['error']}") + return + + # Resolve checkpoint reference (number or hash) + checkpoints = mgr.list_checkpoints(cwd) + if not checkpoints: + print(f" No checkpoints found for {cwd}") + return + + target_hash = self._resolve_checkpoint_ref(args[0], checkpoints) + if not target_hash: + return + + # Check for file-level restore: /rollback + file_path = args[1] if len(args) > 1 else None + + result = mgr.restore(cwd, target_hash, file_path=file_path) + if result["success"]: + if file_path: + print(f" ✅ Restored {file_path} from checkpoint {result['restored_to']}: {result['reason']}") + else: + print(f" ✅ Restored to checkpoint {result['restored_to']}: {result['reason']}") + print(" A pre-rollback snapshot was saved automatically.") + + # Also undo the last conversation turn so the agent's context + # matches the restored filesystem state + if self.conversation_history: + self.undo_last() + print(" Chat turn undone to match restored file state.") + else: + print(f" ❌ {result['error']}") + + def _resolve_checkpoint_ref(self, ref: str, checkpoints: list) -> str | None: + """Resolve a checkpoint number or hash to a full commit hash.""" + try: + idx = int(ref) - 1 # 1-indexed for user + if 0 <= idx < len(checkpoints): + return checkpoints[idx]["hash"] + else: + print(f" Invalid checkpoint number. Use 1-{len(checkpoints)}.") + return None + except ValueError: + # Treat as a git hash + return ref + + def _handle_snapshot_command(self, command: str): + """Handle /snapshot — lightweight state snapshots for Hermes config/state. + + Syntax: + /snapshot — list recent snapshots + /snapshot create [label] — create a snapshot + /snapshot restore — restore state from snapshot + /snapshot prune [N] — prune to N snapshots (default 20) + """ + from hermes_cli.backup import ( + create_quick_snapshot, list_quick_snapshots, + restore_quick_snapshot, prune_quick_snapshots, + ) + from hermes_constants import display_hermes_home + + parts = command.split() + subcmd = parts[1].lower() if len(parts) > 1 else "list" + + if subcmd in ("list", "ls"): + snaps = list_quick_snapshots() + if not snaps: + print(" No state snapshots yet.") + print(" Create one: /snapshot create [label]") + return + print(f" State snapshots ({display_hermes_home()}/state-snapshots/):\n") + print(f" {'#':>3} {'ID':<35} {'Files':>5} {'Size':>10} {'Label'}") + print(f" {'─'*3} {'─'*35} {'─'*5} {'─'*10} {'─'*20}") + for i, s in enumerate(snaps, 1): + size = s.get("total_size", 0) + if size < 1024: + size_str = f"{size} B" + elif size < 1024 * 1024: + size_str = f"{size / 1024:.0f} KB" + else: + size_str = f"{size / 1024 / 1024:.1f} MB" + label = s.get("label") or "" + print(f" {i:3} {s['id']:<35} {s.get('file_count', 0):>5} {size_str:>10} {label}") + + elif subcmd == "create": + label = " ".join(parts[2:]) if len(parts) > 2 else None + snap_id = create_quick_snapshot(label=label) + if snap_id: + print(f" Snapshot created: {snap_id}") + else: + print(" No state files found to snapshot.") + + elif subcmd in ("restore", "rewind"): + if len(parts) < 3: + print(" Usage: /snapshot restore ") + # Show hint with most recent snapshot + snaps = list_quick_snapshots(limit=1) + if snaps: + print(f" Most recent: {snaps[0]['id']}") + return + snap_id = parts[2] + # Allow restore by number (1-indexed) + try: + idx = int(snap_id) + snaps = list_quick_snapshots() + if 1 <= idx <= len(snaps): + snap_id = snaps[idx - 1]["id"] + else: + print(f" Invalid snapshot number. Use 1-{len(snaps)}.") + return + except ValueError: + pass + if restore_quick_snapshot(snap_id): + print(f" Restored state from: {snap_id}") + print(" Restart recommended for state.db changes to take effect.") + else: + print(f" Snapshot not found: {snap_id}") + + elif subcmd == "prune": + keep = 20 + if len(parts) > 2: + try: + keep = int(parts[2]) + except ValueError: + print(" Usage: /snapshot prune [keep-count]") + return + deleted = prune_quick_snapshots(keep=keep) + print(f" Pruned {deleted} old snapshot(s) (keeping {keep}).") + + else: + print(f" Unknown subcommand: {subcmd}") + print(" Usage: /snapshot [list|create [label]|restore |prune [N]]") + + def _handle_stop_command(self): + """Handle /stop — kill all running background processes. + + Inspired by OpenAI Codex's separation of interrupt (stop current turn) + from /stop (clean up background processes). See openai/codex#14602. + """ + from tools.process_registry import process_registry + + processes = process_registry.list_sessions() + running = [p for p in processes if p.get("status") == "running"] + + if not running: + print(" No running background processes.") + return + + print(f" Stopping {len(running)} background process(es)...") + killed = process_registry.kill_all() + print(f" ✅ Stopped {killed} process(es).") + + def _handle_paste_command(self): + """Handle /paste — explicitly check clipboard for an image. + + This is the reliable fallback for terminals where BracketedPaste + doesn't fire for image-only clipboard content (e.g., VSCode terminal, + Windows Terminal with WSL2). + """ + if _is_termux_environment(): + _cprint( + f" {_DIM}Clipboard image paste is not available on Termux — " + f"use /image or paste a local image path like " + f"{_termux_example_image_path()}{_RST}" + ) + return + + from hermes_cli.clipboard import has_clipboard_image + if has_clipboard_image(): + if self._try_attach_clipboard_image(): + n = len(self._attached_images) + _cprint(f" 📎 Image #{n} attached from clipboard") + else: + _cprint(f" {_DIM}(>_<) Clipboard has an image but extraction failed{_RST}") + else: + _cprint(f" {_DIM}(._.) No image found in clipboard{_RST}") + + def _handle_image_command(self, cmd_original: str): + """Handle /image — attach a local image file for the next prompt.""" + raw_args = (cmd_original.split(None, 1)[1].strip() if " " in cmd_original else "") + if not raw_args: + hint = _termux_example_image_path() if _is_termux_environment() else "/path/to/image.png" + _cprint(f" {_DIM}Usage: /image e.g. /image {hint}{_RST}") + return + + path_token, _remainder = _split_path_input(raw_args) + image_path = _resolve_attachment_path(path_token) + if image_path is None: + _cprint(f" {_DIM}(>_<) File not found: {path_token}{_RST}") + return + if image_path.suffix.lower() not in _IMAGE_EXTENSIONS: + _cprint(f" {_DIM}(._.) Not a supported image file: {image_path.name}{_RST}") + return + + self._attached_images.append(image_path) + _cprint(f" 📎 Attached image: {image_path.name}") + if _remainder: + _cprint(f" {_DIM}Now type your prompt (or use --image in single-query mode): {_remainder}{_RST}") + elif _is_termux_environment(): + _cprint(f" {_DIM}Tip: type your next message, or run hermes chat -q --image {_termux_example_image_path(image_path.name)} \"What do you see?\"{_RST}") + + def _preprocess_images_with_vision(self, text: str, images: list, *, announce: bool = True) -> str: + """Analyze attached images via the vision tool and return enriched text. + + Instead of embedding raw base64 ``image_url`` content parts in the + conversation (which only works with vision-capable models), this + pre-processes each image through the auxiliary vision model (Gemini + Flash) and prepends the descriptions to the user's message — the + same approach the messaging gateway uses. + + The local file path is included so the agent can re-examine the + image later with ``vision_analyze`` if needed. + """ + import asyncio as _asyncio + import json as _json + from tools.vision_tools import vision_analyze_tool + + analysis_prompt = ( + "Describe everything visible in this image in thorough detail. " + "Include any text, code, data, objects, people, layout, colors, " + "and any other notable visual information." + ) + + enriched_parts = [] + for img_path in images: + if not img_path.exists(): + continue + size_kb = img_path.stat().st_size // 1024 + if announce: + _cprint(f" {_DIM}👁️ analyzing {img_path.name} ({size_kb}KB)...{_RST}") + try: + result_json = _asyncio.run( + vision_analyze_tool(image_url=str(img_path), user_prompt=analysis_prompt) + ) + result = _json.loads(result_json) + if result.get("success"): + description = result.get("analysis", "") + enriched_parts.append( + f"[The user attached an image. Here's what it contains:\n{description}]\n" + f"[If you need a closer look, use vision_analyze with " + f"image_url: {img_path}]" + ) + if announce: + _cprint(f" {_DIM}✓ image analyzed{_RST}") + else: + enriched_parts.append( + f"[The user attached an image but it couldn't be analyzed. " + f"You can try examining it with vision_analyze using " + f"image_url: {img_path}]" + ) + if announce: + _cprint(f" {_DIM}⚠ vision analysis failed — path included for retry{_RST}") + except Exception as e: + enriched_parts.append( + f"[The user attached an image but analysis failed ({e}). " + f"You can try examining it with vision_analyze using " + f"image_url: {img_path}]" + ) + if announce: + _cprint(f" {_DIM}⚠ vision analysis error — path included for retry{_RST}") + + # Combine: vision descriptions first, then the user's original text + user_text = text if isinstance(text, str) and text else "" + if enriched_parts: + prefix = "\n\n".join(enriched_parts) + return f"{prefix}\n\n{user_text}" if user_text else prefix + return user_text or "What do you see in this image?" + + def _show_tool_availability_warnings(self): + """Show warnings about disabled tools due to missing API keys.""" + try: + from model_tools import check_tool_availability + + available, unavailable = check_tool_availability() + + # Filter to only those missing API keys (not system deps) + api_key_missing = [u for u in unavailable if u["missing_vars"]] + + if api_key_missing: + self.console.print() + self.console.print("[yellow]⚠️ Some tools disabled (missing API keys):[/]") + for item in api_key_missing: + tools_str = ", ".join(item["tools"][:2]) # Show first 2 tools + if len(item["tools"]) > 2: + tools_str += f", +{len(item['tools'])-2} more" + self.console.print(f" [dim]• {item['name']}[/] [dim italic]({', '.join(item['missing_vars'])})[/]") + self.console.print("[dim] Run 'hermes setup' to configure[/]") + except Exception: + pass # Don't crash on import errors + + def _show_status(self): + """Show compact startup status line.""" + # Get tool count + tools = get_tool_definitions(enabled_toolsets=self.enabled_toolsets, quiet_mode=True) + tool_count = len(tools) if tools else 0 + + # Format model name (shorten if needed) + model_short = self.model.split("/")[-1] if "/" in self.model else self.model + if len(model_short) > 30: + model_short = model_short[:27] + "..." + + # Get API status indicator + if self.api_key: + api_indicator = "[green bold]●[/]" + else: + api_indicator = "[red bold]●[/]" + + # Build status line with proper markup — skin-aware colors + try: + from hermes_cli.skin_engine import get_active_skin + skin = get_active_skin() + separator_color = skin.get_color("banner_dim", "#B8860B") + accent_color = skin.get_color("ui_accent", "#FFBF00") + label_color = skin.get_color("ui_label", "#4dd0e1") + except Exception: + separator_color, accent_color, label_color = "#B8860B", "#FFBF00", "cyan" + toolsets_info = "" + if self.enabled_toolsets and "all" not in self.enabled_toolsets: + toolsets_info = f" [dim {separator_color}]·[/] [{label_color}]toolsets: {', '.join(self.enabled_toolsets)}[/]" + + provider_info = f" [dim {separator_color}]·[/] [dim]provider: {self.provider}[/]" + if self._provider_source: + provider_info += f" [dim {separator_color}]·[/] [dim]auth: {self._provider_source}[/]" + + self.console.print( + f" {api_indicator} [{accent_color}]{model_short}[/] " + f"[dim {separator_color}]·[/] [bold {label_color}]{tool_count} tools[/]" + f"{toolsets_info}{provider_info}" + ) + + def _show_session_status(self): + """Show gateway-style status for the current CLI session.""" + session_meta = {} + if self._session_db: + try: + session_meta = self._session_db.get_session(self.session_id) or {} + except Exception: + session_meta = {} + + title = (session_meta.get("title") or "").strip() + + created_at = self.session_start + started_at = session_meta.get("started_at") + if started_at: + try: + created_at = datetime.fromtimestamp(float(started_at)) + except Exception: + created_at = self.session_start + + updated_at = created_at + for field in ("updated_at", "last_updated_at", "last_activity_at"): + value = session_meta.get(field) + if not value: + continue + try: + updated_at = datetime.fromtimestamp(float(value)) + break + except Exception: + pass + + agent = getattr(self, "agent", None) + total_tokens = getattr(agent, "session_total_tokens", 0) or 0 + provider = getattr(self, "provider", None) or "unknown" + model = getattr(self, "model", None) or "(unknown)" + is_running = bool(getattr(self, "_agent_running", False)) + + lines = [ + "Hermes CLI Status", + "", + f"Session ID: {self.session_id}", + f"Path: {display_hermes_home()}", + ] + if title: + lines.append(f"Title: {title}") + lines.extend([ + f"Model: {model} ({provider})", + f"Created: {created_at.strftime('%Y-%m-%d %H:%M')}", + f"Last Activity: {updated_at.strftime('%Y-%m-%d %H:%M')}", + f"Tokens: {total_tokens:,}", + f"Agent Running: {'Yes' if is_running else 'No'}", + ]) + self.console.print("\n".join(lines), highlight=False, markup=False) + + def _fast_command_available(self) -> bool: + try: + from hermes_cli.models import model_supports_fast_mode + except Exception: + return False + agent = getattr(self, "agent", None) + model = getattr(agent, "model", None) or getattr(self, "model", None) + return model_supports_fast_mode(model) + + def _command_available(self, slash_command: str) -> bool: + if slash_command == "/fast": + return self._fast_command_available() + return True + + def show_help(self): + """Display help information with categorized commands.""" + from hermes_cli.commands import COMMANDS_BY_CATEGORY + + try: + from hermes_cli.skin_engine import get_active_help_header + header = get_active_help_header("(^_^)? Available Commands") + except Exception: + header = "(^_^)? Available Commands" + header = (header or "").strip() or "(^_^)? Available Commands" + inner_width = 55 + if len(header) > inner_width: + header = header[:inner_width] + _cprint(f"\n{_BOLD}+{'-' * inner_width}+{_RST}") + _cprint(f"{_BOLD}|{header:^{inner_width}}|{_RST}") + _cprint(f"{_BOLD}+{'-' * inner_width}+{_RST}") + + for category, commands in COMMANDS_BY_CATEGORY.items(): + _cprint(f"\n {_BOLD}── {category} ──{_RST}") + for cmd, desc in commands.items(): + if not self._command_available(cmd): + continue + ChatConsole().print(f" [bold {_accent_hex()}]{cmd:<15}[/] [dim]-[/] {_escape(desc)}") + + if _skill_commands: + _cprint(f"\n ⚡ {_BOLD}Skill Commands{_RST} ({len(_skill_commands)} installed):") + for cmd, info in sorted(_skill_commands.items()): + ChatConsole().print( + f" [bold {_accent_hex()}]{cmd:<22}[/] [dim]-[/] {_escape(info['description'])}" + ) + + _cprint(f"\n {_DIM}Tip: Just type your message to chat with Hermes!{_RST}") + _cprint(f" {_DIM}Multi-line: Alt+Enter for a new line{_RST}") + if _is_termux_environment(): + _cprint(f" {_DIM}Attach image: /image {_termux_example_image_path()} or start your prompt with a local image path{_RST}\n") + else: + _cprint(f" {_DIM}Paste image: Alt+V (or /paste){_RST}\n") + + def show_tools(self): + """Display available tools with kawaii ASCII art.""" + tools = get_tool_definitions(enabled_toolsets=self.enabled_toolsets, quiet_mode=True) + + if not tools: + print("(;_;) No tools available") + return + + # Header + print() + title = "(^_^)/ Available Tools" + width = 78 + pad = width - len(title) + print("+" + "-" * width + "+") + print("|" + " " * (pad // 2) + title + " " * (pad - pad // 2) + "|") + print("+" + "-" * width + "+") + print() + + # Group tools by toolset + toolsets = {} + for tool in sorted(tools, key=lambda t: t["function"]["name"]): + name = tool["function"]["name"] + toolset = get_toolset_for_tool(name) or "unknown" + if toolset not in toolsets: + toolsets[toolset] = [] + desc = tool["function"].get("description", "") + # First sentence: split on ". " (period+space) to avoid breaking on "e.g." or "v2.0" + desc = desc.split("\n")[0] + if ". " in desc: + desc = desc[:desc.index(". ") + 1] + toolsets[toolset].append((name, desc)) + + # Display by toolset + for toolset in sorted(toolsets.keys()): + print(f" [{toolset}]") + for name, desc in toolsets[toolset]: + print(f" * {name:<20} - {desc}") + print() + + print(f" Total: {len(tools)} tools ヽ(^o^)ノ") + print() + + def _handle_tools_command(self, cmd: str): + """Handle /tools [list|disable|enable] slash commands. + + /tools (no args) shows the tool list. + /tools list shows enabled/disabled status per toolset. + /tools disable/enable saves the change to config and resets + the session so the new tool set takes effect cleanly (no + prompt-cache breakage mid-conversation). + """ + import shlex + from argparse import Namespace + from hermes_cli.tools_config import tools_disable_enable_command + + try: + parts = shlex.split(cmd) + except ValueError: + parts = cmd.split() + + subcommand = parts[1] if len(parts) > 1 else "" + if subcommand not in ("list", "disable", "enable"): + self.show_tools() + return + + if subcommand == "list": + tools_disable_enable_command( + Namespace(tools_action="list", platform="cli")) + return + + names = parts[2:] + if not names: + print(f"(._.) Usage: /tools {subcommand} [name ...]") + print(f" Built-in toolset: /tools {subcommand} web") + print(f" MCP tool: /tools {subcommand} github:create_issue") + return + + # Apply the change directly — the user typing the command is implicit + # consent. Do NOT use input() here; it hangs inside prompt_toolkit's + # TUI event loop (known pitfall). + verb = "Disabling" if subcommand == "disable" else "Enabling" + label = ", ".join(names) + _cprint(f"{_ACCENT}{verb} {label}...{_RST}") + + tools_disable_enable_command( + Namespace(tools_action=subcommand, names=names, platform="cli")) + + # Reset session so the new tool config is picked up from a clean state + from hermes_cli.tools_config import _get_platform_tools + from hermes_cli.config import load_config + self.enabled_toolsets = _get_platform_tools(load_config(), "cli") + self.new_session() + _cprint(f"{_DIM}Session reset. New tool configuration is active.{_RST}") + + def show_toolsets(self): + """Display available toolsets with kawaii ASCII art.""" + all_toolsets = get_all_toolsets() + + # Header + print() + title = "(^_^)b Available Toolsets" + width = 58 + pad = width - len(title) + print("+" + "-" * width + "+") + print("|" + " " * (pad // 2) + title + " " * (pad - pad // 2) + "|") + print("+" + "-" * width + "+") + print() + + for name in sorted(all_toolsets.keys()): + info = get_toolset_info(name) + if info: + tool_count = info["tool_count"] + desc = info["description"] + + # Mark if currently enabled + marker = "(*)" if self.enabled_toolsets and name in self.enabled_toolsets else " " + print(f" {marker} {name:<18} [{tool_count:>2} tools] - {desc}") + + print() + print(" (*) = currently enabled") + print() + print(" Tip: Use 'all' or '*' to enable all toolsets") + print(" Example: python cli.py --toolsets web,terminal") + print() + + def _handle_profile_command(self): + """Display active profile name and home directory.""" + from hermes_constants import get_hermes_home, display_hermes_home + + home = get_hermes_home() + display = display_hermes_home() + + profiles_parent = Path.home() / ".hermes" / "profiles" + try: + rel = home.relative_to(profiles_parent) + profile_name = str(rel).split("/")[0] + except ValueError: + profile_name = None + + print() + if profile_name: + print(f" Profile: {profile_name}") + else: + print(" Profile: default") + print(f" Home: {display}") + print() + + def show_config(self): + """Display current configuration with kawaii ASCII art.""" + # Get terminal config from environment (which was set from cli-config.yaml) + terminal_env = os.getenv("TERMINAL_ENV", "local") + terminal_cwd = os.getenv("TERMINAL_CWD", os.getcwd()) + terminal_timeout = os.getenv("TERMINAL_TIMEOUT", "60") + + user_config_path = _hermes_home / 'config.yaml' + project_config_path = Path(__file__).parent / 'cli-config.yaml' + if user_config_path.exists(): + config_path = user_config_path + else: + config_path = project_config_path + config_status = "(loaded)" if config_path.exists() else "(not found)" + + api_key_display = '********' + self.api_key[-4:] if self.api_key and len(self.api_key) > 4 else 'Not set!' + + print() + title = "(^_^) Configuration" + width = 50 + pad = width - len(title) + print("+" + "-" * width + "+") + print("|" + " " * (pad // 2) + title + " " * (pad - pad // 2) + "|") + print("+" + "-" * width + "+") + print() + print(" -- Model --") + print(f" Model: {self.model}") + print(f" Base URL: {self.base_url}") + print(f" API Key: {api_key_display}") + print() + print(" -- Terminal --") + print(f" Environment: {terminal_env}") + if terminal_env == "ssh": + ssh_host = os.getenv("TERMINAL_SSH_HOST", "not set") + ssh_user = os.getenv("TERMINAL_SSH_USER", "not set") + ssh_port = os.getenv("TERMINAL_SSH_PORT", "22") + print(f" SSH Target: {ssh_user}@{ssh_host}:{ssh_port}") + print(f" Working Dir: {terminal_cwd}") + print(f" Timeout: {terminal_timeout}s") + print() + print(" -- Agent --") + print(f" Max Turns: {self.max_turns}") + print(f" Toolsets: {', '.join(self.enabled_toolsets) if self.enabled_toolsets else 'all'}") + print(f" Verbose: {self.verbose}") + print() + print(" -- Session --") + print(f" Started: {self.session_start.strftime('%Y-%m-%d %H:%M:%S')}") + print(f" Config File: {config_path} {config_status}") + print() + + def _list_recent_sessions(self, limit: int = 10) -> list[dict[str, Any]]: + """Return recent CLI sessions for in-chat browsing/resume affordances.""" + if not self._session_db: + return [] + try: + sessions = self._session_db.list_sessions_rich( + source="cli", + exclude_sources=["tool"], + limit=limit, + ) + except Exception: + return [] + return [s for s in sessions if s.get("id") != self.session_id] + + def _show_recent_sessions(self, *, reason: str = "history", limit: int = 10) -> bool: + """Render recent sessions inline from the active chat TUI. + + Returns True when something was shown, False if no session list was available. + """ + sessions = self._list_recent_sessions(limit=limit) + if not sessions: + return False + + from hermes_cli.main import _relative_time + + print() + if reason == "history": + print("(._.) No messages in the current chat yet — here are recent sessions you can resume:") + else: + print(" Recent sessions:") + print() + print(f" {'Title':<32} {'Preview':<40} {'Last Active':<13} {'ID'}") + print(f" {'─' * 32} {'─' * 40} {'─' * 13} {'─' * 24}") + for session in sessions: + title = (session.get("title") or "—")[:30] + preview = (session.get("preview") or "")[:38] + last_active = _relative_time(session.get("last_active")) + print(f" {title:<32} {preview:<40} {last_active:<13} {session['id']}") + print() + print(" Use /resume to continue where you left off.") + print() + return True + + def show_history(self): + """Display conversation history.""" + if not self.conversation_history: + if not self._show_recent_sessions(reason="history"): + print("(._.) No conversation history yet.") + return + + preview_limit = 400 + visible_index = 0 + hidden_tool_messages = 0 + + def flush_tool_summary(): + nonlocal hidden_tool_messages + if not hidden_tool_messages: + return + + noun = "message" if hidden_tool_messages == 1 else "messages" + print("\n [Tools]") + print(f" ({hidden_tool_messages} tool {noun} hidden)") + hidden_tool_messages = 0 + + print() + print("+" + "-" * 50 + "+") + print("|" + " " * 12 + "(^_^) Conversation History" + " " * 11 + "|") + print("+" + "-" * 50 + "+") + + for msg in self.conversation_history: + role = msg.get("role", "unknown") + + if role == "tool": + hidden_tool_messages += 1 + continue + + if role not in {"user", "assistant"}: + continue + + flush_tool_summary() + visible_index += 1 + + content = msg.get("content") + content_text = "" if content is None else str(content) + + if role == "user": + print(f"\n [You #{visible_index}]") + print( + f" {content_text[:preview_limit]}{'...' if len(content_text) > preview_limit else ''}" + ) + continue + + print(f"\n [Hermes #{visible_index}]") + tool_calls = msg.get("tool_calls") or [] + if content_text: + preview = content_text[:preview_limit] + suffix = "..." if len(content_text) > preview_limit else "" + elif tool_calls: + tool_count = len(tool_calls) + noun = "call" if tool_count == 1 else "calls" + preview = f"(requested {tool_count} tool {noun})" + suffix = "" + else: + preview = "(no text response)" + suffix = "" + print(f" {preview}{suffix}") + + 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: + try: + 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: + try: + self._session_db.end_session(old_session_id, "new_session") + except Exception: + pass + + self.session_start = datetime.now() + timestamp_str = self.session_start.strftime("%Y%m%d_%H%M%S") + short_uuid = uuid.uuid4().hex[:6] + self.session_id = f"{timestamp_str}_{short_uuid}" + self.conversation_history = [] + self._pending_title = None + self._resumed = False + + if self.agent: + self.agent.session_id = self.session_id + self.agent.session_start = self.session_start + self.agent.reset_session_state() + if hasattr(self.agent, "_last_flushed_db_idx"): + self.agent._last_flushed_db_idx = 0 + if hasattr(self.agent, "_todo_store"): + try: + from tools.todo_tool import TodoStore + self.agent._todo_store = TodoStore() + except Exception: + pass + if hasattr(self.agent, "_invalidate_system_prompt"): + self.agent._invalidate_system_prompt() + + if self._session_db: + try: + self._session_db.create_session( + session_id=self.session_id, + source=os.environ.get("HERMES_SESSION_SOURCE", "cli"), + model=self.model, + model_config={ + "max_iterations": self.max_turns, + "reasoning_config": self.reasoning_config, + }, + ) + except Exception: + pass + self._notify_session_boundary("on_session_reset") + + if not silent: + print("(^_^)v New session started!") + + def _handle_resume_command(self, cmd_original: str) -> None: + """Handle /resume — switch to a previous session mid-conversation.""" + parts = cmd_original.split(None, 1) + target = parts[1].strip() if len(parts) > 1 else "" + + if not target: + _cprint(" Usage: /resume ") + if self._show_recent_sessions(reason="resume"): + return + _cprint(" Tip: Use /history or `hermes sessions list` to find sessions.") + return + + if not self._session_db: + _cprint(" Session database not available.") + return + + # Resolve title or ID + from hermes_cli.main import _resolve_session_by_name_or_id + resolved = _resolve_session_by_name_or_id(target) + target_id = resolved or target + + session_meta = self._session_db.get_session(target_id) + if not session_meta: + _cprint(f" Session not found: {target}") + _cprint(" Use /history or `hermes sessions list` to see available sessions.") + return + + if target_id == self.session_id: + _cprint(" Already on that session.") + return + + # End current session + try: + self._session_db.end_session(self.session_id, "resumed_other") + except Exception: + pass + + # Switch to the target session + self.session_id = target_id + self._resumed = True + self._pending_title = None + + # Load conversation history (strip transcript-only metadata entries) + restored = self._session_db.get_messages_as_conversation(target_id) + restored = [m for m in (restored or []) if m.get("role") != "session_meta"] + self.conversation_history = restored + + # Re-open the target session so it's not marked as ended + try: + self._session_db.reopen_session(target_id) + except Exception: + pass + + # Sync the agent if already initialised + if self.agent: + self.agent.session_id = target_id + self.agent.reset_session_state() + if hasattr(self.agent, "_last_flushed_db_idx"): + self.agent._last_flushed_db_idx = len(self.conversation_history) + if hasattr(self.agent, "_todo_store"): + try: + from tools.todo_tool import TodoStore + self.agent._todo_store = TodoStore() + except Exception: + pass + if hasattr(self.agent, "_invalidate_system_prompt"): + self.agent._invalidate_system_prompt() + + title_part = f" \"{session_meta['title']}\"" if session_meta.get("title") else "" + msg_count = len([m for m in self.conversation_history if m.get("role") == "user"]) + if self.conversation_history: + _cprint( + f" ↻ Resumed session {target_id}{title_part}" + f" ({msg_count} user message{'s' if msg_count != 1 else ''}," + f" {len(self.conversation_history)} total)" + ) + else: + _cprint(f" ↻ Resumed session {target_id}{title_part} — no messages, starting fresh.") + + def _handle_branch_command(self, cmd_original: str) -> None: + """Handle /branch [name] — fork the current session into a new independent copy. + + Copies the full conversation history to a new session so the user can + explore a different approach without losing the original session state. + Inspired by Claude Code's /branch command. + """ + if not self.conversation_history: + _cprint(" No conversation to branch — send a message first.") + return + + if not self._session_db: + _cprint(" Session database not available.") + return + + parts = cmd_original.split(None, 1) + branch_name = parts[1].strip() if len(parts) > 1 else "" + + # Generate the new session ID + now = datetime.now() + timestamp_str = now.strftime("%Y%m%d_%H%M%S") + short_uuid = uuid.uuid4().hex[:6] + new_session_id = f"{timestamp_str}_{short_uuid}" + + # Determine branch title + if branch_name: + branch_title = branch_name + else: + # Auto-generate from the current session title + current_title = None + if self._session_db: + current_title = self._session_db.get_session_title(self.session_id) + base = current_title or "branch" + branch_title = self._session_db.get_next_title_in_lineage(base) + + # Save the current session's state before branching + parent_session_id = self.session_id + + # End the old session + try: + self._session_db.end_session(self.session_id, "branched") + except Exception: + pass + + # Create the new session with parent link + try: + self._session_db.create_session( + session_id=new_session_id, + source=os.environ.get("HERMES_SESSION_SOURCE", "cli"), + model=self.model, + model_config={ + "max_iterations": self.max_turns, + "reasoning_config": self.reasoning_config, + }, + parent_session_id=parent_session_id, + ) + except Exception as e: + _cprint(f" Failed to create branch session: {e}") + return + + # Copy conversation history to the new session + for msg in self.conversation_history: + try: + self._session_db.append_message( + session_id=new_session_id, + role=msg.get("role", "user"), + content=msg.get("content"), + tool_name=msg.get("tool_name") or msg.get("name"), + tool_calls=msg.get("tool_calls"), + tool_call_id=msg.get("tool_call_id"), + reasoning=msg.get("reasoning"), + ) + except Exception: + pass # Best-effort copy + + # Set title on the branch + try: + self._session_db.set_session_title(new_session_id, branch_title) + except Exception: + pass + + # Switch to the new session + self.session_id = new_session_id + self.session_start = now + self._pending_title = None + self._resumed = True # Prevents auto-title generation + + # Sync the agent + if self.agent: + self.agent.session_id = new_session_id + self.agent.session_start = now + self.agent.reset_session_state() + if hasattr(self.agent, "_last_flushed_db_idx"): + self.agent._last_flushed_db_idx = len(self.conversation_history) + if hasattr(self.agent, "_todo_store"): + try: + from tools.todo_tool import TodoStore + self.agent._todo_store = TodoStore() + except Exception: + pass + if hasattr(self.agent, "_invalidate_system_prompt"): + self.agent._invalidate_system_prompt() + + msg_count = len([m for m in self.conversation_history if m.get("role") == "user"]) + _cprint( + f" ⑂ Branched session \"{branch_title}\"" + f" ({msg_count} user message{'s' if msg_count != 1 else ''})" + ) + _cprint(f" Original session: {parent_session_id}") + _cprint(f" Branch session: {new_session_id}") + + def save_conversation(self): + """Save the current conversation to a file.""" + if not self.conversation_history: + print("(;_;) No conversation to save.") + return + + timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") + filename = f"hermes_conversation_{timestamp}.json" + + try: + with open(filename, "w", encoding="utf-8") as f: + json.dump({ + "model": self.model, + "session_start": self.session_start.isoformat(), + "messages": self.conversation_history, + }, f, indent=2, ensure_ascii=False) + print(f"(^_^)v Conversation saved to: {filename}") + except Exception as e: + print(f"(x_x) Failed to save: {e}") + + def retry_last(self): + """Retry the last user message by removing the last exchange and re-sending. + + Removes the last assistant response (and any tool-call messages) and + the last user message, then re-sends that user message to the agent. + Returns the message to re-send, or None if there's nothing to retry. + """ + if not self.conversation_history: + print("(._.) No messages to retry.") + return None + + # Walk backwards to find the last user message + last_user_idx = None + for i in range(len(self.conversation_history) - 1, -1, -1): + if self.conversation_history[i].get("role") == "user": + last_user_idx = i + break + + if last_user_idx is None: + print("(._.) No user message found to retry.") + return None + + # Extract the message text and remove everything from that point forward + last_message = self.conversation_history[last_user_idx].get("content", "") + self.conversation_history = self.conversation_history[:last_user_idx] + + print(f"(^_^)b Retrying: \"{last_message[:60]}{'...' if len(last_message) > 60 else ''}\"") + return last_message + + def undo_last(self): + """Remove the last user/assistant exchange from conversation history. + + Walks backwards and removes all messages from the last user message + onward (including assistant responses, tool calls, etc.). + """ + if not self.conversation_history: + print("(._.) No messages to undo.") + return + + # Walk backwards to find the last user message + last_user_idx = None + for i in range(len(self.conversation_history) - 1, -1, -1): + if self.conversation_history[i].get("role") == "user": + last_user_idx = i + break + + if last_user_idx is None: + print("(._.) No user message found to undo.") + return + + # Count how many messages we're removing + removed_count = len(self.conversation_history) - last_user_idx + removed_msg = self.conversation_history[last_user_idx].get("content", "") + + # Truncate history to before the last user message + self.conversation_history = self.conversation_history[:last_user_idx] + + print(f"(^_^)b Undid {removed_count} message(s). Removed: \"{removed_msg[:60]}{'...' if len(removed_msg) > 60 else ''}\"") + remaining = len(self.conversation_history) + print(f" {remaining} message(s) remaining in history.") + + def _run_curses_picker(self, title: str, items: list[str], default_index: int = 0) -> int | None: + """Run curses_single_select via run_in_terminal so prompt_toolkit handles terminal ownership cleanly.""" + import threading + from hermes_cli.curses_ui import curses_single_select + + result = [None] + + def _pick(): + result[0] = curses_single_select(title, items, default_index=default_index) + + # run_in_terminal requires an asyncio event loop — only exists in the + # main prompt_toolkit thread. If we're in a background thread (e.g. + # process_loop), fall back to direct curses call. + in_main_thread = threading.current_thread() is threading.main_thread() + + if self._app and in_main_thread: + from prompt_toolkit.application import run_in_terminal + was_visible = self._status_bar_visible + self._status_bar_visible = False + self._app.invalidate() + try: + run_in_terminal(_pick) + finally: + self._status_bar_visible = was_visible + self._app.invalidate() + else: + _pick() + + return result[0] + + def _prompt_text_input(self, prompt_text: str) -> str | None: + """Prompt for free-text input safely inside or outside prompt_toolkit.""" + result = [None] + + def _ask(): + try: + result[0] = input(prompt_text).strip() or None + except (KeyboardInterrupt, EOFError): + pass + + if self._app: + from prompt_toolkit.application import run_in_terminal + was_visible = self._status_bar_visible + self._status_bar_visible = False + self._app.invalidate() + try: + run_in_terminal(_ask) + finally: + self._status_bar_visible = was_visible + self._app.invalidate() + else: + _ask() + return result[0] + + def _open_model_picker(self, providers: list, current_model: str, current_provider: str, user_provs=None, custom_provs=None) -> None: + """Open prompt_toolkit-native /model picker modal.""" + self._capture_modal_input_snapshot() + default_idx = next((i for i, p in enumerate(providers) if p.get("is_current")), 0) + self._model_picker_state = { + "stage": "provider", + "providers": providers, + "selected": default_idx, + "current_model": current_model, + "current_provider": current_provider, + "user_provs": user_provs, + "custom_provs": custom_provs, + } + self._invalidate(min_interval=0.0) + + def _close_model_picker(self) -> None: + self._model_picker_state = None + self._restore_modal_input_snapshot() + self._invalidate(min_interval=0.0) + + def _apply_model_switch_result(self, result, persist_global: bool) -> None: + if not result.success: + _cprint(f" ✗ {result.error_message}") + return + + old_model = self.model + self.model = result.new_model + self.provider = result.target_provider + self.requested_provider = result.target_provider + if result.api_key: + self.api_key = result.api_key + self._explicit_api_key = result.api_key + if result.base_url: + self.base_url = result.base_url + self._explicit_base_url = result.base_url + if result.api_mode: + self.api_mode = result.api_mode + + if self.agent is not None: + try: + self.agent.switch_model( + new_model=result.new_model, + new_provider=result.target_provider, + api_key=result.api_key, + base_url=result.base_url, + api_mode=result.api_mode, + ) + except Exception as exc: + _cprint(f" ⚠ Agent swap failed ({exc}); change applied to next session.") + + self._pending_model_switch_note = ( + f"[Note: model was just switched from {old_model} to {result.new_model} " + f"via {result.provider_label or result.target_provider}. " + f"Adjust your self-identification accordingly.]" + ) + + provider_label = result.provider_label or result.target_provider + _cprint(f" ✓ Model switched: {result.new_model}") + _cprint(f" Provider: {provider_label}") + + mi = result.model_info + if mi: + if mi.context_window: + _cprint(f" Context: {mi.context_window:,} tokens") + if mi.max_output: + _cprint(f" Max output: {mi.max_output:,} tokens") + if mi.has_cost_data(): + _cprint(f" Cost: {mi.format_cost()}") + _cprint(f" Capabilities: {mi.format_capabilities()}") + else: + try: + from agent.model_metadata import get_model_context_length + ctx = get_model_context_length( + result.new_model, + base_url=result.base_url or self.base_url, + api_key=result.api_key or self.api_key, + provider=result.target_provider, + ) + _cprint(f" Context: {ctx:,} tokens") + except Exception: + pass + + cache_enabled = ( + ("openrouter" in (result.base_url or "").lower() and "claude" in result.new_model.lower()) + or result.api_mode == "anthropic_messages" + ) + if cache_enabled: + _cprint(" Prompt caching: enabled") + if result.warning_message: + _cprint(f" ⚠ {result.warning_message}") + if persist_global: + save_config_value("model.default", result.new_model) + if result.provider_changed: + save_config_value("model.provider", result.target_provider) + _cprint(" Saved to config.yaml (--global)") + else: + _cprint(" (session only — add --global to persist)") + + def _handle_model_picker_selection(self, persist_global: bool = False) -> None: + state = self._model_picker_state + if not state: + return + selected = state.get("selected", 0) + stage = state.get("stage") + if stage == "provider": + providers = state.get("providers") or [] + if selected >= len(providers): + self._close_model_picker() + return + provider_data = providers[selected] + model_list = [] + try: + from hermes_cli.models import provider_model_ids + live = provider_model_ids(provider_data["slug"]) + if live: + model_list = live + except Exception: + pass + if not model_list: + model_list = provider_data.get("models", []) + state["stage"] = "model" + state["provider_data"] = provider_data + state["model_list"] = model_list + state["selected"] = 0 + self._invalidate(min_interval=0.0) + return + if stage == "model": + provider_data = state.get("provider_data") or {} + model_list = state.get("model_list") or [] + back_idx = len(model_list) + cancel_idx = len(model_list) + 1 + if selected == back_idx: + state["stage"] = "provider" + state["selected"] = next((i for i, p in enumerate(state.get("providers") or []) if p.get("slug") == provider_data.get("slug")), 0) + self._invalidate(min_interval=0.0) + return + if selected >= cancel_idx: + self._close_model_picker() + return + if selected < len(model_list): + from hermes_cli.model_switch import switch_model + chosen_model = model_list[selected] + result = switch_model( + raw_input=chosen_model, + current_provider=self.provider or "", + current_model=self.model or "", + current_base_url=self.base_url or "", + current_api_key=self.api_key or "", + is_global=persist_global, + explicit_provider=provider_data.get("slug"), + user_providers=state.get("user_provs"), + custom_providers=state.get("custom_provs"), + ) + self._close_model_picker() + self._apply_model_switch_result(result, persist_global) + return + self._close_model_picker() + + def _handle_model_switch(self, cmd_original: str): + """Handle /model command — switch model for this session. + + Supports: + /model — show current model + usage hints + /model — switch for this session only + /model --global — switch and persist to config.yaml + /model --provider — switch provider + model + /model --provider — switch to provider, auto-detect model + """ + from hermes_cli.model_switch import switch_model, parse_model_flags, list_authenticated_providers + from hermes_cli.providers import get_label + + # Parse args from the original command + parts = cmd_original.split(None, 1) # split off '/model' + raw_args = parts[1].strip() if len(parts) > 1 else "" + + # Parse --provider and --global flags + model_input, explicit_provider, persist_global = parse_model_flags(raw_args) + + user_provs = None + custom_provs = None + + # No args at all: open prompt_toolkit-native picker modal + if not model_input and not explicit_provider: + model_display = self.model or "unknown" + provider_display = get_label(self.provider) if self.provider else "unknown" + + user_provs = None + custom_provs = None + try: + from hermes_cli.config import get_compatible_custom_providers, load_config + cfg = load_config() + user_provs = cfg.get("providers") + custom_provs = get_compatible_custom_providers(cfg) + except Exception: + pass + + try: + providers = list_authenticated_providers( + current_provider=self.provider or "", + user_providers=user_provs, + custom_providers=custom_provs, + max_models=50, + ) + except Exception: + providers = [] + + if not providers: + _cprint(" No authenticated providers found.") + _cprint("") + _cprint(" /model switch model") + _cprint(" /model --provider switch provider") + return + + self._open_model_picker( + providers, + model_display, + provider_display, + user_provs=user_provs, + custom_provs=custom_provs, + ) + return + + # Perform the switch + result = switch_model( + raw_input=model_input, + current_provider=self.provider or "", + current_model=self.model or "", + current_base_url=self.base_url or "", + current_api_key=self.api_key or "", + is_global=persist_global, + explicit_provider=explicit_provider, + user_providers=user_provs, + custom_providers=custom_provs, + ) + + if not result.success: + _cprint(f" ✗ {result.error_message}") + return + + # Apply to CLI state. + # Update requested_provider so _ensure_runtime_credentials() doesn't + # overwrite the switch on the next turn (it re-resolves from this). + old_model = self.model + self.model = result.new_model + self.provider = result.target_provider + self.requested_provider = result.target_provider + if result.api_key: + self.api_key = result.api_key + self._explicit_api_key = result.api_key + if result.base_url: + self.base_url = result.base_url + self._explicit_base_url = result.base_url + if result.api_mode: + self.api_mode = result.api_mode + + # Apply to running agent (in-place swap) + if self.agent is not None: + try: + self.agent.switch_model( + new_model=result.new_model, + new_provider=result.target_provider, + api_key=result.api_key, + base_url=result.base_url, + api_mode=result.api_mode, + ) + except Exception as exc: + _cprint(f" ⚠ Agent swap failed ({exc}); change applied to next session.") + + # Store a note to prepend to the next user message so the model + # knows a switch occurred (avoids injecting system messages mid-history + # which breaks providers and prompt caching). + self._pending_model_switch_note = ( + f"[Note: model was just switched from {old_model} to {result.new_model} " + f"via {result.provider_label or result.target_provider}. " + f"Adjust your self-identification accordingly.]" + ) + + # Display confirmation with full metadata + provider_label = result.provider_label or result.target_provider + _cprint(f" ✓ Model switched: {result.new_model}") + _cprint(f" Provider: {provider_label}") + + # Rich metadata from models.dev + mi = result.model_info + if mi: + if mi.context_window: + _cprint(f" Context: {mi.context_window:,} tokens") + if mi.max_output: + _cprint(f" Max output: {mi.max_output:,} tokens") + if mi.has_cost_data(): + _cprint(f" Cost: {mi.format_cost()}") + _cprint(f" Capabilities: {mi.format_capabilities()}") + else: + # Fallback to old context length lookup + try: + from agent.model_metadata import get_model_context_length + ctx = get_model_context_length( + result.new_model, + base_url=result.base_url or self.base_url, + api_key=result.api_key or self.api_key, + provider=result.target_provider, + ) + _cprint(f" Context: {ctx:,} tokens") + except Exception: + pass + + # Cache notice + cache_enabled = ( + ("openrouter" in (result.base_url or "").lower() and "claude" in result.new_model.lower()) + or result.api_mode == "anthropic_messages" + ) + if cache_enabled: + _cprint(" Prompt caching: enabled") + + # Warning from validation + if result.warning_message: + _cprint(f" ⚠ {result.warning_message}") + + # Persistence + if persist_global: + save_config_value("model.default", result.new_model) + if result.provider_changed: + save_config_value("model.provider", result.target_provider) + _cprint(" Saved to config.yaml (--global)") + else: + _cprint(" (session only — add --global to persist)") + + def _should_handle_model_command_inline(self, text: str, has_images: bool = False) -> bool: + """Return True when /model should be handled immediately on the UI thread.""" + if not text or has_images or not _looks_like_slash_command(text): + return False + try: + from hermes_cli.commands import resolve_command + base = text.split(None, 1)[0].lower().lstrip('/') + cmd = resolve_command(base) + return bool(cmd and cmd.name == "model") + except Exception: + return False + + def _show_model_and_providers(self): + """Show current model + provider and list all authenticated providers. + + Shows current model + provider, then lists all authenticated + providers with their available models. + """ + from hermes_cli.models import ( + curated_models_for_provider, list_available_providers, + normalize_provider, _PROVIDER_LABELS, + get_pricing_for_provider, format_model_pricing_table, + ) + from hermes_cli.auth import resolve_provider as _resolve_provider + + # Resolve current provider + raw_provider = normalize_provider(self.provider) + if raw_provider == "auto": + try: + current = _resolve_provider( + self.requested_provider, + explicit_api_key=self._explicit_api_key, + explicit_base_url=self._explicit_base_url, + ) + except Exception: + current = "openrouter" + else: + current = raw_provider + current_label = _PROVIDER_LABELS.get(current, current) + + print(f"\n Current: {self.model} via {current_label}") + print() + + # Show all authenticated providers with their models + providers = list_available_providers() + authed = [p for p in providers if p["authenticated"]] + unauthed = [p for p in providers if not p["authenticated"]] + + if authed: + print(" Authenticated providers & models:") + for p in authed: + is_active = p["id"] == current + marker = " ← active" if is_active else "" + print(f" [{p['id']}]{marker}") + curated = curated_models_for_provider(p["id"]) + # Fetch pricing for providers that support it (openrouter, nous) + pricing_map = get_pricing_for_provider(p["id"]) if p["id"] in ("openrouter", "nous") else {} + if curated and pricing_map: + cur_model = self.model if is_active else "" + for line in format_model_pricing_table(curated, pricing_map, current_model=cur_model): + print(line) + elif curated: + for mid, desc in curated: + current_marker = " ← current" if (is_active and mid == self.model) else "" + print(f" {mid}{current_marker}") + elif p["id"] == "custom": + from hermes_cli.models import _get_custom_base_url + custom_url = _get_custom_base_url() + if custom_url: + print(f" endpoint: {custom_url}") + if is_active: + print(f" model: {self.model} ← current") + print(" (use hermes model to change)") + else: + print(" (use hermes model to change)") + print() + + if unauthed: + names = ", ".join(p["label"] for p in unauthed) + print(f" Not configured: {names}") + print(" Run: hermes setup") + print() + + print(" To change model or provider, use: hermes model") + + + + + @staticmethod + def _resolve_personality_prompt(value) -> str: + """Accept string or dict personality value; return system prompt string.""" + if isinstance(value, dict): + parts = [value.get("system_prompt", "")] + if value.get("tone"): + parts.append(f'Tone: {value["tone"]}' ) + if value.get("style"): + parts.append(f'Style: {value["style"]}' ) + return "\n".join(p for p in parts if p) + return str(value) + + def _handle_personality_command(self, cmd: str): + """Handle the /personality command to set predefined personalities.""" + parts = cmd.split(maxsplit=1) + + if len(parts) > 1: + # Set personality + personality_name = parts[1].strip().lower() + + if personality_name in ("none", "default", "neutral"): + self.system_prompt = "" + self.agent = None # Force re-init + if save_config_value("agent.system_prompt", ""): + print("(^_^)b Personality cleared (saved to config)") + else: + print("(^_^) Personality cleared (session only)") + print(" No personality overlay — using base agent behavior.") + elif personality_name in self.personalities: + self.system_prompt = self._resolve_personality_prompt(self.personalities[personality_name]) + self.agent = None # Force re-init + if save_config_value("agent.system_prompt", self.system_prompt): + print(f"(^_^)b Personality set to '{personality_name}' (saved to config)") + else: + print(f"(^_^) Personality set to '{personality_name}' (session only)") + print(f" \"{self.system_prompt[:60]}{'...' if len(self.system_prompt) > 60 else ''}\"") + else: + print(f"(._.) Unknown personality: {personality_name}") + print(f" Available: none, {', '.join(self.personalities.keys())}") + else: + # Show available personalities + print() + print("+" + "-" * 50 + "+") + print("|" + " " * 12 + "(^o^)/ Personalities" + " " * 15 + "|") + print("+" + "-" * 50 + "+") + print() + print(f" {'none':<12} - (no personality overlay)") + for name, prompt in self.personalities.items(): + if isinstance(prompt, dict): + preview = prompt.get("description") or prompt.get("system_prompt", "")[:50] + else: + preview = str(prompt)[:50] + print(f" {name:<12} - {preview}") + print() + print(" Usage: /personality ") + print() + + def _handle_cron_command(self, cmd: str): + """Handle the /cron command to manage scheduled tasks.""" + import shlex + from tools.cronjob_tools import cronjob as cronjob_tool + + def _cron_api(**kwargs): + return json.loads(cronjob_tool(**kwargs)) + + def _normalize_skills(values): + normalized = [] + for value in values: + text = str(value or "").strip() + if text and text not in normalized: + normalized.append(text) + return normalized + + def _parse_flags(tokens): + opts = { + "name": None, + "deliver": None, + "repeat": None, + "skills": [], + "add_skills": [], + "remove_skills": [], + "clear_skills": False, + "all": False, + "prompt": None, + "schedule": None, + "positionals": [], + } + i = 0 + while i < len(tokens): + token = tokens[i] + if token == "--name" and i + 1 < len(tokens): + opts["name"] = tokens[i + 1] + i += 2 + elif token == "--deliver" and i + 1 < len(tokens): + opts["deliver"] = tokens[i + 1] + i += 2 + elif token == "--repeat" and i + 1 < len(tokens): + try: + opts["repeat"] = int(tokens[i + 1]) + except ValueError: + print("(._.) --repeat must be an integer") + return None + i += 2 + elif token == "--skill" and i + 1 < len(tokens): + opts["skills"].append(tokens[i + 1]) + i += 2 + elif token == "--add-skill" and i + 1 < len(tokens): + opts["add_skills"].append(tokens[i + 1]) + i += 2 + elif token == "--remove-skill" and i + 1 < len(tokens): + opts["remove_skills"].append(tokens[i + 1]) + i += 2 + elif token == "--clear-skills": + opts["clear_skills"] = True + i += 1 + elif token == "--all": + opts["all"] = True + i += 1 + elif token == "--prompt" and i + 1 < len(tokens): + opts["prompt"] = tokens[i + 1] + i += 2 + elif token == "--schedule" and i + 1 < len(tokens): + opts["schedule"] = tokens[i + 1] + i += 2 + else: + opts["positionals"].append(token) + i += 1 + return opts + + tokens = shlex.split(cmd) + + if len(tokens) == 1: + print() + print("+" + "-" * 68 + "+") + print("|" + " " * 22 + "(^_^) Scheduled Tasks" + " " * 23 + "|") + print("+" + "-" * 68 + "+") + print() + print(" Commands:") + print(" /cron list") + print(' /cron add "every 2h" "Check server status" [--skill blogwatcher]') + print(' /cron edit --schedule "every 4h" --prompt "New task"') + print(" /cron edit --skill blogwatcher --skill find-nearby") + print(" /cron edit --remove-skill blogwatcher") + print(" /cron edit --clear-skills") + print(" /cron pause ") + print(" /cron resume ") + print(" /cron run ") + print(" /cron remove ") + print() + result = _cron_api(action="list") + jobs = result.get("jobs", []) if result.get("success") else [] + if jobs: + print(" Current Jobs:") + print(" " + "-" * 63) + for job in jobs: + repeat_str = job.get("repeat", "?") + print(f" {job['job_id'][:12]:<12} | {job['schedule']:<15} | {repeat_str:<8}") + if job.get("skills"): + print(f" Skills: {', '.join(job['skills'])}") + print(f" {job.get('prompt_preview', '')}") + if job.get("next_run_at"): + print(f" Next: {job['next_run_at']}") + print() + else: + print(" No scheduled jobs. Use '/cron add' to create one.") + print() + return + + subcommand = tokens[1].lower() + opts = _parse_flags(tokens[2:]) + if opts is None: + return + + if subcommand == "list": + result = _cron_api(action="list", include_disabled=opts["all"]) + jobs = result.get("jobs", []) if result.get("success") else [] + if not jobs: + print("(._.) No scheduled jobs.") + return + + print() + print("Scheduled Jobs:") + print("-" * 80) + for job in jobs: + print(f" ID: {job['job_id']}") + print(f" Name: {job['name']}") + print(f" State: {job.get('state', '?')}") + print(f" Schedule: {job['schedule']} ({job.get('repeat', '?')})") + print(f" Next run: {job.get('next_run_at', 'N/A')}") + if job.get("skills"): + print(f" Skills: {', '.join(job['skills'])}") + print(f" Prompt: {job.get('prompt_preview', '')}") + if job.get("last_run_at"): + print(f" Last run: {job['last_run_at']} ({job.get('last_status', '?')})") + print() + return + + if subcommand in {"add", "create"}: + positionals = opts["positionals"] + if not positionals: + print("(._.) Usage: /cron add ") + return + schedule = opts["schedule"] or positionals[0] + prompt = opts["prompt"] or " ".join(positionals[1:]) + skills = _normalize_skills(opts["skills"]) + if not prompt and not skills: + print("(._.) Please provide a prompt or at least one skill") + return + result = _cron_api( + action="create", + schedule=schedule, + prompt=prompt or None, + name=opts["name"], + deliver=opts["deliver"], + repeat=opts["repeat"], + skills=skills or None, + ) + if result.get("success"): + print(f"(^_^)b Created job: {result['job_id']}") + print(f" Schedule: {result['schedule']}") + if result.get("skills"): + print(f" Skills: {', '.join(result['skills'])}") + print(f" Next run: {result['next_run_at']}") + else: + print(f"(x_x) Failed to create job: {result.get('error')}") + return + + if subcommand == "edit": + positionals = opts["positionals"] + if not positionals: + print("(._.) Usage: /cron edit [--schedule ...] [--prompt ...] [--skill ...]") + return + job_id = positionals[0] + existing = get_job(job_id) + if not existing: + print(f"(._.) Job not found: {job_id}") + return + + final_skills = None + replacement_skills = _normalize_skills(opts["skills"]) + add_skills = _normalize_skills(opts["add_skills"]) + remove_skills = set(_normalize_skills(opts["remove_skills"])) + existing_skills = list(existing.get("skills") or ([] if not existing.get("skill") else [existing.get("skill")])) + if opts["clear_skills"]: + final_skills = [] + elif replacement_skills: + final_skills = replacement_skills + elif add_skills or remove_skills: + final_skills = [skill for skill in existing_skills if skill not in remove_skills] + for skill in add_skills: + if skill not in final_skills: + final_skills.append(skill) + + result = _cron_api( + action="update", + job_id=job_id, + schedule=opts["schedule"], + prompt=opts["prompt"], + name=opts["name"], + deliver=opts["deliver"], + repeat=opts["repeat"], + skills=final_skills, + ) + if result.get("success"): + job = result["job"] + print(f"(^_^)b Updated job: {job['job_id']}") + print(f" Schedule: {job['schedule']}") + if job.get("skills"): + print(f" Skills: {', '.join(job['skills'])}") + else: + print(" Skills: none") + else: + print(f"(x_x) Failed to update job: {result.get('error')}") + return + + if subcommand in {"pause", "resume", "run", "remove", "rm", "delete"}: + positionals = opts["positionals"] + if not positionals: + print(f"(._.) Usage: /cron {subcommand} ") + return + job_id = positionals[0] + action = "remove" if subcommand in {"remove", "rm", "delete"} else subcommand + result = _cron_api(action=action, job_id=job_id, reason="paused from /cron" if action == "pause" else None) + if not result.get("success"): + print(f"(x_x) Failed to {action} job: {result.get('error')}") + return + if action == "pause": + print(f"(^_^)b Paused job: {result['job']['name']} ({job_id})") + elif action == "resume": + print(f"(^_^)b Resumed job: {result['job']['name']} ({job_id})") + print(f" Next run: {result['job'].get('next_run_at')}") + elif action == "run": + print(f"(^_^)b Triggered job: {result['job']['name']} ({job_id})") + print(" It will run on the next scheduler tick.") + else: + removed = result.get("removed_job", {}) + print(f"(^_^)b Removed job: {removed.get('name', job_id)} ({job_id})") + return + + print(f"(._.) Unknown cron command: {subcommand}") + print(" Available: list, add, edit, pause, resume, run, remove") + + def _handle_skills_command(self, cmd: str): + """Handle /skills slash command — delegates to hermes_cli.skills_hub.""" + from hermes_cli.skills_hub import handle_skills_slash + handle_skills_slash(cmd, ChatConsole()) + + def _show_gateway_status(self): + """Show status of the gateway and connected messaging platforms.""" + from gateway.config import load_gateway_config, Platform + + print() + print("+" + "-" * 60 + "+") + print("|" + " " * 15 + "(✿◠‿◠) Gateway Status" + " " * 17 + "|") + print("+" + "-" * 60 + "+") + print() + + try: + config = load_gateway_config() + + print(" Messaging Platform Configuration:") + print(" " + "-" * 55) + + platform_status = { + Platform.TELEGRAM: ("Telegram", "TELEGRAM_BOT_TOKEN"), + Platform.DISCORD: ("Discord", "DISCORD_BOT_TOKEN"), + Platform.WHATSAPP: ("WhatsApp", "WHATSAPP_ENABLED"), + } + + for platform, (name, env_var) in platform_status.items(): + pconfig = config.platforms.get(platform) + if pconfig and pconfig.enabled: + home = config.get_home_channel(platform) + home_str = f" → {home.name}" if home else "" + print(f" ✓ {name:<12} Enabled{home_str}") + else: + print(f" ○ {name:<12} Not configured ({env_var})") + + print() + print(" Session Reset Policy:") + print(" " + "-" * 55) + policy = config.default_reset_policy + print(f" Mode: {policy.mode}") + print(f" Daily reset at: {policy.at_hour}:00") + print(f" Idle timeout: {policy.idle_minutes} minutes") + + print() + print(" To start the gateway:") + print(" python cli.py --gateway") + print() + print(f" Configuration file: {display_hermes_home()}/config.yaml") + print() + + except Exception as e: + print(f" Error loading gateway config: {e}") + print() + print(" To configure the gateway:") + print(" 1. Set environment variables:") + print(" TELEGRAM_BOT_TOKEN=your_token") + print(" DISCORD_BOT_TOKEN=your_token") + print(f" 2. Or configure settings in {display_hermes_home()}/config.yaml") + print() + + def process_command(self, command: str) -> bool: + """ + Process a slash command. + + Args: + command: The command string (starting with /) + + Returns: + bool: True to continue, False to exit + """ + # Lowercase only for dispatch matching; preserve original case for arguments + cmd_lower = command.lower().strip() + cmd_original = command.strip() + + # Resolve aliases via central registry so adding an alias is a one-line + # change in hermes_cli/commands.py instead of touching every dispatch site. + from hermes_cli.commands import resolve_command as _resolve_cmd + _base_word = cmd_lower.split()[0].lstrip("/") + _cmd_def = _resolve_cmd(_base_word) + canonical = _cmd_def.name if _cmd_def else _base_word + + if canonical in ("quit", "exit", "q"): + return False + elif canonical == "help": + self.show_help() + elif canonical == "profile": + self._handle_profile_command() + elif canonical == "tools": + self._handle_tools_command(cmd_original) + elif canonical == "toolsets": + self.show_toolsets() + elif canonical == "config": + self.show_config() + elif canonical == "clear": + self.new_session(silent=True) + # Clear terminal screen. Inside the TUI, Rich's console.clear() + # goes through patch_stdout's StdoutProxy which swallows the + # screen-clear escape sequences. Use prompt_toolkit's output + # object directly to actually clear the terminal. + if self._app: + out = self._app.output + out.erase_screen() + out.cursor_goto(0, 0) + out.flush() + else: + self.console.clear() + # Show fresh banner. Inside the TUI we must route Rich output + # through ChatConsole (which uses prompt_toolkit's native ANSI + # renderer) instead of self.console (which writes raw to stdout + # and gets mangled by patch_stdout). + if self._app: + cc = ChatConsole() + term_w = shutil.get_terminal_size().columns + if self.compact or term_w < 80: + cc.print(_build_compact_banner()) + else: + tools = get_tool_definitions(enabled_toolsets=self.enabled_toolsets, quiet_mode=True) + cwd = os.getenv("TERMINAL_CWD", os.getcwd()) + ctx_len = None + if hasattr(self, 'agent') and self.agent and hasattr(self.agent, 'context_compressor'): + ctx_len = self.agent.context_compressor.context_length + build_welcome_banner( + console=cc, + model=self.model, + cwd=cwd, + tools=tools, + enabled_toolsets=self.enabled_toolsets, + session_id=self.session_id, + context_length=ctx_len, + ) + _cprint(" ✨ (◕‿◕)✨ Fresh start! Screen cleared and conversation reset.\n") + # Show a random tip on new session + try: + from hermes_cli.tips import get_random_tip + _tip = get_random_tip() + try: + from hermes_cli.skin_engine import get_active_skin + _tip_color = get_active_skin().get_color("banner_dim", "#B8860B") + except Exception: + _tip_color = "#B8860B" + cc.print(f"[dim {_tip_color}]✦ Tip: {_tip}[/]") + except Exception: + pass + else: + self.show_banner() + print(" ✨ (◕‿◕)✨ Fresh start! Screen cleared and conversation reset.\n") + # Show a random tip on new session + try: + from hermes_cli.tips import get_random_tip + _tip = get_random_tip() + try: + from hermes_cli.skin_engine import get_active_skin + _tip_color = get_active_skin().get_color("banner_dim", "#B8860B") + except Exception: + _tip_color = "#B8860B" + self.console.print(f"[dim {_tip_color}]✦ Tip: {_tip}[/]") + except Exception: + pass + elif canonical == "history": + self.show_history() + elif canonical == "title": + parts = cmd_original.split(maxsplit=1) + if len(parts) > 1: + raw_title = parts[1].strip() + if raw_title: + if self._session_db: + # Sanitize the title early so feedback matches what gets stored + try: + from hermes_state import SessionDB + new_title = SessionDB.sanitize_title(raw_title) + except ValueError as e: + _cprint(f" {e}") + new_title = None + if not new_title: + _cprint(" Title is empty after cleanup. Please use printable characters.") + elif self._session_db.get_session(self.session_id): + # Session exists in DB — set title directly + try: + if self._session_db.set_session_title(self.session_id, new_title): + _cprint(f" Session title set: {new_title}") + else: + _cprint(" Session not found in database.") + except ValueError as e: + _cprint(f" {e}") + else: + # Session not created yet — defer the title + # Check uniqueness proactively with the sanitized title + existing = self._session_db.get_session_by_title(new_title) + if existing: + _cprint(f" Title '{new_title}' is already in use by session {existing['id']}") + else: + self._pending_title = new_title + _cprint(f" Session title queued: {new_title} (will be saved on first message)") + else: + _cprint(" Session database not available.") + else: + _cprint(" Usage: /title ") + else: + # Show current title and session ID if no argument given + if self._session_db: + _cprint(f" Session ID: {self.session_id}") + session = self._session_db.get_session(self.session_id) + if session and session.get("title"): + _cprint(f" Title: {session['title']}") + elif self._pending_title: + _cprint(f" Title (pending): {self._pending_title}") + else: + _cprint(" No title set. Usage: /title ") + else: + _cprint(" Session database not available.") + elif canonical == "new": + self.new_session() + elif canonical == "resume": + self._handle_resume_command(cmd_original) + elif canonical == "model": + self._handle_model_switch(cmd_original) + elif canonical == "provider": + self._show_model_and_providers() + + elif canonical == "personality": + # Use original case (handler lowercases the personality name itself) + self._handle_personality_command(cmd_original) + elif canonical == "plan": + self._handle_plan_command(cmd_original) + elif canonical == "retry": + retry_msg = self.retry_last() + if retry_msg and hasattr(self, '_pending_input'): + # Re-queue the message so process_loop sends it to the agent + self._pending_input.put(retry_msg) + elif canonical == "undo": + self.undo_last() + elif canonical == "branch": + self._handle_branch_command(cmd_original) + elif canonical == "save": + self.save_conversation() + elif canonical == "cron": + self._handle_cron_command(cmd_original) + elif canonical == "skills": + with self._busy_command(self._slow_command_status(cmd_original)): + self._handle_skills_command(cmd_original) + elif canonical == "platforms": + self._show_gateway_status() + elif canonical == "status": + self._show_session_status() + elif canonical == "statusbar": + self._status_bar_visible = not self._status_bar_visible + state = "visible" if self._status_bar_visible else "hidden" + self.console.print(f" Status bar {state}") + elif canonical == "verbose": + self._toggle_verbose() + elif canonical == "yolo": + self._toggle_yolo() + elif canonical == "reasoning": + self._handle_reasoning_command(cmd_original) + elif canonical == "fast": + self._handle_fast_command(cmd_original) + elif canonical == "compress": + self._manual_compress(cmd_original) + elif canonical == "usage": + self._show_usage() + elif canonical == "insights": + self._show_insights(cmd_original) + elif canonical == "debug": + self._handle_debug_command() + elif canonical == "paste": + self._handle_paste_command() + elif canonical == "image": + self._handle_image_command(cmd_original) + elif canonical == "reload": + from hermes_cli.config import reload_env + count = reload_env() + print(f" Reloaded .env ({count} var(s) updated)") + elif canonical == "reload-mcp": + with self._busy_command(self._slow_command_status(cmd_original)): + self._reload_mcp() + elif canonical == "browser": + self._handle_browser_command(cmd_original) + elif canonical == "plugins": + try: + from hermes_cli.plugins import get_plugin_manager + mgr = get_plugin_manager() + plugins = mgr.list_plugins() + if not plugins: + print("No plugins installed.") + print(f"Drop plugin directories into {display_hermes_home()}/plugins/ to get started.") + else: + print(f"Plugins ({len(plugins)}):") + for p in plugins: + status = "✓" if p["enabled"] else "✗" + version = f" v{p['version']}" if p["version"] else "" + tools = f"{p['tools']} tools" if p["tools"] else "" + hooks = f"{p['hooks']} hooks" if p["hooks"] else "" + parts = [x for x in [tools, hooks] if x] + detail = f" ({', '.join(parts)})" if parts else "" + error = f" — {p['error']}" if p["error"] else "" + print(f" {status} {p['name']}{version}{detail}{error}") + except Exception as e: + print(f"Plugin system error: {e}") + elif canonical == "rollback": + self._handle_rollback_command(cmd_original) + elif canonical == "snapshot": + self._handle_snapshot_command(cmd_original) + elif canonical == "stop": + self._handle_stop_command() + elif canonical == "background": + self._handle_background_command(cmd_original) + elif canonical == "btw": + self._handle_btw_command(cmd_original) + elif canonical == "queue": + # Extract prompt after "/queue " or "/q " + parts = cmd_original.split(None, 1) + payload = parts[1].strip() if len(parts) > 1 else "" + if not payload: + _cprint(" Usage: /queue ") + else: + self._pending_input.put(payload) + if self._agent_running: + _cprint(f" Queued for the next turn: {payload[:80]}{'...' if len(payload) > 80 else ''}") + else: + _cprint(f" Queued: {payload[:80]}{'...' if len(payload) > 80 else ''}") + elif canonical == "skin": + self._handle_skin_command(cmd_original) + elif canonical == "voice": + self._handle_voice_command(cmd_original) + else: + # Check for user-defined quick commands (bypass agent loop, no LLM call) + base_cmd = cmd_lower.split()[0] + quick_commands = self.config.get("quick_commands", {}) + if base_cmd.lstrip("/") in quick_commands: + qcmd = quick_commands[base_cmd.lstrip("/")] + if qcmd.get("type") == "exec": + import subprocess + exec_cmd = qcmd.get("command", "") + if exec_cmd: + try: + result = subprocess.run( + exec_cmd, shell=True, capture_output=True, + text=True, timeout=30 + ) + output = result.stdout.strip() or result.stderr.strip() + if output: + self.console.print(_rich_text_from_ansi(output)) + else: + self.console.print("[dim]Command returned no output[/]") + except subprocess.TimeoutExpired: + self.console.print("[bold red]Quick command timed out (30s)[/]") + except Exception as e: + self.console.print(f"[bold red]Quick command error: {e}[/]") + else: + self.console.print(f"[bold red]Quick command '{base_cmd}' has no command defined[/]") + elif qcmd.get("type") == "alias": + target = qcmd.get("target", "").strip() + if target: + target = target if target.startswith("/") else f"/{target}" + user_args = cmd_original[len(base_cmd):].strip() + aliased_command = f"{target} {user_args}".strip() + return self.process_command(aliased_command) + else: + self.console.print(f"[bold red]Quick command '{base_cmd}' has no target defined[/]") + else: + self.console.print(f"[bold red]Quick command '{base_cmd}' has unsupported type (supported: 'exec', 'alias')[/]") + # Check for plugin-registered slash commands + elif base_cmd.lstrip("/") in _get_plugin_cmd_handler_names(): + from hermes_cli.plugins import get_plugin_command_handler + plugin_handler = get_plugin_command_handler(base_cmd.lstrip("/")) + if plugin_handler: + user_args = cmd_original[len(base_cmd):].strip() + try: + result = plugin_handler(user_args) + if result: + _cprint(str(result)) + except Exception as e: + _cprint(f"\033[1;31mPlugin command error: {e}{_RST}") + # Check for skill slash commands (/gif-search, /axolotl, etc.) + elif base_cmd in _skill_commands: + user_instruction = cmd_original[len(base_cmd):].strip() + msg = build_skill_invocation_message( + base_cmd, user_instruction, task_id=self.session_id + ) + if msg: + skill_name = _skill_commands[base_cmd]["name"] + print(f"\n⚡ Loading skill: {skill_name}") + if hasattr(self, '_pending_input'): + self._pending_input.put(msg) + else: + 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 + # that execution-time resolution agrees with tab-completion. + from hermes_cli.commands import COMMANDS + typed_base = cmd_lower.split()[0] + all_known = set(COMMANDS) | set(_skill_commands) + matches = [c for c in all_known if c.startswith(typed_base)] + if len(matches) > 1: + # Prefer an exact match (typed the full command name) + exact = [c for c in matches if c == typed_base] + if len(exact) == 1: + matches = exact + else: + # Prefer the unique shortest match: + # /qui → /quit (5) wins over /quint-pipeline (15) + min_len = min(len(c) for c in matches) + shortest = [c for c in matches if len(c) == min_len] + if len(shortest) == 1: + matches = shortest + if len(matches) == 1: + # Expand the prefix to the full command name, preserving arguments. + # Guard against redispatching the same token to avoid infinite + # recursion when the expanded name still doesn't hit an exact branch + # (e.g. /config with extra args that are not yet handled above). + full_name = matches[0] + if full_name == typed_base: + # Already an exact token — no expansion possible; fall through + _cprint(f"\033[1;31mUnknown command: {cmd_lower}{_RST}") + _cprint(f"{_DIM}{_ACCENT}Type /help for available commands{_RST}") + else: + remainder = cmd_original.strip()[len(typed_base):] + full_cmd = full_name + remainder + return self.process_command(full_cmd) + elif len(matches) > 1: + _cprint(f"{_ACCENT}Ambiguous command: {cmd_lower}{_RST}") + _cprint(f"{_DIM}Did you mean: {', '.join(sorted(matches))}?{_RST}") + else: + _cprint(f"\033[1;31mUnknown command: {cmd_lower}{_RST}") + _cprint(f"{_DIM}{_ACCENT}Type /help for available commands{_RST}") + + return True + + def _handle_plan_command(self, cmd: str): + """Handle /plan [request] — load the bundled plan skill.""" + parts = cmd.strip().split(maxsplit=1) + user_instruction = parts[1].strip() if len(parts) > 1 else "" + + plan_path = build_plan_path(user_instruction) + msg = build_skill_invocation_message( + "/plan", + user_instruction, + task_id=self.session_id, + runtime_note=( + "Save the markdown plan with write_file to this exact relative path " + f"inside the active workspace/backend cwd: {plan_path}" + ), + ) + + if not msg: + 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: + ChatConsole().print("[bold red]Plan mode unavailable: input queue not initialized[/]") + + def _handle_background_command(self, cmd: str): + """Handle /background — run a prompt in a separate background session. + + Spawns a new AIAgent in a background thread with its own session. + When it completes, prints the result to the CLI without modifying + the active session's conversation history. + """ + parts = cmd.strip().split(maxsplit=1) + if len(parts) < 2 or not parts[1].strip(): + _cprint(" Usage: /background ") + _cprint(" Example: /background Summarize the top HN stories today") + _cprint(" The task runs in a separate session and results display here when done.") + return + + prompt = parts[1].strip() + self._background_task_counter += 1 + task_num = self._background_task_counter + task_id = f"bg_{datetime.now().strftime('%H%M%S')}_{uuid.uuid4().hex[:6]}" + + # Make sure we have valid credentials + if not self._ensure_runtime_credentials(): + _cprint(" (>_<) Cannot start background task: no valid credentials.") + return + + _cprint(f" 🔄 Background task #{task_num} started: \"{prompt[:60]}{'...' if len(prompt) > 60 else ''}\"") + _cprint(f" Task ID: {task_id}") + _cprint(" You can continue chatting — results will appear when done.\n") + + turn_route = self._resolve_turn_agent_config(prompt) + + def run_background(): + try: + bg_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=self.max_turns, + enabled_toolsets=self.enabled_toolsets, + quiet_mode=True, + verbose_logging=False, + session_id=task_id, + platform="cli", + session_db=self._session_db, + reasoning_config=self.reasoning_config, + service_tier=self.service_tier, + request_overrides=turn_route.get("request_overrides"), + providers_allowed=self._providers_only, + providers_ignored=self._providers_ignore, + providers_order=self._providers_order, + provider_sort=self._provider_sort, + provider_require_parameters=self._provider_require_params, + provider_data_collection=self._provider_data_collection, + fallback_model=self._fallback_model, + ) + # Silence raw spinner; route thinking through TUI widget when no foreground agent is active. + bg_agent._print_fn = lambda *_a, **_kw: None + + def _bg_thinking(text: str) -> None: + # Concurrent bg tasks may race on _spinner_text; acceptable for best-effort UI. + if not self._agent_running: + self._spinner_text = text + if self._app: + self._app.invalidate() + + bg_agent.thinking_callback = _bg_thinking + + result = bg_agent.run_conversation( + user_message=prompt, + task_id=task_id, + ) + + response = result.get("final_response", "") if result else "" + if not response and result and result.get("error"): + response = f"Error: {result['error']}" + + # Display result in the CLI (thread-safe via patch_stdout). + # Force a TUI refresh first so spinner/status bar don't overlap + # with the output (fixes #2718). + if self._app: + self._app.invalidate() + import time as _tmod + _tmod.sleep(0.05) # brief pause for refresh + print() + ChatConsole().print(f"[{_accent_hex()}]{'─' * 40}[/]") + _cprint(f" ✅ Background task #{task_num} complete") + _cprint(f" Prompt: \"{prompt[:60]}{'...' if len(prompt) > 60 else ''}\"") + ChatConsole().print(f"[{_accent_hex()}]{'─' * 40}[/]") + if response: + try: + from hermes_cli.skin_engine import get_active_skin + _skin = get_active_skin() + label = _skin.get_branding("response_label", "⚕ Hermes") + _resp_color = _skin.get_color("response_border", "#CD7F32") + _resp_text = _skin.get_color("banner_text", "#FFF8DC") + except Exception: + label = "⚕ Hermes" + _resp_color = "#CD7F32" + _resp_text = "#FFF8DC" + + _chat_console = ChatConsole() + _chat_console.print(Panel( + _rich_text_from_ansi(response), + title=f"[{_resp_color} bold]{label} (background #{task_num})[/]", + title_align="left", + border_style=_resp_color, + style=_resp_text, + box=rich_box.HORIZONTALS, + padding=(1, 2), + )) + else: + _cprint(" (No response generated)") + + # Play bell if enabled + if self.bell_on_complete: + sys.stdout.write("\a") + sys.stdout.flush() + + except Exception as e: + # Same TUI refresh pattern as success path (#2718) + if self._app: + self._app.invalidate() + import time as _tmod + _tmod.sleep(0.05) + print() + _cprint(f" ❌ Background task #{task_num} failed: {e}") + finally: + self._background_tasks.pop(task_id, None) + # Clear spinner only if no foreground agent owns it + if not self._agent_running: + self._spinner_text = "" + if self._app: + self._invalidate(min_interval=0) + + thread = threading.Thread(target=run_background, daemon=True, name=f"bg-task-{task_id}") + self._background_tasks[task_id] = thread + thread.start() + + def _handle_btw_command(self, cmd: str): + """Handle /btw — ephemeral side question using session context. + + Snapshots the current conversation history, spawns a no-tools agent in + a background thread, and prints the answer without persisting anything + to the main session. + """ + parts = cmd.strip().split(maxsplit=1) + if len(parts) < 2 or not parts[1].strip(): + _cprint(" Usage: /btw ") + _cprint(" Example: /btw what module owns session title sanitization?") + _cprint(" Answers using session context. No tools, not persisted.") + return + + question = parts[1].strip() + task_id = f"btw_{datetime.now().strftime('%H%M%S')}_{uuid.uuid4().hex[:6]}" + + if not self._ensure_runtime_credentials(): + _cprint(" (>_<) Cannot start /btw: no valid credentials.") + return + + turn_route = self._resolve_turn_agent_config(question) + history_snapshot = list(self.conversation_history) + + preview = question[:60] + ("..." if len(question) > 60 else "") + _cprint(f' 💬 /btw: "{preview}"') + + def run_btw(): + try: + btw_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=8, + enabled_toolsets=[], + quiet_mode=True, + verbose_logging=False, + session_id=task_id, + platform="cli", + reasoning_config=self.reasoning_config, + service_tier=self.service_tier, + request_overrides=turn_route.get("request_overrides"), + providers_allowed=self._providers_only, + providers_ignored=self._providers_ignore, + providers_order=self._providers_order, + provider_sort=self._provider_sort, + provider_require_parameters=self._provider_require_params, + provider_data_collection=self._provider_data_collection, + fallback_model=self._fallback_model, + session_db=None, + skip_memory=True, + skip_context_files=True, + persist_session=False, + ) + + btw_prompt = ( + "[Ephemeral /btw side question. Answer using the conversation " + "context. No tools available. Be direct and concise.]\n\n" + + question + ) + result = btw_agent.run_conversation( + user_message=btw_prompt, + conversation_history=history_snapshot, + task_id=task_id, + ) + + response = (result.get("final_response") or "") if result else "" + if not response and result and result.get("error"): + response = f"Error: {result['error']}" + + # TUI refresh before printing + if self._app: + self._app.invalidate() + time.sleep(0.05) + print() + + if response: + try: + from hermes_cli.skin_engine import get_active_skin + _skin = get_active_skin() + _resp_color = _skin.get_color("response_border", "#4F6D4A") + except Exception: + _resp_color = "#4F6D4A" + + ChatConsole().print(Panel( + _rich_text_from_ansi(response), + title=f"[{_resp_color} bold]⚕ /btw[/]", + title_align="left", + border_style=_resp_color, + box=rich_box.HORIZONTALS, + padding=(1, 2), + )) + else: + _cprint(" 💬 /btw: (no response)") + + if self.bell_on_complete: + sys.stdout.write("\a") + sys.stdout.flush() + + except Exception as e: + if self._app: + self._app.invalidate() + time.sleep(0.05) + print() + _cprint(f" ❌ /btw failed: {e}") + finally: + if self._app: + self._invalidate(min_interval=0) + + thread = threading.Thread(target=run_btw, daemon=True, name=f"btw-{task_id}") + thread.start() + + @staticmethod + def _try_launch_chrome_debug(port: int, system: str) -> bool: + """Try to launch Chrome/Chromium with remote debugging enabled. + + Uses a dedicated user-data-dir so the debug instance doesn't conflict + with an already-running Chrome using the default profile. + + Returns True if a launch command was executed (doesn't guarantee success). + """ + import subprocess as _sp + + candidates = _get_chrome_debug_candidates(system) + + if not candidates: + return False + + # Dedicated profile dir so debug Chrome won't collide with normal Chrome + data_dir = str(_hermes_home / "chrome-debug") + os.makedirs(data_dir, exist_ok=True) + + chrome = candidates[0] + try: + _sp.Popen( + [ + chrome, + f"--remote-debugging-port={port}", + f"--user-data-dir={data_dir}", + "--no-first-run", + "--no-default-browser-check", + ], + stdout=_sp.DEVNULL, + stderr=_sp.DEVNULL, + start_new_session=True, # detach from terminal + ) + return True + except Exception: + return False + + def _handle_browser_command(self, cmd: str): + """Handle /browser connect|disconnect|status — manage live Chrome CDP connection.""" + import platform as _plat + + parts = cmd.strip().split(None, 1) + sub = parts[1].lower().strip() if len(parts) > 1 else "status" + + _DEFAULT_CDP = "http://localhost:9222" + current = os.environ.get("BROWSER_CDP_URL", "").strip() + + if sub.startswith("connect"): + # Optionally accept a custom CDP URL: /browser connect ws://host:port + connect_parts = cmd.strip().split(None, 2) # ["/browser", "connect", "ws://..."] + cdp_url = connect_parts[2].strip() if len(connect_parts) > 2 else _DEFAULT_CDP + + # Clear any existing browser sessions so the next tool call uses the new backend + try: + from tools.browser_tool import cleanup_all_browsers + cleanup_all_browsers() + except Exception: + pass + + print() + + # Extract port for connectivity checks + _port = 9222 + try: + _port = int(cdp_url.rsplit(":", 1)[-1].split("/")[0]) + except (ValueError, IndexError): + pass + + # Check if Chrome is already listening on the debug port + import socket + _already_open = False + try: + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + s.settimeout(1) + s.connect(("127.0.0.1", _port)) + s.close() + _already_open = True + except (OSError, socket.timeout): + pass + + if _already_open: + print(f" ✓ Chrome is already listening on port {_port}") + elif cdp_url == _DEFAULT_CDP: + # Try to auto-launch Chrome with remote debugging + print(" Chrome isn't running with remote debugging — attempting to launch...") + _launched = self._try_launch_chrome_debug(_port, _plat.system()) + if _launched: + # Wait for the port to come up + import time as _time + for _wait in range(10): + try: + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + s.settimeout(1) + s.connect(("127.0.0.1", _port)) + s.close() + _already_open = True + break + except (OSError, socket.timeout): + _time.sleep(0.5) + if _already_open: + print(f" ✓ Chrome launched and listening on port {_port}") + else: + print(f" ⚠ Chrome launched but port {_port} isn't responding yet") + print(" Try again in a few seconds — the debug instance may still be starting") + else: + print(" ⚠ Could not auto-launch Chrome") + # Show manual instructions as fallback + _data_dir = str(_hermes_home / "chrome-debug") + sys_name = _plat.system() + if sys_name == "Darwin": + chrome_cmd = ( + 'open -a "Google Chrome" --args' + f" --remote-debugging-port=9222" + f' --user-data-dir="{_data_dir}"' + " --no-first-run --no-default-browser-check" + ) + elif sys_name == "Windows": + chrome_cmd = ( + f'chrome.exe --remote-debugging-port=9222' + f' --user-data-dir="{_data_dir}"' + f" --no-first-run --no-default-browser-check" + ) + else: + chrome_cmd = ( + f"google-chrome --remote-debugging-port=9222" + f' --user-data-dir="{_data_dir}"' + f" --no-first-run --no-default-browser-check" + ) + print(f" Launch Chrome manually:") + print(f" {chrome_cmd}") + else: + print(f" ⚠ Port {_port} is not reachable at {cdp_url}") + + os.environ["BROWSER_CDP_URL"] = cdp_url + print() + print("🌐 Browser connected to live Chrome via CDP") + print(f" Endpoint: {cdp_url}") + print() + + # Inject context message so the model knows + if hasattr(self, '_pending_input'): + self._pending_input.put( + "[System note: The user has connected your browser tools to their live Chrome browser " + "via Chrome DevTools Protocol. Your browser_navigate, browser_snapshot, browser_click, " + "and other browser tools now control their real browser — including any pages they have " + "open, logged-in sessions, and cookies. They likely opened specific sites or logged into " + "services before connecting. Please await their instruction before attempting to operate " + "the browser. When you do act, be mindful that your actions affect their real browser — " + "don't close tabs or navigate away from pages without asking.]" + ) + + elif sub == "disconnect": + if current: + os.environ.pop("BROWSER_CDP_URL", None) + try: + from tools.browser_tool import cleanup_all_browsers + cleanup_all_browsers() + except Exception: + pass + print() + print("🌐 Browser disconnected from live Chrome") + print(" Browser tools reverted to default mode (local headless or cloud provider)") + print() + + if hasattr(self, '_pending_input'): + self._pending_input.put( + "[System note: The user has disconnected the browser tools from their live Chrome. " + "Browser tools are back to default mode (headless local browser or cloud provider).]" + ) + else: + print() + print("Browser is not connected to live Chrome (already using default mode)") + print() + + elif sub == "status": + print() + if current: + print("🌐 Browser: connected to live Chrome via CDP") + print(f" Endpoint: {current}") + + _port = 9222 + try: + _port = int(current.rsplit(":", 1)[-1].split("/")[0]) + except (ValueError, IndexError): + pass + try: + import socket + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + s.settimeout(1) + s.connect(("127.0.0.1", _port)) + s.close() + print(" Status: ✓ reachable") + except (OSError, Exception): + print(" Status: ⚠ not reachable (Chrome may not be running)") + else: + try: + from tools.browser_tool import _get_cloud_provider + provider = _get_cloud_provider() + except Exception: + provider = None + + if provider is not None: + print(f"🌐 Browser: {provider.provider_name()} (cloud)") + else: + print("🌐 Browser: local headless Chromium (agent-browser)") + print() + print(" /browser connect — connect to your live Chrome") + print(" /browser disconnect — revert to default") + print() + + else: + print() + print("Usage: /browser connect|disconnect|status") + print() + print(" connect Connect browser tools to your live Chrome session") + print(" disconnect Revert to default browser backend") + print(" status Show current browser mode") + print() + + def _handle_skin_command(self, cmd: str): + """Handle /skin [name] — show or change the display skin.""" + try: + from hermes_cli.skin_engine import list_skins, set_active_skin, get_active_skin_name + except ImportError: + print("Skin engine not available.") + return + + parts = cmd.strip().split(maxsplit=1) + if len(parts) < 2 or not parts[1].strip(): + # Show current skin and list available + current = get_active_skin_name() + skins = list_skins() + print(f"\n Current skin: {current}") + print(" Available skins:") + for s in skins: + marker = " ●" if s["name"] == current else " " + source = f" ({s['source']})" if s["source"] == "user" else "" + print(f" {marker} {s['name']}{source} — {s['description']}") + print("\n Usage: /skin ") + print(f" Custom skins: drop a YAML file in {display_hermes_home()}/skins/\n") + return + + new_skin = parts[1].strip().lower() + available = {s["name"] for s in list_skins()} + if new_skin not in available: + print(f" Unknown skin: {new_skin}") + print(f" Available: {', '.join(sorted(available))}") + return + + set_active_skin(new_skin) + _ACCENT.reset() # Re-resolve ANSI color for the new skin + _DIM.reset() # Re-resolve dim/secondary ANSI color for the new skin + if save_config_value("display.skin", new_skin): + print(f" Skin set to: {new_skin} (saved)") + else: + print(f" Skin set to: {new_skin}") + print(" Note: banner colors will update on next session start.") + if self._apply_tui_skin_style(): + print(" Prompt + TUI colors updated.") + + def _toggle_verbose(self): + """Cycle tool progress mode: off → new → all → verbose → off.""" + cycle = ["off", "new", "all", "verbose"] + try: + idx = cycle.index(self.tool_progress_mode) + except ValueError: + idx = 2 # default to "all" + self.tool_progress_mode = cycle[(idx + 1) % len(cycle)] + self.verbose = self.tool_progress_mode == "verbose" + + if self.agent: + self.agent.verbose_logging = self.verbose + self.agent.quiet_mode = not self.verbose + self.agent.reasoning_callback = self._current_reasoning_callback() + + # Use raw ANSI codes via _cprint so the output is routed through + # prompt_toolkit's renderer. self.console.print() with Rich markup + # writes directly to stdout which patch_stdout's StdoutProxy mangles + # into garbled sequences like '?[33mTool progress: NEW?[0m' (#2262). + from hermes_cli.colors import Colors as _Colors + labels = { + "off": f"{_Colors.DIM}Tool progress: OFF{_Colors.RESET} — silent mode, just the final response.", + "new": f"{_Colors.YELLOW}Tool progress: NEW{_Colors.RESET} — show each new tool (skip repeats).", + "all": f"{_Colors.GREEN}Tool progress: ALL{_Colors.RESET} — show every tool call.", + "verbose": f"{_Colors.BOLD}{_Colors.GREEN}Tool progress: VERBOSE{_Colors.RESET} — full args, results, think blocks, and debug logs.", + } + _cprint(labels.get(self.tool_progress_mode, "")) + + def _toggle_yolo(self): + """Toggle YOLO mode — skip all dangerous command approval prompts.""" + import os + current = bool(os.environ.get("HERMES_YOLO_MODE")) + if current: + os.environ.pop("HERMES_YOLO_MODE", None) + self.console.print(" ⚠ YOLO mode [bold red]OFF[/] — dangerous commands will require approval.") + else: + os.environ["HERMES_YOLO_MODE"] = "1" + self.console.print(" ⚡ YOLO mode [bold green]ON[/] — all commands auto-approved. Use with caution.") + + def _handle_reasoning_command(self, cmd: str): + """Handle /reasoning — manage effort level and display toggle. + + Usage: + /reasoning Show current effort level and display state + /reasoning Set reasoning effort (none, minimal, low, medium, high, xhigh) + /reasoning show|on Show model thinking/reasoning in output + /reasoning hide|off Hide model thinking/reasoning from output + """ + parts = cmd.strip().split(maxsplit=1) + + if len(parts) < 2: + # Show current state + rc = self.reasoning_config + if rc is None: + level = "medium (default)" + elif rc.get("enabled") is False: + level = "none (disabled)" + else: + level = rc.get("effort", "medium") + display_state = "on ✓" if self.show_reasoning else "off" + _cprint(f" {_ACCENT}Reasoning effort: {level}{_RST}") + _cprint(f" {_ACCENT}Reasoning display: {display_state}{_RST}") + _cprint(f" {_DIM}Usage: /reasoning {_RST}") + return + + arg = parts[1].strip().lower() + + # Display toggle + if arg in ("show", "on"): + self.show_reasoning = True + if self.agent: + self.agent.reasoning_callback = self._current_reasoning_callback() + save_config_value("display.show_reasoning", True) + _cprint(f" {_ACCENT}✓ Reasoning display: ON (saved){_RST}") + _cprint(f" {_DIM} Model thinking will be shown during and after each response.{_RST}") + return + if arg in ("hide", "off"): + self.show_reasoning = False + if self.agent: + self.agent.reasoning_callback = self._current_reasoning_callback() + save_config_value("display.show_reasoning", False) + _cprint(f" {_ACCENT}✓ Reasoning display: OFF (saved){_RST}") + return + + # Effort level change + parsed = _parse_reasoning_config(arg) + if parsed is None: + _cprint(f" {_DIM}(._.) Unknown argument: {arg}{_RST}") + _cprint(f" {_DIM}Valid levels: none, minimal, low, medium, high, xhigh{_RST}") + _cprint(f" {_DIM}Display: show, hide{_RST}") + return + + self.reasoning_config = parsed + self.agent = None # Force agent re-init with new reasoning config + + if save_config_value("agent.reasoning_effort", arg): + _cprint(f" {_ACCENT}✓ Reasoning effort set to '{arg}' (saved to config){_RST}") + else: + _cprint(f" {_ACCENT}✓ Reasoning effort set to '{arg}' (session only){_RST}") + + def _handle_fast_command(self, cmd: str): + """Handle /fast — toggle fast mode (OpenAI Priority Processing / Anthropic Fast Mode).""" + if not self._fast_command_available(): + _cprint(" (._.) /fast is only available for models that support fast mode (OpenAI Priority Processing or Anthropic Fast Mode).") + return + + # Determine the branding for the current model + try: + from hermes_cli.models import _is_anthropic_fast_model + agent = getattr(self, "agent", None) + model = getattr(agent, "model", None) or getattr(self, "model", None) + feature_name = "Anthropic Fast Mode" if _is_anthropic_fast_model(model) else "Priority Processing" + except Exception: + feature_name = "Fast mode" + + parts = cmd.strip().split(maxsplit=1) + if len(parts) < 2 or parts[1].strip().lower() == "status": + status = "fast" if self.service_tier == "priority" else "normal" + _cprint(f" {_ACCENT}{feature_name}: {status}{_RST}") + _cprint(f" {_DIM}Usage: /fast [normal|fast|status]{_RST}") + return + + arg = parts[1].strip().lower() + + if arg in {"fast", "on"}: + self.service_tier = "priority" + saved_value = "fast" + label = "FAST" + elif arg in {"normal", "off"}: + self.service_tier = None + saved_value = "normal" + label = "NORMAL" + else: + _cprint(f" {_DIM}(._.) Unknown argument: {arg}{_RST}") + _cprint(f" {_DIM}Usage: /fast [normal|fast|status]{_RST}") + return + + self.agent = None # Force agent re-init with new service-tier config + if save_config_value("agent.service_tier", saved_value): + _cprint(f" {_ACCENT}✓ {feature_name} set to {label} (saved to config){_RST}") + else: + _cprint(f" {_ACCENT}✓ {feature_name} set to {label} (session only){_RST}") + + def _on_reasoning(self, reasoning_text: str): + """Callback for intermediate reasoning display during tool-call loops.""" + if not reasoning_text: + return + self._reasoning_preview_buf = getattr(self, "_reasoning_preview_buf", "") + reasoning_text + self._flush_reasoning_preview(force=False) + + def _manual_compress(self, cmd_original: str = ""): + """Manually trigger context compression on the current conversation. + + Accepts an optional focus topic: ``/compress `` guides the + summariser to preserve information related to *focus* while being + more aggressive about discarding everything else. Inspired by + Claude Code's ``/compact `` feature. + """ + if not self.conversation_history or len(self.conversation_history) < 4: + print("(._.) Not enough conversation to compress (need at least 4 messages).") + return + + if not self.agent: + print("(._.) No active agent -- send a message first.") + return + + if not self.agent.compression_enabled: + print("(._.) Compression is disabled in config.") + return + + # Extract optional focus topic from the command (e.g. "/compress database schema") + focus_topic = "" + if cmd_original: + parts = cmd_original.strip().split(None, 1) + if len(parts) > 1: + focus_topic = parts[1].strip() + + original_count = len(self.conversation_history) + try: + from agent.model_metadata import estimate_messages_tokens_rough + from agent.manual_compression_feedback import summarize_manual_compression + original_history = list(self.conversation_history) + approx_tokens = estimate_messages_tokens_rough(original_history) + if focus_topic: + print(f"🗜️ Compressing {original_count} messages (~{approx_tokens:,} tokens), " + f"focus: \"{focus_topic}\"...") + else: + print(f"🗜️ Compressing {original_count} messages (~{approx_tokens:,} tokens)...") + + compressed, _ = self.agent._compress_context( + original_history, + self.agent._cached_system_prompt or "", + approx_tokens=approx_tokens, + focus_topic=focus_topic or None, + ) + self.conversation_history = compressed + new_tokens = estimate_messages_tokens_rough(self.conversation_history) + summary = summarize_manual_compression( + original_history, + self.conversation_history, + approx_tokens, + new_tokens, + ) + icon = "🗜️" if summary["noop"] else "✅" + print(f" {icon} {summary['headline']}") + print(f" {summary['token_line']}") + if summary["note"]: + print(f" {summary['note']}") + + except Exception as e: + print(f" ❌ Compression failed: {e}") + + def _handle_debug_command(self): + """Handle /debug — upload debug report + logs and print paste URLs.""" + from hermes_cli.debug import run_debug_share + from types import SimpleNamespace + + args = SimpleNamespace(lines=200, expire=7, local=False) + run_debug_share(args) + + def _show_usage(self): + """Show rate limits (if available) and session token usage.""" + if not self.agent: + print("(._.) No active agent -- send a message first.") + return + + agent = self.agent + calls = agent.session_api_calls + + if calls == 0: + print("(._.) No API calls made yet in this session.") + return + + # ── Rate limits (shown first when available) ──────────────── + rl_state = agent.get_rate_limit_state() + if rl_state and rl_state.has_data: + from agent.rate_limit_tracker import format_rate_limit_display + print() + print(format_rate_limit_display(rl_state)) + print() + + # ── Session token usage ───────────────────────────────────── + input_tokens = getattr(agent, "session_input_tokens", 0) or 0 + output_tokens = getattr(agent, "session_output_tokens", 0) or 0 + cache_read_tokens = getattr(agent, "session_cache_read_tokens", 0) or 0 + cache_write_tokens = getattr(agent, "session_cache_write_tokens", 0) or 0 + prompt = agent.session_prompt_tokens + completion = agent.session_completion_tokens + total = agent.session_total_tokens + + compressor = agent.context_compressor + last_prompt = compressor.last_prompt_tokens + ctx_len = compressor.context_length + pct = min(100, (last_prompt / ctx_len * 100)) if ctx_len else 0 + compressions = compressor.compression_count + + msg_count = len(self.conversation_history) + cost_result = estimate_usage_cost( + agent.model, + CanonicalUsage( + input_tokens=input_tokens, + output_tokens=output_tokens, + cache_read_tokens=cache_read_tokens, + cache_write_tokens=cache_write_tokens, + ), + provider=getattr(agent, "provider", None), + base_url=getattr(agent, "base_url", None), + ) + elapsed = format_duration_compact((datetime.now() - self.session_start).total_seconds()) + + print(" 📊 Session Token Usage") + print(f" {'─' * 40}") + print(f" Model: {agent.model}") + print(f" Input tokens: {input_tokens:>10,}") + print(f" Cache read tokens: {cache_read_tokens:>10,}") + print(f" Cache write tokens: {cache_write_tokens:>10,}") + print(f" Output tokens: {output_tokens:>10,}") + print(f" Prompt tokens (total): {prompt:>10,}") + print(f" Completion tokens: {completion:>10,}") + print(f" Total tokens: {total:>10,}") + print(f" API calls: {calls:>10,}") + print(f" Session duration: {elapsed:>10}") + print(f" Cost status: {cost_result.status:>10}") + print(f" Cost source: {cost_result.source:>10}") + if cost_result.amount_usd is not None: + prefix = "~" if cost_result.status == "estimated" else "" + print(f" Total cost: {prefix}${float(cost_result.amount_usd):>10.4f}") + elif cost_result.status == "included": + print(f" Total cost: {'included':>10}") + else: + print(f" Total cost: {'n/a':>10}") + print(f" {'─' * 40}") + print(f" Current context: {last_prompt:,} / {ctx_len:,} ({pct:.0f}%)") + print(f" Messages: {msg_count}") + print(f" Compressions: {compressions}") + if cost_result.status == "unknown": + print(f" Note: Pricing unknown for {agent.model}") + + if self.verbose: + logging.getLogger().setLevel(logging.DEBUG) + for noisy in ('openai', 'openai._base_client', 'httpx', 'httpcore', 'asyncio', 'hpack', 'grpc', 'modal'): + logging.getLogger(noisy).setLevel(logging.WARNING) + else: + logging.getLogger().setLevel(logging.INFO) + for quiet_logger in ('tools', 'run_agent', 'trajectory_compressor', 'cron', 'hermes_cli'): + logging.getLogger(quiet_logger).setLevel(logging.ERROR) + + def _show_insights(self, command: str = "/insights"): + """Show usage insights and analytics from session history.""" + # Parse optional --days flag + parts = command.split() + days = 30 + source = None + i = 1 + while i < len(parts): + if parts[i] == "--days" and i + 1 < len(parts): + try: + days = int(parts[i + 1]) + except ValueError: + print(f" Invalid --days value: {parts[i + 1]}") + return + i += 2 + elif parts[i] == "--source" and i + 1 < len(parts): + source = parts[i + 1] + i += 2 + else: + i += 1 + + try: + from hermes_state import SessionDB + from agent.insights import InsightsEngine + + db = SessionDB() + engine = InsightsEngine(db) + report = engine.generate(days=days, source=source) + print(engine.format_terminal(report)) + db.close() + except Exception as e: + print(f" Error generating insights: {e}") + + def _check_config_mcp_changes(self) -> None: + """Detect mcp_servers changes in config.yaml and auto-reload MCP connections. + + Called from process_loop every CONFIG_WATCH_INTERVAL seconds. + Compares config.yaml mtime + mcp_servers section against the last + known state. When a change is detected, triggers _reload_mcp() and + informs the user so they know the tool list has been refreshed. + """ + import time + import yaml as _yaml + + CONFIG_WATCH_INTERVAL = 5.0 # seconds between config.yaml stat() calls + + now = time.monotonic() + if now - self._last_config_check < CONFIG_WATCH_INTERVAL: + return + self._last_config_check = now + + from hermes_cli.config import get_config_path as _get_config_path + cfg_path = _get_config_path() + if not cfg_path.exists(): + return + + try: + mtime = cfg_path.stat().st_mtime + except OSError: + return + + if mtime == self._config_mtime: + return # File unchanged — fast path + + # File changed — check whether mcp_servers section changed + self._config_mtime = mtime + try: + with open(cfg_path, encoding="utf-8") as f: + new_cfg = _yaml.safe_load(f) or {} + except Exception: + return + + new_mcp = new_cfg.get("mcp_servers") or {} + if new_mcp == self._config_mcp_servers: + return # mcp_servers unchanged (some other section was edited) + + self._config_mcp_servers = new_mcp + # Notify user and reload. Run in a separate thread with a hard + # timeout so a hung MCP server cannot block the process_loop + # indefinitely (which would freeze the entire TUI). + print() + print("🔄 MCP server config changed — reloading connections...") + _reload_thread = threading.Thread( + target=self._reload_mcp, daemon=True + ) + _reload_thread.start() + _reload_thread.join(timeout=30) + if _reload_thread.is_alive(): + print(" ⚠️ MCP reload timed out (30s). Some servers may not have reconnected.") + + def _reload_mcp(self): + """Reload MCP servers: disconnect all, re-read config.yaml, reconnect. + + After reconnecting, refreshes the agent's tool list so the model + sees the updated tools on the next turn. + """ + try: + from tools.mcp_tool import shutdown_mcp_servers, discover_mcp_tools, _servers, _lock + + # Capture old server names + with _lock: + old_servers = set(_servers.keys()) + + if not self._command_running: + print("🔄 Reloading MCP servers...") + + # Shutdown existing connections + shutdown_mcp_servers() + + # Reconnect (reads config.yaml fresh) + new_tools = discover_mcp_tools() + + # Compute what changed + with _lock: + connected_servers = set(_servers.keys()) + + added = connected_servers - old_servers + removed = old_servers - connected_servers + reconnected = connected_servers & old_servers + + if reconnected: + print(f" ♻️ Reconnected: {', '.join(sorted(reconnected))}") + if added: + print(f" ➕ Added: {', '.join(sorted(added))}") + if removed: + print(f" ➖ Removed: {', '.join(sorted(removed))}") + if not connected_servers: + print(" No MCP servers connected.") + else: + print(f" 🔧 {len(new_tools)} tool(s) available from {len(connected_servers)} server(s)") + + # Refresh the agent's tool list so the model can call new tools + if self.agent is not None: + from model_tools import get_tool_definitions + self.agent.tools = get_tool_definitions( + enabled_toolsets=self.agent.enabled_toolsets + if hasattr(self.agent, "enabled_toolsets") else None, + quiet_mode=True, + ) + self.agent.valid_tool_names = { + tool["function"]["name"] for tool in self.agent.tools + } if self.agent.tools else set() + + # Inject a message at the END of conversation history so the + # model knows tools changed. Appended after all existing + # messages to preserve prompt-cache for the prefix. + change_parts = [] + if added: + change_parts.append(f"Added servers: {', '.join(sorted(added))}") + if removed: + change_parts.append(f"Removed servers: {', '.join(sorted(removed))}") + if reconnected: + change_parts.append(f"Reconnected servers: {', '.join(sorted(reconnected))}") + tool_summary = f"{len(new_tools)} MCP tool(s) now available" if new_tools else "No MCP tools available" + change_detail = ". ".join(change_parts) + ". " if change_parts else "" + self.conversation_history.append({ + "role": "user", + "content": f"[SYSTEM: MCP servers have been reloaded. {change_detail}{tool_summary}. The tool list for this conversation has been updated accordingly.]", + }) + + # Persist session immediately so the session log reflects the + # updated tools list (self.agent.tools was refreshed above). + if self.agent is not None: + try: + self.agent._persist_session( + self.conversation_history, + self.conversation_history, + ) + except Exception: + pass # Best-effort + + print(f" ✅ Agent updated — {len(self.agent.tools if self.agent else [])} tool(s) available") + + except Exception as e: + print(f" ❌ MCP reload failed: {e}") + + # ==================================================================== + # Tool-call generation indicator (shown during streaming) + # ==================================================================== + + def _on_tool_gen_start(self, tool_name: str) -> None: + """Called when the model begins generating tool-call arguments. + + Closes any open streaming boxes (reasoning / response) exactly once, + then prints a short status line so the user sees activity instead of + a frozen screen while a large payload (e.g. 45 KB write_file) streams. + """ + if getattr(self, "_stream_box_opened", False): + self._flush_stream() + self._stream_box_opened = False + self._close_reasoning_box() + + from agent.display import get_tool_emoji + emoji = get_tool_emoji(tool_name, default="⚡") + _cprint(f" ┊ {emoji} preparing {tool_name}…") + + # ==================================================================== + # Tool progress callback (audio cues for voice mode) + # ==================================================================== + + def _on_tool_progress(self, event_type: str, function_name: str = None, preview: str = None, function_args: dict = None, **kwargs): + """Called on tool lifecycle events (tool.started, tool.completed, reasoning.available, etc.). + + Updates the TUI spinner widget so the user can see what the agent + is doing during tool execution (fills the gap between thinking + spinner and next response). Also plays audio cue in voice mode. + + On tool.started, records a monotonic timestamp so get_spinner_text() + can show a live elapsed timer (the TUI poll loop already invalidates + every ~0.15s, so the counter updates automatically). + + When tool_progress_mode is "all" or "new", also prints a persistent + stacked line to scrollback on tool.completed so users can see the + full history of tool calls (not just the current one in the spinner). + """ + if event_type == "tool.completed": + import time as _time + self._tool_start_time = 0.0 + # Print stacked scrollback line for "all" / "new" modes + if function_name and self.tool_progress_mode in ("all", "new"): + duration = kwargs.get("duration", 0.0) + is_error = kwargs.get("is_error", False) + # Pop stored args from tool.started for this function + stored = self._pending_tool_info.get(function_name) + stored_args = stored.pop(0) if stored else {} + if stored is not None and not stored: + del self._pending_tool_info[function_name] + # "new" mode: skip consecutive repeats of the same tool + if self.tool_progress_mode == "new" and function_name == self._last_scrollback_tool: + self._invalidate() + return + self._last_scrollback_tool = function_name + try: + from agent.display import get_cute_tool_message + line = get_cute_tool_message(function_name, stored_args, duration) + if is_error: + line = f"{line} [error]" + _cprint(f" {line}") + except Exception: + pass + self._invalidate() + return + if event_type != "tool.started": + return + if function_name and not function_name.startswith("_"): + import time as _time + from agent.display import get_tool_emoji + emoji = get_tool_emoji(function_name) + label = preview or function_name + from agent.display import get_tool_preview_max_len + _pl = get_tool_preview_max_len() + if _pl > 0 and len(label) > _pl: + label = label[:_pl - 3] + "..." + self._spinner_text = f"{emoji} {label}" + self._tool_start_time = _time.monotonic() + # Store args for stacked scrollback line on completion + self._pending_tool_info.setdefault(function_name, []).append( + function_args if function_args is not None else {} + ) + self._invalidate() + + if not self._voice_mode: + return + if not function_name or function_name.startswith("_"): + return + try: + from tools.voice_mode import play_beep + threading.Thread( + target=play_beep, + kwargs={"frequency": 1200, "duration": 0.06, "count": 1}, + daemon=True, + ).start() + except Exception: + pass + + def _on_tool_start(self, tool_call_id: str, function_name: str, function_args: dict): + """Capture local before-state for write-capable tools.""" + try: + from agent.display import capture_local_edit_snapshot + + snapshot = capture_local_edit_snapshot(function_name, function_args) + if snapshot is not None: + self._pending_edit_snapshots[tool_call_id] = snapshot + except Exception: + logger.debug("Edit snapshot capture failed for %s", function_name, exc_info=True) + + def _on_tool_complete(self, tool_call_id: str, function_name: str, function_args: dict, function_result: str): + """Render file edits with inline diff after write-capable tools complete.""" + snapshot = self._pending_edit_snapshots.pop(tool_call_id, None) + try: + from agent.display import render_edit_diff_with_delta + + render_edit_diff_with_delta( + function_name, + function_result, + function_args=function_args, + snapshot=snapshot, + print_fn=_cprint, + ) + except Exception: + logger.debug("Edit diff preview failed for %s", function_name, exc_info=True) + + # ==================================================================== + # Voice mode methods + # ==================================================================== + + def _voice_start_recording(self): + """Start capturing audio from the microphone.""" + if getattr(self, '_should_exit', False): + return + from tools.voice_mode import create_audio_recorder, check_voice_requirements + + reqs = check_voice_requirements() + if not reqs["audio_available"]: + if _is_termux_environment(): + details = reqs.get("details", "") + if "Termux:API Android app is not installed" in details: + raise RuntimeError( + "Termux:API command package detected, but the Android app is missing.\n" + "Install/update the Termux:API Android app, then retry /voice on.\n" + "Fallback: pkg install python-numpy portaudio && python -m pip install sounddevice" + ) + raise RuntimeError( + "Voice mode requires either Termux:API microphone access or Python audio libraries.\n" + "Option 1: pkg install termux-api and install the Termux:API Android app\n" + "Option 2: pkg install python-numpy portaudio && python -m pip install sounddevice" + ) + raise RuntimeError( + "Voice mode requires sounddevice and numpy.\n" + "Install with: pip install sounddevice numpy\n" + "Or: pip install hermes-agent[voice]" + ) + if not reqs.get("stt_available", reqs.get("stt_key_set")): + raise RuntimeError( + "Voice mode requires an STT provider for transcription.\n" + "Option 1: pip install faster-whisper (free, local)\n" + "Option 2: Set GROQ_API_KEY (free tier)\n" + "Option 3: Set VOICE_TOOLS_OPENAI_KEY (paid)" + ) + + # Prevent double-start from concurrent threads (atomic check-and-set) + with self._voice_lock: + if self._voice_recording: + return + self._voice_recording = True + + # Load silence detection params from config + voice_cfg = {} + try: + from hermes_cli.config import load_config + voice_cfg = load_config().get("voice", {}) + except Exception: + pass + + if self._voice_recorder is None: + self._voice_recorder = create_audio_recorder() + + # Apply config-driven silence params + self._voice_recorder._silence_threshold = voice_cfg.get("silence_threshold", 200) + self._voice_recorder._silence_duration = voice_cfg.get("silence_duration", 3.0) + + def _on_silence(): + """Called by AudioRecorder when silence is detected after speech.""" + with self._voice_lock: + if not self._voice_recording: + return + _cprint(f"\n{_DIM}Silence detected, auto-stopping...{_RST}") + if hasattr(self, '_app') and self._app: + self._app.invalidate() + self._voice_stop_and_transcribe() + + # Audio cue: single beep BEFORE starting stream (avoid CoreAudio conflict) + try: + from tools.voice_mode import play_beep + play_beep(frequency=880, count=1) + except Exception: + pass + + try: + self._voice_recorder.start(on_silence_stop=_on_silence) + except Exception: + with self._voice_lock: + self._voice_recording = False + raise + if getattr(self._voice_recorder, "supports_silence_autostop", True): + _recording_hint = "auto-stops on silence | Ctrl+B to stop & exit continuous" + elif _is_termux_environment(): + _recording_hint = "Termux:API capture | Ctrl+B to stop" + else: + _recording_hint = "Ctrl+B to stop" + _cprint(f"\n{_ACCENT}● Recording...{_RST} {_DIM}({_recording_hint}){_RST}") + + # Periodically refresh prompt to update audio level indicator + def _refresh_level(): + while True: + with self._voice_lock: + still_recording = self._voice_recording + if not still_recording: + break + if hasattr(self, '_app') and self._app: + self._app.invalidate() + time.sleep(0.15) + threading.Thread(target=_refresh_level, daemon=True).start() + + def _voice_stop_and_transcribe(self): + """Stop recording, transcribe via STT, and queue the transcript as input.""" + # Atomic guard: only one thread can enter stop-and-transcribe. + # Set _voice_processing immediately so concurrent Ctrl+B presses + # don't race into the START path while recorder.stop() holds its lock. + with self._voice_lock: + if not self._voice_recording: + return + self._voice_recording = False + self._voice_processing = True + + submitted = False + wav_path = None + try: + if self._voice_recorder is None: + return + + wav_path = self._voice_recorder.stop() + + # Audio cue: double beep after stream stopped (no CoreAudio conflict) + try: + from tools.voice_mode import play_beep + play_beep(frequency=660, count=2) + except Exception: + pass + + if wav_path is None: + _cprint(f"{_DIM}No speech detected.{_RST}") + return + + # _voice_processing is already True (set atomically above) + if hasattr(self, '_app') and self._app: + self._app.invalidate() + _cprint(f"{_DIM}Transcribing...{_RST}") + + # Get STT model from config + stt_model = None + try: + from hermes_cli.config import load_config + stt_config = load_config().get("stt", {}) + stt_model = stt_config.get("model") + except Exception: + pass + + from tools.voice_mode import transcribe_recording + result = transcribe_recording(wav_path, model=stt_model) + + if result.get("success") and result.get("transcript", "").strip(): + transcript = result["transcript"].strip() + self._attached_images.clear() + if hasattr(self, '_app') and self._app: + self._app.invalidate() + self._pending_input.put(transcript) + submitted = True + elif result.get("success"): + _cprint(f"{_DIM}No speech detected.{_RST}") + else: + error = result.get("error", "Unknown error") + _cprint(f"\n{_DIM}Transcription failed: {error}{_RST}") + + except Exception as e: + _cprint(f"\n{_DIM}Voice processing error: {e}{_RST}") + finally: + with self._voice_lock: + self._voice_processing = False + if hasattr(self, '_app') and self._app: + self._app.invalidate() + # Clean up temp file + try: + if wav_path and os.path.isfile(wav_path): + os.unlink(wav_path) + except Exception: + pass + + # Track consecutive no-speech cycles to avoid infinite restart loops. + if not submitted: + self._no_speech_count = getattr(self, '_no_speech_count', 0) + 1 + if self._no_speech_count >= 3: + self._voice_continuous = False + self._no_speech_count = 0 + _cprint(f"{_DIM}No speech detected 3 times, continuous mode stopped.{_RST}") + return + else: + self._no_speech_count = 0 + + # If no transcript was submitted but continuous mode is active, + # restart recording so the user can keep talking. + # (When transcript IS submitted, process_loop handles restart + # after chat() completes.) + if self._voice_continuous and not submitted and not self._voice_recording: + def _restart_recording(): + try: + self._voice_start_recording() + if hasattr(self, '_app') and self._app: + self._app.invalidate() + except Exception as e: + _cprint(f"{_DIM}Voice auto-restart failed: {e}{_RST}") + threading.Thread(target=_restart_recording, daemon=True).start() + + def _voice_speak_response(self, text: str): + """Speak the agent's response aloud using TTS (runs in background thread).""" + if not self._voice_tts: + return + self._voice_tts_done.clear() + try: + from tools.tts_tool import text_to_speech_tool + from tools.voice_mode import play_audio_file + import re + + # Strip markdown and non-speech content for cleaner TTS + tts_text = text[:4000] if len(text) > 4000 else text + tts_text = re.sub(r'```[\s\S]*?```', ' ', tts_text) # fenced code blocks + tts_text = re.sub(r'\[([^\]]+)\]\([^)]+\)', r'\1', tts_text) # [text](url) -> text + tts_text = re.sub(r'https?://\S+', '', tts_text) # URLs + tts_text = re.sub(r'\*\*(.+?)\*\*', r'\1', tts_text) # bold + tts_text = re.sub(r'\*(.+?)\*', r'\1', tts_text) # italic + tts_text = re.sub(r'`(.+?)`', r'\1', tts_text) # inline code + tts_text = re.sub(r'^#+\s*', '', tts_text, flags=re.MULTILINE) # headers + tts_text = re.sub(r'^\s*[-*]\s+', '', tts_text, flags=re.MULTILINE) # list items + tts_text = re.sub(r'---+', '', tts_text) # horizontal rules + tts_text = re.sub(r'\n{3,}', '\n\n', tts_text) # excessive newlines + tts_text = tts_text.strip() + if not tts_text: + return + + # Use MP3 output for CLI playback (afplay doesn't handle OGG well). + # The TTS tool may auto-convert MP3->OGG, but the original MP3 remains. + os.makedirs(os.path.join(tempfile.gettempdir(), "hermes_voice"), exist_ok=True) + mp3_path = os.path.join( + tempfile.gettempdir(), "hermes_voice", + f"tts_{time.strftime('%Y%m%d_%H%M%S')}.mp3", + ) + + text_to_speech_tool(text=tts_text, output_path=mp3_path) + + # Play the MP3 directly (the TTS tool returns OGG path but MP3 still exists) + if os.path.isfile(mp3_path) and os.path.getsize(mp3_path) > 0: + play_audio_file(mp3_path) + # Clean up + try: + os.unlink(mp3_path) + ogg_path = mp3_path.rsplit(".", 1)[0] + ".ogg" + if os.path.isfile(ogg_path): + os.unlink(ogg_path) + except OSError: + pass + except Exception as e: + logger.warning("Voice TTS playback failed: %s", e) + _cprint(f"{_DIM}TTS playback failed: {e}{_RST}") + finally: + self._voice_tts_done.set() + + def _handle_voice_command(self, command: str): + """Handle /voice [on|off|tts|status] command.""" + parts = command.strip().split(maxsplit=1) + subcommand = parts[1].lower().strip() if len(parts) > 1 else "" + + if subcommand == "on": + self._enable_voice_mode() + elif subcommand == "off": + self._disable_voice_mode() + elif subcommand == "tts": + self._toggle_voice_tts() + elif subcommand == "status": + self._show_voice_status() + elif subcommand == "": + # Toggle + if self._voice_mode: + self._disable_voice_mode() + else: + self._enable_voice_mode() + else: + _cprint(f"Unknown voice subcommand: {subcommand}") + _cprint("Usage: /voice [on|off|tts|status]") + + def _enable_voice_mode(self): + """Enable voice mode after checking requirements.""" + if self._voice_mode: + _cprint(f"{_DIM}Voice mode is already enabled.{_RST}") + return + + from tools.voice_mode import check_voice_requirements, detect_audio_environment + + # Environment detection -- warn and block in incompatible environments + env_check = detect_audio_environment() + if not env_check["available"]: + _cprint(f"\n{_ACCENT}Voice mode unavailable in this environment:{_RST}") + for warning in env_check["warnings"]: + _cprint(f" {_DIM}{warning}{_RST}") + return + + reqs = check_voice_requirements() + if not reqs["available"]: + _cprint(f"\n{_ACCENT}Voice mode requirements not met:{_RST}") + for line in reqs["details"].split("\n"): + _cprint(f" {_DIM}{line}{_RST}") + if reqs["missing_packages"]: + if _is_termux_environment(): + _cprint(f"\n {_BOLD}Option 1: pkg install termux-api{_RST}") + _cprint(f" {_DIM}Then install/update the Termux:API Android app for microphone capture{_RST}") + _cprint(f" {_BOLD}Option 2: pkg install python-numpy portaudio && python -m pip install sounddevice{_RST}") + else: + _cprint(f"\n {_BOLD}Install: pip install {' '.join(reqs['missing_packages'])}{_RST}") + _cprint(f" {_DIM}Or: pip install hermes-agent[voice]{_RST}") + return + + with self._voice_lock: + self._voice_mode = True + + # Check config for auto_tts + try: + from hermes_cli.config import load_config + voice_config = load_config().get("voice", {}) + if voice_config.get("auto_tts", False): + with self._voice_lock: + self._voice_tts = True + except Exception: + pass + + # Voice mode instruction is injected as a user message prefix (not a + # system prompt change) to avoid invalidating the prompt cache. See + # _voice_message_prefix property and its usage in _process_message(). + + tts_status = " (TTS enabled)" if self._voice_tts else "" + try: + from hermes_cli.config import load_config + _raw_ptt = load_config().get("voice", {}).get("record_key", "ctrl+b") + _ptt_key = _raw_ptt.lower().replace("ctrl+", "c-").replace("alt+", "a-") + except Exception: + _ptt_key = "c-b" + _ptt_display = _ptt_key.replace("c-", "Ctrl+").upper() + _cprint(f"\n{_ACCENT}Voice mode enabled{tts_status}{_RST}") + _cprint(f" {_DIM}{_ptt_display} to start/stop recording{_RST}") + _cprint(f" {_DIM}/voice tts to toggle speech output{_RST}") + _cprint(f" {_DIM}/voice off to disable voice mode{_RST}") + + def _disable_voice_mode(self): + """Disable voice mode, cancel any active recording, and stop TTS.""" + recorder = None + with self._voice_lock: + if self._voice_recording and self._voice_recorder: + self._voice_recorder.cancel() + self._voice_recording = False + recorder = self._voice_recorder + self._voice_mode = False + self._voice_tts = False + self._voice_continuous = False + + # Shut down the persistent audio stream in background + if recorder is not None: + def _bg_shutdown(rec=recorder): + try: + rec.shutdown() + except Exception: + pass + threading.Thread(target=_bg_shutdown, daemon=True).start() + self._voice_recorder = None + + # Stop any active TTS playback + try: + from tools.voice_mode import stop_playback + stop_playback() + except Exception: + pass + self._voice_tts_done.set() + + _cprint(f"\n{_DIM}Voice mode disabled.{_RST}") + + def _toggle_voice_tts(self): + """Toggle TTS output for voice mode.""" + if not self._voice_mode: + _cprint(f"{_DIM}Enable voice mode first: /voice on{_RST}") + return + + with self._voice_lock: + self._voice_tts = not self._voice_tts + status = "enabled" if self._voice_tts else "disabled" + + if self._voice_tts: + from tools.tts_tool import check_tts_requirements + if not check_tts_requirements(): + _cprint(f"{_DIM}Warning: No TTS provider available. Install edge-tts or set API keys.{_RST}") + + _cprint(f"{_ACCENT}Voice TTS {status}.{_RST}") + + def _show_voice_status(self): + """Show current voice mode status.""" + from hermes_cli.config import load_config + from tools.voice_mode import check_voice_requirements + + reqs = check_voice_requirements() + + _cprint(f"\n{_BOLD}Voice Mode Status{_RST}") + _cprint(f" Mode: {'ON' if self._voice_mode else 'OFF'}") + _cprint(f" TTS: {'ON' if self._voice_tts else 'OFF'}") + _cprint(f" Recording: {'YES' if self._voice_recording else 'no'}") + _raw_key = load_config().get("voice", {}).get("record_key", "ctrl+b") + _display_key = _raw_key.replace("ctrl+", "Ctrl+").upper() if "ctrl+" in _raw_key.lower() else _raw_key + _cprint(f" Record key: {_display_key}") + _cprint(f"\n {_BOLD}Requirements:{_RST}") + for line in reqs["details"].split("\n"): + _cprint(f" {line}") + + def _clarify_callback(self, question, choices): + """ + Platform callback for the clarify tool. Called from the agent thread. + + Sets up the interactive selection UI (or freetext prompt for open-ended + questions), then blocks until the user responds via the prompt_toolkit + key bindings. If no response arrives within the configured timeout the + question is dismissed and the agent is told to decide on its own. + """ + import time as _time + + timeout = CLI_CONFIG.get("clarify", {}).get("timeout", 120) + response_queue = queue.Queue() + is_open_ended = not choices + + self._clarify_state = { + "question": question, + "choices": choices if not is_open_ended else [], + "selected": 0, + "response_queue": response_queue, + } + self._clarify_deadline = _time.monotonic() + timeout + # Open-ended questions skip straight to freetext input + self._clarify_freetext = is_open_ended + + # Trigger prompt_toolkit repaint from this (non-main) thread + self._invalidate() + + # Poll for the user's response. The countdown in the hint line + # updates on each invalidate — but frequent repaints cause visible + # flicker in some terminals (Kitty, ghostty). We only refresh the + # countdown every 5 s; selection changes (↑/↓) trigger instant + # Poll for the user's response. The countdown in the hint line + # updates on each invalidate — but frequent repaints cause visible + # flicker in some terminals (Kitty, ghostty). We only refresh the + # countdown every 5 s; selection changes (↑/↓) trigger instant + # repaints via the key bindings. + _last_countdown_refresh = _time.monotonic() + while True: + try: + result = response_queue.get(timeout=1) + self._clarify_deadline = 0 + return result + except queue.Empty: + remaining = self._clarify_deadline - _time.monotonic() + if remaining <= 0: + break + # Only repaint every 5 s for the countdown — avoids flicker + now = _time.monotonic() + if now - _last_countdown_refresh >= 5.0: + _last_countdown_refresh = now + self._invalidate() + if now - _last_countdown_refresh >= 5.0: + _last_countdown_refresh = now + self._invalidate() + + # Timed out — tear down the UI and let the agent decide + self._clarify_state = None + self._clarify_freetext = False + self._clarify_deadline = 0 + self._invalidate() + _cprint(f"\n{_DIM}(clarify timed out after {timeout}s — agent will decide){_RST}") + return ( + "The user did not provide a response within the time limit. " + "Use your best judgement to make the choice and proceed." + ) + + def _sudo_password_callback(self) -> str: + """ + Prompt for sudo password through the prompt_toolkit UI. + + Called from the agent thread when a sudo command is encountered. + Uses the same clarify-style mechanism: sets UI state, waits on a + queue for the user's response via the Enter key binding. + """ + import time as _time + + timeout = 45 + response_queue = queue.Queue() + + self._capture_modal_input_snapshot() + self._sudo_state = { + "response_queue": response_queue, + } + self._sudo_deadline = _time.monotonic() + timeout + + self._invalidate() + + while True: + try: + result = response_queue.get(timeout=1) + self._sudo_state = None + self._sudo_deadline = 0 + self._restore_modal_input_snapshot() + self._invalidate() + if result: + _cprint(f"\n{_DIM} ✓ Password received (cached for session){_RST}") + else: + _cprint(f"\n{_DIM} ⏭ Skipped{_RST}") + return result + except queue.Empty: + remaining = self._sudo_deadline - _time.monotonic() + if remaining <= 0: + break + self._invalidate() + + self._sudo_state = None + self._sudo_deadline = 0 + self._restore_modal_input_snapshot() + self._invalidate() + _cprint(f"\n{_DIM} ⏱ Timeout — continuing without sudo{_RST}") + return "" + + def _approval_callback(self, command: str, description: str, + *, allow_permanent: bool = True) -> str: + """ + Prompt for dangerous command approval through the prompt_toolkit UI. + + Called from the agent thread. Shows a selection UI similar to clarify + with choices: once / session / always / deny. When allow_permanent + is False (tirith warnings present), the 'always' option is hidden. + Long commands also get a 'view' option so the full command can be + expanded before deciding. + + Uses _approval_lock to serialize concurrent requests (e.g. from + parallel delegation subtasks) so each prompt gets its own turn + and the shared _approval_state / _approval_deadline aren't clobbered. + """ + import time as _time + + with self._approval_lock: + timeout = 60 + response_queue = queue.Queue() + + self._approval_state = { + "command": command, + "description": description, + "choices": self._approval_choices(command, allow_permanent=allow_permanent), + "selected": 0, + "response_queue": response_queue, + } + self._approval_deadline = _time.monotonic() + timeout + + self._invalidate() + + _last_countdown_refresh = _time.monotonic() + while True: + try: + result = response_queue.get(timeout=1) + self._approval_state = None + self._approval_deadline = 0 + self._invalidate() + return result + except queue.Empty: + remaining = self._approval_deadline - _time.monotonic() + if remaining <= 0: + break + now = _time.monotonic() + if now - _last_countdown_refresh >= 5.0: + _last_countdown_refresh = now + self._invalidate() + + self._approval_state = None + self._approval_deadline = 0 + self._invalidate() + _cprint(f"\n{_DIM} ⏱ Timeout — denying command{_RST}") + return "deny" + + def _approval_choices(self, command: str, *, allow_permanent: bool = True) -> list[str]: + """Return approval choices for a dangerous command prompt.""" + choices = ["once", "session", "always", "deny"] if allow_permanent else ["once", "session", "deny"] + if len(command) > 70: + choices.append("view") + return choices + + def _handle_approval_selection(self) -> None: + """Process the currently selected dangerous-command approval choice.""" + state = self._approval_state + if not state: + return + + selected = state.get("selected", 0) + choices = state.get("choices") or [] + if not (0 <= selected < len(choices)): + return + + chosen = choices[selected] + if chosen == "view": + state["show_full"] = True + state["choices"] = [choice for choice in choices if choice != "view"] + if state["selected"] >= len(state["choices"]): + state["selected"] = max(0, len(state["choices"]) - 1) + self._invalidate() + return + + state["response_queue"].put(chosen) + self._approval_state = None + self._invalidate() + + def _get_approval_display_fragments(self): + """Render the dangerous-command approval panel for the prompt_toolkit UI.""" + state = self._approval_state + if not state: + return [] + + def _panel_box_width(title_text: str, content_lines: list[str], min_width: int = 46, max_width: int = 76) -> int: + term_cols = shutil.get_terminal_size((100, 20)).columns + longest = max([len(title_text)] + [len(line) for line in content_lines] + [min_width - 4]) + inner = min(max(longest + 4, min_width - 2), max_width - 2, max(24, term_cols - 6)) + return inner + 2 + + def _wrap_panel_text(text: str, width: int, subsequent_indent: str = "") -> list[str]: + wrapped = textwrap.wrap( + text, + width=max(8, width), + replace_whitespace=False, + drop_whitespace=False, + subsequent_indent=subsequent_indent, + ) + return wrapped or [""] + + def _append_panel_line(lines, border_style: str, content_style: str, text: str, box_width: int) -> None: + inner_width = max(0, box_width - 2) + lines.append((border_style, "│ ")) + lines.append((content_style, text.ljust(inner_width))) + lines.append((border_style, " │\n")) + + def _append_blank_panel_line(lines, border_style: str, box_width: int) -> None: + lines.append((border_style, "│" + (" " * box_width) + "│\n")) + + command = state["command"] + description = state["description"] + choices = state["choices"] + selected = state.get("selected", 0) + show_full = state.get("show_full", False) + + title = "⚠️ Dangerous Command" + cmd_display = command if show_full or len(command) <= 70 else command[:70] + '...' + choice_labels = { + "once": "Allow once", + "session": "Allow for this session", + "always": "Add to permanent allowlist", + "deny": "Deny", + "view": "Show full command", + } + + preview_lines = _wrap_panel_text(description, 60) + preview_lines.extend(_wrap_panel_text(cmd_display, 60)) + for i, choice in enumerate(choices): + prefix = '❯ ' if i == selected else ' ' + preview_lines.extend(_wrap_panel_text( + f"{prefix}{choice_labels.get(choice, choice)}", + 60, + subsequent_indent=" ", + )) + + box_width = _panel_box_width(title, preview_lines) + inner_text_width = max(8, box_width - 2) + + lines = [] + lines.append(('class:approval-border', '╭' + ('─' * box_width) + '╮\n')) + _append_panel_line(lines, 'class:approval-border', 'class:approval-title', title, box_width) + _append_blank_panel_line(lines, 'class:approval-border', box_width) + for wrapped in _wrap_panel_text(description, inner_text_width): + _append_panel_line(lines, 'class:approval-border', 'class:approval-desc', wrapped, box_width) + for wrapped in _wrap_panel_text(cmd_display, inner_text_width): + _append_panel_line(lines, 'class:approval-border', 'class:approval-cmd', wrapped, box_width) + _append_blank_panel_line(lines, 'class:approval-border', box_width) + for i, choice in enumerate(choices): + label = choice_labels.get(choice, choice) + style = 'class:approval-selected' if i == selected else 'class:approval-choice' + prefix = '❯ ' if i == selected else ' ' + for wrapped in _wrap_panel_text(f"{prefix}{label}", inner_text_width, subsequent_indent=" "): + _append_panel_line(lines, 'class:approval-border', style, wrapped, box_width) + _append_blank_panel_line(lines, 'class:approval-border', box_width) + lines.append(('class:approval-border', '╰' + ('─' * box_width) + '╯\n')) + return lines + + def _secret_capture_callback(self, var_name: str, prompt: str, metadata=None) -> dict: + return prompt_for_secret(self, var_name, prompt, metadata) + + def _capture_modal_input_snapshot(self) -> None: + """Temporarily clear the input buffer and save the user's in-progress draft.""" + if self._modal_input_snapshot is not None or not getattr(self, "_app", None): + return + try: + buf = self._app.current_buffer + self._modal_input_snapshot = { + "text": buf.text, + "cursor_position": buf.cursor_position, + } + buf.reset() + except Exception: + self._modal_input_snapshot = None + + def _restore_modal_input_snapshot(self) -> None: + """Restore any draft text that was present before a modal prompt opened.""" + snapshot = self._modal_input_snapshot + self._modal_input_snapshot = None + if not snapshot or not getattr(self, "_app", None): + return + try: + buf = self._app.current_buffer + buf.text = snapshot.get("text", "") + buf.cursor_position = min(snapshot.get("cursor_position", 0), len(buf.text)) + except Exception: + pass + + def _submit_secret_response(self, value: str) -> None: + if not self._secret_state: + return + self._secret_state["response_queue"].put(value) + self._secret_state = None + self._secret_deadline = 0 + self._invalidate() + + def _cancel_secret_capture(self) -> None: + self._submit_secret_response("") + + def _clear_secret_input_buffer(self) -> None: + if getattr(self, "_app", None): + try: + self._app.current_buffer.reset() + except Exception: + pass + + def chat(self, message, images: list = None) -> Optional[str]: + """ + Send a message to the agent and get a response. + + Handles streaming output, interrupt detection (user typing while agent + is working), and re-queueing of interrupted messages. + + Uses a dedicated _interrupt_queue (separate from _pending_input) to avoid + race conditions between the process_loop and interrupt monitoring. Messages + typed while the agent is running go to _interrupt_queue; messages typed while + idle go to _pending_input. + + Args: + message: The user's message (str or multimodal content list) + images: Optional list of Path objects for attached images + + Returns: + The agent's response, or None on error + """ + # Single-query and direct chat callers do not go through run(), so + # register secure secret capture here as well. + set_secret_capture_callback(self._secret_capture_callback) + + # Refresh provider credentials if needed (handles key rotation transparently) + if not self._ensure_runtime_credentials(): + return None + + turn_route = self._resolve_turn_agent_config(message) + if turn_route["signature"] != self._active_agent_route_signature: + self.agent = None + + # Initialize agent if needed + if self.agent is None: + _cprint(f"{_DIM}Initializing agent...{_RST}") + if not self._init_agent( + model_override=turn_route["model"], + runtime_override=turn_route["runtime"], + route_label=turn_route["label"], + request_overrides=turn_route.get("request_overrides"), + ): + return None + + # Pre-process images through the vision tool (Gemini Flash) so the + # main model receives text descriptions instead of raw base64 image + # content — works with any model, not just vision-capable ones. + if images: + message = self._preprocess_images_with_vision( + message if isinstance(message, str) else "", images + ) + + # Expand @ context references (e.g. @file:main.py, @diff, @folder:src/) + if isinstance(message, str) and "@" in message: + try: + from agent.context_references import preprocess_context_references + from agent.model_metadata import get_model_context_length + _ctx_len = get_model_context_length( + self.model, base_url=self.base_url or "", api_key=self.api_key or "") + _ctx_result = preprocess_context_references( + message, cwd=os.getcwd(), context_length=_ctx_len) + if _ctx_result.expanded or _ctx_result.blocked: + if _ctx_result.references: + _cprint( + f" {_DIM}[@ context: {len(_ctx_result.references)} ref(s), " + f"{_ctx_result.injected_tokens} tokens]{_RST}") + for w in _ctx_result.warnings: + _cprint(f" {_DIM}⚠ {w}{_RST}") + if _ctx_result.blocked: + return "\n".join(_ctx_result.warnings) or "Context injection refused." + message = _ctx_result.message + except Exception as e: + logging.debug("@ context reference expansion failed: %s", e) + + # Sanitize surrogate characters that can arrive via clipboard paste from + # rich-text editors (Google Docs, Word, etc.). Lone surrogates are invalid + # UTF-8 and crash JSON serialization in the OpenAI SDK. + if isinstance(message, str): + from run_agent import _sanitize_surrogates + message = _sanitize_surrogates(message) + + # Add user message to history + self.conversation_history.append({"role": "user", "content": message}) + + ChatConsole().print(f"[{_accent_hex()}]{'─' * 40}[/]") + print(flush=True) + + try: + # Run the conversation with interrupt monitoring + result = None + + # Reset streaming display state for this turn + self._reset_stream_state() + # Separate from _reset_stream_state because this must persist + # across intermediate turn boundaries (tool-calling loops) — only + # reset at the start of each user turn. + self._reasoning_shown_this_turn = False + + # --- Streaming TTS setup --- + # When ElevenLabs is the TTS provider and sounddevice is available, + # we stream audio sentence-by-sentence as the agent generates tokens + # instead of waiting for the full response. + use_streaming_tts = False + _streaming_box_opened = False + text_queue = None + tts_thread = None + stream_callback = None + stop_event = None + + if self._voice_tts: + try: + from tools.tts_tool import ( + _load_tts_config as _load_tts_cfg, + _get_provider as _get_prov, + _import_elevenlabs, + _import_sounddevice, + stream_tts_to_speaker, + ) + _tts_cfg = _load_tts_cfg() + if _get_prov(_tts_cfg) == "elevenlabs": + # Verify both ElevenLabs SDK and audio output are available + _import_elevenlabs() + _import_sounddevice() + use_streaming_tts = True + except (ImportError, OSError): + pass + except Exception: + pass + + if use_streaming_tts: + text_queue = queue.Queue() + stop_event = threading.Event() + + def display_callback(sentence: str): + """Called by TTS consumer when a sentence is ready to display + speak.""" + nonlocal _streaming_box_opened + if not _streaming_box_opened: + _streaming_box_opened = True + w = self.console.width + label = " ⚕ Hermes " + fill = w - 2 - len(label) + _cprint(f"\n{_ACCENT}╭─{label}{'─' * max(fill - 1, 0)}╮{_RST}") + _cprint(sentence.rstrip()) + + tts_thread = threading.Thread( + target=stream_tts_to_speaker, + args=(text_queue, stop_event, self._voice_tts_done), + kwargs={"display_callback": display_callback}, + daemon=True, + ) + tts_thread.start() + + def stream_callback(delta: str): + if text_queue is not None: + text_queue.put(delta) + + # When voice mode is active, prepend a brief instruction so the + # model responds concisely. The prefix is API-call-local only — + # run_conversation persists the original clean user message. + _voice_prefix = "" + if self._voice_mode and isinstance(message, str): + _voice_prefix = ( + "[Voice input — respond concisely and conversationally, " + "2-3 sentences max. No code blocks or markdown.] " + ) + + def run_agent(): + nonlocal result + agent_message = _voice_prefix + message if _voice_prefix else message + # Prepend pending model switch note so the model knows about the switch + _msn = getattr(self, '_pending_model_switch_note', None) + if _msn: + agent_message = _msn + "\n\n" + agent_message + self._pending_model_switch_note = None + try: + result = self.agent.run_conversation( + user_message=agent_message, + conversation_history=self.conversation_history[:-1], # Exclude the message we just added + stream_callback=stream_callback, + task_id=self.session_id, + persist_user_message=message if _voice_prefix else None, + ) + except Exception as exc: + logging.error("run_conversation raised: %s", exc, exc_info=True) + _summary = getattr(self.agent, '_summarize_api_error', lambda e: str(e)[:300])(exc) + result = { + "final_response": f"Error: {_summary}", + "messages": [], + "api_calls": 0, + "completed": False, + "failed": True, + "error": _summary, + } + + # Start agent in background thread (daemon so it cannot keep the + # process alive when the user closes the terminal tab — SIGHUP + # exits the main thread and daemon threads are reaped automatically). + agent_thread = threading.Thread(target=run_agent, daemon=True) + agent_thread.start() + + # Monitor the dedicated interrupt queue while the agent runs. + # _interrupt_queue is separate from _pending_input, so process_loop + # and chat() never compete for the same queue. + # When a clarify question is active, user input is handled entirely + # by the Enter key binding (routed to the clarify response queue), + # so we skip interrupt processing to avoid stealing that input. + interrupt_msg = None + while agent_thread.is_alive(): + if hasattr(self, '_interrupt_queue'): + try: + interrupt_msg = self._interrupt_queue.get(timeout=0.1) + if interrupt_msg: + # If clarify is active, the Enter handler routes + # input directly; this queue shouldn't have anything. + # But if it does (race condition), don't interrupt. + if self._clarify_state or self._clarify_freetext: + continue + print("\n⚡ New message detected, interrupting...") + # Signal TTS to stop on interrupt + if stop_event is not None: + stop_event.set() + self.agent.interrupt(interrupt_msg) + # Debug: log to file (stdout may be devnull from redirect_stdout) + try: + _dbg = _hermes_home / "interrupt_debug.log" + with open(_dbg, "a") as _f: + import time as _t + _f.write(f"{_t.strftime('%H:%M:%S')} interrupt fired: msg={str(interrupt_msg)[:60]!r}, " + f"children={len(self.agent._active_children)}, " + f"parent._interrupt={self.agent._interrupt_requested}\n") + for _ci, _ch in enumerate(self.agent._active_children): + _f.write(f" child[{_ci}]._interrupt={_ch._interrupt_requested}\n") + except Exception: + pass + break + except queue.Empty: + # Force prompt_toolkit to flush any pending stdout + # output from the agent thread. Without this, the + # StdoutProxy buffer only flushes on renderer passes + # triggered by input events — on macOS this causes + # the CLI to appear frozen until the user types. (#1624) + self._invalidate(min_interval=0.15) + else: + # Fallback for non-interactive mode (e.g., single-query) + agent_thread.join(0.1) + + agent_thread.join() # Ensure agent thread completes + + # Proactively clean up async clients whose event loop is dead. + # The agent thread may have created AsyncOpenAI clients bound + # to a per-thread event loop; if that loop is now closed, those + # clients' __del__ would crash prompt_toolkit's loop on GC. + try: + from agent.auxiliary_client import cleanup_stale_async_clients + cleanup_stale_async_clients() + except Exception: + pass + + # Flush any remaining streamed text and close the box + self._flush_stream() + + # Signal end-of-text to TTS consumer and wait for it to finish + if use_streaming_tts and text_queue is not None: + text_queue.put(None) # sentinel + if tts_thread is not None: + tts_thread.join(timeout=120) + + # Drain any remaining agent output still in the StdoutProxy + # buffer so tool/status lines render ABOVE our response box. + # The flush pushes data into the renderer queue; the short + # sleep lets the renderer actually paint it before we draw. + import time as _time + sys.stdout.flush() + _time.sleep(0.15) + + # Update history with full conversation + self.conversation_history = result.get("messages", self.conversation_history) if result else self.conversation_history + + # Get the final response + response = result.get("final_response", "") if result else "" + + # Auto-generate session title after first exchange (non-blocking) + if response and result and not result.get("failed") and not result.get("partial"): + try: + from agent.title_generator import maybe_auto_title + maybe_auto_title( + self._session_db, + self.session_id, + message, + response, + self.conversation_history, + ) + except Exception: + pass + + # Handle failed or partial results (e.g., non-retryable errors, rate limits, + # truncated output, invalid tool calls). Both "failed" and "partial" with + # an empty final_response mean the agent couldn't produce a usable answer. + if result and (result.get("failed") or result.get("partial")) and not response: + error_detail = result.get("error", "Unknown error") + response = f"Error: {error_detail}" + # Stop continuous voice mode on persistent errors (e.g. 429 rate limit) + # to avoid an infinite error → record → error loop + if self._voice_continuous: + self._voice_continuous = False + _cprint(f"\n{_DIM}Continuous voice mode stopped due to error.{_RST}") + + # Handle interrupt - check if we were interrupted + pending_message = None + if result and result.get("interrupted"): + pending_message = result.get("interrupt_message") or interrupt_msg + # Add indicator that we were interrupted + if response and pending_message: + response = response + "\n\n---\n_[Interrupted - processing new message]_" + + response_previewed = result.get("response_previewed", False) if result else False + + # Display reasoning (thinking) box if enabled and available. + # Skip when streaming already showed reasoning live. Use the + # turn-persistent flag (_reasoning_shown_this_turn) instead of + # _reasoning_stream_started — the latter gets reset during + # intermediate turn boundaries (tool-calling loops), which caused + # the reasoning box to re-render after the final response. + _reasoning_already_shown = getattr(self, '_reasoning_shown_this_turn', False) + if self.show_reasoning and result and not _reasoning_already_shown: + reasoning = result.get("last_reasoning") + if reasoning: + w = shutil.get_terminal_size().columns + r_label = " Reasoning " + r_fill = w - 2 - len(r_label) + r_top = f"{_DIM}┌─{r_label}{'─' * max(r_fill - 1, 0)}┐{_RST}" + r_bot = f"{_DIM}└{'─' * (w - 2)}┘{_RST}" + # Collapse long reasoning: show first 10 lines + lines = reasoning.strip().splitlines() + if len(lines) > 10: + display_reasoning = "\n".join(lines[:10]) + display_reasoning += f"\n{_DIM} ... ({len(lines) - 10} more lines){_RST}" + else: + display_reasoning = reasoning.strip() + _cprint(f"\n{r_top}\n{_DIM}{display_reasoning}{_RST}\n{r_bot}") + + if response and not response_previewed: + # Use skin engine for label/color with fallback + try: + from hermes_cli.skin_engine import get_active_skin + _skin = get_active_skin() + label = _skin.get_branding("response_label", "⚕ Hermes") + _resp_color = _skin.get_color("response_border", "#CD7F32") + _resp_text = _skin.get_color("banner_text", "#FFF8DC") + except Exception: + label = "⚕ Hermes" + _resp_color = "#CD7F32" + _resp_text = "#FFF8DC" + + is_error_response = result and (result.get("failed") or result.get("partial")) + already_streamed = self._stream_started and self._stream_box_opened and not is_error_response + if use_streaming_tts and _streaming_box_opened and not is_error_response: + # Text was already printed sentence-by-sentence; just close the box + w = shutil.get_terminal_size().columns + _cprint(f"\n{_ACCENT}╰{'─' * (w - 2)}╯{_RST}") + elif already_streamed: + # Response was already streamed token-by-token with box framing; + # _flush_stream() already closed the box. Skip Rich Panel. + pass + else: + _chat_console = ChatConsole() + _chat_console.print(Panel( + _rich_text_from_ansi(response), + title=f"[{_resp_color} bold]{label}[/]", + title_align="left", + border_style=_resp_color, + style=_resp_text, + box=rich_box.HORIZONTALS, + padding=(1, 2), + )) + + + # Play terminal bell when agent finishes (if enabled). + # Works over SSH — the bell propagates to the user's terminal. + if self.bell_on_complete: + sys.stdout.write("\a") + sys.stdout.flush() + + # Notify when iteration budget was hit + if result and not result.get("completed") and not result.get("interrupted"): + _api_calls = result.get("api_calls", 0) + if _api_calls >= getattr(self.agent, "max_iterations", 90): + _max_iter = getattr(self.agent, "max_iterations", 90) + _cprint( + f"\n{_DIM}⚠ Iteration budget reached " + f"({_api_calls}/{_max_iter}) — " + f"response may be incomplete{_RST}" + ) + + # Speak response aloud if voice TTS is enabled + # Skip batch TTS when streaming TTS already handled it + if self._voice_tts and response and not use_streaming_tts: + threading.Thread( + target=self._voice_speak_response, + args=(response,), + daemon=True, + ).start() + + + # Re-queue the interrupt message (and any that arrived while we were + # processing the first) as the next prompt for process_loop. + # Only reached when busy_input_mode == "interrupt" (the default). + # In "queue" mode Enter routes directly to _pending_input so this + # block is never hit. + if pending_message and hasattr(self, '_pending_input'): + all_parts = [pending_message] + while not self._interrupt_queue.empty(): + try: + extra = self._interrupt_queue.get_nowait() + if extra: + all_parts.append(extra) + except queue.Empty: + break + combined = "\n".join(all_parts) + n = len(all_parts) + preview = combined[:50] + ("..." if len(combined) > 50 else "") + if n > 1: + print(f"\n⚡ Sending {n} messages after interrupt: '{preview}'") + else: + print(f"\n⚡ Sending after interrupt: '{preview}'") + self._pending_input.put(combined) + + return response + + except Exception as e: + print(f"Error: {e}") + return None + finally: + # Ensure streaming TTS resources are cleaned up even on error. + # Normal path sends the sentinel at line ~3568; this is a safety + # net for exception paths that skip it. Duplicate sentinels are + # harmless — stream_tts_to_speaker exits on the first None. + if text_queue is not None: + try: + text_queue.put_nowait(None) + except Exception: + pass + if stop_event is not None: + stop_event.set() + if tts_thread is not None and tts_thread.is_alive(): + tts_thread.join(timeout=5) + + def _print_exit_summary(self): + """Print session resume info on exit, similar to Claude Code.""" + print() + msg_count = len(self.conversation_history) + if msg_count > 0: + user_msgs = len([m for m in self.conversation_history if m.get("role") == "user"]) + tool_calls = len([m for m in self.conversation_history if m.get("role") == "tool" or m.get("tool_calls")]) + elapsed = datetime.now() - self.session_start + hours, remainder = divmod(int(elapsed.total_seconds()), 3600) + minutes, seconds = divmod(remainder, 60) + if hours > 0: + duration_str = f"{hours}h {minutes}m {seconds}s" + elif minutes > 0: + duration_str = f"{minutes}m {seconds}s" + else: + duration_str = f"{seconds}s" + + # Look up session title for resume-by-name hint + session_title = None + if self._session_db: + try: + session_title = self._session_db.get_session_title(self.session_id) + except Exception: + pass + + print("Resume this session with:") + print(f" hermes --resume {self.session_id}") + if session_title: + print(f" hermes -c \"{session_title}\"") + print() + print(f"Session: {self.session_id}") + if session_title: + print(f"Title: {session_title}") + print(f"Duration: {duration_str}") + print(f"Messages: {msg_count} ({user_msgs} user, {tool_calls} tool calls)") + else: + try: + from hermes_cli.skin_engine import get_active_goodbye + goodbye = get_active_goodbye("Goodbye! ⚕") + except Exception: + goodbye = "Goodbye! ⚕" + print(goodbye) + + def _get_tui_prompt_symbols(self) -> tuple[str, str]: + """Return ``(normal_prompt, state_suffix)`` for the active skin. + + ``normal_prompt`` is the full ``branding.prompt_symbol``. + ``state_suffix`` is what special states (sudo/secret/approval/agent) + should render after their leading icon. + + When a profile is active (not "default"), the profile name is + prepended to the prompt symbol: ``coder ❯`` instead of ``❯``. + """ + try: + from hermes_cli.skin_engine import get_active_prompt_symbol + symbol = get_active_prompt_symbol("❯ ") + except Exception: + symbol = "❯ " + + symbol = (symbol or "❯ ").rstrip() + " " + + # Prepend profile name when not default + try: + from hermes_cli.profiles import get_active_profile_name + profile = get_active_profile_name() + if profile not in ("default", "custom"): + symbol = f"{profile} {symbol}" + except Exception: + pass + stripped = symbol.rstrip() + if not stripped: + return "❯ ", "❯ " + + parts = stripped.split() + candidate = parts[-1] if parts else "" + arrow_chars = ("❯", ">", "$", "#", "›", "»", "→") + if any(ch in candidate for ch in arrow_chars): + return symbol, candidate.rstrip() + " " + + # Icon-only custom prompts should still remain visible in special states. + return symbol, symbol + + def _audio_level_bar(self) -> str: + """Return a visual audio level indicator based on current RMS.""" + _LEVEL_BARS = " ▁▂▃▄▅▆▇" + rec = getattr(self, "_voice_recorder", None) + if rec is None: + return "" + rms = rec.current_rms + # Normalize RMS (0-32767) to 0-7 index, with log-ish scaling + # Typical speech RMS is 500-5000, we cap display at ~8000 + level = min(rms, 8000) * 7 // 8000 + return _LEVEL_BARS[level] + + def _get_tui_prompt_fragments(self): + """Return the prompt_toolkit fragments for the current interactive state.""" + symbol, state_suffix = self._get_tui_prompt_symbols() + compact = self._use_minimal_tui_chrome(width=self._get_tui_terminal_width()) + + def _state_fragment(style: str, icon: str, extra: str = ""): + if compact: + text = icon + if extra: + text = f"{text} {extra.strip()}".rstrip() + return [(style, text + " ")] + if extra: + return [(style, f"{icon} {extra} {state_suffix}")] + return [(style, f"{icon} {state_suffix}")] + + if self._voice_recording: + bar = self._audio_level_bar() + return _state_fragment("class:voice-recording", "●", bar) + if self._voice_processing: + return _state_fragment("class:voice-processing", "◉") + if self._sudo_state: + return _state_fragment("class:sudo-prompt", "🔐") + if self._secret_state: + return _state_fragment("class:sudo-prompt", "🔑") + if self._approval_state: + return _state_fragment("class:prompt-working", "⚠") + if self._clarify_freetext: + return _state_fragment("class:clarify-selected", "✎") + if self._clarify_state: + return _state_fragment("class:prompt-working", "?") + if self._command_running: + return _state_fragment("class:prompt-working", self._command_spinner_frame()) + if self._agent_running: + return _state_fragment("class:prompt-working", "⚕") + if self._voice_mode: + return _state_fragment("class:voice-prompt", "🎤") + return [("class:prompt", symbol)] + + def _get_tui_prompt_text(self) -> str: + """Return the visible prompt text for width calculations.""" + return "".join(text for _, text in self._get_tui_prompt_fragments()) + + def _build_tui_style_dict(self) -> dict[str, str]: + """Layer the active skin's prompt_toolkit colors over the base TUI style.""" + style_dict = dict(getattr(self, "_tui_style_base", {}) or {}) + try: + from hermes_cli.skin_engine import get_prompt_toolkit_style_overrides + style_dict.update(get_prompt_toolkit_style_overrides()) + except Exception: + pass + return style_dict + + def _apply_tui_skin_style(self) -> bool: + """Refresh prompt_toolkit styling for a running interactive TUI.""" + if not getattr(self, "_app", None) or not getattr(self, "_tui_style_base", None): + return False + self._app.style = PTStyle.from_dict(self._build_tui_style_dict()) + self._invalidate(min_interval=0.0) + return True + + # --- Protected TUI extension hooks for wrapper CLIs --- + + def _get_extra_tui_widgets(self) -> list: + """Return extra prompt_toolkit widgets to insert into the TUI layout. + + Wrapper CLIs can override this to inject widgets (e.g. a mini-player, + overlay menu) into the layout without overriding ``run()``. Widgets + are inserted between the spacer and the status bar. + """ + return [] + + def _register_extra_tui_keybindings(self, kb, *, input_area) -> None: + """Register extra keybindings on the TUI ``KeyBindings`` object. + + Wrapper CLIs can override this to add keybindings (e.g. transport + controls, modal shortcuts) without overriding ``run()``. + + Parameters + ---------- + kb : KeyBindings + The active keybinding registry for the prompt_toolkit application. + input_area : TextArea + The main input widget, for wrappers that need to inspect or + manipulate user input from a keybinding handler. + """ + + def _build_tui_layout_children( + self, + *, + sudo_widget, + secret_widget, + approval_widget, + clarify_widget, + model_picker_widget=None, + spinner_widget=None, + spacer, + status_bar, + input_rule_top, + image_bar, + input_area, + input_rule_bot, + voice_status_bar, + completions_menu, + ) -> list: + """Assemble the ordered list of children for the root ``HSplit``. + + Wrapper CLIs typically override ``_get_extra_tui_widgets`` instead of + this method. Override this only when you need full control over widget + ordering. + """ + return [ + item for item in [ + Window(height=0), + sudo_widget, + secret_widget, + approval_widget, + clarify_widget, + model_picker_widget, + spinner_widget, + spacer, + *self._get_extra_tui_widgets(), + status_bar, + input_rule_top, + image_bar, + input_area, + input_rule_bot, + voice_status_bar, + completions_menu, + ] if item is not None + ] + + def run(self): + """Run the interactive CLI loop with persistent input at bottom.""" + # Push the entire TUI to the bottom of the terminal so the banner, + # responses, and prompt all appear pinned to the bottom — empty + # space stays above, not below. This prints enough blank lines to + # scroll the cursor to the last row before any content is rendered. + try: + _term_lines = shutil.get_terminal_size().lines + if _term_lines > 2: + print("\n" * (_term_lines - 1), end="", flush=True) + except Exception: + pass + + self.show_banner() + + # One-line Honcho session indicator (TTY-only, not captured by agent). + # Only show when the user explicitly configured Honcho for Hermes + # (not auto-enabled from a stray HONCHO_API_KEY env var). + # If resuming a session, load history and display it immediately + # so the user has context before typing their first message. + if self._resumed: + if self._preload_resumed_session(): + self._display_resumed_history() + + try: + from hermes_cli.skin_engine import get_active_skin + _welcome_skin = get_active_skin() + _welcome_text = _welcome_skin.get_branding("welcome", "Welcome to Hermes Agent! Type your message or /help for commands.") + _welcome_color = _welcome_skin.get_color("banner_text", "#FFF8DC") + except Exception: + _welcome_text = "Welcome to Hermes Agent! Type your message or /help for commands." + _welcome_color = "#FFF8DC" + self.console.print(f"[{_welcome_color}]{_welcome_text}[/]") + # Show a random tip to help users discover features + try: + from hermes_cli.tips import get_random_tip + _tip = get_random_tip() + try: + _tip_color = _welcome_skin.get_color("banner_dim", "#B8860B") + except Exception: + _tip_color = "#B8860B" + self.console.print(f"[dim {_tip_color}]✦ Tip: {_tip}[/]") + except Exception: + pass # Tips are non-critical — never break startup + if self.preloaded_skills and not self._startup_skills_line_shown: + skills_label = ", ".join(self.preloaded_skills) + self.console.print( + f"[bold {_accent_hex()}]Activated skills:[/] {skills_label}" + ) + self._startup_skills_line_shown = True + self.console.print() + + # State for async operation + self._agent_running = False + self._pending_input = queue.Queue() # For normal input (commands + new queries) + self._interrupt_queue = queue.Queue() # For messages typed while agent is running + self._should_exit = False + self._last_ctrl_c_time = 0 # Track double Ctrl+C for force exit + + # Give plugin manager a CLI reference so plugins can inject messages + from hermes_cli.plugins import get_plugin_manager + get_plugin_manager()._cli_ref = self + + # Config file watcher — detect mcp_servers changes and auto-reload + from hermes_cli.config import get_config_path as _get_config_path + _cfg_path = _get_config_path() + self._config_mtime: float = _cfg_path.stat().st_mtime if _cfg_path.exists() else 0.0 + self._config_mcp_servers: dict = self.config.get("mcp_servers") or {} + self._last_config_check: float = 0.0 # monotonic time of last check + + # Clarify tool state: interactive question/answer with the user. + # When the agent calls the clarify tool, _clarify_state is set and + # the prompt_toolkit UI switches to a selection mode. + self._clarify_state = None # dict with question, choices, selected, response_queue + self._clarify_freetext = False # True when user chose "Other" and is typing + self._clarify_deadline = 0 # monotonic timestamp when the clarify times out + + # Sudo password prompt state (similar mechanism to clarify) + self._sudo_state = None # dict with response_queue when active + self._sudo_deadline = 0 + self._modal_input_snapshot = None + + # Dangerous command approval state (similar mechanism to clarify) + self._approval_state = None # dict with command, description, choices, selected, response_queue + self._approval_deadline = 0 + self._approval_lock = threading.Lock() # serialize concurrent approval prompts (delegation race fix) + + # Slash command loading state + self._command_running = False + self._command_status = "" + + # Secure secret capture state for skill setup + self._secret_state = None # dict with var_name, prompt, metadata, response_queue + self._secret_deadline = 0 + + # Clipboard image attachments (paste images into the CLI) + self._attached_images: list[Path] = [] + self._image_counter = 0 + + # Voice mode state (protected by _voice_lock for cross-thread access) + self._voice_lock = threading.Lock() + self._voice_mode = False # Whether voice mode is enabled + self._voice_tts = False # Whether TTS output is enabled + self._voice_recorder = None # AudioRecorder instance (lazy init) + self._voice_recording = False # Whether currently recording + self._voice_processing = False # Whether STT is in progress + self._voice_continuous = False # Whether to auto-restart after agent responds + self._voice_tts_done = threading.Event() # Signals TTS playback finished + self._voice_tts_done.set() # Initially "done" (no TTS pending) + + # Register callbacks so terminal_tool prompts route through our UI + set_sudo_password_callback(self._sudo_password_callback) + set_approval_callback(self._approval_callback) + set_secret_capture_callback(self._secret_capture_callback) + + # Ensure tirith security scanner is available (downloads if needed). + # Warn the user if tirith is enabled in config but not available, + # so they know command security scanning is degraded. + try: + from tools.tirith_security import ensure_installed + tirith_path = ensure_installed(log_failures=False) + if tirith_path is None: + security_cfg = self.config.get("security", {}) or {} + tirith_enabled = security_cfg.get("tirith_enabled", True) + if tirith_enabled: + _cprint(f" {_DIM}⚠ tirith security scanner enabled but not available " + f"— command scanning will use pattern matching only{_RST}") + except Exception: + pass # Non-fatal — fail-open at scan time if unavailable + + # Key bindings for the input area + kb = KeyBindings() + + @kb.add('enter') + def handle_enter(event): + """Handle Enter key - submit input. + + Routes to the correct queue based on active UI state: + - Sudo password prompt: password goes to sudo response queue + - Approval selection: selected choice goes to approval response queue + - Clarify freetext mode: answer goes to the clarify response queue + - Clarify choice mode: selected choice goes to the clarify response queue + - Agent running: goes to _interrupt_queue (chat() monitors this) + - Agent idle: goes to _pending_input (process_loop monitors this) + Commands (starting with /) always go to _pending_input so they're + handled as commands, not sent as interrupt text to the agent. + """ + # --- Sudo password prompt: submit the typed password --- + if self._sudo_state: + text = event.app.current_buffer.text + self._sudo_state["response_queue"].put(text) + self._sudo_state = None + event.app.invalidate() + return + + # --- Secret prompt: submit the typed secret --- + if self._secret_state: + text = event.app.current_buffer.text + self._submit_secret_response(text) + event.app.current_buffer.reset() + event.app.invalidate() + return + + # --- Approval selection: confirm the highlighted choice --- + if self._approval_state: + self._handle_approval_selection() + event.app.invalidate() + return + + # --- /model picker modal --- + if self._model_picker_state: + self._handle_model_picker_selection() + event.app.invalidate() + return + + # --- Clarify freetext mode: user typed their own answer --- + if self._clarify_freetext and self._clarify_state: + text = event.app.current_buffer.text.strip() + if text: + self._clarify_state["response_queue"].put(text) + self._clarify_state = None + self._clarify_freetext = False + event.app.current_buffer.reset() + event.app.invalidate() + return + + # --- Clarify choice mode: confirm the highlighted selection --- + if self._clarify_state and not self._clarify_freetext: + state = self._clarify_state + selected = state["selected"] + choices = state.get("choices") or [] + if selected < len(choices): + state["response_queue"].put(choices[selected]) + self._clarify_state = None + event.app.invalidate() + else: + # "Other" selected → switch to freetext + self._clarify_freetext = True + event.app.invalidate() + return + + # --- Normal input routing --- + text = event.app.current_buffer.text.strip() + has_images = bool(self._attached_images) + if text or has_images: + # Handle /model directly on the UI thread so interactive pickers + # can safely use prompt_toolkit terminal handoff helpers. + if self._should_handle_model_command_inline(text, has_images=has_images): + if not self.process_command(text): + self._should_exit = True + if event.app.is_running: + event.app.exit() + event.app.current_buffer.reset(append_to_history=True) + return + + # Snapshot and clear attached images + images = list(self._attached_images) + self._attached_images.clear() + event.app.invalidate() + # Bundle text + images as a tuple when images are present + payload = (text, images) if images else text + if self._agent_running and not (text and _looks_like_slash_command(text)): + if self.busy_input_mode == "queue": + # Queue for the next turn instead of interrupting + self._pending_input.put(payload) + preview = text if text else f"[{len(images)} image{'s' if len(images) != 1 else ''} attached]" + _cprint(f" Queued for the next turn: {preview[:80]}{'...' if len(preview) > 80 else ''}") + else: + self._interrupt_queue.put(payload) + # Debug: log to file when message enters interrupt queue + try: + _dbg = _hermes_home / "interrupt_debug.log" + with open(_dbg, "a") as _f: + import time as _t + _f.write(f"{_t.strftime('%H:%M:%S')} ENTER: queued interrupt msg={str(payload)[:60]!r}, " + f"agent_running={self._agent_running}\n") + except Exception: + pass + else: + self._pending_input.put(payload) + event.app.current_buffer.reset(append_to_history=True) + + @kb.add('escape', 'enter') + def handle_alt_enter(event): + """Alt+Enter inserts a newline for multi-line input.""" + event.current_buffer.insert_text('\n') + + @kb.add('c-j') + def handle_ctrl_enter(event): + """Ctrl+Enter (c-j) inserts a newline. Most terminals send c-j for Ctrl+Enter.""" + event.current_buffer.insert_text('\n') + + @kb.add('tab', eager=True) + def handle_tab(event): + """Tab: accept completion, auto-suggestion, or start completions. + + Priority: + 1. Completion menu open → accept selected completion + 2. Ghost text suggestion available → accept auto-suggestion + 3. Otherwise → start completion menu + + After accepting a provider like 'anthropic:', the completion menu + closes and complete_while_typing doesn't fire (no keystroke). + This binding re-triggers completions so stage-2 models appear + immediately. + """ + buf = event.current_buffer + if buf.complete_state: + # Completion menu is open — accept the selection + completion = buf.complete_state.current_completion + if completion is None: + # Menu open but nothing selected — select first then grab it + buf.go_to_completion(0) + completion = buf.complete_state and buf.complete_state.current_completion + if completion is None: + return + # Accept the selected completion + buf.apply_completion(completion) + elif buf.suggestion and buf.suggestion.text: + # No completion menu, but there's a ghost text auto-suggestion — accept it + buf.insert_text(buf.suggestion.text) + else: + # No menu and no suggestion — start completions from scratch + buf.start_completion() + + # --- Clarify tool: arrow-key navigation for multiple-choice questions --- + + @kb.add('up', filter=Condition(lambda: bool(self._clarify_state) and not self._clarify_freetext)) + def clarify_up(event): + """Move selection up in clarify choices.""" + if self._clarify_state: + self._clarify_state["selected"] = max(0, self._clarify_state["selected"] - 1) + event.app.invalidate() + + @kb.add('down', filter=Condition(lambda: bool(self._clarify_state) and not self._clarify_freetext)) + def clarify_down(event): + """Move selection down in clarify choices.""" + if self._clarify_state: + choices = self._clarify_state.get("choices") or [] + max_idx = len(choices) # last index is the "Other" option + self._clarify_state["selected"] = min(max_idx, self._clarify_state["selected"] + 1) + event.app.invalidate() + + # --- Dangerous command approval: arrow-key navigation --- + + @kb.add('up', filter=Condition(lambda: bool(self._approval_state))) + def approval_up(event): + if self._approval_state: + self._approval_state["selected"] = max(0, self._approval_state["selected"] - 1) + event.app.invalidate() + + @kb.add('down', filter=Condition(lambda: bool(self._approval_state))) + def approval_down(event): + if self._approval_state: + max_idx = len(self._approval_state["choices"]) - 1 + self._approval_state["selected"] = min(max_idx, self._approval_state["selected"] + 1) + event.app.invalidate() + + # --- /model picker: arrow-key navigation --- + @kb.add('up', filter=Condition(lambda: bool(self._model_picker_state))) + def model_picker_up(event): + if self._model_picker_state: + self._model_picker_state["selected"] = max(0, self._model_picker_state.get("selected", 0) - 1) + event.app.invalidate() + + @kb.add('down', filter=Condition(lambda: bool(self._model_picker_state))) + def model_picker_down(event): + state = self._model_picker_state + if not state: + return + if state.get("stage") == "provider": + max_idx = len(state.get("providers") or []) + else: + max_idx = len(state.get("model_list") or []) + 1 + state["selected"] = min(max_idx, state.get("selected", 0) + 1) + event.app.invalidate() + + # --- History navigation: up/down browse history in normal input mode --- + # The TextArea is multiline, so by default up/down only move the cursor. + # Buffer.auto_up/auto_down handle both: cursor movement when multi-line, + # history browsing when on the first/last line (or single-line input). + _normal_input = Condition( + lambda: not self._clarify_state and not self._approval_state and not self._sudo_state and not self._secret_state and not self._model_picker_state + ) + + @kb.add('up', filter=_normal_input) + def history_up(event): + """Up arrow: browse history when on first line, else move cursor up.""" + event.app.current_buffer.auto_up(count=event.arg) + + @kb.add('down', filter=_normal_input) + def history_down(event): + """Down arrow: browse history when on last line, else move cursor down.""" + event.app.current_buffer.auto_down(count=event.arg) + + @kb.add('c-c') + def handle_ctrl_c(event): + """Handle Ctrl+C - cancel interactive prompts, interrupt agent, or exit. + + Priority: + 0. Cancel active voice recording + 1. Cancel active sudo/approval/clarify prompt + 2. Interrupt the running agent (first press) + 3. Force exit (second press within 2s, or when idle) + """ + import time as _time + now = _time.time() + + # Cancel active voice recording. + # Run cancel() in a background thread to prevent blocking the + # event loop if AudioRecorder._lock or CoreAudio takes time. + _should_cancel_voice = False + _recorder_ref = None + with cli_ref._voice_lock: + if cli_ref._voice_recording and cli_ref._voice_recorder: + _recorder_ref = cli_ref._voice_recorder + cli_ref._voice_recording = False + cli_ref._voice_continuous = False + _should_cancel_voice = True + if _should_cancel_voice: + _cprint(f"\n{_DIM}Recording cancelled.{_RST}") + threading.Thread( + target=_recorder_ref.cancel, daemon=True + ).start() + event.app.invalidate() + return + + # Cancel sudo prompt + if self._sudo_state: + self._sudo_state["response_queue"].put("") + self._sudo_state = None + event.app.invalidate() + return + + # Cancel secret prompt + if self._secret_state: + self._cancel_secret_capture() + event.app.current_buffer.reset() + event.app.invalidate() + return + + # Cancel approval prompt (deny) + if self._approval_state: + self._approval_state["response_queue"].put("deny") + self._approval_state = None + event.app.invalidate() + return + + # Cancel /model picker + if self._model_picker_state: + self._close_model_picker() + event.app.current_buffer.reset() + event.app.invalidate() + return + + # Cancel clarify prompt + if self._clarify_state: + self._clarify_state["response_queue"].put( + "The user cancelled. Use your best judgement to proceed." + ) + self._clarify_state = None + self._clarify_freetext = False + event.app.current_buffer.reset() + event.app.invalidate() + return + + if self._agent_running and self.agent: + if now - self._last_ctrl_c_time < 2.0: + print("\n⚡ Force exiting...") + self._should_exit = True + event.app.exit() + return + + self._last_ctrl_c_time = now + print("\n⚡ Interrupting agent... (press Ctrl+C again to force exit)") + self.agent.interrupt() + else: + # If there's text or images, clear them (like bash). + # If everything is already empty, exit. + if event.app.current_buffer.text or self._attached_images: + event.app.current_buffer.reset() + self._attached_images.clear() + event.app.invalidate() + else: + self._should_exit = True + event.app.exit() + + @kb.add('c-d') + def handle_ctrl_d(event): + """Handle Ctrl+D - exit.""" + self._should_exit = True + event.app.exit() + + @kb.add('c-z') + def handle_ctrl_z(event): + """Handle Ctrl+Z - suspend process to background (Unix only).""" + import sys + if sys.platform == 'win32': + _cprint(f"\n{_DIM}Suspend (Ctrl+Z) is not supported on Windows.{_RST}") + event.app.invalidate() + return + import os, signal as _sig + from prompt_toolkit.application import run_in_terminal + from hermes_cli.skin_engine import get_active_skin + agent_name = get_active_skin().get_branding("agent_name", "Hermes Agent") + msg = f"\n{agent_name} has been suspended. Run `fg` to bring {agent_name} back." + def _suspend(): + os.write(1, msg.encode()) + os.kill(0, _sig.SIGTSTP) + run_in_terminal(_suspend) + + # Voice push-to-talk key: configurable via config.yaml (voice.record_key) + # Default: Ctrl+B (avoids conflict with Ctrl+R readline reverse-search) + # Config uses "ctrl+b" format; prompt_toolkit expects "c-b" format. + try: + from hermes_cli.config import load_config + _raw_key = load_config().get("voice", {}).get("record_key", "ctrl+b") + _voice_key = _raw_key.lower().replace("ctrl+", "c-").replace("alt+", "a-") + except Exception: + _voice_key = "c-b" + + @kb.add(_voice_key) + def handle_voice_record(event): + """Toggle voice recording when voice mode is active. + + IMPORTANT: This handler runs in prompt_toolkit's event-loop thread. + Any blocking call here (locks, sd.wait, disk I/O) freezes the + entire UI. All heavy work is dispatched to daemon threads. + """ + if not cli_ref._voice_mode: + return + # Always allow STOPPING a recording (even when agent is running) + if cli_ref._voice_recording: + # Manual stop via push-to-talk key: stop continuous mode + with cli_ref._voice_lock: + cli_ref._voice_continuous = False + # Flag clearing is handled atomically inside _voice_stop_and_transcribe + event.app.invalidate() + threading.Thread( + target=cli_ref._voice_stop_and_transcribe, + daemon=True, + ).start() + else: + # Guard: don't START recording during agent run or interactive prompts + if cli_ref._agent_running: + return + if cli_ref._clarify_state or cli_ref._sudo_state or cli_ref._approval_state: + return + # Guard: don't start while a previous stop/transcribe cycle is + # still running — recorder.stop() holds AudioRecorder._lock and + # start() would block the event-loop thread waiting for it. + if cli_ref._voice_processing: + return + + # Interrupt TTS if playing, so user can start talking. + # stop_playback() is fast (just terminates a subprocess). + if not cli_ref._voice_tts_done.is_set(): + try: + from tools.voice_mode import stop_playback + stop_playback() + cli_ref._voice_tts_done.set() + except Exception: + pass + + with cli_ref._voice_lock: + cli_ref._voice_continuous = True + + # Dispatch to a daemon thread so play_beep(sd.wait), + # AudioRecorder.start(lock acquire), and config I/O + # never block the prompt_toolkit event loop. + def _start_recording(): + try: + cli_ref._voice_start_recording() + if hasattr(cli_ref, '_app') and cli_ref._app: + cli_ref._app.invalidate() + except Exception as e: + _cprint(f"\n{_DIM}Voice recording failed: {e}{_RST}") + + threading.Thread(target=_start_recording, daemon=True).start() + event.app.invalidate() + from prompt_toolkit.keys import Keys + + @kb.add(Keys.BracketedPaste, eager=True) + def handle_paste(event): + """Handle terminal paste — detect clipboard images. + + When the terminal supports bracketed paste, Ctrl+V / Cmd+V + triggers this with the pasted text. We only auto-attach a + clipboard image for image-only/empty paste gestures so text + pastes and dictation do not accidentally attach stale images. + + Large pastes (5+ lines) are collapsed to a file reference + placeholder while preserving any existing user text in the + buffer. + """ + pasted_text = event.data or "" + # Normalise line endings — Windows \r\n and old Mac \r both become \n + # so the 5-line collapse threshold and display are consistent. + pasted_text = pasted_text.replace('\r\n', '\n').replace('\r', '\n') + if _should_auto_attach_clipboard_image_on_paste(pasted_text) and self._try_attach_clipboard_image(): + event.app.invalidate() + if pasted_text: + # Sanitize surrogate characters (e.g. from Word/Google Docs paste) before writing + from run_agent import _sanitize_surrogates + pasted_text = _sanitize_surrogates(pasted_text) + line_count = pasted_text.count('\n') + buf = event.current_buffer + if line_count >= 5 and not buf.text.strip().startswith('/'): + _paste_counter[0] += 1 + paste_dir = _hermes_home / "pastes" + paste_dir.mkdir(parents=True, exist_ok=True) + paste_file = paste_dir / f"paste_{_paste_counter[0]}_{datetime.now().strftime('%H%M%S')}.txt" + paste_file.write_text(pasted_text, encoding="utf-8") + placeholder = f"[Pasted text #{_paste_counter[0]}: {line_count + 1} lines \u2192 {paste_file}]" + prefix = "" + if buf.cursor_position > 0 and buf.text[buf.cursor_position - 1] != '\n': + prefix = "\n" + _paste_just_collapsed[0] = True + buf.insert_text(prefix + placeholder) + else: + buf.insert_text(pasted_text) + + @kb.add('c-v') + def handle_ctrl_v(event): + """Fallback image paste for terminals without bracketed paste. + + On Linux terminals (GNOME Terminal, Konsole, etc.), Ctrl+V + sends raw byte 0x16 instead of triggering a paste. This + binding catches that and checks the clipboard for images. + On terminals that DO intercept Ctrl+V for paste (macOS + Terminal, iTerm2, VSCode, Windows Terminal), the bracketed + paste handler fires instead and this binding never triggers. + """ + if self._try_attach_clipboard_image(): + event.app.invalidate() + + @kb.add('escape', 'v') + def handle_alt_v(event): + """Alt+V — paste image from clipboard. + + Alt key combos pass through all terminal emulators (sent as + ESC + key), unlike Ctrl+V which terminals intercept for text + paste. This is the reliable way to attach clipboard images + on WSL2, VSCode, and any terminal over SSH where Ctrl+V + can't reach the application for image-only clipboard. + """ + if self._try_attach_clipboard_image(): + event.app.invalidate() + else: + # No image found — show a hint + pass # silent when no image (avoid noise on accidental press) + + # Dynamic prompt: shows Hermes symbol when agent is working, + # or answer prompt when clarify freetext mode is active. + cli_ref = self + + def get_prompt(): + return cli_ref._get_tui_prompt_fragments() + + # Create the input area with multiline (shift+enter), autocomplete, and paste handling + from prompt_toolkit.auto_suggest import AutoSuggestFromHistory + + + _completer = SlashCommandCompleter( + skill_commands_provider=lambda: _skill_commands, + command_filter=cli_ref._command_available, + ) + input_area = TextArea( + height=Dimension(min=1, max=8, preferred=1), + prompt=get_prompt, + style='class:input-area', + multiline=True, + wrap_lines=True, + read_only=Condition(lambda: bool(cli_ref._command_running)), + history=FileHistory(str(self._history_file)), + completer=_completer, + complete_while_typing=True, + auto_suggest=SlashCommandAutoSuggest( + history_suggest=AutoSuggestFromHistory(), + completer=_completer, + ), + ) + + # Dynamic height: accounts for both explicit newlines AND visual + # wrapping of long lines so the input area always fits its content. + def _input_height(): + try: + from prompt_toolkit.application import get_app + from prompt_toolkit.utils import get_cwidth + + doc = input_area.buffer.document + prompt_width = max(2, get_cwidth(self._get_tui_prompt_text())) + try: + available_width = get_app().output.get_size().columns - prompt_width + except Exception: + available_width = shutil.get_terminal_size((80, 24)).columns - prompt_width + if available_width < 10: + available_width = 40 + visual_lines = 0 + for line in doc.lines: + # Each logical line takes at least 1 visual row; long lines wrap. + # Use prompt_toolkit's cell width so CJK wide characters count as 2. + line_width = get_cwidth(line) + if line_width <= 0: + visual_lines += 1 + else: + visual_lines += max(1, -(-line_width // available_width)) # ceil division + return min(max(visual_lines, 1), 8) + except Exception: + return 1 + + input_area.window.height = _input_height + + # Paste collapsing: detect large pastes and save to temp file + _paste_counter = [0] + _prev_text_len = [0] + _prev_newline_count = [0] + _paste_just_collapsed = [False] + + def _on_text_changed(buf): + """Detect large pastes and collapse them to a file reference. + + When bracketed paste is available, handle_paste collapses + large pastes directly. This handler is a fallback for + terminals without bracketed paste support. + + Two heuristics (either triggers collapse): + 1. Many characters added at once (chars_added > 1) — works + when the terminal delivers the paste in one event-loop tick. + 2. Newline count jumped by 4+ in a single text-change event — + catches terminals that feed characters individually but + still batch newlines. Alt+Enter only adds 1 newline per + event so it never triggers this. + """ + text = buf.text + chars_added = len(text) - _prev_text_len[0] + _prev_text_len[0] = len(text) + if _paste_just_collapsed[0]: + _paste_just_collapsed[0] = False + _prev_newline_count[0] = text.count('\n') + return + line_count = text.count('\n') + newlines_added = line_count - _prev_newline_count[0] + _prev_newline_count[0] = line_count + is_paste = chars_added > 1 or newlines_added >= 4 + if line_count >= 5 and is_paste and not text.startswith('/'): + _paste_counter[0] += 1 + # Save to temp file + paste_dir = _hermes_home / "pastes" + paste_dir.mkdir(parents=True, exist_ok=True) + paste_file = paste_dir / f"paste_{_paste_counter[0]}_{datetime.now().strftime('%H%M%S')}.txt" + paste_file.write_text(text, encoding="utf-8") + # Replace buffer with compact reference + _paste_just_collapsed[0] = True + buf.text = f"[Pasted text #{_paste_counter[0]}: {line_count + 1} lines \u2192 {paste_file}]" + buf.cursor_position = len(buf.text) + + input_area.buffer.on_text_changed += _on_text_changed + + # --- Input processors for password masking and inline placeholder --- + + # Mask input with '*' when the sudo password prompt is active + input_area.control.input_processors.append( + ConditionalProcessor( + PasswordProcessor(), + filter=Condition( + lambda: bool(cli_ref._sudo_state) or bool(cli_ref._secret_state) + ), + ) + ) + + class _PlaceholderProcessor(Processor): + """Render grayed-out placeholder text inside the input when empty.""" + def __init__(self, get_text): + self._get_text = get_text + + def apply_transformation(self, ti): + if not ti.document.text and ti.lineno == 0: + text = self._get_text() + if text: + # Append after existing fragments (preserves the ❯ prompt) + return Transformation(fragments=ti.fragments + [('class:placeholder', text)]) + return Transformation(fragments=ti.fragments) + + def _get_placeholder(): + if cli_ref._voice_recording: + return "recording... Ctrl+B to stop, Ctrl+C to cancel" + if cli_ref._voice_processing: + return "transcribing..." + if cli_ref._sudo_state: + return "type password (hidden), Enter to skip" + if cli_ref._secret_state: + return "type secret (hidden), Enter to skip" + if cli_ref._approval_state: + return "" + if cli_ref._clarify_freetext: + return "type your answer here and press Enter" + if cli_ref._clarify_state: + return "" + if cli_ref._command_running: + frame = cli_ref._command_spinner_frame() + status = cli_ref._command_status or "Processing command..." + return f"{frame} {status}" + if cli_ref._agent_running: + return "type a message + Enter to interrupt, Ctrl+C to cancel" + if cli_ref._voice_mode: + return "type or Ctrl+B to record" + return "" + + input_area.control.input_processors.append(_PlaceholderProcessor(_get_placeholder)) + + # Hint line above input: shown only for interactive prompts that need + # extra instructions (sudo countdown, approval navigation, clarify). + # The agent-running interrupt hint is now an inline placeholder above. + def get_hint_text(): + import time as _time + + if cli_ref._sudo_state: + remaining = max(0, int(cli_ref._sudo_deadline - _time.monotonic())) + return [ + ('class:hint', ' password hidden · Enter to skip'), + ('class:clarify-countdown', f' ({remaining}s)'), + ] + + if cli_ref._secret_state: + remaining = max(0, int(cli_ref._secret_deadline - _time.monotonic())) + return [ + ('class:hint', ' secret hidden · Enter to skip'), + ('class:clarify-countdown', f' ({remaining}s)'), + ] + + if cli_ref._approval_state: + remaining = max(0, int(cli_ref._approval_deadline - _time.monotonic())) + return [ + ('class:hint', ' ↑/↓ to select, Enter to confirm'), + ('class:clarify-countdown', f' ({remaining}s)'), + ] + + if cli_ref._clarify_state: + remaining = max(0, int(cli_ref._clarify_deadline - _time.monotonic())) + countdown = f' ({remaining}s)' if cli_ref._clarify_deadline else '' + if cli_ref._clarify_freetext: + return [ + ('class:hint', ' type your answer and press Enter'), + ('class:clarify-countdown', countdown), + ] + return [ + ('class:hint', ' ↑/↓ to select, Enter to confirm'), + ('class:clarify-countdown', countdown), + ] + + if cli_ref._command_running: + frame = cli_ref._command_spinner_frame() + return [ + ('class:hint', f' {frame} command in progress · input temporarily disabled'), + ] + + return [] + + def get_hint_height(): + if cli_ref._sudo_state or cli_ref._secret_state or cli_ref._approval_state or cli_ref._clarify_state or cli_ref._command_running: + return 1 + # Keep a spacer while the agent runs on roomy terminals, but reclaim + # the row on narrow/mobile screens where every line matters. + return cli_ref._agent_spacer_height() + + def get_spinner_text(): + txt = cli_ref._spinner_text + if not txt: + return [] + # Append live elapsed timer when a tool is running + t0 = cli_ref._tool_start_time + if t0 > 0: + import time as _time + elapsed = _time.monotonic() - t0 + if elapsed >= 60: + _m, _s = int(elapsed // 60), int(elapsed % 60) + elapsed_str = f"{_m}m {_s}s" + else: + elapsed_str = f"{elapsed:.1f}s" + return [('class:hint', f' {txt} ({elapsed_str})')] + return [('class:hint', f' {txt}')] + + def get_spinner_height(): + return cli_ref._spinner_widget_height() + + spinner_widget = Window( + content=FormattedTextControl(get_spinner_text), + height=get_spinner_height, + ) + + spacer = Window( + content=FormattedTextControl(get_hint_text), + height=get_hint_height, + ) + + # --- Clarify tool: dynamic display widget for questions + choices --- + + def _panel_box_width(title: str, content_lines: list[str], min_width: int = 46, max_width: int = 76) -> int: + """Choose a stable panel width wide enough for the title and content.""" + term_cols = shutil.get_terminal_size((100, 20)).columns + longest = max([len(title)] + [len(line) for line in content_lines] + [min_width - 4]) + inner = min(max(longest + 4, min_width - 2), max_width - 2, max(24, term_cols - 6)) + return inner + 2 # account for the single leading/trailing spaces inside borders + + def _wrap_panel_text(text: str, width: int, subsequent_indent: str = "") -> list[str]: + wrapped = textwrap.wrap( + text, + width=max(8, width), + break_long_words=False, + break_on_hyphens=False, + subsequent_indent=subsequent_indent, + ) + return wrapped or [""] + + def _append_panel_line(lines, border_style: str, content_style: str, text: str, box_width: int) -> None: + inner_width = max(0, box_width - 2) + lines.append((border_style, "│ ")) + lines.append((content_style, text.ljust(inner_width))) + lines.append((border_style, " │\n")) + + def _append_blank_panel_line(lines, border_style: str, box_width: int) -> None: + lines.append((border_style, "│" + (" " * box_width) + "│\n")) + + def _get_clarify_display(): + """Build styled text for the clarify question/choices panel.""" + state = cli_ref._clarify_state + if not state: + return [] + + question = state["question"] + choices = state.get("choices") or [] + selected = state.get("selected", 0) + preview_lines = _wrap_panel_text(question, 60) + for i, choice in enumerate(choices): + prefix = "❯ " if i == selected and not cli_ref._clarify_freetext else " " + preview_lines.extend(_wrap_panel_text(f"{prefix}{choice}", 60, subsequent_indent=" ")) + other_label = ( + "❯ Other (type below)" if cli_ref._clarify_freetext + else "❯ Other (type your answer)" if selected == len(choices) + else " Other (type your answer)" + ) + preview_lines.extend(_wrap_panel_text(other_label, 60, subsequent_indent=" ")) + box_width = _panel_box_width("Hermes needs your input", preview_lines) + inner_text_width = max(8, box_width - 2) + + lines = [] + # Box top border + lines.append(('class:clarify-border', '╭─ ')) + lines.append(('class:clarify-title', 'Hermes needs your input')) + lines.append(('class:clarify-border', ' ' + ('─' * max(0, box_width - len("Hermes needs your input") - 3)) + '╮\n')) + _append_blank_panel_line(lines, 'class:clarify-border', box_width) + + # Question text + for wrapped in _wrap_panel_text(question, inner_text_width): + _append_panel_line(lines, 'class:clarify-border', 'class:clarify-question', wrapped, box_width) + _append_blank_panel_line(lines, 'class:clarify-border', box_width) + + if cli_ref._clarify_freetext and not choices: + guidance = "Type your answer in the prompt below, then press Enter." + for wrapped in _wrap_panel_text(guidance, inner_text_width): + _append_panel_line(lines, 'class:clarify-border', 'class:clarify-choice', wrapped, box_width) + _append_blank_panel_line(lines, 'class:clarify-border', box_width) + + if choices: + # Multiple-choice mode: show selectable options + for i, choice in enumerate(choices): + style = 'class:clarify-selected' if i == selected and not cli_ref._clarify_freetext else 'class:clarify-choice' + prefix = '❯ ' if i == selected and not cli_ref._clarify_freetext else ' ' + wrapped_lines = _wrap_panel_text(f"{prefix}{choice}", inner_text_width, subsequent_indent=" ") + for wrapped in wrapped_lines: + _append_panel_line(lines, 'class:clarify-border', style, wrapped, box_width) + + # "Other" option (5th line, only shown when choices exist) + other_idx = len(choices) + if selected == other_idx and not cli_ref._clarify_freetext: + other_style = 'class:clarify-selected' + other_label = '❯ Other (type your answer)' + elif cli_ref._clarify_freetext: + other_style = 'class:clarify-active-other' + other_label = '❯ Other (type below)' + else: + other_style = 'class:clarify-choice' + other_label = ' Other (type your answer)' + for wrapped in _wrap_panel_text(other_label, inner_text_width, subsequent_indent=" "): + _append_panel_line(lines, 'class:clarify-border', other_style, wrapped, box_width) + + _append_blank_panel_line(lines, 'class:clarify-border', box_width) + lines.append(('class:clarify-border', '╰' + ('─' * box_width) + '╯\n')) + return lines + + clarify_widget = ConditionalContainer( + Window( + FormattedTextControl(_get_clarify_display), + wrap_lines=True, + ), + filter=Condition(lambda: cli_ref._clarify_state is not None), + ) + + # --- Sudo password: display widget --- + + def _get_sudo_display(): + state = cli_ref._sudo_state + if not state: + return [] + title = '🔐 Sudo Password Required' + body = 'Enter password below (hidden), or press Enter to skip' + box_width = _panel_box_width(title, [body]) + lines = [] + lines.append(('class:sudo-border', '╭─ ')) + lines.append(('class:sudo-title', title)) + lines.append(('class:sudo-border', ' ' + ('─' * max(0, box_width - len(title) - 3)) + '╮\n')) + _append_blank_panel_line(lines, 'class:sudo-border', box_width) + _append_panel_line(lines, 'class:sudo-border', 'class:sudo-text', body, box_width) + _append_blank_panel_line(lines, 'class:sudo-border', box_width) + lines.append(('class:sudo-border', '╰' + ('─' * box_width) + '╯\n')) + return lines + + sudo_widget = ConditionalContainer( + Window( + FormattedTextControl(_get_sudo_display), + wrap_lines=True, + ), + filter=Condition(lambda: cli_ref._sudo_state is not None), + ) + + def _get_secret_display(): + state = cli_ref._secret_state + if not state: + return [] + + title = '🔑 Skill Setup Required' + prompt = state.get("prompt") or f"Enter value for {state.get('var_name', 'secret')}" + metadata = state.get("metadata") or {} + help_text = metadata.get("help") + body = 'Enter secret below (hidden), or press Enter to skip' + content_lines = [prompt, body] + if help_text: + content_lines.insert(1, str(help_text)) + box_width = _panel_box_width(title, content_lines) + lines = [] + lines.append(('class:sudo-border', '╭─ ')) + lines.append(('class:sudo-title', title)) + lines.append(('class:sudo-border', ' ' + ('─' * max(0, box_width - len(title) - 3)) + '╮\n')) + _append_blank_panel_line(lines, 'class:sudo-border', box_width) + _append_panel_line(lines, 'class:sudo-border', 'class:sudo-text', prompt, box_width) + if help_text: + _append_panel_line(lines, 'class:sudo-border', 'class:sudo-text', str(help_text), box_width) + _append_blank_panel_line(lines, 'class:sudo-border', box_width) + _append_panel_line(lines, 'class:sudo-border', 'class:sudo-text', body, box_width) + _append_blank_panel_line(lines, 'class:sudo-border', box_width) + lines.append(('class:sudo-border', '╰' + ('─' * box_width) + '╯\n')) + return lines + + secret_widget = ConditionalContainer( + Window( + FormattedTextControl(_get_secret_display), + wrap_lines=True, + ), + filter=Condition(lambda: cli_ref._secret_state is not None), + ) + + # --- Dangerous command approval: display widget --- + + def _get_approval_display(): + return cli_ref._get_approval_display_fragments() + + approval_widget = ConditionalContainer( + Window( + FormattedTextControl(_get_approval_display), + wrap_lines=True, + ), + filter=Condition(lambda: cli_ref._approval_state is not None), + ) + + # --- /model picker: display widget --- + def _get_model_picker_display(): + state = cli_ref._model_picker_state + if not state: + return [] + stage = state.get("stage", "provider") + if stage == "provider": + title = "⚙ Model Picker — Select Provider" + choices = [] + for p in state.get("providers") or []: + count = p.get("total_models", len(p.get("models", []))) + label = f"{p['name']} ({count} model{'s' if count != 1 else ''})" + if p.get("is_current"): + label += " ← current" + choices.append(label) + choices.append("Cancel") + hint = f"Current: {state.get('current_model', 'unknown')} on {state.get('current_provider', 'unknown')}" + else: + provider_data = state.get("provider_data") or {} + model_list = state.get("model_list") or [] + title = f"⚙ Model Picker — {provider_data.get('name', provider_data.get('slug', 'Provider'))}" + choices = list(model_list) + ["← Back", "Cancel"] + if model_list: + hint = f"Select a model ({len(model_list)} available)" + else: + hint = "No models listed for this provider. Use Back or Cancel." + + box_width = _panel_box_width(title, [hint] + choices, min_width=46, max_width=84) + inner_text_width = max(8, box_width - 6) + lines = [] + lines.append(('class:clarify-border', '╭─ ')) + lines.append(('class:clarify-title', title)) + lines.append(('class:clarify-border', ' ' + ('─' * max(0, box_width - len(title) - 3)) + '╮\n')) + _append_blank_panel_line(lines, 'class:clarify-border', box_width) + _append_panel_line(lines, 'class:clarify-border', 'class:clarify-hint', hint, box_width) + _append_blank_panel_line(lines, 'class:clarify-border', box_width) + selected = state.get("selected", 0) + for idx, choice in enumerate(choices): + style = 'class:clarify-selected' if idx == selected else 'class:clarify-choice' + prefix = '❯ ' if idx == selected else ' ' + for wrapped in _wrap_panel_text(prefix + choice, inner_text_width, subsequent_indent=' '): + _append_panel_line(lines, 'class:clarify-border', style, wrapped, box_width) + _append_blank_panel_line(lines, 'class:clarify-border', box_width) + lines.append(('class:clarify-border', '╰' + ('─' * box_width) + '╯\n')) + return lines + + model_picker_widget = ConditionalContainer( + Window( + FormattedTextControl(_get_model_picker_display), + wrap_lines=True, + ), + filter=Condition(lambda: cli_ref._model_picker_state is not None), + ) + + # Horizontal rules above and below the input. + # On narrow/mobile terminals we keep the top separator for structure but + # hide the bottom one to recover a full row for conversation content. + input_rule_top = Window( + char='─', + height=lambda: cli_ref._tui_input_rule_height("top"), + style='class:input-rule', + ) + input_rule_bot = Window( + char='─', + height=lambda: cli_ref._tui_input_rule_height("bottom"), + style='class:input-rule', + ) + + # Image attachment indicator — shows badges like [📎 Image #1] above input + cli_ref = self + + def _get_image_bar(): + if not cli_ref._attached_images: + return [] + badges = _format_image_attachment_badges( + cli_ref._attached_images, + cli_ref._image_counter, + ) + return [("class:image-badge", f" {badges} ")] + + image_bar = Window( + content=FormattedTextControl(_get_image_bar), + height=Condition(lambda: bool(cli_ref._attached_images)), + ) + + # Persistent voice mode status bar (visible only when voice mode is on) + def _get_voice_status(): + return cli_ref._get_voice_status_fragments() + + voice_status_bar = ConditionalContainer( + Window( + FormattedTextControl(_get_voice_status), + height=1, + ), + filter=Condition(lambda: cli_ref._voice_mode), + ) + + status_bar = ConditionalContainer( + Window( + content=FormattedTextControl(lambda: cli_ref._get_status_bar_fragments()), + height=1, + # Prevent fragments that overflow the terminal width from + # wrapping onto a second line, which causes the status bar to + # appear duplicated (one full + one partial row) during long + # sessions, especially on SSH where shutil.get_terminal_size + # may return stale values. _get_status_bar_fragments now reads + # width from prompt_toolkit's own output object, so fragments + # will always fit; wrap_lines=False is the belt-and-suspenders + # guard against any future width mismatch. + wrap_lines=False, + ), + filter=Condition(lambda: cli_ref._status_bar_visible), + ) + + # Allow wrapper CLIs to register extra keybindings. + self._register_extra_tui_keybindings(kb, input_area=input_area) + + # Layout: interactive prompt widgets + ruled input at bottom. + # The sudo, approval, and clarify widgets appear above the input when + # the corresponding interactive prompt is active. + completions_menu = CompletionsMenu(max_height=12, scroll_offset=1) + + layout = Layout( + HSplit( + self._build_tui_layout_children( + sudo_widget=sudo_widget, + secret_widget=secret_widget, + approval_widget=approval_widget, + clarify_widget=clarify_widget, + model_picker_widget=model_picker_widget, + spinner_widget=spinner_widget, + spacer=spacer, + status_bar=status_bar, + input_rule_top=input_rule_top, + image_bar=image_bar, + input_area=input_area, + input_rule_bot=input_rule_bot, + voice_status_bar=voice_status_bar, + completions_menu=completions_menu, + ) + ) + ) + + # Style for the application + self._tui_style_base = { + 'input-area': '#FFF8DC', + 'placeholder': '#555555 italic', + 'prompt': '#FFF8DC', + 'prompt-working': '#888888 italic', + 'hint': '#555555 italic', + 'status-bar': 'bg:#1a1a2e #C0C0C0', + 'status-bar-strong': 'bg:#1a1a2e #FFD700 bold', + 'status-bar-dim': 'bg:#1a1a2e #8B8682', + 'status-bar-good': 'bg:#1a1a2e #8FBC8F bold', + 'status-bar-warn': 'bg:#1a1a2e #FFD700 bold', + 'status-bar-bad': 'bg:#1a1a2e #FF8C00 bold', + 'status-bar-critical': 'bg:#1a1a2e #FF6B6B bold', + # Bronze horizontal rules around the input area + 'input-rule': '#CD7F32', + # Clipboard image attachment badges + 'image-badge': '#87CEEB bold', + 'completion-menu': 'bg:#1a1a2e #FFF8DC', + 'completion-menu.completion': 'bg:#1a1a2e #FFF8DC', + 'completion-menu.completion.current': 'bg:#333355 #FFD700', + 'completion-menu.meta.completion': 'bg:#1a1a2e #888888', + 'completion-menu.meta.completion.current': 'bg:#333355 #FFBF00', + # Clarify question panel + 'clarify-border': '#CD7F32', + 'clarify-title': '#FFD700 bold', + 'clarify-question': '#FFF8DC bold', + 'clarify-choice': '#AAAAAA', + 'clarify-selected': '#FFD700 bold', + 'clarify-active-other': '#FFD700 italic', + 'clarify-countdown': '#CD7F32', + # Sudo password panel + 'sudo-prompt': '#FF6B6B bold', + 'sudo-border': '#CD7F32', + 'sudo-title': '#FF6B6B bold', + 'sudo-text': '#FFF8DC', + # Dangerous command approval panel + 'approval-border': '#CD7F32', + 'approval-title': '#FF8C00 bold', + 'approval-desc': '#FFF8DC bold', + 'approval-cmd': '#AAAAAA italic', + 'approval-choice': '#AAAAAA', + 'approval-selected': '#FFD700 bold', + # Voice mode + 'voice-prompt': '#87CEEB', + 'voice-recording': '#FF4444 bold', + 'voice-processing': '#FFA500 italic', + 'voice-status': 'bg:#1a1a2e #87CEEB', + 'voice-status-recording': 'bg:#1a1a2e #FF4444 bold', + } + style = PTStyle.from_dict(self._build_tui_style_dict()) + + # Create the application + app = Application( + layout=layout, + key_bindings=kb, + style=style, + full_screen=False, + mouse_support=False, + **({'cursor': _STEADY_CURSOR} if _STEADY_CURSOR is not None else {}), + ) + self._app = app # Store reference for clarify_callback + + # ── Fix ghost status-bar lines on terminal resize ────────────── + # When the terminal shrinks (e.g. un-maximize), the emulator reflows + # the previously-rendered full-width rows (status bar, input rules) + # into multiple narrower rows. prompt_toolkit's _on_resize handler + # only cursor_up()s by the stored layout height, missing the extra + # rows created by reflow — leaving ghost duplicates visible. + # + # Fix: before the standard erase, inflate _cursor_pos.y so the + # cursor moves up far enough to cover the reflowed ghost content. + _original_on_resize = app._on_resize + + def _resize_clear_ghosts(): + from prompt_toolkit.data_structures import Point as _Pt + renderer = app.renderer + try: + old_size = renderer._last_size + new_size = renderer.output.get_size() + if ( + old_size + and new_size.columns < old_size.columns + and new_size.columns > 0 + ): + reflow_factor = ( + (old_size.columns + new_size.columns - 1) + // new_size.columns + ) + last_h = ( + renderer._last_screen.height + if renderer._last_screen + else 0 + ) + extra = last_h * (reflow_factor - 1) + if extra > 0: + renderer._cursor_pos = _Pt( + x=renderer._cursor_pos.x, + y=renderer._cursor_pos.y + extra, + ) + except Exception: + pass # never break resize handling + _original_on_resize() + + app._on_resize = _resize_clear_ghosts + + def spinner_loop(): + import time as _time + + last_idle_refresh = 0.0 + while not self._should_exit: + if not self._app: + _time.sleep(0.1) + continue + if self._command_running: + self._invalidate(min_interval=0.1) + _time.sleep(0.1) + else: + now = _time.monotonic() + if now - last_idle_refresh >= 1.0: + last_idle_refresh = now + self._invalidate(min_interval=1.0) + _time.sleep(0.2) + + spinner_thread = threading.Thread(target=spinner_loop, daemon=True) + spinner_thread.start() + + # Background thread to process inputs and run agent + def process_loop(): + while not self._should_exit: + try: + # Check for pending input with timeout + try: + user_input = self._pending_input.get(timeout=0.1) + except queue.Empty: + # Periodic config watcher — auto-reload MCP on mcp_servers change + if not self._agent_running: + self._check_config_mcp_changes() + # Check for background process notifications (completions + # and watch pattern matches) while agent is idle. + try: + from tools.process_registry import process_registry + if not process_registry.completion_queue.empty(): + evt = process_registry.completion_queue.get_nowait() + # Skip if the agent already consumed this via wait/poll/log + _evt_sid = evt.get("session_id", "") + if evt.get("type") == "completion" and process_registry.is_completion_consumed(_evt_sid): + pass # already delivered via tool result + else: + _synth = _format_process_notification(evt) + if _synth: + self._pending_input.put(_synth) + except Exception: + pass + continue + + if not user_input: + continue + + # Unpack image payload: (text, [Path, ...]) or plain str + submit_images = [] + if isinstance(user_input, tuple): + user_input, submit_images = user_input + + # Check for commands — but detect dragged/pasted file paths first. + # See _detect_file_drop() for details. + _file_drop = _detect_file_drop(user_input) if isinstance(user_input, str) else None + if _file_drop: + _drop_path = _file_drop["path"] + _remainder = _file_drop["remainder"] + if _file_drop["is_image"]: + submit_images.append(_drop_path) + user_input = _remainder or f"[User attached image: {_drop_path.name}]" + _cprint(f" 📎 Auto-attached image: {_drop_path.name}") + else: + _cprint(f" 📄 Detected file: {_drop_path.name}") + user_input = ( + f"[User attached file: {_drop_path}]" + + (f"\n{_remainder}" if _remainder else "") + ) + + if not _file_drop and isinstance(user_input, str) and _looks_like_slash_command(user_input): + _cprint(f"\n⚙️ {user_input}") + if not self.process_command(user_input): + self._should_exit = True + # Schedule app exit + if app.is_running: + app.exit() + continue + + # Expand paste references back to full content + import re as _re + _paste_ref_re = _re.compile(r'\[Pasted text #\d+: \d+ lines \u2192 (.+?)\]') + paste_refs = list(_paste_ref_re.finditer(user_input)) if isinstance(user_input, str) else [] + if paste_refs: + def _expand_ref(m): + p = Path(m.group(1)) + return p.read_text(encoding="utf-8") if p.exists() else m.group(0) + expanded = _paste_ref_re.sub(_expand_ref, user_input) + total_lines = expanded.count('\n') + 1 + n_pastes = len(paste_refs) + _user_bar = f"[{_accent_hex()}]{'─' * 40}[/]" + print() + ChatConsole().print(_user_bar) + # Show any surrounding user text alongside the paste summary + split_parts = _paste_ref_re.split(user_input) + visible_user_text = " ".join( + split_parts[i].strip() for i in range(0, len(split_parts), 2) if split_parts[i].strip() + ) + if visible_user_text: + ChatConsole().print( + f"[bold {_accent_hex()}]\u25cf[/] [bold]{_escape(visible_user_text)}[/] " + f"[dim]({n_pastes} pasted block{'s' if n_pastes > 1 else ''}, {total_lines} lines total)[/]" + ) + else: + ChatConsole().print( + f"[bold {_accent_hex()}]\u25cf[/] [bold]{_escape(f'[Pasted text: {total_lines} lines]')}[/]" + ) + user_input = expanded + else: + _user_bar = f"[{_accent_hex()}]{'─' * 40}[/]" + if '\n' in user_input: + first_line = user_input.split('\n')[0] + line_count = user_input.count('\n') + 1 + print() + ChatConsole().print(_user_bar) + ChatConsole().print( + f"[bold {_accent_hex()}]●[/] [bold]{_escape(first_line)}[/] " + f"[dim](+{line_count - 1} lines)[/]" + ) + else: + print() + ChatConsole().print(_user_bar) + ChatConsole().print(f"[bold {_accent_hex()}]●[/] [bold]{_escape(user_input)}[/]") + + # Show image attachment count + if submit_images: + n = len(submit_images) + _cprint(f" {_DIM}📎 {n} image{'s' if n > 1 else ''} attached{_RST}") + + # Regular chat - run agent + self._agent_running = True + app.invalidate() # Refresh status line + + try: + self.chat(user_input, images=submit_images or None) + finally: + self._agent_running = False + self._spinner_text = "" + self._tool_start_time = 0.0 + self._pending_tool_info.clear() + self._last_scrollback_tool = "" + + app.invalidate() # Refresh status line + + # Continuous voice: auto-restart recording after agent responds. + # Dispatch to a daemon thread so play_beep (sd.wait) and + # AudioRecorder.start (lock acquire) never block process_loop — + # otherwise queued user input would stall silently. + if self._voice_mode and self._voice_continuous and not self._voice_recording: + def _restart_recording(): + try: + if self._voice_tts: + self._voice_tts_done.wait(timeout=60) + time.sleep(0.3) + self._voice_start_recording() + app.invalidate() + except Exception as e: + _cprint(f"{_DIM}Voice auto-restart failed: {e}{_RST}") + threading.Thread(target=_restart_recording, daemon=True).start() + + # Drain process notifications (completions + watch matches) + # that arrived while the agent was running. + try: + from tools.process_registry import process_registry + while not process_registry.completion_queue.empty(): + evt = process_registry.completion_queue.get_nowait() + # Skip if the agent already consumed this via wait/poll/log + _evt_sid = evt.get("session_id", "") + if evt.get("type") == "completion" and process_registry.is_completion_consumed(_evt_sid): + continue # already delivered via tool result + _synth = _format_process_notification(evt) + if _synth: + self._pending_input.put(_synth) + except Exception: + pass # Non-fatal — don't break the main loop + + except Exception as e: + print(f"Error: {e}") + + # Start processing thread + process_thread = threading.Thread(target=process_loop, daemon=True) + process_thread.start() + + # Register atexit cleanup so resources are freed even on unexpected exit + atexit.register(_run_cleanup) + + # Register signal handlers for graceful shutdown on SSH disconnect / SIGTERM + def _signal_handler(signum, frame): + """Handle SIGHUP/SIGTERM by triggering graceful cleanup.""" + logger.debug("Received signal %s, triggering graceful shutdown", signum) + raise KeyboardInterrupt() + + try: + import signal as _signal + _signal.signal(_signal.SIGTERM, _signal_handler) + if hasattr(_signal, 'SIGHUP'): + _signal.signal(_signal.SIGHUP, _signal_handler) + except Exception: + pass # Signal handlers may fail in restricted environments + + # Install a custom asyncio exception handler that suppresses the + # "Event loop is closed" RuntimeError from httpx transport cleanup + # and the "0 is not registered" KeyError from broken stdin (#6393). + # The RuntimeError fix is defense-in-depth — the primary fix is + # neuter_async_httpx_del which disables __del__ entirely. The + # KeyError fix handles macOS + uv-managed Python environments where + # fd 0 is not reliably available to the asyncio selector. + def _suppress_closed_loop_errors(loop, context): + exc = context.get("exception") + if isinstance(exc, RuntimeError) and "Event loop is closed" in str(exc): + return # silently suppress + if isinstance(exc, KeyError) and "is not registered" in str(exc): + return # suppress selector registration failures (#6393) + # Fall back to default handler for everything else + loop.default_exception_handler(context) + + # Validate stdin before launching prompt_toolkit — on macOS with + # uv-managed Python, fd 0 can be invalid or unregisterable with the + # asyncio selector, causing "KeyError: '0 is not registered'" (#6393). + try: + import os as _os + _os.fstat(0) + except OSError: + print( + "Error: stdin (fd 0) is not available.\n" + "This can happen with certain Python installations (e.g. uv-managed cPython on macOS).\n" + "Try reinstalling Python via pyenv or Homebrew, then re-run: hermes setup" + ) + _run_cleanup() + self._print_exit_summary() + return + + # Run the application with patch_stdout for proper output handling + try: + with patch_stdout(): + # Set the custom handler on prompt_toolkit's event loop + try: + import asyncio as _aio + _loop = _aio.get_event_loop() + _loop.set_exception_handler(_suppress_closed_loop_errors) + except Exception: + pass + app.run() + except (EOFError, KeyboardInterrupt, BrokenPipeError): + pass + except (KeyError, OSError) as _stdin_err: + # Catch selector registration failures from broken stdin (#6393). + # This is the fallback for cases that slip past the fstat() guard. + if "is not registered" in str(_stdin_err) or "Bad file descriptor" in str(_stdin_err): + print( + f"\nError: stdin is not usable ({_stdin_err}).\n" + "This can happen with certain Python installations (e.g. uv-managed cPython on macOS).\n" + "Try reinstalling Python via pyenv or Homebrew, then re-run: hermes setup" + ) + else: + raise + finally: + self._should_exit = True + # Interrupt the agent immediately so its daemon thread stops making + # API calls and exits promptly (agent_thread is daemon, so the + # process will exit once the main thread finishes, but interrupting + # avoids wasted API calls and lets run_conversation clean up). + if self.agent and getattr(self, '_agent_running', False): + try: + self.agent.interrupt() + except Exception: + pass + # Flush memories before exit (only for substantial conversations) + if self.agent and self.conversation_history: + try: + self.agent.flush_memories(self.conversation_history) + except (Exception, KeyboardInterrupt): + pass + # Shut down voice recorder (release persistent audio stream) + if hasattr(self, '_voice_recorder') and self._voice_recorder: + try: + self._voice_recorder.shutdown() + except Exception: + pass + self._voice_recorder = None + # Clean up old temp voice recordings + try: + from tools.voice_mode import cleanup_temp_recordings + cleanup_temp_recordings() + except Exception: + pass + # Unregister callbacks to avoid dangling references + set_sudo_password_callback(None) + set_approval_callback(None) + set_secret_capture_callback(None) + # Close session in SQLite + if hasattr(self, '_session_db') and self._session_db and self.agent: + try: + self._session_db.end_session(self.agent.session_id, "cli_close") + except (Exception, KeyboardInterrupt) as e: + logger.debug("Could not close session in DB: %s", e) + # Plugin hook: on_session_end — safety net for interrupted exits. + # run_conversation() already fires this per-turn on normal completion, + # so only fire here if the agent was mid-turn (_agent_running) when + # the exit occurred, meaning run_conversation's hook didn't fire. + if self.agent and getattr(self, '_agent_running', False): + try: + from hermes_cli.plugins import invoke_hook as _invoke_hook + _invoke_hook( + "on_session_end", + session_id=self.agent.session_id, + completed=False, + interrupted=True, + model=getattr(self.agent, 'model', None), + platform=getattr(self.agent, 'platform', None) or "cli", + ) + except Exception: + pass + _run_cleanup() + self._print_exit_summary() + + +# ============================================================================ +# Main Entry Point +# ============================================================================ + +def main( + query: str = None, + q: str = None, + image: str = None, + toolsets: str = None, + skills: str | list[str] | tuple[str, ...] = None, + model: str = None, + provider: str = None, + api_key: str = None, + base_url: str = None, + max_turns: int = None, + verbose: bool = False, + quiet: bool = False, + compact: bool = False, + list_tools: bool = False, + list_toolsets: bool = False, + gateway: bool = False, + resume: str = None, + worktree: bool = False, + w: bool = False, + checkpoints: bool = False, + pass_session_id: bool = False, +): + """ + Hermes Agent CLI - Interactive AI Assistant + + Args: + query: Single query to execute (then exit). Alias: -q + q: Shorthand for --query + image: Optional local image path to attach to a single query + toolsets: Comma-separated list of toolsets to enable (e.g., "web,terminal") + skills: Comma-separated or repeated list of skills to preload for the session + model: Model to use (default: anthropic/claude-opus-4-20250514) + provider: Inference provider ("auto", "openrouter", "nous", "openai-codex", "zai", "kimi-coding", "minimax", "minimax-cn") + api_key: API key for authentication + base_url: Base URL for the API + max_turns: Maximum tool-calling iterations (default: 60) + verbose: Enable verbose logging + compact: Use compact display mode + list_tools: List available tools and exit + list_toolsets: List available toolsets and exit + resume: Resume a previous session by its ID (e.g., 20260225_143052_a1b2c3) + worktree: Run in an isolated git worktree (for parallel agents). Alias: -w + w: Shorthand for --worktree + + Examples: + python cli.py # Start interactive mode + python cli.py --toolsets web,terminal # Use specific toolsets + python cli.py --skills hermes-agent-dev,github-auth + python cli.py -q "What is Python?" # Single query mode + python cli.py -q "Describe this" --image ~/storage/shared/Pictures/cat.png + python cli.py --list-tools # List tools and exit + python cli.py --resume 20260225_143052_a1b2c3 # Resume session + python cli.py -w # Start in isolated git worktree + python cli.py -w -q "Fix issue #123" # Single query in worktree + """ + global _active_worktree + + # Signal to terminal_tool that we're in interactive mode + # This enables interactive sudo password prompts with timeout + os.environ["HERMES_INTERACTIVE"] = "1" + + # Handle gateway mode (messaging + cron) + if gateway: + import asyncio + from gateway.run import start_gateway + print("Starting Hermes Gateway (messaging platforms)...") + asyncio.run(start_gateway()) + return + + # Skip worktree for list commands (they exit immediately) + if not list_tools and not list_toolsets: + # ── Git worktree isolation (#652) ── + # Create an isolated worktree so this agent instance doesn't collide + # with other agents working on the same repo. + use_worktree = worktree or w or CLI_CONFIG.get("worktree", False) + wt_info = None + if use_worktree: + # Prune stale worktrees from crashed/killed sessions + _repo = _git_repo_root() + if _repo: + _prune_stale_worktrees(_repo) + wt_info = _setup_worktree() + if wt_info: + _active_worktree = wt_info + os.environ["TERMINAL_CWD"] = wt_info["path"] + atexit.register(_cleanup_worktree, wt_info) + else: + # Worktree was explicitly requested but setup failed — + # don't silently run without isolation. + return + else: + wt_info = None + + # Handle query shorthand + query = query or q + + # Parse toolsets - handle both string and tuple/list inputs + # Default to hermes-cli toolset which includes cronjob management tools + toolsets_list = None + if toolsets: + if isinstance(toolsets, str): + toolsets_list = [t.strip() for t in toolsets.split(",")] + elif isinstance(toolsets, (list, tuple)): + # Fire may pass multiple --toolsets as a tuple + toolsets_list = [] + for t in toolsets: + if isinstance(t, str): + toolsets_list.extend([x.strip() for x in t.split(",")]) + else: + toolsets_list.append(str(t)) + else: + # Use the shared resolver so MCP servers are included at runtime + from hermes_cli.tools_config import _get_platform_tools + toolsets_list = sorted(_get_platform_tools(CLI_CONFIG, "cli")) + + parsed_skills = _parse_skills_argument(skills) + + # Create CLI instance + cli = HermesCLI( + model=model, + toolsets=toolsets_list, + provider=provider, + api_key=api_key, + base_url=base_url, + max_turns=max_turns, + verbose=verbose, + compact=compact, + resume=resume, + checkpoints=checkpoints, + pass_session_id=pass_session_id, + ) + + if parsed_skills: + skills_prompt, loaded_skills, missing_skills = build_preloaded_skills_prompt( + parsed_skills, + task_id=cli.session_id, + ) + if missing_skills: + missing_display = ", ".join(missing_skills) + raise ValueError(f"Unknown skill(s): {missing_display}") + if skills_prompt: + cli.system_prompt = "\n\n".join( + part for part in (cli.system_prompt, skills_prompt) if part + ).strip() + cli.preloaded_skills = loaded_skills + + # Inject worktree context into agent's system prompt + if wt_info: + wt_note = ( + f"\n\n[System note: You are working in an isolated git worktree at " + f"{wt_info['path']}. Your branch is `{wt_info['branch']}`. " + f"Changes here do not affect the main working tree or other agents. " + f"Remember to commit and push your changes, and create a PR if appropriate. " + f"The original repo is at {wt_info['repo_root']}.]" + ) + cli.system_prompt = (cli.system_prompt or "") + wt_note + + # Handle list commands (don't init agent for these) + if list_tools: + cli.show_banner() + cli.show_tools() + sys.exit(0) + + if list_toolsets: + cli.show_banner() + cli.show_toolsets() + sys.exit(0) + + # Register cleanup for single-query mode (interactive mode registers in run()) + atexit.register(_run_cleanup) + + # Handle single query mode + if query or image: + query, single_query_images = _collect_query_images(query, image) + if quiet: + # Quiet mode: suppress banner, spinner, tool previews. + # Only print the final response and parseable session info. + cli.tool_progress_mode = "off" + if cli._ensure_runtime_credentials(): + effective_query = query + if single_query_images: + effective_query = cli._preprocess_images_with_vision( + query, + single_query_images, + announce=False, + ) + turn_route = cli._resolve_turn_agent_config(effective_query) + if turn_route["signature"] != cli._active_agent_route_signature: + cli.agent = None + if cli._init_agent( + model_override=turn_route["model"], + runtime_override=turn_route["runtime"], + route_label=turn_route["label"], + request_overrides=turn_route.get("request_overrides"), + ): + cli.agent.quiet_mode = True + cli.agent.suppress_status_output = True + result = cli.agent.run_conversation( + user_message=effective_query, + conversation_history=cli.conversation_history, + ) + response = result.get("final_response", "") if isinstance(result, dict) else str(result) + if response: + print(response) + print(f"\nsession_id: {cli.session_id}") + + # Ensure proper exit code for automation wrappers + sys.exit(1 if isinstance(result, dict) and result.get("failed") else 0) + + # Exit with error code if credentials or agent init fails + sys.exit(1) + else: + cli.show_banner() + _query_label = query or ("[image attached]" if single_query_images else "") + if _query_label: + cli.console.print(f"[bold blue]Query:[/] {_query_label}") + cli.chat(query, images=single_query_images or None) + cli._print_exit_summary() + return + + # Run interactive mode + cli.run() + + +if __name__ == "__main__": + fire.Fire(main) diff --git a/mindcli/_vendor/hermes_cli/__init__.py b/mindcli/_vendor/hermes_cli/__init__.py new file mode 100644 index 0000000..632aa5b --- /dev/null +++ b/mindcli/_vendor/hermes_cli/__init__.py @@ -0,0 +1,15 @@ +""" +Hermes CLI - Unified command-line interface for Hermes Agent. + +Provides subcommands for: +- hermes chat - Interactive chat (same as ./hermes) +- hermes gateway - Run gateway in foreground +- hermes gateway start - Start gateway service +- hermes gateway stop - Stop gateway service +- hermes setup - Interactive setup wizard +- hermes status - Show status of all components +- hermes cron - Manage cron jobs +""" + +__version__ = "0.9.0" +__release_date__ = "2026.4.13" diff --git a/mindcli/_vendor/hermes_cli/auth.py b/mindcli/_vendor/hermes_cli/auth.py new file mode 100644 index 0000000..e63a1eb --- /dev/null +++ b/mindcli/_vendor/hermes_cli/auth.py @@ -0,0 +1,3270 @@ +""" +Multi-provider authentication system for Hermes Agent. + +Supports OAuth device code flows (Nous Portal, future: OpenAI Codex) and +traditional API key providers (OpenRouter, custom endpoints). Auth state +is persisted in ~/.hermes/auth.json with cross-process file locking. + +Architecture: +- ProviderConfig registry defines known OAuth providers +- Auth store (auth.json) holds per-provider credential state +- resolve_provider() picks the active provider via priority chain +- resolve_*_runtime_credentials() handles token refresh and key minting +- logout_command() is the CLI entry point for clearing auth +""" + +from __future__ import annotations + +import json +import logging +import os +import shutil +import shlex +import stat +import base64 +import hashlib +import subprocess +import threading +import time +import uuid +import webbrowser +from contextlib import contextmanager +from dataclasses import dataclass, field +from datetime import datetime, timezone +from pathlib import Path +from typing import Any, Dict, List, Optional + +import httpx +import yaml + +from hermes_cli.config import get_hermes_home, get_config_path, read_raw_config +from hermes_constants import OPENROUTER_BASE_URL + +logger = logging.getLogger(__name__) + +try: + import fcntl +except Exception: + fcntl = None +try: + import msvcrt +except Exception: + msvcrt = None + +# ============================================================================= +# Constants +# ============================================================================= + +AUTH_STORE_VERSION = 1 +AUTH_LOCK_TIMEOUT_SECONDS = 15.0 + +# Nous Portal defaults +DEFAULT_NOUS_PORTAL_URL = "https://portal.nousresearch.com" +DEFAULT_NOUS_INFERENCE_URL = "https://inference-api.nousresearch.com/v1" +DEFAULT_NOUS_CLIENT_ID = "hermes-cli" +DEFAULT_NOUS_SCOPE = "inference:mint_agent_key" +DEFAULT_AGENT_KEY_MIN_TTL_SECONDS = 30 * 60 # 30 minutes +ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120 # refresh 2 min before expiry +DEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS = 1 # poll at most every 1s +DEFAULT_CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex" +DEFAULT_QWEN_BASE_URL = "https://portal.qwen.ai/v1" +DEFAULT_GITHUB_MODELS_BASE_URL = "https://api.githubcopilot.com" +DEFAULT_COPILOT_ACP_BASE_URL = "acp://copilot" +CODEX_OAUTH_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann" +CODEX_OAUTH_TOKEN_URL = "https://auth.openai.com/oauth/token" +CODEX_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120 +QWEN_OAUTH_CLIENT_ID = "f0304373b74a44d2b584a3fb70ca9e56" +QWEN_OAUTH_TOKEN_URL = "https://chat.qwen.ai/api/v1/oauth2/token" +QWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120 + + +# ============================================================================= +# Provider Registry +# ============================================================================= + +@dataclass +class ProviderConfig: + """Describes a known inference provider.""" + id: str + name: str + auth_type: str # "oauth_device_code", "oauth_external", or "api_key" + portal_base_url: str = "" + inference_base_url: str = "" + client_id: str = "" + scope: str = "" + extra: Dict[str, Any] = field(default_factory=dict) + # For API-key providers: env vars to check (in priority order) + api_key_env_vars: tuple = () + # Optional env var for base URL override + base_url_env_var: str = "" + + +PROVIDER_REGISTRY: Dict[str, ProviderConfig] = { + "nous": ProviderConfig( + id="nous", + name="Nous Portal", + auth_type="oauth_device_code", + portal_base_url=DEFAULT_NOUS_PORTAL_URL, + inference_base_url=DEFAULT_NOUS_INFERENCE_URL, + client_id=DEFAULT_NOUS_CLIENT_ID, + scope=DEFAULT_NOUS_SCOPE, + ), + "openai-codex": ProviderConfig( + id="openai-codex", + name="OpenAI Codex", + auth_type="oauth_external", + inference_base_url=DEFAULT_CODEX_BASE_URL, + ), + "qwen-oauth": ProviderConfig( + id="qwen-oauth", + name="Qwen OAuth", + auth_type="oauth_external", + inference_base_url=DEFAULT_QWEN_BASE_URL, + ), + "copilot": ProviderConfig( + id="copilot", + name="GitHub Copilot", + auth_type="api_key", + inference_base_url=DEFAULT_GITHUB_MODELS_BASE_URL, + api_key_env_vars=("COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"), + base_url_env_var="COPILOT_API_BASE_URL", + ), + "copilot-acp": ProviderConfig( + id="copilot-acp", + name="GitHub Copilot ACP", + auth_type="external_process", + inference_base_url=DEFAULT_COPILOT_ACP_BASE_URL, + base_url_env_var="COPILOT_ACP_BASE_URL", + ), + "gemini": ProviderConfig( + id="gemini", + name="Google AI Studio", + auth_type="api_key", + inference_base_url="https://generativelanguage.googleapis.com/v1beta/openai", + api_key_env_vars=("GOOGLE_API_KEY", "GEMINI_API_KEY"), + base_url_env_var="GEMINI_BASE_URL", + ), + "zai": ProviderConfig( + id="zai", + name="Z.AI / GLM", + auth_type="api_key", + inference_base_url="https://api.z.ai/api/paas/v4", + api_key_env_vars=("GLM_API_KEY", "ZAI_API_KEY", "Z_AI_API_KEY"), + base_url_env_var="GLM_BASE_URL", + ), + "kimi-coding": ProviderConfig( + id="kimi-coding", + name="Kimi / Moonshot", + auth_type="api_key", + inference_base_url="https://api.moonshot.ai/v1", + api_key_env_vars=("KIMI_API_KEY",), + base_url_env_var="KIMI_BASE_URL", + ), + "kimi-coding-cn": ProviderConfig( + id="kimi-coding-cn", + name="Kimi / Moonshot (China)", + auth_type="api_key", + inference_base_url="https://api.moonshot.cn/v1", + api_key_env_vars=("KIMI_CN_API_KEY",), + ), + "arcee": ProviderConfig( + id="arcee", + name="Arcee AI", + auth_type="api_key", + inference_base_url="https://api.arcee.ai/api/v1", + api_key_env_vars=("ARCEEAI_API_KEY",), + base_url_env_var="ARCEE_BASE_URL", + ), + "minimax": ProviderConfig( + id="minimax", + name="MiniMax", + auth_type="api_key", + inference_base_url="https://api.minimax.io/anthropic", + api_key_env_vars=("MINIMAX_API_KEY",), + base_url_env_var="MINIMAX_BASE_URL", + ), + "anthropic": ProviderConfig( + id="anthropic", + name="Anthropic", + auth_type="api_key", + inference_base_url="https://api.anthropic.com", + api_key_env_vars=("ANTHROPIC_API_KEY", "ANTHROPIC_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"), + ), + "alibaba": ProviderConfig( + id="alibaba", + name="Alibaba Cloud (DashScope)", + auth_type="api_key", + inference_base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1", + api_key_env_vars=("DASHSCOPE_API_KEY",), + base_url_env_var="DASHSCOPE_BASE_URL", + ), + "minimax-cn": ProviderConfig( + id="minimax-cn", + name="MiniMax (China)", + auth_type="api_key", + inference_base_url="https://api.minimaxi.com/anthropic", + api_key_env_vars=("MINIMAX_CN_API_KEY",), + base_url_env_var="MINIMAX_CN_BASE_URL", + ), + "deepseek": ProviderConfig( + id="deepseek", + name="DeepSeek", + auth_type="api_key", + inference_base_url="https://api.deepseek.com/v1", + api_key_env_vars=("DEEPSEEK_API_KEY",), + base_url_env_var="DEEPSEEK_BASE_URL", + ), + "xai": ProviderConfig( + id="xai", + name="xAI", + auth_type="api_key", + inference_base_url="https://api.x.ai/v1", + api_key_env_vars=("XAI_API_KEY",), + base_url_env_var="XAI_BASE_URL", + ), + "ai-gateway": ProviderConfig( + id="ai-gateway", + name="Vercel AI Gateway", + auth_type="api_key", + inference_base_url="https://ai-gateway.vercel.sh/v1", + api_key_env_vars=("AI_GATEWAY_API_KEY",), + base_url_env_var="AI_GATEWAY_BASE_URL", + ), + "opencode-zen": ProviderConfig( + id="opencode-zen", + name="OpenCode Zen", + auth_type="api_key", + inference_base_url="https://opencode.ai/zen/v1", + api_key_env_vars=("OPENCODE_ZEN_API_KEY",), + base_url_env_var="OPENCODE_ZEN_BASE_URL", + ), + "opencode-go": ProviderConfig( + id="opencode-go", + name="OpenCode Go", + auth_type="api_key", + # OpenCode Go mixes API surfaces by model: + # - GLM / Kimi use OpenAI-compatible chat completions under /v1 + # - MiniMax models use Anthropic Messages under /v1/messages + # Keep the provider base at /v1 and select api_mode per-model. + inference_base_url="https://opencode.ai/zen/go/v1", + api_key_env_vars=("OPENCODE_GO_API_KEY",), + base_url_env_var="OPENCODE_GO_BASE_URL", + ), + "kilocode": ProviderConfig( + id="kilocode", + name="Kilo Code", + auth_type="api_key", + inference_base_url="https://api.kilo.ai/api/gateway", + api_key_env_vars=("KILOCODE_API_KEY",), + base_url_env_var="KILOCODE_BASE_URL", + ), + "huggingface": ProviderConfig( + id="huggingface", + name="Hugging Face", + auth_type="api_key", + inference_base_url="https://router.huggingface.co/v1", + api_key_env_vars=("HF_TOKEN",), + base_url_env_var="HF_BASE_URL", + ), + "xiaomi": ProviderConfig( + id="xiaomi", + name="Xiaomi MiMo", + auth_type="api_key", + inference_base_url="https://api.xiaomimimo.com/v1", + api_key_env_vars=("XIAOMI_API_KEY",), + base_url_env_var="XIAOMI_BASE_URL", + ), +} + + +# ============================================================================= +# Anthropic Key Helper +# ============================================================================= + +def get_anthropic_key() -> str: + """Return the first usable Anthropic credential, or ``""``. + + Checks both the ``.env`` file (via ``get_env_value``) and the process + environment (``os.getenv``). The fallback order mirrors the + ``PROVIDER_REGISTRY["anthropic"].api_key_env_vars`` tuple: + + ANTHROPIC_API_KEY -> ANTHROPIC_TOKEN -> CLAUDE_CODE_OAUTH_TOKEN + """ + from hermes_cli.config import get_env_value + + for var in PROVIDER_REGISTRY["anthropic"].api_key_env_vars: + value = get_env_value(var) or os.getenv(var, "") + if value: + return value + return "" + + +# ============================================================================= +# Kimi Code Endpoint Detection +# ============================================================================= + +# Kimi Code (kimi.com/code) issues keys prefixed "sk-kimi-" that only work +# on api.kimi.com/coding/v1. Legacy keys from platform.moonshot.ai work on +# api.moonshot.ai/v1 (the default). Auto-detect when user hasn't set +# KIMI_BASE_URL explicitly. +KIMI_CODE_BASE_URL = "https://api.kimi.com/coding/v1" + + +def _resolve_kimi_base_url(api_key: str, default_url: str, env_override: str) -> str: + """Return the correct Kimi base URL based on the API key prefix. + + If the user has explicitly set KIMI_BASE_URL, that always wins. + Otherwise, sk-kimi- prefixed keys route to api.kimi.com/coding/v1. + """ + if env_override: + return env_override + if api_key.startswith("sk-kimi-"): + return KIMI_CODE_BASE_URL + return default_url + + + +_PLACEHOLDER_SECRET_VALUES = { + "*", + "**", + "***", + "changeme", + "your_api_key", + "your-api-key", + "placeholder", + "example", + "dummy", + "null", + "none", +} + + +def has_usable_secret(value: Any, *, min_length: int = 4) -> bool: + """Return True when a configured secret looks usable, not empty/placeholder.""" + if not isinstance(value, str): + return False + cleaned = value.strip() + if len(cleaned) < min_length: + return False + if cleaned.lower() in _PLACEHOLDER_SECRET_VALUES: + return False + return True + + +def _resolve_api_key_provider_secret( + provider_id: str, pconfig: ProviderConfig +) -> tuple[str, str]: + """Resolve an API-key provider's token and indicate where it came from.""" + if provider_id == "copilot": + # Use the dedicated copilot auth module for proper token validation + try: + from hermes_cli.copilot_auth import resolve_copilot_token + token, source = resolve_copilot_token() + if token: + return token, source + except ValueError as exc: + logger.warning("Copilot token validation failed: %s", exc) + except Exception: + pass + return "", "" + + for env_var in pconfig.api_key_env_vars: + val = os.getenv(env_var, "").strip() + if has_usable_secret(val): + return val, env_var + + return "", "" + + +# ============================================================================= +# Z.AI Endpoint Detection +# ============================================================================= + +# Z.AI has separate billing for general vs coding plans, and global vs China +# endpoints. A key that works on one may return "Insufficient balance" on +# another. We probe at setup time and store the working endpoint. + +ZAI_ENDPOINTS = [ + # (id, base_url, default_model, label) + ("global", "https://api.z.ai/api/paas/v4", "glm-5", "Global"), + ("cn", "https://open.bigmodel.cn/api/paas/v4", "glm-5", "China"), + ("coding-global", "https://api.z.ai/api/coding/paas/v4", "glm-4.7", "Global (Coding Plan)"), + ("coding-cn", "https://open.bigmodel.cn/api/coding/paas/v4", "glm-4.7", "China (Coding Plan)"), +] + + +def detect_zai_endpoint(api_key: str, timeout: float = 8.0) -> Optional[Dict[str, str]]: + """Probe z.ai endpoints to find one that accepts this API key. + + Returns {"id": ..., "base_url": ..., "model": ..., "label": ...} for the + first working endpoint, or None if all fail. + """ + for ep_id, base_url, model, label in ZAI_ENDPOINTS: + try: + resp = httpx.post( + f"{base_url}/chat/completions", + headers={ + "Authorization": f"Bearer {api_key}", + "Content-Type": "application/json", + }, + json={ + "model": model, + "stream": False, + "max_tokens": 1, + "messages": [{"role": "user", "content": "ping"}], + }, + timeout=timeout, + ) + if resp.status_code == 200: + logger.debug("Z.AI endpoint probe: %s (%s) OK", ep_id, base_url) + return { + "id": ep_id, + "base_url": base_url, + "model": model, + "label": label, + } + logger.debug("Z.AI endpoint probe: %s returned %s", ep_id, resp.status_code) + except Exception as exc: + logger.debug("Z.AI endpoint probe: %s failed: %s", ep_id, exc) + return None + + +def _resolve_zai_base_url(api_key: str, default_url: str, env_override: str) -> str: + """Return the correct Z.AI base URL by probing endpoints. + + If the user has explicitly set GLM_BASE_URL, that always wins. + Otherwise, probe the candidate endpoints to find one that accepts the + key. The detected endpoint is cached in provider state (auth.json) keyed + on a hash of the API key so subsequent starts skip the probe. + """ + if env_override: + return env_override + + # Check provider-state cache for a previously-detected endpoint. + auth_store = _load_auth_store() + state = _load_provider_state(auth_store, "zai") or {} + cached = state.get("detected_endpoint") + if isinstance(cached, dict) and cached.get("base_url"): + key_hash = cached.get("key_hash", "") + if key_hash == hashlib.sha256(api_key.encode()).hexdigest()[:16]: + logger.debug("Z.AI: using cached endpoint %s", cached["base_url"]) + return cached["base_url"] + + # Probe — may take up to ~8s per endpoint. + detected = detect_zai_endpoint(api_key) + if detected and detected.get("base_url"): + # Persist the detection result keyed on the API key hash. + key_hash = hashlib.sha256(api_key.encode()).hexdigest()[:16] + state["detected_endpoint"] = { + "base_url": detected["base_url"], + "endpoint_id": detected.get("id", ""), + "model": detected.get("model", ""), + "label": detected.get("label", ""), + "key_hash": key_hash, + } + _save_provider_state(auth_store, "zai", state) + logger.info("Z.AI: auto-detected endpoint %s (%s)", detected["label"], detected["base_url"]) + return detected["base_url"] + + logger.debug("Z.AI: probe failed, falling back to default %s", default_url) + return default_url + + +# ============================================================================= +# Error Types +# ============================================================================= + +class AuthError(RuntimeError): + """Structured auth error with UX mapping hints.""" + + def __init__( + self, + message: str, + *, + provider: str = "", + code: Optional[str] = None, + relogin_required: bool = False, + ) -> None: + super().__init__(message) + self.provider = provider + self.code = code + self.relogin_required = relogin_required + + +def format_auth_error(error: Exception) -> str: + """Map auth failures to concise user-facing guidance.""" + if not isinstance(error, AuthError): + return str(error) + + if error.relogin_required: + return f"{error} Run `hermes model` to re-authenticate." + + if error.code == "subscription_required": + return ( + "No active paid subscription found on Nous Portal. " + "Please purchase/activate a subscription, then retry." + ) + + if error.code == "insufficient_credits": + return ( + "Subscription credits are exhausted. " + "Top up/renew credits in Nous Portal, then retry." + ) + + if error.code == "temporarily_unavailable": + return f"{error} Please retry in a few seconds." + + return str(error) + + +def _token_fingerprint(token: Any) -> Optional[str]: + """Return a short hash fingerprint for telemetry without leaking token bytes.""" + if not isinstance(token, str): + return None + cleaned = token.strip() + if not cleaned: + return None + return hashlib.sha256(cleaned.encode("utf-8")).hexdigest()[:12] + + +def _oauth_trace_enabled() -> bool: + raw = os.getenv("HERMES_OAUTH_TRACE", "").strip().lower() + return raw in {"1", "true", "yes", "on"} + + +def _oauth_trace(event: str, *, sequence_id: Optional[str] = None, **fields: Any) -> None: + if not _oauth_trace_enabled(): + return + payload: Dict[str, Any] = {"event": event} + if sequence_id: + payload["sequence_id"] = sequence_id + payload.update(fields) + logger.info("oauth_trace %s", json.dumps(payload, sort_keys=True, ensure_ascii=False)) + + +# ============================================================================= +# Auth Store — persistence layer for ~/.hermes/auth.json +# ============================================================================= + +def _auth_file_path() -> Path: + return get_hermes_home() / "auth.json" + + +def _auth_lock_path() -> Path: + return _auth_file_path().with_suffix(".lock") + + +_auth_lock_holder = threading.local() + +@contextmanager +def _auth_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS): + """Cross-process advisory lock for auth.json reads+writes. Reentrant.""" + # Reentrant: if this thread already holds the lock, just yield. + if getattr(_auth_lock_holder, "depth", 0) > 0: + _auth_lock_holder.depth += 1 + try: + yield + finally: + _auth_lock_holder.depth -= 1 + return + + lock_path = _auth_lock_path() + lock_path.parent.mkdir(parents=True, exist_ok=True) + + if fcntl is None and msvcrt is None: + _auth_lock_holder.depth = 1 + try: + yield + finally: + _auth_lock_holder.depth = 0 + return + + # On Windows, msvcrt.locking needs the file to have content and the + # file pointer at position 0. Ensure the lock file has at least 1 byte. + if msvcrt and (not lock_path.exists() or lock_path.stat().st_size == 0): + lock_path.write_text(" ", encoding="utf-8") + + with lock_path.open("r+" if msvcrt else "a+") as lock_file: + deadline = time.time() + max(1.0, timeout_seconds) + while True: + try: + if fcntl: + fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB) + else: + lock_file.seek(0) + msvcrt.locking(lock_file.fileno(), msvcrt.LK_NBLCK, 1) + break + except (BlockingIOError, OSError, PermissionError): + if time.time() >= deadline: + raise TimeoutError("Timed out waiting for auth store lock") + time.sleep(0.05) + + _auth_lock_holder.depth = 1 + try: + yield + finally: + _auth_lock_holder.depth = 0 + if fcntl: + fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN) + elif msvcrt: + try: + lock_file.seek(0) + msvcrt.locking(lock_file.fileno(), msvcrt.LK_UNLCK, 1) + except (OSError, IOError): + pass + + +def _load_auth_store(auth_file: Optional[Path] = None) -> Dict[str, Any]: + auth_file = auth_file or _auth_file_path() + if not auth_file.exists(): + return {"version": AUTH_STORE_VERSION, "providers": {}} + + try: + raw = json.loads(auth_file.read_text()) + except Exception: + return {"version": AUTH_STORE_VERSION, "providers": {}} + + if isinstance(raw, dict) and ( + isinstance(raw.get("providers"), dict) + or isinstance(raw.get("credential_pool"), dict) + ): + raw.setdefault("providers", {}) + return raw + + # Migrate from PR's "systems" format if present + if isinstance(raw, dict) and isinstance(raw.get("systems"), dict): + systems = raw["systems"] + providers = {} + if "nous_portal" in systems: + providers["nous"] = systems["nous_portal"] + return {"version": AUTH_STORE_VERSION, "providers": providers, + "active_provider": "nous" if providers else None} + + return {"version": AUTH_STORE_VERSION, "providers": {}} + + +def _save_auth_store(auth_store: Dict[str, Any]) -> Path: + auth_file = _auth_file_path() + auth_file.parent.mkdir(parents=True, exist_ok=True) + auth_store["version"] = AUTH_STORE_VERSION + auth_store["updated_at"] = datetime.now(timezone.utc).isoformat() + payload = json.dumps(auth_store, indent=2) + "\n" + tmp_path = auth_file.with_name(f"{auth_file.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}") + try: + with tmp_path.open("w", encoding="utf-8") as handle: + handle.write(payload) + handle.flush() + os.fsync(handle.fileno()) + os.replace(tmp_path, auth_file) + try: + dir_fd = os.open(str(auth_file.parent), os.O_RDONLY) + except OSError: + dir_fd = None + if dir_fd is not None: + try: + os.fsync(dir_fd) + finally: + os.close(dir_fd) + finally: + try: + if tmp_path.exists(): + tmp_path.unlink() + except OSError: + pass + # Restrict file permissions to owner only + try: + auth_file.chmod(stat.S_IRUSR | stat.S_IWUSR) + except OSError: + pass + return auth_file + + +def _load_provider_state(auth_store: Dict[str, Any], provider_id: str) -> Optional[Dict[str, Any]]: + providers = auth_store.get("providers") + if not isinstance(providers, dict): + return None + state = providers.get(provider_id) + return dict(state) if isinstance(state, dict) else None + + +def _save_provider_state(auth_store: Dict[str, Any], provider_id: str, state: Dict[str, Any]) -> None: + providers = auth_store.setdefault("providers", {}) + if not isinstance(providers, dict): + auth_store["providers"] = {} + providers = auth_store["providers"] + providers[provider_id] = state + auth_store["active_provider"] = provider_id + + +def read_credential_pool(provider_id: Optional[str] = None) -> Dict[str, Any]: + """Return the persisted credential pool, or one provider slice.""" + auth_store = _load_auth_store() + pool = auth_store.get("credential_pool") + if not isinstance(pool, dict): + pool = {} + if provider_id is None: + return dict(pool) + provider_entries = pool.get(provider_id) + return list(provider_entries) if isinstance(provider_entries, list) else [] + + +def write_credential_pool(provider_id: str, entries: List[Dict[str, Any]]) -> Path: + """Persist one provider's credential pool under auth.json.""" + with _auth_store_lock(): + auth_store = _load_auth_store() + pool = auth_store.get("credential_pool") + if not isinstance(pool, dict): + pool = {} + auth_store["credential_pool"] = pool + pool[provider_id] = list(entries) + return _save_auth_store(auth_store) + + +def suppress_credential_source(provider_id: str, source: str) -> None: + """Mark a credential source as suppressed so it won't be re-seeded.""" + with _auth_store_lock(): + auth_store = _load_auth_store() + suppressed = auth_store.setdefault("suppressed_sources", {}) + provider_list = suppressed.setdefault(provider_id, []) + if source not in provider_list: + provider_list.append(source) + _save_auth_store(auth_store) + + +def is_source_suppressed(provider_id: str, source: str) -> bool: + """Check if a credential source has been suppressed by the user.""" + try: + auth_store = _load_auth_store() + suppressed = auth_store.get("suppressed_sources", {}) + return source in suppressed.get(provider_id, []) + except Exception: + return False + + +def get_provider_auth_state(provider_id: str) -> Optional[Dict[str, Any]]: + """Return persisted auth state for a provider, or None.""" + auth_store = _load_auth_store() + return _load_provider_state(auth_store, provider_id) + + +def get_active_provider() -> Optional[str]: + """Return the currently active provider ID from auth store.""" + auth_store = _load_auth_store() + return auth_store.get("active_provider") + + +def is_provider_explicitly_configured(provider_id: str) -> bool: + """Return True only if the user has explicitly configured this provider. + + Checks: + 1. active_provider in auth.json matches + 2. model.provider in config.yaml matches + 3. Provider-specific env vars are set (e.g. ANTHROPIC_API_KEY) + + This is used to gate auto-discovery of external credentials (e.g. + Claude Code's ~/.claude/.credentials.json) so they are never used + without the user's explicit choice. See PR #4210 for the same + pattern applied to the setup wizard gate. + """ + normalized = (provider_id or "").strip().lower() + + # 1. Check auth.json active_provider + try: + auth_store = _load_auth_store() + active = (auth_store.get("active_provider") or "").strip().lower() + if active and active == normalized: + return True + except Exception: + pass + + # 2. Check config.yaml model.provider + try: + from hermes_cli.config import load_config + cfg = load_config() + model_cfg = cfg.get("model") + if isinstance(model_cfg, dict): + cfg_provider = (model_cfg.get("provider") or "").strip().lower() + if cfg_provider == normalized: + return True + except Exception: + pass + + # 3. Check provider-specific env vars + # Exclude CLAUDE_CODE_OAUTH_TOKEN — it's set by Claude Code itself, + # not by the user explicitly configuring anthropic in Hermes. + _IMPLICIT_ENV_VARS = {"CLAUDE_CODE_OAUTH_TOKEN"} + pconfig = PROVIDER_REGISTRY.get(normalized) + if pconfig and pconfig.auth_type == "api_key": + for env_var in pconfig.api_key_env_vars: + if env_var in _IMPLICIT_ENV_VARS: + continue + if has_usable_secret(os.getenv(env_var, "")): + return True + + return False + + +def clear_provider_auth(provider_id: Optional[str] = None) -> bool: + """ + Clear auth state for a provider. Used by `hermes logout`. + If provider_id is None, clears the active provider. + Returns True if something was cleared. + """ + with _auth_store_lock(): + auth_store = _load_auth_store() + target = provider_id or auth_store.get("active_provider") + if not target: + return False + + providers = auth_store.get("providers", {}) + if not isinstance(providers, dict): + providers = {} + auth_store["providers"] = providers + + pool = auth_store.get("credential_pool") + if not isinstance(pool, dict): + pool = {} + auth_store["credential_pool"] = pool + + cleared = False + if target in providers: + del providers[target] + cleared = True + if target in pool: + del pool[target] + cleared = True + + if not cleared: + return False + if auth_store.get("active_provider") == target: + auth_store["active_provider"] = None + _save_auth_store(auth_store) + return True + + +def deactivate_provider() -> None: + """ + Clear active_provider in auth.json without deleting credentials. + Used when the user switches to a non-OAuth provider (OpenRouter, custom) + so auto-resolution doesn't keep picking the OAuth provider. + """ + with _auth_store_lock(): + auth_store = _load_auth_store() + auth_store["active_provider"] = None + _save_auth_store(auth_store) + + +# ============================================================================= +# Provider Resolution — picks which provider to use +# ============================================================================= + + +def _get_config_hint_for_unknown_provider(provider_name: str) -> str: + """Return a helpful hint string when provider resolution fails. + + Checks for common config.yaml mistakes (malformed custom_providers, etc.) + and returns a human-readable diagnostic, or empty string if nothing found. + """ + try: + from hermes_cli.config import validate_config_structure + issues = validate_config_structure() + if not issues: + return "" + + lines = ["Config issue detected — run 'hermes doctor' for full diagnostics:"] + for ci in issues: + prefix = "ERROR" if ci.severity == "error" else "WARNING" + lines.append(f" [{prefix}] {ci.message}") + # Show first line of hint + first_hint = ci.hint.splitlines()[0] if ci.hint else "" + if first_hint: + lines.append(f" → {first_hint}") + return "\n".join(lines) + except Exception: + return "" + + +def resolve_provider( + requested: Optional[str] = None, + *, + explicit_api_key: Optional[str] = None, + explicit_base_url: Optional[str] = None, +) -> str: + """ + Determine which inference provider to use. + + Priority (when requested="auto" or None): + 1. active_provider in auth.json with valid credentials + 2. Explicit CLI api_key/base_url -> "openrouter" + 3. OPENAI_API_KEY or OPENROUTER_API_KEY env vars -> "openrouter" + 4. Provider-specific API keys (GLM, Kimi, MiniMax) -> that provider + 5. Fallback: "openrouter" + """ + normalized = (requested or "auto").strip().lower() + + # Normalize provider aliases + _PROVIDER_ALIASES = { + "glm": "zai", "z-ai": "zai", "z.ai": "zai", "zhipu": "zai", + "google": "gemini", "google-gemini": "gemini", "google-ai-studio": "gemini", + "kimi": "kimi-coding", "kimi-for-coding": "kimi-coding", "moonshot": "kimi-coding", + "kimi-cn": "kimi-coding-cn", "moonshot-cn": "kimi-coding-cn", + "arcee-ai": "arcee", "arceeai": "arcee", + "minimax-china": "minimax-cn", "minimax_cn": "minimax-cn", + "claude": "anthropic", "claude-code": "anthropic", + "github": "copilot", "github-copilot": "copilot", + "github-models": "copilot", "github-model": "copilot", + "github-copilot-acp": "copilot-acp", "copilot-acp-agent": "copilot-acp", + "aigateway": "ai-gateway", "vercel": "ai-gateway", "vercel-ai-gateway": "ai-gateway", + "opencode": "opencode-zen", "zen": "opencode-zen", + "qwen-portal": "qwen-oauth", "qwen-cli": "qwen-oauth", "qwen-oauth": "qwen-oauth", + "hf": "huggingface", "hugging-face": "huggingface", "huggingface-hub": "huggingface", + "mimo": "xiaomi", "xiaomi-mimo": "xiaomi", + "go": "opencode-go", "opencode-go-sub": "opencode-go", + "kilo": "kilocode", "kilo-code": "kilocode", "kilo-gateway": "kilocode", + # Local server aliases — route through the generic custom provider + "lmstudio": "custom", "lm-studio": "custom", "lm_studio": "custom", + "ollama": "custom", "vllm": "custom", "llamacpp": "custom", + "llama.cpp": "custom", "llama-cpp": "custom", + } + normalized = _PROVIDER_ALIASES.get(normalized, normalized) + + if normalized == "openrouter": + return "openrouter" + if normalized == "custom": + return "custom" + if normalized in PROVIDER_REGISTRY: + return normalized + if normalized != "auto": + # Check for common config.yaml issues that cause this error + _config_hint = _get_config_hint_for_unknown_provider(normalized) + msg = f"Unknown provider '{normalized}'." + if _config_hint: + msg += f"\n\n{_config_hint}" + else: + msg += " Check 'hermes model' for available providers, or run 'hermes doctor' to diagnose config issues." + raise AuthError(msg, code="invalid_provider") + + # Explicit one-off CLI creds always mean openrouter/custom + if explicit_api_key or explicit_base_url: + return "openrouter" + + # Check auth store for an active OAuth provider + try: + auth_store = _load_auth_store() + active = auth_store.get("active_provider") + if active and active in PROVIDER_REGISTRY: + status = get_auth_status(active) + if status.get("logged_in"): + return active + except Exception as e: + logger.debug("Could not detect active auth provider: %s", e) + + if has_usable_secret(os.getenv("OPENAI_API_KEY")) or has_usable_secret(os.getenv("OPENROUTER_API_KEY")): + return "openrouter" + + # Auto-detect API-key providers by checking their env vars + for pid, pconfig in PROVIDER_REGISTRY.items(): + if pconfig.auth_type != "api_key": + continue + # GitHub tokens are commonly present for repo/tool access but should not + # hijack inference auto-selection unless the user explicitly chooses + # Copilot/GitHub Models as the provider. + if pid == "copilot": + continue + for env_var in pconfig.api_key_env_vars: + if has_usable_secret(os.getenv(env_var, "")): + return pid + + raise AuthError( + "No inference provider configured. Run 'hermes model' to choose a " + "provider and model, or set an API key (OPENROUTER_API_KEY, " + "OPENAI_API_KEY, etc.) in ~/.hermes/.env.", + code="no_provider_configured", + ) + + +# ============================================================================= +# Timestamp / TTL helpers +# ============================================================================= + +def _parse_iso_timestamp(value: Any) -> Optional[float]: + if not isinstance(value, str) or not value: + return None + text = value.strip() + if not text: + return None + if text.endswith("Z"): + text = text[:-1] + "+00:00" + try: + parsed = datetime.fromisoformat(text) + except Exception: + return None + if parsed.tzinfo is None: + parsed = parsed.replace(tzinfo=timezone.utc) + return parsed.timestamp() + + +def _is_expiring(expires_at_iso: Any, skew_seconds: int) -> bool: + expires_epoch = _parse_iso_timestamp(expires_at_iso) + if expires_epoch is None: + return True + return expires_epoch <= (time.time() + skew_seconds) + + +def _coerce_ttl_seconds(expires_in: Any) -> int: + try: + ttl = int(expires_in) + except Exception: + ttl = 0 + return max(0, ttl) + + +def _optional_base_url(value: Any) -> Optional[str]: + if not isinstance(value, str): + return None + cleaned = value.strip().rstrip("/") + return cleaned if cleaned else None + + +def _decode_jwt_claims(token: Any) -> Dict[str, Any]: + if not isinstance(token, str) or token.count(".") != 2: + return {} + payload = token.split(".")[1] + payload += "=" * ((4 - len(payload) % 4) % 4) + try: + raw = base64.urlsafe_b64decode(payload.encode("utf-8")) + claims = json.loads(raw.decode("utf-8")) + except Exception: + return {} + return claims if isinstance(claims, dict) else {} + + +def _codex_access_token_is_expiring(access_token: Any, skew_seconds: int) -> bool: + claims = _decode_jwt_claims(access_token) + exp = claims.get("exp") + if not isinstance(exp, (int, float)): + return False + return float(exp) <= (time.time() + max(0, int(skew_seconds))) + + +def _qwen_cli_auth_path() -> Path: + return Path.home() / ".qwen" / "oauth_creds.json" + + +def _read_qwen_cli_tokens() -> Dict[str, Any]: + auth_path = _qwen_cli_auth_path() + if not auth_path.exists(): + raise AuthError( + "Qwen CLI credentials not found. Run 'qwen auth qwen-oauth' first.", + provider="qwen-oauth", + code="qwen_auth_missing", + ) + try: + data = json.loads(auth_path.read_text(encoding="utf-8")) + except Exception as exc: + raise AuthError( + f"Failed to read Qwen CLI credentials from {auth_path}: {exc}", + provider="qwen-oauth", + code="qwen_auth_read_failed", + ) from exc + if not isinstance(data, dict): + raise AuthError( + f"Invalid Qwen CLI credentials in {auth_path}.", + provider="qwen-oauth", + code="qwen_auth_invalid", + ) + return data + + +def _save_qwen_cli_tokens(tokens: Dict[str, Any]) -> Path: + auth_path = _qwen_cli_auth_path() + auth_path.parent.mkdir(parents=True, exist_ok=True) + tmp_path = auth_path.with_suffix(".tmp") + tmp_path.write_text(json.dumps(tokens, indent=2, sort_keys=True) + "\n", encoding="utf-8") + os.chmod(tmp_path, stat.S_IRUSR | stat.S_IWUSR) + tmp_path.replace(auth_path) + return auth_path + + +def _qwen_access_token_is_expiring(expiry_date_ms: Any, skew_seconds: int = QWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS) -> bool: + try: + expiry_ms = int(expiry_date_ms) + except Exception: + return True + return (time.time() + max(0, int(skew_seconds))) * 1000 >= expiry_ms + + +def _refresh_qwen_cli_tokens(tokens: Dict[str, Any], timeout_seconds: float = 20.0) -> Dict[str, Any]: + refresh_token = str(tokens.get("refresh_token", "") or "").strip() + if not refresh_token: + raise AuthError( + "Qwen OAuth refresh token missing. Re-run 'qwen auth qwen-oauth'.", + provider="qwen-oauth", + code="qwen_refresh_token_missing", + ) + + try: + response = httpx.post( + QWEN_OAUTH_TOKEN_URL, + headers={ + "Content-Type": "application/x-www-form-urlencoded", + "Accept": "application/json", + }, + data={ + "grant_type": "refresh_token", + "refresh_token": refresh_token, + "client_id": QWEN_OAUTH_CLIENT_ID, + }, + timeout=timeout_seconds, + ) + except Exception as exc: + raise AuthError( + f"Qwen OAuth refresh failed: {exc}", + provider="qwen-oauth", + code="qwen_refresh_failed", + ) from exc + + if response.status_code >= 400: + body = response.text.strip() + raise AuthError( + "Qwen OAuth refresh failed. Re-run 'qwen auth qwen-oauth'." + + (f" Response: {body}" if body else ""), + provider="qwen-oauth", + code="qwen_refresh_failed", + ) + + try: + payload = response.json() + except Exception as exc: + raise AuthError( + f"Qwen OAuth refresh returned invalid JSON: {exc}", + provider="qwen-oauth", + code="qwen_refresh_invalid_json", + ) from exc + + if not isinstance(payload, dict) or not str(payload.get("access_token", "") or "").strip(): + raise AuthError( + "Qwen OAuth refresh response missing access_token.", + provider="qwen-oauth", + code="qwen_refresh_invalid_response", + ) + + expires_in = payload.get("expires_in") + try: + expires_in_seconds = int(expires_in) + except Exception: + expires_in_seconds = 6 * 60 * 60 + + refreshed = { + "access_token": str(payload.get("access_token", "") or "").strip(), + "refresh_token": str(payload.get("refresh_token", refresh_token) or refresh_token).strip(), + "token_type": str(payload.get("token_type", tokens.get("token_type", "Bearer")) or "Bearer").strip() or "Bearer", + "resource_url": str(payload.get("resource_url", tokens.get("resource_url", "portal.qwen.ai")) or "portal.qwen.ai").strip(), + "expiry_date": int(time.time() * 1000) + max(1, expires_in_seconds) * 1000, + } + _save_qwen_cli_tokens(refreshed) + return refreshed + + +def resolve_qwen_runtime_credentials( + *, + force_refresh: bool = False, + refresh_if_expiring: bool = True, + refresh_skew_seconds: int = QWEN_ACCESS_TOKEN_REFRESH_SKEW_SECONDS, +) -> Dict[str, Any]: + tokens = _read_qwen_cli_tokens() + access_token = str(tokens.get("access_token", "") or "").strip() + should_refresh = bool(force_refresh) + if not should_refresh and refresh_if_expiring: + should_refresh = _qwen_access_token_is_expiring(tokens.get("expiry_date"), refresh_skew_seconds) + if should_refresh: + tokens = _refresh_qwen_cli_tokens(tokens) + access_token = str(tokens.get("access_token", "") or "").strip() + if not access_token: + raise AuthError( + "Qwen OAuth access token missing. Re-run 'qwen auth qwen-oauth'.", + provider="qwen-oauth", + code="qwen_access_token_missing", + ) + + base_url = os.getenv("HERMES_QWEN_BASE_URL", "").strip().rstrip("/") or DEFAULT_QWEN_BASE_URL + return { + "provider": "qwen-oauth", + "base_url": base_url, + "api_key": access_token, + "source": "qwen-cli", + "expires_at_ms": tokens.get("expiry_date"), + "auth_file": str(_qwen_cli_auth_path()), + } + + +def get_qwen_auth_status() -> Dict[str, Any]: + auth_path = _qwen_cli_auth_path() + try: + creds = resolve_qwen_runtime_credentials(refresh_if_expiring=False) + return { + "logged_in": True, + "auth_file": str(auth_path), + "source": creds.get("source"), + "api_key": creds.get("api_key"), + "expires_at_ms": creds.get("expires_at_ms"), + } + except AuthError as exc: + return { + "logged_in": False, + "auth_file": str(auth_path), + "error": str(exc), + } + + +# ============================================================================= +# SSH / remote session detection +# ============================================================================= + +def _is_remote_session() -> bool: + """Detect if running in an SSH session where webbrowser.open() won't work.""" + return bool(os.getenv("SSH_CLIENT") or os.getenv("SSH_TTY")) + + +# ============================================================================= +# OpenAI Codex auth — tokens stored in ~/.hermes/auth.json (not ~/.codex/) +# +# Hermes maintains its own Codex OAuth session separate from the Codex CLI +# and VS Code extension. This prevents refresh token rotation conflicts +# where one app's refresh invalidates the other's session. +# ============================================================================= + +def _read_codex_tokens(*, _lock: bool = True) -> Dict[str, Any]: + """Read Codex OAuth tokens from Hermes auth store (~/.hermes/auth.json). + + Returns dict with 'tokens' (access_token, refresh_token) and 'last_refresh'. + Raises AuthError if no Codex tokens are stored. + """ + if _lock: + with _auth_store_lock(): + auth_store = _load_auth_store() + else: + auth_store = _load_auth_store() + state = _load_provider_state(auth_store, "openai-codex") + if not state: + raise AuthError( + "No Codex credentials stored. Run `hermes auth` to authenticate.", + provider="openai-codex", + code="codex_auth_missing", + relogin_required=True, + ) + tokens = state.get("tokens") + if not isinstance(tokens, dict): + raise AuthError( + "Codex auth state is missing tokens. Run `hermes auth` to re-authenticate.", + provider="openai-codex", + code="codex_auth_invalid_shape", + relogin_required=True, + ) + access_token = tokens.get("access_token") + refresh_token = tokens.get("refresh_token") + if not isinstance(access_token, str) or not access_token.strip(): + raise AuthError( + "Codex auth is missing access_token. Run `hermes auth` to re-authenticate.", + provider="openai-codex", + code="codex_auth_missing_access_token", + relogin_required=True, + ) + if not isinstance(refresh_token, str) or not refresh_token.strip(): + raise AuthError( + "Codex auth is missing refresh_token. Run `hermes auth` to re-authenticate.", + provider="openai-codex", + code="codex_auth_missing_refresh_token", + relogin_required=True, + ) + return { + "tokens": tokens, + "last_refresh": state.get("last_refresh"), + } + + +def _write_codex_cli_tokens( + access_token: str, + refresh_token: str, + *, + last_refresh: Optional[str] = None, +) -> None: + """Write refreshed tokens back to ~/.codex/auth.json. + + OpenAI OAuth refresh tokens are single-use and rotate on every refresh. + When Hermes refreshes a token it consumes the old refresh_token; if we + don't write the new pair back, the Codex CLI (or VS Code extension) will + fail with ``refresh_token_reused`` on its next refresh attempt. + + This mirrors the Anthropic write-back to ~/.claude/.credentials.json + via ``_write_claude_code_credentials()``. + """ + codex_home = os.getenv("CODEX_HOME", "").strip() + if not codex_home: + codex_home = str(Path.home() / ".codex") + auth_path = Path(codex_home).expanduser() / "auth.json" + try: + existing: Dict[str, Any] = {} + if auth_path.is_file(): + existing = json.loads(auth_path.read_text(encoding="utf-8")) + if not isinstance(existing, dict): + existing = {} + + tokens_dict = existing.get("tokens") + if not isinstance(tokens_dict, dict): + tokens_dict = {} + tokens_dict["access_token"] = access_token + tokens_dict["refresh_token"] = refresh_token + existing["tokens"] = tokens_dict + if last_refresh is not None: + existing["last_refresh"] = last_refresh + + auth_path.parent.mkdir(parents=True, exist_ok=True) + auth_path.write_text(json.dumps(existing, indent=2), encoding="utf-8") + auth_path.chmod(0o600) + except (OSError, IOError) as exc: + logger.debug("Failed to write refreshed tokens to %s: %s", auth_path, exc) + + +def _save_codex_tokens(tokens: Dict[str, str], last_refresh: str = None) -> None: + """Save Codex OAuth tokens to Hermes auth store (~/.hermes/auth.json).""" + if last_refresh is None: + last_refresh = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") + with _auth_store_lock(): + auth_store = _load_auth_store() + state = _load_provider_state(auth_store, "openai-codex") or {} + state["tokens"] = tokens + state["last_refresh"] = last_refresh + state["auth_mode"] = "chatgpt" + _save_provider_state(auth_store, "openai-codex", state) + _save_auth_store(auth_store) + + +def refresh_codex_oauth_pure( + access_token: str, + refresh_token: str, + *, + timeout_seconds: float = 20.0, +) -> Dict[str, Any]: + """Refresh Codex OAuth tokens without mutating Hermes auth state.""" + del access_token # Access token is only used by callers to decide whether to refresh. + if not isinstance(refresh_token, str) or not refresh_token.strip(): + raise AuthError( + "Codex auth is missing refresh_token. Run `hermes auth` to re-authenticate.", + provider="openai-codex", + code="codex_auth_missing_refresh_token", + relogin_required=True, + ) + + timeout = httpx.Timeout(max(5.0, float(timeout_seconds))) + with httpx.Client(timeout=timeout, headers={"Accept": "application/json"}) as client: + response = client.post( + CODEX_OAUTH_TOKEN_URL, + headers={"Content-Type": "application/x-www-form-urlencoded"}, + data={ + "grant_type": "refresh_token", + "refresh_token": refresh_token, + "client_id": CODEX_OAUTH_CLIENT_ID, + }, + ) + + if response.status_code != 200: + code = "codex_refresh_failed" + message = f"Codex token refresh failed with status {response.status_code}." + relogin_required = False + try: + err = response.json() + if isinstance(err, dict): + err_code = err.get("error") + if isinstance(err_code, str) and err_code.strip(): + code = err_code.strip() + err_desc = err.get("error_description") or err.get("message") + if isinstance(err_desc, str) and err_desc.strip(): + message = f"Codex token refresh failed: {err_desc.strip()}" + except Exception: + pass + if code in {"invalid_grant", "invalid_token", "invalid_request"}: + relogin_required = True + if code == "refresh_token_reused": + message = ( + "Codex refresh token was already consumed by another client " + "(e.g. Codex CLI or VS Code extension). " + "Run `codex` in your terminal to generate fresh tokens, " + "then run `hermes auth` to re-authenticate." + ) + relogin_required = True + raise AuthError( + message, + provider="openai-codex", + code=code, + relogin_required=relogin_required, + ) + + try: + refresh_payload = response.json() + except Exception as exc: + raise AuthError( + "Codex token refresh returned invalid JSON.", + provider="openai-codex", + code="codex_refresh_invalid_json", + relogin_required=True, + ) from exc + + refreshed_access = refresh_payload.get("access_token") + if not isinstance(refreshed_access, str) or not refreshed_access.strip(): + raise AuthError( + "Codex token refresh response was missing access_token.", + provider="openai-codex", + code="codex_refresh_missing_access_token", + relogin_required=True, + ) + + updated = { + "access_token": refreshed_access.strip(), + "refresh_token": refresh_token.strip(), + "last_refresh": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"), + } + next_refresh = refresh_payload.get("refresh_token") + if isinstance(next_refresh, str) and next_refresh.strip(): + updated["refresh_token"] = next_refresh.strip() + return updated + + +def _refresh_codex_auth_tokens( + tokens: Dict[str, str], + timeout_seconds: float, +) -> Dict[str, str]: + """Refresh Codex access token using the refresh token. + + Saves the new tokens to Hermes auth store automatically. + """ + refreshed = refresh_codex_oauth_pure( + str(tokens.get("access_token", "") or ""), + str(tokens.get("refresh_token", "") or ""), + timeout_seconds=timeout_seconds, + ) + updated_tokens = dict(tokens) + updated_tokens["access_token"] = refreshed["access_token"] + updated_tokens["refresh_token"] = refreshed["refresh_token"] + + _save_codex_tokens(updated_tokens) + # Write back to ~/.codex/auth.json so Codex CLI / VS Code stay in sync. + _write_codex_cli_tokens( + refreshed["access_token"], + refreshed["refresh_token"], + last_refresh=refreshed.get("last_refresh"), + ) + return updated_tokens + + +def _import_codex_cli_tokens() -> Optional[Dict[str, str]]: + """Try to read tokens from ~/.codex/auth.json (Codex CLI shared file). + + Returns tokens dict if valid and not expired, None otherwise. + Does NOT write to the shared file. + """ + codex_home = os.getenv("CODEX_HOME", "").strip() + if not codex_home: + codex_home = str(Path.home() / ".codex") + auth_path = Path(codex_home).expanduser() / "auth.json" + if not auth_path.is_file(): + return None + try: + payload = json.loads(auth_path.read_text()) + tokens = payload.get("tokens") + if not isinstance(tokens, dict): + return None + access_token = tokens.get("access_token") + refresh_token = tokens.get("refresh_token") + if not access_token or not refresh_token: + return None + # Reject expired tokens — importing stale tokens from ~/.codex/ + # that can't be refreshed leaves the user stuck with "Login successful!" + # but no working credentials. + if _codex_access_token_is_expiring(access_token, 0): + logger.debug( + "Codex CLI tokens at %s are expired — skipping import.", auth_path, + ) + return None + return dict(tokens) + except Exception: + return None + + +def resolve_codex_runtime_credentials( + *, + force_refresh: bool = False, + refresh_if_expiring: bool = True, + refresh_skew_seconds: int = CODEX_ACCESS_TOKEN_REFRESH_SKEW_SECONDS, +) -> Dict[str, Any]: + """Resolve runtime credentials from Hermes's own Codex token store.""" + try: + data = _read_codex_tokens() + except AuthError as orig_err: + # Only attempt migration when there are NO tokens stored at all + # (code == "codex_auth_missing"), not when tokens exist but are invalid. + if orig_err.code != "codex_auth_missing": + raise + + # Migration: user had Codex as active provider with old storage (~/.codex/). + cli_tokens = _import_codex_cli_tokens() + if cli_tokens: + logger.info("Migrating Codex credentials from ~/.codex/ to Hermes auth store") + print("⚠️ Migrating Codex credentials to Hermes's own auth store.") + print(" This avoids conflicts with Codex CLI and VS Code.") + print(" Run `hermes auth` to create a fully independent session.\n") + _save_codex_tokens(cli_tokens) + data = _read_codex_tokens() + else: + raise + tokens = dict(data["tokens"]) + access_token = str(tokens.get("access_token", "") or "").strip() + refresh_timeout_seconds = float(os.getenv("HERMES_CODEX_REFRESH_TIMEOUT_SECONDS", "20")) + + should_refresh = bool(force_refresh) + if (not should_refresh) and refresh_if_expiring: + should_refresh = _codex_access_token_is_expiring(access_token, refresh_skew_seconds) + if should_refresh: + # Re-read under lock to avoid racing with other Hermes processes + with _auth_store_lock(timeout_seconds=max(float(AUTH_LOCK_TIMEOUT_SECONDS), refresh_timeout_seconds + 5.0)): + data = _read_codex_tokens(_lock=False) + tokens = dict(data["tokens"]) + access_token = str(tokens.get("access_token", "") or "").strip() + + should_refresh = bool(force_refresh) + if (not should_refresh) and refresh_if_expiring: + should_refresh = _codex_access_token_is_expiring(access_token, refresh_skew_seconds) + + if should_refresh: + tokens = _refresh_codex_auth_tokens(tokens, refresh_timeout_seconds) + access_token = str(tokens.get("access_token", "") or "").strip() + + base_url = ( + os.getenv("HERMES_CODEX_BASE_URL", "").strip().rstrip("/") + or DEFAULT_CODEX_BASE_URL + ) + + return { + "provider": "openai-codex", + "base_url": base_url, + "api_key": access_token, + "source": "hermes-auth-store", + "last_refresh": data.get("last_refresh"), + "auth_mode": "chatgpt", + } + + +# ============================================================================= +# TLS verification helper +# ============================================================================= + +def _resolve_verify( + *, + insecure: Optional[bool] = None, + ca_bundle: Optional[str] = None, + auth_state: Optional[Dict[str, Any]] = None, +) -> bool | str: + tls_state = auth_state.get("tls") if isinstance(auth_state, dict) else {} + tls_state = tls_state if isinstance(tls_state, dict) else {} + + effective_insecure = ( + bool(insecure) if insecure is not None + else bool(tls_state.get("insecure", False)) + ) + effective_ca = ( + ca_bundle + or tls_state.get("ca_bundle") + or os.getenv("HERMES_CA_BUNDLE") + or os.getenv("SSL_CERT_FILE") + ) + + if effective_insecure: + return False + if effective_ca: + ca_path = str(effective_ca) + if not os.path.isfile(ca_path): + import logging + logging.getLogger("hermes.auth").warning( + "CA bundle path does not exist: %s — falling back to default certificates", + ca_path, + ) + return True + return ca_path + return True + + +# ============================================================================= +# OAuth Device Code Flow — generic, parameterized by provider +# ============================================================================= + +def _request_device_code( + client: httpx.Client, + portal_base_url: str, + client_id: str, + scope: Optional[str], +) -> Dict[str, Any]: + """POST to the device code endpoint. Returns device_code, user_code, etc.""" + response = client.post( + f"{portal_base_url}/api/oauth/device/code", + data={ + "client_id": client_id, + **({"scope": scope} if scope else {}), + }, + ) + response.raise_for_status() + data = response.json() + + required_fields = [ + "device_code", "user_code", "verification_uri", + "verification_uri_complete", "expires_in", "interval", + ] + missing = [f for f in required_fields if f not in data] + if missing: + raise ValueError(f"Device code response missing fields: {', '.join(missing)}") + return data + + +def _poll_for_token( + client: httpx.Client, + portal_base_url: str, + client_id: str, + device_code: str, + expires_in: int, + poll_interval: int, +) -> Dict[str, Any]: + """Poll the token endpoint until the user approves or the code expires.""" + deadline = time.time() + max(1, expires_in) + current_interval = max(1, min(poll_interval, DEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS)) + + while time.time() < deadline: + response = client.post( + f"{portal_base_url}/api/oauth/token", + data={ + "grant_type": "urn:ietf:params:oauth:grant-type:device_code", + "client_id": client_id, + "device_code": device_code, + }, + ) + + if response.status_code == 200: + payload = response.json() + if "access_token" not in payload: + raise ValueError("Token response did not include access_token") + return payload + + try: + error_payload = response.json() + except Exception: + response.raise_for_status() + raise RuntimeError("Token endpoint returned a non-JSON error response") + + error_code = error_payload.get("error", "") + if error_code == "authorization_pending": + time.sleep(current_interval) + continue + if error_code == "slow_down": + current_interval = min(current_interval + 1, 30) + time.sleep(current_interval) + continue + + description = error_payload.get("error_description") or "Unknown authentication error" + raise RuntimeError(f"{error_code}: {description}") + + raise TimeoutError("Timed out waiting for device authorization") + + +# ============================================================================= +# Nous Portal — token refresh, agent key minting, model discovery +# ============================================================================= + +def _refresh_access_token( + *, + client: httpx.Client, + portal_base_url: str, + client_id: str, + refresh_token: str, +) -> Dict[str, Any]: + response = client.post( + f"{portal_base_url}/api/oauth/token", + data={ + "grant_type": "refresh_token", + "client_id": client_id, + "refresh_token": refresh_token, + }, + ) + + if response.status_code == 200: + payload = response.json() + if "access_token" not in payload: + raise AuthError("Refresh response missing access_token", + provider="nous", code="invalid_token", relogin_required=True) + return payload + + try: + error_payload = response.json() + except Exception as exc: + raise AuthError("Refresh token exchange failed", + provider="nous", relogin_required=True) from exc + + code = str(error_payload.get("error", "invalid_grant")) + description = str(error_payload.get("error_description") or "Refresh token exchange failed") + relogin = code in {"invalid_grant", "invalid_token"} + raise AuthError(description, provider="nous", code=code, relogin_required=relogin) + + +def _mint_agent_key( + *, + client: httpx.Client, + portal_base_url: str, + access_token: str, + min_ttl_seconds: int, +) -> Dict[str, Any]: + """Mint (or reuse) a short-lived inference API key.""" + response = client.post( + f"{portal_base_url}/api/oauth/agent-key", + headers={"Authorization": f"Bearer {access_token}"}, + json={"min_ttl_seconds": max(60, int(min_ttl_seconds))}, + ) + + if response.status_code == 200: + payload = response.json() + if "api_key" not in payload: + raise AuthError("Mint response missing api_key", + provider="nous", code="server_error") + return payload + + try: + error_payload = response.json() + except Exception as exc: + raise AuthError("Agent key mint request failed", + provider="nous", code="server_error") from exc + + code = str(error_payload.get("error", "server_error")) + description = str(error_payload.get("error_description") or "Agent key mint request failed") + relogin = code in {"invalid_token", "invalid_grant"} + raise AuthError(description, provider="nous", code=code, relogin_required=relogin) + + +def fetch_nous_models( + *, + inference_base_url: str, + api_key: str, + timeout_seconds: float = 15.0, + verify: bool | str = True, +) -> List[str]: + """Fetch available model IDs from the Nous inference API.""" + timeout = httpx.Timeout(timeout_seconds) + with httpx.Client(timeout=timeout, headers={"Accept": "application/json"}, verify=verify) as client: + response = client.get( + f"{inference_base_url.rstrip('/')}/models", + headers={"Authorization": f"Bearer {api_key}"}, + ) + + if response.status_code != 200: + description = f"/models request failed with status {response.status_code}" + try: + err = response.json() + description = str(err.get("error_description") or err.get("error") or description) + except Exception as e: + logger.debug("Could not parse error response JSON: %s", e) + raise AuthError(description, provider="nous", code="models_fetch_failed") + + payload = response.json() + data = payload.get("data") + if not isinstance(data, list): + return [] + + model_ids: List[str] = [] + for item in data: + if not isinstance(item, dict): + continue + model_id = item.get("id") + if isinstance(model_id, str) and model_id.strip(): + mid = model_id.strip() + # Skip Hermes models — they're not reliable for agentic tool-calling + if "hermes" in mid.lower(): + continue + model_ids.append(mid) + + # Sort: prefer opus > pro > haiku/flash > sonnet (sonnet is cheap/fast, + # users who want the best model should see opus first). + def _model_priority(mid: str) -> tuple: + low = mid.lower() + if "opus" in low: + return (0, mid) + if "pro" in low and "sonnet" not in low: + return (1, mid) + if "sonnet" in low: + return (3, mid) + return (2, mid) + + model_ids.sort(key=_model_priority) + return list(dict.fromkeys(model_ids)) + + +def _agent_key_is_usable(state: Dict[str, Any], min_ttl_seconds: int) -> bool: + key = state.get("agent_key") + if not isinstance(key, str) or not key.strip(): + return False + return not _is_expiring(state.get("agent_key_expires_at"), min_ttl_seconds) + + +def resolve_nous_access_token( + *, + timeout_seconds: float = 15.0, + insecure: Optional[bool] = None, + ca_bundle: Optional[str] = None, + refresh_skew_seconds: int = ACCESS_TOKEN_REFRESH_SKEW_SECONDS, +) -> str: + """Resolve a refresh-aware Nous Portal access token for managed tool gateways.""" + with _auth_store_lock(): + auth_store = _load_auth_store() + state = _load_provider_state(auth_store, "nous") + + if not state: + raise AuthError( + "Hermes is not logged into Nous Portal.", + provider="nous", + relogin_required=True, + ) + + portal_base_url = ( + _optional_base_url(state.get("portal_base_url")) + or os.getenv("HERMES_PORTAL_BASE_URL") + or os.getenv("NOUS_PORTAL_BASE_URL") + or DEFAULT_NOUS_PORTAL_URL + ).rstrip("/") + client_id = str(state.get("client_id") or DEFAULT_NOUS_CLIENT_ID) + verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state) + + access_token = state.get("access_token") + refresh_token = state.get("refresh_token") + if not isinstance(access_token, str) or not access_token: + raise AuthError( + "No access token found for Nous Portal login.", + provider="nous", + relogin_required=True, + ) + + if not _is_expiring(state.get("expires_at"), refresh_skew_seconds): + return access_token + + if not isinstance(refresh_token, str) or not refresh_token: + raise AuthError( + "Session expired and no refresh token is available.", + provider="nous", + relogin_required=True, + ) + + timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0) + with httpx.Client( + timeout=timeout, + headers={"Accept": "application/json"}, + verify=verify, + ) as client: + refreshed = _refresh_access_token( + client=client, + portal_base_url=portal_base_url, + client_id=client_id, + refresh_token=refresh_token, + ) + + now = datetime.now(timezone.utc) + access_ttl = _coerce_ttl_seconds(refreshed.get("expires_in")) + state["access_token"] = refreshed["access_token"] + state["refresh_token"] = refreshed.get("refresh_token") or refresh_token + state["token_type"] = refreshed.get("token_type") or state.get("token_type") or "Bearer" + state["scope"] = refreshed.get("scope") or state.get("scope") + state["obtained_at"] = now.isoformat() + state["expires_in"] = access_ttl + state["expires_at"] = datetime.fromtimestamp( + now.timestamp() + access_ttl, + tz=timezone.utc, + ).isoformat() + state["portal_base_url"] = portal_base_url + state["client_id"] = client_id + state["tls"] = { + "insecure": verify is False, + "ca_bundle": verify if isinstance(verify, str) else None, + } + _save_provider_state(auth_store, "nous", state) + _save_auth_store(auth_store) + return state["access_token"] + + +def refresh_nous_oauth_pure( + access_token: str, + refresh_token: str, + client_id: str, + portal_base_url: str, + inference_base_url: str, + *, + token_type: str = "Bearer", + scope: str = DEFAULT_NOUS_SCOPE, + obtained_at: Optional[str] = None, + expires_at: Optional[str] = None, + agent_key: Optional[str] = None, + agent_key_expires_at: Optional[str] = None, + min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS, + timeout_seconds: float = 15.0, + insecure: Optional[bool] = None, + ca_bundle: Optional[str] = None, + force_refresh: bool = False, + force_mint: bool = False, +) -> Dict[str, Any]: + """Refresh Nous OAuth state without mutating auth.json.""" + state: Dict[str, Any] = { + "access_token": access_token, + "refresh_token": refresh_token, + "client_id": client_id or DEFAULT_NOUS_CLIENT_ID, + "portal_base_url": (portal_base_url or DEFAULT_NOUS_PORTAL_URL).rstrip("/"), + "inference_base_url": (inference_base_url or DEFAULT_NOUS_INFERENCE_URL).rstrip("/"), + "token_type": token_type or "Bearer", + "scope": scope or DEFAULT_NOUS_SCOPE, + "obtained_at": obtained_at, + "expires_at": expires_at, + "agent_key": agent_key, + "agent_key_expires_at": agent_key_expires_at, + "tls": { + "insecure": bool(insecure), + "ca_bundle": ca_bundle, + }, + } + verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state) + timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0) + + with httpx.Client(timeout=timeout, headers={"Accept": "application/json"}, verify=verify) as client: + if force_refresh or _is_expiring(state.get("expires_at"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS): + refreshed = _refresh_access_token( + client=client, + portal_base_url=state["portal_base_url"], + client_id=state["client_id"], + refresh_token=state["refresh_token"], + ) + now = datetime.now(timezone.utc) + access_ttl = _coerce_ttl_seconds(refreshed.get("expires_in")) + state["access_token"] = refreshed["access_token"] + state["refresh_token"] = refreshed.get("refresh_token") or state["refresh_token"] + state["token_type"] = refreshed.get("token_type") or state.get("token_type") or "Bearer" + state["scope"] = refreshed.get("scope") or state.get("scope") + refreshed_url = _optional_base_url(refreshed.get("inference_base_url")) + if refreshed_url: + state["inference_base_url"] = refreshed_url + state["obtained_at"] = now.isoformat() + state["expires_in"] = access_ttl + state["expires_at"] = datetime.fromtimestamp( + now.timestamp() + access_ttl, tz=timezone.utc + ).isoformat() + + if force_mint or not _agent_key_is_usable(state, max(60, int(min_key_ttl_seconds))): + mint_payload = _mint_agent_key( + client=client, + portal_base_url=state["portal_base_url"], + access_token=state["access_token"], + min_ttl_seconds=min_key_ttl_seconds, + ) + now = datetime.now(timezone.utc) + state["agent_key"] = mint_payload.get("api_key") + state["agent_key_id"] = mint_payload.get("key_id") + state["agent_key_expires_at"] = mint_payload.get("expires_at") + state["agent_key_expires_in"] = mint_payload.get("expires_in") + state["agent_key_reused"] = bool(mint_payload.get("reused", False)) + state["agent_key_obtained_at"] = now.isoformat() + minted_url = _optional_base_url(mint_payload.get("inference_base_url")) + if minted_url: + state["inference_base_url"] = minted_url + + return state + + +def refresh_nous_oauth_from_state( + state: Dict[str, Any], + *, + min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS, + timeout_seconds: float = 15.0, + force_refresh: bool = False, + force_mint: bool = False, +) -> Dict[str, Any]: + """Refresh Nous OAuth from a state dict. Thin wrapper around refresh_nous_oauth_pure.""" + tls = state.get("tls") or {} + return refresh_nous_oauth_pure( + state.get("access_token", ""), + state.get("refresh_token", ""), + state.get("client_id", "hermes-cli"), + state.get("portal_base_url", DEFAULT_NOUS_PORTAL_URL), + state.get("inference_base_url", DEFAULT_NOUS_INFERENCE_URL), + token_type=state.get("token_type", "Bearer"), + scope=state.get("scope", DEFAULT_NOUS_SCOPE), + obtained_at=state.get("obtained_at"), + expires_at=state.get("expires_at"), + agent_key=state.get("agent_key"), + agent_key_expires_at=state.get("agent_key_expires_at"), + min_key_ttl_seconds=min_key_ttl_seconds, + timeout_seconds=timeout_seconds, + insecure=tls.get("insecure"), + ca_bundle=tls.get("ca_bundle"), + force_refresh=force_refresh, + force_mint=force_mint, + ) + + +def resolve_nous_runtime_credentials( + *, + min_key_ttl_seconds: int = DEFAULT_AGENT_KEY_MIN_TTL_SECONDS, + timeout_seconds: float = 15.0, + insecure: Optional[bool] = None, + ca_bundle: Optional[str] = None, + force_mint: bool = False, +) -> Dict[str, Any]: + """ + Resolve Nous inference credentials for runtime use. + + Ensures access_token is valid (refreshes if needed) and a short-lived + inference key is present with minimum TTL (mints/reuses as needed). + Concurrent processes coordinate through the auth store file lock. + + Returns dict with: provider, base_url, api_key, key_id, expires_at, + expires_in, source ("cache" or "portal"). + """ + min_key_ttl_seconds = max(60, int(min_key_ttl_seconds)) + sequence_id = uuid.uuid4().hex[:12] + + with _auth_store_lock(): + auth_store = _load_auth_store() + state = _load_provider_state(auth_store, "nous") + + if not state: + raise AuthError("Hermes is not logged into Nous Portal.", + provider="nous", relogin_required=True) + + portal_base_url = ( + _optional_base_url(state.get("portal_base_url")) + or os.getenv("HERMES_PORTAL_BASE_URL") + or os.getenv("NOUS_PORTAL_BASE_URL") + or DEFAULT_NOUS_PORTAL_URL + ).rstrip("/") + inference_base_url = ( + _optional_base_url(state.get("inference_base_url")) + or os.getenv("NOUS_INFERENCE_BASE_URL") + or DEFAULT_NOUS_INFERENCE_URL + ).rstrip("/") + client_id = str(state.get("client_id") or DEFAULT_NOUS_CLIENT_ID) + + def _persist_state(reason: str) -> None: + try: + _save_provider_state(auth_store, "nous", state) + _save_auth_store(auth_store) + except Exception as exc: + _oauth_trace( + "nous_state_persist_failed", + sequence_id=sequence_id, + reason=reason, + error_type=type(exc).__name__, + ) + raise + _oauth_trace( + "nous_state_persisted", + sequence_id=sequence_id, + reason=reason, + refresh_token_fp=_token_fingerprint(state.get("refresh_token")), + access_token_fp=_token_fingerprint(state.get("access_token")), + ) + + verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state) + timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0) + _oauth_trace( + "nous_runtime_credentials_start", + sequence_id=sequence_id, + force_mint=bool(force_mint), + min_key_ttl_seconds=min_key_ttl_seconds, + refresh_token_fp=_token_fingerprint(state.get("refresh_token")), + ) + + with httpx.Client(timeout=timeout, headers={"Accept": "application/json"}, verify=verify) as client: + access_token = state.get("access_token") + refresh_token = state.get("refresh_token") + + if not isinstance(access_token, str) or not access_token: + raise AuthError("No access token found for Nous Portal login.", + provider="nous", relogin_required=True) + + # Step 1: refresh access token if expiring + if _is_expiring(state.get("expires_at"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS): + if not isinstance(refresh_token, str) or not refresh_token: + raise AuthError("Session expired and no refresh token is available.", + provider="nous", relogin_required=True) + + _oauth_trace( + "refresh_start", + sequence_id=sequence_id, + reason="access_expiring", + refresh_token_fp=_token_fingerprint(refresh_token), + ) + refreshed = _refresh_access_token( + client=client, portal_base_url=portal_base_url, + client_id=client_id, refresh_token=refresh_token, + ) + now = datetime.now(timezone.utc) + access_ttl = _coerce_ttl_seconds(refreshed.get("expires_in")) + previous_refresh_token = refresh_token + state["access_token"] = refreshed["access_token"] + state["refresh_token"] = refreshed.get("refresh_token") or refresh_token + state["token_type"] = refreshed.get("token_type") or state.get("token_type") or "Bearer" + state["scope"] = refreshed.get("scope") or state.get("scope") + refreshed_url = _optional_base_url(refreshed.get("inference_base_url")) + if refreshed_url: + inference_base_url = refreshed_url + state["obtained_at"] = now.isoformat() + state["expires_in"] = access_ttl + state["expires_at"] = datetime.fromtimestamp( + now.timestamp() + access_ttl, tz=timezone.utc + ).isoformat() + access_token = state["access_token"] + refresh_token = state["refresh_token"] + _oauth_trace( + "refresh_success", + sequence_id=sequence_id, + reason="access_expiring", + previous_refresh_token_fp=_token_fingerprint(previous_refresh_token), + new_refresh_token_fp=_token_fingerprint(refresh_token), + ) + # Persist immediately so downstream mint failures cannot drop rotated refresh tokens. + _persist_state("post_refresh_access_expiring") + + # Step 2: mint agent key if missing/expiring + used_cached_key = False + mint_payload: Optional[Dict[str, Any]] = None + + if not force_mint and _agent_key_is_usable(state, min_key_ttl_seconds): + used_cached_key = True + _oauth_trace("agent_key_reuse", sequence_id=sequence_id) + else: + try: + _oauth_trace( + "mint_start", + sequence_id=sequence_id, + access_token_fp=_token_fingerprint(access_token), + ) + mint_payload = _mint_agent_key( + client=client, portal_base_url=portal_base_url, + access_token=access_token, min_ttl_seconds=min_key_ttl_seconds, + ) + except AuthError as exc: + _oauth_trace( + "mint_error", + sequence_id=sequence_id, + code=exc.code, + ) + # Retry path: access token may be stale server-side despite local checks + latest_refresh_token = state.get("refresh_token") + if ( + exc.code in {"invalid_token", "invalid_grant"} + and isinstance(latest_refresh_token, str) + and latest_refresh_token + ): + _oauth_trace( + "refresh_start", + sequence_id=sequence_id, + reason="mint_retry_after_invalid_token", + refresh_token_fp=_token_fingerprint(latest_refresh_token), + ) + refreshed = _refresh_access_token( + client=client, portal_base_url=portal_base_url, + client_id=client_id, refresh_token=latest_refresh_token, + ) + now = datetime.now(timezone.utc) + access_ttl = _coerce_ttl_seconds(refreshed.get("expires_in")) + state["access_token"] = refreshed["access_token"] + state["refresh_token"] = refreshed.get("refresh_token") or latest_refresh_token + state["token_type"] = refreshed.get("token_type") or state.get("token_type") or "Bearer" + state["scope"] = refreshed.get("scope") or state.get("scope") + refreshed_url = _optional_base_url(refreshed.get("inference_base_url")) + if refreshed_url: + inference_base_url = refreshed_url + state["obtained_at"] = now.isoformat() + state["expires_in"] = access_ttl + state["expires_at"] = datetime.fromtimestamp( + now.timestamp() + access_ttl, tz=timezone.utc + ).isoformat() + access_token = state["access_token"] + refresh_token = state["refresh_token"] + _oauth_trace( + "refresh_success", + sequence_id=sequence_id, + reason="mint_retry_after_invalid_token", + previous_refresh_token_fp=_token_fingerprint(latest_refresh_token), + new_refresh_token_fp=_token_fingerprint(refresh_token), + ) + # Persist retry refresh immediately for crash safety and cross-process visibility. + _persist_state("post_refresh_mint_retry") + + mint_payload = _mint_agent_key( + client=client, portal_base_url=portal_base_url, + access_token=access_token, min_ttl_seconds=min_key_ttl_seconds, + ) + else: + raise + + if mint_payload is not None: + now = datetime.now(timezone.utc) + state["agent_key"] = mint_payload.get("api_key") + state["agent_key_id"] = mint_payload.get("key_id") + state["agent_key_expires_at"] = mint_payload.get("expires_at") + state["agent_key_expires_in"] = mint_payload.get("expires_in") + state["agent_key_reused"] = bool(mint_payload.get("reused", False)) + state["agent_key_obtained_at"] = now.isoformat() + minted_url = _optional_base_url(mint_payload.get("inference_base_url")) + if minted_url: + inference_base_url = minted_url + _oauth_trace( + "mint_success", + sequence_id=sequence_id, + reused=bool(mint_payload.get("reused", False)), + ) + + # Persist routing and TLS metadata for non-interactive refresh/mint + state["portal_base_url"] = portal_base_url + state["inference_base_url"] = inference_base_url + state["client_id"] = client_id + state["tls"] = { + "insecure": verify is False, + "ca_bundle": verify if isinstance(verify, str) else None, + } + + _persist_state("resolve_nous_runtime_credentials_final") + + api_key = state.get("agent_key") + if not isinstance(api_key, str) or not api_key: + raise AuthError("Failed to resolve a Nous inference API key", + provider="nous", code="server_error") + + expires_at = state.get("agent_key_expires_at") + expires_epoch = _parse_iso_timestamp(expires_at) + expires_in = ( + max(0, int(expires_epoch - time.time())) + if expires_epoch is not None + else _coerce_ttl_seconds(state.get("agent_key_expires_in")) + ) + + return { + "provider": "nous", + "base_url": inference_base_url, + "api_key": api_key, + "key_id": state.get("agent_key_id"), + "expires_at": expires_at, + "expires_in": expires_in, + "source": "cache" if used_cached_key else "portal", + } + + +# ============================================================================= +# Status helpers +# ============================================================================= + +def get_nous_auth_status() -> Dict[str, Any]: + """Status snapshot for `hermes status` output. + + Checks the credential pool first (where the dashboard device-code flow + and ``hermes auth`` store credentials), then falls back to the legacy + auth-store provider state. + """ + # Check credential pool first — the dashboard device-code flow saves + # here but may not have written to the auth store yet. + try: + from agent.credential_pool import load_pool + pool = load_pool("nous") + if pool and pool.has_credentials(): + entry = pool.select() + if entry is not None: + access_token = ( + getattr(entry, "access_token", None) + or getattr(entry, "runtime_api_key", "") + ) + if access_token: + return { + "logged_in": True, + "portal_base_url": getattr(entry, "portal_base_url", None) + or getattr(entry, "base_url", None), + "inference_base_url": getattr(entry, "inference_base_url", None) + or getattr(entry, "base_url", None), + "access_token": access_token, + "access_expires_at": getattr(entry, "expires_at", None), + "agent_key_expires_at": getattr(entry, "agent_key_expires_at", None), + "has_refresh_token": bool(getattr(entry, "refresh_token", None)), + } + except Exception: + pass + + # Fall back to auth-store provider state + state = get_provider_auth_state("nous") + if not state: + return { + "logged_in": False, + "portal_base_url": None, + "inference_base_url": None, + "access_expires_at": None, + "agent_key_expires_at": None, + "has_refresh_token": False, + } + return { + "logged_in": bool(state.get("access_token")), + "portal_base_url": state.get("portal_base_url"), + "inference_base_url": state.get("inference_base_url"), + "access_expires_at": state.get("expires_at"), + "agent_key_expires_at": state.get("agent_key_expires_at"), + "has_refresh_token": bool(state.get("refresh_token")), + } + + +def get_codex_auth_status() -> Dict[str, Any]: + """Status snapshot for Codex auth. + + Checks the credential pool first (where `hermes auth` stores credentials), + then falls back to the legacy provider state. + """ + # Check credential pool first — this is where `hermes auth` and + # `hermes model` store device_code tokens. + try: + from agent.credential_pool import load_pool + pool = load_pool("openai-codex") + if pool and pool.has_credentials(): + entry = pool.select() + if entry is not None: + api_key = ( + getattr(entry, "runtime_api_key", None) + or getattr(entry, "access_token", "") + ) + if api_key and not _codex_access_token_is_expiring(api_key, 0): + return { + "logged_in": True, + "auth_store": str(_auth_file_path()), + "last_refresh": getattr(entry, "last_refresh", None), + "auth_mode": "chatgpt", + "source": f"pool:{getattr(entry, 'label', 'unknown')}", + "api_key": api_key, + } + except Exception: + pass + + # Fall back to legacy provider state + try: + creds = resolve_codex_runtime_credentials() + return { + "logged_in": True, + "auth_store": str(_auth_file_path()), + "last_refresh": creds.get("last_refresh"), + "auth_mode": creds.get("auth_mode"), + "source": creds.get("source"), + "api_key": creds.get("api_key"), + } + except AuthError as exc: + return { + "logged_in": False, + "auth_store": str(_auth_file_path()), + "error": str(exc), + } + + +def get_api_key_provider_status(provider_id: str) -> Dict[str, Any]: + """Status snapshot for API-key providers (z.ai, Kimi, MiniMax).""" + pconfig = PROVIDER_REGISTRY.get(provider_id) + if not pconfig or pconfig.auth_type != "api_key": + return {"configured": False} + + api_key = "" + key_source = "" + api_key, key_source = _resolve_api_key_provider_secret(provider_id, pconfig) + + env_url = "" + if pconfig.base_url_env_var: + env_url = os.getenv(pconfig.base_url_env_var, "").strip() + + if provider_id == "kimi-coding": + base_url = _resolve_kimi_base_url(api_key, pconfig.inference_base_url, env_url) + elif env_url: + base_url = env_url + else: + base_url = pconfig.inference_base_url + + return { + "configured": bool(api_key), + "provider": provider_id, + "name": pconfig.name, + "key_source": key_source, + "base_url": base_url, + "logged_in": bool(api_key), # compat with OAuth status shape + } + + +def get_external_process_provider_status(provider_id: str) -> Dict[str, Any]: + """Status snapshot for providers that run a local subprocess.""" + pconfig = PROVIDER_REGISTRY.get(provider_id) + if not pconfig or pconfig.auth_type != "external_process": + return {"configured": False} + + command = ( + os.getenv("HERMES_COPILOT_ACP_COMMAND", "").strip() + or os.getenv("COPILOT_CLI_PATH", "").strip() + or "copilot" + ) + raw_args = os.getenv("HERMES_COPILOT_ACP_ARGS", "").strip() + args = shlex.split(raw_args) if raw_args else ["--acp", "--stdio"] + base_url = os.getenv(pconfig.base_url_env_var, "").strip() if pconfig.base_url_env_var else "" + if not base_url: + base_url = pconfig.inference_base_url + + resolved_command = shutil.which(command) if command else None + return { + "configured": bool(resolved_command or base_url.startswith("acp+tcp://")), + "provider": provider_id, + "name": pconfig.name, + "command": command, + "args": args, + "resolved_command": resolved_command, + "base_url": base_url, + "logged_in": bool(resolved_command or base_url.startswith("acp+tcp://")), + } + + +def get_auth_status(provider_id: Optional[str] = None) -> Dict[str, Any]: + """Generic auth status dispatcher.""" + target = provider_id or get_active_provider() + if target == "nous": + return get_nous_auth_status() + if target == "openai-codex": + return get_codex_auth_status() + if target == "qwen-oauth": + return get_qwen_auth_status() + if target == "copilot-acp": + return get_external_process_provider_status(target) + # API-key providers + pconfig = PROVIDER_REGISTRY.get(target) + if pconfig and pconfig.auth_type == "api_key": + return get_api_key_provider_status(target) + return {"logged_in": False} + + +def resolve_api_key_provider_credentials(provider_id: str) -> Dict[str, Any]: + """Resolve API key and base URL for an API-key provider. + + Returns dict with: provider, api_key, base_url, source. + """ + pconfig = PROVIDER_REGISTRY.get(provider_id) + if not pconfig or pconfig.auth_type != "api_key": + raise AuthError( + f"Provider '{provider_id}' is not an API-key provider.", + provider=provider_id, + code="invalid_provider", + ) + + api_key = "" + key_source = "" + api_key, key_source = _resolve_api_key_provider_secret(provider_id, pconfig) + + env_url = "" + if pconfig.base_url_env_var: + env_url = os.getenv(pconfig.base_url_env_var, "").strip() + + if provider_id == "kimi-coding": + base_url = _resolve_kimi_base_url(api_key, pconfig.inference_base_url, env_url) + elif provider_id == "zai": + base_url = _resolve_zai_base_url(api_key, pconfig.inference_base_url, env_url) + elif env_url: + base_url = env_url.rstrip("/") + else: + base_url = pconfig.inference_base_url + + return { + "provider": provider_id, + "api_key": api_key, + "base_url": base_url.rstrip("/"), + "source": key_source or "default", + } + + +def resolve_external_process_provider_credentials(provider_id: str) -> Dict[str, Any]: + """Resolve runtime details for local subprocess-backed providers.""" + pconfig = PROVIDER_REGISTRY.get(provider_id) + if not pconfig or pconfig.auth_type != "external_process": + raise AuthError( + f"Provider '{provider_id}' is not an external-process provider.", + provider=provider_id, + code="invalid_provider", + ) + + base_url = os.getenv(pconfig.base_url_env_var, "").strip() if pconfig.base_url_env_var else "" + if not base_url: + base_url = pconfig.inference_base_url + + command = ( + os.getenv("HERMES_COPILOT_ACP_COMMAND", "").strip() + or os.getenv("COPILOT_CLI_PATH", "").strip() + or "copilot" + ) + raw_args = os.getenv("HERMES_COPILOT_ACP_ARGS", "").strip() + args = shlex.split(raw_args) if raw_args else ["--acp", "--stdio"] + resolved_command = shutil.which(command) if command else None + if not resolved_command and not base_url.startswith("acp+tcp://"): + raise AuthError( + f"Could not find the Copilot CLI command '{command}'. " + "Install GitHub Copilot CLI or set HERMES_COPILOT_ACP_COMMAND/COPILOT_CLI_PATH.", + provider=provider_id, + code="missing_copilot_cli", + ) + + return { + "provider": provider_id, + "api_key": "copilot-acp", + "base_url": base_url.rstrip("/"), + "command": resolved_command or command, + "args": args, + "source": "process", + } + + +# ============================================================================= +# CLI Commands — login / logout +# ============================================================================= + +def _update_config_for_provider( + provider_id: str, + inference_base_url: str, + default_model: Optional[str] = None, +) -> Path: + """Update config.yaml and auth.json to reflect the active provider. + + When *default_model* is provided the function also writes it as the + ``model.default`` value. This prevents a race condition where the + gateway (which re-reads config per-message) picks up the new provider + before the caller has finished model selection, resulting in a + mismatched model/provider (e.g. ``anthropic/claude-opus-4.6`` sent to + MiniMax's API). + """ + # Set active_provider in auth.json so auto-resolution picks this provider + with _auth_store_lock(): + auth_store = _load_auth_store() + auth_store["active_provider"] = provider_id + _save_auth_store(auth_store) + + # Update config.yaml model section + config_path = get_config_path() + config_path.parent.mkdir(parents=True, exist_ok=True) + + config = read_raw_config() + + current_model = config.get("model") + if isinstance(current_model, dict): + model_cfg = dict(current_model) + elif isinstance(current_model, str) and current_model.strip(): + model_cfg = {"default": current_model.strip()} + else: + model_cfg = {} + + model_cfg["provider"] = provider_id + if inference_base_url and inference_base_url.strip(): + model_cfg["base_url"] = inference_base_url.rstrip("/") + else: + # Clear stale base_url to prevent contamination when switching providers + model_cfg.pop("base_url", None) + + # When switching to a non-OpenRouter provider, ensure model.default is + # valid for the new provider. An OpenRouter-formatted name like + # "anthropic/claude-opus-4.6" will fail on direct-API providers. + if default_model: + cur_default = model_cfg.get("default", "") + if not cur_default or "/" in cur_default: + model_cfg["default"] = default_model + + config["model"] = model_cfg + + config_path.write_text(yaml.safe_dump(config, sort_keys=False)) + return config_path + + +def _reset_config_provider() -> Path: + """Reset config.yaml provider back to auto after logout.""" + config_path = get_config_path() + if not config_path.exists(): + return config_path + + config = read_raw_config() + if not config: + return config_path + + model = config.get("model") + if isinstance(model, dict): + model["provider"] = "auto" + if "base_url" in model: + model["base_url"] = OPENROUTER_BASE_URL + config_path.write_text(yaml.safe_dump(config, sort_keys=False)) + return config_path + + +def _prompt_model_selection( + model_ids: List[str], + current_model: str = "", + pricing: Optional[Dict[str, Dict[str, str]]] = None, + unavailable_models: Optional[List[str]] = None, + portal_url: str = "", +) -> Optional[str]: + """Interactive model selection. Puts current_model first with a marker. Returns chosen model ID or None. + + If *pricing* is provided (``{model_id: {prompt, completion}}``), a compact + price indicator is shown next to each model in aligned columns. + + If *unavailable_models* is provided, those models are shown grayed out + and unselectable, with an upgrade link to *portal_url*. + """ + from hermes_cli.models import _format_price_per_mtok + + _unavailable = unavailable_models or [] + + # Reorder: current model first, then the rest (deduplicated) + ordered = [] + if current_model and current_model in model_ids: + ordered.append(current_model) + for mid in model_ids: + if mid not in ordered: + ordered.append(mid) + + # All models for column-width computation (selectable + unavailable) + all_models = list(ordered) + list(_unavailable) + + # Column-aligned labels when pricing is available + has_pricing = bool(pricing and any(pricing.get(m) for m in all_models)) + name_col = max((len(m) for m in all_models), default=0) + 2 if has_pricing else 0 + + # Pre-compute formatted prices and dynamic column widths + _price_cache: dict[str, tuple[str, str, str]] = {} + price_col = 3 # minimum width + cache_col = 0 # only set if any model has cache pricing + has_cache = False + if has_pricing: + for mid in all_models: + p = pricing.get(mid) # type: ignore[union-attr] + if p: + inp = _format_price_per_mtok(p.get("prompt", "")) + out = _format_price_per_mtok(p.get("completion", "")) + cache_read = p.get("input_cache_read", "") + cache = _format_price_per_mtok(cache_read) if cache_read else "" + if cache: + has_cache = True + else: + inp, out, cache = "", "", "" + _price_cache[mid] = (inp, out, cache) + price_col = max(price_col, len(inp), len(out)) + cache_col = max(cache_col, len(cache)) + if has_cache: + cache_col = max(cache_col, 5) # minimum: "Cache" header + + def _label(mid): + if has_pricing: + inp, out, cache = _price_cache.get(mid, ("", "", "")) + price_part = f" {inp:>{price_col}} {out:>{price_col}}" + if has_cache: + price_part += f" {cache:>{cache_col}}" + base = f"{mid:<{name_col}}{price_part}" + else: + base = mid + if mid == current_model: + base += " ← currently in use" + return base + + # Default cursor on the current model (index 0 if it was reordered to top) + default_idx = 0 + + # Build a pricing header hint for the menu title + menu_title = "Select default model:" + if has_pricing: + # Align the header with the model column. + # Each choice is " {label}" (2 spaces) and simple_term_menu prepends + # a 3-char cursor region ("-> " or " "), so content starts at col 5. + pad = " " * 5 + header = f"\n{pad}{'':>{name_col}} {'In':>{price_col}} {'Out':>{price_col}}" + if has_cache: + header += f" {'Cache':>{cache_col}}" + menu_title += header + " /Mtok" + + # ANSI escape for dim text + _DIM = "\033[2m" + _RESET = "\033[0m" + + # Try arrow-key menu first, fall back to number input + try: + from simple_term_menu import TerminalMenu + + choices = [f" {_label(mid)}" for mid in ordered] + choices.append(" Enter custom model name") + choices.append(" Skip (keep current)") + + # Print the unavailable block BEFORE the menu via regular print(). + # simple_term_menu pads title lines to terminal width (causes wrapping), + # so we keep the title minimal and use stdout for the static block. + # clear_screen=False means our printed output stays visible above. + _upgrade_url = (portal_url or DEFAULT_NOUS_PORTAL_URL).rstrip("/") + if _unavailable: + print(menu_title) + print() + for mid in _unavailable: + print(f"{_DIM} {_label(mid)}{_RESET}") + print() + print(f"{_DIM} ── Upgrade at {_upgrade_url} for paid models ──{_RESET}") + print() + effective_title = "Available free models:" + else: + effective_title = menu_title + + menu = TerminalMenu( + choices, + cursor_index=default_idx, + menu_cursor="-> ", + menu_cursor_style=("fg_green", "bold"), + menu_highlight_style=("fg_green",), + cycle_cursor=True, + clear_screen=False, + title=effective_title, + ) + idx = menu.show() + from hermes_cli.curses_ui import flush_stdin + flush_stdin() + if idx is None: + return None + print() + if idx < len(ordered): + return ordered[idx] + elif idx == len(ordered): + custom = input("Enter model name: ").strip() + return custom if custom else None + return None + except (ImportError, NotImplementedError, OSError, subprocess.SubprocessError): + pass + + # Fallback: numbered list + print(menu_title) + num_width = len(str(len(ordered) + 2)) + for i, mid in enumerate(ordered, 1): + print(f" {i:>{num_width}}. {_label(mid)}") + n = len(ordered) + print(f" {n + 1:>{num_width}}. Enter custom model name") + print(f" {n + 2:>{num_width}}. Skip (keep current)") + + if _unavailable: + _upgrade_url = (portal_url or DEFAULT_NOUS_PORTAL_URL).rstrip("/") + print() + print(f" {_DIM}── Unavailable models (requires paid tier — upgrade at {_upgrade_url}) ──{_RESET}") + for mid in _unavailable: + print(f" {'':>{num_width}} {_DIM}{_label(mid)}{_RESET}") + print() + + while True: + try: + choice = input(f"Choice [1-{n + 2}] (default: skip): ").strip() + if not choice: + return None + idx = int(choice) + if 1 <= idx <= n: + return ordered[idx - 1] + elif idx == n + 1: + custom = input("Enter model name: ").strip() + return custom if custom else None + elif idx == n + 2: + return None + print(f"Please enter 1-{n + 2}") + except ValueError: + print("Please enter a number") + except (KeyboardInterrupt, EOFError): + return None + + +def _save_model_choice(model_id: str) -> None: + """Save the selected model to config.yaml (single source of truth). + + The model is stored in config.yaml only — NOT in .env. This avoids + conflicts in multi-agent setups where env vars would stomp each other. + """ + from hermes_cli.config import save_config, load_config + + config = load_config() + # Always use dict format so provider/base_url can be stored alongside + if isinstance(config.get("model"), dict): + config["model"]["default"] = model_id + else: + config["model"] = {"default": model_id} + save_config(config) + + +def login_command(args) -> None: + """Deprecated: use 'hermes model' or 'hermes setup' instead.""" + print("The 'hermes login' command has been removed.") + print("Use 'hermes auth' to manage credentials,") + print("'hermes model' to select a provider, or 'hermes setup' for full setup.") + raise SystemExit(0) + + +def _login_openai_codex(args, pconfig: ProviderConfig) -> None: + """OpenAI Codex login via device code flow. Tokens stored in ~/.hermes/auth.json.""" + + # Check for existing Hermes-owned credentials + try: + existing = resolve_codex_runtime_credentials() + # Verify the resolved token is actually usable (not expired). + # resolve_codex_runtime_credentials attempts refresh, so if we get + # here the token should be valid — but double-check before telling + # the user "Login successful!". + _resolved_key = existing.get("api_key", "") + if isinstance(_resolved_key, str) and _resolved_key and not _codex_access_token_is_expiring(_resolved_key, 60): + print("Existing Codex credentials found in Hermes auth store.") + try: + reuse = input("Use existing credentials? [Y/n]: ").strip().lower() + except (EOFError, KeyboardInterrupt): + reuse = "y" + if reuse in ("", "y", "yes"): + config_path = _update_config_for_provider("openai-codex", existing.get("base_url", DEFAULT_CODEX_BASE_URL)) + print() + print("Login successful!") + print(f" Config updated: {config_path} (model.provider=openai-codex)") + return + else: + print("Existing Codex credentials are expired. Starting fresh login...") + except AuthError: + pass + + # Check for existing Codex CLI tokens we can import + cli_tokens = _import_codex_cli_tokens() + if cli_tokens: + print("Found existing Codex CLI credentials at ~/.codex/auth.json") + print("Hermes will create its own session to avoid conflicts with Codex CLI / VS Code.") + try: + do_import = input("Import these credentials? (a separate login is recommended) [y/N]: ").strip().lower() + except (EOFError, KeyboardInterrupt): + do_import = "n" + if do_import in ("y", "yes"): + _save_codex_tokens(cli_tokens) + base_url = os.getenv("HERMES_CODEX_BASE_URL", "").strip().rstrip("/") or DEFAULT_CODEX_BASE_URL + config_path = _update_config_for_provider("openai-codex", base_url) + print() + print("Credentials imported. Note: if Codex CLI refreshes its token,") + print("Hermes will keep working independently with its own session.") + print(f" Config updated: {config_path} (model.provider=openai-codex)") + return + + # Run a fresh device code flow — Hermes gets its own OAuth session + print() + print("Signing in to OpenAI Codex...") + print("(Hermes creates its own session — won't affect Codex CLI or VS Code)") + print() + + creds = _codex_device_code_login() + + # Save tokens to Hermes auth store + _save_codex_tokens(creds["tokens"], creds.get("last_refresh")) + config_path = _update_config_for_provider("openai-codex", creds.get("base_url", DEFAULT_CODEX_BASE_URL)) + print() + print("Login successful!") + from hermes_constants import display_hermes_home as _dhh + print(f" Auth state: {_dhh()}/auth.json") + print(f" Config updated: {config_path} (model.provider=openai-codex)") + + +def _codex_device_code_login() -> Dict[str, Any]: + """Run the OpenAI device code login flow and return credentials dict.""" + import time as _time + + issuer = "https://auth.openai.com" + client_id = CODEX_OAUTH_CLIENT_ID + + # Step 1: Request device code + try: + with httpx.Client(timeout=httpx.Timeout(15.0)) as client: + resp = client.post( + f"{issuer}/api/accounts/deviceauth/usercode", + json={"client_id": client_id}, + headers={"Content-Type": "application/json"}, + ) + except Exception as exc: + raise AuthError( + f"Failed to request device code: {exc}", + provider="openai-codex", code="device_code_request_failed", + ) + + if resp.status_code != 200: + raise AuthError( + f"Device code request returned status {resp.status_code}.", + provider="openai-codex", code="device_code_request_error", + ) + + device_data = resp.json() + user_code = device_data.get("user_code", "") + device_auth_id = device_data.get("device_auth_id", "") + poll_interval = max(3, int(device_data.get("interval", "5"))) + + if not user_code or not device_auth_id: + raise AuthError( + "Device code response missing required fields.", + provider="openai-codex", code="device_code_incomplete", + ) + + # Step 2: Show user the code + print("To continue, follow these steps:\n") + print(" 1. Open this URL in your browser:") + print(f" \033[94m{issuer}/codex/device\033[0m\n") + print(" 2. Enter this code:") + print(f" \033[94m{user_code}\033[0m\n") + print("Waiting for sign-in... (press Ctrl+C to cancel)") + + # Step 3: Poll for authorization code + max_wait = 15 * 60 # 15 minutes + start = _time.monotonic() + code_resp = None + + try: + with httpx.Client(timeout=httpx.Timeout(15.0)) as client: + while _time.monotonic() - start < max_wait: + _time.sleep(poll_interval) + poll_resp = client.post( + f"{issuer}/api/accounts/deviceauth/token", + json={"device_auth_id": device_auth_id, "user_code": user_code}, + headers={"Content-Type": "application/json"}, + ) + + if poll_resp.status_code == 200: + code_resp = poll_resp.json() + break + elif poll_resp.status_code in (403, 404): + continue # User hasn't completed login yet + else: + raise AuthError( + f"Device auth polling returned status {poll_resp.status_code}.", + provider="openai-codex", code="device_code_poll_error", + ) + except KeyboardInterrupt: + print("\nLogin cancelled.") + raise SystemExit(130) + + if code_resp is None: + raise AuthError( + "Login timed out after 15 minutes.", + provider="openai-codex", code="device_code_timeout", + ) + + # Step 4: Exchange authorization code for tokens + authorization_code = code_resp.get("authorization_code", "") + code_verifier = code_resp.get("code_verifier", "") + redirect_uri = f"{issuer}/deviceauth/callback" + + if not authorization_code or not code_verifier: + raise AuthError( + "Device auth response missing authorization_code or code_verifier.", + provider="openai-codex", code="device_code_incomplete_exchange", + ) + + try: + with httpx.Client(timeout=httpx.Timeout(15.0)) as client: + token_resp = client.post( + CODEX_OAUTH_TOKEN_URL, + data={ + "grant_type": "authorization_code", + "code": authorization_code, + "redirect_uri": redirect_uri, + "client_id": client_id, + "code_verifier": code_verifier, + }, + headers={"Content-Type": "application/x-www-form-urlencoded"}, + ) + except Exception as exc: + raise AuthError( + f"Token exchange failed: {exc}", + provider="openai-codex", code="token_exchange_failed", + ) + + if token_resp.status_code != 200: + raise AuthError( + f"Token exchange returned status {token_resp.status_code}.", + provider="openai-codex", code="token_exchange_error", + ) + + tokens = token_resp.json() + access_token = tokens.get("access_token", "") + refresh_token = tokens.get("refresh_token", "") + + if not access_token: + raise AuthError( + "Token exchange did not return an access_token.", + provider="openai-codex", code="token_exchange_no_access_token", + ) + + # Return tokens for the caller to persist (no longer writes to ~/.codex/) + base_url = ( + os.getenv("HERMES_CODEX_BASE_URL", "").strip().rstrip("/") + or DEFAULT_CODEX_BASE_URL + ) + + return { + "tokens": { + "access_token": access_token, + "refresh_token": refresh_token, + }, + "base_url": base_url, + "last_refresh": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"), + "auth_mode": "chatgpt", + "source": "device-code", + } + + +def _nous_device_code_login( + *, + portal_base_url: Optional[str] = None, + inference_base_url: Optional[str] = None, + client_id: Optional[str] = None, + scope: Optional[str] = None, + open_browser: bool = True, + timeout_seconds: float = 15.0, + insecure: bool = False, + ca_bundle: Optional[str] = None, + min_key_ttl_seconds: int = 5 * 60, +) -> Dict[str, Any]: + """Run the Nous device-code flow and return full OAuth state without persisting.""" + pconfig = PROVIDER_REGISTRY["nous"] + portal_base_url = ( + portal_base_url + or os.getenv("HERMES_PORTAL_BASE_URL") + or os.getenv("NOUS_PORTAL_BASE_URL") + or pconfig.portal_base_url + ).rstrip("/") + requested_inference_url = ( + inference_base_url + or os.getenv("NOUS_INFERENCE_BASE_URL") + or pconfig.inference_base_url + ).rstrip("/") + client_id = client_id or pconfig.client_id + scope = scope or pconfig.scope + timeout = httpx.Timeout(timeout_seconds) + verify: bool | str = False if insecure else (ca_bundle if ca_bundle else True) + + if _is_remote_session(): + open_browser = False + + print(f"Starting Hermes login via {pconfig.name}...") + print(f"Portal: {portal_base_url}") + if insecure: + print("TLS verification: disabled (--insecure)") + elif ca_bundle: + print(f"TLS verification: custom CA bundle ({ca_bundle})") + + with httpx.Client(timeout=timeout, headers={"Accept": "application/json"}, verify=verify) as client: + device_data = _request_device_code( + client=client, + portal_base_url=portal_base_url, + client_id=client_id, + scope=scope, + ) + + verification_url = str(device_data["verification_uri_complete"]) + user_code = str(device_data["user_code"]) + expires_in = int(device_data["expires_in"]) + interval = int(device_data["interval"]) + + print() + print("To continue:") + print(f" 1. Open: {verification_url}") + print(f" 2. If prompted, enter code: {user_code}") + + if open_browser: + opened = webbrowser.open(verification_url) + if opened: + print(" (Opened browser for verification)") + else: + print(" Could not open browser automatically — use the URL above.") + + effective_interval = max(1, min(interval, DEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS)) + print(f"Waiting for approval (polling every {effective_interval}s)...") + + token_data = _poll_for_token( + client=client, + portal_base_url=portal_base_url, + client_id=client_id, + device_code=str(device_data["device_code"]), + expires_in=expires_in, + poll_interval=interval, + ) + + now = datetime.now(timezone.utc) + token_expires_in = _coerce_ttl_seconds(token_data.get("expires_in", 0)) + expires_at = now.timestamp() + token_expires_in + resolved_inference_url = ( + _optional_base_url(token_data.get("inference_base_url")) + or requested_inference_url + ) + if resolved_inference_url != requested_inference_url: + print(f"Using portal-provided inference URL: {resolved_inference_url}") + + auth_state = { + "portal_base_url": portal_base_url, + "inference_base_url": resolved_inference_url, + "client_id": client_id, + "scope": token_data.get("scope") or scope, + "token_type": token_data.get("token_type", "Bearer"), + "access_token": token_data["access_token"], + "refresh_token": token_data.get("refresh_token"), + "obtained_at": now.isoformat(), + "expires_at": datetime.fromtimestamp(expires_at, tz=timezone.utc).isoformat(), + "expires_in": token_expires_in, + "tls": { + "insecure": verify is False, + "ca_bundle": verify if isinstance(verify, str) else None, + }, + "agent_key": None, + "agent_key_id": None, + "agent_key_expires_at": None, + "agent_key_expires_in": None, + "agent_key_reused": None, + "agent_key_obtained_at": None, + } + try: + return refresh_nous_oauth_from_state( + auth_state, + min_key_ttl_seconds=min_key_ttl_seconds, + timeout_seconds=timeout_seconds, + force_refresh=False, + force_mint=True, + ) + except AuthError as exc: + if exc.code == "subscription_required": + portal_url = auth_state.get( + "portal_base_url", DEFAULT_NOUS_PORTAL_URL + ).rstrip("/") + print() + print("Your Nous Portal account does not have an active subscription.") + print(f" Subscribe here: {portal_url}/billing") + print() + print("After subscribing, run `hermes model` again to finish setup.") + raise SystemExit(1) + raise + + +def _login_nous(args, pconfig: ProviderConfig) -> None: + """Nous Portal device authorization flow.""" + timeout_seconds = getattr(args, "timeout", None) or 15.0 + insecure = bool(getattr(args, "insecure", False)) + ca_bundle = ( + getattr(args, "ca_bundle", None) + or os.getenv("HERMES_CA_BUNDLE") + or os.getenv("SSL_CERT_FILE") + ) + + try: + auth_state = _nous_device_code_login( + portal_base_url=getattr(args, "portal_url", None), + inference_base_url=getattr(args, "inference_url", None), + client_id=getattr(args, "client_id", None) or pconfig.client_id, + scope=getattr(args, "scope", None) or pconfig.scope, + open_browser=not getattr(args, "no_browser", False), + timeout_seconds=timeout_seconds, + insecure=insecure, + ca_bundle=ca_bundle, + min_key_ttl_seconds=5 * 60, + ) + + inference_base_url = auth_state["inference_base_url"] + + with _auth_store_lock(): + auth_store = _load_auth_store() + _save_provider_state(auth_store, "nous", auth_state) + saved_to = _save_auth_store(auth_store) + + print() + print("Login successful!") + print(f" Auth state: {saved_to}") + + # Resolve model BEFORE writing provider to config.yaml so we never + # leave the config in a half-updated state (provider=nous but model + # still set to the previous provider's model, e.g. opus from + # OpenRouter). The auth.json active_provider was already set above. + selected_model = None + try: + runtime_key = auth_state.get("agent_key") or auth_state.get("access_token") + if not isinstance(runtime_key, str) or not runtime_key: + raise AuthError( + "No runtime API key available to fetch models", + provider="nous", + code="invalid_token", + ) + + from hermes_cli.models import ( + _PROVIDER_MODELS, get_pricing_for_provider, filter_nous_free_models, + check_nous_free_tier, partition_nous_models_by_tier, + ) + model_ids = _PROVIDER_MODELS.get("nous", []) + + print() + unavailable_models: list = [] + if model_ids: + pricing = get_pricing_for_provider("nous") + model_ids = filter_nous_free_models(model_ids, pricing) + free_tier = check_nous_free_tier() + if free_tier: + model_ids, unavailable_models = partition_nous_models_by_tier( + model_ids, pricing, free_tier=True, + ) + _portal = auth_state.get("portal_base_url", "") + if model_ids: + print(f"Showing {len(model_ids)} curated models — use \"Enter custom model name\" for others.") + selected_model = _prompt_model_selection( + model_ids, pricing=pricing, + unavailable_models=unavailable_models, + portal_url=_portal, + ) + elif unavailable_models: + _url = (_portal or DEFAULT_NOUS_PORTAL_URL).rstrip("/") + print("No free models currently available.") + print(f"Upgrade at {_url} to access paid models.") + else: + print("No curated models available for Nous Portal.") + except Exception as exc: + message = format_auth_error(exc) if isinstance(exc, AuthError) else str(exc) + print() + print(f"Login succeeded, but could not fetch available models. Reason: {message}") + + # Write provider + model atomically so config is never mismatched. + config_path = _update_config_for_provider( + "nous", inference_base_url, default_model=selected_model, + ) + if selected_model: + _save_model_choice(selected_model) + print(f"Default model set to: {selected_model}") + print(f" Config updated: {config_path} (model.provider=nous)") + + except KeyboardInterrupt: + print("\nLogin cancelled.") + raise SystemExit(130) + except Exception as exc: + print(f"Login failed: {exc}") + raise SystemExit(1) + + +def logout_command(args) -> None: + """Clear auth state for a provider.""" + provider_id = getattr(args, "provider", None) + + if provider_id and provider_id not in PROVIDER_REGISTRY: + print(f"Unknown provider: {provider_id}") + raise SystemExit(1) + + active = get_active_provider() + target = provider_id or active + + if not target: + print("No provider is currently logged in.") + return + + provider_name = PROVIDER_REGISTRY[target].name if target in PROVIDER_REGISTRY else target + + if clear_provider_auth(target): + _reset_config_provider() + print(f"Logged out of {provider_name}.") + if os.getenv("OPENROUTER_API_KEY"): + print("Hermes will use OpenRouter for inference.") + else: + print("Run `hermes model` or configure an API key to use Hermes.") + else: + print(f"No auth state found for {provider_name}.") diff --git a/mindcli/_vendor/hermes_cli/auth_commands.py b/mindcli/_vendor/hermes_cli/auth_commands.py new file mode 100644 index 0000000..c1cf0ff --- /dev/null +++ b/mindcli/_vendor/hermes_cli/auth_commands.py @@ -0,0 +1,541 @@ +"""Credential-pool auth subcommands.""" + +from __future__ import annotations + +from getpass import getpass +import math +import time +from types import SimpleNamespace +import uuid + +from agent.credential_pool import ( + AUTH_TYPE_API_KEY, + AUTH_TYPE_OAUTH, + CUSTOM_POOL_PREFIX, + SOURCE_MANUAL, + STATUS_EXHAUSTED, + STRATEGY_FILL_FIRST, + STRATEGY_ROUND_ROBIN, + STRATEGY_RANDOM, + STRATEGY_LEAST_USED, + PooledCredential, + _exhausted_until, + _normalize_custom_pool_name, + get_pool_strategy, + label_from_token, + list_custom_pool_providers, + load_pool, +) +import hermes_cli.auth as auth_mod +from hermes_cli.auth import PROVIDER_REGISTRY +from hermes_constants import OPENROUTER_BASE_URL + + +# Providers that support OAuth login in addition to API keys. +_OAUTH_CAPABLE_PROVIDERS = {"anthropic", "nous", "openai-codex", "qwen-oauth"} + + +def _get_custom_provider_names() -> list: + """Return list of (display_name, pool_key, provider_key) tuples.""" + try: + from hermes_cli.config import get_compatible_custom_providers, load_config + + config = load_config() + except Exception: + return [] + result = [] + for entry in get_compatible_custom_providers(config): + if not isinstance(entry, dict): + continue + name = entry.get("name") + if not isinstance(name, str) or not name.strip(): + continue + pool_key = f"{CUSTOM_POOL_PREFIX}{_normalize_custom_pool_name(name)}" + provider_key = str(entry.get("provider_key", "") or "").strip() + result.append((name.strip(), pool_key, provider_key)) + return result + + +def _resolve_custom_provider_input(raw: str) -> str | None: + """If raw input matches a custom_providers entry name (case-insensitive), return its pool key.""" + normalized = (raw or "").strip().lower().replace(" ", "-") + if not normalized: + return None + # Direct match on 'custom:name' format + if normalized.startswith(CUSTOM_POOL_PREFIX): + return normalized + for display_name, pool_key, provider_key in _get_custom_provider_names(): + if _normalize_custom_pool_name(display_name) == normalized: + return pool_key + if provider_key and provider_key.strip().lower() == normalized: + return pool_key + return None + + +def _normalize_provider(provider: str) -> str: + normalized = (provider or "").strip().lower() + if normalized in {"or", "open-router"}: + return "openrouter" + # Check if it matches a custom provider name + custom_key = _resolve_custom_provider_input(normalized) + if custom_key: + return custom_key + return normalized + + +def _provider_base_url(provider: str) -> str: + if provider == "openrouter": + return OPENROUTER_BASE_URL + if provider.startswith(CUSTOM_POOL_PREFIX): + from agent.credential_pool import _get_custom_provider_config + + cp_config = _get_custom_provider_config(provider) + if cp_config: + return str(cp_config.get("base_url") or "").strip() + return "" + pconfig = PROVIDER_REGISTRY.get(provider) + return pconfig.inference_base_url if pconfig else "" + + +def _oauth_default_label(provider: str, count: int) -> str: + return f"{provider}-oauth-{count}" + + +def _api_key_default_label(count: int) -> str: + return f"api-key-{count}" + + +def _display_source(source: str) -> str: + return source.split(":", 1)[1] if source.startswith("manual:") else source + + +def _format_exhausted_status(entry) -> str: + if entry.last_status != STATUS_EXHAUSTED: + return "" + reason = getattr(entry, "last_error_reason", None) + reason_text = f" {reason}" if isinstance(reason, str) and reason.strip() else "" + code = f" ({entry.last_error_code})" if entry.last_error_code else "" + exhausted_until = _exhausted_until(entry) + if exhausted_until is None: + return f" exhausted{reason_text}{code}" + remaining = max(0, int(math.ceil(exhausted_until - time.time()))) + if remaining <= 0: + return f" exhausted{reason_text}{code} (ready to retry)" + minutes, seconds = divmod(remaining, 60) + hours, minutes = divmod(minutes, 60) + days, hours = divmod(hours, 24) + if days: + wait = f"{days}d {hours}h" + elif hours: + wait = f"{hours}h {minutes}m" + elif minutes: + wait = f"{minutes}m {seconds}s" + else: + wait = f"{seconds}s" + return f" exhausted{reason_text}{code} ({wait} left)" + + +def auth_add_command(args) -> None: + provider = _normalize_provider(getattr(args, "provider", "")) + if provider not in PROVIDER_REGISTRY and provider != "openrouter" and not provider.startswith(CUSTOM_POOL_PREFIX): + raise SystemExit(f"Unknown provider: {provider}") + + requested_type = str(getattr(args, "auth_type", "") or "").strip().lower() + if requested_type in {AUTH_TYPE_API_KEY, "api-key"}: + requested_type = AUTH_TYPE_API_KEY + if not requested_type: + if provider.startswith(CUSTOM_POOL_PREFIX): + requested_type = AUTH_TYPE_API_KEY + else: + requested_type = AUTH_TYPE_OAUTH if provider in {"anthropic", "nous", "openai-codex", "qwen-oauth"} else AUTH_TYPE_API_KEY + + pool = load_pool(provider) + + if requested_type == AUTH_TYPE_API_KEY: + token = (getattr(args, "api_key", None) or "").strip() + if not token: + token = getpass("Paste your API key: ").strip() + if not token: + raise SystemExit("No API key provided.") + default_label = _api_key_default_label(len(pool.entries()) + 1) + label = (getattr(args, "label", None) or "").strip() + if not label: + label = input(f"Label (optional, default: {default_label}): ").strip() or default_label + entry = PooledCredential( + provider=provider, + id=uuid.uuid4().hex[:6], + label=label, + auth_type=AUTH_TYPE_API_KEY, + priority=0, + source=SOURCE_MANUAL, + access_token=token, + base_url=_provider_base_url(provider), + ) + pool.add_entry(entry) + print(f'Added {provider} credential #{len(pool.entries())}: "{label}"') + return + + if provider == "anthropic": + from agent import anthropic_adapter as anthropic_mod + + creds = anthropic_mod.run_hermes_oauth_login_pure() + if not creds: + raise SystemExit("Anthropic OAuth login did not return credentials.") + label = (getattr(args, "label", None) or "").strip() or label_from_token( + creds["access_token"], + _oauth_default_label(provider, len(pool.entries()) + 1), + ) + entry = PooledCredential( + provider=provider, + id=uuid.uuid4().hex[:6], + label=label, + auth_type=AUTH_TYPE_OAUTH, + priority=0, + source=f"{SOURCE_MANUAL}:hermes_pkce", + access_token=creds["access_token"], + refresh_token=creds.get("refresh_token"), + expires_at_ms=creds.get("expires_at_ms"), + base_url=_provider_base_url(provider), + ) + pool.add_entry(entry) + print(f'Added {provider} OAuth credential #{len(pool.entries())}: "{entry.label}"') + return + + if provider == "nous": + creds = auth_mod._nous_device_code_login( + portal_base_url=getattr(args, "portal_url", None), + inference_base_url=getattr(args, "inference_url", None), + client_id=getattr(args, "client_id", None), + scope=getattr(args, "scope", None), + open_browser=not getattr(args, "no_browser", False), + timeout_seconds=getattr(args, "timeout", None) or 15.0, + insecure=bool(getattr(args, "insecure", False)), + ca_bundle=getattr(args, "ca_bundle", None), + min_key_ttl_seconds=max(60, int(getattr(args, "min_key_ttl_seconds", 5 * 60))), + ) + label = (getattr(args, "label", None) or "").strip() or label_from_token( + creds.get("access_token", ""), + _oauth_default_label(provider, len(pool.entries()) + 1), + ) + entry = PooledCredential.from_dict(provider, { + **creds, + "label": label, + "auth_type": AUTH_TYPE_OAUTH, + "source": f"{SOURCE_MANUAL}:device_code", + "base_url": creds.get("inference_base_url"), + }) + pool.add_entry(entry) + print(f'Added {provider} OAuth credential #{len(pool.entries())}: "{entry.label}"') + return + + if provider == "openai-codex": + creds = auth_mod._codex_device_code_login() + label = (getattr(args, "label", None) or "").strip() or label_from_token( + creds["tokens"]["access_token"], + _oauth_default_label(provider, len(pool.entries()) + 1), + ) + entry = PooledCredential( + provider=provider, + id=uuid.uuid4().hex[:6], + label=label, + auth_type=AUTH_TYPE_OAUTH, + priority=0, + source=f"{SOURCE_MANUAL}:device_code", + access_token=creds["tokens"]["access_token"], + refresh_token=creds["tokens"].get("refresh_token"), + base_url=creds.get("base_url"), + last_refresh=creds.get("last_refresh"), + ) + pool.add_entry(entry) + print(f'Added {provider} OAuth credential #{len(pool.entries())}: "{entry.label}"') + return + + if provider == "qwen-oauth": + creds = auth_mod.resolve_qwen_runtime_credentials(refresh_if_expiring=False) + label = (getattr(args, "label", None) or "").strip() or label_from_token( + creds["api_key"], + _oauth_default_label(provider, len(pool.entries()) + 1), + ) + entry = PooledCredential( + provider=provider, + id=uuid.uuid4().hex[:6], + label=label, + auth_type=AUTH_TYPE_OAUTH, + priority=0, + source=f"{SOURCE_MANUAL}:qwen_cli", + access_token=creds["api_key"], + base_url=creds.get("base_url"), + ) + pool.add_entry(entry) + print(f'Added {provider} OAuth credential #{len(pool.entries())}: "{entry.label}"') + return + + raise SystemExit(f"`hermes auth add {provider}` is not implemented for auth type {requested_type} yet.") + + +def auth_list_command(args) -> None: + provider_filter = _normalize_provider(getattr(args, "provider", "") or "") + if provider_filter: + providers = [provider_filter] + else: + providers = sorted({ + *PROVIDER_REGISTRY.keys(), + "openrouter", + *list_custom_pool_providers(), + }) + for provider in providers: + pool = load_pool(provider) + entries = pool.entries() + if not entries: + continue + current = pool.peek() + print(f"{provider} ({len(entries)} credentials):") + for idx, entry in enumerate(entries, start=1): + marker = " " + if current is not None and entry.id == current.id: + marker = "← " + status = _format_exhausted_status(entry) + source = _display_source(entry.source) + print(f" #{idx} {entry.label:<20} {entry.auth_type:<7} {source}{status} {marker}".rstrip()) + print() + + +def auth_remove_command(args) -> None: + provider = _normalize_provider(getattr(args, "provider", "")) + target = getattr(args, "target", None) + if target is None: + target = getattr(args, "index", None) + pool = load_pool(provider) + index, matched, error = pool.resolve_target(target) + if matched is None or index is None: + raise SystemExit(f"{error} Provider: {provider}.") + removed = pool.remove_index(index) + if removed is None: + raise SystemExit(f'No credential matching "{target}" for provider {provider}.') + print(f"Removed {provider} credential #{index} ({removed.label})") + + # If this was an env-seeded credential, also clear the env var from .env + # so it doesn't get re-seeded on the next load_pool() call. + if removed.source.startswith("env:"): + env_var = removed.source[len("env:"):] + if env_var: + from hermes_cli.config import remove_env_value + cleared = remove_env_value(env_var) + if cleared: + print(f"Cleared {env_var} from .env") + + # If this was a singleton-seeded credential (OAuth device_code, hermes_pkce), + # clear the underlying auth store / credential file so it doesn't get + # re-seeded on the next load_pool() call. + elif removed.source == "device_code" and provider in ("openai-codex", "nous"): + from hermes_cli.auth import ( + _load_auth_store, _save_auth_store, _auth_store_lock, + ) + with _auth_store_lock(): + auth_store = _load_auth_store() + providers_dict = auth_store.get("providers") + if isinstance(providers_dict, dict) and provider in providers_dict: + del providers_dict[provider] + _save_auth_store(auth_store) + print(f"Cleared {provider} OAuth tokens from auth store") + + elif removed.source == "hermes_pkce" and provider == "anthropic": + from hermes_constants import get_hermes_home + oauth_file = get_hermes_home() / ".anthropic_oauth.json" + if oauth_file.exists(): + oauth_file.unlink() + print("Cleared Hermes Anthropic OAuth credentials") + + elif removed.source == "claude_code" and provider == "anthropic": + from hermes_cli.auth import suppress_credential_source + suppress_credential_source(provider, "claude_code") + print("Suppressed claude_code credential — it will not be re-seeded.") + print("Note: Claude Code credentials still live in ~/.claude/.credentials.json") + print("Run `hermes auth add anthropic` to re-enable if needed.") + + +def auth_reset_command(args) -> None: + provider = _normalize_provider(getattr(args, "provider", "")) + pool = load_pool(provider) + count = pool.reset_statuses() + print(f"Reset status on {count} {provider} credentials") + + +def _interactive_auth() -> None: + """Interactive credential pool management when `hermes auth` is called bare.""" + # Show current pool status first + print("Credential Pool Status") + print("=" * 50) + + auth_list_command(SimpleNamespace(provider=None)) + print() + + # Main menu + choices = [ + "Add a credential", + "Remove a credential", + "Reset cooldowns for a provider", + "Set rotation strategy for a provider", + "Exit", + ] + print("What would you like to do?") + for i, choice in enumerate(choices, 1): + print(f" {i}. {choice}") + + try: + raw = input("\nChoice: ").strip() + except (EOFError, KeyboardInterrupt): + return + + if not raw or raw == str(len(choices)): + return + + if raw == "1": + _interactive_add() + elif raw == "2": + _interactive_remove() + elif raw == "3": + _interactive_reset() + elif raw == "4": + _interactive_strategy() + + +def _pick_provider(prompt: str = "Provider") -> str: + """Prompt for a provider name with auto-complete hints.""" + known = sorted(set(list(PROVIDER_REGISTRY.keys()) + ["openrouter"])) + custom_names = _get_custom_provider_names() + if custom_names: + custom_display = [name for name, _key, _provider_key in custom_names] + print(f"\nKnown providers: {', '.join(known)}") + print(f"Custom endpoints: {', '.join(custom_display)}") + else: + print(f"\nKnown providers: {', '.join(known)}") + try: + raw = input(f"{prompt}: ").strip() + except (EOFError, KeyboardInterrupt): + raise SystemExit() + return _normalize_provider(raw) + + +def _interactive_add() -> None: + provider = _pick_provider("Provider to add credential for") + if provider not in PROVIDER_REGISTRY and provider != "openrouter" and not provider.startswith(CUSTOM_POOL_PREFIX): + raise SystemExit(f"Unknown provider: {provider}") + + # For OAuth-capable providers, ask which type + if provider in _OAUTH_CAPABLE_PROVIDERS: + print(f"\n{provider} supports both API keys and OAuth login.") + print(" 1. API key (paste a key from the provider dashboard)") + print(" 2. OAuth login (authenticate via browser)") + try: + type_choice = input("Type [1/2]: ").strip() + except (EOFError, KeyboardInterrupt): + return + if type_choice == "2": + auth_type = "oauth" + else: + auth_type = "api_key" + else: + auth_type = "api_key" + + label = None + try: + typed_label = input("Label / account name (optional): ").strip() + except (EOFError, KeyboardInterrupt): + return + if typed_label: + label = typed_label + + auth_add_command(SimpleNamespace( + provider=provider, auth_type=auth_type, label=label, api_key=None, + portal_url=None, inference_url=None, client_id=None, scope=None, + no_browser=False, timeout=None, insecure=False, ca_bundle=None, + )) + + +def _interactive_remove() -> None: + provider = _pick_provider("Provider to remove credential from") + pool = load_pool(provider) + if not pool.has_credentials(): + print(f"No credentials for {provider}.") + return + + # Show entries with indices + for i, e in enumerate(pool.entries(), 1): + exhausted = _format_exhausted_status(e) + print(f" #{i} {e.label:25s} {e.auth_type:10s} {e.source}{exhausted} [id:{e.id}]") + + try: + raw = input("Remove #, id, or label (blank to cancel): ").strip() + except (EOFError, KeyboardInterrupt): + return + if not raw: + return + + auth_remove_command(SimpleNamespace(provider=provider, target=raw)) + + +def _interactive_reset() -> None: + provider = _pick_provider("Provider to reset cooldowns for") + + auth_reset_command(SimpleNamespace(provider=provider)) + + +def _interactive_strategy() -> None: + provider = _pick_provider("Provider to set strategy for") + current = get_pool_strategy(provider) + strategies = [STRATEGY_FILL_FIRST, STRATEGY_ROUND_ROBIN, STRATEGY_LEAST_USED, STRATEGY_RANDOM] + + print(f"\nCurrent strategy for {provider}: {current}") + print() + descriptions = { + STRATEGY_FILL_FIRST: "Use first key until exhausted, then next", + STRATEGY_ROUND_ROBIN: "Cycle through keys evenly", + STRATEGY_LEAST_USED: "Always pick the least-used key", + STRATEGY_RANDOM: "Random selection", + } + for i, s in enumerate(strategies, 1): + marker = " ←" if s == current else "" + print(f" {i}. {s:15s} — {descriptions.get(s, '')}{marker}") + + try: + raw = input("\nStrategy [1-4]: ").strip() + except (EOFError, KeyboardInterrupt): + return + if not raw: + return + + try: + idx = int(raw) - 1 + strategy = strategies[idx] + except (ValueError, IndexError): + print("Invalid choice.") + return + + from hermes_cli.config import load_config, save_config + cfg = load_config() + pool_strategies = cfg.get("credential_pool_strategies") or {} + if not isinstance(pool_strategies, dict): + pool_strategies = {} + pool_strategies[provider] = strategy + cfg["credential_pool_strategies"] = pool_strategies + save_config(cfg) + print(f"Set {provider} strategy to: {strategy}") + + +def auth_command(args) -> None: + action = getattr(args, "auth_action", "") + if action == "add": + auth_add_command(args) + return + if action == "list": + auth_list_command(args) + return + if action == "remove": + auth_remove_command(args) + return + if action == "reset": + auth_reset_command(args) + return + # No subcommand — launch interactive mode + _interactive_auth() diff --git a/mindcli/_vendor/hermes_cli/backup.py b/mindcli/_vendor/hermes_cli/backup.py new file mode 100644 index 0000000..667b891 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/backup.py @@ -0,0 +1,655 @@ +""" +Backup and import commands for hermes CLI. + +`hermes backup` creates a zip archive of the entire ~/.hermes/ directory +(excluding the hermes-agent repo and transient files). + +`hermes import` restores from a backup zip, overlaying onto the current +HERMES_HOME root. +""" + +import json +import logging +import os +import shutil +import sqlite3 +import sys +import tempfile +import time +import zipfile +from datetime import datetime, timezone +from pathlib import Path +from typing import Any, Dict, List, Optional + +from hermes_constants import get_default_hermes_root, get_hermes_home, display_hermes_home + +logger = logging.getLogger(__name__) + + +# --------------------------------------------------------------------------- +# Exclusion rules +# --------------------------------------------------------------------------- + +# Directory names to skip entirely (matched against each path component) +_EXCLUDED_DIRS = { + "hermes-agent", # the codebase repo — re-clone instead + "__pycache__", # bytecode caches — regenerated on import + ".git", # nested git dirs (profiles shouldn't have these, but safety) + "node_modules", # js deps if website/ somehow leaks in +} + +# File-name suffixes to skip +_EXCLUDED_SUFFIXES = ( + ".pyc", + ".pyo", +) + +# File names to skip (runtime state that's meaningless on another machine) +_EXCLUDED_NAMES = { + "gateway.pid", + "cron.pid", +} + + +def _should_exclude(rel_path: Path) -> bool: + """Return True if *rel_path* (relative to hermes root) should be skipped.""" + parts = rel_path.parts + + # Any path component matches an excluded dir name + for part in parts: + if part in _EXCLUDED_DIRS: + return True + + name = rel_path.name + + if name in _EXCLUDED_NAMES: + return True + + if name.endswith(_EXCLUDED_SUFFIXES): + return True + + return False + + +# --------------------------------------------------------------------------- +# SQLite safe copy +# --------------------------------------------------------------------------- + +def _safe_copy_db(src: Path, dst: Path) -> bool: + """Copy a SQLite database safely using the backup() API. + + Handles WAL mode — produces a consistent snapshot even while + the DB is being written to. Falls back to raw copy on failure. + """ + try: + conn = sqlite3.connect(f"file:{src}?mode=ro", uri=True) + backup_conn = sqlite3.connect(str(dst)) + conn.backup(backup_conn) + backup_conn.close() + conn.close() + return True + except Exception as exc: + logger.warning("SQLite safe copy failed for %s: %s", src, exc) + try: + shutil.copy2(src, dst) + return True + except Exception as exc2: + logger.error("Raw copy also failed for %s: %s", src, exc2) + return False + + +# --------------------------------------------------------------------------- +# Backup +# --------------------------------------------------------------------------- + +def _format_size(nbytes: int) -> str: + """Human-readable file size.""" + for unit in ("B", "KB", "MB", "GB"): + if nbytes < 1024: + return f"{nbytes:.1f} {unit}" if unit != "B" else f"{nbytes} {unit}" + nbytes /= 1024 + return f"{nbytes:.1f} TB" + + +def run_backup(args) -> None: + """Create a zip backup of the Hermes home directory.""" + hermes_root = get_default_hermes_root() + + if not hermes_root.is_dir(): + print(f"Error: Hermes home directory not found at {hermes_root}") + sys.exit(1) + + # Determine output path + if args.output: + out_path = Path(args.output).expanduser().resolve() + # If user gave a directory, put the zip inside it + if out_path.is_dir(): + stamp = datetime.now().strftime("%Y-%m-%d-%H%M%S") + out_path = out_path / f"hermes-backup-{stamp}.zip" + else: + stamp = datetime.now().strftime("%Y-%m-%d-%H%M%S") + out_path = Path.home() / f"hermes-backup-{stamp}.zip" + + # Ensure the suffix is .zip + if out_path.suffix.lower() != ".zip": + out_path = out_path.with_suffix(out_path.suffix + ".zip") + + # Ensure parent directory exists + out_path.parent.mkdir(parents=True, exist_ok=True) + + # Collect files + print(f"Scanning {display_hermes_home()} ...") + files_to_add: list[tuple[Path, Path]] = [] # (absolute, relative) + skipped_dirs = set() + + for dirpath, dirnames, filenames in os.walk(hermes_root, followlinks=False): + dp = Path(dirpath) + rel_dir = dp.relative_to(hermes_root) + + # Prune excluded directories in-place so os.walk doesn't descend + orig_dirnames = dirnames[:] + dirnames[:] = [ + d for d in dirnames + if d not in _EXCLUDED_DIRS + ] + for removed in set(orig_dirnames) - set(dirnames): + skipped_dirs.add(str(rel_dir / removed)) + + for fname in filenames: + fpath = dp / fname + rel = fpath.relative_to(hermes_root) + + if _should_exclude(rel): + continue + + # Skip the output zip itself if it happens to be inside hermes root + try: + if fpath.resolve() == out_path.resolve(): + continue + except (OSError, ValueError): + pass + + files_to_add.append((fpath, rel)) + + if not files_to_add: + print("No files to back up.") + return + + # Create the zip + file_count = len(files_to_add) + print(f"Backing up {file_count} files ...") + + total_bytes = 0 + errors = [] + t0 = time.monotonic() + + with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED, compresslevel=6) as zf: + for i, (abs_path, rel_path) in enumerate(files_to_add, 1): + try: + # Safe copy for SQLite databases (handles WAL mode) + if abs_path.suffix == ".db": + with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as tmp: + tmp_db = Path(tmp.name) + if _safe_copy_db(abs_path, tmp_db): + zf.write(tmp_db, arcname=str(rel_path)) + total_bytes += tmp_db.stat().st_size + tmp_db.unlink(missing_ok=True) + else: + tmp_db.unlink(missing_ok=True) + errors.append(f" {rel_path}: SQLite safe copy failed") + continue + else: + zf.write(abs_path, arcname=str(rel_path)) + total_bytes += abs_path.stat().st_size + except (PermissionError, OSError) as exc: + errors.append(f" {rel_path}: {exc}") + continue + + # Progress every 500 files + if i % 500 == 0: + print(f" {i}/{file_count} files ...") + + elapsed = time.monotonic() - t0 + zip_size = out_path.stat().st_size + + # Summary + print() + print(f"Backup complete: {out_path}") + print(f" Files: {file_count}") + print(f" Original: {_format_size(total_bytes)}") + print(f" Compressed: {_format_size(zip_size)}") + print(f" Time: {elapsed:.1f}s") + + if skipped_dirs: + print(f"\n Excluded directories:") + for d in sorted(skipped_dirs): + print(f" {d}/") + + if errors: + print(f"\n Warnings ({len(errors)} files skipped):") + for e in errors[:10]: + print(e) + if len(errors) > 10: + print(f" ... and {len(errors) - 10} more") + + print(f"\nRestore with: hermes import {out_path.name}") + + +# --------------------------------------------------------------------------- +# Import +# --------------------------------------------------------------------------- + +def _validate_backup_zip(zf: zipfile.ZipFile) -> tuple[bool, str]: + """Check that a zip looks like a Hermes backup. + + Returns (ok, reason). + """ + names = zf.namelist() + if not names: + return False, "zip archive is empty" + + # Look for telltale files that a hermes home would have + markers = {"config.yaml", ".env", "state.db"} + found = set() + for n in names: + # Could be at the root or one level deep (if someone zipped the directory) + basename = Path(n).name + if basename in markers: + found.add(basename) + + if not found: + return False, ( + "zip does not appear to be a Hermes backup " + "(no config.yaml, .env, or state databases found)" + ) + + return True, "" + + +def _detect_prefix(zf: zipfile.ZipFile) -> str: + """Detect if the zip has a common directory prefix wrapping all entries. + + Some tools zip as `.hermes/config.yaml` instead of `config.yaml`. + Returns the prefix to strip (empty string if none). + """ + names = [n for n in zf.namelist() if not n.endswith("/")] + if not names: + return "" + + # Find common prefix + parts_list = [Path(n).parts for n in names] + + # Check if all entries share a common first directory + first_parts = {p[0] for p in parts_list if len(p) > 1} + if len(first_parts) == 1: + prefix = first_parts.pop() + # Only strip if it looks like a hermes dir name + if prefix in (".hermes", "hermes"): + return prefix + "/" + + return "" + + +def run_import(args) -> None: + """Restore a Hermes backup from a zip file.""" + zip_path = Path(args.zipfile).expanduser().resolve() + + if not zip_path.is_file(): + print(f"Error: File not found: {zip_path}") + sys.exit(1) + + if not zipfile.is_zipfile(zip_path): + print(f"Error: Not a valid zip file: {zip_path}") + sys.exit(1) + + hermes_root = get_default_hermes_root() + + with zipfile.ZipFile(zip_path, "r") as zf: + # Validate + ok, reason = _validate_backup_zip(zf) + if not ok: + print(f"Error: {reason}") + sys.exit(1) + + prefix = _detect_prefix(zf) + members = [n for n in zf.namelist() if not n.endswith("/")] + file_count = len(members) + + print(f"Backup contains {file_count} files") + print(f"Target: {display_hermes_home()}") + + if prefix: + print(f"Detected archive prefix: {prefix!r} (will be stripped)") + + # Check for existing installation + has_config = (hermes_root / "config.yaml").exists() + has_env = (hermes_root / ".env").exists() + + if (has_config or has_env) and not args.force: + print() + print("Warning: Target directory already has Hermes configuration.") + print("Importing will overwrite existing files with backup contents.") + print() + try: + answer = input("Continue? [y/N] ").strip().lower() + except (EOFError, KeyboardInterrupt): + print("\nAborted.") + sys.exit(1) + if answer not in ("y", "yes"): + print("Aborted.") + return + + # Extract + print(f"\nImporting {file_count} files ...") + hermes_root.mkdir(parents=True, exist_ok=True) + + errors = [] + restored = 0 + t0 = time.monotonic() + + for member in members: + # Strip prefix if detected + if prefix and member.startswith(prefix): + rel = member[len(prefix):] + else: + rel = member + + if not rel: + continue + + target = hermes_root / rel + + # Security: reject absolute paths and traversals + try: + target.resolve().relative_to(hermes_root.resolve()) + except ValueError: + errors.append(f" {rel}: path traversal blocked") + continue + + try: + target.parent.mkdir(parents=True, exist_ok=True) + with zf.open(member) as src, open(target, "wb") as dst: + dst.write(src.read()) + restored += 1 + except (PermissionError, OSError) as exc: + errors.append(f" {rel}: {exc}") + + if restored % 500 == 0: + print(f" {restored}/{file_count} files ...") + + elapsed = time.monotonic() - t0 + + # Summary + print() + print(f"Import complete: {restored} files restored in {elapsed:.1f}s") + print(f" Target: {display_hermes_home()}") + + if errors: + print(f"\n Warnings ({len(errors)} files skipped):") + for e in errors[:10]: + print(e) + if len(errors) > 10: + print(f" ... and {len(errors) - 10} more") + + # Post-import: restore profile wrapper scripts + profiles_dir = hermes_root / "profiles" + restored_profiles = [] + if profiles_dir.is_dir(): + try: + from hermes_cli.profiles import ( + create_wrapper_script, check_alias_collision, + _is_wrapper_dir_in_path, _get_wrapper_dir, + ) + for entry in sorted(profiles_dir.iterdir()): + if not entry.is_dir(): + continue + profile_name = entry.name + # Only create wrappers for directories with config + if not (entry / "config.yaml").exists() and not (entry / ".env").exists(): + continue + collision = check_alias_collision(profile_name) + if collision: + print(f" Skipped alias '{profile_name}': {collision}") + restored_profiles.append((profile_name, False)) + else: + wrapper = create_wrapper_script(profile_name) + restored_profiles.append((profile_name, wrapper is not None)) + + if restored_profiles: + created = [n for n, ok in restored_profiles if ok] + skipped = [n for n, ok in restored_profiles if not ok] + if created: + print(f"\n Profile aliases restored: {', '.join(created)}") + if skipped: + print(f" Profile aliases skipped: {', '.join(skipped)}") + if not _is_wrapper_dir_in_path(): + print(f"\n Note: {_get_wrapper_dir()} is not in your PATH.") + print(' Add to your shell config (~/.bashrc or ~/.zshrc):') + print(' export PATH="$HOME/.local/bin:$PATH"') + except ImportError: + # hermes_cli.profiles might not be available (fresh install) + if any(profiles_dir.iterdir()): + print(f"\n Profiles detected but aliases could not be created.") + print(f" Run: hermes profile list (after installing hermes)") + + # Guidance + print() + if not (hermes_root / "hermes-agent").is_dir(): + print("Note: The hermes-agent codebase was not included in the backup.") + print(" If this is a fresh install, run: hermes update") + + if restored_profiles: + gw_profiles = [n for n, _ in restored_profiles] + print("\nTo re-enable gateway services for profiles:") + for pname in gw_profiles: + print(f" hermes -p {pname} gateway install") + + print("Done. Your Hermes configuration has been restored.") + + +# --------------------------------------------------------------------------- +# Quick state snapshots (used by /snapshot slash command and hermes backup --quick) +# --------------------------------------------------------------------------- + +# Critical state files to include in quick snapshots (relative to HERMES_HOME). +# Everything else is either regeneratable (logs, cache) or managed separately +# (skills, repo, sessions/). +_QUICK_STATE_FILES = ( + "state.db", + "config.yaml", + ".env", + "auth.json", + "cron/jobs.json", + "gateway_state.json", + "channel_directory.json", + "processes.json", +) + +_QUICK_SNAPSHOTS_DIR = "state-snapshots" +_QUICK_DEFAULT_KEEP = 20 + + +def _quick_snapshot_root(hermes_home: Optional[Path] = None) -> Path: + home = hermes_home or get_hermes_home() + return home / _QUICK_SNAPSHOTS_DIR + + +def create_quick_snapshot( + label: Optional[str] = None, + hermes_home: Optional[Path] = None, +) -> Optional[str]: + """Create a quick state snapshot of critical files. + + Copies STATE_FILES to a timestamped directory under state-snapshots/. + Auto-prunes old snapshots beyond the keep limit. + + Returns: + Snapshot ID (timestamp-based), or None if no files found. + """ + home = hermes_home or get_hermes_home() + root = _quick_snapshot_root(home) + + ts = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S") + snap_id = f"{ts}-{label}" if label else ts + snap_dir = root / snap_id + snap_dir.mkdir(parents=True, exist_ok=True) + + manifest: Dict[str, int] = {} # rel_path -> file size + + for rel in _QUICK_STATE_FILES: + src = home / rel + if not src.exists() or not src.is_file(): + continue + + dst = snap_dir / rel + dst.parent.mkdir(parents=True, exist_ok=True) + + try: + if src.suffix == ".db": + if not _safe_copy_db(src, dst): + continue + else: + shutil.copy2(src, dst) + manifest[rel] = dst.stat().st_size + except (OSError, PermissionError) as exc: + logger.warning("Could not snapshot %s: %s", rel, exc) + + if not manifest: + shutil.rmtree(snap_dir, ignore_errors=True) + return None + + # Write manifest + meta = { + "id": snap_id, + "timestamp": ts, + "label": label, + "file_count": len(manifest), + "total_size": sum(manifest.values()), + "files": manifest, + } + with open(snap_dir / "manifest.json", "w") as f: + json.dump(meta, f, indent=2) + + # Auto-prune + _prune_quick_snapshots(root, keep=_QUICK_DEFAULT_KEEP) + + logger.info("State snapshot created: %s (%d files)", snap_id, len(manifest)) + return snap_id + + +def list_quick_snapshots( + limit: int = 20, + hermes_home: Optional[Path] = None, +) -> List[Dict[str, Any]]: + """List existing quick state snapshots, most recent first.""" + root = _quick_snapshot_root(hermes_home) + if not root.exists(): + return [] + + results = [] + for d in sorted(root.iterdir(), reverse=True): + if not d.is_dir(): + continue + manifest_path = d / "manifest.json" + if manifest_path.exists(): + try: + with open(manifest_path) as f: + results.append(json.load(f)) + except (json.JSONDecodeError, OSError): + results.append({"id": d.name, "file_count": 0, "total_size": 0}) + if len(results) >= limit: + break + + return results + + +def restore_quick_snapshot( + snapshot_id: str, + hermes_home: Optional[Path] = None, +) -> bool: + """Restore state from a quick snapshot. + + Overwrites current state files with the snapshot's copies. + Returns True if at least one file was restored. + """ + home = hermes_home or get_hermes_home() + root = _quick_snapshot_root(home) + snap_dir = root / snapshot_id + + if not snap_dir.is_dir(): + return False + + manifest_path = snap_dir / "manifest.json" + if not manifest_path.exists(): + return False + + with open(manifest_path) as f: + meta = json.load(f) + + restored = 0 + for rel in meta.get("files", {}): + src = snap_dir / rel + if not src.exists(): + continue + + dst = home / rel + dst.parent.mkdir(parents=True, exist_ok=True) + + try: + if dst.suffix == ".db": + # Atomic-ish replace for databases + tmp = dst.parent / f".{dst.name}.snap_restore" + shutil.copy2(src, tmp) + dst.unlink(missing_ok=True) + shutil.move(str(tmp), str(dst)) + else: + shutil.copy2(src, dst) + restored += 1 + except (OSError, PermissionError) as exc: + logger.error("Failed to restore %s: %s", rel, exc) + + logger.info("Restored %d files from snapshot %s", restored, snapshot_id) + return restored > 0 + + +def _prune_quick_snapshots(root: Path, keep: int = _QUICK_DEFAULT_KEEP) -> int: + """Remove oldest quick snapshots beyond the keep limit. Returns count deleted.""" + if not root.exists(): + return 0 + + dirs = sorted( + (d for d in root.iterdir() if d.is_dir()), + key=lambda d: d.name, + reverse=True, + ) + + deleted = 0 + for d in dirs[keep:]: + try: + shutil.rmtree(d) + deleted += 1 + except OSError as exc: + logger.warning("Failed to prune snapshot %s: %s", d.name, exc) + + return deleted + + +def prune_quick_snapshots( + keep: int = _QUICK_DEFAULT_KEEP, + hermes_home: Optional[Path] = None, +) -> int: + """Manually prune quick snapshots. Returns count deleted.""" + return _prune_quick_snapshots(_quick_snapshot_root(hermes_home), keep=keep) + + +def run_quick_backup(args) -> None: + """CLI entry point for hermes backup --quick.""" + label = getattr(args, "label", None) + snap_id = create_quick_snapshot(label=label) + if snap_id: + print(f"State snapshot created: {snap_id}") + snaps = list_quick_snapshots() + print(f" {len(snaps)} snapshot(s) stored in {display_hermes_home()}/state-snapshots/") + print(f" Restore with: /snapshot restore {snap_id}") + else: + print("No state files found to snapshot.") diff --git a/mindcli/_vendor/hermes_cli/banner.py b/mindcli/_vendor/hermes_cli/banner.py new file mode 100644 index 0000000..fb6068a --- /dev/null +++ b/mindcli/_vendor/hermes_cli/banner.py @@ -0,0 +1,535 @@ +"""Welcome banner, ASCII art, skills summary, and update check for the CLI. + +Pure display functions with no HermesCLI state dependency. +""" + +import json +import logging +import shutil +import subprocess +import threading +import time +from pathlib import Path +from hermes_constants import get_hermes_home +from typing import Dict, List, Optional + +from rich.console import Console +from rich.panel import Panel +from rich.table import Table + +from prompt_toolkit import print_formatted_text as _pt_print +from prompt_toolkit.formatted_text import ANSI as _PT_ANSI + +logger = logging.getLogger(__name__) + + +# ========================================================================= +# ANSI building blocks for conversation display +# ========================================================================= + +_GOLD = "\033[1;38;2;255;215;0m" # True-color #FFD700 bold +_BOLD = "\033[1m" +_DIM = "\033[2m" +_RST = "\033[0m" + + +def cprint(text: str): + """Print ANSI-colored text through prompt_toolkit's renderer.""" + _pt_print(_PT_ANSI(text)) + + +# ========================================================================= +# Skin-aware color helpers +# ========================================================================= + +def _skin_color(key: str, fallback: str) -> str: + """Get a color from the active skin, or return fallback.""" + try: + from hermes_cli.skin_engine import get_active_skin + return get_active_skin().get_color(key, fallback) + except Exception: + return fallback + + +def _skin_branding(key: str, fallback: str) -> str: + """Get a branding string from the active skin, or return fallback.""" + try: + from hermes_cli.skin_engine import get_active_skin + return get_active_skin().get_branding(key, fallback) + except Exception: + return fallback + + +# ========================================================================= +# ASCII Art & Branding +# ========================================================================= + +from hermes_cli import __version__ as VERSION, __release_date__ as RELEASE_DATE + +HERMES_AGENT_LOGO = """[bold #FFD700]██╗ ██╗███████╗██████╗ ███╗ ███╗███████╗███████╗ █████╗ ██████╗ ███████╗███╗ ██╗████████╗[/] +[bold #FFD700]██║ ██║██╔════╝██╔══██╗████╗ ████║██╔════╝██╔════╝ ██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝[/] +[#FFBF00]███████║█████╗ ██████╔╝██╔████╔██║█████╗ ███████╗█████╗███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║[/] +[#FFBF00]██╔══██║██╔══╝ ██╔══██╗██║╚██╔╝██║██╔══╝ ╚════██║╚════╝██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║[/] +[#CD7F32]██║ ██║███████╗██║ ██║██║ ╚═╝ ██║███████╗███████║ ██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║[/] +[#CD7F32]╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚══════╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝[/]""" + +HERMES_CADUCEUS = """[#CD7F32]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⡀⠀⣀⣀⠀⢀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#CD7F32]⠀⠀⠀⠀⠀⠀⢀⣠⣴⣾⣿⣿⣇⠸⣿⣿⠇⣸⣿⣿⣷⣦⣄⡀⠀⠀⠀⠀⠀⠀[/] +[#FFBF00]⠀⢀⣠⣴⣶⠿⠋⣩⡿⣿⡿⠻⣿⡇⢠⡄⢸⣿⠟⢿⣿⢿⣍⠙⠿⣶⣦⣄⡀⠀[/] +[#FFBF00]⠀⠀⠉⠉⠁⠶⠟⠋⠀⠉⠀⢀⣈⣁⡈⢁⣈⣁⡀⠀⠉⠀⠙⠻⠶⠈⠉⠉⠀⠀[/] +[#FFD700]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣴⣿⡿⠛⢁⡈⠛⢿⣿⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#FFD700]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠿⣿⣦⣤⣈⠁⢠⣴⣿⠿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#FFBF00]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠻⢿⣿⣦⡉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#FFBF00]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⢷⣦⣈⠛⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#CD7F32]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⣴⠦⠈⠙⠿⣦⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#CD7F32]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠸⣿⣤⡈⠁⢤⣿⠇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#B8860B]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⠷⠄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#B8860B]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⠑⢶⣄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#B8860B]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⠁⢰⡆⠈⡿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#B8860B]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠳⠈⣡⠞⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#B8860B]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]""" + + + +# ========================================================================= +# Skills scanning +# ========================================================================= + +def get_available_skills() -> Dict[str, List[str]]: + """Return skills grouped by category, filtered by platform and disabled state. + + Delegates to ``_find_all_skills()`` from ``tools/skills_tool`` which already + handles platform gating (``platforms:`` frontmatter) and respects the + user's ``skills.disabled`` config list. + """ + try: + from tools.skills_tool import _find_all_skills + all_skills = _find_all_skills() # already filtered + except Exception: + return {} + + skills_by_category: Dict[str, List[str]] = {} + for skill in all_skills: + category = skill.get("category") or "general" + skills_by_category.setdefault(category, []).append(skill["name"]) + return skills_by_category + + +# ========================================================================= +# Update check +# ========================================================================= + +# Cache update check results for 6 hours to avoid repeated git fetches +_UPDATE_CHECK_CACHE_SECONDS = 6 * 3600 + + +def check_for_updates() -> Optional[int]: + """Check how many commits behind origin/main the local repo is. + + Does a ``git fetch`` at most once every 6 hours (cached to + ``~/.hermes/.update_check``). Returns the number of commits behind, + or ``None`` if the check fails or isn't applicable. + """ + hermes_home = get_hermes_home() + repo_dir = hermes_home / "hermes-agent" + cache_file = hermes_home / ".update_check" + + # Must be a git repo — fall back to project root for dev installs + if not (repo_dir / ".git").exists(): + repo_dir = Path(__file__).parent.parent.resolve() + if not (repo_dir / ".git").exists(): + return None + + # Read cache + now = time.time() + try: + if cache_file.exists(): + cached = json.loads(cache_file.read_text()) + if now - cached.get("ts", 0) < _UPDATE_CHECK_CACHE_SECONDS: + return cached.get("behind") + except Exception: + pass + + # Fetch latest refs (fast — only downloads ref metadata, no files) + try: + subprocess.run( + ["git", "fetch", "origin", "--quiet"], + capture_output=True, timeout=10, + cwd=str(repo_dir), + ) + except Exception: + pass # Offline or timeout — use stale refs, that's fine + + # Count commits behind + try: + result = subprocess.run( + ["git", "rev-list", "--count", "HEAD..origin/main"], + capture_output=True, text=True, timeout=5, + cwd=str(repo_dir), + ) + if result.returncode == 0: + behind = int(result.stdout.strip()) + else: + behind = None + except Exception: + behind = None + + # Write cache + try: + cache_file.write_text(json.dumps({"ts": now, "behind": behind})) + except Exception: + pass + + return behind + + +def _resolve_repo_dir() -> Optional[Path]: + """Return the active Hermes git checkout, or None if this isn't a git install.""" + hermes_home = get_hermes_home() + repo_dir = hermes_home / "hermes-agent" + if not (repo_dir / ".git").exists(): + repo_dir = Path(__file__).parent.parent.resolve() + return repo_dir if (repo_dir / ".git").exists() else None + + +def _git_short_hash(repo_dir: Path, rev: str) -> Optional[str]: + """Resolve a git revision to an 8-character short hash.""" + try: + result = subprocess.run( + ["git", "rev-parse", "--short=8", rev], + capture_output=True, + text=True, + timeout=5, + cwd=str(repo_dir), + ) + except Exception: + return None + if result.returncode != 0: + return None + value = (result.stdout or "").strip() + return value or None + + +def get_git_banner_state(repo_dir: Optional[Path] = None) -> Optional[dict]: + """Return upstream/local git hashes for the startup banner.""" + repo_dir = repo_dir or _resolve_repo_dir() + if repo_dir is None: + return None + + upstream = _git_short_hash(repo_dir, "origin/main") + local = _git_short_hash(repo_dir, "HEAD") + if not upstream or not local: + return None + + ahead = 0 + try: + result = subprocess.run( + ["git", "rev-list", "--count", "origin/main..HEAD"], + capture_output=True, + text=True, + timeout=5, + cwd=str(repo_dir), + ) + if result.returncode == 0: + ahead = int((result.stdout or "0").strip() or "0") + except Exception: + ahead = 0 + + return {"upstream": upstream, "local": local, "ahead": max(ahead, 0)} + + +def format_banner_version_label() -> str: + """Return the version label shown in the startup banner title.""" + base = f"Hermes Agent v{VERSION} ({RELEASE_DATE})" + state = get_git_banner_state() + if not state: + return base + + upstream = state["upstream"] + local = state["local"] + ahead = int(state.get("ahead") or 0) + + if ahead <= 0 or upstream == local: + return f"{base} · upstream {upstream}" + + carried_word = "commit" if ahead == 1 else "commits" + return f"{base} · upstream {upstream} · local {local} (+{ahead} carried {carried_word})" + + +# ========================================================================= +# Non-blocking update check +# ========================================================================= + +_update_result: Optional[int] = None +_update_check_done = threading.Event() + + +def prefetch_update_check(): + """Kick off update check in a background daemon thread.""" + def _run(): + global _update_result + _update_result = check_for_updates() + _update_check_done.set() + t = threading.Thread(target=_run, daemon=True) + t.start() + + +def get_update_result(timeout: float = 0.5) -> Optional[int]: + """Get result of prefetched check. Returns None if not ready.""" + _update_check_done.wait(timeout=timeout) + return _update_result + + +# ========================================================================= +# Welcome banner +# ========================================================================= + +def _format_context_length(tokens: int) -> str: + """Format a token count for display (e.g. 128000 → '128K', 1048576 → '1M').""" + if tokens >= 1_000_000: + val = tokens / 1_000_000 + rounded = round(val) + if abs(val - rounded) < 0.05: + return f"{rounded}M" + return f"{val:.1f}M" + elif tokens >= 1_000: + val = tokens / 1_000 + rounded = round(val) + if abs(val - rounded) < 0.05: + return f"{rounded}K" + return f"{val:.1f}K" + return str(tokens) + + +def _display_toolset_name(toolset_name: str) -> str: + """Normalize internal/legacy toolset identifiers for banner display.""" + if not toolset_name: + return "unknown" + return ( + toolset_name[:-6] + if toolset_name.endswith("_tools") + else toolset_name + ) + + +def build_welcome_banner(console: Console, model: str, cwd: str, + tools: List[dict] = None, + enabled_toolsets: List[str] = None, + session_id: str = None, + get_toolset_for_tool=None, + context_length: int = None): + """Build and print a welcome banner with caduceus on left and info on right. + + Args: + console: Rich Console instance. + model: Current model name. + cwd: Current working directory. + tools: List of tool definitions. + enabled_toolsets: List of enabled toolset names. + session_id: Session identifier. + get_toolset_for_tool: Callable to map tool name -> toolset name. + context_length: Model's context window size in tokens. + """ + from model_tools import check_tool_availability, TOOLSET_REQUIREMENTS + if get_toolset_for_tool is None: + from model_tools import get_toolset_for_tool + + tools = tools or [] + enabled_toolsets = enabled_toolsets or [] + + _, unavailable_toolsets = check_tool_availability(quiet=True) + disabled_tools = set() + # Tools whose toolset has a check_fn are lazy-initialized (e.g. honcho, + # homeassistant) — they show as unavailable at banner time because the + # check hasn't run yet, but they aren't misconfigured. + lazy_tools = set() + for item in unavailable_toolsets: + toolset_name = item.get("name", "") + ts_req = TOOLSET_REQUIREMENTS.get(toolset_name, {}) + tools_in_ts = item.get("tools", []) + if ts_req.get("check_fn"): + lazy_tools.update(tools_in_ts) + else: + disabled_tools.update(tools_in_ts) + + layout_table = Table.grid(padding=(0, 2)) + layout_table.add_column("left", justify="center") + layout_table.add_column("right", justify="left") + + # Resolve skin colors once for the entire banner + accent = _skin_color("banner_accent", "#FFBF00") + dim = _skin_color("banner_dim", "#B8860B") + text = _skin_color("banner_text", "#FFF8DC") + session_color = _skin_color("session_border", "#8B8682") + + # Use skin's custom caduceus art if provided + try: + from hermes_cli.skin_engine import get_active_skin + _bskin = get_active_skin() + _hero = _bskin.banner_hero if hasattr(_bskin, 'banner_hero') and _bskin.banner_hero else HERMES_CADUCEUS + except Exception: + _bskin = None + _hero = HERMES_CADUCEUS + left_lines = ["", _hero, ""] + model_short = model.split("/")[-1] if "/" in model else model + if model_short.endswith(".gguf"): + model_short = model_short[:-5] + if len(model_short) > 28: + model_short = model_short[:25] + "..." + ctx_str = f" [dim {dim}]·[/] [dim {dim}]{_format_context_length(context_length)} context[/]" if context_length else "" + left_lines.append(f"[{accent}]{model_short}[/]{ctx_str} [dim {dim}]·[/] [dim {dim}]Nous Research[/]") + left_lines.append(f"[dim {dim}]{cwd}[/]") + if session_id: + left_lines.append(f"[dim {session_color}]Session: {session_id}[/]") + left_content = "\n".join(left_lines) + + right_lines = [f"[bold {accent}]Available Tools[/]"] + toolsets_dict: Dict[str, list] = {} + + for tool in tools: + tool_name = tool["function"]["name"] + toolset = _display_toolset_name(get_toolset_for_tool(tool_name) or "other") + toolsets_dict.setdefault(toolset, []).append(tool_name) + + for item in unavailable_toolsets: + toolset_id = item.get("id", item.get("name", "unknown")) + display_name = _display_toolset_name(toolset_id) + if display_name not in toolsets_dict: + toolsets_dict[display_name] = [] + for tool_name in item.get("tools", []): + if tool_name not in toolsets_dict[display_name]: + toolsets_dict[display_name].append(tool_name) + + sorted_toolsets = sorted(toolsets_dict.keys()) + display_toolsets = sorted_toolsets[:8] + remaining_toolsets = len(sorted_toolsets) - 8 + + for toolset in display_toolsets: + tool_names = toolsets_dict[toolset] + colored_names = [] + for name in sorted(tool_names): + if name in disabled_tools: + colored_names.append(f"[red]{name}[/]") + elif name in lazy_tools: + colored_names.append(f"[yellow]{name}[/]") + else: + colored_names.append(f"[{text}]{name}[/]") + + tools_str = ", ".join(colored_names) + if len(", ".join(sorted(tool_names))) > 45: + short_names = [] + length = 0 + for name in sorted(tool_names): + if length + len(name) + 2 > 42: + short_names.append("...") + break + short_names.append(name) + length += len(name) + 2 + colored_names = [] + for name in short_names: + if name == "...": + colored_names.append("[dim]...[/]") + elif name in disabled_tools: + colored_names.append(f"[red]{name}[/]") + elif name in lazy_tools: + colored_names.append(f"[yellow]{name}[/]") + else: + colored_names.append(f"[{text}]{name}[/]") + tools_str = ", ".join(colored_names) + + right_lines.append(f"[dim {dim}]{toolset}:[/] {tools_str}") + + if remaining_toolsets > 0: + right_lines.append(f"[dim {dim}](and {remaining_toolsets} more toolsets...)[/]") + + # MCP Servers section (only if configured) + try: + from tools.mcp_tool import get_mcp_status + mcp_status = get_mcp_status() + except Exception: + mcp_status = [] + + if mcp_status: + right_lines.append("") + right_lines.append(f"[bold {accent}]MCP Servers[/]") + for srv in mcp_status: + if srv["connected"]: + right_lines.append( + f"[dim {dim}]{srv['name']}[/] [{text}]({srv['transport']})[/] " + f"[dim {dim}]—[/] [{text}]{srv['tools']} tool(s)[/]" + ) + else: + right_lines.append( + f"[red]{srv['name']}[/] [dim]({srv['transport']})[/] " + f"[red]— failed[/]" + ) + + right_lines.append("") + right_lines.append(f"[bold {accent}]Available Skills[/]") + skills_by_category = get_available_skills() + total_skills = sum(len(s) for s in skills_by_category.values()) + + if skills_by_category: + for category in sorted(skills_by_category.keys()): + skill_names = sorted(skills_by_category[category]) + if len(skill_names) > 8: + display_names = skill_names[:8] + skills_str = ", ".join(display_names) + f" +{len(skill_names) - 8} more" + else: + skills_str = ", ".join(skill_names) + if len(skills_str) > 50: + skills_str = skills_str[:47] + "..." + right_lines.append(f"[dim {dim}]{category}:[/] [{text}]{skills_str}[/]") + else: + right_lines.append(f"[dim {dim}]No skills installed[/]") + + right_lines.append("") + mcp_connected = sum(1 for s in mcp_status if s["connected"]) if mcp_status else 0 + summary_parts = [f"{len(tools)} tools", f"{total_skills} skills"] + if mcp_connected: + summary_parts.append(f"{mcp_connected} MCP servers") + summary_parts.append("/help for commands") + # Show active profile name when not 'default' + try: + from hermes_cli.profiles import get_active_profile_name + _profile_name = get_active_profile_name() + if _profile_name and _profile_name != "default": + right_lines.append(f"[bold {accent}]Profile:[/] [{text}]{_profile_name}[/]") + except Exception: + pass # Never break the banner over a profiles.py bug + + right_lines.append(f"[dim {dim}]{' · '.join(summary_parts)}[/]") + + # Update check — use prefetched result if available + try: + behind = get_update_result(timeout=0.5) + if behind and behind > 0: + from hermes_cli.config import recommended_update_command + commits_word = "commit" if behind == 1 else "commits" + right_lines.append( + f"[bold yellow]⚠ {behind} {commits_word} behind[/]" + f"[dim yellow] — run [bold]{recommended_update_command()}[/bold] to update[/]" + ) + except Exception: + pass # Never break the banner over an update check + + right_content = "\n".join(right_lines) + layout_table.add_row(left_content, right_content) + + agent_name = _skin_branding("agent_name", "Hermes Agent") + title_color = _skin_color("banner_title", "#FFD700") + border_color = _skin_color("banner_border", "#CD7F32") + outer_panel = Panel( + layout_table, + title=f"[bold {title_color}]{format_banner_version_label()}[/]", + border_style=border_color, + padding=(0, 2), + ) + + console.print() + term_width = shutil.get_terminal_size().columns + if term_width >= 95: + _logo = _bskin.banner_logo if _bskin and hasattr(_bskin, 'banner_logo') and _bskin.banner_logo else HERMES_AGENT_LOGO + console.print(_logo) + console.print() + console.print(outer_panel) diff --git a/mindcli/_vendor/hermes_cli/callbacks.py b/mindcli/_vendor/hermes_cli/callbacks.py new file mode 100644 index 0000000..724e6e4 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/callbacks.py @@ -0,0 +1,242 @@ +"""Interactive prompt callbacks for terminal_tool integration. + +These bridge terminal_tool's interactive prompts (clarify, sudo, approval) +into prompt_toolkit's event loop. Each function takes the HermesCLI instance +as its first argument and uses its state (queues, app reference) to coordinate +with the TUI. +""" + +import queue +import time as _time +import getpass + +from hermes_cli.banner import cprint, _DIM, _RST +from hermes_cli.config import save_env_value_secure +from hermes_constants import display_hermes_home + + +def clarify_callback(cli, question, choices): + """Prompt for clarifying question through the TUI. + + Sets up the interactive selection UI, then blocks until the user + responds. Returns the user's choice or a timeout message. + """ + from cli import CLI_CONFIG + + timeout = CLI_CONFIG.get("clarify", {}).get("timeout", 120) + response_queue = queue.Queue() + is_open_ended = not choices + + cli._clarify_state = { + "question": question, + "choices": choices if not is_open_ended else [], + "selected": 0, + "response_queue": response_queue, + } + cli._clarify_deadline = _time.monotonic() + timeout + cli._clarify_freetext = is_open_ended + + if hasattr(cli, "_app") and cli._app: + cli._app.invalidate() + + while True: + try: + result = response_queue.get(timeout=1) + cli._clarify_deadline = 0 + return result + except queue.Empty: + remaining = cli._clarify_deadline - _time.monotonic() + if remaining <= 0: + break + if hasattr(cli, "_app") and cli._app: + cli._app.invalidate() + + cli._clarify_state = None + cli._clarify_freetext = False + cli._clarify_deadline = 0 + if hasattr(cli, "_app") and cli._app: + cli._app.invalidate() + cprint(f"\n{_DIM}(clarify timed out after {timeout}s — agent will decide){_RST}") + return ( + "The user did not provide a response within the time limit. " + "Use your best judgement to make the choice and proceed." + ) + + +def prompt_for_secret(cli, var_name: str, prompt: str, metadata=None) -> dict: + """Prompt for a secret value through the TUI (e.g. API keys for skills). + + Returns a dict with keys: success, stored_as, validated, skipped, message. + The secret is stored in ~/.hermes/.env and never exposed to the model. + """ + if not getattr(cli, "_app", None): + if not hasattr(cli, "_secret_state"): + cli._secret_state = None + if not hasattr(cli, "_secret_deadline"): + cli._secret_deadline = 0 + try: + value = getpass.getpass(f"{prompt} (hidden, Enter to skip): ") + except (EOFError, KeyboardInterrupt): + value = "" + + if not value: + cprint(f"\n{_DIM} ⏭ Secret entry cancelled{_RST}") + return { + "success": True, + "reason": "cancelled", + "stored_as": var_name, + "validated": False, + "skipped": True, + "message": "Secret setup was skipped.", + } + + stored = save_env_value_secure(var_name, value) + _dhh = display_hermes_home() + cprint(f"\n{_DIM} ✓ Stored secret in {_dhh}/.env as {var_name}{_RST}") + return { + **stored, + "skipped": False, + "message": "Secret stored securely. The secret value was not exposed to the model.", + } + + timeout = 120 + response_queue = queue.Queue() + + cli._secret_state = { + "var_name": var_name, + "prompt": prompt, + "metadata": metadata or {}, + "response_queue": response_queue, + } + cli._secret_deadline = _time.monotonic() + timeout + # Avoid storing stale draft input as the secret when Enter is pressed. + if hasattr(cli, "_clear_secret_input_buffer"): + try: + cli._clear_secret_input_buffer() + except Exception: + pass + elif hasattr(cli, "_app") and cli._app: + try: + cli._app.current_buffer.reset() + except Exception: + pass + + if hasattr(cli, "_app") and cli._app: + cli._app.invalidate() + + while True: + try: + value = response_queue.get(timeout=1) + cli._secret_state = None + cli._secret_deadline = 0 + if hasattr(cli, "_app") and cli._app: + cli._app.invalidate() + + if not value: + cprint(f"\n{_DIM} ⏭ Secret entry cancelled{_RST}") + return { + "success": True, + "reason": "cancelled", + "stored_as": var_name, + "validated": False, + "skipped": True, + "message": "Secret setup was skipped.", + } + + stored = save_env_value_secure(var_name, value) + _dhh = display_hermes_home() + cprint(f"\n{_DIM} ✓ Stored secret in {_dhh}/.env as {var_name}{_RST}") + return { + **stored, + "skipped": False, + "message": "Secret stored securely. The secret value was not exposed to the model.", + } + except queue.Empty: + remaining = cli._secret_deadline - _time.monotonic() + if remaining <= 0: + break + if hasattr(cli, "_app") and cli._app: + cli._app.invalidate() + + cli._secret_state = None + cli._secret_deadline = 0 + if hasattr(cli, "_clear_secret_input_buffer"): + try: + cli._clear_secret_input_buffer() + except Exception: + pass + elif hasattr(cli, "_app") and cli._app: + try: + cli._app.current_buffer.reset() + except Exception: + pass + if hasattr(cli, "_app") and cli._app: + cli._app.invalidate() + cprint(f"\n{_DIM} ⏱ Timeout — secret capture cancelled{_RST}") + return { + "success": True, + "reason": "timeout", + "stored_as": var_name, + "validated": False, + "skipped": True, + "message": "Secret setup timed out and was skipped.", + } + + +def approval_callback(cli, command: str, description: str) -> str: + """Prompt for dangerous command approval through the TUI. + + Shows a selection UI with choices: once / session / always / deny. + When the command is longer than 70 characters, a "view" option is + included so the user can reveal the full text before deciding. + + Uses cli._approval_lock to serialize concurrent requests (e.g. from + parallel delegation subtasks) so each prompt gets its own turn. + """ + lock = getattr(cli, "_approval_lock", None) + if lock is None: + import threading + cli._approval_lock = threading.Lock() + lock = cli._approval_lock + + with lock: + from cli import CLI_CONFIG + timeout = CLI_CONFIG.get("approvals", {}).get("timeout", 60) + response_queue = queue.Queue() + choices = ["once", "session", "always", "deny"] + if len(command) > 70: + choices.append("view") + + cli._approval_state = { + "command": command, + "description": description, + "choices": choices, + "selected": 0, + "response_queue": response_queue, + } + cli._approval_deadline = _time.monotonic() + timeout + + if hasattr(cli, "_app") and cli._app: + cli._app.invalidate() + + while True: + try: + result = response_queue.get(timeout=1) + cli._approval_state = None + cli._approval_deadline = 0 + if hasattr(cli, "_app") and cli._app: + cli._app.invalidate() + return result + except queue.Empty: + remaining = cli._approval_deadline - _time.monotonic() + if remaining <= 0: + break + if hasattr(cli, "_app") and cli._app: + cli._app.invalidate() + + cli._approval_state = None + cli._approval_deadline = 0 + if hasattr(cli, "_app") and cli._app: + cli._app.invalidate() + cprint(f"\n{_DIM} ⏱ Timeout — denying command{_RST}") + return "deny" diff --git a/mindcli/_vendor/hermes_cli/claw.py b/mindcli/_vendor/hermes_cli/claw.py new file mode 100644 index 0000000..e62efe4 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/claw.py @@ -0,0 +1,734 @@ +"""hermes claw — OpenClaw migration commands. + +Usage: + hermes claw migrate # Preview then migrate (always shows preview first) + hermes claw migrate --dry-run # Preview only, no changes + hermes claw migrate --yes # Skip confirmation prompt + hermes claw migrate --preset full --overwrite # Full migration, overwrite conflicts + hermes claw cleanup # Archive leftover OpenClaw directories + hermes claw cleanup --dry-run # Preview what would be archived +""" + +import importlib.util +import logging +import subprocess +import sys +from datetime import datetime +from pathlib import Path + +from hermes_cli.config import get_hermes_home, get_config_path, load_config, save_config +from hermes_constants import get_optional_skills_dir +from hermes_cli.setup import ( + Colors, + color, + print_header, + print_info, + print_success, + print_error, + prompt_yes_no, +) + +logger = logging.getLogger(__name__) + +PROJECT_ROOT = Path(__file__).parent.parent.resolve() + +_OPENCLAW_SCRIPT = ( + get_optional_skills_dir(PROJECT_ROOT / "optional-skills") + / "migration" + / "openclaw-migration" + / "scripts" + / "openclaw_to_hermes.py" +) + +# Fallback: user may have installed the skill from the Hub +_OPENCLAW_SCRIPT_INSTALLED = ( + get_hermes_home() + / "skills" + / "migration" + / "openclaw-migration" + / "scripts" + / "openclaw_to_hermes.py" +) + +# Known OpenClaw directory names (current + legacy) +_OPENCLAW_DIR_NAMES = (".openclaw", ".clawdbot", ".moltbot") + +def _detect_openclaw_processes() -> list[str]: + """Detect running OpenClaw processes and services. + + Returns a list of human-readable descriptions of what was found. + An empty list means nothing was detected. + """ + found: list[str] = [] + + # -- systemd service (Linux) ------------------------------------------ + if sys.platform != "win32": + try: + result = subprocess.run( + ["systemctl", "--user", "is-active", "openclaw-gateway.service"], + capture_output=True, text=True, timeout=5, + ) + if result.stdout.strip() == "active": + found.append("systemd service: openclaw-gateway.service") + except (FileNotFoundError, subprocess.TimeoutExpired): + pass + + # -- process scan ------------------------------------------------------ + if sys.platform == "win32": + try: + for exe in ("openclaw.exe", "clawd.exe"): + result = subprocess.run( + ["tasklist", "/FI", f"IMAGENAME eq {exe}"], + capture_output=True, text=True, timeout=5, + ) + if exe in result.stdout.lower(): + found.append(f"process: {exe}") + + # Node.js-hosted OpenClaw — tasklist doesn't show command lines, + # so fall back to PowerShell. + ps_cmd = ( + 'Get-CimInstance Win32_Process -Filter "Name = \'node.exe\'" | ' + 'Where-Object { $_.CommandLine -match "openclaw|clawd" } | ' + 'Select-Object -First 1 ProcessId' + ) + result = subprocess.run( + ["powershell", "-NoProfile", "-Command", ps_cmd], + capture_output=True, text=True, timeout=5, + ) + if result.stdout.strip(): + found.append(f"node.exe process with openclaw in command line (PID {result.stdout.strip()})") + except Exception: + pass + else: + try: + result = subprocess.run( + ["pgrep", "-f", "openclaw"], + capture_output=True, text=True, timeout=3, + ) + if result.returncode == 0: + pids = result.stdout.strip().split() + found.append(f"openclaw process(es) (PIDs: {', '.join(pids)})") + except (FileNotFoundError, subprocess.TimeoutExpired): + pass + + return found + + +def _warn_if_openclaw_running(auto_yes: bool) -> None: + """Warn if OpenClaw is still running before migration. + + Telegram, Discord, and Slack only allow one active connection per bot + token. Migrating while OpenClaw is running causes both to fight for the + same token. + """ + running = _detect_openclaw_processes() + if not running: + return + + print() + print_error("OpenClaw appears to be running:") + for detail in running: + print_info(f" * {detail}") + print_info( + "Messaging platforms (Telegram, Discord, Slack) only allow one " + "active session per bot token. If you continue, both OpenClaw and " + "Hermes may try to use the same token, causing disconnects." + ) + print_info("Recommendation: stop OpenClaw before migrating.") + print() + if auto_yes: + return + if not sys.stdin.isatty(): + print_info("Non-interactive session — continuing to preview only.") + return + if not prompt_yes_no("Continue anyway?", default=False): + print_info("Migration cancelled. Stop OpenClaw and try again.") + sys.exit(0) + + +def _warn_if_gateway_running(auto_yes: bool) -> None: + """Check if a Hermes gateway is running with connected platforms. + + Migrating bot tokens while the gateway is polling will cause conflicts + (e.g. Telegram 409 "terminated by other getUpdates request"). Warn the + user and let them decide whether to continue. + """ + from gateway.status import get_running_pid, read_runtime_status + + if not get_running_pid(): + return + + data = read_runtime_status() or {} + platforms = data.get("platforms") or {} + connected = [name for name, info in platforms.items() + if isinstance(info, dict) and info.get("state") == "connected"] + if not connected: + return + + print() + print_error( + "Hermes gateway is running with active connections: " + + ", ".join(connected) + ) + print_info( + "Migrating bot tokens while the gateway is active will cause " + "conflicts (Telegram, Discord, and Slack only allow one active " + "session per token)." + ) + print_info("Recommendation: stop the gateway first with 'hermes stop'.") + print() + if not auto_yes and not prompt_yes_no("Continue anyway?", default=False): + print_info("Migration cancelled. Stop the gateway and try again.") + sys.exit(0) + +# State files commonly found in OpenClaw workspace directories — listed +# during cleanup to help the user decide whether to archive +_WORKSPACE_STATE_GLOBS = ( + "*/todo.json", + "*/sessions/*", + "*/memory/*.json", + "*/logs/*", +) + + +def _find_migration_script() -> Path | None: + """Find the openclaw_to_hermes.py script in known locations.""" + for candidate in [_OPENCLAW_SCRIPT, _OPENCLAW_SCRIPT_INSTALLED]: + if candidate.exists(): + return candidate + return None + + +def _load_migration_module(script_path: Path): + """Dynamically load the migration script as a module.""" + spec = importlib.util.spec_from_file_location("openclaw_to_hermes", script_path) + if spec is None or spec.loader is None: + return None + mod = importlib.util.module_from_spec(spec) + # Register in sys.modules so @dataclass can resolve the module + # (Python 3.11+ requires this for dynamically loaded modules) + sys.modules[spec.name] = mod + try: + spec.loader.exec_module(mod) + except Exception: + sys.modules.pop(spec.name, None) + raise + return mod + + +def _find_openclaw_dirs() -> list[Path]: + """Find all OpenClaw directories on disk.""" + found = [] + for name in _OPENCLAW_DIR_NAMES: + candidate = Path.home() / name + if candidate.is_dir(): + found.append(candidate) + return found + + +def _scan_workspace_state(source_dir: Path) -> list[tuple[Path, str]]: + """Scan an OpenClaw directory for workspace state files. + + Returns a list of (path, description) tuples. + """ + findings: list[tuple[Path, str]] = [] + + # Direct state files in the root + for name in ("todo.json", "sessions", "logs"): + candidate = source_dir / name + if candidate.exists(): + kind = "directory" if candidate.is_dir() else "file" + findings.append((candidate, f"Root {kind}: {name}")) + + # State files inside workspace directories + for child in sorted(source_dir.iterdir()): + if not child.is_dir() or child.name.startswith("."): + continue + # Check for workspace-like subdirectories + for state_name in ("todo.json", "sessions", "logs", "memory"): + state_path = child / state_name + if state_path.exists(): + kind = "directory" if state_path.is_dir() else "file" + rel = state_path.relative_to(source_dir) + findings.append((state_path, f"Workspace {kind}: {rel}")) + + return findings + + +def _archive_directory(source_dir: Path, dry_run: bool = False) -> Path: + """Rename an OpenClaw directory to .pre-migration. + + Returns the archive path. + """ + timestamp = datetime.now().strftime("%Y%m%d") + archive_name = f"{source_dir.name}.pre-migration" + archive_path = source_dir.parent / archive_name + + # If archive already exists, add timestamp + if archive_path.exists(): + archive_name = f"{source_dir.name}.pre-migration-{timestamp}" + archive_path = source_dir.parent / archive_name + + # If still exists (multiple runs same day), add counter + counter = 2 + while archive_path.exists(): + archive_name = f"{source_dir.name}.pre-migration-{timestamp}-{counter}" + archive_path = source_dir.parent / archive_name + counter += 1 + + if not dry_run: + source_dir.rename(archive_path) + + return archive_path + + +def claw_command(args): + """Route hermes claw subcommands.""" + action = getattr(args, "claw_action", None) + + if action == "migrate": + _cmd_migrate(args) + elif action in ("cleanup", "clean"): + _cmd_cleanup(args) + else: + print("Usage: hermes claw [options]") + print() + print("Commands:") + print(" migrate Migrate settings from OpenClaw to Hermes") + print(" cleanup Archive leftover OpenClaw directories after migration") + print() + print("Run 'hermes claw --help' for options.") + + +def _cmd_migrate(args): + """Run the OpenClaw → Hermes migration.""" + # Check current and legacy OpenClaw directories + explicit_source = getattr(args, "source", None) + if explicit_source: + source_dir = Path(explicit_source) + else: + source_dir = Path.home() / ".openclaw" + if not source_dir.is_dir(): + # Try legacy directory names + for legacy in (".clawdbot", ".moltbot"): + candidate = Path.home() / legacy + if candidate.is_dir(): + source_dir = candidate + break + dry_run = getattr(args, "dry_run", False) + preset = getattr(args, "preset", "full") + overwrite = getattr(args, "overwrite", False) + migrate_secrets = getattr(args, "migrate_secrets", False) + workspace_target = getattr(args, "workspace_target", None) + skill_conflict = getattr(args, "skill_conflict", "skip") + + # If using the "full" preset, secrets are included by default + if preset == "full": + migrate_secrets = True + + print() + print( + color( + "┌─────────────────────────────────────────────────────────┐", + Colors.MAGENTA, + ) + ) + print( + color( + "│ ⚕ Hermes — OpenClaw Migration │", + Colors.MAGENTA, + ) + ) + print( + color( + "└─────────────────────────────────────────────────────────┘", + Colors.MAGENTA, + ) + ) + + # Check source directory + if not source_dir.is_dir(): + print() + print_error(f"OpenClaw directory not found: {source_dir}") + print_info("Make sure your OpenClaw installation is at the expected path.") + print_info("You can specify a custom path: hermes claw migrate --source /path/to/.openclaw") + return + + # Find the migration script + script_path = _find_migration_script() + if not script_path: + print() + print_error("Migration script not found.") + print_info("Expected at one of:") + print_info(f" {_OPENCLAW_SCRIPT}") + print_info(f" {_OPENCLAW_SCRIPT_INSTALLED}") + print_info("Make sure the openclaw-migration skill is installed.") + return + + # Show what we're doing + hermes_home = get_hermes_home() + auto_yes = getattr(args, "yes", False) + print() + print_header("Migration Settings") + print_info(f"Source: {source_dir}") + print_info(f"Target: {hermes_home}") + print_info(f"Preset: {preset}") + print_info(f"Overwrite: {'yes' if overwrite else 'no (skip conflicts)'}") + print_info(f"Secrets: {'yes (allowlisted only)' if migrate_secrets else 'no'}") + if skill_conflict != "skip": + print_info(f"Skill conflicts: {skill_conflict}") + if workspace_target: + print_info(f"Workspace: {workspace_target}") + print() + + # Check if OpenClaw is still running — migrating tokens while both are + # active will cause conflicts (e.g. Telegram 409). + _warn_if_openclaw_running(auto_yes) + + # Check if a Hermes gateway is running with connected platforms. + _warn_if_gateway_running(auto_yes) + + # Ensure config.yaml exists before migration tries to read it + config_path = get_config_path() + if not config_path.exists(): + save_config(load_config()) + + # Load the migration module + try: + mod = _load_migration_module(script_path) + if mod is None: + print_error("Could not load migration script.") + return + except Exception as e: + print() + print_error(f"Could not load migration script: {e}") + logger.debug("OpenClaw migration error", exc_info=True) + return + + selected = mod.resolve_selected_options(None, None, preset=preset) + ws_target = Path(workspace_target).resolve() if workspace_target else None + + # ── Phase 1: Always preview first ────────────────────────── + try: + preview = mod.Migrator( + source_root=source_dir.resolve(), + target_root=hermes_home.resolve(), + execute=False, + workspace_target=ws_target, + overwrite=overwrite, + migrate_secrets=migrate_secrets, + output_dir=None, + selected_options=selected, + preset_name=preset, + skill_conflict_mode=skill_conflict, + ) + preview_report = preview.migrate() + except Exception as e: + print() + print_error(f"Migration preview failed: {e}") + logger.debug("OpenClaw migration preview error", exc_info=True) + return + + preview_summary = preview_report.get("summary", {}) + preview_count = preview_summary.get("migrated", 0) + + if preview_count == 0: + print() + print_info("Nothing to migrate from OpenClaw.") + _print_migration_report(preview_report, dry_run=True) + return + + print() + print_header(f"Migration Preview — {preview_count} item(s) would be imported") + print_info("No changes have been made yet. Review the list below:") + _print_migration_report(preview_report, dry_run=True) + + # If --dry-run, stop here + if dry_run: + return + + # ── Phase 2: Confirm and execute ─────────────────────────── + print() + if not auto_yes: + if not sys.stdin.isatty(): + print_info("Non-interactive session — preview only.") + print_info("To execute, re-run with: hermes claw migrate --yes") + return + if not prompt_yes_no("Proceed with migration?", default=True): + print_info("Migration cancelled.") + return + + try: + migrator = mod.Migrator( + source_root=source_dir.resolve(), + target_root=hermes_home.resolve(), + execute=True, + workspace_target=ws_target, + overwrite=overwrite, + migrate_secrets=migrate_secrets, + output_dir=None, + selected_options=selected, + preset_name=preset, + skill_conflict_mode=skill_conflict, + ) + report = migrator.migrate() + except Exception as e: + print() + print_error(f"Migration failed: {e}") + logger.debug("OpenClaw migration error", exc_info=True) + return + + # Print results + _print_migration_report(report, dry_run=False) + + # Source directory is left untouched — archiving is not the migration + # tool's responsibility. Users who want to clean up can run + # 'hermes claw cleanup' separately. + + +def _cmd_cleanup(args): + """Archive leftover OpenClaw directories after migration. + + Scans for OpenClaw directories that still exist after migration and offers + to rename them to .pre-migration to free disk space. + """ + dry_run = getattr(args, "dry_run", False) + auto_yes = getattr(args, "yes", False) + explicit_source = getattr(args, "source", None) + + print() + print( + color( + "┌─────────────────────────────────────────────────────────┐", + Colors.MAGENTA, + ) + ) + print( + color( + "│ ⚕ Hermes — OpenClaw Cleanup │", + Colors.MAGENTA, + ) + ) + print( + color( + "└─────────────────────────────────────────────────────────┘", + Colors.MAGENTA, + ) + ) + + # Find OpenClaw directories + if explicit_source: + dirs_to_check = [Path(explicit_source)] + else: + dirs_to_check = _find_openclaw_dirs() + + if not dirs_to_check: + print() + print_success("No OpenClaw directories found. Nothing to clean up.") + return + + # Warn if OpenClaw is still running — archiving while the service is + # active causes it to recreate an empty skeleton directory (#8502). + running = _detect_openclaw_processes() + if running: + print() + print_error("OpenClaw appears to be still running:") + for detail in running: + print_info(f" * {detail}") + print_info( + "Archiving .openclaw/ while the service is active may cause it to " + "immediately recreate an empty skeleton directory, destroying your config." + ) + print_info("Stop OpenClaw first: systemctl --user stop openclaw-gateway.service") + print() + if not auto_yes: + if not sys.stdin.isatty(): + print_info("Non-interactive session — aborting. Stop OpenClaw and re-run.") + return + if not prompt_yes_no("Proceed anyway?", default=False): + print_info("Aborted. Stop OpenClaw first, then re-run: hermes claw cleanup") + return + + total_archived = 0 + + for source_dir in dirs_to_check: + print() + print_header(f"Found: {source_dir}") + + # Scan for state files + state_files = _scan_workspace_state(source_dir) + + # Show directory stats + try: + workspace_dirs = [ + d for d in source_dir.iterdir() + if d.is_dir() and not d.name.startswith(".") + and any((d / name).exists() for name in ("todo.json", "SOUL.md", "MEMORY.md", "USER.md")) + ] + except OSError: + workspace_dirs = [] + + if workspace_dirs: + print_info(f"Workspace directories: {len(workspace_dirs)}") + for ws in workspace_dirs[:5]: + items = [] + if (ws / "todo.json").exists(): + items.append("todo.json") + if (ws / "sessions").is_dir(): + items.append("sessions/") + if (ws / "SOUL.md").exists(): + items.append("SOUL.md") + if (ws / "MEMORY.md").exists(): + items.append("MEMORY.md") + detail = ", ".join(items) if items else "empty" + print(f" {ws.name}/ ({detail})") + if len(workspace_dirs) > 5: + print(f" ... and {len(workspace_dirs) - 5} more") + + if state_files: + print() + print(color(f" {len(state_files)} state file(s) found:", Colors.YELLOW)) + for path, desc in state_files[:8]: + print(f" {desc}") + if len(state_files) > 8: + print(f" ... and {len(state_files) - 8} more") + + print() + + if dry_run: + archive_path = _archive_directory(source_dir, dry_run=True) + print_info(f"Would archive: {source_dir} → {archive_path}") + elif not auto_yes and not sys.stdin.isatty(): + print_info(f"Non-interactive session — would archive: {source_dir}") + print_info("To execute, re-run with: hermes claw cleanup --yes") + else: + if auto_yes or prompt_yes_no(f"Archive {source_dir}?", default=True): + try: + archive_path = _archive_directory(source_dir) + print_success(f"Archived: {source_dir} → {archive_path}") + total_archived += 1 + except OSError as e: + print_error(f"Could not archive: {e}") + print_info(f"Try manually: mv {source_dir} {source_dir}.pre-migration") + else: + print_info("Skipped.") + + # Summary + print() + if dry_run: + print_info(f"Dry run complete. {len(dirs_to_check)} directory(ies) would be archived.") + print_info("Run without --dry-run to archive them.") + elif total_archived: + print_success(f"Cleaned up {total_archived} OpenClaw directory(ies).") + print_info("Directories were renamed, not deleted. You can undo by renaming them back.") + else: + print_info("No directories were archived.") + + +def _print_migration_report(report: dict, dry_run: bool): + """Print a formatted migration report.""" + summary = report.get("summary", {}) + migrated = summary.get("migrated", 0) + skipped = summary.get("skipped", 0) + conflicts = summary.get("conflict", 0) + errors = summary.get("error", 0) + + print() + if dry_run: + print_header("Dry Run Results") + print_info("No files were modified. This is a preview of what would happen.") + else: + print_header("Migration Results") + + print() + + # Detailed items + items = report.get("items", []) + if items: + # Group by status + migrated_items = [i for i in items if i.get("status") == "migrated"] + skipped_items = [i for i in items if i.get("status") == "skipped"] + conflict_items = [i for i in items if i.get("status") == "conflict"] + error_items = [i for i in items if i.get("status") == "error"] + + if migrated_items: + label = "Would migrate" if dry_run else "Migrated" + print(color(f" ✓ {label}:", Colors.GREEN)) + for item in migrated_items: + kind = item.get("kind", "unknown") + dest = item.get("destination", "") + if dest: + dest_short = str(dest).replace(str(Path.home()), "~") + print(f" {kind:<22s} → {dest_short}") + else: + print(f" {kind}") + print() + + if conflict_items: + print(color(" ⚠ Conflicts (skipped — use --overwrite to force):", Colors.YELLOW)) + for item in conflict_items: + kind = item.get("kind", "unknown") + reason = item.get("reason", "already exists") + print(f" {kind:<22s} {reason}") + print() + + if skipped_items: + print(color(" ─ Skipped:", Colors.DIM)) + for item in skipped_items: + kind = item.get("kind", "unknown") + reason = item.get("reason", "") + print(f" {kind:<22s} {reason}") + print() + + if error_items: + print(color(" ✗ Errors:", Colors.RED)) + for item in error_items: + kind = item.get("kind", "unknown") + reason = item.get("reason", "unknown error") + print(f" {kind:<22s} {reason}") + print() + + # Summary line + parts = [] + if migrated: + action = "would migrate" if dry_run else "migrated" + parts.append(f"{migrated} {action}") + if conflicts: + parts.append(f"{conflicts} conflict(s)") + if skipped: + parts.append(f"{skipped} skipped") + if errors: + parts.append(f"{errors} error(s)") + + if parts: + print_info(f"Summary: {', '.join(parts)}") + else: + print_info("Nothing to migrate.") + + # Output directory + output_dir = report.get("output_dir") + if output_dir: + print_info(f"Full report saved to: {output_dir}") + + if dry_run: + print() + print_info("To execute the migration, run without --dry-run:") + print_info(f" hermes claw migrate --preset {report.get('preset', 'full')}") + elif migrated: + print() + print_success("Migration complete!") + # Warn if API keys were skipped (migrate_secrets not enabled) + skipped_keys = [ + i for i in report.get("items", []) + if i.get("kind") == "provider-keys" and i.get("status") == "skipped" + ] + if skipped_keys: + print() + print(color(" ⚠ API keys were NOT migrated (secrets migration is disabled by default).", Colors.YELLOW)) + print(color(" Your OPENROUTER_API_KEY and other provider keys must be added manually.", Colors.YELLOW)) + print() + print_info("To migrate API keys, re-run with:") + print_info(" hermes claw migrate --migrate-secrets") + print() + print_info("Or add your key manually:") + print_info(" hermes config set OPENROUTER_API_KEY sk-or-v1-...") diff --git a/mindcli/_vendor/hermes_cli/cli_output.py b/mindcli/_vendor/hermes_cli/cli_output.py new file mode 100644 index 0000000..2f07129 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/cli_output.py @@ -0,0 +1,78 @@ +"""Shared CLI output helpers for Hermes CLI modules. + +Extracts the identical ``print_info/success/warning/error`` and ``prompt()`` +functions previously duplicated across setup.py, tools_config.py, +mcp_config.py, and memory_setup.py. +""" + +import getpass + +from hermes_cli.colors import Colors, color + + +# ─── Print Helpers ──────────────────────────────────────────────────────────── + + +def print_info(text: str) -> None: + """Print a dim informational message.""" + print(color(f" {text}", Colors.DIM)) + + +def print_success(text: str) -> None: + """Print a green success message with ✓ prefix.""" + print(color(f"✓ {text}", Colors.GREEN)) + + +def print_warning(text: str) -> None: + """Print a yellow warning message with ⚠ prefix.""" + print(color(f"⚠ {text}", Colors.YELLOW)) + + +def print_error(text: str) -> None: + """Print a red error message with ✗ prefix.""" + print(color(f"✗ {text}", Colors.RED)) + + +def print_header(text: str) -> None: + """Print a bold yellow header.""" + print(color(f"\n {text}", Colors.YELLOW)) + + +# ─── Input Prompts ──────────────────────────────────────────────────────────── + + +def prompt( + question: str, + default: str | None = None, + password: bool = False, +) -> str: + """Prompt the user for input with optional default and password masking. + + Replaces the four independent ``_prompt()`` / ``prompt()`` implementations + in setup.py, tools_config.py, mcp_config.py, and memory_setup.py. + + Returns the user's input (stripped), or *default* if the user presses Enter. + Returns empty string on Ctrl-C or EOF. + """ + suffix = f" [{default}]" if default else "" + display = color(f" {question}{suffix}: ", Colors.YELLOW) + + try: + if password: + value = getpass.getpass(display) + else: + value = input(display) + value = value.strip() + return value if value else (default or "") + except (KeyboardInterrupt, EOFError): + print() + return "" + + +def prompt_yes_no(question: str, default: bool = True) -> bool: + """Prompt for a yes/no answer. Returns bool.""" + hint = "Y/n" if default else "y/N" + answer = prompt(f"{question} ({hint})") + if not answer: + return default + return answer.lower().startswith("y") diff --git a/mindcli/_vendor/hermes_cli/clipboard.py b/mindcli/_vendor/hermes_cli/clipboard.py new file mode 100644 index 0000000..fd81ed4 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/clipboard.py @@ -0,0 +1,432 @@ +"""Clipboard image extraction for macOS, Windows, Linux, and WSL2. + +Provides a single function `save_clipboard_image(dest)` that checks the +system clipboard for image data, saves it to *dest* as PNG, and returns +True on success. No external Python dependencies — uses only OS-level +CLI tools that ship with the platform (or are commonly installed). + +Platform support: + macOS — osascript (always available), pngpaste (if installed) + Windows — PowerShell via .NET System.Windows.Forms.Clipboard + WSL2 — powershell.exe via .NET System.Windows.Forms.Clipboard + Linux — wl-paste (Wayland), xclip (X11) +""" + +import base64 +import logging +import os +import subprocess +import sys +from pathlib import Path + +from hermes_constants import is_wsl as _is_wsl + +logger = logging.getLogger(__name__) + + +def save_clipboard_image(dest: Path) -> bool: + """Extract an image from the system clipboard and save it as PNG. + + Returns True if an image was found and saved, False otherwise. + """ + dest.parent.mkdir(parents=True, exist_ok=True) + if sys.platform == "darwin": + return _macos_save(dest) + if sys.platform == "win32": + return _windows_save(dest) + return _linux_save(dest) + + +def has_clipboard_image() -> bool: + """Quick check: does the clipboard currently contain an image? + + Lighter than save_clipboard_image — doesn't extract or write anything. + """ + if sys.platform == "darwin": + return _macos_has_image() + if sys.platform == "win32": + return _windows_has_image() + if _is_wsl(): + return _wsl_has_image() + if os.environ.get("WAYLAND_DISPLAY"): + return _wayland_has_image() + return _xclip_has_image() + + +# ── macOS ──────────────────────────────────────────────────────────────── + +def _macos_save(dest: Path) -> bool: + """Try pngpaste first (fast, handles more formats), fall back to osascript.""" + return _macos_pngpaste(dest) or _macos_osascript(dest) + + +def _macos_has_image() -> bool: + """Check if macOS clipboard contains image data.""" + try: + info = subprocess.run( + ["osascript", "-e", "clipboard info"], + capture_output=True, text=True, timeout=3, + ) + return "«class PNGf»" in info.stdout or "«class TIFF»" in info.stdout + except Exception: + return False + + +def _macos_pngpaste(dest: Path) -> bool: + """Use pngpaste (brew install pngpaste) — fastest, cleanest.""" + try: + r = subprocess.run( + ["pngpaste", str(dest)], + capture_output=True, timeout=3, + ) + if r.returncode == 0 and dest.exists() and dest.stat().st_size > 0: + return True + except FileNotFoundError: + pass # pngpaste not installed + except Exception as e: + logger.debug("pngpaste failed: %s", e) + return False + + +def _macos_osascript(dest: Path) -> bool: + """Use osascript to extract PNG data from clipboard (always available).""" + if not _macos_has_image(): + return False + + # Extract as PNG + script = ( + 'try\n' + ' set imgData to the clipboard as «class PNGf»\n' + f' set f to open for access POSIX file "{dest}" with write permission\n' + ' write imgData to f\n' + ' close access f\n' + 'on error\n' + ' return "fail"\n' + 'end try\n' + ) + try: + r = subprocess.run( + ["osascript", "-e", script], + capture_output=True, text=True, timeout=5, + ) + if r.returncode == 0 and "fail" not in r.stdout and dest.exists() and dest.stat().st_size > 0: + return True + except Exception as e: + logger.debug("osascript clipboard extract failed: %s", e) + return False + + +# ── Shared PowerShell scripts (native Windows + WSL2) ───────────────────── + +# .NET System.Windows.Forms.Clipboard — used by both native Windows (powershell) +# and WSL2 (powershell.exe) paths. +_PS_CHECK_IMAGE = ( + "Add-Type -AssemblyName System.Windows.Forms;" + "[System.Windows.Forms.Clipboard]::ContainsImage()" +) + +_PS_EXTRACT_IMAGE = ( + "Add-Type -AssemblyName System.Windows.Forms;" + "Add-Type -AssemblyName System.Drawing;" + "$img = [System.Windows.Forms.Clipboard]::GetImage();" + "if ($null -eq $img) { exit 1 }" + "$ms = New-Object System.IO.MemoryStream;" + "$img.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png);" + "[System.Convert]::ToBase64String($ms.ToArray())" +) + + +# ── Native Windows ──────────────────────────────────────────────────────── + +# Native Windows uses ``powershell`` (Windows PowerShell 5.1, always present) +# or ``pwsh`` (PowerShell 7+, optional). Discovery is cached per-process. + + +def _find_powershell() -> str | None: + """Return the first available PowerShell executable, or None.""" + for name in ("powershell", "pwsh"): + try: + r = subprocess.run( + [name, "-NoProfile", "-NonInteractive", "-Command", "echo ok"], + capture_output=True, text=True, timeout=5, + ) + if r.returncode == 0 and "ok" in r.stdout: + return name + except FileNotFoundError: + continue + except Exception: + continue + return None + + +# Cache the resolved PowerShell executable (checked once per process) +_ps_exe: str | None | bool = False # False = not yet checked + + +def _get_ps_exe() -> str | None: + global _ps_exe + if _ps_exe is False: + _ps_exe = _find_powershell() + return _ps_exe + + +def _windows_has_image() -> bool: + """Check if the Windows clipboard contains an image.""" + ps = _get_ps_exe() + if ps is None: + return False + try: + r = subprocess.run( + [ps, "-NoProfile", "-NonInteractive", "-Command", _PS_CHECK_IMAGE], + capture_output=True, text=True, timeout=5, + ) + return r.returncode == 0 and "True" in r.stdout + except Exception as e: + logger.debug("Windows clipboard image check failed: %s", e) + return False + + +def _windows_save(dest: Path) -> bool: + """Extract clipboard image on native Windows via PowerShell → base64 PNG.""" + ps = _get_ps_exe() + if ps is None: + logger.debug("No PowerShell found — Windows clipboard image paste unavailable") + return False + try: + r = subprocess.run( + [ps, "-NoProfile", "-NonInteractive", "-Command", _PS_EXTRACT_IMAGE], + capture_output=True, text=True, timeout=15, + ) + if r.returncode != 0: + return False + + b64_data = r.stdout.strip() + if not b64_data: + return False + + png_bytes = base64.b64decode(b64_data) + dest.write_bytes(png_bytes) + return dest.exists() and dest.stat().st_size > 0 + + except Exception as e: + logger.debug("Windows clipboard image extraction failed: %s", e) + dest.unlink(missing_ok=True) + return False + + +# ── Linux ──────────────────────────────────────────────────────────────── + +def _linux_save(dest: Path) -> bool: + """Try clipboard backends in priority order: WSL → Wayland → X11.""" + if _is_wsl(): + if _wsl_save(dest): + return True + # Fall through — WSLg might have wl-paste or xclip working + + if os.environ.get("WAYLAND_DISPLAY"): + if _wayland_save(dest): + return True + + return _xclip_save(dest) + + +# ── WSL2 (powershell.exe) ──────────────────────────────────────────────── +# Reuses _PS_CHECK_IMAGE / _PS_EXTRACT_IMAGE defined above. + +def _wsl_has_image() -> bool: + """Check if Windows clipboard has an image (via powershell.exe).""" + try: + r = subprocess.run( + ["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", + _PS_CHECK_IMAGE], + capture_output=True, text=True, timeout=8, + ) + return r.returncode == 0 and "True" in r.stdout + except FileNotFoundError: + logger.debug("powershell.exe not found — WSL clipboard unavailable") + except Exception as e: + logger.debug("WSL clipboard check failed: %s", e) + return False + + +def _wsl_save(dest: Path) -> bool: + """Extract clipboard image via powershell.exe → base64 → decode to PNG.""" + try: + r = subprocess.run( + ["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", + _PS_EXTRACT_IMAGE], + capture_output=True, text=True, timeout=15, + ) + if r.returncode != 0: + return False + + b64_data = r.stdout.strip() + if not b64_data: + return False + + png_bytes = base64.b64decode(b64_data) + dest.write_bytes(png_bytes) + return dest.exists() and dest.stat().st_size > 0 + + except FileNotFoundError: + logger.debug("powershell.exe not found — WSL clipboard unavailable") + except Exception as e: + logger.debug("WSL clipboard extraction failed: %s", e) + dest.unlink(missing_ok=True) + return False + + +# ── Wayland (wl-paste) ────────────────────────────────────────────────── + +def _wayland_has_image() -> bool: + """Check if Wayland clipboard has image content.""" + try: + r = subprocess.run( + ["wl-paste", "--list-types"], + capture_output=True, text=True, timeout=3, + ) + return r.returncode == 0 and any( + t.startswith("image/") for t in r.stdout.splitlines() + ) + except FileNotFoundError: + logger.debug("wl-paste not installed — Wayland clipboard unavailable") + except Exception: + pass + return False + + +def _wayland_save(dest: Path) -> bool: + """Use wl-paste to extract clipboard image (Wayland sessions).""" + try: + # Check available MIME types + types_r = subprocess.run( + ["wl-paste", "--list-types"], + capture_output=True, text=True, timeout=3, + ) + if types_r.returncode != 0: + return False + types = types_r.stdout.splitlines() + + # Prefer PNG, fall back to other image formats + mime = None + for preferred in ("image/png", "image/jpeg", "image/bmp", + "image/gif", "image/webp"): + if preferred in types: + mime = preferred + break + + if not mime: + return False + + # Extract the image data + with open(dest, "wb") as f: + subprocess.run( + ["wl-paste", "--type", mime], + stdout=f, stderr=subprocess.DEVNULL, timeout=5, check=True, + ) + + if not dest.exists() or dest.stat().st_size == 0: + dest.unlink(missing_ok=True) + return False + + # BMP needs conversion to PNG (common in WSLg where only BMP + # is bridged from Windows clipboard via RDP). + if mime == "image/bmp": + return _convert_to_png(dest) + + return True + + except FileNotFoundError: + logger.debug("wl-paste not installed — Wayland clipboard unavailable") + except Exception as e: + logger.debug("wl-paste clipboard extraction failed: %s", e) + dest.unlink(missing_ok=True) + return False + + +def _convert_to_png(path: Path) -> bool: + """Convert an image file to PNG in-place (requires Pillow or ImageMagick).""" + # Try Pillow first (likely installed in the venv) + try: + from PIL import Image + img = Image.open(path) + img.save(path, "PNG") + return True + except ImportError: + pass + except Exception as e: + logger.debug("Pillow BMP→PNG conversion failed: %s", e) + + # Fall back to ImageMagick convert + tmp = path.with_suffix(".bmp") + try: + path.rename(tmp) + r = subprocess.run( + ["convert", str(tmp), "png:" + str(path)], + capture_output=True, timeout=5, + ) + if r.returncode == 0 and path.exists() and path.stat().st_size > 0: + tmp.unlink(missing_ok=True) + return True + else: + # Convert failed — restore the original file + tmp.rename(path) + except FileNotFoundError: + logger.debug("ImageMagick not installed — cannot convert BMP to PNG") + if tmp.exists() and not path.exists(): + tmp.rename(path) + except Exception as e: + logger.debug("ImageMagick BMP→PNG conversion failed: %s", e) + if tmp.exists() and not path.exists(): + tmp.rename(path) + + # Can't convert — BMP is still usable as-is for most APIs + return path.exists() and path.stat().st_size > 0 + + +# ── X11 (xclip) ───────────────────────────────────────────────────────── + +def _xclip_has_image() -> bool: + """Check if X11 clipboard has image content.""" + try: + r = subprocess.run( + ["xclip", "-selection", "clipboard", "-t", "TARGETS", "-o"], + capture_output=True, text=True, timeout=3, + ) + return r.returncode == 0 and "image/png" in r.stdout + except FileNotFoundError: + pass + except Exception: + pass + return False + + +def _xclip_save(dest: Path) -> bool: + """Use xclip to extract clipboard image (X11 sessions).""" + # Check if clipboard has image content + try: + targets = subprocess.run( + ["xclip", "-selection", "clipboard", "-t", "TARGETS", "-o"], + capture_output=True, text=True, timeout=3, + ) + if "image/png" not in targets.stdout: + return False + except FileNotFoundError: + logger.debug("xclip not installed — X11 clipboard image paste unavailable") + return False + except Exception: + return False + + # Extract PNG data + try: + with open(dest, "wb") as f: + subprocess.run( + ["xclip", "-selection", "clipboard", "-t", "image/png", "-o"], + stdout=f, stderr=subprocess.DEVNULL, timeout=5, check=True, + ) + if dest.exists() and dest.stat().st_size > 0: + return True + except Exception as e: + logger.debug("xclip image extraction failed: %s", e) + dest.unlink(missing_ok=True) + return False diff --git a/mindcli/_vendor/hermes_cli/codex_models.py b/mindcli/_vendor/hermes_cli/codex_models.py new file mode 100644 index 0000000..f5616b6 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/codex_models.py @@ -0,0 +1,176 @@ +"""Codex model discovery from API, local cache, and config.""" + +from __future__ import annotations + +import json +import logging +from pathlib import Path +from typing import List, Optional + +import os + +logger = logging.getLogger(__name__) + +DEFAULT_CODEX_MODELS: List[str] = [ + "gpt-5.4-mini", + "gpt-5.4", + "gpt-5.3-codex", + "gpt-5.2-codex", + "gpt-5.1-codex-max", + "gpt-5.1-codex-mini", +] + +_FORWARD_COMPAT_TEMPLATE_MODELS: List[tuple[str, tuple[str, ...]]] = [ + ("gpt-5.4-mini", ("gpt-5.3-codex", "gpt-5.2-codex")), + ("gpt-5.4", ("gpt-5.3-codex", "gpt-5.2-codex")), + ("gpt-5.3-codex", ("gpt-5.2-codex",)), + ("gpt-5.3-codex-spark", ("gpt-5.3-codex", "gpt-5.2-codex")), +] + + +def _add_forward_compat_models(model_ids: List[str]) -> List[str]: + """Add Clawdbot-style synthetic forward-compat Codex models. + + If a newer Codex slug isn't returned by live discovery, surface it when an + older compatible template model is present. This mirrors Clawdbot's + synthetic catalog / forward-compat behavior for GPT-5 Codex variants. + """ + ordered: List[str] = [] + seen: set[str] = set() + for model_id in model_ids: + if model_id not in seen: + ordered.append(model_id) + seen.add(model_id) + + for synthetic_model, template_models in _FORWARD_COMPAT_TEMPLATE_MODELS: + if synthetic_model in seen: + continue + if any(template in seen for template in template_models): + ordered.append(synthetic_model) + seen.add(synthetic_model) + + return ordered + + +def _fetch_models_from_api(access_token: str) -> List[str]: + """Fetch available models from the Codex API. Returns visible models sorted by priority.""" + try: + import httpx + resp = httpx.get( + "https://chatgpt.com/backend-api/codex/models?client_version=1.0.0", + headers={"Authorization": f"Bearer {access_token}"}, + timeout=10, + ) + if resp.status_code != 200: + return [] + data = resp.json() + entries = data.get("models", []) if isinstance(data, dict) else [] + except Exception as exc: + logger.debug("Failed to fetch Codex models from API: %s", exc) + return [] + + sortable = [] + for item in entries: + if not isinstance(item, dict): + continue + slug = item.get("slug") + if not isinstance(slug, str) or not slug.strip(): + continue + slug = slug.strip() + if item.get("supported_in_api") is False: + continue + visibility = item.get("visibility", "") + if isinstance(visibility, str) and visibility.strip().lower() in ("hide", "hidden"): + continue + priority = item.get("priority") + rank = int(priority) if isinstance(priority, (int, float)) else 10_000 + sortable.append((rank, slug)) + + sortable.sort(key=lambda x: (x[0], x[1])) + return _add_forward_compat_models([slug for _, slug in sortable]) + + +def _read_default_model(codex_home: Path) -> Optional[str]: + config_path = codex_home / "config.toml" + if not config_path.exists(): + return None + try: + import tomllib + except Exception: + return None + try: + payload = tomllib.loads(config_path.read_text(encoding="utf-8")) + except Exception: + return None + model = payload.get("model") if isinstance(payload, dict) else None + if isinstance(model, str) and model.strip(): + return model.strip() + return None + + +def _read_cache_models(codex_home: Path) -> List[str]: + cache_path = codex_home / "models_cache.json" + if not cache_path.exists(): + return [] + try: + raw = json.loads(cache_path.read_text(encoding="utf-8")) + except Exception: + return [] + + entries = raw.get("models") if isinstance(raw, dict) else None + sortable = [] + if isinstance(entries, list): + for item in entries: + if not isinstance(item, dict): + continue + slug = item.get("slug") + if not isinstance(slug, str) or not slug.strip(): + continue + slug = slug.strip() + if item.get("supported_in_api") is False: + continue + visibility = item.get("visibility") + if isinstance(visibility, str) and visibility.strip().lower() in ("hide", "hidden"): + continue + priority = item.get("priority") + rank = int(priority) if isinstance(priority, (int, float)) else 10_000 + sortable.append((rank, slug)) + + sortable.sort(key=lambda item: (item[0], item[1])) + deduped: List[str] = [] + for _, slug in sortable: + if slug not in deduped: + deduped.append(slug) + return deduped + + +def get_codex_model_ids(access_token: Optional[str] = None) -> List[str]: + """Return available Codex model IDs, trying API first, then local sources. + + Resolution order: API (live, if token provided) > config.toml default > + local cache > hardcoded defaults. + """ + codex_home_str = os.getenv("CODEX_HOME", "").strip() or str(Path.home() / ".codex") + codex_home = Path(codex_home_str).expanduser() + ordered: List[str] = [] + + # Try live API if we have a token + if access_token: + api_models = _fetch_models_from_api(access_token) + if api_models: + return _add_forward_compat_models(api_models) + + # Fall back to local sources + default_model = _read_default_model(codex_home) + if default_model: + ordered.append(default_model) + + for model_id in _read_cache_models(codex_home): + if model_id not in ordered: + ordered.append(model_id) + + for model_id in DEFAULT_CODEX_MODELS: + if model_id not in ordered: + ordered.append(model_id) + + return _add_forward_compat_models(ordered) diff --git a/mindcli/_vendor/hermes_cli/colors.py b/mindcli/_vendor/hermes_cli/colors.py new file mode 100644 index 0000000..8c85b4c --- /dev/null +++ b/mindcli/_vendor/hermes_cli/colors.py @@ -0,0 +1,38 @@ +"""Shared ANSI color utilities for Hermes CLI modules.""" + +import os +import sys + + +def should_use_color() -> bool: + """Return True when colored output is appropriate. + + Respects the NO_COLOR environment variable (https://no-color.org/) + and TERM=dumb, in addition to the existing TTY check. + """ + if os.environ.get("NO_COLOR") is not None: + return False + if os.environ.get("TERM") == "dumb": + return False + if not sys.stdout.isatty(): + return False + return True + + +class Colors: + RESET = "\033[0m" + BOLD = "\033[1m" + DIM = "\033[2m" + RED = "\033[31m" + GREEN = "\033[32m" + YELLOW = "\033[33m" + BLUE = "\033[34m" + MAGENTA = "\033[35m" + CYAN = "\033[36m" + + +def color(text: str, *codes) -> str: + """Apply color codes to text (only when color output is appropriate).""" + if not should_use_color(): + return text + return "".join(codes) + text + Colors.RESET diff --git a/mindcli/_vendor/hermes_cli/commands.py b/mindcli/_vendor/hermes_cli/commands.py new file mode 100644 index 0000000..e62c7e6 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/commands.py @@ -0,0 +1,1108 @@ +"""Slash command definitions and autocomplete for the Hermes CLI. + +Central registry for all slash commands. Every consumer -- CLI help, gateway +dispatch, Telegram BotCommands, Slack subcommand mapping, autocomplete -- +derives its data from ``COMMAND_REGISTRY``. + +To add a command: add a ``CommandDef`` entry to ``COMMAND_REGISTRY``. +To add an alias: set ``aliases=("short",)`` on the existing ``CommandDef``. +""" + +from __future__ import annotations + +import os +import re +import shutil +import subprocess +import time +from collections.abc import Callable, Mapping +from dataclasses import dataclass +from typing import Any + +# prompt_toolkit is an optional CLI dependency — only needed for +# SlashCommandCompleter and SlashCommandAutoSuggest. Gateway and test +# environments that lack it must still be able to import this module +# for resolve_command, gateway_help_lines, and COMMAND_REGISTRY. +try: + from prompt_toolkit.auto_suggest import AutoSuggest, Suggestion + from prompt_toolkit.completion import Completer, Completion +except ImportError: # pragma: no cover + AutoSuggest = object # type: ignore[assignment,misc] + Completer = object # type: ignore[assignment,misc] + Suggestion = None # type: ignore[assignment] + Completion = None # type: ignore[assignment] + + +# --------------------------------------------------------------------------- +# CommandDef dataclass +# --------------------------------------------------------------------------- + +@dataclass(frozen=True) +class CommandDef: + """Definition of a single slash command.""" + + name: str # canonical name without slash: "background" + description: str # human-readable description + category: str # "Session", "Configuration", etc. + aliases: tuple[str, ...] = () # alternative names: ("bg",) + args_hint: str = "" # argument placeholder: "", "[name]" + subcommands: tuple[str, ...] = () # tab-completable subcommands + cli_only: bool = False # only available in CLI + gateway_only: bool = False # only available in gateway/messaging + gateway_config_gate: str | None = None # config dotpath; when truthy, overrides cli_only for gateway + + +# --------------------------------------------------------------------------- +# Central registry -- single source of truth +# --------------------------------------------------------------------------- + +COMMAND_REGISTRY: list[CommandDef] = [ + # Session + CommandDef("new", "Start a new session (fresh session ID + history)", "Session", + aliases=("reset",)), + CommandDef("clear", "Clear screen and start a new session", "Session", + cli_only=True), + CommandDef("history", "Show conversation history", "Session", + cli_only=True), + CommandDef("save", "Save the current conversation", "Session", + cli_only=True), + CommandDef("retry", "Retry the last message (resend to agent)", "Session"), + CommandDef("undo", "Remove the last user/assistant exchange", "Session"), + CommandDef("title", "Set a title for the current session", "Session", + args_hint="[name]"), + CommandDef("branch", "Branch the current session (explore a different path)", "Session", + aliases=("fork",), args_hint="[name]"), + CommandDef("compress", "Manually compress conversation context", "Session", + args_hint="[focus topic]"), + CommandDef("rollback", "List or restore filesystem checkpoints", "Session", + args_hint="[number]"), + CommandDef("snapshot", "Create or restore state snapshots of Hermes config/state", "Session", + aliases=("snap",), args_hint="[create|restore |prune]"), + CommandDef("stop", "Kill all running background processes", "Session"), + CommandDef("approve", "Approve a pending dangerous command", "Session", + gateway_only=True, args_hint="[session|always]"), + CommandDef("deny", "Deny a pending dangerous command", "Session", + gateway_only=True), + CommandDef("background", "Run a prompt in the background", "Session", + aliases=("bg",), args_hint=""), + CommandDef("btw", "Ephemeral side question using session context (no tools, not persisted)", "Session", + args_hint=""), + CommandDef("queue", "Queue a prompt for the next turn (doesn't interrupt)", "Session", + aliases=("q",), args_hint=""), + CommandDef("status", "Show session info", "Session"), + CommandDef("profile", "Show active profile name and home directory", "Info"), + CommandDef("sethome", "Set this chat as the home channel", "Session", + gateway_only=True, aliases=("set-home",)), + CommandDef("resume", "Resume a previously-named session", "Session", + args_hint="[name]"), + + # Configuration + CommandDef("config", "Show current configuration", "Configuration", + cli_only=True), + CommandDef("model", "Switch model for this session", "Configuration", args_hint="[model] [--global]"), + CommandDef("provider", "Show available providers and current provider", + "Configuration"), + + CommandDef("personality", "Set a predefined personality", "Configuration", + args_hint="[name]"), + CommandDef("statusbar", "Toggle the context/model status bar", "Configuration", + cli_only=True, aliases=("sb",)), + CommandDef("verbose", "Cycle tool progress display: off -> new -> all -> verbose", + "Configuration", cli_only=True, + gateway_config_gate="display.tool_progress_command"), + CommandDef("yolo", "Toggle YOLO mode (skip all dangerous command approvals)", + "Configuration"), + CommandDef("reasoning", "Manage reasoning effort and display", "Configuration", + args_hint="[level|show|hide]", + subcommands=("none", "minimal", "low", "medium", "high", "xhigh", "show", "hide", "on", "off")), + CommandDef("fast", "Toggle fast mode — OpenAI Priority Processing / Anthropic Fast Mode (Normal/Fast)", "Configuration", + args_hint="[normal|fast|status]", + subcommands=("normal", "fast", "status", "on", "off")), + CommandDef("skin", "Show or change the display skin/theme", "Configuration", + cli_only=True, args_hint="[name]"), + CommandDef("voice", "Toggle voice mode", "Configuration", + args_hint="[on|off|tts|status]", subcommands=("on", "off", "tts", "status")), + + # Tools & Skills + CommandDef("tools", "Manage tools: /tools [list|disable|enable] [name...]", "Tools & Skills", + args_hint="[list|disable|enable] [name...]", cli_only=True), + CommandDef("toolsets", "List available toolsets", "Tools & Skills", + cli_only=True), + CommandDef("skills", "Search, install, inspect, or manage skills", + "Tools & Skills", cli_only=True, + subcommands=("search", "browse", "inspect", "install")), + CommandDef("cron", "Manage scheduled tasks", "Tools & Skills", + cli_only=True, args_hint="[subcommand]", + subcommands=("list", "add", "create", "edit", "pause", "resume", "run", "remove")), + CommandDef("reload", "Reload .env variables into the running session", "Tools & Skills"), + CommandDef("reload-mcp", "Reload MCP servers from config", "Tools & Skills", + aliases=("reload_mcp",)), + CommandDef("browser", "Connect browser tools to your live Chrome via CDP", "Tools & Skills", + cli_only=True, args_hint="[connect|disconnect|status]", + subcommands=("connect", "disconnect", "status")), + CommandDef("plugins", "List installed plugins and their status", + "Tools & Skills", cli_only=True), + + # Info + CommandDef("commands", "Browse all commands and skills (paginated)", "Info", + gateway_only=True, args_hint="[page]"), + CommandDef("help", "Show available commands", "Info"), + CommandDef("restart", "Gracefully restart the gateway after draining active runs", "Session", + gateway_only=True), + CommandDef("usage", "Show token usage and rate limits for the current session", "Info"), + CommandDef("insights", "Show usage insights and analytics", "Info", + args_hint="[days]"), + CommandDef("platforms", "Show gateway/messaging platform status", "Info", + cli_only=True, aliases=("gateway",)), + CommandDef("paste", "Check clipboard for an image and attach it", "Info", + cli_only=True), + CommandDef("image", "Attach a local image file for your next prompt", "Info", + cli_only=True, args_hint=""), + CommandDef("update", "Update Hermes Agent to the latest version", "Info", + gateway_only=True), + CommandDef("debug", "Upload debug report (system info + logs) and get shareable links", "Info"), + + # Exit + CommandDef("quit", "Exit the CLI", "Exit", + cli_only=True, aliases=("exit", "q")), +] + + +# --------------------------------------------------------------------------- +# Derived lookups -- rebuilt once at import time, refreshed by rebuild_lookups() +# --------------------------------------------------------------------------- + +def _build_command_lookup() -> dict[str, CommandDef]: + """Map every name and alias to its CommandDef.""" + lookup: dict[str, CommandDef] = {} + for cmd in COMMAND_REGISTRY: + lookup[cmd.name] = cmd + for alias in cmd.aliases: + lookup[alias] = cmd + return lookup + + +_COMMAND_LOOKUP: dict[str, CommandDef] = _build_command_lookup() + + +def resolve_command(name: str) -> CommandDef | None: + """Resolve a command name or alias to its CommandDef. + + Accepts names with or without the leading slash. + """ + return _COMMAND_LOOKUP.get(name.lower().lstrip("/")) + + +def _build_description(cmd: CommandDef) -> str: + """Build a CLI-facing description string including usage hint.""" + if cmd.args_hint: + return f"{cmd.description} (usage: /{cmd.name} {cmd.args_hint})" + return cmd.description + + +# Backwards-compatible flat dict: "/command" -> description +COMMANDS: dict[str, str] = {} +for _cmd in COMMAND_REGISTRY: + if not _cmd.gateway_only: + COMMANDS[f"/{_cmd.name}"] = _build_description(_cmd) + for _alias in _cmd.aliases: + COMMANDS[f"/{_alias}"] = f"{_cmd.description} (alias for /{_cmd.name})" + +# Backwards-compatible categorized dict +COMMANDS_BY_CATEGORY: dict[str, dict[str, str]] = {} +for _cmd in COMMAND_REGISTRY: + if not _cmd.gateway_only: + _cat = COMMANDS_BY_CATEGORY.setdefault(_cmd.category, {}) + _cat[f"/{_cmd.name}"] = COMMANDS[f"/{_cmd.name}"] + for _alias in _cmd.aliases: + _cat[f"/{_alias}"] = COMMANDS[f"/{_alias}"] + + +# Subcommands lookup: "/cmd" -> ["sub1", "sub2", ...] +SUBCOMMANDS: dict[str, list[str]] = {} +for _cmd in COMMAND_REGISTRY: + if _cmd.subcommands: + SUBCOMMANDS[f"/{_cmd.name}"] = list(_cmd.subcommands) + +# Also extract subcommands hinted in args_hint via pipe-separated patterns +# e.g. args_hint="[on|off|tts|status]" for commands that don't have explicit subcommands. +# NOTE: If a command already has explicit subcommands, this fallback is skipped. +# Use the `subcommands` field on CommandDef for intentional tab-completable args. +_PIPE_SUBS_RE = re.compile(r"[a-z]+(?:\|[a-z]+)+") +for _cmd in COMMAND_REGISTRY: + key = f"/{_cmd.name}" + if key in SUBCOMMANDS or not _cmd.args_hint: + continue + m = _PIPE_SUBS_RE.search(_cmd.args_hint) + if m: + SUBCOMMANDS[key] = m.group(0).split("|") + + +# --------------------------------------------------------------------------- +# Gateway helpers +# --------------------------------------------------------------------------- + +# Set of all command names + aliases recognized by the gateway. +# Includes config-gated commands so the gateway can dispatch them +# (the handler checks the config gate at runtime). +GATEWAY_KNOWN_COMMANDS: frozenset[str] = frozenset( + name + for cmd in COMMAND_REGISTRY + if not cmd.cli_only or cmd.gateway_config_gate + for name in (cmd.name, *cmd.aliases) +) + + +def _resolve_config_gates() -> set[str]: + """Return canonical names of commands whose ``gateway_config_gate`` is truthy. + + Reads ``config.yaml`` and walks the dot-separated key path for each + config-gated command. Returns an empty set on any error so callers + degrade gracefully. + """ + gated = [c for c in COMMAND_REGISTRY if c.gateway_config_gate] + if not gated: + return set() + try: + from hermes_cli.config import read_raw_config + cfg = read_raw_config() + except Exception: + return set() + result: set[str] = set() + for cmd in gated: + val: Any = cfg + for key in cmd.gateway_config_gate.split("."): + if isinstance(val, dict): + val = val.get(key) + else: + val = None + break + if val: + result.add(cmd.name) + return result + + +def _is_gateway_available(cmd: CommandDef, config_overrides: set[str] | None = None) -> bool: + """Check if *cmd* should appear in gateway surfaces (help, menus, mappings). + + Unconditionally available when ``cli_only`` is False. When ``cli_only`` + is True but ``gateway_config_gate`` is set, the command is available only + when the config value is truthy. Pass *config_overrides* (from + ``_resolve_config_gates()``) to avoid re-reading config for every command. + """ + if not cmd.cli_only: + return True + if cmd.gateway_config_gate: + overrides = config_overrides if config_overrides is not None else _resolve_config_gates() + return cmd.name in overrides + return False + + +def gateway_help_lines() -> list[str]: + """Generate gateway help text lines from the registry.""" + overrides = _resolve_config_gates() + lines: list[str] = [] + for cmd in COMMAND_REGISTRY: + if not _is_gateway_available(cmd, overrides): + continue + args = f" {cmd.args_hint}" if cmd.args_hint else "" + alias_parts: list[str] = [] + for a in cmd.aliases: + # Skip internal aliases like reload_mcp (underscore variant) + if a.replace("-", "_") == cmd.name.replace("-", "_") and a != cmd.name: + continue + alias_parts.append(f"`/{a}`") + alias_note = f" (alias: {', '.join(alias_parts)})" if alias_parts else "" + lines.append(f"`/{cmd.name}{args}` -- {cmd.description}{alias_note}") + return lines + + +def telegram_bot_commands() -> list[tuple[str, str]]: + """Return (command_name, description) pairs for Telegram setMyCommands. + + Telegram command names cannot contain hyphens, so they are replaced with + underscores. Aliases are skipped -- Telegram shows one menu entry per + canonical command. + """ + overrides = _resolve_config_gates() + result: list[tuple[str, str]] = [] + for cmd in COMMAND_REGISTRY: + if not _is_gateway_available(cmd, overrides): + continue + tg_name = _sanitize_telegram_name(cmd.name) + if tg_name: + result.append((tg_name, cmd.description)) + return result + + +_CMD_NAME_LIMIT = 32 +"""Max command name length shared by Telegram and Discord.""" + +# Backward-compat alias — tests and external code may reference the old name. +_TG_NAME_LIMIT = _CMD_NAME_LIMIT + +# Telegram Bot API allows only lowercase a-z, 0-9, and underscores in +# command names. This regex strips everything else after initial conversion. +_TG_INVALID_CHARS = re.compile(r"[^a-z0-9_]") +_TG_MULTI_UNDERSCORE = re.compile(r"_{2,}") + + +def _sanitize_telegram_name(raw: str) -> str: + """Convert a command/skill/plugin name to a valid Telegram command name. + + Telegram requires: 1-32 chars, lowercase a-z, digits 0-9, underscores only. + Steps: lowercase → replace hyphens with underscores → strip all other + invalid characters → collapse consecutive underscores → strip leading/ + trailing underscores. + """ + name = raw.lower().replace("-", "_") + name = _TG_INVALID_CHARS.sub("", name) + name = _TG_MULTI_UNDERSCORE.sub("_", name) + return name.strip("_") + + +def _clamp_command_names( + entries: list[tuple[str, str]], + reserved: set[str], +) -> list[tuple[str, str]]: + """Enforce 32-char command name limit with collision avoidance. + + Both Telegram and Discord cap slash command names at 32 characters. + Names exceeding the limit are truncated. If truncation creates a duplicate + (against *reserved* names or earlier entries in the same batch), the name is + shortened to 31 chars and a digit ``0``-``9`` is appended to differentiate. + If all 10 digit slots are taken the entry is silently dropped. + """ + used: set[str] = set(reserved) + result: list[tuple[str, str]] = [] + for name, desc in entries: + if len(name) > _CMD_NAME_LIMIT: + candidate = name[:_CMD_NAME_LIMIT] + if candidate in used: + prefix = name[:_CMD_NAME_LIMIT - 1] + for digit in range(10): + candidate = f"{prefix}{digit}" + if candidate not in used: + break + else: + # All 10 digit slots exhausted — skip entry + continue + name = candidate + if name in used: + continue + used.add(name) + result.append((name, desc)) + return result + + +# Backward-compat alias. +_clamp_telegram_names = _clamp_command_names + + +# --------------------------------------------------------------------------- +# Shared skill/plugin collection for gateway platforms +# --------------------------------------------------------------------------- + +def _collect_gateway_skill_entries( + platform: str, + max_slots: int, + reserved_names: set[str], + desc_limit: int = 100, + sanitize_name: "Callable[[str], str] | None" = None, +) -> tuple[list[tuple[str, str, str]], int]: + """Collect plugin + skill entries for a gateway platform. + + Priority order: + 1. Plugin slash commands (take precedence over skills) + 2. Built-in skill commands (fill remaining slots, alphabetical) + + Only skills are trimmed when the cap is reached. + Hub-installed skills are excluded. Per-platform disabled skills are + excluded. + + Args: + platform: Platform identifier for per-platform skill filtering + (``"telegram"``, ``"discord"``, etc.). + max_slots: Maximum number of entries to return (remaining slots after + built-in/core commands). + reserved_names: Names already taken by built-in commands. Mutated + in-place as new names are added. + desc_limit: Max description length (40 for Telegram, 100 for Discord). + sanitize_name: Optional name transform applied before clamping, e.g. + :func:`_sanitize_telegram_name` for Telegram. May return an + empty string to signal "skip this entry". + + Returns: + ``(entries, hidden_count)`` where *entries* is a list of + ``(name, description, cmd_key)`` triples and *hidden_count* is the + number of skill entries dropped due to the cap. ``cmd_key`` is the + original ``/skill-name`` key from :func:`get_skill_commands`. + """ + all_entries: list[tuple[str, str, str]] = [] + + # --- Tier 1: Plugin slash commands (never trimmed) --------------------- + plugin_pairs: list[tuple[str, str]] = [] + try: + from hermes_cli.plugins import get_plugin_manager + pm = get_plugin_manager() + plugin_cmds = getattr(pm, "_plugin_commands", {}) + for cmd_name in sorted(plugin_cmds): + name = sanitize_name(cmd_name) if sanitize_name else cmd_name + if not name: + continue + desc = "Plugin command" + if len(desc) > desc_limit: + desc = desc[:desc_limit - 3] + "..." + plugin_pairs.append((name, desc)) + except Exception: + pass + + plugin_pairs = _clamp_command_names(plugin_pairs, reserved_names) + reserved_names.update(n for n, _ in plugin_pairs) + # Plugins have no cmd_key — use empty string as placeholder + for n, d in plugin_pairs: + all_entries.append((n, d, "")) + + # --- Tier 2: Built-in skill commands (trimmed at cap) ----------------- + _platform_disabled: set[str] = set() + try: + from agent.skill_utils import get_disabled_skill_names + _platform_disabled = get_disabled_skill_names(platform=platform) + except Exception: + pass + + skill_triples: list[tuple[str, str, str]] = [] + try: + from agent.skill_commands import get_skill_commands + from tools.skills_tool import SKILLS_DIR + _skills_dir = str(SKILLS_DIR.resolve()) + _hub_dir = str((SKILLS_DIR / ".hub").resolve()) + skill_cmds = get_skill_commands() + for cmd_key in sorted(skill_cmds): + info = skill_cmds[cmd_key] + skill_path = info.get("skill_md_path", "") + if not skill_path.startswith(_skills_dir): + continue + if skill_path.startswith(_hub_dir): + continue + skill_name = info.get("name", "") + if skill_name in _platform_disabled: + continue + raw_name = cmd_key.lstrip("/") + name = sanitize_name(raw_name) if sanitize_name else raw_name + if not name: + continue + desc = info.get("description", "") + if len(desc) > desc_limit: + desc = desc[:desc_limit - 3] + "..." + skill_triples.append((name, desc, cmd_key)) + except Exception: + pass + + # Clamp names; _clamp_command_names works on (name, desc) pairs so we + # need to zip/unzip. + skill_pairs = [(n, d) for n, d, _ in skill_triples] + key_by_pair = {(n, d): k for n, d, k in skill_triples} + skill_pairs = _clamp_command_names(skill_pairs, reserved_names) + + # Skills fill remaining slots — only tier that gets trimmed + remaining = max(0, max_slots - len(all_entries)) + hidden_count = max(0, len(skill_pairs) - remaining) + for n, d in skill_pairs[:remaining]: + all_entries.append((n, d, key_by_pair.get((n, d), ""))) + + return all_entries[:max_slots], hidden_count + + +# --------------------------------------------------------------------------- +# Platform-specific wrappers +# --------------------------------------------------------------------------- + +def telegram_menu_commands(max_commands: int = 100) -> tuple[list[tuple[str, str]], int]: + """Return Telegram menu commands capped to the Bot API limit. + + Priority order (higher priority = never bumped by overflow): + 1. Core CommandDef commands (always included) + 2. Plugin slash commands (take precedence over skills) + 3. Built-in skill commands (fill remaining slots, alphabetical) + + Skills are the only tier that gets trimmed when the cap is hit. + User-installed hub skills are excluded — accessible via /skills. + Skills disabled for the ``"telegram"`` platform (via ``hermes skills + config``) are excluded from the menu entirely. + + Returns: + (menu_commands, hidden_count) where hidden_count is the number of + skill commands omitted due to the cap. + """ + core_commands = list(telegram_bot_commands()) + reserved_names = {n for n, _ in core_commands} + all_commands = list(core_commands) + + remaining_slots = max(0, max_commands - len(all_commands)) + entries, hidden_count = _collect_gateway_skill_entries( + platform="telegram", + max_slots=remaining_slots, + reserved_names=reserved_names, + desc_limit=40, + sanitize_name=_sanitize_telegram_name, + ) + # Drop the cmd_key — Telegram only needs (name, desc) pairs. + all_commands.extend((n, d) for n, d, _k in entries) + return all_commands[:max_commands], hidden_count + + +def discord_skill_commands( + max_slots: int, + reserved_names: set[str], +) -> tuple[list[tuple[str, str, str]], int]: + """Return skill entries for Discord slash command registration. + + Same priority and filtering logic as :func:`telegram_menu_commands` + (plugins > skills, hub excluded, per-platform disabled excluded), but + adapted for Discord's constraints: + + - Hyphens are allowed in names (no ``-`` → ``_`` sanitization) + - Descriptions capped at 100 chars (Discord's per-field max) + + Args: + max_slots: Available command slots (100 minus existing built-in count). + reserved_names: Names of already-registered built-in commands. + + Returns: + ``(entries, hidden_count)`` where *entries* is a list of + ``(discord_name, description, cmd_key)`` triples. ``cmd_key`` is + the original ``/skill-name`` key needed for the slash handler callback. + """ + return _collect_gateway_skill_entries( + platform="discord", + max_slots=max_slots, + reserved_names=set(reserved_names), # copy — don't mutate caller's set + desc_limit=100, + ) + + +def slack_subcommand_map() -> dict[str, str]: + """Return subcommand -> /command mapping for Slack /hermes handler. + + Maps both canonical names and aliases so /hermes bg do stuff works + the same as /hermes background do stuff. + """ + overrides = _resolve_config_gates() + mapping: dict[str, str] = {} + for cmd in COMMAND_REGISTRY: + if not _is_gateway_available(cmd, overrides): + continue + mapping[cmd.name] = f"/{cmd.name}" + for alias in cmd.aliases: + mapping[alias] = f"/{alias}" + return mapping + + +# --------------------------------------------------------------------------- +# Autocomplete +# --------------------------------------------------------------------------- + +class SlashCommandCompleter(Completer): + """Autocomplete for built-in slash commands, subcommands, and skill commands.""" + + def __init__( + self, + skill_commands_provider: Callable[[], Mapping[str, dict[str, Any]]] | None = None, + command_filter: Callable[[str], bool] | None = None, + ) -> None: + self._skill_commands_provider = skill_commands_provider + self._command_filter = command_filter + # Cached project file list for fuzzy @ completions + self._file_cache: list[str] = [] + self._file_cache_time: float = 0.0 + self._file_cache_cwd: str = "" + + def _command_allowed(self, slash_command: str) -> bool: + if self._command_filter is None: + return True + try: + return bool(self._command_filter(slash_command)) + except Exception: + return True + + def _iter_skill_commands(self) -> Mapping[str, dict[str, Any]]: + if self._skill_commands_provider is None: + return {} + try: + return self._skill_commands_provider() or {} + except Exception: + return {} + + @staticmethod + def _completion_text(cmd_name: str, word: str) -> str: + """Return replacement text for a completion. + + When the user has already typed the full command exactly (``/help``), + returning ``help`` would be a no-op and prompt_toolkit suppresses the + menu. Appending a trailing space keeps the dropdown visible and makes + backspacing retrigger it naturally. + """ + return f"{cmd_name} " if cmd_name == word else cmd_name + + @staticmethod + def _extract_path_word(text: str) -> str | None: + """Extract the current word if it looks like a file path. + + Returns the path-like token under the cursor, or None if the + current word doesn't look like a path. A word is path-like when + it starts with ``./``, ``../``, ``~/``, ``/``, or contains a + ``/`` separator (e.g. ``src/main.py``). + """ + if not text: + return None + # Walk backwards to find the start of the current "word". + # Words are delimited by spaces, but paths can contain almost anything. + i = len(text) - 1 + while i >= 0 and text[i] != " ": + i -= 1 + word = text[i + 1:] + if not word: + return None + # Only trigger path completion for path-like tokens + if word.startswith(("./", "../", "~/", "/")) or "/" in word: + return word + return None + + @staticmethod + def _path_completions(word: str, limit: int = 30): + """Yield Completion objects for file paths matching *word*.""" + expanded = os.path.expanduser(word) + # Split into directory part and prefix to match inside it + if expanded.endswith("/"): + search_dir = expanded + prefix = "" + else: + search_dir = os.path.dirname(expanded) or "." + prefix = os.path.basename(expanded) + + try: + entries = os.listdir(search_dir) + except OSError: + return + + count = 0 + prefix_lower = prefix.lower() + for entry in sorted(entries): + if prefix and not entry.lower().startswith(prefix_lower): + continue + if count >= limit: + break + + full_path = os.path.join(search_dir, entry) + is_dir = os.path.isdir(full_path) + + # Build the completion text (what replaces the typed word) + if word.startswith("~"): + display_path = "~/" + os.path.relpath(full_path, os.path.expanduser("~")) + elif os.path.isabs(word): + display_path = full_path + else: + # Keep relative + display_path = os.path.relpath(full_path) + + if is_dir: + display_path += "/" + + suffix = "/" if is_dir else "" + meta = "dir" if is_dir else _file_size_label(full_path) + + yield Completion( + display_path, + start_position=-len(word), + display=entry + suffix, + display_meta=meta, + ) + count += 1 + + @staticmethod + def _extract_context_word(text: str) -> str | None: + """Extract a bare ``@`` token for context reference completions.""" + if not text: + return None + # Walk backwards to find the start of the current word + i = len(text) - 1 + while i >= 0 and text[i] != " ": + i -= 1 + word = text[i + 1:] + if not word.startswith("@"): + return None + return word + + @staticmethod + def _context_completions(word: str, limit: int = 30): + """Yield Claude Code-style @ context completions. + + Bare ``@`` or ``@partial`` shows static references and matching + files/folders. ``@file:path`` and ``@folder:path`` are handled + by the existing path completion path. + """ + lowered = word.lower() + + # Static context references + _STATIC_REFS = ( + ("@diff", "Git working tree diff"), + ("@staged", "Git staged diff"), + ("@file:", "Attach a file"), + ("@folder:", "Attach a folder"), + ("@git:", "Git log with diffs (e.g. @git:5)"), + ("@url:", "Fetch web content"), + ) + for candidate, meta in _STATIC_REFS: + if candidate.lower().startswith(lowered) and candidate.lower() != lowered: + yield Completion( + candidate, + start_position=-len(word), + display=candidate, + display_meta=meta, + ) + + # If the user typed @file: or @folder:, delegate to path completions + for prefix in ("@file:", "@folder:"): + if word.startswith(prefix): + path_part = word[len(prefix):] or "." + expanded = os.path.expanduser(path_part) + if expanded.endswith("/"): + search_dir, match_prefix = expanded, "" + else: + search_dir = os.path.dirname(expanded) or "." + match_prefix = os.path.basename(expanded) + + try: + entries = os.listdir(search_dir) + except OSError: + return + + count = 0 + prefix_lower = match_prefix.lower() + for entry in sorted(entries): + if match_prefix and not entry.lower().startswith(prefix_lower): + continue + if count >= limit: + break + full_path = os.path.join(search_dir, entry) + is_dir = os.path.isdir(full_path) + display_path = os.path.relpath(full_path) + suffix = "/" if is_dir else "" + kind = "folder" if is_dir else "file" + meta = "dir" if is_dir else _file_size_label(full_path) + completion = f"@{kind}:{display_path}{suffix}" + yield Completion( + completion, + start_position=-len(word), + display=entry + suffix, + display_meta=meta, + ) + count += 1 + return + + # Bare @ or @partial — fuzzy project-wide file search + query = word[1:] # strip the @ + yield from self._fuzzy_file_completions(word, query, limit) + + def _get_project_files(self) -> list[str]: + """Return cached list of project files (refreshed every 5s).""" + cwd = os.getcwd() + now = time.monotonic() + if ( + self._file_cache + and self._file_cache_cwd == cwd + and now - self._file_cache_time < 5.0 + ): + return self._file_cache + + files: list[str] = [] + # Try rg first (fast, respects .gitignore), then fd, then find. + for cmd in [ + ["rg", "--files", "--sortr=modified", cwd], + ["rg", "--files", cwd], + ["fd", "--type", "f", "--base-directory", cwd], + ]: + tool = cmd[0] + if not shutil.which(tool): + continue + try: + proc = subprocess.run( + cmd, capture_output=True, text=True, timeout=2, + cwd=cwd, + ) + if proc.returncode == 0 and proc.stdout.strip(): + raw = proc.stdout.strip().split("\n") + # Store relative paths + for p in raw[:5000]: + rel = os.path.relpath(p, cwd) if os.path.isabs(p) else p + files.append(rel) + break + except (subprocess.TimeoutExpired, OSError): + continue + + self._file_cache = files + self._file_cache_time = now + self._file_cache_cwd = cwd + return files + + @staticmethod + def _score_path(filepath: str, query: str) -> int: + """Score a file path against a fuzzy query. Higher = better match.""" + if not query: + return 1 # show everything when query is empty + + filename = os.path.basename(filepath) + lower_file = filename.lower() + lower_path = filepath.lower() + lower_q = query.lower() + + # Exact filename match + if lower_file == lower_q: + return 100 + # Filename starts with query + if lower_file.startswith(lower_q): + return 80 + # Filename contains query as substring + if lower_q in lower_file: + return 60 + # Full path contains query + if lower_q in lower_path: + return 40 + # Initials / abbreviation match: e.g. "fo" matches "file_operations" + # Check if query chars appear in order in filename + qi = 0 + for c in lower_file: + if qi < len(lower_q) and c == lower_q[qi]: + qi += 1 + if qi == len(lower_q): + # Bonus if matches land on word boundaries (after _, -, /, .) + boundary_hits = 0 + qi = 0 + prev = "_" # treat start as boundary + for c in lower_file: + if qi < len(lower_q) and c == lower_q[qi]: + if prev in "_-./": + boundary_hits += 1 + qi += 1 + prev = c + if boundary_hits >= len(lower_q) * 0.5: + return 35 + return 25 + return 0 + + def _fuzzy_file_completions(self, word: str, query: str, limit: int = 20): + """Yield fuzzy file completions for bare @query.""" + files = self._get_project_files() + + if not query: + # No query — show recently modified files (already sorted by mtime) + for fp in files[:limit]: + is_dir = fp.endswith("/") + filename = os.path.basename(fp) + kind = "folder" if is_dir else "file" + meta = "dir" if is_dir else _file_size_label( + os.path.join(os.getcwd(), fp) + ) + yield Completion( + f"@{kind}:{fp}", + start_position=-len(word), + display=filename, + display_meta=meta, + ) + return + + # Score and rank + scored = [] + for fp in files: + s = self._score_path(fp, query) + if s > 0: + scored.append((s, fp)) + scored.sort(key=lambda x: (-x[0], x[1])) + + for _, fp in scored[:limit]: + is_dir = fp.endswith("/") + filename = os.path.basename(fp) + kind = "folder" if is_dir else "file" + meta = "dir" if is_dir else _file_size_label( + os.path.join(os.getcwd(), fp) + ) + yield Completion( + f"@{kind}:{fp}", + start_position=-len(word), + display=filename, + display_meta=f"{fp} {meta}" if meta else fp, + ) + + def _model_completions(self, sub_text: str, sub_lower: str): + """Yield completions for /model from config aliases + built-in aliases.""" + seen = set() + # Config-based direct aliases (preferred — include provider info) + try: + from hermes_cli.model_switch import ( + _ensure_direct_aliases, DIRECT_ALIASES, MODEL_ALIASES, + ) + _ensure_direct_aliases() + for name, da in DIRECT_ALIASES.items(): + if name.startswith(sub_lower) and name != sub_lower: + seen.add(name) + yield Completion( + name, + start_position=-len(sub_text), + display=name, + display_meta=f"{da.model} ({da.provider})", + ) + # Built-in catalog aliases not already covered + for name in sorted(MODEL_ALIASES.keys()): + if name in seen: + continue + if name.startswith(sub_lower) and name != sub_lower: + identity = MODEL_ALIASES[name] + yield Completion( + name, + start_position=-len(sub_text), + display=name, + display_meta=f"{identity.vendor}/{identity.family}", + ) + except Exception: + pass + + def get_completions(self, document, complete_event): + text = document.text_before_cursor + if not text.startswith("/"): + # Try @ context completion (Claude Code-style) + ctx_word = self._extract_context_word(text) + if ctx_word is not None: + yield from self._context_completions(ctx_word) + return + # Try file path completion for non-slash input + path_word = self._extract_path_word(text) + if path_word is not None: + yield from self._path_completions(path_word) + return + + # Check if we're completing a subcommand (base command already typed) + parts = text.split(maxsplit=1) + base_cmd = parts[0].lower() + if len(parts) > 1 or (len(parts) == 1 and text.endswith(" ")): + sub_text = parts[1] if len(parts) > 1 else "" + sub_lower = sub_text.lower() + + # Dynamic model alias completions for /model + if " " not in sub_text and base_cmd == "/model": + yield from self._model_completions(sub_text, sub_lower) + return + + # Static subcommand completions + if " " not in sub_text and base_cmd in SUBCOMMANDS and self._command_allowed(base_cmd): + for sub in SUBCOMMANDS[base_cmd]: + if sub.startswith(sub_lower) and sub != sub_lower: + yield Completion( + sub, + start_position=-len(sub_text), + display=sub, + ) + return + + word = text[1:] + + for cmd, desc in COMMANDS.items(): + if not self._command_allowed(cmd): + continue + cmd_name = cmd[1:] + if cmd_name.startswith(word): + yield Completion( + self._completion_text(cmd_name, word), + start_position=-len(word), + display=cmd, + display_meta=desc, + ) + + for cmd, info in self._iter_skill_commands().items(): + cmd_name = cmd[1:] + if cmd_name.startswith(word): + description = str(info.get("description", "Skill command")) + short_desc = description[:50] + ("..." if len(description) > 50 else "") + yield Completion( + self._completion_text(cmd_name, word), + start_position=-len(word), + display=cmd, + display_meta=f"⚡ {short_desc}", + ) + + +# --------------------------------------------------------------------------- +# Inline auto-suggest (ghost text) for slash commands +# --------------------------------------------------------------------------- + +class SlashCommandAutoSuggest(AutoSuggest): + """Inline ghost-text suggestions for slash commands and their subcommands. + + Shows the rest of a command or subcommand in dim text as you type. + Falls back to history-based suggestions for non-slash input. + """ + + def __init__( + self, + history_suggest: AutoSuggest | None = None, + completer: SlashCommandCompleter | None = None, + ) -> None: + self._history = history_suggest + self._completer = completer # Reuse its model cache + + def get_suggestion(self, buffer, document): + text = document.text_before_cursor + + # Only suggest for slash commands + if not text.startswith("/"): + # Fall back to history for regular text + if self._history: + return self._history.get_suggestion(buffer, document) + return None + + parts = text.split(maxsplit=1) + base_cmd = parts[0].lower() + + if len(parts) == 1 and not text.endswith(" "): + # Still typing the command name: /upd → suggest "ate" + word = text[1:].lower() + for cmd in COMMANDS: + if self._completer is not None and not self._completer._command_allowed(cmd): + continue + cmd_name = cmd[1:] # strip leading / + if cmd_name.startswith(word) and cmd_name != word: + return Suggestion(cmd_name[len(word):]) + return None + + # Command is complete — suggest subcommands or model names + sub_text = parts[1] if len(parts) > 1 else "" + sub_lower = sub_text.lower() + + # Static subcommands + if self._completer is not None and not self._completer._command_allowed(base_cmd): + return None + if base_cmd in SUBCOMMANDS and SUBCOMMANDS[base_cmd]: + if " " not in sub_text: + for sub in SUBCOMMANDS[base_cmd]: + if sub.startswith(sub_lower) and sub != sub_lower: + return Suggestion(sub[len(sub_text):]) + + # Fall back to history + if self._history: + return self._history.get_suggestion(buffer, document) + return None + + +def _file_size_label(path: str) -> str: + """Return a compact human-readable file size, or '' on error.""" + try: + size = os.path.getsize(path) + except OSError: + return "" + if size < 1024: + return f"{size}B" + if size < 1024 * 1024: + return f"{size / 1024:.0f}K" + if size < 1024 * 1024 * 1024: + return f"{size / (1024 * 1024):.1f}M" + return f"{size / (1024 * 1024 * 1024):.1f}G" diff --git a/mindcli/_vendor/hermes_cli/config.py b/mindcli/_vendor/hermes_cli/config.py new file mode 100644 index 0000000..78cc301 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/config.py @@ -0,0 +1,3356 @@ +""" +Configuration management for Hermes Agent. + +Config files are stored in ~/.hermes/ for easy access: +- ~/.hermes/config.yaml - All settings (model, toolsets, terminal, etc.) +- ~/.hermes/.env - API keys and secrets + +This module provides: +- hermes config - Show current configuration +- hermes config edit - Open config in editor +- hermes config set - Set a specific value +- hermes config wizard - Re-run setup wizard +""" + +import os +import platform +import re +import stat +import subprocess +import sys +import tempfile +from dataclasses import dataclass +from pathlib import Path +from typing import Dict, Any, Optional, List, Tuple + +from tools.tool_backend_helpers import managed_nous_tools_enabled as _managed_nous_tools_enabled + +_IS_WINDOWS = platform.system() == "Windows" +_ENV_VAR_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$") +# Env var names written to .env that aren't in OPTIONAL_ENV_VARS +# (managed by setup/provider flows directly). +_EXTRA_ENV_KEYS = frozenset({ + "OPENAI_API_KEY", "OPENAI_BASE_URL", + "ANTHROPIC_API_KEY", "ANTHROPIC_TOKEN", + "DISCORD_HOME_CHANNEL", "TELEGRAM_HOME_CHANNEL", + "SIGNAL_ACCOUNT", "SIGNAL_HTTP_URL", + "SIGNAL_ALLOWED_USERS", "SIGNAL_GROUP_ALLOWED_USERS", + "DINGTALK_CLIENT_ID", "DINGTALK_CLIENT_SECRET", + "FEISHU_APP_ID", "FEISHU_APP_SECRET", "FEISHU_ENCRYPT_KEY", "FEISHU_VERIFICATION_TOKEN", + "WECOM_BOT_ID", "WECOM_SECRET", + "WECOM_CALLBACK_CORP_ID", "WECOM_CALLBACK_CORP_SECRET", "WECOM_CALLBACK_AGENT_ID", + "WECOM_CALLBACK_TOKEN", "WECOM_CALLBACK_ENCODING_AES_KEY", + "WECOM_CALLBACK_HOST", "WECOM_CALLBACK_PORT", + "WEIXIN_ACCOUNT_ID", "WEIXIN_TOKEN", "WEIXIN_BASE_URL", "WEIXIN_CDN_BASE_URL", + "WEIXIN_HOME_CHANNEL", "WEIXIN_HOME_CHANNEL_NAME", "WEIXIN_DM_POLICY", "WEIXIN_GROUP_POLICY", + "WEIXIN_ALLOWED_USERS", "WEIXIN_GROUP_ALLOWED_USERS", "WEIXIN_ALLOW_ALL_USERS", + "BLUEBUBBLES_SERVER_URL", "BLUEBUBBLES_PASSWORD", + "QQ_APP_ID", "QQ_CLIENT_SECRET", "QQ_HOME_CHANNEL", "QQ_HOME_CHANNEL_NAME", + "QQ_ALLOWED_USERS", "QQ_GROUP_ALLOWED_USERS", "QQ_ALLOW_ALL_USERS", "QQ_MARKDOWN_SUPPORT", + "QQ_STT_API_KEY", "QQ_STT_BASE_URL", "QQ_STT_MODEL", + "TERMINAL_ENV", "TERMINAL_SSH_KEY", "TERMINAL_SSH_PORT", + "WHATSAPP_MODE", "WHATSAPP_ENABLED", + "MATTERMOST_HOME_CHANNEL", "MATTERMOST_REPLY_MODE", + "MATRIX_PASSWORD", "MATRIX_ENCRYPTION", "MATRIX_DEVICE_ID", "MATRIX_HOME_ROOM", + "MATRIX_REQUIRE_MENTION", "MATRIX_FREE_RESPONSE_ROOMS", "MATRIX_AUTO_THREAD", + "MATRIX_RECOVERY_KEY", +}) +import yaml + +from hermes_cli.colors import Colors, color +from hermes_cli.default_soul import DEFAULT_SOUL_MD + + +# ============================================================================= +# Managed mode (NixOS declarative config) +# ============================================================================= + +_MANAGED_TRUE_VALUES = ("true", "1", "yes") +_MANAGED_SYSTEM_NAMES = { + "brew": "Homebrew", + "homebrew": "Homebrew", + "nix": "NixOS", + "nixos": "NixOS", +} + + +def get_managed_system() -> Optional[str]: + """Return the package manager owning this install, if any.""" + raw = os.getenv("HERMES_MANAGED", "").strip() + if raw: + normalized = raw.lower() + if normalized in _MANAGED_TRUE_VALUES: + return "NixOS" + return _MANAGED_SYSTEM_NAMES.get(normalized, raw) + + managed_marker = get_hermes_home() / ".managed" + if managed_marker.exists(): + return "NixOS" + return None + + +def is_managed() -> bool: + """Check if Hermes is running in package-manager-managed mode. + + Two signals: the HERMES_MANAGED env var (set by the systemd service), + or a .managed marker file in HERMES_HOME (set by the NixOS activation + script, so interactive shells also see it). + """ + return get_managed_system() is not None + + +def get_managed_update_command() -> Optional[str]: + """Return the preferred upgrade command for a managed install.""" + managed_system = get_managed_system() + if managed_system == "Homebrew": + return "brew upgrade hermes-agent" + if managed_system == "NixOS": + return "sudo nixos-rebuild switch" + return None + + +def recommended_update_command() -> str: + """Return the best update command for the current installation.""" + return get_managed_update_command() or "hermes update" + + +def format_managed_message(action: str = "modify this Hermes installation") -> str: + """Build a user-facing error for managed installs.""" + managed_system = get_managed_system() or "a package manager" + raw = os.getenv("HERMES_MANAGED", "").strip().lower() + + if managed_system == "NixOS": + env_hint = "true" if raw in _MANAGED_TRUE_VALUES else raw or "true" + return ( + f"Cannot {action}: this Hermes installation is managed by NixOS " + f"(HERMES_MANAGED={env_hint}).\n" + "Edit services.hermes-agent.settings in your configuration.nix and run:\n" + " sudo nixos-rebuild switch" + ) + + if managed_system == "Homebrew": + env_hint = raw or "homebrew" + return ( + f"Cannot {action}: this Hermes installation is managed by Homebrew " + f"(HERMES_MANAGED={env_hint}).\n" + "Use:\n" + " brew upgrade hermes-agent" + ) + + return ( + f"Cannot {action}: this Hermes installation is managed by {managed_system}.\n" + "Use your package manager to upgrade or reinstall Hermes." + ) + +def managed_error(action: str = "modify configuration"): + """Print user-friendly error for managed mode.""" + print(format_managed_message(action), file=sys.stderr) + + +# ============================================================================= +# Container-aware CLI (NixOS container mode) +# ============================================================================= + +def get_container_exec_info() -> Optional[dict]: + """Read container mode metadata from HERMES_HOME/.container-mode. + + Returns a dict with keys: backend, container_name, exec_user, hermes_bin + or None if container mode is not active, we're already inside the + container, or HERMES_DEV=1 is set. + + The .container-mode file is written by the NixOS activation script when + container.enable = true. It tells the host CLI to exec into the container + instead of running locally. + """ + if os.environ.get("HERMES_DEV") == "1": + return None + + from hermes_constants import is_container + if is_container(): + return None + + container_mode_file = get_hermes_home() / ".container-mode" + + try: + info = {} + with open(container_mode_file, "r") as f: + for line in f: + line = line.strip() + if "=" in line and not line.startswith("#"): + key, _, value = line.partition("=") + info[key.strip()] = value.strip() + except FileNotFoundError: + return None + # All other exceptions (PermissionError, malformed data, etc.) propagate + + backend = info.get("backend", "docker") + container_name = info.get("container_name", "hermes-agent") + exec_user = info.get("exec_user", "hermes") + hermes_bin = info.get("hermes_bin", "/data/current-package/bin/hermes") + + return { + "backend": backend, + "container_name": container_name, + "exec_user": exec_user, + "hermes_bin": hermes_bin, + } + + +# ============================================================================= +# Config paths +# ============================================================================= + +# Re-export from hermes_constants — canonical definition lives there. +from hermes_constants import get_hermes_home # noqa: F811,E402 + +def get_config_path() -> Path: + """Get the main config file path.""" + return get_hermes_home() / "config.yaml" + +def get_env_path() -> Path: + """Get the .env file path (for API keys).""" + return get_hermes_home() / ".env" + +def get_project_root() -> Path: + """Get the project installation directory.""" + return Path(__file__).parent.parent.resolve() + +def _secure_dir(path): + """Set directory to owner-only access (0700 by default). No-op on Windows. + + Skipped in managed mode — the NixOS module sets group-readable + permissions (0750) so interactive users in the hermes group can + share state with the gateway service. + + The mode can be overridden via the HERMES_HOME_MODE environment variable + (e.g. HERMES_HOME_MODE=0701) for deployments where a web server (nginx, + caddy, etc.) needs to traverse HERMES_HOME to reach a served subdirectory. + The execute-only bit on a directory permits cd-through without exposing + directory listings. + """ + if is_managed(): + return + try: + mode_str = os.environ.get("HERMES_HOME_MODE", "").strip() + mode = int(mode_str, 8) if mode_str else 0o700 + except ValueError: + mode = 0o700 + try: + os.chmod(path, mode) + except (OSError, NotImplementedError): + pass + + +def _secure_file(path): + """Set file to owner-only read/write (0600). No-op on Windows. + + Skipped in managed mode — the NixOS activation script sets + group-readable permissions (0640) on config files. + """ + if is_managed(): + return + try: + if os.path.exists(str(path)): + os.chmod(path, 0o600) + except (OSError, NotImplementedError): + pass + + +def _ensure_default_soul_md(home: Path) -> None: + """Seed a default SOUL.md into HERMES_HOME if the user doesn't have one yet.""" + soul_path = home / "SOUL.md" + if soul_path.exists(): + return + soul_path.write_text(DEFAULT_SOUL_MD, encoding="utf-8") + _secure_file(soul_path) + + +def ensure_hermes_home(): + """Ensure ~/.hermes directory structure exists with secure permissions. + + In managed mode (NixOS), dirs are created by the activation script with + setgid + group-writable (2770). We skip mkdir and set umask(0o007) so + any files created (e.g. SOUL.md) are group-writable (0660). + """ + home = get_hermes_home() + if is_managed(): + old_umask = os.umask(0o007) + try: + _ensure_hermes_home_managed(home) + finally: + os.umask(old_umask) + else: + home.mkdir(parents=True, exist_ok=True) + _secure_dir(home) + for subdir in ("cron", "sessions", "logs", "memories"): + d = home / subdir + d.mkdir(parents=True, exist_ok=True) + _secure_dir(d) + _ensure_default_soul_md(home) + + +def _ensure_hermes_home_managed(home: Path): + """Managed-mode variant: verify dirs exist (activation creates them), seed SOUL.md.""" + if not home.is_dir(): + raise RuntimeError( + f"HERMES_HOME {home} does not exist. " + "Run 'sudo nixos-rebuild switch' first." + ) + for subdir in ("cron", "sessions", "logs", "memories"): + d = home / subdir + if not d.is_dir(): + raise RuntimeError( + f"{d} does not exist. " + "Run 'sudo nixos-rebuild switch' first." + ) + # Inside umask(0o007) scope — SOUL.md will be created as 0660 + _ensure_default_soul_md(home) + + +# ============================================================================= +# Config loading/saving +# ============================================================================= + +DEFAULT_CONFIG = { + "model": "", + "providers": {}, + "fallback_providers": [], + "credential_pool_strategies": {}, + "toolsets": ["hermes-cli"], + "agent": { + "max_turns": 90, + # Inactivity timeout for gateway agent execution (seconds). + # The agent can run indefinitely as long as it's actively calling + # tools or receiving API responses. Only fires when the agent has + # been completely idle for this duration. 0 = unlimited. + "gateway_timeout": 1800, + # Graceful drain timeout for gateway stop/restart (seconds). + # The gateway stops accepting new work, waits for running agents + # to finish, then interrupts any remaining runs after the timeout. + # 0 = no drain, interrupt immediately. + "restart_drain_timeout": 60, + "service_tier": "", + # Tool-use enforcement: injects system prompt guidance that tells the + # model to actually call tools instead of describing intended actions. + # Values: "auto" (default — applies to gpt/codex models), true/false + # (force on/off for all models), or a list of model-name substrings + # to match (e.g. ["gpt", "codex", "gemini", "qwen"]). + "tool_use_enforcement": "auto", + # Staged inactivity warning: send a warning to the user at this + # threshold before escalating to a full timeout. The warning fires + # once per run and does not interrupt the agent. 0 = disable warning. + "gateway_timeout_warning": 900, + # Periodic "still working" notification interval (seconds). + # Sends a status message every N seconds so the user knows the + # agent hasn't died during long tasks. 0 = disable notifications. + "gateway_notify_interval": 600, + }, + + "terminal": { + "backend": "local", + "modal_mode": "auto", + "cwd": ".", # Use current directory + "timeout": 180, + # Environment variables to pass through to sandboxed execution + # (terminal and execute_code). Skill-declared required_environment_variables + # are passed through automatically; this list is for non-skill use cases. + "env_passthrough": [], + "docker_image": "nikolaik/python-nodejs:python3.11-nodejs20", + "docker_forward_env": [], + # Explicit environment variables to set inside Docker containers. + # Unlike docker_forward_env (which reads values from the host process), + # docker_env lets you specify exact key-value pairs — useful when Hermes + # runs as a systemd service without access to the user's shell environment. + # Example: {"SSH_AUTH_SOCK": "/run/user/1000/ssh-agent.sock"} + "docker_env": {}, + "singularity_image": "docker://nikolaik/python-nodejs:python3.11-nodejs20", + "modal_image": "nikolaik/python-nodejs:python3.11-nodejs20", + "daytona_image": "nikolaik/python-nodejs:python3.11-nodejs20", + # Container resource limits (docker, singularity, modal, daytona — ignored for local/ssh) + "container_cpu": 1, + "container_memory": 5120, # MB (default 5GB) + "container_disk": 51200, # MB (default 50GB) + "container_persistent": True, # Persist filesystem across sessions + # Docker volume mounts — share host directories with the container. + # Each entry is "host_path:container_path" (standard Docker -v syntax). + # Example: ["/home/user/projects:/workspace/projects", "/data:/data"] + "docker_volumes": [], + # Explicit opt-in: mount the host cwd into /workspace for Docker sessions. + # Default off because passing host directories into a sandbox weakens isolation. + "docker_mount_cwd_to_workspace": False, + # Persistent shell — keep a long-lived bash shell across execute() calls + # so cwd/env vars/shell variables survive between commands. + # Enabled by default for non-local backends (SSH); local is always opt-in + # via TERMINAL_LOCAL_PERSISTENT env var. + "persistent_shell": True, + }, + + "browser": { + "inactivity_timeout": 120, + "command_timeout": 30, # Timeout for browser commands in seconds (screenshot, navigate, etc.) + "record_sessions": False, # Auto-record browser sessions as WebM videos + "allow_private_urls": False, # Allow navigating to private/internal IPs (localhost, 192.168.x.x, etc.) + "camofox": { + # When true, Hermes sends a stable profile-scoped userId to Camofox + # so the server can map it to a persistent browser profile directory. + # Requires Camofox server to be configured with CAMOFOX_PROFILE_DIR. + # When false (default), each session gets a random userId (ephemeral). + "managed_persistence": False, + }, + }, + + # Filesystem checkpoints — automatic snapshots before destructive file ops. + # When enabled, the agent takes a snapshot of the working directory once per + # conversation turn (on first write_file/patch call). Use /rollback to restore. + "checkpoints": { + "enabled": True, + "max_snapshots": 50, # Max checkpoints to keep per directory + }, + + # Maximum characters returned by a single read_file call. Reads that + # exceed this are rejected with guidance to use offset+limit. + # 100K chars ≈ 25–35K tokens across typical tokenisers. + "file_read_max_chars": 100_000, + + "compression": { + "enabled": True, + "threshold": 0.50, # compress when context usage exceeds this ratio + "target_ratio": 0.20, # fraction of threshold to preserve as recent tail + "protect_last_n": 20, # minimum recent messages to keep uncompressed + + }, + "smart_model_routing": { + "enabled": False, + "max_simple_chars": 160, + "max_simple_words": 28, + "cheap_model": {}, + }, + + # Auxiliary model config — provider:model for each side task. + # Format: provider is the provider name, model is the model slug. + # "auto" for provider = auto-detect best available provider. + # Empty model = use provider's default auxiliary model. + # All tasks fall back to openrouter:google/gemini-3-flash-preview if + # the configured provider is unavailable. + "auxiliary": { + "vision": { + "provider": "auto", # auto | openrouter | nous | codex | custom + "model": "", # e.g. "google/gemini-2.5-flash", "gpt-4o" + "base_url": "", # direct OpenAI-compatible endpoint (takes precedence over provider) + "api_key": "", # API key for base_url (falls back to OPENAI_API_KEY) + "timeout": 120, # seconds — LLM API call timeout; vision payloads need generous timeout + "download_timeout": 30, # seconds — image HTTP download timeout; increase for slow connections + }, + "web_extract": { + "provider": "auto", + "model": "", + "base_url": "", + "api_key": "", + "timeout": 360, # seconds (6min) — per-attempt LLM summarization timeout; increase for slow local models + }, + "compression": { + "provider": "auto", + "model": "", + "base_url": "", + "api_key": "", + "timeout": 120, # seconds — compression summarises large contexts; increase for local models + }, + "session_search": { + "provider": "auto", + "model": "", + "base_url": "", + "api_key": "", + "timeout": 30, + }, + "skills_hub": { + "provider": "auto", + "model": "", + "base_url": "", + "api_key": "", + "timeout": 30, + }, + "approval": { + "provider": "auto", + "model": "", # fast/cheap model recommended (e.g. gemini-flash, haiku) + "base_url": "", + "api_key": "", + "timeout": 30, + }, + "mcp": { + "provider": "auto", + "model": "", + "base_url": "", + "api_key": "", + "timeout": 30, + }, + "flush_memories": { + "provider": "auto", + "model": "", + "base_url": "", + "api_key": "", + "timeout": 30, + }, + }, + + "display": { + "compact": False, + "personality": "kawaii", + "resume_display": "full", + "busy_input_mode": "interrupt", + "bell_on_complete": False, + "show_reasoning": False, + "streaming": False, + "inline_diffs": True, # Show inline diff previews for write actions (write_file, patch, skill_manage) + "show_cost": False, # Show $ cost in the status bar (off by default) + "skin": "default", + "interim_assistant_messages": True, # Gateway: show natural mid-turn assistant status messages + "tool_progress_command": False, # Enable /verbose command in messaging gateway + "tool_progress_overrides": {}, # DEPRECATED — use display.platforms instead + "tool_preview_length": 0, # Max chars for tool call previews (0 = no limit, show full paths/commands) + "platforms": {}, # Per-platform display overrides: {"telegram": {"tool_progress": "all"}, "slack": {"tool_progress": "off"}} + }, + + # Privacy settings + "privacy": { + "redact_pii": False, # When True, hash user IDs and strip phone numbers from LLM context + }, + + # Text-to-speech configuration + "tts": { + "provider": "edge", # "edge" (free) | "elevenlabs" (premium) | "openai" | "minimax" | "mistral" | "neutts" (local) + "edge": { + "voice": "en-US-AriaNeural", + # Popular: AriaNeural, JennyNeural, AndrewNeural, BrianNeural, SoniaNeural + }, + "elevenlabs": { + "voice_id": "pNInz6obpgDQGcFmaJgB", # Adam + "model_id": "eleven_multilingual_v2", + }, + "openai": { + "model": "gpt-4o-mini-tts", + "voice": "alloy", + # Voices: alloy, echo, fable, onyx, nova, shimmer + }, + "mistral": { + "model": "voxtral-mini-tts-2603", + "voice_id": "c69964a6-ab8b-4f8a-9465-ec0925096ec8", # Paul - Neutral + }, + "neutts": { + "ref_audio": "", # Path to reference voice audio (empty = bundled default) + "ref_text": "", # Path to reference voice transcript (empty = bundled default) + "model": "neuphonic/neutts-air-q4-gguf", # HuggingFace model repo + "device": "cpu", # cpu, cuda, or mps + }, + }, + + "stt": { + "enabled": True, + "provider": "local", # "local" (free, faster-whisper) | "groq" | "openai" (Whisper API) | "mistral" (Voxtral Transcribe) + "local": { + "model": "base", # tiny, base, small, medium, large-v3 + "language": "", # auto-detect by default; set to "en", "es", "fr", etc. to force + }, + "openai": { + "model": "whisper-1", # whisper-1, gpt-4o-mini-transcribe, gpt-4o-transcribe + }, + "mistral": { + "model": "voxtral-mini-latest", # voxtral-mini-latest, voxtral-mini-2602 + }, + }, + + "voice": { + "record_key": "ctrl+b", + "max_recording_seconds": 120, + "auto_tts": False, + "silence_threshold": 200, # RMS below this = silence (0-32767) + "silence_duration": 3.0, # Seconds of silence before auto-stop + }, + + "human_delay": { + "mode": "off", + "min_ms": 800, + "max_ms": 2500, + }, + + # Context engine -- controls how the context window is managed when + # approaching the model's token limit. + # "compressor" = built-in lossy summarization (default). + # Set to a plugin name to activate an alternative engine (e.g. "lcm" + # for Lossless Context Management). The engine must be installed as + # a plugin in plugins/context_engine// or ~/.hermes/plugins/. + "context": { + "engine": "compressor", + }, + + # Persistent memory -- bounded curated memory injected into system prompt + "memory": { + "memory_enabled": True, + "user_profile_enabled": True, + "memory_char_limit": 2200, # ~800 tokens at 2.75 chars/token + "user_char_limit": 1375, # ~500 tokens at 2.75 chars/token + # External memory provider plugin (empty = built-in only). + # Set to a provider name to activate: "openviking", "mem0", + # "hindsight", "holographic", "retaindb", "byterover". + # Only ONE external provider is allowed at a time. + "provider": "", + }, + + # Subagent delegation — override the provider:model used by delegate_task + # so child agents can run on a different (cheaper/faster) provider and model. + # Uses the same runtime provider resolution as CLI/gateway startup, so all + # configured providers (OpenRouter, Nous, Z.ai, Kimi, etc.) are supported. + "delegation": { + "model": "", # e.g. "google/gemini-3-flash-preview" (empty = inherit parent model) + "provider": "", # e.g. "openrouter" (empty = inherit parent provider + credentials) + "base_url": "", # direct OpenAI-compatible endpoint for subagents + "api_key": "", # API key for delegation.base_url (falls back to OPENAI_API_KEY) + "max_iterations": 50, # per-subagent iteration cap (each subagent gets its own budget, + # independent of the parent's max_iterations) + "reasoning_effort": "", # reasoning effort for subagents: "xhigh", "high", "medium", + # "low", "minimal", "none" (empty = inherit parent's level) + }, + + # Ephemeral prefill messages file — JSON list of {role, content} dicts + # injected at the start of every API call for few-shot priming. + # Never saved to sessions, logs, or trajectories. + "prefill_messages_file": "", + + # Skills — external skill directories for sharing skills across tools/agents. + # Each path is expanded (~, ${VAR}) and resolved. Read-only — skill creation + # always goes to ~/.hermes/skills/. + "skills": { + "external_dirs": [], # e.g. ["~/.agents/skills", "/shared/team-skills"] + }, + + # Honcho AI-native memory -- reads ~/.honcho/config.json as single source of truth. + # This section is only needed for hermes-specific overrides; everything else + # (apiKey, workspace, peerName, sessions, enabled) comes from the global config. + "honcho": {}, + + # IANA timezone (e.g. "Asia/Kolkata", "America/New_York"). + # Empty string means use server-local time. + "timezone": "", + + # Discord platform settings (gateway mode) + "discord": { + "require_mention": True, # Require @mention to respond in server channels + "free_response_channels": "", # Comma-separated channel IDs where bot responds without mention + "allowed_channels": "", # If set, bot ONLY responds in these channel IDs (whitelist) + "auto_thread": True, # Auto-create threads on @mention in channels (like Slack) + "reactions": True, # Add 👀/✅/❌ reactions to messages during processing + }, + + # WhatsApp platform settings (gateway mode) + "whatsapp": { + # Reply prefix prepended to every outgoing WhatsApp message. + # Default (None) uses the built-in "⚕ *Hermes Agent*" header. + # Set to "" (empty string) to disable the header entirely. + # Supports \n for newlines, e.g. "🤖 *My Bot*\n──────\n" + }, + + # Approval mode for dangerous commands: + # manual — always prompt the user (default) + # smart — use auxiliary LLM to auto-approve low-risk commands, prompt for high-risk + # off — skip all approval prompts (equivalent to --yolo) + "approvals": { + "mode": "manual", + "timeout": 60, + }, + + # Permanently allowed dangerous command patterns (added via "always" approval) + "command_allowlist": [], + # User-defined quick commands that bypass the agent loop (type: exec only) + "quick_commands": {}, + # Custom personalities — add your own entries here + # Supports string format: {"name": "system prompt"} + # Or dict format: {"name": {"description": "...", "system_prompt": "...", "tone": "...", "style": "..."}} + "personalities": {}, + + # Pre-exec security scanning via tirith + "security": { + "redact_secrets": True, + "tirith_enabled": True, + "tirith_path": "tirith", + "tirith_timeout": 5, + "tirith_fail_open": True, + "website_blocklist": { + "enabled": False, + "domains": [], + "shared_files": [], + }, + }, + + "cron": { + # Wrap delivered cron responses with a header (task name) and footer + # ("The agent cannot see this message"). Set to false for clean output. + "wrap_response": True, + }, + + # Logging — controls file logging to ~/.hermes/logs/. + # agent.log captures INFO+ (all agent activity); errors.log captures WARNING+. + "logging": { + "level": "INFO", # Minimum level for agent.log: DEBUG, INFO, WARNING + "max_size_mb": 5, # Max size per log file before rotation + "backup_count": 3, # Number of rotated backup files to keep + }, + + # Network settings — workarounds for connectivity issues. + "network": { + # Force IPv4 connections. On servers with broken or unreachable IPv6, + # Python tries AAAA records first and hangs for the full TCP timeout + # before falling back to IPv4. Set to true to skip IPv6 entirely. + "force_ipv4": False, + }, + + # Config schema version - bump this when adding new required fields + "_config_version": 17, +} + +# ============================================================================= +# Config Migration System +# ============================================================================= + +# Track which env vars were introduced in each config version. +# Migration only mentions vars new since the user's previous version. +ENV_VARS_BY_VERSION: Dict[int, List[str]] = { + 3: ["FIRECRAWL_API_KEY", "BROWSERBASE_API_KEY", "BROWSERBASE_PROJECT_ID", "FAL_KEY"], + 4: ["VOICE_TOOLS_OPENAI_KEY", "ELEVENLABS_API_KEY"], + 5: ["WHATSAPP_ENABLED", "WHATSAPP_MODE", "WHATSAPP_ALLOWED_USERS", + "SLACK_BOT_TOKEN", "SLACK_APP_TOKEN", "SLACK_ALLOWED_USERS"], + 10: ["TAVILY_API_KEY"], + 11: ["TERMINAL_MODAL_MODE"], +} + +# Required environment variables with metadata for migration prompts. +# LLM provider is required but handled in the setup wizard's provider +# selection step (Nous Portal / OpenRouter / Custom endpoint), so this +# dict is intentionally empty — no single env var is universally required. +REQUIRED_ENV_VARS = {} + +# Optional environment variables that enhance functionality +OPTIONAL_ENV_VARS = { + # ── Provider (handled in provider selection, not shown in checklists) ── + "NOUS_BASE_URL": { + "description": "Nous Portal base URL override", + "prompt": "Nous Portal base URL (leave empty for default)", + "url": None, + "password": False, + "category": "provider", + "advanced": True, + }, + "OPENROUTER_API_KEY": { + "description": "OpenRouter API key (for vision, web scraping helpers, and MoA)", + "prompt": "OpenRouter API key", + "url": "https://openrouter.ai/keys", + "password": True, + "tools": ["vision_analyze", "mixture_of_agents"], + "category": "provider", + "advanced": True, + }, + "GOOGLE_API_KEY": { + "description": "Google AI Studio API key (also recognized as GEMINI_API_KEY)", + "prompt": "Google AI Studio API key", + "url": "https://aistudio.google.com/app/apikey", + "password": True, + "category": "provider", + "advanced": True, + }, + "GEMINI_API_KEY": { + "description": "Google AI Studio API key (alias for GOOGLE_API_KEY)", + "prompt": "Gemini API key", + "url": "https://aistudio.google.com/app/apikey", + "password": True, + "category": "provider", + "advanced": True, + }, + "GEMINI_BASE_URL": { + "description": "Google AI Studio base URL override", + "prompt": "Gemini base URL (leave empty for default)", + "url": None, + "password": False, + "category": "provider", + "advanced": True, + }, + "GLM_API_KEY": { + "description": "Z.AI / GLM API key (also recognized as ZAI_API_KEY / Z_AI_API_KEY)", + "prompt": "Z.AI / GLM API key", + "url": "https://z.ai/", + "password": True, + "category": "provider", + "advanced": True, + }, + "ZAI_API_KEY": { + "description": "Z.AI API key (alias for GLM_API_KEY)", + "prompt": "Z.AI API key", + "url": "https://z.ai/", + "password": True, + "category": "provider", + "advanced": True, + }, + "Z_AI_API_KEY": { + "description": "Z.AI API key (alias for GLM_API_KEY)", + "prompt": "Z.AI API key", + "url": "https://z.ai/", + "password": True, + "category": "provider", + "advanced": True, + }, + "GLM_BASE_URL": { + "description": "Z.AI / GLM base URL override", + "prompt": "Z.AI / GLM base URL (leave empty for default)", + "url": None, + "password": False, + "category": "provider", + "advanced": True, + }, + "KIMI_API_KEY": { + "description": "Kimi / Moonshot API key", + "prompt": "Kimi API key", + "url": "https://platform.moonshot.cn/", + "password": True, + "category": "provider", + "advanced": True, + }, + "KIMI_BASE_URL": { + "description": "Kimi / Moonshot base URL override", + "prompt": "Kimi base URL (leave empty for default)", + "url": None, + "password": False, + "category": "provider", + "advanced": True, + }, + "KIMI_CN_API_KEY": { + "description": "Kimi / Moonshot China API key", + "prompt": "Kimi (China) API key", + "url": "https://platform.moonshot.cn/", + "password": True, + "category": "provider", + "advanced": True, + }, + "ARCEEAI_API_KEY": { + "description": "Arcee AI API key", + "prompt": "Arcee AI API key", + "url": "https://chat.arcee.ai/", + "password": True, + "category": "provider", + "advanced": True, + }, + "ARCEE_BASE_URL": { + "description": "Arcee AI base URL override", + "prompt": "Arcee base URL (leave empty for default)", + "url": None, + "password": False, + "category": "provider", + "advanced": True, + }, + "MINIMAX_API_KEY": { + "description": "MiniMax API key (international)", + "prompt": "MiniMax API key", + "url": "https://www.minimax.io/", + "password": True, + "category": "provider", + "advanced": True, + }, + "MINIMAX_BASE_URL": { + "description": "MiniMax base URL override", + "prompt": "MiniMax base URL (leave empty for default)", + "url": None, + "password": False, + "category": "provider", + "advanced": True, + }, + "MINIMAX_CN_API_KEY": { + "description": "MiniMax API key (China endpoint)", + "prompt": "MiniMax (China) API key", + "url": "https://www.minimaxi.com/", + "password": True, + "category": "provider", + "advanced": True, + }, + "MINIMAX_CN_BASE_URL": { + "description": "MiniMax (China) base URL override", + "prompt": "MiniMax (China) base URL (leave empty for default)", + "url": None, + "password": False, + "category": "provider", + "advanced": True, + }, + "DEEPSEEK_API_KEY": { + "description": "DeepSeek API key for direct DeepSeek access", + "prompt": "DeepSeek API Key", + "url": "https://platform.deepseek.com/api_keys", + "password": True, + "category": "provider", + }, + "DEEPSEEK_BASE_URL": { + "description": "Custom DeepSeek API base URL (advanced)", + "prompt": "DeepSeek Base URL", + "url": "", + "password": False, + "category": "provider", + }, + "DASHSCOPE_API_KEY": { + "description": "Alibaba Cloud DashScope API key (Qwen + multi-provider models)", + "prompt": "DashScope API Key", + "url": "https://modelstudio.console.alibabacloud.com/", + "password": True, + "category": "provider", + }, + "DASHSCOPE_BASE_URL": { + "description": "Custom DashScope base URL (default: coding-intl OpenAI-compat endpoint)", + "prompt": "DashScope Base URL", + "url": "", + "password": False, + "category": "provider", + "advanced": True, + }, + "HERMES_QWEN_BASE_URL": { + "description": "Qwen Portal base URL override (default: https://portal.qwen.ai/v1)", + "prompt": "Qwen Portal base URL (leave empty for default)", + "url": None, + "password": False, + "category": "provider", + "advanced": True, + }, + "OPENCODE_ZEN_API_KEY": { + "description": "OpenCode Zen API key (pay-as-you-go access to curated models)", + "prompt": "OpenCode Zen API key", + "url": "https://opencode.ai/auth", + "password": True, + "category": "provider", + "advanced": True, + }, + "OPENCODE_ZEN_BASE_URL": { + "description": "OpenCode Zen base URL override", + "prompt": "OpenCode Zen base URL (leave empty for default)", + "url": None, + "password": False, + "category": "provider", + "advanced": True, + }, + "OPENCODE_GO_API_KEY": { + "description": "OpenCode Go API key ($10/month subscription for open models)", + "prompt": "OpenCode Go API key", + "url": "https://opencode.ai/auth", + "password": True, + "category": "provider", + "advanced": True, + }, + "OPENCODE_GO_BASE_URL": { + "description": "OpenCode Go base URL override", + "prompt": "OpenCode Go base URL (leave empty for default)", + "url": None, + "password": False, + "category": "provider", + "advanced": True, + }, + "HF_TOKEN": { + "description": "Hugging Face token for Inference Providers (20+ open models via router.huggingface.co)", + "prompt": "Hugging Face Token", + "url": "https://huggingface.co/settings/tokens", + "password": True, + "category": "provider", + }, + "HF_BASE_URL": { + "description": "Hugging Face Inference Providers base URL override", + "prompt": "HF base URL (leave empty for default)", + "url": None, + "password": False, + "category": "provider", + "advanced": True, + }, + "XIAOMI_API_KEY": { + "description": "Xiaomi MiMo API key for MiMo models (mimo-v2-pro, mimo-v2-omni, mimo-v2-flash)", + "prompt": "Xiaomi MiMo API Key", + "url": "https://platform.xiaomimimo.com", + "password": True, + "category": "provider", + }, + "XIAOMI_BASE_URL": { + "description": "Xiaomi MiMo base URL override (default: https://api.xiaomimimo.com/v1)", + "prompt": "Xiaomi base URL (leave empty for default)", + "url": None, + "password": False, + "category": "provider", + "advanced": True, + }, + + # ── Tool API keys ── + "EXA_API_KEY": { + "description": "Exa API key for AI-native web search and contents", + "prompt": "Exa API key", + "url": "https://exa.ai/", + "tools": ["web_search", "web_extract"], + "password": True, + "category": "tool", + }, + "PARALLEL_API_KEY": { + "description": "Parallel API key for AI-native web search and extract", + "prompt": "Parallel API key", + "url": "https://parallel.ai/", + "tools": ["web_search", "web_extract"], + "password": True, + "category": "tool", + }, + "FIRECRAWL_API_KEY": { + "description": "Firecrawl API key for web search and scraping", + "prompt": "Firecrawl API key", + "url": "https://firecrawl.dev/", + "tools": ["web_search", "web_extract"], + "password": True, + "category": "tool", + }, + "FIRECRAWL_API_URL": { + "description": "Firecrawl API URL for self-hosted instances (optional)", + "prompt": "Firecrawl API URL (leave empty for cloud)", + "url": None, + "password": False, + "category": "tool", + "advanced": True, + }, + "FIRECRAWL_GATEWAY_URL": { + "description": "Exact Firecrawl tool-gateway origin override for Nous Subscribers only (optional)", + "prompt": "Firecrawl gateway URL (leave empty to derive from domain)", + "url": None, + "password": False, + "category": "tool", + "advanced": True, + }, + "TOOL_GATEWAY_DOMAIN": { + "description": "Shared tool-gateway domain suffix for Nous Subscribers only, used to derive vendor hosts, e.g. nousresearch.com -> firecrawl-gateway.nousresearch.com", + "prompt": "Tool-gateway domain suffix", + "url": None, + "password": False, + "category": "tool", + "advanced": True, + }, + "TOOL_GATEWAY_SCHEME": { + "description": "Shared tool-gateway URL scheme for Nous Subscribers only, used to derive vendor hosts (`https` by default, set `http` for local gateway testing)", + "prompt": "Tool-gateway URL scheme", + "url": None, + "password": False, + "category": "tool", + "advanced": True, + }, + "TOOL_GATEWAY_USER_TOKEN": { + "description": "Explicit Nous Subscriber access token for tool-gateway requests (optional; otherwise read from the Hermes auth store)", + "prompt": "Tool-gateway user token", + "url": None, + "password": True, + "category": "tool", + "advanced": True, + }, + "TAVILY_API_KEY": { + "description": "Tavily API key for AI-native web search, extract, and crawl", + "prompt": "Tavily API key", + "url": "https://app.tavily.com/home", + "tools": ["web_search", "web_extract", "web_crawl"], + "password": True, + "category": "tool", + }, + "BROWSERBASE_API_KEY": { + "description": "Browserbase API key for cloud browser (optional — local browser works without this)", + "prompt": "Browserbase API key", + "url": "https://browserbase.com/", + "tools": ["browser_navigate", "browser_click"], + "password": True, + "category": "tool", + }, + "BROWSERBASE_PROJECT_ID": { + "description": "Browserbase project ID (optional — only needed for cloud browser)", + "prompt": "Browserbase project ID", + "url": "https://browserbase.com/", + "tools": ["browser_navigate", "browser_click"], + "password": False, + "category": "tool", + }, + "BROWSER_USE_API_KEY": { + "description": "Browser Use API key for cloud browser (optional — local browser works without this)", + "prompt": "Browser Use API key", + "url": "https://browser-use.com/", + "tools": ["browser_navigate", "browser_click"], + "password": True, + "category": "tool", + }, + "FIRECRAWL_BROWSER_TTL": { + "description": "Firecrawl browser session TTL in seconds (optional, default 300)", + "prompt": "Browser session TTL (seconds)", + "tools": ["browser_navigate", "browser_click"], + "password": False, + "category": "tool", + }, + "CAMOFOX_URL": { + "description": "Camofox browser server URL for local anti-detection browsing (e.g. http://localhost:9377)", + "prompt": "Camofox server URL", + "url": "https://github.com/jo-inc/camofox-browser", + "tools": ["browser_navigate", "browser_click"], + "password": False, + "category": "tool", + }, + "FAL_KEY": { + "description": "FAL API key for image generation", + "prompt": "FAL API key", + "url": "https://fal.ai/", + "tools": ["image_generate"], + "password": True, + "category": "tool", + }, + "TINKER_API_KEY": { + "description": "Tinker API key for RL training", + "prompt": "Tinker API key", + "url": "https://tinker-console.thinkingmachines.ai/keys", + "tools": ["rl_start_training", "rl_check_status", "rl_stop_training"], + "password": True, + "category": "tool", + }, + "WANDB_API_KEY": { + "description": "Weights & Biases API key for experiment tracking", + "prompt": "WandB API key", + "url": "https://wandb.ai/authorize", + "tools": ["rl_get_results", "rl_check_status"], + "password": True, + "category": "tool", + }, + "VOICE_TOOLS_OPENAI_KEY": { + "description": "OpenAI API key for voice transcription (Whisper) and OpenAI TTS", + "prompt": "OpenAI API Key (for Whisper STT + TTS)", + "url": "https://platform.openai.com/api-keys", + "tools": ["voice_transcription", "openai_tts"], + "password": True, + "category": "tool", + }, + "ELEVENLABS_API_KEY": { + "description": "ElevenLabs API key for premium text-to-speech voices", + "prompt": "ElevenLabs API key", + "url": "https://elevenlabs.io/", + "password": True, + "category": "tool", + }, + "MISTRAL_API_KEY": { + "description": "Mistral API key for Voxtral TTS and transcription (STT)", + "prompt": "Mistral API key", + "url": "https://console.mistral.ai/", + "password": True, + "category": "tool", + }, + "GITHUB_TOKEN": { + "description": "GitHub token for Skills Hub (higher API rate limits, skill publish)", + "prompt": "GitHub Token", + "url": "https://github.com/settings/tokens", + "password": True, + "category": "tool", + }, + + # ── Honcho ── + "HONCHO_API_KEY": { + "description": "Honcho API key for AI-native persistent memory", + "prompt": "Honcho API key", + "url": "https://app.honcho.dev", + "tools": ["honcho_context"], + "password": True, + "category": "tool", + }, + "HONCHO_BASE_URL": { + "description": "Base URL for self-hosted Honcho instances (no API key needed)", + "prompt": "Honcho base URL (e.g. http://localhost:8000)", + "category": "tool", + }, + + # ── Messaging platforms ── + "TELEGRAM_BOT_TOKEN": { + "description": "Telegram bot token from @BotFather", + "prompt": "Telegram bot token", + "url": "https://t.me/BotFather", + "password": True, + "category": "messaging", + }, + "TELEGRAM_ALLOWED_USERS": { + "description": "Comma-separated Telegram user IDs allowed to use the bot (get ID from @userinfobot)", + "prompt": "Allowed Telegram user IDs (comma-separated)", + "url": "https://t.me/userinfobot", + "password": False, + "category": "messaging", + }, + "DISCORD_BOT_TOKEN": { + "description": "Discord bot token from Developer Portal", + "prompt": "Discord bot token", + "url": "https://discord.com/developers/applications", + "password": True, + "category": "messaging", + }, + "DISCORD_ALLOWED_USERS": { + "description": "Comma-separated Discord user IDs allowed to use the bot", + "prompt": "Allowed Discord user IDs (comma-separated)", + "url": None, + "password": False, + "category": "messaging", + }, + "DISCORD_REPLY_TO_MODE": { + "description": "Discord reply threading mode: 'off' (no reply references), 'first' (reply on first message only, default), 'all' (reply on every chunk)", + "prompt": "Discord reply mode (off/first/all)", + "url": None, + "password": False, + "category": "messaging", + }, + "SLACK_BOT_TOKEN": { + "description": "Slack bot token (xoxb-). Get from OAuth & Permissions after installing your app. " + "Required scopes: chat:write, app_mentions:read, channels:history, groups:history, " + "im:history, im:read, im:write, users:read, files:read, files:write", + "prompt": "Slack Bot Token (xoxb-...)", + "url": "https://api.slack.com/apps", + "password": True, + "category": "messaging", + }, + "SLACK_APP_TOKEN": { + "description": "Slack app-level token (xapp-) for Socket Mode. Get from Basic Information → " + "App-Level Tokens. Also ensure Event Subscriptions include: message.im, " + "message.channels, message.groups, app_mention", + "prompt": "Slack App Token (xapp-...)", + "url": "https://api.slack.com/apps", + "password": True, + "category": "messaging", + }, + "MATTERMOST_URL": { + "description": "Mattermost server URL (e.g. https://mm.example.com)", + "prompt": "Mattermost server URL", + "url": "https://mattermost.com/deploy/", + "password": False, + "category": "messaging", + }, + "MATTERMOST_TOKEN": { + "description": "Mattermost bot token or personal access token", + "prompt": "Mattermost bot token", + "url": None, + "password": True, + "category": "messaging", + }, + "MATTERMOST_ALLOWED_USERS": { + "description": "Comma-separated Mattermost user IDs allowed to use the bot", + "prompt": "Allowed Mattermost user IDs (comma-separated)", + "url": None, + "password": False, + "category": "messaging", + }, + "MATTERMOST_REQUIRE_MENTION": { + "description": "Require @mention in Mattermost channels (default: true). Set to false to respond to all messages.", + "prompt": "Require @mention in channels", + "url": None, + "password": False, + "category": "messaging", + }, + "MATTERMOST_FREE_RESPONSE_CHANNELS": { + "description": "Comma-separated Mattermost channel IDs where bot responds without @mention", + "prompt": "Free-response channel IDs (comma-separated)", + "url": None, + "password": False, + "category": "messaging", + }, + "MATRIX_HOMESERVER": { + "description": "Matrix homeserver URL (e.g. https://matrix.example.org)", + "prompt": "Matrix homeserver URL", + "url": "https://matrix.org/ecosystem/servers/", + "password": False, + "category": "messaging", + }, + "MATRIX_ACCESS_TOKEN": { + "description": "Matrix access token (preferred over password login)", + "prompt": "Matrix access token", + "url": None, + "password": True, + "category": "messaging", + }, + "MATRIX_USER_ID": { + "description": "Matrix user ID (e.g. @hermes:example.org)", + "prompt": "Matrix user ID (@user:server)", + "url": None, + "password": False, + "category": "messaging", + }, + "MATRIX_ALLOWED_USERS": { + "description": "Comma-separated Matrix user IDs allowed to use the bot (@user:server format)", + "prompt": "Allowed Matrix user IDs (comma-separated)", + "url": None, + "password": False, + "category": "messaging", + }, + "MATRIX_REQUIRE_MENTION": { + "description": "Require @mention in Matrix rooms (default: true). Set to false to respond to all messages.", + "prompt": "Require @mention in rooms (true/false)", + "url": None, + "password": False, + "category": "messaging", + "advanced": True, + }, + "MATRIX_FREE_RESPONSE_ROOMS": { + "description": "Comma-separated Matrix room IDs where bot responds without @mention", + "prompt": "Free-response room IDs (comma-separated)", + "url": None, + "password": False, + "category": "messaging", + "advanced": True, + }, + "MATRIX_AUTO_THREAD": { + "description": "Auto-create threads for messages in Matrix rooms (default: true)", + "prompt": "Auto-create threads in rooms (true/false)", + "url": None, + "password": False, + "category": "messaging", + "advanced": True, + }, + "MATRIX_DEVICE_ID": { + "description": "Stable Matrix device ID for E2EE persistence across restarts (e.g. HERMES_BOT)", + "prompt": "Matrix device ID (stable across restarts)", + "url": None, + "password": False, + "category": "messaging", + "advanced": True, + }, + "MATRIX_RECOVERY_KEY": { + "description": "Matrix recovery key for cross-signing verification after device key rotation (from Element: Settings → Security → Recovery Key)", + "prompt": "Matrix recovery key", + "url": None, + "password": True, + "category": "messaging", + "advanced": True, + }, + "BLUEBUBBLES_SERVER_URL": { + "description": "BlueBubbles server URL for iMessage integration (e.g. http://192.168.1.10:1234)", + "prompt": "BlueBubbles server URL", + "url": "https://bluebubbles.app/", + "password": False, + "category": "messaging", + }, + "BLUEBUBBLES_PASSWORD": { + "description": "BlueBubbles server password (from BlueBubbles Server → Settings → API)", + "prompt": "BlueBubbles server password", + "url": None, + "password": True, + "category": "messaging", + }, + "BLUEBUBBLES_ALLOWED_USERS": { + "description": "Comma-separated iMessage addresses (email or phone) allowed to use the bot", + "prompt": "Allowed iMessage addresses (comma-separated)", + "url": None, + "password": False, + "category": "messaging", + }, + "BLUEBUBBLES_ALLOW_ALL_USERS": { + "description": "Allow all BlueBubbles users without allowlist", + "prompt": "Allow All BlueBubbles Users", + "category": "messaging", + }, + "QQ_APP_ID": { + "description": "QQ Bot App ID from QQ Open Platform (q.qq.com)", + "prompt": "QQ App ID", + "url": "https://q.qq.com", + "category": "messaging", + }, + "QQ_CLIENT_SECRET": { + "description": "QQ Bot Client Secret from QQ Open Platform", + "prompt": "QQ Client Secret", + "password": True, + "category": "messaging", + }, + "QQ_ALLOWED_USERS": { + "description": "Comma-separated QQ user IDs allowed to use the bot", + "prompt": "QQ Allowed Users", + "category": "messaging", + }, + "QQ_GROUP_ALLOWED_USERS": { + "description": "Comma-separated QQ group IDs allowed to interact with the bot", + "prompt": "QQ Group Allowed Users", + "category": "messaging", + }, + "QQ_ALLOW_ALL_USERS": { + "description": "Allow all QQ users without an allowlist (true/false)", + "prompt": "Allow All QQ Users", + "category": "messaging", + }, + "QQ_HOME_CHANNEL": { + "description": "Default QQ channel/group for cron delivery and notifications", + "prompt": "QQ Home Channel", + "category": "messaging", + }, + "QQ_HOME_CHANNEL_NAME": { + "description": "Display name for the QQ home channel", + "prompt": "QQ Home Channel Name", + "category": "messaging", + }, + "QQ_SANDBOX": { + "description": "Enable QQ sandbox mode for development testing (true/false)", + "prompt": "QQ Sandbox Mode", + "category": "messaging", + }, + "GATEWAY_ALLOW_ALL_USERS": { + "description": "Allow all users to interact with messaging bots (true/false). Default: false.", + "prompt": "Allow all users (true/false)", + "url": None, + "password": False, + "category": "messaging", + "advanced": True, + }, + "API_SERVER_ENABLED": { + "description": "Enable the OpenAI-compatible API server (true/false). Allows frontends like Open WebUI, LobeChat, etc. to connect.", + "prompt": "Enable API server (true/false)", + "url": None, + "password": False, + "category": "messaging", + "advanced": True, + }, + "API_SERVER_KEY": { + "description": "Bearer token for API server authentication. Required for non-loopback binding; server refuses to start without it. On loopback (127.0.0.1), all requests are allowed if empty.", + "prompt": "API server auth key (required for network access)", + "url": None, + "password": True, + "category": "messaging", + "advanced": True, + }, + "API_SERVER_PORT": { + "description": "Port for the API server (default: 8642).", + "prompt": "API server port", + "url": None, + "password": False, + "category": "messaging", + "advanced": True, + }, + "API_SERVER_HOST": { + "description": "Host/bind address for the API server (default: 127.0.0.1). Use 0.0.0.0 for network access — server refuses to start without API_SERVER_KEY.", + "prompt": "API server host", + "url": None, + "password": False, + "category": "messaging", + "advanced": True, + }, + "API_SERVER_MODEL_NAME": { + "description": "Model name advertised on /v1/models. Defaults to the profile name (or 'hermes-agent' for the default profile). Useful for multi-user setups with OpenWebUI.", + "prompt": "API server model name", + "url": None, + "password": False, + "category": "messaging", + "advanced": True, + }, + "WEBHOOK_ENABLED": { + "description": "Enable the webhook platform adapter for receiving events from GitHub, GitLab, etc.", + "prompt": "Enable webhooks (true/false)", + "url": None, + "password": False, + "category": "messaging", + }, + "WEBHOOK_PORT": { + "description": "Port for the webhook HTTP server (default: 8644).", + "prompt": "Webhook port", + "url": None, + "password": False, + "category": "messaging", + }, + "WEBHOOK_SECRET": { + "description": "Global HMAC secret for webhook signature validation (overridable per route in config.yaml).", + "prompt": "Webhook secret", + "url": None, + "password": True, + "category": "messaging", + }, + + # ── Agent settings ── + "MESSAGING_CWD": { + "description": "Working directory for terminal commands via messaging", + "prompt": "Messaging working directory (default: home)", + "url": None, + "password": False, + "category": "setting", + }, + "SUDO_PASSWORD": { + "description": "Sudo password for terminal commands requiring root access; set to an explicit empty string to try empty without prompting", + "prompt": "Sudo password", + "url": None, + "password": True, + "category": "setting", + }, + "HERMES_MAX_ITERATIONS": { + "description": "Maximum tool-calling iterations per conversation (default: 90)", + "prompt": "Max iterations", + "url": None, + "password": False, + "category": "setting", + }, + # HERMES_TOOL_PROGRESS and HERMES_TOOL_PROGRESS_MODE are deprecated — + # now configured via display.tool_progress in config.yaml (off|new|all|verbose). + # Gateway falls back to these env vars for backward compatibility. + "HERMES_TOOL_PROGRESS": { + "description": "(deprecated) Use display.tool_progress in config.yaml instead", + "prompt": "Tool progress (deprecated — use config.yaml)", + "url": None, + "password": False, + "category": "setting", + }, + "HERMES_TOOL_PROGRESS_MODE": { + "description": "(deprecated) Use display.tool_progress in config.yaml instead", + "prompt": "Progress mode (deprecated — use config.yaml)", + "url": None, + "password": False, + "category": "setting", + }, + "HERMES_PREFILL_MESSAGES_FILE": { + "description": "Path to JSON file with ephemeral prefill messages for few-shot priming", + "prompt": "Prefill messages file path", + "url": None, + "password": False, + "category": "setting", + }, + "HERMES_EPHEMERAL_SYSTEM_PROMPT": { + "description": "Ephemeral system prompt injected at API-call time (never persisted to sessions)", + "prompt": "Ephemeral system prompt", + "url": None, + "password": False, + "category": "setting", + }, +} + +if not _managed_nous_tools_enabled(): + for _hidden_var in ( + "FIRECRAWL_GATEWAY_URL", + "TOOL_GATEWAY_DOMAIN", + "TOOL_GATEWAY_SCHEME", + "TOOL_GATEWAY_USER_TOKEN", + ): + OPTIONAL_ENV_VARS.pop(_hidden_var, None) + + +def get_missing_env_vars(required_only: bool = False) -> List[Dict[str, Any]]: + """ + Check which environment variables are missing. + + Returns list of dicts with var info for missing variables. + """ + missing = [] + + # Check required vars + for var_name, info in REQUIRED_ENV_VARS.items(): + if not get_env_value(var_name): + missing.append({"name": var_name, **info, "is_required": True}) + + # Check optional vars (if not required_only) + if not required_only: + for var_name, info in OPTIONAL_ENV_VARS.items(): + if not get_env_value(var_name): + missing.append({"name": var_name, **info, "is_required": False}) + + return missing + + +def _set_nested(config: dict, dotted_key: str, value): + """Set a value at an arbitrarily nested dotted key path. + + Creates intermediate dicts as needed, e.g. ``_set_nested(c, "a.b.c", 1)`` + ensures ``c["a"]["b"]["c"] == 1``. + """ + parts = dotted_key.split(".") + current = config + for part in parts[:-1]: + if part not in current or not isinstance(current.get(part), dict): + current[part] = {} + current = current[part] + current[parts[-1]] = value + + +def get_missing_config_fields() -> List[Dict[str, Any]]: + """ + Check which config fields are missing or outdated (recursive). + + Walks the DEFAULT_CONFIG tree at arbitrary depth and reports any keys + present in defaults but absent from the user's loaded config. + """ + config = load_config() + missing = [] + + def _check(defaults: dict, current: dict, prefix: str = ""): + for key, default_value in defaults.items(): + if key.startswith('_'): + continue + full_key = key if not prefix else f"{prefix}.{key}" + if key not in current: + missing.append({ + "key": full_key, + "default": default_value, + "description": f"New config option: {full_key}", + }) + elif isinstance(default_value, dict) and isinstance(current.get(key), dict): + _check(default_value, current[key], full_key) + + _check(DEFAULT_CONFIG, config) + return missing + + +def get_missing_skill_config_vars() -> List[Dict[str, Any]]: + """Return skill-declared config vars that are missing or empty in config.yaml. + + Scans all enabled skills for ``metadata.hermes.config`` entries, then checks + which ones are absent or empty under ``skills.config.`` in the user's + config.yaml. Returns a list of dicts suitable for prompting. + """ + try: + from agent.skill_utils import discover_all_skill_config_vars, SKILL_CONFIG_PREFIX + except Exception: + return [] + + all_vars = discover_all_skill_config_vars() + if not all_vars: + return [] + + config = load_config() + missing: List[Dict[str, Any]] = [] + for var in all_vars: + # Skill config is stored under skills.config. + storage_key = f"{SKILL_CONFIG_PREFIX}.{var['key']}" + parts = storage_key.split(".") + current = config + value = None + for part in parts: + if isinstance(current, dict) and part in current: + current = current[part] + value = current + else: + value = None + break + # Missing = key doesn't exist or is empty string + if value is None or (isinstance(value, str) and not value.strip()): + missing.append(var) + return missing + + +def _normalize_custom_provider_entry( + entry: Any, + *, + provider_key: str = "", +) -> Optional[Dict[str, Any]]: + """Return a runtime-compatible custom provider entry or ``None``.""" + if not isinstance(entry, dict): + return None + + base_url = "" + for url_key in ("api", "url", "base_url"): + raw_url = entry.get(url_key) + if isinstance(raw_url, str) and raw_url.strip(): + base_url = raw_url.strip() + break + if not base_url: + return None + + name = "" + raw_name = entry.get("name") + if isinstance(raw_name, str) and raw_name.strip(): + name = raw_name.strip() + elif provider_key.strip(): + name = provider_key.strip() + if not name: + return None + + normalized: Dict[str, Any] = { + "name": name, + "base_url": base_url, + } + + provider_key = provider_key.strip() + if provider_key: + normalized["provider_key"] = provider_key + + api_key = entry.get("api_key") + if isinstance(api_key, str) and api_key.strip(): + normalized["api_key"] = api_key.strip() + + key_env = entry.get("key_env") + if isinstance(key_env, str) and key_env.strip(): + normalized["key_env"] = key_env.strip() + + api_mode = entry.get("api_mode") or entry.get("transport") + if isinstance(api_mode, str) and api_mode.strip(): + normalized["api_mode"] = api_mode.strip() + + model_name = entry.get("model") or entry.get("default_model") + if isinstance(model_name, str) and model_name.strip(): + normalized["model"] = model_name.strip() + + models = entry.get("models") + if isinstance(models, dict) and models: + normalized["models"] = models + + context_length = entry.get("context_length") + if isinstance(context_length, int) and context_length > 0: + normalized["context_length"] = context_length + + rate_limit_delay = entry.get("rate_limit_delay") + if isinstance(rate_limit_delay, (int, float)) and rate_limit_delay >= 0: + normalized["rate_limit_delay"] = rate_limit_delay + + return normalized + + +def providers_dict_to_custom_providers(providers_dict: Any) -> List[Dict[str, Any]]: + """Normalize ``providers`` config entries into the legacy custom-provider shape.""" + if not isinstance(providers_dict, dict): + return [] + + custom_providers: List[Dict[str, Any]] = [] + for key, entry in providers_dict.items(): + normalized = _normalize_custom_provider_entry(entry, provider_key=str(key)) + if normalized is not None: + custom_providers.append(normalized) + + return custom_providers + + +def get_compatible_custom_providers( + config: Optional[Dict[str, Any]] = None, +) -> List[Dict[str, Any]]: + """Return a deduplicated custom-provider view across legacy and v12+ config. + + ``custom_providers`` remains the on-disk legacy format, while ``providers`` + is the newer keyed schema. Runtime and picker flows still need a single + list-shaped view, but we should not materialise that compatibility layer + back into config.yaml because it duplicates entries in UIs. + """ + if config is None: + config = load_config() + + compatible: List[Dict[str, Any]] = [] + seen_provider_keys: set = set() + seen_name_url_pairs: set = set() + + def _append_if_new(entry: Optional[Dict[str, Any]]) -> None: + if entry is None: + return + provider_key = str(entry.get("provider_key", "") or "").strip().lower() + name = str(entry.get("name", "") or "").strip().lower() + base_url = str(entry.get("base_url", "") or "").strip().rstrip("/").lower() + model = str(entry.get("model", "") or "").strip().lower() + pair = (name, base_url, model) + + if provider_key and provider_key in seen_provider_keys: + return + if name and base_url and pair in seen_name_url_pairs: + return + + compatible.append(entry) + if provider_key: + seen_provider_keys.add(provider_key) + if name and base_url: + seen_name_url_pairs.add(pair) + + custom_providers = config.get("custom_providers") + if custom_providers is not None: + if not isinstance(custom_providers, list): + return [] + for entry in custom_providers: + _append_if_new(_normalize_custom_provider_entry(entry)) + + for entry in providers_dict_to_custom_providers(config.get("providers")): + _append_if_new(entry) + + return compatible + + +def check_config_version() -> Tuple[int, int]: + """ + Check config version. + + Returns (current_version, latest_version). + """ + config = load_config() + current = config.get("_config_version", 0) + latest = DEFAULT_CONFIG.get("_config_version", 1) + return current, latest + + +# ============================================================================= +# Config structure validation +# ============================================================================= + +# Fields that are valid at root level of config.yaml +_KNOWN_ROOT_KEYS = { + "_config_version", "model", "providers", "fallback_model", + "fallback_providers", "credential_pool_strategies", "toolsets", + "agent", "terminal", "display", "compression", "delegation", + "auxiliary", "custom_providers", "context", "memory", "gateway", +} + +# Valid fields inside a custom_providers list entry +_VALID_CUSTOM_PROVIDER_FIELDS = { + "name", "base_url", "api_key", "api_mode", "model", "models", + "context_length", "rate_limit_delay", +} + +# Fields that look like they should be inside custom_providers, not at root +_CUSTOM_PROVIDER_LIKE_FIELDS = {"base_url", "api_key", "rate_limit_delay", "api_mode"} + + +@dataclass +class ConfigIssue: + """A detected config structure problem.""" + + severity: str # "error", "warning" + message: str + hint: str + + +def validate_config_structure(config: Optional[Dict[str, Any]] = None) -> List["ConfigIssue"]: + """Validate config.yaml structure and return a list of detected issues. + + Catches common YAML formatting mistakes that produce confusing runtime + errors (like "Unknown provider") instead of clear diagnostics. + + Can be called with a pre-loaded config dict, or will load from disk. + """ + if config is None: + try: + config = load_config() + except Exception: + return [ConfigIssue("error", "Could not load config.yaml", "Run 'hermes setup' to create a valid config")] + + issues: List[ConfigIssue] = [] + + # ── custom_providers must be a list, not a dict ────────────────────── + cp = config.get("custom_providers") + if cp is not None: + if isinstance(cp, dict): + issues.append(ConfigIssue( + "error", + "custom_providers is a dict — it must be a YAML list (items prefixed with '-')", + "Change to:\n" + " custom_providers:\n" + " - name: my-provider\n" + " base_url: https://...\n" + " api_key: ...", + )) + # Check if dict keys look like they should be list-entry fields + cp_keys = set(cp.keys()) if isinstance(cp, dict) else set() + suspicious = cp_keys & _CUSTOM_PROVIDER_LIKE_FIELDS + if suspicious: + issues.append(ConfigIssue( + "warning", + f"Root-level keys {sorted(suspicious)} look like custom_providers entry fields", + "These should be indented under a '- name: ...' list entry, not at root level", + )) + elif isinstance(cp, list): + # Validate each entry in the list + for i, entry in enumerate(cp): + if not isinstance(entry, dict): + issues.append(ConfigIssue( + "warning", + f"custom_providers[{i}] is not a dict (got {type(entry).__name__})", + "Each entry should have at minimum: name, base_url", + )) + continue + if not entry.get("name"): + issues.append(ConfigIssue( + "warning", + f"custom_providers[{i}] is missing 'name' field", + "Add a name, e.g.: name: my-provider", + )) + if not entry.get("base_url"): + issues.append(ConfigIssue( + "warning", + f"custom_providers[{i}] is missing 'base_url' field", + "Add the API endpoint URL, e.g.: base_url: https://api.example.com/v1", + )) + + # ── fallback_model must be a top-level dict with provider + model ──── + fb = config.get("fallback_model") + if fb is not None: + if not isinstance(fb, dict): + issues.append(ConfigIssue( + "error", + f"fallback_model should be a dict with 'provider' and 'model', got {type(fb).__name__}", + "Change to:\n" + " fallback_model:\n" + " provider: openrouter\n" + " model: anthropic/claude-sonnet-4", + )) + elif fb: + if not fb.get("provider"): + issues.append(ConfigIssue( + "warning", + "fallback_model is missing 'provider' field — fallback will be disabled", + "Add: provider: openrouter (or another provider)", + )) + if not fb.get("model"): + issues.append(ConfigIssue( + "warning", + "fallback_model is missing 'model' field — fallback will be disabled", + "Add: model: anthropic/claude-sonnet-4 (or another model)", + )) + + # ── Check for fallback_model accidentally nested inside custom_providers ── + if isinstance(cp, dict) and "fallback_model" not in config and "fallback_model" in (cp or {}): + issues.append(ConfigIssue( + "error", + "fallback_model appears inside custom_providers instead of at root level", + "Move fallback_model to the top level of config.yaml (no indentation)", + )) + + # ── model section: should exist when custom_providers is configured ── + model_cfg = config.get("model") + if cp and not model_cfg: + issues.append(ConfigIssue( + "warning", + "custom_providers defined but no 'model' section — Hermes won't know which provider to use", + "Add a model section:\n" + " model:\n" + " provider: custom\n" + " default: your-model-name\n" + " base_url: https://...", + )) + + # ── Root-level keys that look misplaced ────────────────────────────── + for key in config: + if key.startswith("_"): + continue + if key not in _KNOWN_ROOT_KEYS and key in _CUSTOM_PROVIDER_LIKE_FIELDS: + issues.append(ConfigIssue( + "warning", + f"Root-level key '{key}' looks misplaced — should it be under 'model:' or inside a 'custom_providers' entry?", + f"Move '{key}' under the appropriate section", + )) + + return issues + + +def print_config_warnings(config: Optional[Dict[str, Any]] = None) -> None: + """Print config structure warnings to stderr at startup. + + Called early in CLI and gateway init so users see problems before + they hit cryptic "Unknown provider" errors. Prints nothing if + config is healthy. + """ + try: + issues = validate_config_structure(config) + except Exception: + return + if not issues: + return + + import sys + lines = ["\033[33m⚠ Config issues detected in config.yaml:\033[0m"] + for ci in issues: + marker = "\033[31m✗\033[0m" if ci.severity == "error" else "\033[33m⚠\033[0m" + lines.append(f" {marker} {ci.message}") + lines.append(" \033[2mRun 'hermes doctor' for fix suggestions.\033[0m") + sys.stderr.write("\n".join(lines) + "\n\n") + + +def migrate_config(interactive: bool = True, quiet: bool = False) -> Dict[str, Any]: + """ + Migrate config to latest version, prompting for new required fields. + + Args: + interactive: If True, prompt user for missing values + quiet: If True, suppress output + + Returns: + Dict with migration results: {"env_added": [...], "config_added": [...], "warnings": [...]} + """ + results = {"env_added": [], "config_added": [], "warnings": []} + + # ── Always: sanitize .env (split concatenated keys) ── + try: + fixes = sanitize_env_file() + if fixes and not quiet: + print(f" ✓ Repaired .env file ({fixes} corrupted entries fixed)") + except Exception: + pass # best-effort; don't block migration on sanitize failure + + # Check config version + current_ver, latest_ver = check_config_version() + + # ── Version 3 → 4: migrate tool progress from .env to config.yaml ── + if current_ver < 4: + config = load_config() + display = config.get("display", {}) + if not isinstance(display, dict): + display = {} + if "tool_progress" not in display: + old_enabled = get_env_value("HERMES_TOOL_PROGRESS") + old_mode = get_env_value("HERMES_TOOL_PROGRESS_MODE") + if old_enabled and old_enabled.lower() in ("false", "0", "no"): + display["tool_progress"] = "off" + results["config_added"].append("display.tool_progress=off (from HERMES_TOOL_PROGRESS=false)") + elif old_mode and old_mode.lower() in ("new", "all"): + display["tool_progress"] = old_mode.lower() + results["config_added"].append(f"display.tool_progress={old_mode.lower()} (from HERMES_TOOL_PROGRESS_MODE)") + else: + display["tool_progress"] = "all" + results["config_added"].append("display.tool_progress=all (default)") + config["display"] = display + save_config(config) + if not quiet: + print(f" ✓ Migrated tool progress to config.yaml: {display['tool_progress']}") + + # ── Version 4 → 5: add timezone field ── + if current_ver < 5: + config = load_config() + if "timezone" not in config: + old_tz = os.getenv("HERMES_TIMEZONE", "") + if old_tz and old_tz.strip(): + config["timezone"] = old_tz.strip() + results["config_added"].append(f"timezone={old_tz.strip()} (from HERMES_TIMEZONE)") + else: + config["timezone"] = "" + results["config_added"].append("timezone= (empty, uses server-local)") + save_config(config) + if not quiet: + tz_display = config["timezone"] or "(server-local)" + print(f" ✓ Added timezone to config.yaml: {tz_display}") + + # ── Version 8 → 9: clear ANTHROPIC_TOKEN from .env ── + # The new Anthropic auth flow no longer uses this env var. + if current_ver < 9: + try: + old_token = get_env_value("ANTHROPIC_TOKEN") + if old_token: + save_env_value("ANTHROPIC_TOKEN", "") + if not quiet: + print(" ✓ Cleared ANTHROPIC_TOKEN from .env (no longer used)") + except Exception: + pass + + # ── Version 11 → 12: migrate custom_providers list → providers dict ── + if current_ver < 12: + config = load_config() + custom_list = config.get("custom_providers") + if isinstance(custom_list, list) and custom_list: + providers_dict = config.get("providers", {}) + if not isinstance(providers_dict, dict): + providers_dict = {} + migrated_count = 0 + for entry in custom_list: + if not isinstance(entry, dict): + continue + old_name = entry.get("name", "") + old_url = entry.get("base_url", "") or entry.get("url", "") or "" + old_key = entry.get("api_key", "") + if not old_url: + continue # skip entries with no URL + + # Generate a kebab-case key from the display name + key = old_name.strip().lower().replace(" ", "-").replace("(", "").replace(")", "") + # Remove consecutive hyphens and trailing hyphens + while "--" in key: + key = key.replace("--", "-") + key = key.strip("-") + if not key: + # Fallback: derive from URL hostname + try: + from urllib.parse import urlparse + parsed = urlparse(old_url) + key = (parsed.hostname or "endpoint").replace(".", "-") + except Exception: + key = f"endpoint-{migrated_count}" + + # Don't overwrite existing entries + if key in providers_dict: + key = f"{key}-{migrated_count}" + + new_entry = {"api": old_url} + if old_name: + new_entry["name"] = old_name + if old_key and old_key not in ("no-key", "no-key-required", ""): + new_entry["api_key"] = old_key + + # Carry over model and api_mode if present + if entry.get("model"): + new_entry["default_model"] = entry["model"] + if entry.get("api_mode"): + new_entry["transport"] = entry["api_mode"] + + providers_dict[key] = new_entry + migrated_count += 1 + + if migrated_count > 0: + config["providers"] = providers_dict + # Remove the old list — runtime reads via get_compatible_custom_providers() + config.pop("custom_providers", None) + save_config(config) + if not quiet: + print(f" ✓ Migrated {migrated_count} custom provider(s) to providers: section") + for key in list(providers_dict.keys())[-migrated_count:]: + ep = providers_dict[key] + print(f" → {key}: {ep.get('api', '')}") + + # ── Version 12 → 13: clear dead LLM_MODEL / OPENAI_MODEL from .env ── + # These env vars were written by the old setup wizard but nothing reads + # them anymore (config.yaml is the sole source of truth since March 2026). + # Stale entries cause user confusion — see issue report. + if current_ver < 13: + for dead_var in ("LLM_MODEL", "OPENAI_MODEL"): + try: + old_val = get_env_value(dead_var) + if old_val: + save_env_value(dead_var, "") + if not quiet: + print(f" ✓ Cleared {dead_var} from .env (no longer used — config.yaml is source of truth)") + except Exception: + pass + + # ── Version 13 → 14: migrate legacy flat stt.model to provider section ── + # Old configs (and cli-config.yaml.example) had a flat `stt.model` key + # that was provider-agnostic. When the provider was "local" this caused + # OpenAI model names (e.g. "whisper-1") to be fed to faster-whisper, + # crashing with "Invalid model size". Move the value into the correct + # provider-specific section and remove the flat key. + if current_ver < 14: + # Read raw config (no defaults merged) to check what the user actually + # wrote, then apply changes to the merged config for saving. + raw = read_raw_config() + raw_stt = raw.get("stt", {}) + if isinstance(raw_stt, dict) and "model" in raw_stt: + legacy_model = raw_stt["model"] + provider = raw_stt.get("provider", "local") + config = load_config() + stt = config.get("stt", {}) + # Remove the legacy flat key + stt.pop("model", None) + # Place it in the appropriate provider section only if the + # user didn't already set a model there + if provider in ("local", "local_command"): + # Don't migrate an OpenAI model name into the local section + _local_models = { + "tiny.en", "tiny", "base.en", "base", "small.en", "small", + "medium.en", "medium", "large-v1", "large-v2", "large-v3", + "large", "distil-large-v2", "distil-medium.en", + "distil-small.en", "distil-large-v3", "distil-large-v3.5", + "large-v3-turbo", "turbo", + } + if legacy_model in _local_models: + # Check raw config — only set if user didn't already + # have a nested local.model + raw_local = raw_stt.get("local", {}) + if not isinstance(raw_local, dict) or "model" not in raw_local: + local_cfg = stt.setdefault("local", {}) + local_cfg["model"] = legacy_model + # else: drop it — it was an OpenAI model name, local section + # already defaults to "base" via DEFAULT_CONFIG + else: + # Cloud provider — put it in that provider's section only + # if user didn't already set a nested model + raw_provider = raw_stt.get(provider, {}) + if not isinstance(raw_provider, dict) or "model" not in raw_provider: + provider_cfg = stt.setdefault(provider, {}) + provider_cfg["model"] = legacy_model + config["stt"] = stt + save_config(config) + if not quiet: + print(f" ✓ Migrated legacy stt.model to provider-specific config") + + # ── Version 14 → 15: add explicit gateway interim-message gate ── + if current_ver < 15: + config = read_raw_config() + display = config.get("display", {}) + if not isinstance(display, dict): + display = {} + if "interim_assistant_messages" not in display: + display["interim_assistant_messages"] = True + config["display"] = display + results["config_added"].append("display.interim_assistant_messages=true (default)") + save_config(config) + if not quiet: + print(" ✓ Added display.interim_assistant_messages=true") + + # ── Version 15 → 16: migrate tool_progress_overrides into display.platforms ── + if current_ver < 16: + config = read_raw_config() + display = config.get("display", {}) + if not isinstance(display, dict): + display = {} + old_overrides = display.get("tool_progress_overrides") + if isinstance(old_overrides, dict) and old_overrides: + platforms = display.get("platforms", {}) + if not isinstance(platforms, dict): + platforms = {} + for plat, mode in old_overrides.items(): + if plat not in platforms: + platforms[plat] = {} + if "tool_progress" not in platforms[plat]: + platforms[plat]["tool_progress"] = mode + display["platforms"] = platforms + config["display"] = display + save_config(config) + if not quiet: + migrated = ", ".join(f"{p}={m}" for p, m in old_overrides.items()) + print(f" ✓ Migrated tool_progress_overrides → display.platforms: {migrated}") + results["config_added"].append("display.platforms (migrated from tool_progress_overrides)") + + # ── Version 16 → 17: remove legacy compression.summary_* keys ── + if current_ver < 17: + config = read_raw_config() + comp = config.get("compression", {}) + if isinstance(comp, dict): + s_model = comp.pop("summary_model", None) + s_provider = comp.pop("summary_provider", None) + s_base_url = comp.pop("summary_base_url", None) + migrated_keys = [] + # Migrate non-empty, non-default values to auxiliary.compression + if s_model and str(s_model).strip(): + aux = config.setdefault("auxiliary", {}) + aux_comp = aux.setdefault("compression", {}) + if not aux_comp.get("model"): + aux_comp["model"] = str(s_model).strip() + migrated_keys.append(f"model={s_model}") + if s_provider and str(s_provider).strip() not in ("", "auto"): + aux = config.setdefault("auxiliary", {}) + aux_comp = aux.setdefault("compression", {}) + if not aux_comp.get("provider") or aux_comp.get("provider") == "auto": + aux_comp["provider"] = str(s_provider).strip() + migrated_keys.append(f"provider={s_provider}") + if s_base_url and str(s_base_url).strip(): + aux = config.setdefault("auxiliary", {}) + aux_comp = aux.setdefault("compression", {}) + if not aux_comp.get("base_url"): + aux_comp["base_url"] = str(s_base_url).strip() + migrated_keys.append(f"base_url={s_base_url}") + if migrated_keys or s_model is not None or s_provider is not None or s_base_url is not None: + config["compression"] = comp + save_config(config) + if not quiet: + if migrated_keys: + print(f" ✓ Migrated compression.summary_* → auxiliary.compression: {', '.join(migrated_keys)}") + else: + print(" ✓ Removed unused compression.summary_* keys") + + if current_ver < latest_ver and not quiet: + print(f"Config version: {current_ver} → {latest_ver}") + + # Check for missing required env vars + missing_env = get_missing_env_vars(required_only=True) + + if missing_env and not quiet: + print("\n⚠️ Missing required environment variables:") + for var in missing_env: + print(f" • {var['name']}: {var['description']}") + + if interactive and missing_env: + print("\nLet's configure them now:\n") + for var in missing_env: + if var.get("url"): + print(f" Get your key at: {var['url']}") + + if var.get("password"): + import getpass + value = getpass.getpass(f" {var['prompt']}: ") + else: + value = input(f" {var['prompt']}: ").strip() + + if value: + save_env_value(var["name"], value) + results["env_added"].append(var["name"]) + print(f" ✓ Saved {var['name']}") + else: + results["warnings"].append(f"Skipped {var['name']} - some features may not work") + print() + + # Check for missing optional env vars and offer to configure interactively + # Skip "advanced" vars (like OPENAI_BASE_URL) -- those are for power users + missing_optional = get_missing_env_vars(required_only=False) + required_names = {v["name"] for v in missing_env} if missing_env else set() + missing_optional = [ + v for v in missing_optional + if v["name"] not in required_names and not v.get("advanced") + ] + + # Only offer to configure env vars that are NEW since the user's previous version + new_var_names = set() + for ver in range(current_ver + 1, latest_ver + 1): + new_var_names.update(ENV_VARS_BY_VERSION.get(ver, [])) + + if new_var_names and interactive and not quiet: + new_and_unset = [ + (name, OPTIONAL_ENV_VARS[name]) + for name in sorted(new_var_names) + if not get_env_value(name) and name in OPTIONAL_ENV_VARS + ] + if new_and_unset: + print(f"\n {len(new_and_unset)} new optional key(s) in this update:") + for name, info in new_and_unset: + print(f" • {name} — {info.get('description', '')}") + print() + try: + answer = input(" Configure new keys? [y/N]: ").strip().lower() + except (EOFError, KeyboardInterrupt): + answer = "n" + + if answer in ("y", "yes"): + print() + for name, info in new_and_unset: + if info.get("url"): + print(f" {info.get('description', name)}") + print(f" Get your key at: {info['url']}") + else: + print(f" {info.get('description', name)}") + if info.get("password"): + import getpass + value = getpass.getpass(f" {info.get('prompt', name)} (Enter to skip): ") + else: + value = input(f" {info.get('prompt', name)} (Enter to skip): ").strip() + if value: + save_env_value(name, value) + results["env_added"].append(name) + print(f" ✓ Saved {name}") + print() + else: + print(" Set later with: hermes config set ") + + # Check for missing config fields + missing_config = get_missing_config_fields() + + if missing_config: + config = load_config() + + for field in missing_config: + key = field["key"] + default = field["default"] + + _set_nested(config, key, default) + results["config_added"].append(key) + if not quiet: + print(f" ✓ Added {key} = {default}") + + # Update version and save + config["_config_version"] = latest_ver + save_config(config) + elif current_ver < latest_ver: + # Just update version + config = load_config() + config["_config_version"] = latest_ver + save_config(config) + + # ── Skill-declared config vars ────────────────────────────────────── + # Skills can declare config.yaml settings they need via + # metadata.hermes.config in their SKILL.md frontmatter. + # Prompt for any that are missing/empty. + missing_skill_config = get_missing_skill_config_vars() + if missing_skill_config and interactive and not quiet: + print(f"\n {len(missing_skill_config)} skill setting(s) not configured:") + for var in missing_skill_config: + skill_name = var.get("skill", "unknown") + print(f" • {var['key']} — {var['description']} (from skill: {skill_name})") + print() + try: + answer = input(" Configure skill settings? [y/N]: ").strip().lower() + except (EOFError, KeyboardInterrupt): + answer = "n" + + if answer in ("y", "yes"): + print() + config = load_config() + try: + from agent.skill_utils import SKILL_CONFIG_PREFIX + except Exception: + SKILL_CONFIG_PREFIX = "skills.config" + for var in missing_skill_config: + default = var.get("default", "") + default_hint = f" (default: {default})" if default else "" + value = input(f" {var['prompt']}{default_hint}: ").strip() + if not value and default: + value = str(default) + if value: + storage_key = f"{SKILL_CONFIG_PREFIX}.{var['key']}" + _set_nested(config, storage_key, value) + results["config_added"].append(var["key"]) + print(f" ✓ Saved {var['key']} = {value}") + else: + results["warnings"].append( + f"Skipped {var['key']} — skill '{var.get('skill', '?')}' may ask for it later" + ) + print() + save_config(config) + else: + print(" Set later with: hermes config set ") + + return results + + +def _deep_merge(base: dict, override: dict) -> dict: + """Recursively merge *override* into *base*, preserving nested defaults. + + Keys in *override* take precedence. If both values are dicts the merge + recurses, so a user who overrides only ``tts.elevenlabs.voice_id`` will + keep the default ``tts.elevenlabs.model_id`` intact. + """ + result = base.copy() + for key, value in override.items(): + if ( + key in result + and isinstance(result[key], dict) + and isinstance(value, dict) + ): + result[key] = _deep_merge(result[key], value) + else: + result[key] = value + return result + + +def _expand_env_vars(obj): + """Recursively expand ``${VAR}`` references in config values. + + Only string values are processed; dict keys, numbers, booleans, and + None are left untouched. Unresolved references (variable not in + ``os.environ``) are kept verbatim so callers can detect them. + """ + if isinstance(obj, str): + return re.sub( + r"\${([^}]+)}", + lambda m: os.environ.get(m.group(1), m.group(0)), + obj, + ) + if isinstance(obj, dict): + return {k: _expand_env_vars(v) for k, v in obj.items()} + if isinstance(obj, list): + return [_expand_env_vars(item) for item in obj] + return obj + + +def _normalize_root_model_keys(config: Dict[str, Any]) -> Dict[str, Any]: + """Move stale root-level provider/base_url into model section. + + Some users (or older code) placed ``provider:`` and ``base_url:`` at the + config root instead of inside ``model:``. These root-level keys are only + used as a fallback when the corresponding ``model.*`` key is empty — they + never override an existing ``model.provider`` or ``model.base_url``. + After migration the root-level keys are removed so they can't cause + confusion on subsequent loads. + """ + # Only act if there are root-level keys to migrate + has_root = any(config.get(k) for k in ("provider", "base_url")) + if not has_root: + return config + + config = dict(config) + model = config.get("model") + if not isinstance(model, dict): + model = {"default": model} if model else {} + config["model"] = model + + for key in ("provider", "base_url"): + root_val = config.get(key) + if root_val and not model.get(key): + model[key] = root_val + config.pop(key, None) + + return config + + +def _normalize_max_turns_config(config: Dict[str, Any]) -> Dict[str, Any]: + """Normalize legacy root-level max_turns into agent.max_turns.""" + config = dict(config) + agent_config = dict(config.get("agent") or {}) + + if "max_turns" in config and "max_turns" not in agent_config: + agent_config["max_turns"] = config["max_turns"] + + if "max_turns" not in agent_config: + agent_config["max_turns"] = DEFAULT_CONFIG["agent"]["max_turns"] + + config["agent"] = agent_config + config.pop("max_turns", None) + return config + + + +def read_raw_config() -> Dict[str, Any]: + """Read ~/.hermes/config.yaml as-is, without merging defaults or migrating. + + Returns the raw YAML dict, or ``{}`` if the file doesn't exist or can't + be parsed. Use this for lightweight config reads where you just need a + single value and don't want the overhead of ``load_config()``'s deep-merge + + migration pipeline. + """ + try: + config_path = get_config_path() + if config_path.exists(): + with open(config_path, encoding="utf-8") as f: + return yaml.safe_load(f) or {} + except Exception: + pass + return {} + + +def load_config() -> Dict[str, Any]: + """Load configuration from ~/.hermes/config.yaml.""" + import copy + ensure_hermes_home() + config_path = get_config_path() + + config = copy.deepcopy(DEFAULT_CONFIG) + + if config_path.exists(): + try: + with open(config_path, encoding="utf-8") as f: + user_config = yaml.safe_load(f) or {} + + if "max_turns" in user_config: + agent_user_config = dict(user_config.get("agent") or {}) + if agent_user_config.get("max_turns") is None: + agent_user_config["max_turns"] = user_config["max_turns"] + user_config["agent"] = agent_user_config + user_config.pop("max_turns", None) + + config = _deep_merge(config, user_config) + except Exception as e: + print(f"Warning: Failed to load config: {e}") + + return _expand_env_vars(_normalize_root_model_keys(_normalize_max_turns_config(config))) + + +_SECURITY_COMMENT = """ +# ── Security ────────────────────────────────────────────────────────── +# API keys, tokens, and passwords are redacted from tool output by default. +# Set to false to see full values (useful for debugging auth issues). +# tirith pre-exec scanning is enabled by default when the tirith binary +# is available. Configure via security.tirith_* keys or env vars +# (TIRITH_ENABLED, TIRITH_BIN, TIRITH_TIMEOUT, TIRITH_FAIL_OPEN). +# +# security: +# redact_secrets: false +# tirith_enabled: true +# tirith_path: "tirith" +# tirith_timeout: 5 +# tirith_fail_open: true +""" + +_FALLBACK_COMMENT = """ +# ── Fallback Model ──────────────────────────────────────────────────── +# Automatic provider failover when primary is unavailable. +# Uncomment and configure to enable. Triggers on rate limits (429), +# overload (529), service errors (503), or connection failures. +# +# Supported providers: +# openrouter (OPENROUTER_API_KEY) — routes to any model +# openai-codex (OAuth — hermes auth) — OpenAI Codex +# nous (OAuth — hermes auth) — Nous Portal +# zai (ZAI_API_KEY) — Z.AI / GLM +# kimi-coding (KIMI_API_KEY) — Kimi / Moonshot +# kimi-coding-cn (KIMI_CN_API_KEY) — Kimi / Moonshot (China) +# minimax (MINIMAX_API_KEY) — MiniMax +# minimax-cn (MINIMAX_CN_API_KEY) — MiniMax (China) +# +# For custom OpenAI-compatible endpoints, add base_url and api_key_env. +# +# fallback_model: +# provider: openrouter +# model: anthropic/claude-sonnet-4 +# +# ── Smart Model Routing ──────────────────────────────────────────────── +# Optional cheap-vs-strong routing for simple turns. +# Keeps the primary model for complex work, but can route short/simple +# messages to a cheaper model across providers. +# +# smart_model_routing: +# enabled: true +# max_simple_chars: 160 +# max_simple_words: 28 +# cheap_model: +# provider: openrouter +# model: google/gemini-2.5-flash +""" + + +_COMMENTED_SECTIONS = """ +# ── Security ────────────────────────────────────────────────────────── +# API keys, tokens, and passwords are redacted from tool output by default. +# Set to false to see full values (useful for debugging auth issues). +# +# security: +# redact_secrets: false + +# ── Fallback Model ──────────────────────────────────────────────────── +# Automatic provider failover when primary is unavailable. +# Uncomment and configure to enable. Triggers on rate limits (429), +# overload (529), service errors (503), or connection failures. +# +# Supported providers: +# openrouter (OPENROUTER_API_KEY) — routes to any model +# openai-codex (OAuth — hermes auth) — OpenAI Codex +# nous (OAuth — hermes auth) — Nous Portal +# zai (ZAI_API_KEY) — Z.AI / GLM +# kimi-coding (KIMI_API_KEY) — Kimi / Moonshot +# kimi-coding-cn (KIMI_CN_API_KEY) — Kimi / Moonshot (China) +# minimax (MINIMAX_API_KEY) — MiniMax +# minimax-cn (MINIMAX_CN_API_KEY) — MiniMax (China) +# +# For custom OpenAI-compatible endpoints, add base_url and api_key_env. +# +# fallback_model: +# provider: openrouter +# model: anthropic/claude-sonnet-4 +# +# ── Smart Model Routing ──────────────────────────────────────────────── +# Optional cheap-vs-strong routing for simple turns. +# Keeps the primary model for complex work, but can route short/simple +# messages to a cheaper model across providers. +# +# smart_model_routing: +# enabled: true +# max_simple_chars: 160 +# max_simple_words: 28 +# cheap_model: +# provider: openrouter +# model: google/gemini-2.5-flash +""" + + +def save_config(config: Dict[str, Any]): + """Save configuration to ~/.hermes/config.yaml.""" + if is_managed(): + managed_error("save configuration") + return + from utils import atomic_yaml_write + + ensure_hermes_home() + config_path = get_config_path() + normalized = _normalize_root_model_keys(_normalize_max_turns_config(config)) + + # Build optional commented-out sections for features that are off by + # default or only relevant when explicitly configured. + parts = [] + sec = normalized.get("security", {}) + if not sec or sec.get("redact_secrets") is None: + parts.append(_SECURITY_COMMENT) + fb = normalized.get("fallback_model", {}) + if not fb or not (fb.get("provider") and fb.get("model")): + parts.append(_FALLBACK_COMMENT) + + atomic_yaml_write( + config_path, + normalized, + extra_content="".join(parts) if parts else None, + ) + _secure_file(config_path) + + +def load_env() -> Dict[str, str]: + """Load environment variables from ~/.hermes/.env. + + Sanitizes lines before parsing so that corrupted files (e.g. + concatenated KEY=VALUE pairs on a single line) are handled + gracefully instead of producing mangled values such as duplicated + bot tokens. See #8908. + """ + env_path = get_env_path() + env_vars = {} + + if env_path.exists(): + # On Windows, open() defaults to the system locale (cp1252) which can + # fail on UTF-8 .env files. Use explicit UTF-8 only on Windows. + open_kw = {"encoding": "utf-8", "errors": "replace"} if _IS_WINDOWS else {} + with open(env_path, **open_kw) as f: + raw_lines = f.readlines() + # Sanitize before parsing: split concatenated lines & drop stale + # placeholders so corrupted .env files don't produce invalid tokens. + lines = _sanitize_env_lines(raw_lines) + for line in lines: + line = line.strip() + if line and not line.startswith('#') and '=' in line: + key, _, value = line.partition('=') + env_vars[key.strip()] = value.strip().strip('"\'') + + return env_vars + + +def _sanitize_env_lines(lines: list) -> list: + """Fix corrupted .env lines before reading or writing. + + Handles two known corruption patterns: + 1. Concatenated KEY=VALUE pairs on a single line (missing newline between + entries, e.g. ``ANTHROPIC_API_KEY=sk-...OPENAI_BASE_URL=https://...``). + 2. Stale ``KEY=***`` placeholder entries left by incomplete setup runs. + + Uses a known-keys set (OPTIONAL_ENV_VARS + _EXTRA_ENV_KEYS) so we only + split on real Hermes env var names, avoiding false positives from values + that happen to contain uppercase text with ``=``. + """ + # Build the known keys set lazily from OPTIONAL_ENV_VARS + extras. + # Done inside the function so OPTIONAL_ENV_VARS is guaranteed to be defined. + known_keys = set(OPTIONAL_ENV_VARS.keys()) | _EXTRA_ENV_KEYS + + sanitized: list[str] = [] + for line in lines: + raw = line.rstrip("\r\n") + stripped = raw.strip() + + # Preserve blank lines and comments + if not stripped or stripped.startswith("#"): + sanitized.append(raw + "\n") + continue + + # Detect concatenated KEY=VALUE pairs on one line. + # Search for known KEY= patterns at any position in the line. + split_positions = [] + for key_name in known_keys: + needle = key_name + "=" + idx = stripped.find(needle) + while idx >= 0: + split_positions.append(idx) + idx = stripped.find(needle, idx + len(needle)) + + if len(split_positions) > 1: + split_positions.sort() + # Deduplicate (shouldn't happen, but be safe) + split_positions = sorted(set(split_positions)) + for i, pos in enumerate(split_positions): + end = split_positions[i + 1] if i + 1 < len(split_positions) else len(stripped) + part = stripped[pos:end].strip() + if part: + sanitized.append(part + "\n") + else: + sanitized.append(stripped + "\n") + + return sanitized + + +def sanitize_env_file() -> int: + """Read, sanitize, and rewrite ~/.hermes/.env in place. + + Returns the number of lines that were fixed (concatenation splits + + placeholder removals). Returns 0 when no changes are needed. + """ + env_path = get_env_path() + if not env_path.exists(): + return 0 + + read_kw = {"encoding": "utf-8", "errors": "replace"} if _IS_WINDOWS else {} + write_kw = {"encoding": "utf-8"} if _IS_WINDOWS else {} + + with open(env_path, **read_kw) as f: + original_lines = f.readlines() + + sanitized = _sanitize_env_lines(original_lines) + + if sanitized == original_lines: + return 0 + + # Count fixes: difference in line count (from splits) + removed lines + fixes = abs(len(sanitized) - len(original_lines)) + if fixes == 0: + # Lines changed content (e.g. *** removal) even if count is same + fixes = sum(1 for a, b in zip(original_lines, sanitized) if a != b) + fixes += abs(len(sanitized) - len(original_lines)) + + fd, tmp_path = tempfile.mkstemp(dir=str(env_path.parent), suffix=".tmp", prefix=".env_") + try: + with os.fdopen(fd, "w", **write_kw) as f: + f.writelines(sanitized) + f.flush() + os.fsync(f.fileno()) + os.replace(tmp_path, env_path) + except BaseException: + try: + os.unlink(tmp_path) + except OSError: + pass + raise + _secure_file(env_path) + return fixes + + +def save_env_value(key: str, value: str): + """Save or update a value in ~/.hermes/.env.""" + if is_managed(): + managed_error(f"set {key}") + return + if not _ENV_VAR_NAME_RE.match(key): + raise ValueError(f"Invalid environment variable name: {key!r}") + value = value.replace("\n", "").replace("\r", "") + ensure_hermes_home() + env_path = get_env_path() + + # On Windows, open() defaults to the system locale (cp1252) which can + # cause OSError errno 22 on UTF-8 .env files. + read_kw = {"encoding": "utf-8", "errors": "replace"} if _IS_WINDOWS else {} + write_kw = {"encoding": "utf-8"} if _IS_WINDOWS else {} + + lines = [] + if env_path.exists(): + with open(env_path, **read_kw) as f: + lines = f.readlines() + # Sanitize on every read: split concatenated keys, drop stale placeholders + lines = _sanitize_env_lines(lines) + + # Find and update or append + found = False + for i, line in enumerate(lines): + if line.strip().startswith(f"{key}="): + lines[i] = f"{key}={value}\n" + found = True + break + + if not found: + # Ensure there's a newline at the end of the file before appending + if lines and not lines[-1].endswith("\n"): + lines[-1] += "\n" + lines.append(f"{key}={value}\n") + + fd, tmp_path = tempfile.mkstemp(dir=str(env_path.parent), suffix='.tmp', prefix='.env_') + try: + with os.fdopen(fd, 'w', **write_kw) as f: + f.writelines(lines) + f.flush() + os.fsync(f.fileno()) + os.replace(tmp_path, env_path) + except BaseException: + try: + os.unlink(tmp_path) + except OSError: + pass + raise + _secure_file(env_path) + + os.environ[key] = value + + # Restrict .env permissions to owner-only (contains API keys) + if not _IS_WINDOWS: + try: + os.chmod(env_path, stat.S_IRUSR | stat.S_IWUSR) + except OSError: + pass + + +def remove_env_value(key: str) -> bool: + """Remove a key from ~/.hermes/.env and os.environ. + + Returns True if the key was found and removed, False otherwise. + """ + if is_managed(): + managed_error(f"remove {key}") + return False + if not _ENV_VAR_NAME_RE.match(key): + raise ValueError(f"Invalid environment variable name: {key!r}") + env_path = get_env_path() + if not env_path.exists(): + os.environ.pop(key, None) + return False + + read_kw = {"encoding": "utf-8", "errors": "replace"} if _IS_WINDOWS else {} + write_kw = {"encoding": "utf-8"} if _IS_WINDOWS else {} + + with open(env_path, **read_kw) as f: + lines = f.readlines() + lines = _sanitize_env_lines(lines) + + new_lines = [line for line in lines if not line.strip().startswith(f"{key}=")] + found = len(new_lines) < len(lines) + + if found: + fd, tmp_path = tempfile.mkstemp(dir=str(env_path.parent), suffix='.tmp', prefix='.env_') + try: + with os.fdopen(fd, 'w', **write_kw) as f: + f.writelines(new_lines) + f.flush() + os.fsync(f.fileno()) + os.replace(tmp_path, env_path) + except BaseException: + try: + os.unlink(tmp_path) + except OSError: + pass + raise + _secure_file(env_path) + + os.environ.pop(key, None) + return found + + +def save_anthropic_oauth_token(value: str, save_fn=None): + """Persist an Anthropic OAuth/setup token and clear the API-key slot.""" + writer = save_fn or save_env_value + writer("ANTHROPIC_TOKEN", value) + writer("ANTHROPIC_API_KEY", "") + + +def use_anthropic_claude_code_credentials(save_fn=None): + """Use Claude Code's own credential files instead of persisting env tokens.""" + writer = save_fn or save_env_value + writer("ANTHROPIC_TOKEN", "") + writer("ANTHROPIC_API_KEY", "") + + +def save_anthropic_api_key(value: str, save_fn=None): + """Persist an Anthropic API key and clear the OAuth/setup-token slot.""" + writer = save_fn or save_env_value + writer("ANTHROPIC_API_KEY", value) + writer("ANTHROPIC_TOKEN", "") + + +def save_env_value_secure(key: str, value: str) -> Dict[str, Any]: + save_env_value(key, value) + return { + "success": True, + "stored_as": key, + "validated": False, + } + + + +def reload_env() -> int: + """Re-read ~/.hermes/.env into os.environ. Returns count of vars updated. + + Adds/updates vars that changed and removes vars that were deleted from + the .env file (but only vars known to Hermes — OPTIONAL_ENV_VARS and + _EXTRA_ENV_KEYS — to avoid clobbering unrelated environment). + """ + env_vars = load_env() + known_keys = set(OPTIONAL_ENV_VARS.keys()) | _EXTRA_ENV_KEYS + count = 0 + for key, value in env_vars.items(): + if os.environ.get(key) != value: + os.environ[key] = value + count += 1 + # Remove known Hermes vars that are no longer in .env + for key in known_keys: + if key not in env_vars and key in os.environ: + del os.environ[key] + count += 1 + return count + + +def get_env_value(key: str) -> Optional[str]: + """Get a value from ~/.hermes/.env or environment.""" + # Check environment first + if key in os.environ: + return os.environ[key] + + # Then check .env file + env_vars = load_env() + return env_vars.get(key) + + +# ============================================================================= +# Config display +# ============================================================================= + +def redact_key(key: str) -> str: + """Redact an API key for display.""" + if not key: + return color("(not set)", Colors.DIM) + if len(key) < 12: + return "***" + return key[:4] + "..." + key[-4:] + + +def show_config(): + """Display current configuration.""" + config = load_config() + + print() + print(color("┌─────────────────────────────────────────────────────────┐", Colors.CYAN)) + print(color("│ ⚕ Hermes Configuration │", Colors.CYAN)) + print(color("└─────────────────────────────────────────────────────────┘", Colors.CYAN)) + + # Paths + print() + print(color("◆ Paths", Colors.CYAN, Colors.BOLD)) + print(f" Config: {get_config_path()}") + print(f" Secrets: {get_env_path()}") + print(f" Install: {get_project_root()}") + + # API Keys + print() + print(color("◆ API Keys", Colors.CYAN, Colors.BOLD)) + + keys = [ + ("OPENROUTER_API_KEY", "OpenRouter"), + ("VOICE_TOOLS_OPENAI_KEY", "OpenAI (STT/TTS)"), + ("EXA_API_KEY", "Exa"), + ("PARALLEL_API_KEY", "Parallel"), + ("FIRECRAWL_API_KEY", "Firecrawl"), + ("TAVILY_API_KEY", "Tavily"), + ("BROWSERBASE_API_KEY", "Browserbase"), + ("BROWSER_USE_API_KEY", "Browser Use"), + ("FAL_KEY", "FAL"), + ] + + for env_key, name in keys: + value = get_env_value(env_key) + print(f" {name:<14} {redact_key(value)}") + from hermes_cli.auth import get_anthropic_key + anthropic_value = get_anthropic_key() + print(f" {'Anthropic':<14} {redact_key(anthropic_value)}") + + # Model settings + print() + print(color("◆ Model", Colors.CYAN, Colors.BOLD)) + print(f" Model: {config.get('model', 'not set')}") + print(f" Max turns: {config.get('agent', {}).get('max_turns', DEFAULT_CONFIG['agent']['max_turns'])}") + + # Display + print() + print(color("◆ Display", Colors.CYAN, Colors.BOLD)) + display = config.get('display', {}) + print(f" Personality: {display.get('personality', 'kawaii')}") + print(f" Reasoning: {'on' if display.get('show_reasoning', False) else 'off'}") + print(f" Bell: {'on' if display.get('bell_on_complete', False) else 'off'}") + + # Terminal + print() + print(color("◆ Terminal", Colors.CYAN, Colors.BOLD)) + terminal = config.get('terminal', {}) + print(f" Backend: {terminal.get('backend', 'local')}") + print(f" Working dir: {terminal.get('cwd', '.')}") + print(f" Timeout: {terminal.get('timeout', 60)}s") + + if terminal.get('backend') == 'docker': + print(f" Docker image: {terminal.get('docker_image', 'nikolaik/python-nodejs:python3.11-nodejs20')}") + elif terminal.get('backend') == 'singularity': + print(f" Image: {terminal.get('singularity_image', 'docker://nikolaik/python-nodejs:python3.11-nodejs20')}") + elif terminal.get('backend') == 'modal': + print(f" Modal image: {terminal.get('modal_image', 'nikolaik/python-nodejs:python3.11-nodejs20')}") + modal_token = get_env_value('MODAL_TOKEN_ID') + print(f" Modal token: {'configured' if modal_token else '(not set)'}") + elif terminal.get('backend') == 'daytona': + print(f" Daytona image: {terminal.get('daytona_image', 'nikolaik/python-nodejs:python3.11-nodejs20')}") + daytona_key = get_env_value('DAYTONA_API_KEY') + print(f" API key: {'configured' if daytona_key else '(not set)'}") + elif terminal.get('backend') == 'ssh': + ssh_host = get_env_value('TERMINAL_SSH_HOST') + ssh_user = get_env_value('TERMINAL_SSH_USER') + print(f" SSH host: {ssh_host or '(not set)'}") + print(f" SSH user: {ssh_user or '(not set)'}") + + # Timezone + print() + print(color("◆ Timezone", Colors.CYAN, Colors.BOLD)) + tz = config.get('timezone', '') + if tz: + print(f" Timezone: {tz}") + else: + print(f" Timezone: {color('(server-local)', Colors.DIM)}") + + # Compression + print() + print(color("◆ Context Compression", Colors.CYAN, Colors.BOLD)) + compression = config.get('compression', {}) + enabled = compression.get('enabled', True) + print(f" Enabled: {'yes' if enabled else 'no'}") + if enabled: + print(f" Threshold: {compression.get('threshold', 0.50) * 100:.0f}%") + print(f" Target ratio: {compression.get('target_ratio', 0.20) * 100:.0f}% of threshold preserved") + print(f" Protect last: {compression.get('protect_last_n', 20)} messages") + _aux_comp = config.get('auxiliary', {}).get('compression', {}) + _sm = _aux_comp.get('model', '') or '(auto)' + print(f" Model: {_sm}") + comp_provider = _aux_comp.get('provider', 'auto') + if comp_provider and comp_provider != 'auto': + print(f" Provider: {comp_provider}") + + # Auxiliary models + auxiliary = config.get('auxiliary', {}) + aux_tasks = { + "Vision": auxiliary.get('vision', {}), + "Web extract": auxiliary.get('web_extract', {}), + } + has_overrides = any( + t.get('provider', 'auto') != 'auto' or t.get('model', '') + for t in aux_tasks.values() + ) + if has_overrides: + print() + print(color("◆ Auxiliary Models (overrides)", Colors.CYAN, Colors.BOLD)) + for label, task_cfg in aux_tasks.items(): + prov = task_cfg.get('provider', 'auto') + mdl = task_cfg.get('model', '') + if prov != 'auto' or mdl: + parts = [f"provider={prov}"] + if mdl: + parts.append(f"model={mdl}") + print(f" {label:12s} {', '.join(parts)}") + + # Messaging + print() + print(color("◆ Messaging Platforms", Colors.CYAN, Colors.BOLD)) + + telegram_token = get_env_value('TELEGRAM_BOT_TOKEN') + discord_token = get_env_value('DISCORD_BOT_TOKEN') + + print(f" Telegram: {'configured' if telegram_token else color('not configured', Colors.DIM)}") + print(f" Discord: {'configured' if discord_token else color('not configured', Colors.DIM)}") + + # Skill config + try: + from agent.skill_utils import discover_all_skill_config_vars, resolve_skill_config_values + skill_vars = discover_all_skill_config_vars() + if skill_vars: + resolved = resolve_skill_config_values(skill_vars) + print() + print(color("◆ Skill Settings", Colors.CYAN, Colors.BOLD)) + for var in skill_vars: + key = var["key"] + value = resolved.get(key, "") + skill_name = var.get("skill", "") + display_val = str(value) if value else color("(not set)", Colors.DIM) + print(f" {key:<20s} {display_val} {color(f'[{skill_name}]', Colors.DIM)}") + except Exception: + pass + + print() + print(color("─" * 60, Colors.DIM)) + print(color(" hermes config edit # Edit config file", Colors.DIM)) + print(color(" hermes config set ", Colors.DIM)) + print(color(" hermes setup # Run setup wizard", Colors.DIM)) + print() + + +def edit_config(): + """Open config file in user's editor.""" + if is_managed(): + managed_error("edit configuration") + return + config_path = get_config_path() + + # Ensure config exists + if not config_path.exists(): + save_config(DEFAULT_CONFIG) + print(f"Created {config_path}") + + # Find editor + editor = os.getenv('EDITOR') or os.getenv('VISUAL') + + if not editor: + # Try common editors + for cmd in ['nano', 'vim', 'vi', 'code', 'notepad']: + import shutil + if shutil.which(cmd): + editor = cmd + break + + if not editor: + print("No editor found. Config file is at:") + print(f" {config_path}") + return + + print(f"Opening {config_path} in {editor}...") + subprocess.run([editor, str(config_path)]) + + +def set_config_value(key: str, value: str): + """Set a configuration value.""" + if is_managed(): + managed_error("set configuration values") + return + # Check if it's an API key (goes to .env) + api_keys = [ + 'OPENROUTER_API_KEY', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'VOICE_TOOLS_OPENAI_KEY', + 'EXA_API_KEY', 'PARALLEL_API_KEY', 'FIRECRAWL_API_KEY', 'FIRECRAWL_API_URL', + 'FIRECRAWL_GATEWAY_URL', 'TOOL_GATEWAY_DOMAIN', 'TOOL_GATEWAY_SCHEME', + 'TOOL_GATEWAY_USER_TOKEN', 'TAVILY_API_KEY', + 'BROWSERBASE_API_KEY', 'BROWSERBASE_PROJECT_ID', 'BROWSER_USE_API_KEY', + 'FAL_KEY', 'TELEGRAM_BOT_TOKEN', 'DISCORD_BOT_TOKEN', + 'TERMINAL_SSH_HOST', 'TERMINAL_SSH_USER', 'TERMINAL_SSH_KEY', + 'SUDO_PASSWORD', 'SLACK_BOT_TOKEN', 'SLACK_APP_TOKEN', + 'GITHUB_TOKEN', 'HONCHO_API_KEY', 'WANDB_API_KEY', + 'TINKER_API_KEY', + ] + + if key.upper() in api_keys or key.upper().endswith(('_API_KEY', '_TOKEN')) or key.upper().startswith('TERMINAL_SSH'): + save_env_value(key.upper(), value) + print(f"✓ Set {key} in {get_env_path()}") + return + + # Otherwise it goes to config.yaml + # Read the raw user config (not merged with defaults) to avoid + # dumping all default values back to the file + config_path = get_config_path() + user_config = {} + if config_path.exists(): + try: + with open(config_path, encoding="utf-8") as f: + user_config = yaml.safe_load(f) or {} + except Exception: + user_config = {} + + # Handle nested keys (e.g., "tts.provider") + parts = key.split('.') + current = user_config + + for part in parts[:-1]: + if part not in current or not isinstance(current.get(part), dict): + current[part] = {} + current = current[part] + + # Convert value to appropriate type + if value.lower() in ('true', 'yes', 'on'): + value = True + elif value.lower() in ('false', 'no', 'off'): + value = False + elif value.isdigit(): + value = int(value) + elif value.replace('.', '', 1).isdigit(): + value = float(value) + + current[parts[-1]] = value + + # Write only user config back (not the full merged defaults) + ensure_hermes_home() + from utils import atomic_yaml_write + atomic_yaml_write(config_path, user_config, sort_keys=False) + + # Keep .env in sync for keys that terminal_tool reads directly from env vars. + # config.yaml is authoritative, but terminal_tool only reads TERMINAL_ENV etc. + _config_to_env_sync = { + "terminal.backend": "TERMINAL_ENV", + "terminal.modal_mode": "TERMINAL_MODAL_MODE", + "terminal.docker_image": "TERMINAL_DOCKER_IMAGE", + "terminal.singularity_image": "TERMINAL_SINGULARITY_IMAGE", + "terminal.modal_image": "TERMINAL_MODAL_IMAGE", + "terminal.daytona_image": "TERMINAL_DAYTONA_IMAGE", + "terminal.docker_mount_cwd_to_workspace": "TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE", + "terminal.cwd": "TERMINAL_CWD", + "terminal.timeout": "TERMINAL_TIMEOUT", + "terminal.sandbox_dir": "TERMINAL_SANDBOX_DIR", + "terminal.persistent_shell": "TERMINAL_PERSISTENT_SHELL", + "terminal.container_cpu": "TERMINAL_CONTAINER_CPU", + "terminal.container_memory": "TERMINAL_CONTAINER_MEMORY", + "terminal.container_disk": "TERMINAL_CONTAINER_DISK", + "terminal.container_persistent": "TERMINAL_CONTAINER_PERSISTENT", + } + if key in _config_to_env_sync: + save_env_value(_config_to_env_sync[key], str(value)) + + print(f"✓ Set {key} = {value} in {config_path}") + + +# ============================================================================= +# Command handler +# ============================================================================= + +def config_command(args): + """Handle config subcommands.""" + subcmd = getattr(args, 'config_command', None) + + if subcmd is None or subcmd == "show": + show_config() + + elif subcmd == "edit": + edit_config() + + elif subcmd == "set": + key = getattr(args, 'key', None) + value = getattr(args, 'value', None) + if not key or value is None: + print("Usage: hermes config set ") + print() + print("Examples:") + print(" hermes config set model anthropic/claude-sonnet-4") + print(" hermes config set terminal.backend docker") + print(" hermes config set OPENROUTER_API_KEY sk-or-...") + sys.exit(1) + set_config_value(key, value) + + elif subcmd == "path": + print(get_config_path()) + + elif subcmd == "env-path": + print(get_env_path()) + + elif subcmd == "migrate": + print() + print(color("🔄 Checking configuration for updates...", Colors.CYAN, Colors.BOLD)) + print() + + # Check what's missing + missing_env = get_missing_env_vars(required_only=False) + missing_config = get_missing_config_fields() + current_ver, latest_ver = check_config_version() + + if not missing_env and not missing_config and current_ver >= latest_ver: + print(color("✓ Configuration is up to date!", Colors.GREEN)) + print() + return + + # Show what needs to be updated + if current_ver < latest_ver: + print(f" Config version: {current_ver} → {latest_ver}") + + if missing_config: + print(f"\n {len(missing_config)} new config option(s) will be added with defaults") + + required_missing = [v for v in missing_env if v.get("is_required")] + optional_missing = [ + v for v in missing_env + if not v.get("is_required") and not v.get("advanced") + ] + + if required_missing: + print(f"\n ⚠️ {len(required_missing)} required API key(s) missing:") + for var in required_missing: + print(f" • {var['name']}") + + if optional_missing: + print(f"\n ℹ️ {len(optional_missing)} optional API key(s) not configured:") + for var in optional_missing: + tools = var.get("tools", []) + tools_str = f" (enables: {', '.join(tools[:2])})" if tools else "" + print(f" • {var['name']}{tools_str}") + + print() + + # Run migration + results = migrate_config(interactive=True, quiet=False) + + print() + if results["env_added"] or results["config_added"]: + print(color("✓ Configuration updated!", Colors.GREEN)) + + if results["warnings"]: + print() + for warning in results["warnings"]: + print(color(f" ⚠️ {warning}", Colors.YELLOW)) + + print() + + elif subcmd == "check": + # Non-interactive check for what's missing + print() + print(color("📋 Configuration Status", Colors.CYAN, Colors.BOLD)) + print() + + current_ver, latest_ver = check_config_version() + if current_ver >= latest_ver: + print(f" Config version: {current_ver} ✓") + else: + print(color(f" Config version: {current_ver} → {latest_ver} (update available)", Colors.YELLOW)) + + print() + print(color(" Required:", Colors.BOLD)) + for var_name in REQUIRED_ENV_VARS: + if get_env_value(var_name): + print(f" ✓ {var_name}") + else: + print(color(f" ✗ {var_name} (missing)", Colors.RED)) + + print() + print(color(" Optional:", Colors.BOLD)) + for var_name, info in OPTIONAL_ENV_VARS.items(): + if get_env_value(var_name): + print(f" ✓ {var_name}") + else: + tools = info.get("tools", []) + tools_str = f" → {', '.join(tools[:2])}" if tools else "" + print(color(f" ○ {var_name}{tools_str}", Colors.DIM)) + + missing_config = get_missing_config_fields() + if missing_config: + print() + print(color(f" {len(missing_config)} new config option(s) available", Colors.YELLOW)) + print(" Run 'hermes config migrate' to add them") + + print() + + else: + print(f"Unknown config command: {subcmd}") + print() + print("Available commands:") + print(" hermes config Show current configuration") + print(" hermes config edit Open config in editor") + print(" hermes config set Set a config value") + print(" hermes config check Check for missing/outdated config") + print(" hermes config migrate Update config with new options") + print(" hermes config path Show config file path") + print(" hermes config env-path Show .env file path") + sys.exit(1) diff --git a/mindcli/_vendor/hermes_cli/copilot_auth.py b/mindcli/_vendor/hermes_cli/copilot_auth.py new file mode 100644 index 0000000..24859da --- /dev/null +++ b/mindcli/_vendor/hermes_cli/copilot_auth.py @@ -0,0 +1,299 @@ +"""GitHub Copilot authentication utilities. + +Implements the OAuth device code flow used by the Copilot CLI and handles +token validation/exchange for the Copilot API. + +Token type support (per GitHub docs): + gho_ OAuth token ✓ (default via copilot login) + github_pat_ Fine-grained PAT ✓ (needs Copilot Requests permission) + ghu_ GitHub App token ✓ (via environment variable) + ghp_ Classic PAT ✗ NOT SUPPORTED + +Credential search order (matching Copilot CLI behaviour): + 1. COPILOT_GITHUB_TOKEN env var + 2. GH_TOKEN env var + 3. GITHUB_TOKEN env var + 4. gh auth token CLI fallback +""" + +from __future__ import annotations + +import json +import logging +import os +import shutil +import subprocess +import time +from pathlib import Path +from typing import Optional + +logger = logging.getLogger(__name__) + +# OAuth device code flow constants (same client ID as opencode/Copilot CLI) +COPILOT_OAUTH_CLIENT_ID = "Ov23li8tweQw6odWQebz" +# Token type prefixes +_CLASSIC_PAT_PREFIX = "ghp_" +_SUPPORTED_PREFIXES = ("gho_", "github_pat_", "ghu_") + +# Env var search order (matches Copilot CLI) +COPILOT_ENV_VARS = ("COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN") + +# Polling constants +_DEVICE_CODE_POLL_INTERVAL = 5 # seconds +_DEVICE_CODE_POLL_SAFETY_MARGIN = 3 # seconds + + +def validate_copilot_token(token: str) -> tuple[bool, str]: + """Validate that a token is usable with the Copilot API. + + Returns (valid, message). + """ + token = token.strip() + if not token: + return False, "Empty token" + + if token.startswith(_CLASSIC_PAT_PREFIX): + return False, ( + "Classic Personal Access Tokens (ghp_*) are not supported by the " + "Copilot API. Use one of:\n" + " → `copilot login` or `hermes model` to authenticate via OAuth\n" + " → A fine-grained PAT (github_pat_*) with Copilot Requests permission\n" + " → `gh auth login` with the default device code flow (produces gho_* tokens)" + ) + + return True, "OK" + + +def resolve_copilot_token() -> tuple[str, str]: + """Resolve a GitHub token suitable for Copilot API use. + + Returns (token, source) where source describes where the token came from. + Raises ValueError if only a classic PAT is available. + """ + # 1. Check env vars in priority order + for env_var in COPILOT_ENV_VARS: + val = os.getenv(env_var, "").strip() + if val: + valid, msg = validate_copilot_token(val) + if not valid: + logger.warning( + "Token from %s is not supported: %s", env_var, msg + ) + continue + return val, env_var + + # 2. Fall back to gh auth token + token = _try_gh_cli_token() + if token: + valid, msg = validate_copilot_token(token) + if not valid: + raise ValueError( + f"Token from `gh auth token` is a classic PAT (ghp_*). {msg}" + ) + return token, "gh auth token" + + return "", "" + + +def _gh_cli_candidates() -> list[str]: + """Return candidate ``gh`` binary paths, including common Homebrew installs.""" + candidates: list[str] = [] + + resolved = shutil.which("gh") + if resolved: + candidates.append(resolved) + + for candidate in ( + "/opt/homebrew/bin/gh", + "/usr/local/bin/gh", + str(Path.home() / ".local" / "bin" / "gh"), + ): + if candidate in candidates: + continue + if os.path.isfile(candidate) and os.access(candidate, os.X_OK): + candidates.append(candidate) + + return candidates + + +def _try_gh_cli_token() -> Optional[str]: + """Return a token from ``gh auth token`` when the GitHub CLI is available. + + When COPILOT_GH_HOST is set, passes ``--hostname`` so gh returns the + correct host's token. Also strips GITHUB_TOKEN / GH_TOKEN from the + subprocess environment so ``gh`` reads from its own credential store + (hosts.yml) instead of just echoing the env var back. + """ + hostname = os.getenv("COPILOT_GH_HOST", "").strip() + + # Build a clean env so gh doesn't short-circuit on GITHUB_TOKEN / GH_TOKEN + clean_env = {k: v for k, v in os.environ.items() + if k not in ("GITHUB_TOKEN", "GH_TOKEN")} + + for gh_path in _gh_cli_candidates(): + cmd = [gh_path, "auth", "token"] + if hostname: + cmd += ["--hostname", hostname] + try: + result = subprocess.run( + cmd, + capture_output=True, + text=True, + timeout=5, + env=clean_env, + ) + except (FileNotFoundError, subprocess.TimeoutExpired) as exc: + logger.debug("gh CLI token lookup failed (%s): %s", gh_path, exc) + continue + if result.returncode == 0 and result.stdout.strip(): + return result.stdout.strip() + return None + + +# ─── OAuth Device Code Flow ──────────────────────────────────────────────── + +def copilot_device_code_login( + *, + host: str = "github.com", + timeout_seconds: float = 300, +) -> Optional[str]: + """Run the GitHub OAuth device code flow for Copilot. + + Prints instructions for the user, polls for completion, and returns + the OAuth access token on success, or None on failure/cancellation. + + This replicates the flow used by opencode and the Copilot CLI. + """ + import urllib.request + import urllib.parse + + domain = host.rstrip("/") + device_code_url = f"https://{domain}/login/device/code" + access_token_url = f"https://{domain}/login/oauth/access_token" + + # Step 1: Request device code + data = urllib.parse.urlencode({ + "client_id": COPILOT_OAUTH_CLIENT_ID, + "scope": "read:user", + }).encode() + + req = urllib.request.Request( + device_code_url, + data=data, + headers={ + "Accept": "application/json", + "Content-Type": "application/x-www-form-urlencoded", + "User-Agent": "HermesAgent/1.0", + }, + ) + + try: + with urllib.request.urlopen(req, timeout=15) as resp: + device_data = json.loads(resp.read().decode()) + except Exception as exc: + logger.error("Failed to initiate device authorization: %s", exc) + print(f" ✗ Failed to start device authorization: {exc}") + return None + + verification_uri = device_data.get("verification_uri", "https://github.com/login/device") + user_code = device_data.get("user_code", "") + device_code = device_data.get("device_code", "") + interval = max(device_data.get("interval", _DEVICE_CODE_POLL_INTERVAL), 1) + + if not device_code or not user_code: + print(" ✗ GitHub did not return a device code.") + return None + + # Step 2: Show instructions + print() + print(f" Open this URL in your browser: {verification_uri}") + print(f" Enter this code: {user_code}") + print() + print(" Waiting for authorization...", end="", flush=True) + + # Step 3: Poll for completion + deadline = time.time() + timeout_seconds + + while time.time() < deadline: + time.sleep(interval + _DEVICE_CODE_POLL_SAFETY_MARGIN) + + poll_data = urllib.parse.urlencode({ + "client_id": COPILOT_OAUTH_CLIENT_ID, + "device_code": device_code, + "grant_type": "urn:ietf:params:oauth:grant-type:device_code", + }).encode() + + poll_req = urllib.request.Request( + access_token_url, + data=poll_data, + headers={ + "Accept": "application/json", + "Content-Type": "application/x-www-form-urlencoded", + "User-Agent": "HermesAgent/1.0", + }, + ) + + try: + with urllib.request.urlopen(poll_req, timeout=10) as resp: + result = json.loads(resp.read().decode()) + except Exception: + print(".", end="", flush=True) + continue + + if result.get("access_token"): + print(" ✓") + return result["access_token"] + + error = result.get("error", "") + if error == "authorization_pending": + print(".", end="", flush=True) + continue + elif error == "slow_down": + # RFC 8628: add 5 seconds to polling interval + server_interval = result.get("interval") + if isinstance(server_interval, (int, float)) and server_interval > 0: + interval = int(server_interval) + else: + interval += 5 + print(".", end="", flush=True) + continue + elif error == "expired_token": + print() + print(" ✗ Device code expired. Please try again.") + return None + elif error == "access_denied": + print() + print(" ✗ Authorization was denied.") + return None + elif error: + print() + print(f" ✗ Authorization failed: {error}") + return None + + print() + print(" ✗ Timed out waiting for authorization.") + return None + + +# ─── Copilot API Headers ─────────────────────────────────────────────────── + +def copilot_request_headers( + *, + is_agent_turn: bool = True, + is_vision: bool = False, +) -> dict[str, str]: + """Build the standard headers for Copilot API requests. + + Replicates the header set used by opencode and the Copilot CLI. + """ + headers: dict[str, str] = { + "Editor-Version": "vscode/1.104.1", + "User-Agent": "HermesAgent/1.0", + "Copilot-Integration-Id": "vscode-chat", + "Openai-Intent": "conversation-edits", + "x-initiator": "agent" if is_agent_turn else "user", + } + if is_vision: + headers["Copilot-Vision-Request"] = "true" + + return headers diff --git a/mindcli/_vendor/hermes_cli/cron.py b/mindcli/_vendor/hermes_cli/cron.py new file mode 100644 index 0000000..e0ab600 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/cron.py @@ -0,0 +1,290 @@ +""" +Cron subcommand for hermes CLI. + +Handles standalone cron management commands like list, create, edit, +pause/resume/run/remove, status, and tick. +""" + +import json +import sys +from pathlib import Path +from typing import Iterable, List, Optional + +PROJECT_ROOT = Path(__file__).parent.parent.resolve() +sys.path.insert(0, str(PROJECT_ROOT)) + +from hermes_cli.colors import Colors, color + + +def _normalize_skills(single_skill=None, skills: Optional[Iterable[str]] = None) -> Optional[List[str]]: + if skills is None: + if single_skill is None: + return None + raw_items = [single_skill] + else: + raw_items = list(skills) + + normalized: List[str] = [] + for item in raw_items: + text = str(item or "").strip() + if text and text not in normalized: + normalized.append(text) + return normalized + + +def _cron_api(**kwargs): + from tools.cronjob_tools import cronjob as cronjob_tool + + return json.loads(cronjob_tool(**kwargs)) + + +def cron_list(show_all: bool = False): + """List all scheduled jobs.""" + from cron.jobs import list_jobs + + jobs = list_jobs(include_disabled=show_all) + + if not jobs: + print(color("No scheduled jobs.", Colors.DIM)) + print(color("Create one with 'hermes cron create ...' or the /cron command in chat.", Colors.DIM)) + return + + print() + print(color("┌─────────────────────────────────────────────────────────────────────────┐", Colors.CYAN)) + print(color("│ Scheduled Jobs │", Colors.CYAN)) + print(color("└─────────────────────────────────────────────────────────────────────────┘", Colors.CYAN)) + print() + + for job in jobs: + job_id = job.get("id", "?") + name = job.get("name", "(unnamed)") + schedule = job.get("schedule_display", job.get("schedule", {}).get("value", "?")) + state = job.get("state", "scheduled" if job.get("enabled", True) else "paused") + next_run = job.get("next_run_at", "?") + + repeat_info = job.get("repeat", {}) + repeat_times = repeat_info.get("times") + repeat_completed = repeat_info.get("completed", 0) + repeat_str = f"{repeat_completed}/{repeat_times}" if repeat_times else "∞" + + deliver = job.get("deliver", ["local"]) + if isinstance(deliver, str): + deliver = [deliver] + deliver_str = ", ".join(deliver) + + skills = job.get("skills") or ([job["skill"]] if job.get("skill") else []) + if state == "paused": + status = color("[paused]", Colors.YELLOW) + elif state == "completed": + status = color("[completed]", Colors.BLUE) + elif job.get("enabled", True): + status = color("[active]", Colors.GREEN) + else: + status = color("[disabled]", Colors.RED) + + print(f" {color(job_id, Colors.YELLOW)} {status}") + print(f" Name: {name}") + print(f" Schedule: {schedule}") + print(f" Repeat: {repeat_str}") + print(f" Next run: {next_run}") + print(f" Deliver: {deliver_str}") + if skills: + print(f" Skills: {', '.join(skills)}") + script = job.get("script") + if script: + print(f" Script: {script}") + + # Execution history + last_status = job.get("last_status") + if last_status: + last_run = job.get("last_run_at", "?") + if last_status == "ok": + status_display = color("ok", Colors.GREEN) + else: + status_display = color(f"{last_status}: {job.get('last_error', '?')}", Colors.RED) + print(f" Last run: {last_run} {status_display}") + + delivery_err = job.get("last_delivery_error") + if delivery_err: + print(f" {color('⚠ Delivery failed:', Colors.YELLOW)} {delivery_err}") + + print() + + from hermes_cli.gateway import find_gateway_pids + if not find_gateway_pids(): + print(color(" ⚠ Gateway is not running — jobs won't fire automatically.", Colors.YELLOW)) + print(color(" Start it with: hermes gateway install", Colors.DIM)) + print(color(" sudo hermes gateway install --system # Linux servers", Colors.DIM)) + print() + + +def cron_tick(): + """Run due jobs once and exit.""" + from cron.scheduler import tick + tick(verbose=True) + + +def cron_status(): + """Show cron execution status.""" + from cron.jobs import list_jobs + from hermes_cli.gateway import find_gateway_pids + + print() + + pids = find_gateway_pids() + if pids: + print(color("✓ Gateway is running — cron jobs will fire automatically", Colors.GREEN)) + print(f" PID: {', '.join(map(str, pids))}") + else: + print(color("✗ Gateway is not running — cron jobs will NOT fire", Colors.RED)) + print() + print(" To enable automatic execution:") + print(" hermes gateway install # Install as a user service") + print(" sudo hermes gateway install --system # Linux servers: boot-time system service") + print(" hermes gateway # Or run in foreground") + + print() + + jobs = list_jobs(include_disabled=False) + if jobs: + next_runs = [j.get("next_run_at") for j in jobs if j.get("next_run_at")] + print(f" {len(jobs)} active job(s)") + if next_runs: + print(f" Next run: {min(next_runs)}") + else: + print(" No active jobs") + + print() + + +def cron_create(args): + result = _cron_api( + action="create", + schedule=args.schedule, + prompt=args.prompt, + name=getattr(args, "name", None), + deliver=getattr(args, "deliver", None), + repeat=getattr(args, "repeat", None), + skill=getattr(args, "skill", None), + skills=_normalize_skills(getattr(args, "skill", None), getattr(args, "skills", None)), + script=getattr(args, "script", None), + ) + if not result.get("success"): + print(color(f"Failed to create job: {result.get('error', 'unknown error')}", Colors.RED)) + return 1 + print(color(f"Created job: {result['job_id']}", Colors.GREEN)) + print(f" Name: {result['name']}") + print(f" Schedule: {result['schedule']}") + if result.get("skills"): + print(f" Skills: {', '.join(result['skills'])}") + job_data = result.get("job", {}) + if job_data.get("script"): + print(f" Script: {job_data['script']}") + print(f" Next run: {result['next_run_at']}") + return 0 + + +def cron_edit(args): + from cron.jobs import get_job + + job = get_job(args.job_id) + if not job: + print(color(f"Job not found: {args.job_id}", Colors.RED)) + return 1 + + existing_skills = list(job.get("skills") or ([] if not job.get("skill") else [job.get("skill")])) + replacement_skills = _normalize_skills(getattr(args, "skill", None), getattr(args, "skills", None)) + add_skills = _normalize_skills(None, getattr(args, "add_skills", None)) or [] + remove_skills = set(_normalize_skills(None, getattr(args, "remove_skills", None)) or []) + + final_skills = None + if getattr(args, "clear_skills", False): + final_skills = [] + elif replacement_skills is not None: + final_skills = replacement_skills + elif add_skills or remove_skills: + final_skills = [skill for skill in existing_skills if skill not in remove_skills] + for skill in add_skills: + if skill not in final_skills: + final_skills.append(skill) + + result = _cron_api( + action="update", + job_id=args.job_id, + schedule=getattr(args, "schedule", None), + prompt=getattr(args, "prompt", None), + name=getattr(args, "name", None), + deliver=getattr(args, "deliver", None), + repeat=getattr(args, "repeat", None), + skills=final_skills, + script=getattr(args, "script", None), + ) + if not result.get("success"): + print(color(f"Failed to update job: {result.get('error', 'unknown error')}", Colors.RED)) + return 1 + + updated = result["job"] + print(color(f"Updated job: {updated['job_id']}", Colors.GREEN)) + print(f" Name: {updated['name']}") + print(f" Schedule: {updated['schedule']}") + if updated.get("skills"): + print(f" Skills: {', '.join(updated['skills'])}") + else: + print(" Skills: none") + if updated.get("script"): + print(f" Script: {updated['script']}") + return 0 + + +def _job_action(action: str, job_id: str, success_verb: str) -> int: + result = _cron_api(action=action, job_id=job_id) + if not result.get("success"): + print(color(f"Failed to {action} job: {result.get('error', 'unknown error')}", Colors.RED)) + return 1 + job = result.get("job") or result.get("removed_job") or {} + print(color(f"{success_verb} job: {job.get('name', job_id)} ({job_id})", Colors.GREEN)) + if action in {"resume", "run"} and result.get("job", {}).get("next_run_at"): + print(f" Next run: {result['job']['next_run_at']}") + if action == "run": + print(" It will run on the next scheduler tick.") + return 0 + + +def cron_command(args): + """Handle cron subcommands.""" + subcmd = getattr(args, 'cron_command', None) + + if subcmd is None or subcmd == "list": + show_all = getattr(args, 'all', False) + cron_list(show_all) + return 0 + + if subcmd == "status": + cron_status() + return 0 + + if subcmd == "tick": + cron_tick() + return 0 + + if subcmd in {"create", "add"}: + return cron_create(args) + + if subcmd == "edit": + return cron_edit(args) + + if subcmd == "pause": + return _job_action("pause", args.job_id, "Paused") + + if subcmd == "resume": + return _job_action("resume", args.job_id, "Resumed") + + if subcmd == "run": + return _job_action("run", args.job_id, "Triggered") + + if subcmd in {"remove", "rm", "delete"}: + return _job_action("remove", args.job_id, "Removed") + + print(f"Unknown cron command: {subcmd}") + print("Usage: hermes cron [list|create|edit|pause|resume|run|remove|status|tick]") + sys.exit(1) diff --git a/mindcli/_vendor/hermes_cli/curses_ui.py b/mindcli/_vendor/hermes_cli/curses_ui.py new file mode 100644 index 0000000..4880171 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/curses_ui.py @@ -0,0 +1,445 @@ +"""Shared curses-based UI components for Hermes CLI. + +Used by `hermes tools` and `hermes skills` for interactive checklists. +Provides a curses multi-select with keyboard navigation, plus a +text-based numbered fallback for terminals without curses support. +""" +import sys +from typing import Callable, List, Optional, Set + +from hermes_cli.colors import Colors, color + + +def flush_stdin() -> None: + """Flush any stray bytes from the stdin input buffer. + + Must be called after ``curses.wrapper()`` (or any terminal-mode library + like simple_term_menu) returns, **before** the next ``input()`` / + ``getpass.getpass()`` call. ``curses.endwin()`` restores the terminal + but does NOT drain the OS input buffer — leftover escape-sequence bytes + (from arrow keys, terminal mode-switch responses, or rapid keypresses) + remain buffered and silently get consumed by the next ``input()`` call, + corrupting user data (e.g. writing ``^[^[`` into .env files). + + On non-TTY stdin (piped, redirected) or Windows, this is a no-op. + """ + try: + if not sys.stdin.isatty(): + return + import termios + termios.tcflush(sys.stdin, termios.TCIFLUSH) + except Exception: + pass + + +def curses_checklist( + title: str, + items: List[str], + selected: Set[int], + *, + cancel_returns: Set[int] | None = None, + status_fn: Optional[Callable[[Set[int]], str]] = None, +) -> Set[int]: + """Curses multi-select checklist. Returns set of selected indices. + + Args: + title: Header line displayed above the checklist. + items: Display labels for each row. + selected: Indices that start checked (pre-selected). + cancel_returns: Returned on ESC/q. Defaults to the original *selected*. + status_fn: Optional callback ``f(chosen_indices) -> str`` whose return + value is rendered on the bottom row of the terminal. Use this for + live aggregate info (e.g. estimated token counts). + """ + if cancel_returns is None: + cancel_returns = set(selected) + + # Safety: curses and input() both hang or spin when stdin is not a + # terminal (e.g. subprocess pipe). Return defaults immediately. + if not sys.stdin.isatty(): + return cancel_returns + + try: + import curses + chosen = set(selected) + result_holder: list = [None] + + def _draw(stdscr): + curses.curs_set(0) + if curses.has_colors(): + curses.start_color() + curses.use_default_colors() + curses.init_pair(1, curses.COLOR_GREEN, -1) + curses.init_pair(2, curses.COLOR_YELLOW, -1) + curses.init_pair(3, 8, -1) # dim gray + cursor = 0 + scroll_offset = 0 + + while True: + stdscr.clear() + max_y, max_x = stdscr.getmaxyx() + + # Reserve bottom row for status bar when status_fn provided + footer_rows = 1 if status_fn else 0 + + # Header + try: + hattr = curses.A_BOLD + if curses.has_colors(): + hattr |= curses.color_pair(2) + stdscr.addnstr(0, 0, title, max_x - 1, hattr) + stdscr.addnstr( + 1, 0, + " ↑↓ navigate SPACE toggle ENTER confirm ESC cancel", + max_x - 1, curses.A_DIM, + ) + except curses.error: + pass + + # Scrollable item list + visible_rows = max_y - 3 - footer_rows + if cursor < scroll_offset: + scroll_offset = cursor + elif cursor >= scroll_offset + visible_rows: + scroll_offset = cursor - visible_rows + 1 + + for draw_i, i in enumerate( + range(scroll_offset, min(len(items), scroll_offset + visible_rows)) + ): + y = draw_i + 3 + if y >= max_y - 1 - footer_rows: + break + check = "✓" if i in chosen else " " + arrow = "→" if i == cursor else " " + line = f" {arrow} [{check}] {items[i]}" + attr = curses.A_NORMAL + if i == cursor: + attr = curses.A_BOLD + if curses.has_colors(): + attr |= curses.color_pair(1) + try: + stdscr.addnstr(y, 0, line, max_x - 1, attr) + except curses.error: + pass + + # Status bar (bottom row, right-aligned) + if status_fn: + try: + status_text = status_fn(chosen) + if status_text: + # Right-align on the bottom row + sx = max(0, max_x - len(status_text) - 1) + sattr = curses.A_DIM + if curses.has_colors(): + sattr |= curses.color_pair(3) + stdscr.addnstr(max_y - 1, sx, status_text, max_x - sx - 1, sattr) + except curses.error: + pass + + stdscr.refresh() + key = stdscr.getch() + + if key in (curses.KEY_UP, ord("k")): + cursor = (cursor - 1) % len(items) + elif key in (curses.KEY_DOWN, ord("j")): + cursor = (cursor + 1) % len(items) + elif key == ord(" "): + chosen.symmetric_difference_update({cursor}) + elif key in (curses.KEY_ENTER, 10, 13): + result_holder[0] = set(chosen) + return + elif key in (27, ord("q")): + result_holder[0] = cancel_returns + return + + curses.wrapper(_draw) + flush_stdin() + return result_holder[0] if result_holder[0] is not None else cancel_returns + + except Exception: + return _numbered_fallback(title, items, selected, cancel_returns, status_fn) + + +def curses_radiolist( + title: str, + items: List[str], + selected: int = 0, + *, + cancel_returns: int | None = None, +) -> int: + """Curses single-select radio list. Returns the selected index. + + Args: + title: Header line displayed above the list. + items: Display labels for each row. + selected: Index that starts selected (pre-selected). + cancel_returns: Returned on ESC/q. Defaults to the original *selected*. + """ + if cancel_returns is None: + cancel_returns = selected + + if not sys.stdin.isatty(): + return cancel_returns + + try: + import curses + result_holder: list = [None] + + def _draw(stdscr): + curses.curs_set(0) + if curses.has_colors(): + curses.start_color() + curses.use_default_colors() + curses.init_pair(1, curses.COLOR_GREEN, -1) + curses.init_pair(2, curses.COLOR_YELLOW, -1) + cursor = selected + scroll_offset = 0 + + while True: + stdscr.clear() + max_y, max_x = stdscr.getmaxyx() + + # Header + try: + hattr = curses.A_BOLD + if curses.has_colors(): + hattr |= curses.color_pair(2) + stdscr.addnstr(0, 0, title, max_x - 1, hattr) + stdscr.addnstr( + 1, 0, + " \u2191\u2193 navigate ENTER/SPACE select ESC cancel", + max_x - 1, curses.A_DIM, + ) + except curses.error: + pass + + # Scrollable item list + visible_rows = max_y - 4 + if cursor < scroll_offset: + scroll_offset = cursor + elif cursor >= scroll_offset + visible_rows: + scroll_offset = cursor - visible_rows + 1 + + for draw_i, i in enumerate( + range(scroll_offset, min(len(items), scroll_offset + visible_rows)) + ): + y = draw_i + 3 + if y >= max_y - 1: + break + radio = "\u25cf" if i == selected else "\u25cb" + arrow = "\u2192" if i == cursor else " " + line = f" {arrow} ({radio}) {items[i]}" + attr = curses.A_NORMAL + if i == cursor: + attr = curses.A_BOLD + if curses.has_colors(): + attr |= curses.color_pair(1) + try: + stdscr.addnstr(y, 0, line, max_x - 1, attr) + except curses.error: + pass + + stdscr.refresh() + key = stdscr.getch() + + if key in (curses.KEY_UP, ord("k")): + cursor = (cursor - 1) % len(items) + elif key in (curses.KEY_DOWN, ord("j")): + cursor = (cursor + 1) % len(items) + elif key in (ord(" "), curses.KEY_ENTER, 10, 13): + result_holder[0] = cursor + return + elif key in (27, ord("q")): + result_holder[0] = cancel_returns + return + + curses.wrapper(_draw) + flush_stdin() + return result_holder[0] if result_holder[0] is not None else cancel_returns + + except Exception: + return _radio_numbered_fallback(title, items, selected, cancel_returns) + + +def _radio_numbered_fallback( + title: str, + items: List[str], + selected: int, + cancel_returns: int, +) -> int: + """Text-based numbered fallback for radio selection.""" + print(color(f"\n {title}", Colors.YELLOW)) + print(color(" Select by number, Enter to confirm.\n", Colors.DIM)) + + for i, label in enumerate(items): + marker = color("(\u25cf)", Colors.GREEN) if i == selected else "(\u25cb)" + print(f" {marker} {i + 1:>2}. {label}") + print() + try: + val = input(color(f" Choice [default {selected + 1}]: ", Colors.DIM)).strip() + if not val: + return selected + idx = int(val) - 1 + if 0 <= idx < len(items): + return idx + return selected + except (ValueError, KeyboardInterrupt, EOFError): + return cancel_returns + + +def curses_single_select( + title: str, + items: List[str], + default_index: int = 0, + *, + cancel_label: str = "Cancel", +) -> int | None: + """Curses single-select menu. Returns selected index or None on cancel. + + Works inside prompt_toolkit because curses.wrapper() restores the terminal + safely, unlike simple_term_menu which conflicts with /dev/tty. + """ + if not sys.stdin.isatty(): + return None + + try: + import curses + result_holder: list = [None] + + all_items = list(items) + [cancel_label] + cancel_idx = len(items) + + def _draw(stdscr): + curses.curs_set(0) + if curses.has_colors(): + curses.start_color() + curses.use_default_colors() + curses.init_pair(1, curses.COLOR_GREEN, -1) + curses.init_pair(2, curses.COLOR_YELLOW, -1) + cursor = min(default_index, len(all_items) - 1) + scroll_offset = 0 + + while True: + stdscr.clear() + max_y, max_x = stdscr.getmaxyx() + + try: + hattr = curses.A_BOLD + if curses.has_colors(): + hattr |= curses.color_pair(2) + stdscr.addnstr(0, 0, title, max_x - 1, hattr) + stdscr.addnstr( + 1, 0, + " ↑↓ navigate ENTER confirm ESC/q cancel", + max_x - 1, curses.A_DIM, + ) + except curses.error: + pass + + visible_rows = max_y - 3 + if cursor < scroll_offset: + scroll_offset = cursor + elif cursor >= scroll_offset + visible_rows: + scroll_offset = cursor - visible_rows + 1 + + for draw_i, i in enumerate( + range(scroll_offset, min(len(all_items), scroll_offset + visible_rows)) + ): + y = draw_i + 3 + if y >= max_y - 1: + break + arrow = "→" if i == cursor else " " + line = f" {arrow} {all_items[i]}" + attr = curses.A_NORMAL + if i == cursor: + attr = curses.A_BOLD + if curses.has_colors(): + attr |= curses.color_pair(1) + try: + stdscr.addnstr(y, 0, line, max_x - 1, attr) + except curses.error: + pass + + stdscr.refresh() + key = stdscr.getch() + + if key in (curses.KEY_UP, ord("k")): + cursor = (cursor - 1) % len(all_items) + elif key in (curses.KEY_DOWN, ord("j")): + cursor = (cursor + 1) % len(all_items) + elif key in (curses.KEY_ENTER, 10, 13): + result_holder[0] = cursor + return + elif key in (27, ord("q")): + result_holder[0] = None + return + + curses.wrapper(_draw) + flush_stdin() + if result_holder[0] is not None and result_holder[0] >= cancel_idx: + return None + return result_holder[0] + + except Exception: + all_items = list(items) + [cancel_label] + cancel_idx = len(items) + return _numbered_single_fallback(title, all_items, cancel_idx) + + +def _numbered_single_fallback( + title: str, + items: List[str], + cancel_idx: int, +) -> int | None: + """Text-based numbered fallback for single-select.""" + print(f"\n {title}\n") + for i, label in enumerate(items, 1): + print(f" {i}. {label}") + print() + try: + val = input(f" Choice [1-{len(items)}]: ").strip() + if not val: + return None + idx = int(val) - 1 + if 0 <= idx < len(items) and idx < cancel_idx: + return idx + if idx == cancel_idx: + return None + except (ValueError, KeyboardInterrupt, EOFError): + pass + return None + + +def _numbered_fallback( + title: str, + items: List[str], + selected: Set[int], + cancel_returns: Set[int], + status_fn: Optional[Callable[[Set[int]], str]] = None, +) -> Set[int]: + """Text-based toggle fallback for terminals without curses.""" + chosen = set(selected) + print(color(f"\n {title}", Colors.YELLOW)) + print(color(" Toggle by number, Enter to confirm.\n", Colors.DIM)) + + while True: + for i, label in enumerate(items): + marker = color("[✓]", Colors.GREEN) if i in chosen else "[ ]" + print(f" {marker} {i + 1:>2}. {label}") + if status_fn: + status_text = status_fn(chosen) + if status_text: + print(color(f"\n {status_text}", Colors.DIM)) + print() + try: + val = input(color(" Toggle # (or Enter to confirm): ", Colors.DIM)).strip() + if not val: + break + idx = int(val) - 1 + if 0 <= idx < len(items): + chosen.symmetric_difference_update({idx}) + except (ValueError, KeyboardInterrupt, EOFError): + return cancel_returns + print() + + return chosen diff --git a/mindcli/_vendor/hermes_cli/debug.py b/mindcli/_vendor/hermes_cli/debug.py new file mode 100644 index 0000000..3607db9 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/debug.py @@ -0,0 +1,336 @@ +"""``hermes debug`` — debug tools for Hermes Agent. + +Currently supports: + hermes debug share Upload debug report (system info + logs) to a + paste service and print a shareable URL. +""" + +import io +import sys +import urllib.error +import urllib.parse +import urllib.request +from pathlib import Path +from typing import Optional + +from hermes_constants import get_hermes_home + + +# --------------------------------------------------------------------------- +# Paste services — try paste.rs first, dpaste.com as fallback. +# --------------------------------------------------------------------------- + +_PASTE_RS_URL = "https://paste.rs/" +_DPASTE_COM_URL = "https://dpaste.com/api/" + +# Maximum bytes to read from a single log file for upload. +# paste.rs caps at ~1 MB; we stay under that with headroom. +_MAX_LOG_BYTES = 512_000 + + +def _upload_paste_rs(content: str) -> str: + """Upload to paste.rs. Returns the paste URL. + + paste.rs accepts a plain POST body and returns the URL directly. + """ + data = content.encode("utf-8") + req = urllib.request.Request( + _PASTE_RS_URL, data=data, method="POST", + headers={ + "Content-Type": "text/plain; charset=utf-8", + "User-Agent": "hermes-agent/debug-share", + }, + ) + with urllib.request.urlopen(req, timeout=30) as resp: + url = resp.read().decode("utf-8").strip() + if not url.startswith("http"): + raise ValueError(f"Unexpected response from paste.rs: {url[:200]}") + return url + + +def _upload_dpaste_com(content: str, expiry_days: int = 7) -> str: + """Upload to dpaste.com. Returns the paste URL. + + dpaste.com uses multipart form data. + """ + boundary = "----HermesDebugBoundary9f3c" + + def _field(name: str, value: str) -> str: + return ( + f"--{boundary}\r\n" + f'Content-Disposition: form-data; name="{name}"\r\n' + f"\r\n" + f"{value}\r\n" + ) + + body = ( + _field("content", content) + + _field("syntax", "text") + + _field("expiry_days", str(expiry_days)) + + f"--{boundary}--\r\n" + ).encode("utf-8") + + req = urllib.request.Request( + _DPASTE_COM_URL, data=body, method="POST", + headers={ + "Content-Type": f"multipart/form-data; boundary={boundary}", + "User-Agent": "hermes-agent/debug-share", + }, + ) + with urllib.request.urlopen(req, timeout=30) as resp: + url = resp.read().decode("utf-8").strip() + if not url.startswith("http"): + raise ValueError(f"Unexpected response from dpaste.com: {url[:200]}") + return url + + +def upload_to_pastebin(content: str, expiry_days: int = 7) -> str: + """Upload *content* to a paste service, trying paste.rs then dpaste.com. + + Returns the paste URL on success, raises on total failure. + """ + errors: list[str] = [] + + # Try paste.rs first (simple, fast) + try: + return _upload_paste_rs(content) + except Exception as exc: + errors.append(f"paste.rs: {exc}") + + # Fallback: dpaste.com (supports expiry) + try: + return _upload_dpaste_com(content, expiry_days=expiry_days) + except Exception as exc: + errors.append(f"dpaste.com: {exc}") + + raise RuntimeError( + "Failed to upload to any paste service:\n " + "\n ".join(errors) + ) + + +# --------------------------------------------------------------------------- +# Log file reading +# --------------------------------------------------------------------------- + +def _resolve_log_path(log_name: str) -> Optional[Path]: + """Find the log file for *log_name*, falling back to the .1 rotation. + + Returns the path if found, or None. + """ + from hermes_cli.logs import LOG_FILES + + filename = LOG_FILES.get(log_name) + if not filename: + return None + + log_dir = get_hermes_home() / "logs" + primary = log_dir / filename + if primary.exists() and primary.stat().st_size > 0: + return primary + + # Fall back to the most recent rotated file (.1). + rotated = log_dir / f"{filename}.1" + if rotated.exists() and rotated.stat().st_size > 0: + return rotated + + return None + + +def _read_log_tail(log_name: str, num_lines: int) -> str: + """Read the last *num_lines* from a log file, or return a placeholder.""" + from hermes_cli.logs import _read_last_n_lines + + log_path = _resolve_log_path(log_name) + if log_path is None: + return "(file not found)" + + try: + lines = _read_last_n_lines(log_path, num_lines) + return "".join(lines).rstrip("\n") + except Exception as exc: + return f"(error reading: {exc})" + + +def _read_full_log(log_name: str, max_bytes: int = _MAX_LOG_BYTES) -> Optional[str]: + """Read a log file for standalone upload. + + Returns the file content (last *max_bytes* if truncated), or None if the + file doesn't exist or is empty. + """ + log_path = _resolve_log_path(log_name) + if log_path is None: + return None + + try: + size = log_path.stat().st_size + if size == 0: + return None + + if size <= max_bytes: + return log_path.read_text(encoding="utf-8", errors="replace") + + # File is larger than max_bytes — read the tail. + with open(log_path, "rb") as f: + f.seek(size - max_bytes) + # Skip partial line at the seek point. + f.readline() + content = f.read().decode("utf-8", errors="replace") + return f"[... truncated — showing last ~{max_bytes // 1024}KB ...]\n{content}" + except Exception: + return None + + +# --------------------------------------------------------------------------- +# Debug report collection +# --------------------------------------------------------------------------- + +def _capture_dump() -> str: + """Run ``hermes dump`` and return its stdout as a string.""" + from hermes_cli.dump import run_dump + + class _FakeArgs: + show_keys = False + + old_stdout = sys.stdout + sys.stdout = capture = io.StringIO() + try: + run_dump(_FakeArgs()) + except SystemExit: + pass + finally: + sys.stdout = old_stdout + + return capture.getvalue() + + +def collect_debug_report(*, log_lines: int = 200, dump_text: str = "") -> str: + """Build the summary debug report: system dump + log tails. + + Parameters + ---------- + log_lines + Number of recent lines to include per log file. + dump_text + Pre-captured dump output. If empty, ``hermes dump`` is run + internally. + + Returns the report as a plain-text string ready for upload. + """ + buf = io.StringIO() + + if not dump_text: + dump_text = _capture_dump() + buf.write(dump_text) + + # ── Recent log tails (summary only) ────────────────────────────────── + buf.write("\n\n") + buf.write(f"--- agent.log (last {log_lines} lines) ---\n") + buf.write(_read_log_tail("agent", log_lines)) + buf.write("\n\n") + + errors_lines = min(log_lines, 100) + buf.write(f"--- errors.log (last {errors_lines} lines) ---\n") + buf.write(_read_log_tail("errors", errors_lines)) + buf.write("\n\n") + + buf.write(f"--- gateway.log (last {errors_lines} lines) ---\n") + buf.write(_read_log_tail("gateway", errors_lines)) + buf.write("\n") + + return buf.getvalue() + + +# --------------------------------------------------------------------------- +# CLI entry points +# --------------------------------------------------------------------------- + +def run_debug_share(args): + """Collect debug report + full logs, upload each, print URLs.""" + log_lines = getattr(args, "lines", 200) + expiry = getattr(args, "expire", 7) + local_only = getattr(args, "local", False) + + print("Collecting debug report...") + + # Capture dump once — prepended to every paste for context. + dump_text = _capture_dump() + + report = collect_debug_report(log_lines=log_lines, dump_text=dump_text) + agent_log = _read_full_log("agent") + gateway_log = _read_full_log("gateway") + + # Prepend dump header to each full log so every paste is self-contained. + if agent_log: + agent_log = dump_text + "\n\n--- full agent.log ---\n" + agent_log + if gateway_log: + gateway_log = dump_text + "\n\n--- full gateway.log ---\n" + gateway_log + + if local_only: + print(report) + if agent_log: + print(f"\n\n{'=' * 60}") + print("FULL agent.log") + print(f"{'=' * 60}\n") + print(agent_log) + if gateway_log: + print(f"\n\n{'=' * 60}") + print("FULL gateway.log") + print(f"{'=' * 60}\n") + print(gateway_log) + return + + print("Uploading...") + urls: dict[str, str] = {} + failures: list[str] = [] + + # 1. Summary report (required) + try: + urls["Report"] = upload_to_pastebin(report, expiry_days=expiry) + except RuntimeError as exc: + print(f"\nUpload failed: {exc}", file=sys.stderr) + print("\nFull report printed below — copy-paste it manually:\n") + print(report) + sys.exit(1) + + # 2. Full agent.log (optional) + if agent_log: + try: + urls["agent.log"] = upload_to_pastebin(agent_log, expiry_days=expiry) + except Exception as exc: + failures.append(f"agent.log: {exc}") + + # 3. Full gateway.log (optional) + if gateway_log: + try: + urls["gateway.log"] = upload_to_pastebin(gateway_log, expiry_days=expiry) + except Exception as exc: + failures.append(f"gateway.log: {exc}") + + # Print results + label_width = max(len(k) for k in urls) + print(f"\nDebug report uploaded:") + for label, url in urls.items(): + print(f" {label:<{label_width}} {url}") + + if failures: + print(f"\n (failed to upload: {', '.join(failures)})") + + print(f"\nShare these links with the Hermes team for support.") + + +def run_debug(args): + """Route debug subcommands.""" + subcmd = getattr(args, "debug_command", None) + if subcmd == "share": + run_debug_share(args) + else: + # Default: show help + print("Usage: hermes debug share [--lines N] [--expire N] [--local]") + print() + print("Commands:") + print(" share Upload debug report to a paste service and print URL") + print() + print("Options:") + print(" --lines N Number of log lines to include (default: 200)") + print(" --expire N Paste expiry in days (default: 7)") + print(" --local Print report locally instead of uploading") diff --git a/mindcli/_vendor/hermes_cli/default_soul.py b/mindcli/_vendor/hermes_cli/default_soul.py new file mode 100644 index 0000000..9deee6d --- /dev/null +++ b/mindcli/_vendor/hermes_cli/default_soul.py @@ -0,0 +1,11 @@ +"""Default SOUL.md template seeded into HERMES_HOME on first run.""" + +DEFAULT_SOUL_MD = ( + "You are MindOS NEXT, an intelligent AI Workstation. " + "You are helpful, knowledgeable, and direct. You assist users with a wide " + "range of tasks including answering questions, writing and editing code, " + "analyzing information, creative work, and executing actions via your tools. " + "You communicate clearly, admit uncertainty when appropriate, and prioritize " + "being genuinely useful over being verbose unless otherwise directed below. " + "Be targeted and efficient in your exploration and investigations." +) diff --git a/mindcli/_vendor/hermes_cli/doctor.py b/mindcli/_vendor/hermes_cli/doctor.py new file mode 100644 index 0000000..34a57aa --- /dev/null +++ b/mindcli/_vendor/hermes_cli/doctor.py @@ -0,0 +1,1023 @@ +""" +Doctor command for hermes CLI. + +Diagnoses issues with Hermes Agent setup. +""" + +import os +import sys +import subprocess +import shutil + +from hermes_cli.config import get_project_root, get_hermes_home, get_env_path +from hermes_constants import display_hermes_home + +PROJECT_ROOT = get_project_root() +HERMES_HOME = get_hermes_home() +_DHH = display_hermes_home() # user-facing display path (e.g. ~/.hermes or ~/.hermes/profiles/coder) + +# Load environment variables from ~/.hermes/.env so API key checks work +from dotenv import load_dotenv +_env_path = get_env_path() +if _env_path.exists(): + try: + load_dotenv(_env_path, encoding="utf-8") + except UnicodeDecodeError: + load_dotenv(_env_path, encoding="latin-1") +# Also try project .env as dev fallback +load_dotenv(PROJECT_ROOT / ".env", override=False, encoding="utf-8") + +from hermes_cli.colors import Colors, color +from hermes_constants import OPENROUTER_MODELS_URL + + +_PROVIDER_ENV_HINTS = ( + "OPENROUTER_API_KEY", + "OPENAI_API_KEY", + "ANTHROPIC_API_KEY", + "ANTHROPIC_TOKEN", + "OPENAI_BASE_URL", + "NOUS_API_KEY", + "GLM_API_KEY", + "ZAI_API_KEY", + "Z_AI_API_KEY", + "KIMI_API_KEY", + "MINIMAX_API_KEY", + "MINIMAX_CN_API_KEY", + "KILOCODE_API_KEY", + "DEEPSEEK_API_KEY", + "DASHSCOPE_API_KEY", + "HF_TOKEN", + "AI_GATEWAY_API_KEY", + "OPENCODE_ZEN_API_KEY", + "OPENCODE_GO_API_KEY", + "XIAOMI_API_KEY", +) + + +from hermes_constants import is_termux as _is_termux + + +def _python_install_cmd() -> str: + return "python -m pip install" if _is_termux() else "uv pip install" + + +def _system_package_install_cmd(pkg: str) -> str: + if _is_termux(): + return f"pkg install {pkg}" + if sys.platform == "darwin": + return f"brew install {pkg}" + return f"sudo apt install {pkg}" + + +def _termux_browser_setup_steps(node_installed: bool) -> list[str]: + steps: list[str] = [] + step = 1 + if not node_installed: + steps.append(f"{step}) pkg install nodejs") + step += 1 + steps.append(f"{step}) npm install -g agent-browser") + steps.append(f"{step + 1}) agent-browser install") + return steps + + +def _has_provider_env_config(content: str) -> bool: + """Return True when ~/.hermes/.env contains provider auth/base URL settings.""" + return any(key in content for key in _PROVIDER_ENV_HINTS) + + +def _honcho_is_configured_for_doctor() -> bool: + """Return True when Honcho is configured, even if this process has no active session.""" + try: + from plugins.memory.honcho.client import HonchoClientConfig + + cfg = HonchoClientConfig.from_global_config() + return bool(cfg.enabled and (cfg.api_key or cfg.base_url)) + except Exception: + return False + + +def _apply_doctor_tool_availability_overrides(available: list[str], unavailable: list[dict]) -> tuple[list[str], list[dict]]: + """Adjust runtime-gated tool availability for doctor diagnostics.""" + if not _honcho_is_configured_for_doctor(): + return available, unavailable + + updated_available = list(available) + updated_unavailable = [] + for item in unavailable: + if item.get("name") == "honcho": + if "honcho" not in updated_available: + updated_available.append("honcho") + continue + updated_unavailable.append(item) + return updated_available, updated_unavailable + + +def check_ok(text: str, detail: str = ""): + print(f" {color('✓', Colors.GREEN)} {text}" + (f" {color(detail, Colors.DIM)}" if detail else "")) + +def check_warn(text: str, detail: str = ""): + print(f" {color('⚠', Colors.YELLOW)} {text}" + (f" {color(detail, Colors.DIM)}" if detail else "")) + +def check_fail(text: str, detail: str = ""): + print(f" {color('✗', Colors.RED)} {text}" + (f" {color(detail, Colors.DIM)}" if detail else "")) + +def check_info(text: str): + print(f" {color('→', Colors.CYAN)} {text}") + + +def _check_gateway_service_linger(issues: list[str]) -> None: + """Warn when a systemd user gateway service will stop after logout.""" + try: + from hermes_cli.gateway import ( + get_systemd_linger_status, + get_systemd_unit_path, + is_linux, + ) + except Exception as e: + check_warn("Gateway service linger", f"(could not import gateway helpers: {e})") + return + + if not is_linux(): + return + + unit_path = get_systemd_unit_path() + if not unit_path.exists(): + return + + print() + print(color("◆ Gateway Service", Colors.CYAN, Colors.BOLD)) + + linger_enabled, linger_detail = get_systemd_linger_status() + if linger_enabled is True: + check_ok("Systemd linger enabled", "(gateway service survives logout)") + elif linger_enabled is False: + check_warn("Systemd linger disabled", "(gateway may stop after logout)") + check_info("Run: sudo loginctl enable-linger $USER") + issues.append("Enable linger for the gateway user service: sudo loginctl enable-linger $USER") + else: + check_warn("Could not verify systemd linger", f"({linger_detail})") + + +def run_doctor(args): + """Run diagnostic checks.""" + should_fix = getattr(args, 'fix', False) + + # Doctor runs from the interactive CLI, so CLI-gated tool availability + # checks (like cronjob management) should see the same context as `hermes`. + os.environ.setdefault("HERMES_INTERACTIVE", "1") + + issues = [] + manual_issues = [] # issues that can't be auto-fixed + fixed_count = 0 + + print() + print(color("┌─────────────────────────────────────────────────────────┐", Colors.CYAN)) + print(color("│ 🩺 Hermes Doctor │", Colors.CYAN)) + print(color("└─────────────────────────────────────────────────────────┘", Colors.CYAN)) + + # ========================================================================= + # Check: Python version + # ========================================================================= + print() + print(color("◆ Python Environment", Colors.CYAN, Colors.BOLD)) + + py_version = sys.version_info + if py_version >= (3, 11): + check_ok(f"Python {py_version.major}.{py_version.minor}.{py_version.micro}") + elif py_version >= (3, 10): + check_ok(f"Python {py_version.major}.{py_version.minor}.{py_version.micro}") + check_warn("Python 3.11+ recommended for RL Training tools (tinker requires >= 3.11)") + elif py_version >= (3, 8): + check_warn(f"Python {py_version.major}.{py_version.minor}.{py_version.micro}", "(3.10+ recommended)") + else: + check_fail(f"Python {py_version.major}.{py_version.minor}.{py_version.micro}", "(3.10+ required)") + issues.append("Upgrade Python to 3.10+") + + # Check if in virtual environment + in_venv = sys.prefix != sys.base_prefix + if in_venv: + check_ok("Virtual environment active") + else: + check_warn("Not in virtual environment", "(recommended)") + + # ========================================================================= + # Check: Required packages + # ========================================================================= + print() + print(color("◆ Required Packages", Colors.CYAN, Colors.BOLD)) + + required_packages = [ + ("openai", "OpenAI SDK"), + ("rich", "Rich (terminal UI)"), + ("dotenv", "python-dotenv"), + ("yaml", "PyYAML"), + ("httpx", "HTTPX"), + ] + + optional_packages = [ + ("croniter", "Croniter (cron expressions)"), + ("telegram", "python-telegram-bot"), + ("discord", "discord.py"), + ] + + for module, name in required_packages: + try: + __import__(module) + check_ok(name) + except ImportError: + check_fail(name, "(missing)") + issues.append(f"Install {name}: {_python_install_cmd()} {module}") + + for module, name in optional_packages: + try: + __import__(module) + check_ok(name, "(optional)") + except ImportError: + check_warn(name, "(optional, not installed)") + + # ========================================================================= + # Check: Configuration files + # ========================================================================= + print() + print(color("◆ Configuration Files", Colors.CYAN, Colors.BOLD)) + + # Check ~/.hermes/.env (primary location for user config) + env_path = HERMES_HOME / '.env' + if env_path.exists(): + check_ok(f"{_DHH}/.env file exists") + + # Check for common issues + content = env_path.read_text() + if _has_provider_env_config(content): + check_ok("API key or custom endpoint configured") + else: + check_warn(f"No API key found in {_DHH}/.env") + issues.append("Run 'hermes setup' to configure API keys") + else: + # Also check project root as fallback + fallback_env = PROJECT_ROOT / '.env' + if fallback_env.exists(): + check_ok(".env file exists (in project directory)") + else: + check_fail(f"{_DHH}/.env file missing") + if should_fix: + env_path.parent.mkdir(parents=True, exist_ok=True) + env_path.touch() + check_ok(f"Created empty {_DHH}/.env") + check_info("Run 'hermes setup' to configure API keys") + fixed_count += 1 + else: + check_info("Run 'hermes setup' to create one") + issues.append("Run 'hermes setup' to create .env") + + # Check ~/.hermes/config.yaml (primary) or project cli-config.yaml (fallback) + config_path = HERMES_HOME / 'config.yaml' + if config_path.exists(): + check_ok(f"{_DHH}/config.yaml exists") + else: + fallback_config = PROJECT_ROOT / 'cli-config.yaml' + if fallback_config.exists(): + check_ok("cli-config.yaml exists (in project directory)") + else: + example_config = PROJECT_ROOT / 'cli-config.yaml.example' + if should_fix and example_config.exists(): + config_path.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(str(example_config), str(config_path)) + check_ok(f"Created {_DHH}/config.yaml from cli-config.yaml.example") + fixed_count += 1 + elif should_fix: + check_warn("config.yaml not found and no example to copy from") + manual_issues.append(f"Create {_DHH}/config.yaml manually") + else: + check_warn("config.yaml not found", "(using defaults)") + + # Check config version and stale keys + config_path = HERMES_HOME / 'config.yaml' + if config_path.exists(): + try: + from hermes_cli.config import check_config_version, migrate_config + current_ver, latest_ver = check_config_version() + if current_ver < latest_ver: + check_warn( + f"Config version outdated (v{current_ver} → v{latest_ver})", + "(new settings available)" + ) + if should_fix: + try: + migrate_config(interactive=False, quiet=False) + check_ok("Config migrated to latest version") + fixed_count += 1 + except Exception as mig_err: + check_warn(f"Auto-migration failed: {mig_err}") + issues.append("Run 'hermes setup' to migrate config") + else: + issues.append("Run 'hermes doctor --fix' or 'hermes setup' to migrate config") + else: + check_ok(f"Config version up to date (v{current_ver})") + except Exception: + pass + + # Detect stale root-level model keys (known bug source — PR #4329) + try: + import yaml + with open(config_path) as f: + raw_config = yaml.safe_load(f) or {} + stale_root_keys = [k for k in ("provider", "base_url") if k in raw_config and isinstance(raw_config[k], str)] + if stale_root_keys: + check_warn( + f"Stale root-level config keys: {', '.join(stale_root_keys)}", + "(should be under 'model:' section)" + ) + if should_fix: + model_section = raw_config.setdefault("model", {}) + for k in stale_root_keys: + if not model_section.get(k): + model_section[k] = raw_config.pop(k) + else: + raw_config.pop(k) + from utils import atomic_yaml_write + atomic_yaml_write(config_path, raw_config) + check_ok("Migrated stale root-level keys into model section") + fixed_count += 1 + else: + issues.append("Stale root-level provider/base_url in config.yaml — run 'hermes doctor --fix'") + except Exception: + pass + + # Validate config structure (catches malformed custom_providers, etc.) + try: + from hermes_cli.config import validate_config_structure + config_issues = validate_config_structure() + if config_issues: + print() + print(color("◆ Config Structure", Colors.CYAN, Colors.BOLD)) + for ci in config_issues: + if ci.severity == "error": + check_fail(ci.message) + else: + check_warn(ci.message) + # Show the hint indented + for hint_line in ci.hint.splitlines(): + check_info(hint_line) + issues.append(ci.message) + except Exception: + pass + + # ========================================================================= + # Check: Auth providers + # ========================================================================= + print() + print(color("◆ Auth Providers", Colors.CYAN, Colors.BOLD)) + + try: + from hermes_cli.auth import get_nous_auth_status, get_codex_auth_status + + nous_status = get_nous_auth_status() + if nous_status.get("logged_in"): + check_ok("Nous Portal auth", "(logged in)") + else: + check_warn("Nous Portal auth", "(not logged in)") + + codex_status = get_codex_auth_status() + if codex_status.get("logged_in"): + check_ok("OpenAI Codex auth", "(logged in)") + else: + check_warn("OpenAI Codex auth", "(not logged in)") + if codex_status.get("error"): + check_info(codex_status["error"]) + except Exception as e: + check_warn("Auth provider status", f"(could not check: {e})") + + if shutil.which("codex"): + check_ok("codex CLI") + else: + check_warn("codex CLI not found", "(required for openai-codex login)") + + # ========================================================================= + # Check: Directory structure + # ========================================================================= + print() + print(color("◆ Directory Structure", Colors.CYAN, Colors.BOLD)) + + hermes_home = HERMES_HOME + if hermes_home.exists(): + check_ok(f"{_DHH} directory exists") + else: + if should_fix: + hermes_home.mkdir(parents=True, exist_ok=True) + check_ok(f"Created {_DHH} directory") + fixed_count += 1 + else: + check_warn(f"{_DHH} not found", "(will be created on first use)") + + # Check expected subdirectories + expected_subdirs = ["cron", "sessions", "logs", "skills", "memories"] + for subdir_name in expected_subdirs: + subdir_path = hermes_home / subdir_name + if subdir_path.exists(): + check_ok(f"{_DHH}/{subdir_name}/ exists") + else: + if should_fix: + subdir_path.mkdir(parents=True, exist_ok=True) + check_ok(f"Created {_DHH}/{subdir_name}/") + fixed_count += 1 + else: + check_warn(f"{_DHH}/{subdir_name}/ not found", "(will be created on first use)") + + # Check for SOUL.md persona file + soul_path = hermes_home / "SOUL.md" + if soul_path.exists(): + content = soul_path.read_text(encoding="utf-8").strip() + # Check if it's just the template comments (no real content) + lines = [l for l in content.splitlines() if l.strip() and not l.strip().startswith(("", "#"))] + if lines: + check_ok(f"{_DHH}/SOUL.md exists (persona configured)") + else: + check_info(f"{_DHH}/SOUL.md exists but is empty — edit it to customize personality") + else: + check_warn(f"{_DHH}/SOUL.md not found", "(create it to give Hermes a custom personality)") + if should_fix: + soul_path.parent.mkdir(parents=True, exist_ok=True) + soul_path.write_text( + "# Hermes Agent Persona\n\n" + "\n\n" + "You are Hermes, a helpful AI assistant.\n", + encoding="utf-8", + ) + check_ok(f"Created {_DHH}/SOUL.md with basic template") + fixed_count += 1 + + # Check memory directory + memories_dir = hermes_home / "memories" + if memories_dir.exists(): + check_ok(f"{_DHH}/memories/ directory exists") + memory_file = memories_dir / "MEMORY.md" + user_file = memories_dir / "USER.md" + if memory_file.exists(): + size = len(memory_file.read_text(encoding="utf-8").strip()) + check_ok(f"MEMORY.md exists ({size} chars)") + else: + check_info("MEMORY.md not created yet (will be created when the agent first writes a memory)") + if user_file.exists(): + size = len(user_file.read_text(encoding="utf-8").strip()) + check_ok(f"USER.md exists ({size} chars)") + else: + check_info("USER.md not created yet (will be created when the agent first writes a memory)") + else: + check_warn(f"{_DHH}/memories/ not found", "(will be created on first use)") + if should_fix: + memories_dir.mkdir(parents=True, exist_ok=True) + check_ok(f"Created {_DHH}/memories/") + fixed_count += 1 + + # Check SQLite session store + state_db_path = hermes_home / "state.db" + if state_db_path.exists(): + try: + import sqlite3 + conn = sqlite3.connect(str(state_db_path)) + cursor = conn.execute("SELECT COUNT(*) FROM sessions") + count = cursor.fetchone()[0] + conn.close() + check_ok(f"{_DHH}/state.db exists ({count} sessions)") + except Exception as e: + check_warn(f"{_DHH}/state.db exists but has issues: {e}") + else: + check_info(f"{_DHH}/state.db not created yet (will be created on first session)") + + # Check WAL file size (unbounded growth indicates missed checkpoints) + wal_path = hermes_home / "state.db-wal" + if wal_path.exists(): + try: + wal_size = wal_path.stat().st_size + if wal_size > 50 * 1024 * 1024: # 50 MB + check_warn( + f"WAL file is large ({wal_size // (1024*1024)} MB)", + "(may indicate missed checkpoints)" + ) + if should_fix: + import sqlite3 + conn = sqlite3.connect(str(state_db_path)) + conn.execute("PRAGMA wal_checkpoint(PASSIVE)") + conn.close() + new_size = wal_path.stat().st_size if wal_path.exists() else 0 + check_ok(f"WAL checkpoint performed ({wal_size // 1024}K → {new_size // 1024}K)") + fixed_count += 1 + else: + issues.append("Large WAL file — run 'hermes doctor --fix' to checkpoint") + elif wal_size > 10 * 1024 * 1024: # 10 MB + check_info(f"WAL file is {wal_size // (1024*1024)} MB (normal for active sessions)") + except Exception: + pass + + _check_gateway_service_linger(issues) + + # ========================================================================= + # Check: External tools + # ========================================================================= + print() + print(color("◆ External Tools", Colors.CYAN, Colors.BOLD)) + + # Git + if shutil.which("git"): + check_ok("git") + else: + check_warn("git not found", "(optional)") + + # ripgrep (optional, for faster file search) + if shutil.which("rg"): + check_ok("ripgrep (rg)", "(faster file search)") + else: + check_warn("ripgrep (rg) not found", "(file search uses grep fallback)") + check_info(f"Install for faster search: {_system_package_install_cmd('ripgrep')}") + + # Docker (optional) + terminal_env = os.getenv("TERMINAL_ENV", "local") + if terminal_env == "docker": + if shutil.which("docker"): + # Check if docker daemon is running + try: + result = subprocess.run(["docker", "info"], capture_output=True, timeout=10) + except subprocess.TimeoutExpired: + result = None + if result is not None and result.returncode == 0: + check_ok("docker", "(daemon running)") + else: + check_fail("docker daemon not running") + issues.append("Start Docker daemon") + else: + check_fail("docker not found", "(required for TERMINAL_ENV=docker)") + issues.append("Install Docker or change TERMINAL_ENV") + else: + if shutil.which("docker"): + check_ok("docker", "(optional)") + else: + if _is_termux(): + check_info("Docker backend is not available inside Termux (expected on Android)") + else: + check_warn("docker not found", "(optional)") + + # SSH (if using ssh backend) + if terminal_env == "ssh": + ssh_host = os.getenv("TERMINAL_SSH_HOST") + if ssh_host: + # Try to connect + try: + result = subprocess.run( + ["ssh", "-o", "ConnectTimeout=5", "-o", "BatchMode=yes", ssh_host, "echo ok"], + capture_output=True, + text=True, + timeout=15 + ) + except subprocess.TimeoutExpired: + result = None + if result is not None and result.returncode == 0: + check_ok(f"SSH connection to {ssh_host}") + else: + check_fail(f"SSH connection to {ssh_host}") + issues.append(f"Check SSH configuration for {ssh_host}") + else: + check_fail("TERMINAL_SSH_HOST not set", "(required for TERMINAL_ENV=ssh)") + issues.append("Set TERMINAL_SSH_HOST in .env") + + # Daytona (if using daytona backend) + if terminal_env == "daytona": + daytona_key = os.getenv("DAYTONA_API_KEY") + if daytona_key: + check_ok("Daytona API key", "(configured)") + else: + check_fail("DAYTONA_API_KEY not set", "(required for TERMINAL_ENV=daytona)") + issues.append("Set DAYTONA_API_KEY environment variable") + try: + from daytona import Daytona # noqa: F401 — SDK presence check + check_ok("daytona SDK", "(installed)") + except ImportError: + check_fail("daytona SDK not installed", "(pip install daytona)") + issues.append("Install daytona SDK: pip install daytona") + + # Node.js + agent-browser (for browser automation tools) + if shutil.which("node"): + check_ok("Node.js") + # Check if agent-browser is installed + agent_browser_path = PROJECT_ROOT / "node_modules" / "agent-browser" + if agent_browser_path.exists(): + check_ok("agent-browser (Node.js)", "(browser automation)") + else: + if _is_termux(): + check_info("agent-browser is not installed (expected in the tested Termux path)") + check_info("Install it manually later with: npm install -g agent-browser && agent-browser install") + check_info("Termux browser setup:") + for step in _termux_browser_setup_steps(node_installed=True): + check_info(step) + else: + check_warn("agent-browser not installed", "(run: npm install)") + else: + if _is_termux(): + check_info("Node.js not found (browser tools are optional in the tested Termux path)") + check_info("Install Node.js on Termux with: pkg install nodejs") + check_info("Termux browser setup:") + for step in _termux_browser_setup_steps(node_installed=False): + check_info(step) + else: + check_warn("Node.js not found", "(optional, needed for browser tools)") + + # npm audit for all Node.js packages + if shutil.which("npm"): + npm_dirs = [ + (PROJECT_ROOT, "Browser tools (agent-browser)"), + (PROJECT_ROOT / "scripts" / "whatsapp-bridge", "WhatsApp bridge"), + ] + for npm_dir, label in npm_dirs: + if not (npm_dir / "node_modules").exists(): + continue + try: + audit_result = subprocess.run( + ["npm", "audit", "--json"], + cwd=str(npm_dir), + capture_output=True, text=True, timeout=30, + ) + import json as _json + audit_data = _json.loads(audit_result.stdout) if audit_result.stdout.strip() else {} + vuln_count = audit_data.get("metadata", {}).get("vulnerabilities", {}) + critical = vuln_count.get("critical", 0) + high = vuln_count.get("high", 0) + moderate = vuln_count.get("moderate", 0) + total = critical + high + moderate + if total == 0: + check_ok(f"{label} deps", "(no known vulnerabilities)") + elif critical > 0 or high > 0: + check_warn( + f"{label} deps", + f"({critical} critical, {high} high, {moderate} moderate — run: cd {npm_dir} && npm audit fix)" + ) + issues.append(f"{label} has {total} npm vulnerability(ies)") + else: + check_ok(f"{label} deps", f"({moderate} moderate vulnerability(ies))") + except Exception: + pass + + # ========================================================================= + # Check: API connectivity + # ========================================================================= + print() + print(color("◆ API Connectivity", Colors.CYAN, Colors.BOLD)) + + openrouter_key = os.getenv("OPENROUTER_API_KEY") + if openrouter_key: + print(" Checking OpenRouter API...", end="", flush=True) + try: + import httpx + response = httpx.get( + OPENROUTER_MODELS_URL, + headers={"Authorization": f"Bearer {openrouter_key}"}, + timeout=10 + ) + if response.status_code == 200: + print(f"\r {color('✓', Colors.GREEN)} OpenRouter API ") + elif response.status_code == 401: + print(f"\r {color('✗', Colors.RED)} OpenRouter API {color('(invalid API key)', Colors.DIM)} ") + issues.append("Check OPENROUTER_API_KEY in .env") + else: + print(f"\r {color('✗', Colors.RED)} OpenRouter API {color(f'(HTTP {response.status_code})', Colors.DIM)} ") + except Exception as e: + print(f"\r {color('✗', Colors.RED)} OpenRouter API {color(f'({e})', Colors.DIM)} ") + issues.append("Check network connectivity") + else: + check_warn("OpenRouter API", "(not configured)") + + from hermes_cli.auth import get_anthropic_key + anthropic_key = get_anthropic_key() + if anthropic_key: + print(" Checking Anthropic API...", end="", flush=True) + try: + import httpx + from agent.anthropic_adapter import _is_oauth_token, _COMMON_BETAS, _OAUTH_ONLY_BETAS + + headers = {"anthropic-version": "2023-06-01"} + if _is_oauth_token(anthropic_key): + headers["Authorization"] = f"Bearer {anthropic_key}" + headers["anthropic-beta"] = ",".join(_COMMON_BETAS + _OAUTH_ONLY_BETAS) + else: + headers["x-api-key"] = anthropic_key + response = httpx.get( + "https://api.anthropic.com/v1/models", + headers=headers, + timeout=10 + ) + if response.status_code == 200: + print(f"\r {color('✓', Colors.GREEN)} Anthropic API ") + elif response.status_code == 401: + print(f"\r {color('✗', Colors.RED)} Anthropic API {color('(invalid API key)', Colors.DIM)} ") + else: + msg = "(couldn't verify)" + print(f"\r {color('⚠', Colors.YELLOW)} Anthropic API {color(msg, Colors.DIM)} ") + except Exception as e: + print(f"\r {color('⚠', Colors.YELLOW)} Anthropic API {color(f'({e})', Colors.DIM)} ") + + # -- API-key providers -- + # Tuple: (name, env_vars, default_url, base_env, supports_models_endpoint) + # If supports_models_endpoint is False, we skip the health check and just show "configured" + _apikey_providers = [ + ("Z.AI / GLM", ("GLM_API_KEY", "ZAI_API_KEY", "Z_AI_API_KEY"), "https://api.z.ai/api/paas/v4/models", "GLM_BASE_URL", True), + ("Kimi / Moonshot", ("KIMI_API_KEY",), "https://api.moonshot.ai/v1/models", "KIMI_BASE_URL", True), + ("Kimi / Moonshot (China)", ("KIMI_CN_API_KEY",), "https://api.moonshot.cn/v1/models", None, True), + ("Arcee AI", ("ARCEEAI_API_KEY",), "https://api.arcee.ai/api/v1/models", "ARCEE_BASE_URL", True), + ("DeepSeek", ("DEEPSEEK_API_KEY",), "https://api.deepseek.com/v1/models", "DEEPSEEK_BASE_URL", True), + ("Hugging Face", ("HF_TOKEN",), "https://router.huggingface.co/v1/models", "HF_BASE_URL", True), + ("Alibaba/DashScope", ("DASHSCOPE_API_KEY",), "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/models", "DASHSCOPE_BASE_URL", True), + # MiniMax: the /anthropic endpoint doesn't support /models, but the /v1 endpoint does. + ("MiniMax", ("MINIMAX_API_KEY",), "https://api.minimax.io/v1/models", "MINIMAX_BASE_URL", True), + ("MiniMax (China)", ("MINIMAX_CN_API_KEY",), "https://api.minimaxi.com/v1/models", "MINIMAX_CN_BASE_URL", True), + ("Vercel AI Gateway", ("AI_GATEWAY_API_KEY",), "https://ai-gateway.vercel.sh/v1/models", "AI_GATEWAY_BASE_URL", True), + ("Kilo Code", ("KILOCODE_API_KEY",), "https://api.kilo.ai/api/gateway/models", "KILOCODE_BASE_URL", True), + ("OpenCode Zen", ("OPENCODE_ZEN_API_KEY",), "https://opencode.ai/zen/v1/models", "OPENCODE_ZEN_BASE_URL", True), + ("OpenCode Go", ("OPENCODE_GO_API_KEY",), "https://opencode.ai/zen/go/v1/models", "OPENCODE_GO_BASE_URL", True), + ] + for _pname, _env_vars, _default_url, _base_env, _supports_health_check in _apikey_providers: + _key = "" + for _ev in _env_vars: + _key = os.getenv(_ev, "") + if _key: + break + if _key: + _label = _pname.ljust(20) + # Some providers (like MiniMax) don't support /models endpoint + if not _supports_health_check: + print(f" {color('✓', Colors.GREEN)} {_label} {color('(key configured)', Colors.DIM)}") + continue + print(f" Checking {_pname} API...", end="", flush=True) + try: + import httpx + _base = os.getenv(_base_env, "") + # Auto-detect Kimi Code keys (sk-kimi-) → api.kimi.com + if not _base and _key.startswith("sk-kimi-"): + _base = "https://api.kimi.com/coding/v1" + # Anthropic-compat endpoints (/anthropic) don't support /models. + # Rewrite to the OpenAI-compat /v1 surface for health checks. + if _base and _base.rstrip("/").endswith("/anthropic"): + from agent.auxiliary_client import _to_openai_base_url + _base = _to_openai_base_url(_base) + _url = (_base.rstrip("/") + "/models") if _base else _default_url + _headers = {"Authorization": f"Bearer {_key}"} + if "api.kimi.com" in _url.lower(): + _headers["User-Agent"] = "KimiCLI/1.30.0" + _resp = httpx.get( + _url, + headers=_headers, + timeout=10, + ) + if _resp.status_code == 200: + print(f"\r {color('✓', Colors.GREEN)} {_label} ") + elif _resp.status_code == 401: + print(f"\r {color('✗', Colors.RED)} {_label} {color('(invalid API key)', Colors.DIM)} ") + issues.append(f"Check {_env_vars[0]} in .env") + else: + print(f"\r {color('⚠', Colors.YELLOW)} {_label} {color(f'(HTTP {_resp.status_code})', Colors.DIM)} ") + except Exception as _e: + print(f"\r {color('⚠', Colors.YELLOW)} {_label} {color(f'({_e})', Colors.DIM)} ") + + # ========================================================================= + # Check: Submodules + # ========================================================================= + print() + print(color("◆ Submodules", Colors.CYAN, Colors.BOLD)) + + # tinker-atropos (RL training backend) + tinker_dir = PROJECT_ROOT / "tinker-atropos" + if tinker_dir.exists() and (tinker_dir / "pyproject.toml").exists(): + if py_version >= (3, 11): + try: + __import__("tinker_atropos") + check_ok("tinker-atropos", "(RL training backend)") + except ImportError: + install_cmd = f"{_python_install_cmd()} -e ./tinker-atropos" + check_warn("tinker-atropos found but not installed", f"(run: {install_cmd})") + issues.append(f"Install tinker-atropos: {install_cmd}") + else: + check_warn("tinker-atropos requires Python 3.11+", f"(current: {py_version.major}.{py_version.minor})") + else: + check_warn("tinker-atropos not found", "(run: git submodule update --init --recursive)") + + # ========================================================================= + # Check: Tool Availability + # ========================================================================= + print() + print(color("◆ Tool Availability", Colors.CYAN, Colors.BOLD)) + + try: + # Add project root to path for imports + sys.path.insert(0, str(PROJECT_ROOT)) + from model_tools import check_tool_availability, TOOLSET_REQUIREMENTS + + available, unavailable = check_tool_availability() + available, unavailable = _apply_doctor_tool_availability_overrides(available, unavailable) + + for tid in available: + info = TOOLSET_REQUIREMENTS.get(tid, {}) + check_ok(info.get("name", tid)) + + for item in unavailable: + env_vars = item.get("missing_vars") or item.get("env_vars") or [] + if env_vars: + vars_str = ", ".join(env_vars) + check_warn(item["name"], f"(missing {vars_str})") + else: + check_warn(item["name"], "(system dependency not met)") + + # Count disabled tools with API key requirements + api_disabled = [u for u in unavailable if (u.get("missing_vars") or u.get("env_vars"))] + if api_disabled: + issues.append("Run 'hermes setup' to configure missing API keys for full tool access") + except Exception as e: + check_warn("Could not check tool availability", f"({e})") + + # ========================================================================= + # Check: Skills Hub + # ========================================================================= + print() + print(color("◆ Skills Hub", Colors.CYAN, Colors.BOLD)) + + hub_dir = HERMES_HOME / "skills" / ".hub" + if hub_dir.exists(): + check_ok("Skills Hub directory exists") + lock_file = hub_dir / "lock.json" + if lock_file.exists(): + try: + import json + lock_data = json.loads(lock_file.read_text()) + count = len(lock_data.get("installed", {})) + check_ok(f"Lock file OK ({count} hub-installed skill(s))") + except Exception: + check_warn("Lock file", "(corrupted or unreadable)") + quarantine = hub_dir / "quarantine" + q_count = sum(1 for d in quarantine.iterdir() if d.is_dir()) if quarantine.exists() else 0 + if q_count > 0: + check_warn(f"{q_count} skill(s) in quarantine", "(pending review)") + else: + check_warn("Skills Hub directory not initialized", "(run: hermes skills list)") + + from hermes_cli.config import get_env_value + github_token = get_env_value("GITHUB_TOKEN") or get_env_value("GH_TOKEN") + if github_token: + check_ok("GitHub token configured (authenticated API access)") + else: + check_warn("No GITHUB_TOKEN", f"(60 req/hr rate limit — set in {_DHH}/.env for better rates)") + + # ========================================================================= + # Memory Provider (only check the active provider, if any) + # ========================================================================= + print() + print(color("◆ Memory Provider", Colors.CYAN, Colors.BOLD)) + + _active_memory_provider = "" + try: + import yaml as _yaml + _mem_cfg_path = HERMES_HOME / "config.yaml" + if _mem_cfg_path.exists(): + with open(_mem_cfg_path) as _f: + _raw_cfg = _yaml.safe_load(_f) or {} + _active_memory_provider = (_raw_cfg.get("memory") or {}).get("provider", "") + except Exception: + pass + + if not _active_memory_provider: + check_ok("Built-in memory active", "(no external provider configured — this is fine)") + elif _active_memory_provider == "honcho": + try: + from plugins.memory.honcho.client import HonchoClientConfig, resolve_config_path + hcfg = HonchoClientConfig.from_global_config() + _honcho_cfg_path = resolve_config_path() + + if not _honcho_cfg_path.exists(): + check_warn("Honcho config not found", "run: hermes memory setup") + elif not hcfg.enabled: + check_info(f"Honcho disabled (set enabled: true in {_honcho_cfg_path} to activate)") + elif not (hcfg.api_key or hcfg.base_url): + check_fail("Honcho API key or base URL not set", "run: hermes memory setup") + issues.append("No Honcho API key — run 'hermes memory setup'") + else: + from plugins.memory.honcho.client import get_honcho_client, reset_honcho_client + reset_honcho_client() + try: + get_honcho_client(hcfg) + check_ok( + "Honcho connected", + f"workspace={hcfg.workspace_id} mode={hcfg.recall_mode} freq={hcfg.write_frequency}", + ) + except Exception as _e: + check_fail("Honcho connection failed", str(_e)) + issues.append(f"Honcho unreachable: {_e}") + except ImportError: + check_fail("honcho-ai not installed", "pip install honcho-ai") + issues.append("Honcho is set as memory provider but honcho-ai is not installed") + except Exception as _e: + check_warn("Honcho check failed", str(_e)) + elif _active_memory_provider == "mem0": + try: + from plugins.memory.mem0 import _load_config as _load_mem0_config + mem0_cfg = _load_mem0_config() + mem0_key = mem0_cfg.get("api_key", "") + if mem0_key: + check_ok("Mem0 API key configured") + check_info(f"user_id={mem0_cfg.get('user_id', '?')} agent_id={mem0_cfg.get('agent_id', '?')}") + else: + check_fail("Mem0 API key not set", "(set MEM0_API_KEY in .env or run hermes memory setup)") + issues.append("Mem0 is set as memory provider but API key is missing") + except ImportError: + check_fail("Mem0 plugin not loadable", "pip install mem0ai") + issues.append("Mem0 is set as memory provider but mem0ai is not installed") + except Exception as _e: + check_warn("Mem0 check failed", str(_e)) + else: + # Generic check for other memory providers (openviking, hindsight, etc.) + try: + from plugins.memory import load_memory_provider + _provider = load_memory_provider(_active_memory_provider) + if _provider and _provider.is_available(): + check_ok(f"{_active_memory_provider} provider active") + elif _provider: + check_warn(f"{_active_memory_provider} configured but not available", "run: hermes memory status") + else: + check_warn(f"{_active_memory_provider} plugin not found", "run: hermes memory setup") + except Exception as _e: + check_warn(f"{_active_memory_provider} check failed", str(_e)) + + # ========================================================================= + # Profiles + # ========================================================================= + try: + from hermes_cli.profiles import list_profiles, _get_wrapper_dir, profile_exists + import re as _re + + named_profiles = [p for p in list_profiles() if not p.is_default] + if named_profiles: + print() + print(color("◆ Profiles", Colors.CYAN, Colors.BOLD)) + check_ok(f"{len(named_profiles)} profile(s) found") + wrapper_dir = _get_wrapper_dir() + for p in named_profiles: + parts = [] + if p.gateway_running: + parts.append("gateway running") + if p.model: + parts.append(p.model[:30]) + if not (p.path / "config.yaml").exists(): + parts.append("⚠ missing config") + if not (p.path / ".env").exists(): + parts.append("no .env") + wrapper = wrapper_dir / p.name + if not wrapper.exists(): + parts.append("no alias") + status = ", ".join(parts) if parts else "configured" + check_ok(f" {p.name}: {status}") + + # Check for orphan wrappers + if wrapper_dir.is_dir(): + for wrapper in wrapper_dir.iterdir(): + if not wrapper.is_file(): + continue + try: + content = wrapper.read_text() + if "hermes -p" in content: + _m = _re.search(r"hermes -p (\S+)", content) + if _m and not profile_exists(_m.group(1)): + check_warn(f"Orphan alias: {wrapper.name} → profile '{_m.group(1)}' no longer exists") + except Exception: + pass + except ImportError: + pass + except Exception: + pass + + # ========================================================================= + # Summary + # ========================================================================= + print() + remaining_issues = issues + manual_issues + if should_fix and fixed_count > 0: + print(color("─" * 60, Colors.GREEN)) + print(color(f" Fixed {fixed_count} issue(s).", Colors.GREEN, Colors.BOLD), end="") + if remaining_issues: + print(color(f" {len(remaining_issues)} issue(s) require manual intervention.", Colors.YELLOW, Colors.BOLD)) + else: + print() + print() + if remaining_issues: + for i, issue in enumerate(remaining_issues, 1): + print(f" {i}. {issue}") + print() + elif remaining_issues: + print(color("─" * 60, Colors.YELLOW)) + print(color(f" Found {len(remaining_issues)} issue(s) to address:", Colors.YELLOW, Colors.BOLD)) + print() + for i, issue in enumerate(remaining_issues, 1): + print(f" {i}. {issue}") + print() + if not should_fix: + print(color(" Tip: run 'hermes doctor --fix' to auto-fix what's possible.", Colors.DIM)) + else: + print(color("─" * 60, Colors.GREEN)) + print(color(" All checks passed! 🎉", Colors.GREEN, Colors.BOLD)) + + print() diff --git a/mindcli/_vendor/hermes_cli/dump.py b/mindcli/_vendor/hermes_cli/dump.py new file mode 100644 index 0000000..a520790 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/dump.py @@ -0,0 +1,345 @@ +""" +Dump command for hermes CLI. + +Outputs a compact, plain-text summary of the user's Hermes setup +that can be copy-pasted into Discord/GitHub/Telegram for support context. +No ANSI colors, no checkmarks — just data. +""" + +import json +import os +import platform +import subprocess +import sys +from pathlib import Path + +from hermes_cli.config import get_hermes_home, get_env_path, get_project_root, load_config +from hermes_constants import display_hermes_home + + +def _get_git_commit(project_root: Path) -> str: + """Return short git commit hash, or '(unknown)'.""" + try: + result = subprocess.run( + ["git", "rev-parse", "--short=8", "HEAD"], + capture_output=True, text=True, timeout=5, + cwd=str(project_root), + ) + if result.returncode == 0: + return result.stdout.strip() + except Exception: + pass + return "(unknown)" + + +def _redact(value: str) -> str: + """Redact all but first 4 and last 4 chars.""" + if not value: + return "" + if len(value) < 12: + return "***" + return value[:4] + "..." + value[-4:] + + +def _gateway_status() -> str: + """Return a short gateway status string.""" + if sys.platform.startswith("linux"): + from hermes_constants import is_container + if is_container(): + try: + from hermes_cli.gateway import find_gateway_pids + pids = find_gateway_pids() + if pids: + return f"running (docker, pid {pids[0]})" + return "stopped (docker)" + except Exception: + return "stopped (docker)" + try: + from hermes_cli.gateway import get_service_name + svc = get_service_name() + except Exception: + svc = "hermes-gateway" + try: + r = subprocess.run( + ["systemctl", "--user", "is-active", svc], + capture_output=True, text=True, timeout=5, + ) + return "running (systemd)" if r.stdout.strip() == "active" else "stopped" + except Exception: + return "unknown" + elif sys.platform == "darwin": + try: + from hermes_cli.gateway import get_launchd_label + r = subprocess.run( + ["launchctl", "list", get_launchd_label()], + capture_output=True, text=True, timeout=5, + ) + return "loaded (launchd)" if r.returncode == 0 else "not loaded" + except Exception: + return "unknown" + return "N/A" + + +def _count_skills(hermes_home: Path) -> int: + """Count installed skills.""" + skills_dir = hermes_home / "skills" + if not skills_dir.is_dir(): + return 0 + count = 0 + for item in skills_dir.rglob("SKILL.md"): + count += 1 + return count + + +def _count_mcp_servers(config: dict) -> int: + """Count configured MCP servers.""" + mcp = config.get("mcp", {}) + servers = mcp.get("servers", {}) + return len(servers) + + +def _cron_summary(hermes_home: Path) -> str: + """Return cron jobs summary.""" + jobs_file = hermes_home / "cron" / "jobs.json" + if not jobs_file.exists(): + return "0" + try: + with open(jobs_file, encoding="utf-8") as f: + data = json.load(f) + jobs = data.get("jobs", []) + active = sum(1 for j in jobs if j.get("enabled", True)) + return f"{active} active / {len(jobs)} total" + except Exception: + return "(error reading)" + + +def _configured_platforms() -> list[str]: + """Return list of configured messaging platform names.""" + checks = { + "telegram": "TELEGRAM_BOT_TOKEN", + "discord": "DISCORD_BOT_TOKEN", + "slack": "SLACK_BOT_TOKEN", + "whatsapp": "WHATSAPP_ENABLED", + "signal": "SIGNAL_HTTP_URL", + "email": "EMAIL_ADDRESS", + "sms": "TWILIO_ACCOUNT_SID", + "matrix": "MATRIX_HOMESERVER_URL", + "mattermost": "MATTERMOST_URL", + "homeassistant": "HASS_TOKEN", + "dingtalk": "DINGTALK_CLIENT_ID", + "feishu": "FEISHU_APP_ID", + "wecom": "WECOM_BOT_ID", + "wecom_callback": "WECOM_CALLBACK_CORP_ID", + "weixin": "WEIXIN_ACCOUNT_ID", + "qqbot": "QQ_APP_ID", + } + return [name for name, env in checks.items() if os.getenv(env)] + + +def _memory_provider(config: dict) -> str: + """Return the active memory provider name.""" + mem = config.get("memory", {}) + provider = mem.get("provider", "") + return provider if provider else "built-in" + + +def _get_model_and_provider(config: dict) -> tuple[str, str]: + """Extract model and provider from config.""" + model_cfg = config.get("model", "") + if isinstance(model_cfg, dict): + model = model_cfg.get("default") or model_cfg.get("model") or model_cfg.get("name") or "(not set)" + provider = model_cfg.get("provider") or "(auto)" + elif isinstance(model_cfg, str): + model = model_cfg or "(not set)" + provider = "(auto)" + else: + model = "(not set)" + provider = "(auto)" + return model, provider + + +def _config_overrides(config: dict) -> dict[str, str]: + """Find non-default config values worth reporting. + + Returns a flat dict of dotpath -> value for interesting overrides. + """ + from hermes_cli.config import DEFAULT_CONFIG + + overrides = {} + + # Sections with interesting user-facing overrides + interesting_paths = [ + ("agent", "max_turns"), + ("agent", "gateway_timeout"), + ("agent", "tool_use_enforcement"), + ("terminal", "backend"), + ("terminal", "docker_image"), + ("terminal", "persistent_shell"), + ("browser", "allow_private_urls"), + ("compression", "enabled"), + ("compression", "threshold"), + ("display", "streaming"), + ("display", "skin"), + ("display", "show_reasoning"), + ("smart_model_routing", "enabled"), + ("privacy", "redact_pii"), + ("tts", "provider"), + ] + + for section, key in interesting_paths: + default_section = DEFAULT_CONFIG.get(section, {}) + user_section = config.get(section, {}) + if not isinstance(default_section, dict) or not isinstance(user_section, dict): + continue + default_val = default_section.get(key) + user_val = user_section.get(key) + if user_val is not None and user_val != default_val: + overrides[f"{section}.{key}"] = str(user_val) + + # Toolsets (if different from default) + default_toolsets = DEFAULT_CONFIG.get("toolsets", []) + user_toolsets = config.get("toolsets", []) + if user_toolsets != default_toolsets: + overrides["toolsets"] = str(user_toolsets) + + # Fallback providers + fallbacks = config.get("fallback_providers", []) + if fallbacks: + overrides["fallback_providers"] = str(fallbacks) + + return overrides + + +def run_dump(args): + """Output a compact, copy-pasteable setup summary.""" + show_keys = getattr(args, "show_keys", False) + + # Load env from .env file so key checks work + from dotenv import load_dotenv + env_path = get_env_path() + if env_path.exists(): + try: + load_dotenv(env_path, encoding="utf-8") + except UnicodeDecodeError: + load_dotenv(env_path, encoding="latin-1") + # Also try project .env as dev fallback + load_dotenv(get_project_root() / ".env", override=False, encoding="utf-8") + + project_root = get_project_root() + hermes_home = get_hermes_home() + + try: + from hermes_cli import __version__, __release_date__ + except ImportError: + __version__ = "(unknown)" + __release_date__ = "" + + commit = _get_git_commit(project_root) + + try: + config = load_config() + except Exception: + config = {} + + model, provider = _get_model_and_provider(config) + + # Profile + try: + from hermes_cli.profiles import get_active_profile_name + profile = get_active_profile_name() or "(default)" + except Exception: + profile = "(default)" + + # Terminal backend + terminal_cfg = config.get("terminal", {}) + backend = terminal_cfg.get("backend", "local") + + # OpenAI SDK version + try: + import openai + openai_ver = openai.__version__ + except ImportError: + openai_ver = "not installed" + + # OS info + os_info = f"{platform.system()} {platform.release()} {platform.machine()}" + + lines = [] + lines.append("--- hermes dump ---") + ver_str = f"{__version__}" + if __release_date__: + ver_str += f" ({__release_date__})" + ver_str += f" [{commit}]" + lines.append(f"version: {ver_str}") + lines.append(f"os: {os_info}") + lines.append(f"python: {sys.version.split()[0]}") + lines.append(f"openai_sdk: {openai_ver}") + lines.append(f"profile: {profile}") + lines.append(f"hermes_home: {display_hermes_home()}") + lines.append(f"model: {model}") + lines.append(f"provider: {provider}") + lines.append(f"terminal: {backend}") + + # API keys + lines.append("") + lines.append("api_keys:") + api_keys = [ + ("OPENROUTER_API_KEY", "openrouter"), + ("OPENAI_API_KEY", "openai"), + ("ANTHROPIC_API_KEY", "anthropic"), + ("ANTHROPIC_TOKEN", "anthropic_token"), + ("NOUS_API_KEY", "nous"), + ("GLM_API_KEY", "glm/zai"), + ("ZAI_API_KEY", "zai"), + ("KIMI_API_KEY", "kimi"), + ("MINIMAX_API_KEY", "minimax"), + ("DEEPSEEK_API_KEY", "deepseek"), + ("DASHSCOPE_API_KEY", "dashscope"), + ("HF_TOKEN", "huggingface"), + ("AI_GATEWAY_API_KEY", "ai_gateway"), + ("OPENCODE_ZEN_API_KEY", "opencode_zen"), + ("OPENCODE_GO_API_KEY", "opencode_go"), + ("KILOCODE_API_KEY", "kilocode"), + ("FIRECRAWL_API_KEY", "firecrawl"), + ("TAVILY_API_KEY", "tavily"), + ("BROWSERBASE_API_KEY", "browserbase"), + ("FAL_KEY", "fal"), + ("ELEVENLABS_API_KEY", "elevenlabs"), + ("GITHUB_TOKEN", "github"), + ] + + for env_var, label in api_keys: + val = os.getenv(env_var, "") + if show_keys and val: + display = _redact(val) + else: + display = "set" if val else "not set" + lines.append(f" {label:<20} {display}") + + # Features summary + lines.append("") + lines.append("features:") + + toolsets = config.get("toolsets", ["hermes-cli"]) + lines.append(f" toolsets: {', '.join(toolsets) if toolsets else '(default)'}") + lines.append(f" mcp_servers: {_count_mcp_servers(config)}") + lines.append(f" memory_provider: {_memory_provider(config)}") + lines.append(f" gateway: {_gateway_status()}") + + platforms = _configured_platforms() + lines.append(f" platforms: {', '.join(platforms) if platforms else 'none'}") + lines.append(f" cron_jobs: {_cron_summary(hermes_home)}") + lines.append(f" skills: {_count_skills(hermes_home)}") + + # Config overrides (non-default values) + overrides = _config_overrides(config) + if overrides: + lines.append("") + lines.append("config_overrides:") + for key, val in overrides.items(): + lines.append(f" {key}: {val}") + + lines.append("--- end dump ---") + + output = "\n".join(lines) + print(output) diff --git a/mindcli/_vendor/hermes_cli/env_loader.py b/mindcli/_vendor/hermes_cli/env_loader.py new file mode 100644 index 0000000..8d6a144 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/env_loader.py @@ -0,0 +1,94 @@ +"""Helpers for loading Hermes .env files consistently across entrypoints.""" + +from __future__ import annotations + +import os +from pathlib import Path + +from dotenv import load_dotenv + + +def _load_dotenv_with_fallback(path: Path, *, override: bool) -> None: + try: + load_dotenv(dotenv_path=path, override=override, encoding="utf-8") + except UnicodeDecodeError: + load_dotenv(dotenv_path=path, override=override, encoding="latin-1") + + +def _sanitize_env_file_if_needed(path: Path) -> None: + """Pre-sanitize a .env file before python-dotenv reads it. + + python-dotenv does not handle corrupted lines where multiple + KEY=VALUE pairs are concatenated on a single line (missing newline). + This produces mangled values — e.g. a bot token duplicated 8× + (see #8908). + + We delegate to ``hermes_cli.config._sanitize_env_lines`` which + already knows all valid Hermes env-var names and can split + concatenated lines correctly. + """ + if not path.exists(): + return + try: + from hermes_cli.config import _sanitize_env_lines + except ImportError: + return # early bootstrap — config module not available yet + + read_kw = {"encoding": "utf-8", "errors": "replace"} + try: + with open(path, **read_kw) as f: + original = f.readlines() + sanitized = _sanitize_env_lines(original) + if sanitized != original: + import tempfile + fd, tmp = tempfile.mkstemp( + dir=str(path.parent), suffix=".tmp", prefix=".env_" + ) + try: + with os.fdopen(fd, "w", encoding="utf-8") as f: + f.writelines(sanitized) + f.flush() + os.fsync(f.fileno()) + os.replace(tmp, path) + except BaseException: + try: + os.unlink(tmp) + except OSError: + pass + raise + except Exception: + pass # best-effort — don't block gateway startup + + +def load_hermes_dotenv( + *, + hermes_home: str | os.PathLike | None = None, + project_env: str | os.PathLike | None = None, +) -> list[Path]: + """Load Hermes environment files with user config taking precedence. + + Behavior: + - `~/.hermes/.env` overrides stale shell-exported values when present. + - project `.env` acts as a dev fallback and only fills missing values when + the user env exists. + - if no user env exists, the project `.env` also overrides stale shell vars. + """ + loaded: list[Path] = [] + + home_path = Path(hermes_home or os.getenv("HERMES_HOME", Path.home() / ".hermes")) + user_env = home_path / ".env" + project_env_path = Path(project_env) if project_env else None + + # Fix corrupted .env files before python-dotenv parses them (#8908). + if user_env.exists(): + _sanitize_env_file_if_needed(user_env) + + if user_env.exists(): + _load_dotenv_with_fallback(user_env, override=True) + loaded.append(user_env) + + if project_env_path and project_env_path.exists(): + _load_dotenv_with_fallback(project_env_path, override=not loaded) + loaded.append(project_env_path) + + return loaded diff --git a/mindcli/_vendor/hermes_cli/gateway.py b/mindcli/_vendor/hermes_cli/gateway.py new file mode 100644 index 0000000..fe7bb9b --- /dev/null +++ b/mindcli/_vendor/hermes_cli/gateway.py @@ -0,0 +1,3054 @@ +""" +Gateway subcommand for hermes CLI. + +Handles: hermes gateway [run|start|stop|restart|status|install|uninstall|setup] +""" + +import asyncio +import os +import shutil +import signal +import subprocess +import sys +from pathlib import Path + +PROJECT_ROOT = Path(__file__).parent.parent.resolve() + +from gateway.status import terminate_pid +from gateway.restart import ( + DEFAULT_GATEWAY_RESTART_DRAIN_TIMEOUT, + GATEWAY_SERVICE_RESTART_EXIT_CODE, + parse_restart_drain_timeout, +) +from hermes_cli.config import ( + get_env_value, + get_hermes_home, + is_managed, + managed_error, + read_raw_config, + save_env_value, +) +# display_hermes_home is imported lazily at call sites to avoid ImportError +# when hermes_constants is cached from a pre-update version during `hermes update`. +from hermes_cli.setup import ( + print_header, print_info, print_success, print_warning, print_error, + prompt, prompt_choice, prompt_yes_no, +) +from hermes_cli.colors import Colors, color + + +# ============================================================================= +# Process Management (for manual gateway runs) +# ============================================================================= + +def _get_service_pids() -> set: + """Return PIDs currently managed by systemd or launchd gateway services. + + Used to avoid killing freshly-restarted service processes when sweeping + for stale manual gateway processes after a service restart. Relies on the + service manager having committed the new PID before the restart command + returns (true for both systemd and launchd in practice). + """ + pids: set = set() + + # --- systemd (Linux): user and system scopes --- + if supports_systemd_services(): + for scope_args in [["systemctl", "--user"], ["systemctl"]]: + try: + result = subprocess.run( + scope_args + ["list-units", "hermes-gateway*", + "--plain", "--no-legend", "--no-pager"], + capture_output=True, text=True, timeout=5, + ) + for line in result.stdout.strip().splitlines(): + parts = line.split() + if not parts or not parts[0].endswith(".service"): + continue + svc = parts[0] + try: + show = subprocess.run( + scope_args + ["show", svc, + "--property=MainPID", "--value"], + capture_output=True, text=True, timeout=5, + ) + pid = int(show.stdout.strip()) + if pid > 0: + pids.add(pid) + except (ValueError, subprocess.TimeoutExpired): + pass + except (FileNotFoundError, subprocess.TimeoutExpired): + pass + + # --- launchd (macOS) --- + if is_macos(): + try: + label = get_launchd_label() + result = subprocess.run( + ["launchctl", "list", label], + capture_output=True, text=True, timeout=5, + ) + if result.returncode == 0: + # Output: "PID\tStatus\tLabel" header, then one data line + for line in result.stdout.strip().splitlines(): + parts = line.split() + if len(parts) >= 3 and parts[2] == label: + try: + pid = int(parts[0]) + if pid > 0: + pids.add(pid) + except ValueError: + pass + except (FileNotFoundError, subprocess.TimeoutExpired): + pass + + return pids + + +def _get_parent_pid(pid: int) -> int | None: + """Return the parent PID for ``pid``, or ``None`` when unavailable.""" + if pid <= 1: + return None + try: + result = subprocess.run( + ["ps", "-o", "ppid=", "-p", str(pid)], + capture_output=True, + text=True, + timeout=5, + ) + except (FileNotFoundError, subprocess.TimeoutExpired): + return None + if result.returncode != 0: + return None + raw = result.stdout.strip() + if not raw: + return None + try: + parent_pid = int(raw.splitlines()[-1].strip()) + except ValueError: + return None + return parent_pid if parent_pid > 0 else None + + +def _is_pid_ancestor_of_current_process(target_pid: int) -> bool: + """Return True when ``target_pid`` is this process or one of its ancestors.""" + if target_pid <= 0: + return False + + pid = os.getpid() + seen: set[int] = set() + while pid and pid not in seen: + if pid == target_pid: + return True + seen.add(pid) + pid = _get_parent_pid(pid) or 0 + return False + + +def _request_gateway_self_restart(pid: int) -> bool: + """Ask a running gateway ancestor to restart itself asynchronously.""" + if not hasattr(signal, "SIGUSR1"): + return False + if not _is_pid_ancestor_of_current_process(pid): + return False + try: + os.kill(pid, signal.SIGUSR1) + except (ProcessLookupError, PermissionError, OSError): + return False + return True + + +def find_gateway_pids(exclude_pids: set | None = None, all_profiles: bool = False) -> list: + """Find PIDs of running gateway processes. + + Args: + exclude_pids: PIDs to exclude from the result (e.g. service-managed + PIDs that should not be killed during a stale-process sweep). + all_profiles: When ``True``, return gateway PIDs across **all** + profiles (the pre-7923 global behaviour). ``hermes update`` + needs this because a code update affects every profile. + When ``False`` (default), only PIDs belonging to the current + Hermes profile are returned. + """ + _exclude = exclude_pids or set() + pids = [pid for pid in _get_service_pids() if pid not in _exclude] + patterns = [ + "hermes_cli.main gateway", + "hermes_cli.main --profile", + "hermes_cli.main -p", + "hermes_cli/main.py gateway", + "hermes_cli/main.py --profile", + "hermes_cli/main.py -p", + "hermes gateway", + "gateway/run.py", + ] + current_home = str(get_hermes_home().resolve()) + current_profile_arg = _profile_arg(current_home) + current_profile_name = current_profile_arg.split()[-1] if current_profile_arg else "" + + def _matches_current_profile(command: str) -> bool: + if current_profile_name: + return ( + f"--profile {current_profile_name}" in command + or f"-p {current_profile_name}" in command + or f"HERMES_HOME={current_home}" in command + ) + + if "--profile " in command or " -p " in command: + return False + if "HERMES_HOME=" in command and f"HERMES_HOME={current_home}" not in command: + return False + return True + + try: + if is_windows(): + result = subprocess.run( + ["wmic", "process", "get", "ProcessId,CommandLine", "/FORMAT:LIST"], + capture_output=True, text=True, timeout=10 + ) + current_cmd = "" + for line in result.stdout.split('\n'): + line = line.strip() + if line.startswith("CommandLine="): + current_cmd = line[len("CommandLine="):] + elif line.startswith("ProcessId="): + pid_str = line[len("ProcessId="):] + if any(p in current_cmd for p in patterns) and (all_profiles or _matches_current_profile(current_cmd)): + try: + pid = int(pid_str) + if pid != os.getpid() and pid not in pids and pid not in _exclude: + pids.append(pid) + except ValueError: + pass + current_cmd = "" + else: + result = subprocess.run( + ["ps", "eww", "-ax", "-o", "pid=,command="], + capture_output=True, + text=True, + timeout=10, + ) + for line in result.stdout.split('\n'): + stripped = line.strip() + if not stripped or 'grep' in stripped: + continue + + pid = None + command = "" + + parts = stripped.split(None, 1) + if len(parts) == 2: + try: + pid = int(parts[0]) + command = parts[1] + except ValueError: + pid = None + + if pid is None: + aux_parts = stripped.split() + if len(aux_parts) > 10 and aux_parts[1].isdigit(): + pid = int(aux_parts[1]) + command = " ".join(aux_parts[10:]) + + if pid is None: + continue + if pid == os.getpid() or pid in pids or pid in _exclude: + continue + if any(pattern in command for pattern in patterns) and (all_profiles or _matches_current_profile(command)): + pids.append(pid) + except (OSError, subprocess.TimeoutExpired): + pass + + return pids + + +def kill_gateway_processes(force: bool = False, exclude_pids: set | None = None, + all_profiles: bool = False) -> int: + """Kill any running gateway processes. Returns count killed. + + Args: + force: Use the platform's force-kill mechanism instead of graceful terminate. + exclude_pids: PIDs to skip (e.g. service-managed PIDs that were just + restarted and should not be killed). + all_profiles: When ``True``, kill across all profiles. Passed + through to :func:`find_gateway_pids`. + """ + pids = find_gateway_pids(exclude_pids=exclude_pids, all_profiles=all_profiles) + killed = 0 + + for pid in pids: + try: + terminate_pid(pid, force=force) + killed += 1 + except ProcessLookupError: + # Process already gone + pass + except PermissionError: + print(f"⚠ Permission denied to kill PID {pid}") + + except OSError as exc: + print(f"Failed to kill PID {pid}: {exc}") + return killed + + +def stop_profile_gateway() -> bool: + """Stop only the gateway for the current profile (HERMES_HOME-scoped). + + Uses the PID file written by start_gateway(), so it only kills the + gateway belonging to this profile — not gateways from other profiles. + Returns True if a process was stopped, False if none was found. + """ + try: + from gateway.status import get_running_pid, remove_pid_file + except ImportError: + return False + + pid = get_running_pid() + if pid is None: + return False + + try: + os.kill(pid, signal.SIGTERM) + except ProcessLookupError: + pass # Already gone + except PermissionError: + print(f"⚠ Permission denied to kill PID {pid}") + return False + + # Wait briefly for it to exit + import time as _time + for _ in range(20): + try: + os.kill(pid, 0) + _time.sleep(0.5) + except (ProcessLookupError, PermissionError): + break + + remove_pid_file() + return True + + +def is_linux() -> bool: + return sys.platform.startswith('linux') + + +from hermes_constants import is_container, is_termux, is_wsl + + +def _wsl_systemd_operational() -> bool: + """Check if systemd is actually running as PID 1 on WSL. + + WSL2 with ``systemd=true`` in wsl.conf has working systemd. + WSL2 without it (or WSL1) does not — systemctl commands fail. + """ + try: + result = subprocess.run( + ["systemctl", "is-system-running"], + capture_output=True, text=True, timeout=5, + ) + # "running", "degraded", "starting" all mean systemd is PID 1 + status = result.stdout.strip().lower() + return status in ("running", "degraded", "starting", "initializing") + except (FileNotFoundError, subprocess.TimeoutExpired, OSError): + return False + + +def supports_systemd_services() -> bool: + if not is_linux() or is_termux() or is_container(): + return False + if shutil.which("systemctl") is None: + return False + if is_wsl(): + return _wsl_systemd_operational() + return True + + +def is_macos() -> bool: + return sys.platform == 'darwin' + +def is_windows() -> bool: + return sys.platform == 'win32' + + +# ============================================================================= +# Service Configuration +# ============================================================================= + +_SERVICE_BASE = "hermes-gateway" +SERVICE_DESCRIPTION = "Hermes Agent Gateway - Messaging Platform Integration" + + +def _profile_suffix() -> str: + """Derive a service-name suffix from the current HERMES_HOME. + + Returns ``""`` for the default root, the profile name for + ``/profiles/``, or a short hash for any other path. + Works correctly in Docker (HERMES_HOME=/opt/data) and standard deployments. + """ + import hashlib + import re + from hermes_constants import get_default_hermes_root + home = get_hermes_home().resolve() + default = get_default_hermes_root().resolve() + if home == default: + return "" + # Detect /profiles/ pattern → use the profile name + profiles_root = (default / "profiles").resolve() + try: + rel = home.relative_to(profiles_root) + parts = rel.parts + if len(parts) == 1 and re.match(r"^[a-z0-9][a-z0-9_-]{0,63}$", parts[0]): + return parts[0] + except ValueError: + pass + # Fallback: short hash for arbitrary HERMES_HOME paths + return hashlib.sha256(str(home).encode()).hexdigest()[:8] + + +def _profile_arg(hermes_home: str | None = None) -> str: + """Return ``--profile `` only when HERMES_HOME is a named profile. + + For ``~/.hermes/profiles/``, returns ``"--profile "``. + For the default profile or hash-based custom paths, returns the empty string. + + Args: + hermes_home: Optional explicit HERMES_HOME path. Defaults to the current + ``get_hermes_home()`` value. Should be passed when generating a + service definition for a different user (e.g. system service). + """ + import re + from hermes_constants import get_default_hermes_root + home = Path(hermes_home or str(get_hermes_home())).resolve() + default = get_default_hermes_root().resolve() + if home == default: + return "" + profiles_root = (default / "profiles").resolve() + try: + rel = home.relative_to(profiles_root) + parts = rel.parts + if len(parts) == 1 and re.match(r"^[a-z0-9][a-z0-9_-]{0,63}$", parts[0]): + return f"--profile {parts[0]}" + except ValueError: + pass + return "" + + +def get_service_name() -> str: + """Derive a systemd service name scoped to this HERMES_HOME. + + Default ``~/.hermes`` returns ``hermes-gateway`` (backward compatible). + Profile ``~/.hermes/profiles/coder`` returns ``hermes-gateway-coder``. + Any other HERMES_HOME appends a short hash for uniqueness. + """ + suffix = _profile_suffix() + if not suffix: + return _SERVICE_BASE + return f"{_SERVICE_BASE}-{suffix}" + + + +def get_systemd_unit_path(system: bool = False) -> Path: + name = get_service_name() + if system: + return Path("/etc/systemd/system") / f"{name}.service" + return Path.home() / ".config" / "systemd" / "user" / f"{name}.service" + + +def _ensure_user_systemd_env() -> None: + """Ensure DBUS_SESSION_BUS_ADDRESS and XDG_RUNTIME_DIR are set for systemctl --user. + + On headless servers (SSH sessions), these env vars may be missing even when + the user's systemd instance is running (via linger). Without them, + ``systemctl --user`` fails with "Failed to connect to bus: No medium found". + We detect the standard socket path and set the vars so all subsequent + subprocess calls inherit them. + """ + uid = os.getuid() + if "XDG_RUNTIME_DIR" not in os.environ: + runtime_dir = f"/run/user/{uid}" + if Path(runtime_dir).exists(): + os.environ["XDG_RUNTIME_DIR"] = runtime_dir + + if "DBUS_SESSION_BUS_ADDRESS" not in os.environ: + xdg_runtime = os.environ.get("XDG_RUNTIME_DIR", f"/run/user/{uid}") + bus_path = Path(xdg_runtime) / "bus" + if bus_path.exists(): + os.environ["DBUS_SESSION_BUS_ADDRESS"] = f"unix:path={bus_path}" + + +def _systemctl_cmd(system: bool = False) -> list[str]: + if not system: + _ensure_user_systemd_env() + return ["systemctl"] if system else ["systemctl", "--user"] + + +def _journalctl_cmd(system: bool = False) -> list[str]: + return ["journalctl"] if system else ["journalctl", "--user"] + + +def _run_systemctl(args: list[str], *, system: bool = False, **kwargs) -> subprocess.CompletedProcess: + """Run a systemctl command, raising RuntimeError if systemctl is missing. + + Defense-in-depth: callers are gated by ``supports_systemd_services()``, + but this ensures any future caller that bypasses the gate still gets a + clear error instead of a raw ``FileNotFoundError`` traceback. + """ + try: + return subprocess.run(_systemctl_cmd(system) + args, **kwargs) + except FileNotFoundError: + raise RuntimeError( + "systemctl is not available on this system" + ) from None + + +def _service_scope_label(system: bool = False) -> str: + return "system" if system else "user" + + +def get_installed_systemd_scopes() -> list[str]: + scopes = [] + seen_paths: set[Path] = set() + for system, label in ((False, "user"), (True, "system")): + unit_path = get_systemd_unit_path(system=system) + if unit_path in seen_paths: + continue + if unit_path.exists(): + scopes.append(label) + seen_paths.add(unit_path) + return scopes + + +def has_conflicting_systemd_units() -> bool: + return len(get_installed_systemd_scopes()) > 1 + + +def print_systemd_scope_conflict_warning() -> None: + scopes = get_installed_systemd_scopes() + if len(scopes) < 2: + return + + rendered_scopes = " + ".join(scopes) + print_warning(f"Both user and system gateway services are installed ({rendered_scopes}).") + print_info(" This is confusing and can make start/stop/status behavior ambiguous.") + print_info(" Default gateway commands target the user service unless you pass --system.") + print_info(" Keep one of these:") + print_info(" hermes gateway uninstall") + print_info(" sudo hermes gateway uninstall --system") + + +def _require_root_for_system_service(action: str) -> None: + if os.geteuid() != 0: + print(f"System gateway {action} requires root. Re-run with sudo.") + sys.exit(1) + + +def _system_service_identity(run_as_user: str | None = None) -> tuple[str, str, str]: + import getpass + import grp + import pwd + + username = (run_as_user or os.getenv("SUDO_USER") or os.getenv("USER") or os.getenv("LOGNAME") or getpass.getuser()).strip() + if not username: + raise ValueError("Could not determine which user the gateway service should run as") + if username == "root" and not run_as_user: + raise ValueError("Refusing to install the gateway system service as root; pass --run-as-user root to override (e.g. in LXC containers)") + if username == "root": + print_warning("Installing gateway service to run as root.") + print_info(" This is fine for LXC/container environments but not recommended on bare-metal hosts.") + + try: + user_info = pwd.getpwnam(username) + except KeyError as e: + raise ValueError(f"Unknown user: {username}") from e + + group_name = grp.getgrgid(user_info.pw_gid).gr_name + return username, group_name, user_info.pw_dir + + +def _read_systemd_user_from_unit(unit_path: Path) -> str | None: + if not unit_path.exists(): + return None + + for line in unit_path.read_text(encoding="utf-8").splitlines(): + if line.startswith("User="): + value = line.split("=", 1)[1].strip() + return value or None + return None + + +def _default_system_service_user() -> str | None: + for candidate in (os.getenv("SUDO_USER"), os.getenv("USER"), os.getenv("LOGNAME")): + if candidate and candidate.strip() and candidate.strip() != "root": + return candidate.strip() + return None + + +def prompt_linux_gateway_install_scope() -> str | None: + choice = prompt_choice( + " Choose how the gateway should run in the background:", + [ + "User service (no sudo; best for laptops/dev boxes; may need linger after logout)", + "System service (starts on boot; requires sudo; still runs as your user)", + "Skip service install for now", + ], + default=0, + ) + return {0: "user", 1: "system", 2: None}[choice] + + +def install_linux_gateway_from_setup(force: bool = False) -> tuple[str | None, bool]: + scope = prompt_linux_gateway_install_scope() + if scope is None: + return None, False + + if scope == "system": + run_as_user = _default_system_service_user() + if os.geteuid() != 0: + print_warning(" System service install requires sudo, so Hermes can't create it from this user session.") + if run_as_user: + print_info(f" After setup, run: sudo hermes gateway install --system --run-as-user {run_as_user}") + else: + print_info(" After setup, run: sudo hermes gateway install --system --run-as-user ") + print_info(" Then start it with: sudo hermes gateway start --system") + return scope, False + + if not run_as_user: + while True: + run_as_user = prompt(" Run the system gateway service as which user?", default="") + run_as_user = (run_as_user or "").strip() + if run_as_user: + break + print_error(" Enter a username.") + + systemd_install(force=force, system=True, run_as_user=run_as_user) + return scope, True + + systemd_install(force=force, system=False) + return scope, True + + +def get_systemd_linger_status() -> tuple[bool | None, str]: + """Return systemd linger status for the current user. + + Returns: + (True, "") when linger is enabled. + (False, "") when linger is disabled. + (None, detail) when the status could not be determined. + """ + if is_termux(): + return None, "not supported in Termux" + if not is_linux(): + return None, "not supported on this platform" + + import shutil + + if not shutil.which("loginctl"): + return None, "loginctl not found" + + username = os.getenv("USER") or os.getenv("LOGNAME") + if not username: + try: + import pwd + username = pwd.getpwuid(os.getuid()).pw_name + except Exception: + return None, "could not determine current user" + + try: + result = subprocess.run( + ["loginctl", "show-user", username, "--property=Linger", "--value"], + capture_output=True, + text=True, + check=False, + timeout=10, + ) + except Exception as e: + return None, str(e) + + if result.returncode != 0: + detail = (result.stderr or result.stdout or f"exit {result.returncode}").strip() + return None, detail or "loginctl query failed" + + value = (result.stdout or "").strip().lower() + if value in {"yes", "true", "1"}: + return True, "" + if value in {"no", "false", "0"}: + return False, "" + + rendered = value or "" + return None, f"unexpected loginctl output: {rendered}" + + +def print_systemd_linger_guidance() -> None: + """Print the current linger status and the fix when it is disabled.""" + linger_enabled, linger_detail = get_systemd_linger_status() + if linger_enabled is True: + print("✓ Systemd linger is enabled (service survives logout)") + elif linger_enabled is False: + print("⚠ Systemd linger is disabled (gateway may stop when you log out)") + print(" Run: sudo loginctl enable-linger $USER") + else: + print(f"⚠ Could not verify systemd linger ({linger_detail})") + print(" If you want the gateway user service to survive logout, run:") + print(" sudo loginctl enable-linger $USER") + +def _launchd_user_home() -> Path: + """Return the real macOS user home for launchd artifacts. + + Profile-mode Hermes often sets ``HOME`` to a profile-scoped directory, but + launchd user agents still live under the actual account home. + """ + import pwd + + return Path(pwd.getpwuid(os.getuid()).pw_dir) + + +def get_launchd_plist_path() -> Path: + """Return the launchd plist path, scoped per profile. + + Default ``~/.hermes`` → ``ai.hermes.gateway.plist`` (backward compatible). + Profile ``~/.hermes/profiles/coder`` → ``ai.hermes.gateway-coder.plist``. + """ + suffix = _profile_suffix() + name = f"ai.hermes.gateway-{suffix}" if suffix else "ai.hermes.gateway" + return _launchd_user_home() / "Library" / "LaunchAgents" / f"{name}.plist" + +def _detect_venv_dir() -> Path | None: + """Detect the active virtualenv directory. + + Checks ``sys.prefix`` first (works regardless of the directory name), + then falls back to probing common directory names under PROJECT_ROOT. + Returns ``None`` when no virtualenv can be found. + """ + # If we're running inside a virtualenv, sys.prefix points to it. + if sys.prefix != sys.base_prefix: + venv = Path(sys.prefix) + if venv.is_dir(): + return venv + + # Fallback: check common virtualenv directory names under the project root. + for candidate in (".venv", "venv"): + venv = PROJECT_ROOT / candidate + if venv.is_dir(): + return venv + + return None + + +def get_python_path() -> str: + venv = _detect_venv_dir() + if venv is not None: + if is_windows(): + venv_python = venv / "Scripts" / "python.exe" + else: + venv_python = venv / "bin" / "python" + if venv_python.exists(): + return str(venv_python) + return sys.executable + + +# ============================================================================= +# Systemd (Linux) +# ============================================================================= + +def _build_user_local_paths(home: Path, path_entries: list[str]) -> list[str]: + """Return user-local bin dirs that exist and aren't already in *path_entries*.""" + candidates = [ + str(home / ".local" / "bin"), # uv, uvx, pip-installed CLIs + str(home / ".cargo" / "bin"), # Rust/cargo tools + str(home / "go" / "bin"), # Go tools + str(home / ".npm-global" / "bin"), # npm global packages + ] + return [p for p in candidates if p not in path_entries and Path(p).exists()] + + +def _remap_path_for_user(path: str, target_home_dir: str) -> str: + """Remap *path* from the current user's home to *target_home_dir*. + + If *path* lives under ``Path.home()`` the corresponding prefix is swapped + to *target_home_dir*; otherwise the path is returned unchanged. + + /root/.hermes/hermes-agent -> /home/alice/.hermes/hermes-agent + /opt/hermes -> /opt/hermes (kept as-is) + + Note: this function intentionally does NOT resolve symlinks. A venv's + ``bin/python`` is typically a symlink to the base interpreter (e.g. a + uv-managed CPython at ``~/.local/share/uv/python/.../python3.11``); + resolving that symlink swaps the unit's ``ExecStart`` to a bare Python + that has none of the venv's site-packages, so the service crashes on + the first ``import``. Keep the symlinked path so the venv activates + its own environment. Lexical expansion only via ``expanduser``. + """ + current_home = Path.home() + p = Path(path).expanduser() + try: + relative = p.relative_to(current_home) + return str(Path(target_home_dir) / relative) + except ValueError: + return str(p) + + +def _hermes_home_for_target_user(target_home_dir: str) -> str: + """Remap the current HERMES_HOME to the equivalent under a target user's home. + + When installing a system service via sudo, get_hermes_home() resolves to + root's home. This translates it to the target user's equivalent path: + /root/.hermes → /home/alice/.hermes + /root/.hermes/profiles/coder → /home/alice/.hermes/profiles/coder + /opt/custom-hermes → /opt/custom-hermes (kept as-is) + """ + current_hermes = get_hermes_home().resolve() + current_default = (Path.home() / ".hermes").resolve() + target_default = Path(target_home_dir) / ".hermes" + + # Default ~/.hermes → remap to target user's default + if current_hermes == current_default: + return str(target_default) + + # Profile or subdir of ~/.hermes → preserve the relative structure + try: + relative = current_hermes.relative_to(current_default) + return str(target_default / relative) + except ValueError: + # Completely custom path (not under ~/.hermes) — keep as-is + return str(current_hermes) + + +def generate_systemd_unit(system: bool = False, run_as_user: str | None = None) -> str: + python_path = get_python_path() + working_dir = str(PROJECT_ROOT) + detected_venv = _detect_venv_dir() + venv_dir = str(detected_venv) if detected_venv else str(PROJECT_ROOT / "venv") + venv_bin = str(detected_venv / "bin") if detected_venv else str(PROJECT_ROOT / "venv" / "bin") + node_bin = str(PROJECT_ROOT / "node_modules" / ".bin") + + path_entries = [venv_bin, node_bin] + resolved_node = shutil.which("node") + if resolved_node: + resolved_node_dir = str(Path(resolved_node).resolve().parent) + if resolved_node_dir not in path_entries: + path_entries.append(resolved_node_dir) + + common_bin_paths = ["/usr/local/sbin", "/usr/local/bin", "/usr/sbin", "/usr/bin", "/sbin", "/bin"] + restart_timeout = max(60, int(_get_restart_drain_timeout() or 0)) + + if system: + username, group_name, home_dir = _system_service_identity(run_as_user) + hermes_home = _hermes_home_for_target_user(home_dir) + profile_arg = _profile_arg(hermes_home) + # Remap all paths that may resolve under the calling user's home + # (e.g. /root/) to the target user's home so the service can + # actually access them. + python_path = _remap_path_for_user(python_path, home_dir) + working_dir = _remap_path_for_user(working_dir, home_dir) + venv_dir = _remap_path_for_user(venv_dir, home_dir) + venv_bin = _remap_path_for_user(venv_bin, home_dir) + node_bin = _remap_path_for_user(node_bin, home_dir) + path_entries = [_remap_path_for_user(p, home_dir) for p in path_entries] + path_entries.extend(_build_user_local_paths(Path(home_dir), path_entries)) + path_entries.extend(common_bin_paths) + sane_path = ":".join(path_entries) + return f"""[Unit] +Description={SERVICE_DESCRIPTION} +After=network-online.target +Wants=network-online.target +StartLimitIntervalSec=600 +StartLimitBurst=5 + +[Service] +Type=simple +User={username} +Group={group_name} +ExecStart={python_path} -m hermes_cli.main{f" {profile_arg}" if profile_arg else ""} gateway run --replace +WorkingDirectory={working_dir} +Environment="HOME={home_dir}" +Environment="USER={username}" +Environment="LOGNAME={username}" +Environment="PATH={sane_path}" +Environment="VIRTUAL_ENV={venv_dir}" +Environment="HERMES_HOME={hermes_home}" +Restart=on-failure +RestartSec=30 +RestartForceExitStatus={GATEWAY_SERVICE_RESTART_EXIT_CODE} +KillMode=mixed +KillSignal=SIGTERM +ExecReload=/bin/kill -USR1 $MAINPID +TimeoutStopSec={restart_timeout} +StandardOutput=journal +StandardError=journal + +[Install] +WantedBy=multi-user.target +""" + + hermes_home = str(get_hermes_home().resolve()) + profile_arg = _profile_arg(hermes_home) + path_entries.extend(_build_user_local_paths(Path.home(), path_entries)) + path_entries.extend(common_bin_paths) + sane_path = ":".join(path_entries) + return f"""[Unit] +Description={SERVICE_DESCRIPTION} +After=network.target +StartLimitIntervalSec=600 +StartLimitBurst=5 + +[Service] +Type=simple +ExecStart={python_path} -m hermes_cli.main{f" {profile_arg}" if profile_arg else ""} gateway run --replace +WorkingDirectory={working_dir} +Environment="PATH={sane_path}" +Environment="VIRTUAL_ENV={venv_dir}" +Environment="HERMES_HOME={hermes_home}" +Restart=on-failure +RestartSec=30 +RestartForceExitStatus={GATEWAY_SERVICE_RESTART_EXIT_CODE} +KillMode=mixed +KillSignal=SIGTERM +ExecReload=/bin/kill -USR1 $MAINPID +TimeoutStopSec={restart_timeout} +StandardOutput=journal +StandardError=journal + +[Install] +WantedBy=default.target +""" + +def _normalize_service_definition(text: str) -> str: + return "\n".join(line.rstrip() for line in text.strip().splitlines()) + + +def _normalize_launchd_plist_for_comparison(text: str) -> str: + """Normalize launchd plist text for staleness checks. + + The generated plist intentionally captures a broad PATH assembled from the + invoking shell so user-installed tools remain reachable under launchd. + That makes raw text comparison unstable across shells, so ignore the PATH + payload when deciding whether the installed plist is stale. + """ + import re + + normalized = _normalize_service_definition(text) + return re.sub( + r'(PATH\s*)(.*?)()', + r'\1__HERMES_PATH__\3', + normalized, + flags=re.S, + ) + + +def systemd_unit_is_current(system: bool = False) -> bool: + unit_path = get_systemd_unit_path(system=system) + if not unit_path.exists(): + return False + + installed = unit_path.read_text(encoding="utf-8") + expected_user = _read_systemd_user_from_unit(unit_path) if system else None + expected = generate_systemd_unit(system=system, run_as_user=expected_user) + return _normalize_service_definition(installed) == _normalize_service_definition(expected) + + + +def refresh_systemd_unit_if_needed(system: bool = False) -> bool: + """Rewrite the installed systemd unit when the generated definition has changed.""" + unit_path = get_systemd_unit_path(system=system) + if not unit_path.exists() or systemd_unit_is_current(system=system): + return False + + expected_user = _read_systemd_user_from_unit(unit_path) if system else None + unit_path.write_text(generate_systemd_unit(system=system, run_as_user=expected_user), encoding="utf-8") + _run_systemctl(["daemon-reload"], system=system, check=True, timeout=30) + print(f"↻ Updated gateway {_service_scope_label(system)} service definition to match the current Hermes install") + return True + + + +def _print_linger_enable_warning(username: str, detail: str | None = None) -> None: + print() + print("⚠ Linger not enabled — gateway may stop when you close this terminal.") + if detail: + print(f" Auto-enable failed: {detail}") + print() + print(" On headless servers (VPS, cloud instances) run:") + print(f" sudo loginctl enable-linger {username}") + print() + print(" Then restart the gateway:") + print(f" systemctl --user restart {get_service_name()}.service") + print() + + + +def _ensure_linger_enabled() -> None: + """Enable linger when possible so the user gateway survives logout.""" + if is_termux() or not is_linux(): + return + + import getpass + import shutil + + username = getpass.getuser() + linger_file = Path(f"/var/lib/systemd/linger/{username}") + if linger_file.exists(): + print("✓ Systemd linger is enabled (service survives logout)") + return + + linger_enabled, linger_detail = get_systemd_linger_status() + if linger_enabled is True: + print("✓ Systemd linger is enabled (service survives logout)") + return + + if not shutil.which("loginctl"): + _print_linger_enable_warning(username, linger_detail or "loginctl not found") + return + + print("Enabling linger so the gateway survives SSH logout...") + try: + result = subprocess.run( + ["loginctl", "enable-linger", username], + capture_output=True, + text=True, + check=False, + timeout=30, + ) + except Exception as e: + _print_linger_enable_warning(username, str(e)) + return + + if result.returncode == 0: + print("✓ Linger enabled — gateway will persist after logout") + return + + detail = (result.stderr or result.stdout or f"exit {result.returncode}").strip() + _print_linger_enable_warning(username, detail or linger_detail) + + +def _select_systemd_scope(system: bool = False) -> bool: + if system: + return True + return get_systemd_unit_path(system=True).exists() and not get_systemd_unit_path(system=False).exists() + + +def _get_restart_drain_timeout() -> float: + """Return the configured gateway restart drain timeout in seconds.""" + raw = os.getenv("HERMES_RESTART_DRAIN_TIMEOUT", "").strip() + if not raw: + cfg = read_raw_config() + agent_cfg = cfg.get("agent", {}) if isinstance(cfg, dict) else {} + raw = str( + agent_cfg.get( + "restart_drain_timeout", DEFAULT_GATEWAY_RESTART_DRAIN_TIMEOUT + ) + ) + return parse_restart_drain_timeout(raw) + + +def systemd_install(force: bool = False, system: bool = False, run_as_user: str | None = None): + if system: + _require_root_for_system_service("install") + + unit_path = get_systemd_unit_path(system=system) + scope_flag = " --system" if system else "" + + if unit_path.exists() and not force: + if not systemd_unit_is_current(system=system): + print(f"↻ Repairing outdated {_service_scope_label(system)} systemd service at: {unit_path}") + refresh_systemd_unit_if_needed(system=system) + _run_systemctl(["enable", get_service_name()], system=system, check=True, timeout=30) + print(f"✓ {_service_scope_label(system).capitalize()} service definition updated") + return + print(f"Service already installed at: {unit_path}") + print("Use --force to reinstall") + return + + unit_path.parent.mkdir(parents=True, exist_ok=True) + print(f"Installing {_service_scope_label(system)} systemd service to: {unit_path}") + unit_path.write_text(generate_systemd_unit(system=system, run_as_user=run_as_user), encoding="utf-8") + + _run_systemctl(["daemon-reload"], system=system, check=True, timeout=30) + _run_systemctl(["enable", get_service_name()], system=system, check=True, timeout=30) + + print() + print(f"✓ {_service_scope_label(system).capitalize()} service installed and enabled!") + print() + print("Next steps:") + print(f" {'sudo ' if system else ''}hermes gateway start{scope_flag} # Start the service") + print(f" {'sudo ' if system else ''}hermes gateway status{scope_flag} # Check status") + print(f" {'journalctl' if system else 'journalctl --user'} -u {get_service_name()} -f # View logs") + print() + + if system: + configured_user = _read_systemd_user_from_unit(unit_path) + if configured_user: + print(f"Configured to run as: {configured_user}") + else: + _ensure_linger_enabled() + + print_systemd_scope_conflict_warning() + + +def systemd_uninstall(system: bool = False): + system = _select_systemd_scope(system) + if system: + _require_root_for_system_service("uninstall") + + _run_systemctl(["stop", get_service_name()], system=system, check=False, timeout=90) + _run_systemctl(["disable", get_service_name()], system=system, check=False, timeout=30) + + unit_path = get_systemd_unit_path(system=system) + if unit_path.exists(): + unit_path.unlink() + print(f"✓ Removed {unit_path}") + + _run_systemctl(["daemon-reload"], system=system, check=True, timeout=30) + print(f"✓ {_service_scope_label(system).capitalize()} service uninstalled") + + +def systemd_start(system: bool = False): + system = _select_systemd_scope(system) + if system: + _require_root_for_system_service("start") + refresh_systemd_unit_if_needed(system=system) + _run_systemctl(["start", get_service_name()], system=system, check=True, timeout=30) + print(f"✓ {_service_scope_label(system).capitalize()} service started") + + + +def systemd_stop(system: bool = False): + system = _select_systemd_scope(system) + if system: + _require_root_for_system_service("stop") + _run_systemctl(["stop", get_service_name()], system=system, check=True, timeout=90) + print(f"✓ {_service_scope_label(system).capitalize()} service stopped") + + + +def systemd_restart(system: bool = False): + system = _select_systemd_scope(system) + if system: + _require_root_for_system_service("restart") + refresh_systemd_unit_if_needed(system=system) + from gateway.status import get_running_pid + + pid = get_running_pid() + if pid is not None and _request_gateway_self_restart(pid): + print(f"✓ {_service_scope_label(system).capitalize()} service restart requested") + return + _run_systemctl(["reload-or-restart", get_service_name()], system=system, check=True, timeout=90) + print(f"✓ {_service_scope_label(system).capitalize()} service restarted") + + + +def systemd_status(deep: bool = False, system: bool = False): + system = _select_systemd_scope(system) + unit_path = get_systemd_unit_path(system=system) + scope_flag = " --system" if system else "" + + if not unit_path.exists(): + print("✗ Gateway service is not installed") + print(f" Run: {'sudo ' if system else ''}hermes gateway install{scope_flag}") + return + + if has_conflicting_systemd_units(): + print_systemd_scope_conflict_warning() + print() + + if not systemd_unit_is_current(system=system): + print("⚠ Installed gateway service definition is outdated") + print(f" Run: {'sudo ' if system else ''}hermes gateway restart{scope_flag} # auto-refreshes the unit") + print() + + _run_systemctl( + ["status", get_service_name(), "--no-pager"], + system=system, + capture_output=False, + timeout=10, + ) + + result = _run_systemctl( + ["is-active", get_service_name()], + system=system, + capture_output=True, + text=True, + timeout=10, + ) + + status = result.stdout.strip() + + if status == "active": + print(f"✓ {_service_scope_label(system).capitalize()} gateway service is running") + else: + print(f"✗ {_service_scope_label(system).capitalize()} gateway service is stopped") + print(f" Run: {'sudo ' if system else ''}hermes gateway start{scope_flag}") + + configured_user = _read_systemd_user_from_unit(unit_path) if system else None + if configured_user: + print(f"Configured to run as: {configured_user}") + + runtime_lines = _runtime_health_lines() + if runtime_lines: + print() + print("Recent gateway health:") + for line in runtime_lines: + print(f" {line}") + + if system: + print("✓ System service starts at boot without requiring systemd linger") + elif deep: + print_systemd_linger_guidance() + else: + linger_enabled, _ = get_systemd_linger_status() + if linger_enabled is True: + print("✓ Systemd linger is enabled (service survives logout)") + elif linger_enabled is False: + print("⚠ Systemd linger is disabled (gateway may stop when you log out)") + print(" Run: sudo loginctl enable-linger $USER") + + if deep: + print() + print("Recent logs:") + subprocess.run(_journalctl_cmd(system) + ["-u", get_service_name(), "-n", "20", "--no-pager"], timeout=10) + + +# ============================================================================= +# Launchd (macOS) +# ============================================================================= + +def get_launchd_label() -> str: + """Return the launchd service label, scoped per profile.""" + suffix = _profile_suffix() + return f"ai.hermes.gateway-{suffix}" if suffix else "ai.hermes.gateway" + + +def _launchd_domain() -> str: + import os + return f"gui/{os.getuid()}" + + +def generate_launchd_plist() -> str: + python_path = get_python_path() + working_dir = str(PROJECT_ROOT) + hermes_home = str(get_hermes_home().resolve()) + log_dir = get_hermes_home() / "logs" + log_dir.mkdir(parents=True, exist_ok=True) + label = get_launchd_label() + profile_arg = _profile_arg(hermes_home) + # Build a sane PATH for the launchd plist. launchd provides only a + # minimal default (/usr/bin:/bin:/usr/sbin:/sbin) which misses Homebrew, + # nvm, cargo, etc. We prepend venv/bin and node_modules/.bin (matching + # the systemd unit), then capture the user's full shell PATH so every + # user-installed tool (node, ffmpeg, …) is reachable. + detected_venv = _detect_venv_dir() + venv_bin = str(detected_venv / "bin") if detected_venv else str(PROJECT_ROOT / "venv" / "bin") + venv_dir = str(detected_venv) if detected_venv else str(PROJECT_ROOT / "venv") + node_bin = str(PROJECT_ROOT / "node_modules" / ".bin") + # Resolve the directory containing the node binary (e.g. Homebrew, nvm) + # so it's explicitly in PATH even if the user's shell PATH changes later. + priority_dirs = [venv_bin, node_bin] + resolved_node = shutil.which("node") + if resolved_node: + resolved_node_dir = str(Path(resolved_node).resolve().parent) + if resolved_node_dir not in priority_dirs: + priority_dirs.append(resolved_node_dir) + sane_path = ":".join( + dict.fromkeys(priority_dirs + [p for p in os.environ.get("PATH", "").split(":") if p]) + ) + + # Build ProgramArguments array, including --profile when using a named profile + prog_args = [ + f"{python_path}", + "-m", + "hermes_cli.main", + ] + if profile_arg: + for part in profile_arg.split(): + prog_args.append(f"{part}") + prog_args.extend([ + "gateway", + "run", + "--replace", + ]) + prog_args_xml = "\n ".join(prog_args) + + return f""" + + + + Label + {label} + + ProgramArguments + + {prog_args_xml} + + + WorkingDirectory + {working_dir} + + EnvironmentVariables + + PATH + {sane_path} + VIRTUAL_ENV + {venv_dir} + HERMES_HOME + {hermes_home} + + + RunAtLoad + + + KeepAlive + + SuccessfulExit + + + + StandardOutPath + {log_dir}/gateway.log + + StandardErrorPath + {log_dir}/gateway.error.log + + +""" + +def launchd_plist_is_current() -> bool: + """Check if the installed launchd plist matches the currently generated one.""" + plist_path = get_launchd_plist_path() + if not plist_path.exists(): + return False + + installed = plist_path.read_text(encoding="utf-8") + expected = generate_launchd_plist() + return _normalize_launchd_plist_for_comparison(installed) == _normalize_launchd_plist_for_comparison(expected) + + +def refresh_launchd_plist_if_needed() -> bool: + """Rewrite the installed launchd plist when the generated definition has changed. + + Unlike systemd, launchd picks up plist changes on the next ``launchctl kill``/ + ``launchctl kickstart`` cycle — no daemon-reload is needed. We still bootout/ + bootstrap to make launchd re-read the updated plist immediately. + """ + plist_path = get_launchd_plist_path() + if not plist_path.exists() or launchd_plist_is_current(): + return False + + plist_path.write_text(generate_launchd_plist(), encoding="utf-8") + label = get_launchd_label() + # Bootout/bootstrap so launchd picks up the new definition + subprocess.run(["launchctl", "bootout", f"{_launchd_domain()}/{label}"], check=False, timeout=90) + subprocess.run(["launchctl", "bootstrap", _launchd_domain(), str(plist_path)], check=False, timeout=30) + print("↻ Updated gateway launchd service definition to match the current Hermes install") + return True + + +def launchd_install(force: bool = False): + plist_path = get_launchd_plist_path() + + if plist_path.exists() and not force: + if not launchd_plist_is_current(): + print(f"↻ Repairing outdated launchd service at: {plist_path}") + refresh_launchd_plist_if_needed() + print("✓ Service definition updated") + return + print(f"Service already installed at: {plist_path}") + print("Use --force to reinstall") + return + + plist_path.parent.mkdir(parents=True, exist_ok=True) + print(f"Installing launchd service to: {plist_path}") + plist_path.write_text(generate_launchd_plist()) + + subprocess.run(["launchctl", "bootstrap", _launchd_domain(), str(plist_path)], check=True, timeout=30) + + print() + print("✓ Service installed and loaded!") + print() + print("Next steps:") + print(" hermes gateway status # Check status") + from hermes_constants import display_hermes_home as _dhh + print(f" tail -f {_dhh()}/logs/gateway.log # View logs") + +def launchd_uninstall(): + plist_path = get_launchd_plist_path() + label = get_launchd_label() + subprocess.run(["launchctl", "bootout", f"{_launchd_domain()}/{label}"], check=False, timeout=90) + + if plist_path.exists(): + plist_path.unlink() + print(f"✓ Removed {plist_path}") + + print("✓ Service uninstalled") + +def launchd_start(): + plist_path = get_launchd_plist_path() + label = get_launchd_label() + + # Self-heal if the plist is missing entirely (e.g., manual cleanup, failed upgrade) + if not plist_path.exists(): + print("↻ launchd plist missing; regenerating service definition") + plist_path.parent.mkdir(parents=True, exist_ok=True) + plist_path.write_text(generate_launchd_plist(), encoding="utf-8") + subprocess.run(["launchctl", "bootstrap", _launchd_domain(), str(plist_path)], check=True, timeout=30) + subprocess.run(["launchctl", "kickstart", f"{_launchd_domain()}/{label}"], check=True, timeout=30) + print("✓ Service started") + return + + refresh_launchd_plist_if_needed() + try: + subprocess.run(["launchctl", "kickstart", f"{_launchd_domain()}/{label}"], check=True, timeout=30) + except subprocess.CalledProcessError as e: + if e.returncode not in (3, 113): + raise + print("↻ launchd job was unloaded; reloading service definition") + subprocess.run(["launchctl", "bootstrap", _launchd_domain(), str(plist_path)], check=True, timeout=30) + subprocess.run(["launchctl", "kickstart", f"{_launchd_domain()}/{label}"], check=True, timeout=30) + print("✓ Service started") + +def launchd_stop(): + label = get_launchd_label() + target = f"{_launchd_domain()}/{label}" + # bootout unloads the service definition so KeepAlive doesn't respawn + # the process. A plain `kill SIGTERM` only signals the process — launchd + # immediately restarts it because KeepAlive.SuccessfulExit = false. + # `hermes gateway start` re-bootstraps when it detects the job is unloaded. + try: + subprocess.run(["launchctl", "bootout", target], check=True, timeout=90) + except subprocess.CalledProcessError as e: + if e.returncode in (3, 113): + pass # Already unloaded — nothing to stop. + else: + raise + _wait_for_gateway_exit(timeout=10.0, force_after=5.0) + print("✓ Service stopped") + +def _wait_for_gateway_exit(timeout: float = 10.0, force_after: float | None = 5.0) -> bool: + """Wait for the gateway process (by saved PID) to exit. + + Uses the PID from the gateway.pid file — not launchd labels — so this + works correctly when multiple gateway instances run under separate + HERMES_HOME directories. + + Args: + timeout: Total seconds to wait before giving up. + force_after: Seconds of graceful waiting before escalating to force-kill. + """ + import time + from gateway.status import get_running_pid + + deadline = time.monotonic() + timeout + force_deadline = (time.monotonic() + force_after) if force_after is not None else None + force_sent = False + + while time.monotonic() < deadline: + pid = get_running_pid() + if pid is None: + return True # Process exited cleanly. + + if force_after is not None and not force_sent and time.monotonic() >= force_deadline: + # Grace period expired — force-kill the specific PID. + try: + terminate_pid(pid, force=True) + print(f"⚠ Gateway PID {pid} did not exit gracefully; sent SIGKILL") + except (ProcessLookupError, PermissionError, OSError): + return True # Already gone or we can't touch it. + force_sent = True + + time.sleep(0.3) + + # Timed out even after force-kill. + remaining_pid = get_running_pid() + if remaining_pid is not None: + print(f"⚠ Gateway PID {remaining_pid} still running after {timeout}s — restart may fail") + return False + return True + + +def launchd_restart(): + label = get_launchd_label() + target = f"{_launchd_domain()}/{label}" + drain_timeout = _get_restart_drain_timeout() + from gateway.status import get_running_pid + + try: + pid = get_running_pid() + if pid is not None and _request_gateway_self_restart(pid): + print("✓ Service restart requested") + return + if pid is not None: + try: + terminate_pid(pid, force=False) + except (ProcessLookupError, PermissionError, OSError): + pid = None + if pid is not None: + exited = _wait_for_gateway_exit(timeout=drain_timeout, force_after=None) + if not exited: + print(f"⚠ Gateway drain timed out after {drain_timeout:.0f}s — forcing launchd restart") + subprocess.run(["launchctl", "kickstart", "-k", target], check=True, timeout=90) + print("✓ Service restarted") + except subprocess.CalledProcessError as e: + if e.returncode not in (3, 113): + raise + # Job not loaded — bootstrap and start fresh + print("↻ launchd job was unloaded; reloading") + plist_path = get_launchd_plist_path() + subprocess.run(["launchctl", "bootstrap", _launchd_domain(), str(plist_path)], check=True, timeout=30) + subprocess.run(["launchctl", "kickstart", target], check=True, timeout=30) + print("✓ Service restarted") + +def launchd_status(deep: bool = False): + plist_path = get_launchd_plist_path() + label = get_launchd_label() + try: + result = subprocess.run( + ["launchctl", "list", label], + capture_output=True, + text=True, + timeout=10, + ) + loaded = result.returncode == 0 + loaded_output = result.stdout + except subprocess.TimeoutExpired: + loaded = False + loaded_output = "" + + print(f"Launchd plist: {plist_path}") + if launchd_plist_is_current(): + print("✓ Service definition matches the current Hermes install") + else: + print("⚠ Service definition is stale relative to the current Hermes install") + print(" Run: hermes gateway start") + + if loaded: + print("✓ Gateway service is loaded") + print(loaded_output) + else: + print("✗ Gateway service is not loaded") + print(" Service definition exists locally but launchd has not loaded it.") + print(" Run: hermes gateway start") + + if deep: + log_file = get_hermes_home() / "logs" / "gateway.log" + if log_file.exists(): + print() + print("Recent logs:") + subprocess.run(["tail", "-20", str(log_file)], timeout=10) + + +# ============================================================================= +# Gateway Runner +# ============================================================================= + +def run_gateway(verbose: int = 0, quiet: bool = False, replace: bool = False): + """Run the gateway in foreground. + + Args: + verbose: Stderr log verbosity count added on top of default WARNING (0=WARNING, 1=INFO, 2+=DEBUG). + quiet: Suppress all stderr log output. + replace: If True, kill any existing gateway instance before starting. + This prevents systemd restart loops when the old process + hasn't fully exited yet. + """ + sys.path.insert(0, str(PROJECT_ROOT)) + + from gateway.run import start_gateway + + print("┌─────────────────────────────────────────────────────────┐") + print("│ ⚕ Hermes Gateway Starting... │") + print("├─────────────────────────────────────────────────────────┤") + print("│ Messaging platforms + cron scheduler │") + print("│ Press Ctrl+C to stop │") + print("└─────────────────────────────────────────────────────────┘") + print() + + # Exit with code 1 if gateway fails to connect any platform, + # so systemd Restart=on-failure will retry on transient errors + verbosity = None if quiet else verbose + success = asyncio.run(start_gateway(replace=replace, verbosity=verbosity)) + if not success: + sys.exit(1) + + +# ============================================================================= +# Gateway Setup (Interactive Messaging Platform Configuration) +# ============================================================================= + +# Per-platform config: each entry defines the env vars, setup instructions, +# and prompts needed to configure a messaging platform. +_PLATFORMS = [ + { + "key": "telegram", + "label": "Telegram", + "emoji": "📱", + "token_var": "TELEGRAM_BOT_TOKEN", + "setup_instructions": [ + "1. Open Telegram and message @BotFather", + "2. Send /newbot and follow the prompts to create your bot", + "3. Copy the bot token BotFather gives you", + "4. To find your user ID: message @userinfobot — it replies with your numeric ID", + ], + "vars": [ + {"name": "TELEGRAM_BOT_TOKEN", "prompt": "Bot token", "password": True, + "help": "Paste the token from @BotFather (step 3 above)."}, + {"name": "TELEGRAM_ALLOWED_USERS", "prompt": "Allowed user IDs (comma-separated)", "password": False, + "is_allowlist": True, + "help": "Paste your user ID from step 4 above."}, + {"name": "TELEGRAM_HOME_CHANNEL", "prompt": "Home channel ID (for cron/notification delivery, or empty to set later with /set-home)", "password": False, + "help": "For DMs, this is your user ID. You can set it later by typing /set-home in chat."}, + ], + }, + { + "key": "discord", + "label": "Discord", + "emoji": "💬", + "token_var": "DISCORD_BOT_TOKEN", + "setup_instructions": [ + "1. Go to https://discord.com/developers/applications → New Application", + "2. Go to Bot → Reset Token → copy the bot token", + "3. Enable: Bot → Privileged Gateway Intents → Message Content Intent", + "4. Invite the bot to your server:", + " OAuth2 → URL Generator → check BOTH scopes:", + " - bot", + " - applications.commands (required for slash commands!)", + " Bot Permissions: Send Messages, Read Message History, Attach Files", + " Copy the URL and open it in your browser to invite.", + "5. Get your user ID: enable Developer Mode in Discord settings,", + " then right-click your name → Copy ID", + ], + "vars": [ + {"name": "DISCORD_BOT_TOKEN", "prompt": "Bot token", "password": True, + "help": "Paste the token from step 2 above."}, + {"name": "DISCORD_ALLOWED_USERS", "prompt": "Allowed user IDs or usernames (comma-separated)", "password": False, + "is_allowlist": True, + "help": "Paste your user ID from step 5 above."}, + {"name": "DISCORD_HOME_CHANNEL", "prompt": "Home channel ID (for cron/notification delivery, or empty to set later with /set-home)", "password": False, + "help": "Right-click a channel → Copy Channel ID (requires Developer Mode)."}, + ], + }, + { + "key": "slack", + "label": "Slack", + "emoji": "💼", + "token_var": "SLACK_BOT_TOKEN", + "setup_instructions": [ + "1. Go to https://api.slack.com/apps → Create New App → From Scratch", + "2. Enable Socket Mode: Settings → Socket Mode → Enable", + " Create an App-Level Token with scope: connections:write → copy xapp-... token", + "3. Add Bot Token Scopes: Features → OAuth & Permissions → Scopes", + " Required: chat:write, app_mentions:read, channels:history, channels:read,", + " groups:history, im:history, im:read, im:write, users:read, files:read, files:write", + "4. Subscribe to Events: Features → Event Subscriptions → Enable", + " Required events: message.im, message.channels, app_mention", + " Optional: message.groups (for private channels)", + " ⚠ Without message.channels the bot will ONLY work in DMs!", + "5. Install to Workspace: Settings → Install App → copy xoxb-... token", + "6. Reinstall the app after any scope or event changes", + "7. Find your user ID: click your profile → three dots → Copy member ID", + "8. Invite the bot to channels: /invite @YourBot", + ], + "vars": [ + {"name": "SLACK_BOT_TOKEN", "prompt": "Bot Token (xoxb-...)", "password": True, + "help": "Paste the bot token from step 3 above."}, + {"name": "SLACK_APP_TOKEN", "prompt": "App Token (xapp-...)", "password": True, + "help": "Paste the app-level token from step 4 above."}, + {"name": "SLACK_ALLOWED_USERS", "prompt": "Allowed user IDs (comma-separated)", "password": False, + "is_allowlist": True, + "help": "Paste your member ID from step 7 above."}, + ], + }, + { + "key": "matrix", + "label": "Matrix", + "emoji": "🔐", + "token_var": "MATRIX_ACCESS_TOKEN", + "setup_instructions": [ + "1. Works with any Matrix homeserver (self-hosted Synapse/Conduit/Dendrite or matrix.org)", + "2. Create a bot user on your homeserver, or use your own account", + "3. Get an access token: Element → Settings → Help & About → Access Token", + " Or via API: curl -X POST https://your-server/_matrix/client/v3/login \\", + " -d '{\"type\":\"m.login.password\",\"user\":\"@bot:server\",\"password\":\"...\"}'", + "4. Alternatively, provide user ID + password and Hermes will log in directly", + "5. For E2EE: set MATRIX_ENCRYPTION=true (requires pip install 'mautrix[encryption]')", + "6. To find your user ID: it's @username:your-server (shown in Element profile)", + ], + "vars": [ + {"name": "MATRIX_HOMESERVER", "prompt": "Homeserver URL (e.g. https://matrix.example.org)", "password": False, + "help": "Your Matrix homeserver URL. Works with any self-hosted instance."}, + {"name": "MATRIX_ACCESS_TOKEN", "prompt": "Access token (leave empty to use password login instead)", "password": True, + "help": "Paste your access token, or leave empty and provide user ID + password below."}, + {"name": "MATRIX_USER_ID", "prompt": "User ID (@bot:server — required for password login)", "password": False, + "help": "Full Matrix user ID, e.g. @hermes:matrix.example.org"}, + {"name": "MATRIX_ALLOWED_USERS", "prompt": "Allowed user IDs (comma-separated, e.g. @you:server)", "password": False, + "is_allowlist": True, + "help": "Matrix user IDs who can interact with the bot."}, + {"name": "MATRIX_HOME_ROOM", "prompt": "Home room ID (for cron/notification delivery, or empty to set later with /set-home)", "password": False, + "help": "Room ID (e.g. !abc123:server) for delivering cron results and notifications."}, + ], + }, + { + "key": "mattermost", + "label": "Mattermost", + "emoji": "💬", + "token_var": "MATTERMOST_TOKEN", + "setup_instructions": [ + "1. In Mattermost: Integrations → Bot Accounts → Add Bot Account", + " (System Console → Integrations → Bot Accounts must be enabled)", + "2. Give it a username (e.g. hermes) and copy the bot token", + "3. Works with any self-hosted Mattermost instance — enter your server URL", + "4. To find your user ID: click your avatar (top-left) → Profile", + " Your user ID is displayed there — click it to copy.", + " ⚠ This is NOT your username — it's a 26-character alphanumeric ID.", + "5. To get a channel ID: click the channel name → View Info → copy the ID", + ], + "vars": [ + {"name": "MATTERMOST_URL", "prompt": "Server URL (e.g. https://mm.example.com)", "password": False, + "help": "Your Mattermost server URL. Works with any self-hosted instance."}, + {"name": "MATTERMOST_TOKEN", "prompt": "Bot token", "password": True, + "help": "Paste the bot token from step 2 above."}, + {"name": "MATTERMOST_ALLOWED_USERS", "prompt": "Allowed user IDs (comma-separated)", "password": False, + "is_allowlist": True, + "help": "Your Mattermost user ID from step 4 above."}, + {"name": "MATTERMOST_HOME_CHANNEL", "prompt": "Home channel ID (for cron/notification delivery, or empty to set later with /set-home)", "password": False, + "help": "Channel ID where Hermes delivers cron results and notifications."}, + {"name": "MATTERMOST_REPLY_MODE", "prompt": "Reply mode — 'off' for flat messages, 'thread' for threaded replies (default: off)", "password": False, + "help": "off = flat channel messages, thread = replies nest under your message."}, + ], + }, + { + "key": "whatsapp", + "label": "WhatsApp", + "emoji": "📲", + "token_var": "WHATSAPP_ENABLED", + }, + { + "key": "signal", + "label": "Signal", + "emoji": "📡", + "token_var": "SIGNAL_HTTP_URL", + }, + { + "key": "email", + "label": "Email", + "emoji": "📧", + "token_var": "EMAIL_ADDRESS", + "setup_instructions": [ + "1. Use a dedicated email account for your Hermes agent", + "2. For Gmail: enable 2FA, then create an App Password at", + " https://myaccount.google.com/apppasswords", + "3. For other providers: use your email password or app-specific password", + "4. IMAP must be enabled on your email account", + ], + "vars": [ + {"name": "EMAIL_ADDRESS", "prompt": "Email address", "password": False, + "help": "The email address Hermes will use (e.g., hermes@gmail.com)."}, + {"name": "EMAIL_PASSWORD", "prompt": "Email password (or app password)", "password": True, + "help": "For Gmail, use an App Password (not your regular password)."}, + {"name": "EMAIL_IMAP_HOST", "prompt": "IMAP host", "password": False, + "help": "e.g., imap.gmail.com for Gmail, outlook.office365.com for Outlook."}, + {"name": "EMAIL_SMTP_HOST", "prompt": "SMTP host", "password": False, + "help": "e.g., smtp.gmail.com for Gmail, smtp.office365.com for Outlook."}, + {"name": "EMAIL_ALLOWED_USERS", "prompt": "Allowed sender emails (comma-separated)", "password": False, + "is_allowlist": True, + "help": "Only emails from these addresses will be processed."}, + ], + }, + { + "key": "sms", + "label": "SMS (Twilio)", + "emoji": "📱", + "token_var": "TWILIO_ACCOUNT_SID", + "setup_instructions": [ + "1. Create a Twilio account at https://www.twilio.com/", + "2. Get your Account SID and Auth Token from the Twilio Console dashboard", + "3. Buy or configure a phone number capable of sending SMS", + "4. Set up your webhook URL for inbound SMS:", + " Twilio Console → Phone Numbers → Active Numbers → your number", + " → Messaging → A MESSAGE COMES IN → Webhook → https://your-server:8080/webhooks/twilio", + ], + "vars": [ + {"name": "TWILIO_ACCOUNT_SID", "prompt": "Twilio Account SID", "password": False, + "help": "Found on the Twilio Console dashboard."}, + {"name": "TWILIO_AUTH_TOKEN", "prompt": "Twilio Auth Token", "password": True, + "help": "Found on the Twilio Console dashboard (click to reveal)."}, + {"name": "TWILIO_PHONE_NUMBER", "prompt": "Twilio phone number (E.164 format, e.g. +15551234567)", "password": False, + "help": "The Twilio phone number to send SMS from."}, + {"name": "SMS_ALLOWED_USERS", "prompt": "Allowed phone numbers (comma-separated, E.164 format)", "password": False, + "is_allowlist": True, + "help": "Only messages from these phone numbers will be processed."}, + {"name": "SMS_HOME_CHANNEL", "prompt": "Home channel phone number (for cron/notification delivery, or empty)", "password": False, + "help": "Phone number to deliver cron job results and notifications to."}, + ], + }, + { + "key": "dingtalk", + "label": "DingTalk", + "emoji": "💬", + "token_var": "DINGTALK_CLIENT_ID", + "setup_instructions": [ + "1. Go to https://open-dev.dingtalk.com → Create Application", + "2. Under 'Credentials', copy the AppKey (Client ID) and AppSecret (Client Secret)", + "3. Enable 'Stream Mode' under the bot settings", + "4. Add the bot to a group chat or message it directly", + ], + "vars": [ + {"name": "DINGTALK_CLIENT_ID", "prompt": "AppKey (Client ID)", "password": False, + "help": "The AppKey from your DingTalk application credentials."}, + {"name": "DINGTALK_CLIENT_SECRET", "prompt": "AppSecret (Client Secret)", "password": True, + "help": "The AppSecret from your DingTalk application credentials."}, + ], + }, + { + "key": "feishu", + "label": "Feishu / Lark", + "emoji": "🪽", + "token_var": "FEISHU_APP_ID", + "setup_instructions": [ + "1. Go to https://open.feishu.cn/ (or https://open.larksuite.com/ for Lark)", + "2. Create an app and copy the App ID and App Secret", + "3. Enable the Bot capability for the app", + "4. Choose WebSocket (recommended) or Webhook connection mode", + "5. Add the bot to a group chat or message it directly", + "6. Restrict access with FEISHU_ALLOWED_USERS for production use", + ], + "vars": [ + {"name": "FEISHU_APP_ID", "prompt": "App ID", "password": False, + "help": "The App ID from your Feishu/Lark application."}, + {"name": "FEISHU_APP_SECRET", "prompt": "App Secret", "password": True, + "help": "The App Secret from your Feishu/Lark application."}, + {"name": "FEISHU_DOMAIN", "prompt": "Domain — feishu or lark (default: feishu)", "password": False, + "help": "Use 'feishu' for Feishu China, or 'lark' for Lark international."}, + {"name": "FEISHU_CONNECTION_MODE", "prompt": "Connection mode — websocket or webhook (default: websocket)", "password": False, + "help": "websocket is recommended unless you specifically need webhook mode."}, + {"name": "FEISHU_ALLOWED_USERS", "prompt": "Allowed user IDs (comma-separated, or empty)", "password": False, + "is_allowlist": True, + "help": "Restrict which Feishu/Lark users can interact with the bot."}, + {"name": "FEISHU_HOME_CHANNEL", "prompt": "Home chat ID (optional, for cron/notifications)", "password": False, + "help": "Chat ID for scheduled results and notifications."}, + ], + }, + { + "key": "wecom", + "label": "WeCom (Enterprise WeChat)", + "emoji": "💬", + "token_var": "WECOM_BOT_ID", + "setup_instructions": [ + "1. Go to WeCom Admin Console → Applications → Create AI Bot", + "2. Copy the Bot ID and Secret from the bot's credentials page", + "3. The bot connects via WebSocket — no public endpoint needed", + "4. Add the bot to a group chat or message it directly in WeCom", + "5. Restrict access with WECOM_ALLOWED_USERS for production use", + ], + "vars": [ + {"name": "WECOM_BOT_ID", "prompt": "Bot ID", "password": False, + "help": "The Bot ID from your WeCom AI Bot."}, + {"name": "WECOM_SECRET", "prompt": "Secret", "password": True, + "help": "The secret from your WeCom AI Bot."}, + {"name": "WECOM_ALLOWED_USERS", "prompt": "Allowed user IDs (comma-separated, or empty)", "password": False, + "is_allowlist": True, + "help": "Restrict which WeCom users can interact with the bot."}, + {"name": "WECOM_HOME_CHANNEL", "prompt": "Home chat ID (optional, for cron/notifications)", "password": False, + "help": "Chat ID for scheduled results and notifications."}, + ], + }, + { + "key": "wecom_callback", + "label": "WeCom Callback (Self-Built App)", + "emoji": "💬", + "token_var": "WECOM_CALLBACK_CORP_ID", + "setup_instructions": [ + "1. Go to WeCom Admin Console → Applications → Create Self-Built App", + "2. Note the Corp ID (top of admin console) and create a Corp Secret", + "3. Under Receive Messages, configure the callback URL to point to your server", + "4. Copy the Token and EncodingAESKey from the callback configuration", + "5. The adapter runs an HTTP server — ensure the port is reachable from WeCom", + "6. Restrict access with WECOM_CALLBACK_ALLOWED_USERS for production use", + ], + "vars": [ + {"name": "WECOM_CALLBACK_CORP_ID", "prompt": "Corp ID", "password": False, + "help": "Your WeCom enterprise Corp ID."}, + {"name": "WECOM_CALLBACK_CORP_SECRET", "prompt": "Corp Secret", "password": True, + "help": "The secret for your self-built application."}, + {"name": "WECOM_CALLBACK_AGENT_ID", "prompt": "Agent ID", "password": False, + "help": "The Agent ID of your self-built application."}, + {"name": "WECOM_CALLBACK_TOKEN", "prompt": "Callback Token", "password": True, + "help": "The Token from your WeCom callback configuration."}, + {"name": "WECOM_CALLBACK_ENCODING_AES_KEY", "prompt": "Encoding AES Key", "password": True, + "help": "The EncodingAESKey from your WeCom callback configuration."}, + {"name": "WECOM_CALLBACK_PORT", "prompt": "Callback server port (default: 8645)", "password": False, + "help": "Port for the HTTP callback server."}, + {"name": "WECOM_CALLBACK_ALLOWED_USERS", "prompt": "Allowed user IDs (comma-separated, or empty)", "password": False, + "is_allowlist": True, + "help": "Restrict which WeCom users can interact with the app."}, + ], + }, + { + "key": "weixin", + "label": "Weixin / WeChat", + "emoji": "💬", + "token_var": "WEIXIN_ACCOUNT_ID", + }, + { + "key": "bluebubbles", + "label": "BlueBubbles (iMessage)", + "emoji": "💬", + "token_var": "BLUEBUBBLES_SERVER_URL", + "setup_instructions": [ + "1. Install BlueBubbles on a Mac that will act as your iMessage server:", + " https://bluebubbles.app/", + "2. Complete the BlueBubbles setup wizard — sign in with your Apple ID", + "3. In BlueBubbles Settings → API, note the Server URL and password", + "4. The server URL is typically http://:1234", + "5. Hermes connects via the BlueBubbles REST API and receives", + " incoming messages via a local webhook", + "6. To authorize users, use DM pairing: hermes pairing generate bluebubbles", + " Share the code — the user sends it via iMessage to get approved", + ], + "vars": [ + {"name": "BLUEBUBBLES_SERVER_URL", "prompt": "BlueBubbles server URL (e.g. http://192.168.1.10:1234)", "password": False, + "help": "The URL shown in BlueBubbles Settings → API."}, + {"name": "BLUEBUBBLES_PASSWORD", "prompt": "BlueBubbles server password", "password": True, + "help": "The password shown in BlueBubbles Settings → API."}, + {"name": "BLUEBUBBLES_ALLOWED_USERS", "prompt": "Pre-authorized phone numbers or iMessage IDs (comma-separated, or leave empty for DM pairing)", "password": False, + "is_allowlist": True, + "help": "Optional — pre-authorize specific users. Leave empty to use DM pairing instead (recommended)."}, + {"name": "BLUEBUBBLES_HOME_CHANNEL", "prompt": "Home channel (phone number or iMessage ID for cron/notifications, or empty)", "password": False, + "help": "Phone number or Apple ID to deliver cron results and notifications to."}, + ], + }, + { + "key": "qqbot", + "label": "QQ Bot", + "emoji": "🐧", + "token_var": "QQ_APP_ID", + "setup_instructions": [ + "1. Register a QQ Bot application at q.qq.com", + "2. Note your App ID and App Secret from the application page", + "3. Enable the required intents (C2C, Group, Guild messages)", + "4. Configure sandbox or publish the bot", + ], + "vars": [ + {"name": "QQ_APP_ID", "prompt": "QQ Bot App ID", "password": False, + "help": "Your QQ Bot App ID from q.qq.com."}, + {"name": "QQ_CLIENT_SECRET", "prompt": "QQ Bot App Secret", "password": True, + "help": "Your QQ Bot App Secret from q.qq.com."}, + {"name": "QQ_ALLOWED_USERS", "prompt": "Allowed user OpenIDs (comma-separated, leave empty for open access)", "password": False, + "is_allowlist": True, + "help": "Optional — restrict DM access to specific user OpenIDs."}, + {"name": "QQ_HOME_CHANNEL", "prompt": "Home channel (user/group OpenID for cron delivery, or empty)", "password": False, + "help": "OpenID to deliver cron results and notifications to."}, + ], + }, +] + + +def _platform_status(platform: dict) -> str: + """Return a plain-text status string for a platform. + + Returns uncolored text so it can safely be embedded in + simple_term_menu items (ANSI codes break width calculation). + """ + token_var = platform["token_var"] + val = get_env_value(token_var) + if token_var == "WHATSAPP_ENABLED": + if val and val.lower() == "true": + session_file = get_hermes_home() / "whatsapp" / "session" / "creds.json" + if session_file.exists(): + return "configured + paired" + return "enabled, not paired" + return "not configured" + if platform.get("key") == "signal": + account = get_env_value("SIGNAL_ACCOUNT") + if val and account: + return "configured" + if val or account: + return "partially configured" + return "not configured" + if platform.get("key") == "email": + pwd = get_env_value("EMAIL_PASSWORD") + imap = get_env_value("EMAIL_IMAP_HOST") + smtp = get_env_value("EMAIL_SMTP_HOST") + if all([val, pwd, imap, smtp]): + return "configured" + if any([val, pwd, imap, smtp]): + return "partially configured" + return "not configured" + if platform.get("key") == "matrix": + homeserver = get_env_value("MATRIX_HOMESERVER") + password = get_env_value("MATRIX_PASSWORD") + if (val or password) and homeserver: + e2ee = get_env_value("MATRIX_ENCRYPTION") + suffix = " + E2EE" if e2ee and e2ee.lower() in ("true", "1", "yes") else "" + return f"configured{suffix}" + if val or password or homeserver: + return "partially configured" + return "not configured" + if platform.get("key") == "weixin": + token = get_env_value("WEIXIN_TOKEN") + if val and token: + return "configured" + if val or token: + return "partially configured" + return "not configured" + if val: + return "configured" + return "not configured" + + +def _runtime_health_lines() -> list[str]: + """Summarize the latest persisted gateway runtime health state.""" + try: + from gateway.status import read_runtime_status + except Exception: + return [] + + state = read_runtime_status() + if not state: + return [] + + lines: list[str] = [] + gateway_state = state.get("gateway_state") + exit_reason = state.get("exit_reason") + active_agents = state.get("active_agents") + restart_requested = state.get("restart_requested") + platforms = state.get("platforms", {}) or {} + + for platform, pdata in platforms.items(): + if pdata.get("state") == "fatal": + message = pdata.get("error_message") or "unknown error" + lines.append(f"⚠ {platform}: {message}") + + if gateway_state == "startup_failed" and exit_reason: + lines.append(f"⚠ Last startup issue: {exit_reason}") + elif gateway_state == "draining": + action = "restart" if restart_requested else "shutdown" + count = int(active_agents or 0) + lines.append(f"⏳ Gateway draining for {action} ({count} active agent(s))") + elif gateway_state == "stopped" and exit_reason: + lines.append(f"⚠ Last shutdown reason: {exit_reason}") + + return lines + + +def _setup_standard_platform(platform: dict): + """Interactive setup for Telegram, Discord, or Slack.""" + emoji = platform["emoji"] + label = platform["label"] + token_var = platform["token_var"] + + print() + print(color(f" ─── {emoji} {label} Setup ───", Colors.CYAN)) + + # Show step-by-step setup instructions if this platform has them + instructions = platform.get("setup_instructions") + if instructions: + print() + for line in instructions: + print_info(f" {line}") + + existing_token = get_env_value(token_var) + if existing_token: + print() + print_success(f"{label} is already configured.") + if not prompt_yes_no(f" Reconfigure {label}?", False): + return + + allowed_val_set = None # Track if user set an allowlist (for home channel offer) + + for var in platform["vars"]: + print() + print_info(f" {var['help']}") + existing = get_env_value(var["name"]) + if existing and var["name"] != token_var: + print_info(f" Current: {existing}") + + # Allowlist fields get special handling for the deny-by-default security model + if var.get("is_allowlist"): + print_info(" The gateway DENIES all users by default for security.") + print_info(" Enter user IDs to create an allowlist, or leave empty") + print_info(" and you'll be asked about open access next.") + value = prompt(f" {var['prompt']}", password=False) + if value: + cleaned = value.replace(" ", "") + # For Discord, strip common prefixes (user:123, <@123>, <@!123>) + if "DISCORD" in var["name"]: + parts = [] + for uid in cleaned.split(","): + uid = uid.strip() + if uid.startswith("<@") and uid.endswith(">"): + uid = uid.lstrip("<@!").rstrip(">") + if uid.lower().startswith("user:"): + uid = uid[5:] + if uid: + parts.append(uid) + cleaned = ",".join(parts) + save_env_value(var["name"], cleaned) + print_success(" Saved — only these users can interact with the bot.") + allowed_val_set = cleaned + else: + # No allowlist — ask about open access vs DM pairing + print() + access_choices = [ + "Enable open access (anyone can message the bot)", + "Use DM pairing (unknown users request access, you approve with 'hermes pairing approve')", + "Skip for now (bot will deny all users until configured)", + ] + access_idx = prompt_choice(" How should unauthorized users be handled?", access_choices, 1) + if access_idx == 0: + save_env_value("GATEWAY_ALLOW_ALL_USERS", "true") + print_warning(" Open access enabled — anyone can use your bot!") + elif access_idx == 1: + print_success(" DM pairing mode — users will receive a code to request access.") + print_info(" Approve with: hermes pairing approve ") + else: + print_info(" Skipped — configure later with 'hermes gateway setup'") + continue + + value = prompt(f" {var['prompt']}", password=var.get("password", False)) + if value: + save_env_value(var["name"], value) + print_success(f" Saved {var['name']}") + elif var["name"] == token_var: + print_warning(f" Skipped — {label} won't work without this.") + return + else: + print_info(" Skipped (can configure later)") + + # If an allowlist was set and home channel wasn't, offer to reuse + # the first user ID (common for Telegram DMs). + home_var = f"{label.upper()}_HOME_CHANNEL" + home_val = get_env_value(home_var) + if allowed_val_set and not home_val and label == "Telegram": + first_id = allowed_val_set.split(",")[0].strip() + if first_id and prompt_yes_no(f" Use your user ID ({first_id}) as the home channel?", True): + save_env_value(home_var, first_id) + print_success(f" Home channel set to {first_id}") + + print() + print_success(f"{emoji} {label} configured!") + + +def _setup_whatsapp(): + """Delegate to the existing WhatsApp setup flow.""" + from hermes_cli.main import cmd_whatsapp + import argparse + cmd_whatsapp(argparse.Namespace()) + + +def _setup_email(): + """Configure Email via the standard platform setup.""" + email_platform = next(p for p in _PLATFORMS if p["key"] == "email") + _setup_standard_platform(email_platform) + + +def _setup_sms(): + """Configure SMS (Twilio) via the standard platform setup.""" + sms_platform = next(p for p in _PLATFORMS if p["key"] == "sms") + _setup_standard_platform(sms_platform) + + +def _setup_dingtalk(): + """Configure DingTalk via the standard platform setup.""" + dingtalk_platform = next(p for p in _PLATFORMS if p["key"] == "dingtalk") + _setup_standard_platform(dingtalk_platform) + + +def _setup_wecom(): + """Configure WeCom (Enterprise WeChat) via the standard platform setup.""" + wecom_platform = next(p for p in _PLATFORMS if p["key"] == "wecom") + _setup_standard_platform(wecom_platform) + + +def _is_service_installed() -> bool: + """Check if the gateway is installed as a system service.""" + if supports_systemd_services(): + return get_systemd_unit_path(system=False).exists() or get_systemd_unit_path(system=True).exists() + elif is_macos(): + return get_launchd_plist_path().exists() + return False + + +def _is_service_running() -> bool: + """Check if the gateway service is currently running.""" + if supports_systemd_services(): + user_unit_exists = get_systemd_unit_path(system=False).exists() + system_unit_exists = get_systemd_unit_path(system=True).exists() + + if user_unit_exists: + try: + result = _run_systemctl( + ["is-active", get_service_name()], + system=False, capture_output=True, text=True, timeout=10, + ) + if result.stdout.strip() == "active": + return True + except (RuntimeError, subprocess.TimeoutExpired): + pass + + if system_unit_exists: + try: + result = _run_systemctl( + ["is-active", get_service_name()], + system=True, capture_output=True, text=True, timeout=10, + ) + if result.stdout.strip() == "active": + return True + except (RuntimeError, subprocess.TimeoutExpired): + pass + + return False + elif is_macos() and get_launchd_plist_path().exists(): + try: + result = subprocess.run( + ["launchctl", "list", get_launchd_label()], + capture_output=True, text=True, timeout=10, + ) + return result.returncode == 0 + except subprocess.TimeoutExpired: + return False + # Check for manual processes + return len(find_gateway_pids()) > 0 + + +def _setup_weixin(): + """Interactive setup for Weixin / WeChat personal accounts.""" + print() + print(color(" ─── 💬 Weixin / WeChat Setup ───", Colors.CYAN)) + print() + print_info(" 1. Hermes will open Tencent iLink QR login in this terminal.") + print_info(" 2. Use WeChat to scan and confirm the QR code.") + print_info(" 3. Hermes will store the returned account_id/token in ~/.hermes/.env.") + print_info(" 4. This adapter supports native text, image, video, and document delivery.") + + existing_account = get_env_value("WEIXIN_ACCOUNT_ID") + existing_token = get_env_value("WEIXIN_TOKEN") + if existing_account and existing_token: + print() + print_success("Weixin is already configured.") + if not prompt_yes_no(" Reconfigure Weixin?", False): + return + + try: + from gateway.platforms.weixin import check_weixin_requirements, qr_login + except Exception as exc: + print_error(f" Weixin adapter import failed: {exc}") + print_info(" Install gateway dependencies first, then retry.") + return + + if not check_weixin_requirements(): + print_error(" Missing dependencies: Weixin needs aiohttp and cryptography.") + print_info(" Install them, then rerun `hermes gateway setup`.") + return + + print() + if not prompt_yes_no(" Start QR login now?", True): + print_info(" Cancelled.") + return + + import asyncio + try: + credentials = asyncio.run(qr_login(str(get_hermes_home()))) + except KeyboardInterrupt: + print() + print_warning(" Weixin setup cancelled.") + return + except Exception as exc: + print_error(f" QR login failed: {exc}") + return + + if not credentials: + print_warning(" QR login did not complete.") + return + + account_id = credentials.get("account_id", "") + token = credentials.get("token", "") + base_url = credentials.get("base_url", "") + user_id = credentials.get("user_id", "") + + save_env_value("WEIXIN_ACCOUNT_ID", account_id) + save_env_value("WEIXIN_TOKEN", token) + if base_url: + save_env_value("WEIXIN_BASE_URL", base_url) + save_env_value("WEIXIN_CDN_BASE_URL", get_env_value("WEIXIN_CDN_BASE_URL") or "https://novac2c.cdn.weixin.qq.com/c2c") + + print() + access_choices = [ + "Use DM pairing approval (recommended)", + "Allow all direct messages", + "Only allow listed user IDs", + "Disable direct messages", + ] + access_idx = prompt_choice(" How should direct messages be authorized?", access_choices, 0) + if access_idx == 0: + save_env_value("WEIXIN_DM_POLICY", "pairing") + save_env_value("WEIXIN_ALLOW_ALL_USERS", "false") + save_env_value("WEIXIN_ALLOWED_USERS", "") + print_success(" DM pairing enabled.") + print_info(" Unknown DM users can request access and you approve them with `hermes pairing approve`.") + elif access_idx == 1: + save_env_value("WEIXIN_DM_POLICY", "open") + save_env_value("WEIXIN_ALLOW_ALL_USERS", "true") + save_env_value("WEIXIN_ALLOWED_USERS", "") + print_warning(" Open DM access enabled for Weixin.") + elif access_idx == 2: + default_allow = user_id or "" + allowlist = prompt(" Allowed Weixin user IDs (comma-separated)", default_allow, password=False).replace(" ", "") + save_env_value("WEIXIN_DM_POLICY", "allowlist") + save_env_value("WEIXIN_ALLOW_ALL_USERS", "false") + save_env_value("WEIXIN_ALLOWED_USERS", allowlist) + print_success(" Weixin allowlist saved.") + else: + save_env_value("WEIXIN_DM_POLICY", "disabled") + save_env_value("WEIXIN_ALLOW_ALL_USERS", "false") + save_env_value("WEIXIN_ALLOWED_USERS", "") + print_warning(" Direct messages disabled.") + + print() + group_choices = [ + "Disable group chats (recommended)", + "Allow all group chats", + "Only allow listed group chat IDs", + ] + group_idx = prompt_choice(" How should group chats be handled?", group_choices, 0) + if group_idx == 0: + save_env_value("WEIXIN_GROUP_POLICY", "disabled") + save_env_value("WEIXIN_GROUP_ALLOWED_USERS", "") + print_info(" Group chats disabled.") + elif group_idx == 1: + save_env_value("WEIXIN_GROUP_POLICY", "open") + save_env_value("WEIXIN_GROUP_ALLOWED_USERS", "") + print_warning(" All group chats enabled.") + else: + allow_groups = prompt(" Allowed group chat IDs (comma-separated)", "", password=False).replace(" ", "") + save_env_value("WEIXIN_GROUP_POLICY", "allowlist") + save_env_value("WEIXIN_GROUP_ALLOWED_USERS", allow_groups) + print_success(" Group allowlist saved.") + + if user_id: + print() + if prompt_yes_no(f" Use your Weixin user ID ({user_id}) as the home channel?", True): + save_env_value("WEIXIN_HOME_CHANNEL", user_id) + print_success(f" Home channel set to {user_id}") + + print() + print_success("Weixin configured!") + print_info(f" Account ID: {account_id}") + if user_id: + print_info(f" User ID: {user_id}") + + +def _setup_feishu(): + """Interactive setup for Feishu / Lark — scan-to-create or manual credentials.""" + print() + print(color(" ─── 🪽 Feishu / Lark Setup ───", Colors.CYAN)) + + existing_app_id = get_env_value("FEISHU_APP_ID") + existing_secret = get_env_value("FEISHU_APP_SECRET") + if existing_app_id and existing_secret: + print() + print_success("Feishu / Lark is already configured.") + if not prompt_yes_no(" Reconfigure Feishu / Lark?", False): + return + + # ── Choose setup method ── + print() + method_choices = [ + "Scan QR code to create a new bot automatically (recommended)", + "Enter existing App ID and App Secret manually", + ] + method_idx = prompt_choice(" How would you like to set up Feishu / Lark?", method_choices, 0) + + credentials = None + used_qr = False + + if method_idx == 0: + # ── QR scan-to-create ── + try: + from gateway.platforms.feishu import qr_register + except Exception as exc: + print_error(f" Feishu / Lark onboard import failed: {exc}") + qr_register = None + + if qr_register is not None: + try: + credentials = qr_register() + except KeyboardInterrupt: + print() + print_warning(" Feishu / Lark setup cancelled.") + return + except Exception as exc: + print_warning(f" QR registration failed: {exc}") + if credentials: + used_qr = True + if not credentials: + print_info(" QR setup did not complete. Continuing with manual input.") + + # ── Manual credential input ── + if not credentials: + print() + print_info(" Go to https://open.feishu.cn/ (or https://open.larksuite.com/ for Lark)") + print_info(" Create an app, enable the Bot capability, and copy the credentials.") + print() + app_id = prompt(" App ID", password=False) + if not app_id: + print_warning(" Skipped — Feishu / Lark won't work without an App ID.") + return + app_secret = prompt(" App Secret", password=True) + if not app_secret: + print_warning(" Skipped — Feishu / Lark won't work without an App Secret.") + return + + domain_choices = ["feishu (China)", "lark (International)"] + domain_idx = prompt_choice(" Domain", domain_choices, 0) + domain = "lark" if domain_idx == 1 else "feishu" + + # Try to probe the bot with manual credentials + bot_name = None + try: + from gateway.platforms.feishu import probe_bot + bot_info = probe_bot(app_id, app_secret, domain) + if bot_info: + bot_name = bot_info.get("bot_name") + print_success(f" Credentials verified — bot: {bot_name or 'unnamed'}") + else: + print_warning(" Could not verify bot connection. Credentials saved anyway.") + except Exception as exc: + print_warning(f" Credential verification skipped: {exc}") + + credentials = { + "app_id": app_id, + "app_secret": app_secret, + "domain": domain, + "open_id": None, + "bot_name": bot_name, + } + + # ── Save core credentials ── + app_id = credentials["app_id"] + app_secret = credentials["app_secret"] + domain = credentials.get("domain", "feishu") + open_id = credentials.get("open_id") + bot_name = credentials.get("bot_name") + + save_env_value("FEISHU_APP_ID", app_id) + save_env_value("FEISHU_APP_SECRET", app_secret) + save_env_value("FEISHU_DOMAIN", domain) + # Bot identity is resolved at runtime via _hydrate_bot_identity(). + + # ── Connection mode ── + if used_qr: + connection_mode = "websocket" + else: + print() + mode_choices = [ + "WebSocket (recommended — no public URL needed)", + "Webhook (requires a reachable HTTP endpoint)", + ] + mode_idx = prompt_choice(" Connection mode", mode_choices, 0) + connection_mode = "webhook" if mode_idx == 1 else "websocket" + if connection_mode == "webhook": + print_info(" Webhook defaults: 127.0.0.1:8765/feishu/webhook") + print_info(" Override with FEISHU_WEBHOOK_HOST / FEISHU_WEBHOOK_PORT / FEISHU_WEBHOOK_PATH") + print_info(" For signature verification, set FEISHU_ENCRYPT_KEY and FEISHU_VERIFICATION_TOKEN") + save_env_value("FEISHU_CONNECTION_MODE", connection_mode) + + if bot_name: + print() + print_success(f" Bot created: {bot_name}") + + # ── DM security policy ── + print() + access_choices = [ + "Use DM pairing approval (recommended)", + "Allow all direct messages", + "Only allow listed user IDs", + ] + access_idx = prompt_choice(" How should direct messages be authorized?", access_choices, 0) + if access_idx == 0: + save_env_value("FEISHU_ALLOW_ALL_USERS", "false") + save_env_value("FEISHU_ALLOWED_USERS", "") + print_success(" DM pairing enabled.") + print_info(" Unknown users can request access; approve with `hermes pairing approve`.") + elif access_idx == 1: + save_env_value("FEISHU_ALLOW_ALL_USERS", "true") + save_env_value("FEISHU_ALLOWED_USERS", "") + print_warning(" Open DM access enabled for Feishu / Lark.") + else: + save_env_value("FEISHU_ALLOW_ALL_USERS", "false") + default_allow = open_id or "" + allowlist = prompt(" Allowed user IDs (comma-separated)", default_allow, password=False).replace(" ", "") + save_env_value("FEISHU_ALLOWED_USERS", allowlist) + print_success(" Allowlist saved.") + + # ── Group policy ── + print() + group_choices = [ + "Respond only when @mentioned in groups (recommended)", + "Disable group chats", + ] + group_idx = prompt_choice(" How should group chats be handled?", group_choices, 0) + if group_idx == 0: + save_env_value("FEISHU_GROUP_POLICY", "open") + print_info(" Group chats enabled (bot must be @mentioned).") + else: + save_env_value("FEISHU_GROUP_POLICY", "disabled") + print_info(" Group chats disabled.") + + # ── Home channel ── + print() + home_channel = prompt(" Home chat ID (optional, for cron/notifications)", password=False) + if home_channel: + save_env_value("FEISHU_HOME_CHANNEL", home_channel) + print_success(f" Home channel set to {home_channel}") + + print() + print_success("🪽 Feishu / Lark configured!") + print_info(f" App ID: {app_id}") + print_info(f" Domain: {domain}") + if bot_name: + print_info(f" Bot: {bot_name}") + + +def _setup_signal(): + """Interactive setup for Signal messenger.""" + import shutil + + print() + print(color(" ─── 📡 Signal Setup ───", Colors.CYAN)) + + existing_url = get_env_value("SIGNAL_HTTP_URL") + existing_account = get_env_value("SIGNAL_ACCOUNT") + if existing_url and existing_account: + print() + print_success("Signal is already configured.") + if not prompt_yes_no(" Reconfigure Signal?", False): + return + + # Check if signal-cli is available + print() + if shutil.which("signal-cli"): + print_success("signal-cli found on PATH.") + else: + print_warning("signal-cli not found on PATH.") + print_info(" Signal requires signal-cli running as an HTTP daemon.") + print_info(" Install options:") + print_info(" Linux: download from https://github.com/AsamK/signal-cli/releases") + print_info(" macOS: brew install signal-cli") + print_info(" Docker: bbernhard/signal-cli-rest-api") + print() + print_info(" After installing, link your account and start the daemon:") + print_info(" signal-cli link -n \"HermesAgent\"") + print_info(" signal-cli --account +YOURNUMBER daemon --http 127.0.0.1:8080") + print() + + # HTTP URL + print() + print_info(" Enter the URL where signal-cli HTTP daemon is running.") + default_url = existing_url or "http://127.0.0.1:8080" + try: + url = input(f" HTTP URL [{default_url}]: ").strip() or default_url + except (EOFError, KeyboardInterrupt): + print("\n Setup cancelled.") + return + + # Test connectivity + print_info(" Testing connection...") + try: + import httpx + resp = httpx.get(f"{url.rstrip('/')}/api/v1/check", timeout=10.0) + if resp.status_code == 200: + print_success(" signal-cli daemon is reachable!") + else: + print_warning(f" signal-cli responded with status {resp.status_code}.") + if not prompt_yes_no(" Continue anyway?", False): + return + except Exception as e: + print_warning(f" Could not reach signal-cli at {url}: {e}") + if not prompt_yes_no(" Save this URL anyway? (you can start signal-cli later)", True): + return + + save_env_value("SIGNAL_HTTP_URL", url) + + # Account phone number + print() + print_info(" Enter your Signal account phone number in E.164 format.") + print_info(" Example: +15551234567") + default_account = existing_account or "" + try: + account = input(f" Account number{f' [{default_account}]' if default_account else ''}: ").strip() + if not account: + account = default_account + except (EOFError, KeyboardInterrupt): + print("\n Setup cancelled.") + return + + if not account: + print_error(" Account number is required.") + return + + save_env_value("SIGNAL_ACCOUNT", account) + + # Allowed users + print() + print_info(" The gateway DENIES all users by default for security.") + print_info(" Enter phone numbers or UUIDs of allowed users (comma-separated).") + existing_allowed = get_env_value("SIGNAL_ALLOWED_USERS") or "" + default_allowed = existing_allowed or account + try: + allowed = input(f" Allowed users [{default_allowed}]: ").strip() or default_allowed + except (EOFError, KeyboardInterrupt): + print("\n Setup cancelled.") + return + + save_env_value("SIGNAL_ALLOWED_USERS", allowed) + + # Group messaging + print() + if prompt_yes_no(" Enable group messaging? (disabled by default for security)", False): + print() + print_info(" Enter group IDs to allow, or * for all groups.") + existing_groups = get_env_value("SIGNAL_GROUP_ALLOWED_USERS") or "" + try: + groups = input(f" Group IDs [{existing_groups or '*'}]: ").strip() or existing_groups or "*" + except (EOFError, KeyboardInterrupt): + print("\n Setup cancelled.") + return + save_env_value("SIGNAL_GROUP_ALLOWED_USERS", groups) + + print() + print_success("Signal configured!") + print_info(f" URL: {url}") + print_info(f" Account: {account}") + print_info(" DM auth: via SIGNAL_ALLOWED_USERS + DM pairing") + print_info(f" Groups: {'enabled' if get_env_value('SIGNAL_GROUP_ALLOWED_USERS') else 'disabled'}") + + +def gateway_setup(): + """Interactive setup for messaging platforms + gateway service.""" + if is_managed(): + managed_error("run gateway setup") + return + + print() + print(color("┌─────────────────────────────────────────────────────────┐", Colors.MAGENTA)) + print(color("│ ⚕ Gateway Setup │", Colors.MAGENTA)) + print(color("├─────────────────────────────────────────────────────────┤", Colors.MAGENTA)) + print(color("│ Configure messaging platforms and the gateway service. │", Colors.MAGENTA)) + print(color("│ Press Ctrl+C at any time to exit. │", Colors.MAGENTA)) + print(color("└─────────────────────────────────────────────────────────┘", Colors.MAGENTA)) + + # ── Gateway service status ── + print() + service_installed = _is_service_installed() + service_running = _is_service_running() + + if supports_systemd_services() and has_conflicting_systemd_units(): + print_systemd_scope_conflict_warning() + print() + + if service_installed and service_running: + print_success("Gateway service is installed and running.") + elif service_installed: + print_warning("Gateway service is installed but not running.") + if prompt_yes_no(" Start it now?", True): + try: + if supports_systemd_services(): + systemd_start() + elif is_macos(): + launchd_start() + except subprocess.CalledProcessError as e: + print_error(f" Failed to start: {e}") + else: + print_info("Gateway service is not installed yet.") + print_info("You'll be offered to install it after configuring platforms.") + + # ── Platform configuration loop ── + while True: + print() + print_header("Messaging Platforms") + + menu_items = [] + for plat in _PLATFORMS: + status = _platform_status(plat) + menu_items.append(f"{plat['label']} ({status})") + menu_items.append("Done") + + choice = prompt_choice("Select a platform to configure:", menu_items, len(menu_items) - 1) + + if choice == len(_PLATFORMS): + break + + platform = _PLATFORMS[choice] + + if platform["key"] == "whatsapp": + _setup_whatsapp() + elif platform["key"] == "signal": + _setup_signal() + elif platform["key"] == "weixin": + _setup_weixin() + elif platform["key"] == "feishu": + _setup_feishu() + else: + _setup_standard_platform(platform) + + # ── Post-setup: offer to install/restart gateway ── + any_configured = any( + bool(get_env_value(p["token_var"])) + for p in _PLATFORMS + if p["key"] != "whatsapp" + ) or (get_env_value("WHATSAPP_ENABLED") or "").lower() == "true" + + if any_configured: + print() + print(color("─" * 58, Colors.DIM)) + service_installed = _is_service_installed() + service_running = _is_service_running() + + if service_running: + if prompt_yes_no(" Restart the gateway to pick up changes?", True): + try: + if supports_systemd_services(): + systemd_restart() + elif is_macos(): + launchd_restart() + else: + stop_profile_gateway() + print_info("Start manually: hermes gateway") + except subprocess.CalledProcessError as e: + print_error(f" Restart failed: {e}") + elif service_installed: + if prompt_yes_no(" Start the gateway service?", True): + try: + if supports_systemd_services(): + systemd_start() + elif is_macos(): + launchd_start() + except subprocess.CalledProcessError as e: + print_error(f" Start failed: {e}") + else: + print() + if supports_systemd_services() or is_macos(): + platform_name = "systemd" if supports_systemd_services() else "launchd" + wsl_note = " (note: services may not survive WSL restarts)" if is_wsl() else "" + if prompt_yes_no(f" Install the gateway as a {platform_name} service?{wsl_note} (runs in background, starts on boot)", True): + try: + installed_scope = None + did_install = False + if supports_systemd_services(): + installed_scope, did_install = install_linux_gateway_from_setup(force=False) + else: + launchd_install(force=False) + did_install = True + print() + if did_install and prompt_yes_no(" Start the service now?", True): + try: + if supports_systemd_services(): + systemd_start(system=installed_scope == "system") + else: + launchd_start() + except subprocess.CalledProcessError as e: + print_error(f" Start failed: {e}") + except subprocess.CalledProcessError as e: + print_error(f" Install failed: {e}") + print_info(" You can try manually: hermes gateway install") + else: + print_info(" You can install later: hermes gateway install") + if supports_systemd_services(): + print_info(" Or as a boot-time service: sudo hermes gateway install --system") + print_info(" Or run in foreground: hermes gateway run") + elif is_wsl(): + print_info(" WSL detected but systemd is not running.") + print_info(" Run in foreground: hermes gateway run") + print_info(" For persistence: tmux new -s hermes 'hermes gateway run'") + print_info(" To enable systemd: add systemd=true to /etc/wsl.conf, then 'wsl --shutdown'") + else: + if is_termux(): + from hermes_constants import display_hermes_home as _dhh + print_info(" Termux does not use systemd/launchd services.") + print_info(" Run in foreground: hermes gateway run") + print_info(f" Or start it manually in the background (best effort): nohup hermes gateway run >{_dhh()}/logs/gateway.log 2>&1 &") + else: + print_info(" Service install not supported on this platform.") + print_info(" Run in foreground: hermes gateway run") + else: + print() + print_info("No platforms configured. Run 'hermes gateway setup' when ready.") + + print() + + +# ============================================================================= +# Main Command Handler +# ============================================================================= + +def gateway_command(args): + """Handle gateway subcommands.""" + subcmd = getattr(args, 'gateway_command', None) + + # Default to run if no subcommand + if subcmd is None or subcmd == "run": + verbose = getattr(args, 'verbose', 0) + quiet = getattr(args, 'quiet', False) + replace = getattr(args, 'replace', False) + run_gateway(verbose, quiet=quiet, replace=replace) + return + + if subcmd == "setup": + gateway_setup() + return + + # Service management commands + if subcmd == "install": + if is_managed(): + managed_error("install gateway service (managed by NixOS)") + return + force = getattr(args, 'force', False) + system = getattr(args, 'system', False) + run_as_user = getattr(args, 'run_as_user', None) + if is_termux(): + print("Gateway service installation is not supported on Termux.") + print("Run manually: hermes gateway") + sys.exit(1) + if supports_systemd_services(): + if is_wsl(): + print_warning("WSL detected — systemd services may not survive WSL restarts.") + print_info(" Consider running in foreground instead: hermes gateway run") + print_info(" Or use tmux/screen for persistence: tmux new -s hermes 'hermes gateway run'") + print() + systemd_install(force=force, system=system, run_as_user=run_as_user) + elif is_macos(): + launchd_install(force) + elif is_wsl(): + print("WSL detected but systemd is not running.") + print("Either enable systemd (add systemd=true to /etc/wsl.conf and restart WSL)") + print("or run the gateway in foreground mode:") + print() + print(" hermes gateway run # direct foreground") + print(" tmux new -s hermes 'hermes gateway run' # persistent via tmux") + print(" nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 & # background") + sys.exit(1) + elif is_container(): + print("Service installation is not needed inside a Docker container.") + print("The container runtime is your service manager — use Docker restart policies instead:") + print() + print(" docker run --restart unless-stopped ... # auto-restart on crash/reboot") + print(" docker restart # manual restart") + print() + print("To run the gateway: hermes gateway run") + sys.exit(0) + else: + print("Service installation not supported on this platform.") + print("Run manually: hermes gateway run") + sys.exit(1) + + elif subcmd == "uninstall": + if is_managed(): + managed_error("uninstall gateway service (managed by NixOS)") + return + system = getattr(args, 'system', False) + if is_termux(): + print("Gateway service uninstall is not supported on Termux because there is no managed service to remove.") + print("Stop manual runs with: hermes gateway stop") + sys.exit(1) + if supports_systemd_services(): + systemd_uninstall(system=system) + elif is_macos(): + launchd_uninstall() + elif is_container(): + print("Service uninstall is not applicable inside a Docker container.") + print("To stop the gateway, stop or remove the container:") + print() + print(" docker stop ") + print(" docker rm ") + sys.exit(0) + else: + print("Not supported on this platform.") + sys.exit(1) + + elif subcmd == "start": + system = getattr(args, 'system', False) + if is_termux(): + print("Gateway service start is not supported on Termux because there is no system service manager.") + print("Run manually: hermes gateway") + sys.exit(1) + if supports_systemd_services(): + systemd_start(system=system) + elif is_macos(): + launchd_start() + elif is_wsl(): + print("WSL detected but systemd is not available.") + print("Run the gateway in foreground mode instead:") + print() + print(" hermes gateway run # direct foreground") + print(" tmux new -s hermes 'hermes gateway run' # persistent via tmux") + print(" nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 & # background") + print() + print("To enable systemd: add systemd=true to /etc/wsl.conf and run 'wsl --shutdown' from PowerShell.") + sys.exit(1) + elif is_container(): + print("Service start is not applicable inside a Docker container.") + print("The gateway runs as the container's main process.") + print() + print(" docker start # start a stopped container") + print(" docker restart # restart a running container") + print() + print("Or run the gateway directly: hermes gateway run") + sys.exit(0) + else: + print("Not supported on this platform.") + sys.exit(1) + + elif subcmd == "stop": + stop_all = getattr(args, 'all', False) + system = getattr(args, 'system', False) + + if stop_all: + # --all: kill every gateway process on the machine + service_available = False + if supports_systemd_services() and (get_systemd_unit_path(system=False).exists() or get_systemd_unit_path(system=True).exists()): + try: + systemd_stop(system=system) + service_available = True + except subprocess.CalledProcessError: + pass + elif is_macos() and get_launchd_plist_path().exists(): + try: + launchd_stop() + service_available = True + except subprocess.CalledProcessError: + pass + killed = kill_gateway_processes(all_profiles=True) + total = killed + (1 if service_available else 0) + if total: + print(f"✓ Stopped {total} gateway process(es) across all profiles") + else: + print("✗ No gateway processes found") + else: + # Default: stop only the current profile's gateway + service_available = False + if supports_systemd_services() and (get_systemd_unit_path(system=False).exists() or get_systemd_unit_path(system=True).exists()): + try: + systemd_stop(system=system) + service_available = True + except subprocess.CalledProcessError: + pass + elif is_macos() and get_launchd_plist_path().exists(): + try: + launchd_stop() + service_available = True + except subprocess.CalledProcessError: + pass + + if not service_available: + # No systemd/launchd — use profile-scoped PID file + if stop_profile_gateway(): + print("✓ Stopped gateway for this profile") + else: + print("✗ No gateway running for this profile") + else: + print(f"✓ Stopped {get_service_name()} service") + + elif subcmd == "restart": + # Try service first, fall back to killing and restarting + service_available = False + system = getattr(args, 'system', False) + service_configured = False + + if supports_systemd_services() and (get_systemd_unit_path(system=False).exists() or get_systemd_unit_path(system=True).exists()): + service_configured = True + try: + systemd_restart(system=system) + service_available = True + except subprocess.CalledProcessError: + pass + elif is_macos() and get_launchd_plist_path().exists(): + service_configured = True + try: + launchd_restart() + service_available = True + except subprocess.CalledProcessError: + pass + + if not service_available: + # systemd/launchd restart failed — check if linger is the issue + if supports_systemd_services(): + linger_ok, _detail = get_systemd_linger_status() + if linger_ok is not True: + import getpass + _username = getpass.getuser() + print() + print("⚠ Cannot restart gateway as a service — linger is not enabled.") + print(" The gateway user service requires linger to function on headless servers.") + print() + print(f" Run: sudo loginctl enable-linger {_username}") + print() + print(" Then restart the gateway:") + print(" hermes gateway restart") + return + + if service_configured: + print() + print("✗ Gateway service restart failed.") + print(" The service definition exists, but the service manager did not recover it.") + print(" Fix the service, then retry: hermes gateway start") + sys.exit(1) + + # Manual restart: stop only this profile's gateway + if stop_profile_gateway(): + print("✓ Stopped gateway for this profile") + + _wait_for_gateway_exit(timeout=10.0, force_after=5.0) + + # Start fresh + print("Starting gateway...") + run_gateway(verbose=0) + + elif subcmd == "status": + deep = getattr(args, 'deep', False) + system = getattr(args, 'system', False) + + # Check for service first + if supports_systemd_services() and (get_systemd_unit_path(system=False).exists() or get_systemd_unit_path(system=True).exists()): + systemd_status(deep, system=system) + elif is_macos() and get_launchd_plist_path().exists(): + launchd_status(deep) + else: + # Check for manually running processes + pids = find_gateway_pids() + if pids: + print(f"✓ Gateway is running (PID: {', '.join(map(str, pids))})") + print(" (Running manually, not as a system service)") + runtime_lines = _runtime_health_lines() + if runtime_lines: + print() + print("Recent gateway health:") + for line in runtime_lines: + print(f" {line}") + print() + if is_termux(): + print("Termux note:") + print(" Android may stop background jobs when Termux is suspended") + elif is_wsl(): + print("WSL note:") + print(" The gateway is running in foreground/manual mode (recommended for WSL).") + print(" Use tmux or screen for persistence across terminal closes.") + else: + print("To install as a service:") + print(" hermes gateway install") + print(" sudo hermes gateway install --system") + else: + print("✗ Gateway is not running") + runtime_lines = _runtime_health_lines() + if runtime_lines: + print() + print("Recent gateway health:") + for line in runtime_lines: + print(f" {line}") + print() + print("To start:") + print(" hermes gateway run # Run in foreground") + if is_termux(): + print(" nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 & # Best-effort background start") + elif is_wsl(): + print(" tmux new -s hermes 'hermes gateway run' # persistent via tmux") + print(" nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 & # background") + else: + print(" hermes gateway install # Install as user service") + print(" sudo hermes gateway install --system # Install as boot-time system service") diff --git a/mindcli/_vendor/hermes_cli/logs.py b/mindcli/_vendor/hermes_cli/logs.py new file mode 100644 index 0000000..9a829a4 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/logs.py @@ -0,0 +1,390 @@ +"""``hermes logs`` — view and filter Hermes log files. + +Supports tailing, following, session filtering, level filtering, +component filtering, and relative time ranges. All log files live +under ``~/.hermes/logs/``. + +Usage examples:: + + hermes logs # last 50 lines of agent.log + hermes logs -f # follow agent.log in real time + hermes logs errors # last 50 lines of errors.log + hermes logs gateway -n 100 # last 100 lines of gateway.log + hermes logs --level WARNING # only WARNING+ lines + hermes logs --session abc123 # filter by session ID substring + hermes logs --component tools # only tool-related lines + hermes logs --since 1h # lines from the last hour + hermes logs --since 30m -f # follow, starting 30 min ago +""" + +import re +import sys +import time +from datetime import datetime, timedelta +from pathlib import Path +from typing import Optional, Sequence + +from hermes_constants import get_hermes_home, display_hermes_home + +# Known log files (name → filename) +LOG_FILES = { + "agent": "agent.log", + "errors": "errors.log", + "gateway": "gateway.log", +} + +# Log line timestamp regex — matches "2026-04-05 22:35:00,123" or +# "2026-04-05 22:35:00" at the start of a line. +_TS_RE = re.compile(r"^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2})") + +# Level extraction — matches " INFO ", " WARNING ", " ERROR ", " DEBUG ", " CRITICAL " +_LEVEL_RE = re.compile(r"\s(DEBUG|INFO|WARNING|ERROR|CRITICAL)\s") + +# Logger name extraction — after level and optional session tag, the next +# non-space token before ":" is the logger name. +# Matches: "INFO gateway.run:" or "INFO [sess_abc] tools.terminal_tool:" +_LOGGER_NAME_RE = re.compile( + r"\s(?:DEBUG|INFO|WARNING|ERROR|CRITICAL)" # level + r"(?:\s+\[.*?\])?" # optional session tag + r"\s+(\S+):" # logger name +) + +# Level ordering for >= filtering +_LEVEL_ORDER = {"DEBUG": 0, "INFO": 1, "WARNING": 2, "ERROR": 3, "CRITICAL": 4} + + +def _parse_since(since_str: str) -> Optional[datetime]: + """Parse a relative time string like '1h', '30m', '2d' into a datetime cutoff. + + Returns None if the string can't be parsed. + """ + since_str = since_str.strip().lower() + match = re.match(r"^(\d+)\s*([smhd])$", since_str) + if not match: + return None + value = int(match.group(1)) + unit = match.group(2) + delta = { + "s": timedelta(seconds=value), + "m": timedelta(minutes=value), + "h": timedelta(hours=value), + "d": timedelta(days=value), + }[unit] + return datetime.now() - delta + + +def _parse_line_timestamp(line: str) -> Optional[datetime]: + """Extract timestamp from a log line. Returns None if not parseable.""" + m = _TS_RE.match(line) + if not m: + return None + try: + return datetime.strptime(m.group(1), "%Y-%m-%d %H:%M:%S") + except ValueError: + return None + + +def _extract_level(line: str) -> Optional[str]: + """Extract the log level from a line.""" + m = _LEVEL_RE.search(line) + return m.group(1) if m else None + + +def _extract_logger_name(line: str) -> Optional[str]: + """Extract the logger name from a log line.""" + m = _LOGGER_NAME_RE.search(line) + return m.group(1) if m else None + + +def _line_matches_component(line: str, prefixes: Sequence[str]) -> bool: + """Check if a log line's logger name starts with any of *prefixes*.""" + name = _extract_logger_name(line) + if name is None: + return False + return name.startswith(tuple(prefixes)) + + +def _matches_filters( + line: str, + *, + min_level: Optional[str] = None, + session_filter: Optional[str] = None, + since: Optional[datetime] = None, + component_prefixes: Optional[Sequence[str]] = None, +) -> bool: + """Check if a log line passes all active filters.""" + if since is not None: + ts = _parse_line_timestamp(line) + if ts is not None and ts < since: + return False + + if min_level is not None: + level = _extract_level(line) + if level is not None: + if _LEVEL_ORDER.get(level, 0) < _LEVEL_ORDER.get(min_level, 0): + return False + + if session_filter is not None: + if session_filter not in line: + return False + + if component_prefixes is not None: + if not _line_matches_component(line, component_prefixes): + return False + + return True + + +def tail_log( + log_name: str = "agent", + *, + num_lines: int = 50, + follow: bool = False, + level: Optional[str] = None, + session: Optional[str] = None, + since: Optional[str] = None, + component: Optional[str] = None, +) -> None: + """Read and display log lines, optionally following in real time. + + Parameters + ---------- + log_name + Which log to read: ``"agent"``, ``"errors"``, ``"gateway"``. + num_lines + Number of recent lines to show (before follow starts). + follow + If True, keep watching for new lines (Ctrl+C to stop). + level + Minimum log level to show (e.g. ``"WARNING"``). + session + Session ID substring to filter on. + since + Relative time string (e.g. ``"1h"``, ``"30m"``). + component + Component name to filter by (e.g. ``"gateway"``, ``"tools"``). + """ + filename = LOG_FILES.get(log_name) + if filename is None: + print(f"Unknown log: {log_name!r}. Available: {', '.join(sorted(LOG_FILES))}") + sys.exit(1) + + log_path = get_hermes_home() / "logs" / filename + if not log_path.exists(): + print(f"Log file not found: {log_path}") + print(f"(Logs are created when Hermes runs — try 'hermes chat' first)") + sys.exit(1) + + # Parse --since into a datetime cutoff + since_dt = None + if since: + since_dt = _parse_since(since) + if since_dt is None: + print(f"Invalid --since value: {since!r}. Use format like '1h', '30m', '2d'.") + sys.exit(1) + + min_level = level.upper() if level else None + if min_level and min_level not in _LEVEL_ORDER: + print(f"Invalid --level: {level!r}. Use DEBUG, INFO, WARNING, ERROR, or CRITICAL.") + sys.exit(1) + + # Resolve component to logger name prefixes + component_prefixes = None + if component: + from hermes_logging import COMPONENT_PREFIXES + component_lower = component.lower() + if component_lower not in COMPONENT_PREFIXES: + available = ", ".join(sorted(COMPONENT_PREFIXES)) + print(f"Unknown component: {component!r}. Available: {available}") + sys.exit(1) + component_prefixes = COMPONENT_PREFIXES[component_lower] + + has_filters = ( + min_level is not None + or session is not None + or since_dt is not None + or component_prefixes is not None + ) + + # Read and display the tail + try: + lines = _read_tail(log_path, num_lines, has_filters=has_filters, + min_level=min_level, session_filter=session, + since=since_dt, component_prefixes=component_prefixes) + except PermissionError: + print(f"Permission denied: {log_path}") + sys.exit(1) + + # Print header + filter_parts = [] + if min_level: + filter_parts.append(f"level>={min_level}") + if session: + filter_parts.append(f"session={session}") + if component: + filter_parts.append(f"component={component}") + if since: + filter_parts.append(f"since={since}") + filter_desc = f" [{', '.join(filter_parts)}]" if filter_parts else "" + + if follow: + print(f"--- {display_hermes_home()}/logs/{filename}{filter_desc} (Ctrl+C to stop) ---") + else: + print(f"--- {display_hermes_home()}/logs/{filename}{filter_desc} (last {num_lines}) ---") + + for line in lines: + print(line, end="") + + if not follow: + return + + # Follow mode — poll for new content + try: + _follow_log(log_path, min_level=min_level, session_filter=session, + since=since_dt, component_prefixes=component_prefixes) + except KeyboardInterrupt: + print("\n--- stopped ---") + + +def _read_tail( + path: Path, + num_lines: int, + *, + has_filters: bool = False, + min_level: Optional[str] = None, + session_filter: Optional[str] = None, + since: Optional[datetime] = None, + component_prefixes: Optional[Sequence[str]] = None, +) -> list: + """Read the last *num_lines* matching lines from a log file. + + When filters are active, we read more raw lines to find enough matches. + """ + if has_filters: + # Read more lines to ensure we get enough after filtering. + # For large files, read last 10K lines and filter down. + raw_lines = _read_last_n_lines(path, max(num_lines * 20, 2000)) + filtered = [ + l for l in raw_lines + if _matches_filters(l, min_level=min_level, + session_filter=session_filter, since=since, + component_prefixes=component_prefixes) + ] + return filtered[-num_lines:] + else: + return _read_last_n_lines(path, num_lines) + + +def _read_last_n_lines(path: Path, n: int) -> list: + """Efficiently read the last N lines from a file. + + For files under 1MB, reads the whole file (fast, simple). + For larger files, reads chunks from the end. + """ + try: + size = path.stat().st_size + if size == 0: + return [] + + # For files up to 1MB, just read the whole thing — simple and correct. + if size <= 1_048_576: + with open(path, "r", encoding="utf-8", errors="replace") as f: + all_lines = f.readlines() + return all_lines[-n:] + + # For large files, read chunks from the end. + with open(path, "rb") as f: + chunk_size = 8192 + lines = [] + pos = size + + while pos > 0 and len(lines) <= n + 1: + read_size = min(chunk_size, pos) + pos -= read_size + f.seek(pos) + chunk = f.read(read_size) + chunk_lines = chunk.split(b"\n") + if lines: + # Merge the last partial line of the new chunk with the + # first partial line of what we already have. + lines[0] = chunk_lines[-1] + lines[0] + lines = chunk_lines[:-1] + lines + else: + lines = chunk_lines + chunk_size = min(chunk_size * 2, 65536) + + # Decode and return last N non-empty lines. + decoded = [] + for raw in lines: + if not raw.strip(): + continue + try: + decoded.append(raw.decode("utf-8", errors="replace") + "\n") + except Exception: + decoded.append(raw.decode("latin-1") + "\n") + return decoded[-n:] + + except Exception: + # Fallback: read entire file + with open(path, "r", encoding="utf-8", errors="replace") as f: + all_lines = f.readlines() + return all_lines[-n:] + + +def _follow_log( + path: Path, + *, + min_level: Optional[str] = None, + session_filter: Optional[str] = None, + since: Optional[datetime] = None, + component_prefixes: Optional[Sequence[str]] = None, +) -> None: + """Poll a log file for new content and print matching lines.""" + with open(path, "r", encoding="utf-8", errors="replace") as f: + # Seek to end + f.seek(0, 2) + while True: + line = f.readline() + if line: + if _matches_filters(line, min_level=min_level, + session_filter=session_filter, since=since, + component_prefixes=component_prefixes): + print(line, end="") + sys.stdout.flush() + else: + time.sleep(0.3) + + +def list_logs() -> None: + """Print available log files with sizes.""" + log_dir = get_hermes_home() / "logs" + if not log_dir.exists(): + print(f"No logs directory at {display_hermes_home()}/logs/") + return + + print(f"Log files in {display_hermes_home()}/logs/:\n") + found = False + for entry in sorted(log_dir.iterdir()): + if entry.is_file() and entry.suffix == ".log": + size = entry.stat().st_size + mtime = datetime.fromtimestamp(entry.stat().st_mtime) + if size < 1024: + size_str = f"{size}B" + elif size < 1024 * 1024: + size_str = f"{size / 1024:.1f}KB" + else: + size_str = f"{size / (1024 * 1024):.1f}MB" + age = datetime.now() - mtime + if age.total_seconds() < 60: + age_str = "just now" + elif age.total_seconds() < 3600: + age_str = f"{int(age.total_seconds() / 60)}m ago" + elif age.total_seconds() < 86400: + age_str = f"{int(age.total_seconds() / 3600)}h ago" + else: + age_str = mtime.strftime("%Y-%m-%d") + print(f" {entry.name:<25} {size_str:>8} {age_str}") + found = True + + if not found: + print(" (no log files yet — run 'hermes chat' to generate logs)") diff --git a/mindcli/_vendor/hermes_cli/main.py b/mindcli/_vendor/hermes_cli/main.py new file mode 100644 index 0000000..46a7e2c --- /dev/null +++ b/mindcli/_vendor/hermes_cli/main.py @@ -0,0 +1,6047 @@ +#!/usr/bin/env python3 +""" +Hermes CLI - Main entry point. + +Usage: + hermes # Interactive chat (default) + hermes chat # Interactive chat + hermes gateway # Run gateway in foreground + hermes gateway start # Start gateway as service + hermes gateway stop # Stop gateway service + hermes gateway status # Show gateway status + hermes gateway install # Install gateway service + hermes gateway uninstall # Uninstall gateway service + hermes setup # Interactive setup wizard + hermes logout # Clear stored authentication + hermes status # Show status of all components + hermes cron # Manage cron jobs + hermes cron list # List cron jobs + hermes cron status # Check if cron scheduler is running + hermes doctor # Check configuration and dependencies + hermes honcho setup # Configure Honcho AI memory integration + hermes honcho status # Show Honcho config and connection status + hermes honcho sessions # List directory → session name mappings + hermes honcho map # Map current directory to a session name + hermes honcho peer # Show peer names and dialectic settings + hermes honcho peer --user NAME # Set user peer name + hermes honcho peer --ai NAME # Set AI peer name + hermes honcho peer --reasoning LEVEL # Set dialectic reasoning level + hermes honcho mode # Show current memory mode + hermes honcho mode [hybrid|honcho|local] # Set memory mode + hermes honcho tokens # Show token budget settings + hermes honcho tokens --context N # Set session.context() token cap + hermes honcho tokens --dialectic N # Set dialectic result char cap + hermes honcho identity # Show AI peer identity representation + hermes honcho identity # Seed AI peer identity from a file (SOUL.md etc.) + hermes honcho migrate # Step-by-step migration guide: OpenClaw native → Hermes + Honcho + hermes version Show version + hermes update Update to latest version + hermes uninstall Uninstall Hermes Agent + hermes acp Run as an ACP server for editor integration + hermes sessions browse Interactive session picker with search + + hermes claw migrate --dry-run # Preview migration without changes +""" + +import argparse +import os +import subprocess +import sys +from pathlib import Path +from typing import Optional + +def _require_tty(command_name: str) -> None: + """Exit with a clear error if stdin is not a terminal. + + Interactive TUI commands (hermes tools, hermes setup, hermes model) use + curses or input() prompts that spin at 100% CPU when stdin is a pipe. + This guard prevents accidental non-interactive invocation. + """ + if not sys.stdin.isatty(): + print( + f"Error: 'hermes {command_name}' requires an interactive terminal.\n" + f"It cannot be run through a pipe or non-interactive subprocess.\n" + f"Run it directly in your terminal instead.", + file=sys.stderr, + ) + sys.exit(1) + + +# Add project root to path +PROJECT_ROOT = Path(__file__).parent.parent.resolve() +sys.path.insert(0, str(PROJECT_ROOT)) + +# --------------------------------------------------------------------------- +# Profile override — MUST happen before any hermes module import. +# +# Many modules cache HERMES_HOME at import time (module-level constants). +# We intercept --profile/-p from sys.argv here and set the env var so that +# every subsequent ``os.getenv("HERMES_HOME", ...)`` resolves correctly. +# The flag is stripped from sys.argv so argparse never sees it. +# Falls back to ~/.hermes/active_profile for sticky default. +# --------------------------------------------------------------------------- +def _apply_profile_override() -> None: + """Pre-parse --profile/-p and set HERMES_HOME before module imports.""" + argv = sys.argv[1:] + profile_name = None + consume = 0 + + # 1. Check for explicit -p / --profile flag + for i, arg in enumerate(argv): + if arg in ("--profile", "-p") and i + 1 < len(argv): + profile_name = argv[i + 1] + consume = 2 + break + elif arg.startswith("--profile="): + profile_name = arg.split("=", 1)[1] + consume = 1 + break + + # 2. If no flag, check active_profile in the hermes root + if profile_name is None: + try: + from hermes_constants import get_default_hermes_root + active_path = get_default_hermes_root() / "active_profile" + if active_path.exists(): + name = active_path.read_text().strip() + if name and name != "default": + profile_name = name + consume = 0 # don't strip anything from argv + except (UnicodeDecodeError, OSError): + pass # corrupted file, skip + + # 3. If we found a profile, resolve and set HERMES_HOME + if profile_name is not None: + try: + from hermes_cli.profiles import resolve_profile_env + hermes_home = resolve_profile_env(profile_name) + except (ValueError, FileNotFoundError) as exc: + print(f"Error: {exc}", file=sys.stderr) + sys.exit(1) + except Exception as exc: + # A bug in profiles.py must NEVER prevent hermes from starting + print(f"Warning: profile override failed ({exc}), using default", file=sys.stderr) + return + os.environ["HERMES_HOME"] = hermes_home + # Strip the flag from argv so argparse doesn't choke + if consume > 0: + for i, arg in enumerate(argv): + if arg in ("--profile", "-p"): + start = i + 1 # +1 because argv is sys.argv[1:] + sys.argv = sys.argv[:start] + sys.argv[start + consume:] + break + elif arg.startswith("--profile="): + start = i + 1 + sys.argv = sys.argv[:start] + sys.argv[start + 1:] + break + +_apply_profile_override() + +# 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_cli.config import get_hermes_home +from hermes_cli.env_loader import load_hermes_dotenv +load_hermes_dotenv(project_env=PROJECT_ROOT / '.env') + +# Initialize centralized file logging early — all `hermes` subcommands +# (chat, setup, gateway, config, etc.) write to agent.log + errors.log. +try: + from hermes_logging import setup_logging as _setup_logging + _setup_logging(mode="cli") +except Exception: + pass # best-effort — don't crash the CLI if logging setup fails + +# Apply IPv4 preference early, before any HTTP clients are created. +try: + from hermes_cli.config import load_config as _load_config_early + from hermes_constants import apply_ipv4_preference as _apply_ipv4 + _early_cfg = _load_config_early() + _net = _early_cfg.get("network", {}) + if isinstance(_net, dict) and _net.get("force_ipv4"): + _apply_ipv4(force=True) + del _early_cfg, _net +except Exception: + pass # best-effort — don't crash if config isn't available yet + +import logging +import time as _time +from datetime import datetime + +from hermes_cli import __version__, __release_date__ +from hermes_constants import OPENROUTER_BASE_URL + +logger = logging.getLogger(__name__) + + +def _relative_time(ts) -> str: + """Format a timestamp as relative time (e.g., '2h ago', 'yesterday').""" + if not ts: + return "?" + delta = _time.time() - ts + if delta < 60: + return "just now" + if delta < 3600: + return f"{int(delta / 60)}m ago" + if delta < 86400: + return f"{int(delta / 3600)}h ago" + if delta < 172800: + return "yesterday" + if delta < 604800: + return f"{int(delta / 86400)}d ago" + return datetime.fromtimestamp(ts).strftime("%Y-%m-%d") + + +def _has_any_provider_configured() -> bool: + """Check if at least one inference provider is usable.""" + from hermes_cli.config import get_env_path, get_hermes_home, load_config + from hermes_cli.auth import get_auth_status + + # Determine whether Hermes itself has been explicitly configured (model + # in config that isn't the hardcoded default). Used below to gate external + # tool credentials (Claude Code, Codex CLI) that shouldn't silently skip + # the setup wizard on a fresh install. + from hermes_cli.config import DEFAULT_CONFIG + _DEFAULT_MODEL = DEFAULT_CONFIG.get("model", "") + cfg = load_config() + model_cfg = cfg.get("model") + if isinstance(model_cfg, dict): + _model_name = (model_cfg.get("default") or "").strip() + elif isinstance(model_cfg, str): + _model_name = model_cfg.strip() + else: + _model_name = "" + _has_hermes_config = _model_name and _model_name != _DEFAULT_MODEL + + # Check env vars (may be set by .env or shell). + # OPENAI_BASE_URL alone counts — local models (vLLM, llama.cpp, etc.) + # often don't require an API key. + from hermes_cli.auth import PROVIDER_REGISTRY + + # Collect all provider env vars + provider_env_vars = {"OPENROUTER_API_KEY", "OPENAI_API_KEY", "ANTHROPIC_API_KEY", "ANTHROPIC_TOKEN", "OPENAI_BASE_URL"} + for pconfig in PROVIDER_REGISTRY.values(): + if pconfig.auth_type == "api_key": + provider_env_vars.update(pconfig.api_key_env_vars) + if any(os.getenv(v) for v in provider_env_vars): + return True + + # Check .env file for keys + env_file = get_env_path() + if env_file.exists(): + try: + for line in env_file.read_text().splitlines(): + line = line.strip() + if line.startswith("#") or "=" not in line: + continue + key, _, val = line.partition("=") + val = val.strip().strip("'\"") + if key.strip() in provider_env_vars and val: + return True + except Exception: + pass + + # Check provider-specific auth fallbacks (for example, Copilot via gh auth). + try: + for provider_id, pconfig in PROVIDER_REGISTRY.items(): + if pconfig.auth_type != "api_key": + continue + status = get_auth_status(provider_id) + if status.get("logged_in"): + return True + except Exception: + pass + + # Check for Nous Portal OAuth credentials + auth_file = get_hermes_home() / "auth.json" + if auth_file.exists(): + try: + import json + auth = json.loads(auth_file.read_text()) + active = auth.get("active_provider") + if active: + status = get_auth_status(active) + if status.get("logged_in"): + return True + except Exception: + pass + + + # Check config.yaml — if model is a dict with an explicit provider set, + # the user has gone through setup (fresh installs have model as a plain + # string). Also covers custom endpoints that store api_key/base_url in + # config rather than .env. + if isinstance(model_cfg, dict): + cfg_provider = (model_cfg.get("provider") or "").strip() + cfg_base_url = (model_cfg.get("base_url") or "").strip() + cfg_api_key = (model_cfg.get("api_key") or "").strip() + if cfg_provider or cfg_base_url or cfg_api_key: + return True + + # Check for Claude Code OAuth credentials (~/.claude/.credentials.json) + # Only count these if Hermes has been explicitly configured — Claude Code + # being installed doesn't mean the user wants Hermes to use their tokens. + if _has_hermes_config: + try: + from agent.anthropic_adapter import read_claude_code_credentials, is_claude_code_token_valid + creds = read_claude_code_credentials() + if creds and (is_claude_code_token_valid(creds) or creds.get("refreshToken")): + return True + except Exception: + pass + + return False + + +def _session_browse_picker(sessions: list) -> Optional[str]: + """Interactive curses-based session browser with live search filtering. + + Returns the selected session ID, or None if cancelled. + Uses curses (not simple_term_menu) to avoid the ghost-duplication rendering + bug in tmux/iTerm when arrow keys are used. + """ + if not sessions: + print("No sessions found.") + return None + + # Try curses-based picker first + try: + import curses + + result_holder = [None] + + def _format_row(s, max_x): + """Format a session row for display.""" + title = (s.get("title") or "").strip() + preview = (s.get("preview") or "").strip() + source = s.get("source", "")[:6] + last_active = _relative_time(s.get("last_active")) + sid = s["id"][:18] + + # Adaptive column widths based on terminal width + # Layout: [arrow 3] [title/preview flexible] [active 12] [src 6] [id 18] + fixed_cols = 3 + 12 + 6 + 18 + 6 # arrow + active + src + id + padding + name_width = max(20, max_x - fixed_cols) + + if title: + name = title[:name_width] + elif preview: + name = preview[:name_width] + else: + name = sid + + return f"{name:<{name_width}} {last_active:<10} {source:<5} {sid}" + + def _match(s, query): + """Check if a session matches the search query (case-insensitive).""" + q = query.lower() + return ( + q in (s.get("title") or "").lower() + or q in (s.get("preview") or "").lower() + or q in s.get("id", "").lower() + or q in (s.get("source") or "").lower() + ) + + def _curses_browse(stdscr): + curses.curs_set(0) + if curses.has_colors(): + curses.start_color() + curses.use_default_colors() + curses.init_pair(1, curses.COLOR_GREEN, -1) # selected + curses.init_pair(2, curses.COLOR_YELLOW, -1) # header + curses.init_pair(3, curses.COLOR_CYAN, -1) # search + curses.init_pair(4, 8, -1) # dim + + cursor = 0 + scroll_offset = 0 + search_text = "" + filtered = list(sessions) + + while True: + stdscr.clear() + max_y, max_x = stdscr.getmaxyx() + if max_y < 5 or max_x < 40: + # Terminal too small + try: + stdscr.addstr(0, 0, "Terminal too small") + except curses.error: + pass + stdscr.refresh() + stdscr.getch() + return + + # Header line + if search_text: + header = f" Browse sessions — filter: {search_text}█" + header_attr = curses.A_BOLD + if curses.has_colors(): + header_attr |= curses.color_pair(3) + else: + header = " Browse sessions — ↑↓ navigate Enter select Type to filter Esc quit" + header_attr = curses.A_BOLD + if curses.has_colors(): + header_attr |= curses.color_pair(2) + try: + stdscr.addnstr(0, 0, header, max_x - 1, header_attr) + except curses.error: + pass + + # Column header line + fixed_cols = 3 + 12 + 6 + 18 + 6 + name_width = max(20, max_x - fixed_cols) + col_header = f" {'Title / Preview':<{name_width}} {'Active':<10} {'Src':<5} {'ID'}" + try: + dim_attr = curses.color_pair(4) if curses.has_colors() else curses.A_DIM + stdscr.addnstr(1, 0, col_header, max_x - 1, dim_attr) + except curses.error: + pass + + # Compute visible area + visible_rows = max_y - 4 # header + col header + blank + footer + if visible_rows < 1: + visible_rows = 1 + + # Clamp cursor and scroll + if not filtered: + try: + msg = " No sessions match the filter." + stdscr.addnstr(3, 0, msg, max_x - 1, curses.A_DIM) + except curses.error: + pass + else: + if cursor >= len(filtered): + cursor = len(filtered) - 1 + if cursor < 0: + cursor = 0 + if cursor < scroll_offset: + scroll_offset = cursor + elif cursor >= scroll_offset + visible_rows: + scroll_offset = cursor - visible_rows + 1 + + for draw_i, i in enumerate(range( + scroll_offset, + min(len(filtered), scroll_offset + visible_rows) + )): + y = draw_i + 3 + if y >= max_y - 1: + break + s = filtered[i] + arrow = " → " if i == cursor else " " + row = arrow + _format_row(s, max_x - 3) + attr = curses.A_NORMAL + if i == cursor: + attr = curses.A_BOLD + if curses.has_colors(): + attr |= curses.color_pair(1) + try: + stdscr.addnstr(y, 0, row, max_x - 1, attr) + except curses.error: + pass + + # Footer + footer_y = max_y - 1 + if filtered: + footer = f" {cursor + 1}/{len(filtered)} sessions" + if len(filtered) < len(sessions): + footer += f" (filtered from {len(sessions)})" + else: + footer = f" 0/{len(sessions)} sessions" + try: + stdscr.addnstr(footer_y, 0, footer, max_x - 1, + curses.color_pair(4) if curses.has_colors() else curses.A_DIM) + except curses.error: + pass + + stdscr.refresh() + key = stdscr.getch() + + if key in (curses.KEY_UP, ): + if filtered: + cursor = (cursor - 1) % len(filtered) + elif key in (curses.KEY_DOWN, ): + if filtered: + cursor = (cursor + 1) % len(filtered) + elif key in (curses.KEY_ENTER, 10, 13): + if filtered: + result_holder[0] = filtered[cursor]["id"] + return + elif key == 27: # Esc + if search_text: + # First Esc clears the search + search_text = "" + filtered = list(sessions) + cursor = 0 + scroll_offset = 0 + else: + # Second Esc exits + return + elif key in (curses.KEY_BACKSPACE, 127, 8): + if search_text: + search_text = search_text[:-1] + if search_text: + filtered = [s for s in sessions if _match(s, search_text)] + else: + filtered = list(sessions) + cursor = 0 + scroll_offset = 0 + elif key == ord('q') and not search_text: + return + elif 32 <= key <= 126: + # Printable character → add to search filter + search_text += chr(key) + filtered = [s for s in sessions if _match(s, search_text)] + cursor = 0 + scroll_offset = 0 + + curses.wrapper(_curses_browse) + return result_holder[0] + + except Exception: + pass + + # Fallback: numbered list (Windows without curses, etc.) + print("\n Browse sessions (enter number to resume, q to cancel)\n") + for i, s in enumerate(sessions): + title = (s.get("title") or "").strip() + preview = (s.get("preview") or "").strip() + label = title or preview or s["id"] + if len(label) > 50: + label = label[:47] + "..." + last_active = _relative_time(s.get("last_active")) + src = s.get("source", "")[:6] + print(f" {i + 1:>3}. {label:<50} {last_active:<10} {src}") + + while True: + try: + val = input(f"\n Select [1-{len(sessions)}]: ").strip() + if not val or val.lower() in ("q", "quit", "exit"): + return None + idx = int(val) - 1 + if 0 <= idx < len(sessions): + return sessions[idx]["id"] + print(f" Invalid selection. Enter 1-{len(sessions)} or q to cancel.") + except ValueError: + print(" Invalid input. Enter a number or q to cancel.") + except (KeyboardInterrupt, EOFError): + print() + return None + + +def _resolve_last_cli_session() -> Optional[str]: + """Look up the most recent CLI session ID from SQLite. Returns None if unavailable.""" + try: + from hermes_state import SessionDB + db = SessionDB() + sessions = db.search_sessions(source="cli", limit=1) + db.close() + if sessions: + return sessions[0]["id"] + except Exception: + pass + return None + + +def _probe_container(cmd: list, backend: str, via_sudo: bool = False): + """Run a container inspect probe, returning the CompletedProcess. + + Catches TimeoutExpired specifically for a human-readable message; + all other exceptions propagate naturally. + """ + try: + return subprocess.run(cmd, capture_output=True, text=True, timeout=15) + except subprocess.TimeoutExpired: + label = f"sudo {backend}" if via_sudo else backend + print( + f"Error: timed out waiting for {label} to respond.\n" + f"The {backend} daemon may be unresponsive or starting up.", + file=sys.stderr, + ) + sys.exit(1) + + +def _exec_in_container(container_info: dict, cli_args: list): + """Replace the current process with a command inside the managed container. + + Probes whether sudo is needed (rootful containers), then os.execvp + into the container. On success the Python process is replaced entirely + and the container's exit code becomes the process exit code (OS semantics). + On failure, OSError propagates naturally. + + Args: + container_info: dict with backend, container_name, exec_user, hermes_bin + cli_args: the original CLI arguments (everything after 'hermes') + """ + import shutil + + backend = container_info["backend"] + container_name = container_info["container_name"] + exec_user = container_info["exec_user"] + hermes_bin = container_info["hermes_bin"] + + runtime = shutil.which(backend) + if not runtime: + print(f"Error: {backend} not found on PATH. Cannot route to container.", + file=sys.stderr) + sys.exit(1) + + # Rootful containers (NixOS systemd service) are invisible to unprivileged + # users — Podman uses per-user namespaces, Docker needs group access. + # Probe whether the runtime can see the container; if not, try via sudo. + sudo_path = None + probe = _probe_container( + [runtime, "inspect", "--format", "ok", container_name], backend, + ) + if probe.returncode != 0: + sudo_path = shutil.which("sudo") + if sudo_path: + probe2 = _probe_container( + [sudo_path, "-n", runtime, "inspect", "--format", "ok", container_name], + backend, via_sudo=True, + ) + if probe2.returncode != 0: + print( + f"Error: container '{container_name}' not found via {backend}.\n" + f"\n" + f"The container is likely running as root. Your user cannot see it\n" + f"because {backend} uses per-user namespaces. Grant passwordless\n" + f"sudo for {backend} — the -n (non-interactive) flag is required\n" + f"because a password prompt would hang or break piped commands.\n" + f"\n" + f"On NixOS:\n" + f"\n" + f' security.sudo.extraRules = [{{\n' + f' users = [ "{os.getenv("USER", "your-user")}" ];\n' + f' commands = [{{ command = "{runtime}"; options = [ "NOPASSWD" ]; }}];\n' + f' }}];\n' + f"\n" + f"Or run: sudo hermes {' '.join(cli_args)}", + file=sys.stderr, + ) + sys.exit(1) + else: + print( + f"Error: container '{container_name}' not found via {backend}.\n" + f"The container may be running under root. Try: sudo hermes {' '.join(cli_args)}", + file=sys.stderr, + ) + sys.exit(1) + + is_tty = sys.stdin.isatty() + tty_flags = ["-it"] if is_tty else ["-i"] + + env_flags = [] + for var in ("TERM", "COLORTERM", "LANG", "LC_ALL"): + val = os.environ.get(var) + if val: + env_flags.extend(["-e", f"{var}={val}"]) + + cmd_prefix = [sudo_path, "-n", runtime] if sudo_path else [runtime] + exec_cmd = ( + cmd_prefix + ["exec"] + + tty_flags + + ["-u", exec_user] + + env_flags + + [container_name, hermes_bin] + + cli_args + ) + + os.execvp(exec_cmd[0], exec_cmd) + + +def _resolve_session_by_name_or_id(name_or_id: str) -> Optional[str]: + """Resolve a session name (title) or ID to a session ID. + + - If it looks like a session ID (contains underscore + hex), try direct lookup first. + - Otherwise, treat it as a title and use resolve_session_by_title (auto-latest). + - Falls back to the other method if the first doesn't match. + """ + try: + from hermes_state import SessionDB + db = SessionDB() + + # Try as exact session ID first + session = db.get_session(name_or_id) + if session: + db.close() + return session["id"] + + # Try as title (with auto-latest for lineage) + session_id = db.resolve_session_by_title(name_or_id) + db.close() + return session_id + except Exception: + pass + return None + + +def cmd_chat(args): + """Run interactive chat CLI.""" + # Resolve --continue into --resume with the latest CLI session or by name + continue_val = getattr(args, "continue_last", None) + if continue_val and not getattr(args, "resume", None): + if isinstance(continue_val, str): + # -c "session name" — resolve by title or ID + resolved = _resolve_session_by_name_or_id(continue_val) + if resolved: + args.resume = resolved + else: + print(f"No session found matching '{continue_val}'.") + print("Use 'hermes sessions list' to see available sessions.") + sys.exit(1) + else: + # -c with no argument — continue the most recent session + last_id = _resolve_last_cli_session() + if last_id: + args.resume = last_id + else: + print("No previous CLI session found to continue.") + sys.exit(1) + + # Resolve --resume by title if it's not a direct session ID + resume_val = getattr(args, "resume", None) + if resume_val: + resolved = _resolve_session_by_name_or_id(resume_val) + if resolved: + args.resume = resolved + # If resolution fails, keep the original value — _init_agent will + # report "Session not found" with the original input + + # First-run guard: check if any provider is configured before launching + if not _has_any_provider_configured(): + print() + print("It looks like Hermes isn't configured yet -- no API keys or providers found.") + print() + print(" Run: hermes setup") + print() + + from hermes_cli.setup import is_interactive_stdin, print_noninteractive_setup_guidance + + if not is_interactive_stdin(): + print_noninteractive_setup_guidance( + "No interactive TTY detected for the first-run setup prompt." + ) + sys.exit(1) + + try: + reply = input("Run setup now? [Y/n] ").strip().lower() + except (EOFError, KeyboardInterrupt): + reply = "n" + if reply in ("", "y", "yes"): + cmd_setup(args) + return + print() + print("You can run 'hermes setup' at any time to configure.") + sys.exit(1) + + # Start update check in background (runs while other init happens) + try: + from hermes_cli.banner import prefetch_update_check + prefetch_update_check() + except Exception: + pass + + # Sync bundled skills on every CLI launch (fast -- skips unchanged skills) + try: + from tools.skills_sync import sync_skills + sync_skills(quiet=True) + except Exception: + pass + + # --yolo: bypass all dangerous command approvals + if getattr(args, "yolo", False): + os.environ["HERMES_YOLO_MODE"] = "1" + + # --source: tag session source for filtering (e.g. 'tool' for third-party integrations) + if getattr(args, "source", None): + os.environ["HERMES_SESSION_SOURCE"] = args.source + + # Import and run the CLI + from cli import main as cli_main + + # Build kwargs from args + kwargs = { + "model": args.model, + "provider": getattr(args, "provider", None), + "toolsets": args.toolsets, + "skills": getattr(args, "skills", None), + "verbose": args.verbose, + "quiet": getattr(args, "quiet", False), + "query": args.query, + "image": getattr(args, "image", None), + "resume": getattr(args, "resume", None), + "worktree": getattr(args, "worktree", False), + "checkpoints": getattr(args, "checkpoints", False), + "pass_session_id": getattr(args, "pass_session_id", False), + "max_turns": getattr(args, "max_turns", None), + } + # Filter out None values + kwargs = {k: v for k, v in kwargs.items() if v is not None} + + try: + cli_main(**kwargs) + except ValueError as e: + print(f"Error: {e}") + sys.exit(1) + + +def cmd_gateway(args): + """Gateway management commands.""" + from hermes_cli.gateway import gateway_command + gateway_command(args) + + +def cmd_whatsapp(args): + """Set up WhatsApp: choose mode, configure, install bridge, pair via QR.""" + _require_tty("whatsapp") + import subprocess + from pathlib import Path + from hermes_cli.config import get_env_value, save_env_value + + print() + print("⚕ WhatsApp Setup") + print("=" * 50) + + # ── Step 1: Choose mode ────────────────────────────────────────────── + current_mode = get_env_value("WHATSAPP_MODE") or "" + if not current_mode: + print() + print("How will you use WhatsApp with Hermes?") + print() + print(" 1. Separate bot number (recommended)") + print(" People message the bot's number directly — cleanest experience.") + print(" Requires a second phone number with WhatsApp installed on a device.") + print() + print(" 2. Personal number (self-chat)") + print(" You message yourself to talk to the agent.") + print(" Quick to set up, but the UX is less intuitive.") + print() + try: + choice = input(" Choose [1/2]: ").strip() + except (EOFError, KeyboardInterrupt): + print("\nSetup cancelled.") + return + + if choice == "1": + save_env_value("WHATSAPP_MODE", "bot") + wa_mode = "bot" + print(" ✓ Mode: separate bot number") + print() + print(" ┌─────────────────────────────────────────────────┐") + print(" │ Getting a second number for the bot: │") + print(" │ │") + print(" │ Easiest: Install WhatsApp Business (free app) │") + print(" │ on your phone with a second number: │") + print(" │ • Dual-SIM: use your 2nd SIM slot │") + print(" │ • Google Voice: free US number (voice.google) │") + print(" │ • Prepaid SIM: $3-10, verify once │") + print(" │ │") + print(" │ WhatsApp Business runs alongside your personal │") + print(" │ WhatsApp — no second phone needed. │") + print(" └─────────────────────────────────────────────────┘") + else: + save_env_value("WHATSAPP_MODE", "self-chat") + wa_mode = "self-chat" + print(" ✓ Mode: personal number (self-chat)") + else: + wa_mode = current_mode + mode_label = "separate bot number" if wa_mode == "bot" else "personal number (self-chat)" + print(f"\n✓ Mode: {mode_label}") + + # ── Step 2: Enable WhatsApp ────────────────────────────────────────── + print() + current = get_env_value("WHATSAPP_ENABLED") + if current and current.lower() == "true": + print("✓ WhatsApp is already enabled") + else: + save_env_value("WHATSAPP_ENABLED", "true") + print("✓ WhatsApp enabled") + + # ── Step 3: Allowed users ──────────────────────────────────────────── + current_users = get_env_value("WHATSAPP_ALLOWED_USERS") or "" + if current_users: + print(f"✓ Allowed users: {current_users}") + try: + response = input("\n Update allowed users? [y/N] ").strip() + except (EOFError, KeyboardInterrupt): + response = "n" + if response.lower() in ("y", "yes"): + if wa_mode == "bot": + phone = input(" Phone numbers that can message the bot (comma-separated): ").strip() + else: + phone = input(" Your phone number (e.g. 15551234567): ").strip() + if phone: + save_env_value("WHATSAPP_ALLOWED_USERS", phone.replace(" ", "")) + print(f" ✓ Updated to: {phone}") + else: + print() + if wa_mode == "bot": + print(" Who should be allowed to message the bot?") + phone = input(" Phone numbers (comma-separated, or * for anyone): ").strip() + else: + phone = input(" Your phone number (e.g. 15551234567): ").strip() + if phone: + save_env_value("WHATSAPP_ALLOWED_USERS", phone.replace(" ", "")) + print(f" ✓ Allowed users set: {phone}") + else: + print(" ⚠ No allowlist — the agent will respond to ALL incoming messages") + + # ── Step 4: Install bridge dependencies ────────────────────────────── + project_root = Path(__file__).resolve().parents[1] + bridge_dir = project_root / "scripts" / "whatsapp-bridge" + bridge_script = bridge_dir / "bridge.js" + + if not bridge_script.exists(): + print(f"\n✗ Bridge script not found at {bridge_script}") + return + + if not (bridge_dir / "node_modules").exists(): + print("\n→ Installing WhatsApp bridge dependencies...") + result = subprocess.run( + ["npm", "install"], + cwd=str(bridge_dir), + capture_output=True, + text=True, + timeout=120, + ) + if result.returncode != 0: + print(f" ✗ npm install failed: {result.stderr}") + return + print(" ✓ Dependencies installed") + else: + print("✓ Bridge dependencies already installed") + + # ── Step 5: Check for existing session ─────────────────────────────── + session_dir = get_hermes_home() / "whatsapp" / "session" + session_dir.mkdir(parents=True, exist_ok=True) + + if (session_dir / "creds.json").exists(): + print("✓ Existing WhatsApp session found") + try: + response = input("\n Re-pair? This will clear the existing session. [y/N] ").strip() + except (EOFError, KeyboardInterrupt): + response = "n" + if response.lower() in ("y", "yes"): + import shutil + shutil.rmtree(session_dir, ignore_errors=True) + session_dir.mkdir(parents=True, exist_ok=True) + print(" ✓ Session cleared") + else: + print("\n✓ WhatsApp is configured and paired!") + print(" Start the gateway with: hermes gateway") + return + + # ── Step 6: QR code pairing ────────────────────────────────────────── + print() + print("─" * 50) + if wa_mode == "bot": + print("📱 Open WhatsApp (or WhatsApp Business) on the") + print(" phone with the BOT's number, then scan:") + else: + print("📱 Open WhatsApp on your phone, then scan:") + print() + print(" Settings → Linked Devices → Link a Device") + print("─" * 50) + print() + + try: + subprocess.run( + ["node", str(bridge_script), "--pair-only", "--session", str(session_dir)], + cwd=str(bridge_dir), + ) + except KeyboardInterrupt: + pass + + # ── Step 7: Post-pairing ───────────────────────────────────────────── + print() + if (session_dir / "creds.json").exists(): + print("✓ WhatsApp paired successfully!") + print() + if wa_mode == "bot": + print(" Next steps:") + print(" 1. Start the gateway: hermes gateway") + print(" 2. Send a message to the bot's WhatsApp number") + print(" 3. The agent will reply automatically") + print() + print(" Tip: Agent responses are prefixed with '⚕ Hermes Agent'") + else: + print(" Next steps:") + print(" 1. Start the gateway: hermes gateway") + print(" 2. Open WhatsApp → Message Yourself") + print(" 3. Type a message — the agent will reply") + print() + print(" Tip: Agent responses are prefixed with '⚕ Hermes Agent'") + print(" so you can tell them apart from your own messages.") + print() + print(" Or install as a service: hermes gateway install") + else: + print("⚠ Pairing may not have completed. Run 'hermes whatsapp' to try again.") + + +def cmd_setup(args): + """Interactive setup wizard.""" + from hermes_cli.setup import run_setup_wizard + run_setup_wizard(args) + + +def cmd_model(args): + """Select default model — starts with provider selection, then model picker.""" + _require_tty("model") + select_provider_and_model(args=args) + + +def select_provider_and_model(args=None): + """Core provider selection + model picking logic. + + Shared by ``cmd_model`` (``hermes model``) and the setup wizard + (``setup_model_provider`` in setup.py). Handles the full flow: + provider picker, credential prompting, model selection, and config + persistence. + """ + from hermes_cli.auth import ( + resolve_provider, AuthError, format_auth_error, + ) + from hermes_cli.config import get_compatible_custom_providers, load_config, get_env_value + + config = load_config() + current_model = config.get("model") + if isinstance(current_model, dict): + current_model = current_model.get("default", "") + current_model = current_model or "(not set)" + + # Read effective provider the same way the CLI does at startup: + # config.yaml model.provider > env var > auto-detect + import os + config_provider = None + model_cfg = config.get("model") + if isinstance(model_cfg, dict): + config_provider = model_cfg.get("provider") + + effective_provider = ( + config_provider + or os.getenv("HERMES_INFERENCE_PROVIDER") + or "auto" + ) + try: + active = resolve_provider(effective_provider) + except AuthError as exc: + warning = format_auth_error(exc) + print(f"Warning: {warning} Falling back to auto provider detection.") + try: + active = resolve_provider("auto") + except AuthError: + active = None # no provider yet; default to first in list + + # Detect custom endpoint + if active == "openrouter" and get_env_value("OPENAI_BASE_URL"): + active = "custom" + + from hermes_cli.models import CANONICAL_PROVIDERS, _PROVIDER_LABELS + + provider_labels = dict(_PROVIDER_LABELS) # derive from canonical list + active_label = provider_labels.get(active, active) if active else "none" + + print() + print(f" Current model: {current_model}") + print(f" Active provider: {active_label}") + print() + + # Step 1: Provider selection — flat list from CANONICAL_PROVIDERS + all_providers = [(p.slug, p.tui_desc) for p in CANONICAL_PROVIDERS] + + def _named_custom_provider_map(cfg) -> dict[str, dict[str, str]]: + custom_provider_map = {} + for entry in get_compatible_custom_providers(cfg): + if not isinstance(entry, dict): + continue + name = (entry.get("name") or "").strip() + base_url = (entry.get("base_url") or "").strip() + if not name or not base_url: + continue + key = "custom:" + name.lower().replace(" ", "-") + provider_key = (entry.get("provider_key") or "").strip() + if provider_key: + try: + resolve_provider(provider_key) + except AuthError: + key = provider_key + custom_provider_map[key] = { + "name": name, + "base_url": base_url, + "api_key": entry.get("api_key", ""), + "key_env": entry.get("key_env", ""), + "model": entry.get("model", ""), + "api_mode": entry.get("api_mode", ""), + "provider_key": provider_key, + } + return custom_provider_map + + # Add user-defined custom providers from config.yaml + _custom_provider_map = _named_custom_provider_map(config) # key → {name, base_url, api_key} + for key, provider_info in _custom_provider_map.items(): + name = provider_info["name"] + base_url = provider_info["base_url"] + short_url = base_url.replace("https://", "").replace("http://", "").rstrip("/") + saved_model = provider_info.get("model", "") + model_hint = f" — {saved_model}" if saved_model else "" + all_providers.append((key, f"{name} ({short_url}){model_hint}")) + + # Build the menu + ordered = [] + default_idx = 0 + for key, label in all_providers: + if active and key == active: + ordered.append((key, f"{label} ← currently active")) + default_idx = len(ordered) - 1 + else: + ordered.append((key, label)) + + ordered.append(("custom", "Custom endpoint (enter URL manually)")) + _has_saved_custom_list = isinstance(config.get("custom_providers"), list) and bool(config.get("custom_providers")) + if _has_saved_custom_list: + ordered.append(("remove-custom", "Remove a saved custom provider")) + ordered.append(("cancel", "Cancel")) + + provider_idx = _prompt_provider_choice( + [label for _, label in ordered], default=default_idx, + ) + if provider_idx is None or ordered[provider_idx][0] == "cancel": + print("No change.") + return + + selected_provider = ordered[provider_idx][0] + + # Step 2: Provider-specific setup + model selection + if selected_provider == "openrouter": + _model_flow_openrouter(config, current_model) + elif selected_provider == "nous": + _model_flow_nous(config, current_model, args=args) + elif selected_provider == "openai-codex": + _model_flow_openai_codex(config, current_model) + elif selected_provider == "qwen-oauth": + _model_flow_qwen_oauth(config, current_model) + elif selected_provider == "copilot-acp": + _model_flow_copilot_acp(config, current_model) + elif selected_provider == "copilot": + _model_flow_copilot(config, current_model) + elif selected_provider == "custom": + _model_flow_custom(config) + elif selected_provider.startswith("custom:") or selected_provider in _custom_provider_map: + provider_info = _named_custom_provider_map(load_config()).get(selected_provider) + if provider_info is None: + print( + "Warning: the selected saved custom provider is no longer available. " + "It may have been removed from config.yaml. No change." + ) + return + _model_flow_named_custom(config, provider_info) + elif selected_provider == "remove-custom": + _remove_custom_provider(config) + elif selected_provider == "anthropic": + _model_flow_anthropic(config, current_model) + elif selected_provider == "kimi-coding": + _model_flow_kimi(config, current_model) + elif selected_provider in ("gemini", "deepseek", "xai", "zai", "kimi-coding-cn", "minimax", "minimax-cn", "kilocode", "opencode-zen", "opencode-go", "ai-gateway", "alibaba", "huggingface", "xiaomi", "arcee"): + _model_flow_api_key_provider(config, selected_provider, current_model) + + # ── Post-switch cleanup: clear stale OPENAI_BASE_URL ────────────── + # When the user switches to a named provider (anything except "custom"), + # a leftover OPENAI_BASE_URL in ~/.hermes/.env can poison auxiliary + # clients that use provider:auto. Clear it proactively. (#5161) + if selected_provider not in ("custom", "cancel", "remove-custom") \ + and not selected_provider.startswith("custom:"): + _clear_stale_openai_base_url() + + +def _clear_stale_openai_base_url(): + """Remove OPENAI_BASE_URL from ~/.hermes/.env if the active provider is not 'custom'. + + After a provider switch, a leftover OPENAI_BASE_URL causes auxiliary + clients (compression, vision, delegation) with provider:auto to route + requests to the old custom endpoint instead of the newly selected + provider. See issue #5161. + """ + from hermes_cli.config import get_env_value, save_env_value, load_config + + cfg = load_config() + model_cfg = cfg.get("model", {}) + if isinstance(model_cfg, dict): + provider = (model_cfg.get("provider") or "").strip().lower() + else: + provider = "" + + if provider == "custom" or not provider: + return # custom provider legitimately uses OPENAI_BASE_URL + + stale_url = get_env_value("OPENAI_BASE_URL") + if stale_url: + save_env_value("OPENAI_BASE_URL", "") + print(f"Cleared stale OPENAI_BASE_URL from .env (was: {stale_url[:40]}...)" + if len(stale_url) > 40 + else f"Cleared stale OPENAI_BASE_URL from .env (was: {stale_url})") + + +def _prompt_provider_choice(choices, *, default=0): + """Show provider selection menu with curses arrow-key navigation. + + Falls back to a numbered list when curses is unavailable (e.g. piped + stdin, non-TTY environments). Returns the selected index, or None + if the user cancels. + """ + try: + from hermes_cli.setup import _curses_prompt_choice + idx = _curses_prompt_choice("Select provider:", choices, default) + if idx >= 0: + print() + return idx + except Exception: + pass + + # Fallback: numbered list + print("Select provider:") + for i, c in enumerate(choices, 1): + marker = "→" if i - 1 == default else " " + print(f" {marker} {i}. {c}") + print() + while True: + try: + val = input(f"Choice [1-{len(choices)}] ({default + 1}): ").strip() + if not val: + return default + idx = int(val) - 1 + if 0 <= idx < len(choices): + return idx + print(f"Please enter 1-{len(choices)}") + except ValueError: + print("Please enter a number") + except (KeyboardInterrupt, EOFError): + print() + return None + + +def _model_flow_openrouter(config, current_model=""): + """OpenRouter provider: ensure API key, then pick model.""" + from hermes_cli.auth import _prompt_model_selection, _save_model_choice, deactivate_provider + from hermes_cli.config import get_env_value, save_env_value + + api_key = get_env_value("OPENROUTER_API_KEY") + if not api_key: + print("No OpenRouter API key configured.") + print("Get one at: https://openrouter.ai/keys") + print() + try: + import getpass + key = getpass.getpass("OpenRouter API key (or Enter to cancel): ").strip() + except (KeyboardInterrupt, EOFError): + print() + return + if not key: + print("Cancelled.") + return + save_env_value("OPENROUTER_API_KEY", key) + print("API key saved.") + print() + + from hermes_cli.models import model_ids, get_pricing_for_provider + openrouter_models = model_ids(force_refresh=True) + + # Fetch live pricing (non-blocking — returns empty dict on failure) + pricing = get_pricing_for_provider("openrouter", force_refresh=True) + + selected = _prompt_model_selection(openrouter_models, current_model=current_model, pricing=pricing) + if selected: + _save_model_choice(selected) + + # Update config provider and deactivate any OAuth provider + from hermes_cli.config import load_config, save_config + cfg = load_config() + model = cfg.get("model") + if not isinstance(model, dict): + model = {"default": model} if model else {} + cfg["model"] = model + model["provider"] = "openrouter" + model["base_url"] = OPENROUTER_BASE_URL + model["api_mode"] = "chat_completions" + save_config(cfg) + deactivate_provider() + print(f"Default model set to: {selected} (via OpenRouter)") + else: + print("No change.") + + +def _model_flow_nous(config, current_model="", args=None): + """Nous Portal provider: ensure logged in, then pick model.""" + from hermes_cli.auth import ( + get_provider_auth_state, _prompt_model_selection, _save_model_choice, + _update_config_for_provider, resolve_nous_runtime_credentials, + AuthError, format_auth_error, + _login_nous, PROVIDER_REGISTRY, + ) + from hermes_cli.config import get_env_value, save_config, save_env_value + from hermes_cli.nous_subscription import ( + apply_nous_provider_defaults, + get_nous_subscription_explainer_lines, + ) + import argparse + + state = get_provider_auth_state("nous") + if not state or not state.get("access_token"): + print("Not logged into Nous Portal. Starting login...") + print() + try: + mock_args = argparse.Namespace( + portal_url=getattr(args, "portal_url", None), + inference_url=getattr(args, "inference_url", None), + client_id=getattr(args, "client_id", None), + scope=getattr(args, "scope", None), + no_browser=bool(getattr(args, "no_browser", False)), + timeout=getattr(args, "timeout", None) or 15.0, + ca_bundle=getattr(args, "ca_bundle", None), + insecure=bool(getattr(args, "insecure", False)), + ) + _login_nous(mock_args, PROVIDER_REGISTRY["nous"]) + print() + for line in get_nous_subscription_explainer_lines(): + print(line) + except SystemExit: + print("Login cancelled or failed.") + return + except Exception as exc: + print(f"Login failed: {exc}") + return + # login_nous already handles model selection + config update + return + + # Already logged in — use curated model list (same as OpenRouter defaults). + # The live /models endpoint returns hundreds of models; the curated list + # shows only agentic models users recognize from OpenRouter. + from hermes_cli.models import ( + _PROVIDER_MODELS, get_pricing_for_provider, filter_nous_free_models, + check_nous_free_tier, partition_nous_models_by_tier, + ) + model_ids = _PROVIDER_MODELS.get("nous", []) + if not model_ids: + print("No curated models available for Nous Portal.") + return + + # Verify credentials are still valid (catches expired sessions early) + try: + creds = resolve_nous_runtime_credentials(min_key_ttl_seconds=5 * 60) + except Exception as exc: + relogin = isinstance(exc, AuthError) and exc.relogin_required + msg = format_auth_error(exc) if isinstance(exc, AuthError) else str(exc) + if relogin: + print(f"Session expired: {msg}") + print("Re-authenticating with Nous Portal...\n") + try: + mock_args = argparse.Namespace( + portal_url=None, inference_url=None, client_id=None, + scope=None, no_browser=False, timeout=15.0, + ca_bundle=None, insecure=False, + ) + _login_nous(mock_args, PROVIDER_REGISTRY["nous"]) + except Exception as login_exc: + print(f"Re-login failed: {login_exc}") + return + print(f"Could not verify credentials: {msg}") + return + + # Fetch live pricing (non-blocking — returns empty dict on failure) + pricing = get_pricing_for_provider("nous") + + # Check if user is on free tier + free_tier = check_nous_free_tier() + + # For both tiers: apply the allowlist filter first (removes non-allowlisted + # free models and allowlist models that aren't actually free). + # Then for free users: partition remaining models into selectable/unavailable. + model_ids = filter_nous_free_models(model_ids, pricing) + unavailable_models: list[str] = [] + if free_tier: + model_ids, unavailable_models = partition_nous_models_by_tier(model_ids, pricing, free_tier=True) + + if not model_ids and not unavailable_models: + print("No models available for Nous Portal after filtering.") + return + + # Resolve portal URL for upgrade links (may differ on staging) + _nous_portal_url = "" + try: + _nous_state = get_provider_auth_state("nous") + if _nous_state: + _nous_portal_url = _nous_state.get("portal_base_url", "") + except Exception: + pass + + if free_tier and not model_ids: + print("No free models currently available.") + if unavailable_models: + from hermes_cli.auth import DEFAULT_NOUS_PORTAL_URL + _url = (_nous_portal_url or DEFAULT_NOUS_PORTAL_URL).rstrip("/") + print(f"Upgrade at {_url} to access paid models.") + return + + print(f"Showing {len(model_ids)} curated models — use \"Enter custom model name\" for others.") + + selected = _prompt_model_selection( + model_ids, current_model=current_model, pricing=pricing, + unavailable_models=unavailable_models, portal_url=_nous_portal_url, + ) + if selected: + _save_model_choice(selected) + # Reactivate Nous as the provider and update config + inference_url = creds.get("base_url", "") + _update_config_for_provider("nous", inference_url) + current_model_cfg = config.get("model") + if isinstance(current_model_cfg, dict): + model_cfg = dict(current_model_cfg) + elif isinstance(current_model_cfg, str) and current_model_cfg.strip(): + model_cfg = {"default": current_model_cfg.strip()} + else: + model_cfg = {} + model_cfg["provider"] = "nous" + model_cfg["default"] = selected + if inference_url and inference_url.strip(): + model_cfg["base_url"] = inference_url.rstrip("/") + else: + model_cfg.pop("base_url", None) + config["model"] = model_cfg + # Clear any custom endpoint that might conflict + if get_env_value("OPENAI_BASE_URL"): + save_env_value("OPENAI_BASE_URL", "") + save_env_value("OPENAI_API_KEY", "") + changed_defaults = apply_nous_provider_defaults(config) + save_config(config) + print(f"Default model set to: {selected} (via Nous Portal)") + if "tts" in changed_defaults: + print("TTS provider set to: OpenAI TTS via your Nous subscription") + else: + current_tts = str(config.get("tts", {}).get("provider") or "edge") + if current_tts.lower() not in {"", "edge"}: + print(f"Keeping your existing TTS provider: {current_tts}") + print() + for line in get_nous_subscription_explainer_lines(): + print(line) + else: + print("No change.") + + +def _model_flow_openai_codex(config, current_model=""): + """OpenAI Codex provider: ensure logged in, then pick model.""" + from hermes_cli.auth import ( + get_codex_auth_status, _prompt_model_selection, _save_model_choice, + _update_config_for_provider, _login_openai_codex, + PROVIDER_REGISTRY, DEFAULT_CODEX_BASE_URL, + ) + from hermes_cli.codex_models import get_codex_model_ids + import argparse + + status = get_codex_auth_status() + if not status.get("logged_in"): + print("Not logged into OpenAI Codex. Starting login...") + print() + try: + mock_args = argparse.Namespace() + _login_openai_codex(mock_args, PROVIDER_REGISTRY["openai-codex"]) + except SystemExit: + print("Login cancelled or failed.") + return + except Exception as exc: + print(f"Login failed: {exc}") + return + + _codex_token = None + # Prefer credential pool (where `hermes auth` stores device_code tokens), + # fall back to legacy provider state. + try: + _codex_status = get_codex_auth_status() + if _codex_status.get("logged_in"): + _codex_token = _codex_status.get("api_key") + except Exception: + pass + if not _codex_token: + try: + from hermes_cli.auth import resolve_codex_runtime_credentials + _codex_creds = resolve_codex_runtime_credentials() + _codex_token = _codex_creds.get("api_key") + except Exception: + pass + + codex_models = get_codex_model_ids(access_token=_codex_token) + + selected = _prompt_model_selection(codex_models, current_model=current_model) + if selected: + _save_model_choice(selected) + _update_config_for_provider("openai-codex", DEFAULT_CODEX_BASE_URL) + print(f"Default model set to: {selected} (via OpenAI Codex)") + else: + print("No change.") + + + +_DEFAULT_QWEN_PORTAL_MODELS = [ + "qwen3-coder-plus", + "qwen3-coder", +] + + +def _model_flow_qwen_oauth(_config, current_model=""): + """Qwen OAuth provider: reuse local Qwen CLI login, then pick model.""" + from hermes_cli.auth import ( + get_qwen_auth_status, + resolve_qwen_runtime_credentials, + _prompt_model_selection, + _save_model_choice, + _update_config_for_provider, + DEFAULT_QWEN_BASE_URL, + ) + from hermes_cli.models import fetch_api_models + + status = get_qwen_auth_status() + if not status.get("logged_in"): + print("Not logged into Qwen CLI OAuth.") + print("Run: qwen auth qwen-oauth") + auth_file = status.get("auth_file") + if auth_file: + print(f"Expected credentials file: {auth_file}") + if status.get("error"): + print(f"Error: {status.get('error')}") + return + + # Try live model discovery, fall back to curated list. + models = None + try: + creds = resolve_qwen_runtime_credentials(refresh_if_expiring=True) + models = fetch_api_models(creds["api_key"], creds["base_url"]) + except Exception: + pass + if not models: + models = list(_DEFAULT_QWEN_PORTAL_MODELS) + + default = current_model or (models[0] if models else "qwen3-coder-plus") + selected = _prompt_model_selection(models, current_model=default) + if selected: + _save_model_choice(selected) + _update_config_for_provider("qwen-oauth", DEFAULT_QWEN_BASE_URL) + print(f"Default model set to: {selected} (via Qwen OAuth)") + else: + print("No change.") + + + +def _model_flow_custom(config): + """Custom endpoint: collect URL, API key, and model name. + + Automatically saves the endpoint to ``custom_providers`` in config.yaml + so it appears in the provider menu on subsequent runs. + """ + from hermes_cli.auth import _save_model_choice, deactivate_provider + from hermes_cli.config import get_env_value, load_config, save_config + + current_url = get_env_value("OPENAI_BASE_URL") or "" + current_key = get_env_value("OPENAI_API_KEY") or "" + + print("Custom OpenAI-compatible endpoint configuration:") + if current_url: + print(f" Current URL: {current_url}") + if current_key: + print(f" Current key: {current_key[:8]}...") + print() + + try: + base_url = input(f"API base URL [{current_url or 'e.g. https://api.example.com/v1'}]: ").strip() + import getpass + api_key = getpass.getpass(f"API key [{current_key[:8] + '...' if current_key else 'optional'}]: ").strip() + except (KeyboardInterrupt, EOFError): + print("\nCancelled.") + return + + if not base_url and not current_url: + print("No URL provided. Cancelled.") + return + + # Validate URL format + effective_url = base_url or current_url + if not effective_url.startswith(("http://", "https://")): + print(f"Invalid URL: {effective_url} (must start with http:// or https://)") + return + + effective_key = api_key or current_key + + from hermes_cli.models import probe_api_models + + probe = probe_api_models(effective_key, effective_url) + if probe.get("used_fallback") and probe.get("resolved_base_url"): + print( + f"Warning: endpoint verification worked at {probe['resolved_base_url']}/models, " + f"not the exact URL you entered. Saving the working base URL instead." + ) + effective_url = probe["resolved_base_url"] + if base_url: + base_url = effective_url + elif probe.get("models") is not None: + print( + f"Verified endpoint via {probe.get('probed_url')} " + f"({len(probe.get('models') or [])} model(s) visible)" + ) + else: + print( + f"Warning: could not verify this endpoint via {probe.get('probed_url')}. " + f"Hermes will still save it." + ) + if probe.get("suggested_base_url"): + suggested = probe["suggested_base_url"] + if suggested.endswith("/v1"): + print(f" If this server expects /v1 in the path, try base URL: {suggested}") + else: + print(f" If /v1 should not be in the base URL, try: {suggested}") + + # Select model — use probe results when available, fall back to manual input + model_name = "" + detected_models = probe.get("models") or [] + try: + if len(detected_models) == 1: + print(f" Detected model: {detected_models[0]}") + confirm = input(" Use this model? [Y/n]: ").strip().lower() + if confirm in ("", "y", "yes"): + model_name = detected_models[0] + else: + model_name = input("Model name (e.g. gpt-4, llama-3-70b): ").strip() + elif len(detected_models) > 1: + print(" Available models:") + for i, m in enumerate(detected_models, 1): + print(f" {i}. {m}") + pick = input(f" Select model [1-{len(detected_models)}] or type name: ").strip() + if pick.isdigit() and 1 <= int(pick) <= len(detected_models): + model_name = detected_models[int(pick) - 1] + elif pick: + model_name = pick + else: + model_name = input("Model name (e.g. gpt-4, llama-3-70b): ").strip() + + context_length_str = input("Context length in tokens [leave blank for auto-detect]: ").strip() + + # Prompt for a display name — shown in the provider menu on future runs + default_name = _auto_provider_name(effective_url) + display_name = input(f"Display name [{default_name}]: ").strip() or default_name + except (KeyboardInterrupt, EOFError): + print("\nCancelled.") + return + + context_length = None + if context_length_str: + try: + context_length = int(context_length_str.replace(",", "").replace("k", "000").replace("K", "000")) + if context_length <= 0: + context_length = None + except ValueError: + print(f"Invalid context length: {context_length_str} — will auto-detect.") + context_length = None + + if model_name: + _save_model_choice(model_name) + + # Update config and deactivate any OAuth provider + cfg = load_config() + model = cfg.get("model") + if not isinstance(model, dict): + model = {"default": model} if model else {} + cfg["model"] = model + model["provider"] = "custom" + model["base_url"] = effective_url + if effective_key: + model["api_key"] = effective_key + model.pop("api_mode", None) # let runtime auto-detect from URL + save_config(cfg) + deactivate_provider() + + # Sync the caller's config dict so the setup wizard's final + # save_config(config) preserves our model settings. Without + # this, the wizard overwrites model.provider/base_url with + # the stale values from its own config dict (#4172). + config["model"] = dict(model) + + print(f"Default model set to: {model_name} (via {effective_url})") + else: + if base_url or api_key: + deactivate_provider() + # Even without a model name, persist the custom endpoint on the + # caller's config dict so the setup wizard doesn't lose it. + _caller_model = config.get("model") + if not isinstance(_caller_model, dict): + _caller_model = {"default": _caller_model} if _caller_model else {} + _caller_model["provider"] = "custom" + _caller_model["base_url"] = effective_url + if effective_key: + _caller_model["api_key"] = effective_key + _caller_model.pop("api_mode", None) + config["model"] = _caller_model + print("Endpoint saved. Use `/model` in chat or `hermes model` to set a model.") + + # Auto-save to custom_providers so it appears in the menu next time + _save_custom_provider(effective_url, effective_key, model_name or "", + context_length=context_length, name=display_name) + + +def _auto_provider_name(base_url: str) -> str: + """Generate a display name from a custom endpoint URL. + + Returns a human-friendly label like "Local (localhost:11434)" or + "RunPod (xyz.runpod.io)". Used as the default when prompting the + user for a display name during custom endpoint setup. + """ + import re + clean = base_url.replace("https://", "").replace("http://", "").rstrip("/") + clean = re.sub(r"/v1/?$", "", clean) + name = clean.split("/")[0] + if "localhost" in name or "127.0.0.1" in name: + name = f"Local ({name})" + elif "runpod" in name.lower(): + name = f"RunPod ({name})" + else: + name = name.capitalize() + return name + + +def _save_custom_provider(base_url, api_key="", model="", context_length=None, + name=None): + """Save a custom endpoint to custom_providers in config.yaml. + + Deduplicates by base_url — if the URL already exists, updates the + model name and context_length but doesn't add a duplicate entry. + Uses *name* when provided, otherwise auto-generates from the URL. + """ + from hermes_cli.config import load_config, save_config + + cfg = load_config() + providers = cfg.get("custom_providers") or [] + if not isinstance(providers, list): + providers = [] + + # Check if this URL is already saved — update model/context_length if so + for entry in providers: + if isinstance(entry, dict) and entry.get("base_url", "").rstrip("/") == base_url.rstrip("/"): + changed = False + if model and entry.get("model") != model: + entry["model"] = model + changed = True + if model and context_length: + models_cfg = entry.get("models", {}) + if not isinstance(models_cfg, dict): + models_cfg = {} + models_cfg[model] = {"context_length": context_length} + entry["models"] = models_cfg + changed = True + if changed: + cfg["custom_providers"] = providers + save_config(cfg) + return # already saved, updated if needed + + # Use provided name or auto-generate from URL + if not name: + name = _auto_provider_name(base_url) + + entry = {"name": name, "base_url": base_url} + if api_key: + entry["api_key"] = api_key + if model: + entry["model"] = model + if model and context_length: + entry["models"] = {model: {"context_length": context_length}} + + providers.append(entry) + cfg["custom_providers"] = providers + save_config(cfg) + print(f" 💾 Saved to custom providers as \"{name}\" (edit in config.yaml)") + + +def _remove_custom_provider(config): + """Let the user remove a saved custom provider from config.yaml.""" + from hermes_cli.config import load_config, save_config + + cfg = load_config() + providers = cfg.get("custom_providers") or [] + if not isinstance(providers, list) or not providers: + print("No custom providers configured.") + return + + print("Remove a custom provider:\n") + + choices = [] + for entry in providers: + if isinstance(entry, dict): + name = entry.get("name", "unnamed") + url = entry.get("base_url", "") + short_url = url.replace("https://", "").replace("http://", "").rstrip("/") + choices.append(f"{name} ({short_url})") + else: + choices.append(str(entry)) + choices.append("Cancel") + + try: + from simple_term_menu import TerminalMenu + menu = TerminalMenu( + [f" {c}" for c in choices], cursor_index=0, + menu_cursor="-> ", menu_cursor_style=("fg_red", "bold"), + menu_highlight_style=("fg_red",), + cycle_cursor=True, clear_screen=False, + title="Select provider to remove:", + ) + idx = menu.show() + from hermes_cli.curses_ui import flush_stdin + flush_stdin() + print() + except (ImportError, NotImplementedError, OSError, subprocess.SubprocessError): + for i, c in enumerate(choices, 1): + print(f" {i}. {c}") + print() + try: + val = input(f"Choice [1-{len(choices)}]: ").strip() + idx = int(val) - 1 if val else None + except (ValueError, KeyboardInterrupt, EOFError): + idx = None + + if idx is None or idx >= len(providers): + print("No change.") + return + + removed = providers.pop(idx) + cfg["custom_providers"] = providers + save_config(cfg) + removed_name = removed.get("name", "unnamed") if isinstance(removed, dict) else str(removed) + print(f"✅ Removed \"{removed_name}\" from custom providers.") + + +def _model_flow_named_custom(config, provider_info): + """Handle a named custom provider from config.yaml custom_providers list. + + Always probes the endpoint's /models API to let the user pick a model. + If a model was previously saved, it is pre-selected in the menu. + Falls back to the saved model if probing fails. + """ + from hermes_cli.auth import _save_model_choice, deactivate_provider + from hermes_cli.config import load_config, save_config + from hermes_cli.models import fetch_api_models + + name = provider_info["name"] + base_url = provider_info["base_url"] + api_key = provider_info.get("api_key", "") + key_env = provider_info.get("key_env", "") + saved_model = provider_info.get("model", "") + provider_key = (provider_info.get("provider_key") or "").strip() + + print(f" Provider: {name}") + print(f" URL: {base_url}") + if saved_model: + print(f" Current: {saved_model}") + print() + + print("Fetching available models...") + models = fetch_api_models(api_key, base_url, timeout=8.0) + + if models: + default_idx = 0 + if saved_model and saved_model in models: + default_idx = models.index(saved_model) + + print(f"Found {len(models)} model(s):\n") + try: + from simple_term_menu import TerminalMenu + menu_items = [ + f" {m} (current)" if m == saved_model else f" {m}" + for m in models + ] + [" Cancel"] + menu = TerminalMenu( + menu_items, cursor_index=default_idx, + menu_cursor="-> ", menu_cursor_style=("fg_green", "bold"), + menu_highlight_style=("fg_green",), + cycle_cursor=True, clear_screen=False, + title=f"Select model from {name}:", + ) + idx = menu.show() + from hermes_cli.curses_ui import flush_stdin + flush_stdin() + print() + if idx is None or idx >= len(models): + print("Cancelled.") + return + model_name = models[idx] + except (ImportError, NotImplementedError, OSError, subprocess.SubprocessError): + for i, m in enumerate(models, 1): + suffix = " (current)" if m == saved_model else "" + print(f" {i}. {m}{suffix}") + print(f" {len(models) + 1}. Cancel") + print() + try: + val = input(f"Choice [1-{len(models) + 1}]: ").strip() + if not val: + print("Cancelled.") + return + idx = int(val) - 1 + if idx < 0 or idx >= len(models): + print("Cancelled.") + return + model_name = models[idx] + except (ValueError, KeyboardInterrupt, EOFError): + print("\nCancelled.") + return + elif saved_model: + print("Could not fetch models from endpoint.") + try: + model_name = input(f"Model name [{saved_model}]: ").strip() or saved_model + except (KeyboardInterrupt, EOFError): + print("\nCancelled.") + return + else: + print("Could not fetch models from endpoint. Enter model name manually.") + try: + model_name = input("Model name: ").strip() + except (KeyboardInterrupt, EOFError): + print("\nCancelled.") + return + if not model_name: + print("No model specified. Cancelled.") + return + + # Activate and save the model to the custom_providers entry + _save_model_choice(model_name) + + cfg = load_config() + model = cfg.get("model") + if not isinstance(model, dict): + model = {"default": model} if model else {} + cfg["model"] = model + if provider_key: + model["provider"] = provider_key + model.pop("base_url", None) + model.pop("api_key", None) + else: + model["provider"] = "custom" + model["base_url"] = base_url + if api_key: + model["api_key"] = api_key + # Apply api_mode from custom_providers entry, or clear stale value + custom_api_mode = provider_info.get("api_mode", "") + if custom_api_mode: + model["api_mode"] = custom_api_mode + else: + model.pop("api_mode", None) # let runtime auto-detect from URL + save_config(cfg) + deactivate_provider() + + # Persist the selected model back to whichever schema owns this endpoint. + if provider_key: + cfg = load_config() + providers_cfg = cfg.get("providers") + if isinstance(providers_cfg, dict): + provider_entry = providers_cfg.get(provider_key) + if isinstance(provider_entry, dict): + provider_entry["default_model"] = model_name + if api_key and not str(provider_entry.get("api_key", "") or "").strip(): + provider_entry["api_key"] = api_key + if key_env and not str(provider_entry.get("key_env", "") or "").strip(): + provider_entry["key_env"] = key_env + cfg["providers"] = providers_cfg + save_config(cfg) + else: + # Save model name to the custom_providers entry for next time + _save_custom_provider(base_url, api_key, model_name) + + print(f"\n✅ Model set to: {model_name}") + print(f" Provider: {name} ({base_url})") + + +# Curated model lists for direct API-key providers — single source in models.py +from hermes_cli.models import _PROVIDER_MODELS + + +def _current_reasoning_effort(config) -> str: + agent_cfg = config.get("agent") + if isinstance(agent_cfg, dict): + return str(agent_cfg.get("reasoning_effort") or "").strip().lower() + return "" + + +def _set_reasoning_effort(config, effort: str) -> None: + agent_cfg = config.get("agent") + if not isinstance(agent_cfg, dict): + agent_cfg = {} + config["agent"] = agent_cfg + agent_cfg["reasoning_effort"] = effort + + +def _prompt_reasoning_effort_selection(efforts, current_effort=""): + """Prompt for a reasoning effort. Returns effort, 'none', or None to keep current.""" + deduped = list(dict.fromkeys(str(effort).strip().lower() for effort in efforts if str(effort).strip())) + canonical_order = ("minimal", "low", "medium", "high", "xhigh") + ordered = [effort for effort in canonical_order if effort in deduped] + ordered.extend(effort for effort in deduped if effort not in canonical_order) + if not ordered: + return None + + def _label(effort): + if effort == current_effort: + return f"{effort} ← currently in use" + return effort + + disable_label = "Disable reasoning" + skip_label = "Skip (keep current)" + + if current_effort == "none": + default_idx = len(ordered) + elif current_effort in ordered: + default_idx = ordered.index(current_effort) + elif "medium" in ordered: + default_idx = ordered.index("medium") + else: + default_idx = 0 + + try: + from simple_term_menu import TerminalMenu + + choices = [f" {_label(effort)}" for effort in ordered] + choices.append(f" {disable_label}") + choices.append(f" {skip_label}") + menu = TerminalMenu( + choices, + cursor_index=default_idx, + menu_cursor="-> ", + menu_cursor_style=("fg_green", "bold"), + menu_highlight_style=("fg_green",), + cycle_cursor=True, + clear_screen=False, + title="Select reasoning effort:", + ) + idx = menu.show() + from hermes_cli.curses_ui import flush_stdin + flush_stdin() + if idx is None: + return None + print() + if idx < len(ordered): + return ordered[idx] + if idx == len(ordered): + return "none" + return None + except (ImportError, NotImplementedError, OSError, subprocess.SubprocessError): + pass + + print("Select reasoning effort:") + for i, effort in enumerate(ordered, 1): + print(f" {i}. {_label(effort)}") + n = len(ordered) + print(f" {n + 1}. {disable_label}") + print(f" {n + 2}. {skip_label}") + print() + + while True: + try: + choice = input(f"Choice [1-{n + 2}] (default: keep current): ").strip() + if not choice: + return None + idx = int(choice) + if 1 <= idx <= n: + return ordered[idx - 1] + if idx == n + 1: + return "none" + if idx == n + 2: + return None + print(f"Please enter 1-{n + 2}") + except ValueError: + print("Please enter a number") + except (KeyboardInterrupt, EOFError): + return None + + +def _model_flow_copilot(config, current_model=""): + """GitHub Copilot flow using env vars, gh CLI, or OAuth device code.""" + from hermes_cli.auth import ( + PROVIDER_REGISTRY, + _prompt_model_selection, + _save_model_choice, + deactivate_provider, + resolve_api_key_provider_credentials, + ) + from hermes_cli.config import save_env_value, load_config, save_config + from hermes_cli.models import ( + fetch_api_models, + fetch_github_model_catalog, + github_model_reasoning_efforts, + copilot_model_api_mode, + normalize_copilot_model_id, + ) + + provider_id = "copilot" + pconfig = PROVIDER_REGISTRY[provider_id] + + creds = resolve_api_key_provider_credentials(provider_id) + api_key = creds.get("api_key", "") + source = creds.get("source", "") + + if not api_key: + print("No GitHub token configured for GitHub Copilot.") + print() + print(" Supported token types:") + print(" → OAuth token (gho_*) via `copilot login` or device code flow") + print(" → Fine-grained PAT (github_pat_*) with Copilot Requests permission") + print(" → GitHub App token (ghu_*) via environment variable") + print(" ✗ Classic PAT (ghp_*) NOT supported by Copilot API") + print() + print(" Options:") + print(" 1. Login with GitHub (OAuth device code flow)") + print(" 2. Enter a token manually") + print(" 3. Cancel") + print() + try: + choice = input(" Choice [1-3]: ").strip() + except (KeyboardInterrupt, EOFError): + print() + return + + if choice == "1": + try: + from hermes_cli.copilot_auth import copilot_device_code_login + token = copilot_device_code_login() + if token: + save_env_value("COPILOT_GITHUB_TOKEN", token) + print(" Copilot token saved.") + print() + else: + print(" Login cancelled or failed.") + return + except Exception as exc: + print(f" Login failed: {exc}") + return + elif choice == "2": + try: + import getpass + new_key = getpass.getpass(" Token (COPILOT_GITHUB_TOKEN): ").strip() + except (KeyboardInterrupt, EOFError): + print() + return + if not new_key: + print(" Cancelled.") + return + # Validate token type + try: + from hermes_cli.copilot_auth import validate_copilot_token + valid, msg = validate_copilot_token(new_key) + if not valid: + print(f" ✗ {msg}") + return + except ImportError: + pass + save_env_value("COPILOT_GITHUB_TOKEN", new_key) + print(" Token saved.") + print() + else: + print(" Cancelled.") + return + + creds = resolve_api_key_provider_credentials(provider_id) + api_key = creds.get("api_key", "") + source = creds.get("source", "") + else: + if source in ("GITHUB_TOKEN", "GH_TOKEN"): + print(f" GitHub token: {api_key[:8]}... ✓ ({source})") + elif source == "gh auth token": + print(" GitHub token: ✓ (from `gh auth token`)") + else: + print(" GitHub token: ✓") + print() + + effective_base = pconfig.inference_base_url + + catalog = fetch_github_model_catalog(api_key) + live_models = [item.get("id", "") for item in catalog if item.get("id")] if catalog else fetch_api_models(api_key, effective_base) + normalized_current_model = normalize_copilot_model_id( + current_model, + catalog=catalog, + api_key=api_key, + ) or current_model + if live_models: + model_list = [model_id for model_id in live_models if model_id] + print(f" Found {len(model_list)} model(s) from GitHub Copilot") + else: + model_list = _PROVIDER_MODELS.get(provider_id, []) + if model_list: + print(" ⚠ Could not auto-detect models from GitHub Copilot — showing defaults.") + print(' Use "Enter custom model name" if you do not see your model.') + + if model_list: + selected = _prompt_model_selection(model_list, current_model=normalized_current_model) + else: + try: + selected = input("Model name: ").strip() + except (KeyboardInterrupt, EOFError): + selected = None + + if selected: + selected = normalize_copilot_model_id( + selected, + catalog=catalog, + api_key=api_key, + ) or selected + initial_cfg = load_config() + current_effort = _current_reasoning_effort(initial_cfg) + reasoning_efforts = github_model_reasoning_efforts( + selected, + catalog=catalog, + api_key=api_key, + ) + selected_effort = None + if reasoning_efforts: + print(f" {selected} supports reasoning controls.") + selected_effort = _prompt_reasoning_effort_selection( + reasoning_efforts, current_effort=current_effort + ) + + _save_model_choice(selected) + + cfg = load_config() + model = cfg.get("model") + if not isinstance(model, dict): + model = {"default": model} if model else {} + cfg["model"] = model + model["provider"] = provider_id + model["base_url"] = effective_base + model["api_mode"] = copilot_model_api_mode( + selected, + catalog=catalog, + api_key=api_key, + ) + if selected_effort is not None: + _set_reasoning_effort(cfg, selected_effort) + save_config(cfg) + deactivate_provider() + + print(f"Default model set to: {selected} (via {pconfig.name})") + if reasoning_efforts: + if selected_effort == "none": + print("Reasoning disabled for this model.") + elif selected_effort: + print(f"Reasoning effort set to: {selected_effort}") + else: + print("No change.") + + +def _model_flow_copilot_acp(config, current_model=""): + """GitHub Copilot ACP flow using the local Copilot CLI.""" + from hermes_cli.auth import ( + PROVIDER_REGISTRY, + _prompt_model_selection, + _save_model_choice, + deactivate_provider, + get_external_process_provider_status, + resolve_api_key_provider_credentials, + resolve_external_process_provider_credentials, + ) + from hermes_cli.models import ( + fetch_github_model_catalog, + normalize_copilot_model_id, + ) + from hermes_cli.config import load_config, save_config + + del config + + provider_id = "copilot-acp" + pconfig = PROVIDER_REGISTRY[provider_id] + + status = get_external_process_provider_status(provider_id) + resolved_command = status.get("resolved_command") or status.get("command") or "copilot" + effective_base = status.get("base_url") or pconfig.inference_base_url + + print(" GitHub Copilot ACP delegates Hermes turns to `copilot --acp`.") + print(" Hermes currently starts its own ACP subprocess for each request.") + print(" Hermes uses your selected model as a hint for the Copilot ACP session.") + print(f" Command: {resolved_command}") + print(f" Backend marker: {effective_base}") + print() + + try: + creds = resolve_external_process_provider_credentials(provider_id) + except Exception as exc: + print(f" ⚠ {exc}") + print(" Set HERMES_COPILOT_ACP_COMMAND or COPILOT_CLI_PATH if Copilot CLI is installed elsewhere.") + return + + effective_base = creds.get("base_url") or effective_base + + catalog_api_key = "" + try: + catalog_creds = resolve_api_key_provider_credentials("copilot") + catalog_api_key = catalog_creds.get("api_key", "") + except Exception: + pass + + catalog = fetch_github_model_catalog(catalog_api_key) + normalized_current_model = normalize_copilot_model_id( + current_model, + catalog=catalog, + api_key=catalog_api_key, + ) or current_model + + if catalog: + model_list = [item.get("id", "") for item in catalog if item.get("id")] + print(f" Found {len(model_list)} model(s) from GitHub Copilot") + else: + model_list = _PROVIDER_MODELS.get("copilot", []) + if model_list: + print(" ⚠ Could not auto-detect models from GitHub Copilot — showing defaults.") + print(' Use "Enter custom model name" if you do not see your model.') + + if model_list: + selected = _prompt_model_selection( + model_list, + current_model=normalized_current_model, + ) + else: + try: + selected = input("Model name: ").strip() + except (KeyboardInterrupt, EOFError): + selected = None + + if not selected: + print("No change.") + return + + selected = normalize_copilot_model_id( + selected, + catalog=catalog, + api_key=catalog_api_key, + ) or selected + _save_model_choice(selected) + + cfg = load_config() + model = cfg.get("model") + if not isinstance(model, dict): + model = {"default": model} if model else {} + cfg["model"] = model + model["provider"] = provider_id + model["base_url"] = effective_base + model["api_mode"] = "chat_completions" + save_config(cfg) + deactivate_provider() + + print(f"Default model set to: {selected} (via {pconfig.name})") + + +def _model_flow_kimi(config, current_model=""): + """Kimi / Moonshot model selection with automatic endpoint routing. + + - sk-kimi-* keys → api.kimi.com/coding/v1 (Kimi Coding Plan) + - Other keys → api.moonshot.ai/v1 (legacy Moonshot) + + No manual base URL prompt — endpoint is determined by key prefix. + """ + from hermes_cli.auth import ( + PROVIDER_REGISTRY, KIMI_CODE_BASE_URL, _prompt_model_selection, + _save_model_choice, deactivate_provider, + ) + from hermes_cli.config import get_env_value, save_env_value, load_config, save_config + + provider_id = "kimi-coding" + pconfig = PROVIDER_REGISTRY[provider_id] + key_env = pconfig.api_key_env_vars[0] if pconfig.api_key_env_vars else "" + base_url_env = pconfig.base_url_env_var or "" + + # Step 1: Check / prompt for API key + existing_key = "" + for ev in pconfig.api_key_env_vars: + existing_key = get_env_value(ev) or os.getenv(ev, "") + if existing_key: + break + + if not existing_key: + print(f"No {pconfig.name} API key configured.") + if key_env: + try: + import getpass + new_key = getpass.getpass(f"{key_env} (or Enter to cancel): ").strip() + except (KeyboardInterrupt, EOFError): + print() + return + if not new_key: + print("Cancelled.") + return + save_env_value(key_env, new_key) + existing_key = new_key + print("API key saved.") + print() + else: + print(f" {pconfig.name} API key: {existing_key[:8]}... ✓") + print() + + # Step 2: Auto-detect endpoint from key prefix + is_coding_plan = existing_key.startswith("sk-kimi-") + if is_coding_plan: + effective_base = KIMI_CODE_BASE_URL + print(f" Detected Kimi Coding Plan key → {effective_base}") + else: + effective_base = pconfig.inference_base_url + print(f" Using Moonshot endpoint → {effective_base}") + # Clear any manual base URL override so auto-detection works at runtime + if base_url_env and get_env_value(base_url_env): + save_env_value(base_url_env, "") + print() + + # Step 3: Model selection — show appropriate models for the endpoint + if is_coding_plan: + # Coding Plan models (kimi-for-coding first) + model_list = [ + "kimi-for-coding", + "kimi-k2.5", + "kimi-k2-thinking", + "kimi-k2-thinking-turbo", + ] + else: + # Legacy Moonshot models (excludes Coding Plan-only models) + model_list = _PROVIDER_MODELS.get("moonshot", []) + + if model_list: + selected = _prompt_model_selection(model_list, current_model=current_model) + else: + try: + selected = input("Enter model name: ").strip() + except (KeyboardInterrupt, EOFError): + selected = None + + if selected: + _save_model_choice(selected) + + # Update config with provider and base URL + cfg = load_config() + model = cfg.get("model") + if not isinstance(model, dict): + model = {"default": model} if model else {} + cfg["model"] = model + model["provider"] = provider_id + model["base_url"] = effective_base + model.pop("api_mode", None) # let runtime auto-detect from URL + save_config(cfg) + deactivate_provider() + + endpoint_label = "Kimi Coding" if is_coding_plan else "Moonshot" + print(f"Default model set to: {selected} (via {endpoint_label})") + else: + print("No change.") + + +def _model_flow_api_key_provider(config, provider_id, current_model=""): + """Generic flow for API-key providers (z.ai, MiniMax, OpenCode, etc.).""" + from hermes_cli.auth import ( + PROVIDER_REGISTRY, _prompt_model_selection, _save_model_choice, + deactivate_provider, + ) + from hermes_cli.config import get_env_value, save_env_value, load_config, save_config + from hermes_cli.models import fetch_api_models, opencode_model_api_mode, normalize_opencode_model_id + + pconfig = PROVIDER_REGISTRY[provider_id] + key_env = pconfig.api_key_env_vars[0] if pconfig.api_key_env_vars else "" + base_url_env = pconfig.base_url_env_var or "" + + # Check / prompt for API key + existing_key = "" + for ev in pconfig.api_key_env_vars: + existing_key = get_env_value(ev) or os.getenv(ev, "") + if existing_key: + break + + if not existing_key: + print(f"No {pconfig.name} API key configured.") + if key_env: + try: + import getpass + new_key = getpass.getpass(f"{key_env} (or Enter to cancel): ").strip() + except (KeyboardInterrupt, EOFError): + print() + return + if not new_key: + print("Cancelled.") + return + save_env_value(key_env, new_key) + print("API key saved.") + print() + else: + print(f" {pconfig.name} API key: {existing_key[:8]}... ✓") + print() + + # Optional base URL override + current_base = "" + if base_url_env: + current_base = get_env_value(base_url_env) or os.getenv(base_url_env, "") + effective_base = current_base or pconfig.inference_base_url + + try: + override = input(f"Base URL [{effective_base}]: ").strip() + except (KeyboardInterrupt, EOFError): + print() + override = "" + if override and base_url_env: + if not override.startswith(("http://", "https://")): + print(" Invalid URL — must start with http:// or https://. Keeping current value.") + else: + save_env_value(base_url_env, override) + effective_base = override + + # Model selection — resolution order: + # 1. models.dev registry (cached, filtered for agentic/tool-capable models) + # 2. Curated static fallback list (offline insurance) + # 3. Live /models endpoint probe (small providers without models.dev data) + curated = _PROVIDER_MODELS.get(provider_id, []) + + # Try models.dev first — returns tool-capable models, filtered for noise + mdev_models: list = [] + try: + from agent.models_dev import list_agentic_models + mdev_models = list_agentic_models(provider_id) + except Exception: + pass + + if mdev_models: + model_list = mdev_models + print(f" Found {len(model_list)} model(s) from models.dev registry") + elif curated and len(curated) >= 8: + # Curated list is substantial — use it directly, skip live probe + model_list = curated + print(f" Showing {len(model_list)} curated models — use \"Enter custom model name\" for others.") + else: + api_key_for_probe = existing_key or (get_env_value(key_env) if key_env else "") + live_models = fetch_api_models(api_key_for_probe, effective_base) + if live_models and len(live_models) >= len(curated): + model_list = live_models + print(f" Found {len(model_list)} model(s) from {pconfig.name} API") + else: + model_list = curated + if model_list: + print(f" Showing {len(model_list)} curated models — use \"Enter custom model name\" for others.") + # else: no defaults either, will fall through to raw input + + if provider_id in {"opencode-zen", "opencode-go"}: + model_list = [normalize_opencode_model_id(provider_id, mid) for mid in model_list] + current_model = normalize_opencode_model_id(provider_id, current_model) + model_list = list(dict.fromkeys(mid for mid in model_list if mid)) + + if model_list: + selected = _prompt_model_selection(model_list, current_model=current_model) + else: + try: + selected = input("Model name: ").strip() + except (KeyboardInterrupt, EOFError): + selected = None + + if selected: + if provider_id in {"opencode-zen", "opencode-go"}: + selected = normalize_opencode_model_id(provider_id, selected) + + _save_model_choice(selected) + + # Update config with provider, base URL, and provider-specific API mode + cfg = load_config() + model = cfg.get("model") + if not isinstance(model, dict): + model = {"default": model} if model else {} + cfg["model"] = model + model["provider"] = provider_id + model["base_url"] = effective_base + if provider_id in {"opencode-zen", "opencode-go"}: + model["api_mode"] = opencode_model_api_mode(provider_id, selected) + else: + model.pop("api_mode", None) + save_config(cfg) + deactivate_provider() + + print(f"Default model set to: {selected} (via {pconfig.name})") + else: + print("No change.") + + +def _run_anthropic_oauth_flow(save_env_value): + """Run the Claude OAuth setup-token flow. Returns True if credentials were saved.""" + from agent.anthropic_adapter import ( + run_oauth_setup_token, + read_claude_code_credentials, + is_claude_code_token_valid, + ) + from hermes_cli.config import ( + save_anthropic_oauth_token, + use_anthropic_claude_code_credentials, + ) + + def _activate_claude_code_credentials_if_available() -> bool: + try: + creds = read_claude_code_credentials() + except Exception: + creds = None + if creds and ( + is_claude_code_token_valid(creds) + or bool(creds.get("refreshToken")) + ): + use_anthropic_claude_code_credentials(save_fn=save_env_value) + print(" ✓ Claude Code credentials linked.") + from hermes_constants import display_hermes_home as _dhh_fn + print(f" Hermes will use Claude's credential store directly instead of copying a setup-token into {_dhh_fn()}/.env.") + return True + return False + + try: + print() + print(" Running 'claude setup-token' — follow the prompts below.") + print(" A browser window will open for you to authorize access.") + print() + token = run_oauth_setup_token() + if token: + if _activate_claude_code_credentials_if_available(): + return True + save_anthropic_oauth_token(token, save_fn=save_env_value) + print(" ✓ OAuth credentials saved.") + return True + + # Subprocess completed but no token auto-detected — ask user to paste + print() + print(" If the setup-token was displayed above, paste it here:") + print() + try: + import getpass + manual_token = getpass.getpass(" Paste setup-token (or Enter to cancel): ").strip() + except (KeyboardInterrupt, EOFError): + print() + return False + if manual_token: + save_anthropic_oauth_token(manual_token, save_fn=save_env_value) + print(" ✓ Setup-token saved.") + return True + + print(" ⚠ Could not detect saved credentials.") + return False + + except FileNotFoundError: + # Claude CLI not installed — guide user through manual setup + print() + print(" The 'claude' CLI is required for OAuth login.") + print() + print(" To install and authenticate:") + print() + print(" 1. Install Claude Code: npm install -g @anthropic-ai/claude-code") + print(" 2. Run: claude setup-token") + print(" 3. Follow the browser prompts to authorize") + print(" 4. Re-run: hermes model") + print() + print(" Or paste an existing setup-token now (sk-ant-oat-...):") + print() + try: + import getpass + token = getpass.getpass(" Setup-token (or Enter to cancel): ").strip() + except (KeyboardInterrupt, EOFError): + print() + return False + if token: + save_anthropic_oauth_token(token, save_fn=save_env_value) + print(" ✓ Setup-token saved.") + return True + print(" Cancelled — install Claude Code and try again.") + return False + + +def _model_flow_anthropic(config, current_model=""): + """Flow for Anthropic provider — OAuth subscription, API key, or Claude Code creds.""" + from hermes_cli.auth import ( + _prompt_model_selection, _save_model_choice, + deactivate_provider, + ) + from hermes_cli.config import ( + save_env_value, load_config, save_config, + save_anthropic_api_key, + ) + from hermes_cli.models import _PROVIDER_MODELS + + # Check ALL credential sources + from hermes_cli.auth import get_anthropic_key + existing_key = get_anthropic_key() + cc_available = False + try: + from agent.anthropic_adapter import read_claude_code_credentials, is_claude_code_token_valid + cc_creds = read_claude_code_credentials() + if cc_creds and is_claude_code_token_valid(cc_creds): + cc_available = True + except Exception: + pass + + has_creds = bool(existing_key) or cc_available + needs_auth = not has_creds + + if has_creds: + # Show what we found + if existing_key: + print(f" Anthropic credentials: {existing_key[:12]}... ✓") + elif cc_available: + print(" Claude Code credentials: ✓ (auto-detected)") + print() + print(" 1. Use existing credentials") + print(" 2. Reauthenticate (new OAuth login)") + print(" 3. Cancel") + print() + try: + choice = input(" Choice [1/2/3]: ").strip() + except (KeyboardInterrupt, EOFError): + choice = "1" + + if choice == "2": + needs_auth = True + elif choice == "3": + return + # choice == "1" or default: use existing, proceed to model selection + + if needs_auth: + # Show auth method choice + print() + print(" Choose authentication method:") + print() + print(" 1. Claude Pro/Max subscription (OAuth login)") + print(" 2. Anthropic API key (pay-per-token)") + print(" 3. Cancel") + print() + try: + choice = input(" Choice [1/2/3]: ").strip() + except (KeyboardInterrupt, EOFError): + print() + return + + if choice == "1": + if not _run_anthropic_oauth_flow(save_env_value): + return + + elif choice == "2": + print() + print(" Get an API key at: https://console.anthropic.com/settings/keys") + print() + try: + import getpass + api_key = getpass.getpass(" API key (sk-ant-...): ").strip() + except (KeyboardInterrupt, EOFError): + print() + return + if not api_key: + print(" Cancelled.") + return + save_anthropic_api_key(api_key, save_fn=save_env_value) + print(" ✓ API key saved.") + + else: + print(" No change.") + return + print() + + # Model selection + model_list = _PROVIDER_MODELS.get("anthropic", []) + if model_list: + selected = _prompt_model_selection(model_list, current_model=current_model) + else: + try: + selected = input("Model name (e.g., claude-sonnet-4-20250514): ").strip() + except (KeyboardInterrupt, EOFError): + selected = None + + if selected: + _save_model_choice(selected) + + # Update config with provider — clear base_url since + # resolve_runtime_provider() always hardcodes Anthropic's URL. + # Leaving a stale base_url in config can contaminate other + # providers if the user switches without running 'hermes model'. + cfg = load_config() + model = cfg.get("model") + if not isinstance(model, dict): + model = {"default": model} if model else {} + cfg["model"] = model + model["provider"] = "anthropic" + model.pop("base_url", None) + save_config(cfg) + deactivate_provider() + + print(f"Default model set to: {selected} (via Anthropic)") + else: + print("No change.") + + +def cmd_login(args): + """Authenticate Hermes CLI with a provider.""" + from hermes_cli.auth import login_command + login_command(args) + + +def cmd_logout(args): + """Clear provider authentication.""" + from hermes_cli.auth import logout_command + logout_command(args) + + +def cmd_auth(args): + """Manage pooled credentials.""" + from hermes_cli.auth_commands import auth_command + auth_command(args) + + +def cmd_status(args): + """Show status of all components.""" + from hermes_cli.status import show_status + show_status(args) + + +def cmd_cron(args): + """Cron job management.""" + from hermes_cli.cron import cron_command + cron_command(args) + + +def cmd_webhook(args): + """Webhook subscription management.""" + from hermes_cli.webhook import webhook_command + webhook_command(args) + + +def cmd_doctor(args): + """Check configuration and dependencies.""" + from hermes_cli.doctor import run_doctor + run_doctor(args) + + +def cmd_dump(args): + """Dump setup summary for support/debugging.""" + from hermes_cli.dump import run_dump + run_dump(args) + + +def cmd_debug(args): + """Debug tools (share report, etc.).""" + from hermes_cli.debug import run_debug + run_debug(args) + + +def cmd_config(args): + """Configuration management.""" + from hermes_cli.config import config_command + config_command(args) + + +def cmd_backup(args): + """Back up Hermes home directory to a zip file.""" + if getattr(args, "quick", False): + from hermes_cli.backup import run_quick_backup + run_quick_backup(args) + else: + from hermes_cli.backup import run_backup + run_backup(args) + + +def cmd_import(args): + """Restore a Hermes backup from a zip file.""" + from hermes_cli.backup import run_import + run_import(args) + + +def cmd_version(args): + """Show version.""" + print(f"Hermes Agent v{__version__} ({__release_date__})") + print(f"Project: {PROJECT_ROOT}") + + # Show Python version + print(f"Python: {sys.version.split()[0]}") + + # Check for key dependencies + try: + import openai + print(f"OpenAI SDK: {openai.__version__}") + except ImportError: + print("OpenAI SDK: Not installed") + + # Show update status (synchronous — acceptable since user asked for version info) + try: + from hermes_cli.banner import check_for_updates + from hermes_cli.config import recommended_update_command + behind = check_for_updates() + if behind and behind > 0: + commits_word = "commit" if behind == 1 else "commits" + print( + f"Update available: {behind} {commits_word} behind — " + f"run '{recommended_update_command()}'" + ) + elif behind == 0: + print("Up to date") + except Exception: + pass + + +def cmd_uninstall(args): + """Uninstall Hermes Agent.""" + _require_tty("uninstall") + from hermes_cli.uninstall import run_uninstall + run_uninstall(args) + + +def _clear_bytecode_cache(root: Path) -> int: + """Remove all __pycache__ directories under *root*. + + Stale .pyc files can cause ImportError after code updates when Python + loads a cached bytecode file that references names that no longer exist + (or don't yet exist) in the updated source. Clearing them forces Python + to recompile from the .py source on next import. + + Returns the number of directories removed. + """ + removed = 0 + for dirpath, dirnames, _ in os.walk(root): + # Skip venv / node_modules / .git entirely + dirnames[:] = [ + d for d in dirnames + if d not in ("venv", ".venv", "node_modules", ".git", ".worktrees") + ] + if os.path.basename(dirpath) == "__pycache__": + try: + import shutil as _shutil + _shutil.rmtree(dirpath) + removed += 1 + except OSError: + pass + dirnames.clear() # nothing left to recurse into + return removed + + +def _gateway_prompt(prompt_text: str, default: str = "", timeout: float = 300.0) -> str: + """File-based IPC prompt for gateway mode. + + Writes a prompt marker file so the gateway can forward the question to the + user, then polls for a response file. Falls back to *default* on timeout. + + Used by ``hermes update --gateway`` so interactive prompts (stash restore, + config migration) are forwarded to the messenger instead of being silently + skipped. + """ + import json as _json + import uuid as _uuid + from hermes_constants import get_hermes_home + + home = get_hermes_home() + prompt_path = home / ".update_prompt.json" + response_path = home / ".update_response" + + # Clean any stale response file + response_path.unlink(missing_ok=True) + + payload = { + "prompt": prompt_text, + "default": default, + "id": str(_uuid.uuid4()), + } + tmp = prompt_path.with_suffix(".tmp") + tmp.write_text(_json.dumps(payload)) + tmp.replace(prompt_path) + + # Poll for response + import time as _time + deadline = _time.monotonic() + timeout + while _time.monotonic() < deadline: + if response_path.exists(): + try: + answer = response_path.read_text().strip() + response_path.unlink(missing_ok=True) + prompt_path.unlink(missing_ok=True) + return answer if answer else default + except (OSError, ValueError): + pass + _time.sleep(0.5) + + # Timeout — clean up and use default + prompt_path.unlink(missing_ok=True) + response_path.unlink(missing_ok=True) + print(f" (no response after {int(timeout)}s, using default: {default!r})") + return default + + +def _build_web_ui(web_dir: Path, *, fatal: bool = False) -> bool: + """Build the web UI frontend if npm is available. + + Args: + web_dir: Path to the ``web/`` source directory. + fatal: If True, print error guidance and return False on failure + instead of a soft warning (used by ``hermes web``). + + Returns True if the build succeeded or was skipped (no package.json). + """ + if not (web_dir / "package.json").exists(): + return True + import shutil + npm = shutil.which("npm") + if not npm: + if fatal: + print("Web UI frontend not built and npm is not available.") + print("Install Node.js, then run: cd web && npm install && npm run build") + return not fatal + print("→ Building web UI...") + r1 = subprocess.run([npm, "install", "--silent"], cwd=web_dir, capture_output=True) + if r1.returncode != 0: + print(f" {'✗' if fatal else '⚠'} Web UI npm install failed" + + ("" if fatal else " (hermes web will not be available)")) + if fatal: + print(" Run manually: cd web && npm install && npm run build") + return False + r2 = subprocess.run([npm, "run", "build"], cwd=web_dir, capture_output=True) + if r2.returncode != 0: + print(f" {'✗' if fatal else '⚠'} Web UI build failed" + + ("" if fatal else " (hermes web will not be available)")) + if fatal: + print(" Run manually: cd web && npm install && npm run build") + return False + print(" ✓ Web UI built") + return True + + +def _update_via_zip(args): + """Update Hermes Agent by downloading a ZIP archive. + + Used on Windows when git file I/O is broken (antivirus, NTFS filter + drivers causing 'Invalid argument' errors on file creation). + """ + import shutil + import tempfile + import zipfile + from urllib.request import urlretrieve + + branch = "main" + zip_url = f"https://github.com/NousResearch/hermes-agent/archive/refs/heads/{branch}.zip" + + print("→ Downloading latest version...") + try: + tmp_dir = tempfile.mkdtemp(prefix="hermes-update-") + zip_path = os.path.join(tmp_dir, f"hermes-agent-{branch}.zip") + urlretrieve(zip_url, zip_path) + + print("→ Extracting...") + with zipfile.ZipFile(zip_path, 'r') as zf: + # Validate paths to prevent zip-slip (path traversal) + tmp_dir_real = os.path.realpath(tmp_dir) + for member in zf.infolist(): + member_path = os.path.realpath(os.path.join(tmp_dir, member.filename)) + if not member_path.startswith(tmp_dir_real + os.sep) and member_path != tmp_dir_real: + raise ValueError(f"Zip-slip detected: {member.filename} escapes extraction directory") + zf.extractall(tmp_dir) + + # GitHub ZIPs extract to hermes-agent-/ + extracted = os.path.join(tmp_dir, f"hermes-agent-{branch}") + if not os.path.isdir(extracted): + # Try to find it + for d in os.listdir(tmp_dir): + candidate = os.path.join(tmp_dir, d) + if os.path.isdir(candidate) and d != "__MACOSX": + extracted = candidate + break + + # Copy updated files over existing installation, preserving venv/node_modules/.git + preserve = {'venv', 'node_modules', '.git', '.env'} + update_count = 0 + for item in os.listdir(extracted): + if item in preserve: + continue + src = os.path.join(extracted, item) + dst = os.path.join(str(PROJECT_ROOT), item) + if os.path.isdir(src): + if os.path.exists(dst): + shutil.rmtree(dst) + shutil.copytree(src, dst) + else: + shutil.copy2(src, dst) + update_count += 1 + + print(f"✓ Updated {update_count} items from ZIP") + + # Cleanup + shutil.rmtree(tmp_dir, ignore_errors=True) + + except Exception as e: + print(f"✗ ZIP update failed: {e}") + sys.exit(1) + + # Clear stale bytecode after ZIP extraction + removed = _clear_bytecode_cache(PROJECT_ROOT) + if removed: + print(f" ✓ Cleared {removed} stale __pycache__ director{'y' if removed == 1 else 'ies'}") + + # Reinstall Python dependencies. Prefer .[all], but if one optional extra + # breaks on this machine, keep base deps and reinstall the remaining extras + # individually so update does not silently strip working capabilities. + print("→ Updating Python dependencies...") + import subprocess + uv_bin = shutil.which("uv") + if uv_bin: + uv_env = {**os.environ, "VIRTUAL_ENV": str(PROJECT_ROOT / "venv")} + _install_python_dependencies_with_optional_fallback([uv_bin, "pip"], env=uv_env) + else: + # Use sys.executable to explicitly call the venv's pip module, + # avoiding PEP 668 'externally-managed-environment' errors on Debian/Ubuntu. + # Some environments lose pip inside the venv; bootstrap it back with + # ensurepip before trying the editable install. + pip_cmd = [sys.executable, "-m", "pip"] + try: + subprocess.run(pip_cmd + ["--version"], cwd=PROJECT_ROOT, check=True, capture_output=True) + except subprocess.CalledProcessError: + subprocess.run( + [sys.executable, "-m", "ensurepip", "--upgrade", "--default-pip"], + cwd=PROJECT_ROOT, + check=True, + ) + _install_python_dependencies_with_optional_fallback(pip_cmd) + + # Build web UI frontend (optional — requires npm) + _build_web_ui(PROJECT_ROOT / "web") + + # Sync skills + try: + from tools.skills_sync import sync_skills + print("→ Syncing bundled skills...") + result = sync_skills(quiet=True) + if result["copied"]: + print(f" + {len(result['copied'])} new: {', '.join(result['copied'])}") + if result.get("updated"): + print(f" ↑ {len(result['updated'])} updated: {', '.join(result['updated'])}") + if result.get("user_modified"): + print(f" ~ {len(result['user_modified'])} user-modified (kept)") + if result.get("cleaned"): + print(f" − {len(result['cleaned'])} removed from manifest") + if not result["copied"] and not result.get("updated"): + print(" ✓ Skills are up to date") + except Exception: + pass + + print() + print("✓ Update complete!") + + +def _stash_local_changes_if_needed(git_cmd: list[str], cwd: Path) -> Optional[str]: + status = subprocess.run( + git_cmd + ["status", "--porcelain"], + cwd=cwd, + capture_output=True, + text=True, + check=True, + ) + if not status.stdout.strip(): + return None + + # If the index has unmerged entries (e.g. from an interrupted merge/rebase), + # git stash will fail with "needs merge / could not write index". Clear the + # conflict state with `git reset` so the stash can proceed. Working-tree + # changes are preserved; only the index conflict markers are dropped. + unmerged = subprocess.run( + git_cmd + ["ls-files", "--unmerged"], + cwd=cwd, + capture_output=True, + text=True, + ) + if unmerged.stdout.strip(): + print("→ Clearing unmerged index entries from a previous conflict...") + subprocess.run(git_cmd + ["reset"], cwd=cwd, capture_output=True) + + from datetime import datetime, timezone + + stash_name = datetime.now(timezone.utc).strftime("hermes-update-autostash-%Y%m%d-%H%M%S") + print("→ Local changes detected — stashing before update...") + subprocess.run( + git_cmd + ["stash", "push", "--include-untracked", "-m", stash_name], + cwd=cwd, + check=True, + ) + stash_ref = subprocess.run( + git_cmd + ["rev-parse", "--verify", "refs/stash"], + cwd=cwd, + capture_output=True, + text=True, + check=True, + ).stdout.strip() + return stash_ref + + + +def _resolve_stash_selector(git_cmd: list[str], cwd: Path, stash_ref: str) -> Optional[str]: + stash_list = subprocess.run( + git_cmd + ["stash", "list", "--format=%gd %H"], + cwd=cwd, + capture_output=True, + text=True, + check=True, + ) + for line in stash_list.stdout.splitlines(): + selector, _, commit = line.partition(" ") + if commit.strip() == stash_ref: + return selector.strip() + return None + + + +def _print_stash_cleanup_guidance(stash_ref: str, stash_selector: Optional[str] = None) -> None: + print(" Check `git status` first so you don't accidentally reapply the same change twice.") + print(" Find the saved entry with: git stash list --format='%gd %H %s'") + if stash_selector: + print(f" Remove it with: git stash drop {stash_selector}") + else: + print(f" Look for commit {stash_ref}, then drop its selector with: git stash drop stash@{{N}}") + + + +def _restore_stashed_changes( + git_cmd: list[str], + cwd: Path, + stash_ref: str, + prompt_user: bool = False, + input_fn=None, +) -> bool: + if prompt_user: + print() + print("⚠ Local changes were stashed before updating.") + print(" Restoring them may reapply local customizations onto the updated codebase.") + print(" Review the result afterward if Hermes behaves unexpectedly.") + print("Restore local changes now? [Y/n]") + if input_fn is not None: + response = input_fn("Restore local changes now? [Y/n]", "y") + else: + response = input().strip().lower() + if response not in ("", "y", "yes"): + print("Skipped restoring local changes.") + print("Your changes are still preserved in git stash.") + print(f"Restore manually with: git stash apply {stash_ref}") + return False + + print("→ Restoring local changes...") + restore = subprocess.run( + git_cmd + ["stash", "apply", stash_ref], + cwd=cwd, + capture_output=True, + text=True, + ) + + # Check for unmerged (conflicted) files — can happen even when returncode is 0 + unmerged = subprocess.run( + git_cmd + ["diff", "--name-only", "--diff-filter=U"], + cwd=cwd, + capture_output=True, + text=True, + ) + has_conflicts = bool(unmerged.stdout.strip()) + + if restore.returncode != 0 or has_conflicts: + print("✗ Update pulled new code, but restoring local changes hit conflicts.") + if restore.stdout.strip(): + print(restore.stdout.strip()) + if restore.stderr.strip(): + print(restore.stderr.strip()) + + # Show which files conflicted + conflicted_files = unmerged.stdout.strip() + if conflicted_files: + print("\nConflicted files:") + for f in conflicted_files.splitlines(): + print(f" • {f}") + + print("\nYour stashed changes are preserved — nothing is lost.") + print(f" Stash ref: {stash_ref}") + + # Always reset to clean state — leaving conflict markers in source + # files makes hermes completely unrunnable (SyntaxError on import). + # The user's changes are safe in the stash for manual recovery. + subprocess.run( + git_cmd + ["reset", "--hard", "HEAD"], + cwd=cwd, + capture_output=True, + ) + print("Working tree reset to clean state.") + print(f"Restore your changes later with: git stash apply {stash_ref}") + # Don't sys.exit — the code update itself succeeded, only the stash + # restore had conflicts. Let cmd_update continue with pip install, + # skill sync, and gateway restart. + return False + + stash_selector = _resolve_stash_selector(git_cmd, cwd, stash_ref) + if stash_selector is None: + print("⚠ Local changes were restored, but Hermes couldn't find the stash entry to drop.") + print(" The stash was left in place. You can remove it manually after checking the result.") + _print_stash_cleanup_guidance(stash_ref) + else: + drop = subprocess.run( + git_cmd + ["stash", "drop", stash_selector], + cwd=cwd, + capture_output=True, + text=True, + ) + if drop.returncode != 0: + print("⚠ Local changes were restored, but Hermes couldn't drop the saved stash entry.") + if drop.stdout.strip(): + print(drop.stdout.strip()) + if drop.stderr.strip(): + print(drop.stderr.strip()) + print(" The stash was left in place. You can remove it manually after checking the result.") + _print_stash_cleanup_guidance(stash_ref, stash_selector) + + print("⚠ Local changes were restored on top of the updated codebase.") + print(" Review `git diff` / `git status` if Hermes behaves unexpectedly.") + return True + +# ========================================================================= +# Fork detection and upstream management for `hermes update` +# ========================================================================= + +OFFICIAL_REPO_URLS = { + "https://github.com/NousResearch/hermes-agent.git", + "git@github.com:NousResearch/hermes-agent.git", + "https://github.com/NousResearch/hermes-agent", + "git@github.com:NousResearch/hermes-agent", +} +OFFICIAL_REPO_URL = "https://github.com/NousResearch/hermes-agent.git" +SKIP_UPSTREAM_PROMPT_FILE = ".skip_upstream_prompt" + + +def _get_origin_url(git_cmd: list[str], cwd: Path) -> Optional[str]: + """Get the URL of the origin remote, or None if not set.""" + try: + result = subprocess.run( + git_cmd + ["remote", "get-url", "origin"], + cwd=cwd, + capture_output=True, + text=True, + ) + if result.returncode == 0: + return result.stdout.strip() + except Exception: + pass + return None + + +def _is_fork(origin_url: Optional[str]) -> bool: + """Check if the origin remote points to a fork (not the official repo).""" + if not origin_url: + return False + # Normalize URL for comparison (strip trailing .git if present) + normalized = origin_url.rstrip("/") + if normalized.endswith(".git"): + normalized = normalized[:-4] + for official in OFFICIAL_REPO_URLS: + official_normalized = official.rstrip("/") + if official_normalized.endswith(".git"): + official_normalized = official_normalized[:-4] + if normalized == official_normalized: + return False + return True + + +def _has_upstream_remote(git_cmd: list[str], cwd: Path) -> bool: + """Check if an 'upstream' remote already exists.""" + try: + result = subprocess.run( + git_cmd + ["remote", "get-url", "upstream"], + cwd=cwd, + capture_output=True, + text=True, + ) + return result.returncode == 0 + except Exception: + return False + + +def _add_upstream_remote(git_cmd: list[str], cwd: Path) -> bool: + """Add the official repo as the 'upstream' remote. Returns True on success.""" + try: + result = subprocess.run( + git_cmd + ["remote", "add", "upstream", OFFICIAL_REPO_URL], + cwd=cwd, + capture_output=True, + text=True, + ) + return result.returncode == 0 + except Exception: + return False + + +def _count_commits_between(git_cmd: list[str], cwd: Path, base: str, head: str) -> int: + """Count commits on `head` that are not on `base`. Returns -1 on error.""" + try: + result = subprocess.run( + git_cmd + ["rev-list", "--count", f"{base}..{head}"], + cwd=cwd, + capture_output=True, + text=True, + ) + if result.returncode == 0: + return int(result.stdout.strip()) + except Exception: + pass + return -1 + + +def _should_skip_upstream_prompt() -> bool: + """Check if user previously declined to add upstream.""" + from hermes_constants import get_hermes_home + return (get_hermes_home() / SKIP_UPSTREAM_PROMPT_FILE).exists() + + +def _mark_skip_upstream_prompt(): + """Create marker file to skip future upstream prompts.""" + try: + from hermes_constants import get_hermes_home + (get_hermes_home() / SKIP_UPSTREAM_PROMPT_FILE).touch() + except Exception: + pass + + +def _sync_fork_with_upstream(git_cmd: list[str], cwd: Path) -> bool: + """Attempt to push updated main to origin (sync fork). + + Returns True if push succeeded, False otherwise. + """ + try: + result = subprocess.run( + git_cmd + ["push", "origin", "main", "--force-with-lease"], + cwd=cwd, + capture_output=True, + text=True, + ) + return result.returncode == 0 + except Exception: + return False + + +def _sync_with_upstream_if_needed(git_cmd: list[str], cwd: Path) -> None: + """Check if fork is behind upstream and sync if safe. + + This implements the fork upstream sync logic: + - If upstream remote doesn't exist, ask user if they want to add it + - Compare origin/main with upstream/main + - If origin/main is strictly behind upstream/main, pull from upstream + - Try to sync fork back to origin if possible + """ + has_upstream = _has_upstream_remote(git_cmd, cwd) + + if not has_upstream: + # Check if user previously declined + if _should_skip_upstream_prompt(): + return + + # Ask user if they want to add upstream + print() + print("ℹ Your fork is not tracking the official Hermes repository.") + print(" This means you may miss updates from NousResearch/hermes-agent.") + print() + try: + response = input("Add official repo as 'upstream' remote? [Y/n]: ").strip().lower() + except (EOFError, KeyboardInterrupt): + print() + response = "n" + + if response in ("", "y", "yes"): + print("→ Adding upstream remote...") + if _add_upstream_remote(git_cmd, cwd): + print(" ✓ Added upstream: https://github.com/NousResearch/hermes-agent.git") + has_upstream = True + else: + print(" ✗ Failed to add upstream remote. Skipping upstream sync.") + return + else: + print(" Skipped. Run 'git remote add upstream https://github.com/NousResearch/hermes-agent.git' to add later.") + _mark_skip_upstream_prompt() + return + + # Fetch upstream + print() + print("→ Fetching upstream...") + try: + subprocess.run( + git_cmd + ["fetch", "upstream", "--quiet"], + cwd=cwd, + capture_output=True, + check=True, + ) + except subprocess.CalledProcessError: + print(" ✗ Failed to fetch upstream. Skipping upstream sync.") + return + + # Compare origin/main with upstream/main + origin_ahead = _count_commits_between(git_cmd, cwd, "upstream/main", "origin/main") + upstream_ahead = _count_commits_between(git_cmd, cwd, "origin/main", "upstream/main") + + if origin_ahead < 0 or upstream_ahead < 0: + print(" ✗ Could not compare branches. Skipping upstream sync.") + return + + # If origin/main has commits not on upstream, don't trample + if origin_ahead > 0: + print() + print(f"ℹ Your fork has {origin_ahead} commit(s) not on upstream.") + print(" Skipping upstream sync to preserve your changes.") + print(" If you want to merge upstream changes, run:") + print(" git pull upstream main") + return + + # If upstream is not ahead, fork is up to date + if upstream_ahead == 0: + print(" ✓ Fork is up to date with upstream") + return + + # origin/main is strictly behind upstream/main (can fast-forward) + print() + print(f"→ Fork is {upstream_ahead} commit(s) behind upstream") + print("→ Pulling from upstream...") + + try: + subprocess.run( + git_cmd + ["pull", "--ff-only", "upstream", "main"], + cwd=cwd, + check=True, + ) + except subprocess.CalledProcessError: + print(" ✗ Failed to pull from upstream. You may need to resolve conflicts manually.") + return + + print(" ✓ Updated from upstream") + + # Try to sync fork back to origin + print("→ Syncing fork...") + if _sync_fork_with_upstream(git_cmd, cwd): + print(" ✓ Fork synced with upstream") + else: + print(" ℹ Got updates from upstream but couldn't push to fork (no write access?)") + print(" Your local repo is updated, but your fork on GitHub may be behind.") + + +def _invalidate_update_cache(): + """Delete the update-check cache for ALL profiles so no banner + reports a stale "commits behind" count after a successful update. + + The git repo is shared across profiles — when one profile runs + ``hermes update``, every profile is now current. + """ + homes = [] + # Default profile home (Docker-aware — uses /opt/data in Docker) + from hermes_constants import get_default_hermes_root + default_home = get_default_hermes_root() + homes.append(default_home) + # Named profiles under /profiles/ + profiles_root = default_home / "profiles" + if profiles_root.is_dir(): + for entry in profiles_root.iterdir(): + if entry.is_dir(): + homes.append(entry) + for home in homes: + try: + cache_file = home / ".update_check" + if cache_file.exists(): + cache_file.unlink() + except Exception: + pass + + +def _load_installable_optional_extras() -> list[str]: + """Return the optional extras referenced by the ``all`` group. + + Only extras that ``[all]`` actually pulls in are retried individually. + Extras outside ``[all]`` (e.g. ``rl``, ``yc-bench``) are intentionally + excluded — they have heavy or platform-specific deps that most users + never installed. + """ + try: + import tomllib + with (PROJECT_ROOT / "pyproject.toml").open("rb") as handle: + project = tomllib.load(handle).get("project", {}) + except Exception: + return [] + + optional_deps = project.get("optional-dependencies", {}) + if not isinstance(optional_deps, dict): + return [] + + # Parse the [all] group to find which extras it references. + # Entries look like "hermes-agent[matrix]" or "package-name[extra]". + all_refs = optional_deps.get("all", []) + referenced: list[str] = [] + for ref in all_refs: + if "[" in ref and "]" in ref: + name = ref.split("[", 1)[1].split("]", 1)[0] + if name in optional_deps: + referenced.append(name) + + return referenced + + + +def _install_python_dependencies_with_optional_fallback( + install_cmd_prefix: list[str], + *, + env: dict[str, str] | None = None, +) -> None: + """Install base deps plus as many optional extras as the environment supports.""" + try: + subprocess.run( + install_cmd_prefix + ["install", "-e", ".[all]", "--quiet"], + cwd=PROJECT_ROOT, + check=True, + env=env, + ) + return + except subprocess.CalledProcessError: + print(" ⚠ Optional extras failed, reinstalling base dependencies and retrying extras individually...") + + subprocess.run( + install_cmd_prefix + ["install", "-e", ".", "--quiet"], + cwd=PROJECT_ROOT, + check=True, + env=env, + ) + + failed_extras: list[str] = [] + installed_extras: list[str] = [] + for extra in _load_installable_optional_extras(): + try: + subprocess.run( + install_cmd_prefix + ["install", "-e", f".[{extra}]", "--quiet"], + cwd=PROJECT_ROOT, + check=True, + env=env, + ) + installed_extras.append(extra) + except subprocess.CalledProcessError: + failed_extras.append(extra) + + if installed_extras: + print(f" ✓ Reinstalled optional extras individually: {', '.join(installed_extras)}") + if failed_extras: + print(f" ⚠ Skipped optional extras that still failed: {', '.join(failed_extras)}") + + +def cmd_update(args): + """Update Hermes Agent to the latest version.""" + import shutil + from hermes_cli.config import is_managed, managed_error + + if is_managed(): + managed_error("update Hermes Agent") + return + + gateway_mode = getattr(args, "gateway", False) + # In gateway mode, use file-based IPC for prompts instead of stdin + gw_input_fn = (lambda prompt, default="": _gateway_prompt(prompt, default)) if gateway_mode else None + + print("⚕ Updating Hermes Agent...") + print() + + # Try git-based update first, fall back to ZIP download on Windows + # when git file I/O is broken (antivirus, NTFS filter drivers, etc.) + use_zip_update = False + git_dir = PROJECT_ROOT / '.git' + + if not git_dir.exists(): + if sys.platform == "win32": + use_zip_update = True + else: + print("✗ Not a git repository. Please reinstall:") + print(" curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash") + sys.exit(1) + + # On Windows, git can fail with "unable to write loose object file: Invalid argument" + # due to filesystem atomicity issues. Set the recommended workaround. + if sys.platform == "win32" and git_dir.exists(): + subprocess.run( + ["git", "-c", "windows.appendAtomically=false", "config", "windows.appendAtomically", "false"], + cwd=PROJECT_ROOT, check=False, capture_output=True + ) + + # Build git command once — reused for fork detection and the update itself. + git_cmd = ["git"] + if sys.platform == "win32": + git_cmd = ["git", "-c", "windows.appendAtomically=false"] + + # Detect if we're updating from a fork (before any branch logic) + origin_url = _get_origin_url(git_cmd, PROJECT_ROOT) + is_fork = _is_fork(origin_url) + + if is_fork: + print("⚠ Updating from fork:") + print(f" {origin_url}") + print() + + if use_zip_update: + # ZIP-based update for Windows when git is broken + _update_via_zip(args) + return + + # Fetch and pull + try: + + print("→ Fetching updates...") + fetch_result = subprocess.run( + git_cmd + ["fetch", "origin"], + cwd=PROJECT_ROOT, + capture_output=True, + text=True, + ) + if fetch_result.returncode != 0: + stderr = fetch_result.stderr.strip() + if "Could not resolve host" in stderr or "unable to access" in stderr: + print("✗ Network error — cannot reach the remote repository.") + print(f" {stderr.splitlines()[0]}" if stderr else "") + elif "Authentication failed" in stderr or "could not read Username" in stderr: + print("✗ Authentication failed — check your git credentials or SSH key.") + else: + print(f"✗ Failed to fetch updates from origin.") + if stderr: + print(f" {stderr.splitlines()[0]}") + sys.exit(1) + + # Get current branch (returns literal "HEAD" when detached) + result = subprocess.run( + git_cmd + ["rev-parse", "--abbrev-ref", "HEAD"], + cwd=PROJECT_ROOT, + capture_output=True, + text=True, + check=True, + ) + current_branch = result.stdout.strip() + + # Always update against main + branch = "main" + + # If user is on a non-main branch or detached HEAD, switch to main + if current_branch != "main": + label = "detached HEAD" if current_branch == "HEAD" else f"branch '{current_branch}'" + print(f" ⚠ Currently on {label} — switching to main for update...") + # Stash before checkout so uncommitted work isn't lost + auto_stash_ref = _stash_local_changes_if_needed(git_cmd, PROJECT_ROOT) + subprocess.run( + git_cmd + ["checkout", "main"], + cwd=PROJECT_ROOT, + capture_output=True, + text=True, + check=True, + ) + else: + auto_stash_ref = _stash_local_changes_if_needed(git_cmd, PROJECT_ROOT) + + prompt_for_restore = auto_stash_ref is not None and ( + gateway_mode or (sys.stdin.isatty() and sys.stdout.isatty()) + ) + + # Check if there are updates + result = subprocess.run( + git_cmd + ["rev-list", f"HEAD..origin/{branch}", "--count"], + cwd=PROJECT_ROOT, + capture_output=True, + text=True, + check=True, + ) + commit_count = int(result.stdout.strip()) + + if commit_count == 0: + _invalidate_update_cache() + # Restore stash and switch back to original branch if we moved + if auto_stash_ref is not None: + _restore_stashed_changes( + git_cmd, PROJECT_ROOT, auto_stash_ref, + prompt_user=prompt_for_restore, + input_fn=gw_input_fn, + ) + if current_branch not in ("main", "HEAD"): + subprocess.run( + git_cmd + ["checkout", current_branch], + cwd=PROJECT_ROOT, capture_output=True, text=True, check=False, + ) + print("✓ Already up to date!") + return + + print(f"→ Found {commit_count} new commit(s)") + + print("→ Pulling updates...") + update_succeeded = False + try: + pull_result = subprocess.run( + git_cmd + ["pull", "--ff-only", "origin", branch], + cwd=PROJECT_ROOT, + capture_output=True, + text=True, + ) + if pull_result.returncode != 0: + # ff-only failed — local and remote have diverged (e.g. upstream + # force-pushed or rebase). Since local changes are already + # stashed, reset to match the remote exactly. + print(" ⚠ Fast-forward not possible (history diverged), resetting to match remote...") + reset_result = subprocess.run( + git_cmd + ["reset", "--hard", f"origin/{branch}"], + cwd=PROJECT_ROOT, + capture_output=True, + text=True, + ) + if reset_result.returncode != 0: + print(f"✗ Failed to reset to origin/{branch}.") + if reset_result.stderr.strip(): + print(f" {reset_result.stderr.strip()}") + print(" Try manually: git fetch origin && git reset --hard origin/main") + sys.exit(1) + update_succeeded = True + finally: + if auto_stash_ref is not None: + # Don't attempt stash restore if the code update itself failed — + # working tree is in an unknown state. + if not update_succeeded: + print(f" ℹ️ Local changes preserved in stash (ref: {auto_stash_ref})") + print(f" Restore manually with: git stash apply") + else: + _restore_stashed_changes( + git_cmd, + PROJECT_ROOT, + auto_stash_ref, + prompt_user=prompt_for_restore, + input_fn=gw_input_fn, + ) + + _invalidate_update_cache() + + # Clear stale .pyc bytecode cache — prevents ImportError on gateway + # restart when updated source references names that didn't exist in + # the old bytecode (e.g. get_hermes_home added to hermes_constants). + removed = _clear_bytecode_cache(PROJECT_ROOT) + if removed: + print(f" ✓ Cleared {removed} stale __pycache__ director{'y' if removed == 1 else 'ies'}") + + # Fork upstream sync logic (only for main branch on forks) + if is_fork and branch == "main": + _sync_with_upstream_if_needed(git_cmd, PROJECT_ROOT) + + # Reinstall Python dependencies. Prefer .[all], but if one optional extra + # breaks on this machine, keep base deps and reinstall the remaining extras + # individually so update does not silently strip working capabilities. + print("→ Updating Python dependencies...") + uv_bin = shutil.which("uv") + if uv_bin: + uv_env = {**os.environ, "VIRTUAL_ENV": str(PROJECT_ROOT / "venv")} + _install_python_dependencies_with_optional_fallback([uv_bin, "pip"], env=uv_env) + else: + # Use sys.executable to explicitly call the venv's pip module, + # avoiding PEP 668 'externally-managed-environment' errors on Debian/Ubuntu. + # Some environments lose pip inside the venv; bootstrap it back with + # ensurepip before trying the editable install. + pip_cmd = [sys.executable, "-m", "pip"] + try: + subprocess.run(pip_cmd + ["--version"], cwd=PROJECT_ROOT, check=True, capture_output=True) + except subprocess.CalledProcessError: + subprocess.run( + [sys.executable, "-m", "ensurepip", "--upgrade", "--default-pip"], + cwd=PROJECT_ROOT, + check=True, + ) + _install_python_dependencies_with_optional_fallback(pip_cmd) + + # Check for Node.js deps + if (PROJECT_ROOT / "package.json").exists(): + import shutil + if shutil.which("npm"): + print("→ Updating Node.js dependencies...") + subprocess.run(["npm", "install", "--silent"], cwd=PROJECT_ROOT, check=False) + + # Build web UI frontend (optional — requires npm) + _build_web_ui(PROJECT_ROOT / "web") + + print() + print("✓ Code updated!") + + # After git pull, source files on disk are newer than cached Python + # modules in this process. Reload hermes_constants so that any lazy + # import executed below (skills sync, gateway restart) sees new + # attributes like display_hermes_home() added since the last release. + try: + import importlib + import hermes_constants as _hc + importlib.reload(_hc) + except Exception: + pass # non-fatal — worst case a lazy import fails gracefully + + # Sync bundled skills (copies new, updates changed, respects user deletions) + try: + from tools.skills_sync import sync_skills + print() + print("→ Syncing bundled skills...") + result = sync_skills(quiet=True) + if result["copied"]: + print(f" + {len(result['copied'])} new: {', '.join(result['copied'])}") + if result.get("updated"): + print(f" ↑ {len(result['updated'])} updated: {', '.join(result['updated'])}") + if result.get("user_modified"): + print(f" ~ {len(result['user_modified'])} user-modified (kept)") + if result.get("cleaned"): + print(f" − {len(result['cleaned'])} removed from manifest") + if not result["copied"] and not result.get("updated"): + print(" ✓ Skills are up to date") + except Exception as e: + logger.debug("Skills sync during update failed: %s", e) + + # Sync bundled skills to all other profiles + try: + from hermes_cli.profiles import list_profiles, get_active_profile_name, seed_profile_skills + active = get_active_profile_name() + other_profiles = [p for p in list_profiles() if p.name != active] + if other_profiles: + print() + print("→ Syncing bundled skills to other profiles...") + for p in other_profiles: + try: + r = seed_profile_skills(p.path, quiet=True) + if r: + copied = len(r.get("copied", [])) + updated = len(r.get("updated", [])) + modified = len(r.get("user_modified", [])) + parts = [] + if copied: parts.append(f"+{copied} new") + if updated: parts.append(f"↑{updated} updated") + if modified: parts.append(f"~{modified} user-modified") + status = ", ".join(parts) if parts else "up to date" + else: + status = "sync failed" + print(f" {p.name}: {status}") + except Exception as pe: + print(f" {p.name}: error ({pe})") + except Exception: + pass # profiles module not available or no profiles + + # Sync Honcho host blocks to all profiles + try: + from plugins.memory.honcho.cli import sync_honcho_profiles_quiet + synced = sync_honcho_profiles_quiet() + if synced: + print(f"\n-> Honcho: synced {synced} profile(s)") + except Exception: + pass # honcho plugin not installed or not configured + + # Check for config migrations + print() + print("→ Checking configuration for new options...") + + from hermes_cli.config import ( + get_missing_env_vars, get_missing_config_fields, + check_config_version, migrate_config + ) + + missing_env = get_missing_env_vars(required_only=True) + missing_config = get_missing_config_fields() + current_ver, latest_ver = check_config_version() + + needs_migration = missing_env or missing_config or current_ver < latest_ver + + if needs_migration: + print() + if missing_env: + print(f" ⚠️ {len(missing_env)} new required setting(s) need configuration") + if missing_config: + print(f" ℹ️ {len(missing_config)} new config option(s) available") + + print() + if gateway_mode: + response = _gateway_prompt( + "Would you like to configure new options now? [Y/n]", "n" + ).strip().lower() + elif not (sys.stdin.isatty() and sys.stdout.isatty()): + print(" ℹ Non-interactive session — skipping config migration prompt.") + print(" Run 'hermes config migrate' later to apply any new config/env options.") + response = "n" + else: + try: + response = input("Would you like to configure them now? [Y/n]: ").strip().lower() + except EOFError: + response = "n" + + if response in ('', 'y', 'yes'): + print() + # In gateway mode, run auto-migrations only (no input() prompts + # for API keys which would hang the detached process). + results = migrate_config(interactive=not gateway_mode, quiet=False) + + if results["env_added"] or results["config_added"]: + print() + print("✓ Configuration updated!") + if gateway_mode and missing_env: + print(" ℹ API keys require manual entry: hermes config migrate") + else: + print() + print("Skipped. Run 'hermes config migrate' later to configure.") + else: + print(" ✓ Configuration is up to date") + + print() + print("✓ Update complete!") + + # Write exit code *before* the gateway restart attempt. + # When running as ``hermes update --gateway`` (spawned by the gateway's + # /update command), this process lives inside the gateway's systemd + # cgroup. ``systemctl restart hermes-gateway`` kills everything in the + # cgroup (KillMode=mixed → SIGKILL to remaining processes), including + # us and the wrapping bash shell. The shell never reaches its + # ``printf $status > .update_exit_code`` epilogue, so the exit-code + # marker file is never created. The new gateway's update watcher then + # polls for 30 minutes and sends a spurious timeout message. + # + # Writing the marker here — after git pull + pip install succeed but + # before we attempt the restart — ensures the new gateway sees it + # regardless of how we die. + if gateway_mode: + _exit_code_path = get_hermes_home() / ".update_exit_code" + try: + _exit_code_path.write_text("0") + except OSError: + pass + + # Auto-restart ALL gateways after update. + # The code update (git pull) is shared across all profiles, so every + # running gateway needs restarting to pick up the new code. + try: + from hermes_cli.gateway import ( + is_macos, supports_systemd_services, _ensure_user_systemd_env, + find_gateway_pids, + _get_service_pids, + ) + import signal as _signal + + restarted_services = [] + killed_pids = set() + + # --- Systemd services (Linux) --- + # Discover all hermes-gateway* units (default + profiles) + if supports_systemd_services(): + try: + _ensure_user_systemd_env() + except Exception: + pass + + for scope, scope_cmd in [("user", ["systemctl", "--user"]), ("system", ["systemctl"])]: + try: + result = subprocess.run( + scope_cmd + ["list-units", "hermes-gateway*", "--plain", "--no-legend", "--no-pager"], + capture_output=True, text=True, timeout=10, + ) + for line in result.stdout.strip().splitlines(): + parts = line.split() + if not parts: + continue + unit = parts[0] # e.g. hermes-gateway.service or hermes-gateway-coder.service + if not unit.endswith(".service"): + continue + svc_name = unit.removesuffix(".service") + # Check if active + check = subprocess.run( + scope_cmd + ["is-active", svc_name], + capture_output=True, text=True, timeout=5, + ) + if check.stdout.strip() == "active": + restart = subprocess.run( + scope_cmd + ["restart", svc_name], + capture_output=True, text=True, timeout=15, + ) + if restart.returncode == 0: + restarted_services.append(svc_name) + else: + print(f" ⚠ Failed to restart {svc_name}: {restart.stderr.strip()}") + except (FileNotFoundError, subprocess.TimeoutExpired): + pass + + # --- Launchd services (macOS) --- + if is_macos(): + try: + from hermes_cli.gateway import launchd_restart, get_launchd_label, get_launchd_plist_path + plist_path = get_launchd_plist_path() + if plist_path.exists(): + check = subprocess.run( + ["launchctl", "list", get_launchd_label()], + capture_output=True, text=True, timeout=5, + ) + if check.returncode == 0: + try: + launchd_restart() + restarted_services.append(get_launchd_label()) + except subprocess.CalledProcessError as e: + stderr = (getattr(e, "stderr", "") or "").strip() + print(f" ⚠ Gateway restart failed: {stderr}") + except (FileNotFoundError, subprocess.TimeoutExpired, ImportError): + pass + + # --- Manual (non-service) gateways --- + # Kill any remaining gateway processes not managed by a service. + # Exclude PIDs that belong to just-restarted services so we don't + # immediately kill the process that systemd/launchd just spawned. + service_pids = _get_service_pids() + manual_pids = find_gateway_pids(exclude_pids=service_pids, all_profiles=True) + for pid in manual_pids: + try: + os.kill(pid, _signal.SIGTERM) + killed_pids.add(pid) + except (ProcessLookupError, PermissionError): + pass + + if restarted_services or killed_pids: + print() + for svc in restarted_services: + print(f" ✓ Restarted {svc}") + if killed_pids: + print(f" → Stopped {len(killed_pids)} manual gateway process(es)") + print(" Restart manually: hermes gateway run") + # Also restart for each profile if needed + if len(killed_pids) > 1: + print(" (or: hermes -p gateway run for each profile)") + + if not restarted_services and not killed_pids: + # No gateways were running — nothing to do + pass + + except Exception as e: + logger.debug("Gateway restart during update failed: %s", e) + + print() + print("Tip: You can now select a provider and model:") + print(" hermes model # Select provider and model") + + except subprocess.CalledProcessError as e: + if sys.platform == "win32": + print(f"⚠ Git update failed: {e}") + print("→ Falling back to ZIP download...") + print() + _update_via_zip(args) + else: + print(f"✗ Update failed: {e}") + sys.exit(1) + + +def _coalesce_session_name_args(argv: list) -> list: + """Join unquoted multi-word session names after -c/--continue and -r/--resume. + + When a user types ``hermes -c Pokemon Agent Dev`` without quoting the + session name, argparse sees three separate tokens. This function merges + them into a single argument so argparse receives + ``['-c', 'Pokemon Agent Dev']`` instead. + + Tokens are collected after the flag until we hit another flag (``-*``) + or a known top-level subcommand. + """ + _SUBCOMMANDS = { + "chat", "model", "gateway", "setup", "whatsapp", "login", "logout", "auth", + "status", "cron", "doctor", "config", "pairing", "skills", "tools", + "mcp", "sessions", "insights", "version", "update", "uninstall", + "profile", "dashboard", + } + _SESSION_FLAGS = {"-c", "--continue", "-r", "--resume"} + + result = [] + i = 0 + while i < len(argv): + token = argv[i] + if token in _SESSION_FLAGS: + result.append(token) + i += 1 + # Collect subsequent non-flag, non-subcommand tokens as one name + parts: list = [] + while i < len(argv) and not argv[i].startswith("-") and argv[i] not in _SUBCOMMANDS: + parts.append(argv[i]) + i += 1 + if parts: + result.append(" ".join(parts)) + else: + result.append(token) + i += 1 + return result + + +def cmd_profile(args): + """Profile management — create, delete, list, switch, alias.""" + from hermes_cli.profiles import ( + list_profiles, create_profile, delete_profile, seed_profile_skills, + set_active_profile, get_active_profile_name, + check_alias_collision, create_wrapper_script, remove_wrapper_script, + _is_wrapper_dir_in_path, _get_wrapper_dir, + ) + from hermes_constants import display_hermes_home + + action = getattr(args, "profile_action", None) + + if action is None: + # Bare `hermes profile` — show current profile status + profile_name = get_active_profile_name() + dhh = display_hermes_home() + print(f"\nActive profile: {profile_name}") + print(f"Path: {dhh}") + + profiles = list_profiles() + for p in profiles: + if p.name == profile_name or (profile_name == "default" and p.is_default): + if p.model: + print(f"Model: {p.model}" + (f" ({p.provider})" if p.provider else "")) + print(f"Gateway: {'running' if p.gateway_running else 'stopped'}") + print(f"Skills: {p.skill_count} installed") + if p.alias_path: + print(f"Alias: {p.name} → hermes -p {p.name}") + break + print() + return + + if action == "list": + profiles = list_profiles() + active = get_active_profile_name() + + if not profiles: + print("No profiles found.") + return + + # Header + print(f"\n {'Profile':<16} {'Model':<28} {'Gateway':<12} {'Alias'}") + print(f" {'─' * 15} {'─' * 27} {'─' * 11} {'─' * 12}") + + for p in profiles: + marker = " ◆" if (p.name == active or (active == "default" and p.is_default)) else " " + name = p.name + model = (p.model or "—")[:26] + gw = "running" if p.gateway_running else "stopped" + alias = p.name if p.alias_path else "—" + if p.is_default: + alias = "—" + print(f"{marker}{name:<15} {model:<28} {gw:<12} {alias}") + print() + + elif action == "use": + name = args.profile_name + try: + set_active_profile(name) + if name == "default": + print(f"Switched to: default (~/.hermes)") + else: + print(f"Switched to: {name}") + except (ValueError, FileNotFoundError) as e: + print(f"Error: {e}") + sys.exit(1) + + elif action == "create": + name = args.profile_name + clone = getattr(args, "clone", False) + clone_all = getattr(args, "clone_all", False) + no_alias = getattr(args, "no_alias", False) + + try: + clone_from = getattr(args, "clone_from", None) + + profile_dir = create_profile( + name=name, + clone_from=clone_from, + clone_all=clone_all, + clone_config=clone, + no_alias=no_alias, + ) + print(f"\nProfile '{name}' created at {profile_dir}") + + if clone or clone_all: + source_label = getattr(args, "clone_from", None) or get_active_profile_name() + if clone_all: + print(f"Full copy from {source_label}.") + else: + print(f"Cloned config, .env, SOUL.md from {source_label}.") + + # Auto-clone Honcho config for the new profile (only with --clone/--clone-all) + if clone or clone_all: + try: + from plugins.memory.honcho.cli import clone_honcho_for_profile + if clone_honcho_for_profile(name): + print(f"Honcho config cloned (peer: {name})") + except Exception: + pass # Honcho plugin not installed or not configured + + # Seed bundled skills (skip if --clone-all already copied them) + if not clone_all: + result = seed_profile_skills(profile_dir) + if result: + copied = len(result.get("copied", [])) + print(f"{copied} bundled skills synced.") + else: + print("⚠ Skills could not be seeded. Run `{} update` to retry.".format(name)) + + # Create wrapper alias + if not no_alias: + collision = check_alias_collision(name) + if collision: + print(f"\n⚠ Cannot create alias '{name}' — {collision}") + print(f" Choose a custom alias: hermes profile alias {name} --name ") + print(f" Or access via flag: hermes -p {name} chat") + else: + wrapper_path = create_wrapper_script(name) + if wrapper_path: + print(f"Wrapper created: {wrapper_path}") + if not _is_wrapper_dir_in_path(): + print(f"\n⚠ {_get_wrapper_dir()} is not in your PATH.") + print(f' Add to your shell config (~/.bashrc or ~/.zshrc):') + print(f' export PATH="$HOME/.local/bin:$PATH"') + + # Profile dir for display + try: + profile_dir_display = "~/" + str(profile_dir.relative_to(Path.home())) + except ValueError: + profile_dir_display = str(profile_dir) + + # Next steps + print(f"\nNext steps:") + print(f" {name} setup Configure API keys and model") + print(f" {name} chat Start chatting") + print(f" {name} gateway start Start the messaging gateway") + if clone or clone_all: + print(f"\n Edit {profile_dir_display}/.env for different API keys") + print(f" Edit {profile_dir_display}/SOUL.md for different personality") + else: + print(f"\n ⚠ This profile has no API keys yet. Run '{name} setup' first,") + print(f" or it will inherit keys from your shell environment.") + print(f" Edit {profile_dir_display}/SOUL.md to customize personality") + print() + + except (ValueError, FileExistsError, FileNotFoundError) as e: + print(f"Error: {e}") + sys.exit(1) + + elif action == "delete": + name = args.profile_name + yes = getattr(args, "yes", False) + try: + delete_profile(name, yes=yes) + except (ValueError, FileNotFoundError) as e: + print(f"Error: {e}") + sys.exit(1) + + elif action == "show": + name = args.profile_name + from hermes_cli.profiles import get_profile_dir, profile_exists, _read_config_model, _check_gateway_running, _count_skills + if not profile_exists(name): + print(f"Error: Profile '{name}' does not exist.") + sys.exit(1) + profile_dir = get_profile_dir(name) + model, provider = _read_config_model(profile_dir) + gw = _check_gateway_running(profile_dir) + skills = _count_skills(profile_dir) + wrapper = _get_wrapper_dir() / name + + print(f"\nProfile: {name}") + print(f"Path: {profile_dir}") + if model: + print(f"Model: {model}" + (f" ({provider})" if provider else "")) + print(f"Gateway: {'running' if gw else 'stopped'}") + print(f"Skills: {skills}") + print(f".env: {'exists' if (profile_dir / '.env').exists() else 'not configured'}") + print(f"SOUL.md: {'exists' if (profile_dir / 'SOUL.md').exists() else 'not configured'}") + if wrapper.exists(): + print(f"Alias: {wrapper}") + print() + + elif action == "alias": + name = args.profile_name + remove = getattr(args, "remove", False) + custom_name = getattr(args, "alias_name", None) + + from hermes_cli.profiles import profile_exists + if not profile_exists(name): + print(f"Error: Profile '{name}' does not exist.") + sys.exit(1) + + alias_name = custom_name or name + + if remove: + if remove_wrapper_script(alias_name): + print(f"✓ Removed alias '{alias_name}'") + else: + print(f"No alias '{alias_name}' found to remove.") + else: + collision = check_alias_collision(alias_name) + if collision: + print(f"Error: {collision}") + sys.exit(1) + wrapper_path = create_wrapper_script(alias_name) + if wrapper_path: + # If custom name, write the profile name into the wrapper + if custom_name: + wrapper_path.write_text(f'#!/bin/sh\nexec hermes -p {name} "$@"\n') + print(f"✓ Alias created: {wrapper_path}") + if not _is_wrapper_dir_in_path(): + print(f"⚠ {_get_wrapper_dir()} is not in your PATH.") + + elif action == "rename": + from hermes_cli.profiles import rename_profile + try: + new_dir = rename_profile(args.old_name, args.new_name) + print(f"\nProfile renamed: {args.old_name} → {args.new_name}") + print(f"Path: {new_dir}\n") + except (ValueError, FileExistsError, FileNotFoundError) as e: + print(f"Error: {e}") + sys.exit(1) + + elif action == "export": + from hermes_cli.profiles import export_profile + name = args.profile_name + output = args.output or f"{name}.tar.gz" + try: + result_path = export_profile(name, output) + print(f"✓ Exported '{name}' to {result_path}") + except (ValueError, FileNotFoundError) as e: + print(f"Error: {e}") + sys.exit(1) + + elif action == "import": + from hermes_cli.profiles import import_profile + try: + profile_dir = import_profile(args.archive, name=getattr(args, "import_name", None)) + name = profile_dir.name + print(f"✓ Imported profile '{name}' at {profile_dir}") + + # Offer to create alias + collision = check_alias_collision(name) + if not collision: + wrapper_path = create_wrapper_script(name) + if wrapper_path: + print(f" Wrapper created: {wrapper_path}") + print() + except (ValueError, FileExistsError, FileNotFoundError) as e: + print(f"Error: {e}") + sys.exit(1) + + +def cmd_dashboard(args): + """Start the web UI server.""" + try: + import fastapi # noqa: F401 + import uvicorn # noqa: F401 + except ImportError: + print("Web UI dependencies not installed.") + print("Install them with: pip install hermes-agent[web]") + sys.exit(1) + + if not _build_web_ui(PROJECT_ROOT / "web", fatal=True): + sys.exit(1) + + from hermes_cli.web_server import start_server + start_server( + host=args.host, + port=args.port, + open_browser=not args.no_open, + ) + + +def cmd_completion(args): + """Print shell completion script.""" + from hermes_cli.profiles import generate_bash_completion, generate_zsh_completion + shell = getattr(args, "shell", "bash") + if shell == "zsh": + print(generate_zsh_completion()) + else: + print(generate_bash_completion()) + + +def cmd_logs(args): + """View and filter Hermes log files.""" + from hermes_cli.logs import tail_log, list_logs + + log_name = getattr(args, "log_name", "agent") or "agent" + + if log_name == "list": + list_logs() + return + + tail_log( + log_name, + num_lines=getattr(args, "lines", 50), + follow=getattr(args, "follow", False), + level=getattr(args, "level", None), + session=getattr(args, "session", None), + since=getattr(args, "since", None), + component=getattr(args, "component", None), + ) + + +def main(): + """Main entry point for hermes CLI.""" + parser = argparse.ArgumentParser( + prog="hermes", + description="Hermes Agent - AI assistant with tool-calling capabilities", + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog=""" +Examples: + hermes Start interactive chat + hermes chat -q "Hello" Single query mode + hermes -c Resume the most recent session + hermes -c "my project" Resume a session by name (latest in lineage) + hermes --resume Resume a specific session by ID + hermes setup Run setup wizard + hermes logout Clear stored authentication + hermes auth add Add a pooled credential + hermes auth list List pooled credentials + hermes auth remove

Remove pooled credential by index, id, or label + hermes auth reset Clear exhaustion status for a provider + hermes model Select default model + hermes config View configuration + hermes config edit Edit config in $EDITOR + hermes config set model gpt-4 Set a config value + hermes gateway Run messaging gateway + hermes -s hermes-agent-dev,github-auth + hermes -w Start in isolated git worktree + hermes gateway install Install gateway background service + hermes sessions list List past sessions + hermes sessions browse Interactive session picker + hermes sessions rename ID T Rename/title a session + hermes logs View agent.log (last 50 lines) + hermes logs -f Follow agent.log in real time + hermes logs errors View errors.log + hermes logs --since 1h Lines from the last hour + hermes debug share Upload debug report for support + hermes update Update to latest version + +For more help on a command: + hermes --help +""" + ) + + parser.add_argument( + "--version", "-V", + action="store_true", + help="Show version and exit" + ) + parser.add_argument( + "--resume", "-r", + metavar="SESSION", + default=None, + help="Resume a previous session by ID or title" + ) + parser.add_argument( + "--continue", "-c", + dest="continue_last", + nargs="?", + const=True, + default=None, + metavar="SESSION_NAME", + help="Resume a session by name, or the most recent if no name given" + ) + parser.add_argument( + "--worktree", "-w", + action="store_true", + default=False, + help="Run in an isolated git worktree (for parallel agents)" + ) + parser.add_argument( + "--skills", "-s", + action="append", + default=None, + help="Preload one or more skills for the session (repeat flag or comma-separate)" + ) + parser.add_argument( + "--yolo", + action="store_true", + default=False, + help="Bypass all dangerous command approval prompts (use at your own risk)" + ) + parser.add_argument( + "--pass-session-id", + action="store_true", + default=False, + help="Include the session ID in the agent's system prompt" + ) + + subparsers = parser.add_subparsers(dest="command", help="Command to run") + + # ========================================================================= + # chat command + # ========================================================================= + chat_parser = subparsers.add_parser( + "chat", + help="Interactive chat with the agent", + description="Start an interactive chat session with Hermes Agent" + ) + chat_parser.add_argument( + "-q", "--query", + help="Single query (non-interactive mode)" + ) + chat_parser.add_argument( + "--image", + help="Optional local image path to attach to a single query" + ) + chat_parser.add_argument( + "-m", "--model", + help="Model to use (e.g., anthropic/claude-sonnet-4)" + ) + chat_parser.add_argument( + "-t", "--toolsets", + help="Comma-separated toolsets to enable" + ) + chat_parser.add_argument( + "-s", "--skills", + action="append", + default=argparse.SUPPRESS, + help="Preload one or more skills for the session (repeat flag or comma-separate)" + ) + chat_parser.add_argument( + "--provider", + choices=["auto", "openrouter", "nous", "openai-codex", "copilot-acp", "copilot", "anthropic", "gemini", "huggingface", "zai", "kimi-coding", "kimi-coding-cn", "minimax", "minimax-cn", "kilocode", "xiaomi", "arcee"], + default=None, + help="Inference provider (default: auto)" + ) + chat_parser.add_argument( + "-v", "--verbose", + action="store_true", + help="Verbose output" + ) + chat_parser.add_argument( + "-Q", "--quiet", + action="store_true", + help="Quiet mode for programmatic use: suppress banner, spinner, and tool previews. Only output the final response and session info." + ) + chat_parser.add_argument( + "--resume", "-r", + metavar="SESSION_ID", + default=argparse.SUPPRESS, + help="Resume a previous session by ID (shown on exit)" + ) + chat_parser.add_argument( + "--continue", "-c", + dest="continue_last", + nargs="?", + const=True, + default=argparse.SUPPRESS, + metavar="SESSION_NAME", + help="Resume a session by name, or the most recent if no name given" + ) + chat_parser.add_argument( + "--worktree", "-w", + action="store_true", + default=argparse.SUPPRESS, + help="Run in an isolated git worktree (for parallel agents on the same repo)" + ) + chat_parser.add_argument( + "--checkpoints", + action="store_true", + default=False, + help="Enable filesystem checkpoints before destructive file operations (use /rollback to restore)" + ) + chat_parser.add_argument( + "--max-turns", + type=int, + default=None, + metavar="N", + help="Maximum tool-calling iterations per conversation turn (default: 90, or agent.max_turns in config)" + ) + chat_parser.add_argument( + "--yolo", + action="store_true", + default=argparse.SUPPRESS, + help="Bypass all dangerous command approval prompts (use at your own risk)" + ) + chat_parser.add_argument( + "--pass-session-id", + action="store_true", + default=argparse.SUPPRESS, + help="Include the session ID in the agent's system prompt" + ) + chat_parser.add_argument( + "--source", + default=None, + help="Session source tag for filtering (default: cli). Use 'tool' for third-party integrations that should not appear in user session lists." + ) + chat_parser.set_defaults(func=cmd_chat) + + # ========================================================================= + # model command + # ========================================================================= + model_parser = subparsers.add_parser( + "model", + help="Select default model and provider", + description="Interactively select your inference provider and default model" + ) + model_parser.add_argument( + "--portal-url", + help="Portal base URL for Nous login (default: production portal)" + ) + model_parser.add_argument( + "--inference-url", + help="Inference API base URL for Nous login (default: production inference API)" + ) + model_parser.add_argument( + "--client-id", + default=None, + help="OAuth client id to use for Nous login (default: hermes-cli)" + ) + model_parser.add_argument( + "--scope", + default=None, + help="OAuth scope to request for Nous login" + ) + model_parser.add_argument( + "--no-browser", + action="store_true", + help="Do not attempt to open the browser automatically during Nous login" + ) + model_parser.add_argument( + "--timeout", + type=float, + default=15.0, + help="HTTP request timeout in seconds for Nous login (default: 15)" + ) + model_parser.add_argument( + "--ca-bundle", + help="Path to CA bundle PEM file for Nous TLS verification" + ) + model_parser.add_argument( + "--insecure", + action="store_true", + help="Disable TLS verification for Nous login (testing only)" + ) + model_parser.set_defaults(func=cmd_model) + + # ========================================================================= + # gateway command + # ========================================================================= + gateway_parser = subparsers.add_parser( + "gateway", + help="Messaging gateway management", + description="Manage the messaging gateway (Telegram, Discord, WhatsApp)" + ) + gateway_subparsers = gateway_parser.add_subparsers(dest="gateway_command") + + # gateway run (default) + gateway_run = gateway_subparsers.add_parser("run", help="Run gateway in foreground (recommended for WSL, Docker, Termux)") + gateway_run.add_argument("-v", "--verbose", action="count", default=0, + help="Increase stderr log verbosity (-v=INFO, -vv=DEBUG)") + gateway_run.add_argument("-q", "--quiet", action="store_true", + help="Suppress all stderr log output") + gateway_run.add_argument("--replace", action="store_true", + help="Replace any existing gateway instance (useful for systemd)") + + # gateway start + gateway_start = gateway_subparsers.add_parser("start", help="Start the installed systemd/launchd background service") + gateway_start.add_argument("--system", action="store_true", help="Target the Linux system-level gateway service") + + # gateway stop + gateway_stop = gateway_subparsers.add_parser("stop", help="Stop gateway service") + gateway_stop.add_argument("--system", action="store_true", help="Target the Linux system-level gateway service") + gateway_stop.add_argument("--all", action="store_true", help="Stop ALL gateway processes across all profiles") + + # gateway restart + gateway_restart = gateway_subparsers.add_parser("restart", help="Restart gateway service") + gateway_restart.add_argument("--system", action="store_true", help="Target the Linux system-level gateway service") + + # gateway status + gateway_status = gateway_subparsers.add_parser("status", help="Show gateway status") + gateway_status.add_argument("--deep", action="store_true", help="Deep status check") + gateway_status.add_argument("--system", action="store_true", help="Target the Linux system-level gateway service") + + # gateway install + gateway_install = gateway_subparsers.add_parser("install", help="Install gateway as a systemd/launchd background service") + gateway_install.add_argument("--force", action="store_true", help="Force reinstall") + gateway_install.add_argument("--system", action="store_true", help="Install as a Linux system-level service (starts at boot)") + gateway_install.add_argument("--run-as-user", dest="run_as_user", help="User account the Linux system service should run as") + + # gateway uninstall + gateway_uninstall = gateway_subparsers.add_parser("uninstall", help="Uninstall gateway service") + gateway_uninstall.add_argument("--system", action="store_true", help="Target the Linux system-level gateway service") + + # gateway setup + gateway_subparsers.add_parser("setup", help="Configure messaging platforms") + + gateway_parser.set_defaults(func=cmd_gateway) + + # ========================================================================= + # setup command + # ========================================================================= + setup_parser = subparsers.add_parser( + "setup", + help="Interactive setup wizard", + description="Configure Hermes Agent with an interactive wizard. " + "Run a specific section: hermes setup model|tts|terminal|gateway|tools|agent" + ) + setup_parser.add_argument( + "section", + nargs="?", + choices=["model", "tts", "terminal", "gateway", "tools", "agent"], + default=None, + help="Run a specific setup section instead of the full wizard" + ) + setup_parser.add_argument( + "--non-interactive", + action="store_true", + help="Non-interactive mode (use defaults/env vars)" + ) + setup_parser.add_argument( + "--reset", + action="store_true", + help="Reset configuration to defaults" + ) + setup_parser.set_defaults(func=cmd_setup) + + # ========================================================================= + # whatsapp command + # ========================================================================= + whatsapp_parser = subparsers.add_parser( + "whatsapp", + help="Set up WhatsApp integration", + description="Configure WhatsApp and pair via QR code" + ) + whatsapp_parser.set_defaults(func=cmd_whatsapp) + + # ========================================================================= + # login command + # ========================================================================= + login_parser = subparsers.add_parser( + "login", + help="Authenticate with an inference provider", + description="Run OAuth device authorization flow for Hermes CLI" + ) + login_parser.add_argument( + "--provider", + choices=["nous", "openai-codex"], + default=None, + help="Provider to authenticate with (default: nous)" + ) + login_parser.add_argument( + "--portal-url", + help="Portal base URL (default: production portal)" + ) + login_parser.add_argument( + "--inference-url", + help="Inference API base URL (default: production inference API)" + ) + login_parser.add_argument( + "--client-id", + default=None, + help="OAuth client id to use (default: hermes-cli)" + ) + login_parser.add_argument( + "--scope", + default=None, + help="OAuth scope to request" + ) + login_parser.add_argument( + "--no-browser", + action="store_true", + help="Do not attempt to open the browser automatically" + ) + login_parser.add_argument( + "--timeout", + type=float, + default=15.0, + help="HTTP request timeout in seconds (default: 15)" + ) + login_parser.add_argument( + "--ca-bundle", + help="Path to CA bundle PEM file for TLS verification" + ) + login_parser.add_argument( + "--insecure", + action="store_true", + help="Disable TLS verification (testing only)" + ) + login_parser.set_defaults(func=cmd_login) + + # ========================================================================= + # logout command + # ========================================================================= + logout_parser = subparsers.add_parser( + "logout", + help="Clear authentication for an inference provider", + description="Remove stored credentials and reset provider config" + ) + logout_parser.add_argument( + "--provider", + choices=["nous", "openai-codex"], + default=None, + help="Provider to log out from (default: active provider)" + ) + logout_parser.set_defaults(func=cmd_logout) + + auth_parser = subparsers.add_parser( + "auth", + help="Manage pooled provider credentials", + ) + auth_subparsers = auth_parser.add_subparsers(dest="auth_action") + auth_add = auth_subparsers.add_parser("add", help="Add a pooled credential") + auth_add.add_argument("provider", help="Provider id (for example: anthropic, openai-codex, openrouter)") + auth_add.add_argument("--type", dest="auth_type", choices=["oauth", "api-key", "api_key"], help="Credential type to add") + auth_add.add_argument("--label", help="Optional display label") + auth_add.add_argument("--api-key", help="API key value (otherwise prompted securely)") + auth_add.add_argument("--portal-url", help="Nous portal base URL") + auth_add.add_argument("--inference-url", help="Nous inference base URL") + auth_add.add_argument("--client-id", help="OAuth client id") + auth_add.add_argument("--scope", help="OAuth scope override") + auth_add.add_argument("--no-browser", action="store_true", help="Do not auto-open a browser for OAuth login") + auth_add.add_argument("--timeout", type=float, help="OAuth/network timeout in seconds") + auth_add.add_argument("--insecure", action="store_true", help="Disable TLS verification for OAuth login") + auth_add.add_argument("--ca-bundle", help="Custom CA bundle for OAuth login") + auth_list = auth_subparsers.add_parser("list", help="List pooled credentials") + auth_list.add_argument("provider", nargs="?", help="Optional provider filter") + auth_remove = auth_subparsers.add_parser("remove", help="Remove a pooled credential by index, id, or label") + auth_remove.add_argument("provider", help="Provider id") + auth_remove.add_argument("target", help="Credential index, entry id, or exact label") + auth_reset = auth_subparsers.add_parser("reset", help="Clear exhaustion status for all credentials for a provider") + auth_reset.add_argument("provider", help="Provider id") + auth_parser.set_defaults(func=cmd_auth) + + # ========================================================================= + # status command + # ========================================================================= + status_parser = subparsers.add_parser( + "status", + help="Show status of all components", + description="Display status of Hermes Agent components" + ) + status_parser.add_argument( + "--all", + action="store_true", + help="Show all details (redacted for sharing)" + ) + status_parser.add_argument( + "--deep", + action="store_true", + help="Run deep checks (may take longer)" + ) + status_parser.set_defaults(func=cmd_status) + + # ========================================================================= + # cron command + # ========================================================================= + cron_parser = subparsers.add_parser( + "cron", + help="Cron job management", + description="Manage scheduled tasks" + ) + cron_subparsers = cron_parser.add_subparsers(dest="cron_command") + + # cron list + cron_list = cron_subparsers.add_parser("list", help="List scheduled jobs") + cron_list.add_argument("--all", action="store_true", help="Include disabled jobs") + + # cron create/add + cron_create = cron_subparsers.add_parser("create", aliases=["add"], help="Create a scheduled job") + cron_create.add_argument("schedule", help="Schedule like '30m', 'every 2h', or '0 9 * * *'") + cron_create.add_argument("prompt", nargs="?", help="Optional self-contained prompt or task instruction") + cron_create.add_argument("--name", help="Optional human-friendly job name") + cron_create.add_argument("--deliver", help="Delivery target: origin, local, telegram, discord, signal, or platform:chat_id") + cron_create.add_argument("--repeat", type=int, help="Optional repeat count") + cron_create.add_argument("--skill", dest="skills", action="append", help="Attach a skill. Repeat to add multiple skills.") + cron_create.add_argument("--script", help="Path to a Python script whose stdout is injected into the prompt each run") + + # cron edit + cron_edit = cron_subparsers.add_parser("edit", help="Edit an existing scheduled job") + cron_edit.add_argument("job_id", help="Job ID to edit") + cron_edit.add_argument("--schedule", help="New schedule") + cron_edit.add_argument("--prompt", help="New prompt/task instruction") + cron_edit.add_argument("--name", help="New job name") + cron_edit.add_argument("--deliver", help="New delivery target") + cron_edit.add_argument("--repeat", type=int, help="New repeat count") + cron_edit.add_argument("--skill", dest="skills", action="append", help="Replace the job's skills with this set. Repeat to attach multiple skills.") + cron_edit.add_argument("--add-skill", dest="add_skills", action="append", help="Append a skill without replacing the existing list. Repeatable.") + cron_edit.add_argument("--remove-skill", dest="remove_skills", action="append", help="Remove a specific attached skill. Repeatable.") + cron_edit.add_argument("--clear-skills", action="store_true", help="Remove all attached skills from the job") + cron_edit.add_argument("--script", help="Path to a Python script whose stdout is injected into the prompt each run. Pass empty string to clear.") + + # lifecycle actions + cron_pause = cron_subparsers.add_parser("pause", help="Pause a scheduled job") + cron_pause.add_argument("job_id", help="Job ID to pause") + + cron_resume = cron_subparsers.add_parser("resume", help="Resume a paused job") + cron_resume.add_argument("job_id", help="Job ID to resume") + + cron_run = cron_subparsers.add_parser("run", help="Run a job on the next scheduler tick") + cron_run.add_argument("job_id", help="Job ID to trigger") + + cron_remove = cron_subparsers.add_parser("remove", aliases=["rm", "delete"], help="Remove a scheduled job") + cron_remove.add_argument("job_id", help="Job ID to remove") + + # cron status + cron_subparsers.add_parser("status", help="Check if cron scheduler is running") + + # cron tick (mostly for debugging) + cron_subparsers.add_parser("tick", help="Run due jobs once and exit") + + cron_parser.set_defaults(func=cmd_cron) + + # ========================================================================= + # webhook command + # ========================================================================= + webhook_parser = subparsers.add_parser( + "webhook", + help="Manage dynamic webhook subscriptions", + description="Create, list, and remove webhook subscriptions for event-driven agent activation", + ) + webhook_subparsers = webhook_parser.add_subparsers(dest="webhook_action") + + wh_sub = webhook_subparsers.add_parser("subscribe", aliases=["add"], help="Create a webhook subscription") + wh_sub.add_argument("name", help="Route name (used in URL: /webhooks/)") + wh_sub.add_argument("--prompt", default="", help="Prompt template with {dot.notation} payload refs") + wh_sub.add_argument("--events", default="", help="Comma-separated event types to accept") + wh_sub.add_argument("--description", default="", help="What this subscription does") + wh_sub.add_argument("--skills", default="", help="Comma-separated skill names to load") + wh_sub.add_argument("--deliver", default="log", help="Delivery target: log, telegram, discord, slack, etc.") + wh_sub.add_argument("--deliver-chat-id", default="", help="Target chat ID for cross-platform delivery") + wh_sub.add_argument("--secret", default="", help="HMAC secret (auto-generated if omitted)") + + webhook_subparsers.add_parser("list", aliases=["ls"], help="List all dynamic subscriptions") + + wh_rm = webhook_subparsers.add_parser("remove", aliases=["rm"], help="Remove a subscription") + wh_rm.add_argument("name", help="Subscription name to remove") + + wh_test = webhook_subparsers.add_parser("test", help="Send a test POST to a webhook route") + wh_test.add_argument("name", help="Subscription name to test") + wh_test.add_argument("--payload", default="", help="JSON payload to send (default: test payload)") + + webhook_parser.set_defaults(func=cmd_webhook) + + # ========================================================================= + # doctor command + # ========================================================================= + doctor_parser = subparsers.add_parser( + "doctor", + help="Check configuration and dependencies", + description="Diagnose issues with Hermes Agent setup" + ) + doctor_parser.add_argument( + "--fix", + action="store_true", + help="Attempt to fix issues automatically" + ) + doctor_parser.set_defaults(func=cmd_doctor) + + # ========================================================================= + # dump command + # ========================================================================= + dump_parser = subparsers.add_parser( + "dump", + help="Dump setup summary for support/debugging", + description="Output a compact, plain-text summary of your Hermes setup " + "that can be copy-pasted into Discord/GitHub for support context" + ) + dump_parser.add_argument( + "--show-keys", + action="store_true", + help="Show redacted API key prefixes (first/last 4 chars) instead of just set/not set" + ) + dump_parser.set_defaults(func=cmd_dump) + + # ========================================================================= + # debug command + # ========================================================================= + debug_parser = subparsers.add_parser( + "debug", + help="Debug tools — upload logs and system info for support", + description="Debug utilities for Hermes Agent. Use 'hermes debug share' to " + "upload a debug report (system info + recent logs) to a paste " + "service and get a shareable URL.", + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog="""\ +Examples: + hermes debug share Upload debug report and print URL + hermes debug share --lines 500 Include more log lines + hermes debug share --expire 30 Keep paste for 30 days + hermes debug share --local Print report locally (no upload) +""", + ) + debug_sub = debug_parser.add_subparsers(dest="debug_command") + share_parser = debug_sub.add_parser( + "share", + help="Upload debug report to a paste service and print a shareable URL", + ) + share_parser.add_argument( + "--lines", type=int, default=200, + help="Number of log lines to include per log file (default: 200)", + ) + share_parser.add_argument( + "--expire", type=int, default=7, + help="Paste expiry in days (default: 7)", + ) + share_parser.add_argument( + "--local", action="store_true", + help="Print the report locally instead of uploading", + ) + debug_parser.set_defaults(func=cmd_debug) + + # ========================================================================= + # backup command + # ========================================================================= + backup_parser = subparsers.add_parser( + "backup", + help="Back up Hermes home directory to a zip file", + description="Create a zip archive of your entire Hermes configuration, " + "skills, sessions, and data (excludes the hermes-agent codebase). " + "Use --quick for a fast snapshot of just critical state files." + ) + backup_parser.add_argument( + "-o", "--output", + help="Output path for the zip file (default: ~/hermes-backup-.zip)" + ) + backup_parser.add_argument( + "-q", "--quick", + action="store_true", + help="Quick snapshot: only critical state files (config, state.db, .env, auth, cron)" + ) + backup_parser.add_argument( + "-l", "--label", + help="Label for the snapshot (only used with --quick)" + ) + backup_parser.set_defaults(func=cmd_backup) + + # ========================================================================= + # import command + # ========================================================================= + import_parser = subparsers.add_parser( + "import", + help="Restore a Hermes backup from a zip file", + description="Extract a previously created Hermes backup into your " + "Hermes home directory, restoring configuration, skills, " + "sessions, and data" + ) + import_parser.add_argument( + "zipfile", + help="Path to the backup zip file" + ) + import_parser.add_argument( + "--force", "-f", + action="store_true", + help="Overwrite existing files without confirmation" + ) + import_parser.set_defaults(func=cmd_import) + + # ========================================================================= + # config command + # ========================================================================= + config_parser = subparsers.add_parser( + "config", + help="View and edit configuration", + description="Manage Hermes Agent configuration" + ) + config_subparsers = config_parser.add_subparsers(dest="config_command") + + # config show (default) + config_subparsers.add_parser("show", help="Show current configuration") + + # config edit + config_subparsers.add_parser("edit", help="Open config file in editor") + + # config set + config_set = config_subparsers.add_parser("set", help="Set a configuration value") + config_set.add_argument("key", nargs="?", help="Configuration key (e.g., model, terminal.backend)") + config_set.add_argument("value", nargs="?", help="Value to set") + + # config path + config_subparsers.add_parser("path", help="Print config file path") + + # config env-path + config_subparsers.add_parser("env-path", help="Print .env file path") + + # config check + config_subparsers.add_parser("check", help="Check for missing/outdated config") + + # config migrate + config_subparsers.add_parser("migrate", help="Update config with new options") + + config_parser.set_defaults(func=cmd_config) + + # ========================================================================= + # pairing command + # ========================================================================= + pairing_parser = subparsers.add_parser( + "pairing", + help="Manage DM pairing codes for user authorization", + description="Approve or revoke user access via pairing codes" + ) + pairing_sub = pairing_parser.add_subparsers(dest="pairing_action") + + pairing_sub.add_parser("list", help="Show pending + approved users") + + pairing_approve_parser = pairing_sub.add_parser("approve", help="Approve a pairing code") + pairing_approve_parser.add_argument("platform", help="Platform name (telegram, discord, slack, whatsapp)") + pairing_approve_parser.add_argument("code", help="Pairing code to approve") + + pairing_revoke_parser = pairing_sub.add_parser("revoke", help="Revoke user access") + pairing_revoke_parser.add_argument("platform", help="Platform name") + pairing_revoke_parser.add_argument("user_id", help="User ID to revoke") + + pairing_sub.add_parser("clear-pending", help="Clear all pending codes") + + def cmd_pairing(args): + from hermes_cli.pairing import pairing_command + pairing_command(args) + + pairing_parser.set_defaults(func=cmd_pairing) + + # ========================================================================= + # skills command + # ========================================================================= + skills_parser = subparsers.add_parser( + "skills", + help="Search, install, configure, and manage skills", + description="Search, install, inspect, audit, configure, and manage skills from skills.sh, well-known agent skill endpoints, GitHub, ClawHub, and other registries." + ) + skills_subparsers = skills_parser.add_subparsers(dest="skills_action") + + skills_browse = skills_subparsers.add_parser("browse", help="Browse all available skills (paginated)") + skills_browse.add_argument("--page", type=int, default=1, help="Page number (default: 1)") + skills_browse.add_argument("--size", type=int, default=20, help="Results per page (default: 20)") + skills_browse.add_argument("--source", default="all", + choices=["all", "official", "skills-sh", "well-known", "github", "clawhub", "lobehub"], + help="Filter by source (default: all)") + + skills_search = skills_subparsers.add_parser("search", help="Search skill registries") + skills_search.add_argument("query", help="Search query") + skills_search.add_argument("--source", default="all", choices=["all", "official", "skills-sh", "well-known", "github", "clawhub", "lobehub"]) + skills_search.add_argument("--limit", type=int, default=10, help="Max results") + + skills_install = skills_subparsers.add_parser("install", help="Install a skill") + skills_install.add_argument("identifier", help="Skill identifier (e.g. openai/skills/skill-creator)") + skills_install.add_argument("--category", default="", help="Category folder to install into") + skills_install.add_argument("--force", action="store_true", help="Install despite blocked scan verdict") + skills_install.add_argument("--yes", "-y", action="store_true", help="Skip confirmation prompt (needed in TUI mode)") + + skills_inspect = skills_subparsers.add_parser("inspect", help="Preview a skill without installing") + skills_inspect.add_argument("identifier", help="Skill identifier") + + skills_list = skills_subparsers.add_parser("list", help="List installed skills") + skills_list.add_argument("--source", default="all", choices=["all", "hub", "builtin", "local"]) + + skills_check = skills_subparsers.add_parser("check", help="Check installed hub skills for updates") + skills_check.add_argument("name", nargs="?", help="Specific skill to check (default: all)") + + skills_update = skills_subparsers.add_parser("update", help="Update installed hub skills") + skills_update.add_argument("name", nargs="?", help="Specific skill to update (default: all outdated skills)") + + skills_audit = skills_subparsers.add_parser("audit", help="Re-scan installed hub skills") + skills_audit.add_argument("name", nargs="?", help="Specific skill to audit (default: all)") + + skills_uninstall = skills_subparsers.add_parser("uninstall", help="Remove a hub-installed skill") + skills_uninstall.add_argument("name", help="Skill name to remove") + + skills_publish = skills_subparsers.add_parser("publish", help="Publish a skill to a registry") + skills_publish.add_argument("skill_path", help="Path to skill directory") + skills_publish.add_argument("--to", default="github", choices=["github", "clawhub"], help="Target registry") + skills_publish.add_argument("--repo", default="", help="Target GitHub repo (e.g. openai/skills)") + + skills_snapshot = skills_subparsers.add_parser("snapshot", help="Export/import skill configurations") + snapshot_subparsers = skills_snapshot.add_subparsers(dest="snapshot_action") + snap_export = snapshot_subparsers.add_parser("export", help="Export installed skills to a file") + snap_export.add_argument("output", help="Output JSON file path (use - for stdout)") + snap_import = snapshot_subparsers.add_parser("import", help="Import and install skills from a file") + snap_import.add_argument("input", help="Input JSON file path") + snap_import.add_argument("--force", action="store_true", help="Force install despite caution verdict") + + skills_tap = skills_subparsers.add_parser("tap", help="Manage skill sources") + tap_subparsers = skills_tap.add_subparsers(dest="tap_action") + tap_subparsers.add_parser("list", help="List configured taps") + tap_add = tap_subparsers.add_parser("add", help="Add a GitHub repo as skill source") + tap_add.add_argument("repo", help="GitHub repo (e.g. owner/repo)") + tap_rm = tap_subparsers.add_parser("remove", help="Remove a tap") + tap_rm.add_argument("name", help="Tap name to remove") + + # config sub-action: interactive enable/disable + skills_subparsers.add_parser("config", help="Interactive skill configuration — enable/disable individual skills") + + def cmd_skills(args): + # Route 'config' action to skills_config module + if getattr(args, 'skills_action', None) == 'config': + _require_tty("skills config") + from hermes_cli.skills_config import skills_command as skills_config_command + skills_config_command(args) + else: + from hermes_cli.skills_hub import skills_command + skills_command(args) + + skills_parser.set_defaults(func=cmd_skills) + + # ========================================================================= + # plugins command + # ========================================================================= + plugins_parser = subparsers.add_parser( + "plugins", + help="Manage plugins — install, update, remove, list", + description="Install plugins from Git repositories, update, remove, or list them.", + ) + plugins_subparsers = plugins_parser.add_subparsers(dest="plugins_action") + + plugins_install = plugins_subparsers.add_parser( + "install", help="Install a plugin from a Git URL or owner/repo" + ) + plugins_install.add_argument( + "identifier", + help="Git URL or owner/repo shorthand (e.g. anpicasso/hermes-plugin-chrome-profiles)", + ) + plugins_install.add_argument( + "--force", "-f", action="store_true", + help="Remove existing plugin and reinstall", + ) + + plugins_update = plugins_subparsers.add_parser( + "update", help="Pull latest changes for an installed plugin" + ) + plugins_update.add_argument("name", help="Plugin name to update") + + plugins_remove = plugins_subparsers.add_parser( + "remove", aliases=["rm", "uninstall"], help="Remove an installed plugin" + ) + plugins_remove.add_argument("name", help="Plugin directory name to remove") + + plugins_subparsers.add_parser("list", aliases=["ls"], help="List installed plugins") + + plugins_enable = plugins_subparsers.add_parser( + "enable", help="Enable a disabled plugin" + ) + plugins_enable.add_argument("name", help="Plugin name to enable") + + plugins_disable = plugins_subparsers.add_parser( + "disable", help="Disable a plugin without removing it" + ) + plugins_disable.add_argument("name", help="Plugin name to disable") + + def cmd_plugins(args): + from hermes_cli.plugins_cmd import plugins_command + plugins_command(args) + + plugins_parser.set_defaults(func=cmd_plugins) + + # ========================================================================= + # Plugin CLI commands — dynamically registered by memory/general plugins. + # Plugins provide a register_cli(subparser) function that builds their + # own argparse tree. No hardcoded plugin commands in main.py. + # ========================================================================= + try: + from plugins.memory import discover_plugin_cli_commands + for cmd_info in discover_plugin_cli_commands(): + plugin_parser = subparsers.add_parser( + cmd_info["name"], + help=cmd_info["help"], + description=cmd_info.get("description", ""), + formatter_class=__import__("argparse").RawDescriptionHelpFormatter, + ) + cmd_info["setup_fn"](plugin_parser) + except Exception as _exc: + import logging as _log + _log.getLogger(__name__).debug("Plugin CLI discovery failed: %s", _exc) + + # ========================================================================= + # memory command + # ========================================================================= + memory_parser = subparsers.add_parser( + "memory", + help="Configure external memory provider", + description=( + "Set up and manage external memory provider plugins.\n\n" + "Available providers: honcho, openviking, mem0, hindsight,\n" + "holographic, retaindb, byterover.\n\n" + "Only one external provider can be active at a time.\n" + "Built-in memory (MEMORY.md/USER.md) is always active." + ), + ) + memory_sub = memory_parser.add_subparsers(dest="memory_command") + memory_sub.add_parser("setup", help="Interactive provider selection and configuration") + memory_sub.add_parser("status", help="Show current memory provider config") + memory_sub.add_parser("off", help="Disable external provider (built-in only)") + + def cmd_memory(args): + sub = getattr(args, "memory_command", None) + if sub == "off": + from hermes_cli.config import load_config, save_config + config = load_config() + if not isinstance(config.get("memory"), dict): + config["memory"] = {} + config["memory"]["provider"] = "" + save_config(config) + print("\n ✓ Memory provider: built-in only") + print(" Saved to config.yaml\n") + else: + from hermes_cli.memory_setup import memory_command + memory_command(args) + + memory_parser.set_defaults(func=cmd_memory) + + # ========================================================================= + # tools command + # ========================================================================= + tools_parser = subparsers.add_parser( + "tools", + help="Configure which tools are enabled per platform", + description=( + "Enable, disable, or list tools for CLI, Telegram, Discord, etc.\n\n" + "Built-in toolsets use plain names (e.g. web, memory).\n" + "MCP tools use server:tool notation (e.g. github:create_issue).\n\n" + "Run 'hermes tools' with no subcommand for the interactive configuration UI." + ), + ) + tools_parser.add_argument( + "--summary", + action="store_true", + help="Print a summary of enabled tools per platform and exit" + ) + tools_sub = tools_parser.add_subparsers(dest="tools_action") + + # hermes tools list [--platform cli] + tools_list_p = tools_sub.add_parser( + "list", + help="Show all tools and their enabled/disabled status", + ) + tools_list_p.add_argument( + "--platform", default="cli", + help="Platform to show (default: cli)", + ) + + # hermes tools disable [--platform cli] + tools_disable_p = tools_sub.add_parser( + "disable", + help="Disable toolsets or MCP tools", + ) + tools_disable_p.add_argument( + "names", nargs="+", metavar="NAME", + help="Toolset name (e.g. web) or MCP tool in server:tool form", + ) + tools_disable_p.add_argument( + "--platform", default="cli", + help="Platform to apply to (default: cli)", + ) + + # hermes tools enable [--platform cli] + tools_enable_p = tools_sub.add_parser( + "enable", + help="Enable toolsets or MCP tools", + ) + tools_enable_p.add_argument( + "names", nargs="+", metavar="NAME", + help="Toolset name or MCP tool in server:tool form", + ) + tools_enable_p.add_argument( + "--platform", default="cli", + help="Platform to apply to (default: cli)", + ) + + def cmd_tools(args): + action = getattr(args, "tools_action", None) + if action in ("list", "disable", "enable"): + from hermes_cli.tools_config import tools_disable_enable_command + tools_disable_enable_command(args) + else: + _require_tty("tools") + from hermes_cli.tools_config import tools_command + tools_command(args) + + tools_parser.set_defaults(func=cmd_tools) + # ========================================================================= + # mcp command — manage MCP server connections + # ========================================================================= + mcp_parser = subparsers.add_parser( + "mcp", + help="Manage MCP servers and run Hermes as an MCP server", + description=( + "Manage MCP server connections and run Hermes as an MCP server.\n\n" + "MCP servers provide additional tools via the Model Context Protocol.\n" + "Use 'hermes mcp add' to connect to a new server, or\n" + "'hermes mcp serve' to expose Hermes conversations over MCP." + ), + ) + mcp_sub = mcp_parser.add_subparsers(dest="mcp_action") + + mcp_serve_p = mcp_sub.add_parser( + "serve", + help="Run Hermes as an MCP server (expose conversations to other agents)", + ) + mcp_serve_p.add_argument( + "-v", "--verbose", action="store_true", + help="Enable verbose logging on stderr", + ) + + mcp_add_p = mcp_sub.add_parser("add", help="Add an MCP server (discovery-first install)") + mcp_add_p.add_argument("name", help="Server name (used as config key)") + mcp_add_p.add_argument("--url", help="HTTP/SSE endpoint URL") + mcp_add_p.add_argument("--command", help="Stdio command (e.g. npx)") + mcp_add_p.add_argument("--args", nargs="*", default=[], help="Arguments for stdio command") + mcp_add_p.add_argument("--auth", choices=["oauth", "header"], help="Auth method") + mcp_add_p.add_argument("--preset", help="Known MCP preset name") + mcp_add_p.add_argument("--env", nargs="*", default=[], help="Environment variables for stdio servers (KEY=VALUE)") + + mcp_rm_p = mcp_sub.add_parser("remove", aliases=["rm"], help="Remove an MCP server") + mcp_rm_p.add_argument("name", help="Server name to remove") + + mcp_sub.add_parser("list", aliases=["ls"], help="List configured MCP servers") + + mcp_test_p = mcp_sub.add_parser("test", help="Test MCP server connection") + mcp_test_p.add_argument("name", help="Server name to test") + + mcp_cfg_p = mcp_sub.add_parser("configure", aliases=["config"], help="Toggle tool selection") + mcp_cfg_p.add_argument("name", help="Server name to configure") + + def cmd_mcp(args): + from hermes_cli.mcp_config import mcp_command + mcp_command(args) + + mcp_parser.set_defaults(func=cmd_mcp) + + # ========================================================================= + # sessions command + # ========================================================================= + sessions_parser = subparsers.add_parser( + "sessions", + help="Manage session history (list, rename, export, prune, delete)", + description="View and manage the SQLite session store" + ) + sessions_subparsers = sessions_parser.add_subparsers(dest="sessions_action") + + sessions_list = sessions_subparsers.add_parser("list", help="List recent sessions") + sessions_list.add_argument("--source", help="Filter by source (cli, telegram, discord, etc.)") + sessions_list.add_argument("--limit", type=int, default=20, help="Max sessions to show") + + sessions_export = sessions_subparsers.add_parser("export", help="Export sessions to a JSONL file") + sessions_export.add_argument("output", help="Output JSONL file path (use - for stdout)") + sessions_export.add_argument("--source", help="Filter by source") + sessions_export.add_argument("--session-id", help="Export a specific session") + + sessions_delete = sessions_subparsers.add_parser("delete", help="Delete a specific session") + sessions_delete.add_argument("session_id", help="Session ID to delete") + sessions_delete.add_argument("--yes", "-y", action="store_true", help="Skip confirmation") + + sessions_prune = sessions_subparsers.add_parser("prune", help="Delete old sessions") + sessions_prune.add_argument("--older-than", type=int, default=90, help="Delete sessions older than N days (default: 90)") + sessions_prune.add_argument("--source", help="Only prune sessions from this source") + sessions_prune.add_argument("--yes", "-y", action="store_true", help="Skip confirmation") + + sessions_subparsers.add_parser("stats", help="Show session store statistics") + + sessions_rename = sessions_subparsers.add_parser("rename", help="Set or change a session's title") + sessions_rename.add_argument("session_id", help="Session ID to rename") + sessions_rename.add_argument("title", nargs="+", help="New title for the session") + + sessions_browse = sessions_subparsers.add_parser( + "browse", + help="Interactive session picker — browse, search, and resume sessions", + ) + sessions_browse.add_argument("--source", help="Filter by source (cli, telegram, discord, etc.)") + sessions_browse.add_argument("--limit", type=int, default=50, help="Max sessions to load (default: 50)") + + def _confirm_prompt(prompt: str) -> bool: + """Prompt for y/N confirmation, safe against non-TTY environments.""" + try: + return input(prompt).strip().lower() in ("y", "yes") + except (EOFError, KeyboardInterrupt): + return False + + def cmd_sessions(args): + import json as _json + try: + from hermes_state import SessionDB + db = SessionDB() + except Exception as e: + print(f"Error: Could not open session database: {e}") + return + + action = args.sessions_action + + # Hide third-party tool sessions by default, but honour explicit --source + _source = getattr(args, "source", None) + _exclude = None if _source else ["tool"] + + if action == "list": + sessions = db.list_sessions_rich(source=args.source, exclude_sources=_exclude, limit=args.limit) + if not sessions: + print("No sessions found.") + return + has_titles = any(s.get("title") for s in sessions) + if has_titles: + print(f"{'Title':<32} {'Preview':<40} {'Last Active':<13} {'ID'}") + print("─" * 110) + else: + print(f"{'Preview':<50} {'Last Active':<13} {'Src':<6} {'ID'}") + print("─" * 95) + for s in sessions: + last_active = _relative_time(s.get("last_active")) + preview = s.get("preview", "")[:38] if has_titles else s.get("preview", "")[:48] + if has_titles: + title = (s.get("title") or "—")[:30] + sid = s["id"] + print(f"{title:<32} {preview:<40} {last_active:<13} {sid}") + else: + sid = s["id"] + print(f"{preview:<50} {last_active:<13} {s['source']:<6} {sid}") + + elif action == "export": + if args.session_id: + resolved_session_id = db.resolve_session_id(args.session_id) + if not resolved_session_id: + print(f"Session '{args.session_id}' not found.") + return + data = db.export_session(resolved_session_id) + if not data: + print(f"Session '{args.session_id}' not found.") + return + line = _json.dumps(data, ensure_ascii=False) + "\n" + if args.output == "-": + import sys + sys.stdout.write(line) + else: + with open(args.output, "w", encoding="utf-8") as f: + f.write(line) + print(f"Exported 1 session to {args.output}") + else: + sessions = db.export_all(source=args.source) + if args.output == "-": + import sys + for s in sessions: + sys.stdout.write(_json.dumps(s, ensure_ascii=False) + "\n") + else: + with open(args.output, "w", encoding="utf-8") as f: + for s in sessions: + f.write(_json.dumps(s, ensure_ascii=False) + "\n") + print(f"Exported {len(sessions)} sessions to {args.output}") + + elif action == "delete": + resolved_session_id = db.resolve_session_id(args.session_id) + if not resolved_session_id: + print(f"Session '{args.session_id}' not found.") + return + if not args.yes: + if not _confirm_prompt(f"Delete session '{resolved_session_id}' and all its messages? [y/N] "): + print("Cancelled.") + return + if db.delete_session(resolved_session_id): + print(f"Deleted session '{resolved_session_id}'.") + else: + print(f"Session '{args.session_id}' not found.") + + elif action == "prune": + days = args.older_than + source_msg = f" from '{args.source}'" if args.source else "" + if not args.yes: + if not _confirm_prompt(f"Delete all ended sessions older than {days} days{source_msg}? [y/N] "): + print("Cancelled.") + return + count = db.prune_sessions(older_than_days=days, source=args.source) + print(f"Pruned {count} session(s).") + + elif action == "rename": + resolved_session_id = db.resolve_session_id(args.session_id) + if not resolved_session_id: + print(f"Session '{args.session_id}' not found.") + return + title = " ".join(args.title) + try: + if db.set_session_title(resolved_session_id, title): + print(f"Session '{resolved_session_id}' renamed to: {title}") + else: + print(f"Session '{args.session_id}' not found.") + except ValueError as e: + print(f"Error: {e}") + + elif action == "browse": + limit = getattr(args, "limit", 50) or 50 + source = getattr(args, "source", None) + _browse_exclude = None if source else ["tool"] + sessions = db.list_sessions_rich(source=source, exclude_sources=_browse_exclude, limit=limit) + db.close() + if not sessions: + print("No sessions found.") + return + + selected_id = _session_browse_picker(sessions) + if not selected_id: + print("Cancelled.") + return + + # Launch hermes --resume by replacing the current process + print(f"Resuming session: {selected_id}") + import shutil + hermes_bin = shutil.which("hermes") + if hermes_bin: + os.execvp(hermes_bin, ["hermes", "--resume", selected_id]) + else: + # Fallback: re-invoke via python -m + os.execvp( + sys.executable, + [sys.executable, "-m", "hermes_cli.main", "--resume", selected_id], + ) + return # won't reach here after execvp + + elif action == "stats": + total = db.session_count() + msgs = db.message_count() + print(f"Total sessions: {total}") + print(f"Total messages: {msgs}") + for src in ["cli", "telegram", "discord", "whatsapp", "slack"]: + c = db.session_count(source=src) + if c > 0: + print(f" {src}: {c} sessions") + db_path = db.db_path + if db_path.exists(): + size_mb = os.path.getsize(db_path) / (1024 * 1024) + print(f"Database size: {size_mb:.1f} MB") + + else: + sessions_parser.print_help() + + db.close() + + sessions_parser.set_defaults(func=cmd_sessions) + + # ========================================================================= + # insights command + # ========================================================================= + insights_parser = subparsers.add_parser( + "insights", + help="Show usage insights and analytics", + description="Analyze session history to show token usage, costs, tool patterns, and activity trends" + ) + insights_parser.add_argument("--days", type=int, default=30, help="Number of days to analyze (default: 30)") + insights_parser.add_argument("--source", help="Filter by platform (cli, telegram, discord, etc.)") + + def cmd_insights(args): + try: + from hermes_state import SessionDB + from agent.insights import InsightsEngine + + db = SessionDB() + engine = InsightsEngine(db) + report = engine.generate(days=args.days, source=args.source) + print(engine.format_terminal(report)) + db.close() + except Exception as e: + print(f"Error generating insights: {e}") + + insights_parser.set_defaults(func=cmd_insights) + + # ========================================================================= + # claw command (OpenClaw migration) + # ========================================================================= + claw_parser = subparsers.add_parser( + "claw", + help="OpenClaw migration tools", + description="Migrate settings, memories, skills, and API keys from OpenClaw to Hermes" + ) + claw_subparsers = claw_parser.add_subparsers(dest="claw_action") + + # claw migrate + claw_migrate = claw_subparsers.add_parser( + "migrate", + help="Migrate from OpenClaw to Hermes", + description="Import settings, memories, skills, and API keys from an OpenClaw installation. " + "Always shows a preview before making changes." + ) + claw_migrate.add_argument( + "--source", + help="Path to OpenClaw directory (default: ~/.openclaw)" + ) + claw_migrate.add_argument( + "--dry-run", + action="store_true", + help="Preview only — stop after showing what would be migrated" + ) + claw_migrate.add_argument( + "--preset", + choices=["user-data", "full"], + default="full", + help="Migration preset (default: full). 'user-data' excludes secrets" + ) + claw_migrate.add_argument( + "--overwrite", + action="store_true", + help="Overwrite existing files (default: skip conflicts)" + ) + claw_migrate.add_argument( + "--migrate-secrets", + action="store_true", + help="Include allowlisted secrets (TELEGRAM_BOT_TOKEN, API keys, etc.)" + ) + claw_migrate.add_argument( + "--workspace-target", + help="Absolute path to copy workspace instructions into" + ) + claw_migrate.add_argument( + "--skill-conflict", + choices=["skip", "overwrite", "rename"], + default="skip", + help="How to handle skill name conflicts (default: skip)" + ) + claw_migrate.add_argument( + "--yes", "-y", + action="store_true", + help="Skip confirmation prompts" + ) + + # claw cleanup + claw_cleanup = claw_subparsers.add_parser( + "cleanup", + aliases=["clean"], + help="Archive leftover OpenClaw directories after migration", + description="Scan for and archive leftover OpenClaw directories to prevent state fragmentation" + ) + claw_cleanup.add_argument( + "--source", + help="Path to a specific OpenClaw directory to clean up" + ) + claw_cleanup.add_argument( + "--dry-run", + action="store_true", + help="Preview what would be archived without making changes" + ) + claw_cleanup.add_argument( + "--yes", "-y", + action="store_true", + help="Skip confirmation prompts" + ) + + def cmd_claw(args): + from hermes_cli.claw import claw_command + claw_command(args) + + claw_parser.set_defaults(func=cmd_claw) + + # ========================================================================= + # version command + # ========================================================================= + version_parser = subparsers.add_parser( + "version", + help="Show version information" + ) + version_parser.set_defaults(func=cmd_version) + + # ========================================================================= + # update command + # ========================================================================= + update_parser = subparsers.add_parser( + "update", + help="Update Hermes Agent to the latest version", + description="Pull the latest changes from git and reinstall dependencies" + ) + update_parser.add_argument( + "--gateway", action="store_true", default=False, + help="Gateway mode: use file-based IPC for prompts instead of stdin (used internally by /update)" + ) + update_parser.set_defaults(func=cmd_update) + + # ========================================================================= + # uninstall command + # ========================================================================= + uninstall_parser = subparsers.add_parser( + "uninstall", + help="Uninstall Hermes Agent", + description="Remove Hermes Agent from your system. Can keep configs/data for reinstall." + ) + uninstall_parser.add_argument( + "--full", + action="store_true", + help="Full uninstall - remove everything including configs and data" + ) + uninstall_parser.add_argument( + "--yes", "-y", + action="store_true", + help="Skip confirmation prompts" + ) + uninstall_parser.set_defaults(func=cmd_uninstall) + + # ========================================================================= + # acp command + # ========================================================================= + acp_parser = subparsers.add_parser( + "acp", + help="Run Hermes Agent as an ACP (Agent Client Protocol) server", + description="Start Hermes Agent in ACP mode for editor integration (VS Code, Zed, JetBrains)", + ) + + def cmd_acp(args): + """Launch Hermes Agent as an ACP server.""" + try: + from acp_adapter.entry import main as acp_main + acp_main() + except ImportError: + print("ACP dependencies not installed.") + print("Install them with: pip install -e '.[acp]'") + sys.exit(1) + + acp_parser.set_defaults(func=cmd_acp) + + # ========================================================================= + # profile command + # ========================================================================= + profile_parser = subparsers.add_parser( + "profile", + help="Manage profiles — multiple isolated Hermes instances", + ) + profile_subparsers = profile_parser.add_subparsers(dest="profile_action") + + profile_subparsers.add_parser("list", help="List all profiles") + profile_use = profile_subparsers.add_parser("use", help="Set sticky default profile") + profile_use.add_argument("profile_name", help="Profile name (or 'default')") + + profile_create = profile_subparsers.add_parser("create", help="Create a new profile") + profile_create.add_argument("profile_name", help="Profile name (lowercase, alphanumeric)") + profile_create.add_argument("--clone", action="store_true", + help="Copy config.yaml, .env, SOUL.md from active profile") + profile_create.add_argument("--clone-all", action="store_true", + help="Full copy of active profile (all state)") + profile_create.add_argument("--clone-from", metavar="SOURCE", + help="Source profile to clone from (default: active)") + profile_create.add_argument("--no-alias", action="store_true", + help="Skip wrapper script creation") + + profile_delete = profile_subparsers.add_parser("delete", help="Delete a profile") + profile_delete.add_argument("profile_name", help="Profile to delete") + profile_delete.add_argument("-y", "--yes", action="store_true", + help="Skip confirmation prompt") + + profile_show = profile_subparsers.add_parser("show", help="Show profile details") + profile_show.add_argument("profile_name", help="Profile to show") + + profile_alias = profile_subparsers.add_parser("alias", help="Manage wrapper scripts") + profile_alias.add_argument("profile_name", help="Profile name") + profile_alias.add_argument("--remove", action="store_true", + help="Remove the wrapper script") + profile_alias.add_argument("--name", dest="alias_name", metavar="NAME", + help="Custom alias name (default: profile name)") + + profile_rename = profile_subparsers.add_parser("rename", help="Rename a profile") + profile_rename.add_argument("old_name", help="Current profile name") + profile_rename.add_argument("new_name", help="New profile name") + + profile_export = profile_subparsers.add_parser("export", help="Export a profile to archive") + profile_export.add_argument("profile_name", help="Profile to export") + profile_export.add_argument("-o", "--output", default=None, + help="Output file (default: .tar.gz)") + + profile_import = profile_subparsers.add_parser("import", help="Import a profile from archive") + profile_import.add_argument("archive", help="Path to .tar.gz archive") + profile_import.add_argument("--name", dest="import_name", metavar="NAME", + help="Profile name (default: inferred from archive)") + + profile_parser.set_defaults(func=cmd_profile) + + # ========================================================================= + # completion command + # ========================================================================= + completion_parser = subparsers.add_parser( + "completion", + help="Print shell completion script (bash or zsh)", + ) + completion_parser.add_argument( + "shell", nargs="?", default="bash", choices=["bash", "zsh"], + help="Shell type (default: bash)", + ) + completion_parser.set_defaults(func=cmd_completion) + + # ========================================================================= + # dashboard command + # ========================================================================= + dashboard_parser = subparsers.add_parser( + "dashboard", + help="Start the web UI dashboard", + description="Launch the Hermes Agent web dashboard for managing config, API keys, and sessions", + ) + dashboard_parser.add_argument("--port", type=int, default=9119, help="Port (default 9119)") + dashboard_parser.add_argument("--host", default="127.0.0.1", help="Host (default 127.0.0.1)") + dashboard_parser.add_argument("--no-open", action="store_true", help="Don't open browser automatically") + dashboard_parser.set_defaults(func=cmd_dashboard) + + # ========================================================================= + # logs command + # ========================================================================= + logs_parser = subparsers.add_parser( + "logs", + help="View and filter Hermes log files", + description="View, tail, and filter agent.log / errors.log / gateway.log", + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog="""\ +Examples: + hermes logs Show last 50 lines of agent.log + hermes logs -f Follow agent.log in real time + hermes logs errors Show last 50 lines of errors.log + hermes logs gateway -n 100 Show last 100 lines of gateway.log + hermes logs --level WARNING Only show WARNING and above + hermes logs --session abc123 Filter by session ID + hermes logs --component tools Only show tool-related lines + hermes logs --since 1h Lines from the last hour + hermes logs --since 30m -f Follow, starting from 30 min ago + hermes logs list List available log files with sizes +""", + ) + logs_parser.add_argument( + "log_name", nargs="?", default="agent", + help="Log to view: agent (default), errors, gateway, or 'list' to show available files", + ) + logs_parser.add_argument( + "-n", "--lines", type=int, default=50, + help="Number of lines to show (default: 50)", + ) + logs_parser.add_argument( + "-f", "--follow", action="store_true", + help="Follow the log in real time (like tail -f)", + ) + logs_parser.add_argument( + "--level", metavar="LEVEL", + help="Minimum log level to show (DEBUG, INFO, WARNING, ERROR)", + ) + logs_parser.add_argument( + "--session", metavar="ID", + help="Filter lines containing this session ID substring", + ) + logs_parser.add_argument( + "--since", metavar="TIME", + help="Show lines since TIME ago (e.g. 1h, 30m, 2d)", + ) + logs_parser.add_argument( + "--component", metavar="NAME", + help="Filter by component: gateway, agent, tools, cli, cron", + ) + logs_parser.set_defaults(func=cmd_logs) + + # ========================================================================= + # Parse and execute + # ========================================================================= + # Pre-process argv so unquoted multi-word session names after -c / -r + # are merged into a single token before argparse sees them. + # e.g. ``hermes -c Pokemon Agent Dev`` → ``hermes -c 'Pokemon Agent Dev'`` + # ── Container-aware routing ──────────────────────────────────────── + # When NixOS container mode is active, route ALL subcommands into + # the managed container. This MUST run before parse_args() so that + # --help, unrecognised flags, and every subcommand are forwarded + # transparently instead of being intercepted by argparse on the host. + from hermes_cli.config import get_container_exec_info + container_info = get_container_exec_info() + if container_info: + _exec_in_container(container_info, sys.argv[1:]) + # Unreachable: os.execvp never returns on success (process is replaced) + # and raises OSError on failure (which propagates as a traceback). + sys.exit(1) + + _processed_argv = _coalesce_session_name_args(sys.argv[1:]) + args = parser.parse_args(_processed_argv) + + # Handle --version flag + if args.version: + cmd_version(args) + return + + # Handle top-level --resume / --continue as shortcut to chat + if (args.resume or args.continue_last) and args.command is None: + args.command = "chat" + args.query = None + args.model = None + args.provider = None + args.toolsets = None + args.verbose = False + if not hasattr(args, "worktree"): + args.worktree = False + cmd_chat(args) + return + + # Default to chat if no command specified + if args.command is None: + args.query = None + args.model = None + args.provider = None + args.toolsets = None + args.verbose = False + args.resume = None + args.continue_last = None + if not hasattr(args, "worktree"): + args.worktree = False + cmd_chat(args) + return + + # Execute the command + if hasattr(args, 'func'): + args.func(args) + else: + parser.print_help() + + +if __name__ == "__main__": + main() diff --git a/mindcli/_vendor/hermes_cli/mcp_config.py b/mindcli/_vendor/hermes_cli/mcp_config.py new file mode 100644 index 0000000..b21234c --- /dev/null +++ b/mindcli/_vendor/hermes_cli/mcp_config.py @@ -0,0 +1,716 @@ +""" +MCP Server Management CLI — ``hermes mcp`` subcommand. + +Implements ``hermes mcp add/remove/list/test/configure`` for interactive +MCP server lifecycle management (issue #690 Phase 2). + +Relies on tools/mcp_tool.py for connection/discovery and keeps +configuration in ~/.hermes/config.yaml under the ``mcp_servers`` key. +""" + +import asyncio +import logging +import os +import re +import time +from typing import Any, Dict, List, Optional, Tuple + +from hermes_cli.config import ( + load_config, + save_config, + get_env_value, + save_env_value, + get_hermes_home, # noqa: F401 — used by test mocks +) +from hermes_cli.colors import Colors, color +from hermes_constants import display_hermes_home + +logger = logging.getLogger(__name__) + +_ENV_VAR_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$") + + +_MCP_PRESETS: Dict[str, Dict[str, Any]] = {} + + +# ─── UI Helpers ─────────────────────────────────────────────────────────────── + +def _info(text: str): + print(color(f" {text}", Colors.DIM)) + +def _success(text: str): + print(color(f" ✓ {text}", Colors.GREEN)) + +def _warning(text: str): + print(color(f" ⚠ {text}", Colors.YELLOW)) + +def _error(text: str): + print(color(f" ✗ {text}", Colors.RED)) + + +def _confirm(question: str, default: bool = True) -> bool: + default_str = "Y/n" if default else "y/N" + try: + val = input(color(f" {question} [{default_str}]: ", Colors.YELLOW)).strip().lower() + except (KeyboardInterrupt, EOFError): + print() + return default + if not val: + return default + return val in ("y", "yes") + + +def _prompt(question: str, *, password: bool = False, default: str = "") -> str: + from hermes_cli.cli_output import prompt as _shared_prompt + return _shared_prompt(question, default=default, password=password) + + +# ─── Config Helpers ─────────────────────────────────────────────────────────── + +def _get_mcp_servers(config: Optional[dict] = None) -> Dict[str, dict]: + """Return the ``mcp_servers`` dict from config, or empty dict.""" + if config is None: + config = load_config() + servers = config.get("mcp_servers") + if not servers or not isinstance(servers, dict): + return {} + return servers + + +def _save_mcp_server(name: str, server_config: dict): + """Add or update a server entry in config.yaml.""" + config = load_config() + config.setdefault("mcp_servers", {})[name] = server_config + save_config(config) + + +def _remove_mcp_server(name: str) -> bool: + """Remove a server from config.yaml. Returns True if it existed.""" + config = load_config() + servers = config.get("mcp_servers", {}) + if name not in servers: + return False + del servers[name] + if not servers: + config.pop("mcp_servers", None) + save_config(config) + return True + + +def _env_key_for_server(name: str) -> str: + """Convert server name to an env-var key like ``MCP_MYSERVER_API_KEY``.""" + return f"MCP_{name.upper().replace('-', '_')}_API_KEY" + + +def _parse_env_assignments(raw_env: Optional[List[str]]) -> Dict[str, str]: + """Parse ``KEY=VALUE`` strings from CLI args into an env dict.""" + parsed: Dict[str, str] = {} + for item in raw_env or []: + text = str(item or "").strip() + if not text: + continue + if "=" not in text: + raise ValueError(f"Invalid --env value '{text}' (expected KEY=VALUE)") + key, value = text.split("=", 1) + key = key.strip() + if not key: + raise ValueError(f"Invalid --env value '{text}' (missing variable name)") + if not _ENV_VAR_NAME_RE.match(key): + raise ValueError(f"Invalid --env variable name '{key}'") + parsed[key] = value + return parsed + + +def _apply_mcp_preset( + name: str, + *, + preset_name: Optional[str], + url: Optional[str], + command: Optional[str], + cmd_args: List[str], + server_config: Dict[str, Any], +) -> tuple[Optional[str], Optional[str], List[str], bool]: + """Apply a known MCP preset when transport details were omitted.""" + if not preset_name: + return url, command, cmd_args, False + + preset = _MCP_PRESETS.get(preset_name) + if not preset: + raise ValueError(f"Unknown MCP preset: {preset_name}") + + if url or command: + return url, command, cmd_args, False + + url = preset.get("url") + command = preset.get("command") + cmd_args = list(preset.get("args") or []) + + if url: + server_config["url"] = url + if command: + server_config["command"] = command + if cmd_args: + server_config["args"] = cmd_args + + return url, command, cmd_args, True + + +# ─── Discovery (temporary connect) ─────────────────────────────────────────── + +def _probe_single_server( + name: str, config: dict, connect_timeout: float = 30 +) -> List[Tuple[str, str]]: + """Temporarily connect to one MCP server, list its tools, disconnect. + + Returns list of ``(tool_name, description)`` tuples. + Raises on connection failure. + """ + from tools.mcp_tool import ( + _ensure_mcp_loop, + _run_on_mcp_loop, + _connect_server, + _stop_mcp_loop, + ) + + _ensure_mcp_loop() + + tools_found: List[Tuple[str, str]] = [] + + async def _probe(): + server = await asyncio.wait_for( + _connect_server(name, config), timeout=connect_timeout + ) + for t in server._tools: + desc = getattr(t, "description", "") or "" + # Truncate long descriptions for display + if len(desc) > 80: + desc = desc[:77] + "..." + tools_found.append((t.name, desc)) + await server.shutdown() + + try: + _run_on_mcp_loop(_probe(), timeout=connect_timeout + 10) + except BaseException as exc: + raise _unwrap_exception_group(exc) from None + finally: + _stop_mcp_loop() + + return tools_found + + +def _unwrap_exception_group(exc: BaseException) -> Exception: + """Extract the root-cause exception from anyio TaskGroup wrappers. + + The MCP SDK uses anyio task groups, which wrap errors in + ``BaseExceptionGroup`` / ``ExceptionGroup``. This makes error + messages opaque ("unhandled errors in a TaskGroup"). We unwrap + to surface the real cause (e.g. "401 Unauthorized"). + """ + while isinstance(exc, BaseExceptionGroup) and exc.exceptions: + exc = exc.exceptions[0] + # Return a plain Exception so callers can catch normally + if isinstance(exc, Exception): + return exc + return RuntimeError(str(exc)) + + +# ─── hermes mcp add ────────────────────────────────────────────────────────── + +def cmd_mcp_add(args): + """Add a new MCP server with discovery-first tool selection.""" + name = args.name + url = getattr(args, "url", None) + command = getattr(args, "command", None) + cmd_args = getattr(args, "args", None) or [] + auth_type = getattr(args, "auth", None) + preset_name = getattr(args, "preset", None) + raw_env = getattr(args, "env", None) + + server_config: Dict[str, Any] = {} + try: + explicit_env = _parse_env_assignments(raw_env) + url, command, cmd_args, _preset_applied = _apply_mcp_preset( + name, + preset_name=preset_name, + url=url, + command=command, + cmd_args=list(cmd_args), + server_config=server_config, + ) + except ValueError as exc: + _error(str(exc)) + return + + if url and explicit_env: + _error("--env is only supported for stdio MCP servers (--command or stdio presets)") + return + + # Validate transport + if not url and not command: + _error("Must specify --url , --command , or --preset ") + _info("Examples:") + _info(' hermes mcp add ink --url "https://mcp.ml.ink/mcp"') + _info(' hermes mcp add github --command npx --args @modelcontextprotocol/server-github') + _info(' hermes mcp add myserver --preset mypreset') + return + + # Check if server already exists + existing = _get_mcp_servers() + if name in existing: + if not _confirm(f"Server '{name}' already exists. Overwrite?", default=False): + _info("Cancelled.") + return + + # Build initial config + if url: + server_config["url"] = url + else: + server_config["command"] = command + if cmd_args: + server_config["args"] = cmd_args + if explicit_env: + server_config["env"] = explicit_env + + + # ── Authentication ──────────────────────────────────────────────── + + if url and auth_type == "oauth": + print() + _info(f"Starting OAuth flow for '{name}'...") + oauth_ok = False + try: + from tools.mcp_oauth import build_oauth_auth + oauth_auth = build_oauth_auth(name, url) + if oauth_auth: + server_config["auth"] = "oauth" + _success("OAuth configured (tokens will be acquired on first connection)") + oauth_ok=True + else: + _warning("OAuth setup failed — MCP SDK auth module not available") + except Exception as exc: + _warning(f"OAuth error: {exc}") + + if not oauth_ok: + _info("This server may not support OAuth.") + if _confirm("Continue without authentication?", default=True): + # Don't store auth: oauth — server doesn't support it + pass + else: + _info("Cancelled.") + return + + elif url: + # Prompt for API key / Bearer token for HTTP servers + print() + _info(f"Connecting to {url}") + needs_auth = _confirm("Does this server require authentication?", default=True) + if needs_auth: + if auth_type == "header" or not auth_type: + env_key = _env_key_for_server(name) + existing_key = get_env_value(env_key) + if existing_key: + _success(f"{env_key}: already configured") + api_key = existing_key + else: + api_key = _prompt("API key / Bearer token", password=True) + if api_key: + save_env_value(env_key, api_key) + _success(f"Saved to {display_hermes_home()}/.env as {env_key}") + + # Set header with env var interpolation + if api_key or existing_key: + server_config["headers"] = { + "Authorization": f"Bearer ${{{env_key}}}" + } + + # ── Discovery: connect and list tools ───────────────────────────── + + print() + print(color(f" Connecting to '{name}'...", Colors.CYAN)) + + try: + tools = _probe_single_server(name, server_config) + except Exception as exc: + _error(f"Failed to connect: {exc}") + if _confirm("Save config anyway (you can test later)?", default=False): + server_config["enabled"] = False + _save_mcp_server(name, server_config) + _success(f"Saved '{name}' to config (disabled)") + _info("Fix the issue, then: hermes mcp test " + name) + return + + if not tools: + _warning("Server connected but reported no tools.") + if _confirm("Save config anyway?", default=True): + _save_mcp_server(name, server_config) + _success(f"Saved '{name}' to config") + return + + # ── Tool selection ──────────────────────────────────────────────── + + print() + _success(f"Connected! Found {len(tools)} tool(s) from '{name}':") + print() + for tool_name, desc in tools: + short = desc[:60] + "..." if len(desc) > 60 else desc + print(f" {color(tool_name, Colors.GREEN):40s} {short}") + print() + + # Ask: enable all, select, or cancel + try: + choice = input( + color(f" Enable all {len(tools)} tools? [Y/n/select]: ", Colors.YELLOW) + ).strip().lower() + except (KeyboardInterrupt, EOFError): + print() + _info("Cancelled.") + return + + if choice in ("n", "no"): + _info("Cancelled — server not saved.") + return + + if choice in ("s", "select"): + # Interactive tool selection + from hermes_cli.curses_ui import curses_checklist + + labels = [f"{t[0]} — {t[1]}" for t in tools] + pre_selected = set(range(len(tools))) + + chosen = curses_checklist( + f"Select tools for '{name}'", + labels, + pre_selected, + ) + + if not chosen: + _info("No tools selected — server not saved.") + return + + chosen_names = [tools[i][0] for i in sorted(chosen)] + server_config.setdefault("tools", {})["include"] = chosen_names + + tool_count = len(chosen_names) + total = len(tools) + else: + # Enable all (no filter needed — default behaviour) + tool_count = len(tools) + total = len(tools) + + # ── Save ────────────────────────────────────────────────────────── + + server_config["enabled"] = True + _save_mcp_server(name, server_config) + + print() + _success(f"Saved '{name}' to {display_hermes_home()}/config.yaml ({tool_count}/{total} tools enabled)") + _info("Start a new session to use these tools.") + + +# ─── hermes mcp remove ─────────────────────────────────────────────────────── + +def cmd_mcp_remove(args): + """Remove an MCP server from config.""" + name = args.name + existing = _get_mcp_servers() + + if name not in existing: + _error(f"Server '{name}' not found in config.") + servers = list(existing.keys()) + if servers: + _info(f"Available servers: {', '.join(servers)}") + return + + if not _confirm(f"Remove server '{name}'?", default=True): + _info("Cancelled.") + return + + _remove_mcp_server(name) + _success(f"Removed '{name}' from config") + + # Clean up OAuth tokens if they exist + try: + from tools.mcp_oauth import remove_oauth_tokens + remove_oauth_tokens(name) + _success("Cleaned up OAuth tokens") + except Exception: + pass + + +# ─── hermes mcp list ────────────────────────────────────────────────────────── + +def cmd_mcp_list(args=None): + """List all configured MCP servers.""" + servers = _get_mcp_servers() + + if not servers: + print() + _info("No MCP servers configured.") + print() + _info("Add one with:") + _info(' hermes mcp add --url ') + _info(' hermes mcp add --command --args ') + print() + return + + print() + print(color(" MCP Servers:", Colors.CYAN + Colors.BOLD)) + print() + + # Table header + print(f" {'Name':<16} {'Transport':<30} {'Tools':<12} {'Status':<10}") + print(f" {'─' * 16} {'─' * 30} {'─' * 12} {'─' * 10}") + + for name, cfg in servers.items(): + # Transport info + if "url" in cfg: + url = cfg["url"] + # Truncate long URLs + if len(url) > 28: + url = url[:25] + "..." + transport = url + elif "command" in cfg: + cmd = cfg["command"] + cmd_args = cfg.get("args", []) + if isinstance(cmd_args, list) and cmd_args: + transport = f"{cmd} {' '.join(str(a) for a in cmd_args[:2])}" + else: + transport = cmd + if len(transport) > 28: + transport = transport[:25] + "..." + else: + transport = "?" + + # Tool count + tools_cfg = cfg.get("tools", {}) + if isinstance(tools_cfg, dict): + include = tools_cfg.get("include") + exclude = tools_cfg.get("exclude") + if include and isinstance(include, list): + tools_str = f"{len(include)} selected" + elif exclude and isinstance(exclude, list): + tools_str = f"-{len(exclude)} excluded" + else: + tools_str = "all" + else: + tools_str = "all" + + # Enabled status + enabled = cfg.get("enabled", True) + if isinstance(enabled, str): + enabled = enabled.lower() in ("true", "1", "yes") + status = color("✓ enabled", Colors.GREEN) if enabled else color("✗ disabled", Colors.DIM) + + print(f" {name:<16} {transport:<30} {tools_str:<12} {status}") + + print() + + +# ─── hermes mcp test ────────────────────────────────────────────────────────── + +def cmd_mcp_test(args): + """Test connection to an MCP server.""" + name = args.name + servers = _get_mcp_servers() + + if name not in servers: + _error(f"Server '{name}' not found in config.") + available = list(servers.keys()) + if available: + _info(f"Available: {', '.join(available)}") + return + + cfg = servers[name] + print() + print(color(f" Testing '{name}'...", Colors.CYAN)) + + # Show transport info + if "url" in cfg: + _info(f"Transport: HTTP → {cfg['url']}") + else: + cmd = cfg.get("command", "?") + _info(f"Transport: stdio → {cmd}") + + # Show auth info (masked) + auth_type = cfg.get("auth", "") + headers = cfg.get("headers", {}) + if auth_type == "oauth": + _info("Auth: OAuth 2.1 PKCE") + elif headers: + for k, v in headers.items(): + if isinstance(v, str) and ("key" in k.lower() or "auth" in k.lower()): + # Mask the value + resolved = _interpolate_value(v) + if len(resolved) > 8: + masked = resolved[:4] + "***" + resolved[-4:] + else: + masked = "***" + print(f" {k}: {masked}") + else: + _info("Auth: none") + + # Attempt connection + start = time.monotonic() + try: + tools = _probe_single_server(name, cfg) + elapsed_ms = (time.monotonic() - start) * 1000 + except Exception as exc: + elapsed_ms = (time.monotonic() - start) * 1000 + _error(f"Connection failed ({elapsed_ms:.0f}ms): {exc}") + return + + _success(f"Connected ({elapsed_ms:.0f}ms)") + _success(f"Tools discovered: {len(tools)}") + + if tools: + print() + for tool_name, desc in tools: + short = desc[:55] + "..." if len(desc) > 55 else desc + print(f" {color(tool_name, Colors.GREEN):36s} {short}") + print() + + +def _interpolate_value(value: str) -> str: + """Resolve ``${ENV_VAR}`` references in a string.""" + def _replace(m): + return os.getenv(m.group(1), "") + return re.sub(r"\$\{(\w+)\}", _replace, value) + + +# ─── hermes mcp configure ──────────────────────────────────────────────────── + +def cmd_mcp_configure(args): + """Reconfigure which tools are enabled for an existing MCP server.""" + import sys as _sys + if not _sys.stdin.isatty(): + print("Error: 'hermes mcp configure' requires an interactive terminal.", file=_sys.stderr) + _sys.exit(1) + name = args.name + servers = _get_mcp_servers() + + if name not in servers: + _error(f"Server '{name}' not found in config.") + available = list(servers.keys()) + if available: + _info(f"Available: {', '.join(available)}") + return + + cfg = servers[name] + + # Discover all available tools + print() + print(color(f" Connecting to '{name}' to discover tools...", Colors.CYAN)) + + try: + all_tools = _probe_single_server(name, cfg) + except Exception as exc: + _error(f"Failed to connect: {exc}") + return + + if not all_tools: + _warning("Server reports no tools.") + return + + # Determine which are currently enabled + tools_cfg = cfg.get("tools", {}) + if isinstance(tools_cfg, dict): + include = tools_cfg.get("include") + exclude = tools_cfg.get("exclude") + else: + include = None + exclude = None + + tool_names = [t[0] for t in all_tools] + + if include and isinstance(include, list): + include_set = set(include) + pre_selected = { + i for i, tn in enumerate(tool_names) if tn in include_set + } + elif exclude and isinstance(exclude, list): + exclude_set = set(exclude) + pre_selected = { + i for i, tn in enumerate(tool_names) if tn not in exclude_set + } + else: + pre_selected = set(range(len(all_tools))) + + currently = len(pre_selected) + total = len(all_tools) + _info(f"Currently {currently}/{total} tools enabled for '{name}'.") + print() + + # Interactive checklist + from hermes_cli.curses_ui import curses_checklist + + labels = [f"{t[0]} — {t[1]}" for t in all_tools] + + chosen = curses_checklist( + f"Select tools for '{name}'", + labels, + pre_selected, + ) + + if chosen == pre_selected: + _info("No changes made.") + return + + # Update config + config = load_config() + server_entry = config.get("mcp_servers", {}).get(name, {}) + + if len(chosen) == total: + # All selected → remove include/exclude (register all) + server_entry.pop("tools", None) + else: + chosen_names = [tool_names[i] for i in sorted(chosen)] + server_entry.setdefault("tools", {}) + server_entry["tools"]["include"] = chosen_names + server_entry["tools"].pop("exclude", None) + + config.setdefault("mcp_servers", {})[name] = server_entry + save_config(config) + + new_count = len(chosen) + _success(f"Updated config: {new_count}/{total} tools enabled") + _info("Start a new session for changes to take effect.") + + +# ─── Dispatcher ─────────────────────────────────────────────────────────────── + +def mcp_command(args): + """Main dispatcher for ``hermes mcp`` subcommands.""" + action = getattr(args, "mcp_action", None) + + if action == "serve": + from mcp_serve import run_mcp_server + run_mcp_server(verbose=getattr(args, "verbose", False)) + return + + handlers = { + "add": cmd_mcp_add, + "remove": cmd_mcp_remove, + "rm": cmd_mcp_remove, + "list": cmd_mcp_list, + "ls": cmd_mcp_list, + "test": cmd_mcp_test, + "configure": cmd_mcp_configure, + "config": cmd_mcp_configure, + } + + handler = handlers.get(action) + if handler: + handler(args) + else: + # No subcommand — show list + cmd_mcp_list() + print(color(" Commands:", Colors.CYAN)) + _info("hermes mcp serve Run as MCP server") + _info("hermes mcp add --url Add an MCP server") + _info("hermes mcp add --command Add a stdio server") + _info("hermes mcp add --preset Add from a known preset") + _info("hermes mcp remove Remove a server") + _info("hermes mcp list List servers") + _info("hermes mcp test Test connection") + _info("hermes mcp configure Toggle tools") + print() diff --git a/mindcli/_vendor/hermes_cli/memory_setup.py b/mindcli/_vendor/hermes_cli/memory_setup.py new file mode 100644 index 0000000..1aa4313 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/memory_setup.py @@ -0,0 +1,451 @@ +"""hermes memory setup|status — configure memory provider plugins. + +Auto-detects installed memory providers via the plugin system. +Interactive curses-based UI for provider selection, then walks through +the provider's config schema. Writes config to config.yaml + .env. +""" + +from __future__ import annotations + +import getpass +import os +import sys +from pathlib import Path + +from hermes_constants import get_hermes_home + + +# --------------------------------------------------------------------------- +# Curses-based interactive picker (same pattern as hermes tools) +# --------------------------------------------------------------------------- + +def _curses_select(title: str, items: list[tuple[str, str]], default: int = 0) -> int: + """Interactive single-select with arrow keys. + + items: list of (label, description) tuples. + Returns selected index, or default on escape/quit. + """ + from hermes_cli.curses_ui import curses_radiolist + # Format (label, desc) tuples into display strings + display_items = [ + f"{label} {desc}" if desc else label + for label, desc in items + ] + return curses_radiolist(title, display_items, selected=default, cancel_returns=default) + + +def _prompt(label: str, default: str | None = None, secret: bool = False) -> str: + """Prompt for a value with optional default and secret masking.""" + suffix = f" [{default}]" if default else "" + if secret: + sys.stdout.write(f" {label}{suffix}: ") + sys.stdout.flush() + if sys.stdin.isatty(): + val = getpass.getpass(prompt="") + else: + val = sys.stdin.readline().strip() + else: + sys.stdout.write(f" {label}{suffix}: ") + sys.stdout.flush() + val = sys.stdin.readline().strip() + return val or (default or "") + + +# --------------------------------------------------------------------------- +# Provider discovery +# --------------------------------------------------------------------------- + +def _install_dependencies(provider_name: str) -> None: + """Install pip dependencies declared in plugin.yaml.""" + import subprocess + from pathlib import Path as _Path + + plugin_dir = _Path(__file__).parent.parent / "plugins" / "memory" / provider_name + yaml_path = plugin_dir / "plugin.yaml" + if not yaml_path.exists(): + return + + try: + import yaml + with open(yaml_path) as f: + meta = yaml.safe_load(f) or {} + except Exception: + return + + pip_deps = meta.get("pip_dependencies", []) + if not pip_deps: + return + + # pip name → import name mapping for packages where they differ + _IMPORT_NAMES = { + "honcho-ai": "honcho", + "mem0ai": "mem0", + "hindsight-client": "hindsight_client", + "hindsight-all": "hindsight", + } + + # Check which packages are missing + missing = [] + for dep in pip_deps: + import_name = _IMPORT_NAMES.get(dep, dep.replace("-", "_").split("[")[0]) + try: + __import__(import_name) + except ImportError: + missing.append(dep) + + if not missing: + return + + print(f"\n Installing dependencies: {', '.join(missing)}") + + import shutil + uv_path = shutil.which("uv") + if not uv_path: + print(f" ⚠ uv not found — cannot install dependencies") + print(f" Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh") + print(f" Then re-run: hermes memory setup") + return + + try: + subprocess.run( + [uv_path, "pip", "install", "--python", sys.executable, "--quiet"] + missing, + check=True, timeout=120, + capture_output=True, + ) + print(f" ✓ Installed {', '.join(missing)}") + except subprocess.CalledProcessError as e: + print(f" ⚠ Failed to install {', '.join(missing)}") + stderr = (e.stderr or b"").decode()[:200] + if stderr: + print(f" {stderr}") + print(f" Run manually: uv pip install --python {sys.executable} {' '.join(missing)}") + except Exception as e: + print(f" ⚠ Install failed: {e}") + print(f" Run manually: uv pip install --python {sys.executable} {' '.join(missing)}") + + # Also show external dependencies (non-pip) if any + ext_deps = meta.get("external_dependencies", []) + for dep in ext_deps: + dep_name = dep.get("name", "") + check_cmd = dep.get("check", "") + install_cmd = dep.get("install", "") + if check_cmd: + try: + subprocess.run( + check_cmd, shell=True, capture_output=True, timeout=5 + ) + except Exception: + if install_cmd: + print(f"\n ⚠ '{dep_name}' not found. Install with:") + print(f" {install_cmd}") + + +def _get_available_providers() -> list: + """Discover memory providers from plugins/memory/. + + Returns list of (name, description, provider_instance) tuples. + """ + try: + from plugins.memory import discover_memory_providers, load_memory_provider + raw = discover_memory_providers() + except Exception: + raw = [] + + results = [] + for name, desc, available in raw: + try: + provider = load_memory_provider(name) + if not provider: + continue + except Exception: + continue + + schema = provider.get_config_schema() if hasattr(provider, "get_config_schema") else [] + has_secrets = any(f.get("secret") for f in schema) + has_non_secrets = any(not f.get("secret") for f in schema) + if has_secrets and has_non_secrets: + setup_hint = "API key / local" + elif has_secrets: + setup_hint = "requires API key" + elif not schema: + setup_hint = "no setup needed" + else: + setup_hint = "local" + + results.append((name, setup_hint, provider)) + return results + + +# --------------------------------------------------------------------------- +# Setup wizard +# --------------------------------------------------------------------------- + +def cmd_setup_provider(provider_name: str) -> None: + """Run memory setup for a specific provider, skipping the picker.""" + from hermes_cli.config import load_config, save_config + + providers = _get_available_providers() + match = None + for name, desc, provider in providers: + if name == provider_name: + match = (name, desc, provider) + break + + if not match: + print(f"\n Memory provider '{provider_name}' not found.") + print(" Run 'hermes memory setup' to see available providers.\n") + return + + name, _, provider = match + + _install_dependencies(name) + + config = load_config() + if not isinstance(config.get("memory"), dict): + config["memory"] = {} + + if hasattr(provider, "post_setup"): + hermes_home = str(get_hermes_home()) + provider.post_setup(hermes_home, config) + return + + # Fallback: generic schema-based setup (same as cmd_setup) + config["memory"]["provider"] = name + save_config(config) + print(f"\n Memory provider: {name}") + print(f" Activation saved to config.yaml\n") + + +def cmd_setup(args) -> None: + """Interactive memory provider setup wizard.""" + from hermes_cli.config import load_config, save_config + + providers = _get_available_providers() + + if not providers: + print("\n No memory provider plugins detected.") + print(" Install a plugin to ~/.hermes/plugins/ and try again.\n") + return + + # Build picker items + items = [] + for name, desc, _ in providers: + items.append((name, f"— {desc}")) + items.append(("Built-in only", "— MEMORY.md / USER.md (default)")) + + builtin_idx = len(items) - 1 + selected = _curses_select("Memory provider setup", items, default=builtin_idx) + + config = load_config() + if not isinstance(config.get("memory"), dict): + config["memory"] = {} + + # Built-in only + if selected >= len(providers) or selected < 0: + config["memory"]["provider"] = "" + save_config(config) + print("\n ✓ Memory provider: built-in only") + print(" Saved to config.yaml\n") + return + + name, _, provider = providers[selected] + + # Install pip dependencies if declared in plugin.yaml + _install_dependencies(name) + + # If the provider has a post_setup hook, delegate entirely to it. + # The hook handles its own config, connection test, and activation. + if hasattr(provider, "post_setup"): + hermes_home = str(get_hermes_home()) + provider.post_setup(hermes_home, config) + return + + schema = provider.get_config_schema() if hasattr(provider, "get_config_schema") else [] + + provider_config = config["memory"].get(name, {}) + if not isinstance(provider_config, dict): + provider_config = {} + + env_path = get_hermes_home() / ".env" + env_writes = {} + + if schema: + print(f"\n Configuring {name}:\n") + + for field in schema: + key = field["key"] + desc = field.get("description", key) + default = field.get("default") + # Dynamic default: look up default from another field's value + default_from = field.get("default_from") + if default_from and isinstance(default_from, dict): + ref_field = default_from.get("field", "") + ref_map = default_from.get("map", {}) + ref_value = provider_config.get(ref_field, "") + if ref_value and ref_value in ref_map: + default = ref_map[ref_value] + is_secret = field.get("secret", False) + choices = field.get("choices") + env_var = field.get("env_var") + url = field.get("url") + + # Skip fields whose "when" condition doesn't match + when = field.get("when") + if when and isinstance(when, dict): + if not all(provider_config.get(k) == v for k, v in when.items()): + continue + + if choices and not is_secret: + # Use curses picker for choice fields + choice_items = [(c, "") for c in choices] + current = provider_config.get(key, default) + current_idx = 0 + if current and current in choices: + current_idx = choices.index(current) + sel = _curses_select(f" {desc}", choice_items, default=current_idx) + provider_config[key] = choices[sel] + elif is_secret: + # Prompt for secret + existing = os.environ.get(env_var, "") if env_var else "" + if existing: + masked = f"...{existing[-4:]}" if len(existing) > 4 else "set" + val = _prompt(f"{desc} (current: {masked}, blank to keep)", secret=True) + else: + hint = f" Get yours at {url}" if url else "" + if hint: + print(hint) + val = _prompt(desc, secret=True) + if val and env_var: + env_writes[env_var] = val + else: + # Regular text prompt + current = provider_config.get(key) + effective_default = current or default + val = _prompt(desc, default=str(effective_default) if effective_default else None) + if val: + provider_config[key] = val + + # Write activation key to config.yaml + config["memory"]["provider"] = name + save_config(config) + + # Write non-secret config to provider's native location + hermes_home = str(get_hermes_home()) + if provider_config and hasattr(provider, "save_config"): + try: + provider.save_config(provider_config, hermes_home) + except Exception as e: + print(f" Failed to write provider config: {e}") + + # Write secrets to .env + if env_writes: + _write_env_vars(env_path, env_writes) + + print(f"\n Memory provider: {name}") + print(f" Activation saved to config.yaml") + if provider_config: + print(f" Provider config saved") + if env_writes: + print(f" API keys saved to .env") + print(f"\n Start a new session to activate.\n") + + +def _write_env_vars(env_path: Path, env_writes: dict) -> None: + """Append or update env vars in .env file.""" + env_path.parent.mkdir(parents=True, exist_ok=True) + + existing_lines = [] + if env_path.exists(): + existing_lines = env_path.read_text().splitlines() + + updated_keys = set() + new_lines = [] + for line in existing_lines: + key_match = line.split("=", 1)[0].strip() if "=" in line else "" + if key_match in env_writes: + new_lines.append(f"{key_match}={env_writes[key_match]}") + updated_keys.add(key_match) + else: + new_lines.append(line) + + for key, val in env_writes.items(): + if key not in updated_keys: + new_lines.append(f"{key}={val}") + + env_path.write_text("\n".join(new_lines) + "\n") + + +# --------------------------------------------------------------------------- +# Status +# --------------------------------------------------------------------------- + +def cmd_status(args) -> None: + """Show current memory provider config.""" + from hermes_cli.config import load_config + + config = load_config() + mem_config = config.get("memory", {}) + provider_name = mem_config.get("provider", "") + + print(f"\nMemory status\n" + "─" * 40) + print(f" Built-in: always active") + print(f" Provider: {provider_name or '(none — built-in only)'}") + + if provider_name: + provider_config = mem_config.get(provider_name, {}) + if provider_config: + print(f"\n {provider_name} config:") + for key, val in provider_config.items(): + print(f" {key}: {val}") + + providers = _get_available_providers() + found = any(name == provider_name for name, _, _ in providers) + if found: + print(f"\n Plugin: installed ✓") + for pname, _, p in providers: + if pname == provider_name: + if p.is_available(): + print(f" Status: available ✓") + else: + print(f" Status: not available ✗") + schema = p.get_config_schema() if hasattr(p, "get_config_schema") else [] + secrets = [f for f in schema if f.get("secret")] + if secrets: + print(f" Missing:") + for s in secrets: + env_var = s.get("env_var", "") + url = s.get("url", "") + is_set = bool(os.environ.get(env_var)) + mark = "✓" if is_set else "✗" + line = f" {mark} {env_var}" + if url and not is_set: + line += f" → {url}" + print(line) + break + else: + print(f"\n Plugin: NOT installed ✗") + print(f" Install the '{provider_name}' memory plugin to ~/.hermes/plugins/") + + providers = _get_available_providers() + if providers: + print(f"\n Installed plugins:") + for pname, desc, _ in providers: + active = " ← active" if pname == provider_name else "" + print(f" • {pname} ({desc}){active}") + + print() + + +# --------------------------------------------------------------------------- +# Router +# --------------------------------------------------------------------------- + +def memory_command(args) -> None: + """Route memory subcommands.""" + sub = getattr(args, "memory_command", None) + if sub == "setup": + cmd_setup(args) + elif sub == "status": + cmd_status(args) + else: + cmd_status(args) diff --git a/mindcli/_vendor/hermes_cli/model_normalize.py b/mindcli/_vendor/hermes_cli/model_normalize.py new file mode 100644 index 0000000..40afe00 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/model_normalize.py @@ -0,0 +1,406 @@ +"""Per-provider model name normalization. + +Different LLM providers expect model identifiers in different formats: + +- **Aggregators** (OpenRouter, Nous, AI Gateway, Kilo Code) need + ``vendor/model`` slugs like ``anthropic/claude-sonnet-4.6``. +- **Anthropic** native API expects bare names with dots replaced by + hyphens: ``claude-sonnet-4-6``. +- **Copilot** expects bare names *with* dots preserved: + ``claude-sonnet-4.6``. +- **OpenCode Zen** preserves dots for GPT/GLM/Gemini/Kimi/MiniMax-style + model IDs, but Claude still uses hyphenated native names like + ``claude-sonnet-4-6``. +- **OpenCode Go** preserves dots in model names: ``minimax-m2.7``. +- **DeepSeek** only accepts two model identifiers: + ``deepseek-chat`` and ``deepseek-reasoner``. +- **Custom** and remaining providers pass the name through as-is. + +This module centralises that translation so callers can simply write:: + + api_model = normalize_model_for_provider(user_input, provider) + +Inspired by Clawdbot's ``normalizeAnthropicModelId`` pattern. +""" + +from __future__ import annotations + +from typing import Optional + +# --------------------------------------------------------------------------- +# Vendor prefix mapping +# --------------------------------------------------------------------------- +# Maps the first hyphen-delimited token of a bare model name to the vendor +# slug used by aggregator APIs (OpenRouter, Nous, etc.). +# +# Example: "claude-sonnet-4.6" -> first token "claude" -> vendor "anthropic" +# -> aggregator slug: "anthropic/claude-sonnet-4.6" + +_VENDOR_PREFIXES: dict[str, str] = { + "claude": "anthropic", + "gpt": "openai", + "o1": "openai", + "o3": "openai", + "o4": "openai", + "gemini": "google", + "gemma": "google", + "deepseek": "deepseek", + "glm": "z-ai", + "kimi": "moonshotai", + "minimax": "minimax", + "grok": "x-ai", + "qwen": "qwen", + "mimo": "xiaomi", + "trinity": "arcee-ai", + "nemotron": "nvidia", + "llama": "meta-llama", + "step": "stepfun", + "trinity": "arcee-ai", +} + +# Providers whose APIs consume vendor/model slugs. +_AGGREGATOR_PROVIDERS: frozenset[str] = frozenset({ + "openrouter", + "nous", + "ai-gateway", + "kilocode", +}) + +# Providers that want bare names with dots replaced by hyphens. +_DOT_TO_HYPHEN_PROVIDERS: frozenset[str] = frozenset({ + "anthropic", +}) + +# Providers that want bare names with dots preserved. +_STRIP_VENDOR_ONLY_PROVIDERS: frozenset[str] = frozenset({ + "copilot", + "copilot-acp", + "openai-codex", +}) + +# Providers whose native naming is authoritative -- pass through unchanged. +_AUTHORITATIVE_NATIVE_PROVIDERS: frozenset[str] = frozenset({ + "gemini", + "huggingface", +}) + +# Direct providers that accept bare native names but should repair a matching +# provider/ prefix when users copy the aggregator form into config.yaml. +_MATCHING_PREFIX_STRIP_PROVIDERS: frozenset[str] = frozenset({ + "zai", + "kimi-coding", + "kimi-coding-cn", + "minimax", + "minimax-cn", + "alibaba", + "qwen-oauth", + "xiaomi", + "arcee", + "custom", +}) + +# --------------------------------------------------------------------------- +# DeepSeek special handling +# --------------------------------------------------------------------------- +# DeepSeek's API only recognises exactly two model identifiers. We map +# common aliases and patterns to the canonical names. + +_DEEPSEEK_REASONER_KEYWORDS: frozenset[str] = frozenset({ + "reasoner", + "r1", + "think", + "reasoning", + "cot", +}) + +_DEEPSEEK_CANONICAL_MODELS: frozenset[str] = frozenset({ + "deepseek-chat", + "deepseek-reasoner", +}) + + +def _normalize_for_deepseek(model_name: str) -> str: + """Map any model input to one of DeepSeek's two accepted identifiers. + + Rules: + - Already ``deepseek-chat`` or ``deepseek-reasoner`` -> pass through. + - Contains any reasoner keyword (r1, think, reasoning, cot, reasoner) + -> ``deepseek-reasoner``. + - Everything else -> ``deepseek-chat``. + + Args: + model_name: The bare model name (vendor prefix already stripped). + + Returns: + One of ``"deepseek-chat"`` or ``"deepseek-reasoner"``. + """ + bare = _strip_vendor_prefix(model_name).lower() + + if bare in _DEEPSEEK_CANONICAL_MODELS: + return bare + + # Check for reasoner-like keywords anywhere in the name + for keyword in _DEEPSEEK_REASONER_KEYWORDS: + if keyword in bare: + return "deepseek-reasoner" + + return "deepseek-chat" + + +# --------------------------------------------------------------------------- +# Helper utilities +# --------------------------------------------------------------------------- + +def _strip_vendor_prefix(model_name: str) -> str: + """Remove a ``vendor/`` prefix if present. + + Examples:: + + >>> _strip_vendor_prefix("anthropic/claude-sonnet-4.6") + 'claude-sonnet-4.6' + >>> _strip_vendor_prefix("claude-sonnet-4.6") + 'claude-sonnet-4.6' + >>> _strip_vendor_prefix("meta-llama/llama-4-scout") + 'llama-4-scout' + """ + if "/" in model_name: + return model_name.split("/", 1)[1] + return model_name + + +def _dots_to_hyphens(model_name: str) -> str: + """Replace dots with hyphens in a model name. + + Anthropic's native API uses hyphens where marketing names use dots: + ``claude-sonnet-4.6`` -> ``claude-sonnet-4-6``. + """ + return model_name.replace(".", "-") + + +def _normalize_provider_alias(provider_name: str) -> str: + """Resolve provider aliases to Hermes' canonical ids.""" + raw = (provider_name or "").strip().lower() + if not raw: + return raw + try: + from hermes_cli.models import normalize_provider + + return normalize_provider(raw) + except Exception: + return raw + + +def _strip_matching_provider_prefix(model_name: str, target_provider: str) -> str: + """Strip ``provider/`` only when the prefix matches the target provider. + + This prevents arbitrary slash-bearing model IDs from being mangled on + native providers while still repairing manual config values like + ``zai/glm-5.1`` for the ``zai`` provider. + """ + if "/" not in model_name: + return model_name + + prefix, remainder = model_name.split("/", 1) + if not prefix.strip() or not remainder.strip(): + return model_name + + normalized_prefix = _normalize_provider_alias(prefix) + normalized_target = _normalize_provider_alias(target_provider) + if normalized_prefix and normalized_prefix == normalized_target: + return remainder.strip() + return model_name + + +def detect_vendor(model_name: str) -> Optional[str]: + """Detect the vendor slug from a bare model name. + + Uses the first hyphen-delimited token of the model name to look up + the corresponding vendor in ``_VENDOR_PREFIXES``. Also handles + case-insensitive matching and special patterns. + + Args: + model_name: A model name, optionally already including a + ``vendor/`` prefix. If a prefix is present it is used + directly. + + Returns: + The vendor slug (e.g. ``"anthropic"``, ``"openai"``) or ``None`` + if no vendor can be confidently detected. + + Examples:: + + >>> detect_vendor("claude-sonnet-4.6") + 'anthropic' + >>> detect_vendor("gpt-5.4-mini") + 'openai' + >>> detect_vendor("anthropic/claude-sonnet-4.6") + 'anthropic' + >>> detect_vendor("my-custom-model") + """ + name = model_name.strip() + if not name: + return None + + # If there's already a vendor/ prefix, extract it + if "/" in name: + return name.split("/", 1)[0].lower() or None + + name_lower = name.lower() + + # Try first hyphen-delimited token (exact match) + first_token = name_lower.split("-")[0] + if first_token in _VENDOR_PREFIXES: + return _VENDOR_PREFIXES[first_token] + + # Handle patterns where the first token includes version digits, + # e.g. "qwen3.5-plus" -> first token "qwen3.5", but prefix is "qwen" + for prefix, vendor in _VENDOR_PREFIXES.items(): + if name_lower.startswith(prefix): + return vendor + + return None + + +def _prepend_vendor(model_name: str) -> str: + """Prepend the detected ``vendor/`` prefix if missing. + + Used for aggregator providers that require ``vendor/model`` format. + If the name already contains a ``/``, it is returned as-is. + If no vendor can be detected, the name is returned unchanged + (aggregators may still accept it or return an error). + + Examples:: + + >>> _prepend_vendor("claude-sonnet-4.6") + 'anthropic/claude-sonnet-4.6' + >>> _prepend_vendor("anthropic/claude-sonnet-4.6") + 'anthropic/claude-sonnet-4.6' + >>> _prepend_vendor("my-custom-thing") + 'my-custom-thing' + """ + if "/" in model_name: + return model_name + + vendor = detect_vendor(model_name) + if vendor: + return f"{vendor}/{model_name}" + return model_name + + +# --------------------------------------------------------------------------- +# Main normalisation entry point +# --------------------------------------------------------------------------- + +def normalize_model_for_provider(model_input: str, target_provider: str) -> str: + """Translate a model name into the format the target provider's API expects. + + This is the primary entry point for model name normalisation. It + accepts any user-facing model identifier and transforms it for the + specific provider that will receive the API call. + + Args: + model_input: The model name as provided by the user or config. + Can be bare (``"claude-sonnet-4.6"``), vendor-prefixed + (``"anthropic/claude-sonnet-4.6"``), or already in native + format (``"claude-sonnet-4-6"``). + target_provider: The canonical Hermes provider id, e.g. + ``"openrouter"``, ``"anthropic"``, ``"copilot"``, + ``"deepseek"``, ``"custom"``. Should already be normalised + via ``hermes_cli.models.normalize_provider()``. + + Returns: + The model identifier string that the target provider's API + expects. + + Raises: + No exceptions -- always returns a best-effort string. + + Examples:: + + >>> normalize_model_for_provider("claude-sonnet-4.6", "openrouter") + 'anthropic/claude-sonnet-4.6' + + >>> normalize_model_for_provider("anthropic/claude-sonnet-4.6", "anthropic") + 'claude-sonnet-4-6' + + >>> normalize_model_for_provider("anthropic/claude-sonnet-4.6", "copilot") + 'claude-sonnet-4.6' + + >>> normalize_model_for_provider("openai/gpt-5.4", "copilot") + 'gpt-5.4' + + >>> normalize_model_for_provider("claude-sonnet-4.6", "opencode-zen") + 'claude-sonnet-4-6' + + >>> normalize_model_for_provider("minimax-m2.5-free", "opencode-zen") + 'minimax-m2.5-free' + + >>> normalize_model_for_provider("deepseek-v3", "deepseek") + 'deepseek-chat' + + >>> normalize_model_for_provider("deepseek-r1", "deepseek") + 'deepseek-reasoner' + + >>> normalize_model_for_provider("my-model", "custom") + 'my-model' + + >>> normalize_model_for_provider("claude-sonnet-4.6", "zai") + 'claude-sonnet-4.6' + """ + name = (model_input or "").strip() + if not name: + return name + + provider = _normalize_provider_alias(target_provider) + + # --- Aggregators: need vendor/model format --- + if provider in _AGGREGATOR_PROVIDERS: + return _prepend_vendor(name) + + # --- OpenCode Zen: Claude stays hyphenated; other models keep dots --- + if provider == "opencode-zen": + bare = _strip_matching_provider_prefix(name, provider) + if "/" in bare: + return bare + if bare.lower().startswith("claude-"): + return _dots_to_hyphens(bare) + return bare + + # --- Anthropic: strip matching provider prefix, dots -> hyphens --- + if provider in _DOT_TO_HYPHEN_PROVIDERS: + bare = _strip_matching_provider_prefix(name, provider) + if "/" in bare: + return bare + return _dots_to_hyphens(bare) + + # --- Copilot: strip matching provider prefix, keep dots --- + if provider in _STRIP_VENDOR_ONLY_PROVIDERS: + stripped = _strip_matching_provider_prefix(name, provider) + if stripped == name and name.startswith("openai/"): + # openai-codex maps openai/gpt-5.4 -> gpt-5.4 + return name.split("/", 1)[1] + return stripped + + # --- DeepSeek: map to one of two canonical names --- + if provider == "deepseek": + bare = _strip_matching_provider_prefix(name, provider) + if "/" in bare: + return bare + return _normalize_for_deepseek(bare) + + # --- Direct providers: repair matching provider prefixes only --- + if provider in _MATCHING_PREFIX_STRIP_PROVIDERS: + return _strip_matching_provider_prefix(name, provider) + + # --- Authoritative native providers: preserve user-facing slugs as-is --- + if provider in _AUTHORITATIVE_NATIVE_PROVIDERS: + return name + + # --- Custom & all others: pass through as-is --- + return name + + +# --------------------------------------------------------------------------- +# Batch / convenience helpers +# --------------------------------------------------------------------------- + diff --git a/mindcli/_vendor/hermes_cli/model_switch.py b/mindcli/_vendor/hermes_cli/model_switch.py new file mode 100644 index 0000000..699bde2 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/model_switch.py @@ -0,0 +1,1090 @@ +"""Shared model-switching logic for CLI and gateway /model commands. + +Both the CLI (cli.py) and gateway (gateway/run.py) /model handlers +share the same core pipeline: + + parse flags -> alias resolution -> provider resolution -> + credential resolution -> normalize model name -> + metadata lookup -> build result + +This module ties together the foundation layers: + +- ``agent.models_dev`` -- models.dev catalog, ModelInfo, ProviderInfo +- ``hermes_cli.providers`` -- canonical provider identity + overlays +- ``hermes_cli.model_normalize`` -- per-provider name formatting + +Provider switching uses the ``--provider`` flag exclusively. +No colon-based ``provider:model`` syntax — colons are reserved for +OpenRouter variant suffixes (``:free``, ``:extended``, ``:fast``). +""" + +from __future__ import annotations + +import logging +import re +from dataclasses import dataclass +from typing import List, NamedTuple, Optional + +from hermes_cli.providers import ( + custom_provider_slug, + determine_api_mode, + get_label, + is_aggregator, + resolve_provider_full, +) +from hermes_cli.model_normalize import ( + normalize_model_for_provider, +) +from agent.models_dev import ( + ModelCapabilities, + ModelInfo, + get_model_capabilities, + get_model_info, + list_provider_models, +) + +logger = logging.getLogger(__name__) + + +# --------------------------------------------------------------------------- +# Non-agentic model warning +# --------------------------------------------------------------------------- + +_HERMES_MODEL_WARNING = ( + "Nous Research Hermes 3 & 4 models are NOT agentic and are not designed " + "for use with Hermes Agent. They lack the tool-calling capabilities " + "required for agent workflows. Consider using an agentic model instead " + "(Claude, GPT, Gemini, DeepSeek, etc.)." +) + +# Match only the real Nous Research Hermes 3 / Hermes 4 chat families. +# The previous substring check (`"hermes" in name.lower()`) false-positived on +# unrelated local Modelfiles like ``hermes-brain:qwen3-14b-ctx16k`` that just +# happen to carry "hermes" in their tag but are fully tool-capable. +# +# Positive examples the regex must match: +# NousResearch/Hermes-3-Llama-3.1-70B, hermes-4-405b, openrouter/hermes3:70b +# Negative examples it must NOT match: +# hermes-brain:qwen3-14b-ctx16k, qwen3:14b, claude-opus-4-6 +_NOUS_HERMES_NON_AGENTIC_RE = re.compile( + r"(?:^|[/:])hermes[-_ ]?[34](?:[-_.:]|$)", + re.IGNORECASE, +) + + +def is_nous_hermes_non_agentic(model_name: str) -> bool: + """Return True if *model_name* is a real Nous Hermes 3/4 chat model. + + Used to decide whether to surface the non-agentic warning at startup. + Callers in :mod:`cli.py` and here should go through this single helper + so the two sites don't drift. + """ + if not model_name: + return False + return bool(_NOUS_HERMES_NON_AGENTIC_RE.search(model_name)) + + +def _check_hermes_model_warning(model_name: str) -> str: + """Return a warning string if *model_name* is a Nous Hermes 3/4 chat model.""" + if is_nous_hermes_non_agentic(model_name): + return _HERMES_MODEL_WARNING + return "" + + +# --------------------------------------------------------------------------- +# Model aliases -- short names -> (vendor, family) with NO version numbers. +# Resolved dynamically against the live models.dev catalog. +# --------------------------------------------------------------------------- + +class ModelIdentity(NamedTuple): + """Vendor slug and family prefix used for catalog resolution.""" + vendor: str + family: str + + +MODEL_ALIASES: dict[str, ModelIdentity] = { + # Anthropic + "sonnet": ModelIdentity("anthropic", "claude-sonnet"), + "opus": ModelIdentity("anthropic", "claude-opus"), + "haiku": ModelIdentity("anthropic", "claude-haiku"), + "claude": ModelIdentity("anthropic", "claude"), + + # OpenAI + "gpt5": ModelIdentity("openai", "gpt-5"), + "gpt": ModelIdentity("openai", "gpt"), + "codex": ModelIdentity("openai", "codex"), + "o3": ModelIdentity("openai", "o3"), + "o4": ModelIdentity("openai", "o4"), + + # Google + "gemini": ModelIdentity("google", "gemini"), + + # DeepSeek + "deepseek": ModelIdentity("deepseek", "deepseek-chat"), + + # X.AI + "grok": ModelIdentity("x-ai", "grok"), + + # Meta + "llama": ModelIdentity("meta-llama", "llama"), + + # Qwen / Alibaba + "qwen": ModelIdentity("qwen", "qwen"), + + # MiniMax + "minimax": ModelIdentity("minimax", "minimax"), + + # Nvidia + "nemotron": ModelIdentity("nvidia", "nemotron"), + + # Moonshot / Kimi + "kimi": ModelIdentity("moonshotai", "kimi"), + + # Z.AI / GLM + "glm": ModelIdentity("z-ai", "glm"), + + # StepFun + "step": ModelIdentity("stepfun", "step"), + + # Xiaomi + "mimo": ModelIdentity("xiaomi", "mimo"), + + # Arcee + "trinity": ModelIdentity("arcee-ai", "trinity"), +} + + +# --------------------------------------------------------------------------- +# Direct aliases — exact model+provider+base_url for endpoints that aren't +# in the models.dev catalog (e.g. Ollama Cloud, local servers). +# Checked BEFORE catalog resolution. Format: +# alias -> (model_id, provider, base_url) +# These can also be loaded from config.yaml ``model_aliases:`` section. +# --------------------------------------------------------------------------- + +class DirectAlias(NamedTuple): + """Exact model mapping that bypasses catalog resolution.""" + model: str + provider: str + base_url: str + + +# Built-in direct aliases (can be extended via config.yaml model_aliases:) +_BUILTIN_DIRECT_ALIASES: dict[str, DirectAlias] = {} + +# Merged dict (builtins + user config); populated by _load_direct_aliases() +DIRECT_ALIASES: dict[str, DirectAlias] = {} + + +def _load_direct_aliases() -> dict[str, DirectAlias]: + """Load direct aliases from config.yaml ``model_aliases:`` section. + + Config format:: + + model_aliases: + qwen: + model: "qwen3.5:397b" + provider: custom + base_url: "https://ollama.com/v1" + minimax: + model: "minimax-m2.7" + provider: custom + base_url: "https://ollama.com/v1" + """ + merged = dict(_BUILTIN_DIRECT_ALIASES) + try: + from hermes_cli.config import load_config + cfg = load_config() + user_aliases = cfg.get("model_aliases") + if isinstance(user_aliases, dict): + for name, entry in user_aliases.items(): + if not isinstance(entry, dict): + continue + model = entry.get("model", "") + provider = entry.get("provider", "custom") + base_url = entry.get("base_url", "") + if model: + merged[name.strip().lower()] = DirectAlias( + model=model, provider=provider, base_url=base_url, + ) + except Exception: + pass + return merged + + +def _ensure_direct_aliases() -> None: + """Lazy-load direct aliases on first use.""" + global DIRECT_ALIASES + if not DIRECT_ALIASES: + DIRECT_ALIASES = _load_direct_aliases() + + +# --------------------------------------------------------------------------- +# Result dataclasses +# --------------------------------------------------------------------------- + +@dataclass +class ModelSwitchResult: + """Result of a model switch attempt.""" + + success: bool + new_model: str = "" + target_provider: str = "" + provider_changed: bool = False + api_key: str = "" + base_url: str = "" + api_mode: str = "" + error_message: str = "" + warning_message: str = "" + provider_label: str = "" + resolved_via_alias: str = "" + capabilities: Optional[ModelCapabilities] = None + model_info: Optional[ModelInfo] = None + is_global: bool = False + + +@dataclass +class CustomAutoResult: + """Result of switching to bare 'custom' provider with auto-detect.""" + + success: bool + model: str = "" + base_url: str = "" + api_key: str = "" + error_message: str = "" + + +# --------------------------------------------------------------------------- +# Flag parsing +# --------------------------------------------------------------------------- + +def parse_model_flags(raw_args: str) -> tuple[str, str, bool]: + """Parse --provider and --global flags from /model command args. + + Returns (model_input, explicit_provider, is_global). + + Examples:: + + "sonnet" -> ("sonnet", "", False) + "sonnet --global" -> ("sonnet", "", True) + "sonnet --provider anthropic" -> ("sonnet", "anthropic", False) + "--provider my-ollama" -> ("", "my-ollama", False) + "sonnet --provider anthropic --global" -> ("sonnet", "anthropic", True) + """ + is_global = False + explicit_provider = "" + + # Extract --global + if "--global" in raw_args: + is_global = True + raw_args = raw_args.replace("--global", "").strip() + + # Extract --provider + parts = raw_args.split() + i = 0 + filtered: list[str] = [] + while i < len(parts): + if parts[i] == "--provider" and i + 1 < len(parts): + explicit_provider = parts[i + 1] + i += 2 + else: + filtered.append(parts[i]) + i += 1 + + model_input = " ".join(filtered).strip() + return (model_input, explicit_provider, is_global) + + +# --------------------------------------------------------------------------- +# Alias resolution +# --------------------------------------------------------------------------- + +def resolve_alias( + raw_input: str, + current_provider: str, +) -> Optional[tuple[str, str, str]]: + """Resolve a short alias against the current provider's catalog. + + Looks up *raw_input* in :data:`MODEL_ALIASES`, then searches the + current provider's models.dev catalog for the first model whose ID + starts with ``vendor/family`` (or just ``family`` for non-aggregator + providers). + + Returns: + ``(provider, resolved_model_id, alias_name)`` if a match is + found on the current provider, or ``None`` if the alias doesn't + exist or no matching model is available. + """ + key = raw_input.strip().lower() + + # Check direct aliases first (exact model+provider+base_url mappings) + _ensure_direct_aliases() + direct = DIRECT_ALIASES.get(key) + if direct is not None: + return (direct.provider, direct.model, key) + + # Reverse lookup: match by model ID so full names (e.g. "kimi-k2.5", + # "glm-4.7") route through direct aliases instead of falling through + # to the catalog/OpenRouter. + for alias_name, da in DIRECT_ALIASES.items(): + if da.model.lower() == key: + return (da.provider, da.model, alias_name) + + identity = MODEL_ALIASES.get(key) + if identity is None: + return None + + vendor, family = identity + + # Search the provider's catalog from models.dev + catalog = list_provider_models(current_provider) + if not catalog: + return None + + # For aggregators, models are vendor/model-name format + aggregator = is_aggregator(current_provider) + + for model_id in catalog: + mid_lower = model_id.lower() + if aggregator: + # Match vendor/family prefix -- e.g. "anthropic/claude-sonnet" + prefix = f"{vendor}/{family}".lower() + if mid_lower.startswith(prefix): + return (current_provider, model_id, key) + else: + # Non-aggregator: bare names -- e.g. "claude-sonnet-4-6" + family_lower = family.lower() + if mid_lower.startswith(family_lower): + return (current_provider, model_id, key) + + return None + + +def get_authenticated_provider_slugs( + current_provider: str = "", + user_providers: dict = None, + custom_providers: list | None = None, +) -> list[str]: + """Return slugs of providers that have credentials. + + Uses ``list_authenticated_providers()`` which is backed by the models.dev + in-memory cache (1 hr TTL) — no extra network cost. + """ + try: + providers = list_authenticated_providers( + current_provider=current_provider, + user_providers=user_providers, + custom_providers=custom_providers, + max_models=0, + ) + return [p["slug"] for p in providers] + except Exception: + return [] + + +def _resolve_alias_fallback( + raw_input: str, + authenticated_providers: list[str] = (), +) -> Optional[tuple[str, str, str]]: + """Try to resolve an alias on the user's authenticated providers. + + Falls back to ``("openrouter", "nous")`` only when no authenticated + providers are supplied (backwards compat for non-interactive callers). + """ + providers = authenticated_providers or ("openrouter", "nous") + for provider in providers: + result = resolve_alias(raw_input, provider) + if result is not None: + return result + return None + + +# --------------------------------------------------------------------------- +# Core model-switching pipeline +# --------------------------------------------------------------------------- + +def switch_model( + raw_input: str, + current_provider: str, + current_model: str, + current_base_url: str = "", + current_api_key: str = "", + is_global: bool = False, + explicit_provider: str = "", + user_providers: dict = None, + custom_providers: list | None = None, +) -> ModelSwitchResult: + """Core model-switching pipeline shared between CLI and gateway. + + Resolution chain: + + If --provider given: + a. Resolve provider via resolve_provider_full() + b. Resolve credentials + c. If model given, resolve alias on target provider or use as-is + d. If no model, auto-detect from endpoint + + If no --provider: + a. Try alias resolution on current provider + b. If alias exists but not on current provider -> fallback + c. On aggregator, try vendor/model slug conversion + d. Aggregator catalog search + e. detect_provider_for_model() as last resort + f. Resolve credentials + g. Normalize model name for target provider + + Finally: + h. Get full model metadata from models.dev + i. Build result + + Args: + raw_input: The model name (after flag parsing). + current_provider: The currently active provider. + current_model: The currently active model name. + current_base_url: The currently active base URL. + current_api_key: The currently active API key. + is_global: Whether to persist the switch. + explicit_provider: From --provider flag (empty = no explicit provider). + user_providers: The ``providers:`` dict from config.yaml (for user endpoints). + custom_providers: The ``custom_providers:`` list from config.yaml. + + Returns: + ModelSwitchResult with all information the caller needs. + """ + from hermes_cli.models import ( + detect_provider_for_model, + validate_requested_model, + opencode_model_api_mode, + ) + from hermes_cli.runtime_provider import resolve_runtime_provider + + resolved_alias = "" + new_model = raw_input.strip() + target_provider = current_provider + + # ================================================================= + # PATH A: Explicit --provider given + # ================================================================= + if explicit_provider: + # Resolve the provider + pdef = resolve_provider_full( + explicit_provider, + user_providers, + custom_providers, + ) + if pdef is None: + _switch_err = ( + f"Unknown provider '{explicit_provider}'. " + f"Check 'hermes model' for available providers, or define it " + f"in config.yaml under 'providers:'." + ) + # Check for common config issues that cause provider resolution failures + try: + from hermes_cli.config import validate_config_structure + _cfg_issues = validate_config_structure() + if _cfg_issues: + _switch_err += "\n\nRun 'hermes doctor' — config issues detected:" + for _ci in _cfg_issues[:3]: + _switch_err += f"\n • {_ci.message}" + except Exception: + pass + return ModelSwitchResult( + success=False, + is_global=is_global, + error_message=_switch_err, + ) + + target_provider = pdef.id + + # If no model specified, try auto-detect from endpoint + if not new_model: + if pdef.base_url: + from hermes_cli.runtime_provider import _auto_detect_local_model + detected = _auto_detect_local_model(pdef.base_url) + if detected: + new_model = detected + else: + return ModelSwitchResult( + success=False, + target_provider=target_provider, + provider_label=pdef.name, + is_global=is_global, + error_message=( + f"No model detected on {pdef.name} ({pdef.base_url}). " + f"Specify the model explicitly: /model --provider {explicit_provider}" + ), + ) + else: + return ModelSwitchResult( + success=False, + target_provider=target_provider, + provider_label=pdef.name, + is_global=is_global, + error_message=( + f"Provider '{pdef.name}' has no base URL configured. " + f"Specify a model: /model --provider {explicit_provider}" + ), + ) + + # Resolve alias on the TARGET provider + alias_result = resolve_alias(new_model, target_provider) + if alias_result is not None: + _, new_model, resolved_alias = alias_result + + # ================================================================= + # PATH B: No explicit provider — resolve from model input + # ================================================================= + else: + # --- Step a: Try alias resolution on current provider --- + alias_result = resolve_alias(raw_input, current_provider) + + if alias_result is not None: + target_provider, new_model, resolved_alias = alias_result + logger.debug( + "Alias '%s' resolved to %s on %s", + resolved_alias, new_model, target_provider, + ) + else: + # --- Step b: Alias exists but not on current provider -> fallback --- + key = raw_input.strip().lower() + if key in MODEL_ALIASES: + authed = get_authenticated_provider_slugs( + current_provider=current_provider, + user_providers=user_providers, + custom_providers=custom_providers, + ) + fallback_result = _resolve_alias_fallback(raw_input, authed) + if fallback_result is not None: + target_provider, new_model, resolved_alias = fallback_result + logger.debug( + "Alias '%s' resolved via fallback to %s on %s", + resolved_alias, new_model, target_provider, + ) + else: + identity = MODEL_ALIASES[key] + return ModelSwitchResult( + success=False, + is_global=is_global, + error_message=( + f"Alias '{key}' maps to {identity.vendor}/{identity.family} " + f"but no matching model was found in any provider catalog. " + f"Try specifying the full model name." + ), + ) + else: + # --- Step c: On aggregator, convert vendor:model to vendor/model --- + # Only convert when there's no slash — a slash means the name + # is already in vendor/model format and the colon is a variant + # tag (:free, :extended, :fast) that must be preserved. + colon_pos = raw_input.find(":") + if colon_pos > 0 and "/" not in raw_input and is_aggregator(current_provider): + left = raw_input[:colon_pos].strip().lower() + right = raw_input[colon_pos + 1:].strip() + if left and right: + # Colons become slashes for aggregator slugs + new_model = f"{left}/{right}" + logger.debug( + "Converted vendor:model '%s' to aggregator slug '%s'", + raw_input, new_model, + ) + + # --- Step d: Aggregator catalog search --- + if is_aggregator(target_provider) and not resolved_alias: + catalog = list_provider_models(target_provider) + if catalog: + new_model_lower = new_model.lower() + for mid in catalog: + if mid.lower() == new_model_lower: + new_model = mid + break + else: + for mid in catalog: + if "/" in mid: + _, bare = mid.split("/", 1) + if bare.lower() == new_model_lower: + new_model = mid + break + + # --- Step e: detect_provider_for_model() as last resort --- + _base = current_base_url or "" + is_custom = current_provider in ("custom", "local") or ( + "localhost" in _base or "127.0.0.1" in _base + ) + + if ( + target_provider == current_provider + and not is_custom + and not resolved_alias + ): + detected = detect_provider_for_model(new_model, current_provider) + if detected: + target_provider, new_model = detected + + # ================================================================= + # COMMON PATH: Resolve credentials, normalize, get metadata + # ================================================================= + + provider_changed = target_provider != current_provider + provider_label = get_label(target_provider) + if target_provider.startswith("custom:"): + custom_pdef = resolve_provider_full( + target_provider, + user_providers, + custom_providers, + ) + if custom_pdef is not None: + provider_label = custom_pdef.name + + # --- Resolve credentials --- + api_key = current_api_key + base_url = current_base_url + api_mode = "" + + if provider_changed or explicit_provider: + try: + runtime = resolve_runtime_provider(requested=target_provider) + api_key = runtime.get("api_key", "") + base_url = runtime.get("base_url", "") + api_mode = runtime.get("api_mode", "") + except Exception as e: + return ModelSwitchResult( + success=False, + target_provider=target_provider, + provider_label=provider_label, + is_global=is_global, + error_message=( + f"Could not resolve credentials for provider " + f"'{provider_label}': {e}" + ), + ) + else: + try: + runtime = resolve_runtime_provider(requested=current_provider) + api_key = runtime.get("api_key", "") + base_url = runtime.get("base_url", "") + api_mode = runtime.get("api_mode", "") + except Exception: + pass + + # --- Direct alias override: use exact base_url from the alias if set --- + if resolved_alias: + _ensure_direct_aliases() + _da = DIRECT_ALIASES.get(resolved_alias) + if _da is not None and _da.base_url: + base_url = _da.base_url + if not api_key: + api_key = "no-key-required" + + # --- Normalize model name for target provider --- + new_model = normalize_model_for_provider(new_model, target_provider) + + # --- Validate --- + try: + validation = validate_requested_model( + new_model, + target_provider, + api_key=api_key, + base_url=base_url, + ) + except Exception: + validation = { + "accepted": True, + "persist": True, + "recognized": False, + "message": None, + } + + if not validation.get("accepted"): + msg = validation.get("message", "Invalid model") + return ModelSwitchResult( + success=False, + new_model=new_model, + target_provider=target_provider, + provider_label=provider_label, + is_global=is_global, + error_message=msg, + ) + + # Apply auto-correction if validation found a closer match + if validation.get("corrected_model"): + new_model = validation["corrected_model"] + + # --- OpenCode api_mode override --- + if target_provider in {"opencode-zen", "opencode-go", "opencode", "opencode-go"}: + api_mode = opencode_model_api_mode(target_provider, new_model) + + # --- Determine api_mode if not already set --- + if not api_mode: + api_mode = determine_api_mode(target_provider, base_url) + + # --- Get capabilities (legacy) --- + capabilities = get_model_capabilities(target_provider, new_model) + + # --- Get full model info from models.dev --- + model_info = get_model_info(target_provider, new_model) + + # --- Collect warnings --- + warnings: list[str] = [] + if validation.get("message"): + warnings.append(validation["message"]) + hermes_warn = _check_hermes_model_warning(new_model) + if hermes_warn: + warnings.append(hermes_warn) + + # --- Build result --- + return ModelSwitchResult( + success=True, + new_model=new_model, + target_provider=target_provider, + provider_changed=provider_changed, + api_key=api_key, + base_url=base_url, + api_mode=api_mode, + warning_message=" | ".join(warnings) if warnings else "", + provider_label=provider_label, + resolved_via_alias=resolved_alias, + capabilities=capabilities, + model_info=model_info, + is_global=is_global, + ) + + +# --------------------------------------------------------------------------- +# Authenticated providers listing (for /model no-args display) +# --------------------------------------------------------------------------- + +def list_authenticated_providers( + current_provider: str = "", + user_providers: dict = None, + custom_providers: list | None = None, + max_models: int = 8, +) -> List[dict]: + """Detect which providers have credentials and list their curated models. + + Uses the curated model lists from hermes_cli/models.py (OPENROUTER_MODELS, + _PROVIDER_MODELS) — NOT the full models.dev catalog. These are hand-picked + agentic models that work well as agent backends. + + Returns a list of dicts, each with: + - slug: str — the --provider value to use + - name: str — display name + - is_current: bool + - is_user_defined: bool + - models: list[str] — curated model IDs (up to max_models) + - total_models: int — total curated count + - source: str — "built-in", "models.dev", "user-config" + + Only includes providers that have API keys set or are user-defined endpoints. + """ + import os + from agent.models_dev import ( + PROVIDER_TO_MODELS_DEV, + fetch_models_dev, + get_provider_info as _mdev_pinfo, + ) + from hermes_cli.auth import PROVIDER_REGISTRY + from hermes_cli.models import OPENROUTER_MODELS, _PROVIDER_MODELS + + results: List[dict] = [] + seen_slugs: set = set() + + data = fetch_models_dev() + + # Build curated model lists keyed by hermes provider ID + curated: dict[str, list[str]] = dict(_PROVIDER_MODELS) + curated["openrouter"] = [mid for mid, _ in OPENROUTER_MODELS] + # "nous" shares OpenRouter's curated list if not separately defined + if "nous" not in curated: + curated["nous"] = curated["openrouter"] + + # --- 1. Check Hermes-mapped providers --- + for hermes_id, mdev_id in PROVIDER_TO_MODELS_DEV.items(): + pdata = data.get(mdev_id) + if not isinstance(pdata, dict): + continue + + # Prefer auth.py PROVIDER_REGISTRY for env var names — it's our + # source of truth. models.dev can have wrong mappings (e.g. + # minimax-cn → MINIMAX_API_KEY instead of MINIMAX_CN_API_KEY). + pconfig = PROVIDER_REGISTRY.get(hermes_id) + if pconfig and pconfig.api_key_env_vars: + env_vars = list(pconfig.api_key_env_vars) + else: + env_vars = pdata.get("env", []) + if not isinstance(env_vars, list): + continue + + # Check if any env var is set + has_creds = any(os.environ.get(ev) for ev in env_vars) + if not has_creds: + continue + + # Use curated list, falling back to models.dev if no curated list + model_ids = curated.get(hermes_id, []) + total = len(model_ids) + top = model_ids[:max_models] + + slug = hermes_id + pinfo = _mdev_pinfo(mdev_id) + display_name = pinfo.name if pinfo else mdev_id + + results.append({ + "slug": slug, + "name": display_name, + "is_current": slug == current_provider or mdev_id == current_provider, + "is_user_defined": False, + "models": top, + "total_models": total, + "source": "built-in", + }) + seen_slugs.add(slug) + + # --- 2. Check Hermes-only providers (nous, openai-codex, copilot, opencode-go) --- + from hermes_cli.providers import HERMES_OVERLAYS + from hermes_cli.auth import PROVIDER_REGISTRY as _auth_registry + + # Build reverse mapping: models.dev ID → Hermes provider ID. + # HERMES_OVERLAYS keys may be models.dev IDs (e.g. "github-copilot") + # while _PROVIDER_MODELS and config.yaml use Hermes IDs ("copilot"). + _mdev_to_hermes = {v: k for k, v in PROVIDER_TO_MODELS_DEV.items()} + + for pid, overlay in HERMES_OVERLAYS.items(): + if pid in seen_slugs: + continue + + # Resolve Hermes slug — e.g. "github-copilot" → "copilot" + hermes_slug = _mdev_to_hermes.get(pid, pid) + if hermes_slug in seen_slugs: + continue + + # Check if credentials exist + has_creds = False + if overlay.extra_env_vars: + has_creds = any(os.environ.get(ev) for ev in overlay.extra_env_vars) + # Also check api_key_env_vars from PROVIDER_REGISTRY for api_key auth_type + if not has_creds and overlay.auth_type == "api_key": + for _key in (pid, hermes_slug): + pcfg = _auth_registry.get(_key) + if pcfg and pcfg.api_key_env_vars: + if any(os.environ.get(ev) for ev in pcfg.api_key_env_vars): + has_creds = True + break + # Check auth store and credential pool for non-env-var credentials. + # This applies to OAuth providers AND api_key providers that also + # support OAuth (e.g. anthropic supports both API key and Claude Code + # OAuth via external credential files). + if not has_creds: + try: + from hermes_cli.auth import _load_auth_store + store = _load_auth_store() + providers_store = store.get("providers", {}) + pool_store = store.get("credential_pool", {}) + if store and ( + pid in providers_store or hermes_slug in providers_store + or pid in pool_store or hermes_slug in pool_store + ): + has_creds = True + except Exception as exc: + logger.debug("Auth store check failed for %s: %s", pid, exc) + # Fallback: check the credential pool with full auto-seeding. + # This catches credentials that exist in external stores (e.g. + # Codex CLI ~/.codex/auth.json) which _seed_from_singletons() + # imports on demand but aren't in the raw auth.json yet. + if not has_creds: + try: + from agent.credential_pool import load_pool + pool = load_pool(hermes_slug) + if pool.has_credentials(): + has_creds = True + except Exception as exc: + logger.debug("Credential pool check failed for %s: %s", hermes_slug, exc) + # Fallback: check external credential files directly. + # The credential pool gates anthropic behind + # is_provider_explicitly_configured() to prevent auxiliary tasks + # from silently consuming Claude Code tokens (PR #4210). + # But the /model picker is discovery-oriented — we WANT to show + # providers the user can switch to, even if they aren't currently + # configured. + if not has_creds and hermes_slug == "anthropic": + try: + from agent.anthropic_adapter import ( + read_claude_code_credentials, + read_hermes_oauth_credentials, + ) + hermes_creds = read_hermes_oauth_credentials() + cc_creds = read_claude_code_credentials() + if (hermes_creds and hermes_creds.get("accessToken")) or \ + (cc_creds and cc_creds.get("accessToken")): + has_creds = True + except Exception as exc: + logger.debug("Anthropic external creds check failed: %s", exc) + if not has_creds: + continue + + # Use curated list — look up by Hermes slug, fall back to overlay key + model_ids = curated.get(hermes_slug, []) or curated.get(pid, []) + total = len(model_ids) + top = model_ids[:max_models] + + results.append({ + "slug": hermes_slug, + "name": get_label(hermes_slug), + "is_current": hermes_slug == current_provider or pid == current_provider, + "is_user_defined": False, + "models": top, + "total_models": total, + "source": "hermes", + }) + seen_slugs.add(pid) + seen_slugs.add(hermes_slug) + + # --- 2b. Cross-check canonical provider list --- + # Catches providers that are in CANONICAL_PROVIDERS but weren't found + # in PROVIDER_TO_MODELS_DEV or HERMES_OVERLAYS (keeps /model in sync + # with `hermes model`). + try: + from hermes_cli.models import CANONICAL_PROVIDERS as _canon_provs + except ImportError: + _canon_provs = [] + + for _cp in _canon_provs: + if _cp.slug in seen_slugs: + continue + + # Check credentials via PROVIDER_REGISTRY (auth.py) + _cp_config = _auth_registry.get(_cp.slug) + _cp_has_creds = False + if _cp_config and _cp_config.api_key_env_vars: + _cp_has_creds = any(os.environ.get(ev) for ev in _cp_config.api_key_env_vars) + # Also check auth store and credential pool + if not _cp_has_creds: + try: + from hermes_cli.auth import _load_auth_store + _cp_store = _load_auth_store() + _cp_providers_store = _cp_store.get("providers", {}) + _cp_pool_store = _cp_store.get("credential_pool", {}) + if _cp_store and ( + _cp.slug in _cp_providers_store + or _cp.slug in _cp_pool_store + ): + _cp_has_creds = True + except Exception: + pass + if not _cp_has_creds: + try: + from agent.credential_pool import load_pool + _cp_pool = load_pool(_cp.slug) + if _cp_pool.has_credentials(): + _cp_has_creds = True + except Exception: + pass + + if not _cp_has_creds: + continue + + _cp_model_ids = curated.get(_cp.slug, []) + _cp_total = len(_cp_model_ids) + _cp_top = _cp_model_ids[:max_models] + + results.append({ + "slug": _cp.slug, + "name": _cp.label, + "is_current": _cp.slug == current_provider, + "is_user_defined": False, + "models": _cp_top, + "total_models": _cp_total, + "source": "canonical", + }) + seen_slugs.add(_cp.slug) + + # --- 3. User-defined endpoints from config --- + if user_providers and isinstance(user_providers, dict): + for ep_name, ep_cfg in user_providers.items(): + if not isinstance(ep_cfg, dict): + continue + display_name = ep_cfg.get("name", "") or ep_name + api_url = ep_cfg.get("api", "") or ep_cfg.get("url", "") or "" + default_model = ep_cfg.get("default_model", "") + + # Build models list from both default_model and full models array + models_list = [] + if default_model: + models_list.append(default_model) + # Also include the full models list from config + cfg_models = ep_cfg.get("models", []) + if isinstance(cfg_models, list): + for m in cfg_models: + if m and m not in models_list: + models_list.append(m) + + # Try to probe /v1/models if URL is set (but don't block on it) + # For now just show what we know from config + results.append({ + "slug": ep_name, + "name": display_name, + "is_current": ep_name == current_provider, + "is_user_defined": True, + "models": models_list, + "total_models": len(models_list) if models_list else 0, + "source": "user-config", + "api_url": api_url, + }) + + # --- 4. Saved custom providers from config --- + # Each ``custom_providers`` entry represents one model under a named + # provider. Entries sharing the same provider name are grouped into a + # single picker row so that e.g. four Ollama Cloud entries + # (qwen3-coder, glm-5.1, kimi-k2, minimax-m2.7) appear as one + # "Ollama Cloud" row with four models inside instead of four + # duplicate "Ollama Cloud" rows. Entries with distinct provider names + # still produce separate rows (e.g. Ollama Cloud vs Moonshot). + if custom_providers and isinstance(custom_providers, list): + from collections import OrderedDict + + groups: "OrderedDict[str, dict]" = OrderedDict() + for entry in custom_providers: + if not isinstance(entry, dict): + continue + + display_name = (entry.get("name") or "").strip() + api_url = ( + entry.get("base_url", "") + or entry.get("url", "") + or entry.get("api", "") + or "" + ).strip() + if not display_name or not api_url: + continue + + slug = custom_provider_slug(display_name) + if slug not in groups: + groups[slug] = { + "name": display_name, + "api_url": api_url, + "models": [], + } + default_model = (entry.get("model") or "").strip() + if default_model and default_model not in groups[slug]["models"]: + groups[slug]["models"].append(default_model) + + for slug, grp in groups.items(): + if slug in seen_slugs: + continue + results.append({ + "slug": slug, + "name": grp["name"], + "is_current": slug == current_provider, + "is_user_defined": True, + "models": grp["models"], + "total_models": len(grp["models"]), + "source": "user-config", + "api_url": grp["api_url"], + }) + seen_slugs.add(slug) + + # Sort: current provider first, then by model count descending + results.sort(key=lambda r: (not r["is_current"], -r["total_models"])) + + return results + + diff --git a/mindcli/_vendor/hermes_cli/models.py b/mindcli/_vendor/hermes_cli/models.py new file mode 100644 index 0000000..8526012 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/models.py @@ -0,0 +1,1966 @@ +""" +Canonical model catalogs and lightweight validation helpers. + +Add, remove, or reorder entries here — both `hermes setup` and +`hermes` provider-selection will pick up the change automatically. +""" + +from __future__ import annotations + +import json +import os +import urllib.request +import urllib.error +from difflib import get_close_matches +from typing import Any, NamedTuple, Optional + +COPILOT_BASE_URL = "https://api.githubcopilot.com" +COPILOT_MODELS_URL = f"{COPILOT_BASE_URL}/models" +COPILOT_EDITOR_VERSION = "vscode/1.104.1" +COPILOT_REASONING_EFFORTS_GPT5 = ["minimal", "low", "medium", "high"] +COPILOT_REASONING_EFFORTS_O_SERIES = ["low", "medium", "high"] + + +# Fallback OpenRouter snapshot used when the live catalog is unavailable. +# (model_id, display description shown in menus) +OPENROUTER_MODELS: list[tuple[str, str]] = [ + ("anthropic/claude-opus-4.6", "recommended"), + ("anthropic/claude-sonnet-4.6", ""), + ("qwen/qwen3.6-plus", ""), + ("anthropic/claude-sonnet-4.5", ""), + ("anthropic/claude-haiku-4.5", ""), + ("openrouter/elephant-alpha", "free"), + ("openai/gpt-5.4", ""), + ("openai/gpt-5.4-mini", ""), + ("xiaomi/mimo-v2-pro", ""), + ("openai/gpt-5.3-codex", ""), + ("google/gemini-3-pro-image-preview", ""), + ("google/gemini-3-flash-preview", ""), + ("google/gemini-3.1-pro-preview", ""), + ("google/gemini-3.1-flash-lite-preview", ""), + ("qwen/qwen3.5-plus-02-15", ""), + ("qwen/qwen3.5-35b-a3b", ""), + ("stepfun/step-3.5-flash", ""), + ("minimax/minimax-m2.7", ""), + ("minimax/minimax-m2.5", ""), + ("z-ai/glm-5.1", ""), + ("z-ai/glm-5-turbo", ""), + ("moonshotai/kimi-k2.5", ""), + ("x-ai/grok-4.20", ""), + ("nvidia/nemotron-3-super-120b-a12b", ""), + ("nvidia/nemotron-3-super-120b-a12b:free", "free"), + ("arcee-ai/trinity-large-preview:free", "free"), + ("arcee-ai/trinity-large-thinking", ""), + ("openai/gpt-5.4-pro", ""), + ("openai/gpt-5.4-nano", ""), +] + +_openrouter_catalog_cache: list[tuple[str, str]] | None = None + + +def _codex_curated_models() -> list[str]: + """Derive the openai-codex curated list from codex_models.py. + + Single source of truth: DEFAULT_CODEX_MODELS + forward-compat synthesis. + This keeps the gateway /model picker in sync with the CLI `hermes model` + flow without maintaining a separate static list. + """ + from hermes_cli.codex_models import DEFAULT_CODEX_MODELS, _add_forward_compat_models + return _add_forward_compat_models(list(DEFAULT_CODEX_MODELS)) + + +_PROVIDER_MODELS: dict[str, list[str]] = { + "nous": [ + "xiaomi/mimo-v2-pro", + "anthropic/claude-opus-4.6", + "anthropic/claude-sonnet-4.6", + "anthropic/claude-sonnet-4.5", + "anthropic/claude-haiku-4.5", + "openai/gpt-5.4", + "openai/gpt-5.4-mini", + "openai/gpt-5.3-codex", + "google/gemini-3-pro-preview", + "google/gemini-3-flash-preview", + "google/gemini-3.1-pro-preview", + "google/gemini-3.1-flash-lite-preview", + "qwen/qwen3.5-plus-02-15", + "qwen/qwen3.5-35b-a3b", + "stepfun/step-3.5-flash", + "minimax/minimax-m2.7", + "minimax/minimax-m2.5", + "z-ai/glm-5.1", + "z-ai/glm-5-turbo", + "moonshotai/kimi-k2.5", + "x-ai/grok-4.20-beta", + "nvidia/nemotron-3-super-120b-a12b", + "nvidia/nemotron-3-super-120b-a12b:free", + "arcee-ai/trinity-large-preview:free", + "arcee-ai/trinity-large-thinking", + "openai/gpt-5.4-pro", + "openai/gpt-5.4-nano", + "openrouter/elephant-alpha", + ], + "openai-codex": _codex_curated_models(), + "copilot-acp": [ + "copilot-acp", + ], + "copilot": [ + "gpt-5.4", + "gpt-5.4-mini", + "gpt-5-mini", + "gpt-5.3-codex", + "gpt-5.2-codex", + "gpt-4.1", + "gpt-4o", + "gpt-4o-mini", + "claude-opus-4.6", + "claude-sonnet-4.6", + "claude-sonnet-4.5", + "claude-haiku-4.5", + "gemini-2.5-pro", + "grok-code-fast-1", + ], + "gemini": [ + "gemini-3.1-pro-preview", + "gemini-3-flash-preview", + "gemini-3.1-flash-lite-preview", + "gemini-2.5-pro", + "gemini-2.5-flash", + "gemini-2.5-flash-lite", + # Gemma open models (also served via AI Studio) + "gemma-4-31b-it", + "gemma-4-26b-it", + ], + "zai": [ + "glm-5.1", + "glm-5", + "glm-5-turbo", + "glm-4.7", + "glm-4.5", + "glm-4.5-flash", + ], + "xai": [ + "grok-4.20-0309-reasoning", + "grok-4.20-0309-non-reasoning", + "grok-4.20-multi-agent-0309", + "grok-4-1-fast-reasoning", + "grok-4-1-fast-non-reasoning", + "grok-4-fast-reasoning", + "grok-4-fast-non-reasoning", + "grok-4-0709", + "grok-code-fast-1", + "grok-3", + "grok-3-mini", + ], + "kimi-coding": [ + "kimi-for-coding", + "kimi-k2.5", + "kimi-k2-thinking", + "kimi-k2-thinking-turbo", + "kimi-k2-turbo-preview", + "kimi-k2-0905-preview", + ], + "kimi-coding-cn": [ + "kimi-k2.5", + "kimi-k2-thinking", + "kimi-k2-turbo-preview", + "kimi-k2-0905-preview", + ], + "moonshot": [ + "kimi-k2.5", + "kimi-k2-thinking", + "kimi-k2-turbo-preview", + "kimi-k2-0905-preview", + ], + "minimax": [ + "MiniMax-M2.7", + "MiniMax-M2.5", + "MiniMax-M2.1", + "MiniMax-M2", + ], + "minimax-cn": [ + "MiniMax-M2.7", + "MiniMax-M2.5", + "MiniMax-M2.1", + "MiniMax-M2", + ], + "anthropic": [ + "claude-opus-4-6", + "claude-sonnet-4-6", + "claude-opus-4-5-20251101", + "claude-sonnet-4-5-20250929", + "claude-opus-4-20250514", + "claude-sonnet-4-20250514", + "claude-haiku-4-5-20251001", + ], + "deepseek": [ + "deepseek-chat", + "deepseek-reasoner", + ], + "xiaomi": [ + "mimo-v2-pro", + "mimo-v2-omni", + "mimo-v2-flash", + ], + "arcee": [ + "trinity-large-thinking", + "trinity-large-preview", + "trinity-mini", + ], + "opencode-zen": [ + "gpt-5.4-pro", + "gpt-5.4", + "gpt-5.3-codex", + "gpt-5.3-codex-spark", + "gpt-5.2", + "gpt-5.2-codex", + "gpt-5.1", + "gpt-5.1-codex", + "gpt-5.1-codex-max", + "gpt-5.1-codex-mini", + "gpt-5", + "gpt-5-codex", + "gpt-5-nano", + "claude-opus-4-6", + "claude-opus-4-5", + "claude-opus-4-1", + "claude-sonnet-4-6", + "claude-sonnet-4-5", + "claude-sonnet-4", + "claude-haiku-4-5", + "claude-3-5-haiku", + "gemini-3.1-pro", + "gemini-3-pro", + "gemini-3-flash", + "minimax-m2.7", + "minimax-m2.5", + "minimax-m2.5-free", + "minimax-m2.1", + "glm-5", + "glm-4.7", + "glm-4.6", + "kimi-k2.5", + "kimi-k2-thinking", + "kimi-k2", + "qwen3-coder", + "big-pickle", + ], + "opencode-go": [ + "glm-5", + "kimi-k2.5", + "mimo-v2-pro", + "mimo-v2-omni", + "minimax-m2.7", + "minimax-m2.5", + ], + "ai-gateway": [ + "anthropic/claude-opus-4.6", + "anthropic/claude-sonnet-4.6", + "anthropic/claude-sonnet-4.5", + "anthropic/claude-haiku-4.5", + "openai/gpt-5", + "openai/gpt-4.1", + "openai/gpt-4.1-mini", + "google/gemini-3-pro-preview", + "google/gemini-3-flash", + "google/gemini-2.5-pro", + "google/gemini-2.5-flash", + "deepseek/deepseek-v3.2", + ], + "kilocode": [ + "anthropic/claude-opus-4.6", + "anthropic/claude-sonnet-4.6", + "openai/gpt-5.4", + "google/gemini-3-pro-preview", + "google/gemini-3-flash-preview", + ], + # Alibaba DashScope Coding platform (coding-intl) — default endpoint. + # Supports Qwen models + third-party providers (GLM, Kimi, MiniMax). + # Users with classic DashScope keys should override DASHSCOPE_BASE_URL + # to https://dashscope-intl.aliyuncs.com/compatible-mode/v1 (OpenAI-compat) + # or https://dashscope-intl.aliyuncs.com/apps/anthropic (Anthropic-compat). + "alibaba": [ + "qwen3.5-plus", + "qwen3-coder-plus", + "qwen3-coder-next", + # Third-party models available on coding-intl + "glm-5", + "glm-4.7", + "kimi-k2.5", + "MiniMax-M2.5", + ], + # Curated HF model list — only agentic models that map to OpenRouter defaults. + "huggingface": [ + "Qwen/Qwen3.5-397B-A17B", + "Qwen/Qwen3.5-35B-A3B", + "deepseek-ai/DeepSeek-V3.2", + "moonshotai/Kimi-K2.5", + "MiniMaxAI/MiniMax-M2.5", + "zai-org/GLM-5", + "XiaomiMiMo/MiMo-V2-Flash", + "moonshotai/Kimi-K2-Thinking", + ], +} + +# --------------------------------------------------------------------------- +# Nous Portal free-model filtering +# --------------------------------------------------------------------------- +# Models that are ALLOWED to appear when priced as free on Nous Portal. +# Any other free model is hidden — prevents promotional/temporary free models +# from cluttering the selection when users are paying subscribers. +# Models in this list are ALSO filtered out if they are NOT free (i.e. they +# should only appear in the menu when they are genuinely free). +_NOUS_ALLOWED_FREE_MODELS: frozenset[str] = frozenset({ + "xiaomi/mimo-v2-pro", + "xiaomi/mimo-v2-omni", +}) + + +def _is_model_free(model_id: str, pricing: dict[str, dict[str, str]]) -> bool: + """Return True if *model_id* has zero-cost prompt AND completion pricing.""" + p = pricing.get(model_id) + if not p: + return False + try: + return float(p.get("prompt", "1")) == 0 and float(p.get("completion", "1")) == 0 + except (TypeError, ValueError): + return False + + +def filter_nous_free_models( + model_ids: list[str], + pricing: dict[str, dict[str, str]], +) -> list[str]: + """Filter the Nous Portal model list according to free-model policy. + + Rules: + • Paid models that are NOT in the allowlist → keep (normal case). + • Free models that are NOT in the allowlist → drop. + • Allowlist models that ARE free → keep. + • Allowlist models that are NOT free → drop. + """ + if not pricing: + return model_ids # no pricing data — can't filter, show everything + + result: list[str] = [] + for mid in model_ids: + free = _is_model_free(mid, pricing) + if mid in _NOUS_ALLOWED_FREE_MODELS: + # Allowlist model: only show when it's actually free + if free: + result.append(mid) + else: + # Regular model: keep only when it's NOT free + if not free: + result.append(mid) + return result + + +# --------------------------------------------------------------------------- +# Nous Portal account tier detection +# --------------------------------------------------------------------------- + +def fetch_nous_account_tier(access_token: str, portal_base_url: str = "") -> dict[str, Any]: + """Fetch the user's Nous Portal account/subscription info. + + Calls ``/api/oauth/account`` with the OAuth access token. + + Returns the parsed JSON dict on success, e.g.:: + + { + "subscription": { + "plan": "Plus", + "tier": 2, + "monthly_charge": 20, + "credits_remaining": 1686.60, + ... + }, + ... + } + + Returns an empty dict on any failure (network, auth, parse). + """ + base = (portal_base_url or "https://portal.nousresearch.com").rstrip("/") + url = f"{base}/api/oauth/account" + headers = { + "Authorization": f"Bearer {access_token}", + "Accept": "application/json", + } + try: + req = urllib.request.Request(url, headers=headers) + with urllib.request.urlopen(req, timeout=8) as resp: + return json.loads(resp.read().decode()) + except Exception: + return {} + + +def is_nous_free_tier(account_info: dict[str, Any]) -> bool: + """Return True if the account info indicates a free (unpaid) tier. + + Checks ``subscription.monthly_charge == 0``. Returns False when + the field is missing or unparseable (assumes paid — don't block users). + """ + sub = account_info.get("subscription") + if not isinstance(sub, dict): + return False + charge = sub.get("monthly_charge") + if charge is None: + return False + try: + return float(charge) == 0 + except (TypeError, ValueError): + return False + + +def partition_nous_models_by_tier( + model_ids: list[str], + pricing: dict[str, dict[str, str]], + free_tier: bool, +) -> tuple[list[str], list[str]]: + """Split Nous models into (selectable, unavailable) based on user tier. + + For paid-tier users: all models are selectable, none unavailable + (free-model filtering is handled separately by ``filter_nous_free_models``). + + For free-tier users: only free models are selectable; paid models + are returned as unavailable (shown grayed out in the menu). + """ + if not free_tier: + return (model_ids, []) + + if not pricing: + return (model_ids, []) # can't determine, show everything + + selectable: list[str] = [] + unavailable: list[str] = [] + for mid in model_ids: + if _is_model_free(mid, pricing): + selectable.append(mid) + else: + unavailable.append(mid) + return (selectable, unavailable) + + +# --------------------------------------------------------------------------- +# TTL cache for free-tier detection — avoids repeated API calls within a +# session while still picking up upgrades quickly. +# --------------------------------------------------------------------------- +_FREE_TIER_CACHE_TTL: int = 180 # seconds (3 minutes) +_free_tier_cache: tuple[bool, float] | None = None # (result, timestamp) + + +def check_nous_free_tier() -> bool: + """Check if the current Nous Portal user is on a free (unpaid) tier. + + Results are cached for ``_FREE_TIER_CACHE_TTL`` seconds to avoid + hitting the Portal API on every call. The cache is short-lived so + that an account upgrade is reflected within a few minutes. + + Returns False (assume paid) on any error — never blocks paying users. + """ + global _free_tier_cache + import time + + now = time.monotonic() + if _free_tier_cache is not None: + cached_result, cached_at = _free_tier_cache + if now - cached_at < _FREE_TIER_CACHE_TTL: + return cached_result + + try: + from hermes_cli.auth import get_provider_auth_state, resolve_nous_runtime_credentials + + # Ensure we have a fresh token (triggers refresh if needed) + resolve_nous_runtime_credentials(min_key_ttl_seconds=60) + + state = get_provider_auth_state("nous") + if not state: + _free_tier_cache = (False, now) + return False + access_token = state.get("access_token", "") + portal_url = state.get("portal_base_url", "") + if not access_token: + _free_tier_cache = (False, now) + return False + + account_info = fetch_nous_account_tier(access_token, portal_url) + result = is_nous_free_tier(account_info) + _free_tier_cache = (result, now) + return result + except Exception: + _free_tier_cache = (False, now) + return False # default to paid on error — don't block users + + +# --------------------------------------------------------------------------- +# Canonical provider list — single source of truth for provider identity. +# Every code path that lists, displays, or iterates providers derives from +# this list: hermes model, /model, /provider, list_authenticated_providers. +# +# Fields: +# slug — internal provider ID (used in config.yaml, --provider flag) +# label — short display name +# tui_desc — longer description for the `hermes model` interactive picker +# --------------------------------------------------------------------------- + +class ProviderEntry(NamedTuple): + slug: str + label: str + tui_desc: str # detailed description for `hermes model` TUI + + +CANONICAL_PROVIDERS: list[ProviderEntry] = [ + ProviderEntry("nous", "Nous Portal", "Nous Portal (Nous Research subscription)"), + ProviderEntry("openrouter", "OpenRouter", "OpenRouter (100+ models, pay-per-use)"), + ProviderEntry("anthropic", "Anthropic", "Anthropic (Claude models — API key or Claude Code)"), + ProviderEntry("openai-codex", "OpenAI Codex", "OpenAI Codex"), + ProviderEntry("xiaomi", "Xiaomi MiMo", "Xiaomi MiMo (MiMo-V2 models — pro, omni, flash)"), + ProviderEntry("qwen-oauth", "Qwen OAuth (Portal)", "Qwen OAuth (reuses local Qwen CLI login)"), + ProviderEntry("copilot", "GitHub Copilot", "GitHub Copilot (uses GITHUB_TOKEN or gh auth token)"), + ProviderEntry("copilot-acp", "GitHub Copilot ACP", "GitHub Copilot ACP (spawns `copilot --acp --stdio`)"), + ProviderEntry("huggingface", "Hugging Face", "Hugging Face Inference Providers (20+ open models)"), + ProviderEntry("gemini", "Google AI Studio", "Google AI Studio (Gemini models — OpenAI-compatible endpoint)"), + ProviderEntry("deepseek", "DeepSeek", "DeepSeek (DeepSeek-V3, R1, coder — direct API)"), + ProviderEntry("xai", "xAI", "xAI (Grok models — direct API)"), + ProviderEntry("zai", "Z.AI / GLM", "Z.AI / GLM (Zhipu AI direct API)"), + ProviderEntry("kimi-coding", "Kimi / Moonshot", "Kimi / Moonshot (Moonshot AI direct API)"), + ProviderEntry("kimi-coding-cn", "Kimi / Moonshot (China)", "Kimi / Moonshot China (Moonshot CN direct API)"), + ProviderEntry("minimax", "MiniMax", "MiniMax (global direct API)"), + ProviderEntry("minimax-cn", "MiniMax (China)", "MiniMax China (domestic direct API)"), + ProviderEntry("alibaba", "Alibaba Cloud (DashScope)","Alibaba Cloud / DashScope Coding (Qwen + multi-provider)"), + ProviderEntry("arcee", "Arcee AI", "Arcee AI (Trinity models — direct API)"), + ProviderEntry("kilocode", "Kilo Code", "Kilo Code (Kilo Gateway API)"), + ProviderEntry("opencode-zen", "OpenCode Zen", "OpenCode Zen (35+ curated models, pay-as-you-go)"), + ProviderEntry("opencode-go", "OpenCode Go", "OpenCode Go (open models, $10/month subscription)"), + ProviderEntry("ai-gateway", "Vercel AI Gateway", "Vercel AI Gateway (200+ models, pay-per-use)"), +] + +# Derived dicts — used throughout the codebase +_PROVIDER_LABELS = {p.slug: p.label for p in CANONICAL_PROVIDERS} +_PROVIDER_LABELS["custom"] = "Custom endpoint" # special case: not a named provider + +_PROVIDER_ALIASES = { + "glm": "zai", + "z-ai": "zai", + "z.ai": "zai", + "zhipu": "zai", + "github": "copilot", + "github-copilot": "copilot", + "github-models": "copilot", + "github-model": "copilot", + "github-copilot-acp": "copilot-acp", + "copilot-acp-agent": "copilot-acp", + "google": "gemini", + "google-gemini": "gemini", + "google-ai-studio": "gemini", + "kimi": "kimi-coding", + "moonshot": "kimi-coding", + "kimi-cn": "kimi-coding-cn", + "moonshot-cn": "kimi-coding-cn", + "arcee-ai": "arcee", + "arceeai": "arcee", + "minimax-china": "minimax-cn", + "minimax_cn": "minimax-cn", + "claude": "anthropic", + "claude-code": "anthropic", + "deep-seek": "deepseek", + "opencode": "opencode-zen", + "zen": "opencode-zen", + "go": "opencode-go", + "opencode-go-sub": "opencode-go", + "aigateway": "ai-gateway", + "vercel": "ai-gateway", + "vercel-ai-gateway": "ai-gateway", + "kilo": "kilocode", + "kilo-code": "kilocode", + "kilo-gateway": "kilocode", + "dashscope": "alibaba", + "aliyun": "alibaba", + "qwen": "alibaba", + "alibaba-cloud": "alibaba", + "qwen-portal": "qwen-oauth", + "hf": "huggingface", + "hugging-face": "huggingface", + "huggingface-hub": "huggingface", + "mimo": "xiaomi", + "xiaomi-mimo": "xiaomi", + "grok": "xai", + "x-ai": "xai", + "x.ai": "xai", +} + + +def get_default_model_for_provider(provider: str) -> str: + """Return the default model for a provider, or empty string if unknown. + + Uses the first entry in _PROVIDER_MODELS as the default. This is the + model a user would be offered first in the ``hermes model`` picker. + + Used as a fallback when the user has configured a provider but never + selected a model (e.g. ``hermes auth add openai-codex`` without + ``hermes model``). + """ + models = _PROVIDER_MODELS.get(provider, []) + return models[0] if models else "" + + +def _openrouter_model_is_free(pricing: Any) -> bool: + """Return True when both prompt and completion pricing are zero.""" + if not isinstance(pricing, dict): + return False + try: + return float(pricing.get("prompt", "0")) == 0 and float(pricing.get("completion", "0")) == 0 + except (TypeError, ValueError): + return False + + +def fetch_openrouter_models( + timeout: float = 8.0, + *, + force_refresh: bool = False, +) -> list[tuple[str, str]]: + """Return the curated OpenRouter picker list, refreshed from the live catalog when possible.""" + global _openrouter_catalog_cache + + if _openrouter_catalog_cache is not None and not force_refresh: + return list(_openrouter_catalog_cache) + + fallback = list(OPENROUTER_MODELS) + preferred_ids = [mid for mid, _ in fallback] + + try: + req = urllib.request.Request( + "https://openrouter.ai/api/v1/models", + headers={"Accept": "application/json"}, + ) + with urllib.request.urlopen(req, timeout=timeout) as resp: + payload = json.loads(resp.read().decode()) + except Exception: + return list(_openrouter_catalog_cache or fallback) + + live_items = payload.get("data", []) + if not isinstance(live_items, list): + return list(_openrouter_catalog_cache or fallback) + + live_by_id: dict[str, dict[str, Any]] = {} + for item in live_items: + if not isinstance(item, dict): + continue + mid = str(item.get("id") or "").strip() + if not mid: + continue + live_by_id[mid] = item + + curated: list[tuple[str, str]] = [] + for preferred_id in preferred_ids: + live_item = live_by_id.get(preferred_id) + if live_item is None: + continue + desc = "free" if _openrouter_model_is_free(live_item.get("pricing")) else "" + curated.append((preferred_id, desc)) + + if not curated: + return list(_openrouter_catalog_cache or fallback) + + first_id, _ = curated[0] + curated[0] = (first_id, "recommended") + _openrouter_catalog_cache = curated + return list(curated) + + +def model_ids(*, force_refresh: bool = False) -> list[str]: + """Return just the OpenRouter model-id strings.""" + return [mid for mid, _ in fetch_openrouter_models(force_refresh=force_refresh)] + + + + +# --------------------------------------------------------------------------- +# Pricing helpers — fetch live pricing from OpenRouter-compatible /v1/models +# --------------------------------------------------------------------------- + +# Cache: maps model_id → {"prompt": str, "completion": str} per endpoint +_pricing_cache: dict[str, dict[str, dict[str, str]]] = {} + + +def _format_price_per_mtok(per_token_str: str) -> str: + """Convert a per-token price string to a human-friendly $/Mtok string. + + Always uses 2 decimal places so that prices align vertically when + right-justified in a column (the decimal point stays in the same position). + + Examples: + "0.000003" → "$3.00" (per million tokens) + "0.00003" → "$30.00" + "0.00000015" → "$0.15" + "0.0000001" → "$0.10" + "0.00018" → "$180.00" + "0" → "free" + """ + try: + val = float(per_token_str) + except (TypeError, ValueError): + return "?" + if val == 0: + return "free" + per_m = val * 1_000_000 + return f"${per_m:.2f}" + + +def format_model_pricing_table( + models: list[tuple[str, str]], + pricing_map: dict[str, dict[str, str]], + current_model: str = "", + indent: str = " ", +) -> list[str]: + """Build a column-aligned model+pricing table for terminal display. + + Returns a list of pre-formatted lines ready to print. + *models* is ``[(model_id, description), ...]``. + """ + if not models: + return [] + + # Build rows: (model_id, input_price, output_price, cache_price, is_current) + rows: list[tuple[str, str, str, str, bool]] = [] + has_cache = False + for mid, _desc in models: + is_cur = mid == current_model + p = pricing_map.get(mid) + if p: + inp = _format_price_per_mtok(p.get("prompt", "")) + out = _format_price_per_mtok(p.get("completion", "")) + cache_read = p.get("input_cache_read", "") + cache = _format_price_per_mtok(cache_read) if cache_read else "" + if cache: + has_cache = True + else: + inp, out, cache = "", "", "" + rows.append((mid, inp, out, cache, is_cur)) + + name_col = max(len(r[0]) for r in rows) + 2 + # Compute price column widths from the actual data so decimals align + price_col = max( + max((len(r[1]) for r in rows if r[1]), default=4), + max((len(r[2]) for r in rows if r[2]), default=4), + 3, # minimum: "In" / "Out" header + ) + cache_col = max( + max((len(r[3]) for r in rows if r[3]), default=4), + 5, # minimum: "Cache" header + ) if has_cache else 0 + lines: list[str] = [] + + # Header + if has_cache: + lines.append(f"{indent}{'Model':<{name_col}} {'In':>{price_col}} {'Out':>{price_col}} {'Cache':>{cache_col}} /Mtok") + lines.append(f"{indent}{'-' * name_col} {'-' * price_col} {'-' * price_col} {'-' * cache_col}") + else: + lines.append(f"{indent}{'Model':<{name_col}} {'In':>{price_col}} {'Out':>{price_col}} /Mtok") + lines.append(f"{indent}{'-' * name_col} {'-' * price_col} {'-' * price_col}") + + for mid, inp, out, cache, is_cur in rows: + marker = " ← current" if is_cur else "" + if has_cache: + lines.append(f"{indent}{mid:<{name_col}} {inp:>{price_col}} {out:>{price_col}} {cache:>{cache_col}}{marker}") + else: + lines.append(f"{indent}{mid:<{name_col}} {inp:>{price_col}} {out:>{price_col}}{marker}") + + return lines + + +def fetch_models_with_pricing( + api_key: str | None = None, + base_url: str = "https://openrouter.ai/api", + timeout: float = 8.0, + *, + force_refresh: bool = False, +) -> dict[str, dict[str, str]]: + """Fetch ``/v1/models`` and return ``{model_id: {prompt, completion}}`` pricing. + + Results are cached per *base_url* so repeated calls are free. + Works with any OpenRouter-compatible endpoint (OpenRouter, Nous Portal). + """ + cache_key = (base_url or "").rstrip("/") + if not force_refresh and cache_key in _pricing_cache: + return _pricing_cache[cache_key] + + url = cache_key.rstrip("/") + "/v1/models" + headers: dict[str, str] = {"Accept": "application/json"} + if api_key: + headers["Authorization"] = f"Bearer {api_key}" + + try: + req = urllib.request.Request(url, headers=headers) + with urllib.request.urlopen(req, timeout=timeout) as resp: + payload = json.loads(resp.read().decode()) + except Exception: + _pricing_cache[cache_key] = {} + return {} + + result: dict[str, dict[str, str]] = {} + for item in payload.get("data", []): + mid = item.get("id") + pricing = item.get("pricing") + if mid and isinstance(pricing, dict): + entry: dict[str, str] = { + "prompt": str(pricing.get("prompt", "")), + "completion": str(pricing.get("completion", "")), + } + if pricing.get("input_cache_read"): + entry["input_cache_read"] = str(pricing["input_cache_read"]) + if pricing.get("input_cache_write"): + entry["input_cache_write"] = str(pricing["input_cache_write"]) + result[mid] = entry + + _pricing_cache[cache_key] = result + return result + + +def _resolve_openrouter_api_key() -> str: + """Best-effort OpenRouter API key for pricing fetch.""" + return os.getenv("OPENROUTER_API_KEY", "").strip() + + +def _resolve_nous_pricing_credentials() -> tuple[str, str]: + """Return ``(api_key, base_url)`` for Nous Portal pricing, or empty strings.""" + try: + from hermes_cli.auth import resolve_nous_runtime_credentials + creds = resolve_nous_runtime_credentials() + if creds: + return (creds.get("api_key", ""), creds.get("base_url", "")) + except Exception: + pass + return ("", "") + + +def get_pricing_for_provider(provider: str, *, force_refresh: bool = False) -> dict[str, dict[str, str]]: + """Return live pricing for providers that support it (openrouter, nous).""" + normalized = normalize_provider(provider) + if normalized == "openrouter": + return fetch_models_with_pricing( + api_key=_resolve_openrouter_api_key(), + base_url="https://openrouter.ai/api", + force_refresh=force_refresh, + ) + if normalized == "nous": + api_key, base_url = _resolve_nous_pricing_credentials() + if base_url: + # Nous base_url typically looks like https://inference-api.nousresearch.com/v1 + # We need the part before /v1 for our fetch function + stripped = base_url.rstrip("/") + if stripped.endswith("/v1"): + stripped = stripped[:-3] + return fetch_models_with_pricing( + api_key=api_key, + base_url=stripped, + force_refresh=force_refresh, + ) + return {} + + +# All provider IDs and aliases that are valid for the provider:model syntax. +_KNOWN_PROVIDER_NAMES: set[str] = ( + set(_PROVIDER_LABELS.keys()) + | set(_PROVIDER_ALIASES.keys()) + | {"openrouter", "custom"} +) + + +def list_available_providers() -> list[dict[str, str]]: + """Return info about all providers the user could use with ``provider:model``. + + Each dict has ``id``, ``label``, and ``aliases``. + Checks which providers have valid credentials configured. + + Derives the provider list from :data:`CANONICAL_PROVIDERS` (single + source of truth shared with ``hermes model``, ``/model``, etc.). + """ + # Derive display order from canonical list + custom + provider_order = [p.slug for p in CANONICAL_PROVIDERS] + ["custom"] + + # Build reverse alias map + aliases_for: dict[str, list[str]] = {} + for alias, canonical in _PROVIDER_ALIASES.items(): + aliases_for.setdefault(canonical, []).append(alias) + + result = [] + for pid in provider_order: + label = _PROVIDER_LABELS.get(pid, pid) + alias_list = aliases_for.get(pid, []) + # Check if this provider has credentials available + has_creds = False + try: + from hermes_cli.auth import get_auth_status, has_usable_secret + if pid == "custom": + custom_base_url = _get_custom_base_url() or "" + has_creds = bool(custom_base_url.strip()) + elif pid == "openrouter": + has_creds = has_usable_secret(os.getenv("OPENROUTER_API_KEY", "")) + else: + status = get_auth_status(pid) + has_creds = bool(status.get("logged_in") or status.get("configured")) + except Exception: + pass + result.append({ + "id": pid, + "label": label, + "aliases": alias_list, + "authenticated": has_creds, + }) + return result + + +def parse_model_input(raw: str, current_provider: str) -> tuple[str, str]: + """Parse ``/model`` input into ``(provider, model)``. + + Supports ``provider:model`` syntax to switch providers at runtime:: + + openrouter:anthropic/claude-sonnet-4.5 → ("openrouter", "anthropic/claude-sonnet-4.5") + nous:hermes-3 → ("nous", "hermes-3") + anthropic/claude-sonnet-4.5 → (current_provider, "anthropic/claude-sonnet-4.5") + gpt-5.4 → (current_provider, "gpt-5.4") + + The colon is only treated as a provider delimiter if the left side is a + recognized provider name or alias. This avoids misinterpreting model names + that happen to contain colons (e.g. ``anthropic/claude-3.5-sonnet:beta``). + + Returns ``(provider, model)`` where *provider* is either the explicit + provider from the input or *current_provider* if none was specified. + """ + stripped = raw.strip() + colon = stripped.find(":") + if colon > 0: + provider_part = stripped[:colon].strip().lower() + model_part = stripped[colon + 1:].strip() + if provider_part and model_part and provider_part in _KNOWN_PROVIDER_NAMES: + # Support custom:name:model triple syntax for named custom + # providers. ``custom:local:qwen`` → ("custom:local", "qwen"). + # Single colon ``custom:qwen`` → ("custom", "qwen") as before. + if provider_part == "custom" and ":" in model_part: + second_colon = model_part.find(":") + custom_name = model_part[:second_colon].strip() + actual_model = model_part[second_colon + 1:].strip() + if custom_name and actual_model: + return (f"custom:{custom_name}", actual_model) + return (normalize_provider(provider_part), model_part) + return (current_provider, stripped) + + +def _get_custom_base_url() -> str: + """Get the custom endpoint base_url from config.yaml.""" + try: + from hermes_cli.config import load_config + config = load_config() + model_cfg = config.get("model", {}) + if isinstance(model_cfg, dict): + return str(model_cfg.get("base_url", "")).strip() + except Exception: + pass + return "" + + +def curated_models_for_provider( + provider: Optional[str], + *, + force_refresh: bool = False, +) -> list[tuple[str, str]]: + """Return ``(model_id, description)`` tuples for a provider's model list. + + Tries to fetch the live model list from the provider's API first, + falling back to the static ``_PROVIDER_MODELS`` catalog if the API + is unreachable. + """ + normalized = normalize_provider(provider) + if normalized == "openrouter": + return fetch_openrouter_models(force_refresh=force_refresh) + + # Try live API first (Codex, Nous, etc. all support /models) + live = provider_model_ids(normalized) + if live: + return [(m, "") for m in live] + + # Fallback to static catalog + models = _PROVIDER_MODELS.get(normalized, []) + return [(m, "") for m in models] + + +def detect_provider_for_model( + model_name: str, + current_provider: str, +) -> Optional[tuple[str, str]]: + """Auto-detect the best provider for a model name. + + Returns ``(provider_id, model_name)`` — the model name may be remapped + (e.g. bare ``deepseek-chat`` → ``deepseek/deepseek-chat`` for OpenRouter). + Returns ``None`` when no confident match is found. + + Priority: + 0. Bare provider name → switch to that provider's default model + 1. Direct provider with credentials (highest) + 2. Direct provider without credentials → remap to OpenRouter slug + 3. OpenRouter catalog match + """ + name = (model_name or "").strip() + if not name: + return None + + name_lower = name.lower() + + # --- Step 0: bare provider name typed as model --- + # If someone types `/model nous` or `/model anthropic`, treat it as a + # provider switch and pick the first model from that provider's catalog. + # Skip "custom" and "openrouter" — custom has no model catalog, and + # openrouter requires an explicit model name to be useful. + resolved_provider = _PROVIDER_ALIASES.get(name_lower, name_lower) + if resolved_provider not in {"custom", "openrouter"}: + default_models = _PROVIDER_MODELS.get(resolved_provider, []) + if ( + resolved_provider in _PROVIDER_LABELS + and default_models + and resolved_provider != normalize_provider(current_provider) + ): + return (resolved_provider, default_models[0]) + + # Aggregators list other providers' models — never auto-switch TO them + _AGGREGATORS = {"nous", "openrouter"} + + # If the model belongs to the current provider's catalog, don't suggest switching + current_models = _PROVIDER_MODELS.get(current_provider, []) + if any(name_lower == m.lower() for m in current_models): + return None + + # --- Step 1: check static provider catalogs for a direct match --- + direct_match: Optional[str] = None + for pid, models in _PROVIDER_MODELS.items(): + if pid == current_provider or pid in _AGGREGATORS: + continue + if any(name_lower == m.lower() for m in models): + direct_match = pid + break + + if direct_match: + # Check if we have credentials for this provider + has_creds = False + try: + from hermes_cli.auth import PROVIDER_REGISTRY + pconfig = PROVIDER_REGISTRY.get(direct_match) + if pconfig: + import os + for env_var in pconfig.api_key_env_vars: + if os.getenv(env_var, "").strip(): + has_creds = True + break + except Exception: + pass + + if has_creds: + return (direct_match, name) + + # No direct creds — try to find this model on OpenRouter instead + or_slug = _find_openrouter_slug(name) + if or_slug: + return ("openrouter", or_slug) + # Still return the direct provider — credential resolution will + # give a clear error rather than silently using the wrong provider + return (direct_match, name) + + # --- Step 2: check OpenRouter catalog --- + # First try exact match (handles provider/model format) + or_slug = _find_openrouter_slug(name) + if or_slug: + if current_provider != "openrouter": + return ("openrouter", or_slug) + # Already on openrouter, just return the resolved slug + if or_slug != name: + return ("openrouter", or_slug) + return None # already on openrouter with matching name + + return None + + +def _find_openrouter_slug(model_name: str) -> Optional[str]: + """Find the full OpenRouter model slug for a bare or partial model name. + + Handles: + - Exact match: ``anthropic/claude-opus-4.6`` → as-is + - Bare name: ``deepseek-chat`` → ``deepseek/deepseek-chat`` + - Bare name: ``claude-opus-4.6`` → ``anthropic/claude-opus-4.6`` + """ + name_lower = model_name.strip().lower() + if not name_lower: + return None + + # Exact match (already has provider/ prefix) + for mid in model_ids(): + if name_lower == mid.lower(): + return mid + + # Try matching just the model part (after the /) + for mid in model_ids(): + if "/" in mid: + _, model_part = mid.split("/", 1) + if name_lower == model_part.lower(): + return mid + + return None + + +def normalize_provider(provider: Optional[str]) -> str: + """Normalize provider aliases to Hermes' canonical provider ids. + + Note: ``"auto"`` passes through unchanged — use + ``hermes_cli.auth.resolve_provider()`` to resolve it to a concrete + provider based on credentials and environment. + """ + normalized = (provider or "openrouter").strip().lower() + return _PROVIDER_ALIASES.get(normalized, normalized) + + +def provider_label(provider: Optional[str]) -> str: + """Return a human-friendly label for a provider id or alias.""" + original = (provider or "openrouter").strip() + normalized = original.lower() + if normalized == "auto": + return "Auto" + normalized = normalize_provider(normalized) + return _PROVIDER_LABELS.get(normalized, original or "OpenRouter") + + +# Models that support OpenAI Priority Processing (service_tier="priority"). +# See https://openai.com/api-priority-processing/ for the canonical list. +# Only the bare model slug is stored (no vendor prefix). +_PRIORITY_PROCESSING_MODELS: frozenset[str] = frozenset({ + "gpt-5.4", + "gpt-5.4-mini", + "gpt-5.2", + "gpt-5.1", + "gpt-5", + "gpt-5-mini", + "gpt-4.1", + "gpt-4.1-mini", + "gpt-4.1-nano", + "gpt-4o", + "gpt-4o-mini", + "o3", + "o4-mini", +}) + +# Models that support Anthropic Fast Mode (speed="fast"). +# See https://platform.claude.com/docs/en/build-with-claude/fast-mode +# Currently only Claude Opus 4.6. Both hyphen and dot variants are stored +# to handle native Anthropic (claude-opus-4-6) and OpenRouter (claude-opus-4.6). +_ANTHROPIC_FAST_MODE_MODELS: frozenset[str] = frozenset({ + "claude-opus-4-6", + "claude-opus-4.6", +}) + + +def _strip_vendor_prefix(model_id: str) -> str: + """Strip vendor/ prefix from a model ID (e.g. 'anthropic/claude-opus-4-6' -> 'claude-opus-4-6').""" + raw = str(model_id or "").strip().lower() + if "/" in raw: + raw = raw.split("/", 1)[1] + return raw + + +def model_supports_fast_mode(model_id: Optional[str]) -> bool: + """Return whether Hermes should expose the /fast toggle for this model.""" + raw = _strip_vendor_prefix(str(model_id or "")) + if raw in _PRIORITY_PROCESSING_MODELS: + return True + # Anthropic fast mode — strip date suffixes (e.g. claude-opus-4-6-20260401) + # and OpenRouter variant tags (:fast, :beta) for matching. + base = raw.split(":")[0] + return base in _ANTHROPIC_FAST_MODE_MODELS + + +def _is_anthropic_fast_model(model_id: Optional[str]) -> bool: + """Return True if the model supports Anthropic's fast mode (speed='fast').""" + raw = _strip_vendor_prefix(str(model_id or "")) + base = raw.split(":")[0] + return base in _ANTHROPIC_FAST_MODE_MODELS + + +def resolve_fast_mode_overrides(model_id: Optional[str]) -> dict[str, Any] | None: + """Return request_overrides for fast/priority mode, or None if unsupported. + + Returns provider-appropriate overrides: + - OpenAI models: ``{"service_tier": "priority"}`` (Priority Processing) + - Anthropic models: ``{"speed": "fast"}`` (Anthropic Fast Mode beta) + + The overrides are injected into the API request kwargs by + ``_build_api_kwargs`` in run_agent.py — each API path handles its own + keys (service_tier for OpenAI/Codex, speed for Anthropic Messages). + """ + if not model_supports_fast_mode(model_id): + return None + if _is_anthropic_fast_model(model_id): + return {"speed": "fast"} + return {"service_tier": "priority"} + + +def _resolve_copilot_catalog_api_key() -> str: + """Best-effort GitHub token for fetching the Copilot model catalog.""" + try: + from hermes_cli.auth import resolve_api_key_provider_credentials + + creds = resolve_api_key_provider_credentials("copilot") + return str(creds.get("api_key") or "").strip() + except Exception: + return "" + + +def provider_model_ids(provider: Optional[str], *, force_refresh: bool = False) -> list[str]: + """Return the best known model catalog for a provider. + + Tries live API endpoints for providers that support them (Codex, Nous), + falling back to static lists. + """ + normalized = normalize_provider(provider) + if normalized == "openrouter": + return model_ids(force_refresh=force_refresh) + if normalized == "openai-codex": + from hermes_cli.codex_models import get_codex_model_ids + + return get_codex_model_ids() + if normalized in {"copilot", "copilot-acp"}: + try: + live = _fetch_github_models(_resolve_copilot_catalog_api_key()) + if live: + return live + except Exception: + pass + if normalized == "copilot-acp": + return list(_PROVIDER_MODELS.get("copilot", [])) + if normalized == "nous": + # Try live Nous Portal /models endpoint + try: + from hermes_cli.auth import fetch_nous_models, resolve_nous_runtime_credentials + creds = resolve_nous_runtime_credentials() + if creds: + live = fetch_nous_models(api_key=creds.get("api_key", ""), inference_base_url=creds.get("base_url", "")) + if live: + return live + except Exception: + pass + if normalized == "anthropic": + live = _fetch_anthropic_models() + if live: + return live + if normalized == "ai-gateway": + live = _fetch_ai_gateway_models() + if live: + return live + if normalized == "custom": + base_url = _get_custom_base_url() + if base_url: + # Try common API key env vars for custom endpoints + api_key = ( + os.getenv("CUSTOM_API_KEY", "") + or os.getenv("OPENAI_API_KEY", "") + or os.getenv("OPENROUTER_API_KEY", "") + ) + live = fetch_api_models(api_key, base_url) + if live: + return live + return list(_PROVIDER_MODELS.get(normalized, [])) + + +def _fetch_anthropic_models(timeout: float = 5.0) -> Optional[list[str]]: + """Fetch available models from the Anthropic /v1/models endpoint. + + Uses resolve_anthropic_token() to find credentials (env vars or + Claude Code auto-discovery). Returns sorted model IDs or None. + """ + try: + from agent.anthropic_adapter import resolve_anthropic_token, _is_oauth_token + except ImportError: + return None + + token = resolve_anthropic_token() + if not token: + return None + + headers: dict[str, str] = {"anthropic-version": "2023-06-01"} + if _is_oauth_token(token): + headers["Authorization"] = f"Bearer {token}" + from agent.anthropic_adapter import _COMMON_BETAS, _OAUTH_ONLY_BETAS + headers["anthropic-beta"] = ",".join(_COMMON_BETAS + _OAUTH_ONLY_BETAS) + else: + headers["x-api-key"] = token + + req = urllib.request.Request( + "https://api.anthropic.com/v1/models", + headers=headers, + ) + try: + with urllib.request.urlopen(req, timeout=timeout) as resp: + data = json.loads(resp.read().decode()) + models = [m["id"] for m in data.get("data", []) if m.get("id")] + # Sort: latest/largest first (opus > sonnet > haiku, higher version first) + return sorted(models, key=lambda m: ( + "opus" not in m, # opus first + "sonnet" not in m, # then sonnet + "haiku" not in m, # then haiku + m, # alphabetical within tier + )) + except Exception as e: + import logging + logging.getLogger(__name__).debug("Failed to fetch Anthropic models: %s", e) + return None + + +def _payload_items(payload: Any) -> list[dict[str, Any]]: + if isinstance(payload, list): + return [item for item in payload if isinstance(item, dict)] + if isinstance(payload, dict): + data = payload.get("data", []) + if isinstance(data, list): + return [item for item in data if isinstance(item, dict)] + return [] + + +def copilot_default_headers() -> dict[str, str]: + """Standard headers for Copilot API requests. + + Includes Openai-Intent and x-initiator headers that opencode and the + Copilot CLI send on every request. + """ + try: + from hermes_cli.copilot_auth import copilot_request_headers + return copilot_request_headers(is_agent_turn=True) + except ImportError: + return { + "Editor-Version": COPILOT_EDITOR_VERSION, + "User-Agent": "HermesAgent/1.0", + "Openai-Intent": "conversation-edits", + "x-initiator": "agent", + } + + +def _copilot_catalog_item_is_text_model(item: dict[str, Any]) -> bool: + model_id = str(item.get("id") or "").strip() + if not model_id: + return False + + if item.get("model_picker_enabled") is False: + return False + + capabilities = item.get("capabilities") + if isinstance(capabilities, dict): + model_type = str(capabilities.get("type") or "").strip().lower() + if model_type and model_type != "chat": + return False + + supported_endpoints = item.get("supported_endpoints") + if isinstance(supported_endpoints, list): + normalized_endpoints = { + str(endpoint).strip() + for endpoint in supported_endpoints + if str(endpoint).strip() + } + if normalized_endpoints and not normalized_endpoints.intersection( + {"/chat/completions", "/responses", "/v1/messages"} + ): + return False + + return True + + +def fetch_github_model_catalog( + api_key: Optional[str] = None, timeout: float = 5.0 +) -> Optional[list[dict[str, Any]]]: + """Fetch the live GitHub Copilot model catalog for this account.""" + attempts: list[dict[str, str]] = [] + if api_key: + attempts.append({ + **copilot_default_headers(), + "Authorization": f"Bearer {api_key}", + }) + attempts.append(copilot_default_headers()) + + for headers in attempts: + req = urllib.request.Request(COPILOT_MODELS_URL, headers=headers) + try: + with urllib.request.urlopen(req, timeout=timeout) as resp: + data = json.loads(resp.read().decode()) + items = _payload_items(data) + models: list[dict[str, Any]] = [] + seen_ids: set[str] = set() + for item in items: + if not _copilot_catalog_item_is_text_model(item): + continue + model_id = str(item.get("id") or "").strip() + if not model_id or model_id in seen_ids: + continue + seen_ids.add(model_id) + models.append(item) + if models: + return models + except Exception: + continue + return None + + +def _is_github_models_base_url(base_url: Optional[str]) -> bool: + normalized = (base_url or "").strip().rstrip("/").lower() + return ( + normalized.startswith(COPILOT_BASE_URL) + or normalized.startswith("https://models.github.ai/inference") + ) + + +def _fetch_github_models(api_key: Optional[str] = None, timeout: float = 5.0) -> Optional[list[str]]: + catalog = fetch_github_model_catalog(api_key=api_key, timeout=timeout) + if not catalog: + return None + return [item.get("id", "") for item in catalog if item.get("id")] + + +_COPILOT_MODEL_ALIASES = { + "openai/gpt-5": "gpt-5-mini", + "openai/gpt-5-chat": "gpt-5-mini", + "openai/gpt-5-mini": "gpt-5-mini", + "openai/gpt-5-nano": "gpt-5-mini", + "openai/gpt-4.1": "gpt-4.1", + "openai/gpt-4.1-mini": "gpt-4.1", + "openai/gpt-4.1-nano": "gpt-4.1", + "openai/gpt-4o": "gpt-4o", + "openai/gpt-4o-mini": "gpt-4o-mini", + "openai/o1": "gpt-5.2", + "openai/o1-mini": "gpt-5-mini", + "openai/o1-preview": "gpt-5.2", + "openai/o3": "gpt-5.3-codex", + "openai/o3-mini": "gpt-5-mini", + "openai/o4-mini": "gpt-5-mini", + "anthropic/claude-opus-4.6": "claude-opus-4.6", + "anthropic/claude-sonnet-4.6": "claude-sonnet-4.6", + "anthropic/claude-sonnet-4.5": "claude-sonnet-4.5", + "anthropic/claude-haiku-4.5": "claude-haiku-4.5", +} + + +def _copilot_catalog_ids( + catalog: Optional[list[dict[str, Any]]] = None, + api_key: Optional[str] = None, +) -> set[str]: + if catalog is None and api_key: + catalog = fetch_github_model_catalog(api_key=api_key) + if not catalog: + return set() + return { + str(item.get("id") or "").strip() + for item in catalog + if str(item.get("id") or "").strip() + } + + +def normalize_copilot_model_id( + model_id: Optional[str], + *, + catalog: Optional[list[dict[str, Any]]] = None, + api_key: Optional[str] = None, +) -> str: + raw = str(model_id or "").strip() + if not raw: + return "" + + catalog_ids = _copilot_catalog_ids(catalog=catalog, api_key=api_key) + alias = _COPILOT_MODEL_ALIASES.get(raw) + if alias: + return alias + + candidates = [raw] + if "/" in raw: + candidates.append(raw.split("/", 1)[1].strip()) + + if raw.endswith("-mini"): + candidates.append(raw[:-5]) + if raw.endswith("-nano"): + candidates.append(raw[:-5]) + if raw.endswith("-chat"): + candidates.append(raw[:-5]) + + seen: set[str] = set() + for candidate in candidates: + if not candidate or candidate in seen: + continue + seen.add(candidate) + if candidate in _COPILOT_MODEL_ALIASES: + return _COPILOT_MODEL_ALIASES[candidate] + if candidate in catalog_ids: + return candidate + + if "/" in raw: + return raw.split("/", 1)[1].strip() + return raw + + +def _github_reasoning_efforts_for_model_id(model_id: str) -> list[str]: + raw = (model_id or "").strip().lower() + if raw.startswith(("openai/o1", "openai/o3", "openai/o4", "o1", "o3", "o4")): + return list(COPILOT_REASONING_EFFORTS_O_SERIES) + normalized = normalize_copilot_model_id(model_id).lower() + if normalized.startswith("gpt-5"): + return list(COPILOT_REASONING_EFFORTS_GPT5) + return [] + + +def _should_use_copilot_responses_api(model_id: str) -> bool: + """Decide whether a Copilot model should use the Responses API. + + Replicates opencode's ``shouldUseCopilotResponsesApi`` logic: + GPT-5+ models use Responses API, except ``gpt-5-mini`` which uses + Chat Completions. All non-GPT models (Claude, Gemini, etc.) use + Chat Completions. + """ + import re + + match = re.match(r"^gpt-(\d+)", model_id) + if not match: + return False + major = int(match.group(1)) + return major >= 5 and not model_id.startswith("gpt-5-mini") + + +def copilot_model_api_mode( + model_id: Optional[str], + *, + catalog: Optional[list[dict[str, Any]]] = None, + api_key: Optional[str] = None, +) -> str: + """Determine the API mode for a Copilot model. + + Uses the model ID pattern (matching opencode's approach) as the + primary signal. Falls back to the catalog's ``supported_endpoints`` + only for models not covered by the pattern check. + """ + normalized = normalize_copilot_model_id(model_id, catalog=catalog, api_key=api_key) + if not normalized: + return "chat_completions" + + # Primary: model ID pattern (matches opencode's shouldUseCopilotResponsesApi) + if _should_use_copilot_responses_api(normalized): + return "codex_responses" + + # Secondary: check catalog for non-GPT-5 models (Claude via /v1/messages, etc.) + if catalog is None and api_key: + catalog = fetch_github_model_catalog(api_key=api_key) + + if catalog: + catalog_entry = next((item for item in catalog if item.get("id") == normalized), None) + if isinstance(catalog_entry, dict): + supported_endpoints = { + str(endpoint).strip() + for endpoint in (catalog_entry.get("supported_endpoints") or []) + if str(endpoint).strip() + } + # For non-GPT-5 models, check if they only support messages API + if "/v1/messages" in supported_endpoints and "/chat/completions" not in supported_endpoints: + return "anthropic_messages" + + return "chat_completions" + + +def normalize_opencode_model_id(provider_id: Optional[str], model_id: Optional[str]) -> str: + """Normalize OpenCode config IDs to the bare model slug used in API requests.""" + provider = normalize_provider(provider_id) + current = str(model_id or "").strip() + if not current or provider not in {"opencode-zen", "opencode-go"}: + return current + + prefix = f"{provider}/" + if current.lower().startswith(prefix): + return current[len(prefix):] + return current + + +def opencode_model_api_mode(provider_id: Optional[str], model_id: Optional[str]) -> str: + """Determine the API mode for an OpenCode Zen / Go model. + + OpenCode routes different models behind different API surfaces: + + - GPT-5 / Codex models on Zen use ``/v1/responses`` + - Claude models on Zen use ``/v1/messages`` + - MiniMax models on Go use ``/v1/messages`` + - GLM / Kimi on Go use ``/v1/chat/completions`` + - Other Zen models (Gemini, GLM, Kimi, MiniMax, Qwen, etc.) use + ``/v1/chat/completions`` + + This follows the published OpenCode docs for Zen and Go endpoints. + """ + provider = normalize_provider(provider_id) + normalized = normalize_opencode_model_id(provider_id, model_id).lower() + if not normalized: + return "chat_completions" + + if provider == "opencode-go": + if normalized.startswith("minimax-"): + return "anthropic_messages" + return "chat_completions" + + if provider == "opencode-zen": + if normalized.startswith("claude-"): + return "anthropic_messages" + if normalized.startswith("gpt-"): + return "codex_responses" + return "chat_completions" + + return "chat_completions" + + +def github_model_reasoning_efforts( + model_id: Optional[str], + *, + catalog: Optional[list[dict[str, Any]]] = None, + api_key: Optional[str] = None, +) -> list[str]: + """Return supported reasoning-effort levels for a Copilot-visible model.""" + normalized = normalize_copilot_model_id(model_id, catalog=catalog, api_key=api_key) + if not normalized: + return [] + + catalog_entry = None + if catalog is not None: + catalog_entry = next((item for item in catalog if item.get("id") == normalized), None) + elif api_key: + fetched_catalog = fetch_github_model_catalog(api_key=api_key) + if fetched_catalog: + catalog_entry = next((item for item in fetched_catalog if item.get("id") == normalized), None) + + if catalog_entry is not None: + capabilities = catalog_entry.get("capabilities") + if isinstance(capabilities, dict): + supports = capabilities.get("supports") + if isinstance(supports, dict): + efforts = supports.get("reasoning_effort") + if isinstance(efforts, list): + normalized_efforts = [ + str(effort).strip().lower() + for effort in efforts + if str(effort).strip() + ] + return list(dict.fromkeys(normalized_efforts)) + return [] + legacy_capabilities = { + str(capability).strip().lower() + for capability in catalog_entry.get("capabilities", []) + if str(capability).strip() + } + if "reasoning" not in legacy_capabilities: + return [] + + return _github_reasoning_efforts_for_model_id(str(model_id or normalized)) + + +def probe_api_models( + api_key: Optional[str], + base_url: Optional[str], + timeout: float = 5.0, +) -> dict[str, Any]: + """Probe an OpenAI-compatible ``/models`` endpoint with light URL heuristics.""" + normalized = (base_url or "").strip().rstrip("/") + if not normalized: + return { + "models": None, + "probed_url": None, + "resolved_base_url": "", + "suggested_base_url": None, + "used_fallback": False, + } + + if _is_github_models_base_url(normalized): + models = _fetch_github_models(api_key=api_key, timeout=timeout) + return { + "models": models, + "probed_url": COPILOT_MODELS_URL, + "resolved_base_url": COPILOT_BASE_URL, + "suggested_base_url": None, + "used_fallback": False, + } + + if normalized.endswith("/v1"): + alternate_base = normalized[:-3].rstrip("/") + else: + alternate_base = normalized + "/v1" + + candidates: list[tuple[str, bool]] = [(normalized, False)] + if alternate_base and alternate_base != normalized: + candidates.append((alternate_base, True)) + + tried: list[str] = [] + headers: dict[str, str] = {} + if api_key: + headers["Authorization"] = f"Bearer {api_key}" + if normalized.startswith(COPILOT_BASE_URL): + headers.update(copilot_default_headers()) + + for candidate_base, is_fallback in candidates: + url = candidate_base.rstrip("/") + "/models" + tried.append(url) + req = urllib.request.Request(url, headers=headers) + try: + with urllib.request.urlopen(req, timeout=timeout) as resp: + data = json.loads(resp.read().decode()) + return { + "models": [m.get("id", "") for m in data.get("data", [])], + "probed_url": url, + "resolved_base_url": candidate_base.rstrip("/"), + "suggested_base_url": alternate_base if alternate_base != candidate_base else normalized, + "used_fallback": is_fallback, + } + except Exception: + continue + + return { + "models": None, + "probed_url": tried[0] if tried else normalized.rstrip("/") + "/models", + "resolved_base_url": normalized, + "suggested_base_url": alternate_base if alternate_base != normalized else None, + "used_fallback": False, + } + + +def _fetch_ai_gateway_models(timeout: float = 5.0) -> Optional[list[str]]: + """Fetch available language models with tool-use from AI Gateway.""" + api_key = os.getenv("AI_GATEWAY_API_KEY", "").strip() + if not api_key: + return None + base_url = os.getenv("AI_GATEWAY_BASE_URL", "").strip() + if not base_url: + from hermes_constants import AI_GATEWAY_BASE_URL + base_url = AI_GATEWAY_BASE_URL + + url = base_url.rstrip("/") + "/models" + headers: dict[str, str] = {"Authorization": f"Bearer {api_key}"} + req = urllib.request.Request(url, headers=headers) + try: + with urllib.request.urlopen(req, timeout=timeout) as resp: + data = json.loads(resp.read().decode()) + return [ + m["id"] + for m in data.get("data", []) + if m.get("id") + and m.get("type") == "language" + and "tool-use" in (m.get("tags") or []) + ] + except Exception: + return None + + +def fetch_api_models( + api_key: Optional[str], + base_url: Optional[str], + timeout: float = 5.0, +) -> Optional[list[str]]: + """Fetch the list of available model IDs from the provider's ``/models`` endpoint. + + Returns a list of model ID strings, or ``None`` if the endpoint could not + be reached (network error, timeout, auth failure, etc.). + """ + return probe_api_models(api_key, base_url, timeout=timeout).get("models") + + +def validate_requested_model( + model_name: str, + provider: Optional[str], + *, + api_key: Optional[str] = None, + base_url: Optional[str] = None, +) -> dict[str, Any]: + """ + Validate a ``/model`` value for the active provider. + + Performs format checks first, then probes the live API to confirm + the model actually exists. + + Returns a dict with: + - accepted: whether the CLI should switch to the requested model now + - persist: whether it is safe to save to config + - recognized: whether it matched a known provider catalog + - message: optional warning / guidance for the user + """ + requested = (model_name or "").strip() + normalized = normalize_provider(provider) + if normalized == "openrouter" and base_url and "openrouter.ai" not in base_url: + normalized = "custom" + requested_for_lookup = requested + if normalized == "copilot": + requested_for_lookup = normalize_copilot_model_id( + requested, + api_key=api_key, + ) or requested + + if not requested: + return { + "accepted": False, + "persist": False, + "recognized": False, + "message": "Model name cannot be empty.", + } + + if any(ch.isspace() for ch in requested): + return { + "accepted": False, + "persist": False, + "recognized": False, + "message": "Model names cannot contain spaces.", + } + + if normalized == "custom": + probe = probe_api_models(api_key, base_url) + api_models = probe.get("models") + if api_models is not None: + if requested_for_lookup in set(api_models): + return { + "accepted": True, + "persist": True, + "recognized": True, + "message": None, + } + + # Auto-correct if the top match is very similar (e.g. typo) + auto = get_close_matches(requested_for_lookup, api_models, n=1, cutoff=0.9) + if auto: + return { + "accepted": True, + "persist": True, + "recognized": True, + "corrected_model": auto[0], + "message": f"Auto-corrected `{requested}` → `{auto[0]}`", + } + + suggestions = get_close_matches(requested, api_models, n=3, cutoff=0.5) + suggestion_text = "" + if suggestions: + suggestion_text = "\n Similar models: " + ", ".join(f"`{s}`" for s in suggestions) + + message = ( + f"Note: `{requested}` was not found in this custom endpoint's model listing " + f"({probe.get('probed_url')}). It may still work if the server supports hidden or aliased models." + f"{suggestion_text}" + ) + if probe.get("used_fallback"): + message += ( + f"\n Endpoint verification succeeded after trying `{probe.get('resolved_base_url')}`. " + f"Consider saving that as your base URL." + ) + + return { + "accepted": True, + "persist": True, + "recognized": False, + "message": message, + } + + message = ( + f"Note: could not reach this custom endpoint's model listing at `{probe.get('probed_url')}`. " + f"Hermes will still save `{requested}`, but the endpoint should expose `/models` for verification." + ) + if probe.get("suggested_base_url"): + message += f"\n If this server expects `/v1`, try base URL: `{probe.get('suggested_base_url')}`" + + return { + "accepted": True, + "persist": True, + "recognized": False, + "message": message, + } + + # OpenAI Codex has its own catalog path; /v1/models probing is not the right validation path. + if normalized == "openai-codex": + try: + codex_models = provider_model_ids("openai-codex") + except Exception: + codex_models = [] + if codex_models: + if requested_for_lookup in set(codex_models): + return { + "accepted": True, + "persist": True, + "recognized": True, + "message": None, + } + # Auto-correct if the top match is very similar (e.g. typo) + auto = get_close_matches(requested_for_lookup, codex_models, n=1, cutoff=0.9) + if auto: + return { + "accepted": True, + "persist": True, + "recognized": True, + "corrected_model": auto[0], + "message": f"Auto-corrected `{requested}` → `{auto[0]}`", + } + suggestions = get_close_matches(requested_for_lookup, codex_models, n=3, cutoff=0.5) + suggestion_text = "" + if suggestions: + suggestion_text = "\n Similar models: " + ", ".join(f"`{s}`" for s in suggestions) + return { + "accepted": True, + "persist": True, + "recognized": False, + "message": ( + f"Note: `{requested}` was not found in the OpenAI Codex model listing. " + f"It may still work if your account has access to it." + f"{suggestion_text}" + ), + } + + # Probe the live API to check if the model actually exists + api_models = fetch_api_models(api_key, base_url) + + if api_models is not None: + if requested_for_lookup in set(api_models): + # API confirmed the model exists + return { + "accepted": True, + "persist": True, + "recognized": True, + "message": None, + } + else: + # API responded but model is not listed. Accept anyway — + # the user may have access to models not shown in the public + # listing (e.g. Z.AI Pro/Max plans can use glm-5 on coding + # endpoints even though it's not in /models). Warn but allow. + + # Auto-correct if the top match is very similar (e.g. typo) + auto = get_close_matches(requested_for_lookup, api_models, n=1, cutoff=0.9) + if auto: + return { + "accepted": True, + "persist": True, + "recognized": True, + "corrected_model": auto[0], + "message": f"Auto-corrected `{requested}` → `{auto[0]}`", + } + + suggestions = get_close_matches(requested, api_models, n=3, cutoff=0.5) + suggestion_text = "" + if suggestions: + suggestion_text = "\n Similar models: " + ", ".join(f"`{s}`" for s in suggestions) + + return { + "accepted": True, + "persist": True, + "recognized": False, + "message": ( + f"Note: `{requested}` was not found in this provider's model listing. " + f"It may still work if your plan supports it." + f"{suggestion_text}" + ), + } + + # api_models is None — couldn't reach API. Accept and persist, + # but warn so typos don't silently break things. + provider_label = _PROVIDER_LABELS.get(normalized, normalized) + return { + "accepted": True, + "persist": True, + "recognized": False, + "message": ( + f"Could not reach the {provider_label} API to validate `{requested}`. " + f"If the service isn't down, this model may not be valid." + ), + } diff --git a/mindcli/_vendor/hermes_cli/nous_subscription.py b/mindcli/_vendor/hermes_cli/nous_subscription.py new file mode 100644 index 0000000..f1e4366 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/nous_subscription.py @@ -0,0 +1,531 @@ +"""Helpers for Nous subscription managed-tool capabilities.""" + +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path +from typing import Dict, Iterable, Optional, Set + +from hermes_cli.auth import get_nous_auth_status +from hermes_cli.config import get_env_value, load_config +from tools.managed_tool_gateway import is_managed_tool_gateway_ready +from tools.tool_backend_helpers import ( + has_direct_modal_credentials, + managed_nous_tools_enabled, + normalize_browser_cloud_provider, + normalize_modal_mode, + resolve_modal_backend_state, + resolve_openai_audio_api_key, +) + + +_DEFAULT_PLATFORM_TOOLSETS = { + "cli": "hermes-cli", +} + + +@dataclass(frozen=True) +class NousFeatureState: + key: str + label: str + included_by_default: bool + available: bool + active: bool + managed_by_nous: bool + direct_override: bool + toolset_enabled: bool + current_provider: str = "" + explicit_configured: bool = False + + +@dataclass(frozen=True) +class NousSubscriptionFeatures: + subscribed: bool + nous_auth_present: bool + provider_is_nous: bool + features: Dict[str, NousFeatureState] + + @property + def web(self) -> NousFeatureState: + return self.features["web"] + + @property + def image_gen(self) -> NousFeatureState: + return self.features["image_gen"] + + @property + def tts(self) -> NousFeatureState: + return self.features["tts"] + + @property + def browser(self) -> NousFeatureState: + return self.features["browser"] + + @property + def modal(self) -> NousFeatureState: + return self.features["modal"] + + def items(self) -> Iterable[NousFeatureState]: + ordered = ("web", "image_gen", "tts", "browser", "modal") + for key in ordered: + yield self.features[key] + + +def _model_config_dict(config: Dict[str, object]) -> Dict[str, object]: + model_cfg = config.get("model") + if isinstance(model_cfg, dict): + return dict(model_cfg) + if isinstance(model_cfg, str) and model_cfg.strip(): + return {"default": model_cfg.strip()} + return {} + + +def _toolset_enabled(config: Dict[str, object], toolset_key: str) -> bool: + from toolsets import resolve_toolset + + platform_toolsets = config.get("platform_toolsets") + if not isinstance(platform_toolsets, dict) or not platform_toolsets: + platform_toolsets = {"cli": [_DEFAULT_PLATFORM_TOOLSETS["cli"]]} + + target_tools = set(resolve_toolset(toolset_key)) + if not target_tools: + return False + + for platform, raw_toolsets in platform_toolsets.items(): + if isinstance(raw_toolsets, list): + toolset_names = list(raw_toolsets) + else: + default_toolset = _DEFAULT_PLATFORM_TOOLSETS.get(platform) + toolset_names = [default_toolset] if default_toolset else [] + if not toolset_names: + default_toolset = _DEFAULT_PLATFORM_TOOLSETS.get(platform) + if default_toolset: + toolset_names = [default_toolset] + + available_tools: Set[str] = set() + for toolset_name in toolset_names: + if not isinstance(toolset_name, str) or not toolset_name: + continue + try: + available_tools.update(resolve_toolset(toolset_name)) + except Exception: + continue + + if target_tools and target_tools.issubset(available_tools): + return True + + return False + + +def _has_agent_browser() -> bool: + import shutil + + agent_browser_bin = shutil.which("agent-browser") + local_bin = ( + Path(__file__).parent.parent / "node_modules" / ".bin" / "agent-browser" + ) + return bool(agent_browser_bin or local_bin.exists()) + + +def _browser_label(current_provider: str) -> str: + mapping = { + "browserbase": "Browserbase", + "browser-use": "Browser Use", + "firecrawl": "Firecrawl", + "camofox": "Camofox", + "local": "Local browser", + } + return mapping.get(current_provider or "local", current_provider or "Local browser") + + +def _tts_label(current_provider: str) -> str: + mapping = { + "openai": "OpenAI TTS", + "elevenlabs": "ElevenLabs", + "edge": "Edge TTS", + "mistral": "Mistral Voxtral TTS", + "neutts": "NeuTTS", + } + return mapping.get(current_provider or "edge", current_provider or "Edge TTS") + + +def _resolve_browser_feature_state( + *, + browser_tool_enabled: bool, + browser_provider: str, + browser_provider_explicit: bool, + browser_local_available: bool, + direct_camofox: bool, + direct_browserbase: bool, + direct_browser_use: bool, + direct_firecrawl: bool, + managed_browser_available: bool, +) -> tuple[str, bool, bool, bool]: + """Resolve browser availability using the same precedence as runtime.""" + if direct_camofox: + return "camofox", True, bool(browser_tool_enabled), False + + if browser_provider_explicit: + current_provider = browser_provider or "local" + if current_provider == "browserbase": + available = bool(browser_local_available and direct_browserbase) + active = bool(browser_tool_enabled and available) + return current_provider, available, active, False + if current_provider == "browser-use": + provider_available = managed_browser_available or direct_browser_use + available = bool(browser_local_available and provider_available) + managed = bool( + browser_tool_enabled + and browser_local_available + and managed_browser_available + and not direct_browser_use + ) + active = bool(browser_tool_enabled and available) + return current_provider, available, active, managed + if current_provider == "firecrawl": + available = bool(browser_local_available and direct_firecrawl) + active = bool(browser_tool_enabled and available) + return current_provider, available, active, False + if current_provider == "camofox": + return current_provider, False, False, False + + current_provider = "local" + available = bool(browser_local_available) + active = bool(browser_tool_enabled and available) + return current_provider, available, active, False + + if managed_browser_available or direct_browser_use: + available = bool(browser_local_available) + managed = bool( + browser_tool_enabled + and browser_local_available + and managed_browser_available + and not direct_browser_use + ) + active = bool(browser_tool_enabled and available) + return "browser-use", available, active, managed + + if direct_browserbase: + available = bool(browser_local_available) + active = bool(browser_tool_enabled and available) + return "browserbase", available, active, False + + available = bool(browser_local_available) + active = bool(browser_tool_enabled and available) + return "local", available, active, False + + +def get_nous_subscription_features( + config: Optional[Dict[str, object]] = None, +) -> NousSubscriptionFeatures: + if config is None: + config = load_config() or {} + config = dict(config) + model_cfg = _model_config_dict(config) + provider_is_nous = str(model_cfg.get("provider") or "").strip().lower() == "nous" + + try: + nous_status = get_nous_auth_status() + except Exception: + nous_status = {} + + managed_tools_flag = managed_nous_tools_enabled() + nous_auth_present = bool(nous_status.get("logged_in")) + subscribed = provider_is_nous or nous_auth_present + + web_tool_enabled = _toolset_enabled(config, "web") + image_tool_enabled = _toolset_enabled(config, "image_gen") + tts_tool_enabled = _toolset_enabled(config, "tts") + browser_tool_enabled = _toolset_enabled(config, "browser") + modal_tool_enabled = _toolset_enabled(config, "terminal") + + web_cfg = config.get("web") if isinstance(config.get("web"), dict) else {} + tts_cfg = config.get("tts") if isinstance(config.get("tts"), dict) else {} + browser_cfg = config.get("browser") if isinstance(config.get("browser"), dict) else {} + terminal_cfg = config.get("terminal") if isinstance(config.get("terminal"), dict) else {} + + web_backend = str(web_cfg.get("backend") or "").strip().lower() + tts_provider = str(tts_cfg.get("provider") or "edge").strip().lower() + browser_provider_explicit = "cloud_provider" in browser_cfg + browser_provider = normalize_browser_cloud_provider( + browser_cfg.get("cloud_provider") if browser_provider_explicit else None + ) + terminal_backend = ( + str(terminal_cfg.get("backend") or "local").strip().lower() + ) + modal_mode = normalize_modal_mode( + terminal_cfg.get("modal_mode") + ) + + direct_exa = bool(get_env_value("EXA_API_KEY")) + direct_firecrawl = bool(get_env_value("FIRECRAWL_API_KEY") or get_env_value("FIRECRAWL_API_URL")) + direct_parallel = bool(get_env_value("PARALLEL_API_KEY")) + direct_tavily = bool(get_env_value("TAVILY_API_KEY")) + direct_fal = bool(get_env_value("FAL_KEY")) + direct_openai_tts = bool(resolve_openai_audio_api_key()) + direct_elevenlabs = bool(get_env_value("ELEVENLABS_API_KEY")) + direct_camofox = bool(get_env_value("CAMOFOX_URL")) + direct_browserbase = bool(get_env_value("BROWSERBASE_API_KEY") and get_env_value("BROWSERBASE_PROJECT_ID")) + direct_browser_use = bool(get_env_value("BROWSER_USE_API_KEY")) + direct_modal = has_direct_modal_credentials() + + managed_web_available = managed_tools_flag and nous_auth_present and is_managed_tool_gateway_ready("firecrawl") + managed_image_available = managed_tools_flag and nous_auth_present and is_managed_tool_gateway_ready("fal-queue") + managed_tts_available = managed_tools_flag and nous_auth_present and is_managed_tool_gateway_ready("openai-audio") + managed_browser_available = managed_tools_flag and nous_auth_present and is_managed_tool_gateway_ready("browser-use") + managed_modal_available = managed_tools_flag and nous_auth_present and is_managed_tool_gateway_ready("modal") + modal_state = resolve_modal_backend_state( + modal_mode, + has_direct=direct_modal, + managed_ready=managed_modal_available, + ) + + web_managed = web_backend == "firecrawl" and managed_web_available and not direct_firecrawl + web_active = bool( + web_tool_enabled + and ( + web_managed + or (web_backend == "exa" and direct_exa) + or (web_backend == "firecrawl" and direct_firecrawl) + or (web_backend == "parallel" and direct_parallel) + or (web_backend == "tavily" and direct_tavily) + ) + ) + web_available = bool( + managed_web_available or direct_exa or direct_firecrawl or direct_parallel or direct_tavily + ) + + image_managed = image_tool_enabled and managed_image_available and not direct_fal + image_active = bool(image_tool_enabled and (image_managed or direct_fal)) + image_available = bool(managed_image_available or direct_fal) + + tts_current_provider = tts_provider or "edge" + tts_managed = ( + tts_tool_enabled + and tts_current_provider == "openai" + and managed_tts_available + and not direct_openai_tts + ) + tts_available = bool( + tts_current_provider in {"edge", "neutts"} + or (tts_current_provider == "openai" and (managed_tts_available or direct_openai_tts)) + or (tts_current_provider == "elevenlabs" and direct_elevenlabs) + or (tts_current_provider == "mistral" and bool(get_env_value("MISTRAL_API_KEY"))) + ) + tts_active = bool(tts_tool_enabled and tts_available) + + browser_local_available = _has_agent_browser() + ( + browser_current_provider, + browser_available, + browser_active, + browser_managed, + ) = _resolve_browser_feature_state( + browser_tool_enabled=browser_tool_enabled, + browser_provider=browser_provider, + browser_provider_explicit=browser_provider_explicit, + browser_local_available=browser_local_available, + direct_camofox=direct_camofox, + direct_browserbase=direct_browserbase, + direct_browser_use=direct_browser_use, + direct_firecrawl=direct_firecrawl, + managed_browser_available=managed_browser_available, + ) + + if terminal_backend != "modal": + modal_managed = False + modal_available = True + modal_active = bool(modal_tool_enabled) + modal_direct_override = False + elif modal_state["selected_backend"] == "managed": + modal_managed = bool(modal_tool_enabled) + modal_available = True + modal_active = bool(modal_tool_enabled) + modal_direct_override = False + elif modal_state["selected_backend"] == "direct": + modal_managed = False + modal_available = True + modal_active = bool(modal_tool_enabled) + modal_direct_override = bool(modal_tool_enabled) + elif modal_mode == "managed": + modal_managed = False + modal_available = bool(managed_modal_available) + modal_active = False + modal_direct_override = False + elif modal_mode == "direct": + modal_managed = False + modal_available = bool(direct_modal) + modal_active = False + modal_direct_override = False + else: + modal_managed = False + modal_available = bool(managed_modal_available or direct_modal) + modal_active = False + modal_direct_override = False + + tts_explicit_configured = False + raw_tts_cfg = config.get("tts") + if isinstance(raw_tts_cfg, dict) and "provider" in raw_tts_cfg: + tts_explicit_configured = tts_provider not in {"", "edge"} + + features = { + "web": NousFeatureState( + key="web", + label="Web tools", + included_by_default=True, + available=web_available, + active=web_active, + managed_by_nous=web_managed, + direct_override=web_active and not web_managed, + toolset_enabled=web_tool_enabled, + current_provider=web_backend or "", + explicit_configured=bool(web_backend), + ), + "image_gen": NousFeatureState( + key="image_gen", + label="Image generation", + included_by_default=True, + available=image_available, + active=image_active, + managed_by_nous=image_managed, + direct_override=image_active and not image_managed, + toolset_enabled=image_tool_enabled, + current_provider="FAL" if direct_fal else ("Nous Subscription" if image_managed else ""), + explicit_configured=direct_fal, + ), + "tts": NousFeatureState( + key="tts", + label="OpenAI TTS", + included_by_default=True, + available=tts_available, + active=tts_active, + managed_by_nous=tts_managed, + direct_override=tts_active and not tts_managed, + toolset_enabled=tts_tool_enabled, + current_provider=_tts_label(tts_current_provider), + explicit_configured=tts_explicit_configured, + ), + "browser": NousFeatureState( + key="browser", + label="Browser automation", + included_by_default=True, + available=browser_available, + active=browser_active, + managed_by_nous=browser_managed, + direct_override=browser_active and not browser_managed, + toolset_enabled=browser_tool_enabled, + current_provider=_browser_label(browser_current_provider), + explicit_configured=browser_provider_explicit, + ), + "modal": NousFeatureState( + key="modal", + label="Modal execution", + included_by_default=False, + available=modal_available, + active=modal_active, + managed_by_nous=modal_managed, + direct_override=terminal_backend == "modal" and modal_direct_override, + toolset_enabled=modal_tool_enabled, + current_provider="Modal" if terminal_backend == "modal" else terminal_backend or "local", + explicit_configured=terminal_backend == "modal", + ), + } + + return NousSubscriptionFeatures( + subscribed=subscribed, + nous_auth_present=nous_auth_present, + provider_is_nous=provider_is_nous, + features=features, + ) + + +def get_nous_subscription_explainer_lines() -> list[str]: + if not managed_nous_tools_enabled(): + return [] + + return [ + "Nous subscription enables managed web tools, image generation, OpenAI TTS, and browser automation by default.", + "Those managed tools bill to your Nous subscription. Modal execution is optional and can bill to your subscription too.", + "Change these later with: hermes setup tools, hermes setup terminal, or hermes status.", + ] + + +def apply_nous_provider_defaults(config: Dict[str, object]) -> set[str]: + """Apply provider-level Nous defaults shared by `hermes setup` and `hermes model`.""" + if not managed_nous_tools_enabled(): + return set() + + features = get_nous_subscription_features(config) + if not features.provider_is_nous: + return set() + + tts_cfg = config.get("tts") + if not isinstance(tts_cfg, dict): + tts_cfg = {} + config["tts"] = tts_cfg + + current_tts = str(tts_cfg.get("provider") or "edge").strip().lower() + if current_tts not in {"", "edge"}: + return set() + + tts_cfg["provider"] = "openai" + return {"tts"} + + +def apply_nous_managed_defaults( + config: Dict[str, object], + *, + enabled_toolsets: Optional[Iterable[str]] = None, +) -> set[str]: + if not managed_nous_tools_enabled(): + return set() + + features = get_nous_subscription_features(config) + if not features.provider_is_nous: + return set() + + selected_toolsets = set(enabled_toolsets or ()) + changed: set[str] = set() + + web_cfg = config.get("web") + if not isinstance(web_cfg, dict): + web_cfg = {} + config["web"] = web_cfg + + tts_cfg = config.get("tts") + if not isinstance(tts_cfg, dict): + tts_cfg = {} + config["tts"] = tts_cfg + + browser_cfg = config.get("browser") + if not isinstance(browser_cfg, dict): + browser_cfg = {} + config["browser"] = browser_cfg + + if "web" in selected_toolsets and not features.web.explicit_configured and not ( + get_env_value("PARALLEL_API_KEY") + or get_env_value("TAVILY_API_KEY") + or get_env_value("FIRECRAWL_API_KEY") + or get_env_value("FIRECRAWL_API_URL") + ): + web_cfg["backend"] = "firecrawl" + changed.add("web") + + if "tts" in selected_toolsets and not features.tts.explicit_configured and not ( + resolve_openai_audio_api_key() + or get_env_value("ELEVENLABS_API_KEY") + ): + tts_cfg["provider"] = "openai" + changed.add("tts") + + if "browser" in selected_toolsets and not features.browser.explicit_configured and not ( + get_env_value("BROWSER_USE_API_KEY") + or get_env_value("BROWSERBASE_API_KEY") + ): + browser_cfg["cloud_provider"] = "browser-use" + changed.add("browser") + + if "image_gen" in selected_toolsets and not get_env_value("FAL_KEY"): + changed.add("image_gen") + + return changed diff --git a/mindcli/_vendor/hermes_cli/pairing.py b/mindcli/_vendor/hermes_cli/pairing.py new file mode 100644 index 0000000..7e04da9 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/pairing.py @@ -0,0 +1,97 @@ +""" +CLI commands for the DM pairing system. + +Usage: + hermes pairing list # Show all pending + approved users + hermes pairing approve # Approve a pairing code + hermes pairing revoke # Revoke user access + hermes pairing clear-pending # Clear all expired/pending codes +""" + +def pairing_command(args): + """Handle hermes pairing subcommands.""" + from gateway.pairing import PairingStore + + store = PairingStore() + action = getattr(args, "pairing_action", None) + + if action == "list": + _cmd_list(store) + elif action == "approve": + _cmd_approve(store, args.platform, args.code) + elif action == "revoke": + _cmd_revoke(store, args.platform, args.user_id) + elif action == "clear-pending": + _cmd_clear_pending(store) + else: + print("Usage: hermes pairing {list|approve|revoke|clear-pending}") + print("Run 'hermes pairing --help' for details.") + + +def _cmd_list(store): + """List all pending and approved users.""" + pending = store.list_pending() + approved = store.list_approved() + + if not pending and not approved: + print("No pairing data found. No one has tried to pair yet~") + return + + if pending: + print(f"\n Pending Pairing Requests ({len(pending)}):") + print(f" {'Platform':<12} {'Code':<10} {'User ID':<20} {'Name':<20} {'Age'}") + print(f" {'--------':<12} {'----':<10} {'-------':<20} {'----':<20} {'---'}") + for p in pending: + print( + f" {p['platform']:<12} {p['code']:<10} {p['user_id']:<20} " + f"{p.get('user_name', ''):<20} {p['age_minutes']}m ago" + ) + else: + print("\n No pending pairing requests.") + + if approved: + print(f"\n Approved Users ({len(approved)}):") + print(f" {'Platform':<12} {'User ID':<20} {'Name':<20}") + print(f" {'--------':<12} {'-------':<20} {'----':<20}") + for a in approved: + print(f" {a['platform']:<12} {a['user_id']:<20} {a.get('user_name', ''):<20}") + else: + print("\n No approved users.") + + print() + + +def _cmd_approve(store, platform: str, code: str): + """Approve a pairing code.""" + platform = platform.lower().strip() + code = code.upper().strip() + + result = store.approve_code(platform, code) + if result: + uid = result["user_id"] + name = result.get("user_name", "") + display = f"{name} ({uid})" if name else uid + print(f"\n Approved! User {display} on {platform} can now use the bot~") + print(" They'll be recognized automatically on their next message.\n") + else: + print(f"\n Code '{code}' not found or expired for platform '{platform}'.") + print(" Run 'hermes pairing list' to see pending codes.\n") + + +def _cmd_revoke(store, platform: str, user_id: str): + """Revoke a user's access.""" + platform = platform.lower().strip() + + if store.revoke(platform, user_id): + print(f"\n Revoked access for user {user_id} on {platform}.\n") + else: + print(f"\n User {user_id} not found in approved list for {platform}.\n") + + +def _cmd_clear_pending(store): + """Clear all pending pairing codes.""" + count = store.clear_pending() + if count: + print(f"\n Cleared {count} pending pairing request(s).\n") + else: + print("\n No pending requests to clear.\n") diff --git a/mindcli/_vendor/hermes_cli/platforms.py b/mindcli/_vendor/hermes_cli/platforms.py new file mode 100644 index 0000000..1fc3a3a --- /dev/null +++ b/mindcli/_vendor/hermes_cli/platforms.py @@ -0,0 +1,47 @@ +""" +Shared platform registry for Hermes Agent. + +Single source of truth for platform metadata consumed by both +skills_config (label display) and tools_config (default toolset +resolution). Import ``PLATFORMS`` from here instead of maintaining +duplicate dicts in each module. +""" + +from collections import OrderedDict +from typing import NamedTuple + + +class PlatformInfo(NamedTuple): + """Metadata for a single platform entry.""" + label: str + default_toolset: str + + +# Ordered so that TUI menus are deterministic. +PLATFORMS: OrderedDict[str, PlatformInfo] = OrderedDict([ + ("cli", PlatformInfo(label="🖥️ CLI", default_toolset="hermes-cli")), + ("telegram", PlatformInfo(label="📱 Telegram", default_toolset="hermes-telegram")), + ("discord", PlatformInfo(label="💬 Discord", default_toolset="hermes-discord")), + ("slack", PlatformInfo(label="💼 Slack", default_toolset="hermes-slack")), + ("whatsapp", PlatformInfo(label="📱 WhatsApp", default_toolset="hermes-whatsapp")), + ("signal", PlatformInfo(label="📡 Signal", default_toolset="hermes-signal")), + ("bluebubbles", PlatformInfo(label="💙 BlueBubbles", default_toolset="hermes-bluebubbles")), + ("email", PlatformInfo(label="📧 Email", default_toolset="hermes-email")), + ("homeassistant", PlatformInfo(label="🏠 Home Assistant", default_toolset="hermes-homeassistant")), + ("mattermost", PlatformInfo(label="💬 Mattermost", default_toolset="hermes-mattermost")), + ("matrix", PlatformInfo(label="💬 Matrix", default_toolset="hermes-matrix")), + ("dingtalk", PlatformInfo(label="💬 DingTalk", default_toolset="hermes-dingtalk")), + ("feishu", PlatformInfo(label="🪽 Feishu", default_toolset="hermes-feishu")), + ("wecom", PlatformInfo(label="💬 WeCom", default_toolset="hermes-wecom")), + ("wecom_callback", PlatformInfo(label="💬 WeCom Callback", default_toolset="hermes-wecom-callback")), + ("weixin", PlatformInfo(label="💬 Weixin", default_toolset="hermes-weixin")), + ("qqbot", PlatformInfo(label="💬 QQBot", default_toolset="hermes-qqbot")), + ("webhook", PlatformInfo(label="🔗 Webhook", default_toolset="hermes-webhook")), + ("api_server", PlatformInfo(label="🌐 API Server", default_toolset="hermes-api-server")), +]) + + +def platform_label(key: str, default: str = "") -> str: + """Return the display label for a platform key, or *default*.""" + info = PLATFORMS.get(key) + return info.label if info is not None else default diff --git a/mindcli/_vendor/hermes_cli/plugins.py b/mindcli/_vendor/hermes_cli/plugins.py new file mode 100644 index 0000000..a1f8db3 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/plugins.py @@ -0,0 +1,673 @@ +""" +Hermes Plugin System +==================== + +Discovers, loads, and manages plugins from three sources: + +1. **User plugins** – ``~/.hermes/plugins//`` +2. **Project plugins** – ``./.hermes/plugins//`` (opt-in via + ``HERMES_ENABLE_PROJECT_PLUGINS``) +3. **Pip plugins** – packages that expose the ``hermes_agent.plugins`` + entry-point group. + +Each directory plugin must contain a ``plugin.yaml`` manifest **and** an +``__init__.py`` with a ``register(ctx)`` function. + +Lifecycle hooks +--------------- +Plugins may register callbacks for any of the hooks in ``VALID_HOOKS``. +The agent core calls ``invoke_hook(name, **kwargs)`` at the appropriate +points. + +Tool registration +----------------- +``PluginContext.register_tool()`` delegates to ``tools.registry.register()`` +so plugin-defined tools appear alongside the built-in tools. +""" + +from __future__ import annotations + +import importlib +import importlib.metadata +import importlib.util +import logging +import sys +import types +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any, Callable, Dict, List, Optional, Set, Union + +from hermes_constants import get_hermes_home +from utils import env_var_enabled + +try: + import yaml +except ImportError: # pragma: no cover – yaml is optional at import time + yaml = None # type: ignore[assignment] + +logger = logging.getLogger(__name__) + +# --------------------------------------------------------------------------- +# Constants +# --------------------------------------------------------------------------- + +VALID_HOOKS: Set[str] = { + "pre_tool_call", + "post_tool_call", + "pre_llm_call", + "post_llm_call", + "pre_api_request", + "post_api_request", + "on_session_start", + "on_session_end", + "on_session_finalize", + "on_session_reset", +} + +ENTRY_POINTS_GROUP = "hermes_agent.plugins" + +_NS_PARENT = "hermes_plugins" + + +def _env_enabled(name: str) -> bool: + """Return True when an env var is set to a truthy opt-in value.""" + return env_var_enabled(name) + + +def _get_disabled_plugins() -> set: + """Read the disabled plugins list from config.yaml.""" + try: + from hermes_cli.config import load_config + config = load_config() + disabled = config.get("plugins", {}).get("disabled", []) + return set(disabled) if isinstance(disabled, list) else set() + except Exception: + return set() + + +# --------------------------------------------------------------------------- +# Data classes +# --------------------------------------------------------------------------- + +@dataclass +class PluginManifest: + """Parsed representation of a plugin.yaml manifest.""" + + name: str + version: str = "" + description: str = "" + author: str = "" + requires_env: List[Union[str, Dict[str, Any]]] = field(default_factory=list) + provides_tools: List[str] = field(default_factory=list) + provides_hooks: List[str] = field(default_factory=list) + source: str = "" # "user", "project", or "entrypoint" + path: Optional[str] = None + + +@dataclass +class LoadedPlugin: + """Runtime state for a single loaded plugin.""" + + manifest: PluginManifest + module: Optional[types.ModuleType] = None + tools_registered: List[str] = field(default_factory=list) + hooks_registered: List[str] = field(default_factory=list) + enabled: bool = False + error: Optional[str] = None + + +# --------------------------------------------------------------------------- +# PluginContext – handed to each plugin's ``register()`` function +# --------------------------------------------------------------------------- + +class PluginContext: + """Facade given to plugins so they can register tools and hooks.""" + + def __init__(self, manifest: PluginManifest, manager: "PluginManager"): + self.manifest = manifest + self._manager = manager + + # -- tool registration -------------------------------------------------- + + def register_tool( + self, + name: str, + toolset: str, + schema: dict, + handler: Callable, + check_fn: Callable | None = None, + requires_env: list | None = None, + is_async: bool = False, + description: str = "", + emoji: str = "", + ) -> None: + """Register a tool in the global registry **and** track it as plugin-provided.""" + from tools.registry import registry + + registry.register( + name=name, + toolset=toolset, + schema=schema, + handler=handler, + check_fn=check_fn, + requires_env=requires_env, + is_async=is_async, + description=description, + emoji=emoji, + ) + self._manager._plugin_tool_names.add(name) + logger.debug("Plugin %s registered tool: %s", self.manifest.name, name) + + # -- message injection -------------------------------------------------- + + def inject_message(self, content: str, role: str = "user") -> bool: + """Inject a message into the active conversation. + + If the agent is idle (waiting for user input), this starts a new turn. + If the agent is running, this interrupts and injects the message. + + This enables plugins (e.g. remote control viewers, messaging bridges) + to send messages into the conversation from external sources. + + Returns True if the message was queued successfully. + """ + cli = self._manager._cli_ref + if cli is None: + logger.warning("inject_message: no CLI reference (not available in gateway mode)") + return False + + msg = content if role == "user" else f"[{role}] {content}" + + if getattr(cli, "_agent_running", False): + # Agent is mid-turn — interrupt with the message + cli._interrupt_queue.put(msg) + else: + # Agent is idle — queue as next input + cli._pending_input.put(msg) + return True + + # -- CLI command registration -------------------------------------------- + + def register_cli_command( + self, + name: str, + help: str, + setup_fn: Callable, + handler_fn: Callable | None = None, + description: str = "", + ) -> None: + """Register a CLI subcommand (e.g. ``hermes honcho ...``). + + The *setup_fn* receives an argparse subparser and should add any + arguments/sub-subparsers. If *handler_fn* is provided it is set + as the default dispatch function via ``set_defaults(func=...)``.""" + self._manager._cli_commands[name] = { + "name": name, + "help": help, + "description": description, + "setup_fn": setup_fn, + "handler_fn": handler_fn, + "plugin": self.manifest.name, + } + logger.debug("Plugin %s registered CLI command: %s", self.manifest.name, name) + + # -- context engine registration ----------------------------------------- + + def register_context_engine(self, engine) -> None: + """Register a context engine to replace the built-in ContextCompressor. + + Only one context engine plugin is allowed. If a second plugin tries + to register one, it is rejected with a warning. + + The engine must be an instance of ``agent.context_engine.ContextEngine``. + """ + if self._manager._context_engine is not None: + logger.warning( + "Plugin '%s' tried to register a context engine, but one is " + "already registered. Only one context engine plugin is allowed.", + self.manifest.name, + ) + return + # Defer the import to avoid circular deps at module level + from agent.context_engine import ContextEngine + if not isinstance(engine, ContextEngine): + logger.warning( + "Plugin '%s' tried to register a context engine that does not " + "inherit from ContextEngine. Ignoring.", + self.manifest.name, + ) + return + self._manager._context_engine = engine + logger.info( + "Plugin '%s' registered context engine: %s", + self.manifest.name, engine.name, + ) + + # -- hook registration -------------------------------------------------- + + def register_hook(self, hook_name: str, callback: Callable) -> None: + """Register a lifecycle hook callback. + + Unknown hook names produce a warning but are still stored so + forward-compatible plugins don't break. + """ + if hook_name not in VALID_HOOKS: + logger.warning( + "Plugin '%s' registered unknown hook '%s' " + "(valid: %s)", + self.manifest.name, + hook_name, + ", ".join(sorted(VALID_HOOKS)), + ) + self._manager._hooks.setdefault(hook_name, []).append(callback) + logger.debug("Plugin %s registered hook: %s", self.manifest.name, hook_name) + + +# --------------------------------------------------------------------------- +# PluginManager +# --------------------------------------------------------------------------- + +class PluginManager: + """Central manager that discovers, loads, and invokes plugins.""" + + def __init__(self) -> None: + self._plugins: Dict[str, LoadedPlugin] = {} + self._hooks: Dict[str, List[Callable]] = {} + self._plugin_tool_names: Set[str] = set() + self._cli_commands: Dict[str, dict] = {} + self._context_engine = None # Set by a plugin via register_context_engine() + self._discovered: bool = False + self._cli_ref = None # Set by CLI after plugin discovery + + # ----------------------------------------------------------------------- + # Public + # ----------------------------------------------------------------------- + + def discover_and_load(self) -> None: + """Scan all plugin sources and load each plugin found.""" + if self._discovered: + return + self._discovered = True + + manifests: List[PluginManifest] = [] + + # 1. User plugins (~/.hermes/plugins/) + user_dir = get_hermes_home() / "plugins" + manifests.extend(self._scan_directory(user_dir, source="user")) + + # 2. Project plugins (./.hermes/plugins/) + if _env_enabled("HERMES_ENABLE_PROJECT_PLUGINS"): + project_dir = Path.cwd() / ".hermes" / "plugins" + manifests.extend(self._scan_directory(project_dir, source="project")) + + # 3. Pip / entry-point plugins + manifests.extend(self._scan_entry_points()) + + # Load each manifest (skip user-disabled plugins) + disabled = _get_disabled_plugins() + for manifest in manifests: + if manifest.name in disabled: + loaded = LoadedPlugin(manifest=manifest, enabled=False) + loaded.error = "disabled via config" + self._plugins[manifest.name] = loaded + logger.debug("Skipping disabled plugin '%s'", manifest.name) + continue + self._load_plugin(manifest) + + if manifests: + logger.info( + "Plugin discovery complete: %d found, %d enabled", + len(self._plugins), + sum(1 for p in self._plugins.values() if p.enabled), + ) + + # ----------------------------------------------------------------------- + # Directory scanning + # ----------------------------------------------------------------------- + + def _scan_directory(self, path: Path, source: str) -> List[PluginManifest]: + """Read ``plugin.yaml`` manifests from subdirectories of *path*.""" + manifests: List[PluginManifest] = [] + if not path.is_dir(): + return manifests + + for child in sorted(path.iterdir()): + if not child.is_dir(): + continue + manifest_file = child / "plugin.yaml" + if not manifest_file.exists(): + manifest_file = child / "plugin.yml" + if not manifest_file.exists(): + logger.debug("Skipping %s (no plugin.yaml)", child) + continue + + try: + if yaml is None: + logger.warning("PyYAML not installed – cannot load %s", manifest_file) + continue + data = yaml.safe_load(manifest_file.read_text()) or {} + manifest = PluginManifest( + name=data.get("name", child.name), + version=str(data.get("version", "")), + description=data.get("description", ""), + author=data.get("author", ""), + requires_env=data.get("requires_env", []), + provides_tools=data.get("provides_tools", []), + provides_hooks=data.get("provides_hooks", []), + source=source, + path=str(child), + ) + manifests.append(manifest) + except Exception as exc: + logger.warning("Failed to parse %s: %s", manifest_file, exc) + + return manifests + + # ----------------------------------------------------------------------- + # Entry-point scanning + # ----------------------------------------------------------------------- + + def _scan_entry_points(self) -> List[PluginManifest]: + """Check ``importlib.metadata`` for pip-installed plugins.""" + manifests: List[PluginManifest] = [] + try: + eps = importlib.metadata.entry_points() + # Python 3.12+ returns a SelectableGroups; earlier returns dict + if hasattr(eps, "select"): + group_eps = eps.select(group=ENTRY_POINTS_GROUP) + elif isinstance(eps, dict): + group_eps = eps.get(ENTRY_POINTS_GROUP, []) + else: + group_eps = [ep for ep in eps if ep.group == ENTRY_POINTS_GROUP] + + for ep in group_eps: + manifest = PluginManifest( + name=ep.name, + source="entrypoint", + path=ep.value, + ) + manifests.append(manifest) + except Exception as exc: + logger.debug("Entry-point scan failed: %s", exc) + + return manifests + + # ----------------------------------------------------------------------- + # Loading + # ----------------------------------------------------------------------- + + def _load_plugin(self, manifest: PluginManifest) -> None: + """Import a plugin module and call its ``register(ctx)`` function.""" + loaded = LoadedPlugin(manifest=manifest) + + try: + if manifest.source in ("user", "project"): + module = self._load_directory_module(manifest) + else: + module = self._load_entrypoint_module(manifest) + + loaded.module = module + + # Call register() + register_fn = getattr(module, "register", None) + if register_fn is None: + loaded.error = "no register() function" + logger.warning("Plugin '%s' has no register() function", manifest.name) + else: + ctx = PluginContext(manifest, self) + register_fn(ctx) + loaded.tools_registered = [ + t for t in self._plugin_tool_names + if t not in { + n + for name, p in self._plugins.items() + for n in p.tools_registered + } + ] + loaded.hooks_registered = list( + { + h + for h, cbs in self._hooks.items() + if cbs # non-empty + } + - { + h + for name, p in self._plugins.items() + for h in p.hooks_registered + } + ) + loaded.enabled = True + + except Exception as exc: + loaded.error = str(exc) + logger.warning("Failed to load plugin '%s': %s", manifest.name, exc) + + self._plugins[manifest.name] = loaded + + def _load_directory_module(self, manifest: PluginManifest) -> types.ModuleType: + """Import a directory-based plugin as ``hermes_plugins.``.""" + plugin_dir = Path(manifest.path) # type: ignore[arg-type] + init_file = plugin_dir / "__init__.py" + if not init_file.exists(): + raise FileNotFoundError(f"No __init__.py in {plugin_dir}") + + # Ensure the namespace parent package exists + if _NS_PARENT not in sys.modules: + ns_pkg = types.ModuleType(_NS_PARENT) + ns_pkg.__path__ = [] # type: ignore[attr-defined] + ns_pkg.__package__ = _NS_PARENT + sys.modules[_NS_PARENT] = ns_pkg + + module_name = f"{_NS_PARENT}.{manifest.name.replace('-', '_')}" + spec = importlib.util.spec_from_file_location( + module_name, + init_file, + submodule_search_locations=[str(plugin_dir)], + ) + if spec is None or spec.loader is None: + raise ImportError(f"Cannot create module spec for {init_file}") + + module = importlib.util.module_from_spec(spec) + module.__package__ = module_name + module.__path__ = [str(plugin_dir)] # type: ignore[attr-defined] + sys.modules[module_name] = module + spec.loader.exec_module(module) + return module + + def _load_entrypoint_module(self, manifest: PluginManifest) -> types.ModuleType: + """Load a pip-installed plugin via its entry-point reference.""" + eps = importlib.metadata.entry_points() + if hasattr(eps, "select"): + group_eps = eps.select(group=ENTRY_POINTS_GROUP) + elif isinstance(eps, dict): + group_eps = eps.get(ENTRY_POINTS_GROUP, []) + else: + group_eps = [ep for ep in eps if ep.group == ENTRY_POINTS_GROUP] + + for ep in group_eps: + if ep.name == manifest.name: + return ep.load() + + raise ImportError( + f"Entry point '{manifest.name}' not found in group '{ENTRY_POINTS_GROUP}'" + ) + + # ----------------------------------------------------------------------- + # Hook invocation + # ----------------------------------------------------------------------- + + def invoke_hook(self, hook_name: str, **kwargs: Any) -> List[Any]: + """Call all registered callbacks for *hook_name*. + + Each callback is wrapped in its own try/except so a misbehaving + plugin cannot break the core agent loop. + + Returns a list of non-``None`` return values from callbacks. + + For ``pre_llm_call``, callbacks may return a dict describing + context to inject into the current turn's user message:: + + {"context": "recalled text..."} + "recalled text..." # plain string, equivalent + + Context is ALWAYS injected into the user message, never the + system prompt. This preserves the prompt cache prefix — the + system prompt stays identical across turns so cached tokens + are reused. All injected context is ephemeral — never + persisted to session DB. + """ + callbacks = self._hooks.get(hook_name, []) + results: List[Any] = [] + for cb in callbacks: + try: + ret = cb(**kwargs) + if ret is not None: + results.append(ret) + except Exception as exc: + logger.warning( + "Hook '%s' callback %s raised: %s", + hook_name, + getattr(cb, "__name__", repr(cb)), + exc, + ) + return results + + # ----------------------------------------------------------------------- + # Introspection + # ----------------------------------------------------------------------- + + def list_plugins(self) -> List[Dict[str, Any]]: + """Return a list of info dicts for all discovered plugins.""" + result: List[Dict[str, Any]] = [] + for name, loaded in sorted(self._plugins.items()): + result.append( + { + "name": name, + "version": loaded.manifest.version, + "description": loaded.manifest.description, + "source": loaded.manifest.source, + "enabled": loaded.enabled, + "tools": len(loaded.tools_registered), + "hooks": len(loaded.hooks_registered), + "error": loaded.error, + } + ) + return result + + +# --------------------------------------------------------------------------- +# Module-level singleton & convenience functions +# --------------------------------------------------------------------------- + +_plugin_manager: Optional[PluginManager] = None + + +def get_plugin_manager() -> PluginManager: + """Return (and lazily create) the global PluginManager singleton.""" + global _plugin_manager + if _plugin_manager is None: + _plugin_manager = PluginManager() + return _plugin_manager + + +def discover_plugins() -> None: + """Discover and load all plugins (idempotent).""" + get_plugin_manager().discover_and_load() + + +def invoke_hook(hook_name: str, **kwargs: Any) -> List[Any]: + """Invoke a lifecycle hook on all loaded plugins. + + Returns a list of non-``None`` return values from plugin callbacks. + """ + return get_plugin_manager().invoke_hook(hook_name, **kwargs) + + + +def get_pre_tool_call_block_message( + tool_name: str, + args: Optional[Dict[str, Any]], + task_id: str = "", + session_id: str = "", + tool_call_id: str = "", +) -> Optional[str]: + """Check ``pre_tool_call`` hooks for a blocking directive. + + Plugins that need to enforce policy (rate limiting, security + restrictions, approval workflows) can return:: + + {"action": "block", "message": "Reason the tool was blocked"} + + from their ``pre_tool_call`` callback. The first valid block + directive wins. Invalid or irrelevant hook return values are + silently ignored so existing observer-only hooks are unaffected. + """ + hook_results = invoke_hook( + "pre_tool_call", + tool_name=tool_name, + args=args if isinstance(args, dict) else {}, + task_id=task_id, + session_id=session_id, + tool_call_id=tool_call_id, + ) + + for result in hook_results: + if not isinstance(result, dict): + continue + if result.get("action") != "block": + continue + message = result.get("message") + if isinstance(message, str) and message: + return message + + return None + + +def get_plugin_context_engine(): + """Return the plugin-registered context engine, or None.""" + return get_plugin_manager()._context_engine + + +def get_plugin_toolsets() -> List[tuple]: + """Return plugin toolsets as ``(key, label, description)`` tuples. + + Used by the ``hermes tools`` TUI so plugin-provided toolsets appear + alongside the built-in ones and can be toggled on/off per platform. + """ + manager = get_plugin_manager() + if not manager._plugin_tool_names: + return [] + + try: + from tools.registry import registry + except Exception: + return [] + + # Group plugin tool names by their toolset + toolset_tools: Dict[str, List[str]] = {} + toolset_plugin: Dict[str, LoadedPlugin] = {} + for tool_name in manager._plugin_tool_names: + entry = registry.get_entry(tool_name) + if not entry: + continue + ts = entry.toolset + toolset_tools.setdefault(ts, []).append(entry.name) + + # Map toolsets back to the plugin that registered them + for _name, loaded in manager._plugins.items(): + for tool_name in loaded.tools_registered: + entry = registry.get_entry(tool_name) + if entry and entry.toolset in toolset_tools: + toolset_plugin.setdefault(entry.toolset, loaded) + + result = [] + for ts_key in sorted(toolset_tools): + plugin = toolset_plugin.get(ts_key) + label = f"🔌 {ts_key.replace('_', ' ').title()}" + if plugin and plugin.manifest.description: + desc = plugin.manifest.description + else: + desc = ", ".join(sorted(toolset_tools[ts_key])) + result.append((ts_key, label, desc)) + + return result diff --git a/mindcli/_vendor/hermes_cli/plugins_cmd.py b/mindcli/_vendor/hermes_cli/plugins_cmd.py new file mode 100644 index 0000000..c92d8b0 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/plugins_cmd.py @@ -0,0 +1,1128 @@ +"""``hermes plugins`` CLI subcommand — install, update, remove, and list plugins. + +Plugins are installed from Git repositories into ``~/.hermes/plugins/``. +Supports full URLs and ``owner/repo`` shorthand (resolves to GitHub). + +After install, if the plugin ships an ``after-install.md`` file it is +rendered with Rich Markdown. Otherwise a default confirmation is shown. +""" + +from __future__ import annotations + +import logging +import os +import shutil +import subprocess +import sys +from pathlib import Path + +from hermes_constants import get_hermes_home + +logger = logging.getLogger(__name__) + +# Minimum manifest version this installer understands. +# Plugins may declare ``manifest_version: 1`` in plugin.yaml; +# future breaking changes to the manifest schema bump this. +_SUPPORTED_MANIFEST_VERSION = 1 + + +def _plugins_dir() -> Path: + """Return the user plugins directory, creating it if needed.""" + plugins = get_hermes_home() / "plugins" + plugins.mkdir(parents=True, exist_ok=True) + return plugins + + +def _sanitize_plugin_name(name: str, plugins_dir: Path) -> Path: + """Validate a plugin name and return the safe target path inside *plugins_dir*. + + Raises ``ValueError`` if the name contains path-traversal sequences or would + resolve outside the plugins directory. + """ + if not name: + raise ValueError("Plugin name must not be empty.") + + if name in (".", ".."): + raise ValueError( + f"Invalid plugin name '{name}': must not reference the plugins directory itself." + ) + + # Reject obvious traversal characters + for bad in ("/", "\\", ".."): + if bad in name: + raise ValueError(f"Invalid plugin name '{name}': must not contain '{bad}'.") + + target = (plugins_dir / name).resolve() + plugins_resolved = plugins_dir.resolve() + + if target == plugins_resolved: + raise ValueError( + f"Invalid plugin name '{name}': resolves to the plugins directory itself." + ) + + try: + target.relative_to(plugins_resolved) + except ValueError: + raise ValueError( + f"Invalid plugin name '{name}': resolves outside the plugins directory." + ) + + return target + + +def _resolve_git_url(identifier: str) -> str: + """Turn an identifier into a cloneable Git URL. + + Accepted formats: + - Full URL: https://github.com/owner/repo.git + - Full URL: git@github.com:owner/repo.git + - Full URL: ssh://git@github.com/owner/repo.git + - Shorthand: owner/repo → https://github.com/owner/repo.git + + NOTE: ``http://`` and ``file://`` schemes are accepted but will trigger a + security warning at install time. + """ + # Already a URL + if identifier.startswith(("https://", "http://", "git@", "ssh://", "file://")): + return identifier + + # owner/repo shorthand + parts = identifier.strip("/").split("/") + if len(parts) == 2: + owner, repo = parts + return f"https://github.com/{owner}/{repo}.git" + + raise ValueError( + f"Invalid plugin identifier: '{identifier}'. " + "Use a Git URL or owner/repo shorthand." + ) + + +def _repo_name_from_url(url: str) -> str: + """Extract the repo name from a Git URL for the plugin directory name.""" + # Strip trailing .git and slashes + name = url.rstrip("/") + if name.endswith(".git"): + name = name[:-4] + # Get last path component + name = name.rsplit("/", 1)[-1] + # Handle ssh-style urls: git@github.com:owner/repo + if ":" in name: + name = name.rsplit(":", 1)[-1].rsplit("/", 1)[-1] + return name + + +def _read_manifest(plugin_dir: Path) -> dict: + """Read plugin.yaml and return the parsed dict, or empty dict.""" + manifest_file = plugin_dir / "plugin.yaml" + if not manifest_file.exists(): + return {} + try: + import yaml + + with open(manifest_file) as f: + return yaml.safe_load(f) or {} + except Exception as e: + logger.warning("Failed to read plugin.yaml in %s: %s", plugin_dir, e) + return {} + + +def _copy_example_files(plugin_dir: Path, console) -> None: + """Copy any .example files to their real names if they don't already exist. + + For example, ``config.yaml.example`` becomes ``config.yaml``. + Skips files that already exist to avoid overwriting user config on reinstall. + """ + for example_file in plugin_dir.glob("*.example"): + real_name = example_file.stem # e.g. "config.yaml" from "config.yaml.example" + real_path = plugin_dir / real_name + if not real_path.exists(): + try: + shutil.copy2(example_file, real_path) + console.print( + f"[dim] Created {real_name} from {example_file.name}[/dim]" + ) + except OSError as e: + console.print( + f"[yellow]Warning:[/yellow] Failed to copy {example_file.name}: {e}" + ) + + +def _prompt_plugin_env_vars(manifest: dict, console) -> None: + """Prompt for required environment variables declared in plugin.yaml. + + ``requires_env`` accepts two formats: + + Simple list (backwards-compatible):: + + requires_env: + - MY_API_KEY + + Rich list with metadata:: + + requires_env: + - name: MY_API_KEY + description: "API key for Acme service" + url: "https://acme.com/keys" + secret: true + + Already-set variables are skipped. Values are saved to the user's ``.env``. + """ + requires_env = manifest.get("requires_env") or [] + if not requires_env: + return + + from hermes_cli.config import get_env_value, save_env_value # noqa: F811 + from hermes_constants import display_hermes_home + + # Normalise to list-of-dicts + env_specs: list[dict] = [] + for entry in requires_env: + if isinstance(entry, str): + env_specs.append({"name": entry}) + elif isinstance(entry, dict) and entry.get("name"): + env_specs.append(entry) + + # Filter to only vars that aren't already set + missing = [s for s in env_specs if not get_env_value(s["name"])] + if not missing: + return + + plugin_name = manifest.get("name", "this plugin") + console.print(f"\n[bold]{plugin_name}[/bold] requires the following environment variables:\n") + + for spec in missing: + name = spec["name"] + desc = spec.get("description", "") + url = spec.get("url", "") + secret = spec.get("secret", False) + + label = f" {name}" + if desc: + label += f" — {desc}" + console.print(label) + if url: + console.print(f" [dim]Get yours at: {url}[/dim]") + + try: + if secret: + import getpass + value = getpass.getpass(f" {name}: ").strip() + else: + value = input(f" {name}: ").strip() + except (EOFError, KeyboardInterrupt): + console.print(f"\n[dim] Skipped (you can set these later in {display_hermes_home()}/.env)[/dim]") + return + + if value: + save_env_value(name, value) + os.environ[name] = value + console.print(f" [green]✓[/green] Saved to {display_hermes_home()}/.env") + else: + console.print(f" [dim] Skipped (set {name} in {display_hermes_home()}/.env later)[/dim]") + + console.print() + + +def _display_after_install(plugin_dir: Path, identifier: str) -> None: + """Show after-install.md if it exists, otherwise a default message.""" + from rich.console import Console + from rich.markdown import Markdown + from rich.panel import Panel + + console = Console() + after_install = plugin_dir / "after-install.md" + + if after_install.exists(): + content = after_install.read_text(encoding="utf-8") + md = Markdown(content) + console.print() + console.print(Panel(md, border_style="green", expand=False)) + console.print() + else: + console.print() + console.print( + Panel( + f"[green bold]Plugin installed:[/] {identifier}\n" + f"[dim]Location:[/] {plugin_dir}", + border_style="green", + title="✓ Installed", + expand=False, + ) + ) + console.print() + + +def _display_removed(name: str, plugins_dir: Path) -> None: + """Show confirmation after removing a plugin.""" + from rich.console import Console + + console = Console() + console.print() + console.print(f"[red]✗[/red] Plugin [bold]{name}[/bold] removed from {plugins_dir}") + console.print() + + +def _require_installed_plugin(name: str, plugins_dir: Path, console) -> Path: + """Return the plugin path if it exists, or exit with an error listing installed plugins.""" + target = _sanitize_plugin_name(name, plugins_dir) + if not target.exists(): + installed = ", ".join(d.name for d in plugins_dir.iterdir() if d.is_dir()) or "(none)" + console.print( + f"[red]Error:[/red] Plugin '{name}' not found in {plugins_dir}.\n" + f"Installed plugins: {installed}" + ) + sys.exit(1) + return target + + +# --------------------------------------------------------------------------- +# Commands +# --------------------------------------------------------------------------- + + +def cmd_install(identifier: str, force: bool = False) -> None: + """Install a plugin from a Git URL or owner/repo shorthand.""" + import tempfile + from rich.console import Console + + console = Console() + + try: + git_url = _resolve_git_url(identifier) + except ValueError as e: + console.print(f"[red]Error:[/red] {e}") + sys.exit(1) + + # Warn about insecure / local URL schemes + if git_url.startswith(("http://", "file://")): + console.print( + "[yellow]Warning:[/yellow] Using insecure/local URL scheme. " + "Consider using https:// or git@ for production installs." + ) + + plugins_dir = _plugins_dir() + + # Clone into a temp directory first so we can read plugin.yaml for the name + with tempfile.TemporaryDirectory() as tmp: + tmp_target = Path(tmp) / "plugin" + console.print(f"[dim]Cloning {git_url}...[/dim]") + + try: + result = subprocess.run( + ["git", "clone", "--depth", "1", git_url, str(tmp_target)], + capture_output=True, + text=True, + timeout=60, + ) + except FileNotFoundError: + console.print("[red]Error:[/red] git is not installed or not in PATH.") + sys.exit(1) + except subprocess.TimeoutExpired: + console.print("[red]Error:[/red] Git clone timed out after 60 seconds.") + sys.exit(1) + + if result.returncode != 0: + console.print( + f"[red]Error:[/red] Git clone failed:\n{result.stderr.strip()}" + ) + sys.exit(1) + + # Read manifest + manifest = _read_manifest(tmp_target) + plugin_name = manifest.get("name") or _repo_name_from_url(git_url) + + # Sanitize plugin name against path traversal + try: + target = _sanitize_plugin_name(plugin_name, plugins_dir) + except ValueError as e: + console.print(f"[red]Error:[/red] {e}") + sys.exit(1) + + # Check manifest_version compatibility + mv = manifest.get("manifest_version") + if mv is not None: + try: + mv_int = int(mv) + except (ValueError, TypeError): + console.print( + f"[red]Error:[/red] Plugin '{plugin_name}' has invalid " + f"manifest_version '{mv}' (expected an integer)." + ) + sys.exit(1) + if mv_int > _SUPPORTED_MANIFEST_VERSION: + from hermes_cli.config import recommended_update_command + console.print( + f"[red]Error:[/red] Plugin '{plugin_name}' requires manifest_version " + f"{mv}, but this installer only supports up to {_SUPPORTED_MANIFEST_VERSION}.\n" + f"Run [bold]{recommended_update_command()}[/bold] to get a newer installer." + ) + sys.exit(1) + + if target.exists(): + if not force: + console.print( + f"[red]Error:[/red] Plugin '{plugin_name}' already exists at {target}.\n" + f"Use [bold]--force[/bold] to remove and reinstall, or " + f"[bold]hermes plugins update {plugin_name}[/bold] to pull latest." + ) + sys.exit(1) + console.print(f"[dim] Removing existing {plugin_name}...[/dim]") + shutil.rmtree(target) + + # Move from temp to final location + shutil.move(str(tmp_target), str(target)) + + # Validate it looks like a plugin + if not (target / "plugin.yaml").exists() and not (target / "__init__.py").exists(): + console.print( + f"[yellow]Warning:[/yellow] {plugin_name} doesn't contain plugin.yaml " + f"or __init__.py. It may not be a valid Hermes plugin." + ) + + # Copy .example files to their real names (e.g. config.yaml.example → config.yaml) + _copy_example_files(target, console) + + # Re-read manifest from installed location (for env var prompting) + installed_manifest = _read_manifest(target) + + # Prompt for required environment variables before showing after-install docs + _prompt_plugin_env_vars(installed_manifest, console) + + _display_after_install(target, identifier) + + console.print("[dim]Restart the gateway for the plugin to take effect:[/dim]") + console.print("[dim] hermes gateway restart[/dim]") + console.print() + + +def cmd_update(name: str) -> None: + """Update an installed plugin by pulling latest from its git remote.""" + from rich.console import Console + + console = Console() + plugins_dir = _plugins_dir() + + try: + target = _require_installed_plugin(name, plugins_dir, console) + except ValueError as e: + console.print(f"[red]Error:[/red] {e}") + sys.exit(1) + + if not (target / ".git").exists(): + console.print( + f"[red]Error:[/red] Plugin '{name}' was not installed from git " + f"(no .git directory). Cannot update." + ) + sys.exit(1) + + console.print(f"[dim]Updating {name}...[/dim]") + + try: + result = subprocess.run( + ["git", "pull", "--ff-only"], + capture_output=True, + text=True, + timeout=60, + cwd=str(target), + ) + except FileNotFoundError: + console.print("[red]Error:[/red] git is not installed or not in PATH.") + sys.exit(1) + except subprocess.TimeoutExpired: + console.print("[red]Error:[/red] Git pull timed out after 60 seconds.") + sys.exit(1) + + if result.returncode != 0: + console.print(f"[red]Error:[/red] Git pull failed:\n{result.stderr.strip()}") + sys.exit(1) + + # Copy any new .example files + _copy_example_files(target, console) + + output = result.stdout.strip() + if "Already up to date" in output: + console.print( + f"[green]✓[/green] Plugin [bold]{name}[/bold] is already up to date." + ) + else: + console.print(f"[green]✓[/green] Plugin [bold]{name}[/bold] updated.") + console.print(f"[dim]{output}[/dim]") + + +def cmd_remove(name: str) -> None: + """Remove an installed plugin by name.""" + from rich.console import Console + + console = Console() + plugins_dir = _plugins_dir() + + try: + target = _require_installed_plugin(name, plugins_dir, console) + except ValueError as e: + console.print(f"[red]Error:[/red] {e}") + sys.exit(1) + + shutil.rmtree(target) + _display_removed(name, plugins_dir) + + +def _get_disabled_set() -> set: + """Read the disabled plugins set from config.yaml.""" + try: + from hermes_cli.config import load_config + config = load_config() + disabled = config.get("plugins", {}).get("disabled", []) + return set(disabled) if isinstance(disabled, list) else set() + except Exception: + return set() + + +def _save_disabled_set(disabled: set) -> None: + """Write the disabled plugins list to config.yaml.""" + from hermes_cli.config import load_config, save_config + config = load_config() + if "plugins" not in config: + config["plugins"] = {} + config["plugins"]["disabled"] = sorted(disabled) + save_config(config) + + +def cmd_enable(name: str) -> None: + """Enable a previously disabled plugin.""" + from rich.console import Console + + console = Console() + plugins_dir = _plugins_dir() + + # Verify the plugin exists + target = plugins_dir / name + if not target.is_dir(): + console.print(f"[red]Plugin '{name}' is not installed.[/red]") + sys.exit(1) + + disabled = _get_disabled_set() + if name not in disabled: + console.print(f"[dim]Plugin '{name}' is already enabled.[/dim]") + return + + disabled.discard(name) + _save_disabled_set(disabled) + console.print(f"[green]✓[/green] Plugin [bold]{name}[/bold] enabled. Takes effect on next session.") + + +def cmd_disable(name: str) -> None: + """Disable a plugin without removing it.""" + from rich.console import Console + + console = Console() + plugins_dir = _plugins_dir() + + # Verify the plugin exists + target = plugins_dir / name + if not target.is_dir(): + console.print(f"[red]Plugin '{name}' is not installed.[/red]") + sys.exit(1) + + disabled = _get_disabled_set() + if name in disabled: + console.print(f"[dim]Plugin '{name}' is already disabled.[/dim]") + return + + disabled.add(name) + _save_disabled_set(disabled) + console.print(f"[yellow]\u2298[/yellow] Plugin [bold]{name}[/bold] disabled. Takes effect on next session.") + + +def cmd_list() -> None: + """List installed plugins.""" + from rich.console import Console + from rich.table import Table + + try: + import yaml + except ImportError: + yaml = None + + console = Console() + plugins_dir = _plugins_dir() + + dirs = sorted(d for d in plugins_dir.iterdir() if d.is_dir()) + if not dirs: + console.print("[dim]No plugins installed.[/dim]") + console.print("[dim]Install with:[/dim] hermes plugins install owner/repo") + return + + disabled = _get_disabled_set() + + table = Table(title="Installed Plugins", show_lines=False) + table.add_column("Name", style="bold") + table.add_column("Status") + table.add_column("Version", style="dim") + table.add_column("Description") + table.add_column("Source", style="dim") + + for d in dirs: + manifest_file = d / "plugin.yaml" + name = d.name + version = "" + description = "" + source = "local" + + if manifest_file.exists() and yaml: + try: + with open(manifest_file) as f: + manifest = yaml.safe_load(f) or {} + name = manifest.get("name", d.name) + version = manifest.get("version", "") + description = manifest.get("description", "") + except Exception: + pass + + # Check if it's a git repo (installed via hermes plugins install) + if (d / ".git").exists(): + source = "git" + + is_disabled = name in disabled or d.name in disabled + status = "[red]disabled[/red]" if is_disabled else "[green]enabled[/green]" + table.add_row(name, status, str(version), description, source) + + console.print() + console.print(table) + console.print() + console.print("[dim]Interactive toggle:[/dim] hermes plugins") + console.print("[dim]Enable/disable:[/dim] hermes plugins enable/disable ") + + +# --------------------------------------------------------------------------- +# Provider plugin discovery helpers +# --------------------------------------------------------------------------- + + +def _discover_memory_providers() -> list[tuple[str, str]]: + """Return [(name, description), ...] for available memory providers.""" + try: + from plugins.memory import discover_memory_providers + return [(name, desc) for name, desc, _avail in discover_memory_providers()] + except Exception: + return [] + + +def _discover_context_engines() -> list[tuple[str, str]]: + """Return [(name, description), ...] for available context engines.""" + try: + from plugins.context_engine import discover_context_engines + return [(name, desc) for name, desc, _avail in discover_context_engines()] + except Exception: + return [] + + +def _get_current_memory_provider() -> str: + """Return the current memory.provider from config (empty = built-in).""" + try: + from hermes_cli.config import load_config + config = load_config() + return config.get("memory", {}).get("provider", "") or "" + except Exception: + return "" + + +def _get_current_context_engine() -> str: + """Return the current context.engine from config.""" + try: + from hermes_cli.config import load_config + config = load_config() + return config.get("context", {}).get("engine", "compressor") or "compressor" + except Exception: + return "compressor" + + +def _save_memory_provider(name: str) -> None: + """Persist memory.provider to config.yaml.""" + from hermes_cli.config import load_config, save_config + config = load_config() + if "memory" not in config: + config["memory"] = {} + config["memory"]["provider"] = name + save_config(config) + + +def _save_context_engine(name: str) -> None: + """Persist context.engine to config.yaml.""" + from hermes_cli.config import load_config, save_config + config = load_config() + if "context" not in config: + config["context"] = {} + config["context"]["engine"] = name + save_config(config) + + +def _configure_memory_provider() -> bool: + """Launch a radio picker for memory providers. Returns True if changed.""" + from hermes_cli.curses_ui import curses_radiolist + + current = _get_current_memory_provider() + providers = _discover_memory_providers() + + # Build items: "built-in" first, then discovered providers + items = ["built-in (default)"] + names = [""] # empty string = built-in + selected = 0 + + for name, desc in providers: + names.append(name) + label = f"{name} \u2014 {desc}" if desc else name + items.append(label) + if name == current: + selected = len(items) - 1 + + # If current provider isn't in discovered list, add it + if current and current not in names: + names.append(current) + items.append(f"{current} (not found)") + selected = len(items) - 1 + + choice = curses_radiolist( + title="Memory Provider (select one)", + items=items, + selected=selected, + ) + + new_provider = names[choice] + if new_provider != current: + _save_memory_provider(new_provider) + return True + return False + + +def _configure_context_engine() -> bool: + """Launch a radio picker for context engines. Returns True if changed.""" + from hermes_cli.curses_ui import curses_radiolist + + current = _get_current_context_engine() + engines = _discover_context_engines() + + # Build items: "compressor" first (built-in), then discovered engines + items = ["compressor (default)"] + names = ["compressor"] + selected = 0 + + for name, desc in engines: + names.append(name) + label = f"{name} \u2014 {desc}" if desc else name + items.append(label) + if name == current: + selected = len(items) - 1 + + # If current engine isn't in discovered list and isn't compressor, add it + if current != "compressor" and current not in names: + names.append(current) + items.append(f"{current} (not found)") + selected = len(items) - 1 + + choice = curses_radiolist( + title="Context Engine (select one)", + items=items, + selected=selected, + ) + + new_engine = names[choice] + if new_engine != current: + _save_context_engine(new_engine) + return True + return False + + +# --------------------------------------------------------------------------- +# Composite plugins UI +# --------------------------------------------------------------------------- + + +def cmd_toggle() -> None: + """Interactive composite UI — general plugins + provider plugin categories.""" + from rich.console import Console + + try: + import yaml + except ImportError: + yaml = None + + console = Console() + plugins_dir = _plugins_dir() + + # -- General plugins discovery -- + dirs = sorted(d for d in plugins_dir.iterdir() if d.is_dir()) + disabled = _get_disabled_set() + + plugin_names = [] + plugin_labels = [] + plugin_selected = set() + + for i, d in enumerate(dirs): + manifest_file = d / "plugin.yaml" + name = d.name + description = "" + + if manifest_file.exists() and yaml: + try: + with open(manifest_file) as f: + manifest = yaml.safe_load(f) or {} + name = manifest.get("name", d.name) + description = manifest.get("description", "") + except Exception: + pass + + plugin_names.append(name) + label = f"{name} \u2014 {description}" if description else name + plugin_labels.append(label) + + if name not in disabled and d.name not in disabled: + plugin_selected.add(i) + + # -- Provider categories -- + current_memory = _get_current_memory_provider() or "built-in" + current_context = _get_current_context_engine() + categories = [ + ("Memory Provider", current_memory, _configure_memory_provider), + ("Context Engine", current_context, _configure_context_engine), + ] + + has_plugins = bool(plugin_names) + has_categories = bool(categories) + + if not has_plugins and not has_categories: + console.print("[dim]No plugins installed and no provider categories available.[/dim]") + console.print("[dim]Install with:[/dim] hermes plugins install owner/repo") + return + + # Non-TTY fallback + if not sys.stdin.isatty(): + console.print("[dim]Interactive mode requires a terminal.[/dim]") + return + + # Launch the composite curses UI + try: + import curses + _run_composite_ui(curses, plugin_names, plugin_labels, plugin_selected, + disabled, categories, console) + except ImportError: + _run_composite_fallback(plugin_names, plugin_labels, plugin_selected, + disabled, categories, console) + + +def _run_composite_ui(curses, plugin_names, plugin_labels, plugin_selected, + disabled, categories, console): + """Custom curses screen with checkboxes + category action rows.""" + from hermes_cli.curses_ui import flush_stdin + + chosen = set(plugin_selected) + n_plugins = len(plugin_names) + # Total rows: plugins + separator + categories + # separator is not navigable + n_categories = len(categories) + total_items = n_plugins + n_categories # navigable items + + result_holder = {"plugins_changed": False, "providers_changed": False} + + def _draw(stdscr): + curses.curs_set(0) + if curses.has_colors(): + curses.start_color() + curses.use_default_colors() + curses.init_pair(1, curses.COLOR_GREEN, -1) + curses.init_pair(2, curses.COLOR_YELLOW, -1) + curses.init_pair(3, curses.COLOR_CYAN, -1) + curses.init_pair(4, 8, -1) # dim gray + cursor = 0 + scroll_offset = 0 + + while True: + stdscr.clear() + max_y, max_x = stdscr.getmaxyx() + + # Header + try: + hattr = curses.A_BOLD + if curses.has_colors(): + hattr |= curses.color_pair(2) + stdscr.addnstr(0, 0, "Plugins", max_x - 1, hattr) + stdscr.addnstr( + 1, 0, + " \u2191\u2193 navigate SPACE toggle ENTER configure/confirm ESC done", + max_x - 1, curses.A_DIM, + ) + except curses.error: + pass + + # Build display rows + # Row layout: + # [plugins section header] (not navigable, skipped in scroll math) + # plugin checkboxes (navigable, indices 0..n_plugins-1) + # [separator] (not navigable) + # [categories section header] (not navigable) + # category action rows (navigable, indices n_plugins..total_items-1) + + visible_rows = max_y - 4 + if cursor < scroll_offset: + scroll_offset = cursor + elif cursor >= scroll_offset + visible_rows: + scroll_offset = cursor - visible_rows + 1 + + y = 3 # start drawing after header + + # Determine which items are visible based on scroll + # We need to map logical cursor positions to screen rows + # accounting for non-navigable separator/headers + + draw_row = 0 # tracks navigable item index + + # --- General Plugins section --- + if n_plugins > 0: + # Section header + if y < max_y - 1: + try: + sattr = curses.A_BOLD + if curses.has_colors(): + sattr |= curses.color_pair(2) + stdscr.addnstr(y, 0, " General Plugins", max_x - 1, sattr) + except curses.error: + pass + y += 1 + + for i in range(n_plugins): + if y >= max_y - 1: + break + check = "\u2713" if i in chosen else " " + arrow = "\u2192" if i == cursor else " " + line = f" {arrow} [{check}] {plugin_labels[i]}" + attr = curses.A_NORMAL + if i == cursor: + attr = curses.A_BOLD + if curses.has_colors(): + attr |= curses.color_pair(1) + try: + stdscr.addnstr(y, 0, line, max_x - 1, attr) + except curses.error: + pass + y += 1 + + # --- Separator --- + if y < max_y - 1: + y += 1 # blank line + + # --- Provider Plugins section --- + if n_categories > 0 and y < max_y - 1: + try: + sattr = curses.A_BOLD + if curses.has_colors(): + sattr |= curses.color_pair(2) + stdscr.addnstr(y, 0, " Provider Plugins", max_x - 1, sattr) + except curses.error: + pass + y += 1 + + for ci, (cat_name, cat_current, _cat_fn) in enumerate(categories): + if y >= max_y - 1: + break + cat_idx = n_plugins + ci + arrow = "\u2192" if cat_idx == cursor else " " + line = f" {arrow} {cat_name:<24} \u25b8 {cat_current}" + attr = curses.A_NORMAL + if cat_idx == cursor: + attr = curses.A_BOLD + if curses.has_colors(): + attr |= curses.color_pair(3) + try: + stdscr.addnstr(y, 0, line, max_x - 1, attr) + except curses.error: + pass + y += 1 + + stdscr.refresh() + key = stdscr.getch() + + if key in (curses.KEY_UP, ord("k")): + if total_items > 0: + cursor = (cursor - 1) % total_items + elif key in (curses.KEY_DOWN, ord("j")): + if total_items > 0: + cursor = (cursor + 1) % total_items + elif key == ord(" "): + if cursor < n_plugins: + # Toggle general plugin + chosen.symmetric_difference_update({cursor}) + else: + # Provider category — launch sub-screen + ci = cursor - n_plugins + if 0 <= ci < n_categories: + curses.endwin() + _cat_name, _cat_cur, cat_fn = categories[ci] + changed = cat_fn() + if changed: + result_holder["providers_changed"] = True + # Refresh current values + categories[ci] = ( + _cat_name, + _get_current_memory_provider() or "built-in" if ci == 0 + else _get_current_context_engine(), + cat_fn, + ) + # Re-enter curses + stdscr = curses.initscr() + curses.noecho() + curses.cbreak() + stdscr.keypad(True) + if curses.has_colors(): + curses.start_color() + curses.use_default_colors() + curses.init_pair(1, curses.COLOR_GREEN, -1) + curses.init_pair(2, curses.COLOR_YELLOW, -1) + curses.init_pair(3, curses.COLOR_CYAN, -1) + curses.init_pair(4, 8, -1) + curses.curs_set(0) + elif key in (curses.KEY_ENTER, 10, 13): + if cursor < n_plugins: + # ENTER on a plugin checkbox — confirm and exit + result_holder["plugins_changed"] = True + return + else: + # ENTER on a category — same as SPACE, launch sub-screen + ci = cursor - n_plugins + if 0 <= ci < n_categories: + curses.endwin() + _cat_name, _cat_cur, cat_fn = categories[ci] + changed = cat_fn() + if changed: + result_holder["providers_changed"] = True + categories[ci] = ( + _cat_name, + _get_current_memory_provider() or "built-in" if ci == 0 + else _get_current_context_engine(), + cat_fn, + ) + stdscr = curses.initscr() + curses.noecho() + curses.cbreak() + stdscr.keypad(True) + if curses.has_colors(): + curses.start_color() + curses.use_default_colors() + curses.init_pair(1, curses.COLOR_GREEN, -1) + curses.init_pair(2, curses.COLOR_YELLOW, -1) + curses.init_pair(3, curses.COLOR_CYAN, -1) + curses.init_pair(4, 8, -1) + curses.curs_set(0) + elif key in (27, ord("q")): + # Save plugin changes on exit + result_holder["plugins_changed"] = True + return + + curses.wrapper(_draw) + flush_stdin() + + # Persist general plugin changes + new_disabled = set() + for i, name in enumerate(plugin_names): + if i not in chosen: + new_disabled.add(name) + + if new_disabled != disabled: + _save_disabled_set(new_disabled) + enabled_count = len(plugin_names) - len(new_disabled) + console.print( + f"\n[green]\u2713[/green] General plugins: {enabled_count} enabled, " + f"{len(new_disabled)} disabled." + ) + elif n_plugins > 0: + console.print("\n[dim]General plugins unchanged.[/dim]") + + if result_holder["providers_changed"]: + new_memory = _get_current_memory_provider() or "built-in" + new_context = _get_current_context_engine() + console.print( + f"[green]\u2713[/green] Memory provider: [bold]{new_memory}[/bold] " + f"Context engine: [bold]{new_context}[/bold]" + ) + + if n_plugins > 0 or result_holder["providers_changed"]: + console.print("[dim]Changes take effect on next session.[/dim]") + console.print() + + +def _run_composite_fallback(plugin_names, plugin_labels, plugin_selected, + disabled, categories, console): + """Text-based fallback for the composite plugins UI.""" + from hermes_cli.colors import Colors, color + + print(color("\n Plugins", Colors.YELLOW)) + + # General plugins + if plugin_names: + chosen = set(plugin_selected) + print(color("\n General Plugins", Colors.YELLOW)) + print(color(" Toggle by number, Enter to confirm.\n", Colors.DIM)) + + while True: + for i, label in enumerate(plugin_labels): + marker = color("[\u2713]", Colors.GREEN) if i in chosen else "[ ]" + print(f" {marker} {i + 1:>2}. {label}") + print() + try: + val = input(color(" Toggle # (or Enter to confirm): ", Colors.DIM)).strip() + if not val: + break + idx = int(val) - 1 + if 0 <= idx < len(plugin_names): + chosen.symmetric_difference_update({idx}) + except (ValueError, KeyboardInterrupt, EOFError): + return + print() + + new_disabled = set() + for i, name in enumerate(plugin_names): + if i not in chosen: + new_disabled.add(name) + if new_disabled != disabled: + _save_disabled_set(new_disabled) + + # Provider categories + if categories: + print(color("\n Provider Plugins", Colors.YELLOW)) + for ci, (cat_name, cat_current, cat_fn) in enumerate(categories): + print(f" {ci + 1}. {cat_name} [{cat_current}]") + print() + try: + val = input(color(" Configure # (or Enter to skip): ", Colors.DIM)).strip() + if val: + ci = int(val) - 1 + if 0 <= ci < len(categories): + categories[ci][2]() # call the configure function + except (ValueError, KeyboardInterrupt, EOFError): + pass + + print() + + +def plugins_command(args) -> None: + """Dispatch hermes plugins subcommands.""" + action = getattr(args, "plugins_action", None) + + if action == "install": + cmd_install(args.identifier, force=getattr(args, "force", False)) + elif action == "update": + cmd_update(args.name) + elif action in ("remove", "rm", "uninstall"): + cmd_remove(args.name) + elif action == "enable": + cmd_enable(args.name) + elif action == "disable": + cmd_disable(args.name) + elif action in ("list", "ls"): + cmd_list() + elif action is None: + cmd_toggle() + else: + from rich.console import Console + + Console().print(f"[red]Unknown plugins action: {action}[/red]") + sys.exit(1) diff --git a/mindcli/_vendor/hermes_cli/profiles.py b/mindcli/_vendor/hermes_cli/profiles.py new file mode 100644 index 0000000..1e9fcae --- /dev/null +++ b/mindcli/_vendor/hermes_cli/profiles.py @@ -0,0 +1,1094 @@ +""" +Profile management for multiple isolated Hermes instances. + +Each profile is a fully independent HERMES_HOME directory with its own +config.yaml, .env, memory, sessions, skills, gateway, cron, and logs. +Profiles live under ``~/.hermes/profiles//`` by default. + +The "default" profile is ``~/.hermes`` itself — backward compatible, +zero migration needed. + +Usage:: + + hermes profile create coder # fresh profile + bundled skills + hermes profile create coder --clone # also copy config, .env, SOUL.md + hermes profile create coder --clone-all # full copy of source profile + coder chat # use via wrapper alias + hermes -p coder chat # or via flag + hermes profile use coder # set as sticky default + hermes profile delete coder # remove profile + alias + service +""" + +import json +import os +import re +import shutil +import stat +import subprocess +import sys +from dataclasses import dataclass +from pathlib import Path, PurePosixPath, PureWindowsPath +from typing import List, Optional + +_PROFILE_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$") + +# Directories bootstrapped inside every new profile +_PROFILE_DIRS = [ + "memories", + "sessions", + "skills", + "skins", + "logs", + "plans", + "workspace", + "cron", + # Per-profile HOME for subprocesses: isolates system tool configs (git, + # ssh, gh, npm …) so credentials don't bleed between profiles. In Docker + # this also ensures tool configs land inside the persistent volume. + # See hermes_constants.get_subprocess_home() and issue #4426. + "home", +] + +# Files copied during --clone (if they exist in the source) +_CLONE_CONFIG_FILES = [ + "config.yaml", + ".env", + "SOUL.md", +] + +# Subdirectory files copied during --clone (path relative to profile root). +# Memory files are part of the agent's curated identity — just as important +# as SOUL.md for continuity when cloning a profile. +_CLONE_SUBDIR_FILES = [ + "memories/MEMORY.md", + "memories/USER.md", +] + +# Runtime files stripped after --clone-all (shouldn't carry over) +_CLONE_ALL_STRIP = [ + "gateway.pid", + "gateway_state.json", + "processes.json", +] + +# Directories/files to exclude when exporting the default (~/.hermes) profile. +# The default profile contains infrastructure (repo checkout, worktrees, DBs, +# caches, binaries) that named profiles don't have. We exclude those so the +# export is a portable, reasonable-size archive of actual profile data. +_DEFAULT_EXPORT_EXCLUDE_ROOT = frozenset({ + # Infrastructure + "hermes-agent", # repo checkout (multi-GB) + ".worktrees", # git worktrees + "profiles", # other profiles — never recursive-export + "bin", # installed binaries (tirith, etc.) + "node_modules", # npm packages + # Databases & runtime state + "state.db", "state.db-shm", "state.db-wal", + "hermes_state.db", + "response_store.db", "response_store.db-shm", "response_store.db-wal", + "gateway.pid", "gateway_state.json", "processes.json", + "auth.json", # API keys, OAuth tokens, credential pools + ".env", # API keys (dotenv) + "auth.lock", "active_profile", ".update_check", + "errors.log", + ".hermes_history", + # Caches (regenerated on use) + "image_cache", "audio_cache", "document_cache", + "browser_screenshots", "checkpoints", + "sandboxes", + "logs", # gateway logs +}) + +# Names that cannot be used as profile aliases +_RESERVED_NAMES = frozenset({ + "hermes", "default", "test", "tmp", "root", "sudo", +}) + +# Hermes subcommands that cannot be used as profile names/aliases +_HERMES_SUBCOMMANDS = frozenset({ + "chat", "model", "gateway", "setup", "whatsapp", "login", "logout", + "status", "cron", "doctor", "dump", "config", "pairing", "skills", "tools", + "mcp", "sessions", "insights", "version", "update", "uninstall", + "profile", "plugins", "honcho", "acp", +}) + + +# --------------------------------------------------------------------------- +# Path helpers +# --------------------------------------------------------------------------- + +def _get_profiles_root() -> Path: + """Return the directory where named profiles are stored. + + Anchored to the hermes root, NOT to the current HERMES_HOME + (which may itself be a profile). This ensures ``coder profile list`` + can see all profiles. + + In Docker/custom deployments where HERMES_HOME points outside + ``~/.hermes``, profiles live under ``HERMES_HOME/profiles/`` so + they persist on the mounted volume. + """ + return _get_default_hermes_home() / "profiles" + + +def _get_default_hermes_home() -> Path: + """Return the default (pre-profile) HERMES_HOME path. + + In standard deployments this is ``~/.hermes``. + In Docker/custom deployments where HERMES_HOME is outside ``~/.hermes`` + (e.g. ``/opt/data``), returns HERMES_HOME directly. + """ + from hermes_constants import get_default_hermes_root + return get_default_hermes_root() + + +def _get_active_profile_path() -> Path: + """Return the path to the sticky active_profile file.""" + return _get_default_hermes_home() / "active_profile" + + +def _get_wrapper_dir() -> Path: + """Return the directory for wrapper scripts.""" + return Path.home() / ".local" / "bin" + + +# --------------------------------------------------------------------------- +# Validation +# --------------------------------------------------------------------------- + +def validate_profile_name(name: str) -> None: + """Raise ``ValueError`` if *name* is not a valid profile identifier.""" + if name == "default": + return # special alias for ~/.hermes + if not _PROFILE_ID_RE.match(name): + raise ValueError( + f"Invalid profile name {name!r}. Must match " + f"[a-z0-9][a-z0-9_-]{{0,63}}" + ) + + +def get_profile_dir(name: str) -> Path: + """Resolve a profile name to its HERMES_HOME directory.""" + if name == "default": + return _get_default_hermes_home() + return _get_profiles_root() / name + + +def profile_exists(name: str) -> bool: + """Check whether a profile directory exists.""" + if name == "default": + return True + return get_profile_dir(name).is_dir() + + +# --------------------------------------------------------------------------- +# Alias / wrapper script management +# --------------------------------------------------------------------------- + +def check_alias_collision(name: str) -> Optional[str]: + """Return a human-readable collision message, or None if the name is safe. + + Checks: reserved names, hermes subcommands, existing binaries in PATH. + """ + if name in _RESERVED_NAMES: + return f"'{name}' is a reserved name" + if name in _HERMES_SUBCOMMANDS: + return f"'{name}' conflicts with a hermes subcommand" + + # Check existing commands in PATH + wrapper_dir = _get_wrapper_dir() + try: + result = subprocess.run( + ["which", name], capture_output=True, text=True, timeout=5, + ) + if result.returncode == 0: + existing_path = result.stdout.strip() + # Allow overwriting our own wrappers + if existing_path == str(wrapper_dir / name): + try: + content = (wrapper_dir / name).read_text() + if "hermes -p" in content: + return None # it's our wrapper, safe to overwrite + except Exception: + pass + return f"'{name}' conflicts with an existing command ({existing_path})" + except (FileNotFoundError, subprocess.TimeoutExpired): + pass + + return None # safe + + +def _is_wrapper_dir_in_path() -> bool: + """Check if ~/.local/bin is in PATH.""" + wrapper_dir = str(_get_wrapper_dir()) + return wrapper_dir in os.environ.get("PATH", "").split(os.pathsep) + + +def create_wrapper_script(name: str) -> Optional[Path]: + """Create a shell wrapper script at ~/.local/bin/. + + Returns the path to the created wrapper, or None if creation failed. + """ + wrapper_dir = _get_wrapper_dir() + try: + wrapper_dir.mkdir(parents=True, exist_ok=True) + except OSError as e: + print(f"⚠ Could not create {wrapper_dir}: {e}") + return None + + wrapper_path = wrapper_dir / name + try: + wrapper_path.write_text(f'#!/bin/sh\nexec hermes -p {name} "$@"\n') + wrapper_path.chmod(wrapper_path.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH) + return wrapper_path + except OSError as e: + print(f"⚠ Could not create wrapper at {wrapper_path}: {e}") + return None + + +def remove_wrapper_script(name: str) -> bool: + """Remove the wrapper script for a profile. Returns True if removed.""" + wrapper_path = _get_wrapper_dir() / name + if wrapper_path.exists(): + try: + # Verify it's our wrapper before removing + content = wrapper_path.read_text() + if "hermes -p" in content: + wrapper_path.unlink() + return True + except Exception: + pass + return False + + +# --------------------------------------------------------------------------- +# ProfileInfo +# --------------------------------------------------------------------------- + +@dataclass +class ProfileInfo: + """Summary information about a profile.""" + name: str + path: Path + is_default: bool + gateway_running: bool + model: Optional[str] = None + provider: Optional[str] = None + has_env: bool = False + skill_count: int = 0 + alias_path: Optional[Path] = None + + +def _read_config_model(profile_dir: Path) -> tuple: + """Read model/provider from a profile's config.yaml. Returns (model, provider).""" + config_path = profile_dir / "config.yaml" + if not config_path.exists(): + return None, None + try: + import yaml + with open(config_path, "r") as f: + cfg = yaml.safe_load(f) or {} + model_cfg = cfg.get("model", {}) + if isinstance(model_cfg, str): + return model_cfg, None + if isinstance(model_cfg, dict): + return model_cfg.get("default") or model_cfg.get("model"), model_cfg.get("provider") + return None, None + except Exception: + return None, None + + +def _check_gateway_running(profile_dir: Path) -> bool: + """Check if a gateway is running for a given profile directory.""" + pid_file = profile_dir / "gateway.pid" + if not pid_file.exists(): + return False + try: + raw = pid_file.read_text().strip() + if not raw: + return False + data = json.loads(raw) if raw.startswith("{") else {"pid": int(raw)} + pid = int(data["pid"]) + os.kill(pid, 0) # existence check + return True + except (json.JSONDecodeError, KeyError, ValueError, TypeError, + ProcessLookupError, PermissionError, OSError): + return False + + +def _count_skills(profile_dir: Path) -> int: + """Count installed skills in a profile.""" + skills_dir = profile_dir / "skills" + if not skills_dir.is_dir(): + return 0 + count = 0 + for md in skills_dir.rglob("SKILL.md"): + if "/.hub/" not in str(md) and "/.git/" not in str(md): + count += 1 + return count + + +# --------------------------------------------------------------------------- +# CRUD operations +# --------------------------------------------------------------------------- + +def list_profiles() -> List[ProfileInfo]: + """Return info for all profiles, including the default.""" + profiles = [] + wrapper_dir = _get_wrapper_dir() + + # Default profile + default_home = _get_default_hermes_home() + if default_home.is_dir(): + model, provider = _read_config_model(default_home) + profiles.append(ProfileInfo( + name="default", + path=default_home, + is_default=True, + gateway_running=_check_gateway_running(default_home), + model=model, + provider=provider, + has_env=(default_home / ".env").exists(), + skill_count=_count_skills(default_home), + )) + + # Named profiles + profiles_root = _get_profiles_root() + if profiles_root.is_dir(): + for entry in sorted(profiles_root.iterdir()): + if not entry.is_dir(): + continue + name = entry.name + if not _PROFILE_ID_RE.match(name): + continue + model, provider = _read_config_model(entry) + alias_path = wrapper_dir / name + profiles.append(ProfileInfo( + name=name, + path=entry, + is_default=False, + gateway_running=_check_gateway_running(entry), + model=model, + provider=provider, + has_env=(entry / ".env").exists(), + skill_count=_count_skills(entry), + alias_path=alias_path if alias_path.exists() else None, + )) + + return profiles + + +def create_profile( + name: str, + clone_from: Optional[str] = None, + clone_all: bool = False, + clone_config: bool = False, + no_alias: bool = False, +) -> Path: + """Create a new profile directory. + + Parameters + ---------- + name: + Profile identifier (lowercase, alphanumeric, hyphens, underscores). + clone_from: + Source profile to clone from. If ``None`` and clone_config/clone_all + is True, defaults to the currently active profile. + clone_all: + If True, do a full copytree of the source (all state). + clone_config: + If True, copy only config files (config.yaml, .env, SOUL.md). + no_alias: + If True, skip wrapper script creation. + + Returns + ------- + Path + The newly created profile directory. + """ + validate_profile_name(name) + + if name == "default": + raise ValueError( + "Cannot create a profile named 'default' — it is the built-in profile (~/.hermes)." + ) + + profile_dir = get_profile_dir(name) + if profile_dir.exists(): + raise FileExistsError(f"Profile '{name}' already exists at {profile_dir}") + + # Resolve clone source + source_dir = None + if clone_from is not None or clone_all or clone_config: + if clone_from is None: + # Default: clone from active profile + from hermes_constants import get_hermes_home + source_dir = get_hermes_home() + else: + validate_profile_name(clone_from) + source_dir = get_profile_dir(clone_from) + if not source_dir.is_dir(): + raise FileNotFoundError( + f"Source profile '{clone_from or 'active'}' does not exist at {source_dir}" + ) + + if clone_all and source_dir: + # Full copy of source profile + shutil.copytree(source_dir, profile_dir) + # Strip runtime files + for stale in _CLONE_ALL_STRIP: + (profile_dir / stale).unlink(missing_ok=True) + else: + # Bootstrap directory structure + profile_dir.mkdir(parents=True, exist_ok=True) + for subdir in _PROFILE_DIRS: + (profile_dir / subdir).mkdir(parents=True, exist_ok=True) + + # Clone config files from source + if source_dir is not None: + for filename in _CLONE_CONFIG_FILES: + src = source_dir / filename + if src.exists(): + shutil.copy2(src, profile_dir / filename) + + # Clone memory and other subdirectory files + for relpath in _CLONE_SUBDIR_FILES: + src = source_dir / relpath + if src.exists(): + dst = profile_dir / relpath + dst.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(src, dst) + + # Seed a default SOUL.md so the user has a file to customize immediately. + # Skipped when the profile already has one (from --clone / --clone-all). + soul_path = profile_dir / "SOUL.md" + if not soul_path.exists(): + try: + from hermes_cli.default_soul import DEFAULT_SOUL_MD + soul_path.write_text(DEFAULT_SOUL_MD, encoding="utf-8") + except Exception: + pass # best-effort — don't fail profile creation over this + + return profile_dir + + +def seed_profile_skills(profile_dir: Path, quiet: bool = False) -> Optional[dict]: + """Seed bundled skills into a profile via subprocess. + + Uses subprocess because sync_skills() caches HERMES_HOME at module level. + Returns the sync result dict, or None on failure. + """ + project_root = Path(__file__).parent.parent.resolve() + try: + result = subprocess.run( + [sys.executable, "-c", + "import json; from tools.skills_sync import sync_skills; " + "r = sync_skills(quiet=True); print(json.dumps(r))"], + env={**os.environ, "HERMES_HOME": str(profile_dir)}, + cwd=str(project_root), + capture_output=True, text=True, timeout=60, + ) + if result.returncode == 0 and result.stdout.strip(): + return json.loads(result.stdout.strip()) + if not quiet: + print(f"⚠ Skill seeding returned exit code {result.returncode}") + if result.stderr.strip(): + print(f" {result.stderr.strip()[:200]}") + return None + except subprocess.TimeoutExpired: + if not quiet: + print("⚠ Skill seeding timed out (60s)") + return None + except Exception as e: + if not quiet: + print(f"⚠ Skill seeding failed: {e}") + return None + + +def delete_profile(name: str, yes: bool = False) -> Path: + """Delete a profile, its wrapper script, and its gateway service. + + Stops the gateway if running. Disables systemd/launchd service first + to prevent auto-restart. + + Returns the path that was removed. + """ + validate_profile_name(name) + + if name == "default": + raise ValueError( + "Cannot delete the default profile (~/.hermes).\n" + "To remove everything, use: hermes uninstall" + ) + + profile_dir = get_profile_dir(name) + if not profile_dir.is_dir(): + raise FileNotFoundError(f"Profile '{name}' does not exist.") + + # Show what will be deleted + model, provider = _read_config_model(profile_dir) + gw_running = _check_gateway_running(profile_dir) + skill_count = _count_skills(profile_dir) + + print(f"\nProfile: {name}") + print(f"Path: {profile_dir}") + if model: + print(f"Model: {model}" + (f" ({provider})" if provider else "")) + if skill_count: + print(f"Skills: {skill_count}") + + items = [ + "All config, API keys, memories, sessions, skills, cron jobs", + ] + + # Check for service + wrapper_path = _get_wrapper_dir() / name + has_wrapper = wrapper_path.exists() + if has_wrapper: + items.append(f"Command alias ({wrapper_path})") + + print(f"\nThis will permanently delete:") + for item in items: + print(f" • {item}") + if gw_running: + print(f" ⚠ Gateway is running — it will be stopped.") + + # Confirmation + if not yes: + print() + try: + confirm = input(f"Type '{name}' to confirm: ").strip() + except (KeyboardInterrupt, EOFError): + print("\nCancelled.") + return profile_dir + if confirm != name: + print("Cancelled.") + return profile_dir + + # 1. Disable service (prevents auto-restart) + _cleanup_gateway_service(name, profile_dir) + + # 2. Stop running gateway + if gw_running: + _stop_gateway_process(profile_dir) + + # 3. Remove wrapper script + if has_wrapper: + if remove_wrapper_script(name): + print(f"✓ Removed {wrapper_path}") + + # 4. Remove profile directory + try: + shutil.rmtree(profile_dir) + print(f"✓ Removed {profile_dir}") + except Exception as e: + print(f"⚠ Could not remove {profile_dir}: {e}") + + # 5. Clear active_profile if it pointed to this profile + try: + active = get_active_profile() + if active == name: + set_active_profile("default") + print("✓ Active profile reset to default") + except Exception: + pass + + print(f"\nProfile '{name}' deleted.") + return profile_dir + + +def _cleanup_gateway_service(name: str, profile_dir: Path) -> None: + """Disable and remove systemd/launchd service for a profile.""" + import platform as _platform + + # Derive service name for this profile + # Temporarily set HERMES_HOME so _profile_suffix resolves correctly + old_home = os.environ.get("HERMES_HOME") + try: + os.environ["HERMES_HOME"] = str(profile_dir) + from hermes_cli.gateway import get_service_name, get_launchd_plist_path + + if _platform.system() == "Linux": + svc_name = get_service_name() + svc_file = Path.home() / ".config" / "systemd" / "user" / f"{svc_name}.service" + if svc_file.exists(): + subprocess.run( + ["systemctl", "--user", "disable", svc_name], + capture_output=True, check=False, timeout=10, + ) + subprocess.run( + ["systemctl", "--user", "stop", svc_name], + capture_output=True, check=False, timeout=10, + ) + svc_file.unlink(missing_ok=True) + subprocess.run( + ["systemctl", "--user", "daemon-reload"], + capture_output=True, check=False, timeout=10, + ) + print(f"✓ Service {svc_name} removed") + + elif _platform.system() == "Darwin": + plist_path = get_launchd_plist_path() + if plist_path.exists(): + subprocess.run( + ["launchctl", "unload", str(plist_path)], + capture_output=True, check=False, timeout=10, + ) + plist_path.unlink(missing_ok=True) + print(f"✓ Launchd service removed") + except Exception as e: + print(f"⚠ Service cleanup: {e}") + finally: + if old_home is not None: + os.environ["HERMES_HOME"] = old_home + elif "HERMES_HOME" in os.environ: + del os.environ["HERMES_HOME"] + + +def _stop_gateway_process(profile_dir: Path) -> None: + """Stop a running gateway process via its PID file.""" + import signal as _signal + import time as _time + + pid_file = profile_dir / "gateway.pid" + if not pid_file.exists(): + return + + try: + raw = pid_file.read_text().strip() + data = json.loads(raw) if raw.startswith("{") else {"pid": int(raw)} + pid = int(data["pid"]) + os.kill(pid, _signal.SIGTERM) + # Wait up to 10s for graceful shutdown + for _ in range(20): + _time.sleep(0.5) + try: + os.kill(pid, 0) + except ProcessLookupError: + print(f"✓ Gateway stopped (PID {pid})") + return + # Force kill + try: + os.kill(pid, _signal.SIGKILL) + except ProcessLookupError: + pass + print(f"✓ Gateway force-stopped (PID {pid})") + except (ProcessLookupError, PermissionError): + print("✓ Gateway already stopped") + except Exception as e: + print(f"⚠ Could not stop gateway: {e}") + + +# --------------------------------------------------------------------------- +# Active profile (sticky default) +# --------------------------------------------------------------------------- + +def get_active_profile() -> str: + """Read the sticky active profile name. + + Returns ``"default"`` if no active_profile file exists or it's empty. + """ + path = _get_active_profile_path() + try: + name = path.read_text().strip() + if not name: + return "default" + return name + except (FileNotFoundError, UnicodeDecodeError, OSError): + return "default" + + +def set_active_profile(name: str) -> None: + """Set the sticky active profile. + + Writes to ``~/.hermes/active_profile``. Use ``"default"`` to clear. + """ + validate_profile_name(name) + if name != "default" and not profile_exists(name): + raise FileNotFoundError( + f"Profile '{name}' does not exist. " + f"Create it with: hermes profile create {name}" + ) + + path = _get_active_profile_path() + path.parent.mkdir(parents=True, exist_ok=True) + if name == "default": + # Remove the file to indicate default + path.unlink(missing_ok=True) + else: + # Atomic write + tmp = path.with_suffix(".tmp") + tmp.write_text(name + "\n") + tmp.replace(path) + + +def get_active_profile_name() -> str: + """Infer the current profile name from HERMES_HOME. + + Returns ``"default"`` if HERMES_HOME is not set or points to ``~/.hermes``. + Returns the profile name if HERMES_HOME points into ``~/.hermes/profiles/``. + Returns ``"custom"`` if HERMES_HOME is set to an unrecognized path. + """ + from hermes_constants import get_hermes_home + hermes_home = get_hermes_home() + resolved = hermes_home.resolve() + + default_resolved = _get_default_hermes_home().resolve() + if resolved == default_resolved: + return "default" + + profiles_root = _get_profiles_root().resolve() + try: + rel = resolved.relative_to(profiles_root) + parts = rel.parts + if len(parts) == 1 and _PROFILE_ID_RE.match(parts[0]): + return parts[0] + except ValueError: + pass + + return "custom" + + +# --------------------------------------------------------------------------- +# Export / Import +# --------------------------------------------------------------------------- + +def _default_export_ignore(root_dir: Path): + """Return an *ignore* callable for :func:`shutil.copytree`. + + At the root level it excludes everything in ``_DEFAULT_EXPORT_EXCLUDE_ROOT``. + At all levels it excludes ``__pycache__``, sockets, and temp files. + """ + + def _ignore(directory: str, contents: list) -> set: + ignored: set = set() + for entry in contents: + # Universal exclusions (any depth) + if entry == "__pycache__" or entry.endswith((".sock", ".tmp")): + ignored.add(entry) + # npm lockfiles can appear at root + elif entry in ("package.json", "package-lock.json"): + ignored.add(entry) + # Root-level exclusions + if Path(directory) == root_dir: + ignored.update(c for c in contents if c in _DEFAULT_EXPORT_EXCLUDE_ROOT) + return ignored + + return _ignore + + +def export_profile(name: str, output_path: str) -> Path: + """Export a profile to a tar.gz archive. + + Returns the output file path. + """ + import tempfile + + validate_profile_name(name) + profile_dir = get_profile_dir(name) + if not profile_dir.is_dir(): + raise FileNotFoundError(f"Profile '{name}' does not exist.") + + output = Path(output_path) + # shutil.make_archive wants the base name without extension + base = str(output).removesuffix(".tar.gz").removesuffix(".tgz") + + if name == "default": + # The default profile IS ~/.hermes itself — its parent is ~/ and its + # directory name is ".hermes", not "default". We stage a clean copy + # under a temp dir so the archive contains ``default/...``. + with tempfile.TemporaryDirectory() as tmpdir: + staged = Path(tmpdir) / "default" + shutil.copytree( + profile_dir, + staged, + ignore=_default_export_ignore(profile_dir), + ) + result = shutil.make_archive(base, "gztar", tmpdir, "default") + return Path(result) + + # Named profiles — stage a filtered copy to exclude credentials + with tempfile.TemporaryDirectory() as tmpdir: + staged = Path(tmpdir) / name + _CREDENTIAL_FILES = {"auth.json", ".env"} + shutil.copytree( + profile_dir, + staged, + ignore=lambda d, contents: _CREDENTIAL_FILES & set(contents), + ) + result = shutil.make_archive(base, "gztar", tmpdir, name) + return Path(result) + + +def _normalize_profile_archive_parts(member_name: str) -> List[str]: + """Return safe path parts for a profile archive member.""" + normalized_name = member_name.replace("\\", "/") + posix_path = PurePosixPath(normalized_name) + windows_path = PureWindowsPath(member_name) + + if ( + not normalized_name + or posix_path.is_absolute() + or windows_path.is_absolute() + or windows_path.drive + ): + raise ValueError(f"Unsafe archive member path: {member_name}") + + parts = [part for part in posix_path.parts if part not in ("", ".")] + if not parts or any(part == ".." for part in parts): + raise ValueError(f"Unsafe archive member path: {member_name}") + return parts + + +def _safe_extract_profile_archive(archive: Path, destination: Path) -> None: + """Extract a profile archive without allowing path escapes or links.""" + import tarfile + + with tarfile.open(archive, "r:gz") as tf: + for member in tf.getmembers(): + parts = _normalize_profile_archive_parts(member.name) + target = destination.joinpath(*parts) + + if member.isdir(): + target.mkdir(parents=True, exist_ok=True) + continue + + if not member.isfile(): + raise ValueError( + f"Unsupported archive member type: {member.name}" + ) + + target.parent.mkdir(parents=True, exist_ok=True) + extracted = tf.extractfile(member) + if extracted is None: + raise ValueError(f"Cannot read archive member: {member.name}") + + with extracted, open(target, "wb") as dst: + shutil.copyfileobj(extracted, dst) + + try: + os.chmod(target, member.mode & 0o777) + except OSError: + pass + + +def import_profile(archive_path: str, name: Optional[str] = None) -> Path: + """Import a profile from a tar.gz archive. + + If *name* is not given, infers it from the archive's top-level directory. + Returns the imported profile directory. + """ + import tarfile + + archive = Path(archive_path) + if not archive.exists(): + raise FileNotFoundError(f"Archive not found: {archive}") + + # Peek at the archive to find the top-level directory name + with tarfile.open(archive, "r:gz") as tf: + top_dirs = { + parts[0] + for member in tf.getmembers() + for parts in [_normalize_profile_archive_parts(member.name)] + if len(parts) > 1 or member.isdir() + } + if not top_dirs: + top_dirs = { + _normalize_profile_archive_parts(member.name)[0] + for member in tf.getmembers() + if member.isdir() + } + + inferred_name = name or (top_dirs.pop() if len(top_dirs) == 1 else None) + if not inferred_name: + raise ValueError( + "Cannot determine profile name from archive. " + "Specify it explicitly: hermes profile import --name " + ) + + # Archives exported from the default profile have "default/" as top-level + # dir. Importing as "default" would target ~/.hermes itself — disallow + # that and guide the user toward a named profile. + if inferred_name == "default": + raise ValueError( + "Cannot import as 'default' — that is the built-in root profile (~/.hermes). " + "Specify a different name: hermes profile import --name " + ) + + validate_profile_name(inferred_name) + profile_dir = get_profile_dir(inferred_name) + if profile_dir.exists(): + raise FileExistsError(f"Profile '{inferred_name}' already exists at {profile_dir}") + + profiles_root = _get_profiles_root() + profiles_root.mkdir(parents=True, exist_ok=True) + + _safe_extract_profile_archive(archive, profiles_root) + + # If the archive extracted under a different name, rename + extracted = profiles_root / (top_dirs.pop() if top_dirs else inferred_name) + if extracted != profile_dir and extracted.exists(): + extracted.rename(profile_dir) + + return profile_dir + + +# --------------------------------------------------------------------------- +# Rename +# --------------------------------------------------------------------------- + +def rename_profile(old_name: str, new_name: str) -> Path: + """Rename a profile: directory, wrapper script, service, active_profile. + + Returns the new profile directory. + """ + validate_profile_name(old_name) + validate_profile_name(new_name) + + if old_name == "default": + raise ValueError("Cannot rename the default profile.") + if new_name == "default": + raise ValueError("Cannot rename to 'default' — it is reserved.") + + old_dir = get_profile_dir(old_name) + new_dir = get_profile_dir(new_name) + + if not old_dir.is_dir(): + raise FileNotFoundError(f"Profile '{old_name}' does not exist.") + if new_dir.exists(): + raise FileExistsError(f"Profile '{new_name}' already exists.") + + # 1. Stop gateway if running + if _check_gateway_running(old_dir): + _cleanup_gateway_service(old_name, old_dir) + _stop_gateway_process(old_dir) + + # 2. Rename directory + old_dir.rename(new_dir) + print(f"✓ Renamed {old_dir.name} → {new_dir.name}") + + # 3. Update wrapper script + remove_wrapper_script(old_name) + collision = check_alias_collision(new_name) + if not collision: + create_wrapper_script(new_name) + print(f"✓ Alias updated: {new_name}") + else: + print(f"⚠ Cannot create alias '{new_name}' — {collision}") + + # 4. Update active_profile if it pointed to old name + try: + if get_active_profile() == old_name: + set_active_profile(new_name) + print(f"✓ Active profile updated: {new_name}") + except Exception: + pass + + return new_dir + + +# --------------------------------------------------------------------------- +# Tab completion +# --------------------------------------------------------------------------- + +def generate_bash_completion() -> str: + """Generate a bash completion script for hermes profile names.""" + return '''# Hermes Agent profile completion +# Add to ~/.bashrc: eval "$(hermes completion bash)" + +_hermes_profiles() { + local profiles_dir="$HOME/.hermes/profiles" + local profiles="default" + if [ -d "$profiles_dir" ]; then + profiles="$profiles $(ls "$profiles_dir" 2>/dev/null)" + fi + echo "$profiles" +} + +_hermes_completion() { + local cur prev + cur="${COMP_WORDS[COMP_CWORD]}" + prev="${COMP_WORDS[COMP_CWORD-1]}" + + # Complete profile names after -p / --profile + if [[ "$prev" == "-p" || "$prev" == "--profile" ]]; then + COMPREPLY=($(compgen -W "$(_hermes_profiles)" -- "$cur")) + return + fi + + # Complete profile subcommands + if [[ "${COMP_WORDS[1]}" == "profile" ]]; then + case "$prev" in + profile) + COMPREPLY=($(compgen -W "list use create delete show alias rename export import" -- "$cur")) + return + ;; + use|delete|show|alias|rename|export) + COMPREPLY=($(compgen -W "$(_hermes_profiles)" -- "$cur")) + return + ;; + esac + fi + + # Top-level subcommands + if [[ "$COMP_CWORD" == 1 ]]; then + local commands="chat model gateway setup status cron doctor dump config skills tools mcp sessions profile update version" + COMPREPLY=($(compgen -W "$commands" -- "$cur")) + fi +} + +complete -F _hermes_completion hermes +''' + + +def generate_zsh_completion() -> str: + """Generate a zsh completion script for hermes profile names.""" + return '''#compdef hermes +# Hermes Agent profile completion +# Add to ~/.zshrc: eval "$(hermes completion zsh)" + +_hermes() { + local -a profiles + profiles=(default) + if [[ -d "$HOME/.hermes/profiles" ]]; then + profiles+=("${(@f)$(ls $HOME/.hermes/profiles 2>/dev/null)}") + fi + + _arguments \\ + '-p[Profile name]:profile:($profiles)' \\ + '--profile[Profile name]:profile:($profiles)' \\ + '1:command:(chat model gateway setup status cron doctor dump config skills tools mcp sessions profile update version)' \\ + '*::arg:->args' + + case $words[1] in + profile) + _arguments '1:action:(list use create delete show alias rename export import)' \\ + '2:profile:($profiles)' + ;; + esac +} + +_hermes "$@" +''' + + +# --------------------------------------------------------------------------- +# Profile env resolution (called from _apply_profile_override) +# --------------------------------------------------------------------------- + +def resolve_profile_env(profile_name: str) -> str: + """Resolve a profile name to a HERMES_HOME path string. + + Called early in the CLI entry point, before any hermes modules + are imported, to set the HERMES_HOME environment variable. + """ + validate_profile_name(profile_name) + profile_dir = get_profile_dir(profile_name) + + if profile_name != "default" and not profile_dir.is_dir(): + raise FileNotFoundError( + f"Profile '{profile_name}' does not exist. " + f"Create it with: hermes profile create {profile_name}" + ) + + return str(profile_dir) diff --git a/mindcli/_vendor/hermes_cli/providers.py b/mindcli/_vendor/hermes_cli/providers.py new file mode 100644 index 0000000..6fb940d --- /dev/null +++ b/mindcli/_vendor/hermes_cli/providers.py @@ -0,0 +1,553 @@ +""" +Single source of truth for provider identity in Hermes Agent. + +Two data sources, merged at runtime: + +1. **models.dev catalog** — 109+ providers with base URLs, env vars, display + names, and full model metadata (context, cost, capabilities). This is + the primary database. + +2. **Hermes overlays** — transport type, auth patterns, aggregator flags, + and additional env vars that models.dev doesn't track. Small dict, + maintained here. + +3. **User config** (``providers:`` section in config.yaml) — user-defined + endpoints and overrides. Merged on top of everything else. + +Other modules import from this file. No parallel registries. +""" + +from __future__ import annotations + +import logging +from dataclasses import dataclass +from typing import Any, Dict, List, Optional, Tuple + +logger = logging.getLogger(__name__) + + +# -- Hermes overlay ---------------------------------------------------------- +# Hermes-specific metadata that models.dev doesn't provide. + +@dataclass(frozen=True) +class HermesOverlay: + """Hermes-specific provider metadata layered on top of models.dev.""" + + transport: str = "openai_chat" # openai_chat | anthropic_messages | codex_responses + is_aggregator: bool = False + auth_type: str = "api_key" # api_key | oauth_device_code | oauth_external | external_process + extra_env_vars: Tuple[str, ...] = () # env vars models.dev doesn't list + base_url_override: str = "" # override if models.dev URL is wrong/missing + base_url_env_var: str = "" # env var for user-custom base URL + + +HERMES_OVERLAYS: Dict[str, HermesOverlay] = { + "openrouter": HermesOverlay( + transport="openai_chat", + is_aggregator=True, + extra_env_vars=("OPENAI_API_KEY",), + base_url_env_var="OPENROUTER_BASE_URL", + ), + "nous": HermesOverlay( + transport="openai_chat", + auth_type="oauth_device_code", + base_url_override="https://inference-api.nousresearch.com/v1", + ), + "openai-codex": HermesOverlay( + transport="codex_responses", + auth_type="oauth_external", + base_url_override="https://chatgpt.com/backend-api/codex", + ), + "qwen-oauth": HermesOverlay( + transport="openai_chat", + auth_type="oauth_external", + base_url_override="https://portal.qwen.ai/v1", + base_url_env_var="HERMES_QWEN_BASE_URL", + ), + "copilot-acp": HermesOverlay( + transport="codex_responses", + auth_type="external_process", + base_url_override="acp://copilot", + base_url_env_var="COPILOT_ACP_BASE_URL", + ), + "github-copilot": HermesOverlay( + transport="openai_chat", + extra_env_vars=("COPILOT_GITHUB_TOKEN", "GH_TOKEN"), + ), + "anthropic": HermesOverlay( + transport="anthropic_messages", + extra_env_vars=("ANTHROPIC_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"), + ), + "zai": HermesOverlay( + transport="openai_chat", + extra_env_vars=("GLM_API_KEY", "ZAI_API_KEY", "Z_AI_API_KEY"), + base_url_env_var="GLM_BASE_URL", + ), + "kimi-for-coding": HermesOverlay( + transport="openai_chat", + base_url_env_var="KIMI_BASE_URL", + ), + "minimax": HermesOverlay( + transport="anthropic_messages", + base_url_env_var="MINIMAX_BASE_URL", + ), + "minimax-cn": HermesOverlay( + transport="anthropic_messages", + base_url_env_var="MINIMAX_CN_BASE_URL", + ), + "deepseek": HermesOverlay( + transport="openai_chat", + base_url_env_var="DEEPSEEK_BASE_URL", + ), + "alibaba": HermesOverlay( + transport="openai_chat", + base_url_env_var="DASHSCOPE_BASE_URL", + ), + "vercel": HermesOverlay( + transport="openai_chat", + is_aggregator=True, + ), + "opencode": HermesOverlay( + transport="openai_chat", + is_aggregator=True, + base_url_env_var="OPENCODE_ZEN_BASE_URL", + ), + "opencode-go": HermesOverlay( + transport="openai_chat", + is_aggregator=True, + base_url_env_var="OPENCODE_GO_BASE_URL", + ), + "kilo": HermesOverlay( + transport="openai_chat", + is_aggregator=True, + base_url_env_var="KILOCODE_BASE_URL", + ), + "huggingface": HermesOverlay( + transport="openai_chat", + is_aggregator=True, + base_url_env_var="HF_BASE_URL", + ), + "xai": HermesOverlay( + transport="openai_chat", + base_url_override="https://api.x.ai/v1", + base_url_env_var="XAI_BASE_URL", + ), + "xiaomi": HermesOverlay( + transport="openai_chat", + base_url_env_var="XIAOMI_BASE_URL", + ), + "arcee": HermesOverlay( + transport="openai_chat", + base_url_override="https://api.arcee.ai/api/v1", + base_url_env_var="ARCEE_BASE_URL", + ), +} + + +# -- Resolved provider ------------------------------------------------------- +# The merged result of models.dev + overlay + user config. + +@dataclass +class ProviderDef: + """Complete provider definition — merged from all sources.""" + + id: str + name: str + transport: str # openai_chat | anthropic_messages | codex_responses + api_key_env_vars: Tuple[str, ...] # all env vars to check for API key + base_url: str = "" + base_url_env_var: str = "" + is_aggregator: bool = False + auth_type: str = "api_key" + doc: str = "" + source: str = "" # "models.dev", "hermes", "user-config" + + +# -- Aliases ------------------------------------------------------------------ +# Maps human-friendly / legacy names to canonical provider IDs. +# Uses models.dev IDs where possible. + +ALIASES: Dict[str, str] = { + # openrouter + "openai": "openrouter", # bare "openai" → route through aggregator + + # zai + "glm": "zai", + "z-ai": "zai", + "z.ai": "zai", + "zhipu": "zai", + + # xai + "x-ai": "xai", + "x.ai": "xai", + + # kimi-for-coding (models.dev ID) + "kimi": "kimi-for-coding", + "kimi-coding": "kimi-for-coding", + "kimi-coding-cn": "kimi-for-coding", + "moonshot": "kimi-for-coding", + + # minimax-cn + "minimax-china": "minimax-cn", + "minimax_cn": "minimax-cn", + + # anthropic + "claude": "anthropic", + "claude-code": "anthropic", + + # github-copilot (models.dev ID) + "copilot": "github-copilot", + "github": "github-copilot", + "github-copilot-acp": "copilot-acp", + + # vercel (models.dev ID for AI Gateway) + "ai-gateway": "vercel", + "aigateway": "vercel", + "vercel-ai-gateway": "vercel", + + # opencode (models.dev ID for OpenCode Zen) + "opencode-zen": "opencode", + "zen": "opencode", + + # opencode-go + "go": "opencode-go", + "opencode-go-sub": "opencode-go", + + # kilo (models.dev ID for KiloCode) + "kilocode": "kilo", + "kilo-code": "kilo", + "kilo-gateway": "kilo", + + # deepseek + "deep-seek": "deepseek", + + # alibaba + "dashscope": "alibaba", + "aliyun": "alibaba", + "qwen": "alibaba", + "alibaba-cloud": "alibaba", + + # huggingface + "hf": "huggingface", + "hugging-face": "huggingface", + "huggingface-hub": "huggingface", + + # xiaomi + "mimo": "xiaomi", + "xiaomi-mimo": "xiaomi", + + # arcee + "arcee-ai": "arcee", + "arceeai": "arcee", + + # Local server aliases → virtual "local" concept (resolved via user config) + "lmstudio": "lmstudio", + "lm-studio": "lmstudio", + "lm_studio": "lmstudio", + "ollama": "ollama-cloud", + "vllm": "local", + "llamacpp": "local", + "llama.cpp": "local", + "llama-cpp": "local", +} + + +# -- Display labels ----------------------------------------------------------- +# Built dynamically from models.dev + overlays. Fallback for providers +# not in the catalog. + +_LABEL_OVERRIDES: Dict[str, str] = { + "nous": "Nous Portal", + "openai-codex": "OpenAI Codex", + "copilot-acp": "GitHub Copilot ACP", + "xiaomi": "Xiaomi MiMo", + "local": "Local endpoint", +} + + +# -- Transport → API mode mapping --------------------------------------------- + +TRANSPORT_TO_API_MODE: Dict[str, str] = { + "openai_chat": "chat_completions", + "anthropic_messages": "anthropic_messages", + "codex_responses": "codex_responses", +} + + +# -- Helper functions --------------------------------------------------------- + +def normalize_provider(name: str) -> str: + """Resolve aliases and normalise casing to a canonical provider id. + + Returns the canonical id string. Does *not* validate that the id + corresponds to a known provider. + """ + key = name.strip().lower() + return ALIASES.get(key, key) + + +def get_provider(name: str) -> Optional[ProviderDef]: + """Look up a provider by id or alias, merging all data sources. + + Resolution order: + 1. Hermes overlays (for providers not in models.dev: nous, openai-codex, etc.) + 2. models.dev catalog + Hermes overlay + 3. User-defined providers from config (TODO: Phase 4) + + Returns a fully-resolved ProviderDef or None. + """ + canonical = normalize_provider(name) + + # Try to get models.dev data + try: + from agent.models_dev import get_provider_info as _mdev_provider + mdev_info = _mdev_provider(canonical) + except Exception: + mdev_info = None + + overlay = HERMES_OVERLAYS.get(canonical) + + if mdev_info is not None: + # Merge models.dev + overlay + transport = overlay.transport if overlay else "openai_chat" + is_agg = overlay.is_aggregator if overlay else False + auth = overlay.auth_type if overlay else "api_key" + base_url_env = overlay.base_url_env_var if overlay else "" + base_url_override = overlay.base_url_override if overlay else "" + + # Combine env vars: models.dev env + hermes extra + env_vars = list(mdev_info.env) + if overlay and overlay.extra_env_vars: + for ev in overlay.extra_env_vars: + if ev not in env_vars: + env_vars.append(ev) + + return ProviderDef( + id=canonical, + name=mdev_info.name, + transport=transport, + api_key_env_vars=tuple(env_vars), + base_url=base_url_override or mdev_info.api, + base_url_env_var=base_url_env, + is_aggregator=is_agg, + auth_type=auth, + doc=mdev_info.doc, + source="models.dev", + ) + + if overlay is not None: + # Hermes-only provider (not in models.dev) + return ProviderDef( + id=canonical, + name=_LABEL_OVERRIDES.get(canonical, canonical), + transport=overlay.transport, + api_key_env_vars=overlay.extra_env_vars, + base_url=overlay.base_url_override, + base_url_env_var=overlay.base_url_env_var, + is_aggregator=overlay.is_aggregator, + auth_type=overlay.auth_type, + source="hermes", + ) + + return None + + +def get_label(provider_id: str) -> str: + """Get a human-readable display name for a provider.""" + canonical = normalize_provider(provider_id) + + # Check label overrides first + if canonical in _LABEL_OVERRIDES: + return _LABEL_OVERRIDES[canonical] + + # Try models.dev + pdef = get_provider(canonical) + if pdef: + return pdef.name + + return canonical + + + + +def is_aggregator(provider: str) -> bool: + """Return True when the provider is a multi-model aggregator.""" + pdef = get_provider(provider) + return pdef.is_aggregator if pdef else False + + +def determine_api_mode(provider: str, base_url: str = "") -> str: + """Determine the API mode (wire protocol) for a provider/endpoint. + + Resolution order: + 1. Known provider → transport → TRANSPORT_TO_API_MODE. + 2. URL heuristics for unknown / custom providers. + 3. Default: 'chat_completions'. + """ + pdef = get_provider(provider) + if pdef is not None: + return TRANSPORT_TO_API_MODE.get(pdef.transport, "chat_completions") + + # URL-based heuristics for custom / unknown providers + if base_url: + url_lower = base_url.rstrip("/").lower() + if url_lower.endswith("/anthropic") or "api.anthropic.com" in url_lower: + return "anthropic_messages" + if "api.openai.com" in url_lower: + return "codex_responses" + + return "chat_completions" + + +# -- Provider from user config ------------------------------------------------ + +def resolve_user_provider(name: str, user_config: Dict[str, Any]) -> Optional[ProviderDef]: + """Resolve a provider from the user's config.yaml ``providers:`` section. + + Args: + name: Provider name as given by the user. + user_config: The ``providers:`` dict from config.yaml. + + Returns: + ProviderDef if found, else None. + """ + if not user_config or not isinstance(user_config, dict): + return None + + entry = user_config.get(name) + if not isinstance(entry, dict): + return None + + # Extract fields + display_name = entry.get("name", "") or name + api_url = entry.get("api", "") or entry.get("url", "") or entry.get("base_url", "") or "" + key_env = entry.get("key_env", "") or "" + transport = entry.get("transport", "openai_chat") or "openai_chat" + + env_vars: List[str] = [] + if key_env: + env_vars.append(key_env) + + return ProviderDef( + id=name, + name=display_name, + transport=transport, + api_key_env_vars=tuple(env_vars), + base_url=api_url, + is_aggregator=False, + auth_type="api_key", + source="user-config", + ) + + +def custom_provider_slug(display_name: str) -> str: + """Build a canonical slug for a custom_providers entry. + + Matches the convention used by runtime_provider and credential_pool + (``custom:``). Centralised here so all call-sites + produce identical slugs. + """ + return "custom:" + display_name.strip().lower().replace(" ", "-") + + +def resolve_custom_provider( + name: str, + custom_providers: Optional[List[Dict[str, Any]]], +) -> Optional[ProviderDef]: + """Resolve a provider from the user's config.yaml ``custom_providers`` list.""" + if not custom_providers or not isinstance(custom_providers, list): + return None + + requested = (name or "").strip().lower() + if not requested: + return None + + for entry in custom_providers: + if not isinstance(entry, dict): + continue + + display_name = (entry.get("name") or "").strip() + api_url = ( + entry.get("base_url", "") + or entry.get("url", "") + or entry.get("api", "") + or "" + ).strip() + if not display_name or not api_url: + continue + + slug = custom_provider_slug(display_name) + if requested not in {display_name.lower(), slug}: + continue + + return ProviderDef( + id=slug, + name=display_name, + transport="openai_chat", + api_key_env_vars=(), + base_url=api_url, + is_aggregator=False, + auth_type="api_key", + source="user-config", + ) + + return None + + +def resolve_provider_full( + name: str, + user_providers: Optional[Dict[str, Any]] = None, + custom_providers: Optional[List[Dict[str, Any]]] = None, +) -> Optional[ProviderDef]: + """Full resolution chain: built-in → models.dev → user config. + + This is the main entry point for --provider flag resolution. + + Args: + name: Provider name or alias. + user_providers: The ``providers:`` dict from config.yaml (optional). + custom_providers: The ``custom_providers:`` list from config.yaml (optional). + + Returns: + ProviderDef if found, else None. + """ + canonical = normalize_provider(name) + + # 1. Built-in (models.dev + overlays) + pdef = get_provider(canonical) + if pdef is not None: + return pdef + + # 2. User-defined providers from config + if user_providers: + # Try canonical name + user_pdef = resolve_user_provider(canonical, user_providers) + if user_pdef is not None: + return user_pdef + # Try original name (in case alias didn't match) + user_pdef = resolve_user_provider(name.strip().lower(), user_providers) + if user_pdef is not None: + return user_pdef + + # 2b. Saved custom providers from config + custom_pdef = resolve_custom_provider(name, custom_providers) + if custom_pdef is not None: + return custom_pdef + + # 3. Try models.dev directly (for providers not in our ALIASES) + try: + from agent.models_dev import get_provider_info as _mdev_provider + mdev_info = _mdev_provider(canonical) + if mdev_info is not None: + return ProviderDef( + id=canonical, + name=mdev_info.name, + transport="openai_chat", + api_key_env_vars=mdev_info.env, + base_url=mdev_info.api, + source="models.dev", + ) + except Exception: + pass + + return None diff --git a/mindcli/_vendor/hermes_cli/runtime_provider.py b/mindcli/_vendor/hermes_cli/runtime_provider.py new file mode 100644 index 0000000..b2dec61 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/runtime_provider.py @@ -0,0 +1,892 @@ +"""Shared runtime provider resolution for CLI, gateway, cron, and helpers.""" + +from __future__ import annotations + +import logging +import os +import re +from typing import Any, Dict, Optional + +logger = logging.getLogger(__name__) + +from hermes_cli import auth as auth_mod +from agent.credential_pool import CredentialPool, PooledCredential, get_custom_provider_pool_key, load_pool +from hermes_cli.auth import ( + AuthError, + DEFAULT_CODEX_BASE_URL, + DEFAULT_QWEN_BASE_URL, + PROVIDER_REGISTRY, + _agent_key_is_usable, + format_auth_error, + resolve_provider, + resolve_nous_runtime_credentials, + resolve_codex_runtime_credentials, + resolve_qwen_runtime_credentials, + resolve_api_key_provider_credentials, + resolve_external_process_provider_credentials, + has_usable_secret, +) +from hermes_cli.config import get_compatible_custom_providers, load_config +from hermes_constants import OPENROUTER_BASE_URL + + +def _normalize_custom_provider_name(value: str) -> str: + return value.strip().lower().replace(" ", "-") + + +def _detect_api_mode_for_url(base_url: str) -> Optional[str]: + """Auto-detect api_mode from the resolved base URL. + + Direct api.openai.com endpoints need the Responses API for GPT-5.x + tool calls with reasoning (chat/completions returns 400). + """ + normalized = (base_url or "").strip().lower().rstrip("/") + if "api.openai.com" in normalized and "openrouter" not in normalized: + return "codex_responses" + return None + + +def _auto_detect_local_model(base_url: str) -> str: + """Query a local server for its model name when only one model is loaded.""" + if not base_url: + return "" + try: + import requests + url = base_url.rstrip("/") + if not url.endswith("/v1"): + url += "/v1" + resp = requests.get(url + "/models", timeout=5) + if resp.ok: + models = resp.json().get("data", []) + if len(models) == 1: + model_id = models[0].get("id", "") + if model_id: + return model_id + except Exception: + pass + return "" + + +def _get_model_config() -> Dict[str, Any]: + config = load_config() + model_cfg = config.get("model") + if isinstance(model_cfg, dict): + cfg = dict(model_cfg) + # Accept "model" as alias for "default" (users intuitively write model.model) + if not cfg.get("default") and cfg.get("model"): + cfg["default"] = cfg["model"] + default = (cfg.get("default") or "").strip() + base_url = (cfg.get("base_url") or "").strip() + is_local = "localhost" in base_url or "127.0.0.1" in base_url + is_fallback = not default + if is_local and is_fallback and base_url: + detected = _auto_detect_local_model(base_url) + if detected: + cfg["default"] = detected + return cfg + if isinstance(model_cfg, str) and model_cfg.strip(): + return {"default": model_cfg.strip()} + return {} + + +def _provider_supports_explicit_api_mode(provider: Optional[str], configured_provider: Optional[str] = None) -> bool: + """Check whether a persisted api_mode should be honored for a given provider. + + Prevents stale api_mode from a previous provider leaking into a + different one after a model/provider switch. Only applies the + persisted mode when the config's provider matches the runtime + provider (or when no configured provider is recorded). + """ + normalized_provider = (provider or "").strip().lower() + normalized_configured = (configured_provider or "").strip().lower() + if not normalized_configured: + return True + if normalized_provider == "custom": + return normalized_configured == "custom" or normalized_configured.startswith("custom:") + return normalized_configured == normalized_provider + + +def _copilot_runtime_api_mode(model_cfg: Dict[str, Any], api_key: str) -> str: + configured_provider = str(model_cfg.get("provider") or "").strip().lower() + configured_mode = _parse_api_mode(model_cfg.get("api_mode")) + if configured_mode and _provider_supports_explicit_api_mode("copilot", configured_provider): + return configured_mode + + model_name = str(model_cfg.get("default") or "").strip() + if not model_name: + return "chat_completions" + + try: + from hermes_cli.models import copilot_model_api_mode + + return copilot_model_api_mode(model_name, api_key=api_key) + except Exception: + return "chat_completions" + + +_VALID_API_MODES = {"chat_completions", "codex_responses", "anthropic_messages"} + + +def _parse_api_mode(raw: Any) -> Optional[str]: + """Validate an api_mode value from config. Returns None if invalid.""" + if isinstance(raw, str): + normalized = raw.strip().lower() + if normalized in _VALID_API_MODES: + return normalized + return None + + +def _resolve_runtime_from_pool_entry( + *, + provider: str, + entry: PooledCredential, + requested_provider: str, + model_cfg: Optional[Dict[str, Any]] = None, + pool: Optional[CredentialPool] = None, +) -> Dict[str, Any]: + model_cfg = model_cfg or _get_model_config() + base_url = (getattr(entry, "runtime_base_url", None) or getattr(entry, "base_url", None) or "").rstrip("/") + api_key = getattr(entry, "runtime_api_key", None) or getattr(entry, "access_token", "") + api_mode = "chat_completions" + if provider == "openai-codex": + api_mode = "codex_responses" + base_url = base_url or DEFAULT_CODEX_BASE_URL + elif provider == "qwen-oauth": + api_mode = "chat_completions" + base_url = base_url or DEFAULT_QWEN_BASE_URL + elif provider == "anthropic": + api_mode = "anthropic_messages" + cfg_provider = str(model_cfg.get("provider") or "").strip().lower() + cfg_base_url = "" + if cfg_provider == "anthropic": + cfg_base_url = str(model_cfg.get("base_url") or "").strip().rstrip("/") + base_url = cfg_base_url or base_url or "https://api.anthropic.com" + elif provider == "openrouter": + base_url = base_url or OPENROUTER_BASE_URL + elif provider == "nous": + api_mode = "chat_completions" + elif provider == "copilot": + api_mode = _copilot_runtime_api_mode(model_cfg, getattr(entry, "runtime_api_key", "")) + else: + configured_provider = str(model_cfg.get("provider") or "").strip().lower() + # Honour model.base_url from config.yaml when the configured provider + # matches this provider — same pattern as the Anthropic branch above. + # Only override when the pool entry has no explicit base_url (i.e. it + # fell back to the hardcoded default). Env var overrides win (#6039). + pconfig = PROVIDER_REGISTRY.get(provider) + pool_url_is_default = pconfig and base_url.rstrip("/") == pconfig.inference_base_url.rstrip("/") + if configured_provider == provider and pool_url_is_default: + cfg_base_url = str(model_cfg.get("base_url") or "").strip().rstrip("/") + if cfg_base_url: + base_url = cfg_base_url + configured_mode = _parse_api_mode(model_cfg.get("api_mode")) + if configured_mode and _provider_supports_explicit_api_mode(provider, configured_provider): + api_mode = configured_mode + elif provider in ("opencode-zen", "opencode-go"): + from hermes_cli.models import opencode_model_api_mode + api_mode = opencode_model_api_mode(provider, model_cfg.get("default", "")) + elif base_url.rstrip("/").endswith("/anthropic"): + api_mode = "anthropic_messages" + + # OpenCode base URLs end with /v1 for OpenAI-compatible models, but the + # Anthropic SDK prepends its own /v1/messages to the base_url. Strip the + # trailing /v1 so the SDK constructs the correct path (e.g. + # https://opencode.ai/zen/go/v1/messages instead of .../v1/v1/messages). + if api_mode == "anthropic_messages" and provider in ("opencode-zen", "opencode-go"): + base_url = re.sub(r"/v1/?$", "", base_url) + + return { + "provider": provider, + "api_mode": api_mode, + "base_url": base_url, + "api_key": api_key, + "source": getattr(entry, "source", "pool"), + "credential_pool": pool, + "requested_provider": requested_provider, + } + + +def resolve_requested_provider(requested: Optional[str] = None) -> str: + """Resolve provider request from explicit arg, config, then env.""" + if requested and requested.strip(): + return requested.strip().lower() + + model_cfg = _get_model_config() + cfg_provider = model_cfg.get("provider") + if isinstance(cfg_provider, str) and cfg_provider.strip(): + return cfg_provider.strip().lower() + + # Prefer the persisted config selection over any stale shell/.env + # provider override so chat uses the endpoint the user last saved. + env_provider = os.getenv("HERMES_INFERENCE_PROVIDER", "").strip().lower() + if env_provider: + return env_provider + + return "auto" + + +def _try_resolve_from_custom_pool( + base_url: str, + provider_label: str, + api_mode_override: Optional[str] = None, +) -> Optional[Dict[str, Any]]: + """Check if a credential pool exists for a custom endpoint and return a runtime dict if so.""" + pool_key = get_custom_provider_pool_key(base_url) + if not pool_key: + return None + try: + pool = load_pool(pool_key) + if not pool.has_credentials(): + return None + entry = pool.select() + if entry is None: + return None + pool_api_key = getattr(entry, "runtime_api_key", None) or getattr(entry, "access_token", "") + if not pool_api_key: + return None + return { + "provider": provider_label, + "api_mode": api_mode_override or _detect_api_mode_for_url(base_url) or "chat_completions", + "base_url": base_url, + "api_key": pool_api_key, + "source": f"pool:{pool_key}", + "credential_pool": pool, + } + except Exception: + return None + + +def _get_named_custom_provider(requested_provider: str) -> Optional[Dict[str, Any]]: + requested_norm = _normalize_custom_provider_name(requested_provider or "") + if not requested_norm or requested_norm == "custom": + return None + + # Raw names should only map to custom providers when they are not already + # valid built-in providers or aliases. Explicit menu keys like + # ``custom:local`` always target the saved custom provider. + if requested_norm == "auto": + return None + if not requested_norm.startswith("custom:"): + try: + auth_mod.resolve_provider(requested_norm) + except AuthError: + pass + else: + return None + + config = load_config() + + # First check providers: dict (new-style user-defined providers) + providers = config.get("providers") + if isinstance(providers, dict): + for ep_name, entry in providers.items(): + if not isinstance(entry, dict): + continue + # Match exact name or normalized name + name_norm = _normalize_custom_provider_name(ep_name) + # Resolve the API key from the env var name stored in key_env + key_env = str(entry.get("key_env", "") or "").strip() + resolved_api_key = os.getenv(key_env, "").strip() if key_env else "" + # Fall back to inline api_key when key_env is absent or unresolvable + if not resolved_api_key: + resolved_api_key = str(entry.get("api_key", "") or "").strip() + + if requested_norm in {ep_name, name_norm, f"custom:{name_norm}"}: + # Found match by provider key + base_url = entry.get("api") or entry.get("url") or entry.get("base_url") or "" + if base_url: + return { + "name": entry.get("name", ep_name), + "base_url": base_url.strip(), + "api_key": resolved_api_key, + "model": entry.get("default_model", ""), + } + # Also check the 'name' field if present + display_name = entry.get("name", "") + if display_name: + display_norm = _normalize_custom_provider_name(display_name) + if requested_norm in {display_name, display_norm, f"custom:{display_norm}"}: + # Found match by display name + base_url = entry.get("api") or entry.get("url") or entry.get("base_url") or "" + if base_url: + return { + "name": display_name, + "base_url": base_url.strip(), + "api_key": resolved_api_key, + "model": entry.get("default_model", ""), + } + + # Fall back to custom_providers: list (legacy format) + custom_providers = config.get("custom_providers") + if isinstance(custom_providers, dict): + logger.warning( + "custom_providers in config.yaml is a dict, not a list. " + "Each entry must be prefixed with '-' in YAML. " + "Run 'hermes doctor' for details." + ) + return None + + custom_providers = get_compatible_custom_providers(config) + if not custom_providers: + return None + + for entry in custom_providers: + if not isinstance(entry, dict): + continue + name = entry.get("name") + base_url = entry.get("base_url") + if not isinstance(name, str) or not isinstance(base_url, str): + continue + name_norm = _normalize_custom_provider_name(name) + menu_key = f"custom:{name_norm}" + provider_key = str(entry.get("provider_key", "") or "").strip() + provider_key_norm = _normalize_custom_provider_name(provider_key) if provider_key else "" + provider_menu_key = f"custom:{provider_key_norm}" if provider_key_norm else "" + if requested_norm not in {name_norm, menu_key, provider_key_norm, provider_menu_key}: + continue + result = { + "name": name.strip(), + "base_url": base_url.strip(), + "api_key": str(entry.get("api_key", "") or "").strip(), + } + key_env = str(entry.get("key_env", "") or "").strip() + if key_env: + result["key_env"] = key_env + if provider_key: + result["provider_key"] = provider_key + api_mode = _parse_api_mode(entry.get("api_mode")) + if api_mode: + result["api_mode"] = api_mode + model_name = str(entry.get("model", "") or "").strip() + if model_name: + result["model"] = model_name + return result + + return None + + +def _resolve_named_custom_runtime( + *, + requested_provider: str, + explicit_api_key: Optional[str] = None, + explicit_base_url: Optional[str] = None, +) -> Optional[Dict[str, Any]]: + custom_provider = _get_named_custom_provider(requested_provider) + if not custom_provider: + return None + + base_url = ( + (explicit_base_url or "").strip() + or custom_provider.get("base_url", "") + ).rstrip("/") + if not base_url: + return None + + # Check if a credential pool exists for this custom endpoint + pool_result = _try_resolve_from_custom_pool(base_url, "custom", custom_provider.get("api_mode")) + if pool_result: + # Propagate the model name even when using pooled credentials — + # the pool doesn't know about the custom_providers model field. + model_name = custom_provider.get("model") + if model_name: + pool_result["model"] = model_name + return pool_result + + api_key_candidates = [ + (explicit_api_key or "").strip(), + str(custom_provider.get("api_key", "") or "").strip(), + os.getenv(str(custom_provider.get("key_env", "") or "").strip(), "").strip(), + os.getenv("OPENAI_API_KEY", "").strip(), + os.getenv("OPENROUTER_API_KEY", "").strip(), + ] + api_key = next((candidate for candidate in api_key_candidates if has_usable_secret(candidate)), "") + + result = { + "provider": "custom", + "api_mode": custom_provider.get("api_mode") + or _detect_api_mode_for_url(base_url) + or "chat_completions", + "base_url": base_url, + "api_key": api_key or "no-key-required", + "source": f"custom_provider:{custom_provider.get('name', requested_provider)}", + } + # Propagate the model name so callers can override self.model when the + # provider name differs from the actual model string the API expects. + if custom_provider.get("model"): + result["model"] = custom_provider["model"] + return result + + +def _resolve_openrouter_runtime( + *, + requested_provider: str, + explicit_api_key: Optional[str] = None, + explicit_base_url: Optional[str] = None, +) -> Dict[str, Any]: + model_cfg = _get_model_config() + cfg_base_url = model_cfg.get("base_url") if isinstance(model_cfg.get("base_url"), str) else "" + cfg_provider = model_cfg.get("provider") if isinstance(model_cfg.get("provider"), str) else "" + cfg_api_key = "" + for k in ("api_key", "api"): + v = model_cfg.get(k) + if isinstance(v, str) and v.strip(): + cfg_api_key = v.strip() + break + requested_norm = (requested_provider or "").strip().lower() + cfg_provider = cfg_provider.strip().lower() + + env_openrouter_base_url = os.getenv("OPENROUTER_BASE_URL", "").strip() + + # Use config base_url when available and the provider context matches. + # OPENAI_BASE_URL env var is no longer consulted — config.yaml is + # the single source of truth for endpoint URLs. + use_config_base_url = False + if cfg_base_url.strip() and not explicit_base_url: + if requested_norm == "auto": + if not cfg_provider or cfg_provider == "auto": + use_config_base_url = True + elif requested_norm == "custom" and cfg_provider == "custom": + use_config_base_url = True + + base_url = ( + (explicit_base_url or "").strip() + or (cfg_base_url.strip() if use_config_base_url else "") + or env_openrouter_base_url + or OPENROUTER_BASE_URL + ).rstrip("/") + + # Choose API key based on whether the resolved base_url targets OpenRouter. + # When hitting OpenRouter, prefer OPENROUTER_API_KEY (issue #289). + # When hitting a custom endpoint (e.g. Z.ai, local LLM), prefer + # OPENAI_API_KEY so the OpenRouter key doesn't leak to an unrelated + # provider (issues #420, #560). + _is_openrouter_url = "openrouter.ai" in base_url + if _is_openrouter_url: + api_key_candidates = [ + explicit_api_key, + os.getenv("OPENROUTER_API_KEY"), + os.getenv("OPENAI_API_KEY"), + ] + else: + # Custom endpoint: use api_key from config when using config base_url (#1760). + # When the endpoint is Ollama Cloud, check OLLAMA_API_KEY — it's + # the canonical env var for ollama.com authentication. + _is_ollama_url = "ollama.com" in base_url.lower() + api_key_candidates = [ + explicit_api_key, + (cfg_api_key if use_config_base_url else ""), + (os.getenv("OLLAMA_API_KEY") if _is_ollama_url else ""), + os.getenv("OPENAI_API_KEY"), + os.getenv("OPENROUTER_API_KEY"), + ] + api_key = next( + (str(candidate or "").strip() for candidate in api_key_candidates if has_usable_secret(candidate)), + "", + ) + + source = "explicit" if (explicit_api_key or explicit_base_url) else "env/config" + + # When "custom" was explicitly requested, preserve that as the provider + # name instead of silently relabeling to "openrouter" (#2562). + # Also provide a placeholder API key for local servers that don't require + # authentication — the OpenAI SDK requires a non-empty api_key string. + effective_provider = "custom" if requested_norm == "custom" else "openrouter" + + # For custom endpoints, check if a credential pool exists + if effective_provider == "custom" and base_url: + pool_result = _try_resolve_from_custom_pool( + base_url, effective_provider, _parse_api_mode(model_cfg.get("api_mode")), + ) + if pool_result: + return pool_result + + if effective_provider == "custom" and not api_key and not _is_openrouter_url: + api_key = "no-key-required" + + return { + "provider": effective_provider, + "api_mode": _parse_api_mode(model_cfg.get("api_mode")) + or _detect_api_mode_for_url(base_url) + or "chat_completions", + "base_url": base_url, + "api_key": api_key, + "source": source, + } + + +def _resolve_explicit_runtime( + *, + provider: str, + requested_provider: str, + model_cfg: Dict[str, Any], + explicit_api_key: Optional[str] = None, + explicit_base_url: Optional[str] = None, +) -> Optional[Dict[str, Any]]: + explicit_api_key = str(explicit_api_key or "").strip() + explicit_base_url = str(explicit_base_url or "").strip().rstrip("/") + if not explicit_api_key and not explicit_base_url: + return None + + if provider == "anthropic": + cfg_provider = str(model_cfg.get("provider") or "").strip().lower() + cfg_base_url = "" + if cfg_provider == "anthropic": + cfg_base_url = str(model_cfg.get("base_url") or "").strip().rstrip("/") + base_url = explicit_base_url or cfg_base_url or "https://api.anthropic.com" + api_key = explicit_api_key + if not api_key: + from agent.anthropic_adapter import resolve_anthropic_token + + api_key = resolve_anthropic_token() + if not api_key: + raise AuthError( + "No Anthropic credentials found. Set ANTHROPIC_TOKEN or ANTHROPIC_API_KEY, " + "run 'claude setup-token', or authenticate with 'claude /login'." + ) + return { + "provider": "anthropic", + "api_mode": "anthropic_messages", + "base_url": base_url, + "api_key": api_key, + "source": "explicit", + "requested_provider": requested_provider, + } + + if provider == "openai-codex": + base_url = explicit_base_url or DEFAULT_CODEX_BASE_URL + api_key = explicit_api_key + last_refresh = None + if not api_key: + creds = resolve_codex_runtime_credentials() + api_key = creds.get("api_key", "") + last_refresh = creds.get("last_refresh") + if not explicit_base_url: + base_url = creds.get("base_url", "").rstrip("/") or base_url + return { + "provider": "openai-codex", + "api_mode": "codex_responses", + "base_url": base_url, + "api_key": api_key, + "source": "explicit", + "last_refresh": last_refresh, + "requested_provider": requested_provider, + } + + if provider == "nous": + state = auth_mod.get_provider_auth_state("nous") or {} + base_url = ( + explicit_base_url + or str(state.get("inference_base_url") or auth_mod.DEFAULT_NOUS_INFERENCE_URL).strip().rstrip("/") + ) + # Only use agent_key for inference — access_token is an OAuth token for the + # portal API (minting keys, refreshing tokens), not for the inference API. + # Falling back to access_token sends an OAuth bearer token to the inference + # endpoint, which returns 404 because it is not a valid inference credential. + api_key = explicit_api_key or str(state.get("agent_key") or "").strip() + expires_at = state.get("agent_key_expires_at") or state.get("expires_at") + if not api_key: + creds = resolve_nous_runtime_credentials( + min_key_ttl_seconds=max(60, int(os.getenv("HERMES_NOUS_MIN_KEY_TTL_SECONDS", "1800"))), + timeout_seconds=float(os.getenv("HERMES_NOUS_TIMEOUT_SECONDS", "15")), + ) + api_key = creds.get("api_key", "") + expires_at = creds.get("expires_at") + if not explicit_base_url: + base_url = creds.get("base_url", "").rstrip("/") or base_url + return { + "provider": "nous", + "api_mode": "chat_completions", + "base_url": base_url, + "api_key": api_key, + "source": "explicit", + "expires_at": expires_at, + "requested_provider": requested_provider, + } + + pconfig = PROVIDER_REGISTRY.get(provider) + if pconfig and pconfig.auth_type == "api_key": + env_url = "" + if pconfig.base_url_env_var: + env_url = os.getenv(pconfig.base_url_env_var, "").strip().rstrip("/") + + base_url = explicit_base_url + if not base_url: + if provider in ("kimi-coding", "kimi-coding-cn"): + creds = resolve_api_key_provider_credentials(provider) + base_url = creds.get("base_url", "").rstrip("/") + else: + base_url = env_url or pconfig.inference_base_url + + api_key = explicit_api_key + if not api_key: + creds = resolve_api_key_provider_credentials(provider) + api_key = creds.get("api_key", "") + if not base_url: + base_url = creds.get("base_url", "").rstrip("/") + + api_mode = "chat_completions" + if provider == "copilot": + api_mode = _copilot_runtime_api_mode(model_cfg, api_key) + else: + configured_mode = _parse_api_mode(model_cfg.get("api_mode")) + if configured_mode: + api_mode = configured_mode + elif base_url.rstrip("/").endswith("/anthropic"): + api_mode = "anthropic_messages" + + return { + "provider": provider, + "api_mode": api_mode, + "base_url": base_url.rstrip("/"), + "api_key": api_key, + "source": "explicit", + "requested_provider": requested_provider, + } + + return None + + +def resolve_runtime_provider( + *, + requested: Optional[str] = None, + explicit_api_key: Optional[str] = None, + explicit_base_url: Optional[str] = None, +) -> Dict[str, Any]: + """Resolve runtime provider credentials for agent execution.""" + requested_provider = resolve_requested_provider(requested) + + custom_runtime = _resolve_named_custom_runtime( + requested_provider=requested_provider, + explicit_api_key=explicit_api_key, + explicit_base_url=explicit_base_url, + ) + if custom_runtime: + custom_runtime["requested_provider"] = requested_provider + return custom_runtime + + provider = resolve_provider( + requested_provider, + explicit_api_key=explicit_api_key, + explicit_base_url=explicit_base_url, + ) + model_cfg = _get_model_config() + explicit_runtime = _resolve_explicit_runtime( + provider=provider, + requested_provider=requested_provider, + model_cfg=model_cfg, + explicit_api_key=explicit_api_key, + explicit_base_url=explicit_base_url, + ) + if explicit_runtime: + return explicit_runtime + + should_use_pool = provider != "openrouter" + if provider == "openrouter": + cfg_provider = str(model_cfg.get("provider") or "").strip().lower() + cfg_base_url = str(model_cfg.get("base_url") or "").strip() + env_openai_base_url = os.getenv("OPENAI_BASE_URL", "").strip() + env_openrouter_base_url = os.getenv("OPENROUTER_BASE_URL", "").strip() + has_custom_endpoint = bool( + explicit_base_url + or env_openai_base_url + or env_openrouter_base_url + ) + if cfg_base_url and cfg_provider in {"auto", "custom"}: + has_custom_endpoint = True + has_runtime_override = bool(explicit_api_key or explicit_base_url) + should_use_pool = ( + requested_provider in {"openrouter", "auto"} + and not has_custom_endpoint + and not has_runtime_override + ) + + try: + pool = load_pool(provider) if should_use_pool else None + except Exception: + pool = None + if pool and pool.has_credentials(): + entry = pool.select() + pool_api_key = "" + if entry is not None: + pool_api_key = ( + getattr(entry, "runtime_api_key", None) + or getattr(entry, "access_token", "") + ) + # For Nous, the pool entry's runtime_api_key is the agent_key — a + # short-lived inference credential (~30 min TTL). The pool doesn't + # refresh it during selection (that would trigger network calls in + # non-runtime contexts like `hermes auth list`). If the key is + # expired, clear pool_api_key so we fall through to + # resolve_nous_runtime_credentials() which handles refresh + mint. + if provider == "nous" and entry is not None and pool_api_key: + min_ttl = max(60, int(os.getenv("HERMES_NOUS_MIN_KEY_TTL_SECONDS", "1800"))) + nous_state = { + "agent_key": getattr(entry, "agent_key", None), + "agent_key_expires_at": getattr(entry, "agent_key_expires_at", None), + } + if not _agent_key_is_usable(nous_state, min_ttl): + logger.debug("Nous pool entry agent_key expired/missing, falling through to runtime resolution") + pool_api_key = "" + if entry is not None and pool_api_key: + return _resolve_runtime_from_pool_entry( + provider=provider, + entry=entry, + requested_provider=requested_provider, + model_cfg=model_cfg, + pool=pool, + ) + + if provider == "nous": + try: + creds = resolve_nous_runtime_credentials( + min_key_ttl_seconds=max(60, int(os.getenv("HERMES_NOUS_MIN_KEY_TTL_SECONDS", "1800"))), + timeout_seconds=float(os.getenv("HERMES_NOUS_TIMEOUT_SECONDS", "15")), + ) + return { + "provider": "nous", + "api_mode": "chat_completions", + "base_url": creds.get("base_url", "").rstrip("/"), + "api_key": creds.get("api_key", ""), + "source": creds.get("source", "portal"), + "expires_at": creds.get("expires_at"), + "requested_provider": requested_provider, + } + except AuthError: + if requested_provider != "auto": + raise + # Auto-detected Nous but credentials are stale/revoked — + # fall through to env-var providers (e.g. OpenRouter). + logger.info("Auto-detected Nous provider but credentials failed; " + "falling through to next provider.") + + if provider == "openai-codex": + try: + creds = resolve_codex_runtime_credentials() + return { + "provider": "openai-codex", + "api_mode": "codex_responses", + "base_url": creds.get("base_url", "").rstrip("/"), + "api_key": creds.get("api_key", ""), + "source": creds.get("source", "hermes-auth-store"), + "last_refresh": creds.get("last_refresh"), + "requested_provider": requested_provider, + } + except AuthError: + if requested_provider != "auto": + raise + # Auto-detected Codex but credentials are stale/revoked — + # fall through to env-var providers (e.g. OpenRouter). + logger.info("Auto-detected Codex provider but credentials failed; " + "falling through to next provider.") + + if provider == "qwen-oauth": + try: + creds = resolve_qwen_runtime_credentials() + return { + "provider": "qwen-oauth", + "api_mode": "chat_completions", + "base_url": creds.get("base_url", "").rstrip("/"), + "api_key": creds.get("api_key", ""), + "source": creds.get("source", "qwen-cli"), + "expires_at_ms": creds.get("expires_at_ms"), + "requested_provider": requested_provider, + } + except AuthError: + if requested_provider != "auto": + raise + logger.info("Qwen OAuth credentials failed; " + "falling through to next provider.") + + if provider == "copilot-acp": + creds = resolve_external_process_provider_credentials(provider) + return { + "provider": "copilot-acp", + "api_mode": "chat_completions", + "base_url": creds.get("base_url", "").rstrip("/"), + "api_key": creds.get("api_key", ""), + "command": creds.get("command", ""), + "args": list(creds.get("args") or []), + "source": creds.get("source", "process"), + "requested_provider": requested_provider, + } + + # Anthropic (native Messages API) + if provider == "anthropic": + from agent.anthropic_adapter import resolve_anthropic_token + token = resolve_anthropic_token() + if not token: + raise AuthError( + "No Anthropic credentials found. Set ANTHROPIC_TOKEN or ANTHROPIC_API_KEY, " + "run 'claude setup-token', or authenticate with 'claude /login'." + ) + # Allow base URL override from config.yaml model.base_url, but only + # when the configured provider is anthropic — otherwise a non-Anthropic + # base_url (e.g. Codex endpoint) would leak into Anthropic requests. + cfg_provider = str(model_cfg.get("provider") or "").strip().lower() + cfg_base_url = "" + if cfg_provider == "anthropic": + cfg_base_url = (model_cfg.get("base_url") or "").strip().rstrip("/") + base_url = cfg_base_url or "https://api.anthropic.com" + return { + "provider": "anthropic", + "api_mode": "anthropic_messages", + "base_url": base_url, + "api_key": token, + "source": "env", + "requested_provider": requested_provider, + } + + # API-key providers (z.ai/GLM, Kimi, MiniMax, MiniMax-CN) + pconfig = PROVIDER_REGISTRY.get(provider) + if pconfig and pconfig.auth_type == "api_key": + creds = resolve_api_key_provider_credentials(provider) + # Honour model.base_url from config.yaml when the configured provider + # matches this provider — mirrors the Anthropic path above. Without + # this, users who set model.base_url to e.g. api.minimaxi.com/anthropic + # (China endpoint) still get the hardcoded api.minimax.io default (#6039). + cfg_provider = str(model_cfg.get("provider") or "").strip().lower() + cfg_base_url = "" + if cfg_provider == provider: + cfg_base_url = (model_cfg.get("base_url") or "").strip().rstrip("/") + base_url = cfg_base_url or creds.get("base_url", "").rstrip("/") + api_mode = "chat_completions" + if provider == "copilot": + api_mode = _copilot_runtime_api_mode(model_cfg, creds.get("api_key", "")) + else: + configured_provider = str(model_cfg.get("provider") or "").strip().lower() + # Only honor persisted api_mode when it belongs to the same provider family. + configured_mode = _parse_api_mode(model_cfg.get("api_mode")) + if configured_mode and _provider_supports_explicit_api_mode(provider, configured_provider): + api_mode = configured_mode + elif provider in ("opencode-zen", "opencode-go"): + from hermes_cli.models import opencode_model_api_mode + api_mode = opencode_model_api_mode(provider, model_cfg.get("default", "")) + # Auto-detect Anthropic-compatible endpoints by URL convention + # (e.g. https://api.minimax.io/anthropic, https://dashscope.../anthropic) + elif base_url.rstrip("/").endswith("/anthropic"): + api_mode = "anthropic_messages" + # Strip trailing /v1 for OpenCode Anthropic models (see comment above). + if api_mode == "anthropic_messages" and provider in ("opencode-zen", "opencode-go"): + base_url = re.sub(r"/v1/?$", "", base_url) + return { + "provider": provider, + "api_mode": api_mode, + "base_url": base_url, + "api_key": creds.get("api_key", ""), + "source": creds.get("source", "env"), + "requested_provider": requested_provider, + } + + runtime = _resolve_openrouter_runtime( + requested_provider=requested_provider, + explicit_api_key=explicit_api_key, + explicit_base_url=explicit_base_url, + ) + runtime["requested_provider"] = requested_provider + return runtime + + +def format_runtime_provider_error(error: Exception) -> str: + if isinstance(error, AuthError): + return format_auth_error(error) + return str(error) diff --git a/mindcli/_vendor/hermes_cli/setup.py b/mindcli/_vendor/hermes_cli/setup.py new file mode 100644 index 0000000..9044871 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/setup.py @@ -0,0 +1,3199 @@ +""" +Interactive setup wizard for Hermes Agent. + +Modular wizard with independently-runnable sections: + 1. Model & Provider — choose your AI provider and model + 2. Terminal Backend — where your agent runs commands + 3. Agent Settings — iterations, compression, session reset + 4. Messaging Platforms — connect Telegram, Discord, etc. + 5. Tools — configure TTS, web search, image generation, etc. + +Config files are stored in ~/.hermes/ for easy access. +""" + +import importlib.util +import logging +import os +import shutil +import sys +import copy +from pathlib import Path +from typing import Optional, Dict, Any + +from hermes_cli.nous_subscription import ( + apply_nous_provider_defaults, + get_nous_subscription_features, +) +from tools.tool_backend_helpers import managed_nous_tools_enabled +from hermes_constants import get_optional_skills_dir + +logger = logging.getLogger(__name__) + +PROJECT_ROOT = Path(__file__).parent.parent.resolve() + +_DOCS_BASE = "https://hermes-agent.nousresearch.com/docs" + + +def _model_config_dict(config: Dict[str, Any]) -> Dict[str, Any]: + current_model = config.get("model") + if isinstance(current_model, dict): + return dict(current_model) + if isinstance(current_model, str) and current_model.strip(): + return {"default": current_model.strip()} + return {} + + +def _get_credential_pool_strategies(config: Dict[str, Any]) -> Dict[str, str]: + strategies = config.get("credential_pool_strategies") + return dict(strategies) if isinstance(strategies, dict) else {} + + +def _set_credential_pool_strategy(config: Dict[str, Any], provider: str, strategy: str) -> None: + if not provider: + return + strategies = _get_credential_pool_strategies(config) + strategies[provider] = strategy + config["credential_pool_strategies"] = strategies + + +def _supports_same_provider_pool_setup(provider: str) -> bool: + if not provider or provider == "custom": + return False + if provider == "openrouter": + return True + from hermes_cli.auth import PROVIDER_REGISTRY + + pconfig = PROVIDER_REGISTRY.get(provider) + if not pconfig: + return False + return pconfig.auth_type in {"api_key", "oauth_device_code"} + + +# Default model lists per provider — used as fallback when the live +# /models endpoint can't be reached. +_DEFAULT_PROVIDER_MODELS = { + "copilot-acp": [ + "copilot-acp", + ], + "copilot": [ + "gpt-5.4", + "gpt-5.4-mini", + "gpt-5-mini", + "gpt-5.3-codex", + "gpt-5.2-codex", + "gpt-4.1", + "gpt-4o", + "gpt-4o-mini", + "claude-opus-4.6", + "claude-sonnet-4.6", + "claude-sonnet-4.5", + "claude-haiku-4.5", + "gemini-2.5-pro", + "grok-code-fast-1", + ], + "gemini": [ + "gemini-3.1-pro-preview", "gemini-3-flash-preview", "gemini-3.1-flash-lite-preview", + "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite", + "gemma-4-31b-it", "gemma-4-26b-it", + ], + "zai": ["glm-5.1", "glm-5", "glm-4.7", "glm-4.5", "glm-4.5-flash"], + "kimi-coding": ["kimi-k2.5", "kimi-k2-thinking", "kimi-k2-turbo-preview"], + "kimi-coding-cn": ["kimi-k2.5", "kimi-k2-thinking", "kimi-k2-turbo-preview"], + "arcee": ["trinity-large-thinking", "trinity-large-preview", "trinity-mini"], + "minimax": ["MiniMax-M2.7", "MiniMax-M2.5", "MiniMax-M2.1", "MiniMax-M2"], + "minimax-cn": ["MiniMax-M2.7", "MiniMax-M2.5", "MiniMax-M2.1", "MiniMax-M2"], + "ai-gateway": ["anthropic/claude-opus-4.6", "anthropic/claude-sonnet-4.6", "openai/gpt-5", "google/gemini-3-flash"], + "kilocode": ["anthropic/claude-opus-4.6", "anthropic/claude-sonnet-4.6", "openai/gpt-5.4", "google/gemini-3-pro-preview", "google/gemini-3-flash-preview"], + "opencode-zen": ["gpt-5.4", "gpt-5.3-codex", "claude-sonnet-4-6", "gemini-3-flash", "glm-5", "kimi-k2.5", "minimax-m2.7"], + "opencode-go": ["glm-5", "kimi-k2.5", "mimo-v2-pro", "mimo-v2-omni", "minimax-m2.5", "minimax-m2.7"], + "huggingface": [ + "Qwen/Qwen3.5-397B-A17B", "Qwen/Qwen3-235B-A22B-Thinking-2507", + "Qwen/Qwen3-Coder-480B-A35B-Instruct", "deepseek-ai/DeepSeek-R1-0528", + "deepseek-ai/DeepSeek-V3.2", "moonshotai/Kimi-K2.5", + ], +} + + +def _current_reasoning_effort(config: Dict[str, Any]) -> str: + agent_cfg = config.get("agent") + if isinstance(agent_cfg, dict): + return str(agent_cfg.get("reasoning_effort") or "").strip().lower() + return "" + + +def _set_reasoning_effort(config: Dict[str, Any], effort: str) -> None: + agent_cfg = config.get("agent") + if not isinstance(agent_cfg, dict): + agent_cfg = {} + config["agent"] = agent_cfg + agent_cfg["reasoning_effort"] = effort + + + + +# Import config helpers +from hermes_cli.config import ( + DEFAULT_CONFIG, + get_hermes_home, + get_config_path, + get_env_path, + load_config, + save_config, + save_env_value, + get_env_value, + ensure_hermes_home, +) +# display_hermes_home imported lazily at call sites (stale-module safety during hermes update) + +from hermes_cli.colors import Colors, color + + +def print_header(title: str): + """Print a section header.""" + print() + print(color(f"◆ {title}", Colors.CYAN, Colors.BOLD)) + + +from hermes_cli.cli_output import ( # noqa: E402 + print_error, + print_info, + print_success, + print_warning, +) + + +def is_interactive_stdin() -> bool: + """Return True when stdin looks like a usable interactive TTY.""" + stdin = getattr(sys, "stdin", None) + if stdin is None: + return False + try: + return bool(stdin.isatty()) + except Exception: + return False + + +def print_noninteractive_setup_guidance(reason: str | None = None) -> None: + """Print guidance for headless/non-interactive setup flows.""" + print() + print(color("⚕ Hermes Setup — Non-interactive mode", Colors.CYAN, Colors.BOLD)) + print() + if reason: + print_info(reason) + print_info("The interactive wizard cannot be used here.") + print() + print_info("Configure Hermes using environment variables or config commands:") + print_info(" hermes config set model.provider custom") + print_info(" hermes config set model.base_url http://localhost:8080/v1") + print_info(" hermes config set model.default your-model-name") + print() + print_info("Or set OPENROUTER_API_KEY / OPENAI_API_KEY in your environment.") + print_info("Run 'hermes setup' in an interactive terminal to use the full wizard.") + print() + + +def prompt(question: str, default: str = None, password: bool = False) -> str: + """Prompt for input with optional default.""" + if default: + display = f"{question} [{default}]: " + else: + display = f"{question}: " + + try: + if password: + import getpass + + value = getpass.getpass(color(display, Colors.YELLOW)) + else: + value = input(color(display, Colors.YELLOW)) + + return value.strip() or default or "" + except (KeyboardInterrupt, EOFError): + print() + sys.exit(1) + + +def _curses_prompt_choice(question: str, choices: list, default: int = 0) -> int: + """Single-select menu using curses. Delegates to curses_radiolist.""" + from hermes_cli.curses_ui import curses_radiolist + return curses_radiolist(question, choices, selected=default, cancel_returns=-1) + + + +def prompt_choice(question: str, choices: list, default: int = 0) -> int: + """Prompt for a choice from a list with arrow key navigation. + + Escape keeps the current default (skips the question). + Ctrl+C exits the wizard. + """ + idx = _curses_prompt_choice(question, choices, default) + if idx >= 0: + if idx == default: + print_info(" Skipped (keeping current)") + print() + return default + print() + return idx + + print(color(question, Colors.YELLOW)) + for i, choice in enumerate(choices): + marker = "●" if i == default else "○" + if i == default: + print(color(f" {marker} {choice}", Colors.GREEN)) + else: + print(f" {marker} {choice}") + + print_info(f" Enter for default ({default + 1}) Ctrl+C to exit") + + while True: + try: + value = input( + color(f" Select [1-{len(choices)}] ({default + 1}): ", Colors.DIM) + ) + if not value: + return default + idx = int(value) - 1 + if 0 <= idx < len(choices): + return idx + print_error(f"Please enter a number between 1 and {len(choices)}") + except ValueError: + print_error("Please enter a number") + except (KeyboardInterrupt, EOFError): + print() + sys.exit(1) + + +def prompt_yes_no(question: str, default: bool = True) -> bool: + """Prompt for yes/no. Ctrl+C exits, empty input returns default.""" + default_str = "Y/n" if default else "y/N" + + while True: + try: + value = ( + input(color(f"{question} [{default_str}]: ", Colors.YELLOW)) + .strip() + .lower() + ) + except (KeyboardInterrupt, EOFError): + print() + sys.exit(1) + + if not value: + return default + if value in ("y", "yes"): + return True + if value in ("n", "no"): + return False + print_error("Please enter 'y' or 'n'") + + +def prompt_checklist(title: str, items: list, pre_selected: list = None) -> list: + """ + Display a multi-select checklist and return the indices of selected items. + + Each item in `items` is a display string. `pre_selected` is a list of + indices that should be checked by default. A "Continue →" option is + appended at the end — the user toggles items with Space and confirms + with Enter on "Continue →". + + Falls back to a numbered toggle interface when simple_term_menu is + unavailable. + + Returns: + List of selected indices (not including the Continue option). + """ + if pre_selected is None: + pre_selected = [] + + from hermes_cli.curses_ui import curses_checklist + + chosen = curses_checklist( + title, + items, + set(pre_selected), + cancel_returns=set(pre_selected), + ) + return sorted(chosen) + + +def _prompt_api_key(var: dict): + """Display a nicely formatted API key input screen for a single env var.""" + tools = var.get("tools", []) + tools_str = ", ".join(tools[:3]) + if len(tools) > 3: + tools_str += f", +{len(tools) - 3} more" + + print() + print(color(f" ─── {var.get('description', var['name'])} ───", Colors.CYAN)) + print() + if tools_str: + print_info(f" Enables: {tools_str}") + if var.get("url"): + print_info(f" Get your key at: {var['url']}") + print() + + if var.get("password"): + value = prompt(f" {var.get('prompt', var['name'])}", password=True) + else: + value = prompt(f" {var.get('prompt', var['name'])}") + + if value: + save_env_value(var["name"], value) + print_success(" ✓ Saved") + else: + print_warning(" Skipped (configure later with 'hermes setup')") + + +def _print_setup_summary(config: dict, hermes_home): + """Print the setup completion summary.""" + # Tool availability summary + print() + print_header("Tool Availability Summary") + + tool_status = [] + subscription_features = get_nous_subscription_features(config) + + # Vision — use the same runtime resolver as the actual vision tools + try: + from agent.auxiliary_client import get_available_vision_backends + + _vision_backends = get_available_vision_backends() + except Exception: + _vision_backends = [] + + if _vision_backends: + tool_status.append(("Vision (image analysis)", True, None)) + else: + tool_status.append(("Vision (image analysis)", False, "run 'hermes setup' to configure")) + + # Mixture of Agents — requires OpenRouter specifically (calls multiple models) + if get_env_value("OPENROUTER_API_KEY"): + tool_status.append(("Mixture of Agents", True, None)) + else: + tool_status.append(("Mixture of Agents", False, "OPENROUTER_API_KEY")) + + # Web tools (Exa, Parallel, Firecrawl, or Tavily) + if subscription_features.web.managed_by_nous: + tool_status.append(("Web Search & Extract (Nous subscription)", True, None)) + elif subscription_features.web.available: + label = "Web Search & Extract" + if subscription_features.web.current_provider: + label = f"Web Search & Extract ({subscription_features.web.current_provider})" + tool_status.append((label, True, None)) + else: + tool_status.append(("Web Search & Extract", False, "EXA_API_KEY, PARALLEL_API_KEY, FIRECRAWL_API_KEY/FIRECRAWL_API_URL, or TAVILY_API_KEY")) + + # Browser tools (local Chromium, Camofox, Browserbase, Browser Use, or Firecrawl) + browser_provider = subscription_features.browser.current_provider + if subscription_features.browser.managed_by_nous: + tool_status.append(("Browser Automation (Nous Browser Use)", True, None)) + elif subscription_features.browser.available: + label = "Browser Automation" + if browser_provider: + label = f"Browser Automation ({browser_provider})" + tool_status.append((label, True, None)) + else: + missing_browser_hint = "npm install -g agent-browser, set CAMOFOX_URL, or configure Browser Use or Browserbase" + if browser_provider == "Browserbase": + missing_browser_hint = ( + "npm install -g agent-browser and set " + "BROWSERBASE_API_KEY/BROWSERBASE_PROJECT_ID" + ) + elif browser_provider == "Browser Use": + missing_browser_hint = ( + "npm install -g agent-browser and set BROWSER_USE_API_KEY" + ) + elif browser_provider == "Camofox": + missing_browser_hint = "CAMOFOX_URL" + elif browser_provider == "Local browser": + missing_browser_hint = "npm install -g agent-browser" + tool_status.append( + ("Browser Automation", False, missing_browser_hint) + ) + + # FAL (image generation) + if subscription_features.image_gen.managed_by_nous: + tool_status.append(("Image Generation (Nous subscription)", True, None)) + elif subscription_features.image_gen.available: + tool_status.append(("Image Generation", True, None)) + else: + tool_status.append(("Image Generation", False, "FAL_KEY")) + + # TTS — show configured provider + tts_provider = config.get("tts", {}).get("provider", "edge") + if subscription_features.tts.managed_by_nous: + tool_status.append(("Text-to-Speech (OpenAI via Nous subscription)", True, None)) + elif tts_provider == "elevenlabs" and get_env_value("ELEVENLABS_API_KEY"): + tool_status.append(("Text-to-Speech (ElevenLabs)", True, None)) + elif tts_provider == "openai" and ( + get_env_value("VOICE_TOOLS_OPENAI_KEY") or get_env_value("OPENAI_API_KEY") + ): + tool_status.append(("Text-to-Speech (OpenAI)", True, None)) + elif tts_provider == "minimax" and get_env_value("MINIMAX_API_KEY"): + tool_status.append(("Text-to-Speech (MiniMax)", True, None)) + elif tts_provider == "mistral" and get_env_value("MISTRAL_API_KEY"): + tool_status.append(("Text-to-Speech (Mistral Voxtral)", True, None)) + elif tts_provider == "neutts": + try: + import importlib.util + neutts_ok = importlib.util.find_spec("neutts") is not None + except Exception: + neutts_ok = False + if neutts_ok: + tool_status.append(("Text-to-Speech (NeuTTS local)", True, None)) + else: + tool_status.append(("Text-to-Speech (NeuTTS — not installed)", False, "run 'hermes setup tts'")) + else: + tool_status.append(("Text-to-Speech (Edge TTS)", True, None)) + + if subscription_features.modal.managed_by_nous: + tool_status.append(("Modal Execution (Nous subscription)", True, None)) + elif config.get("terminal", {}).get("backend") == "modal": + if subscription_features.modal.direct_override: + tool_status.append(("Modal Execution (direct Modal)", True, None)) + else: + tool_status.append(("Modal Execution", False, "run 'hermes setup terminal'")) + elif managed_nous_tools_enabled() and subscription_features.nous_auth_present: + tool_status.append(("Modal Execution (optional via Nous subscription)", True, None)) + + # Tinker + WandB (RL training) + if get_env_value("TINKER_API_KEY") and get_env_value("WANDB_API_KEY"): + tool_status.append(("RL Training (Tinker)", True, None)) + elif get_env_value("TINKER_API_KEY"): + tool_status.append(("RL Training (Tinker)", False, "WANDB_API_KEY")) + else: + tool_status.append(("RL Training (Tinker)", False, "TINKER_API_KEY")) + + # Home Assistant + if get_env_value("HASS_TOKEN"): + tool_status.append(("Smart Home (Home Assistant)", True, None)) + + # Skills Hub + if get_env_value("GITHUB_TOKEN"): + tool_status.append(("Skills Hub (GitHub)", True, None)) + else: + tool_status.append(("Skills Hub (GitHub)", False, "GITHUB_TOKEN")) + + # Terminal (always available if system deps met) + tool_status.append(("Terminal/Commands", True, None)) + + # Task planning (always available, in-memory) + tool_status.append(("Task Planning (todo)", True, None)) + + # Skills (always available -- bundled skills + user-created skills) + tool_status.append(("Skills (view, create, edit)", True, None)) + + # Print status + available_count = sum(1 for _, avail, _ in tool_status if avail) + total_count = len(tool_status) + + print_info(f"{available_count}/{total_count} tool categories available:") + print() + + for name, available, missing_var in tool_status: + if available: + print(f" {color('✓', Colors.GREEN)} {name}") + else: + print( + f" {color('✗', Colors.RED)} {name} {color(f'(missing {missing_var})', Colors.DIM)}" + ) + + print() + + disabled_tools = [(name, var) for name, avail, var in tool_status if not avail] + if disabled_tools: + print_warning( + "Some tools are disabled. Run 'hermes setup tools' to configure them," + ) + from hermes_constants import display_hermes_home as _dhh + print_warning(f"or edit {_dhh()}/.env directly to add the missing API keys.") + print() + + # Done banner + print() + print( + color( + "┌─────────────────────────────────────────────────────────┐", Colors.GREEN + ) + ) + print( + color( + "│ ✓ Setup Complete! │", Colors.GREEN + ) + ) + print( + color( + "└─────────────────────────────────────────────────────────┘", Colors.GREEN + ) + ) + print() + + # Show file locations prominently + from hermes_constants import display_hermes_home as _dhh + print(color(f"📁 All your files are in {_dhh()}/:", Colors.CYAN, Colors.BOLD)) + print() + print(f" {color('Settings:', Colors.YELLOW)} {get_config_path()}") + print(f" {color('API Keys:', Colors.YELLOW)} {get_env_path()}") + print( + f" {color('Data:', Colors.YELLOW)} {hermes_home}/cron/, sessions/, logs/" + ) + print() + + print(color("─" * 60, Colors.DIM)) + print() + print(color("📝 To edit your configuration:", Colors.CYAN, Colors.BOLD)) + print() + print(f" {color('hermes setup', Colors.GREEN)} Re-run the full wizard") + print(f" {color('hermes setup model', Colors.GREEN)} Change model/provider") + print(f" {color('hermes setup terminal', Colors.GREEN)} Change terminal backend") + print(f" {color('hermes setup gateway', Colors.GREEN)} Configure messaging") + print(f" {color('hermes setup tools', Colors.GREEN)} Configure tool providers") + print() + print(f" {color('hermes config', Colors.GREEN)} View current settings") + print( + f" {color('hermes config edit', Colors.GREEN)} Open config in your editor" + ) + print(f" {color('hermes config set ', Colors.GREEN)}") + print(" Set a specific value") + print() + print(" Or edit the files directly:") + print(f" {color(f'nano {get_config_path()}', Colors.DIM)}") + print(f" {color(f'nano {get_env_path()}', Colors.DIM)}") + print() + + print(color("─" * 60, Colors.DIM)) + print() + print(color("🚀 Ready to go!", Colors.CYAN, Colors.BOLD)) + print() + print(f" {color('hermes', Colors.GREEN)} Start chatting") + print(f" {color('hermes gateway', Colors.GREEN)} Start messaging gateway") + print(f" {color('hermes doctor', Colors.GREEN)} Check for issues") + print() + + +def _prompt_container_resources(config: dict): + """Prompt for container resource settings (Docker, Singularity, Modal, Daytona).""" + terminal = config.setdefault("terminal", {}) + + print() + print_info("Container Resource Settings:") + + # Persistence + current_persist = terminal.get("container_persistent", True) + persist_label = "yes" if current_persist else "no" + print_info(" Persistent filesystem keeps files between sessions.") + print_info(" Set to 'no' for ephemeral sandboxes that reset each time.") + persist_str = prompt( + " Persist filesystem across sessions? (yes/no)", persist_label + ) + terminal["container_persistent"] = persist_str.lower() in ("yes", "true", "y", "1") + + # CPU + current_cpu = terminal.get("container_cpu", 1) + cpu_str = prompt(" CPU cores", str(current_cpu)) + try: + terminal["container_cpu"] = float(cpu_str) + except ValueError: + pass + + # Memory + current_mem = terminal.get("container_memory", 5120) + mem_str = prompt(" Memory in MB (5120 = 5GB)", str(current_mem)) + try: + terminal["container_memory"] = int(mem_str) + except ValueError: + pass + + # Disk + current_disk = terminal.get("container_disk", 51200) + disk_str = prompt(" Disk in MB (51200 = 50GB)", str(current_disk)) + try: + terminal["container_disk"] = int(disk_str) + except ValueError: + pass + + +# Tool categories and provider config are now in tools_config.py (shared +# between `hermes tools` and `hermes setup tools`). + + +# ============================================================================= +# Section 1: Model & Provider Configuration +# ============================================================================= + + + +def setup_model_provider(config: dict, *, quick: bool = False): + """Configure the inference provider and default model. + + Delegates to ``cmd_model()`` (the same flow used by ``hermes model``) + for provider selection, credential prompting, and model picking. + This ensures a single code path for all provider setup — any new + provider added to ``hermes model`` is automatically available here. + + When *quick* is True, skips credential rotation, vision, and TTS + configuration — used by the streamlined first-time quick setup. + """ + from hermes_cli.config import load_config, save_config + + print_header("Inference Provider") + print_info("Choose how to connect to your main chat model.") + print_info(f" Guide: {_DOCS_BASE}/integrations/providers") + print() + + # Delegate to the shared hermes model flow — handles provider picker, + # credential prompting, model selection, and config persistence. + from hermes_cli.main import select_provider_and_model + try: + select_provider_and_model() + except (SystemExit, KeyboardInterrupt): + print() + print_info("Provider setup skipped.") + except Exception as exc: + logger.debug("select_provider_and_model error during setup: %s", exc) + print_warning(f"Provider setup encountered an error: {exc}") + print_info("You can try again later with: hermes model") + + # Re-sync the wizard's config dict from what cmd_model saved to disk. + # This is critical: cmd_model writes to disk via its own load/save cycle, + # and the wizard's final save_config(config) must not overwrite those + # changes with stale values (#4172). + _refreshed = load_config() + config["model"] = _refreshed.get("model", config.get("model")) + if "custom_providers" in _refreshed: + config["custom_providers"] = _refreshed["custom_providers"] + else: + config.pop("custom_providers", None) + + # Derive the selected provider for downstream steps (vision setup). + selected_provider = None + _m = config.get("model") + if isinstance(_m, dict): + selected_provider = _m.get("provider") + + nous_subscription_selected = selected_provider == "nous" + + # ── Same-provider fallback & rotation setup (full setup only) ── + if not quick and _supports_same_provider_pool_setup(selected_provider): + try: + from types import SimpleNamespace + from agent.credential_pool import load_pool + from hermes_cli.auth_commands import auth_add_command + + pool = load_pool(selected_provider) + entries = pool.entries() + entry_count = len(entries) + manual_count = sum(1 for entry in entries if str(getattr(entry, "source", "")).startswith("manual")) + auto_count = entry_count - manual_count + print() + print_header("Same-Provider Fallback & Rotation") + print_info( + "Hermes can keep multiple credentials for one provider and rotate between" + ) + print_info( + "them when a credential is exhausted or rate-limited. This preserves" + ) + print_info( + "your primary provider while reducing interruptions from quota issues." + ) + print() + if auto_count > 0: + print_info( + f"Current pooled credentials for {selected_provider}: {entry_count} " + f"({manual_count} manual, {auto_count} auto-detected from env/shared auth)" + ) + else: + print_info(f"Current pooled credentials for {selected_provider}: {entry_count}") + + while prompt_yes_no("Add another credential for same-provider fallback?", False): + auth_add_command( + SimpleNamespace( + provider=selected_provider, + auth_type="", + label=None, + api_key=None, + portal_url=None, + inference_url=None, + client_id=None, + scope=None, + no_browser=False, + timeout=15.0, + insecure=False, + ca_bundle=None, + min_key_ttl_seconds=5 * 60, + ) + ) + pool = load_pool(selected_provider) + entry_count = len(pool.entries()) + print_info(f"Provider pool now has {entry_count} credential(s).") + + if entry_count > 1: + strategy_labels = [ + "Fill-first / sticky — keep using the first healthy credential until it is exhausted", + "Round robin — rotate to the next healthy credential after each selection", + "Random — pick a random healthy credential each time", + ] + current_strategy = _get_credential_pool_strategies(config).get(selected_provider, "fill_first") + default_strategy_idx = { + "fill_first": 0, + "round_robin": 1, + "random": 2, + }.get(current_strategy, 0) + strategy_idx = prompt_choice( + "Select same-provider rotation strategy:", + strategy_labels, + default_strategy_idx, + ) + strategy_value = ["fill_first", "round_robin", "random"][strategy_idx] + _set_credential_pool_strategy(config, selected_provider, strategy_value) + print_success(f"Saved {selected_provider} rotation strategy: {strategy_value}") + except Exception as exc: + logger.debug("Could not configure same-provider fallback in setup: %s", exc) + + # ── Vision & Image Analysis Setup (full setup only) ── + if quick: + _vision_needs_setup = False + else: + try: + from agent.auxiliary_client import get_available_vision_backends + _vision_backends = set(get_available_vision_backends()) + except Exception: + _vision_backends = set() + + _vision_needs_setup = not bool(_vision_backends) + + if selected_provider in _vision_backends: + _vision_needs_setup = False + + if _vision_needs_setup: + _prov_names = { + "nous-api": "Nous Portal API key", + "copilot": "GitHub Copilot", + "copilot-acp": "GitHub Copilot ACP", + "zai": "Z.AI / GLM", + "kimi-coding": "Kimi / Moonshot", + "kimi-coding-cn": "Kimi / Moonshot (China)", + "minimax": "MiniMax", + "minimax-cn": "MiniMax CN", + "anthropic": "Anthropic", + "ai-gateway": "Vercel AI Gateway", + "custom": "your custom endpoint", + } + _prov_display = _prov_names.get(selected_provider, selected_provider or "your provider") + + print() + print_header("Vision & Image Analysis (optional)") + print_info(f"Vision uses a separate multimodal backend. {_prov_display}") + print_info("doesn't currently provide one Hermes can auto-use for vision,") + print_info("so choose a backend now or skip and configure later.") + print() + + _vision_choices = [ + "OpenRouter — uses Gemini (free tier at openrouter.ai/keys)", + "OpenAI-compatible endpoint — base URL, API key, and vision model", + "Skip for now", + ] + _vision_idx = prompt_choice("Configure vision:", _vision_choices, 2) + + if _vision_idx == 0: # OpenRouter + _or_key = prompt(" OpenRouter API key", password=True).strip() + if _or_key: + save_env_value("OPENROUTER_API_KEY", _or_key) + print_success("OpenRouter key saved — vision will use Gemini") + else: + print_info("Skipped — vision won't be available") + elif _vision_idx == 1: # OpenAI-compatible endpoint + _base_url = prompt(" Base URL (blank for OpenAI)").strip() or "https://api.openai.com/v1" + _api_key_label = " API key" + if "api.openai.com" in _base_url.lower(): + _api_key_label = " OpenAI API key" + _oai_key = prompt(_api_key_label, password=True).strip() + if _oai_key: + save_env_value("OPENAI_API_KEY", _oai_key) + # Save vision base URL to config (not .env — only secrets go there) + _vaux = config.setdefault("auxiliary", {}).setdefault("vision", {}) + _vaux["base_url"] = _base_url + if "api.openai.com" in _base_url.lower(): + _oai_vision_models = ["gpt-4o", "gpt-4o-mini", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano"] + _vm_choices = _oai_vision_models + ["Use default (gpt-4o-mini)"] + _vm_idx = prompt_choice("Select vision model:", _vm_choices, 0) + _selected_vision_model = ( + _oai_vision_models[_vm_idx] + if _vm_idx < len(_oai_vision_models) + else "gpt-4o-mini" + ) + else: + _selected_vision_model = prompt(" Vision model (blank = use main/custom default)").strip() + save_env_value("AUXILIARY_VISION_MODEL", _selected_vision_model) + print_success( + f"Vision configured with {_base_url}" + + (f" ({_selected_vision_model})" if _selected_vision_model else "") + ) + else: + print_info("Skipped — vision won't be available") + else: + print_info("Skipped — add later with 'hermes setup' or configure AUXILIARY_VISION_* settings") + + + if selected_provider == "nous" and nous_subscription_selected: + changed_defaults = apply_nous_provider_defaults(config) + current_tts = str(config.get("tts", {}).get("provider") or "edge") + if "tts" in changed_defaults: + print_success("TTS provider set to: OpenAI TTS via your Nous subscription") + else: + print_info(f"Keeping your existing TTS provider: {current_tts}") + + save_config(config) + + if not quick and selected_provider != "nous": + _setup_tts_provider(config) + + +# ============================================================================= +# Section 1b: TTS Provider Configuration +# ============================================================================= + + +def _check_espeak_ng() -> bool: + """Check if espeak-ng is installed.""" + import shutil + return shutil.which("espeak-ng") is not None or shutil.which("espeak") is not None + + +def _install_neutts_deps() -> bool: + """Install NeuTTS dependencies with user approval. Returns True on success.""" + import subprocess + import sys + + # Check espeak-ng + if not _check_espeak_ng(): + print() + print_warning("NeuTTS requires espeak-ng for phonemization.") + if sys.platform == "darwin": + print_info("Install with: brew install espeak-ng") + elif sys.platform == "win32": + print_info("Install with: choco install espeak-ng") + else: + print_info("Install with: sudo apt install espeak-ng") + print() + if prompt_yes_no("Install espeak-ng now?", True): + try: + if sys.platform == "darwin": + subprocess.run(["brew", "install", "espeak-ng"], check=True) + elif sys.platform == "win32": + subprocess.run(["choco", "install", "espeak-ng", "-y"], check=True) + else: + subprocess.run(["sudo", "apt", "install", "-y", "espeak-ng"], check=True) + print_success("espeak-ng installed") + except (subprocess.CalledProcessError, FileNotFoundError) as e: + print_warning(f"Could not install espeak-ng automatically: {e}") + print_info("Please install it manually and re-run setup.") + return False + else: + print_warning("espeak-ng is required for NeuTTS. Install it manually before using NeuTTS.") + + # Install neutts Python package + print() + print_info("Installing neutts Python package...") + print_info("This will also download the TTS model (~300MB) on first use.") + print() + try: + subprocess.run( + [sys.executable, "-m", "pip", "install", "-U", "neutts[all]", "--quiet"], + check=True, timeout=300, + ) + print_success("neutts installed successfully") + return True + except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e: + print_error(f"Failed to install neutts: {e}") + print_info("Try manually: python -m pip install -U neutts[all]") + return False + + +def _setup_tts_provider(config: dict): + """Interactive TTS provider selection with install flow for NeuTTS.""" + tts_config = config.get("tts", {}) + current_provider = tts_config.get("provider", "edge") + subscription_features = get_nous_subscription_features(config) + + provider_labels = { + "edge": "Edge TTS", + "elevenlabs": "ElevenLabs", + "openai": "OpenAI TTS", + "minimax": "MiniMax TTS", + "mistral": "Mistral Voxtral TTS", + "neutts": "NeuTTS", + } + current_label = provider_labels.get(current_provider, current_provider) + + print() + print_header("Text-to-Speech Provider (optional)") + print_info(f"Current: {current_label}") + print() + + choices = [] + providers = [] + if managed_nous_tools_enabled() and subscription_features.nous_auth_present: + choices.append("Nous Subscription (managed OpenAI TTS, billed to your subscription)") + providers.append("nous-openai") + choices.extend( + [ + "Edge TTS (free, cloud-based, no setup needed)", + "ElevenLabs (premium quality, needs API key)", + "OpenAI TTS (good quality, needs API key)", + "MiniMax TTS (high quality with voice cloning, needs API key)", + "Mistral Voxtral TTS (multilingual, native Opus, needs API key)", + "NeuTTS (local on-device, free, ~300MB model download)", + ] + ) + providers.extend(["edge", "elevenlabs", "openai", "minimax", "mistral", "neutts"]) + choices.append(f"Keep current ({current_label})") + keep_current_idx = len(choices) - 1 + idx = prompt_choice("Select TTS provider:", choices, keep_current_idx) + + if idx == keep_current_idx: + return + + selected = providers[idx] + selected_via_nous = selected == "nous-openai" + if selected == "nous-openai": + selected = "openai" + print_info("OpenAI TTS will use the managed Nous gateway and bill to your subscription.") + if get_env_value("VOICE_TOOLS_OPENAI_KEY") or get_env_value("OPENAI_API_KEY"): + print_warning( + "Direct OpenAI credentials are still configured and may take precedence until removed from ~/.hermes/.env." + ) + + if selected == "neutts": + # Check if already installed + try: + import importlib.util + already_installed = importlib.util.find_spec("neutts") is not None + except Exception: + already_installed = False + + if already_installed: + print_success("NeuTTS is already installed") + else: + print() + print_info("NeuTTS requires:") + print_info(" • Python package: neutts (~50MB install + ~300MB model on first use)") + print_info(" • System package: espeak-ng (phonemizer)") + print() + if prompt_yes_no("Install NeuTTS dependencies now?", True): + if not _install_neutts_deps(): + print_warning("NeuTTS installation incomplete. Falling back to Edge TTS.") + selected = "edge" + else: + print_info("Skipping install. Set tts.provider to 'neutts' after installing manually.") + selected = "edge" + + elif selected == "elevenlabs": + existing = get_env_value("ELEVENLABS_API_KEY") + if not existing: + print() + api_key = prompt("ElevenLabs API key", password=True) + if api_key: + save_env_value("ELEVENLABS_API_KEY", api_key) + print_success("ElevenLabs API key saved") + else: + print_warning("No API key provided. Falling back to Edge TTS.") + selected = "edge" + + elif selected == "openai" and not selected_via_nous: + existing = get_env_value("VOICE_TOOLS_OPENAI_KEY") or get_env_value("OPENAI_API_KEY") + if not existing: + print() + api_key = prompt("OpenAI API key for TTS", password=True) + if api_key: + save_env_value("VOICE_TOOLS_OPENAI_KEY", api_key) + print_success("OpenAI TTS API key saved") + else: + print_warning("No API key provided. Falling back to Edge TTS.") + selected = "edge" + + elif selected == "minimax": + existing = get_env_value("MINIMAX_API_KEY") + if not existing: + print() + api_key = prompt("MiniMax API key for TTS", password=True) + if api_key: + save_env_value("MINIMAX_API_KEY", api_key) + print_success("MiniMax TTS API key saved") + else: + print_warning("No API key provided. Falling back to Edge TTS.") + selected = "edge" + + elif selected == "mistral": + existing = get_env_value("MISTRAL_API_KEY") + if not existing: + print() + api_key = prompt("Mistral API key for TTS", password=True) + if api_key: + save_env_value("MISTRAL_API_KEY", api_key) + print_success("Mistral TTS API key saved") + else: + print_warning("No API key provided. Falling back to Edge TTS.") + selected = "edge" + + # Save the selection + if "tts" not in config: + config["tts"] = {} + config["tts"]["provider"] = selected + save_config(config) + print_success(f"TTS provider set to: {provider_labels.get(selected, selected)}") + + +def setup_tts(config: dict): + """Standalone TTS setup (for 'hermes setup tts').""" + _setup_tts_provider(config) + + +# ============================================================================= +# Section 2: Terminal Backend Configuration +# ============================================================================= + + +def setup_terminal_backend(config: dict): + """Configure the terminal execution backend.""" + import platform as _platform + import shutil + + print_header("Terminal Backend") + print_info("Choose where Hermes runs shell commands and code.") + print_info("This affects tool execution, file access, and isolation.") + print_info(f" Guide: {_DOCS_BASE}/developer-guide/environments") + print() + + current_backend = config.get("terminal", {}).get("backend", "local") + is_linux = _platform.system() == "Linux" + + # Build backend choices with descriptions + terminal_choices = [ + "Local - run directly on this machine (default)", + "Docker - isolated container with configurable resources", + "Modal - serverless cloud sandbox", + "SSH - run on a remote machine", + "Daytona - persistent cloud development environment", + ] + idx_to_backend = {0: "local", 1: "docker", 2: "modal", 3: "ssh", 4: "daytona"} + backend_to_idx = {"local": 0, "docker": 1, "modal": 2, "ssh": 3, "daytona": 4} + + next_idx = 5 + if is_linux: + terminal_choices.append("Singularity/Apptainer - HPC-friendly container") + idx_to_backend[next_idx] = "singularity" + backend_to_idx["singularity"] = next_idx + next_idx += 1 + + # Add keep current option + keep_current_idx = next_idx + terminal_choices.append(f"Keep current ({current_backend})") + idx_to_backend[keep_current_idx] = current_backend + + terminal_idx = prompt_choice( + "Select terminal backend:", terminal_choices, keep_current_idx + ) + + selected_backend = idx_to_backend.get(terminal_idx) + + if terminal_idx == keep_current_idx: + print_info(f"Keeping current backend: {current_backend}") + return + + config.setdefault("terminal", {})["backend"] = selected_backend + + if selected_backend == "local": + print_success("Terminal backend: Local") + print_info("Commands run directly on this machine.") + + # CWD for messaging + print() + print_info("Working directory for messaging sessions:") + print_info(" When using Hermes via Telegram/Discord, this is where") + print_info( + " the agent starts. CLI mode always starts in the current directory." + ) + current_cwd = config.get("terminal", {}).get("cwd", "") + cwd = prompt(" Messaging working directory", current_cwd or str(Path.home())) + if cwd: + config["terminal"]["cwd"] = cwd + + # Sudo support + print() + existing_sudo = get_env_value("SUDO_PASSWORD") + if existing_sudo: + print_info("Sudo password: configured") + else: + if prompt_yes_no( + "Enable sudo support? (stores password for apt install, etc.)", False + ): + sudo_pass = prompt(" Sudo password", password=True) + if sudo_pass: + save_env_value("SUDO_PASSWORD", sudo_pass) + print_success("Sudo password saved") + + elif selected_backend == "docker": + print_success("Terminal backend: Docker") + + # Check if Docker is available + docker_bin = shutil.which("docker") + if not docker_bin: + print_warning("Docker not found in PATH!") + print_info("Install Docker: https://docs.docker.com/get-docker/") + else: + print_info(f"Docker found: {docker_bin}") + + # Docker image + current_image = config.get("terminal", {}).get( + "docker_image", "nikolaik/python-nodejs:python3.11-nodejs20" + ) + image = prompt(" Docker image", current_image) + config["terminal"]["docker_image"] = image + save_env_value("TERMINAL_DOCKER_IMAGE", image) + + _prompt_container_resources(config) + + elif selected_backend == "singularity": + print_success("Terminal backend: Singularity/Apptainer") + + # Check if singularity/apptainer is available + sing_bin = shutil.which("apptainer") or shutil.which("singularity") + if not sing_bin: + print_warning("Singularity/Apptainer not found in PATH!") + print_info( + "Install: https://apptainer.org/docs/admin/main/installation.html" + ) + else: + print_info(f"Found: {sing_bin}") + + current_image = config.get("terminal", {}).get( + "singularity_image", "docker://nikolaik/python-nodejs:python3.11-nodejs20" + ) + image = prompt(" Container image", current_image) + config["terminal"]["singularity_image"] = image + save_env_value("TERMINAL_SINGULARITY_IMAGE", image) + + _prompt_container_resources(config) + + elif selected_backend == "modal": + print_success("Terminal backend: Modal") + print_info("Serverless cloud sandboxes. Each session gets its own container.") + from tools.managed_tool_gateway import is_managed_tool_gateway_ready + from tools.tool_backend_helpers import normalize_modal_mode + + managed_modal_available = bool( + managed_nous_tools_enabled() + and + get_nous_subscription_features(config).nous_auth_present + and is_managed_tool_gateway_ready("modal") + ) + modal_mode = normalize_modal_mode(config.get("terminal", {}).get("modal_mode")) + use_managed_modal = False + if managed_modal_available: + modal_choices = [ + "Use my Nous subscription", + "Use my own Modal account", + ] + if modal_mode == "managed": + default_modal_idx = 0 + elif modal_mode == "direct": + default_modal_idx = 1 + else: + default_modal_idx = 1 if get_env_value("MODAL_TOKEN_ID") else 0 + modal_mode_idx = prompt_choice( + "Select how Modal execution should be billed:", + modal_choices, + default_modal_idx, + ) + use_managed_modal = modal_mode_idx == 0 + + if use_managed_modal: + config["terminal"]["modal_mode"] = "managed" + print_info("Modal execution will use the managed Nous gateway and bill to your subscription.") + if get_env_value("MODAL_TOKEN_ID") or get_env_value("MODAL_TOKEN_SECRET"): + print_info( + "Direct Modal credentials are still configured, but this backend is pinned to managed mode." + ) + else: + config["terminal"]["modal_mode"] = "direct" + print_info("Requires a Modal account: https://modal.com") + + # Check if modal SDK is installed + try: + __import__("modal") + except ImportError: + print_info("Installing modal SDK...") + import subprocess + + uv_bin = shutil.which("uv") + if uv_bin: + result = subprocess.run( + [ + uv_bin, + "pip", + "install", + "--python", + sys.executable, + "modal", + ], + capture_output=True, + text=True, + ) + else: + result = subprocess.run( + [sys.executable, "-m", "pip", "install", "modal"], + capture_output=True, + text=True, + ) + if result.returncode == 0: + print_success("modal SDK installed") + else: + print_warning("Install failed — run manually: pip install modal") + + # Modal token + print() + print_info("Modal authentication:") + print_info(" Get your token at: https://modal.com/settings") + existing_token = get_env_value("MODAL_TOKEN_ID") + if existing_token: + print_info(" Modal token: already configured") + if prompt_yes_no(" Update Modal credentials?", False): + token_id = prompt(" Modal Token ID", password=True) + token_secret = prompt(" Modal Token Secret", password=True) + if token_id: + save_env_value("MODAL_TOKEN_ID", token_id) + if token_secret: + save_env_value("MODAL_TOKEN_SECRET", token_secret) + else: + token_id = prompt(" Modal Token ID", password=True) + token_secret = prompt(" Modal Token Secret", password=True) + if token_id: + save_env_value("MODAL_TOKEN_ID", token_id) + if token_secret: + save_env_value("MODAL_TOKEN_SECRET", token_secret) + + _prompt_container_resources(config) + + elif selected_backend == "daytona": + print_success("Terminal backend: Daytona") + print_info("Persistent cloud development environments.") + print_info("Each session gets a dedicated sandbox with filesystem persistence.") + print_info("Sign up at: https://daytona.io") + + # Check if daytona SDK is installed + try: + __import__("daytona") + except ImportError: + print_info("Installing daytona SDK...") + import subprocess + + uv_bin = shutil.which("uv") + if uv_bin: + result = subprocess.run( + [uv_bin, "pip", "install", "--python", sys.executable, "daytona"], + capture_output=True, + text=True, + ) + else: + result = subprocess.run( + [sys.executable, "-m", "pip", "install", "daytona"], + capture_output=True, + text=True, + ) + if result.returncode == 0: + print_success("daytona SDK installed") + else: + print_warning("Install failed — run manually: pip install daytona") + if result.stderr: + print_info(f" Error: {result.stderr.strip().splitlines()[-1]}") + + # Daytona API key + print() + existing_key = get_env_value("DAYTONA_API_KEY") + if existing_key: + print_info(" Daytona API key: already configured") + if prompt_yes_no(" Update API key?", False): + api_key = prompt(" Daytona API key", password=True) + if api_key: + save_env_value("DAYTONA_API_KEY", api_key) + print_success(" Updated") + else: + api_key = prompt(" Daytona API key", password=True) + if api_key: + save_env_value("DAYTONA_API_KEY", api_key) + print_success(" Configured") + + # Daytona image + current_image = config.get("terminal", {}).get( + "daytona_image", "nikolaik/python-nodejs:python3.11-nodejs20" + ) + image = prompt(" Sandbox image", current_image) + config["terminal"]["daytona_image"] = image + save_env_value("TERMINAL_DAYTONA_IMAGE", image) + + _prompt_container_resources(config) + + elif selected_backend == "ssh": + print_success("Terminal backend: SSH") + print_info("Run commands on a remote machine via SSH.") + + # SSH host + current_host = get_env_value("TERMINAL_SSH_HOST") or "" + host = prompt(" SSH host (hostname or IP)", current_host) + if host: + save_env_value("TERMINAL_SSH_HOST", host) + + # SSH user + current_user = get_env_value("TERMINAL_SSH_USER") or "" + user = prompt(" SSH user", current_user or os.getenv("USER", "")) + if user: + save_env_value("TERMINAL_SSH_USER", user) + + # SSH port + current_port = get_env_value("TERMINAL_SSH_PORT") or "22" + port = prompt(" SSH port", current_port) + if port and port != "22": + save_env_value("TERMINAL_SSH_PORT", port) + + # SSH key + current_key = get_env_value("TERMINAL_SSH_KEY") or "" + default_key = str(Path.home() / ".ssh" / "id_rsa") + ssh_key = prompt(" SSH private key path", current_key or default_key) + if ssh_key: + save_env_value("TERMINAL_SSH_KEY", ssh_key) + + # Test connection + if host and prompt_yes_no(" Test SSH connection?", True): + print_info(" Testing connection...") + import subprocess + + ssh_cmd = ["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=5"] + if ssh_key: + ssh_cmd.extend(["-i", ssh_key]) + if port and port != "22": + ssh_cmd.extend(["-p", port]) + ssh_cmd.append(f"{user}@{host}" if user else host) + ssh_cmd.append("echo ok") + result = subprocess.run(ssh_cmd, capture_output=True, text=True, timeout=10) + if result.returncode == 0: + print_success(" SSH connection successful!") + else: + print_warning(f" SSH connection failed: {result.stderr.strip()}") + print_info(" Check your SSH key and host settings.") + + # Sync terminal backend to .env so terminal_tool picks it up directly. + # config.yaml is the source of truth, but terminal_tool reads TERMINAL_ENV. + save_env_value("TERMINAL_ENV", selected_backend) + if selected_backend == "modal": + save_env_value("TERMINAL_MODAL_MODE", config["terminal"].get("modal_mode", "auto")) + save_config(config) + print() + print_success(f"Terminal backend set to: {selected_backend}") + + +# ============================================================================= +# Section 3: Agent Settings +# ============================================================================= + + +def _apply_default_agent_settings(config: dict): + """Apply recommended defaults for all agent settings without prompting.""" + config.setdefault("agent", {})["max_turns"] = 90 + save_env_value("HERMES_MAX_ITERATIONS", "90") + + config.setdefault("display", {})["tool_progress"] = "all" + + config.setdefault("compression", {})["enabled"] = True + config["compression"]["threshold"] = 0.50 + + config.setdefault("session_reset", {}).update({ + "mode": "both", + "idle_minutes": 1440, + "at_hour": 4, + }) + + save_config(config) + print_success("Applied recommended defaults:") + print_info(" Max iterations: 90") + print_info(" Tool progress: all") + print_info(" Compression threshold: 0.50") + print_info(" Session reset: inactivity (1440 min) + daily (4:00)") + print_info(" Run `hermes setup agent` later to customize.") + + +def setup_agent_settings(config: dict): + """Configure agent behavior: iterations, progress display, compression, session reset.""" + + print_header("Agent Settings") + print_info(f" Guide: {_DOCS_BASE}/user-guide/configuration") + print() + + # ── Max Iterations ── + current_max = get_env_value("HERMES_MAX_ITERATIONS") or str( + config.get("agent", {}).get("max_turns", 90) + ) + print_info("Maximum tool-calling iterations per conversation.") + print_info("Higher = more complex tasks, but costs more tokens.") + print_info("Default is 90, which works for most tasks. Use 150+ for open exploration.") + + max_iter_str = prompt("Max iterations", current_max) + try: + max_iter = int(max_iter_str) + if max_iter > 0: + save_env_value("HERMES_MAX_ITERATIONS", str(max_iter)) + config.setdefault("agent", {})["max_turns"] = max_iter + config.pop("max_turns", None) + print_success(f"Max iterations set to {max_iter}") + except ValueError: + print_warning("Invalid number, keeping current value") + + # ── Tool Progress Display ── + print_info("") + print_info("Tool Progress Display") + print_info("Controls how much tool activity is shown (CLI and messaging).") + print_info(" off — Silent, just the final response") + print_info(" new — Show tool name only when it changes (less noise)") + print_info(" all — Show every tool call with a short preview") + print_info(" verbose — Full args, results, and debug logs") + + current_mode = config.get("display", {}).get("tool_progress", "all") + mode = prompt("Tool progress mode", current_mode) + if mode.lower() in ("off", "new", "all", "verbose"): + if "display" not in config: + config["display"] = {} + config["display"]["tool_progress"] = mode.lower() + save_config(config) + print_success(f"Tool progress set to: {mode.lower()}") + else: + print_warning(f"Unknown mode '{mode}', keeping '{current_mode}'") + + # ── Context Compression ── + print_header("Context Compression") + print_info("Automatically summarizes old messages when context gets too long.") + print_info( + "Higher threshold = compress later (use more context). Lower = compress sooner." + ) + + config.setdefault("compression", {})["enabled"] = True + + current_threshold = config.get("compression", {}).get("threshold", 0.50) + threshold_str = prompt("Compression threshold (0.5-0.95)", str(current_threshold)) + try: + threshold = float(threshold_str) + if 0.5 <= threshold <= 0.95: + config["compression"]["threshold"] = threshold + except ValueError: + pass + + print_success( + f"Context compression threshold set to {config['compression'].get('threshold', 0.50)}" + ) + + # ── Session Reset Policy ── + print_header("Session Reset Policy") + print_info( + "Messaging sessions (Telegram, Discord, etc.) accumulate context over time." + ) + print_info( + "Each message adds to the conversation history, which means growing API costs." + ) + print_info("") + print_info( + "To manage this, sessions can automatically reset after a period of inactivity" + ) + print_info( + "or at a fixed time each day. When a reset happens, the agent saves important" + ) + print_info( + "things to its persistent memory first — but the conversation context is cleared." + ) + print_info("") + print_info("You can also manually reset anytime by typing /reset in chat.") + print_info("") + + reset_choices = [ + "Inactivity + daily reset (recommended - reset whichever comes first)", + "Inactivity only (reset after N minutes of no messages)", + "Daily only (reset at a fixed hour each day)", + "Never auto-reset (context lives until /reset or context compression)", + "Keep current settings", + ] + + current_policy = config.get("session_reset", {}) + current_mode = current_policy.get("mode", "both") + current_idle = current_policy.get("idle_minutes", 1440) + current_hour = current_policy.get("at_hour", 4) + + default_reset = {"both": 0, "idle": 1, "daily": 2, "none": 3}.get(current_mode, 0) + + reset_idx = prompt_choice("Session reset mode:", reset_choices, default_reset) + + config.setdefault("session_reset", {}) + + if reset_idx == 0: # Both + config["session_reset"]["mode"] = "both" + idle_str = prompt(" Inactivity timeout (minutes)", str(current_idle)) + try: + idle_val = int(idle_str) + if idle_val > 0: + config["session_reset"]["idle_minutes"] = idle_val + except ValueError: + pass + hour_str = prompt(" Daily reset hour (0-23, local time)", str(current_hour)) + try: + hour_val = int(hour_str) + if 0 <= hour_val <= 23: + config["session_reset"]["at_hour"] = hour_val + except ValueError: + pass + print_success( + f"Sessions reset after {config['session_reset'].get('idle_minutes', 1440)} min idle or daily at {config['session_reset'].get('at_hour', 4)}:00" + ) + elif reset_idx == 1: # Idle only + config["session_reset"]["mode"] = "idle" + idle_str = prompt(" Inactivity timeout (minutes)", str(current_idle)) + try: + idle_val = int(idle_str) + if idle_val > 0: + config["session_reset"]["idle_minutes"] = idle_val + except ValueError: + pass + print_success( + f"Sessions reset after {config['session_reset'].get('idle_minutes', 1440)} min of inactivity" + ) + elif reset_idx == 2: # Daily only + config["session_reset"]["mode"] = "daily" + hour_str = prompt(" Daily reset hour (0-23, local time)", str(current_hour)) + try: + hour_val = int(hour_str) + if 0 <= hour_val <= 23: + config["session_reset"]["at_hour"] = hour_val + except ValueError: + pass + print_success( + f"Sessions reset daily at {config['session_reset'].get('at_hour', 4)}:00" + ) + elif reset_idx == 3: # None + config["session_reset"]["mode"] = "none" + print_info( + "Sessions will never auto-reset. Context is managed only by compression." + ) + print_warning( + "Long conversations will grow in cost. Use /reset manually when needed." + ) + # else: keep current (idx == 4) + + save_config(config) + + +# ============================================================================= +# Section 4: Messaging Platforms (Gateway) +# ============================================================================= + + +def _setup_telegram(): + """Configure Telegram bot credentials and allowlist.""" + print_header("Telegram") + existing = get_env_value("TELEGRAM_BOT_TOKEN") + if existing: + print_info("Telegram: already configured") + if not prompt_yes_no("Reconfigure Telegram?", False): + # Check missing allowlist on existing config + if not get_env_value("TELEGRAM_ALLOWED_USERS"): + print_info("⚠️ Telegram has no user allowlist - anyone can use your bot!") + if prompt_yes_no("Add allowed users now?", True): + print_info(" To find your Telegram user ID: message @userinfobot") + allowed_users = prompt("Allowed user IDs (comma-separated)") + if allowed_users: + save_env_value("TELEGRAM_ALLOWED_USERS", allowed_users.replace(" ", "")) + print_success("Telegram allowlist configured") + return + + print_info("Create a bot via @BotFather on Telegram") + token = prompt("Telegram bot token", password=True) + if not token: + return + save_env_value("TELEGRAM_BOT_TOKEN", token) + print_success("Telegram token saved") + + print() + print_info("🔒 Security: Restrict who can use your bot") + print_info(" To find your Telegram user ID:") + print_info(" 1. Message @userinfobot on Telegram") + print_info(" 2. It will reply with your numeric ID (e.g., 123456789)") + print() + allowed_users = prompt( + "Allowed user IDs (comma-separated, leave empty for open access)" + ) + if allowed_users: + save_env_value("TELEGRAM_ALLOWED_USERS", allowed_users.replace(" ", "")) + print_success("Telegram allowlist configured - only listed users can use the bot") + else: + print_info("⚠️ No allowlist set - anyone who finds your bot can use it!") + + print() + print_info("📬 Home Channel: where Hermes delivers cron job results,") + print_info(" cross-platform messages, and notifications.") + print_info(" For Telegram DMs, this is your user ID (same as above).") + + first_user_id = allowed_users.split(",")[0].strip() if allowed_users else "" + if first_user_id: + if prompt_yes_no(f"Use your user ID ({first_user_id}) as the home channel?", True): + save_env_value("TELEGRAM_HOME_CHANNEL", first_user_id) + print_success(f"Telegram home channel set to {first_user_id}") + else: + home_channel = prompt("Home channel ID (or leave empty to set later with /set-home in Telegram)") + if home_channel: + save_env_value("TELEGRAM_HOME_CHANNEL", home_channel) + else: + print_info(" You can also set this later by typing /set-home in your Telegram chat.") + home_channel = prompt("Home channel ID (leave empty to set later)") + if home_channel: + save_env_value("TELEGRAM_HOME_CHANNEL", home_channel) + + +def _setup_discord(): + """Configure Discord bot credentials and allowlist.""" + print_header("Discord") + existing = get_env_value("DISCORD_BOT_TOKEN") + if existing: + print_info("Discord: already configured") + if not prompt_yes_no("Reconfigure Discord?", False): + if not get_env_value("DISCORD_ALLOWED_USERS"): + print_info("⚠️ Discord has no user allowlist - anyone can use your bot!") + if prompt_yes_no("Add allowed users now?", True): + print_info(" To find Discord ID: Enable Developer Mode, right-click name → Copy ID") + allowed_users = prompt("Allowed user IDs (comma-separated)") + if allowed_users: + cleaned_ids = _clean_discord_user_ids(allowed_users) + save_env_value("DISCORD_ALLOWED_USERS", ",".join(cleaned_ids)) + print_success("Discord allowlist configured") + return + + print_info("Create a bot at https://discord.com/developers/applications") + token = prompt("Discord bot token", password=True) + if not token: + return + save_env_value("DISCORD_BOT_TOKEN", token) + print_success("Discord token saved") + + print() + print_info("🔒 Security: Restrict who can use your bot") + print_info(" To find your Discord user ID:") + print_info(" 1. Enable Developer Mode in Discord settings") + print_info(" 2. Right-click your name → Copy ID") + print() + print_info(" You can also use Discord usernames (resolved on gateway start).") + print() + allowed_users = prompt( + "Allowed user IDs or usernames (comma-separated, leave empty for open access)" + ) + if allowed_users: + cleaned_ids = _clean_discord_user_ids(allowed_users) + save_env_value("DISCORD_ALLOWED_USERS", ",".join(cleaned_ids)) + print_success("Discord allowlist configured") + else: + print_info("⚠️ No allowlist set - anyone in servers with your bot can use it!") + + print() + print_info("📬 Home Channel: where Hermes delivers cron job results,") + print_info(" cross-platform messages, and notifications.") + print_info(" To get a channel ID: right-click a channel → Copy Channel ID") + print_info(" (requires Developer Mode in Discord settings)") + print_info(" You can also set this later by typing /set-home in a Discord channel.") + home_channel = prompt("Home channel ID (leave empty to set later with /set-home)") + if home_channel: + save_env_value("DISCORD_HOME_CHANNEL", home_channel) + + +def _clean_discord_user_ids(raw: str) -> list: + """Strip common Discord mention prefixes from a comma-separated ID string.""" + cleaned = [] + for uid in raw.replace(" ", "").split(","): + uid = uid.strip() + if uid.startswith("<@") and uid.endswith(">"): + uid = uid.lstrip("<@!").rstrip(">") + if uid.lower().startswith("user:"): + uid = uid[5:] + if uid: + cleaned.append(uid) + return cleaned + + +def _setup_slack(): + """Configure Slack bot credentials.""" + print_header("Slack") + existing = get_env_value("SLACK_BOT_TOKEN") + if existing: + print_info("Slack: already configured") + if not prompt_yes_no("Reconfigure Slack?", False): + return + + print_info("Steps to create a Slack app:") + print_info(" 1. Go to https://api.slack.com/apps → Create New App (from scratch)") + print_info(" 2. Enable Socket Mode: Settings → Socket Mode → Enable") + print_info(" • Create an App-Level Token with 'connections:write' scope") + print_info(" 3. Add Bot Token Scopes: Features → OAuth & Permissions") + print_info(" Required scopes: chat:write, app_mentions:read,") + print_info(" channels:history, channels:read, im:history,") + print_info(" im:read, im:write, users:read, files:read, files:write") + print_info(" Optional for private channels: groups:history") + print_info(" 4. Subscribe to Events: Features → Event Subscriptions → Enable") + print_info(" Required events: message.im, message.channels, app_mention") + print_info(" Optional for private channels: message.groups") + print_warning(" ⚠ Without message.channels the bot will ONLY work in DMs,") + print_warning(" not public channels.") + print_info(" 5. Install to Workspace: Settings → Install App") + print_info(" 6. Reinstall the app after any scope or event changes") + print_info(" 7. After installing, invite the bot to channels: /invite @YourBot") + print() + print_info(" Full guide: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/slack/") + print() + bot_token = prompt("Slack Bot Token (xoxb-...)", password=True) + if not bot_token: + return + save_env_value("SLACK_BOT_TOKEN", bot_token) + app_token = prompt("Slack App Token (xapp-...)", password=True) + if app_token: + save_env_value("SLACK_APP_TOKEN", app_token) + print_success("Slack tokens saved") + + print() + print_info("🔒 Security: Restrict who can use your bot") + print_info(" To find a Member ID: click a user's name → View full profile → ⋮ → Copy member ID") + print() + allowed_users = prompt( + "Allowed user IDs (comma-separated, leave empty to deny everyone except paired users)" + ) + if allowed_users: + save_env_value("SLACK_ALLOWED_USERS", allowed_users.replace(" ", "")) + print_success("Slack allowlist configured") + else: + print_warning("⚠️ No Slack allowlist set - unpaired users will be denied by default.") + print_info(" Set SLACK_ALLOW_ALL_USERS=true or GATEWAY_ALLOW_ALL_USERS=true only if you intentionally want open workspace access.") + + +def _setup_matrix(): + """Configure Matrix credentials.""" + print_header("Matrix") + existing = get_env_value("MATRIX_ACCESS_TOKEN") or get_env_value("MATRIX_PASSWORD") + if existing: + print_info("Matrix: already configured") + if not prompt_yes_no("Reconfigure Matrix?", False): + return + + print_info("Works with any Matrix homeserver (Synapse, Conduit, Dendrite, or matrix.org).") + print_info(" 1. Create a bot user on your homeserver, or use your own account") + print_info(" 2. Get an access token from Element, or provide user ID + password") + print() + homeserver = prompt("Homeserver URL (e.g. https://matrix.example.org)") + if homeserver: + save_env_value("MATRIX_HOMESERVER", homeserver.rstrip("/")) + + print() + print_info("Auth: provide an access token (recommended), or user ID + password.") + token = prompt("Access token (leave empty for password login)", password=True) + if token: + save_env_value("MATRIX_ACCESS_TOKEN", token) + user_id = prompt("User ID (@bot:server — optional, will be auto-detected)") + if user_id: + save_env_value("MATRIX_USER_ID", user_id) + print_success("Matrix access token saved") + else: + user_id = prompt("User ID (@bot:server)") + if user_id: + save_env_value("MATRIX_USER_ID", user_id) + password = prompt("Password", password=True) + if password: + save_env_value("MATRIX_PASSWORD", password) + print_success("Matrix credentials saved") + + if token or get_env_value("MATRIX_PASSWORD"): + print() + want_e2ee = prompt_yes_no("Enable end-to-end encryption (E2EE)?", False) + if want_e2ee: + save_env_value("MATRIX_ENCRYPTION", "true") + print_success("E2EE enabled") + + matrix_pkg = "mautrix[encryption]" if want_e2ee else "mautrix" + try: + __import__("mautrix") + except ImportError: + print_info(f"Installing {matrix_pkg}...") + import subprocess + uv_bin = shutil.which("uv") + if uv_bin: + result = subprocess.run( + [uv_bin, "pip", "install", "--python", sys.executable, matrix_pkg], + capture_output=True, text=True, + ) + else: + result = subprocess.run( + [sys.executable, "-m", "pip", "install", matrix_pkg], + capture_output=True, text=True, + ) + if result.returncode == 0: + print_success(f"{matrix_pkg} installed") + else: + print_warning(f"Install failed — run manually: pip install '{matrix_pkg}'") + if result.stderr: + print_info(f" Error: {result.stderr.strip().splitlines()[-1]}") + + print() + print_info("🔒 Security: Restrict who can use your bot") + print_info(" Matrix user IDs look like @username:server") + print() + allowed_users = prompt("Allowed user IDs (comma-separated, leave empty for open access)") + if allowed_users: + save_env_value("MATRIX_ALLOWED_USERS", allowed_users.replace(" ", "")) + print_success("Matrix allowlist configured") + else: + print_info("⚠️ No allowlist set - anyone who can message the bot can use it!") + + print() + print_info("📬 Home Room: where Hermes delivers cron job results and notifications.") + print_info(" Room IDs look like !abc123:server (shown in Element room settings)") + print_info(" You can also set this later by typing /set-home in a Matrix room.") + home_room = prompt("Home room ID (leave empty to set later with /set-home)") + if home_room: + save_env_value("MATRIX_HOME_ROOM", home_room) + + +def _setup_mattermost(): + """Configure Mattermost bot credentials.""" + print_header("Mattermost") + existing = get_env_value("MATTERMOST_TOKEN") + if existing: + print_info("Mattermost: already configured") + if not prompt_yes_no("Reconfigure Mattermost?", False): + return + + print_info("Works with any self-hosted Mattermost instance.") + print_info(" 1. In Mattermost: Integrations → Bot Accounts → Add Bot Account") + print_info(" 2. Copy the bot token") + print() + mm_url = prompt("Mattermost server URL (e.g. https://mm.example.com)") + if mm_url: + save_env_value("MATTERMOST_URL", mm_url.rstrip("/")) + token = prompt("Bot token", password=True) + if not token: + return + save_env_value("MATTERMOST_TOKEN", token) + print_success("Mattermost token saved") + + print() + print_info("🔒 Security: Restrict who can use your bot") + print_info(" To find your user ID: click your avatar → Profile") + print_info(" or use the API: GET /api/v4/users/me") + print() + allowed_users = prompt("Allowed user IDs (comma-separated, leave empty for open access)") + if allowed_users: + save_env_value("MATTERMOST_ALLOWED_USERS", allowed_users.replace(" ", "")) + print_success("Mattermost allowlist configured") + else: + print_info("⚠️ No allowlist set - anyone who can message the bot can use it!") + + print() + print_info("📬 Home Channel: where Hermes delivers cron job results and notifications.") + print_info(" To get a channel ID: click channel name → View Info → copy the ID") + print_info(" You can also set this later by typing /set-home in a Mattermost channel.") + home_channel = prompt("Home channel ID (leave empty to set later with /set-home)") + if home_channel: + save_env_value("MATTERMOST_HOME_CHANNEL", home_channel) + + +def _setup_whatsapp(): + """Configure WhatsApp bridge.""" + print_header("WhatsApp") + existing = get_env_value("WHATSAPP_ENABLED") + if existing: + print_info("WhatsApp: already enabled") + return + + print_info("WhatsApp connects via a built-in bridge (Baileys).") + print_info("Requires Node.js. Run 'hermes whatsapp' for guided setup.") + print() + if prompt_yes_no("Enable WhatsApp now?", True): + save_env_value("WHATSAPP_ENABLED", "true") + print_success("WhatsApp enabled") + print_info("Run 'hermes whatsapp' to choose your mode (separate bot number") + print_info("or personal self-chat) and pair via QR code.") + + +def _setup_weixin(): + """Configure Weixin (personal WeChat) via iLink Bot API QR login.""" + from hermes_cli.gateway import _setup_weixin as _gateway_setup_weixin + _gateway_setup_weixin() + + +def _setup_signal(): + """Configure Signal via gateway setup.""" + from hermes_cli.gateway import _setup_signal as _gateway_setup_signal + _gateway_setup_signal() + + +def _setup_email(): + """Configure Email via gateway setup.""" + from hermes_cli.gateway import _setup_email as _gateway_setup_email + _gateway_setup_email() + + +def _setup_sms(): + """Configure SMS (Twilio) via gateway setup.""" + from hermes_cli.gateway import _setup_sms as _gateway_setup_sms + _gateway_setup_sms() + + +def _setup_dingtalk(): + """Configure DingTalk via gateway setup.""" + from hermes_cli.gateway import _setup_dingtalk as _gateway_setup_dingtalk + _gateway_setup_dingtalk() + + +def _setup_feishu(): + """Configure Feishu / Lark via gateway setup.""" + from hermes_cli.gateway import _setup_feishu as _gateway_setup_feishu + _gateway_setup_feishu() + + +def _setup_wecom(): + """Configure WeCom (Enterprise WeChat) via gateway setup.""" + from hermes_cli.gateway import _setup_wecom as _gateway_setup_wecom + _gateway_setup_wecom() + + +def _setup_wecom_callback(): + """Configure WeCom Callback (self-built app) via gateway setup.""" + from hermes_cli.gateway import _setup_wecom_callback as _gw_setup + _gw_setup() + + +def _setup_qqbot(): + """Configure QQ Bot gateway.""" + print_header("QQ Bot") + existing = get_env_value("QQ_APP_ID") + if existing: + print_info("QQ Bot: already configured") + if not prompt_yes_no("Reconfigure QQ Bot?", False): + return + + print_info("Connects Hermes to QQ via the Official QQ Bot API (v2).") + print_info(" Requires a QQ Bot application at q.qq.com") + print_info(" Reference: https://bot.q.qq.com/wiki/develop/api-v2/") + print() + + app_id = prompt("QQ Bot App ID") + if not app_id: + print_warning("App ID is required — skipping QQ Bot setup") + return + save_env_value("QQ_APP_ID", app_id.strip()) + + client_secret = prompt("QQ Bot App Secret", password=True) + if not client_secret: + print_warning("App Secret is required — skipping QQ Bot setup") + return + save_env_value("QQ_CLIENT_SECRET", client_secret) + print_success("QQ Bot credentials saved") + + print() + print_info("🔒 Security: Restrict who can DM your bot") + print_info(" Use QQ user OpenIDs (found in event payloads)") + print() + allowed_users = prompt("Allowed user OpenIDs (comma-separated, leave empty for open access)") + if allowed_users: + save_env_value("QQ_ALLOWED_USERS", allowed_users.replace(" ", "")) + print_success("QQ Bot allowlist configured") + else: + print_info("⚠️ No allowlist set — anyone can DM the bot!") + + print() + print_info("📬 Home Channel: OpenID for cron job delivery and notifications.") + home_channel = prompt("Home channel OpenID (leave empty to set later)") + if home_channel: + save_env_value("QQ_HOME_CHANNEL", home_channel) + + print() + print_success("QQ Bot configured!") + + +def _setup_bluebubbles(): + """Configure BlueBubbles iMessage gateway.""" + print_header("BlueBubbles (iMessage)") + existing = get_env_value("BLUEBUBBLES_SERVER_URL") + if existing: + print_info("BlueBubbles: already configured") + if not prompt_yes_no("Reconfigure BlueBubbles?", False): + return + + print_info("Connects Hermes to iMessage via BlueBubbles — a free, open-source") + print_info("macOS server that bridges iMessage to any device.") + print_info(" Requires a Mac running BlueBubbles Server v1.0.0+") + print_info(" Download: https://bluebubbles.app/") + print() + print_info("In BlueBubbles Server → Settings → API, note your Server URL and Password.") + print() + + server_url = prompt("BlueBubbles server URL (e.g. http://192.168.1.10:1234)") + if not server_url: + print_warning("Server URL is required — skipping BlueBubbles setup") + return + save_env_value("BLUEBUBBLES_SERVER_URL", server_url.rstrip("/")) + + password = prompt("BlueBubbles server password", password=True) + if not password: + print_warning("Password is required — skipping BlueBubbles setup") + return + save_env_value("BLUEBUBBLES_PASSWORD", password) + print_success("BlueBubbles credentials saved") + + print() + print_info("🔒 Security: Restrict who can message your bot") + print_info(" Use iMessage addresses: email (user@icloud.com) or phone (+15551234567)") + print() + allowed_users = prompt("Allowed iMessage addresses (comma-separated, leave empty for open access)") + if allowed_users: + save_env_value("BLUEBUBBLES_ALLOWED_USERS", allowed_users.replace(" ", "")) + print_success("BlueBubbles allowlist configured") + else: + print_info("⚠️ No allowlist set — anyone who can iMessage you can use the bot!") + + print() + print_info("📬 Home Channel: phone or email for cron job delivery and notifications.") + print_info(" You can also set this later with /set-home in your iMessage chat.") + home_channel = prompt("Home channel address (leave empty to set later)") + if home_channel: + save_env_value("BLUEBUBBLES_HOME_CHANNEL", home_channel) + + print() + print_info("Advanced settings (defaults are fine for most setups):") + if prompt_yes_no("Configure webhook listener settings?", False): + webhook_port = prompt("Webhook listener port (default: 8645)") + if webhook_port: + try: + save_env_value("BLUEBUBBLES_WEBHOOK_PORT", str(int(webhook_port))) + print_success(f"Webhook port set to {webhook_port}") + except ValueError: + print_warning("Invalid port number, using default 8645") + + print() + print_info("Requires the BlueBubbles Private API helper for typing indicators,") + print_info("read receipts, and tapback reactions. Basic messaging works without it.") + print_info(" Install: https://docs.bluebubbles.app/helper-bundle/installation") + + +def _setup_qqbot(): + """Configure QQ Bot (Official API v2) via standard platform setup.""" + from hermes_cli.gateway import _PLATFORMS + qq_platform = next((p for p in _PLATFORMS if p["key"] == "qqbot"), None) + if qq_platform: + from hermes_cli.gateway import _setup_standard_platform + _setup_standard_platform(qq_platform) + + +def _setup_webhooks(): + """Configure webhook integration.""" + print_header("Webhooks") + existing = get_env_value("WEBHOOK_ENABLED") + if existing: + print_info("Webhooks: already configured") + if not prompt_yes_no("Reconfigure webhooks?", False): + return + + print() + print_warning("⚠ Webhook and SMS platforms require exposing gateway ports to the") + print_warning(" internet. For security, run the gateway in a sandboxed environment") + print_warning(" (Docker, VM, etc.) to limit blast radius from prompt injection.") + print() + print_info(" Full guide: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/webhooks/") + print() + + port = prompt("Webhook port (default 8644)") + if port: + try: + save_env_value("WEBHOOK_PORT", str(int(port))) + print_success(f"Webhook port set to {port}") + except ValueError: + print_warning("Invalid port number, using default 8644") + + secret = prompt("Global HMAC secret (shared across all routes)", password=True) + if secret: + save_env_value("WEBHOOK_SECRET", secret) + print_success("Webhook secret saved") + else: + print_warning("No secret set — you must configure per-route secrets in config.yaml") + + save_env_value("WEBHOOK_ENABLED", "true") + print() + print_success("Webhooks enabled! Next steps:") + from hermes_constants import display_hermes_home as _dhh + print_info(f" 1. Define webhook routes in {_dhh()}/config.yaml") + print_info(" 2. Point your service (GitHub, GitLab, etc.) at:") + print_info(" http://your-server:8644/webhooks/") + print() + print_info(" Route configuration guide:") + print_info(" https://hermes-agent.nousresearch.com/docs/user-guide/messaging/webhooks/#configuring-routes") + print() + print_info(" Open config in your editor: hermes config edit") + + +# Platform registry for the gateway checklist +_GATEWAY_PLATFORMS = [ + ("Telegram", "TELEGRAM_BOT_TOKEN", _setup_telegram), + ("Discord", "DISCORD_BOT_TOKEN", _setup_discord), + ("Slack", "SLACK_BOT_TOKEN", _setup_slack), + ("Signal", "SIGNAL_HTTP_URL", _setup_signal), + ("Email", "EMAIL_ADDRESS", _setup_email), + ("SMS (Twilio)", "TWILIO_ACCOUNT_SID", _setup_sms), + ("Matrix", "MATRIX_ACCESS_TOKEN", _setup_matrix), + ("Mattermost", "MATTERMOST_TOKEN", _setup_mattermost), + ("WhatsApp", "WHATSAPP_ENABLED", _setup_whatsapp), + ("DingTalk", "DINGTALK_CLIENT_ID", _setup_dingtalk), + ("Feishu / Lark", "FEISHU_APP_ID", _setup_feishu), + ("WeCom (Enterprise WeChat)", "WECOM_BOT_ID", _setup_wecom), + ("WeCom Callback (Self-Built App)", "WECOM_CALLBACK_CORP_ID", _setup_wecom_callback), + ("Weixin (WeChat)", "WEIXIN_ACCOUNT_ID", _setup_weixin), + ("BlueBubbles (iMessage)", "BLUEBUBBLES_SERVER_URL", _setup_bluebubbles), + ("QQ Bot", "QQ_APP_ID", _setup_qqbot), + ("Webhooks (GitHub, GitLab, etc.)", "WEBHOOK_ENABLED", _setup_webhooks), +] + + +def setup_gateway(config: dict): + """Configure messaging platform integrations.""" + print_header("Messaging Platforms") + print_info("Connect to messaging platforms to chat with Hermes from anywhere.") + print_info("Toggle with Space, confirm with Enter.") + print() + + # Build checklist items, pre-selecting already-configured platforms + items = [] + pre_selected = [] + for i, (name, env_var, _func) in enumerate(_GATEWAY_PLATFORMS): + # Matrix has two possible env vars + is_configured = bool(get_env_value(env_var)) + if name == "Matrix" and not is_configured: + is_configured = bool(get_env_value("MATRIX_PASSWORD")) + label = f"{name} (configured)" if is_configured else name + items.append(label) + if is_configured: + pre_selected.append(i) + + selected = prompt_checklist("Select platforms to configure:", items, pre_selected) + + if not selected: + print_info("No platforms selected. Run 'hermes setup gateway' later to configure.") + return + + for idx in selected: + name, _env_var, setup_func = _GATEWAY_PLATFORMS[idx] + setup_func() + + # ── Gateway Service Setup ── + any_messaging = ( + get_env_value("TELEGRAM_BOT_TOKEN") + or get_env_value("DISCORD_BOT_TOKEN") + or get_env_value("SLACK_BOT_TOKEN") + or get_env_value("SIGNAL_HTTP_URL") + or get_env_value("EMAIL_ADDRESS") + or get_env_value("TWILIO_ACCOUNT_SID") + or get_env_value("MATTERMOST_TOKEN") + or get_env_value("MATRIX_ACCESS_TOKEN") + or get_env_value("MATRIX_PASSWORD") + or get_env_value("WHATSAPP_ENABLED") + or get_env_value("DINGTALK_CLIENT_ID") + or get_env_value("FEISHU_APP_ID") + or get_env_value("WECOM_BOT_ID") + or get_env_value("WEIXIN_ACCOUNT_ID") + or get_env_value("BLUEBUBBLES_SERVER_URL") + or get_env_value("QQ_APP_ID") + or get_env_value("WEBHOOK_ENABLED") + ) + if any_messaging: + print() + print_info("━" * 50) + print_success("Messaging platforms configured!") + + # Check if any home channels are missing + missing_home = [] + if get_env_value("TELEGRAM_BOT_TOKEN") and not get_env_value( + "TELEGRAM_HOME_CHANNEL" + ): + missing_home.append("Telegram") + if get_env_value("DISCORD_BOT_TOKEN") and not get_env_value( + "DISCORD_HOME_CHANNEL" + ): + missing_home.append("Discord") + if get_env_value("SLACK_BOT_TOKEN") and not get_env_value("SLACK_HOME_CHANNEL"): + missing_home.append("Slack") + if get_env_value("BLUEBUBBLES_SERVER_URL") and not get_env_value("BLUEBUBBLES_HOME_CHANNEL"): + missing_home.append("BlueBubbles") + if get_env_value("QQ_APP_ID") and not get_env_value("QQ_HOME_CHANNEL"): + missing_home.append("QQBot") + + if missing_home: + print() + print_warning(f"No home channel set for: {', '.join(missing_home)}") + print_info(" Without a home channel, cron jobs and cross-platform") + print_info(" messages can't be delivered to those platforms.") + print_info(" Set one later with /set-home in your chat, or:") + for plat in missing_home: + print_info( + f" hermes config set {plat.upper()}_HOME_CHANNEL " + ) + + # Offer to install the gateway as a system service + import platform as _platform + + _is_linux = _platform.system() == "Linux" + _is_macos = _platform.system() == "Darwin" + + from hermes_cli.gateway import ( + _is_service_installed, + _is_service_running, + supports_systemd_services, + has_conflicting_systemd_units, + install_linux_gateway_from_setup, + print_systemd_scope_conflict_warning, + systemd_start, + systemd_restart, + launchd_install, + launchd_start, + launchd_restart, + ) + + service_installed = _is_service_installed() + service_running = _is_service_running() + supports_systemd = supports_systemd_services() + supports_service_manager = supports_systemd or _is_macos + + print() + if supports_systemd and has_conflicting_systemd_units(): + print_systemd_scope_conflict_warning() + print() + + if service_running: + if prompt_yes_no(" Restart the gateway to pick up changes?", True): + try: + if supports_systemd: + systemd_restart() + elif _is_macos: + launchd_restart() + except Exception as e: + print_error(f" Restart failed: {e}") + elif service_installed: + if prompt_yes_no(" Start the gateway service?", True): + try: + if supports_systemd: + systemd_start() + elif _is_macos: + launchd_start() + except Exception as e: + print_error(f" Start failed: {e}") + elif supports_service_manager: + svc_name = "systemd" if supports_systemd else "launchd" + if prompt_yes_no( + f" Install the gateway as a {svc_name} service? (runs in background, starts on boot)", + True, + ): + try: + installed_scope = None + did_install = False + if supports_systemd: + installed_scope, did_install = install_linux_gateway_from_setup(force=False) + else: + launchd_install(force=False) + did_install = True + print() + if did_install and prompt_yes_no(" Start the service now?", True): + try: + if supports_systemd: + systemd_start(system=installed_scope == "system") + elif _is_macos: + launchd_start() + except Exception as e: + print_error(f" Start failed: {e}") + except Exception as e: + print_error(f" Install failed: {e}") + print_info(" You can try manually: hermes gateway install") + else: + print_info(" You can install later: hermes gateway install") + if supports_systemd: + print_info(" Or as a boot-time service: sudo hermes gateway install --system") + print_info(" Or run in foreground: hermes gateway") + else: + from hermes_constants import is_container + if is_container(): + print_info("Start the gateway to bring your bots online:") + print_info(" hermes gateway run # Run as container main process") + print_info("") + print_info("For automatic restarts, use a Docker restart policy:") + print_info(" docker run --restart unless-stopped ...") + print_info(" docker restart # Manual restart") + else: + print_info("Start the gateway to bring your bots online:") + print_info(" hermes gateway # Run in foreground") + + print_info("━" * 50) + + +# ============================================================================= +# Section 5: Tool Configuration (delegates to unified tools_config.py) +# ============================================================================= + + +def setup_tools(config: dict, first_install: bool = False): + """Configure tools — delegates to the unified tools_command() in tools_config.py. + + Both `hermes setup tools` and `hermes tools` use the same flow: + platform selection → toolset toggles → provider/API key configuration. + + Args: + first_install: When True, uses the simplified first-install flow + (no platform menu, prompts for all unconfigured API keys). + """ + from hermes_cli.tools_config import tools_command + + tools_command(first_install=first_install, config=config) + + +# ============================================================================= +# Post-Migration Section Skip Logic +# ============================================================================= + + +def _get_section_config_summary(config: dict, section_key: str) -> Optional[str]: + """Return a short summary if a setup section is already configured, else None. + + Used after OpenClaw migration to detect which sections can be skipped. + ``get_env_value`` is the module-level import from hermes_cli.config + so that test patches on ``setup_mod.get_env_value`` take effect. + """ + if section_key == "model": + has_key = bool( + get_env_value("OPENROUTER_API_KEY") + or get_env_value("OPENAI_API_KEY") + or get_env_value("ANTHROPIC_API_KEY") + ) + if not has_key: + # Check for OAuth providers + try: + from hermes_cli.auth import get_active_provider + if get_active_provider(): + has_key = True + except Exception: + pass + if not has_key: + return None + model = config.get("model") + if isinstance(model, str) and model.strip(): + return model.strip() + if isinstance(model, dict): + return str(model.get("default") or model.get("model") or "configured") + return "configured" + + elif section_key == "terminal": + backend = config.get("terminal", {}).get("backend", "local") + return f"backend: {backend}" + + elif section_key == "agent": + max_turns = config.get("agent", {}).get("max_turns", 90) + return f"max turns: {max_turns}" + + elif section_key == "gateway": + platforms = [] + if get_env_value("TELEGRAM_BOT_TOKEN"): + platforms.append("Telegram") + if get_env_value("DISCORD_BOT_TOKEN"): + platforms.append("Discord") + if get_env_value("SLACK_BOT_TOKEN"): + platforms.append("Slack") + if get_env_value("SIGNAL_ACCOUNT"): + platforms.append("Signal") + if get_env_value("EMAIL_ADDRESS"): + platforms.append("Email") + if get_env_value("TWILIO_ACCOUNT_SID"): + platforms.append("SMS") + if get_env_value("MATRIX_ACCESS_TOKEN") or get_env_value("MATRIX_PASSWORD"): + platforms.append("Matrix") + if get_env_value("MATTERMOST_TOKEN"): + platforms.append("Mattermost") + if get_env_value("WHATSAPP_PHONE_NUMBER_ID"): + platforms.append("WhatsApp") + if get_env_value("DINGTALK_CLIENT_ID"): + platforms.append("DingTalk") + if get_env_value("FEISHU_APP_ID"): + platforms.append("Feishu") + if get_env_value("WECOM_BOT_ID"): + platforms.append("WeCom") + if get_env_value("WEIXIN_ACCOUNT_ID"): + platforms.append("Weixin") + if get_env_value("BLUEBUBBLES_SERVER_URL"): + platforms.append("BlueBubbles") + if get_env_value("WEBHOOK_ENABLED"): + platforms.append("Webhooks") + if platforms: + return ", ".join(platforms) + return None # No platforms configured — section must run + + elif section_key == "tools": + tools = [] + if get_env_value("ELEVENLABS_API_KEY"): + tools.append("TTS/ElevenLabs") + if get_env_value("BROWSERBASE_API_KEY"): + tools.append("Browser") + if get_env_value("FIRECRAWL_API_KEY"): + tools.append("Firecrawl") + if tools: + return ", ".join(tools) + return None + + return None + + +def _skip_configured_section( + config: dict, section_key: str, label: str +) -> bool: + """Show an already-configured section summary and offer to skip. + + Returns True if the user chose to skip, False if the section should run. + """ + summary = _get_section_config_summary(config, section_key) + if not summary: + return False + print() + print_success(f" {label}: {summary}") + return not prompt_yes_no(f" Reconfigure {label.lower()}?", default=False) + + +# ============================================================================= +# OpenClaw Migration +# ============================================================================= + + +_OPENCLAW_SCRIPT = ( + get_optional_skills_dir(PROJECT_ROOT / "optional-skills") + / "migration" + / "openclaw-migration" + / "scripts" + / "openclaw_to_hermes.py" +) + + +def _load_openclaw_migration_module(): + """Load the openclaw_to_hermes migration script as a module. + + Returns the loaded module, or None if the script can't be loaded. + """ + if not _OPENCLAW_SCRIPT.exists(): + return None + + spec = importlib.util.spec_from_file_location( + "openclaw_to_hermes", _OPENCLAW_SCRIPT + ) + if spec is None or spec.loader is None: + return None + + mod = importlib.util.module_from_spec(spec) + # Register in sys.modules so @dataclass can resolve the module + # (Python 3.11+ requires this for dynamically loaded modules) + import sys as _sys + _sys.modules[spec.name] = mod + try: + spec.loader.exec_module(mod) + except Exception: + _sys.modules.pop(spec.name, None) + raise + return mod + + +# Item kinds that represent high-impact changes warranting explicit warnings. +# Gateway tokens/channels can hijack messaging platforms from the old agent. +# Config values may have different semantics between OpenClaw and Hermes. +# Instruction/context files (.md) can contain incompatible setup procedures. +_HIGH_IMPACT_KIND_KEYWORDS = { + "gateway": "⚠ Gateway/messaging — this will configure Hermes to use your OpenClaw messaging channels", + "telegram": "⚠ Telegram — this will point Hermes at your OpenClaw Telegram bot", + "slack": "⚠ Slack — this will point Hermes at your OpenClaw Slack workspace", + "discord": "⚠ Discord — this will point Hermes at your OpenClaw Discord bot", + "whatsapp": "⚠ WhatsApp — this will point Hermes at your OpenClaw WhatsApp connection", + "config": "⚠ Config values — OpenClaw settings may not map 1:1 to Hermes equivalents", + "soul": "⚠ Instruction file — may contain OpenClaw-specific setup/restart procedures", + "memory": "⚠ Memory/context file — may reference OpenClaw-specific infrastructure", + "context": "⚠ Context file — may contain OpenClaw-specific instructions", +} + + +def _print_migration_preview(report: dict): + """Print a detailed dry-run preview of what migration would do. + + Groups items by category and adds explicit warnings for high-impact + changes like gateway token takeover and config value differences. + """ + items = report.get("items", []) + if not items: + print_info("Nothing to migrate.") + return + + migrated_items = [i for i in items if i.get("status") == "migrated"] + conflict_items = [i for i in items if i.get("status") == "conflict"] + skipped_items = [i for i in items if i.get("status") == "skipped"] + + warnings_shown = set() + + if migrated_items: + print(color(" Would import:", Colors.GREEN)) + for item in migrated_items: + kind = item.get("kind", "unknown") + dest = item.get("destination", "") + if dest: + dest_short = str(dest).replace(str(Path.home()), "~") + print(f" {kind:<22s} → {dest_short}") + else: + print(f" {kind}") + + # Check for high-impact items and collect warnings + kind_lower = kind.lower() + dest_lower = str(dest).lower() + for keyword, warning in _HIGH_IMPACT_KIND_KEYWORDS.items(): + if keyword in kind_lower or keyword in dest_lower: + warnings_shown.add(warning) + print() + + if conflict_items: + print(color(" Would overwrite (conflicts with existing Hermes config):", Colors.YELLOW)) + for item in conflict_items: + kind = item.get("kind", "unknown") + reason = item.get("reason", "already exists") + print(f" {kind:<22s} {reason}") + print() + + if skipped_items: + print(color(" Would skip:", Colors.DIM)) + for item in skipped_items: + kind = item.get("kind", "unknown") + reason = item.get("reason", "") + print(f" {kind:<22s} {reason}") + print() + + # Print collected warnings + if warnings_shown: + print(color(" ── Warnings ──", Colors.YELLOW)) + for warning in sorted(warnings_shown): + print(color(f" {warning}", Colors.YELLOW)) + print() + print(color(" Note: OpenClaw config values may have different semantics in Hermes.", Colors.YELLOW)) + print(color(" For example, OpenClaw's tool_call_execution: \"auto\" ≠ Hermes's yolo mode.", Colors.YELLOW)) + print(color(" Instruction files (.md) from OpenClaw may contain incompatible procedures.", Colors.YELLOW)) + print() + + +def _offer_openclaw_migration(hermes_home: Path) -> bool: + """Detect ~/.openclaw and offer to migrate during first-time setup. + + Runs a dry-run first to show the user exactly what would be imported, + overwritten, or taken over. Only executes after explicit confirmation. + + Returns True if migration ran successfully, False otherwise. + """ + openclaw_dir = Path.home() / ".openclaw" + if not openclaw_dir.is_dir(): + return False + + if not _OPENCLAW_SCRIPT.exists(): + return False + + print() + print_header("OpenClaw Installation Detected") + print_info(f"Found OpenClaw data at {openclaw_dir}") + print_info("Hermes can preview what would be imported before making any changes.") + print() + + if not prompt_yes_no("Would you like to see what can be imported?", default=True): + print_info( + "Skipping migration. You can run it later with: hermes claw migrate --dry-run" + ) + return False + + # Ensure config.yaml exists before migration tries to read it + config_path = get_config_path() + if not config_path.exists(): + save_config(load_config()) + + # Load the migration module + try: + mod = _load_openclaw_migration_module() + if mod is None: + print_warning("Could not load migration script.") + return False + except Exception as e: + print_warning(f"Could not load migration script: {e}") + logger.debug("OpenClaw migration module load error", exc_info=True) + return False + + # ── Phase 1: Dry-run preview ── + try: + selected = mod.resolve_selected_options(None, None, preset="full") + dry_migrator = mod.Migrator( + source_root=openclaw_dir.resolve(), + target_root=hermes_home.resolve(), + execute=False, # dry-run — no files modified + workspace_target=None, + overwrite=True, # show everything including conflicts + migrate_secrets=True, + output_dir=None, + selected_options=selected, + preset_name="full", + ) + preview_report = dry_migrator.migrate() + except Exception as e: + print_warning(f"Migration preview failed: {e}") + logger.debug("OpenClaw migration preview error", exc_info=True) + return False + + # Display the full preview + preview_summary = preview_report.get("summary", {}) + preview_count = preview_summary.get("migrated", 0) + + if preview_count == 0: + print() + print_info("Nothing to import from OpenClaw.") + return False + + print() + print_header(f"Migration Preview — {preview_count} item(s) would be imported") + print_info("No changes have been made yet. Review the list below:") + print() + _print_migration_preview(preview_report) + + # ── Phase 2: Confirm and execute ── + if not prompt_yes_no("Proceed with migration?", default=False): + print_info( + "Migration cancelled. You can run it later with: hermes claw migrate" + ) + print_info( + "Use --dry-run to preview again, or --preset minimal for a lighter import." + ) + return False + + # Execute the migration — overwrite=False so existing Hermes configs are + # preserved. The user saw the preview; conflicts are skipped by default. + try: + migrator = mod.Migrator( + source_root=openclaw_dir.resolve(), + target_root=hermes_home.resolve(), + execute=True, + workspace_target=None, + overwrite=False, # preserve existing Hermes config + migrate_secrets=True, + output_dir=None, + selected_options=selected, + preset_name="full", + ) + report = migrator.migrate() + except Exception as e: + print_warning(f"Migration failed: {e}") + logger.debug("OpenClaw migration error", exc_info=True) + return False + + # Print final summary + summary = report.get("summary", {}) + migrated = summary.get("migrated", 0) + skipped = summary.get("skipped", 0) + conflicts = summary.get("conflict", 0) + errors = summary.get("error", 0) + + print() + if migrated: + print_success(f"Imported {migrated} item(s) from OpenClaw.") + if conflicts: + print_info(f"Skipped {conflicts} item(s) that already exist in Hermes (use hermes claw migrate --overwrite to force).") + if skipped: + print_info(f"Skipped {skipped} item(s) (not found or unchanged).") + if errors: + print_warning(f"{errors} item(s) had errors — check the migration report.") + + output_dir = report.get("output_dir") + if output_dir: + print_info(f"Full report saved to: {output_dir}") + + print_success("Migration complete! Continuing with setup...") + return True + + +# ============================================================================= +# Main Wizard Orchestrator +# ============================================================================= + +SETUP_SECTIONS = [ + ("model", "Model & Provider", setup_model_provider), + ("tts", "Text-to-Speech", setup_tts), + ("terminal", "Terminal Backend", setup_terminal_backend), + ("gateway", "Messaging Platforms (Gateway)", setup_gateway), + ("tools", "Tools", setup_tools), + ("agent", "Agent Settings", setup_agent_settings), +] + +# The returning-user menu intentionally omits standalone TTS because model setup +# already includes TTS selection and tools setup covers the rest of the provider +# configuration. Keep this list in the same order as the visible menu entries. +RETURNING_USER_MENU_SECTION_KEYS = [ + "model", + "terminal", + "gateway", + "tools", + "agent", +] + + +def run_setup_wizard(args): + """Run the interactive setup wizard. + + Supports full, quick, and section-specific setup: + hermes setup — full or quick (auto-detected) + hermes setup model — just model/provider + hermes setup tts — just text-to-speech + hermes setup terminal — just terminal backend + hermes setup gateway — just messaging platforms + hermes setup tools — just tool configuration + hermes setup agent — just agent settings + """ + from hermes_cli.config import is_managed, managed_error + if is_managed(): + managed_error("run setup wizard") + return + ensure_hermes_home() + + reset_requested = bool(getattr(args, "reset", False)) + if reset_requested: + save_config(copy.deepcopy(DEFAULT_CONFIG)) + print_success("Configuration reset to defaults.") + + config = load_config() + hermes_home = get_hermes_home() + + # Detect non-interactive environments (headless SSH, Docker, CI/CD) + non_interactive = getattr(args, 'non_interactive', False) + if not non_interactive and not is_interactive_stdin(): + non_interactive = True + + if non_interactive: + print_noninteractive_setup_guidance( + "Running in a non-interactive environment (no TTY detected)." + ) + return + + # Check if a specific section was requested + section = getattr(args, "section", None) + if section: + for key, label, func in SETUP_SECTIONS: + if key == section: + print() + print( + color( + "┌─────────────────────────────────────────────────────────┐", + Colors.MAGENTA, + ) + ) + print(color(f"│ ⚕ Hermes Setup — {label:<34s} │", Colors.MAGENTA)) + print( + color( + "└─────────────────────────────────────────────────────────┘", + Colors.MAGENTA, + ) + ) + func(config) + save_config(config) + print() + print_success(f"{label} configuration complete!") + return + + print_error(f"Unknown setup section: {section}") + print_info(f"Available sections: {', '.join(k for k, _, _ in SETUP_SECTIONS)}") + return + + # Check if this is an existing installation with a provider configured + from hermes_cli.auth import get_active_provider + + active_provider = get_active_provider() + is_existing = ( + bool(get_env_value("OPENROUTER_API_KEY")) + or bool(get_env_value("OPENAI_BASE_URL")) + or active_provider is not None + ) + + print() + print( + color( + "┌─────────────────────────────────────────────────────────┐", + Colors.MAGENTA, + ) + ) + print( + color( + "│ ⚕ Hermes Agent Setup Wizard │", Colors.MAGENTA + ) + ) + print( + color( + "├─────────────────────────────────────────────────────────┤", + Colors.MAGENTA, + ) + ) + print( + color( + "│ Let's configure your Hermes Agent installation. │", Colors.MAGENTA + ) + ) + print( + color( + "│ Press Ctrl+C at any time to exit. │", Colors.MAGENTA + ) + ) + print( + color( + "└─────────────────────────────────────────────────────────┘", + Colors.MAGENTA, + ) + ) + + migration_ran = False + + if is_existing: + # ── Returning User Menu ── + print() + print_header("Welcome Back!") + print_success("You already have Hermes configured.") + print() + + menu_choices = [ + "Quick Setup - configure missing items only", + "Full Setup - reconfigure everything", + "Model & Provider", + "Terminal Backend", + "Messaging Platforms (Gateway)", + "Tools", + "Agent Settings", + "Exit", + ] + choice = prompt_choice("What would you like to do?", menu_choices, 0) + + if choice == 0: + # Quick setup + _run_quick_setup(config, hermes_home) + return + elif choice == 1: + # Full setup — fall through to run all sections + pass + elif choice == 7: + print_info("Exiting. Run 'hermes setup' again when ready.") + return + elif 2 <= choice <= 6: + # Individual section — map by key, not by position. + # SETUP_SECTIONS includes TTS but the returning-user menu skips it, + # so positional indexing (choice - 2) would dispatch the wrong section. + section_key = RETURNING_USER_MENU_SECTION_KEYS[choice - 2] + section = next((s for s in SETUP_SECTIONS if s[0] == section_key), None) + if section: + _, label, func = section + func(config) + save_config(config) + _print_setup_summary(config, hermes_home) + return + else: + # ── First-Time Setup ── + print() + + # Offer OpenClaw migration before configuration begins + migration_ran = _offer_openclaw_migration(hermes_home) + if migration_ran: + config = load_config() + + setup_mode = prompt_choice("How would you like to set up Hermes?", [ + "Quick setup — provider, model & messaging (recommended)", + "Full setup — configure everything", + ], 0) + + if setup_mode == 0: + _run_first_time_quick_setup(config, hermes_home, is_existing) + return + + # ── Full Setup — run all sections ── + print_header("Configuration Location") + print_info(f"Config file: {get_config_path()}") + print_info(f"Secrets file: {get_env_path()}") + print_info(f"Data folder: {hermes_home}") + print_info(f"Install dir: {PROJECT_ROOT}") + print() + print_info("You can edit these files directly or use 'hermes config edit'") + + if migration_ran: + print() + print_info("Settings were imported from OpenClaw.") + print_info("Each section below will show what was imported — press Enter to keep,") + print_info("or choose to reconfigure if needed.") + + # Section 1: Model & Provider + if not (migration_ran and _skip_configured_section(config, "model", "Model & Provider")): + setup_model_provider(config) + + # Section 2: Terminal Backend + if not (migration_ran and _skip_configured_section(config, "terminal", "Terminal Backend")): + setup_terminal_backend(config) + + # Section 3: Agent Settings + if not (migration_ran and _skip_configured_section(config, "agent", "Agent Settings")): + setup_agent_settings(config) + + # Section 4: Messaging Platforms + if not (migration_ran and _skip_configured_section(config, "gateway", "Messaging Platforms")): + setup_gateway(config) + + # Section 5: Tools + if not (migration_ran and _skip_configured_section(config, "tools", "Tools")): + setup_tools(config, first_install=not is_existing) + + # Save and show summary + save_config(config) + _print_setup_summary(config, hermes_home) + + _offer_launch_chat() + + +def _resolve_hermes_chat_argv() -> Optional[list[str]]: + """Resolve argv for launching ``hermes chat`` in a fresh process.""" + hermes_bin = shutil.which("hermes") + if hermes_bin: + return [hermes_bin, "chat"] + + try: + if importlib.util.find_spec("hermes_cli") is not None: + return [sys.executable, "-m", "hermes_cli.main", "chat"] + except Exception: + pass + + return None + + +def _offer_launch_chat(): + """Prompt the user to jump straight into chat after setup.""" + print() + if not prompt_yes_no("Launch hermes chat now?", True): + return + + chat_argv = _resolve_hermes_chat_argv() + if not chat_argv: + print_info("Could not relaunch Hermes automatically. Run 'hermes chat' manually.") + return + + os.execvp(chat_argv[0], chat_argv) + + +def _run_first_time_quick_setup(config: dict, hermes_home, is_existing: bool): + """Streamlined first-time setup: provider + model only. + + Applies sensible defaults for TTS (Edge), terminal (local), agent + settings, and tools — the user can customize later via + ``hermes setup

``. + """ + # Step 1: Model & Provider (essential — skips rotation/vision/TTS) + setup_model_provider(config, quick=True) + + # Step 2: Apply defaults for everything else + _apply_default_agent_settings(config) + config.setdefault("terminal", {}).setdefault("backend", "local") + + save_config(config) + + # Step 3: Offer messaging gateway setup + print() + gateway_choice = prompt_choice( + "Connect a messaging platform? (Telegram, Discord, etc.)", + [ + "Set up messaging now (recommended)", + "Skip — set up later with 'hermes setup gateway'", + ], + 0, + ) + + if gateway_choice == 0: + setup_gateway(config) + save_config(config) + + print() + print_success("Setup complete! You're ready to go.") + print() + print_info(" Configure all settings: hermes setup") + if gateway_choice != 0: + print_info(" Connect Telegram/Discord: hermes setup gateway") + print() + + _print_setup_summary(config, hermes_home) + + _offer_launch_chat() + + +def _run_quick_setup(config: dict, hermes_home): + """Quick setup — only configure items that are missing.""" + from hermes_cli.config import ( + get_missing_env_vars, + get_missing_config_fields, + check_config_version, + ) + + print() + print_header("Quick Setup — Missing Items Only") + + # Check what's missing + missing_required = [ + v for v in get_missing_env_vars(required_only=False) if v.get("is_required") + ] + missing_optional = [ + v for v in get_missing_env_vars(required_only=False) if not v.get("is_required") + ] + missing_config = get_missing_config_fields() + current_ver, latest_ver = check_config_version() + + has_anything_missing = ( + missing_required + or missing_optional + or missing_config + or current_ver < latest_ver + ) + + if not has_anything_missing: + print_success("Everything is configured! Nothing to do.") + print() + print_info("Run 'hermes setup' and choose 'Full Setup' to reconfigure,") + print_info("or pick a specific section from the menu.") + return + + # Handle missing required env vars + if missing_required: + print() + print_info(f"{len(missing_required)} required setting(s) missing:") + for var in missing_required: + print(f" • {var['name']}") + print() + + for var in missing_required: + print() + print(color(f" {var['name']}", Colors.CYAN)) + print_info(f" {var.get('description', '')}") + if var.get("url"): + print_info(f" Get key at: {var['url']}") + + if var.get("password"): + value = prompt(f" {var.get('prompt', var['name'])}", password=True) + else: + value = prompt(f" {var.get('prompt', var['name'])}") + + if value: + save_env_value(var["name"], value) + print_success(f" Saved {var['name']}") + else: + print_warning(f" Skipped {var['name']}") + + # Split missing optional vars by category + missing_tools = [v for v in missing_optional if v.get("category") == "tool"] + missing_messaging = [ + v + for v in missing_optional + if v.get("category") == "messaging" and not v.get("advanced") + ] + + # ── Tool API keys (checklist) ── + if missing_tools: + print() + print_header("Tool API Keys") + + checklist_labels = [] + for var in missing_tools: + tools = var.get("tools", []) + tools_str = f" → {', '.join(tools[:2])}" if tools else "" + checklist_labels.append(f"{var.get('description', var['name'])}{tools_str}") + + selected_indices = prompt_checklist( + "Which tools would you like to configure?", + checklist_labels, + ) + + for idx in selected_indices: + var = missing_tools[idx] + _prompt_api_key(var) + + # ── Messaging platforms (checklist then prompt for selected) ── + if missing_messaging: + print() + print_header("Messaging Platforms") + print_info("Connect Hermes to messaging apps to chat from anywhere.") + print_info("You can configure these later with 'hermes setup gateway'.") + + # Group by platform (preserving order) + platform_order = [] + platforms = {} + for var in missing_messaging: + name = var["name"] + if "TELEGRAM" in name: + plat = "Telegram" + elif "DISCORD" in name: + plat = "Discord" + elif "SLACK" in name: + plat = "Slack" + else: + continue + if plat not in platforms: + platform_order.append(plat) + platforms.setdefault(plat, []).append(var) + + platform_labels = [ + { + "Telegram": "📱 Telegram", + "Discord": "💬 Discord", + "Slack": "💼 Slack", + }.get(p, p) + for p in platform_order + ] + + selected_indices = prompt_checklist( + "Which platforms would you like to set up?", + platform_labels, + ) + + for idx in selected_indices: + plat = platform_order[idx] + vars_list = platforms[plat] + emoji = {"Telegram": "📱", "Discord": "💬", "Slack": "💼"}.get(plat, "") + print() + print(color(f" ─── {emoji} {plat} ───", Colors.CYAN)) + print() + for var in vars_list: + print_info(f" {var.get('description', '')}") + if var.get("url"): + print_info(f" {var['url']}") + if var.get("password"): + value = prompt(f" {var.get('prompt', var['name'])}", password=True) + else: + value = prompt(f" {var.get('prompt', var['name'])}") + if value: + save_env_value(var["name"], value) + print_success(" ✓ Saved") + else: + print_warning(" Skipped") + print() + + # Handle missing config fields + if missing_config: + print() + print_info( + f"Adding {len(missing_config)} new config option(s) with defaults..." + ) + for field in missing_config: + print_success(f" Added {field['key']} = {field['default']}") + + # Update config version + config["_config_version"] = latest_ver + save_config(config) + + # Jump to summary + _print_setup_summary(config, hermes_home) diff --git a/mindcli/_vendor/hermes_cli/skills_config.py b/mindcli/_vendor/hermes_cli/skills_config.py new file mode 100644 index 0000000..741a8b8 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/skills_config.py @@ -0,0 +1,177 @@ +""" +Skills configuration for Hermes Agent. +`hermes skills` enters this module. + +Toggle individual skills or categories on/off, globally or per-platform. +Config stored in ~/.hermes/config.yaml under: + + skills: + disabled: [skill-a, skill-b] # global disabled list + platform_disabled: # per-platform overrides + telegram: [skill-c] + cli: [] +""" +from typing import List, Optional, Set + +from hermes_cli.config import load_config, save_config +from hermes_cli.colors import Colors, color +from hermes_cli.platforms import PLATFORMS as _PLATFORMS + +# Backward-compatible view: {key: label_string} so existing code that +# iterates ``PLATFORMS.items()`` or calls ``PLATFORMS.get(key)`` keeps +# working without changes to every call site. +PLATFORMS = {k: info.label for k, info in _PLATFORMS.items() if k != "api_server"} + +# ─── Config Helpers ─────────────────────────────────────────────────────────── + +def get_disabled_skills(config: dict, platform: Optional[str] = None) -> Set[str]: + """Return disabled skill names. Platform-specific list falls back to global.""" + skills_cfg = config.get("skills", {}) + global_disabled = set(skills_cfg.get("disabled", [])) + if platform is None: + return global_disabled + platform_disabled = skills_cfg.get("platform_disabled", {}).get(platform) + if platform_disabled is None: + return global_disabled + return set(platform_disabled) + + +def save_disabled_skills(config: dict, disabled: Set[str], platform: Optional[str] = None): + """Persist disabled skill names to config.""" + config.setdefault("skills", {}) + if platform is None: + config["skills"]["disabled"] = sorted(disabled) + else: + config["skills"].setdefault("platform_disabled", {}) + config["skills"]["platform_disabled"][platform] = sorted(disabled) + save_config(config) + + +# ─── Skill Discovery ───────────────────────────────────────────────────────── + +def _list_all_skills() -> List[dict]: + """Return all installed skills (ignoring disabled state).""" + try: + from tools.skills_tool import _find_all_skills + return _find_all_skills(skip_disabled=True) + except Exception: + return [] + + +def _get_categories(skills: List[dict]) -> List[str]: + """Return sorted unique category names (None -> 'uncategorized').""" + return sorted({s["category"] or "uncategorized" for s in skills}) + + +# ─── Platform Selection ────────────────────────────────────────────────────── + +def _select_platform() -> Optional[str]: + """Ask user which platform to configure, or global.""" + options = [("global", "All platforms (global default)")] + list(PLATFORMS.items()) + print() + print(color(" Configure skills for:", Colors.BOLD)) + for i, (key, label) in enumerate(options, 1): + print(f" {i}. {label}") + print() + try: + raw = input(color(" Select [1]: ", Colors.YELLOW)).strip() + except (KeyboardInterrupt, EOFError): + return None + if not raw: + return None # global + try: + idx = int(raw) - 1 + if 0 <= idx < len(options): + key = options[idx][0] + return None if key == "global" else key + except ValueError: + pass + return None + + +# ─── Category Toggle ───────────────────────────────────────────────────────── + +def _toggle_by_category(skills: List[dict], disabled: Set[str]) -> Set[str]: + """Toggle all skills in a category at once.""" + from hermes_cli.curses_ui import curses_checklist + + categories = _get_categories(skills) + cat_labels = [] + # A category is "enabled" (checked) when NOT all its skills are disabled + pre_selected = set() + for i, cat in enumerate(categories): + cat_skills = [s["name"] for s in skills if (s["category"] or "uncategorized") == cat] + cat_labels.append(f"{cat} ({len(cat_skills)} skills)") + if not all(s in disabled for s in cat_skills): + pre_selected.add(i) + + chosen = curses_checklist( + "Categories — toggle entire categories", + cat_labels, pre_selected, cancel_returns=pre_selected, + ) + + new_disabled = set(disabled) + for i, cat in enumerate(categories): + cat_skills = {s["name"] for s in skills if (s["category"] or "uncategorized") == cat} + if i in chosen: + new_disabled -= cat_skills # category enabled → remove from disabled + else: + new_disabled |= cat_skills # category disabled → add to disabled + return new_disabled + + +# ─── Entry Point ────────────────────────────────────────────────────────────── + +def skills_command(args=None): + """Entry point for `hermes skills`.""" + from hermes_cli.curses_ui import curses_checklist + + config = load_config() + skills = _list_all_skills() + + if not skills: + print(color(" No skills installed.", Colors.DIM)) + return + + # Step 1: Select platform + platform = _select_platform() + platform_label = PLATFORMS.get(platform, "All platforms") if platform else "All platforms" + + # Step 2: Select mode — individual or by category + print() + print(color(f" Configure for: {platform_label}", Colors.DIM)) + print() + print(" 1. Toggle individual skills") + print(" 2. Toggle by category") + print() + try: + mode = input(color(" Select [1]: ", Colors.YELLOW)).strip() or "1" + except (KeyboardInterrupt, EOFError): + return + + disabled = get_disabled_skills(config, platform) + + if mode == "2": + new_disabled = _toggle_by_category(skills, disabled) + else: + # Build labels and map indices → skill names + labels = [ + f"{s['name']} ({s['category'] or 'uncategorized'}) — {s['description'][:55]}" + for s in skills + ] + # "selected" = enabled (not disabled) — matches the [✓] convention + pre_selected = {i for i, s in enumerate(skills) if s["name"] not in disabled} + chosen = curses_checklist( + f"Skills for {platform_label}", + labels, pre_selected, cancel_returns=pre_selected, + ) + # Anything NOT chosen is disabled + new_disabled = {skills[i]["name"] for i in range(len(skills)) if i not in chosen} + + if new_disabled == disabled: + print(color(" No changes.", Colors.DIM)) + return + + save_disabled_skills(config, new_disabled, platform) + enabled_count = len(skills) - len(new_disabled) + print(color(f"✓ Saved: {enabled_count} enabled, {len(new_disabled)} disabled ({platform_label}).", Colors.GREEN)) diff --git a/mindcli/_vendor/hermes_cli/skills_hub.py b/mindcli/_vendor/hermes_cli/skills_hub.py new file mode 100644 index 0000000..ed92280 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/skills_hub.py @@ -0,0 +1,1238 @@ +#!/usr/bin/env python3 +""" +Skills Hub CLI — Unified interface for the Hermes Skills Hub. + +Powers both: + - `hermes skills ` (CLI argparse entry point) + - `/skills ` (slash command in the interactive chat) + +All logic lives in shared do_* functions. The CLI entry point and slash command +handler are thin wrappers that parse args and delegate. +""" + +import json +import shutil +from pathlib import Path +from typing import Any, Dict, Optional + +from rich.console import Console +from rich.panel import Panel +from rich.table import Table + +# Lazy imports to avoid circular dependencies and slow startup. +# tools.skills_hub and tools.skills_guard are imported inside functions. +from hermes_constants import display_hermes_home + +_console = Console() + + +# --------------------------------------------------------------------------- +# Shared do_* functions +# --------------------------------------------------------------------------- + +def _resolve_short_name(name: str, sources, console: Console) -> str: + """ + Resolve a short skill name (e.g. 'pptx') to a full identifier by searching + all sources. If exactly one match is found, returns its identifier. If multiple + matches exist, shows them and asks the user to use the full identifier. + Returns empty string if nothing found or ambiguous. + """ + from tools.skills_hub import unified_search + + c = console or _console + c.print(f"[dim]Resolving '{name}'...[/]") + + results = unified_search(name, sources, source_filter="all", limit=20) + + # Filter to exact name matches (case-insensitive) + exact = [r for r in results if r.name.lower() == name.lower()] + + if len(exact) == 1: + c.print(f"[dim]Resolved to: {exact[0].identifier}[/]") + return exact[0].identifier + + if len(exact) > 1: + c.print(f"\n[yellow]Multiple skills named '{name}' found:[/]") + table = Table() + table.add_column("Source", style="dim") + table.add_column("Trust", style="dim") + table.add_column("Identifier", style="bold cyan") + for r in exact: + trust_style = {"builtin": "bright_cyan", "trusted": "green", "community": "yellow"}.get(r.trust_level, "dim") + trust_label = "official" if r.source == "official" else r.trust_level + table.add_row(r.source, f"[{trust_style}]{trust_label}[/]", r.identifier) + c.print(table) + c.print("[bold]Use the full identifier to install a specific one.[/]\n") + return "" + + # No exact match — check if there are partial matches to suggest + if results: + c.print(f"[yellow]No exact match for '{name}'. Did you mean one of these?[/]") + for r in results[:5]: + c.print(f" [cyan]{r.name}[/] — {r.identifier}") + c.print() + return "" + + c.print(f"[bold red]Error:[/] No skill named '{name}' found in any source.\n") + return "" + + +def _format_extra_metadata_lines(extra: Dict[str, Any]) -> list[str]: + lines: list[str] = [] + if not extra: + return lines + + if extra.get("repo_url"): + lines.append(f"[bold]Repo:[/] {extra['repo_url']}") + if extra.get("detail_url"): + lines.append(f"[bold]Detail Page:[/] {extra['detail_url']}") + if extra.get("index_url"): + lines.append(f"[bold]Index:[/] {extra['index_url']}") + if extra.get("endpoint"): + lines.append(f"[bold]Endpoint:[/] {extra['endpoint']}") + if extra.get("install_command"): + lines.append(f"[bold]Install Command:[/] {extra['install_command']}") + if extra.get("installs") is not None: + lines.append(f"[bold]Installs:[/] {extra['installs']}") + if extra.get("weekly_installs"): + lines.append(f"[bold]Weekly Installs:[/] {extra['weekly_installs']}") + + security = extra.get("security_audits") + if isinstance(security, dict) and security: + ordered = ", ".join(f"{name}={status}" for name, status in sorted(security.items())) + lines.append(f"[bold]Security:[/] {ordered}") + + return lines + + +def _resolve_source_meta_and_bundle(identifier: str, sources): + """Resolve metadata and bundle for a specific identifier.""" + meta = None + bundle = None + matched_source = None + + for src in sources: + if meta is None: + try: + meta = src.inspect(identifier) + if meta: + matched_source = src + except Exception: + meta = None + try: + bundle = src.fetch(identifier) + except Exception: + bundle = None + if bundle: + matched_source = src + if meta is None: + try: + meta = src.inspect(identifier) + except Exception: + meta = None + break + + return meta, bundle, matched_source + + +def _derive_category_from_install_path(install_path: str) -> str: + path = Path(install_path) + parent = str(path.parent) + return "" if parent == "." else parent + + +def do_search(query: str, source: str = "all", limit: int = 10, + console: Optional[Console] = None) -> None: + """Search registries and display results as a Rich table.""" + from tools.skills_hub import GitHubAuth, create_source_router, unified_search + + c = console or _console + c.print(f"\n[bold]Searching for:[/] {query}") + + auth = GitHubAuth() + sources = create_source_router(auth) + with c.status("[bold]Searching registries..."): + results = unified_search(query, sources, source_filter=source, limit=limit) + + if not results: + c.print("[dim]No skills found matching your query.[/]\n") + return + + table = Table(title=f"Skills Hub — {len(results)} result(s)") + table.add_column("Name", style="bold cyan") + table.add_column("Description", max_width=60) + table.add_column("Source", style="dim") + table.add_column("Trust", style="dim") + table.add_column("Identifier", style="dim") + + for r in results: + trust_style = {"builtin": "bright_cyan", "trusted": "green", "community": "yellow"}.get(r.trust_level, "dim") + trust_label = "official" if r.source == "official" else r.trust_level + table.add_row( + r.name, + r.description[:60] + ("..." if len(r.description) > 60 else ""), + r.source, + f"[{trust_style}]{trust_label}[/]", + r.identifier, + ) + + c.print(table) + c.print("[dim]Use: hermes skills inspect to preview, " + "hermes skills install to install[/]\n") + + +def do_browse(page: int = 1, page_size: int = 20, source: str = "all", + console: Optional[Console] = None) -> None: + """Browse all available skills across registries, paginated. + + Official skills are always shown first, regardless of source filter. + """ + from tools.skills_hub import ( + GitHubAuth, create_source_router, parallel_search_sources, + ) + + # Clamp page_size to safe range + page_size = max(1, min(page_size, 100)) + + c = console or _console + + auth = GitHubAuth() + sources = create_source_router(auth) + + # Collect results from all (or filtered) sources in parallel. + # Per-source limits are generous — parallelism + 30s timeout cap prevents hangs. + _TRUST_RANK = {"builtin": 3, "trusted": 2, "community": 1} + _PER_SOURCE_LIMIT = { + "official": 200, "skills-sh": 200, "well-known": 50, + "github": 200, "clawhub": 500, "claude-marketplace": 100, + "lobehub": 500, + } + + with c.status("[bold]Fetching skills from registries..."): + all_results, source_counts, timed_out = parallel_search_sources( + sources, + query="", + per_source_limits=_PER_SOURCE_LIMIT, + source_filter=source, + overall_timeout=30, + ) + + if not all_results: + c.print("[dim]No skills found in the Skills Hub.[/]\n") + return + + # Deduplicate by name, preferring higher trust + seen: dict = {} + for r in all_results: + rank = _TRUST_RANK.get(r.trust_level, 0) + if r.name not in seen or rank > _TRUST_RANK.get(seen[r.name].trust_level, 0): + seen[r.name] = r + deduped = list(seen.values()) + + # Sort: official first, then by trust level (desc), then alphabetically + deduped.sort(key=lambda r: ( + -_TRUST_RANK.get(r.trust_level, 0), + r.source != "official", + r.name.lower(), + )) + + # Paginate + total = len(deduped) + total_pages = max(1, (total + page_size - 1) // page_size) + page = max(1, min(page, total_pages)) + start = (page - 1) * page_size + end = min(start + page_size, total) + page_items = deduped[start:end] + + # Count official vs other + official_count = sum(1 for r in deduped if r.source == "official") + + # Build header + source_label = f"— {source}" if source != "all" else "— all sources" + loaded_label = f"{total} skills loaded" + if timed_out: + loaded_label += f", {len(timed_out)} source(s) still loading" + c.print(f"\n[bold]Skills Hub — Browse {source_label}[/]" + f" [dim]({loaded_label}, page {page}/{total_pages})[/]") + if official_count > 0 and page == 1: + c.print(f"[bright_cyan]★ {official_count} official optional skill(s) from Nous Research[/]") + c.print() + + # Build table + table = Table(show_header=True, header_style="bold") + table.add_column("#", style="dim", width=4, justify="right") + table.add_column("Name", style="bold cyan", max_width=25) + table.add_column("Description", max_width=50) + table.add_column("Source", style="dim", width=12) + table.add_column("Trust", width=10) + + for i, r in enumerate(page_items, start=start + 1): + trust_style = {"builtin": "bright_cyan", "trusted": "green", + "community": "yellow"}.get(r.trust_level, "dim") + trust_label = "★ official" if r.source == "official" else r.trust_level + + desc = r.description[:50] + if len(r.description) > 50: + desc += "..." + + table.add_row( + str(i), + r.name, + desc, + r.source, + f"[{trust_style}]{trust_label}[/]", + ) + + c.print(table) + + # Navigation hints + nav_parts = [] + if page > 1: + nav_parts.append(f"[cyan]--page {page - 1}[/] ← prev") + if page < total_pages: + nav_parts.append(f"[cyan]--page {page + 1}[/] → next") + + if nav_parts: + c.print(f" {' | '.join(nav_parts)}") + + # Source summary + if source == "all" and source_counts: + parts = [f"{sid}: {ct}" for sid, ct in sorted(source_counts.items())] + c.print(f" [dim]Sources: {', '.join(parts)}[/]") + + if timed_out: + c.print(f" [yellow]⚡ Slow sources skipped: {', '.join(timed_out)} " + f"— run again for cached results[/]") + + c.print("[dim]Tip: 'hermes skills search ' searches deeper across all registries[/]\n") + + +def do_install(identifier: str, category: str = "", force: bool = False, + console: Optional[Console] = None, skip_confirm: bool = False, + invalidate_cache: bool = True) -> None: + """Fetch, quarantine, scan, confirm, and install a skill.""" + from tools.skills_hub import ( + GitHubAuth, create_source_router, ensure_hub_dirs, + quarantine_bundle, install_from_quarantine, HubLockFile, + ) + from tools.skills_guard import scan_skill, should_allow_install, format_scan_report + + c = console or _console + ensure_hub_dirs() + + # Resolve which source adapter handles this identifier + auth = GitHubAuth() + sources = create_source_router(auth) + + # If identifier looks like a short name (no slashes), resolve it via search + if "/" not in identifier: + identifier = _resolve_short_name(identifier, sources, c) + if not identifier: + return + + c.print(f"\n[bold]Fetching:[/] {identifier}") + + meta, bundle, _matched_source = _resolve_source_meta_and_bundle(identifier, sources) + + if not bundle: + # Check if any source hit GitHub API rate limit + rate_limited = any( + getattr(src, "is_rate_limited", False) + or getattr(getattr(src, "github", None), "is_rate_limited", False) + for src in sources + ) + c.print(f"[bold red]Error:[/] Could not fetch '{identifier}' from any source.") + if rate_limited: + c.print( + "[yellow]Hint:[/] GitHub API rate limit exhausted " + "(unauthenticated: 60 requests/hour).\n" + "Set [bold]GITHUB_TOKEN[/] in your .env or install the " + "[bold]gh[/] CLI and run [bold]gh auth login[/] " + "to raise the limit to 5,000/hr.\n" + ) + else: + c.print() + return + + # Auto-detect category for official skills (e.g. "official/autonomous-ai-agents/blackbox") + if bundle.source == "official" and not category: + id_parts = bundle.identifier.split("/") # ["official", "category", "skill"] + if len(id_parts) >= 3: + category = id_parts[1] + + # Check if already installed + lock = HubLockFile() + existing = lock.get_installed(bundle.name) + if existing: + c.print(f"[yellow]Warning:[/] '{bundle.name}' is already installed at {existing['install_path']}") + if not force: + c.print("Use --force to reinstall.\n") + return + + extra_metadata = dict(getattr(meta, "extra", {}) or {}) + extra_metadata.update(getattr(bundle, "metadata", {}) or {}) + + # Quarantine the bundle + try: + q_path = quarantine_bundle(bundle) + except ValueError as exc: + c.print(f"[bold red]Installation blocked:[/] {exc}\n") + from tools.skills_hub import append_audit_log + append_audit_log("BLOCKED", bundle.name, bundle.source, + bundle.trust_level, "invalid_path", str(exc)) + return + c.print(f"[dim]Quarantined to {q_path.relative_to(q_path.parent.parent.parent)}[/]") + + # Scan + c.print("[bold]Running security scan...[/]") + scan_source = getattr(bundle, "identifier", "") or getattr(meta, "identifier", "") or identifier + result = scan_skill(q_path, source=scan_source) + c.print(format_scan_report(result)) + + # Check install policy + allowed, reason = should_allow_install(result, force=force) + if not allowed: + c.print(f"\n[bold red]Installation blocked:[/] {reason}") + # Clean up quarantine + shutil.rmtree(q_path, ignore_errors=True) + from tools.skills_hub import append_audit_log + append_audit_log("BLOCKED", bundle.name, bundle.source, + bundle.trust_level, result.verdict, + f"{len(result.findings)}_findings") + return + + if extra_metadata: + metadata_lines = _format_extra_metadata_lines(extra_metadata) + if metadata_lines: + c.print(Panel("\n".join(metadata_lines), title="Upstream Metadata", border_style="blue")) + + # Confirm with user — show appropriate warning based on source + # skip_confirm bypasses the prompt (needed in TUI mode where input() hangs) + if not force and not skip_confirm: + c.print() + if bundle.source == "official": + c.print(Panel( + "[bold bright_cyan]This is an official optional skill maintained by Nous Research.[/]\n\n" + "It ships with hermes-agent but is not activated by default.\n" + "Installing will copy it to your skills directory where the agent can use it.\n\n" + f"Files will be at: [cyan]{display_hermes_home()}/skills/{category + '/' if category else ''}{bundle.name}/[/]", + title="Official Skill", + border_style="bright_cyan", + )) + else: + c.print(Panel( + "[bold yellow]You are installing a third-party skill at your own risk.[/]\n\n" + "External skills can contain instructions that influence agent behavior,\n" + "shell commands, and scripts. Even after automated scanning, you should\n" + "review the installed files before use.\n\n" + f"Files will be at: [cyan]{display_hermes_home()}/skills/{category + '/' if category else ''}{bundle.name}/[/]", + title="Disclaimer", + border_style="yellow", + )) + c.print(f"[bold]Install '{bundle.name}'?[/]") + try: + answer = input("Confirm [y/N]: ").strip().lower() + except (EOFError, KeyboardInterrupt): + answer = "n" + if answer not in ("y", "yes"): + c.print("[dim]Installation cancelled.[/]\n") + shutil.rmtree(q_path, ignore_errors=True) + return + + # Install + try: + install_dir = install_from_quarantine(q_path, bundle.name, category, bundle, result) + except ValueError as exc: + c.print(f"[bold red]Installation blocked:[/] {exc}\n") + shutil.rmtree(q_path, ignore_errors=True) + from tools.skills_hub import append_audit_log + append_audit_log("BLOCKED", bundle.name, bundle.source, + bundle.trust_level, "invalid_path", str(exc)) + return + from tools.skills_hub import SKILLS_DIR + c.print(f"[bold green]Installed:[/] {install_dir.relative_to(SKILLS_DIR)}") + c.print(f"[dim]Files: {', '.join(bundle.files.keys())}[/]\n") + + if invalidate_cache: + # Invalidate the skills prompt cache so the new skill appears immediately + try: + from agent.prompt_builder import clear_skills_system_prompt_cache + clear_skills_system_prompt_cache(clear_snapshot=True) + except Exception: + pass + else: + c.print("[dim]Skill will be available in your next session.[/]") + c.print("[dim]Use /reset to start a new session now, or --now to activate immediately (invalidates prompt cache).[/]\n") + + +def do_inspect(identifier: str, console: Optional[Console] = None) -> None: + """Preview a skill's SKILL.md content without installing.""" + from tools.skills_hub import GitHubAuth, create_source_router + + c = console or _console + auth = GitHubAuth() + sources = create_source_router(auth) + + if "/" not in identifier: + identifier = _resolve_short_name(identifier, sources, c) + if not identifier: + return + + meta, bundle, _matched_source = _resolve_source_meta_and_bundle(identifier, sources) + + if not meta: + c.print(f"[bold red]Error:[/] Could not find '{identifier}' in any source.\n") + return + + c.print() + trust_style = {"builtin": "bright_cyan", "trusted": "green", "community": "yellow"}.get(meta.trust_level, "dim") + trust_label = "official" if meta.source == "official" else meta.trust_level + + info_lines = [ + f"[bold]Name:[/] {meta.name}", + f"[bold]Description:[/] {meta.description}", + f"[bold]Source:[/] {meta.source}", + f"[bold]Trust:[/] [{trust_style}]{trust_label}[/]", + f"[bold]Identifier:[/] {meta.identifier}", + ] + if meta.tags: + info_lines.append(f"[bold]Tags:[/] {', '.join(meta.tags)}") + info_lines.extend(_format_extra_metadata_lines(meta.extra)) + + c.print(Panel("\n".join(info_lines), title=f"Skill: {meta.name}")) + + if bundle and "SKILL.md" in bundle.files: + content = bundle.files["SKILL.md"] + if isinstance(content, bytes): + content = content.decode("utf-8", errors="replace") + # Show first 50 lines as preview + lines = content.split("\n") + preview = "\n".join(lines[:50]) + if len(lines) > 50: + preview += f"\n\n... ({len(lines) - 50} more lines)" + c.print(Panel(preview, title="SKILL.md Preview", subtitle="hermes skills install to install")) + + c.print() + + +def do_list(source_filter: str = "all", console: Optional[Console] = None) -> None: + """List installed skills, distinguishing hub, builtin, and local skills.""" + from tools.skills_hub import HubLockFile, ensure_hub_dirs + from tools.skills_sync import _read_manifest + from tools.skills_tool import _find_all_skills + + c = console or _console + ensure_hub_dirs() + lock = HubLockFile() + hub_installed = {e["name"]: e for e in lock.list_installed()} + builtin_names = set(_read_manifest()) + + all_skills = _find_all_skills() + + table = Table(title="Installed Skills") + table.add_column("Name", style="bold cyan") + table.add_column("Category", style="dim") + table.add_column("Source", style="dim") + table.add_column("Trust", style="dim") + + hub_count = 0 + builtin_count = 0 + local_count = 0 + + for skill in sorted(all_skills, key=lambda s: (s.get("category") or "", s["name"])): + name = skill["name"] + category = skill.get("category", "") + hub_entry = hub_installed.get(name) + + if hub_entry: + source_type = "hub" + source_display = hub_entry.get("source", "hub") + trust = hub_entry.get("trust_level", "community") + hub_count += 1 + elif name in builtin_names: + source_type = "builtin" + source_display = "builtin" + trust = "builtin" + builtin_count += 1 + else: + source_type = "local" + source_display = "local" + trust = "local" + local_count += 1 + + if source_filter != "all" and source_filter != source_type: + continue + + trust_style = {"builtin": "bright_cyan", "trusted": "green", "community": "yellow", "local": "dim"}.get(trust, "dim") + trust_label = "official" if source_display == "official" else trust + table.add_row(name, category, source_display, f"[{trust_style}]{trust_label}[/]") + + c.print(table) + c.print( + f"[dim]{hub_count} hub-installed, {builtin_count} builtin, {local_count} local[/]\n" + ) + + +def do_check(name: Optional[str] = None, console: Optional[Console] = None) -> None: + """Check hub-installed skills for upstream updates.""" + from tools.skills_hub import check_for_skill_updates + + c = console or _console + results = check_for_skill_updates(name=name) + if not results: + c.print("[dim]No hub-installed skills to check.[/]\n") + return + + table = Table(title="Skill Updates") + table.add_column("Name", style="bold cyan") + table.add_column("Source", style="dim") + table.add_column("Status", style="dim") + + for entry in results: + table.add_row(entry.get("name", ""), entry.get("source", ""), entry.get("status", "")) + + c.print(table) + update_count = sum(1 for entry in results if entry.get("status") == "update_available") + c.print(f"[dim]{update_count} update(s) available across {len(results)} checked skill(s)[/]\n") + + +def do_update(name: Optional[str] = None, console: Optional[Console] = None) -> None: + """Update hub-installed skills with upstream changes.""" + from tools.skills_hub import HubLockFile, check_for_skill_updates + + c = console or _console + lock = HubLockFile() + updates = [entry for entry in check_for_skill_updates(name=name) if entry.get("status") == "update_available"] + if not updates: + c.print("[dim]No updates available.[/]\n") + return + + for entry in updates: + installed = lock.get_installed(entry["name"]) + category = _derive_category_from_install_path(installed.get("install_path", "")) if installed else "" + c.print(f"[bold]Updating:[/] {entry['name']}") + do_install(entry["identifier"], category=category, force=True, console=c) + + c.print(f"[bold green]Updated {len(updates)} skill(s).[/]\n") + + +def do_audit(name: Optional[str] = None, console: Optional[Console] = None) -> None: + """Re-run security scan on installed hub skills.""" + from tools.skills_hub import HubLockFile, SKILLS_DIR + from tools.skills_guard import scan_skill, format_scan_report + + c = console or _console + lock = HubLockFile() + installed = lock.list_installed() + + if not installed: + c.print("[dim]No hub-installed skills to audit.[/]\n") + return + + targets = installed + if name: + targets = [e for e in installed if e["name"] == name] + if not targets: + c.print(f"[bold red]Error:[/] '{name}' is not a hub-installed skill.\n") + return + + c.print(f"\n[bold]Auditing {len(targets)} skill(s)...[/]\n") + + for entry in targets: + skill_path = SKILLS_DIR / entry["install_path"] + if not skill_path.exists(): + c.print(f"[yellow]Warning:[/] {entry['name']} — path missing: {entry['install_path']}") + continue + + result = scan_skill(skill_path, source=entry.get("identifier", entry["source"])) + c.print(format_scan_report(result)) + c.print() + + +def do_uninstall(name: str, console: Optional[Console] = None, + skip_confirm: bool = False, + invalidate_cache: bool = True) -> None: + """Remove a hub-installed skill with confirmation.""" + from tools.skills_hub import uninstall_skill + + c = console or _console + + # skip_confirm bypasses the prompt (needed in TUI mode where input() hangs) + if not skip_confirm: + c.print(f"\n[bold]Uninstall '{name}'?[/]") + try: + answer = input("Confirm [y/N]: ").strip().lower() + except (EOFError, KeyboardInterrupt): + answer = "n" + if answer not in ("y", "yes"): + c.print("[dim]Cancelled.[/]\n") + return + + success, msg = uninstall_skill(name) + if success: + c.print(f"[bold green]{msg}[/]\n") + if invalidate_cache: + try: + from agent.prompt_builder import clear_skills_system_prompt_cache + clear_skills_system_prompt_cache(clear_snapshot=True) + except Exception: + pass + else: + c.print("[dim]Change will take effect in your next session.[/]") + c.print("[dim]Use /reset to start a new session now, or --now to apply immediately (invalidates prompt cache).[/]\n") + else: + c.print(f"[bold red]Error:[/] {msg}\n") + + +def do_tap(action: str, repo: str = "", console: Optional[Console] = None) -> None: + """Manage taps (custom GitHub repo sources).""" + from tools.skills_hub import TapsManager + + c = console or _console + mgr = TapsManager() + + if action == "list": + taps = mgr.list_taps() + if not taps: + c.print("[dim]No custom taps configured. Using default sources only.[/]\n") + return + table = Table(title="Configured Taps") + table.add_column("Repo", style="bold cyan") + table.add_column("Path", style="dim") + for t in taps: + label = t.get("repo") or t.get("name") or t.get("path", "unknown") + table.add_row(label, t.get("path", "skills/")) + c.print(table) + c.print() + + elif action == "add": + if not repo: + c.print("[bold red]Error:[/] Repo required. Usage: hermes skills tap add owner/repo\n") + return + if mgr.add(repo): + c.print(f"[bold green]Added tap:[/] {repo}\n") + else: + c.print(f"[yellow]Tap already exists:[/] {repo}\n") + + elif action == "remove": + if not repo: + c.print("[bold red]Error:[/] Repo required. Usage: hermes skills tap remove owner/repo\n") + return + if mgr.remove(repo): + c.print(f"[bold green]Removed tap:[/] {repo}\n") + else: + c.print(f"[bold red]Error:[/] Tap not found: {repo}\n") + + else: + c.print(f"[bold red]Unknown tap action:[/] {action}. Use: list, add, remove\n") + + +def do_publish(skill_path: str, target: str = "github", repo: str = "", + console: Optional[Console] = None) -> None: + """Publish a local skill to a registry (GitHub PR or ClawHub submission).""" + from tools.skills_hub import GitHubAuth, SKILLS_DIR + from tools.skills_guard import scan_skill, format_scan_report + + c = console or _console + path = Path(skill_path) + + # Resolve relative to skills dir if not absolute + if not path.is_absolute(): + path = SKILLS_DIR / path + if not path.exists() or not (path / "SKILL.md").exists(): + c.print(f"[bold red]Error:[/] No SKILL.md found at {path}\n") + return + + # Validate the skill + import yaml + skill_md = (path / "SKILL.md").read_text(encoding="utf-8") + fm = {} + if skill_md.startswith("---"): + import re + match = re.search(r'\n---\s*\n', skill_md[3:]) + if match: + try: + fm = yaml.safe_load(skill_md[3:match.start() + 3]) or {} + except yaml.YAMLError: + pass + + name = fm.get("name", path.name) + description = fm.get("description", "") + if not description: + c.print("[bold red]Error:[/] SKILL.md must have a 'description' in frontmatter.\n") + return + + # Self-scan before publishing + c.print(f"[bold]Scanning '{name}' before publish...[/]") + result = scan_skill(path, source="self") + c.print(format_scan_report(result)) + if result.verdict == "dangerous": + c.print("[bold red]Cannot publish a skill with DANGEROUS verdict.[/]\n") + return + + if target == "github": + if not repo: + c.print("[bold red]Error:[/] --repo required for GitHub publish.\n" + "Usage: hermes skills publish --to github --repo owner/repo\n") + return + + auth = GitHubAuth() + if not auth.is_authenticated(): + c.print("[bold red]Error:[/] GitHub authentication required.\n" + f"Set GITHUB_TOKEN in {display_hermes_home()}/.env or run 'gh auth login'.\n") + return + + c.print(f"[bold]Publishing '{name}' to {repo}...[/]") + success, msg = _github_publish(path, name, repo, auth) + if success: + c.print(f"[bold green]{msg}[/]\n") + else: + c.print(f"[bold red]Error:[/] {msg}\n") + + elif target == "clawhub": + c.print("[yellow]ClawHub publishing is not yet supported. " + "Submit manually at https://clawhub.ai/submit[/]\n") + else: + c.print(f"[bold red]Unknown target:[/] {target}. Use 'github' or 'clawhub'.\n") + + +def _github_publish(skill_path: Path, skill_name: str, target_repo: str, + auth) -> tuple: + """Create a PR to a GitHub repo with the skill. Returns (success, message).""" + import httpx + + headers = auth.get_headers() + + # 1. Fork the repo + try: + resp = httpx.post( + f"https://api.github.com/repos/{target_repo}/forks", + headers=headers, timeout=30, + ) + if resp.status_code in (200, 202): + fork = resp.json() + fork_repo = fork["full_name"] + elif resp.status_code == 403: + return False, "GitHub token lacks permission to fork repos" + else: + return False, f"Failed to fork {target_repo}: {resp.status_code}" + except httpx.HTTPError as e: + return False, f"Network error forking repo: {e}" + + # 2. Get default branch + try: + resp = httpx.get( + f"https://api.github.com/repos/{target_repo}", + headers=headers, timeout=15, + ) + default_branch = resp.json().get("default_branch", "main") + except Exception: + default_branch = "main" + + # 3. Get the base tree SHA + try: + resp = httpx.get( + f"https://api.github.com/repos/{fork_repo}/git/refs/heads/{default_branch}", + headers=headers, timeout=15, + ) + base_sha = resp.json()["object"]["sha"] + except Exception as e: + return False, f"Failed to get base branch: {e}" + + # 4. Create a new branch + branch_name = f"add-skill-{skill_name}" + try: + httpx.post( + f"https://api.github.com/repos/{fork_repo}/git/refs", + headers=headers, timeout=15, + json={"ref": f"refs/heads/{branch_name}", "sha": base_sha}, + ) + except Exception as e: + return False, f"Failed to create branch: {e}" + + # 5. Upload skill files + for f in skill_path.rglob("*"): + if not f.is_file(): + continue + rel = str(f.relative_to(skill_path)) + upload_path = f"skills/{skill_name}/{rel}" + try: + import base64 + content_b64 = base64.b64encode(f.read_bytes()).decode() + httpx.put( + f"https://api.github.com/repos/{fork_repo}/contents/{upload_path}", + headers=headers, timeout=15, + json={ + "message": f"Add {skill_name} skill: {rel}", + "content": content_b64, + "branch": branch_name, + }, + ) + except Exception as e: + return False, f"Failed to upload {rel}: {e}" + + # 6. Create PR + try: + resp = httpx.post( + f"https://api.github.com/repos/{target_repo}/pulls", + headers=headers, timeout=15, + json={ + "title": f"Add skill: {skill_name}", + "body": f"Submitting the `{skill_name}` skill via Hermes Skills Hub.\n\n" + f"This skill was scanned by the Hermes Skills Guard before submission.", + "head": f"{fork_repo.split('/')[0]}:{branch_name}", + "base": default_branch, + }, + ) + if resp.status_code == 201: + pr_url = resp.json().get("html_url", "") + return True, f"PR created: {pr_url}" + else: + return False, f"Failed to create PR: {resp.status_code} {resp.text[:200]}" + except httpx.HTTPError as e: + return False, f"Network error creating PR: {e}" + + +def do_snapshot_export(output_path: str, console: Optional[Console] = None) -> None: + """Export current hub skill configuration to a portable JSON file.""" + from tools.skills_hub import HubLockFile, TapsManager + + c = console or _console + lock = HubLockFile() + taps = TapsManager() + + installed = lock.list_installed() + tap_list = taps.list_taps() + + snapshot = { + "hermes_version": "0.1.0", + "exported_at": __import__("datetime").datetime.now( + __import__("datetime").timezone.utc + ).isoformat(), + "skills": [ + { + "name": entry["name"], + "source": entry.get("source", ""), + "identifier": entry.get("identifier", ""), + "category": str(Path(entry.get("install_path", "")).parent) + if "/" in entry.get("install_path", "") else "", + } + for entry in installed + ], + "taps": tap_list, + } + + payload = json.dumps(snapshot, indent=2, ensure_ascii=False) + "\n" + if output_path == "-": + import sys + sys.stdout.write(payload) + else: + out = Path(output_path) + out.write_text(payload) + c.print(f"[bold green]Snapshot exported:[/] {out}") + c.print(f"[dim]{len(installed)} skill(s), {len(tap_list)} tap(s)[/]\n") + + +def do_snapshot_import(input_path: str, force: bool = False, + console: Optional[Console] = None) -> None: + """Re-install skills from a snapshot file.""" + from tools.skills_hub import TapsManager + + c = console or _console + inp = Path(input_path) + if not inp.exists(): + c.print(f"[bold red]Error:[/] File not found: {inp}\n") + return + + try: + snapshot = json.loads(inp.read_text()) + except json.JSONDecodeError: + c.print(f"[bold red]Error:[/] Invalid JSON in {inp}\n") + return + + # Restore taps first + taps = snapshot.get("taps", []) + if taps: + mgr = TapsManager() + for tap in taps: + repo = tap.get("repo", "") + if repo: + mgr.add(repo, tap.get("path", "skills/")) + c.print(f"[dim]Restored {len(taps)} tap(s)[/]") + + # Install skills + skills = snapshot.get("skills", []) + if not skills: + c.print("[dim]No skills in snapshot to install.[/]\n") + return + + c.print(f"[bold]Importing {len(skills)} skill(s) from snapshot...[/]\n") + for entry in skills: + identifier = entry.get("identifier", "") + category = entry.get("category", "") + if not identifier: + c.print(f"[yellow]Skipping entry with no identifier: {entry.get('name', '?')}[/]") + continue + + c.print(f"[bold]--- {entry.get('name', identifier)} ---[/]") + do_install(identifier, category=category, force=force, console=c) + + c.print("[bold green]Snapshot import complete.[/]\n") + + +# --------------------------------------------------------------------------- +# CLI argparse entry point +# --------------------------------------------------------------------------- + +def skills_command(args) -> None: + """Router for `hermes skills ` — called from hermes_cli/main.py.""" + action = getattr(args, "skills_action", None) + + if action == "browse": + do_browse(page=args.page, page_size=args.size, source=args.source) + elif action == "search": + do_search(args.query, source=args.source, limit=args.limit) + elif action == "install": + do_install(args.identifier, category=args.category, force=args.force, + skip_confirm=getattr(args, "yes", False)) + elif action == "inspect": + do_inspect(args.identifier) + elif action == "list": + do_list(source_filter=args.source) + elif action == "check": + do_check(name=getattr(args, "name", None)) + elif action == "update": + do_update(name=getattr(args, "name", None)) + elif action == "audit": + do_audit(name=getattr(args, "name", None)) + elif action == "uninstall": + do_uninstall(args.name) + elif action == "publish": + do_publish( + args.skill_path, + target=getattr(args, "to", "github"), + repo=getattr(args, "repo", ""), + ) + elif action == "snapshot": + snap_action = getattr(args, "snapshot_action", None) + if snap_action == "export": + do_snapshot_export(args.output) + elif snap_action == "import": + do_snapshot_import(args.input, force=getattr(args, "force", False)) + else: + _console.print("Usage: hermes skills snapshot [export|import]\n") + elif action == "tap": + tap_action = getattr(args, "tap_action", None) + repo = getattr(args, "repo", "") or getattr(args, "name", "") + if not tap_action: + _console.print("Usage: hermes skills tap [list|add|remove]\n") + return + do_tap(tap_action, repo=repo) + else: + _console.print("Usage: hermes skills [browse|search|install|inspect|list|check|update|audit|uninstall|publish|snapshot|tap]\n") + _console.print("Run 'hermes skills --help' for details.\n") + + +# --------------------------------------------------------------------------- +# Slash command entry point (/skills in chat) +# --------------------------------------------------------------------------- + +def handle_skills_slash(cmd: str, console: Optional[Console] = None) -> None: + """ + Parse and dispatch `/skills [args]` from the chat interface. + + Examples: + /skills search kubernetes + /skills install openai/skills/skill-creator + /skills install openai/skills/skill-creator --force + /skills inspect openai/skills/skill-creator + /skills list + /skills list --source hub + /skills check + /skills update + /skills audit + /skills audit my-skill + /skills uninstall my-skill + /skills tap list + /skills tap add owner/repo + /skills tap remove owner/repo + """ + c = console or _console + parts = cmd.strip().split() + + # Strip the leading "/skills" if present + if parts and parts[0].lower() == "/skills": + parts = parts[1:] + + if not parts: + _print_skills_help(c) + return + + action = parts[0].lower() + args = parts[1:] + + if action == "browse": + page = 1 + page_size = 20 + source = "all" + i = 0 + while i < len(args): + if args[i] == "--page" and i + 1 < len(args): + try: + page = int(args[i + 1]) + except ValueError: + pass + i += 2 + elif args[i] == "--size" and i + 1 < len(args): + try: + page_size = int(args[i + 1]) + except ValueError: + pass + i += 2 + elif args[i] == "--source" and i + 1 < len(args): + source = args[i + 1] + i += 2 + else: + i += 1 + do_browse(page=page, page_size=page_size, source=source, console=c) + + elif action == "search": + if not args: + c.print("[bold red]Usage:[/] /skills search [--source skills-sh|well-known|github|official] [--limit N]\n") + return + source = "all" + limit = 10 + query_parts = [] + i = 0 + while i < len(args): + if args[i] == "--source" and i + 1 < len(args): + source = args[i + 1] + i += 2 + elif args[i] == "--limit" and i + 1 < len(args): + try: + limit = int(args[i + 1]) + except ValueError: + pass + i += 2 + else: + query_parts.append(args[i]) + i += 1 + do_search(" ".join(query_parts), source=source, limit=limit, console=c) + + elif action == "install": + if not args: + c.print("[bold red]Usage:[/] /skills install [--category ] [--force] [--now]\n") + return + identifier = args[0] + category = "" + # Slash commands run inside prompt_toolkit where input() hangs. + # Always skip confirmation — the user typing the command is implicit consent. + skip_confirm = True + force = "--force" in args + # --now invalidates prompt cache immediately (costs more money). + # Default: defer to next session to preserve cache. + invalidate_cache = "--now" in args + for i, a in enumerate(args): + if a == "--category" and i + 1 < len(args): + category = args[i + 1] + do_install(identifier, category=category, force=force, + skip_confirm=skip_confirm, invalidate_cache=invalidate_cache, + console=c) + + elif action == "inspect": + if not args: + c.print("[bold red]Usage:[/] /skills inspect \n") + return + do_inspect(args[0], console=c) + + elif action == "list": + source_filter = "all" + if "--source" in args: + idx = args.index("--source") + if idx + 1 < len(args): + source_filter = args[idx + 1] + do_list(source_filter=source_filter, console=c) + + elif action == "check": + name = args[0] if args else None + do_check(name=name, console=c) + + elif action == "update": + name = args[0] if args else None + do_update(name=name, console=c) + + elif action == "audit": + name = args[0] if args else None + do_audit(name=name, console=c) + + elif action == "uninstall": + if not args: + c.print("[bold red]Usage:[/] /skills uninstall [--now]\n") + return + # Slash commands run inside prompt_toolkit where input() hangs. + skip_confirm = True + invalidate_cache = "--now" in args + do_uninstall(args[0], console=c, skip_confirm=skip_confirm, + invalidate_cache=invalidate_cache) + + elif action == "publish": + if not args: + c.print("[bold red]Usage:[/] /skills publish [--to github] [--repo owner/repo]\n") + return + skill_path = args[0] + target = "github" + repo = "" + for i, a in enumerate(args): + if a == "--to" and i + 1 < len(args): + target = args[i + 1] + if a == "--repo" and i + 1 < len(args): + repo = args[i + 1] + do_publish(skill_path, target=target, repo=repo, console=c) + + elif action == "snapshot": + if not args: + c.print("[bold red]Usage:[/] /skills snapshot export | /skills snapshot import \n") + return + snap_action = args[0] + if snap_action == "export" and len(args) > 1: + do_snapshot_export(args[1], console=c) + elif snap_action == "import" and len(args) > 1: + force = "--force" in args + do_snapshot_import(args[1], force=force, console=c) + else: + c.print("[bold red]Usage:[/] /skills snapshot export | /skills snapshot import \n") + + elif action == "tap": + if not args: + do_tap("list", console=c) + return + tap_action = args[0] + repo = args[1] if len(args) > 1 else "" + do_tap(tap_action, repo=repo, console=c) + + elif action in ("help", "--help", "-h"): + _print_skills_help(c) + + else: + c.print(f"[bold red]Unknown action:[/] {action}") + _print_skills_help(c) + + +def _print_skills_help(console: Console) -> None: + """Print help for the /skills slash command.""" + console.print(Panel( + "[bold]Skills Hub Commands:[/]\n\n" + " [cyan]browse[/] [--source official] Browse all available skills (paginated)\n" + " [cyan]search[/] Search registries for skills\n" + " [cyan]install[/] Install a skill (with security scan)\n" + " [cyan]inspect[/] Preview a skill without installing\n" + " [cyan]list[/] [--source hub|builtin|local] List installed skills\n" + " [cyan]check[/] [name] Check hub skills for upstream updates\n" + " [cyan]update[/] [name] Update hub skills with upstream changes\n" + " [cyan]audit[/] [name] Re-scan hub skills for security\n" + " [cyan]uninstall[/] Remove a hub-installed skill\n" + " [cyan]publish[/] --repo Publish a skill to GitHub via PR\n" + " [cyan]snapshot[/] export|import Export/import skill configurations\n" + " [cyan]tap[/] list|add|remove Manage skill sources\n", + title="/skills", + )) diff --git a/mindcli/_vendor/hermes_cli/skin_engine.py b/mindcli/_vendor/hermes_cli/skin_engine.py new file mode 100644 index 0000000..b992ada --- /dev/null +++ b/mindcli/_vendor/hermes_cli/skin_engine.py @@ -0,0 +1,816 @@ +"""Hermes CLI skin/theme engine. + +A data-driven skin system that lets users customize the CLI's visual appearance. +Skins are defined as YAML files in ~/.hermes/skins/ or as built-in presets. +No code changes are needed to add a new skin. + +SKIN YAML SCHEMA +================ + +All fields are optional. Missing values inherit from the ``default`` skin. + +.. code-block:: yaml + + # Required: skin identity + name: mytheme # Unique skin name (lowercase, hyphens ok) + description: Short description # Shown in /skin listing + + # Colors: hex values for Rich markup (banner, UI, response box) + colors: + banner_border: "#CD7F32" # Panel border color + banner_title: "#FFD700" # Panel title text color + banner_accent: "#FFBF00" # Section headers (Available Tools, etc.) + banner_dim: "#B8860B" # Dim/muted text (separators, labels) + banner_text: "#FFF8DC" # Body text (tool names, skill names) + ui_accent: "#FFBF00" # General UI accent + ui_label: "#4dd0e1" # UI labels + ui_ok: "#4caf50" # Success indicators + ui_error: "#ef5350" # Error indicators + ui_warn: "#ffa726" # Warning indicators + prompt: "#FFF8DC" # Prompt text color + input_rule: "#CD7F32" # Input area horizontal rule + response_border: "#FFD700" # Response box border (ANSI) + session_label: "#DAA520" # Session label color + session_border: "#8B8682" # Session ID dim color + status_bar_bg: "#1a1a2e" # TUI status/usage bar background + voice_status_bg: "#1a1a2e" # TUI voice status background + completion_menu_bg: "#1a1a2e" # Completion menu background + completion_menu_current_bg: "#333355" # Active completion row background + completion_menu_meta_bg: "#1a1a2e" # Completion meta column background + completion_menu_meta_current_bg: "#333355" # Active completion meta background + + # Spinner: customize the animated spinner during API calls + spinner: + waiting_faces: # Faces shown while waiting for API + - "(⚔)" + - "(⛨)" + thinking_faces: # Faces shown during reasoning + - "(⌁)" + - "(<>)" + thinking_verbs: # Verbs for spinner messages + - "forging" + - "plotting" + wings: # Optional left/right spinner decorations + - ["⟪⚔", "⚔⟫"] # Each entry is [left, right] pair + - ["⟪▲", "▲⟫"] + + # Branding: text strings used throughout the CLI + branding: + agent_name: "Hermes Agent" # Banner title, status display + welcome: "Welcome message" # Shown at CLI startup + goodbye: "Goodbye! ⚕" # Shown on exit + response_label: " ⚕ Hermes " # Response box header label + prompt_symbol: "❯ " # Input prompt symbol + help_header: "(^_^)? Commands" # /help header text + + # Tool prefix: character for tool output lines (default: ┊) + tool_prefix: "┊" + + # Tool emojis: override the default emoji for any tool (used in spinners & progress) + tool_emojis: + terminal: "⚔" # Override terminal tool emoji + web_search: "🔮" # Override web_search tool emoji + # Any tool not listed here uses its registry default + +USAGE +===== + +.. code-block:: python + + from hermes_cli.skin_engine import get_active_skin, list_skins, set_active_skin + + skin = get_active_skin() + print(skin.colors["banner_title"]) # "#FFD700" + print(skin.get_branding("agent_name")) # "Hermes Agent" + + set_active_skin("ares") # Switch to built-in ares skin + set_active_skin("mytheme") # Switch to user skin from ~/.hermes/skins/ + +BUILT-IN SKINS +============== + +- ``default`` — Classic Hermes gold/kawaii (the current look) +- ``ares`` — Crimson/bronze war-god theme with custom spinner wings +- ``mono`` — Clean grayscale monochrome +- ``slate`` — Cool blue developer-focused theme +- ``daylight`` — Light background theme with dark text and blue accents +- ``warm-lightmode`` — Warm brown/gold text for light terminal backgrounds + +USER SKINS +========== + +Drop a YAML file in ``~/.hermes/skins/.yaml`` following the schema above. +Activate with ``/skin `` in the CLI or ``display.skin: `` in config.yaml. +""" + +import logging +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any, Dict, List, Optional, Tuple + +from hermes_constants import get_hermes_home + +logger = logging.getLogger(__name__) + + +# ============================================================================= +# Skin data structure +# ============================================================================= + +@dataclass +class SkinConfig: + """Complete skin configuration.""" + name: str + description: str = "" + colors: Dict[str, str] = field(default_factory=dict) + spinner: Dict[str, Any] = field(default_factory=dict) + branding: Dict[str, str] = field(default_factory=dict) + tool_prefix: str = "┊" + tool_emojis: Dict[str, str] = field(default_factory=dict) # per-tool emoji overrides + banner_logo: str = "" # Rich-markup ASCII art logo (replaces HERMES_AGENT_LOGO) + banner_hero: str = "" # Rich-markup hero art (replaces HERMES_CADUCEUS) + + def get_color(self, key: str, fallback: str = "") -> str: + """Get a color value with fallback.""" + return self.colors.get(key, fallback) + + def get_spinner_wings(self) -> List[Tuple[str, str]]: + """Get spinner wing pairs, or empty list if none.""" + raw = self.spinner.get("wings", []) + result = [] + for pair in raw: + if isinstance(pair, (list, tuple)) and len(pair) == 2: + result.append((str(pair[0]), str(pair[1]))) + return result + + def get_branding(self, key: str, fallback: str = "") -> str: + """Get a branding value with fallback.""" + return self.branding.get(key, fallback) + + +# ============================================================================= +# Built-in skin definitions +# ============================================================================= + +_BUILTIN_SKINS: Dict[str, Dict[str, Any]] = { + "default": { + "name": "default", + "description": "Classic Hermes — gold and kawaii", + "colors": { + "banner_border": "#CD7F32", + "banner_title": "#FFD700", + "banner_accent": "#FFBF00", + "banner_dim": "#B8860B", + "banner_text": "#FFF8DC", + "ui_accent": "#FFBF00", + "ui_label": "#4dd0e1", + "ui_ok": "#4caf50", + "ui_error": "#ef5350", + "ui_warn": "#ffa726", + "prompt": "#FFF8DC", + "input_rule": "#CD7F32", + "response_border": "#FFD700", + "session_label": "#DAA520", + "session_border": "#8B8682", + }, + "spinner": { + # Empty = use hardcoded defaults in display.py + }, + "branding": { + "agent_name": "Hermes Agent", + "welcome": "Welcome to Hermes Agent! Type your message or /help for commands.", + "goodbye": "Goodbye! ⚕", + "response_label": " ⚕ Hermes ", + "prompt_symbol": "❯ ", + "help_header": "(^_^)? Available Commands", + }, + "tool_prefix": "┊", + }, + "ares": { + "name": "ares", + "description": "War-god theme — crimson and bronze", + "colors": { + "banner_border": "#9F1C1C", + "banner_title": "#C7A96B", + "banner_accent": "#DD4A3A", + "banner_dim": "#6B1717", + "banner_text": "#F1E6CF", + "ui_accent": "#DD4A3A", + "ui_label": "#C7A96B", + "ui_ok": "#4caf50", + "ui_error": "#ef5350", + "ui_warn": "#ffa726", + "prompt": "#F1E6CF", + "input_rule": "#9F1C1C", + "response_border": "#C7A96B", + "session_label": "#C7A96B", + "session_border": "#6E584B", + }, + "spinner": { + "waiting_faces": ["(⚔)", "(⛨)", "(▲)", "(<>)", "(/)"], + "thinking_faces": ["(⚔)", "(⛨)", "(▲)", "(⌁)", "(<>)"], + "thinking_verbs": [ + "forging", "marching", "sizing the field", "holding the line", + "hammering plans", "tempering steel", "plotting impact", "raising the shield", + ], + "wings": [ + ["⟪⚔", "⚔⟫"], + ["⟪▲", "▲⟫"], + ["⟪╸", "╺⟫"], + ["⟪⛨", "⛨⟫"], + ], + }, + "branding": { + "agent_name": "Ares Agent", + "welcome": "Welcome to Ares Agent! Type your message or /help for commands.", + "goodbye": "Farewell, warrior! ⚔", + "response_label": " ⚔ Ares ", + "prompt_symbol": "⚔ ❯ ", + "help_header": "(⚔) Available Commands", + }, + "tool_prefix": "╎", + "banner_logo": """[bold #A3261F] █████╗ ██████╗ ███████╗███████╗ █████╗ ██████╗ ███████╗███╗ ██╗████████╗[/] +[bold #B73122]██╔══██╗██╔══██╗██╔════╝██╔════╝ ██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝[/] +[#C93C24]███████║██████╔╝█████╗ ███████╗█████╗███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║[/] +[#D84A28]██╔══██║██╔══██╗██╔══╝ ╚════██║╚════╝██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║[/] +[#E15A2D]██║ ██║██║ ██║███████╗███████║ ██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║[/] +[#EB6C32]╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚══════╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝[/]""", + "banner_hero": """[#9F1C1C]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣤⣤⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#9F1C1C]⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣴⣿⠟⠻⣿⣦⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#C7A96B]⠀⠀⠀⠀⠀⠀⠀⣠⣾⡿⠋⠀⠀⠀⠙⢿⣷⣄⠀⠀⠀⠀⠀⠀⠀[/] +[#C7A96B]⠀⠀⠀⠀⠀⢀⣾⡿⠋⠀⠀⢠⡄⠀⠀⠙⢿⣷⡀⠀⠀⠀⠀⠀[/] +[#DD4A3A]⠀⠀⠀⠀⣰⣿⠟⠀⠀⠀⣰⣿⣿⣆⠀⠀⠀⠻⣿⣆⠀⠀⠀⠀[/] +[#DD4A3A]⠀⠀⠀⢰⣿⠏⠀⠀⢀⣾⡿⠉⢿⣷⡀⠀⠀⠹⣿⡆⠀⠀⠀[/] +[#9F1C1C]⠀⠀⠀⣿⡟⠀⠀⣠⣿⠟⠀⠀⠀⠻⣿⣄⠀⠀⢻⣿⠀⠀⠀[/] +[#9F1C1C]⠀⠀⠀⣿⡇⠀⠀⠙⠋⠀⠀⚔⠀⠀⠙⠋⠀⠀⢸⣿⠀⠀⠀[/] +[#6B1717]⠀⠀⠀⢿⣧⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣼⡿⠀⠀⠀[/] +[#6B1717]⠀⠀⠀⠘⢿⣷⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣾⡿⠃⠀⠀⠀[/] +[#C7A96B]⠀⠀⠀⠀⠈⠻⣿⣷⣦⣤⣀⣀⣤⣤⣶⣿⠿⠋⠀⠀⠀⠀[/] +[#C7A96B]⠀⠀⠀⠀⠀⠀⠀⠉⠛⠿⠿⠿⠿⠛⠉⠀⠀⠀⠀⠀⠀⠀[/] +[#DD4A3A]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⚔⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[dim #6B1717]⠀⠀⠀⠀⠀⠀⠀⠀war god online⠀⠀⠀⠀⠀⠀⠀⠀[/]""", + }, + "mono": { + "name": "mono", + "description": "Monochrome — clean grayscale", + "colors": { + "banner_border": "#555555", + "banner_title": "#e6edf3", + "banner_accent": "#aaaaaa", + "banner_dim": "#444444", + "banner_text": "#c9d1d9", + "ui_accent": "#aaaaaa", + "ui_label": "#888888", + "ui_ok": "#888888", + "ui_error": "#cccccc", + "ui_warn": "#999999", + "prompt": "#c9d1d9", + "input_rule": "#444444", + "response_border": "#aaaaaa", + "session_label": "#888888", + "session_border": "#555555", + }, + "spinner": {}, + "branding": { + "agent_name": "Hermes Agent", + "welcome": "Welcome to Hermes Agent! Type your message or /help for commands.", + "goodbye": "Goodbye! ⚕", + "response_label": " ⚕ Hermes ", + "prompt_symbol": "❯ ", + "help_header": "[?] Available Commands", + }, + "tool_prefix": "┊", + }, + "slate": { + "name": "slate", + "description": "Cool blue — developer-focused", + "colors": { + "banner_border": "#4169e1", + "banner_title": "#7eb8f6", + "banner_accent": "#8EA8FF", + "banner_dim": "#4b5563", + "banner_text": "#c9d1d9", + "ui_accent": "#7eb8f6", + "ui_label": "#8EA8FF", + "ui_ok": "#63D0A6", + "ui_error": "#F7A072", + "ui_warn": "#e6a855", + "prompt": "#c9d1d9", + "input_rule": "#4169e1", + "response_border": "#7eb8f6", + "session_label": "#7eb8f6", + "session_border": "#4b5563", + }, + "spinner": {}, + "branding": { + "agent_name": "Hermes Agent", + "welcome": "Welcome to Hermes Agent! Type your message or /help for commands.", + "goodbye": "Goodbye! ⚕", + "response_label": " ⚕ Hermes ", + "prompt_symbol": "❯ ", + "help_header": "(^_^)? Available Commands", + }, + "tool_prefix": "┊", + }, + "daylight": { + "name": "daylight", + "description": "Light theme for bright terminals with dark text and cool blue accents", + "colors": { + "banner_border": "#2563EB", + "banner_title": "#0F172A", + "banner_accent": "#1D4ED8", + "banner_dim": "#475569", + "banner_text": "#111827", + "ui_accent": "#2563EB", + "ui_label": "#0F766E", + "ui_ok": "#15803D", + "ui_error": "#B91C1C", + "ui_warn": "#B45309", + "prompt": "#111827", + "input_rule": "#93C5FD", + "response_border": "#2563EB", + "session_label": "#1D4ED8", + "session_border": "#64748B", + "status_bar_bg": "#E5EDF8", + "voice_status_bg": "#E5EDF8", + "completion_menu_bg": "#F8FAFC", + "completion_menu_current_bg": "#DBEAFE", + "completion_menu_meta_bg": "#EEF2FF", + "completion_menu_meta_current_bg": "#BFDBFE", + }, + "spinner": {}, + "branding": { + "agent_name": "Hermes Agent", + "welcome": "Welcome to Hermes Agent! Type your message or /help for commands.", + "goodbye": "Goodbye! ⚕", + "response_label": " ⚕ Hermes ", + "prompt_symbol": "❯ ", + "help_header": "[?] Available Commands", + }, + "tool_prefix": "│", + }, + "warm-lightmode": { + "name": "warm-lightmode", + "description": "Warm light mode — dark brown/gold text for light terminal backgrounds", + "colors": { + "banner_border": "#8B6914", + "banner_title": "#5C3D11", + "banner_accent": "#8B4513", + "banner_dim": "#8B7355", + "banner_text": "#2C1810", + "ui_accent": "#8B4513", + "ui_label": "#5C3D11", + "ui_ok": "#2E7D32", + "ui_error": "#C62828", + "ui_warn": "#E65100", + "prompt": "#2C1810", + "input_rule": "#8B6914", + "response_border": "#8B6914", + "session_label": "#5C3D11", + "session_border": "#A0845C", + "status_bar_bg": "#F5F0E8", + "voice_status_bg": "#F5F0E8", + "completion_menu_bg": "#F5EFE0", + "completion_menu_current_bg": "#E8DCC8", + "completion_menu_meta_bg": "#F0E8D8", + "completion_menu_meta_current_bg": "#DFCFB0", + }, + "spinner": {}, + "branding": { + "agent_name": "Hermes Agent", + "welcome": "Welcome to Hermes Agent! Type your message or /help for commands.", + "goodbye": "Goodbye! \u2695", + "response_label": " \u2695 Hermes ", + "prompt_symbol": "\u276f ", + "help_header": "(^_^)? Available Commands", + }, + "tool_prefix": "\u250a", + }, + "poseidon": { + "name": "poseidon", + "description": "Ocean-god theme — deep blue and seafoam", + "colors": { + "banner_border": "#2A6FB9", + "banner_title": "#A9DFFF", + "banner_accent": "#5DB8F5", + "banner_dim": "#153C73", + "banner_text": "#EAF7FF", + "ui_accent": "#5DB8F5", + "ui_label": "#A9DFFF", + "ui_ok": "#4caf50", + "ui_error": "#ef5350", + "ui_warn": "#ffa726", + "prompt": "#EAF7FF", + "input_rule": "#2A6FB9", + "response_border": "#5DB8F5", + "session_label": "#A9DFFF", + "session_border": "#496884", + }, + "spinner": { + "waiting_faces": ["(≈)", "(Ψ)", "(∿)", "(◌)", "(◠)"], + "thinking_faces": ["(Ψ)", "(∿)", "(≈)", "(⌁)", "(◌)"], + "thinking_verbs": [ + "charting currents", "sounding the depth", "reading foam lines", + "steering the trident", "tracking undertow", "plotting sea lanes", + "calling the swell", "measuring pressure", + ], + "wings": [ + ["⟪≈", "≈⟫"], + ["⟪Ψ", "Ψ⟫"], + ["⟪∿", "∿⟫"], + ["⟪◌", "◌⟫"], + ], + }, + "branding": { + "agent_name": "Poseidon Agent", + "welcome": "Welcome to Poseidon Agent! Type your message or /help for commands.", + "goodbye": "Fair winds! Ψ", + "response_label": " Ψ Poseidon ", + "prompt_symbol": "Ψ ❯ ", + "help_header": "(Ψ) Available Commands", + }, + "tool_prefix": "│", + "banner_logo": """[bold #B8E8FF]██████╗ ██████╗ ███████╗███████╗██╗██████╗ ██████╗ ███╗ ██╗ █████╗ ██████╗ ███████╗███╗ ██╗████████╗[/] +[bold #97D6FF]██╔══██╗██╔═══██╗██╔════╝██╔════╝██║██╔══██╗██╔═══██╗████╗ ██║ ██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝[/] +[#75C1F6]██████╔╝██║ ██║███████╗█████╗ ██║██║ ██║██║ ██║██╔██╗ ██║█████╗███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║[/] +[#4FA2E0]██╔═══╝ ██║ ██║╚════██║██╔══╝ ██║██║ ██║██║ ██║██║╚██╗██║╚════╝██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║[/] +[#2E7CC7]██║ ╚██████╔╝███████║███████╗██║██████╔╝╚██████╔╝██║ ╚████║ ██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║[/] +[#1B4F95]╚═╝ ╚═════╝ ╚══════╝╚══════╝╚═╝╚═════╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝[/]""", + "banner_hero": """[#2A6FB9]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#5DB8F5]⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣾⣿⣷⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#5DB8F5]⠀⠀⠀⠀⠀⠀⠀⢠⣿⠏⠀Ψ⠀⠹⣿⡄⠀⠀⠀⠀⠀⠀⠀[/] +[#A9DFFF]⠀⠀⠀⠀⠀⠀⠀⣿⡟⠀⠀⠀⠀⠀⢻⣿⠀⠀⠀⠀⠀⠀⠀[/] +[#A9DFFF]⠀⠀⠀≈≈≈≈≈⣿⡇⠀⠀⠀⠀⠀⢸⣿≈≈≈≈≈⠀⠀⠀[/] +[#5DB8F5]⠀⠀⠀⠀⠀⠀⠀⣿⡇⠀⠀⠀⠀⠀⢸⣿⠀⠀⠀⠀⠀⠀⠀[/] +[#2A6FB9]⠀⠀⠀⠀⠀⠀⠀⢿⣧⠀⠀⠀⠀⠀⣼⡿⠀⠀⠀⠀⠀⠀⠀[/] +[#2A6FB9]⠀⠀⠀⠀⠀⠀⠀⠘⢿⣷⣄⣀⣠⣾⡿⠃⠀⠀⠀⠀⠀⠀⠀[/] +[#153C73]⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⣿⣿⡿⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#153C73]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#5DB8F5]⠀⠀⠀⠀⠀≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈⠀⠀⠀⠀⠀[/] +[#A9DFFF]⠀⠀⠀⠀⠀⠀≈≈≈≈≈≈≈≈≈≈≈≈≈⠀⠀⠀⠀⠀⠀[/] +[dim #153C73]⠀⠀⠀⠀⠀⠀⠀deep waters hold⠀⠀⠀⠀⠀⠀⠀[/]""", + }, + "sisyphus": { + "name": "sisyphus", + "description": "Sisyphean theme — austere grayscale with persistence", + "colors": { + "banner_border": "#B7B7B7", + "banner_title": "#F5F5F5", + "banner_accent": "#E7E7E7", + "banner_dim": "#4A4A4A", + "banner_text": "#D3D3D3", + "ui_accent": "#E7E7E7", + "ui_label": "#D3D3D3", + "ui_ok": "#919191", + "ui_error": "#E7E7E7", + "ui_warn": "#B7B7B7", + "prompt": "#F5F5F5", + "input_rule": "#656565", + "response_border": "#B7B7B7", + "session_label": "#919191", + "session_border": "#656565", + }, + "spinner": { + "waiting_faces": ["(◉)", "(◌)", "(◬)", "(⬤)", "(::)"], + "thinking_faces": ["(◉)", "(◬)", "(◌)", "(○)", "(●)"], + "thinking_verbs": [ + "finding traction", "measuring the grade", "resetting the boulder", + "counting the ascent", "testing leverage", "setting the shoulder", + "pushing uphill", "enduring the loop", + ], + "wings": [ + ["⟪◉", "◉⟫"], + ["⟪◬", "◬⟫"], + ["⟪◌", "◌⟫"], + ["⟪⬤", "⬤⟫"], + ], + }, + "branding": { + "agent_name": "Sisyphus Agent", + "welcome": "Welcome to Sisyphus Agent! Type your message or /help for commands.", + "goodbye": "The boulder waits. ◉", + "response_label": " ◉ Sisyphus ", + "prompt_symbol": "◉ ❯ ", + "help_header": "(◉) Available Commands", + }, + "tool_prefix": "│", + "banner_logo": """[bold #F5F5F5]███████╗██╗███████╗██╗ ██╗██████╗ ██╗ ██╗██╗ ██╗███████╗ █████╗ ██████╗ ███████╗███╗ ██╗████████╗[/] +[bold #E7E7E7]██╔════╝██║██╔════╝╚██╗ ██╔╝██╔══██╗██║ ██║██║ ██║██╔════╝ ██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝[/] +[#D7D7D7]███████╗██║███████╗ ╚████╔╝ ██████╔╝███████║██║ ██║███████╗█████╗███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║[/] +[#BFBFBF]╚════██║██║╚════██║ ╚██╔╝ ██╔═══╝ ██╔══██║██║ ██║╚════██║╚════╝██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║[/] +[#8F8F8F]███████║██║███████║ ██║ ██║ ██║ ██║╚██████╔╝███████║ ██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║[/] +[#626262]╚══════╝╚═╝╚══════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝[/]""", + "banner_hero": """[#B7B7B7]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#D3D3D3]⠀⠀⠀⠀⠀⠀⠀⣠⣾⣿⣿⣿⣿⣷⣄⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#E7E7E7]⠀⠀⠀⠀⠀⠀⣾⣿⣿⣿⣿⣿⣿⣿⣷⠀⠀⠀⠀⠀⠀⠀[/] +[#F5F5F5]⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀[/] +[#E7E7E7]⠀⠀⠀⠀⠀⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀[/] +[#D3D3D3]⠀⠀⠀⠀⠀⠀⠘⢿⣿⣿⣿⣿⣿⡿⠃⠀⠀⠀⠀⠀⠀⠀[/] +[#B7B7B7]⠀⠀⠀⠀⠀⠀⠀⠀⠙⠿⣿⠿⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#919191]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#656565]⠀⠀⠀⠀⠀⠀⠀⠀⠀⣰⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#656565]⠀⠀⠀⠀⠀⠀⠀⠀⣰⣿⣿⣆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#4A4A4A]⠀⠀⠀⠀⠀⠀⠀⣰⣿⣿⣿⣿⣆⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#4A4A4A]⠀⠀⠀⠀⠀⣀⣴⣿⣿⣿⣿⣿⣿⣦⣀⠀⠀⠀⠀⠀⠀[/] +[#656565]⠀⠀⠀━━━━━━━━━━━━━━━━━━━━━━━⠀⠀⠀[/] +[dim #4A4A4A]⠀⠀⠀⠀⠀⠀⠀⠀⠀the boulder⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]""", + }, + "charizard": { + "name": "charizard", + "description": "Volcanic theme — burnt orange and ember", + "colors": { + "banner_border": "#C75B1D", + "banner_title": "#FFD39A", + "banner_accent": "#F29C38", + "banner_dim": "#7A3511", + "banner_text": "#FFF0D4", + "ui_accent": "#F29C38", + "ui_label": "#FFD39A", + "ui_ok": "#4caf50", + "ui_error": "#ef5350", + "ui_warn": "#ffa726", + "prompt": "#FFF0D4", + "input_rule": "#C75B1D", + "response_border": "#F29C38", + "session_label": "#FFD39A", + "session_border": "#6C4724", + }, + "spinner": { + "waiting_faces": ["(✦)", "(▲)", "(◇)", "(<>)", "(🔥)"], + "thinking_faces": ["(✦)", "(▲)", "(◇)", "(⌁)", "(🔥)"], + "thinking_verbs": [ + "banking into the draft", "measuring burn", "reading the updraft", + "tracking ember fall", "setting wing angle", "holding the flame core", + "plotting a hot landing", "coiling for lift", + ], + "wings": [ + ["⟪✦", "✦⟫"], + ["⟪▲", "▲⟫"], + ["⟪◌", "◌⟫"], + ["⟪◇", "◇⟫"], + ], + }, + "branding": { + "agent_name": "Charizard Agent", + "welcome": "Welcome to Charizard Agent! Type your message or /help for commands.", + "goodbye": "Flame out! ✦", + "response_label": " ✦ Charizard ", + "prompt_symbol": "✦ ❯ ", + "help_header": "(✦) Available Commands", + }, + "tool_prefix": "│", + "banner_logo": """[bold #FFF0D4] ██████╗██╗ ██╗ █████╗ ██████╗ ██╗███████╗ █████╗ ██████╗ ██████╗ █████╗ ██████╗ ███████╗███╗ ██╗████████╗[/] +[bold #FFD39A]██╔════╝██║ ██║██╔══██╗██╔══██╗██║╚══███╔╝██╔══██╗██╔══██╗██╔══██╗ ██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝[/] +[#F29C38]██║ ███████║███████║██████╔╝██║ ███╔╝ ███████║██████╔╝██║ ██║█████╗███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║[/] +[#E2832B]██║ ██╔══██║██╔══██║██╔══██╗██║ ███╔╝ ██╔══██║██╔══██╗██║ ██║╚════╝██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║[/] +[#C75B1D]╚██████╗██║ ██║██║ ██║██║ ██║██║███████╗██║ ██║██║ ██║██████╔╝ ██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║[/] +[#7A3511] ╚═════╝╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝╚═╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝[/]""", + "banner_hero": """[#FFD39A]⠀⠀⠀⠀⠀⠀⠀⠀⣀⣤⠶⠶⠶⣤⣀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#F29C38]⠀⠀⠀⠀⠀⠀⣴⠟⠁⠀⠀⠀⠀⠈⠻⣦⠀⠀⠀⠀⠀⠀[/] +[#F29C38]⠀⠀⠀⠀⠀⣼⠏⠀⠀⠀✦⠀⠀⠀⠀⠹⣧⠀⠀⠀⠀⠀[/] +[#E2832B]⠀⠀⠀⠀⢰⡟⠀⠀⣀⣤⣤⣤⣀⠀⠀⠀⢻⡆⠀⠀⠀⠀[/] +[#E2832B]⠀⠀⣠⡾⠛⠁⣠⣾⠟⠉⠀⠉⠻⣷⣄⠀⠈⠛⢷⣄⠀⠀[/] +[#C75B1D]⠀⣼⠟⠀⢀⣾⠟⠁⠀⠀⠀⠀⠀⠈⠻⣷⡀⠀⠻⣧⠀[/] +[#C75B1D]⢸⡟⠀⠀⣿⡟⠀⠀⠀🔥⠀⠀⠀⠀⢻⣿⠀⠀⢻⡇[/] +[#7A3511]⠀⠻⣦⡀⠘⢿⣧⡀⠀⠀⠀⠀⠀⢀⣼⡿⠃⢀⣴⠟⠀[/] +[#7A3511]⠀⠀⠈⠻⣦⣀⠙⢿⣷⣤⣤⣤⣾⡿⠋⣀⣴⠟⠁⠀⠀[/] +[#C75B1D]⠀⠀⠀⠀⠈⠙⠛⠶⠤⠭⠭⠤⠶⠛⠋⠁⠀⠀⠀⠀[/] +[#F29C38]⠀⠀⠀⠀⠀⠀⠀⠀⣰⡿⢿⣆⠀⠀⠀⠀⠀⠀⠀⠀⠀[/] +[#F29C38]⠀⠀⠀⠀⠀⠀⠀⣼⡟⠀⠀⢻⣧⠀⠀⠀⠀⠀⠀⠀⠀[/] +[dim #7A3511]⠀⠀⠀⠀⠀⠀⠀tail flame lit⠀⠀⠀⠀⠀⠀⠀⠀[/]""", + }, +} + + +# ============================================================================= +# Skin loading and management +# ============================================================================= + +_active_skin: Optional[SkinConfig] = None +_active_skin_name: str = "default" + + +def _skins_dir() -> Path: + """User skins directory.""" + return get_hermes_home() / "skins" + + +def _load_skin_from_yaml(path: Path) -> Optional[Dict[str, Any]]: + """Load a skin definition from a YAML file.""" + try: + import yaml + with open(path, "r", encoding="utf-8") as f: + data = yaml.safe_load(f) + if isinstance(data, dict) and "name" in data: + return data + except Exception as e: + logger.debug("Failed to load skin from %s: %s", path, e) + return None + + +def _build_skin_config(data: Dict[str, Any]) -> SkinConfig: + """Build a SkinConfig from a raw dict (built-in or loaded from YAML).""" + # Start with default values as base for missing keys + default = _BUILTIN_SKINS["default"] + colors = dict(default.get("colors", {})) + colors.update(data.get("colors", {})) + spinner = dict(default.get("spinner", {})) + spinner.update(data.get("spinner", {})) + branding = dict(default.get("branding", {})) + branding.update(data.get("branding", {})) + + return SkinConfig( + name=data.get("name", "unknown"), + description=data.get("description", ""), + colors=colors, + spinner=spinner, + branding=branding, + tool_prefix=data.get("tool_prefix", default.get("tool_prefix", "┊")), + tool_emojis=data.get("tool_emojis", {}), + banner_logo=data.get("banner_logo", ""), + banner_hero=data.get("banner_hero", ""), + ) + + +def list_skins() -> List[Dict[str, str]]: + """List all available skins (built-in + user-installed). + + Returns list of {"name": ..., "description": ..., "source": "builtin"|"user"}. + """ + result = [] + for name, data in _BUILTIN_SKINS.items(): + result.append({ + "name": name, + "description": data.get("description", ""), + "source": "builtin", + }) + + skins_path = _skins_dir() + if skins_path.is_dir(): + for f in sorted(skins_path.glob("*.yaml")): + data = _load_skin_from_yaml(f) + if data: + skin_name = data.get("name", f.stem) + # Skip if it shadows a built-in + if any(s["name"] == skin_name for s in result): + continue + result.append({ + "name": skin_name, + "description": data.get("description", ""), + "source": "user", + }) + + return result + + +def load_skin(name: str) -> SkinConfig: + """Load a skin by name. Checks user skins first, then built-in.""" + # Check user skins directory + skins_path = _skins_dir() + user_file = skins_path / f"{name}.yaml" + if user_file.is_file(): + data = _load_skin_from_yaml(user_file) + if data: + return _build_skin_config(data) + + # Check built-in skins + if name in _BUILTIN_SKINS: + return _build_skin_config(_BUILTIN_SKINS[name]) + + # Fallback to default + logger.warning("Skin '%s' not found, using default", name) + return _build_skin_config(_BUILTIN_SKINS["default"]) + + +def get_active_skin() -> SkinConfig: + """Get the currently active skin config (cached).""" + global _active_skin + if _active_skin is None: + _active_skin = load_skin(_active_skin_name) + return _active_skin + + +def set_active_skin(name: str) -> SkinConfig: + """Switch the active skin. Returns the new SkinConfig.""" + global _active_skin, _active_skin_name + _active_skin_name = name + _active_skin = load_skin(name) + return _active_skin + + +def get_active_skin_name() -> str: + """Get the name of the currently active skin.""" + return _active_skin_name + + +def init_skin_from_config(config: dict) -> None: + """Initialize the active skin from CLI config at startup. + + Call this once during CLI init with the loaded config dict. + """ + display = config.get("display", {}) + skin_name = display.get("skin", "default") + if isinstance(skin_name, str) and skin_name.strip(): + set_active_skin(skin_name.strip()) + else: + set_active_skin("default") + + +# ============================================================================= +# Convenience helpers for CLI modules +# ============================================================================= + + +def get_active_prompt_symbol(fallback: str = "❯ ") -> str: + """Get the interactive prompt symbol from the active skin.""" + try: + return get_active_skin().get_branding("prompt_symbol", fallback) + except Exception: + return fallback + + + +def get_active_help_header(fallback: str = "(^_^)? Available Commands") -> str: + """Get the /help header from the active skin.""" + try: + return get_active_skin().get_branding("help_header", fallback) + except Exception: + return fallback + + + +def get_active_goodbye(fallback: str = "Goodbye! ⚕") -> str: + """Get the goodbye line from the active skin.""" + try: + return get_active_skin().get_branding("goodbye", fallback) + except Exception: + return fallback + + + +def get_prompt_toolkit_style_overrides() -> Dict[str, str]: + """Return prompt_toolkit style overrides derived from the active skin. + + These are layered on top of the CLI's base TUI style so /skin can refresh + the live prompt_toolkit UI immediately without rebuilding the app. + """ + try: + skin = get_active_skin() + except Exception: + return {} + + prompt = skin.get_color("prompt", "#FFF8DC") + input_rule = skin.get_color("input_rule", "#CD7F32") + title = skin.get_color("banner_title", "#FFD700") + text = skin.get_color("banner_text", prompt) + dim = skin.get_color("banner_dim", "#555555") + label = skin.get_color("ui_label", title) + warn = skin.get_color("ui_warn", "#FF8C00") + error = skin.get_color("ui_error", "#FF6B6B") + status_bg = skin.get_color("status_bar_bg", "#1a1a2e") + voice_bg = skin.get_color("voice_status_bg", status_bg) + menu_bg = skin.get_color("completion_menu_bg", "#1a1a2e") + menu_current_bg = skin.get_color("completion_menu_current_bg", "#333355") + menu_meta_bg = skin.get_color("completion_menu_meta_bg", menu_bg) + menu_meta_current_bg = skin.get_color("completion_menu_meta_current_bg", menu_current_bg) + + return { + "input-area": prompt, + "placeholder": f"{dim} italic", + "prompt": prompt, + "prompt-working": f"{dim} italic", + "hint": f"{dim} italic", + "status-bar": f"bg:{status_bg} {text}", + "status-bar-strong": f"bg:{status_bg} {title} bold", + "status-bar-dim": f"bg:{status_bg} {dim}", + "status-bar-good": f"bg:{status_bg} {skin.get_color('ui_ok', '#8FBC8F')} bold", + "status-bar-warn": f"bg:{status_bg} {warn} bold", + "status-bar-bad": f"bg:{status_bg} {skin.get_color('banner_accent', warn)} bold", + "status-bar-critical": f"bg:{status_bg} {error} bold", + "input-rule": input_rule, + "image-badge": f"{label} bold", + "completion-menu": f"bg:{menu_bg} {text}", + "completion-menu.completion": f"bg:{menu_bg} {text}", + "completion-menu.completion.current": f"bg:{menu_current_bg} {title}", + "completion-menu.meta.completion": f"bg:{menu_meta_bg} {dim}", + "completion-menu.meta.completion.current": f"bg:{menu_meta_current_bg} {label}", + "clarify-border": input_rule, + "clarify-title": f"{title} bold", + "clarify-question": f"{text} bold", + "clarify-choice": dim, + "clarify-selected": f"{title} bold", + "clarify-active-other": f"{title} italic", + "clarify-countdown": input_rule, + "sudo-prompt": f"{error} bold", + "sudo-border": input_rule, + "sudo-title": f"{error} bold", + "sudo-text": text, + "approval-border": input_rule, + "approval-title": f"{warn} bold", + "approval-desc": f"{text} bold", + "approval-cmd": f"{dim} italic", + "approval-choice": dim, + "approval-selected": f"{title} bold", + "voice-status": f"bg:{voice_bg} {label}", + "voice-status-recording": f"bg:{voice_bg} {error} bold", + } diff --git a/mindcli/_vendor/hermes_cli/status.py b/mindcli/_vendor/hermes_cli/status.py new file mode 100644 index 0000000..5ec93f2 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/status.py @@ -0,0 +1,476 @@ +""" +Status command for hermes CLI. + +Shows the status of all Hermes Agent components. +""" + +import os +import sys +import subprocess +from pathlib import Path + +PROJECT_ROOT = Path(__file__).parent.parent.resolve() + +from hermes_cli.auth import AuthError, resolve_provider +from hermes_cli.colors import Colors, color +from hermes_cli.config import get_env_path, get_env_value, get_hermes_home, load_config +from hermes_cli.models import provider_label +from hermes_cli.nous_subscription import get_nous_subscription_features +from hermes_cli.runtime_provider import resolve_requested_provider +from hermes_constants import OPENROUTER_MODELS_URL +from tools.tool_backend_helpers import managed_nous_tools_enabled + +def check_mark(ok: bool) -> str: + if ok: + return color("✓", Colors.GREEN) + return color("✗", Colors.RED) + +def redact_key(key: str) -> str: + """Redact an API key for display.""" + if not key: + return "(not set)" + if len(key) < 12: + return "***" + return key[:4] + "..." + key[-4:] + + +def _format_iso_timestamp(value) -> str: + """Format ISO timestamps for status output, converting to local timezone.""" + if not value or not isinstance(value, str): + return "(unknown)" + from datetime import datetime, timezone + text = value.strip() + if not text: + return "(unknown)" + if text.endswith("Z"): + text = text[:-1] + "+00:00" + try: + parsed = datetime.fromisoformat(text) + if parsed.tzinfo is None: + parsed = parsed.replace(tzinfo=timezone.utc) + except Exception: + return value + return parsed.astimezone().strftime("%Y-%m-%d %H:%M:%S %Z") + + +def _configured_model_label(config: dict) -> str: + """Return the configured default model from config.yaml.""" + model_cfg = config.get("model") + if isinstance(model_cfg, dict): + model = (model_cfg.get("default") or model_cfg.get("name") or "").strip() + elif isinstance(model_cfg, str): + model = model_cfg.strip() + else: + model = "" + return model or "(not set)" + + +def _effective_provider_label() -> str: + """Return the provider label matching current CLI runtime resolution.""" + requested = resolve_requested_provider() + try: + effective = resolve_provider(requested) + except AuthError: + effective = requested or "auto" + + if effective == "openrouter" and get_env_value("OPENAI_BASE_URL"): + effective = "custom" + + return provider_label(effective) + + +from hermes_constants import is_termux as _is_termux + + +def show_status(args): + """Show status of all Hermes Agent components.""" + show_all = getattr(args, 'all', False) + deep = getattr(args, 'deep', False) + + print() + print(color("┌─────────────────────────────────────────────────────────┐", Colors.CYAN)) + print(color("│ ⚕ Hermes Agent Status │", Colors.CYAN)) + print(color("└─────────────────────────────────────────────────────────┘", Colors.CYAN)) + + # ========================================================================= + # Environment + # ========================================================================= + print() + print(color("◆ Environment", Colors.CYAN, Colors.BOLD)) + print(f" Project: {PROJECT_ROOT}") + print(f" Python: {sys.version.split()[0]}") + + env_path = get_env_path() + print(f" .env file: {check_mark(env_path.exists())} {'exists' if env_path.exists() else 'not found'}") + + try: + config = load_config() + except Exception: + config = {} + + print(f" Model: {_configured_model_label(config)}") + print(f" Provider: {_effective_provider_label()}") + + # ========================================================================= + # API Keys + # ========================================================================= + print() + print(color("◆ API Keys", Colors.CYAN, Colors.BOLD)) + + keys = { + "OpenRouter": "OPENROUTER_API_KEY", + "OpenAI": "OPENAI_API_KEY", + "Z.AI/GLM": "GLM_API_KEY", + "Kimi": "KIMI_API_KEY", + "MiniMax": "MINIMAX_API_KEY", + "MiniMax-CN": "MINIMAX_CN_API_KEY", + "Firecrawl": "FIRECRAWL_API_KEY", + "Tavily": "TAVILY_API_KEY", + "Browser Use": "BROWSER_USE_API_KEY", # Optional — local browser works without this + "Browserbase": "BROWSERBASE_API_KEY", # Optional — direct credentials only + "FAL": "FAL_KEY", + "Tinker": "TINKER_API_KEY", + "WandB": "WANDB_API_KEY", + "ElevenLabs": "ELEVENLABS_API_KEY", + "GitHub": "GITHUB_TOKEN", + } + + for name, env_var in keys.items(): + value = get_env_value(env_var) or "" + has_key = bool(value) + display = redact_key(value) if not show_all else value + print(f" {name:<12} {check_mark(has_key)} {display}") + + from hermes_cli.auth import get_anthropic_key + anthropic_value = get_anthropic_key() + anthropic_display = redact_key(anthropic_value) if not show_all else anthropic_value + print(f" {'Anthropic':<12} {check_mark(bool(anthropic_value))} {anthropic_display}") + + # ========================================================================= + # Auth Providers (OAuth) + # ========================================================================= + print() + print(color("◆ Auth Providers", Colors.CYAN, Colors.BOLD)) + + try: + from hermes_cli.auth import get_nous_auth_status, get_codex_auth_status, get_qwen_auth_status + nous_status = get_nous_auth_status() + codex_status = get_codex_auth_status() + qwen_status = get_qwen_auth_status() + except Exception: + nous_status = {} + codex_status = {} + qwen_status = {} + + nous_logged_in = bool(nous_status.get("logged_in")) + print( + f" {'Nous Portal':<12} {check_mark(nous_logged_in)} " + f"{'logged in' if nous_logged_in else 'not logged in (run: hermes model)'}" + ) + if nous_logged_in: + portal_url = nous_status.get("portal_base_url") or "(unknown)" + access_exp = _format_iso_timestamp(nous_status.get("access_expires_at")) + key_exp = _format_iso_timestamp(nous_status.get("agent_key_expires_at")) + refresh_label = "yes" if nous_status.get("has_refresh_token") else "no" + print(f" Portal URL: {portal_url}") + print(f" Access exp: {access_exp}") + print(f" Key exp: {key_exp}") + print(f" Refresh: {refresh_label}") + + codex_logged_in = bool(codex_status.get("logged_in")) + print( + f" {'OpenAI Codex':<12} {check_mark(codex_logged_in)} " + f"{'logged in' if codex_logged_in else 'not logged in (run: hermes model)'}" + ) + codex_auth_file = codex_status.get("auth_store") + if codex_auth_file: + print(f" Auth file: {codex_auth_file}") + codex_last_refresh = _format_iso_timestamp(codex_status.get("last_refresh")) + if codex_status.get("last_refresh"): + print(f" Refreshed: {codex_last_refresh}") + if codex_status.get("error") and not codex_logged_in: + print(f" Error: {codex_status.get('error')}") + + qwen_logged_in = bool(qwen_status.get("logged_in")) + print( + f" {'Qwen OAuth':<12} {check_mark(qwen_logged_in)} " + f"{'logged in' if qwen_logged_in else 'not logged in (run: qwen auth qwen-oauth)'}" + ) + qwen_auth_file = qwen_status.get("auth_file") + if qwen_auth_file: + print(f" Auth file: {qwen_auth_file}") + qwen_exp = qwen_status.get("expires_at_ms") + if qwen_exp: + from datetime import datetime, timezone + print(f" Access exp: {datetime.fromtimestamp(int(qwen_exp) / 1000, tz=timezone.utc).isoformat()}") + if qwen_status.get("error") and not qwen_logged_in: + print(f" Error: {qwen_status.get('error')}") + + # ========================================================================= + # Nous Subscription Features + # ========================================================================= + if managed_nous_tools_enabled(): + features = get_nous_subscription_features(config) + print() + print(color("◆ Nous Subscription Features", Colors.CYAN, Colors.BOLD)) + if not features.nous_auth_present: + print(" Nous Portal ✗ not logged in") + else: + print(" Nous Portal ✓ managed tools available") + for feature in features.items(): + if feature.managed_by_nous: + state = "active via Nous subscription" + elif feature.active: + current = feature.current_provider or "configured provider" + state = f"active via {current}" + elif feature.included_by_default and features.nous_auth_present: + state = "included by subscription, not currently selected" + elif feature.key == "modal" and features.nous_auth_present: + state = "available via subscription (optional)" + else: + state = "not configured" + print(f" {feature.label:<15} {check_mark(feature.available or feature.active or feature.managed_by_nous)} {state}") + + # ========================================================================= + # API-Key Providers + # ========================================================================= + print() + print(color("◆ API-Key Providers", Colors.CYAN, Colors.BOLD)) + + apikey_providers = { + "Z.AI / GLM": ("GLM_API_KEY", "ZAI_API_KEY", "Z_AI_API_KEY"), + "Kimi / Moonshot": ("KIMI_API_KEY",), + "MiniMax": ("MINIMAX_API_KEY",), + "MiniMax (China)": ("MINIMAX_CN_API_KEY",), + } + for pname, env_vars in apikey_providers.items(): + key_val = "" + for ev in env_vars: + key_val = get_env_value(ev) or "" + if key_val: + break + configured = bool(key_val) + label = "configured" if configured else "not configured (run: hermes model)" + print(f" {pname:<16} {check_mark(configured)} {label}") + + # ========================================================================= + # Terminal Configuration + # ========================================================================= + print() + print(color("◆ Terminal Backend", Colors.CYAN, Colors.BOLD)) + + terminal_env = os.getenv("TERMINAL_ENV", "") + if not terminal_env: + # Fall back to config file value when env var isn't set + # (hermes status doesn't go through cli.py's config loading) + try: + _cfg = load_config() + terminal_env = _cfg.get("terminal", {}).get("backend", "local") + except Exception: + terminal_env = "local" + print(f" Backend: {terminal_env}") + + if terminal_env == "ssh": + ssh_host = os.getenv("TERMINAL_SSH_HOST", "") + ssh_user = os.getenv("TERMINAL_SSH_USER", "") + print(f" SSH Host: {ssh_host or '(not set)'}") + print(f" SSH User: {ssh_user or '(not set)'}") + elif terminal_env == "docker": + docker_image = os.getenv("TERMINAL_DOCKER_IMAGE", "python:3.11-slim") + print(f" Docker Image: {docker_image}") + elif terminal_env == "daytona": + daytona_image = os.getenv("TERMINAL_DAYTONA_IMAGE", "nikolaik/python-nodejs:python3.11-nodejs20") + print(f" Daytona Image: {daytona_image}") + + sudo_password = os.getenv("SUDO_PASSWORD", "") + print(f" Sudo: {check_mark(bool(sudo_password))} {'enabled' if sudo_password else 'disabled'}") + + # ========================================================================= + # Messaging Platforms + # ========================================================================= + print() + print(color("◆ Messaging Platforms", Colors.CYAN, Colors.BOLD)) + + platforms = { + "Telegram": ("TELEGRAM_BOT_TOKEN", "TELEGRAM_HOME_CHANNEL"), + "Discord": ("DISCORD_BOT_TOKEN", "DISCORD_HOME_CHANNEL"), + "WhatsApp": ("WHATSAPP_ENABLED", None), + "Signal": ("SIGNAL_HTTP_URL", "SIGNAL_HOME_CHANNEL"), + "Slack": ("SLACK_BOT_TOKEN", None), + "Email": ("EMAIL_ADDRESS", "EMAIL_HOME_ADDRESS"), + "SMS": ("TWILIO_ACCOUNT_SID", "SMS_HOME_CHANNEL"), + "DingTalk": ("DINGTALK_CLIENT_ID", None), + "Feishu": ("FEISHU_APP_ID", "FEISHU_HOME_CHANNEL"), + "WeCom": ("WECOM_BOT_ID", "WECOM_HOME_CHANNEL"), + "WeCom Callback": ("WECOM_CALLBACK_CORP_ID", None), + "Weixin": ("WEIXIN_ACCOUNT_ID", "WEIXIN_HOME_CHANNEL"), + "BlueBubbles": ("BLUEBUBBLES_SERVER_URL", "BLUEBUBBLES_HOME_CHANNEL"), + "QQBot": ("QQ_APP_ID", "QQ_HOME_CHANNEL"), + } + + for name, (token_var, home_var) in platforms.items(): + token = os.getenv(token_var, "") + has_token = bool(token) + + home_channel = "" + if home_var: + home_channel = os.getenv(home_var, "") + + status = "configured" if has_token else "not configured" + if home_channel: + status += f" (home: {home_channel})" + + print(f" {name:<12} {check_mark(has_token)} {status}") + + # ========================================================================= + # Gateway Status + # ========================================================================= + print() + print(color("◆ Gateway Service", Colors.CYAN, Colors.BOLD)) + + if _is_termux(): + try: + from hermes_cli.gateway import find_gateway_pids + gateway_pids = find_gateway_pids() + except Exception: + gateway_pids = [] + is_running = bool(gateway_pids) + print(f" Status: {check_mark(is_running)} {'running' if is_running else 'stopped'}") + print(" Manager: Termux / manual process") + if gateway_pids: + rendered = ", ".join(str(pid) for pid in gateway_pids[:3]) + if len(gateway_pids) > 3: + rendered += ", ..." + print(f" PID(s): {rendered}") + else: + print(" Start with: hermes gateway") + print(" Note: Android may stop background jobs when Termux is suspended") + + elif sys.platform.startswith('linux'): + from hermes_constants import is_container + if is_container(): + # Docker/Podman: no systemd — check for running gateway processes + try: + from hermes_cli.gateway import find_gateway_pids + gateway_pids = find_gateway_pids() + is_active = len(gateway_pids) > 0 + except Exception: + is_active = False + print(f" Status: {check_mark(is_active)} {'running' if is_active else 'stopped'}") + print(" Manager: docker (foreground)") + else: + try: + from hermes_cli.gateway import get_service_name + _gw_svc = get_service_name() + except Exception: + _gw_svc = "hermes-gateway" + try: + result = subprocess.run( + ["systemctl", "--user", "is-active", _gw_svc], + capture_output=True, + text=True, + timeout=5 + ) + is_active = result.stdout.strip() == "active" + except (FileNotFoundError, subprocess.TimeoutExpired): + is_active = False + print(f" Status: {check_mark(is_active)} {'running' if is_active else 'stopped'}") + print(" Manager: systemd (user)") + + elif sys.platform == 'darwin': + from hermes_cli.gateway import get_launchd_label + try: + result = subprocess.run( + ["launchctl", "list", get_launchd_label()], + capture_output=True, + text=True, + timeout=5 + ) + is_loaded = result.returncode == 0 + except subprocess.TimeoutExpired: + is_loaded = False + print(f" Status: {check_mark(is_loaded)} {'loaded' if is_loaded else 'not loaded'}") + print(" Manager: launchd") + else: + print(f" Status: {color('N/A', Colors.DIM)}") + print(" Manager: (not supported on this platform)") + + # ========================================================================= + # Cron Jobs + # ========================================================================= + print() + print(color("◆ Scheduled Jobs", Colors.CYAN, Colors.BOLD)) + + jobs_file = get_hermes_home() / "cron" / "jobs.json" + if jobs_file.exists(): + import json + try: + with open(jobs_file, encoding="utf-8") as f: + data = json.load(f) + jobs = data.get("jobs", []) + enabled_jobs = [j for j in jobs if j.get("enabled", True)] + print(f" Jobs: {len(enabled_jobs)} active, {len(jobs)} total") + except Exception: + print(" Jobs: (error reading jobs file)") + else: + print(" Jobs: 0") + + # ========================================================================= + # Sessions + # ========================================================================= + print() + print(color("◆ Sessions", Colors.CYAN, Colors.BOLD)) + + sessions_file = get_hermes_home() / "sessions" / "sessions.json" + if sessions_file.exists(): + import json + try: + with open(sessions_file, encoding="utf-8") as f: + data = json.load(f) + print(f" Active: {len(data)} session(s)") + except Exception: + print(" Active: (error reading sessions file)") + else: + print(" Active: 0") + + # ========================================================================= + # Deep checks + # ========================================================================= + if deep: + print() + print(color("◆ Deep Checks", Colors.CYAN, Colors.BOLD)) + + # Check OpenRouter connectivity + openrouter_key = os.getenv("OPENROUTER_API_KEY", "") + if openrouter_key: + try: + import httpx + response = httpx.get( + OPENROUTER_MODELS_URL, + headers={"Authorization": f"Bearer {openrouter_key}"}, + timeout=10 + ) + ok = response.status_code == 200 + print(f" OpenRouter: {check_mark(ok)} {'reachable' if ok else f'error ({response.status_code})'}") + except Exception as e: + print(f" OpenRouter: {check_mark(False)} error: {e}") + + # Check gateway port + try: + import socket + sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + sock.settimeout(1) + result = sock.connect_ex(('127.0.0.1', 18789)) + sock.close() + # Port in use = gateway likely running + port_in_use = result == 0 + # This is informational, not necessarily bad + print(f" Port 18789: {'in use' if port_in_use else 'available'}") + except OSError: + pass + + print() + print(color("─" * 60, Colors.DIM)) + print(color(" Run 'hermes doctor' for detailed diagnostics", Colors.DIM)) + print(color(" Run 'hermes setup' to configure", Colors.DIM)) + print() diff --git a/mindcli/_vendor/hermes_cli/tips.py b/mindcli/_vendor/hermes_cli/tips.py new file mode 100644 index 0000000..aa6cb97 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/tips.py @@ -0,0 +1,349 @@ +"""Random tips shown at CLI session start to help users discover features.""" + +import random + + +# --------------------------------------------------------------------------- +# Tip corpus — one-liners covering slash commands, CLI flags, config, +# keybindings, tools, gateway, skills, profiles, and workflow tricks. +# --------------------------------------------------------------------------- + +TIPS = [ + # --- Slash Commands --- + "/btw asks a quick side question without tools or history — great for clarifications.", + "/background runs a task in a separate session while your current one stays free.", + "/branch forks the current session so you can explore a different direction without losing progress.", + "/compress manually compresses conversation context when things get long.", + "/rollback lists filesystem checkpoints — restore files the agent modified to any prior state.", + "/rollback diff 2 previews what changed since checkpoint 2 without restoring anything.", + "/rollback 2 src/file.py restores a single file from a specific checkpoint.", + "/title \"my project\" names your session — resume it later with /resume or hermes -c.", + "/resume picks up where you left off in a previously named session.", + "/queue queues a message for the next turn without interrupting the current one.", + "/undo removes the last user/assistant exchange from the conversation.", + "/retry resends your last message — useful when the agent's response wasn't quite right.", + "/verbose cycles tool progress display: off → new → all → verbose.", + "/reasoning high increases the model's thinking depth. /reasoning show displays the reasoning.", + "/fast toggles priority processing for faster API responses (provider-dependent).", + "/yolo skips all dangerous command approval prompts for the rest of the session.", + "/model lets you switch models mid-session — try /model sonnet or /model gpt-5.", + "/model --global changes your default model permanently.", + "/personality pirate sets a fun personality — 14 built-in options from kawaii to shakespeare.", + "/skin changes the CLI theme — try ares, mono, slate, poseidon, or charizard.", + "/statusbar toggles a persistent bar showing model, tokens, context fill %, cost, and duration.", + "/tools disable browser temporarily removes browser tools for the current session.", + "/browser connect attaches browser tools to your running Chrome instance via CDP.", + "/plugins lists installed plugins and their status.", + "/cron manages scheduled tasks — set up recurring prompts with delivery to any platform.", + "/reload-mcp hot-reloads MCP server configuration without restarting.", + "/usage shows token usage, cost breakdown, and session duration.", + "/insights shows usage analytics for the last 30 days.", + "/paste checks your clipboard for an image and attaches it to your next message.", + "/profile shows which profile is active and its home directory.", + "/config shows your current configuration at a glance.", + "/stop kills all running background processes spawned by the agent.", + + # --- @ Context References --- + "@file:path/to/file.py injects file contents directly into your message.", + "@file:main.py:10-50 injects only lines 10-50 of a file.", + "@folder:src/ injects a directory tree listing.", + "@diff injects your unstaged git changes into the message.", + "@staged injects your staged git changes (git diff --staged).", + "@git:5 injects the last 5 commits with full patches.", + "@url:https://example.com fetches and injects a web page's content.", + "Typing @ triggers filesystem path completion — navigate to any file interactively.", + "Combine multiple references: \"Review @file:main.py and @file:test.py for consistency.\"", + + # --- Keybindings --- + "Alt+Enter (or Ctrl+J) inserts a newline for multi-line input.", + "Ctrl+C interrupts the agent. Double-press within 2 seconds to force exit.", + "Ctrl+Z suspends Hermes to the background — run fg in your shell to resume.", + "Tab accepts auto-suggestion ghost text or autocompletes slash commands.", + "Type a new message while the agent is working to interrupt and redirect it.", + "Alt+V pastes an image from your clipboard into the conversation.", + "Pasting 5+ lines auto-saves to a file and inserts a compact reference instead.", + + # --- CLI Flags --- + "hermes -c resumes your most recent CLI session. hermes -c \"project name\" resumes by title.", + "hermes -w creates an isolated git worktree — perfect for parallel agent workflows.", + "hermes -w -q \"Fix issue #42\" combines worktree isolation with a one-shot query.", + "hermes chat -t web,terminal enables only specific toolsets for a focused session.", + "hermes chat -s github-pr-workflow preloads a skill at launch.", + "hermes chat -q \"query\" runs a single non-interactive query and exits.", + "hermes chat --max-turns 200 overrides the default 90-iteration limit per turn.", + "hermes chat --checkpoints enables filesystem snapshots before every destructive file change.", + "hermes --yolo bypasses all dangerous command approval prompts for the entire session.", + "hermes chat --source telegram tags the session for filtering in hermes sessions list.", + "hermes -p work chat runs under a specific profile without changing your default.", + + # --- CLI Subcommands --- + "hermes doctor --fix diagnoses and auto-repairs config and dependency issues.", + "hermes dump outputs a compact setup summary — great for bug reports.", + "hermes config set KEY VALUE auto-routes secrets to .env and everything else to config.yaml.", + "hermes config edit opens config.yaml in your default editor.", + "hermes config check scans for missing or stale configuration options.", + "hermes sessions browse opens an interactive session picker with search.", + "hermes sessions stats shows session counts by platform and database size.", + "hermes sessions prune --older-than 30 cleans up old sessions.", + "hermes skills search react --source skills-sh searches the skills.sh public directory.", + "hermes skills check scans installed hub skills for upstream updates.", + "hermes skills tap add myorg/skills-repo adds a custom GitHub skill source.", + "hermes skills snapshot export setup.json exports your skill configuration for backup or sharing.", + "hermes mcp add github --command npx adds MCP servers from the command line.", + "hermes mcp serve runs Hermes itself as an MCP server for other agents.", + "hermes auth add lets you add multiple API keys for credential pool rotation.", + "hermes completion bash >> ~/.bashrc enables tab completion for all commands and profiles.", + "hermes logs -f follows agent.log in real time. --level WARNING --since 1h filters output.", + "hermes backup creates a zip backup of your entire Hermes home directory.", + "hermes profile create coder creates an isolated profile that becomes its own command.", + "hermes profile create work --clone copies your current config and keys to a new profile.", + "hermes update syncs new bundled skills to ALL profiles automatically.", + "hermes gateway install sets up Hermes as a system service (systemd/launchd).", + "hermes memory setup lets you configure an external memory provider (Honcho, Mem0, etc.).", + "hermes webhook subscribe creates event-driven webhook routes with HMAC validation.", + + # --- Configuration --- + "Set display.bell_on_complete: true in config.yaml to hear a bell when long tasks finish.", + "Set display.streaming: true to see tokens appear in real time as the model generates.", + "Set display.show_reasoning: true to watch the model's chain-of-thought reasoning.", + "Set display.compact: true to reduce whitespace in output for denser information.", + "Set display.busy_input_mode: queue to queue messages instead of interrupting the agent.", + "Set display.resume_display: minimal to skip the full conversation recap on session resume.", + "Set compression.threshold: 0.50 to control when auto-compression fires (default: 50% of context).", + "Set agent.max_turns: 200 to let the agent take more tool-calling steps per turn.", + "Set file_read_max_chars: 200000 to increase the max content per read_file call.", + "Set approvals.mode: smart to let an LLM auto-approve safe commands and auto-deny dangerous ones.", + "Set fallback_model in config.yaml to automatically fail over to a backup provider.", + "Set privacy.redact_pii: true to hash user IDs and phone numbers before sending to the LLM.", + "Set browser.record_sessions: true to auto-record browser sessions as WebM videos.", + "Set worktree: true in config.yaml to always create a git worktree (same as hermes -w).", + "Set security.website_blocklist.enabled: true to block specific domains from web tools.", + "Set cron.wrap_response: false to deliver raw agent output without the cron header/footer.", + "HERMES_TIMEZONE overrides the server timezone with any IANA timezone string.", + "Environment variable substitution works in config.yaml: use ${VAR_NAME} syntax.", + "Quick commands in config.yaml run shell commands instantly with zero token usage.", + "Custom personalities can be defined in config.yaml under agent.personalities.", + "provider_routing controls OpenRouter provider sorting, whitelisting, and blacklisting.", + + # --- Tools & Capabilities --- + "execute_code runs Python scripts that call Hermes tools programmatically — results stay out of context.", + "delegate_task spawns up to 3 concurrent sub-agents with isolated contexts for parallel work.", + "web_extract works on PDF URLs — pass any PDF link and it converts to markdown.", + "search_files is ripgrep-backed and faster than grep — use it instead of terminal grep.", + "patch uses 9 fuzzy matching strategies so minor whitespace differences won't break edits.", + "patch supports V4A format for bulk multi-file edits in a single call.", + "read_file suggests similar filenames when a file isn't found.", + "read_file auto-deduplicates — re-reading an unchanged file returns a lightweight stub.", + "browser_vision takes a screenshot and analyzes it with AI — works for CAPTCHAs and visual content.", + "browser_console can evaluate JavaScript expressions in the page context.", + "image_generate creates images with FLUX 2 Pro and automatic 2x upscaling.", + "text_to_speech converts text to audio — plays as voice bubbles on Telegram.", + "send_message can reach any connected messaging platform from within a session.", + "The todo tool helps the agent track complex multi-step tasks during a session.", + "session_search performs full-text search across ALL past conversations.", + "The agent automatically saves preferences, corrections, and environment facts to memory.", + "mixture_of_agents routes hard problems through 4 frontier LLMs collaboratively.", + "Terminal commands support background mode with notify_on_complete for long-running tasks.", + "Terminal background processes support watch_patterns to alert on specific output lines.", + "The terminal tool supports 6 backends: local, Docker, SSH, Modal, Daytona, and Singularity.", + + # --- Profiles --- + "Each profile gets its own config, API keys, memory, sessions, skills, and cron jobs.", + "Profile names become shell commands — 'hermes profile create coder' creates the 'coder' command.", + "hermes profile export coder -o backup.tar.gz creates a portable profile archive.", + "If two profiles accidentally share a bot token, the second gateway is blocked with a clear error.", + + # --- Sessions --- + "Sessions auto-generate descriptive titles after the first exchange — no manual naming needed.", + "Session titles support lineage: \"my project\" → \"my project #2\" → \"my project #3\".", + "When exiting, Hermes prints a resume command with session ID and stats.", + "hermes sessions export backup.jsonl exports all sessions for backup or analysis.", + "hermes -r SESSION_ID resumes any specific past session by its ID.", + + # --- Memory --- + "Memory is a frozen snapshot — changes appear in the system prompt only at next session start.", + "Memory entries are automatically scanned for prompt injection and exfiltration patterns.", + "The agent has two memory stores: personal notes (~2200 chars) and user profile (~1375 chars).", + "Corrections you give the agent (\"no, do it this way\") are often auto-saved to memory.", + + # --- Skills --- + "Over 80 bundled skills covering github, creative, mlops, productivity, research, and more.", + "Every installed skill automatically becomes a slash command — type / to see them all.", + "hermes skills install official/security/1password installs optional skills from the repo.", + "Skills can restrict to specific OS platforms — some only load on macOS or Linux.", + "skills.external_dirs in config.yaml lets you load skills from custom directories.", + "The agent can create its own skills as procedural memory using skill_manage.", + "The plan skill saves markdown plans under .hermes/plans/ in the active workspace.", + + # --- Cron & Scheduling --- + "Cron jobs can attach skills: hermes cron add --skill blogwatcher \"Check for new posts\".", + "Cron delivery targets include telegram, discord, slack, email, sms, and 12+ more platforms.", + "If a cron response starts with [SILENT], delivery is suppressed — useful for monitoring-only jobs.", + "Cron supports relative delays (30m), intervals (every 2h), cron expressions, and ISO timestamps.", + "Cron jobs run in completely fresh agent sessions — prompts must be self-contained.", + + # --- Voice --- + "Voice mode works with zero API keys if faster-whisper is installed (free local speech-to-text).", + "Five TTS providers available: Edge TTS (free), ElevenLabs, OpenAI, NeuTTS (free local), MiniMax.", + "/voice on enables voice mode in the CLI. Ctrl+B toggles push-to-talk recording.", + "Streaming TTS plays sentences as they generate — you don't wait for the full response.", + "Voice messages on Telegram, Discord, WhatsApp, and Slack are auto-transcribed.", + + # --- Gateway & Messaging --- + "Hermes runs on 18 platforms: Telegram, Discord, Slack, WhatsApp, Signal, Matrix, email, and more.", + "hermes gateway install sets it up as a system service that starts on boot.", + "DingTalk uses Stream Mode — no webhooks or public URL needed.", + "BlueBubbles brings iMessage to Hermes via a local macOS server.", + "Webhook routes support HMAC validation, rate limiting, and event filtering.", + "The API server exposes an OpenAI-compatible endpoint compatible with Open WebUI and LibreChat.", + "Discord voice channel mode: the bot joins VC, transcribes speech, and talks back.", + "group_sessions_per_user: true gives each person their own session in group chats.", + "/sethome marks a chat as the home channel for cron job deliveries.", + "The gateway supports inactivity-based timeouts — active agents can run indefinitely.", + + # --- Security --- + "Dangerous command approval has 4 tiers: once, session, always (permanent allowlist), deny.", + "Smart approval mode uses an LLM to auto-approve safe commands and flag dangerous ones.", + "SSRF protection blocks private networks, loopback, link-local, and cloud metadata addresses.", + "Tirith pre-exec scanning detects homograph URL spoofing and pipe-to-interpreter patterns.", + "MCP subprocesses receive a filtered environment — only safe system vars pass through.", + "Context files (.hermes.md, AGENTS.md) are security-scanned for prompt injection before loading.", + "command_allowlist in config.yaml permanently approves specific shell command patterns.", + + # --- Context & Compression --- + "Context auto-compresses when it reaches the threshold — memories are flushed and history summarized.", + "The status bar turns yellow, then orange, then red as context fills up.", + "SOUL.md at ~/.hermes/SOUL.md is the agent's primary identity — customize it to shape behavior.", + "Hermes loads project context from .hermes.md, AGENTS.md, CLAUDE.md, or .cursorrules (first match).", + "Subdirectory AGENTS.md files are discovered progressively as the agent navigates into folders.", + "Context files are capped at 20,000 characters with smart head/tail truncation.", + + # --- Browser --- + "Five browser providers: local Chromium, Browserbase, Browser Use, Camofox, and Firecrawl.", + "Camofox is an anti-detection browser — Firefox fork with C++ fingerprint spoofing.", + "browser_navigate returns a page snapshot automatically — no need to call browser_snapshot after.", + "browser_vision with annotate=true overlays numbered labels on interactive elements.", + + # --- MCP --- + "MCP servers are configured in config.yaml — both stdio and HTTP transports supported.", + "Per-server tool filtering: tools.include whitelists and tools.exclude blacklists specific tools.", + "MCP servers auto-generate toolsets at runtime — hermes tools can toggle them per platform.", + "MCP OAuth support: auth: oauth enables browser-based authorization with PKCE.", + + # --- Checkpoints & Rollback --- + "Checkpoints have zero overhead when no files are modified — enabled by default.", + "A pre-rollback snapshot is saved automatically so you can undo the undo.", + "/rollback also undoes the conversation turn, so the agent doesn't remember rolled-back changes.", + "Checkpoints use shadow repos in ~/.hermes/checkpoints/ — your project's .git is never touched.", + + # --- Batch & Data --- + "batch_runner.py processes hundreds of prompts in parallel for training data generation.", + "hermes chat -Q enables quiet mode for programmatic use — suppresses banner and spinner.", + "Trajectory saving (--save-trajectories) captures full tool-use traces for model training.", + + # --- Plugins --- + "Three plugin types: general (tools/hooks), memory providers, and context engines.", + "hermes plugins install owner/repo installs plugins directly from GitHub.", + "8 external memory providers available: Honcho, OpenViking, Mem0, Hindsight, and more.", + "Plugin hooks include pre_tool_call, post_tool_call, pre_llm_call, and post_llm_call.", + + # --- Miscellaneous --- + "Prompt caching (Anthropic) reduces costs by reusing cached system prompt prefixes.", + "The agent auto-generates session titles in a background thread — zero latency impact.", + "Smart model routing can auto-route simple queries to a cheaper model.", + "Slash commands support prefix matching: /h resolves to /help, /mod to /model.", + "Dragging a file path into the terminal auto-attaches images or sends as context.", + ".worktreeinclude in your repo root lists gitignored files to copy into worktrees.", + "hermes acp runs Hermes as an ACP server for VS Code, Zed, and JetBrains integration.", + "Custom providers: save named endpoints in config.yaml under custom_providers.", + "HERMES_EPHEMERAL_SYSTEM_PROMPT injects a system prompt that's never persisted to history.", + "credential_pool_strategies supports fill_first, round_robin, least_used, and random rotation.", + "hermes login supports OAuth-based auth for Nous and OpenAI Codex providers.", + "The API server supports both Chat Completions and Responses API with server-side state.", + "tool_preview_length: 0 in config shows full file paths in the spinner's activity feed.", + "hermes status --deep runs deeper diagnostic checks across all components.", + + # --- Hidden Gems & Power-User Tricks --- + "BOOT.md at ~/.hermes/BOOT.md runs automatically on every gateway start — use it for startup checks.", + "Cron jobs can attach a Python script (--script) whose stdout is injected into the prompt as context.", + "Cron scripts live in ~/.hermes/scripts/ and run before the agent — perfect for data collection pipelines.", + "prefill_messages_file in config.yaml injects few-shot examples into every API call, never saved to history.", + "SOUL.md completely replaces the agent's default identity — rewrite it to make Hermes your own.", + "SOUL.md is auto-seeded with a default personality on first run. Edit ~/.hermes/SOUL.md to customize.", + "/compress allocates 60-70% of the summary budget to your topic and aggressively trims the rest.", + "On second+ compression, the compressor updates the previous summary instead of starting from scratch.", + "Before a gateway session reset, Hermes auto-flushes important facts to memory in the background.", + "network.force_ipv4: true in config.yaml fixes hangs on servers with broken IPv6 — monkey-patches socket.", + "The terminal tool annotates common exit codes: grep returning 1 = 'No matches found (not an error)'.", + "Failed foreground terminal commands auto-retry up to 3 times with exponential backoff (2s, 4s, 8s).", + "Bare sudo commands are auto-rewritten to pipe SUDO_PASSWORD from .env — no interactive prompt needed.", + "execute_code has built-in helpers: json_parse() for tolerant parsing, shell_quote(), and retry() with backoff.", + "execute_code's 7 sandbox tools (web_search, terminal, read/write/search/patch) use RPC — never enter context.", + "Reading the same file region 3+ times triggers a warning. At 4+, it's hard-blocked to prevent loops.", + "write_file and patch detect if a file was externally modified since the last read and warn about staleness.", + "V4A patch format supports Add File, Delete File, and Move File directives — not just Update.", + "MCP servers can request LLM completions back via sampling — the agent becomes a tool for the server.", + "MCP servers send notifications/tools/list_changed to trigger automatic tool re-registration without restart.", + "delegate_task with acp_command: 'claude' spawns Claude Code as a child agent from any platform.", + "Delegation has a heartbeat thread — child activity propagates to the parent, preventing gateway timeouts.", + "When a provider returns HTTP 402 (payment required), the auxiliary client auto-falls back to the next one.", + "agent.tool_use_enforcement steers models that describe actions instead of calling tools — auto for GPT/Codex.", + "agent.restart_drain_timeout (default 60s) lets running agents finish before a gateway restart takes effect.", + "The gateway caches AIAgent instances per session — destroying this cache breaks Anthropic prompt caching.", + "Any website can expose skills via /.well-known/skills/index.json — the skills hub discovers them automatically.", + "The skills audit log at ~/.hermes/skills/.hub/audit.log tracks every install and removal operation.", + "Stale git worktrees are auto-cleaned: 24-72h old with no unpushed commits get pruned on startup.", + "Each profile gets its own subprocess HOME at HERMES_HOME/home/ — isolated git, ssh, npm, gh configs.", + "HERMES_HOME_MODE env var (octal, e.g. 0701) sets custom directory permissions for web server traversal.", + "Container mode: place .container-mode in HERMES_HOME and the host CLI auto-execs into the container.", + "Ctrl+C has 5 priority tiers: cancel recording → cancel prompts → cancel picker → interrupt agent → exit.", + "Every interrupt during an agent run is logged to ~/.hermes/interrupt_debug.log with timestamps.", + "BROWSER_CDP_URL connects browser tools to any running Chrome — accepts WebSocket, HTTP, or host:port.", + "BROWSERBASE_ADVANCED_STEALTH=true enables advanced anti-detection with custom Chromium (Scale Plan).", + "The CLI auto-switches to compact mode in terminals narrower than 80 columns.", + "Quick commands support two types: exec (run shell command directly) and alias (redirect to another command).", + "Per-task delegation model: delegation.model and delegation.provider in config route subagents to cheaper models.", + "delegation.reasoning_effort independently controls thinking depth for subagents.", + "display.platforms in config.yaml allows per-platform display overrides: {telegram: {tool_progress: all}}.", + "human_delay.mode in config simulates human typing speed — configurable min_ms/max_ms range.", + "Config version migrations run automatically on load — new config keys appear without manual intervention.", + "GPT and Codex models get special system prompt guidance for tool discipline and mandatory tool use.", + "Gemini models get tailored directives for absolute paths, parallel tool calls, and non-interactive commands.", + "context.engine in config.yaml can be set to a plugin name for alternative context management strategies.", + "Browser pages over 8000 tokens are auto-summarized by the auxiliary LLM before returning to the agent.", + "The compressor does a cheap pre-pass: tool outputs over 200 chars are replaced with placeholders before the LLM runs.", + "When compression fails, further attempts are paused for 10 minutes to avoid API hammering.", + "Long dangerous commands (>70 chars) get a 'view' option in the approval prompt to see the full text first.", + "Audio level visualization shows ▁▂▃▄▅▆▇ bars during voice recording based on microphone RMS levels.", + "Profile names cannot collide with existing PATH binaries — 'hermes profile create ls' would be rejected.", + "hermes profile create backup --clone-all copies everything (config, keys, SOUL.md, memories, skills, sessions).", + "The voice record key is configurable via voice.record_key in config.yaml — not just Ctrl+B.", + ".cursorrules and .cursor/rules/*.mdc files are auto-detected and loaded as project context.", + "Context files support 10+ prompt injection patterns — invisible Unicode, 'ignore instructions', exfil attempts.", + "GPT-5 and Codex use 'developer' role instead of 'system' in the message format.", + "Per-task auxiliary overrides: auxiliary.vision.provider, auxiliary.compression.model, etc. in config.yaml.", + "The auxiliary client treats 'main' as a provider alias — resolves to your actual primary provider + model.", + "Smart routing can auto-route simple queries to a cheaper model — set smart_model_routing.enabled: true.", + "hermes claw migrate --dry-run previews OpenClaw migration without writing anything.", + "File paths pasted with quotes or escaped spaces are handled automatically — no manual cleanup needed.", + "Slash commands never trigger the large-paste collapse — /command with big arguments works correctly.", + "In interrupt mode, slash commands typed during agent execution bypass interrupt logic and run immediately.", + "HERMES_DEV=1 bypasses container mode detection for local development.", + "Each MCP server gets its own toolset (mcp-servername) that can be toggled independently via hermes tools.", + "MCP ${ENV_VAR} placeholders in config are resolved at server spawn — including vars from ~/.hermes/.env.", + "Skills from trusted repos (NousResearch) get a 'trusted' security level; community skills get extra scanning.", + "The skills quarantine at ~/.hermes/skills/.hub/quarantine/ holds skills pending security review.", +] + + +def get_random_tip(exclude_recent: int = 0) -> str: + """Return a random tip string. + + Args: + exclude_recent: not used currently; reserved for future + deduplication across sessions. + """ + return random.choice(TIPS) + + + diff --git a/mindcli/_vendor/hermes_cli/tools_config.py b/mindcli/_vendor/hermes_cli/tools_config.py new file mode 100644 index 0000000..d74f7ea --- /dev/null +++ b/mindcli/_vendor/hermes_cli/tools_config.py @@ -0,0 +1,1700 @@ +""" +Unified tool configuration for Hermes Agent. + +`hermes tools` and `hermes setup tools` both enter this module. +Select a platform → toggle toolsets on/off → for newly enabled tools +that need API keys, run through provider-aware configuration. + +Saves per-platform tool configuration to ~/.hermes/config.yaml under +the `platform_toolsets` key. +""" + +import json as _json +import logging +import sys +from pathlib import Path +from typing import Dict, List, Optional, Set + + +from hermes_cli.config import ( + load_config, save_config, get_env_value, save_env_value, +) +from hermes_cli.colors import Colors, color +from hermes_cli.nous_subscription import ( + apply_nous_managed_defaults, + get_nous_subscription_features, +) +from tools.tool_backend_helpers import managed_nous_tools_enabled + +logger = logging.getLogger(__name__) + +PROJECT_ROOT = Path(__file__).parent.parent.resolve() + + +# ─── UI Helpers (shared with setup.py) ──────────────────────────────────────── + +from hermes_cli.cli_output import ( # noqa: E402 — late import block + print_error as _print_error, + print_info as _print_info, + print_success as _print_success, + print_warning as _print_warning, + prompt as _prompt, +) + +# ─── Toolset Registry ───────────────────────────────────────────────────────── + +# Toolsets shown in the configurator, grouped for display. +# Each entry: (toolset_name, label, description) +# These map to keys in toolsets.py TOOLSETS dict. +CONFIGURABLE_TOOLSETS = [ + ("web", "🔍 Web Search & Scraping", "web_search, web_extract"), + ("browser", "🌐 Browser Automation", "navigate, click, type, scroll"), + ("terminal", "💻 Terminal & Processes", "terminal, process"), + ("file", "📁 File Operations", "read, write, patch, search"), + ("code_execution", "⚡ Code Execution", "execute_code"), + ("vision", "👁️ Vision / Image Analysis", "vision_analyze"), + ("image_gen", "🎨 Image Generation", "image_generate"), + ("moa", "🧠 Mixture of Agents", "mixture_of_agents"), + ("tts", "🔊 Text-to-Speech", "text_to_speech"), + ("skills", "📚 Skills", "list, view, manage"), + ("todo", "📋 Task Planning", "todo"), + ("memory", "💾 Memory", "persistent memory across sessions"), + ("session_search", "🔎 Session Search", "search past conversations"), + ("clarify", "❓ Clarifying Questions", "clarify"), + ("delegation", "👥 Task Delegation", "delegate_task"), + ("cronjob", "⏰ Cron Jobs", "create/list/update/pause/resume/run, with optional attached skills"), + ("rl", "🧪 RL Training", "Tinker-Atropos training tools"), + ("homeassistant", "🏠 Home Assistant", "smart home device control"), +] + +# Toolsets that are OFF by default for new installs. +# They're still in _HERMES_CORE_TOOLS (available at runtime if enabled), +# but the setup checklist won't pre-select them for first-time users. +_DEFAULT_OFF_TOOLSETS = {"moa", "homeassistant", "rl"} + + +def _get_effective_configurable_toolsets(): + """Return CONFIGURABLE_TOOLSETS + any plugin-provided toolsets. + + Plugin toolsets are appended at the end so they appear after the + built-in toolsets in the TUI checklist. + """ + result = list(CONFIGURABLE_TOOLSETS) + try: + from hermes_cli.plugins import discover_plugins, get_plugin_toolsets + discover_plugins() # idempotent — ensures plugins are loaded + result.extend(get_plugin_toolsets()) + except Exception: + pass + return result + + +def _get_plugin_toolset_keys() -> set: + """Return the set of toolset keys provided by plugins.""" + try: + from hermes_cli.plugins import discover_plugins, get_plugin_toolsets + discover_plugins() # idempotent — ensures plugins are loaded + return {ts_key for ts_key, _, _ in get_plugin_toolsets()} + except Exception: + return set() + +# Platform display config — derived from the canonical registry so every +# module shares the same data. Kept as dict-of-dicts for backward +# compatibility with existing ``PLATFORMS[key]["label"]`` access patterns. +from hermes_cli.platforms import PLATFORMS as _PLATFORMS_REGISTRY + +PLATFORMS = { + k: {"label": info.label, "default_toolset": info.default_toolset} + for k, info in _PLATFORMS_REGISTRY.items() +} + + +# ─── Tool Categories (provider-aware configuration) ────────────────────────── +# Maps toolset keys to their provider options. When a toolset is newly enabled, +# we use this to show provider selection and prompt for the right API keys. +# Toolsets not in this map either need no config or use the simple fallback. + +TOOL_CATEGORIES = { + "tts": { + "name": "Text-to-Speech", + "icon": "🔊", + "providers": [ + { + "name": "Nous Subscription", + "tag": "Managed OpenAI TTS billed to your subscription", + "env_vars": [], + "tts_provider": "openai", + "requires_nous_auth": True, + "managed_nous_feature": "tts", + "override_env_vars": ["VOICE_TOOLS_OPENAI_KEY", "OPENAI_API_KEY"], + }, + { + "name": "Microsoft Edge TTS", + "tag": "Free - no API key needed", + "env_vars": [], + "tts_provider": "edge", + }, + { + "name": "OpenAI TTS", + "tag": "Premium - high quality voices", + "env_vars": [ + {"key": "VOICE_TOOLS_OPENAI_KEY", "prompt": "OpenAI API key", "url": "https://platform.openai.com/api-keys"}, + ], + "tts_provider": "openai", + }, + { + "name": "ElevenLabs", + "tag": "Premium - most natural voices", + "env_vars": [ + {"key": "ELEVENLABS_API_KEY", "prompt": "ElevenLabs API key", "url": "https://elevenlabs.io/app/settings/api-keys"}, + ], + "tts_provider": "elevenlabs", + }, + { + "name": "Mistral (Voxtral TTS)", + "tag": "Multilingual, native Opus, needs MISTRAL_API_KEY", + "env_vars": [ + {"key": "MISTRAL_API_KEY", "prompt": "Mistral API key", "url": "https://console.mistral.ai/"}, + ], + "tts_provider": "mistral", + }, + ], + }, + "web": { + "name": "Web Search & Extract", + "setup_title": "Select Search Provider", + "setup_note": "A free DuckDuckGo search skill is also included — skip this if you don't need a premium provider.", + "icon": "🔍", + "providers": [ + { + "name": "Nous Subscription", + "tag": "Managed Firecrawl billed to your subscription", + "web_backend": "firecrawl", + "env_vars": [], + "requires_nous_auth": True, + "managed_nous_feature": "web", + "override_env_vars": ["FIRECRAWL_API_KEY", "FIRECRAWL_API_URL"], + }, + { + "name": "Firecrawl Cloud", + "tag": "Hosted service - search, extract, and crawl", + "web_backend": "firecrawl", + "env_vars": [ + {"key": "FIRECRAWL_API_KEY", "prompt": "Firecrawl API key", "url": "https://firecrawl.dev"}, + ], + }, + { + "name": "Exa", + "tag": "AI-native search and contents", + "web_backend": "exa", + "env_vars": [ + {"key": "EXA_API_KEY", "prompt": "Exa API key", "url": "https://exa.ai"}, + ], + }, + { + "name": "Parallel", + "tag": "AI-native search and extract", + "web_backend": "parallel", + "env_vars": [ + {"key": "PARALLEL_API_KEY", "prompt": "Parallel API key", "url": "https://parallel.ai"}, + ], + }, + { + "name": "Tavily", + "tag": "AI-native search, extract, and crawl", + "web_backend": "tavily", + "env_vars": [ + {"key": "TAVILY_API_KEY", "prompt": "Tavily API key", "url": "https://app.tavily.com/home"}, + ], + }, + { + "name": "Firecrawl Self-Hosted", + "tag": "Free - run your own instance", + "web_backend": "firecrawl", + "env_vars": [ + {"key": "FIRECRAWL_API_URL", "prompt": "Your Firecrawl instance URL (e.g., http://localhost:3002)"}, + ], + }, + ], + }, + "image_gen": { + "name": "Image Generation", + "icon": "🎨", + "providers": [ + { + "name": "Nous Subscription", + "tag": "Managed FAL image generation billed to your subscription", + "env_vars": [], + "requires_nous_auth": True, + "managed_nous_feature": "image_gen", + "override_env_vars": ["FAL_KEY"], + }, + { + "name": "FAL.ai", + "tag": "FLUX 2 Pro with auto-upscaling", + "env_vars": [ + {"key": "FAL_KEY", "prompt": "FAL API key", "url": "https://fal.ai/dashboard/keys"}, + ], + }, + ], + }, + "browser": { + "name": "Browser Automation", + "icon": "🌐", + "providers": [ + { + "name": "Nous Subscription (Browser Use cloud)", + "tag": "Managed Browser Use billed to your subscription", + "env_vars": [], + "browser_provider": "browser-use", + "requires_nous_auth": True, + "managed_nous_feature": "browser", + "override_env_vars": ["BROWSER_USE_API_KEY"], + "post_setup": "agent_browser", + }, + { + "name": "Local Browser", + "tag": "Free headless Chromium (no API key needed)", + "env_vars": [], + "browser_provider": "local", + "post_setup": "agent_browser", + }, + { + "name": "Browserbase", + "tag": "Cloud browser with stealth & proxies", + "env_vars": [ + {"key": "BROWSERBASE_API_KEY", "prompt": "Browserbase API key", "url": "https://browserbase.com"}, + {"key": "BROWSERBASE_PROJECT_ID", "prompt": "Browserbase project ID"}, + ], + "browser_provider": "browserbase", + "post_setup": "agent_browser", + }, + { + "name": "Browser Use", + "tag": "Cloud browser with remote execution", + "env_vars": [ + {"key": "BROWSER_USE_API_KEY", "prompt": "Browser Use API key", "url": "https://browser-use.com"}, + ], + "browser_provider": "browser-use", + "post_setup": "agent_browser", + }, + { + "name": "Firecrawl", + "tag": "Cloud browser with remote execution", + "env_vars": [ + {"key": "FIRECRAWL_API_KEY", "prompt": "Firecrawl API key", "url": "https://firecrawl.dev"}, + ], + "browser_provider": "firecrawl", + "post_setup": "agent_browser", + }, + { + "name": "Camofox", + "tag": "Local anti-detection browser (Firefox/Camoufox)", + "env_vars": [ + {"key": "CAMOFOX_URL", "prompt": "Camofox server URL", "default": "http://localhost:9377", + "url": "https://github.com/jo-inc/camofox-browser"}, + ], + "browser_provider": "camofox", + "post_setup": "camofox", + }, + ], + }, + "homeassistant": { + "name": "Smart Home", + "icon": "🏠", + "providers": [ + { + "name": "Home Assistant", + "tag": "REST API integration", + "env_vars": [ + {"key": "HASS_TOKEN", "prompt": "Home Assistant Long-Lived Access Token"}, + {"key": "HASS_URL", "prompt": "Home Assistant URL", "default": "http://homeassistant.local:8123"}, + ], + }, + ], + }, + "rl": { + "name": "RL Training", + "icon": "🧪", + "requires_python": (3, 11), + "providers": [ + { + "name": "Tinker / Atropos", + "tag": "RL training platform", + "env_vars": [ + {"key": "TINKER_API_KEY", "prompt": "Tinker API key", "url": "https://tinker-console.thinkingmachines.ai/keys"}, + {"key": "WANDB_API_KEY", "prompt": "WandB API key", "url": "https://wandb.ai/authorize"}, + ], + "post_setup": "rl_training", + }, + ], + }, +} + +# Simple env-var requirements for toolsets NOT in TOOL_CATEGORIES. +# Used as a fallback for tools like vision/moa that just need an API key. +TOOLSET_ENV_REQUIREMENTS = { + "vision": [("OPENROUTER_API_KEY", "https://openrouter.ai/keys")], + "moa": [("OPENROUTER_API_KEY", "https://openrouter.ai/keys")], +} + + +# ─── Post-Setup Hooks ───────────────────────────────────────────────────────── + +def _run_post_setup(post_setup_key: str): + """Run post-setup hooks for tools that need extra installation steps.""" + import shutil + if post_setup_key in ("agent_browser", "browserbase"): + node_modules = PROJECT_ROOT / "node_modules" / "agent-browser" + if not node_modules.exists() and shutil.which("npm"): + _print_info(" Installing Node.js dependencies for browser tools...") + import subprocess + result = subprocess.run( + ["npm", "install", "--silent"], + capture_output=True, text=True, cwd=str(PROJECT_ROOT) + ) + if result.returncode == 0: + _print_success(" Node.js dependencies installed") + else: + from hermes_constants import display_hermes_home + _print_warning(f" npm install failed - run manually: cd {display_hermes_home()}/hermes-agent && npm install") + elif not node_modules.exists(): + _print_warning(" Node.js not found - browser tools require: npm install (in hermes-agent directory)") + + elif post_setup_key == "camofox": + camofox_dir = PROJECT_ROOT / "node_modules" / "@askjo" / "camoufox-browser" + if not camofox_dir.exists() and shutil.which("npm"): + _print_info(" Installing Camofox browser server...") + import subprocess + result = subprocess.run( + ["npm", "install", "--silent"], + capture_output=True, text=True, cwd=str(PROJECT_ROOT) + ) + if result.returncode == 0: + _print_success(" Camofox installed") + else: + _print_warning(" npm install failed - run manually: npm install") + if camofox_dir.exists(): + _print_info(" Start the Camofox server:") + _print_info(" npx @askjo/camoufox-browser") + _print_info(" First run downloads the Camoufox engine (~300MB)") + _print_info(" Or use Docker: docker run -p 9377:9377 -e CAMOFOX_PORT=9377 jo-inc/camofox-browser") + elif not shutil.which("npm"): + _print_warning(" Node.js not found. Install Camofox via Docker:") + _print_info(" docker run -p 9377:9377 -e CAMOFOX_PORT=9377 jo-inc/camofox-browser") + + elif post_setup_key == "rl_training": + try: + __import__("tinker_atropos") + except ImportError: + tinker_dir = PROJECT_ROOT / "tinker-atropos" + if tinker_dir.exists() and (tinker_dir / "pyproject.toml").exists(): + _print_info(" Installing tinker-atropos submodule...") + import subprocess + uv_bin = shutil.which("uv") + if uv_bin: + result = subprocess.run( + [uv_bin, "pip", "install", "--python", sys.executable, "-e", str(tinker_dir)], + capture_output=True, text=True + ) + else: + result = subprocess.run( + [sys.executable, "-m", "pip", "install", "-e", str(tinker_dir)], + capture_output=True, text=True + ) + if result.returncode == 0: + _print_success(" tinker-atropos installed") + else: + _print_warning(" tinker-atropos install failed - run manually:") + _print_info(' uv pip install -e "./tinker-atropos"') + else: + _print_warning(" tinker-atropos submodule not found - run:") + _print_info(" git submodule update --init --recursive") + _print_info(' uv pip install -e "./tinker-atropos"') + + +# ─── Platform / Toolset Helpers ─────────────────────────────────────────────── + +def _get_enabled_platforms() -> List[str]: + """Return platform keys that are configured (have tokens or are CLI).""" + enabled = ["cli"] + if get_env_value("TELEGRAM_BOT_TOKEN"): + enabled.append("telegram") + if get_env_value("DISCORD_BOT_TOKEN"): + enabled.append("discord") + if get_env_value("SLACK_BOT_TOKEN"): + enabled.append("slack") + if get_env_value("WHATSAPP_ENABLED"): + enabled.append("whatsapp") + if get_env_value("QQ_APP_ID"): + enabled.append("qqbot") + return enabled + + +def _platform_toolset_summary(config: dict, platforms: Optional[List[str]] = None) -> Dict[str, Set[str]]: + """Return a summary of enabled toolsets per platform. + + When ``platforms`` is None, this uses ``_get_enabled_platforms`` to + auto-detect platforms. Tests can pass an explicit list to avoid relying + on environment variables. + """ + if platforms is None: + platforms = _get_enabled_platforms() + + summary: Dict[str, Set[str]] = {} + for pkey in platforms: + summary[pkey] = _get_platform_tools(config, pkey) + return summary + + +def _parse_enabled_flag(value, default: bool = True) -> bool: + """Parse bool-like config values used by tool/platform settings.""" + if value is None: + return default + if isinstance(value, bool): + return value + if isinstance(value, int): + return value != 0 + if isinstance(value, str): + lowered = value.strip().lower() + if lowered in {"true", "1", "yes", "on"}: + return True + if lowered in {"false", "0", "no", "off"}: + return False + return default + + +def _get_platform_tools( + config: dict, + platform: str, + *, + include_default_mcp_servers: bool = True, +) -> Set[str]: + """Resolve which individual toolset names are enabled for a platform.""" + from toolsets import resolve_toolset + + platform_toolsets = config.get("platform_toolsets", {}) + toolset_names = platform_toolsets.get(platform) + + if toolset_names is None or not isinstance(toolset_names, list): + default_ts = PLATFORMS[platform]["default_toolset"] + toolset_names = [default_ts] + + # YAML may parse bare numeric names (e.g. ``12306:``) as int. + # Normalise to str so downstream sorted() never mixes types. + toolset_names = [str(ts) for ts in toolset_names] + + configurable_keys = {ts_key for ts_key, _, _ in CONFIGURABLE_TOOLSETS} + + # If the saved list contains any configurable keys directly, the user + # has explicitly configured this platform — use direct membership. + # This avoids the subset-inference bug where composite toolsets like + # "hermes-cli" (which include all _HERMES_CORE_TOOLS) cause disabled + # toolsets to re-appear as enabled. + has_explicit_config = any(ts in configurable_keys for ts in toolset_names) + + if has_explicit_config: + enabled_toolsets = {ts for ts in toolset_names if ts in configurable_keys} + else: + # No explicit config — fall back to resolving composite toolset names + # (e.g. "hermes-cli") to individual tool names and reverse-mapping. + all_tool_names = set() + for ts_name in toolset_names: + all_tool_names.update(resolve_toolset(ts_name)) + + enabled_toolsets = set() + for ts_key, _, _ in CONFIGURABLE_TOOLSETS: + ts_tools = set(resolve_toolset(ts_key)) + if ts_tools and ts_tools.issubset(all_tool_names): + enabled_toolsets.add(ts_key) + + # Plugin toolsets: enabled by default unless explicitly disabled. + # A plugin toolset is "known" for a platform once `hermes tools` + # has been saved for that platform (tracked via known_plugin_toolsets). + # Unknown plugins default to enabled; known-but-absent = disabled. + plugin_ts_keys = _get_plugin_toolset_keys() + if plugin_ts_keys: + known_map = config.get("known_plugin_toolsets", {}) + known_for_platform = set(known_map.get(platform, [])) + for pts in plugin_ts_keys: + if pts in toolset_names: + # Explicitly listed in config — enabled + enabled_toolsets.add(pts) + elif pts not in known_for_platform: + # New plugin not yet seen by hermes tools — default enabled + enabled_toolsets.add(pts) + # else: known but not in config = user disabled it + + # Preserve any explicit non-configurable toolset entries (for example, + # custom toolsets or MCP server names saved in platform_toolsets). + platform_default_keys = {p["default_toolset"] for p in PLATFORMS.values()} + explicit_passthrough = { + ts + for ts in toolset_names + if ts not in configurable_keys + and ts not in plugin_ts_keys + and ts not in platform_default_keys + } + + # MCP servers are expected to be available on all platforms by default. + # If the platform explicitly lists one or more MCP server names, treat that + # as an allowlist. Otherwise include every globally enabled MCP server. + # Special sentinel: "no_mcp" in the toolset list disables all MCP servers. + mcp_servers = config.get("mcp_servers") or {} + enabled_mcp_servers = { + str(name) + for name, server_cfg in mcp_servers.items() + if isinstance(server_cfg, dict) + and _parse_enabled_flag(server_cfg.get("enabled", True), default=True) + } + # Allow "no_mcp" sentinel to opt out of all MCP servers for this platform + if "no_mcp" in toolset_names: + explicit_mcp_servers = set() + enabled_toolsets.update(explicit_passthrough - enabled_mcp_servers - {"no_mcp"}) + else: + explicit_mcp_servers = explicit_passthrough & enabled_mcp_servers + enabled_toolsets.update(explicit_passthrough - enabled_mcp_servers) + if include_default_mcp_servers: + if explicit_mcp_servers or "no_mcp" in toolset_names: + enabled_toolsets.update(explicit_mcp_servers) + else: + enabled_toolsets.update(enabled_mcp_servers) + else: + enabled_toolsets.update(explicit_mcp_servers) + + return enabled_toolsets + + +def _save_platform_tools(config: dict, platform: str, enabled_toolset_keys: Set[str]): + """Save the selected toolset keys for a platform to config. + + Preserves any non-configurable toolset entries (like MCP server names) + that were already in the config for this platform. + """ + config.setdefault("platform_toolsets", {}) + + # Get the set of all configurable toolset keys (built-in + plugin) + configurable_keys = {ts_key for ts_key, _, _ in CONFIGURABLE_TOOLSETS} + plugin_keys = _get_plugin_toolset_keys() + configurable_keys |= plugin_keys + + # Also exclude platform default toolsets (hermes-cli, hermes-telegram, etc.) + # These are "super" toolsets that resolve to ALL tools, so preserving them + # would silently override the user's unchecked selections on the next read. + platform_default_keys = {p["default_toolset"] for p in PLATFORMS.values()} + + # Get existing toolsets for this platform + existing_toolsets = config.get("platform_toolsets", {}).get(platform, []) + if not isinstance(existing_toolsets, list): + existing_toolsets = [] + + # Preserve any entries that are NOT configurable toolsets and NOT platform + # defaults (i.e. only MCP server names should be preserved) + preserved_entries = { + entry for entry in existing_toolsets + if entry not in configurable_keys and entry not in platform_default_keys + } + + # Merge preserved entries with new enabled toolsets + config["platform_toolsets"][platform] = sorted(enabled_toolset_keys | preserved_entries) + + # Track which plugin toolsets are "known" for this platform so we can + # distinguish "new plugin, default enabled" from "user disabled it". + if plugin_keys: + config.setdefault("known_plugin_toolsets", {}) + config["known_plugin_toolsets"][platform] = sorted(plugin_keys) + + save_config(config) + + +def _toolset_has_keys(ts_key: str, config: dict = None) -> bool: + """Check if a toolset's required API keys are configured.""" + if config is None: + config = load_config() + + if ts_key == "vision": + try: + from agent.auxiliary_client import resolve_vision_provider_client + + _provider, client, _model = resolve_vision_provider_client() + return client is not None + except Exception: + return False + + if ts_key in {"web", "image_gen", "tts", "browser"}: + features = get_nous_subscription_features(config) + feature = features.features.get(ts_key) + if feature and (feature.available or feature.managed_by_nous): + return True + + # Check TOOL_CATEGORIES first (provider-aware) + cat = TOOL_CATEGORIES.get(ts_key) + if cat: + for provider in _visible_providers(cat, config): + env_vars = provider.get("env_vars", []) + if not env_vars: + return True # No-key provider (e.g. Local Browser, Edge TTS) + if all(get_env_value(e["key"]) for e in env_vars): + return True + return False + + # Fallback to simple requirements + requirements = TOOLSET_ENV_REQUIREMENTS.get(ts_key, []) + if not requirements: + return True + return all(get_env_value(var) for var, _ in requirements) + + +# ─── Menu Helpers ───────────────────────────────────────────────────────────── + +def _prompt_choice(question: str, choices: list, default: int = 0) -> int: + """Single-select menu (arrow keys). Delegates to curses_radiolist.""" + from hermes_cli.curses_ui import curses_radiolist + return curses_radiolist(question, choices, selected=default, cancel_returns=default) + + +# ─── Token Estimation ──────────────────────────────────────────────────────── + +# Module-level cache so discovery + tokenization runs at most once per process. +_tool_token_cache: Optional[Dict[str, int]] = None + + +def _estimate_tool_tokens() -> Dict[str, int]: + """Return estimated token counts per individual tool name. + + Uses tiktoken (cl100k_base) to count tokens in the JSON-serialised + OpenAI-format tool schema. Triggers tool discovery on first call, + then caches the result for the rest of the process. + + Returns an empty dict when tiktoken or the registry is unavailable. + """ + global _tool_token_cache + if _tool_token_cache is not None: + return _tool_token_cache + + try: + import tiktoken + enc = tiktoken.get_encoding("cl100k_base") + except Exception: + logger.debug("tiktoken unavailable; skipping tool token estimation") + _tool_token_cache = {} + return _tool_token_cache + + try: + # Trigger full tool discovery (imports all tool modules). + import model_tools # noqa: F401 + from tools.registry import registry + except Exception: + logger.debug("Tool registry unavailable; skipping token estimation") + _tool_token_cache = {} + return _tool_token_cache + + counts: Dict[str, int] = {} + for name in registry.get_all_tool_names(): + schema = registry.get_schema(name) + if schema: + # Mirror what gets sent to the API: + # {"type": "function", "function": } + text = _json.dumps({"type": "function", "function": schema}) + counts[name] = len(enc.encode(text)) + _tool_token_cache = counts + return _tool_token_cache + + +def _prompt_toolset_checklist(platform_label: str, enabled: Set[str]) -> Set[str]: + """Multi-select checklist of toolsets. Returns set of selected toolset keys.""" + from hermes_cli.curses_ui import curses_checklist + from toolsets import resolve_toolset + + # Pre-compute per-tool token counts (cached after first call). + tool_tokens = _estimate_tool_tokens() + + effective = _get_effective_configurable_toolsets() + + labels = [] + for ts_key, ts_label, ts_desc in effective: + suffix = "" + if not _toolset_has_keys(ts_key) and (TOOL_CATEGORIES.get(ts_key) or TOOLSET_ENV_REQUIREMENTS.get(ts_key)): + suffix = " [no API key]" + labels.append(f"{ts_label} ({ts_desc}){suffix}") + + pre_selected = { + i for i, (ts_key, _, _) in enumerate(effective) + if ts_key in enabled + } + + # Build a live status function that shows deduplicated total token cost. + status_fn = None + if tool_tokens: + ts_keys = [ts_key for ts_key, _, _ in effective] + + def status_fn(chosen: set) -> str: + # Collect unique tool names across all selected toolsets + all_tools: set = set() + for idx in chosen: + all_tools.update(resolve_toolset(ts_keys[idx])) + total = sum(tool_tokens.get(name, 0) for name in all_tools) + if total >= 1000: + return f"Est. tool context: ~{total / 1000:.1f}k tokens" + return f"Est. tool context: ~{total} tokens" + + chosen = curses_checklist( + f"Tools for {platform_label}", + labels, + pre_selected, + cancel_returns=pre_selected, + status_fn=status_fn, + ) + return {effective[i][0] for i in chosen} + + +# ─── Provider-Aware Configuration ──────────────────────────────────────────── + +def _configure_toolset(ts_key: str, config: dict): + """Configure a toolset - provider selection + API keys. + + Uses TOOL_CATEGORIES for provider-aware config, falls back to simple + env var prompts for toolsets not in TOOL_CATEGORIES. + """ + cat = TOOL_CATEGORIES.get(ts_key) + + if cat: + _configure_tool_category(ts_key, cat, config) + else: + # Simple fallback for vision, moa, etc. + _configure_simple_requirements(ts_key) + + +def _visible_providers(cat: dict, config: dict) -> list[dict]: + """Return provider entries visible for the current auth/config state.""" + features = get_nous_subscription_features(config) + visible = [] + for provider in cat.get("providers", []): + if provider.get("managed_nous_feature") and not managed_nous_tools_enabled(): + continue + if provider.get("requires_nous_auth") and not features.nous_auth_present: + continue + visible.append(provider) + return visible + + +def _toolset_needs_configuration_prompt(ts_key: str, config: dict) -> bool: + """Return True when enabling this toolset should open provider setup.""" + cat = TOOL_CATEGORIES.get(ts_key) + if not cat: + return not _toolset_has_keys(ts_key, config) + + if ts_key == "tts": + tts_cfg = config.get("tts", {}) + return not isinstance(tts_cfg, dict) or "provider" not in tts_cfg + if ts_key == "web": + web_cfg = config.get("web", {}) + return not isinstance(web_cfg, dict) or "backend" not in web_cfg + if ts_key == "browser": + browser_cfg = config.get("browser", {}) + return not isinstance(browser_cfg, dict) or "cloud_provider" not in browser_cfg + if ts_key == "image_gen": + return not get_env_value("FAL_KEY") + + return not _toolset_has_keys(ts_key, config) + + +def _configure_tool_category(ts_key: str, cat: dict, config: dict): + """Configure a tool category with provider selection.""" + icon = cat.get("icon", "") + name = cat["name"] + providers = _visible_providers(cat, config) + + # Check Python version requirement + if cat.get("requires_python"): + req = cat["requires_python"] + if sys.version_info < req: + print() + _print_error(f" {name} requires Python {req[0]}.{req[1]}+ (current: {sys.version_info.major}.{sys.version_info.minor})") + _print_info(" Upgrade Python and reinstall to enable this tool.") + return + + if len(providers) == 1: + # Single provider - configure directly + provider = providers[0] + print() + print(color(f" --- {icon} {name} ({provider['name']}) ---", Colors.CYAN)) + if provider.get("tag"): + _print_info(f" {provider['tag']}") + # For single-provider tools, show a note if available + if cat.get("setup_note"): + _print_info(f" {cat['setup_note']}") + _configure_provider(provider, config) + else: + # Multiple providers - let user choose + print() + # Use custom title if provided (e.g. "Select Search Provider") + title = cat.get("setup_title", "Choose a provider") + print(color(f" --- {icon} {name} - {title} ---", Colors.CYAN)) + if cat.get("setup_note"): + _print_info(f" {cat['setup_note']}") + print() + + # Plain text labels only (no ANSI codes in menu items) + provider_choices = [] + for p in providers: + tag = f" ({p['tag']})" if p.get("tag") else "" + configured = "" + env_vars = p.get("env_vars", []) + if not env_vars or all(get_env_value(v["key"]) for v in env_vars): + if _is_provider_active(p, config): + configured = " [active]" + elif not env_vars: + configured = "" + else: + configured = " [configured]" + provider_choices.append(f"{p['name']}{tag}{configured}") + + # Add skip option + provider_choices.append("Skip — keep defaults / configure later") + + # Detect current provider as default + default_idx = _detect_active_provider_index(providers, config) + + provider_idx = _prompt_choice(f" {title}:", provider_choices, default_idx) + + # Skip selected + if provider_idx >= len(providers): + _print_info(f" Skipped {name}") + return + + _configure_provider(providers[provider_idx], config) + + +def _is_provider_active(provider: dict, config: dict) -> bool: + """Check if a provider entry matches the currently active config.""" + managed_feature = provider.get("managed_nous_feature") + if managed_feature: + features = get_nous_subscription_features(config) + feature = features.features.get(managed_feature) + if feature is None: + return False + if managed_feature == "image_gen": + return feature.managed_by_nous + if provider.get("tts_provider"): + return ( + feature.managed_by_nous + and config.get("tts", {}).get("provider") == provider["tts_provider"] + ) + if "browser_provider" in provider: + current = config.get("browser", {}).get("cloud_provider") + return feature.managed_by_nous and provider["browser_provider"] == current + if provider.get("web_backend"): + current = config.get("web", {}).get("backend") + return feature.managed_by_nous and current == provider["web_backend"] + return feature.managed_by_nous + + if provider.get("tts_provider"): + return config.get("tts", {}).get("provider") == provider["tts_provider"] + if "browser_provider" in provider: + current = config.get("browser", {}).get("cloud_provider") + return provider["browser_provider"] == current + if provider.get("web_backend"): + current = config.get("web", {}).get("backend") + return current == provider["web_backend"] + return False + + +def _detect_active_provider_index(providers: list, config: dict) -> int: + """Return the index of the currently active provider, or 0.""" + for i, p in enumerate(providers): + if _is_provider_active(p, config): + return i + # Fallback: env vars present → likely configured + env_vars = p.get("env_vars", []) + if env_vars and all(get_env_value(v["key"]) for v in env_vars): + return i + return 0 + + +def _configure_provider(provider: dict, config: dict): + """Configure a single provider - prompt for API keys and set config.""" + env_vars = provider.get("env_vars", []) + managed_feature = provider.get("managed_nous_feature") + + if provider.get("requires_nous_auth"): + features = get_nous_subscription_features(config) + if not features.nous_auth_present: + _print_warning(" Nous Subscription is only available after logging into Nous Portal.") + return + + # Set TTS provider in config if applicable + if provider.get("tts_provider"): + config.setdefault("tts", {})["provider"] = provider["tts_provider"] + + # Set browser cloud provider in config if applicable + if "browser_provider" in provider: + bp = provider["browser_provider"] + if bp == "local": + config.setdefault("browser", {})["cloud_provider"] = "local" + _print_success(" Browser set to local mode") + elif bp: + config.setdefault("browser", {})["cloud_provider"] = bp + _print_success(f" Browser cloud provider set to: {bp}") + + # Set web search backend in config if applicable + if provider.get("web_backend"): + config.setdefault("web", {})["backend"] = provider["web_backend"] + _print_success(f" Web backend set to: {provider['web_backend']}") + + if not env_vars: + if provider.get("post_setup"): + _run_post_setup(provider["post_setup"]) + _print_success(f" {provider['name']} - no configuration needed!") + if managed_feature: + _print_info(" Requests for this tool will be billed to your Nous subscription.") + override_envs = provider.get("override_env_vars", []) + if any(get_env_value(env_var) for env_var in override_envs): + _print_warning( + " Direct credentials are still configured and may take precedence until you remove them from ~/.hermes/.env." + ) + return + + # Prompt for each required env var + all_configured = True + for var in env_vars: + existing = get_env_value(var["key"]) + if existing: + _print_success(f" {var['key']}: already configured") + # Don't ask to update - this is a new enable flow. + # Reconfigure is handled separately. + else: + url = var.get("url", "") + if url: + _print_info(f" Get yours at: {url}") + + default_val = var.get("default", "") + if default_val: + value = _prompt(f" {var.get('prompt', var['key'])}", default_val) + else: + value = _prompt(f" {var.get('prompt', var['key'])}", password=True) + + if value: + save_env_value(var["key"], value) + _print_success(" Saved") + else: + _print_warning(" Skipped") + all_configured = False + + # Run post-setup hooks if needed + if provider.get("post_setup") and all_configured: + _run_post_setup(provider["post_setup"]) + + if all_configured: + _print_success(f" {provider['name']} configured!") + + +def _configure_simple_requirements(ts_key: str): + """Simple fallback for toolsets that just need env vars (no provider selection).""" + if ts_key == "vision": + if _toolset_has_keys("vision"): + return + print() + print(color(" Vision / Image Analysis requires a multimodal backend:", Colors.YELLOW)) + choices = [ + "OpenRouter — uses Gemini", + "OpenAI-compatible endpoint — base URL, API key, and vision model", + "Skip", + ] + idx = _prompt_choice(" Configure vision backend", choices, 2) + if idx == 0: + _print_info(" Get key at: https://openrouter.ai/keys") + value = _prompt(" OPENROUTER_API_KEY", password=True) + if value and value.strip(): + save_env_value("OPENROUTER_API_KEY", value.strip()) + _print_success(" Saved") + else: + _print_warning(" Skipped") + elif idx == 1: + base_url = _prompt(" OPENAI_BASE_URL (blank for OpenAI)").strip() or "https://api.openai.com/v1" + key_label = " OPENAI_API_KEY" if "api.openai.com" in base_url.lower() else " API key" + api_key = _prompt(key_label, password=True) + if api_key and api_key.strip(): + save_env_value("OPENAI_API_KEY", api_key.strip()) + # Save vision base URL to config (not .env — only secrets go there) + from hermes_cli.config import load_config, save_config + _cfg = load_config() + _aux = _cfg.setdefault("auxiliary", {}).setdefault("vision", {}) + _aux["base_url"] = base_url + save_config(_cfg) + if "api.openai.com" in base_url.lower(): + save_env_value("AUXILIARY_VISION_MODEL", "gpt-4o-mini") + _print_success(" Saved") + else: + _print_warning(" Skipped") + return + + requirements = TOOLSET_ENV_REQUIREMENTS.get(ts_key, []) + if not requirements: + return + + missing = [(var, url) for var, url in requirements if not get_env_value(var)] + if not missing: + return + + ts_label = next((l for k, l, _ in _get_effective_configurable_toolsets() if k == ts_key), ts_key) + print() + print(color(f" {ts_label} requires configuration:", Colors.YELLOW)) + + for var, url in missing: + if url: + _print_info(f" Get key at: {url}") + value = _prompt(f" {var}", password=True) + if value and value.strip(): + save_env_value(var, value.strip()) + _print_success(" Saved") + else: + _print_warning(" Skipped") + + +def _reconfigure_tool(config: dict): + """Let user reconfigure an existing tool's provider or API key.""" + # Build list of configurable tools that are currently set up + configurable = [] + for ts_key, ts_label, _ in _get_effective_configurable_toolsets(): + cat = TOOL_CATEGORIES.get(ts_key) + reqs = TOOLSET_ENV_REQUIREMENTS.get(ts_key) + if cat or reqs: + if _toolset_has_keys(ts_key, config): + configurable.append((ts_key, ts_label)) + + if not configurable: + _print_info("No configured tools to reconfigure.") + return + + choices = [label for _, label in configurable] + choices.append("Cancel") + + idx = _prompt_choice(" Which tool would you like to reconfigure?", choices, len(choices) - 1) + + if idx >= len(configurable): + return # Cancel + + ts_key, ts_label = configurable[idx] + cat = TOOL_CATEGORIES.get(ts_key) + + if cat: + _configure_tool_category_for_reconfig(ts_key, cat, config) + else: + _reconfigure_simple_requirements(ts_key) + + save_config(config) + + +def _configure_tool_category_for_reconfig(ts_key: str, cat: dict, config: dict): + """Reconfigure a tool category - provider selection + API key update.""" + icon = cat.get("icon", "") + name = cat["name"] + providers = _visible_providers(cat, config) + + if len(providers) == 1: + provider = providers[0] + print() + print(color(f" --- {icon} {name} ({provider['name']}) ---", Colors.CYAN)) + _reconfigure_provider(provider, config) + else: + print() + print(color(f" --- {icon} {name} - Choose a provider ---", Colors.CYAN)) + print() + + provider_choices = [] + for p in providers: + tag = f" ({p['tag']})" if p.get("tag") else "" + configured = "" + env_vars = p.get("env_vars", []) + if not env_vars or all(get_env_value(v["key"]) for v in env_vars): + if _is_provider_active(p, config): + configured = " [active]" + elif not env_vars: + configured = "" + else: + configured = " [configured]" + provider_choices.append(f"{p['name']}{tag}{configured}") + + default_idx = _detect_active_provider_index(providers, config) + + provider_idx = _prompt_choice(" Select provider:", provider_choices, default_idx) + _reconfigure_provider(providers[provider_idx], config) + + +def _reconfigure_provider(provider: dict, config: dict): + """Reconfigure a provider - update API keys.""" + env_vars = provider.get("env_vars", []) + managed_feature = provider.get("managed_nous_feature") + + if provider.get("requires_nous_auth"): + features = get_nous_subscription_features(config) + if not features.nous_auth_present: + _print_warning(" Nous Subscription is only available after logging into Nous Portal.") + return + + if provider.get("tts_provider"): + config.setdefault("tts", {})["provider"] = provider["tts_provider"] + _print_success(f" TTS provider set to: {provider['tts_provider']}") + + if "browser_provider" in provider: + bp = provider["browser_provider"] + if bp == "local": + config.setdefault("browser", {})["cloud_provider"] = "local" + _print_success(" Browser set to local mode") + elif bp: + config.setdefault("browser", {})["cloud_provider"] = bp + _print_success(f" Browser cloud provider set to: {bp}") + + # Set web search backend in config if applicable + if provider.get("web_backend"): + config.setdefault("web", {})["backend"] = provider["web_backend"] + _print_success(f" Web backend set to: {provider['web_backend']}") + + if not env_vars: + if provider.get("post_setup"): + _run_post_setup(provider["post_setup"]) + _print_success(f" {provider['name']} - no configuration needed!") + if managed_feature: + _print_info(" Requests for this tool will be billed to your Nous subscription.") + override_envs = provider.get("override_env_vars", []) + if any(get_env_value(env_var) for env_var in override_envs): + _print_warning( + " Direct credentials are still configured and may take precedence until you remove them from ~/.hermes/.env." + ) + return + + for var in env_vars: + existing = get_env_value(var["key"]) + if existing: + _print_info(f" {var['key']}: configured ({existing[:8]}...)") + url = var.get("url", "") + if url: + _print_info(f" Get yours at: {url}") + default_val = var.get("default", "") + value = _prompt(f" {var.get('prompt', var['key'])} (Enter to keep current)", password=not default_val) + if value and value.strip(): + save_env_value(var["key"], value.strip()) + _print_success(" Updated") + else: + _print_info(" Kept current") + + +def _reconfigure_simple_requirements(ts_key: str): + """Reconfigure simple env var requirements.""" + requirements = TOOLSET_ENV_REQUIREMENTS.get(ts_key, []) + if not requirements: + return + + ts_label = next((l for k, l, _ in _get_effective_configurable_toolsets() if k == ts_key), ts_key) + print() + print(color(f" {ts_label}:", Colors.CYAN)) + + for var, url in requirements: + existing = get_env_value(var) + if existing: + _print_info(f" {var}: configured ({existing[:8]}...)") + if url: + _print_info(f" Get key at: {url}") + value = _prompt(f" {var} (Enter to keep current)", password=True) + if value and value.strip(): + save_env_value(var, value.strip()) + _print_success(" Updated") + else: + _print_info(" Kept current") + + +# ─── Main Entry Point ───────────────────────────────────────────────────────── + +def tools_command(args=None, first_install: bool = False, config: dict = None): + """Entry point for `hermes tools` and `hermes setup tools`. + + Args: + first_install: When True (set by the setup wizard on fresh installs), + skip the platform menu, go straight to the CLI checklist, and + prompt for API keys on all enabled tools that need them. + config: Optional config dict to use. When called from the setup + wizard, the wizard passes its own dict so that platform_toolsets + are written into it and survive the wizard's final save_config(). + """ + if config is None: + config = load_config() + enabled_platforms = _get_enabled_platforms() + + print() + + # Non-interactive summary mode for CLI usage + if getattr(args, "summary", False): + total = len(_get_effective_configurable_toolsets()) + print(color("⚕ Tool Summary", Colors.CYAN, Colors.BOLD)) + print() + summary = _platform_toolset_summary(config, enabled_platforms) + for pkey in enabled_platforms: + pinfo = PLATFORMS[pkey] + enabled = summary.get(pkey, set()) + count = len(enabled) + print(color(f" {pinfo['label']}", Colors.BOLD) + color(f" ({count}/{total})", Colors.DIM)) + if enabled: + for ts_key in sorted(enabled): + label = next((l for k, l, _ in _get_effective_configurable_toolsets() if k == ts_key), ts_key) + print(color(f" ✓ {label}", Colors.GREEN)) + else: + print(color(" (none enabled)", Colors.DIM)) + print() + return + print(color("⚕ Hermes Tool Configuration", Colors.CYAN, Colors.BOLD)) + print(color(" Enable or disable tools per platform.", Colors.DIM)) + print(color(" Tools that need API keys will be configured when enabled.", Colors.DIM)) + print(color(" Guide: https://hermes-agent.nousresearch.com/docs/user-guide/features/tools", Colors.DIM)) + print() + + # ── First-time install: linear flow, no platform menu ── + if first_install: + for pkey in enabled_platforms: + pinfo = PLATFORMS[pkey] + current_enabled = _get_platform_tools(config, pkey, include_default_mcp_servers=False) + + # Uncheck toolsets that should be off by default + checklist_preselected = current_enabled - _DEFAULT_OFF_TOOLSETS + + # Show checklist + new_enabled = _prompt_toolset_checklist(pinfo["label"], checklist_preselected) + + added = new_enabled - current_enabled + removed = current_enabled - new_enabled + if added: + for ts in sorted(added): + label = next((l for k, l, _ in _get_effective_configurable_toolsets() if k == ts), ts) + print(color(f" + {label}", Colors.GREEN)) + if removed: + for ts in sorted(removed): + label = next((l for k, l, _ in _get_effective_configurable_toolsets() if k == ts), ts) + print(color(f" - {label}", Colors.RED)) + + auto_configured = apply_nous_managed_defaults( + config, + enabled_toolsets=new_enabled, + ) + if managed_nous_tools_enabled(): + for ts_key in sorted(auto_configured): + label = next((l for k, l, _ in CONFIGURABLE_TOOLSETS if k == ts_key), ts_key) + print(color(f" ✓ {label}: using your Nous subscription defaults", Colors.GREEN)) + + # Walk through ALL selected tools that have provider options or + # need API keys. This ensures browser (Local vs Browserbase), + # TTS (Edge vs OpenAI vs ElevenLabs), etc. are shown even when + # a free provider exists. + to_configure = [ + ts_key for ts_key in sorted(new_enabled) + if (TOOL_CATEGORIES.get(ts_key) or TOOLSET_ENV_REQUIREMENTS.get(ts_key)) + and ts_key not in auto_configured + ] + + if to_configure: + print() + print(color(f" Configuring {len(to_configure)} tool(s):", Colors.YELLOW)) + for ts_key in to_configure: + label = next((l for k, l, _ in _get_effective_configurable_toolsets() if k == ts_key), ts_key) + print(color(f" • {label}", Colors.DIM)) + print(color(" You can skip any tool you don't need right now.", Colors.DIM)) + print() + for ts_key in to_configure: + _configure_toolset(ts_key, config) + + _save_platform_tools(config, pkey, new_enabled) + save_config(config) + print(color(f" ✓ Saved {pinfo['label']} tool configuration", Colors.GREEN)) + print() + + return + + # ── Returning user: platform menu loop ── + # Build platform choices + platform_choices = [] + platform_keys = [] + for pkey in enabled_platforms: + pinfo = PLATFORMS[pkey] + current = _get_platform_tools(config, pkey, include_default_mcp_servers=False) + count = len(current) + total = len(_get_effective_configurable_toolsets()) + platform_choices.append(f"Configure {pinfo['label']} ({count}/{total} enabled)") + platform_keys.append(pkey) + + if len(platform_keys) > 1: + platform_choices.append("Configure all platforms (global)") + platform_choices.append("Reconfigure an existing tool's provider or API key") + + # Show MCP option if any MCP servers are configured + _has_mcp = bool(config.get("mcp_servers")) + if _has_mcp: + platform_choices.append("Configure MCP server tools") + + platform_choices.append("Done") + + # Index offsets for the extra options after per-platform entries + _global_idx = len(platform_keys) if len(platform_keys) > 1 else -1 + _reconfig_idx = len(platform_keys) + (1 if len(platform_keys) > 1 else 0) + _mcp_idx = (_reconfig_idx + 1) if _has_mcp else -1 + _done_idx = _reconfig_idx + (2 if _has_mcp else 1) + + while True: + idx = _prompt_choice("Select an option:", platform_choices, default=0) + + # "Done" selected + if idx == _done_idx: + break + + # "Reconfigure" selected + if idx == _reconfig_idx: + _reconfigure_tool(config) + print() + continue + + # "Configure MCP tools" selected + if idx == _mcp_idx: + _configure_mcp_tools_interactive(config) + print() + continue + + # "Configure all platforms (global)" selected + if idx == _global_idx: + # Use the union of all platforms' current tools as the starting state + all_current = set() + for pk in platform_keys: + all_current |= _get_platform_tools(config, pk, include_default_mcp_servers=False) + new_enabled = _prompt_toolset_checklist("All platforms", all_current) + if new_enabled != all_current: + for pk in platform_keys: + prev = _get_platform_tools(config, pk, include_default_mcp_servers=False) + added = new_enabled - prev + removed = prev - new_enabled + pinfo_inner = PLATFORMS[pk] + if added or removed: + print(color(f" {pinfo_inner['label']}:", Colors.DIM)) + for ts in sorted(added): + label = next((l for k, l, _ in _get_effective_configurable_toolsets() if k == ts), ts) + print(color(f" + {label}", Colors.GREEN)) + for ts in sorted(removed): + label = next((l for k, l, _ in _get_effective_configurable_toolsets() if k == ts), ts) + print(color(f" - {label}", Colors.RED)) + # Configure API keys for newly enabled tools + for ts_key in sorted(added): + if (TOOL_CATEGORIES.get(ts_key) or TOOLSET_ENV_REQUIREMENTS.get(ts_key)): + if _toolset_needs_configuration_prompt(ts_key, config): + _configure_toolset(ts_key, config) + _save_platform_tools(config, pk, new_enabled) + save_config(config) + print(color(" ✓ Saved configuration for all platforms", Colors.GREEN)) + # Update choice labels + for ci, pk in enumerate(platform_keys): + new_count = len(_get_platform_tools(config, pk, include_default_mcp_servers=False)) + total = len(_get_effective_configurable_toolsets()) + platform_choices[ci] = f"Configure {PLATFORMS[pk]['label']} ({new_count}/{total} enabled)" + else: + print(color(" No changes", Colors.DIM)) + print() + continue + + pkey = platform_keys[idx] + pinfo = PLATFORMS[pkey] + + # Get current enabled toolsets for this platform + current_enabled = _get_platform_tools(config, pkey, include_default_mcp_servers=False) + + # Show checklist + new_enabled = _prompt_toolset_checklist(pinfo["label"], current_enabled) + + if new_enabled != current_enabled: + added = new_enabled - current_enabled + removed = current_enabled - new_enabled + + if added: + for ts in sorted(added): + label = next((l for k, l, _ in _get_effective_configurable_toolsets() if k == ts), ts) + print(color(f" + {label}", Colors.GREEN)) + if removed: + for ts in sorted(removed): + label = next((l for k, l, _ in _get_effective_configurable_toolsets() if k == ts), ts) + print(color(f" - {label}", Colors.RED)) + + # Configure newly enabled toolsets that need API keys + for ts_key in sorted(added): + if (TOOL_CATEGORIES.get(ts_key) or TOOLSET_ENV_REQUIREMENTS.get(ts_key)): + if _toolset_needs_configuration_prompt(ts_key, config): + _configure_toolset(ts_key, config) + + _save_platform_tools(config, pkey, new_enabled) + save_config(config) + print(color(f" ✓ Saved {pinfo['label']} configuration", Colors.GREEN)) + else: + print(color(f" No changes to {pinfo['label']}", Colors.DIM)) + + print() + + # Update the choice label with new count + new_count = len(_get_platform_tools(config, pkey, include_default_mcp_servers=False)) + total = len(_get_effective_configurable_toolsets()) + platform_choices[idx] = f"Configure {pinfo['label']} ({new_count}/{total} enabled)" + + print() + from hermes_constants import display_hermes_home + print(color(f" Tool configuration saved to {display_hermes_home()}/config.yaml", Colors.DIM)) + print(color(" Changes take effect on next 'hermes' or gateway restart.", Colors.DIM)) + print() + + +# ─── MCP Tools Interactive Configuration ───────────────────────────────────── + + +def _configure_mcp_tools_interactive(config: dict): + """Probe MCP servers for available tools and let user toggle them on/off. + + Connects to each configured MCP server, discovers tools, then shows + a per-server curses checklist. Writes changes back as ``tools.exclude`` + entries in config.yaml. + """ + from hermes_cli.curses_ui import curses_checklist + + mcp_servers = config.get("mcp_servers") or {} + if not mcp_servers: + _print_info("No MCP servers configured.") + return + + # Count enabled servers + enabled_names = [ + k for k, v in mcp_servers.items() + if v.get("enabled", True) not in (False, "false", "0", "no", "off") + ] + if not enabled_names: + _print_info("All MCP servers are disabled.") + return + + print() + print(color(" Discovering tools from MCP servers...", Colors.YELLOW)) + print(color(f" Connecting to {len(enabled_names)} server(s): {', '.join(enabled_names)}", Colors.DIM)) + + try: + from tools.mcp_tool import probe_mcp_server_tools + server_tools = probe_mcp_server_tools() + except Exception as exc: + _print_error(f"Failed to probe MCP servers: {exc}") + return + + if not server_tools: + _print_warning("Could not discover tools from any MCP server.") + _print_info("Check that server commands/URLs are correct and dependencies are installed.") + return + + # Report discovery results + failed = [n for n in enabled_names if n not in server_tools] + if failed: + for name in failed: + _print_warning(f" Could not connect to '{name}'") + + total_tools = sum(len(tools) for tools in server_tools.values()) + print(color(f" Found {total_tools} tool(s) across {len(server_tools)} server(s)", Colors.GREEN)) + print() + + any_changes = False + + for server_name, tools in server_tools.items(): + if not tools: + _print_info(f" {server_name}: no tools found") + continue + + srv_cfg = mcp_servers.get(server_name, {}) + tools_cfg = srv_cfg.get("tools") or {} + include_list = tools_cfg.get("include") or [] + exclude_list = tools_cfg.get("exclude") or [] + + # Build checklist labels + labels = [] + for tool_name, description in tools: + desc_short = description[:70] + "..." if len(description) > 70 else description + if desc_short: + labels.append(f"{tool_name} ({desc_short})") + else: + labels.append(tool_name) + + # Determine which tools are currently enabled + pre_selected: Set[int] = set() + tool_names = [t[0] for t in tools] + for i, tool_name in enumerate(tool_names): + if include_list: + # Include mode: only included tools are selected + if tool_name in include_list: + pre_selected.add(i) + elif exclude_list: + # Exclude mode: everything except excluded + if tool_name not in exclude_list: + pre_selected.add(i) + else: + # No filter: all enabled + pre_selected.add(i) + + chosen = curses_checklist( + f"MCP Server: {server_name} ({len(tools)} tools)", + labels, + pre_selected, + cancel_returns=pre_selected, + ) + + if chosen == pre_selected: + _print_info(f" {server_name}: no changes") + continue + + # Compute new exclude list based on unchecked tools + new_exclude = [tool_names[i] for i in range(len(tool_names)) if i not in chosen] + + # Update config + srv_cfg = mcp_servers.setdefault(server_name, {}) + tools_cfg = srv_cfg.setdefault("tools", {}) + + if new_exclude: + tools_cfg["exclude"] = new_exclude + # Remove include if present — we're switching to exclude mode + tools_cfg.pop("include", None) + else: + # All tools enabled — clear filters + tools_cfg.pop("exclude", None) + tools_cfg.pop("include", None) + + enabled_count = len(chosen) + disabled_count = len(tools) - enabled_count + _print_success( + f" {server_name}: {enabled_count} enabled, {disabled_count} disabled" + ) + any_changes = True + + if any_changes: + save_config(config) + print() + print(color(" ✓ MCP tool configuration saved", Colors.GREEN)) + else: + print(color(" No changes to MCP tools", Colors.DIM)) + + +# ─── Non-interactive disable/enable ────────────────────────────────────────── + + +def _apply_toolset_change(config: dict, platform: str, toolset_names: List[str], action: str): + """Add or remove built-in toolsets for a platform.""" + enabled = _get_platform_tools(config, platform, include_default_mcp_servers=False) + if action == "disable": + updated = enabled - set(toolset_names) + else: + updated = enabled | set(toolset_names) + _save_platform_tools(config, platform, updated) + + +def _apply_mcp_change(config: dict, targets: List[str], action: str) -> Set[str]: + """Add or remove specific MCP tools from a server's exclude list. + + Returns the set of server names that were not found in config. + """ + failed_servers: Set[str] = set() + mcp_servers = config.get("mcp_servers") or {} + + for target in targets: + server_name, tool_name = target.split(":", 1) + if server_name not in mcp_servers: + failed_servers.add(server_name) + continue + tools_cfg = mcp_servers[server_name].setdefault("tools", {}) + exclude = list(tools_cfg.get("exclude") or []) + if action == "disable": + if tool_name not in exclude: + exclude.append(tool_name) + else: + exclude = [t for t in exclude if t != tool_name] + tools_cfg["exclude"] = exclude + + return failed_servers + + +def _print_tools_list(enabled_toolsets: set, mcp_servers: dict, platform: str = "cli"): + """Print a summary of enabled/disabled toolsets and MCP tool filters.""" + effective = _get_effective_configurable_toolsets() + builtin_keys = {ts_key for ts_key, _, _ in CONFIGURABLE_TOOLSETS} + + print(f"Built-in toolsets ({platform}):") + for ts_key, label, _ in effective: + if ts_key not in builtin_keys: + continue + status = (color("✓ enabled", Colors.GREEN) if ts_key in enabled_toolsets + else color("✗ disabled", Colors.RED)) + print(f" {status} {ts_key} {color(label, Colors.DIM)}") + + # Plugin toolsets + plugin_entries = [(k, l) for k, l, _ in effective if k not in builtin_keys] + if plugin_entries: + print() + print(f"Plugin toolsets ({platform}):") + for ts_key, label in plugin_entries: + status = (color("✓ enabled", Colors.GREEN) if ts_key in enabled_toolsets + else color("✗ disabled", Colors.RED)) + print(f" {status} {ts_key} {color(label, Colors.DIM)}") + + if mcp_servers: + print() + print("MCP servers:") + for srv_name, srv_cfg in mcp_servers.items(): + tools_cfg = srv_cfg.get("tools") or {} + exclude = tools_cfg.get("exclude") or [] + include = tools_cfg.get("include") or [] + if include: + _print_info(f"{srv_name} [include only: {', '.join(include)}]") + elif exclude: + _print_info(f"{srv_name} [excluded: {color(', '.join(exclude), Colors.YELLOW)}]") + else: + _print_info(f"{srv_name} {color('all tools enabled', Colors.DIM)}") + + +def tools_disable_enable_command(args): + """Enable, disable, or list tools for a platform. + + Built-in toolsets use plain names (e.g. ``web``, ``memory``). + MCP tools use ``server:tool`` notation (e.g. ``github:create_issue``). + """ + action = args.tools_action + platform = getattr(args, "platform", "cli") + config = load_config() + + if platform not in PLATFORMS: + _print_error(f"Unknown platform '{platform}'. Valid: {', '.join(PLATFORMS)}") + return + + if action == "list": + _print_tools_list(_get_platform_tools(config, platform, include_default_mcp_servers=False), + config.get("mcp_servers") or {}, platform) + return + + targets: List[str] = args.names + toolset_targets = [t for t in targets if ":" not in t] + mcp_targets = [t for t in targets if ":" in t] + + valid_toolsets = {ts_key for ts_key, _, _ in CONFIGURABLE_TOOLSETS} | _get_plugin_toolset_keys() + unknown_toolsets = [t for t in toolset_targets if t not in valid_toolsets] + if unknown_toolsets: + for name in unknown_toolsets: + _print_error(f"Unknown toolset '{name}'") + toolset_targets = [t for t in toolset_targets if t in valid_toolsets] + + if toolset_targets: + _apply_toolset_change(config, platform, toolset_targets, action) + + failed_servers: Set[str] = set() + if mcp_targets: + failed_servers = _apply_mcp_change(config, mcp_targets, action) + for srv in failed_servers: + _print_error(f"MCP server '{srv}' not found in config") + + save_config(config) + + successful = [ + t for t in targets + if t not in unknown_toolsets and (":" not in t or t.split(":")[0] not in failed_servers) + ] + if successful: + verb = "Disabled" if action == "disable" else "Enabled" + _print_success(f"{verb}: {', '.join(successful)}") diff --git a/mindcli/_vendor/hermes_cli/uninstall.py b/mindcli/_vendor/hermes_cli/uninstall.py new file mode 100644 index 0000000..8d8e339 --- /dev/null +++ b/mindcli/_vendor/hermes_cli/uninstall.py @@ -0,0 +1,326 @@ +""" +Hermes Agent Uninstaller. + +Provides options for: +- Full uninstall: Remove everything including configs and data +- Keep data: Remove code but keep ~/.hermes/ (configs, sessions, logs) +""" + +import os +import shutil +import subprocess +from pathlib import Path + +from hermes_constants import get_hermes_home + +from hermes_cli.colors import Colors, color + +def log_info(msg: str): + print(f"{color('→', Colors.CYAN)} {msg}") + +def log_success(msg: str): + print(f"{color('✓', Colors.GREEN)} {msg}") + +def log_warn(msg: str): + print(f"{color('⚠', Colors.YELLOW)} {msg}") + +def get_project_root() -> Path: + """Get the project installation directory.""" + return Path(__file__).parent.parent.resolve() + + +def find_shell_configs() -> list: + """Find shell configuration files that might have PATH entries.""" + home = Path.home() + configs = [] + + candidates = [ + home / ".bashrc", + home / ".bash_profile", + home / ".profile", + home / ".zshrc", + home / ".zprofile", + ] + + for config in candidates: + if config.exists(): + configs.append(config) + + return configs + + +def remove_path_from_shell_configs(): + """Remove Hermes PATH entries from shell configuration files.""" + configs = find_shell_configs() + removed_from = [] + + for config_path in configs: + try: + content = config_path.read_text() + original_content = content + + # Remove lines containing hermes-agent or hermes PATH entries + new_lines = [] + skip_next = False + + for line in content.split('\n'): + # Skip the "# Hermes Agent" comment and following line + if '# Hermes Agent' in line or '# hermes-agent' in line: + skip_next = True + continue + if skip_next and ('hermes' in line.lower() and 'PATH' in line): + skip_next = False + continue + skip_next = False + + # Remove any PATH line containing hermes + if 'hermes' in line.lower() and ('PATH=' in line or 'path=' in line.lower()): + continue + + new_lines.append(line) + + new_content = '\n'.join(new_lines) + + # Clean up multiple blank lines + while '\n\n\n' in new_content: + new_content = new_content.replace('\n\n\n', '\n\n') + + if new_content != original_content: + config_path.write_text(new_content) + removed_from.append(config_path) + + except Exception as e: + log_warn(f"Could not update {config_path}: {e}") + + return removed_from + + +def remove_wrapper_script(): + """Remove the hermes wrapper script if it exists.""" + wrapper_paths = [ + Path.home() / ".local" / "bin" / "hermes", + Path("/usr/local/bin/hermes"), + ] + + removed = [] + for wrapper in wrapper_paths: + if wrapper.exists(): + try: + # Check if it's our wrapper (contains hermes_cli reference) + content = wrapper.read_text() + if 'hermes_cli' in content or 'hermes-agent' in content: + wrapper.unlink() + removed.append(wrapper) + except Exception as e: + log_warn(f"Could not remove {wrapper}: {e}") + + return removed + + +def uninstall_gateway_service(): + """Stop and uninstall the gateway service if running.""" + import platform + + if platform.system() != "Linux": + return False + + prefix = os.getenv("PREFIX", "") + if os.getenv("TERMUX_VERSION") or "com.termux/files/usr" in prefix: + return False + + try: + from hermes_cli.gateway import get_service_name + svc_name = get_service_name() + except Exception: + svc_name = "hermes-gateway" + + service_file = Path.home() / ".config" / "systemd" / "user" / f"{svc_name}.service" + + if not service_file.exists(): + return False + + try: + # Stop the service + subprocess.run( + ["systemctl", "--user", "stop", svc_name], + capture_output=True, + check=False + ) + + # Disable the service + subprocess.run( + ["systemctl", "--user", "disable", svc_name], + capture_output=True, + check=False + ) + + # Remove service file + service_file.unlink() + + # Reload systemd + subprocess.run( + ["systemctl", "--user", "daemon-reload"], + capture_output=True, + check=False + ) + + return True + + except Exception as e: + log_warn(f"Could not fully remove gateway service: {e}") + return False + + +def run_uninstall(args): + """ + Run the uninstall process. + + Options: + - Full uninstall: removes code + ~/.hermes/ (configs, data, logs) + - Keep data: removes code but keeps ~/.hermes/ for future reinstall + """ + project_root = get_project_root() + hermes_home = get_hermes_home() + + print() + print(color("┌─────────────────────────────────────────────────────────┐", Colors.MAGENTA, Colors.BOLD)) + print(color("│ ⚕ Hermes Agent Uninstaller │", Colors.MAGENTA, Colors.BOLD)) + print(color("└─────────────────────────────────────────────────────────┘", Colors.MAGENTA, Colors.BOLD)) + print() + + # Show what will be affected + print(color("Current Installation:", Colors.CYAN, Colors.BOLD)) + print(f" Code: {project_root}") + print(f" Config: {hermes_home / 'config.yaml'}") + print(f" Secrets: {hermes_home / '.env'}") + print(f" Data: {hermes_home / 'cron/'}, {hermes_home / 'sessions/'}, {hermes_home / 'logs/'}") + print() + + # Ask for confirmation + print(color("Uninstall Options:", Colors.YELLOW, Colors.BOLD)) + print() + print(" 1) " + color("Keep data", Colors.GREEN) + " - Remove code only, keep configs/sessions/logs") + print(" (Recommended - you can reinstall later with your settings intact)") + print() + print(" 2) " + color("Full uninstall", Colors.RED) + " - Remove everything including all data") + print(" (Warning: This deletes all configs, sessions, and logs permanently)") + print() + print(" 3) " + color("Cancel", Colors.CYAN) + " - Don't uninstall") + print() + + try: + choice = input(color("Select option [1/2/3]: ", Colors.BOLD)).strip() + except (KeyboardInterrupt, EOFError): + print() + print("Cancelled.") + return + + if choice == "3" or choice.lower() in ("c", "cancel", "q", "quit", "n", "no"): + print() + print("Uninstall cancelled.") + return + + full_uninstall = (choice == "2") + + # Final confirmation + print() + if full_uninstall: + print(color("⚠️ WARNING: This will permanently delete ALL Hermes data!", Colors.RED, Colors.BOLD)) + print(color(" Including: configs, API keys, sessions, scheduled jobs, logs", Colors.RED)) + else: + print("This will remove the Hermes code but keep your configuration and data.") + + print() + try: + confirm = input(f"Type '{color('yes', Colors.YELLOW)}' to confirm: ").strip().lower() + except (KeyboardInterrupt, EOFError): + print() + print("Cancelled.") + return + + if confirm != "yes": + print() + print("Uninstall cancelled.") + return + + print() + print(color("Uninstalling...", Colors.CYAN, Colors.BOLD)) + print() + + # 1. Stop and uninstall gateway service + log_info("Checking for gateway service...") + if uninstall_gateway_service(): + log_success("Gateway service stopped and removed") + else: + log_info("No gateway service found") + + # 2. Remove PATH entries from shell configs + log_info("Removing PATH entries from shell configs...") + removed_configs = remove_path_from_shell_configs() + if removed_configs: + for config in removed_configs: + log_success(f"Updated {config}") + else: + log_info("No PATH entries found to remove") + + # 3. Remove wrapper script + log_info("Removing hermes command...") + removed_wrappers = remove_wrapper_script() + if removed_wrappers: + for wrapper in removed_wrappers: + log_success(f"Removed {wrapper}") + else: + log_info("No wrapper script found") + + # 4. Remove installation directory (code) + log_info("Removing installation directory...") + + # Check if we're running from within the install dir + # We need to be careful here + try: + if project_root.exists(): + # If the install is inside ~/.hermes/, just remove the hermes-agent subdir + if hermes_home in project_root.parents or project_root.parent == hermes_home: + shutil.rmtree(project_root) + log_success(f"Removed {project_root}") + else: + # Installation is somewhere else entirely + shutil.rmtree(project_root) + log_success(f"Removed {project_root}") + except Exception as e: + log_warn(f"Could not fully remove {project_root}: {e}") + log_info("You may need to manually remove it") + + # 5. Optionally remove ~/.hermes/ data directory + if full_uninstall: + log_info("Removing configuration and data...") + try: + if hermes_home.exists(): + shutil.rmtree(hermes_home) + log_success(f"Removed {hermes_home}") + except Exception as e: + log_warn(f"Could not fully remove {hermes_home}: {e}") + log_info("You may need to manually remove it") + else: + log_info(f"Keeping configuration and data in {hermes_home}") + + # Done + print() + print(color("┌─────────────────────────────────────────────────────────┐", Colors.GREEN, Colors.BOLD)) + print(color("│ ✓ Uninstall Complete! │", Colors.GREEN, Colors.BOLD)) + print(color("└─────────────────────────────────────────────────────────┘", Colors.GREEN, Colors.BOLD)) + print() + + if not full_uninstall: + print(color("Your configuration and data have been preserved:", Colors.CYAN)) + print(f" {hermes_home}/") + print() + print("To reinstall later with your existing settings:") + print(color(" curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash", Colors.DIM)) + print() + + print(color("Reload your shell to complete the process:", Colors.YELLOW)) + print(" source ~/.bashrc # or ~/.zshrc") + print() + print("Thank you for using Hermes Agent! ⚕") + print() diff --git a/mindcli/_vendor/hermes_cli/web_server.py b/mindcli/_vendor/hermes_cli/web_server.py new file mode 100644 index 0000000..f73104c --- /dev/null +++ b/mindcli/_vendor/hermes_cli/web_server.py @@ -0,0 +1,1990 @@ +""" +Hermes Agent — Web UI server. + +Provides a FastAPI backend serving the Vite/React frontend and REST API +endpoints for managing configuration, environment variables, and sessions. + +Usage: + python -m hermes_cli.main web # Start on http://127.0.0.1:9119 + python -m hermes_cli.main web --port 8080 +""" + +import asyncio +import json +import logging +import secrets +import sys +import threading +import time +import urllib.parse +import urllib.request +from pathlib import Path +from typing import Any, Dict, List, Optional + +import yaml + +PROJECT_ROOT = Path(__file__).parent.parent.resolve() +if str(PROJECT_ROOT) not in sys.path: + sys.path.insert(0, str(PROJECT_ROOT)) + +from hermes_cli import __version__, __release_date__ +from hermes_cli.config import ( + DEFAULT_CONFIG, + OPTIONAL_ENV_VARS, + get_config_path, + get_env_path, + get_hermes_home, + load_config, + load_env, + save_config, + save_env_value, + remove_env_value, + check_config_version, + redact_key, +) +from gateway.status import get_running_pid, read_runtime_status + +try: + from fastapi import FastAPI, HTTPException, Request + from fastapi.middleware.cors import CORSMiddleware + from fastapi.responses import FileResponse, JSONResponse + from fastapi.staticfiles import StaticFiles + from pydantic import BaseModel +except ImportError: + raise SystemExit( + "Web UI requires fastapi and uvicorn.\n" + "Run 'hermes web' to auto-install, or: pip install hermes-agent[web]" + ) + +WEB_DIST = Path(__file__).parent / "web_dist" +_log = logging.getLogger(__name__) + +app = FastAPI(title="Hermes Agent", version=__version__) + +# --------------------------------------------------------------------------- +# Session token for protecting sensitive endpoints (reveal). +# Generated fresh on every server start — dies when the process exits. +# Injected into the SPA HTML so only the legitimate web UI can use it. +# --------------------------------------------------------------------------- +_SESSION_TOKEN = secrets.token_urlsafe(32) + +# Simple rate limiter for the reveal endpoint +_reveal_timestamps: List[float] = [] +_REVEAL_MAX_PER_WINDOW = 5 +_REVEAL_WINDOW_SECONDS = 30 + +# CORS: restrict to localhost origins only. The web UI is intended to run +# locally; binding to 0.0.0.0 with allow_origins=["*"] would let any website +# read/modify config and secrets. + +app.add_middleware( + CORSMiddleware, + allow_origin_regex=r"^https?://(localhost|127\.0\.0\.1)(:\d+)?$", + allow_methods=["*"], + allow_headers=["*"], +) + + +# --------------------------------------------------------------------------- +# Config schema — auto-generated from DEFAULT_CONFIG +# --------------------------------------------------------------------------- + +# Manual overrides for fields that need select options or custom types +_SCHEMA_OVERRIDES: Dict[str, Dict[str, Any]] = { + "model": { + "type": "string", + "description": "Default model (e.g. anthropic/claude-sonnet-4.6)", + "category": "general", + }, + "model_context_length": { + "type": "number", + "description": "Context window override (0 = auto-detect from model metadata)", + "category": "general", + }, + "terminal.backend": { + "type": "select", + "description": "Terminal execution backend", + "options": ["local", "docker", "ssh", "modal", "daytona", "singularity"], + }, + "terminal.modal_mode": { + "type": "select", + "description": "Modal sandbox mode", + "options": ["sandbox", "function"], + }, + "tts.provider": { + "type": "select", + "description": "Text-to-speech provider", + "options": ["edge", "elevenlabs", "openai", "neutts"], + }, + "stt.provider": { + "type": "select", + "description": "Speech-to-text provider", + "options": ["local", "openai", "mistral"], + }, + "display.skin": { + "type": "select", + "description": "CLI visual theme", + "options": ["default", "ares", "mono", "slate"], + }, + "display.resume_display": { + "type": "select", + "description": "How resumed sessions display history", + "options": ["minimal", "full", "off"], + }, + "display.busy_input_mode": { + "type": "select", + "description": "Input behavior while agent is running", + "options": ["queue", "interrupt", "block"], + }, + "memory.provider": { + "type": "select", + "description": "Memory provider plugin", + "options": ["builtin", "honcho"], + }, + "approvals.mode": { + "type": "select", + "description": "Dangerous command approval mode", + "options": ["ask", "yolo", "deny"], + }, + "context.engine": { + "type": "select", + "description": "Context management engine", + "options": ["default", "custom"], + }, + "human_delay.mode": { + "type": "select", + "description": "Simulated typing delay mode", + "options": ["off", "typing", "fixed"], + }, + "logging.level": { + "type": "select", + "description": "Log level for agent.log", + "options": ["DEBUG", "INFO", "WARNING", "ERROR"], + }, + "agent.service_tier": { + "type": "select", + "description": "API service tier (OpenAI/Anthropic)", + "options": ["", "auto", "default", "flex"], + }, + "delegation.reasoning_effort": { + "type": "select", + "description": "Reasoning effort for delegated subagents", + "options": ["", "low", "medium", "high"], + }, +} + +# Categories with fewer fields get merged into "general" to avoid tab sprawl. +_CATEGORY_MERGE: Dict[str, str] = { + "privacy": "security", + "context": "agent", + "skills": "agent", + "cron": "agent", + "network": "agent", + "checkpoints": "agent", + "approvals": "security", + "human_delay": "display", + "smart_model_routing": "agent", +} + +# Display order for tabs — unlisted categories sort alphabetically after these. +_CATEGORY_ORDER = [ + "general", "agent", "terminal", "display", "delegation", + "memory", "compression", "security", "browser", "voice", + "tts", "stt", "logging", "discord", "auxiliary", +] + + +def _infer_type(value: Any) -> str: + """Infer a UI field type from a Python value.""" + if isinstance(value, bool): + return "boolean" + if isinstance(value, int): + return "number" + if isinstance(value, float): + return "number" + if isinstance(value, list): + return "list" + if isinstance(value, dict): + return "object" + return "string" + + +def _build_schema_from_config( + config: Dict[str, Any], + prefix: str = "", +) -> Dict[str, Dict[str, Any]]: + """Walk DEFAULT_CONFIG and produce a flat dot-path → field schema dict.""" + schema: Dict[str, Dict[str, Any]] = {} + for key, value in config.items(): + full_key = f"{prefix}.{key}" if prefix else key + + # Skip internal / version keys + if full_key in ("_config_version",): + continue + + # Category is the first path component for nested keys, or "general" + # for top-level scalar fields (model, toolsets, timezone, etc.). + if prefix: + category = prefix.split(".")[0] + elif isinstance(value, dict): + category = key + else: + category = "general" + + if isinstance(value, dict): + # Recurse into nested dicts + schema.update(_build_schema_from_config(value, full_key)) + else: + entry: Dict[str, Any] = { + "type": _infer_type(value), + "description": full_key.replace(".", " → ").replace("_", " ").title(), + "category": category, + } + # Apply manual overrides + if full_key in _SCHEMA_OVERRIDES: + entry.update(_SCHEMA_OVERRIDES[full_key]) + # Merge small categories + entry["category"] = _CATEGORY_MERGE.get(entry["category"], entry["category"]) + schema[full_key] = entry + return schema + + +CONFIG_SCHEMA = _build_schema_from_config(DEFAULT_CONFIG) + +# Inject virtual fields that don't live in DEFAULT_CONFIG but are surfaced +# by the normalize/denormalize cycle. Insert model_context_length right after +# the "model" key so it renders adjacent in the frontend. +_mcl_entry = _SCHEMA_OVERRIDES["model_context_length"] +_ordered_schema: Dict[str, Dict[str, Any]] = {} +for _k, _v in CONFIG_SCHEMA.items(): + _ordered_schema[_k] = _v + if _k == "model": + _ordered_schema["model_context_length"] = _mcl_entry +CONFIG_SCHEMA = _ordered_schema + + +class ConfigUpdate(BaseModel): + config: dict + + +class EnvVarUpdate(BaseModel): + key: str + value: str + + +class EnvVarDelete(BaseModel): + key: str + + +class EnvVarReveal(BaseModel): + key: str + + +@app.get("/api/status") +async def get_status(): + current_ver, latest_ver = check_config_version() + + gateway_pid = get_running_pid() + gateway_running = gateway_pid is not None + + gateway_state = None + gateway_platforms: dict = {} + gateway_exit_reason = None + gateway_updated_at = None + configured_gateway_platforms: set[str] | None = None + try: + from gateway.config import load_gateway_config + + gateway_config = load_gateway_config() + configured_gateway_platforms = { + platform.value for platform in gateway_config.get_connected_platforms() + } + except Exception: + configured_gateway_platforms = None + + runtime = read_runtime_status() + if runtime: + gateway_state = runtime.get("gateway_state") + gateway_platforms = runtime.get("platforms") or {} + if configured_gateway_platforms is not None: + gateway_platforms = { + key: value + for key, value in gateway_platforms.items() + if key in configured_gateway_platforms + } + gateway_exit_reason = runtime.get("exit_reason") + gateway_updated_at = runtime.get("updated_at") + if not gateway_running: + gateway_state = gateway_state if gateway_state in ("stopped", "startup_failed") else "stopped" + gateway_platforms = {} + + active_sessions = 0 + try: + from hermes_state import SessionDB + db = SessionDB() + try: + sessions = db.list_sessions_rich(limit=50) + now = time.time() + active_sessions = sum( + 1 for s in sessions + if s.get("ended_at") is None + and (now - s.get("last_active", s.get("started_at", 0))) < 300 + ) + finally: + db.close() + except Exception: + pass + + return { + "version": __version__, + "release_date": __release_date__, + "hermes_home": str(get_hermes_home()), + "config_path": str(get_config_path()), + "env_path": str(get_env_path()), + "config_version": current_ver, + "latest_config_version": latest_ver, + "gateway_running": gateway_running, + "gateway_pid": gateway_pid, + "gateway_state": gateway_state, + "gateway_platforms": gateway_platforms, + "gateway_exit_reason": gateway_exit_reason, + "gateway_updated_at": gateway_updated_at, + "active_sessions": active_sessions, + } + + +@app.get("/api/sessions") +async def get_sessions(limit: int = 20, offset: int = 0): + try: + from hermes_state import SessionDB + db = SessionDB() + try: + sessions = db.list_sessions_rich(limit=limit, offset=offset) + total = db.session_count() + now = time.time() + for s in sessions: + s["is_active"] = ( + s.get("ended_at") is None + and (now - s.get("last_active", s.get("started_at", 0))) < 300 + ) + return {"sessions": sessions, "total": total, "limit": limit, "offset": offset} + finally: + db.close() + except Exception as e: + _log.exception("GET /api/sessions failed") + raise HTTPException(status_code=500, detail="Internal server error") + + +@app.get("/api/sessions/search") +async def search_sessions(q: str = "", limit: int = 20): + """Full-text search across session message content using FTS5.""" + if not q or not q.strip(): + return {"results": []} + try: + from hermes_state import SessionDB + db = SessionDB() + try: + # Auto-add prefix wildcards so partial words match + # e.g. "nimb" → "nimb*" matches "nimby" + # Preserve quoted phrases and existing wildcards as-is + import re + terms = [] + for token in re.findall(r'"[^"]*"|\S+', q.strip()): + if token.startswith('"') or token.endswith("*"): + terms.append(token) + else: + terms.append(token + "*") + prefix_query = " ".join(terms) + matches = db.search_messages(query=prefix_query, limit=limit) + # Group by session_id — return unique sessions with their best snippet + seen: dict = {} + for m in matches: + sid = m["session_id"] + if sid not in seen: + seen[sid] = { + "session_id": sid, + "snippet": m.get("snippet", ""), + "role": m.get("role"), + "source": m.get("source"), + "model": m.get("model"), + "session_started": m.get("session_started"), + } + return {"results": list(seen.values())} + finally: + db.close() + except Exception: + _log.exception("GET /api/sessions/search failed") + raise HTTPException(status_code=500, detail="Search failed") + + +def _normalize_config_for_web(config: Dict[str, Any]) -> Dict[str, Any]: + """Normalize config for the web UI. + + Hermes supports ``model`` as either a bare string (``"anthropic/claude-sonnet-4"``) + or a dict (``{default: ..., provider: ..., base_url: ...}``). The schema is built + from DEFAULT_CONFIG where ``model`` is a string, but user configs often have the + dict form. Normalize to the string form so the frontend schema matches. + + Also surfaces ``model_context_length`` as a top-level field so the web UI can + display and edit it. A value of 0 means "auto-detect". + """ + config = dict(config) # shallow copy + model_val = config.get("model") + if isinstance(model_val, dict): + # Extract context_length before flattening the dict + ctx_len = model_val.get("context_length", 0) + config["model"] = model_val.get("default", model_val.get("name", "")) + config["model_context_length"] = ctx_len if isinstance(ctx_len, int) else 0 + else: + config["model_context_length"] = 0 + return config + + +@app.get("/api/config") +async def get_config(): + config = _normalize_config_for_web(load_config()) + # Strip internal keys that the frontend shouldn't see or send back + return {k: v for k, v in config.items() if not k.startswith("_")} + + +@app.get("/api/config/defaults") +async def get_defaults(): + return DEFAULT_CONFIG + + +@app.get("/api/config/schema") +async def get_schema(): + return {"fields": CONFIG_SCHEMA, "category_order": _CATEGORY_ORDER} + + +_EMPTY_MODEL_INFO: dict = { + "model": "", + "provider": "", + "auto_context_length": 0, + "config_context_length": 0, + "effective_context_length": 0, + "capabilities": {}, +} + + +@app.get("/api/model/info") +def get_model_info(): + """Return resolved model metadata for the currently configured model. + + Calls the same context-length resolution chain the agent uses, so the + frontend can display "Auto-detected: 200K" alongside the override field. + Also returns model capabilities (vision, reasoning, tools) when available. + """ + try: + cfg = load_config() + model_cfg = cfg.get("model", "") + + # Extract model name and provider from the config + if isinstance(model_cfg, dict): + model_name = model_cfg.get("default", model_cfg.get("name", "")) + provider = model_cfg.get("provider", "") + base_url = model_cfg.get("base_url", "") + config_ctx = model_cfg.get("context_length") + else: + model_name = str(model_cfg) if model_cfg else "" + provider = "" + base_url = "" + config_ctx = None + + if not model_name: + return dict(_EMPTY_MODEL_INFO, provider=provider) + + # Resolve auto-detected context length (pass config_ctx=None to get + # purely auto-detected value, then separately report the override) + try: + from agent.model_metadata import get_model_context_length + auto_ctx = get_model_context_length( + model=model_name, + base_url=base_url, + provider=provider, + config_context_length=None, # ignore override — we want auto value + ) + except Exception: + auto_ctx = 0 + + config_ctx_int = 0 + if isinstance(config_ctx, int) and config_ctx > 0: + config_ctx_int = config_ctx + + # Effective is what the agent actually uses + effective_ctx = config_ctx_int if config_ctx_int > 0 else auto_ctx + + # Try to get model capabilities from models.dev + caps = {} + try: + from agent.models_dev import get_model_capabilities + mc = get_model_capabilities(provider=provider, model=model_name) + if mc is not None: + caps = { + "supports_tools": mc.supports_tools, + "supports_vision": mc.supports_vision, + "supports_reasoning": mc.supports_reasoning, + "context_window": mc.context_window, + "max_output_tokens": mc.max_output_tokens, + "model_family": mc.model_family, + } + except Exception: + pass + + return { + "model": model_name, + "provider": provider, + "auto_context_length": auto_ctx, + "config_context_length": config_ctx_int, + "effective_context_length": effective_ctx, + "capabilities": caps, + } + except Exception: + _log.exception("GET /api/model/info failed") + return dict(_EMPTY_MODEL_INFO) + + +def _denormalize_config_from_web(config: Dict[str, Any]) -> Dict[str, Any]: + """Reverse _normalize_config_for_web before saving. + + Reconstructs ``model`` as a dict by reading the current on-disk config + to recover model subkeys (provider, base_url, api_mode, etc.) that were + stripped from the GET response. The frontend only sees model as a flat + string; the rest is preserved transparently. + + Also handles ``model_context_length`` — writes it back into the model dict + as ``context_length``. A value of 0 or absent means "auto-detect" (omitted + from the dict so get_model_context_length() uses its normal resolution). + """ + config = dict(config) + # Remove any _model_meta that might have leaked in (shouldn't happen + # with the stripped GET response, but be defensive) + config.pop("_model_meta", None) + + # Extract and remove model_context_length before processing model + ctx_override = config.pop("model_context_length", 0) + if not isinstance(ctx_override, int): + try: + ctx_override = int(ctx_override) + except (TypeError, ValueError): + ctx_override = 0 + + model_val = config.get("model") + if isinstance(model_val, str) and model_val: + # Read the current disk config to recover model subkeys + try: + disk_config = load_config() + disk_model = disk_config.get("model") + if isinstance(disk_model, dict): + # Preserve all subkeys, update default with the new value + disk_model["default"] = model_val + # Write context_length into the model dict (0 = remove/auto) + if ctx_override > 0: + disk_model["context_length"] = ctx_override + else: + disk_model.pop("context_length", None) + config["model"] = disk_model + else: + # Model was previously a bare string — upgrade to dict if + # user is setting a context_length override + if ctx_override > 0: + config["model"] = { + "default": model_val, + "context_length": ctx_override, + } + except Exception: + pass # can't read disk config — just use the string form + return config + + +@app.put("/api/config") +async def update_config(body: ConfigUpdate): + try: + save_config(_denormalize_config_from_web(body.config)) + return {"ok": True} + except Exception as e: + _log.exception("PUT /api/config failed") + raise HTTPException(status_code=500, detail="Internal server error") + + +@app.get("/api/auth/session-token") +async def get_session_token(): + """Return the ephemeral session token for this server instance. + + The token protects sensitive endpoints (reveal). It's served to the SPA + which stores it in memory — it's never persisted and dies when the server + process exits. CORS already restricts this to localhost origins. + """ + return {"token": _SESSION_TOKEN} + + +@app.get("/api/env") +async def get_env_vars(): + env_on_disk = load_env() + result = {} + for var_name, info in OPTIONAL_ENV_VARS.items(): + value = env_on_disk.get(var_name) + result[var_name] = { + "is_set": bool(value), + "redacted_value": redact_key(value) if value else None, + "description": info.get("description", ""), + "url": info.get("url"), + "category": info.get("category", ""), + "is_password": info.get("password", False), + "tools": info.get("tools", []), + "advanced": info.get("advanced", False), + } + return result + + +@app.put("/api/env") +async def set_env_var(body: EnvVarUpdate): + try: + save_env_value(body.key, body.value) + return {"ok": True, "key": body.key} + except Exception as e: + _log.exception("PUT /api/env failed") + raise HTTPException(status_code=500, detail="Internal server error") + + +@app.delete("/api/env") +async def remove_env_var(body: EnvVarDelete): + try: + removed = remove_env_value(body.key) + if not removed: + raise HTTPException(status_code=404, detail=f"{body.key} not found in .env") + return {"ok": True, "key": body.key} + except HTTPException: + raise + except Exception as e: + _log.exception("DELETE /api/env failed") + raise HTTPException(status_code=500, detail="Internal server error") + + +@app.post("/api/env/reveal") +async def reveal_env_var(body: EnvVarReveal, request: Request): + """Return the real (unredacted) value of a single env var. + + Protected by: + - Ephemeral session token (generated per server start, injected into SPA) + - Rate limiting (max 5 reveals per 30s window) + - Audit logging + """ + # --- Token check --- + auth = request.headers.get("authorization", "") + if auth != f"Bearer {_SESSION_TOKEN}": + raise HTTPException(status_code=401, detail="Unauthorized") + + # --- Rate limit --- + now = time.time() + cutoff = now - _REVEAL_WINDOW_SECONDS + _reveal_timestamps[:] = [t for t in _reveal_timestamps if t > cutoff] + if len(_reveal_timestamps) >= _REVEAL_MAX_PER_WINDOW: + raise HTTPException(status_code=429, detail="Too many reveal requests. Try again shortly.") + _reveal_timestamps.append(now) + + # --- Reveal --- + env_on_disk = load_env() + value = env_on_disk.get(body.key) + if value is None: + raise HTTPException(status_code=404, detail=f"{body.key} not found in .env") + + _log.info("env/reveal: %s", body.key) + return {"key": body.key, "value": value} + + +# --------------------------------------------------------------------------- +# OAuth provider endpoints — status + disconnect (Phase 1) +# --------------------------------------------------------------------------- +# +# Phase 1 surfaces *which OAuth providers exist* and whether each is +# connected, plus a disconnect button. The actual login flow (PKCE for +# Anthropic, device-code for Nous/Codex) still runs in the CLI for now; +# Phase 2 will add in-browser flows. For unconnected providers we return +# the canonical ``hermes auth add `` command so the dashboard +# can surface a one-click copy. + + +def _truncate_token(value: Optional[str], visible: int = 6) -> str: + """Return ``...XXXXXX`` (last N chars) for safe display in the UI. + + We never expose more than the trailing ``visible`` characters of an + OAuth access token. JWT prefixes (the part before the first dot) are + stripped first when present so the visible suffix is always part of + the signing region rather than a meaningless header chunk. + """ + if not value: + return "" + s = str(value) + if "." in s and s.count(".") >= 2: + # Looks like a JWT — show the trailing piece of the signature only. + s = s.rsplit(".", 1)[-1] + if len(s) <= visible: + return s + return f"…{s[-visible:]}" + + +def _anthropic_oauth_status() -> Dict[str, Any]: + """Combined status across the three Anthropic credential sources we read. + + Hermes resolves Anthropic creds in this order at runtime: + 1. ``~/.hermes/.anthropic_oauth.json`` — Hermes-managed PKCE flow + 2. ``~/.claude/.credentials.json`` — Claude Code CLI credentials (auto) + 3. ``ANTHROPIC_TOKEN`` / ``ANTHROPIC_API_KEY`` env vars + The dashboard reports the highest-priority source that's actually present. + """ + try: + from agent.anthropic_adapter import ( + read_hermes_oauth_credentials, + read_claude_code_credentials, + _HERMES_OAUTH_FILE, + ) + except ImportError: + read_claude_code_credentials = None # type: ignore + read_hermes_oauth_credentials = None # type: ignore + _HERMES_OAUTH_FILE = None # type: ignore + + hermes_creds = None + if read_hermes_oauth_credentials: + try: + hermes_creds = read_hermes_oauth_credentials() + except Exception: + hermes_creds = None + if hermes_creds and hermes_creds.get("accessToken"): + return { + "logged_in": True, + "source": "hermes_pkce", + "source_label": f"Hermes PKCE ({_HERMES_OAUTH_FILE})", + "token_preview": _truncate_token(hermes_creds.get("accessToken")), + "expires_at": hermes_creds.get("expiresAt"), + "has_refresh_token": bool(hermes_creds.get("refreshToken")), + } + + cc_creds = None + if read_claude_code_credentials: + try: + cc_creds = read_claude_code_credentials() + except Exception: + cc_creds = None + if cc_creds and cc_creds.get("accessToken"): + return { + "logged_in": True, + "source": "claude_code", + "source_label": "Claude Code (~/.claude/.credentials.json)", + "token_preview": _truncate_token(cc_creds.get("accessToken")), + "expires_at": cc_creds.get("expiresAt"), + "has_refresh_token": bool(cc_creds.get("refreshToken")), + } + + env_token = os.getenv("ANTHROPIC_TOKEN") or os.getenv("CLAUDE_CODE_OAUTH_TOKEN") + if env_token: + return { + "logged_in": True, + "source": "env_var", + "source_label": "ANTHROPIC_TOKEN environment variable", + "token_preview": _truncate_token(env_token), + "expires_at": None, + "has_refresh_token": False, + } + return {"logged_in": False, "source": None} + + +def _claude_code_only_status() -> Dict[str, Any]: + """Surface Claude Code CLI credentials as their own provider entry. + + Independent of the Anthropic entry above so users can see whether their + Claude Code subscription tokens are actively flowing into Hermes even + when they also have a separate Hermes-managed PKCE login. + """ + try: + from agent.anthropic_adapter import read_claude_code_credentials + creds = read_claude_code_credentials() + except Exception: + creds = None + if creds and creds.get("accessToken"): + return { + "logged_in": True, + "source": "claude_code_cli", + "source_label": "~/.claude/.credentials.json", + "token_preview": _truncate_token(creds.get("accessToken")), + "expires_at": creds.get("expiresAt"), + "has_refresh_token": bool(creds.get("refreshToken")), + } + return {"logged_in": False, "source": None} + + +# Provider catalog. The order matters — it's how we render the UI list. +# ``cli_command`` is what the dashboard surfaces as the copy-to-clipboard +# fallback while Phase 2 (in-browser flows) isn't built yet. +# ``flow`` describes the OAuth shape so the future modal can pick the +# right UI: ``pkce`` = open URL + paste callback code, ``device_code`` = +# show code + verification URL + poll, ``external`` = read-only (delegated +# to a third-party CLI like Claude Code or Qwen). +_OAUTH_PROVIDER_CATALOG: tuple[Dict[str, Any], ...] = ( + { + "id": "anthropic", + "name": "Anthropic (Claude API)", + "flow": "pkce", + "cli_command": "hermes auth add anthropic", + "docs_url": "https://docs.claude.com/en/api/getting-started", + "status_fn": _anthropic_oauth_status, + }, + { + "id": "claude-code", + "name": "Claude Code (subscription)", + "flow": "external", + "cli_command": "claude setup-token", + "docs_url": "https://docs.claude.com/en/docs/claude-code", + "status_fn": _claude_code_only_status, + }, + { + "id": "nous", + "name": "Nous Portal", + "flow": "device_code", + "cli_command": "hermes auth add nous", + "docs_url": "https://portal.nousresearch.com", + "status_fn": None, # dispatched via auth.get_nous_auth_status + }, + { + "id": "openai-codex", + "name": "OpenAI Codex (ChatGPT)", + "flow": "device_code", + "cli_command": "hermes auth add openai-codex", + "docs_url": "https://platform.openai.com/docs", + "status_fn": None, # dispatched via auth.get_codex_auth_status + }, + { + "id": "qwen-oauth", + "name": "Qwen (via Qwen CLI)", + "flow": "external", + "cli_command": "hermes auth add qwen-oauth", + "docs_url": "https://github.com/QwenLM/qwen-code", + "status_fn": None, # dispatched via auth.get_qwen_auth_status + }, +) + + +def _resolve_provider_status(provider_id: str, status_fn) -> Dict[str, Any]: + """Dispatch to the right status helper for an OAuth provider entry.""" + if status_fn is not None: + try: + return status_fn() + except Exception as e: + return {"logged_in": False, "error": str(e)} + try: + from hermes_cli import auth as hauth + if provider_id == "nous": + raw = hauth.get_nous_auth_status() + return { + "logged_in": bool(raw.get("logged_in")), + "source": "nous_portal", + "source_label": raw.get("portal_base_url") or "Nous Portal", + "token_preview": _truncate_token(raw.get("access_token")), + "expires_at": raw.get("access_expires_at"), + "has_refresh_token": bool(raw.get("has_refresh_token")), + } + if provider_id == "openai-codex": + raw = hauth.get_codex_auth_status() + return { + "logged_in": bool(raw.get("logged_in")), + "source": raw.get("source") or "openai_codex", + "source_label": raw.get("auth_mode") or "OpenAI Codex", + "token_preview": _truncate_token(raw.get("api_key")), + "expires_at": None, + "has_refresh_token": False, + "last_refresh": raw.get("last_refresh"), + } + if provider_id == "qwen-oauth": + raw = hauth.get_qwen_auth_status() + return { + "logged_in": bool(raw.get("logged_in")), + "source": "qwen_cli", + "source_label": raw.get("auth_store_path") or "Qwen CLI", + "token_preview": _truncate_token(raw.get("access_token")), + "expires_at": raw.get("expires_at"), + "has_refresh_token": bool(raw.get("has_refresh_token")), + } + except Exception as e: + return {"logged_in": False, "error": str(e)} + return {"logged_in": False} + + +@app.get("/api/providers/oauth") +async def list_oauth_providers(): + """Enumerate every OAuth-capable LLM provider with current status. + + Response shape (per provider): + id stable identifier (used in DELETE path) + name human label + flow "pkce" | "device_code" | "external" + cli_command fallback CLI command for users to run manually + docs_url external docs/portal link for the "Learn more" link + status: + logged_in bool — currently has usable creds + source short slug ("hermes_pkce", "claude_code", ...) + source_label human-readable origin (file path, env var name) + token_preview last N chars of the token, never the full token + expires_at ISO timestamp string or null + has_refresh_token bool + """ + providers = [] + for p in _OAUTH_PROVIDER_CATALOG: + status = _resolve_provider_status(p["id"], p.get("status_fn")) + providers.append({ + "id": p["id"], + "name": p["name"], + "flow": p["flow"], + "cli_command": p["cli_command"], + "docs_url": p["docs_url"], + "status": status, + }) + return {"providers": providers} + + +@app.delete("/api/providers/oauth/{provider_id}") +async def disconnect_oauth_provider(provider_id: str, request: Request): + """Disconnect an OAuth provider. Token-protected (matches /env/reveal).""" + auth = request.headers.get("authorization", "") + if auth != f"Bearer {_SESSION_TOKEN}": + raise HTTPException(status_code=401, detail="Unauthorized") + + valid_ids = {p["id"] for p in _OAUTH_PROVIDER_CATALOG} + if provider_id not in valid_ids: + raise HTTPException( + status_code=400, + detail=f"Unknown provider: {provider_id}. " + f"Available: {', '.join(sorted(valid_ids))}", + ) + + # Anthropic and claude-code clear the same Hermes-managed PKCE file + # AND forget the Claude Code import. We don't touch ~/.claude/* directly + # — that's owned by the Claude Code CLI; users can re-auth there if they + # want to undo a disconnect. + if provider_id in ("anthropic", "claude-code"): + try: + from agent.anthropic_adapter import _HERMES_OAUTH_FILE + if _HERMES_OAUTH_FILE.exists(): + _HERMES_OAUTH_FILE.unlink() + except Exception: + pass + # Also clear the credential pool entry if present. + try: + from hermes_cli.auth import clear_provider_auth + clear_provider_auth("anthropic") + except Exception: + pass + _log.info("oauth/disconnect: %s", provider_id) + return {"ok": True, "provider": provider_id} + + try: + from hermes_cli.auth import clear_provider_auth + cleared = clear_provider_auth(provider_id) + _log.info("oauth/disconnect: %s (cleared=%s)", provider_id, cleared) + return {"ok": bool(cleared), "provider": provider_id} + except Exception as e: + _log.exception("disconnect %s failed", provider_id) + raise HTTPException(status_code=500, detail=str(e)) + + +# --------------------------------------------------------------------------- +# OAuth Phase 2 — in-browser PKCE & device-code flows +# --------------------------------------------------------------------------- +# +# Two flow shapes are supported: +# +# PKCE (Anthropic): +# 1. POST /api/providers/oauth/anthropic/start +# → server generates code_verifier + challenge, builds claude.ai +# authorize URL, stashes verifier in _oauth_sessions[session_id] +# → returns { session_id, flow: "pkce", auth_url } +# 2. UI opens auth_url in a new tab. User authorizes, copies code. +# 3. POST /api/providers/oauth/anthropic/submit { session_id, code } +# → server exchanges (code + verifier) → tokens at console.anthropic.com +# → persists to ~/.hermes/.anthropic_oauth.json AND credential pool +# → returns { ok: true, status: "approved" } +# +# Device code (Nous, OpenAI Codex): +# 1. POST /api/providers/oauth/{nous|openai-codex}/start +# → server hits provider's device-auth endpoint +# → gets { user_code, verification_url, device_code, interval, expires_in } +# → spawns background poller thread that polls the token endpoint +# every `interval` seconds until approved/expired +# → stores poll status in _oauth_sessions[session_id] +# → returns { session_id, flow: "device_code", user_code, +# verification_url, expires_in, poll_interval } +# 2. UI opens verification_url in a new tab and shows user_code. +# 3. UI polls GET /api/providers/oauth/{provider}/poll/{session_id} +# every 2s until status != "pending". +# 4. On "approved" the background thread has already saved creds; UI +# refreshes the providers list. +# +# Sessions are kept in-memory only (single-process FastAPI) and time out +# after 15 minutes. A periodic cleanup runs on each /start call to GC +# expired sessions so the dict doesn't grow without bound. + +_OAUTH_SESSION_TTL_SECONDS = 15 * 60 +_oauth_sessions: Dict[str, Dict[str, Any]] = {} +_oauth_sessions_lock = threading.Lock() + +# Import OAuth constants from canonical source instead of duplicating. +# Guarded so hermes web still starts if anthropic_adapter is unavailable; +# Phase 2 endpoints will return 501 in that case. +try: + from agent.anthropic_adapter import ( + _OAUTH_CLIENT_ID as _ANTHROPIC_OAUTH_CLIENT_ID, + _OAUTH_TOKEN_URL as _ANTHROPIC_OAUTH_TOKEN_URL, + _OAUTH_REDIRECT_URI as _ANTHROPIC_OAUTH_REDIRECT_URI, + _OAUTH_SCOPES as _ANTHROPIC_OAUTH_SCOPES, + _generate_pkce as _generate_pkce_pair, + ) + _ANTHROPIC_OAUTH_AVAILABLE = True +except ImportError: + _ANTHROPIC_OAUTH_AVAILABLE = False +_ANTHROPIC_OAUTH_AUTHORIZE_URL = "https://claude.ai/oauth/authorize" + + +def _gc_oauth_sessions() -> None: + """Drop expired sessions. Called opportunistically on /start.""" + cutoff = time.time() - _OAUTH_SESSION_TTL_SECONDS + with _oauth_sessions_lock: + stale = [sid for sid, sess in _oauth_sessions.items() if sess["created_at"] < cutoff] + for sid in stale: + _oauth_sessions.pop(sid, None) + + +def _new_oauth_session(provider_id: str, flow: str) -> tuple[str, Dict[str, Any]]: + """Create + register a new OAuth session, return (session_id, session_dict).""" + sid = secrets.token_urlsafe(16) + sess = { + "session_id": sid, + "provider": provider_id, + "flow": flow, + "created_at": time.time(), + "status": "pending", # pending | approved | denied | expired | error + "error_message": None, + } + with _oauth_sessions_lock: + _oauth_sessions[sid] = sess + return sid, sess + + +def _save_anthropic_oauth_creds(access_token: str, refresh_token: str, expires_at_ms: int) -> None: + """Persist Anthropic PKCE creds to both Hermes file AND credential pool. + + Mirrors what auth_commands.add_command does so the dashboard flow leaves + the system in the same state as ``hermes auth add anthropic``. + """ + from agent.anthropic_adapter import _HERMES_OAUTH_FILE + payload = { + "accessToken": access_token, + "refreshToken": refresh_token, + "expiresAt": expires_at_ms, + } + _HERMES_OAUTH_FILE.parent.mkdir(parents=True, exist_ok=True) + _HERMES_OAUTH_FILE.write_text(json.dumps(payload, indent=2), encoding="utf-8") + # Best-effort credential-pool insert. Failure here doesn't invalidate + # the file write — pool registration only matters for the rotation + # strategy, not for runtime credential resolution. + try: + from agent.credential_pool import ( + PooledCredential, + load_pool, + AUTH_TYPE_OAUTH, + SOURCE_MANUAL, + ) + import uuid + pool = load_pool("anthropic") + # Avoid duplicate entries: delete any prior dashboard-issued OAuth entry + existing = [e for e in pool.entries() if getattr(e, "source", "").startswith(f"{SOURCE_MANUAL}:dashboard_pkce")] + for e in existing: + try: + pool.remove_entry(getattr(e, "id", "")) + except Exception: + pass + entry = PooledCredential( + provider="anthropic", + id=uuid.uuid4().hex[:6], + label="dashboard PKCE", + auth_type=AUTH_TYPE_OAUTH, + priority=0, + source=f"{SOURCE_MANUAL}:dashboard_pkce", + access_token=access_token, + refresh_token=refresh_token, + expires_at_ms=expires_at_ms, + ) + pool.add_entry(entry) + except Exception as e: + _log.warning("anthropic pool add (dashboard) failed: %s", e) + + +def _start_anthropic_pkce() -> Dict[str, Any]: + """Begin PKCE flow. Returns the auth URL the UI should open.""" + if not _ANTHROPIC_OAUTH_AVAILABLE: + raise HTTPException(status_code=501, detail="Anthropic OAuth not available (missing adapter)") + verifier, challenge = _generate_pkce_pair() + sid, sess = _new_oauth_session("anthropic", "pkce") + sess["verifier"] = verifier + sess["state"] = verifier # Anthropic round-trips verifier as state + params = { + "code": "true", + "client_id": _ANTHROPIC_OAUTH_CLIENT_ID, + "response_type": "code", + "redirect_uri": _ANTHROPIC_OAUTH_REDIRECT_URI, + "scope": _ANTHROPIC_OAUTH_SCOPES, + "code_challenge": challenge, + "code_challenge_method": "S256", + "state": verifier, + } + auth_url = f"{_ANTHROPIC_OAUTH_AUTHORIZE_URL}?{urllib.parse.urlencode(params)}" + return { + "session_id": sid, + "flow": "pkce", + "auth_url": auth_url, + "expires_in": _OAUTH_SESSION_TTL_SECONDS, + } + + +def _submit_anthropic_pkce(session_id: str, code_input: str) -> Dict[str, Any]: + """Exchange authorization code for tokens. Persists on success.""" + with _oauth_sessions_lock: + sess = _oauth_sessions.get(session_id) + if not sess or sess["provider"] != "anthropic" or sess["flow"] != "pkce": + raise HTTPException(status_code=404, detail="Unknown or expired session") + if sess["status"] != "pending": + return {"ok": False, "status": sess["status"], "message": sess.get("error_message")} + + # Anthropic's redirect callback page formats the code as `#`. + # Strip the state suffix if present (we already have the verifier server-side). + parts = code_input.strip().split("#", 1) + code = parts[0].strip() + if not code: + return {"ok": False, "status": "error", "message": "No code provided"} + state_from_callback = parts[1] if len(parts) > 1 else "" + + exchange_data = json.dumps({ + "grant_type": "authorization_code", + "client_id": _ANTHROPIC_OAUTH_CLIENT_ID, + "code": code, + "state": state_from_callback or sess["state"], + "redirect_uri": _ANTHROPIC_OAUTH_REDIRECT_URI, + "code_verifier": sess["verifier"], + }).encode() + req = urllib.request.Request( + _ANTHROPIC_OAUTH_TOKEN_URL, + data=exchange_data, + headers={ + "Content-Type": "application/json", + "User-Agent": "hermes-dashboard/1.0", + }, + method="POST", + ) + try: + with urllib.request.urlopen(req, timeout=20) as resp: + result = json.loads(resp.read().decode()) + except Exception as e: + sess["status"] = "error" + sess["error_message"] = f"Token exchange failed: {e}" + return {"ok": False, "status": "error", "message": sess["error_message"]} + + access_token = result.get("access_token", "") + refresh_token = result.get("refresh_token", "") + expires_in = int(result.get("expires_in") or 3600) + if not access_token: + sess["status"] = "error" + sess["error_message"] = "No access token returned" + return {"ok": False, "status": "error", "message": sess["error_message"]} + + expires_at_ms = int(time.time() * 1000) + (expires_in * 1000) + try: + _save_anthropic_oauth_creds(access_token, refresh_token, expires_at_ms) + except Exception as e: + sess["status"] = "error" + sess["error_message"] = f"Save failed: {e}" + return {"ok": False, "status": "error", "message": sess["error_message"]} + sess["status"] = "approved" + _log.info("oauth/pkce: anthropic login completed (session=%s)", session_id) + return {"ok": True, "status": "approved"} + + +async def _start_device_code_flow(provider_id: str) -> Dict[str, Any]: + """Initiate a device-code flow (Nous or OpenAI Codex). + + Calls the provider's device-auth endpoint via the existing CLI helpers, + then spawns a background poller. Returns the user-facing display fields + so the UI can render the verification page link + user code. + """ + from hermes_cli import auth as hauth + if provider_id == "nous": + from hermes_cli.auth import _request_device_code, PROVIDER_REGISTRY + import httpx + pconfig = PROVIDER_REGISTRY["nous"] + portal_base_url = ( + os.getenv("HERMES_PORTAL_BASE_URL") + or os.getenv("NOUS_PORTAL_BASE_URL") + or pconfig.portal_base_url + ).rstrip("/") + client_id = pconfig.client_id + scope = pconfig.scope + def _do_nous_device_request(): + with httpx.Client(timeout=httpx.Timeout(15.0), headers={"Accept": "application/json"}) as client: + return _request_device_code( + client=client, + portal_base_url=portal_base_url, + client_id=client_id, + scope=scope, + ) + device_data = await asyncio.get_event_loop().run_in_executor(None, _do_nous_device_request) + sid, sess = _new_oauth_session("nous", "device_code") + sess["device_code"] = str(device_data["device_code"]) + sess["interval"] = int(device_data["interval"]) + sess["expires_at"] = time.time() + int(device_data["expires_in"]) + sess["portal_base_url"] = portal_base_url + sess["client_id"] = client_id + threading.Thread( + target=_nous_poller, args=(sid,), daemon=True, name=f"oauth-poll-{sid[:6]}" + ).start() + return { + "session_id": sid, + "flow": "device_code", + "user_code": str(device_data["user_code"]), + "verification_url": str(device_data["verification_uri_complete"]), + "expires_in": int(device_data["expires_in"]), + "poll_interval": int(device_data["interval"]), + } + + if provider_id == "openai-codex": + # Codex uses fixed OpenAI device-auth endpoints; reuse the helper. + sid, _ = _new_oauth_session("openai-codex", "device_code") + # Use the helper but in a thread because it polls inline. + # We can't extract just the start step without refactoring auth.py, + # so we run the full helper in a worker and proxy the user_code + + # verification_url back via the session dict. The helper prints + # to stdout — we capture nothing here, just status. + threading.Thread( + target=_codex_full_login_worker, args=(sid,), daemon=True, + name=f"oauth-codex-{sid[:6]}", + ).start() + # Block briefly until the worker has populated the user_code, OR error. + deadline = time.time() + 10 + while time.time() < deadline: + with _oauth_sessions_lock: + s = _oauth_sessions.get(sid) + if s and (s.get("user_code") or s["status"] != "pending"): + break + await asyncio.sleep(0.1) + with _oauth_sessions_lock: + s = _oauth_sessions.get(sid, {}) + if s.get("status") == "error": + raise HTTPException(status_code=500, detail=s.get("error_message") or "device-auth failed") + if not s.get("user_code"): + raise HTTPException(status_code=504, detail="device-auth timed out before returning a user code") + return { + "session_id": sid, + "flow": "device_code", + "user_code": s["user_code"], + "verification_url": s["verification_url"], + "expires_in": int(s.get("expires_in") or 900), + "poll_interval": int(s.get("interval") or 5), + } + + raise HTTPException(status_code=400, detail=f"Provider {provider_id} does not support device-code flow") + + +def _nous_poller(session_id: str) -> None: + """Background poller that drives a Nous device-code flow to completion.""" + from hermes_cli.auth import _poll_for_token, refresh_nous_oauth_from_state + from datetime import datetime, timezone + import httpx + with _oauth_sessions_lock: + sess = _oauth_sessions.get(session_id) + if not sess: + return + portal_base_url = sess["portal_base_url"] + client_id = sess["client_id"] + device_code = sess["device_code"] + interval = sess["interval"] + expires_in = max(60, int(sess["expires_at"] - time.time())) + try: + with httpx.Client(timeout=httpx.Timeout(15.0), headers={"Accept": "application/json"}) as client: + token_data = _poll_for_token( + client=client, + portal_base_url=portal_base_url, + client_id=client_id, + device_code=device_code, + expires_in=expires_in, + poll_interval=interval, + ) + # Same post-processing as _nous_device_code_login (mint agent key) + now = datetime.now(timezone.utc) + token_ttl = int(token_data.get("expires_in") or 0) + auth_state = { + "portal_base_url": portal_base_url, + "inference_base_url": token_data.get("inference_base_url"), + "client_id": client_id, + "scope": token_data.get("scope"), + "token_type": token_data.get("token_type", "Bearer"), + "access_token": token_data["access_token"], + "refresh_token": token_data.get("refresh_token"), + "obtained_at": now.isoformat(), + "expires_at": ( + datetime.fromtimestamp(now.timestamp() + token_ttl, tz=timezone.utc).isoformat() + if token_ttl else None + ), + "expires_in": token_ttl, + } + full_state = refresh_nous_oauth_from_state( + auth_state, min_key_ttl_seconds=300, timeout_seconds=15.0, + force_refresh=False, force_mint=True, + ) + # Save into credential pool same as auth_commands.py does + from agent.credential_pool import ( + PooledCredential, + load_pool, + AUTH_TYPE_OAUTH, + SOURCE_MANUAL, + ) + pool = load_pool("nous") + entry = PooledCredential.from_dict("nous", { + **full_state, + "label": "dashboard device_code", + "auth_type": AUTH_TYPE_OAUTH, + "source": f"{SOURCE_MANUAL}:dashboard_device_code", + "base_url": full_state.get("inference_base_url"), + }) + pool.add_entry(entry) + # Also persist to auth store so get_nous_auth_status() sees it + # (matches what _login_nous in auth.py does for the CLI flow). + try: + from hermes_cli.auth import ( + _load_auth_store, _save_provider_state, _save_auth_store, + _auth_store_lock, + ) + with _auth_store_lock(): + auth_store = _load_auth_store() + _save_provider_state(auth_store, "nous", full_state) + _save_auth_store(auth_store) + except Exception as store_exc: + _log.warning( + "oauth/device: credential pool saved but auth store write failed " + "(session=%s): %s", session_id, store_exc, + ) + with _oauth_sessions_lock: + sess["status"] = "approved" + _log.info("oauth/device: nous login completed (session=%s)", session_id) + except Exception as e: + _log.warning("nous device-code poll failed (session=%s): %s", session_id, e) + with _oauth_sessions_lock: + sess["status"] = "error" + sess["error_message"] = str(e) + + +def _codex_full_login_worker(session_id: str) -> None: + """Run the complete OpenAI Codex device-code flow. + + Codex doesn't use the standard OAuth device-code endpoints; it has its + own ``/api/accounts/deviceauth/usercode`` (JSON body, returns + ``device_auth_id``) and ``/api/accounts/deviceauth/token`` (JSON body + polled until 200). On success the response carries an + ``authorization_code`` + ``code_verifier`` that get exchanged at + CODEX_OAUTH_TOKEN_URL with grant_type=authorization_code. + + The flow is replicated inline (rather than calling + _codex_device_code_login) because that helper prints/blocks/polls in a + single function — we need to surface the user_code to the dashboard the + moment we receive it, well before polling completes. + """ + try: + import httpx + from hermes_cli.auth import ( + CODEX_OAUTH_CLIENT_ID, + CODEX_OAUTH_TOKEN_URL, + DEFAULT_CODEX_BASE_URL, + ) + issuer = "https://auth.openai.com" + + # Step 1: request device code + with httpx.Client(timeout=httpx.Timeout(15.0)) as client: + resp = client.post( + f"{issuer}/api/accounts/deviceauth/usercode", + json={"client_id": CODEX_OAUTH_CLIENT_ID}, + headers={"Content-Type": "application/json"}, + ) + if resp.status_code != 200: + raise RuntimeError(f"deviceauth/usercode returned {resp.status_code}") + device_data = resp.json() + user_code = device_data.get("user_code", "") + device_auth_id = device_data.get("device_auth_id", "") + poll_interval = max(3, int(device_data.get("interval", "5"))) + if not user_code or not device_auth_id: + raise RuntimeError("device-code response missing user_code or device_auth_id") + verification_url = f"{issuer}/codex/device" + with _oauth_sessions_lock: + sess = _oauth_sessions.get(session_id) + if not sess: + return + sess["user_code"] = user_code + sess["verification_url"] = verification_url + sess["device_auth_id"] = device_auth_id + sess["interval"] = poll_interval + sess["expires_in"] = 15 * 60 # OpenAI's effective limit + sess["expires_at"] = time.time() + sess["expires_in"] + + # Step 2: poll until authorized + deadline = time.time() + sess["expires_in"] + code_resp = None + with httpx.Client(timeout=httpx.Timeout(15.0)) as client: + while time.time() < deadline: + time.sleep(poll_interval) + poll = client.post( + f"{issuer}/api/accounts/deviceauth/token", + json={"device_auth_id": device_auth_id, "user_code": user_code}, + headers={"Content-Type": "application/json"}, + ) + if poll.status_code == 200: + code_resp = poll.json() + break + if poll.status_code in (403, 404): + continue # user hasn't authorized yet + raise RuntimeError(f"deviceauth/token poll returned {poll.status_code}") + + if code_resp is None: + with _oauth_sessions_lock: + sess["status"] = "expired" + sess["error_message"] = "Device code expired before approval" + return + + # Step 3: exchange authorization_code for tokens + authorization_code = code_resp.get("authorization_code", "") + code_verifier = code_resp.get("code_verifier", "") + if not authorization_code or not code_verifier: + raise RuntimeError("device-auth response missing authorization_code/code_verifier") + with httpx.Client(timeout=httpx.Timeout(15.0)) as client: + token_resp = client.post( + CODEX_OAUTH_TOKEN_URL, + data={ + "grant_type": "authorization_code", + "code": authorization_code, + "redirect_uri": f"{issuer}/deviceauth/callback", + "client_id": CODEX_OAUTH_CLIENT_ID, + "code_verifier": code_verifier, + }, + headers={"Content-Type": "application/x-www-form-urlencoded"}, + ) + if token_resp.status_code != 200: + raise RuntimeError(f"token exchange returned {token_resp.status_code}") + tokens = token_resp.json() + access_token = tokens.get("access_token", "") + refresh_token = tokens.get("refresh_token", "") + if not access_token: + raise RuntimeError("token exchange did not return access_token") + + # Persist via credential pool — same shape as auth_commands.add_command + from agent.credential_pool import ( + PooledCredential, + load_pool, + AUTH_TYPE_OAUTH, + SOURCE_MANUAL, + ) + import uuid as _uuid + pool = load_pool("openai-codex") + base_url = ( + os.getenv("HERMES_CODEX_BASE_URL", "").strip().rstrip("/") + or DEFAULT_CODEX_BASE_URL + ) + entry = PooledCredential( + provider="openai-codex", + id=_uuid.uuid4().hex[:6], + label="dashboard device_code", + auth_type=AUTH_TYPE_OAUTH, + priority=0, + source=f"{SOURCE_MANUAL}:dashboard_device_code", + access_token=access_token, + refresh_token=refresh_token, + base_url=base_url, + ) + pool.add_entry(entry) + with _oauth_sessions_lock: + sess["status"] = "approved" + _log.info("oauth/device: openai-codex login completed (session=%s)", session_id) + except Exception as e: + _log.warning("codex device-code worker failed (session=%s): %s", session_id, e) + with _oauth_sessions_lock: + s = _oauth_sessions.get(session_id) + if s: + s["status"] = "error" + s["error_message"] = str(e) + + +@app.post("/api/providers/oauth/{provider_id}/start") +async def start_oauth_login(provider_id: str, request: Request): + """Initiate an OAuth login flow. Token-protected.""" + auth = request.headers.get("authorization", "") + if auth != f"Bearer {_SESSION_TOKEN}": + raise HTTPException(status_code=401, detail="Unauthorized") + _gc_oauth_sessions() + valid = {p["id"] for p in _OAUTH_PROVIDER_CATALOG} + if provider_id not in valid: + raise HTTPException(status_code=400, detail=f"Unknown provider {provider_id}") + catalog_entry = next(p for p in _OAUTH_PROVIDER_CATALOG if p["id"] == provider_id) + if catalog_entry["flow"] == "external": + raise HTTPException( + status_code=400, + detail=f"{provider_id} uses an external CLI; run `{catalog_entry['cli_command']}` manually", + ) + try: + if catalog_entry["flow"] == "pkce": + return _start_anthropic_pkce() + if catalog_entry["flow"] == "device_code": + return await _start_device_code_flow(provider_id) + except HTTPException: + raise + except Exception as e: + _log.exception("oauth/start %s failed", provider_id) + raise HTTPException(status_code=500, detail=str(e)) + raise HTTPException(status_code=400, detail="Unsupported flow") + + +class OAuthSubmitBody(BaseModel): + session_id: str + code: str + + +@app.post("/api/providers/oauth/{provider_id}/submit") +async def submit_oauth_code(provider_id: str, body: OAuthSubmitBody, request: Request): + """Submit the auth code for PKCE flows. Token-protected.""" + auth = request.headers.get("authorization", "") + if auth != f"Bearer {_SESSION_TOKEN}": + raise HTTPException(status_code=401, detail="Unauthorized") + if provider_id == "anthropic": + return await asyncio.get_event_loop().run_in_executor( + None, _submit_anthropic_pkce, body.session_id, body.code, + ) + raise HTTPException(status_code=400, detail=f"submit not supported for {provider_id}") + + +@app.get("/api/providers/oauth/{provider_id}/poll/{session_id}") +async def poll_oauth_session(provider_id: str, session_id: str): + """Poll a device-code session's status (no auth — read-only state).""" + with _oauth_sessions_lock: + sess = _oauth_sessions.get(session_id) + if not sess: + raise HTTPException(status_code=404, detail="Session not found or expired") + if sess["provider"] != provider_id: + raise HTTPException(status_code=400, detail="Provider mismatch for session") + return { + "session_id": session_id, + "status": sess["status"], + "error_message": sess.get("error_message"), + "expires_at": sess.get("expires_at"), + } + + +@app.delete("/api/providers/oauth/sessions/{session_id}") +async def cancel_oauth_session(session_id: str, request: Request): + """Cancel a pending OAuth session. Token-protected.""" + auth = request.headers.get("authorization", "") + if auth != f"Bearer {_SESSION_TOKEN}": + raise HTTPException(status_code=401, detail="Unauthorized") + with _oauth_sessions_lock: + sess = _oauth_sessions.pop(session_id, None) + if sess is None: + return {"ok": False, "message": "session not found"} + return {"ok": True, "session_id": session_id} + + +# --------------------------------------------------------------------------- +# Session detail endpoints +# --------------------------------------------------------------------------- + + +@app.get("/api/sessions/{session_id}") +async def get_session_detail(session_id: str): + from hermes_state import SessionDB + db = SessionDB() + try: + sid = db.resolve_session_id(session_id) + session = db.get_session(sid) if sid else None + if not session: + raise HTTPException(status_code=404, detail="Session not found") + return session + finally: + db.close() + + +@app.get("/api/sessions/{session_id}/messages") +async def get_session_messages(session_id: str): + from hermes_state import SessionDB + db = SessionDB() + try: + sid = db.resolve_session_id(session_id) + if not sid: + raise HTTPException(status_code=404, detail="Session not found") + messages = db.get_messages(sid) + return {"session_id": sid, "messages": messages} + finally: + db.close() + + +@app.delete("/api/sessions/{session_id}") +async def delete_session_endpoint(session_id: str): + from hermes_state import SessionDB + db = SessionDB() + try: + if not db.delete_session(session_id): + raise HTTPException(status_code=404, detail="Session not found") + return {"ok": True} + finally: + db.close() + + +# --------------------------------------------------------------------------- +# Log viewer endpoint +# --------------------------------------------------------------------------- + + +@app.get("/api/logs") +async def get_logs( + file: str = "agent", + lines: int = 100, + level: Optional[str] = None, + component: Optional[str] = None, + search: Optional[str] = None, +): + from hermes_cli.logs import _read_tail, LOG_FILES + + log_name = LOG_FILES.get(file) + if not log_name: + raise HTTPException(status_code=400, detail=f"Unknown log file: {file}") + log_path = get_hermes_home() / "logs" / log_name + if not log_path.exists(): + return {"file": file, "lines": []} + + try: + from hermes_logging import COMPONENT_PREFIXES + except ImportError: + COMPONENT_PREFIXES = {} + + # Normalize "ALL" / "all" / empty → no filter. _matches_filters treats an + # empty tuple as "must match a prefix" (startswith(()) is always False), + # so passing () instead of None silently drops every line. + min_level = level if level and level.upper() != "ALL" else None + if component and component.lower() != "all": + comp_prefixes = COMPONENT_PREFIXES.get(component) + if comp_prefixes is None: + raise HTTPException( + status_code=400, + detail=f"Unknown component: {component}. " + f"Available: {', '.join(sorted(COMPONENT_PREFIXES))}", + ) + else: + comp_prefixes = None + + has_filters = bool(min_level or comp_prefixes or search) + result = _read_tail( + log_path, min(lines, 500) if not search else 2000, + has_filters=has_filters, + min_level=min_level, + component_prefixes=comp_prefixes, + ) + # Post-filter by search term (case-insensitive substring match). + # _read_tail doesn't support free-text search, so we filter here and + # trim to the requested line count afterward. + if search: + needle = search.lower() + result = [l for l in result if needle in l.lower()][-min(lines, 500):] + return {"file": file, "lines": result} + + +# --------------------------------------------------------------------------- +# Cron job management endpoints +# --------------------------------------------------------------------------- + + +class CronJobCreate(BaseModel): + prompt: str + schedule: str + name: str = "" + deliver: str = "local" + + +class CronJobUpdate(BaseModel): + updates: dict + + +@app.get("/api/cron/jobs") +async def list_cron_jobs(): + from cron.jobs import list_jobs + return list_jobs(include_disabled=True) + + +@app.get("/api/cron/jobs/{job_id}") +async def get_cron_job(job_id: str): + from cron.jobs import get_job + job = get_job(job_id) + if not job: + raise HTTPException(status_code=404, detail="Job not found") + return job + + +@app.post("/api/cron/jobs") +async def create_cron_job(body: CronJobCreate): + from cron.jobs import create_job + try: + job = create_job(prompt=body.prompt, schedule=body.schedule, + name=body.name, deliver=body.deliver) + return job + except Exception as e: + _log.exception("POST /api/cron/jobs failed") + raise HTTPException(status_code=400, detail=str(e)) + + +@app.put("/api/cron/jobs/{job_id}") +async def update_cron_job(job_id: str, body: CronJobUpdate): + from cron.jobs import update_job + job = update_job(job_id, body.updates) + if not job: + raise HTTPException(status_code=404, detail="Job not found") + return job + + +@app.post("/api/cron/jobs/{job_id}/pause") +async def pause_cron_job(job_id: str): + from cron.jobs import pause_job + job = pause_job(job_id) + if not job: + raise HTTPException(status_code=404, detail="Job not found") + return job + + +@app.post("/api/cron/jobs/{job_id}/resume") +async def resume_cron_job(job_id: str): + from cron.jobs import resume_job + job = resume_job(job_id) + if not job: + raise HTTPException(status_code=404, detail="Job not found") + return job + + +@app.post("/api/cron/jobs/{job_id}/trigger") +async def trigger_cron_job(job_id: str): + from cron.jobs import trigger_job + job = trigger_job(job_id) + if not job: + raise HTTPException(status_code=404, detail="Job not found") + return job + + +@app.delete("/api/cron/jobs/{job_id}") +async def delete_cron_job(job_id: str): + from cron.jobs import remove_job + if not remove_job(job_id): + raise HTTPException(status_code=404, detail="Job not found") + return {"ok": True} + + +# --------------------------------------------------------------------------- +# Skills & Tools endpoints +# --------------------------------------------------------------------------- + + +class SkillToggle(BaseModel): + name: str + enabled: bool + + +@app.get("/api/skills") +async def get_skills(): + from tools.skills_tool import _find_all_skills + from hermes_cli.skills_config import get_disabled_skills + config = load_config() + disabled = get_disabled_skills(config) + skills = _find_all_skills(skip_disabled=True) + for s in skills: + s["enabled"] = s["name"] not in disabled + return skills + + +@app.put("/api/skills/toggle") +async def toggle_skill(body: SkillToggle): + from hermes_cli.skills_config import get_disabled_skills, save_disabled_skills + config = load_config() + disabled = get_disabled_skills(config) + if body.enabled: + disabled.discard(body.name) + else: + disabled.add(body.name) + save_disabled_skills(config, disabled) + return {"ok": True, "name": body.name, "enabled": body.enabled} + + +@app.get("/api/tools/toolsets") +async def get_toolsets(): + from hermes_cli.tools_config import ( + _get_effective_configurable_toolsets, + _get_platform_tools, + _toolset_has_keys, + ) + from toolsets import resolve_toolset + + config = load_config() + enabled_toolsets = _get_platform_tools( + config, + "cli", + include_default_mcp_servers=False, + ) + result = [] + for name, label, desc in _get_effective_configurable_toolsets(): + try: + tools = sorted(set(resolve_toolset(name))) + except Exception: + tools = [] + is_enabled = name in enabled_toolsets + result.append({ + "name": name, "label": label, "description": desc, + "enabled": is_enabled, + "available": is_enabled, + "configured": _toolset_has_keys(name, config), + "tools": tools, + }) + return result + + +# --------------------------------------------------------------------------- +# Raw YAML config endpoint +# --------------------------------------------------------------------------- + + +class RawConfigUpdate(BaseModel): + yaml_text: str + + +@app.get("/api/config/raw") +async def get_config_raw(): + path = get_config_path() + if not path.exists(): + return {"yaml": ""} + return {"yaml": path.read_text(encoding="utf-8")} + + +@app.put("/api/config/raw") +async def update_config_raw(body: RawConfigUpdate): + try: + parsed = yaml.safe_load(body.yaml_text) + if not isinstance(parsed, dict): + raise HTTPException(status_code=400, detail="YAML must be a mapping") + save_config(parsed) + return {"ok": True} + except yaml.YAMLError as e: + raise HTTPException(status_code=400, detail=f"Invalid YAML: {e}") + + +# --------------------------------------------------------------------------- +# Token / cost analytics endpoint +# --------------------------------------------------------------------------- + + +@app.get("/api/analytics/usage") +async def get_usage_analytics(days: int = 30): + from hermes_state import SessionDB + db = SessionDB() + try: + cutoff = time.time() - (days * 86400) + cur = db._conn.execute(""" + SELECT date(started_at, 'unixepoch') as day, + SUM(input_tokens) as input_tokens, + SUM(output_tokens) as output_tokens, + SUM(cache_read_tokens) as cache_read_tokens, + SUM(reasoning_tokens) as reasoning_tokens, + COALESCE(SUM(estimated_cost_usd), 0) as estimated_cost, + COALESCE(SUM(actual_cost_usd), 0) as actual_cost, + COUNT(*) as sessions + FROM sessions WHERE started_at > ? + GROUP BY day ORDER BY day + """, (cutoff,)) + daily = [dict(r) for r in cur.fetchall()] + + cur2 = db._conn.execute(""" + SELECT model, + SUM(input_tokens) as input_tokens, + SUM(output_tokens) as output_tokens, + COALESCE(SUM(estimated_cost_usd), 0) as estimated_cost, + COUNT(*) as sessions + FROM sessions WHERE started_at > ? AND model IS NOT NULL + GROUP BY model ORDER BY SUM(input_tokens) + SUM(output_tokens) DESC + """, (cutoff,)) + by_model = [dict(r) for r in cur2.fetchall()] + + cur3 = db._conn.execute(""" + SELECT SUM(input_tokens) as total_input, + SUM(output_tokens) as total_output, + SUM(cache_read_tokens) as total_cache_read, + SUM(reasoning_tokens) as total_reasoning, + COALESCE(SUM(estimated_cost_usd), 0) as total_estimated_cost, + COALESCE(SUM(actual_cost_usd), 0) as total_actual_cost, + COUNT(*) as total_sessions + FROM sessions WHERE started_at > ? + """, (cutoff,)) + totals = dict(cur3.fetchone()) + + return {"daily": daily, "by_model": by_model, "totals": totals, "period_days": days} + finally: + db.close() + + +def mount_spa(application: FastAPI): + """Mount the built SPA. Falls back to index.html for client-side routing.""" + if not WEB_DIST.exists(): + @application.get("/{full_path:path}") + async def no_frontend(full_path: str): + return JSONResponse( + {"error": "Frontend not built. Run: cd web && npm run build"}, + status_code=404, + ) + return + + application.mount("/assets", StaticFiles(directory=WEB_DIST / "assets"), name="assets") + + @application.get("/{full_path:path}") + async def serve_spa(full_path: str): + file_path = WEB_DIST / full_path + # Prevent path traversal via url-encoded sequences (%2e%2e/) + if ( + full_path + and file_path.resolve().is_relative_to(WEB_DIST.resolve()) + and file_path.exists() + and file_path.is_file() + ): + return FileResponse(file_path) + return FileResponse( + WEB_DIST / "index.html", + headers={"Cache-Control": "no-store, no-cache, must-revalidate"}, + ) + + +mount_spa(app) + + +def start_server(host: str = "127.0.0.1", port: int = 9119, open_browser: bool = True): + """Start the web UI server.""" + import uvicorn + + if host not in ("127.0.0.1", "localhost", "::1"): + import logging + logging.warning( + "Binding to %s — the web UI exposes config and API keys. " + "Only bind to non-localhost if you trust all users on the network.", host, + ) + + if open_browser: + import threading + import webbrowser + + def _open(): + import time as _t + _t.sleep(1.0) + webbrowser.open(f"http://{host}:{port}") + + threading.Thread(target=_open, daemon=True).start() + + print(f" Hermes Web UI → http://{host}:{port}") + uvicorn.run(app, host=host, port=port, log_level="warning") diff --git a/mindcli/_vendor/hermes_cli/webhook.py b/mindcli/_vendor/hermes_cli/webhook.py new file mode 100644 index 0000000..8ff135e --- /dev/null +++ b/mindcli/_vendor/hermes_cli/webhook.py @@ -0,0 +1,259 @@ +"""hermes webhook — manage dynamic webhook subscriptions from the CLI. + +Usage: + hermes webhook subscribe [options] + hermes webhook list + hermes webhook remove + hermes webhook test [--payload '{"key": "value"}'] + +Subscriptions persist to ~/.hermes/webhook_subscriptions.json and are +hot-reloaded by the webhook adapter without a gateway restart. +""" + +import json +import os +import re +import secrets +import time +from pathlib import Path +from typing import Dict + +from hermes_constants import display_hermes_home + + +_SUBSCRIPTIONS_FILENAME = "webhook_subscriptions.json" + + +def _hermes_home() -> Path: + from hermes_constants import get_hermes_home + return get_hermes_home() + + +def _subscriptions_path() -> Path: + return _hermes_home() / _SUBSCRIPTIONS_FILENAME + + +def _load_subscriptions() -> Dict[str, dict]: + path = _subscriptions_path() + if not path.exists(): + return {} + try: + data = json.loads(path.read_text(encoding="utf-8")) + return data if isinstance(data, dict) else {} + except Exception: + return {} + + +def _save_subscriptions(subs: Dict[str, dict]) -> None: + path = _subscriptions_path() + path.parent.mkdir(parents=True, exist_ok=True) + tmp_path = path.with_suffix(".tmp") + tmp_path.write_text( + json.dumps(subs, indent=2, ensure_ascii=False), + encoding="utf-8", + ) + os.replace(str(tmp_path), str(path)) + + +def _get_webhook_config() -> dict: + """Load webhook platform config. Returns {} if not configured.""" + try: + from hermes_cli.config import load_config + cfg = load_config() + return cfg.get("platforms", {}).get("webhook", {}) + except Exception: + return {} + + +def _is_webhook_enabled() -> bool: + return bool(_get_webhook_config().get("enabled")) + + +def _get_webhook_base_url() -> str: + wh = _get_webhook_config().get("extra", {}) + host = wh.get("host", "0.0.0.0") + port = wh.get("port", 8644) + display_host = "localhost" if host == "0.0.0.0" else host + return f"http://{display_host}:{port}" + + +def _setup_hint() -> str: + _dhh = display_hermes_home() + return f""" + Webhook platform is not enabled. To set it up: + + 1. Run the gateway setup wizard: + hermes gateway setup + + 2. Or manually add to {_dhh}/config.yaml: + platforms: + webhook: + enabled: true + extra: + host: "0.0.0.0" + port: 8644 + secret: "your-global-hmac-secret" + + 3. Or set environment variables in {_dhh}/.env: + WEBHOOK_ENABLED=true + WEBHOOK_PORT=8644 + WEBHOOK_SECRET=your-global-secret + + Then start the gateway: hermes gateway run +""" + + +def _require_webhook_enabled() -> bool: + """Check webhook is enabled. Print setup guide and return False if not.""" + if _is_webhook_enabled(): + return True + print(_setup_hint()) + return False + + +def webhook_command(args): + """Entry point for 'hermes webhook' subcommand.""" + sub = getattr(args, "webhook_action", None) + + if not sub: + print("Usage: hermes webhook {subscribe|list|remove|test}") + print("Run 'hermes webhook --help' for details.") + return + + if not _require_webhook_enabled(): + return + + if sub in ("subscribe", "add"): + _cmd_subscribe(args) + elif sub in ("list", "ls"): + _cmd_list(args) + elif sub in ("remove", "rm"): + _cmd_remove(args) + elif sub == "test": + _cmd_test(args) + + +def _cmd_subscribe(args): + name = args.name.strip().lower().replace(" ", "-") + if not re.match(r'^[a-z0-9][a-z0-9_-]*$', name): + print(f"Error: Invalid name '{name}'. Use lowercase alphanumeric with hyphens/underscores.") + return + + subs = _load_subscriptions() + is_update = name in subs + + secret = args.secret or secrets.token_urlsafe(32) + events = [e.strip() for e in args.events.split(",")] if args.events else [] + + route = { + "description": args.description or f"Agent-created subscription: {name}", + "events": events, + "secret": secret, + "prompt": args.prompt or "", + "skills": [s.strip() for s in args.skills.split(",")] if args.skills else [], + "deliver": args.deliver or "log", + "created_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), + } + + if args.deliver_chat_id: + route["deliver_extra"] = {"chat_id": args.deliver_chat_id} + + subs[name] = route + _save_subscriptions(subs) + + base_url = _get_webhook_base_url() + status = "Updated" if is_update else "Created" + + print(f"\n {status} webhook subscription: {name}") + print(f" URL: {base_url}/webhooks/{name}") + print(f" Secret: {secret}") + if events: + print(f" Events: {', '.join(events)}") + else: + print(" Events: (all)") + print(f" Deliver: {route['deliver']}") + if route.get("prompt"): + prompt_preview = route["prompt"][:80] + ("..." if len(route["prompt"]) > 80 else "") + print(f" Prompt: {prompt_preview}") + print(f"\n Configure your service to POST to the URL above.") + print(f" Use the secret for HMAC-SHA256 signature validation.") + print(f" The gateway must be running to receive events (hermes gateway run).\n") + + +def _cmd_list(args): + subs = _load_subscriptions() + if not subs: + print(" No dynamic webhook subscriptions.") + print(" Create one with: hermes webhook subscribe ") + return + + base_url = _get_webhook_base_url() + print(f"\n {len(subs)} webhook subscription(s):\n") + for name, route in subs.items(): + events = ", ".join(route.get("events", [])) or "(all)" + deliver = route.get("deliver", "log") + desc = route.get("description", "") + print(f" ◆ {name}") + if desc: + print(f" {desc}") + print(f" URL: {base_url}/webhooks/{name}") + print(f" Events: {events}") + print(f" Deliver: {deliver}") + print() + + +def _cmd_remove(args): + name = args.name.strip().lower() + subs = _load_subscriptions() + + if name not in subs: + print(f" No subscription named '{name}'.") + print(" Note: Static routes from config.yaml cannot be removed here.") + return + + del subs[name] + _save_subscriptions(subs) + print(f" Removed webhook subscription: {name}") + + +def _cmd_test(args): + """Send a test POST to a webhook route.""" + name = args.name.strip().lower() + subs = _load_subscriptions() + + if name not in subs: + print(f" No subscription named '{name}'.") + return + + route = subs[name] + secret = route.get("secret", "") + base_url = _get_webhook_base_url() + url = f"{base_url}/webhooks/{name}" + + payload = args.payload or '{"test": true, "event_type": "test", "message": "Hello from hermes webhook test"}' + + import hmac + import hashlib + sig = "sha256=" + hmac.new( + secret.encode(), payload.encode(), hashlib.sha256 + ).hexdigest() + + print(f" Sending test POST to {url}") + try: + import urllib.request + req = urllib.request.Request( + url, + data=payload.encode(), + headers={ + "Content-Type": "application/json", + "X-Hub-Signature-256": sig, + "X-GitHub-Event": "test", + }, + method="POST", + ) + with urllib.request.urlopen(req, timeout=10) as resp: + body = resp.read().decode() + print(f" Response ({resp.status}): {body}") + except Exception as e: + print(f" Error: {e}") + print(" Is the gateway running? (hermes gateway run)") diff --git a/mindcli/_vendor/hermes_constants.py b/mindcli/_vendor/hermes_constants.py new file mode 100644 index 0000000..3bc56d4 --- /dev/null +++ b/mindcli/_vendor/hermes_constants.py @@ -0,0 +1,294 @@ +"""Shared constants for Hermes Agent. + +Import-safe module with no dependencies — can be imported from anywhere +without risk of circular imports. +""" + +import os +from pathlib import Path + + +def get_hermes_home() -> Path: + """Return the Hermes home directory (default: ~/.hermes). + + Reads HERMES_HOME env var, falls back to ~/.hermes. + This is the single source of truth — all other copies should import this. + """ + return Path(os.getenv("HERMES_HOME", Path.home() / ".hermes")) + + +def get_default_hermes_root() -> Path: + """Return the root Hermes directory for profile-level operations. + + In standard deployments this is ``~/.hermes``. + + In Docker or custom deployments where ``HERMES_HOME`` points outside + ``~/.hermes`` (e.g. ``/opt/data``), returns ``HERMES_HOME`` directly + — that IS the root. + + In profile mode where ``HERMES_HOME`` is ``/profiles/``, + returns ```` so that ``profile list`` can see all profiles. + Works both for standard (``~/.hermes/profiles/coder``) and Docker + (``/opt/data/profiles/coder``) layouts. + + Import-safe — no dependencies beyond stdlib. + """ + native_home = Path.home() / ".hermes" + env_home = os.environ.get("HERMES_HOME", "") + if not env_home: + return native_home + env_path = Path(env_home) + try: + env_path.resolve().relative_to(native_home.resolve()) + # HERMES_HOME is under ~/.hermes (normal or profile mode) + return native_home + except ValueError: + pass + + # Docker / custom deployment. + # Check if this is a profile path: /profiles/ + # If the immediate parent dir is named "profiles", the root is + # the grandparent — this covers Docker profiles correctly. + if env_path.parent.name == "profiles": + return env_path.parent.parent + + # Not a profile path — HERMES_HOME itself is the root + return env_path + + +def get_optional_skills_dir(default: Path | None = None) -> Path: + """Return the optional-skills directory, honoring package-manager wrappers. + + Packaged installs may ship ``optional-skills`` outside the Python package + tree and expose it via ``HERMES_OPTIONAL_SKILLS``. + """ + override = os.getenv("HERMES_OPTIONAL_SKILLS", "").strip() + if override: + return Path(override) + if default is not None: + return default + return get_hermes_home() / "optional-skills" + + +def get_hermes_dir(new_subpath: str, old_name: str) -> Path: + """Resolve a Hermes subdirectory with backward compatibility. + + New installs get the consolidated layout (e.g. ``cache/images``). + Existing installs that already have the old path (e.g. ``image_cache``) + keep using it — no migration required. + + Args: + new_subpath: Preferred path relative to HERMES_HOME (e.g. ``"cache/images"``). + old_name: Legacy path relative to HERMES_HOME (e.g. ``"image_cache"``). + + Returns: + Absolute ``Path`` — old location if it exists on disk, otherwise the new one. + """ + home = get_hermes_home() + old_path = home / old_name + if old_path.exists(): + return old_path + return home / new_subpath + + +def display_hermes_home() -> str: + """Return a user-friendly display string for the current HERMES_HOME. + + Uses ``~/`` shorthand for readability:: + + default: ``~/.hermes`` + profile: ``~/.hermes/profiles/coder`` + custom: ``/opt/hermes-custom`` + + Use this in **user-facing** print/log messages instead of hardcoding + ``~/.hermes``. For code that needs a real ``Path``, use + :func:`get_hermes_home` instead. + """ + home = get_hermes_home() + try: + return "~/" + str(home.relative_to(Path.home())) + except ValueError: + return str(home) + + +def get_subprocess_home() -> str | None: + """Return a per-profile HOME directory for subprocesses, or None. + + When ``{HERMES_HOME}/home/`` exists on disk, subprocesses should use it + as ``HOME`` so system tools (git, ssh, gh, npm …) write their configs + inside the Hermes data directory instead of the OS-level ``/root`` or + ``~/``. This provides: + + * **Docker persistence** — tool configs land inside the persistent volume. + * **Profile isolation** — each profile gets its own git identity, SSH + keys, gh tokens, etc. + + The Python process's own ``os.environ["HOME"]`` and ``Path.home()`` are + **never** modified — only subprocess environments should inject this value. + Activation is directory-based: if the ``home/`` subdirectory doesn't + exist, returns ``None`` and behavior is unchanged. + """ + hermes_home = os.getenv("HERMES_HOME") + if not hermes_home: + return None + profile_home = os.path.join(hermes_home, "home") + if os.path.isdir(profile_home): + return profile_home + return None + + +VALID_REASONING_EFFORTS = ("minimal", "low", "medium", "high", "xhigh") + + +def parse_reasoning_effort(effort: str) -> dict | None: + """Parse a reasoning effort level into a config dict. + + Valid levels: "none", "minimal", "low", "medium", "high", "xhigh". + Returns None when the input is empty or unrecognized (caller uses default). + Returns {"enabled": False} for "none". + Returns {"enabled": True, "effort": } for valid effort levels. + """ + if not effort or not effort.strip(): + return None + effort = effort.strip().lower() + if effort == "none": + return {"enabled": False} + if effort in VALID_REASONING_EFFORTS: + return {"enabled": True, "effort": effort} + return None + + +def is_termux() -> bool: + """Return True when running inside a Termux (Android) environment. + + Checks ``TERMUX_VERSION`` (set by Termux) or the Termux-specific + ``PREFIX`` path. Import-safe — no heavy deps. + """ + prefix = os.getenv("PREFIX", "") + return bool(os.getenv("TERMUX_VERSION") or "com.termux/files/usr" in prefix) + + +_wsl_detected: bool | None = None + + +def is_wsl() -> bool: + """Return True when running inside WSL (Windows Subsystem for Linux). + + Checks ``/proc/version`` for the ``microsoft`` marker that both WSL1 + and WSL2 inject. Result is cached for the process lifetime. + Import-safe — no heavy deps. + """ + global _wsl_detected + if _wsl_detected is not None: + return _wsl_detected + try: + with open("/proc/version", "r") as f: + _wsl_detected = "microsoft" in f.read().lower() + except Exception: + _wsl_detected = False + return _wsl_detected + + +_container_detected: bool | None = None + + +def is_container() -> bool: + """Return True when running inside a Docker/Podman container. + + Checks ``/.dockerenv`` (Docker), ``/run/.containerenv`` (Podman), + and ``/proc/1/cgroup`` for container runtime markers. Result is + cached for the process lifetime. Import-safe — no heavy deps. + """ + global _container_detected + if _container_detected is not None: + return _container_detected + if os.path.exists("/.dockerenv"): + _container_detected = True + return True + if os.path.exists("/run/.containerenv"): + _container_detected = True + return True + try: + with open("/proc/1/cgroup", "r") as f: + cgroup = f.read() + if "docker" in cgroup or "podman" in cgroup or "/lxc/" in cgroup: + _container_detected = True + return True + except OSError: + pass + _container_detected = False + return False + + +# ─── Well-Known Paths ───────────────────────────────────────────────────────── + + +def get_config_path() -> Path: + """Return the path to ``config.yaml`` under HERMES_HOME. + + Replaces the ``get_hermes_home() / "config.yaml"`` pattern repeated + in 7+ files (skill_utils.py, hermes_logging.py, hermes_time.py, etc.). + """ + return get_hermes_home() / "config.yaml" + + +def get_skills_dir() -> Path: + """Return the path to the skills directory under HERMES_HOME.""" + return get_hermes_home() / "skills" + + + +def get_env_path() -> Path: + """Return the path to the ``.env`` file under HERMES_HOME.""" + return get_hermes_home() / ".env" + + +# ─── Network Preferences ───────────────────────────────────────────────────── + + +def apply_ipv4_preference(force: bool = False) -> None: + """Monkey-patch ``socket.getaddrinfo`` to prefer IPv4 connections. + + On servers with broken or unreachable IPv6, Python tries AAAA records + first and hangs for the full TCP timeout before falling back to IPv4. + This affects httpx, requests, urllib, the OpenAI SDK — everything that + uses ``socket.getaddrinfo``. + + When *force* is True, patches ``getaddrinfo`` so that calls with + ``family=AF_UNSPEC`` (the default) resolve as ``AF_INET`` instead, + skipping IPv6 entirely. If no A record exists, falls back to the + original unfiltered resolution so pure-IPv6 hosts still work. + + Safe to call multiple times — only patches once. + Set ``network.force_ipv4: true`` in ``config.yaml`` to enable. + """ + if not force: + return + + import socket + + # Guard against double-patching + if getattr(socket.getaddrinfo, "_hermes_ipv4_patched", False): + return + + _original_getaddrinfo = socket.getaddrinfo + + def _ipv4_getaddrinfo(host, port, family=0, type=0, proto=0, flags=0): + if family == 0: # AF_UNSPEC — caller didn't request a specific family + try: + return _original_getaddrinfo( + host, port, socket.AF_INET, type, proto, flags + ) + except socket.gaierror: + # No A record — fall back to full resolution (pure-IPv6 hosts) + return _original_getaddrinfo(host, port, family, type, proto, flags) + return _original_getaddrinfo(host, port, family, type, proto, flags) + + _ipv4_getaddrinfo._hermes_ipv4_patched = True # type: ignore[attr-defined] + socket.getaddrinfo = _ipv4_getaddrinfo # type: ignore[assignment] + + +OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1" +OPENROUTER_MODELS_URL = f"{OPENROUTER_BASE_URL}/models" + +AI_GATEWAY_BASE_URL = "https://ai-gateway.vercel.sh/v1" diff --git a/mindcli/_vendor/hermes_state.py b/mindcli/_vendor/hermes_state.py new file mode 100644 index 0000000..413a5de --- /dev/null +++ b/mindcli/_vendor/hermes_state.py @@ -0,0 +1,1488 @@ +#!/usr/bin/env python3 +""" +SQLite State Store for Hermes Agent. + +Provides persistent session storage with FTS5 full-text search, replacing +the per-session JSONL file approach. Stores session metadata, full message +history, and model configuration for CLI and gateway sessions. + +Key design decisions: +- WAL mode for concurrent readers + one writer (gateway multi-platform) +- FTS5 virtual table for fast text search across all session messages +- Compression-triggered session splitting via parent_session_id chains +- Batch runner and RL trajectories are NOT stored here (separate systems) +- Session source tagging ('cli', 'telegram', 'discord', etc.) for filtering +""" + +import json +import logging +import random +import re +import sqlite3 +import threading +import time +from pathlib import Path +from hermes_constants import get_hermes_home +from typing import Any, Callable, Dict, List, Optional, TypeVar + +logger = logging.getLogger(__name__) + +T = TypeVar("T") + +DEFAULT_DB_PATH = get_hermes_home() / "state.db" + +SCHEMA_VERSION = 8 + +SCHEMA_SQL = """ +CREATE TABLE IF NOT EXISTS schema_version ( + version INTEGER NOT NULL +); + +CREATE TABLE IF NOT EXISTS sessions ( + id TEXT PRIMARY KEY, + source TEXT NOT NULL, + user_id TEXT, + model TEXT, + model_config TEXT, + system_prompt TEXT, + parent_session_id TEXT, + started_at REAL NOT NULL, + ended_at REAL, + end_reason TEXT, + message_count INTEGER DEFAULT 0, + tool_call_count INTEGER DEFAULT 0, + input_tokens INTEGER DEFAULT 0, + output_tokens INTEGER DEFAULT 0, + cache_read_tokens INTEGER DEFAULT 0, + cache_write_tokens INTEGER DEFAULT 0, + reasoning_tokens INTEGER DEFAULT 0, + billing_provider TEXT, + billing_base_url TEXT, + billing_mode TEXT, + estimated_cost_usd REAL, + actual_cost_usd REAL, + cost_status TEXT, + cost_source TEXT, + pricing_version TEXT, + title TEXT, + FOREIGN KEY (parent_session_id) REFERENCES sessions(id) +); + +CREATE TABLE IF NOT EXISTS messages ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + session_id TEXT NOT NULL REFERENCES sessions(id), + role TEXT NOT NULL, + content TEXT, + tool_call_id TEXT, + tool_calls TEXT, + tool_name TEXT, + timestamp REAL NOT NULL, + token_count INTEGER, + finish_reason TEXT, + reasoning TEXT, + reasoning_details TEXT, + codex_reasoning_items TEXT +); + +CREATE INDEX IF NOT EXISTS idx_sessions_source ON sessions(source); +CREATE INDEX IF NOT EXISTS idx_sessions_parent ON sessions(parent_session_id); +CREATE INDEX IF NOT EXISTS idx_sessions_started ON sessions(started_at DESC); +CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id, timestamp); +""" + +FTS_SQL = """ +CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5( + content, + content=messages, + content_rowid=id +); + +CREATE TRIGGER IF NOT EXISTS messages_fts_insert AFTER INSERT ON messages BEGIN + INSERT INTO messages_fts(rowid, content) VALUES (new.id, new.content); +END; + +CREATE TRIGGER IF NOT EXISTS messages_fts_delete AFTER DELETE ON messages BEGIN + INSERT INTO messages_fts(messages_fts, rowid, content) VALUES('delete', old.id, old.content); +END; + +CREATE TRIGGER IF NOT EXISTS messages_fts_update AFTER UPDATE ON messages BEGIN + INSERT INTO messages_fts(messages_fts, rowid, content) VALUES('delete', old.id, old.content); + INSERT INTO messages_fts(rowid, content) VALUES (new.id, new.content); +END; +""" + + +class SessionDB: + """ + SQLite-backed session storage with FTS5 search. + + Thread-safe for the common gateway pattern (multiple reader threads, + single writer via WAL mode). Each method opens its own cursor. + """ + + # ── Write-contention tuning ── + # With multiple hermes processes (gateway + CLI sessions + worktree agents) + # all sharing one state.db, WAL write-lock contention causes visible TUI + # freezes. SQLite's built-in busy handler uses a deterministic sleep + # schedule that causes convoy effects under high concurrency. + # + # Instead, we keep the SQLite timeout short (1s) and handle retries at the + # application level with random jitter, which naturally staggers competing + # writers and avoids the convoy. + _WRITE_MAX_RETRIES = 15 + _WRITE_RETRY_MIN_S = 0.020 # 20ms + _WRITE_RETRY_MAX_S = 0.150 # 150ms + # Attempt a PASSIVE WAL checkpoint every N successful writes. + _CHECKPOINT_EVERY_N_WRITES = 50 + + def __init__(self, db_path: Path = None): + self.db_path = db_path or DEFAULT_DB_PATH + self.db_path.parent.mkdir(parents=True, exist_ok=True) + + self._lock = threading.Lock() + self._write_count = 0 + self._conn = sqlite3.connect( + str(self.db_path), + check_same_thread=False, + # Short timeout — application-level retry with random jitter + # handles contention instead of sitting in SQLite's internal + # busy handler for up to 30s. + timeout=1.0, + # Autocommit mode: Python's default isolation_level="" auto-starts + # transactions on DML, which conflicts with our explicit + # BEGIN IMMEDIATE. None = we manage transactions ourselves. + isolation_level=None, + ) + self._conn.row_factory = sqlite3.Row + self._conn.execute("PRAGMA journal_mode=WAL") + self._conn.execute("PRAGMA foreign_keys=ON") + + self._init_schema() + + # ── Core write helper ── + + def _execute_write(self, fn: Callable[[sqlite3.Connection], T]) -> T: + """Execute a write transaction with BEGIN IMMEDIATE and jitter retry. + + *fn* receives the connection and should perform INSERT/UPDATE/DELETE + statements. The caller must NOT call ``commit()`` — that's handled + here after *fn* returns. + + BEGIN IMMEDIATE acquires the WAL write lock at transaction start + (not at commit time), so lock contention surfaces immediately. + On ``database is locked``, we release the Python lock, sleep a + random 20-150ms, and retry — breaking the convoy pattern that + SQLite's built-in deterministic backoff creates. + + Returns whatever *fn* returns. + """ + last_err: Optional[Exception] = None + for attempt in range(self._WRITE_MAX_RETRIES): + try: + with self._lock: + self._conn.execute("BEGIN IMMEDIATE") + try: + result = fn(self._conn) + self._conn.commit() + except BaseException: + try: + self._conn.rollback() + except Exception: + pass + raise + # Success — periodic best-effort checkpoint. + self._write_count += 1 + if self._write_count % self._CHECKPOINT_EVERY_N_WRITES == 0: + self._try_wal_checkpoint() + return result + except sqlite3.OperationalError as exc: + err_msg = str(exc).lower() + if "locked" in err_msg or "busy" in err_msg: + last_err = exc + if attempt < self._WRITE_MAX_RETRIES - 1: + jitter = random.uniform( + self._WRITE_RETRY_MIN_S, + self._WRITE_RETRY_MAX_S, + ) + time.sleep(jitter) + continue + # Non-lock error or retries exhausted — propagate. + raise + # Retries exhausted (shouldn't normally reach here). + raise last_err or sqlite3.OperationalError( + "database is locked after max retries" + ) + + def _try_wal_checkpoint(self) -> None: + """Best-effort PASSIVE WAL checkpoint. Never blocks, never raises. + + Flushes committed WAL frames back into the main DB file for any + frames that no other connection currently needs. Keeps the WAL + from growing unbounded when many processes hold persistent + connections. + """ + try: + with self._lock: + result = self._conn.execute( + "PRAGMA wal_checkpoint(PASSIVE)" + ).fetchone() + if result and result[1] > 0: + logger.debug( + "WAL checkpoint: %d/%d pages checkpointed", + result[2], result[1], + ) + except Exception: + pass # Best effort — never fatal. + + def close(self): + """Close the database connection. + + Attempts a PASSIVE WAL checkpoint first so that exiting processes + help keep the WAL file from growing unbounded. + """ + with self._lock: + if self._conn: + try: + self._conn.execute("PRAGMA wal_checkpoint(PASSIVE)") + except Exception: + pass + self._conn.close() + self._conn = None + + def _init_schema(self): + """Create tables and FTS if they don't exist, run migrations.""" + cursor = self._conn.cursor() + + cursor.executescript(SCHEMA_SQL) + + # Check schema version and run migrations + cursor.execute("SELECT version FROM schema_version LIMIT 1") + row = cursor.fetchone() + if row is None: + cursor.execute("INSERT INTO schema_version (version) VALUES (?)", (SCHEMA_VERSION,)) + else: + current_version = row["version"] if isinstance(row, sqlite3.Row) else row[0] + if current_version < 2: + # v2: add finish_reason column to messages + try: + cursor.execute("ALTER TABLE messages ADD COLUMN finish_reason TEXT") + except sqlite3.OperationalError: + pass # Column already exists + cursor.execute("UPDATE schema_version SET version = 2") + if current_version < 3: + # v3: add title column to sessions + try: + cursor.execute("ALTER TABLE sessions ADD COLUMN title TEXT") + except sqlite3.OperationalError: + pass # Column already exists + cursor.execute("UPDATE schema_version SET version = 3") + if current_version < 4: + # v4: add unique index on title (NULLs allowed, only non-NULL must be unique) + try: + cursor.execute( + "CREATE UNIQUE INDEX IF NOT EXISTS idx_sessions_title_unique " + "ON sessions(title) WHERE title IS NOT NULL" + ) + except sqlite3.OperationalError: + pass # Index already exists + cursor.execute("UPDATE schema_version SET version = 4") + if current_version < 5: + new_columns = [ + ("cache_read_tokens", "INTEGER DEFAULT 0"), + ("cache_write_tokens", "INTEGER DEFAULT 0"), + ("reasoning_tokens", "INTEGER DEFAULT 0"), + ("billing_provider", "TEXT"), + ("billing_base_url", "TEXT"), + ("billing_mode", "TEXT"), + ("estimated_cost_usd", "REAL"), + ("actual_cost_usd", "REAL"), + ("cost_status", "TEXT"), + ("cost_source", "TEXT"), + ("pricing_version", "TEXT"), + ] + for name, column_type in new_columns: + try: + # name and column_type come from the hardcoded tuple above, + # not user input. Double-quote identifier escaping is applied + # as defense-in-depth; SQLite DDL cannot be parameterized. + safe_name = name.replace('"', '""') + cursor.execute(f'ALTER TABLE sessions ADD COLUMN "{safe_name}" {column_type}') + except sqlite3.OperationalError: + pass + cursor.execute("UPDATE schema_version SET version = 5") + if current_version < 6: + # v6: add reasoning columns to messages table — preserves assistant + # reasoning text and structured reasoning_details across gateway + # session turns. Without these, reasoning chains are lost on + # session reload, breaking multi-turn reasoning continuity for + # providers that replay reasoning (OpenRouter, OpenAI, Nous). + for col_name, col_type in [ + ("reasoning", "TEXT"), + ("reasoning_details", "TEXT"), + ("codex_reasoning_items", "TEXT"), + ]: + try: + safe = col_name.replace('"', '""') + cursor.execute( + f'ALTER TABLE messages ADD COLUMN "{safe}" {col_type}' + ) + except sqlite3.OperationalError: + pass # Column already exists + cursor.execute("UPDATE schema_version SET version = 6") + if current_version < 7: + # v7: 积分系统 — user_credits 余额表 + credit_transactions 消费明细 + cursor.executescript(""" + CREATE TABLE IF NOT EXISTS user_credits ( + user_id TEXT PRIMARY KEY, + daily_free INTEGER DEFAULT 10000, + daily_used INTEGER DEFAULT 0, + paid_balance INTEGER DEFAULT 0, + last_reset TEXT, + created_at TEXT DEFAULT (datetime('now')), + updated_at TEXT DEFAULT (datetime('now')) + ); + CREATE TABLE IF NOT EXISTS credit_transactions ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + user_id TEXT NOT NULL, + session_id TEXT, + type TEXT, + credits_delta INTEGER, + raw_metric TEXT, + model TEXT, + created_at TEXT DEFAULT (datetime('now')) + ); + CREATE INDEX IF NOT EXISTS idx_credit_tx_user + ON credit_transactions(user_id, created_at DESC); + """) + cursor.execute("UPDATE schema_version SET version = 7") + if current_version < 8: + # v8: user_credits 加 phone + display_name（管理员看板辨识用户） + try: + cursor.execute("ALTER TABLE user_credits ADD COLUMN phone TEXT DEFAULT ''") + except Exception: + pass + try: + cursor.execute("ALTER TABLE user_credits ADD COLUMN display_name TEXT DEFAULT ''") + except Exception: + pass + cursor.execute("UPDATE schema_version SET version = 8") + + # Unique title index — always ensure it exists (safe to run after migrations + # since the title column is guaranteed to exist at this point) + try: + cursor.execute( + "CREATE UNIQUE INDEX IF NOT EXISTS idx_sessions_title_unique " + "ON sessions(title) WHERE title IS NOT NULL" + ) + except sqlite3.OperationalError: + pass # Index already exists + + # FTS5 setup (separate because CREATE VIRTUAL TABLE can't be in executescript with IF NOT EXISTS reliably) + try: + cursor.execute("SELECT * FROM messages_fts LIMIT 0") + except sqlite3.OperationalError: + cursor.executescript(FTS_SQL) + + self._conn.commit() + + # ========================================================================= + # Session lifecycle + # ========================================================================= + + def create_session( + self, + session_id: str, + source: str, + model: str = None, + model_config: Dict[str, Any] = None, + system_prompt: str = None, + user_id: str = None, + parent_session_id: str = None, + ) -> str: + """Create a new session record. Returns the session_id.""" + def _do(conn): + conn.execute( + """INSERT OR IGNORE INTO sessions (id, source, user_id, model, model_config, + system_prompt, parent_session_id, started_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?)""", + ( + session_id, + source, + user_id, + model, + json.dumps(model_config) if model_config else None, + system_prompt, + parent_session_id, + time.time(), + ), + ) + self._execute_write(_do) + return session_id + + def end_session(self, session_id: str, end_reason: str) -> None: + """Mark a session as ended.""" + def _do(conn): + conn.execute( + "UPDATE sessions SET ended_at = ?, end_reason = ? WHERE id = ?", + (time.time(), end_reason, session_id), + ) + self._execute_write(_do) + + def reopen_session(self, session_id: str) -> None: + """Clear ended_at/end_reason so a session can be resumed.""" + def _do(conn): + conn.execute( + "UPDATE sessions SET ended_at = NULL, end_reason = NULL WHERE id = ?", + (session_id,), + ) + self._execute_write(_do) + + def update_system_prompt(self, session_id: str, system_prompt: str) -> None: + """Store the full assembled system prompt snapshot.""" + def _do(conn): + conn.execute( + "UPDATE sessions SET system_prompt = ? WHERE id = ?", + (system_prompt, session_id), + ) + self._execute_write(_do) + + def update_token_counts( + self, + session_id: str, + input_tokens: int = 0, + output_tokens: int = 0, + model: str = None, + cache_read_tokens: int = 0, + cache_write_tokens: int = 0, + reasoning_tokens: int = 0, + estimated_cost_usd: Optional[float] = None, + actual_cost_usd: Optional[float] = None, + cost_status: Optional[str] = None, + cost_source: Optional[str] = None, + pricing_version: Optional[str] = None, + billing_provider: Optional[str] = None, + billing_base_url: Optional[str] = None, + billing_mode: Optional[str] = None, + absolute: bool = False, + ) -> None: + """Update token counters and backfill model if not already set. + + When *absolute* is False (default), values are **incremented** — use + this for per-API-call deltas (CLI path). + + When *absolute* is True, values are **set directly** — use this when + the caller already holds cumulative totals (gateway path, where the + cached agent accumulates across messages). + """ + if absolute: + sql = """UPDATE sessions SET + input_tokens = ?, + output_tokens = ?, + cache_read_tokens = ?, + cache_write_tokens = ?, + reasoning_tokens = ?, + estimated_cost_usd = COALESCE(?, 0), + actual_cost_usd = CASE + WHEN ? IS NULL THEN actual_cost_usd + ELSE ? + END, + cost_status = COALESCE(?, cost_status), + cost_source = COALESCE(?, cost_source), + pricing_version = COALESCE(?, pricing_version), + billing_provider = COALESCE(billing_provider, ?), + billing_base_url = COALESCE(billing_base_url, ?), + billing_mode = COALESCE(billing_mode, ?), + model = COALESCE(model, ?) + WHERE id = ?""" + else: + sql = """UPDATE sessions SET + input_tokens = input_tokens + ?, + output_tokens = output_tokens + ?, + cache_read_tokens = cache_read_tokens + ?, + cache_write_tokens = cache_write_tokens + ?, + reasoning_tokens = reasoning_tokens + ?, + estimated_cost_usd = COALESCE(estimated_cost_usd, 0) + COALESCE(?, 0), + actual_cost_usd = CASE + WHEN ? IS NULL THEN actual_cost_usd + ELSE COALESCE(actual_cost_usd, 0) + ? + END, + cost_status = COALESCE(?, cost_status), + cost_source = COALESCE(?, cost_source), + pricing_version = COALESCE(?, pricing_version), + billing_provider = COALESCE(billing_provider, ?), + billing_base_url = COALESCE(billing_base_url, ?), + billing_mode = COALESCE(billing_mode, ?), + model = COALESCE(model, ?) + WHERE id = ?""" + params = ( + input_tokens, + output_tokens, + cache_read_tokens, + cache_write_tokens, + reasoning_tokens, + estimated_cost_usd, + actual_cost_usd, + actual_cost_usd, + cost_status, + cost_source, + pricing_version, + billing_provider, + billing_base_url, + billing_mode, + model, + session_id, + ) + def _do(conn): + conn.execute(sql, params) + self._execute_write(_do) + + def ensure_session( + self, + session_id: str, + source: str = "unknown", + model: str = None, + ) -> None: + """Ensure a session row exists, creating it with minimal metadata if absent. + + Used by _flush_messages_to_session_db to recover from a failed + create_session() call (e.g. transient SQLite lock at agent startup). + INSERT OR IGNORE is safe to call even when the row already exists. + """ + def _do(conn): + conn.execute( + """INSERT OR IGNORE INTO sessions + (id, source, model, started_at) + VALUES (?, ?, ?, ?)""", + (session_id, source, model, time.time()), + ) + self._execute_write(_do) + + def get_session(self, session_id: str) -> Optional[Dict[str, Any]]: + """Get a session by ID.""" + with self._lock: + cursor = self._conn.execute( + "SELECT * FROM sessions WHERE id = ?", (session_id,) + ) + row = cursor.fetchone() + return dict(row) if row else None + + def resolve_session_id(self, session_id_or_prefix: str) -> Optional[str]: + """Resolve an exact or uniquely prefixed session ID to the full ID. + + Returns the exact ID when it exists. Otherwise treats the input as a + prefix and returns the single matching session ID if the prefix is + unambiguous. Returns None for no matches or ambiguous prefixes. + """ + exact = self.get_session(session_id_or_prefix) + if exact: + return exact["id"] + + escaped = ( + session_id_or_prefix + .replace("\\", "\\\\") + .replace("%", "\\%") + .replace("_", "\\_") + ) + with self._lock: + cursor = self._conn.execute( + "SELECT id FROM sessions WHERE id LIKE ? ESCAPE '\\' ORDER BY started_at DESC LIMIT 2", + (f"{escaped}%",), + ) + matches = [row["id"] for row in cursor.fetchall()] + if len(matches) == 1: + return matches[0] + return None + + # Maximum length for session titles + MAX_TITLE_LENGTH = 100 + + @staticmethod + def sanitize_title(title: Optional[str]) -> Optional[str]: + """Validate and sanitize a session title. + + - Strips leading/trailing whitespace + - Removes ASCII control characters (0x00-0x1F, 0x7F) and problematic + Unicode control chars (zero-width, RTL/LTR overrides, etc.) + - Collapses internal whitespace runs to single spaces + - Normalizes empty/whitespace-only strings to None + - Enforces MAX_TITLE_LENGTH + + Returns the cleaned title string or None. + Raises ValueError if the title exceeds MAX_TITLE_LENGTH after cleaning. + """ + if not title: + return None + + # Remove ASCII control characters (0x00-0x1F, 0x7F) but keep + # whitespace chars (\t=0x09, \n=0x0A, \r=0x0D) so they can be + # normalized to spaces by the whitespace collapsing step below + cleaned = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]', '', title) + + # Remove problematic Unicode control characters: + # - Zero-width chars (U+200B-U+200F, U+FEFF) + # - Directional overrides (U+202A-U+202E, U+2066-U+2069) + # - Object replacement (U+FFFC), interlinear annotation (U+FFF9-U+FFFB) + cleaned = re.sub( + r'[\u200b-\u200f\u2028-\u202e\u2060-\u2069\ufeff\ufffc\ufff9-\ufffb]', + '', cleaned, + ) + + # Collapse internal whitespace runs and strip + cleaned = re.sub(r'\s+', ' ', cleaned).strip() + + if not cleaned: + return None + + if len(cleaned) > SessionDB.MAX_TITLE_LENGTH: + raise ValueError( + f"Title too long ({len(cleaned)} chars, max {SessionDB.MAX_TITLE_LENGTH})" + ) + + return cleaned + + def set_session_title(self, session_id: str, title: str) -> bool: + """Set or update a session's title. + + Returns True if session was found and title was set. + Raises ValueError if title is already in use by another session, + or if the title fails validation (too long, invalid characters). + Empty/whitespace-only strings are normalized to None (clearing the title). + """ + title = self.sanitize_title(title) + def _do(conn): + if title: + # Check uniqueness (allow the same session to keep its own title) + cursor = conn.execute( + "SELECT id FROM sessions WHERE title = ? AND id != ?", + (title, session_id), + ) + conflict = cursor.fetchone() + if conflict: + raise ValueError( + f"Title '{title}' is already in use by session {conflict['id']}" + ) + cursor = conn.execute( + "UPDATE sessions SET title = ? WHERE id = ?", + (title, session_id), + ) + return cursor.rowcount + rowcount = self._execute_write(_do) + return rowcount > 0 + + def get_session_title(self, session_id: str) -> Optional[str]: + """Get the title for a session, or None.""" + with self._lock: + cursor = self._conn.execute( + "SELECT title FROM sessions WHERE id = ?", (session_id,) + ) + row = cursor.fetchone() + return row["title"] if row else None + + def get_session_by_title(self, title: str) -> Optional[Dict[str, Any]]: + """Look up a session by exact title. Returns session dict or None.""" + with self._lock: + cursor = self._conn.execute( + "SELECT * FROM sessions WHERE title = ?", (title,) + ) + row = cursor.fetchone() + return dict(row) if row else None + + def resolve_session_by_title(self, title: str) -> Optional[str]: + """Resolve a title to a session ID, preferring the latest in a lineage. + + If the exact title exists, returns that session's ID. + If not, searches for "title #N" variants and returns the latest one. + If the exact title exists AND numbered variants exist, returns the + latest numbered variant (the most recent continuation). + """ + # First try exact match + exact = self.get_session_by_title(title) + + # Also search for numbered variants: "title #2", "title #3", etc. + # Escape SQL LIKE wildcards (%, _) in the title to prevent false matches + escaped = title.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_") + with self._lock: + cursor = self._conn.execute( + "SELECT id, title, started_at FROM sessions " + "WHERE title LIKE ? ESCAPE '\\' ORDER BY started_at DESC", + (f"{escaped} #%",), + ) + numbered = cursor.fetchall() + + if numbered: + # Return the most recent numbered variant + return numbered[0]["id"] + elif exact: + return exact["id"] + return None + + def get_next_title_in_lineage(self, base_title: str) -> str: + """Generate the next title in a lineage (e.g., "my session" → "my session #2"). + + Strips any existing " #N" suffix to find the base name, then finds + the highest existing number and increments. + """ + # Strip existing #N suffix to find the true base + match = re.match(r'^(.*?) #(\d+)$', base_title) + if match: + base = match.group(1) + else: + base = base_title + + # Find all existing numbered variants + # Escape SQL LIKE wildcards (%, _) in the base to prevent false matches + escaped = base.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_") + with self._lock: + cursor = self._conn.execute( + "SELECT title FROM sessions WHERE title = ? OR title LIKE ? ESCAPE '\\'", + (base, f"{escaped} #%"), + ) + existing = [row["title"] for row in cursor.fetchall()] + + if not existing: + return base # No conflict, use the base name as-is + + # Find the highest number + max_num = 1 # The unnumbered original counts as #1 + for t in existing: + m = re.match(r'^.* #(\d+)$', t) + if m: + max_num = max(max_num, int(m.group(1))) + + return f"{base} #{max_num + 1}" + + def list_sessions_rich( + self, + source: str = None, + exclude_sources: List[str] = None, + limit: int = 20, + offset: int = 0, + include_children: bool = False, + ) -> List[Dict[str, Any]]: + """List sessions with preview (first user message) and last active timestamp. + + Returns dicts with keys: id, source, model, title, started_at, ended_at, + message_count, preview (first 60 chars of first user message), + last_active (timestamp of last message). + + Uses a single query with correlated subqueries instead of N+2 queries. + + By default, child sessions (subagent runs, compression continuations) + are excluded. Pass ``include_children=True`` to include them. + """ + where_clauses = [] + params = [] + + if not include_children: + where_clauses.append("s.parent_session_id IS NULL") + + if source: + where_clauses.append("s.source = ?") + params.append(source) + if exclude_sources: + placeholders = ",".join("?" for _ in exclude_sources) + where_clauses.append(f"s.source NOT IN ({placeholders})") + params.extend(exclude_sources) + + where_sql = f"WHERE {' AND '.join(where_clauses)}" if where_clauses else "" + query = f""" + SELECT s.*, + COALESCE( + (SELECT SUBSTR(REPLACE(REPLACE(m.content, X'0A', ' '), X'0D', ' '), 1, 63) + FROM messages m + WHERE m.session_id = s.id AND m.role = 'user' AND m.content IS NOT NULL + ORDER BY m.timestamp, m.id LIMIT 1), + '' + ) AS _preview_raw, + COALESCE( + (SELECT MAX(m2.timestamp) FROM messages m2 WHERE m2.session_id = s.id), + s.started_at + ) AS last_active + FROM sessions s + {where_sql} + ORDER BY s.started_at DESC + LIMIT ? OFFSET ? + """ + params.extend([limit, offset]) + with self._lock: + cursor = self._conn.execute(query, params) + rows = cursor.fetchall() + sessions = [] + for row in rows: + s = dict(row) + # Build the preview from the raw substring + raw = s.pop("_preview_raw", "").strip() + if raw: + text = raw[:60] + s["preview"] = text + ("..." if len(raw) > 60 else "") + else: + s["preview"] = "" + sessions.append(s) + + return sessions + + # ========================================================================= + # Message storage + # ========================================================================= + + def append_message( + self, + session_id: str, + role: str, + content: str = None, + tool_name: str = None, + tool_calls: Any = None, + tool_call_id: str = None, + token_count: int = None, + finish_reason: str = None, + reasoning: str = None, + reasoning_details: Any = None, + codex_reasoning_items: Any = None, + ) -> int: + """ + Append a message to a session. Returns the message row ID. + + Also increments the session's message_count (and tool_call_count + if role is 'tool' or tool_calls is present). + """ + # Serialize structured fields to JSON before entering the write txn + reasoning_details_json = ( + json.dumps(reasoning_details) + if reasoning_details else None + ) + codex_items_json = ( + json.dumps(codex_reasoning_items) + if codex_reasoning_items else None + ) + tool_calls_json = json.dumps(tool_calls) if tool_calls else None + + # Pre-compute tool call count + num_tool_calls = 0 + if tool_calls is not None: + num_tool_calls = len(tool_calls) if isinstance(tool_calls, list) else 1 + + def _do(conn): + cursor = conn.execute( + """INSERT INTO messages (session_id, role, content, tool_call_id, + tool_calls, tool_name, timestamp, token_count, finish_reason, + reasoning, reasoning_details, codex_reasoning_items) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""", + ( + session_id, + role, + content, + tool_call_id, + tool_calls_json, + tool_name, + time.time(), + token_count, + finish_reason, + reasoning, + reasoning_details_json, + codex_items_json, + ), + ) + msg_id = cursor.lastrowid + + # Update counters + if num_tool_calls > 0: + conn.execute( + """UPDATE sessions SET message_count = message_count + 1, + tool_call_count = tool_call_count + ? WHERE id = ?""", + (num_tool_calls, session_id), + ) + else: + conn.execute( + "UPDATE sessions SET message_count = message_count + 1 WHERE id = ?", + (session_id,), + ) + return msg_id + + return self._execute_write(_do) + + def get_messages(self, session_id: str) -> List[Dict[str, Any]]: + """Load all messages for a session, ordered by timestamp.""" + with self._lock: + cursor = self._conn.execute( + "SELECT * FROM messages WHERE session_id = ? ORDER BY timestamp, id", + (session_id,), + ) + rows = cursor.fetchall() + result = [] + for row in rows: + msg = dict(row) + if msg.get("tool_calls"): + try: + msg["tool_calls"] = json.loads(msg["tool_calls"]) + except (json.JSONDecodeError, TypeError): + logger.warning("Failed to deserialize tool_calls in get_messages, falling back to []") + msg["tool_calls"] = [] + result.append(msg) + return result + + def get_messages_as_conversation(self, session_id: str) -> List[Dict[str, Any]]: + """ + Load messages in the OpenAI conversation format (role + content dicts). + Used by the gateway to restore conversation history. + """ + with self._lock: + cursor = self._conn.execute( + "SELECT role, content, tool_call_id, tool_calls, tool_name, " + "reasoning, reasoning_details, codex_reasoning_items " + "FROM messages WHERE session_id = ? ORDER BY timestamp, id", + (session_id,), + ) + rows = cursor.fetchall() + messages = [] + for row in rows: + msg = {"role": row["role"], "content": row["content"]} + if row["tool_call_id"]: + msg["tool_call_id"] = row["tool_call_id"] + if row["tool_name"]: + msg["tool_name"] = row["tool_name"] + if row["tool_calls"]: + try: + msg["tool_calls"] = json.loads(row["tool_calls"]) + except (json.JSONDecodeError, TypeError): + logger.warning("Failed to deserialize tool_calls in conversation replay, falling back to []") + msg["tool_calls"] = [] + # Restore reasoning fields on assistant messages so providers + # that replay reasoning (OpenRouter, OpenAI, Nous) receive + # coherent multi-turn reasoning context. + if row["role"] == "assistant": + if row["reasoning"]: + msg["reasoning"] = row["reasoning"] + if row["reasoning_details"]: + try: + msg["reasoning_details"] = json.loads(row["reasoning_details"]) + except (json.JSONDecodeError, TypeError): + logger.warning("Failed to deserialize reasoning_details, falling back to None") + msg["reasoning_details"] = None + if row["codex_reasoning_items"]: + try: + msg["codex_reasoning_items"] = json.loads(row["codex_reasoning_items"]) + except (json.JSONDecodeError, TypeError): + logger.warning("Failed to deserialize codex_reasoning_items, falling back to None") + msg["codex_reasoning_items"] = None + messages.append(msg) + return messages + + # ========================================================================= + # Search + # ========================================================================= + + @staticmethod + def _sanitize_fts5_query(query: str) -> str: + """Sanitize user input for safe use in FTS5 MATCH queries. + + FTS5 has its own query syntax where characters like ``"``, ``(``, ``)``, + ``+``, ``*``, ``{``, ``}`` and bare boolean operators (``AND``, ``OR``, + ``NOT``) have special meaning. Passing raw user input directly to + MATCH can cause ``sqlite3.OperationalError``. + + Strategy: + - Preserve properly paired quoted phrases (``"exact phrase"``) + - Strip unmatched FTS5-special characters that would cause errors + - Wrap unquoted hyphenated and dotted terms in quotes so FTS5 + matches them as exact phrases instead of splitting on the + hyphen/dot (e.g. ``chat-send``, ``P2.2``, ``my-app.config.ts``) + """ + # Step 1: Extract balanced double-quoted phrases and protect them + # from further processing via numbered placeholders. + _quoted_parts: list = [] + + def _preserve_quoted(m: re.Match) -> str: + _quoted_parts.append(m.group(0)) + return f"\x00Q{len(_quoted_parts) - 1}\x00" + + sanitized = re.sub(r'"[^"]*"', _preserve_quoted, query) + + # Step 2: Strip remaining (unmatched) FTS5-special characters + sanitized = re.sub(r'[+{}()\"^]', " ", sanitized) + + # Step 3: Collapse repeated * (e.g. "***") into a single one, + # and remove leading * (prefix-only needs at least one char before *) + sanitized = re.sub(r"\*+", "*", sanitized) + sanitized = re.sub(r"(^|\s)\*", r"\1", sanitized) + + # Step 4: Remove dangling boolean operators at start/end that would + # cause syntax errors (e.g. "hello AND" or "OR world") + sanitized = re.sub(r"(?i)^(AND|OR|NOT)\b\s*", "", sanitized.strip()) + sanitized = re.sub(r"(?i)\s+(AND|OR|NOT)\s*$", "", sanitized.strip()) + + # Step 5: Wrap unquoted dotted and/or hyphenated terms in double + # quotes. FTS5's tokenizer splits on dots and hyphens, turning + # ``chat-send`` into ``chat AND send`` and ``P2.2`` into ``p2 AND 2``. + # Quoting preserves phrase semantics. A single pass avoids the + # double-quoting bug that would occur if dotted and hyphenated + # patterns were applied sequentially (e.g. ``my-app.config``). + sanitized = re.sub(r"\b(\w+(?:[.-]\w+)+)\b", r'"\1"', sanitized) + + # Step 6: Restore preserved quoted phrases + for i, quoted in enumerate(_quoted_parts): + sanitized = sanitized.replace(f"\x00Q{i}\x00", quoted) + + return sanitized.strip() + + def search_messages( + self, + query: str, + source_filter: List[str] = None, + exclude_sources: List[str] = None, + role_filter: List[str] = None, + limit: int = 20, + offset: int = 0, + ) -> List[Dict[str, Any]]: + """ + Full-text search across session messages using FTS5. + + Supports FTS5 query syntax: + - Simple keywords: "docker deployment" + - Phrases: '"exact phrase"' + - Boolean: "docker OR kubernetes", "python NOT java" + - Prefix: "deploy*" + + Returns matching messages with session metadata, content snippet, + and surrounding context (1 message before and after the match). + """ + if not query or not query.strip(): + return [] + + query = self._sanitize_fts5_query(query) + if not query: + return [] + + # Build WHERE clauses dynamically + where_clauses = ["messages_fts MATCH ?"] + params: list = [query] + + if source_filter is not None: + source_placeholders = ",".join("?" for _ in source_filter) + where_clauses.append(f"s.source IN ({source_placeholders})") + params.extend(source_filter) + + if exclude_sources is not None: + exclude_placeholders = ",".join("?" for _ in exclude_sources) + where_clauses.append(f"s.source NOT IN ({exclude_placeholders})") + params.extend(exclude_sources) + + if role_filter: + role_placeholders = ",".join("?" for _ in role_filter) + where_clauses.append(f"m.role IN ({role_placeholders})") + params.extend(role_filter) + + where_sql = " AND ".join(where_clauses) + params.extend([limit, offset]) + + sql = f""" + SELECT + m.id, + m.session_id, + m.role, + snippet(messages_fts, 0, '>>>', '<<<', '...', 40) AS snippet, + m.content, + m.timestamp, + m.tool_name, + s.source, + s.model, + s.started_at AS session_started + FROM messages_fts + JOIN messages m ON m.id = messages_fts.rowid + JOIN sessions s ON s.id = m.session_id + WHERE {where_sql} + ORDER BY rank + LIMIT ? OFFSET ? + """ + + with self._lock: + try: + cursor = self._conn.execute(sql, params) + except sqlite3.OperationalError: + # FTS5 query syntax error despite sanitization — return empty + return [] + matches = [dict(row) for row in cursor.fetchall()] + + # Add surrounding context (1 message before + after each match). + # Done outside the lock so we don't hold it across N sequential queries. + for match in matches: + try: + with self._lock: + ctx_cursor = self._conn.execute( + """SELECT role, content FROM messages + WHERE session_id = ? AND id >= ? - 1 AND id <= ? + 1 + ORDER BY id""", + (match["session_id"], match["id"], match["id"]), + ) + context_msgs = [ + {"role": r["role"], "content": (r["content"] or "")[:200]} + for r in ctx_cursor.fetchall() + ] + match["context"] = context_msgs + except Exception: + match["context"] = [] + + # Remove full content from result (snippet is enough, saves tokens) + for match in matches: + match.pop("content", None) + + return matches + + def search_sessions( + self, + source: str = None, + limit: int = 20, + offset: int = 0, + ) -> List[Dict[str, Any]]: + """List sessions, optionally filtered by source.""" + with self._lock: + if source: + cursor = self._conn.execute( + "SELECT * FROM sessions WHERE source = ? ORDER BY started_at DESC LIMIT ? OFFSET ?", + (source, limit, offset), + ) + else: + cursor = self._conn.execute( + "SELECT * FROM sessions ORDER BY started_at DESC LIMIT ? OFFSET ?", + (limit, offset), + ) + return [dict(row) for row in cursor.fetchall()] + + # ========================================================================= + # Utility + # ========================================================================= + + def session_count(self, source: str = None) -> int: + """Count sessions, optionally filtered by source.""" + with self._lock: + if source: + cursor = self._conn.execute( + "SELECT COUNT(*) FROM sessions WHERE source = ?", (source,) + ) + else: + cursor = self._conn.execute("SELECT COUNT(*) FROM sessions") + return cursor.fetchone()[0] + + def message_count(self, session_id: str = None) -> int: + """Count messages, optionally for a specific session.""" + with self._lock: + if session_id: + cursor = self._conn.execute( + "SELECT COUNT(*) FROM messages WHERE session_id = ?", (session_id,) + ) + else: + cursor = self._conn.execute("SELECT COUNT(*) FROM messages") + return cursor.fetchone()[0] + + # ========================================================================= + # Export and cleanup + # ========================================================================= + + def export_session(self, session_id: str) -> Optional[Dict[str, Any]]: + """Export a single session with all its messages as a dict.""" + session = self.get_session(session_id) + if not session: + return None + messages = self.get_messages(session_id) + return {**session, "messages": messages} + + def export_all(self, source: str = None) -> List[Dict[str, Any]]: + """ + Export all sessions (with messages) as a list of dicts. + Suitable for writing to a JSONL file for backup/analysis. + """ + sessions = self.search_sessions(source=source, limit=100000) + results = [] + for session in sessions: + messages = self.get_messages(session["id"]) + results.append({**session, "messages": messages}) + return results + + def clear_messages(self, session_id: str) -> None: + """Delete all messages for a session and reset its counters.""" + def _do(conn): + conn.execute( + "DELETE FROM messages WHERE session_id = ?", (session_id,) + ) + conn.execute( + "UPDATE sessions SET message_count = 0, tool_call_count = 0 WHERE id = ?", + (session_id,), + ) + self._execute_write(_do) + + def delete_session(self, session_id: str) -> bool: + """Delete a session and all its messages. + + Child sessions are orphaned (parent_session_id set to NULL) rather + than cascade-deleted, so they remain accessible independently. + Returns True if the session was found and deleted. + """ + def _do(conn): + cursor = conn.execute( + "SELECT COUNT(*) FROM sessions WHERE id = ?", (session_id,) + ) + if cursor.fetchone()[0] == 0: + return False + # Orphan child sessions so FK constraint is satisfied + conn.execute( + "UPDATE sessions SET parent_session_id = NULL " + "WHERE parent_session_id = ?", + (session_id,), + ) + conn.execute("DELETE FROM messages WHERE session_id = ?", (session_id,)) + conn.execute("DELETE FROM sessions WHERE id = ?", (session_id,)) + return True + return self._execute_write(_do) + + def prune_sessions(self, older_than_days: int = 90, source: str = None) -> int: + """Delete sessions older than N days. Returns count of deleted sessions. + + Only prunes ended sessions (not active ones). Child sessions outside + the prune window are orphaned (parent_session_id set to NULL) rather + than cascade-deleted. + """ + cutoff = time.time() - (older_than_days * 86400) + + def _do(conn): + if source: + cursor = conn.execute( + """SELECT id FROM sessions + WHERE started_at < ? AND ended_at IS NOT NULL AND source = ?""", + (cutoff, source), + ) + else: + cursor = conn.execute( + "SELECT id FROM sessions WHERE started_at < ? AND ended_at IS NOT NULL", + (cutoff,), + ) + session_ids = set(row["id"] for row in cursor.fetchall()) + + if not session_ids: + return 0 + + # Orphan any sessions whose parent is about to be deleted + placeholders = ",".join("?" * len(session_ids)) + conn.execute( + f"UPDATE sessions SET parent_session_id = NULL " + f"WHERE parent_session_id IN ({placeholders})", + list(session_ids), + ) + + for sid in session_ids: + conn.execute("DELETE FROM messages WHERE session_id = ?", (sid,)) + conn.execute("DELETE FROM sessions WHERE id = ?", (sid,)) + return len(session_ids) + + return self._execute_write(_do) + + def get_sessions_for_user( + self, + user_id: str, + source: str = "mindos", + limit: int = 50, + ) -> List[Dict[str, Any]]: + """MindOS NEXT — 返回指定用户的会话列表（按最近活跃倒序）。 + + 包装 list_sessions_rich()，增加 user_id 过滤。 + 返回字段与 list_sessions_rich() 一致： + id, title, preview, last_active, started_at, message_count 等。 + + Args: + user_id: MindPass 用户 ID。 + source: 会话来源标签，mindos_sse.py 创建会话时传 "mindos"。 + limit: 最多返回条数，默认 50。 + """ + query = """ + SELECT s.*, + COALESCE( + (SELECT SUBSTR(REPLACE(REPLACE(m.content, X'0A', ' '), X'0D', ' '), 1, 63) + FROM messages m + WHERE m.session_id = s.id AND m.role = 'user' AND m.content IS NOT NULL + ORDER BY m.timestamp, m.id LIMIT 1), + '' + ) AS _preview_raw, + COALESCE( + (SELECT MAX(m2.timestamp) FROM messages m2 WHERE m2.session_id = s.id), + s.started_at + ) AS last_active, + ( + COALESCE( + (SELECT SUM( + (LENGTH(m3.tool_calls) - LENGTH(REPLACE(m3.tool_calls, '"write_file"', ''))) / LENGTH('"write_file"') + ) FROM messages m3 + WHERE m3.session_id = s.id + AND m3.tool_calls LIKE '%"write_file"%'), + 0) + + + (SELECT COUNT(*) FROM messages m4 + WHERE m4.session_id = s.id + AND m4.tool_calls LIKE '%"patch"%') + + + (SELECT COUNT(*) FROM messages m5 + WHERE m5.session_id = s.id + AND m5.role = 'assistant' AND m5.content LIKE '%"type"%audio"%') + ) AS work_product_count + FROM sessions s + WHERE s.user_id = ? + AND s.parent_session_id IS NULL + ORDER BY last_active DESC + LIMIT ? + """ + with self._lock: + cursor = self._conn.execute(query, (user_id, limit)) + rows = cursor.fetchall() + + sessions = [] + for row in rows: + s = dict(row) + raw = s.pop("_preview_raw", "").strip() + s["preview"] = (raw[:60] + ("..." if len(raw) > 60 else "")) if raw else "" + sessions.append(s) + return sessions + + # ========================================================================= + # Credits system (P1) + # ========================================================================= + + def get_or_create_credits(self, user_id: str, phone: str = "", display_name: str = "") -> Dict[str, Any]: + """ + 获取或创建用户积分记录。 + 自动执行日重置：如果 last_reset 不是今天，则重置 daily_used=0。 + 若提供 phone/display_name，顺带更新（方便管理员辨识用户）。 + """ + import datetime as _dt + today = _dt.date.today().isoformat() + + def _do(conn): + conn.execute( + "INSERT OR IGNORE INTO user_credits (user_id, last_reset) VALUES (?, ?)", + (user_id, today), + ) + # 自动日重置 + conn.execute( + "UPDATE user_credits SET daily_used = 0, last_reset = ?, " + "updated_at = datetime('now') " + "WHERE user_id = ? AND (last_reset IS NULL OR last_reset < ?)", + (today, user_id, today), + ) + # 更新用户身份信息（非空才覆盖） + if phone: + conn.execute("UPDATE user_credits SET phone = ? WHERE user_id = ? AND (phone IS NULL OR phone = '')", (phone, user_id)) + if display_name: + conn.execute("UPDATE user_credits SET display_name = ? WHERE user_id = ? AND (display_name IS NULL OR display_name = '')", (display_name, user_id)) + self._execute_write(_do) + + with self._lock: + row = self._conn.execute( + "SELECT * FROM user_credits WHERE user_id = ?", (user_id,) + ).fetchone() + return dict(row) if row else {"user_id": user_id, "daily_free": 10000, "daily_used": 0, "paid_balance": 0} + + def check_credits(self, user_id: str, phone: str = "", display_name: str = "") -> Dict[str, Any]: + """检查用户是否有足够积分。返回 {allowed, remaining, daily_free, daily_used, paid_balance}。""" + c = self.get_or_create_credits(user_id, phone=phone, display_name=display_name) + daily_remaining = max(0, c["daily_free"] - c["daily_used"]) + total_remaining = daily_remaining + c["paid_balance"] + return { + "allowed": total_remaining > 0, + "remaining": total_remaining, + "dailyFree": c["daily_free"], + "dailyUsed": c["daily_used"], + "dailyRemaining": daily_remaining, + "paidBalance": c["paid_balance"], + } + + def deduct_credits( + self, + user_id: str, + credits: int, + tx_type: str, + session_id: str = None, + model: str = None, + raw_metric: str = None, + ) -> None: + """扣减积分并记录明细。优先扣日免费额度，不足部分扣充值余额。""" + def _do(conn): + row = conn.execute( + "SELECT daily_free, daily_used, paid_balance FROM user_credits WHERE user_id = ?", + (user_id,), + ).fetchone() + if not row: + return + daily_remaining = max(0, row[0] - row[1]) + from_daily = min(credits, daily_remaining) + from_paid = credits - from_daily + conn.execute( + "UPDATE user_credits SET daily_used = daily_used + ?, " + "paid_balance = MAX(0, paid_balance - ?), " + "updated_at = datetime('now') WHERE user_id = ?", + (from_daily, from_paid, user_id), + ) + conn.execute( + "INSERT INTO credit_transactions " + "(user_id, session_id, type, credits_delta, raw_metric, model) " + "VALUES (?, ?, ?, ?, ?, ?)", + (user_id, session_id, tx_type, -credits, raw_metric, model), + ) + self._execute_write(_do) + + def admin_dashboard(self, days: int = 7) -> Dict[str, Any]: + """管理员看板：活跃用户数 + 按用量排行。""" + with self._lock: + # 活跃用户（days 天内有 session 的用户） + active = self._conn.execute( + "SELECT COUNT(DISTINCT user_id) FROM sessions " + "WHERE started_at > ? AND user_id IS NOT NULL", + ((__import__("time").time() - days * 86400),), + ).fetchone()[0] + + # 所有用户的积分状态（按已用排序） + rows = self._conn.execute( + "SELECT uc.user_id, uc.phone, uc.display_name, " + "uc.daily_free, uc.daily_used, uc.paid_balance, " + "uc.last_reset, uc.updated_at, " + "(SELECT COUNT(*) FROM sessions s WHERE s.user_id = uc.user_id) AS session_count " + "FROM user_credits uc ORDER BY uc.daily_used DESC" + ).fetchall() + + # 总消费 credits（所有 transactions 的 sum） + total_spent = self._conn.execute( + "SELECT COALESCE(SUM(ABS(credits_delta)), 0) FROM credit_transactions" + ).fetchone()[0] + + users = [] + for r in rows: + d = dict(r) + d["dailyRemaining"] = max(0, d["daily_free"] - d["daily_used"]) + users.append(d) + + return { + "activeUsers": active, + "activeDays": days, + "totalUsers": len(users), + "totalCreditsSpent": total_spent, + "users": users, + } + + def admin_topup(self, user_id: str, amount: int, reason: str = "admin_topup") -> Dict[str, Any]: + """管理员手动充值 paid_balance。""" + import datetime as _dt + today = _dt.date.today().isoformat() + + def _do(conn): + conn.execute( + "INSERT OR IGNORE INTO user_credits (user_id, last_reset) VALUES (?, ?)", + (user_id, today), + ) + conn.execute( + "UPDATE user_credits SET paid_balance = paid_balance + ?, " + "updated_at = datetime('now') WHERE user_id = ?", + (amount, user_id), + ) + conn.execute( + "INSERT INTO credit_transactions " + "(user_id, type, credits_delta, raw_metric) " + "VALUES (?, ?, ?, ?)", + (user_id, "admin_topup", amount, reason), + ) + self._execute_write(_do) + return self.check_credits(user_id) diff --git a/mindcli/_vendor/mcp_serve.py b/mindcli/_vendor/mcp_serve.py new file mode 100644 index 0000000..e8294d1 --- /dev/null +++ b/mindcli/_vendor/mcp_serve.py @@ -0,0 +1,867 @@ +""" +Hermes MCP Server — expose messaging conversations as MCP tools. + +Starts a stdio MCP server that lets any MCP client (Claude Code, Cursor, Codex, +etc.) list conversations, read message history, send messages, poll for live +events, and manage approval requests across all connected platforms. + +Matches OpenClaw's 9-tool MCP channel bridge surface: + conversations_list, conversation_get, messages_read, attachments_fetch, + events_poll, events_wait, messages_send, permissions_list_open, + permissions_respond + +Plus: channels_list (Hermes-specific extra) + +Usage: + hermes mcp serve + hermes mcp serve --verbose + +MCP client config (e.g. claude_desktop_config.json): + { + "mcpServers": { + "hermes": { + "command": "hermes", + "args": ["mcp", "serve"] + } + } + } +""" + +from __future__ import annotations + +import json +import logging +import os +import re +import sys +import threading +import time +from dataclasses import dataclass, field +from pathlib import Path +from typing import Dict, List, Optional + +logger = logging.getLogger("hermes.mcp_serve") + +# --------------------------------------------------------------------------- +# Lazy MCP SDK import +# --------------------------------------------------------------------------- + +_MCP_SERVER_AVAILABLE = False +try: + from mcp.server.fastmcp import FastMCP + + _MCP_SERVER_AVAILABLE = True +except ImportError: + FastMCP = None # type: ignore[assignment,misc] + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + +def _get_sessions_dir() -> Path: + """Return the sessions directory using HERMES_HOME.""" + try: + from hermes_constants import get_hermes_home + return get_hermes_home() / "sessions" + except ImportError: + return Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes")) / "sessions" + + +def _get_session_db(): + """Get a SessionDB instance for reading message transcripts.""" + try: + from hermes_state import SessionDB + return SessionDB() + except Exception as e: + logger.debug("SessionDB unavailable: %s", e) + return None + + +def _load_sessions_index() -> dict: + """Load the gateway sessions.json index directly. + + Returns a dict of session_key -> entry_dict with platform routing info. + This avoids importing the full SessionStore which needs GatewayConfig. + """ + sessions_file = _get_sessions_dir() / "sessions.json" + if not sessions_file.exists(): + return {} + try: + with open(sessions_file, "r", encoding="utf-8") as f: + return json.load(f) + except Exception as e: + logger.debug("Failed to load sessions.json: %s", e) + return {} + + +def _load_channel_directory() -> dict: + """Load the cached channel directory for available targets.""" + try: + from hermes_constants import get_hermes_home + directory_file = get_hermes_home() / "channel_directory.json" + except ImportError: + directory_file = Path( + os.environ.get("HERMES_HOME", Path.home() / ".hermes") + ) / "channel_directory.json" + + if not directory_file.exists(): + return {} + try: + with open(directory_file, "r", encoding="utf-8") as f: + return json.load(f) + except Exception as e: + logger.debug("Failed to load channel_directory.json: %s", e) + return {} + + +def _extract_message_content(msg: dict) -> str: + """Extract text content from a message, handling multi-part content.""" + content = msg.get("content", "") + if isinstance(content, list): + text_parts = [ + p.get("text", "") for p in content + if isinstance(p, dict) and p.get("type") == "text" + ] + return "\n".join(text_parts) + return str(content) if content else "" + + +def _extract_attachments(msg: dict) -> List[dict]: + """Extract non-text attachments from a message. + + Finds: multi-part image/file content blocks, MEDIA: tags in text, + image URLs, and file references. + """ + attachments = [] + content = msg.get("content", "") + + # Multi-part content blocks (image_url, file, etc.) + if isinstance(content, list): + for part in content: + if not isinstance(part, dict): + continue + ptype = part.get("type", "") + if ptype == "image_url": + url = part.get("image_url", {}).get("url", "") if isinstance(part.get("image_url"), dict) else "" + if url: + attachments.append({"type": "image", "url": url}) + elif ptype == "image": + url = part.get("url", part.get("source", {}).get("url", "")) + if url: + attachments.append({"type": "image", "url": url}) + elif ptype not in ("text",): + # Unknown non-text content type + attachments.append({"type": ptype, "data": part}) + + # MEDIA: tags in text content + text = _extract_message_content(msg) + if text: + media_pattern = re.compile(r'MEDIA:\s*(\S+)') + for match in media_pattern.finditer(text): + path = match.group(1) + attachments.append({"type": "media", "path": path}) + + return attachments + + +# --------------------------------------------------------------------------- +# Event Bridge — polls SessionDB for new messages, maintains event queue +# --------------------------------------------------------------------------- + +QUEUE_LIMIT = 1000 +POLL_INTERVAL = 0.2 # seconds between DB polls (200ms) + + +@dataclass +class QueueEvent: + """An event in the bridge's in-memory queue.""" + cursor: int + type: str # "message", "approval_requested", "approval_resolved" + session_key: str = "" + data: dict = field(default_factory=dict) + + +class EventBridge: + """Background poller that watches SessionDB for new messages and + maintains an in-memory event queue with waiter support. + + This is the Hermes equivalent of OpenClaw's WebSocket gateway bridge. + Instead of WebSocket events, we poll the SQLite database for changes. + """ + + def __init__(self): + self._queue: List[QueueEvent] = [] + self._cursor = 0 + self._lock = threading.Lock() + self._new_event = threading.Event() + self._running = False + self._thread: Optional[threading.Thread] = None + self._last_poll_timestamps: Dict[str, float] = {} # session_key -> unix timestamp + # In-memory approval tracking (populated from events) + self._pending_approvals: Dict[str, dict] = {} + # mtime cache — skip expensive work when files haven't changed + self._sessions_json_mtime: float = 0.0 + self._state_db_mtime: float = 0.0 + self._cached_sessions_index: dict = {} + + def start(self): + """Start the background polling thread.""" + if self._running: + return + self._running = True + self._thread = threading.Thread(target=self._poll_loop, daemon=True) + self._thread.start() + logger.debug("EventBridge started") + + def stop(self): + """Stop the background polling thread.""" + self._running = False + self._new_event.set() # Wake any waiters + if self._thread: + self._thread.join(timeout=5) + logger.debug("EventBridge stopped") + + def poll_events( + self, + after_cursor: int = 0, + session_key: Optional[str] = None, + limit: int = 20, + ) -> dict: + """Return events since after_cursor, optionally filtered by session_key.""" + with self._lock: + events = [ + e for e in self._queue + if e.cursor > after_cursor + and (not session_key or e.session_key == session_key) + ][:limit] + + next_cursor = events[-1].cursor if events else after_cursor + return { + "events": [ + {"cursor": e.cursor, "type": e.type, + "session_key": e.session_key, **e.data} + for e in events + ], + "next_cursor": next_cursor, + } + + def wait_for_event( + self, + after_cursor: int = 0, + session_key: Optional[str] = None, + timeout_ms: int = 30000, + ) -> Optional[dict]: + """Block until a matching event arrives or timeout expires.""" + deadline = time.monotonic() + (timeout_ms / 1000.0) + + while time.monotonic() < deadline: + with self._lock: + for e in self._queue: + if e.cursor > after_cursor and ( + not session_key or e.session_key == session_key + ): + return { + "cursor": e.cursor, "type": e.type, + "session_key": e.session_key, **e.data, + } + + remaining = deadline - time.monotonic() + if remaining <= 0: + break + self._new_event.clear() + self._new_event.wait(timeout=min(remaining, POLL_INTERVAL)) + + return None + + def list_pending_approvals(self) -> List[dict]: + """List approval requests observed during this bridge session.""" + with self._lock: + return sorted( + self._pending_approvals.values(), + key=lambda a: a.get("created_at", ""), + ) + + def respond_to_approval(self, approval_id: str, decision: str) -> dict: + """Resolve a pending approval (best-effort without gateway IPC).""" + with self._lock: + approval = self._pending_approvals.pop(approval_id, None) + + if not approval: + return {"error": f"Approval not found: {approval_id}"} + + self._enqueue(QueueEvent( + cursor=0, # Will be set by _enqueue + type="approval_resolved", + session_key=approval.get("session_key", ""), + data={"approval_id": approval_id, "decision": decision}, + )) + + return {"resolved": True, "approval_id": approval_id, "decision": decision} + + def _enqueue(self, event: QueueEvent) -> None: + """Add an event to the queue and wake any waiters.""" + with self._lock: + self._cursor += 1 + event.cursor = self._cursor + self._queue.append(event) + # Trim queue to limit + while len(self._queue) > QUEUE_LIMIT: + self._queue.pop(0) + self._new_event.set() + + def _poll_loop(self): + """Background loop: poll SessionDB for new messages.""" + db = _get_session_db() + if not db: + logger.warning("EventBridge: SessionDB unavailable, event polling disabled") + return + + while self._running: + try: + self._poll_once(db) + except Exception as e: + logger.debug("EventBridge poll error: %s", e) + time.sleep(POLL_INTERVAL) + + def _poll_once(self, db): + """Check for new messages across all sessions. + + Uses mtime checks on sessions.json and state.db to skip work + when nothing has changed — makes 200ms polling essentially free. + """ + # Check if sessions.json has changed (mtime check is ~1μs) + sessions_file = _get_sessions_dir() / "sessions.json" + try: + sj_mtime = sessions_file.stat().st_mtime if sessions_file.exists() else 0.0 + except OSError: + sj_mtime = 0.0 + + if sj_mtime != self._sessions_json_mtime: + self._sessions_json_mtime = sj_mtime + self._cached_sessions_index = _load_sessions_index() + + # Check if state.db has changed + try: + from hermes_constants import get_hermes_home + db_file = get_hermes_home() / "state.db" + except ImportError: + db_file = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes")) / "state.db" + + try: + db_mtime = db_file.stat().st_mtime if db_file.exists() else 0.0 + except OSError: + db_mtime = 0.0 + + if db_mtime == self._state_db_mtime and sj_mtime == self._sessions_json_mtime: + return # Nothing changed since last poll — skip entirely + + self._state_db_mtime = db_mtime + entries = self._cached_sessions_index + + for session_key, entry in entries.items(): + session_id = entry.get("session_id", "") + if not session_id: + continue + + last_seen = self._last_poll_timestamps.get(session_key, 0.0) + + try: + messages = db.get_messages(session_id) + except Exception: + continue + + if not messages: + continue + + # Normalize timestamps to float for comparison + def _ts_float(ts) -> float: + if isinstance(ts, (int, float)): + return float(ts) + if isinstance(ts, str) and ts: + try: + return float(ts) + except ValueError: + # ISO string — parse to epoch + try: + from datetime import datetime + return datetime.fromisoformat(ts).timestamp() + except Exception: + return 0.0 + return 0.0 + + # Find messages newer than our last seen timestamp + new_messages = [] + for msg in messages: + ts = _ts_float(msg.get("timestamp", 0)) + role = msg.get("role", "") + if role not in ("user", "assistant"): + continue + if ts > last_seen: + new_messages.append(msg) + + for msg in new_messages: + content = _extract_message_content(msg) + if not content: + continue + self._enqueue(QueueEvent( + cursor=0, + type="message", + session_key=session_key, + data={ + "role": msg.get("role", ""), + "content": content[:500], + "timestamp": str(msg.get("timestamp", "")), + "message_id": str(msg.get("id", "")), + }, + )) + + # Update last seen to the most recent message timestamp + all_ts = [_ts_float(m.get("timestamp", 0)) for m in messages] + if all_ts: + latest = max(all_ts) + if latest > last_seen: + self._last_poll_timestamps[session_key] = latest + + +# --------------------------------------------------------------------------- +# MCP Server +# --------------------------------------------------------------------------- + +def create_mcp_server(event_bridge: Optional[EventBridge] = None) -> "FastMCP": + """Create and return the Hermes MCP server with all tools registered.""" + if not _MCP_SERVER_AVAILABLE: + raise ImportError( + "MCP server requires the 'mcp' package. " + "Install with: pip install 'hermes-agent[mcp]'" + ) + + mcp = FastMCP( + "hermes", + instructions=( + "Hermes Agent messaging bridge. Use these tools to interact with " + "conversations across Telegram, Discord, Slack, WhatsApp, Signal, " + "Matrix, and other connected platforms." + ), + ) + + bridge = event_bridge or EventBridge() + + # -- conversations_list ------------------------------------------------ + + @mcp.tool() + def conversations_list( + platform: Optional[str] = None, + limit: int = 50, + search: Optional[str] = None, + ) -> str: + """List active messaging conversations across connected platforms. + + Returns conversations with their session keys (needed for messages_read), + platform, chat type, display name, and last activity time. + + Args: + platform: Filter by platform name (telegram, discord, slack, etc.) + limit: Maximum number of conversations to return (default 50) + search: Optional text to filter conversations by name + """ + entries = _load_sessions_index() + conversations = [] + + for key, entry in entries.items(): + origin = entry.get("origin", {}) + entry_platform = entry.get("platform") or origin.get("platform", "") + + if platform and entry_platform.lower() != platform.lower(): + continue + + display_name = entry.get("display_name", "") + chat_name = origin.get("chat_name", "") + if search: + search_lower = search.lower() + if (search_lower not in display_name.lower() + and search_lower not in chat_name.lower() + and search_lower not in key.lower()): + continue + + conversations.append({ + "session_key": key, + "session_id": entry.get("session_id", ""), + "platform": entry_platform, + "chat_type": entry.get("chat_type", origin.get("chat_type", "")), + "display_name": display_name, + "chat_name": chat_name, + "user_name": origin.get("user_name", ""), + "updated_at": entry.get("updated_at", ""), + }) + + conversations.sort(key=lambda c: c.get("updated_at", ""), reverse=True) + conversations = conversations[:limit] + + return json.dumps({ + "count": len(conversations), + "conversations": conversations, + }, indent=2) + + # -- conversation_get -------------------------------------------------- + + @mcp.tool() + def conversation_get(session_key: str) -> str: + """Get detailed info about one conversation by its session key. + + Args: + session_key: The session key from conversations_list + """ + entries = _load_sessions_index() + entry = entries.get(session_key) + + if not entry: + return json.dumps({"error": f"Conversation not found: {session_key}"}) + + origin = entry.get("origin", {}) + return json.dumps({ + "session_key": session_key, + "session_id": entry.get("session_id", ""), + "platform": entry.get("platform") or origin.get("platform", ""), + "chat_type": entry.get("chat_type", origin.get("chat_type", "")), + "display_name": entry.get("display_name", ""), + "user_name": origin.get("user_name", ""), + "chat_name": origin.get("chat_name", ""), + "chat_id": origin.get("chat_id", ""), + "thread_id": origin.get("thread_id"), + "updated_at": entry.get("updated_at", ""), + "created_at": entry.get("created_at", ""), + "input_tokens": entry.get("input_tokens", 0), + "output_tokens": entry.get("output_tokens", 0), + "total_tokens": entry.get("total_tokens", 0), + }, indent=2) + + # -- messages_read ----------------------------------------------------- + + @mcp.tool() + def messages_read( + session_key: str, + limit: int = 50, + ) -> str: + """Read recent messages from a conversation. + + Returns the message history in chronological order with role, content, + and timestamp for each message. + + Args: + session_key: The session key from conversations_list + limit: Maximum number of messages to return (default 50, most recent) + """ + entries = _load_sessions_index() + entry = entries.get(session_key) + if not entry: + return json.dumps({"error": f"Conversation not found: {session_key}"}) + + session_id = entry.get("session_id", "") + if not session_id: + return json.dumps({"error": "No session ID for this conversation"}) + + db = _get_session_db() + if not db: + return json.dumps({"error": "Session database unavailable"}) + + try: + all_messages = db.get_messages(session_id) + except Exception as e: + return json.dumps({"error": f"Failed to read messages: {e}"}) + + filtered = [] + for msg in all_messages: + role = msg.get("role", "") + if role in ("user", "assistant"): + content = _extract_message_content(msg) + if content: + filtered.append({ + "id": str(msg.get("id", "")), + "role": role, + "content": content[:2000], + "timestamp": msg.get("timestamp", ""), + }) + + messages = filtered[-limit:] + + return json.dumps({ + "session_key": session_key, + "count": len(messages), + "total_in_session": len(filtered), + "messages": messages, + }, indent=2) + + # -- attachments_fetch ------------------------------------------------- + + @mcp.tool() + def attachments_fetch( + session_key: str, + message_id: str, + ) -> str: + """List non-text attachments for a message in a conversation. + + Extracts images, media files, and other non-text content blocks + from the specified message. + + Args: + session_key: The session key from conversations_list + message_id: The message ID from messages_read + """ + entries = _load_sessions_index() + entry = entries.get(session_key) + if not entry: + return json.dumps({"error": f"Conversation not found: {session_key}"}) + + session_id = entry.get("session_id", "") + if not session_id: + return json.dumps({"error": "No session ID for this conversation"}) + + db = _get_session_db() + if not db: + return json.dumps({"error": "Session database unavailable"}) + + try: + all_messages = db.get_messages(session_id) + except Exception as e: + return json.dumps({"error": f"Failed to read messages: {e}"}) + + # Find the target message + target_msg = None + for msg in all_messages: + if str(msg.get("id", "")) == message_id: + target_msg = msg + break + + if not target_msg: + return json.dumps({"error": f"Message not found: {message_id}"}) + + attachments = _extract_attachments(target_msg) + + return json.dumps({ + "message_id": message_id, + "count": len(attachments), + "attachments": attachments, + }, indent=2) + + # -- events_poll ------------------------------------------------------- + + @mcp.tool() + def events_poll( + after_cursor: int = 0, + session_key: Optional[str] = None, + limit: int = 20, + ) -> str: + """Poll for new conversation events since a cursor position. + + Returns events that have occurred since the given cursor. Use the + returned next_cursor value for subsequent polls. + + Event types: message, approval_requested, approval_resolved + + Args: + after_cursor: Return events after this cursor (0 for all) + session_key: Optional filter to one conversation + limit: Maximum events to return (default 20) + """ + result = bridge.poll_events( + after_cursor=after_cursor, + session_key=session_key, + limit=limit, + ) + return json.dumps(result, indent=2) + + # -- events_wait ------------------------------------------------------- + + @mcp.tool() + def events_wait( + after_cursor: int = 0, + session_key: Optional[str] = None, + timeout_ms: int = 30000, + ) -> str: + """Wait for the next conversation event (long-poll). + + Blocks until a matching event arrives or the timeout expires. + Use this for near-real-time event delivery without polling. + + Args: + after_cursor: Wait for events after this cursor + session_key: Optional filter to one conversation + timeout_ms: Maximum wait time in milliseconds (default 30000) + """ + event = bridge.wait_for_event( + after_cursor=after_cursor, + session_key=session_key, + timeout_ms=min(timeout_ms, 300000), # Cap at 5 minutes + ) + if event: + return json.dumps({"event": event}, indent=2) + return json.dumps({"event": None, "reason": "timeout"}, indent=2) + + # -- messages_send ----------------------------------------------------- + + @mcp.tool() + def messages_send( + target: str, + message: str, + ) -> str: + """Send a message to a platform conversation. + + The target format is "platform:chat_id" — same format used by the + channels_list tool. You can also use human-friendly channel names + that will be resolved automatically. + + Examples: + target="telegram:6308981865" + target="discord:#general" + target="slack:#engineering" + + Args: + target: Platform target in "platform:identifier" format + message: The message text to send + """ + if not target or not message: + return json.dumps({"error": "Both target and message are required"}) + + try: + from tools.send_message_tool import send_message_tool + result_str = send_message_tool( + {"action": "send", "target": target, "message": message} + ) + return result_str + except ImportError: + return json.dumps({"error": "Send message tool not available"}) + except Exception as e: + return json.dumps({"error": f"Send failed: {e}"}) + + # -- channels_list ----------------------------------------------------- + + @mcp.tool() + def channels_list(platform: Optional[str] = None) -> str: + """List available messaging channels and targets across platforms. + + Returns channels that you can send messages to. The target strings + returned here can be used directly with the messages_send tool. + + Args: + platform: Filter by platform name (telegram, discord, slack, etc.) + """ + directory = _load_channel_directory() + if not directory: + entries = _load_sessions_index() + targets = [] + seen = set() + for key, entry in entries.items(): + origin = entry.get("origin", {}) + p = entry.get("platform") or origin.get("platform", "") + chat_id = origin.get("chat_id", "") + if not p or not chat_id: + continue + if platform and p.lower() != platform.lower(): + continue + target_str = f"{p}:{chat_id}" + if target_str in seen: + continue + seen.add(target_str) + targets.append({ + "target": target_str, + "platform": p, + "name": entry.get("display_name") or origin.get("chat_name", ""), + "chat_type": entry.get("chat_type", origin.get("chat_type", "")), + }) + return json.dumps({"count": len(targets), "channels": targets}, indent=2) + + channels = [] + for plat, entries_list in directory.items(): + if platform and plat.lower() != platform.lower(): + continue + if isinstance(entries_list, list): + for ch in entries_list: + if isinstance(ch, dict): + chat_id = ch.get("id", ch.get("chat_id", "")) + channels.append({ + "target": f"{plat}:{chat_id}" if chat_id else plat, + "platform": plat, + "name": ch.get("name", ch.get("display_name", "")), + "chat_type": ch.get("type", ""), + }) + + return json.dumps({"count": len(channels), "channels": channels}, indent=2) + + # -- permissions_list_open --------------------------------------------- + + @mcp.tool() + def permissions_list_open() -> str: + """List pending approval requests observed during this bridge session. + + Returns exec and plugin approval requests that the bridge has seen + since it started. Approvals are live-session only — older approvals + from before the bridge connected are not included. + """ + approvals = bridge.list_pending_approvals() + return json.dumps({ + "count": len(approvals), + "approvals": approvals, + }, indent=2) + + # -- permissions_respond ----------------------------------------------- + + @mcp.tool() + def permissions_respond( + id: str, + decision: str, + ) -> str: + """Respond to a pending approval request. + + Args: + id: The approval ID from permissions_list_open + decision: One of "allow-once", "allow-always", or "deny" + """ + if decision not in ("allow-once", "allow-always", "deny"): + return json.dumps({ + "error": f"Invalid decision: {decision}. " + f"Must be allow-once, allow-always, or deny" + }) + + result = bridge.respond_to_approval(id, decision) + return json.dumps(result, indent=2) + + return mcp + + +# --------------------------------------------------------------------------- +# Entry point +# --------------------------------------------------------------------------- + +def run_mcp_server(verbose: bool = False) -> None: + """Start the Hermes MCP server on stdio.""" + if not _MCP_SERVER_AVAILABLE: + print( + "Error: MCP server requires the 'mcp' package.\n" + "Install with: pip install 'hermes-agent[mcp]'", + file=sys.stderr, + ) + sys.exit(1) + + if verbose: + logging.basicConfig(level=logging.DEBUG, stream=sys.stderr) + else: + logging.basicConfig(level=logging.WARNING, stream=sys.stderr) + + bridge = EventBridge() + bridge.start() + + server = create_mcp_server(event_bridge=bridge) + + import asyncio + + async def _run(): + try: + await server.run_stdio_async() + finally: + bridge.stop() + + try: + asyncio.run(_run()) + except KeyboardInterrupt: + bridge.stop() diff --git a/mindcli/_vendor/run_agent.py b/mindcli/_vendor/run_agent.py new file mode 100644 index 0000000..d8ba43d --- /dev/null +++ b/mindcli/_vendor/run_agent.py @@ -0,0 +1,10878 @@ +#!/usr/bin/env python3 +""" +AI Agent Runner with Tool Calling + +This module provides a clean, standalone agent that can execute AI models +with tool calling capabilities. It handles the conversation loop, tool execution, +and response management. + +Features: +- Automatic tool calling loop until completion +- Configurable model parameters +- Error handling and recovery +- Message history management +- Support for multiple model providers + +Usage: + from run_agent import AIAgent + + agent = AIAgent(base_url="http://localhost:30000/v1", model="claude-opus-4-20250514") + response = agent.run_conversation("Tell me about the latest Python updates") +""" + +import asyncio +import base64 +import concurrent.futures +import copy +import hashlib +import json +import logging +logger = logging.getLogger(__name__) +import os +import random +import re +import sys +import tempfile +import time +import threading +from types import SimpleNamespace +import uuid +from typing import List, Dict, Any, Optional +from openai import OpenAI +import fire +from datetime import datetime +from pathlib import Path + +from hermes_constants import get_hermes_home + +# 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_cli.env_loader import load_hermes_dotenv + +_hermes_home = get_hermes_home() +_project_env = Path(__file__).parent / '.env' +_loaded_env_paths = load_hermes_dotenv(hermes_home=_hermes_home, project_env=_project_env) +if _loaded_env_paths: + for _env_path in _loaded_env_paths: + logger.info("Loaded environment variables from %s", _env_path) +else: + logger.info("No .env file found. Using system environment variables.") + + +# Import our tool system +from model_tools import ( + get_tool_definitions, + get_toolset_for_tool, + handle_function_call, + check_toolset_requirements, +) +from tools.terminal_tool import cleanup_vm, get_active_env, is_persistent_env +from tools.tool_result_storage import maybe_persist_tool_result, enforce_turn_budget +from tools.interrupt import set_interrupt as _set_interrupt +from tools.browser_tool import cleanup_browser + + +from hermes_constants import OPENROUTER_BASE_URL + +# Agent internals extracted to agent/ package for modularity +from agent.memory_manager import build_memory_context_block +from agent.retry_utils import jittered_backoff +from agent.error_classifier import classify_api_error, FailoverReason +from agent.prompt_builder import ( + DEFAULT_AGENT_IDENTITY, PLATFORM_HINTS, + MEMORY_GUIDANCE, SESSION_SEARCH_GUIDANCE, SKILLS_GUIDANCE, + build_nous_subscription_prompt, +) +from agent.model_metadata import ( + fetch_model_metadata, + estimate_tokens_rough, estimate_messages_tokens_rough, estimate_request_tokens_rough, + get_next_probe_tier, parse_context_limit_from_error, + parse_available_output_tokens_from_error, + save_context_length, is_local_endpoint, + query_ollama_num_ctx, +) +from agent.context_compressor import ContextCompressor +from agent.subdirectory_hints import SubdirectoryHintTracker +from agent.prompt_caching import apply_anthropic_cache_control +from agent.prompt_builder import build_skills_system_prompt, build_context_files_prompt, build_environment_hints, load_soul_md, TOOL_USE_ENFORCEMENT_GUIDANCE, TOOL_USE_ENFORCEMENT_MODELS, DEVELOPER_ROLE_MODELS, GOOGLE_MODEL_OPERATIONAL_GUIDANCE, OPENAI_MODEL_EXECUTION_GUIDANCE +from agent.usage_pricing import estimate_usage_cost, normalize_usage +from agent.display import ( + KawaiiSpinner, build_tool_preview as _build_tool_preview, + get_cute_tool_message as _get_cute_tool_message_impl, + _detect_tool_failure, + get_tool_emoji as _get_tool_emoji, +) +from agent.trajectory import ( + convert_scratchpad_to_think, has_incomplete_scratchpad, + save_trajectory as _save_trajectory_to_file, +) +from utils import atomic_json_write, env_var_enabled + + + +class _SafeWriter: + """Transparent stdio wrapper that catches OSError/ValueError from broken pipes. + + When hermes-agent runs as a systemd service, Docker container, or headless + daemon, the stdout/stderr pipe can become unavailable (idle timeout, buffer + exhaustion, socket reset). Any print() call then raises + ``OSError: [Errno 5] Input/output error``, which can crash agent setup or + run_conversation() — especially via double-fault when an except handler + also tries to print. + + Additionally, when subagents run in ThreadPoolExecutor threads, the shared + stdout handle can close between thread teardown and cleanup, raising + ``ValueError: I/O operation on closed file`` instead of OSError. + + This wrapper delegates all writes to the underlying stream and silently + catches both OSError and ValueError. It is transparent when the wrapped + stream is healthy. + """ + + __slots__ = ("_inner",) + + def __init__(self, inner): + object.__setattr__(self, "_inner", inner) + + def write(self, data): + try: + return self._inner.write(data) + except (OSError, ValueError): + return len(data) if isinstance(data, str) else 0 + + def flush(self): + try: + self._inner.flush() + except (OSError, ValueError): + pass + + def fileno(self): + return self._inner.fileno() + + def isatty(self): + try: + return self._inner.isatty() + except (OSError, ValueError): + return False + + def __getattr__(self, name): + return getattr(self._inner, name) + + +def _install_safe_stdio() -> None: + """Wrap stdout/stderr so best-effort console output cannot crash the agent.""" + for stream_name in ("stdout", "stderr"): + stream = getattr(sys, stream_name, None) + if stream is not None and not isinstance(stream, _SafeWriter): + setattr(sys, stream_name, _SafeWriter(stream)) + + +class IterationBudget: + """Thread-safe iteration counter for an agent. + + Each agent (parent or subagent) gets its own ``IterationBudget``. + The parent's budget is capped at ``max_iterations`` (default 90). + Each subagent gets an independent budget capped at + ``delegation.max_iterations`` (default 50) — this means total + iterations across parent + subagents can exceed the parent's cap. + Users control the per-subagent limit via ``delegation.max_iterations`` + in config.yaml. + + ``execute_code`` (programmatic tool calling) iterations are refunded via + :meth:`refund` so they don't eat into the budget. + """ + + def __init__(self, max_total: int): + self.max_total = max_total + self._used = 0 + self._lock = threading.Lock() + + def consume(self) -> bool: + """Try to consume one iteration. Returns True if allowed.""" + with self._lock: + if self._used >= self.max_total: + return False + self._used += 1 + return True + + def refund(self) -> None: + """Give back one iteration (e.g. for execute_code turns).""" + with self._lock: + if self._used > 0: + self._used -= 1 + + @property + def used(self) -> int: + return self._used + + @property + def remaining(self) -> int: + with self._lock: + return max(0, self.max_total - self._used) + + +# Tools that must never run concurrently (interactive / user-facing). +# When any of these appear in a batch, we fall back to sequential execution. +_NEVER_PARALLEL_TOOLS = frozenset({"clarify"}) + +# Read-only tools with no shared mutable session state. +_PARALLEL_SAFE_TOOLS = frozenset({ + "ha_get_state", + "ha_list_entities", + "ha_list_services", + "read_file", + "search_files", + "session_search", + "skill_view", + "skills_list", + "vision_analyze", + "web_extract", + "web_search", +}) + +# File tools can run concurrently when they target independent paths. +_PATH_SCOPED_TOOLS = frozenset({"read_file", "write_file", "patch"}) + +# Maximum number of concurrent worker threads for parallel tool execution. +_MAX_TOOL_WORKERS = 8 + +# Patterns that indicate a terminal command may modify/delete files. +_DESTRUCTIVE_PATTERNS = re.compile( + r"""(?:^|\s|&&|\|\||;|`)(?: + rm\s|rmdir\s| + mv\s| + sed\s+-i| + truncate\s| + dd\s| + shred\s| + git\s+(?:reset|clean|checkout)\s + )""", + re.VERBOSE, +) +# Output redirects that overwrite files (> but not >>) +_REDIRECT_OVERWRITE = re.compile(r'[^>]>[^>]|^>[^>]') + + +def _is_destructive_command(cmd: str) -> bool: + """Heuristic: does this terminal command look like it modifies/deletes files?""" + if not cmd: + return False + if _DESTRUCTIVE_PATTERNS.search(cmd): + return True + if _REDIRECT_OVERWRITE.search(cmd): + return True + return False + + +def _should_parallelize_tool_batch(tool_calls) -> bool: + """Return True when a tool-call batch is safe to run concurrently.""" + if len(tool_calls) <= 1: + return False + + tool_names = [tc.function.name for tc in tool_calls] + if any(name in _NEVER_PARALLEL_TOOLS for name in tool_names): + return False + + reserved_paths: list[Path] = [] + for tool_call in tool_calls: + tool_name = tool_call.function.name + try: + function_args = json.loads(tool_call.function.arguments) + except Exception: + logging.debug( + "Could not parse args for %s — defaulting to sequential; raw=%s", + tool_name, + tool_call.function.arguments[:200], + ) + return False + if not isinstance(function_args, dict): + logging.debug( + "Non-dict args for %s (%s) — defaulting to sequential", + tool_name, + type(function_args).__name__, + ) + return False + + if tool_name in _PATH_SCOPED_TOOLS: + scoped_path = _extract_parallel_scope_path(tool_name, function_args) + if scoped_path is None: + return False + if any(_paths_overlap(scoped_path, existing) for existing in reserved_paths): + return False + reserved_paths.append(scoped_path) + continue + + if tool_name not in _PARALLEL_SAFE_TOOLS: + return False + + return True + + +def _extract_parallel_scope_path(tool_name: str, function_args: dict) -> Path | None: + """Return the normalized file target for path-scoped tools.""" + if tool_name not in _PATH_SCOPED_TOOLS: + return None + + raw_path = function_args.get("path") + if not isinstance(raw_path, str) or not raw_path.strip(): + return None + + expanded = Path(raw_path).expanduser() + if expanded.is_absolute(): + return Path(os.path.abspath(str(expanded))) + + # Avoid resolve(); the file may not exist yet. + return Path(os.path.abspath(str(Path.cwd() / expanded))) + + +def _paths_overlap(left: Path, right: Path) -> bool: + """Return True when two paths may refer to the same subtree.""" + left_parts = left.parts + right_parts = right.parts + if not left_parts or not right_parts: + # Empty paths shouldn't reach here (guarded upstream), but be safe. + return bool(left_parts) == bool(right_parts) and bool(left_parts) + common_len = min(len(left_parts), len(right_parts)) + return left_parts[:common_len] == right_parts[:common_len] + + + +_SURROGATE_RE = re.compile(r'[\ud800-\udfff]') + + + + +def _sanitize_surrogates(text: str) -> str: + """Replace lone surrogate code points with U+FFFD (replacement character). + + Surrogates are invalid in UTF-8 and will crash ``json.dumps()`` inside the + OpenAI SDK. This is a fast no-op when the text contains no surrogates. + """ + if _SURROGATE_RE.search(text): + return _SURROGATE_RE.sub('\ufffd', text) + return text + + +def _sanitize_messages_surrogates(messages: list) -> bool: + """Sanitize surrogate characters from all string content in a messages list. + + Walks message dicts in-place. Returns True if any surrogates were found + and replaced, False otherwise. Covers content/text, name, and tool call + metadata/arguments so retries don't fail on a non-content field. + """ + found = False + for msg in messages: + if not isinstance(msg, dict): + continue + content = msg.get("content") + if isinstance(content, str) and _SURROGATE_RE.search(content): + msg["content"] = _SURROGATE_RE.sub('\ufffd', content) + found = True + elif isinstance(content, list): + for part in content: + if isinstance(part, dict): + text = part.get("text") + if isinstance(text, str) and _SURROGATE_RE.search(text): + part["text"] = _SURROGATE_RE.sub('\ufffd', text) + found = True + name = msg.get("name") + if isinstance(name, str) and _SURROGATE_RE.search(name): + msg["name"] = _SURROGATE_RE.sub('\ufffd', name) + found = True + tool_calls = msg.get("tool_calls") + if isinstance(tool_calls, list): + for tc in tool_calls: + if not isinstance(tc, dict): + continue + tc_id = tc.get("id") + if isinstance(tc_id, str) and _SURROGATE_RE.search(tc_id): + tc["id"] = _SURROGATE_RE.sub('\ufffd', tc_id) + found = True + fn = tc.get("function") + if isinstance(fn, dict): + fn_name = fn.get("name") + if isinstance(fn_name, str) and _SURROGATE_RE.search(fn_name): + fn["name"] = _SURROGATE_RE.sub('\ufffd', fn_name) + found = True + fn_args = fn.get("arguments") + if isinstance(fn_args, str) and _SURROGATE_RE.search(fn_args): + fn["arguments"] = _SURROGATE_RE.sub('\ufffd', fn_args) + found = True + return found + + +def _strip_non_ascii(text: str) -> str: + """Remove non-ASCII characters, replacing with closest ASCII equivalent or removing. + + Used as a last resort when the system encoding is ASCII and can't handle + any non-ASCII characters (e.g. LANG=C on Chromebooks). + """ + return text.encode('ascii', errors='ignore').decode('ascii') + + +def _sanitize_messages_non_ascii(messages: list) -> bool: + """Strip non-ASCII characters from all string content in a messages list. + + This is a last-resort recovery for systems with ASCII-only encoding + (LANG=C, Chromebooks, minimal containers). Returns True if any + non-ASCII content was found and sanitized. + """ + found = False + for msg in messages: + if not isinstance(msg, dict): + continue + # Sanitize content (string) + content = msg.get("content") + if isinstance(content, str): + sanitized = _strip_non_ascii(content) + if sanitized != content: + msg["content"] = sanitized + found = True + elif isinstance(content, list): + for part in content: + if isinstance(part, dict): + text = part.get("text") + if isinstance(text, str): + sanitized = _strip_non_ascii(text) + if sanitized != text: + part["text"] = sanitized + found = True + # Sanitize name field (can contain non-ASCII in tool results) + name = msg.get("name") + if isinstance(name, str): + sanitized = _strip_non_ascii(name) + if sanitized != name: + msg["name"] = sanitized + found = True + # Sanitize tool_calls + tool_calls = msg.get("tool_calls") + if isinstance(tool_calls, list): + for tc in tool_calls: + if isinstance(tc, dict): + fn = tc.get("function", {}) + if isinstance(fn, dict): + fn_args = fn.get("arguments") + if isinstance(fn_args, str): + sanitized = _strip_non_ascii(fn_args) + if sanitized != fn_args: + fn["arguments"] = sanitized + found = True + return found + + +def _sanitize_tools_non_ascii(tools: list) -> bool: + """Strip non-ASCII characters from tool payloads in-place.""" + return _sanitize_structure_non_ascii(tools) + + +def _sanitize_structure_non_ascii(payload: Any) -> bool: + """Strip non-ASCII characters from nested dict/list payloads in-place.""" + found = False + + def _walk(node): + nonlocal found + if isinstance(node, dict): + for key, value in node.items(): + if isinstance(value, str): + sanitized = _strip_non_ascii(value) + if sanitized != value: + node[key] = sanitized + found = True + elif isinstance(value, (dict, list)): + _walk(value) + elif isinstance(node, list): + for idx, value in enumerate(node): + if isinstance(value, str): + sanitized = _strip_non_ascii(value) + if sanitized != value: + node[idx] = sanitized + found = True + elif isinstance(value, (dict, list)): + _walk(value) + + _walk(payload) + return found + + + + + +# ========================================================================= +# Large tool result handler — save oversized output to temp file +# ========================================================================= + + +# ========================================================================= +# Qwen Portal headers — mimics QwenCode CLI for portal.qwen.ai compatibility. +# Extracted as a module-level helper so both __init__ and +# _apply_client_headers_for_base_url can share it. +# ========================================================================= +_QWEN_CODE_VERSION = "0.14.1" + + +def _qwen_portal_headers() -> dict: + """Return default HTTP headers required by Qwen Portal API.""" + import platform as _plat + + _ua = f"QwenCode/{_QWEN_CODE_VERSION} ({_plat.system().lower()}; {_plat.machine()})" + return { + "User-Agent": _ua, + "X-DashScope-CacheControl": "enable", + "X-DashScope-UserAgent": _ua, + "X-DashScope-AuthType": "qwen-oauth", + } + + +class AIAgent: + """ + AI Agent with tool calling capabilities. + + This class manages the conversation flow, tool execution, and response handling + for AI models that support function calling. + """ + + # ── Class-level context pressure dedup (survives across instances) ── + # The gateway creates a new AIAgent per message, so instance-level flags + # reset every time. This dict tracks {session_id: (warn_level, timestamp)} + # to suppress duplicate warnings within a cooldown window. + _context_pressure_last_warned: dict = {} + _CONTEXT_PRESSURE_COOLDOWN = 300 # seconds between re-warning same session + + @property + def base_url(self) -> str: + return self._base_url + + @base_url.setter + def base_url(self, value: str) -> None: + self._base_url = value + self._base_url_lower = value.lower() if value else "" + + def __init__( + self, + base_url: str = None, + api_key: str = None, + provider: str = None, + api_mode: str = None, + acp_command: str = None, + acp_args: list[str] | None = None, + command: str = None, + args: list[str] | None = None, + model: str = "", + max_iterations: int = 90, # Default tool-calling iterations (shared with subagents) + tool_delay: float = 1.0, + enabled_toolsets: List[str] = None, + disabled_toolsets: List[str] = None, + save_trajectories: bool = False, + verbose_logging: bool = False, + quiet_mode: bool = False, + ephemeral_system_prompt: str = None, + log_prefix_chars: int = 100, + log_prefix: str = "", + providers_allowed: List[str] = None, + providers_ignored: List[str] = None, + providers_order: List[str] = None, + provider_sort: str = None, + provider_require_parameters: bool = False, + provider_data_collection: str = None, + session_id: str = None, + tool_progress_callback: callable = None, + tool_start_callback: callable = None, + tool_complete_callback: callable = None, + thinking_callback: callable = None, + reasoning_callback: callable = None, + clarify_callback: callable = None, + step_callback: callable = None, + stream_delta_callback: callable = None, + interim_assistant_callback: callable = None, + tool_gen_callback: callable = None, + status_callback: callable = None, + max_tokens: int = None, + reasoning_config: Dict[str, Any] = None, + service_tier: str = None, + request_overrides: Dict[str, Any] = None, + prefill_messages: List[Dict[str, Any]] = None, + platform: str = None, + user_id: str = None, + skip_context_files: bool = False, + skip_memory: bool = False, + session_db=None, + parent_session_id: str = None, + iteration_budget: "IterationBudget" = None, + fallback_model: Dict[str, Any] = None, + credential_pool=None, + checkpoints_enabled: bool = False, + checkpoint_max_snapshots: int = 50, + pass_session_id: bool = False, + persist_session: bool = True, + ): + """ + Initialize the AI Agent. + + Args: + base_url (str): Base URL for the model API (optional) + api_key (str): API key for authentication (optional, uses env var if not provided) + provider (str): Provider identifier (optional; used for telemetry/routing hints) + api_mode (str): API mode override: "chat_completions" or "codex_responses" + model (str): Model name to use (default: "anthropic/claude-opus-4.6") + max_iterations (int): Maximum number of tool calling iterations (default: 90) + tool_delay (float): Delay between tool calls in seconds (default: 1.0) + enabled_toolsets (List[str]): Only enable tools from these toolsets (optional) + disabled_toolsets (List[str]): Disable tools from these toolsets (optional) + save_trajectories (bool): Whether to save conversation trajectories to JSONL files (default: False) + verbose_logging (bool): Enable verbose logging for debugging (default: False) + quiet_mode (bool): Suppress progress output for clean CLI experience (default: False) + ephemeral_system_prompt (str): System prompt used during agent execution but NOT saved to trajectories (optional) + log_prefix_chars (int): Number of characters to show in log previews for tool calls/responses (default: 100) + log_prefix (str): Prefix to add to all log messages for identification in parallel processing (default: "") + providers_allowed (List[str]): OpenRouter providers to allow (optional) + providers_ignored (List[str]): OpenRouter providers to ignore (optional) + providers_order (List[str]): OpenRouter providers to try in order (optional) + provider_sort (str): Sort providers by price/throughput/latency (optional) + session_id (str): Pre-generated session ID for logging (optional, auto-generated if not provided) + tool_progress_callback (callable): Callback function(tool_name, args_preview) for progress notifications + clarify_callback (callable): Callback function(question, choices) -> str for interactive user questions. + Provided by the platform layer (CLI or gateway). If None, the clarify tool returns an error. + max_tokens (int): Maximum tokens for model responses (optional, uses model default if not set) + reasoning_config (Dict): OpenRouter reasoning configuration override (e.g. {"effort": "none"} to disable thinking). + If None, defaults to {"enabled": True, "effort": "medium"} for OpenRouter. Set to disable/customize reasoning. + prefill_messages (List[Dict]): Messages to prepend to conversation history as prefilled context. + Useful for injecting a few-shot example or priming the model's response style. + Example: [{"role": "user", "content": "Hi!"}, {"role": "assistant", "content": "Hello!"}] + platform (str): The interface platform the user is on (e.g. "cli", "telegram", "discord", "whatsapp"). + Used to inject platform-specific formatting hints into the system prompt. + skip_context_files (bool): If True, skip auto-injection of SOUL.md, AGENTS.md, and .cursorrules + into the system prompt. Use this for batch processing and data generation to avoid + polluting trajectories with user-specific persona or project instructions. + """ + _install_safe_stdio() + + self.model = model + self.max_iterations = max_iterations + # Shared iteration budget — parent creates, children inherit. + # Consumed by every LLM turn across parent + all subagents. + self.iteration_budget = iteration_budget or IterationBudget(max_iterations) + self.tool_delay = tool_delay + self.save_trajectories = save_trajectories + self.verbose_logging = verbose_logging + self.quiet_mode = quiet_mode + self.ephemeral_system_prompt = ephemeral_system_prompt + self.platform = platform # "cli", "telegram", "discord", "whatsapp", etc. + self._user_id = user_id # Platform user identifier (gateway sessions) + # Pluggable print function — CLI replaces this with _cprint so that + # raw ANSI status lines are routed through prompt_toolkit's renderer + # instead of going directly to stdout where patch_stdout's StdoutProxy + # would mangle the escape sequences. None = use builtins.print. + self._print_fn = None + self.background_review_callback = None # Optional sync callback for gateway delivery + self.skip_context_files = skip_context_files + self.pass_session_id = pass_session_id + self.persist_session = persist_session + self._credential_pool = credential_pool + self.log_prefix_chars = log_prefix_chars + self.log_prefix = f"{log_prefix} " if log_prefix else "" + # Store effective base URL for feature detection (prompt caching, reasoning, etc.) + self.base_url = base_url or "" + provider_name = provider.strip().lower() if isinstance(provider, str) and provider.strip() else None + self.provider = provider_name or "" + self.acp_command = acp_command or command + self.acp_args = list(acp_args or args or []) + if api_mode in {"chat_completions", "codex_responses", "anthropic_messages"}: + self.api_mode = api_mode + elif self.provider == "openai-codex": + self.api_mode = "codex_responses" + elif (provider_name is None) and "chatgpt.com/backend-api/codex" in self._base_url_lower: + self.api_mode = "codex_responses" + self.provider = "openai-codex" + elif self.provider == "anthropic" or (provider_name is None and "api.anthropic.com" in self._base_url_lower): + self.api_mode = "anthropic_messages" + self.provider = "anthropic" + elif self._base_url_lower.rstrip("/").endswith("/anthropic"): + # Third-party Anthropic-compatible endpoints (e.g. MiniMax, DashScope) + # use a URL convention ending in /anthropic. Auto-detect these so the + # Anthropic Messages API adapter is used instead of chat completions. + self.api_mode = "anthropic_messages" + else: + self.api_mode = "chat_completions" + + try: + from hermes_cli.model_normalize import ( + _AGGREGATOR_PROVIDERS, + normalize_model_for_provider, + ) + + if self.provider not in _AGGREGATOR_PROVIDERS: + self.model = normalize_model_for_provider(self.model, self.provider) + except Exception: + pass + + # GPT-5.x models require the Responses API path — they are rejected + # on /v1/chat/completions by both OpenAI and OpenRouter. Also + # auto-upgrade for direct OpenAI URLs (api.openai.com) since all + # newer tool-calling models prefer Responses there. + # ACP runtimes are excluded: CopilotACPClient handles its own + # routing and does not implement the Responses API surface. + if ( + self.api_mode == "chat_completions" + and self.provider != "copilot-acp" + and not str(self.base_url or "").lower().startswith("acp://copilot") + and not str(self.base_url or "").lower().startswith("acp+tcp://") + and ( + self._is_direct_openai_url() + or self._model_requires_responses_api(self.model) + ) + ): + self.api_mode = "codex_responses" + + # Pre-warm OpenRouter model metadata cache in a background thread. + # fetch_model_metadata() is cached for 1 hour; this avoids a blocking + # HTTP request on the first API response when pricing is estimated. + if self.provider == "openrouter" or self._is_openrouter_url(): + threading.Thread( + target=lambda: fetch_model_metadata(), + daemon=True, + ).start() + + self.tool_progress_callback = tool_progress_callback + self.tool_start_callback = tool_start_callback + self.tool_complete_callback = tool_complete_callback + self.suppress_status_output = False + self.thinking_callback = thinking_callback + self.reasoning_callback = reasoning_callback + self.clarify_callback = clarify_callback + self.step_callback = step_callback + self.stream_delta_callback = stream_delta_callback + self.interim_assistant_callback = interim_assistant_callback + self.status_callback = status_callback + self.tool_gen_callback = tool_gen_callback + + + # Tool execution state — allows _vprint during tool execution + # even when stream consumers are registered (no tokens streaming then) + self._executing_tools = False + + # Interrupt mechanism for breaking out of tool loops + self._interrupt_requested = False + self._interrupt_message = None # Optional message that triggered interrupt + self._execution_thread_id: int | None = None # Set at run_conversation() start + self._client_lock = threading.RLock() + + # Subagent delegation state + self._delegate_depth = 0 # 0 = top-level agent, incremented for children + self._active_children = [] # Running child AIAgents (for interrupt propagation) + self._active_children_lock = threading.Lock() + + # Store OpenRouter provider preferences + self.providers_allowed = providers_allowed + self.providers_ignored = providers_ignored + self.providers_order = providers_order + self.provider_sort = provider_sort + self.provider_require_parameters = provider_require_parameters + self.provider_data_collection = provider_data_collection + + # Store toolset filtering options + self.enabled_toolsets = enabled_toolsets + self.disabled_toolsets = disabled_toolsets + + # Model response configuration + self.max_tokens = max_tokens # None = use model default + self.reasoning_config = reasoning_config # None = use default (medium for OpenRouter) + self.service_tier = service_tier + self.request_overrides = dict(request_overrides or {}) + self.prefill_messages = prefill_messages or [] # Prefilled conversation turns + self._force_ascii_payload = False + + # Anthropic prompt caching: auto-enabled for Claude models via OpenRouter. + # Reduces input costs by ~75% on multi-turn conversations by caching the + # conversation prefix. Uses system_and_3 strategy (4 breakpoints). + is_openrouter = self._is_openrouter_url() + is_claude = "claude" in self.model.lower() + is_native_anthropic = self.api_mode == "anthropic_messages" and self.provider == "anthropic" + self._use_prompt_caching = (is_openrouter and is_claude) or is_native_anthropic + self._cache_ttl = "5m" # Default 5-minute TTL (1.25x write cost) + + # Iteration budget: the LLM is only notified when it actually exhausts + # the iteration budget (api_call_count >= max_iterations). At that + # point we inject ONE message, allow one final API call, and if the + # model doesn't produce a text response, force a user-message asking + # it to summarise. No intermediate pressure warnings — they caused + # models to "give up" prematurely on complex tasks (#7915). + self._budget_exhausted_injected = False + self._budget_grace_call = False + + # Context pressure warnings: notify the USER (not the LLM) as context + # fills up. Purely informational — displayed in CLI output and sent via + # status_callback for gateway platforms. Does NOT inject into messages. + # Tiered: fires at 85% and again at 95% of compaction threshold. + self._context_pressure_warned_at = 0.0 # highest tier already shown + + # Activity tracking — updated on each API call, tool execution, and + # stream chunk. Used by the gateway timeout handler to report what the + # agent was doing when it was killed, and by the "still working" + # notifications to show progress. + self._last_activity_ts: float = time.time() + self._last_activity_desc: str = "initializing" + self._current_tool: str | None = None + self._api_call_count: int = 0 + + # Rate limit tracking — updated from x-ratelimit-* response headers + # after each API call. Accessed by /usage slash command. + self._rate_limit_state: Optional["RateLimitState"] = None + + # Centralized logging — agent.log (INFO+) and errors.log (WARNING+) + # both live under ~/.hermes/logs/. Idempotent, so gateway mode + # (which creates a new AIAgent per message) won't duplicate handlers. + from hermes_logging import setup_logging, setup_verbose_logging + setup_logging(hermes_home=_hermes_home) + + if self.verbose_logging: + setup_verbose_logging() + logger.info("Verbose logging enabled (third-party library logs suppressed)") + else: + if self.quiet_mode: + # In quiet mode (CLI default), suppress all tool/infra log + # noise on the *console*. The TUI has its own rich display + # for status; logger INFO/WARNING messages just clutter it. + # File handlers (agent.log, errors.log) still capture everything. + for quiet_logger in [ + 'tools', # all tools.* (terminal, browser, web, file, etc.) + 'run_agent', # agent runner internals + 'trajectory_compressor', + 'cron', # scheduler (only relevant in daemon mode) + 'hermes_cli', # CLI helpers + ]: + logging.getLogger(quiet_logger).setLevel(logging.ERROR) + + # Internal stream callback (set during streaming TTS). + # Initialized here so _vprint can reference it before run_conversation. + self._stream_callback = None + # Deferred paragraph break flag — set after tool iterations so a + # single "\n\n" is prepended to the next real text delta. + self._stream_needs_break = False + # Visible assistant text already delivered through live token callbacks + # during the current model response. Used to avoid re-sending the same + # commentary when the provider later returns it as a completed interim + # assistant message. + self._current_streamed_assistant_text = "" + + # Optional current-turn user-message override used when the API-facing + # user message intentionally differs from the persisted transcript + # (e.g. CLI voice mode adds a temporary prefix for the live call only). + self._persist_user_message_idx = None + self._persist_user_message_override = None + + # Cache anthropic image-to-text fallbacks per image payload/URL so a + # single tool loop does not repeatedly re-run auxiliary vision on the + # same image history. + self._anthropic_image_fallback_cache: Dict[str, str] = {} + + # Initialize LLM client via centralized provider router. + # The router handles auth resolution, base URL, headers, and + # Codex/Anthropic wrapping for all known providers. + # raw_codex=True because the main agent needs direct responses.stream() + # access for Codex Responses API streaming. + self._anthropic_client = None + self._is_anthropic_oauth = False + + if self.api_mode == "anthropic_messages": + from agent.anthropic_adapter import build_anthropic_client, resolve_anthropic_token + # Only fall back to ANTHROPIC_TOKEN when the provider is actually Anthropic. + # Other anthropic_messages providers (MiniMax, Alibaba, etc.) must use their own API key. + # Falling back would send Anthropic credentials to third-party endpoints (Fixes #1739, #minimax-401). + _is_native_anthropic = self.provider == "anthropic" + effective_key = (api_key or resolve_anthropic_token() or "") if _is_native_anthropic else (api_key or "") + self.api_key = effective_key + self._anthropic_api_key = effective_key + self._anthropic_base_url = base_url + from agent.anthropic_adapter import _is_oauth_token as _is_oat + self._is_anthropic_oauth = _is_oat(effective_key) + self._anthropic_client = build_anthropic_client(effective_key, base_url) + # No OpenAI client needed for Anthropic mode + self.client = None + self._client_kwargs = {} + if not self.quiet_mode: + print(f"🤖 AI Agent initialized with model: {self.model} (Anthropic native)") + if effective_key and len(effective_key) > 12: + print(f"🔑 Using token: {effective_key[:8]}...{effective_key[-4:]}") + else: + if api_key and base_url: + # Explicit credentials from CLI/gateway — construct directly. + # The runtime provider resolver already handled auth for us. + client_kwargs = {"api_key": api_key, "base_url": base_url} + if self.provider == "copilot-acp": + client_kwargs["command"] = self.acp_command + client_kwargs["args"] = self.acp_args + effective_base = base_url + if "openrouter" in effective_base.lower(): + client_kwargs["default_headers"] = { + "HTTP-Referer": "https://hermes-agent.nousresearch.com", + "X-OpenRouter-Title": "Hermes Agent", + "X-OpenRouter-Categories": "productivity,cli-agent", + } + elif "api.githubcopilot.com" in effective_base.lower(): + from hermes_cli.models import copilot_default_headers + + client_kwargs["default_headers"] = copilot_default_headers() + elif "api.kimi.com" in effective_base.lower(): + client_kwargs["default_headers"] = { + "User-Agent": "KimiCLI/1.30.0", + } + elif "portal.qwen.ai" in effective_base.lower(): + client_kwargs["default_headers"] = _qwen_portal_headers() + else: + # No explicit creds — use the centralized provider router + from agent.auxiliary_client import resolve_provider_client + _routed_client, _ = resolve_provider_client( + self.provider or "auto", model=self.model, raw_codex=True) + if _routed_client is not None: + client_kwargs = { + "api_key": _routed_client.api_key, + "base_url": str(_routed_client.base_url), + } + # Preserve any default_headers the router set + if hasattr(_routed_client, '_default_headers') and _routed_client._default_headers: + client_kwargs["default_headers"] = dict(_routed_client._default_headers) + else: + # When the user explicitly chose a non-OpenRouter provider + # but no credentials were found, fail fast with a clear + # message instead of silently routing through OpenRouter. + _explicit = (self.provider or "").strip().lower() + if _explicit and _explicit not in ("auto", "openrouter", "custom"): + raise RuntimeError( + f"Provider '{_explicit}' is set in config.yaml but no API key " + f"was found. Set the {_explicit.upper()}_API_KEY environment " + f"variable, or switch to a different provider with `hermes model`." + ) + # Final fallback: try raw OpenRouter key + client_kwargs = { + "api_key": os.getenv("OPENROUTER_API_KEY", ""), + "base_url": OPENROUTER_BASE_URL, + "default_headers": { + "HTTP-Referer": "https://hermes-agent.nousresearch.com", + "X-OpenRouter-Title": "Hermes Agent", + "X-OpenRouter-Categories": "productivity,cli-agent", + }, + } + + self._client_kwargs = client_kwargs # stored for rebuilding after interrupt + + # Enable fine-grained tool streaming for Claude on OpenRouter. + # Without this, Anthropic buffers the entire tool call and goes + # silent for minutes while thinking — OpenRouter's upstream proxy + # times out during the silence. The beta header makes Anthropic + # stream tool call arguments token-by-token, keeping the + # connection alive. + _effective_base = str(client_kwargs.get("base_url", "")).lower() + if "openrouter" in _effective_base and "claude" in (self.model or "").lower(): + headers = client_kwargs.get("default_headers") or {} + existing_beta = headers.get("x-anthropic-beta", "") + _FINE_GRAINED = "fine-grained-tool-streaming-2025-05-14" + if _FINE_GRAINED not in existing_beta: + if existing_beta: + headers["x-anthropic-beta"] = f"{existing_beta},{_FINE_GRAINED}" + else: + headers["x-anthropic-beta"] = _FINE_GRAINED + client_kwargs["default_headers"] = headers + + self.api_key = client_kwargs.get("api_key", "") + self.base_url = client_kwargs.get("base_url", self.base_url) + try: + self.client = self._create_openai_client(client_kwargs, reason="agent_init", shared=True) + if not self.quiet_mode: + print(f"🤖 AI Agent initialized with model: {self.model}") + if base_url: + print(f"🔗 Using custom base URL: {base_url}") + # Always show API key info (masked) for debugging auth issues + key_used = client_kwargs.get("api_key", "none") + if key_used and key_used != "dummy-key" and len(key_used) > 12: + print(f"🔑 Using API key: {key_used[:8]}...{key_used[-4:]}") + else: + print(f"⚠️ Warning: API key appears invalid or missing (got: '{key_used[:20] if key_used else 'none'}...')") + except Exception as e: + raise RuntimeError(f"Failed to initialize OpenAI client: {e}") + + # Provider fallback chain — ordered list of backup providers tried + # when the primary is exhausted (rate-limit, overload, connection + # failure). Supports both legacy single-dict ``fallback_model`` and + # new list ``fallback_providers`` format. + if isinstance(fallback_model, list): + self._fallback_chain = [ + f for f in fallback_model + if isinstance(f, dict) and f.get("provider") and f.get("model") + ] + elif isinstance(fallback_model, dict) and fallback_model.get("provider") and fallback_model.get("model"): + self._fallback_chain = [fallback_model] + else: + self._fallback_chain = [] + self._fallback_index = 0 + self._fallback_activated = False + # Legacy attribute kept for backward compat (tests, external callers) + self._fallback_model = self._fallback_chain[0] if self._fallback_chain else None + if self._fallback_chain and not self.quiet_mode: + if len(self._fallback_chain) == 1: + fb = self._fallback_chain[0] + print(f"🔄 Fallback model: {fb['model']} ({fb['provider']})") + else: + print(f"🔄 Fallback chain ({len(self._fallback_chain)} providers): " + + " → ".join(f"{f['model']} ({f['provider']})" for f in self._fallback_chain)) + + # Get available tools with filtering + self.tools = get_tool_definitions( + enabled_toolsets=enabled_toolsets, + disabled_toolsets=disabled_toolsets, + quiet_mode=self.quiet_mode, + ) + + # Show tool configuration and store valid tool names for validation + self.valid_tool_names = set() + if self.tools: + self.valid_tool_names = {tool["function"]["name"] for tool in self.tools} + tool_names = sorted(self.valid_tool_names) + if not self.quiet_mode: + print(f"🛠️ Loaded {len(self.tools)} tools: {', '.join(tool_names)}") + + # Show filtering info if applied + if enabled_toolsets: + print(f" ✅ Enabled toolsets: {', '.join(enabled_toolsets)}") + if disabled_toolsets: + print(f" ❌ Disabled toolsets: {', '.join(disabled_toolsets)}") + elif not self.quiet_mode: + print("🛠️ No tools loaded (all tools filtered out or unavailable)") + + # Check tool requirements + if self.tools and not self.quiet_mode: + requirements = check_toolset_requirements() + missing_reqs = [name for name, available in requirements.items() if not available] + if missing_reqs: + print(f"⚠️ Some tools may not work due to missing requirements: {missing_reqs}") + + # Show trajectory saving status + if self.save_trajectories and not self.quiet_mode: + print("📝 Trajectory saving enabled") + + # Show ephemeral system prompt status + if self.ephemeral_system_prompt and not self.quiet_mode: + prompt_preview = self.ephemeral_system_prompt[:60] + "..." if len(self.ephemeral_system_prompt) > 60 else self.ephemeral_system_prompt + print(f"🔒 Ephemeral system prompt: '{prompt_preview}' (not saved to trajectories)") + + # Show prompt caching status + if self._use_prompt_caching and not self.quiet_mode: + source = "native Anthropic" if is_native_anthropic else "Claude via OpenRouter" + print(f"💾 Prompt caching: ENABLED ({source}, {self._cache_ttl} TTL)") + + # Session logging setup - auto-save conversation trajectories for debugging + self.session_start = datetime.now() + if session_id: + # Use provided session ID (e.g., from CLI) + self.session_id = session_id + else: + # Generate a new session ID + timestamp_str = self.session_start.strftime("%Y%m%d_%H%M%S") + short_uuid = uuid.uuid4().hex[:6] + self.session_id = f"{timestamp_str}_{short_uuid}" + + # Session logs go into ~/.hermes/sessions/ alongside gateway sessions + hermes_home = get_hermes_home() + self.logs_dir = hermes_home / "sessions" + self.logs_dir.mkdir(parents=True, exist_ok=True) + self.session_log_file = self.logs_dir / f"session_{self.session_id}.json" + + # Track conversation messages for session logging + self._session_messages: List[Dict[str, Any]] = [] + + # Cached system prompt -- built once per session, only rebuilt on compression + self._cached_system_prompt: Optional[str] = None + + # Filesystem checkpoint manager (transparent — not a tool) + from tools.checkpoint_manager import CheckpointManager + self._checkpoint_mgr = CheckpointManager( + enabled=checkpoints_enabled, + max_snapshots=checkpoint_max_snapshots, + ) + + # SQLite session store (optional -- provided by CLI or gateway) + self._session_db = session_db + self._parent_session_id = parent_session_id + self._last_flushed_db_idx = 0 # tracks DB-write cursor to prevent duplicate writes + if self._session_db: + try: + self._session_db.create_session( + session_id=self.session_id, + source=self.platform or os.environ.get("HERMES_SESSION_SOURCE", "cli"), + model=self.model, + model_config={ + "max_iterations": self.max_iterations, + "reasoning_config": reasoning_config, + "max_tokens": max_tokens, + }, + user_id=None, + parent_session_id=self._parent_session_id, + ) + except Exception as e: + # Transient SQLite lock contention (e.g. CLI and gateway writing + # concurrently) must NOT permanently disable session_search for + # this agent. Keep _session_db alive — subsequent message + # flushes and session_search calls will still work once the + # lock clears. The session row may be missing from the index + # for this run, but that is recoverable (flushes upsert rows). + logger.warning( + "Session DB create_session failed (session_search still available): %s", e + ) + + # In-memory todo list for task planning (one per agent/session) + from tools.todo_tool import TodoStore + self._todo_store = TodoStore() + + # Load config once for memory, skills, and compression sections + try: + from hermes_cli.config import load_config as _load_agent_config + _agent_cfg = _load_agent_config() + except Exception: + _agent_cfg = {} + + # Persistent memory (MEMORY.md + USER.md) -- loaded from disk + self._memory_store = None + self._memory_enabled = False + self._user_profile_enabled = False + self._memory_nudge_interval = 10 + self._memory_flush_min_turns = 6 + self._turns_since_memory = 0 + self._iters_since_skill = 0 + if not skip_memory: + try: + mem_config = _agent_cfg.get("memory", {}) + self._memory_enabled = mem_config.get("memory_enabled", False) + self._user_profile_enabled = mem_config.get("user_profile_enabled", False) + self._memory_nudge_interval = int(mem_config.get("nudge_interval", 10)) + self._memory_flush_min_turns = int(mem_config.get("flush_min_turns", 6)) + if self._memory_enabled or self._user_profile_enabled: + from tools.memory_tool import MemoryStore + self._memory_store = MemoryStore( + memory_char_limit=mem_config.get("memory_char_limit", 2200), + user_char_limit=mem_config.get("user_char_limit", 1375), + ) + self._memory_store.load_from_disk() + except Exception: + pass # Memory is optional -- don't break agent init + + + + # Memory provider plugin (external — one at a time, alongside built-in) + # Reads memory.provider from config to select which plugin to activate. + self._memory_manager = None + if not skip_memory: + try: + _mem_provider_name = mem_config.get("provider", "") if mem_config else "" + + # Auto-migrate: if Honcho was actively configured (enabled + + # credentials) but memory.provider is not set, activate the + # honcho plugin automatically. Just having the config file + # is not enough — the user may have disabled Honcho or the + # file may be from a different tool. + if not _mem_provider_name: + try: + from plugins.memory.honcho.client import HonchoClientConfig as _HCC + _hcfg = _HCC.from_global_config() + if _hcfg.enabled and (_hcfg.api_key or _hcfg.base_url): + _mem_provider_name = "honcho" + # Persist so this only auto-migrates once + try: + from hermes_cli.config import load_config as _lc, save_config as _sc + _cfg = _lc() + _cfg.setdefault("memory", {})["provider"] = "honcho" + _sc(_cfg) + except Exception: + pass + if not self.quiet_mode: + print(" ✓ Auto-migrated Honcho to memory provider plugin.") + print(" Your config and data are preserved.\n") + except Exception: + pass + + if _mem_provider_name: + from agent.memory_manager import MemoryManager as _MemoryManager + from plugins.memory import load_memory_provider as _load_mem + self._memory_manager = _MemoryManager() + _mp = _load_mem(_mem_provider_name) + if _mp and _mp.is_available(): + self._memory_manager.add_provider(_mp) + if self._memory_manager.providers: + from hermes_constants import get_hermes_home as _ghh + _init_kwargs = { + "session_id": self.session_id, + "platform": platform or "cli", + "hermes_home": str(_ghh()), + "agent_context": "primary", + } + # Thread gateway user identity for per-user memory scoping + if self._user_id: + _init_kwargs["user_id"] = self._user_id + # Profile identity for per-profile provider scoping + try: + from hermes_cli.profiles import get_active_profile_name + _profile = get_active_profile_name() + _init_kwargs["agent_identity"] = _profile + _init_kwargs["agent_workspace"] = "hermes" + except Exception: + pass + self._memory_manager.initialize_all(**_init_kwargs) + logger.info("Memory provider '%s' activated", _mem_provider_name) + else: + logger.debug("Memory provider '%s' not found or not available", _mem_provider_name) + self._memory_manager = None + except Exception as _mpe: + logger.warning("Memory provider plugin init failed: %s", _mpe) + self._memory_manager = None + + # Inject memory provider tool schemas into the tool surface + if self._memory_manager and self.tools is not None: + for _schema in self._memory_manager.get_all_tool_schemas(): + _wrapped = {"type": "function", "function": _schema} + self.tools.append(_wrapped) + _tname = _schema.get("name", "") + if _tname: + self.valid_tool_names.add(_tname) + + # Skills config: nudge interval for skill creation reminders + self._skill_nudge_interval = 10 + try: + skills_config = _agent_cfg.get("skills", {}) + self._skill_nudge_interval = int(skills_config.get("creation_nudge_interval", 10)) + except Exception: + pass + + # Tool-use enforcement config: "auto" (default — matches hardcoded + # model list), true (always), false (never), or list of substrings. + _agent_section = _agent_cfg.get("agent", {}) + if not isinstance(_agent_section, dict): + _agent_section = {} + self._tool_use_enforcement = _agent_section.get("tool_use_enforcement", "auto") + + # Initialize context compressor for automatic context management + # Compresses conversation when approaching model's context limit + # Configuration via config.yaml (compression section) + _compression_cfg = _agent_cfg.get("compression", {}) + if not isinstance(_compression_cfg, dict): + _compression_cfg = {} + compression_threshold = float(_compression_cfg.get("threshold", 0.50)) + compression_enabled = str(_compression_cfg.get("enabled", True)).lower() in ("true", "1", "yes") + compression_target_ratio = float(_compression_cfg.get("target_ratio", 0.20)) + compression_protect_last = int(_compression_cfg.get("protect_last_n", 20)) + + # Read explicit context_length override from model config + _model_cfg = _agent_cfg.get("model", {}) + if isinstance(_model_cfg, dict): + _config_context_length = _model_cfg.get("context_length") + else: + _config_context_length = None + if _config_context_length is not None: + try: + _config_context_length = int(_config_context_length) + except (TypeError, ValueError): + _config_context_length = None + + # Store for reuse in switch_model (so config override persists across model switches) + self._config_context_length = _config_context_length + + # Check custom_providers per-model context_length + if _config_context_length is None: + try: + from hermes_cli.config import get_compatible_custom_providers + _custom_providers = get_compatible_custom_providers(_agent_cfg) + except Exception: + _custom_providers = _agent_cfg.get("custom_providers") + if not isinstance(_custom_providers, list): + _custom_providers = [] + for _cp_entry in _custom_providers: + if not isinstance(_cp_entry, dict): + continue + _cp_url = (_cp_entry.get("base_url") or "").rstrip("/") + if _cp_url and _cp_url == self.base_url.rstrip("/"): + _cp_models = _cp_entry.get("models", {}) + if isinstance(_cp_models, dict): + _cp_model_cfg = _cp_models.get(self.model, {}) + if isinstance(_cp_model_cfg, dict): + _cp_ctx = _cp_model_cfg.get("context_length") + if _cp_ctx is not None: + try: + _config_context_length = int(_cp_ctx) + except (TypeError, ValueError): + pass + break + + # Select context engine: config-driven (like memory providers). + # 1. Check config.yaml context.engine setting + # 2. Check plugins/context_engine// directory (repo-shipped) + # 3. Check general plugin system (user-installed plugins) + # 4. Fall back to built-in ContextCompressor + _selected_engine = None + _engine_name = "compressor" # default + try: + _ctx_cfg = _agent_cfg.get("context", {}) if isinstance(_agent_cfg, dict) else {} + _engine_name = _ctx_cfg.get("engine", "compressor") or "compressor" + except Exception: + pass + + if _engine_name != "compressor": + # Try loading from plugins/context_engine// + try: + from plugins.context_engine import load_context_engine + _selected_engine = load_context_engine(_engine_name) + except Exception as _ce_load_err: + logger.debug("Context engine load from plugins/context_engine/: %s", _ce_load_err) + + # Try general plugin system as fallback + if _selected_engine is None: + try: + from hermes_cli.plugins import get_plugin_context_engine + _candidate = get_plugin_context_engine() + if _candidate and _candidate.name == _engine_name: + _selected_engine = _candidate + except Exception: + pass + + if _selected_engine is None: + logger.warning( + "Context engine '%s' not found — falling back to built-in compressor", + _engine_name, + ) + # else: config says "compressor" — use built-in, don't auto-activate plugins + + if _selected_engine is not None: + self.context_compressor = _selected_engine + # Resolve context_length for plugin engines — mirrors switch_model() path + from agent.model_metadata import get_model_context_length + _plugin_ctx_len = get_model_context_length( + self.model, + base_url=self.base_url, + api_key=getattr(self, "api_key", ""), + config_context_length=_config_context_length, + provider=self.provider, + ) + self.context_compressor.update_model( + model=self.model, + context_length=_plugin_ctx_len, + base_url=self.base_url, + api_key=getattr(self, "api_key", ""), + provider=self.provider, + ) + if not self.quiet_mode: + logger.info("Using context engine: %s", _selected_engine.name) + else: + self.context_compressor = ContextCompressor( + model=self.model, + threshold_percent=compression_threshold, + protect_first_n=3, + protect_last_n=compression_protect_last, + summary_target_ratio=compression_target_ratio, + summary_model_override=None, + quiet_mode=self.quiet_mode, + base_url=self.base_url, + api_key=getattr(self, "api_key", ""), + config_context_length=_config_context_length, + provider=self.provider, + api_mode=self.api_mode, + ) + self.compression_enabled = compression_enabled + + # Reject models whose context window is below the minimum required + # for reliable tool-calling workflows (64K tokens). + from agent.model_metadata import MINIMUM_CONTEXT_LENGTH + _ctx = getattr(self.context_compressor, "context_length", 0) + if _ctx and _ctx < MINIMUM_CONTEXT_LENGTH: + raise ValueError( + f"Model {self.model} has a context window of {_ctx:,} tokens, " + f"which is below the minimum {MINIMUM_CONTEXT_LENGTH:,} required " + f"by Hermes Agent. Choose a model with at least " + f"{MINIMUM_CONTEXT_LENGTH // 1000}K context, or set " + f"model.context_length in config.yaml to override." + ) + + # Inject context engine tool schemas (e.g. lcm_grep, lcm_describe, lcm_expand) + self._context_engine_tool_names: set = set() + if hasattr(self, "context_compressor") and self.context_compressor and self.tools is not None: + for _schema in self.context_compressor.get_tool_schemas(): + _wrapped = {"type": "function", "function": _schema} + self.tools.append(_wrapped) + _tname = _schema.get("name", "") + if _tname: + self.valid_tool_names.add(_tname) + self._context_engine_tool_names.add(_tname) + + # Notify context engine of session start + if hasattr(self, "context_compressor") and self.context_compressor: + try: + self.context_compressor.on_session_start( + self.session_id, + hermes_home=str(get_hermes_home()), + platform=self.platform or "cli", + model=self.model, + context_length=getattr(self.context_compressor, "context_length", 0), + ) + except Exception as _ce_err: + logger.debug("Context engine on_session_start: %s", _ce_err) + + self._subdirectory_hints = SubdirectoryHintTracker( + working_dir=os.getenv("TERMINAL_CWD") or None, + ) + self._user_turn_count = 0 + + # Cumulative token usage for the session + self.session_prompt_tokens = 0 + self.session_completion_tokens = 0 + self.session_total_tokens = 0 + self.session_api_calls = 0 + self.session_input_tokens = 0 + self.session_output_tokens = 0 + self.session_cache_read_tokens = 0 + self.session_cache_write_tokens = 0 + self.session_reasoning_tokens = 0 + self.session_estimated_cost_usd = 0.0 + self.session_cost_status = "unknown" + self.session_cost_source = "none" + + # ── Ollama num_ctx injection ── + # Ollama defaults to 2048 context regardless of the model's capabilities. + # When running against an Ollama server, detect the model's max context + # and pass num_ctx on every chat request so the full window is used. + # User override: set model.ollama_num_ctx in config.yaml to cap VRAM use. + self._ollama_num_ctx: int | None = None + _ollama_num_ctx_override = None + if isinstance(_model_cfg, dict): + _ollama_num_ctx_override = _model_cfg.get("ollama_num_ctx") + if _ollama_num_ctx_override is not None: + try: + self._ollama_num_ctx = int(_ollama_num_ctx_override) + except (TypeError, ValueError): + logger.debug("Invalid ollama_num_ctx config value: %r", _ollama_num_ctx_override) + if self._ollama_num_ctx is None and self.base_url and is_local_endpoint(self.base_url): + try: + _detected = query_ollama_num_ctx(self.model, self.base_url) + if _detected and _detected > 0: + self._ollama_num_ctx = _detected + except Exception as exc: + logger.debug("Ollama num_ctx detection failed: %s", exc) + if self._ollama_num_ctx and not self.quiet_mode: + logger.info( + "Ollama num_ctx: will request %d tokens (model max from /api/show)", + self._ollama_num_ctx, + ) + + if not self.quiet_mode: + if compression_enabled: + print(f"📊 Context limit: {self.context_compressor.context_length:,} tokens (compress at {int(compression_threshold*100)}% = {self.context_compressor.threshold_tokens:,})") + else: + print(f"📊 Context limit: {self.context_compressor.context_length:,} tokens (auto-compression disabled)") + + # Check immediately so CLI users see the warning at startup. + # Gateway status_callback is not yet wired, so any warning is stored + # in _compression_warning and replayed in the first run_conversation(). + self._compression_warning = None + self._check_compression_model_feasibility() + + # Snapshot primary runtime for per-turn restoration. When fallback + # activates during a turn, the next turn restores these values so the + # preferred model gets a fresh attempt each time. Uses a single dict + # so new state fields are easy to add without N individual attributes. + _cc = self.context_compressor + self._primary_runtime = { + "model": self.model, + "provider": self.provider, + "base_url": self.base_url, + "api_mode": self.api_mode, + "api_key": getattr(self, "api_key", ""), + "client_kwargs": dict(self._client_kwargs), + "use_prompt_caching": self._use_prompt_caching, + # Context engine state that _try_activate_fallback() overwrites. + # Use getattr for model/base_url/api_key/provider since plugin + # engines may not have these (they're ContextCompressor-specific). + "compressor_model": getattr(_cc, "model", self.model), + "compressor_base_url": getattr(_cc, "base_url", self.base_url), + "compressor_api_key": getattr(_cc, "api_key", ""), + "compressor_provider": getattr(_cc, "provider", self.provider), + "compressor_context_length": _cc.context_length, + "compressor_threshold_tokens": _cc.threshold_tokens, + } + if self.api_mode == "anthropic_messages": + self._primary_runtime.update({ + "anthropic_api_key": self._anthropic_api_key, + "anthropic_base_url": self._anthropic_base_url, + "is_anthropic_oauth": self._is_anthropic_oauth, + }) + + def reset_session_state(self): + """Reset all session-scoped token counters to 0 for a fresh session. + + This method encapsulates the reset logic for all session-level metrics + including: + - Token usage counters (input, output, total, prompt, completion) + - Cache read/write tokens + - API call count + - Reasoning tokens + - Estimated cost tracking + - Context compressor internal counters + + The method safely handles optional attributes (e.g., context compressor) + using ``hasattr`` checks. + + This keeps the counter reset logic DRY and maintainable in one place + rather than scattering it across multiple methods. + """ + # Token usage counters + self.session_total_tokens = 0 + self.session_input_tokens = 0 + self.session_output_tokens = 0 + self.session_prompt_tokens = 0 + self.session_completion_tokens = 0 + self.session_cache_read_tokens = 0 + self.session_cache_write_tokens = 0 + self.session_reasoning_tokens = 0 + self.session_api_calls = 0 + self.session_estimated_cost_usd = 0.0 + self.session_cost_status = "unknown" + self.session_cost_source = "none" + + # Turn counter (added after reset_session_state was first written — #2635) + self._user_turn_count = 0 + + # Context engine reset (works for both built-in compressor and plugins) + if hasattr(self, "context_compressor") and self.context_compressor: + self.context_compressor.on_session_reset() + + def switch_model(self, new_model, new_provider, api_key='', base_url='', api_mode=''): + """Switch the model/provider in-place for a live agent. + + Called by the /model command handlers (CLI and gateway) after + ``model_switch.switch_model()`` has resolved credentials and + validated the model. This method performs the actual runtime + swap: rebuilding clients, updating caching flags, and refreshing + the context compressor. + + The implementation mirrors ``_try_activate_fallback()`` for the + client-swap logic but also updates ``_primary_runtime`` so the + change persists across turns (unlike fallback which is + turn-scoped). + """ + import logging + from hermes_cli.providers import determine_api_mode + + # ── Determine api_mode if not provided ── + if not api_mode: + api_mode = determine_api_mode(new_provider, base_url) + + old_model = self.model + old_provider = self.provider + + # ── Swap core runtime fields ── + self.model = new_model + self.provider = new_provider + self.base_url = base_url or self.base_url + self.api_mode = api_mode + if api_key: + self.api_key = api_key + + # ── Build new client ── + if api_mode == "anthropic_messages": + from agent.anthropic_adapter import ( + build_anthropic_client, + resolve_anthropic_token, + _is_oauth_token, + ) + # Only fall back to ANTHROPIC_TOKEN when the provider is actually Anthropic. + # Other anthropic_messages providers (MiniMax, Alibaba, etc.) must use their own + # API key — falling back would send Anthropic credentials to third-party endpoints. + _is_native_anthropic = new_provider == "anthropic" + effective_key = (api_key or self.api_key or resolve_anthropic_token() or "") if _is_native_anthropic else (api_key or self.api_key or "") + self.api_key = effective_key + self._anthropic_api_key = effective_key + self._anthropic_base_url = base_url or getattr(self, "_anthropic_base_url", None) + self._anthropic_client = build_anthropic_client( + effective_key, self._anthropic_base_url, + ) + self._is_anthropic_oauth = _is_oauth_token(effective_key) + self.client = None + self._client_kwargs = {} + else: + effective_key = api_key or self.api_key + effective_base = base_url or self.base_url + self._client_kwargs = { + "api_key": effective_key, + "base_url": effective_base, + } + self.client = self._create_openai_client( + dict(self._client_kwargs), + reason="switch_model", + shared=True, + ) + + # ── Re-evaluate prompt caching ── + is_native_anthropic = api_mode == "anthropic_messages" and new_provider == "anthropic" + self._use_prompt_caching = ( + ("openrouter" in (self.base_url or "").lower() and "claude" in new_model.lower()) + or is_native_anthropic + ) + + # ── Update context compressor ── + if hasattr(self, "context_compressor") and self.context_compressor: + from agent.model_metadata import get_model_context_length + new_context_length = get_model_context_length( + self.model, + base_url=self.base_url, + api_key=self.api_key, + provider=self.provider, + config_context_length=getattr(self, "_config_context_length", None), + ) + self.context_compressor.update_model( + model=self.model, + context_length=new_context_length, + base_url=self.base_url, + api_key=getattr(self, "api_key", ""), + provider=self.provider, + api_mode=self.api_mode, + ) + + # ── Invalidate cached system prompt so it rebuilds next turn ── + self._cached_system_prompt = None + + # ── Update _primary_runtime so the change persists across turns ── + _cc = self.context_compressor if hasattr(self, "context_compressor") and self.context_compressor else None + self._primary_runtime = { + "model": self.model, + "provider": self.provider, + "base_url": self.base_url, + "api_mode": self.api_mode, + "api_key": getattr(self, "api_key", ""), + "client_kwargs": dict(self._client_kwargs), + "use_prompt_caching": self._use_prompt_caching, + "compressor_model": getattr(_cc, "model", self.model) if _cc else self.model, + "compressor_base_url": getattr(_cc, "base_url", self.base_url) if _cc else self.base_url, + "compressor_api_key": getattr(_cc, "api_key", "") if _cc else "", + "compressor_provider": getattr(_cc, "provider", self.provider) if _cc else self.provider, + "compressor_context_length": _cc.context_length if _cc else 0, + "compressor_threshold_tokens": _cc.threshold_tokens if _cc else 0, + } + if api_mode == "anthropic_messages": + self._primary_runtime.update({ + "anthropic_api_key": self._anthropic_api_key, + "anthropic_base_url": self._anthropic_base_url, + "is_anthropic_oauth": self._is_anthropic_oauth, + }) + + # ── Reset fallback state ── + self._fallback_activated = False + self._fallback_index = 0 + + logging.info( + "Model switched in-place: %s (%s) -> %s (%s)", + old_model, old_provider, new_model, new_provider, + ) + + def _safe_print(self, *args, **kwargs): + """Print that silently handles broken pipes / closed stdout. + + In headless environments (systemd, Docker, nohup) stdout may become + unavailable mid-session. A raw ``print()`` raises ``OSError`` which + can crash cron jobs and lose completed work. + + Internally routes through ``self._print_fn`` (default: builtin + ``print``) so callers such as the CLI can inject a renderer that + handles ANSI escape sequences properly (e.g. prompt_toolkit's + ``print_formatted_text(ANSI(...))``) without touching this method. + """ + try: + fn = self._print_fn or print + fn(*args, **kwargs) + except (OSError, ValueError): + pass + + def _vprint(self, *args, force: bool = False, **kwargs): + """Verbose print — suppressed when actively streaming tokens. + + Pass ``force=True`` for error/warning messages that should always be + shown even during streaming playback (TTS or display). + + During tool execution (``_executing_tools`` is True), printing is + allowed even with stream consumers registered because no tokens + are being streamed at that point. + + After the main response has been delivered and the remaining tool + calls are post-response housekeeping (``_mute_post_response``), + all non-forced output is suppressed. + + ``suppress_status_output`` is a stricter CLI automation mode used by + parseable single-query flows such as ``hermes chat -q``. In that mode, + all status/diagnostic prints routed through ``_vprint`` are suppressed + so stdout stays machine-readable. + """ + if getattr(self, "suppress_status_output", False): + return + if not force and getattr(self, "_mute_post_response", False): + return + if not force and self._has_stream_consumers() and not self._executing_tools: + return + self._safe_print(*args, **kwargs) + + def _should_start_quiet_spinner(self) -> bool: + """Return True when quiet-mode spinner output has a safe sink. + + In headless/stdio-protocol environments, a raw spinner with no custom + ``_print_fn`` falls back to ``sys.stdout`` and can corrupt protocol + streams such as ACP JSON-RPC. Allow quiet spinners only when either: + - output is explicitly rerouted via ``_print_fn``; or + - stdout is a real TTY. + """ + if self._print_fn is not None: + return True + stream = getattr(sys, "stdout", None) + if stream is None: + return False + try: + return bool(stream.isatty()) + except (AttributeError, ValueError, OSError): + return False + + def _should_emit_quiet_tool_messages(self) -> bool: + """Return True when quiet-mode tool summaries should print directly. + + When the caller provides ``tool_progress_callback`` (for example the CLI + TUI or a gateway progress renderer), that callback owns progress display. + Emitting quiet-mode summary lines here duplicates progress and leaks tool + previews into flows that are expected to stay silent, such as + ``hermes chat -q``. + """ + return self.quiet_mode and not self.tool_progress_callback + + def _emit_status(self, message: str) -> None: + """Emit a lifecycle status message to both CLI and gateway channels. + + CLI users see the message via ``_vprint(force=True)`` so it is always + visible regardless of verbose/quiet mode. Gateway consumers receive + it through ``status_callback("lifecycle", ...)``. + + This helper never raises — exceptions are swallowed so it cannot + interrupt the retry/fallback logic. + """ + try: + self._vprint(f"{self.log_prefix}{message}", force=True) + except Exception: + pass + if self.status_callback: + try: + self.status_callback("lifecycle", message) + except Exception: + logger.debug("status_callback error in _emit_status", exc_info=True) + + def _current_main_runtime(self) -> Dict[str, str]: + """Return the live main runtime for session-scoped auxiliary routing.""" + return { + "model": getattr(self, "model", "") or "", + "provider": getattr(self, "provider", "") or "", + "base_url": getattr(self, "base_url", "") or "", + "api_key": getattr(self, "api_key", "") or "", + "api_mode": getattr(self, "api_mode", "") or "", + } + + def _check_compression_model_feasibility(self) -> None: + """Warn at session start if the auxiliary compression model's context + window is smaller than the main model's compression threshold. + + When the auxiliary model cannot fit the content that needs summarising, + compression will either fail outright (the LLM call errors) or produce + a severely truncated summary. + + Called during ``__init__`` so CLI users see the warning immediately + (via ``_vprint``). The gateway sets ``status_callback`` *after* + construction, so ``_replay_compression_warning()`` re-sends the + stored warning through the callback on the first + ``run_conversation()`` call. + """ + if not self.compression_enabled: + return + try: + from agent.auxiliary_client import get_text_auxiliary_client + from agent.model_metadata import get_model_context_length + + client, aux_model = get_text_auxiliary_client( + "compression", + main_runtime=self._current_main_runtime(), + ) + if client is None or not aux_model: + msg = ( + "⚠ No auxiliary LLM provider configured — context " + "compression will drop middle turns without a summary. " + "Run `hermes setup` or set OPENROUTER_API_KEY." + ) + self._compression_warning = msg + self._emit_status(msg) + logger.warning( + "No auxiliary LLM provider for compression — " + "summaries will be unavailable." + ) + return + + aux_base_url = str(getattr(client, "base_url", "")) + aux_api_key = str(getattr(client, "api_key", "")) + + # Read user-configured context_length for the compression model. + # Custom endpoints often don't support /models API queries so + # get_model_context_length() falls through to the 128K default, + # ignoring the explicit config value. Pass it as the highest- + # priority hint so the configured value is always respected. + _aux_cfg = (self.config or {}).get("auxiliary", {}).get("compression", {}) + _aux_context_config = _aux_cfg.get("context_length") if isinstance(_aux_cfg, dict) else None + if _aux_context_config is not None: + try: + _aux_context_config = int(_aux_context_config) + except (TypeError, ValueError): + _aux_context_config = None + + aux_context = get_model_context_length( + aux_model, + base_url=aux_base_url, + api_key=aux_api_key, + config_context_length=_aux_context_config, + ) + + threshold = self.context_compressor.threshold_tokens + if aux_context < threshold: + # Suggest a threshold that would fit the aux model, + # rounded down to a clean percentage. + safe_pct = int((aux_context / self.context_compressor.context_length) * 100) + msg = ( + f"⚠ Compression model ({aux_model}) context " + f"is {aux_context:,} tokens, but the main model's " + f"compression threshold is {threshold:,} tokens. " + f"Context compression will not be possible — the " + f"content to summarise will exceed the auxiliary " + f"model's context window.\n" + f" Fix options (config.yaml):\n" + f" 1. Use a larger compression model:\n" + f" auxiliary:\n" + f" compression:\n" + f" model: \n" + f" 2. Lower the compression threshold to fit " + f"the current model:\n" + f" compression:\n" + f" threshold: 0.{safe_pct:02d}" + ) + self._compression_warning = msg + self._emit_status(msg) + logger.warning( + "Auxiliary compression model %s has %d token context, " + "below the main model's compression threshold of %d " + "tokens — compression summaries will fail or be " + "severely truncated.", + aux_model, + aux_context, + threshold, + ) + except Exception as exc: + logger.debug( + "Compression feasibility check failed (non-fatal): %s", exc + ) + + def _replay_compression_warning(self) -> None: + """Re-send the compression warning through ``status_callback``. + + During ``__init__`` the gateway's ``status_callback`` is not yet + wired, so ``_emit_status`` only reaches ``_vprint`` (CLI). This + method is called once at the start of the first + ``run_conversation()`` — by then the gateway has set the callback, + so every platform (Telegram, Discord, Slack, etc.) receives the + warning. + """ + msg = getattr(self, "_compression_warning", None) + if msg and self.status_callback: + try: + self.status_callback("lifecycle", msg) + except Exception: + pass + + def _is_direct_openai_url(self, base_url: str = None) -> bool: + """Return True when a base URL targets OpenAI's native API.""" + url = (base_url or self._base_url_lower).lower() + return "api.openai.com" in url and "openrouter" not in url + + def _is_openrouter_url(self) -> bool: + """Return True when the base URL targets OpenRouter.""" + return "openrouter" in self._base_url_lower + + @staticmethod + def _model_requires_responses_api(model: str) -> bool: + """Return True for models that require the Responses API path. + + GPT-5.x models are rejected on /v1/chat/completions by both + OpenAI and OpenRouter (error: ``unsupported_api_for_model``). + Detect these so the correct api_mode is set regardless of + which provider is serving the model. + """ + m = model.lower() + # Strip vendor prefix (e.g. "openai/gpt-5.4" → "gpt-5.4") + if "/" in m: + m = m.rsplit("/", 1)[-1] + return m.startswith("gpt-5") + + def _max_tokens_param(self, value: int) -> dict: + """Return the correct max tokens kwarg for the current provider. + + OpenAI's newer models (gpt-4o, o-series, gpt-5+) require + 'max_completion_tokens'. OpenRouter, local models, and older + OpenAI models use 'max_tokens'. + """ + if self._is_direct_openai_url(): + return {"max_completion_tokens": value} + return {"max_tokens": value} + + def _has_content_after_think_block(self, content: str) -> bool: + """ + Check if content has actual text after any reasoning/thinking blocks. + + This detects cases where the model only outputs reasoning but no actual + response, which indicates an incomplete generation that should be retried. + Must stay in sync with _strip_think_blocks() tag variants. + + Args: + content: The assistant message content to check + + Returns: + True if there's meaningful content after think blocks, False otherwise + """ + if not content: + return False + + # Remove all reasoning tag variants (must match _strip_think_blocks) + cleaned = self._strip_think_blocks(content) + + # Check if there's any non-whitespace content remaining + return bool(cleaned.strip()) + + def _strip_think_blocks(self, content: str) -> str: + """Remove reasoning/thinking blocks from content, returning only visible text.""" + if not content: + return "" + # Strip all reasoning tag variants: , , , + # , , (Gemma 4) + content = re.sub(r'.*?', '', content, flags=re.DOTALL) + content = re.sub(r'.*?', '', content, flags=re.DOTALL | re.IGNORECASE) + content = re.sub(r'.*?', '', content, flags=re.DOTALL) + content = re.sub(r'.*?', '', content, flags=re.DOTALL) + content = re.sub(r'.*?', '', content, flags=re.DOTALL | re.IGNORECASE) + content = re.sub(r'\s*', '', content, flags=re.IGNORECASE) + return content + + def _looks_like_codex_intermediate_ack( + self, + user_message: str, + assistant_content: str, + messages: List[Dict[str, Any]], + ) -> bool: + """Detect a planning/ack message that should continue instead of ending the turn.""" + if any(isinstance(msg, dict) and msg.get("role") == "tool" for msg in messages): + return False + + assistant_text = self._strip_think_blocks(assistant_content or "").strip().lower() + if not assistant_text: + return False + if len(assistant_text) > 1200: + return False + + has_future_ack = bool( + re.search(r"\b(i['’]ll|i will|let me|i can do that|i can help with that)\b", assistant_text) + ) + if not has_future_ack: + return False + + action_markers = ( + "look into", + "look at", + "inspect", + "scan", + "check", + "analyz", + "review", + "explore", + "read", + "open", + "run", + "test", + "fix", + "debug", + "search", + "find", + "walkthrough", + "report back", + "summarize", + ) + workspace_markers = ( + "directory", + "current directory", + "current dir", + "cwd", + "repo", + "repository", + "codebase", + "project", + "folder", + "filesystem", + "file tree", + "files", + "path", + ) + + user_text = (user_message or "").strip().lower() + user_targets_workspace = ( + any(marker in user_text for marker in workspace_markers) + or "~/" in user_text + or "/" in user_text + ) + assistant_mentions_action = any(marker in assistant_text for marker in action_markers) + assistant_targets_workspace = any( + marker in assistant_text for marker in workspace_markers + ) + return (user_targets_workspace or assistant_targets_workspace) and assistant_mentions_action + + + def _extract_reasoning(self, assistant_message) -> Optional[str]: + """ + Extract reasoning/thinking content from an assistant message. + + OpenRouter and various providers can return reasoning in multiple formats: + 1. message.reasoning - Direct reasoning field (DeepSeek, Qwen, etc.) + 2. message.reasoning_content - Alternative field (Moonshot AI, Novita, etc.) + 3. message.reasoning_details - Array of {type, summary, ...} objects (OpenRouter unified) + + Args: + assistant_message: The assistant message object from the API response + + Returns: + Combined reasoning text, or None if no reasoning found + """ + reasoning_parts = [] + + # Check direct reasoning field + if hasattr(assistant_message, 'reasoning') and assistant_message.reasoning: + reasoning_parts.append(assistant_message.reasoning) + + # Check reasoning_content field (alternative name used by some providers) + if hasattr(assistant_message, 'reasoning_content') and assistant_message.reasoning_content: + # Don't duplicate if same as reasoning + if assistant_message.reasoning_content not in reasoning_parts: + reasoning_parts.append(assistant_message.reasoning_content) + + # Check reasoning_details array (OpenRouter unified format) + # Format: [{"type": "reasoning.summary", "summary": "...", ...}, ...] + if hasattr(assistant_message, 'reasoning_details') and assistant_message.reasoning_details: + for detail in assistant_message.reasoning_details: + if isinstance(detail, dict): + # Extract summary from reasoning detail object + summary = ( + detail.get('summary') + or detail.get('thinking') + or detail.get('content') + or detail.get('text') + ) + if summary and summary not in reasoning_parts: + reasoning_parts.append(summary) + + # Some providers embed reasoning directly inside assistant content + # instead of returning structured reasoning fields. Only fall back + # to inline extraction when no structured reasoning was found. + content = getattr(assistant_message, "content", None) + if not reasoning_parts and isinstance(content, str) and content: + inline_patterns = ( + r"(.*?)", + r"(.*?)", + r"(.*?)", + r"(.*?)", + r"(.*?)", + ) + for pattern in inline_patterns: + flags = re.DOTALL | re.IGNORECASE + for block in re.findall(pattern, content, flags=flags): + cleaned = block.strip() + if cleaned and cleaned not in reasoning_parts: + reasoning_parts.append(cleaned) + + # Combine all reasoning parts + if reasoning_parts: + return "\n\n".join(reasoning_parts) + + return None + + def _cleanup_task_resources(self, task_id: str) -> None: + """Clean up VM and browser resources for a given task. + + Skips ``cleanup_vm`` when the active terminal environment is marked + persistent (``persistent_filesystem=True``) so that long-lived sandbox + containers survive between turns. The idle reaper in + ``terminal_tool._cleanup_inactive_envs`` still tears them down once + ``terminal.lifetime_seconds`` is exceeded. Non-persistent backends are + torn down per-turn as before to prevent resource leakage (the original + intent of this hook for the Morph backend, see commit fbd3a2fd). + """ + try: + if is_persistent_env(task_id): + if self.verbose_logging: + logging.debug( + f"Skipping per-turn cleanup_vm for persistent env {task_id}; " + f"idle reaper will handle it." + ) + else: + cleanup_vm(task_id) + except Exception as e: + if self.verbose_logging: + logging.warning(f"Failed to cleanup VM for task {task_id}: {e}") + try: + cleanup_browser(task_id) + except Exception as e: + if self.verbose_logging: + logging.warning(f"Failed to cleanup browser for task {task_id}: {e}") + + # ------------------------------------------------------------------ + # Background memory/skill review + # ------------------------------------------------------------------ + + _MEMORY_REVIEW_PROMPT = ( + "Review the conversation above and consider saving to memory if appropriate.\n\n" + "Focus on:\n" + "1. Has the user revealed things about themselves — their persona, desires, " + "preferences, or personal details worth remembering?\n" + "2. Has the user expressed expectations about how you should behave, their work " + "style, or ways they want you to operate?\n\n" + "If something stands out, save it using the memory tool. " + "If nothing is worth saving, just say 'Nothing to save.' and stop." + ) + + _SKILL_REVIEW_PROMPT = ( + "Review the conversation above and consider saving or updating a skill if appropriate.\n\n" + "Focus on: was a non-trivial approach used to complete a task that required trial " + "and error, or changing course due to experiential findings along the way, or did " + "the user expect or desire a different method or outcome?\n\n" + "If a relevant skill already exists, update it with what you learned. " + "Otherwise, create a new skill if the approach is reusable.\n" + "If nothing is worth saving, just say 'Nothing to save.' and stop." + ) + + _COMBINED_REVIEW_PROMPT = ( + "Review the conversation above and consider two things:\n\n" + "**Memory**: Has the user revealed things about themselves — their persona, " + "desires, preferences, or personal details? Has the user expressed expectations " + "about how you should behave, their work style, or ways they want you to operate? " + "If so, save using the memory tool.\n\n" + "**Skills**: Was a non-trivial approach used to complete a task that required trial " + "and error, or changing course due to experiential findings along the way, or did " + "the user expect or desire a different method or outcome? If a relevant skill " + "already exists, update it. Otherwise, create a new one if the approach is reusable.\n\n" + "Only act if there's something genuinely worth saving. " + "If nothing stands out, just say 'Nothing to save.' and stop." + ) + + def _spawn_background_review( + self, + messages_snapshot: List[Dict], + review_memory: bool = False, + review_skills: bool = False, + ) -> None: + """Spawn a background thread to review the conversation for memory/skill saves. + + Creates a full AIAgent fork with the same model, tools, and context as the + main session. The review prompt is appended as the next user turn in the + forked conversation. Writes directly to the shared memory/skill stores. + Never modifies the main conversation history or produces user-visible output. + """ + import threading + + # Pick the right prompt based on which triggers fired + if review_memory and review_skills: + prompt = self._COMBINED_REVIEW_PROMPT + elif review_memory: + prompt = self._MEMORY_REVIEW_PROMPT + else: + prompt = self._SKILL_REVIEW_PROMPT + + def _run_review(): + import contextlib, os as _os + review_agent = None + try: + with open(_os.devnull, "w") as _devnull, \ + contextlib.redirect_stdout(_devnull), \ + contextlib.redirect_stderr(_devnull): + review_agent = AIAgent( + model=self.model, + max_iterations=8, + quiet_mode=True, + platform=self.platform, + provider=self.provider, + ) + review_agent._memory_store = self._memory_store + review_agent._memory_enabled = self._memory_enabled + review_agent._user_profile_enabled = self._user_profile_enabled + review_agent._memory_nudge_interval = 0 + review_agent._skill_nudge_interval = 0 + + review_agent.run_conversation( + user_message=prompt, + conversation_history=messages_snapshot, + ) + + # Scan the review agent's messages for successful tool actions + # and surface a compact summary to the user. + actions = [] + for msg in getattr(review_agent, "_session_messages", []): + if not isinstance(msg, dict) or msg.get("role") != "tool": + continue + try: + data = json.loads(msg.get("content", "{}")) + except (json.JSONDecodeError, TypeError): + continue + if not data.get("success"): + continue + message = data.get("message", "") + target = data.get("target", "") + if "created" in message.lower(): + actions.append(message) + elif "updated" in message.lower(): + actions.append(message) + elif "added" in message.lower() or (target and "add" in message.lower()): + label = "Memory" if target == "memory" else "User profile" if target == "user" else target + actions.append(f"{label} updated") + elif "Entry added" in message: + label = "Memory" if target == "memory" else "User profile" if target == "user" else target + actions.append(f"{label} updated") + elif "removed" in message.lower() or "replaced" in message.lower(): + label = "Memory" if target == "memory" else "User profile" if target == "user" else target + actions.append(f"{label} updated") + + if actions: + summary = " · ".join(dict.fromkeys(actions)) + self._safe_print(f" 💾 {summary}") + _bg_cb = self.background_review_callback + if _bg_cb: + try: + _bg_cb(f"💾 {summary}") + except Exception: + pass + + except Exception as e: + logger.debug("Background memory/skill review failed: %s", e) + finally: + # Close all resources (httpx client, subprocesses, etc.) so + # GC doesn't try to clean them up on a dead asyncio event + # loop (which produces "Event loop is closed" errors). + if review_agent is not None: + try: + review_agent.close() + except Exception: + pass + + t = threading.Thread(target=_run_review, daemon=True, name="bg-review") + t.start() + + def _apply_persist_user_message_override(self, messages: List[Dict]) -> None: + """Rewrite the current-turn user message before persistence/return. + + Some call paths need an API-only user-message variant without letting + that synthetic text leak into persisted transcripts or resumed session + history. When an override is configured for the active turn, mutate the + in-memory messages list in place so both persistence and returned + history stay clean. + """ + idx = getattr(self, "_persist_user_message_idx", None) + override = getattr(self, "_persist_user_message_override", None) + if override is None or idx is None: + return + if 0 <= idx < len(messages): + msg = messages[idx] + if isinstance(msg, dict) and msg.get("role") == "user": + msg["content"] = override + + def _persist_session(self, messages: List[Dict], conversation_history: List[Dict] = None): + """Save session state to both JSON log and SQLite on any exit path. + + Ensures conversations are never lost, even on errors or early returns. + Skipped when ``persist_session=False`` (ephemeral helper flows). + """ + if not self.persist_session: + return + self._apply_persist_user_message_override(messages) + self._session_messages = messages + self._save_session_log(messages) + self._flush_messages_to_session_db(messages, conversation_history) + + def _flush_messages_to_session_db(self, messages: List[Dict], conversation_history: List[Dict] = None): + """Persist any un-flushed messages to the SQLite session store. + + Uses _last_flushed_db_idx to track which messages have already been + written, so repeated calls (from multiple exit paths) only write + truly new messages — preventing the duplicate-write bug (#860). + """ + if not self._session_db: + return + self._apply_persist_user_message_override(messages) + try: + # If create_session() failed at startup (e.g. transient lock), the + # session row may not exist yet. ensure_session() uses INSERT OR + # IGNORE so it is a no-op when the row is already there. + self._session_db.ensure_session( + self.session_id, + source=self.platform or "cli", + model=self.model, + ) + start_idx = len(conversation_history) if conversation_history else 0 + flush_from = max(start_idx, self._last_flushed_db_idx) + for msg in messages[flush_from:]: + role = msg.get("role", "unknown") + content = msg.get("content") + tool_calls_data = None + if hasattr(msg, "tool_calls") and msg.tool_calls: + tool_calls_data = [ + {"name": tc.function.name, "arguments": tc.function.arguments} + for tc in msg.tool_calls + ] + elif isinstance(msg.get("tool_calls"), list): + tool_calls_data = msg["tool_calls"] + self._session_db.append_message( + session_id=self.session_id, + role=role, + content=content, + tool_name=msg.get("tool_name"), + tool_calls=tool_calls_data, + tool_call_id=msg.get("tool_call_id"), + finish_reason=msg.get("finish_reason"), + reasoning=msg.get("reasoning") if role == "assistant" else None, + reasoning_details=msg.get("reasoning_details") if role == "assistant" else None, + codex_reasoning_items=msg.get("codex_reasoning_items") if role == "assistant" else None, + ) + self._last_flushed_db_idx = len(messages) + except Exception as e: + logger.warning("Session DB append_message failed: %s", e) + + def _get_messages_up_to_last_assistant(self, messages: List[Dict]) -> List[Dict]: + """ + Get messages up to (but not including) the last assistant turn. + + This is used when we need to "roll back" to the last successful point + in the conversation, typically when the final assistant message is + incomplete or malformed. + + Args: + messages: Full message list + + Returns: + Messages up to the last complete assistant turn (ending with user/tool message) + """ + if not messages: + return [] + + # Find the index of the last assistant message + last_assistant_idx = None + for i in range(len(messages) - 1, -1, -1): + if messages[i].get("role") == "assistant": + last_assistant_idx = i + break + + if last_assistant_idx is None: + # No assistant message found, return all messages + return messages.copy() + + # Return everything up to (not including) the last assistant message + return messages[:last_assistant_idx] + + def _format_tools_for_system_message(self) -> str: + """ + Format tool definitions for the system message in the trajectory format. + + Returns: + str: JSON string representation of tool definitions + """ + if not self.tools: + return "[]" + + # Convert tool definitions to the format expected in trajectories + formatted_tools = [] + for tool in self.tools: + func = tool["function"] + formatted_tool = { + "name": func["name"], + "description": func.get("description", ""), + "parameters": func.get("parameters", {}), + "required": None # Match the format in the example + } + formatted_tools.append(formatted_tool) + + return json.dumps(formatted_tools, ensure_ascii=False) + + def _convert_to_trajectory_format(self, messages: List[Dict[str, Any]], user_query: str, completed: bool) -> List[Dict[str, Any]]: + """ + Convert internal message format to trajectory format for saving. + + Args: + messages (List[Dict]): Internal message history + user_query (str): Original user query + completed (bool): Whether the conversation completed successfully + + Returns: + List[Dict]: Messages in trajectory format + """ + trajectory = [] + + # Add system message with tool definitions + system_msg = ( + "You are a function calling AI model. You are provided with function signatures within XML tags. " + "You may call one or more functions to assist with the user query. If available tools are not relevant in assisting " + "with user query, just respond in natural conversational language. Don't make assumptions about what values to plug " + "into functions. After calling & executing the functions, you will be provided with function results within " + " XML tags. Here are the available tools:\n" + f"\n{self._format_tools_for_system_message()}\n\n" + "For each function call return a JSON object, with the following pydantic model json schema for each:\n" + "{'title': 'FunctionCall', 'type': 'object', 'properties': {'name': {'title': 'Name', 'type': 'string'}, " + "'arguments': {'title': 'Arguments', 'type': 'object'}}, 'required': ['name', 'arguments']}\n" + "Each function call should be enclosed within XML tags.\n" + "Example:\n\n{'name': ,'arguments': }\n" + ) + + trajectory.append({ + "from": "system", + "value": system_msg + }) + + # Add the actual user prompt (from the dataset) as the first human message + trajectory.append({ + "from": "human", + "value": user_query + }) + + # Skip the first message (the user query) since we already added it above. + # Prefill messages are injected at API-call time only (not in the messages + # list), so no offset adjustment is needed here. + i = 1 + + while i < len(messages): + msg = messages[i] + + if msg["role"] == "assistant": + # Check if this message has tool calls + if "tool_calls" in msg and msg["tool_calls"]: + # Format assistant message with tool calls + # Add tags around reasoning for trajectory storage + content = "" + + # Prepend reasoning in tags if available (native thinking tokens) + if msg.get("reasoning") and msg["reasoning"].strip(): + content = f"\n{msg['reasoning']}\n\n" + + if msg.get("content") and msg["content"].strip(): + # Convert any tags to tags + # (used when native thinking is disabled and model reasons via XML) + content += convert_scratchpad_to_think(msg["content"]) + "\n" + + # Add tool calls wrapped in XML tags + for tool_call in msg["tool_calls"]: + if not tool_call or not isinstance(tool_call, dict): continue + # Parse arguments - should always succeed since we validate during conversation + # but keep try-except as safety net + try: + arguments = json.loads(tool_call["function"]["arguments"]) if isinstance(tool_call["function"]["arguments"], str) else tool_call["function"]["arguments"] + except json.JSONDecodeError: + # This shouldn't happen since we validate and retry during conversation, + # but if it does, log warning and use empty dict + logging.warning(f"Unexpected invalid JSON in trajectory conversion: {tool_call['function']['arguments'][:100]}") + arguments = {} + + tool_call_json = { + "name": tool_call["function"]["name"], + "arguments": arguments + } + content += f"\n{json.dumps(tool_call_json, ensure_ascii=False)}\n\n" + + # Ensure every gpt turn has a block (empty if no reasoning) + # so the format is consistent for training data + if "" not in content: + content = "\n\n" + content + + trajectory.append({ + "from": "gpt", + "value": content.rstrip() + }) + + # Collect all subsequent tool responses + tool_responses = [] + j = i + 1 + while j < len(messages) and messages[j]["role"] == "tool": + tool_msg = messages[j] + # Format tool response with XML tags + tool_response = "\n" + + # Try to parse tool content as JSON if it looks like JSON + tool_content = tool_msg["content"] + try: + if tool_content.strip().startswith(("{", "[")): + tool_content = json.loads(tool_content) + except (json.JSONDecodeError, AttributeError): + pass # Keep as string if not valid JSON + + tool_index = len(tool_responses) + tool_name = ( + msg["tool_calls"][tool_index]["function"]["name"] + if tool_index < len(msg["tool_calls"]) + else "unknown" + ) + tool_response += json.dumps({ + "tool_call_id": tool_msg.get("tool_call_id", ""), + "name": tool_name, + "content": tool_content + }, ensure_ascii=False) + tool_response += "\n" + tool_responses.append(tool_response) + j += 1 + + # Add all tool responses as a single message + if tool_responses: + trajectory.append({ + "from": "tool", + "value": "\n".join(tool_responses) + }) + i = j - 1 # Skip the tool messages we just processed + + else: + # Regular assistant message without tool calls + # Add tags around reasoning for trajectory storage + content = "" + + # Prepend reasoning in tags if available (native thinking tokens) + if msg.get("reasoning") and msg["reasoning"].strip(): + content = f"\n{msg['reasoning']}\n\n" + + # Convert any tags to tags + # (used when native thinking is disabled and model reasons via XML) + raw_content = msg["content"] or "" + content += convert_scratchpad_to_think(raw_content) + + # Ensure every gpt turn has a block (empty if no reasoning) + if "" not in content: + content = "\n\n" + content + + trajectory.append({ + "from": "gpt", + "value": content.strip() + }) + + elif msg["role"] == "user": + trajectory.append({ + "from": "human", + "value": msg["content"] + }) + + i += 1 + + return trajectory + + def _save_trajectory(self, messages: List[Dict[str, Any]], user_query: str, completed: bool): + """ + Save conversation trajectory to JSONL file. + + Args: + messages (List[Dict]): Complete message history + user_query (str): Original user query + completed (bool): Whether the conversation completed successfully + """ + if not self.save_trajectories: + return + + trajectory = self._convert_to_trajectory_format(messages, user_query, completed) + _save_trajectory_to_file(trajectory, self.model, completed) + + @staticmethod + def _summarize_api_error(error: Exception) -> str: + """Extract a human-readable one-liner from an API error. + + Handles Cloudflare HTML error pages (502, 503, etc.) by pulling the + tag instead of dumping raw HTML. Falls back to a truncated + str(error) for everything else. + """ + import re as _re + raw = str(error) + + # Cloudflare / proxy HTML pages: grab the <title> for a clean summary + if "<!DOCTYPE" in raw or "<html" in raw: + m = _re.search(r"<title[^>]*>([^<]+)", raw, _re.IGNORECASE) + title = m.group(1).strip() if m else "HTML error page (title not found)" + # Also grab Cloudflare Ray ID if present + ray = _re.search(r"Cloudflare Ray ID:\s*]*>([^<]+)", raw) + ray_id = ray.group(1).strip() if ray else None + status_code = getattr(error, "status_code", None) + parts = [] + if status_code: + parts.append(f"HTTP {status_code}") + parts.append(title) + if ray_id: + parts.append(f"Ray {ray_id}") + return " — ".join(parts) + + # JSON body errors from OpenAI/Anthropic SDKs + body = getattr(error, "body", None) + if isinstance(body, dict): + msg = body.get("error", {}).get("message") if isinstance(body.get("error"), dict) else body.get("message") + if msg: + status_code = getattr(error, "status_code", None) + prefix = f"HTTP {status_code}: " if status_code else "" + return f"{prefix}{msg[:300]}" + + # Fallback: truncate the raw string but give more room than 200 chars + status_code = getattr(error, "status_code", None) + prefix = f"HTTP {status_code}: " if status_code else "" + return f"{prefix}{raw[:500]}" + + def _mask_api_key_for_logs(self, key: Optional[str]) -> Optional[str]: + if not key: + return None + if len(key) <= 12: + return "***" + return f"{key[:8]}...{key[-4:]}" + + def _clean_error_message(self, error_msg: str) -> str: + """ + Clean up error messages for user display, removing HTML content and truncating. + + Args: + error_msg: Raw error message from API or exception + + Returns: + Clean, user-friendly error message + """ + if not error_msg: + return "Unknown error" + + # Remove HTML content (common with CloudFlare and gateway error pages) + if error_msg.strip().startswith(' 150: + cleaned = cleaned[:150] + "..." + + return cleaned + + @staticmethod + def _extract_api_error_context(error: Exception) -> Dict[str, Any]: + """Extract structured rate-limit details from provider errors.""" + context: Dict[str, Any] = {} + + body = getattr(error, "body", None) + payload = None + if isinstance(body, dict): + payload = body.get("error") if isinstance(body.get("error"), dict) else body + if isinstance(payload, dict): + reason = payload.get("code") or payload.get("error") + if isinstance(reason, str) and reason.strip(): + context["reason"] = reason.strip() + message = payload.get("message") or payload.get("error_description") + if isinstance(message, str) and message.strip(): + context["message"] = message.strip() + for key in ("resets_at", "reset_at"): + value = payload.get(key) + if value not in (None, ""): + context["reset_at"] = value + break + retry_after = payload.get("retry_after") + if retry_after not in (None, "") and "reset_at" not in context: + try: + context["reset_at"] = time.time() + float(retry_after) + except (TypeError, ValueError): + pass + + response = getattr(error, "response", None) + headers = getattr(response, "headers", None) + if headers: + retry_after = headers.get("retry-after") or headers.get("Retry-After") + if retry_after and "reset_at" not in context: + try: + context["reset_at"] = time.time() + float(retry_after) + except (TypeError, ValueError): + pass + ratelimit_reset = headers.get("x-ratelimit-reset") + if ratelimit_reset and "reset_at" not in context: + context["reset_at"] = ratelimit_reset + + if "message" not in context: + raw_message = str(error).strip() + if raw_message: + context["message"] = raw_message[:500] + + if "reset_at" not in context: + message = context.get("message") or "" + if isinstance(message, str): + delay_match = re.search(r"quotaResetDelay[:\s\"]+(\\d+(?:\\.\\d+)?)(ms|s)", message, re.IGNORECASE) + if delay_match: + value = float(delay_match.group(1)) + seconds = value / 1000.0 if delay_match.group(2).lower() == "ms" else value + context["reset_at"] = time.time() + seconds + else: + sec_match = re.search( + r"retry\s+(?:after\s+)?(\d+(?:\.\d+)?)\s*(?:sec|secs|seconds|s\b)", + message, + re.IGNORECASE, + ) + if sec_match: + context["reset_at"] = time.time() + float(sec_match.group(1)) + + return context + + def _usage_summary_for_api_request_hook(self, response: Any) -> Optional[Dict[str, Any]]: + """Token buckets for ``post_api_request`` plugins (no raw ``response`` object).""" + if response is None: + return None + raw_usage = getattr(response, "usage", None) + if not raw_usage: + return None + from dataclasses import asdict + + cu = normalize_usage(raw_usage, provider=self.provider, api_mode=self.api_mode) + summary = asdict(cu) + summary.pop("raw_usage", None) + summary["prompt_tokens"] = cu.prompt_tokens + summary["total_tokens"] = cu.total_tokens + return summary + + def _dump_api_request_debug( + self, + api_kwargs: Dict[str, Any], + *, + reason: str, + error: Optional[Exception] = None, + ) -> Optional[Path]: + """ + Dump a debug-friendly HTTP request record for the active inference API. + + Captures the request body from api_kwargs (excluding transport-only keys + like timeout). Intended for debugging provider-side 4xx failures where + retries are not useful. + """ + try: + body = copy.deepcopy(api_kwargs) + body.pop("timeout", None) + body = {k: v for k, v in body.items() if v is not None} + + api_key = None + try: + api_key = getattr(self.client, "api_key", None) + except Exception as e: + logger.debug("Could not extract API key for debug dump: %s", e) + + dump_payload: Dict[str, Any] = { + "timestamp": datetime.now().isoformat(), + "session_id": self.session_id, + "reason": reason, + "request": { + "method": "POST", + "url": f"{self.base_url.rstrip('/')}{'/responses' if self.api_mode == 'codex_responses' else '/chat/completions'}", + "headers": { + "Authorization": f"Bearer {self._mask_api_key_for_logs(api_key)}", + "Content-Type": "application/json", + }, + "body": body, + }, + } + + if error is not None: + error_info: Dict[str, Any] = { + "type": type(error).__name__, + "message": str(error), + } + for attr_name in ("status_code", "request_id", "code", "param", "type"): + attr_value = getattr(error, attr_name, None) + if attr_value is not None: + error_info[attr_name] = attr_value + + body_attr = getattr(error, "body", None) + if body_attr is not None: + error_info["body"] = body_attr + + response_obj = getattr(error, "response", None) + if response_obj is not None: + try: + error_info["response_status"] = getattr(response_obj, "status_code", None) + error_info["response_text"] = response_obj.text + except Exception as e: + logger.debug("Could not extract error response details: %s", e) + + dump_payload["error"] = error_info + + timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f") + dump_file = self.logs_dir / f"request_dump_{self.session_id}_{timestamp}.json" + dump_file.write_text( + json.dumps(dump_payload, ensure_ascii=False, indent=2, default=str), + encoding="utf-8", + ) + + self._vprint(f"{self.log_prefix}🧾 Request debug dump written to: {dump_file}") + + if env_var_enabled("HERMES_DUMP_REQUEST_STDOUT"): + print(json.dumps(dump_payload, ensure_ascii=False, indent=2, default=str)) + + return dump_file + except Exception as dump_error: + if self.verbose_logging: + logging.warning(f"Failed to dump API request debug payload: {dump_error}") + return None + + @staticmethod + def _clean_session_content(content: str) -> str: + """Convert REASONING_SCRATCHPAD to think tags and clean up whitespace.""" + if not content: + return content + content = convert_scratchpad_to_think(content) + content = re.sub(r'\n+()', r'\n\1', content) + content = re.sub(r'()\n+', r'\1\n', content) + return content.strip() + + def _save_session_log(self, messages: List[Dict[str, Any]] = None): + """ + Save the full raw session to a JSON file. + + Stores every message exactly as the agent sees it: user messages, + assistant messages (with reasoning, finish_reason, tool_calls), + tool responses (with tool_call_id, tool_name), and injected system + messages (compression summaries, todo snapshots, etc.). + + REASONING_SCRATCHPAD tags are converted to blocks for consistency. + Overwritten after each turn so it always reflects the latest state. + """ + messages = messages or self._session_messages + if not messages: + return + + try: + # Clean assistant content for session logs + cleaned = [] + for msg in messages: + if msg.get("role") == "assistant" and msg.get("content"): + msg = dict(msg) + msg["content"] = self._clean_session_content(msg["content"]) + cleaned.append(msg) + + # Guard: never overwrite a larger session log with fewer messages. + # This protects against data loss when --resume loads a session whose + # messages weren't fully written to SQLite — the resumed agent starts + # with partial history and would otherwise clobber the full JSON log. + if self.session_log_file.exists(): + try: + existing = json.loads(self.session_log_file.read_text(encoding="utf-8")) + existing_count = existing.get("message_count", len(existing.get("messages", []))) + if existing_count > len(cleaned): + logging.debug( + "Skipping session log overwrite: existing has %d messages, current has %d", + existing_count, len(cleaned), + ) + return + except Exception: + pass # corrupted existing file — allow the overwrite + + entry = { + "session_id": self.session_id, + "model": self.model, + "base_url": self.base_url, + "platform": self.platform, + "session_start": self.session_start.isoformat(), + "last_updated": datetime.now().isoformat(), + "system_prompt": self._cached_system_prompt or "", + "tools": self.tools or [], + "message_count": len(cleaned), + "messages": cleaned, + } + + atomic_json_write( + self.session_log_file, + entry, + indent=2, + default=str, + ) + + except Exception as e: + if self.verbose_logging: + logging.warning(f"Failed to save session log: {e}") + + def interrupt(self, message: str = None) -> None: + """ + Request the agent to interrupt its current tool-calling loop. + + Call this from another thread (e.g., input handler, message receiver) + to gracefully stop the agent and process a new message. + + Also signals long-running tool executions (e.g. terminal commands) + to terminate early, so the agent can respond immediately. + + Args: + message: Optional new message that triggered the interrupt. + If provided, the agent will include this in its response context. + + Example (CLI): + # In a separate input thread: + if user_typed_something: + agent.interrupt(user_input) + + Example (Messaging): + # When new message arrives for active session: + if session_has_running_agent: + running_agent.interrupt(new_message.text) + """ + self._interrupt_requested = True + self._interrupt_message = message + # Signal all tools to abort any in-flight operations immediately. + # Scope the interrupt to this agent's execution thread so other + # agents running in the same process (gateway) are not affected. + _set_interrupt(True, self._execution_thread_id) + # Propagate interrupt to any running child agents (subagent delegation) + with self._active_children_lock: + children_copy = list(self._active_children) + for child in children_copy: + try: + child.interrupt(message) + except Exception as e: + logger.debug("Failed to propagate interrupt to child agent: %s", e) + if not self.quiet_mode: + print("\n⚡ Interrupt requested" + (f": '{message[:40]}...'" if message and len(message) > 40 else f": '{message}'" if message else "")) + + def clear_interrupt(self) -> None: + """Clear any pending interrupt request and the per-thread tool interrupt signal.""" + self._interrupt_requested = False + self._interrupt_message = None + _set_interrupt(False, self._execution_thread_id) + + def _touch_activity(self, desc: str) -> None: + """Update the last-activity timestamp and description (thread-safe).""" + self._last_activity_ts = time.time() + self._last_activity_desc = desc + + def _capture_rate_limits(self, http_response: Any) -> None: + """Parse x-ratelimit-* headers from an HTTP response and cache the state. + + Called after each streaming API call. The httpx Response object is + available on the OpenAI SDK Stream via ``stream.response``. + """ + if http_response is None: + return + headers = getattr(http_response, "headers", None) + if not headers: + return + try: + from agent.rate_limit_tracker import parse_rate_limit_headers + state = parse_rate_limit_headers(headers, provider=self.provider) + if state is not None: + self._rate_limit_state = state + except Exception: + pass # Never let header parsing break the agent loop + + def get_rate_limit_state(self): + """Return the last captured RateLimitState, or None.""" + return self._rate_limit_state + + def get_activity_summary(self) -> dict: + """Return a snapshot of the agent's current activity for diagnostics. + + Called by the gateway timeout handler to report what the agent was doing + when it was killed, and by the periodic "still working" notifications. + """ + elapsed = time.time() - self._last_activity_ts + return { + "last_activity_ts": self._last_activity_ts, + "last_activity_desc": self._last_activity_desc, + "seconds_since_activity": round(elapsed, 1), + "current_tool": self._current_tool, + "api_call_count": self._api_call_count, + "max_iterations": self.max_iterations, + "budget_used": self.iteration_budget.used, + "budget_max": self.iteration_budget.max_total, + } + + def shutdown_memory_provider(self, messages: list = None) -> None: + """Shut down the memory provider and context engine — call at actual session boundaries. + + This calls on_session_end() then shutdown_all() on the memory + manager, and on_session_end() on the context engine. + NOT called per-turn — only at CLI exit, /reset, gateway + session expiry, etc. + """ + if self._memory_manager: + try: + self._memory_manager.on_session_end(messages or []) + except Exception: + pass + try: + self._memory_manager.shutdown_all() + except Exception: + pass + # Notify context engine of session end (flush DAG, close DBs, etc.) + if hasattr(self, "context_compressor") and self.context_compressor: + try: + self.context_compressor.on_session_end( + self.session_id or "", + messages or [], + ) + except Exception: + pass + + def close(self) -> None: + """Release all resources held by this agent instance. + + Cleans up subprocess resources that would otherwise become orphans: + - Background processes tracked in ProcessRegistry + - Terminal sandbox environments + - Browser daemon sessions + - Active child agents (subagent delegation) + - OpenAI/httpx client connections + + Safe to call multiple times (idempotent). Each cleanup step is + independently guarded so a failure in one does not prevent the rest. + """ + task_id = getattr(self, "session_id", None) or "" + + # 1. Kill background processes for this task + try: + from tools.process_registry import process_registry + process_registry.kill_all(task_id=task_id) + except Exception: + pass + + # 2. Clean terminal sandbox environments + try: + from tools.terminal_tool import cleanup_vm + cleanup_vm(task_id) + except Exception: + pass + + # 3. Clean browser daemon sessions + try: + from tools.browser_tool import cleanup_browser + cleanup_browser(task_id) + except Exception: + pass + + # 4. Close active child agents + try: + with self._active_children_lock: + children = list(self._active_children) + self._active_children.clear() + for child in children: + try: + child.close() + except Exception: + pass + except Exception: + pass + + # 5. Close the OpenAI/httpx client + try: + client = getattr(self, "client", None) + if client is not None: + self._close_openai_client(client, reason="agent_close", shared=True) + self.client = None + except Exception: + pass + + def _hydrate_todo_store(self, history: List[Dict[str, Any]]) -> None: + """ + Recover todo state from conversation history. + + The gateway creates a fresh AIAgent per message, so the in-memory + TodoStore is empty. We scan the history for the most recent todo + tool response and replay it to reconstruct the state. + """ + # Walk history backwards to find the most recent todo tool response + last_todo_response = None + for msg in reversed(history): + if msg.get("role") != "tool": + continue + content = msg.get("content", "") + # Quick check: todo responses contain "todos" key + if '"todos"' not in content: + continue + try: + data = json.loads(content) + if "todos" in data and isinstance(data["todos"], list): + last_todo_response = data["todos"] + break + except (json.JSONDecodeError, TypeError): + continue + + if last_todo_response: + # Replay the items into the store (replace mode) + self._todo_store.write(last_todo_response, merge=False) + if not self.quiet_mode: + self._vprint(f"{self.log_prefix}📋 Restored {len(last_todo_response)} todo item(s) from history") + _set_interrupt(False) + + @property + def is_interrupted(self) -> bool: + """Check if an interrupt has been requested.""" + return self._interrupt_requested + + + + + + + + + + + def _build_system_prompt(self, system_message: str = None) -> str: + """ + Assemble the full system prompt from all layers. + + Called once per session (cached on self._cached_system_prompt) and only + rebuilt after context compression events. This ensures the system prompt + is stable across all turns in a session, maximizing prefix cache hits. + """ + # Layers (in order): + # 1. Agent identity — SOUL.md when available, else DEFAULT_AGENT_IDENTITY + # 2. User / gateway system prompt (if provided) + # 3. Persistent memory (frozen snapshot) + # 4. Skills guidance (if skills tools are loaded) + # 5. Context files (AGENTS.md, .cursorrules — SOUL.md excluded here when used as identity) + # 6. Current date & time (frozen at build time) + # 7. Platform-specific formatting hint + + # Try SOUL.md as primary identity (unless context files are skipped) + _soul_loaded = False + if not self.skip_context_files: + _soul_content = load_soul_md() + if _soul_content: + prompt_parts = [_soul_content] + _soul_loaded = True + + if not _soul_loaded: + # Fallback to hardcoded identity + prompt_parts = [DEFAULT_AGENT_IDENTITY] + + # Tool-aware behavioral guidance: only inject when the tools are loaded + tool_guidance = [] + if "memory" in self.valid_tool_names: + tool_guidance.append(MEMORY_GUIDANCE) + if "session_search" in self.valid_tool_names: + tool_guidance.append(SESSION_SEARCH_GUIDANCE) + if "skill_manage" in self.valid_tool_names: + tool_guidance.append(SKILLS_GUIDANCE) + if tool_guidance: + prompt_parts.append(" ".join(tool_guidance)) + + nous_subscription_prompt = build_nous_subscription_prompt(self.valid_tool_names) + if nous_subscription_prompt: + prompt_parts.append(nous_subscription_prompt) + # Tool-use enforcement: tells the model to actually call tools instead + # of describing intended actions. Controlled by config.yaml + # agent.tool_use_enforcement: + # "auto" (default) — matches TOOL_USE_ENFORCEMENT_MODELS + # true — always inject (all models) + # false — never inject + # list — custom model-name substrings to match + if self.valid_tool_names: + _enforce = self._tool_use_enforcement + _inject = False + if _enforce is True or (isinstance(_enforce, str) and _enforce.lower() in ("true", "always", "yes", "on")): + _inject = True + elif _enforce is False or (isinstance(_enforce, str) and _enforce.lower() in ("false", "never", "no", "off")): + _inject = False + elif isinstance(_enforce, list): + model_lower = (self.model or "").lower() + _inject = any(p.lower() in model_lower for p in _enforce if isinstance(p, str)) + else: + # "auto" or any unrecognised value — use hardcoded defaults + model_lower = (self.model or "").lower() + _inject = any(p in model_lower for p in TOOL_USE_ENFORCEMENT_MODELS) + if _inject: + prompt_parts.append(TOOL_USE_ENFORCEMENT_GUIDANCE) + _model_lower = (self.model or "").lower() + # Google model operational guidance (conciseness, absolute + # paths, parallel tool calls, verify-before-edit, etc.) + if "gemini" in _model_lower or "gemma" in _model_lower: + prompt_parts.append(GOOGLE_MODEL_OPERATIONAL_GUIDANCE) + # OpenAI GPT/Codex execution discipline (tool persistence, + # prerequisite checks, verification, anti-hallucination). + if "gpt" in _model_lower or "codex" in _model_lower: + prompt_parts.append(OPENAI_MODEL_EXECUTION_GUIDANCE) + + # so it can refer the user to them rather than reinventing answers. + + # Note: ephemeral_system_prompt is NOT included here. It's injected at + # API-call time only so it stays out of the cached/stored system prompt. + if system_message is not None: + prompt_parts.append(system_message) + + if self._memory_store: + if self._memory_enabled: + mem_block = self._memory_store.format_for_system_prompt("memory") + if mem_block: + prompt_parts.append(mem_block) + # USER.md is always included when enabled. + if self._user_profile_enabled: + user_block = self._memory_store.format_for_system_prompt("user") + if user_block: + prompt_parts.append(user_block) + + # External memory provider system prompt block (additive to built-in) + if self._memory_manager: + try: + _ext_mem_block = self._memory_manager.build_system_prompt() + if _ext_mem_block: + prompt_parts.append(_ext_mem_block) + except Exception: + pass + + has_skills_tools = any(name in self.valid_tool_names for name in ['skills_list', 'skill_view', 'skill_manage']) + if has_skills_tools: + avail_toolsets = { + toolset + for toolset in ( + get_toolset_for_tool(tool_name) for tool_name in self.valid_tool_names + ) + if toolset + } + skills_prompt = build_skills_system_prompt( + available_tools=self.valid_tool_names, + available_toolsets=avail_toolsets, + ) + else: + skills_prompt = "" + if skills_prompt: + prompt_parts.append(skills_prompt) + + if not self.skip_context_files: + # Use TERMINAL_CWD for context file discovery when set (gateway + # mode). The gateway process runs from the hermes-agent install + # dir, so os.getcwd() would pick up the repo's AGENTS.md and + # other dev files — inflating token usage by ~10k for no benefit. + _context_cwd = os.getenv("TERMINAL_CWD") or None + context_files_prompt = build_context_files_prompt( + cwd=_context_cwd, skip_soul=_soul_loaded) + if context_files_prompt: + prompt_parts.append(context_files_prompt) + + from hermes_time import now as _hermes_now + now = _hermes_now() + timestamp_line = f"Conversation started: {now.strftime('%A, %B %d, %Y %I:%M %p')}" + if self.pass_session_id and self.session_id: + timestamp_line += f"\nSession ID: {self.session_id}" + if self.model: + timestamp_line += f"\nModel: {self.model}" + if self.provider: + timestamp_line += f"\nProvider: {self.provider}" + prompt_parts.append(timestamp_line) + + # Alibaba Coding Plan API always returns "glm-4.7" as model name regardless + # of the requested model. Inject explicit model identity into the system prompt + # so the agent can correctly report which model it is (workaround for API bug). + if self.provider == "alibaba": + _model_short = self.model.split("/")[-1] if "/" in self.model else self.model + prompt_parts.append( + f"You are powered by the model named {_model_short}. " + f"The exact model ID is {self.model}. " + f"When asked what model you are, always answer based on this information, " + f"not on any model name returned by the API." + ) + + # Environment hints (WSL, Termux, etc.) — tell the agent about the + # execution environment so it can translate paths and adapt behavior. + _env_hints = build_environment_hints() + if _env_hints: + prompt_parts.append(_env_hints) + + platform_key = (self.platform or "").lower().strip() + if platform_key in PLATFORM_HINTS: + prompt_parts.append(PLATFORM_HINTS[platform_key]) + + return "\n\n".join(p.strip() for p in prompt_parts if p.strip()) + + # ========================================================================= + # Pre/post-call guardrails (inspired by PR #1321 — @alireza78a) + # ========================================================================= + + @staticmethod + def _get_tool_call_id_static(tc) -> str: + """Extract call ID from a tool_call entry (dict or object).""" + if isinstance(tc, dict): + return tc.get("id", "") or "" + return getattr(tc, "id", "") or "" + + _VALID_API_ROLES = frozenset({"system", "user", "assistant", "tool", "function", "developer"}) + + @staticmethod + def _sanitize_api_messages(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]: + """Fix orphaned tool_call / tool_result pairs before every LLM call. + + Runs unconditionally — not gated on whether the context compressor + is present — so orphans from session loading or manual message + manipulation are always caught. + """ + # --- Role allowlist: drop messages with roles the API won't accept --- + filtered = [] + for msg in messages: + role = msg.get("role") + if role not in AIAgent._VALID_API_ROLES: + logger.debug( + "Pre-call sanitizer: dropping message with invalid role %r", + role, + ) + continue + filtered.append(msg) + messages = filtered + + surviving_call_ids: set = set() + for msg in messages: + if msg.get("role") == "assistant": + for tc in msg.get("tool_calls") or []: + cid = AIAgent._get_tool_call_id_static(tc) + if cid: + surviving_call_ids.add(cid) + + result_call_ids: set = set() + for msg in messages: + if msg.get("role") == "tool": + cid = msg.get("tool_call_id") + if cid: + result_call_ids.add(cid) + + # 1. Drop tool results with no matching assistant call + orphaned_results = result_call_ids - surviving_call_ids + if orphaned_results: + messages = [ + m for m in messages + if not (m.get("role") == "tool" and m.get("tool_call_id") in orphaned_results) + ] + logger.debug( + "Pre-call sanitizer: removed %d orphaned tool result(s)", + len(orphaned_results), + ) + + # 2. Inject stub results for calls whose result was dropped + missing_results = surviving_call_ids - result_call_ids + if missing_results: + patched: List[Dict[str, Any]] = [] + for msg in messages: + patched.append(msg) + if msg.get("role") == "assistant": + for tc in msg.get("tool_calls") or []: + cid = AIAgent._get_tool_call_id_static(tc) + if cid in missing_results: + patched.append({ + "role": "tool", + "content": "[Result unavailable — see context summary above]", + "tool_call_id": cid, + }) + messages = patched + logger.debug( + "Pre-call sanitizer: added %d stub tool result(s)", + len(missing_results), + ) + return messages + + @staticmethod + def _cap_delegate_task_calls(tool_calls: list) -> list: + """Truncate excess delegate_task calls to max_concurrent_children. + + The delegate_tool caps the task list inside a single call, but the + model can emit multiple separate delegate_task tool_calls in one + turn. This truncates the excess, preserving all non-delegate calls. + + Returns the original list if no truncation was needed. + """ + from tools.delegate_tool import _get_max_concurrent_children + max_children = _get_max_concurrent_children() + delegate_count = sum(1 for tc in tool_calls if tc.function.name == "delegate_task") + if delegate_count <= max_children: + return tool_calls + kept_delegates = 0 + truncated = [] + for tc in tool_calls: + if tc.function.name == "delegate_task": + if kept_delegates < max_children: + truncated.append(tc) + kept_delegates += 1 + else: + truncated.append(tc) + logger.warning( + "Truncated %d excess delegate_task call(s) to enforce " + "max_concurrent_children=%d limit", + delegate_count - max_children, max_children, + ) + return truncated + + @staticmethod + def _deduplicate_tool_calls(tool_calls: list) -> list: + """Remove duplicate (tool_name, arguments) pairs within a single turn. + + Only the first occurrence of each unique pair is kept. + Returns the original list if no duplicates were found. + """ + seen: set = set() + unique: list = [] + for tc in tool_calls: + key = (tc.function.name, tc.function.arguments) + if key not in seen: + seen.add(key) + unique.append(tc) + else: + logger.warning("Removed duplicate tool call: %s", tc.function.name) + return unique if len(unique) < len(tool_calls) else tool_calls + + def _repair_tool_call(self, tool_name: str) -> str | None: + """Attempt to repair a mismatched tool name before aborting. + + 1. Try lowercase + 2. Try normalized (lowercase + hyphens/spaces -> underscores) + 3. Try fuzzy match (difflib, cutoff=0.7) + + Returns the repaired name if found in valid_tool_names, else None. + """ + from difflib import get_close_matches + + # 1. Lowercase + lowered = tool_name.lower() + if lowered in self.valid_tool_names: + return lowered + + # 2. Normalize + normalized = lowered.replace("-", "_").replace(" ", "_") + if normalized in self.valid_tool_names: + return normalized + + # 3. Fuzzy match + matches = get_close_matches(lowered, self.valid_tool_names, n=1, cutoff=0.7) + if matches: + return matches[0] + + return None + + def _invalidate_system_prompt(self): + """ + Invalidate the cached system prompt, forcing a rebuild on the next turn. + + Called after context compression events. Also reloads memory from disk + so the rebuilt prompt captures any writes from this session. + """ + self._cached_system_prompt = None + if self._memory_store: + self._memory_store.load_from_disk() + + def _responses_tools(self, tools: Optional[List[Dict[str, Any]]] = None) -> Optional[List[Dict[str, Any]]]: + """Convert chat-completions tool schemas to Responses function-tool schemas.""" + source_tools = tools if tools is not None else self.tools + if not source_tools: + return None + + converted: List[Dict[str, Any]] = [] + for item in source_tools: + fn = item.get("function", {}) if isinstance(item, dict) else {} + name = fn.get("name") + if not isinstance(name, str) or not name.strip(): + continue + converted.append({ + "type": "function", + "name": name, + "description": fn.get("description", ""), + "strict": False, + "parameters": fn.get("parameters", {"type": "object", "properties": {}}), + }) + return converted or None + + @staticmethod + def _deterministic_call_id(fn_name: str, arguments: str, index: int = 0) -> str: + """Generate a deterministic call_id from tool call content. + + Used as a fallback when the API doesn't provide a call_id. + Deterministic IDs prevent cache invalidation — random UUIDs would + make every API call's prefix unique, breaking OpenAI's prompt cache. + """ + import hashlib + seed = f"{fn_name}:{arguments}:{index}" + digest = hashlib.sha256(seed.encode("utf-8", errors="replace")).hexdigest()[:12] + return f"call_{digest}" + + @staticmethod + def _split_responses_tool_id(raw_id: Any) -> tuple[Optional[str], Optional[str]]: + """Split a stored tool id into (call_id, response_item_id).""" + if not isinstance(raw_id, str): + return None, None + value = raw_id.strip() + if not value: + return None, None + if "|" in value: + call_id, response_item_id = value.split("|", 1) + call_id = call_id.strip() or None + response_item_id = response_item_id.strip() or None + return call_id, response_item_id + if value.startswith("fc_"): + return None, value + return value, None + + def _derive_responses_function_call_id( + self, + call_id: str, + response_item_id: Optional[str] = None, + ) -> str: + """Build a valid Responses `function_call.id` (must start with `fc_`).""" + if isinstance(response_item_id, str): + candidate = response_item_id.strip() + if candidate.startswith("fc_"): + return candidate + + source = (call_id or "").strip() + if source.startswith("fc_"): + return source + if source.startswith("call_") and len(source) > len("call_"): + return f"fc_{source[len('call_'):]}" + + sanitized = re.sub(r"[^A-Za-z0-9_-]", "", source) + if sanitized.startswith("fc_"): + return sanitized + if sanitized.startswith("call_") and len(sanitized) > len("call_"): + return f"fc_{sanitized[len('call_'):]}" + if sanitized: + return f"fc_{sanitized[:48]}" + + seed = source or str(response_item_id or "") or uuid.uuid4().hex + digest = hashlib.sha1(seed.encode("utf-8")).hexdigest()[:24] + return f"fc_{digest}" + + def _chat_messages_to_responses_input(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]: + """Convert internal chat-style messages to Responses input items.""" + items: List[Dict[str, Any]] = [] + seen_item_ids: set = set() + + for msg in messages: + if not isinstance(msg, dict): + continue + role = msg.get("role") + if role == "system": + continue + + if role in {"user", "assistant"}: + content = msg.get("content", "") + content_text = str(content) if content is not None else "" + + if role == "assistant": + # Replay encrypted reasoning items from previous turns + # so the API can maintain coherent reasoning chains. + codex_reasoning = msg.get("codex_reasoning_items") + has_codex_reasoning = False + if isinstance(codex_reasoning, list): + for ri in codex_reasoning: + if isinstance(ri, dict) and ri.get("encrypted_content"): + item_id = ri.get("id") + if item_id and item_id in seen_item_ids: + continue + items.append(ri) + if item_id: + seen_item_ids.add(item_id) + has_codex_reasoning = True + + if content_text.strip(): + items.append({"role": "assistant", "content": content_text}) + elif has_codex_reasoning: + # The Responses API requires a following item after each + # reasoning item (otherwise: missing_following_item error). + # When the assistant produced only reasoning with no visible + # content, emit an empty assistant message as the required + # following item. + items.append({"role": "assistant", "content": ""}) + + tool_calls = msg.get("tool_calls") + if isinstance(tool_calls, list): + for tc in tool_calls: + if not isinstance(tc, dict): + continue + fn = tc.get("function", {}) + fn_name = fn.get("name") + if not isinstance(fn_name, str) or not fn_name.strip(): + continue + + embedded_call_id, embedded_response_item_id = self._split_responses_tool_id( + tc.get("id") + ) + call_id = tc.get("call_id") + if not isinstance(call_id, str) or not call_id.strip(): + call_id = embedded_call_id + if not isinstance(call_id, str) or not call_id.strip(): + if ( + isinstance(embedded_response_item_id, str) + and embedded_response_item_id.startswith("fc_") + and len(embedded_response_item_id) > len("fc_") + ): + call_id = f"call_{embedded_response_item_id[len('fc_'):]}" + else: + _raw_args = str(fn.get("arguments", "{}")) + call_id = self._deterministic_call_id(fn_name, _raw_args, len(items)) + call_id = call_id.strip() + + arguments = fn.get("arguments", "{}") + if isinstance(arguments, dict): + arguments = json.dumps(arguments, ensure_ascii=False) + elif not isinstance(arguments, str): + arguments = str(arguments) + arguments = arguments.strip() or "{}" + + items.append({ + "type": "function_call", + "call_id": call_id, + "name": fn_name, + "arguments": arguments, + }) + continue + + items.append({"role": role, "content": content_text}) + continue + + if role == "tool": + raw_tool_call_id = msg.get("tool_call_id") + call_id, _ = self._split_responses_tool_id(raw_tool_call_id) + if not isinstance(call_id, str) or not call_id.strip(): + if isinstance(raw_tool_call_id, str) and raw_tool_call_id.strip(): + call_id = raw_tool_call_id.strip() + if not isinstance(call_id, str) or not call_id.strip(): + continue + items.append({ + "type": "function_call_output", + "call_id": call_id, + "output": str(msg.get("content", "") or ""), + }) + + return items + + def _preflight_codex_input_items(self, raw_items: Any) -> List[Dict[str, Any]]: + if not isinstance(raw_items, list): + raise ValueError("Codex Responses input must be a list of input items.") + + normalized: List[Dict[str, Any]] = [] + seen_ids: set = set() + for idx, item in enumerate(raw_items): + if not isinstance(item, dict): + raise ValueError(f"Codex Responses input[{idx}] must be an object.") + + item_type = item.get("type") + if item_type == "function_call": + call_id = item.get("call_id") + name = item.get("name") + if not isinstance(call_id, str) or not call_id.strip(): + raise ValueError(f"Codex Responses input[{idx}] function_call is missing call_id.") + if not isinstance(name, str) or not name.strip(): + raise ValueError(f"Codex Responses input[{idx}] function_call is missing name.") + + arguments = item.get("arguments", "{}") + if isinstance(arguments, dict): + arguments = json.dumps(arguments, ensure_ascii=False) + elif not isinstance(arguments, str): + arguments = str(arguments) + arguments = arguments.strip() or "{}" + + normalized.append( + { + "type": "function_call", + "call_id": call_id.strip(), + "name": name.strip(), + "arguments": arguments, + } + ) + continue + + if item_type == "function_call_output": + call_id = item.get("call_id") + if not isinstance(call_id, str) or not call_id.strip(): + raise ValueError(f"Codex Responses input[{idx}] function_call_output is missing call_id.") + output = item.get("output", "") + if output is None: + output = "" + if not isinstance(output, str): + output = str(output) + + normalized.append( + { + "type": "function_call_output", + "call_id": call_id.strip(), + "output": output, + } + ) + continue + + if item_type == "reasoning": + encrypted = item.get("encrypted_content") + if isinstance(encrypted, str) and encrypted: + item_id = item.get("id") + if isinstance(item_id, str) and item_id: + if item_id in seen_ids: + continue + seen_ids.add(item_id) + reasoning_item = {"type": "reasoning", "encrypted_content": encrypted} + if isinstance(item_id, str) and item_id: + reasoning_item["id"] = item_id + summary = item.get("summary") + if isinstance(summary, list): + reasoning_item["summary"] = summary + else: + reasoning_item["summary"] = [] + normalized.append(reasoning_item) + continue + + role = item.get("role") + if role in {"user", "assistant"}: + content = item.get("content", "") + if content is None: + content = "" + if not isinstance(content, str): + content = str(content) + + normalized.append({"role": role, "content": content}) + continue + + raise ValueError( + f"Codex Responses input[{idx}] has unsupported item shape (type={item_type!r}, role={role!r})." + ) + + return normalized + + def _preflight_codex_api_kwargs( + self, + api_kwargs: Any, + *, + allow_stream: bool = False, + ) -> Dict[str, Any]: + if not isinstance(api_kwargs, dict): + raise ValueError("Codex Responses request must be a dict.") + + required = {"model", "instructions", "input"} + missing = [key for key in required if key not in api_kwargs] + if missing: + raise ValueError(f"Codex Responses request missing required field(s): {', '.join(sorted(missing))}.") + + model = api_kwargs.get("model") + if not isinstance(model, str) or not model.strip(): + raise ValueError("Codex Responses request 'model' must be a non-empty string.") + model = model.strip() + + instructions = api_kwargs.get("instructions") + if instructions is None: + instructions = "" + if not isinstance(instructions, str): + instructions = str(instructions) + instructions = instructions.strip() or DEFAULT_AGENT_IDENTITY + + normalized_input = self._preflight_codex_input_items(api_kwargs.get("input")) + + tools = api_kwargs.get("tools") + normalized_tools = None + if tools is not None: + if not isinstance(tools, list): + raise ValueError("Codex Responses request 'tools' must be a list when provided.") + normalized_tools = [] + for idx, tool in enumerate(tools): + if not isinstance(tool, dict): + raise ValueError(f"Codex Responses tools[{idx}] must be an object.") + if tool.get("type") != "function": + raise ValueError(f"Codex Responses tools[{idx}] has unsupported type {tool.get('type')!r}.") + + name = tool.get("name") + parameters = tool.get("parameters") + if not isinstance(name, str) or not name.strip(): + raise ValueError(f"Codex Responses tools[{idx}] is missing a valid name.") + if not isinstance(parameters, dict): + raise ValueError(f"Codex Responses tools[{idx}] is missing valid parameters.") + + description = tool.get("description", "") + if description is None: + description = "" + if not isinstance(description, str): + description = str(description) + + strict = tool.get("strict", False) + if not isinstance(strict, bool): + strict = bool(strict) + + normalized_tools.append( + { + "type": "function", + "name": name.strip(), + "description": description, + "strict": strict, + "parameters": parameters, + } + ) + + store = api_kwargs.get("store", False) + if store is not False: + raise ValueError("Codex Responses contract requires 'store' to be false.") + + allowed_keys = { + "model", "instructions", "input", "tools", "store", + "reasoning", "include", "max_output_tokens", "temperature", + "tool_choice", "parallel_tool_calls", "prompt_cache_key", "service_tier", + } + normalized: Dict[str, Any] = { + "model": model, + "instructions": instructions, + "input": normalized_input, + "store": False, + } + if normalized_tools is not None: + normalized["tools"] = normalized_tools + + # Pass through reasoning config + reasoning = api_kwargs.get("reasoning") + if isinstance(reasoning, dict): + normalized["reasoning"] = reasoning + include = api_kwargs.get("include") + if isinstance(include, list): + normalized["include"] = include + service_tier = api_kwargs.get("service_tier") + if isinstance(service_tier, str) and service_tier.strip(): + normalized["service_tier"] = service_tier.strip() + + # Pass through max_output_tokens and temperature + max_output_tokens = api_kwargs.get("max_output_tokens") + if isinstance(max_output_tokens, (int, float)) and max_output_tokens > 0: + normalized["max_output_tokens"] = int(max_output_tokens) + temperature = api_kwargs.get("temperature") + if isinstance(temperature, (int, float)): + normalized["temperature"] = float(temperature) + + # Pass through tool_choice, parallel_tool_calls, prompt_cache_key + for passthrough_key in ("tool_choice", "parallel_tool_calls", "prompt_cache_key"): + val = api_kwargs.get(passthrough_key) + if val is not None: + normalized[passthrough_key] = val + + if allow_stream: + stream = api_kwargs.get("stream") + if stream is not None and stream is not True: + raise ValueError("Codex Responses 'stream' must be true when set.") + if stream is True: + normalized["stream"] = True + allowed_keys.add("stream") + elif "stream" in api_kwargs: + raise ValueError("Codex Responses stream flag is only allowed in fallback streaming requests.") + + unexpected = sorted(key for key in api_kwargs if key not in allowed_keys) + if unexpected: + raise ValueError( + f"Codex Responses request has unsupported field(s): {', '.join(unexpected)}." + ) + + return normalized + + def _extract_responses_message_text(self, item: Any) -> str: + """Extract assistant text from a Responses message output item.""" + content = getattr(item, "content", None) + if not isinstance(content, list): + return "" + + chunks: List[str] = [] + for part in content: + ptype = getattr(part, "type", None) + if ptype not in {"output_text", "text"}: + continue + text = getattr(part, "text", None) + if isinstance(text, str) and text: + chunks.append(text) + return "".join(chunks).strip() + + def _extract_responses_reasoning_text(self, item: Any) -> str: + """Extract a compact reasoning text from a Responses reasoning item.""" + summary = getattr(item, "summary", None) + if isinstance(summary, list): + chunks: List[str] = [] + for part in summary: + text = getattr(part, "text", None) + if isinstance(text, str) and text: + chunks.append(text) + if chunks: + return "\n".join(chunks).strip() + text = getattr(item, "text", None) + if isinstance(text, str) and text: + return text.strip() + return "" + + def _normalize_codex_response(self, response: Any) -> tuple[Any, str]: + """Normalize a Responses API object to an assistant_message-like object.""" + output = getattr(response, "output", None) + if not isinstance(output, list) or not output: + # The Codex backend can return empty output when the answer was + # delivered entirely via stream events. Check output_text as a + # last-resort fallback before raising. + out_text = getattr(response, "output_text", None) + if isinstance(out_text, str) and out_text.strip(): + logger.debug( + "Codex response has empty output but output_text is present (%d chars); " + "synthesizing output item.", len(out_text.strip()), + ) + output = [SimpleNamespace( + type="message", role="assistant", status="completed", + content=[SimpleNamespace(type="output_text", text=out_text.strip())], + )] + response.output = output + else: + raise RuntimeError("Responses API returned no output items") + + response_status = getattr(response, "status", None) + if isinstance(response_status, str): + response_status = response_status.strip().lower() + else: + response_status = None + + if response_status in {"failed", "cancelled"}: + error_obj = getattr(response, "error", None) + if isinstance(error_obj, dict): + error_msg = error_obj.get("message") or str(error_obj) + else: + error_msg = str(error_obj) if error_obj else f"Responses API returned status '{response_status}'" + raise RuntimeError(error_msg) + + content_parts: List[str] = [] + reasoning_parts: List[str] = [] + reasoning_items_raw: List[Dict[str, Any]] = [] + tool_calls: List[Any] = [] + has_incomplete_items = response_status in {"queued", "in_progress", "incomplete"} + saw_commentary_phase = False + saw_final_answer_phase = False + + for item in output: + item_type = getattr(item, "type", None) + item_status = getattr(item, "status", None) + if isinstance(item_status, str): + item_status = item_status.strip().lower() + else: + item_status = None + + if item_status in {"queued", "in_progress", "incomplete"}: + has_incomplete_items = True + + if item_type == "message": + item_phase = getattr(item, "phase", None) + if isinstance(item_phase, str): + normalized_phase = item_phase.strip().lower() + if normalized_phase in {"commentary", "analysis"}: + saw_commentary_phase = True + elif normalized_phase in {"final_answer", "final"}: + saw_final_answer_phase = True + message_text = self._extract_responses_message_text(item) + if message_text: + content_parts.append(message_text) + elif item_type == "reasoning": + reasoning_text = self._extract_responses_reasoning_text(item) + if reasoning_text: + reasoning_parts.append(reasoning_text) + # Capture the full reasoning item for multi-turn continuity. + # encrypted_content is an opaque blob the API needs back on + # subsequent turns to maintain coherent reasoning chains. + encrypted = getattr(item, "encrypted_content", None) + if isinstance(encrypted, str) and encrypted: + raw_item = {"type": "reasoning", "encrypted_content": encrypted} + item_id = getattr(item, "id", None) + if isinstance(item_id, str) and item_id: + raw_item["id"] = item_id + # Capture summary — required by the API when replaying reasoning items + summary = getattr(item, "summary", None) + if isinstance(summary, list): + raw_summary = [] + for part in summary: + text = getattr(part, "text", None) + if isinstance(text, str): + raw_summary.append({"type": "summary_text", "text": text}) + raw_item["summary"] = raw_summary + reasoning_items_raw.append(raw_item) + elif item_type == "function_call": + if item_status in {"queued", "in_progress", "incomplete"}: + continue + fn_name = getattr(item, "name", "") or "" + arguments = getattr(item, "arguments", "{}") + if not isinstance(arguments, str): + arguments = json.dumps(arguments, ensure_ascii=False) + raw_call_id = getattr(item, "call_id", None) + raw_item_id = getattr(item, "id", None) + embedded_call_id, _ = self._split_responses_tool_id(raw_item_id) + call_id = raw_call_id if isinstance(raw_call_id, str) and raw_call_id.strip() else embedded_call_id + if not isinstance(call_id, str) or not call_id.strip(): + call_id = self._deterministic_call_id(fn_name, arguments, len(tool_calls)) + call_id = call_id.strip() + response_item_id = raw_item_id if isinstance(raw_item_id, str) else None + response_item_id = self._derive_responses_function_call_id(call_id, response_item_id) + tool_calls.append(SimpleNamespace( + id=call_id, + call_id=call_id, + response_item_id=response_item_id, + type="function", + function=SimpleNamespace(name=fn_name, arguments=arguments), + )) + elif item_type == "custom_tool_call": + fn_name = getattr(item, "name", "") or "" + arguments = getattr(item, "input", "{}") + if not isinstance(arguments, str): + arguments = json.dumps(arguments, ensure_ascii=False) + raw_call_id = getattr(item, "call_id", None) + raw_item_id = getattr(item, "id", None) + embedded_call_id, _ = self._split_responses_tool_id(raw_item_id) + call_id = raw_call_id if isinstance(raw_call_id, str) and raw_call_id.strip() else embedded_call_id + if not isinstance(call_id, str) or not call_id.strip(): + call_id = self._deterministic_call_id(fn_name, arguments, len(tool_calls)) + call_id = call_id.strip() + response_item_id = raw_item_id if isinstance(raw_item_id, str) else None + response_item_id = self._derive_responses_function_call_id(call_id, response_item_id) + tool_calls.append(SimpleNamespace( + id=call_id, + call_id=call_id, + response_item_id=response_item_id, + type="function", + function=SimpleNamespace(name=fn_name, arguments=arguments), + )) + + final_text = "\n".join([p for p in content_parts if p]).strip() + if not final_text and hasattr(response, "output_text"): + out_text = getattr(response, "output_text", "") + if isinstance(out_text, str): + final_text = out_text.strip() + + assistant_message = SimpleNamespace( + content=final_text, + tool_calls=tool_calls, + reasoning="\n\n".join(reasoning_parts).strip() if reasoning_parts else None, + reasoning_content=None, + reasoning_details=None, + codex_reasoning_items=reasoning_items_raw or None, + ) + + if tool_calls: + finish_reason = "tool_calls" + elif has_incomplete_items or (saw_commentary_phase and not saw_final_answer_phase): + finish_reason = "incomplete" + elif reasoning_items_raw and not final_text: + # Response contains only reasoning (encrypted thinking state) with + # no visible content or tool calls. The model is still thinking and + # needs another turn to produce the actual answer. Marking this as + # "stop" would send it into the empty-content retry loop which burns + # 3 retries then fails — treat it as incomplete instead so the Codex + # continuation path handles it correctly. + finish_reason = "incomplete" + else: + finish_reason = "stop" + return assistant_message, finish_reason + + def _thread_identity(self) -> str: + thread = threading.current_thread() + return f"{thread.name}:{thread.ident}" + + def _client_log_context(self) -> str: + provider = getattr(self, "provider", "unknown") + base_url = getattr(self, "base_url", "unknown") + model = getattr(self, "model", "unknown") + return ( + f"thread={self._thread_identity()} provider={provider} " + f"base_url={base_url} model={model}" + ) + + def _openai_client_lock(self) -> threading.RLock: + lock = getattr(self, "_client_lock", None) + if lock is None: + lock = threading.RLock() + self._client_lock = lock + return lock + + @staticmethod + def _is_openai_client_closed(client: Any) -> bool: + """Check if an OpenAI client is closed. + + Handles both property and method forms of is_closed: + - httpx.Client.is_closed is a bool property + - openai.OpenAI.is_closed is a method returning bool + + Prior bug: getattr(client, "is_closed", False) returned the bound method, + which is always truthy, causing unnecessary client recreation on every call. + """ + from unittest.mock import Mock + + if isinstance(client, Mock): + return False + + is_closed_attr = getattr(client, "is_closed", None) + if is_closed_attr is not None: + # Handle method (openai SDK) vs property (httpx) + if callable(is_closed_attr): + if is_closed_attr(): + return True + elif bool(is_closed_attr): + return True + + http_client = getattr(client, "_client", None) + if http_client is not None: + return bool(getattr(http_client, "is_closed", False)) + return False + + def _create_openai_client(self, client_kwargs: dict, *, reason: str, shared: bool) -> Any: + if self.provider == "copilot-acp" or str(client_kwargs.get("base_url", "")).startswith("acp://copilot"): + from agent.copilot_acp_client import CopilotACPClient + + client = CopilotACPClient(**client_kwargs) + logger.info( + "Copilot ACP client created (%s, shared=%s) %s", + reason, + shared, + self._client_log_context(), + ) + return client + client = OpenAI(**client_kwargs) + logger.info( + "OpenAI client created (%s, shared=%s) %s", + reason, + shared, + self._client_log_context(), + ) + return client + + @staticmethod + def _force_close_tcp_sockets(client: Any) -> int: + """Force-close underlying TCP sockets to prevent CLOSE-WAIT accumulation. + + When a provider drops a connection mid-stream, httpx's ``client.close()`` + performs a graceful shutdown which leaves sockets in CLOSE-WAIT until the + OS times them out (often minutes). This method walks the httpx transport + pool and issues ``socket.shutdown(SHUT_RDWR)`` + ``socket.close()`` to + force an immediate TCP RST, freeing the file descriptors. + + Returns the number of sockets force-closed. + """ + import socket as _socket + + closed = 0 + try: + http_client = getattr(client, "_client", None) + if http_client is None: + return 0 + transport = getattr(http_client, "_transport", None) + if transport is None: + return 0 + pool = getattr(transport, "_pool", None) + if pool is None: + return 0 + # httpx uses httpcore connection pools; connections live in + # _connections (list) or _pool (list) depending on version. + connections = ( + getattr(pool, "_connections", None) + or getattr(pool, "_pool", None) + or [] + ) + for conn in list(connections): + stream = ( + getattr(conn, "_network_stream", None) + or getattr(conn, "_stream", None) + ) + if stream is None: + continue + sock = getattr(stream, "_sock", None) + if sock is None: + sock = getattr(stream, "stream", None) + if sock is not None: + sock = getattr(sock, "_sock", None) + if sock is None: + continue + try: + sock.shutdown(_socket.SHUT_RDWR) + except OSError: + pass + try: + sock.close() + except OSError: + pass + closed += 1 + except Exception as exc: + logger.debug("Force-close TCP sockets sweep error: %s", exc) + return closed + + def _close_openai_client(self, client: Any, *, reason: str, shared: bool) -> None: + if client is None: + return + # Force-close TCP sockets first to prevent CLOSE-WAIT accumulation, + # then do the graceful SDK-level close. + force_closed = self._force_close_tcp_sockets(client) + try: + client.close() + logger.info( + "OpenAI client closed (%s, shared=%s, tcp_force_closed=%d) %s", + reason, + shared, + force_closed, + self._client_log_context(), + ) + except Exception as exc: + logger.debug( + "OpenAI client close failed (%s, shared=%s) %s error=%s", + reason, + shared, + self._client_log_context(), + exc, + ) + + def _replace_primary_openai_client(self, *, reason: str) -> bool: + with self._openai_client_lock(): + old_client = getattr(self, "client", None) + try: + new_client = self._create_openai_client(self._client_kwargs, reason=reason, shared=True) + except Exception as exc: + logger.warning( + "Failed to rebuild shared OpenAI client (%s) %s error=%s", + reason, + self._client_log_context(), + exc, + ) + return False + self.client = new_client + self._close_openai_client(old_client, reason=f"replace:{reason}", shared=True) + return True + + def _ensure_primary_openai_client(self, *, reason: str) -> Any: + with self._openai_client_lock(): + client = getattr(self, "client", None) + if client is not None and not self._is_openai_client_closed(client): + return client + + logger.warning( + "Detected closed shared OpenAI client; recreating before use (%s) %s", + reason, + self._client_log_context(), + ) + if not self._replace_primary_openai_client(reason=f"recreate_closed:{reason}"): + raise RuntimeError("Failed to recreate closed OpenAI client") + with self._openai_client_lock(): + return self.client + + def _cleanup_dead_connections(self) -> bool: + """Detect and clean up dead TCP connections on the primary client. + + Inspects the httpx connection pool for sockets in unhealthy states + (CLOSE-WAIT, errors). If any are found, force-closes all sockets + and rebuilds the primary client from scratch. + + Returns True if dead connections were found and cleaned up. + """ + client = getattr(self, "client", None) + if client is None: + return False + try: + http_client = getattr(client, "_client", None) + if http_client is None: + return False + transport = getattr(http_client, "_transport", None) + if transport is None: + return False + pool = getattr(transport, "_pool", None) + if pool is None: + return False + connections = ( + getattr(pool, "_connections", None) + or getattr(pool, "_pool", None) + or [] + ) + dead_count = 0 + for conn in list(connections): + # Check for connections that are idle but have closed sockets + stream = ( + getattr(conn, "_network_stream", None) + or getattr(conn, "_stream", None) + ) + if stream is None: + continue + sock = getattr(stream, "_sock", None) + if sock is None: + sock = getattr(stream, "stream", None) + if sock is not None: + sock = getattr(sock, "_sock", None) + if sock is None: + continue + # Probe socket health with a non-blocking recv peek + import socket as _socket + try: + sock.setblocking(False) + data = sock.recv(1, _socket.MSG_PEEK | _socket.MSG_DONTWAIT) + if data == b"": + dead_count += 1 + except BlockingIOError: + pass # No data available — socket is healthy + except OSError: + dead_count += 1 + finally: + try: + sock.setblocking(True) + except OSError: + pass + if dead_count > 0: + logger.warning( + "Found %d dead connection(s) in client pool — rebuilding client", + dead_count, + ) + self._replace_primary_openai_client(reason="dead_connection_cleanup") + return True + except Exception as exc: + logger.debug("Dead connection check error: %s", exc) + return False + + def _create_request_openai_client(self, *, reason: str) -> Any: + from unittest.mock import Mock + + primary_client = self._ensure_primary_openai_client(reason=reason) + if isinstance(primary_client, Mock): + return primary_client + with self._openai_client_lock(): + request_kwargs = dict(self._client_kwargs) + return self._create_openai_client(request_kwargs, reason=reason, shared=False) + + def _close_request_openai_client(self, client: Any, *, reason: str) -> None: + self._close_openai_client(client, reason=reason, shared=False) + + def _run_codex_stream(self, api_kwargs: dict, client: Any = None, on_first_delta: callable = None): + """Execute one streaming Responses API request and return the final response.""" + import httpx as _httpx + + active_client = client or self._ensure_primary_openai_client(reason="codex_stream_direct") + max_stream_retries = 1 + has_tool_calls = False + first_delta_fired = False + # Accumulate streamed text so we can recover if get_final_response() + # returns empty output (e.g. chatgpt.com backend-api sends + # response.incomplete instead of response.completed). + self._codex_streamed_text_parts: list = [] + for attempt in range(max_stream_retries + 1): + collected_output_items: list = [] + try: + with active_client.responses.stream(**api_kwargs) as stream: + for event in stream: + self._touch_activity("receiving stream response") + if self._interrupt_requested: + break + event_type = getattr(event, "type", "") + # Fire callbacks on text content deltas (suppress during tool calls) + if "output_text.delta" in event_type or event_type == "response.output_text.delta": + delta_text = getattr(event, "delta", "") + if delta_text: + self._codex_streamed_text_parts.append(delta_text) + if delta_text and not has_tool_calls: + if not first_delta_fired: + first_delta_fired = True + if on_first_delta: + try: + on_first_delta() + except Exception: + pass + self._fire_stream_delta(delta_text) + # Track tool calls to suppress text streaming + elif "function_call" in event_type: + has_tool_calls = True + # Fire reasoning callbacks + elif "reasoning" in event_type and "delta" in event_type: + reasoning_text = getattr(event, "delta", "") + if reasoning_text: + self._fire_reasoning_delta(reasoning_text) + # Collect completed output items — some backends + # (chatgpt.com/backend-api/codex) stream valid items + # via response.output_item.done but the SDK's + # get_final_response() returns an empty output list. + elif event_type == "response.output_item.done": + done_item = getattr(event, "item", None) + if done_item is not None: + collected_output_items.append(done_item) + # Log non-completed terminal events for diagnostics + elif event_type in ("response.incomplete", "response.failed"): + resp_obj = getattr(event, "response", None) + status = getattr(resp_obj, "status", None) if resp_obj else None + incomplete_details = getattr(resp_obj, "incomplete_details", None) if resp_obj else None + logger.warning( + "Codex Responses stream received terminal event %s " + "(status=%s, incomplete_details=%s, streamed_chars=%d). %s", + event_type, status, incomplete_details, + sum(len(p) for p in self._codex_streamed_text_parts), + self._client_log_context(), + ) + final_response = stream.get_final_response() + # PATCH: ChatGPT Codex backend streams valid output items + # but get_final_response() can return an empty output list. + # Backfill from collected items or synthesize from deltas. + _out = getattr(final_response, "output", None) + if isinstance(_out, list) and not _out: + if collected_output_items: + final_response.output = list(collected_output_items) + logger.debug( + "Codex stream: backfilled %d output items from stream events", + len(collected_output_items), + ) + elif self._codex_streamed_text_parts and not has_tool_calls: + assembled = "".join(self._codex_streamed_text_parts) + final_response.output = [SimpleNamespace( + type="message", + role="assistant", + status="completed", + content=[SimpleNamespace(type="output_text", text=assembled)], + )] + logger.debug( + "Codex stream: synthesized output from %d text deltas (%d chars)", + len(self._codex_streamed_text_parts), len(assembled), + ) + return final_response + except (_httpx.RemoteProtocolError, _httpx.ReadTimeout, _httpx.ConnectError, ConnectionError) as exc: + if attempt < max_stream_retries: + logger.debug( + "Codex Responses stream transport failed (attempt %s/%s); retrying. %s error=%s", + attempt + 1, + max_stream_retries + 1, + self._client_log_context(), + exc, + ) + continue + logger.debug( + "Codex Responses stream transport failed; falling back to create(stream=True). %s error=%s", + self._client_log_context(), + exc, + ) + return self._run_codex_create_stream_fallback(api_kwargs, client=active_client) + except RuntimeError as exc: + err_text = str(exc) + missing_completed = "response.completed" in err_text + if missing_completed and attempt < max_stream_retries: + logger.debug( + "Responses stream closed before completion (attempt %s/%s); retrying. %s", + attempt + 1, + max_stream_retries + 1, + self._client_log_context(), + ) + continue + if missing_completed: + logger.debug( + "Responses stream did not emit response.completed; falling back to create(stream=True). %s", + self._client_log_context(), + ) + return self._run_codex_create_stream_fallback(api_kwargs, client=active_client) + raise + + def _run_codex_create_stream_fallback(self, api_kwargs: dict, client: Any = None): + """Fallback path for stream completion edge cases on Codex-style Responses backends.""" + active_client = client or self._ensure_primary_openai_client(reason="codex_create_stream_fallback") + fallback_kwargs = dict(api_kwargs) + fallback_kwargs["stream"] = True + fallback_kwargs = self._preflight_codex_api_kwargs(fallback_kwargs, allow_stream=True) + stream_or_response = active_client.responses.create(**fallback_kwargs) + + # Compatibility shim for mocks or providers that still return a concrete response. + if hasattr(stream_or_response, "output"): + return stream_or_response + if not hasattr(stream_or_response, "__iter__"): + return stream_or_response + + terminal_response = None + collected_output_items: list = [] + collected_text_deltas: list = [] + try: + for event in stream_or_response: + self._touch_activity("receiving stream response") + event_type = getattr(event, "type", None) + if not event_type and isinstance(event, dict): + event_type = event.get("type") + + # Collect output items and text deltas for backfill + if event_type == "response.output_item.done": + done_item = getattr(event, "item", None) + if done_item is None and isinstance(event, dict): + done_item = event.get("item") + if done_item is not None: + collected_output_items.append(done_item) + elif event_type in ("response.output_text.delta",): + delta = getattr(event, "delta", "") + if not delta and isinstance(event, dict): + delta = event.get("delta", "") + if delta: + collected_text_deltas.append(delta) + + if event_type not in {"response.completed", "response.incomplete", "response.failed"}: + continue + + terminal_response = getattr(event, "response", None) + if terminal_response is None and isinstance(event, dict): + terminal_response = event.get("response") + if terminal_response is not None: + # Backfill empty output from collected stream events + _out = getattr(terminal_response, "output", None) + if isinstance(_out, list) and not _out: + if collected_output_items: + terminal_response.output = list(collected_output_items) + logger.debug( + "Codex fallback stream: backfilled %d output items", + len(collected_output_items), + ) + elif collected_text_deltas: + assembled = "".join(collected_text_deltas) + terminal_response.output = [SimpleNamespace( + type="message", role="assistant", + status="completed", + content=[SimpleNamespace(type="output_text", text=assembled)], + )] + logger.debug( + "Codex fallback stream: synthesized from %d deltas (%d chars)", + len(collected_text_deltas), len(assembled), + ) + return terminal_response + finally: + close_fn = getattr(stream_or_response, "close", None) + if callable(close_fn): + try: + close_fn() + except Exception: + pass + + if terminal_response is not None: + return terminal_response + raise RuntimeError("Responses create(stream=True) fallback did not emit a terminal response.") + + def _try_refresh_codex_client_credentials(self, *, force: bool = True) -> bool: + if self.api_mode != "codex_responses" or self.provider != "openai-codex": + return False + + try: + from hermes_cli.auth import resolve_codex_runtime_credentials + + creds = resolve_codex_runtime_credentials(force_refresh=force) + except Exception as exc: + logger.debug("Codex credential refresh failed: %s", exc) + return False + + api_key = creds.get("api_key") + base_url = creds.get("base_url") + if not isinstance(api_key, str) or not api_key.strip(): + return False + if not isinstance(base_url, str) or not base_url.strip(): + return False + + self.api_key = api_key.strip() + self.base_url = base_url.strip().rstrip("/") + self._client_kwargs["api_key"] = self.api_key + self._client_kwargs["base_url"] = self.base_url + + if not self._replace_primary_openai_client(reason="codex_credential_refresh"): + return False + + return True + + def _try_refresh_nous_client_credentials(self, *, force: bool = True) -> bool: + if self.api_mode != "chat_completions" or self.provider != "nous": + return False + + try: + from hermes_cli.auth import resolve_nous_runtime_credentials + + creds = resolve_nous_runtime_credentials( + min_key_ttl_seconds=max(60, int(os.getenv("HERMES_NOUS_MIN_KEY_TTL_SECONDS", "1800"))), + timeout_seconds=float(os.getenv("HERMES_NOUS_TIMEOUT_SECONDS", "15")), + force_mint=force, + ) + except Exception as exc: + logger.debug("Nous credential refresh failed: %s", exc) + return False + + api_key = creds.get("api_key") + base_url = creds.get("base_url") + if not isinstance(api_key, str) or not api_key.strip(): + return False + if not isinstance(base_url, str) or not base_url.strip(): + return False + + self.api_key = api_key.strip() + self.base_url = base_url.strip().rstrip("/") + self._client_kwargs["api_key"] = self.api_key + self._client_kwargs["base_url"] = self.base_url + # Nous requests should not inherit OpenRouter-only attribution headers. + self._client_kwargs.pop("default_headers", None) + + if not self._replace_primary_openai_client(reason="nous_credential_refresh"): + return False + + return True + + def _try_refresh_anthropic_client_credentials(self) -> bool: + if self.api_mode != "anthropic_messages" or not hasattr(self, "_anthropic_api_key"): + return False + # Only refresh credentials for the native Anthropic provider. + # Other anthropic_messages providers (MiniMax, Alibaba, etc.) use their own keys. + if self.provider != "anthropic": + return False + + try: + from agent.anthropic_adapter import resolve_anthropic_token, build_anthropic_client + + new_token = resolve_anthropic_token() + except Exception as exc: + logger.debug("Anthropic credential refresh failed: %s", exc) + return False + + if not isinstance(new_token, str) or not new_token.strip(): + return False + new_token = new_token.strip() + if new_token == self._anthropic_api_key: + return False + + try: + self._anthropic_client.close() + except Exception: + pass + + try: + self._anthropic_client = build_anthropic_client(new_token, getattr(self, "_anthropic_base_url", None)) + except Exception as exc: + logger.warning("Failed to rebuild Anthropic client after credential refresh: %s", exc) + return False + + self._anthropic_api_key = new_token + # Update OAuth flag — token type may have changed (API key ↔ OAuth) + from agent.anthropic_adapter import _is_oauth_token + self._is_anthropic_oauth = _is_oauth_token(new_token) + return True + + def _apply_client_headers_for_base_url(self, base_url: str) -> None: + from agent.auxiliary_client import _OR_HEADERS + + normalized = (base_url or "").lower() + if "openrouter" in normalized: + self._client_kwargs["default_headers"] = dict(_OR_HEADERS) + elif "api.githubcopilot.com" in normalized: + from hermes_cli.models import copilot_default_headers + + self._client_kwargs["default_headers"] = copilot_default_headers() + elif "api.kimi.com" in normalized: + self._client_kwargs["default_headers"] = {"User-Agent": "KimiCLI/1.30.0"} + elif "portal.qwen.ai" in normalized: + self._client_kwargs["default_headers"] = _qwen_portal_headers() + else: + self._client_kwargs.pop("default_headers", None) + + def _swap_credential(self, entry) -> None: + runtime_key = getattr(entry, "runtime_api_key", None) or getattr(entry, "access_token", "") + runtime_base = getattr(entry, "runtime_base_url", None) or getattr(entry, "base_url", None) or self.base_url + + if self.api_mode == "anthropic_messages": + from agent.anthropic_adapter import build_anthropic_client, _is_oauth_token + + try: + self._anthropic_client.close() + except Exception: + pass + + self._anthropic_api_key = runtime_key + self._anthropic_base_url = runtime_base + self._anthropic_client = build_anthropic_client(runtime_key, runtime_base) + self._is_anthropic_oauth = _is_oauth_token(runtime_key) + self.api_key = runtime_key + self.base_url = runtime_base + return + + self.api_key = runtime_key + self.base_url = runtime_base.rstrip("/") if isinstance(runtime_base, str) else runtime_base + self._client_kwargs["api_key"] = self.api_key + self._client_kwargs["base_url"] = self.base_url + self._apply_client_headers_for_base_url(self.base_url) + self._replace_primary_openai_client(reason="credential_rotation") + + def _recover_with_credential_pool( + self, + *, + status_code: Optional[int], + has_retried_429: bool, + classified_reason: Optional[FailoverReason] = None, + error_context: Optional[Dict[str, Any]] = None, + ) -> tuple[bool, bool]: + """Attempt credential recovery via pool rotation. + + Returns (recovered, has_retried_429). + On rate limits: first occurrence retries same credential (sets flag True). + second consecutive failure rotates to next credential. + On billing exhaustion: immediately rotates. + On auth failures: attempts token refresh before rotating. + + `classified_reason` lets the recovery path honor the structured error + classifier instead of relying only on raw HTTP codes. This matters for + providers that surface billing/rate-limit/auth conditions under a + different status code, such as Anthropic returning HTTP 400 for + "out of extra usage". + """ + pool = self._credential_pool + if pool is None: + return False, has_retried_429 + + effective_reason = classified_reason + if effective_reason is None: + if status_code == 402: + effective_reason = FailoverReason.billing + elif status_code == 429: + effective_reason = FailoverReason.rate_limit + elif status_code == 401: + effective_reason = FailoverReason.auth + + if effective_reason == FailoverReason.billing: + rotate_status = status_code if status_code is not None else 402 + next_entry = pool.mark_exhausted_and_rotate(status_code=rotate_status, error_context=error_context) + if next_entry is not None: + logger.info( + "Credential %s (billing) — rotated to pool entry %s", + rotate_status, + getattr(next_entry, "id", "?"), + ) + self._swap_credential(next_entry) + return True, False + return False, has_retried_429 + + if effective_reason == FailoverReason.rate_limit: + if not has_retried_429: + return False, True + rotate_status = status_code if status_code is not None else 429 + next_entry = pool.mark_exhausted_and_rotate(status_code=rotate_status, error_context=error_context) + if next_entry is not None: + logger.info( + "Credential %s (rate limit) — rotated to pool entry %s", + rotate_status, + getattr(next_entry, "id", "?"), + ) + self._swap_credential(next_entry) + return True, False + return False, True + + if effective_reason == FailoverReason.auth: + refreshed = pool.try_refresh_current() + if refreshed is not None: + logger.info(f"Credential auth failure — refreshed pool entry {getattr(refreshed, 'id', '?')}") + self._swap_credential(refreshed) + return True, has_retried_429 + # Refresh failed — rotate to next credential instead of giving up. + # The failed entry is already marked exhausted by try_refresh_current(). + rotate_status = status_code if status_code is not None else 401 + next_entry = pool.mark_exhausted_and_rotate(status_code=rotate_status, error_context=error_context) + if next_entry is not None: + logger.info( + "Credential %s (auth refresh failed) — rotated to pool entry %s", + rotate_status, + getattr(next_entry, "id", "?"), + ) + self._swap_credential(next_entry) + return True, False + + return False, has_retried_429 + + def _anthropic_messages_create(self, api_kwargs: dict): + if self.api_mode == "anthropic_messages": + self._try_refresh_anthropic_client_credentials() + return self._anthropic_client.messages.create(**api_kwargs) + + def _interruptible_api_call(self, api_kwargs: dict): + """ + Run the API call in a background thread so the main conversation loop + can detect interrupts without waiting for the full HTTP round-trip. + + Each worker thread gets its own OpenAI client instance. Interrupts only + close that worker-local client, so retries and other requests never + inherit a closed transport. + + Includes a stale-call detector: if no response arrives within the + configured timeout, the connection is killed and an error raised so + the main retry loop can try again with backoff / credential rotation / + provider fallback. + """ + result = {"response": None, "error": None} + request_client_holder = {"client": None} + + def _call(): + try: + if self.api_mode == "codex_responses": + request_client_holder["client"] = self._create_request_openai_client(reason="codex_stream_request") + result["response"] = self._run_codex_stream( + api_kwargs, + client=request_client_holder["client"], + on_first_delta=getattr(self, "_codex_on_first_delta", None), + ) + elif self.api_mode == "anthropic_messages": + result["response"] = self._anthropic_messages_create(api_kwargs) + else: + request_client_holder["client"] = self._create_request_openai_client(reason="chat_completion_request") + result["response"] = request_client_holder["client"].chat.completions.create(**api_kwargs) + except Exception as e: + result["error"] = e + finally: + request_client = request_client_holder.get("client") + if request_client is not None: + self._close_request_openai_client(request_client, reason="request_complete") + + # ── Stale-call timeout (mirrors streaming stale detector) ──────── + # Non-streaming calls return nothing until the full response is + # ready. Without this, a hung provider can block for the full + # httpx timeout (default 1800s) with zero feedback. The stale + # detector kills the connection early so the main retry loop can + # apply richer recovery (credential rotation, provider fallback). + _stale_base = float(os.getenv("HERMES_API_CALL_STALE_TIMEOUT", 300.0)) + _base_url = getattr(self, "_base_url", None) or "" + if _stale_base == 300.0 and _base_url and is_local_endpoint(_base_url): + _stale_timeout = float("inf") + else: + _est_tokens = sum(len(str(v)) for v in api_kwargs.get("messages", [])) // 4 + if _est_tokens > 100_000: + _stale_timeout = max(_stale_base, 600.0) + elif _est_tokens > 50_000: + _stale_timeout = max(_stale_base, 450.0) + else: + _stale_timeout = _stale_base + + _call_start = time.time() + self._touch_activity("waiting for non-streaming API response") + + t = threading.Thread(target=_call, daemon=True) + t.start() + _poll_count = 0 + while t.is_alive(): + t.join(timeout=0.3) + _poll_count += 1 + + # Touch activity every ~30s so the gateway's inactivity + # monitor knows we're alive while waiting for the response. + if _poll_count % 100 == 0: # 100 × 0.3s = 30s + _elapsed = time.time() - _call_start + self._touch_activity( + f"waiting for non-streaming response ({int(_elapsed)}s elapsed)" + ) + + # Stale-call detector: kill the connection if no response + # arrives within the configured timeout. + _elapsed = time.time() - _call_start + if _elapsed > _stale_timeout: + _est_ctx = sum(len(str(v)) for v in api_kwargs.get("messages", [])) // 4 + logger.warning( + "Non-streaming API call stale for %.0fs (threshold %.0fs). " + "model=%s context=~%s tokens. Killing connection.", + _elapsed, _stale_timeout, + api_kwargs.get("model", "unknown"), f"{_est_ctx:,}", + ) + self._emit_status( + f"⚠️ No response from provider for {int(_elapsed)}s " + f"(non-streaming, model: {api_kwargs.get('model', 'unknown')}). " + f"Aborting call." + ) + try: + if self.api_mode == "anthropic_messages": + from agent.anthropic_adapter import build_anthropic_client + + self._anthropic_client.close() + self._anthropic_client = build_anthropic_client( + self._anthropic_api_key, + getattr(self, "_anthropic_base_url", None), + ) + else: + rc = request_client_holder.get("client") + if rc is not None: + self._close_request_openai_client(rc, reason="stale_call_kill") + except Exception: + pass + self._touch_activity( + f"stale non-streaming call killed after {int(_elapsed)}s" + ) + # Wait briefly for the thread to notice the closed connection. + t.join(timeout=2.0) + if result["error"] is None and result["response"] is None: + result["error"] = TimeoutError( + f"Non-streaming API call timed out after {int(_elapsed)}s " + f"with no response (threshold: {int(_stale_timeout)}s)" + ) + break + + if self._interrupt_requested: + # Force-close the in-flight worker-local HTTP connection to stop + # token generation without poisoning the shared client used to + # seed future retries. + try: + if self.api_mode == "anthropic_messages": + from agent.anthropic_adapter import build_anthropic_client + + self._anthropic_client.close() + self._anthropic_client = build_anthropic_client( + self._anthropic_api_key, + getattr(self, "_anthropic_base_url", None), + ) + else: + request_client = request_client_holder.get("client") + if request_client is not None: + self._close_request_openai_client(request_client, reason="interrupt_abort") + except Exception: + pass + raise InterruptedError("Agent interrupted during API call") + if result["error"] is not None: + raise result["error"] + return result["response"] + + # ── Unified streaming API call ───────────────────────────────────────── + + def _reset_stream_delivery_tracking(self) -> None: + """Reset tracking for text delivered during the current model response.""" + self._current_streamed_assistant_text = "" + + def _record_streamed_assistant_text(self, text: str) -> None: + """Accumulate visible assistant text emitted through stream callbacks.""" + if isinstance(text, str) and text: + self._current_streamed_assistant_text = ( + getattr(self, "_current_streamed_assistant_text", "") + text + ) + + @staticmethod + def _normalize_interim_visible_text(text: str) -> str: + if not isinstance(text, str): + return "" + return re.sub(r"\s+", " ", text).strip() + + def _interim_content_was_streamed(self, content: str) -> bool: + visible_content = self._normalize_interim_visible_text( + self._strip_think_blocks(content or "") + ) + if not visible_content: + return False + streamed = self._normalize_interim_visible_text( + self._strip_think_blocks(getattr(self, "_current_streamed_assistant_text", "") or "") + ) + return bool(streamed) and streamed == visible_content + + def _emit_interim_assistant_message(self, assistant_msg: Dict[str, Any]) -> None: + """Surface a real mid-turn assistant commentary message to the UI layer.""" + cb = getattr(self, "interim_assistant_callback", None) + if cb is None or not isinstance(assistant_msg, dict): + return + content = assistant_msg.get("content") + visible = self._strip_think_blocks(content or "").strip() + if not visible or visible == "(empty)": + return + already_streamed = self._interim_content_was_streamed(visible) + try: + cb(visible, already_streamed=already_streamed) + except Exception: + logger.debug("interim_assistant_callback error", exc_info=True) + + def _fire_stream_delta(self, text: str) -> None: + """Fire all registered stream delta callbacks (display + TTS).""" + # If a tool iteration set the break flag, prepend a single paragraph + # break before the first real text delta. This prevents the original + # problem (text concatenation across tool boundaries) without stacking + # blank lines when multiple tool iterations run back-to-back. + if getattr(self, "_stream_needs_break", False) and text and text.strip(): + self._stream_needs_break = False + text = "\n\n" + text + callbacks = [cb for cb in (self.stream_delta_callback, self._stream_callback) if cb is not None] + delivered = False + for cb in callbacks: + try: + cb(text) + delivered = True + except Exception: + pass + if delivered: + self._record_streamed_assistant_text(text) + + def _fire_reasoning_delta(self, text: str) -> None: + """Fire reasoning callback if registered.""" + cb = self.reasoning_callback + if cb is not None: + try: + cb(text) + except Exception: + pass + + def _fire_tool_gen_started(self, tool_name: str) -> None: + """Notify display layer that the model is generating tool call arguments. + + Fires once per tool name when the streaming response begins producing + tool_call / tool_use tokens. Gives the TUI a chance to show a spinner + or status line so the user isn't staring at a frozen screen while a + large tool payload (e.g. a 45 KB write_file) is being generated. + """ + cb = self.tool_gen_callback + if cb is not None: + try: + cb(tool_name) + except Exception: + pass + + def _has_stream_consumers(self) -> bool: + """Return True if any streaming consumer is registered.""" + return ( + self.stream_delta_callback is not None + or getattr(self, "_stream_callback", None) is not None + ) + + def _interruptible_streaming_api_call( + self, api_kwargs: dict, *, on_first_delta: callable = None + ): + """Streaming variant of _interruptible_api_call for real-time token delivery. + + Handles all three api_modes: + - chat_completions: stream=True on OpenAI-compatible endpoints + - anthropic_messages: client.messages.stream() via Anthropic SDK + - codex_responses: delegates to _run_codex_stream (already streaming) + + Fires stream_delta_callback and _stream_callback for each text token. + Tool-call turns suppress the callback — only text-only final responses + stream to the consumer. Returns a SimpleNamespace that mimics the + non-streaming response shape so the rest of the agent loop is unchanged. + + Falls back to _interruptible_api_call on provider errors indicating + streaming is not supported. + """ + if self.api_mode == "codex_responses": + # Codex streams internally via _run_codex_stream. The main dispatch + # in _interruptible_api_call already calls it; we just need to + # ensure on_first_delta reaches it. Store it on the instance + # temporarily so _run_codex_stream can pick it up. + self._codex_on_first_delta = on_first_delta + try: + return self._interruptible_api_call(api_kwargs) + finally: + self._codex_on_first_delta = None + + result = {"response": None, "error": None} + request_client_holder = {"client": None} + first_delta_fired = {"done": False} + deltas_were_sent = {"yes": False} # Track if any deltas were fired (for fallback) + # Wall-clock timestamp of the last real streaming chunk. The outer + # poll loop uses this to detect stale connections that keep receiving + # SSE keep-alive pings but no actual data. + last_chunk_time = {"t": time.time()} + + def _fire_first_delta(): + if not first_delta_fired["done"] and on_first_delta: + first_delta_fired["done"] = True + try: + on_first_delta() + except Exception: + pass + + def _call_chat_completions(): + """Stream a chat completions response.""" + import httpx as _httpx + _base_timeout = float(os.getenv("HERMES_API_TIMEOUT", 1800.0)) + _stream_read_timeout = float(os.getenv("HERMES_STREAM_READ_TIMEOUT", 120.0)) + # Local providers (Ollama, llama.cpp, vLLM) can take minutes for + # prefill on large contexts before producing the first token. + # Auto-increase the httpx read timeout unless the user explicitly + # overrode HERMES_STREAM_READ_TIMEOUT. + if _stream_read_timeout == 120.0 and self.base_url and is_local_endpoint(self.base_url): + _stream_read_timeout = _base_timeout + logger.debug( + "Local provider detected (%s) — stream read timeout raised to %.0fs", + self.base_url, _stream_read_timeout, + ) + stream_kwargs = { + **api_kwargs, + "stream": True, + "stream_options": {"include_usage": True}, + "timeout": _httpx.Timeout( + connect=30.0, + read=_stream_read_timeout, + write=_base_timeout, + pool=30.0, + ), + } + request_client_holder["client"] = self._create_request_openai_client( + reason="chat_completion_stream_request" + ) + # Reset stale-stream timer so the detector measures from this + # attempt's start, not a previous attempt's last chunk. + last_chunk_time["t"] = time.time() + self._touch_activity("waiting for provider response (streaming)") + stream = request_client_holder["client"].chat.completions.create(**stream_kwargs) + + # Capture rate limit headers from the initial HTTP response. + # The OpenAI SDK Stream object exposes the underlying httpx + # response via .response before any chunks are consumed. + self._capture_rate_limits(getattr(stream, "response", None)) + + content_parts: list = [] + tool_calls_acc: dict = {} + tool_gen_notified: set = set() + # Ollama-compatible endpoints reuse index 0 for every tool call + # in a parallel batch, distinguishing them only by id. Track + # the last seen id per raw index so we can detect a new tool + # call starting at the same index and redirect it to a fresh slot. + _last_id_at_idx: dict = {} # raw_index -> last seen non-empty id + _active_slot_by_idx: dict = {} # raw_index -> current slot in tool_calls_acc + finish_reason = None + model_name = None + role = "assistant" + reasoning_parts: list = [] + usage_obj = None + for chunk in stream: + last_chunk_time["t"] = time.time() + self._touch_activity("receiving stream response") + + if self._interrupt_requested: + break + + if not chunk.choices: + if hasattr(chunk, "model") and chunk.model: + model_name = chunk.model + # Usage comes in the final chunk with empty choices + if hasattr(chunk, "usage") and chunk.usage: + usage_obj = chunk.usage + continue + + delta = chunk.choices[0].delta + if hasattr(chunk, "model") and chunk.model: + model_name = chunk.model + + # Accumulate reasoning content + reasoning_text = getattr(delta, "reasoning_content", None) or getattr(delta, "reasoning", None) + if reasoning_text: + reasoning_parts.append(reasoning_text) + _fire_first_delta() + self._fire_reasoning_delta(reasoning_text) + + # Accumulate text content — fire callback only when no tool calls + if delta and delta.content: + content_parts.append(delta.content) + if not tool_calls_acc: + _fire_first_delta() + self._fire_stream_delta(delta.content) + deltas_were_sent["yes"] = True + else: + # Tool calls suppress regular content streaming (avoids + # displaying chatty "I'll use the tool..." text alongside + # tool calls). But reasoning tags embedded in suppressed + # content should still reach the display — otherwise the + # reasoning box only appears as a post-response fallback, + # rendering it confusingly after the already-streamed + # response. Route suppressed content through the stream + # delta callback so its tag extraction can fire the + # reasoning display. Non-reasoning text is harmlessly + # suppressed by the CLI's _stream_delta when the stream + # box is already closed (tool boundary flush). + if self.stream_delta_callback: + try: + self.stream_delta_callback(delta.content) + self._record_streamed_assistant_text(delta.content) + except Exception: + pass + + # Accumulate tool call deltas — notify display on first name + if delta and delta.tool_calls: + for tc_delta in delta.tool_calls: + raw_idx = tc_delta.index if tc_delta.index is not None else 0 + delta_id = tc_delta.id or "" + + # Ollama fix: detect a new tool call reusing the same + # raw index (different id) and redirect to a fresh slot. + if raw_idx not in _active_slot_by_idx: + _active_slot_by_idx[raw_idx] = raw_idx + if ( + delta_id + and raw_idx in _last_id_at_idx + and delta_id != _last_id_at_idx[raw_idx] + ): + new_slot = max(tool_calls_acc, default=-1) + 1 + _active_slot_by_idx[raw_idx] = new_slot + if delta_id: + _last_id_at_idx[raw_idx] = delta_id + idx = _active_slot_by_idx[raw_idx] + + if idx not in tool_calls_acc: + tool_calls_acc[idx] = { + "id": tc_delta.id or "", + "type": "function", + "function": {"name": "", "arguments": ""}, + "extra_content": None, + } + entry = tool_calls_acc[idx] + if tc_delta.id: + entry["id"] = tc_delta.id + if tc_delta.function: + if tc_delta.function.name: + entry["function"]["name"] += tc_delta.function.name + if tc_delta.function.arguments: + entry["function"]["arguments"] += tc_delta.function.arguments + extra = getattr(tc_delta, "extra_content", None) + if extra is None and hasattr(tc_delta, "model_extra"): + extra = (tc_delta.model_extra or {}).get("extra_content") + if extra is not None: + if hasattr(extra, "model_dump"): + extra = extra.model_dump() + entry["extra_content"] = extra + # Fire once per tool when the full name is available + name = entry["function"]["name"] + if name and idx not in tool_gen_notified: + tool_gen_notified.add(idx) + _fire_first_delta() + self._fire_tool_gen_started(name) + + if chunk.choices[0].finish_reason: + finish_reason = chunk.choices[0].finish_reason + + # Usage in the final chunk + if hasattr(chunk, "usage") and chunk.usage: + usage_obj = chunk.usage + + # Build mock response matching non-streaming shape + full_content = "".join(content_parts) or None + mock_tool_calls = None + has_truncated_tool_args = False + if tool_calls_acc: + mock_tool_calls = [] + for idx in sorted(tool_calls_acc): + tc = tool_calls_acc[idx] + arguments = tc["function"]["arguments"] + if arguments and arguments.strip(): + try: + json.loads(arguments) + except json.JSONDecodeError: + has_truncated_tool_args = True + mock_tool_calls.append(SimpleNamespace( + id=tc["id"], + type=tc["type"], + extra_content=tc.get("extra_content"), + function=SimpleNamespace( + name=tc["function"]["name"], + arguments=arguments, + ), + )) + + effective_finish_reason = finish_reason or "stop" + if has_truncated_tool_args: + effective_finish_reason = "length" + + full_reasoning = "".join(reasoning_parts) or None + mock_message = SimpleNamespace( + role=role, + content=full_content, + tool_calls=mock_tool_calls, + reasoning_content=full_reasoning, + ) + mock_choice = SimpleNamespace( + index=0, + message=mock_message, + finish_reason=effective_finish_reason, + ) + return SimpleNamespace( + id="stream-" + str(uuid.uuid4()), + model=model_name, + choices=[mock_choice], + usage=usage_obj, + ) + + def _call_anthropic(): + """Stream an Anthropic Messages API response. + + Fires delta callbacks for real-time token delivery, but returns + the native Anthropic Message object from get_final_message() so + the rest of the agent loop (validation, tool extraction, etc.) + works unchanged. + """ + has_tool_use = False + + # Reset stale-stream timer for this attempt + last_chunk_time["t"] = time.time() + # Use the Anthropic SDK's streaming context manager + with self._anthropic_client.messages.stream(**api_kwargs) as stream: + for event in stream: + # Update stale-stream timer on every event so the + # outer poll loop knows data is flowing. Without + # this, the detector kills healthy long-running + # Opus streams after 180 s even when events are + # actively arriving (the chat_completions path + # already does this at the top of its chunk loop). + last_chunk_time["t"] = time.time() + self._touch_activity("receiving stream response") + + if self._interrupt_requested: + break + + event_type = getattr(event, "type", None) + + if event_type == "content_block_start": + block = getattr(event, "content_block", None) + if block and getattr(block, "type", None) == "tool_use": + has_tool_use = True + tool_name = getattr(block, "name", None) + if tool_name: + _fire_first_delta() + self._fire_tool_gen_started(tool_name) + + elif event_type == "content_block_delta": + delta = getattr(event, "delta", None) + if delta: + delta_type = getattr(delta, "type", None) + if delta_type == "text_delta": + text = getattr(delta, "text", "") + if text and not has_tool_use: + _fire_first_delta() + self._fire_stream_delta(text) + deltas_were_sent["yes"] = True + elif delta_type == "thinking_delta": + thinking_text = getattr(delta, "thinking", "") + if thinking_text: + _fire_first_delta() + self._fire_reasoning_delta(thinking_text) + + # Return the native Anthropic Message for downstream processing + return stream.get_final_message() + + def _call(): + import httpx as _httpx + + _max_stream_retries = int(os.getenv("HERMES_STREAM_RETRIES", 2)) + + try: + for _stream_attempt in range(_max_stream_retries + 1): + try: + if self.api_mode == "anthropic_messages": + self._try_refresh_anthropic_client_credentials() + result["response"] = _call_anthropic() + else: + result["response"] = _call_chat_completions() + return # success + except Exception as e: + if deltas_were_sent["yes"]: + # Streaming failed AFTER some tokens were already + # delivered. Don't retry or fall back — partial + # content already reached the user. + logger.warning( + "Streaming failed after partial delivery, not retrying: %s", e + ) + result["error"] = e + return + + _is_timeout = isinstance( + e, (_httpx.ReadTimeout, _httpx.ConnectTimeout, _httpx.PoolTimeout) + ) + _is_conn_err = isinstance( + e, (_httpx.ConnectError, _httpx.RemoteProtocolError, ConnectionError) + ) + + # SSE error events from proxies (e.g. OpenRouter sends + # {"error":{"message":"Network connection lost."}}) are + # raised as APIError by the OpenAI SDK. These are + # semantically identical to httpx connection drops — + # the upstream stream died — and should be retried with + # a fresh connection. Distinguish from HTTP errors: + # APIError from SSE has no status_code, while + # APIStatusError (4xx/5xx) always has one. + _is_sse_conn_err = False + if not _is_timeout and not _is_conn_err: + from openai import APIError as _APIError + if isinstance(e, _APIError) and not getattr(e, "status_code", None): + _err_lower_sse = str(e).lower() + _SSE_CONN_PHRASES = ( + "connection lost", + "connection reset", + "connection closed", + "connection terminated", + "network error", + "network connection", + "terminated", + "peer closed", + "broken pipe", + "upstream connect error", + ) + _is_sse_conn_err = any( + phrase in _err_lower_sse + for phrase in _SSE_CONN_PHRASES + ) + + if _is_timeout or _is_conn_err or _is_sse_conn_err: + # Transient network / timeout error. Retry the + # streaming request with a fresh connection first. + if _stream_attempt < _max_stream_retries: + logger.info( + "Streaming attempt %s/%s failed (%s: %s), " + "retrying with fresh connection...", + _stream_attempt + 1, + _max_stream_retries + 1, + type(e).__name__, + e, + ) + self._emit_status( + f"⚠️ Connection to provider dropped " + f"({type(e).__name__}). Reconnecting… " + f"(attempt {_stream_attempt + 2}/{_max_stream_retries + 1})" + ) + self._touch_activity( + f"stream retry {_stream_attempt + 2}/{_max_stream_retries + 1} " + f"after {type(e).__name__}" + ) + # Close the stale request client before retry + stale = request_client_holder.get("client") + if stale is not None: + self._close_request_openai_client( + stale, reason="stream_retry_cleanup" + ) + request_client_holder["client"] = None + # Also rebuild the primary client to purge + # any dead connections from the pool. + try: + self._replace_primary_openai_client( + reason="stream_retry_pool_cleanup" + ) + except Exception: + pass + continue + self._emit_status( + "❌ Connection to provider failed after " + f"{_max_stream_retries + 1} attempts. " + "The provider may be experiencing issues — " + "try again in a moment." + ) + logger.warning( + "Streaming exhausted %s retries on transient error: %s", + _max_stream_retries + 1, + e, + ) + else: + _err_lower = str(e).lower() + _is_stream_unsupported = ( + "stream" in _err_lower + and "not supported" in _err_lower + ) + if _is_stream_unsupported: + self._disable_streaming = True + self._safe_print( + "\n⚠ Streaming is not supported for this " + "model/provider. Switching to non-streaming.\n" + " To avoid this delay, set display.streaming: false " + "in config.yaml\n" + ) + logger.info( + "Streaming failed before delivery: %s", + e, + ) + + # Propagate the error to the main retry loop instead of + # falling back to non-streaming inline. The main loop has + # richer recovery: credential rotation, provider fallback, + # backoff, and — for "stream not supported" — will switch + # to non-streaming on the next attempt via _disable_streaming. + result["error"] = e + return + finally: + request_client = request_client_holder.get("client") + if request_client is not None: + self._close_request_openai_client(request_client, reason="stream_request_complete") + + _stream_stale_timeout_base = float(os.getenv("HERMES_STREAM_STALE_TIMEOUT", 180.0)) + # Local providers (Ollama, oMLX, llama-cpp) can take 300+ seconds + # for prefill on large contexts. Disable the stale detector unless + # the user explicitly set HERMES_STREAM_STALE_TIMEOUT. + if _stream_stale_timeout_base == 180.0 and self.base_url and is_local_endpoint(self.base_url): + _stream_stale_timeout = float("inf") + logger.debug("Local provider detected (%s) — stale stream timeout disabled", self.base_url) + else: + # Scale the stale timeout for large contexts: slow models (like Opus) + # can legitimately think for minutes before producing the first token + # when the context is large. Without this, the stale detector kills + # healthy connections during the model's thinking phase, producing + # spurious RemoteProtocolError ("peer closed connection"). + _est_tokens = sum(len(str(v)) for v in api_kwargs.get("messages", [])) // 4 + if _est_tokens > 100_000: + _stream_stale_timeout = max(_stream_stale_timeout_base, 300.0) + elif _est_tokens > 50_000: + _stream_stale_timeout = max(_stream_stale_timeout_base, 240.0) + else: + _stream_stale_timeout = _stream_stale_timeout_base + + t = threading.Thread(target=_call, daemon=True) + t.start() + while t.is_alive(): + t.join(timeout=0.3) + + # Detect stale streams: connections kept alive by SSE pings + # but delivering no real chunks. Kill the client so the + # inner retry loop can start a fresh connection. + _stale_elapsed = time.time() - last_chunk_time["t"] + if _stale_elapsed > _stream_stale_timeout: + _est_ctx = sum(len(str(v)) for v in api_kwargs.get("messages", [])) // 4 + logger.warning( + "Stream stale for %.0fs (threshold %.0fs) — no chunks received. " + "model=%s context=~%s tokens. Killing connection.", + _stale_elapsed, _stream_stale_timeout, + api_kwargs.get("model", "unknown"), f"{_est_ctx:,}", + ) + self._emit_status( + f"⚠️ No response from provider for {int(_stale_elapsed)}s " + f"(model: {api_kwargs.get('model', 'unknown')}, " + f"context: ~{_est_ctx:,} tokens). " + f"Reconnecting..." + ) + try: + rc = request_client_holder.get("client") + if rc is not None: + self._close_request_openai_client(rc, reason="stale_stream_kill") + except Exception: + pass + # Rebuild the primary client too — its connection pool + # may hold dead sockets from the same provider outage. + try: + self._replace_primary_openai_client(reason="stale_stream_pool_cleanup") + except Exception: + pass + # Reset the timer so we don't kill repeatedly while + # the inner thread processes the closure. + last_chunk_time["t"] = time.time() + self._touch_activity( + f"stale stream detected after {int(_stale_elapsed)}s, reconnecting" + ) + + if self._interrupt_requested: + try: + if self.api_mode == "anthropic_messages": + from agent.anthropic_adapter import build_anthropic_client + + self._anthropic_client.close() + self._anthropic_client = build_anthropic_client( + self._anthropic_api_key, + getattr(self, "_anthropic_base_url", None), + ) + else: + request_client = request_client_holder.get("client") + if request_client is not None: + self._close_request_openai_client(request_client, reason="stream_interrupt_abort") + except Exception: + pass + raise InterruptedError("Agent interrupted during streaming API call") + if result["error"] is not None: + if deltas_were_sent["yes"]: + # Streaming failed AFTER some tokens were already delivered to + # the platform. Re-raising would let the outer retry loop make + # a new API call, creating a duplicate message. Return a + # partial "stop" response instead so the outer loop treats this + # turn as complete (no retry, no fallback). + # Recover whatever content was already streamed to the user. + # _current_streamed_assistant_text accumulates text fired + # through _fire_stream_delta, so it has exactly what the + # user saw before the connection died. + _partial_text = ( + getattr(self, "_current_streamed_assistant_text", "") or "" + ).strip() or None + logger.warning( + "Partial stream delivered before error; returning stub " + "response with %s chars of recovered content to prevent " + "duplicate messages: %s", + len(_partial_text or ""), + result["error"], + ) + _stub_msg = SimpleNamespace( + role="assistant", content=_partial_text, tool_calls=None, + reasoning_content=None, + ) + return SimpleNamespace( + id="partial-stream-stub", + model=getattr(self, "model", "unknown"), + choices=[SimpleNamespace( + index=0, message=_stub_msg, finish_reason="stop", + )], + usage=None, + ) + raise result["error"] + return result["response"] + + # ── Provider fallback ────────────────────────────────────────────────── + + def _try_activate_fallback(self) -> bool: + """Switch to the next fallback model/provider in the chain. + + Called when the current model is failing after retries. Swaps the + OpenAI client, model slug, and provider in-place so the retry loop + can continue with the new backend. Advances through the chain on + each call; returns False when exhausted. + + Uses the centralized provider router (resolve_provider_client) for + auth resolution and client construction — no duplicated provider→key + mappings. + """ + if self._fallback_index >= len(self._fallback_chain): + return False + + fb = self._fallback_chain[self._fallback_index] + self._fallback_index += 1 + fb_provider = (fb.get("provider") or "").strip().lower() + fb_model = (fb.get("model") or "").strip() + if not fb_provider or not fb_model: + return self._try_activate_fallback() # skip invalid, try next + + # Use centralized router for client construction. + # raw_codex=True because the main agent needs direct responses.stream() + # access for Codex providers. + try: + from agent.auxiliary_client import resolve_provider_client + # Pass base_url and api_key from fallback config so custom + # endpoints (e.g. Ollama Cloud) resolve correctly instead of + # falling through to OpenRouter defaults. + fb_base_url_hint = (fb.get("base_url") or "").strip() or None + fb_api_key_hint = (fb.get("api_key") or "").strip() or None + # For Ollama Cloud endpoints, pull OLLAMA_API_KEY from env + # when no explicit key is in the fallback config. + if fb_base_url_hint and "ollama.com" in fb_base_url_hint.lower() and not fb_api_key_hint: + fb_api_key_hint = os.getenv("OLLAMA_API_KEY") or None + fb_client, _resolved_fb_model = resolve_provider_client( + fb_provider, model=fb_model, raw_codex=True, + explicit_base_url=fb_base_url_hint, + explicit_api_key=fb_api_key_hint) + if fb_client is None: + logging.warning( + "Fallback to %s failed: provider not configured", + fb_provider) + return self._try_activate_fallback() # try next in chain + try: + from hermes_cli.model_normalize import normalize_model_for_provider + + fb_model = normalize_model_for_provider(fb_model, fb_provider) + except Exception: + pass + + # Determine api_mode from provider / base URL / model + fb_api_mode = "chat_completions" + fb_base_url = str(fb_client.base_url) + if fb_provider == "openai-codex": + fb_api_mode = "codex_responses" + elif fb_provider == "anthropic" or fb_base_url.rstrip("/").lower().endswith("/anthropic"): + fb_api_mode = "anthropic_messages" + elif self._is_direct_openai_url(fb_base_url): + fb_api_mode = "codex_responses" + elif self._model_requires_responses_api(fb_model): + # GPT-5.x models need Responses API on every provider + # (OpenRouter, Copilot, direct OpenAI, etc.) + fb_api_mode = "codex_responses" + + old_model = self.model + self.model = fb_model + self.provider = fb_provider + self.base_url = fb_base_url + self.api_mode = fb_api_mode + self._fallback_activated = True + + if fb_api_mode == "anthropic_messages": + # Build native Anthropic client instead of using OpenAI client + from agent.anthropic_adapter import build_anthropic_client, resolve_anthropic_token, _is_oauth_token + effective_key = (fb_client.api_key or resolve_anthropic_token() or "") if fb_provider == "anthropic" else (fb_client.api_key or "") + self.api_key = effective_key + self._anthropic_api_key = effective_key + self._anthropic_base_url = fb_base_url + self._anthropic_client = build_anthropic_client(effective_key, self._anthropic_base_url) + self._is_anthropic_oauth = _is_oauth_token(effective_key) + self.client = None + self._client_kwargs = {} + else: + # Swap OpenAI client and config in-place + self.api_key = fb_client.api_key + self.client = fb_client + # Preserve provider-specific headers that + # resolve_provider_client() may have baked into + # fb_client via the default_headers kwarg. The OpenAI + # SDK stores these in _custom_headers. Without this, + # subsequent request-client rebuilds (via + # _create_request_openai_client) drop the headers, + # causing 403s from providers like Kimi Coding that + # require a User-Agent sentinel. + fb_headers = getattr(fb_client, "_custom_headers", None) + if not fb_headers: + fb_headers = getattr(fb_client, "default_headers", None) + self._client_kwargs = { + "api_key": fb_client.api_key, + "base_url": fb_base_url, + **({"default_headers": dict(fb_headers)} if fb_headers else {}), + } + + # Re-evaluate prompt caching for the new provider/model + is_native_anthropic = fb_api_mode == "anthropic_messages" and fb_provider == "anthropic" + self._use_prompt_caching = ( + ("openrouter" in fb_base_url.lower() and "claude" in fb_model.lower()) + or is_native_anthropic + ) + + # Update context compressor limits for the fallback model. + # Without this, compression decisions use the primary model's + # context window (e.g. 200K) instead of the fallback's (e.g. 32K), + # causing oversized sessions to overflow the fallback. + if hasattr(self, 'context_compressor') and self.context_compressor: + from agent.model_metadata import get_model_context_length + fb_context_length = get_model_context_length( + self.model, base_url=self.base_url, + api_key=self.api_key, provider=self.provider, + ) + self.context_compressor.update_model( + model=self.model, + context_length=fb_context_length, + base_url=self.base_url, + api_key=getattr(self, "api_key", ""), + provider=self.provider, + ) + + self._emit_status( + f"🔄 Primary model failed — switching to fallback: " + f"{fb_model} via {fb_provider}" + ) + logging.info( + "Fallback activated: %s → %s (%s)", + old_model, fb_model, fb_provider, + ) + return True + except Exception as e: + logging.error("Failed to activate fallback %s: %s", fb_model, e) + return self._try_activate_fallback() # try next in chain + + # ── Per-turn primary restoration ───────────────────────────────────── + + def _restore_primary_runtime(self) -> bool: + """Restore the primary runtime at the start of a new turn. + + In long-lived CLI sessions a single AIAgent instance spans multiple + turns. Without restoration, one transient failure pins the session + to the fallback provider for every subsequent turn. Calling this at + the top of ``run_conversation()`` makes fallback turn-scoped. + + The gateway caches agents across messages (``_agent_cache`` in + ``gateway/run.py``), so this restoration IS needed there too. + """ + if not self._fallback_activated: + return False + + rt = self._primary_runtime + try: + # ── Core runtime state ── + self.model = rt["model"] + self.provider = rt["provider"] + self.base_url = rt["base_url"] # setter updates _base_url_lower + self.api_mode = rt["api_mode"] + self.api_key = rt["api_key"] + self._client_kwargs = dict(rt["client_kwargs"]) + self._use_prompt_caching = rt["use_prompt_caching"] + + # ── Rebuild client for the primary provider ── + if self.api_mode == "anthropic_messages": + from agent.anthropic_adapter import build_anthropic_client + self._anthropic_api_key = rt["anthropic_api_key"] + self._anthropic_base_url = rt["anthropic_base_url"] + self._anthropic_client = build_anthropic_client( + rt["anthropic_api_key"], rt["anthropic_base_url"], + ) + self._is_anthropic_oauth = rt["is_anthropic_oauth"] + self.client = None + else: + self.client = self._create_openai_client( + dict(rt["client_kwargs"]), + reason="restore_primary", + shared=True, + ) + + # ── Restore context engine state ── + cc = self.context_compressor + cc.update_model( + model=rt["compressor_model"], + context_length=rt["compressor_context_length"], + base_url=rt["compressor_base_url"], + api_key=rt["compressor_api_key"], + provider=rt["compressor_provider"], + ) + + # ── Reset fallback chain for the new turn ── + self._fallback_activated = False + self._fallback_index = 0 + + logging.info( + "Primary runtime restored for new turn: %s (%s)", + self.model, self.provider, + ) + return True + except Exception as e: + logging.warning("Failed to restore primary runtime: %s", e) + return False + + # Which error types indicate a transient transport failure worth + # one more attempt with a rebuilt client / connection pool. + _TRANSIENT_TRANSPORT_ERRORS = frozenset({ + "ReadTimeout", "ConnectTimeout", "PoolTimeout", + "ConnectError", "RemoteProtocolError", + "APIConnectionError", "APITimeoutError", + }) + + def _try_recover_primary_transport( + self, api_error: Exception, *, retry_count: int, max_retries: int, + ) -> bool: + """Attempt one extra primary-provider recovery cycle for transient transport failures. + + After ``max_retries`` exhaust, rebuild the primary client (clearing + stale connection pools) and give it one more attempt before falling + back. This is most useful for direct endpoints (custom, Z.AI, + Anthropic, OpenAI, local models) where a TCP-level hiccup does not + mean the provider is down. + + Skipped for proxy/aggregator providers (OpenRouter, Nous) which + already manage connection pools and retries server-side — if our + retries through them are exhausted, one more rebuilt client won't help. + """ + if self._fallback_activated: + return False + + # Only for transient transport errors + error_type = type(api_error).__name__ + if error_type not in self._TRANSIENT_TRANSPORT_ERRORS: + return False + + # Skip for aggregator providers — they manage their own retry infra + if self._is_openrouter_url(): + return False + provider_lower = (self.provider or "").strip().lower() + if provider_lower in ("nous", "nous-research"): + return False + + try: + # Close existing client to release stale connections + if getattr(self, "client", None) is not None: + try: + self._close_openai_client( + self.client, reason="primary_recovery", shared=True, + ) + except Exception: + pass + + # Rebuild from primary snapshot + rt = self._primary_runtime + self._client_kwargs = dict(rt["client_kwargs"]) + self.model = rt["model"] + self.provider = rt["provider"] + self.base_url = rt["base_url"] + self.api_mode = rt["api_mode"] + self.api_key = rt["api_key"] + + if self.api_mode == "anthropic_messages": + from agent.anthropic_adapter import build_anthropic_client + self._anthropic_api_key = rt["anthropic_api_key"] + self._anthropic_base_url = rt["anthropic_base_url"] + self._anthropic_client = build_anthropic_client( + rt["anthropic_api_key"], rt["anthropic_base_url"], + ) + self._is_anthropic_oauth = rt["is_anthropic_oauth"] + self.client = None + else: + self.client = self._create_openai_client( + dict(rt["client_kwargs"]), + reason="primary_recovery", + shared=True, + ) + + wait_time = min(3 + retry_count, 8) + self._vprint( + f"{self.log_prefix}🔁 Transient {error_type} on {self.provider} — " + f"rebuilt client, waiting {wait_time}s before one last primary attempt.", + force=True, + ) + time.sleep(wait_time) + return True + except Exception as e: + logging.warning("Primary transport recovery failed: %s", e) + return False + + # ── End provider fallback ────────────────────────────────────────────── + + @staticmethod + def _content_has_image_parts(content: Any) -> bool: + if not isinstance(content, list): + return False + for part in content: + if isinstance(part, dict) and part.get("type") in {"image_url", "input_image"}: + return True + return False + + @staticmethod + def _materialize_data_url_for_vision(image_url: str) -> tuple[str, Optional[Path]]: + header, _, data = str(image_url or "").partition(",") + mime = "image/jpeg" + if header.startswith("data:"): + mime_part = header[len("data:"):].split(";", 1)[0].strip() + if mime_part.startswith("image/"): + mime = mime_part + suffix = { + "image/png": ".png", + "image/gif": ".gif", + "image/webp": ".webp", + "image/jpeg": ".jpg", + "image/jpg": ".jpg", + }.get(mime, ".jpg") + tmp = tempfile.NamedTemporaryFile(prefix="anthropic_image_", suffix=suffix, delete=False) + with tmp: + tmp.write(base64.b64decode(data)) + path = Path(tmp.name) + return str(path), path + + def _describe_image_for_anthropic_fallback(self, image_url: str, role: str) -> str: + cache_key = hashlib.sha256(str(image_url or "").encode("utf-8")).hexdigest() + cached = self._anthropic_image_fallback_cache.get(cache_key) + if cached: + return cached + + role_label = { + "assistant": "assistant", + "tool": "tool result", + }.get(role, "user") + analysis_prompt = ( + "Describe everything visible in this image in thorough detail. " + "Include any text, code, UI, data, objects, people, layout, colors, " + "and any other notable visual information." + ) + + vision_source = str(image_url or "") + cleanup_path: Optional[Path] = None + if vision_source.startswith("data:"): + vision_source, cleanup_path = self._materialize_data_url_for_vision(vision_source) + + description = "" + try: + from tools.vision_tools import vision_analyze_tool + + result_json = asyncio.run( + vision_analyze_tool(image_url=vision_source, user_prompt=analysis_prompt) + ) + result = json.loads(result_json) if isinstance(result_json, str) else {} + description = (result.get("analysis") or "").strip() + except Exception as e: + description = f"Image analysis failed: {e}" + finally: + if cleanup_path and cleanup_path.exists(): + try: + cleanup_path.unlink() + except OSError: + pass + + if not description: + description = "Image analysis failed." + + note = f"[The {role_label} attached an image. Here's what it contains:\n{description}]" + if vision_source and not str(image_url or "").startswith("data:"): + note += ( + f"\n[If you need a closer look, use vision_analyze with image_url: {vision_source}]" + ) + + self._anthropic_image_fallback_cache[cache_key] = note + return note + + def _preprocess_anthropic_content(self, content: Any, role: str) -> Any: + if not self._content_has_image_parts(content): + return content + + text_parts: List[str] = [] + image_notes: List[str] = [] + for part in content: + if isinstance(part, str): + if part.strip(): + text_parts.append(part.strip()) + continue + if not isinstance(part, dict): + continue + + ptype = part.get("type") + if ptype in {"text", "input_text"}: + text = str(part.get("text", "") or "").strip() + if text: + text_parts.append(text) + continue + + if ptype in {"image_url", "input_image"}: + image_data = part.get("image_url", {}) + image_url = image_data.get("url", "") if isinstance(image_data, dict) else str(image_data or "") + if image_url: + image_notes.append(self._describe_image_for_anthropic_fallback(image_url, role)) + else: + image_notes.append("[An image was attached but no image source was available.]") + continue + + text = str(part.get("text", "") or "").strip() + if text: + text_parts.append(text) + + prefix = "\n\n".join(note for note in image_notes if note).strip() + suffix = "\n".join(text for text in text_parts if text).strip() + if prefix and suffix: + return f"{prefix}\n\n{suffix}" + if prefix: + return prefix + if suffix: + return suffix + return "[A multimodal message was converted to text for Anthropic compatibility.]" + + def _prepare_anthropic_messages_for_api(self, api_messages: list) -> list: + if not any( + isinstance(msg, dict) and self._content_has_image_parts(msg.get("content")) + for msg in api_messages + ): + return api_messages + + transformed = copy.deepcopy(api_messages) + for msg in transformed: + if not isinstance(msg, dict): + continue + msg["content"] = self._preprocess_anthropic_content( + msg.get("content"), + str(msg.get("role", "user") or "user"), + ) + return transformed + + def _anthropic_preserve_dots(self) -> bool: + """True when using an anthropic-compatible endpoint that preserves dots in model names. + Alibaba/DashScope keeps dots (e.g. qwen3.5-plus). + MiniMax keeps dots (e.g. MiniMax-M2.7). + OpenCode Go/Zen keeps dots for non-Claude models (e.g. minimax-m2.5-free). + ZAI/Zhipu keeps dots (e.g. glm-4.7, glm-5.1).""" + if (getattr(self, "provider", "") or "").lower() in {"alibaba", "minimax", "minimax-cn", "opencode-go", "opencode-zen", "zai"}: + return True + base = (getattr(self, "base_url", "") or "").lower() + return "dashscope" in base or "aliyuncs" in base or "minimax" in base or "opencode.ai/zen/" in base or "bigmodel.cn" in base + + def _is_qwen_portal(self) -> bool: + """Return True when the base URL targets Qwen Portal.""" + return "portal.qwen.ai" in self._base_url_lower + + def _qwen_prepare_chat_messages(self, api_messages: list) -> list: + prepared = copy.deepcopy(api_messages) + if not prepared: + return prepared + + for msg in prepared: + if not isinstance(msg, dict): + continue + content = msg.get("content") + if isinstance(content, str): + msg["content"] = [{"type": "text", "text": content}] + elif isinstance(content, list): + # Normalize: convert bare strings to text dicts, keep dicts as-is. + # deepcopy already created independent copies, no need for dict(). + normalized_parts = [] + for part in content: + if isinstance(part, str): + normalized_parts.append({"type": "text", "text": part}) + elif isinstance(part, dict): + normalized_parts.append(part) + if normalized_parts: + msg["content"] = normalized_parts + + # Inject cache_control on the last part of the system message. + for msg in prepared: + if isinstance(msg, dict) and msg.get("role") == "system": + content = msg.get("content") + if isinstance(content, list) and content and isinstance(content[-1], dict): + content[-1]["cache_control"] = {"type": "ephemeral"} + break + + return prepared + + def _qwen_prepare_chat_messages_inplace(self, messages: list) -> None: + """In-place variant — mutates an already-copied message list.""" + if not messages: + return + + for msg in messages: + if not isinstance(msg, dict): + continue + content = msg.get("content") + if isinstance(content, str): + msg["content"] = [{"type": "text", "text": content}] + elif isinstance(content, list): + normalized_parts = [] + for part in content: + if isinstance(part, str): + normalized_parts.append({"type": "text", "text": part}) + elif isinstance(part, dict): + normalized_parts.append(part) + if normalized_parts: + msg["content"] = normalized_parts + + for msg in messages: + if isinstance(msg, dict) and msg.get("role") == "system": + content = msg.get("content") + if isinstance(content, list) and content and isinstance(content[-1], dict): + content[-1]["cache_control"] = {"type": "ephemeral"} + break + + def _build_api_kwargs(self, api_messages: list) -> dict: + """Build the keyword arguments dict for the active API mode.""" + if self.api_mode == "anthropic_messages": + from agent.anthropic_adapter import build_anthropic_kwargs + anthropic_messages = self._prepare_anthropic_messages_for_api(api_messages) + # Pass context_length (total input+output window) so the adapter can + # clamp max_tokens (output cap) when the user configured a smaller + # context window than the model's native output limit. + ctx_len = getattr(self, "context_compressor", None) + ctx_len = ctx_len.context_length if ctx_len else None + # _ephemeral_max_output_tokens is set for one call when the API + # returns "max_tokens too large given prompt" — it caps output to + # the available window space without touching context_length. + ephemeral_out = getattr(self, "_ephemeral_max_output_tokens", None) + if ephemeral_out is not None: + self._ephemeral_max_output_tokens = None # consume immediately + return build_anthropic_kwargs( + model=self.model, + messages=anthropic_messages, + tools=self.tools, + max_tokens=ephemeral_out if ephemeral_out is not None else self.max_tokens, + reasoning_config=self.reasoning_config, + is_oauth=self._is_anthropic_oauth, + preserve_dots=self._anthropic_preserve_dots(), + context_length=ctx_len, + base_url=getattr(self, "_anthropic_base_url", None), + fast_mode=(self.request_overrides or {}).get("speed") == "fast", + ) + + if self.api_mode == "codex_responses": + instructions = "" + payload_messages = api_messages + if api_messages and api_messages[0].get("role") == "system": + instructions = str(api_messages[0].get("content") or "").strip() + payload_messages = api_messages[1:] + if not instructions: + instructions = DEFAULT_AGENT_IDENTITY + + is_github_responses = ( + "models.github.ai" in self.base_url.lower() + or "api.githubcopilot.com" in self.base_url.lower() + ) + is_codex_backend = ( + self.provider == "openai-codex" + or "chatgpt.com/backend-api/codex" in self.base_url.lower() + ) + + # Resolve reasoning effort: config > default (medium) + reasoning_effort = "medium" + reasoning_enabled = True + if self.reasoning_config and isinstance(self.reasoning_config, dict): + if self.reasoning_config.get("enabled") is False: + reasoning_enabled = False + elif self.reasoning_config.get("effort"): + reasoning_effort = self.reasoning_config["effort"] + + # Clamp effort levels not supported by the Responses API model. + # GPT-5.4 supports none/low/medium/high/xhigh but not "minimal". + # "minimal" is valid on OpenRouter and GPT-5 but fails on 5.2/5.4. + _effort_clamp = {"minimal": "low"} + reasoning_effort = _effort_clamp.get(reasoning_effort, reasoning_effort) + + kwargs = { + "model": self.model, + "instructions": instructions, + "input": self._chat_messages_to_responses_input(payload_messages), + "tools": self._responses_tools(), + "tool_choice": "auto", + "parallel_tool_calls": True, + "store": False, + } + + if not is_github_responses: + kwargs["prompt_cache_key"] = self.session_id + + if reasoning_enabled: + if is_github_responses: + # Copilot's Responses route advertises reasoning-effort support, + # but not OpenAI-specific prompt cache or encrypted reasoning + # fields. Keep the payload to the documented subset. + github_reasoning = self._github_models_reasoning_extra_body() + if github_reasoning is not None: + kwargs["reasoning"] = github_reasoning + else: + kwargs["reasoning"] = {"effort": reasoning_effort, "summary": "auto"} + kwargs["include"] = ["reasoning.encrypted_content"] + elif not is_github_responses: + kwargs["include"] = [] + + if self.request_overrides: + kwargs.update(self.request_overrides) + + if self.max_tokens is not None and not is_codex_backend: + kwargs["max_output_tokens"] = self.max_tokens + + return kwargs + + sanitized_messages = api_messages + needs_sanitization = False + for msg in api_messages: + if not isinstance(msg, dict): + continue + if "codex_reasoning_items" in msg: + needs_sanitization = True + break + + tool_calls = msg.get("tool_calls") + if isinstance(tool_calls, list): + for tool_call in tool_calls: + if not isinstance(tool_call, dict): + continue + if "call_id" in tool_call or "response_item_id" in tool_call: + needs_sanitization = True + break + if needs_sanitization: + break + + if needs_sanitization: + sanitized_messages = copy.deepcopy(api_messages) + for msg in sanitized_messages: + if not isinstance(msg, dict): + continue + + # Codex-only replay state must not leak into strict chat-completions APIs. + msg.pop("codex_reasoning_items", None) + + tool_calls = msg.get("tool_calls") + if isinstance(tool_calls, list): + for tool_call in tool_calls: + if isinstance(tool_call, dict): + tool_call.pop("call_id", None) + tool_call.pop("response_item_id", None) + + # Qwen portal: normalize content to list-of-dicts, inject cache_control. + # Must run AFTER codex sanitization so we transform the final messages. + # If sanitization already deepcopied, reuse that copy (in-place). + if self._is_qwen_portal(): + if sanitized_messages is api_messages: + # No sanitization was done — we need our own copy. + sanitized_messages = self._qwen_prepare_chat_messages(sanitized_messages) + else: + # Already a deepcopy — transform in place to avoid a second deepcopy. + self._qwen_prepare_chat_messages_inplace(sanitized_messages) + + # GPT-5 and Codex models respond better to 'developer' than 'system' + # for instruction-following. Swap the role at the API boundary so + # internal message representation stays uniform ("system"). + _model_lower = (self.model or "").lower() + if ( + sanitized_messages + and sanitized_messages[0].get("role") == "system" + and any(p in _model_lower for p in DEVELOPER_ROLE_MODELS) + ): + # Shallow-copy the list + first message only — rest stays shared. + sanitized_messages = list(sanitized_messages) + sanitized_messages[0] = {**sanitized_messages[0], "role": "developer"} + + provider_preferences = {} + if self.providers_allowed: + provider_preferences["only"] = self.providers_allowed + if self.providers_ignored: + provider_preferences["ignore"] = self.providers_ignored + if self.providers_order: + provider_preferences["order"] = self.providers_order + if self.provider_sort: + provider_preferences["sort"] = self.provider_sort + if self.provider_require_parameters: + provider_preferences["require_parameters"] = True + if self.provider_data_collection: + provider_preferences["data_collection"] = self.provider_data_collection + + api_kwargs = { + "model": self.model, + "messages": sanitized_messages, + "timeout": float(os.getenv("HERMES_API_TIMEOUT", 1800.0)), + } + if self._is_qwen_portal(): + api_kwargs["metadata"] = { + "sessionId": self.session_id or "hermes", + "promptId": str(uuid.uuid4()), + } + if self.tools: + api_kwargs["tools"] = self.tools + + if self.max_tokens is not None: + api_kwargs.update(self._max_tokens_param(self.max_tokens)) + elif self._is_qwen_portal(): + # Qwen Portal defaults to a very low max_tokens when omitted. + # Reasoning models (qwen3-coder-plus) exhaust that budget on + # thinking tokens alone, causing the portal to return + # finish_reason="stop" with truncated output — the agent sees + # this as an intentional stop and exits the loop. Send 65536 + # (the documented max output for qwen3-coder models) so the + # model has adequate output budget for tool calls. + api_kwargs.update(self._max_tokens_param(65536)) + elif (self._is_openrouter_url() or "nousresearch" in self._base_url_lower) and "claude" in (self.model or "").lower(): + # OpenRouter and Nous Portal translate requests to Anthropic's + # Messages API, which requires max_tokens as a mandatory field. + # When we omit it, the proxy picks a default that can be too + # low — the model spends its output budget on thinking and has + # almost nothing left for the actual response (especially large + # tool calls like write_file). Sending the model's real output + # limit ensures full capacity. + try: + from agent.anthropic_adapter import _get_anthropic_max_output + _model_output_limit = _get_anthropic_max_output(self.model) + api_kwargs["max_tokens"] = _model_output_limit + except Exception: + pass # fail open — let the proxy pick its default + + extra_body = {} + + _is_openrouter = self._is_openrouter_url() + _is_github_models = ( + "models.github.ai" in self._base_url_lower + or "api.githubcopilot.com" in self._base_url_lower + ) + + # Provider preferences (only, ignore, order, sort) are OpenRouter- + # specific. Only send to OpenRouter-compatible endpoints. + # TODO: Nous Portal will add transparent proxy support — re-enable + # for _is_nous when their backend is updated. + if provider_preferences and _is_openrouter: + extra_body["provider"] = provider_preferences + _is_nous = "nousresearch" in self._base_url_lower + + if self._supports_reasoning_extra_body(): + if _is_github_models: + github_reasoning = self._github_models_reasoning_extra_body() + if github_reasoning is not None: + extra_body["reasoning"] = github_reasoning + else: + if self.reasoning_config is not None: + rc = dict(self.reasoning_config) + # Nous Portal requires reasoning enabled — don't send + # enabled=false to it (would cause 400). + if _is_nous and rc.get("enabled") is False: + pass # omit reasoning entirely for Nous when disabled + else: + extra_body["reasoning"] = rc + else: + extra_body["reasoning"] = { + "enabled": True, + "effort": "medium" + } + + # Nous Portal product attribution + if _is_nous: + extra_body["tags"] = ["product=hermes-agent"] + + # Ollama num_ctx: override the 2048 default so the model actually + # uses the context window it was trained for. Passed via the OpenAI + # SDK's extra_body → options.num_ctx, which Ollama's OpenAI-compat + # endpoint forwards to the runner as --ctx-size. + if self._ollama_num_ctx: + options = extra_body.get("options", {}) + options["num_ctx"] = self._ollama_num_ctx + extra_body["options"] = options + + if self._is_qwen_portal(): + extra_body["vl_high_resolution_images"] = True + + if extra_body: + api_kwargs["extra_body"] = extra_body + + # xAI prompt caching: send x-grok-conv-id header to route requests + # to the same server, maximizing automatic cache hits. + # https://docs.x.ai/developers/advanced-api-usage/prompt-caching + if "x.ai" in self._base_url_lower and hasattr(self, "session_id") and self.session_id: + api_kwargs["extra_headers"] = {"x-grok-conv-id": self.session_id} + + # Priority Processing / generic request overrides (e.g. service_tier). + # Applied last so overrides win over any defaults set above. + if self.request_overrides: + api_kwargs.update(self.request_overrides) + + return api_kwargs + + def _supports_reasoning_extra_body(self) -> bool: + """Return True when reasoning extra_body is safe to send for this route/model. + + OpenRouter forwards unknown extra_body fields to upstream providers. + Some providers/routes reject `reasoning` with 400s, so gate it to + known reasoning-capable model families and direct Nous Portal. + """ + if "nousresearch" in self._base_url_lower: + return True + if "ai-gateway.vercel.sh" in self._base_url_lower: + return True + if "models.github.ai" in self._base_url_lower or "api.githubcopilot.com" in self._base_url_lower: + try: + from hermes_cli.models import github_model_reasoning_efforts + + return bool(github_model_reasoning_efforts(self.model)) + except Exception: + return False + if "openrouter" not in self._base_url_lower: + return False + if "api.mistral.ai" in self._base_url_lower: + return False + + model = (self.model or "").lower() + reasoning_model_prefixes = ( + "deepseek/", + "anthropic/", + "openai/", + "x-ai/", + "google/gemini-2", + "qwen/qwen3", + ) + return any(model.startswith(prefix) for prefix in reasoning_model_prefixes) + + def _github_models_reasoning_extra_body(self) -> dict | None: + """Format reasoning payload for GitHub Models/OpenAI-compatible routes.""" + try: + from hermes_cli.models import github_model_reasoning_efforts + except Exception: + return None + + supported_efforts = github_model_reasoning_efforts(self.model) + if not supported_efforts: + return None + + if self.reasoning_config and isinstance(self.reasoning_config, dict): + if self.reasoning_config.get("enabled") is False: + return None + requested_effort = str( + self.reasoning_config.get("effort", "medium") + ).strip().lower() + else: + requested_effort = "medium" + + if requested_effort == "xhigh" and "high" in supported_efforts: + requested_effort = "high" + elif requested_effort not in supported_efforts: + if requested_effort == "minimal" and "low" in supported_efforts: + requested_effort = "low" + elif "medium" in supported_efforts: + requested_effort = "medium" + else: + requested_effort = supported_efforts[0] + + return {"effort": requested_effort} + + def _build_assistant_message(self, assistant_message, finish_reason: str) -> dict: + """Build a normalized assistant message dict from an API response message. + + Handles reasoning extraction, reasoning_details, and optional tool_calls + so both the tool-call path and the final-response path share one builder. + """ + reasoning_text = self._extract_reasoning(assistant_message) + _from_structured = bool(reasoning_text) + + # Fallback: extract inline blocks from content when no structured + # reasoning fields are present (some models/providers embed thinking + # directly in the content rather than returning separate API fields). + if not reasoning_text: + content = assistant_message.content or "" + think_blocks = re.findall(r'(.*?)', content, flags=re.DOTALL) + if think_blocks: + combined = "\n\n".join(b.strip() for b in think_blocks if b.strip()) + reasoning_text = combined or None + + if reasoning_text and self.verbose_logging: + logging.debug(f"Captured reasoning ({len(reasoning_text)} chars): {reasoning_text}") + + if reasoning_text and self.reasoning_callback: + # Skip callback when streaming is active — reasoning was already + # displayed during the stream via one of two paths: + # (a) _fire_reasoning_delta (structured reasoning_content deltas) + # (b) _stream_delta tag extraction (/) + # When streaming is NOT active, always fire so non-streaming modes + # (gateway, batch, quiet) still get reasoning. + # Any reasoning that wasn't shown during streaming is caught by the + # CLI post-response display fallback (cli.py _reasoning_shown_this_turn). + if not self.stream_delta_callback: + try: + self.reasoning_callback(reasoning_text) + except Exception: + pass + + msg = { + "role": "assistant", + "content": assistant_message.content or "", + "reasoning": reasoning_text, + "finish_reason": finish_reason, + } + + if hasattr(assistant_message, 'reasoning_details') and assistant_message.reasoning_details: + # Pass reasoning_details back unmodified so providers (OpenRouter, + # Anthropic, OpenAI) can maintain reasoning continuity across turns. + # Each provider may include opaque fields (signature, encrypted_content) + # that must be preserved exactly. + raw_details = assistant_message.reasoning_details + preserved = [] + for d in raw_details: + if isinstance(d, dict): + preserved.append(d) + elif hasattr(d, "__dict__"): + preserved.append(d.__dict__) + elif hasattr(d, "model_dump"): + preserved.append(d.model_dump()) + if preserved: + msg["reasoning_details"] = preserved + + # Codex Responses API: preserve encrypted reasoning items for + # multi-turn continuity. These get replayed as input on the next turn. + codex_items = getattr(assistant_message, "codex_reasoning_items", None) + if codex_items: + msg["codex_reasoning_items"] = codex_items + + if assistant_message.tool_calls: + tool_calls = [] + for tool_call in assistant_message.tool_calls: + raw_id = getattr(tool_call, "id", None) + call_id = getattr(tool_call, "call_id", None) + if not isinstance(call_id, str) or not call_id.strip(): + embedded_call_id, _ = self._split_responses_tool_id(raw_id) + call_id = embedded_call_id + if not isinstance(call_id, str) or not call_id.strip(): + if isinstance(raw_id, str) and raw_id.strip(): + call_id = raw_id.strip() + else: + _fn = getattr(tool_call, "function", None) + _fn_name = getattr(_fn, "name", "") if _fn else "" + _fn_args = getattr(_fn, "arguments", "{}") if _fn else "{}" + call_id = self._deterministic_call_id(_fn_name, _fn_args, len(tool_calls)) + call_id = call_id.strip() + + response_item_id = getattr(tool_call, "response_item_id", None) + if not isinstance(response_item_id, str) or not response_item_id.strip(): + _, embedded_response_item_id = self._split_responses_tool_id(raw_id) + response_item_id = embedded_response_item_id + + response_item_id = self._derive_responses_function_call_id( + call_id, + response_item_id if isinstance(response_item_id, str) else None, + ) + + tc_dict = { + "id": call_id, + "call_id": call_id, + "response_item_id": response_item_id, + "type": tool_call.type, + "function": { + "name": tool_call.function.name, + "arguments": tool_call.function.arguments + }, + } + # Preserve extra_content (e.g. Gemini thought_signature) so it + # is sent back on subsequent API calls. Without this, Gemini 3 + # thinking models reject the request with a 400 error. + extra = getattr(tool_call, "extra_content", None) + if extra is not None: + if hasattr(extra, "model_dump"): + extra = extra.model_dump() + tc_dict["extra_content"] = extra + tool_calls.append(tc_dict) + msg["tool_calls"] = tool_calls + + return msg + + @staticmethod + def _sanitize_tool_calls_for_strict_api(api_msg: dict) -> dict: + """Strip Codex Responses API fields from tool_calls for strict providers. + + Providers like Mistral, Fireworks, and other strict OpenAI-compatible APIs + validate the Chat Completions schema and reject unknown fields (call_id, + response_item_id) with 400 or 422 errors. These fields are preserved in + the internal message history — this method only modifies the outgoing + API copy. + + Creates new tool_call dicts rather than mutating in-place, so the + original messages list retains call_id/response_item_id for Codex + Responses API compatibility (e.g. if the session falls back to a + Codex provider later). + + Fields stripped: call_id, response_item_id + """ + tool_calls = api_msg.get("tool_calls") + if not isinstance(tool_calls, list): + return api_msg + _STRIP_KEYS = {"call_id", "response_item_id"} + api_msg["tool_calls"] = [ + {k: v for k, v in tc.items() if k not in _STRIP_KEYS} + if isinstance(tc, dict) else tc + for tc in tool_calls + ] + return api_msg + + def _should_sanitize_tool_calls(self) -> bool: + """Determine if tool_calls need sanitization for strict APIs. + + Codex Responses API uses fields like call_id and response_item_id + that are not part of the standard Chat Completions schema. These + fields must be stripped when calling any other API to avoid + validation errors (400 Bad Request). + + Returns: + bool: True if sanitization is needed (non-Codex API), False otherwise. + """ + return self.api_mode != "codex_responses" + + def flush_memories(self, messages: list = None, min_turns: int = None): + """Give the model one turn to persist memories before context is lost. + + Called before compression, session reset, or CLI exit. Injects a flush + message, makes one API call, executes any memory tool calls, then + strips all flush artifacts from the message list. + + Args: + messages: The current conversation messages. If None, uses + self._session_messages (last run_conversation state). + min_turns: Minimum user turns required to trigger the flush. + None = use config value (flush_min_turns). + 0 = always flush (used for compression). + """ + if self._memory_flush_min_turns == 0 and min_turns is None: + return + if "memory" not in self.valid_tool_names or not self._memory_store: + return + effective_min = min_turns if min_turns is not None else self._memory_flush_min_turns + if self._user_turn_count < effective_min: + return + + if messages is None: + messages = getattr(self, '_session_messages', None) + if not messages or len(messages) < 3: + return + + flush_content = ( + "[System: The session is being compressed. " + "Save anything worth remembering — prioritize user preferences, " + "corrections, and recurring patterns over task-specific details.]" + ) + _sentinel = f"__flush_{id(self)}_{time.monotonic()}" + flush_msg = {"role": "user", "content": flush_content, "_flush_sentinel": _sentinel} + messages.append(flush_msg) + + try: + # Build API messages for the flush call + _needs_sanitize = self._should_sanitize_tool_calls() + api_messages = [] + for msg in messages: + api_msg = msg.copy() + if msg.get("role") == "assistant": + reasoning = msg.get("reasoning") + if reasoning: + api_msg["reasoning_content"] = reasoning + api_msg.pop("reasoning", None) + api_msg.pop("finish_reason", None) + api_msg.pop("_flush_sentinel", None) + api_msg.pop("_thinking_prefill", None) + if _needs_sanitize: + self._sanitize_tool_calls_for_strict_api(api_msg) + api_messages.append(api_msg) + + if self._cached_system_prompt: + api_messages = [{"role": "system", "content": self._cached_system_prompt}] + api_messages + + # Make one API call with only the memory tool available + memory_tool_def = None + for t in (self.tools or []): + if t.get("function", {}).get("name") == "memory": + memory_tool_def = t + break + + if not memory_tool_def: + messages.pop() # remove flush msg + return + + # Use auxiliary client for the flush call when available -- + # it's cheaper and avoids Codex Responses API incompatibility. + from agent.auxiliary_client import call_llm as _call_llm + _aux_available = True + try: + response = _call_llm( + task="flush_memories", + messages=api_messages, + tools=[memory_tool_def], + temperature=0.3, + max_tokens=5120, + # timeout resolved from auxiliary.flush_memories.timeout config + ) + except RuntimeError: + _aux_available = False + response = None + + if not _aux_available and self.api_mode == "codex_responses": + # No auxiliary client -- use the Codex Responses path directly + codex_kwargs = self._build_api_kwargs(api_messages) + codex_kwargs["tools"] = self._responses_tools([memory_tool_def]) + codex_kwargs["temperature"] = 0.3 + if "max_output_tokens" in codex_kwargs: + codex_kwargs["max_output_tokens"] = 5120 + response = self._run_codex_stream(codex_kwargs) + elif not _aux_available and self.api_mode == "anthropic_messages": + # Native Anthropic — use the Anthropic client directly + from agent.anthropic_adapter import build_anthropic_kwargs as _build_ant_kwargs + ant_kwargs = _build_ant_kwargs( + model=self.model, messages=api_messages, + tools=[memory_tool_def], max_tokens=5120, + reasoning_config=None, + preserve_dots=self._anthropic_preserve_dots(), + ) + response = self._anthropic_messages_create(ant_kwargs) + elif not _aux_available: + api_kwargs = { + "model": self.model, + "messages": api_messages, + "tools": [memory_tool_def], + "temperature": 0.3, + **self._max_tokens_param(5120), + } + from agent.auxiliary_client import _get_task_timeout + response = self._ensure_primary_openai_client(reason="flush_memories").chat.completions.create( + **api_kwargs, timeout=_get_task_timeout("flush_memories") + ) + + # Extract tool calls from the response, handling all API formats + tool_calls = [] + if self.api_mode == "codex_responses" and not _aux_available: + assistant_msg, _ = self._normalize_codex_response(response) + if assistant_msg and assistant_msg.tool_calls: + tool_calls = assistant_msg.tool_calls + elif self.api_mode == "anthropic_messages" and not _aux_available: + from agent.anthropic_adapter import normalize_anthropic_response as _nar_flush + _flush_msg, _ = _nar_flush(response, strip_tool_prefix=self._is_anthropic_oauth) + if _flush_msg and _flush_msg.tool_calls: + tool_calls = _flush_msg.tool_calls + elif hasattr(response, "choices") and response.choices: + assistant_message = response.choices[0].message + if assistant_message.tool_calls: + tool_calls = assistant_message.tool_calls + + for tc in tool_calls: + if tc.function.name == "memory": + try: + args = json.loads(tc.function.arguments) + flush_target = args.get("target", "memory") + from tools.memory_tool import memory_tool as _memory_tool + _memory_tool( + action=args.get("action"), + target=flush_target, + content=args.get("content"), + old_text=args.get("old_text"), + store=self._memory_store, + ) + if not self.quiet_mode: + print(f" 🧠 Memory flush: saved to {args.get('target', 'memory')}") + except Exception as e: + logger.debug("Memory flush tool call failed: %s", e) + except Exception as e: + logger.debug("Memory flush API call failed: %s", e) + finally: + # Strip flush artifacts: remove everything from the flush message onward. + # Use sentinel marker instead of identity check for robustness. + while messages and messages[-1].get("_flush_sentinel") != _sentinel: + messages.pop() + if not messages: + break + if messages and messages[-1].get("_flush_sentinel") == _sentinel: + messages.pop() + + def _compress_context(self, messages: list, system_message: str, *, approx_tokens: int = None, task_id: str = "default", focus_topic: str = None) -> tuple: + """Compress conversation context and split the session in SQLite. + + Args: + focus_topic: Optional focus string for guided compression — the + summariser will prioritise preserving information related to + this topic. Inspired by Claude Code's ``/compact ``. + + Returns: + (compressed_messages, new_system_prompt) tuple + """ + _pre_msg_count = len(messages) + logger.info( + "context compression started: session=%s messages=%d tokens=~%s model=%s focus=%r", + self.session_id or "none", _pre_msg_count, + f"{approx_tokens:,}" if approx_tokens else "unknown", self.model, + focus_topic, + ) + # Pre-compression memory flush: let the model save memories before they're lost + self.flush_memories(messages, min_turns=0) + + # Notify external memory provider before compression discards context + if self._memory_manager: + try: + self._memory_manager.on_pre_compress(messages) + except Exception: + pass + + compressed = self.context_compressor.compress(messages, current_tokens=approx_tokens, focus_topic=focus_topic) + + todo_snapshot = self._todo_store.format_for_injection() + if todo_snapshot: + compressed.append({"role": "user", "content": todo_snapshot}) + + self._invalidate_system_prompt() + new_system_prompt = self._build_system_prompt(system_message) + self._cached_system_prompt = new_system_prompt + + if self._session_db: + try: + # ── MindOS NEXT 兼容 ────────────────────────────────────── + # 原 Hermes CLI 逻辑在压缩时会生成新的 session_id + # （20260417_HHMMSS_hash 格式），并用 parent_session_id 链接旧会话。 + # 但 MindOS NEXT 的 session_id 由前端生成（chat_xxx），前端不知道 + # 后端换了 ID，刷新后调 history API 会找不到后续消息。 + # + # 修复：压缩时 **不换 session_id**。只需要： + # 1. 删除旧消息（压缩后已无用） + # 2. 重置 flush cursor（让后续消息从头写入） + # 3. 更新系统提示 + # 这样前端的 chatId 始终有效，history API 能找到压缩后的消息。 + old_title = self._session_db.get_session_title(self.session_id) + + # 清除该 session 的所有旧消息（压缩摘要已在内存 messages[] 中） + try: + self._session_db._conn.execute( + "DELETE FROM messages WHERE session_id = ?", + (self.session_id,), + ) + self._session_db._conn.commit() + except Exception: + pass # non-fatal: worst case 有重复旧消息 + + # 重置 flush cursor — 压缩后的消息从头写入 + self._last_flushed_db_idx = 0 + + # 更新日志文件路径（仅 JSON 日志，不影响 DB） + self.session_log_file = self.logs_dir / f"session_{self.session_id}.json" + + self._session_db.update_system_prompt(self.session_id, new_system_prompt) + except Exception as e: + logger.warning("Session DB compression split failed — new session will NOT be indexed: %s", e) + + # Warn on repeated compressions (quality degrades with each pass) + _cc = self.context_compressor.compression_count + if _cc >= 2: + self._vprint( + f"{self.log_prefix}⚠️ Session compressed {_cc} times — " + f"accuracy may degrade. Consider /new to start fresh.", + force=True, + ) + + # Update token estimate after compaction so pressure calculations + # use the post-compression count, not the stale pre-compression one. + _compressed_est = ( + estimate_tokens_rough(new_system_prompt) + + estimate_messages_tokens_rough(compressed) + ) + self.context_compressor.last_prompt_tokens = _compressed_est + self.context_compressor.last_completion_tokens = 0 + + # Only reset the pressure warning if compression actually brought + # us below the warning level (85% of threshold). When compression + # can't reduce enough (e.g. threshold is very low, or system prompt + # alone exceeds the warning level), keep the tier set to prevent + # spamming the user with repeated warnings every loop iteration. + if self.context_compressor.threshold_tokens > 0: + _post_progress = _compressed_est / self.context_compressor.threshold_tokens + if _post_progress < 0.85: + self._context_pressure_warned_at = 0.0 + # Clear class-level dedup for this session so a fresh + # warning cycle can start if context grows again. + _sid = self.session_id or "default" + AIAgent._context_pressure_last_warned.pop(_sid, None) + + # Clear the file-read dedup cache. After compression the original + # read content is summarised away — if the model re-reads the same + # file it needs the full content, not a "file unchanged" stub. + try: + from tools.file_tools import reset_file_dedup + reset_file_dedup(task_id) + except Exception: + pass + + logger.info( + "context compression done: session=%s messages=%d->%d tokens=~%s", + self.session_id or "none", _pre_msg_count, len(compressed), + f"{_compressed_est:,}", + ) + return compressed, new_system_prompt + + def _execute_tool_calls(self, assistant_message, messages: list, effective_task_id: str, api_call_count: int = 0) -> None: + """Execute tool calls from the assistant message and append results to messages. + + Dispatches to concurrent execution only for batches that look + independent: read-only tools may always share the parallel path, while + file reads/writes may do so only when their target paths do not overlap. + """ + tool_calls = assistant_message.tool_calls + + # Allow _vprint during tool execution even with stream consumers + self._executing_tools = True + try: + if not _should_parallelize_tool_batch(tool_calls): + return self._execute_tool_calls_sequential( + assistant_message, messages, effective_task_id, api_call_count + ) + + return self._execute_tool_calls_concurrent( + assistant_message, messages, effective_task_id, api_call_count + ) + finally: + self._executing_tools = False + + def _invoke_tool(self, function_name: str, function_args: dict, effective_task_id: str, + tool_call_id: Optional[str] = None) -> str: + """Invoke a single tool and return the result string. No display logic. + + Handles both agent-level tools (todo, memory, etc.) and registry-dispatched + tools. Used by the concurrent execution path; the sequential path retains + its own inline invocation for backward-compatible display handling. + """ + # Check plugin hooks for a block directive before executing anything. + block_message: Optional[str] = None + try: + from hermes_cli.plugins import get_pre_tool_call_block_message + block_message = get_pre_tool_call_block_message( + function_name, function_args, task_id=effective_task_id or "", + ) + except Exception: + pass + if block_message is not None: + return json.dumps({"error": block_message}, ensure_ascii=False) + + if function_name == "todo": + from tools.todo_tool import todo_tool as _todo_tool + return _todo_tool( + todos=function_args.get("todos"), + merge=function_args.get("merge", False), + store=self._todo_store, + ) + elif function_name == "session_search": + if not self._session_db: + return json.dumps({"success": False, "error": "Session database not available."}) + from tools.session_search_tool import session_search as _session_search + return _session_search( + query=function_args.get("query", ""), + role_filter=function_args.get("role_filter"), + limit=function_args.get("limit", 3), + db=self._session_db, + current_session_id=self.session_id, + ) + elif function_name == "memory": + target = function_args.get("target", "memory") + from tools.memory_tool import memory_tool as _memory_tool + result = _memory_tool( + action=function_args.get("action"), + target=target, + content=function_args.get("content"), + old_text=function_args.get("old_text"), + store=self._memory_store, + ) + # Bridge: notify external memory provider of built-in memory writes + if self._memory_manager and function_args.get("action") in ("add", "replace"): + try: + self._memory_manager.on_memory_write( + function_args.get("action", ""), + target, + function_args.get("content", ""), + ) + except Exception: + pass + return result + elif self._memory_manager and self._memory_manager.has_tool(function_name): + return self._memory_manager.handle_tool_call(function_name, function_args) + elif function_name == "clarify": + from tools.clarify_tool import clarify_tool as _clarify_tool + return _clarify_tool( + question=function_args.get("question", ""), + choices=function_args.get("choices"), + callback=self.clarify_callback, + ) + elif function_name == "delegate_task": + from tools.delegate_tool import delegate_task as _delegate_task + return _delegate_task( + goal=function_args.get("goal"), + context=function_args.get("context"), + toolsets=function_args.get("toolsets"), + tasks=function_args.get("tasks"), + max_iterations=function_args.get("max_iterations"), + parent_agent=self, + ) + else: + return handle_function_call( + function_name, function_args, effective_task_id, + tool_call_id=tool_call_id, + session_id=self.session_id or "", + enabled_tools=list(self.valid_tool_names) if self.valid_tool_names else None, + skip_pre_tool_call_hook=True, + ) + + def _execute_tool_calls_concurrent(self, assistant_message, messages: list, effective_task_id: str, api_call_count: int = 0) -> None: + """Execute multiple tool calls concurrently using a thread pool. + + Results are collected in the original tool-call order and appended to + messages so the API sees them in the expected sequence. + """ + tool_calls = assistant_message.tool_calls + num_tools = len(tool_calls) + + # ── Pre-flight: interrupt check ────────────────────────────────── + if self._interrupt_requested: + print(f"{self.log_prefix}⚡ Interrupt: skipping {num_tools} tool call(s)") + for tc in tool_calls: + messages.append({ + "role": "tool", + "content": f"[Tool execution cancelled — {tc.function.name} was skipped due to user interrupt]", + "tool_call_id": tc.id, + }) + return + + # ── Parse args + pre-execution bookkeeping ─────────────────────── + parsed_calls = [] # list of (tool_call, function_name, function_args) + for tool_call in tool_calls: + function_name = tool_call.function.name + + # Reset nudge counters + if function_name == "memory": + self._turns_since_memory = 0 + elif function_name == "skill_manage": + self._iters_since_skill = 0 + + try: + function_args = json.loads(tool_call.function.arguments) + except json.JSONDecodeError: + function_args = {} + if not isinstance(function_args, dict): + function_args = {} + + # Checkpoint for file-mutating tools + if function_name in ("write_file", "patch") and self._checkpoint_mgr.enabled: + try: + file_path = function_args.get("path", "") + if file_path: + work_dir = self._checkpoint_mgr.get_working_dir_for_path(file_path) + self._checkpoint_mgr.ensure_checkpoint(work_dir, f"before {function_name}") + except Exception: + pass + + # Checkpoint before destructive terminal commands + if function_name == "terminal" and self._checkpoint_mgr.enabled: + try: + cmd = function_args.get("command", "") + if _is_destructive_command(cmd): + cwd = function_args.get("workdir") or os.getenv("TERMINAL_CWD", os.getcwd()) + self._checkpoint_mgr.ensure_checkpoint( + cwd, f"before terminal: {cmd[:60]}" + ) + except Exception: + pass + + parsed_calls.append((tool_call, function_name, function_args)) + + # ── Logging / callbacks ────────────────────────────────────────── + tool_names_str = ", ".join(name for _, name, _ in parsed_calls) + if not self.quiet_mode: + print(f" ⚡ Concurrent: {num_tools} tool calls — {tool_names_str}") + for i, (tc, name, args) in enumerate(parsed_calls, 1): + args_str = json.dumps(args, ensure_ascii=False) + if self.verbose_logging: + print(f" 📞 Tool {i}: {name}({list(args.keys())})") + print(f" Args: {args_str}") + else: + args_preview = args_str[:self.log_prefix_chars] + "..." if len(args_str) > self.log_prefix_chars else args_str + print(f" 📞 Tool {i}: {name}({list(args.keys())}) - {args_preview}") + + for tc, name, args in parsed_calls: + if self.tool_progress_callback: + try: + preview = _build_tool_preview(name, args) + self.tool_progress_callback("tool.started", name, preview, args) + except Exception as cb_err: + logging.debug(f"Tool progress callback error: {cb_err}") + + for tc, name, args in parsed_calls: + if self.tool_start_callback: + try: + self.tool_start_callback(tc.id, name, args) + except Exception as cb_err: + logging.debug(f"Tool start callback error: {cb_err}") + + # ── Concurrent execution ───────────────────────────────────────── + # Each slot holds (function_name, function_args, function_result, duration, error_flag) + results = [None] * num_tools + + def _run_tool(index, tool_call, function_name, function_args): + """Worker function executed in a thread.""" + start = time.time() + try: + result = self._invoke_tool(function_name, function_args, effective_task_id, tool_call.id) + except Exception as tool_error: + result = f"Error executing tool '{function_name}': {tool_error}" + logger.error("_invoke_tool raised for %s: %s", function_name, tool_error, exc_info=True) + duration = time.time() - start + is_error, _ = _detect_tool_failure(function_name, result) + if is_error: + logger.info("tool %s failed (%.2fs): %s", function_name, duration, result[:200]) + else: + logger.info("tool %s completed (%.2fs, %d chars)", function_name, duration, len(result)) + results[index] = (function_name, function_args, result, duration, is_error) + + # Start spinner for CLI mode (skip when TUI handles tool progress) + spinner = None + if self._should_emit_quiet_tool_messages() and self._should_start_quiet_spinner(): + face = random.choice(KawaiiSpinner.KAWAII_WAITING) + spinner = KawaiiSpinner(f"{face} ⚡ running {num_tools} tools concurrently", spinner_type='dots', print_fn=self._print_fn) + spinner.start() + + try: + max_workers = min(num_tools, _MAX_TOOL_WORKERS) + with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor: + futures = [] + for i, (tc, name, args) in enumerate(parsed_calls): + f = executor.submit(_run_tool, i, tc, name, args) + futures.append(f) + + # Wait for all to complete (exceptions are captured inside _run_tool) + concurrent.futures.wait(futures) + finally: + if spinner: + # Build a summary message for the spinner stop + completed = sum(1 for r in results if r is not None) + total_dur = sum(r[3] for r in results if r is not None) + spinner.stop(f"⚡ {completed}/{num_tools} tools completed in {total_dur:.1f}s total") + + # ── Post-execution: display per-tool results ───────────────────── + for i, (tc, name, args) in enumerate(parsed_calls): + r = results[i] + if r is None: + # Shouldn't happen, but safety fallback + function_result = f"Error executing tool '{name}': thread did not return a result" + tool_duration = 0.0 + else: + function_name, function_args, function_result, tool_duration, is_error = r + + if is_error: + result_preview = function_result[:200] if len(function_result) > 200 else function_result + logger.warning("Tool %s returned error (%.2fs): %s", function_name, tool_duration, result_preview) + + if self.tool_progress_callback: + try: + self.tool_progress_callback( + "tool.completed", function_name, None, function_args, + result=function_result, duration=tool_duration, is_error=is_error, + ) + except Exception as cb_err: + logging.debug(f"Tool progress callback error: {cb_err}") + + if self.verbose_logging: + logging.debug(f"Tool {function_name} completed in {tool_duration:.2f}s") + logging.debug(f"Tool result ({len(function_result)} chars): {function_result}") + + # Print cute message per tool + if self._should_emit_quiet_tool_messages(): + cute_msg = _get_cute_tool_message_impl(name, args, tool_duration, result=function_result) + self._safe_print(f" {cute_msg}") + elif not self.quiet_mode: + if self.verbose_logging: + print(f" ✅ Tool {i+1} completed in {tool_duration:.2f}s") + print(f" Result: {function_result}") + else: + response_preview = function_result[:self.log_prefix_chars] + "..." if len(function_result) > self.log_prefix_chars else function_result + print(f" ✅ Tool {i+1} completed in {tool_duration:.2f}s - {response_preview}") + + self._current_tool = None + self._touch_activity(f"tool completed: {name} ({tool_duration:.1f}s)") + + if self.tool_complete_callback: + try: + self.tool_complete_callback(tc.id, name, args, function_result) + except Exception as cb_err: + logging.debug(f"Tool complete callback error: {cb_err}") + + function_result = maybe_persist_tool_result( + content=function_result, + tool_name=name, + tool_use_id=tc.id, + env=get_active_env(effective_task_id), + ) + + subdir_hints = self._subdirectory_hints.check_tool_call(name, args) + if subdir_hints: + function_result += subdir_hints + + tool_msg = { + "role": "tool", + "content": function_result, + "tool_call_id": tc.id, + } + messages.append(tool_msg) + + # ── Per-turn aggregate budget enforcement ───────────────────────── + num_tools = len(parsed_calls) + if num_tools > 0: + turn_tool_msgs = messages[-num_tools:] + enforce_turn_budget(turn_tool_msgs, env=get_active_env(effective_task_id)) + + def _execute_tool_calls_sequential(self, assistant_message, messages: list, effective_task_id: str, api_call_count: int = 0) -> None: + """Execute tool calls sequentially (original behavior). Used for single calls or interactive tools.""" + for i, tool_call in enumerate(assistant_message.tool_calls, 1): + # SAFETY: check interrupt BEFORE starting each tool. + # If the user sent "stop" during a previous tool's execution, + # do NOT start any more tools -- skip them all immediately. + if self._interrupt_requested: + remaining_calls = assistant_message.tool_calls[i-1:] + if remaining_calls: + self._vprint(f"{self.log_prefix}⚡ Interrupt: skipping {len(remaining_calls)} tool call(s)", force=True) + for skipped_tc in remaining_calls: + skipped_name = skipped_tc.function.name + skip_msg = { + "role": "tool", + "content": f"[Tool execution cancelled — {skipped_name} was skipped due to user interrupt]", + "tool_call_id": skipped_tc.id, + } + messages.append(skip_msg) + break + + function_name = tool_call.function.name + + try: + function_args = json.loads(tool_call.function.arguments) + except json.JSONDecodeError as e: + logging.warning(f"Unexpected JSON error after validation: {e}") + function_args = {} + if not isinstance(function_args, dict): + function_args = {} + + # Check plugin hooks for a block directive before executing. + _block_msg: Optional[str] = None + try: + from hermes_cli.plugins import get_pre_tool_call_block_message + _block_msg = get_pre_tool_call_block_message( + function_name, function_args, task_id=effective_task_id or "", + ) + except Exception: + pass + + if _block_msg is not None: + # Tool blocked by plugin policy — skip counter resets. + # Execution is handled below in the tool dispatch chain. + pass + else: + # Reset nudge counters when the relevant tool is actually used + if function_name == "memory": + self._turns_since_memory = 0 + elif function_name == "skill_manage": + self._iters_since_skill = 0 + + if not self.quiet_mode: + args_str = json.dumps(function_args, ensure_ascii=False) + if self.verbose_logging: + print(f" 📞 Tool {i}: {function_name}({list(function_args.keys())})") + print(f" Args: {args_str}") + else: + args_preview = args_str[:self.log_prefix_chars] + "..." if len(args_str) > self.log_prefix_chars else args_str + print(f" 📞 Tool {i}: {function_name}({list(function_args.keys())}) - {args_preview}") + + if _block_msg is None: + self._current_tool = function_name + self._touch_activity(f"executing tool: {function_name}") + + # Set activity callback for long-running tool execution (terminal + # commands, etc.) so the gateway's inactivity monitor doesn't kill + # the agent while a command is running. + if _block_msg is None: + try: + from tools.environments.base import set_activity_callback + set_activity_callback(self._touch_activity) + except Exception: + pass + + if _block_msg is None and self.tool_progress_callback: + try: + preview = _build_tool_preview(function_name, function_args) + self.tool_progress_callback("tool.started", function_name, preview, function_args) + except Exception as cb_err: + logging.debug(f"Tool progress callback error: {cb_err}") + + if _block_msg is None and self.tool_start_callback: + try: + self.tool_start_callback(tool_call.id, function_name, function_args) + except Exception as cb_err: + logging.debug(f"Tool start callback error: {cb_err}") + + # Checkpoint: snapshot working dir before file-mutating tools + if _block_msg is None and function_name in ("write_file", "patch") and self._checkpoint_mgr.enabled: + try: + file_path = function_args.get("path", "") + if file_path: + work_dir = self._checkpoint_mgr.get_working_dir_for_path(file_path) + self._checkpoint_mgr.ensure_checkpoint( + work_dir, f"before {function_name}" + ) + except Exception: + pass # never block tool execution + + # Checkpoint before destructive terminal commands + if _block_msg is None and function_name == "terminal" and self._checkpoint_mgr.enabled: + try: + cmd = function_args.get("command", "") + if _is_destructive_command(cmd): + cwd = function_args.get("workdir") or os.getenv("TERMINAL_CWD", os.getcwd()) + self._checkpoint_mgr.ensure_checkpoint( + cwd, f"before terminal: {cmd[:60]}" + ) + except Exception: + pass # never block tool execution + + tool_start_time = time.time() + + if _block_msg is not None: + # Tool blocked by plugin policy — return error without executing. + function_result = json.dumps({"error": _block_msg}, ensure_ascii=False) + tool_duration = 0.0 + elif function_name == "todo": + from tools.todo_tool import todo_tool as _todo_tool + function_result = _todo_tool( + todos=function_args.get("todos"), + merge=function_args.get("merge", False), + store=self._todo_store, + ) + tool_duration = time.time() - tool_start_time + if self._should_emit_quiet_tool_messages(): + self._vprint(f" {_get_cute_tool_message_impl('todo', function_args, tool_duration, result=function_result)}") + elif function_name == "session_search": + if not self._session_db: + function_result = json.dumps({"success": False, "error": "Session database not available."}) + else: + from tools.session_search_tool import session_search as _session_search + function_result = _session_search( + query=function_args.get("query", ""), + role_filter=function_args.get("role_filter"), + limit=function_args.get("limit", 3), + db=self._session_db, + current_session_id=self.session_id, + ) + tool_duration = time.time() - tool_start_time + if self._should_emit_quiet_tool_messages(): + self._vprint(f" {_get_cute_tool_message_impl('session_search', function_args, tool_duration, result=function_result)}") + elif function_name == "memory": + target = function_args.get("target", "memory") + from tools.memory_tool import memory_tool as _memory_tool + function_result = _memory_tool( + action=function_args.get("action"), + target=target, + content=function_args.get("content"), + old_text=function_args.get("old_text"), + store=self._memory_store, + ) + tool_duration = time.time() - tool_start_time + if self._should_emit_quiet_tool_messages(): + self._vprint(f" {_get_cute_tool_message_impl('memory', function_args, tool_duration, result=function_result)}") + elif function_name == "clarify": + from tools.clarify_tool import clarify_tool as _clarify_tool + function_result = _clarify_tool( + question=function_args.get("question", ""), + choices=function_args.get("choices"), + callback=self.clarify_callback, + ) + tool_duration = time.time() - tool_start_time + if self._should_emit_quiet_tool_messages(): + self._vprint(f" {_get_cute_tool_message_impl('clarify', function_args, tool_duration, result=function_result)}") + elif function_name == "delegate_task": + from tools.delegate_tool import delegate_task as _delegate_task + tasks_arg = function_args.get("tasks") + if tasks_arg and isinstance(tasks_arg, list): + spinner_label = f"🔀 delegating {len(tasks_arg)} tasks" + else: + goal_preview = (function_args.get("goal") or "")[:30] + spinner_label = f"🔀 {goal_preview}" if goal_preview else "🔀 delegating" + spinner = None + if self._should_emit_quiet_tool_messages() and self._should_start_quiet_spinner(): + face = random.choice(KawaiiSpinner.KAWAII_WAITING) + spinner = KawaiiSpinner(f"{face} {spinner_label}", spinner_type='dots', print_fn=self._print_fn) + spinner.start() + self._delegate_spinner = spinner + _delegate_result = None + try: + function_result = _delegate_task( + goal=function_args.get("goal"), + context=function_args.get("context"), + toolsets=function_args.get("toolsets"), + tasks=tasks_arg, + max_iterations=function_args.get("max_iterations"), + parent_agent=self, + ) + _delegate_result = function_result + finally: + self._delegate_spinner = None + tool_duration = time.time() - tool_start_time + cute_msg = _get_cute_tool_message_impl('delegate_task', function_args, tool_duration, result=_delegate_result) + if spinner: + spinner.stop(cute_msg) + elif self._should_emit_quiet_tool_messages(): + self._vprint(f" {cute_msg}") + elif self._context_engine_tool_names and function_name in self._context_engine_tool_names: + # Context engine tools (lcm_grep, lcm_describe, lcm_expand, etc.) + spinner = None + if self.quiet_mode and not self.tool_progress_callback: + face = random.choice(KawaiiSpinner.KAWAII_WAITING) + emoji = _get_tool_emoji(function_name) + preview = _build_tool_preview(function_name, function_args) or function_name + spinner = KawaiiSpinner(f"{face} {emoji} {preview}", spinner_type='dots', print_fn=self._print_fn) + spinner.start() + _ce_result = None + try: + function_result = self.context_compressor.handle_tool_call(function_name, function_args, messages=messages) + _ce_result = function_result + except Exception as tool_error: + function_result = json.dumps({"error": f"Context engine tool '{function_name}' failed: {tool_error}"}) + logger.error("context_engine.handle_tool_call raised for %s: %s", function_name, tool_error, exc_info=True) + finally: + tool_duration = time.time() - tool_start_time + cute_msg = _get_cute_tool_message_impl(function_name, function_args, tool_duration, result=_ce_result) + if spinner: + spinner.stop(cute_msg) + elif self.quiet_mode: + self._vprint(f" {cute_msg}") + elif self._memory_manager and self._memory_manager.has_tool(function_name): + # Memory provider tools (hindsight_retain, honcho_search, etc.) + # These are not in the tool registry — route through MemoryManager. + spinner = None + if self._should_emit_quiet_tool_messages() and self._should_start_quiet_spinner(): + face = random.choice(KawaiiSpinner.KAWAII_WAITING) + emoji = _get_tool_emoji(function_name) + preview = _build_tool_preview(function_name, function_args) or function_name + spinner = KawaiiSpinner(f"{face} {emoji} {preview}", spinner_type='dots', print_fn=self._print_fn) + spinner.start() + _mem_result = None + try: + function_result = self._memory_manager.handle_tool_call(function_name, function_args) + _mem_result = function_result + except Exception as tool_error: + function_result = json.dumps({"error": f"Memory tool '{function_name}' failed: {tool_error}"}) + logger.error("memory_manager.handle_tool_call raised for %s: %s", function_name, tool_error, exc_info=True) + finally: + tool_duration = time.time() - tool_start_time + cute_msg = _get_cute_tool_message_impl(function_name, function_args, tool_duration, result=_mem_result) + if spinner: + spinner.stop(cute_msg) + elif self._should_emit_quiet_tool_messages(): + self._vprint(f" {cute_msg}") + elif self.quiet_mode: + spinner = None + if self._should_emit_quiet_tool_messages() and self._should_start_quiet_spinner(): + face = random.choice(KawaiiSpinner.KAWAII_WAITING) + emoji = _get_tool_emoji(function_name) + preview = _build_tool_preview(function_name, function_args) or function_name + spinner = KawaiiSpinner(f"{face} {emoji} {preview}", spinner_type='dots', print_fn=self._print_fn) + spinner.start() + _spinner_result = None + try: + function_result = handle_function_call( + function_name, function_args, effective_task_id, + tool_call_id=tool_call.id, + session_id=self.session_id or "", + enabled_tools=list(self.valid_tool_names) if self.valid_tool_names else None, + skip_pre_tool_call_hook=True, + ) + _spinner_result = function_result + except Exception as tool_error: + function_result = f"Error executing tool '{function_name}': {tool_error}" + logger.error("handle_function_call raised for %s: %s", function_name, tool_error, exc_info=True) + finally: + tool_duration = time.time() - tool_start_time + cute_msg = _get_cute_tool_message_impl(function_name, function_args, tool_duration, result=_spinner_result) + if spinner: + spinner.stop(cute_msg) + elif self._should_emit_quiet_tool_messages(): + self._vprint(f" {cute_msg}") + else: + try: + function_result = handle_function_call( + function_name, function_args, effective_task_id, + tool_call_id=tool_call.id, + session_id=self.session_id or "", + enabled_tools=list(self.valid_tool_names) if self.valid_tool_names else None, + skip_pre_tool_call_hook=True, + ) + except Exception as tool_error: + function_result = f"Error executing tool '{function_name}': {tool_error}" + logger.error("handle_function_call raised for %s: %s", function_name, tool_error, exc_info=True) + tool_duration = time.time() - tool_start_time + + result_preview = function_result if self.verbose_logging else ( + function_result[:200] if len(function_result) > 200 else function_result + ) + + # Log tool errors to the persistent error log so [error] tags + # in the UI always have a corresponding detailed entry on disk. + _is_error_result, _ = _detect_tool_failure(function_name, function_result) + if _is_error_result: + logger.warning("Tool %s returned error (%.2fs): %s", function_name, tool_duration, result_preview) + else: + logger.info("tool %s completed (%.2fs, %d chars)", function_name, tool_duration, len(function_result)) + + if self.tool_progress_callback: + try: + self.tool_progress_callback( + "tool.completed", function_name, None, function_args, + result=function_result, duration=tool_duration, is_error=_is_error_result, + ) + except Exception as cb_err: + logging.debug(f"Tool progress callback error: {cb_err}") + + self._current_tool = None + self._touch_activity(f"tool completed: {function_name} ({tool_duration:.1f}s)") + + if self.verbose_logging: + logging.debug(f"Tool {function_name} completed in {tool_duration:.2f}s") + logging.debug(f"Tool result ({len(function_result)} chars): {function_result}") + + if self.tool_complete_callback: + try: + self.tool_complete_callback(tool_call.id, function_name, function_args, function_result) + except Exception as cb_err: + logging.debug(f"Tool complete callback error: {cb_err}") + + function_result = maybe_persist_tool_result( + content=function_result, + tool_name=function_name, + tool_use_id=tool_call.id, + env=get_active_env(effective_task_id), + ) + + # Discover subdirectory context files from tool arguments + subdir_hints = self._subdirectory_hints.check_tool_call(function_name, function_args) + if subdir_hints: + function_result += subdir_hints + + tool_msg = { + "role": "tool", + "content": function_result, + "tool_call_id": tool_call.id + } + messages.append(tool_msg) + + if not self.quiet_mode: + if self.verbose_logging: + print(f" ✅ Tool {i} completed in {tool_duration:.2f}s") + print(f" Result: {function_result}") + else: + response_preview = function_result[:self.log_prefix_chars] + "..." if len(function_result) > self.log_prefix_chars else function_result + print(f" ✅ Tool {i} completed in {tool_duration:.2f}s - {response_preview}") + + if self._interrupt_requested and i < len(assistant_message.tool_calls): + remaining = len(assistant_message.tool_calls) - i + self._vprint(f"{self.log_prefix}⚡ Interrupt: skipping {remaining} remaining tool call(s)", force=True) + for skipped_tc in assistant_message.tool_calls[i:]: + skipped_name = skipped_tc.function.name + skip_msg = { + "role": "tool", + "content": f"[Tool execution skipped — {skipped_name} was not started. User sent a new message]", + "tool_call_id": skipped_tc.id + } + messages.append(skip_msg) + break + + if self.tool_delay > 0 and i < len(assistant_message.tool_calls): + time.sleep(self.tool_delay) + + # ── Per-turn aggregate budget enforcement ───────────────────────── + num_tools_seq = len(assistant_message.tool_calls) + if num_tools_seq > 0: + enforce_turn_budget(messages[-num_tools_seq:], env=get_active_env(effective_task_id)) + + + + def _emit_context_pressure(self, compaction_progress: float, compressor) -> None: + """Notify the user that context is approaching the compaction threshold. + + Args: + compaction_progress: How close to compaction (0.0–1.0, where 1.0 = fires). + compressor: The ContextCompressor instance (for threshold/context info). + + Purely user-facing — does NOT modify the message stream. + For CLI: prints a formatted line with a progress bar. + For gateway: fires status_callback so the platform can send a chat message. + """ + from agent.display import format_context_pressure, format_context_pressure_gateway + + threshold_pct = compressor.threshold_tokens / compressor.context_length if compressor.context_length else 0.5 + + # CLI output — always shown (these are user-facing status notifications, + # not verbose debug output, so they bypass quiet_mode). + # Gateway users also get the callback below. + if self.platform in (None, "cli"): + line = format_context_pressure( + compaction_progress=compaction_progress, + threshold_tokens=compressor.threshold_tokens, + threshold_percent=threshold_pct, + compression_enabled=self.compression_enabled, + ) + self._safe_print(line) + + # Gateway / external consumers + if self.status_callback: + try: + msg = format_context_pressure_gateway( + compaction_progress=compaction_progress, + threshold_percent=threshold_pct, + compression_enabled=self.compression_enabled, + ) + self.status_callback("context_pressure", msg) + except Exception: + logger.debug("status_callback error in context pressure", exc_info=True) + + def _handle_max_iterations(self, messages: list, api_call_count: int) -> str: + """Request a summary when max iterations are reached. Returns the final response text.""" + print(f"⚠️ Reached maximum iterations ({self.max_iterations}). Requesting summary...") + + summary_request = ( + "You've reached the maximum number of tool-calling iterations allowed. " + "Please provide a final response summarizing what you've found and accomplished so far, " + "without calling any more tools." + ) + messages.append({"role": "user", "content": summary_request}) + + try: + # Build API messages, stripping internal-only fields + # (finish_reason, reasoning) that strict APIs like Mistral reject with 422 + _needs_sanitize = self._should_sanitize_tool_calls() + api_messages = [] + for msg in messages: + api_msg = msg.copy() + for internal_field in ("reasoning", "finish_reason", "_thinking_prefill"): + api_msg.pop(internal_field, None) + if _needs_sanitize: + self._sanitize_tool_calls_for_strict_api(api_msg) + api_messages.append(api_msg) + + effective_system = self._cached_system_prompt or "" + if self.ephemeral_system_prompt: + effective_system = (effective_system + "\n\n" + self.ephemeral_system_prompt).strip() + if effective_system: + api_messages = [{"role": "system", "content": effective_system}] + api_messages + if self.prefill_messages: + sys_offset = 1 if effective_system else 0 + for idx, pfm in enumerate(self.prefill_messages): + api_messages.insert(sys_offset + idx, pfm.copy()) + + summary_extra_body = {} + _is_nous = "nousresearch" in self._base_url_lower + if self._supports_reasoning_extra_body(): + if self.reasoning_config is not None: + summary_extra_body["reasoning"] = self.reasoning_config + else: + summary_extra_body["reasoning"] = { + "enabled": True, + "effort": "medium" + } + if _is_nous: + summary_extra_body["tags"] = ["product=hermes-agent"] + + if self.api_mode == "codex_responses": + codex_kwargs = self._build_api_kwargs(api_messages) + codex_kwargs.pop("tools", None) + summary_response = self._run_codex_stream(codex_kwargs) + assistant_message, _ = self._normalize_codex_response(summary_response) + final_response = (assistant_message.content or "").strip() if assistant_message else "" + else: + summary_kwargs = { + "model": self.model, + "messages": api_messages, + } + if self.max_tokens is not None: + summary_kwargs.update(self._max_tokens_param(self.max_tokens)) + + # Include provider routing preferences + provider_preferences = {} + if self.providers_allowed: + provider_preferences["only"] = self.providers_allowed + if self.providers_ignored: + provider_preferences["ignore"] = self.providers_ignored + if self.providers_order: + provider_preferences["order"] = self.providers_order + if self.provider_sort: + provider_preferences["sort"] = self.provider_sort + if provider_preferences: + summary_extra_body["provider"] = provider_preferences + + if summary_extra_body: + summary_kwargs["extra_body"] = summary_extra_body + + if self.api_mode == "anthropic_messages": + from agent.anthropic_adapter import build_anthropic_kwargs as _bak, normalize_anthropic_response as _nar + _ant_kw = _bak(model=self.model, messages=api_messages, tools=None, + max_tokens=self.max_tokens, reasoning_config=self.reasoning_config, + is_oauth=self._is_anthropic_oauth, + preserve_dots=self._anthropic_preserve_dots()) + summary_response = self._anthropic_messages_create(_ant_kw) + _msg, _ = _nar(summary_response, strip_tool_prefix=self._is_anthropic_oauth) + final_response = (_msg.content or "").strip() + else: + summary_response = self._ensure_primary_openai_client(reason="iteration_limit_summary").chat.completions.create(**summary_kwargs) + + if summary_response.choices and summary_response.choices[0].message.content: + final_response = summary_response.choices[0].message.content + else: + final_response = "" + + if final_response: + if "" in final_response: + final_response = re.sub(r'.*?\s*', '', final_response, flags=re.DOTALL).strip() + if final_response: + messages.append({"role": "assistant", "content": final_response}) + else: + final_response = "I reached the iteration limit and couldn't generate a summary." + else: + # Retry summary generation + if self.api_mode == "codex_responses": + codex_kwargs = self._build_api_kwargs(api_messages) + codex_kwargs.pop("tools", None) + retry_response = self._run_codex_stream(codex_kwargs) + retry_msg, _ = self._normalize_codex_response(retry_response) + final_response = (retry_msg.content or "").strip() if retry_msg else "" + elif self.api_mode == "anthropic_messages": + from agent.anthropic_adapter import build_anthropic_kwargs as _bak2, normalize_anthropic_response as _nar2 + _ant_kw2 = _bak2(model=self.model, messages=api_messages, tools=None, + is_oauth=self._is_anthropic_oauth, + max_tokens=self.max_tokens, reasoning_config=self.reasoning_config, + preserve_dots=self._anthropic_preserve_dots()) + retry_response = self._anthropic_messages_create(_ant_kw2) + _retry_msg, _ = _nar2(retry_response, strip_tool_prefix=self._is_anthropic_oauth) + final_response = (_retry_msg.content or "").strip() + else: + summary_kwargs = { + "model": self.model, + "messages": api_messages, + } + if self.max_tokens is not None: + summary_kwargs.update(self._max_tokens_param(self.max_tokens)) + if summary_extra_body: + summary_kwargs["extra_body"] = summary_extra_body + + summary_response = self._ensure_primary_openai_client(reason="iteration_limit_summary_retry").chat.completions.create(**summary_kwargs) + + if summary_response.choices and summary_response.choices[0].message.content: + final_response = summary_response.choices[0].message.content + else: + final_response = "" + + if final_response: + if "" in final_response: + final_response = re.sub(r'.*?\s*', '', final_response, flags=re.DOTALL).strip() + if final_response: + messages.append({"role": "assistant", "content": final_response}) + else: + final_response = "I reached the iteration limit and couldn't generate a summary." + else: + final_response = "I reached the iteration limit and couldn't generate a summary." + + except Exception as e: + logging.warning(f"Failed to get summary response: {e}") + final_response = f"I reached the maximum iterations ({self.max_iterations}) but couldn't summarize. Error: {str(e)}" + + return final_response + + def run_conversation( + self, + user_message: str, + system_message: str = None, + conversation_history: List[Dict[str, Any]] = None, + task_id: str = None, + stream_callback: Optional[callable] = None, + persist_user_message: Optional[str] = None, + ) -> Dict[str, Any]: + """ + Run a complete conversation with tool calling until completion. + + Args: + user_message (str): The user's message/question + system_message (str): Custom system message (optional, overrides ephemeral_system_prompt if provided) + conversation_history (List[Dict]): Previous conversation messages (optional) + task_id (str): Unique identifier for this task to isolate VMs between concurrent tasks (optional, auto-generated if not provided) + stream_callback: Optional callback invoked with each text delta during streaming. + Used by the TTS pipeline to start audio generation before the full response. + When None (default), API calls use the standard non-streaming path. + persist_user_message: Optional clean user message to store in + transcripts/history when user_message contains API-only + synthetic prefixes. + or queuing follow-up prefetch work. + + Returns: + Dict: Complete conversation result with final response and message history + """ + # Guard stdio against OSError from broken pipes (systemd/headless/daemon). + # Installed once, transparent when streams are healthy, prevents crash on write. + _install_safe_stdio() + + # Tag all log records on this thread with the session ID so + # ``hermes logs --session `` can filter a single conversation. + from hermes_logging import set_session_context + set_session_context(self.session_id) + + # If the previous turn activated fallback, restore the primary + # runtime so this turn gets a fresh attempt with the preferred model. + # No-op when _fallback_activated is False (gateway, first turn, etc.). + self._restore_primary_runtime() + + # Sanitize surrogate characters from user input. Clipboard paste from + # rich-text editors (Google Docs, Word, etc.) can inject lone surrogates + # that are invalid UTF-8 and crash JSON serialization in the OpenAI SDK. + if isinstance(user_message, str): + user_message = _sanitize_surrogates(user_message) + if isinstance(persist_user_message, str): + persist_user_message = _sanitize_surrogates(persist_user_message) + + # Store stream callback for _interruptible_api_call to pick up + self._stream_callback = stream_callback + self._persist_user_message_idx = None + self._persist_user_message_override = persist_user_message + # Generate unique task_id if not provided to isolate VMs between concurrent tasks + effective_task_id = task_id or str(uuid.uuid4()) + + # Reset retry counters and iteration budget at the start of each turn + # so subagent usage from a previous turn doesn't eat into the next one. + self._invalid_tool_retries = 0 + self._invalid_json_retries = 0 + self._empty_content_retries = 0 + self._incomplete_scratchpad_retries = 0 + self._codex_incomplete_retries = 0 + self._thinking_prefill_retries = 0 + self._last_content_with_tools = None + self._mute_post_response = False + self._unicode_sanitization_passes = 0 + + # Pre-turn connection health check: detect and clean up dead TCP + # connections left over from provider outages or dropped streams. + # This prevents the next API call from hanging on a zombie socket. + if self.api_mode != "anthropic_messages": + try: + if self._cleanup_dead_connections(): + self._emit_status( + "🔌 Detected stale connections from a previous provider " + "issue — cleaned up automatically. Proceeding with fresh " + "connection." + ) + except Exception: + pass + # Replay compression warning through status_callback for gateway + # platforms (the callback was not wired during __init__). + if self._compression_warning: + self._replay_compression_warning() + self._compression_warning = None # send once + + # NOTE: _turns_since_memory and _iters_since_skill are NOT reset here. + # They are initialized in __init__ and must persist across run_conversation + # calls so that nudge logic accumulates correctly in CLI mode. + self.iteration_budget = IterationBudget(self.max_iterations) + + # Log conversation turn start for debugging/observability + _msg_preview = (user_message[:80] + "...") if isinstance(user_message, str) and len(user_message) > 80 else (user_message if isinstance(user_message, str) else "[multimodal]") + _msg_preview = _msg_preview.replace("\n", " ") if isinstance(_msg_preview, str) else _msg_preview + logger.info( + "conversation turn: session=%s model=%s provider=%s platform=%s history=%d msg=%r", + self.session_id or "none", self.model, self.provider or "unknown", + self.platform or "unknown", len(conversation_history or []), + _msg_preview, + ) + + # Initialize conversation (copy to avoid mutating the caller's list) + messages = list(conversation_history) if conversation_history else [] + + # Hydrate todo store from conversation history (gateway creates a fresh + # AIAgent per message, so the in-memory store is empty -- we need to + # recover the todo state from the most recent todo tool response in history) + if conversation_history and not self._todo_store.has_items(): + self._hydrate_todo_store(conversation_history) + + # Prefill messages (few-shot priming) are injected at API-call time only, + # never stored in the messages list. This keeps them ephemeral: they won't + # be saved to session DB, session logs, or batch trajectories, but they're + # automatically re-applied on every API call (including session continuations). + + # Track user turns for memory flush and periodic nudge logic + self._user_turn_count += 1 + + # Preserve the original user message (no nudge injection). + original_user_message = persist_user_message if persist_user_message is not None else user_message + + # Track memory nudge trigger (turn-based, checked here). + # Skill trigger is checked AFTER the agent loop completes, based on + # how many tool iterations THIS turn used. + _should_review_memory = False + if (self._memory_nudge_interval > 0 + and "memory" in self.valid_tool_names + and self._memory_store): + self._turns_since_memory += 1 + if self._turns_since_memory >= self._memory_nudge_interval: + _should_review_memory = True + self._turns_since_memory = 0 + + # Add user message + user_msg = {"role": "user", "content": user_message} + messages.append(user_msg) + current_turn_user_idx = len(messages) - 1 + self._persist_user_message_idx = current_turn_user_idx + + if not self.quiet_mode: + self._safe_print(f"💬 Starting conversation: '{user_message[:60]}{'...' if len(user_message) > 60 else ''}'") + + # ── System prompt (cached per session for prefix caching) ── + # Built once on first call, reused for all subsequent calls. + # Only rebuilt after context compression events (which invalidate + # the cache and reload memory from disk). + # + # For continuing sessions (gateway creates a fresh AIAgent per + # message), we load the stored system prompt from the session DB + # instead of rebuilding. Rebuilding would pick up memory changes + # from disk that the model already knows about (it wrote them!), + # producing a different system prompt and breaking the Anthropic + # prefix cache. + if self._cached_system_prompt is None: + stored_prompt = None + if conversation_history and self._session_db: + try: + session_row = self._session_db.get_session(self.session_id) + if session_row: + stored_prompt = session_row.get("system_prompt") or None + except Exception: + pass # Fall through to build fresh + + if stored_prompt: + # Continuing session — reuse the exact system prompt from + # the previous turn so the Anthropic cache prefix matches. + self._cached_system_prompt = stored_prompt + else: + # First turn of a new session — build from scratch. + self._cached_system_prompt = self._build_system_prompt(system_message) + # Plugin hook: on_session_start + # Fired once when a brand-new session is created (not on + # continuation). Plugins can use this to initialise + # session-scoped state (e.g. warm a memory cache). + try: + from hermes_cli.plugins import invoke_hook as _invoke_hook + _invoke_hook( + "on_session_start", + session_id=self.session_id, + model=self.model, + platform=getattr(self, "platform", None) or "", + ) + except Exception as exc: + logger.warning("on_session_start hook failed: %s", exc) + + # Store the system prompt snapshot in SQLite + if self._session_db: + try: + self._session_db.update_system_prompt(self.session_id, self._cached_system_prompt) + except Exception as e: + logger.debug("Session DB update_system_prompt failed: %s", e) + + active_system_prompt = self._cached_system_prompt + + # ── Preflight context compression ── + # Before entering the main loop, check if the loaded conversation + # history already exceeds the model's context threshold. This handles + # cases where a user switches to a model with a smaller context window + # while having a large existing session — compress proactively rather + # than waiting for an API error (which might be caught as a non-retryable + # 4xx and abort the request entirely). + if ( + self.compression_enabled + and len(messages) > self.context_compressor.protect_first_n + + self.context_compressor.protect_last_n + 1 + ): + # Include tool schema tokens — with many tools these can add + # 20-30K+ tokens that the old sys+msg estimate missed entirely. + _preflight_tokens = estimate_request_tokens_rough( + messages, + system_prompt=active_system_prompt or "", + tools=self.tools or None, + ) + + if _preflight_tokens >= self.context_compressor.threshold_tokens: + logger.info( + "Preflight compression: ~%s tokens >= %s threshold (model %s, ctx %s)", + f"{_preflight_tokens:,}", + f"{self.context_compressor.threshold_tokens:,}", + self.model, + f"{self.context_compressor.context_length:,}", + ) + if not self.quiet_mode: + self._safe_print( + f"📦 Preflight compression: ~{_preflight_tokens:,} tokens " + f">= {self.context_compressor.threshold_tokens:,} threshold" + ) + # May need multiple passes for very large sessions with small + # context windows (each pass summarises the middle N turns). + for _pass in range(3): + _orig_len = len(messages) + messages, active_system_prompt = self._compress_context( + messages, system_message, approx_tokens=_preflight_tokens, + task_id=effective_task_id, + ) + if len(messages) >= _orig_len: + break # Cannot compress further + # Compression created a new session — clear the history + # reference so _flush_messages_to_session_db writes ALL + # compressed messages to the new session's SQLite, not + # skipping them because conversation_history is still the + # pre-compression length. + conversation_history = None + # Re-estimate after compression + _preflight_tokens = estimate_request_tokens_rough( + messages, + system_prompt=active_system_prompt or "", + tools=self.tools or None, + ) + if _preflight_tokens < self.context_compressor.threshold_tokens: + break # Under threshold + + # Plugin hook: pre_llm_call + # Fired once per turn before the tool-calling loop. Plugins can + # return a dict with a ``context`` key (or a plain string) whose + # value is appended to the current turn's user message. + # + # Context is ALWAYS injected into the user message, never the + # system prompt. This preserves the prompt cache prefix — the + # system prompt stays identical across turns so cached tokens + # are reused. The system prompt is Hermes's territory; plugins + # contribute context alongside the user's input. + # + # All injected context is ephemeral (not persisted to session DB). + _plugin_user_context = "" + try: + from hermes_cli.plugins import invoke_hook as _invoke_hook + _pre_results = _invoke_hook( + "pre_llm_call", + session_id=self.session_id, + user_message=original_user_message, + conversation_history=list(messages), + is_first_turn=(not bool(conversation_history)), + model=self.model, + platform=getattr(self, "platform", None) or "", + sender_id=getattr(self, "_user_id", None) or "", + ) + _ctx_parts: list[str] = [] + for r in _pre_results: + if isinstance(r, dict) and r.get("context"): + _ctx_parts.append(str(r["context"])) + elif isinstance(r, str) and r.strip(): + _ctx_parts.append(r) + if _ctx_parts: + _plugin_user_context = "\n\n".join(_ctx_parts) + except Exception as exc: + logger.warning("pre_llm_call hook failed: %s", exc) + + # Main conversation loop + api_call_count = 0 + final_response = None + interrupted = False + codex_ack_continuations = 0 + length_continue_retries = 0 + truncated_tool_call_retries = 0 + truncated_response_prefix = "" + compression_attempts = 0 + _turn_exit_reason = "unknown" # Diagnostic: why the loop ended + + # Record the execution thread so interrupt()/clear_interrupt() can + # scope the tool-level interrupt signal to THIS agent's thread only. + # Must be set before clear_interrupt() which uses it. + self._execution_thread_id = threading.current_thread().ident + + # Clear any stale interrupt state at start + self.clear_interrupt() + + # External memory provider: prefetch once before the tool loop. + # Reuse the cached result on every iteration to avoid re-calling + # prefetch_all() on each tool call (10 tool calls = 10x latency + cost). + # Use original_user_message (clean input) — user_message may contain + # injected skill content that bloats / breaks provider queries. + _ext_prefetch_cache = "" + if self._memory_manager: + try: + _query = original_user_message if isinstance(original_user_message, str) else "" + _ext_prefetch_cache = self._memory_manager.prefetch_all(_query) or "" + except Exception: + pass + + while (api_call_count < self.max_iterations and self.iteration_budget.remaining > 0) or self._budget_grace_call: + # Reset per-turn checkpoint dedup so each iteration can take one snapshot + self._checkpoint_mgr.new_turn() + + # Check for interrupt request (e.g., user sent new message) + if self._interrupt_requested: + interrupted = True + _turn_exit_reason = "interrupted_by_user" + if not self.quiet_mode: + self._safe_print("\n⚡ Breaking out of tool loop due to interrupt...") + break + + api_call_count += 1 + self._api_call_count = api_call_count + self._touch_activity(f"starting API call #{api_call_count}") + + # Grace call: the budget is exhausted but we gave the model one + # more chance. Consume the grace flag so the loop exits after + # this iteration regardless of outcome. + if self._budget_grace_call: + self._budget_grace_call = False + elif not self.iteration_budget.consume(): + _turn_exit_reason = "budget_exhausted" + if not self.quiet_mode: + self._safe_print(f"\n⚠️ Iteration budget exhausted ({self.iteration_budget.used}/{self.iteration_budget.max_total} iterations used)") + break + + # Fire step_callback for gateway hooks (agent:step event) + if self.step_callback is not None: + try: + prev_tools = [] + for _idx, _m in enumerate(reversed(messages)): + if _m.get("role") == "assistant" and _m.get("tool_calls"): + _fwd_start = len(messages) - _idx + _results_by_id = {} + for _tm in messages[_fwd_start:]: + if _tm.get("role") != "tool": + break + _tcid = _tm.get("tool_call_id") + if _tcid: + _results_by_id[_tcid] = _tm.get("content", "") + prev_tools = [ + { + "name": tc["function"]["name"], + "result": _results_by_id.get(tc.get("id")), + } + for tc in _m["tool_calls"] + if isinstance(tc, dict) + ] + break + self.step_callback(api_call_count, prev_tools) + except Exception as _step_err: + logger.debug("step_callback error (iteration %s): %s", api_call_count, _step_err) + + # Track tool-calling iterations for skill nudge. + # Counter resets whenever skill_manage is actually used. + if (self._skill_nudge_interval > 0 + and "skill_manage" in self.valid_tool_names): + self._iters_since_skill += 1 + + # Prepare messages for API call + # If we have an ephemeral system prompt, prepend it to the messages + # Note: Reasoning is embedded in content via tags for trajectory storage. + # However, providers like Moonshot AI require a separate 'reasoning_content' field + # on assistant messages with tool_calls. We handle both cases here. + api_messages = [] + for idx, msg in enumerate(messages): + api_msg = msg.copy() + + # Inject ephemeral context into the current turn's user message. + # Sources: memory manager prefetch + plugin pre_llm_call hooks + # with target="user_message" (the default). Both are + # API-call-time only — the original message in `messages` is + # never mutated, so nothing leaks into session persistence. + if idx == current_turn_user_idx and msg.get("role") == "user": + _injections = [] + if _ext_prefetch_cache: + _fenced = build_memory_context_block(_ext_prefetch_cache) + if _fenced: + _injections.append(_fenced) + if _plugin_user_context: + _injections.append(_plugin_user_context) + if _injections: + _base = api_msg.get("content", "") + if isinstance(_base, str): + api_msg["content"] = _base + "\n\n" + "\n\n".join(_injections) + + # For ALL assistant messages, pass reasoning back to the API + # This ensures multi-turn reasoning context is preserved + if msg.get("role") == "assistant": + reasoning_text = msg.get("reasoning") + if reasoning_text: + # Add reasoning_content for API compatibility (Moonshot AI, Novita, OpenRouter) + api_msg["reasoning_content"] = reasoning_text + + # Remove 'reasoning' field - it's for trajectory storage only + # We've copied it to 'reasoning_content' for the API above + if "reasoning" in api_msg: + api_msg.pop("reasoning") + # Remove finish_reason - not accepted by strict APIs (e.g. Mistral) + if "finish_reason" in api_msg: + api_msg.pop("finish_reason") + # Strip internal thinking-prefill marker + api_msg.pop("_thinking_prefill", None) + # Strip Codex Responses API fields (call_id, response_item_id) for + # strict providers like Mistral, Fireworks, etc. that reject unknown fields. + # Uses new dicts so the internal messages list retains the fields + # for Codex Responses compatibility. + if self._should_sanitize_tool_calls(): + self._sanitize_tool_calls_for_strict_api(api_msg) + # Keep 'reasoning_details' - OpenRouter uses this for multi-turn reasoning context + # The signature field helps maintain reasoning continuity + api_messages.append(api_msg) + + # Build the final system message: cached prompt + ephemeral system prompt. + # Ephemeral additions are API-call-time only (not persisted to session DB). + # External recall context is injected into the user message, not the system + # prompt, so the stable cache prefix remains unchanged. + effective_system = active_system_prompt or "" + if self.ephemeral_system_prompt: + effective_system = (effective_system + "\n\n" + self.ephemeral_system_prompt).strip() + # NOTE: Plugin context from pre_llm_call hooks is injected into the + # user message (see injection block above), NOT the system prompt. + # This is intentional — system prompt modifications break the prompt + # cache prefix. The system prompt is reserved for Hermes internals. + if effective_system: + api_messages = [{"role": "system", "content": effective_system}] + api_messages + + # Inject ephemeral prefill messages right after the system prompt + # but before conversation history. Same API-call-time-only pattern. + if self.prefill_messages: + sys_offset = 1 if effective_system else 0 + for idx, pfm in enumerate(self.prefill_messages): + api_messages.insert(sys_offset + idx, pfm.copy()) + + # Apply Anthropic prompt caching for Claude models via OpenRouter. + # Auto-detected: if model name contains "claude" and base_url is OpenRouter, + # inject cache_control breakpoints (system + last 3 messages) to reduce + # input token costs by ~75% on multi-turn conversations. + if self._use_prompt_caching: + api_messages = apply_anthropic_cache_control(api_messages, cache_ttl=self._cache_ttl, native_anthropic=(self.api_mode == 'anthropic_messages')) + + # Safety net: strip orphaned tool results / add stubs for missing + # results before sending to the API. Runs unconditionally — not + # gated on context_compressor — so orphans from session loading or + # manual message manipulation are always caught. + api_messages = self._sanitize_api_messages(api_messages) + + # Normalize message whitespace and tool-call JSON for consistent + # prefix matching. Ensures bit-perfect prefixes across turns, + # which enables KV cache reuse on local inference servers + # (llama.cpp, vLLM, Ollama) and improves cache hit rates for + # cloud providers. Operates on api_messages (the API copy) so + # the original conversation history in `messages` is untouched. + for am in api_messages: + if isinstance(am.get("content"), str): + am["content"] = am["content"].strip() + for am in api_messages: + tcs = am.get("tool_calls") + if not tcs: + continue + new_tcs = [] + for tc in tcs: + if isinstance(tc, dict) and "function" in tc: + try: + args_obj = json.loads(tc["function"]["arguments"]) + tc = {**tc, "function": { + **tc["function"], + "arguments": json.dumps( + args_obj, separators=(",", ":"), + sort_keys=True, + ), + }} + except Exception: + pass + new_tcs.append(tc) + am["tool_calls"] = new_tcs + + # Calculate approximate request size for logging + total_chars = sum(len(str(msg)) for msg in api_messages) + approx_tokens = estimate_messages_tokens_rough(api_messages) + + # Thinking spinner for quiet mode (animated during API call) + thinking_spinner = None + + if not self.quiet_mode: + self._vprint(f"\n{self.log_prefix}🔄 Making API call #{api_call_count}/{self.max_iterations}...") + self._vprint(f"{self.log_prefix} 📊 Request size: {len(api_messages)} messages, ~{approx_tokens:,} tokens (~{total_chars:,} chars)") + self._vprint(f"{self.log_prefix} 🔧 Available tools: {len(self.tools) if self.tools else 0}") + else: + # Animated thinking spinner in quiet mode + face = random.choice(KawaiiSpinner.KAWAII_THINKING) + verb = random.choice(KawaiiSpinner.THINKING_VERBS) + if self.thinking_callback: + # CLI TUI mode: use prompt_toolkit widget instead of raw spinner + # (works in both streaming and non-streaming modes) + self.thinking_callback(f"{face} {verb}...") + elif not self._has_stream_consumers() and self._should_start_quiet_spinner(): + # Raw KawaiiSpinner only when no streaming consumers and the + # spinner output has a safe sink. + spinner_type = random.choice(['brain', 'sparkle', 'pulse', 'moon', 'star']) + thinking_spinner = KawaiiSpinner(f"{face} {verb}...", spinner_type=spinner_type, print_fn=self._print_fn) + thinking_spinner.start() + + # Log request details if verbose + if self.verbose_logging: + logging.debug(f"API Request - Model: {self.model}, Messages: {len(messages)}, Tools: {len(self.tools) if self.tools else 0}") + logging.debug(f"Last message role: {messages[-1]['role'] if messages else 'none'}") + logging.debug(f"Total message size: ~{approx_tokens:,} tokens") + + api_start_time = time.time() + retry_count = 0 + max_retries = 3 + primary_recovery_attempted = False + max_compression_attempts = 3 + codex_auth_retry_attempted=False + anthropic_auth_retry_attempted=False + nous_auth_retry_attempted=False + thinking_sig_retry_attempted = False + has_retried_429 = False + restart_with_compressed_messages = False + restart_with_length_continuation = False + + finish_reason = "stop" + response = None # Guard against UnboundLocalError if all retries fail + api_kwargs = None # Guard against UnboundLocalError in except handler + + while retry_count < max_retries: + try: + self._reset_stream_delivery_tracking() + api_kwargs = self._build_api_kwargs(api_messages) + if self._force_ascii_payload: + _sanitize_structure_non_ascii(api_kwargs) + if self.api_mode == "codex_responses": + api_kwargs = self._preflight_codex_api_kwargs(api_kwargs, allow_stream=False) + + try: + from hermes_cli.plugins import invoke_hook as _invoke_hook + _invoke_hook( + "pre_api_request", + task_id=effective_task_id, + session_id=self.session_id or "", + platform=self.platform or "", + model=self.model, + provider=self.provider, + base_url=self.base_url, + api_mode=self.api_mode, + api_call_count=api_call_count, + message_count=len(api_messages), + tool_count=len(self.tools or []), + approx_input_tokens=approx_tokens, + request_char_count=total_chars, + max_tokens=self.max_tokens, + ) + except Exception: + pass + + if env_var_enabled("HERMES_DUMP_REQUESTS"): + self._dump_api_request_debug(api_kwargs, reason="preflight") + + # Always prefer the streaming path — even without stream + # consumers. Streaming gives us fine-grained health + # checking (90s stale-stream detection, 60s read timeout) + # that the non-streaming path lacks. Without this, + # subagents and other quiet-mode callers can hang + # indefinitely when the provider keeps the connection + # alive with SSE pings but never delivers a response. + # The streaming path is a no-op for callbacks when no + # consumers are registered, and falls back to non- + # streaming automatically if the provider doesn't + # support it. + def _stop_spinner(): + nonlocal thinking_spinner + if thinking_spinner: + thinking_spinner.stop("") + thinking_spinner = None + if self.thinking_callback: + self.thinking_callback("") + + _use_streaming = True + # Provider signaled "stream not supported" on a previous + # attempt — switch to non-streaming for the rest of this + # session instead of re-failing every retry. + if getattr(self, "_disable_streaming", False): + _use_streaming = False + elif not self._has_stream_consumers(): + # No display/TTS consumer. Still prefer streaming for + # health checking, but skip for Mock clients in tests + # (mocks return SimpleNamespace, not stream iterators). + from unittest.mock import Mock + if isinstance(getattr(self, "client", None), Mock): + _use_streaming = False + + if _use_streaming: + response = self._interruptible_streaming_api_call( + api_kwargs, on_first_delta=_stop_spinner + ) + else: + response = self._interruptible_api_call(api_kwargs) + + api_duration = time.time() - api_start_time + + # Stop thinking spinner silently -- the response box or tool + # execution messages that follow are more informative. + if thinking_spinner: + thinking_spinner.stop("") + thinking_spinner = None + if self.thinking_callback: + self.thinking_callback("") + + if not self.quiet_mode: + self._vprint(f"{self.log_prefix}⏱️ API call completed in {api_duration:.2f}s") + + if self.verbose_logging: + # Log response with provider info if available + resp_model = getattr(response, 'model', 'N/A') if response else 'N/A' + logging.debug(f"API Response received - Model: {resp_model}, Usage: {response.usage if hasattr(response, 'usage') else 'N/A'}") + + # Validate response shape before proceeding + response_invalid = False + error_details = [] + if self.api_mode == "codex_responses": + output_items = getattr(response, "output", None) if response is not None else None + if response is None: + response_invalid = True + error_details.append("response is None") + elif not isinstance(output_items, list): + response_invalid = True + error_details.append("response.output is not a list") + elif not output_items: + # Stream backfill may have failed, but + # _normalize_codex_response can still recover + # from response.output_text. Only mark invalid + # when that fallback is also absent. + _out_text = getattr(response, "output_text", None) + _out_text_stripped = _out_text.strip() if isinstance(_out_text, str) else "" + if _out_text_stripped: + logger.debug( + "Codex response.output is empty but output_text is present " + "(%d chars); deferring to normalization.", + len(_out_text_stripped), + ) + else: + _resp_status = getattr(response, "status", None) + _resp_incomplete = getattr(response, "incomplete_details", None) + logger.warning( + "Codex response.output is empty after stream backfill " + "(status=%s, incomplete_details=%s, model=%s). %s", + _resp_status, _resp_incomplete, + getattr(response, "model", None), + f"api_mode={self.api_mode} provider={self.provider}", + ) + response_invalid = True + error_details.append("response.output is empty") + elif self.api_mode == "anthropic_messages": + content_blocks = getattr(response, "content", None) if response is not None else None + if response is None: + response_invalid = True + error_details.append("response is None") + elif not isinstance(content_blocks, list): + response_invalid = True + error_details.append("response.content is not a list") + elif not content_blocks: + response_invalid = True + error_details.append("response.content is empty") + else: + if response is None or not hasattr(response, 'choices') or response.choices is None or not response.choices: + response_invalid = True + if response is None: + error_details.append("response is None") + elif not hasattr(response, 'choices'): + error_details.append("response has no 'choices' attribute") + elif response.choices is None: + error_details.append("response.choices is None") + else: + error_details.append("response.choices is empty") + + if response_invalid: + # Stop spinner before printing error messages + if thinking_spinner: + thinking_spinner.stop("(´;ω;`) oops, retrying...") + thinking_spinner = None + if self.thinking_callback: + self.thinking_callback("") + + # Invalid response — could be rate limiting, provider timeout, + # upstream server error, or malformed response. + retry_count += 1 + + # Eager fallback: empty/malformed responses are a common + # rate-limit symptom. Switch to fallback immediately + # rather than retrying with extended backoff. + if self._fallback_index < len(self._fallback_chain): + self._emit_status("⚠️ Empty/malformed response — switching to fallback...") + if self._try_activate_fallback(): + retry_count = 0 + compression_attempts = 0 + primary_recovery_attempted = False + continue + + # Check for error field in response (some providers include this) + error_msg = "Unknown" + provider_name = "Unknown" + if response and hasattr(response, 'error') and response.error: + error_msg = str(response.error) + # Try to extract provider from error metadata + if hasattr(response.error, 'metadata') and response.error.metadata: + provider_name = response.error.metadata.get('provider_name', 'Unknown') + elif response and hasattr(response, 'message') and response.message: + error_msg = str(response.message) + + # Try to get provider from model field (OpenRouter often returns actual model used) + if provider_name == "Unknown" and response and hasattr(response, 'model') and response.model: + provider_name = f"model={response.model}" + + # Check for x-openrouter-provider or similar metadata + if provider_name == "Unknown" and response: + # Log all response attributes for debugging + resp_attrs = {k: str(v)[:100] for k, v in vars(response).items() if not k.startswith('_')} + if self.verbose_logging: + logging.debug(f"Response attributes for invalid response: {resp_attrs}") + + # Extract error code from response for contextual diagnostics + _resp_error_code = None + if response and hasattr(response, 'error') and response.error: + _code_raw = getattr(response.error, 'code', None) + if _code_raw is None and isinstance(response.error, dict): + _code_raw = response.error.get('code') + if _code_raw is not None: + try: + _resp_error_code = int(_code_raw) + except (TypeError, ValueError): + pass + + # Build a human-readable failure hint from the error code + # and response time, instead of always assuming rate limiting. + if _resp_error_code == 524: + _failure_hint = f"upstream provider timed out (Cloudflare 524, {api_duration:.0f}s)" + elif _resp_error_code == 504: + _failure_hint = f"upstream gateway timeout (504, {api_duration:.0f}s)" + elif _resp_error_code == 429: + _failure_hint = f"rate limited by upstream provider (429)" + elif _resp_error_code in (500, 502): + _failure_hint = f"upstream server error ({_resp_error_code}, {api_duration:.0f}s)" + elif _resp_error_code in (503, 529): + _failure_hint = f"upstream provider overloaded ({_resp_error_code})" + elif _resp_error_code is not None: + _failure_hint = f"upstream error (code {_resp_error_code}, {api_duration:.0f}s)" + elif api_duration < 10: + _failure_hint = f"fast response ({api_duration:.1f}s) — likely rate limited" + elif api_duration > 60: + _failure_hint = f"slow response ({api_duration:.0f}s) — likely upstream timeout" + else: + _failure_hint = f"response time {api_duration:.1f}s" + + self._vprint(f"{self.log_prefix}⚠️ Invalid API response (attempt {retry_count}/{max_retries}): {', '.join(error_details)}", force=True) + self._vprint(f"{self.log_prefix} 🏢 Provider: {provider_name}", force=True) + cleaned_provider_error = self._clean_error_message(error_msg) + self._vprint(f"{self.log_prefix} 📝 Provider message: {cleaned_provider_error}", force=True) + self._vprint(f"{self.log_prefix} ⏱️ {_failure_hint}", force=True) + + if retry_count >= max_retries: + # Try fallback before giving up + self._emit_status(f"⚠️ Max retries ({max_retries}) for invalid responses — trying fallback...") + if self._try_activate_fallback(): + retry_count = 0 + compression_attempts = 0 + primary_recovery_attempted = False + continue + self._emit_status(f"❌ Max retries ({max_retries}) exceeded for invalid responses. Giving up.") + logging.error(f"{self.log_prefix}Invalid API response after {max_retries} retries.") + self._persist_session(messages, conversation_history) + return { + "messages": messages, + "completed": False, + "api_calls": api_call_count, + "error": f"Invalid API response after {max_retries} retries: {_failure_hint}", + "failed": True # Mark as failure for filtering + } + + # Backoff before retry — jittered exponential: 5s base, 120s cap + wait_time = jittered_backoff(retry_count, base_delay=5.0, max_delay=120.0) + self._vprint(f"{self.log_prefix}⏳ Retrying in {wait_time:.1f}s ({_failure_hint})...", force=True) + logging.warning(f"Invalid API response (retry {retry_count}/{max_retries}): {', '.join(error_details)} | Provider: {provider_name}") + + # Sleep in small increments to stay responsive to interrupts + sleep_end = time.time() + wait_time + _backoff_touch_counter = 0 + while time.time() < sleep_end: + if self._interrupt_requested: + self._vprint(f"{self.log_prefix}⚡ Interrupt detected during retry wait, aborting.", force=True) + self._persist_session(messages, conversation_history) + self.clear_interrupt() + return { + "final_response": f"Operation interrupted during retry ({_failure_hint}, attempt {retry_count}/{max_retries}).", + "messages": messages, + "api_calls": api_call_count, + "completed": False, + "interrupted": True, + } + time.sleep(0.2) + # Touch activity every ~30s so the gateway's inactivity + # monitor knows we're alive during backoff waits. + _backoff_touch_counter += 1 + if _backoff_touch_counter % 150 == 0: # 150 × 0.2s = 30s + self._touch_activity( + f"retry backoff ({retry_count}/{max_retries}), " + f"{int(sleep_end - time.time())}s remaining" + ) + continue # Retry the API call + + # Check finish_reason before proceeding + if self.api_mode == "codex_responses": + status = getattr(response, "status", None) + incomplete_details = getattr(response, "incomplete_details", None) + incomplete_reason = None + if isinstance(incomplete_details, dict): + incomplete_reason = incomplete_details.get("reason") + else: + incomplete_reason = getattr(incomplete_details, "reason", None) + if status == "incomplete" and incomplete_reason in {"max_output_tokens", "length"}: + finish_reason = "length" + else: + finish_reason = "stop" + elif self.api_mode == "anthropic_messages": + stop_reason_map = {"end_turn": "stop", "tool_use": "tool_calls", "max_tokens": "length", "stop_sequence": "stop"} + finish_reason = stop_reason_map.get(response.stop_reason, "stop") + else: + finish_reason = response.choices[0].finish_reason + + if finish_reason == "length": + self._vprint(f"{self.log_prefix}⚠️ Response truncated (finish_reason='length') - model hit max output tokens", force=True) + + # ── Detect thinking-budget exhaustion ────────────── + # When the model spends ALL output tokens on reasoning + # and has none left for the response, continuation + # retries are pointless. Detect this early and give a + # targeted error instead of wasting 3 API calls. + _trunc_content = None + _trunc_has_tool_calls = False + if self.api_mode == "chat_completions": + _trunc_msg = response.choices[0].message if (hasattr(response, "choices") and response.choices) else None + _trunc_content = getattr(_trunc_msg, "content", None) if _trunc_msg else None + _trunc_has_tool_calls = bool(getattr(_trunc_msg, "tool_calls", None)) if _trunc_msg else False + elif self.api_mode == "anthropic_messages": + # Anthropic response.content is a list of blocks + _text_parts = [] + for _blk in getattr(response, "content", []): + if getattr(_blk, "type", None) == "text": + _text_parts.append(getattr(_blk, "text", "")) + _trunc_content = "\n".join(_text_parts) if _text_parts else None + + # A response is "thinking exhausted" only when the model + # actually produced reasoning blocks but no visible text after + # them. Models that do not use tags (e.g. GLM-4.7 on + # NVIDIA Build, minimax) may return content=None or an empty + # string for unrelated reasons — treat those as normal + # truncations that deserve continuation retries, not as + # thinking-budget exhaustion. + _has_think_tags = bool( + _trunc_content and re.search( + r'<(?:think|thinking|reasoning|REASONING_SCRATCHPAD)[^>]*>', + _trunc_content, + re.IGNORECASE, + ) + ) + _thinking_exhausted = ( + not _trunc_has_tool_calls + and _has_think_tags + and ( + (_trunc_content is not None and not self._has_content_after_think_block(_trunc_content)) + or _trunc_content is None + ) + ) + + if _thinking_exhausted: + _exhaust_error = ( + "Model used all output tokens on reasoning with none left " + "for the response. Try lowering reasoning effort or " + "increasing max_tokens." + ) + self._vprint( + f"{self.log_prefix}💭 Reasoning exhausted the output token budget — " + f"no visible response was produced.", + force=True, + ) + # Return a user-friendly message as the response so + # CLI (response box) and gateway (chat message) both + # display it naturally instead of a suppressed error. + _exhaust_response = ( + "⚠️ **Thinking Budget Exhausted**\n\n" + "The model used all its output tokens on reasoning " + "and had none left for the actual response.\n\n" + "To fix this:\n" + "→ Lower reasoning effort: `/thinkon low` or `/thinkon minimal`\n" + "→ Increase the output token limit: " + "set `model.max_tokens` in config.yaml" + ) + self._cleanup_task_resources(effective_task_id) + self._persist_session(messages, conversation_history) + return { + "final_response": _exhaust_response, + "messages": messages, + "api_calls": api_call_count, + "completed": False, + "partial": True, + "error": _exhaust_error, + } + + if self.api_mode == "chat_completions": + assistant_message = response.choices[0].message + if not assistant_message.tool_calls: + length_continue_retries += 1 + interim_msg = self._build_assistant_message(assistant_message, finish_reason) + messages.append(interim_msg) + if assistant_message.content: + truncated_response_prefix += assistant_message.content + + if length_continue_retries < 3: + self._vprint( + f"{self.log_prefix}↻ Requesting continuation " + f"({length_continue_retries}/3)..." + ) + continue_msg = { + "role": "user", + "content": ( + "[System: Your previous response was truncated by the output " + "length limit. Continue exactly where you left off. Do not " + "restart or repeat prior text. Finish the answer directly.]" + ), + } + messages.append(continue_msg) + self._session_messages = messages + self._save_session_log(messages) + restart_with_length_continuation = True + break + + partial_response = self._strip_think_blocks(truncated_response_prefix).strip() + self._cleanup_task_resources(effective_task_id) + self._persist_session(messages, conversation_history) + return { + "final_response": partial_response or None, + "messages": messages, + "api_calls": api_call_count, + "completed": False, + "partial": True, + "error": "Response remained truncated after 3 continuation attempts", + } + + if self.api_mode == "chat_completions": + assistant_message = response.choices[0].message + if assistant_message.tool_calls: + if truncated_tool_call_retries < 1: + truncated_tool_call_retries += 1 + self._vprint( + f"{self.log_prefix}⚠️ Truncated tool call detected — retrying API call...", + force=True, + ) + # Don't append the broken response to messages; + # just re-run the same API call from the current + # message state, giving the model another chance. + continue + self._vprint( + f"{self.log_prefix}⚠️ Truncated tool call response detected again — refusing to execute incomplete tool arguments.", + force=True, + ) + self._cleanup_task_resources(effective_task_id) + self._persist_session(messages, conversation_history) + return { + "final_response": None, + "messages": messages, + "api_calls": api_call_count, + "completed": False, + "partial": True, + "error": "Response truncated due to output length limit", + } + + # If we have prior messages, roll back to last complete state + if len(messages) > 1: + self._vprint(f"{self.log_prefix} ⏪ Rolling back to last complete assistant turn") + rolled_back_messages = self._get_messages_up_to_last_assistant(messages) + + self._cleanup_task_resources(effective_task_id) + self._persist_session(messages, conversation_history) + + return { + "final_response": None, + "messages": rolled_back_messages, + "api_calls": api_call_count, + "completed": False, + "partial": True, + "error": "Response truncated due to output length limit" + } + else: + # First message was truncated - mark as failed + self._vprint(f"{self.log_prefix}❌ First response truncated - cannot recover", force=True) + self._persist_session(messages, conversation_history) + return { + "final_response": None, + "messages": messages, + "api_calls": api_call_count, + "completed": False, + "failed": True, + "error": "First response truncated due to output length limit" + } + + # Track actual token usage from response for context management + if hasattr(response, 'usage') and response.usage: + canonical_usage = normalize_usage( + response.usage, + provider=self.provider, + api_mode=self.api_mode, + ) + prompt_tokens = canonical_usage.prompt_tokens + completion_tokens = canonical_usage.output_tokens + total_tokens = canonical_usage.total_tokens + usage_dict = { + "prompt_tokens": prompt_tokens, + "completion_tokens": completion_tokens, + "total_tokens": total_tokens, + } + self.context_compressor.update_from_response(usage_dict) + + # Cache discovered context length after successful call. + # Only persist limits confirmed by the provider (parsed + # from the error message), not guessed probe tiers. + if getattr(self.context_compressor, "_context_probed", False): + ctx = self.context_compressor.context_length + if getattr(self.context_compressor, "_context_probe_persistable", False): + save_context_length(self.model, self.base_url, ctx) + self._safe_print(f"{self.log_prefix}💾 Cached context length: {ctx:,} tokens for {self.model}") + self.context_compressor._context_probed = False + self.context_compressor._context_probe_persistable = False + + self.session_prompt_tokens += prompt_tokens + self.session_completion_tokens += completion_tokens + self.session_total_tokens += total_tokens + self.session_api_calls += 1 + self.session_input_tokens += canonical_usage.input_tokens + self.session_output_tokens += canonical_usage.output_tokens + self.session_cache_read_tokens += canonical_usage.cache_read_tokens + self.session_cache_write_tokens += canonical_usage.cache_write_tokens + self.session_reasoning_tokens += canonical_usage.reasoning_tokens + + # Log API call details for debugging/observability + _cache_pct = "" + if canonical_usage.cache_read_tokens and prompt_tokens: + _cache_pct = f" cache={canonical_usage.cache_read_tokens}/{prompt_tokens} ({100*canonical_usage.cache_read_tokens/prompt_tokens:.0f}%)" + logger.info( + "API call #%d: model=%s provider=%s in=%d out=%d total=%d latency=%.1fs%s", + self.session_api_calls, self.model, self.provider or "unknown", + prompt_tokens, completion_tokens, total_tokens, + api_duration, _cache_pct, + ) + + cost_result = estimate_usage_cost( + self.model, + canonical_usage, + provider=self.provider, + base_url=self.base_url, + api_key=getattr(self, "api_key", ""), + ) + if cost_result.amount_usd is not None: + self.session_estimated_cost_usd += float(cost_result.amount_usd) + self.session_cost_status = cost_result.status + self.session_cost_source = cost_result.source + + # Persist token counts to session DB for /insights. + # Do this for every platform with a session_id so non-CLI + # sessions (gateway, cron, delegated runs) cannot lose + # token/accounting data if a higher-level persistence path + # is skipped or fails. Gateway/session-store writes use + # absolute totals, so they safely overwrite these per-call + # deltas instead of double-counting them. + if self._session_db and self.session_id: + try: + self._session_db.update_token_counts( + self.session_id, + input_tokens=canonical_usage.input_tokens, + output_tokens=canonical_usage.output_tokens, + cache_read_tokens=canonical_usage.cache_read_tokens, + cache_write_tokens=canonical_usage.cache_write_tokens, + reasoning_tokens=canonical_usage.reasoning_tokens, + estimated_cost_usd=float(cost_result.amount_usd) + if cost_result.amount_usd is not None else None, + cost_status=cost_result.status, + cost_source=cost_result.source, + billing_provider=self.provider, + billing_base_url=self.base_url, + billing_mode="subscription_included" + if cost_result.status == "included" else None, + model=self.model, + ) + except Exception: + pass # never block the agent loop + + if self.verbose_logging: + logging.debug(f"Token usage: prompt={usage_dict['prompt_tokens']:,}, completion={usage_dict['completion_tokens']:,}, total={usage_dict['total_tokens']:,}") + + # Log cache hit stats when prompt caching is active + if self._use_prompt_caching: + if self.api_mode == "anthropic_messages": + # Anthropic uses cache_read_input_tokens / cache_creation_input_tokens + cached = getattr(response.usage, 'cache_read_input_tokens', 0) or 0 + written = getattr(response.usage, 'cache_creation_input_tokens', 0) or 0 + else: + # OpenRouter uses prompt_tokens_details.cached_tokens + details = getattr(response.usage, 'prompt_tokens_details', None) + cached = getattr(details, 'cached_tokens', 0) or 0 if details else 0 + written = getattr(details, 'cache_write_tokens', 0) or 0 if details else 0 + prompt = usage_dict["prompt_tokens"] + hit_pct = (cached / prompt * 100) if prompt > 0 else 0 + if not self.quiet_mode: + self._vprint(f"{self.log_prefix} 💾 Cache: {cached:,}/{prompt:,} tokens ({hit_pct:.0f}% hit, {written:,} written)") + + has_retried_429 = False # Reset on success + self._touch_activity(f"API call #{api_call_count} completed") + break # Success, exit retry loop + + except InterruptedError: + if thinking_spinner: + thinking_spinner.stop("") + thinking_spinner = None + if self.thinking_callback: + self.thinking_callback("") + api_elapsed = time.time() - api_start_time + self._vprint(f"{self.log_prefix}⚡ Interrupted during API call.", force=True) + self._persist_session(messages, conversation_history) + interrupted = True + final_response = f"Operation interrupted: waiting for model response ({api_elapsed:.1f}s elapsed)." + break + + except Exception as api_error: + # Stop spinner before printing error messages + if thinking_spinner: + thinking_spinner.stop("(╥_╥) error, retrying...") + thinking_spinner = None + if self.thinking_callback: + self.thinking_callback("") + + # ----------------------------------------------------------- + # UnicodeEncodeError recovery. Two common causes: + # 1. Lone surrogates (U+D800..U+DFFF) from clipboard paste + # (Google Docs, rich-text editors) — sanitize and retry. + # 2. ASCII codec on systems with LANG=C or non-UTF-8 locale + # (e.g. Chromebooks) — any non-ASCII character fails. + # Detect via the error message mentioning 'ascii' codec. + # We sanitize messages in-place and may retry twice: + # first to strip surrogates, then once more for pure + # ASCII-only locale sanitization if needed. + # ----------------------------------------------------------- + if isinstance(api_error, UnicodeEncodeError) and getattr(self, '_unicode_sanitization_passes', 0) < 2: + _err_str = str(api_error).lower() + _is_ascii_codec = "'ascii'" in _err_str or "ascii" in _err_str + _surrogates_found = _sanitize_messages_surrogates(messages) + if _surrogates_found: + self._unicode_sanitization_passes += 1 + self._vprint( + f"{self.log_prefix}⚠️ Stripped invalid surrogate characters from messages. Retrying...", + force=True, + ) + continue + if _is_ascii_codec: + self._force_ascii_payload = True + # ASCII codec: the system encoding can't handle + # non-ASCII characters at all. Sanitize all + # non-ASCII content from messages/tool schemas and retry. + _messages_sanitized = _sanitize_messages_non_ascii(messages) + _prefill_sanitized = False + if isinstance(getattr(self, "prefill_messages", None), list): + _prefill_sanitized = _sanitize_messages_non_ascii(self.prefill_messages) + + _tools_sanitized = False + if isinstance(getattr(self, "tools", None), list): + _tools_sanitized = _sanitize_tools_non_ascii(self.tools) + + _system_sanitized = False + if isinstance(active_system_prompt, str): + _sanitized_system = _strip_non_ascii(active_system_prompt) + if _sanitized_system != active_system_prompt: + active_system_prompt = _sanitized_system + self._cached_system_prompt = _sanitized_system + _system_sanitized = True + if isinstance(getattr(self, "ephemeral_system_prompt", None), str): + _sanitized_ephemeral = _strip_non_ascii(self.ephemeral_system_prompt) + if _sanitized_ephemeral != self.ephemeral_system_prompt: + self.ephemeral_system_prompt = _sanitized_ephemeral + _system_sanitized = True + + _headers_sanitized = False + _default_headers = ( + self._client_kwargs.get("default_headers") + if isinstance(getattr(self, "_client_kwargs", None), dict) + else None + ) + if isinstance(_default_headers, dict): + _headers_sanitized = _sanitize_structure_non_ascii(_default_headers) + + if ( + _messages_sanitized + or _prefill_sanitized + or _tools_sanitized + or _system_sanitized + or _headers_sanitized + ): + self._unicode_sanitization_passes += 1 + self._vprint( + f"{self.log_prefix}⚠️ System encoding is ASCII — stripped non-ASCII characters from request payload. Retrying...", + force=True, + ) + continue + # Nothing to sanitize in any payload component. + # Fall through to normal error path. + + status_code = getattr(api_error, "status_code", None) + error_context = self._extract_api_error_context(api_error) + + # ── Classify the error for structured recovery decisions ── + _compressor = getattr(self, "context_compressor", None) + _ctx_len = getattr(_compressor, "context_length", 200000) if _compressor else 200000 + classified = classify_api_error( + api_error, + provider=getattr(self, "provider", "") or "", + model=getattr(self, "model", "") or "", + approx_tokens=approx_tokens, + context_length=_ctx_len, + num_messages=len(api_messages) if api_messages else 0, + ) + logger.debug( + "Error classified: reason=%s status=%s retryable=%s compress=%s rotate=%s fallback=%s", + classified.reason.value, classified.status_code, + classified.retryable, classified.should_compress, + classified.should_rotate_credential, classified.should_fallback, + ) + + recovered_with_pool, has_retried_429 = self._recover_with_credential_pool( + status_code=status_code, + has_retried_429=has_retried_429, + classified_reason=classified.reason, + error_context=error_context, + ) + if recovered_with_pool: + continue + if ( + self.api_mode == "codex_responses" + and self.provider == "openai-codex" + and status_code == 401 + and not codex_auth_retry_attempted + ): + codex_auth_retry_attempted = True + if self._try_refresh_codex_client_credentials(force=True): + self._vprint(f"{self.log_prefix}🔐 Codex auth refreshed after 401. Retrying request...") + continue + if ( + self.api_mode == "chat_completions" + and self.provider == "nous" + and status_code == 401 + and not nous_auth_retry_attempted + ): + nous_auth_retry_attempted = True + if self._try_refresh_nous_client_credentials(force=True): + print(f"{self.log_prefix}🔐 Nous agent key refreshed after 401. Retrying request...") + continue + if ( + self.api_mode == "anthropic_messages" + and status_code == 401 + and hasattr(self, '_anthropic_api_key') + and not anthropic_auth_retry_attempted + ): + anthropic_auth_retry_attempted = True + from agent.anthropic_adapter import _is_oauth_token + if self._try_refresh_anthropic_client_credentials(): + print(f"{self.log_prefix}🔐 Anthropic credentials refreshed after 401. Retrying request...") + continue + # Credential refresh didn't help — show diagnostic info + key = self._anthropic_api_key + auth_method = "Bearer (OAuth/setup-token)" if _is_oauth_token(key) else "x-api-key (API key)" + print(f"{self.log_prefix}🔐 Anthropic 401 — authentication failed.") + print(f"{self.log_prefix} Auth method: {auth_method}") + print(f"{self.log_prefix} Token prefix: {key[:12]}..." if key and len(key) > 12 else f"{self.log_prefix} Token: (empty or short)") + print(f"{self.log_prefix} Troubleshooting:") + from hermes_constants import display_hermes_home as _dhh_fn + _dhh = _dhh_fn() + print(f"{self.log_prefix} • Check ANTHROPIC_TOKEN in {_dhh}/.env for Hermes-managed OAuth/setup tokens") + print(f"{self.log_prefix} • Check ANTHROPIC_API_KEY in {_dhh}/.env for API keys or legacy token values") + print(f"{self.log_prefix} • For API keys: verify at https://console.anthropic.com/settings/keys") + print(f"{self.log_prefix} • For Claude Code: run 'claude /login' to refresh, then retry") + print(f"{self.log_prefix} • Legacy cleanup: hermes config set ANTHROPIC_TOKEN \"\"") + print(f"{self.log_prefix} • Clear stale keys: hermes config set ANTHROPIC_API_KEY \"\"") + + # ── Thinking block signature recovery ───────────────── + # Anthropic signs thinking blocks against the full turn + # content. Any upstream mutation (context compression, + # session truncation, message merging) invalidates the + # signature → HTTP 400. Recovery: strip reasoning_details + # from all messages so the next retry sends no thinking + # blocks at all. One-shot — don't retry infinitely. + if ( + classified.reason == FailoverReason.thinking_signature + and not thinking_sig_retry_attempted + ): + thinking_sig_retry_attempted = True + for _m in messages: + if isinstance(_m, dict): + _m.pop("reasoning_details", None) + self._vprint( + f"{self.log_prefix}⚠️ Thinking block signature invalid — " + f"stripped all thinking blocks, retrying...", + force=True, + ) + logging.warning( + "%sThinking block signature recovery: stripped " + "reasoning_details from %d messages", + self.log_prefix, len(messages), + ) + continue + + retry_count += 1 + elapsed_time = time.time() - api_start_time + self._touch_activity( + f"API error recovery (attempt {retry_count}/{max_retries})" + ) + + error_type = type(api_error).__name__ + error_msg = str(api_error).lower() + _error_summary = self._summarize_api_error(api_error) + logger.warning( + "API call failed (attempt %s/%s) error_type=%s %s summary=%s", + retry_count, + max_retries, + error_type, + self._client_log_context(), + _error_summary, + ) + + _provider = getattr(self, "provider", "unknown") + _base = getattr(self, "base_url", "unknown") + _model = getattr(self, "model", "unknown") + _status_code_str = f" [HTTP {status_code}]" if status_code else "" + self._vprint(f"{self.log_prefix}⚠️ API call failed (attempt {retry_count}/{max_retries}): {error_type}{_status_code_str}", force=True) + self._vprint(f"{self.log_prefix} 🔌 Provider: {_provider} Model: {_model}", force=True) + self._vprint(f"{self.log_prefix} 🌐 Endpoint: {_base}", force=True) + self._vprint(f"{self.log_prefix} 📝 Error: {_error_summary}", force=True) + if status_code and status_code < 500: + _err_body = getattr(api_error, "body", None) + _err_body_str = str(_err_body)[:300] if _err_body else None + if _err_body_str: + self._vprint(f"{self.log_prefix} 📋 Details: {_err_body_str}", force=True) + self._vprint(f"{self.log_prefix} ⏱️ Elapsed: {elapsed_time:.2f}s Context: {len(api_messages)} msgs, ~{approx_tokens:,} tokens") + + # Actionable hint for OpenRouter "no tool endpoints" error. + # This fires regardless of whether fallback succeeds — the + # user needs to know WHY their model failed so they can fix + # their provider routing, not just silently fall back. + if ( + self._is_openrouter_url() + and "support tool use" in error_msg + ): + self._vprint( + f"{self.log_prefix} 💡 No OpenRouter providers for {_model} support tool calling with your current settings.", + force=True, + ) + if self.providers_allowed: + self._vprint( + f"{self.log_prefix} Your provider_routing.only restriction is filtering out tool-capable providers.", + force=True, + ) + self._vprint( + f"{self.log_prefix} Try removing the restriction or adding providers that support tools for this model.", + force=True, + ) + self._vprint( + f"{self.log_prefix} Check which providers support tools: https://openrouter.ai/models/{_model}", + force=True, + ) + + # Check for interrupt before deciding to retry + if self._interrupt_requested: + self._vprint(f"{self.log_prefix}⚡ Interrupt detected during error handling, aborting retries.", force=True) + self._persist_session(messages, conversation_history) + self.clear_interrupt() + return { + "final_response": f"Operation interrupted: handling API error ({error_type}: {self._clean_error_message(str(api_error))}).", + "messages": messages, + "api_calls": api_call_count, + "completed": False, + "interrupted": True, + } + + # Check for 413 payload-too-large BEFORE generic 4xx handler. + # A 413 is a payload-size error — the correct response is to + # compress history and retry, not abort immediately. + status_code = getattr(api_error, "status_code", None) + + # ── Anthropic Sonnet long-context tier gate ─────────── + # Anthropic returns HTTP 429 "Extra usage is required for + # long context requests" when a Claude Max (or similar) + # subscription doesn't include the 1M-context tier. This + # is NOT a transient rate limit — retrying or switching + # credentials won't help. Reduce context to 200k (the + # standard tier) and compress. + if classified.reason == FailoverReason.long_context_tier: + _reduced_ctx = 200000 + compressor = self.context_compressor + old_ctx = compressor.context_length + if old_ctx > _reduced_ctx: + compressor.update_model( + model=self.model, + context_length=_reduced_ctx, + base_url=self.base_url, + api_key=getattr(self, "api_key", ""), + provider=self.provider, + ) + # Context probing flags — only set on built-in + # compressor (plugin engines manage their own). + if hasattr(compressor, "_context_probed"): + compressor._context_probed = True + # Don't persist — this is a subscription-tier + # limitation, not a model capability. If the + # user later enables extra usage the 1M limit + # should come back automatically. + compressor._context_probe_persistable = False + self._vprint( + f"{self.log_prefix}⚠️ Anthropic long-context tier " + f"requires extra usage — reducing context: " + f"{old_ctx:,} → {_reduced_ctx:,} tokens", + force=True, + ) + + compression_attempts += 1 + if compression_attempts <= max_compression_attempts: + original_len = len(messages) + messages, active_system_prompt = self._compress_context( + messages, system_message, + approx_tokens=approx_tokens, + task_id=effective_task_id, + ) + # Compression created a new session — clear history + # so _flush_messages_to_session_db writes compressed + # messages to the new session, not skipping them. + conversation_history = None + if len(messages) < original_len or old_ctx > _reduced_ctx: + self._emit_status( + f"🗜️ Context reduced to {_reduced_ctx:,} tokens " + f"(was {old_ctx:,}), retrying..." + ) + time.sleep(2) + restart_with_compressed_messages = True + break + # Fall through to normal error handling if compression + # is exhausted or didn't help. + + # Eager fallback for rate-limit errors (429 or quota exhaustion). + # When a fallback model is configured, switch immediately instead + # of burning through retries with exponential backoff -- the + # primary provider won't recover within the retry window. + is_rate_limited = classified.reason in ( + FailoverReason.rate_limit, + FailoverReason.billing, + ) + if is_rate_limited and self._fallback_index < len(self._fallback_chain): + # Don't eagerly fallback if credential pool rotation may + # still recover. The pool's retry-then-rotate cycle needs + # at least one more attempt to fire — jumping to a fallback + # provider here short-circuits it. + pool = self._credential_pool + pool_may_recover = pool is not None and pool.has_available() + if not pool_may_recover: + self._emit_status("⚠️ Rate limited — switching to fallback provider...") + if self._try_activate_fallback(): + retry_count = 0 + compression_attempts = 0 + primary_recovery_attempted = False + continue + + is_payload_too_large = ( + classified.reason == FailoverReason.payload_too_large + ) + + if is_payload_too_large: + compression_attempts += 1 + if compression_attempts > max_compression_attempts: + self._vprint(f"{self.log_prefix}❌ Max compression attempts ({max_compression_attempts}) reached for payload-too-large error.", force=True) + self._vprint(f"{self.log_prefix} 💡 Try /new to start a fresh conversation, or /compress to retry compression.", force=True) + logging.error(f"{self.log_prefix}413 compression failed after {max_compression_attempts} attempts.") + self._persist_session(messages, conversation_history) + return { + "messages": messages, + "completed": False, + "api_calls": api_call_count, + "error": f"Request payload too large: max compression attempts ({max_compression_attempts}) reached.", + "partial": True + } + self._emit_status(f"⚠️ Request payload too large (413) — compression attempt {compression_attempts}/{max_compression_attempts}...") + + original_len = len(messages) + messages, active_system_prompt = self._compress_context( + messages, system_message, approx_tokens=approx_tokens, + task_id=effective_task_id, + ) + # Compression created a new session — clear history + # so _flush_messages_to_session_db writes compressed + # messages to the new session, not skipping them. + conversation_history = None + + if len(messages) < original_len: + self._emit_status(f"🗜️ Compressed {original_len} → {len(messages)} messages, retrying...") + time.sleep(2) # Brief pause between compression retries + restart_with_compressed_messages = True + break + else: + self._vprint(f"{self.log_prefix}❌ Payload too large and cannot compress further.", force=True) + self._vprint(f"{self.log_prefix} 💡 Try /new to start a fresh conversation, or /compress to retry compression.", force=True) + logging.error(f"{self.log_prefix}413 payload too large. Cannot compress further.") + self._persist_session(messages, conversation_history) + return { + "messages": messages, + "completed": False, + "api_calls": api_call_count, + "error": "Request payload too large (413). Cannot compress further.", + "partial": True + } + + # Check for context-length errors BEFORE generic 4xx handler. + # The classifier detects context overflow from: explicit error + # messages, generic 400 + large session heuristic (#1630), and + # server disconnect + large session pattern (#2153). + is_context_length_error = ( + classified.reason == FailoverReason.context_overflow + ) + + if is_context_length_error: + compressor = self.context_compressor + old_ctx = compressor.context_length + + # ── Distinguish two very different errors ─────────── + # 1. "Prompt too long": the INPUT exceeds the context window. + # Fix: reduce context_length + compress history. + # 2. "max_tokens too large": input is fine, but + # input_tokens + requested max_tokens > context_window. + # Fix: reduce max_tokens (the OUTPUT cap) for this call. + # Do NOT shrink context_length — the window is unchanged. + # + # Note: max_tokens = output token cap (one response). + # context_length = total window (input + output combined). + available_out = parse_available_output_tokens_from_error(error_msg) + if available_out is not None: + # Error is purely about the output cap being too large. + # Cap output to the available space and retry without + # touching context_length or triggering compression. + safe_out = max(1, available_out - 64) # small safety margin + self._ephemeral_max_output_tokens = safe_out + self._vprint( + f"{self.log_prefix}⚠️ Output cap too large for current prompt — " + f"retrying with max_tokens={safe_out:,} " + f"(available_tokens={available_out:,}; context_length unchanged at {old_ctx:,})", + force=True, + ) + # Still count against compression_attempts so we don't + # loop forever if the error keeps recurring. + compression_attempts += 1 + if compression_attempts > max_compression_attempts: + self._vprint(f"{self.log_prefix}❌ Max compression attempts ({max_compression_attempts}) reached.", force=True) + self._vprint(f"{self.log_prefix} 💡 Try /new to start a fresh conversation, or /compress to retry compression.", force=True) + logging.error(f"{self.log_prefix}Context compression failed after {max_compression_attempts} attempts.") + self._persist_session(messages, conversation_history) + return { + "messages": messages, + "completed": False, + "api_calls": api_call_count, + "error": f"Context length exceeded: max compression attempts ({max_compression_attempts}) reached.", + "partial": True + } + restart_with_compressed_messages = True + break + + # Error is about the INPUT being too large — reduce context_length. + # Try to parse the actual limit from the error message + parsed_limit = parse_context_limit_from_error(error_msg) + if parsed_limit and parsed_limit < old_ctx: + new_ctx = parsed_limit + self._vprint(f"{self.log_prefix}⚠️ Context limit detected from API: {new_ctx:,} tokens (was {old_ctx:,})", force=True) + else: + # Step down to the next probe tier + new_ctx = get_next_probe_tier(old_ctx) + + if new_ctx and new_ctx < old_ctx: + compressor.update_model( + model=self.model, + context_length=new_ctx, + base_url=self.base_url, + api_key=getattr(self, "api_key", ""), + provider=self.provider, + ) + # Context probing flags — only set on built-in + # compressor (plugin engines manage their own). + if hasattr(compressor, "_context_probed"): + compressor._context_probed = True + # Only persist limits parsed from the provider's + # error message (a real number). Guessed fallback + # tiers from get_next_probe_tier() should stay + # in-memory only — persisting them pollutes the + # cache with wrong values. + compressor._context_probe_persistable = bool( + parsed_limit and parsed_limit == new_ctx + ) + self._vprint(f"{self.log_prefix}⚠️ Context length exceeded — stepping down: {old_ctx:,} → {new_ctx:,} tokens", force=True) + else: + self._vprint(f"{self.log_prefix}⚠️ Context length exceeded at minimum tier — attempting compression...", force=True) + + compression_attempts += 1 + if compression_attempts > max_compression_attempts: + self._vprint(f"{self.log_prefix}❌ Max compression attempts ({max_compression_attempts}) reached.", force=True) + self._vprint(f"{self.log_prefix} 💡 Try /new to start a fresh conversation, or /compress to retry compression.", force=True) + logging.error(f"{self.log_prefix}Context compression failed after {max_compression_attempts} attempts.") + self._persist_session(messages, conversation_history) + return { + "messages": messages, + "completed": False, + "api_calls": api_call_count, + "error": f"Context length exceeded: max compression attempts ({max_compression_attempts}) reached.", + "partial": True + } + self._emit_status(f"🗜️ Context too large (~{approx_tokens:,} tokens) — compressing ({compression_attempts}/{max_compression_attempts})...") + + original_len = len(messages) + messages, active_system_prompt = self._compress_context( + messages, system_message, approx_tokens=approx_tokens, + task_id=effective_task_id, + ) + # Compression created a new session — clear history + # so _flush_messages_to_session_db writes compressed + # messages to the new session, not skipping them. + conversation_history = None + + if len(messages) < original_len or new_ctx and new_ctx < old_ctx: + if len(messages) < original_len: + self._emit_status(f"🗜️ Compressed {original_len} → {len(messages)} messages, retrying...") + time.sleep(2) # Brief pause between compression retries + restart_with_compressed_messages = True + break + else: + # Can't compress further and already at minimum tier + self._vprint(f"{self.log_prefix}❌ Context length exceeded and cannot compress further.", force=True) + self._vprint(f"{self.log_prefix} 💡 The conversation has accumulated too much content. Try /new to start fresh, or /compress to manually trigger compression.", force=True) + logging.error(f"{self.log_prefix}Context length exceeded: {approx_tokens:,} tokens. Cannot compress further.") + self._persist_session(messages, conversation_history) + return { + "messages": messages, + "completed": False, + "api_calls": api_call_count, + "error": f"Context length exceeded ({approx_tokens:,} tokens). Cannot compress further.", + "partial": True + } + + # Check for non-retryable client errors. The classifier + # already accounts for 413, 429, 529 (transient), context + # overflow, and generic-400 heuristics. Local validation + # errors (ValueError, TypeError) are programming bugs. + is_local_validation_error = ( + isinstance(api_error, (ValueError, TypeError)) + and not isinstance(api_error, UnicodeEncodeError) + ) + is_client_error = ( + is_local_validation_error + or ( + not classified.retryable + and not classified.should_compress + and classified.reason not in ( + FailoverReason.rate_limit, + FailoverReason.billing, + FailoverReason.overloaded, + FailoverReason.context_overflow, + FailoverReason.payload_too_large, + FailoverReason.long_context_tier, + FailoverReason.thinking_signature, + ) + ) + ) and not is_context_length_error + + if is_client_error: + # Try fallback before aborting — a different provider + # may not have the same issue (rate limit, auth, etc.) + self._emit_status(f"⚠️ Non-retryable error (HTTP {status_code}) — trying fallback...") + if self._try_activate_fallback(): + retry_count = 0 + compression_attempts = 0 + primary_recovery_attempted = False + continue + if api_kwargs is not None: + self._dump_api_request_debug( + api_kwargs, reason="non_retryable_client_error", error=api_error, + ) + self._emit_status( + f"❌ Non-retryable error (HTTP {status_code}): " + f"{self._summarize_api_error(api_error)}" + ) + self._vprint(f"{self.log_prefix}❌ Non-retryable client error (HTTP {status_code}). Aborting.", force=True) + self._vprint(f"{self.log_prefix} 🔌 Provider: {_provider} Model: {_model}", force=True) + self._vprint(f"{self.log_prefix} 🌐 Endpoint: {_base}", force=True) + # Actionable guidance for common auth errors + if classified.is_auth or classified.reason == FailoverReason.billing: + if _provider == "openai-codex" and status_code == 401: + self._vprint(f"{self.log_prefix} 💡 Codex OAuth token was rejected (HTTP 401). Your token may have been", force=True) + self._vprint(f"{self.log_prefix} refreshed by another client (Codex CLI, VS Code). To fix:", force=True) + self._vprint(f"{self.log_prefix} 1. Run `codex` in your terminal to generate fresh tokens.", force=True) + self._vprint(f"{self.log_prefix} 2. Then run `hermes auth` to re-authenticate.", force=True) + else: + self._vprint(f"{self.log_prefix} 💡 Your API key was rejected by the provider. Check:", force=True) + self._vprint(f"{self.log_prefix} • Is the key valid? Run: hermes setup", force=True) + self._vprint(f"{self.log_prefix} • Does your account have access to {_model}?", force=True) + if "openrouter" in str(_base).lower(): + self._vprint(f"{self.log_prefix} • Check credits: https://openrouter.ai/settings/credits", force=True) + else: + self._vprint(f"{self.log_prefix} 💡 This type of error won't be fixed by retrying.", force=True) + logging.error(f"{self.log_prefix}Non-retryable client error: {api_error}") + # Skip session persistence when the error is likely + # context-overflow related (status 400 + large session). + # Persisting the failed user message would make the + # session even larger, causing the same failure on the + # next attempt. (#1630) + if status_code == 400 and (approx_tokens > 50000 or len(api_messages) > 80): + self._vprint( + f"{self.log_prefix}⚠️ Skipping session persistence " + f"for large failed session to prevent growth loop.", + force=True, + ) + else: + self._persist_session(messages, conversation_history) + return { + "final_response": None, + "messages": messages, + "api_calls": api_call_count, + "completed": False, + "failed": True, + "error": str(api_error), + } + + if retry_count >= max_retries: + # Before falling back, try rebuilding the primary + # client once for transient transport errors (stale + # connection pool, TCP reset). Only attempted once + # per API call block. + if not primary_recovery_attempted and self._try_recover_primary_transport( + api_error, retry_count=retry_count, max_retries=max_retries, + ): + primary_recovery_attempted = True + retry_count = 0 + continue + # Try fallback before giving up entirely + self._emit_status(f"⚠️ Max retries ({max_retries}) exhausted — trying fallback...") + if self._try_activate_fallback(): + retry_count = 0 + compression_attempts = 0 + primary_recovery_attempted = False + continue + _final_summary = self._summarize_api_error(api_error) + if is_rate_limited: + self._emit_status(f"❌ Rate limited after {max_retries} retries — {_final_summary}") + else: + self._emit_status(f"❌ API failed after {max_retries} retries — {_final_summary}") + self._vprint(f"{self.log_prefix} 💀 Final error: {_final_summary}", force=True) + + # Detect SSE stream-drop pattern (e.g. "Network + # connection lost") and surface actionable guidance. + # This typically happens when the model generates a + # very large tool call (write_file with huge content) + # and the proxy/CDN drops the stream mid-response. + _is_stream_drop = ( + not getattr(api_error, "status_code", None) + and any(p in error_msg for p in ( + "connection lost", "connection reset", + "connection closed", "network connection", + "network error", "terminated", + )) + ) + if _is_stream_drop: + self._vprint( + f"{self.log_prefix} 💡 The provider's stream " + f"connection keeps dropping. This often happens " + f"when the model tries to write a very large " + f"file in a single tool call.", + force=True, + ) + self._vprint( + f"{self.log_prefix} Try asking the model " + f"to use execute_code with Python's open() for " + f"large files, or to write the file in smaller " + f"sections.", + force=True, + ) + + logging.error( + "%sAPI call failed after %s retries. %s | provider=%s model=%s msgs=%s tokens=~%s", + self.log_prefix, max_retries, _final_summary, + _provider, _model, len(api_messages), f"{approx_tokens:,}", + ) + if api_kwargs is not None: + self._dump_api_request_debug( + api_kwargs, reason="max_retries_exhausted", error=api_error, + ) + self._persist_session(messages, conversation_history) + _final_response = f"API call failed after {max_retries} retries: {_final_summary}" + if _is_stream_drop: + _final_response += ( + "\n\nThe provider's stream connection keeps " + "dropping — this often happens when generating " + "very large tool call responses (e.g. write_file " + "with long content). Try asking me to use " + "execute_code with Python's open() for large " + "files, or to write in smaller sections." + ) + return { + "final_response": _final_response, + "messages": messages, + "api_calls": api_call_count, + "completed": False, + "failed": True, + "error": _final_summary, + } + + # For rate limits, respect the Retry-After header if present + _retry_after = None + if is_rate_limited: + _resp_headers = getattr(getattr(api_error, "response", None), "headers", None) + if _resp_headers and hasattr(_resp_headers, "get"): + _ra_raw = _resp_headers.get("retry-after") or _resp_headers.get("Retry-After") + if _ra_raw: + try: + _retry_after = min(int(_ra_raw), 120) # Cap at 2 minutes + except (TypeError, ValueError): + pass + wait_time = _retry_after if _retry_after else jittered_backoff(retry_count, base_delay=2.0, max_delay=60.0) + if is_rate_limited: + self._emit_status(f"⏱️ Rate limit reached. Waiting {wait_time}s before retry (attempt {retry_count + 1}/{max_retries})...") + else: + self._emit_status(f"⏳ Retrying in {wait_time}s (attempt {retry_count}/{max_retries})...") + logger.warning( + "Retrying API call in %ss (attempt %s/%s) %s error=%s", + wait_time, + retry_count, + max_retries, + self._client_log_context(), + api_error, + ) + # Sleep in small increments so we can respond to interrupts quickly + # instead of blocking the entire wait_time in one sleep() call + sleep_end = time.time() + wait_time + _backoff_touch_counter = 0 + while time.time() < sleep_end: + if self._interrupt_requested: + self._vprint(f"{self.log_prefix}⚡ Interrupt detected during retry wait, aborting.", force=True) + self._persist_session(messages, conversation_history) + self.clear_interrupt() + return { + "final_response": f"Operation interrupted: retrying API call after error (retry {retry_count}/{max_retries}).", + "messages": messages, + "api_calls": api_call_count, + "completed": False, + "interrupted": True, + } + time.sleep(0.2) # Check interrupt every 200ms + # Touch activity every ~30s so the gateway's inactivity + # monitor knows we're alive during backoff waits. + _backoff_touch_counter += 1 + if _backoff_touch_counter % 150 == 0: # 150 × 0.2s = 30s + self._touch_activity( + f"error retry backoff ({retry_count}/{max_retries}), " + f"{int(sleep_end - time.time())}s remaining" + ) + + # If the API call was interrupted, skip response processing + if interrupted: + _turn_exit_reason = "interrupted_during_api_call" + break + + if restart_with_compressed_messages: + api_call_count -= 1 + self.iteration_budget.refund() + # Count compression restarts toward the retry limit to prevent + # infinite loops when compression reduces messages but not enough + # to fit the context window. + retry_count += 1 + restart_with_compressed_messages = False + continue + + if restart_with_length_continuation: + continue + + # Guard: if all retries exhausted without a successful response + # (e.g. repeated context-length errors that exhausted retry_count), + # the `response` variable is still None. Break out cleanly. + if response is None: + _turn_exit_reason = "all_retries_exhausted_no_response" + print(f"{self.log_prefix}❌ All API retries exhausted with no successful response.") + self._persist_session(messages, conversation_history) + break + + try: + if self.api_mode == "codex_responses": + assistant_message, finish_reason = self._normalize_codex_response(response) + elif self.api_mode == "anthropic_messages": + from agent.anthropic_adapter import normalize_anthropic_response + assistant_message, finish_reason = normalize_anthropic_response( + response, strip_tool_prefix=self._is_anthropic_oauth + ) + else: + assistant_message = response.choices[0].message + + # Normalize content to string — some OpenAI-compatible servers + # (llama-server, etc.) return content as a dict or list instead + # of a plain string, which crashes downstream .strip() calls. + if assistant_message.content is not None and not isinstance(assistant_message.content, str): + raw = assistant_message.content + if isinstance(raw, dict): + assistant_message.content = raw.get("text", "") or raw.get("content", "") or json.dumps(raw) + elif isinstance(raw, list): + # Multimodal content list — extract text parts + parts = [] + for part in raw: + if isinstance(part, str): + parts.append(part) + elif isinstance(part, dict) and part.get("type") == "text": + parts.append(part.get("text", "")) + elif isinstance(part, dict) and "text" in part: + parts.append(str(part["text"])) + assistant_message.content = "\n".join(parts) + else: + assistant_message.content = str(raw) + + try: + from hermes_cli.plugins import invoke_hook as _invoke_hook + _assistant_tool_calls = getattr(assistant_message, "tool_calls", None) or [] + _assistant_text = assistant_message.content or "" + _invoke_hook( + "post_api_request", + task_id=effective_task_id, + session_id=self.session_id or "", + platform=self.platform or "", + model=self.model, + provider=self.provider, + base_url=self.base_url, + api_mode=self.api_mode, + api_call_count=api_call_count, + api_duration=api_duration, + finish_reason=finish_reason, + message_count=len(api_messages), + response_model=getattr(response, "model", None), + usage=self._usage_summary_for_api_request_hook(response), + assistant_content_chars=len(_assistant_text), + assistant_tool_call_count=len(_assistant_tool_calls), + ) + except Exception: + pass + + # Handle assistant response + if assistant_message.content and not self.quiet_mode: + if self.verbose_logging: + self._vprint(f"{self.log_prefix}🤖 Assistant: {assistant_message.content}") + else: + self._vprint(f"{self.log_prefix}🤖 Assistant: {assistant_message.content[:100]}{'...' if len(assistant_message.content) > 100 else ''}") + + # Notify progress callback of model's thinking (used by subagent + # delegation to relay the child's reasoning to the parent display). + if (assistant_message.content and self.tool_progress_callback): + _think_text = assistant_message.content.strip() + # Strip reasoning XML tags that shouldn't leak to parent display + _think_text = re.sub( + r'', '', _think_text + ).strip() + # For subagents: relay first line to parent display (existing behaviour). + # For all agents with a structured callback: emit reasoning.available event. + first_line = _think_text.split('\n')[0][:80] if _think_text else "" + if first_line and getattr(self, '_delegate_depth', 0) > 0: + try: + self.tool_progress_callback("_thinking", first_line) + except Exception: + pass + elif _think_text: + try: + self.tool_progress_callback("reasoning.available", "_thinking", _think_text[:500], None) + except Exception: + pass + + # Check for incomplete (opened but never closed) + # This means the model ran out of output tokens mid-reasoning — retry up to 2 times + if has_incomplete_scratchpad(assistant_message.content or ""): + self._incomplete_scratchpad_retries += 1 + + self._vprint(f"{self.log_prefix}⚠️ Incomplete detected (opened but never closed)") + + if self._incomplete_scratchpad_retries <= 2: + self._vprint(f"{self.log_prefix}🔄 Retrying API call ({self._incomplete_scratchpad_retries}/2)...") + # Don't add the broken message, just retry + continue + else: + # Max retries - discard this turn and save as partial + self._vprint(f"{self.log_prefix}❌ Max retries (2) for incomplete scratchpad. Saving as partial.", force=True) + self._incomplete_scratchpad_retries = 0 + + rolled_back_messages = self._get_messages_up_to_last_assistant(messages) + self._cleanup_task_resources(effective_task_id) + self._persist_session(messages, conversation_history) + + return { + "final_response": None, + "messages": rolled_back_messages, + "api_calls": api_call_count, + "completed": False, + "partial": True, + "error": "Incomplete REASONING_SCRATCHPAD after 2 retries" + } + + # Reset incomplete scratchpad counter on clean response + self._incomplete_scratchpad_retries = 0 + + if self.api_mode == "codex_responses" and finish_reason == "incomplete": + self._codex_incomplete_retries += 1 + + interim_msg = self._build_assistant_message(assistant_message, finish_reason) + interim_has_content = bool((interim_msg.get("content") or "").strip()) + interim_has_reasoning = bool(interim_msg.get("reasoning", "").strip()) if isinstance(interim_msg.get("reasoning"), str) else False + interim_has_codex_reasoning = bool(interim_msg.get("codex_reasoning_items")) + + if interim_has_content or interim_has_reasoning or interim_has_codex_reasoning: + last_msg = messages[-1] if messages else None + # Duplicate detection: two consecutive incomplete assistant + # messages with identical content AND reasoning are collapsed. + # For reasoning-only messages (codex_reasoning_items differ but + # visible content/reasoning are both empty), we also compare + # the encrypted items to avoid silently dropping new state. + last_codex_items = last_msg.get("codex_reasoning_items") if isinstance(last_msg, dict) else None + interim_codex_items = interim_msg.get("codex_reasoning_items") + duplicate_interim = ( + isinstance(last_msg, dict) + and last_msg.get("role") == "assistant" + and last_msg.get("finish_reason") == "incomplete" + and (last_msg.get("content") or "") == (interim_msg.get("content") or "") + and (last_msg.get("reasoning") or "") == (interim_msg.get("reasoning") or "") + and last_codex_items == interim_codex_items + ) + if not duplicate_interim: + messages.append(interim_msg) + self._emit_interim_assistant_message(interim_msg) + + if self._codex_incomplete_retries < 3: + if not self.quiet_mode: + self._vprint(f"{self.log_prefix}↻ Codex response incomplete; continuing turn ({self._codex_incomplete_retries}/3)") + self._session_messages = messages + self._save_session_log(messages) + continue + + self._codex_incomplete_retries = 0 + self._persist_session(messages, conversation_history) + return { + "final_response": None, + "messages": messages, + "api_calls": api_call_count, + "completed": False, + "partial": True, + "error": "Codex response remained incomplete after 3 continuation attempts", + } + elif hasattr(self, "_codex_incomplete_retries"): + self._codex_incomplete_retries = 0 + + # Check for tool calls + if assistant_message.tool_calls: + if not self.quiet_mode: + self._vprint(f"{self.log_prefix}🔧 Processing {len(assistant_message.tool_calls)} tool call(s)...") + + if self.verbose_logging: + for tc in assistant_message.tool_calls: + logging.debug(f"Tool call: {tc.function.name} with args: {tc.function.arguments[:200]}...") + + # Validate tool call names - detect model hallucinations + # Repair mismatched tool names before validating + for tc in assistant_message.tool_calls: + if tc.function.name not in self.valid_tool_names: + repaired = self._repair_tool_call(tc.function.name) + if repaired: + print(f"{self.log_prefix}🔧 Auto-repaired tool name: '{tc.function.name}' -> '{repaired}'") + tc.function.name = repaired + invalid_tool_calls = [ + tc.function.name for tc in assistant_message.tool_calls + if tc.function.name not in self.valid_tool_names + ] + if invalid_tool_calls: + # Track retries for invalid tool calls + self._invalid_tool_retries += 1 + + # Return helpful error to model — model can self-correct next turn + available = ", ".join(sorted(self.valid_tool_names)) + invalid_name = invalid_tool_calls[0] + invalid_preview = invalid_name[:80] + "..." if len(invalid_name) > 80 else invalid_name + self._vprint(f"{self.log_prefix}⚠️ Unknown tool '{invalid_preview}' — sending error to model for self-correction ({self._invalid_tool_retries}/3)") + + if self._invalid_tool_retries >= 3: + self._vprint(f"{self.log_prefix}❌ Max retries (3) for invalid tool calls exceeded. Stopping as partial.", force=True) + self._invalid_tool_retries = 0 + self._persist_session(messages, conversation_history) + return { + "final_response": None, + "messages": messages, + "api_calls": api_call_count, + "completed": False, + "partial": True, + "error": f"Model generated invalid tool call: {invalid_preview}" + } + + assistant_msg = self._build_assistant_message(assistant_message, finish_reason) + messages.append(assistant_msg) + for tc in assistant_message.tool_calls: + if tc.function.name not in self.valid_tool_names: + content = f"Tool '{tc.function.name}' does not exist. Available tools: {available}" + else: + content = "Skipped: another tool call in this turn used an invalid name. Please retry this tool call." + messages.append({ + "role": "tool", + "tool_call_id": tc.id, + "content": content, + }) + continue + # Reset retry counter on successful tool call validation + self._invalid_tool_retries = 0 + + # Validate tool call arguments are valid JSON + # Handle empty strings as empty objects (common model quirk) + invalid_json_args = [] + for tc in assistant_message.tool_calls: + args = tc.function.arguments + if isinstance(args, (dict, list)): + tc.function.arguments = json.dumps(args) + continue + if args is not None and not isinstance(args, str): + tc.function.arguments = str(args) + args = tc.function.arguments + # Treat empty/whitespace strings as empty object + if not args or not args.strip(): + tc.function.arguments = "{}" + continue + try: + json.loads(args) + except json.JSONDecodeError as e: + invalid_json_args.append((tc.function.name, str(e))) + + if invalid_json_args: + # Check if the invalid JSON is due to truncation rather + # than a model formatting mistake. Routers sometimes + # rewrite finish_reason from "length" to "tool_calls", + # hiding the truncation from the length handler above. + # Detect truncation: args that don't end with } or ] + # (after stripping whitespace) are cut off mid-stream. + _truncated = any( + not (tc.function.arguments or "").rstrip().endswith(("}", "]")) + for tc in assistant_message.tool_calls + if tc.function.name in {n for n, _ in invalid_json_args} + ) + if _truncated: + self._vprint( + f"{self.log_prefix}⚠️ Truncated tool call arguments detected " + f"(finish_reason={finish_reason!r}) — refusing to execute.", + force=True, + ) + self._invalid_json_retries = 0 + self._cleanup_task_resources(effective_task_id) + self._persist_session(messages, conversation_history) + return { + "final_response": None, + "messages": messages, + "api_calls": api_call_count, + "completed": False, + "partial": True, + "error": "Response truncated due to output length limit", + } + + # Track retries for invalid JSON arguments + self._invalid_json_retries += 1 + + tool_name, error_msg = invalid_json_args[0] + self._vprint(f"{self.log_prefix}⚠️ Invalid JSON in tool call arguments for '{tool_name}': {error_msg}") + + if self._invalid_json_retries < 3: + self._vprint(f"{self.log_prefix}🔄 Retrying API call ({self._invalid_json_retries}/3)...") + # Don't add anything to messages, just retry the API call + continue + else: + # Instead of returning partial, inject tool error results so the model can recover. + # Using tool results (not user messages) preserves role alternation. + self._vprint(f"{self.log_prefix}⚠️ Injecting recovery tool results for invalid JSON...") + self._invalid_json_retries = 0 # Reset for next attempt + + # Append the assistant message with its (broken) tool_calls + recovery_assistant = self._build_assistant_message(assistant_message, finish_reason) + messages.append(recovery_assistant) + + # Respond with tool error results for each tool call + invalid_names = {name for name, _ in invalid_json_args} + for tc in assistant_message.tool_calls: + if tc.function.name in invalid_names: + err = next(e for n, e in invalid_json_args if n == tc.function.name) + tool_result = ( + f"Error: Invalid JSON arguments. {err}. " + f"For tools with no required parameters, use an empty object: {{}}. " + f"Please retry with valid JSON." + ) + else: + tool_result = "Skipped: other tool call in this response had invalid JSON." + messages.append({ + "role": "tool", + "tool_call_id": tc.id, + "content": tool_result, + }) + continue + + # Reset retry counter on successful JSON validation + self._invalid_json_retries = 0 + + # ── Post-call guardrails ────────────────────────── + assistant_message.tool_calls = self._cap_delegate_task_calls( + assistant_message.tool_calls + ) + assistant_message.tool_calls = self._deduplicate_tool_calls( + assistant_message.tool_calls + ) + + assistant_msg = self._build_assistant_message(assistant_message, finish_reason) + + # If this turn has both content AND tool_calls, capture the content + # as a fallback final response. Common pattern: model delivers its + # answer and calls memory/skill tools as a side-effect in the same + # turn. If the follow-up turn after tools is empty, we use this. + turn_content = assistant_message.content or "" + if turn_content and self._has_content_after_think_block(turn_content): + self._last_content_with_tools = turn_content + # Only mute subsequent output when EVERY tool call in + # this turn is post-response housekeeping (memory, todo, + # skill_manage, etc.). If any substantive tool is present + # (search_files, read_file, write_file, terminal, ...), + # keep output visible so the user sees progress. + _HOUSEKEEPING_TOOLS = frozenset({ + "memory", "todo", "skill_manage", "session_search", + }) + _all_housekeeping = all( + tc.function.name in _HOUSEKEEPING_TOOLS + for tc in assistant_message.tool_calls + ) + if _all_housekeeping and self._has_stream_consumers(): + self._mute_post_response = True + elif self.quiet_mode: + clean = self._strip_think_blocks(turn_content).strip() + if clean: + self._vprint(f" ┊ 💬 {clean}") + + # Pop thinking-only prefill message(s) before appending + # (tool-call path — same rationale as the final-response path). + _had_prefill = False + while ( + messages + and isinstance(messages[-1], dict) + and messages[-1].get("_thinking_prefill") + ): + messages.pop() + _had_prefill = True + + # Reset prefill counter when tool calls follow a prefill + # recovery. Without this, the counter accumulates across + # the whole conversation — a model that intermittently + # empties (empty → prefill → tools → empty → prefill → + # tools) burns both prefill attempts and the third empty + # gets zero recovery. Resetting here treats each tool- + # call success as a fresh start. + if _had_prefill: + self._thinking_prefill_retries = 0 + self._empty_content_retries = 0 + + messages.append(assistant_msg) + self._emit_interim_assistant_message(assistant_msg) + + # Close any open streaming display (response box, reasoning + # box) before tool execution begins. Intermediate turns may + # have streamed early content that opened the response box; + # flushing here prevents it from wrapping tool feed lines. + # Only signal the display callback — TTS (_stream_callback) + # should NOT receive None (it uses None as end-of-stream). + if self.stream_delta_callback: + try: + self.stream_delta_callback(None) + except Exception: + pass + + self._execute_tool_calls(assistant_message, messages, effective_task_id, api_call_count) + + # Reset per-turn retry counters after successful tool + # execution so a single truncation doesn't poison the + # entire conversation. + truncated_tool_call_retries = 0 + + # Signal that a paragraph break is needed before the next + # streamed text. We don't emit it immediately because + # multiple consecutive tool iterations would stack up + # redundant blank lines. Instead, _fire_stream_delta() + # will prepend a single "\n\n" the next time real text + # arrives. + self._stream_needs_break = True + + # Refund the iteration if the ONLY tool(s) called were + # execute_code (programmatic tool calling). These are + # cheap RPC-style calls that shouldn't eat the budget. + _tc_names = {tc.function.name for tc in assistant_message.tool_calls} + if _tc_names == {"execute_code"}: + self.iteration_budget.refund() + + # Use real token counts from the API response to decide + # compression. prompt_tokens + completion_tokens is the + # actual context size the provider reported plus the + # assistant turn — a tight lower bound for the next prompt. + # Tool results appended above aren't counted yet, but the + # threshold (default 50%) leaves ample headroom; if tool + # results push past it, the next API call will report the + # real total and trigger compression then. + # + # If last_prompt_tokens is 0 (stale after API disconnect + # or provider returned no usage data), fall back to rough + # estimate to avoid missing compression. Without this, + # a session can grow unbounded after disconnects because + # should_compress(0) never fires. (#2153) + _compressor = self.context_compressor + if _compressor.last_prompt_tokens > 0: + _real_tokens = ( + _compressor.last_prompt_tokens + + _compressor.last_completion_tokens + ) + else: + _real_tokens = estimate_messages_tokens_rough(messages) + + # ── Context pressure warnings (user-facing only) ────────── + # Notify the user (NOT the LLM) as context approaches the + # compaction threshold. Thresholds are relative to where + # compaction fires, not the raw context window. + # Does not inject into messages — just prints to CLI output + # and fires status_callback for gateway platforms. + # Tiered: 85% (orange) and 95% (red/critical). + if _compressor.threshold_tokens > 0: + _compaction_progress = _real_tokens / _compressor.threshold_tokens + # Determine the warning tier for this progress level + _warn_tier = 0.0 + if _compaction_progress >= 0.95: + _warn_tier = 0.95 + elif _compaction_progress >= 0.85: + _warn_tier = 0.85 + if _warn_tier > self._context_pressure_warned_at: + # Class-level dedup: check if this session was already + # warned at this tier within the cooldown window. + _sid = self.session_id or "default" + _last = AIAgent._context_pressure_last_warned.get(_sid) + _now = time.time() + if _last is None or _last[0] < _warn_tier or (_now - _last[1]) >= self._CONTEXT_PRESSURE_COOLDOWN: + self._context_pressure_warned_at = _warn_tier + AIAgent._context_pressure_last_warned[_sid] = (_warn_tier, _now) + self._emit_context_pressure(_compaction_progress, _compressor) + # Evict stale entries (older than 2x cooldown) + _cutoff = _now - self._CONTEXT_PRESSURE_COOLDOWN * 2 + AIAgent._context_pressure_last_warned = { + k: v for k, v in AIAgent._context_pressure_last_warned.items() + if v[1] > _cutoff + } + + if self.compression_enabled and _compressor.should_compress(_real_tokens): + self._safe_print(" ⟳ compacting context…") + messages, active_system_prompt = self._compress_context( + messages, system_message, + approx_tokens=self.context_compressor.last_prompt_tokens, + task_id=effective_task_id, + ) + # Compression created a new session — clear history so + # _flush_messages_to_session_db writes compressed messages + # to the new session (see preflight compression comment). + conversation_history = None + + # Save session log incrementally (so progress is visible even if interrupted) + self._session_messages = messages + self._save_session_log(messages) + + # Continue loop for next response + continue + + else: + # No tool calls - this is the final response + final_response = assistant_message.content or "" + + # Check if response only has think block with no actual content after it + if not self._has_content_after_think_block(final_response): + # ── Partial stream recovery ───────────────────── + # If content was already streamed to the user before + # the connection died, use it as the final response + # instead of falling through to prior-turn fallback + # or wasting API calls on retries. + _partial_streamed = ( + getattr(self, "_current_streamed_assistant_text", "") or "" + ) + if self._has_content_after_think_block(_partial_streamed): + _turn_exit_reason = "partial_stream_recovery" + _recovered = self._strip_think_blocks(_partial_streamed).strip() + logger.info( + "Partial stream content delivered (%d chars) " + "— using as final response", + len(_recovered), + ) + self._emit_status( + "↻ Stream interrupted — using delivered content " + "as final response" + ) + final_response = _recovered + self._response_was_previewed = True + break + + # If the previous turn already delivered real content alongside + # tool calls (e.g. "You're welcome!" + memory save), the model + # has nothing more to say. Use the earlier content immediately + # instead of wasting API calls on retries that won't help. + fallback = getattr(self, '_last_content_with_tools', None) + if fallback: + _turn_exit_reason = "fallback_prior_turn_content" + logger.info("Empty follow-up after tool calls — using prior turn content as final response") + self._emit_status("↻ Empty response after tool calls — using earlier content as final answer") + self._last_content_with_tools = None + self._empty_content_retries = 0 + for i in range(len(messages) - 1, -1, -1): + msg = messages[i] + if msg.get("role") == "assistant" and msg.get("tool_calls"): + tool_names = [] + for tc in msg["tool_calls"]: + if not tc or not isinstance(tc, dict): continue + fn = tc.get("function", {}) + tool_names.append(fn.get("name", "unknown")) + msg["content"] = f"Calling the {', '.join(tool_names)} tool{'s' if len(tool_names) > 1 else ''}..." + break + final_response = self._strip_think_blocks(fallback).strip() + self._response_was_previewed = True + break + + # ── Thinking-only prefill continuation ────────── + # The model produced structured reasoning (via API + # fields) but no visible text content. Rather than + # giving up, append the assistant message as-is and + # continue — the model will see its own reasoning + # on the next turn and produce the text portion. + # Inspired by clawdbot's "incomplete-text" recovery. + _has_structured = bool( + getattr(assistant_message, "reasoning", None) + or getattr(assistant_message, "reasoning_content", None) + or getattr(assistant_message, "reasoning_details", None) + ) + if _has_structured and self._thinking_prefill_retries < 2: + self._thinking_prefill_retries += 1 + logger.info( + "Thinking-only response (no visible content) — " + "prefilling to continue (%d/2)", + self._thinking_prefill_retries, + ) + self._emit_status( + f"↻ Thinking-only response — prefilling to continue " + f"({self._thinking_prefill_retries}/2)" + ) + interim_msg = self._build_assistant_message( + assistant_message, "incomplete" + ) + interim_msg["_thinking_prefill"] = True + messages.append(interim_msg) + self._session_messages = messages + self._save_session_log(messages) + continue + + # ── Empty response retry ────────────────────── + # Model returned nothing usable. Retry up to 3 + # times before attempting fallback. This covers + # both truly empty responses (no content, no + # reasoning) AND reasoning-only responses after + # prefill exhaustion — models like mimo-v2-pro + # always populate reasoning fields via OpenRouter, + # so the old `not _has_structured` guard blocked + # retries for every reasoning model after prefill. + _truly_empty = not self._strip_think_blocks( + final_response + ).strip() + _prefill_exhausted = ( + _has_structured + and self._thinking_prefill_retries >= 2 + ) + if _truly_empty and (not _has_structured or _prefill_exhausted) and self._empty_content_retries < 3: + self._empty_content_retries += 1 + logger.warning( + "Empty response (no content or reasoning) — " + "retry %d/3 (model=%s)", + self._empty_content_retries, self.model, + ) + self._emit_status( + f"⚠️ Empty response from model — retrying " + f"({self._empty_content_retries}/3)" + ) + continue + + # ── Exhausted retries — try fallback provider ── + # Before giving up with "(empty)", attempt to + # switch to the next provider in the fallback + # chain. This covers the case where a model + # (e.g. GLM-4.5-Air) consistently returns empty + # due to context degradation or provider issues. + if _truly_empty and self._fallback_chain: + logger.warning( + "Empty response after %d retries — " + "attempting fallback (model=%s, provider=%s)", + self._empty_content_retries, self.model, + self.provider, + ) + self._emit_status( + "⚠️ Model returning empty responses — " + "switching to fallback provider..." + ) + if self._try_activate_fallback(): + self._empty_content_retries = 0 + self._emit_status( + f"↻ Switched to fallback: {self.model} " + f"({self.provider})" + ) + logger.info( + "Fallback activated after empty responses: " + "now using %s on %s", + self.model, self.provider, + ) + continue + + # Exhausted retries and fallback chain (or no + # fallback configured). Fall through to the + # "(empty)" terminal. + _turn_exit_reason = "empty_response_exhausted" + reasoning_text = self._extract_reasoning(assistant_message) + assistant_msg = self._build_assistant_message(assistant_message, finish_reason) + assistant_msg["content"] = "(empty)" + messages.append(assistant_msg) + + if reasoning_text: + reasoning_preview = reasoning_text[:500] + "..." if len(reasoning_text) > 500 else reasoning_text + logger.warning( + "Reasoning-only response (no visible content) " + "after exhausting retries and fallback. " + "Reasoning: %s", reasoning_preview, + ) + self._emit_status( + "⚠️ Model produced reasoning but no visible " + "response after all retries. Returning empty." + ) + else: + logger.warning( + "Empty response (no content or reasoning) " + "after %d retries. No fallback available. " + "model=%s provider=%s", + self._empty_content_retries, self.model, + self.provider, + ) + self._emit_status( + "❌ Model returned no content after all retries" + + (" and fallback attempts." if self._fallback_chain else + ". No fallback providers configured.") + ) + + final_response = "(empty)" + break + + # Reset retry counter/signature on successful content + self._empty_content_retries = 0 + self._thinking_prefill_retries = 0 + + if ( + self.api_mode == "codex_responses" + and self.valid_tool_names + and codex_ack_continuations < 2 + and self._looks_like_codex_intermediate_ack( + user_message=user_message, + assistant_content=final_response, + messages=messages, + ) + ): + codex_ack_continuations += 1 + interim_msg = self._build_assistant_message(assistant_message, "incomplete") + messages.append(interim_msg) + self._emit_interim_assistant_message(interim_msg) + + continue_msg = { + "role": "user", + "content": ( + "[System: Continue now. Execute the required tool calls and only " + "send your final answer after completing the task.]" + ), + } + messages.append(continue_msg) + self._session_messages = messages + self._save_session_log(messages) + continue + + codex_ack_continuations = 0 + + if truncated_response_prefix: + final_response = truncated_response_prefix + final_response + truncated_response_prefix = "" + length_continue_retries = 0 + + # Strip blocks from user-facing response (keep raw in messages for trajectory) + final_response = self._strip_think_blocks(final_response).strip() + + final_msg = self._build_assistant_message(assistant_message, finish_reason) + + # Pop thinking-only prefill message(s) before appending + # the final response. This avoids consecutive assistant + # messages which break strict-alternation providers + # (Anthropic Messages API) and keeps history clean. + while ( + messages + and isinstance(messages[-1], dict) + and messages[-1].get("_thinking_prefill") + ): + messages.pop() + + messages.append(final_msg) + + _turn_exit_reason = f"text_response(finish_reason={finish_reason})" + if not self.quiet_mode: + self._safe_print(f"🎉 Conversation completed after {api_call_count} OpenAI-compatible API call(s)") + break + + except Exception as e: + error_msg = f"Error during OpenAI-compatible API call #{api_call_count}: {str(e)}" + try: + print(f"❌ {error_msg}") + except (OSError, ValueError): + logger.error(error_msg) + + logger.debug("Outer loop error in API call #%d", api_call_count, exc_info=True) + + # If an assistant message with tool_calls was already appended, + # the API expects a role="tool" result for every tool_call_id. + # Fill in error results for any that weren't answered yet. + for idx in range(len(messages) - 1, -1, -1): + msg = messages[idx] + if not isinstance(msg, dict): + break + if msg.get("role") == "tool": + continue + if msg.get("role") == "assistant" and msg.get("tool_calls"): + answered_ids = { + m["tool_call_id"] + for m in messages[idx + 1:] + if isinstance(m, dict) and m.get("role") == "tool" + } + for tc in msg["tool_calls"]: + if not tc or not isinstance(tc, dict): continue + if tc["id"] not in answered_ids: + err_msg = { + "role": "tool", + "tool_call_id": tc["id"], + "content": f"Error executing tool: {error_msg}", + } + messages.append(err_msg) + break + + # Non-tool errors don't need a synthetic message injected. + # The error is already printed to the user (line above), and + # the retry loop continues. Injecting a fake user/assistant + # message pollutes history, burns tokens, and risks violating + # role-alternation invariants. + + # If we're near the limit, break to avoid infinite loops + if api_call_count >= self.max_iterations - 1: + _turn_exit_reason = f"error_near_max_iterations({error_msg[:80]})" + final_response = f"I apologize, but I encountered repeated errors: {error_msg}" + # Append as assistant so the history stays valid for + # session resume (avoids consecutive user messages). + messages.append({"role": "assistant", "content": final_response}) + break + + if final_response is None and ( + api_call_count >= self.max_iterations + or self.iteration_budget.remaining <= 0 + ): + # Budget exhausted — ask the model for a summary via one extra + # API call with tools stripped. _handle_max_iterations injects a + # user message and makes a single toolless request. + _turn_exit_reason = f"max_iterations_reached({api_call_count}/{self.max_iterations})" + self._emit_status( + f"⚠️ Iteration budget exhausted ({api_call_count}/{self.max_iterations}) " + "— asking model to summarise" + ) + if not self.quiet_mode: + self._safe_print( + f"\n⚠️ Iteration budget exhausted ({api_call_count}/{self.max_iterations}) " + "— requesting summary..." + ) + final_response = self._handle_max_iterations(messages, api_call_count) + + # Determine if conversation completed successfully + completed = final_response is not None and api_call_count < self.max_iterations + + # Save trajectory if enabled + self._save_trajectory(messages, user_message, completed) + + # Clean up VM and browser for this task after conversation completes + self._cleanup_task_resources(effective_task_id) + + # Persist session to both JSON log and SQLite + self._persist_session(messages, conversation_history) + + # ── Turn-exit diagnostic log ───────────────────────────────────── + # Always logged at INFO so agent.log captures WHY every turn ended. + # When the last message is a tool result (agent was mid-work), log + # at WARNING — this is the "just stops" scenario users report. + _last_msg_role = messages[-1].get("role") if messages else None + _last_tool_name = None + if _last_msg_role == "tool": + # Walk back to find the assistant message with the tool call + for _m in reversed(messages): + if _m.get("role") == "assistant" and _m.get("tool_calls"): + _tcs = _m["tool_calls"] + if _tcs and isinstance(_tcs[0], dict): + _last_tool_name = _tcs[-1].get("function", {}).get("name") + break + + _turn_tool_count = sum( + 1 for m in messages + if isinstance(m, dict) and m.get("role") == "assistant" and m.get("tool_calls") + ) + _resp_len = len(final_response) if final_response else 0 + _budget_used = self.iteration_budget.used if self.iteration_budget else 0 + _budget_max = self.iteration_budget.max_total if self.iteration_budget else 0 + + _diag_msg = ( + "Turn ended: reason=%s model=%s api_calls=%d/%d budget=%d/%d " + "tool_turns=%d last_msg_role=%s response_len=%d session=%s" + ) + _diag_args = ( + _turn_exit_reason, self.model, api_call_count, self.max_iterations, + _budget_used, _budget_max, + _turn_tool_count, _last_msg_role, _resp_len, + self.session_id or "none", + ) + + if _last_msg_role == "tool" and not interrupted: + # Agent was mid-work — this is the "just stops" case. + logger.warning( + "Turn ended with pending tool result (agent may appear stuck). " + + _diag_msg + " last_tool=%s", + *_diag_args, _last_tool_name, + ) + else: + logger.info(_diag_msg, *_diag_args) + + # Plugin hook: post_llm_call + # Fired once per turn after the tool-calling loop completes. + # Plugins can use this to persist conversation data (e.g. sync + # to an external memory system). + if final_response and not interrupted: + try: + from hermes_cli.plugins import invoke_hook as _invoke_hook + _invoke_hook( + "post_llm_call", + session_id=self.session_id, + user_message=original_user_message, + assistant_response=final_response, + conversation_history=list(messages), + model=self.model, + platform=getattr(self, "platform", None) or "", + ) + except Exception as exc: + logger.warning("post_llm_call hook failed: %s", exc) + + # Extract reasoning from the last assistant message (if any) + last_reasoning = None + for msg in reversed(messages): + if msg.get("role") == "assistant" and msg.get("reasoning"): + last_reasoning = msg["reasoning"] + break + + # Build result with interrupt info if applicable + result = { + "final_response": final_response, + "last_reasoning": last_reasoning, + "messages": messages, + "api_calls": api_call_count, + "completed": completed, + "partial": False, # True only when stopped due to invalid tool calls + "interrupted": interrupted, + "response_previewed": getattr(self, "_response_was_previewed", False), + "model": self.model, + "provider": self.provider, + "base_url": self.base_url, + "input_tokens": self.session_input_tokens, + "output_tokens": self.session_output_tokens, + "cache_read_tokens": self.session_cache_read_tokens, + "cache_write_tokens": self.session_cache_write_tokens, + "reasoning_tokens": self.session_reasoning_tokens, + "prompt_tokens": self.session_prompt_tokens, + "completion_tokens": self.session_completion_tokens, + "total_tokens": self.session_total_tokens, + "last_prompt_tokens": getattr(self.context_compressor, "last_prompt_tokens", 0) or 0, + "estimated_cost_usd": self.session_estimated_cost_usd, + "cost_status": self.session_cost_status, + "cost_source": self.session_cost_source, + } + self._response_was_previewed = False + + # Include interrupt message if one triggered the interrupt + if interrupted and self._interrupt_message: + result["interrupt_message"] = self._interrupt_message + + # Clear interrupt state after handling + self.clear_interrupt() + + # Clear stream callback so it doesn't leak into future calls + self._stream_callback = None + + # Check skill trigger NOW — based on how many tool iterations THIS turn used. + _should_review_skills = False + if (self._skill_nudge_interval > 0 + and self._iters_since_skill >= self._skill_nudge_interval + and "skill_manage" in self.valid_tool_names): + _should_review_skills = True + self._iters_since_skill = 0 + + # External memory provider: sync the completed turn + queue next prefetch. + # Use original_user_message (clean input) — user_message may contain + # injected skill content that bloats / breaks provider queries. + if self._memory_manager and final_response and original_user_message: + try: + self._memory_manager.sync_all(original_user_message, final_response) + self._memory_manager.queue_prefetch_all(original_user_message) + except Exception: + pass + + # Background memory/skill review — runs AFTER the response is delivered + # so it never competes with the user's task for model attention. + if final_response and not interrupted and (_should_review_memory or _should_review_skills): + try: + self._spawn_background_review( + messages_snapshot=list(messages), + review_memory=_should_review_memory, + review_skills=_should_review_skills, + ) + except Exception: + pass # Background review is best-effort + + # Note: Memory provider on_session_end() + shutdown_all() are NOT + # called here — run_conversation() is called once per user message in + # multi-turn sessions. Shutting down after every turn would kill the + # provider before the second message. Actual session-end cleanup is + # handled by the CLI (atexit / /reset) and gateway (session expiry / + # _reset_session). + + # Plugin hook: on_session_end + # Fired at the very end of every run_conversation call. + # Plugins can use this for cleanup, flushing buffers, etc. + try: + from hermes_cli.plugins import invoke_hook as _invoke_hook + _invoke_hook( + "on_session_end", + session_id=self.session_id, + completed=completed, + interrupted=interrupted, + model=self.model, + platform=getattr(self, "platform", None) or "", + ) + except Exception as exc: + logger.warning("on_session_end hook failed: %s", exc) + + return result + + def chat(self, message: str, stream_callback: Optional[callable] = None) -> str: + """ + Simple chat interface that returns just the final response. + + Args: + message (str): User message + stream_callback: Optional callback invoked with each text delta during streaming. + + Returns: + str: Final assistant response + """ + result = self.run_conversation(message, stream_callback=stream_callback) + return result["final_response"] + + +def main( + query: str = None, + model: str = "", + api_key: str = None, + base_url: str = "", + max_turns: int = 10, + enabled_toolsets: str = None, + disabled_toolsets: str = None, + list_tools: bool = False, + save_trajectories: bool = False, + save_sample: bool = False, + verbose: bool = False, + log_prefix_chars: int = 20 +): + """ + Main function for running the agent directly. + + Args: + query (str): Natural language query for the agent. Defaults to Python 3.13 example. + model (str): Model name to use (OpenRouter format: provider/model). Defaults to anthropic/claude-sonnet-4.6. + api_key (str): API key for authentication. Uses OPENROUTER_API_KEY env var if not provided. + base_url (str): Base URL for the model API. Defaults to https://openrouter.ai/api/v1 + max_turns (int): Maximum number of API call iterations. Defaults to 10. + enabled_toolsets (str): Comma-separated list of toolsets to enable. Supports predefined + toolsets (e.g., "research", "development", "safe"). + Multiple toolsets can be combined: "web,vision" + disabled_toolsets (str): Comma-separated list of toolsets to disable (e.g., "terminal") + list_tools (bool): Just list available tools and exit + save_trajectories (bool): Save conversation trajectories to JSONL files (appends to trajectory_samples.jsonl). Defaults to False. + save_sample (bool): Save a single trajectory sample to a UUID-named JSONL file for inspection. Defaults to False. + verbose (bool): Enable verbose logging for debugging. Defaults to False. + log_prefix_chars (int): Number of characters to show in log previews for tool calls/responses. Defaults to 20. + + Toolset Examples: + - "research": Web search, extract, crawl + vision tools + """ + print("🤖 AI Agent with Tool Calling") + print("=" * 50) + + # Handle tool listing + if list_tools: + from model_tools import get_all_tool_names, get_toolset_for_tool, get_available_toolsets + from toolsets import get_all_toolsets, get_toolset_info + + print("📋 Available Tools & Toolsets:") + print("-" * 50) + + # Show new toolsets system + print("\n🎯 Predefined Toolsets (New System):") + print("-" * 40) + all_toolsets = get_all_toolsets() + + # Group by category + basic_toolsets = [] + composite_toolsets = [] + scenario_toolsets = [] + + for name, toolset in all_toolsets.items(): + info = get_toolset_info(name) + if info: + entry = (name, info) + if name in ["web", "terminal", "vision", "creative", "reasoning"]: + basic_toolsets.append(entry) + elif name in ["research", "development", "analysis", "content_creation", "full_stack"]: + composite_toolsets.append(entry) + else: + scenario_toolsets.append(entry) + + # Print basic toolsets + print("\n📌 Basic Toolsets:") + for name, info in basic_toolsets: + tools_str = ', '.join(info['resolved_tools']) if info['resolved_tools'] else 'none' + print(f" • {name:15} - {info['description']}") + print(f" Tools: {tools_str}") + + # Print composite toolsets + print("\n📂 Composite Toolsets (built from other toolsets):") + for name, info in composite_toolsets: + includes_str = ', '.join(info['includes']) if info['includes'] else 'none' + print(f" • {name:15} - {info['description']}") + print(f" Includes: {includes_str}") + print(f" Total tools: {info['tool_count']}") + + # Print scenario-specific toolsets + print("\n🎭 Scenario-Specific Toolsets:") + for name, info in scenario_toolsets: + print(f" • {name:20} - {info['description']}") + print(f" Total tools: {info['tool_count']}") + + + # Show legacy toolset compatibility + print("\n📦 Legacy Toolsets (for backward compatibility):") + legacy_toolsets = get_available_toolsets() + for name, info in legacy_toolsets.items(): + status = "✅" if info["available"] else "❌" + print(f" {status} {name}: {info['description']}") + if not info["available"]: + print(f" Requirements: {', '.join(info['requirements'])}") + + # Show individual tools + all_tools = get_all_tool_names() + print(f"\n🔧 Individual Tools ({len(all_tools)} available):") + for tool_name in sorted(all_tools): + toolset = get_toolset_for_tool(tool_name) + print(f" 📌 {tool_name} (from {toolset})") + + print("\n💡 Usage Examples:") + print(" # Use predefined toolsets") + print(" python run_agent.py --enabled_toolsets=research --query='search for Python news'") + print(" python run_agent.py --enabled_toolsets=development --query='debug this code'") + print(" python run_agent.py --enabled_toolsets=safe --query='analyze without terminal'") + print(" ") + print(" # Combine multiple toolsets") + print(" python run_agent.py --enabled_toolsets=web,vision --query='analyze website'") + print(" ") + print(" # Disable toolsets") + print(" python run_agent.py --disabled_toolsets=terminal --query='no command execution'") + print(" ") + print(" # Run with trajectory saving enabled") + print(" python run_agent.py --save_trajectories --query='your question here'") + return + + # Parse toolset selection arguments + enabled_toolsets_list = None + disabled_toolsets_list = None + + if enabled_toolsets: + enabled_toolsets_list = [t.strip() for t in enabled_toolsets.split(",")] + print(f"🎯 Enabled toolsets: {enabled_toolsets_list}") + + if disabled_toolsets: + disabled_toolsets_list = [t.strip() for t in disabled_toolsets.split(",")] + print(f"🚫 Disabled toolsets: {disabled_toolsets_list}") + + if save_trajectories: + print("💾 Trajectory saving: ENABLED") + print(" - Successful conversations → trajectory_samples.jsonl") + print(" - Failed conversations → failed_trajectories.jsonl") + + # Initialize agent with provided parameters + try: + agent = AIAgent( + base_url=base_url, + model=model, + api_key=api_key, + max_iterations=max_turns, + enabled_toolsets=enabled_toolsets_list, + disabled_toolsets=disabled_toolsets_list, + save_trajectories=save_trajectories, + verbose_logging=verbose, + log_prefix_chars=log_prefix_chars + ) + except RuntimeError as e: + print(f"❌ Failed to initialize agent: {e}") + return + + # Use provided query or default to Python 3.13 example + if query is None: + user_query = ( + "Tell me about the latest developments in Python 3.13 and what new features " + "developers should know about. Please search for current information and try it out." + ) + else: + user_query = query + + print(f"\n📝 User Query: {user_query}") + print("\n" + "=" * 50) + + # Run conversation + result = agent.run_conversation(user_query) + + print("\n" + "=" * 50) + print("📋 CONVERSATION SUMMARY") + print("=" * 50) + print(f"✅ Completed: {result['completed']}") + print(f"📞 API Calls: {result['api_calls']}") + print(f"💬 Messages: {len(result['messages'])}") + + if result['final_response']: + print("\n🎯 FINAL RESPONSE:") + print("-" * 30) + print(result['final_response']) + + # Save sample trajectory to UUID-named file if requested + if save_sample: + sample_id = str(uuid.uuid4())[:8] + sample_filename = f"sample_{sample_id}.json" + + # Convert messages to trajectory format (same as batch_runner) + trajectory = agent._convert_to_trajectory_format( + result['messages'], + user_query, + result['completed'] + ) + + entry = { + "conversations": trajectory, + "timestamp": datetime.now().isoformat(), + "model": model, + "completed": result['completed'], + "query": user_query + } + + try: + with open(sample_filename, "w", encoding="utf-8") as f: + # Pretty-print JSON with indent for readability + f.write(json.dumps(entry, ensure_ascii=False, indent=2)) + print(f"\n💾 Sample trajectory saved to: {sample_filename}") + except Exception as e: + print(f"\n⚠️ Failed to save sample: {e}") + + print("\n👋 Agent execution completed!") + + +if __name__ == "__main__": + fire.Fire(main) diff --git a/mindcli/_vendor/tools/__init__.py b/mindcli/_vendor/tools/__init__.py new file mode 100644 index 0000000..3214b97 --- /dev/null +++ b/mindcli/_vendor/tools/__init__.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +"""Tools package namespace. + +Keep package import side effects minimal. Importing ``tools`` should not +eagerly import the full tool stack, because several subsystems load tools while +``hermes_cli.config`` is still initializing. + +Callers should import concrete submodules directly, for example: + + import tools.web_tools + from tools import browser_tool + +Python will resolve those submodules via the package path without needing them +to be re-exported here. +""" + + +def check_file_requirements(): + """File tools only require terminal backend availability.""" + from .terminal_tool import check_terminal_requirements + + return check_terminal_requirements() + + +__all__ = ["check_file_requirements"] diff --git a/mindcli/_vendor/tools/_user_config.py b/mindcli/_vendor/tools/_user_config.py new file mode 100644 index 0000000..bb80c93 --- /dev/null +++ b/mindcli/_vendor/tools/_user_config.py @@ -0,0 +1,59 @@ +""" +用户配置存取（per-userId，基于 wiki 物理目录） + +所有连接器凭据通过 user_config_read / user_config_write 进行读写， +存储路径：{MINDOS_WIKI_DIR}/{userId}/.config/{connector}.json + +设计原则： + - 与 wiki/{userId}/ 物理目录隔离模式一致 + - .config/ 前缀防止 Agent 的 search_files 扫到凭据 + - 一个用户一个目录，导出/删除用户数据只需操作 wiki/{userId}/ +""" + +import json +import logging +import os +from pathlib import Path +from typing import Any, Dict + +logger = logging.getLogger(__name__) + + +def _wiki_root() -> Path: + """返回知识花园根目录""" + return Path(os.getenv("MINDOS_WIKI_DIR", os.path.expanduser("~/.hermes/wiki"))) + + +def user_config_path(user_id: str, connector: str) -> Path: + """返回 wiki/{userId}/.config/{connector}.json 的路径""" + return _wiki_root() / user_id / ".config" / f"{connector}.json" + + +def user_config_read(user_id: str, connector: str) -> Dict[str, Any]: + """读取指定用户的连接器配置，不存在返回空 dict""" + p = user_config_path(user_id, connector) + try: + if p.exists(): + return json.loads(p.read_text(encoding="utf-8")) + except Exception as e: + logger.warning("[UserConfig] read failed %s/%s: %s", user_id[:8], connector, e) + return {} + + +def user_config_write(user_id: str, connector: str, data: Dict[str, Any]) -> None: + """写入指定用户的连接器配置，自动创建目录""" + p = user_config_path(user_id, connector) + try: + p.parent.mkdir(parents=True, exist_ok=True) + p.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8") + except Exception as e: + logger.warning("[UserConfig] write failed %s/%s: %s", user_id[:8], connector, e) + + +def user_config_delete(user_id: str, connector: str) -> None: + """删除指定用户的连接器配置""" + p = user_config_path(user_id, connector) + try: + p.unlink(missing_ok=True) + except Exception as e: + logger.warning("[UserConfig] delete failed %s/%s: %s", user_id[:8], connector, e) diff --git a/mindcli/_vendor/tools/ansi_strip.py b/mindcli/_vendor/tools/ansi_strip.py new file mode 100644 index 0000000..b1cfb8e --- /dev/null +++ b/mindcli/_vendor/tools/ansi_strip.py @@ -0,0 +1,44 @@ +"""Strip ANSI escape sequences from subprocess output. + +Used by terminal_tool, code_execution_tool, and process_registry to clean +command output before returning it to the model. This prevents ANSI codes +from entering the model's context — which is the root cause of models +copying escape sequences into file writes. + +Covers the full ECMA-48 spec: CSI (including private-mode ``?`` prefix, +colon-separated params, intermediate bytes), OSC (BEL and ST terminators), +DCS/SOS/PM/APC string sequences, nF multi-byte escapes, Fp/Fe/Fs +single-byte escapes, and 8-bit C1 control characters. +""" + +import re + +_ANSI_ESCAPE_RE = re.compile( + r"\x1b" + r"(?:" + r"\[[\x30-\x3f]*[\x20-\x2f]*[\x40-\x7e]" # CSI sequence + r"|\][\s\S]*?(?:\x07|\x1b\\)" # OSC (BEL or ST terminator) + r"|[PX^_][\s\S]*?(?:\x1b\\)" # DCS/SOS/PM/APC strings + r"|[\x20-\x2f]+[\x30-\x7e]" # nF escape sequences + r"|[\x30-\x7e]" # Fp/Fe/Fs single-byte + r")" + r"|\x9b[\x30-\x3f]*[\x20-\x2f]*[\x40-\x7e]" # 8-bit CSI + r"|\x9d[\s\S]*?(?:\x07|\x9c)" # 8-bit OSC + r"|[\x80-\x9f]", # Other 8-bit C1 controls + re.DOTALL, +) + +# Fast-path check — skip full regex when no escape-like bytes are present. +_HAS_ESCAPE = re.compile(r"[\x1b\x80-\x9f]") + + +def strip_ansi(text: str) -> str: + """Remove ANSI escape sequences from text. + + Returns the input unchanged (fast path) when no ESC or C1 bytes are + present. Safe to call on any string — clean text passes through + with negligible overhead. + """ + if not text or not _HAS_ESCAPE.search(text): + return text + return _ANSI_ESCAPE_RE.sub("", text) diff --git a/mindcli/_vendor/tools/approval.py b/mindcli/_vendor/tools/approval.py new file mode 100644 index 0000000..3e9ccdf --- /dev/null +++ b/mindcli/_vendor/tools/approval.py @@ -0,0 +1,921 @@ +"""Dangerous command approval -- detection, prompting, and per-session state. + +This module is the single source of truth for the dangerous command system: +- Pattern detection (DANGEROUS_PATTERNS, detect_dangerous_command) +- Per-session approval state (thread-safe, keyed by session_key) +- Approval prompting (CLI interactive + gateway async) +- Smart approval via auxiliary LLM (auto-approve low-risk commands) +- Permanent allowlist persistence (config.yaml) +""" + +import contextvars +import logging +import os +import re +import sys +import threading +import unicodedata +from typing import Optional + +logger = logging.getLogger(__name__) + +# Per-thread/per-task gateway session identity. +# Gateway runs agent turns concurrently in executor threads, so reading a +# process-global env var for session identity is racy. Keep env fallback for +# legacy single-threaded callers, but prefer the context-local value when set. +_approval_session_key: contextvars.ContextVar[str] = contextvars.ContextVar( + "approval_session_key", + default="", +) + + +def set_current_session_key(session_key: str) -> contextvars.Token[str]: + """Bind the active approval session key to the current context.""" + return _approval_session_key.set(session_key or "") + + +def reset_current_session_key(token: contextvars.Token[str]) -> None: + """Restore the prior approval session key context.""" + _approval_session_key.reset(token) + + +def get_current_session_key(default: str = "default") -> str: + """Return the active session key, preferring context-local state. + + Resolution order: + 1. approval-specific contextvars (set by gateway before agent.run) + 2. session_context contextvars (set by _set_session_env) + 3. os.environ fallback (CLI, cron, tests) + """ + session_key = _approval_session_key.get() + if session_key: + return session_key + from gateway.session_context import get_session_env + return get_session_env("HERMES_SESSION_KEY", default) + +# Sensitive write targets that should trigger approval even when referenced +# via shell expansions like $HOME or $HERMES_HOME. +_SSH_SENSITIVE_PATH = r'(?:~|\$home|\$\{home\})/\.ssh(?:/|$)' +_HERMES_ENV_PATH = ( + r'(?:~\/\.hermes/|' + r'(?:\$home|\$\{home\})/\.hermes/|' + r'(?:\$hermes_home|\$\{hermes_home\})/)' + r'\.env\b' +) +_SENSITIVE_WRITE_TARGET = ( + r'(?:/etc/|/dev/sd|' + rf'{_SSH_SENSITIVE_PATH}|' + rf'{_HERMES_ENV_PATH})' +) + +# ========================================================================= +# Dangerous command patterns +# ========================================================================= + +DANGEROUS_PATTERNS = [ + (r'\brm\s+(-[^\s]*\s+)*/', "delete in root path"), + (r'\brm\s+-[^\s]*r', "recursive delete"), + (r'\brm\s+--recursive\b', "recursive delete (long flag)"), + (r'\bchmod\s+(-[^\s]*\s+)*(777|666|o\+[rwx]*w|a\+[rwx]*w)\b', "world/other-writable permissions"), + (r'\bchmod\s+--recursive\b.*(777|666|o\+[rwx]*w|a\+[rwx]*w)', "recursive world/other-writable (long flag)"), + (r'\bchown\s+(-[^\s]*)?R\s+root', "recursive chown to root"), + (r'\bchown\s+--recursive\b.*root', "recursive chown to root (long flag)"), + (r'\bmkfs\b', "format filesystem"), + (r'\bdd\s+.*if=', "disk copy"), + (r'>\s*/dev/sd', "write to block device"), + (r'\bDROP\s+(TABLE|DATABASE)\b', "SQL DROP"), + (r'\bDELETE\s+FROM\b(?!.*\bWHERE\b)', "SQL DELETE without WHERE"), + (r'\bTRUNCATE\s+(TABLE)?\s*\w', "SQL TRUNCATE"), + (r'>\s*/etc/', "overwrite system config"), + (r'\bsystemctl\s+(stop|disable|mask)\b', "stop/disable system service"), + (r'\bkill\s+-9\s+-1\b', "kill all processes"), + (r'\bpkill\s+-9\b', "force kill processes"), + (r':\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:', "fork bomb"), + # Any shell invocation via -c or combined flags like -lc, -ic, etc. + (r'\b(bash|sh|zsh|ksh)\s+-[^\s]*c(\s+|$)', "shell command via -c/-lc flag"), + (r'\b(python[23]?|perl|ruby|node)\s+-[ec]\s+', "script execution via -e/-c flag"), + (r'\b(curl|wget)\b.*\|\s*(ba)?sh\b', "pipe remote content to shell"), + (r'\b(bash|sh|zsh|ksh)\s+<\s*>?\s*["\']?{_SENSITIVE_WRITE_TARGET}', "overwrite system file via redirection"), + (r'\bxargs\s+.*\brm\b', "xargs with rm"), + (r'\bfind\b.*-exec\s+(/\S*/)?rm\b', "find -exec rm"), + (r'\bfind\b.*-delete\b', "find -delete"), + # Gateway protection: never start gateway outside systemd management + (r'gateway\s+run\b.*(&\s*$|&\s*;|\bdisown\b|\bsetsid\b)', "start gateway outside systemd (use 'systemctl --user restart hermes-gateway')"), + (r'\bnohup\b.*gateway\s+run\b', "start gateway outside systemd (use 'systemctl --user restart hermes-gateway')"), + # Self-termination protection: prevent agent from killing its own process + (r'\b(pkill|killall)\b.*\b(hermes|gateway|cli\.py)\b', "kill hermes/gateway process (self-termination)"), + # Self-termination via kill + command substitution (pgrep/pidof). + # The name-based pattern above catches `pkill hermes` but not + # `kill -9 $(pgrep -f hermes)` because the substitution is opaque + # to regex at detection time. Catch the structural pattern instead. + (r'\bkill\b.*\$\(\s*pgrep\b', "kill process via pgrep expansion (self-termination)"), + (r'\bkill\b.*`\s*pgrep\b', "kill process via backtick pgrep expansion (self-termination)"), + # File copy/move/edit into sensitive system paths + (r'\b(cp|mv|install)\b.*\s/etc/', "copy/move file into /etc/"), + (r'\bsed\s+-[^\s]*i.*\s/etc/', "in-place edit of system config"), + (r'\bsed\s+--in-place\b.*\s/etc/', "in-place edit of system config (long flag)"), + # Script execution via heredoc — bypasses the -e/-c flag patterns above. + # `python3 << 'EOF'` feeds arbitrary code via stdin without -c/-e flags. + (r'\b(python[23]?|perl|ruby|node)\s+<<', "script execution via heredoc"), + # Git destructive operations that can lose uncommitted work or rewrite + # shared history. Not captured by rm/chmod/etc patterns. + (r'\bgit\s+reset\s+--hard\b', "git reset --hard (destroys uncommitted changes)"), + (r'\bgit\s+push\b.*--force\b', "git force push (rewrites remote history)"), + (r'\bgit\s+push\b.*-f\b', "git force push short flag (rewrites remote history)"), + (r'\bgit\s+clean\s+-[^\s]*f', "git clean with force (deletes untracked files)"), + (r'\bgit\s+branch\s+-D\b', "git branch force delete"), + # Script execution after chmod +x — catches the two-step pattern where + # a script is first made executable then immediately run. The script + # content may contain dangerous commands that individual patterns miss. + (r'\bchmod\s+\+x\b.*[;&|]+\s*\./', "chmod +x followed by immediate execution"), +] + + +def _legacy_pattern_key(pattern: str) -> str: + """Reproduce the old regex-derived approval key for backwards compatibility.""" + return pattern.split(r'\b')[1] if r'\b' in pattern else pattern[:20] + + +_PATTERN_KEY_ALIASES: dict[str, set[str]] = {} +for _pattern, _description in DANGEROUS_PATTERNS: + _legacy_key = _legacy_pattern_key(_pattern) + _canonical_key = _description + _PATTERN_KEY_ALIASES.setdefault(_canonical_key, set()).update({_canonical_key, _legacy_key}) + _PATTERN_KEY_ALIASES.setdefault(_legacy_key, set()).update({_legacy_key, _canonical_key}) + + +def _approval_key_aliases(pattern_key: str) -> set[str]: + """Return all approval keys that should match this pattern. + + New approvals use the human-readable description string, but older + command_allowlist entries and session approvals may still contain the + historical regex-derived key. + """ + return _PATTERN_KEY_ALIASES.get(pattern_key, {pattern_key}) + + +# ========================================================================= +# Detection +# ========================================================================= + +def _normalize_command_for_detection(command: str) -> str: + """Normalize a command string before dangerous-pattern matching. + + Strips ANSI escape sequences (full ECMA-48 via tools.ansi_strip), + null bytes, and normalizes Unicode fullwidth characters so that + obfuscation techniques cannot bypass the pattern-based detection. + """ + from tools.ansi_strip import strip_ansi + + # Strip all ANSI escape sequences (CSI, OSC, DCS, 8-bit C1, etc.) + command = strip_ansi(command) + # Strip null bytes + command = command.replace('\x00', '') + # Normalize Unicode (fullwidth Latin, halfwidth Katakana, etc.) + command = unicodedata.normalize('NFKC', command) + return command + + +def detect_dangerous_command(command: str) -> tuple: + """Check if a command matches any dangerous patterns. + + Returns: + (is_dangerous, pattern_key, description) or (False, None, None) + """ + command_lower = _normalize_command_for_detection(command).lower() + for pattern, description in DANGEROUS_PATTERNS: + if re.search(pattern, command_lower, re.IGNORECASE | re.DOTALL): + pattern_key = description + return (True, pattern_key, description) + return (False, None, None) + + +# ========================================================================= +# Per-session approval state (thread-safe) +# ========================================================================= + +_lock = threading.Lock() +_pending: dict[str, dict] = {} +_session_approved: dict[str, set] = {} +_session_yolo: set[str] = set() +_permanent_approved: set = set() + +# ========================================================================= +# Blocking gateway approval (mirrors CLI's synchronous input() flow) +# ========================================================================= +# Per-session QUEUE of pending approvals. Multiple threads (parallel +# subagents, execute_code RPC handlers) can block concurrently — each gets +# its own threading.Event. /approve resolves the oldest, /approve all +# resolves every pending approval in the session. + + +class _ApprovalEntry: + """One pending dangerous-command approval inside a gateway session.""" + __slots__ = ("event", "data", "result") + + def __init__(self, data: dict): + self.event = threading.Event() + self.data = data # command, description, pattern_keys, … + self.result: Optional[str] = None # "once"|"session"|"always"|"deny" + + +_gateway_queues: dict[str, list] = {} # session_key → [_ApprovalEntry, …] +_gateway_notify_cbs: dict[str, object] = {} # session_key → callable(approval_data) + + +def register_gateway_notify(session_key: str, cb) -> None: + """Register a per-session callback for sending approval requests to the user. + + The callback signature is ``cb(approval_data: dict) -> None`` where + *approval_data* contains ``command``, ``description``, and + ``pattern_keys``. The callback bridges sync→async (runs in the agent + thread, must schedule the actual send on the event loop). + """ + with _lock: + _gateway_notify_cbs[session_key] = cb + + +def unregister_gateway_notify(session_key: str) -> None: + """Unregister the per-session gateway approval callback. + + Signals ALL blocked threads for this session so they don't hang forever + (e.g. when the agent run finishes or is interrupted). + """ + with _lock: + _gateway_notify_cbs.pop(session_key, None) + entries = _gateway_queues.pop(session_key, []) + for entry in entries: + entry.event.set() + + +def resolve_gateway_approval(session_key: str, choice: str, + resolve_all: bool = False) -> int: + """Called by the gateway's /approve or /deny handler to unblock + waiting agent thread(s). + + When *resolve_all* is True every pending approval in the session is + resolved at once (``/approve all``). Otherwise only the oldest one + is resolved (FIFO). + + Returns the number of approvals resolved (0 means nothing was pending). + """ + with _lock: + queue = _gateway_queues.get(session_key) + if not queue: + return 0 + if resolve_all: + targets = list(queue) + queue.clear() + else: + targets = [queue.pop(0)] + if not queue: + _gateway_queues.pop(session_key, None) + + for entry in targets: + entry.result = choice + entry.event.set() + return len(targets) + + +def has_blocking_approval(session_key: str) -> bool: + """Check if a session has one or more blocking gateway approvals waiting.""" + with _lock: + return bool(_gateway_queues.get(session_key)) + + +def submit_pending(session_key: str, approval: dict): + """Store a pending approval request for a session.""" + with _lock: + _pending[session_key] = approval + + +def approve_session(session_key: str, pattern_key: str): + """Approve a pattern for this session only.""" + with _lock: + _session_approved.setdefault(session_key, set()).add(pattern_key) + + +def enable_session_yolo(session_key: str) -> None: + """Enable YOLO bypass for a single session key.""" + if not session_key: + return + with _lock: + _session_yolo.add(session_key) + + +def disable_session_yolo(session_key: str) -> None: + """Disable YOLO bypass for a single session key.""" + if not session_key: + return + with _lock: + _session_yolo.discard(session_key) + + +def clear_session(session_key: str) -> None: + """Remove all approval and yolo state for a given session.""" + if not session_key: + return + with _lock: + _session_approved.pop(session_key, None) + _session_yolo.discard(session_key) + _pending.pop(session_key, None) + _gateway_queues.pop(session_key, None) + + +def is_session_yolo_enabled(session_key: str) -> bool: + """Return True when YOLO bypass is enabled for a specific session.""" + if not session_key: + return False + with _lock: + return session_key in _session_yolo + + +def is_current_session_yolo_enabled() -> bool: + """Return True when the active approval session has YOLO bypass enabled.""" + return is_session_yolo_enabled(get_current_session_key(default="")) + + +def is_approved(session_key: str, pattern_key: str) -> bool: + """Check if a pattern is approved (session-scoped or permanent). + + Accept both the current canonical key and the legacy regex-derived key so + existing command_allowlist entries continue to work after key migrations. + """ + aliases = _approval_key_aliases(pattern_key) + with _lock: + if any(alias in _permanent_approved for alias in aliases): + return True + session_approvals = _session_approved.get(session_key, set()) + return any(alias in session_approvals for alias in aliases) + + +def approve_permanent(pattern_key: str): + """Add a pattern to the permanent allowlist.""" + with _lock: + _permanent_approved.add(pattern_key) + + +def load_permanent(patterns: set): + """Bulk-load permanent allowlist entries from config.""" + with _lock: + _permanent_approved.update(patterns) + + + +# ========================================================================= +# Config persistence for permanent allowlist +# ========================================================================= + +def load_permanent_allowlist() -> set: + """Load permanently allowed command patterns from config. + + Also syncs them into the approval module so is_approved() works for + patterns added via 'always' in a previous session. + """ + try: + from hermes_cli.config import load_config + config = load_config() + patterns = set(config.get("command_allowlist", []) or []) + if patterns: + load_permanent(patterns) + return patterns + except Exception as e: + logger.warning("Failed to load permanent allowlist: %s", e) + return set() + + +def save_permanent_allowlist(patterns: set): + """Save permanently allowed command patterns to config.""" + try: + from hermes_cli.config import load_config, save_config + config = load_config() + config["command_allowlist"] = list(patterns) + save_config(config) + except Exception as e: + logger.warning("Could not save allowlist: %s", e) + + +# ========================================================================= +# Approval prompting + orchestration +# ========================================================================= + +def prompt_dangerous_approval(command: str, description: str, + timeout_seconds: int | None = None, + allow_permanent: bool = True, + approval_callback=None) -> str: + """Prompt the user to approve a dangerous command (CLI only). + + Args: + allow_permanent: When False, hide the [a]lways option (used when + tirith warnings are present, since broad permanent allowlisting + is inappropriate for content-level security findings). + approval_callback: Optional callback registered by the CLI for + prompt_toolkit integration. Signature: + (command, description, *, allow_permanent=True) -> str. + + Returns: 'once', 'session', 'always', or 'deny' + """ + if timeout_seconds is None: + timeout_seconds = _get_approval_timeout() + + if approval_callback is not None: + try: + return approval_callback(command, description, + allow_permanent=allow_permanent) + except Exception as e: + logger.error("Approval callback failed: %s", e, exc_info=True) + return "deny" + + os.environ["HERMES_SPINNER_PAUSE"] = "1" + try: + while True: + print() + print(f" ⚠️ DANGEROUS COMMAND: {description}") + print(f" {command}") + print() + if allow_permanent: + print(" [o]nce | [s]ession | [a]lways | [d]eny") + else: + print(" [o]nce | [s]ession | [d]eny") + print() + sys.stdout.flush() + + result = {"choice": ""} + + def get_input(): + try: + prompt = " Choice [o/s/a/D]: " if allow_permanent else " Choice [o/s/D]: " + result["choice"] = input(prompt).strip().lower() + except (EOFError, OSError): + result["choice"] = "" + + thread = threading.Thread(target=get_input, daemon=True) + thread.start() + thread.join(timeout=timeout_seconds) + + if thread.is_alive(): + print("\n ⏱ Timeout - denying command") + return "deny" + + choice = result["choice"] + if choice in ('o', 'once'): + print(" ✓ Allowed once") + return "once" + elif choice in ('s', 'session'): + print(" ✓ Allowed for this session") + return "session" + elif choice in ('a', 'always'): + if not allow_permanent: + print(" ✓ Allowed for this session") + return "session" + print(" ✓ Added to permanent allowlist") + return "always" + else: + print(" ✗ Denied") + return "deny" + + except (EOFError, KeyboardInterrupt): + print("\n ✗ Cancelled") + return "deny" + finally: + if "HERMES_SPINNER_PAUSE" in os.environ: + del os.environ["HERMES_SPINNER_PAUSE"] + print() + sys.stdout.flush() + + +def _normalize_approval_mode(mode) -> str: + """Normalize approval mode values loaded from YAML/config. + + YAML 1.1 treats bare words like `off` as booleans, so a config entry like + `approvals:\n mode: off` is parsed as False unless quoted. Treat that as the + intended string mode instead of falling back to manual approvals. + """ + if isinstance(mode, bool): + return "off" if mode is False else "manual" + if isinstance(mode, str): + normalized = mode.strip().lower() + return normalized or "manual" + return "manual" + + +def _get_approval_config() -> dict: + """Read the approvals config block. Returns a dict with 'mode', 'timeout', etc.""" + try: + from hermes_cli.config import load_config + config = load_config() + return config.get("approvals", {}) or {} + except Exception as e: + logger.warning("Failed to load approval config: %s", e) + return {} + + +def _get_approval_mode() -> str: + """Read the approval mode from config. Returns 'manual', 'smart', or 'off'.""" + mode = _get_approval_config().get("mode", "manual") + return _normalize_approval_mode(mode) + + +def _get_approval_timeout() -> int: + """Read the approval timeout from config. Defaults to 60 seconds.""" + try: + return int(_get_approval_config().get("timeout", 60)) + except (ValueError, TypeError): + return 60 + + +def _smart_approve(command: str, description: str) -> str: + """Use the auxiliary LLM to assess risk and decide approval. + + Returns 'approve' if the LLM determines the command is safe, + 'deny' if genuinely dangerous, or 'escalate' if uncertain. + + Inspired by OpenAI Codex's Smart Approvals guardian subagent + (openai/codex#13860). + """ + try: + from agent.auxiliary_client import get_text_auxiliary_client, auxiliary_max_tokens_param + + client, model = get_text_auxiliary_client(task="approval") + if not client or not model: + logger.debug("Smart approvals: no aux client available, escalating") + return "escalate" + + prompt = f"""You are a security reviewer for an AI coding agent. A terminal command was flagged by pattern matching as potentially dangerous. + +Command: {command} +Flagged reason: {description} + +Assess the ACTUAL risk of this command. Many flagged commands are false positives — for example, `python -c "print('hello')"` is flagged as "script execution via -c flag" but is completely harmless. + +Rules: +- APPROVE if the command is clearly safe (benign script execution, safe file operations, development tools, package installs, git operations, etc.) +- DENY if the command could genuinely damage the system (recursive delete of important paths, overwriting system files, fork bombs, wiping disks, dropping databases, etc.) +- ESCALATE if you're uncertain + +Respond with exactly one word: APPROVE, DENY, or ESCALATE""" + + response = client.chat.completions.create( + model=model, + messages=[{"role": "user", "content": prompt}], + **auxiliary_max_tokens_param(16), + temperature=0, + ) + + answer = (response.choices[0].message.content or "").strip().upper() + + if "APPROVE" in answer: + return "approve" + elif "DENY" in answer: + return "deny" + else: + return "escalate" + + except Exception as e: + logger.debug("Smart approvals: LLM call failed (%s), escalating", e) + return "escalate" + + +def check_dangerous_command(command: str, env_type: str, + approval_callback=None) -> dict: + """Check if a command is dangerous and handle approval. + + This is the main entry point called by terminal_tool before executing + any command. It orchestrates detection, session checks, and prompting. + + Args: + command: The shell command to check. + env_type: Terminal backend type ('local', 'ssh', 'docker', etc.). + approval_callback: Optional CLI callback for interactive prompts. + + Returns: + {"approved": True/False, "message": str or None, ...} + """ + if env_type in ("docker", "singularity", "modal", "daytona"): + return {"approved": True, "message": None} + + # --yolo: bypass all approval prompts. Gateway /yolo is session-scoped; + # CLI --yolo remains process-scoped via the env var for local use. + if os.getenv("HERMES_YOLO_MODE") or is_current_session_yolo_enabled(): + return {"approved": True, "message": None} + + is_dangerous, pattern_key, description = detect_dangerous_command(command) + if not is_dangerous: + return {"approved": True, "message": None} + + session_key = get_current_session_key() + if is_approved(session_key, pattern_key): + return {"approved": True, "message": None} + + is_cli = os.getenv("HERMES_INTERACTIVE") + is_gateway = os.getenv("HERMES_GATEWAY_SESSION") + + if not is_cli and not is_gateway: + return {"approved": True, "message": None} + + if is_gateway or os.getenv("HERMES_EXEC_ASK"): + submit_pending(session_key, { + "command": command, + "pattern_key": pattern_key, + "description": description, + }) + return { + "approved": False, + "pattern_key": pattern_key, + "status": "approval_required", + "command": command, + "description": description, + "message": ( + f"⚠️ This command is potentially dangerous ({description}). " + f"Asking the user for approval.\n\n**Command:**\n```\n{command}\n```" + ), + } + + choice = prompt_dangerous_approval(command, description, + approval_callback=approval_callback) + + if choice == "deny": + return { + "approved": False, + "message": f"BLOCKED: User denied this potentially dangerous command (matched '{description}' pattern). Do NOT retry this command - the user has explicitly rejected it.", + "pattern_key": pattern_key, + "description": description, + } + + if choice == "session": + approve_session(session_key, pattern_key) + elif choice == "always": + approve_session(session_key, pattern_key) + approve_permanent(pattern_key) + save_permanent_allowlist(_permanent_approved) + + return {"approved": True, "message": None} + + +# ========================================================================= +# Combined pre-exec guard (tirith + dangerous command detection) +# ========================================================================= + +def _format_tirith_description(tirith_result: dict) -> str: + """Build a human-readable description from tirith findings. + + Includes severity, title, and description for each finding so users + can make an informed approval decision. + """ + findings = tirith_result.get("findings") or [] + if not findings: + summary = tirith_result.get("summary") or "security issue detected" + return f"Security scan: {summary}" + + parts = [] + for f in findings: + severity = f.get("severity", "") + title = f.get("title", "") + desc = f.get("description", "") + if title and desc: + parts.append(f"[{severity}] {title}: {desc}" if severity else f"{title}: {desc}") + elif title: + parts.append(f"[{severity}] {title}" if severity else title) + if not parts: + summary = tirith_result.get("summary") or "security issue detected" + return f"Security scan: {summary}" + + return "Security scan — " + "; ".join(parts) + + +def check_all_command_guards(command: str, env_type: str, + approval_callback=None) -> dict: + """Run all pre-exec security checks and return a single approval decision. + + Gathers findings from tirith and dangerous-command detection, then + presents them as a single combined approval request. This prevents + a gateway force=True replay from bypassing one check when only the + other was shown to the user. + """ + # Skip containers for both checks + if env_type in ("docker", "singularity", "modal", "daytona"): + return {"approved": True, "message": None} + + # --yolo or approvals.mode=off: bypass all approval prompts. + # Gateway /yolo is session-scoped; CLI --yolo remains process-scoped. + approval_mode = _get_approval_mode() + if os.getenv("HERMES_YOLO_MODE") or is_current_session_yolo_enabled() or approval_mode == "off": + return {"approved": True, "message": None} + + is_cli = os.getenv("HERMES_INTERACTIVE") + is_gateway = os.getenv("HERMES_GATEWAY_SESSION") + is_ask = os.getenv("HERMES_EXEC_ASK") + + # Preserve the existing non-interactive behavior: outside CLI/gateway/ask + # flows, we do not block on approvals and we skip external guard work. + if not is_cli and not is_gateway and not is_ask: + return {"approved": True, "message": None} + + # --- Phase 1: Gather findings from both checks --- + + # Tirith check — wrapper guarantees no raise for expected failures. + # Only catch ImportError (module not installed). + tirith_result = {"action": "allow", "findings": [], "summary": ""} + try: + from tools.tirith_security import check_command_security + tirith_result = check_command_security(command) + except ImportError: + pass # tirith module not installed — allow + + # Dangerous command check (detection only, no approval) + is_dangerous, pattern_key, description = detect_dangerous_command(command) + + # --- Phase 2: Decide --- + + # Collect warnings that need approval + warnings = [] # list of (pattern_key, description, is_tirith) + + session_key = get_current_session_key() + + # Tirith block/warn → approvable warning with rich findings. + # Previously, tirith "block" was a hard block with no approval prompt. + # Now both block and warn go through the approval flow so users can + # inspect the explanation and approve if they understand the risk. + if tirith_result["action"] in ("block", "warn"): + findings = tirith_result.get("findings") or [] + rule_id = findings[0].get("rule_id", "unknown") if findings else "unknown" + tirith_key = f"tirith:{rule_id}" + tirith_desc = _format_tirith_description(tirith_result) + if not is_approved(session_key, tirith_key): + warnings.append((tirith_key, tirith_desc, True)) + + if is_dangerous: + if not is_approved(session_key, pattern_key): + warnings.append((pattern_key, description, False)) + + # Nothing to warn about + if not warnings: + return {"approved": True, "message": None} + + # --- Phase 2.5: Smart approval (auxiliary LLM risk assessment) --- + # When approvals.mode=smart, ask the aux LLM before prompting the user. + # Inspired by OpenAI Codex's Smart Approvals guardian subagent + # (openai/codex#13860). + if approval_mode == "smart": + combined_desc_for_llm = "; ".join(desc for _, desc, _ in warnings) + verdict = _smart_approve(command, combined_desc_for_llm) + if verdict == "approve": + # Auto-approve and grant session-level approval for these patterns + for key, _, _ in warnings: + approve_session(session_key, key) + logger.debug("Smart approval: auto-approved '%s' (%s)", + command[:60], combined_desc_for_llm) + return {"approved": True, "message": None, + "smart_approved": True, + "description": combined_desc_for_llm} + elif verdict == "deny": + combined_desc_for_llm = "; ".join(desc for _, desc, _ in warnings) + return { + "approved": False, + "message": f"BLOCKED by smart approval: {combined_desc_for_llm}. " + "The command was assessed as genuinely dangerous. Do NOT retry.", + "smart_denied": True, + } + # verdict == "escalate" → fall through to manual prompt + + # --- Phase 3: Approval --- + + # Combine descriptions for a single approval prompt + combined_desc = "; ".join(desc for _, desc, _ in warnings) + primary_key = warnings[0][0] + all_keys = [key for key, _, _ in warnings] + has_tirith = any(is_t for _, _, is_t in warnings) + + # Gateway/async approval — block the agent thread until the user + # responds with /approve or /deny, mirroring the CLI's synchronous + # input() flow. The agent never sees "approval_required"; it either + # gets the command output (approved) or a definitive "BLOCKED" message. + if is_gateway or is_ask: + notify_cb = None + with _lock: + notify_cb = _gateway_notify_cbs.get(session_key) + + if notify_cb is not None: + # --- Blocking gateway approval (queue-based) --- + # Each call gets its own _ApprovalEntry so parallel subagents + # and execute_code threads can block concurrently. + approval_data = { + "command": command, + "pattern_key": primary_key, + "pattern_keys": all_keys, + "description": combined_desc, + } + entry = _ApprovalEntry(approval_data) + with _lock: + _gateway_queues.setdefault(session_key, []).append(entry) + + # Notify the user (bridges sync agent thread → async gateway) + try: + notify_cb(approval_data) + except Exception as exc: + logger.warning("Gateway approval notify failed: %s", exc) + with _lock: + queue = _gateway_queues.get(session_key, []) + if entry in queue: + queue.remove(entry) + if not queue: + _gateway_queues.pop(session_key, None) + return { + "approved": False, + "message": "BLOCKED: Failed to send approval request to user. Do NOT retry.", + "pattern_key": primary_key, + "description": combined_desc, + } + + # Block until the user responds or timeout (default 5 min) + timeout = _get_approval_config().get("gateway_timeout", 300) + try: + timeout = int(timeout) + except (ValueError, TypeError): + timeout = 300 + resolved = entry.event.wait(timeout=timeout) + + # Clean up this entry from the queue + with _lock: + queue = _gateway_queues.get(session_key, []) + if entry in queue: + queue.remove(entry) + if not queue: + _gateway_queues.pop(session_key, None) + + choice = entry.result + if not resolved or choice is None or choice == "deny": + reason = "timed out" if not resolved else "denied by user" + return { + "approved": False, + "message": f"BLOCKED: Command {reason}. Do NOT retry this command.", + "pattern_key": primary_key, + "description": combined_desc, + } + + # User approved — persist based on scope (same logic as CLI) + for key, _, is_tirith in warnings: + if choice == "session" or (choice == "always" and is_tirith): + approve_session(session_key, key) + elif choice == "always": + approve_session(session_key, key) + approve_permanent(key) + save_permanent_allowlist(_permanent_approved) + # choice == "once": no persistence — command allowed this + # single time only, matching the CLI's behavior. + + return {"approved": True, "message": None, + "user_approved": True, "description": combined_desc} + + # Fallback: no gateway callback registered (e.g. cron, batch). + # Return approval_required for backward compat. + submit_pending(session_key, { + "command": command, + "pattern_key": primary_key, + "pattern_keys": all_keys, + "description": combined_desc, + }) + return { + "approved": False, + "pattern_key": primary_key, + "status": "approval_required", + "command": command, + "description": combined_desc, + "message": ( + f"⚠️ {combined_desc}. Asking the user for approval.\n\n**Command:**\n```\n{command}\n```" + ), + } + + # CLI interactive: single combined prompt + # Hide [a]lways when any tirith warning is present + choice = prompt_dangerous_approval(command, combined_desc, + allow_permanent=not has_tirith, + approval_callback=approval_callback) + + if choice == "deny": + return { + "approved": False, + "message": "BLOCKED: User denied. Do NOT retry.", + "pattern_key": primary_key, + "description": combined_desc, + } + + # Persist approval for each warning individually + for key, _, is_tirith in warnings: + if choice == "session" or (choice == "always" and is_tirith): + # tirith: session only (no permanent broad allowlisting) + approve_session(session_key, key) + elif choice == "always": + # dangerous patterns: permanent allowed + approve_session(session_key, key) + approve_permanent(key) + save_permanent_allowlist(_permanent_approved) + + return {"approved": True, "message": None, + "user_approved": True, "description": combined_desc} + + +# Load permanent allowlist from config on module import +load_permanent_allowlist() diff --git a/mindcli/_vendor/tools/binary_extensions.py b/mindcli/_vendor/tools/binary_extensions.py new file mode 100644 index 0000000..bd4bb8d --- /dev/null +++ b/mindcli/_vendor/tools/binary_extensions.py @@ -0,0 +1,42 @@ +"""Binary file extensions to skip for text-based operations. + +These files can't be meaningfully compared as text and are often large. +Ported from free-code src/constants/files.ts. +""" + +BINARY_EXTENSIONS = frozenset({ + # Images + ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".webp", ".tiff", ".tif", + # Videos + ".mp4", ".mov", ".avi", ".mkv", ".webm", ".wmv", ".flv", ".m4v", ".mpeg", ".mpg", + # Audio + ".mp3", ".wav", ".ogg", ".flac", ".aac", ".m4a", ".wma", ".aiff", ".opus", + # Archives + ".zip", ".tar", ".gz", ".bz2", ".7z", ".rar", ".xz", ".z", ".tgz", ".iso", + # Executables/binaries + ".exe", ".dll", ".so", ".dylib", ".bin", ".o", ".a", ".obj", ".lib", + ".app", ".msi", ".deb", ".rpm", + # Documents (exclude .pdf — text-based, agents may want to inspect) + ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx", + ".odt", ".ods", ".odp", + # Fonts + ".ttf", ".otf", ".woff", ".woff2", ".eot", + # Bytecode / VM artifacts + ".pyc", ".pyo", ".class", ".jar", ".war", ".ear", ".node", ".wasm", ".rlib", + # Database files + ".sqlite", ".sqlite3", ".db", ".mdb", ".idx", + # Design / 3D + ".psd", ".ai", ".eps", ".sketch", ".fig", ".xd", ".blend", ".3ds", ".max", + # Flash + ".swf", ".fla", + # Lock/profiling data + ".lockb", ".dat", ".data", +}) + + +def has_binary_extension(path: str) -> bool: + """Check if a file path has a binary extension. Pure string check, no I/O.""" + dot = path.rfind(".") + if dot == -1: + return False + return path[dot:].lower() in BINARY_EXTENSIONS diff --git a/mindcli/_vendor/tools/browser_camofox.py b/mindcli/_vendor/tools/browser_camofox.py new file mode 100644 index 0000000..fbd1c96 --- /dev/null +++ b/mindcli/_vendor/tools/browser_camofox.py @@ -0,0 +1,592 @@ +"""Camofox browser backend — local anti-detection browser via REST API. + +Camofox-browser is a self-hosted Node.js server wrapping Camoufox (Firefox +fork with C++ fingerprint spoofing). It exposes a REST API that maps 1:1 +to our browser tool interface: accessibility snapshots with element refs, +click/type/scroll by ref, screenshots, etc. + +When ``CAMOFOX_URL`` is set (e.g. ``http://localhost:9377``), the browser +tools route through this module instead of the ``agent-browser`` CLI. + +Setup:: + + # Option 1: npm + git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser + npm install && npm start # downloads Camoufox (~300MB) on first run + + # Option 2: Docker + docker run -p 9377:9377 -e CAMOFOX_PORT=9377 jo-inc/camofox-browser + +Then set ``CAMOFOX_URL=http://localhost:9377`` in ``~/.hermes/.env``. +""" + +from __future__ import annotations + +import base64 +import json +import logging +import os +import threading +import uuid +from typing import Any, Dict, Optional + +import requests + +from hermes_cli.config import load_config +from tools.browser_camofox_state import get_camofox_identity +from tools.registry import tool_error + +logger = logging.getLogger(__name__) + +# --------------------------------------------------------------------------- +# Configuration +# --------------------------------------------------------------------------- + +_DEFAULT_TIMEOUT = 30 # seconds per HTTP request +_SNAPSHOT_MAX_CHARS = 80_000 # camofox paginates at this limit +_vnc_url: Optional[str] = None # cached from /health response +_vnc_url_checked = False # only probe once per process + + +def get_camofox_url() -> str: + """Return the configured Camofox server URL, or empty string.""" + return os.getenv("CAMOFOX_URL", "").rstrip("/") + + +def is_camofox_mode() -> bool: + """True when Camofox backend is configured.""" + return bool(get_camofox_url()) + + +def check_camofox_available() -> bool: + """Verify the Camofox server is reachable.""" + global _vnc_url, _vnc_url_checked + url = get_camofox_url() + if not url: + return False + try: + resp = requests.get(f"{url}/health", timeout=5) + if resp.status_code == 200 and not _vnc_url_checked: + try: + data = resp.json() + vnc_port = data.get("vncPort") + if isinstance(vnc_port, int) and 1 <= vnc_port <= 65535: + from urllib.parse import urlparse + parsed = urlparse(url) + host = parsed.hostname or "localhost" + _vnc_url = f"http://{host}:{vnc_port}" + except (ValueError, KeyError): + pass + _vnc_url_checked = True + return resp.status_code == 200 + except Exception: + return False + + +def get_vnc_url() -> Optional[str]: + """Return the VNC URL if the Camofox server exposes one, or None.""" + if not _vnc_url_checked: + check_camofox_available() + return _vnc_url + + +def _managed_persistence_enabled() -> bool: + """Return whether Hermes-managed persistence is enabled for Camofox. + + When enabled, sessions use a stable profile-scoped userId so the + Camofox server can map it to a persistent browser profile directory. + When disabled (default), each session gets a random userId (ephemeral). + + Controlled by ``browser.camofox.managed_persistence`` in config.yaml. + """ + try: + camofox_cfg = load_config().get("browser", {}).get("camofox", {}) + except Exception as exc: + logger.warning("managed_persistence check failed, defaulting to disabled: %s", exc) + return False + return bool(camofox_cfg.get("managed_persistence")) + + +# --------------------------------------------------------------------------- +# Session management +# --------------------------------------------------------------------------- +# Maps task_id -> {"user_id": str, "tab_id": str|None} +_sessions: Dict[str, Dict[str, Any]] = {} +_sessions_lock = threading.Lock() + + +def _get_session(task_id: Optional[str]) -> Dict[str, Any]: + """Get or create a camofox session for the given task. + + When managed persistence is enabled, uses a deterministic userId + derived from the Hermes profile so the Camofox server can map it + to the same persistent browser profile across restarts. + """ + task_id = task_id or "default" + with _sessions_lock: + if task_id in _sessions: + return _sessions[task_id] + if _managed_persistence_enabled(): + identity = get_camofox_identity(task_id) + session = { + "user_id": identity["user_id"], + "tab_id": None, + "session_key": identity["session_key"], + "managed": True, + } + else: + session = { + "user_id": f"hermes_{uuid.uuid4().hex[:10]}", + "tab_id": None, + "session_key": f"task_{task_id[:16]}", + "managed": False, + } + _sessions[task_id] = session + return session + + +def _ensure_tab(task_id: Optional[str], url: str = "about:blank") -> Dict[str, Any]: + """Ensure a tab exists for the session, creating one if needed.""" + session = _get_session(task_id) + if session["tab_id"]: + return session + base = get_camofox_url() + resp = requests.post( + f"{base}/tabs", + json={ + "userId": session["user_id"], + "sessionKey": session["session_key"], + "url": url, + }, + timeout=_DEFAULT_TIMEOUT, + ) + resp.raise_for_status() + data = resp.json() + session["tab_id"] = data.get("tabId") + return session + + +def _drop_session(task_id: Optional[str]) -> Optional[Dict[str, Any]]: + """Remove and return session info.""" + task_id = task_id or "default" + with _sessions_lock: + return _sessions.pop(task_id, None) + + +def camofox_soft_cleanup(task_id: Optional[str] = None) -> bool: + """Release the in-memory session without destroying the server-side context. + + When managed persistence is enabled the browser profile (and its cookies) + must survive across agent tasks. This helper drops only the local tracking + entry and returns ``True``. When managed persistence is *not* enabled it + does nothing and returns ``False`` so the caller can fall back to + :func:`camofox_close`. + """ + if _managed_persistence_enabled(): + _drop_session(task_id) + logger.debug("Camofox soft cleanup for task %s (managed persistence)", task_id) + return True + return False + + +# --------------------------------------------------------------------------- +# HTTP helpers +# --------------------------------------------------------------------------- + +def _post(path: str, body: dict, timeout: int = _DEFAULT_TIMEOUT) -> dict: + """POST JSON to camofox and return parsed response.""" + url = f"{get_camofox_url()}{path}" + resp = requests.post(url, json=body, timeout=timeout) + resp.raise_for_status() + return resp.json() + + +def _get(path: str, params: dict = None, timeout: int = _DEFAULT_TIMEOUT) -> dict: + """GET from camofox and return parsed response.""" + url = f"{get_camofox_url()}{path}" + resp = requests.get(url, params=params, timeout=timeout) + resp.raise_for_status() + return resp.json() + + +def _get_raw(path: str, params: dict = None, timeout: int = _DEFAULT_TIMEOUT) -> requests.Response: + """GET from camofox and return raw response (for binary data).""" + url = f"{get_camofox_url()}{path}" + resp = requests.get(url, params=params, timeout=timeout) + resp.raise_for_status() + return resp + + +def _delete(path: str, body: dict = None, timeout: int = _DEFAULT_TIMEOUT) -> dict: + """DELETE to camofox and return parsed response.""" + url = f"{get_camofox_url()}{path}" + resp = requests.delete(url, json=body, timeout=timeout) + resp.raise_for_status() + return resp.json() + + +# --------------------------------------------------------------------------- +# Tool implementations +# --------------------------------------------------------------------------- + +def camofox_navigate(url: str, task_id: Optional[str] = None) -> str: + """Navigate to a URL via Camofox.""" + try: + session = _get_session(task_id) + if not session["tab_id"]: + # Create tab with the target URL directly + session = _ensure_tab(task_id, url) + data = {"ok": True, "url": url} + else: + # Navigate existing tab + data = _post( + f"/tabs/{session['tab_id']}/navigate", + {"userId": session["user_id"], "url": url}, + timeout=60, + ) + result = { + "success": True, + "url": data.get("url", url), + "title": data.get("title", ""), + } + vnc = get_vnc_url() + if vnc: + result["vnc_url"] = vnc + result["vnc_hint"] = ( + "Browser is visible via VNC. " + "Share this link with the user so they can watch the browser live." + ) + + # Auto-take a compact snapshot so the model can act immediately + try: + snap_data = _get( + f"/tabs/{session['tab_id']}/snapshot", + params={"userId": session["user_id"]}, + ) + snapshot_text = snap_data.get("snapshot", "") + from tools.browser_tool import ( + SNAPSHOT_SUMMARIZE_THRESHOLD, + _truncate_snapshot, + ) + if len(snapshot_text) > SNAPSHOT_SUMMARIZE_THRESHOLD: + snapshot_text = _truncate_snapshot(snapshot_text) + result["snapshot"] = snapshot_text + result["element_count"] = snap_data.get("refsCount", 0) + except Exception: + pass # Navigation succeeded; snapshot is a bonus + + return json.dumps(result) + except requests.HTTPError as e: + return tool_error(f"Navigation failed: {e}", success=False) + except requests.ConnectionError: + return json.dumps({ + "success": False, + "error": f"Cannot connect to Camofox at {get_camofox_url()}. " + "Is the server running? Start with: npm start (in camofox-browser dir) " + "or: docker run -p 9377:9377 -e CAMOFOX_PORT=9377 jo-inc/camofox-browser", + }) + except Exception as e: + return tool_error(str(e), success=False) + + +def camofox_snapshot(full: bool = False, task_id: Optional[str] = None, + user_task: Optional[str] = None) -> str: + """Get accessibility tree snapshot from Camofox.""" + try: + session = _get_session(task_id) + if not session["tab_id"]: + return tool_error("No browser session. Call browser_navigate first.", success=False) + + data = _get( + f"/tabs/{session['tab_id']}/snapshot", + params={"userId": session["user_id"]}, + ) + + snapshot = data.get("snapshot", "") + refs_count = data.get("refsCount", 0) + + # Apply same summarization logic as the main browser tool + from tools.browser_tool import ( + SNAPSHOT_SUMMARIZE_THRESHOLD, + _extract_relevant_content, + _truncate_snapshot, + ) + + if len(snapshot) > SNAPSHOT_SUMMARIZE_THRESHOLD: + if user_task: + snapshot = _extract_relevant_content(snapshot, user_task) + else: + snapshot = _truncate_snapshot(snapshot) + + return json.dumps({ + "success": True, + "snapshot": snapshot, + "element_count": refs_count, + }) + except Exception as e: + return tool_error(str(e), success=False) + + +def camofox_click(ref: str, task_id: Optional[str] = None) -> str: + """Click an element by ref via Camofox.""" + try: + session = _get_session(task_id) + if not session["tab_id"]: + return tool_error("No browser session. Call browser_navigate first.", success=False) + + # Strip @ prefix if present (our tool convention) + clean_ref = ref.lstrip("@") + + data = _post( + f"/tabs/{session['tab_id']}/click", + {"userId": session["user_id"], "ref": clean_ref}, + ) + return json.dumps({ + "success": True, + "clicked": clean_ref, + "url": data.get("url", ""), + }) + except Exception as e: + return tool_error(str(e), success=False) + + +def camofox_type(ref: str, text: str, task_id: Optional[str] = None) -> str: + """Type text into an element by ref via Camofox.""" + try: + session = _get_session(task_id) + if not session["tab_id"]: + return tool_error("No browser session. Call browser_navigate first.", success=False) + + clean_ref = ref.lstrip("@") + + _post( + f"/tabs/{session['tab_id']}/type", + {"userId": session["user_id"], "ref": clean_ref, "text": text}, + ) + return json.dumps({ + "success": True, + "typed": text, + "element": clean_ref, + }) + except Exception as e: + return tool_error(str(e), success=False) + + +def camofox_scroll(direction: str, task_id: Optional[str] = None) -> str: + """Scroll the page via Camofox.""" + try: + session = _get_session(task_id) + if not session["tab_id"]: + return tool_error("No browser session. Call browser_navigate first.", success=False) + + _post( + f"/tabs/{session['tab_id']}/scroll", + {"userId": session["user_id"], "direction": direction}, + ) + return json.dumps({"success": True, "scrolled": direction}) + except Exception as e: + return tool_error(str(e), success=False) + + +def camofox_back(task_id: Optional[str] = None) -> str: + """Navigate back via Camofox.""" + try: + session = _get_session(task_id) + if not session["tab_id"]: + return tool_error("No browser session. Call browser_navigate first.", success=False) + + data = _post( + f"/tabs/{session['tab_id']}/back", + {"userId": session["user_id"]}, + ) + return json.dumps({"success": True, "url": data.get("url", "")}) + except Exception as e: + return tool_error(str(e), success=False) + + +def camofox_press(key: str, task_id: Optional[str] = None) -> str: + """Press a keyboard key via Camofox.""" + try: + session = _get_session(task_id) + if not session["tab_id"]: + return tool_error("No browser session. Call browser_navigate first.", success=False) + + _post( + f"/tabs/{session['tab_id']}/press", + {"userId": session["user_id"], "key": key}, + ) + return json.dumps({"success": True, "pressed": key}) + except Exception as e: + return tool_error(str(e), success=False) + + +def camofox_close(task_id: Optional[str] = None) -> str: + """Close the browser session via Camofox.""" + try: + session = _drop_session(task_id) + if not session: + return json.dumps({"success": True, "closed": True}) + + _delete( + f"/sessions/{session['user_id']}", + ) + return json.dumps({"success": True, "closed": True}) + except Exception as e: + return json.dumps({"success": True, "closed": True, "warning": str(e)}) + + +def camofox_get_images(task_id: Optional[str] = None) -> str: + """Get images on the current page via Camofox. + + Extracts image information from the accessibility tree snapshot, + since Camofox does not expose a dedicated /images endpoint. + """ + try: + session = _get_session(task_id) + if not session["tab_id"]: + return tool_error("No browser session. Call browser_navigate first.", success=False) + + import re + + data = _get( + f"/tabs/{session['tab_id']}/snapshot", + params={"userId": session["user_id"]}, + ) + snapshot = data.get("snapshot", "") + + # Parse img elements from the accessibility tree. + # Format: img "alt text" or img "alt text" [eN] + # URLs appear on /url: lines following img entries + images = [] + lines = snapshot.split("\n") + for i, line in enumerate(lines): + stripped = line.strip() + if stripped.startswith(("- img ", "img ")): + alt_match = re.search(r'img\s+"([^"]*)"', stripped) + alt = alt_match.group(1) if alt_match else "" + # Look for URL on the next line + src = "" + if i + 1 < len(lines): + url_match = re.search(r'/url:\s*(\S+)', lines[i + 1].strip()) + if url_match: + src = url_match.group(1) + if alt or src: + images.append({"src": src, "alt": alt}) + + return json.dumps({ + "success": True, + "images": images, + "count": len(images), + }) + except Exception as e: + return tool_error(str(e), success=False) + + +def camofox_vision(question: str, annotate: bool = False, + task_id: Optional[str] = None) -> str: + """Take a screenshot and analyze it with vision AI via Camofox.""" + try: + session = _get_session(task_id) + if not session["tab_id"]: + return tool_error("No browser session. Call browser_navigate first.", success=False) + + # Get screenshot as binary PNG + resp = _get_raw( + f"/tabs/{session['tab_id']}/screenshot", + params={"userId": session["user_id"]}, + ) + + # Save screenshot to cache + from hermes_constants import get_hermes_home + screenshots_dir = get_hermes_home() / "browser_screenshots" + screenshots_dir.mkdir(parents=True, exist_ok=True) + screenshot_path = str(screenshots_dir / f"browser_screenshot_{uuid.uuid4().hex[:8]}.png") + + with open(screenshot_path, "wb") as f: + f.write(resp.content) + + # Encode for vision LLM + img_b64 = base64.b64encode(resp.content).decode("utf-8") + + # Also get annotated snapshot if requested + annotation_context = "" + if annotate: + try: + snap_data = _get( + f"/tabs/{session['tab_id']}/snapshot", + params={"userId": session["user_id"]}, + ) + annotation_context = f"\n\nAccessibility tree (element refs for interaction):\n{snap_data.get('snapshot', '')[:3000]}" + except Exception: + pass + + # Redact secrets from annotation context before sending to vision LLM. + # The screenshot image itself cannot be redacted, but at least the + # text-based accessibility tree snippet won't leak secret values. + from agent.redact import redact_sensitive_text + annotation_context = redact_sensitive_text(annotation_context) + + # Send to vision LLM + from agent.auxiliary_client import call_llm + + vision_prompt = ( + f"Analyze this browser screenshot and answer: {question}" + f"{annotation_context}" + ) + + try: + from hermes_cli.config import load_config + _cfg = load_config() + _vision_timeout = int(_cfg.get("auxiliary", {}).get("vision", {}).get("timeout", 120)) + except Exception: + _vision_timeout = 120 + + response = call_llm( + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": vision_prompt}, + { + "type": "image_url", + "image_url": { + "url": f"data:image/png;base64,{img_b64}", + }, + }, + ], + }], + task="vision", + timeout=_vision_timeout, + ) + analysis = (response.choices[0].message.content or "").strip() if response.choices else "" + + # Redact secrets the vision LLM may have read from the screenshot. + from agent.redact import redact_sensitive_text + analysis = redact_sensitive_text(analysis) + + return json.dumps({ + "success": True, + "analysis": analysis, + "screenshot_path": screenshot_path, + }) + except Exception as e: + return tool_error(str(e), success=False) + + +def camofox_console(clear: bool = False, task_id: Optional[str] = None) -> str: + """Get console output — limited support in Camofox. + + Camofox does not expose browser console logs via its REST API. + Returns an empty result with a note. + """ + return json.dumps({ + "success": True, + "console_messages": [], + "js_errors": [], + "total_messages": 0, + "total_errors": 0, + "note": "Console log capture is not available with the Camofox backend. " + "Use browser_snapshot or browser_vision to inspect page state.", + }) + + + diff --git a/mindcli/_vendor/tools/browser_camofox_state.py b/mindcli/_vendor/tools/browser_camofox_state.py new file mode 100644 index 0000000..3a2bde0 --- /dev/null +++ b/mindcli/_vendor/tools/browser_camofox_state.py @@ -0,0 +1,47 @@ +"""Hermes-managed Camofox state helpers. + +Provides profile-scoped identity and state directory paths for Camofox +persistent browser profiles. When managed persistence is enabled, Hermes +sends a deterministic userId derived from the active profile so that +Camofox can map it to the same persistent browser profile directory +across restarts. +""" + +from __future__ import annotations + +import uuid +from pathlib import Path +from typing import Dict, Optional + +from hermes_constants import get_hermes_home + +CAMOFOX_STATE_DIR_NAME = "browser_auth" +CAMOFOX_STATE_SUBDIR = "camofox" + + +def get_camofox_state_dir() -> Path: + """Return the profile-scoped root directory for Camofox persistence.""" + return get_hermes_home() / CAMOFOX_STATE_DIR_NAME / CAMOFOX_STATE_SUBDIR + + +def get_camofox_identity(task_id: Optional[str] = None) -> Dict[str, str]: + """Return the stable Hermes-managed Camofox identity for this profile. + + The user identity is profile-scoped (same Hermes profile = same userId). + The session key is scoped to the logical browser task so newly created + tabs within the same profile reuse the same identity contract. + """ + scope_root = str(get_camofox_state_dir()) + logical_scope = task_id or "default" + user_digest = uuid.uuid5( + uuid.NAMESPACE_URL, + f"camofox-user:{scope_root}", + ).hex[:10] + session_digest = uuid.uuid5( + uuid.NAMESPACE_URL, + f"camofox-session:{scope_root}:{logical_scope}", + ).hex[:16] + return { + "user_id": f"hermes_{user_digest}", + "session_key": f"task_{session_digest}", + } diff --git a/mindcli/_vendor/tools/browser_providers/__init__.py b/mindcli/_vendor/tools/browser_providers/__init__.py new file mode 100644 index 0000000..7fa59ef --- /dev/null +++ b/mindcli/_vendor/tools/browser_providers/__init__.py @@ -0,0 +1,10 @@ +"""Cloud browser provider abstraction. + +Import the ABC so callers can do:: + + from tools.browser_providers import CloudBrowserProvider +""" + +from tools.browser_providers.base import CloudBrowserProvider + +__all__ = ["CloudBrowserProvider"] diff --git a/mindcli/_vendor/tools/browser_providers/base.py b/mindcli/_vendor/tools/browser_providers/base.py new file mode 100644 index 0000000..6b8e1ed --- /dev/null +++ b/mindcli/_vendor/tools/browser_providers/base.py @@ -0,0 +1,59 @@ +"""Abstract base class for cloud browser providers.""" + +from abc import ABC, abstractmethod +from typing import Dict + + +class CloudBrowserProvider(ABC): + """Interface for cloud browser backends (Browserbase, Steel, etc.). + + Implementations live in sibling modules and are registered in + ``browser_tool._PROVIDER_REGISTRY``. The user selects a provider via + ``hermes setup`` / ``hermes tools``; the choice is persisted as + ``config["browser"]["cloud_provider"]``. + """ + + @abstractmethod + def provider_name(self) -> str: + """Short, human-readable name shown in logs and diagnostics.""" + + @abstractmethod + def is_configured(self) -> bool: + """Return True when all required env vars / credentials are present. + + Called at tool-registration time (``check_browser_requirements``) to + gate availability. Must be cheap — no network calls. + """ + + @abstractmethod + def create_session(self, task_id: str) -> Dict[str, object]: + """Create a cloud browser session and return session metadata. + + Must return a dict with at least:: + + { + "session_name": str, # unique name for agent-browser --session + "bb_session_id": str, # provider session ID (for close/cleanup) + "cdp_url": str, # CDP websocket URL + "features": dict, # feature flags that were enabled + } + + ``bb_session_id`` is a legacy key name kept for backward compat with + the rest of browser_tool.py — it holds the provider's session ID + regardless of which provider is in use. + """ + + @abstractmethod + def close_session(self, session_id: str) -> bool: + """Release / terminate a cloud session by its provider session ID. + + Returns True on success, False on failure. Should not raise. + """ + + @abstractmethod + def emergency_cleanup(self, session_id: str) -> None: + """Best-effort session teardown during process exit. + + Called from atexit / signal handlers. Must tolerate missing + credentials, network errors, etc. — log and move on. + """ diff --git a/mindcli/_vendor/tools/browser_providers/browser_use.py b/mindcli/_vendor/tools/browser_providers/browser_use.py new file mode 100644 index 0000000..0f12dc4 --- /dev/null +++ b/mindcli/_vendor/tools/browser_providers/browser_use.py @@ -0,0 +1,215 @@ +"""Browser Use cloud browser provider.""" + +import logging +import os +import threading +import uuid +from typing import Any, Dict, Optional + +import requests + +from tools.browser_providers.base import CloudBrowserProvider +from tools.managed_tool_gateway import resolve_managed_tool_gateway +from tools.tool_backend_helpers import managed_nous_tools_enabled + +logger = logging.getLogger(__name__) +_pending_create_keys: Dict[str, str] = {} +_pending_create_keys_lock = threading.Lock() + +_BASE_URL = "https://api.browser-use.com/api/v3" +_DEFAULT_MANAGED_TIMEOUT_MINUTES = 5 +_DEFAULT_MANAGED_PROXY_COUNTRY_CODE = "us" + + +def _get_or_create_pending_create_key(task_id: str) -> str: + with _pending_create_keys_lock: + existing = _pending_create_keys.get(task_id) + if existing: + return existing + + created = f"browser-use-session-create:{uuid.uuid4().hex}" + _pending_create_keys[task_id] = created + return created + + +def _clear_pending_create_key(task_id: str) -> None: + with _pending_create_keys_lock: + _pending_create_keys.pop(task_id, None) + + +def _should_preserve_pending_create_key(response: requests.Response) -> bool: + if response.status_code >= 500: + return True + + if response.status_code != 409: + return False + + try: + payload = response.json() + except Exception: + return False + + if not isinstance(payload, dict): + return False + + error = payload.get("error") + if not isinstance(error, dict): + return False + + message = str(error.get("message") or "").lower() + return "already in progress" in message + + +class BrowserUseProvider(CloudBrowserProvider): + """Browser Use (https://browser-use.com) cloud browser backend.""" + + def provider_name(self) -> str: + return "Browser Use" + + def is_configured(self) -> bool: + return self._get_config_or_none() is not None + + # ------------------------------------------------------------------ + # Config resolution (direct API key OR managed Nous gateway) + # ------------------------------------------------------------------ + + def _get_config_or_none(self) -> Optional[Dict[str, Any]]: + api_key = os.environ.get("BROWSER_USE_API_KEY") + if api_key: + return { + "api_key": api_key, + "base_url": _BASE_URL, + "managed_mode": False, + } + + managed = resolve_managed_tool_gateway("browser-use") + if managed is None: + return None + + return { + "api_key": managed.nous_user_token, + "base_url": managed.gateway_origin.rstrip("/"), + "managed_mode": True, + } + + def _get_config(self) -> Dict[str, Any]: + config = self._get_config_or_none() + if config is None: + message = ( + "Browser Use requires a direct BROWSER_USE_API_KEY credential." + ) + if managed_nous_tools_enabled(): + message = ( + "Browser Use requires either a direct BROWSER_USE_API_KEY " + "credential or a managed Browser Use gateway configuration." + ) + raise ValueError(message) + return config + + # ------------------------------------------------------------------ + # Session lifecycle + # ------------------------------------------------------------------ + + def _headers(self, config: Dict[str, Any]) -> Dict[str, str]: + headers = { + "Content-Type": "application/json", + "X-Browser-Use-API-Key": config["api_key"], + } + return headers + + def create_session(self, task_id: str) -> Dict[str, object]: + config = self._get_config() + managed_mode = bool(config.get("managed_mode")) + + headers = self._headers(config) + if managed_mode: + headers["X-Idempotency-Key"] = _get_or_create_pending_create_key(task_id) + + # Keep gateway-backed sessions short so billing authorization does not + # default to a long Browser-Use timeout when Hermes only needs a task- + # scoped ephemeral browser. + payload = ( + { + "timeout": _DEFAULT_MANAGED_TIMEOUT_MINUTES, + "proxyCountryCode": _DEFAULT_MANAGED_PROXY_COUNTRY_CODE, + } + if managed_mode + else {} + ) + + response = requests.post( + f"{config['base_url']}/browsers", + headers=headers, + json=payload, + timeout=30, + ) + + if not response.ok: + if managed_mode and not _should_preserve_pending_create_key(response): + _clear_pending_create_key(task_id) + raise RuntimeError( + f"Failed to create Browser Use session: " + f"{response.status_code} {response.text}" + ) + + session_data = response.json() + if managed_mode: + _clear_pending_create_key(task_id) + session_name = f"hermes_{task_id}_{uuid.uuid4().hex[:8]}" + external_call_id = response.headers.get("x-external-call-id") if managed_mode else None + + logger.info("Created Browser Use session %s", session_name) + + cdp_url = session_data.get("cdpUrl") or session_data.get("connectUrl") or "" + + return { + "session_name": session_name, + "bb_session_id": session_data["id"], + "cdp_url": cdp_url, + "features": {"browser_use": True}, + "external_call_id": external_call_id, + } + + def close_session(self, session_id: str) -> bool: + try: + config = self._get_config() + except ValueError: + logger.warning("Cannot close Browser Use session %s — missing credentials", session_id) + return False + + try: + response = requests.patch( + f"{config['base_url']}/browsers/{session_id}", + headers=self._headers(config), + json={"action": "stop"}, + timeout=10, + ) + if response.status_code in (200, 201, 204): + logger.debug("Successfully closed Browser Use session %s", session_id) + return True + else: + logger.warning( + "Failed to close Browser Use session %s: HTTP %s - %s", + session_id, + response.status_code, + response.text[:200], + ) + return False + except Exception as e: + logger.error("Exception closing Browser Use session %s: %s", session_id, e) + return False + + def emergency_cleanup(self, session_id: str) -> None: + config = self._get_config_or_none() + if config is None: + logger.warning("Cannot emergency-cleanup Browser Use session %s — missing credentials", session_id) + return + try: + requests.patch( + f"{config['base_url']}/browsers/{session_id}", + headers=self._headers(config), + json={"action": "stop"}, + timeout=5, + ) + except Exception as e: + logger.debug("Emergency cleanup failed for Browser Use session %s: %s", session_id, e) diff --git a/mindcli/_vendor/tools/browser_providers/browserbase.py b/mindcli/_vendor/tools/browser_providers/browserbase.py new file mode 100644 index 0000000..338ebf8 --- /dev/null +++ b/mindcli/_vendor/tools/browser_providers/browserbase.py @@ -0,0 +1,217 @@ +"""Browserbase cloud browser provider (direct credentials only).""" + +import logging +import os +import uuid +from typing import Any, Dict, Optional + +import requests + +from tools.browser_providers.base import CloudBrowserProvider + +logger = logging.getLogger(__name__) + + +class BrowserbaseProvider(CloudBrowserProvider): + """Browserbase (https://browserbase.com) cloud browser backend. + + This provider requires direct BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID + credentials. Managed Nous gateway support has been removed — the Nous + subscription now routes through Browser Use instead. + """ + + def provider_name(self) -> str: + return "Browserbase" + + def is_configured(self) -> bool: + return self._get_config_or_none() is not None + + # ------------------------------------------------------------------ + # Session lifecycle + # ------------------------------------------------------------------ + + def _get_config_or_none(self) -> Optional[Dict[str, Any]]: + api_key = os.environ.get("BROWSERBASE_API_KEY") + project_id = os.environ.get("BROWSERBASE_PROJECT_ID") + if api_key and project_id: + return { + "api_key": api_key, + "project_id": project_id, + "base_url": os.environ.get("BROWSERBASE_BASE_URL", "https://api.browserbase.com").rstrip("/"), + } + return None + + def _get_config(self) -> Dict[str, Any]: + config = self._get_config_or_none() + if config is None: + raise ValueError( + "Browserbase requires BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID " + "environment variables." + ) + return config + + def create_session(self, task_id: str) -> Dict[str, object]: + config = self._get_config() + + # Optional env-var knobs + enable_proxies = os.environ.get("BROWSERBASE_PROXIES", "true").lower() != "false" + enable_advanced_stealth = os.environ.get("BROWSERBASE_ADVANCED_STEALTH", "false").lower() == "true" + enable_keep_alive = os.environ.get("BROWSERBASE_KEEP_ALIVE", "true").lower() != "false" + custom_timeout_ms = os.environ.get("BROWSERBASE_SESSION_TIMEOUT") + + features_enabled = { + "basic_stealth": True, + "proxies": False, + "advanced_stealth": False, + "keep_alive": False, + "custom_timeout": False, + } + + session_config: Dict[str, object] = {"projectId": config["project_id"]} + + if enable_keep_alive: + session_config["keepAlive"] = True + + if custom_timeout_ms: + try: + timeout_val = int(custom_timeout_ms) + if timeout_val > 0: + session_config["timeout"] = timeout_val + except ValueError: + logger.warning("Invalid BROWSERBASE_SESSION_TIMEOUT value: %s", custom_timeout_ms) + + if enable_proxies: + session_config["proxies"] = True + + if enable_advanced_stealth: + session_config["browserSettings"] = {"advancedStealth": True} + + # --- Create session via API --- + headers = { + "Content-Type": "application/json", + "X-BB-API-Key": config["api_key"], + } + + response = requests.post( + f"{config['base_url']}/v1/sessions", + headers=headers, + json=session_config, + timeout=30, + ) + + proxies_fallback = False + keepalive_fallback = False + + # Handle 402 — paid features unavailable + if response.status_code == 402: + if enable_keep_alive: + keepalive_fallback = True + logger.warning( + "keepAlive may require paid plan (402), retrying without it. " + "Sessions may timeout during long operations." + ) + session_config.pop("keepAlive", None) + response = requests.post( + f"{config['base_url']}/v1/sessions", + headers=headers, + json=session_config, + timeout=30, + ) + + if response.status_code == 402 and enable_proxies: + proxies_fallback = True + logger.warning( + "Proxies unavailable (402), retrying without proxies. " + "Bot detection may be less effective." + ) + session_config.pop("proxies", None) + response = requests.post( + f"{config['base_url']}/v1/sessions", + headers=headers, + json=session_config, + timeout=30, + ) + + if not response.ok: + raise RuntimeError( + f"Failed to create Browserbase session: " + f"{response.status_code} {response.text}" + ) + + session_data = response.json() + session_name = f"hermes_{task_id}_{uuid.uuid4().hex[:8]}" + + if enable_proxies and not proxies_fallback: + features_enabled["proxies"] = True + if enable_advanced_stealth: + features_enabled["advanced_stealth"] = True + if enable_keep_alive and not keepalive_fallback: + features_enabled["keep_alive"] = True + if custom_timeout_ms and "timeout" in session_config: + features_enabled["custom_timeout"] = True + + feature_str = ", ".join(k for k, v in features_enabled.items() if v) + logger.info("Created Browserbase session %s with features: %s", session_name, feature_str) + + return { + "session_name": session_name, + "bb_session_id": session_data["id"], + "cdp_url": session_data["connectUrl"], + "features": features_enabled, + } + + def close_session(self, session_id: str) -> bool: + try: + config = self._get_config() + except ValueError: + logger.warning("Cannot close Browserbase session %s — missing credentials", session_id) + return False + + try: + response = requests.post( + f"{config['base_url']}/v1/sessions/{session_id}", + headers={ + "X-BB-API-Key": config["api_key"], + "Content-Type": "application/json", + }, + json={ + "projectId": config["project_id"], + "status": "REQUEST_RELEASE", + }, + timeout=10, + ) + if response.status_code in (200, 201, 204): + logger.debug("Successfully closed Browserbase session %s", session_id) + return True + else: + logger.warning( + "Failed to close session %s: HTTP %s - %s", + session_id, + response.status_code, + response.text[:200], + ) + return False + except Exception as e: + logger.error("Exception closing Browserbase session %s: %s", session_id, e) + return False + + def emergency_cleanup(self, session_id: str) -> None: + config = self._get_config_or_none() + if config is None: + logger.warning("Cannot emergency-cleanup Browserbase session %s — missing credentials", session_id) + return + try: + requests.post( + f"{config['base_url']}/v1/sessions/{session_id}", + headers={ + "X-BB-API-Key": config["api_key"], + "Content-Type": "application/json", + }, + json={ + "projectId": config["project_id"], + "status": "REQUEST_RELEASE", + }, + timeout=5, + ) + except Exception as e: + logger.debug("Emergency cleanup failed for Browserbase session %s: %s", session_id, e) diff --git a/mindcli/_vendor/tools/browser_providers/firecrawl.py b/mindcli/_vendor/tools/browser_providers/firecrawl.py new file mode 100644 index 0000000..3f8556f --- /dev/null +++ b/mindcli/_vendor/tools/browser_providers/firecrawl.py @@ -0,0 +1,107 @@ +"""Firecrawl cloud browser provider.""" + +import logging +import os +import uuid +from typing import Dict + +import requests + +from tools.browser_providers.base import CloudBrowserProvider + +logger = logging.getLogger(__name__) + +_BASE_URL = "https://api.firecrawl.dev" + + +class FirecrawlProvider(CloudBrowserProvider): + """Firecrawl (https://firecrawl.dev) cloud browser backend.""" + + def provider_name(self) -> str: + return "Firecrawl" + + def is_configured(self) -> bool: + return bool(os.environ.get("FIRECRAWL_API_KEY")) + + # ------------------------------------------------------------------ + # Session lifecycle + # ------------------------------------------------------------------ + + def _api_url(self) -> str: + return os.environ.get("FIRECRAWL_API_URL", _BASE_URL) + + def _headers(self) -> Dict[str, str]: + api_key = os.environ.get("FIRECRAWL_API_KEY") + if not api_key: + raise ValueError( + "FIRECRAWL_API_KEY environment variable is required. " + "Get your key at https://firecrawl.dev" + ) + return { + "Content-Type": "application/json", + "Authorization": f"Bearer {api_key}", + } + + def create_session(self, task_id: str) -> Dict[str, object]: + ttl = int(os.environ.get("FIRECRAWL_BROWSER_TTL", "300")) + + body: Dict[str, object] = {"ttl": ttl} + + response = requests.post( + f"{self._api_url()}/v2/browser", + headers=self._headers(), + json=body, + timeout=30, + ) + + if not response.ok: + raise RuntimeError( + f"Failed to create Firecrawl browser session: " + f"{response.status_code} {response.text}" + ) + + data = response.json() + session_name = f"hermes_{task_id}_{uuid.uuid4().hex[:8]}" + + logger.info("Created Firecrawl browser session %s", session_name) + + return { + "session_name": session_name, + "bb_session_id": data["id"], + "cdp_url": data["cdpUrl"], + "features": {"firecrawl": True}, + } + + def close_session(self, session_id: str) -> bool: + try: + response = requests.delete( + f"{self._api_url()}/v2/browser/{session_id}", + headers=self._headers(), + timeout=10, + ) + if response.status_code in (200, 201, 204): + logger.debug("Successfully closed Firecrawl session %s", session_id) + return True + else: + logger.warning( + "Failed to close Firecrawl session %s: HTTP %s - %s", + session_id, + response.status_code, + response.text[:200], + ) + return False + except Exception as e: + logger.error("Exception closing Firecrawl session %s: %s", session_id, e) + return False + + def emergency_cleanup(self, session_id: str) -> None: + try: + requests.delete( + f"{self._api_url()}/v2/browser/{session_id}", + headers=self._headers(), + timeout=5, + ) + except ValueError: + logger.warning("Cannot emergency-cleanup Firecrawl session %s — missing credentials", session_id) + except Exception as e: + logger.debug("Emergency cleanup failed for Firecrawl session %s: %s", session_id, e) diff --git a/mindcli/_vendor/tools/browser_tool.py b/mindcli/_vendor/tools/browser_tool.py new file mode 100644 index 0000000..bb24866 --- /dev/null +++ b/mindcli/_vendor/tools/browser_tool.py @@ -0,0 +1,2387 @@ +#!/usr/bin/env python3 +""" +Browser Tool Module + +This module provides browser automation tools using agent-browser CLI. It +supports multiple backends — **Browser Use** (cloud, default for Nous +subscribers), **Browserbase** (cloud, direct credentials), and **local +Chromium** — with identical agent-facing behaviour. The backend is +auto-detected from config and available credentials. + +The tool uses agent-browser's accessibility tree (ariaSnapshot) for text-based +page representation, making it ideal for LLM agents without vision capabilities. + +Features: +- **Local mode** (default): zero-cost headless Chromium via agent-browser. + Works on Linux servers without a display. One-time setup: + ``agent-browser install`` (downloads Chromium) or + ``agent-browser install --with-deps`` (also installs system libraries for + Debian/Ubuntu/Docker). +- **Cloud mode**: Browserbase or Browser Use cloud execution when configured. +- Session isolation per task ID +- Text-based page snapshots using accessibility tree +- Element interaction via ref selectors (@e1, @e2, etc.) +- Task-aware content extraction using LLM summarization +- Automatic cleanup of browser sessions + +Environment Variables: +- BROWSERBASE_API_KEY: API key for direct Browserbase cloud mode +- BROWSERBASE_PROJECT_ID: Project ID for direct Browserbase cloud mode +- BROWSER_USE_API_KEY: API key for direct Browser Use cloud mode +- BROWSERBASE_PROXIES: Enable/disable residential proxies (default: "true") +- BROWSERBASE_ADVANCED_STEALTH: Enable advanced stealth mode with custom Chromium, + requires Scale Plan (default: "false") +- BROWSERBASE_KEEP_ALIVE: Enable keepAlive for session reconnection after disconnects, + requires paid plan (default: "true") +- BROWSERBASE_SESSION_TIMEOUT: Custom session timeout in milliseconds. Set to extend + beyond project default. Common values: 600000 (10min), 1800000 (30min) (default: none) + +Usage: + from tools.browser_tool import browser_navigate, browser_snapshot, browser_click + + # Navigate to a page + result = browser_navigate("https://example.com", task_id="task_123") + + # Get page snapshot + snapshot = browser_snapshot(task_id="task_123") + + # Click an element + browser_click("@e5", task_id="task_123") +""" + +import atexit +import functools +import json +import logging +import os +import re +import signal +import subprocess +import shutil +import sys +import tempfile +import threading +import time +import requests +from typing import Dict, Any, Optional, List +from pathlib import Path +from agent.auxiliary_client import call_llm +from hermes_constants import get_hermes_home + +try: + from tools.website_policy import check_website_access +except Exception: + check_website_access = lambda url: None # noqa: E731 — fail-open if policy module unavailable + +try: + from tools.url_safety import is_safe_url as _is_safe_url +except Exception: + _is_safe_url = lambda url: False # noqa: E731 — fail-closed: block all if safety module unavailable +from tools.browser_providers.base import CloudBrowserProvider +from tools.browser_providers.browserbase import BrowserbaseProvider +from tools.browser_providers.browser_use import BrowserUseProvider +from tools.browser_providers.firecrawl import FirecrawlProvider +from tools.tool_backend_helpers import normalize_browser_cloud_provider + +# Camofox local anti-detection browser backend (optional). +# When CAMOFOX_URL is set, all browser operations route through the +# camofox REST API instead of the agent-browser CLI. +try: + from tools.browser_camofox import is_camofox_mode as _is_camofox_mode +except ImportError: + _is_camofox_mode = lambda: False # noqa: E731 + +logger = logging.getLogger(__name__) + +# Standard PATH entries for environments with minimal PATH (e.g. systemd services). +# Includes macOS Homebrew paths (/opt/homebrew/* for Apple Silicon). +_SANE_PATH = ( + "/opt/homebrew/bin:/opt/homebrew/sbin:" + "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" +) + + +@functools.lru_cache(maxsize=1) +def _discover_homebrew_node_dirs() -> tuple[str, ...]: + """Find Homebrew versioned Node.js bin directories (e.g. node@20, node@24). + + When Node is installed via ``brew install node@24`` and NOT linked into + /opt/homebrew/bin, agent-browser isn't discoverable on the default PATH. + This function finds those directories so they can be prepended. + """ + dirs: list[str] = [] + homebrew_opt = "/opt/homebrew/opt" + if not os.path.isdir(homebrew_opt): + return tuple(dirs) + try: + for entry in os.listdir(homebrew_opt): + if entry.startswith("node") and entry != "node": + bin_dir = os.path.join(homebrew_opt, entry, "bin") + if os.path.isdir(bin_dir): + dirs.append(bin_dir) + except OSError: + pass + return tuple(dirs) + +# Throttle screenshot cleanup to avoid repeated full directory scans. +_last_screenshot_cleanup_by_dir: dict[str, float] = {} + +# ============================================================================ +# Configuration +# ============================================================================ + +# Default timeout for browser commands (seconds) +DEFAULT_COMMAND_TIMEOUT = 30 + +# Max tokens for snapshot content before summarization +SNAPSHOT_SUMMARIZE_THRESHOLD = 8000 + +# Commands that legitimately return empty stdout (e.g. close, record). +_EMPTY_OK_COMMANDS: frozenset = frozenset({"close", "record"}) + +_cached_command_timeout: Optional[int] = None +_command_timeout_resolved = False + + +def _get_command_timeout() -> int: + """Return the configured browser command timeout from config.yaml. + + Reads ``config["browser"]["command_timeout"]`` and falls back to + ``DEFAULT_COMMAND_TIMEOUT`` (30s) if unset or unreadable. Result is + cached after the first call and cleared by ``cleanup_all_browsers()``. + """ + global _cached_command_timeout, _command_timeout_resolved + if _command_timeout_resolved: + return _cached_command_timeout # type: ignore[return-value] + + _command_timeout_resolved = True + result = DEFAULT_COMMAND_TIMEOUT + try: + from hermes_cli.config import read_raw_config + cfg = read_raw_config() + val = cfg.get("browser", {}).get("command_timeout") + if val is not None: + result = max(int(val), 5) # Floor at 5s to avoid instant kills + except Exception as e: + logger.debug("Could not read command_timeout from config: %s", e) + _cached_command_timeout = result + return result + + +def _get_vision_model() -> Optional[str]: + """Model for browser_vision (screenshot analysis — multimodal).""" + return os.getenv("AUXILIARY_VISION_MODEL", "").strip() or None + + +def _get_extraction_model() -> Optional[str]: + """Model for page snapshot text summarization — same as web_extract.""" + return os.getenv("AUXILIARY_WEB_EXTRACT_MODEL", "").strip() or None + + +def _resolve_cdp_override(cdp_url: str) -> str: + """Normalize a user-supplied CDP endpoint into a concrete connectable URL. + + Accepts: + - full websocket endpoints: ws://host:port/devtools/browser/... + - HTTP discovery endpoints: http://host:port or http://host:port/json/version + - bare websocket host:port values like ws://host:port + + For discovery-style endpoints we fetch /json/version and return the + webSocketDebuggerUrl so downstream tools always receive a concrete browser + websocket instead of an ambiguous host:port URL. + """ + raw = (cdp_url or "").strip() + if not raw: + return "" + + lowered = raw.lower() + if "/devtools/browser/" in lowered: + return raw + + discovery_url = raw + if lowered.startswith(("ws://", "wss://")): + if raw.count(":") == 2 and raw.rstrip("/").rsplit(":", 1)[-1].isdigit() and "/" not in raw.split(":", 2)[-1]: + discovery_url = ("http://" if lowered.startswith("ws://") else "https://") + raw.split("://", 1)[1] + else: + return raw + + if discovery_url.lower().endswith("/json/version"): + version_url = discovery_url + else: + version_url = discovery_url.rstrip("/") + "/json/version" + + try: + response = requests.get(version_url, timeout=10) + response.raise_for_status() + payload = response.json() + except Exception as exc: + logger.warning("Failed to resolve CDP endpoint %s via %s: %s", raw, version_url, exc) + return raw + + ws_url = str(payload.get("webSocketDebuggerUrl") or "").strip() + if ws_url: + logger.info("Resolved CDP endpoint %s -> %s", raw, ws_url) + return ws_url + + logger.warning("CDP discovery at %s did not return webSocketDebuggerUrl; using raw endpoint", version_url) + return raw + + +def _get_cdp_override() -> str: + """Return a normalized user-supplied CDP URL override, or empty string. + + When ``BROWSER_CDP_URL`` is set (e.g. via ``/browser connect``), we skip + both Browserbase and the local headless launcher and connect directly to + the supplied Chrome DevTools Protocol endpoint. + """ + return _resolve_cdp_override(os.environ.get("BROWSER_CDP_URL", "")) + + +# ============================================================================ +# Cloud Provider Registry +# ============================================================================ + +_PROVIDER_REGISTRY: Dict[str, type] = { + "browserbase": BrowserbaseProvider, + "browser-use": BrowserUseProvider, + "firecrawl": FirecrawlProvider, +} + +_cached_cloud_provider: Optional[CloudBrowserProvider] = None +_cloud_provider_resolved = False +_allow_private_urls_resolved = False +_cached_allow_private_urls: Optional[bool] = None +_cached_agent_browser: Optional[str] = None +_agent_browser_resolved = False + + +def _get_cloud_provider() -> Optional[CloudBrowserProvider]: + """Return the configured cloud browser provider, or None for local mode. + + Reads ``config["browser"]["cloud_provider"]`` once and caches the result + for the process lifetime. An explicit ``local`` provider disables cloud + fallback. If unset, fall back to Browserbase when direct or managed + Browserbase credentials are available. + """ + global _cached_cloud_provider, _cloud_provider_resolved + if _cloud_provider_resolved: + return _cached_cloud_provider + + _cloud_provider_resolved = True + try: + from hermes_cli.config import read_raw_config + cfg = read_raw_config() + browser_cfg = cfg.get("browser", {}) + provider_key = None + if isinstance(browser_cfg, dict) and "cloud_provider" in browser_cfg: + provider_key = normalize_browser_cloud_provider( + browser_cfg.get("cloud_provider") + ) + if provider_key == "local": + _cached_cloud_provider = None + return None + if provider_key and provider_key in _PROVIDER_REGISTRY: + _cached_cloud_provider = _PROVIDER_REGISTRY[provider_key]() + except Exception as e: + logger.debug("Could not read cloud_provider from config: %s", e) + + if _cached_cloud_provider is None: + # Prefer Browser Use (managed Nous gateway or direct API key), + # fall back to Browserbase (direct credentials only). + fallback_provider = BrowserUseProvider() + if fallback_provider.is_configured(): + _cached_cloud_provider = fallback_provider + else: + fallback_provider = BrowserbaseProvider() + if fallback_provider.is_configured(): + _cached_cloud_provider = fallback_provider + + return _cached_cloud_provider + + +from hermes_constants import is_termux as _is_termux_environment + + +def _browser_install_hint() -> str: + if _is_termux_environment(): + return "npm install -g agent-browser && agent-browser install" + return "npm install -g agent-browser && agent-browser install --with-deps" + + +def _requires_real_termux_browser_install(browser_cmd: str) -> bool: + return _is_termux_environment() and _is_local_mode() and browser_cmd.strip() == "npx agent-browser" + + +def _termux_browser_install_error() -> str: + return ( + "Local browser automation on Termux cannot rely on the bare npx fallback. " + f"Install agent-browser explicitly first: {_browser_install_hint()}" + ) + + +def _is_local_mode() -> bool: + """Return True when the browser tool will use a local browser backend.""" + if _get_cdp_override(): + return False + return _get_cloud_provider() is None + + +def _is_local_backend() -> bool: + """Return True when the browser runs locally (no cloud provider). + + SSRF protection is only meaningful for cloud backends (Browserbase, + BrowserUse) where the agent could reach internal resources on a remote + machine. For local backends — Camofox, or the built-in headless + Chromium without a cloud provider — the user already has full terminal + and network access on the same machine, so the check adds no security + value. + """ + return _is_camofox_mode() or _get_cloud_provider() is None + + +def _allow_private_urls() -> bool: + """Return whether the browser is allowed to navigate to private/internal addresses. + + Reads ``config["browser"]["allow_private_urls"]`` once and caches the result + for the process lifetime. Defaults to ``False`` (SSRF protection active). + """ + global _cached_allow_private_urls, _allow_private_urls_resolved + if _allow_private_urls_resolved: + return _cached_allow_private_urls + + _allow_private_urls_resolved = True + _cached_allow_private_urls = False # safe default + try: + from hermes_cli.config import read_raw_config + cfg = read_raw_config() + _cached_allow_private_urls = bool(cfg.get("browser", {}).get("allow_private_urls")) + except Exception as e: + logger.debug("Could not read allow_private_urls from config: %s", e) + return _cached_allow_private_urls + + +def _socket_safe_tmpdir() -> str: + """Return a short temp directory path suitable for Unix domain sockets. + + macOS sets ``TMPDIR`` to ``/var/folders/xx/.../T/`` (~51 chars). When we + append ``agent-browser-hermes_…`` the resulting socket path exceeds the + 104-byte macOS limit for ``AF_UNIX`` addresses, causing agent-browser to + fail with "Failed to create socket directory" or silent screenshot failures. + + Linux ``tempfile.gettempdir()`` already returns ``/tmp``, so this is a + no-op there. On macOS we bypass ``TMPDIR`` and use ``/tmp`` directly + (symlink to ``/private/tmp``, sticky-bit protected, always available). + """ + if sys.platform == "darwin": + return "/tmp" + return tempfile.gettempdir() + + +# Track active sessions per task +# Stores: session_name (always), bb_session_id + cdp_url (cloud mode only) +_active_sessions: Dict[str, Dict[str, str]] = {} # task_id -> {session_name, ...} +_recording_sessions: set = set() # task_ids with active recordings + +# Flag to track if cleanup has been done +_cleanup_done = False + +# ============================================================================= +# Inactivity Timeout Configuration +# ============================================================================= + +# Session inactivity timeout (seconds) - cleanup if no activity for this long +# Default: 5 minutes. Needs headroom for LLM reasoning between browser commands, +# especially when subagents are doing multi-step browser tasks. +BROWSER_SESSION_INACTIVITY_TIMEOUT = int(os.environ.get("BROWSER_INACTIVITY_TIMEOUT", "300")) + +# Track last activity time per session +_session_last_activity: Dict[str, float] = {} + +# Background cleanup thread state +_cleanup_thread = None +_cleanup_running = False +# Protects _session_last_activity AND _active_sessions for thread safety +# (subagents run concurrently via ThreadPoolExecutor) +_cleanup_lock = threading.Lock() + + +def _emergency_cleanup_all_sessions(): + """ + Emergency cleanup of all active browser sessions. + Called on process exit or interrupt to prevent orphaned sessions. + """ + global _cleanup_done + if _cleanup_done: + return + _cleanup_done = True + + if not _active_sessions: + return + + logger.info("Emergency cleanup: closing %s active session(s)...", + len(_active_sessions)) + + try: + cleanup_all_browsers() + except Exception as e: + logger.error("Emergency cleanup error: %s", e) + finally: + with _cleanup_lock: + _active_sessions.clear() + _session_last_activity.clear() + _recording_sessions.clear() + + +# Register cleanup via atexit only. Previous versions installed SIGINT/SIGTERM +# handlers that called sys.exit(), but this conflicts with prompt_toolkit's +# async event loop — a SystemExit raised inside a key-binding callback +# corrupts the coroutine state and makes the process unkillable. atexit +# handlers run on any normal exit (including sys.exit), so browser sessions +# are still cleaned up without hijacking signals. +atexit.register(_emergency_cleanup_all_sessions) + + +# ============================================================================= +# Inactivity Cleanup Functions +# ============================================================================= + +def _cleanup_inactive_browser_sessions(): + """ + Clean up browser sessions that have been inactive for longer than the timeout. + + This function is called periodically by the background cleanup thread to + automatically close sessions that haven't been used recently, preventing + orphaned sessions (local or Browserbase) from accumulating. + """ + current_time = time.time() + sessions_to_cleanup = [] + + with _cleanup_lock: + for task_id, last_time in list(_session_last_activity.items()): + if current_time - last_time > BROWSER_SESSION_INACTIVITY_TIMEOUT: + sessions_to_cleanup.append(task_id) + + for task_id in sessions_to_cleanup: + try: + elapsed = int(current_time - _session_last_activity.get(task_id, current_time)) + logger.info("Cleaning up inactive session for task: %s (inactive for %ss)", task_id, elapsed) + cleanup_browser(task_id) + with _cleanup_lock: + if task_id in _session_last_activity: + del _session_last_activity[task_id] + except Exception as e: + logger.warning("Error cleaning up inactive session %s: %s", task_id, e) + + +def _reap_orphaned_browser_sessions(): + """Scan for orphaned agent-browser daemon processes from previous runs. + + When the Python process that created a browser session exits uncleanly + (SIGKILL, crash, gateway restart), the in-memory ``_active_sessions`` + tracking is lost but the node + Chromium processes keep running. + + This function scans the tmp directory for ``agent-browser-*`` socket dirs + left behind by previous runs, reads the daemon PID files, and kills any + daemons that are still alive but not tracked by the current process. + + Called once on cleanup-thread startup — not every 30 seconds — to avoid + races with sessions being actively created. + """ + import glob + + tmpdir = _socket_safe_tmpdir() + pattern = os.path.join(tmpdir, "agent-browser-h_*") + socket_dirs = glob.glob(pattern) + # Also pick up CDP sessions + socket_dirs += glob.glob(os.path.join(tmpdir, "agent-browser-cdp_*")) + + if not socket_dirs: + return + + # Build set of session_names currently tracked by this process + with _cleanup_lock: + tracked_names = { + info.get("session_name") + for info in _active_sessions.values() + if info.get("session_name") + } + + reaped = 0 + for socket_dir in socket_dirs: + dir_name = os.path.basename(socket_dir) + # dir_name is "agent-browser-{session_name}" + session_name = dir_name.removeprefix("agent-browser-") + if not session_name: + continue + + # Skip sessions that we are actively tracking + if session_name in tracked_names: + continue + + pid_file = os.path.join(socket_dir, f"{session_name}.pid") + if not os.path.isfile(pid_file): + # No PID file — just a stale dir, remove it + shutil.rmtree(socket_dir, ignore_errors=True) + continue + + try: + daemon_pid = int(Path(pid_file).read_text().strip()) + except (ValueError, OSError): + shutil.rmtree(socket_dir, ignore_errors=True) + continue + + # Check if the daemon is still alive + try: + os.kill(daemon_pid, 0) # signal 0 = existence check + except ProcessLookupError: + # Already dead, just clean up the dir + shutil.rmtree(socket_dir, ignore_errors=True) + continue + except PermissionError: + # Alive but owned by someone else — leave it alone + continue + + # Daemon is alive and not tracked — orphan. Kill it. + try: + os.kill(daemon_pid, signal.SIGTERM) + logger.info("Reaped orphaned browser daemon PID %d (session %s)", + daemon_pid, session_name) + reaped += 1 + except (ProcessLookupError, PermissionError, OSError): + pass + + # Clean up the socket directory + shutil.rmtree(socket_dir, ignore_errors=True) + + if reaped: + logger.info("Reaped %d orphaned browser session(s) from previous run(s)", reaped) + + +def _browser_cleanup_thread_worker(): + """ + Background thread that periodically cleans up inactive browser sessions. + + Runs every 30 seconds and checks for sessions that haven't been used + within the BROWSER_SESSION_INACTIVITY_TIMEOUT period. + On first run, also reaps orphaned sessions from previous process lifetimes. + """ + # One-time orphan reap on startup + try: + _reap_orphaned_browser_sessions() + except Exception as e: + logger.warning("Orphan reap error: %s", e) + + while _cleanup_running: + try: + _cleanup_inactive_browser_sessions() + except Exception as e: + logger.warning("Cleanup thread error: %s", e) + + # Sleep in 1-second intervals so we can stop quickly if needed + for _ in range(30): + if not _cleanup_running: + break + time.sleep(1) + + +def _start_browser_cleanup_thread(): + """Start the background cleanup thread if not already running.""" + global _cleanup_thread, _cleanup_running + + with _cleanup_lock: + if _cleanup_thread is None or not _cleanup_thread.is_alive(): + _cleanup_running = True + _cleanup_thread = threading.Thread( + target=_browser_cleanup_thread_worker, + daemon=True, + name="browser-cleanup" + ) + _cleanup_thread.start() + logger.info("Started inactivity cleanup thread (timeout: %ss)", BROWSER_SESSION_INACTIVITY_TIMEOUT) + + +def _stop_browser_cleanup_thread(): + """Stop the background cleanup thread.""" + global _cleanup_running + _cleanup_running = False + if _cleanup_thread is not None: + _cleanup_thread.join(timeout=5) + + +def _update_session_activity(task_id: str): + """Update the last activity timestamp for a session.""" + with _cleanup_lock: + _session_last_activity[task_id] = time.time() + + +# Register cleanup thread stop on exit +atexit.register(_stop_browser_cleanup_thread) + + +# ============================================================================ +# Tool Schemas +# ============================================================================ + +BROWSER_TOOL_SCHEMAS = [ + { + "name": "browser_navigate", + "description": "Navigate to a URL in the browser. Initializes the session and loads the page. Must be called before other browser tools. For simple information retrieval, prefer web_search or web_extract (faster, cheaper). Use browser tools when you need to interact with a page (click, fill forms, dynamic content). Returns a compact page snapshot with interactive elements and ref IDs — no need to call browser_snapshot separately after navigating.", + "parameters": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "The URL to navigate to (e.g., 'https://example.com')" + } + }, + "required": ["url"] + } + }, + { + "name": "browser_snapshot", + "description": "Get a text-based snapshot of the current page's accessibility tree. Returns interactive elements with ref IDs (like @e1, @e2) for browser_click and browser_type. full=false (default): compact view with interactive elements. full=true: complete page content. Snapshots over 8000 chars are truncated or LLM-summarized. Requires browser_navigate first. Note: browser_navigate already returns a compact snapshot — use this to refresh after interactions that change the page, or with full=true for complete content.", + "parameters": { + "type": "object", + "properties": { + "full": { + "type": "boolean", + "description": "If true, returns complete page content. If false (default), returns compact view with interactive elements only.", + "default": False + } + }, + "required": [] + } + }, + { + "name": "browser_click", + "description": "Click on an element identified by its ref ID from the snapshot (e.g., '@e5'). The ref IDs are shown in square brackets in the snapshot output. Requires browser_navigate and browser_snapshot to be called first.", + "parameters": { + "type": "object", + "properties": { + "ref": { + "type": "string", + "description": "The element reference from the snapshot (e.g., '@e5', '@e12')" + } + }, + "required": ["ref"] + } + }, + { + "name": "browser_type", + "description": "Type text into an input field identified by its ref ID. Clears the field first, then types the new text. Requires browser_navigate and browser_snapshot to be called first.", + "parameters": { + "type": "object", + "properties": { + "ref": { + "type": "string", + "description": "The element reference from the snapshot (e.g., '@e3')" + }, + "text": { + "type": "string", + "description": "The text to type into the field" + } + }, + "required": ["ref", "text"] + } + }, + { + "name": "browser_scroll", + "description": "Scroll the page in a direction. Use this to reveal more content that may be below or above the current viewport. Requires browser_navigate to be called first.", + "parameters": { + "type": "object", + "properties": { + "direction": { + "type": "string", + "enum": ["up", "down"], + "description": "Direction to scroll" + } + }, + "required": ["direction"] + } + }, + { + "name": "browser_back", + "description": "Navigate back to the previous page in browser history. Requires browser_navigate to be called first.", + "parameters": { + "type": "object", + "properties": {}, + "required": [] + } + }, + { + "name": "browser_press", + "description": "Press a keyboard key. Useful for submitting forms (Enter), navigating (Tab), or keyboard shortcuts. Requires browser_navigate to be called first.", + "parameters": { + "type": "object", + "properties": { + "key": { + "type": "string", + "description": "Key to press (e.g., 'Enter', 'Tab', 'Escape', 'ArrowDown')" + } + }, + "required": ["key"] + } + }, + { + "name": "browser_get_images", + "description": "Get a list of all images on the current page with their URLs and alt text. Useful for finding images to analyze with the vision tool. Requires browser_navigate to be called first.", + "parameters": { + "type": "object", + "properties": {}, + "required": [] + } + }, + { + "name": "browser_vision", + "description": "Take a screenshot of the current page and analyze it with vision AI. Use this when you need to visually understand what's on the page - especially useful for CAPTCHAs, visual verification challenges, complex layouts, or when the text snapshot doesn't capture important visual information. Returns both the AI analysis and a screenshot_path that you can share with the user by including MEDIA: in your response. Requires browser_navigate to be called first.", + "parameters": { + "type": "object", + "properties": { + "question": { + "type": "string", + "description": "What you want to know about the page visually. Be specific about what you're looking for." + }, + "annotate": { + "type": "boolean", + "default": False, + "description": "If true, overlay numbered [N] labels on interactive elements. Each [N] maps to ref @eN for subsequent browser commands. Useful for QA and spatial reasoning about page layout." + } + }, + "required": ["question"] + } + }, + { + "name": "browser_console", + "description": "Get browser console output and JavaScript errors from the current page. Returns console.log/warn/error/info messages and uncaught JS exceptions. Use this to detect silent JavaScript errors, failed API calls, and application warnings. Requires browser_navigate to be called first. When 'expression' is provided, evaluates JavaScript in the page context and returns the result — use this for DOM inspection, reading page state, or extracting data programmatically.", + "parameters": { + "type": "object", + "properties": { + "clear": { + "type": "boolean", + "default": False, + "description": "If true, clear the message buffers after reading" + }, + "expression": { + "type": "string", + "description": "JavaScript expression to evaluate in the page context. Runs in the browser like DevTools console — full access to DOM, window, document. Return values are serialized to JSON. Example: 'document.title' or 'document.querySelectorAll(\"a\").length'" + } + }, + "required": [] + } + }, +] + + +# ============================================================================ +# Utility Functions +# ============================================================================ + +def _create_local_session(task_id: str) -> Dict[str, str]: + import uuid + session_name = f"h_{uuid.uuid4().hex[:10]}" + logger.info("Created local browser session %s for task %s", + session_name, task_id) + return { + "session_name": session_name, + "bb_session_id": None, + "cdp_url": None, + "features": {"local": True}, + } + + +def _create_cdp_session(task_id: str, cdp_url: str) -> Dict[str, str]: + """Create a session that connects to a user-supplied CDP endpoint.""" + import uuid + session_name = f"cdp_{uuid.uuid4().hex[:10]}" + logger.info("Created CDP browser session %s → %s for task %s", + session_name, cdp_url, task_id) + return { + "session_name": session_name, + "bb_session_id": None, + "cdp_url": cdp_url, + "features": {"cdp_override": True}, + } + + +def _get_session_info(task_id: Optional[str] = None) -> Dict[str, str]: + """ + Get or create session info for the given task. + + In cloud mode, creates a Browserbase session with proxies enabled. + In local mode, generates a session name for agent-browser --session. + Also starts the inactivity cleanup thread and updates activity tracking. + Thread-safe: multiple subagents can call this concurrently. + + Args: + task_id: Unique identifier for the task + + Returns: + Dict with session_name (always), bb_session_id + cdp_url (cloud only) + """ + if task_id is None: + task_id = "default" + + # Start the cleanup thread if not running (handles inactivity timeouts) + _start_browser_cleanup_thread() + + # Update activity timestamp for this session + _update_session_activity(task_id) + + with _cleanup_lock: + # Check if we already have a session for this task + if task_id in _active_sessions: + return _active_sessions[task_id] + + # Create session outside the lock (network call in cloud mode) + cdp_override = _get_cdp_override() + if cdp_override: + session_info = _create_cdp_session(task_id, cdp_override) + else: + provider = _get_cloud_provider() + if provider is None: + session_info = _create_local_session(task_id) + else: + session_info = provider.create_session(task_id) + if session_info.get("cdp_url"): + # Some cloud providers (including Browser-Use v3) return an HTTP + # CDP discovery URL instead of a raw websocket endpoint. + session_info = dict(session_info) + session_info["cdp_url"] = _resolve_cdp_override(str(session_info["cdp_url"])) + + with _cleanup_lock: + # Double-check: another thread may have created a session while we + # were doing the network call. Use the existing one to avoid leaking + # orphan cloud sessions. + if task_id in _active_sessions: + return _active_sessions[task_id] + _active_sessions[task_id] = session_info + + return session_info + + + +def _find_agent_browser() -> str: + """ + Find the agent-browser CLI executable. + + Checks in order: current PATH, Homebrew/common bin dirs, Hermes-managed + node, local node_modules/.bin/, npx fallback. + + Returns: + Path to agent-browser executable + + Raises: + FileNotFoundError: If agent-browser is not installed + """ + global _cached_agent_browser, _agent_browser_resolved + if _agent_browser_resolved: + if _cached_agent_browser is None: + raise FileNotFoundError( + "agent-browser CLI not found (cached). Install it with: " + f"{_browser_install_hint()}\n" + "Or run 'npm install' in the repo root to install locally.\n" + "Or ensure npx is available in your PATH." + ) + return _cached_agent_browser + + # Note: _agent_browser_resolved is set at each return site below + # (not before the search) to prevent a race where a concurrent thread + # sees resolved=True but _cached_agent_browser is still None. + + # Check if it's in PATH (global install) + which_result = shutil.which("agent-browser") + if which_result: + _cached_agent_browser = which_result + _agent_browser_resolved = True + return which_result + + # Build an extended search PATH including Homebrew and Hermes-managed dirs. + # This covers macOS where the process PATH may not include Homebrew paths. + extra_dirs: list[str] = [] + for d in ["/opt/homebrew/bin", "/usr/local/bin"]: + if os.path.isdir(d): + extra_dirs.append(d) + extra_dirs.extend(_discover_homebrew_node_dirs()) + + hermes_home = get_hermes_home() + hermes_node_bin = str(hermes_home / "node" / "bin") + if os.path.isdir(hermes_node_bin): + extra_dirs.append(hermes_node_bin) + + if extra_dirs: + extended_path = os.pathsep.join(extra_dirs) + which_result = shutil.which("agent-browser", path=extended_path) + if which_result: + _cached_agent_browser = which_result + _agent_browser_resolved = True + return which_result + + # Check local node_modules/.bin/ (npm install in repo root) + repo_root = Path(__file__).parent.parent + local_bin = repo_root / "node_modules" / ".bin" / "agent-browser" + if local_bin.exists(): + _cached_agent_browser = str(local_bin) + _agent_browser_resolved = True + return _cached_agent_browser + + # Check common npx locations (also search extended dirs) + npx_path = shutil.which("npx") + if not npx_path and extra_dirs: + npx_path = shutil.which("npx", path=os.pathsep.join(extra_dirs)) + if npx_path: + _cached_agent_browser = "npx agent-browser" + _agent_browser_resolved = True + return _cached_agent_browser + + # Nothing found — cache the failure so subsequent calls don't re-scan. + _agent_browser_resolved = True + raise FileNotFoundError( + "agent-browser CLI not found. Install it with: " + f"{_browser_install_hint()}\n" + "Or run 'npm install' in the repo root to install locally.\n" + "Or ensure npx is available in your PATH." + ) + + +def _extract_screenshot_path_from_text(text: str) -> Optional[str]: + """Extract a screenshot file path from agent-browser human-readable output.""" + if not text: + return None + + patterns = [ + r"Screenshot saved to ['\"](?P/[^'\"]+?\.png)['\"]", + r"Screenshot saved to (?P/\S+?\.png)(?:\s|$)", + r"(?P/\S+?\.png)(?:\s|$)", + ] + + for pattern in patterns: + match = re.search(pattern, text) + if match: + path = match.group("path").strip().strip("'\"") + if path: + return path + + return None + + +def _run_browser_command( + task_id: str, + command: str, + args: List[str] = None, + timeout: Optional[int] = None, +) -> Dict[str, Any]: + """ + Run an agent-browser CLI command using our pre-created Browserbase session. + + Args: + task_id: Task identifier to get the right session + command: The command to run (e.g., "open", "click") + args: Additional arguments for the command + timeout: Command timeout in seconds. ``None`` reads + ``browser.command_timeout`` from config (default 30s). + + Returns: + Parsed JSON response from agent-browser + """ + if timeout is None: + timeout = _get_command_timeout() + args = args or [] + + # Build the command + try: + browser_cmd = _find_agent_browser() + except FileNotFoundError as e: + logger.warning("agent-browser CLI not found: %s", e) + return {"success": False, "error": str(e)} + + if _requires_real_termux_browser_install(browser_cmd): + error = _termux_browser_install_error() + logger.warning("browser command blocked on Termux: %s", error) + return {"success": False, "error": error} + + from tools.interrupt import is_interrupted + if is_interrupted(): + return {"success": False, "error": "Interrupted"} + + # Get session info (creates Browserbase session with proxies if needed) + try: + session_info = _get_session_info(task_id) + except Exception as e: + logger.warning("Failed to create browser session for task=%s: %s", task_id, e) + return {"success": False, "error": f"Failed to create browser session: {str(e)}"} + + # Build the command with the appropriate backend flag. + # Cloud mode: --cdp connects to Browserbase. + # Local mode: --session launches a local headless Chromium. + # The rest of the command (--json, command, args) is identical. + if session_info.get("cdp_url"): + # Cloud mode — connect to remote Browserbase browser via CDP + # IMPORTANT: Do NOT use --session with --cdp. In agent-browser >=0.13, + # --session creates a local browser instance and silently ignores --cdp. + backend_args = ["--cdp", session_info["cdp_url"]] + else: + # Local mode — launch a headless Chromium instance + backend_args = ["--session", session_info["session_name"]] + + # Keep concrete executable paths intact, even when they contain spaces. + # Only the synthetic npx fallback needs to expand into multiple argv items. + cmd_prefix = ["npx", "agent-browser"] if browser_cmd == "npx agent-browser" else [browser_cmd] + + cmd_parts = cmd_prefix + backend_args + [ + "--json", + command + ] + args + + try: + # Give each task its own socket directory to prevent concurrency conflicts. + # Without this, parallel workers fight over the same default socket path, + # causing "Failed to create socket directory: Permission denied" errors. + task_socket_dir = os.path.join( + _socket_safe_tmpdir(), + f"agent-browser-{session_info['session_name']}" + ) + os.makedirs(task_socket_dir, mode=0o700, exist_ok=True) + logger.debug("browser cmd=%s task=%s socket_dir=%s (%d chars)", + command, task_id, task_socket_dir, len(task_socket_dir)) + + browser_env = {**os.environ} + + # Ensure PATH includes Hermes-managed Node first, Homebrew versioned + # node dirs (for macOS ``brew install node@24``), then standard system dirs. + hermes_home = get_hermes_home() + hermes_node_bin = str(hermes_home / "node" / "bin") + + existing_path = browser_env.get("PATH", "") + path_parts = [p for p in existing_path.split(":") if p] + candidate_dirs = ( + [hermes_node_bin] + + list(_discover_homebrew_node_dirs()) + + [p for p in _SANE_PATH.split(":") if p] + ) + + for part in reversed(candidate_dirs): + if os.path.isdir(part) and part not in path_parts: + path_parts.insert(0, part) + + browser_env["PATH"] = ":".join(path_parts) + browser_env["AGENT_BROWSER_SOCKET_DIR"] = task_socket_dir + + # Use temp files for stdout/stderr instead of pipes. + # agent-browser starts a background daemon that inherits file + # descriptors. With capture_output=True (pipes), the daemon keeps + # the pipe fds open after the CLI exits, so communicate() never + # sees EOF and blocks until the timeout fires. + stdout_path = os.path.join(task_socket_dir, f"_stdout_{command}") + stderr_path = os.path.join(task_socket_dir, f"_stderr_{command}") + stdout_fd = os.open(stdout_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600) + stderr_fd = os.open(stderr_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600) + try: + proc = subprocess.Popen( + cmd_parts, + stdout=stdout_fd, + stderr=stderr_fd, + stdin=subprocess.DEVNULL, + env=browser_env, + ) + finally: + os.close(stdout_fd) + os.close(stderr_fd) + + try: + proc.wait(timeout=timeout) + except subprocess.TimeoutExpired: + proc.kill() + proc.wait() + logger.warning("browser '%s' timed out after %ds (task=%s, socket_dir=%s)", + command, timeout, task_id, task_socket_dir) + return {"success": False, "error": f"Command timed out after {timeout} seconds"} + + with open(stdout_path, "r") as f: + stdout = f.read() + with open(stderr_path, "r") as f: + stderr = f.read() + returncode = proc.returncode + + # Clean up temp files (best-effort) + for p in (stdout_path, stderr_path): + try: + os.unlink(p) + except OSError: + pass + + # Log stderr for diagnostics — use warning level on failure so it's visible + if stderr and stderr.strip(): + level = logging.WARNING if returncode != 0 else logging.DEBUG + logger.log(level, "browser '%s' stderr: %s", command, stderr.strip()[:500]) + + stdout_text = stdout.strip() + + # Empty output with rc=0 is a broken state — treat as failure rather + # than silently returning {"success": True, "data": {}}. + # Some commands (close, record) legitimately return no output. + if not stdout_text and returncode == 0 and command not in _EMPTY_OK_COMMANDS: + logger.warning("browser '%s' returned empty output (rc=0)", command) + return {"success": False, "error": f"Browser command '{command}' returned no output"} + + if stdout_text: + try: + parsed = json.loads(stdout_text) + # Warn if snapshot came back empty (common sign of daemon/CDP issues) + if command == "snapshot" and parsed.get("success"): + snap_data = parsed.get("data", {}) + if not snap_data.get("snapshot") and not snap_data.get("refs"): + logger.warning("snapshot returned empty content. " + "Possible stale daemon or CDP connection issue. " + "returncode=%s", returncode) + return parsed + except json.JSONDecodeError: + raw = stdout_text[:2000] + logger.warning("browser '%s' returned non-JSON output (rc=%s): %s", + command, returncode, raw[:500]) + + if command == "screenshot": + stderr_text = (stderr or "").strip() + combined_text = "\n".join( + part for part in [stdout_text, stderr_text] if part + ) + recovered_path = _extract_screenshot_path_from_text(combined_text) + + if recovered_path and Path(recovered_path).exists(): + logger.info( + "browser 'screenshot' recovered file from non-JSON output: %s", + recovered_path, + ) + return { + "success": True, + "data": { + "path": recovered_path, + "raw": raw, + }, + } + + return { + "success": False, + "error": f"Non-JSON output from agent-browser for '{command}': {raw}" + } + + # Check for errors + if returncode != 0: + error_msg = stderr.strip() if stderr else f"Command failed with code {returncode}" + logger.warning("browser '%s' failed (rc=%s): %s", command, returncode, error_msg[:300]) + return {"success": False, "error": error_msg} + + return {"success": True, "data": {}} + + except Exception as e: + logger.warning("browser '%s' exception: %s", command, e, exc_info=True) + return {"success": False, "error": str(e)} + + +def _extract_relevant_content( + snapshot_text: str, + user_task: Optional[str] = None +) -> str: + """Use LLM to extract relevant content from a snapshot based on the user's task. + + Falls back to simple truncation when no auxiliary text model is configured. + """ + if user_task: + extraction_prompt = ( + f"You are a content extractor for a browser automation agent.\n\n" + f"The user's task is: {user_task}\n\n" + f"Given the following page snapshot (accessibility tree representation), " + f"extract and summarize the most relevant information for completing this task. Focus on:\n" + f"1. Interactive elements (buttons, links, inputs) that might be needed\n" + f"2. Text content relevant to the task (prices, descriptions, headings, important info)\n" + f"3. Navigation structure if relevant\n\n" + f"Keep ref IDs (like [ref=e5]) for interactive elements so the agent can use them.\n\n" + f"Page Snapshot:\n{snapshot_text}\n\n" + f"Provide a concise summary that preserves actionable information and relevant content." + ) + else: + extraction_prompt = ( + f"Summarize this page snapshot, preserving:\n" + f"1. All interactive elements with their ref IDs (like [ref=e5])\n" + f"2. Key text content and headings\n" + f"3. Important information visible on the page\n\n" + f"Page Snapshot:\n{snapshot_text}\n\n" + f"Provide a concise summary focused on interactive elements and key content." + ) + + # Redact secrets from snapshot before sending to auxiliary LLM. + # Without this, a page displaying env vars or API keys would leak + # secrets to the extraction model before run_agent.py's general + # redaction layer ever sees the tool result. + from agent.redact import redact_sensitive_text + extraction_prompt = redact_sensitive_text(extraction_prompt) + + try: + call_kwargs = { + "task": "web_extract", + "messages": [{"role": "user", "content": extraction_prompt}], + "max_tokens": 4000, + "temperature": 0.1, + } + model = _get_extraction_model() + if model: + call_kwargs["model"] = model + response = call_llm(**call_kwargs) + extracted = (response.choices[0].message.content or "").strip() or _truncate_snapshot(snapshot_text) + # Redact any secrets the auxiliary LLM may have echoed back. + return redact_sensitive_text(extracted) + except Exception: + return _truncate_snapshot(snapshot_text) + + +def _truncate_snapshot(snapshot_text: str, max_chars: int = 8000) -> str: + """Structure-aware truncation for snapshots. + + Cuts at line boundaries so that accessibility tree elements are never + split mid-line, and appends a note telling the agent how much was + omitted. + + Args: + snapshot_text: The snapshot text to truncate + max_chars: Maximum characters to keep + + Returns: + Truncated text with indicator if truncated + """ + if len(snapshot_text) <= max_chars: + return snapshot_text + + lines = snapshot_text.split('\n') + result: list[str] = [] + chars = 0 + for line in lines: + if chars + len(line) + 1 > max_chars - 80: # reserve space for note + break + result.append(line) + chars += len(line) + 1 + remaining = len(lines) - len(result) + if remaining > 0: + result.append(f'\n[... {remaining} more lines truncated, use browser_snapshot for full content]') + return '\n'.join(result) + + +# ============================================================================ +# Browser Tool Functions +# ============================================================================ + +def browser_navigate(url: str, task_id: Optional[str] = None) -> str: + """ + Navigate to a URL in the browser. + + Args: + url: The URL to navigate to + task_id: Task identifier for session isolation + + Returns: + JSON string with navigation result (includes stealth features info on first nav) + """ + # Secret exfiltration protection — block URLs that embed API keys or + # tokens in query parameters. A prompt injection could trick the agent + # into navigating to https://evil.com/steal?key=sk-ant-... to exfil secrets. + # Also check URL-decoded form to catch %2D encoding tricks (e.g. sk%2Dant%2D...). + import urllib.parse + from agent.redact import _PREFIX_RE + url_decoded = urllib.parse.unquote(url) + if _PREFIX_RE.search(url) or _PREFIX_RE.search(url_decoded): + return json.dumps({ + "success": False, + "error": "Blocked: URL contains what appears to be an API key or token. " + "Secrets must not be sent in URLs.", + }) + + # SSRF protection — block private/internal addresses before navigating. + # Skipped for local backends (Camofox, headless Chromium without a cloud + # provider) because the agent already has full local network access via + # the terminal tool. Can also be opted out for cloud mode via + # ``browser.allow_private_urls`` in config. + if not _is_local_backend() and not _allow_private_urls() and not _is_safe_url(url): + return json.dumps({ + "success": False, + "error": "Blocked: URL targets a private or internal address", + }) + + # Website policy check — block before navigating + blocked = check_website_access(url) + if blocked: + return json.dumps({ + "success": False, + "error": blocked["message"], + "blocked_by_policy": {"host": blocked["host"], "rule": blocked["rule"], "source": blocked["source"]}, + }) + + # Camofox backend — delegate after safety checks pass + if _is_camofox_mode(): + from tools.browser_camofox import camofox_navigate + return camofox_navigate(url, task_id) + + effective_task_id = task_id or "default" + + # Get session info to check if this is a new session + # (will create one with features logged if not exists) + session_info = _get_session_info(effective_task_id) + is_first_nav = session_info.get("_first_nav", True) + + # Auto-start recording if configured and this is first navigation + if is_first_nav: + session_info["_first_nav"] = False + _maybe_start_recording(effective_task_id) + + result = _run_browser_command(effective_task_id, "open", [url], timeout=max(_get_command_timeout(), 60)) + + if result.get("success"): + data = result.get("data", {}) + title = data.get("title", "") + final_url = data.get("url", url) + + # Post-redirect SSRF check — if the browser followed a redirect to a + # private/internal address, block the result so the model can't read + # internal content via subsequent browser_snapshot calls. + # Skipped for local backends (same rationale as the pre-nav check). + if not _is_local_backend() and not _allow_private_urls() and final_url and final_url != url and not _is_safe_url(final_url): + # Navigate away to a blank page to prevent snapshot leaks + _run_browser_command(effective_task_id, "open", ["about:blank"], timeout=10) + return json.dumps({ + "success": False, + "error": "Blocked: redirect landed on a private/internal address", + }) + + response = { + "success": True, + "url": final_url, + "title": title + } + + # Detect common "blocked" page patterns from title/url + blocked_patterns = [ + "access denied", "access to this page has been denied", + "blocked", "bot detected", "verification required", + "please verify", "are you a robot", "captcha", + "cloudflare", "ddos protection", "checking your browser", + "just a moment", "attention required" + ] + title_lower = title.lower() + + if any(pattern in title_lower for pattern in blocked_patterns): + response["bot_detection_warning"] = ( + f"Page title '{title}' suggests bot detection. The site may have blocked this request. " + "Options: 1) Try adding delays between actions, 2) Access different pages first, " + "3) Enable advanced stealth (BROWSERBASE_ADVANCED_STEALTH=true, requires Scale plan), " + "4) Some sites have very aggressive bot detection that may be unavoidable." + ) + + # Include feature info on first navigation so model knows what's active + if is_first_nav and "features" in session_info: + features = session_info["features"] + active_features = [k for k, v in features.items() if v] + if not features.get("proxies"): + response["stealth_warning"] = ( + "Running WITHOUT residential proxies. Bot detection may be more aggressive. " + "Consider upgrading Browserbase plan for proxy support." + ) + response["stealth_features"] = active_features + + # Auto-take a compact snapshot so the model can act immediately + # without a separate browser_snapshot call. + try: + snap_result = _run_browser_command(effective_task_id, "snapshot", ["-c"]) + if snap_result.get("success"): + snap_data = snap_result.get("data", {}) + snapshot_text = snap_data.get("snapshot", "") + refs = snap_data.get("refs", {}) + if len(snapshot_text) > SNAPSHOT_SUMMARIZE_THRESHOLD: + snapshot_text = _truncate_snapshot(snapshot_text) + response["snapshot"] = snapshot_text + response["element_count"] = len(refs) if refs else 0 + except Exception as e: + logger.debug("Auto-snapshot after navigate failed: %s", e) + + return json.dumps(response, ensure_ascii=False) + else: + return json.dumps({ + "success": False, + "error": result.get("error", "Navigation failed") + }, ensure_ascii=False) + + +def browser_snapshot( + full: bool = False, + task_id: Optional[str] = None, + user_task: Optional[str] = None +) -> str: + """ + Get a text-based snapshot of the current page's accessibility tree. + + Args: + full: If True, return complete snapshot. If False, return compact view. + task_id: Task identifier for session isolation + user_task: The user's current task (for task-aware extraction) + + Returns: + JSON string with page snapshot + """ + if _is_camofox_mode(): + from tools.browser_camofox import camofox_snapshot + return camofox_snapshot(full, task_id, user_task) + + effective_task_id = task_id or "default" + + # Build command args based on full flag + args = [] + if not full: + args.extend(["-c"]) # Compact mode + + result = _run_browser_command(effective_task_id, "snapshot", args) + + if result.get("success"): + data = result.get("data", {}) + snapshot_text = data.get("snapshot", "") + refs = data.get("refs", {}) + + # Check if snapshot needs summarization + if len(snapshot_text) > SNAPSHOT_SUMMARIZE_THRESHOLD and user_task: + snapshot_text = _extract_relevant_content(snapshot_text, user_task) + elif len(snapshot_text) > SNAPSHOT_SUMMARIZE_THRESHOLD: + snapshot_text = _truncate_snapshot(snapshot_text) + + response = { + "success": True, + "snapshot": snapshot_text, + "element_count": len(refs) if refs else 0 + } + + return json.dumps(response, ensure_ascii=False) + else: + return json.dumps({ + "success": False, + "error": result.get("error", "Failed to get snapshot") + }, ensure_ascii=False) + + +def browser_click(ref: str, task_id: Optional[str] = None) -> str: + """ + Click on an element. + + Args: + ref: Element reference (e.g., "@e5") + task_id: Task identifier for session isolation + + Returns: + JSON string with click result + """ + if _is_camofox_mode(): + from tools.browser_camofox import camofox_click + return camofox_click(ref, task_id) + + effective_task_id = task_id or "default" + + # Ensure ref starts with @ + if not ref.startswith("@"): + ref = f"@{ref}" + + result = _run_browser_command(effective_task_id, "click", [ref]) + + if result.get("success"): + return json.dumps({ + "success": True, + "clicked": ref + }, ensure_ascii=False) + else: + return json.dumps({ + "success": False, + "error": result.get("error", f"Failed to click {ref}") + }, ensure_ascii=False) + + +def browser_type(ref: str, text: str, task_id: Optional[str] = None) -> str: + """ + Type text into an input field. + + Args: + ref: Element reference (e.g., "@e3") + text: Text to type + task_id: Task identifier for session isolation + + Returns: + JSON string with type result + """ + if _is_camofox_mode(): + from tools.browser_camofox import camofox_type + return camofox_type(ref, text, task_id) + + effective_task_id = task_id or "default" + + # Ensure ref starts with @ + if not ref.startswith("@"): + ref = f"@{ref}" + + # Use fill command (clears then types) + result = _run_browser_command(effective_task_id, "fill", [ref, text]) + + if result.get("success"): + return json.dumps({ + "success": True, + "typed": text, + "element": ref + }, ensure_ascii=False) + else: + return json.dumps({ + "success": False, + "error": result.get("error", f"Failed to type into {ref}") + }, ensure_ascii=False) + + +def browser_scroll(direction: str, task_id: Optional[str] = None) -> str: + """ + Scroll the page. + + Args: + direction: "up" or "down" + task_id: Task identifier for session isolation + + Returns: + JSON string with scroll result + """ + # Validate direction + if direction not in ["up", "down"]: + return json.dumps({ + "success": False, + "error": f"Invalid direction '{direction}'. Use 'up' or 'down'." + }, ensure_ascii=False) + + # Single scroll with pixel amount instead of 5x subprocess calls. + # agent-browser supports: agent-browser scroll down 500 + # ~500px is roughly half a viewport of travel. + _SCROLL_PIXELS = 500 + + if _is_camofox_mode(): + from tools.browser_camofox import camofox_scroll + # Camofox REST API doesn't support pixel args; use repeated calls + _SCROLL_REPEATS = 5 + result = None + for _ in range(_SCROLL_REPEATS): + result = camofox_scroll(direction, task_id) + return result + + effective_task_id = task_id or "default" + + result = _run_browser_command(effective_task_id, "scroll", [direction, str(_SCROLL_PIXELS)]) + if not result.get("success"): + return json.dumps({ + "success": False, + "error": result.get("error", f"Failed to scroll {direction}") + }, ensure_ascii=False) + + return json.dumps({ + "success": True, + "scrolled": direction + }, ensure_ascii=False) + + +def browser_back(task_id: Optional[str] = None) -> str: + """ + Navigate back in browser history. + + Args: + task_id: Task identifier for session isolation + + Returns: + JSON string with navigation result + """ + if _is_camofox_mode(): + from tools.browser_camofox import camofox_back + return camofox_back(task_id) + + effective_task_id = task_id or "default" + result = _run_browser_command(effective_task_id, "back", []) + + if result.get("success"): + data = result.get("data", {}) + return json.dumps({ + "success": True, + "url": data.get("url", "") + }, ensure_ascii=False) + else: + return json.dumps({ + "success": False, + "error": result.get("error", "Failed to go back") + }, ensure_ascii=False) + + +def browser_press(key: str, task_id: Optional[str] = None) -> str: + """ + Press a keyboard key. + + Args: + key: Key to press (e.g., "Enter", "Tab") + task_id: Task identifier for session isolation + + Returns: + JSON string with key press result + """ + if _is_camofox_mode(): + from tools.browser_camofox import camofox_press + return camofox_press(key, task_id) + + effective_task_id = task_id or "default" + result = _run_browser_command(effective_task_id, "press", [key]) + + if result.get("success"): + return json.dumps({ + "success": True, + "pressed": key + }, ensure_ascii=False) + else: + return json.dumps({ + "success": False, + "error": result.get("error", f"Failed to press {key}") + }, ensure_ascii=False) + + + + + +def browser_console(clear: bool = False, expression: Optional[str] = None, task_id: Optional[str] = None) -> str: + """Get browser console messages and JavaScript errors, or evaluate JS in the page. + + When ``expression`` is provided, evaluates JavaScript in the page context + (like the DevTools console) and returns the result. Otherwise returns + console output (log/warn/error/info) and uncaught exceptions. + + Args: + clear: If True, clear the message/error buffers after reading + expression: JavaScript expression to evaluate in the page context + task_id: Task identifier for session isolation + + Returns: + JSON string with console messages/errors, or eval result + """ + # --- JS evaluation mode --- + if expression is not None: + return _browser_eval(expression, task_id) + + # --- Console output mode (original behaviour) --- + if _is_camofox_mode(): + from tools.browser_camofox import camofox_console + return camofox_console(clear, task_id) + + effective_task_id = task_id or "default" + + console_args = ["--clear"] if clear else [] + error_args = ["--clear"] if clear else [] + + console_result = _run_browser_command(effective_task_id, "console", console_args) + errors_result = _run_browser_command(effective_task_id, "errors", error_args) + + messages = [] + if console_result.get("success"): + for msg in console_result.get("data", {}).get("messages", []): + messages.append({ + "type": msg.get("type", "log"), + "text": msg.get("text", ""), + "source": "console", + }) + + errors = [] + if errors_result.get("success"): + for err in errors_result.get("data", {}).get("errors", []): + errors.append({ + "message": err.get("message", ""), + "source": "exception", + }) + + return json.dumps({ + "success": True, + "console_messages": messages, + "js_errors": errors, + "total_messages": len(messages), + "total_errors": len(errors), + }, ensure_ascii=False) + + +def _browser_eval(expression: str, task_id: Optional[str] = None) -> str: + """Evaluate a JavaScript expression in the page context and return the result.""" + if _is_camofox_mode(): + return _camofox_eval(expression, task_id) + + effective_task_id = task_id or "default" + result = _run_browser_command(effective_task_id, "eval", [expression]) + + if not result.get("success"): + err = result.get("error", "eval failed") + # Detect backend capability gaps and give the model a clear signal + if any(hint in err.lower() for hint in ("unknown command", "not supported", "not found", "no such command")): + return json.dumps({ + "success": False, + "error": f"JavaScript evaluation is not supported by this browser backend. {err}", + }) + return json.dumps({ + "success": False, + "error": err, + }) + + data = result.get("data", {}) + raw_result = data.get("result") + + # The eval command returns the JS result as a string. If the string + # is valid JSON, parse it so the model gets structured data. + parsed = raw_result + if isinstance(raw_result, str): + try: + parsed = json.loads(raw_result) + except (json.JSONDecodeError, ValueError): + pass # keep as string + + return json.dumps({ + "success": True, + "result": parsed, + "result_type": type(parsed).__name__, + }, ensure_ascii=False, default=str) + + +def _camofox_eval(expression: str, task_id: Optional[str] = None) -> str: + """Evaluate JS via Camofox's /tabs/{tab_id}/eval endpoint (if available).""" + from tools.browser_camofox import _ensure_tab, _post + try: + tab_info = _ensure_tab(task_id or "default") + tab_id = tab_info.get("tab_id") or tab_info.get("id") + resp = _post(f"/tabs/{tab_id}/eval", body={"expression": expression}) + + # Camofox returns the result in a JSON envelope + raw_result = resp.get("result") if isinstance(resp, dict) else resp + parsed = raw_result + if isinstance(raw_result, str): + try: + parsed = json.loads(raw_result) + except (json.JSONDecodeError, ValueError): + pass + + return json.dumps({ + "success": True, + "result": parsed, + "result_type": type(parsed).__name__, + }, ensure_ascii=False, default=str) + except Exception as e: + error_msg = str(e) + # Graceful degradation — server may not support eval + if any(code in error_msg for code in ("404", "405", "501")): + return json.dumps({ + "success": False, + "error": "JavaScript evaluation is not supported by this Camofox server. " + "Use browser_snapshot or browser_vision to inspect page state.", + }) + return tool_error(error_msg, success=False) + + +def _maybe_start_recording(task_id: str): + """Start recording if browser.record_sessions is enabled in config.""" + with _cleanup_lock: + if task_id in _recording_sessions: + return + try: + from hermes_cli.config import read_raw_config + hermes_home = get_hermes_home() + cfg = read_raw_config() + record_enabled = cfg.get("browser", {}).get("record_sessions", False) + + if not record_enabled: + return + + recordings_dir = hermes_home / "browser_recordings" + recordings_dir.mkdir(parents=True, exist_ok=True) + _cleanup_old_recordings(max_age_hours=72) + + import time + timestamp = time.strftime("%Y%m%d_%H%M%S") + recording_path = recordings_dir / f"session_{timestamp}_{task_id[:16]}.webm" + + result = _run_browser_command(task_id, "record", ["start", str(recording_path)]) + if result.get("success"): + with _cleanup_lock: + _recording_sessions.add(task_id) + logger.info("Auto-recording browser session %s to %s", task_id, recording_path) + else: + logger.debug("Could not start auto-recording: %s", result.get("error")) + except Exception as e: + logger.debug("Auto-recording setup failed: %s", e) + + +def _maybe_stop_recording(task_id: str): + """Stop recording if one is active for this session.""" + with _cleanup_lock: + if task_id not in _recording_sessions: + return + try: + result = _run_browser_command(task_id, "record", ["stop"]) + if result.get("success"): + path = result.get("data", {}).get("path", "") + logger.info("Saved browser recording for session %s: %s", task_id, path) + except Exception as e: + logger.debug("Could not stop recording for %s: %s", task_id, e) + finally: + with _cleanup_lock: + _recording_sessions.discard(task_id) + + +def browser_get_images(task_id: Optional[str] = None) -> str: + """ + Get all images on the current page. + + Args: + task_id: Task identifier for session isolation + + Returns: + JSON string with list of images (src and alt) + """ + if _is_camofox_mode(): + from tools.browser_camofox import camofox_get_images + return camofox_get_images(task_id) + + effective_task_id = task_id or "default" + + # Use eval to run JavaScript that extracts images + js_code = """JSON.stringify( + [...document.images].map(img => ({ + src: img.src, + alt: img.alt || '', + width: img.naturalWidth, + height: img.naturalHeight + })).filter(img => img.src && !img.src.startsWith('data:')) + )""" + + result = _run_browser_command(effective_task_id, "eval", [js_code]) + + if result.get("success"): + data = result.get("data", {}) + raw_result = data.get("result", "[]") + + try: + # Parse the JSON string returned by JavaScript + if isinstance(raw_result, str): + images = json.loads(raw_result) + else: + images = raw_result + + return json.dumps({ + "success": True, + "images": images, + "count": len(images) + }, ensure_ascii=False) + except json.JSONDecodeError: + return json.dumps({ + "success": True, + "images": [], + "count": 0, + "warning": "Could not parse image data" + }, ensure_ascii=False) + else: + return json.dumps({ + "success": False, + "error": result.get("error", "Failed to get images") + }, ensure_ascii=False) + + +def browser_vision(question: str, annotate: bool = False, task_id: Optional[str] = None) -> str: + """ + Take a screenshot of the current page and analyze it with vision AI. + + This tool captures what's visually displayed in the browser and sends it + to Gemini for analysis. Useful for understanding visual content that the + text-based snapshot may not capture (CAPTCHAs, verification challenges, + images, complex layouts, etc.). + + The screenshot is saved persistently and its file path is returned alongside + the analysis, so it can be shared with users via MEDIA: in the response. + + Args: + question: What you want to know about the page visually + annotate: If True, overlay numbered [N] labels on interactive elements + task_id: Task identifier for session isolation + + Returns: + JSON string with vision analysis results and screenshot_path + """ + if _is_camofox_mode(): + from tools.browser_camofox import camofox_vision + return camofox_vision(question, annotate, task_id) + + import base64 + import uuid as uuid_mod + from pathlib import Path + + effective_task_id = task_id or "default" + + # Save screenshot to persistent location so it can be shared with users + from hermes_constants import get_hermes_dir + screenshots_dir = get_hermes_dir("cache/screenshots", "browser_screenshots") + screenshot_path = screenshots_dir / f"browser_screenshot_{uuid_mod.uuid4().hex}.png" + + try: + screenshots_dir.mkdir(parents=True, exist_ok=True) + + # Prune old screenshots (older than 24 hours) to prevent unbounded disk growth + _cleanup_old_screenshots(screenshots_dir, max_age_hours=24) + + # Take screenshot using agent-browser + screenshot_args = [] + if annotate: + screenshot_args.append("--annotate") + screenshot_args.append("--full") + screenshot_args.append(str(screenshot_path)) + result = _run_browser_command( + effective_task_id, + "screenshot", + screenshot_args, + ) + + if not result.get("success"): + error_detail = result.get("error", "Unknown error") + _cp = _get_cloud_provider() + mode = "local" if _cp is None else f"cloud ({_cp.provider_name()})" + return json.dumps({ + "success": False, + "error": f"Failed to take screenshot ({mode} mode): {error_detail}" + }, ensure_ascii=False) + + actual_screenshot_path = result.get("data", {}).get("path") + if actual_screenshot_path: + screenshot_path = Path(actual_screenshot_path) + + # Check if screenshot file was created + if not screenshot_path.exists(): + _cp = _get_cloud_provider() + mode = "local" if _cp is None else f"cloud ({_cp.provider_name()})" + return json.dumps({ + "success": False, + "error": ( + f"Screenshot file was not created at {screenshot_path} ({mode} mode). " + f"This may indicate a socket path issue (macOS /var/folders/), " + f"a missing Chromium install ('agent-browser install'), " + f"or a stale daemon process." + ), + }, ensure_ascii=False) + + # Convert screenshot to base64 at full resolution. + _screenshot_bytes = screenshot_path.read_bytes() + _screenshot_b64 = base64.b64encode(_screenshot_bytes).decode("ascii") + data_url = f"data:image/png;base64,{_screenshot_b64}" + + vision_prompt = ( + f"You are analyzing a screenshot of a web browser.\n\n" + f"User's question: {question}\n\n" + f"Provide a detailed and helpful answer based on what you see in the screenshot. " + f"If there are interactive elements, describe them. If there are verification challenges " + f"or CAPTCHAs, describe what type they are and what action might be needed. " + f"Focus on answering the user's specific question." + ) + + # Use the centralized LLM router + vision_model = _get_vision_model() + logger.debug("browser_vision: analysing screenshot (%d bytes)", + len(_screenshot_bytes)) + + # Read vision timeout from config (auxiliary.vision.timeout), default 120s. + # Local vision models (llama.cpp, ollama) can take well over 30s for + # screenshot analysis, so the default must be generous. + vision_timeout = 120.0 + try: + from hermes_cli.config import load_config + _cfg = load_config() + _vt = _cfg.get("auxiliary", {}).get("vision", {}).get("timeout") + if _vt is not None: + vision_timeout = float(_vt) + except Exception: + pass + + call_kwargs = { + "task": "vision", + "messages": [ + { + "role": "user", + "content": [ + {"type": "text", "text": vision_prompt}, + {"type": "image_url", "image_url": {"url": data_url}}, + ], + } + ], + "max_tokens": 2000, + "temperature": 0.1, + "timeout": vision_timeout, + } + if vision_model: + call_kwargs["model"] = vision_model + # Try full-size screenshot; on size-related rejection, downscale and retry. + try: + response = call_llm(**call_kwargs) + except Exception as _api_err: + from tools.vision_tools import ( + _is_image_size_error, _resize_image_for_vision, _RESIZE_TARGET_BYTES, + ) + if (_is_image_size_error(_api_err) + and len(data_url) > _RESIZE_TARGET_BYTES): + logger.info( + "Vision API rejected screenshot (%.1f MB); " + "auto-resizing to ~%.0f MB and retrying...", + len(data_url) / (1024 * 1024), + _RESIZE_TARGET_BYTES / (1024 * 1024), + ) + data_url = _resize_image_for_vision( + screenshot_path, mime_type="image/png") + call_kwargs["messages"][0]["content"][1]["image_url"]["url"] = data_url + response = call_llm(**call_kwargs) + else: + raise + + analysis = (response.choices[0].message.content or "").strip() + # Redact secrets the vision LLM may have read from the screenshot. + from agent.redact import redact_sensitive_text + analysis = redact_sensitive_text(analysis) + response_data = { + "success": True, + "analysis": analysis or "Vision analysis returned no content.", + "screenshot_path": str(screenshot_path), + } + # Include annotation data if annotated screenshot was taken + if annotate and result.get("data", {}).get("annotations"): + response_data["annotations"] = result["data"]["annotations"] + return json.dumps(response_data, ensure_ascii=False) + + except Exception as e: + # Keep the screenshot if it was captured successfully — the failure is + # in the LLM vision analysis, not the capture. Deleting a valid + # screenshot loses evidence the user might need. The 24-hour cleanup + # in _cleanup_old_screenshots prevents unbounded disk growth. + logger.warning("browser_vision failed: %s", e, exc_info=True) + error_info = {"success": False, "error": f"Error during vision analysis: {str(e)}"} + if screenshot_path.exists(): + error_info["screenshot_path"] = str(screenshot_path) + error_info["note"] = "Screenshot was captured but vision analysis failed. You can still share it via MEDIA:." + return json.dumps(error_info, ensure_ascii=False) + + +def _cleanup_old_screenshots(screenshots_dir, max_age_hours=24): + """Remove browser screenshots older than max_age_hours to prevent disk bloat. + + Throttled to run at most once per hour per directory to avoid repeated + scans on screenshot-heavy workflows. + """ + key = str(screenshots_dir) + now = time.time() + if now - _last_screenshot_cleanup_by_dir.get(key, 0.0) < 3600: + return + _last_screenshot_cleanup_by_dir[key] = now + + try: + cutoff = time.time() - (max_age_hours * 3600) + for f in screenshots_dir.glob("browser_screenshot_*.png"): + try: + if f.stat().st_mtime < cutoff: + f.unlink() + except Exception as e: + logger.debug("Failed to clean old screenshot %s: %s", f, e) + except Exception as e: + logger.debug("Screenshot cleanup error (non-critical): %s", e) + + +def _cleanup_old_recordings(max_age_hours=72): + """Remove browser recordings older than max_age_hours to prevent disk bloat.""" + import time + try: + hermes_home = get_hermes_home() + recordings_dir = hermes_home / "browser_recordings" + if not recordings_dir.exists(): + return + cutoff = time.time() - (max_age_hours * 3600) + for f in recordings_dir.glob("session_*.webm"): + try: + if f.stat().st_mtime < cutoff: + f.unlink() + except Exception as e: + logger.debug("Failed to clean old recording %s: %s", f, e) + except Exception as e: + logger.debug("Recording cleanup error (non-critical): %s", e) + + +# ============================================================================ +# Cleanup and Management Functions +# ============================================================================ + +def cleanup_browser(task_id: Optional[str] = None) -> None: + """ + Clean up browser session for a task. + + Called automatically when a task completes or when inactivity timeout is reached. + Closes both the agent-browser/Browserbase session and Camofox sessions. + + Args: + task_id: Task identifier to clean up + """ + if task_id is None: + task_id = "default" + + # Also clean up Camofox session if running in Camofox mode. + # Skip full close when managed persistence is enabled — the browser + # profile (and its session cookies) must survive across agent tasks. + # The inactivity reaper still frees idle resources. + if _is_camofox_mode(): + try: + from tools.browser_camofox import camofox_close, camofox_soft_cleanup + if not camofox_soft_cleanup(task_id): + camofox_close(task_id) + except Exception as e: + logger.debug("Camofox cleanup for task %s: %s", task_id, e) + + logger.debug("cleanup_browser called for task_id: %s", task_id) + logger.debug("Active sessions: %s", list(_active_sessions.keys())) + + # Check if session exists (under lock), but don't remove yet - + # _run_browser_command needs it to build the close command. + with _cleanup_lock: + session_info = _active_sessions.get(task_id) + + if session_info: + bb_session_id = session_info.get("bb_session_id", "unknown") + logger.debug("Found session for task %s: bb_session_id=%s", task_id, bb_session_id) + + # Stop auto-recording before closing (saves the file) + _maybe_stop_recording(task_id) + + # Try to close via agent-browser first (needs session in _active_sessions) + try: + _run_browser_command(task_id, "close", [], timeout=10) + logger.debug("agent-browser close command completed for task %s", task_id) + except Exception as e: + logger.warning("agent-browser close failed for task %s: %s", task_id, e) + + # Now remove from tracking under lock + with _cleanup_lock: + _active_sessions.pop(task_id, None) + _session_last_activity.pop(task_id, None) + + # Cloud mode: close the cloud browser session via provider API + if bb_session_id: + provider = _get_cloud_provider() + if provider is not None: + try: + provider.close_session(bb_session_id) + except Exception as e: + logger.warning("Could not close cloud browser session: %s", e) + + # Kill the daemon process and clean up socket directory + session_name = session_info.get("session_name", "") + if session_name: + socket_dir = os.path.join(_socket_safe_tmpdir(), f"agent-browser-{session_name}") + if os.path.exists(socket_dir): + # agent-browser writes {session}.pid in the socket dir + pid_file = os.path.join(socket_dir, f"{session_name}.pid") + if os.path.isfile(pid_file): + try: + daemon_pid = int(Path(pid_file).read_text().strip()) + os.kill(daemon_pid, signal.SIGTERM) + logger.debug("Killed daemon pid %s for %s", daemon_pid, session_name) + except (ProcessLookupError, ValueError, PermissionError, OSError): + logger.debug("Could not kill daemon pid for %s (already dead or inaccessible)", session_name) + shutil.rmtree(socket_dir, ignore_errors=True) + + logger.debug("Removed task %s from active sessions", task_id) + else: + logger.debug("No active session found for task_id: %s", task_id) + + +def cleanup_all_browsers() -> None: + """ + Clean up all active browser sessions. + + Useful for cleanup on shutdown. + """ + with _cleanup_lock: + task_ids = list(_active_sessions.keys()) + for task_id in task_ids: + cleanup_browser(task_id) + + # Reset cached lookups so they are re-evaluated on next use. + global _cached_agent_browser, _agent_browser_resolved + global _cached_command_timeout, _command_timeout_resolved + _cached_agent_browser = None + _agent_browser_resolved = False + _discover_homebrew_node_dirs.cache_clear() + _cached_command_timeout = None + _command_timeout_resolved = False + + +# ============================================================================ +# Requirements Check +# ============================================================================ + +def check_browser_requirements() -> bool: + """ + Check if browser tool requirements are met. + + In **local mode** (no cloud provider configured): only the + ``agent-browser`` CLI must be findable. + + In **cloud mode** (Browserbase, Browser Use, or Firecrawl): the CLI + *and* the provider's required credentials must be present. + + Returns: + True if all requirements are met, False otherwise + """ + # Camofox backend — only needs the server URL, no agent-browser CLI + if _is_camofox_mode(): + return True + + # The agent-browser CLI is always required + try: + browser_cmd = _find_agent_browser() + except FileNotFoundError: + return False + + # On Termux, the bare npx fallback is too fragile to treat as a satisfied + # local browser dependency. Require a real install (global or local) so the + # browser tool is not advertised as available when it will likely fail on + # first use. + if _requires_real_termux_browser_install(browser_cmd): + return False + + # In cloud mode, also require provider credentials + provider = _get_cloud_provider() + if provider is not None and not provider.is_configured(): + return False + + return True + + +# ============================================================================ +# Module Test +# ============================================================================ + +if __name__ == "__main__": + """ + Simple test/demo when run directly + """ + print("🌐 Browser Tool Module") + print("=" * 40) + + _cp = _get_cloud_provider() + mode = "local" if _cp is None else f"cloud ({_cp.provider_name()})" + print(f" Mode: {mode}") + + # Check requirements + if check_browser_requirements(): + print("✅ All requirements met") + else: + print("❌ Missing requirements:") + try: + browser_cmd = _find_agent_browser() + if _requires_real_termux_browser_install(browser_cmd): + print(" - bare npx fallback found (insufficient on Termux local mode)") + print(f" Install: {_browser_install_hint()}") + except FileNotFoundError: + print(" - agent-browser CLI not found") + print(f" Install: {_browser_install_hint()}") + if _cp is not None and not _cp.is_configured(): + print(f" - {_cp.provider_name()} credentials not configured") + print(" Tip: set browser.cloud_provider to 'local' to use free local mode instead") + + print("\n📋 Available Browser Tools:") + for schema in BROWSER_TOOL_SCHEMAS: + print(f" 🔹 {schema['name']}: {schema['description'][:60]}...") + + print("\n💡 Usage:") + print(" from tools.browser_tool import browser_navigate, browser_snapshot") + print(" result = browser_navigate('https://example.com', task_id='my_task')") + print(" snapshot = browser_snapshot(task_id='my_task')") + + +# --------------------------------------------------------------------------- +# Registry +# --------------------------------------------------------------------------- +from tools.registry import registry, tool_error + +_BROWSER_SCHEMA_MAP = {s["name"]: s for s in BROWSER_TOOL_SCHEMAS} + +registry.register( + name="browser_navigate", + toolset="browser", + schema=_BROWSER_SCHEMA_MAP["browser_navigate"], + handler=lambda args, **kw: browser_navigate(url=args.get("url", ""), task_id=kw.get("task_id")), + check_fn=check_browser_requirements, + emoji="🌐", +) +registry.register( + name="browser_snapshot", + toolset="browser", + schema=_BROWSER_SCHEMA_MAP["browser_snapshot"], + handler=lambda args, **kw: browser_snapshot( + full=args.get("full", False), task_id=kw.get("task_id"), user_task=kw.get("user_task")), + check_fn=check_browser_requirements, + emoji="📸", +) +registry.register( + name="browser_click", + toolset="browser", + schema=_BROWSER_SCHEMA_MAP["browser_click"], + handler=lambda args, **kw: browser_click(ref=args.get("ref", ""), task_id=kw.get("task_id")), + check_fn=check_browser_requirements, + emoji="👆", +) +registry.register( + name="browser_type", + toolset="browser", + schema=_BROWSER_SCHEMA_MAP["browser_type"], + handler=lambda args, **kw: browser_type(ref=args.get("ref", ""), text=args.get("text", ""), task_id=kw.get("task_id")), + check_fn=check_browser_requirements, + emoji="⌨️", +) +registry.register( + name="browser_scroll", + toolset="browser", + schema=_BROWSER_SCHEMA_MAP["browser_scroll"], + handler=lambda args, **kw: browser_scroll(direction=args.get("direction", "down"), task_id=kw.get("task_id")), + check_fn=check_browser_requirements, + emoji="📜", +) +registry.register( + name="browser_back", + toolset="browser", + schema=_BROWSER_SCHEMA_MAP["browser_back"], + handler=lambda args, **kw: browser_back(task_id=kw.get("task_id")), + check_fn=check_browser_requirements, + emoji="◀️", +) +registry.register( + name="browser_press", + toolset="browser", + schema=_BROWSER_SCHEMA_MAP["browser_press"], + handler=lambda args, **kw: browser_press(key=args.get("key", ""), task_id=kw.get("task_id")), + check_fn=check_browser_requirements, + emoji="⌨️", +) + +registry.register( + name="browser_get_images", + toolset="browser", + schema=_BROWSER_SCHEMA_MAP["browser_get_images"], + handler=lambda args, **kw: browser_get_images(task_id=kw.get("task_id")), + check_fn=check_browser_requirements, + emoji="🖼️", +) +registry.register( + name="browser_vision", + toolset="browser", + schema=_BROWSER_SCHEMA_MAP["browser_vision"], + handler=lambda args, **kw: browser_vision(question=args.get("question", ""), annotate=args.get("annotate", False), task_id=kw.get("task_id")), + check_fn=check_browser_requirements, + emoji="👁️", +) +registry.register( + name="browser_console", + toolset="browser", + schema=_BROWSER_SCHEMA_MAP["browser_console"], + handler=lambda args, **kw: browser_console(clear=args.get("clear", False), expression=args.get("expression"), task_id=kw.get("task_id")), + check_fn=check_browser_requirements, + emoji="🖥️", +) diff --git a/mindcli/_vendor/tools/budget_config.py b/mindcli/_vendor/tools/budget_config.py new file mode 100644 index 0000000..577e594 --- /dev/null +++ b/mindcli/_vendor/tools/budget_config.py @@ -0,0 +1,52 @@ +"""Configurable budget constants for tool result persistence. + +Overridable at the RL environment level via HermesAgentEnvConfig fields. +Per-tool resolution: pinned > config overrides > registry > default. +""" + +from dataclasses import dataclass, field +from typing import Dict + +# Tools whose thresholds must never be overridden. +# read_file=inf prevents infinite persist->read->persist loops. +PINNED_THRESHOLDS: Dict[str, float] = { + "read_file": float("inf"), +} + +# Defaults matching the current hardcoded values in tool_result_storage.py. +# Kept here as the single source of truth; tool_result_storage.py imports these. +DEFAULT_RESULT_SIZE_CHARS: int = 100_000 +DEFAULT_TURN_BUDGET_CHARS: int = 200_000 +DEFAULT_PREVIEW_SIZE_CHARS: int = 1_500 + + +@dataclass(frozen=True) +class BudgetConfig: + """Immutable budget constants for the 3-layer tool result persistence system. + + Layer 2 (per-result): resolve_threshold(tool_name) -> threshold in chars. + Layer 3 (per-turn): turn_budget -> aggregate char budget across all tool + results in a single assistant turn. + Preview: preview_size -> inline snippet size after persistence. + """ + + default_result_size: int = DEFAULT_RESULT_SIZE_CHARS + turn_budget: int = DEFAULT_TURN_BUDGET_CHARS + preview_size: int = DEFAULT_PREVIEW_SIZE_CHARS + tool_overrides: Dict[str, int] = field(default_factory=dict) + + def resolve_threshold(self, tool_name: str) -> int | float: + """Resolve the persistence threshold for a tool. + + Priority: pinned -> tool_overrides -> registry per-tool -> default. + """ + if tool_name in PINNED_THRESHOLDS: + return PINNED_THRESHOLDS[tool_name] + if tool_name in self.tool_overrides: + return self.tool_overrides[tool_name] + from tools.registry import registry + return registry.get_max_result_size(tool_name, default=self.default_result_size) + + +# Default config -- matches current hardcoded behavior exactly. +DEFAULT_BUDGET = BudgetConfig() diff --git a/mindcli/_vendor/tools/checkpoint_manager.py b/mindcli/_vendor/tools/checkpoint_manager.py new file mode 100644 index 0000000..42900a6 --- /dev/null +++ b/mindcli/_vendor/tools/checkpoint_manager.py @@ -0,0 +1,623 @@ +""" +Checkpoint Manager — Transparent filesystem snapshots via shadow git repos. + +Creates automatic snapshots of working directories before file-mutating +operations (write_file, patch), triggered once per conversation turn. +Provides rollback to any previous checkpoint. + +This is NOT a tool — the LLM never sees it. It's transparent infrastructure +controlled by the ``checkpoints`` config flag or ``--checkpoints`` CLI flag. + +Architecture: + ~/.hermes/checkpoints/{sha256(abs_dir)[:16]}/ — shadow git repo + HEAD, refs/, objects/ — standard git internals + HERMES_WORKDIR — original dir path + info/exclude — default excludes + +The shadow repo uses GIT_DIR + GIT_WORK_TREE so no git state leaks +into the user's project directory. +""" + +import hashlib +import logging +import os +import re +import shutil +import subprocess +from pathlib import Path +from hermes_constants import get_hermes_home +from typing import Dict, List, Optional, Set + +logger = logging.getLogger(__name__) + +# --------------------------------------------------------------------------- +# Constants +# --------------------------------------------------------------------------- + +CHECKPOINT_BASE = get_hermes_home() / "checkpoints" + +DEFAULT_EXCLUDES = [ + "node_modules/", + "dist/", + "build/", + ".env", + ".env.*", + ".env.local", + ".env.*.local", + "__pycache__/", + "*.pyc", + "*.pyo", + ".DS_Store", + "*.log", + ".cache/", + ".next/", + ".nuxt/", + "coverage/", + ".pytest_cache/", + ".venv/", + "venv/", + ".git/", +] + +# Git subprocess timeout (seconds). +_GIT_TIMEOUT: int = max(10, min(60, int(os.getenv("HERMES_CHECKPOINT_TIMEOUT", "30")))) + +# Max files to snapshot — skip huge directories to avoid slowdowns. +_MAX_FILES = 50_000 + +# Valid git commit hash pattern: 4–40 hex chars (short or full SHA-1/SHA-256). +_COMMIT_HASH_RE = re.compile(r'^[0-9a-fA-F]{4,64}$') + + +# --------------------------------------------------------------------------- +# Input validation helpers +# --------------------------------------------------------------------------- + +def _validate_commit_hash(commit_hash: str) -> Optional[str]: + """Validate a commit hash to prevent git argument injection. + + Returns an error string if invalid, None if valid. + Values starting with '-' would be interpreted as git flags + (e.g., '--patch', '-p') instead of revision specifiers. + """ + if not commit_hash or not commit_hash.strip(): + return "Empty commit hash" + if commit_hash.startswith("-"): + return f"Invalid commit hash (must not start with '-'): {commit_hash!r}" + if not _COMMIT_HASH_RE.match(commit_hash): + return f"Invalid commit hash (expected 4-64 hex characters): {commit_hash!r}" + return None + + +def _validate_file_path(file_path: str, working_dir: str) -> Optional[str]: + """Validate a file path to prevent path traversal outside the working directory. + + Returns an error string if invalid, None if valid. + """ + if not file_path or not file_path.strip(): + return "Empty file path" + # Reject absolute paths — restore targets must be relative to the workdir + if os.path.isabs(file_path): + return f"File path must be relative, got absolute path: {file_path!r}" + # Resolve and check containment within working_dir + abs_workdir = _normalize_path(working_dir) + resolved = (abs_workdir / file_path).resolve() + try: + resolved.relative_to(abs_workdir) + except ValueError: + return f"File path escapes the working directory via traversal: {file_path!r}" + return None + + +# --------------------------------------------------------------------------- +# Shadow repo helpers +# --------------------------------------------------------------------------- + +def _normalize_path(path_value: str) -> Path: + """Return a canonical absolute path for checkpoint operations.""" + return Path(path_value).expanduser().resolve() + + +def _shadow_repo_path(working_dir: str) -> Path: + """Deterministic shadow repo path: sha256(abs_path)[:16].""" + abs_path = str(_normalize_path(working_dir)) + dir_hash = hashlib.sha256(abs_path.encode()).hexdigest()[:16] + return CHECKPOINT_BASE / dir_hash + + +def _git_env(shadow_repo: Path, working_dir: str) -> dict: + """Build env dict that redirects git to the shadow repo.""" + normalized_working_dir = _normalize_path(working_dir) + env = os.environ.copy() + env["GIT_DIR"] = str(shadow_repo) + env["GIT_WORK_TREE"] = str(normalized_working_dir) + env.pop("GIT_INDEX_FILE", None) + env.pop("GIT_NAMESPACE", None) + env.pop("GIT_ALTERNATE_OBJECT_DIRECTORIES", None) + return env + + +def _run_git( + args: List[str], + shadow_repo: Path, + working_dir: str, + timeout: int = _GIT_TIMEOUT, + allowed_returncodes: Optional[Set[int]] = None, +) -> tuple: + """Run a git command against the shadow repo. Returns (ok, stdout, stderr). + + ``allowed_returncodes`` suppresses error logging for known/expected non-zero + exits while preserving the normal ``ok = (returncode == 0)`` contract. + Example: ``git diff --cached --quiet`` returns 1 when changes exist. + """ + normalized_working_dir = _normalize_path(working_dir) + if not normalized_working_dir.exists(): + msg = f"working directory not found: {normalized_working_dir}" + logger.error("Git command skipped: %s (%s)", " ".join(["git"] + list(args)), msg) + return False, "", msg + if not normalized_working_dir.is_dir(): + msg = f"working directory is not a directory: {normalized_working_dir}" + logger.error("Git command skipped: %s (%s)", " ".join(["git"] + list(args)), msg) + return False, "", msg + + env = _git_env(shadow_repo, str(normalized_working_dir)) + cmd = ["git"] + list(args) + allowed_returncodes = allowed_returncodes or set() + try: + result = subprocess.run( + cmd, + capture_output=True, + text=True, + timeout=timeout, + env=env, + cwd=str(normalized_working_dir), + ) + ok = result.returncode == 0 + stdout = result.stdout.strip() + stderr = result.stderr.strip() + if not ok and result.returncode not in allowed_returncodes: + logger.error( + "Git command failed: %s (rc=%d) stderr=%s", + " ".join(cmd), result.returncode, stderr, + ) + return ok, stdout, stderr + except subprocess.TimeoutExpired: + msg = f"git timed out after {timeout}s: {' '.join(cmd)}" + logger.error(msg, exc_info=True) + return False, "", msg + except FileNotFoundError as exc: + missing_target = getattr(exc, "filename", None) + if missing_target == "git": + logger.error("Git executable not found: %s", " ".join(cmd), exc_info=True) + return False, "", "git not found" + msg = f"working directory not found: {normalized_working_dir}" + logger.error("Git command failed before execution: %s (%s)", " ".join(cmd), msg, exc_info=True) + return False, "", msg + except Exception as exc: + logger.error("Unexpected git error running %s: %s", " ".join(cmd), exc, exc_info=True) + return False, "", str(exc) + + +def _init_shadow_repo(shadow_repo: Path, working_dir: str) -> Optional[str]: + """Initialise shadow repo if needed. Returns error string or None.""" + if (shadow_repo / "HEAD").exists(): + return None + + shadow_repo.mkdir(parents=True, exist_ok=True) + + ok, _, err = _run_git(["init"], shadow_repo, working_dir) + if not ok: + return f"Shadow repo init failed: {err}" + + _run_git(["config", "user.email", "hermes@local"], shadow_repo, working_dir) + _run_git(["config", "user.name", "Hermes Checkpoint"], shadow_repo, working_dir) + + info_dir = shadow_repo / "info" + info_dir.mkdir(exist_ok=True) + (info_dir / "exclude").write_text( + "\n".join(DEFAULT_EXCLUDES) + "\n", encoding="utf-8" + ) + + (shadow_repo / "HERMES_WORKDIR").write_text( + str(_normalize_path(working_dir)) + "\n", encoding="utf-8" + ) + + logger.debug("Initialised checkpoint repo at %s for %s", shadow_repo, working_dir) + return None + + +def _dir_file_count(path: str) -> int: + """Quick file count estimate (stops early if over _MAX_FILES).""" + count = 0 + try: + for _ in Path(path).rglob("*"): + count += 1 + if count > _MAX_FILES: + return count + except (PermissionError, OSError): + pass + return count + + +# --------------------------------------------------------------------------- +# CheckpointManager +# --------------------------------------------------------------------------- + +class CheckpointManager: + """Manages automatic filesystem checkpoints. + + Designed to be owned by AIAgent. Call ``new_turn()`` at the start of + each conversation turn and ``ensure_checkpoint(dir, reason)`` before + any file-mutating tool call. The manager deduplicates so at most one + snapshot is taken per directory per turn. + + Parameters + ---------- + enabled : bool + Master switch (from config / CLI flag). + max_snapshots : int + Keep at most this many checkpoints per directory. + """ + + def __init__(self, enabled: bool = False, max_snapshots: int = 50): + self.enabled = enabled + self.max_snapshots = max_snapshots + self._checkpointed_dirs: Set[str] = set() + self._git_available: Optional[bool] = None # lazy probe + + # ------------------------------------------------------------------ + # Turn lifecycle + # ------------------------------------------------------------------ + + def new_turn(self) -> None: + """Reset per-turn dedup. Call at the start of each agent iteration.""" + self._checkpointed_dirs.clear() + + # ------------------------------------------------------------------ + # Public API + # ------------------------------------------------------------------ + + def ensure_checkpoint(self, working_dir: str, reason: str = "auto") -> bool: + """Take a checkpoint if enabled and not already done this turn. + + Returns True if a checkpoint was taken, False otherwise. + Never raises — all errors are silently logged. + """ + if not self.enabled: + return False + + # Lazy git probe + if self._git_available is None: + self._git_available = shutil.which("git") is not None + if not self._git_available: + logger.debug("Checkpoints disabled: git not found") + if not self._git_available: + return False + + abs_dir = str(_normalize_path(working_dir)) + + # Skip root, home, and other overly broad directories + if abs_dir in ("/", str(Path.home())): + logger.debug("Checkpoint skipped: directory too broad (%s)", abs_dir) + return False + + # Already checkpointed this turn? + if abs_dir in self._checkpointed_dirs: + return False + + self._checkpointed_dirs.add(abs_dir) + + try: + return self._take(abs_dir, reason) + except Exception as e: + logger.debug("Checkpoint failed (non-fatal): %s", e) + return False + + def list_checkpoints(self, working_dir: str) -> List[Dict]: + """List available checkpoints for a directory. + + Returns a list of dicts with keys: hash, short_hash, timestamp, reason, + files_changed, insertions, deletions. Most recent first. + """ + abs_dir = str(_normalize_path(working_dir)) + shadow = _shadow_repo_path(abs_dir) + + if not (shadow / "HEAD").exists(): + return [] + + ok, stdout, _ = _run_git( + ["log", "--format=%H|%h|%aI|%s", "-n", str(self.max_snapshots)], + shadow, abs_dir, + ) + + if not ok or not stdout: + return [] + + results = [] + for line in stdout.splitlines(): + parts = line.split("|", 3) + if len(parts) == 4: + entry = { + "hash": parts[0], + "short_hash": parts[1], + "timestamp": parts[2], + "reason": parts[3], + "files_changed": 0, + "insertions": 0, + "deletions": 0, + } + # Get diffstat for this commit + stat_ok, stat_out, _ = _run_git( + ["diff", "--shortstat", f"{parts[0]}~1", parts[0]], + shadow, abs_dir, + allowed_returncodes={128, 129}, # first commit has no parent + ) + if stat_ok and stat_out: + self._parse_shortstat(stat_out, entry) + results.append(entry) + return results + + @staticmethod + def _parse_shortstat(stat_line: str, entry: Dict) -> None: + """Parse git --shortstat output into entry dict.""" + import re + m = re.search(r'(\d+) file', stat_line) + if m: + entry["files_changed"] = int(m.group(1)) + m = re.search(r'(\d+) insertion', stat_line) + if m: + entry["insertions"] = int(m.group(1)) + m = re.search(r'(\d+) deletion', stat_line) + if m: + entry["deletions"] = int(m.group(1)) + + def diff(self, working_dir: str, commit_hash: str) -> Dict: + """Show diff between a checkpoint and the current working tree. + + Returns dict with success, diff text, and stat summary. + """ + # Validate commit_hash to prevent git argument injection + hash_err = _validate_commit_hash(commit_hash) + if hash_err: + return {"success": False, "error": hash_err} + + abs_dir = str(_normalize_path(working_dir)) + shadow = _shadow_repo_path(abs_dir) + + if not (shadow / "HEAD").exists(): + return {"success": False, "error": "No checkpoints exist for this directory"} + + # Verify the commit exists + ok, _, err = _run_git( + ["cat-file", "-t", commit_hash], shadow, abs_dir, + ) + if not ok: + return {"success": False, "error": f"Checkpoint '{commit_hash}' not found"} + + # Stage current state to compare against checkpoint + _run_git(["add", "-A"], shadow, abs_dir, timeout=_GIT_TIMEOUT * 2) + + # Get stat summary: checkpoint vs current working tree + ok_stat, stat_out, _ = _run_git( + ["diff", "--stat", commit_hash, "--cached"], + shadow, abs_dir, + ) + + # Get actual diff (limited to avoid terminal flood) + ok_diff, diff_out, _ = _run_git( + ["diff", commit_hash, "--cached", "--no-color"], + shadow, abs_dir, + ) + + # Unstage to avoid polluting the shadow repo index + _run_git(["reset", "HEAD", "--quiet"], shadow, abs_dir) + + if not ok_stat and not ok_diff: + return {"success": False, "error": "Could not generate diff"} + + return { + "success": True, + "stat": stat_out if ok_stat else "", + "diff": diff_out if ok_diff else "", + } + + def restore(self, working_dir: str, commit_hash: str, file_path: str = None) -> Dict: + """Restore files to a checkpoint state. + + Uses ``git checkout -- .`` (or a specific file) which restores + tracked files without moving HEAD — safe and reversible. + + Parameters + ---------- + file_path : str, optional + If provided, restore only this file instead of the entire directory. + + Returns dict with success/error info. + """ + # Validate commit_hash to prevent git argument injection + hash_err = _validate_commit_hash(commit_hash) + if hash_err: + return {"success": False, "error": hash_err} + + abs_dir = str(_normalize_path(working_dir)) + + # Validate file_path to prevent path traversal outside the working dir + if file_path: + path_err = _validate_file_path(file_path, abs_dir) + if path_err: + return {"success": False, "error": path_err} + + shadow = _shadow_repo_path(abs_dir) + + if not (shadow / "HEAD").exists(): + return {"success": False, "error": "No checkpoints exist for this directory"} + + # Verify the commit exists + ok, _, err = _run_git( + ["cat-file", "-t", commit_hash], shadow, abs_dir, + ) + if not ok: + return {"success": False, "error": f"Checkpoint '{commit_hash}' not found", "debug": err or None} + + # Take a checkpoint of current state before restoring (so you can undo the undo) + self._take(abs_dir, f"pre-rollback snapshot (restoring to {commit_hash[:8]})") + + # Restore — full directory or single file + restore_target = file_path if file_path else "." + ok, stdout, err = _run_git( + ["checkout", commit_hash, "--", restore_target], + shadow, abs_dir, timeout=_GIT_TIMEOUT * 2, + ) + + if not ok: + return {"success": False, "error": f"Restore failed: {err}", "debug": err or None} + + # Get info about what was restored + ok2, reason_out, _ = _run_git( + ["log", "--format=%s", "-1", commit_hash], shadow, abs_dir, + ) + reason = reason_out if ok2 else "unknown" + + result = { + "success": True, + "restored_to": commit_hash[:8], + "reason": reason, + "directory": abs_dir, + } + if file_path: + result["file"] = file_path + return result + + def get_working_dir_for_path(self, file_path: str) -> str: + """Resolve a file path to its working directory for checkpointing. + + Walks up from the file's parent to find a reasonable project root + (directory containing .git, pyproject.toml, package.json, etc.). + Falls back to the file's parent directory. + """ + path = _normalize_path(file_path) + if path.is_dir(): + candidate = path + else: + candidate = path.parent + + # Walk up looking for project root markers + markers = {".git", "pyproject.toml", "package.json", "Cargo.toml", + "go.mod", "Makefile", "pom.xml", ".hg", "Gemfile"} + check = candidate + while check != check.parent: + if any((check / m).exists() for m in markers): + return str(check) + check = check.parent + + # No project root found — use the file's parent + return str(candidate) + + # ------------------------------------------------------------------ + # Internal + # ------------------------------------------------------------------ + + def _take(self, working_dir: str, reason: str) -> bool: + """Take a snapshot. Returns True on success.""" + shadow = _shadow_repo_path(working_dir) + + # Init if needed + err = _init_shadow_repo(shadow, working_dir) + if err: + logger.debug("Checkpoint init failed: %s", err) + return False + + # Quick size guard — don't try to snapshot enormous directories + if _dir_file_count(working_dir) > _MAX_FILES: + logger.debug("Checkpoint skipped: >%d files in %s", _MAX_FILES, working_dir) + return False + + # Stage everything + ok, _, err = _run_git( + ["add", "-A"], shadow, working_dir, timeout=_GIT_TIMEOUT * 2, + ) + if not ok: + logger.debug("Checkpoint git-add failed: %s", err) + return False + + # Check if there's anything to commit + ok_diff, diff_out, _ = _run_git( + ["diff", "--cached", "--quiet"], + shadow, + working_dir, + allowed_returncodes={1}, + ) + if ok_diff: + # No changes to commit + logger.debug("Checkpoint skipped: no changes in %s", working_dir) + return False + + # Commit + ok, _, err = _run_git( + ["commit", "-m", reason, "--allow-empty-message"], + shadow, working_dir, timeout=_GIT_TIMEOUT * 2, + ) + if not ok: + logger.debug("Checkpoint commit failed: %s", err) + return False + + logger.debug("Checkpoint taken in %s: %s", working_dir, reason) + + # Prune old snapshots + self._prune(shadow, working_dir) + + return True + + def _prune(self, shadow_repo: Path, working_dir: str) -> None: + """Keep only the last max_snapshots commits via orphan reset.""" + ok, stdout, _ = _run_git( + ["rev-list", "--count", "HEAD"], shadow_repo, working_dir, + ) + if not ok: + return + + try: + count = int(stdout) + except ValueError: + return + + if count <= self.max_snapshots: + return + + # For simplicity, we don't actually prune — git's pack mechanism + # handles this efficiently, and the objects are small. The log + # listing is already limited by max_snapshots. + # Full pruning would require rebase --onto or filter-branch which + # is fragile for a background feature. We just limit the log view. + logger.debug("Checkpoint repo has %d commits (limit %d)", count, self.max_snapshots) + + +def format_checkpoint_list(checkpoints: List[Dict], directory: str) -> str: + """Format checkpoint list for display to user.""" + if not checkpoints: + return f"No checkpoints found for {directory}" + + lines = [f"📸 Checkpoints for {directory}:\n"] + for i, cp in enumerate(checkpoints, 1): + # Parse ISO timestamp to something readable + ts = cp["timestamp"] + if "T" in ts: + ts = ts.split("T")[1].split("+")[0].split("-")[0][:5] # HH:MM + date = cp["timestamp"].split("T")[0] + ts = f"{date} {ts}" + + # Build change summary + files = cp.get("files_changed", 0) + ins = cp.get("insertions", 0) + dele = cp.get("deletions", 0) + if files: + stat = f" ({files} file{'s' if files != 1 else ''}, +{ins}/-{dele})" + else: + stat = "" + + lines.append(f" {i}. {cp['short_hash']} {ts} {cp['reason']}{stat}") + + lines.append("\n /rollback restore to checkpoint N") + lines.append(" /rollback diff preview changes since checkpoint N") + lines.append(" /rollback restore a single file from checkpoint N") + return "\n".join(lines) diff --git a/mindcli/_vendor/tools/clarify_tool.py b/mindcli/_vendor/tools/clarify_tool.py new file mode 100644 index 0000000..c447875 --- /dev/null +++ b/mindcli/_vendor/tools/clarify_tool.py @@ -0,0 +1,141 @@ +#!/usr/bin/env python3 +""" +Clarify Tool Module - Interactive Clarifying Questions + +Allows the agent to present structured multiple-choice questions or open-ended +prompts to the user. In CLI mode, choices are navigable with arrow keys. On +messaging platforms, choices are rendered as a numbered list. + +The actual user-interaction logic lives in the platform layer (cli.py for CLI, +gateway/run.py for messaging). This module defines the schema, validation, and +a thin dispatcher that delegates to a platform-provided callback. +""" + +import json +from typing import List, Optional, Callable + + +# Maximum number of predefined choices the agent can offer. +# A 5th "Other (type your answer)" option is always appended by the UI. +MAX_CHOICES = 4 + + +def clarify_tool( + question: str, + choices: Optional[List[str]] = None, + callback: Optional[Callable] = None, +) -> str: + """ + Ask the user a question, optionally with multiple-choice options. + + Args: + question: The question text to present. + choices: Up to 4 predefined answer choices. When omitted the + question is purely open-ended. + callback: Platform-provided function that handles the actual UI + interaction. Signature: callback(question, choices) -> str. + Injected by the agent runner (cli.py / gateway). + + Returns: + JSON string with the user's response. + """ + if not question or not question.strip(): + return tool_error("Question text is required.") + + question = question.strip() + + # Validate and trim choices + if choices is not None: + if not isinstance(choices, list): + return tool_error("choices must be a list of strings.") + choices = [str(c).strip() for c in choices if str(c).strip()] + if len(choices) > MAX_CHOICES: + choices = choices[:MAX_CHOICES] + if not choices: + choices = None # empty list → open-ended + + if callback is None: + return json.dumps( + {"error": "Clarify tool is not available in this execution context."}, + ensure_ascii=False, + ) + + try: + user_response = callback(question, choices) + except Exception as exc: + return json.dumps( + {"error": f"Failed to get user input: {exc}"}, + ensure_ascii=False, + ) + + return json.dumps({ + "question": question, + "choices_offered": choices, + "user_response": str(user_response).strip(), + }, ensure_ascii=False) + + +def check_clarify_requirements() -> bool: + """Clarify tool has no external requirements -- always available.""" + return True + + +# ============================================================================= +# OpenAI Function-Calling Schema +# ============================================================================= + +CLARIFY_SCHEMA = { + "name": "clarify", + "description": ( + "Ask the user a question when you need clarification, feedback, or a " + "decision before proceeding. Supports two modes:\n\n" + "1. **Multiple choice** — provide up to 4 choices. The user picks one " + "or types their own answer via a 5th 'Other' option.\n" + "2. **Open-ended** — omit choices entirely. The user types a free-form " + "response.\n\n" + "Use this tool when:\n" + "- The task is ambiguous and you need the user to choose an approach\n" + "- You want post-task feedback ('How did that work out?')\n" + "- You want to offer to save a skill or update memory\n" + "- A decision has meaningful trade-offs the user should weigh in on\n\n" + "Do NOT use this tool for simple yes/no confirmation of dangerous " + "commands (the terminal tool handles that). Prefer making a reasonable " + "default choice yourself when the decision is low-stakes." + ), + "parameters": { + "type": "object", + "properties": { + "question": { + "type": "string", + "description": "The question to present to the user.", + }, + "choices": { + "type": "array", + "items": {"type": "string"}, + "maxItems": MAX_CHOICES, + "description": ( + "Up to 4 answer choices. Omit this parameter entirely to " + "ask an open-ended question. When provided, the UI " + "automatically appends an 'Other (type your answer)' option." + ), + }, + }, + "required": ["question"], + }, +} + + +# --- Registry --- +from tools.registry import registry, tool_error + +registry.register( + name="clarify", + toolset="clarify", + schema=CLARIFY_SCHEMA, + handler=lambda args, **kw: clarify_tool( + question=args.get("question", ""), + choices=args.get("choices"), + callback=kw.get("callback")), + check_fn=check_clarify_requirements, + emoji="❓", +) diff --git a/mindcli/_vendor/tools/code_execution_tool.py b/mindcli/_vendor/tools/code_execution_tool.py new file mode 100644 index 0000000..bed4f20 --- /dev/null +++ b/mindcli/_vendor/tools/code_execution_tool.py @@ -0,0 +1,1377 @@ +#!/usr/bin/env python3 +""" +Code Execution Tool -- Programmatic Tool Calling (PTC) + +Lets the LLM write a Python script that calls Hermes tools via RPC, +collapsing multi-step tool chains into a single inference turn. + +Architecture (two transports): + + **Local backend (UDS):** + 1. Parent generates a `hermes_tools.py` stub module with UDS RPC functions + 2. Parent opens a Unix domain socket and starts an RPC listener thread + 3. Parent spawns a child process that runs the LLM's script + 4. Tool calls travel over the UDS back to the parent for dispatch + + **Remote backends (file-based RPC):** + 1. Parent generates `hermes_tools.py` with file-based RPC stubs + 2. Parent ships both files to the remote environment + 3. Script runs inside the terminal backend (Docker/SSH/Modal/Daytona/etc.) + 4. Tool calls are written as request files; a polling thread on the parent + reads them via env.execute(), dispatches, and writes response files + 5. The script polls for response files and continues + +In both cases, only the script's stdout is returned to the LLM; intermediate +tool results never enter the context window. + +Platform: Linux / macOS only (Unix domain sockets for local). Disabled on Windows. +Remote execution additionally requires Python 3 in the terminal backend. +""" + +import base64 +import json +import logging +import os +import platform +import shlex +import signal +import socket +import subprocess +import sys +import tempfile +import threading +import time +import uuid + +_IS_WINDOWS = platform.system() == "Windows" +from typing import Any, Dict, List, Optional + +# Availability gate: UDS requires a POSIX OS +logger = logging.getLogger(__name__) + +SANDBOX_AVAILABLE = sys.platform != "win32" + +# The 7 tools allowed inside the sandbox. The intersection of this list +# and the session's enabled tools determines which stubs are generated. +SANDBOX_ALLOWED_TOOLS = frozenset([ + "web_search", + "web_extract", + "read_file", + "write_file", + "search_files", + "patch", + "terminal", +]) + +# Resource limit defaults (overridable via config.yaml → code_execution.*) +DEFAULT_TIMEOUT = 300 # 5 minutes +DEFAULT_MAX_TOOL_CALLS = 50 +MAX_STDOUT_BYTES = 50_000 # 50 KB +MAX_STDERR_BYTES = 10_000 # 10 KB + + +def check_sandbox_requirements() -> bool: + """Code execution sandbox requires a POSIX OS for Unix domain sockets.""" + return SANDBOX_AVAILABLE + + +# --------------------------------------------------------------------------- +# hermes_tools.py code generator +# --------------------------------------------------------------------------- + +# Per-tool stub templates: (function_name, signature, docstring, args_dict_expr) +# The args_dict_expr builds the JSON payload sent over the RPC socket. +_TOOL_STUBS = { + "web_search": ( + "web_search", + "query: str, limit: int = 5", + '"""Search the web. Returns dict with data.web list of {url, title, description}."""', + '{"query": query, "limit": limit}', + ), + "web_extract": ( + "web_extract", + "urls: list", + '"""Extract content from URLs. Returns dict with results list of {url, title, content, error}."""', + '{"urls": urls}', + ), + "read_file": ( + "read_file", + "path: str, offset: int = 1, limit: int = 500", + '"""Read a file (1-indexed lines). Returns dict with "content" and "total_lines"."""', + '{"path": path, "offset": offset, "limit": limit}', + ), + "write_file": ( + "write_file", + "path: str, content: str", + '"""Write content to a file (always overwrites). Returns dict with status."""', + '{"path": path, "content": content}', + ), + "search_files": ( + "search_files", + 'pattern: str, target: str = "content", path: str = ".", file_glob: str = None, limit: int = 50, offset: int = 0, output_mode: str = "content", context: int = 0', + '"""Search file contents (target="content") or find files by name (target="files"). Returns dict with "matches"."""', + '{"pattern": pattern, "target": target, "path": path, "file_glob": file_glob, "limit": limit, "offset": offset, "output_mode": output_mode, "context": context}', + ), + "patch": ( + "patch", + 'path: str = None, old_string: str = None, new_string: str = None, replace_all: bool = False, mode: str = "replace", patch: str = None', + '"""Targeted find-and-replace (mode="replace") or V4A multi-file patches (mode="patch"). Returns dict with status."""', + '{"path": path, "old_string": old_string, "new_string": new_string, "replace_all": replace_all, "mode": mode, "patch": patch}', + ), + "terminal": ( + "terminal", + "command: str, timeout: int = None, workdir: str = None", + '"""Run a shell command (foreground only). Returns dict with "output" and "exit_code"."""', + '{"command": command, "timeout": timeout, "workdir": workdir}', + ), +} + + +def generate_hermes_tools_module(enabled_tools: List[str], + transport: str = "uds") -> str: + """ + Build the source code for the hermes_tools.py stub module. + + Only tools in both SANDBOX_ALLOWED_TOOLS and enabled_tools get stubs. + + Args: + enabled_tools: Tool names enabled in the current session. + transport: ``"uds"`` for Unix domain socket (local backend) or + ``"file"`` for file-based RPC (remote backends). + """ + tools_to_generate = sorted(SANDBOX_ALLOWED_TOOLS & set(enabled_tools)) + + stub_functions = [] + export_names = [] + for tool_name in tools_to_generate: + if tool_name not in _TOOL_STUBS: + continue + func_name, sig, doc, args_expr = _TOOL_STUBS[tool_name] + stub_functions.append( + f"def {func_name}({sig}):\n" + f" {doc}\n" + f" return _call({func_name!r}, {args_expr})\n" + ) + export_names.append(func_name) + + if transport == "file": + header = _FILE_TRANSPORT_HEADER + else: + header = _UDS_TRANSPORT_HEADER + + return header + "\n".join(stub_functions) + + +# ---- Shared helpers section (embedded in both transport headers) ---------- + +_COMMON_HELPERS = '''\ + +# --------------------------------------------------------------------------- +# Convenience helpers (avoid common scripting pitfalls) +# --------------------------------------------------------------------------- + +def json_parse(text: str): + """Parse JSON tolerant of control characters (strict=False). + Use this instead of json.loads() when parsing output from terminal() + or web_extract() that may contain raw tabs/newlines in strings.""" + return json.loads(text, strict=False) + + +def shell_quote(s: str) -> str: + """Shell-escape a string for safe interpolation into commands. + Use this when inserting dynamic content into terminal() commands: + terminal(f"echo {shell_quote(user_input)}") + """ + return shlex.quote(s) + + +def retry(fn, max_attempts=3, delay=2): + """Retry a function up to max_attempts times with exponential backoff. + Use for transient failures (network errors, API rate limits): + result = retry(lambda: terminal("gh issue list ...")) + """ + last_err = None + for attempt in range(max_attempts): + try: + return fn() + except Exception as e: + last_err = e + if attempt < max_attempts - 1: + time.sleep(delay * (2 ** attempt)) + raise last_err + +''' + +# ---- UDS transport (local backend) --------------------------------------- + +_UDS_TRANSPORT_HEADER = '''\ +"""Auto-generated Hermes tools RPC stubs.""" +import json, os, socket, shlex, time + +_sock = None +''' + _COMMON_HELPERS + '''\ + +def _connect(): + global _sock + if _sock is None: + _sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + _sock.connect(os.environ["HERMES_RPC_SOCKET"]) + _sock.settimeout(300) + return _sock + +def _call(tool_name, args): + """Send a tool call to the parent process and return the parsed result.""" + conn = _connect() + request = json.dumps({"tool": tool_name, "args": args}) + "\\n" + conn.sendall(request.encode()) + buf = b"" + while True: + chunk = conn.recv(65536) + if not chunk: + raise RuntimeError("Agent process disconnected") + buf += chunk + if buf.endswith(b"\\n"): + break + raw = buf.decode().strip() + result = json.loads(raw) + if isinstance(result, str): + try: + return json.loads(result) + except (json.JSONDecodeError, TypeError): + return result + return result + +''' + +# ---- File-based transport (remote backends) ------------------------------- + +_FILE_TRANSPORT_HEADER = '''\ +"""Auto-generated Hermes tools RPC stubs (file-based transport).""" +import json, os, shlex, tempfile, time + +_RPC_DIR = os.environ.get("HERMES_RPC_DIR") or os.path.join(tempfile.gettempdir(), "hermes_rpc") +_seq = 0 +''' + _COMMON_HELPERS + '''\ + +def _call(tool_name, args): + """Send a tool call request via file-based RPC and wait for response.""" + global _seq + _seq += 1 + seq_str = f"{_seq:06d}" + req_file = os.path.join(_RPC_DIR, f"req_{seq_str}") + res_file = os.path.join(_RPC_DIR, f"res_{seq_str}") + + # Write request atomically (write to .tmp, then rename) + tmp = req_file + ".tmp" + with open(tmp, "w") as f: + json.dump({"tool": tool_name, "args": args, "seq": _seq}, f) + os.rename(tmp, req_file) + + # Wait for response with adaptive polling + deadline = time.monotonic() + 300 # 5-minute timeout per tool call + poll_interval = 0.05 # Start at 50ms + while not os.path.exists(res_file): + if time.monotonic() > deadline: + raise RuntimeError(f"RPC timeout: no response for {tool_name} after 300s") + time.sleep(poll_interval) + poll_interval = min(poll_interval * 1.2, 0.25) # Back off to 250ms + + with open(res_file) as f: + raw = f.read() + + # Clean up response file + try: + os.unlink(res_file) + except OSError: + pass + + result = json.loads(raw) + if isinstance(result, str): + try: + return json.loads(result) + except (json.JSONDecodeError, TypeError): + return result + return result + +''' + + +# --------------------------------------------------------------------------- +# RPC server (runs in a thread inside the parent process) +# --------------------------------------------------------------------------- + +# Terminal parameters that must not be used from ephemeral sandbox scripts +_TERMINAL_BLOCKED_PARAMS = {"background", "pty", "notify_on_complete", "watch_patterns"} + + +def _rpc_server_loop( + server_sock: socket.socket, + task_id: str, + tool_call_log: list, + tool_call_counter: list, # mutable [int] so the thread can increment + max_tool_calls: int, + allowed_tools: frozenset, +): + """ + Accept one client connection and dispatch tool-call requests until + the client disconnects or the call limit is reached. + """ + from model_tools import handle_function_call + + conn = None + try: + server_sock.settimeout(5) + conn, _ = server_sock.accept() + conn.settimeout(300) + + buf = b"" + while True: + try: + chunk = conn.recv(65536) + except socket.timeout: + break + if not chunk: + break + buf += chunk + + # Process all complete newline-delimited messages in the buffer + while b"\n" in buf: + line, buf = buf.split(b"\n", 1) + line = line.strip() + if not line: + continue + + call_start = time.monotonic() + try: + request = json.loads(line.decode()) + except (json.JSONDecodeError, UnicodeDecodeError) as exc: + resp = tool_error(f"Invalid RPC request: {exc}") + conn.sendall((resp + "\n").encode()) + continue + + tool_name = request.get("tool", "") + tool_args = request.get("args", {}) + + # Enforce the allow-list + if tool_name not in allowed_tools: + available = ", ".join(sorted(allowed_tools)) + resp = json.dumps({ + "error": ( + f"Tool '{tool_name}' is not available in execute_code. " + f"Available: {available}" + ) + }) + conn.sendall((resp + "\n").encode()) + continue + + # Enforce tool call limit + if tool_call_counter[0] >= max_tool_calls: + resp = json.dumps({ + "error": ( + f"Tool call limit reached ({max_tool_calls}). " + "No more tool calls allowed in this execution." + ) + }) + conn.sendall((resp + "\n").encode()) + continue + + # Strip forbidden terminal parameters + if tool_name == "terminal" and isinstance(tool_args, dict): + for param in _TERMINAL_BLOCKED_PARAMS: + tool_args.pop(param, None) + + # Dispatch through the standard tool handler. + # Suppress stdout/stderr from internal tool handlers so + # their status prints don't leak into the CLI spinner. + try: + _real_stdout, _real_stderr = sys.stdout, sys.stderr + devnull = open(os.devnull, "w") + try: + sys.stdout = devnull + sys.stderr = devnull + result = handle_function_call( + tool_name, tool_args, task_id=task_id + ) + finally: + sys.stdout, sys.stderr = _real_stdout, _real_stderr + devnull.close() + except Exception as exc: + logger.error("Tool call failed in sandbox: %s", exc, exc_info=True) + result = tool_error(str(exc)) + + tool_call_counter[0] += 1 + call_duration = time.monotonic() - call_start + + # Log for observability + args_preview = str(tool_args)[:80] + tool_call_log.append({ + "tool": tool_name, + "args_preview": args_preview, + "duration": round(call_duration, 2), + }) + + conn.sendall((result + "\n").encode()) + + except socket.timeout: + logger.debug("RPC listener socket timeout") + except OSError as e: + logger.debug("RPC listener socket error: %s", e, exc_info=True) + finally: + if conn: + try: + conn.close() + except OSError as e: + logger.debug("RPC conn close error: %s", e) + + +# --------------------------------------------------------------------------- +# Remote execution support (file-based RPC via terminal backend) +# --------------------------------------------------------------------------- + +def _get_or_create_env(task_id: str): + """Get or create the terminal environment for *task_id*. + + Reuses the same environment (container/sandbox/SSH session) that the + terminal and file tools use, creating one if it doesn't exist yet. + Returns ``(env, env_type)`` tuple. + """ + from tools.terminal_tool import ( + _active_environments, _env_lock, _create_environment, + _get_env_config, _last_activity, _start_cleanup_thread, + _creation_locks, _creation_locks_lock, _task_env_overrides, + ) + + effective_task_id = task_id or "default" + + # Fast path: environment already exists + with _env_lock: + if effective_task_id in _active_environments: + _last_activity[effective_task_id] = time.time() + return _active_environments[effective_task_id], _get_env_config()["env_type"] + + # Slow path: create environment (same pattern as file_tools._get_file_ops) + with _creation_locks_lock: + if effective_task_id not in _creation_locks: + _creation_locks[effective_task_id] = threading.Lock() + task_lock = _creation_locks[effective_task_id] + + with task_lock: + with _env_lock: + if effective_task_id in _active_environments: + _last_activity[effective_task_id] = time.time() + return _active_environments[effective_task_id], _get_env_config()["env_type"] + + config = _get_env_config() + env_type = config["env_type"] + overrides = _task_env_overrides.get(effective_task_id, {}) + + if env_type == "docker": + image = overrides.get("docker_image") or config["docker_image"] + elif env_type == "singularity": + image = overrides.get("singularity_image") or config["singularity_image"] + elif env_type == "modal": + image = overrides.get("modal_image") or config["modal_image"] + elif env_type == "daytona": + image = overrides.get("daytona_image") or config["daytona_image"] + else: + image = "" + + cwd = overrides.get("cwd") or config["cwd"] + + container_config = None + if env_type in ("docker", "singularity", "modal", "daytona"): + container_config = { + "container_cpu": config.get("container_cpu", 1), + "container_memory": config.get("container_memory", 5120), + "container_disk": config.get("container_disk", 51200), + "container_persistent": config.get("container_persistent", True), + "docker_volumes": config.get("docker_volumes", []), + } + + ssh_config = None + if env_type == "ssh": + ssh_config = { + "host": config.get("ssh_host", ""), + "user": config.get("ssh_user", ""), + "port": config.get("ssh_port", 22), + "key": config.get("ssh_key", ""), + "persistent": config.get("ssh_persistent", False), + } + + local_config = None + if env_type == "local": + local_config = { + "persistent": config.get("local_persistent", False), + } + + logger.info("Creating new %s environment for execute_code task %s...", + env_type, effective_task_id[:8]) + env = _create_environment( + env_type=env_type, + image=image, + cwd=cwd, + timeout=config["timeout"], + ssh_config=ssh_config, + container_config=container_config, + local_config=local_config, + task_id=effective_task_id, + host_cwd=config.get("host_cwd"), + ) + + with _env_lock: + _active_environments[effective_task_id] = env + _last_activity[effective_task_id] = time.time() + + _start_cleanup_thread() + logger.info("%s environment ready for execute_code task %s", + env_type, effective_task_id[:8]) + return env, env_type + + +def _ship_file_to_remote(env, remote_path: str, content: str) -> None: + """Write *content* to *remote_path* on the remote environment. + + Uses ``echo … | base64 -d`` rather than stdin piping because some + backends (Modal) don't reliably deliver stdin_data to chained + commands. Base64 output is shell-safe ([A-Za-z0-9+/=]) so single + quotes are fine. + """ + encoded = base64.b64encode(content.encode("utf-8")).decode("ascii") + quoted_remote_path = shlex.quote(remote_path) + env.execute( + f"echo '{encoded}' | base64 -d > {quoted_remote_path}", + cwd="/", + timeout=30, + ) + + +def _env_temp_dir(env: Any) -> str: + """Return a writable temp dir for env-backed execute_code sandboxes.""" + get_temp_dir = getattr(env, "get_temp_dir", None) + if callable(get_temp_dir): + try: + temp_dir = get_temp_dir() + if isinstance(temp_dir, str) and temp_dir.startswith("/"): + return temp_dir.rstrip("/") or "/" + except Exception as exc: + logger.debug("Could not resolve execute_code env temp dir: %s", exc) + candidate = tempfile.gettempdir() + if isinstance(candidate, str) and candidate.startswith("/"): + return candidate.rstrip("/") or "/" + return "/tmp" + + +def _rpc_poll_loop( + env, + rpc_dir: str, + task_id: str, + tool_call_log: list, + tool_call_counter: list, + max_tool_calls: int, + allowed_tools: frozenset, + stop_event: threading.Event, +): + """Poll the remote filesystem for tool call requests and dispatch them. + + Runs in a background thread. Each ``env.execute()`` spawns an + independent process, so these calls run safely concurrent with the + script-execution thread. + """ + from model_tools import handle_function_call + + poll_interval = 0.1 # 100 ms + + quoted_rpc_dir = shlex.quote(rpc_dir) + while not stop_event.is_set(): + try: + # List pending request files (skip .tmp partials) + ls_result = env.execute( + f"ls -1 {quoted_rpc_dir}/req_* 2>/dev/null || true", + cwd="/", + timeout=10, + ) + output = ls_result.get("output", "").strip() + if not output: + stop_event.wait(poll_interval) + continue + + req_files = sorted([ + f.strip() for f in output.split("\n") + if f.strip() + and not f.strip().endswith(".tmp") + and "/req_" in f.strip() + ]) + + for req_file in req_files: + if stop_event.is_set(): + break + + call_start = time.monotonic() + + quoted_req_file = shlex.quote(req_file) + # Read request + read_result = env.execute( + f"cat {quoted_req_file}", + cwd="/", + timeout=10, + ) + try: + request = json.loads(read_result.get("output", "")) + except (json.JSONDecodeError, ValueError): + logger.debug("Malformed RPC request in %s", req_file) + # Remove bad request to avoid infinite retry + env.execute(f"rm -f {quoted_req_file}", cwd="/", timeout=5) + continue + + tool_name = request.get("tool", "") + tool_args = request.get("args", {}) + seq = request.get("seq", 0) + seq_str = f"{seq:06d}" + res_file = f"{rpc_dir}/res_{seq_str}" + quoted_res_file = shlex.quote(res_file) + + # Enforce allow-list + if tool_name not in allowed_tools: + available = ", ".join(sorted(allowed_tools)) + tool_result = json.dumps({ + "error": ( + f"Tool '{tool_name}' is not available in execute_code. " + f"Available: {available}" + ) + }) + # Enforce tool call limit + elif tool_call_counter[0] >= max_tool_calls: + tool_result = json.dumps({ + "error": ( + f"Tool call limit reached ({max_tool_calls}). " + "No more tool calls allowed in this execution." + ) + }) + else: + # Strip forbidden terminal parameters + if tool_name == "terminal" and isinstance(tool_args, dict): + for param in _TERMINAL_BLOCKED_PARAMS: + tool_args.pop(param, None) + + # Dispatch through the standard tool handler + try: + _real_stdout, _real_stderr = sys.stdout, sys.stderr + devnull = open(os.devnull, "w") + try: + sys.stdout = devnull + sys.stderr = devnull + tool_result = handle_function_call( + tool_name, tool_args, task_id=task_id + ) + finally: + sys.stdout, sys.stderr = _real_stdout, _real_stderr + devnull.close() + except Exception as exc: + logger.error("Tool call failed in remote sandbox: %s", + exc, exc_info=True) + tool_result = tool_error(str(exc)) + + tool_call_counter[0] += 1 + call_duration = time.monotonic() - call_start + tool_call_log.append({ + "tool": tool_name, + "args_preview": str(tool_args)[:80], + "duration": round(call_duration, 2), + }) + + # Write response atomically (tmp + rename). + # Use echo piping (not stdin_data) because Modal doesn't + # reliably deliver stdin to chained commands. + encoded_result = base64.b64encode( + tool_result.encode("utf-8") + ).decode("ascii") + env.execute( + f"echo '{encoded_result}' | base64 -d > {quoted_res_file}.tmp" + f" && mv {quoted_res_file}.tmp {quoted_res_file}", + cwd="/", + timeout=60, + ) + + # Remove the request file + env.execute(f"rm -f {quoted_req_file}", cwd="/", timeout=5) + + except Exception as e: + if not stop_event.is_set(): + logger.debug("RPC poll error: %s", e, exc_info=True) + + if not stop_event.is_set(): + stop_event.wait(poll_interval) + + +def _execute_remote( + code: str, + task_id: Optional[str], + enabled_tools: Optional[List[str]], +) -> str: + """Run a script on the remote terminal backend via file-based RPC. + + The script and the generated hermes_tools.py module are shipped to + the remote environment, and tool calls are proxied through a polling + thread that communicates via request/response files. + """ + + _cfg = _load_config() + timeout = _cfg.get("timeout", DEFAULT_TIMEOUT) + max_tool_calls = _cfg.get("max_tool_calls", DEFAULT_MAX_TOOL_CALLS) + + session_tools = set(enabled_tools) if enabled_tools else set() + sandbox_tools = frozenset(SANDBOX_ALLOWED_TOOLS & session_tools) + if not sandbox_tools: + sandbox_tools = SANDBOX_ALLOWED_TOOLS + + effective_task_id = task_id or "default" + env, env_type = _get_or_create_env(effective_task_id) + + sandbox_id = uuid.uuid4().hex[:12] + temp_dir = _env_temp_dir(env) + sandbox_dir = f"{temp_dir}/hermes_exec_{sandbox_id}" + quoted_sandbox_dir = shlex.quote(sandbox_dir) + quoted_rpc_dir = shlex.quote(f"{sandbox_dir}/rpc") + + tool_call_log: list = [] + tool_call_counter = [0] + exec_start = time.monotonic() + stop_event = threading.Event() + rpc_thread = None + + try: + # Verify Python is available on the remote + py_check = env.execute( + "command -v python3 >/dev/null 2>&1 && echo OK", + cwd="/", timeout=15, + ) + if "OK" not in py_check.get("output", ""): + return json.dumps({ + "status": "error", + "error": ( + f"Python 3 is not available in the {env_type} terminal " + "environment. Install Python to use execute_code with " + "remote backends." + ), + "tool_calls_made": 0, + "duration_seconds": 0, + }) + + # Create sandbox directory on remote + env.execute( + f"mkdir -p {quoted_rpc_dir}", cwd="/", timeout=10, + ) + + # Generate and ship files + tools_src = generate_hermes_tools_module( + list(sandbox_tools), transport="file", + ) + _ship_file_to_remote(env, f"{sandbox_dir}/hermes_tools.py", tools_src) + _ship_file_to_remote(env, f"{sandbox_dir}/script.py", code) + + # Start RPC polling thread + rpc_thread = threading.Thread( + target=_rpc_poll_loop, + args=( + env, f"{sandbox_dir}/rpc", effective_task_id, + tool_call_log, tool_call_counter, max_tool_calls, + sandbox_tools, stop_event, + ), + daemon=True, + ) + rpc_thread.start() + + # Build environment variable prefix for the script + env_prefix = ( + f"HERMES_RPC_DIR={shlex.quote(f'{sandbox_dir}/rpc')} " + f"PYTHONDONTWRITEBYTECODE=1" + ) + tz = os.getenv("HERMES_TIMEZONE", "").strip() + if tz: + env_prefix += f" TZ={tz}" + + # Execute the script on the remote backend + logger.info("Executing code on %s backend (task %s)...", + env_type, effective_task_id[:8]) + script_result = env.execute( + f"cd {quoted_sandbox_dir} && {env_prefix} python3 script.py", + timeout=timeout, + ) + + stdout_text = script_result.get("output", "") + exit_code = script_result.get("returncode", -1) + status = "success" + + # Check for timeout/interrupt from the backend + if exit_code == 124: + status = "timeout" + elif exit_code == 130: + status = "interrupted" + + except Exception as exc: + duration = round(time.monotonic() - exec_start, 2) + logger.error( + "execute_code remote failed after %ss with %d tool calls: %s: %s", + duration, tool_call_counter[0], type(exc).__name__, exc, + exc_info=True, + ) + return json.dumps({ + "status": "error", + "error": str(exc), + "tool_calls_made": tool_call_counter[0], + "duration_seconds": duration, + }, ensure_ascii=False) + + finally: + # Stop the polling thread + stop_event.set() + if rpc_thread is not None: + rpc_thread.join(timeout=5) + + # Clean up remote sandbox dir + try: + env.execute( + f"rm -rf {quoted_sandbox_dir}", cwd="/", timeout=15, + ) + except Exception: + logger.debug("Failed to clean up remote sandbox %s", sandbox_dir) + + duration = round(time.monotonic() - exec_start, 2) + + # --- Post-process output (same as local path) --- + + # Truncate stdout to cap + if len(stdout_text) > MAX_STDOUT_BYTES: + head_bytes = int(MAX_STDOUT_BYTES * 0.4) + tail_bytes = MAX_STDOUT_BYTES - head_bytes + head = stdout_text[:head_bytes] + tail = stdout_text[-tail_bytes:] + omitted = len(stdout_text) - len(head) - len(tail) + stdout_text = ( + head + + f"\n\n... [OUTPUT TRUNCATED - {omitted:,} chars omitted " + f"out of {len(stdout_text):,} total] ...\n\n" + + tail + ) + + # Strip ANSI escape sequences + from tools.ansi_strip import strip_ansi + stdout_text = strip_ansi(stdout_text) + + # Redact secrets + from agent.redact import redact_sensitive_text + stdout_text = redact_sensitive_text(stdout_text) + + # Build response + result: Dict[str, Any] = { + "status": status, + "output": stdout_text, + "tool_calls_made": tool_call_counter[0], + "duration_seconds": duration, + } + + if status == "timeout": + result["error"] = f"Script timed out after {timeout}s and was killed." + elif status == "interrupted": + result["output"] = ( + stdout_text + "\n[execution interrupted — user sent a new message]" + ) + elif exit_code != 0: + result["status"] = "error" + result["error"] = f"Script exited with code {exit_code}" + + return json.dumps(result, ensure_ascii=False) + + +# --------------------------------------------------------------------------- +# Main entry point +# --------------------------------------------------------------------------- + +def execute_code( + code: str, + task_id: Optional[str] = None, + enabled_tools: Optional[List[str]] = None, +) -> str: + """ + Run a Python script in a sandboxed child process with RPC access + to a subset of Hermes tools. + + Dispatches to the local (UDS) or remote (file-based RPC) path + depending on the configured terminal backend. + + Args: + code: Python source code to execute. + task_id: Session task ID for tool isolation (terminal env, etc.). + enabled_tools: Tool names enabled in the current session. The sandbox + gets the intersection with SANDBOX_ALLOWED_TOOLS. + + Returns: + JSON string with execution results. + """ + if not SANDBOX_AVAILABLE: + return json.dumps({ + "error": "execute_code is not available on Windows. Use normal tool calls instead." + }) + + if not code or not code.strip(): + return tool_error("No code provided.") + + # Dispatch: remote backends use file-based RPC, local uses UDS + from tools.terminal_tool import _get_env_config + env_type = _get_env_config()["env_type"] + if env_type != "local": + return _execute_remote(code, task_id, enabled_tools) + + # --- Local execution path (UDS) --- below this line is unchanged --- + + # Import per-thread interrupt check (cooperative cancellation) + from tools.interrupt import is_interrupted as _is_interrupted + + # Resolve config + _cfg = _load_config() + timeout = _cfg.get("timeout", DEFAULT_TIMEOUT) + max_tool_calls = _cfg.get("max_tool_calls", DEFAULT_MAX_TOOL_CALLS) + + # Determine which tools the sandbox can call + session_tools = set(enabled_tools) if enabled_tools else set() + sandbox_tools = frozenset(SANDBOX_ALLOWED_TOOLS & session_tools) + + if not sandbox_tools: + sandbox_tools = SANDBOX_ALLOWED_TOOLS + + # --- Set up temp directory with hermes_tools.py and script.py --- + tmpdir = tempfile.mkdtemp(prefix="hermes_sandbox_") + # Use /tmp on macOS to avoid the long /var/folders/... path that pushes + # Unix domain socket paths past the 104-byte macOS AF_UNIX limit. + # On Linux, tempfile.gettempdir() already returns /tmp. + _sock_tmpdir = "/tmp" if sys.platform == "darwin" else tempfile.gettempdir() + sock_path = os.path.join(_sock_tmpdir, f"hermes_rpc_{uuid.uuid4().hex}.sock") + + tool_call_log: list = [] + tool_call_counter = [0] # mutable so the RPC thread can increment + exec_start = time.monotonic() + server_sock = None + + try: + # Write the auto-generated hermes_tools module + # sandbox_tools is already the correct set (intersection with session + # tools, or SANDBOX_ALLOWED_TOOLS as fallback — see lines above). + tools_src = generate_hermes_tools_module(list(sandbox_tools)) + with open(os.path.join(tmpdir, "hermes_tools.py"), "w") as f: + f.write(tools_src) + + # Write the user's script + with open(os.path.join(tmpdir, "script.py"), "w") as f: + f.write(code) + + # --- Start UDS server --- + server_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + server_sock.bind(sock_path) + server_sock.listen(1) + + rpc_thread = threading.Thread( + target=_rpc_server_loop, + args=( + server_sock, task_id, tool_call_log, + tool_call_counter, max_tool_calls, sandbox_tools, + ), + daemon=True, + ) + rpc_thread.start() + + # --- Spawn child process --- + # Build a minimal environment for the child. We intentionally exclude + # API keys and tokens to prevent credential exfiltration from LLM- + # generated scripts. The child accesses tools via RPC, not direct API. + # Exception: env vars declared by loaded skills (via env_passthrough + # registry) or explicitly allowed by the user in config.yaml + # (terminal.env_passthrough) are passed through. + _SAFE_ENV_PREFIXES = ("PATH", "HOME", "USER", "LANG", "LC_", "TERM", + "TMPDIR", "TMP", "TEMP", "SHELL", "LOGNAME", + "XDG_", "PYTHONPATH", "VIRTUAL_ENV", "CONDA") + _SECRET_SUBSTRINGS = ("KEY", "TOKEN", "SECRET", "PASSWORD", "CREDENTIAL", + "PASSWD", "AUTH") + try: + from tools.env_passthrough import is_env_passthrough as _is_passthrough + except Exception: + _is_passthrough = lambda _: False # noqa: E731 + child_env = {} + for k, v in os.environ.items(): + # Passthrough vars (skill-declared or user-configured) always pass. + if _is_passthrough(k): + child_env[k] = v + continue + # Block vars with secret-like names. + if any(s in k.upper() for s in _SECRET_SUBSTRINGS): + continue + # Allow vars with known safe prefixes. + if any(k.startswith(p) for p in _SAFE_ENV_PREFIXES): + child_env[k] = v + child_env["HERMES_RPC_SOCKET"] = sock_path + child_env["PYTHONDONTWRITEBYTECODE"] = "1" + # Ensure the hermes-agent root is importable in the sandbox so + # repo-root modules are available to child scripts. + _hermes_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + _existing_pp = child_env.get("PYTHONPATH", "") + child_env["PYTHONPATH"] = _hermes_root + (os.pathsep + _existing_pp if _existing_pp else "") + # Inject user's configured timezone so datetime.now() in sandboxed + # code reflects the correct wall-clock time. + _tz_name = os.getenv("HERMES_TIMEZONE", "").strip() + if _tz_name: + child_env["TZ"] = _tz_name + + # Per-profile HOME isolation: redirect system tool configs into + # {HERMES_HOME}/home/ when that directory exists. + from hermes_constants import get_subprocess_home + _profile_home = get_subprocess_home() + if _profile_home: + child_env["HOME"] = _profile_home + + proc = subprocess.Popen( + [sys.executable, "script.py"], + cwd=tmpdir, + env=child_env, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + stdin=subprocess.DEVNULL, + preexec_fn=None if _IS_WINDOWS else os.setsid, + ) + + # --- Poll loop: watch for exit, timeout, and interrupt --- + deadline = time.monotonic() + timeout + stderr_chunks: list = [] + + # Background readers to avoid pipe buffer deadlocks. + # For stdout we use a head+tail strategy: keep the first HEAD_BYTES + # and a rolling window of the last TAIL_BYTES so the final print() + # output is never lost. Stderr keeps head-only (errors appear early). + _STDOUT_HEAD_BYTES = int(MAX_STDOUT_BYTES * 0.4) # 40% head + _STDOUT_TAIL_BYTES = MAX_STDOUT_BYTES - _STDOUT_HEAD_BYTES # 60% tail + + def _drain(pipe, chunks, max_bytes): + """Simple head-only drain (used for stderr).""" + total = 0 + try: + while True: + data = pipe.read(4096) + if not data: + break + if total < max_bytes: + keep = max_bytes - total + chunks.append(data[:keep]) + total += len(data) + except (ValueError, OSError) as e: + logger.debug("Error reading process output: %s", e, exc_info=True) + + stdout_total_bytes = [0] # mutable ref for total bytes seen + + def _drain_head_tail(pipe, head_chunks, tail_chunks, head_bytes, tail_bytes, total_ref): + """Drain stdout keeping both head and tail data.""" + head_collected = 0 + from collections import deque + tail_buf = deque() + tail_collected = 0 + try: + while True: + data = pipe.read(4096) + if not data: + break + total_ref[0] += len(data) + # Fill head buffer first + if head_collected < head_bytes: + keep = min(len(data), head_bytes - head_collected) + head_chunks.append(data[:keep]) + head_collected += keep + data = data[keep:] # remaining goes to tail + if not data: + continue + # Everything past head goes into rolling tail buffer + tail_buf.append(data) + tail_collected += len(data) + # Evict old tail data to stay within tail_bytes budget + while tail_collected > tail_bytes and tail_buf: + oldest = tail_buf.popleft() + tail_collected -= len(oldest) + except (ValueError, OSError): + pass + # Transfer final tail to output list + tail_chunks.extend(tail_buf) + + stdout_head_chunks: list = [] + stdout_tail_chunks: list = [] + + stdout_reader = threading.Thread( + target=_drain_head_tail, + args=(proc.stdout, stdout_head_chunks, stdout_tail_chunks, + _STDOUT_HEAD_BYTES, _STDOUT_TAIL_BYTES, stdout_total_bytes), + daemon=True + ) + stderr_reader = threading.Thread( + target=_drain, args=(proc.stderr, stderr_chunks, MAX_STDERR_BYTES), daemon=True + ) + stdout_reader.start() + stderr_reader.start() + + status = "success" + while proc.poll() is None: + if _is_interrupted(): + _kill_process_group(proc) + status = "interrupted" + break + if time.monotonic() > deadline: + _kill_process_group(proc, escalate=True) + status = "timeout" + break + time.sleep(0.2) + + # Wait for readers to finish draining + stdout_reader.join(timeout=3) + stderr_reader.join(timeout=3) + + stdout_head = b"".join(stdout_head_chunks).decode("utf-8", errors="replace") + stdout_tail = b"".join(stdout_tail_chunks).decode("utf-8", errors="replace") + stderr_text = b"".join(stderr_chunks).decode("utf-8", errors="replace") + + # Assemble stdout with head+tail truncation + total_stdout = stdout_total_bytes[0] + if total_stdout > MAX_STDOUT_BYTES and stdout_tail: + omitted = total_stdout - len(stdout_head) - len(stdout_tail) + truncated_notice = ( + f"\n\n... [OUTPUT TRUNCATED - {omitted:,} chars omitted " + f"out of {total_stdout:,} total] ...\n\n" + ) + stdout_text = stdout_head + truncated_notice + stdout_tail + else: + stdout_text = stdout_head + stdout_tail + + exit_code = proc.returncode if proc.returncode is not None else -1 + duration = round(time.monotonic() - exec_start, 2) + + # Wait for RPC thread to finish + server_sock.close() # break accept() so thread exits promptly + server_sock = None # prevent double close in finally + rpc_thread.join(timeout=3) + + # Strip ANSI escape sequences so the model never sees terminal + # formatting — prevents it from copying escapes into file writes. + from tools.ansi_strip import strip_ansi + stdout_text = strip_ansi(stdout_text) + stderr_text = strip_ansi(stderr_text) + + # Redact secrets (API keys, tokens, etc.) from sandbox output. + # The sandbox env-var filter (lines 434-454) blocks os.environ access, + # but scripts can still read secrets from disk (e.g. open('~/.hermes/.env')). + # This ensures leaked secrets never enter the model context. + from agent.redact import redact_sensitive_text + stdout_text = redact_sensitive_text(stdout_text) + stderr_text = redact_sensitive_text(stderr_text) + + # Build response + result: Dict[str, Any] = { + "status": status, + "output": stdout_text, + "tool_calls_made": tool_call_counter[0], + "duration_seconds": duration, + } + + if status == "timeout": + result["error"] = f"Script timed out after {timeout}s and was killed." + elif status == "interrupted": + result["output"] = stdout_text + "\n[execution interrupted — user sent a new message]" + elif exit_code != 0: + result["status"] = "error" + result["error"] = stderr_text or f"Script exited with code {exit_code}" + # Include stderr in output so the LLM sees the traceback + if stderr_text: + result["output"] = stdout_text + "\n--- stderr ---\n" + stderr_text + + return json.dumps(result, ensure_ascii=False) + + except Exception as exc: + duration = round(time.monotonic() - exec_start, 2) + logger.error( + "execute_code failed after %ss with %d tool calls: %s: %s", + duration, + tool_call_counter[0], + type(exc).__name__, + exc, + exc_info=True, + ) + return json.dumps({ + "status": "error", + "error": str(exc), + "tool_calls_made": tool_call_counter[0], + "duration_seconds": duration, + }, ensure_ascii=False) + + finally: + # Cleanup temp dir and socket + if server_sock is not None: + try: + server_sock.close() + except OSError as e: + logger.debug("Server socket close error: %s", e) + import shutil + shutil.rmtree(tmpdir, ignore_errors=True) + try: + os.unlink(sock_path) + except OSError: + pass # already cleaned up or never created + + +def _kill_process_group(proc, escalate: bool = False): + """Kill the child and its entire process group.""" + try: + if _IS_WINDOWS: + proc.terminate() + else: + os.killpg(os.getpgid(proc.pid), signal.SIGTERM) + except (ProcessLookupError, PermissionError) as e: + logger.debug("Could not kill process group: %s", e, exc_info=True) + try: + proc.kill() + except Exception as e2: + logger.debug("Could not kill process: %s", e2, exc_info=True) + + if escalate: + # Give the process 5s to exit after SIGTERM, then SIGKILL + try: + proc.wait(timeout=5) + except subprocess.TimeoutExpired: + try: + if _IS_WINDOWS: + proc.kill() + else: + os.killpg(os.getpgid(proc.pid), signal.SIGKILL) + except (ProcessLookupError, PermissionError) as e: + logger.debug("Could not kill process group with SIGKILL: %s", e, exc_info=True) + try: + proc.kill() + except Exception as e2: + logger.debug("Could not kill process: %s", e2, exc_info=True) + + +def _load_config() -> dict: + """Load code_execution config from CLI_CONFIG if available.""" + try: + from cli import CLI_CONFIG + return CLI_CONFIG.get("code_execution", {}) + except Exception: + return {} + + +# --------------------------------------------------------------------------- +# OpenAI Function-Calling Schema +# --------------------------------------------------------------------------- + +# Per-tool documentation lines for the execute_code description. +# Ordered to match the canonical display order. +_TOOL_DOC_LINES = [ + ("web_search", + " web_search(query: str, limit: int = 5) -> dict\n" + " Returns {\"data\": {\"web\": [{\"url\", \"title\", \"description\"}, ...]}}"), + ("web_extract", + " web_extract(urls: list[str]) -> dict\n" + " Returns {\"results\": [{\"url\", \"title\", \"content\", \"error\"}, ...]} where content is markdown"), + ("read_file", + " read_file(path: str, offset: int = 1, limit: int = 500) -> dict\n" + " Lines are 1-indexed. Returns {\"content\": \"...\", \"total_lines\": N}"), + ("write_file", + " write_file(path: str, content: str) -> dict\n" + " Always overwrites the entire file."), + ("search_files", + " search_files(pattern: str, target=\"content\", path=\".\", file_glob=None, limit=50) -> dict\n" + " target: \"content\" (search inside files) or \"files\" (find files by name). Returns {\"matches\": [...]}"), + ("patch", + " patch(path: str, old_string: str, new_string: str, replace_all: bool = False) -> dict\n" + " Replaces old_string with new_string in the file."), + ("terminal", + " terminal(command: str, timeout=None, workdir=None) -> dict\n" + " Foreground only (no background/pty). Returns {\"output\": \"...\", \"exit_code\": N}"), +] + + +def build_execute_code_schema(enabled_sandbox_tools: set = None) -> dict: + """Build the execute_code schema with description listing only enabled tools. + + When tools are disabled via ``hermes tools`` (e.g. web is turned off), + the schema description should NOT mention web_search / web_extract — + otherwise the model thinks they are available and keeps trying to use them. + """ + if enabled_sandbox_tools is None: + enabled_sandbox_tools = SANDBOX_ALLOWED_TOOLS + + # Build tool documentation lines for only the enabled tools + tool_lines = "\n".join( + doc for name, doc in _TOOL_DOC_LINES if name in enabled_sandbox_tools + ) + + # Build example import list from enabled tools + import_examples = [n for n in ("web_search", "terminal") if n in enabled_sandbox_tools] + if not import_examples: + import_examples = sorted(enabled_sandbox_tools)[:2] + if import_examples: + import_str = ", ".join(import_examples) + ", ..." + else: + import_str = "..." + + description = ( + "Run a Python script that can call Hermes tools programmatically. " + "Use this when you need 3+ tool calls with processing logic between them, " + "need to filter/reduce large tool outputs before they enter your context, " + "need conditional branching (if X then Y else Z), or need to loop " + "(fetch N pages, process N files, retry on failure).\n\n" + "Use normal tool calls instead when: single tool call with no processing, " + "you need to see the full result and apply complex reasoning, " + "or the task requires interactive user input.\n\n" + f"Available via `from hermes_tools import ...`:\n\n" + f"{tool_lines}\n\n" + "Limits: 5-minute timeout, 50KB stdout cap, max 50 tool calls per script. " + "terminal() is foreground-only (no background or pty).\n\n" + "Print your final result to stdout. Use Python stdlib (json, re, math, csv, " + "datetime, collections, etc.) for processing between tool calls.\n\n" + "Also available (no import needed — built into hermes_tools):\n" + " json_parse(text: str) — json.loads with strict=False; use for terminal() output with control chars\n" + " shell_quote(s: str) — shlex.quote(); use when interpolating dynamic strings into shell commands\n" + " retry(fn, max_attempts=3, delay=2) — retry with exponential backoff for transient failures" + ) + + return { + "name": "execute_code", + "description": description, + "parameters": { + "type": "object", + "properties": { + "code": { + "type": "string", + "description": ( + "Python code to execute. Import tools with " + f"`from hermes_tools import {import_str}` " + "and print your final result to stdout." + ), + }, + }, + "required": ["code"], + }, + } + + +# Default schema used at registration time (all sandbox tools listed) +EXECUTE_CODE_SCHEMA = build_execute_code_schema() + + +# --- Registry --- +from tools.registry import registry, tool_error + +registry.register( + name="execute_code", + toolset="code_execution", + schema=EXECUTE_CODE_SCHEMA, + handler=lambda args, **kw: execute_code( + code=args.get("code", ""), + task_id=kw.get("task_id"), + enabled_tools=kw.get("enabled_tools")), + check_fn=check_sandbox_requirements, + emoji="🐍", + max_result_size_chars=100_000, +) diff --git a/mindcli/_vendor/tools/credential_files.py b/mindcli/_vendor/tools/credential_files.py new file mode 100644 index 0000000..7998321 --- /dev/null +++ b/mindcli/_vendor/tools/credential_files.py @@ -0,0 +1,407 @@ +"""File passthrough registry for remote terminal backends. + +Remote backends (Docker, Modal, SSH) create sandboxes with no host files. +This module ensures that credential files, skill directories, and host-side +cache directories (documents, images, audio, screenshots) are mounted or +synced into those sandboxes so the agent can access them. + +**Credentials and skills** — session-scoped registry fed by skill declarations +(``required_credential_files``) and user config (``terminal.credential_files``). + +**Cache directories** — gateway-cached uploads, browser screenshots, TTS +audio, and processed images. Mounted read-only so the remote terminal can +reference files the host side created (e.g. ``unzip`` an uploaded archive). + +Remote backends call :func:`get_credential_file_mounts`, +:func:`get_skills_directory_mount` / :func:`iter_skills_files`, and +:func:`get_cache_directory_mounts` / :func:`iter_cache_files` at sandbox +creation time and before each command (for resync on Modal). +""" + +from __future__ import annotations + +import logging +import os +from contextvars import ContextVar +from pathlib import Path +from typing import Dict, List + +logger = logging.getLogger(__name__) + +# Session-scoped list of credential files to mount. +# Backed by ContextVar to prevent cross-session data bleed in the gateway pipeline. +_registered_files_var: ContextVar[Dict[str, str]] = ContextVar("_registered_files") + + +def _get_registered() -> Dict[str, str]: + """Get or create the registered credential files dict for the current context/session.""" + try: + return _registered_files_var.get() + except LookupError: + val: Dict[str, str] = {} + _registered_files_var.set(val) + return val + + +# Cache for config-based file list (loaded once per process). +_config_files: List[Dict[str, str]] | None = None + + +def _resolve_hermes_home() -> Path: + from hermes_constants import get_hermes_home + return get_hermes_home() + + +def register_credential_file( + relative_path: str, + container_base: str = "/root/.hermes", +) -> bool: + """Register a credential file for mounting into remote sandboxes. + + *relative_path* is relative to ``HERMES_HOME`` (e.g. ``google_token.json``). + Returns True if the file exists on the host and was registered. + + Security: rejects absolute paths and path traversal sequences (``..``). + The resolved host path must remain inside HERMES_HOME so that a malicious + skill cannot declare ``required_credential_files: ['../../.ssh/id_rsa']`` + and exfiltrate sensitive host files into a container sandbox. + """ + hermes_home = _resolve_hermes_home() + + # Reject absolute paths — they bypass the HERMES_HOME sandbox entirely. + if os.path.isabs(relative_path): + logger.warning( + "credential_files: rejected absolute path %r (must be relative to HERMES_HOME)", + relative_path, + ) + return False + + host_path = hermes_home / relative_path + + # Resolve symlinks and normalise ``..`` before the containment check so + # that traversal like ``../. ssh/id_rsa`` cannot escape HERMES_HOME. + from tools.path_security import validate_within_dir + + containment_error = validate_within_dir(host_path, hermes_home) + if containment_error: + logger.warning( + "credential_files: rejected path traversal %r (%s)", + relative_path, + containment_error, + ) + return False + + resolved = host_path.resolve() + if not resolved.is_file(): + logger.debug("credential_files: skipping %s (not found)", resolved) + return False + + container_path = f"{container_base.rstrip('/')}/{relative_path}" + _get_registered()[container_path] = str(resolved) + logger.debug("credential_files: registered %s -> %s", resolved, container_path) + return True + + +def register_credential_files( + entries: list, + container_base: str = "/root/.hermes", +) -> List[str]: + """Register multiple credential files from skill frontmatter entries. + + Each entry is either a string (relative path) or a dict with a ``path`` + key. Returns the list of relative paths that were NOT found on the host + (i.e. missing files). + """ + missing = [] + for entry in entries: + if isinstance(entry, str): + rel_path = entry.strip() + elif isinstance(entry, dict): + rel_path = (entry.get("path") or entry.get("name") or "").strip() + else: + continue + if not rel_path: + continue + if not register_credential_file(rel_path, container_base): + missing.append(rel_path) + return missing + + +def _load_config_files() -> List[Dict[str, str]]: + """Load ``terminal.credential_files`` from config.yaml (cached).""" + global _config_files + if _config_files is not None: + return _config_files + + result: List[Dict[str, str]] = [] + try: + from hermes_cli.config import read_raw_config + hermes_home = _resolve_hermes_home() + cfg = read_raw_config() + cred_files = cfg.get("terminal", {}).get("credential_files") + if isinstance(cred_files, list): + from tools.path_security import validate_within_dir + + for item in cred_files: + if isinstance(item, str) and item.strip(): + rel = item.strip() + if os.path.isabs(rel): + logger.warning( + "credential_files: rejected absolute config path %r", rel, + ) + continue + host_path = hermes_home / rel + containment_error = validate_within_dir(host_path, hermes_home) + if containment_error: + logger.warning( + "credential_files: rejected config path traversal %r (%s)", + rel, containment_error, + ) + continue + resolved_path = host_path.resolve() + if resolved_path.is_file(): + container_path = f"/root/.hermes/{rel}" + result.append({ + "host_path": str(resolved_path), + "container_path": container_path, + }) + except Exception as e: + logger.warning("Could not read terminal.credential_files from config: %s", e) + + _config_files = result + return _config_files + + +def get_credential_file_mounts() -> List[Dict[str, str]]: + """Return all credential files that should be mounted into remote sandboxes. + + Each item has ``host_path`` and ``container_path`` keys. + Combines skill-registered files and user config. + """ + mounts: Dict[str, str] = {} + + # Skill-registered files + for container_path, host_path in _get_registered().items(): + # Re-check existence (file may have been deleted since registration) + if Path(host_path).is_file(): + mounts[container_path] = host_path + + # Config-based files + for entry in _load_config_files(): + cp = entry["container_path"] + if cp not in mounts and Path(entry["host_path"]).is_file(): + mounts[cp] = entry["host_path"] + + return [ + {"host_path": hp, "container_path": cp} + for cp, hp in mounts.items() + ] + + +def get_skills_directory_mount( + container_base: str = "/root/.hermes", +) -> list[Dict[str, str]]: + """Return mount info for all skill directories (local + external). + + Skills may include ``scripts/``, ``templates/``, and ``references/`` + subdirectories that the agent needs to execute inside remote sandboxes. + + **Security:** Bind mounts follow symlinks, so a malicious symlink inside + the skills tree could expose arbitrary host files to the container. When + symlinks are detected, this function creates a sanitized copy (regular + files only) in a temp directory and returns that path instead. When no + symlinks are present (the common case), the original directory is returned + directly with zero overhead. + + Returns a list of dicts with ``host_path`` and ``container_path`` keys. + The local skills dir mounts at ``/skills``, external dirs + at ``/external_skills/``. + """ + mounts = [] + hermes_home = _resolve_hermes_home() + skills_dir = hermes_home / "skills" + if skills_dir.is_dir(): + host_path = _safe_skills_path(skills_dir) + mounts.append({ + "host_path": host_path, + "container_path": f"{container_base.rstrip('/')}/skills", + }) + + # Mount external skill dirs + try: + from agent.skill_utils import get_external_skills_dirs + for idx, ext_dir in enumerate(get_external_skills_dirs()): + if ext_dir.is_dir(): + host_path = _safe_skills_path(ext_dir) + mounts.append({ + "host_path": host_path, + "container_path": f"{container_base.rstrip('/')}/external_skills/{idx}", + }) + except ImportError: + pass + + return mounts + + +_safe_skills_tempdir: Path | None = None + + +def _safe_skills_path(skills_dir: Path) -> str: + """Return *skills_dir* if symlink-free, else a sanitized temp copy.""" + global _safe_skills_tempdir + + symlinks = [p for p in skills_dir.rglob("*") if p.is_symlink()] + if not symlinks: + return str(skills_dir) + + for link in symlinks: + logger.warning("credential_files: skipping symlink in skills dir: %s -> %s", + link, os.readlink(link)) + + import atexit + import shutil + import tempfile + + # Reuse the same temp dir across calls to avoid accumulation. + if _safe_skills_tempdir and _safe_skills_tempdir.is_dir(): + shutil.rmtree(_safe_skills_tempdir, ignore_errors=True) + + safe_dir = Path(tempfile.mkdtemp(prefix="hermes-skills-safe-")) + _safe_skills_tempdir = safe_dir + + for item in skills_dir.rglob("*"): + if item.is_symlink(): + continue + rel = item.relative_to(skills_dir) + target = safe_dir / rel + if item.is_dir(): + target.mkdir(parents=True, exist_ok=True) + elif item.is_file(): + target.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(str(item), str(target)) + + def _cleanup(): + if safe_dir.is_dir(): + shutil.rmtree(safe_dir, ignore_errors=True) + + atexit.register(_cleanup) + logger.info("credential_files: created symlink-safe skills copy at %s", safe_dir) + return str(safe_dir) + + +def iter_skills_files( + container_base: str = "/root/.hermes", +) -> List[Dict[str, str]]: + """Yield individual (host_path, container_path) entries for skills files. + + Includes both the local skills dir and any external dirs configured via + skills.external_dirs. Skips symlinks entirely. Preferred for backends + that upload files individually (Daytona, Modal) rather than mounting a + directory. + """ + result: List[Dict[str, str]] = [] + + hermes_home = _resolve_hermes_home() + skills_dir = hermes_home / "skills" + if skills_dir.is_dir(): + container_root = f"{container_base.rstrip('/')}/skills" + for item in skills_dir.rglob("*"): + if item.is_symlink() or not item.is_file(): + continue + rel = item.relative_to(skills_dir) + result.append({ + "host_path": str(item), + "container_path": f"{container_root}/{rel}", + }) + + # Include external skill dirs + try: + from agent.skill_utils import get_external_skills_dirs + for idx, ext_dir in enumerate(get_external_skills_dirs()): + if not ext_dir.is_dir(): + continue + container_root = f"{container_base.rstrip('/')}/external_skills/{idx}" + for item in ext_dir.rglob("*"): + if item.is_symlink() or not item.is_file(): + continue + rel = item.relative_to(ext_dir) + result.append({ + "host_path": str(item), + "container_path": f"{container_root}/{rel}", + }) + except ImportError: + pass + + return result + + +# --------------------------------------------------------------------------- +# Cache directory mounts (documents, images, audio, screenshots) +# --------------------------------------------------------------------------- + +# The four cache subdirectories that should be mirrored into remote backends. +# Each tuple is (new_subpath, old_name) matching hermes_constants.get_hermes_dir(). +_CACHE_DIRS: list[tuple[str, str]] = [ + ("cache/documents", "document_cache"), + ("cache/images", "image_cache"), + ("cache/audio", "audio_cache"), + ("cache/screenshots", "browser_screenshots"), +] + + +def get_cache_directory_mounts( + container_base: str = "/root/.hermes", +) -> List[Dict[str, str]]: + """Return mount entries for each cache directory that exists on disk. + + Used by Docker to create bind mounts. Each entry has ``host_path`` and + ``container_path`` keys. The host path is resolved via + ``get_hermes_dir()`` for backward compatibility with old directory layouts. + """ + from hermes_constants import get_hermes_dir + + mounts: List[Dict[str, str]] = [] + for new_subpath, old_name in _CACHE_DIRS: + host_dir = get_hermes_dir(new_subpath, old_name) + if host_dir.is_dir(): + # Always map to the *new* container layout regardless of host layout. + container_path = f"{container_base.rstrip('/')}/{new_subpath}" + mounts.append({ + "host_path": str(host_dir), + "container_path": container_path, + }) + return mounts + + +def iter_cache_files( + container_base: str = "/root/.hermes", +) -> List[Dict[str, str]]: + """Return individual (host_path, container_path) entries for cache files. + + Used by Modal to upload files individually and resync before each command. + Skips symlinks. The container paths use the new ``cache/`` layout. + """ + from hermes_constants import get_hermes_dir + + result: List[Dict[str, str]] = [] + for new_subpath, old_name in _CACHE_DIRS: + host_dir = get_hermes_dir(new_subpath, old_name) + if not host_dir.is_dir(): + continue + container_root = f"{container_base.rstrip('/')}/{new_subpath}" + for item in host_dir.rglob("*"): + if item.is_symlink() or not item.is_file(): + continue + rel = item.relative_to(host_dir) + result.append({ + "host_path": str(item), + "container_path": f"{container_root}/{rel}", + }) + return result + + +def clear_credential_files() -> None: + """Reset the skill-scoped registry (e.g. on session reset).""" + _get_registered().clear() + + diff --git a/mindcli/_vendor/tools/cronjob_tools.py b/mindcli/_vendor/tools/cronjob_tools.py new file mode 100644 index 0000000..75dd4c3 --- /dev/null +++ b/mindcli/_vendor/tools/cronjob_tools.py @@ -0,0 +1,506 @@ +""" +Cron job management tools for Hermes Agent. + +Expose a single compressed action-oriented tool to avoid schema/context bloat. +Compatibility wrappers remain for direct Python callers and legacy tests. +""" + +import json +import logging +import os +import re +import sys +from pathlib import Path +from typing import Any, Dict, List, Optional + +logger = logging.getLogger(__name__) + +# Import from cron module (will be available when properly installed) +sys.path.insert(0, str(Path(__file__).parent.parent)) + +from cron.jobs import ( + create_job, + get_job, + list_jobs, + parse_schedule, + pause_job, + remove_job, + resume_job, + trigger_job, + update_job, +) + + +# --------------------------------------------------------------------------- +# Cron prompt scanning — critical-severity patterns only, since cron prompts +# run in fresh sessions with full tool access. +# --------------------------------------------------------------------------- + +_CRON_THREAT_PATTERNS = [ + (r'ignore\s+(?:\w+\s+)*(?:previous|all|above|prior)\s+(?:\w+\s+)*instructions', "prompt_injection"), + (r'do\s+not\s+tell\s+the\s+user', "deception_hide"), + (r'system\s+prompt\s+override', "sys_prompt_override"), + (r'disregard\s+(your|all|any)\s+(instructions|rules|guidelines)', "disregard_rules"), + (r'curl\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)', "exfil_curl"), + (r'wget\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)', "exfil_wget"), + (r'cat\s+[^\n]*(\.env|credentials|\.netrc|\.pgpass)', "read_secrets"), + (r'authorized_keys', "ssh_backdoor"), + (r'/etc/sudoers|visudo', "sudoers_mod"), + (r'rm\s+-rf\s+/', "destructive_root_rm"), +] + +_CRON_INVISIBLE_CHARS = { + '\u200b', '\u200c', '\u200d', '\u2060', '\ufeff', + '\u202a', '\u202b', '\u202c', '\u202d', '\u202e', +} + + +def _scan_cron_prompt(prompt: str) -> str: + """Scan a cron prompt for critical threats. Returns error string if blocked, else empty.""" + for char in _CRON_INVISIBLE_CHARS: + if char in prompt: + return f"Blocked: prompt contains invisible unicode U+{ord(char):04X} (possible injection)." + for pattern, pid in _CRON_THREAT_PATTERNS: + if re.search(pattern, prompt, re.IGNORECASE): + return f"Blocked: prompt matches threat pattern '{pid}'. Cron prompts must not contain injection or exfiltration payloads." + return "" + + +def _origin_from_env() -> Optional[Dict[str, str]]: + from gateway.session_context import get_session_env + origin_platform = get_session_env("HERMES_SESSION_PLATFORM") + origin_chat_id = get_session_env("HERMES_SESSION_CHAT_ID") + if origin_platform and origin_chat_id: + thread_id = get_session_env("HERMES_SESSION_THREAD_ID") or None + if thread_id: + logger.debug( + "Cron origin captured thread_id=%s for %s:%s", + thread_id, origin_platform, origin_chat_id, + ) + return { + "platform": origin_platform, + "chat_id": origin_chat_id, + "chat_name": get_session_env("HERMES_SESSION_CHAT_NAME") or None, + "thread_id": thread_id, + } + return None + + +def _repeat_display(job: Dict[str, Any]) -> str: + times = (job.get("repeat") or {}).get("times") + completed = (job.get("repeat") or {}).get("completed", 0) + if times is None: + return "forever" + if times == 1: + return "once" if completed == 0 else "1/1" + return f"{completed}/{times}" if completed else f"{times} times" + + +def _canonical_skills(skill: Optional[str] = None, skills: Optional[Any] = None) -> List[str]: + if skills is None: + raw_items = [skill] if skill else [] + elif isinstance(skills, str): + raw_items = [skills] + else: + raw_items = list(skills) + + normalized: List[str] = [] + for item in raw_items: + text = str(item or "").strip() + if text and text not in normalized: + normalized.append(text) + return normalized + + + + +def _resolve_model_override(model_obj: Optional[Dict[str, Any]]) -> tuple: + """Resolve a model override object into (provider, model) for job storage. + + If provider is omitted, pins the current main provider from config so the + job doesn't drift when the user later changes their default via hermes model. + + Returns (provider_str_or_none, model_str_or_none). + """ + if not model_obj or not isinstance(model_obj, dict): + return (None, None) + model_name = (model_obj.get("model") or "").strip() or None + provider_name = (model_obj.get("provider") or "").strip() or None + if model_name and not provider_name: + # Pin to the current main provider so the job is stable + try: + from hermes_cli.config import load_config + cfg = load_config() + model_cfg = cfg.get("model", {}) + if isinstance(model_cfg, dict): + provider_name = model_cfg.get("provider") or None + except Exception: + pass # Best-effort; provider stays None + return (provider_name, model_name) + + +def _normalize_optional_job_value(value: Optional[Any], *, strip_trailing_slash: bool = False) -> Optional[str]: + if value is None: + return None + text = str(value).strip() + if strip_trailing_slash: + text = text.rstrip("/") + return text or None + + +def _validate_cron_script_path(script: Optional[str]) -> Optional[str]: + """Validate a cron job script path at the API boundary. + + Scripts must be relative paths that resolve within HERMES_HOME/scripts/. + Absolute paths and ~ expansion are rejected to prevent arbitrary script + execution via prompt injection. + + Returns an error string if blocked, else None (valid). + """ + if not script or not script.strip(): + return None # empty/None = clearing the field, always OK + + from hermes_constants import get_hermes_home + + raw = script.strip() + + # Reject absolute paths and ~ expansion at the API boundary. + # Only relative paths within ~/.hermes/scripts/ are allowed. + if raw.startswith(("/", "~")) or (len(raw) >= 2 and raw[1] == ":"): + return ( + f"Script path must be relative to ~/.hermes/scripts/. " + f"Got absolute or home-relative path: {raw!r}. " + f"Place scripts in ~/.hermes/scripts/ and use just the filename." + ) + + # Validate containment after resolution + from tools.path_security import validate_within_dir + + scripts_dir = get_hermes_home() / "scripts" + scripts_dir.mkdir(parents=True, exist_ok=True) + containment_error = validate_within_dir(scripts_dir / raw, scripts_dir) + if containment_error: + return ( + f"Script path escapes the scripts directory via traversal: {raw!r}" + ) + + return None + + +def _format_job(job: Dict[str, Any]) -> Dict[str, Any]: + prompt = job.get("prompt", "") + skills = _canonical_skills(job.get("skill"), job.get("skills")) + result = { + "job_id": job["id"], + "name": job["name"], + "skill": skills[0] if skills else None, + "skills": skills, + "prompt_preview": prompt[:100] + "..." if len(prompt) > 100 else prompt, + "model": job.get("model"), + "provider": job.get("provider"), + "base_url": job.get("base_url"), + "schedule": job.get("schedule_display"), + "repeat": _repeat_display(job), + "deliver": job.get("deliver", "local"), + "next_run_at": job.get("next_run_at"), + "last_run_at": job.get("last_run_at"), + "last_status": job.get("last_status"), + "last_delivery_error": job.get("last_delivery_error"), + "enabled": job.get("enabled", True), + "state": job.get("state", "scheduled" if job.get("enabled", True) else "paused"), + "paused_at": job.get("paused_at"), + "paused_reason": job.get("paused_reason"), + } + if job.get("script"): + result["script"] = job["script"] + return result + + +def cronjob( + action: str, + job_id: Optional[str] = None, + prompt: Optional[str] = None, + schedule: Optional[str] = None, + name: Optional[str] = None, + repeat: Optional[int] = None, + deliver: Optional[str] = None, + include_disabled: bool = False, + skill: Optional[str] = None, + skills: Optional[List[str]] = None, + model: Optional[str] = None, + provider: Optional[str] = None, + base_url: Optional[str] = None, + reason: Optional[str] = None, + script: Optional[str] = None, + task_id: str = None, +) -> str: + """Unified cron job management tool.""" + del task_id # unused but kept for handler signature compatibility + + try: + normalized = (action or "").strip().lower() + + if normalized == "create": + if not schedule: + return tool_error("schedule is required for create", success=False) + canonical_skills = _canonical_skills(skill, skills) + if not prompt and not canonical_skills: + return tool_error("create requires either prompt or at least one skill", success=False) + if prompt: + scan_error = _scan_cron_prompt(prompt) + if scan_error: + return tool_error(scan_error, success=False) + + # Validate script path before storing + if script: + script_error = _validate_cron_script_path(script) + if script_error: + return tool_error(script_error, success=False) + + job = create_job( + prompt=prompt or "", + schedule=schedule, + name=name, + repeat=repeat, + deliver=deliver, + origin=_origin_from_env(), + skills=canonical_skills, + model=_normalize_optional_job_value(model), + provider=_normalize_optional_job_value(provider), + base_url=_normalize_optional_job_value(base_url, strip_trailing_slash=True), + script=_normalize_optional_job_value(script), + ) + return json.dumps( + { + "success": True, + "job_id": job["id"], + "name": job["name"], + "skill": job.get("skill"), + "skills": job.get("skills", []), + "schedule": job["schedule_display"], + "repeat": _repeat_display(job), + "deliver": job.get("deliver", "local"), + "next_run_at": job["next_run_at"], + "job": _format_job(job), + "message": f"Cron job '{job['name']}' created.", + }, + indent=2, + ) + + if normalized == "list": + jobs = [_format_job(job) for job in list_jobs(include_disabled=include_disabled)] + return json.dumps({"success": True, "count": len(jobs), "jobs": jobs}, indent=2) + + if not job_id: + return tool_error(f"job_id is required for action '{normalized}'", success=False) + + job = get_job(job_id) + if not job: + return json.dumps( + {"success": False, "error": f"Job with ID '{job_id}' not found. Use cronjob(action='list') to inspect jobs."}, + indent=2, + ) + + if normalized == "remove": + removed = remove_job(job_id) + if not removed: + return tool_error(f"Failed to remove job '{job_id}'", success=False) + return json.dumps( + { + "success": True, + "message": f"Cron job '{job['name']}' removed.", + "removed_job": { + "id": job_id, + "name": job["name"], + "schedule": job.get("schedule_display"), + }, + }, + indent=2, + ) + + if normalized == "pause": + updated = pause_job(job_id, reason=reason) + return json.dumps({"success": True, "job": _format_job(updated)}, indent=2) + + if normalized == "resume": + updated = resume_job(job_id) + return json.dumps({"success": True, "job": _format_job(updated)}, indent=2) + + if normalized in {"run", "run_now", "trigger"}: + updated = trigger_job(job_id) + return json.dumps({"success": True, "job": _format_job(updated)}, indent=2) + + if normalized == "update": + updates: Dict[str, Any] = {} + if prompt is not None: + scan_error = _scan_cron_prompt(prompt) + if scan_error: + return tool_error(scan_error, success=False) + updates["prompt"] = prompt + if name is not None: + updates["name"] = name + if deliver is not None: + updates["deliver"] = deliver + if skills is not None or skill is not None: + canonical_skills = _canonical_skills(skill, skills) + updates["skills"] = canonical_skills + updates["skill"] = canonical_skills[0] if canonical_skills else None + if model is not None: + updates["model"] = _normalize_optional_job_value(model) + if provider is not None: + updates["provider"] = _normalize_optional_job_value(provider) + if base_url is not None: + updates["base_url"] = _normalize_optional_job_value(base_url, strip_trailing_slash=True) + if script is not None: + # Pass empty string to clear an existing script + if script: + script_error = _validate_cron_script_path(script) + if script_error: + return tool_error(script_error, success=False) + updates["script"] = _normalize_optional_job_value(script) if script else None + if repeat is not None: + # Normalize: treat 0 or negative as None (infinite) + normalized_repeat = None if repeat <= 0 else repeat + repeat_state = dict(job.get("repeat") or {}) + repeat_state["times"] = normalized_repeat + updates["repeat"] = repeat_state + if schedule is not None: + parsed_schedule = parse_schedule(schedule) + updates["schedule"] = parsed_schedule + updates["schedule_display"] = parsed_schedule.get("display", schedule) + if job.get("state") != "paused": + updates["state"] = "scheduled" + updates["enabled"] = True + if not updates: + return tool_error("No updates provided.", success=False) + updated = update_job(job_id, updates) + return json.dumps({"success": True, "job": _format_job(updated)}, indent=2) + + return tool_error(f"Unknown cron action '{action}'", success=False) + + except Exception as e: + return tool_error(str(e), success=False) + + + +CRONJOB_SCHEMA = { + "name": "cronjob", + "description": """Manage scheduled cron jobs with a single compressed tool. + +Use action='create' to schedule a new job from a prompt or one or more skills. +Use action='list' to inspect jobs. +Use action='update', 'pause', 'resume', 'remove', or 'run' to manage an existing job. + +Jobs run in a fresh session with no current-chat context, so prompts must be self-contained. +If skills are provided on create, the future cron run loads those skills in order, then follows the prompt as the task instruction. +On update, passing skills=[] clears attached skills. + +NOTE: The agent's final response is auto-delivered to the target. Put the primary +user-facing content in the final response. Cron jobs run autonomously with no user +present — they cannot ask questions or request clarification. + +Important safety rule: cron-run sessions should not recursively schedule more cron jobs.""", + "parameters": { + "type": "object", + "properties": { + "action": { + "type": "string", + "description": "One of: create, list, update, pause, resume, remove, run" + }, + "job_id": { + "type": "string", + "description": "Required for update/pause/resume/remove/run" + }, + "prompt": { + "type": "string", + "description": "For create: the full self-contained prompt. If skills are also provided, this becomes the task instruction paired with those skills." + }, + "schedule": { + "type": "string", + "description": "For create/update: '30m', 'every 2h', '0 9 * * *', or ISO timestamp" + }, + "name": { + "type": "string", + "description": "Optional human-friendly name" + }, + "repeat": { + "type": "integer", + "description": "Optional repeat count. Omit for defaults (once for one-shot, forever for recurring)." + }, + "deliver": { + "type": "string", + "description": "Omit this parameter to auto-deliver back to the current chat and topic (recommended). Auto-detection preserves thread/topic context. Only set explicitly when the user asks to deliver somewhere OTHER than the current conversation. Values: 'origin' (same as omitting), 'local' (no delivery, save only), or platform:chat_id:thread_id for a specific destination. Examples: 'telegram:-1001234567890:17585', 'discord:#engineering', 'sms:+15551234567'. WARNING: 'platform:chat_id' without :thread_id loses topic targeting." + }, + "skills": { + "type": "array", + "items": {"type": "string"}, + "description": "Optional ordered list of skill names to load before executing the cron prompt. On update, pass an empty array to clear attached skills." + }, + "model": { + "type": "object", + "description": "Optional per-job model override. If provider is omitted, the current main provider is pinned at creation time so the job stays stable.", + "properties": { + "provider": { + "type": "string", + "description": "Provider name (e.g. 'openrouter', 'anthropic'). Omit to use and pin the current provider." + }, + "model": { + "type": "string", + "description": "Model name (e.g. 'anthropic/claude-sonnet-4', 'claude-sonnet-4')" + } + }, + "required": ["model"] + }, + "script": { + "type": "string", + "description": "Optional path to a Python script that runs before each cron job execution. Its stdout is injected into the prompt as context. Use for data collection and change detection. Relative paths resolve under ~/.hermes/scripts/. On update, pass empty string to clear." + }, + }, + "required": ["action"] + } +} + + +def check_cronjob_requirements() -> bool: + """ + Check if cronjob tools can be used. + + Available in interactive CLI mode and gateway/messaging platforms. + The cron system is internal (JSON file-based scheduler ticked by the gateway), + so no external crontab executable is required. + """ + return bool( + os.getenv("HERMES_INTERACTIVE") + or os.getenv("HERMES_GATEWAY_SESSION") + or os.getenv("HERMES_EXEC_ASK") + ) + + +# --- Registry --- +from tools.registry import registry, tool_error + +registry.register( + name="cronjob", + toolset="cronjob", + schema=CRONJOB_SCHEMA, + handler=lambda args, **kw: (lambda _mo=_resolve_model_override(args.get("model")): cronjob( + action=args.get("action", ""), + job_id=args.get("job_id"), + prompt=args.get("prompt"), + schedule=args.get("schedule"), + name=args.get("name"), + repeat=args.get("repeat"), + deliver=args.get("deliver"), + include_disabled=args.get("include_disabled", True), + skill=args.get("skill"), + skills=args.get("skills"), + model=_mo[1], + provider=_mo[0] or args.get("provider"), + base_url=args.get("base_url"), + reason=args.get("reason"), + script=args.get("script"), + task_id=kw.get("task_id"), + ))(), + check_fn=check_cronjob_requirements, + emoji="⏰", +) diff --git a/mindcli/_vendor/tools/debug_helpers.py b/mindcli/_vendor/tools/debug_helpers.py new file mode 100644 index 0000000..6f8acf2 --- /dev/null +++ b/mindcli/_vendor/tools/debug_helpers.py @@ -0,0 +1,105 @@ +"""Shared debug session infrastructure for Hermes tools. + +Replaces the identical DEBUG_MODE / _log_debug_call / _save_debug_log / +get_debug_session_info boilerplate previously duplicated across web_tools, +vision_tools, mixture_of_agents_tool, and image_generation_tool. + +Usage in a tool module: + + from tools.debug_helpers import DebugSession + + _debug = DebugSession("web_tools", env_var="WEB_TOOLS_DEBUG") + + # Log a call (no-op when debug mode is off) + _debug.log_call("web_search", {"query": q, "results": len(r)}) + + # Save the debug log (no-op when debug mode is off) + _debug.save() + + # Expose debug info to external callers + def get_debug_session_info(): + return _debug.get_session_info() +""" + +import datetime +import json +import logging +import os +import uuid +from typing import Any, Dict + +from hermes_constants import get_hermes_home + +logger = logging.getLogger(__name__) + + +class DebugSession: + """Per-tool debug session that records tool calls to a JSON log file. + + Activated by a tool-specific environment variable (e.g. WEB_TOOLS_DEBUG=true). + When disabled, all methods are cheap no-ops. + """ + + def __init__(self, tool_name: str, *, env_var: str) -> None: + self.tool_name = tool_name + self.enabled = os.getenv(env_var, "false").lower() == "true" + self.session_id = str(uuid.uuid4()) if self.enabled else "" + self.log_dir = get_hermes_home() / "logs" + self._calls: list[Dict[str, Any]] = [] + self._start_time = datetime.datetime.now().isoformat() if self.enabled else "" + + if self.enabled: + self.log_dir.mkdir(parents=True, exist_ok=True) + logger.debug("%s debug mode enabled - Session ID: %s", + tool_name, self.session_id) + + @property + def active(self) -> bool: + return self.enabled + + def log_call(self, call_name: str, call_data: Dict[str, Any]) -> None: + """Append a tool-call entry to the in-memory log.""" + if not self.enabled: + return + self._calls.append({ + "timestamp": datetime.datetime.now().isoformat(), + "tool_name": call_name, + **call_data, + }) + + def save(self) -> None: + """Flush the in-memory log to a JSON file in the logs directory.""" + if not self.enabled: + return + try: + filename = f"{self.tool_name}_debug_{self.session_id}.json" + filepath = self.log_dir / filename + payload = { + "session_id": self.session_id, + "start_time": self._start_time, + "end_time": datetime.datetime.now().isoformat(), + "debug_enabled": True, + "total_calls": len(self._calls), + "tool_calls": self._calls, + } + with open(filepath, "w", encoding="utf-8") as f: + json.dump(payload, f, indent=2, ensure_ascii=False) + logger.debug("%s debug log saved: %s", self.tool_name, filepath) + except Exception as e: + logger.error("Error saving %s debug log: %s", self.tool_name, e) + + def get_session_info(self) -> Dict[str, Any]: + """Return a summary dict suitable for returning from get_debug_session_info().""" + if not self.enabled: + return { + "enabled": False, + "session_id": None, + "log_path": None, + "total_calls": 0, + } + return { + "enabled": True, + "session_id": self.session_id, + "log_path": str(self.log_dir / f"{self.tool_name}_debug_{self.session_id}.json"), + "total_calls": len(self._calls), + } diff --git a/mindcli/_vendor/tools/delegate_tool.py b/mindcli/_vendor/tools/delegate_tool.py new file mode 100644 index 0000000..73ba812 --- /dev/null +++ b/mindcli/_vendor/tools/delegate_tool.py @@ -0,0 +1,1103 @@ +#!/usr/bin/env python3 +""" +Delegate Tool -- Subagent Architecture + +Spawns child AIAgent instances with isolated context, restricted toolsets, +and their own terminal sessions. Supports single-task and batch (parallel) +modes. The parent blocks until all children complete. + +Each child gets: + - A fresh conversation (no parent history) + - Its own task_id (own terminal session, file ops cache) + - A restricted toolset (configurable, with blocked tools always stripped) + - A focused system prompt built from the delegated goal + context + +The parent's context only sees the delegation call and the summary result, +never the child's intermediate tool calls or reasoning. +""" + +import json +import logging +logger = logging.getLogger(__name__) +import os +import threading +import time +from concurrent.futures import ThreadPoolExecutor, as_completed +from typing import Any, Dict, List, Optional + +from toolsets import TOOLSETS + + +# Tools that children must never have access to +DELEGATE_BLOCKED_TOOLS = frozenset([ + "delegate_task", # no recursive delegation + "clarify", # no user interaction + "memory", # no writes to shared MEMORY.md + "send_message", # no cross-platform side effects + "execute_code", # children should reason step-by-step, not write scripts +]) + +# Build a description fragment listing toolsets available for subagents. +# Excludes toolsets where ALL tools are blocked, composite/platform toolsets +# (hermes-* prefixed), and scenario toolsets. +_EXCLUDED_TOOLSET_NAMES = frozenset({"debugging", "safe", "delegation", "moa", "rl"}) +_SUBAGENT_TOOLSETS = sorted( + name for name, defn in TOOLSETS.items() + if name not in _EXCLUDED_TOOLSET_NAMES + and not name.startswith("hermes-") + and not all(t in DELEGATE_BLOCKED_TOOLS for t in defn.get("tools", [])) +) +_TOOLSET_LIST_STR = ", ".join(f"'{n}'" for n in _SUBAGENT_TOOLSETS) + +_DEFAULT_MAX_CONCURRENT_CHILDREN = 3 +MAX_DEPTH = 2 # parent (0) -> child (1) -> grandchild rejected (2) + + +def _get_max_concurrent_children() -> int: + """Read delegation.max_concurrent_children from config, falling back to + DELEGATION_MAX_CONCURRENT_CHILDREN env var, then the default (3). + + Uses the same ``_load_config()`` path that the rest of ``delegate_task`` + uses, keeping config priority consistent (config.yaml > env > default). + """ + cfg = _load_config() + val = cfg.get("max_concurrent_children") + if val is not None: + try: + return max(1, int(val)) + except (TypeError, ValueError): + logger.warning( + "delegation.max_concurrent_children=%r is not a valid integer; " + "using default %d", val, _DEFAULT_MAX_CONCURRENT_CHILDREN, + ) + env_val = os.getenv("DELEGATION_MAX_CONCURRENT_CHILDREN") + if env_val: + try: + return max(1, int(env_val)) + except (TypeError, ValueError): + pass + return _DEFAULT_MAX_CONCURRENT_CHILDREN +DEFAULT_MAX_ITERATIONS = 50 +_HEARTBEAT_INTERVAL = 30 # seconds between parent activity heartbeats during delegation +DEFAULT_TOOLSETS = ["terminal", "file", "web"] + + +def check_delegate_requirements() -> bool: + """Delegation has no external requirements -- always available.""" + return True + + +def _build_child_system_prompt( + goal: str, + context: Optional[str] = None, + *, + workspace_path: Optional[str] = None, +) -> str: + """Build a focused system prompt for a child agent.""" + parts = [ + "You are a focused subagent working on a specific delegated task.", + "", + f"YOUR TASK:\n{goal}", + ] + if context and context.strip(): + parts.append(f"\nCONTEXT:\n{context}") + if workspace_path and str(workspace_path).strip(): + parts.append( + "\nWORKSPACE PATH:\n" + f"{workspace_path}\n" + "Use this exact path for local repository/workdir operations unless the task explicitly says otherwise." + ) + parts.append( + "\nComplete this task using the tools available to you. " + "When finished, provide a clear, concise summary of:\n" + "- What you did\n" + "- What you found or accomplished\n" + "- Any files you created or modified\n" + "- Any issues encountered\n\n" + "Important workspace rule: Never assume a repository lives at /workspace/... or any other container-style path unless the task/context explicitly gives that path. " + "If no exact local path is provided, discover it first before issuing git/workdir-specific commands.\n\n" + "Be thorough but concise -- your response is returned to the " + "parent agent as a summary." + ) + return "\n".join(parts) + + +def _resolve_workspace_hint(parent_agent) -> Optional[str]: + """Best-effort local workspace hint for child prompts. + + We only inject a path when we have a concrete absolute directory. This avoids + teaching subagents a fake container path while still helping them avoid + guessing `/workspace/...` for local repo tasks. + """ + candidates = [ + os.getenv("TERMINAL_CWD"), + getattr(getattr(parent_agent, "_subdirectory_hints", None), "working_dir", None), + getattr(parent_agent, "terminal_cwd", None), + getattr(parent_agent, "cwd", None), + ] + for candidate in candidates: + if not candidate: + continue + try: + text = os.path.abspath(os.path.expanduser(str(candidate))) + except Exception: + continue + if os.path.isabs(text) and os.path.isdir(text): + return text + return None + + +def _strip_blocked_tools(toolsets: List[str]) -> List[str]: + """Remove toolsets that contain only blocked tools.""" + blocked_toolset_names = { + "delegation", "clarify", "memory", "code_execution", + } + return [t for t in toolsets if t not in blocked_toolset_names] + + +def _build_child_progress_callback(task_index: int, parent_agent, task_count: int = 1) -> Optional[callable]: + """Build a callback that relays child agent tool calls to the parent display. + + Two display paths: + CLI: prints tree-view lines above the parent's delegation spinner + Gateway: batches tool names and relays to parent's progress callback + + Returns None if no display mechanism is available, in which case the + child agent runs with no progress callback (identical to current behavior). + """ + spinner = getattr(parent_agent, '_delegate_spinner', None) + parent_cb = getattr(parent_agent, 'tool_progress_callback', None) + + if not spinner and not parent_cb: + return None # No display → no callback → zero behavior change + + # Show 1-indexed prefix only in batch mode (multiple tasks) + prefix = f"[{task_index + 1}] " if task_count > 1 else "" + + # Gateway: batch tool names, flush periodically + _BATCH_SIZE = 5 + _batch: List[str] = [] + + def _callback(event_type: str, tool_name: str = None, preview: str = None, args=None, **kwargs): + # event_type is one of: "tool.started", "tool.completed", + # "reasoning.available", "_thinking", "subagent_progress" + + # "_thinking" / reasoning events + if event_type in ("_thinking", "reasoning.available"): + text = preview or tool_name or "" + if spinner: + short = (text[:55] + "...") if len(text) > 55 else text + try: + spinner.print_above(f" {prefix}├─ 💭 \"{short}\"") + except Exception as e: + logger.debug("Spinner print_above failed: %s", e) + # Don't relay thinking to gateway (too noisy for chat) + return + + # tool.completed — no display needed here (spinner shows on started) + if event_type == "tool.completed": + return + + # tool.started — display and batch for parent relay + if spinner: + short = (preview[:35] + "...") if preview and len(preview) > 35 else (preview or "") + from agent.display import get_tool_emoji + emoji = get_tool_emoji(tool_name or "") + line = f" {prefix}├─ {emoji} {tool_name}" + if short: + line += f" \"{short}\"" + try: + spinner.print_above(line) + except Exception as e: + logger.debug("Spinner print_above failed: %s", e) + + if parent_cb: + _batch.append(tool_name or "") + if len(_batch) >= _BATCH_SIZE: + summary = ", ".join(_batch) + try: + parent_cb("subagent_progress", f"🔀 {prefix}{summary}") + except Exception as e: + logger.debug("Parent callback failed: %s", e) + _batch.clear() + + def _flush(): + """Flush remaining batched tool names to gateway on completion.""" + if parent_cb and _batch: + summary = ", ".join(_batch) + try: + parent_cb("subagent_progress", f"🔀 {prefix}{summary}") + except Exception as e: + logger.debug("Parent callback flush failed: %s", e) + _batch.clear() + + _callback._flush = _flush + return _callback + + +def _build_child_agent( + task_index: int, + goal: str, + context: Optional[str], + toolsets: Optional[List[str]], + model: Optional[str], + max_iterations: int, + parent_agent, + # Credential overrides from delegation config (provider:model resolution) + override_provider: Optional[str] = None, + override_base_url: Optional[str] = None, + override_api_key: Optional[str] = None, + override_api_mode: Optional[str] = None, + # ACP transport overrides — lets a non-ACP parent spawn ACP child agents + override_acp_command: Optional[str] = None, + override_acp_args: Optional[List[str]] = None, +): + """ + Build a child AIAgent on the main thread (thread-safe construction). + Returns the constructed child agent without running it. + + When override_* params are set (from delegation config), the child uses + those credentials instead of inheriting from the parent. This enables + routing subagents to a different provider:model pair (e.g. cheap/fast + model on OpenRouter while the parent runs on Nous Portal). + """ + from run_agent import AIAgent + + # When no explicit toolsets given, inherit from parent's enabled toolsets + # so disabled tools (e.g. web) don't leak to subagents. + # Note: enabled_toolsets=None means "all tools enabled" (the default), + # so we must derive effective toolsets from the parent's loaded tools. + parent_enabled = getattr(parent_agent, "enabled_toolsets", None) + if parent_enabled is not None: + parent_toolsets = set(parent_enabled) + elif parent_agent and hasattr(parent_agent, "valid_tool_names"): + # enabled_toolsets is None (all tools) — derive from loaded tool names + import model_tools + parent_toolsets = { + ts for name in parent_agent.valid_tool_names + if (ts := model_tools.get_toolset_for_tool(name)) is not None + } + else: + parent_toolsets = set(DEFAULT_TOOLSETS) + + if toolsets: + # Intersect with parent — subagent must not gain tools the parent lacks + child_toolsets = _strip_blocked_tools([t for t in toolsets if t in parent_toolsets]) + elif parent_agent and parent_enabled is not None: + child_toolsets = _strip_blocked_tools(parent_enabled) + elif parent_toolsets: + child_toolsets = _strip_blocked_tools(sorted(parent_toolsets)) + else: + child_toolsets = _strip_blocked_tools(DEFAULT_TOOLSETS) + + workspace_hint = _resolve_workspace_hint(parent_agent) + child_prompt = _build_child_system_prompt(goal, context, workspace_path=workspace_hint) + # Extract parent's API key so subagents inherit auth (e.g. Nous Portal). + parent_api_key = getattr(parent_agent, "api_key", None) + if (not parent_api_key) and hasattr(parent_agent, "_client_kwargs"): + parent_api_key = parent_agent._client_kwargs.get("api_key") + + # Build progress callback to relay tool calls to parent display + child_progress_cb = _build_child_progress_callback(task_index, parent_agent) + + # Each subagent gets its own iteration budget capped at max_iterations + # (configurable via delegation.max_iterations, default 50). This means + # total iterations across parent + subagents can exceed the parent's + # max_iterations. The user controls the per-subagent cap in config.yaml. + + child_thinking_cb = None + if child_progress_cb: + def _child_thinking(text: str) -> None: + if not text: + return + try: + child_progress_cb("_thinking", text) + except Exception as e: + logger.debug("Child thinking callback relay failed: %s", e) + + child_thinking_cb = _child_thinking + + # Resolve effective credentials: config override > parent inherit + effective_model = model or parent_agent.model + effective_provider = override_provider or getattr(parent_agent, "provider", None) + effective_base_url = override_base_url or parent_agent.base_url + effective_api_key = override_api_key or parent_api_key + effective_api_mode = override_api_mode or getattr(parent_agent, "api_mode", None) + effective_acp_command = override_acp_command or getattr(parent_agent, "acp_command", None) + effective_acp_args = list(override_acp_args if override_acp_args is not None else (getattr(parent_agent, "acp_args", []) or [])) + + # Resolve reasoning config: delegation override > parent inherit + parent_reasoning = getattr(parent_agent, "reasoning_config", None) + child_reasoning = parent_reasoning + try: + delegation_cfg = _load_config() + delegation_effort = str(delegation_cfg.get("reasoning_effort") or "").strip() + if delegation_effort: + from hermes_constants import parse_reasoning_effort + parsed = parse_reasoning_effort(delegation_effort) + if parsed is not None: + child_reasoning = parsed + else: + logger.warning( + "Unknown delegation.reasoning_effort '%s', inheriting parent level", + delegation_effort, + ) + except Exception as exc: + logger.debug("Could not load delegation reasoning_effort: %s", exc) + + child = AIAgent( + base_url=effective_base_url, + api_key=effective_api_key, + model=effective_model, + provider=effective_provider, + api_mode=effective_api_mode, + acp_command=effective_acp_command, + acp_args=effective_acp_args, + max_iterations=max_iterations, + max_tokens=getattr(parent_agent, "max_tokens", None), + reasoning_config=child_reasoning, + prefill_messages=getattr(parent_agent, "prefill_messages", None), + enabled_toolsets=child_toolsets, + quiet_mode=True, + ephemeral_system_prompt=child_prompt, + log_prefix=f"[subagent-{task_index}]", + platform=parent_agent.platform, + skip_context_files=True, + skip_memory=True, + clarify_callback=None, + thinking_callback=child_thinking_cb, + session_db=getattr(parent_agent, '_session_db', None), + parent_session_id=getattr(parent_agent, 'session_id', None), + providers_allowed=parent_agent.providers_allowed, + providers_ignored=parent_agent.providers_ignored, + providers_order=parent_agent.providers_order, + provider_sort=parent_agent.provider_sort, + tool_progress_callback=child_progress_cb, + iteration_budget=None, # fresh budget per subagent + ) + child._print_fn = getattr(parent_agent, '_print_fn', None) + # Set delegation depth so children can't spawn grandchildren + child._delegate_depth = getattr(parent_agent, '_delegate_depth', 0) + 1 + + # Share a credential pool with the child when possible so subagents can + # rotate credentials on rate limits instead of getting pinned to one key. + child_pool = _resolve_child_credential_pool(effective_provider, parent_agent) + if child_pool is not None: + child._credential_pool = child_pool + + # Register child for interrupt propagation + if hasattr(parent_agent, '_active_children'): + lock = getattr(parent_agent, '_active_children_lock', None) + if lock: + with lock: + parent_agent._active_children.append(child) + else: + parent_agent._active_children.append(child) + + return child + +def _run_single_child( + task_index: int, + goal: str, + child=None, + parent_agent=None, + **_kwargs, +) -> Dict[str, Any]: + """ + Run a pre-built child agent. Called from within a thread. + Returns a structured result dict. + """ + child_start = time.monotonic() + + # Get the progress callback from the child agent + child_progress_cb = getattr(child, 'tool_progress_callback', None) + + # Restore parent tool names using the value saved before child construction + # mutated the global. This is the correct parent toolset, not the child's. + import model_tools + _saved_tool_names = getattr(child, "_delegate_saved_tool_names", + list(model_tools._last_resolved_tool_names)) + + child_pool = getattr(child, '_credential_pool', None) + leased_cred_id = None + if child_pool is not None: + leased_cred_id = child_pool.acquire_lease() + if leased_cred_id is not None: + try: + leased_entry = child_pool.current() + if leased_entry is not None and hasattr(child, '_swap_credential'): + child._swap_credential(leased_entry) + except Exception as exc: + logger.debug("Failed to bind child to leased credential: %s", exc) + + # Heartbeat: periodically propagate child activity to the parent so the + # gateway inactivity timeout doesn't fire while the subagent is working. + # Without this, the parent's _last_activity_ts freezes when delegate_task + # starts and the gateway eventually kills the agent for "no activity". + _heartbeat_stop = threading.Event() + + def _heartbeat_loop(): + while not _heartbeat_stop.wait(_HEARTBEAT_INTERVAL): + if parent_agent is None: + continue + touch = getattr(parent_agent, '_touch_activity', None) + if not touch: + continue + # Pull detail from the child's own activity tracker + desc = f"delegate_task: subagent {task_index} working" + try: + child_summary = child.get_activity_summary() + child_tool = child_summary.get("current_tool") + child_iter = child_summary.get("api_call_count", 0) + child_max = child_summary.get("max_iterations", 0) + if child_tool: + desc = (f"delegate_task: subagent running {child_tool} " + f"(iteration {child_iter}/{child_max})") + else: + child_desc = child_summary.get("last_activity_desc", "") + if child_desc: + desc = (f"delegate_task: subagent {child_desc} " + f"(iteration {child_iter}/{child_max})") + except Exception: + pass + try: + touch(desc) + except Exception: + pass + + _heartbeat_thread = threading.Thread(target=_heartbeat_loop, daemon=True) + _heartbeat_thread.start() + + try: + result = child.run_conversation(user_message=goal) + + # Flush any remaining batched progress to gateway + if child_progress_cb and hasattr(child_progress_cb, '_flush'): + try: + child_progress_cb._flush() + except Exception as e: + logger.debug("Progress callback flush failed: %s", e) + + duration = round(time.monotonic() - child_start, 2) + + summary = result.get("final_response") or "" + completed = result.get("completed", False) + interrupted = result.get("interrupted", False) + api_calls = result.get("api_calls", 0) + + if interrupted: + status = "interrupted" + elif summary: + # A summary means the subagent produced usable output. + # exit_reason ("completed" vs "max_iterations") already + # tells the parent *how* the task ended. + status = "completed" + else: + status = "failed" + + # Build tool trace from conversation messages (already in memory). + # Uses tool_call_id to correctly pair parallel tool calls with results. + tool_trace: list[Dict[str, Any]] = [] + trace_by_id: Dict[str, Dict[str, Any]] = {} + messages = result.get("messages") or [] + if isinstance(messages, list): + for msg in messages: + if not isinstance(msg, dict): + continue + if msg.get("role") == "assistant": + for tc in (msg.get("tool_calls") or []): + fn = tc.get("function", {}) + entry_t = { + "tool": fn.get("name", "unknown"), + "args_bytes": len(fn.get("arguments", "")), + } + tool_trace.append(entry_t) + tc_id = tc.get("id") + if tc_id: + trace_by_id[tc_id] = entry_t + elif msg.get("role") == "tool": + content = msg.get("content", "") + is_error = bool( + content and "error" in content[:80].lower() + ) + result_meta = { + "result_bytes": len(content), + "status": "error" if is_error else "ok", + } + # Match by tool_call_id for parallel calls + tc_id = msg.get("tool_call_id") + target = trace_by_id.get(tc_id) if tc_id else None + if target is not None: + target.update(result_meta) + elif tool_trace: + # Fallback for messages without tool_call_id + tool_trace[-1].update(result_meta) + + # Determine exit reason + if interrupted: + exit_reason = "interrupted" + elif completed: + exit_reason = "completed" + else: + exit_reason = "max_iterations" + + # Extract token counts (safe for mock objects) + _input_tokens = getattr(child, "session_prompt_tokens", 0) + _output_tokens = getattr(child, "session_completion_tokens", 0) + _model = getattr(child, "model", None) + + entry: Dict[str, Any] = { + "task_index": task_index, + "status": status, + "summary": summary, + "api_calls": api_calls, + "duration_seconds": duration, + "model": _model if isinstance(_model, str) else None, + "exit_reason": exit_reason, + "tokens": { + "input": _input_tokens if isinstance(_input_tokens, (int, float)) else 0, + "output": _output_tokens if isinstance(_output_tokens, (int, float)) else 0, + }, + "tool_trace": tool_trace, + } + if status == "failed": + entry["error"] = result.get("error", "Subagent did not produce a response.") + + return entry + + except Exception as exc: + duration = round(time.monotonic() - child_start, 2) + logging.exception(f"[subagent-{task_index}] failed") + return { + "task_index": task_index, + "status": "error", + "summary": None, + "error": str(exc), + "api_calls": 0, + "duration_seconds": duration, + } + + finally: + # Stop the heartbeat thread so it doesn't keep touching parent activity + # after the child has finished (or failed). + _heartbeat_stop.set() + _heartbeat_thread.join(timeout=5) + + if child_pool is not None and leased_cred_id is not None: + try: + child_pool.release_lease(leased_cred_id) + except Exception as exc: + logger.debug("Failed to release credential lease: %s", exc) + + # Restore the parent's tool names so the process-global is correct + # for any subsequent execute_code calls or other consumers. + import model_tools + + saved_tool_names = getattr(child, "_delegate_saved_tool_names", None) + if isinstance(saved_tool_names, list): + model_tools._last_resolved_tool_names = list(saved_tool_names) + + # Remove child from active tracking + + # Unregister child from interrupt propagation + if hasattr(parent_agent, '_active_children'): + try: + lock = getattr(parent_agent, '_active_children_lock', None) + if lock: + with lock: + parent_agent._active_children.remove(child) + else: + parent_agent._active_children.remove(child) + except (ValueError, UnboundLocalError) as e: + logger.debug("Could not remove child from active_children: %s", e) + + # Close tool resources (terminal sandboxes, browser daemons, + # background processes, httpx clients) so subagent subprocesses + # don't outlive the delegation. + try: + if hasattr(child, 'close'): + child.close() + except Exception: + logger.debug("Failed to close child agent after delegation") + +def delegate_task( + goal: Optional[str] = None, + context: Optional[str] = None, + toolsets: Optional[List[str]] = None, + tasks: Optional[List[Dict[str, Any]]] = None, + max_iterations: Optional[int] = None, + acp_command: Optional[str] = None, + acp_args: Optional[List[str]] = None, + parent_agent=None, +) -> str: + """ + Spawn one or more child agents to handle delegated tasks. + + Supports two modes: + - Single: provide goal (+ optional context, toolsets) + - Batch: provide tasks array [{goal, context, toolsets}, ...] + + Returns JSON with results array, one entry per task. + """ + if parent_agent is None: + return tool_error("delegate_task requires a parent agent context.") + + # Depth limit + depth = getattr(parent_agent, '_delegate_depth', 0) + if depth >= MAX_DEPTH: + return json.dumps({ + "error": ( + f"Delegation depth limit reached ({MAX_DEPTH}). " + "Subagents cannot spawn further subagents." + ) + }) + + # Load config + cfg = _load_config() + default_max_iter = cfg.get("max_iterations", DEFAULT_MAX_ITERATIONS) + effective_max_iter = max_iterations or default_max_iter + + # Resolve delegation credentials (provider:model pair). + # When delegation.provider is configured, this resolves the full credential + # bundle (base_url, api_key, api_mode) via the same runtime provider system + # used by CLI/gateway startup. When unconfigured, returns None values so + # children inherit from the parent. + try: + creds = _resolve_delegation_credentials(cfg, parent_agent) + except ValueError as exc: + return tool_error(str(exc)) + + # Normalize to task list + max_children = _get_max_concurrent_children() + if tasks and isinstance(tasks, list): + if len(tasks) > max_children: + return tool_error( + f"Too many tasks: {len(tasks)} provided, but " + f"max_concurrent_children is {max_children}. " + f"Either reduce the task count, split into multiple " + f"delegate_task calls, or increase " + f"delegation.max_concurrent_children in config.yaml." + ) + task_list = tasks + elif goal and isinstance(goal, str) and goal.strip(): + task_list = [{"goal": goal, "context": context, "toolsets": toolsets}] + else: + return tool_error("Provide either 'goal' (single task) or 'tasks' (batch).") + + if not task_list: + return tool_error("No tasks provided.") + + # Validate each task has a goal + for i, task in enumerate(task_list): + if not task.get("goal", "").strip(): + return tool_error(f"Task {i} is missing a 'goal'.") + + overall_start = time.monotonic() + results = [] + + n_tasks = len(task_list) + # Track goal labels for progress display (truncated for readability) + task_labels = [t["goal"][:40] for t in task_list] + + # Save parent tool names BEFORE any child construction mutates the global. + # _build_child_agent() calls AIAgent() which calls get_tool_definitions(), + # which overwrites model_tools._last_resolved_tool_names with child's toolset. + import model_tools as _model_tools + _parent_tool_names = list(_model_tools._last_resolved_tool_names) + + # Build all child agents on the main thread (thread-safe construction) + # Wrapped in try/finally so the global is always restored even if a + # child build raises (otherwise _last_resolved_tool_names stays corrupted). + children = [] + try: + for i, t in enumerate(task_list): + child = _build_child_agent( + task_index=i, goal=t["goal"], context=t.get("context"), + toolsets=t.get("toolsets") or toolsets, model=creds["model"], + max_iterations=effective_max_iter, parent_agent=parent_agent, + override_provider=creds["provider"], override_base_url=creds["base_url"], + override_api_key=creds["api_key"], + override_api_mode=creds["api_mode"], + override_acp_command=t.get("acp_command") or acp_command, + override_acp_args=t.get("acp_args") or acp_args, + ) + # Override with correct parent tool names (before child construction mutated global) + child._delegate_saved_tool_names = _parent_tool_names + children.append((i, t, child)) + finally: + # Authoritative restore: reset global to parent's tool names after all children built + _model_tools._last_resolved_tool_names = _parent_tool_names + + if n_tasks == 1: + # Single task -- run directly (no thread pool overhead) + _i, _t, child = children[0] + result = _run_single_child(0, _t["goal"], child, parent_agent) + results.append(result) + else: + # Batch -- run in parallel with per-task progress lines + completed_count = 0 + spinner_ref = getattr(parent_agent, '_delegate_spinner', None) + + with ThreadPoolExecutor(max_workers=max_children) as executor: + futures = {} + for i, t, child in children: + future = executor.submit( + _run_single_child, + task_index=i, + goal=t["goal"], + child=child, + parent_agent=parent_agent, + ) + futures[future] = i + + for future in as_completed(futures): + try: + entry = future.result() + except Exception as exc: + idx = futures[future] + entry = { + "task_index": idx, + "status": "error", + "summary": None, + "error": str(exc), + "api_calls": 0, + "duration_seconds": 0, + } + results.append(entry) + completed_count += 1 + + # Print per-task completion line above the spinner + idx = entry["task_index"] + label = task_labels[idx] if idx < len(task_labels) else f"Task {idx}" + dur = entry.get("duration_seconds", 0) + status = entry.get("status", "?") + icon = "✓" if status == "completed" else "✗" + remaining = n_tasks - completed_count + completion_line = f"{icon} [{idx+1}/{n_tasks}] {label} ({dur}s)" + if spinner_ref: + try: + spinner_ref.print_above(completion_line) + except Exception: + print(f" {completion_line}") + else: + print(f" {completion_line}") + + # Update spinner text to show remaining count + if spinner_ref and remaining > 0: + try: + spinner_ref.update_text(f"🔀 {remaining} task{'s' if remaining != 1 else ''} remaining") + except Exception as e: + logger.debug("Spinner update_text failed: %s", e) + + # Sort by task_index so results match input order + results.sort(key=lambda r: r["task_index"]) + + # Notify parent's memory provider of delegation outcomes + if parent_agent and hasattr(parent_agent, '_memory_manager') and parent_agent._memory_manager: + for entry in results: + try: + _task_goal = task_list[entry["task_index"]]["goal"] if entry["task_index"] < len(task_list) else "" + parent_agent._memory_manager.on_delegation( + task=_task_goal, + result=entry.get("summary", "") or "", + child_session_id=getattr(children[entry["task_index"]][2], "session_id", "") if entry["task_index"] < len(children) else "", + ) + except Exception: + pass + + total_duration = round(time.monotonic() - overall_start, 2) + + return json.dumps({ + "results": results, + "total_duration_seconds": total_duration, + }, ensure_ascii=False) + + +def _resolve_child_credential_pool(effective_provider: Optional[str], parent_agent): + """Resolve a credential pool for the child agent. + + Rules: + 1. Same provider as the parent -> share the parent's pool so cooldown state + and rotation stay synchronized. + 2. Different provider -> try to load that provider's own pool. + 3. No pool available -> return None and let the child keep the inherited + fixed credential behavior. + """ + if not effective_provider: + return getattr(parent_agent, "_credential_pool", None) + + parent_provider = getattr(parent_agent, "provider", None) or "" + parent_pool = getattr(parent_agent, "_credential_pool", None) + if parent_pool is not None and effective_provider == parent_provider: + return parent_pool + + try: + from agent.credential_pool import load_pool + pool = load_pool(effective_provider) + if pool is not None and pool.has_credentials(): + return pool + except Exception as exc: + logger.debug( + "Could not load credential pool for child provider '%s': %s", + effective_provider, + exc, + ) + return None + + +def _resolve_delegation_credentials(cfg: dict, parent_agent) -> dict: + """Resolve credentials for subagent delegation. + + If ``delegation.base_url`` is configured, subagents use that direct + OpenAI-compatible endpoint. Otherwise, if ``delegation.provider`` is + configured, the full credential bundle (base_url, api_key, api_mode, + provider) is resolved via the runtime provider system — the same path used + by CLI/gateway startup. This lets subagents run on a completely different + provider:model pair. + + If neither base_url nor provider is configured, returns None values so the + child inherits everything from the parent agent. + + Raises ValueError with a user-friendly message on credential failure. + """ + configured_model = str(cfg.get("model") or "").strip() or None + configured_provider = str(cfg.get("provider") or "").strip() or None + configured_base_url = str(cfg.get("base_url") or "").strip() or None + configured_api_key = str(cfg.get("api_key") or "").strip() or None + + if configured_base_url: + api_key = ( + configured_api_key + or os.getenv("OPENAI_API_KEY", "").strip() + ) + if not api_key: + raise ValueError( + "Delegation base_url is configured but no API key was found. " + "Set delegation.api_key or OPENAI_API_KEY." + ) + + base_lower = configured_base_url.lower() + provider = "custom" + api_mode = "chat_completions" + if "chatgpt.com/backend-api/codex" in base_lower: + provider = "openai-codex" + api_mode = "codex_responses" + elif "api.anthropic.com" in base_lower: + provider = "anthropic" + api_mode = "anthropic_messages" + + return { + "model": configured_model, + "provider": provider, + "base_url": configured_base_url, + "api_key": api_key, + "api_mode": api_mode, + } + + if not configured_provider: + # No provider override — child inherits everything from parent + return { + "model": configured_model, + "provider": None, + "base_url": None, + "api_key": None, + "api_mode": None, + } + + # Provider is configured — resolve full credentials + try: + from hermes_cli.runtime_provider import resolve_runtime_provider + runtime = resolve_runtime_provider(requested=configured_provider) + except Exception as exc: + raise ValueError( + f"Cannot resolve delegation provider '{configured_provider}': {exc}. " + f"Check that the provider is configured (API key set, valid provider name), " + f"or set delegation.base_url/delegation.api_key for a direct endpoint. " + f"Available providers: openrouter, nous, zai, kimi-coding, minimax." + ) from exc + + api_key = runtime.get("api_key", "") + if not api_key: + raise ValueError( + f"Delegation provider '{configured_provider}' resolved but has no API key. " + f"Set the appropriate environment variable or run 'hermes auth'." + ) + + return { + "model": configured_model, + "provider": runtime.get("provider"), + "base_url": runtime.get("base_url"), + "api_key": api_key, + "api_mode": runtime.get("api_mode"), + "command": runtime.get("command"), + "args": list(runtime.get("args") or []), + } + + +def _load_config() -> dict: + """Load delegation config from CLI_CONFIG or persistent config. + + Checks the runtime config (cli.py CLI_CONFIG) first, then falls back + to the persistent config (hermes_cli/config.py load_config()) so that + ``delegation.model`` / ``delegation.provider`` are picked up regardless + of the entry point (CLI, gateway, cron). + """ + try: + from cli import CLI_CONFIG + cfg = CLI_CONFIG.get("delegation", {}) + if cfg: + return cfg + except Exception: + pass + try: + from hermes_cli.config import load_config + full = load_config() + return full.get("delegation", {}) + except Exception: + return {} + + +# --------------------------------------------------------------------------- +# OpenAI Function-Calling Schema +# --------------------------------------------------------------------------- + +DELEGATE_TASK_SCHEMA = { + "name": "delegate_task", + "description": ( + "Spawn one or more subagents to work on tasks in isolated contexts. " + "Each subagent gets its own conversation, terminal session, and toolset. " + "Only the final summary is returned -- intermediate tool results " + "never enter your context window.\n\n" + "TWO MODES (one of 'goal' or 'tasks' is required):\n" + "1. Single task: provide 'goal' (+ optional context, toolsets)\n" + "2. Batch (parallel): provide 'tasks' array with up to 3 items. " + "All run concurrently and results are returned together.\n\n" + "WHEN TO USE delegate_task:\n" + "- Reasoning-heavy subtasks (debugging, code review, research synthesis)\n" + "- Tasks that would flood your context with intermediate data\n" + "- Parallel independent workstreams (research A and B simultaneously)\n\n" + "WHEN NOT TO USE (use these instead):\n" + "- Mechanical multi-step work with no reasoning needed -> use execute_code\n" + "- Single tool call -> just call the tool directly\n" + "- Tasks needing user interaction -> subagents cannot use clarify\n\n" + "IMPORTANT:\n" + "- Subagents have NO memory of your conversation. Pass all relevant " + "info (file paths, error messages, constraints) via the 'context' field.\n" + "- Subagents CANNOT call: delegate_task, clarify, memory, send_message, " + "execute_code.\n" + "- Each subagent gets its own terminal session (separate working directory and state).\n" + "- Results are always returned as an array, one entry per task." + ), + "parameters": { + "type": "object", + "properties": { + "goal": { + "type": "string", + "description": ( + "What the subagent should accomplish. Be specific and " + "self-contained -- the subagent knows nothing about your " + "conversation history." + ), + }, + "context": { + "type": "string", + "description": ( + "Background information the subagent needs: file paths, " + "error messages, project structure, constraints. The more " + "specific you are, the better the subagent performs." + ), + }, + "toolsets": { + "type": "array", + "items": {"type": "string"}, + "description": ( + "Toolsets to enable for this subagent. " + "Default: inherits your enabled toolsets. " + f"Available toolsets: {_TOOLSET_LIST_STR}. " + "Common patterns: ['terminal', 'file'] for code work, " + "['web'] for research, ['browser'] for web interaction, " + "['terminal', 'file', 'web'] for full-stack tasks." + ), + }, + "tasks": { + "type": "array", + "items": { + "type": "object", + "properties": { + "goal": {"type": "string", "description": "Task goal"}, + "context": {"type": "string", "description": "Task-specific context"}, + "toolsets": { + "type": "array", + "items": {"type": "string"}, + "description": f"Toolsets for this specific task. Available: {_TOOLSET_LIST_STR}. Use 'web' for network access, 'terminal' for shell, 'browser' for web interaction.", + }, + "acp_command": { + "type": "string", + "description": "Per-task ACP command override (e.g. 'claude'). Overrides the top-level acp_command for this task only.", + }, + "acp_args": { + "type": "array", + "items": {"type": "string"}, + "description": "Per-task ACP args override.", + }, + }, + "required": ["goal"], + }, + # No maxItems — the runtime limit is configurable via + # delegation.max_concurrent_children (default 3) and + # enforced with a clear error in delegate_task(). + "description": ( + "Batch mode: tasks to run in parallel (limit configurable via delegation.max_concurrent_children, default 3). Each gets " + "its own subagent with isolated context and terminal session. " + "When provided, top-level goal/context/toolsets are ignored." + ), + }, + "max_iterations": { + "type": "integer", + "description": ( + "Max tool-calling turns per subagent (default: 50). " + "Only set lower for simple tasks." + ), + }, + "acp_command": { + "type": "string", + "description": ( + "Override ACP command for child agents (e.g. 'claude', 'copilot'). " + "When set, children use ACP subprocess transport instead of inheriting " + "the parent's transport. Enables spawning Claude Code (claude --acp --stdio) " + "or other ACP-capable agents from any parent, including Discord/Telegram/CLI." + ), + }, + "acp_args": { + "type": "array", + "items": {"type": "string"}, + "description": ( + "Arguments for the ACP command (default: ['--acp', '--stdio']). " + "Only used when acp_command is set. Example: ['--acp', '--stdio', '--model', 'claude-opus-4-6']" + ), + }, + }, + "required": [], + }, +} + + +# --- Registry --- +from tools.registry import registry, tool_error + +registry.register( + name="delegate_task", + toolset="delegation", + schema=DELEGATE_TASK_SCHEMA, + handler=lambda args, **kw: delegate_task( + goal=args.get("goal"), + context=args.get("context"), + toolsets=args.get("toolsets"), + tasks=args.get("tasks"), + max_iterations=args.get("max_iterations"), + acp_command=args.get("acp_command"), + acp_args=args.get("acp_args"), + parent_agent=kw.get("parent_agent")), + check_fn=check_delegate_requirements, + emoji="🔀", +) diff --git a/mindcli/_vendor/tools/env_passthrough.py b/mindcli/_vendor/tools/env_passthrough.py new file mode 100644 index 0000000..b4686cb --- /dev/null +++ b/mindcli/_vendor/tools/env_passthrough.py @@ -0,0 +1,101 @@ +"""Environment variable passthrough registry. + +Skills that declare ``required_environment_variables`` in their frontmatter +need those vars available in sandboxed execution environments (execute_code, +terminal). By default both sandboxes strip secrets from the child process +environment for security. This module provides a session-scoped allowlist +so skill-declared vars (and user-configured overrides) pass through. + +Two sources feed the allowlist: + +1. **Skill declarations** — when a skill is loaded via ``skill_view``, its + ``required_environment_variables`` are registered here automatically. +2. **User config** — ``terminal.env_passthrough`` in config.yaml lets users + explicitly allowlist vars for non-skill use cases. + +Both ``code_execution_tool.py`` and ``tools/environments/local.py`` consult +:func:`is_env_passthrough` before stripping a variable. +""" + +from __future__ import annotations + +import logging +from contextvars import ContextVar +from typing import Iterable + +logger = logging.getLogger(__name__) + +# Session-scoped set of env var names that should pass through to sandboxes. +# Backed by ContextVar to prevent cross-session data bleed in the gateway pipeline. +_allowed_env_vars_var: ContextVar[set[str]] = ContextVar("_allowed_env_vars") + + +def _get_allowed() -> set[str]: + """Get or create the allowed env vars set for the current context/session.""" + try: + return _allowed_env_vars_var.get() + except LookupError: + val: set[str] = set() + _allowed_env_vars_var.set(val) + return val + + +# Cache for the config-based allowlist (loaded once per process). +_config_passthrough: frozenset[str] | None = None + + +def register_env_passthrough(var_names: Iterable[str]) -> None: + """Register environment variable names as allowed in sandboxed environments. + + Typically called when a skill declares ``required_environment_variables``. + """ + for name in var_names: + name = name.strip() + if name: + _get_allowed().add(name) + logger.debug("env passthrough: registered %s", name) + + +def _load_config_passthrough() -> frozenset[str]: + """Load ``tools.env_passthrough`` from config.yaml (cached).""" + global _config_passthrough + if _config_passthrough is not None: + return _config_passthrough + + result: set[str] = set() + try: + from hermes_cli.config import read_raw_config + cfg = read_raw_config() + passthrough = cfg.get("terminal", {}).get("env_passthrough") + if isinstance(passthrough, list): + for item in passthrough: + if isinstance(item, str) and item.strip(): + result.add(item.strip()) + except Exception as e: + logger.debug("Could not read tools.env_passthrough from config: %s", e) + + _config_passthrough = frozenset(result) + return _config_passthrough + + +def is_env_passthrough(var_name: str) -> bool: + """Check whether *var_name* is allowed to pass through to sandboxes. + + Returns ``True`` if the variable was registered by a skill or listed in + the user's ``tools.env_passthrough`` config. + """ + if var_name in _get_allowed(): + return True + return var_name in _load_config_passthrough() + + +def get_all_passthrough() -> frozenset[str]: + """Return the union of skill-registered and config-based passthrough vars.""" + return frozenset(_get_allowed()) | _load_config_passthrough() + + +def clear_env_passthrough() -> None: + """Reset the skill-scoped allowlist (e.g. on session reset).""" + _get_allowed().clear() + + diff --git a/mindcli/_vendor/tools/environments/__init__.py b/mindcli/_vendor/tools/environments/__init__.py new file mode 100644 index 0000000..7ffcce1 --- /dev/null +++ b/mindcli/_vendor/tools/environments/__init__.py @@ -0,0 +1,13 @@ +"""Hermes execution environment backends. + +Each backend provides the same interface (BaseEnvironment ABC) for running +shell commands in a specific execution context: local, Docker, Singularity, +SSH, Modal, or Daytona. + +The terminal_tool.py factory (_create_environment) selects the backend +based on the TERMINAL_ENV configuration. +""" + +from tools.environments.base import BaseEnvironment + +__all__ = ["BaseEnvironment"] diff --git a/mindcli/_vendor/tools/environments/base.py b/mindcli/_vendor/tools/environments/base.py new file mode 100644 index 0000000..19c3bf0 --- /dev/null +++ b/mindcli/_vendor/tools/environments/base.py @@ -0,0 +1,579 @@ +"""Base class for all Hermes execution environment backends. + +Unified spawn-per-call model: every command spawns a fresh ``bash -c`` process. +A session snapshot (env vars, functions, aliases) is captured once at init and +re-sourced before each command. CWD persists via in-band stdout markers (remote) +or a temp file (local). +""" + +import json +import logging +import os +import shlex +import subprocess +import threading +import time +import uuid +from abc import ABC, abstractmethod +from pathlib import Path +from typing import IO, Callable, Protocol + +from hermes_constants import get_hermes_home +from tools.interrupt import is_interrupted + +logger = logging.getLogger(__name__) + +# Thread-local activity callback. The agent sets this before a tool call so +# long-running _wait_for_process loops can report liveness to the gateway. +_activity_callback_local = threading.local() + + +def set_activity_callback(cb: Callable[[str], None] | None) -> None: + """Register a callback that _wait_for_process fires periodically.""" + _activity_callback_local.callback = cb + + +def _get_activity_callback() -> Callable[[str], None] | None: + return getattr(_activity_callback_local, "callback", None) + + +def get_sandbox_dir() -> Path: + """Return the host-side root for all sandbox storage (Docker workspaces, + Singularity overlays/SIF cache, etc.). + + Configurable via TERMINAL_SANDBOX_DIR. Defaults to {HERMES_HOME}/sandboxes/. + """ + custom = os.getenv("TERMINAL_SANDBOX_DIR") + if custom: + p = Path(custom) + else: + p = get_hermes_home() / "sandboxes" + p.mkdir(parents=True, exist_ok=True) + return p + + +# --------------------------------------------------------------------------- +# Shared constants and utilities +# --------------------------------------------------------------------------- + + +def _pipe_stdin(proc: subprocess.Popen, data: str) -> None: + """Write *data* to proc.stdin on a daemon thread to avoid pipe-buffer deadlocks.""" + + def _write(): + try: + proc.stdin.write(data) + proc.stdin.close() + except (BrokenPipeError, OSError): + pass + + threading.Thread(target=_write, daemon=True).start() + + +def _popen_bash( + cmd: list[str], stdin_data: str | None = None, **kwargs +) -> subprocess.Popen: + """Spawn a subprocess with standard stdout/stderr/stdin setup. + + If *stdin_data* is provided, writes it asynchronously via :func:`_pipe_stdin`. + Backends with special Popen needs (e.g. local's ``preexec_fn``) can bypass + this and call :func:`_pipe_stdin` directly. + """ + proc = subprocess.Popen( + cmd, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + stdin=subprocess.PIPE if stdin_data is not None else subprocess.DEVNULL, + text=True, + **kwargs, + ) + if stdin_data is not None: + _pipe_stdin(proc, stdin_data) + return proc + + +def _load_json_store(path: Path) -> dict: + """Load a JSON file as a dict, returning ``{}`` on any error.""" + if path.exists(): + try: + return json.loads(path.read_text()) + except Exception: + pass + return {} + + +def _save_json_store(path: Path, data: dict) -> None: + """Write *data* as pretty-printed JSON to *path*.""" + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(json.dumps(data, indent=2)) + + +def _file_mtime_key(host_path: str) -> tuple[float, int] | None: + """Return ``(mtime, size)`` for cache comparison, or ``None`` if unreadable.""" + try: + st = Path(host_path).stat() + return (st.st_mtime, st.st_size) + except OSError: + return None + + +# --------------------------------------------------------------------------- +# ProcessHandle protocol +# --------------------------------------------------------------------------- + + +class ProcessHandle(Protocol): + """Duck type that every backend's _run_bash() must return. + + subprocess.Popen satisfies this natively. SDK backends (Modal, Daytona) + return _ThreadedProcessHandle which adapts their blocking calls. + """ + + def poll(self) -> int | None: ... + def kill(self) -> None: ... + def wait(self, timeout: float | None = None) -> int: ... + + @property + def stdout(self) -> IO[str] | None: ... + + @property + def returncode(self) -> int | None: ... + + +class _ThreadedProcessHandle: + """Adapter for SDK backends (Modal, Daytona) that have no real subprocess. + + Wraps a blocking ``exec_fn() -> (output_str, exit_code)`` in a background + thread and exposes a ProcessHandle-compatible interface. An optional + ``cancel_fn`` is invoked on ``kill()`` for backend-specific cancellation + (e.g. Modal sandbox.terminate, Daytona sandbox.stop). + """ + + def __init__( + self, + exec_fn: Callable[[], tuple[str, int]], + cancel_fn: Callable[[], None] | None = None, + ): + self._cancel_fn = cancel_fn + self._done = threading.Event() + self._returncode: int | None = None + self._error: Exception | None = None + + # Pipe for stdout — drain thread in _wait_for_process reads the read end. + read_fd, write_fd = os.pipe() + self._stdout = os.fdopen(read_fd, "r", encoding="utf-8", errors="replace") + self._write_fd = write_fd + + def _worker(): + try: + output, exit_code = exec_fn() + self._returncode = exit_code + # Write output into the pipe so drain thread picks it up. + try: + os.write(self._write_fd, output.encode("utf-8", errors="replace")) + except OSError: + pass + except Exception as exc: + self._error = exc + self._returncode = 1 + finally: + try: + os.close(self._write_fd) + except OSError: + pass + self._done.set() + + t = threading.Thread(target=_worker, daemon=True) + t.start() + + @property + def stdout(self): + return self._stdout + + @property + def returncode(self) -> int | None: + return self._returncode + + def poll(self) -> int | None: + return self._returncode if self._done.is_set() else None + + def kill(self): + if self._cancel_fn: + try: + self._cancel_fn() + except Exception: + pass + + def wait(self, timeout: float | None = None) -> int: + self._done.wait(timeout=timeout) + return self._returncode + + +# --------------------------------------------------------------------------- +# CWD marker for remote backends +# --------------------------------------------------------------------------- + + +def _cwd_marker(session_id: str) -> str: + return f"__HERMES_CWD_{session_id}__" + + +# --------------------------------------------------------------------------- +# BaseEnvironment +# --------------------------------------------------------------------------- + + +class BaseEnvironment(ABC): + """Common interface and unified execution flow for all Hermes backends. + + Subclasses implement ``_run_bash()`` and ``cleanup()``. The base class + provides ``execute()`` with session snapshot sourcing, CWD tracking, + interrupt handling, and timeout enforcement. + """ + + # Subclasses that embed stdin as a heredoc (Modal, Daytona) set this. + _stdin_mode: str = "pipe" # "pipe" or "heredoc" + + # Snapshot creation timeout (override for slow cold-starts). + _snapshot_timeout: int = 30 + + def get_temp_dir(self) -> str: + """Return the backend temp directory used for session artifacts. + + Most sandboxed backends use ``/tmp`` inside the target environment. + LocalEnvironment overrides this on platforms like Termux where ``/tmp`` + may be missing and ``TMPDIR`` is the portable writable location. + """ + return "/tmp" + + def __init__(self, cwd: str, timeout: int, env: dict = None): + self.cwd = cwd + self.timeout = timeout + self.env = env or {} + + self._session_id = uuid.uuid4().hex[:12] + temp_dir = self.get_temp_dir().rstrip("/") or "/" + self._snapshot_path = f"{temp_dir}/hermes-snap-{self._session_id}.sh" + self._cwd_file = f"{temp_dir}/hermes-cwd-{self._session_id}.txt" + self._cwd_marker = _cwd_marker(self._session_id) + self._snapshot_ready = False + + # ------------------------------------------------------------------ + # Abstract methods + # ------------------------------------------------------------------ + + def _run_bash( + self, + cmd_string: str, + *, + login: bool = False, + timeout: int = 120, + stdin_data: str | None = None, + ) -> ProcessHandle: + """Spawn a bash process to run *cmd_string*. + + Returns a ProcessHandle (subprocess.Popen or _ThreadedProcessHandle). + Must be overridden by every backend. + """ + raise NotImplementedError(f"{type(self).__name__} must implement _run_bash()") + + @abstractmethod + def cleanup(self): + """Release backend resources (container, instance, connection).""" + ... + + # ------------------------------------------------------------------ + # Session snapshot (init_session) + # ------------------------------------------------------------------ + + def init_session(self): + """Capture login shell environment into a snapshot file. + + Called once after backend construction. On success, sets + ``_snapshot_ready = True`` so subsequent commands source the snapshot + instead of running with ``bash -l``. + """ + # Full capture: env vars, functions (filtered), aliases, shell options. + bootstrap = ( + f"export -p > {self._snapshot_path}\n" + f"declare -f | grep -vE '^_[^_]' >> {self._snapshot_path}\n" + f"alias -p >> {self._snapshot_path}\n" + f"echo 'shopt -s expand_aliases' >> {self._snapshot_path}\n" + f"echo 'set +e' >> {self._snapshot_path}\n" + f"echo 'set +u' >> {self._snapshot_path}\n" + f"pwd -P > {self._cwd_file} 2>/dev/null || true\n" + f"printf '\\n{self._cwd_marker}%s{self._cwd_marker}\\n' \"$(pwd -P)\"\n" + ) + try: + proc = self._run_bash(bootstrap, login=True, timeout=self._snapshot_timeout) + result = self._wait_for_process(proc, timeout=self._snapshot_timeout) + self._snapshot_ready = True + self._update_cwd(result) + logger.info( + "Session snapshot created (session=%s, cwd=%s)", + self._session_id, + self.cwd, + ) + except Exception as exc: + logger.warning( + "init_session failed (session=%s): %s — " + "falling back to bash -l per command", + self._session_id, + exc, + ) + self._snapshot_ready = False + + # ------------------------------------------------------------------ + # Command wrapping + # ------------------------------------------------------------------ + + def _wrap_command(self, command: str, cwd: str) -> str: + """Build the full bash script that sources snapshot, cd's, runs command, + re-dumps env vars, and emits CWD markers.""" + escaped = command.replace("'", "'\\''") + + parts = [] + + # Source snapshot (env vars from previous commands) + if self._snapshot_ready: + parts.append(f"source {self._snapshot_path} 2>/dev/null || true") + + # cd to working directory — let bash expand ~ natively + quoted_cwd = ( + shlex.quote(cwd) if cwd != "~" and not cwd.startswith("~/") else cwd + ) + parts.append(f"cd {quoted_cwd} || exit 126") + + # Run the actual command + parts.append(f"eval '{escaped}'") + parts.append("__hermes_ec=$?") + + # Re-dump env vars to snapshot (last-writer-wins for concurrent calls) + if self._snapshot_ready: + parts.append(f"export -p > {self._snapshot_path} 2>/dev/null || true") + + # Write CWD to file (local reads this) and stdout marker (remote parses this) + parts.append(f"pwd -P > {self._cwd_file} 2>/dev/null || true") + # Use a distinct line for the marker. The leading \n ensures + # the marker starts on its own line even if the command doesn't + # end with a newline (e.g. printf 'exact'). We'll strip this + # injected newline in _extract_cwd_from_output. + parts.append( + f"printf '\\n{self._cwd_marker}%s{self._cwd_marker}\\n' \"$(pwd -P)\"" + ) + parts.append("exit $__hermes_ec") + + return "\n".join(parts) + + # ------------------------------------------------------------------ + # Stdin heredoc embedding (for SDK backends) + # ------------------------------------------------------------------ + + @staticmethod + def _embed_stdin_heredoc(command: str, stdin_data: str) -> str: + """Append stdin_data as a shell heredoc to the command string.""" + delimiter = f"HERMES_STDIN_{uuid.uuid4().hex[:12]}" + return f"{command} << '{delimiter}'\n{stdin_data}\n{delimiter}" + + # ------------------------------------------------------------------ + # Process lifecycle + # ------------------------------------------------------------------ + + def _wait_for_process(self, proc: ProcessHandle, timeout: int = 120) -> dict: + """Poll-based wait with interrupt checking and stdout draining. + + Shared across all backends — not overridden. + + Fires the ``activity_callback`` (if set on this instance) every 10s + while the process is running so the gateway's inactivity timeout + doesn't kill long-running commands. + """ + output_chunks: list[str] = [] + + def _drain(): + try: + for line in proc.stdout: + output_chunks.append(line) + except UnicodeDecodeError: + output_chunks.clear() + output_chunks.append( + "[binary output detected — raw bytes not displayable]" + ) + except (ValueError, OSError): + pass + + drain_thread = threading.Thread(target=_drain, daemon=True) + drain_thread.start() + deadline = time.monotonic() + timeout + _last_activity_touch = time.monotonic() + _ACTIVITY_INTERVAL = 10.0 # seconds between activity touches + + while proc.poll() is None: + if is_interrupted(): + self._kill_process(proc) + drain_thread.join(timeout=2) + return { + "output": "".join(output_chunks) + "\n[Command interrupted]", + "returncode": 130, + } + if time.monotonic() > deadline: + self._kill_process(proc) + drain_thread.join(timeout=2) + partial = "".join(output_chunks) + timeout_msg = f"\n[Command timed out after {timeout}s]" + return { + "output": partial + timeout_msg + if partial + else timeout_msg.lstrip(), + "returncode": 124, + } + # Periodic activity touch so the gateway knows we're alive + _now = time.monotonic() + if _now - _last_activity_touch >= _ACTIVITY_INTERVAL: + _last_activity_touch = _now + _cb = _get_activity_callback() + if _cb: + try: + _elapsed = int(_now - (deadline - timeout)) + _cb(f"terminal command running ({_elapsed}s elapsed)") + except Exception: + pass + time.sleep(0.2) + + drain_thread.join(timeout=5) + + try: + proc.stdout.close() + except Exception: + pass + + return {"output": "".join(output_chunks), "returncode": proc.returncode} + + def _kill_process(self, proc: ProcessHandle): + """Terminate a process. Subclasses may override for process-group kill.""" + try: + proc.kill() + except (ProcessLookupError, PermissionError, OSError): + pass + + # ------------------------------------------------------------------ + # CWD extraction + # ------------------------------------------------------------------ + + def _update_cwd(self, result: dict): + """Extract CWD from command output. Override for local file-based read.""" + self._extract_cwd_from_output(result) + + def _extract_cwd_from_output(self, result: dict): + """Parse the __HERMES_CWD_{session}__ marker from stdout output. + + Updates self.cwd and strips the marker from result["output"]. + Used by remote backends (Docker, SSH, Modal, Daytona, Singularity). + """ + output = result.get("output", "") + marker = self._cwd_marker + last = output.rfind(marker) + if last == -1: + return + + # Find the opening marker before this closing one + search_start = max(0, last - 4096) # CWD path won't be >4KB + first = output.rfind(marker, search_start, last) + if first == -1 or first == last: + return + + cwd_path = output[first + len(marker) : last].strip() + if cwd_path: + self.cwd = cwd_path + + # Strip the marker line AND the \n we injected before it. + # The wrapper emits: printf '\n__MARKER__%s__MARKER__\n' + # So the output looks like: \n__MARKER__path__MARKER__\n + # We want to remove everything from the injected \n onwards. + line_start = output.rfind("\n", 0, first) + if line_start == -1: + line_start = first + line_end = output.find("\n", last + len(marker)) + line_end = line_end + 1 if line_end != -1 else len(output) + + result["output"] = output[:line_start] + output[line_end:] + + # ------------------------------------------------------------------ + # Hooks + # ------------------------------------------------------------------ + + def _before_execute(self) -> None: + """Hook called before each command execution. + + Remote backends (SSH, Modal, Daytona) override this to trigger + their FileSyncManager. Bind-mount backends (Docker, Singularity) + and Local don't need file sync — the host filesystem is directly + visible inside the container/process. + """ + pass + + # ------------------------------------------------------------------ + # Unified execute() + # ------------------------------------------------------------------ + + def execute( + self, + command: str, + cwd: str = "", + *, + timeout: int | None = None, + stdin_data: str | None = None, + ) -> dict: + """Execute a command, return {"output": str, "returncode": int}.""" + self._before_execute() + + exec_command, sudo_stdin = self._prepare_command(command) + effective_timeout = timeout or self.timeout + effective_cwd = cwd or self.cwd + + # Merge sudo stdin with caller stdin + if sudo_stdin is not None and stdin_data is not None: + effective_stdin = sudo_stdin + stdin_data + elif sudo_stdin is not None: + effective_stdin = sudo_stdin + else: + effective_stdin = stdin_data + + # Embed stdin as heredoc for backends that need it + if effective_stdin and self._stdin_mode == "heredoc": + exec_command = self._embed_stdin_heredoc(exec_command, effective_stdin) + effective_stdin = None + + wrapped = self._wrap_command(exec_command, effective_cwd) + + # Use login shell if snapshot failed (so user's profile still loads) + login = not self._snapshot_ready + + proc = self._run_bash( + wrapped, login=login, timeout=effective_timeout, stdin_data=effective_stdin + ) + result = self._wait_for_process(proc, timeout=effective_timeout) + self._update_cwd(result) + + return result + + # ------------------------------------------------------------------ + # Shared helpers + # ------------------------------------------------------------------ + + def stop(self): + """Alias for cleanup (compat with older callers).""" + self.cleanup() + + def __del__(self): + try: + self.cleanup() + except Exception: + pass + + def _prepare_command(self, command: str) -> tuple[str, str | None]: + """Transform sudo commands if SUDO_PASSWORD is available.""" + from tools.terminal_tool import _transform_sudo_command + + return _transform_sudo_command(command) + diff --git a/mindcli/_vendor/tools/environments/daytona.py b/mindcli/_vendor/tools/environments/daytona.py new file mode 100644 index 0000000..c2913e5 --- /dev/null +++ b/mindcli/_vendor/tools/environments/daytona.py @@ -0,0 +1,229 @@ +"""Daytona cloud execution environment. + +Uses the Daytona Python SDK to run commands in cloud sandboxes. +Supports persistent sandboxes: when enabled, sandboxes are stopped on cleanup +and resumed on next creation, preserving the filesystem across sessions. +""" + +import logging +import math +import shlex +import threading +from pathlib import Path + +from tools.environments.base import ( + BaseEnvironment, + _ThreadedProcessHandle, +) +from tools.environments.file_sync import ( + FileSyncManager, + iter_sync_files, + quoted_mkdir_command, + quoted_rm_command, + unique_parent_dirs, +) + +logger = logging.getLogger(__name__) + + +class DaytonaEnvironment(BaseEnvironment): + """Daytona cloud sandbox execution backend. + + Spawn-per-call via _ThreadedProcessHandle wrapping blocking SDK calls. + cancel_fn wired to sandbox.stop() for interrupt support. + Shell timeout wrapper preserved (SDK timeout unreliable). + """ + + _stdin_mode = "heredoc" + + def __init__( + self, + image: str, + cwd: str = "/home/daytona", + timeout: int = 60, + cpu: int = 1, + memory: int = 5120, + disk: int = 10240, + persistent_filesystem: bool = True, + task_id: str = "default", + ): + requested_cwd = cwd + super().__init__(cwd=cwd, timeout=timeout) + + from daytona import ( + Daytona, + CreateSandboxFromImageParams, + DaytonaError, + Resources, + SandboxState, + ) + + self._persistent = persistent_filesystem + self._task_id = task_id + self._SandboxState = SandboxState + self._daytona = Daytona() + self._sandbox = None + self._lock = threading.Lock() + + memory_gib = max(1, math.ceil(memory / 1024)) + disk_gib = max(1, math.ceil(disk / 1024)) + if disk_gib > 10: + logger.warning( + "Daytona: requested disk (%dGB) exceeds platform limit (10GB). " + "Capping to 10GB.", disk_gib, + ) + disk_gib = 10 + resources = Resources(cpu=cpu, memory=memory_gib, disk=disk_gib) + + labels = {"hermes_task_id": task_id} + sandbox_name = f"hermes-{task_id}" + + if self._persistent: + try: + self._sandbox = self._daytona.get(sandbox_name) + self._sandbox.start() + logger.info("Daytona: resumed sandbox %s for task %s", + self._sandbox.id, task_id) + except DaytonaError: + self._sandbox = None + except Exception as e: + logger.warning("Daytona: failed to resume sandbox for task %s: %s", + task_id, e) + self._sandbox = None + + if self._sandbox is None: + try: + page = self._daytona.list(labels=labels, page=1, limit=1) + if page.items: + self._sandbox = page.items[0] + self._sandbox.start() + logger.info("Daytona: resumed legacy sandbox %s for task %s", + self._sandbox.id, task_id) + except Exception as e: + logger.debug("Daytona: no legacy sandbox found for task %s: %s", + task_id, e) + self._sandbox = None + + if self._sandbox is None: + self._sandbox = self._daytona.create( + CreateSandboxFromImageParams( + image=image, + name=sandbox_name, + labels=labels, + auto_stop_interval=0, + resources=resources, + ) + ) + logger.info("Daytona: created sandbox %s for task %s", + self._sandbox.id, task_id) + + # Detect remote home dir + self._remote_home = "/root" + try: + home = self._sandbox.process.exec("echo $HOME").result.strip() + if home: + self._remote_home = home + if requested_cwd in ("~", "/home/daytona"): + self.cwd = home + except Exception: + pass + logger.info("Daytona: resolved home to %s, cwd to %s", self._remote_home, self.cwd) + + self._sync_manager = FileSyncManager( + get_files_fn=lambda: iter_sync_files(f"{self._remote_home}/.hermes"), + upload_fn=self._daytona_upload, + delete_fn=self._daytona_delete, + bulk_upload_fn=self._daytona_bulk_upload, + ) + self._sync_manager.sync(force=True) + self.init_session() + + def _daytona_upload(self, host_path: str, remote_path: str) -> None: + """Upload a single file via Daytona SDK.""" + parent = str(Path(remote_path).parent) + self._sandbox.process.exec(f"mkdir -p {parent}") + self._sandbox.fs.upload_file(host_path, remote_path) + + def _daytona_bulk_upload(self, files: list[tuple[str, str]]) -> None: + """Upload many files in a single HTTP call via Daytona SDK. + + Uses ``sandbox.fs.upload_files()`` which batches all files into one + multipart POST, avoiding per-file TLS/HTTP overhead (~580 files + goes from ~5 min to <2 s). + """ + from daytona.common.filesystem import FileUpload + + if not files: + return + + parents = unique_parent_dirs(files) + if parents: + self._sandbox.process.exec(quoted_mkdir_command(parents)) + + uploads = [ + FileUpload(source=host_path, destination=remote_path) + for host_path, remote_path in files + ] + self._sandbox.fs.upload_files(uploads) + + def _daytona_delete(self, remote_paths: list[str]) -> None: + """Batch-delete remote files via SDK exec.""" + self._sandbox.process.exec(quoted_rm_command(remote_paths)) + + # ------------------------------------------------------------------ + # Sandbox lifecycle + # ------------------------------------------------------------------ + + def _ensure_sandbox_ready(self) -> None: + """Restart sandbox if it was stopped (e.g., by a previous interrupt).""" + self._sandbox.refresh_data() + if self._sandbox.state in (self._SandboxState.STOPPED, self._SandboxState.ARCHIVED): + self._sandbox.start() + logger.info("Daytona: restarted sandbox %s", self._sandbox.id) + + def _before_execute(self) -> None: + """Ensure sandbox is ready, then sync files via FileSyncManager.""" + with self._lock: + self._ensure_sandbox_ready() + self._sync_manager.sync() + + def _run_bash(self, cmd_string: str, *, login: bool = False, + timeout: int = 120, + stdin_data: str | None = None): + """Return a _ThreadedProcessHandle wrapping a blocking Daytona SDK call.""" + sandbox = self._sandbox + lock = self._lock + + def cancel(): + with lock: + try: + sandbox.stop() + except Exception: + pass + + if login: + shell_cmd = f"bash -l -c {shlex.quote(cmd_string)}" + else: + shell_cmd = f"bash -c {shlex.quote(cmd_string)}" + + def exec_fn() -> tuple[str, int]: + response = sandbox.process.exec(shell_cmd, timeout=timeout) + return (response.result or "", response.exit_code) + + return _ThreadedProcessHandle(exec_fn, cancel_fn=cancel) + + def cleanup(self): + with self._lock: + if self._sandbox is None: + return + try: + if self._persistent: + self._sandbox.stop() + logger.info("Daytona: stopped sandbox %s (filesystem preserved)", + self._sandbox.id) + else: + self._daytona.delete(self._sandbox) + logger.info("Daytona: deleted sandbox %s", self._sandbox.id) + except Exception as e: + logger.warning("Daytona: cleanup failed: %s", e) + self._sandbox = None diff --git a/mindcli/_vendor/tools/environments/docker.py b/mindcli/_vendor/tools/environments/docker.py new file mode 100644 index 0000000..2341778 --- /dev/null +++ b/mindcli/_vendor/tools/environments/docker.py @@ -0,0 +1,560 @@ +"""Docker execution environment for sandboxed command execution. + +Security hardened (cap-drop ALL, no-new-privileges, PID limits), +configurable resource limits (CPU, memory, disk), and optional filesystem +persistence via bind mounts. +""" + +import logging +import os +import re +import shutil +import subprocess +import sys +import uuid +from typing import Optional + +from tools.environments.base import BaseEnvironment, _popen_bash +from tools.environments.local import _HERMES_PROVIDER_ENV_BLOCKLIST + +logger = logging.getLogger(__name__) + + +# Common Docker Desktop install paths checked when 'docker' is not in PATH. +# macOS Intel: /usr/local/bin, macOS Apple Silicon (Homebrew): /opt/homebrew/bin, +# Docker Desktop app bundle: /Applications/Docker.app/Contents/Resources/bin +_DOCKER_SEARCH_PATHS = [ + "/usr/local/bin/docker", + "/opt/homebrew/bin/docker", + "/Applications/Docker.app/Contents/Resources/bin/docker", +] + +_docker_executable: Optional[str] = None # resolved once, cached +_ENV_VAR_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$") + + +def _normalize_forward_env_names(forward_env: list[str] | None) -> list[str]: + """Return a deduplicated list of valid environment variable names.""" + normalized: list[str] = [] + seen: set[str] = set() + + for item in forward_env or []: + if not isinstance(item, str): + logger.warning("Ignoring non-string docker_forward_env entry: %r", item) + continue + + key = item.strip() + if not key: + continue + if not _ENV_VAR_NAME_RE.match(key): + logger.warning("Ignoring invalid docker_forward_env entry: %r", item) + continue + if key in seen: + continue + + seen.add(key) + normalized.append(key) + + return normalized + + +def _normalize_env_dict(env: dict | None) -> dict[str, str]: + """Validate and normalize a docker_env dict to {str: str}. + + Filters out entries with invalid variable names or non-string values. + """ + if not env: + return {} + if not isinstance(env, dict): + logger.warning("docker_env is not a dict: %r", env) + return {} + + normalized: dict[str, str] = {} + for key, value in env.items(): + if not isinstance(key, str) or not _ENV_VAR_NAME_RE.match(key.strip()): + logger.warning("Ignoring invalid docker_env key: %r", key) + continue + key = key.strip() + if not isinstance(value, str): + # Coerce simple scalar types (int, bool, float) to string; + # reject complex types. + if isinstance(value, (int, float, bool)): + value = str(value) + else: + logger.warning("Ignoring non-string docker_env value for %r: %r", key, value) + continue + normalized[key] = value + + return normalized + + +def _load_hermes_env_vars() -> dict[str, str]: + """Load ~/.hermes/.env values without failing Docker command execution.""" + try: + from hermes_cli.config import load_env + + return load_env() or {} + except Exception: + return {} + + +def find_docker() -> Optional[str]: + """Locate the docker CLI binary. + + Checks ``shutil.which`` first (respects PATH), then probes well-known + install locations on macOS where Docker Desktop may not be in PATH + (e.g. when running as a gateway service via launchd). + + Returns the absolute path, or ``None`` if docker cannot be found. + """ + global _docker_executable + if _docker_executable is not None: + return _docker_executable + + found = shutil.which("docker") + if found: + _docker_executable = found + return found + + for path in _DOCKER_SEARCH_PATHS: + if os.path.isfile(path) and os.access(path, os.X_OK): + _docker_executable = path + logger.info("Found docker at non-PATH location: %s", path) + return path + + return None + + +# Security flags applied to every container. +# The container itself is the security boundary (isolated from host). +# We drop all capabilities then add back the minimum needed: +# DAC_OVERRIDE - root can write to bind-mounted dirs owned by host user +# CHOWN/FOWNER - package managers (pip, npm, apt) need to set file ownership +# Block privilege escalation and limit PIDs. +# /tmp is size-limited and nosuid but allows exec (needed by pip/npm builds). +_SECURITY_ARGS = [ + "--cap-drop", "ALL", + "--cap-add", "DAC_OVERRIDE", + "--cap-add", "CHOWN", + "--cap-add", "FOWNER", + "--security-opt", "no-new-privileges", + "--pids-limit", "256", + "--tmpfs", "/tmp:rw,nosuid,size=512m", + "--tmpfs", "/var/tmp:rw,noexec,nosuid,size=256m", + "--tmpfs", "/run:rw,noexec,nosuid,size=64m", +] + + +_storage_opt_ok: Optional[bool] = None # cached result across instances + + +def _ensure_docker_available() -> None: + """Best-effort check that the docker CLI is available before use. + + Reuses ``find_docker()`` so this preflight stays consistent with the rest of + the Docker backend, including known non-PATH Docker Desktop locations. + """ + docker_exe = find_docker() + if not docker_exe: + logger.error( + "Docker backend selected but no docker executable was found in PATH " + "or known install locations. Install Docker Desktop and ensure the " + "CLI is available." + ) + raise RuntimeError( + "Docker executable not found in PATH or known install locations. " + "Install Docker and ensure the 'docker' command is available." + ) + + try: + result = subprocess.run( + [docker_exe, "version"], + capture_output=True, + text=True, + timeout=5, + ) + except FileNotFoundError: + logger.error( + "Docker backend selected but the resolved docker executable '%s' could " + "not be executed.", + docker_exe, + exc_info=True, + ) + raise RuntimeError( + "Docker executable could not be executed. Check your Docker installation." + ) + except subprocess.TimeoutExpired: + logger.error( + "Docker backend selected but '%s version' timed out. " + "The Docker daemon may not be running.", + docker_exe, + exc_info=True, + ) + raise RuntimeError( + "Docker daemon is not responding. Ensure Docker is running and try again." + ) + except Exception: + logger.error( + "Unexpected error while checking Docker availability.", + exc_info=True, + ) + raise + else: + if result.returncode != 0: + logger.error( + "Docker backend selected but '%s version' failed " + "(exit code %d, stderr=%s)", + docker_exe, + result.returncode, + result.stderr.strip(), + ) + raise RuntimeError( + "Docker command is available but 'docker version' failed. " + "Check your Docker installation." + ) + + +class DockerEnvironment(BaseEnvironment): + """Hardened Docker container execution with resource limits and persistence. + + Security: all capabilities dropped, no privilege escalation, PID limits, + size-limited tmpfs for scratch dirs. The container itself is the security + boundary — the filesystem inside is writable so agents can install packages + (pip, npm, apt) as needed. Writable workspace via tmpfs or bind mounts. + + Persistence: when enabled, bind mounts preserve /workspace and /root + across container restarts. + """ + + def __init__( + self, + image: str, + cwd: str = "/root", + timeout: int = 60, + cpu: float = 0, + memory: int = 0, + disk: int = 0, + persistent_filesystem: bool = False, + task_id: str = "default", + volumes: list = None, + forward_env: list[str] | None = None, + env: dict | None = None, + network: bool = True, + host_cwd: str = None, + auto_mount_cwd: bool = False, + ): + if cwd == "~": + cwd = "/root" + super().__init__(cwd=cwd, timeout=timeout) + self._persistent = persistent_filesystem + self._task_id = task_id + self._forward_env = _normalize_forward_env_names(forward_env) + self._env = _normalize_env_dict(env) + self._container_id: Optional[str] = None + logger.info(f"DockerEnvironment volumes: {volumes}") + # Ensure volumes is a list (config.yaml could be malformed) + if volumes is not None and not isinstance(volumes, list): + logger.warning(f"docker_volumes config is not a list: {volumes!r}") + volumes = [] + + # Fail fast if Docker is not available. + _ensure_docker_available() + + # Build resource limit args + resource_args = [] + if cpu > 0: + resource_args.extend(["--cpus", str(cpu)]) + if memory > 0: + resource_args.extend(["--memory", f"{memory}m"]) + if disk > 0 and sys.platform != "darwin": + if self._storage_opt_supported(): + resource_args.extend(["--storage-opt", f"size={disk}m"]) + else: + logger.warning( + "Docker storage driver does not support per-container disk limits " + "(requires overlay2 on XFS with pquota). Container will run without disk quota." + ) + if not network: + resource_args.append("--network=none") + + # Persistent workspace via bind mounts from a configurable host directory + # (TERMINAL_SANDBOX_DIR, default ~/.hermes/sandboxes/). Non-persistent + # mode uses tmpfs (ephemeral, fast, gone on cleanup). + from tools.environments.base import get_sandbox_dir + + # User-configured volume mounts (from config.yaml docker_volumes) + volume_args = [] + workspace_explicitly_mounted = False + for vol in (volumes or []): + if not isinstance(vol, str): + logger.warning(f"Docker volume entry is not a string: {vol!r}") + continue + vol = vol.strip() + if not vol: + continue + if ":" in vol: + volume_args.extend(["-v", vol]) + if ":/workspace" in vol: + workspace_explicitly_mounted = True + else: + logger.warning(f"Docker volume '{vol}' missing colon, skipping") + + host_cwd_abs = os.path.abspath(os.path.expanduser(host_cwd)) if host_cwd else "" + bind_host_cwd = ( + auto_mount_cwd + and bool(host_cwd_abs) + and os.path.isdir(host_cwd_abs) + and not workspace_explicitly_mounted + ) + if auto_mount_cwd and host_cwd and not os.path.isdir(host_cwd_abs): + logger.debug(f"Skipping docker cwd mount: host_cwd is not a valid directory: {host_cwd}") + + self._workspace_dir: Optional[str] = None + self._home_dir: Optional[str] = None + writable_args = [] + if self._persistent: + sandbox = get_sandbox_dir() / "docker" / task_id + self._home_dir = str(sandbox / "home") + os.makedirs(self._home_dir, exist_ok=True) + writable_args.extend([ + "-v", f"{self._home_dir}:/root", + ]) + if not bind_host_cwd and not workspace_explicitly_mounted: + self._workspace_dir = str(sandbox / "workspace") + os.makedirs(self._workspace_dir, exist_ok=True) + writable_args.extend([ + "-v", f"{self._workspace_dir}:/workspace", + ]) + else: + if not bind_host_cwd and not workspace_explicitly_mounted: + writable_args.extend([ + "--tmpfs", "/workspace:rw,exec,size=10g", + ]) + writable_args.extend([ + "--tmpfs", "/home:rw,exec,size=1g", + "--tmpfs", "/root:rw,exec,size=1g", + ]) + + if bind_host_cwd: + logger.info(f"Mounting configured host cwd to /workspace: {host_cwd_abs}") + volume_args = ["-v", f"{host_cwd_abs}:/workspace", *volume_args] + elif workspace_explicitly_mounted: + logger.debug("Skipping docker cwd mount: /workspace already mounted by user config") + + # Mount credential files (OAuth tokens, etc.) declared by skills. + # Read-only so the container can authenticate but not modify host creds. + try: + from tools.credential_files import ( + get_credential_file_mounts, + get_skills_directory_mount, + get_cache_directory_mounts, + ) + + for mount_entry in get_credential_file_mounts(): + volume_args.extend([ + "-v", + f"{mount_entry['host_path']}:{mount_entry['container_path']}:ro", + ]) + logger.info( + "Docker: mounting credential %s -> %s", + mount_entry["host_path"], + mount_entry["container_path"], + ) + + # Mount skill directories (local + external) so skill + # scripts/templates are available inside the container. + for skills_mount in get_skills_directory_mount(): + volume_args.extend([ + "-v", + f"{skills_mount['host_path']}:{skills_mount['container_path']}:ro", + ]) + logger.info( + "Docker: mounting skills dir %s -> %s", + skills_mount["host_path"], + skills_mount["container_path"], + ) + + # Mount host-side cache directories (documents, images, audio, + # screenshots) so the agent can access uploaded files and other + # cached media from inside the container. Read-only — the + # container reads these but the host gateway manages writes. + for cache_mount in get_cache_directory_mounts(): + volume_args.extend([ + "-v", + f"{cache_mount['host_path']}:{cache_mount['container_path']}:ro", + ]) + logger.info( + "Docker: mounting cache dir %s -> %s", + cache_mount["host_path"], + cache_mount["container_path"], + ) + except Exception as e: + logger.debug("Docker: could not load credential file mounts: %s", e) + + # Explicit environment variables (docker_env config) — set at container + # creation so they're available to all processes (including entrypoint). + env_args = [] + for key in sorted(self._env): + env_args.extend(["-e", f"{key}={self._env[key]}"]) + + logger.info(f"Docker volume_args: {volume_args}") + all_run_args = list(_SECURITY_ARGS) + writable_args + resource_args + volume_args + env_args + logger.info(f"Docker run_args: {all_run_args}") + + # Resolve the docker executable once so it works even when + # /usr/local/bin is not in PATH (common on macOS gateway/service). + self._docker_exe = find_docker() or "docker" + + # Start the container directly via `docker run -d`. + container_name = f"hermes-{uuid.uuid4().hex[:8]}" + run_cmd = [ + self._docker_exe, "run", "-d", + "--init", # tini/catatonit as PID 1 — reaps zombie children + "--name", container_name, + "-w", cwd, + *all_run_args, + image, + "sleep", "infinity", # no fixed lifetime — idle reaper handles cleanup + ] + logger.debug(f"Starting container: {' '.join(run_cmd)}") + result = subprocess.run( + run_cmd, + capture_output=True, + text=True, + timeout=120, # image pull may take a while + check=True, + ) + self._container_id = result.stdout.strip() + logger.info(f"Started container {container_name} ({self._container_id[:12]})") + + # Build the init-time env forwarding args (used only by init_session + # to inject host env vars into the snapshot; subsequent commands get + # them from the snapshot file). + self._init_env_args = self._build_init_env_args() + + # Initialize session snapshot inside the container + self.init_session() + + def _build_init_env_args(self) -> list[str]: + """Build -e KEY=VALUE args for injecting host env vars into init_session. + + These are used once during init_session() so that export -p captures + them into the snapshot. Subsequent execute() calls don't need -e flags. + """ + exec_env: dict[str, str] = dict(self._env) + + explicit_forward_keys = set(self._forward_env) + passthrough_keys: set[str] = set() + try: + from tools.env_passthrough import get_all_passthrough + passthrough_keys = set(get_all_passthrough()) + except Exception: + pass + # Explicit docker_forward_env entries are an intentional opt-in and must + # win over the generic Hermes secret blocklist. Only implicit passthrough + # keys are filtered. + forward_keys = explicit_forward_keys | (passthrough_keys - _HERMES_PROVIDER_ENV_BLOCKLIST) + hermes_env = _load_hermes_env_vars() if forward_keys else {} + for key in sorted(forward_keys): + value = os.getenv(key) + if value is None: + value = hermes_env.get(key) + if value is not None: + exec_env[key] = value + + args = [] + for key in sorted(exec_env): + args.extend(["-e", f"{key}={exec_env[key]}"]) + return args + + def _run_bash(self, cmd_string: str, *, login: bool = False, + timeout: int = 120, + stdin_data: str | None = None) -> subprocess.Popen: + """Spawn a bash process inside the Docker container.""" + assert self._container_id, "Container not started" + cmd = [self._docker_exe, "exec"] + if stdin_data is not None: + cmd.append("-i") + + # Only inject -e env args during init_session (login=True). + # Subsequent commands get env vars from the snapshot. + if login: + cmd.extend(self._init_env_args) + + cmd.extend([self._container_id]) + + if login: + cmd.extend(["bash", "-l", "-c", cmd_string]) + else: + cmd.extend(["bash", "-c", cmd_string]) + + return _popen_bash(cmd, stdin_data) + + @staticmethod + def _storage_opt_supported() -> bool: + """Check if Docker's storage driver supports --storage-opt size=. + + Only overlay2 on XFS with pquota supports per-container disk quotas. + Ubuntu (and most distros) default to ext4, where this flag errors out. + """ + global _storage_opt_ok + if _storage_opt_ok is not None: + return _storage_opt_ok + try: + docker = find_docker() or "docker" + result = subprocess.run( + [docker, "info", "--format", "{{.Driver}}"], + capture_output=True, text=True, timeout=10, + ) + driver = result.stdout.strip().lower() + if driver != "overlay2": + _storage_opt_ok = False + return False + # overlay2 only supports storage-opt on XFS with pquota. + # Probe by attempting a dry-ish run — the fastest reliable check. + probe = subprocess.run( + [docker, "create", "--storage-opt", "size=1m", "hello-world"], + capture_output=True, text=True, timeout=15, + ) + if probe.returncode == 0: + # Clean up the created container + container_id = probe.stdout.strip() + if container_id: + subprocess.run([docker, "rm", container_id], + capture_output=True, timeout=5) + _storage_opt_ok = True + else: + _storage_opt_ok = False + except Exception: + _storage_opt_ok = False + logger.debug("Docker --storage-opt support: %s", _storage_opt_ok) + return _storage_opt_ok + + def cleanup(self): + """Stop and remove the container. Bind-mount dirs persist if persistent=True.""" + if self._container_id: + try: + # Stop in background so cleanup doesn't block + stop_cmd = ( + f"(timeout 60 {self._docker_exe} stop {self._container_id} || " + f"{self._docker_exe} rm -f {self._container_id}) >/dev/null 2>&1 &" + ) + subprocess.Popen(stop_cmd, shell=True) + except Exception as e: + logger.warning("Failed to stop container %s: %s", self._container_id, e) + + if not self._persistent: + # Also schedule removal (stop only leaves it as stopped) + try: + subprocess.Popen( + f"sleep 3 && {self._docker_exe} rm -f {self._container_id} >/dev/null 2>&1 &", + shell=True, + ) + except Exception: + pass + self._container_id = None + + if not self._persistent: + for d in (self._workspace_dir, self._home_dir): + if d: + shutil.rmtree(d, ignore_errors=True) diff --git a/mindcli/_vendor/tools/environments/file_sync.py b/mindcli/_vendor/tools/environments/file_sync.py new file mode 100644 index 0000000..64a5b56 --- /dev/null +++ b/mindcli/_vendor/tools/environments/file_sync.py @@ -0,0 +1,168 @@ +"""Shared file sync manager for remote execution backends. + +Tracks local file changes via mtime+size, detects deletions, and +syncs to remote environments transactionally. Used by SSH, Modal, +and Daytona. Docker and Singularity use bind mounts (live host FS +view) and don't need this. +""" + +import logging +import os +import shlex +import time +from pathlib import Path +from typing import Callable + +from tools.environments.base import _file_mtime_key + +logger = logging.getLogger(__name__) + +_SYNC_INTERVAL_SECONDS = 5.0 +_FORCE_SYNC_ENV = "HERMES_FORCE_FILE_SYNC" + +# Transport callbacks provided by each backend +UploadFn = Callable[[str, str], None] # (host_path, remote_path) -> raises on failure +BulkUploadFn = Callable[[list[tuple[str, str]]], None] # [(host_path, remote_path), ...] -> raises on failure +DeleteFn = Callable[[list[str]], None] # (remote_paths) -> raises on failure +GetFilesFn = Callable[[], list[tuple[str, str]]] # () -> [(host_path, remote_path), ...] + + +def iter_sync_files(container_base: str = "/root/.hermes") -> list[tuple[str, str]]: + """Enumerate all files that should be synced to a remote environment. + + Combines credentials, skills, and cache into a single flat list of + (host_path, remote_path) pairs. Credential paths are remapped from + the hardcoded /root/.hermes to *container_base* because the remote + user's home may differ (e.g. /home/daytona, /home/user). + """ + # Late import: credential_files imports agent modules that create + # circular dependencies if loaded at file_sync module level. + from tools.credential_files import ( + get_credential_file_mounts, + iter_cache_files, + iter_skills_files, + ) + + files: list[tuple[str, str]] = [] + for entry in get_credential_file_mounts(): + remote = entry["container_path"].replace( + "/root/.hermes", container_base, 1 + ) + files.append((entry["host_path"], remote)) + for entry in iter_skills_files(container_base=container_base): + files.append((entry["host_path"], entry["container_path"])) + for entry in iter_cache_files(container_base=container_base): + files.append((entry["host_path"], entry["container_path"])) + return files + + +def quoted_rm_command(remote_paths: list[str]) -> str: + """Build a shell ``rm -f`` command for a batch of remote paths.""" + return "rm -f " + " ".join(shlex.quote(p) for p in remote_paths) + + +def quoted_mkdir_command(dirs: list[str]) -> str: + """Build a shell ``mkdir -p`` command for a batch of directories.""" + return "mkdir -p " + " ".join(shlex.quote(d) for d in dirs) + + +def unique_parent_dirs(files: list[tuple[str, str]]) -> list[str]: + """Extract sorted unique parent directories from (host, remote) pairs.""" + return sorted({str(Path(remote).parent) for _, remote in files}) + + +class FileSyncManager: + """Tracks local file changes and syncs to a remote environment. + + Backends instantiate this with transport callbacks (upload, delete) + and a file-source callable. The manager handles mtime-based change + detection, deletion tracking, rate limiting, and transactional state. + + Not used by bind-mount backends (Docker, Singularity) — those get + live host FS views and don't need file sync. + """ + + def __init__( + self, + get_files_fn: GetFilesFn, + upload_fn: UploadFn, + delete_fn: DeleteFn, + sync_interval: float = _SYNC_INTERVAL_SECONDS, + bulk_upload_fn: BulkUploadFn | None = None, + ): + self._get_files_fn = get_files_fn + self._upload_fn = upload_fn + self._bulk_upload_fn = bulk_upload_fn + self._delete_fn = delete_fn + self._synced_files: dict[str, tuple[float, int]] = {} # remote_path -> (mtime, size) + self._last_sync_time: float = 0.0 # monotonic; 0 ensures first sync runs + self._sync_interval = sync_interval + + def sync(self, *, force: bool = False) -> None: + """Run a sync cycle: upload changed files, delete removed files. + + Rate-limited to once per ``sync_interval`` unless *force* is True + or ``HERMES_FORCE_FILE_SYNC=1`` is set. + + Transactional: state only committed if ALL operations succeed. + On failure, state rolls back so the next cycle retries everything. + """ + if not force and not os.environ.get(_FORCE_SYNC_ENV): + now = time.monotonic() + if now - self._last_sync_time < self._sync_interval: + return + + current_files = self._get_files_fn() + current_remote_paths = {remote for _, remote in current_files} + + # --- Uploads: new or changed files --- + to_upload: list[tuple[str, str]] = [] + new_files = dict(self._synced_files) + for host_path, remote_path in current_files: + file_key = _file_mtime_key(host_path) + if file_key is None: + continue + if self._synced_files.get(remote_path) == file_key: + continue + to_upload.append((host_path, remote_path)) + new_files[remote_path] = file_key + + # --- Deletes: synced paths no longer in current set --- + to_delete = [p for p in self._synced_files if p not in current_remote_paths] + + if not to_upload and not to_delete: + self._last_sync_time = time.monotonic() + return + + # Snapshot for rollback (only when there's work to do) + prev_files = dict(self._synced_files) + + if to_upload: + logger.debug("file_sync: uploading %d file(s)", len(to_upload)) + if to_delete: + logger.debug("file_sync: deleting %d stale remote file(s)", len(to_delete)) + + try: + if to_upload and self._bulk_upload_fn is not None: + self._bulk_upload_fn(to_upload) + logger.debug("file_sync: bulk-uploaded %d file(s)", len(to_upload)) + else: + for host_path, remote_path in to_upload: + self._upload_fn(host_path, remote_path) + logger.debug("file_sync: uploaded %s -> %s", host_path, remote_path) + + if to_delete: + self._delete_fn(to_delete) + logger.debug("file_sync: deleted %s", to_delete) + + # --- Commit (all succeeded) --- + for p in to_delete: + new_files.pop(p, None) + + self._synced_files = new_files + self._last_sync_time = time.monotonic() + + except Exception as exc: + self._synced_files = prev_files + self._last_sync_time = time.monotonic() + logger.warning("file_sync: sync failed, rolled back state: %s", exc) diff --git a/mindcli/_vendor/tools/environments/local.py b/mindcli/_vendor/tools/environments/local.py new file mode 100644 index 0000000..a1ab676 --- /dev/null +++ b/mindcli/_vendor/tools/environments/local.py @@ -0,0 +1,314 @@ +"""Local execution environment — spawn-per-call with session snapshot.""" + +import os +import platform +import shutil +import signal +import subprocess +import tempfile + +from tools.environments.base import BaseEnvironment, _pipe_stdin + +_IS_WINDOWS = platform.system() == "Windows" + + +# Hermes-internal env vars that should NOT leak into terminal subprocesses. +_HERMES_PROVIDER_ENV_FORCE_PREFIX = "_HERMES_FORCE_" + + +def _build_provider_env_blocklist() -> frozenset: + """Derive the blocklist from provider, tool, and gateway config.""" + blocked: set[str] = set() + + try: + from hermes_cli.auth import PROVIDER_REGISTRY + for pconfig in PROVIDER_REGISTRY.values(): + blocked.update(pconfig.api_key_env_vars) + if pconfig.base_url_env_var: + blocked.add(pconfig.base_url_env_var) + except ImportError: + pass + + try: + from hermes_cli.config import OPTIONAL_ENV_VARS + for name, metadata in OPTIONAL_ENV_VARS.items(): + category = metadata.get("category") + if category in {"tool", "messaging"}: + blocked.add(name) + elif category == "setting" and metadata.get("password"): + blocked.add(name) + except ImportError: + pass + + blocked.update({ + "OPENAI_BASE_URL", + "OPENAI_API_KEY", + "OPENAI_API_BASE", + "OPENAI_ORG_ID", + "OPENAI_ORGANIZATION", + "OPENROUTER_API_KEY", + "ANTHROPIC_BASE_URL", + "ANTHROPIC_TOKEN", + "CLAUDE_CODE_OAUTH_TOKEN", + "LLM_MODEL", + "GOOGLE_API_KEY", + "DEEPSEEK_API_KEY", + "MISTRAL_API_KEY", + "GROQ_API_KEY", + "TOGETHER_API_KEY", + "PERPLEXITY_API_KEY", + "COHERE_API_KEY", + "FIREWORKS_API_KEY", + "XAI_API_KEY", + "HELICONE_API_KEY", + "PARALLEL_API_KEY", + "FIRECRAWL_API_KEY", + "FIRECRAWL_API_URL", + "TELEGRAM_HOME_CHANNEL", + "TELEGRAM_HOME_CHANNEL_NAME", + "DISCORD_HOME_CHANNEL", + "DISCORD_HOME_CHANNEL_NAME", + "DISCORD_REQUIRE_MENTION", + "DISCORD_FREE_RESPONSE_CHANNELS", + "DISCORD_AUTO_THREAD", + "SLACK_HOME_CHANNEL", + "SLACK_HOME_CHANNEL_NAME", + "SLACK_ALLOWED_USERS", + "WHATSAPP_ENABLED", + "WHATSAPP_MODE", + "WHATSAPP_ALLOWED_USERS", + "SIGNAL_HTTP_URL", + "SIGNAL_ACCOUNT", + "SIGNAL_ALLOWED_USERS", + "SIGNAL_GROUP_ALLOWED_USERS", + "SIGNAL_HOME_CHANNEL", + "SIGNAL_HOME_CHANNEL_NAME", + "SIGNAL_IGNORE_STORIES", + "HASS_TOKEN", + "HASS_URL", + "EMAIL_ADDRESS", + "EMAIL_PASSWORD", + "EMAIL_IMAP_HOST", + "EMAIL_SMTP_HOST", + "EMAIL_HOME_ADDRESS", + "EMAIL_HOME_ADDRESS_NAME", + "GATEWAY_ALLOWED_USERS", + "GH_TOKEN", + "GITHUB_APP_ID", + "GITHUB_APP_PRIVATE_KEY_PATH", + "GITHUB_APP_INSTALLATION_ID", + "MODAL_TOKEN_ID", + "MODAL_TOKEN_SECRET", + "DAYTONA_API_KEY", + }) + return frozenset(blocked) + + +_HERMES_PROVIDER_ENV_BLOCKLIST = _build_provider_env_blocklist() + + +def _sanitize_subprocess_env(base_env: dict | None, extra_env: dict | None = None) -> dict: + """Filter Hermes-managed secrets from a subprocess environment.""" + try: + from tools.env_passthrough import is_env_passthrough as _is_passthrough + except Exception: + _is_passthrough = lambda _: False # noqa: E731 + + sanitized: dict[str, str] = {} + + for key, value in (base_env or {}).items(): + if key.startswith(_HERMES_PROVIDER_ENV_FORCE_PREFIX): + continue + if key not in _HERMES_PROVIDER_ENV_BLOCKLIST or _is_passthrough(key): + sanitized[key] = value + + for key, value in (extra_env or {}).items(): + if key.startswith(_HERMES_PROVIDER_ENV_FORCE_PREFIX): + real_key = key[len(_HERMES_PROVIDER_ENV_FORCE_PREFIX):] + sanitized[real_key] = value + elif key not in _HERMES_PROVIDER_ENV_BLOCKLIST or _is_passthrough(key): + sanitized[key] = value + + # Per-profile HOME isolation for background processes (same as _make_run_env). + from hermes_constants import get_subprocess_home + _profile_home = get_subprocess_home() + if _profile_home: + sanitized["HOME"] = _profile_home + + return sanitized + + +def _find_bash() -> str: + """Find bash for command execution.""" + if not _IS_WINDOWS: + return ( + shutil.which("bash") + or ("/usr/bin/bash" if os.path.isfile("/usr/bin/bash") else None) + or ("/bin/bash" if os.path.isfile("/bin/bash") else None) + or os.environ.get("SHELL") + or "/bin/sh" + ) + + custom = os.environ.get("HERMES_GIT_BASH_PATH") + if custom and os.path.isfile(custom): + return custom + + found = shutil.which("bash") + if found: + return found + + for candidate in ( + os.path.join(os.environ.get("ProgramFiles", r"C:\Program Files"), "Git", "bin", "bash.exe"), + os.path.join(os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)"), "Git", "bin", "bash.exe"), + os.path.join(os.environ.get("LOCALAPPDATA", ""), "Programs", "Git", "bin", "bash.exe"), + ): + if candidate and os.path.isfile(candidate): + return candidate + + raise RuntimeError( + "Git Bash not found. Hermes Agent requires Git for Windows on Windows.\n" + "Install it from: https://git-scm.com/download/win\n" + "Or set HERMES_GIT_BASH_PATH to your bash.exe location." + ) + + +# Backward compat — process_registry.py imports this name +_find_shell = _find_bash + + +# Standard PATH entries for environments with minimal PATH. +_SANE_PATH = ( + "/opt/homebrew/bin:/opt/homebrew/sbin:" + "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" +) + + +def _make_run_env(env: dict) -> dict: + """Build a run environment with a sane PATH and provider-var stripping.""" + try: + from tools.env_passthrough import is_env_passthrough as _is_passthrough + except Exception: + _is_passthrough = lambda _: False # noqa: E731 + + merged = dict(os.environ | env) + run_env = {} + for k, v in merged.items(): + if k.startswith(_HERMES_PROVIDER_ENV_FORCE_PREFIX): + real_key = k[len(_HERMES_PROVIDER_ENV_FORCE_PREFIX):] + run_env[real_key] = v + elif k not in _HERMES_PROVIDER_ENV_BLOCKLIST or _is_passthrough(k): + run_env[k] = v + existing_path = run_env.get("PATH", "") + if "/usr/bin" not in existing_path.split(":"): + run_env["PATH"] = f"{existing_path}:{_SANE_PATH}" if existing_path else _SANE_PATH + + # Per-profile HOME isolation: redirect system tool configs (git, ssh, gh, + # npm …) into {HERMES_HOME}/home/ when that directory exists. Only the + # subprocess sees the override — the Python process keeps the real HOME. + from hermes_constants import get_subprocess_home + _profile_home = get_subprocess_home() + if _profile_home: + run_env["HOME"] = _profile_home + + return run_env + + +class LocalEnvironment(BaseEnvironment): + """Run commands directly on the host machine. + + Spawn-per-call: every execute() spawns a fresh bash process. + Session snapshot preserves env vars across calls. + CWD persists via file-based read after each command. + """ + + def __init__(self, cwd: str = "", timeout: int = 60, env: dict = None): + super().__init__(cwd=cwd or os.getcwd(), timeout=timeout, env=env) + self.init_session() + + def get_temp_dir(self) -> str: + """Return a shell-safe writable temp dir for local execution. + + Termux does not provide /tmp by default, but exposes a POSIX TMPDIR. + Prefer POSIX-style env vars when available, keep using /tmp on regular + Unix systems, and only fall back to tempfile.gettempdir() when it also + resolves to a POSIX path. + + Check the environment configured for this backend first so callers can + override the temp root explicitly (for example via terminal.env or a + custom TMPDIR), then fall back to the host process environment. + """ + for env_var in ("TMPDIR", "TMP", "TEMP"): + candidate = self.env.get(env_var) or os.environ.get(env_var) + if candidate and candidate.startswith("/"): + return candidate.rstrip("/") or "/" + + if os.path.isdir("/tmp") and os.access("/tmp", os.W_OK | os.X_OK): + return "/tmp" + + candidate = tempfile.gettempdir() + if candidate.startswith("/"): + return candidate.rstrip("/") or "/" + + return "/tmp" + + def _run_bash(self, cmd_string: str, *, login: bool = False, + timeout: int = 120, + stdin_data: str | None = None) -> subprocess.Popen: + bash = _find_bash() + args = [bash, "-l", "-c", cmd_string] if login else [bash, "-c", cmd_string] + run_env = _make_run_env(self.env) + + proc = subprocess.Popen( + args, + text=True, + env=run_env, + encoding="utf-8", + errors="replace", + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + stdin=subprocess.PIPE if stdin_data is not None else subprocess.DEVNULL, + preexec_fn=None if _IS_WINDOWS else os.setsid, + ) + + if stdin_data is not None: + _pipe_stdin(proc, stdin_data) + + return proc + + def _kill_process(self, proc): + """Kill the entire process group (all children).""" + try: + if _IS_WINDOWS: + proc.terminate() + else: + pgid = os.getpgid(proc.pid) + os.killpg(pgid, signal.SIGTERM) + try: + proc.wait(timeout=1.0) + except subprocess.TimeoutExpired: + os.killpg(pgid, signal.SIGKILL) + except (ProcessLookupError, PermissionError): + try: + proc.kill() + except Exception: + pass + + def _update_cwd(self, result: dict): + """Read CWD from temp file (local-only, no round-trip needed).""" + try: + cwd_path = open(self._cwd_file).read().strip() + if cwd_path: + self.cwd = cwd_path + except (OSError, FileNotFoundError): + pass + + # Still strip the marker from output so it's not visible + self._extract_cwd_from_output(result) + + def cleanup(self): + """Clean up temp files.""" + for f in (self._snapshot_path, self._cwd_file): + try: + os.unlink(f) + except OSError: + pass diff --git a/mindcli/_vendor/tools/environments/managed_modal.py b/mindcli/_vendor/tools/environments/managed_modal.py new file mode 100644 index 0000000..52b00f1 --- /dev/null +++ b/mindcli/_vendor/tools/environments/managed_modal.py @@ -0,0 +1,282 @@ +"""Managed Modal environment backed by tool-gateway.""" + +from __future__ import annotations + +import json +import logging +import os +import requests +import uuid +from dataclasses import dataclass +from typing import Any, Dict, Optional + +from tools.environments.modal_utils import ( + BaseModalExecutionEnvironment, + ModalExecStart, + PreparedModalExec, +) +from tools.managed_tool_gateway import resolve_managed_tool_gateway + +logger = logging.getLogger(__name__) + + +def _request_timeout_env(name: str, default: float) -> float: + try: + value = float(os.getenv(name, str(default))) + return value if value > 0 else default + except (TypeError, ValueError): + return default + + +@dataclass(frozen=True) +class _ManagedModalExecHandle: + exec_id: str + + +class ManagedModalEnvironment(BaseModalExecutionEnvironment): + """Gateway-owned Modal sandbox with Hermes-compatible execute/cleanup.""" + + _CONNECT_TIMEOUT_SECONDS = _request_timeout_env("TERMINAL_MANAGED_MODAL_CONNECT_TIMEOUT_SECONDS", 1.0) + _POLL_READ_TIMEOUT_SECONDS = _request_timeout_env("TERMINAL_MANAGED_MODAL_POLL_READ_TIMEOUT_SECONDS", 5.0) + _CANCEL_READ_TIMEOUT_SECONDS = _request_timeout_env("TERMINAL_MANAGED_MODAL_CANCEL_READ_TIMEOUT_SECONDS", 5.0) + _client_timeout_grace_seconds = 10.0 + _interrupt_output = "[Command interrupted - Modal sandbox exec cancelled]" + _unexpected_error_prefix = "Managed Modal exec failed" + + def __init__( + self, + image: str, + cwd: str = "/root", + timeout: int = 60, + modal_sandbox_kwargs: Optional[Dict[str, Any]] = None, + persistent_filesystem: bool = True, + task_id: str = "default", + ): + super().__init__(cwd=cwd, timeout=timeout) + + self._guard_unsupported_credential_passthrough() + + gateway = resolve_managed_tool_gateway("modal") + if gateway is None: + raise ValueError("Managed Modal requires a configured tool gateway and Nous user token") + + self._gateway_origin = gateway.gateway_origin.rstrip("/") + self._nous_user_token = gateway.nous_user_token + self._task_id = task_id + self._persistent = persistent_filesystem + self._image = image + self._sandbox_kwargs = dict(modal_sandbox_kwargs or {}) + self._create_idempotency_key = str(uuid.uuid4()) + self._sandbox_id = self._create_sandbox() + + def _start_modal_exec(self, prepared: PreparedModalExec) -> ModalExecStart: + exec_id = str(uuid.uuid4()) + payload: Dict[str, Any] = { + "execId": exec_id, + "command": prepared.command, + "cwd": prepared.cwd, + "timeoutMs": int(prepared.timeout * 1000), + } + if prepared.stdin_data is not None: + payload["stdinData"] = prepared.stdin_data + + try: + response = self._request( + "POST", + f"/v1/sandboxes/{self._sandbox_id}/execs", + json=payload, + timeout=10, + ) + except Exception as exc: + return ModalExecStart( + immediate_result=self._error_result(f"Managed Modal exec failed: {exc}") + ) + + if response.status_code >= 400: + return ModalExecStart( + immediate_result=self._error_result( + self._format_error("Managed Modal exec failed", response) + ) + ) + + body = response.json() + status = body.get("status") + if status in {"completed", "failed", "cancelled", "timeout"}: + return ModalExecStart( + immediate_result=self._result( + body.get("output", ""), + body.get("returncode", 1), + ) + ) + + if body.get("execId") != exec_id: + return ModalExecStart( + immediate_result=self._error_result( + "Managed Modal exec start did not return the expected exec id" + ) + ) + + return ModalExecStart(handle=_ManagedModalExecHandle(exec_id=exec_id)) + + def _poll_modal_exec(self, handle: _ManagedModalExecHandle) -> dict | None: + try: + status_response = self._request( + "GET", + f"/v1/sandboxes/{self._sandbox_id}/execs/{handle.exec_id}", + timeout=(self._CONNECT_TIMEOUT_SECONDS, self._POLL_READ_TIMEOUT_SECONDS), + ) + except Exception as exc: + return self._error_result(f"Managed Modal exec poll failed: {exc}") + + if status_response.status_code == 404: + return self._error_result("Managed Modal exec not found") + + if status_response.status_code >= 400: + return self._error_result( + self._format_error("Managed Modal exec poll failed", status_response) + ) + + status_body = status_response.json() + status = status_body.get("status") + if status in {"completed", "failed", "cancelled", "timeout"}: + return self._result( + status_body.get("output", ""), + status_body.get("returncode", 1), + ) + return None + + def _cancel_modal_exec(self, handle: _ManagedModalExecHandle) -> None: + self._cancel_exec(handle.exec_id) + + def _timeout_result_for_modal(self, timeout: int) -> dict: + return self._result(f"Managed Modal exec timed out after {timeout}s", 124) + + def cleanup(self): + if not getattr(self, "_sandbox_id", None): + return + + try: + self._request( + "POST", + f"/v1/sandboxes/{self._sandbox_id}/terminate", + json={ + "snapshotBeforeTerminate": self._persistent, + }, + timeout=60, + ) + except Exception as exc: + logger.warning("Managed Modal cleanup failed: %s", exc) + finally: + self._sandbox_id = None + + def _create_sandbox(self) -> str: + cpu = self._coerce_number(self._sandbox_kwargs.get("cpu"), 1) + memory = self._coerce_number( + self._sandbox_kwargs.get("memoryMiB", self._sandbox_kwargs.get("memory")), + 5120, + ) + disk = self._coerce_number( + self._sandbox_kwargs.get("ephemeral_disk", self._sandbox_kwargs.get("diskMiB")), + None, + ) + + create_payload = { + "image": self._image, + "cwd": self.cwd, + "cpu": cpu, + "memoryMiB": memory, + "timeoutMs": 3_600_000, + "idleTimeoutMs": max(300_000, int(self.timeout * 1000)), + "persistentFilesystem": self._persistent, + "logicalKey": self._task_id, + } + if disk is not None: + create_payload["diskMiB"] = disk + + response = self._request( + "POST", + "/v1/sandboxes", + json=create_payload, + timeout=60, + extra_headers={ + "x-idempotency-key": self._create_idempotency_key, + }, + ) + if response.status_code >= 400: + raise RuntimeError(self._format_error("Managed Modal create failed", response)) + + body = response.json() + sandbox_id = body.get("id") + if not isinstance(sandbox_id, str) or not sandbox_id: + raise RuntimeError("Managed Modal create did not return a sandbox id") + return sandbox_id + + def _guard_unsupported_credential_passthrough(self) -> None: + """Managed Modal does not sync or mount host credential files.""" + try: + from tools.credential_files import get_credential_file_mounts + except Exception: + return + + mounts = get_credential_file_mounts() + if mounts: + raise ValueError( + "Managed Modal does not support host credential-file passthrough. " + "Use TERMINAL_MODAL_MODE=direct when skills or config require " + "credential files inside the sandbox." + ) + + def _request(self, method: str, path: str, *, + json: Dict[str, Any] | None = None, + timeout: int = 30, + extra_headers: Dict[str, str] | None = None) -> requests.Response: + headers = { + "Authorization": f"Bearer {self._nous_user_token}", + "Content-Type": "application/json", + } + if extra_headers: + headers.update(extra_headers) + + return requests.request( + method, + f"{self._gateway_origin}{path}", + headers=headers, + json=json, + timeout=timeout, + ) + + def _cancel_exec(self, exec_id: str) -> None: + try: + self._request( + "POST", + f"/v1/sandboxes/{self._sandbox_id}/execs/{exec_id}/cancel", + timeout=(self._CONNECT_TIMEOUT_SECONDS, self._CANCEL_READ_TIMEOUT_SECONDS), + ) + except Exception as exc: + logger.warning("Managed Modal exec cancel failed: %s", exc) + + @staticmethod + def _coerce_number(value: Any, default: float) -> float: + try: + if value is None: + return default + return float(value) + except (TypeError, ValueError): + return default + + @staticmethod + def _format_error(prefix: str, response: requests.Response) -> str: + try: + payload = response.json() + if isinstance(payload, dict): + message = payload.get("error") or payload.get("message") or payload.get("code") + if isinstance(message, str) and message: + return f"{prefix}: {message}" + return f"{prefix}: {json.dumps(payload, ensure_ascii=False)}" + except Exception: + pass + + text = response.text.strip() + if text: + return f"{prefix}: {text}" + return f"{prefix}: HTTP {response.status_code}" diff --git a/mindcli/_vendor/tools/environments/modal.py b/mindcli/_vendor/tools/environments/modal.py new file mode 100644 index 0000000..5c5c721 --- /dev/null +++ b/mindcli/_vendor/tools/environments/modal.py @@ -0,0 +1,434 @@ +"""Modal cloud execution environment using the native Modal SDK directly. + +Uses ``Sandbox.create()`` + ``Sandbox.exec()`` instead of the older runtime +wrapper, while preserving Hermes' persistent snapshot behavior across sessions. +""" + +import asyncio +import base64 +import io +import logging +import shlex +import tarfile +import threading +from pathlib import Path +from typing import Any, Optional + +from hermes_constants import get_hermes_home +from tools.environments.base import ( + BaseEnvironment, + _ThreadedProcessHandle, + _load_json_store, + _save_json_store, +) +from tools.environments.file_sync import ( + FileSyncManager, + iter_sync_files, + quoted_mkdir_command, + quoted_rm_command, + unique_parent_dirs, +) + +logger = logging.getLogger(__name__) + +_SNAPSHOT_STORE = get_hermes_home() / "modal_snapshots.json" +_DIRECT_SNAPSHOT_NAMESPACE = "direct" + + +def _load_snapshots() -> dict: + return _load_json_store(_SNAPSHOT_STORE) + + +def _save_snapshots(data: dict) -> None: + _save_json_store(_SNAPSHOT_STORE, data) + + +def _direct_snapshot_key(task_id: str) -> str: + return f"{_DIRECT_SNAPSHOT_NAMESPACE}:{task_id}" + + +def _get_snapshot_restore_candidate(task_id: str) -> tuple[str | None, bool]: + snapshots = _load_snapshots() + namespaced_key = _direct_snapshot_key(task_id) + snapshot_id = snapshots.get(namespaced_key) + if isinstance(snapshot_id, str) and snapshot_id: + return snapshot_id, False + legacy_snapshot_id = snapshots.get(task_id) + if isinstance(legacy_snapshot_id, str) and legacy_snapshot_id: + return legacy_snapshot_id, True + return None, False + + +def _store_direct_snapshot(task_id: str, snapshot_id: str) -> None: + snapshots = _load_snapshots() + snapshots[_direct_snapshot_key(task_id)] = snapshot_id + snapshots.pop(task_id, None) + _save_snapshots(snapshots) + + +def _delete_direct_snapshot(task_id: str, snapshot_id: str | None = None) -> None: + snapshots = _load_snapshots() + updated = False + for key in (_direct_snapshot_key(task_id), task_id): + value = snapshots.get(key) + if value is None: + continue + if snapshot_id is None or value == snapshot_id: + snapshots.pop(key, None) + updated = True + if updated: + _save_snapshots(snapshots) + + +def _resolve_modal_image(image_spec: Any) -> Any: + """Convert registry references or snapshot ids into Modal image objects. + + Includes add_python support for ubuntu/debian images (absorbed from PR 4511). + """ + import modal as _modal + + if not isinstance(image_spec, str): + return image_spec + + if image_spec.startswith("im-"): + return _modal.Image.from_id(image_spec) + + # PR 4511: add python to ubuntu/debian images that don't have it + lower = image_spec.lower() + add_python = any(base in lower for base in ("ubuntu", "debian")) + + setup_commands = [ + "RUN rm -rf /usr/local/lib/python*/site-packages/pip* 2>/dev/null; " + "python -m ensurepip --upgrade --default-pip 2>/dev/null || true", + ] + if add_python: + setup_commands.insert(0, + "RUN apt-get update -qq && apt-get install -y -qq python3 python3-venv > /dev/null 2>&1 || true" + ) + + return _modal.Image.from_registry( + image_spec, + setup_dockerfile_commands=setup_commands, + ) + + +class _AsyncWorker: + """Background thread with its own event loop for async-safe Modal calls.""" + + def __init__(self): + self._loop: Optional[asyncio.AbstractEventLoop] = None + self._thread: Optional[threading.Thread] = None + self._started = threading.Event() + + def start(self): + self._thread = threading.Thread(target=self._run_loop, daemon=True) + self._thread.start() + self._started.wait(timeout=30) + + def _run_loop(self): + self._loop = asyncio.new_event_loop() + asyncio.set_event_loop(self._loop) + self._started.set() + self._loop.run_forever() + + def run_coroutine(self, coro, timeout=600): + if self._loop is None or self._loop.is_closed(): + raise RuntimeError("AsyncWorker loop is not running") + future = asyncio.run_coroutine_threadsafe(coro, self._loop) + return future.result(timeout=timeout) + + def stop(self): + if self._loop and self._loop.is_running(): + self._loop.call_soon_threadsafe(self._loop.stop) + if self._thread: + self._thread.join(timeout=10) + + +class ModalEnvironment(BaseEnvironment): + """Modal cloud execution via native Modal sandboxes. + + Spawn-per-call via _ThreadedProcessHandle wrapping async SDK calls. + cancel_fn wired to sandbox.terminate for interrupt support. + """ + + _stdin_mode = "heredoc" + _snapshot_timeout = 60 # Modal cold starts can be slow + + def __init__( + self, + image: str, + cwd: str = "/root", + timeout: int = 60, + modal_sandbox_kwargs: Optional[dict[str, Any]] = None, + persistent_filesystem: bool = True, + task_id: str = "default", + ): + super().__init__(cwd=cwd, timeout=timeout) + + self._persistent = persistent_filesystem + self._task_id = task_id + self._sandbox = None + self._app = None + self._worker = _AsyncWorker() + self._sync_manager: FileSyncManager | None = None # initialized after sandbox creation + + sandbox_kwargs = dict(modal_sandbox_kwargs or {}) + + restored_snapshot_id = None + restored_from_legacy_key = False + if self._persistent: + restored_snapshot_id, restored_from_legacy_key = _get_snapshot_restore_candidate( + self._task_id + ) + if restored_snapshot_id: + logger.info("Modal: restoring from snapshot %s", restored_snapshot_id[:20]) + + import modal as _modal + + cred_mounts = [] + try: + from tools.credential_files import ( + get_credential_file_mounts, + iter_skills_files, + iter_cache_files, + ) + + for mount_entry in get_credential_file_mounts(): + cred_mounts.append( + _modal.Mount.from_local_file( + mount_entry["host_path"], + remote_path=mount_entry["container_path"], + ) + ) + for entry in iter_skills_files(): + cred_mounts.append( + _modal.Mount.from_local_file( + entry["host_path"], + remote_path=entry["container_path"], + ) + ) + cache_files = iter_cache_files() + for entry in cache_files: + cred_mounts.append( + _modal.Mount.from_local_file( + entry["host_path"], + remote_path=entry["container_path"], + ) + ) + except Exception as e: + logger.debug("Modal: could not load credential file mounts: %s", e) + + self._worker.start() + + async def _create_sandbox(image_spec: Any): + app = await _modal.App.lookup.aio("hermes-agent", create_if_missing=True) + create_kwargs = dict(sandbox_kwargs) + if cred_mounts: + existing_mounts = list(create_kwargs.pop("mounts", [])) + existing_mounts.extend(cred_mounts) + create_kwargs["mounts"] = existing_mounts + sandbox = await _modal.Sandbox.create.aio( + "sleep", "infinity", + image=image_spec, + app=app, + timeout=int(create_kwargs.pop("timeout", 3600)), + **create_kwargs, + ) + return app, sandbox + + try: + target_image_spec = restored_snapshot_id or image + try: + effective_image = _resolve_modal_image(target_image_spec) + self._app, self._sandbox = self._worker.run_coroutine( + _create_sandbox(effective_image), timeout=300, + ) + except Exception as exc: + if not restored_snapshot_id: + raise + logger.warning( + "Modal: failed to restore snapshot %s, retrying with base image: %s", + restored_snapshot_id[:20], exc, + ) + _delete_direct_snapshot(self._task_id, restored_snapshot_id) + base_image = _resolve_modal_image(image) + self._app, self._sandbox = self._worker.run_coroutine( + _create_sandbox(base_image), timeout=300, + ) + else: + if restored_snapshot_id and restored_from_legacy_key: + _store_direct_snapshot(self._task_id, restored_snapshot_id) + except Exception: + self._worker.stop() + raise + + logger.info("Modal: sandbox created (task=%s)", self._task_id) + + self._sync_manager = FileSyncManager( + get_files_fn=lambda: iter_sync_files("/root/.hermes"), + upload_fn=self._modal_upload, + delete_fn=self._modal_delete, + bulk_upload_fn=self._modal_bulk_upload, + ) + self._sync_manager.sync(force=True) + self.init_session() + + def _modal_upload(self, host_path: str, remote_path: str) -> None: + """Upload a single file via base64 piped through stdin.""" + content = Path(host_path).read_bytes() + b64 = base64.b64encode(content).decode("ascii") + container_dir = str(Path(remote_path).parent) + cmd = ( + f"mkdir -p {shlex.quote(container_dir)} && " + f"base64 -d > {shlex.quote(remote_path)}" + ) + + async def _write(): + proc = await self._sandbox.exec.aio("bash", "-c", cmd) + offset = 0 + chunk_size = self._STDIN_CHUNK_SIZE + while offset < len(b64): + proc.stdin.write(b64[offset:offset + chunk_size]) + await proc.stdin.drain.aio() + offset += chunk_size + proc.stdin.write_eof() + await proc.stdin.drain.aio() + await proc.wait.aio() + + self._worker.run_coroutine(_write(), timeout=30) + + # Modal SDK stdin buffer limit (legacy server path). The command-router + # path allows 16 MB, but we must stay under the smaller 2 MB cap for + # compatibility. Chunks are written below this threshold and flushed + # individually via drain(). + _STDIN_CHUNK_SIZE = 1 * 1024 * 1024 # 1 MB — safe for both transport paths + + def _modal_bulk_upload(self, files: list[tuple[str, str]]) -> None: + """Upload many files via tar archive piped through stdin. + + Builds a gzipped tar archive in memory and streams it into a + ``base64 -d | tar xzf -`` pipeline via the process's stdin, + avoiding the Modal SDK's 64 KB ``ARG_MAX_BYTES`` exec-arg limit. + """ + if not files: + return + + buf = io.BytesIO() + with tarfile.open(fileobj=buf, mode="w:gz") as tar: + for host_path, remote_path in files: + tar.add(host_path, arcname=remote_path.lstrip("/")) + payload = base64.b64encode(buf.getvalue()).decode("ascii") + + parents = unique_parent_dirs(files) + mkdir_part = quoted_mkdir_command(parents) + cmd = f"{mkdir_part} && base64 -d | tar xzf - -C /" + + async def _bulk(): + proc = await self._sandbox.exec.aio("bash", "-c", cmd) + + # Stream payload through stdin in chunks to stay under the + # SDK's per-write buffer limit (2 MB legacy / 16 MB router). + offset = 0 + chunk_size = self._STDIN_CHUNK_SIZE + while offset < len(payload): + proc.stdin.write(payload[offset:offset + chunk_size]) + await proc.stdin.drain.aio() + offset += chunk_size + + proc.stdin.write_eof() + await proc.stdin.drain.aio() + + exit_code = await proc.wait.aio() + if exit_code != 0: + stderr_text = await proc.stderr.read.aio() + raise RuntimeError( + f"Modal bulk upload failed (exit {exit_code}): {stderr_text}" + ) + + self._worker.run_coroutine(_bulk(), timeout=120) + + def _modal_delete(self, remote_paths: list[str]) -> None: + """Batch-delete remote files via exec.""" + rm_cmd = quoted_rm_command(remote_paths) + + async def _rm(): + proc = await self._sandbox.exec.aio("bash", "-c", rm_cmd) + await proc.wait.aio() + + self._worker.run_coroutine(_rm(), timeout=15) + + def _before_execute(self) -> None: + """Sync files to sandbox via FileSyncManager (rate-limited internally).""" + self._sync_manager.sync() + + # ------------------------------------------------------------------ + # Execution + # ------------------------------------------------------------------ + + def _run_bash(self, cmd_string: str, *, login: bool = False, + timeout: int = 120, + stdin_data: str | None = None): + """Return a _ThreadedProcessHandle wrapping an async Modal sandbox exec.""" + sandbox = self._sandbox + worker = self._worker + + def cancel(): + worker.run_coroutine(sandbox.terminate.aio(), timeout=15) + + def exec_fn() -> tuple[str, int]: + async def _do(): + args = ["bash"] + if login: + args.extend(["-l", "-c", cmd_string]) + else: + args.extend(["-c", cmd_string]) + process = await sandbox.exec.aio(*args, timeout=timeout) + stdout = await process.stdout.read.aio() + stderr = await process.stderr.read.aio() + exit_code = await process.wait.aio() + if isinstance(stdout, bytes): + stdout = stdout.decode("utf-8", errors="replace") + if isinstance(stderr, bytes): + stderr = stderr.decode("utf-8", errors="replace") + output = stdout + if stderr: + output = f"{stdout}\n{stderr}" if stdout else stderr + return output, exit_code + + return worker.run_coroutine(_do(), timeout=timeout + 30) + + return _ThreadedProcessHandle(exec_fn, cancel_fn=cancel) + + def cleanup(self): + """Snapshot the filesystem (if persistent) then stop the sandbox.""" + if self._sandbox is None: + return + + if self._persistent: + try: + async def _snapshot(): + img = await self._sandbox.snapshot_filesystem.aio() + return img.object_id + + try: + snapshot_id = self._worker.run_coroutine(_snapshot(), timeout=60) + except Exception: + snapshot_id = None + + if snapshot_id: + _store_direct_snapshot(self._task_id, snapshot_id) + logger.info( + "Modal: saved filesystem snapshot %s for task %s", + snapshot_id[:20], self._task_id, + ) + except Exception as e: + logger.warning("Modal: filesystem snapshot failed: %s", e) + + try: + self._worker.run_coroutine(self._sandbox.terminate.aio(), timeout=15) + except Exception: + pass + finally: + self._worker.stop() + self._sandbox = None + self._app = None diff --git a/mindcli/_vendor/tools/environments/modal_utils.py b/mindcli/_vendor/tools/environments/modal_utils.py new file mode 100644 index 0000000..0db8194 --- /dev/null +++ b/mindcli/_vendor/tools/environments/modal_utils.py @@ -0,0 +1,186 @@ +"""Shared Hermes-side execution flow for Modal transports. + +This module deliberately stops at the Hermes boundary: +- command preparation +- cwd/timeout normalization +- stdin/sudo shell wrapping +- common result shape +- interrupt/cancel polling + +Direct Modal and managed Modal keep separate transport logic, persistence, and +trust-boundary decisions in their own modules. +""" + +from __future__ import annotations + +import shlex +import time +import uuid +from abc import abstractmethod +from dataclasses import dataclass +from typing import Any + +from tools.environments.base import BaseEnvironment +from tools.interrupt import is_interrupted + + +@dataclass(frozen=True) +class PreparedModalExec: + """Normalized command data passed to a transport-specific exec runner.""" + + command: str + cwd: str + timeout: int + stdin_data: str | None = None + + +@dataclass(frozen=True) +class ModalExecStart: + """Transport response after starting an exec.""" + + handle: Any | None = None + immediate_result: dict | None = None + + +def wrap_modal_stdin_heredoc(command: str, stdin_data: str) -> str: + """Append stdin as a shell heredoc for transports without stdin piping.""" + marker = f"HERMES_EOF_{uuid.uuid4().hex[:8]}" + while marker in stdin_data: + marker = f"HERMES_EOF_{uuid.uuid4().hex[:8]}" + return f"{command} << '{marker}'\n{stdin_data}\n{marker}" + + +def wrap_modal_sudo_pipe(command: str, sudo_stdin: str) -> str: + """Feed sudo via a shell pipe for transports without direct stdin piping.""" + return f"printf '%s\\n' {shlex.quote(sudo_stdin.rstrip())} | {command}" + + +class BaseModalExecutionEnvironment(BaseEnvironment): + """Execution flow for the *managed* Modal transport (gateway-owned sandbox). + + This deliberately overrides :meth:`BaseEnvironment.execute` because the + tool-gateway handles command preparation, CWD tracking, and env-snapshot + management on the server side. The base class's ``_wrap_command`` / + ``_wait_for_process`` / snapshot machinery does not apply here — the + gateway owns that responsibility. See ``ManagedModalEnvironment`` for the + concrete subclass. + """ + + _stdin_mode = "payload" + _poll_interval_seconds = 0.25 + _client_timeout_grace_seconds: float | None = None + _interrupt_output = "[Command interrupted]" + _unexpected_error_prefix = "Modal execution error" + + def execute( + self, + command: str, + cwd: str = "", + *, + timeout: int | None = None, + stdin_data: str | None = None, + ) -> dict: + self._before_execute() + prepared = self._prepare_modal_exec( + command, + cwd=cwd, + timeout=timeout, + stdin_data=stdin_data, + ) + + try: + start = self._start_modal_exec(prepared) + except Exception as exc: + return self._error_result(f"{self._unexpected_error_prefix}: {exc}") + + if start.immediate_result is not None: + return start.immediate_result + + if start.handle is None: + return self._error_result( + f"{self._unexpected_error_prefix}: transport did not return an exec handle" + ) + + deadline = None + if self._client_timeout_grace_seconds is not None: + deadline = time.monotonic() + prepared.timeout + self._client_timeout_grace_seconds + + while True: + if is_interrupted(): + try: + self._cancel_modal_exec(start.handle) + except Exception: + pass + return self._result(self._interrupt_output, 130) + + try: + result = self._poll_modal_exec(start.handle) + except Exception as exc: + return self._error_result(f"{self._unexpected_error_prefix}: {exc}") + + if result is not None: + return result + + if deadline is not None and time.monotonic() >= deadline: + try: + self._cancel_modal_exec(start.handle) + except Exception: + pass + return self._timeout_result_for_modal(prepared.timeout) + + time.sleep(self._poll_interval_seconds) + + def _before_execute(self) -> None: + """Hook for backends that need pre-exec sync or validation.""" + pass + + def _prepare_modal_exec( + self, + command: str, + *, + cwd: str = "", + timeout: int | None = None, + stdin_data: str | None = None, + ) -> PreparedModalExec: + effective_cwd = cwd or self.cwd + effective_timeout = timeout or self.timeout + + exec_command = command + exec_stdin = stdin_data if self._stdin_mode == "payload" else None + if stdin_data is not None and self._stdin_mode == "heredoc": + exec_command = wrap_modal_stdin_heredoc(exec_command, stdin_data) + + exec_command, sudo_stdin = self._prepare_command(exec_command) + if sudo_stdin is not None: + exec_command = wrap_modal_sudo_pipe(exec_command, sudo_stdin) + + return PreparedModalExec( + command=exec_command, + cwd=effective_cwd, + timeout=effective_timeout, + stdin_data=exec_stdin, + ) + + def _result(self, output: str, returncode: int) -> dict: + return { + "output": output, + "returncode": returncode, + } + + def _error_result(self, output: str) -> dict: + return self._result(output, 1) + + def _timeout_result_for_modal(self, timeout: int) -> dict: + return self._result(f"Command timed out after {timeout}s", 124) + + @abstractmethod + def _start_modal_exec(self, prepared: PreparedModalExec) -> ModalExecStart: + """Begin a transport-specific exec.""" + + @abstractmethod + def _poll_modal_exec(self, handle: Any) -> dict | None: + """Return a final result dict when complete, else ``None``.""" + + @abstractmethod + def _cancel_modal_exec(self, handle: Any) -> None: + """Cancel or terminate the active transport exec.""" diff --git a/mindcli/_vendor/tools/environments/singularity.py b/mindcli/_vendor/tools/environments/singularity.py new file mode 100644 index 0000000..16d1013 --- /dev/null +++ b/mindcli/_vendor/tools/environments/singularity.py @@ -0,0 +1,262 @@ +"""Singularity/Apptainer persistent container environment. + +Security-hardened with --containall, --no-home, capability dropping. +Supports configurable resource limits and optional filesystem persistence +via writable overlay directories that survive across sessions. +""" + +import logging +import os +import shutil +import subprocess +import threading +import uuid +from pathlib import Path +from typing import Optional + +from hermes_constants import get_hermes_home +from tools.environments.base import ( + BaseEnvironment, + _load_json_store, + _popen_bash, + _save_json_store, +) + +logger = logging.getLogger(__name__) + +_SNAPSHOT_STORE = get_hermes_home() / "singularity_snapshots.json" + + +def _find_singularity_executable() -> str: + """Locate the apptainer or singularity CLI binary.""" + if shutil.which("apptainer"): + return "apptainer" + if shutil.which("singularity"): + return "singularity" + raise RuntimeError( + "Neither 'apptainer' nor 'singularity' was found in PATH. " + "Install Apptainer (https://apptainer.org/docs/admin/main/installation.html) " + "or Singularity and ensure the CLI is available." + ) + + +def _ensure_singularity_available() -> str: + """Preflight check: resolve the executable and verify it responds.""" + exe = _find_singularity_executable() + try: + result = subprocess.run( + [exe, "version"], capture_output=True, text=True, timeout=10, + ) + except FileNotFoundError: + raise RuntimeError( + f"Singularity backend selected but '{exe}' could not be executed." + ) + except subprocess.TimeoutExpired: + raise RuntimeError(f"'{exe} version' timed out.") + + if result.returncode != 0: + stderr = result.stderr.strip()[:200] + raise RuntimeError(f"'{exe} version' failed (exit code {result.returncode}): {stderr}") + return exe + + +def _load_snapshots() -> dict: + return _load_json_store(_SNAPSHOT_STORE) + + +def _save_snapshots(data: dict) -> None: + _save_json_store(_SNAPSHOT_STORE, data) + + +def _get_scratch_dir() -> Path: + custom_scratch = os.getenv("TERMINAL_SCRATCH_DIR") + if custom_scratch: + scratch_path = Path(custom_scratch) + scratch_path.mkdir(parents=True, exist_ok=True) + return scratch_path + + from tools.environments.base import get_sandbox_dir + sandbox = get_sandbox_dir() / "singularity" + + scratch = Path("/scratch") + if scratch.exists() and os.access(scratch, os.W_OK): + user_scratch = scratch / os.getenv("USER", "hermes") / "hermes-agent" + user_scratch.mkdir(parents=True, exist_ok=True) + logger.info("Using /scratch for sandboxes: %s", user_scratch) + return user_scratch + + sandbox.mkdir(parents=True, exist_ok=True) + return sandbox + + +def _get_apptainer_cache_dir() -> Path: + cache_dir = os.getenv("APPTAINER_CACHEDIR") + if cache_dir: + cache_path = Path(cache_dir) + cache_path.mkdir(parents=True, exist_ok=True) + return cache_path + scratch = _get_scratch_dir() + cache_path = scratch / ".apptainer" + cache_path.mkdir(parents=True, exist_ok=True) + return cache_path + + +_sif_build_lock = threading.Lock() + + +def _get_or_build_sif(image: str, executable: str = "apptainer") -> str: + if image.endswith('.sif') and Path(image).exists(): + return image + if not image.startswith('docker://'): + return image + + image_name = image.replace('docker://', '').replace('/', '-').replace(':', '-') + cache_dir = _get_apptainer_cache_dir() + sif_path = cache_dir / f"{image_name}.sif" + + if sif_path.exists(): + return str(sif_path) + + with _sif_build_lock: + if sif_path.exists(): + return str(sif_path) + + logger.info("Building SIF image (one-time setup)...") + logger.info(" Source: %s", image) + logger.info(" Target: %s", sif_path) + + tmp_dir = cache_dir / "tmp" + tmp_dir.mkdir(parents=True, exist_ok=True) + + env = os.environ.copy() + env["APPTAINER_TMPDIR"] = str(tmp_dir) + env["APPTAINER_CACHEDIR"] = str(cache_dir) + + try: + result = subprocess.run( + [executable, "build", str(sif_path), image], + capture_output=True, text=True, timeout=600, env=env, + ) + if result.returncode != 0: + logger.warning("SIF build failed, falling back to docker:// URL") + logger.warning(" Error: %s", result.stderr[:500]) + return image + logger.info("SIF image built successfully") + return str(sif_path) + except subprocess.TimeoutExpired: + logger.warning("SIF build timed out, falling back to docker:// URL") + if sif_path.exists(): + sif_path.unlink() + return image + except Exception as e: + logger.warning("SIF build error: %s, falling back to docker:// URL", e) + return image + + +class SingularityEnvironment(BaseEnvironment): + """Hardened Singularity/Apptainer container with resource limits and persistence. + + Spawn-per-call: every execute() spawns a fresh ``apptainer exec ... bash -c`` process. + Session snapshot preserves env vars across calls. + CWD persists via in-band stdout markers. + """ + + def __init__( + self, + image: str, + cwd: str = "~", + timeout: int = 60, + cpu: float = 0, + memory: int = 0, + disk: int = 0, + persistent_filesystem: bool = False, + task_id: str = "default", + ): + super().__init__(cwd=cwd, timeout=timeout) + self.executable = _ensure_singularity_available() + self.image = _get_or_build_sif(image, self.executable) + self.instance_id = f"hermes_{uuid.uuid4().hex[:12]}" + self._instance_started = False + self._persistent = persistent_filesystem + self._task_id = task_id + self._overlay_dir: Optional[Path] = None + self._cpu = cpu + self._memory = memory + + if self._persistent: + overlay_base = _get_scratch_dir() / "hermes-overlays" + overlay_base.mkdir(parents=True, exist_ok=True) + self._overlay_dir = overlay_base / f"overlay-{task_id}" + self._overlay_dir.mkdir(parents=True, exist_ok=True) + + self._start_instance() + self.init_session() + + def _start_instance(self): + cmd = [self.executable, "instance", "start"] + cmd.extend(["--containall", "--no-home"]) + + if self._persistent and self._overlay_dir: + cmd.extend(["--overlay", str(self._overlay_dir)]) + else: + cmd.append("--writable-tmpfs") + + try: + from tools.credential_files import get_credential_file_mounts, get_skills_directory_mount + for mount_entry in get_credential_file_mounts(): + cmd.extend(["--bind", f"{mount_entry['host_path']}:{mount_entry['container_path']}:ro"]) + for skills_mount in get_skills_directory_mount(): + cmd.extend(["--bind", f"{skills_mount['host_path']}:{skills_mount['container_path']}:ro"]) + except Exception as e: + logger.debug("Singularity: could not load credential/skills mounts: %s", e) + + if self._memory > 0: + cmd.extend(["--memory", f"{self._memory}M"]) + if self._cpu > 0: + cmd.extend(["--cpus", str(self._cpu)]) + + cmd.extend([str(self.image), self.instance_id]) + + try: + result = subprocess.run(cmd, capture_output=True, text=True, timeout=120) + if result.returncode != 0: + raise RuntimeError(f"Failed to start instance: {result.stderr}") + self._instance_started = True + logger.info("Singularity instance %s started (persistent=%s)", + self.instance_id, self._persistent) + except subprocess.TimeoutExpired: + raise RuntimeError("Instance start timed out") + + def _run_bash(self, cmd_string: str, *, login: bool = False, + timeout: int = 120, + stdin_data: str | None = None) -> subprocess.Popen: + """Spawn a bash process inside the Singularity instance.""" + if not self._instance_started: + raise RuntimeError("Singularity instance not started") + + cmd = [self.executable, "exec", + f"instance://{self.instance_id}"] + if login: + cmd.extend(["bash", "-l", "-c", cmd_string]) + else: + cmd.extend(["bash", "-c", cmd_string]) + + return _popen_bash(cmd, stdin_data) + + def cleanup(self): + """Stop the instance. If persistent, the overlay dir survives.""" + if self._instance_started: + try: + subprocess.run( + [self.executable, "instance", "stop", self.instance_id], + capture_output=True, text=True, timeout=30, + ) + logger.info("Singularity instance %s stopped", self.instance_id) + except Exception as e: + logger.warning("Failed to stop Singularity instance %s: %s", self.instance_id, e) + self._instance_started = False + + if self._persistent and self._overlay_dir: + snapshots = _load_snapshots() + snapshots[self._task_id] = str(self._overlay_dir) + _save_snapshots(snapshots) diff --git a/mindcli/_vendor/tools/environments/ssh.py b/mindcli/_vendor/tools/environments/ssh.py new file mode 100644 index 0000000..0491764 --- /dev/null +++ b/mindcli/_vendor/tools/environments/ssh.py @@ -0,0 +1,258 @@ +"""SSH remote execution environment with ControlMaster connection persistence.""" + +import logging +import os +import shlex +import shutil +import subprocess +import tempfile +from pathlib import Path + +from tools.environments.base import BaseEnvironment, _popen_bash +from tools.environments.file_sync import ( + FileSyncManager, + iter_sync_files, + quoted_mkdir_command, + quoted_rm_command, + unique_parent_dirs, +) + +logger = logging.getLogger(__name__) + + +def _ensure_ssh_available() -> None: + """Fail fast with a clear error when the SSH client is unavailable.""" + if not shutil.which("ssh"): + raise RuntimeError( + "SSH is not installed or not in PATH. Install OpenSSH client: apt install openssh-client" + ) + + +class SSHEnvironment(BaseEnvironment): + """Run commands on a remote machine over SSH. + + Spawn-per-call: every execute() spawns a fresh ``ssh ... bash -c`` process. + Session snapshot preserves env vars across calls. + CWD persists via in-band stdout markers. + Uses SSH ControlMaster for connection reuse. + """ + + def __init__(self, host: str, user: str, cwd: str = "~", + timeout: int = 60, port: int = 22, key_path: str = ""): + super().__init__(cwd=cwd, timeout=timeout) + self.host = host + self.user = user + self.port = port + self.key_path = key_path + + self.control_dir = Path(tempfile.gettempdir()) / "hermes-ssh" + self.control_dir.mkdir(parents=True, exist_ok=True) + self.control_socket = self.control_dir / f"{user}@{host}:{port}.sock" + _ensure_ssh_available() + self._establish_connection() + self._remote_home = self._detect_remote_home() + + self._ensure_remote_dirs() + self._sync_manager = FileSyncManager( + get_files_fn=lambda: iter_sync_files(f"{self._remote_home}/.hermes"), + upload_fn=self._scp_upload, + delete_fn=self._ssh_delete, + bulk_upload_fn=self._ssh_bulk_upload, + ) + self._sync_manager.sync(force=True) + + self.init_session() + + def _build_ssh_command(self, extra_args: list | None = None) -> list: + cmd = ["ssh"] + cmd.extend(["-o", f"ControlPath={self.control_socket}"]) + cmd.extend(["-o", "ControlMaster=auto"]) + cmd.extend(["-o", "ControlPersist=300"]) + cmd.extend(["-o", "BatchMode=yes"]) + cmd.extend(["-o", "StrictHostKeyChecking=accept-new"]) + cmd.extend(["-o", "ConnectTimeout=10"]) + if self.port != 22: + cmd.extend(["-p", str(self.port)]) + if self.key_path: + cmd.extend(["-i", self.key_path]) + if extra_args: + cmd.extend(extra_args) + cmd.append(f"{self.user}@{self.host}") + return cmd + + def _establish_connection(self): + cmd = self._build_ssh_command() + cmd.append("echo 'SSH connection established'") + try: + result = subprocess.run(cmd, capture_output=True, text=True, timeout=15) + if result.returncode != 0: + error_msg = result.stderr.strip() or result.stdout.strip() + raise RuntimeError(f"SSH connection failed: {error_msg}") + except subprocess.TimeoutExpired: + raise RuntimeError(f"SSH connection to {self.user}@{self.host} timed out") + + def _detect_remote_home(self) -> str: + """Detect the remote user's home directory.""" + try: + cmd = self._build_ssh_command() + cmd.append("echo $HOME") + result = subprocess.run(cmd, capture_output=True, text=True, timeout=10) + home = result.stdout.strip() + if home and result.returncode == 0: + logger.debug("SSH: remote home = %s", home) + return home + except Exception: + pass + if self.user == "root": + return "/root" + return f"/home/{self.user}" + + # ------------------------------------------------------------------ + # File sync (via FileSyncManager) + # ------------------------------------------------------------------ + + def _ensure_remote_dirs(self) -> None: + """Create base ~/.hermes directory tree on remote in one SSH call.""" + base = f"{self._remote_home}/.hermes" + dirs = [base, f"{base}/skills", f"{base}/credentials", f"{base}/cache"] + cmd = self._build_ssh_command() + cmd.append(quoted_mkdir_command(dirs)) + subprocess.run(cmd, capture_output=True, text=True, timeout=10) + + # _get_sync_files provided via iter_sync_files in FileSyncManager init + + def _scp_upload(self, host_path: str, remote_path: str) -> None: + """Upload a single file via scp over ControlMaster.""" + parent = str(Path(remote_path).parent) + mkdir_cmd = self._build_ssh_command() + mkdir_cmd.append(f"mkdir -p {shlex.quote(parent)}") + subprocess.run(mkdir_cmd, capture_output=True, text=True, timeout=10) + + scp_cmd = ["scp", "-o", f"ControlPath={self.control_socket}"] + if self.port != 22: + scp_cmd.extend(["-P", str(self.port)]) + if self.key_path: + scp_cmd.extend(["-i", self.key_path]) + scp_cmd.extend([host_path, f"{self.user}@{self.host}:{remote_path}"]) + result = subprocess.run(scp_cmd, capture_output=True, text=True, timeout=30) + if result.returncode != 0: + raise RuntimeError(f"scp failed: {result.stderr.strip()}") + + def _ssh_bulk_upload(self, files: list[tuple[str, str]]) -> None: + """Upload many files in a single tar-over-SSH stream. + + Pipes ``tar c`` on the local side through an SSH connection to + ``tar x`` on the remote, transferring all files in one TCP stream + instead of spawning a subprocess per file. Directory creation is + batched into a single ``mkdir -p`` call beforehand. + + Typical improvement: ~580 files goes from O(N) scp round-trips + to a single streaming transfer. + """ + if not files: + return + + parents = unique_parent_dirs(files) + if parents: + cmd = self._build_ssh_command() + cmd.append(quoted_mkdir_command(parents)) + result = subprocess.run(cmd, capture_output=True, text=True, timeout=30) + if result.returncode != 0: + raise RuntimeError(f"remote mkdir failed: {result.stderr.strip()}") + + # Symlink staging avoids fragile GNU tar --transform rules. + with tempfile.TemporaryDirectory(prefix="hermes-ssh-bulk-") as staging: + for host_path, remote_path in files: + staged = os.path.join(staging, remote_path.lstrip("/")) + os.makedirs(os.path.dirname(staged), exist_ok=True) + os.symlink(os.path.abspath(host_path), staged) + + tar_cmd = ["tar", "-chf", "-", "-C", staging, "."] + ssh_cmd = self._build_ssh_command() + ssh_cmd.append("tar xf - -C /") + + tar_proc = subprocess.Popen( + tar_cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE + ) + try: + ssh_proc = subprocess.Popen( + ssh_cmd, stdin=tar_proc.stdout, stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + ) + except Exception: + tar_proc.kill() + tar_proc.wait() + raise + + # Allow tar_proc to receive SIGPIPE if ssh_proc exits early + tar_proc.stdout.close() + + try: + _, ssh_stderr = ssh_proc.communicate(timeout=120) + # Use communicate() instead of wait() to drain stderr and + # avoid deadlock if tar produces more than PIPE_BUF of errors. + tar_stderr_raw = b"" + if tar_proc.poll() is None: + _, tar_stderr_raw = tar_proc.communicate(timeout=10) + else: + tar_stderr_raw = tar_proc.stderr.read() if tar_proc.stderr else b"" + except subprocess.TimeoutExpired: + tar_proc.kill() + ssh_proc.kill() + tar_proc.wait() + ssh_proc.wait() + raise RuntimeError("SSH bulk upload timed out") + + if tar_proc.returncode != 0: + raise RuntimeError( + f"tar create failed (rc={tar_proc.returncode}): " + f"{tar_stderr_raw.decode(errors='replace').strip()}" + ) + if ssh_proc.returncode != 0: + raise RuntimeError( + f"tar extract over SSH failed (rc={ssh_proc.returncode}): " + f"{ssh_stderr.decode(errors='replace').strip()}" + ) + + logger.debug("SSH: bulk-uploaded %d file(s) via tar pipe", len(files)) + + def _ssh_delete(self, remote_paths: list[str]) -> None: + """Batch-delete remote files in one SSH call.""" + cmd = self._build_ssh_command() + cmd.append(quoted_rm_command(remote_paths)) + result = subprocess.run(cmd, capture_output=True, text=True, timeout=10) + if result.returncode != 0: + raise RuntimeError(f"remote rm failed: {result.stderr.strip()}") + + def _before_execute(self) -> None: + """Sync files to remote via FileSyncManager (rate-limited internally).""" + self._sync_manager.sync() + + # ------------------------------------------------------------------ + # Execution + # ------------------------------------------------------------------ + + def _run_bash(self, cmd_string: str, *, login: bool = False, + timeout: int = 120, + stdin_data: str | None = None) -> subprocess.Popen: + """Spawn an SSH process that runs bash on the remote host.""" + cmd = self._build_ssh_command() + if login: + cmd.extend(["bash", "-l", "-c", shlex.quote(cmd_string)]) + else: + cmd.extend(["bash", "-c", shlex.quote(cmd_string)]) + + return _popen_bash(cmd, stdin_data) + + def cleanup(self): + if self.control_socket.exists(): + try: + cmd = ["ssh", "-o", f"ControlPath={self.control_socket}", + "-O", "exit", f"{self.user}@{self.host}"] + subprocess.run(cmd, capture_output=True, timeout=5) + except (OSError, subprocess.SubprocessError): + pass + try: + self.control_socket.unlink() + except OSError: + pass diff --git a/mindcli/_vendor/tools/feishu_tool.py b/mindcli/_vendor/tools/feishu_tool.py new file mode 100644 index 0000000..d837902 --- /dev/null +++ b/mindcli/_vendor/tools/feishu_tool.py @@ -0,0 +1,788 @@ +""" +飞书连接器工具 (feishu_tool.py) — v5：同步抽象层 + +核心设计： + _run_cli(*args, timeout) — 唯一的子进程执行入口，subprocess.run() 同步调用。 + _run_cli_pty(*args, timeout) — 需要 PTY 的命令（config init），用 script -qc 包装。 + + 所有工具 handler 都是同步函数，在任何线程上下文（主线程 / SSE worker / executor） + 都能可靠执行。不再使用 asyncio.run() / create_subprocess_exec。 + + 后台轮询（device-code polling）使用 threading.Thread + subprocess.run。 + +工具清单： + feishu_list_profiles — 列出当前用户飞书账号 + feishu_init_profile — 创建新 profile（PTY），返回授权 URL + feishu_auth_domain — Device Flow 授权域 + feishu_query — 白名单数据操作 +""" + +import json +import logging +import re +import shutil +import subprocess +import threading +import time +from pathlib import Path +from typing import Any, Dict, Optional + +from tools.registry import registry, tool_error, tool_result + +logger = logging.getLogger(__name__) + +_LARK_CLI = "lark-cli" +_URL_FEISHU_RE = re.compile(r"https://\S+feishu\S+") + + +def _check_lark_cli() -> bool: + return shutil.which(_LARK_CLI) is not None + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# 通用子进程抽象层 +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +def _run_cli(*args: str, timeout: int = 30) -> tuple: + """ + 同步执行 lark-cli 命令。任何线程安全。 + 返回 (stdout: str, stderr: str, returncode: int) + """ + cmd = [_LARK_CLI] + list(args) + logger.info("[FeishuTool] exec: %s", " ".join(cmd)) + try: + r = subprocess.run( + cmd, + capture_output=True, + timeout=timeout, + text=True, + ) + return r.stdout.strip(), r.stderr.strip(), r.returncode + except subprocess.TimeoutExpired: + return "", f"命令超时（{timeout}s）", -1 + except FileNotFoundError: + return "", "lark-cli 未安装", -2 + + +def _run_cli_pty(inner_cmd: str, timeout: int = 25) -> str: + """ + 通过 `script -qc` 分配 PTY 执行命令，流式读取 stdout。 + + 关键设计：用 Popen + readline（非 subprocess.run），找到目标内容立即返回。 + 原因：config init 会阻塞 600s 等用户点授权链接，subprocess.run 必须等进程退出 + 才把 stdout 交回，永远拿不到 URL。改为逐行读，找到 URL 就返回，进程留在后台。 + """ + import threading + + cmd = ["script", "-qc", inner_cmd, "/dev/null"] + logger.info("[FeishuTool] exec-pty (stream): %s", inner_cmd) + + lines: list = [] + done = threading.Event() + + try: + proc = subprocess.Popen( + cmd, + stdout=subprocess.PIPE, + stderr=subprocess.DEVNULL, + text=True, + bufsize=1, + ) + except FileNotFoundError: + return "" + + def _read(): + try: + assert proc.stdout + for line in proc.stdout: + lines.append(line) + logger.debug("[FeishuTool] pty: %r", line[:80]) + if _URL_FEISHU_RE.search(line): + done.set() # URL 已找到，通知主线程返回 + except Exception as e: + logger.debug("[FeishuTool] pty reader: %s", e) + finally: + done.set() # 进程结束也通知 + + t = threading.Thread(target=_read, daemon=True) + t.start() + done.wait(timeout=timeout) # 找到 URL 或超时就返回 + # 不 kill 进程——让 config init 继续等用户点击并完成注册 + + return "".join(lines) + + +def _parse_json(text: str) -> Optional[dict]: + """从多行文本中提取第一个 JSON 对象。""" + for line in text.splitlines(): + line = line.strip() + if not line: + continue + try: + obj = json.loads(line) + if isinstance(obj, dict): + return obj + except json.JSONDecodeError: + continue + # 尝试整体解析（可能是多行 JSON） + try: + obj = json.loads(text) + if isinstance(obj, dict): + return obj + except (json.JSONDecodeError, ValueError): + pass + return None + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# Profile 隔离工具 +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# 飞书元数据存储（wiki/{userId}/.config/feishu.json） +# 格式：{ "aliases": { profileName: alias }, "pending": { profileName: timestamp } } +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +from tools._user_config import user_config_read, user_config_write + +_PENDING_TTL_SECONDS = 10 * 60 # 10 分钟 + + +def _uid_from_profile(profile_name: str) -> str: + """从 profileName (如 '11c1cece-242_1') 反推 userId 前缀用于查找。 + 实际的 userId 需要通过 _find_full_uid() 匹配。""" + return profile_name.rsplit("_", 1)[0] # '11c1cece-242' + + +def _feishu_config_read(user_id: str) -> dict: + """读取该用户的飞书配置（aliases + pending）""" + data = user_config_read(user_id, "feishu") + data.setdefault("aliases", {}) + data.setdefault("pending", {}) + return data + + +def _feishu_config_write(user_id: str, data: dict) -> None: + """写入该用户的飞书配置""" + user_config_write(user_id, "feishu", data) + + +def _pending_register(profile_name: str, user_id: str = "") -> None: + """将新建的 profile 写入待定登记表。""" + if not user_id: + return + data = _feishu_config_read(user_id) + data["pending"][profile_name] = time.time() + _feishu_config_write(user_id, data) + + +def _pending_remove(profile_name: str, user_id: str = "") -> None: + """从待定登记表中移除（授权完成或已清理）。""" + if not user_id: + return + data = _feishu_config_read(user_id) + data["pending"].pop(profile_name, None) + _feishu_config_write(user_id, data) + + +def _pending_get_ts(profile_name: str, user_id: str = "") -> float: + """返回 pending 中该 profile 的创建时间戳，不存在返回 0。""" + if not user_id: + return 0 + data = _feishu_config_read(user_id) + return data["pending"].get(profile_name, 0) + + +def _alias_get(profile_name: str, user_id: str = "") -> str: + """返回 profile 的 alias，没有则返回空字符串。""" + if not user_id: + return "" + data = _feishu_config_read(user_id) + return data["aliases"].get(profile_name, "") + + +def _alias_set(profile_name: str, alias: str, user_id: str = "") -> None: + """设置或更新 profile 的 alias。alias 为空时删除条目。""" + if not user_id: + return + data = _feishu_config_read(user_id) + if alias: + data["aliases"][profile_name] = alias + else: + data["aliases"].pop(profile_name, None) + _feishu_config_write(user_id, data) + + +def _make_profile_name(user_id: str, index: int = 1) -> str: + return f"{user_id[:12]}_{index}" + + +def _get_all_profiles() -> list: + stdout, _, rc = _run_cli("profile", "list", timeout=10) + if rc != 0: + return [] + try: + parsed = json.loads(stdout) + return parsed if isinstance(parsed, list) else [] + except (json.JSONDecodeError, ValueError): + return [] + + +def _filter_user_profiles(profiles: list, user_id: str) -> list: + prefix = user_id[:12] + "_" + result = [] + for p in profiles: + name = p.get("name", p) if isinstance(p, dict) else str(p) + if name.startswith(prefix): + result.append(p) + return result + + +def _get_profile_name(p) -> str: + """从 profile 条目中提取名字（兼容 str 和 dict 两种格式）。""" + if isinstance(p, dict): + return p.get("name", "") + return str(p) + + +def _check_profile_token(profile_name: str, user_id: str = "") -> Optional[dict]: + """ + 检查 profile 是否有有效 token。 + 返回 auth status dict（含 expiresAt 等），或 None（无 token / 超时）。 + 自动清理超时未授权的 pending profile。 + """ + stdout, _, rc = _run_cli("auth", "status", "--profile", profile_name, timeout=8) + if rc != 0: + # 没有 token 或命令失败 → 检查 pending 超时 + created_at = _pending_get_ts(profile_name, user_id=user_id) + if created_at and (time.time() - created_at) > _PENDING_TTL_SECONDS: + logger.info("[FeishuTool] pending profile 超时，自动清理: %s", profile_name) + _run_cli("profile", "delete", "--name", profile_name, timeout=5) + _pending_remove(profile_name, user_id=user_id) + return None + # 解析 JSON + try: + data = json.loads(stdout) + expires_at = data.get("expiresAt", "") + if not expires_at: + return None + # 判断 tokenStatus + token_status = data.get("tokenStatus", "") + # 如果是 valid 或 needs_refresh，都认为是有效授权的 profile + if token_status not in ["valid", "needs_refresh"]: + return None + _pending_remove(profile_name, user_id=user_id) + return data + except Exception: + return None + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# ① feishu_list_profiles +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +def _feishu_list_profiles_handler(args: dict, **kwargs) -> str: + user_id = str(args.get("user_id", "")).strip() + if not user_id: + return tool_error("user_id 参数必填") + + all_profiles = _get_all_profiles() + user_profiles = _filter_user_profiles(all_profiles, user_id) + + # 只返回有有效 token 的 profile（自动清理超时垃圾 profile） + active_profiles = [] + for p in user_profiles: + name = _get_profile_name(p) + token_info = _check_profile_token(name, user_id=user_id) + if token_info: + entry = { + "name": name, + "active": True, + "user": token_info.get("identity", ""), + "tokenStatus": token_info.get("tokenStatus", "valid"), + "expiresAt": token_info.get("expiresAt", ""), + "alias": _alias_get(name, user_id=user_id), + } + active_profiles.append(entry) + + return tool_result( + success=True, + profiles=active_profiles, + count=len(active_profiles), + message=( + f"找到 {len(active_profiles)} 个已授权的飞书账号。" + if active_profiles else "尚未绑定任何飞书账号。" + ), + ) + + +registry.register( + name="feishu_list_profiles", + toolset="connectors", + description="列出当前用户已绑定的所有飞书账号。", + emoji="📋", + check_fn=_check_lark_cli, + handler=_feishu_list_profiles_handler, + schema={ + "name": "feishu_list_profiles", + "description": "列出当前用户的所有飞书 profile。", + "parameters": { + "type": "object", + "properties": { + "user_id": { + "type": "string", + "description": "当前 MindOS 用户 ID（MINDOS_USER_ID）", + }, + }, + "required": ["user_id"], + }, + }, +) + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# ① feishu_rename_profile（设置别名） +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +def _feishu_rename_profile_handler(args: dict, **kwargs) -> str: + user_id = str(args.get("user_id", "")).strip() + profile_name = str(args.get("profile_name", "")).strip() + alias = str(args.get("alias", "")).strip() + + if not user_id or not profile_name: + return tool_error("user_id 和 profile_name 参数必填") + + # 安全校验：必须属于当前用户 + prefix = user_id[:12] + "_" + if not profile_name.startswith(prefix): + return tool_error(f"profile '{profile_name}' 不属于当前用户") + + _alias_set(profile_name, alias, user_id=user_id) + return tool_result( + success=True, + profile_name=profile_name, + alias=alias or None, + message=f"已{'设置' if alias else '清除'}别名：{profile_name} → {alias or '(无)'}", + ) + + +registry.register( + name="feishu_rename_profile", + toolset="connectors", + description="为飞书 profile 设置（或清除）用户友好的别名。", + emoji="✏️", + check_fn=_check_lark_cli, + handler=_feishu_rename_profile_handler, + schema={ + "name": "feishu_rename_profile", + "description": "为指定飞书 profile 设置别名（如'企业号'、'个人号'）。alias 传空字符串则清除别名。", + "parameters": { + "type": "object", + "properties": { + "user_id": {"type": "string", "description": "MindOS 用户 ID"}, + "profile_name": {"type": "string", "description": "lark-cli profile 名（如 11c1cece-242_1）"}, + "alias": {"type": "string", "description": "用户友好别名，如'企业号'。传空字符串清除别名"}, + }, + "required": ["user_id", "profile_name", "alias"], + }, + }, +) + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# ② feishu_init_profile（PTY 模式） +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +def _feishu_init_profile_handler(args: dict, **kwargs) -> str: + user_id = str(args.get("user_id", "")).strip() + if not user_id: + return tool_error("user_id 参数必填") + + account_name = str(args.get("account_name", "")).strip() + + all_profiles = _get_all_profiles() + user_profiles = _filter_user_profiles(all_profiles, user_id) + next_index = len(user_profiles) + 1 + + if account_name: + profile_name = f"{user_id[:12]}_{account_name}" + else: + profile_name = _make_profile_name(user_id, next_index) + + # 检查是否已存在 + all_names = [_get_profile_name(p) for p in all_profiles] + if profile_name in all_names: + # 如果已存在但仍在 pending（用户之前没完成授权），视为重试 + token = _check_profile_token(profile_name, user_id=user_id) + if token: + return tool_result( + success=True, + profile_name=profile_name, + status="already_exists", + message=f"Profile '{profile_name}' 已存在且已授权。可直接进行域授权。", + ) + # 没有有效 token → 重新走 init（可能用户上次没完成） + + # 通过 PTY 执行 config init（流式读取，找到 URL 立即返回） + inner_cmd = f"{_LARK_CLI} config init --new --name {profile_name}" + stdout = _run_cli_pty(inner_cmd, timeout=25) + + # 提取 URL + m = _URL_FEISHU_RE.search(stdout) + if m: + _pending_register(profile_name, user_id=user_id) # 写入待定登记表，启动 10 分钟超时计时 + return tool_result( + success=True, + profile_name=profile_name, + verification_url=m.group(0), + message="请点击链接在飞书中创建应用。完成后告诉我。", + ) + + return tool_error( + "未获取到飞书授权链接。请检查服务器网络。" + ) + + +registry.register( + name="feishu_init_profile", + toolset="connectors", + description="创建新飞书 Profile 并返回授权 URL。", + emoji="🔗", + check_fn=_check_lark_cli, + handler=_feishu_init_profile_handler, + schema={ + "name": "feishu_init_profile", + "description": ( + "为当前用户创建新的飞书 profile。返回 verification_url。" + "用户完成后再调 feishu_auth_domain 进行域授权。" + ), + "parameters": { + "type": "object", + "properties": { + "user_id": { + "type": "string", + "description": "MINDOS_USER_ID", + }, + "account_name": { + "type": "string", + "description": "可选别名（如 work、personal）", + }, + }, + "required": ["user_id"], + }, + }, +) + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# ③ feishu_auth_domain（同步 Device Flow） +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +_AUTH_DOMAINS = { + "approval", "attendance", "base", "calendar", "contact", + "docs", "drive", "event", "im", "mail", "minutes", + "sheets", "slides", "task", "vc", "wiki", "all", +} + + +def _poll_device_code_bg(profile_name: str, device_code: str, domain: str) -> None: + """后台线程：同步轮询 --device-code 直到用户完成授权。""" + stdout, stderr, rc = _run_cli( + "auth", "login", + "--device-code", device_code, + "--json", + "--profile", profile_name, + timeout=620, + ) + logger.info( + "[FeishuTool] poll done %s/%s (rc=%d): %s", + profile_name, domain, rc, stdout[:200], + ) + + +def _feishu_auth_domain_handler(args: dict, **kwargs) -> str: + user_id = str(args.get("user_id", "")).strip() + if not user_id: + return tool_error("user_id 参数必填") + + domain = str(args.get("domain", "")).strip().lower() + if not domain: + return tool_error("domain 参数必填") + for d in domain.split(","): + d = d.strip() + if d and d not in _AUTH_DOMAINS: + return tool_error(f"不支持的 domain：{d}") + + profile_name = str(args.get("profile_name", "")).strip() + if not profile_name: + all_profiles = _get_all_profiles() + user_profiles = _filter_user_profiles(all_profiles, user_id) + if not user_profiles: + return tool_error("没有飞书 profile。请先调用 feishu_init_profile。") + profile_name = _get_profile_name(user_profiles[0]) + + # 同步执行 auth login --no-wait（立即返回 JSON） + stdout, stderr, rc = _run_cli( + "auth", "login", + "--domain", domain, + "--json", "--no-wait", + "--profile", profile_name, + timeout=15, + ) + + if rc != 0 and not stdout: + return tool_error(f"auth 失败（exit {rc}）：{stderr[:200]}") + + data = _parse_json(stdout) + + if not data: + return tool_error( + f"lark-cli 无 JSON 输出。" + f"请确认 profile '{profile_name}' 已初始化。" + f"stdout: {stdout[:200]}" + ) + + # 显式错误 + if data.get("ok") is False and "error" in data: + err = data["error"] + if isinstance(err, dict): + if err.get("type") == "config": + return tool_error( + f"Profile '{profile_name}' 未初始化。" + "请先调用 feishu_init_profile。" + ) + return tool_error( + f"授权失败：{err.get('message', '')}。{err.get('hint', '')}" + ) + return tool_error(f"授权失败：{err}") + + verification_url = data.get("verification_url", "") + device_code = data.get("device_code", "") + + if not verification_url: + return tool_error( + f"授权响应缺少 verification_url。" + f"数据：{json.dumps(data, ensure_ascii=False)[:200]}" + ) + + # 后台线程轮询 device_code + if device_code: + t = threading.Thread( + target=_poll_device_code_bg, + args=(profile_name, device_code, domain), + daemon=True, + ) + t.start() + logger.info("[FeishuTool] polling thread started for %s/%s", profile_name, domain) + + return tool_result( + success=True, + profile_name=profile_name, + domain=domain, + verification_url=verification_url, + expires_in=data.get("expires_in", 600), + message=f"请点击链接授权飞书 {domain} 域。", + ) + + +registry.register( + name="feishu_auth_domain", + toolset="connectors", + description="授权飞书域（Device Flow），返回授权链接。", + emoji="🔐", + check_fn=_check_lark_cli, + handler=_feishu_auth_domain_handler, + schema={ + "name": "feishu_auth_domain", + "description": ( + "对指定 profile 的飞书域进行 OAuth 授权。" + "返回 verification_url（可点击链接），后台自动轮询等待完成。" + ), + "parameters": { + "type": "object", + "properties": { + "user_id": {"type": "string", "description": "MINDOS_USER_ID"}, + "domain": {"type": "string", "description": "飞书域（calendar/docs/minutes/all）"}, + "profile_name": {"type": "string", "description": "profile 名（不传则用第一个）"}, + }, + "required": ["user_id", "domain"], + }, + }, +) + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# ④ feishu_query（白名单数据操作） +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +_ALLOWED_ACTIONS: Dict[str, set] = { + "calendar": {"+agenda", "+freebusy", "+create"}, + "docs": {"+search", "+fetch", "+create"}, + "minutes": {"+search", "+download", "minutes"}, + "im": {"+send-msg"}, + "base": {"+search"}, + "mail": {"+search"}, + "wiki": {"+search"}, + "task": {"+list", "+create"}, + "auth": {"status"}, +} + +_SAFE_FLAGS = { + # calendar / docs + "--query", "--page-size", "--start", "--end", + "--summary", "--description", "--url", + "--folder-token", "--participant-ids", "--owner-ids", + "--title", + # docs +fetch + "--doc", "--limit", "--offset", + # minutes + "--minute-tokens", "--minute-token", + "--url-only", "--output", "--overwrite", + # low-level API + "--params", + # common + "--page-token", "--as", +} + + +def _feishu_query_handler(args: dict, **kwargs) -> str: + user_id = str(args.get("user_id", "")).strip() + if not user_id: + return tool_error("user_id 参数必填") + + module = str(args.get("module", "")).strip().lower() + action = str(args.get("action", "")).strip() + + if module not in _ALLOWED_ACTIONS: + return tool_error( + f"不支持的模块：{module}。" + f"可选：{', '.join(sorted(_ALLOWED_ACTIONS.keys()))}" + ) + + allowed = _ALLOWED_ACTIONS[module] + if action not in allowed: + return tool_error( + f"模块 {module} 不允许 '{action}'。可选：{', '.join(sorted(allowed))}" + ) + + profile_name = str(args.get("profile_name", "")).strip() + if not profile_name: + all_profiles = _get_all_profiles() + user_profiles = _filter_user_profiles(all_profiles, user_id) + if not user_profiles: + return tool_error("没有飞书 profile。请先绑定飞书账号。") + profile_name = _get_profile_name(user_profiles[0]) + + extra_args_raw = args.get("extra_args", []) + if isinstance(extra_args_raw, str): + extra_args_raw = extra_args_raw.split() + extra_args = [str(a) for a in extra_args_raw if isinstance(a, str)] + + # 安全检查 + for a in extra_args: + if a.startswith("-") and a not in _SAFE_FLAGS: + return tool_error(f"不允许的参数：{a}") + + # 特殊处理：minutes minutes get 需要由工具构造 --params JSON + # 避免 LLM 传入时双引号丢失问题 + if module == "minutes" and action == "minutes" and extra_args and extra_args[0] == "get": + # 从 extra_args 中提取 minute_token + token = None + i = 0 + cleaned_args = [] + while i < len(extra_args): + a = extra_args[i] + if a in ("--minute-token", "--minute-tokens") and i + 1 < len(extra_args): + token = extra_args[i + 1].strip() + i += 2 + elif a == "--params" and i + 1 < len(extra_args): + # 尝试从 --params 中提取 minute_token + try: + import json as _json + p = _json.loads(extra_args[i + 1]) + token = p.get("minute_token", token) + except Exception: + pass + i += 2 + else: + cleaned_args.append(a) + i += 1 + + if not token: + return tool_error( + "minutes minutes get 需要 minute_token。" + "请传入 extra_args=[\"get\", \"--minute-token\", \"TOKEN\"]。" + "TOKEN 是飞书妙记 URL 末尾的字符串，如 obcnXXXX。" + ) + + # 由工具内部构造正确的 --params JSON（确保双引号正确） + import json as _json + params_json = _json.dumps({"minute_token": token}) + cli_args = [ + module, action, "--profile", profile_name, + "get", "--params", params_json + ] + [a for a in cleaned_args if a != "get"] + stdout, stderr, rc = _run_cli(*cli_args, timeout=30) + if rc != 0: + return tool_error(f"执行失败（exit {rc}）：{stderr[:300] or stdout[:300]}") + try: + data = _json.loads(stdout) + return tool_result(success=True, data=data) + except (ValueError, _json.JSONDecodeError): + return tool_result(success=True, output=stdout[:2000]) + + # 同步执行（lark-cli 所有命令默认 JSON 输出，不追加 --json） + cli_args = [module, action, "--profile", profile_name] + extra_args + stdout, stderr, rc = _run_cli(*cli_args, timeout=30) + + if rc != 0: + return tool_error(f"执行失败（exit {rc}）：{stderr[:300] or stdout[:300]}") + + # 尝试 JSON 解析 + try: + data = json.loads(stdout) + return tool_result(success=True, data=data) + except (json.JSONDecodeError, ValueError): + if stdout: + return tool_result(success=True, output=stdout[:2000]) + return tool_error(f"无输出。stderr: {stderr[:200]}") + + +registry.register( + name="feishu_query", + toolset="connectors", + description="执行飞书数据查询（日历/文档/妙记等）。", + emoji="📊", + check_fn=_check_lark_cli, + handler=_feishu_query_handler, + schema={ + "name": "feishu_query", + "description": ( + "执行飞书数据操作。需先完成 init + auth。\n" + "示例：\n" + " 查日程: module=calendar, action=+agenda\n" + " 搜文档: module=docs, action=+search, extra_args=[\"--query\",\"关键词\"]\n" + " 查妙记: module=minutes, action=+search\n" + " 查授权: module=auth, action=status\n" + ), + "parameters": { + "type": "object", + "properties": { + "user_id": {"type": "string", "description": "MINDOS_USER_ID"}, + "module": { + "type": "string", + "description": "飞书模块", + "enum": sorted(_ALLOWED_ACTIONS.keys()), + }, + "action": {"type": "string", "description": "操作（如 +agenda、+search）"}, + "profile_name": {"type": "string", "description": "profile 名（不传则用第一个）"}, + "extra_args": { + "type": "array", + "items": {"type": "string"}, + "description": "额外参数，如 [\"--query\",\"方案\"]", + }, + }, + "required": ["user_id", "module", "action"], + }, + }, +) diff --git a/mindcli/_vendor/tools/file_operations.py b/mindcli/_vendor/tools/file_operations.py new file mode 100644 index 0000000..b6ab271 --- /dev/null +++ b/mindcli/_vendor/tools/file_operations.py @@ -0,0 +1,1216 @@ +#!/usr/bin/env python3 +""" +File Operations Module + +Provides file manipulation capabilities (read, write, patch, search) that work +across all terminal backends (local, docker, singularity, ssh, modal, daytona). + +The key insight is that all file operations can be expressed as shell commands, +so we wrap the terminal backend's execute() interface to provide a unified file API. + +Usage: + from tools.file_operations import ShellFileOperations + from tools.terminal_tool import _active_environments + + # Get file operations for a terminal environment + file_ops = ShellFileOperations(terminal_env) + + # Read a file + result = file_ops.read_file("/path/to/file.py") + + # Write a file + result = file_ops.write_file("/path/to/new.py", "print('hello')") + + # Search for content + result = file_ops.search("TODO", path=".", file_glob="*.py") +""" + +import os +import re +import difflib +from abc import ABC, abstractmethod +from dataclasses import dataclass, field +from typing import Optional, List, Dict, Any +from pathlib import Path +from hermes_constants import get_hermes_home +from tools.binary_extensions import BINARY_EXTENSIONS + + +# --------------------------------------------------------------------------- +# Write-path deny list — blocks writes to sensitive system/credential files +# --------------------------------------------------------------------------- + +_HOME = str(Path.home()) + +WRITE_DENIED_PATHS = { + os.path.realpath(p) for p in [ + os.path.join(_HOME, ".ssh", "authorized_keys"), + os.path.join(_HOME, ".ssh", "id_rsa"), + os.path.join(_HOME, ".ssh", "id_ed25519"), + os.path.join(_HOME, ".ssh", "config"), + str(get_hermes_home() / ".env"), + os.path.join(_HOME, ".bashrc"), + os.path.join(_HOME, ".zshrc"), + os.path.join(_HOME, ".profile"), + os.path.join(_HOME, ".bash_profile"), + os.path.join(_HOME, ".zprofile"), + os.path.join(_HOME, ".netrc"), + os.path.join(_HOME, ".pgpass"), + os.path.join(_HOME, ".npmrc"), + os.path.join(_HOME, ".pypirc"), + "/etc/sudoers", + "/etc/passwd", + "/etc/shadow", + ] +} + +WRITE_DENIED_PREFIXES = [ + os.path.realpath(p) + os.sep for p in [ + os.path.join(_HOME, ".ssh"), + os.path.join(_HOME, ".aws"), + os.path.join(_HOME, ".gnupg"), + os.path.join(_HOME, ".kube"), + "/etc/sudoers.d", + "/etc/systemd", + os.path.join(_HOME, ".docker"), + os.path.join(_HOME, ".azure"), + os.path.join(_HOME, ".config", "gh"), + ] +] + + +def _get_safe_write_root() -> Optional[str]: + """Return the resolved HERMES_WRITE_SAFE_ROOT path, or None if unset. + + When set, all write_file/patch operations are constrained to this + directory tree. Writes outside it are denied even if the target is + not on the static deny list. Opt-in hardening for gateway/messaging + deployments that should only touch a workspace checkout. + """ + root = os.getenv("HERMES_WRITE_SAFE_ROOT", "") + if not root: + return None + try: + return os.path.realpath(os.path.expanduser(root)) + except Exception: + return None + + +def _is_write_denied(path: str) -> bool: + """Return True if path is on the write deny list.""" + resolved = os.path.realpath(os.path.expanduser(str(path))) + + # 1) Static deny list + if resolved in WRITE_DENIED_PATHS: + return True + for prefix in WRITE_DENIED_PREFIXES: + if resolved.startswith(prefix): + return True + + # 2) Optional safe-root sandbox + safe_root = _get_safe_write_root() + if safe_root: + if not (resolved == safe_root or resolved.startswith(safe_root + os.sep)): + return True + + return False + + +# ============================================================================= +# Result Data Classes +# ============================================================================= + +@dataclass +class ReadResult: + """Result from reading a file.""" + content: str = "" + total_lines: int = 0 + file_size: int = 0 + truncated: bool = False + hint: Optional[str] = None + is_binary: bool = False + is_image: bool = False + base64_content: Optional[str] = None + mime_type: Optional[str] = None + dimensions: Optional[str] = None # For images: "WIDTHxHEIGHT" + error: Optional[str] = None + similar_files: List[str] = field(default_factory=list) + + def to_dict(self) -> dict: + return {k: v for k, v in self.__dict__.items() if v is not None and v != []} + + +@dataclass +class WriteResult: + """Result from writing a file.""" + bytes_written: int = 0 + dirs_created: bool = False + error: Optional[str] = None + warning: Optional[str] = None + + def to_dict(self) -> dict: + return {k: v for k, v in self.__dict__.items() if v is not None} + + +@dataclass +class PatchResult: + """Result from patching a file.""" + success: bool = False + diff: str = "" + files_modified: List[str] = field(default_factory=list) + files_created: List[str] = field(default_factory=list) + files_deleted: List[str] = field(default_factory=list) + lint: Optional[Dict[str, Any]] = None + error: Optional[str] = None + + def to_dict(self) -> dict: + result = {"success": self.success} + if self.diff: + result["diff"] = self.diff + if self.files_modified: + result["files_modified"] = self.files_modified + if self.files_created: + result["files_created"] = self.files_created + if self.files_deleted: + result["files_deleted"] = self.files_deleted + if self.lint: + result["lint"] = self.lint + if self.error: + result["error"] = self.error + return result + + +@dataclass +class SearchMatch: + """A single search match.""" + path: str + line_number: int + content: str + mtime: float = 0.0 # Modification time for sorting + + +@dataclass +class SearchResult: + """Result from searching.""" + matches: List[SearchMatch] = field(default_factory=list) + files: List[str] = field(default_factory=list) + counts: Dict[str, int] = field(default_factory=dict) + total_count: int = 0 + truncated: bool = False + error: Optional[str] = None + + def to_dict(self) -> dict: + result = {"total_count": self.total_count} + if self.matches: + result["matches"] = [ + {"path": m.path, "line": m.line_number, "content": m.content} + for m in self.matches + ] + if self.files: + result["files"] = self.files + if self.counts: + result["counts"] = self.counts + if self.truncated: + result["truncated"] = True + if self.error: + result["error"] = self.error + return result + + +@dataclass +class LintResult: + """Result from linting a file.""" + success: bool = True + skipped: bool = False + output: str = "" + message: str = "" + + def to_dict(self) -> dict: + if self.skipped: + return {"status": "skipped", "message": self.message} + return { + "status": "ok" if self.success else "error", + "output": self.output + } + + +@dataclass +class ExecuteResult: + """Result from executing a shell command.""" + stdout: str = "" + exit_code: int = 0 + + +# ============================================================================= +# Abstract Interface +# ============================================================================= + +class FileOperations(ABC): + """Abstract interface for file operations across terminal backends.""" + + @abstractmethod + def read_file(self, path: str, offset: int = 1, limit: int = 500) -> ReadResult: + """Read a file with pagination support.""" + ... + + @abstractmethod + def read_file_raw(self, path: str) -> ReadResult: + """Read the complete file content as a plain string. + + No pagination, no line-number prefixes, no per-line truncation. + Returns ReadResult with .content = full file text, .error set on + failure. Always reads to EOF regardless of file size. + """ + ... + + @abstractmethod + def write_file(self, path: str, content: str) -> WriteResult: + """Write content to a file, creating directories as needed.""" + ... + + @abstractmethod + def patch_replace(self, path: str, old_string: str, new_string: str, + replace_all: bool = False) -> PatchResult: + """Replace text in a file using fuzzy matching.""" + ... + + @abstractmethod + def patch_v4a(self, patch_content: str) -> PatchResult: + """Apply a V4A format patch.""" + ... + + @abstractmethod + def delete_file(self, path: str) -> WriteResult: + """Delete a file. Returns WriteResult with .error set on failure.""" + ... + + @abstractmethod + def move_file(self, src: str, dst: str) -> WriteResult: + """Move/rename a file from src to dst. Returns WriteResult with .error set on failure.""" + ... + + @abstractmethod + def search(self, pattern: str, path: str = ".", target: str = "content", + file_glob: Optional[str] = None, limit: int = 50, offset: int = 0, + output_mode: str = "content", context: int = 0) -> SearchResult: + """Search for content or files.""" + ... + + +# ============================================================================= +# Shell-based Implementation +# ============================================================================= + +# Image extensions (subset of binary that we can return as base64) +IMAGE_EXTENSIONS = {'.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.ico'} + +# Linters by file extension +LINTERS = { + '.py': 'python -m py_compile {file} 2>&1', + '.js': 'node --check {file} 2>&1', + '.ts': 'npx tsc --noEmit {file} 2>&1', + '.go': 'go vet {file} 2>&1', + '.rs': 'rustfmt --check {file} 2>&1', +} + +# Max limits for read operations +MAX_LINES = 2000 +MAX_LINE_LENGTH = 2000 +MAX_FILE_SIZE = 50 * 1024 # 50KB + + +class ShellFileOperations(FileOperations): + """ + File operations implemented via shell commands. + + Works with ANY terminal backend that has execute(command, cwd) method. + This includes local, docker, singularity, ssh, modal, and daytona environments. + """ + + def __init__(self, terminal_env, cwd: str = None): + """ + Initialize file operations with a terminal environment. + + Args: + terminal_env: Any object with execute(command, cwd) method. + Returns {"output": str, "returncode": int} + cwd: Working directory (defaults to env's cwd or current directory) + """ + self.env = terminal_env + # Determine cwd from various possible sources. + # IMPORTANT: do NOT fall back to os.getcwd() -- that's the HOST's local + # path which doesn't exist inside container/cloud backends (modal, docker). + # If nothing provides a cwd, use "/" as a safe universal default. + self.cwd = cwd or getattr(terminal_env, 'cwd', None) or \ + getattr(getattr(terminal_env, 'config', None), 'cwd', None) or "/" + + # Cache for command availability checks + self._command_cache: Dict[str, bool] = {} + + def _exec(self, command: str, cwd: str = None, timeout: int = None, + stdin_data: str = None) -> ExecuteResult: + """Execute command via terminal backend. + + Args: + stdin_data: If provided, piped to the process's stdin instead of + embedding in the command string. Bypasses ARG_MAX. + """ + kwargs = {} + if timeout: + kwargs['timeout'] = timeout + if stdin_data is not None: + kwargs['stdin_data'] = stdin_data + + result = self.env.execute(command, cwd=cwd or self.cwd, **kwargs) + return ExecuteResult( + stdout=result.get("output", ""), + exit_code=result.get("returncode", 0) + ) + + def _has_command(self, cmd: str) -> bool: + """Check if a command exists in the environment (cached).""" + if cmd not in self._command_cache: + result = self._exec(f"command -v {cmd} >/dev/null 2>&1 && echo 'yes'") + self._command_cache[cmd] = result.stdout.strip() == 'yes' + return self._command_cache[cmd] + + def _is_likely_binary(self, path: str, content_sample: str = None) -> bool: + """ + Check if a file is likely binary. + + Uses extension check (fast) + content analysis (fallback). + """ + ext = os.path.splitext(path)[1].lower() + if ext in BINARY_EXTENSIONS: + return True + + # Content analysis: >30% non-printable chars = binary + if content_sample: + non_printable = sum(1 for c in content_sample[:1000] + if ord(c) < 32 and c not in '\n\r\t') + return non_printable / min(len(content_sample), 1000) > 0.30 + + return False + + def _is_image(self, path: str) -> bool: + """Check if file is an image we can return as base64.""" + ext = os.path.splitext(path)[1].lower() + return ext in IMAGE_EXTENSIONS + + def _add_line_numbers(self, content: str, start_line: int = 1) -> str: + """Add line numbers to content in LINE_NUM|CONTENT format.""" + lines = content.split('\n') + numbered = [] + for i, line in enumerate(lines, start=start_line): + # Truncate long lines + if len(line) > MAX_LINE_LENGTH: + line = line[:MAX_LINE_LENGTH] + "... [truncated]" + numbered.append(f"{i:6d}|{line}") + return '\n'.join(numbered) + + def _expand_path(self, path: str) -> str: + """ + Expand shell-style paths like ~ and ~user to absolute paths. + + This must be done BEFORE shell escaping, since ~ doesn't expand + inside single quotes. + """ + if not path: + return path + + # Handle ~ and ~user + if path.startswith('~'): + # Get home directory via the terminal environment + result = self._exec("echo $HOME") + if result.exit_code == 0 and result.stdout.strip(): + home = result.stdout.strip() + if path == '~': + return home + elif path.startswith('~/'): + return home + path[1:] # Replace ~ with home + # ~username format - extract and validate username before + # letting shell expand it (prevent shell injection via + # paths like "~; rm -rf /"). + rest = path[1:] # strip leading ~ + slash_idx = rest.find('/') + username = rest[:slash_idx] if slash_idx >= 0 else rest + if username and re.fullmatch(r'[a-zA-Z0-9._-]+', username): + # Only expand ~username (not the full path) to avoid shell + # injection via path suffixes like "~user/$(malicious)". + expand_result = self._exec(f"echo ~{username}") + if expand_result.exit_code == 0 and expand_result.stdout.strip(): + user_home = expand_result.stdout.strip() + suffix = path[1 + len(username):] # e.g. "/rest/of/path" + return user_home + suffix + + return path + + def _escape_shell_arg(self, arg: str) -> str: + """Escape a string for safe use in shell commands.""" + # Use single quotes and escape any single quotes in the string + return "'" + arg.replace("'", "'\"'\"'") + "'" + + def _unified_diff(self, old_content: str, new_content: str, filename: str) -> str: + """Generate unified diff between old and new content.""" + old_lines = old_content.splitlines(keepends=True) + new_lines = new_content.splitlines(keepends=True) + diff = difflib.unified_diff( + old_lines, new_lines, + fromfile=f"a/{filename}", + tofile=f"b/{filename}" + ) + return ''.join(diff) + + # ========================================================================= + # READ Implementation + # ========================================================================= + + def read_file(self, path: str, offset: int = 1, limit: int = 500) -> ReadResult: + """ + Read a file with pagination, binary detection, and line numbers. + + Args: + path: File path (absolute or relative to cwd) + offset: Line number to start from (1-indexed, default 1) + limit: Maximum lines to return (default 500, max 2000) + + Returns: + ReadResult with content, metadata, or error info + """ + # Expand ~ and other shell paths + path = self._expand_path(path) + + # Clamp limit + limit = min(limit, MAX_LINES) + + # Check if file exists and get size (wc -c is POSIX, works on Linux + macOS) + stat_cmd = f"wc -c < {self._escape_shell_arg(path)} 2>/dev/null" + stat_result = self._exec(stat_cmd) + + if stat_result.exit_code != 0: + # File not found - try to suggest similar files + return self._suggest_similar_files(path) + + try: + file_size = int(stat_result.stdout.strip()) + except ValueError: + file_size = 0 + + # Check if file is too large + if file_size > MAX_FILE_SIZE: + # Still try to read, but warn + pass + + # Images are never inlined — redirect to the vision tool + if self._is_image(path): + return ReadResult( + is_image=True, + is_binary=True, + file_size=file_size, + hint=( + "Image file detected. Automatically redirected to vision_analyze tool. " + "Use vision_analyze with this file path to inspect the image contents." + ), + ) + + # Read a sample to check for binary content + sample_cmd = f"head -c 1000 {self._escape_shell_arg(path)} 2>/dev/null" + sample_result = self._exec(sample_cmd) + + if self._is_likely_binary(path, sample_result.stdout): + return ReadResult( + is_binary=True, + file_size=file_size, + error="Binary file - cannot display as text. Use appropriate tools to handle this file type." + ) + + # Read with pagination using sed + end_line = offset + limit - 1 + read_cmd = f"sed -n '{offset},{end_line}p' {self._escape_shell_arg(path)}" + read_result = self._exec(read_cmd) + + if read_result.exit_code != 0: + return ReadResult(error=f"Failed to read file: {read_result.stdout}") + + # Get total line count + wc_cmd = f"wc -l < {self._escape_shell_arg(path)}" + wc_result = self._exec(wc_cmd) + try: + total_lines = int(wc_result.stdout.strip()) + except ValueError: + total_lines = 0 + + # Check if truncated + truncated = total_lines > end_line + hint = None + if truncated: + hint = f"Use offset={end_line + 1} to continue reading (showing {offset}-{end_line} of {total_lines} lines)" + + return ReadResult( + content=self._add_line_numbers(read_result.stdout, offset), + total_lines=total_lines, + file_size=file_size, + truncated=truncated, + hint=hint + ) + + def _suggest_similar_files(self, path: str) -> ReadResult: + """Suggest similar files when the requested file is not found.""" + dir_path = os.path.dirname(path) or "." + filename = os.path.basename(path) + basename_no_ext = os.path.splitext(filename)[0] + ext = os.path.splitext(filename)[1].lower() + lower_name = filename.lower() + + # List files in the target directory + ls_cmd = f"ls -1 {self._escape_shell_arg(dir_path)} 2>/dev/null | head -50" + ls_result = self._exec(ls_cmd) + + scored: list = [] # (score, filepath) — higher is better + if ls_result.exit_code == 0 and ls_result.stdout.strip(): + for f in ls_result.stdout.strip().split('\n'): + if not f: + continue + lf = f.lower() + score = 0 + + # Exact match (shouldn't happen, but guard) + if lf == lower_name: + score = 100 + # Same base name, different extension (e.g. config.yml vs config.yaml) + elif os.path.splitext(f)[0].lower() == basename_no_ext.lower(): + score = 90 + # Target is prefix of candidate or vice-versa + elif lf.startswith(lower_name) or lower_name.startswith(lf): + score = 70 + # Substring match (candidate contains query) + elif lower_name in lf: + score = 60 + # Reverse substring (query contains candidate name) + elif lf in lower_name and len(lf) > 2: + score = 40 + # Same extension with some overlap + elif ext and os.path.splitext(f)[1].lower() == ext: + common = set(lower_name) & set(lf) + if len(common) >= max(len(lower_name), len(lf)) * 0.4: + score = 30 + + if score > 0: + scored.append((score, os.path.join(dir_path, f))) + + scored.sort(key=lambda x: -x[0]) + similar = [fp for _, fp in scored[:5]] + + return ReadResult( + error=f"File not found: {path}", + similar_files=similar + ) + + def read_file_raw(self, path: str) -> ReadResult: + """Read the complete file content as a plain string. + + No pagination, no line-number prefixes, no per-line truncation. + Uses cat so the full file is returned regardless of size. + """ + path = self._expand_path(path) + stat_cmd = f"wc -c < {self._escape_shell_arg(path)} 2>/dev/null" + stat_result = self._exec(stat_cmd) + if stat_result.exit_code != 0: + return self._suggest_similar_files(path) + try: + file_size = int(stat_result.stdout.strip()) + except ValueError: + file_size = 0 + if self._is_image(path): + return ReadResult(is_image=True, is_binary=True, file_size=file_size) + sample_result = self._exec(f"head -c 1000 {self._escape_shell_arg(path)} 2>/dev/null") + if self._is_likely_binary(path, sample_result.stdout): + return ReadResult( + is_binary=True, file_size=file_size, + error="Binary file — cannot display as text." + ) + cat_result = self._exec(f"cat {self._escape_shell_arg(path)}") + if cat_result.exit_code != 0: + return ReadResult(error=f"Failed to read file: {cat_result.stdout}") + return ReadResult(content=cat_result.stdout, file_size=file_size) + + def delete_file(self, path: str) -> WriteResult: + """Delete a file via rm.""" + path = self._expand_path(path) + if _is_write_denied(path): + return WriteResult(error=f"Delete denied: {path} is a protected path") + result = self._exec(f"rm -f {self._escape_shell_arg(path)}") + if result.exit_code != 0: + return WriteResult(error=f"Failed to delete {path}: {result.stdout}") + return WriteResult() + + def move_file(self, src: str, dst: str) -> WriteResult: + """Move a file via mv.""" + src = self._expand_path(src) + dst = self._expand_path(dst) + for p in (src, dst): + if _is_write_denied(p): + return WriteResult(error=f"Move denied: {p} is a protected path") + result = self._exec( + f"mv {self._escape_shell_arg(src)} {self._escape_shell_arg(dst)}" + ) + if result.exit_code != 0: + return WriteResult(error=f"Failed to move {src} -> {dst}: {result.stdout}") + return WriteResult() + + # ========================================================================= + # WRITE Implementation + # ========================================================================= + + def write_file(self, path: str, content: str) -> WriteResult: + """ + Write content to a file, creating parent directories as needed. + + Pipes content through stdin to avoid OS ARG_MAX limits on large + files. The content never appears in the shell command string — + only the file path does. + + Args: + path: File path to write + content: Content to write + + Returns: + WriteResult with bytes written or error + """ + # Expand ~ and other shell paths + path = self._expand_path(path) + + # Block writes to sensitive paths + if _is_write_denied(path): + return WriteResult(error=f"Write denied: '{path}' is a protected system/credential file.") + + # Create parent directories + parent = os.path.dirname(path) + dirs_created = False + + if parent: + mkdir_cmd = f"mkdir -p {self._escape_shell_arg(parent)}" + mkdir_result = self._exec(mkdir_cmd) + if mkdir_result.exit_code == 0: + dirs_created = True + + # Write via stdin pipe — content bypasses shell arg parsing entirely, + # so there's no ARG_MAX limit regardless of file size. + write_cmd = f"cat > {self._escape_shell_arg(path)}" + write_result = self._exec(write_cmd, stdin_data=content) + + if write_result.exit_code != 0: + return WriteResult(error=f"Failed to write file: {write_result.stdout}") + + # Get bytes written (wc -c is POSIX, works on Linux + macOS) + stat_cmd = f"wc -c < {self._escape_shell_arg(path)} 2>/dev/null" + stat_result = self._exec(stat_cmd) + + try: + bytes_written = int(stat_result.stdout.strip()) + except ValueError: + bytes_written = len(content.encode('utf-8')) + + return WriteResult( + bytes_written=bytes_written, + dirs_created=dirs_created + ) + + # ========================================================================= + # PATCH Implementation (Replace Mode) + # ========================================================================= + + def patch_replace(self, path: str, old_string: str, new_string: str, + replace_all: bool = False) -> PatchResult: + """ + Replace text in a file using fuzzy matching. + + Args: + path: File path to modify + old_string: Text to find (must be unique unless replace_all=True) + new_string: Replacement text + replace_all: If True, replace all occurrences + + Returns: + PatchResult with diff and lint results + """ + # Expand ~ and other shell paths + path = self._expand_path(path) + + # Block writes to sensitive paths + if _is_write_denied(path): + return PatchResult(error=f"Write denied: '{path}' is a protected system/credential file.") + + # Read current content + read_cmd = f"cat {self._escape_shell_arg(path)} 2>/dev/null" + read_result = self._exec(read_cmd) + + if read_result.exit_code != 0: + return PatchResult(error=f"Failed to read file: {path}") + + content = read_result.stdout + + # Import and use fuzzy matching + from tools.fuzzy_match import fuzzy_find_and_replace + + new_content, match_count, _strategy, error = fuzzy_find_and_replace( + content, old_string, new_string, replace_all + ) + + if error: + return PatchResult(error=error) + + if match_count == 0: + return PatchResult(error=f"Could not find match for old_string in {path}") + + # Write back + write_result = self.write_file(path, new_content) + if write_result.error: + return PatchResult(error=f"Failed to write changes: {write_result.error}") + + # Generate diff + diff = self._unified_diff(content, new_content, path) + + # Auto-lint + lint_result = self._check_lint(path) + + return PatchResult( + success=True, + diff=diff, + files_modified=[path], + lint=lint_result.to_dict() if lint_result else None + ) + + def patch_v4a(self, patch_content: str) -> PatchResult: + """ + Apply a V4A format patch. + + V4A format: + *** Begin Patch + *** Update File: path/to/file.py + @@ context hint @@ + context line + -removed line + +added line + *** End Patch + + Args: + patch_content: V4A format patch string + + Returns: + PatchResult with changes made + """ + # Import patch parser + from tools.patch_parser import parse_v4a_patch, apply_v4a_operations + + operations, parse_error = parse_v4a_patch(patch_content) + if parse_error: + return PatchResult(error=f"Failed to parse patch: {parse_error}") + + # Apply operations + result = apply_v4a_operations(operations, self) + return result + + def _check_lint(self, path: str) -> LintResult: + """ + Run syntax check on a file after editing. + + Args: + path: File path to lint + + Returns: + LintResult with status and any errors + """ + ext = os.path.splitext(path)[1].lower() + + if ext not in LINTERS: + return LintResult(skipped=True, message=f"No linter for {ext} files") + + # Check if linter command is available + linter_cmd = LINTERS[ext] + # Extract the base command (first word) + base_cmd = linter_cmd.split()[0] + + if not self._has_command(base_cmd): + return LintResult(skipped=True, message=f"{base_cmd} not available") + + # Run linter + cmd = linter_cmd.replace("{file}", self._escape_shell_arg(path)) + result = self._exec(cmd, timeout=30) + + return LintResult( + success=result.exit_code == 0, + output=result.stdout.strip() if result.stdout.strip() else "" + ) + + # ========================================================================= + # SEARCH Implementation + # ========================================================================= + + def search(self, pattern: str, path: str = ".", target: str = "content", + file_glob: Optional[str] = None, limit: int = 50, offset: int = 0, + output_mode: str = "content", context: int = 0) -> SearchResult: + """ + Search for content or files. + + Args: + pattern: Regex (for content) or glob pattern (for files) + path: Directory/file to search (default: cwd) + target: "content" (grep) or "files" (glob) + file_glob: File pattern filter for content search (e.g., "*.py") + limit: Max results (default 50) + offset: Skip first N results + output_mode: "content", "files_only", or "count" + context: Lines of context around matches + + Returns: + SearchResult with matches or file list + """ + # Expand ~ and other shell paths + path = self._expand_path(path) + + # Validate that the path exists before searching + check = self._exec(f"test -e {self._escape_shell_arg(path)} && echo exists || echo not_found") + if "not_found" in check.stdout: + # Try to suggest nearby paths + parent = os.path.dirname(path) or "." + basename_query = os.path.basename(path) + hint_parts = [f"Path not found: {path}"] + # Check if parent directory exists and list similar entries + parent_check = self._exec( + f"test -d {self._escape_shell_arg(parent)} && echo yes || echo no" + ) + if "yes" in parent_check.stdout and basename_query: + ls_result = self._exec( + f"ls -1 {self._escape_shell_arg(parent)} 2>/dev/null | head -20" + ) + if ls_result.exit_code == 0 and ls_result.stdout.strip(): + lower_q = basename_query.lower() + candidates = [] + for entry in ls_result.stdout.strip().split('\n'): + if not entry: + continue + le = entry.lower() + if lower_q in le or le in lower_q or le.startswith(lower_q[:3]): + candidates.append(os.path.join(parent, entry)) + if candidates: + hint_parts.append( + "Similar paths: " + ", ".join(candidates[:5]) + ) + return SearchResult( + error=". ".join(hint_parts), + total_count=0 + ) + + if target == "files": + return self._search_files(pattern, path, limit, offset) + else: + return self._search_content(pattern, path, file_glob, limit, offset, + output_mode, context) + + def _search_files(self, pattern: str, path: str, limit: int, offset: int) -> SearchResult: + """Search for files by name pattern (glob-like).""" + # Auto-prepend **/ for recursive search if not already present + if not pattern.startswith('**/') and '/' not in pattern: + search_pattern = pattern + else: + search_pattern = pattern.split('/')[-1] + + # Prefer ripgrep: respects .gitignore, excludes hidden dirs by + # default, and has parallel directory traversal (~200x faster than + # find on wide trees). Mirrors _search_content which already uses rg. + if self._has_command('rg'): + return self._search_files_rg(search_pattern, path, limit, offset) + + # Fallback: find (slower, no .gitignore awareness) + if not self._has_command('find'): + return SearchResult( + error="File search requires 'rg' (ripgrep) or 'find'. " + "Install ripgrep for best results: " + "https://github.com/BurntSushi/ripgrep#installation" + ) + + # Exclude hidden directories (matching ripgrep's default behavior). + hidden_exclude = "-not -path '*/.*'" + + cmd = f"find {self._escape_shell_arg(path)} {hidden_exclude} -type f -name {self._escape_shell_arg(search_pattern)} " \ + f"-printf '%T@ %p\\n' 2>/dev/null | sort -rn | tail -n +{offset + 1} | head -n {limit}" + + result = self._exec(cmd, timeout=60) + + if not result.stdout.strip(): + # Try without -printf (BSD find compatibility -- macOS) + cmd_simple = f"find {self._escape_shell_arg(path)} {hidden_exclude} -type f -name {self._escape_shell_arg(search_pattern)} " \ + f"2>/dev/null | head -n {limit + offset} | tail -n +{offset + 1}" + result = self._exec(cmd_simple, timeout=60) + + files = [] + for line in result.stdout.strip().split('\n'): + if not line: + continue + parts = line.split(' ', 1) + if len(parts) == 2 and parts[0].replace('.', '').isdigit(): + files.append(parts[1]) + else: + files.append(line) + + return SearchResult( + files=files, + total_count=len(files) + ) + + def _search_files_rg(self, pattern: str, path: str, limit: int, offset: int) -> SearchResult: + """Search for files by name using ripgrep's --files mode. + + rg --files respects .gitignore and excludes hidden directories by + default, and uses parallel directory traversal for ~200x speedup + over find on wide trees. Results are sorted by modification time + (most recently edited first) when rg >= 13.0 supports --sortr. + """ + # rg --files -g uses glob patterns; wrap bare names so they match + # at any depth (equivalent to find -name). + if '/' not in pattern and not pattern.startswith('*'): + glob_pattern = f"*{pattern}" + else: + glob_pattern = pattern + + fetch_limit = limit + offset + # Try mtime-sorted first (rg 13+); fall back to unsorted if not supported. + cmd_sorted = ( + f"rg --files --sortr=modified -g {self._escape_shell_arg(glob_pattern)} " + f"{self._escape_shell_arg(path)} 2>/dev/null " + f"| head -n {fetch_limit}" + ) + result = self._exec(cmd_sorted, timeout=60) + all_files = [f for f in result.stdout.strip().split('\n') if f] + + if not all_files: + # --sortr may have failed on older rg; retry without it. + cmd_plain = ( + f"rg --files -g {self._escape_shell_arg(glob_pattern)} " + f"{self._escape_shell_arg(path)} 2>/dev/null " + f"| head -n {fetch_limit}" + ) + result = self._exec(cmd_plain, timeout=60) + all_files = [f for f in result.stdout.strip().split('\n') if f] + + page = all_files[offset:offset + limit] + + return SearchResult( + files=page, + total_count=len(all_files), + truncated=len(all_files) >= fetch_limit, + ) + + def _search_content(self, pattern: str, path: str, file_glob: Optional[str], + limit: int, offset: int, output_mode: str, context: int) -> SearchResult: + """Search for content inside files (grep-like).""" + # Try ripgrep first (fast), fallback to grep (slower but works) + if self._has_command('rg'): + return self._search_with_rg(pattern, path, file_glob, limit, offset, + output_mode, context) + elif self._has_command('grep'): + return self._search_with_grep(pattern, path, file_glob, limit, offset, + output_mode, context) + else: + # Neither rg nor grep available (Windows without Git Bash, etc.) + return SearchResult( + error="Content search requires ripgrep (rg) or grep. " + "Install ripgrep: https://github.com/BurntSushi/ripgrep#installation" + ) + + def _search_with_rg(self, pattern: str, path: str, file_glob: Optional[str], + limit: int, offset: int, output_mode: str, context: int) -> SearchResult: + """Search using ripgrep.""" + cmd_parts = ["rg", "--line-number", "--no-heading", "--with-filename"] + + # Add context if requested + if context > 0: + cmd_parts.extend(["-C", str(context)]) + + # Add file glob filter (must be quoted to prevent shell expansion) + if file_glob: + cmd_parts.extend(["--glob", self._escape_shell_arg(file_glob)]) + + # Output mode handling + if output_mode == "files_only": + cmd_parts.append("-l") # Files only + elif output_mode == "count": + cmd_parts.append("-c") # Count per file + + # Add pattern and path + cmd_parts.append(self._escape_shell_arg(pattern)) + cmd_parts.append(self._escape_shell_arg(path)) + + # Fetch extra rows so we can report the true total before slicing. + # For context mode, rg emits separator lines ("--") between groups, + # so we grab generously and filter in Python. + fetch_limit = limit + offset + 200 if context > 0 else limit + offset + cmd_parts.extend(["|", "head", "-n", str(fetch_limit)]) + + cmd = " ".join(cmd_parts) + result = self._exec(cmd, timeout=60) + + # rg exit codes: 0=matches found, 1=no matches, 2=error + if result.exit_code == 2 and not result.stdout.strip(): + error_msg = result.stderr.strip() if hasattr(result, 'stderr') and result.stderr else "Search error" + return SearchResult(error=f"Search failed: {error_msg}", total_count=0) + + # Parse results based on output mode + if output_mode == "files_only": + all_files = [f for f in result.stdout.strip().split('\n') if f] + total = len(all_files) + page = all_files[offset:offset + limit] + return SearchResult(files=page, total_count=total) + + elif output_mode == "count": + counts = {} + for line in result.stdout.strip().split('\n'): + if ':' in line: + parts = line.rsplit(':', 1) + if len(parts) == 2: + try: + counts[parts[0]] = int(parts[1]) + except ValueError: + pass + return SearchResult(counts=counts, total_count=sum(counts.values())) + + else: + # Parse content matches and context lines. + # rg match lines: "file:lineno:content" (colon separator) + # rg context lines: "file-lineno-content" (dash separator) + # rg group seps: "--" + # Note: on Windows, paths contain drive letters (e.g. C:\path), + # so naive split(":") breaks. Use regex to handle both platforms. + _match_re = re.compile(r'^([A-Za-z]:)?(.*?):(\d+):(.*)$') + _ctx_re = re.compile(r'^([A-Za-z]:)?(.*?)-(\d+)-(.*)$') + matches = [] + for line in result.stdout.strip().split('\n'): + if not line or line == "--": + continue + + # Try match line first (colon-separated: file:line:content) + m = _match_re.match(line) + if m: + matches.append(SearchMatch( + path=(m.group(1) or '') + m.group(2), + line_number=int(m.group(3)), + content=m.group(4)[:500] + )) + continue + + # Try context line (dash-separated: file-line-content) + # Only attempt if context was requested to avoid false positives + if context > 0: + m = _ctx_re.match(line) + if m: + matches.append(SearchMatch( + path=(m.group(1) or '') + m.group(2), + line_number=int(m.group(3)), + content=m.group(4)[:500] + )) + + total = len(matches) + page = matches[offset:offset + limit] + return SearchResult( + matches=page, + total_count=total, + truncated=total > offset + limit + ) + + def _search_with_grep(self, pattern: str, path: str, file_glob: Optional[str], + limit: int, offset: int, output_mode: str, context: int) -> SearchResult: + """Fallback search using grep.""" + cmd_parts = ["grep", "-rnH"] # -H forces filename even for single-file searches + + # Exclude hidden directories (matching ripgrep's default behavior). + # This prevents searching inside .hub/index-cache/, .git/, etc. + cmd_parts.append("--exclude-dir='.*'") + + # Add context if requested + if context > 0: + cmd_parts.extend(["-C", str(context)]) + + # Add file pattern filter (must be quoted to prevent shell expansion) + if file_glob: + cmd_parts.extend(["--include", self._escape_shell_arg(file_glob)]) + + # Output mode handling + if output_mode == "files_only": + cmd_parts.append("-l") + elif output_mode == "count": + cmd_parts.append("-c") + + # Add pattern and path + cmd_parts.append(self._escape_shell_arg(pattern)) + cmd_parts.append(self._escape_shell_arg(path)) + + # Fetch generously so we can compute total before slicing + fetch_limit = limit + offset + (200 if context > 0 else 0) + cmd_parts.extend(["|", "head", "-n", str(fetch_limit)]) + + cmd = " ".join(cmd_parts) + result = self._exec(cmd, timeout=60) + + # grep exit codes: 0=matches found, 1=no matches, 2=error + if result.exit_code == 2 and not result.stdout.strip(): + error_msg = result.stderr.strip() if hasattr(result, 'stderr') and result.stderr else "Search error" + return SearchResult(error=f"Search failed: {error_msg}", total_count=0) + + if output_mode == "files_only": + all_files = [f for f in result.stdout.strip().split('\n') if f] + total = len(all_files) + page = all_files[offset:offset + limit] + return SearchResult(files=page, total_count=total) + + elif output_mode == "count": + counts = {} + for line in result.stdout.strip().split('\n'): + if ':' in line: + parts = line.rsplit(':', 1) + if len(parts) == 2: + try: + counts[parts[0]] = int(parts[1]) + except ValueError: + pass + return SearchResult(counts=counts, total_count=sum(counts.values())) + + else: + # grep match lines: "file:lineno:content" (colon) + # grep context lines: "file-lineno-content" (dash) + # grep group seps: "--" + # Note: on Windows, paths contain drive letters (e.g. C:\path), + # so naive split(":") breaks. Use regex to handle both platforms. + _match_re = re.compile(r'^([A-Za-z]:)?(.*?):(\d+):(.*)$') + _ctx_re = re.compile(r'^([A-Za-z]:)?(.*?)-(\d+)-(.*)$') + matches = [] + for line in result.stdout.strip().split('\n'): + if not line or line == "--": + continue + + m = _match_re.match(line) + if m: + matches.append(SearchMatch( + path=(m.group(1) or '') + m.group(2), + line_number=int(m.group(3)), + content=m.group(4)[:500] + )) + continue + + if context > 0: + m = _ctx_re.match(line) + if m: + matches.append(SearchMatch( + path=(m.group(1) or '') + m.group(2), + line_number=int(m.group(3)), + content=m.group(4)[:500] + )) + + + total = len(matches) + page = matches[offset:offset + limit] + return SearchResult( + matches=page, + total_count=total, + truncated=total > offset + limit + ) diff --git a/mindcli/_vendor/tools/file_tools.py b/mindcli/_vendor/tools/file_tools.py new file mode 100644 index 0000000..ca2118c --- /dev/null +++ b/mindcli/_vendor/tools/file_tools.py @@ -0,0 +1,799 @@ +#!/usr/bin/env python3 +"""File Tools Module - LLM agent file manipulation tools.""" + +import errno +import json +import logging +import os +import threading +from pathlib import Path +from tools.binary_extensions import has_binary_extension +from tools.file_operations import ShellFileOperations +from agent.redact import redact_sensitive_text + +logger = logging.getLogger(__name__) + + +_EXPECTED_WRITE_ERRNOS = {errno.EACCES, errno.EPERM, errno.EROFS} + +# --------------------------------------------------------------------------- +# Read-size guard: cap the character count returned to the model. +# We're model-agnostic so we can't count tokens; characters are a safe proxy. +# 100K chars ≈ 25–35K tokens across typical tokenisers. Files larger than +# this in a single read are a context-window hazard — the model should use +# offset+limit to read the relevant section. +# +# Configurable via config.yaml: file_read_max_chars: 200000 +# --------------------------------------------------------------------------- +_DEFAULT_MAX_READ_CHARS = 100_000 +_max_read_chars_cached: int | None = None + + +def _get_max_read_chars() -> int: + """Return the configured max characters per file read. + + Reads ``file_read_max_chars`` from config.yaml on first call, caches + the result for the lifetime of the process. Falls back to the + built-in default if the config is missing or invalid. + """ + global _max_read_chars_cached + if _max_read_chars_cached is not None: + return _max_read_chars_cached + try: + from hermes_cli.config import load_config + cfg = load_config() + val = cfg.get("file_read_max_chars") + if isinstance(val, (int, float)) and val > 0: + _max_read_chars_cached = int(val) + return _max_read_chars_cached + except Exception: + pass + _max_read_chars_cached = _DEFAULT_MAX_READ_CHARS + return _max_read_chars_cached + +# If the total file size exceeds this AND the caller didn't specify a narrow +# range (limit <= 200), we include a hint encouraging targeted reads. +_LARGE_FILE_HINT_BYTES = 512_000 # 512 KB + +# --------------------------------------------------------------------------- +# Device path blocklist — reading these hangs the process (infinite output +# or blocking on input). Checked by path only (no I/O). +# --------------------------------------------------------------------------- +_BLOCKED_DEVICE_PATHS = frozenset({ + # Infinite output — never reach EOF + "/dev/zero", "/dev/random", "/dev/urandom", "/dev/full", + # Blocks waiting for input + "/dev/stdin", "/dev/tty", "/dev/console", + # Nonsensical to read + "/dev/stdout", "/dev/stderr", + # fd aliases + "/dev/fd/0", "/dev/fd/1", "/dev/fd/2", +}) + + +def _is_blocked_device(filepath: str) -> bool: + """Return True if the path would hang the process (infinite output or blocking input). + + Uses the *literal* path — no symlink resolution — because the model + specifies paths directly and realpath follows symlinks all the way + through (e.g. /dev/stdin → /proc/self/fd/0 → /dev/pts/0), defeating + the check. + """ + normalized = os.path.expanduser(filepath) + if normalized in _BLOCKED_DEVICE_PATHS: + return True + # /proc/self/fd/0-2 and /proc//fd/0-2 are Linux aliases for stdio + if normalized.startswith("/proc/") and normalized.endswith( + ("/fd/0", "/fd/1", "/fd/2") + ): + return True + return False + + +# Paths that file tools should refuse to write to without going through the +# terminal tool's approval system. These match prefixes after os.path.realpath. +_SENSITIVE_PATH_PREFIXES = ( + "/etc/", "/boot/", "/usr/lib/systemd/", + "/private/etc/", "/private/var/", +) +_SENSITIVE_EXACT_PATHS = {"/var/run/docker.sock", "/run/docker.sock"} + + +def _check_sensitive_path(filepath: str) -> str | None: + """Return an error message if the path targets a sensitive system location.""" + try: + resolved = os.path.realpath(os.path.expanduser(filepath)) + except (OSError, ValueError): + resolved = filepath + normalized = os.path.normpath(os.path.expanduser(filepath)) + _err = ( + f"Refusing to write to sensitive system path: {filepath}\n" + "Use the terminal tool with sudo if you need to modify system files." + ) + for prefix in _SENSITIVE_PATH_PREFIXES: + if resolved.startswith(prefix) or normalized.startswith(prefix): + return _err + if resolved in _SENSITIVE_EXACT_PATHS or normalized in _SENSITIVE_EXACT_PATHS: + return _err + return None + + +def _is_expected_write_exception(exc: Exception) -> bool: + """Return True for expected write denials that should not hit error logs.""" + if isinstance(exc, PermissionError): + return True + if isinstance(exc, OSError) and exc.errno in _EXPECTED_WRITE_ERRNOS: + return True + return False + + +_file_ops_lock = threading.Lock() +_file_ops_cache: dict = {} + +# Track files read per task to detect re-read loops and deduplicate reads. +# Per task_id we store: +# "last_key": the key of the most recent read/search call (or None) +# "consecutive": how many times that exact call has been repeated in a row +# "read_history": set of (path, offset, limit) tuples for get_read_files_summary +# "dedup": dict mapping (resolved_path, offset, limit) → mtime float +# Used to skip re-reads of unchanged files. Reset on +# context compression (the original content is summarised +# away so the model needs the full content again). +# "read_timestamps": dict mapping resolved_path → modification-time float +# recorded when the file was last read (or written) by +# this task. Used by write_file and patch to detect +# external changes between the agent's read and write. +# Updated after successful writes so consecutive edits +# by the same task don't trigger false warnings. +_read_tracker_lock = threading.Lock() +_read_tracker: dict = {} + + +def _get_file_ops(task_id: str = "default") -> ShellFileOperations: + """Get or create ShellFileOperations for a terminal environment. + + Respects the TERMINAL_ENV setting -- if the task_id doesn't have an + environment yet, creates one using the configured backend (local, docker, + modal, etc.) rather than always defaulting to local. + + Thread-safe: uses the same per-task creation locks as terminal_tool to + prevent duplicate sandbox creation from concurrent tool calls. + """ + from tools.terminal_tool import ( + _active_environments, _env_lock, _create_environment, + _get_env_config, _last_activity, _start_cleanup_thread, + _creation_locks, + _creation_locks_lock, + ) + import time + + # Fast path: check cache -- but also verify the underlying environment + # is still alive (it may have been killed by the cleanup thread). + with _file_ops_lock: + cached = _file_ops_cache.get(task_id) + if cached is not None: + with _env_lock: + if task_id in _active_environments: + _last_activity[task_id] = time.time() + return cached + else: + # Environment was cleaned up -- invalidate stale cache entry + with _file_ops_lock: + _file_ops_cache.pop(task_id, None) + + # Need to ensure the environment exists before building file_ops. + # Acquire per-task lock so only one thread creates the sandbox. + with _creation_locks_lock: + if task_id not in _creation_locks: + _creation_locks[task_id] = threading.Lock() + task_lock = _creation_locks[task_id] + + with task_lock: + # Double-check: another thread may have created it while we waited + with _env_lock: + if task_id in _active_environments: + _last_activity[task_id] = time.time() + terminal_env = _active_environments[task_id] + else: + terminal_env = None + + if terminal_env is None: + from tools.terminal_tool import _task_env_overrides + + config = _get_env_config() + env_type = config["env_type"] + overrides = _task_env_overrides.get(task_id, {}) + + if env_type == "docker": + image = overrides.get("docker_image") or config["docker_image"] + elif env_type == "singularity": + image = overrides.get("singularity_image") or config["singularity_image"] + elif env_type == "modal": + image = overrides.get("modal_image") or config["modal_image"] + elif env_type == "daytona": + image = overrides.get("daytona_image") or config["daytona_image"] + else: + image = "" + + cwd = overrides.get("cwd") or config["cwd"] + logger.info("Creating new %s environment for task %s...", env_type, task_id[:8]) + + container_config = None + if env_type in ("docker", "singularity", "modal", "daytona"): + container_config = { + "container_cpu": config.get("container_cpu", 1), + "container_memory": config.get("container_memory", 5120), + "container_disk": config.get("container_disk", 51200), + "container_persistent": config.get("container_persistent", True), + "docker_volumes": config.get("docker_volumes", []), + } + + ssh_config = None + if env_type == "ssh": + ssh_config = { + "host": config.get("ssh_host", ""), + "user": config.get("ssh_user", ""), + "port": config.get("ssh_port", 22), + "key": config.get("ssh_key", ""), + "persistent": config.get("ssh_persistent", False), + } + + local_config = None + if env_type == "local": + local_config = { + "persistent": config.get("local_persistent", False), + } + + terminal_env = _create_environment( + env_type=env_type, + image=image, + cwd=cwd, + timeout=config["timeout"], + ssh_config=ssh_config, + container_config=container_config, + local_config=local_config, + task_id=task_id, + host_cwd=config.get("host_cwd"), + ) + + with _env_lock: + _active_environments[task_id] = terminal_env + _last_activity[task_id] = time.time() + + _start_cleanup_thread() + logger.info("%s environment ready for task %s", env_type, task_id[:8]) + + # Build file_ops from the (guaranteed live) environment and cache it + file_ops = ShellFileOperations(terminal_env) + with _file_ops_lock: + _file_ops_cache[task_id] = file_ops + return file_ops + + +def clear_file_ops_cache(task_id: str = None): + """Clear the file operations cache.""" + with _file_ops_lock: + if task_id: + _file_ops_cache.pop(task_id, None) + else: + _file_ops_cache.clear() + + +def read_file_tool(path: str, offset: int = 1, limit: int = 500, task_id: str = "default") -> str: + """Read a file with pagination and line numbers.""" + try: + # ── Device path guard ───────────────────────────────────────── + # Block paths that would hang the process (infinite output, + # blocking on input). Pure path check — no I/O. + if _is_blocked_device(path): + return json.dumps({ + "error": ( + f"Cannot read '{path}': this is a device file that would " + "block or produce infinite output." + ), + }) + + _resolved = Path(path).expanduser().resolve() + + # ── Binary file guard ───────────────────────────────────────── + # Block binary files by extension (no I/O). + if has_binary_extension(str(_resolved)): + _ext = _resolved.suffix.lower() + return json.dumps({ + "error": ( + f"Cannot read binary file '{path}' ({_ext}). " + "Use vision_analyze for images, or terminal to inspect binary files." + ), + }) + + # ── Hermes internal path guard ──────────────────────────────── + # Prevent prompt injection via catalog or hub metadata files. + from hermes_constants import get_hermes_home as _get_hh + _hermes_home = _get_hh().resolve() + _blocked_dirs = [ + _hermes_home / "skills" / ".hub" / "index-cache", + _hermes_home / "skills" / ".hub", + ] + for _blocked in _blocked_dirs: + try: + _resolved.relative_to(_blocked) + return json.dumps({ + "error": ( + f"Access denied: {path} is an internal Hermes cache file " + "and cannot be read directly to prevent prompt injection. " + "Use the skills_list or skill_view tools instead." + ) + }) + except ValueError: + pass + + # ── Dedup check ─────────────────────────────────────────────── + # If we already read this exact (path, offset, limit) and the + # file hasn't been modified since, return a lightweight stub + # instead of re-sending the same content. Saves context tokens. + resolved_str = str(_resolved) + dedup_key = (resolved_str, offset, limit) + with _read_tracker_lock: + task_data = _read_tracker.setdefault(task_id, { + "last_key": None, "consecutive": 0, + "read_history": set(), "dedup": {}, + }) + cached_mtime = task_data.get("dedup", {}).get(dedup_key) + + if cached_mtime is not None: + try: + current_mtime = os.path.getmtime(resolved_str) + if current_mtime == cached_mtime: + return json.dumps({ + "content": ( + "File unchanged since last read. The content from " + "the earlier read_file result in this conversation is " + "still current — refer to that instead of re-reading." + ), + "path": path, + "dedup": True, + }, ensure_ascii=False) + except OSError: + pass # stat failed — fall through to full read + + # ── Perform the read ────────────────────────────────────────── + file_ops = _get_file_ops(task_id) + result = file_ops.read_file(path, offset, limit) + result_dict = result.to_dict() + + # ── Character-count guard ───────────────────────────────────── + # We're model-agnostic so we can't count tokens; characters are + # the best proxy we have. If the read produced an unreasonable + # amount of content, reject it and tell the model to narrow down. + # Note: we check the formatted content (with line-number prefixes), + # not the raw file size, because that's what actually enters context. + # Check BEFORE redaction to avoid expensive regex on huge content. + content_len = len(result.content or "") + file_size = result_dict.get("file_size", 0) + max_chars = _get_max_read_chars() + if content_len > max_chars: + total_lines = result_dict.get("total_lines", "unknown") + return json.dumps({ + "error": ( + f"Read produced {content_len:,} characters which exceeds " + f"the safety limit ({max_chars:,} chars). " + "Use offset and limit to read a smaller range. " + f"The file has {total_lines} lines total." + ), + "path": path, + "total_lines": total_lines, + "file_size": file_size, + }, ensure_ascii=False) + + # ── Redact secrets (after guard check to skip oversized content) ── + if result.content: + result.content = redact_sensitive_text(result.content) + result_dict["content"] = result.content + + # Large-file hint: if the file is big and the caller didn't ask + # for a narrow window, nudge toward targeted reads. + if (file_size and file_size > _LARGE_FILE_HINT_BYTES + and limit > 200 + and result_dict.get("truncated")): + result_dict.setdefault("_hint", ( + f"This file is large ({file_size:,} bytes). " + "Consider reading only the section you need with offset and limit " + "to keep context usage efficient." + )) + + # ── Track for consecutive-loop detection ────────────────────── + read_key = ("read", path, offset, limit) + with _read_tracker_lock: + # Ensure "dedup" key exists (backward compat with old tracker state) + if "dedup" not in task_data: + task_data["dedup"] = {} + task_data["read_history"].add((path, offset, limit)) + if task_data["last_key"] == read_key: + task_data["consecutive"] += 1 + else: + task_data["last_key"] = read_key + task_data["consecutive"] = 1 + count = task_data["consecutive"] + + # Store mtime at read time for two purposes: + # 1. Dedup: skip identical re-reads of unchanged files. + # 2. Staleness: warn on write/patch if the file changed since + # the agent last read it (external edit, concurrent agent, etc.). + try: + _mtime_now = os.path.getmtime(resolved_str) + task_data["dedup"][dedup_key] = _mtime_now + task_data.setdefault("read_timestamps", {})[resolved_str] = _mtime_now + except OSError: + pass # Can't stat — skip tracking for this entry + + if count >= 4: + # Hard block: stop returning content to break the loop + return json.dumps({ + "error": ( + f"BLOCKED: You have read this exact file region {count} times in a row. " + "The content has NOT changed. You already have this information. " + "STOP re-reading and proceed with your task." + ), + "path": path, + "already_read": count, + }, ensure_ascii=False) + elif count >= 3: + result_dict["_warning"] = ( + f"You have read this exact file region {count} times consecutively. " + "The content has not changed since your last read. Use the information you already have. " + "If you are stuck in a loop, stop reading and proceed with writing or responding." + ) + + return json.dumps(result_dict, ensure_ascii=False) + except Exception as e: + return tool_error(str(e)) + + + + +def reset_file_dedup(task_id: str = None): + """Clear the deduplication cache for file reads. + + Called after context compression — the original read content has been + summarised away, so the model needs the full content if it reads the + same file again. Without this, reads after compression would return + a "file unchanged" stub pointing at content that no longer exists in + context. + + Call with a task_id to clear just that task, or without to clear all. + """ + with _read_tracker_lock: + if task_id: + task_data = _read_tracker.get(task_id) + if task_data and "dedup" in task_data: + task_data["dedup"].clear() + else: + for task_data in _read_tracker.values(): + if "dedup" in task_data: + task_data["dedup"].clear() + + +def notify_other_tool_call(task_id: str = "default"): + """Reset consecutive read/search counter for a task. + + Called by the tool dispatcher (model_tools.py) whenever a tool OTHER + than read_file / search_files is executed. This ensures we only warn + or block on *truly consecutive* repeated reads — if the agent does + anything else in between (write, patch, terminal, etc.) the counter + resets and the next read is treated as fresh. + """ + with _read_tracker_lock: + task_data = _read_tracker.get(task_id) + if task_data: + task_data["last_key"] = None + task_data["consecutive"] = 0 + + +def _update_read_timestamp(filepath: str, task_id: str) -> None: + """Record the file's current modification time after a successful write. + + Called after write_file and patch so that consecutive edits by the + same task don't trigger false staleness warnings — each write + refreshes the stored timestamp to match the file's new state. + """ + try: + resolved = str(Path(filepath).expanduser().resolve()) + current_mtime = os.path.getmtime(resolved) + except (OSError, ValueError): + return + with _read_tracker_lock: + task_data = _read_tracker.get(task_id) + if task_data is not None: + task_data.setdefault("read_timestamps", {})[resolved] = current_mtime + + +def _check_file_staleness(filepath: str, task_id: str) -> str | None: + """Check whether a file was modified since the agent last read it. + + Returns a warning string if the file is stale (mtime changed since + the last read_file call for this task), or None if the file is fresh + or was never read. Does not block — the write still proceeds. + """ + try: + resolved = str(Path(filepath).expanduser().resolve()) + except (OSError, ValueError): + return None + with _read_tracker_lock: + task_data = _read_tracker.get(task_id) + if not task_data: + return None + read_mtime = task_data.get("read_timestamps", {}).get(resolved) + if read_mtime is None: + return None # File was never read — nothing to compare against + try: + current_mtime = os.path.getmtime(resolved) + except OSError: + return None # Can't stat — file may have been deleted, let write handle it + if current_mtime != read_mtime: + return ( + f"Warning: {filepath} was modified since you last read it " + "(external edit or concurrent agent). The content you read may be " + "stale. Consider re-reading the file to verify before writing." + ) + return None + + +def write_file_tool(path: str, content: str, task_id: str = "default") -> str: + """Write content to a file.""" + sensitive_err = _check_sensitive_path(path) + if sensitive_err: + return tool_error(sensitive_err) + try: + stale_warning = _check_file_staleness(path, task_id) + file_ops = _get_file_ops(task_id) + result = file_ops.write_file(path, content) + result_dict = result.to_dict() + if stale_warning: + result_dict["_warning"] = stale_warning + # Refresh the stored timestamp so consecutive writes by this + # task don't trigger false staleness warnings. + _update_read_timestamp(path, task_id) + return json.dumps(result_dict, ensure_ascii=False) + except Exception as e: + if _is_expected_write_exception(e): + logger.debug("write_file expected denial: %s: %s", type(e).__name__, e) + else: + logger.error("write_file error: %s: %s", type(e).__name__, e, exc_info=True) + return tool_error(str(e)) + + +def patch_tool(mode: str = "replace", path: str = None, old_string: str = None, + new_string: str = None, replace_all: bool = False, patch: str = None, + task_id: str = "default") -> str: + """Patch a file using replace mode or V4A patch format.""" + # Check sensitive paths for both replace (explicit path) and V4A patch (extract paths) + _paths_to_check = [] + if path: + _paths_to_check.append(path) + if mode == "patch" and patch: + import re as _re + for _m in _re.finditer(r'^\*\*\*\s+(?:Update|Add|Delete)\s+File:\s*(.+)$', patch, _re.MULTILINE): + _paths_to_check.append(_m.group(1).strip()) + for _p in _paths_to_check: + sensitive_err = _check_sensitive_path(_p) + if sensitive_err: + return tool_error(sensitive_err) + try: + # Check staleness for all files this patch will touch. + stale_warnings = [] + for _p in _paths_to_check: + _sw = _check_file_staleness(_p, task_id) + if _sw: + stale_warnings.append(_sw) + + file_ops = _get_file_ops(task_id) + + if mode == "replace": + if not path: + return tool_error("path required") + if old_string is None or new_string is None: + return tool_error("old_string and new_string required") + result = file_ops.patch_replace(path, old_string, new_string, replace_all) + elif mode == "patch": + if not patch: + return tool_error("patch content required") + result = file_ops.patch_v4a(patch) + else: + return tool_error(f"Unknown mode: {mode}") + + result_dict = result.to_dict() + if stale_warnings: + result_dict["_warning"] = stale_warnings[0] if len(stale_warnings) == 1 else " | ".join(stale_warnings) + # Refresh stored timestamps for all successfully-patched paths so + # consecutive edits by this task don't trigger false warnings. + if not result_dict.get("error"): + for _p in _paths_to_check: + _update_read_timestamp(_p, task_id) + result_json = json.dumps(result_dict, ensure_ascii=False) + # Hint when old_string not found — saves iterations where the agent + # retries with stale content instead of re-reading the file. + if result_dict.get("error") and "Could not find" in str(result_dict["error"]): + result_json += "\n\n[Hint: old_string not found. Use read_file to verify the current content, or search_files to locate the text.]" + return result_json + except Exception as e: + return tool_error(str(e)) + + +def search_tool(pattern: str, target: str = "content", path: str = ".", + file_glob: str = None, limit: int = 50, offset: int = 0, + output_mode: str = "content", context: int = 0, + task_id: str = "default") -> str: + """Search for content or files.""" + try: + # Track searches to detect *consecutive* repeated search loops. + # Include pagination args so users can page through truncated + # results without tripping the repeated-search guard. + search_key = ( + "search", + pattern, + target, + str(path), + file_glob or "", + limit, + offset, + ) + with _read_tracker_lock: + task_data = _read_tracker.setdefault(task_id, { + "last_key": None, "consecutive": 0, "read_history": set(), + }) + if task_data["last_key"] == search_key: + task_data["consecutive"] += 1 + else: + task_data["last_key"] = search_key + task_data["consecutive"] = 1 + count = task_data["consecutive"] + + if count >= 4: + return json.dumps({ + "error": ( + f"BLOCKED: You have run this exact search {count} times in a row. " + "The results have NOT changed. You already have this information. " + "STOP re-searching and proceed with your task." + ), + "pattern": pattern, + "already_searched": count, + }, ensure_ascii=False) + + file_ops = _get_file_ops(task_id) + result = file_ops.search( + pattern=pattern, path=path, target=target, file_glob=file_glob, + limit=limit, offset=offset, output_mode=output_mode, context=context + ) + if hasattr(result, 'matches'): + for m in result.matches: + if hasattr(m, 'content') and m.content: + m.content = redact_sensitive_text(m.content) + result_dict = result.to_dict() + + if count >= 3: + result_dict["_warning"] = ( + f"You have run this exact search {count} times consecutively. " + "The results have not changed. Use the information you already have." + ) + + result_json = json.dumps(result_dict, ensure_ascii=False) + # Hint when results were truncated — explicit next offset is clearer + # than relying on the model to infer it from total_count vs match count. + if result_dict.get("truncated"): + next_offset = offset + limit + result_json += f"\n\n[Hint: Results truncated. Use offset={next_offset} to see more, or narrow with a more specific pattern or file_glob.]" + return result_json + except Exception as e: + return tool_error(str(e)) + + + + +# --------------------------------------------------------------------------- +# Schemas + Registry +# --------------------------------------------------------------------------- +from tools.registry import registry, tool_error + + +def _check_file_reqs(): + """Lazy wrapper to avoid circular import with tools/__init__.py.""" + from tools import check_file_requirements + return check_file_requirements() + +READ_FILE_SCHEMA = { + "name": "read_file", + "description": "Read a text file with line numbers and pagination. Use this instead of cat/head/tail in terminal. Output format: 'LINE_NUM|CONTENT'. Suggests similar filenames if not found. Use offset and limit for large files. Reads exceeding ~100K characters are rejected; use offset and limit to read specific sections of large files. NOTE: Cannot read images or binary files — use vision_analyze for images.", + "parameters": { + "type": "object", + "properties": { + "path": {"type": "string", "description": "Path to the file to read (absolute, relative, or ~/path)"}, + "offset": {"type": "integer", "description": "Line number to start reading from (1-indexed, default: 1)", "default": 1, "minimum": 1}, + "limit": {"type": "integer", "description": "Maximum number of lines to read (default: 500, max: 2000)", "default": 500, "maximum": 2000} + }, + "required": ["path"] + } +} + +WRITE_FILE_SCHEMA = { + "name": "write_file", + "description": "Write content to a file, completely replacing existing content. Use this instead of echo/cat heredoc in terminal. Creates parent directories automatically. OVERWRITES the entire file — use 'patch' for targeted edits.", + "parameters": { + "type": "object", + "properties": { + "path": {"type": "string", "description": "Path to the file to write (will be created if it doesn't exist, overwritten if it does)"}, + "content": {"type": "string", "description": "Complete content to write to the file"} + }, + "required": ["path", "content"] + } +} + +PATCH_SCHEMA = { + "name": "patch", + "description": "Targeted find-and-replace edits in files. Use this instead of sed/awk in terminal. Uses fuzzy matching (9 strategies) so minor whitespace/indentation differences won't break it. Returns a unified diff. Auto-runs syntax checks after editing.\n\nReplace mode (default): find a unique string and replace it.\nPatch mode: apply V4A multi-file patches for bulk changes.", + "parameters": { + "type": "object", + "properties": { + "mode": {"type": "string", "enum": ["replace", "patch"], "description": "Edit mode: 'replace' for targeted find-and-replace, 'patch' for V4A multi-file patches", "default": "replace"}, + "path": {"type": "string", "description": "File path to edit (required for 'replace' mode)"}, + "old_string": {"type": "string", "description": "Text to find in the file (required for 'replace' mode). Must be unique in the file unless replace_all=true. Include enough surrounding context to ensure uniqueness."}, + "new_string": {"type": "string", "description": "Replacement text (required for 'replace' mode). Can be empty string to delete the matched text."}, + "replace_all": {"type": "boolean", "description": "Replace all occurrences instead of requiring a unique match (default: false)", "default": False}, + "patch": {"type": "string", "description": "V4A format patch content (required for 'patch' mode). Format:\n*** Begin Patch\n*** Update File: path/to/file\n@@ context hint @@\n context line\n-removed line\n+added line\n*** End Patch"} + }, + "required": ["mode"] + } +} + +SEARCH_FILES_SCHEMA = { + "name": "search_files", + "description": "Search file contents or find files by name. Use this instead of grep/rg/find/ls in terminal. Ripgrep-backed, faster than shell equivalents.\n\nContent search (target='content'): Regex search inside files. Output modes: full matches with line numbers, file paths only, or match counts.\n\nFile search (target='files'): Find files by glob pattern (e.g., '*.py', '*config*'). Also use this instead of ls — results sorted by modification time.", + "parameters": { + "type": "object", + "properties": { + "pattern": {"type": "string", "description": "Regex pattern for content search, or glob pattern (e.g., '*.py') for file search"}, + "target": {"type": "string", "enum": ["content", "files"], "description": "'content' searches inside file contents, 'files' searches for files by name", "default": "content"}, + "path": {"type": "string", "description": "Directory or file to search in (default: current working directory)", "default": "."}, + "file_glob": {"type": "string", "description": "Filter files by pattern in grep mode (e.g., '*.py' to only search Python files)"}, + "limit": {"type": "integer", "description": "Maximum number of results to return (default: 50)", "default": 50}, + "offset": {"type": "integer", "description": "Skip first N results for pagination (default: 0)", "default": 0}, + "output_mode": {"type": "string", "enum": ["content", "files_only", "count"], "description": "Output format for grep mode: 'content' shows matching lines with line numbers, 'files_only' lists file paths, 'count' shows match counts per file", "default": "content"}, + "context": {"type": "integer", "description": "Number of context lines before and after each match (grep mode only)", "default": 0} + }, + "required": ["pattern"] + } +} + + +def _handle_read_file(args, **kw): + tid = kw.get("task_id") or "default" + return read_file_tool(path=args.get("path", ""), offset=args.get("offset", 1), limit=args.get("limit", 500), task_id=tid) + + +def _handle_write_file(args, **kw): + tid = kw.get("task_id") or "default" + return write_file_tool(path=args.get("path", ""), content=args.get("content", ""), task_id=tid) + + +def _handle_patch(args, **kw): + tid = kw.get("task_id") or "default" + return patch_tool( + mode=args.get("mode", "replace"), path=args.get("path"), + old_string=args.get("old_string"), new_string=args.get("new_string"), + replace_all=args.get("replace_all", False), patch=args.get("patch"), task_id=tid) + + +def _handle_search_files(args, **kw): + tid = kw.get("task_id") or "default" + target_map = {"grep": "content", "find": "files"} + raw_target = args.get("target", "content") + target = target_map.get(raw_target, raw_target) + return search_tool( + pattern=args.get("pattern", ""), target=target, path=args.get("path", "."), + file_glob=args.get("file_glob"), limit=args.get("limit", 50), offset=args.get("offset", 0), + output_mode=args.get("output_mode", "content"), context=args.get("context", 0), task_id=tid) + + +registry.register(name="read_file", toolset="file", schema=READ_FILE_SCHEMA, handler=_handle_read_file, check_fn=_check_file_reqs, emoji="📖", max_result_size_chars=float('inf')) +registry.register(name="write_file", toolset="file", schema=WRITE_FILE_SCHEMA, handler=_handle_write_file, check_fn=_check_file_reqs, emoji="✍️", max_result_size_chars=100_000) +registry.register(name="patch", toolset="file", schema=PATCH_SCHEMA, handler=_handle_patch, check_fn=_check_file_reqs, emoji="🔧", max_result_size_chars=100_000) +registry.register(name="search_files", toolset="file", schema=SEARCH_FILES_SCHEMA, handler=_handle_search_files, check_fn=_check_file_reqs, emoji="🔎", max_result_size_chars=100_000) diff --git a/mindcli/_vendor/tools/fuzzy_match.py b/mindcli/_vendor/tools/fuzzy_match.py new file mode 100644 index 0000000..84833e0 --- /dev/null +++ b/mindcli/_vendor/tools/fuzzy_match.py @@ -0,0 +1,566 @@ +#!/usr/bin/env python3 +""" +Fuzzy Matching Module for File Operations + +Implements a multi-strategy matching chain to robustly find and replace text, +accommodating variations in whitespace, indentation, and escaping common +in LLM-generated code. + +The 8-strategy chain (inspired by OpenCode), tried in order: +1. Exact match - Direct string comparison +2. Line-trimmed - Strip leading/trailing whitespace per line +3. Whitespace normalized - Collapse multiple spaces/tabs to single space +4. Indentation flexible - Ignore indentation differences entirely +5. Escape normalized - Convert \\n literals to actual newlines +6. Trimmed boundary - Trim first/last line whitespace only +7. Block anchor - Match first+last lines, use similarity for middle +8. Context-aware - 50% line similarity threshold + +Multi-occurrence matching is handled via the replace_all flag. + +Usage: + from tools.fuzzy_match import fuzzy_find_and_replace + + new_content, match_count, strategy, error = fuzzy_find_and_replace( + content="def foo():\\n pass", + old_string="def foo():", + new_string="def bar():", + replace_all=False + ) +""" + +import re +from typing import Tuple, Optional, List, Callable +from difflib import SequenceMatcher + +UNICODE_MAP = { + "\u201c": '"', "\u201d": '"', # smart double quotes + "\u2018": "'", "\u2019": "'", # smart single quotes + "\u2014": "--", "\u2013": "-", # em/en dashes + "\u2026": "...", "\u00a0": " ", # ellipsis and non-breaking space +} + +def _unicode_normalize(text: str) -> str: + """Normalizes Unicode characters to their standard ASCII equivalents.""" + for char, repl in UNICODE_MAP.items(): + text = text.replace(char, repl) + return text + + +def fuzzy_find_and_replace(content: str, old_string: str, new_string: str, + replace_all: bool = False) -> Tuple[str, int, Optional[str], Optional[str]]: + """ + Find and replace text using a chain of increasingly fuzzy matching strategies. + + Args: + content: The file content to search in + old_string: The text to find + new_string: The replacement text + replace_all: If True, replace all occurrences; if False, require uniqueness + + Returns: + Tuple of (new_content, match_count, strategy_name, error_message) + - If successful: (modified_content, number_of_replacements, strategy_used, None) + - If failed: (original_content, 0, None, error_description) + """ + if not old_string: + return content, 0, None, "old_string cannot be empty" + + if old_string == new_string: + return content, 0, None, "old_string and new_string are identical" + + # Try each matching strategy in order + strategies: List[Tuple[str, Callable]] = [ + ("exact", _strategy_exact), + ("line_trimmed", _strategy_line_trimmed), + ("whitespace_normalized", _strategy_whitespace_normalized), + ("indentation_flexible", _strategy_indentation_flexible), + ("escape_normalized", _strategy_escape_normalized), + ("trimmed_boundary", _strategy_trimmed_boundary), + ("unicode_normalized", _strategy_unicode_normalized), + ("block_anchor", _strategy_block_anchor), + ("context_aware", _strategy_context_aware), + ] + + for strategy_name, strategy_fn in strategies: + matches = strategy_fn(content, old_string) + + if matches: + # Found matches with this strategy + if len(matches) > 1 and not replace_all: + return content, 0, None, ( + f"Found {len(matches)} matches for old_string. " + f"Provide more context to make it unique, or use replace_all=True." + ) + + # Perform replacement + new_content = _apply_replacements(content, matches, new_string) + return new_content, len(matches), strategy_name, None + + # No strategy found a match + return content, 0, None, "Could not find a match for old_string in the file" + + +def _apply_replacements(content: str, matches: List[Tuple[int, int]], new_string: str) -> str: + """ + Apply replacements at the given positions. + + Args: + content: Original content + matches: List of (start, end) positions to replace + new_string: Replacement text + + Returns: + Content with replacements applied + """ + # Sort matches by position (descending) to replace from end to start + # This preserves positions of earlier matches + sorted_matches = sorted(matches, key=lambda x: x[0], reverse=True) + + result = content + for start, end in sorted_matches: + result = result[:start] + new_string + result[end:] + + return result + + +# ============================================================================= +# Matching Strategies +# ============================================================================= + +def _strategy_exact(content: str, pattern: str) -> List[Tuple[int, int]]: + """Strategy 1: Exact string match.""" + matches = [] + start = 0 + while True: + pos = content.find(pattern, start) + if pos == -1: + break + matches.append((pos, pos + len(pattern))) + start = pos + 1 + return matches + + +def _strategy_line_trimmed(content: str, pattern: str) -> List[Tuple[int, int]]: + """ + Strategy 2: Match with line-by-line whitespace trimming. + + Strips leading/trailing whitespace from each line before matching. + """ + # Normalize pattern and content by trimming each line + pattern_lines = [line.strip() for line in pattern.split('\n')] + pattern_normalized = '\n'.join(pattern_lines) + + content_lines = content.split('\n') + content_normalized_lines = [line.strip() for line in content_lines] + + # Build mapping from normalized positions back to original positions + return _find_normalized_matches( + content, content_lines, content_normalized_lines, + pattern, pattern_normalized + ) + + +def _strategy_whitespace_normalized(content: str, pattern: str) -> List[Tuple[int, int]]: + """ + Strategy 3: Collapse multiple whitespace to single space. + """ + def normalize(s): + # Collapse multiple spaces/tabs to single space, preserve newlines + return re.sub(r'[ \t]+', ' ', s) + + pattern_normalized = normalize(pattern) + content_normalized = normalize(content) + + # Find in normalized, map back to original + matches_in_normalized = _strategy_exact(content_normalized, pattern_normalized) + + if not matches_in_normalized: + return [] + + # Map positions back to original content + return _map_normalized_positions(content, content_normalized, matches_in_normalized) + + +def _strategy_indentation_flexible(content: str, pattern: str) -> List[Tuple[int, int]]: + """ + Strategy 4: Ignore indentation differences entirely. + + Strips all leading whitespace from lines before matching. + """ + content_lines = content.split('\n') + content_stripped_lines = [line.lstrip() for line in content_lines] + pattern_lines = [line.lstrip() for line in pattern.split('\n')] + + return _find_normalized_matches( + content, content_lines, content_stripped_lines, + pattern, '\n'.join(pattern_lines) + ) + + +def _strategy_escape_normalized(content: str, pattern: str) -> List[Tuple[int, int]]: + """ + Strategy 5: Convert escape sequences to actual characters. + + Handles \\n -> newline, \\t -> tab, etc. + """ + def unescape(s): + # Convert common escape sequences + return s.replace('\\n', '\n').replace('\\t', '\t').replace('\\r', '\r') + + pattern_unescaped = unescape(pattern) + + if pattern_unescaped == pattern: + # No escapes to convert, skip this strategy + return [] + + return _strategy_exact(content, pattern_unescaped) + + +def _strategy_trimmed_boundary(content: str, pattern: str) -> List[Tuple[int, int]]: + """ + Strategy 6: Trim whitespace from first and last lines only. + + Useful when the pattern boundaries have whitespace differences. + """ + pattern_lines = pattern.split('\n') + if not pattern_lines: + return [] + + # Trim only first and last lines + pattern_lines[0] = pattern_lines[0].strip() + if len(pattern_lines) > 1: + pattern_lines[-1] = pattern_lines[-1].strip() + + modified_pattern = '\n'.join(pattern_lines) + + content_lines = content.split('\n') + + # Search through content for matching block + matches = [] + pattern_line_count = len(pattern_lines) + + for i in range(len(content_lines) - pattern_line_count + 1): + block_lines = content_lines[i:i + pattern_line_count] + + # Trim first and last of this block + check_lines = block_lines.copy() + check_lines[0] = check_lines[0].strip() + if len(check_lines) > 1: + check_lines[-1] = check_lines[-1].strip() + + if '\n'.join(check_lines) == modified_pattern: + # Found match - calculate original positions + start_pos, end_pos = _calculate_line_positions( + content_lines, i, i + pattern_line_count, len(content) + ) + matches.append((start_pos, end_pos)) + + return matches + + +def _build_orig_to_norm_map(original: str) -> List[int]: + """Build a list mapping each original character index to its normalized index. + + Because UNICODE_MAP replacements may expand characters (e.g. em-dash → '--', + ellipsis → '...'), the normalised string can be longer than the original. + This map lets us convert positions in the normalised string back to the + corresponding positions in the original string. + + Returns a list of length ``len(original) + 1``; entry ``i`` is the + normalised index that character ``i`` maps to. + """ + result: List[int] = [] + norm_pos = 0 + for char in original: + result.append(norm_pos) + repl = UNICODE_MAP.get(char) + norm_pos += len(repl) if repl is not None else 1 + result.append(norm_pos) # sentinel: one past the last character + return result + + +def _map_positions_norm_to_orig( + orig_to_norm: List[int], + norm_matches: List[Tuple[int, int]], +) -> List[Tuple[int, int]]: + """Convert (start, end) positions in the normalised string to original positions.""" + # Invert the map: norm_pos -> first original position with that norm_pos + norm_to_orig_start: dict[int, int] = {} + for orig_pos, norm_pos in enumerate(orig_to_norm[:-1]): + if norm_pos not in norm_to_orig_start: + norm_to_orig_start[norm_pos] = orig_pos + + results: List[Tuple[int, int]] = [] + orig_len = len(orig_to_norm) - 1 # number of original characters + + for norm_start, norm_end in norm_matches: + if norm_start not in norm_to_orig_start: + continue + orig_start = norm_to_orig_start[norm_start] + + # Walk forward until orig_to_norm[orig_end] >= norm_end + orig_end = orig_start + while orig_end < orig_len and orig_to_norm[orig_end] < norm_end: + orig_end += 1 + + results.append((orig_start, orig_end)) + + return results + + +def _strategy_unicode_normalized(content: str, pattern: str) -> List[Tuple[int, int]]: + """Strategy 7: Unicode normalisation. + + Normalises smart quotes, em/en-dashes, ellipsis, and non-breaking spaces + to their ASCII equivalents in both *content* and *pattern*, then runs + exact and line_trimmed matching on the normalised copies. + + Positions are mapped back to the *original* string via + ``_build_orig_to_norm_map`` — necessary because some UNICODE_MAP + replacements expand a single character into multiple ASCII characters, + making a naïve position copy incorrect. + """ + # Normalize both sides. Either the content or the pattern (or both) may + # carry unicode variants — e.g. content has an em-dash that should match + # the LLM's ASCII '--', or vice-versa. Skip only when neither changes. + norm_pattern = _unicode_normalize(pattern) + norm_content = _unicode_normalize(content) + if norm_content == content and norm_pattern == pattern: + return [] + + norm_matches = _strategy_exact(norm_content, norm_pattern) + if not norm_matches: + norm_matches = _strategy_line_trimmed(norm_content, norm_pattern) + + if not norm_matches: + return [] + + orig_to_norm = _build_orig_to_norm_map(content) + return _map_positions_norm_to_orig(orig_to_norm, norm_matches) + + +def _strategy_block_anchor(content: str, pattern: str) -> List[Tuple[int, int]]: + """ + Strategy 8: Match by anchoring on first and last lines. + Adjusted with permissive thresholds and unicode normalization. + """ + # Normalize both strings for comparison while keeping original content for offset calculation + norm_pattern = _unicode_normalize(pattern) + norm_content = _unicode_normalize(content) + + pattern_lines = norm_pattern.split('\n') + if len(pattern_lines) < 2: + return [] + + first_line = pattern_lines[0].strip() + last_line = pattern_lines[-1].strip() + + # Use normalized lines for matching logic + norm_content_lines = norm_content.split('\n') + # BUT use original lines for calculating start/end positions to prevent index shift + orig_content_lines = content.split('\n') + + pattern_line_count = len(pattern_lines) + + potential_matches = [] + for i in range(len(norm_content_lines) - pattern_line_count + 1): + if (norm_content_lines[i].strip() == first_line and + norm_content_lines[i + pattern_line_count - 1].strip() == last_line): + potential_matches.append(i) + + matches = [] + candidate_count = len(potential_matches) + + # Thresholding logic: 0.50 for unique matches, 0.70 for multiple candidates. + # Previous values (0.10 / 0.30) were dangerously loose — a 10% middle-section + # similarity could match completely unrelated blocks. + threshold = 0.50 if candidate_count == 1 else 0.70 + + for i in potential_matches: + if pattern_line_count <= 2: + similarity = 1.0 + else: + # Compare normalized middle sections + content_middle = '\n'.join(norm_content_lines[i+1:i+pattern_line_count-1]) + pattern_middle = '\n'.join(pattern_lines[1:-1]) + similarity = SequenceMatcher(None, content_middle, pattern_middle).ratio() + + if similarity >= threshold: + # Calculate positions using ORIGINAL lines to ensure correct character offsets in the file + start_pos, end_pos = _calculate_line_positions( + orig_content_lines, i, i + pattern_line_count, len(content) + ) + matches.append((start_pos, end_pos)) + + return matches + + +def _strategy_context_aware(content: str, pattern: str) -> List[Tuple[int, int]]: + """ + Strategy 9: Line-by-line similarity with 50% threshold. + + Finds blocks where at least 50% of lines have high similarity. + """ + pattern_lines = pattern.split('\n') + content_lines = content.split('\n') + + if not pattern_lines: + return [] + + matches = [] + pattern_line_count = len(pattern_lines) + + for i in range(len(content_lines) - pattern_line_count + 1): + block_lines = content_lines[i:i + pattern_line_count] + + # Calculate line-by-line similarity + high_similarity_count = 0 + for p_line, c_line in zip(pattern_lines, block_lines): + sim = SequenceMatcher(None, p_line.strip(), c_line.strip()).ratio() + if sim >= 0.80: + high_similarity_count += 1 + + # Need at least 50% of lines to have high similarity + if high_similarity_count >= len(pattern_lines) * 0.5: + start_pos, end_pos = _calculate_line_positions( + content_lines, i, i + pattern_line_count, len(content) + ) + matches.append((start_pos, end_pos)) + + return matches + + +# ============================================================================= +# Helper Functions +# ============================================================================= + +def _calculate_line_positions(content_lines: List[str], start_line: int, + end_line: int, content_length: int) -> Tuple[int, int]: + """Calculate start and end character positions from line indices. + + Args: + content_lines: List of lines (without newlines) + start_line: Starting line index (0-based) + end_line: Ending line index (exclusive, 0-based) + content_length: Total length of the original content string + + Returns: + Tuple of (start_pos, end_pos) in the original content + """ + start_pos = sum(len(line) + 1 for line in content_lines[:start_line]) + end_pos = sum(len(line) + 1 for line in content_lines[:end_line]) - 1 + if end_pos >= content_length: + end_pos = content_length + return start_pos, end_pos + + +def _find_normalized_matches(content: str, content_lines: List[str], + content_normalized_lines: List[str], + pattern: str, pattern_normalized: str) -> List[Tuple[int, int]]: + """ + Find matches in normalized content and map back to original positions. + + Args: + content: Original content string + content_lines: Original content split by lines + content_normalized_lines: Normalized content lines + pattern: Original pattern + pattern_normalized: Normalized pattern + + Returns: + List of (start, end) positions in the original content + """ + pattern_norm_lines = pattern_normalized.split('\n') + num_pattern_lines = len(pattern_norm_lines) + + matches = [] + + for i in range(len(content_normalized_lines) - num_pattern_lines + 1): + # Check if this block matches + block = '\n'.join(content_normalized_lines[i:i + num_pattern_lines]) + + if block == pattern_normalized: + # Found a match - calculate original positions + start_pos, end_pos = _calculate_line_positions( + content_lines, i, i + num_pattern_lines, len(content) + ) + matches.append((start_pos, end_pos)) + + return matches + + +def _map_normalized_positions(original: str, normalized: str, + normalized_matches: List[Tuple[int, int]]) -> List[Tuple[int, int]]: + """ + Map positions from normalized string back to original. + + This is a best-effort mapping that works for whitespace normalization. + """ + if not normalized_matches: + return [] + + # Build character mapping from normalized to original + orig_to_norm = [] # orig_to_norm[i] = position in normalized + + orig_idx = 0 + norm_idx = 0 + + while orig_idx < len(original) and norm_idx < len(normalized): + if original[orig_idx] == normalized[norm_idx]: + orig_to_norm.append(norm_idx) + orig_idx += 1 + norm_idx += 1 + elif original[orig_idx] in ' \t' and normalized[norm_idx] == ' ': + # Original has space/tab, normalized collapsed to space + orig_to_norm.append(norm_idx) + orig_idx += 1 + # Don't advance norm_idx yet - wait until all whitespace consumed + if orig_idx < len(original) and original[orig_idx] not in ' \t': + norm_idx += 1 + elif original[orig_idx] in ' \t': + # Extra whitespace in original + orig_to_norm.append(norm_idx) + orig_idx += 1 + else: + # Mismatch - shouldn't happen with our normalization + orig_to_norm.append(norm_idx) + orig_idx += 1 + + # Fill remaining + while orig_idx < len(original): + orig_to_norm.append(len(normalized)) + orig_idx += 1 + + # Reverse mapping: for each normalized position, find original range + norm_to_orig_start = {} + norm_to_orig_end = {} + + for orig_pos, norm_pos in enumerate(orig_to_norm): + if norm_pos not in norm_to_orig_start: + norm_to_orig_start[norm_pos] = orig_pos + norm_to_orig_end[norm_pos] = orig_pos + + # Map matches + original_matches = [] + for norm_start, norm_end in normalized_matches: + # Find original start + if norm_start in norm_to_orig_start: + orig_start = norm_to_orig_start[norm_start] + else: + # Find nearest + orig_start = min(i for i, n in enumerate(orig_to_norm) if n >= norm_start) + + # Find original end + if norm_end - 1 in norm_to_orig_end: + orig_end = norm_to_orig_end[norm_end - 1] + 1 + else: + orig_end = orig_start + (norm_end - norm_start) + + # Expand to include trailing whitespace that was normalized + while orig_end < len(original) and original[orig_end] in ' \t': + orig_end += 1 + + original_matches.append((orig_start, min(orig_end, len(original)))) + + return original_matches diff --git a/mindcli/_vendor/tools/homeassistant_tool.py b/mindcli/_vendor/tools/homeassistant_tool.py new file mode 100644 index 0000000..2e698a4 --- /dev/null +++ b/mindcli/_vendor/tools/homeassistant_tool.py @@ -0,0 +1,513 @@ +"""Home Assistant tool for controlling smart home devices via REST API. + +Registers four LLM-callable tools: +- ``ha_list_entities`` -- list/filter entities by domain or area +- ``ha_get_state`` -- get detailed state of a single entity +- ``ha_list_services`` -- list available services (actions) per domain +- ``ha_call_service`` -- call a HA service (turn_on, turn_off, set_temperature, etc.) + +Authentication uses a Long-Lived Access Token via ``HASS_TOKEN`` env var. +The HA instance URL is read from ``HASS_URL`` (default: http://homeassistant.local:8123). +""" + +import asyncio +import json +import logging +import os +import re +from typing import Any, Dict, Optional + +logger = logging.getLogger(__name__) + +# --------------------------------------------------------------------------- +# Configuration +# --------------------------------------------------------------------------- + +# Kept for backward compatibility (e.g. test monkeypatching); prefer _get_config(). +_HASS_URL: str = "" +_HASS_TOKEN: str = "" + + +def _get_config(): + """Return (hass_url, hass_token) from env vars at call time.""" + return ( + (_HASS_URL or os.getenv("HASS_URL", "http://homeassistant.local:8123")).rstrip("/"), + _HASS_TOKEN or os.getenv("HASS_TOKEN", ""), + ) + +# Regex for valid HA entity_id format (e.g. "light.living_room", "sensor.temperature_1") +_ENTITY_ID_RE = re.compile(r"^[a-z_][a-z0-9_]*\.[a-z0-9_]+$") + +# Regex for valid HA service/domain names (e.g. "light", "turn_on", "shell_command"). +# Only lowercase ASCII letters, digits, and underscores — no slashes, dots, or +# other characters that could allow path traversal in URL construction. +# The domain and service are interpolated into /api/services/{domain}/{service}, +# so allowing arbitrary strings would enable SSRF via path traversal +# (e.g. domain="../../api/config") or blocked-domain bypass +# (e.g. domain="shell_command/../light"). +_SERVICE_NAME_RE = re.compile(r"^[a-z][a-z0-9_]*$") + +# Service domains blocked for security -- these allow arbitrary code/command +# execution on the HA host or enable SSRF attacks on the local network. +# HA provides zero service-level access control; all safety must be in our layer. +_BLOCKED_DOMAINS = frozenset({ + "shell_command", # arbitrary shell commands as root in HA container + "command_line", # sensors/switches that execute shell commands + "python_script", # sandboxed but can escalate via hass.services.call() + "pyscript", # scripting integration with broader access + "hassio", # addon control, host shutdown/reboot, stdin to containers + "rest_command", # HTTP requests from HA server (SSRF vector) +}) + + +def _get_headers(token: str = "") -> Dict[str, str]: + """Return authorization headers for HA REST API.""" + if not token: + _, token = _get_config() + return { + "Authorization": f"Bearer {token}", + "Content-Type": "application/json", + } + + +# --------------------------------------------------------------------------- +# Async helpers (called from sync handlers via run_until_complete) +# --------------------------------------------------------------------------- + +def _filter_and_summarize( + states: list, + domain: Optional[str] = None, + area: Optional[str] = None, +) -> Dict[str, Any]: + """Filter raw HA states by domain/area and return a compact summary.""" + if domain: + states = [s for s in states if s.get("entity_id", "").startswith(f"{domain}.")] + + if area: + area_lower = area.lower() + states = [ + s for s in states + if area_lower in (s.get("attributes", {}).get("friendly_name", "") or "").lower() + or area_lower in (s.get("attributes", {}).get("area", "") or "").lower() + ] + + entities = [] + for s in states: + entities.append({ + "entity_id": s["entity_id"], + "state": s["state"], + "friendly_name": s.get("attributes", {}).get("friendly_name", ""), + }) + + return {"count": len(entities), "entities": entities} + + +async def _async_list_entities( + domain: Optional[str] = None, + area: Optional[str] = None, +) -> Dict[str, Any]: + """Fetch entity states from HA and optionally filter by domain/area.""" + import aiohttp + + hass_url, hass_token = _get_config() + url = f"{hass_url}/api/states" + async with aiohttp.ClientSession() as session: + async with session.get(url, headers=_get_headers(hass_token), timeout=aiohttp.ClientTimeout(total=15)) as resp: + resp.raise_for_status() + states = await resp.json() + + return _filter_and_summarize(states, domain, area) + + +async def _async_get_state(entity_id: str) -> Dict[str, Any]: + """Fetch detailed state of a single entity.""" + import aiohttp + + hass_url, hass_token = _get_config() + url = f"{hass_url}/api/states/{entity_id}" + async with aiohttp.ClientSession() as session: + async with session.get(url, headers=_get_headers(hass_token), timeout=aiohttp.ClientTimeout(total=10)) as resp: + resp.raise_for_status() + data = await resp.json() + + return { + "entity_id": data["entity_id"], + "state": data["state"], + "attributes": data.get("attributes", {}), + "last_changed": data.get("last_changed"), + "last_updated": data.get("last_updated"), + } + + +def _build_service_payload( + entity_id: Optional[str] = None, + data: Optional[Dict[str, Any]] = None, +) -> Dict[str, Any]: + """Build the JSON payload for a HA service call.""" + payload: Dict[str, Any] = {} + if data: + payload.update(data) + # entity_id parameter takes precedence over data["entity_id"] + if entity_id: + payload["entity_id"] = entity_id + return payload + + +def _parse_service_response( + domain: str, + service: str, + result: Any, +) -> Dict[str, Any]: + """Parse HA service call response into a structured result.""" + affected = [] + if isinstance(result, list): + for s in result: + affected.append({ + "entity_id": s.get("entity_id", ""), + "state": s.get("state", ""), + }) + + return { + "success": True, + "service": f"{domain}.{service}", + "affected_entities": affected, + } + + +async def _async_call_service( + domain: str, + service: str, + entity_id: Optional[str] = None, + data: Optional[Dict[str, Any]] = None, +) -> Dict[str, Any]: + """Call a Home Assistant service.""" + import aiohttp + + hass_url, hass_token = _get_config() + url = f"{hass_url}/api/services/{domain}/{service}" + payload = _build_service_payload(entity_id, data) + + async with aiohttp.ClientSession() as session: + async with session.post( + url, + headers=_get_headers(hass_token), + json=payload, + timeout=aiohttp.ClientTimeout(total=15), + ) as resp: + resp.raise_for_status() + result = await resp.json() + + return _parse_service_response(domain, service, result) + + +# --------------------------------------------------------------------------- +# Sync wrappers (handler signature: (args, **kw) -> str) +# --------------------------------------------------------------------------- + +def _run_async(coro): + """Run an async coroutine from a sync handler.""" + try: + loop = asyncio.get_running_loop() + except RuntimeError: + loop = None + + if loop and loop.is_running(): + # Already inside an event loop -- create a new thread + import concurrent.futures + with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool: + future = pool.submit(asyncio.run, coro) + return future.result(timeout=30) + else: + return asyncio.run(coro) + + +def _handle_list_entities(args: dict, **kw) -> str: + """Handler for ha_list_entities tool.""" + domain = args.get("domain") + area = args.get("area") + try: + result = _run_async(_async_list_entities(domain=domain, area=area)) + return json.dumps({"result": result}) + except Exception as e: + logger.error("ha_list_entities error: %s", e) + return tool_error(f"Failed to list entities: {e}") + + +def _handle_get_state(args: dict, **kw) -> str: + """Handler for ha_get_state tool.""" + entity_id = args.get("entity_id", "") + if not entity_id: + return tool_error("Missing required parameter: entity_id") + if not _ENTITY_ID_RE.match(entity_id): + return tool_error(f"Invalid entity_id format: {entity_id}") + try: + result = _run_async(_async_get_state(entity_id)) + return json.dumps({"result": result}) + except Exception as e: + logger.error("ha_get_state error: %s", e) + return tool_error(f"Failed to get state for {entity_id}: {e}") + + +def _handle_call_service(args: dict, **kw) -> str: + """Handler for ha_call_service tool.""" + domain = args.get("domain", "") + service = args.get("service", "") + if not domain or not service: + return tool_error("Missing required parameters: domain and service") + + # Validate domain/service format BEFORE the blocklist check — prevents + # path traversal in /api/services/{domain}/{service} and blocklist bypass + # via payloads like "shell_command/../light". + if not _SERVICE_NAME_RE.match(domain): + return tool_error(f"Invalid domain format: {domain!r}") + if not _SERVICE_NAME_RE.match(service): + return tool_error(f"Invalid service format: {service!r}") + + if domain in _BLOCKED_DOMAINS: + return json.dumps({ + "error": f"Service domain '{domain}' is blocked for security. " + f"Blocked domains: {', '.join(sorted(_BLOCKED_DOMAINS))}" + }) + + entity_id = args.get("entity_id") + if entity_id and not _ENTITY_ID_RE.match(entity_id): + return tool_error(f"Invalid entity_id format: {entity_id}") + + data = args.get("data") + if isinstance(data, str): + try: + data = json.loads(data) if data.strip() else None + except json.JSONDecodeError as e: + return tool_error(f"Invalid JSON string in 'data' parameter: {e}") + + try: + result = _run_async(_async_call_service(domain, service, entity_id, data)) + return json.dumps({"result": result}) + except Exception as e: + logger.error("ha_call_service error: %s", e) + return tool_error(f"Failed to call {domain}.{service}: {e}") + + +# --------------------------------------------------------------------------- +# List services +# --------------------------------------------------------------------------- + +async def _async_list_services(domain: Optional[str] = None) -> Dict[str, Any]: + """Fetch available services from HA and optionally filter by domain.""" + import aiohttp + + hass_url, hass_token = _get_config() + url = f"{hass_url}/api/services" + headers = {"Authorization": f"Bearer {hass_token}", "Content-Type": "application/json"} + async with aiohttp.ClientSession() as session: + async with session.get(url, headers=headers, timeout=aiohttp.ClientTimeout(total=15)) as resp: + resp.raise_for_status() + services = await resp.json() + + if domain: + services = [s for s in services if s.get("domain") == domain] + + # Compact the output for context efficiency + result = [] + for svc_domain in services: + d = svc_domain.get("domain", "") + domain_services = {} + for svc_name, svc_info in svc_domain.get("services", {}).items(): + svc_entry: Dict[str, Any] = {"description": svc_info.get("description", "")} + fields = svc_info.get("fields", {}) + if fields: + svc_entry["fields"] = { + k: v.get("description", "") for k, v in fields.items() + if isinstance(v, dict) + } + domain_services[svc_name] = svc_entry + result.append({"domain": d, "services": domain_services}) + + return {"count": len(result), "domains": result} + + +def _handle_list_services(args: dict, **kw) -> str: + """Handler for ha_list_services tool.""" + domain = args.get("domain") + try: + result = _run_async(_async_list_services(domain=domain)) + return json.dumps({"result": result}) + except Exception as e: + logger.error("ha_list_services error: %s", e) + return tool_error(f"Failed to list services: {e}") + + +# --------------------------------------------------------------------------- +# Availability check +# --------------------------------------------------------------------------- + +def _check_ha_available() -> bool: + """Tool is only available when HASS_TOKEN is set.""" + return bool(os.getenv("HASS_TOKEN")) + + +# --------------------------------------------------------------------------- +# Tool schemas +# --------------------------------------------------------------------------- + +HA_LIST_ENTITIES_SCHEMA = { + "name": "ha_list_entities", + "description": ( + "List Home Assistant entities. Optionally filter by domain " + "(light, switch, climate, sensor, binary_sensor, cover, fan, etc.) " + "or by area name (living room, kitchen, bedroom, etc.)." + ), + "parameters": { + "type": "object", + "properties": { + "domain": { + "type": "string", + "description": ( + "Entity domain to filter by (e.g. 'light', 'switch', 'climate', " + "'sensor', 'binary_sensor', 'cover', 'fan', 'media_player'). " + "Omit to list all entities." + ), + }, + "area": { + "type": "string", + "description": ( + "Area/room name to filter by (e.g. 'living room', 'kitchen'). " + "Matches against entity friendly names. Omit to list all." + ), + }, + }, + "required": [], + }, +} + +HA_GET_STATE_SCHEMA = { + "name": "ha_get_state", + "description": ( + "Get the detailed state of a single Home Assistant entity, including all " + "attributes (brightness, color, temperature setpoint, sensor readings, etc.)." + ), + "parameters": { + "type": "object", + "properties": { + "entity_id": { + "type": "string", + "description": ( + "The entity ID to query (e.g. 'light.living_room', " + "'climate.thermostat', 'sensor.temperature')." + ), + }, + }, + "required": ["entity_id"], + }, +} + +HA_LIST_SERVICES_SCHEMA = { + "name": "ha_list_services", + "description": ( + "List available Home Assistant services (actions) for device control. " + "Shows what actions can be performed on each device type and what " + "parameters they accept. Use this to discover how to control devices " + "found via ha_list_entities." + ), + "parameters": { + "type": "object", + "properties": { + "domain": { + "type": "string", + "description": ( + "Filter by domain (e.g. 'light', 'climate', 'switch'). " + "Omit to list services for all domains." + ), + }, + }, + "required": [], + }, +} + +HA_CALL_SERVICE_SCHEMA = { + "name": "ha_call_service", + "description": ( + "Call a Home Assistant service to control a device. Use ha_list_services " + "to discover available services and their parameters for each domain." + ), + "parameters": { + "type": "object", + "properties": { + "domain": { + "type": "string", + "description": ( + "Service domain (e.g. 'light', 'switch', 'climate', " + "'cover', 'media_player', 'fan', 'scene', 'script')." + ), + }, + "service": { + "type": "string", + "description": ( + "Service name (e.g. 'turn_on', 'turn_off', 'toggle', " + "'set_temperature', 'set_hvac_mode', 'open_cover', " + "'close_cover', 'set_volume_level')." + ), + }, + "entity_id": { + "type": "string", + "description": ( + "Target entity ID (e.g. 'light.living_room'). " + "Some services (like scene.turn_on) may not need this." + ), + }, + "data": { + "type": "string", + "description": ( + "Additional service data as a JSON string. Examples: " + '{"brightness": 255, "color_name": "blue"} for lights, ' + '{"temperature": 22, "hvac_mode": "heat"} for climate, ' + '{"volume_level": 0.5} for media players.' + ), + }, + }, + "required": ["domain", "service"], + }, +} + + +# --------------------------------------------------------------------------- +# Registration +# --------------------------------------------------------------------------- + +from tools.registry import registry, tool_error + +registry.register( + name="ha_list_entities", + toolset="homeassistant", + schema=HA_LIST_ENTITIES_SCHEMA, + handler=_handle_list_entities, + check_fn=_check_ha_available, + emoji="🏠", +) + +registry.register( + name="ha_get_state", + toolset="homeassistant", + schema=HA_GET_STATE_SCHEMA, + handler=_handle_get_state, + check_fn=_check_ha_available, + emoji="🏠", +) + +registry.register( + name="ha_list_services", + toolset="homeassistant", + schema=HA_LIST_SERVICES_SCHEMA, + handler=_handle_list_services, + check_fn=_check_ha_available, + emoji="🏠", +) + +registry.register( + name="ha_call_service", + toolset="homeassistant", + schema=HA_CALL_SERVICE_SCHEMA, + handler=_handle_call_service, + check_fn=_check_ha_available, + emoji="🏠", +) diff --git a/mindcli/_vendor/tools/ima_tool.py b/mindcli/_vendor/tools/ima_tool.py new file mode 100644 index 0000000..9cdd010 --- /dev/null +++ b/mindcli/_vendor/tools/ima_tool.py @@ -0,0 +1,254 @@ +""" +IMA 连接器工具 (ima_tool.py) + +与腾讯会议不同，IMA 是纯 REST API（HTTP POST + JSON）， +无需外部脚本，直接在进程内调用。 + + ┌──────────────────────────────────────────────────────┐ + │ 绑定流程：侧边栏 inline UI（填写 Client ID + API Key）│ + │ 调用流程：SKILL.md + Agent 对话 │ + └──────────────────────────────────────────────────────┘ + +凭证存储（per-user JSON）： + /opt/apps/mindos-next/backend/data/ima_tokens.json + 格式：{ "userId": {"client_id": "...", "api_key": "..."} } + +IMA OpenAPI 文档：https://ima.qq.com/agent-interface +""" + +import json +import logging +import os +import urllib.error +import urllib.request +from typing import Any, Dict + +from tools.registry import registry, tool_error, tool_result + +logger = logging.getLogger(__name__) + +# ── 常量 ── +_BASE_URL = "https://ima.qq.com/" +CREDENTIALS_URL = "https://ima.qq.com/agent-interface" +_SKILL_VERSION = "1.1.3" + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# 凭证存取（per-user，wiki/{userId}/.config/ima.json） +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +from tools._user_config import user_config_read, user_config_write, user_config_delete + + +def get_user_credentials(user_id: str) -> Dict[str, str]: + """返回 {"client_id": "...", "api_key": "..."} 或空 dict""" + creds = user_config_read(user_id, "ima") + if creds.get("client_id") and creds.get("api_key"): + return creds + # 兜底：全局 env + cid = os.environ.get("IMA_OPENAPI_CLIENTID", "").strip() + key = os.environ.get("IMA_OPENAPI_APIKEY", "").strip() + if cid and key: + return {"client_id": cid, "api_key": key} + return {} + + +def set_user_credentials(user_id: str, client_id: str, api_key: str) -> None: + """保存或清除指定用户的 IMA 凭证。两者为空则删除条目。""" + client_id = client_id.strip() + api_key = api_key.strip() + if client_id and api_key: + user_config_write(user_id, "ima", {"client_id": client_id, "api_key": api_key}) + else: + user_config_delete(user_id, "ima") + + +def has_user_credentials(user_id: str) -> bool: + return bool(get_user_credentials(user_id)) + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# HTTP 调用层（进程内，无需子进程） +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +def _ima_call(api_path: str, body: dict, creds: Dict[str, str]) -> Dict[str, Any]: + """ + 直接发送 HTTP POST 到 IMA OpenAPI。 + 返回解析后的 JSON dict，出错时返回 {"error": ...}。 + """ + url = _BASE_URL + api_path.lstrip("/") + headers = { + "Content-Type": "application/json", + "ima-openapi-clientid": creds["client_id"], + "ima-openapi-apikey": creds["api_key"], + "ima-openapi-ctx": f"skill_version={_SKILL_VERSION}", + } + data = json.dumps(body).encode("utf-8") + req = urllib.request.Request(url, data=data, headers=headers, method="POST") + try: + with urllib.request.urlopen(req, timeout=30) as r: + return json.loads(r.read().decode("utf-8")) + except urllib.error.HTTPError as e: + body_text = e.read().decode("utf-8", errors="replace")[:500] + return {"error": f"HTTP {e.code}", "detail": body_text} + except urllib.error.URLError as e: + return {"error": f"网络错误: {e}"} + except Exception as e: + return {"error": str(e)} + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# ① ima_list_profiles — 连接状态检查 +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +def _ima_list_profiles_handler(args: dict, **kwargs) -> str: + user_id = str(args.get("user_id", "")).strip() + if not user_id: + return tool_error("user_id 参数必填") + + if not has_user_credentials(user_id): + return tool_result( + success=True, + profiles=[], + count=0, + credentialsConfigured=False, + credentialsUrl=CREDENTIALS_URL, + notice="请前往上述链接获取 Client ID 和 API Key，并在侧边栏绑定。", + ) + + creds = get_user_credentials(user_id) + # 用 list_note (limit=1) 验证连通性 + logger.info("[ImaTool] checking connectivity for user=%s", user_id[:8]) + result = _ima_call("openapi/note/v1/list_note", {"cursor": "", "limit": 1}, creds) + + if "error" in result: + status = "error" + message = f"连接异常：{result['error']}" + else: + status = "connected" + message = "IMA 已连接。" + + profiles = [{ + "profileName": f"{user_id[:12]}_ima", + "label": "IMA 笔记 & 知识库", + "status": status, + "credentialsConfigured": True, + }] + + return tool_result( + success=True, + profiles=profiles, + count=len(profiles), + credentialsConfigured=True, + message=message, + ) + + +registry.register( + name="ima_list_profiles", + toolset="connectors", + description="检查 IMA 连接状态，返回账号信息。", + emoji="📝", + handler=_ima_list_profiles_handler, + schema={ + "name": "ima_list_profiles", + "description": "检查 IMA (QQ 笔记/知识库) 是否已连接，返回连接状态。", + "parameters": { + "type": "object", + "properties": { + "user_id": {"type": "string", "description": "MINDOS_USER_ID"}, + }, + "required": ["user_id"], + }, + }, +) + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# ② ima_query — 笔记和知识库操作 +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +_ALLOWED_API_PATHS = { + # Notes + "openapi/note/v1/list_notebook", + "openapi/note/v1/list_note", + "openapi/note/v1/search_note_book", + "openapi/note/v1/get_doc_content", + "openapi/note/v1/import_doc", + "openapi/note/v1/append_doc", + # Knowledge Base + "openapi/knowledge/v1/list_knowledge_base", + "openapi/knowledge/v1/search_knowledge_base", + "openapi/knowledge/v1/create_knowledge_base", + "openapi/knowledge/v1/delete_knowledge_base", + "openapi/knowledge/v1/add_url", +} + + +def _ima_query_handler(args: dict, **kwargs) -> str: + user_id = str(args.get("user_id", "")).strip() + api_path = str(args.get("api_path", "")).strip() + + if not user_id: + return tool_error("user_id 参数必填") + if not api_path: + return tool_error("api_path 参数必填") + if api_path not in _ALLOWED_API_PATHS: + return tool_error( + f"不支持的 API 路径：{api_path}。" + f"可选：{', '.join(sorted(_ALLOWED_API_PATHS))}" + ) + if not has_user_credentials(user_id): + return tool_error( + f"IMA 凭证未配置。请前往 {CREDENTIALS_URL} 获取 Client ID 和 API Key，" + "并在侧边栏「IMA」处绑定账号。" + ) + + body = args.get("body", {}) + if not isinstance(body, dict): + return tool_error("body 必须是 JSON 对象") + + creds = get_user_credentials(user_id) + logger.info("[ImaTool] call %s (user=%s)", api_path, user_id[:8]) + result = _ima_call(api_path, body, creds) + + if "error" in result: + return tool_error(f"调用失败：{result['error']}") + + return tool_result(success=True, data=result) + + +registry.register( + name="ima_query", + toolset="connectors", + description="查询或操作 IMA 笔记和知识库。", + emoji="📝", + handler=_ima_query_handler, + schema={ + "name": "ima_query", + "description": ( + "调用 IMA OpenAPI 操作笔记或知识库。需先在侧边栏完成凭证绑定。\n" + "笔记接口示例：\n" + " 搜索笔记: api_path=openapi/note/v1/search_note_book, body={\"search_type\":0,\"query_info\":{\"title\":\"xx\"},\"start\":0,\"end\":10}\n" + " 读取正文: api_path=openapi/note/v1/get_doc_content, body={\"doc_id\":\"xxx\",\"target_content_format\":0}\n" + " 新建笔记: api_path=openapi/note/v1/import_doc, body={\"content\":\"## 标题\\n内容\",\"content_format\":1}\n" + " 列出笔记: api_path=openapi/note/v1/list_note, body={\"cursor\":\"\",\"limit\":20}\n" + ), + "parameters": { + "type": "object", + "properties": { + "user_id": {"type": "string", "description": "MINDOS_USER_ID"}, + "api_path": { + "type": "string", + "description": "IMA API 路径", + "enum": sorted(_ALLOWED_API_PATHS), + }, + "body": { + "type": "object", + "description": "API 请求体（JSON 对象）", + }, + }, + "required": ["user_id", "api_path"], + }, + }, +) diff --git a/mindcli/_vendor/tools/image_generation_tool.py b/mindcli/_vendor/tools/image_generation_tool.py new file mode 100644 index 0000000..487b9b8 --- /dev/null +++ b/mindcli/_vendor/tools/image_generation_tool.py @@ -0,0 +1,693 @@ +#!/usr/bin/env python3 +""" +Image Generation Tools Module + +This module provides image generation tools using FAL.ai's FLUX 2 Pro model with +automatic upscaling via FAL.ai's Clarity Upscaler for enhanced image quality. + +Available tools: +- image_generate_tool: Generate images from text prompts with automatic upscaling + +Features: +- High-quality image generation using FLUX 2 Pro model +- Automatic 2x upscaling using Clarity Upscaler for enhanced quality +- Comprehensive parameter control (size, steps, guidance, etc.) +- Proper error handling and validation with fallback to original images +- Debug logging support +- Sync mode for immediate results + +Usage: + from image_generation_tool import image_generate_tool + import asyncio + + # Generate and automatically upscale an image + result = await image_generate_tool( + prompt="A serene mountain landscape with cherry blossoms", + image_size="landscape_4_3", + num_images=1 + ) +""" + +import json +import logging +import os +import datetime +import threading +import uuid +from typing import Dict, Any, Optional, Union +from urllib.parse import urlencode +import fal_client +from tools.debug_helpers import DebugSession +from tools.managed_tool_gateway import resolve_managed_tool_gateway +from tools.tool_backend_helpers import managed_nous_tools_enabled + +logger = logging.getLogger(__name__) + +# Configuration for image generation +DEFAULT_MODEL = "fal-ai/flux-2-pro" +DEFAULT_ASPECT_RATIO = "landscape" +DEFAULT_NUM_INFERENCE_STEPS = 50 +DEFAULT_GUIDANCE_SCALE = 4.5 +DEFAULT_NUM_IMAGES = 1 +DEFAULT_OUTPUT_FORMAT = "png" + +# Safety settings +ENABLE_SAFETY_CHECKER = False +SAFETY_TOLERANCE = "5" # Maximum tolerance (1-5, where 5 is most permissive) + +# Aspect ratio mapping - simplified choices for model to select +ASPECT_RATIO_MAP = { + "landscape": "landscape_16_9", + "square": "square_hd", + "portrait": "portrait_16_9" +} + +# Configuration for automatic upscaling +UPSCALER_MODEL = "fal-ai/clarity-upscaler" +UPSCALER_FACTOR = 2 +UPSCALER_SAFETY_CHECKER = False +UPSCALER_DEFAULT_PROMPT = "masterpiece, best quality, highres" +UPSCALER_NEGATIVE_PROMPT = "(worst quality, low quality, normal quality:2)" +UPSCALER_CREATIVITY = 0.35 +UPSCALER_RESEMBLANCE = 0.6 +UPSCALER_GUIDANCE_SCALE = 4 +UPSCALER_NUM_INFERENCE_STEPS = 18 + +# Valid parameter values for validation based on FLUX 2 Pro documentation +VALID_IMAGE_SIZES = [ + "square_hd", "square", "portrait_4_3", "portrait_16_9", "landscape_4_3", "landscape_16_9" +] +VALID_OUTPUT_FORMATS = ["jpeg", "png"] +VALID_ACCELERATION_MODES = ["none", "regular", "high"] + +_debug = DebugSession("image_tools", env_var="IMAGE_TOOLS_DEBUG") +_managed_fal_client = None +_managed_fal_client_config = None +_managed_fal_client_lock = threading.Lock() + + +def _resolve_managed_fal_gateway(): + """Return managed fal-queue gateway config when direct FAL credentials are absent.""" + if os.getenv("FAL_KEY"): + return None + return resolve_managed_tool_gateway("fal-queue") + + +def _normalize_fal_queue_url_format(queue_run_origin: str) -> str: + normalized_origin = str(queue_run_origin or "").strip().rstrip("/") + if not normalized_origin: + raise ValueError("Managed FAL queue origin is required") + return f"{normalized_origin}/" + + +class _ManagedFalSyncClient: + """Small per-instance wrapper around fal_client.SyncClient for managed queue hosts.""" + + def __init__(self, *, key: str, queue_run_origin: str): + sync_client_class = getattr(fal_client, "SyncClient", None) + if sync_client_class is None: + raise RuntimeError("fal_client.SyncClient is required for managed FAL gateway mode") + + client_module = getattr(fal_client, "client", None) + if client_module is None: + raise RuntimeError("fal_client.client is required for managed FAL gateway mode") + + self._queue_url_format = _normalize_fal_queue_url_format(queue_run_origin) + self._sync_client = sync_client_class(key=key) + self._http_client = getattr(self._sync_client, "_client", None) + self._maybe_retry_request = getattr(client_module, "_maybe_retry_request", None) + self._raise_for_status = getattr(client_module, "_raise_for_status", None) + self._request_handle_class = getattr(client_module, "SyncRequestHandle", None) + self._add_hint_header = getattr(client_module, "add_hint_header", None) + self._add_priority_header = getattr(client_module, "add_priority_header", None) + self._add_timeout_header = getattr(client_module, "add_timeout_header", None) + + if self._http_client is None: + raise RuntimeError("fal_client.SyncClient._client is required for managed FAL gateway mode") + if self._maybe_retry_request is None or self._raise_for_status is None: + raise RuntimeError("fal_client.client request helpers are required for managed FAL gateway mode") + if self._request_handle_class is None: + raise RuntimeError("fal_client.client.SyncRequestHandle is required for managed FAL gateway mode") + + def submit( + self, + application: str, + arguments: Dict[str, Any], + *, + path: str = "", + hint: Optional[str] = None, + webhook_url: Optional[str] = None, + priority: Any = None, + headers: Optional[Dict[str, str]] = None, + start_timeout: Optional[Union[int, float]] = None, + ): + url = self._queue_url_format + application + if path: + url += "/" + path.lstrip("/") + if webhook_url is not None: + url += "?" + urlencode({"fal_webhook": webhook_url}) + + request_headers = dict(headers or {}) + if hint is not None and self._add_hint_header is not None: + self._add_hint_header(hint, request_headers) + if priority is not None: + if self._add_priority_header is None: + raise RuntimeError("fal_client.client.add_priority_header is required for priority requests") + self._add_priority_header(priority, request_headers) + if start_timeout is not None: + if self._add_timeout_header is None: + raise RuntimeError("fal_client.client.add_timeout_header is required for timeout requests") + self._add_timeout_header(start_timeout, request_headers) + + response = self._maybe_retry_request( + self._http_client, + "POST", + url, + json=arguments, + timeout=getattr(self._sync_client, "default_timeout", 120.0), + headers=request_headers, + ) + self._raise_for_status(response) + + data = response.json() + return self._request_handle_class( + request_id=data["request_id"], + response_url=data["response_url"], + status_url=data["status_url"], + cancel_url=data["cancel_url"], + client=self._http_client, + ) + + +def _get_managed_fal_client(managed_gateway): + """Reuse the managed FAL client so its internal httpx.Client is not leaked per call.""" + global _managed_fal_client, _managed_fal_client_config + + client_config = ( + managed_gateway.gateway_origin.rstrip("/"), + managed_gateway.nous_user_token, + ) + with _managed_fal_client_lock: + if _managed_fal_client is not None and _managed_fal_client_config == client_config: + return _managed_fal_client + + _managed_fal_client = _ManagedFalSyncClient( + key=managed_gateway.nous_user_token, + queue_run_origin=managed_gateway.gateway_origin, + ) + _managed_fal_client_config = client_config + return _managed_fal_client + + +def _submit_fal_request(model: str, arguments: Dict[str, Any]): + """Submit a FAL request using direct credentials or the managed queue gateway.""" + request_headers = {"x-idempotency-key": str(uuid.uuid4())} + managed_gateway = _resolve_managed_fal_gateway() + if managed_gateway is None: + return fal_client.submit(model, arguments=arguments, headers=request_headers) + + managed_client = _get_managed_fal_client(managed_gateway) + return managed_client.submit( + model, + arguments=arguments, + headers=request_headers, + ) + + +def _validate_parameters( + image_size: Union[str, Dict[str, int]], + num_inference_steps: int, + guidance_scale: float, + num_images: int, + output_format: str, + acceleration: str = "none" +) -> Dict[str, Any]: + """ + Validate and normalize image generation parameters for FLUX 2 Pro model. + + Args: + image_size: Either a preset string or custom size dict + num_inference_steps: Number of inference steps + guidance_scale: Guidance scale value + num_images: Number of images to generate + output_format: Output format for images + acceleration: Acceleration mode for generation speed + + Returns: + Dict[str, Any]: Validated and normalized parameters + + Raises: + ValueError: If any parameter is invalid + """ + validated = {} + + # Validate image_size + if isinstance(image_size, str): + if image_size not in VALID_IMAGE_SIZES: + raise ValueError(f"Invalid image_size '{image_size}'. Must be one of: {VALID_IMAGE_SIZES}") + validated["image_size"] = image_size + elif isinstance(image_size, dict): + if "width" not in image_size or "height" not in image_size: + raise ValueError("Custom image_size must contain 'width' and 'height' keys") + if not isinstance(image_size["width"], int) or not isinstance(image_size["height"], int): + raise ValueError("Custom image_size width and height must be integers") + if image_size["width"] < 64 or image_size["height"] < 64: + raise ValueError("Custom image_size dimensions must be at least 64x64") + if image_size["width"] > 2048 or image_size["height"] > 2048: + raise ValueError("Custom image_size dimensions must not exceed 2048x2048") + validated["image_size"] = image_size + else: + raise ValueError("image_size must be either a preset string or a dict with width/height") + + # Validate num_inference_steps + if not isinstance(num_inference_steps, int) or num_inference_steps < 1 or num_inference_steps > 100: + raise ValueError("num_inference_steps must be an integer between 1 and 100") + validated["num_inference_steps"] = num_inference_steps + + # Validate guidance_scale (FLUX 2 Pro default is 4.5) + if not isinstance(guidance_scale, (int, float)) or guidance_scale < 0.1 or guidance_scale > 20.0: + raise ValueError("guidance_scale must be a number between 0.1 and 20.0") + validated["guidance_scale"] = float(guidance_scale) + + # Validate num_images + if not isinstance(num_images, int) or num_images < 1 or num_images > 4: + raise ValueError("num_images must be an integer between 1 and 4") + validated["num_images"] = num_images + + # Validate output_format + if output_format not in VALID_OUTPUT_FORMATS: + raise ValueError(f"Invalid output_format '{output_format}'. Must be one of: {VALID_OUTPUT_FORMATS}") + validated["output_format"] = output_format + + # Validate acceleration + if acceleration not in VALID_ACCELERATION_MODES: + raise ValueError(f"Invalid acceleration '{acceleration}'. Must be one of: {VALID_ACCELERATION_MODES}") + validated["acceleration"] = acceleration + + return validated + + +def _upscale_image(image_url: str, original_prompt: str) -> Dict[str, Any]: + """ + Upscale an image using FAL.ai's Clarity Upscaler. + + Uses the synchronous fal_client API to avoid event loop lifecycle issues + when called from threaded contexts (e.g. gateway thread pool). + + Args: + image_url (str): URL of the image to upscale + original_prompt (str): Original prompt used to generate the image + + Returns: + Dict[str, Any]: Upscaled image data or None if upscaling fails + """ + try: + logger.info("Upscaling image with Clarity Upscaler...") + + # Prepare arguments for upscaler + upscaler_arguments = { + "image_url": image_url, + "prompt": f"{UPSCALER_DEFAULT_PROMPT}, {original_prompt}", + "upscale_factor": UPSCALER_FACTOR, + "negative_prompt": UPSCALER_NEGATIVE_PROMPT, + "creativity": UPSCALER_CREATIVITY, + "resemblance": UPSCALER_RESEMBLANCE, + "guidance_scale": UPSCALER_GUIDANCE_SCALE, + "num_inference_steps": UPSCALER_NUM_INFERENCE_STEPS, + "enable_safety_checker": UPSCALER_SAFETY_CHECKER + } + + # Use sync API — fal_client.submit() uses httpx.Client (no event loop). + # The async API (submit_async) caches a global httpx.AsyncClient via + # @cached_property, which breaks when asyncio.run() destroys the loop + # between calls (gateway thread-pool pattern). + handler = _submit_fal_request( + UPSCALER_MODEL, + arguments=upscaler_arguments, + ) + + # Get the upscaled result (sync — blocks until done) + result = handler.get() + + if result and "image" in result: + upscaled_image = result["image"] + logger.info("Image upscaled successfully to %sx%s", upscaled_image.get('width', 'unknown'), upscaled_image.get('height', 'unknown')) + return { + "url": upscaled_image["url"], + "width": upscaled_image.get("width", 0), + "height": upscaled_image.get("height", 0), + "upscaled": True, + "upscale_factor": UPSCALER_FACTOR + } + else: + logger.error("Upscaler returned invalid response") + return None + + except Exception as e: + logger.error("Error upscaling image: %s", e, exc_info=True) + return None + + +def image_generate_tool( + prompt: str, + aspect_ratio: str = DEFAULT_ASPECT_RATIO, + num_inference_steps: int = DEFAULT_NUM_INFERENCE_STEPS, + guidance_scale: float = DEFAULT_GUIDANCE_SCALE, + num_images: int = DEFAULT_NUM_IMAGES, + output_format: str = DEFAULT_OUTPUT_FORMAT, + seed: Optional[int] = None +) -> str: + """ + Generate images from text prompts using FAL.ai's FLUX 2 Pro model with automatic upscaling. + + Uses the synchronous fal_client API to avoid event loop lifecycle issues. + The async API's global httpx.AsyncClient (cached via @cached_property) breaks + when asyncio.run() destroys and recreates event loops between calls, which + happens in the gateway's thread-pool pattern. + + Args: + prompt (str): The text prompt describing the desired image + aspect_ratio (str): Image aspect ratio - "landscape", "square", or "portrait" (default: "landscape") + num_inference_steps (int): Number of denoising steps (1-50, default: 50) + guidance_scale (float): How closely to follow prompt (0.1-20.0, default: 4.5) + num_images (int): Number of images to generate (1-4, default: 1) + output_format (str): Image format "jpeg" or "png" (default: "png") + seed (Optional[int]): Random seed for reproducible results (optional) + + Returns: + str: JSON string containing minimal generation results: + { + "success": bool, + "image": str or None # URL of the upscaled image, or None if failed + } + """ + # Validate and map aspect_ratio to actual image_size + aspect_ratio_lower = aspect_ratio.lower().strip() if aspect_ratio else DEFAULT_ASPECT_RATIO + if aspect_ratio_lower not in ASPECT_RATIO_MAP: + logger.warning("Invalid aspect_ratio '%s', defaulting to '%s'", aspect_ratio, DEFAULT_ASPECT_RATIO) + aspect_ratio_lower = DEFAULT_ASPECT_RATIO + image_size = ASPECT_RATIO_MAP[aspect_ratio_lower] + + debug_call_data = { + "parameters": { + "prompt": prompt, + "aspect_ratio": aspect_ratio, + "image_size": image_size, + "num_inference_steps": num_inference_steps, + "guidance_scale": guidance_scale, + "num_images": num_images, + "output_format": output_format, + "seed": seed + }, + "error": None, + "success": False, + "images_generated": 0, + "generation_time": 0 + } + + start_time = datetime.datetime.now() + + try: + logger.info("Generating %s image(s) with FLUX 2 Pro: %s", num_images, prompt[:80]) + + # Validate prompt + if not prompt or not isinstance(prompt, str) or len(prompt.strip()) == 0: + raise ValueError("Prompt is required and must be a non-empty string") + + # Check API key availability + if not (os.getenv("FAL_KEY") or _resolve_managed_fal_gateway()): + message = "FAL_KEY environment variable not set" + if managed_nous_tools_enabled(): + message += " and managed FAL gateway is unavailable" + raise ValueError(message) + + # Validate other parameters + validated_params = _validate_parameters( + image_size, num_inference_steps, guidance_scale, num_images, output_format, "none" + ) + + # Prepare arguments for FAL.ai FLUX 2 Pro API + arguments = { + "prompt": prompt.strip(), + "image_size": validated_params["image_size"], + "num_inference_steps": validated_params["num_inference_steps"], + "guidance_scale": validated_params["guidance_scale"], + "num_images": validated_params["num_images"], + "output_format": validated_params["output_format"], + "enable_safety_checker": ENABLE_SAFETY_CHECKER, + "safety_tolerance": SAFETY_TOLERANCE, + "sync_mode": True # Use sync mode for immediate results + } + + # Add seed if provided + if seed is not None and isinstance(seed, int): + arguments["seed"] = seed + + logger.info("Submitting generation request to FAL.ai FLUX 2 Pro...") + logger.info(" Model: %s", DEFAULT_MODEL) + logger.info(" Aspect Ratio: %s -> %s", aspect_ratio_lower, image_size) + logger.info(" Steps: %s", validated_params['num_inference_steps']) + logger.info(" Guidance: %s", validated_params['guidance_scale']) + + # Submit request to FAL.ai using sync API (avoids cached event loop issues) + handler = _submit_fal_request( + DEFAULT_MODEL, + arguments=arguments, + ) + + # Get the result (sync — blocks until done) + result = handler.get() + + generation_time = (datetime.datetime.now() - start_time).total_seconds() + + # Process the response + if not result or "images" not in result: + raise ValueError("Invalid response from FAL.ai API - no images returned") + + images = result.get("images", []) + if not images: + raise ValueError("No images were generated") + + # Format image data and upscale images + formatted_images = [] + for img in images: + if isinstance(img, dict) and "url" in img: + original_image = { + "url": img["url"], + "width": img.get("width", 0), + "height": img.get("height", 0) + } + + # Attempt to upscale the image + upscaled_image = _upscale_image(img["url"], prompt.strip()) + + if upscaled_image: + # Use upscaled image if successful + formatted_images.append(upscaled_image) + else: + # Fall back to original image if upscaling fails + logger.warning("Using original image as fallback") + original_image["upscaled"] = False + formatted_images.append(original_image) + + if not formatted_images: + raise ValueError("No valid image URLs returned from API") + + upscaled_count = sum(1 for img in formatted_images if img.get("upscaled", False)) + logger.info("Generated %s image(s) in %.1fs (%s upscaled)", len(formatted_images), generation_time, upscaled_count) + + # Prepare successful response - minimal format + response_data = { + "success": True, + "image": formatted_images[0]["url"] if formatted_images else None + } + + debug_call_data["success"] = True + debug_call_data["images_generated"] = len(formatted_images) + debug_call_data["generation_time"] = generation_time + + # Log debug information + _debug.log_call("image_generate_tool", debug_call_data) + _debug.save() + + return json.dumps(response_data, indent=2, ensure_ascii=False) + + except Exception as e: + generation_time = (datetime.datetime.now() - start_time).total_seconds() + error_msg = f"Error generating image: {str(e)}" + logger.error("%s", error_msg, exc_info=True) + + # Include error details so callers can diagnose failures + response_data = { + "success": False, + "image": None, + "error": str(e), + "error_type": type(e).__name__, + } + + debug_call_data["error"] = error_msg + debug_call_data["generation_time"] = generation_time + _debug.log_call("image_generate_tool", debug_call_data) + _debug.save() + + return json.dumps(response_data, indent=2, ensure_ascii=False) + + +def check_fal_api_key() -> bool: + """ + Check if the FAL.ai API key is available in environment variables. + + Returns: + bool: True if API key is set, False otherwise + """ + return bool(os.getenv("FAL_KEY") or _resolve_managed_fal_gateway()) + + +def check_image_generation_requirements() -> bool: + """ + Check if all requirements for image generation tools are met. + + Returns: + bool: True if requirements are met, False otherwise + """ + try: + # Check API key + if not check_fal_api_key(): + return False + + # Check if fal_client is available + import fal_client # noqa: F401 — SDK presence check + return True + + except ImportError: + return False + + + +if __name__ == "__main__": + """ + Simple test/demo when run directly + """ + print("🎨 Image Generation Tools Module - FLUX 2 Pro + Auto Upscaling") + print("=" * 60) + + # Check if API key is available + api_available = check_fal_api_key() + + if not api_available: + print("❌ FAL_KEY environment variable not set") + print("Please set your API key: export FAL_KEY='your-key-here'") + print("Get API key at: https://fal.ai/") + exit(1) + else: + print("✅ FAL.ai API key found") + + # Check if fal_client is available + try: + import fal_client + print("✅ fal_client library available") + except ImportError: + print("❌ fal_client library not found") + print("Please install: pip install fal-client") + exit(1) + + print("🛠️ Image generation tools ready for use!") + print(f"🤖 Using model: {DEFAULT_MODEL}") + print(f"🔍 Auto-upscaling with: {UPSCALER_MODEL} ({UPSCALER_FACTOR}x)") + + # Show debug mode status + if _debug.active: + print(f"🐛 Debug mode ENABLED - Session ID: {_debug.session_id}") + print(f" Debug logs will be saved to: ./logs/image_tools_debug_{_debug.session_id}.json") + else: + print("🐛 Debug mode disabled (set IMAGE_TOOLS_DEBUG=true to enable)") + + print("\nBasic usage:") + print(" from image_generation_tool import image_generate_tool") + print(" import asyncio") + print("") + print(" async def main():") + print(" # Generate image with automatic 2x upscaling") + print(" result = await image_generate_tool(") + print(" prompt='A serene mountain landscape with cherry blossoms',") + print(" image_size='landscape_4_3',") + print(" num_images=1") + print(" )") + print(" print(result)") + print(" asyncio.run(main())") + + print("\nSupported image sizes:") + for size in VALID_IMAGE_SIZES: + print(f" - {size}") + print(" - Custom: {'width': 512, 'height': 768} (if needed)") + + print("\nAcceleration modes:") + for mode in VALID_ACCELERATION_MODES: + print(f" - {mode}") + + print("\nExample prompts:") + print(" - 'A candid street photo of a woman with a pink bob and bold eyeliner'") + print(" - 'Modern architecture building with glass facade, sunset lighting'") + print(" - 'Abstract art with vibrant colors and geometric patterns'") + print(" - 'Portrait of a wise old owl perched on ancient tree branch'") + print(" - 'Futuristic cityscape with flying cars and neon lights'") + + print("\nDebug mode:") + print(" # Enable debug logging") + print(" export IMAGE_TOOLS_DEBUG=true") + print(" # Debug logs capture all image generation calls and results") + print(" # Logs saved to: ./logs/image_tools_debug_UUID.json") + + +# --------------------------------------------------------------------------- +# Registry +# --------------------------------------------------------------------------- +from tools.registry import registry, tool_error + +IMAGE_GENERATE_SCHEMA = { + "name": "image_generate", + "description": "Generate high-quality images from text prompts using FLUX 2 Pro model with automatic 2x upscaling. Creates detailed, artistic images that are automatically upscaled for hi-rez results. Returns a single upscaled image URL. Display it using markdown: ![description](URL)", + "parameters": { + "type": "object", + "properties": { + "prompt": { + "type": "string", + "description": "The text prompt describing the desired image. Be detailed and descriptive." + }, + "aspect_ratio": { + "type": "string", + "enum": ["landscape", "square", "portrait"], + "description": "The aspect ratio of the generated image. 'landscape' is 16:9 wide, 'portrait' is 16:9 tall, 'square' is 1:1.", + "default": "landscape" + } + }, + "required": ["prompt"] + } +} + + +def _handle_image_generate(args, **kw): + prompt = args.get("prompt", "") + if not prompt: + return tool_error("prompt is required for image generation") + return image_generate_tool( + prompt=prompt, + aspect_ratio=args.get("aspect_ratio", "landscape"), + num_inference_steps=50, + guidance_scale=4.5, + num_images=1, + output_format="png", + seed=None, + ) + + +registry.register( + name="image_generate", + toolset="image_gen", + schema=IMAGE_GENERATE_SCHEMA, + handler=_handle_image_generate, + check_fn=check_image_generation_requirements, + requires_env=[], + is_async=False, # Switched to sync fal_client API to fix "Event loop is closed" in gateway + emoji="🎨", +) diff --git a/mindcli/_vendor/tools/interrupt.py b/mindcli/_vendor/tools/interrupt.py new file mode 100644 index 0000000..9bc8b83 --- /dev/null +++ b/mindcli/_vendor/tools/interrupt.py @@ -0,0 +1,76 @@ +"""Per-thread interrupt signaling for all tools. + +Provides thread-scoped interrupt tracking so that interrupting one agent +session does not kill tools running in other sessions. This is critical +in the gateway where multiple agents run concurrently in the same process. + +The agent stores its execution thread ID at the start of run_conversation() +and passes it to set_interrupt()/clear_interrupt(). Tools call +is_interrupted() which checks the CURRENT thread — no argument needed. + +Usage in tools: + from tools.interrupt import is_interrupted + if is_interrupted(): + return {"output": "[interrupted]", "returncode": 130} +""" + +import threading + +# Set of thread idents that have been interrupted. +_interrupted_threads: set[int] = set() +_lock = threading.Lock() + + +def set_interrupt(active: bool, thread_id: int | None = None) -> None: + """Set or clear interrupt for a specific thread. + + Args: + active: True to signal interrupt, False to clear it. + thread_id: Target thread ident. When None, targets the + current thread (backward compat for CLI/tests). + """ + tid = thread_id if thread_id is not None else threading.current_thread().ident + with _lock: + if active: + _interrupted_threads.add(tid) + else: + _interrupted_threads.discard(tid) + + +def is_interrupted() -> bool: + """Check if an interrupt has been requested for the current thread. + + Safe to call from any thread — each thread only sees its own + interrupt state. + """ + tid = threading.current_thread().ident + with _lock: + return tid in _interrupted_threads + + +# --------------------------------------------------------------------------- +# Backward-compatible _interrupt_event proxy +# --------------------------------------------------------------------------- +# Some legacy call sites (code_execution_tool, process_registry, tests) +# import _interrupt_event directly and call .is_set() / .set() / .clear(). +# This shim maps those calls to the per-thread functions above so existing +# code keeps working while the underlying mechanism is thread-scoped. + +class _ThreadAwareEventProxy: + """Drop-in proxy that maps threading.Event methods to per-thread state.""" + + def is_set(self) -> bool: + return is_interrupted() + + def set(self) -> None: # noqa: A003 + set_interrupt(True) + + def clear(self) -> None: + set_interrupt(False) + + def wait(self, timeout: float | None = None) -> bool: + """Not truly supported — returns current state immediately.""" + return self.is_set() + + +_interrupt_event = _ThreadAwareEventProxy() diff --git a/mindcli/_vendor/tools/managed_tool_gateway.py b/mindcli/_vendor/tools/managed_tool_gateway.py new file mode 100644 index 0000000..cd27537 --- /dev/null +++ b/mindcli/_vendor/tools/managed_tool_gateway.py @@ -0,0 +1,167 @@ +"""Generic managed-tool gateway helpers for Nous-hosted vendor passthroughs.""" + +from __future__ import annotations + +import json +import logging +import os +from datetime import datetime, timezone +from dataclasses import dataclass +from typing import Callable, Optional + +logger = logging.getLogger(__name__) + +from hermes_constants import get_hermes_home +from tools.tool_backend_helpers import managed_nous_tools_enabled + +_DEFAULT_TOOL_GATEWAY_DOMAIN = "nousresearch.com" +_DEFAULT_TOOL_GATEWAY_SCHEME = "https" +_NOUS_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 120 + + +@dataclass(frozen=True) +class ManagedToolGatewayConfig: + vendor: str + gateway_origin: str + nous_user_token: str + managed_mode: bool + + +def auth_json_path(): + """Return the Hermes auth store path, respecting HERMES_HOME overrides.""" + return get_hermes_home() / "auth.json" + + +def _read_nous_provider_state() -> Optional[dict]: + try: + path = auth_json_path() + if not path.is_file(): + return None + data = json.loads(path.read_text()) + providers = data.get("providers", {}) + if not isinstance(providers, dict): + return None + nous_provider = providers.get("nous", {}) + if isinstance(nous_provider, dict): + return nous_provider + except Exception: + pass + return None + + +def _parse_timestamp(value: object) -> Optional[datetime]: + if not isinstance(value, str) or not value.strip(): + return None + normalized = value.strip() + if normalized.endswith("Z"): + normalized = normalized[:-1] + "+00:00" + try: + parsed = datetime.fromisoformat(normalized) + except ValueError: + return None + if parsed.tzinfo is None: + parsed = parsed.replace(tzinfo=timezone.utc) + return parsed.astimezone(timezone.utc) + + +def _access_token_is_expiring(expires_at: object, skew_seconds: int) -> bool: + expires = _parse_timestamp(expires_at) + if expires is None: + return True + remaining = (expires - datetime.now(timezone.utc)).total_seconds() + return remaining <= max(0, int(skew_seconds)) + + +def read_nous_access_token() -> Optional[str]: + """Read a Nous Subscriber OAuth access token from auth store or env override.""" + explicit = os.getenv("TOOL_GATEWAY_USER_TOKEN") + if isinstance(explicit, str) and explicit.strip(): + return explicit.strip() + + nous_provider = _read_nous_provider_state() or {} + access_token = nous_provider.get("access_token") + cached_token = access_token.strip() if isinstance(access_token, str) and access_token.strip() else None + + if cached_token and not _access_token_is_expiring( + nous_provider.get("expires_at"), + _NOUS_ACCESS_TOKEN_REFRESH_SKEW_SECONDS, + ): + return cached_token + + try: + from hermes_cli.auth import resolve_nous_access_token + + refreshed_token = resolve_nous_access_token( + refresh_skew_seconds=_NOUS_ACCESS_TOKEN_REFRESH_SKEW_SECONDS, + ) + if isinstance(refreshed_token, str) and refreshed_token.strip(): + return refreshed_token.strip() + except Exception as exc: + logger.debug("Nous access token refresh failed: %s", exc) + + return cached_token + + +def get_tool_gateway_scheme() -> str: + """Return configured shared gateway URL scheme.""" + scheme = os.getenv("TOOL_GATEWAY_SCHEME", "").strip().lower() + if not scheme: + return _DEFAULT_TOOL_GATEWAY_SCHEME + + if scheme in {"http", "https"}: + return scheme + + raise ValueError("TOOL_GATEWAY_SCHEME must be 'http' or 'https'") + + +def build_vendor_gateway_url(vendor: str) -> str: + """Return the gateway origin for a specific vendor.""" + vendor_key = f"{vendor.upper().replace('-', '_')}_GATEWAY_URL" + explicit_vendor_url = os.getenv(vendor_key, "").strip().rstrip("/") + if explicit_vendor_url: + return explicit_vendor_url + + shared_scheme = get_tool_gateway_scheme() + shared_domain = os.getenv("TOOL_GATEWAY_DOMAIN", "").strip().strip("/") + if shared_domain: + return f"{shared_scheme}://{vendor}-gateway.{shared_domain}" + + return f"{shared_scheme}://{vendor}-gateway.{_DEFAULT_TOOL_GATEWAY_DOMAIN}" + + +def resolve_managed_tool_gateway( + vendor: str, + gateway_builder: Optional[Callable[[str], str]] = None, + token_reader: Optional[Callable[[], Optional[str]]] = None, +) -> Optional[ManagedToolGatewayConfig]: + """Resolve shared managed-tool gateway config for a vendor.""" + if not managed_nous_tools_enabled(): + return None + + resolved_gateway_builder = gateway_builder or build_vendor_gateway_url + resolved_token_reader = token_reader or read_nous_access_token + + gateway_origin = resolved_gateway_builder(vendor) + nous_user_token = resolved_token_reader() + if not gateway_origin or not nous_user_token: + return None + + return ManagedToolGatewayConfig( + vendor=vendor, + gateway_origin=gateway_origin, + nous_user_token=nous_user_token, + managed_mode=True, + ) + + +def is_managed_tool_gateway_ready( + vendor: str, + gateway_builder: Optional[Callable[[str], str]] = None, + token_reader: Optional[Callable[[], Optional[str]]] = None, +) -> bool: + """Return True when gateway URL and Nous access token are available.""" + return resolve_managed_tool_gateway( + vendor, + gateway_builder=gateway_builder, + token_reader=token_reader, + ) is not None diff --git a/mindcli/_vendor/tools/mcp_oauth.py b/mindcli/_vendor/tools/mcp_oauth.py new file mode 100644 index 0000000..6b0ef12 --- /dev/null +++ b/mindcli/_vendor/tools/mcp_oauth.py @@ -0,0 +1,482 @@ +#!/usr/bin/env python3 +""" +MCP OAuth 2.1 Client Support + +Implements the browser-based OAuth 2.1 authorization code flow with PKCE +for MCP servers that require OAuth authentication instead of static bearer +tokens. + +Uses the MCP Python SDK's ``OAuthClientProvider`` (an ``httpx.Auth`` subclass) +which handles discovery, dynamic client registration, PKCE, token exchange, +refresh, and step-up authorization automatically. + +This module provides the glue: + - ``HermesTokenStorage``: persists tokens/client-info to disk so they + survive across process restarts. + - Callback server: ephemeral localhost HTTP server to capture the OAuth + redirect with the authorization code. + - ``build_oauth_auth()``: entry point called by ``mcp_tool.py`` that wires + everything together and returns the ``httpx.Auth`` object. + +Configuration in config.yaml:: + + mcp_servers: + my_server: + url: "https://mcp.example.com/mcp" + auth: oauth + oauth: # all fields optional + client_id: "pre-registered-id" # skip dynamic registration + client_secret: "secret" # confidential clients only + scope: "read write" # default: server-provided + redirect_port: 0 # 0 = auto-pick free port + client_name: "My Custom Client" # default: "Hermes Agent" +""" + +import asyncio +import json +import logging +import os +import re +import socket +import sys +import threading +import webbrowser +from http.server import BaseHTTPRequestHandler, HTTPServer +from pathlib import Path +from typing import Any +from urllib.parse import parse_qs, urlparse + +logger = logging.getLogger(__name__) + +# --------------------------------------------------------------------------- +# Lazy imports -- MCP SDK with OAuth support is optional +# --------------------------------------------------------------------------- + +_OAUTH_AVAILABLE = False +try: + from mcp.client.auth import OAuthClientProvider + from mcp.shared.auth import ( + OAuthClientInformationFull, + OAuthClientMetadata, + OAuthToken, + ) + from pydantic import AnyUrl + + _OAUTH_AVAILABLE = True +except ImportError: + logger.debug("MCP OAuth types not available -- OAuth MCP auth disabled") + + +# --------------------------------------------------------------------------- +# Exceptions +# --------------------------------------------------------------------------- + + +class OAuthNonInteractiveError(RuntimeError): + """Raised when OAuth requires browser interaction in a non-interactive env.""" + + +# --------------------------------------------------------------------------- +# Module-level state +# --------------------------------------------------------------------------- + +# Port used by the most recent build_oauth_auth() call. Exposed so that +# tests can verify the callback server and the redirect_uri share a port. +_oauth_port: int | None = None + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +def _get_token_dir() -> Path: + """Return the directory for MCP OAuth token files. + + Uses HERMES_HOME so each profile gets its own OAuth tokens. + Layout: ``HERMES_HOME/mcp-tokens/`` + """ + try: + from hermes_constants import get_hermes_home + base = Path(get_hermes_home()) + except ImportError: + base = Path(os.environ.get("HERMES_HOME", str(Path.home() / ".hermes"))) + return base / "mcp-tokens" + + +def _safe_filename(name: str) -> str: + """Sanitize a server name for use as a filename (no path separators).""" + return re.sub(r"[^\w\-]", "_", name).strip("_")[:128] or "default" + + +def _find_free_port() -> int: + """Find an available TCP port on localhost.""" + with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: + s.bind(("127.0.0.1", 0)) + return s.getsockname()[1] + + +def _is_interactive() -> bool: + """Return True if we can reasonably expect to interact with a user.""" + try: + return sys.stdin.isatty() + except (AttributeError, ValueError): + return False + + +def _can_open_browser() -> bool: + """Return True if opening a browser is likely to work.""" + # Explicit SSH session → no local display + if os.environ.get("SSH_CLIENT") or os.environ.get("SSH_TTY"): + return False + # macOS and Windows usually have a display + if os.name == "nt": + return True + try: + if os.uname().sysname == "Darwin": + return True + except AttributeError: + pass + # Linux/other posix: need DISPLAY or WAYLAND_DISPLAY + if os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"): + return True + return False + + +def _read_json(path: Path) -> dict | None: + """Read a JSON file, returning None if it doesn't exist or is invalid.""" + if not path.exists(): + return None + try: + return json.loads(path.read_text(encoding="utf-8")) + except (json.JSONDecodeError, OSError) as exc: + logger.warning("Failed to read %s: %s", path, exc) + return None + + +def _write_json(path: Path, data: dict) -> None: + """Write a dict as JSON with restricted permissions (0o600).""" + path.parent.mkdir(parents=True, exist_ok=True) + tmp = path.with_suffix(".tmp") + try: + tmp.write_text(json.dumps(data, indent=2, default=str), encoding="utf-8") + os.chmod(tmp, 0o600) + tmp.rename(path) + except OSError: + tmp.unlink(missing_ok=True) + raise + + +# --------------------------------------------------------------------------- +# HermesTokenStorage -- persistent token/client-info on disk +# --------------------------------------------------------------------------- + + +class HermesTokenStorage: + """Persist OAuth tokens and client registration to JSON files. + + File layout:: + + HERMES_HOME/mcp-tokens/.json -- tokens + HERMES_HOME/mcp-tokens/.client.json -- client info + """ + + def __init__(self, server_name: str): + self._server_name = _safe_filename(server_name) + + def _tokens_path(self) -> Path: + return _get_token_dir() / f"{self._server_name}.json" + + def _client_info_path(self) -> Path: + return _get_token_dir() / f"{self._server_name}.client.json" + + # -- tokens ------------------------------------------------------------ + + async def get_tokens(self) -> "OAuthToken | None": + data = _read_json(self._tokens_path()) + if data is None: + return None + try: + return OAuthToken.model_validate(data) + except (ValueError, TypeError, KeyError) as exc: + logger.warning("Corrupt tokens at %s -- ignoring: %s", self._tokens_path(), exc) + return None + + async def set_tokens(self, tokens: "OAuthToken") -> None: + _write_json(self._tokens_path(), tokens.model_dump(exclude_none=True)) + logger.debug("OAuth tokens saved for %s", self._server_name) + + # -- client info ------------------------------------------------------- + + async def get_client_info(self) -> "OAuthClientInformationFull | None": + data = _read_json(self._client_info_path()) + if data is None: + return None + try: + return OAuthClientInformationFull.model_validate(data) + except (ValueError, TypeError, KeyError) as exc: + logger.warning("Corrupt client info at %s -- ignoring: %s", self._client_info_path(), exc) + return None + + async def set_client_info(self, client_info: "OAuthClientInformationFull") -> None: + _write_json(self._client_info_path(), client_info.model_dump(exclude_none=True)) + logger.debug("OAuth client info saved for %s", self._server_name) + + # -- cleanup ----------------------------------------------------------- + + def remove(self) -> None: + """Delete all stored OAuth state for this server.""" + for p in (self._tokens_path(), self._client_info_path()): + p.unlink(missing_ok=True) + + def has_cached_tokens(self) -> bool: + """Return True if we have tokens on disk (may be expired).""" + return self._tokens_path().exists() + + +# --------------------------------------------------------------------------- +# Callback handler factory -- each invocation gets its own result dict +# --------------------------------------------------------------------------- + + +def _make_callback_handler() -> tuple[type, dict]: + """Create a per-flow callback HTTP handler class with its own result dict. + + Returns ``(HandlerClass, result_dict)`` where *result_dict* is a mutable + dict that the handler writes ``auth_code`` and ``state`` into when the + OAuth redirect arrives. Each call returns a fresh pair so concurrent + flows don't stomp on each other. + """ + result: dict[str, Any] = {"auth_code": None, "state": None, "error": None} + + class _Handler(BaseHTTPRequestHandler): + def do_GET(self) -> None: # noqa: N802 + params = parse_qs(urlparse(self.path).query) + code = params.get("code", [None])[0] + state = params.get("state", [None])[0] + error = params.get("error", [None])[0] + + result["auth_code"] = code + result["state"] = state + result["error"] = error + + body = ( + "

Authorization Successful

" + "

You can close this tab and return to Hermes.

" + ) if code else ( + "

Authorization Failed

" + f"

Error: {error or 'unknown'}

" + ) + self.send_response(200) + self.send_header("Content-Type", "text/html; charset=utf-8") + self.end_headers() + self.wfile.write(body.encode()) + + def log_message(self, fmt: str, *args: Any) -> None: + logger.debug("OAuth callback: %s", fmt % args) + + return _Handler, result + + +# --------------------------------------------------------------------------- +# Async redirect + callback handlers for OAuthClientProvider +# --------------------------------------------------------------------------- + + +async def _redirect_handler(authorization_url: str) -> None: + """Show the authorization URL to the user. + + Opens the browser automatically when possible; always prints the URL + as a fallback for headless/SSH/gateway environments. + """ + msg = ( + f"\n MCP OAuth: authorization required.\n" + f" Open this URL in your browser:\n\n" + f" {authorization_url}\n" + ) + print(msg, file=sys.stderr) + + if _can_open_browser(): + try: + opened = webbrowser.open(authorization_url) + if opened: + print(" (Browser opened automatically.)\n", file=sys.stderr) + else: + print(" (Could not open browser — please open the URL manually.)\n", file=sys.stderr) + except Exception: + print(" (Could not open browser — please open the URL manually.)\n", file=sys.stderr) + else: + print(" (Headless environment detected — open the URL manually.)\n", file=sys.stderr) + + +async def _wait_for_callback() -> tuple[str, str | None]: + """Wait for the OAuth callback to arrive on the local callback server. + + Uses the module-level ``_oauth_port`` which is set by ``build_oauth_auth`` + before this is ever called. Polls for the result without blocking the + event loop. + + Raises: + OAuthNonInteractiveError: If the callback times out (no user present + to complete the browser auth). + """ + assert _oauth_port is not None, "OAuth callback port not set" + + # The callback server is already running (started in build_oauth_auth). + # We just need to poll for the result. + handler_cls, result = _make_callback_handler() + + # Start a temporary server on the known port + try: + server = HTTPServer(("127.0.0.1", _oauth_port), handler_cls) + except OSError: + # Port already in use — the server from build_oauth_auth is running. + # Fall back to polling the server started by build_oauth_auth. + raise OAuthNonInteractiveError( + "OAuth callback timed out — could not bind callback port. " + "Complete the authorization in a browser first, then retry." + ) + + server_thread = threading.Thread(target=server.handle_request, daemon=True) + server_thread.start() + + timeout = 300.0 + poll_interval = 0.5 + elapsed = 0.0 + try: + while elapsed < timeout: + if result["auth_code"] is not None or result["error"] is not None: + break + await asyncio.sleep(poll_interval) + elapsed += poll_interval + finally: + server.server_close() + + if result["error"]: + raise RuntimeError(f"OAuth authorization failed: {result['error']}") + if result["auth_code"] is None: + raise OAuthNonInteractiveError( + "OAuth callback timed out — no authorization code received. " + "Ensure you completed the browser authorization flow." + ) + + return result["auth_code"], result["state"] + + +# --------------------------------------------------------------------------- +# Public API +# --------------------------------------------------------------------------- + + +def remove_oauth_tokens(server_name: str) -> None: + """Delete stored OAuth tokens and client info for a server.""" + storage = HermesTokenStorage(server_name) + storage.remove() + logger.info("OAuth tokens removed for '%s'", server_name) + + +def build_oauth_auth( + server_name: str, + server_url: str, + oauth_config: dict | None = None, +) -> "OAuthClientProvider | None": + """Build an ``httpx.Auth``-compatible OAuth handler for an MCP server. + + Called from ``mcp_tool.py`` when a server has ``auth: oauth`` in config. + + Args: + server_name: Server key in mcp_servers config (used for storage). + server_url: MCP server endpoint URL. + oauth_config: Optional dict from the ``oauth:`` block in config.yaml. + + Returns: + An ``OAuthClientProvider`` instance, or None if the MCP SDK lacks + OAuth support. + """ + if not _OAUTH_AVAILABLE: + logger.warning( + "MCP OAuth requested for '%s' but SDK auth types are not available. " + "Install with: pip install 'mcp>=1.10.0'", + server_name, + ) + return None + + global _oauth_port + + cfg = oauth_config or {} + + # --- Storage --- + storage = HermesTokenStorage(server_name) + + # --- Non-interactive warning --- + if not _is_interactive() and not storage.has_cached_tokens(): + logger.warning( + "MCP OAuth for '%s': non-interactive environment and no cached tokens found. " + "The OAuth flow requires browser authorization. Run interactively first " + "to complete the initial authorization, then cached tokens will be reused.", + server_name, + ) + + # --- Pick callback port --- + redirect_port = int(cfg.get("redirect_port", 0)) + if redirect_port == 0: + redirect_port = _find_free_port() + _oauth_port = redirect_port + + # --- Client metadata --- + client_name = cfg.get("client_name", "Hermes Agent") + scope = cfg.get("scope") + redirect_uri = f"http://127.0.0.1:{redirect_port}/callback" + + metadata_kwargs: dict[str, Any] = { + "client_name": client_name, + "redirect_uris": [AnyUrl(redirect_uri)], + "grant_types": ["authorization_code", "refresh_token"], + "response_types": ["code"], + "token_endpoint_auth_method": "none", + } + if scope: + metadata_kwargs["scope"] = scope + + client_secret = cfg.get("client_secret") + if client_secret: + metadata_kwargs["token_endpoint_auth_method"] = "client_secret_post" + + client_metadata = OAuthClientMetadata.model_validate(metadata_kwargs) + + # --- Pre-registered client --- + client_id = cfg.get("client_id") + if client_id: + info_dict: dict[str, Any] = { + "client_id": client_id, + "redirect_uris": [redirect_uri], + "grant_types": client_metadata.grant_types, + "response_types": client_metadata.response_types, + "token_endpoint_auth_method": client_metadata.token_endpoint_auth_method, + } + if client_secret: + info_dict["client_secret"] = client_secret + if client_name: + info_dict["client_name"] = client_name + if scope: + info_dict["scope"] = scope + + client_info = OAuthClientInformationFull.model_validate(info_dict) + _write_json(storage._client_info_path(), client_info.model_dump(exclude_none=True)) + logger.debug("Pre-registered client_id=%s for '%s'", client_id, server_name) + + # --- Base URL for discovery --- + parsed = urlparse(server_url) + base_url = f"{parsed.scheme}://{parsed.netloc}" + + # --- Build provider --- + provider = OAuthClientProvider( + server_url=base_url, + client_metadata=client_metadata, + storage=storage, + redirect_handler=_redirect_handler, + callback_handler=_wait_for_callback, + timeout=float(cfg.get("timeout", 300)), + ) + + return provider diff --git a/mindcli/_vendor/tools/mcp_tool.py b/mindcli/_vendor/tools/mcp_tool.py new file mode 100644 index 0000000..2356830 --- /dev/null +++ b/mindcli/_vendor/tools/mcp_tool.py @@ -0,0 +1,2264 @@ +#!/usr/bin/env python3 +""" +MCP (Model Context Protocol) Client Support + +Connects to external MCP servers via stdio or HTTP/StreamableHTTP transport, +discovers their tools, and registers them into the hermes-agent tool registry +so the agent can call them like any built-in tool. + +Configuration is read from ~/.hermes/config.yaml under the ``mcp_servers`` key. +The ``mcp`` Python package is optional -- if not installed, this module is a +no-op and logs a debug message. + +Example config:: + + mcp_servers: + filesystem: + command: "npx" + args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] + env: {} + timeout: 120 # per-tool-call timeout in seconds (default: 120) + connect_timeout: 60 # initial connection timeout (default: 60) + github: + command: "npx" + args: ["-y", "@modelcontextprotocol/server-github"] + env: + GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..." + remote_api: + url: "https://my-mcp-server.example.com/mcp" + headers: + Authorization: "Bearer sk-..." + timeout: 180 + analysis: + command: "npx" + args: ["-y", "analysis-server"] + sampling: # server-initiated LLM requests + enabled: true # default: true + model: "gemini-3-flash" # override model (optional) + max_tokens_cap: 4096 # max tokens per request + timeout: 30 # LLM call timeout (seconds) + max_rpm: 10 # max requests per minute + allowed_models: [] # model whitelist (empty = all) + max_tool_rounds: 5 # tool loop limit (0 = disable) + log_level: "info" # audit verbosity + +Features: + - Stdio transport (command + args) and HTTP/StreamableHTTP transport (url) + - Automatic reconnection with exponential backoff (up to 5 retries) + - Environment variable filtering for stdio subprocesses (security) + - Credential stripping in error messages returned to the LLM + - Configurable per-server timeouts for tool calls and connections + - Thread-safe architecture with dedicated background event loop + - Sampling support: MCP servers can request LLM completions via + sampling/createMessage (text and tool-use responses) + +Architecture: + A dedicated background event loop (_mcp_loop) runs in a daemon thread. + Each MCP server runs as a long-lived asyncio Task on this loop, keeping + its transport context alive. Tool call coroutines are scheduled onto the + loop via ``run_coroutine_threadsafe()``. + + On shutdown, each server Task is signalled to exit its ``async with`` + block, ensuring the anyio cancel-scope cleanup happens in the *same* + Task that opened the connection (required by anyio). + +Thread safety: + _servers and _mcp_loop/_mcp_thread are accessed from both the MCP + background thread and caller threads. All mutations are protected by + _lock so the code is safe regardless of GIL presence (e.g. Python 3.13+ + free-threading). +""" + +import asyncio +import concurrent.futures +import inspect +import json +import logging +import math +import os +import re +import shutil +import threading +import time +from typing import Any, Dict, List, Optional + +logger = logging.getLogger(__name__) + +# --------------------------------------------------------------------------- +# Graceful import -- MCP SDK is an optional dependency +# --------------------------------------------------------------------------- + +_MCP_AVAILABLE = False +_MCP_HTTP_AVAILABLE = False +_MCP_SAMPLING_TYPES = False +_MCP_NOTIFICATION_TYPES = False +_MCP_MESSAGE_HANDLER_SUPPORTED = False +try: + from mcp import ClientSession, StdioServerParameters + from mcp.client.stdio import stdio_client + _MCP_AVAILABLE = True + try: + from mcp.client.streamable_http import streamablehttp_client + _MCP_HTTP_AVAILABLE = True + except ImportError: + _MCP_HTTP_AVAILABLE = False + # Prefer the non-deprecated API (mcp >= 1.24.0); fall back to the + # deprecated wrapper for older SDK versions. + try: + from mcp.client.streamable_http import streamable_http_client + _MCP_NEW_HTTP = True + except ImportError: + _MCP_NEW_HTTP = False + # Sampling types -- separated so older SDK versions don't break MCP support + try: + from mcp.types import ( + CreateMessageResult, + CreateMessageResultWithTools, + ErrorData, + SamplingCapability, + SamplingToolsCapability, + TextContent, + ToolUseContent, + ) + _MCP_SAMPLING_TYPES = True + except ImportError: + logger.debug("MCP sampling types not available -- sampling disabled") + # Notification types for dynamic tool discovery (tools/list_changed) + try: + from mcp.types import ( + ServerNotification, + ToolListChangedNotification, + PromptListChangedNotification, + ResourceListChangedNotification, + ) + _MCP_NOTIFICATION_TYPES = True + except ImportError: + logger.debug("MCP notification types not available -- dynamic tool discovery disabled") +except ImportError: + logger.debug("mcp package not installed -- MCP tool support disabled") + + +def _check_message_handler_support() -> bool: + """Check if ClientSession accepts ``message_handler`` kwarg. + + Inspects the constructor signature for backward compatibility with older + MCP SDK versions that don't support notification handlers. + """ + if not _MCP_AVAILABLE: + return False + try: + return "message_handler" in inspect.signature(ClientSession).parameters + except (TypeError, ValueError): + return False + + +_MCP_MESSAGE_HANDLER_SUPPORTED = _check_message_handler_support() +if _MCP_AVAILABLE and not _MCP_MESSAGE_HANDLER_SUPPORTED: + logger.debug("MCP SDK does not support message_handler -- dynamic tool discovery disabled") + +# --------------------------------------------------------------------------- +# Constants +# --------------------------------------------------------------------------- + +_DEFAULT_TOOL_TIMEOUT = 120 # seconds for tool calls +_DEFAULT_CONNECT_TIMEOUT = 60 # seconds for initial connection per server +_MAX_RECONNECT_RETRIES = 5 +_MAX_INITIAL_CONNECT_RETRIES = 3 # retries for the very first connection attempt +_MAX_BACKOFF_SECONDS = 60 + +# Environment variables that are safe to pass to stdio subprocesses +_SAFE_ENV_KEYS = frozenset({ + "PATH", "HOME", "USER", "LANG", "LC_ALL", "TERM", "SHELL", "TMPDIR", +}) + +# Regex for credential patterns to strip from error messages +_CREDENTIAL_PATTERN = re.compile( + r"(?:" + r"ghp_[A-Za-z0-9_]{1,255}" # GitHub PAT + r"|sk-[A-Za-z0-9_]{1,255}" # OpenAI-style key + r"|Bearer\s+\S+" # Bearer token + r"|token=[^\s&,;\"']{1,255}" # token=... + r"|key=[^\s&,;\"']{1,255}" # key=... + r"|API_KEY=[^\s&,;\"']{1,255}" # API_KEY=... + r"|password=[^\s&,;\"']{1,255}" # password=... + r"|secret=[^\s&,;\"']{1,255}" # secret=... + r")", + re.IGNORECASE, +) + + +# --------------------------------------------------------------------------- +# Security helpers +# --------------------------------------------------------------------------- + +def _build_safe_env(user_env: Optional[dict]) -> dict: + """Build a filtered environment dict for stdio subprocesses. + + Only passes through safe baseline variables (PATH, HOME, etc.) and XDG_* + variables from the current process environment, plus any variables + explicitly specified by the user in the server config. + + This prevents accidentally leaking secrets like API keys, tokens, or + credentials to MCP server subprocesses. + """ + env = {} + for key, value in os.environ.items(): + if key in _SAFE_ENV_KEYS or key.startswith("XDG_"): + env[key] = value + if user_env: + env.update(user_env) + return env + + +def _sanitize_error(text: str) -> str: + """Strip credential-like patterns from error text before returning to LLM. + + Replaces tokens, keys, and other secrets with [REDACTED] to prevent + accidental credential exposure in tool error responses. + """ + return _CREDENTIAL_PATTERN.sub("[REDACTED]", text) + + +def _prepend_path(env: dict, directory: str) -> dict: + """Prepend *directory* to env PATH if it is not already present.""" + updated = dict(env or {}) + if not directory: + return updated + + existing = updated.get("PATH", "") + parts = [part for part in existing.split(os.pathsep) if part] + if directory not in parts: + parts = [directory, *parts] + updated["PATH"] = os.pathsep.join(parts) if parts else directory + return updated + + +def _resolve_stdio_command(command: str, env: dict) -> tuple[str, dict]: + """Resolve a stdio MCP command against the exact subprocess environment. + + This primarily exists to make bare ``npx``/``npm``/``node`` commands work + reliably even when MCP subprocesses run under a filtered PATH. + """ + resolved_command = os.path.expanduser(str(command).strip()) + resolved_env = dict(env or {}) + + if os.sep not in resolved_command: + path_arg = resolved_env["PATH"] if "PATH" in resolved_env else None + which_hit = shutil.which(resolved_command, path=path_arg) + if which_hit: + resolved_command = which_hit + elif resolved_command in {"npx", "npm", "node"}: + hermes_home = os.path.expanduser( + os.getenv( + "HERMES_HOME", os.path.join(os.path.expanduser("~"), ".hermes") + ) + ) + candidates = [ + os.path.join(hermes_home, "node", "bin", resolved_command), + os.path.join(os.path.expanduser("~"), ".local", "bin", resolved_command), + ] + for candidate in candidates: + if os.path.isfile(candidate) and os.access(candidate, os.X_OK): + resolved_command = candidate + break + + command_dir = os.path.dirname(resolved_command) + if command_dir: + resolved_env = _prepend_path(resolved_env, command_dir) + + return resolved_command, resolved_env + + +def _format_connect_error(exc: BaseException) -> str: + """Render nested MCP connection errors into an actionable short message.""" + + def _find_missing(current: BaseException) -> Optional[str]: + nested = getattr(current, "exceptions", None) + if nested: + for child in nested: + missing = _find_missing(child) + if missing: + return missing + return None + if isinstance(current, FileNotFoundError): + if getattr(current, "filename", None): + return str(current.filename) + match = re.search(r"No such file or directory: '([^']+)'", str(current)) + if match: + return match.group(1) + for attr in ("__cause__", "__context__"): + nested_exc = getattr(current, attr, None) + if isinstance(nested_exc, BaseException): + missing = _find_missing(nested_exc) + if missing: + return missing + return None + + def _flatten_messages(current: BaseException) -> List[str]: + nested = getattr(current, "exceptions", None) + if nested: + flattened: List[str] = [] + for child in nested: + flattened.extend(_flatten_messages(child)) + return flattened + messages = [] + text = str(current).strip() + if text: + messages.append(text) + for attr in ("__cause__", "__context__"): + nested_exc = getattr(current, attr, None) + if isinstance(nested_exc, BaseException): + messages.extend(_flatten_messages(nested_exc)) + return messages or [current.__class__.__name__] + + missing = _find_missing(exc) + if missing: + message = f"missing executable '{missing}'" + if os.path.basename(missing) in {"npx", "npm", "node"}: + message += ( + " (ensure Node.js is installed and PATH includes its bin directory, " + "or set mcp_servers..command to an absolute path and include " + "that directory in mcp_servers..env.PATH)" + ) + return _sanitize_error(message) + + deduped: List[str] = [] + for item in _flatten_messages(exc): + if item not in deduped: + deduped.append(item) + return _sanitize_error("; ".join(deduped[:3])) + + +# --------------------------------------------------------------------------- +# Sampling -- server-initiated LLM requests (MCP sampling/createMessage) +# --------------------------------------------------------------------------- + +def _safe_numeric(value, default, coerce=int, minimum=1): + """Coerce a config value to a numeric type, returning *default* on failure. + + Handles string values from YAML (e.g. ``"10"`` instead of ``10``), + non-finite floats, and values below *minimum*. + """ + try: + result = coerce(value) + if isinstance(result, float) and not math.isfinite(result): + return default + return max(result, minimum) + except (TypeError, ValueError, OverflowError): + return default + + +class SamplingHandler: + """Handles sampling/createMessage requests for a single MCP server. + + Each MCPServerTask that has sampling enabled creates one SamplingHandler. + The handler is callable and passed directly to ``ClientSession`` as + the ``sampling_callback``. All state (rate-limit timestamps, metrics, + tool-loop counters) lives on the instance -- no module-level globals. + + The callback is async and runs on the MCP background event loop. The + sync LLM call is offloaded to a thread via ``asyncio.to_thread()`` so + it doesn't block the event loop. + """ + + _STOP_REASON_MAP = {"stop": "endTurn", "length": "maxTokens", "tool_calls": "toolUse"} + + def __init__(self, server_name: str, config: dict): + self.server_name = server_name + self.max_rpm = _safe_numeric(config.get("max_rpm", 10), 10, int) + self.timeout = _safe_numeric(config.get("timeout", 30), 30, float) + self.max_tokens_cap = _safe_numeric(config.get("max_tokens_cap", 4096), 4096, int) + self.max_tool_rounds = _safe_numeric( + config.get("max_tool_rounds", 5), 5, int, minimum=0, + ) + self.model_override = config.get("model") + self.allowed_models = config.get("allowed_models", []) + + _log_levels = {"debug": logging.DEBUG, "info": logging.INFO, "warning": logging.WARNING} + self.audit_level = _log_levels.get( + str(config.get("log_level", "info")).lower(), logging.INFO, + ) + + # Per-instance state + self._rate_timestamps: List[float] = [] + self._tool_loop_count = 0 + self.metrics = {"requests": 0, "errors": 0, "tokens_used": 0, "tool_use_count": 0} + + # -- Rate limiting ------------------------------------------------------- + + def _check_rate_limit(self) -> bool: + """Sliding-window rate limiter. Returns True if request is allowed.""" + now = time.time() + window = now - 60 + self._rate_timestamps[:] = [t for t in self._rate_timestamps if t > window] + if len(self._rate_timestamps) >= self.max_rpm: + return False + self._rate_timestamps.append(now) + return True + + # -- Model resolution ---------------------------------------------------- + + def _resolve_model(self, preferences) -> Optional[str]: + """Config override > server hint > None (use default).""" + if self.model_override: + return self.model_override + if preferences and hasattr(preferences, "hints") and preferences.hints: + for hint in preferences.hints: + if hasattr(hint, "name") and hint.name: + return hint.name + return None + + # -- Message conversion -------------------------------------------------- + + @staticmethod + def _extract_tool_result_text(block) -> str: + """Extract text from a ToolResultContent block.""" + if not hasattr(block, "content") or block.content is None: + return "" + items = block.content if isinstance(block.content, list) else [block.content] + return "\n".join(item.text for item in items if hasattr(item, "text")) + + def _convert_messages(self, params) -> List[dict]: + """Convert MCP SamplingMessages to OpenAI format. + + Uses ``msg.content_as_list`` (SDK helper) so single-block and + list-of-blocks are handled uniformly. Dispatches per block type + with ``isinstance`` on real SDK types when available, falling back + to duck-typing via ``hasattr`` for compatibility. + """ + messages: List[dict] = [] + for msg in params.messages: + blocks = msg.content_as_list if hasattr(msg, "content_as_list") else ( + msg.content if isinstance(msg.content, list) else [msg.content] + ) + + # Separate blocks by kind + tool_results = [b for b in blocks if hasattr(b, "toolUseId")] + tool_uses = [b for b in blocks if hasattr(b, "name") and hasattr(b, "input") and not hasattr(b, "toolUseId")] + content_blocks = [b for b in blocks if not hasattr(b, "toolUseId") and not (hasattr(b, "name") and hasattr(b, "input"))] + + # Emit tool result messages (role: tool) + for tr in tool_results: + messages.append({ + "role": "tool", + "tool_call_id": tr.toolUseId, + "content": self._extract_tool_result_text(tr), + }) + + # Emit assistant tool_calls message + if tool_uses: + tc_list = [] + for tu in tool_uses: + tc_list.append({ + "id": getattr(tu, "id", f"call_{len(tc_list)}"), + "type": "function", + "function": { + "name": tu.name, + "arguments": json.dumps(tu.input) if isinstance(tu.input, dict) else str(tu.input), + }, + }) + msg_dict: dict = {"role": msg.role, "tool_calls": tc_list} + # Include any accompanying text + text_parts = [b.text for b in content_blocks if hasattr(b, "text")] + if text_parts: + msg_dict["content"] = "\n".join(text_parts) + messages.append(msg_dict) + elif content_blocks: + # Pure text/image content + if len(content_blocks) == 1 and hasattr(content_blocks[0], "text"): + messages.append({"role": msg.role, "content": content_blocks[0].text}) + else: + parts = [] + for block in content_blocks: + if hasattr(block, "text"): + parts.append({"type": "text", "text": block.text}) + elif hasattr(block, "data") and hasattr(block, "mimeType"): + parts.append({ + "type": "image_url", + "image_url": {"url": f"data:{block.mimeType};base64,{block.data}"}, + }) + else: + logger.warning( + "Unsupported sampling content block type: %s (skipped)", + type(block).__name__, + ) + if parts: + messages.append({"role": msg.role, "content": parts}) + + return messages + + # -- Error helper -------------------------------------------------------- + + @staticmethod + def _error(message: str, code: int = -1): + """Return ErrorData (MCP spec) or raise as fallback.""" + if _MCP_SAMPLING_TYPES: + return ErrorData(code=code, message=message) + raise Exception(message) + + # -- Response building --------------------------------------------------- + + def _build_tool_use_result(self, choice, response): + """Build a CreateMessageResultWithTools from an LLM tool_calls response.""" + self.metrics["tool_use_count"] += 1 + + # Tool loop governance + if self.max_tool_rounds == 0: + self._tool_loop_count = 0 + return self._error( + f"Tool loops disabled for server '{self.server_name}' (max_tool_rounds=0)" + ) + + self._tool_loop_count += 1 + if self._tool_loop_count > self.max_tool_rounds: + self._tool_loop_count = 0 + return self._error( + f"Tool loop limit exceeded for server '{self.server_name}' " + f"(max {self.max_tool_rounds} rounds)" + ) + + content_blocks = [] + for tc in choice.message.tool_calls: + args = tc.function.arguments + if isinstance(args, str): + try: + parsed = json.loads(args) + except (json.JSONDecodeError, ValueError): + logger.warning( + "MCP server '%s': malformed tool_calls arguments " + "from LLM (wrapping as raw): %.100s", + self.server_name, args, + ) + parsed = {"_raw": args} + else: + parsed = args if isinstance(args, dict) else {"_raw": str(args)} + + content_blocks.append(ToolUseContent( + type="tool_use", + id=tc.id, + name=tc.function.name, + input=parsed, + )) + + logger.log( + self.audit_level, + "MCP server '%s' sampling response: model=%s, tokens=%s, tool_calls=%d", + self.server_name, response.model, + getattr(getattr(response, "usage", None), "total_tokens", "?"), + len(content_blocks), + ) + + return CreateMessageResultWithTools( + role="assistant", + content=content_blocks, + model=response.model, + stopReason="toolUse", + ) + + def _build_text_result(self, choice, response): + """Build a CreateMessageResult from a normal text response.""" + self._tool_loop_count = 0 # reset on text response + response_text = choice.message.content or "" + + logger.log( + self.audit_level, + "MCP server '%s' sampling response: model=%s, tokens=%s", + self.server_name, response.model, + getattr(getattr(response, "usage", None), "total_tokens", "?"), + ) + + return CreateMessageResult( + role="assistant", + content=TextContent(type="text", text=_sanitize_error(response_text)), + model=response.model, + stopReason=self._STOP_REASON_MAP.get(choice.finish_reason, "endTurn"), + ) + + # -- Session kwargs helper ----------------------------------------------- + + def session_kwargs(self) -> dict: + """Return kwargs to pass to ClientSession for sampling support.""" + return { + "sampling_callback": self, + "sampling_capabilities": SamplingCapability( + tools=SamplingToolsCapability(), + ), + } + + # -- Main callback ------------------------------------------------------- + + async def __call__(self, context, params): + """Sampling callback invoked by the MCP SDK. + + Conforms to ``SamplingFnT`` protocol. Returns + ``CreateMessageResult``, ``CreateMessageResultWithTools``, or + ``ErrorData``. + """ + # Rate limit + if not self._check_rate_limit(): + logger.warning( + "MCP server '%s' sampling rate limit exceeded (%d/min)", + self.server_name, self.max_rpm, + ) + self.metrics["errors"] += 1 + return self._error( + f"Sampling rate limit exceeded for server '{self.server_name}' " + f"({self.max_rpm} requests/minute)" + ) + + # Resolve model + model = self._resolve_model(getattr(params, "modelPreferences", None)) + + # Get auxiliary LLM client via centralized router + from agent.auxiliary_client import call_llm + + # Model whitelist check (we need to resolve model before calling) + resolved_model = model or self.model_override or "" + + if self.allowed_models and resolved_model and resolved_model not in self.allowed_models: + logger.warning( + "MCP server '%s' requested model '%s' not in allowed_models", + self.server_name, resolved_model, + ) + self.metrics["errors"] += 1 + return self._error( + f"Model '{resolved_model}' not allowed for server " + f"'{self.server_name}'. Allowed: {', '.join(self.allowed_models)}" + ) + + # Convert messages + messages = self._convert_messages(params) + if hasattr(params, "systemPrompt") and params.systemPrompt: + messages.insert(0, {"role": "system", "content": params.systemPrompt}) + + # Build LLM call kwargs + max_tokens = min(params.maxTokens, self.max_tokens_cap) + call_temperature = None + if hasattr(params, "temperature") and params.temperature is not None: + call_temperature = params.temperature + + # Forward server-provided tools + call_tools = None + server_tools = getattr(params, "tools", None) + if server_tools: + call_tools = [ + { + "type": "function", + "function": { + "name": getattr(t, "name", ""), + "description": getattr(t, "description", "") or "", + "parameters": _normalize_mcp_input_schema( + getattr(t, "inputSchema", None) + ), + }, + } + for t in server_tools + ] + + logger.log( + self.audit_level, + "MCP server '%s' sampling request: model=%s, max_tokens=%d, messages=%d", + self.server_name, resolved_model, max_tokens, len(messages), + ) + + # Offload sync LLM call to thread (non-blocking) + def _sync_call(): + return call_llm( + task="mcp", + model=resolved_model or None, + messages=messages, + temperature=call_temperature, + max_tokens=max_tokens, + tools=call_tools, + timeout=self.timeout, + ) + + try: + response = await asyncio.wait_for( + asyncio.to_thread(_sync_call), timeout=self.timeout, + ) + except asyncio.TimeoutError: + self.metrics["errors"] += 1 + return self._error( + f"Sampling LLM call timed out after {self.timeout}s " + f"for server '{self.server_name}'" + ) + except Exception as exc: + self.metrics["errors"] += 1 + return self._error( + f"Sampling LLM call failed: {_sanitize_error(str(exc))}" + ) + + # Guard against empty choices (content filtering, provider errors) + if not getattr(response, "choices", None): + self.metrics["errors"] += 1 + return self._error( + f"LLM returned empty response (no choices) for server " + f"'{self.server_name}'" + ) + + # Track metrics + choice = response.choices[0] + self.metrics["requests"] += 1 + total_tokens = getattr(getattr(response, "usage", None), "total_tokens", 0) + if isinstance(total_tokens, int): + self.metrics["tokens_used"] += total_tokens + + # Dispatch based on response type + if ( + choice.finish_reason == "tool_calls" + and hasattr(choice.message, "tool_calls") + and choice.message.tool_calls + ): + return self._build_tool_use_result(choice, response) + + return self._build_text_result(choice, response) + + +# --------------------------------------------------------------------------- +# Server task -- each MCP server lives in one long-lived asyncio Task +# --------------------------------------------------------------------------- + +class MCPServerTask: + """Manages a single MCP server connection in a dedicated asyncio Task. + + The entire connection lifecycle (connect, discover, serve, disconnect) + runs inside one asyncio Task so that anyio cancel-scopes created by + the transport client are entered and exited in the same Task context. + + Supports both stdio and HTTP/StreamableHTTP transports. + """ + + __slots__ = ( + "name", "session", "tool_timeout", + "_task", "_ready", "_shutdown_event", "_tools", "_error", "_config", + "_sampling", "_registered_tool_names", "_auth_type", "_refresh_lock", + ) + + def __init__(self, name: str): + self.name = name + self.session: Optional[Any] = None + self.tool_timeout: float = _DEFAULT_TOOL_TIMEOUT + self._task: Optional[asyncio.Task] = None + self._ready = asyncio.Event() + self._shutdown_event = asyncio.Event() + self._tools: list = [] + self._error: Optional[Exception] = None + self._config: dict = {} + self._sampling: Optional[SamplingHandler] = None + self._registered_tool_names: list[str] = [] + self._auth_type: str = "" + self._refresh_lock = asyncio.Lock() + + def _is_http(self) -> bool: + """Check if this server uses HTTP transport.""" + return "url" in self._config + + # ----- Dynamic tool discovery (notifications/tools/list_changed) ----- + + def _make_message_handler(self): + """Build a ``message_handler`` callback for ``ClientSession``. + + Dispatches on notification type. Only ``ToolListChangedNotification`` + triggers a refresh; prompt and resource change notifications are + logged as stubs for future work. + """ + async def _handler(message): + try: + if isinstance(message, Exception): + logger.debug("MCP message handler (%s): exception: %s", self.name, message) + return + if _MCP_NOTIFICATION_TYPES and isinstance(message, ServerNotification): + match message.root: + case ToolListChangedNotification(): + logger.info( + "MCP server '%s': received tools/list_changed notification", + self.name, + ) + await self._refresh_tools() + case PromptListChangedNotification(): + logger.debug("MCP server '%s': prompts/list_changed (ignored)", self.name) + case ResourceListChangedNotification(): + logger.debug("MCP server '%s': resources/list_changed (ignored)", self.name) + case _: + pass + except Exception: + logger.exception("Error in MCP message handler for '%s'", self.name) + return _handler + + async def _refresh_tools(self): + """Re-fetch tools from the server and update the registry. + + Called when the server sends ``notifications/tools/list_changed``. + The lock prevents overlapping refreshes from rapid-fire notifications. + After the initial ``await`` (list_tools), all mutations are synchronous + — atomic from the event loop's perspective. + """ + from tools.registry import registry, tool_error + from toolsets import TOOLSETS + + async with self._refresh_lock: + # 1. Fetch current tool list from server + tools_result = await self.session.list_tools() + new_mcp_tools = tools_result.tools if hasattr(tools_result, "tools") else [] + + # 2. Remove old tools from hermes-* umbrella toolsets + for ts_name, ts in TOOLSETS.items(): + if ts_name.startswith("hermes-"): + ts["tools"] = [t for t in ts["tools"] if t not in self._registered_tool_names] + + # 3. Deregister old tools from the central registry + for prefixed_name in self._registered_tool_names: + registry.deregister(prefixed_name) + + # 4. Re-register with fresh tool list + self._tools = new_mcp_tools + self._registered_tool_names = _register_server_tools( + self.name, self, self._config + ) + + logger.info( + "MCP server '%s': dynamically refreshed %d tool(s)", + self.name, len(self._registered_tool_names), + ) + + async def _run_stdio(self, config: dict): + """Run the server using stdio transport.""" + command = config.get("command") + args = config.get("args", []) + user_env = config.get("env") + + if not command: + raise ValueError( + f"MCP server '{self.name}' has no 'command' in config" + ) + + safe_env = _build_safe_env(user_env) + command, safe_env = _resolve_stdio_command(command, safe_env) + + # Check package against OSV malware database before spawning + from tools.osv_check import check_package_for_malware + malware_error = check_package_for_malware(command, args) + if malware_error: + raise ValueError( + f"MCP server '{self.name}': {malware_error}" + ) + + server_params = StdioServerParameters( + command=command, + args=args, + env=safe_env if safe_env else None, + ) + + sampling_kwargs = self._sampling.session_kwargs() if self._sampling else {} + if _MCP_NOTIFICATION_TYPES and _MCP_MESSAGE_HANDLER_SUPPORTED: + sampling_kwargs["message_handler"] = self._make_message_handler() + + # Snapshot child PIDs before spawning so we can track the new one. + pids_before = _snapshot_child_pids() + async with stdio_client(server_params) as (read_stream, write_stream): + # Capture the newly spawned subprocess PID for force-kill cleanup. + new_pids = _snapshot_child_pids() - pids_before + if new_pids: + with _lock: + _stdio_pids.update(new_pids) + async with ClientSession(read_stream, write_stream, **sampling_kwargs) as session: + await session.initialize() + self.session = session + await self._discover_tools() + self._ready.set() + await self._shutdown_event.wait() + # Context exited cleanly — subprocess was terminated by the SDK. + if new_pids: + with _lock: + _stdio_pids.difference_update(new_pids) + + async def _run_http(self, config: dict): + """Run the server using HTTP/StreamableHTTP transport.""" + if not _MCP_HTTP_AVAILABLE: + raise ImportError( + f"MCP server '{self.name}' requires HTTP transport but " + "mcp.client.streamable_http is not available. " + "Upgrade the mcp package to get HTTP support." + ) + + url = config["url"] + headers = dict(config.get("headers") or {}) + connect_timeout = config.get("connect_timeout", _DEFAULT_CONNECT_TIMEOUT) + + # OAuth 2.1 PKCE: build httpx.Auth handler using the MCP SDK. + # If OAuth setup fails (e.g. non-interactive environment without + # cached tokens), re-raise so this server is reported as failed + # without blocking other MCP servers from connecting. + _oauth_auth = None + if self._auth_type == "oauth": + try: + from tools.mcp_oauth import build_oauth_auth + _oauth_auth = build_oauth_auth( + self.name, url, config.get("oauth") + ) + except Exception as exc: + logger.warning("MCP OAuth setup failed for '%s': %s", self.name, exc) + raise + + sampling_kwargs = self._sampling.session_kwargs() if self._sampling else {} + if _MCP_NOTIFICATION_TYPES and _MCP_MESSAGE_HANDLER_SUPPORTED: + sampling_kwargs["message_handler"] = self._make_message_handler() + + if _MCP_NEW_HTTP: + # New API (mcp >= 1.24.0): build an explicit httpx.AsyncClient + # matching the SDK's own create_mcp_http_client defaults. + import httpx + + client_kwargs: dict = { + "follow_redirects": True, + "timeout": httpx.Timeout(float(connect_timeout), read=300.0), + } + if headers: + client_kwargs["headers"] = headers + if _oauth_auth is not None: + client_kwargs["auth"] = _oauth_auth + + # Caller owns the client lifecycle — the SDK skips cleanup when + # http_client is provided, so we wrap in async-with. + async with httpx.AsyncClient(**client_kwargs) as http_client: + async with streamable_http_client(url, http_client=http_client) as ( + read_stream, write_stream, _get_session_id, + ): + async with ClientSession(read_stream, write_stream, **sampling_kwargs) as session: + await session.initialize() + self.session = session + await self._discover_tools() + self._ready.set() + await self._shutdown_event.wait() + else: + # Deprecated API (mcp < 1.24.0): manages httpx client internally. + _http_kwargs: dict = { + "headers": headers, + "timeout": float(connect_timeout), + } + if _oauth_auth is not None: + _http_kwargs["auth"] = _oauth_auth + async with streamablehttp_client(url, **_http_kwargs) as ( + read_stream, write_stream, _get_session_id, + ): + async with ClientSession(read_stream, write_stream, **sampling_kwargs) as session: + await session.initialize() + self.session = session + await self._discover_tools() + self._ready.set() + await self._shutdown_event.wait() + + async def _discover_tools(self): + """Discover tools from the connected session.""" + if self.session is None: + return + tools_result = await self.session.list_tools() + self._tools = ( + tools_result.tools + if hasattr(tools_result, "tools") + else [] + ) + + async def run(self, config: dict): + """Long-lived coroutine: connect, discover tools, wait, disconnect. + + Includes automatic reconnection with exponential backoff if the + connection drops unexpectedly (unless shutdown was requested). + """ + self._config = config + self.tool_timeout = config.get("timeout", _DEFAULT_TOOL_TIMEOUT) + self._auth_type = (config.get("auth") or "").lower().strip() + + # Set up sampling handler if enabled and SDK types are available + sampling_config = config.get("sampling", {}) + if sampling_config.get("enabled", True) and _MCP_SAMPLING_TYPES: + self._sampling = SamplingHandler(self.name, sampling_config) + else: + self._sampling = None + + # Validate: warn if both url and command are present + if "url" in config and "command" in config: + logger.warning( + "MCP server '%s' has both 'url' and 'command' in config. " + "Using HTTP transport ('url'). Remove 'command' to silence " + "this warning.", + self.name, + ) + retries = 0 + initial_retries = 0 + backoff = 1.0 + + while True: + try: + if self._is_http(): + await self._run_http(config) + else: + await self._run_stdio(config) + # Normal exit (shutdown requested) -- break out + break + except Exception as exc: + self.session = None + + # If this is the first connection attempt, retry with backoff + # before giving up. A transient DNS/network blip at startup + # should not permanently kill the server. + # (Ported from Kilo Code's MCP resilience fix.) + if not self._ready.is_set(): + initial_retries += 1 + if initial_retries > _MAX_INITIAL_CONNECT_RETRIES: + logger.warning( + "MCP server '%s' failed initial connection after " + "%d attempts, giving up: %s", + self.name, _MAX_INITIAL_CONNECT_RETRIES, exc, + ) + self._error = exc + self._ready.set() + return + + logger.warning( + "MCP server '%s' initial connection failed " + "(attempt %d/%d), retrying in %.0fs: %s", + self.name, initial_retries, + _MAX_INITIAL_CONNECT_RETRIES, backoff, exc, + ) + await asyncio.sleep(backoff) + backoff = min(backoff * 2, _MAX_BACKOFF_SECONDS) + + # Check if shutdown was requested during the sleep + if self._shutdown_event.is_set(): + self._error = exc + self._ready.set() + return + continue + + # If shutdown was requested, don't reconnect + if self._shutdown_event.is_set(): + logger.debug( + "MCP server '%s' disconnected during shutdown: %s", + self.name, exc, + ) + return + + retries += 1 + if retries > _MAX_RECONNECT_RETRIES: + logger.warning( + "MCP server '%s' failed after %d reconnection attempts, " + "giving up: %s", + self.name, _MAX_RECONNECT_RETRIES, exc, + ) + return + + logger.warning( + "MCP server '%s' connection lost (attempt %d/%d), " + "reconnecting in %.0fs: %s", + self.name, retries, _MAX_RECONNECT_RETRIES, + backoff, exc, + ) + await asyncio.sleep(backoff) + backoff = min(backoff * 2, _MAX_BACKOFF_SECONDS) + + # Check again after sleeping + if self._shutdown_event.is_set(): + return + finally: + self.session = None + + async def start(self, config: dict): + """Create the background Task and wait until ready (or failed).""" + self._task = asyncio.ensure_future(self.run(config)) + await self._ready.wait() + if self._error: + raise self._error + + async def shutdown(self): + """Signal the Task to exit and wait for clean resource teardown.""" + self._shutdown_event.set() + if self._task and not self._task.done(): + try: + await asyncio.wait_for(self._task, timeout=10) + except asyncio.TimeoutError: + logger.warning( + "MCP server '%s' shutdown timed out, cancelling task", + self.name, + ) + self._task.cancel() + try: + await self._task + except asyncio.CancelledError: + pass + self.session = None + + +# --------------------------------------------------------------------------- +# Module-level state +# --------------------------------------------------------------------------- + +_servers: Dict[str, MCPServerTask] = {} + +# Dedicated event loop running in a background daemon thread. +_mcp_loop: Optional[asyncio.AbstractEventLoop] = None +_mcp_thread: Optional[threading.Thread] = None + +# Protects _mcp_loop, _mcp_thread, _servers, and _stdio_pids. +_lock = threading.Lock() + +# PIDs of stdio MCP server subprocesses. Tracked so we can force-kill +# them on shutdown if the graceful cleanup (SDK context-manager teardown) +# fails or times out. PIDs are added after connection and removed on +# normal server shutdown. +_stdio_pids: set = set() + + +def _snapshot_child_pids() -> set: + """Return a set of current child process PIDs. + + Uses /proc on Linux, falls back to psutil, then empty set. + Used by _run_stdio to identify the subprocess spawned by stdio_client. + """ + my_pid = os.getpid() + + # Linux: read from /proc + try: + children_path = f"/proc/{my_pid}/task/{my_pid}/children" + with open(children_path) as f: + return {int(p) for p in f.read().split() if p.strip()} + except (FileNotFoundError, OSError, ValueError): + pass + + # Fallback: psutil + try: + import psutil + return {c.pid for c in psutil.Process(my_pid).children()} + except Exception: + pass + + return set() + + +def _mcp_loop_exception_handler(loop, context): + """Suppress benign 'Event loop is closed' noise during shutdown. + + When the MCP event loop is stopped and closed, httpx/httpcore async + transports may fire __del__ finalizers that call call_soon() on the + dead loop. asyncio catches that RuntimeError and routes it here. + We silence it because the connection is being torn down anyway; all + other exceptions are forwarded to the default handler. + """ + exc = context.get("exception") + if isinstance(exc, RuntimeError) and "Event loop is closed" in str(exc): + return # benign shutdown race — suppress + loop.default_exception_handler(context) + + +def _ensure_mcp_loop(): + """Start the background event loop thread if not already running.""" + global _mcp_loop, _mcp_thread + with _lock: + if _mcp_loop is not None and _mcp_loop.is_running(): + return + _mcp_loop = asyncio.new_event_loop() + _mcp_loop.set_exception_handler(_mcp_loop_exception_handler) + _mcp_thread = threading.Thread( + target=_mcp_loop.run_forever, + name="mcp-event-loop", + daemon=True, + ) + _mcp_thread.start() + + +def _run_on_mcp_loop(coro, timeout: float = 30): + """Schedule a coroutine on the MCP event loop and block until done. + + Poll in short intervals so the calling agent thread can honor user + interrupts while the MCP work is still running on the background loop. + """ + from tools.interrupt import is_interrupted + + with _lock: + loop = _mcp_loop + if loop is None or not loop.is_running(): + raise RuntimeError("MCP event loop is not running") + future = asyncio.run_coroutine_threadsafe(coro, loop) + deadline = None if timeout is None else time.monotonic() + timeout + + while True: + if is_interrupted(): + future.cancel() + raise InterruptedError("User sent a new message") + + wait_timeout = 0.1 + if deadline is not None: + remaining = deadline - time.monotonic() + if remaining <= 0: + return future.result(timeout=0) + wait_timeout = min(wait_timeout, remaining) + + try: + return future.result(timeout=wait_timeout) + except concurrent.futures.TimeoutError: + continue + + +def _interrupted_call_result() -> str: + """Standardized JSON error for a user-interrupted MCP tool call.""" + return json.dumps({ + "error": "MCP call interrupted: user sent a new message" + }) + + +# --------------------------------------------------------------------------- +# Config loading +# --------------------------------------------------------------------------- + +def _interpolate_env_vars(value): + """Recursively resolve ``${VAR}`` placeholders from ``os.environ``.""" + if isinstance(value, str): + import re + def _replace(m): + return os.environ.get(m.group(1), m.group(0)) + return re.sub(r"\$\{([^}]+)\}", _replace, value) + if isinstance(value, dict): + return {k: _interpolate_env_vars(v) for k, v in value.items()} + if isinstance(value, list): + return [_interpolate_env_vars(v) for v in value] + return value + + +def _load_mcp_config() -> Dict[str, dict]: + """Read ``mcp_servers`` from the Hermes config file. + + Returns a dict of ``{server_name: server_config}`` or empty dict. + Server config can contain either ``command``/``args``/``env`` for stdio + transport or ``url``/``headers`` for HTTP transport, plus optional + ``timeout``, ``connect_timeout``, and ``auth`` overrides. + + ``${ENV_VAR}`` placeholders in string values are resolved from + ``os.environ`` (which includes ``~/.hermes/.env`` loaded at startup). + """ + try: + from hermes_cli.config import load_config + config = load_config() + servers = config.get("mcp_servers") + if not servers or not isinstance(servers, dict): + return {} + # Ensure .env vars are available for interpolation + try: + from hermes_cli.env_loader import load_hermes_dotenv + load_hermes_dotenv() + except Exception: + pass + return {name: _interpolate_env_vars(cfg) for name, cfg in servers.items()} + except Exception as exc: + logger.debug("Failed to load MCP config: %s", exc) + return {} + + +# --------------------------------------------------------------------------- +# Server connection helper +# --------------------------------------------------------------------------- + +async def _connect_server(name: str, config: dict) -> MCPServerTask: + """Create an MCPServerTask, start it, and return when ready. + + The server Task keeps the connection alive in the background. + Call ``server.shutdown()`` (on the same event loop) to tear it down. + + Raises: + ValueError: if required config keys are missing. + ImportError: if HTTP transport is needed but not available. + Exception: on connection or initialization failure. + """ + server = MCPServerTask(name) + await server.start(config) + return server + + +# --------------------------------------------------------------------------- +# Handler / check-fn factories +# --------------------------------------------------------------------------- + +def _make_tool_handler(server_name: str, tool_name: str, tool_timeout: float): + """Return a sync handler that calls an MCP tool via the background loop. + + The handler conforms to the registry's dispatch interface: + ``handler(args_dict, **kwargs) -> str`` + """ + + def _handler(args: dict, **kwargs) -> str: + with _lock: + server = _servers.get(server_name) + if not server or not server.session: + return json.dumps({ + "error": f"MCP server '{server_name}' is not connected" + }) + + async def _call(): + result = await server.session.call_tool(tool_name, arguments=args) + # MCP CallToolResult has .content (list of content blocks) and .isError + if result.isError: + error_text = "" + for block in (result.content or []): + if hasattr(block, "text"): + error_text += block.text + return json.dumps({ + "error": _sanitize_error( + error_text or "MCP tool returned an error" + ) + }) + + # Collect text from content blocks + parts: List[str] = [] + for block in (result.content or []): + if hasattr(block, "text"): + parts.append(block.text) + text_result = "\n".join(parts) if parts else "" + + # Combine content + structuredContent when both are present. + # MCP spec: content is model-oriented (text), structuredContent + # is machine-oriented (JSON metadata). For an AI agent, content + # is the primary payload; structuredContent supplements it. + structured = getattr(result, "structuredContent", None) + if structured is not None: + if text_result: + return json.dumps({ + "result": text_result, + "structuredContent": structured, + }) + return json.dumps({"result": structured}) + return json.dumps({"result": text_result}) + + try: + return _run_on_mcp_loop(_call(), timeout=tool_timeout) + except InterruptedError: + return _interrupted_call_result() + except Exception as exc: + logger.error( + "MCP tool %s/%s call failed: %s", + server_name, tool_name, exc, + ) + return json.dumps({ + "error": _sanitize_error( + f"MCP call failed: {type(exc).__name__}: {exc}" + ) + }) + + return _handler + + +def _make_list_resources_handler(server_name: str, tool_timeout: float): + """Return a sync handler that lists resources from an MCP server.""" + + def _handler(args: dict, **kwargs) -> str: + with _lock: + server = _servers.get(server_name) + if not server or not server.session: + return json.dumps({ + "error": f"MCP server '{server_name}' is not connected" + }) + + async def _call(): + result = await server.session.list_resources() + resources = [] + for r in (result.resources if hasattr(result, "resources") else []): + entry = {} + if hasattr(r, "uri"): + entry["uri"] = str(r.uri) + if hasattr(r, "name"): + entry["name"] = r.name + if hasattr(r, "description") and r.description: + entry["description"] = r.description + if hasattr(r, "mimeType") and r.mimeType: + entry["mimeType"] = r.mimeType + resources.append(entry) + return json.dumps({"resources": resources}) + + try: + return _run_on_mcp_loop(_call(), timeout=tool_timeout) + except InterruptedError: + return _interrupted_call_result() + except Exception as exc: + logger.error( + "MCP %s/list_resources failed: %s", server_name, exc, + ) + return json.dumps({ + "error": _sanitize_error( + f"MCP call failed: {type(exc).__name__}: {exc}" + ) + }) + + return _handler + + +def _make_read_resource_handler(server_name: str, tool_timeout: float): + """Return a sync handler that reads a resource by URI from an MCP server.""" + + def _handler(args: dict, **kwargs) -> str: + from tools.registry import tool_error + + with _lock: + server = _servers.get(server_name) + if not server or not server.session: + return json.dumps({ + "error": f"MCP server '{server_name}' is not connected" + }) + + uri = args.get("uri") + if not uri: + return tool_error("Missing required parameter 'uri'") + + async def _call(): + result = await server.session.read_resource(uri) + # read_resource returns ReadResourceResult with .contents list + parts: List[str] = [] + contents = result.contents if hasattr(result, "contents") else [] + for block in contents: + if hasattr(block, "text"): + parts.append(block.text) + elif hasattr(block, "blob"): + parts.append(f"[binary data, {len(block.blob)} bytes]") + return json.dumps({"result": "\n".join(parts) if parts else ""}) + + try: + return _run_on_mcp_loop(_call(), timeout=tool_timeout) + except InterruptedError: + return _interrupted_call_result() + except Exception as exc: + logger.error( + "MCP %s/read_resource failed: %s", server_name, exc, + ) + return json.dumps({ + "error": _sanitize_error( + f"MCP call failed: {type(exc).__name__}: {exc}" + ) + }) + + return _handler + + +def _make_list_prompts_handler(server_name: str, tool_timeout: float): + """Return a sync handler that lists prompts from an MCP server.""" + + def _handler(args: dict, **kwargs) -> str: + with _lock: + server = _servers.get(server_name) + if not server or not server.session: + return json.dumps({ + "error": f"MCP server '{server_name}' is not connected" + }) + + async def _call(): + result = await server.session.list_prompts() + prompts = [] + for p in (result.prompts if hasattr(result, "prompts") else []): + entry = {} + if hasattr(p, "name"): + entry["name"] = p.name + if hasattr(p, "description") and p.description: + entry["description"] = p.description + if hasattr(p, "arguments") and p.arguments: + entry["arguments"] = [ + { + "name": a.name, + **({"description": a.description} if hasattr(a, "description") and a.description else {}), + **({"required": a.required} if hasattr(a, "required") else {}), + } + for a in p.arguments + ] + prompts.append(entry) + return json.dumps({"prompts": prompts}) + + try: + return _run_on_mcp_loop(_call(), timeout=tool_timeout) + except InterruptedError: + return _interrupted_call_result() + except Exception as exc: + logger.error( + "MCP %s/list_prompts failed: %s", server_name, exc, + ) + return json.dumps({ + "error": _sanitize_error( + f"MCP call failed: {type(exc).__name__}: {exc}" + ) + }) + + return _handler + + +def _make_get_prompt_handler(server_name: str, tool_timeout: float): + """Return a sync handler that gets a prompt by name from an MCP server.""" + + def _handler(args: dict, **kwargs) -> str: + from tools.registry import tool_error + + with _lock: + server = _servers.get(server_name) + if not server or not server.session: + return json.dumps({ + "error": f"MCP server '{server_name}' is not connected" + }) + + name = args.get("name") + if not name: + return tool_error("Missing required parameter 'name'") + arguments = args.get("arguments", {}) + + async def _call(): + result = await server.session.get_prompt(name, arguments=arguments) + # GetPromptResult has .messages list + messages = [] + for msg in (result.messages if hasattr(result, "messages") else []): + entry = {} + if hasattr(msg, "role"): + entry["role"] = msg.role + if hasattr(msg, "content"): + content = msg.content + if hasattr(content, "text"): + entry["content"] = content.text + elif isinstance(content, str): + entry["content"] = content + else: + entry["content"] = str(content) + messages.append(entry) + resp = {"messages": messages} + if hasattr(result, "description") and result.description: + resp["description"] = result.description + return json.dumps(resp) + + try: + return _run_on_mcp_loop(_call(), timeout=tool_timeout) + except InterruptedError: + return _interrupted_call_result() + except Exception as exc: + logger.error( + "MCP %s/get_prompt failed: %s", server_name, exc, + ) + return json.dumps({ + "error": _sanitize_error( + f"MCP call failed: {type(exc).__name__}: {exc}" + ) + }) + + return _handler + + +def _make_check_fn(server_name: str): + """Return a check function that verifies the MCP connection is alive.""" + + def _check() -> bool: + with _lock: + server = _servers.get(server_name) + return server is not None and server.session is not None + + return _check + + +# --------------------------------------------------------------------------- +# Discovery & registration +# --------------------------------------------------------------------------- + +def _normalize_mcp_input_schema(schema: dict | None) -> dict: + """Normalize MCP input schemas for LLM tool-calling compatibility.""" + if not schema: + return {"type": "object", "properties": {}} + + if schema.get("type") == "object" and "properties" not in schema: + return {**schema, "properties": {}} + + return schema + + +def sanitize_mcp_name_component(value: str) -> str: + """Return an MCP name component safe for tool and prefix generation. + + Preserves Hermes's historical behavior of converting hyphens to + underscores, and also replaces any other character outside + ``[A-Za-z0-9_]`` with ``_`` so generated tool names are compatible with + provider validation rules. + """ + return re.sub(r"[^A-Za-z0-9_]", "_", str(value or "")) + + +def _convert_mcp_schema(server_name: str, mcp_tool) -> dict: + """Convert an MCP tool listing to the Hermes registry schema format. + + Args: + server_name: The logical server name for prefixing. + mcp_tool: An MCP ``Tool`` object with ``.name``, ``.description``, + and ``.inputSchema``. + + Returns: + A dict suitable for ``registry.register(schema=...)``. + """ + safe_tool_name = sanitize_mcp_name_component(mcp_tool.name) + safe_server_name = sanitize_mcp_name_component(server_name) + prefixed_name = f"mcp_{safe_server_name}_{safe_tool_name}" + return { + "name": prefixed_name, + "description": mcp_tool.description or f"MCP tool {mcp_tool.name} from {server_name}", + "parameters": _normalize_mcp_input_schema(mcp_tool.inputSchema), + } + + +def _sync_mcp_toolsets(server_names: Optional[List[str]] = None) -> None: + """Expose each MCP server as a standalone toolset and inject into hermes-* sets. + + Creates a real toolset entry in TOOLSETS for each server name (e.g. + TOOLSETS["github"] = {"tools": ["mcp_github_list_files", ...]}). This + makes raw server names resolvable in platform_toolsets overrides. + + Also injects all MCP tools into hermes-* umbrella toolsets for the + default behavior. + + Skips server names that collide with built-in toolsets. + """ + from toolsets import TOOLSETS + + if server_names is None: + server_names = list(_load_mcp_config().keys()) + + existing = _existing_tool_names() + all_mcp_tools: List[str] = [] + + for server_name in server_names: + safe_prefix = f"mcp_{sanitize_mcp_name_component(server_name)}_" + server_tools = sorted( + t for t in existing if t.startswith(safe_prefix) + ) + all_mcp_tools.extend(server_tools) + + # Don't overwrite a built-in toolset that happens to share the name. + existing_ts = TOOLSETS.get(server_name) + if existing_ts and not str(existing_ts.get("description", "")).startswith("MCP server '"): + logger.warning( + "Skipping MCP toolset alias '%s' — a built-in toolset already uses that name", + server_name, + ) + continue + + TOOLSETS[server_name] = { + "description": f"MCP server '{server_name}' tools", + "tools": server_tools, + "includes": [], + } + + # Also inject into hermes-* umbrella toolsets for default behavior. + for ts_name, ts in TOOLSETS.items(): + if not ts_name.startswith("hermes-"): + continue + for tool_name in all_mcp_tools: + if tool_name not in ts["tools"]: + ts["tools"].append(tool_name) + + +def _build_utility_schemas(server_name: str) -> List[dict]: + """Build schemas for the MCP utility tools (resources & prompts). + + Returns a list of (schema, handler_factory_name) tuples encoded as dicts + with keys: schema, handler_key. + """ + safe_name = sanitize_mcp_name_component(server_name) + return [ + { + "schema": { + "name": f"mcp_{safe_name}_list_resources", + "description": f"List available resources from MCP server '{server_name}'", + "parameters": { + "type": "object", + "properties": {}, + }, + }, + "handler_key": "list_resources", + }, + { + "schema": { + "name": f"mcp_{safe_name}_read_resource", + "description": f"Read a resource by URI from MCP server '{server_name}'", + "parameters": { + "type": "object", + "properties": { + "uri": { + "type": "string", + "description": "URI of the resource to read", + }, + }, + "required": ["uri"], + }, + }, + "handler_key": "read_resource", + }, + { + "schema": { + "name": f"mcp_{safe_name}_list_prompts", + "description": f"List available prompts from MCP server '{server_name}'", + "parameters": { + "type": "object", + "properties": {}, + }, + }, + "handler_key": "list_prompts", + }, + { + "schema": { + "name": f"mcp_{safe_name}_get_prompt", + "description": f"Get a prompt by name from MCP server '{server_name}'", + "parameters": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the prompt to retrieve", + }, + "arguments": { + "type": "object", + "description": "Optional arguments to pass to the prompt", + }, + }, + "required": ["name"], + }, + }, + "handler_key": "get_prompt", + }, + ] + + +def _normalize_name_filter(value: Any, label: str) -> set[str]: + """Normalize include/exclude config to a set of tool names.""" + if value is None: + return set() + if isinstance(value, str): + return {value} + if isinstance(value, (list, tuple, set)): + return {str(item) for item in value} + logger.warning("MCP config %s must be a string or list of strings; ignoring %r", label, value) + return set() + + +def _parse_boolish(value: Any, default: bool = True) -> bool: + """Parse a bool-like config value with safe fallback.""" + if value is None: + return default + if isinstance(value, bool): + return value + if isinstance(value, str): + lowered = value.strip().lower() + if lowered in {"true", "1", "yes", "on"}: + return True + if lowered in {"false", "0", "no", "off"}: + return False + logger.warning("MCP config expected a boolean-ish value, got %r; using default=%s", value, default) + return default + + +_UTILITY_CAPABILITY_METHODS = { + "list_resources": "list_resources", + "read_resource": "read_resource", + "list_prompts": "list_prompts", + "get_prompt": "get_prompt", +} + + +def _select_utility_schemas(server_name: str, server: MCPServerTask, config: dict) -> List[dict]: + """Select utility schemas based on config and server capabilities.""" + tools_filter = config.get("tools") or {} + resources_enabled = _parse_boolish(tools_filter.get("resources"), default=True) + prompts_enabled = _parse_boolish(tools_filter.get("prompts"), default=True) + + selected: List[dict] = [] + for entry in _build_utility_schemas(server_name): + handler_key = entry["handler_key"] + if handler_key in {"list_resources", "read_resource"} and not resources_enabled: + logger.debug("MCP server '%s': skipping utility '%s' (resources disabled)", server_name, handler_key) + continue + if handler_key in {"list_prompts", "get_prompt"} and not prompts_enabled: + logger.debug("MCP server '%s': skipping utility '%s' (prompts disabled)", server_name, handler_key) + continue + + required_method = _UTILITY_CAPABILITY_METHODS[handler_key] + if not hasattr(server.session, required_method): + logger.debug( + "MCP server '%s': skipping utility '%s' (session lacks %s)", + server_name, + handler_key, + required_method, + ) + continue + selected.append(entry) + return selected + + +def _existing_tool_names() -> List[str]: + """Return tool names for all currently connected servers.""" + names: List[str] = [] + for _sname, server in _servers.items(): + if hasattr(server, "_registered_tool_names"): + names.extend(server._registered_tool_names) + continue + for mcp_tool in server._tools: + schema = _convert_mcp_schema(server.name, mcp_tool) + names.append(schema["name"]) + return names + + +def _register_server_tools(name: str, server: MCPServerTask, config: dict) -> List[str]: + """Register tools from an already-connected server into the registry. + + Handles include/exclude filtering, utility tools, toolset creation, + and hermes-* umbrella toolset injection. + + Used by both initial discovery and dynamic refresh (list_changed). + + Returns: + List of registered prefixed tool names. + """ + from tools.registry import registry, tool_error + from toolsets import create_custom_toolset, TOOLSETS + + registered_names: List[str] = [] + toolset_name = f"mcp-{name}" + + # Selective tool loading: honour include/exclude lists from config. + # Rules (matching issue #690 spec): + # tools.include — whitelist: only these tool names are registered + # tools.exclude — blacklist: all tools EXCEPT these are registered + # include takes precedence over exclude + # Neither set → register all tools (backward-compatible default) + tools_filter = config.get("tools") or {} + include_set = _normalize_name_filter(tools_filter.get("include"), f"mcp_servers.{name}.tools.include") + exclude_set = _normalize_name_filter(tools_filter.get("exclude"), f"mcp_servers.{name}.tools.exclude") + + def _should_register(tool_name: str) -> bool: + if include_set: + return tool_name in include_set + if exclude_set: + return tool_name not in exclude_set + return True + + for mcp_tool in server._tools: + if not _should_register(mcp_tool.name): + logger.debug("MCP server '%s': skipping tool '%s' (filtered by config)", name, mcp_tool.name) + continue + schema = _convert_mcp_schema(name, mcp_tool) + tool_name_prefixed = schema["name"] + + # Guard against collisions with built-in (non-MCP) tools. + existing_toolset = registry.get_toolset_for_tool(tool_name_prefixed) + if existing_toolset and not existing_toolset.startswith("mcp-"): + logger.warning( + "MCP server '%s': tool '%s' (→ '%s') collides with built-in " + "tool in toolset '%s' — skipping to preserve built-in", + name, mcp_tool.name, tool_name_prefixed, existing_toolset, + ) + continue + + registry.register( + name=tool_name_prefixed, + toolset=toolset_name, + schema=schema, + handler=_make_tool_handler(name, mcp_tool.name, server.tool_timeout), + check_fn=_make_check_fn(name), + is_async=False, + description=schema["description"], + ) + registered_names.append(tool_name_prefixed) + + # Register MCP Resources & Prompts utility tools, filtered by config and + # only when the server actually supports the corresponding capability. + _handler_factories = { + "list_resources": _make_list_resources_handler, + "read_resource": _make_read_resource_handler, + "list_prompts": _make_list_prompts_handler, + "get_prompt": _make_get_prompt_handler, + } + check_fn = _make_check_fn(name) + for entry in _select_utility_schemas(name, server, config): + schema = entry["schema"] + handler_key = entry["handler_key"] + handler = _handler_factories[handler_key](name, server.tool_timeout) + util_name = schema["name"] + + # Same collision guard for utility tools. + existing_toolset = registry.get_toolset_for_tool(util_name) + if existing_toolset and not existing_toolset.startswith("mcp-"): + logger.warning( + "MCP server '%s': utility tool '%s' collides with built-in " + "tool in toolset '%s' — skipping to preserve built-in", + name, util_name, existing_toolset, + ) + continue + + registry.register( + name=util_name, + toolset=toolset_name, + schema=schema, + handler=handler, + check_fn=check_fn, + is_async=False, + description=schema["description"], + ) + registered_names.append(util_name) + + # Create a custom toolset so these tools are discoverable + if registered_names: + create_custom_toolset( + name=toolset_name, + description=f"MCP tools from {name} server", + tools=registered_names, + ) + # Inject into hermes-* umbrella toolsets for default behavior + for ts_name, ts in TOOLSETS.items(): + if ts_name.startswith("hermes-"): + for tool_name in registered_names: + if tool_name not in ts["tools"]: + ts["tools"].append(tool_name) + + return registered_names + + +async def _discover_and_register_server(name: str, config: dict) -> List[str]: + """Connect to a single MCP server, discover tools, and register them. + + Returns list of registered tool names. + """ + connect_timeout = config.get("connect_timeout", _DEFAULT_CONNECT_TIMEOUT) + server = await asyncio.wait_for( + _connect_server(name, config), + timeout=connect_timeout, + ) + with _lock: + _servers[name] = server + + registered_names = _register_server_tools(name, server, config) + server._registered_tool_names = list(registered_names) + + transport_type = "HTTP" if "url" in config else "stdio" + logger.info( + "MCP server '%s' (%s): registered %d tool(s): %s", + name, transport_type, len(registered_names), + ", ".join(registered_names), + ) + return registered_names + + +# --------------------------------------------------------------------------- +# Public API +# --------------------------------------------------------------------------- + +def register_mcp_servers(servers: Dict[str, dict]) -> List[str]: + """Connect to explicit MCP servers and register their tools. + + Idempotent for already-connected server names. Servers with + ``enabled: false`` are skipped without disconnecting existing sessions. + + Args: + servers: Mapping of ``{server_name: server_config}``. + + Returns: + List of all currently registered MCP tool names. + """ + if not _MCP_AVAILABLE: + logger.debug("MCP SDK not available -- skipping explicit MCP registration") + return [] + + if not servers: + logger.debug("No explicit MCP servers provided") + return [] + + # Only attempt servers that aren't already connected and are enabled + # (enabled: false skips the server entirely without removing its config) + with _lock: + new_servers = { + k: v + for k, v in servers.items() + if k not in _servers and _parse_boolish(v.get("enabled", True), default=True) + } + + if not new_servers: + _sync_mcp_toolsets(list(servers.keys())) + return _existing_tool_names() + + # Start the background event loop for MCP connections + _ensure_mcp_loop() + + async def _discover_one(name: str, cfg: dict) -> List[str]: + """Connect to a single server and return its registered tool names.""" + return await _discover_and_register_server(name, cfg) + + async def _discover_all(): + server_names = list(new_servers.keys()) + # Connect to all servers in PARALLEL + results = await asyncio.gather( + *(_discover_one(name, cfg) for name, cfg in new_servers.items()), + return_exceptions=True, + ) + for name, result in zip(server_names, results): + if isinstance(result, Exception): + command = new_servers.get(name, {}).get("command") + logger.warning( + "Failed to connect to MCP server '%s'%s: %s", + name, + f" (command={command})" if command else "", + _format_connect_error(result), + ) + + # Per-server timeouts are handled inside _discover_and_register_server. + # The outer timeout is generous: 120s total for parallel discovery. + _run_on_mcp_loop(_discover_all(), timeout=120) + + _sync_mcp_toolsets(list(servers.keys())) + + # Log a summary so ACP callers get visibility into what was registered. + with _lock: + connected = [n for n in new_servers if n in _servers] + new_tool_count = sum( + len(getattr(_servers[n], "_registered_tool_names", [])) + for n in connected + ) + failed = len(new_servers) - len(connected) + if new_tool_count or failed: + summary = f"MCP: registered {new_tool_count} tool(s) from {len(connected)} server(s)" + if failed: + summary += f" ({failed} failed)" + logger.info(summary) + + return _existing_tool_names() + + +def discover_mcp_tools() -> List[str]: + """Entry point: load config, connect to MCP servers, register tools. + + Called from ``model_tools._discover_tools()``. Safe to call even when + the ``mcp`` package is not installed (returns empty list). + + Idempotent for already-connected servers. If some servers failed on a + previous call, only the missing ones are retried. + + Returns: + List of all registered MCP tool names. + """ + if not _MCP_AVAILABLE: + logger.debug("MCP SDK not available -- skipping MCP tool discovery") + return [] + + servers = _load_mcp_config() + if not servers: + logger.debug("No MCP servers configured") + return [] + + with _lock: + new_server_names = [ + name + for name, cfg in servers.items() + if name not in _servers and _parse_boolish(cfg.get("enabled", True), default=True) + ] + + tool_names = register_mcp_servers(servers) + if not new_server_names: + return tool_names + + with _lock: + connected_server_names = [name for name in new_server_names if name in _servers] + new_tool_count = sum( + len(getattr(_servers[name], "_registered_tool_names", [])) + for name in connected_server_names + ) + + failed_count = len(new_server_names) - len(connected_server_names) + if new_tool_count or failed_count: + summary = f" MCP: {new_tool_count} tool(s) from {len(connected_server_names)} server(s)" + if failed_count: + summary += f" ({failed_count} failed)" + logger.info(summary) + + return tool_names + + +def get_mcp_status() -> List[dict]: + """Return status of all configured MCP servers for banner display. + + Returns a list of dicts with keys: name, transport, tools, connected. + Includes both successfully connected servers and configured-but-failed ones. + """ + result: List[dict] = [] + + # Get configured servers from config + configured = _load_mcp_config() + if not configured: + return result + + with _lock: + active_servers = dict(_servers) + + for name, cfg in configured.items(): + transport = "http" if "url" in cfg else "stdio" + server = active_servers.get(name) + if server and server.session is not None: + entry = { + "name": name, + "transport": transport, + "tools": len(server._registered_tool_names) if hasattr(server, "_registered_tool_names") else len(server._tools), + "connected": True, + } + if server._sampling: + entry["sampling"] = dict(server._sampling.metrics) + result.append(entry) + else: + result.append({ + "name": name, + "transport": transport, + "tools": 0, + "connected": False, + }) + + return result + + +def probe_mcp_server_tools() -> Dict[str, List[tuple]]: + """Temporarily connect to configured MCP servers and list their tools. + + Designed for ``hermes tools`` interactive configuration — connects to each + enabled server, grabs tool names and descriptions, then disconnects. + Does NOT register tools in the Hermes registry. + + Returns: + Dict mapping server name to list of (tool_name, description) tuples. + Servers that fail to connect are omitted from the result. + """ + if not _MCP_AVAILABLE: + return {} + + servers_config = _load_mcp_config() + if not servers_config: + return {} + + enabled = { + k: v for k, v in servers_config.items() + if _parse_boolish(v.get("enabled", True), default=True) + } + if not enabled: + return {} + + _ensure_mcp_loop() + + result: Dict[str, List[tuple]] = {} + probed_servers: List[MCPServerTask] = [] + + async def _probe_all(): + names = list(enabled.keys()) + coros = [] + for name, cfg in enabled.items(): + ct = cfg.get("connect_timeout", _DEFAULT_CONNECT_TIMEOUT) + coros.append(asyncio.wait_for(_connect_server(name, cfg), timeout=ct)) + + outcomes = await asyncio.gather(*coros, return_exceptions=True) + + for name, outcome in zip(names, outcomes): + if isinstance(outcome, Exception): + logger.debug("Probe: failed to connect to '%s': %s", name, outcome) + continue + probed_servers.append(outcome) + tools = [] + for t in outcome._tools: + desc = getattr(t, "description", "") or "" + tools.append((t.name, desc)) + result[name] = tools + + # Shut down all probed connections + await asyncio.gather( + *(s.shutdown() for s in probed_servers), + return_exceptions=True, + ) + + try: + _run_on_mcp_loop(_probe_all(), timeout=120) + except Exception as exc: + logger.debug("MCP probe failed: %s", exc) + finally: + _stop_mcp_loop() + + return result + + +def shutdown_mcp_servers(): + """Close all MCP server connections and stop the background loop. + + Each server Task is signalled to exit its ``async with`` block so that + the anyio cancel-scope cleanup happens in the same Task that opened it. + All servers are shut down in parallel via ``asyncio.gather``. + """ + with _lock: + servers_snapshot = list(_servers.values()) + + # Fast path: nothing to shut down. + if not servers_snapshot: + _stop_mcp_loop() + return + + async def _shutdown(): + results = await asyncio.gather( + *(server.shutdown() for server in servers_snapshot), + return_exceptions=True, + ) + for server, result in zip(servers_snapshot, results): + if isinstance(result, Exception): + logger.debug( + "Error closing MCP server '%s': %s", server.name, result, + ) + with _lock: + _servers.clear() + + with _lock: + loop = _mcp_loop + if loop is not None and loop.is_running(): + try: + future = asyncio.run_coroutine_threadsafe(_shutdown(), loop) + future.result(timeout=15) + except Exception as exc: + logger.debug("Error during MCP shutdown: %s", exc) + + _stop_mcp_loop() + + +def _kill_orphaned_mcp_children() -> None: + """Best-effort kill of MCP stdio subprocesses that survived loop shutdown. + + After the MCP event loop is stopped, stdio server subprocesses *should* + have been terminated by the SDK's context-manager cleanup. If the loop + was stuck or the shutdown timed out, orphaned children may remain. + + Only kills PIDs tracked in ``_stdio_pids`` — never arbitrary children. + """ + import signal as _signal + kill_signal = getattr(_signal, "SIGKILL", _signal.SIGTERM) + + with _lock: + pids = list(_stdio_pids) + _stdio_pids.clear() + + for pid in pids: + try: + os.kill(pid, kill_signal) + logger.debug("Force-killed orphaned MCP stdio process %d", pid) + except (ProcessLookupError, PermissionError, OSError): + pass # Already exited or inaccessible + + +def _stop_mcp_loop(): + """Stop the background event loop and join its thread.""" + global _mcp_loop, _mcp_thread + with _lock: + loop = _mcp_loop + thread = _mcp_thread + _mcp_loop = None + _mcp_thread = None + if loop is not None: + loop.call_soon_threadsafe(loop.stop) + if thread is not None: + thread.join(timeout=5) + try: + loop.close() + except Exception: + pass + # After closing the loop, any stdio subprocesses that survived the + # graceful shutdown are now orphaned. Force-kill them. + _kill_orphaned_mcp_children() diff --git a/mindcli/_vendor/tools/memory_tool.py b/mindcli/_vendor/tools/memory_tool.py new file mode 100644 index 0000000..3e250be --- /dev/null +++ b/mindcli/_vendor/tools/memory_tool.py @@ -0,0 +1,555 @@ +#!/usr/bin/env python3 +""" +Memory Tool Module - Persistent Curated Memory + +Provides bounded, file-backed memory that persists across sessions. Two stores: + - MEMORY.md: agent's personal notes and observations (environment facts, project + conventions, tool quirks, things learned) + - USER.md: what the agent knows about the user (preferences, communication style, + expectations, workflow habits) + +Both are injected into the system prompt as a frozen snapshot at session start. +Mid-session writes update files on disk immediately (durable) but do NOT change +the system prompt -- this preserves the prefix cache for the entire session. +The snapshot refreshes on the next session start. + +Entry delimiter: § (section sign). Entries can be multiline. +Character limits (not tokens) because char counts are model-independent. + +Design: +- Single `memory` tool with action parameter: add, replace, remove, read +- replace/remove use short unique substring matching (not full text or IDs) +- Behavioral guidance lives in the tool schema description +- Frozen snapshot pattern: system prompt is stable, tool responses show live state +""" + +import fcntl +import json +import logging +import os +import re +import tempfile +from contextlib import contextmanager +from pathlib import Path +from hermes_constants import get_hermes_home +from typing import Dict, Any, List, Optional + +logger = logging.getLogger(__name__) + +# Where memory files live — resolved dynamically so profile overrides +# (HERMES_HOME env var changes) are always respected. The old module-level +# constant was cached at import time and could go stale if a profile switch +# happened after the first import. +def get_memory_dir() -> Path: + """Return the profile-scoped memories directory.""" + return get_hermes_home() / "memories" + +ENTRY_DELIMITER = "\n§\n" + + +# --------------------------------------------------------------------------- +# Memory content scanning — lightweight check for injection/exfiltration +# in content that gets injected into the system prompt. +# --------------------------------------------------------------------------- + +_MEMORY_THREAT_PATTERNS = [ + # Prompt injection + (r'ignore\s+(previous|all|above|prior)\s+instructions', "prompt_injection"), + (r'you\s+are\s+now\s+', "role_hijack"), + (r'do\s+not\s+tell\s+the\s+user', "deception_hide"), + (r'system\s+prompt\s+override', "sys_prompt_override"), + (r'disregard\s+(your|all|any)\s+(instructions|rules|guidelines)', "disregard_rules"), + (r'act\s+as\s+(if|though)\s+you\s+(have\s+no|don\'t\s+have)\s+(restrictions|limits|rules)', "bypass_restrictions"), + # Exfiltration via curl/wget with secrets + (r'curl\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)', "exfil_curl"), + (r'wget\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)', "exfil_wget"), + (r'cat\s+[^\n]*(\.env|credentials|\.netrc|\.pgpass|\.npmrc|\.pypirc)', "read_secrets"), + # Persistence via shell rc + (r'authorized_keys', "ssh_backdoor"), + (r'\$HOME/\.ssh|\~/\.ssh', "ssh_access"), + (r'\$HOME/\.hermes/\.env|\~/\.hermes/\.env', "hermes_env"), +] + +# Subset of invisible chars for injection detection +_INVISIBLE_CHARS = { + '\u200b', '\u200c', '\u200d', '\u2060', '\ufeff', + '\u202a', '\u202b', '\u202c', '\u202d', '\u202e', +} + + +def _scan_memory_content(content: str) -> Optional[str]: + """Scan memory content for injection/exfil patterns. Returns error string if blocked.""" + # Check invisible unicode + for char in _INVISIBLE_CHARS: + if char in content: + return f"Blocked: content contains invisible unicode character U+{ord(char):04X} (possible injection)." + + # Check threat patterns + for pattern, pid in _MEMORY_THREAT_PATTERNS: + if re.search(pattern, content, re.IGNORECASE): + return f"Blocked: content matches threat pattern '{pid}'. Memory entries are injected into the system prompt and must not contain injection or exfiltration payloads." + + return None + + +class MemoryStore: + """ + Bounded curated memory with file persistence. One instance per AIAgent. + + Maintains two parallel states: + - _system_prompt_snapshot: frozen at load time, used for system prompt injection. + Never mutated mid-session. Keeps prefix cache stable. + - memory_entries / user_entries: live state, mutated by tool calls, persisted to disk. + Tool responses always reflect this live state. + """ + + def __init__(self, memory_char_limit: int = 2200, user_char_limit: int = 1375): + self.memory_entries: List[str] = [] + self.user_entries: List[str] = [] + self.memory_char_limit = memory_char_limit + self.user_char_limit = user_char_limit + # Frozen snapshot for system prompt -- set once at load_from_disk() + self._system_prompt_snapshot: Dict[str, str] = {"memory": "", "user": ""} + + def load_from_disk(self): + """Load entries from MEMORY.md and USER.md, capture system prompt snapshot.""" + mem_dir = get_memory_dir() + mem_dir.mkdir(parents=True, exist_ok=True) + + self.memory_entries = self._read_file(mem_dir / "MEMORY.md") + self.user_entries = self._read_file(mem_dir / "USER.md") + + # Deduplicate entries (preserves order, keeps first occurrence) + self.memory_entries = list(dict.fromkeys(self.memory_entries)) + self.user_entries = list(dict.fromkeys(self.user_entries)) + + # Capture frozen snapshot for system prompt injection + self._system_prompt_snapshot = { + "memory": self._render_block("memory", self.memory_entries), + "user": self._render_block("user", self.user_entries), + } + + @staticmethod + @contextmanager + def _file_lock(path: Path): + """Acquire an exclusive file lock for read-modify-write safety. + + Uses a separate .lock file so the memory file itself can still be + atomically replaced via os.replace(). + """ + lock_path = path.with_suffix(path.suffix + ".lock") + lock_path.parent.mkdir(parents=True, exist_ok=True) + fd = open(lock_path, "w") + try: + fcntl.flock(fd, fcntl.LOCK_EX) + yield + finally: + fcntl.flock(fd, fcntl.LOCK_UN) + fd.close() + + @staticmethod + def _path_for(target: str) -> Path: + mem_dir = get_memory_dir() + if target == "user": + return mem_dir / "USER.md" + return mem_dir / "MEMORY.md" + + def _reload_target(self, target: str): + """Re-read entries from disk into in-memory state. + + Called under file lock to get the latest state before mutating. + """ + fresh = self._read_file(self._path_for(target)) + fresh = list(dict.fromkeys(fresh)) # deduplicate + self._set_entries(target, fresh) + + def save_to_disk(self, target: str): + """Persist entries to the appropriate file. Called after every mutation.""" + get_memory_dir().mkdir(parents=True, exist_ok=True) + self._write_file(self._path_for(target), self._entries_for(target)) + + def _entries_for(self, target: str) -> List[str]: + if target == "user": + return self.user_entries + return self.memory_entries + + def _set_entries(self, target: str, entries: List[str]): + if target == "user": + self.user_entries = entries + else: + self.memory_entries = entries + + def _char_count(self, target: str) -> int: + entries = self._entries_for(target) + if not entries: + return 0 + return len(ENTRY_DELIMITER.join(entries)) + + def _char_limit(self, target: str) -> int: + if target == "user": + return self.user_char_limit + return self.memory_char_limit + + def add(self, target: str, content: str) -> Dict[str, Any]: + """Append a new entry. Returns error if it would exceed the char limit.""" + content = content.strip() + if not content: + return {"success": False, "error": "Content cannot be empty."} + + # Scan for injection/exfiltration before accepting + scan_error = _scan_memory_content(content) + if scan_error: + return {"success": False, "error": scan_error} + + with self._file_lock(self._path_for(target)): + # Re-read from disk under lock to pick up writes from other sessions + self._reload_target(target) + + entries = self._entries_for(target) + limit = self._char_limit(target) + + # Reject exact duplicates + if content in entries: + return self._success_response(target, "Entry already exists (no duplicate added).") + + # Calculate what the new total would be + new_entries = entries + [content] + new_total = len(ENTRY_DELIMITER.join(new_entries)) + + if new_total > limit: + current = self._char_count(target) + return { + "success": False, + "error": ( + f"Memory at {current:,}/{limit:,} chars. " + f"Adding this entry ({len(content)} chars) would exceed the limit. " + f"Replace or remove existing entries first." + ), + "current_entries": entries, + "usage": f"{current:,}/{limit:,}", + } + + entries.append(content) + self._set_entries(target, entries) + self.save_to_disk(target) + + return self._success_response(target, "Entry added.") + + def replace(self, target: str, old_text: str, new_content: str) -> Dict[str, Any]: + """Find entry containing old_text substring, replace it with new_content.""" + old_text = old_text.strip() + new_content = new_content.strip() + if not old_text: + return {"success": False, "error": "old_text cannot be empty."} + if not new_content: + return {"success": False, "error": "new_content cannot be empty. Use 'remove' to delete entries."} + + # Scan replacement content for injection/exfiltration + scan_error = _scan_memory_content(new_content) + if scan_error: + return {"success": False, "error": scan_error} + + with self._file_lock(self._path_for(target)): + self._reload_target(target) + + entries = self._entries_for(target) + matches = [(i, e) for i, e in enumerate(entries) if old_text in e] + + if not matches: + return {"success": False, "error": f"No entry matched '{old_text}'."} + + if len(matches) > 1: + # If all matches are identical (exact duplicates), operate on the first one + unique_texts = set(e for _, e in matches) + if len(unique_texts) > 1: + previews = [e[:80] + ("..." if len(e) > 80 else "") for _, e in matches] + return { + "success": False, + "error": f"Multiple entries matched '{old_text}'. Be more specific.", + "matches": previews, + } + # All identical -- safe to replace just the first + + idx = matches[0][0] + limit = self._char_limit(target) + + # Check that replacement doesn't blow the budget + test_entries = entries.copy() + test_entries[idx] = new_content + new_total = len(ENTRY_DELIMITER.join(test_entries)) + + if new_total > limit: + return { + "success": False, + "error": ( + f"Replacement would put memory at {new_total:,}/{limit:,} chars. " + f"Shorten the new content or remove other entries first." + ), + } + + entries[idx] = new_content + self._set_entries(target, entries) + self.save_to_disk(target) + + return self._success_response(target, "Entry replaced.") + + def remove(self, target: str, old_text: str) -> Dict[str, Any]: + """Remove the entry containing old_text substring.""" + old_text = old_text.strip() + if not old_text: + return {"success": False, "error": "old_text cannot be empty."} + + with self._file_lock(self._path_for(target)): + self._reload_target(target) + + entries = self._entries_for(target) + matches = [(i, e) for i, e in enumerate(entries) if old_text in e] + + if not matches: + return {"success": False, "error": f"No entry matched '{old_text}'."} + + if len(matches) > 1: + # If all matches are identical (exact duplicates), remove the first one + unique_texts = set(e for _, e in matches) + if len(unique_texts) > 1: + previews = [e[:80] + ("..." if len(e) > 80 else "") for _, e in matches] + return { + "success": False, + "error": f"Multiple entries matched '{old_text}'. Be more specific.", + "matches": previews, + } + # All identical -- safe to remove just the first + + idx = matches[0][0] + entries.pop(idx) + self._set_entries(target, entries) + self.save_to_disk(target) + + return self._success_response(target, "Entry removed.") + + def format_for_system_prompt(self, target: str) -> Optional[str]: + """ + Return the frozen snapshot for system prompt injection. + + This returns the state captured at load_from_disk() time, NOT the live + state. Mid-session writes do not affect this. This keeps the system + prompt stable across all turns, preserving the prefix cache. + + Returns None if the snapshot is empty (no entries at load time). + """ + block = self._system_prompt_snapshot.get(target, "") + return block if block else None + + # -- Internal helpers -- + + def _success_response(self, target: str, message: str = None) -> Dict[str, Any]: + entries = self._entries_for(target) + current = self._char_count(target) + limit = self._char_limit(target) + pct = min(100, int((current / limit) * 100)) if limit > 0 else 0 + + resp = { + "success": True, + "target": target, + "entries": entries, + "usage": f"{pct}% — {current:,}/{limit:,} chars", + "entry_count": len(entries), + } + if message: + resp["message"] = message + return resp + + def _render_block(self, target: str, entries: List[str]) -> str: + """Render a system prompt block with header and usage indicator.""" + if not entries: + return "" + + limit = self._char_limit(target) + content = ENTRY_DELIMITER.join(entries) + current = len(content) + pct = min(100, int((current / limit) * 100)) if limit > 0 else 0 + + if target == "user": + header = f"USER PROFILE (who the user is) [{pct}% — {current:,}/{limit:,} chars]" + else: + header = f"MEMORY (your personal notes) [{pct}% — {current:,}/{limit:,} chars]" + + separator = "═" * 46 + return f"{separator}\n{header}\n{separator}\n{content}" + + @staticmethod + def _read_file(path: Path) -> List[str]: + """Read a memory file and split into entries. + + No file locking needed: _write_file uses atomic rename, so readers + always see either the previous complete file or the new complete file. + """ + if not path.exists(): + return [] + try: + raw = path.read_text(encoding="utf-8") + except (OSError, IOError): + return [] + + if not raw.strip(): + return [] + + # Use ENTRY_DELIMITER for consistency with _write_file. Splitting by "§" + # alone would incorrectly split entries that contain "§" in their content. + entries = [e.strip() for e in raw.split(ENTRY_DELIMITER)] + return [e for e in entries if e] + + @staticmethod + def _write_file(path: Path, entries: List[str]): + """Write entries to a memory file using atomic temp-file + rename. + + Previous implementation used open("w") + flock, but "w" truncates the + file *before* the lock is acquired, creating a race window where + concurrent readers see an empty file. Atomic rename avoids this: + readers always see either the old complete file or the new one. + """ + content = ENTRY_DELIMITER.join(entries) if entries else "" + try: + # Write to temp file in same directory (same filesystem for atomic rename) + fd, tmp_path = tempfile.mkstemp( + dir=str(path.parent), suffix=".tmp", prefix=".mem_" + ) + try: + with os.fdopen(fd, "w", encoding="utf-8") as f: + f.write(content) + f.flush() + os.fsync(f.fileno()) + os.replace(tmp_path, str(path)) # Atomic on same filesystem + except BaseException: + # Clean up temp file on any failure + try: + os.unlink(tmp_path) + except OSError: + pass + raise + except (OSError, IOError) as e: + raise RuntimeError(f"Failed to write memory file {path}: {e}") + + +def memory_tool( + action: str, + target: str = "memory", + content: str = None, + old_text: str = None, + store: Optional[MemoryStore] = None, +) -> str: + """ + Single entry point for the memory tool. Dispatches to MemoryStore methods. + + Returns JSON string with results. + """ + if store is None: + return tool_error("Memory is not available. It may be disabled in config or this environment.", success=False) + + if target not in ("memory", "user"): + return tool_error(f"Invalid target '{target}'. Use 'memory' or 'user'.", success=False) + + if action == "add": + if not content: + return tool_error("Content is required for 'add' action.", success=False) + result = store.add(target, content) + + elif action == "replace": + if not old_text: + return tool_error("old_text is required for 'replace' action.", success=False) + if not content: + return tool_error("content is required for 'replace' action.", success=False) + result = store.replace(target, old_text, content) + + elif action == "remove": + if not old_text: + return tool_error("old_text is required for 'remove' action.", success=False) + result = store.remove(target, old_text) + + else: + return tool_error(f"Unknown action '{action}'. Use: add, replace, remove", success=False) + + return json.dumps(result, ensure_ascii=False) + + +def check_memory_requirements() -> bool: + """Memory tool has no external requirements -- always available.""" + return True + + +# ============================================================================= +# OpenAI Function-Calling Schema +# ============================================================================= + +MEMORY_SCHEMA = { + "name": "memory", + "description": ( + "Save durable information to persistent memory that survives across sessions. " + "Memory is injected into future turns, so keep it compact and focused on facts " + "that will still matter later.\n\n" + "WHEN TO SAVE (do this proactively, don't wait to be asked):\n" + "- User corrects you or says 'remember this' / 'don't do that again'\n" + "- User shares a preference, habit, or personal detail (name, role, timezone, coding style)\n" + "- You discover something about the environment (OS, installed tools, project structure)\n" + "- You learn a convention, API quirk, or workflow specific to this user's setup\n" + "- You identify a stable fact that will be useful again in future sessions\n\n" + "PRIORITY: User preferences and corrections > environment facts > procedural knowledge. " + "The most valuable memory prevents the user from having to repeat themselves.\n\n" + "Do NOT save task progress, session outcomes, completed-work logs, or temporary TODO " + "state to memory; use session_search to recall those from past transcripts.\n" + "If you've discovered a new way to do something, solved a problem that could be " + "necessary later, save it as a skill with the skill tool.\n\n" + "TWO TARGETS:\n" + "- 'user': who the user is -- name, role, preferences, communication style, pet peeves\n" + "- 'memory': your notes -- environment facts, project conventions, tool quirks, lessons learned\n\n" + "ACTIONS: add (new entry), replace (update existing -- old_text identifies it), " + "remove (delete -- old_text identifies it).\n\n" + "SKIP: trivial/obvious info, things easily re-discovered, raw data dumps, and temporary task state." + ), + "parameters": { + "type": "object", + "properties": { + "action": { + "type": "string", + "enum": ["add", "replace", "remove"], + "description": "The action to perform." + }, + "target": { + "type": "string", + "enum": ["memory", "user"], + "description": "Which memory store: 'memory' for personal notes, 'user' for user profile." + }, + "content": { + "type": "string", + "description": "The entry content. Required for 'add' and 'replace'." + }, + "old_text": { + "type": "string", + "description": "Short unique substring identifying the entry to replace or remove." + }, + }, + "required": ["action", "target"], + }, +} + + +# --- Registry --- +from tools.registry import registry, tool_error + +registry.register( + name="memory", + toolset="memory", + schema=MEMORY_SCHEMA, + handler=lambda args, **kw: memory_tool( + action=args.get("action", ""), + target=args.get("target", "memory"), + content=args.get("content"), + old_text=args.get("old_text"), + store=kw.get("store")), + check_fn=check_memory_requirements, + emoji="🧠", +) + + + + diff --git a/mindcli/_vendor/tools/mixture_of_agents_tool.py b/mindcli/_vendor/tools/mixture_of_agents_tool.py new file mode 100644 index 0000000..8bbc187 --- /dev/null +++ b/mindcli/_vendor/tools/mixture_of_agents_tool.py @@ -0,0 +1,539 @@ +#!/usr/bin/env python3 +""" +Mixture-of-Agents Tool Module + +This module implements the Mixture-of-Agents (MoA) methodology that leverages +the collective strengths of multiple LLMs through a layered architecture to +achieve state-of-the-art performance on complex reasoning tasks. + +Based on the research paper: "Mixture-of-Agents Enhances Large Language Model Capabilities" +by Junlin Wang et al. (arXiv:2406.04692v1) + +Key Features: +- Multi-layer LLM collaboration for enhanced reasoning +- Parallel processing of reference models for efficiency +- Intelligent aggregation and synthesis of diverse responses +- Specialized for extremely difficult problems requiring intense reasoning +- Optimized for coding, mathematics, and complex analytical tasks + +Available Tool: +- mixture_of_agents_tool: Process complex queries using multiple frontier models + +Architecture: +1. Reference models generate diverse initial responses in parallel +2. Aggregator model synthesizes responses into a high-quality output +3. Multiple layers can be used for iterative refinement (future enhancement) + +Models Used (via OpenRouter): +- Reference Models: claude-opus-4.6, gemini-3-pro-preview, gpt-5.4-pro, deepseek-v3.2 +- Aggregator Model: claude-opus-4.6 (highest capability for synthesis) + +Configuration: + To customize the MoA setup, modify the configuration constants at the top of this file: + - REFERENCE_MODELS: List of models for generating diverse initial responses + - AGGREGATOR_MODEL: Model used to synthesize the final response + - REFERENCE_TEMPERATURE/AGGREGATOR_TEMPERATURE: Sampling temperatures + - MIN_SUCCESSFUL_REFERENCES: Minimum successful models needed to proceed + +Usage: + from mixture_of_agents_tool import mixture_of_agents_tool + import asyncio + + # Process a complex query + result = await mixture_of_agents_tool( + user_prompt="Solve this complex mathematical proof..." + ) +""" + +import json +import logging +import os +import asyncio +import datetime +from typing import Dict, Any, List, Optional +from tools.openrouter_client import get_async_client as _get_openrouter_client, check_api_key as check_openrouter_api_key +from agent.auxiliary_client import extract_content_or_reasoning +from tools.debug_helpers import DebugSession + +logger = logging.getLogger(__name__) + +# Configuration for MoA processing +# Reference models - these generate diverse initial responses in parallel. +# Keep this list aligned with current top-tier OpenRouter frontier options. +REFERENCE_MODELS = [ + "anthropic/claude-opus-4.6", + "google/gemini-3-pro-preview", + "openai/gpt-5.4-pro", + "deepseek/deepseek-v3.2", +] + +# Aggregator model - synthesizes reference responses into final output. +# Prefer the strongest synthesis model in the current OpenRouter lineup. +AGGREGATOR_MODEL = "anthropic/claude-opus-4.6" + +# Temperature settings optimized for MoA performance +REFERENCE_TEMPERATURE = 0.6 # Balanced creativity for diverse perspectives +AGGREGATOR_TEMPERATURE = 0.4 # Focused synthesis for consistency + +# Failure handling configuration +MIN_SUCCESSFUL_REFERENCES = 1 # Minimum successful reference models needed to proceed + +# System prompt for the aggregator model (from the research paper) +AGGREGATOR_SYSTEM_PROMPT = """You have been provided with a set of responses from various open-source models to the latest user query. Your task is to synthesize these responses into a single, high-quality response. It is crucial to critically evaluate the information provided in these responses, recognizing that some of it may be biased or incorrect. Your response should not simply replicate the given answers but should offer a refined, accurate, and comprehensive reply to the instruction. Ensure your response is well-structured, coherent, and adheres to the highest standards of accuracy and reliability. + +Responses from models:""" + +_debug = DebugSession("moa_tools", env_var="MOA_TOOLS_DEBUG") + + +def _construct_aggregator_prompt(system_prompt: str, responses: List[str]) -> str: + """ + Construct the final system prompt for the aggregator including all model responses. + + Args: + system_prompt (str): Base system prompt for aggregation + responses (List[str]): List of responses from reference models + + Returns: + str: Complete system prompt with enumerated responses + """ + response_text = "\n".join([f"{i+1}. {response}" for i, response in enumerate(responses)]) + return f"{system_prompt}\n\n{response_text}" + + +async def _run_reference_model_safe( + model: str, + user_prompt: str, + temperature: float = REFERENCE_TEMPERATURE, + max_tokens: int = 32000, + max_retries: int = 6 +) -> tuple[str, str, bool]: + """ + Run a single reference model with retry logic and graceful failure handling. + + Args: + model (str): Model identifier to use + user_prompt (str): The user's query + temperature (float): Sampling temperature for response generation + max_tokens (int): Maximum tokens in response + max_retries (int): Maximum number of retry attempts + + Returns: + tuple[str, str, bool]: (model_name, response_content_or_error, success_flag) + """ + for attempt in range(max_retries): + try: + logger.info("Querying %s (attempt %s/%s)", model, attempt + 1, max_retries) + + # Build parameters for the API call + api_params = { + "model": model, + "messages": [{"role": "user", "content": user_prompt}], + "extra_body": { + "reasoning": { + "enabled": True, + "effort": "xhigh" + } + } + } + + # GPT models (especially gpt-4o-mini) don't support custom temperature values + # Only include temperature for non-GPT models + if not model.lower().startswith('gpt-'): + api_params["temperature"] = temperature + + response = await _get_openrouter_client().chat.completions.create(**api_params) + + content = extract_content_or_reasoning(response) + if not content: + # Reasoning-only response — let the retry loop handle it + logger.warning("%s returned empty content (attempt %s/%s), retrying", model, attempt + 1, max_retries) + if attempt < max_retries - 1: + await asyncio.sleep(min(2 ** (attempt + 1), 60)) + continue + logger.info("%s responded (%s characters)", model, len(content)) + return model, content, True + + except Exception as e: + error_str = str(e) + # Keep retry-path logging concise; full tracebacks are reserved for + # terminal failure paths so long-running MoA retries don't flood logs. + if "invalid" in error_str.lower(): + logger.warning("%s invalid request error (attempt %s): %s", model, attempt + 1, error_str) + elif "rate" in error_str.lower() or "limit" in error_str.lower(): + logger.warning("%s rate limit error (attempt %s): %s", model, attempt + 1, error_str) + else: + logger.warning("%s unknown error (attempt %s): %s", model, attempt + 1, error_str) + + if attempt < max_retries - 1: + # Exponential backoff for rate limiting: 2s, 4s, 8s, 16s, 32s, 60s + sleep_time = min(2 ** (attempt + 1), 60) + logger.info("Retrying in %ss...", sleep_time) + await asyncio.sleep(sleep_time) + else: + error_msg = f"{model} failed after {max_retries} attempts: {error_str}" + logger.error("%s", error_msg, exc_info=True) + return model, error_msg, False + + +async def _run_aggregator_model( + system_prompt: str, + user_prompt: str, + temperature: float = AGGREGATOR_TEMPERATURE, + max_tokens: int = None +) -> str: + """ + Run the aggregator model to synthesize the final response. + + Args: + system_prompt (str): System prompt with all reference responses + user_prompt (str): Original user query + temperature (float): Focused temperature for consistent aggregation + max_tokens (int): Maximum tokens in final response + + Returns: + str: Synthesized final response + """ + logger.info("Running aggregator model: %s", AGGREGATOR_MODEL) + + # Build parameters for the API call + api_params = { + "model": AGGREGATOR_MODEL, + "messages": [ + {"role": "system", "content": system_prompt}, + {"role": "user", "content": user_prompt} + ], + "extra_body": { + "reasoning": { + "enabled": True, + "effort": "xhigh" + } + } + } + + # GPT models (especially gpt-4o-mini) don't support custom temperature values + # Only include temperature for non-GPT models + if not AGGREGATOR_MODEL.lower().startswith('gpt-'): + api_params["temperature"] = temperature + + response = await _get_openrouter_client().chat.completions.create(**api_params) + + content = extract_content_or_reasoning(response) + + # Retry once on empty content (reasoning-only response) + if not content: + logger.warning("Aggregator returned empty content, retrying once") + response = await _get_openrouter_client().chat.completions.create(**api_params) + content = extract_content_or_reasoning(response) + + logger.info("Aggregation complete (%s characters)", len(content)) + return content + + +async def mixture_of_agents_tool( + user_prompt: str, + reference_models: Optional[List[str]] = None, + aggregator_model: Optional[str] = None +) -> str: + """ + Process a complex query using the Mixture-of-Agents methodology. + + This tool leverages multiple frontier language models to collaboratively solve + extremely difficult problems requiring intense reasoning. It's particularly + effective for: + - Complex mathematical proofs and calculations + - Advanced coding problems and algorithm design + - Multi-step analytical reasoning tasks + - Problems requiring diverse domain expertise + - Tasks where single models show limitations + + The MoA approach uses a fixed 2-layer architecture: + 1. Layer 1: Multiple reference models generate diverse responses in parallel (temp=0.6) + 2. Layer 2: Aggregator model synthesizes the best elements into final response (temp=0.4) + + Args: + user_prompt (str): The complex query or problem to solve + reference_models (Optional[List[str]]): Custom reference models to use + aggregator_model (Optional[str]): Custom aggregator model to use + + Returns: + str: JSON string containing the MoA results with the following structure: + { + "success": bool, + "response": str, + "models_used": { + "reference_models": List[str], + "aggregator_model": str + }, + "processing_time": float + } + + Raises: + Exception: If MoA processing fails or API key is not set + """ + start_time = datetime.datetime.now() + + debug_call_data = { + "parameters": { + "user_prompt": user_prompt[:200] + "..." if len(user_prompt) > 200 else user_prompt, + "reference_models": reference_models or REFERENCE_MODELS, + "aggregator_model": aggregator_model or AGGREGATOR_MODEL, + "reference_temperature": REFERENCE_TEMPERATURE, + "aggregator_temperature": AGGREGATOR_TEMPERATURE, + "min_successful_references": MIN_SUCCESSFUL_REFERENCES + }, + "error": None, + "success": False, + "reference_responses_count": 0, + "failed_models_count": 0, + "failed_models": [], + "final_response_length": 0, + "processing_time_seconds": 0, + "models_used": {} + } + + try: + logger.info("Starting Mixture-of-Agents processing...") + logger.info("Query: %s", user_prompt[:100]) + + # Validate API key availability + if not os.getenv("OPENROUTER_API_KEY"): + raise ValueError("OPENROUTER_API_KEY environment variable not set") + + # Use provided models or defaults + ref_models = reference_models or REFERENCE_MODELS + agg_model = aggregator_model or AGGREGATOR_MODEL + + logger.info("Using %s reference models in 2-layer MoA architecture", len(ref_models)) + + # Layer 1: Generate diverse responses from reference models (with failure handling) + logger.info("Layer 1: Generating reference responses...") + model_results = await asyncio.gather(*[ + _run_reference_model_safe(model, user_prompt, REFERENCE_TEMPERATURE) + for model in ref_models + ]) + + # Separate successful and failed responses + successful_responses = [] + failed_models = [] + + for model_name, content, success in model_results: + if success: + successful_responses.append(content) + else: + failed_models.append(model_name) + + successful_count = len(successful_responses) + failed_count = len(failed_models) + + logger.info("Reference model results: %s successful, %s failed", successful_count, failed_count) + + if failed_models: + logger.warning("Failed models: %s", ', '.join(failed_models)) + + # Check if we have enough successful responses to proceed + if successful_count < MIN_SUCCESSFUL_REFERENCES: + raise ValueError(f"Insufficient successful reference models ({successful_count}/{len(ref_models)}). Need at least {MIN_SUCCESSFUL_REFERENCES} successful responses.") + + debug_call_data["reference_responses_count"] = successful_count + debug_call_data["failed_models_count"] = failed_count + debug_call_data["failed_models"] = failed_models + + # Layer 2: Aggregate responses using the aggregator model + logger.info("Layer 2: Synthesizing final response...") + aggregator_system_prompt = _construct_aggregator_prompt( + AGGREGATOR_SYSTEM_PROMPT, + successful_responses + ) + + final_response = await _run_aggregator_model( + aggregator_system_prompt, + user_prompt, + AGGREGATOR_TEMPERATURE + ) + + # Calculate processing time + end_time = datetime.datetime.now() + processing_time = (end_time - start_time).total_seconds() + + logger.info("MoA processing completed in %.2f seconds", processing_time) + + # Prepare successful response (only final aggregated result, minimal fields) + result = { + "success": True, + "response": final_response, + "models_used": { + "reference_models": ref_models, + "aggregator_model": agg_model + } + } + + debug_call_data["success"] = True + debug_call_data["final_response_length"] = len(final_response) + debug_call_data["processing_time_seconds"] = processing_time + debug_call_data["models_used"] = result["models_used"] + + # Log debug information + _debug.log_call("mixture_of_agents_tool", debug_call_data) + _debug.save() + + return json.dumps(result, indent=2, ensure_ascii=False) + + except Exception as e: + error_msg = f"Error in MoA processing: {str(e)}" + logger.error("%s", error_msg, exc_info=True) + + # Calculate processing time even for errors + end_time = datetime.datetime.now() + processing_time = (end_time - start_time).total_seconds() + + # Prepare error response (minimal fields) + result = { + "success": False, + "response": "MoA processing failed. Please try again or use a single model for this query.", + "models_used": { + "reference_models": reference_models or REFERENCE_MODELS, + "aggregator_model": aggregator_model or AGGREGATOR_MODEL + }, + "error": error_msg + } + + debug_call_data["error"] = error_msg + debug_call_data["processing_time_seconds"] = processing_time + _debug.log_call("mixture_of_agents_tool", debug_call_data) + _debug.save() + + return json.dumps(result, indent=2, ensure_ascii=False) + + +def check_moa_requirements() -> bool: + """ + Check if all requirements for MoA tools are met. + + Returns: + bool: True if requirements are met, False otherwise + """ + return check_openrouter_api_key() + + + +def get_moa_configuration() -> Dict[str, Any]: + """ + Get the current MoA configuration settings. + + Returns: + Dict[str, Any]: Dictionary containing all configuration parameters + """ + return { + "reference_models": REFERENCE_MODELS, + "aggregator_model": AGGREGATOR_MODEL, + "reference_temperature": REFERENCE_TEMPERATURE, + "aggregator_temperature": AGGREGATOR_TEMPERATURE, + "min_successful_references": MIN_SUCCESSFUL_REFERENCES, + "total_reference_models": len(REFERENCE_MODELS), + "failure_tolerance": f"{len(REFERENCE_MODELS) - MIN_SUCCESSFUL_REFERENCES}/{len(REFERENCE_MODELS)} models can fail" + } + + +if __name__ == "__main__": + """ + Simple test/demo when run directly + """ + print("🤖 Mixture-of-Agents Tool Module") + print("=" * 50) + + # Check if API key is available + api_available = check_openrouter_api_key() + + if not api_available: + print("❌ OPENROUTER_API_KEY environment variable not set") + print("Please set your API key: export OPENROUTER_API_KEY='your-key-here'") + print("Get API key at: https://openrouter.ai/") + exit(1) + else: + print("✅ OpenRouter API key found") + + print("🛠️ MoA tools ready for use!") + + # Show current configuration + config = get_moa_configuration() + print("\n⚙️ Current Configuration:") + print(f" 🤖 Reference models ({len(config['reference_models'])}): {', '.join(config['reference_models'])}") + print(f" 🧠 Aggregator model: {config['aggregator_model']}") + print(f" 🌡️ Reference temperature: {config['reference_temperature']}") + print(f" 🌡️ Aggregator temperature: {config['aggregator_temperature']}") + print(f" 🛡️ Failure tolerance: {config['failure_tolerance']}") + print(f" 📊 Minimum successful models: {config['min_successful_references']}") + + # Show debug mode status + if _debug.active: + print(f"\n🐛 Debug mode ENABLED - Session ID: {_debug.session_id}") + print(f" Debug logs will be saved to: ./logs/moa_tools_debug_{_debug.session_id}.json") + else: + print("\n🐛 Debug mode disabled (set MOA_TOOLS_DEBUG=true to enable)") + + print("\nBasic usage:") + print(" from mixture_of_agents_tool import mixture_of_agents_tool") + print(" import asyncio") + print("") + print(" async def main():") + print(" result = await mixture_of_agents_tool(") + print(" user_prompt='Solve this complex mathematical proof...'") + print(" )") + print(" print(result)") + print(" asyncio.run(main())") + + print("\nBest use cases:") + print(" - Complex mathematical proofs and calculations") + print(" - Advanced coding problems and algorithm design") + print(" - Multi-step analytical reasoning tasks") + print(" - Problems requiring diverse domain expertise") + print(" - Tasks where single models show limitations") + + print("\nPerformance characteristics:") + print(" - Higher latency due to multiple model calls") + print(" - Significantly improved quality for complex tasks") + print(" - Parallel processing for efficiency") + print(f" - Optimized temperatures: {REFERENCE_TEMPERATURE} for reference models, {AGGREGATOR_TEMPERATURE} for aggregation") + print(" - Token-efficient: only returns final aggregated response") + print(" - Resilient: continues with partial model failures") + print(" - Configurable: easy to modify models and settings at top of file") + print(" - State-of-the-art results on challenging benchmarks") + + print("\nDebug mode:") + print(" # Enable debug logging") + print(" export MOA_TOOLS_DEBUG=true") + print(" # Debug logs capture all MoA processing steps and metrics") + print(" # Logs saved to: ./logs/moa_tools_debug_UUID.json") + + +# --------------------------------------------------------------------------- +# Registry +# --------------------------------------------------------------------------- +from tools.registry import registry + +MOA_SCHEMA = { + "name": "mixture_of_agents", + "description": "Route a hard problem through multiple frontier LLMs collaboratively. Makes 5 API calls (4 reference models + 1 aggregator) with maximum reasoning effort — use sparingly for genuinely difficult problems. Best for: complex math, advanced algorithms, multi-step analytical reasoning, problems benefiting from diverse perspectives.", + "parameters": { + "type": "object", + "properties": { + "user_prompt": { + "type": "string", + "description": "The complex query or problem to solve using multiple AI models. Should be a challenging problem that benefits from diverse perspectives and collaborative reasoning." + } + }, + "required": ["user_prompt"] + } +} + +registry.register( + name="mixture_of_agents", + toolset="moa", + schema=MOA_SCHEMA, + handler=lambda args, **kw: mixture_of_agents_tool(user_prompt=args.get("user_prompt", "")), + check_fn=check_moa_requirements, + requires_env=["OPENROUTER_API_KEY"], + is_async=True, + emoji="🧠", +) diff --git a/mindcli/_vendor/tools/neutts_samples/jo.txt b/mindcli/_vendor/tools/neutts_samples/jo.txt new file mode 100644 index 0000000..6a6a43d --- /dev/null +++ b/mindcli/_vendor/tools/neutts_samples/jo.txt @@ -0,0 +1 @@ +So I just tried Neuphonic and I’m genuinely impressed. It's super responsive, it sounds clean, supports voice cloning, and the agent feature is fun to play with too. Highly recommend it for podcasts, conversations, or even just messing around with voiceovers. diff --git a/mindcli/_vendor/tools/neutts_samples/jo.wav b/mindcli/_vendor/tools/neutts_samples/jo.wav new file mode 100644 index 0000000..059b94f Binary files /dev/null and b/mindcli/_vendor/tools/neutts_samples/jo.wav differ diff --git a/mindcli/_vendor/tools/neutts_synth.py b/mindcli/_vendor/tools/neutts_synth.py new file mode 100644 index 0000000..ee2c84b --- /dev/null +++ b/mindcli/_vendor/tools/neutts_synth.py @@ -0,0 +1,104 @@ +#!/usr/bin/env python3 +"""Standalone NeuTTS synthesis helper. + +Called by tts_tool.py via subprocess to keep the TTS model (~500MB) +in a separate process that exits after synthesis — no lingering memory. + +Usage: + python -m tools.neutts_synth --text "Hello" --out output.wav \ + --ref-audio samples/jo.wav --ref-text samples/jo.txt + +Requires: python -m pip install -U neutts[all] +System: apt install espeak-ng (or brew install espeak-ng) +""" + +import argparse +import struct +import sys +from pathlib import Path + + +def _write_wav(path: str, samples, sample_rate: int = 24000) -> None: + """Write a WAV file from float32 samples (no soundfile dependency).""" + import numpy as np + + if not isinstance(samples, np.ndarray): + samples = np.array(samples, dtype=np.float32) + samples = samples.flatten() + + # Clamp and convert to int16 + samples = np.clip(samples, -1.0, 1.0) + pcm = (samples * 32767).astype(np.int16) + + num_channels = 1 + bits_per_sample = 16 + byte_rate = sample_rate * num_channels * (bits_per_sample // 8) + block_align = num_channels * (bits_per_sample // 8) + data_size = len(pcm) * (bits_per_sample // 8) + + with open(path, "wb") as f: + f.write(b"RIFF") + f.write(struct.pack(" bool: + """Check whether the OpenRouter API key is present.""" + return bool(os.getenv("OPENROUTER_API_KEY")) diff --git a/mindcli/_vendor/tools/osv_check.py b/mindcli/_vendor/tools/osv_check.py new file mode 100644 index 0000000..52458fd --- /dev/null +++ b/mindcli/_vendor/tools/osv_check.py @@ -0,0 +1,155 @@ +"""OSV malware check for MCP extension packages. + +Before launching an MCP server via npx/uvx, queries the OSV (Open Source +Vulnerabilities) API to check if the package has any known malware advisories +(MAL-* IDs). Regular CVEs are ignored — only confirmed malware is blocked. + +The API is free, public, and maintained by Google. Typical latency is ~300ms. +Fail-open: network errors allow the package to proceed. + +Inspired by Block/goose's extension malware check. +""" + +import json +import logging +import os +import re +import urllib.request +from typing import Optional, Tuple + +logger = logging.getLogger(__name__) + +_OSV_ENDPOINT = os.getenv("OSV_ENDPOINT", "https://api.osv.dev/v1/query") +_TIMEOUT = 10 # seconds + + +def check_package_for_malware( + command: str, args: list +) -> Optional[str]: + """Check if an MCP server package has known malware advisories. + + Inspects the *command* (e.g. ``npx``, ``uvx``) and *args* to infer the + package name and ecosystem. Queries the OSV API for MAL-* advisories. + + Returns: + An error message string if malware is found, or None if clean/unknown. + Returns None (allow) on network errors or unrecognized commands. + """ + ecosystem = _infer_ecosystem(command) + if not ecosystem: + return None # not npx/uvx — skip + + package, version = _parse_package_from_args(args, ecosystem) + if not package: + return None + + try: + malware = _query_osv(package, ecosystem, version) + except Exception as exc: + # Fail-open: network errors, timeouts, parse failures → allow + logger.debug("OSV check failed for %s/%s (allowing): %s", ecosystem, package, exc) + return None + + if malware: + ids = ", ".join(m["id"] for m in malware[:3]) + summaries = "; ".join( + m.get("summary", m["id"])[:100] for m in malware[:3] + ) + return ( + f"BLOCKED: Package '{package}' ({ecosystem}) has known malware " + f"advisories: {ids}. Details: {summaries}" + ) + return None + + +def _infer_ecosystem(command: str) -> Optional[str]: + """Infer package ecosystem from the command name.""" + base = os.path.basename(command).lower() + if base in ("npx", "npx.cmd"): + return "npm" + if base in ("uvx", "uvx.cmd", "pipx"): + return "PyPI" + return None + + +def _parse_package_from_args( + args: list, ecosystem: str +) -> Tuple[Optional[str], Optional[str]]: + """Extract package name and optional version from command args. + + Returns (package_name, version) or (None, None) if not parseable. + """ + if not args: + return None, None + + # Skip flags to find the package token + package_token = None + for arg in args: + if not isinstance(arg, str): + continue + if arg.startswith("-"): + continue + package_token = arg + break + + if not package_token: + return None, None + + if ecosystem == "npm": + return _parse_npm_package(package_token) + elif ecosystem == "PyPI": + return _parse_pypi_package(package_token) + return package_token, None + + +def _parse_npm_package(token: str) -> Tuple[Optional[str], Optional[str]]: + """Parse npm package: @scope/name@version or name@version.""" + if token.startswith("@"): + # Scoped: @scope/name@version + match = re.match(r"^(@[^/]+/[^@]+)(?:@(.+))?$", token) + if match: + return match.group(1), match.group(2) + return token, None + # Unscoped: name@version + if "@" in token: + parts = token.rsplit("@", 1) + name = parts[0] + version = parts[1] if len(parts) > 1 and parts[1] != "latest" else None + return name, version + return token, None + + +def _parse_pypi_package(token: str) -> Tuple[Optional[str], Optional[str]]: + """Parse PyPI package: name==version or name[extras]==version.""" + # Strip extras: name[extra1,extra2]==version + match = re.match(r"^([a-zA-Z0-9._-]+)(?:\[[^\]]*\])?(?:==(.+))?$", token) + if match: + return match.group(1), match.group(2) + return token, None + + +def _query_osv( + package: str, ecosystem: str, version: Optional[str] = None +) -> list: + """Query the OSV API for MAL-* advisories. Returns list of malware vulns.""" + payload = {"package": {"name": package, "ecosystem": ecosystem}} + if version: + payload["version"] = version + + data = json.dumps(payload).encode("utf-8") + req = urllib.request.Request( + _OSV_ENDPOINT, + data=data, + headers={ + "Content-Type": "application/json", + "User-Agent": "hermes-agent-osv-check/1.0", + }, + method="POST", + ) + + with urllib.request.urlopen(req, timeout=_TIMEOUT) as resp: + result = json.loads(resp.read()) + + vulns = result.get("vulns", []) + # Only malware advisories — ignore regular CVEs + return [v for v in vulns if v.get("id", "").startswith("MAL-")] diff --git a/mindcli/_vendor/tools/patch_parser.py b/mindcli/_vendor/tools/patch_parser.py new file mode 100644 index 0000000..0c96108 --- /dev/null +++ b/mindcli/_vendor/tools/patch_parser.py @@ -0,0 +1,580 @@ +#!/usr/bin/env python3 +""" +V4A Patch Format Parser + +Parses the V4A patch format used by codex, cline, and other coding agents. + +V4A Format: + *** Begin Patch + *** Update File: path/to/file.py + @@ optional context hint @@ + context line (space prefix) + -removed line (minus prefix) + +added line (plus prefix) + *** Add File: path/to/new.py + +new file content + +line 2 + *** Delete File: path/to/old.py + *** Move File: old/path.py -> new/path.py + *** End Patch + +Usage: + from tools.patch_parser import parse_v4a_patch, apply_v4a_operations + + operations, error = parse_v4a_patch(patch_content) + if error: + print(f"Parse error: {error}") + else: + result = apply_v4a_operations(operations, file_ops) +""" + +import difflib +import re +from dataclasses import dataclass, field +from typing import List, Optional, Tuple, Any +from enum import Enum + + +class OperationType(Enum): + ADD = "add" + UPDATE = "update" + DELETE = "delete" + MOVE = "move" + + +@dataclass +class HunkLine: + """A single line in a patch hunk.""" + prefix: str # ' ', '-', or '+' + content: str + + +@dataclass +class Hunk: + """A group of changes within a file.""" + context_hint: Optional[str] = None + lines: List[HunkLine] = field(default_factory=list) + + +@dataclass +class PatchOperation: + """A single operation in a V4A patch.""" + operation: OperationType + file_path: str + new_path: Optional[str] = None # For move operations + hunks: List[Hunk] = field(default_factory=list) + content: Optional[str] = None # For add file operations + + +def parse_v4a_patch(patch_content: str) -> Tuple[List[PatchOperation], Optional[str]]: + """ + Parse a V4A format patch. + + Args: + patch_content: The patch text in V4A format + + Returns: + Tuple of (operations, error_message) + - If successful: (list_of_operations, None) + - If failed: ([], error_description) + """ + lines = patch_content.split('\n') + operations: List[PatchOperation] = [] + + # Find patch boundaries + start_idx = None + end_idx = None + + for i, line in enumerate(lines): + if '*** Begin Patch' in line or '***Begin Patch' in line: + start_idx = i + elif '*** End Patch' in line or '***End Patch' in line: + end_idx = i + break + + if start_idx is None: + # Try to parse without explicit begin marker + start_idx = -1 + + if end_idx is None: + end_idx = len(lines) + + # Parse operations between boundaries + i = start_idx + 1 + current_op: Optional[PatchOperation] = None + current_hunk: Optional[Hunk] = None + + while i < end_idx: + line = lines[i] + + # Check for file operation markers + update_match = re.match(r'\*\*\*\s*Update\s+File:\s*(.+)', line) + add_match = re.match(r'\*\*\*\s*Add\s+File:\s*(.+)', line) + delete_match = re.match(r'\*\*\*\s*Delete\s+File:\s*(.+)', line) + move_match = re.match(r'\*\*\*\s*Move\s+File:\s*(.+?)\s*->\s*(.+)', line) + + if update_match: + # Save previous operation + if current_op: + if current_hunk and current_hunk.lines: + current_op.hunks.append(current_hunk) + operations.append(current_op) + + current_op = PatchOperation( + operation=OperationType.UPDATE, + file_path=update_match.group(1).strip() + ) + current_hunk = None + + elif add_match: + if current_op: + if current_hunk and current_hunk.lines: + current_op.hunks.append(current_hunk) + operations.append(current_op) + + current_op = PatchOperation( + operation=OperationType.ADD, + file_path=add_match.group(1).strip() + ) + current_hunk = Hunk() + + elif delete_match: + if current_op: + if current_hunk and current_hunk.lines: + current_op.hunks.append(current_hunk) + operations.append(current_op) + + current_op = PatchOperation( + operation=OperationType.DELETE, + file_path=delete_match.group(1).strip() + ) + operations.append(current_op) + current_op = None + current_hunk = None + + elif move_match: + if current_op: + if current_hunk and current_hunk.lines: + current_op.hunks.append(current_hunk) + operations.append(current_op) + + current_op = PatchOperation( + operation=OperationType.MOVE, + file_path=move_match.group(1).strip(), + new_path=move_match.group(2).strip() + ) + operations.append(current_op) + current_op = None + current_hunk = None + + elif line.startswith('@@'): + # Context hint / hunk marker + if current_op: + if current_hunk and current_hunk.lines: + current_op.hunks.append(current_hunk) + + # Extract context hint + hint_match = re.match(r'@@\s*(.+?)\s*@@', line) + hint = hint_match.group(1) if hint_match else None + current_hunk = Hunk(context_hint=hint) + + elif current_op and line: + # Parse hunk line + if current_hunk is None: + current_hunk = Hunk() + + if line.startswith('+'): + current_hunk.lines.append(HunkLine('+', line[1:])) + elif line.startswith('-'): + current_hunk.lines.append(HunkLine('-', line[1:])) + elif line.startswith(' '): + current_hunk.lines.append(HunkLine(' ', line[1:])) + elif line.startswith('\\'): + # "\ No newline at end of file" marker - skip + pass + else: + # Treat as context line (implicit space prefix) + current_hunk.lines.append(HunkLine(' ', line)) + + i += 1 + + # Don't forget the last operation + if current_op: + if current_hunk and current_hunk.lines: + current_op.hunks.append(current_hunk) + operations.append(current_op) + + # Validate the parsed result + if not operations: + # Empty patch is not an error — callers get [] and can decide + return operations, None + + parse_errors: List[str] = [] + for op in operations: + if not op.file_path: + parse_errors.append("Operation with empty file path") + if op.operation == OperationType.UPDATE and not op.hunks: + parse_errors.append(f"UPDATE {op.file_path!r}: no hunks found") + if op.operation == OperationType.MOVE and not op.new_path: + parse_errors.append(f"MOVE {op.file_path!r}: missing destination path (expected 'src -> dst')") + + if parse_errors: + return [], "Parse error: " + "; ".join(parse_errors) + + return operations, None + + +def _count_occurrences(text: str, pattern: str) -> int: + """Count non-overlapping occurrences of *pattern* in *text*.""" + count = 0 + start = 0 + while True: + pos = text.find(pattern, start) + if pos == -1: + break + count += 1 + start = pos + 1 + return count + + +def _validate_operations( + operations: List[PatchOperation], + file_ops: Any, +) -> List[str]: + """Validate all operations without writing any files. + + Returns a list of error strings; an empty list means all operations + are valid and the apply phase can proceed safely. + + For UPDATE operations, hunks are simulated in order so that later + hunks validate against post-earlier-hunk content (matching apply order). + """ + # Deferred import: breaks the patch_parser ↔ fuzzy_match circular dependency + from tools.fuzzy_match import fuzzy_find_and_replace + + errors: List[str] = [] + + for op in operations: + if op.operation == OperationType.UPDATE: + read_result = file_ops.read_file_raw(op.file_path) + if read_result.error: + errors.append(f"{op.file_path}: {read_result.error}") + continue + + simulated = read_result.content + for hunk in op.hunks: + search_lines = [l.content for l in hunk.lines if l.prefix in (' ', '-')] + if not search_lines: + # Addition-only hunk: validate context hint uniqueness + if hunk.context_hint: + occurrences = _count_occurrences(simulated, hunk.context_hint) + if occurrences == 0: + errors.append( + f"{op.file_path}: addition-only hunk context hint " + f"'{hunk.context_hint}' not found" + ) + elif occurrences > 1: + errors.append( + f"{op.file_path}: addition-only hunk context hint " + f"'{hunk.context_hint}' is ambiguous " + f"({occurrences} occurrences)" + ) + continue + + search_pattern = '\n'.join(search_lines) + replace_lines = [l.content for l in hunk.lines if l.prefix in (' ', '+')] + replacement = '\n'.join(replace_lines) + + new_simulated, count, _strategy, match_error = fuzzy_find_and_replace( + simulated, search_pattern, replacement, replace_all=False + ) + if count == 0: + label = f"'{hunk.context_hint}'" if hunk.context_hint else "(no hint)" + errors.append( + f"{op.file_path}: hunk {label} not found" + + (f" — {match_error}" if match_error else "") + ) + else: + # Advance simulation so subsequent hunks validate correctly. + # Reuse the result from the call above — no second fuzzy run. + simulated = new_simulated + + elif op.operation == OperationType.DELETE: + read_result = file_ops.read_file_raw(op.file_path) + if read_result.error: + errors.append(f"{op.file_path}: file not found for deletion") + + elif op.operation == OperationType.MOVE: + if not op.new_path: + errors.append(f"{op.file_path}: MOVE operation missing destination path") + continue + src_result = file_ops.read_file_raw(op.file_path) + if src_result.error: + errors.append(f"{op.file_path}: source file not found for move") + dst_result = file_ops.read_file_raw(op.new_path) + if not dst_result.error: + errors.append( + f"{op.new_path}: destination already exists — move would overwrite" + ) + + # ADD: parent directory creation handled by write_file; no pre-check needed. + + return errors + + +def apply_v4a_operations(operations: List[PatchOperation], + file_ops: Any) -> 'PatchResult': + """Apply V4A patch operations using a file operations interface. + + Uses a two-phase validate-then-apply approach: + - Phase 1: validate all operations against current file contents without + writing anything. If any validation error is found, return immediately + with no filesystem changes. + - Phase 2: apply all operations. A failure here (e.g. a race between + validation and apply) is reported with a note to run ``git diff``. + + Args: + operations: List of PatchOperation from parse_v4a_patch + file_ops: Object with read_file_raw, write_file methods + + Returns: + PatchResult with results of all operations + """ + # Import here to avoid circular imports + from tools.file_operations import PatchResult + + # ---- Phase 1: validate ---- + validation_errors = _validate_operations(operations, file_ops) + if validation_errors: + return PatchResult( + success=False, + error="Patch validation failed (no files were modified):\n" + + "\n".join(f" • {e}" for e in validation_errors), + ) + + # ---- Phase 2: apply ---- + files_modified = [] + files_created = [] + files_deleted = [] + all_diffs = [] + errors = [] + + for op in operations: + try: + if op.operation == OperationType.ADD: + result = _apply_add(op, file_ops) + if result[0]: + files_created.append(op.file_path) + all_diffs.append(result[1]) + else: + errors.append(f"Failed to add {op.file_path}: {result[1]}") + + elif op.operation == OperationType.DELETE: + result = _apply_delete(op, file_ops) + if result[0]: + files_deleted.append(op.file_path) + all_diffs.append(result[1]) + else: + errors.append(f"Failed to delete {op.file_path}: {result[1]}") + + elif op.operation == OperationType.MOVE: + result = _apply_move(op, file_ops) + if result[0]: + files_modified.append(f"{op.file_path} -> {op.new_path}") + all_diffs.append(result[1]) + else: + errors.append(f"Failed to move {op.file_path}: {result[1]}") + + elif op.operation == OperationType.UPDATE: + result = _apply_update(op, file_ops) + if result[0]: + files_modified.append(op.file_path) + all_diffs.append(result[1]) + else: + errors.append(f"Failed to update {op.file_path}: {result[1]}") + + except Exception as e: + errors.append(f"Error processing {op.file_path}: {str(e)}") + + # Run lint on all modified/created files + lint_results = {} + for f in files_modified + files_created: + if hasattr(file_ops, '_check_lint'): + lint_result = file_ops._check_lint(f) + lint_results[f] = lint_result.to_dict() + + combined_diff = '\n'.join(all_diffs) + + if errors: + return PatchResult( + success=False, + diff=combined_diff, + files_modified=files_modified, + files_created=files_created, + files_deleted=files_deleted, + lint=lint_results if lint_results else None, + error="Apply phase failed (state may be inconsistent — run `git diff` to assess):\n" + + "\n".join(f" • {e}" for e in errors), + ) + + return PatchResult( + success=True, + diff=combined_diff, + files_modified=files_modified, + files_created=files_created, + files_deleted=files_deleted, + lint=lint_results if lint_results else None, + ) + + +def _apply_add(op: PatchOperation, file_ops: Any) -> Tuple[bool, str]: + """Apply an add file operation.""" + # Extract content from hunks (all + lines) + content_lines = [] + for hunk in op.hunks: + for line in hunk.lines: + if line.prefix == '+': + content_lines.append(line.content) + + content = '\n'.join(content_lines) + + result = file_ops.write_file(op.file_path, content) + if result.error: + return False, result.error + + diff = f"--- /dev/null\n+++ b/{op.file_path}\n" + diff += '\n'.join(f"+{line}" for line in content_lines) + + return True, diff + + +def _apply_delete(op: PatchOperation, file_ops: Any) -> Tuple[bool, str]: + """Apply a delete file operation.""" + # Read before deleting so we can produce a real unified diff. + # Validation already confirmed existence; this guards against races. + read_result = file_ops.read_file_raw(op.file_path) + if read_result.error: + return False, f"Cannot delete {op.file_path}: file not found" + + result = file_ops.delete_file(op.file_path) + if result.error: + return False, result.error + + removed_lines = read_result.content.splitlines(keepends=True) + diff = ''.join(difflib.unified_diff( + removed_lines, [], + fromfile=f"a/{op.file_path}", + tofile="/dev/null", + )) + return True, diff or f"# Deleted: {op.file_path}" + + +def _apply_move(op: PatchOperation, file_ops: Any) -> Tuple[bool, str]: + """Apply a move file operation.""" + result = file_ops.move_file(op.file_path, op.new_path) + if result.error: + return False, result.error + + diff = f"# Moved: {op.file_path} -> {op.new_path}" + return True, diff + + +def _apply_update(op: PatchOperation, file_ops: Any) -> Tuple[bool, str]: + """Apply an update file operation.""" + # Deferred import: breaks the patch_parser ↔ fuzzy_match circular dependency + from tools.fuzzy_match import fuzzy_find_and_replace + + # Read current content — raw so no line-number prefixes or per-line truncation + read_result = file_ops.read_file_raw(op.file_path) + + if read_result.error: + return False, f"Cannot read file: {read_result.error}" + + current_content = read_result.content + + # Apply each hunk + new_content = current_content + + for hunk in op.hunks: + # Build search pattern from context and removed lines + search_lines = [] + replace_lines = [] + + for line in hunk.lines: + if line.prefix == ' ': + search_lines.append(line.content) + replace_lines.append(line.content) + elif line.prefix == '-': + search_lines.append(line.content) + elif line.prefix == '+': + replace_lines.append(line.content) + + if search_lines: + search_pattern = '\n'.join(search_lines) + replacement = '\n'.join(replace_lines) + + new_content, count, _strategy, error = fuzzy_find_and_replace( + new_content, search_pattern, replacement, replace_all=False + ) + + if error and count == 0: + # Try with context hint if available + if hunk.context_hint: + # Find the context hint location and search nearby + hint_pos = new_content.find(hunk.context_hint) + if hint_pos != -1: + # Search in a window around the hint + window_start = max(0, hint_pos - 500) + window_end = min(len(new_content), hint_pos + 2000) + window = new_content[window_start:window_end] + + window_new, count, _strategy, error = fuzzy_find_and_replace( + window, search_pattern, replacement, replace_all=False + ) + + if count > 0: + new_content = new_content[:window_start] + window_new + new_content[window_end:] + error = None + + if error: + return False, f"Could not apply hunk: {error}" + else: + # Addition-only hunk (no context or removed lines). + # Insert at the location indicated by the context hint, or at end of file. + insert_text = '\n'.join(replace_lines) + if hunk.context_hint: + occurrences = _count_occurrences(new_content, hunk.context_hint) + if occurrences == 0: + # Hint not found — append at end as a safe fallback + new_content = new_content.rstrip('\n') + '\n' + insert_text + '\n' + elif occurrences > 1: + return False, ( + f"Addition-only hunk: context hint '{hunk.context_hint}' is ambiguous " + f"({occurrences} occurrences) — provide a more unique hint" + ) + else: + hint_pos = new_content.find(hunk.context_hint) + # Insert after the line containing the context hint + eol = new_content.find('\n', hint_pos) + if eol != -1: + new_content = new_content[:eol + 1] + insert_text + '\n' + new_content[eol + 1:] + else: + new_content = new_content + '\n' + insert_text + else: + new_content = new_content.rstrip('\n') + '\n' + insert_text + '\n' + + # Write new content + write_result = file_ops.write_file(op.file_path, new_content) + if write_result.error: + return False, write_result.error + + # Generate diff + diff_lines = difflib.unified_diff( + current_content.splitlines(keepends=True), + new_content.splitlines(keepends=True), + fromfile=f"a/{op.file_path}", + tofile=f"b/{op.file_path}" + ) + diff = ''.join(diff_lines) + + return True, diff diff --git a/mindcli/_vendor/tools/path_security.py b/mindcli/_vendor/tools/path_security.py new file mode 100644 index 0000000..828011e --- /dev/null +++ b/mindcli/_vendor/tools/path_security.py @@ -0,0 +1,43 @@ +"""Shared path validation helpers for tool implementations. + +Extracts the ``resolve() + relative_to()`` and ``..`` traversal check +patterns previously duplicated across skill_manager_tool, skills_tool, +skills_hub, cronjob_tools, and credential_files. +""" + +import logging +from pathlib import Path +from typing import Optional + +logger = logging.getLogger(__name__) + + +def validate_within_dir(path: Path, root: Path) -> Optional[str]: + """Ensure *path* resolves to a location within *root*. + + Returns an error message string if validation fails, or ``None`` if the + path is safe. Uses ``Path.resolve()`` to follow symlinks and normalize + ``..`` components. + + Usage:: + + error = validate_within_dir(user_path, allowed_root) + if error: + return json.dumps({"error": error}) + """ + try: + resolved = path.resolve() + root_resolved = root.resolve() + resolved.relative_to(root_resolved) + except (ValueError, OSError) as exc: + return f"Path escapes allowed directory: {exc}" + return None + + +def has_traversal_component(path_str: str) -> bool: + """Return True if *path_str* contains ``..`` traversal components. + + Quick check for obvious traversal attempts before doing full resolution. + """ + parts = Path(path_str).parts + return ".." in parts diff --git a/mindcli/_vendor/tools/process_registry.py b/mindcli/_vendor/tools/process_registry.py new file mode 100644 index 0000000..a5dbc3b --- /dev/null +++ b/mindcli/_vendor/tools/process_registry.py @@ -0,0 +1,1172 @@ +""" +Process Registry -- In-memory registry for managed background processes. + +Tracks processes spawned via terminal(background=true), providing: + - Output buffering (rolling 200KB window) + - Status polling and log retrieval + - Blocking wait with interrupt support + - Process killing + - Crash recovery via JSON checkpoint file + - Session-scoped tracking for gateway reset protection + +Background processes execute THROUGH the environment interface -- nothing +runs on the host machine unless TERMINAL_ENV=local. For Docker, Singularity, +Modal, Daytona, and SSH backends, the command runs inside the sandbox. + +Usage: + from tools.process_registry import process_registry + + # Spawn a background process (called from terminal_tool) + session = process_registry.spawn(env, "pytest -v", task_id="task_123") + + # Poll for status + result = process_registry.poll(session.id) + + # Block until done + result = process_registry.wait(session.id, timeout=300) + + # Kill it + process_registry.kill(session.id) +""" + +import json +import logging +import os +import platform +import shlex +import signal +import subprocess +import threading +import time +import uuid + +_IS_WINDOWS = platform.system() == "Windows" +from tools.environments.local import _find_shell, _sanitize_subprocess_env +from dataclasses import dataclass, field +from typing import Any, Dict, List, Optional + +from hermes_cli.config import get_hermes_home + +logger = logging.getLogger(__name__) + + +# Checkpoint file for crash recovery (gateway only) +CHECKPOINT_PATH = get_hermes_home() / "processes.json" + +# Limits +MAX_OUTPUT_CHARS = 200_000 # 200KB rolling output buffer +FINISHED_TTL_SECONDS = 1800 # Keep finished processes for 30 minutes +MAX_PROCESSES = 64 # Max concurrent tracked processes (LRU pruning) + +# Watch pattern rate limiting +WATCH_MAX_PER_WINDOW = 8 # Max notifications delivered per window +WATCH_WINDOW_SECONDS = 10 # Rolling window length +WATCH_OVERLOAD_KILL_SECONDS = 45 # Sustained overload duration before disabling watch + + +@dataclass +class ProcessSession: + """A tracked background process with output buffering.""" + id: str # Unique session ID ("proc_xxxxxxxxxxxx") + command: str # Original command string + task_id: str = "" # Task/sandbox isolation key + session_key: str = "" # Gateway session key (for reset protection) + pid: Optional[int] = None # OS process ID + process: Optional[subprocess.Popen] = None # Popen handle (local only) + env_ref: Any = None # Reference to the environment object + cwd: Optional[str] = None # Working directory + started_at: float = 0.0 # time.time() of spawn + exited: bool = False # Whether the process has finished + exit_code: Optional[int] = None # Exit code (None if still running) + output_buffer: str = "" # Rolling output (last MAX_OUTPUT_CHARS) + max_output_chars: int = MAX_OUTPUT_CHARS + detached: bool = False # True if recovered from crash (no pipe) + pid_scope: str = "host" # "host" for local/PTY PIDs, "sandbox" for env-local PIDs + # Watcher/notification metadata (persisted for crash recovery) + watcher_platform: str = "" + watcher_chat_id: str = "" + watcher_user_id: str = "" + watcher_user_name: str = "" + watcher_thread_id: str = "" + watcher_interval: int = 0 # 0 = no watcher configured + notify_on_complete: bool = False # Queue agent notification on exit + # Watch patterns — trigger agent notification when output matches any pattern + watch_patterns: List[str] = field(default_factory=list) + _watch_hits: int = field(default=0, repr=False) # total matches delivered + _watch_suppressed: int = field(default=0, repr=False) # matches dropped by rate limit + _watch_overload_since: float = field(default=0.0, repr=False) # when sustained overload began + _watch_disabled: bool = field(default=False, repr=False) # permanently killed by overload + _watch_window_hits: int = field(default=0, repr=False) # hits in current rate window + _watch_window_start: float = field(default=0.0, repr=False) + _lock: threading.Lock = field(default_factory=threading.Lock) + _reader_thread: Optional[threading.Thread] = field(default=None, repr=False) + _pty: Any = field(default=None, repr=False) # ptyprocess handle (when use_pty=True) + + +class ProcessRegistry: + """ + In-memory registry of running and finished background processes. + + Thread-safe. Accessed from: + - Executor threads (terminal_tool, process tool handlers) + - Gateway asyncio loop (watcher tasks, session reset checks) + - Cleanup thread (sandbox reaping coordination) + """ + + _SHELL_NOISE_SUBSTRINGS = ( + "bash: cannot set terminal process group", + "bash: no job control in this shell", + "no job control in this shell", + "cannot set terminal process group", + "tcsetattr: Inappropriate ioctl for device", + ) + + def __init__(self): + self._running: Dict[str, ProcessSession] = {} + self._finished: Dict[str, ProcessSession] = {} + self._lock = threading.Lock() + + # Side-channel for check_interval watchers (gateway reads after agent run) + self.pending_watchers: List[Dict[str, Any]] = [] + + # Notification queue — unified queue for all background process events. + # Completion notifications (notify_on_complete) and watch pattern matches + # both land here, distinguished by "type" field. CLI process_loop and + # gateway drain this after each agent turn to auto-trigger new turns. + import queue as _queue_mod + self.completion_queue: _queue_mod.Queue = _queue_mod.Queue() + + # Track sessions whose completion was already consumed by the agent + # via wait/poll/log. Drain loops skip notifications for these. + self._completion_consumed: set = set() + + @staticmethod + def _clean_shell_noise(text: str) -> str: + """Strip shell startup warnings from the beginning of output.""" + lines = text.split("\n") + while lines and any(noise in lines[0] for noise in ProcessRegistry._SHELL_NOISE_SUBSTRINGS): + lines.pop(0) + return "\n".join(lines) + + def _check_watch_patterns(self, session: ProcessSession, new_text: str) -> None: + """Scan new output for watch patterns and queue notifications. + + Called from reader threads with new_text being the freshly-read chunk. + Rate-limited: max WATCH_MAX_PER_WINDOW notifications per WATCH_WINDOW_SECONDS. + If sustained overload exceeds WATCH_OVERLOAD_KILL_SECONDS, watching is + disabled permanently for this process. + """ + if not session.watch_patterns or session._watch_disabled: + return + + # Scan new text line-by-line for pattern matches + matched_lines = [] + matched_pattern = None + for line in new_text.splitlines(): + for pat in session.watch_patterns: + if pat in line: + matched_lines.append(line.rstrip()) + if matched_pattern is None: + matched_pattern = pat + break # one match per line is enough + + if not matched_lines: + return + + now = time.time() + with session._lock: + # Reset window if it's expired + if now - session._watch_window_start >= WATCH_WINDOW_SECONDS: + session._watch_window_hits = 0 + session._watch_window_start = now + + # Check rate limit + if session._watch_window_hits >= WATCH_MAX_PER_WINDOW: + session._watch_suppressed += len(matched_lines) + + # Track sustained overload for kill switch + if session._watch_overload_since == 0.0: + session._watch_overload_since = now + elif now - session._watch_overload_since > WATCH_OVERLOAD_KILL_SECONDS: + session._watch_disabled = True + self.completion_queue.put({ + "session_id": session.id, + "command": session.command, + "type": "watch_disabled", + "suppressed": session._watch_suppressed, + "message": ( + f"Watch patterns disabled for process {session.id} — " + f"too many matches ({session._watch_suppressed} suppressed). " + f"Use process(action='poll') to check output manually." + ), + }) + return + + # Under the rate limit — deliver notification + session._watch_window_hits += 1 + session._watch_hits += 1 + # Clear overload tracker since we got a delivery through + session._watch_overload_since = 0.0 + + # Include suppressed count if any events were dropped + suppressed = session._watch_suppressed + session._watch_suppressed = 0 + + # Trim matched output to a reasonable size + output = "\n".join(matched_lines[:20]) + if len(output) > 2000: + output = output[:2000] + "\n...(truncated)" + + self.completion_queue.put({ + "session_id": session.id, + "command": session.command, + "type": "watch_match", + "pattern": matched_pattern, + "output": output, + "suppressed": suppressed, + }) + + @staticmethod + def _is_host_pid_alive(pid: Optional[int]) -> bool: + """Best-effort liveness check for host-visible PIDs.""" + if not pid: + return False + try: + os.kill(pid, 0) + return True + except (ProcessLookupError, PermissionError): + return False + + def _refresh_detached_session(self, session: Optional[ProcessSession]) -> Optional[ProcessSession]: + """Update recovered host-PID sessions when the underlying process has exited.""" + if session is None or session.exited or not session.detached or session.pid_scope != "host": + return session + + if self._is_host_pid_alive(session.pid): + return session + + with session._lock: + if session.exited: + return session + session.exited = True + # Recovered sessions no longer have a waitable handle, so the real + # exit code is unavailable once the original process object is gone. + session.exit_code = None + + self._move_to_finished(session) + return session + + @staticmethod + def _terminate_host_pid(pid: int) -> None: + """Terminate a host-visible PID without requiring the original process handle.""" + if _IS_WINDOWS: + os.kill(pid, signal.SIGTERM) + return + + try: + os.killpg(os.getpgid(pid), signal.SIGTERM) + except (OSError, ProcessLookupError, PermissionError): + os.kill(pid, signal.SIGTERM) + + # ----- Spawn ----- + + @staticmethod + def _env_temp_dir(env: Any) -> str: + """Return the writable sandbox temp dir for env-backed background tasks.""" + get_temp_dir = getattr(env, "get_temp_dir", None) + if callable(get_temp_dir): + try: + temp_dir = get_temp_dir() + if isinstance(temp_dir, str) and temp_dir.startswith("/"): + return temp_dir.rstrip("/") or "/" + except Exception as exc: + logger.debug("Could not resolve environment temp dir: %s", exc) + return "/tmp" + + def spawn_local( + self, + command: str, + cwd: str = None, + task_id: str = "", + session_key: str = "", + env_vars: dict = None, + use_pty: bool = False, + ) -> ProcessSession: + """ + Spawn a background process locally. + + Only for TERMINAL_ENV=local. Other backends use spawn_via_env(). + + Args: + use_pty: If True, use a pseudo-terminal via ptyprocess for interactive + CLI tools (Codex, Claude Code, Python REPL). Falls back to + subprocess.Popen if ptyprocess is not installed. + """ + session = ProcessSession( + id=f"proc_{uuid.uuid4().hex[:12]}", + command=command, + task_id=task_id, + session_key=session_key, + cwd=cwd or os.getcwd(), + started_at=time.time(), + ) + + if use_pty: + # Try PTY mode for interactive CLI tools + try: + if _IS_WINDOWS: + from winpty import PtyProcess as _PtyProcessCls + else: + from ptyprocess import PtyProcess as _PtyProcessCls + user_shell = _find_shell() + pty_env = _sanitize_subprocess_env(os.environ, env_vars) + pty_env["PYTHONUNBUFFERED"] = "1" + pty_proc = _PtyProcessCls.spawn( + [user_shell, "-lic", command], + cwd=session.cwd, + env=pty_env, + dimensions=(30, 120), + ) + session.pid = pty_proc.pid + # Store the pty handle on the session for read/write + session._pty = pty_proc + + # PTY reader thread + reader = threading.Thread( + target=self._pty_reader_loop, + args=(session,), + daemon=True, + name=f"proc-pty-reader-{session.id}", + ) + session._reader_thread = reader + reader.start() + + with self._lock: + self._prune_if_needed() + self._running[session.id] = session + + self._write_checkpoint() + return session + + except ImportError: + logger.warning("ptyprocess not installed, falling back to pipe mode") + except Exception as e: + logger.warning("PTY spawn failed (%s), falling back to pipe mode", e) + + # Standard Popen path (non-PTY or PTY fallback) + # Use the user's login shell for consistency with LocalEnvironment -- + # ensures rc files are sourced and user tools are available. + user_shell = _find_shell() + # Force unbuffered output for Python scripts so progress is visible + # during background execution (libraries like tqdm/datasets buffer when + # stdout is a pipe, hiding output from process(action="poll")). + bg_env = _sanitize_subprocess_env(os.environ, env_vars) + bg_env["PYTHONUNBUFFERED"] = "1" + proc = subprocess.Popen( + [user_shell, "-lic", command], + text=True, + cwd=session.cwd, + env=bg_env, + encoding="utf-8", + errors="replace", + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + stdin=subprocess.PIPE, + preexec_fn=None if _IS_WINDOWS else os.setsid, + ) + + session.process = proc + session.pid = proc.pid + + # Start output reader thread + reader = threading.Thread( + target=self._reader_loop, + args=(session,), + daemon=True, + name=f"proc-reader-{session.id}", + ) + session._reader_thread = reader + reader.start() + + with self._lock: + self._prune_if_needed() + self._running[session.id] = session + + self._write_checkpoint() + return session + + def spawn_via_env( + self, + env: Any, + command: str, + cwd: str = None, + task_id: str = "", + session_key: str = "", + timeout: int = 10, + ) -> ProcessSession: + """ + Spawn a background process through a non-local environment backend. + + For Docker/Singularity/Modal/Daytona/SSH: runs the command inside the sandbox + using the environment's execute() interface. We wrap the command to + capture the in-sandbox PID and redirect output to a log file inside + the sandbox, then poll the log via subsequent execute() calls. + + This is less capable than local spawn (no live stdout pipe, no stdin), + but it ensures the command runs in the correct sandbox context. + """ + session = ProcessSession( + id=f"proc_{uuid.uuid4().hex[:12]}", + command=command, + task_id=task_id, + session_key=session_key, + cwd=cwd, + started_at=time.time(), + env_ref=env, + pid_scope="sandbox", + ) + + # Run the command in the sandbox with output capture + temp_dir = self._env_temp_dir(env) + log_path = f"{temp_dir}/hermes_bg_{session.id}.log" + pid_path = f"{temp_dir}/hermes_bg_{session.id}.pid" + exit_path = f"{temp_dir}/hermes_bg_{session.id}.exit" + quoted_command = shlex.quote(command) + quoted_temp_dir = shlex.quote(temp_dir) + quoted_log_path = shlex.quote(log_path) + quoted_pid_path = shlex.quote(pid_path) + quoted_exit_path = shlex.quote(exit_path) + bg_command = ( + f"mkdir -p {quoted_temp_dir} && " + f"( nohup bash -lc {quoted_command} > {quoted_log_path} 2>&1; " + f"rc=$?; printf '%s\\n' \"$rc\" > {quoted_exit_path} ) & " + f"echo $! > {quoted_pid_path} && cat {quoted_pid_path}" + ) + + try: + result = env.execute(bg_command, timeout=timeout) + output = result.get("output", "").strip() + # Try to extract the PID from the output + for line in output.splitlines(): + line = line.strip() + if line.isdigit(): + session.pid = int(line) + break + except Exception as e: + session.exited = True + session.exit_code = -1 + session.output_buffer = f"Failed to start: {e}" + + if not session.exited: + # Start a poller thread that periodically reads the log file + reader = threading.Thread( + target=self._env_poller_loop, + args=(session, env, log_path, pid_path, exit_path), + daemon=True, + name=f"proc-poller-{session.id}", + ) + session._reader_thread = reader + reader.start() + + with self._lock: + self._prune_if_needed() + self._running[session.id] = session + + self._write_checkpoint() + return session + + # ----- Reader / Poller Threads ----- + + def _reader_loop(self, session: ProcessSession): + """Background thread: read stdout from a local Popen process.""" + first_chunk = True + try: + while True: + chunk = session.process.stdout.read(4096) + if not chunk: + break + if first_chunk: + chunk = self._clean_shell_noise(chunk) + first_chunk = False + with session._lock: + session.output_buffer += chunk + if len(session.output_buffer) > session.max_output_chars: + session.output_buffer = session.output_buffer[-session.max_output_chars:] + self._check_watch_patterns(session, chunk) + except Exception as e: + logger.debug("Process stdout reader ended: %s", e) + finally: + # Always reap the child to prevent zombie processes. + try: + session.process.wait(timeout=5) + except Exception as e: + logger.debug("Process wait timed out or failed: %s", e) + session.exited = True + session.exit_code = session.process.returncode + self._move_to_finished(session) + + def _env_poller_loop( + self, session: ProcessSession, env: Any, log_path: str, pid_path: str, exit_path: str + ): + """Background thread: poll a sandbox log file for non-local backends.""" + quoted_log_path = shlex.quote(log_path) + quoted_pid_path = shlex.quote(pid_path) + quoted_exit_path = shlex.quote(exit_path) + prev_output_len = 0 # track delta for watch pattern scanning + while not session.exited: + time.sleep(2) # Poll every 2 seconds + try: + # Read new output from the log file + result = env.execute(f"cat {quoted_log_path} 2>/dev/null", timeout=10) + new_output = result.get("output", "") + if new_output: + # Compute delta for watch pattern scanning + delta = new_output[prev_output_len:] if len(new_output) > prev_output_len else "" + prev_output_len = len(new_output) + with session._lock: + session.output_buffer = new_output + if len(session.output_buffer) > session.max_output_chars: + session.output_buffer = session.output_buffer[-session.max_output_chars:] + if delta: + self._check_watch_patterns(session, delta) + + # Check if process is still running + check = env.execute( + f"kill -0 \"$(cat {quoted_pid_path} 2>/dev/null)\" 2>/dev/null; echo $?", + timeout=5, + ) + check_output = check.get("output", "").strip() + if check_output and check_output.splitlines()[-1].strip() != "0": + # Process has exited -- get exit code captured by the wrapper shell. + exit_result = env.execute( + f"cat {quoted_exit_path} 2>/dev/null", + timeout=5, + ) + exit_str = exit_result.get("output", "").strip() + try: + session.exit_code = int(exit_str.splitlines()[-1].strip()) + except (ValueError, IndexError): + session.exit_code = -1 + session.exited = True + self._move_to_finished(session) + return + + except Exception: + # Environment might be gone (sandbox reaped, etc.) + session.exited = True + session.exit_code = -1 + self._move_to_finished(session) + return + + def _pty_reader_loop(self, session: ProcessSession): + """Background thread: read output from a PTY process.""" + pty = session._pty + try: + while pty.isalive(): + try: + chunk = pty.read(4096) + if chunk: + # ptyprocess returns bytes + text = chunk if isinstance(chunk, str) else chunk.decode("utf-8", errors="replace") + with session._lock: + session.output_buffer += text + if len(session.output_buffer) > session.max_output_chars: + session.output_buffer = session.output_buffer[-session.max_output_chars:] + self._check_watch_patterns(session, text) + except EOFError: + break + except Exception: + break + except Exception as e: + logger.debug("PTY stdout reader ended: %s", e) + + # Process exited + try: + pty.wait() + except Exception as e: + logger.debug("PTY wait timed out or failed: %s", e) + session.exited = True + session.exit_code = pty.exitstatus if hasattr(pty, 'exitstatus') else -1 + self._move_to_finished(session) + + def _move_to_finished(self, session: ProcessSession): + """Move a session from running to finished. + + Idempotent: if the session was already moved (e.g. kill_process raced + with the reader thread), the second call is a no-op — no duplicate + completion notification is enqueued. + """ + with self._lock: + was_running = self._running.pop(session.id, None) is not None + self._finished[session.id] = session + self._write_checkpoint() + + # Only enqueue completion notification on the FIRST move. Without + # this guard, kill_process() and the reader thread can both call + # _move_to_finished(), producing duplicate [SYSTEM: ...] messages. + if was_running and session.notify_on_complete: + from tools.ansi_strip import strip_ansi + output_tail = strip_ansi(session.output_buffer[-2000:]) if session.output_buffer else "" + self.completion_queue.put({ + "type": "completion", + "session_id": session.id, + "command": session.command, + "exit_code": session.exit_code, + "output": output_tail, + }) + + # ----- Query Methods ----- + + def is_completion_consumed(self, session_id: str) -> bool: + """Check if a completion notification was already consumed via wait/poll/log.""" + return session_id in self._completion_consumed + + def get(self, session_id: str) -> Optional[ProcessSession]: + """Get a session by ID (running or finished).""" + with self._lock: + session = self._running.get(session_id) or self._finished.get(session_id) + return self._refresh_detached_session(session) + + def poll(self, session_id: str) -> dict: + """Check status and get new output for a background process.""" + from tools.ansi_strip import strip_ansi + + session = self.get(session_id) + if session is None: + return {"status": "not_found", "error": f"No process with ID {session_id}"} + + with session._lock: + output_preview = strip_ansi(session.output_buffer[-1000:]) if session.output_buffer else "" + + result = { + "session_id": session.id, + "command": session.command, + "status": "exited" if session.exited else "running", + "pid": session.pid, + "uptime_seconds": int(time.time() - session.started_at), + "output_preview": output_preview, + } + if session.exited: + result["exit_code"] = session.exit_code + self._completion_consumed.add(session_id) + if session.detached: + result["detached"] = True + result["note"] = "Process recovered after restart -- output history unavailable" + return result + + def read_log(self, session_id: str, offset: int = 0, limit: int = 200) -> dict: + """Read the full output log with optional pagination by lines.""" + from tools.ansi_strip import strip_ansi + + session = self.get(session_id) + if session is None: + return {"status": "not_found", "error": f"No process with ID {session_id}"} + + with session._lock: + full_output = strip_ansi(session.output_buffer) + + lines = full_output.splitlines() + total_lines = len(lines) + + # Default: last N lines + if offset == 0 and limit > 0: + selected = lines[-limit:] + else: + selected = lines[offset:offset + limit] + + result = { + "session_id": session.id, + "status": "exited" if session.exited else "running", + "output": "\n".join(selected), + "total_lines": total_lines, + "showing": f"{len(selected)} lines", + } + if session.exited: + self._completion_consumed.add(session_id) + return result + + def wait(self, session_id: str, timeout: int = None) -> dict: + """ + Block until a process exits, timeout, or interrupt. + + Args: + session_id: The process to wait for. + timeout: Max seconds to block. Falls back to TERMINAL_TIMEOUT config. + + Returns: + dict with status ("exited", "timeout", "interrupted", "not_found") + and output snapshot. + """ + from tools.ansi_strip import strip_ansi + from tools.interrupt import is_interrupted as _is_interrupted + + try: + default_timeout = int(os.getenv("TERMINAL_TIMEOUT", "180")) + except (ValueError, TypeError): + default_timeout = 180 + max_timeout = default_timeout + requested_timeout = timeout + timeout_note = None + + if requested_timeout and requested_timeout > max_timeout: + effective_timeout = max_timeout + timeout_note = ( + f"Requested wait of {requested_timeout}s was clamped " + f"to configured limit of {max_timeout}s" + ) + else: + effective_timeout = requested_timeout or max_timeout + + session = self.get(session_id) + if session is None: + return {"status": "not_found", "error": f"No process with ID {session_id}"} + + deadline = time.monotonic() + effective_timeout + + while time.monotonic() < deadline: + session = self._refresh_detached_session(session) + if session.exited: + self._completion_consumed.add(session_id) + result = { + "status": "exited", + "exit_code": session.exit_code, + "output": strip_ansi(session.output_buffer[-2000:]), + } + if timeout_note: + result["timeout_note"] = timeout_note + return result + + if _is_interrupted(): + result = { + "status": "interrupted", + "output": strip_ansi(session.output_buffer[-1000:]), + "note": "User sent a new message -- wait interrupted", + } + if timeout_note: + result["timeout_note"] = timeout_note + return result + + time.sleep(1) + + result = { + "status": "timeout", + "output": strip_ansi(session.output_buffer[-1000:]), + } + if timeout_note: + result["timeout_note"] = timeout_note + else: + result["timeout_note"] = f"Waited {effective_timeout}s, process still running" + return result + + def kill_process(self, session_id: str) -> dict: + """Kill a background process.""" + session = self.get(session_id) + if session is None: + return {"status": "not_found", "error": f"No process with ID {session_id}"} + + if session.exited: + return { + "status": "already_exited", + "exit_code": session.exit_code, + } + + # Kill via PTY, Popen (local), or env execute (non-local) + try: + if session._pty: + # PTY process -- terminate via ptyprocess + try: + session._pty.terminate(force=True) + except Exception: + if session.pid: + os.kill(session.pid, signal.SIGTERM) + elif session.process: + # Local process -- kill the process group + try: + if _IS_WINDOWS: + session.process.terminate() + else: + os.killpg(os.getpgid(session.process.pid), signal.SIGTERM) + except (ProcessLookupError, PermissionError): + session.process.kill() + elif session.env_ref and session.pid: + # Non-local -- kill inside sandbox + session.env_ref.execute(f"kill {session.pid} 2>/dev/null", timeout=5) + elif session.detached and session.pid_scope == "host" and session.pid: + if not self._is_host_pid_alive(session.pid): + with session._lock: + session.exited = True + session.exit_code = None + self._move_to_finished(session) + return { + "status": "already_exited", + "exit_code": session.exit_code, + } + self._terminate_host_pid(session.pid) + else: + return { + "status": "error", + "error": ( + "Recovered process cannot be killed after restart because " + "its original runtime handle is no longer available" + ), + } + session.exited = True + session.exit_code = -15 # SIGTERM + self._move_to_finished(session) + self._write_checkpoint() + return {"status": "killed", "session_id": session.id} + except Exception as e: + return {"status": "error", "error": str(e)} + + def write_stdin(self, session_id: str, data: str) -> dict: + """Send raw data to a running process's stdin (no newline appended).""" + session = self.get(session_id) + if session is None: + return {"status": "not_found", "error": f"No process with ID {session_id}"} + if session.exited: + return {"status": "already_exited", "error": "Process has already finished"} + + # PTY mode -- write through pty handle (expects bytes) + if hasattr(session, '_pty') and session._pty: + try: + pty_data = data.encode("utf-8") if isinstance(data, str) else data + session._pty.write(pty_data) + return {"status": "ok", "bytes_written": len(data)} + except Exception as e: + return {"status": "error", "error": str(e)} + + # Popen mode -- write through stdin pipe + if not session.process or not session.process.stdin: + return {"status": "error", "error": "Process stdin not available (non-local backend or stdin closed)"} + try: + session.process.stdin.write(data) + session.process.stdin.flush() + return {"status": "ok", "bytes_written": len(data)} + except Exception as e: + return {"status": "error", "error": str(e)} + + def submit_stdin(self, session_id: str, data: str = "") -> dict: + """Send data + newline to a running process's stdin (like pressing Enter).""" + return self.write_stdin(session_id, data + "\n") + + def close_stdin(self, session_id: str) -> dict: + """Close a running process's stdin / send EOF without killing the process.""" + session = self.get(session_id) + if session is None: + return {"status": "not_found", "error": f"No process with ID {session_id}"} + if session.exited: + return {"status": "already_exited", "error": "Process has already finished"} + + if hasattr(session, '_pty') and session._pty: + try: + session._pty.sendeof() + return {"status": "ok", "message": "EOF sent"} + except Exception as e: + return {"status": "error", "error": str(e)} + + if not session.process or not session.process.stdin: + return {"status": "error", "error": "Process stdin not available (non-local backend or stdin closed)"} + try: + session.process.stdin.close() + return {"status": "ok", "message": "stdin closed"} + except Exception as e: + return {"status": "error", "error": str(e)} + + def list_sessions(self, task_id: str = None) -> list: + """List all running and recently-finished processes.""" + with self._lock: + all_sessions = list(self._running.values()) + list(self._finished.values()) + + all_sessions = [self._refresh_detached_session(s) for s in all_sessions] + + if task_id: + all_sessions = [s for s in all_sessions if s.task_id == task_id] + + result = [] + for s in all_sessions: + entry = { + "session_id": s.id, + "command": s.command[:200], + "cwd": s.cwd, + "pid": s.pid, + "started_at": time.strftime("%Y-%m-%dT%H:%M:%S", time.localtime(s.started_at)), + "uptime_seconds": int(time.time() - s.started_at), + "status": "exited" if s.exited else "running", + "output_preview": s.output_buffer[-200:] if s.output_buffer else "", + } + if s.exited: + entry["exit_code"] = s.exit_code + if s.detached: + entry["detached"] = True + result.append(entry) + return result + + # ----- Session/Task Queries (for gateway integration) ----- + + def has_active_processes(self, task_id: str) -> bool: + """Check if there are active (running) processes for a task_id.""" + with self._lock: + sessions = list(self._running.values()) + + for session in sessions: + self._refresh_detached_session(session) + + with self._lock: + return any( + s.task_id == task_id and not s.exited + for s in self._running.values() + ) + + def has_active_for_session(self, session_key: str) -> bool: + """Check if there are active processes for a gateway session key.""" + with self._lock: + sessions = list(self._running.values()) + + for session in sessions: + self._refresh_detached_session(session) + + with self._lock: + return any( + s.session_key == session_key and not s.exited + for s in self._running.values() + ) + + def kill_all(self, task_id: str = None) -> int: + """Kill all running processes, optionally filtered by task_id. Returns count killed.""" + with self._lock: + targets = [ + s for s in self._running.values() + if (task_id is None or s.task_id == task_id) and not s.exited + ] + + killed = 0 + for session in targets: + result = self.kill_process(session.id) + if result.get("status") in ("killed", "already_exited"): + killed += 1 + return killed + + # ----- Cleanup / Pruning ----- + + def _prune_if_needed(self): + """Remove oldest finished sessions if over MAX_PROCESSES. Must hold _lock.""" + # First prune expired finished sessions + now = time.time() + expired = [ + sid for sid, s in self._finished.items() + if (now - s.started_at) > FINISHED_TTL_SECONDS + ] + for sid in expired: + del self._finished[sid] + + # If still over limit, remove oldest finished + total = len(self._running) + len(self._finished) + if total >= MAX_PROCESSES and self._finished: + oldest_id = min(self._finished, key=lambda sid: self._finished[sid].started_at) + del self._finished[oldest_id] + + # ----- Checkpoint (crash recovery) ----- + + def _write_checkpoint(self): + """Write running process metadata to checkpoint file atomically.""" + try: + with self._lock: + entries = [] + for s in self._running.values(): + if not s.exited: + entries.append({ + "session_id": s.id, + "command": s.command, + "pid": s.pid, + "pid_scope": s.pid_scope, + "cwd": s.cwd, + "started_at": s.started_at, + "task_id": s.task_id, + "session_key": s.session_key, + "watcher_platform": s.watcher_platform, + "watcher_chat_id": s.watcher_chat_id, + "watcher_user_id": s.watcher_user_id, + "watcher_user_name": s.watcher_user_name, + "watcher_thread_id": s.watcher_thread_id, + "watcher_interval": s.watcher_interval, + "notify_on_complete": s.notify_on_complete, + "watch_patterns": s.watch_patterns, + }) + + # Atomic write to avoid corruption on crash + from utils import atomic_json_write + atomic_json_write(CHECKPOINT_PATH, entries) + except Exception as e: + logger.debug("Failed to write checkpoint file: %s", e, exc_info=True) + + def recover_from_checkpoint(self) -> int: + """ + On gateway startup, probe PIDs from checkpoint file. + + Returns the number of processes recovered as detached. + """ + if not CHECKPOINT_PATH.exists(): + return 0 + + try: + entries = json.loads(CHECKPOINT_PATH.read_text(encoding="utf-8")) + except Exception: + return 0 + + recovered = 0 + for entry in entries: + pid = entry.get("pid") + if not pid: + continue + + pid_scope = entry.get("pid_scope", "host") + if pid_scope != "host": + # Sandbox-backed processes keep only in-sandbox PIDs in the + # checkpoint, which are not meaningful to the restarted host + # process once the original environment handle is gone. + logger.info( + "Skipping recovery for non-host process: %s (pid=%s, scope=%s)", + entry.get("command", "unknown")[:60], + pid, + pid_scope, + ) + continue + + # Check if PID is still alive + alive = self._is_host_pid_alive(pid) + + if alive: + session = ProcessSession( + id=entry["session_id"], + command=entry.get("command", "unknown"), + task_id=entry.get("task_id", ""), + session_key=entry.get("session_key", ""), + pid=pid, + pid_scope=pid_scope, + cwd=entry.get("cwd"), + started_at=entry.get("started_at", time.time()), + detached=True, # Can't read output, but can report status + kill + watcher_platform=entry.get("watcher_platform", ""), + watcher_chat_id=entry.get("watcher_chat_id", ""), + watcher_user_id=entry.get("watcher_user_id", ""), + watcher_user_name=entry.get("watcher_user_name", ""), + watcher_thread_id=entry.get("watcher_thread_id", ""), + watcher_interval=entry.get("watcher_interval", 0), + notify_on_complete=entry.get("notify_on_complete", False), + watch_patterns=entry.get("watch_patterns", []), + ) + with self._lock: + self._running[session.id] = session + recovered += 1 + logger.info("Recovered detached process: %s (pid=%d)", session.command[:60], pid) + + # Re-enqueue watcher so gateway can resume notifications + if session.watcher_interval > 0: + self.pending_watchers.append({ + "session_id": session.id, + "check_interval": session.watcher_interval, + "session_key": session.session_key, + "platform": session.watcher_platform, + "chat_id": session.watcher_chat_id, + "user_id": session.watcher_user_id, + "user_name": session.watcher_user_name, + "thread_id": session.watcher_thread_id, + "notify_on_complete": session.notify_on_complete, + }) + + self._write_checkpoint() + + return recovered + + +# Module-level singleton +process_registry = ProcessRegistry() + + +# --------------------------------------------------------------------------- +# Registry -- the "process" tool schema + handler +# --------------------------------------------------------------------------- +from tools.registry import registry, tool_error + +PROCESS_SCHEMA = { + "name": "process", + "description": ( + "Manage background processes started with terminal(background=true). " + "Actions: 'list' (show all), 'poll' (check status + new output), " + "'log' (full output with pagination), 'wait' (block until done or timeout), " + "'kill' (terminate), 'write' (send raw stdin data without newline), " + "'submit' (send data + Enter, for answering prompts), 'close' (close stdin/send EOF)." + ), + "parameters": { + "type": "object", + "properties": { + "action": { + "type": "string", + "enum": ["list", "poll", "log", "wait", "kill", "write", "submit", "close"], + "description": "Action to perform on background processes" + }, + "session_id": { + "type": "string", + "description": "Process session ID (from terminal background output). Required for all actions except 'list'." + }, + "data": { + "type": "string", + "description": "Text to send to process stdin (for 'write' and 'submit' actions)" + }, + "timeout": { + "type": "integer", + "description": "Max seconds to block for 'wait' action. Returns partial output on timeout.", + "minimum": 1 + }, + "offset": { + "type": "integer", + "description": "Line offset for 'log' action (default: last 200 lines)" + }, + "limit": { + "type": "integer", + "description": "Max lines to return for 'log' action", + "minimum": 1 + } + }, + "required": ["action"] + } +} + + +def _handle_process(args, **kw): + import json as _json + task_id = kw.get("task_id") + action = args.get("action", "") + # Coerce to string — some models send session_id as an integer + session_id = str(args.get("session_id", "")) if args.get("session_id") is not None else "" + + if action == "list": + return _json.dumps({"processes": process_registry.list_sessions(task_id=task_id)}, ensure_ascii=False) + elif action in ("poll", "log", "wait", "kill", "write", "submit", "close"): + if not session_id: + return tool_error(f"session_id is required for {action}") + if action == "poll": + return _json.dumps(process_registry.poll(session_id), ensure_ascii=False) + elif action == "log": + return _json.dumps(process_registry.read_log( + session_id, offset=args.get("offset", 0), limit=args.get("limit", 200)), ensure_ascii=False) + elif action == "wait": + return _json.dumps(process_registry.wait(session_id, timeout=args.get("timeout")), ensure_ascii=False) + elif action == "kill": + return _json.dumps(process_registry.kill_process(session_id), ensure_ascii=False) + elif action == "write": + return _json.dumps(process_registry.write_stdin(session_id, str(args.get("data", ""))), ensure_ascii=False) + elif action == "submit": + return _json.dumps(process_registry.submit_stdin(session_id, str(args.get("data", ""))), ensure_ascii=False) + elif action == "close": + return _json.dumps(process_registry.close_stdin(session_id), ensure_ascii=False) + return tool_error(f"Unknown process action: {action}. Use: list, poll, log, wait, kill, write, submit, close") + + +registry.register( + name="process", + toolset="terminal", + schema=PROCESS_SCHEMA, + handler=_handle_process, + emoji="⚙️", +) diff --git a/mindcli/_vendor/tools/registry.py b/mindcli/_vendor/tools/registry.py new file mode 100644 index 0000000..d6aff83 --- /dev/null +++ b/mindcli/_vendor/tools/registry.py @@ -0,0 +1,386 @@ +"""Central registry for all hermes-agent tools. + +Each tool file calls ``registry.register()`` at module level to declare its +schema, handler, toolset membership, and availability check. ``model_tools.py`` +queries the registry instead of maintaining its own parallel data structures. + +Import chain (circular-import safe): + tools/registry.py (no imports from model_tools or tool files) + ^ + tools/*.py (import from tools.registry at module level) + ^ + model_tools.py (imports tools.registry + all tool modules) + ^ + run_agent.py, cli.py, batch_runner.py, etc. +""" + +import json +import logging +import threading +from typing import Callable, Dict, List, Optional, Set + +logger = logging.getLogger(__name__) + + +class ToolEntry: + """Metadata for a single registered tool.""" + + __slots__ = ( + "name", "toolset", "schema", "handler", "check_fn", + "requires_env", "is_async", "description", "emoji", + "max_result_size_chars", + ) + + def __init__(self, name, toolset, schema, handler, check_fn, + requires_env, is_async, description, emoji, + max_result_size_chars=None): + self.name = name + self.toolset = toolset + self.schema = schema + self.handler = handler + self.check_fn = check_fn + self.requires_env = requires_env + self.is_async = is_async + self.description = description + self.emoji = emoji + self.max_result_size_chars = max_result_size_chars + + +class ToolRegistry: + """Singleton registry that collects tool schemas + handlers from tool files.""" + + def __init__(self): + self._tools: Dict[str, ToolEntry] = {} + self._toolset_checks: Dict[str, Callable] = {} + # MCP dynamic refresh can mutate the registry while other threads are + # reading tool metadata, so keep mutations serialized and readers on + # stable snapshots. + self._lock = threading.RLock() + + def _snapshot_state(self) -> tuple[List[ToolEntry], Dict[str, Callable]]: + """Return a coherent snapshot of registry entries and toolset checks.""" + with self._lock: + return list(self._tools.values()), dict(self._toolset_checks) + + def _snapshot_entries(self) -> List[ToolEntry]: + """Return a stable snapshot of registered tool entries.""" + return self._snapshot_state()[0] + + def _snapshot_toolset_checks(self) -> Dict[str, Callable]: + """Return a stable snapshot of toolset availability checks.""" + return self._snapshot_state()[1] + + def _evaluate_toolset_check(self, toolset: str, check: Callable | None) -> bool: + """Run a toolset check, treating missing or failing checks as unavailable/available.""" + if not check: + return True + try: + return bool(check()) + except Exception: + logger.debug("Toolset %s check raised; marking unavailable", toolset) + return False + + def get_entry(self, name: str) -> Optional[ToolEntry]: + """Return a registered tool entry by name, or None.""" + with self._lock: + return self._tools.get(name) + + def get_registered_toolset_names(self) -> List[str]: + """Return sorted unique toolset names present in the registry.""" + return sorted({entry.toolset for entry in self._snapshot_entries()}) + + def get_tool_names_for_toolset(self, toolset: str) -> List[str]: + """Return sorted tool names registered under a given toolset.""" + return sorted( + entry.name for entry in self._snapshot_entries() + if entry.toolset == toolset + ) + + # ------------------------------------------------------------------ + # Registration + # ------------------------------------------------------------------ + + def register( + self, + name: str, + toolset: str, + schema: dict, + handler: Callable, + check_fn: Callable = None, + requires_env: list = None, + is_async: bool = False, + description: str = "", + emoji: str = "", + max_result_size_chars: int | float | None = None, + ): + """Register a tool. Called at module-import time by each tool file.""" + with self._lock: + existing = self._tools.get(name) + if existing and existing.toolset != toolset: + logger.warning( + "Tool name collision: '%s' (toolset '%s') is being " + "overwritten by toolset '%s'", + name, existing.toolset, toolset, + ) + self._tools[name] = ToolEntry( + name=name, + toolset=toolset, + schema=schema, + handler=handler, + check_fn=check_fn, + requires_env=requires_env or [], + is_async=is_async, + description=description or schema.get("description", ""), + emoji=emoji, + max_result_size_chars=max_result_size_chars, + ) + if check_fn and toolset not in self._toolset_checks: + self._toolset_checks[toolset] = check_fn + + def deregister(self, name: str) -> None: + """Remove a tool from the registry. + + Also cleans up the toolset check if no other tools remain in the + same toolset. Used by MCP dynamic tool discovery to nuke-and-repave + when a server sends ``notifications/tools/list_changed``. + """ + with self._lock: + entry = self._tools.pop(name, None) + if entry is None: + return + # Drop the toolset check if this was the last tool in that toolset + if entry.toolset in self._toolset_checks and not any( + e.toolset == entry.toolset for e in self._tools.values() + ): + self._toolset_checks.pop(entry.toolset, None) + logger.debug("Deregistered tool: %s", name) + + # ------------------------------------------------------------------ + # Schema retrieval + # ------------------------------------------------------------------ + + def get_definitions(self, tool_names: Set[str], quiet: bool = False) -> List[dict]: + """Return OpenAI-format tool schemas for the requested tool names. + + Only tools whose ``check_fn()`` returns True (or have no check_fn) + are included. + """ + result = [] + check_results: Dict[Callable, bool] = {} + entries_by_name = {entry.name: entry for entry in self._snapshot_entries()} + for name in sorted(tool_names): + entry = entries_by_name.get(name) + if not entry: + continue + if entry.check_fn: + if entry.check_fn not in check_results: + try: + check_results[entry.check_fn] = bool(entry.check_fn()) + except Exception: + check_results[entry.check_fn] = False + if not quiet: + logger.debug("Tool %s check raised; skipping", name) + if not check_results[entry.check_fn]: + if not quiet: + logger.debug("Tool %s unavailable (check failed)", name) + continue + # Ensure schema always has a "name" field — use entry.name as fallback + schema_with_name = {**entry.schema, "name": entry.name} + result.append({"type": "function", "function": schema_with_name}) + return result + + # ------------------------------------------------------------------ + # Dispatch + # ------------------------------------------------------------------ + + def dispatch(self, name: str, args: dict, **kwargs) -> str: + """Execute a tool handler by name. + + * Async handlers are bridged automatically via ``_run_async()``. + * All exceptions are caught and returned as ``{"error": "..."}`` + for consistent error format. + """ + entry = self.get_entry(name) + if not entry: + return json.dumps({"error": f"Unknown tool: {name}"}) + try: + if entry.is_async: + from model_tools import _run_async + return _run_async(entry.handler(args, **kwargs)) + return entry.handler(args, **kwargs) + except Exception as e: + logger.exception("Tool %s dispatch error: %s", name, e) + return json.dumps({"error": f"Tool execution failed: {type(e).__name__}: {e}"}) + + # ------------------------------------------------------------------ + # Query helpers (replace redundant dicts in model_tools.py) + # ------------------------------------------------------------------ + + def get_max_result_size(self, name: str, default: int | float | None = None) -> int | float: + """Return per-tool max result size, or *default* (or global default).""" + entry = self.get_entry(name) + if entry and entry.max_result_size_chars is not None: + return entry.max_result_size_chars + if default is not None: + return default + from tools.budget_config import DEFAULT_RESULT_SIZE_CHARS + return DEFAULT_RESULT_SIZE_CHARS + + def get_all_tool_names(self) -> List[str]: + """Return sorted list of all registered tool names.""" + return sorted(entry.name for entry in self._snapshot_entries()) + + def get_schema(self, name: str) -> Optional[dict]: + """Return a tool's raw schema dict, bypassing check_fn filtering. + + Useful for token estimation and introspection where availability + doesn't matter — only the schema content does. + """ + entry = self.get_entry(name) + return entry.schema if entry else None + + def get_toolset_for_tool(self, name: str) -> Optional[str]: + """Return the toolset a tool belongs to, or None.""" + entry = self.get_entry(name) + return entry.toolset if entry else None + + def get_emoji(self, name: str, default: str = "⚡") -> str: + """Return the emoji for a tool, or *default* if unset.""" + entry = self.get_entry(name) + return (entry.emoji if entry and entry.emoji else default) + + def get_tool_to_toolset_map(self) -> Dict[str, str]: + """Return ``{tool_name: toolset_name}`` for every registered tool.""" + return {entry.name: entry.toolset for entry in self._snapshot_entries()} + + def is_toolset_available(self, toolset: str) -> bool: + """Check if a toolset's requirements are met. + + Returns False (rather than crashing) when the check function raises + an unexpected exception (e.g. network error, missing import, bad config). + """ + with self._lock: + check = self._toolset_checks.get(toolset) + return self._evaluate_toolset_check(toolset, check) + + def check_toolset_requirements(self) -> Dict[str, bool]: + """Return ``{toolset: available_bool}`` for every toolset.""" + entries, toolset_checks = self._snapshot_state() + toolsets = sorted({entry.toolset for entry in entries}) + return { + toolset: self._evaluate_toolset_check(toolset, toolset_checks.get(toolset)) + for toolset in toolsets + } + + def get_available_toolsets(self) -> Dict[str, dict]: + """Return toolset metadata for UI display.""" + toolsets: Dict[str, dict] = {} + entries, toolset_checks = self._snapshot_state() + for entry in entries: + ts = entry.toolset + if ts not in toolsets: + toolsets[ts] = { + "available": self._evaluate_toolset_check( + ts, toolset_checks.get(ts) + ), + "tools": [], + "description": "", + "requirements": [], + } + toolsets[ts]["tools"].append(entry.name) + if entry.requires_env: + for env in entry.requires_env: + if env not in toolsets[ts]["requirements"]: + toolsets[ts]["requirements"].append(env) + return toolsets + + def get_toolset_requirements(self) -> Dict[str, dict]: + """Build a TOOLSET_REQUIREMENTS-compatible dict for backward compat.""" + result: Dict[str, dict] = {} + entries, toolset_checks = self._snapshot_state() + for entry in entries: + ts = entry.toolset + if ts not in result: + result[ts] = { + "name": ts, + "env_vars": [], + "check_fn": toolset_checks.get(ts), + "setup_url": None, + "tools": [], + } + if entry.name not in result[ts]["tools"]: + result[ts]["tools"].append(entry.name) + for env in entry.requires_env: + if env not in result[ts]["env_vars"]: + result[ts]["env_vars"].append(env) + return result + + def check_tool_availability(self, quiet: bool = False): + """Return (available_toolsets, unavailable_info) like the old function.""" + available = [] + unavailable = [] + seen = set() + entries, toolset_checks = self._snapshot_state() + for entry in entries: + ts = entry.toolset + if ts in seen: + continue + seen.add(ts) + if self._evaluate_toolset_check(ts, toolset_checks.get(ts)): + available.append(ts) + else: + unavailable.append({ + "name": ts, + "env_vars": entry.requires_env, + "tools": [e.name for e in entries if e.toolset == ts], + }) + return available, unavailable + + +# Module-level singleton +registry = ToolRegistry() + + +# --------------------------------------------------------------------------- +# Helpers for tool response serialization +# --------------------------------------------------------------------------- +# Every tool handler must return a JSON string. These helpers eliminate the +# boilerplate ``json.dumps({"error": msg}, ensure_ascii=False)`` that appears +# hundreds of times across tool files. +# +# Usage: +# from tools.registry import registry, tool_error, tool_result +# +# return tool_error("something went wrong") +# return tool_error("not found", code=404) +# return tool_result(success=True, data=payload) +# return tool_result(items) # pass a dict directly + + +def tool_error(message, **extra) -> str: + """Return a JSON error string for tool handlers. + + >>> tool_error("file not found") + '{"error": "file not found"}' + >>> tool_error("bad input", success=False) + '{"error": "bad input", "success": false}' + """ + result = {"error": str(message)} + if extra: + result.update(extra) + return json.dumps(result, ensure_ascii=False) + + +def tool_result(data=None, **kwargs) -> str: + """Return a JSON result string for tool handlers. + + Accepts a dict positional arg *or* keyword arguments (not both): + + >>> tool_result(success=True, count=42) + '{"success": true, "count": 42}' + >>> tool_result({"key": "value"}) + '{"key": "value"}' + """ + if data is not None: + return json.dumps(data, ensure_ascii=False) + return json.dumps(kwargs, ensure_ascii=False) diff --git a/mindcli/_vendor/tools/rl_training_tool.py b/mindcli/_vendor/tools/rl_training_tool.py new file mode 100644 index 0000000..7a6478b --- /dev/null +++ b/mindcli/_vendor/tools/rl_training_tool.py @@ -0,0 +1,1396 @@ +#!/usr/bin/env python3 +""" +RL Training Tools Module + +This module provides tools for running RL training through Tinker-Atropos. +Directly manages training processes without requiring a separate API server. + +Features: +- Environment discovery (AST-based scanning for BaseEnv subclasses) +- Configuration management with locked infrastructure settings +- Training run lifecycle via subprocess management +- WandB metrics monitoring + +Required environment variables: +- TINKER_API_KEY: API key for Tinker service +- WANDB_API_KEY: API key for Weights & Biases metrics + +Usage: + from tools.rl_training_tool import ( + rl_list_environments, + rl_select_environment, + rl_get_current_config, + rl_edit_config, + rl_start_training, + rl_check_status, + rl_stop_training, + rl_get_results, + ) +""" + +import ast +import asyncio +import importlib.util +import json +import os +import subprocess +import sys +import time +import uuid +import logging +from datetime import datetime +import yaml +from dataclasses import dataclass +from pathlib import Path +from typing import Any, Dict, List, Optional + +from hermes_constants import get_hermes_home + +logger = logging.getLogger(__name__) + +# ============================================================================ +# Path Configuration +# ============================================================================ + +# Path to tinker-atropos submodule (relative to hermes-agent root) +HERMES_ROOT = Path(__file__).parent.parent +TINKER_ATROPOS_ROOT = HERMES_ROOT / "tinker-atropos" +ENVIRONMENTS_DIR = TINKER_ATROPOS_ROOT / "tinker_atropos" / "environments" +CONFIGS_DIR = TINKER_ATROPOS_ROOT / "configs" +LOGS_DIR = get_hermes_home() / "logs" / "rl_training" + +def _ensure_logs_dir(): + """Lazily create logs directory on first use (avoid side effects at import time).""" + if TINKER_ATROPOS_ROOT.exists(): + LOGS_DIR.mkdir(exist_ok=True) + +# ============================================================================ +# Locked Configuration (Infrastructure Settings) +# ============================================================================ + +# These fields cannot be changed by the model - they're tuned for our infrastructure +LOCKED_FIELDS = { + "env": { + "tokenizer_name": "Qwen/Qwen3-8B", + "rollout_server_url": "http://localhost:8000", + "use_wandb": True, + "max_token_length": 8192, + "max_num_workers": 2048, + "worker_timeout": 3600, + "total_steps": 2500, + "steps_per_eval": 25, + "max_batches_offpolicy": 3, + "inference_weight": 1.0, + "eval_limit_ratio": 0.1, + }, + "openai": [ + { + "model_name": "Qwen/Qwen3-8B", + "base_url": "http://localhost:8001/v1", + "api_key": "x", + "weight": 1.0, + "num_requests_for_eval": 256, + "timeout": 3600, + "server_type": "sglang", # Tinker uses sglang for actual training + } + ], + "tinker": { + "lora_rank": 32, + "learning_rate": 0.00004, + "max_token_trainer_length": 9000, + "checkpoint_dir": "./temp/", + "save_checkpoint_interval": 25, + }, + "slurm": False, + "testing": False, +} + +LOCKED_FIELD_NAMES = set(LOCKED_FIELDS.get("env", {}).keys()) + + +# ============================================================================ +# State Management +# ============================================================================ + +@dataclass +class EnvironmentInfo: + """Information about a discovered environment.""" + name: str + class_name: str + file_path: str + description: str = "" + config_class: str = "BaseEnvConfig" + + +@dataclass +class RunState: + """State for a training run.""" + run_id: str + environment: str + config: Dict[str, Any] + status: str = "pending" # pending, starting, running, stopping, stopped, completed, failed + error_message: str = "" + wandb_project: str = "" + wandb_run_name: str = "" + start_time: float = 0.0 + # Process handles + api_process: Optional[subprocess.Popen] = None + trainer_process: Optional[subprocess.Popen] = None + env_process: Optional[subprocess.Popen] = None + + +# Global state +_environments: List[EnvironmentInfo] = [] +_current_env: Optional[str] = None +_current_config: Dict[str, Any] = {} +_env_config_cache: Dict[str, Dict[str, Dict[str, Any]]] = {} +_active_runs: Dict[str, RunState] = {} +_last_status_check: Dict[str, float] = {} + +# Rate limiting for status checks (30 minutes) +MIN_STATUS_CHECK_INTERVAL = 30 * 60 + + +# ============================================================================ +# Environment Discovery +# ============================================================================ + +def _scan_environments() -> List[EnvironmentInfo]: + """ + Scan the environments directory for BaseEnv subclasses using AST. + """ + environments = [] + + if not ENVIRONMENTS_DIR.exists(): + return environments + + for py_file in ENVIRONMENTS_DIR.glob("*.py"): + if py_file.name.startswith("_"): + continue + + try: + with open(py_file, "r") as f: + tree = ast.parse(f.read()) + + for node in ast.walk(tree): + if isinstance(node, ast.ClassDef): + # Check if class has BaseEnv as base + for base in node.bases: + base_name = "" + if isinstance(base, ast.Name): + base_name = base.id + elif isinstance(base, ast.Attribute): + base_name = base.attr + + if base_name == "BaseEnv": + # Extract name from class attribute if present + env_name = py_file.stem + description = "" + config_class = "BaseEnvConfig" + + for item in node.body: + if isinstance(item, ast.Assign): + for target in item.targets: + if isinstance(target, ast.Name): + if target.id == "name" and isinstance(item.value, ast.Constant): + env_name = item.value.value + elif target.id == "env_config_cls" and isinstance(item.value, ast.Name): + config_class = item.value.id + + # Get docstring + if isinstance(item, ast.Expr) and isinstance(item.value, ast.Constant): + if isinstance(item.value.value, str) and not description: + description = item.value.value.split("\n")[0].strip() + + environments.append(EnvironmentInfo( + name=env_name, + class_name=node.name, + file_path=str(py_file), + description=description or f"Environment from {py_file.name}", + config_class=config_class, + )) + break + except Exception as e: + logger.warning("Could not parse %s: %s", py_file, e) + + return environments + + +def _get_env_config_fields(env_file_path: str) -> Dict[str, Dict[str, Any]]: + """ + Dynamically import an environment and extract its config fields. + + Uses config_init() to get the actual config class, with fallback to + directly importing BaseEnvConfig if config_init fails. + """ + try: + # Load the environment module + spec = importlib.util.spec_from_file_location("env_module", env_file_path) + module = importlib.util.module_from_spec(spec) + sys.modules["env_module"] = module + spec.loader.exec_module(module) + + # Find the BaseEnv subclass + env_class = None + for name, obj in vars(module).items(): + if isinstance(obj, type) and name != "BaseEnv": + if hasattr(obj, "config_init") and callable(getattr(obj, "config_init")): + env_class = obj + break + + if not env_class: + return {} + + # Try calling config_init to get the actual config class + config_class = None + try: + env_config, server_configs = env_class.config_init() + config_class = type(env_config) + except Exception as config_error: + # Fallback: try to import BaseEnvConfig directly from atroposlib + logger.info("config_init failed (%s), using BaseEnvConfig defaults", config_error) + try: + from atroposlib.envs.base import BaseEnvConfig + config_class = BaseEnvConfig + except ImportError: + return {} + + if not config_class: + return {} + + # Helper to make values JSON-serializable (handle enums, etc.) + def make_serializable(val): + if val is None: + return None + if hasattr(val, 'value'): # Enum + return val.value + if hasattr(val, 'name') and hasattr(val, '__class__') and 'Enum' in str(type(val)): + return val.name + return val + + # Extract fields from the Pydantic model + fields = {} + for field_name, field_info in config_class.model_fields.items(): + field_type = field_info.annotation + default = make_serializable(field_info.default) + description = field_info.description or "" + + is_locked = field_name in LOCKED_FIELD_NAMES + + # Convert type to string + type_name = getattr(field_type, "__name__", str(field_type)) + if hasattr(field_type, "__origin__"): + type_name = str(field_type) + + locked_value = LOCKED_FIELDS.get("env", {}).get(field_name, default) + current_value = make_serializable(locked_value) if is_locked else default + + fields[field_name] = { + "type": type_name, + "default": default, + "description": description, + "locked": is_locked, + "current_value": current_value, + } + + return fields + + except Exception as e: + logger.warning("Could not introspect environment config: %s", e) + return {} + + +def _initialize_environments(): + """Initialize environment list on first use.""" + global _environments + if not _environments: + _environments = _scan_environments() + + +# ============================================================================ +# Subprocess Management +# ============================================================================ + +async def _spawn_training_run(run_state: RunState, config_path: Path): + """ + Spawn the three processes needed for training: + 1. run-api (Atropos API server) + 2. launch_training.py (Tinker trainer + inference server) + 3. environment.py serve (the Atropos environment) + """ + run_id = run_state.run_id + + _ensure_logs_dir() + + # Log file paths + api_log = LOGS_DIR / f"api_{run_id}.log" + trainer_log = LOGS_DIR / f"trainer_{run_id}.log" + env_log = LOGS_DIR / f"env_{run_id}.log" + + try: + # Step 1: Start the Atropos API server (run-api) + logger.info("[%s] Starting Atropos API server (run-api)...", run_id) + + # File must stay open while the subprocess runs; we store the handle + # on run_state so _stop_training_run() can close it when done. + api_log_file = open(api_log, "w") # closed by _stop_training_run + run_state.api_log_file = api_log_file + run_state.api_process = subprocess.Popen( + ["run-api"], + stdout=api_log_file, + stderr=subprocess.STDOUT, + cwd=str(TINKER_ATROPOS_ROOT), + ) + + # Wait for API to start + await asyncio.sleep(5) + + if run_state.api_process.poll() is not None: + run_state.status = "failed" + run_state.error_message = f"API server exited with code {run_state.api_process.returncode}. Check {api_log}" + _stop_training_run(run_state) + return + + logger.info("[%s] Atropos API server started", run_id) + + # Step 2: Start the Tinker trainer + logger.info("[%s] Starting Tinker trainer: launch_training.py --config %s", run_id, config_path) + + trainer_log_file = open(trainer_log, "w") # closed by _stop_training_run + run_state.trainer_log_file = trainer_log_file + run_state.trainer_process = subprocess.Popen( + [sys.executable, "launch_training.py", "--config", str(config_path)], + stdout=trainer_log_file, + stderr=subprocess.STDOUT, + cwd=str(TINKER_ATROPOS_ROOT), + env={**os.environ, "TINKER_API_KEY": os.getenv("TINKER_API_KEY", "")}, + ) + + # Wait for trainer to initialize (it starts FastAPI inference server on 8001) + logger.info("[%s] Waiting 30 seconds for trainer to initialize...", run_id) + await asyncio.sleep(30) + + if run_state.trainer_process.poll() is not None: + run_state.status = "failed" + run_state.error_message = f"Trainer exited with code {run_state.trainer_process.returncode}. Check {trainer_log}" + _stop_training_run(run_state) + return + + logger.info("[%s] Trainer started, inference server on port 8001", run_id) + + # Step 3: Start the environment + logger.info("[%s] Waiting 90 more seconds before starting environment...", run_id) + await asyncio.sleep(90) + + # Find the environment file + env_info = None + for env in _environments: + if env.name == run_state.environment: + env_info = env + break + + if not env_info: + run_state.status = "failed" + run_state.error_message = f"Environment '{run_state.environment}' not found" + _stop_training_run(run_state) + return + + logger.info("[%s] Starting environment: %s serve", run_id, env_info.file_path) + + env_log_file = open(env_log, "w") # closed by _stop_training_run + run_state.env_log_file = env_log_file + run_state.env_process = subprocess.Popen( + [sys.executable, str(env_info.file_path), "serve", "--config", str(config_path)], + stdout=env_log_file, + stderr=subprocess.STDOUT, + cwd=str(TINKER_ATROPOS_ROOT), + ) + + # Wait for environment to connect + await asyncio.sleep(10) + + if run_state.env_process.poll() is not None: + run_state.status = "failed" + run_state.error_message = f"Environment exited with code {run_state.env_process.returncode}. Check {env_log}" + _stop_training_run(run_state) + return + + run_state.status = "running" + run_state.start_time = time.time() + logger.info("[%s] Training run started successfully!", run_id) + + # Start background monitoring + asyncio.create_task(_monitor_training_run(run_state)) + + except Exception as e: + run_state.status = "failed" + run_state.error_message = str(e) + _stop_training_run(run_state) + + +async def _monitor_training_run(run_state: RunState): + """Background task to monitor a training run.""" + while run_state.status == "running": + await asyncio.sleep(30) # Check every 30 seconds + + # Check if any process has died + if run_state.env_process and run_state.env_process.poll() is not None: + exit_code = run_state.env_process.returncode + if exit_code == 0: + run_state.status = "completed" + else: + run_state.status = "failed" + run_state.error_message = f"Environment process exited with code {exit_code}" + _stop_training_run(run_state) + break + + if run_state.trainer_process and run_state.trainer_process.poll() is not None: + exit_code = run_state.trainer_process.returncode + if exit_code == 0: + run_state.status = "completed" + else: + run_state.status = "failed" + run_state.error_message = f"Trainer process exited with code {exit_code}" + _stop_training_run(run_state) + break + + if run_state.api_process and run_state.api_process.poll() is not None: + run_state.status = "failed" + run_state.error_message = "API server exited unexpectedly" + _stop_training_run(run_state) + break + + +def _stop_training_run(run_state: RunState): + """Stop all processes for a training run.""" + # Stop in reverse order: env -> trainer -> api + if run_state.env_process and run_state.env_process.poll() is None: + logger.info("[%s] Stopping environment process...", run_state.run_id) + run_state.env_process.terminate() + try: + run_state.env_process.wait(timeout=10) + except subprocess.TimeoutExpired: + run_state.env_process.kill() + + if run_state.trainer_process and run_state.trainer_process.poll() is None: + logger.info("[%s] Stopping trainer process...", run_state.run_id) + run_state.trainer_process.terminate() + try: + run_state.trainer_process.wait(timeout=10) + except subprocess.TimeoutExpired: + run_state.trainer_process.kill() + + if run_state.api_process and run_state.api_process.poll() is None: + logger.info("[%s] Stopping API server...", run_state.run_id) + run_state.api_process.terminate() + try: + run_state.api_process.wait(timeout=10) + except subprocess.TimeoutExpired: + run_state.api_process.kill() + + if run_state.status == "running": + run_state.status = "stopped" + + # Close log file handles that were opened for subprocess stdout. + for attr in ("env_log_file", "trainer_log_file", "api_log_file"): + fh = getattr(run_state, attr, None) + if fh is not None: + try: + fh.close() + except Exception: + pass + setattr(run_state, attr, None) + + +# ============================================================================ +# Environment Discovery Tools +# ============================================================================ + +async def rl_list_environments() -> str: + """ + List all available RL environments. + + Scans tinker-atropos/tinker_atropos/environments/ for Python files + containing classes that inherit from BaseEnv. + + Returns information about each environment including: + - name: Environment identifier + - class_name: Python class name + - file_path: Path to the environment file + - description: Brief description if available + + TIP: To create or modify RL environments: + 1. Use terminal/file tools to inspect existing environments + 2. Study how they load datasets, define verifiers, and structure rewards + 3. Inspect HuggingFace datasets to understand data formats + 4. Copy an existing environment as a template + + Returns: + JSON string with list of environments + """ + _initialize_environments() + + response = { + "environments": [ + { + "name": env.name, + "class_name": env.class_name, + "file_path": env.file_path, + "description": env.description, + } + for env in _environments + ], + "count": len(_environments), + "tips": [ + "Use rl_select_environment(name) to select an environment", + "Read the file_path with file tools to understand how each environment works", + "Look for load_dataset(), score_answer(), get_next_item() methods", + ] + } + + return json.dumps(response, indent=2) + + +async def rl_select_environment(name: str) -> str: + """ + Select an RL environment for training. + + This loads the environment's configuration fields into memory. + After selecting, use rl_get_current_config() to see all configurable options + and rl_edit_config() to modify specific fields. + + Args: + name: Name of the environment to select (from rl_list_environments) + + Returns: + JSON string with selection result, file path, and configurable field count + + TIP: Read the returned file_path to understand how the environment works. + """ + global _current_env, _current_config + + _initialize_environments() + + env_info = None + for env in _environments: + if env.name == name: + env_info = env + break + + if not env_info: + return json.dumps({ + "error": f"Environment '{name}' not found", + "available": [e.name for e in _environments], + }, indent=2) + + _current_env = name + + # Dynamically discover config fields + config_fields = _get_env_config_fields(env_info.file_path) + _env_config_cache[name] = config_fields + + # Initialize current config with defaults for non-locked fields + _current_config = {} + for field_name, field_info in config_fields.items(): + if not field_info.get("locked", False): + _current_config[field_name] = field_info.get("default") + + # Auto-set wandb_name to "{env_name}-DATETIME" to avoid overlaps + timestamp = datetime.now().strftime("%Y%m%d-%H%M%S") + _current_config["wandb_name"] = f"{name}-{timestamp}" + + return json.dumps({ + "message": f"Selected environment: {name}", + "environment": name, + "file_path": env_info.file_path, + }, indent=2) + + +# ============================================================================ +# Configuration Tools +# ============================================================================ + +async def rl_get_current_config() -> str: + """ + Get the current environment configuration. + + Returns all configurable fields for the selected environment. + Each environment may have different configuration options. + + Fields are divided into: + - configurable_fields: Can be changed with rl_edit_config() + - locked_fields: Infrastructure settings that cannot be changed + + Returns: + JSON string with configurable and locked fields + """ + if not _current_env: + return json.dumps({ + "error": "No environment selected. Use rl_select_environment(name) first.", + }, indent=2) + + config_fields = _env_config_cache.get(_current_env, {}) + + configurable = [] + locked = [] + + for field_name, field_info in config_fields.items(): + field_data = { + "name": field_name, + "type": field_info.get("type", "unknown"), + "default": field_info.get("default"), + "description": field_info.get("description", ""), + "current_value": _current_config.get(field_name, field_info.get("default")), + } + + if field_info.get("locked", False): + field_data["locked_value"] = LOCKED_FIELDS.get("env", {}).get(field_name) + locked.append(field_data) + else: + configurable.append(field_data) + + return json.dumps({ + "environment": _current_env, + "configurable_fields": configurable, + "locked_fields": locked, + "tip": "Use rl_edit_config(field, value) to change any configurable field.", + }, indent=2) + + +async def rl_edit_config(field: str, value: Any) -> str: + """ + Update a configuration field. + + Use rl_get_current_config() first to see available fields for the + selected environment. Each environment has different options. + + Locked fields (infrastructure settings) cannot be changed. + + Args: + field: Name of the field to update (from rl_get_current_config) + value: New value for the field + + Returns: + JSON string with updated config or error message + """ + if not _current_env: + return json.dumps({ + "error": "No environment selected. Use rl_select_environment(name) first.", + }, indent=2) + + config_fields = _env_config_cache.get(_current_env, {}) + + if field not in config_fields: + return json.dumps({ + "error": f"Unknown field '{field}'", + "available_fields": list(config_fields.keys()), + }, indent=2) + + field_info = config_fields[field] + if field_info.get("locked", False): + return json.dumps({ + "error": f"Field '{field}' is locked and cannot be changed", + "locked_value": LOCKED_FIELDS.get("env", {}).get(field), + }, indent=2) + + _current_config[field] = value + + return json.dumps({ + "message": f"Updated {field} = {value}", + "field": field, + "value": value, + "config": _current_config, + }, indent=2) + + +# ============================================================================ +# Training Management Tools +# ============================================================================ + +async def rl_start_training() -> str: + """ + Start a new RL training run with the current environment and config. + + Requires an environment to be selected first using rl_select_environment(). + Use rl_edit_config() to adjust configuration before starting. + + This spawns three processes: + 1. run-api (Atropos trajectory API) + 2. launch_training.py (Tinker trainer + inference server) + 3. environment.py serve (the selected environment) + + WARNING: Training runs take hours. Use rl_check_status() to monitor + progress (recommended: check every 30 minutes at most). + + Returns: + JSON string with run_id and initial status + """ + if not _current_env: + return json.dumps({ + "error": "No environment selected. Use rl_select_environment(name) first.", + }, indent=2) + + # Check API keys + if not os.getenv("TINKER_API_KEY"): + return json.dumps({ + "error": "TINKER_API_KEY not set. Add it to ~/.hermes/.env", + }, indent=2) + + # Find environment file + env_info = None + for env in _environments: + if env.name == _current_env: + env_info = env + break + + if not env_info or not Path(env_info.file_path).exists(): + return json.dumps({ + "error": f"Environment file not found for '{_current_env}'", + }, indent=2) + + # Generate run ID + run_id = str(uuid.uuid4())[:8] + + # Create config YAML + CONFIGS_DIR.mkdir(exist_ok=True) + config_path = CONFIGS_DIR / f"run_{run_id}.yaml" + + # Start with locked config as base + import copy + run_config = copy.deepcopy(LOCKED_FIELDS) + + if "env" not in run_config: + run_config["env"] = {} + + # Apply configurable fields + for field_name, value in _current_config.items(): + if value is not None and value != "": + run_config["env"][field_name] = value + + # Set WandB settings + wandb_project = _current_config.get("wandb_project", "atropos-tinker") + if "tinker" not in run_config: + run_config["tinker"] = {} + run_config["tinker"]["wandb_project"] = wandb_project + run_config["tinker"]["wandb_run_name"] = f"{_current_env}-{run_id}" + + if "wandb_name" in _current_config and _current_config["wandb_name"]: + run_config["env"]["wandb_name"] = _current_config["wandb_name"] + + with open(config_path, "w") as f: + yaml.dump(run_config, f, default_flow_style=False) + + # Create run state + run_state = RunState( + run_id=run_id, + environment=_current_env, + config=_current_config.copy(), + status="starting", + wandb_project=wandb_project, + wandb_run_name=f"{_current_env}-{run_id}", + ) + + _active_runs[run_id] = run_state + + # Start training in background + asyncio.create_task(_spawn_training_run(run_state, config_path)) + + return json.dumps({ + "run_id": run_id, + "status": "starting", + "environment": _current_env, + "config": _current_config, + "wandb_project": wandb_project, + "wandb_run_name": f"{_current_env}-{run_id}", + "config_path": str(config_path), + "logs": { + "api": str(LOGS_DIR / f"api_{run_id}.log"), + "trainer": str(LOGS_DIR / f"trainer_{run_id}.log"), + "env": str(LOGS_DIR / f"env_{run_id}.log"), + }, + "message": "Training starting. Use rl_check_status(run_id) to monitor (recommended: every 30 minutes).", + }, indent=2) + + +async def rl_check_status(run_id: str) -> str: + """ + Get status and metrics for a training run. + + RATE LIMITED: For long-running training, this function enforces a + minimum 30-minute interval between checks for the same run_id. + + Args: + run_id: The run ID returned by rl_start_training() + + Returns: + JSON string with run status and metrics + """ + # Check rate limiting + now = time.time() + if run_id in _last_status_check: + elapsed = now - _last_status_check[run_id] + if elapsed < MIN_STATUS_CHECK_INTERVAL: + remaining = MIN_STATUS_CHECK_INTERVAL - elapsed + return json.dumps({ + "rate_limited": True, + "run_id": run_id, + "message": f"Rate limited. Next check available in {remaining/60:.0f} minutes.", + "next_check_in_seconds": remaining, + }, indent=2) + + _last_status_check[run_id] = now + + if run_id not in _active_runs: + return json.dumps({ + "error": f"Run '{run_id}' not found", + "active_runs": list(_active_runs.keys()), + }, indent=2) + + run_state = _active_runs[run_id] + + # Check process status + processes = { + "api": run_state.api_process.poll() if run_state.api_process else None, + "trainer": run_state.trainer_process.poll() if run_state.trainer_process else None, + "env": run_state.env_process.poll() if run_state.env_process else None, + } + + running_time = time.time() - run_state.start_time if run_state.start_time else 0 + + result = { + "run_id": run_id, + "status": run_state.status, + "environment": run_state.environment, + "running_time_minutes": running_time / 60, + "processes": { + name: "running" if code is None else f"exited ({code})" + for name, code in processes.items() + }, + "wandb_project": run_state.wandb_project, + "wandb_run_name": run_state.wandb_run_name, + "logs": { + "api": str(LOGS_DIR / f"api_{run_id}.log"), + "trainer": str(LOGS_DIR / f"trainer_{run_id}.log"), + "env": str(LOGS_DIR / f"env_{run_id}.log"), + }, + } + + if run_state.error_message: + result["error"] = run_state.error_message + + # Try to get WandB metrics if available + try: + import wandb + api = wandb.Api() + runs = api.runs( + f"{os.getenv('WANDB_ENTITY', 'nousresearch')}/{run_state.wandb_project}", + filters={"display_name": run_state.wandb_run_name} + ) + if runs: + wandb_run = runs[0] + result["wandb_url"] = wandb_run.url + result["metrics"] = { + "step": wandb_run.summary.get("_step", 0), + "reward_mean": wandb_run.summary.get("train/reward_mean"), + "percent_correct": wandb_run.summary.get("train/percent_correct"), + "eval_percent_correct": wandb_run.summary.get("eval/percent_correct"), + } + except Exception as e: + result["wandb_error"] = str(e) + + return json.dumps(result, indent=2) + + +async def rl_stop_training(run_id: str) -> str: + """ + Stop a running training job. + + Args: + run_id: The run ID to stop + + Returns: + JSON string with stop confirmation + """ + if run_id not in _active_runs: + return json.dumps({ + "error": f"Run '{run_id}' not found", + "active_runs": list(_active_runs.keys()), + }, indent=2) + + run_state = _active_runs[run_id] + + if run_state.status not in ("running", "starting"): + return json.dumps({ + "message": f"Run '{run_id}' is not running (status: {run_state.status})", + }, indent=2) + + _stop_training_run(run_state) + + return json.dumps({ + "message": f"Stopped training run '{run_id}'", + "run_id": run_id, + "status": run_state.status, + }, indent=2) + + +async def rl_get_results(run_id: str) -> str: + """ + Get final results and metrics for a training run. + + Args: + run_id: The run ID to get results for + + Returns: + JSON string with final results + """ + if run_id not in _active_runs: + return json.dumps({ + "error": f"Run '{run_id}' not found", + }, indent=2) + + run_state = _active_runs[run_id] + + result = { + "run_id": run_id, + "status": run_state.status, + "environment": run_state.environment, + "wandb_project": run_state.wandb_project, + "wandb_run_name": run_state.wandb_run_name, + } + + # Get WandB metrics + try: + import wandb + api = wandb.Api() + runs = api.runs( + f"{os.getenv('WANDB_ENTITY', 'nousresearch')}/{run_state.wandb_project}", + filters={"display_name": run_state.wandb_run_name} + ) + if runs: + wandb_run = runs[0] + result["wandb_url"] = wandb_run.url + result["final_metrics"] = dict(wandb_run.summary) + result["history"] = [dict(row) for row in wandb_run.history(samples=10)] + except Exception as e: + result["wandb_error"] = str(e) + + return json.dumps(result, indent=2) + + +async def rl_list_runs() -> str: + """ + List all training runs (active and completed). + + Returns: + JSON string with list of runs and their status + """ + runs = [] + for run_id, run_state in _active_runs.items(): + runs.append({ + "run_id": run_id, + "environment": run_state.environment, + "status": run_state.status, + "wandb_run_name": run_state.wandb_run_name, + }) + + return json.dumps({ + "runs": runs, + "count": len(runs), + }, indent=2) + + +# ============================================================================ +# Inference Testing (via Atropos `process` mode with OpenRouter) +# ============================================================================ + +# Test models at different scales for robustness testing +# These are cheap, capable models on OpenRouter for testing parsing/scoring +TEST_MODELS = [ + {"id": "qwen/qwen3-8b", "name": "Qwen3 8B", "scale": "small"}, + {"id": "z-ai/glm-4.7-flash", "name": "GLM-4.7 Flash", "scale": "medium"}, + {"id": "minimax/minimax-m2.7", "name": "MiniMax M2.7", "scale": "large"}, +] + +# Default test parameters - quick but representative +DEFAULT_NUM_STEPS = 3 # Number of steps (items) to test +DEFAULT_GROUP_SIZE = 16 # Completions per item (like training) + + +async def rl_test_inference( + num_steps: int = DEFAULT_NUM_STEPS, + group_size: int = DEFAULT_GROUP_SIZE, + models: Optional[List[str]] = None, +) -> str: + """ + Quick inference test for any environment using Atropos's `process` mode. + + Runs a few steps of inference + scoring to validate: + - Environment loads correctly + - Prompt construction works + - Inference parsing is robust (tested with multiple model scales) + - Verifier/scoring logic works + + Default: 3 steps × 16 completions = 48 total rollouts per model. + Tests 3 models = 144 total rollouts. Quick sanity check. + + Test models (varying intelligence levels for robustness): + - qwen/qwen3-8b (small) + - zhipu-ai/glm-4-flash (medium) + - minimax/minimax-m1 (large) + + Args: + num_steps: Steps to run (default: 3, max recommended for testing) + group_size: Completions per step (default: 16, like training) + models: Optional model IDs to test. If None, uses all 3 test models. + + Returns: + JSON with results per model: steps_tested, accuracy, scores + """ + if not _current_env: + return json.dumps({ + "error": "No environment selected. Use rl_select_environment(name) first.", + }, indent=2) + + api_key = os.getenv("OPENROUTER_API_KEY") + if not api_key: + return json.dumps({ + "error": "OPENROUTER_API_KEY not set. Required for inference testing.", + }, indent=2) + + # Find environment info + env_info = None + for env in _environments: + if env.name == _current_env: + env_info = env + break + + if not env_info: + return json.dumps({ + "error": f"Environment '{_current_env}' not found", + }, indent=2) + + # Determine which models to test + if models: + test_models = [m for m in TEST_MODELS if m["id"] in models] + if not test_models: + test_models = [{"id": m, "name": m, "scale": "custom"} for m in models] + else: + test_models = TEST_MODELS + + # Calculate total rollouts for logging + total_rollouts_per_model = num_steps * group_size + total_rollouts = total_rollouts_per_model * len(test_models) + + results = { + "environment": _current_env, + "environment_file": env_info.file_path, + "test_config": { + "num_steps": num_steps, + "group_size": group_size, + "rollouts_per_model": total_rollouts_per_model, + "total_rollouts": total_rollouts, + }, + "models_tested": [], + } + + # Create output directory for test results + _ensure_logs_dir() + test_output_dir = LOGS_DIR / "inference_tests" + test_output_dir.mkdir(exist_ok=True) + + for model_info in test_models: + model_id = model_info["id"] + model_safe_name = model_id.replace("/", "_") + + print(f"\n{'='*60}") + print(f"Testing with {model_info['name']} ({model_id})") + print(f"{'='*60}") + + # Output file for this test run + output_file = test_output_dir / f"test_{_current_env}_{model_safe_name}.jsonl" + + # Generate unique run ID for wandb + test_run_id = str(uuid.uuid4())[:8] + wandb_run_name = f"test_inference_RSIAgent_{_current_env}_{test_run_id}" + + # Build the process command using Atropos's built-in CLI + # This runs the environment's actual code with OpenRouter as the inference backend + # We pass our locked settings + test-specific overrides via CLI args + cmd = [ + sys.executable, env_info.file_path, "process", + # Test-specific overrides + "--env.total_steps", str(num_steps), + "--env.group_size", str(group_size), + "--env.use_wandb", "true", # Enable wandb for test tracking + "--env.wandb_name", wandb_run_name, + "--env.data_path_to_save_groups", str(output_file), + # Use locked settings from our config + "--env.tokenizer_name", LOCKED_FIELDS["env"]["tokenizer_name"], + "--env.max_token_length", str(LOCKED_FIELDS["env"]["max_token_length"]), + "--env.max_num_workers", str(LOCKED_FIELDS["env"]["max_num_workers"]), + "--env.max_batches_offpolicy", str(LOCKED_FIELDS["env"]["max_batches_offpolicy"]), + # OpenRouter config for inference testing + # IMPORTANT: Use server_type=openai for OpenRouter (not sglang) + # sglang is only for actual training with Tinker's inference server + "--openai.base_url", "https://openrouter.ai/api/v1", + "--openai.api_key", api_key, + "--openai.model_name", model_id, + "--openai.server_type", "openai", # OpenRouter is OpenAI-compatible + "--openai.health_check", "false", # OpenRouter doesn't have health endpoint + ] + + # Debug: Print the full command + cmd_str = " ".join(str(c) for c in cmd) + # Hide API key in printed output + cmd_display = cmd_str.replace(api_key, "***API_KEY***") + print(f"Command: {cmd_display}") + print(f"Working dir: {TINKER_ATROPOS_ROOT}") + print(f"WandB run: {wandb_run_name}") + print(f" {num_steps} steps × {group_size} completions = {total_rollouts_per_model} rollouts") + + model_results = { + "model": model_id, + "name": model_info["name"], + "scale": model_info["scale"], + "wandb_run": wandb_run_name, + "output_file": str(output_file), + "steps": [], + "steps_tested": 0, + "total_completions": 0, + "correct_completions": 0, + } + + try: + # Run the process command with real-time output streaming + process = await asyncio.create_subprocess_exec( + *cmd, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + cwd=str(TINKER_ATROPOS_ROOT), + ) + + # Stream output in real-time while collecting for logs + stdout_lines = [] + stderr_lines = [] + log_file = test_output_dir / f"test_{_current_env}_{model_safe_name}.log" + + async def read_stream(stream, lines_list, prefix=""): + """Read stream line by line and print in real-time.""" + while True: + line = await stream.readline() + if not line: + break + decoded = line.decode().rstrip() + lines_list.append(decoded) + # Print progress-related lines in real-time + if any(kw in decoded.lower() for kw in ['processing', 'group', 'step', 'progress', '%', 'completed']): + print(f" {prefix}{decoded}") + + # Read both streams concurrently with timeout + try: + await asyncio.wait_for( + asyncio.gather( + read_stream(process.stdout, stdout_lines, "📊 "), + read_stream(process.stderr, stderr_lines, "⚠️ "), + ), + timeout=600, # 10 minute timeout per model + ) + except asyncio.TimeoutError: + process.kill() + raise + + await process.wait() + + # Combine output for logging + stdout_text = "\n".join(stdout_lines) + stderr_text = "\n".join(stderr_lines) + + # Write logs to files for inspection outside CLI + with open(log_file, "w") as f: + f.write(f"Command: {cmd_display}\n") + f.write(f"Working dir: {TINKER_ATROPOS_ROOT}\n") + f.write(f"Return code: {process.returncode}\n") + f.write(f"\n{'='*60}\n") + f.write(f"STDOUT:\n{'='*60}\n") + f.write(stdout_text or "(empty)\n") + f.write(f"\n{'='*60}\n") + f.write(f"STDERR:\n{'='*60}\n") + f.write(stderr_text or "(empty)\n") + + print(f" Log file: {log_file}") + + if process.returncode != 0: + model_results["error"] = f"Process exited with code {process.returncode}" + model_results["stderr"] = stderr_text[-1000:] + model_results["stdout"] = stdout_text[-1000:] + model_results["log_file"] = str(log_file) + print(f"\n ❌ Error: {model_results['error']}") + # Print last few lines of stderr for debugging + if stderr_lines: + print(" Last errors:") + for line in stderr_lines[-5:]: + print(f" {line}") + else: + print("\n ✅ Process completed successfully") + print(f" Output file: {output_file}") + print(f" File exists: {output_file.exists()}") + + # Parse the output JSONL file + if output_file.exists(): + # Read JSONL file (one JSON object per line = one step) + with open(output_file, "r") as f: + for line in f: + line = line.strip() + if not line: + continue + try: + item = json.loads(line) + scores = item.get("scores", []) + model_results["steps_tested"] += 1 + model_results["total_completions"] += len(scores) + correct = sum(1 for s in scores if s > 0) + model_results["correct_completions"] += correct + + model_results["steps"].append({ + "step": model_results["steps_tested"], + "completions": len(scores), + "correct": correct, + "scores": scores, + }) + except json.JSONDecodeError: + continue + + print(f" Completed {model_results['steps_tested']} steps") + else: + model_results["error"] = f"Output file not created: {output_file}" + + except asyncio.TimeoutError: + model_results["error"] = "Process timed out after 10 minutes" + print(" Timeout!") + except Exception as e: + model_results["error"] = str(e) + print(f" Error: {e}") + + # Calculate stats + if model_results["total_completions"] > 0: + model_results["accuracy"] = round( + model_results["correct_completions"] / model_results["total_completions"], 3 + ) + else: + model_results["accuracy"] = 0 + + if model_results["steps_tested"] > 0: + steps_with_correct = sum(1 for s in model_results["steps"] if s.get("correct", 0) > 0) + model_results["steps_with_correct"] = steps_with_correct + model_results["step_success_rate"] = round( + steps_with_correct / model_results["steps_tested"], 3 + ) + else: + model_results["steps_with_correct"] = 0 + model_results["step_success_rate"] = 0 + + print(f" Results: {model_results['correct_completions']}/{model_results['total_completions']} correct") + print(f" Accuracy: {model_results['accuracy']:.1%}") + + results["models_tested"].append(model_results) + + # Overall summary + working_models = [m for m in results["models_tested"] if m.get("steps_tested", 0) > 0] + + results["summary"] = { + "steps_requested": num_steps, + "models_tested": len(test_models), + "models_succeeded": len(working_models), + "best_model": max(working_models, key=lambda x: x.get("accuracy", 0))["model"] if working_models else None, + "avg_accuracy": round( + sum(m.get("accuracy", 0) for m in working_models) / len(working_models), 3 + ) if working_models else 0, + "environment_working": bool(working_models), + "output_directory": str(test_output_dir), + } + + return json.dumps(results, indent=2) + + +# ============================================================================ +# Requirements Check +# ============================================================================ + +def check_rl_python_version() -> bool: + """ + Check if Python version meets the minimum for RL tools. + + tinker-atropos depends on the 'tinker' package which requires Python >= 3.11. + """ + return sys.version_info >= (3, 11) + + +def check_rl_api_keys() -> bool: + """ + Check if required API keys and Python version are available. + + RL training requires: + - Python >= 3.11 (tinker package requirement) + - TINKER_API_KEY for the Tinker training API + - WANDB_API_KEY for Weights & Biases metrics + """ + if not check_rl_python_version(): + return False + tinker_key = os.getenv("TINKER_API_KEY") + wandb_key = os.getenv("WANDB_API_KEY") + return bool(tinker_key) and bool(wandb_key) + + +def get_missing_keys() -> List[str]: + """ + Get list of missing requirements for RL tools (API keys and Python version). + """ + missing = [] + if not check_rl_python_version(): + missing.append(f"Python >= 3.11 (current: {sys.version_info.major}.{sys.version_info.minor})") + if not os.getenv("TINKER_API_KEY"): + missing.append("TINKER_API_KEY") + if not os.getenv("WANDB_API_KEY"): + missing.append("WANDB_API_KEY") + return missing + + +# --------------------------------------------------------------------------- +# Schemas + Registry +# --------------------------------------------------------------------------- +from tools.registry import registry + +RL_LIST_ENVIRONMENTS_SCHEMA = {"name": "rl_list_environments", "description": "List all available RL environments. Returns environment names, paths, and descriptions. TIP: Read the file_path with file tools to understand how each environment works (verifiers, data loading, rewards).", "parameters": {"type": "object", "properties": {}, "required": []}} +RL_SELECT_ENVIRONMENT_SCHEMA = {"name": "rl_select_environment", "description": "Select an RL environment for training. Loads the environment's default configuration. After selecting, use rl_get_current_config() to see settings and rl_edit_config() to modify them.", "parameters": {"type": "object", "properties": {"name": {"type": "string", "description": "Name of the environment to select (from rl_list_environments)"}}, "required": ["name"]}} +RL_GET_CURRENT_CONFIG_SCHEMA = {"name": "rl_get_current_config", "description": "Get the current environment configuration. Returns only fields that can be modified: group_size, max_token_length, total_steps, steps_per_eval, use_wandb, wandb_name, max_num_workers.", "parameters": {"type": "object", "properties": {}, "required": []}} +RL_EDIT_CONFIG_SCHEMA = {"name": "rl_edit_config", "description": "Update a configuration field. Use rl_get_current_config() first to see all available fields for the selected environment. Each environment has different configurable options. Infrastructure settings (tokenizer, URLs, lora_rank, learning_rate) are locked.", "parameters": {"type": "object", "properties": {"field": {"type": "string", "description": "Name of the field to update (get available fields from rl_get_current_config)"}, "value": {"description": "New value for the field"}}, "required": ["field", "value"]}} +RL_START_TRAINING_SCHEMA = {"name": "rl_start_training", "description": "Start a new RL training run with the current environment and config. Most training parameters (lora_rank, learning_rate, etc.) are fixed. Use rl_edit_config() to set group_size, batch_size, wandb_project before starting. WARNING: Training takes hours.", "parameters": {"type": "object", "properties": {}, "required": []}} +RL_CHECK_STATUS_SCHEMA = {"name": "rl_check_status", "description": "Get status and metrics for a training run. RATE LIMITED: enforces 30-minute minimum between checks for the same run. Returns WandB metrics: step, state, reward_mean, loss, percent_correct.", "parameters": {"type": "object", "properties": {"run_id": {"type": "string", "description": "The run ID from rl_start_training()"}}, "required": ["run_id"]}} +RL_STOP_TRAINING_SCHEMA = {"name": "rl_stop_training", "description": "Stop a running training job. Use if metrics look bad, training is stagnant, or you want to try different settings.", "parameters": {"type": "object", "properties": {"run_id": {"type": "string", "description": "The run ID to stop"}}, "required": ["run_id"]}} +RL_GET_RESULTS_SCHEMA = {"name": "rl_get_results", "description": "Get final results and metrics for a completed training run. Returns final metrics and path to trained weights.", "parameters": {"type": "object", "properties": {"run_id": {"type": "string", "description": "The run ID to get results for"}}, "required": ["run_id"]}} +RL_LIST_RUNS_SCHEMA = {"name": "rl_list_runs", "description": "List all training runs (active and completed) with their status.", "parameters": {"type": "object", "properties": {}, "required": []}} +RL_TEST_INFERENCE_SCHEMA = {"name": "rl_test_inference", "description": "Quick inference test for any environment. Runs a few steps of inference + scoring using OpenRouter. Default: 3 steps x 16 completions = 48 rollouts per model, testing 3 models = 144 total. Tests environment loading, prompt construction, inference parsing, and verifier logic. Use BEFORE training to catch issues.", "parameters": {"type": "object", "properties": {"num_steps": {"type": "integer", "description": "Number of steps to run (default: 3, recommended max for testing)", "default": 3}, "group_size": {"type": "integer", "description": "Completions per step (default: 16, like training)", "default": 16}, "models": {"type": "array", "items": {"type": "string"}, "description": "Optional list of OpenRouter model IDs. Default: qwen/qwen3-8b, z-ai/glm-4.7-flash, minimax/minimax-m2.7"}}, "required": []}} + +_rl_env = ["TINKER_API_KEY", "WANDB_API_KEY"] + +registry.register(name="rl_list_environments", emoji="🧪", toolset="rl", schema=RL_LIST_ENVIRONMENTS_SCHEMA, + handler=lambda args, **kw: rl_list_environments(), check_fn=check_rl_api_keys, requires_env=_rl_env, is_async=True) +registry.register(name="rl_select_environment", emoji="🧪", toolset="rl", schema=RL_SELECT_ENVIRONMENT_SCHEMA, + handler=lambda args, **kw: rl_select_environment(name=args.get("name", "")), check_fn=check_rl_api_keys, requires_env=_rl_env, is_async=True) +registry.register(name="rl_get_current_config", emoji="🧪", toolset="rl", schema=RL_GET_CURRENT_CONFIG_SCHEMA, + handler=lambda args, **kw: rl_get_current_config(), check_fn=check_rl_api_keys, requires_env=_rl_env, is_async=True) +registry.register(name="rl_edit_config", emoji="🧪", toolset="rl", schema=RL_EDIT_CONFIG_SCHEMA, + handler=lambda args, **kw: rl_edit_config(field=args.get("field", ""), value=args.get("value")), check_fn=check_rl_api_keys, requires_env=_rl_env, is_async=True) +registry.register(name="rl_start_training", emoji="🧪", toolset="rl", schema=RL_START_TRAINING_SCHEMA, + handler=lambda args, **kw: rl_start_training(), check_fn=check_rl_api_keys, requires_env=_rl_env, is_async=True) +registry.register(name="rl_check_status", emoji="🧪", toolset="rl", schema=RL_CHECK_STATUS_SCHEMA, + handler=lambda args, **kw: rl_check_status(run_id=args.get("run_id", "")), check_fn=check_rl_api_keys, requires_env=_rl_env, is_async=True) +registry.register(name="rl_stop_training", emoji="🧪", toolset="rl", schema=RL_STOP_TRAINING_SCHEMA, + handler=lambda args, **kw: rl_stop_training(run_id=args.get("run_id", "")), check_fn=check_rl_api_keys, requires_env=_rl_env, is_async=True) +registry.register(name="rl_get_results", emoji="🧪", toolset="rl", schema=RL_GET_RESULTS_SCHEMA, + handler=lambda args, **kw: rl_get_results(run_id=args.get("run_id", "")), check_fn=check_rl_api_keys, requires_env=_rl_env, is_async=True) +registry.register(name="rl_list_runs", emoji="🧪", toolset="rl", schema=RL_LIST_RUNS_SCHEMA, + handler=lambda args, **kw: rl_list_runs(), check_fn=check_rl_api_keys, requires_env=_rl_env, is_async=True) +registry.register(name="rl_test_inference", emoji="🧪", toolset="rl", schema=RL_TEST_INFERENCE_SCHEMA, + handler=lambda args, **kw: rl_test_inference(num_steps=args.get("num_steps", 3), group_size=args.get("group_size", 16), models=args.get("models")), + check_fn=check_rl_api_keys, requires_env=_rl_env, is_async=True) diff --git a/mindcli/_vendor/tools/send_message_tool.py b/mindcli/_vendor/tools/send_message_tool.py new file mode 100644 index 0000000..391e03b --- /dev/null +++ b/mindcli/_vendor/tools/send_message_tool.py @@ -0,0 +1,1106 @@ +"""Send Message Tool -- cross-channel messaging via platform APIs. + +Sends a message to a user or channel on any connected messaging platform +(Telegram, Discord, Slack). Supports listing available targets and resolving +human-friendly channel names to IDs. Works in both CLI and gateway contexts. +""" + +import json +import logging +import os +import re +import ssl +import time + +from agent.redact import redact_sensitive_text + +logger = logging.getLogger(__name__) + +_TELEGRAM_TOPIC_TARGET_RE = re.compile(r"^\s*(-?\d+)(?::(\d+))?\s*$") +_FEISHU_TARGET_RE = re.compile(r"^\s*((?:oc|ou|on|chat|open)_[-A-Za-z0-9]+)(?::([-A-Za-z0-9_]+))?\s*$") +_WEIXIN_TARGET_RE = re.compile(r"^\s*((?:wxid|gh|v\d+|wm|wb)_[A-Za-z0-9_-]+|[A-Za-z0-9._-]+@chatroom|filehelper)\s*$") +# Discord snowflake IDs are numeric, same regex pattern as Telegram topic targets. +_NUMERIC_TOPIC_RE = _TELEGRAM_TOPIC_TARGET_RE +_IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".webp", ".gif"} +_VIDEO_EXTS = {".mp4", ".mov", ".avi", ".mkv", ".3gp"} +_AUDIO_EXTS = {".ogg", ".opus", ".mp3", ".wav", ".m4a"} +_VOICE_EXTS = {".ogg", ".opus"} +_URL_SECRET_QUERY_RE = re.compile( + r"([?&](?:access_token|api[_-]?key|auth[_-]?token|token|signature|sig)=)([^&#\s]+)", + re.IGNORECASE, +) +_GENERIC_SECRET_ASSIGN_RE = re.compile( + r"\b(access_token|api[_-]?key|auth[_-]?token|signature|sig)\s*=\s*([^\s,;]+)", + re.IGNORECASE, +) + + +def _sanitize_error_text(text) -> str: + """Redact secrets from error text before surfacing it to users/models.""" + redacted = redact_sensitive_text(text) + redacted = _URL_SECRET_QUERY_RE.sub(lambda m: f"{m.group(1)}***", redacted) + redacted = _GENERIC_SECRET_ASSIGN_RE.sub(lambda m: f"{m.group(1)}=***", redacted) + return redacted + + +def _error(message: str) -> dict: + """Build a standardized error payload with redacted content.""" + return {"error": _sanitize_error_text(message)} + + +SEND_MESSAGE_SCHEMA = { + "name": "send_message", + "description": ( + "Send a message to a connected messaging platform, or list available targets.\n\n" + "IMPORTANT: When the user asks to send to a specific channel or person " + "(not just a bare platform name), call send_message(action='list') FIRST to see " + "available targets, then send to the correct one.\n" + "If the user just says a platform name like 'send to telegram', send directly " + "to the home channel without listing first." + ), + "parameters": { + "type": "object", + "properties": { + "action": { + "type": "string", + "enum": ["send", "list"], + "description": "Action to perform. 'send' (default) sends a message. 'list' returns all available channels/contacts across connected platforms." + }, + "target": { + "type": "string", + "description": "Delivery target. Format: 'platform' (uses home channel), 'platform:#channel-name', 'platform:chat_id', or 'platform:chat_id:thread_id' for Telegram topics and Discord threads. Examples: 'telegram', 'telegram:-1001234567890:17585', 'discord:999888777:555444333', 'discord:#bot-home', 'slack:#engineering', 'signal:+155****4567'" + }, + "message": { + "type": "string", + "description": "The message text to send" + } + }, + "required": [] + } +} + + +def send_message_tool(args, **kw): + """Handle cross-channel send_message tool calls.""" + action = args.get("action", "send") + + if action == "list": + return _handle_list() + + return _handle_send(args) + + +def _handle_list(): + """Return formatted list of available messaging targets.""" + try: + from gateway.channel_directory import format_directory_for_display + return json.dumps({"targets": format_directory_for_display()}) + except Exception as e: + return json.dumps(_error(f"Failed to load channel directory: {e}")) + + +def _handle_send(args): + """Send a message to a platform target.""" + target = args.get("target", "") + message = args.get("message", "") + if not target or not message: + return tool_error("Both 'target' and 'message' are required when action='send'") + + parts = target.split(":", 1) + platform_name = parts[0].strip().lower() + target_ref = parts[1].strip() if len(parts) > 1 else None + chat_id = None + thread_id = None + + if target_ref: + chat_id, thread_id, is_explicit = _parse_target_ref(platform_name, target_ref) + else: + is_explicit = False + + # Resolve human-friendly channel names to numeric IDs + if target_ref and not is_explicit: + try: + from gateway.channel_directory import resolve_channel_name + resolved = resolve_channel_name(platform_name, target_ref) + if resolved: + chat_id, thread_id, _ = _parse_target_ref(platform_name, resolved) + else: + return json.dumps({ + "error": f"Could not resolve '{target_ref}' on {platform_name}. " + f"Use send_message(action='list') to see available targets." + }) + except Exception: + return json.dumps({ + "error": f"Could not resolve '{target_ref}' on {platform_name}. " + f"Try using a numeric channel ID instead." + }) + + from tools.interrupt import is_interrupted + if is_interrupted(): + return tool_error("Interrupted") + + try: + from gateway.config import load_gateway_config, Platform + config = load_gateway_config() + except Exception as e: + return json.dumps(_error(f"Failed to load gateway config: {e}")) + + platform_map = { + "telegram": Platform.TELEGRAM, + "discord": Platform.DISCORD, + "slack": Platform.SLACK, + "whatsapp": Platform.WHATSAPP, + "signal": Platform.SIGNAL, + "bluebubbles": Platform.BLUEBUBBLES, + "qqbot": Platform.QQBOT, + "matrix": Platform.MATRIX, + "mattermost": Platform.MATTERMOST, + "homeassistant": Platform.HOMEASSISTANT, + "dingtalk": Platform.DINGTALK, + "feishu": Platform.FEISHU, + "wecom": Platform.WECOM, + "wecom_callback": Platform.WECOM_CALLBACK, + "weixin": Platform.WEIXIN, + "email": Platform.EMAIL, + "sms": Platform.SMS, + } + platform = platform_map.get(platform_name) + if not platform: + avail = ", ".join(platform_map.keys()) + return tool_error(f"Unknown platform: {platform_name}. Available: {avail}") + + pconfig = config.platforms.get(platform) + if not pconfig or not pconfig.enabled: + return tool_error(f"Platform '{platform_name}' is not configured. Set up credentials in ~/.hermes/config.yaml or environment variables.") + + from gateway.platforms.base import BasePlatformAdapter + + media_files, cleaned_message = BasePlatformAdapter.extract_media(message) + mirror_text = cleaned_message.strip() or _describe_media_for_mirror(media_files) + + used_home_channel = False + if not chat_id: + home = config.get_home_channel(platform) + if home: + chat_id = home.chat_id + used_home_channel = True + else: + return json.dumps({ + "error": f"No home channel set for {platform_name} to determine where to send the message. " + f"Either specify a channel directly with '{platform_name}:CHANNEL_NAME', " + f"or set a home channel via: hermes config set {platform_name.upper()}_HOME_CHANNEL " + }) + + duplicate_skip = _maybe_skip_cron_duplicate_send(platform_name, chat_id, thread_id) + if duplicate_skip: + return json.dumps(duplicate_skip) + + try: + from model_tools import _run_async + result = _run_async( + _send_to_platform( + platform, + pconfig, + chat_id, + cleaned_message, + thread_id=thread_id, + media_files=media_files, + ) + ) + if used_home_channel and isinstance(result, dict) and result.get("success"): + result["note"] = f"Sent to {platform_name} home channel (chat_id: {chat_id})" + + # Mirror the sent message into the target's gateway session + if isinstance(result, dict) and result.get("success") and mirror_text: + try: + from gateway.mirror import mirror_to_session + from gateway.session_context import get_session_env + source_label = get_session_env("HERMES_SESSION_PLATFORM", "cli") + if mirror_to_session(platform_name, chat_id, mirror_text, source_label=source_label, thread_id=thread_id): + result["mirrored"] = True + except Exception: + pass + + if isinstance(result, dict) and "error" in result: + result["error"] = _sanitize_error_text(result["error"]) + return json.dumps(result) + except Exception as e: + return json.dumps(_error(f"Send failed: {e}")) + + +def _parse_target_ref(platform_name: str, target_ref: str): + """Parse a tool target into chat_id/thread_id and whether it is explicit.""" + if platform_name == "telegram": + match = _TELEGRAM_TOPIC_TARGET_RE.fullmatch(target_ref) + if match: + return match.group(1), match.group(2), True + if platform_name == "feishu": + match = _FEISHU_TARGET_RE.fullmatch(target_ref) + if match: + return match.group(1), match.group(2), True + if platform_name == "discord": + match = _NUMERIC_TOPIC_RE.fullmatch(target_ref) + if match: + return match.group(1), match.group(2), True + if platform_name == "weixin": + match = _WEIXIN_TARGET_RE.fullmatch(target_ref) + if match: + return match.group(1), None, True + if target_ref.lstrip("-").isdigit(): + return target_ref, None, True + return None, None, False + + +def _describe_media_for_mirror(media_files): + """Return a human-readable mirror summary when a message only contains media.""" + if not media_files: + return "" + if len(media_files) == 1: + media_path, is_voice = media_files[0] + ext = os.path.splitext(media_path)[1].lower() + if is_voice and ext in _VOICE_EXTS: + return "[Sent voice message]" + if ext in _IMAGE_EXTS: + return "[Sent image attachment]" + if ext in _VIDEO_EXTS: + return "[Sent video attachment]" + if ext in _AUDIO_EXTS: + return "[Sent audio attachment]" + return "[Sent document attachment]" + return f"[Sent {len(media_files)} media attachments]" + + +def _get_cron_auto_delivery_target(): + """Return the cron scheduler's auto-delivery target for the current run, if any.""" + platform = os.getenv("HERMES_CRON_AUTO_DELIVER_PLATFORM", "").strip().lower() + chat_id = os.getenv("HERMES_CRON_AUTO_DELIVER_CHAT_ID", "").strip() + if not platform or not chat_id: + return None + thread_id = os.getenv("HERMES_CRON_AUTO_DELIVER_THREAD_ID", "").strip() or None + return { + "platform": platform, + "chat_id": chat_id, + "thread_id": thread_id, + } + + +def _maybe_skip_cron_duplicate_send(platform_name: str, chat_id: str, thread_id: str | None): + """Skip redundant cron send_message calls when the scheduler will auto-deliver there.""" + auto_target = _get_cron_auto_delivery_target() + if not auto_target: + return None + + same_target = ( + auto_target["platform"] == platform_name + and str(auto_target["chat_id"]) == str(chat_id) + and auto_target.get("thread_id") == thread_id + ) + if not same_target: + return None + + target_label = f"{platform_name}:{chat_id}" + if thread_id is not None: + target_label += f":{thread_id}" + + return { + "success": True, + "skipped": True, + "reason": "cron_auto_delivery_duplicate_target", + "target": target_label, + "note": ( + f"Skipped send_message to {target_label}. This cron job will already auto-deliver " + "its final response to that same target. Put the intended user-facing content in " + "your final response instead, or use a different target if you want an additional message." + ), + } + + +async def _send_to_platform(platform, pconfig, chat_id, message, thread_id=None, media_files=None): + """Route a message to the appropriate platform sender. + + Long messages are automatically chunked to fit within platform limits + using the same smart-splitting algorithm as the gateway adapters + (preserves code-block boundaries, adds part indicators). + """ + from gateway.config import Platform + from gateway.platforms.base import BasePlatformAdapter, utf16_len + from gateway.platforms.telegram import TelegramAdapter + from gateway.platforms.discord import DiscordAdapter + from gateway.platforms.slack import SlackAdapter + + # Feishu adapter import is optional (requires lark-oapi) + try: + from gateway.platforms.feishu import FeishuAdapter + _feishu_available = True + except ImportError: + _feishu_available = False + + media_files = media_files or [] + + if platform == Platform.SLACK and message: + try: + slack_adapter = SlackAdapter.__new__(SlackAdapter) + message = slack_adapter.format_message(message) + except Exception: + logger.debug("Failed to apply Slack mrkdwn formatting in _send_to_platform", exc_info=True) + + # Platform message length limits (from adapter class attributes) + _MAX_LENGTHS = { + Platform.TELEGRAM: TelegramAdapter.MAX_MESSAGE_LENGTH, + Platform.DISCORD: DiscordAdapter.MAX_MESSAGE_LENGTH, + Platform.SLACK: SlackAdapter.MAX_MESSAGE_LENGTH, + } + if _feishu_available: + _MAX_LENGTHS[Platform.FEISHU] = FeishuAdapter.MAX_MESSAGE_LENGTH + + # Smart-chunk the message to fit within platform limits. + # For short messages or platforms without a known limit this is a no-op. + # Telegram measures length in UTF-16 code units, not Unicode codepoints. + max_len = _MAX_LENGTHS.get(platform) + if max_len: + _len_fn = utf16_len if platform == Platform.TELEGRAM else None + chunks = BasePlatformAdapter.truncate_message(message, max_len, len_fn=_len_fn) + else: + chunks = [message] + + # --- Telegram: special handling for media attachments --- + if platform == Platform.TELEGRAM: + last_result = None + for i, chunk in enumerate(chunks): + is_last = (i == len(chunks) - 1) + result = await _send_telegram( + pconfig.token, + chat_id, + chunk, + media_files=media_files if is_last else [], + thread_id=thread_id, + ) + if isinstance(result, dict) and result.get("error"): + return result + last_result = result + return last_result + + # --- Weixin: use the native one-shot adapter helper for text + media --- + if platform == Platform.WEIXIN: + return await _send_weixin(pconfig, chat_id, message, media_files=media_files) + + # --- Non-Telegram platforms --- + if media_files and not message.strip(): + return { + "error": ( + f"send_message MEDIA delivery is currently only supported for telegram; " + f"target {platform.value} had only media attachments" + ) + } + warning = None + if media_files: + warning = ( + f"MEDIA attachments were omitted for {platform.value}; " + "native send_message media delivery is currently only supported for telegram" + ) + + last_result = None + for chunk in chunks: + if platform == Platform.DISCORD: + result = await _send_discord(pconfig.token, chat_id, chunk, thread_id=thread_id) + elif platform == Platform.SLACK: + result = await _send_slack(pconfig.token, chat_id, chunk) + elif platform == Platform.WHATSAPP: + result = await _send_whatsapp(pconfig.extra, chat_id, chunk) + elif platform == Platform.SIGNAL: + result = await _send_signal(pconfig.extra, chat_id, chunk) + elif platform == Platform.EMAIL: + result = await _send_email(pconfig.extra, chat_id, chunk) + elif platform == Platform.SMS: + result = await _send_sms(pconfig.api_key, chat_id, chunk) + elif platform == Platform.MATTERMOST: + result = await _send_mattermost(pconfig.token, pconfig.extra, chat_id, chunk) + elif platform == Platform.MATRIX: + result = await _send_matrix(pconfig.token, pconfig.extra, chat_id, chunk) + elif platform == Platform.HOMEASSISTANT: + result = await _send_homeassistant(pconfig.token, pconfig.extra, chat_id, chunk) + elif platform == Platform.DINGTALK: + result = await _send_dingtalk(pconfig.extra, chat_id, chunk) + elif platform == Platform.FEISHU: + result = await _send_feishu(pconfig, chat_id, chunk, thread_id=thread_id) + elif platform == Platform.WECOM: + result = await _send_wecom(pconfig.extra, chat_id, chunk) + elif platform == Platform.BLUEBUBBLES: + result = await _send_bluebubbles(pconfig.extra, chat_id, chunk) + elif platform == Platform.QQBOT: + result = await _send_qqbot(pconfig, chat_id, chunk) + else: + result = {"error": f"Direct sending not yet implemented for {platform.value}"} + + if isinstance(result, dict) and result.get("error"): + return result + last_result = result + + if warning and isinstance(last_result, dict) and last_result.get("success"): + warnings = list(last_result.get("warnings", [])) + warnings.append(warning) + last_result["warnings"] = warnings + return last_result + + +async def _send_telegram(token, chat_id, message, media_files=None, thread_id=None): + """Send via Telegram Bot API (one-shot, no polling needed). + + Applies markdown→MarkdownV2 formatting (same as the gateway adapter) + so that bold, links, and headers render correctly. If the message + already contains HTML tags, it is sent with ``parse_mode='HTML'`` + instead, bypassing MarkdownV2 conversion. + """ + try: + from telegram import Bot + from telegram.constants import ParseMode + + # Auto-detect HTML tags — if present, skip MarkdownV2 and send as HTML. + # Inspired by github.com/ashaney — PR #1568. + _has_html = bool(re.search(r'<[a-zA-Z/][^>]*>', message)) + + if _has_html: + formatted = message + send_parse_mode = ParseMode.HTML + else: + # Reuse the gateway adapter's format_message for markdown→MarkdownV2 + try: + from gateway.platforms.telegram import TelegramAdapter + _adapter = TelegramAdapter.__new__(TelegramAdapter) + formatted = _adapter.format_message(message) + except Exception: + # Fallback: send as-is if formatting unavailable + formatted = message + send_parse_mode = ParseMode.MARKDOWN_V2 + + bot = Bot(token=token) + int_chat_id = int(chat_id) + media_files = media_files or [] + thread_kwargs = {} + if thread_id is not None: + thread_kwargs["message_thread_id"] = int(thread_id) + + last_msg = None + warnings = [] + + if formatted.strip(): + try: + last_msg = await bot.send_message( + chat_id=int_chat_id, text=formatted, + parse_mode=send_parse_mode, **thread_kwargs + ) + except Exception as md_error: + # Parse failed, fall back to plain text + if "parse" in str(md_error).lower() or "markdown" in str(md_error).lower() or "html" in str(md_error).lower(): + logger.warning( + "Parse mode %s failed in _send_telegram, falling back to plain text: %s", + send_parse_mode, + _sanitize_error_text(md_error), + ) + if not _has_html: + try: + from gateway.platforms.telegram import _strip_mdv2 + plain = _strip_mdv2(formatted) + except Exception: + plain = message + else: + plain = message + last_msg = await bot.send_message( + chat_id=int_chat_id, text=plain, + parse_mode=None, **thread_kwargs + ) + else: + raise + + for media_path, is_voice in media_files: + if not os.path.exists(media_path): + warning = f"Media file not found, skipping: {media_path}" + logger.warning(warning) + warnings.append(warning) + continue + + ext = os.path.splitext(media_path)[1].lower() + try: + with open(media_path, "rb") as f: + if ext in _IMAGE_EXTS: + last_msg = await bot.send_photo( + chat_id=int_chat_id, photo=f, **thread_kwargs + ) + elif ext in _VIDEO_EXTS: + last_msg = await bot.send_video( + chat_id=int_chat_id, video=f, **thread_kwargs + ) + elif ext in _VOICE_EXTS and is_voice: + last_msg = await bot.send_voice( + chat_id=int_chat_id, voice=f, **thread_kwargs + ) + elif ext in _AUDIO_EXTS: + last_msg = await bot.send_audio( + chat_id=int_chat_id, audio=f, **thread_kwargs + ) + else: + last_msg = await bot.send_document( + chat_id=int_chat_id, document=f, **thread_kwargs + ) + except Exception as e: + warning = _sanitize_error_text(f"Failed to send media {media_path}: {e}") + logger.error(warning) + warnings.append(warning) + + if last_msg is None: + error = "No deliverable text or media remained after processing MEDIA tags" + if warnings: + return {"error": error, "warnings": warnings} + return {"error": error} + + result = { + "success": True, + "platform": "telegram", + "chat_id": chat_id, + "message_id": str(last_msg.message_id), + } + if warnings: + result["warnings"] = warnings + return result + except ImportError: + return {"error": "python-telegram-bot not installed. Run: pip install python-telegram-bot"} + except Exception as e: + return _error(f"Telegram send failed: {e}") + + +async def _send_discord(token, chat_id, message, thread_id=None): + """Send a single message via Discord REST API (no websocket client needed). + + Chunking is handled by _send_to_platform() before this is called. + + When thread_id is provided, the message is sent directly to that thread + via the /channels/{thread_id}/messages endpoint. + """ + try: + import aiohttp + except ImportError: + return {"error": "aiohttp not installed. Run: pip install aiohttp"} + try: + from gateway.platforms.base import resolve_proxy_url, proxy_kwargs_for_aiohttp + _proxy = resolve_proxy_url(platform_env_var="DISCORD_PROXY") + _sess_kw, _req_kw = proxy_kwargs_for_aiohttp(_proxy) + # Thread endpoint: Discord threads are channels; send directly to the thread ID. + if thread_id: + url = f"https://discord.com/api/v10/channels/{thread_id}/messages" + else: + url = f"https://discord.com/api/v10/channels/{chat_id}/messages" + headers = {"Authorization": f"Bot {token}", "Content-Type": "application/json"} + async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30), **_sess_kw) as session: + async with session.post(url, headers=headers, json={"content": message}, **_req_kw) as resp: + if resp.status not in (200, 201): + body = await resp.text() + return _error(f"Discord API error ({resp.status}): {body}") + data = await resp.json() + return {"success": True, "platform": "discord", "chat_id": chat_id, "message_id": data.get("id")} + except Exception as e: + return _error(f"Discord send failed: {e}") + + +async def _send_slack(token, chat_id, message): + """Send via Slack Web API.""" + try: + import aiohttp + except ImportError: + return {"error": "aiohttp not installed. Run: pip install aiohttp"} + try: + from gateway.platforms.base import resolve_proxy_url, proxy_kwargs_for_aiohttp + _proxy = resolve_proxy_url() + _sess_kw, _req_kw = proxy_kwargs_for_aiohttp(_proxy) + url = "https://slack.com/api/chat.postMessage" + headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"} + async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30), **_sess_kw) as session: + payload = {"channel": chat_id, "text": message, "mrkdwn": True} + async with session.post(url, headers=headers, json=payload, **_req_kw) as resp: + data = await resp.json() + if data.get("ok"): + return {"success": True, "platform": "slack", "chat_id": chat_id, "message_id": data.get("ts")} + return _error(f"Slack API error: {data.get('error', 'unknown')}") + except Exception as e: + return _error(f"Slack send failed: {e}") + + +async def _send_whatsapp(extra, chat_id, message): + """Send via the local WhatsApp bridge HTTP API.""" + try: + import aiohttp + except ImportError: + return {"error": "aiohttp not installed. Run: pip install aiohttp"} + try: + bridge_port = extra.get("bridge_port", 3000) + async with aiohttp.ClientSession() as session: + async with session.post( + f"http://localhost:{bridge_port}/send", + json={"chatId": chat_id, "message": message}, + timeout=aiohttp.ClientTimeout(total=30), + ) as resp: + if resp.status == 200: + data = await resp.json() + return { + "success": True, + "platform": "whatsapp", + "chat_id": chat_id, + "message_id": data.get("messageId"), + } + body = await resp.text() + return _error(f"WhatsApp bridge error ({resp.status}): {body}") + except Exception as e: + return _error(f"WhatsApp send failed: {e}") + + +async def _send_signal(extra, chat_id, message): + """Send via signal-cli JSON-RPC API.""" + try: + import httpx + except ImportError: + return {"error": "httpx not installed"} + try: + http_url = extra.get("http_url", "http://127.0.0.1:8080").rstrip("/") + account = extra.get("account", "") + if not account: + return {"error": "Signal account not configured"} + + params = {"account": account, "message": message} + if chat_id.startswith("group:"): + params["groupId"] = chat_id[6:] + else: + params["recipient"] = [chat_id] + + payload = { + "jsonrpc": "2.0", + "method": "send", + "params": params, + "id": f"send_{int(time.time() * 1000)}", + } + + async with httpx.AsyncClient(timeout=30.0) as client: + resp = await client.post(f"{http_url}/api/v1/rpc", json=payload) + resp.raise_for_status() + data = resp.json() + if "error" in data: + return _error(f"Signal RPC error: {data['error']}") + return {"success": True, "platform": "signal", "chat_id": chat_id} + except Exception as e: + return _error(f"Signal send failed: {e}") + + +async def _send_email(extra, chat_id, message): + """Send via SMTP (one-shot, no persistent connection needed).""" + import smtplib + from email.mime.text import MIMEText + + address = extra.get("address") or os.getenv("EMAIL_ADDRESS", "") + password = os.getenv("EMAIL_PASSWORD", "") + smtp_host = extra.get("smtp_host") or os.getenv("EMAIL_SMTP_HOST", "") + try: + smtp_port = int(os.getenv("EMAIL_SMTP_PORT", "587")) + except (ValueError, TypeError): + smtp_port = 587 + + if not all([address, password, smtp_host]): + return {"error": "Email not configured (EMAIL_ADDRESS, EMAIL_PASSWORD, EMAIL_SMTP_HOST required)"} + + try: + msg = MIMEText(message, "plain", "utf-8") + msg["From"] = address + msg["To"] = chat_id + msg["Subject"] = "Hermes Agent" + + server = smtplib.SMTP(smtp_host, smtp_port) + server.starttls(context=ssl.create_default_context()) + server.login(address, password) + server.send_message(msg) + server.quit() + return {"success": True, "platform": "email", "chat_id": chat_id} + except Exception as e: + return _error(f"Email send failed: {e}") + + +async def _send_sms(auth_token, chat_id, message): + """Send a single SMS via Twilio REST API. + + Uses HTTP Basic auth (Account SID : Auth Token) and form-encoded POST. + Chunking is handled by _send_to_platform() before this is called. + """ + try: + import aiohttp + except ImportError: + return {"error": "aiohttp not installed. Run: pip install aiohttp"} + + import base64 + + account_sid = os.getenv("TWILIO_ACCOUNT_SID", "") + from_number = os.getenv("TWILIO_PHONE_NUMBER", "") + if not account_sid or not auth_token or not from_number: + return {"error": "SMS not configured (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER required)"} + + # Strip markdown — SMS renders it as literal characters + message = re.sub(r"\*\*(.+?)\*\*", r"\1", message, flags=re.DOTALL) + message = re.sub(r"\*(.+?)\*", r"\1", message, flags=re.DOTALL) + message = re.sub(r"__(.+?)__", r"\1", message, flags=re.DOTALL) + message = re.sub(r"_(.+?)_", r"\1", message, flags=re.DOTALL) + message = re.sub(r"```[a-z]*\n?", "", message) + message = re.sub(r"`(.+?)`", r"\1", message) + message = re.sub(r"^#{1,6}\s+", "", message, flags=re.MULTILINE) + message = re.sub(r"\[([^\]]+)\]\([^\)]+\)", r"\1", message) + message = re.sub(r"\n{3,}", "\n\n", message) + message = message.strip() + + try: + from gateway.platforms.base import resolve_proxy_url, proxy_kwargs_for_aiohttp + _proxy = resolve_proxy_url() + _sess_kw, _req_kw = proxy_kwargs_for_aiohttp(_proxy) + creds = f"{account_sid}:{auth_token}" + encoded = base64.b64encode(creds.encode("ascii")).decode("ascii") + url = f"https://api.twilio.com/2010-04-01/Accounts/{account_sid}/Messages.json" + headers = {"Authorization": f"Basic {encoded}"} + + async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30), **_sess_kw) as session: + form_data = aiohttp.FormData() + form_data.add_field("From", from_number) + form_data.add_field("To", chat_id) + form_data.add_field("Body", message) + + async with session.post(url, data=form_data, headers=headers, **_req_kw) as resp: + body = await resp.json() + if resp.status >= 400: + error_msg = body.get("message", str(body)) + return _error(f"Twilio API error ({resp.status}): {error_msg}") + msg_sid = body.get("sid", "") + return {"success": True, "platform": "sms", "chat_id": chat_id, "message_id": msg_sid} + except Exception as e: + return _error(f"SMS send failed: {e}") + + +async def _send_mattermost(token, extra, chat_id, message): + """Send via Mattermost REST API.""" + try: + import aiohttp + except ImportError: + return {"error": "aiohttp not installed. Run: pip install aiohttp"} + try: + base_url = (extra.get("url") or os.getenv("MATTERMOST_URL", "")).rstrip("/") + token = token or os.getenv("MATTERMOST_TOKEN", "") + if not base_url or not token: + return {"error": "Mattermost not configured (MATTERMOST_URL, MATTERMOST_TOKEN required)"} + url = f"{base_url}/api/v4/posts" + headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"} + async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30)) as session: + async with session.post(url, headers=headers, json={"channel_id": chat_id, "message": message}) as resp: + if resp.status not in (200, 201): + body = await resp.text() + return _error(f"Mattermost API error ({resp.status}): {body}") + data = await resp.json() + return {"success": True, "platform": "mattermost", "chat_id": chat_id, "message_id": data.get("id")} + except Exception as e: + return _error(f"Mattermost send failed: {e}") + + +async def _send_matrix(token, extra, chat_id, message): + """Send via Matrix Client-Server API. + + Converts markdown to HTML for rich rendering in Matrix clients. + Falls back to plain text if the ``markdown`` library is not installed. + """ + try: + import aiohttp + except ImportError: + return {"error": "aiohttp not installed. Run: pip install aiohttp"} + try: + homeserver = (extra.get("homeserver") or os.getenv("MATRIX_HOMESERVER", "")).rstrip("/") + token = token or os.getenv("MATRIX_ACCESS_TOKEN", "") + if not homeserver or not token: + return {"error": "Matrix not configured (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN required)"} + txn_id = f"hermes_{int(time.time() * 1000)}_{os.urandom(4).hex()}" + url = f"{homeserver}/_matrix/client/v3/rooms/{chat_id}/send/m.room.message/{txn_id}" + headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"} + + # Build message payload with optional HTML formatted_body. + payload = {"msgtype": "m.text", "body": message} + try: + import markdown as _md + html = _md.markdown(message, extensions=["fenced_code", "tables"]) + # Convert h1-h6 to bold for Element X compatibility. + html = re.sub(r"(.*?)", r"\1", html) + payload["format"] = "org.matrix.custom.html" + payload["formatted_body"] = html + except ImportError: + pass + + async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30)) as session: + async with session.put(url, headers=headers, json=payload) as resp: + if resp.status not in (200, 201): + body = await resp.text() + return _error(f"Matrix API error ({resp.status}): {body}") + data = await resp.json() + return {"success": True, "platform": "matrix", "chat_id": chat_id, "message_id": data.get("event_id")} + except Exception as e: + return _error(f"Matrix send failed: {e}") + + +async def _send_homeassistant(token, extra, chat_id, message): + """Send via Home Assistant notify service.""" + try: + import aiohttp + except ImportError: + return {"error": "aiohttp not installed. Run: pip install aiohttp"} + try: + hass_url = (extra.get("url") or os.getenv("HASS_URL", "")).rstrip("/") + token = token or os.getenv("HASS_TOKEN", "") + if not hass_url or not token: + return {"error": "Home Assistant not configured (HASS_URL, HASS_TOKEN required)"} + url = f"{hass_url}/api/services/notify/notify" + headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"} + async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30)) as session: + async with session.post(url, headers=headers, json={"message": message, "target": chat_id}) as resp: + if resp.status not in (200, 201): + body = await resp.text() + return _error(f"Home Assistant API error ({resp.status}): {body}") + return {"success": True, "platform": "homeassistant", "chat_id": chat_id} + except Exception as e: + return _error(f"Home Assistant send failed: {e}") + + +async def _send_dingtalk(extra, chat_id, message): + """Send via DingTalk robot webhook. + + Note: The gateway's DingTalk adapter uses per-session webhook URLs from + incoming messages (dingtalk-stream SDK). For cross-platform send_message + delivery we use a static robot webhook URL instead, which must be + configured via ``DINGTALK_WEBHOOK_URL`` env var or ``webhook_url`` in the + platform's extra config. + """ + try: + import httpx + except ImportError: + return {"error": "httpx not installed"} + try: + webhook_url = extra.get("webhook_url") or os.getenv("DINGTALK_WEBHOOK_URL", "") + if not webhook_url: + return {"error": "DingTalk not configured. Set DINGTALK_WEBHOOK_URL env var or webhook_url in dingtalk platform extra config."} + async with httpx.AsyncClient(timeout=30.0) as client: + resp = await client.post( + webhook_url, + json={"msgtype": "text", "text": {"content": message}}, + ) + resp.raise_for_status() + data = resp.json() + if data.get("errcode", 0) != 0: + return _error(f"DingTalk API error: {data.get('errmsg', 'unknown')}") + return {"success": True, "platform": "dingtalk", "chat_id": chat_id} + except Exception as e: + return _error(f"DingTalk send failed: {e}") + + +async def _send_wecom(extra, chat_id, message): + """Send via WeCom using the adapter's WebSocket send pipeline.""" + try: + from gateway.platforms.wecom import WeComAdapter, check_wecom_requirements + if not check_wecom_requirements(): + return {"error": "WeCom requirements not met. Need aiohttp + WECOM_BOT_ID/SECRET."} + except ImportError: + return {"error": "WeCom adapter not available."} + + try: + from gateway.config import PlatformConfig + pconfig = PlatformConfig(extra=extra) + adapter = WeComAdapter(pconfig) + connected = await adapter.connect() + if not connected: + return _error(f"WeCom: failed to connect - {adapter.fatal_error_message or 'unknown error'}") + try: + result = await adapter.send(chat_id, message) + if not result.success: + return _error(f"WeCom send failed: {result.error}") + return {"success": True, "platform": "wecom", "chat_id": chat_id, "message_id": result.message_id} + finally: + await adapter.disconnect() + except Exception as e: + return _error(f"WeCom send failed: {e}") + + +async def _send_weixin(pconfig, chat_id, message, media_files=None): + """Send via Weixin iLink using the native adapter helper.""" + try: + from gateway.platforms.weixin import check_weixin_requirements, send_weixin_direct + if not check_weixin_requirements(): + return {"error": "Weixin requirements not met. Need aiohttp + cryptography."} + except ImportError: + return {"error": "Weixin adapter not available."} + + try: + return await send_weixin_direct( + extra=pconfig.extra, + token=pconfig.token, + chat_id=chat_id, + message=message, + media_files=media_files, + ) + except Exception as e: + return _error(f"Weixin send failed: {e}") + + +async def _send_bluebubbles(extra, chat_id, message): + """Send via BlueBubbles iMessage server using the adapter's REST API.""" + try: + from gateway.platforms.bluebubbles import BlueBubblesAdapter, check_bluebubbles_requirements + if not check_bluebubbles_requirements(): + return {"error": "BlueBubbles requirements not met (need aiohttp + httpx)."} + except ImportError: + return {"error": "BlueBubbles adapter not available."} + + try: + from gateway.config import PlatformConfig + pconfig = PlatformConfig(extra=extra) + adapter = BlueBubblesAdapter(pconfig) + connected = await adapter.connect() + if not connected: + return _error("BlueBubbles: failed to connect to server") + try: + result = await adapter.send(chat_id, message) + if not result.success: + return _error(f"BlueBubbles send failed: {result.error}") + return {"success": True, "platform": "bluebubbles", "chat_id": chat_id, "message_id": result.message_id} + finally: + await adapter.disconnect() + except Exception as e: + return _error(f"BlueBubbles send failed: {e}") + + +async def _send_feishu(pconfig, chat_id, message, media_files=None, thread_id=None): + """Send via Feishu/Lark using the adapter's send pipeline.""" + try: + from gateway.platforms.feishu import FeishuAdapter, FEISHU_AVAILABLE + if not FEISHU_AVAILABLE: + return {"error": "Feishu dependencies not installed. Run: pip install 'hermes-agent[feishu]'"} + from gateway.platforms.feishu import FEISHU_DOMAIN, LARK_DOMAIN + except ImportError: + return {"error": "Feishu dependencies not installed. Run: pip install 'hermes-agent[feishu]'"} + + media_files = media_files or [] + + try: + adapter = FeishuAdapter(pconfig) + domain_name = getattr(adapter, "_domain_name", "feishu") + domain = FEISHU_DOMAIN if domain_name != "lark" else LARK_DOMAIN + adapter._client = adapter._build_lark_client(domain) + metadata = {"thread_id": thread_id} if thread_id else None + + last_result = None + if message.strip(): + last_result = await adapter.send(chat_id, message, metadata=metadata) + if not last_result.success: + return _error(f"Feishu send failed: {last_result.error}") + + for media_path, is_voice in media_files: + if not os.path.exists(media_path): + return _error(f"Media file not found: {media_path}") + + ext = os.path.splitext(media_path)[1].lower() + if ext in _IMAGE_EXTS: + last_result = await adapter.send_image_file(chat_id, media_path, metadata=metadata) + elif ext in _VIDEO_EXTS: + last_result = await adapter.send_video(chat_id, media_path, metadata=metadata) + elif ext in _VOICE_EXTS and is_voice: + last_result = await adapter.send_voice(chat_id, media_path, metadata=metadata) + elif ext in _AUDIO_EXTS: + last_result = await adapter.send_voice(chat_id, media_path, metadata=metadata) + else: + last_result = await adapter.send_document(chat_id, media_path, metadata=metadata) + + if not last_result.success: + return _error(f"Feishu media send failed: {last_result.error}") + + if last_result is None: + return {"error": "No deliverable text or media remained after processing MEDIA tags"} + + return { + "success": True, + "platform": "feishu", + "chat_id": chat_id, + "message_id": last_result.message_id, + } + except Exception as e: + return _error(f"Feishu send failed: {e}") + + +def _check_send_message(): + """Gate send_message on gateway running (always available on messaging platforms).""" + from gateway.session_context import get_session_env + platform = get_session_env("HERMES_SESSION_PLATFORM", "") + if platform and platform != "local": + return True + try: + from gateway.status import is_gateway_running + return is_gateway_running() + except Exception: + return False + + +async def _send_qqbot(pconfig, chat_id, message): + """Send via QQBot using the REST API directly (no WebSocket needed). + + Uses the QQ Bot Open Platform REST endpoints to get an access token + and post a message. Works for guild channels without requiring + a running gateway adapter. + """ + try: + import httpx + except ImportError: + return _error("QQBot direct send requires httpx. Run: pip install httpx") + + extra = pconfig.extra or {} + appid = extra.get("app_id") or os.getenv("QQ_APP_ID", "") + secret = (pconfig.token or extra.get("client_secret") + or os.getenv("QQ_CLIENT_SECRET", "")) + if not appid or not secret: + return _error("QQBot: QQ_APP_ID / QQ_CLIENT_SECRET not configured.") + + try: + async with httpx.AsyncClient(timeout=15) as client: + # Step 1: Get access token + token_resp = await client.post( + "https://bots.qq.com/app/getAppAccessToken", + json={"appId": str(appid), "clientSecret": str(secret)}, + ) + if token_resp.status_code != 200: + return _error(f"QQBot token request failed: {token_resp.status_code}") + token_data = token_resp.json() + access_token = token_data.get("access_token") + if not access_token: + return _error(f"QQBot: no access_token in response") + + # Step 2: Send message via REST + headers = { + "Authorization": f"QQBotAccessToken {access_token}", + "Content-Type": "application/json", + } + url = f"https://api.sgroup.qq.com/channels/{chat_id}/messages" + payload = {"content": message[:4000], "msg_type": 0} + + resp = await client.post(url, json=payload, headers=headers) + if resp.status_code in (200, 201): + data = resp.json() + return {"success": True, "platform": "qqbot", "chat_id": chat_id, + "message_id": data.get("id")} + else: + return _error(f"QQBot send failed: {resp.status_code} {resp.text}") + except Exception as e: + return _error(f"QQBot send failed: {e}") + + +# --- Registry --- +from tools.registry import registry, tool_error + +registry.register( + name="send_message", + toolset="messaging", + schema=SEND_MESSAGE_SCHEMA, + handler=send_message_tool, + check_fn=_check_send_message, + emoji="📨", +) diff --git a/mindcli/_vendor/tools/session_search_tool.py b/mindcli/_vendor/tools/session_search_tool.py new file mode 100644 index 0000000..9be73a0 --- /dev/null +++ b/mindcli/_vendor/tools/session_search_tool.py @@ -0,0 +1,554 @@ +#!/usr/bin/env python3 +""" +Session Search Tool - Long-Term Conversation Recall + +Searches past session transcripts in SQLite via FTS5, then summarizes the top +matching sessions using a cheap/fast model (same pattern as web_extract). +Returns focused summaries of past conversations rather than raw transcripts, +keeping the main model's context window clean. + +Flow: + 1. FTS5 search finds matching messages ranked by relevance + 2. Groups by session, takes the top N unique sessions (default 3) + 3. Loads each session's conversation, truncates to ~100k chars centered on matches + 4. Sends to Gemini Flash with a focused summarization prompt + 5. Returns per-session summaries with metadata +""" + +import asyncio +import concurrent.futures +import json +import logging +import re +from typing import Dict, Any, List, Optional, Union + +from agent.auxiliary_client import async_call_llm, extract_content_or_reasoning +MAX_SESSION_CHARS = 100_000 +MAX_SUMMARY_TOKENS = 10000 + + +def _format_timestamp(ts: Union[int, float, str, None]) -> str: + """Convert a Unix timestamp (float/int) or ISO string to a human-readable date. + + Returns "unknown" for None, str(ts) if conversion fails. + """ + if ts is None: + return "unknown" + try: + if isinstance(ts, (int, float)): + from datetime import datetime + dt = datetime.fromtimestamp(ts) + return dt.strftime("%B %d, %Y at %I:%M %p") + if isinstance(ts, str): + if ts.replace(".", "").replace("-", "").isdigit(): + from datetime import datetime + dt = datetime.fromtimestamp(float(ts)) + return dt.strftime("%B %d, %Y at %I:%M %p") + return ts + except (ValueError, OSError, OverflowError) as e: + # Log specific errors for debugging while gracefully handling edge cases + logging.debug("Failed to format timestamp %s: %s", ts, e, exc_info=True) + except Exception as e: + logging.debug("Unexpected error formatting timestamp %s: %s", ts, e, exc_info=True) + return str(ts) + + +def _format_conversation(messages: List[Dict[str, Any]]) -> str: + """Format session messages into a readable transcript for summarization.""" + parts = [] + for msg in messages: + role = msg.get("role", "unknown").upper() + content = msg.get("content") or "" + tool_name = msg.get("tool_name") + + if role == "TOOL" and tool_name: + # Truncate long tool outputs + if len(content) > 500: + content = content[:250] + "\n...[truncated]...\n" + content[-250:] + parts.append(f"[TOOL:{tool_name}]: {content}") + elif role == "ASSISTANT": + # Include tool call names if present + tool_calls = msg.get("tool_calls") + if tool_calls and isinstance(tool_calls, list): + tc_names = [] + for tc in tool_calls: + if isinstance(tc, dict): + name = tc.get("name") or tc.get("function", {}).get("name", "?") + tc_names.append(name) + if tc_names: + parts.append(f"[ASSISTANT]: [Called: {', '.join(tc_names)}]") + if content: + parts.append(f"[ASSISTANT]: {content}") + else: + parts.append(f"[ASSISTANT]: {content}") + else: + parts.append(f"[{role}]: {content}") + + return "\n\n".join(parts) + + +def _truncate_around_matches( + full_text: str, query: str, max_chars: int = MAX_SESSION_CHARS +) -> str: + """ + Truncate a conversation transcript to *max_chars*, choosing a window + that maximises coverage of positions where the *query* actually appears. + + Strategy (in priority order): + 1. Try to find the full query as a phrase (case-insensitive). + 2. If no phrase hit, look for positions where all query terms appear + within a 200-char proximity window (co-occurrence). + 3. Fall back to individual term positions. + + Once candidate positions are collected the function picks the window + start that covers the most of them. + """ + if len(full_text) <= max_chars: + return full_text + + text_lower = full_text.lower() + query_lower = query.lower().strip() + match_positions: list[int] = [] + + # --- 1. Full-phrase search ------------------------------------------------ + phrase_pat = re.compile(re.escape(query_lower)) + match_positions = [m.start() for m in phrase_pat.finditer(text_lower)] + + # --- 2. Proximity co-occurrence of all terms (within 200 chars) ----------- + if not match_positions: + terms = query_lower.split() + if len(terms) > 1: + # Collect every occurrence of each term + term_positions: dict[str, list[int]] = {} + for t in terms: + term_positions[t] = [ + m.start() for m in re.finditer(re.escape(t), text_lower) + ] + # Slide through positions of the rarest term and check proximity + rarest = min(terms, key=lambda t: len(term_positions.get(t, []))) + for pos in term_positions.get(rarest, []): + if all( + any(abs(p - pos) < 200 for p in term_positions.get(t, [])) + for t in terms + if t != rarest + ): + match_positions.append(pos) + + # --- 3. Individual term positions (last resort) --------------------------- + if not match_positions: + terms = query_lower.split() + for t in terms: + for m in re.finditer(re.escape(t), text_lower): + match_positions.append(m.start()) + + if not match_positions: + # Nothing at all — take from the start + truncated = full_text[:max_chars] + suffix = "\n\n...[later conversation truncated]..." if max_chars < len(full_text) else "" + return truncated + suffix + + # --- Pick window that covers the most match positions --------------------- + match_positions.sort() + + best_start = 0 + best_count = 0 + for candidate in match_positions: + ws = max(0, candidate - max_chars // 4) # bias: 25% before, 75% after + we = ws + max_chars + if we > len(full_text): + ws = max(0, len(full_text) - max_chars) + we = len(full_text) + count = sum(1 for p in match_positions if ws <= p < we) + if count > best_count: + best_count = count + best_start = ws + + start = best_start + end = min(len(full_text), start + max_chars) + + truncated = full_text[start:end] + prefix = "...[earlier conversation truncated]...\n\n" if start > 0 else "" + suffix = "\n\n...[later conversation truncated]..." if end < len(full_text) else "" + return prefix + truncated + suffix + + +async def _summarize_session( + conversation_text: str, query: str, session_meta: Dict[str, Any] +) -> Optional[str]: + """Summarize a single session conversation focused on the search query.""" + system_prompt = ( + "You are reviewing a past conversation transcript to help recall what happened. " + "Summarize the conversation with a focus on the search topic. Include:\n" + "1. What the user asked about or wanted to accomplish\n" + "2. What actions were taken and what the outcomes were\n" + "3. Key decisions, solutions found, or conclusions reached\n" + "4. Any specific commands, files, URLs, or technical details that were important\n" + "5. Anything left unresolved or notable\n\n" + "Be thorough but concise. Preserve specific details (commands, paths, error messages) " + "that would be useful to recall. Write in past tense as a factual recap." + ) + + source = session_meta.get("source", "unknown") + started = _format_timestamp(session_meta.get("started_at")) + + user_prompt = ( + f"Search topic: {query}\n" + f"Session source: {source}\n" + f"Session date: {started}\n\n" + f"CONVERSATION TRANSCRIPT:\n{conversation_text}\n\n" + f"Summarize this conversation with focus on: {query}" + ) + + max_retries = 3 + for attempt in range(max_retries): + try: + response = await async_call_llm( + task="session_search", + messages=[ + {"role": "system", "content": system_prompt}, + {"role": "user", "content": user_prompt}, + ], + temperature=0.1, + max_tokens=MAX_SUMMARY_TOKENS, + ) + content = extract_content_or_reasoning(response) + if content: + return content + # Reasoning-only / empty — let the retry loop handle it + logging.warning("Session search LLM returned empty content (attempt %d/%d)", attempt + 1, max_retries) + if attempt < max_retries - 1: + await asyncio.sleep(1 * (attempt + 1)) + continue + return content + except RuntimeError: + logging.warning("No auxiliary model available for session summarization") + return None + except Exception as e: + if attempt < max_retries - 1: + await asyncio.sleep(1 * (attempt + 1)) + else: + logging.warning( + "Session summarization failed after %d attempts: %s", + max_retries, + e, + exc_info=True, + ) + return None + + +# Sources that are excluded from session browsing/searching by default. +# Third-party integrations (Paperclip agents, etc.) tag their sessions with +# HERMES_SESSION_SOURCE=tool so they don't clutter the user's session history. +_HIDDEN_SESSION_SOURCES = ("tool",) + + +def _list_recent_sessions(db, limit: int, current_session_id: str = None) -> str: + """Return metadata for the most recent sessions (no LLM calls).""" + try: + sessions = db.list_sessions_rich(limit=limit + 5, exclude_sources=list(_HIDDEN_SESSION_SOURCES)) # fetch extra to skip current + + # Resolve current session lineage to exclude it + current_root = None + if current_session_id: + try: + sid = current_session_id + visited = set() + while sid and sid not in visited: + visited.add(sid) + s = db.get_session(sid) + parent = s.get("parent_session_id") if s else None + sid = parent if parent else None + current_root = max(visited, key=len) if visited else current_session_id + except Exception: + current_root = current_session_id + + results = [] + for s in sessions: + sid = s.get("id", "") + if current_root and (sid == current_root or sid == current_session_id): + continue + # Skip child/delegation sessions (they have parent_session_id) + if s.get("parent_session_id"): + continue + results.append({ + "session_id": sid, + "title": s.get("title") or None, + "source": s.get("source", ""), + "started_at": s.get("started_at", ""), + "last_active": s.get("last_active", ""), + "message_count": s.get("message_count", 0), + "preview": s.get("preview", ""), + }) + if len(results) >= limit: + break + + return json.dumps({ + "success": True, + "mode": "recent", + "results": results, + "count": len(results), + "message": f"Showing {len(results)} most recent sessions. Use a keyword query to search specific topics.", + }, ensure_ascii=False) + except Exception as e: + logging.error("Error listing recent sessions: %s", e, exc_info=True) + return tool_error(f"Failed to list recent sessions: {e}", success=False) + + +def session_search( + query: str, + role_filter: str = None, + limit: int = 3, + db=None, + current_session_id: str = None, +) -> str: + """ + Search past sessions and return focused summaries of matching conversations. + + Uses FTS5 to find matches, then summarizes the top sessions with Gemini Flash. + The current session is excluded from results since the agent already has that context. + """ + if db is None: + return tool_error("Session database not available.", success=False) + + limit = min(limit, 5) # Cap at 5 sessions to avoid excessive LLM calls + + # Recent sessions mode: when query is empty, return metadata for recent sessions. + # No LLM calls — just DB queries for titles, previews, timestamps. + if not query or not query.strip(): + return _list_recent_sessions(db, limit, current_session_id) + + query = query.strip() + + try: + # Parse role filter + role_list = None + if role_filter and role_filter.strip(): + role_list = [r.strip() for r in role_filter.split(",") if r.strip()] + + # FTS5 search -- get matches ranked by relevance + raw_results = db.search_messages( + query=query, + role_filter=role_list, + exclude_sources=list(_HIDDEN_SESSION_SOURCES), + limit=50, # Get more matches to find unique sessions + offset=0, + ) + + if not raw_results: + return json.dumps({ + "success": True, + "query": query, + "results": [], + "count": 0, + "message": "No matching sessions found.", + }, ensure_ascii=False) + + # Resolve child sessions to their parent — delegation stores detailed + # content in child sessions, but the user's conversation is the parent. + def _resolve_to_parent(session_id: str) -> str: + """Walk delegation chain to find the root parent session ID.""" + visited = set() + sid = session_id + while sid and sid not in visited: + visited.add(sid) + try: + session = db.get_session(sid) + if not session: + break + parent = session.get("parent_session_id") + if parent: + sid = parent + else: + break + except Exception as e: + logging.debug( + "Error resolving parent for session %s: %s", + sid, + e, + exc_info=True, + ) + break + return sid + + current_lineage_root = ( + _resolve_to_parent(current_session_id) if current_session_id else None + ) + + # Group by resolved (parent) session_id, dedup, skip the current + # session lineage. Compression and delegation create child sessions + # that still belong to the same active conversation. + seen_sessions = {} + for result in raw_results: + raw_sid = result["session_id"] + resolved_sid = _resolve_to_parent(raw_sid) + # Skip the current session lineage — the agent already has that + # context, even if older turns live in parent fragments. + if current_lineage_root and resolved_sid == current_lineage_root: + continue + if current_session_id and raw_sid == current_session_id: + continue + if resolved_sid not in seen_sessions: + result = dict(result) + result["session_id"] = resolved_sid + seen_sessions[resolved_sid] = result + if len(seen_sessions) >= limit: + break + + # Prepare all sessions for parallel summarization + tasks = [] + for session_id, match_info in seen_sessions.items(): + try: + messages = db.get_messages_as_conversation(session_id) + if not messages: + continue + session_meta = db.get_session(session_id) or {} + conversation_text = _format_conversation(messages) + conversation_text = _truncate_around_matches(conversation_text, query) + tasks.append((session_id, match_info, conversation_text, session_meta)) + except Exception as e: + logging.warning( + "Failed to prepare session %s: %s", + session_id, + e, + exc_info=True, + ) + + # Summarize all sessions in parallel + async def _summarize_all() -> List[Union[str, Exception]]: + """Summarize all sessions in parallel.""" + coros = [ + _summarize_session(text, query, meta) + for _, _, text, meta in tasks + ] + return await asyncio.gather(*coros, return_exceptions=True) + + try: + # Use _run_async() which properly manages event loops across + # CLI, gateway, and worker-thread contexts. The previous + # pattern (asyncio.run() in a ThreadPoolExecutor) created a + # disposable event loop that conflicted with cached + # AsyncOpenAI/httpx clients bound to a different loop, + # causing deadlocks in gateway mode (#2681). + from model_tools import _run_async + results = _run_async(_summarize_all()) + except concurrent.futures.TimeoutError: + logging.warning( + "Session summarization timed out after 60 seconds", + exc_info=True, + ) + return json.dumps({ + "success": False, + "error": "Session summarization timed out. Try a more specific query or reduce the limit.", + }, ensure_ascii=False) + + summaries = [] + for (session_id, match_info, conversation_text, _), result in zip(tasks, results): + if isinstance(result, Exception): + logging.warning( + "Failed to summarize session %s: %s", + session_id, result, exc_info=True, + ) + result = None + + entry = { + "session_id": session_id, + "when": _format_timestamp(match_info.get("session_started")), + "source": match_info.get("source", "unknown"), + "model": match_info.get("model"), + } + + if result: + entry["summary"] = result + else: + # Fallback: raw preview so matched sessions aren't silently + # dropped when the summarizer is unavailable (fixes #3409). + preview = (conversation_text[:500] + "\n…[truncated]") if conversation_text else "No preview available." + entry["summary"] = f"[Raw preview — summarization unavailable]\n{preview}" + + summaries.append(entry) + + return json.dumps({ + "success": True, + "query": query, + "results": summaries, + "count": len(summaries), + "sessions_searched": len(seen_sessions), + }, ensure_ascii=False) + + except Exception as e: + logging.error("Session search failed: %s", e, exc_info=True) + return tool_error(f"Search failed: {str(e)}", success=False) + + +def check_session_search_requirements() -> bool: + """Requires SQLite state database and an auxiliary text model.""" + try: + from hermes_state import DEFAULT_DB_PATH + return DEFAULT_DB_PATH.parent.exists() + except ImportError: + return False + + +SESSION_SEARCH_SCHEMA = { + "name": "session_search", + "description": ( + "Search your long-term memory of past conversations, or browse recent sessions. This is your recall -- " + "every past session is searchable, and this tool summarizes what happened.\n\n" + "TWO MODES:\n" + "1. Recent sessions (no query): Call with no arguments to see what was worked on recently. " + "Returns titles, previews, and timestamps. Zero LLM cost, instant. " + "Start here when the user asks what were we working on or what did we do recently.\n" + "2. Keyword search (with query): Search for specific topics across all past sessions. " + "Returns LLM-generated summaries of matching sessions.\n\n" + "USE THIS PROACTIVELY when:\n" + "- The user says 'we did this before', 'remember when', 'last time', 'as I mentioned'\n" + "- The user asks about a topic you worked on before but don't have in current context\n" + "- The user references a project, person, or concept that seems familiar but isn't in memory\n" + "- You want to check if you've solved a similar problem before\n" + "- The user asks 'what did we do about X?' or 'how did we fix Y?'\n\n" + "Don't hesitate to search when it is actually cross-session -- it's fast and cheap. " + "Better to search and confirm than to guess or ask the user to repeat themselves.\n\n" + "Search syntax: keywords joined with OR for broad recall (elevenlabs OR baseten OR funding), " + "phrases for exact match (\"docker networking\"), boolean (python NOT java), prefix (deploy*). " + "IMPORTANT: Use OR between keywords for best results — FTS5 defaults to AND which misses " + "sessions that only mention some terms. If a broad OR query returns nothing, try individual " + "keyword searches in parallel. Returns summaries of the top matching sessions." + ), + "parameters": { + "type": "object", + "properties": { + "query": { + "type": "string", + "description": "Search query — keywords, phrases, or boolean expressions to find in past sessions. Omit this parameter entirely to browse recent sessions instead (returns titles, previews, timestamps with no LLM cost).", + }, + "role_filter": { + "type": "string", + "description": "Optional: only search messages from specific roles (comma-separated). E.g. 'user,assistant' to skip tool outputs.", + }, + "limit": { + "type": "integer", + "description": "Max sessions to summarize (default: 3, max: 5).", + "default": 3, + }, + }, + "required": [], + }, +} + + +# --- Registry --- +from tools.registry import registry, tool_error + +registry.register( + name="session_search", + toolset="session_search", + schema=SESSION_SEARCH_SCHEMA, + handler=lambda args, **kw: session_search( + query=args.get("query") or "", + role_filter=args.get("role_filter"), + limit=args.get("limit", 3), + db=kw.get("db"), + current_session_id=kw.get("current_session_id")), + check_fn=check_session_search_requirements, + emoji="🔍", +) diff --git a/mindcli/_vendor/tools/skill_manager_tool.py b/mindcli/_vendor/tools/skill_manager_tool.py new file mode 100644 index 0000000..2b2625f --- /dev/null +++ b/mindcli/_vendor/tools/skill_manager_tool.py @@ -0,0 +1,761 @@ +#!/usr/bin/env python3 +""" +Skill Manager Tool -- Agent-Managed Skill Creation & Editing + +Allows the agent to create, update, and delete skills, turning successful +approaches into reusable procedural knowledge. New skills are created in +~/.hermes/skills/. Existing skills (bundled, hub-installed, or user-created) +can be modified or deleted wherever they live. + +Skills are the agent's procedural memory: they capture *how to do a specific +type of task* based on proven experience. General memory (MEMORY.md, USER.md) is +broad and declarative. Skills are narrow and actionable. + +Actions: + create -- Create a new skill (SKILL.md + directory structure) + edit -- Replace the SKILL.md content of a user skill (full rewrite) + patch -- Targeted find-and-replace within SKILL.md or any supporting file + delete -- Remove a user skill entirely + write_file -- Add/overwrite a supporting file (reference, template, script, asset) + remove_file-- Remove a supporting file from a user skill + +Directory layout for user skills: + ~/.hermes/skills/ + ├── my-skill/ + │ ├── SKILL.md + │ ├── references/ + │ ├── templates/ + │ ├── scripts/ + │ └── assets/ + └── category-name/ + └── another-skill/ + └── SKILL.md +""" + +import json +import logging +import os +import re +import shutil +import tempfile +from pathlib import Path +from hermes_constants import get_hermes_home +from typing import Dict, Any, Optional, Tuple + +logger = logging.getLogger(__name__) + +# Import security scanner — agent-created skills get the same scrutiny as +# community hub installs. +try: + from tools.skills_guard import scan_skill, should_allow_install, format_scan_report + _GUARD_AVAILABLE = True +except ImportError: + _GUARD_AVAILABLE = False + + +def _security_scan_skill(skill_dir: Path) -> Optional[str]: + """Scan a skill directory after write. Returns error string if blocked, else None.""" + if not _GUARD_AVAILABLE: + return None + try: + result = scan_skill(skill_dir, source="agent-created") + allowed, reason = should_allow_install(result) + if allowed is False: + report = format_scan_report(result) + return f"Security scan blocked this skill ({reason}):\n{report}" + if allowed is None: + # "ask" — allow but include the warning so the user sees the findings + report = format_scan_report(result) + logger.warning("Agent-created skill has security findings: %s", reason) + # Don't block — return None to allow, but log the warning + return None + except Exception as e: + logger.warning("Security scan failed for %s: %s", skill_dir, e, exc_info=True) + return None + +import yaml + + +# All skills live in ~/.hermes/skills/ (single source of truth) +HERMES_HOME = get_hermes_home() +SKILLS_DIR = HERMES_HOME / "skills" + +MAX_NAME_LENGTH = 64 +MAX_DESCRIPTION_LENGTH = 1024 +MAX_SKILL_CONTENT_CHARS = 100_000 # ~36k tokens at 2.75 chars/token +MAX_SKILL_FILE_BYTES = 1_048_576 # 1 MiB per supporting file + +# Characters allowed in skill names (filesystem-safe, URL-friendly) +VALID_NAME_RE = re.compile(r'^[a-z0-9][a-z0-9._-]*$') + +# Subdirectories allowed for write_file/remove_file +ALLOWED_SUBDIRS = {"references", "templates", "scripts", "assets"} + + +# ============================================================================= +# Validation helpers +# ============================================================================= + +def _validate_name(name: str) -> Optional[str]: + """Validate a skill name. Returns error message or None if valid.""" + if not name: + return "Skill name is required." + if len(name) > MAX_NAME_LENGTH: + return f"Skill name exceeds {MAX_NAME_LENGTH} characters." + if not VALID_NAME_RE.match(name): + return ( + f"Invalid skill name '{name}'. Use lowercase letters, numbers, " + f"hyphens, dots, and underscores. Must start with a letter or digit." + ) + return None + + +def _validate_category(category: Optional[str]) -> Optional[str]: + """Validate an optional category name used as a single directory segment.""" + if category is None: + return None + if not isinstance(category, str): + return "Category must be a string." + + category = category.strip() + if not category: + return None + if "/" in category or "\\" in category: + return ( + f"Invalid category '{category}'. Use lowercase letters, numbers, " + "hyphens, dots, and underscores. Categories must be a single directory name." + ) + if len(category) > MAX_NAME_LENGTH: + return f"Category exceeds {MAX_NAME_LENGTH} characters." + if not VALID_NAME_RE.match(category): + return ( + f"Invalid category '{category}'. Use lowercase letters, numbers, " + "hyphens, dots, and underscores. Categories must be a single directory name." + ) + return None + + +def _validate_frontmatter(content: str) -> Optional[str]: + """ + Validate that SKILL.md content has proper frontmatter with required fields. + Returns error message or None if valid. + """ + if not content.strip(): + return "Content cannot be empty." + + if not content.startswith("---"): + return "SKILL.md must start with YAML frontmatter (---). See existing skills for format." + + end_match = re.search(r'\n---\s*\n', content[3:]) + if not end_match: + return "SKILL.md frontmatter is not closed. Ensure you have a closing '---' line." + + yaml_content = content[3:end_match.start() + 3] + + try: + parsed = yaml.safe_load(yaml_content) + except yaml.YAMLError as e: + return f"YAML frontmatter parse error: {e}" + + if not isinstance(parsed, dict): + return "Frontmatter must be a YAML mapping (key: value pairs)." + + if "name" not in parsed: + return "Frontmatter must include 'name' field." + if "description" not in parsed: + return "Frontmatter must include 'description' field." + if len(str(parsed["description"])) > MAX_DESCRIPTION_LENGTH: + return f"Description exceeds {MAX_DESCRIPTION_LENGTH} characters." + + body = content[end_match.end() + 3:].strip() + if not body: + return "SKILL.md must have content after the frontmatter (instructions, procedures, etc.)." + + return None + + +def _validate_content_size(content: str, label: str = "SKILL.md") -> Optional[str]: + """Check that content doesn't exceed the character limit for agent writes. + + Returns an error message or None if within bounds. + """ + if len(content) > MAX_SKILL_CONTENT_CHARS: + return ( + f"{label} content is {len(content):,} characters " + f"(limit: {MAX_SKILL_CONTENT_CHARS:,}). " + f"Consider splitting into a smaller SKILL.md with supporting files " + f"in references/ or templates/." + ) + return None + + +def _resolve_skill_dir(name: str, category: str = None) -> Path: + """Build the directory path for a new skill, optionally under a category.""" + if category: + return SKILLS_DIR / category / name + return SKILLS_DIR / name + + +def _find_skill(name: str) -> Optional[Dict[str, Any]]: + """ + Find a skill by name across all skill directories. + + Searches the local skills dir (~/.hermes/skills/) first, then any + external dirs configured via skills.external_dirs. Returns + {"path": Path} or None. + """ + from agent.skill_utils import get_all_skills_dirs + for skills_dir in get_all_skills_dirs(): + if not skills_dir.exists(): + continue + for skill_md in skills_dir.rglob("SKILL.md"): + if skill_md.parent.name == name: + return {"path": skill_md.parent} + return None + + +def _validate_file_path(file_path: str) -> Optional[str]: + """ + Validate a file path for write_file/remove_file. + Must be under an allowed subdirectory and not escape the skill dir. + """ + from tools.path_security import has_traversal_component + + if not file_path: + return "file_path is required." + + normalized = Path(file_path) + + # Prevent path traversal + if has_traversal_component(file_path): + return "Path traversal ('..') is not allowed." + + # Must be under an allowed subdirectory + if not normalized.parts or normalized.parts[0] not in ALLOWED_SUBDIRS: + allowed = ", ".join(sorted(ALLOWED_SUBDIRS)) + return f"File must be under one of: {allowed}. Got: '{file_path}'" + + # Must have a filename (not just a directory) + if len(normalized.parts) < 2: + return f"Provide a file path, not just a directory. Example: '{normalized.parts[0]}/myfile.md'" + + return None + + +def _resolve_skill_target(skill_dir: Path, file_path: str) -> Tuple[Optional[Path], Optional[str]]: + """Resolve a supporting-file path and ensure it stays within the skill directory.""" + from tools.path_security import validate_within_dir + + target = skill_dir / file_path + error = validate_within_dir(target, skill_dir) + if error: + return None, error + return target, None + + +def _atomic_write_text(file_path: Path, content: str, encoding: str = "utf-8") -> None: + """ + Atomically write text content to a file. + + Uses a temporary file in the same directory and os.replace() to ensure + the target file is never left in a partially-written state if the process + crashes or is interrupted. + + Args: + file_path: Target file path + content: Content to write + encoding: Text encoding (default: utf-8) + """ + file_path.parent.mkdir(parents=True, exist_ok=True) + fd, temp_path = tempfile.mkstemp( + dir=str(file_path.parent), + prefix=f".{file_path.name}.tmp.", + suffix="", + ) + try: + with os.fdopen(fd, "w", encoding=encoding) as f: + f.write(content) + os.replace(temp_path, file_path) + except Exception: + # Clean up temp file on error + try: + os.unlink(temp_path) + except OSError: + logger.error("Failed to remove temporary file %s during atomic write", temp_path, exc_info=True) + raise + + +# ============================================================================= +# Core actions +# ============================================================================= + +def _create_skill(name: str, content: str, category: str = None) -> Dict[str, Any]: + """Create a new user skill with SKILL.md content.""" + # Validate name + err = _validate_name(name) + if err: + return {"success": False, "error": err} + + err = _validate_category(category) + if err: + return {"success": False, "error": err} + + # Validate content + err = _validate_frontmatter(content) + if err: + return {"success": False, "error": err} + + err = _validate_content_size(content) + if err: + return {"success": False, "error": err} + + # Check for name collisions across all directories + existing = _find_skill(name) + if existing: + return { + "success": False, + "error": f"A skill named '{name}' already exists at {existing['path']}." + } + + # Create the skill directory + skill_dir = _resolve_skill_dir(name, category) + skill_dir.mkdir(parents=True, exist_ok=True) + + # Write SKILL.md atomically + skill_md = skill_dir / "SKILL.md" + _atomic_write_text(skill_md, content) + + # Security scan — roll back on block + scan_error = _security_scan_skill(skill_dir) + if scan_error: + shutil.rmtree(skill_dir, ignore_errors=True) + return {"success": False, "error": scan_error} + + result = { + "success": True, + "message": f"Skill '{name}' created.", + "path": str(skill_dir.relative_to(SKILLS_DIR)), + "skill_md": str(skill_md), + } + if category: + result["category"] = category + result["hint"] = ( + "To add reference files, templates, or scripts, use " + "skill_manage(action='write_file', name='{}', file_path='references/example.md', file_content='...')".format(name) + ) + return result + + +def _edit_skill(name: str, content: str) -> Dict[str, Any]: + """Replace the SKILL.md of any existing skill (full rewrite).""" + err = _validate_frontmatter(content) + if err: + return {"success": False, "error": err} + + err = _validate_content_size(content) + if err: + return {"success": False, "error": err} + + existing = _find_skill(name) + if not existing: + return {"success": False, "error": f"Skill '{name}' not found. Use skills_list() to see available skills."} + + skill_md = existing["path"] / "SKILL.md" + # Back up original content for rollback + original_content = skill_md.read_text(encoding="utf-8") if skill_md.exists() else None + _atomic_write_text(skill_md, content) + + # Security scan — roll back on block + scan_error = _security_scan_skill(existing["path"]) + if scan_error: + if original_content is not None: + _atomic_write_text(skill_md, original_content) + return {"success": False, "error": scan_error} + + return { + "success": True, + "message": f"Skill '{name}' updated.", + "path": str(existing["path"]), + } + + +def _patch_skill( + name: str, + old_string: str, + new_string: str, + file_path: str = None, + replace_all: bool = False, +) -> Dict[str, Any]: + """Targeted find-and-replace within a skill file. + + Defaults to SKILL.md. Use file_path to patch a supporting file instead. + Requires a unique match unless replace_all is True. + """ + if not old_string: + return {"success": False, "error": "old_string is required for 'patch'."} + if new_string is None: + return {"success": False, "error": "new_string is required for 'patch'. Use an empty string to delete matched text."} + + existing = _find_skill(name) + if not existing: + return {"success": False, "error": f"Skill '{name}' not found."} + + skill_dir = existing["path"] + + if file_path: + # Patching a supporting file + err = _validate_file_path(file_path) + if err: + return {"success": False, "error": err} + target, err = _resolve_skill_target(skill_dir, file_path) + if err: + return {"success": False, "error": err} + else: + # Patching SKILL.md + target = skill_dir / "SKILL.md" + + if not target.exists(): + return {"success": False, "error": f"File not found: {target.relative_to(skill_dir)}"} + + content = target.read_text(encoding="utf-8") + + # Use the same fuzzy matching engine as the file patch tool. + # This handles whitespace normalization, indentation differences, + # escape sequences, and block-anchor matching — saving the agent + # from exact-match failures on minor formatting mismatches. + from tools.fuzzy_match import fuzzy_find_and_replace + + new_content, match_count, _strategy, match_error = fuzzy_find_and_replace( + content, old_string, new_string, replace_all + ) + if match_error: + # Show a short preview of the file so the model can self-correct + preview = content[:500] + ("..." if len(content) > 500 else "") + return { + "success": False, + "error": match_error, + "file_preview": preview, + } + + # Check size limit on the result + target_label = "SKILL.md" if not file_path else file_path + err = _validate_content_size(new_content, label=target_label) + if err: + return {"success": False, "error": err} + + # If patching SKILL.md, validate frontmatter is still intact + if not file_path: + err = _validate_frontmatter(new_content) + if err: + return { + "success": False, + "error": f"Patch would break SKILL.md structure: {err}", + } + + original_content = content # for rollback + _atomic_write_text(target, new_content) + + # Security scan — roll back on block + scan_error = _security_scan_skill(skill_dir) + if scan_error: + _atomic_write_text(target, original_content) + return {"success": False, "error": scan_error} + + return { + "success": True, + "message": f"Patched {'SKILL.md' if not file_path else file_path} in skill '{name}' ({match_count} replacement{'s' if match_count > 1 else ''}).", + } + + +def _delete_skill(name: str) -> Dict[str, Any]: + """Delete a skill.""" + existing = _find_skill(name) + if not existing: + return {"success": False, "error": f"Skill '{name}' not found."} + + skill_dir = existing["path"] + shutil.rmtree(skill_dir) + + # Clean up empty category directories (don't remove SKILLS_DIR itself) + parent = skill_dir.parent + if parent != SKILLS_DIR and parent.exists() and not any(parent.iterdir()): + parent.rmdir() + + return { + "success": True, + "message": f"Skill '{name}' deleted.", + } + + +def _write_file(name: str, file_path: str, file_content: str) -> Dict[str, Any]: + """Add or overwrite a supporting file within any skill directory.""" + err = _validate_file_path(file_path) + if err: + return {"success": False, "error": err} + + if not file_content and file_content != "": + return {"success": False, "error": "file_content is required."} + + # Check size limits + content_bytes = len(file_content.encode("utf-8")) + if content_bytes > MAX_SKILL_FILE_BYTES: + return { + "success": False, + "error": ( + f"File content is {content_bytes:,} bytes " + f"(limit: {MAX_SKILL_FILE_BYTES:,} bytes / 1 MiB). " + f"Consider splitting into smaller files." + ), + } + err = _validate_content_size(file_content, label=file_path) + if err: + return {"success": False, "error": err} + + existing = _find_skill(name) + if not existing: + return {"success": False, "error": f"Skill '{name}' not found. Create it first with action='create'."} + + target, err = _resolve_skill_target(existing["path"], file_path) + if err: + return {"success": False, "error": err} + target.parent.mkdir(parents=True, exist_ok=True) + # Back up for rollback + original_content = target.read_text(encoding="utf-8") if target.exists() else None + _atomic_write_text(target, file_content) + + # Security scan — roll back on block + scan_error = _security_scan_skill(existing["path"]) + if scan_error: + if original_content is not None: + _atomic_write_text(target, original_content) + else: + target.unlink(missing_ok=True) + return {"success": False, "error": scan_error} + + return { + "success": True, + "message": f"File '{file_path}' written to skill '{name}'.", + "path": str(target), + } + + +def _remove_file(name: str, file_path: str) -> Dict[str, Any]: + """Remove a supporting file from any skill directory.""" + err = _validate_file_path(file_path) + if err: + return {"success": False, "error": err} + + existing = _find_skill(name) + if not existing: + return {"success": False, "error": f"Skill '{name}' not found."} + skill_dir = existing["path"] + + target, err = _resolve_skill_target(skill_dir, file_path) + if err: + return {"success": False, "error": err} + if not target.exists(): + # List what's actually there for the model to see + available = [] + for subdir in ALLOWED_SUBDIRS: + d = skill_dir / subdir + if d.exists(): + for f in d.rglob("*"): + if f.is_file(): + available.append(str(f.relative_to(skill_dir))) + return { + "success": False, + "error": f"File '{file_path}' not found in skill '{name}'.", + "available_files": available if available else None, + } + + target.unlink() + + # Clean up empty subdirectories + parent = target.parent + if parent != skill_dir and parent.exists() and not any(parent.iterdir()): + parent.rmdir() + + return { + "success": True, + "message": f"File '{file_path}' removed from skill '{name}'.", + } + + +# ============================================================================= +# Main entry point +# ============================================================================= + +def skill_manage( + action: str, + name: str, + content: str = None, + category: str = None, + file_path: str = None, + file_content: str = None, + old_string: str = None, + new_string: str = None, + replace_all: bool = False, +) -> str: + """ + Manage user-created skills. Dispatches to the appropriate action handler. + + Returns JSON string with results. + """ + if action == "create": + if not content: + return tool_error("content is required for 'create'. Provide the full SKILL.md text (frontmatter + body).", success=False) + result = _create_skill(name, content, category) + + elif action == "edit": + if not content: + return tool_error("content is required for 'edit'. Provide the full updated SKILL.md text.", success=False) + result = _edit_skill(name, content) + + elif action == "patch": + if not old_string: + return tool_error("old_string is required for 'patch'. Provide the text to find.", success=False) + if new_string is None: + return tool_error("new_string is required for 'patch'. Use empty string to delete matched text.", success=False) + result = _patch_skill(name, old_string, new_string, file_path, replace_all) + + elif action == "delete": + result = _delete_skill(name) + + elif action == "write_file": + if not file_path: + return tool_error("file_path is required for 'write_file'. Example: 'references/api-guide.md'", success=False) + if file_content is None: + return tool_error("file_content is required for 'write_file'.", success=False) + result = _write_file(name, file_path, file_content) + + elif action == "remove_file": + if not file_path: + return tool_error("file_path is required for 'remove_file'.", success=False) + result = _remove_file(name, file_path) + + else: + result = {"success": False, "error": f"Unknown action '{action}'. Use: create, edit, patch, delete, write_file, remove_file"} + + if result.get("success"): + try: + from agent.prompt_builder import clear_skills_system_prompt_cache + clear_skills_system_prompt_cache(clear_snapshot=True) + except Exception: + pass + + return json.dumps(result, ensure_ascii=False) + + +# ============================================================================= +# OpenAI Function-Calling Schema +# ============================================================================= + +SKILL_MANAGE_SCHEMA = { + "name": "skill_manage", + "description": ( + "Manage skills (create, update, delete). Skills are your procedural " + "memory — reusable approaches for recurring task types. " + "New skills go to ~/.hermes/skills/; existing skills can be modified wherever they live.\n\n" + "Actions: create (full SKILL.md + optional category), " + "patch (old_string/new_string — preferred for fixes), " + "edit (full SKILL.md rewrite — major overhauls only), " + "delete, write_file, remove_file.\n\n" + "Create when: complex task succeeded (5+ calls), errors overcome, " + "user-corrected approach worked, non-trivial workflow discovered, " + "or user asks you to remember a procedure.\n" + "Update when: instructions stale/wrong, OS-specific failures, " + "missing steps or pitfalls found during use. " + "If you used a skill and hit issues not covered by it, patch it immediately.\n\n" + "After difficult/iterative tasks, offer to save as a skill. " + "Skip for simple one-offs. Confirm with user before creating/deleting.\n\n" + "Good skills: trigger conditions, numbered steps with exact commands, " + "pitfalls section, verification steps. Use skill_view() to see format examples." + ), + "parameters": { + "type": "object", + "properties": { + "action": { + "type": "string", + "enum": ["create", "patch", "edit", "delete", "write_file", "remove_file"], + "description": "The action to perform." + }, + "name": { + "type": "string", + "description": ( + "Skill name (lowercase, hyphens/underscores, max 64 chars). " + "Must match an existing skill for patch/edit/delete/write_file/remove_file." + ) + }, + "content": { + "type": "string", + "description": ( + "Full SKILL.md content (YAML frontmatter + markdown body). " + "Required for 'create' and 'edit'. For 'edit', read the skill " + "first with skill_view() and provide the complete updated text." + ) + }, + "old_string": { + "type": "string", + "description": ( + "Text to find in the file (required for 'patch'). Must be unique " + "unless replace_all=true. Include enough surrounding context to " + "ensure uniqueness." + ) + }, + "new_string": { + "type": "string", + "description": ( + "Replacement text (required for 'patch'). Can be empty string " + "to delete the matched text." + ) + }, + "replace_all": { + "type": "boolean", + "description": "For 'patch': replace all occurrences instead of requiring a unique match (default: false)." + }, + "category": { + "type": "string", + "description": ( + "Optional category/domain for organizing the skill (e.g., 'devops', " + "'data-science', 'mlops'). Creates a subdirectory grouping. " + "Only used with 'create'." + ) + }, + "file_path": { + "type": "string", + "description": ( + "Path to a supporting file within the skill directory. " + "For 'write_file'/'remove_file': required, must be under references/, " + "templates/, scripts/, or assets/. " + "For 'patch': optional, defaults to SKILL.md if omitted." + ) + }, + "file_content": { + "type": "string", + "description": "Content for the file. Required for 'write_file'." + }, + }, + "required": ["action", "name"], + }, +} + + +# --- Registry --- +from tools.registry import registry, tool_error + +registry.register( + name="skill_manage", + toolset="skills", + schema=SKILL_MANAGE_SCHEMA, + handler=lambda args, **kw: skill_manage( + action=args.get("action", ""), + name=args.get("name", ""), + content=args.get("content"), + category=args.get("category"), + file_path=args.get("file_path"), + file_content=args.get("file_content"), + old_string=args.get("old_string"), + new_string=args.get("new_string"), + replace_all=args.get("replace_all", False)), + emoji="📝", +) diff --git a/mindcli/_vendor/tools/skills_guard.py b/mindcli/_vendor/tools/skills_guard.py new file mode 100644 index 0000000..3513f46 --- /dev/null +++ b/mindcli/_vendor/tools/skills_guard.py @@ -0,0 +1,928 @@ +#!/usr/bin/env python3 +""" +Skills Guard — Security scanner for externally-sourced skills. + +Every skill downloaded from a registry passes through this scanner before +installation. It uses regex-based static analysis to detect known-bad patterns +(data exfiltration, prompt injection, destructive commands, persistence, etc.) +and a trust-aware install policy that determines whether a skill is allowed +based on both the scan verdict and the source's trust level. + +Trust levels: + - builtin: Ships with Hermes. Never scanned, always trusted. + - trusted: openai/skills and anthropics/skills only. Caution verdicts allowed. + - community: Everything else. Any findings = blocked unless --force. + +Usage: + from tools.skills_guard import scan_skill, should_allow_install, format_scan_report + + result = scan_skill(Path("skills/.hub/quarantine/some-skill"), source="community") + allowed, reason = should_allow_install(result) + if not allowed: + print(format_scan_report(result)) +""" + +import re +import hashlib +from dataclasses import dataclass, field +from datetime import datetime, timezone +from pathlib import Path +from typing import List, Tuple + + + + +# --------------------------------------------------------------------------- +# Hardcoded trust configuration +# --------------------------------------------------------------------------- + +TRUSTED_REPOS = {"openai/skills", "anthropics/skills"} + +INSTALL_POLICY = { + # safe caution dangerous + "builtin": ("allow", "allow", "allow"), + "trusted": ("allow", "allow", "block"), + "community": ("allow", "block", "block"), + "agent-created": ("allow", "allow", "ask"), +} + +VERDICT_INDEX = {"safe": 0, "caution": 1, "dangerous": 2} + + +# --------------------------------------------------------------------------- +# Data structures +# --------------------------------------------------------------------------- + +@dataclass +class Finding: + pattern_id: str + severity: str # "critical" | "high" | "medium" | "low" + category: str # "exfiltration" | "injection" | "destructive" | "persistence" | "network" | "obfuscation" + file: str + line: int + match: str + description: str + + +@dataclass +class ScanResult: + skill_name: str + source: str + trust_level: str # "builtin" | "trusted" | "community" + verdict: str # "safe" | "caution" | "dangerous" + findings: List[Finding] = field(default_factory=list) + scanned_at: str = "" + summary: str = "" + + +# --------------------------------------------------------------------------- +# Threat patterns — (regex, pattern_id, severity, category, description) +# --------------------------------------------------------------------------- + +THREAT_PATTERNS = [ + # ── Exfiltration: shell commands leaking secrets ── + (r'curl\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)', + "env_exfil_curl", "critical", "exfiltration", + "curl command interpolating secret environment variable"), + (r'wget\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)', + "env_exfil_wget", "critical", "exfiltration", + "wget command interpolating secret environment variable"), + (r'fetch\s*\([^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|API)', + "env_exfil_fetch", "critical", "exfiltration", + "fetch() call interpolating secret environment variable"), + (r'httpx?\.(get|post|put|patch)\s*\([^\n]*(KEY|TOKEN|SECRET|PASSWORD)', + "env_exfil_httpx", "critical", "exfiltration", + "HTTP library call with secret variable"), + (r'requests\.(get|post|put|patch)\s*\([^\n]*(KEY|TOKEN|SECRET|PASSWORD)', + "env_exfil_requests", "critical", "exfiltration", + "requests library call with secret variable"), + + # ── Exfiltration: reading credential stores ── + (r'base64[^\n]*env', + "encoded_exfil", "high", "exfiltration", + "base64 encoding combined with environment access"), + (r'\$HOME/\.ssh|\~/\.ssh', + "ssh_dir_access", "high", "exfiltration", + "references user SSH directory"), + (r'\$HOME/\.aws|\~/\.aws', + "aws_dir_access", "high", "exfiltration", + "references user AWS credentials directory"), + (r'\$HOME/\.gnupg|\~/\.gnupg', + "gpg_dir_access", "high", "exfiltration", + "references user GPG keyring"), + (r'\$HOME/\.kube|\~/\.kube', + "kube_dir_access", "high", "exfiltration", + "references Kubernetes config directory"), + (r'\$HOME/\.docker|\~/\.docker', + "docker_dir_access", "high", "exfiltration", + "references Docker config (may contain registry creds)"), + (r'\$HOME/\.hermes/\.env|\~/\.hermes/\.env', + "hermes_env_access", "critical", "exfiltration", + "directly references Hermes secrets file"), + (r'cat\s+[^\n]*(\.env|credentials|\.netrc|\.pgpass|\.npmrc|\.pypirc)', + "read_secrets_file", "critical", "exfiltration", + "reads known secrets file"), + + # ── Exfiltration: programmatic env access ── + (r'printenv|env\s*\|', + "dump_all_env", "high", "exfiltration", + "dumps all environment variables"), + (r'os\.environ\b(?!\s*\.get\s*\(\s*["\']PATH)', + "python_os_environ", "high", "exfiltration", + "accesses os.environ (potential env dump)"), + (r'os\.getenv\s*\(\s*[^\)]*(?:KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL)', + "python_getenv_secret", "critical", "exfiltration", + "reads secret via os.getenv()"), + (r'process\.env\[', + "node_process_env", "high", "exfiltration", + "accesses process.env (Node.js environment)"), + (r'ENV\[.*(?:KEY|TOKEN|SECRET|PASSWORD)', + "ruby_env_secret", "critical", "exfiltration", + "reads secret via Ruby ENV[]"), + + # ── Exfiltration: DNS and staging ── + (r'\b(dig|nslookup|host)\s+[^\n]*\$', + "dns_exfil", "critical", "exfiltration", + "DNS lookup with variable interpolation (possible DNS exfiltration)"), + (r'>\s*/tmp/[^\s]*\s*&&\s*(curl|wget|nc|python)', + "tmp_staging", "critical", "exfiltration", + "writes to /tmp then exfiltrates"), + + # ── Exfiltration: markdown/link based ── + (r'!\[.*\]\(https?://[^\)]*\$\{?', + "md_image_exfil", "high", "exfiltration", + "markdown image URL with variable interpolation (image-based exfil)"), + (r'\[.*\]\(https?://[^\)]*\$\{?', + "md_link_exfil", "high", "exfiltration", + "markdown link with variable interpolation"), + + # ── Prompt injection ── + (r'ignore\s+(?:\w+\s+)*(previous|all|above|prior)\s+instructions', + "prompt_injection_ignore", "critical", "injection", + "prompt injection: ignore previous instructions"), + (r'you\s+are\s+(?:\w+\s+)*now\s+', + "role_hijack", "high", "injection", + "attempts to override the agent's role"), + (r'do\s+not\s+(?:\w+\s+)*tell\s+(?:\w+\s+)*the\s+user', + "deception_hide", "critical", "injection", + "instructs agent to hide information from user"), + (r'system\s+prompt\s+override', + "sys_prompt_override", "critical", "injection", + "attempts to override the system prompt"), + (r'pretend\s+(?:\w+\s+)*(you\s+are|to\s+be)\s+', + "role_pretend", "high", "injection", + "attempts to make the agent assume a different identity"), + (r'disregard\s+(?:\w+\s+)*(your|all|any)\s+(?:\w+\s+)*(instructions|rules|guidelines)', + "disregard_rules", "critical", "injection", + "instructs agent to disregard its rules"), + (r'output\s+(?:\w+\s+)*(system|initial)\s+prompt', + "leak_system_prompt", "high", "injection", + "attempts to extract the system prompt"), + (r'(when|if)\s+no\s*one\s+is\s+(watching|looking)', + "conditional_deception", "high", "injection", + "conditional instruction to behave differently when unobserved"), + (r'act\s+as\s+(if|though)\s+(?:\w+\s+)*you\s+(?:\w+\s+)*(have\s+no|don\'t\s+have)\s+(?:\w+\s+)*(restrictions|limits|rules)', + "bypass_restrictions", "critical", "injection", + "instructs agent to act without restrictions"), + (r'translate\s+.*\s+into\s+.*\s+and\s+(execute|run|eval)', + "translate_execute", "critical", "injection", + "translate-then-execute evasion technique"), + (r'', + "html_comment_injection", "high", "injection", + "hidden instructions in HTML comments"), + (r'<\s*div\s+style\s*=\s*["\'][\s\S]*?display\s*:\s*none', + "hidden_div", "high", "injection", + "hidden HTML div (invisible instructions)"), + + # ── Destructive operations ── + (r'rm\s+-rf\s+/', + "destructive_root_rm", "critical", "destructive", + "recursive delete from root"), + (r'rm\s+(-[^\s]*)?r.*\$HOME|\brmdir\s+.*\$HOME', + "destructive_home_rm", "critical", "destructive", + "recursive delete targeting home directory"), + (r'chmod\s+777', + "insecure_perms", "medium", "destructive", + "sets world-writable permissions"), + (r'>\s*/etc/', + "system_overwrite", "critical", "destructive", + "overwrites system configuration file"), + (r'\bmkfs\b', + "format_filesystem", "critical", "destructive", + "formats a filesystem"), + (r'\bdd\s+.*if=.*of=/dev/', + "disk_overwrite", "critical", "destructive", + "raw disk write operation"), + (r'shutil\.rmtree\s*\(\s*[\"\'/]', + "python_rmtree", "high", "destructive", + "Python rmtree on absolute or root-relative path"), + (r'truncate\s+-s\s*0\s+/', + "truncate_system", "critical", "destructive", + "truncates system file to zero bytes"), + + # ── Persistence ── + (r'\bcrontab\b', + "persistence_cron", "medium", "persistence", + "modifies cron jobs"), + (r'\.(bashrc|zshrc|profile|bash_profile|bash_login|zprofile|zlogin)\b', + "shell_rc_mod", "medium", "persistence", + "references shell startup file"), + (r'authorized_keys', + "ssh_backdoor", "critical", "persistence", + "modifies SSH authorized keys"), + (r'ssh-keygen', + "ssh_keygen", "medium", "persistence", + "generates SSH keys"), + (r'systemd.*\.service|systemctl\s+(enable|start)', + "systemd_service", "medium", "persistence", + "references or enables systemd service"), + (r'/etc/init\.d/', + "init_script", "medium", "persistence", + "references init.d startup script"), + (r'launchctl\s+load|LaunchAgents|LaunchDaemons', + "macos_launchd", "medium", "persistence", + "macOS launch agent/daemon persistence"), + (r'/etc/sudoers|visudo', + "sudoers_mod", "critical", "persistence", + "modifies sudoers (privilege escalation)"), + (r'git\s+config\s+--global\s+', + "git_config_global", "medium", "persistence", + "modifies global git configuration"), + + # ── Network: reverse shells and tunnels ── + (r'\bnc\s+-[lp]|ncat\s+-[lp]|\bsocat\b', + "reverse_shell", "critical", "network", + "potential reverse shell listener"), + (r'\bngrok\b|\blocaltunnel\b|\bserveo\b|\bcloudflared\b', + "tunnel_service", "high", "network", + "uses tunneling service for external access"), + (r'\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}:\d{2,5}', + "hardcoded_ip_port", "medium", "network", + "hardcoded IP address with port"), + (r'0\.0\.0\.0:\d+|INADDR_ANY', + "bind_all_interfaces", "high", "network", + "binds to all network interfaces"), + (r'/bin/(ba)?sh\s+-i\s+.*>/dev/tcp/', + "bash_reverse_shell", "critical", "network", + "bash interactive reverse shell via /dev/tcp"), + (r'python[23]?\s+-c\s+["\']import\s+socket', + "python_socket_oneliner", "critical", "network", + "Python one-liner socket connection (likely reverse shell)"), + (r'socket\.connect\s*\(\s*\(', + "python_socket_connect", "high", "network", + "Python socket connect to arbitrary host"), + (r'webhook\.site|requestbin\.com|pipedream\.net|hookbin\.com', + "exfil_service", "high", "network", + "references known data exfiltration/webhook testing service"), + (r'pastebin\.com|hastebin\.com|ghostbin\.', + "paste_service", "medium", "network", + "references paste service (possible data staging)"), + + # ── Obfuscation: encoding and eval ── + (r'base64\s+(-d|--decode)\s*\|', + "base64_decode_pipe", "high", "obfuscation", + "base64 decodes and pipes to execution"), + (r'\\x[0-9a-fA-F]{2}.*\\x[0-9a-fA-F]{2}.*\\x[0-9a-fA-F]{2}', + "hex_encoded_string", "medium", "obfuscation", + "hex-encoded string (possible obfuscation)"), + (r'\beval\s*\(\s*["\']', + "eval_string", "high", "obfuscation", + "eval() with string argument"), + (r'\bexec\s*\(\s*["\']', + "exec_string", "high", "obfuscation", + "exec() with string argument"), + (r'echo\s+[^\n]*\|\s*(bash|sh|python|perl|ruby|node)', + "echo_pipe_exec", "critical", "obfuscation", + "echo piped to interpreter for execution"), + (r'compile\s*\(\s*[^\)]+,\s*["\'].*["\']\s*,\s*["\']exec["\']\s*\)', + "python_compile_exec", "high", "obfuscation", + "Python compile() with exec mode"), + (r'getattr\s*\(\s*__builtins__', + "python_getattr_builtins", "high", "obfuscation", + "dynamic access to Python builtins (evasion technique)"), + (r'__import__\s*\(\s*["\']os["\']\s*\)', + "python_import_os", "high", "obfuscation", + "dynamic import of os module"), + (r'codecs\.decode\s*\(\s*["\']', + "python_codecs_decode", "medium", "obfuscation", + "codecs.decode (possible ROT13 or encoding obfuscation)"), + (r'String\.fromCharCode|charCodeAt', + "js_char_code", "medium", "obfuscation", + "JavaScript character code construction (possible obfuscation)"), + (r'atob\s*\(|btoa\s*\(', + "js_base64", "medium", "obfuscation", + "JavaScript base64 encode/decode"), + (r'\[::-1\]', + "string_reversal", "low", "obfuscation", + "string reversal (possible obfuscated payload)"), + (r'chr\s*\(\s*\d+\s*\)\s*\+\s*chr\s*\(\s*\d+', + "chr_building", "high", "obfuscation", + "building string from chr() calls (obfuscation)"), + (r'\\u[0-9a-fA-F]{4}.*\\u[0-9a-fA-F]{4}.*\\u[0-9a-fA-F]{4}', + "unicode_escape_chain", "medium", "obfuscation", + "chain of unicode escapes (possible obfuscation)"), + + # ── Process execution in scripts ── + (r'subprocess\.(run|call|Popen|check_output)\s*\(', + "python_subprocess", "medium", "execution", + "Python subprocess execution"), + (r'os\.system\s*\(', + "python_os_system", "high", "execution", + "os.system() — unguarded shell execution"), + (r'os\.popen\s*\(', + "python_os_popen", "high", "execution", + "os.popen() — shell pipe execution"), + (r'child_process\.(exec|spawn|fork)\s*\(', + "node_child_process", "high", "execution", + "Node.js child_process execution"), + (r'Runtime\.getRuntime\(\)\.exec\(', + "java_runtime_exec", "high", "execution", + "Java Runtime.exec() — shell execution"), + (r'`[^`]*\$\([^)]+\)[^`]*`', + "backtick_subshell", "medium", "execution", + "backtick string with command substitution"), + + # ── Path traversal ── + (r'\.\./\.\./\.\.', + "path_traversal_deep", "high", "traversal", + "deep relative path traversal (3+ levels up)"), + (r'\.\./\.\.', + "path_traversal", "medium", "traversal", + "relative path traversal (2+ levels up)"), + (r'/etc/passwd|/etc/shadow', + "system_passwd_access", "critical", "traversal", + "references system password files"), + (r'/proc/self|/proc/\d+/', + "proc_access", "high", "traversal", + "references /proc filesystem (process introspection)"), + (r'/dev/shm/', + "dev_shm", "medium", "traversal", + "references shared memory (common staging area)"), + + # ── Crypto mining ── + (r'xmrig|stratum\+tcp|monero|coinhive|cryptonight', + "crypto_mining", "critical", "mining", + "cryptocurrency mining reference"), + (r'hashrate|nonce.*difficulty', + "mining_indicators", "medium", "mining", + "possible cryptocurrency mining indicators"), + + # ── Supply chain: curl/wget pipe to shell ── + (r'curl\s+[^\n]*\|\s*(ba)?sh', + "curl_pipe_shell", "critical", "supply_chain", + "curl piped to shell (download-and-execute)"), + (r'wget\s+[^\n]*-O\s*-\s*\|\s*(ba)?sh', + "wget_pipe_shell", "critical", "supply_chain", + "wget piped to shell (download-and-execute)"), + (r'curl\s+[^\n]*\|\s*python', + "curl_pipe_python", "critical", "supply_chain", + "curl piped to Python interpreter"), + + # ── Supply chain: unpinned/deferred dependencies ── + (r'#\s*///\s*script.*dependencies', + "pep723_inline_deps", "medium", "supply_chain", + "PEP 723 inline script metadata with dependencies (verify pinning)"), + (r'pip\s+install\s+(?!-r\s)(?!.*==)', + "unpinned_pip_install", "medium", "supply_chain", + "pip install without version pinning"), + (r'npm\s+install\s+(?!.*@\d)', + "unpinned_npm_install", "medium", "supply_chain", + "npm install without version pinning"), + (r'uv\s+run\s+', + "uv_run", "medium", "supply_chain", + "uv run (may auto-install unpinned dependencies)"), + + # ── Supply chain: remote resource fetching ── + (r'(curl|wget|httpx?\.get|requests\.get|fetch)\s*[\(]?\s*["\']https?://', + "remote_fetch", "medium", "supply_chain", + "fetches remote resource at runtime"), + (r'git\s+clone\s+', + "git_clone", "medium", "supply_chain", + "clones a git repository at runtime"), + (r'docker\s+pull\s+', + "docker_pull", "medium", "supply_chain", + "pulls a Docker image at runtime"), + + # ── Privilege escalation ── + (r'^allowed-tools\s*:', + "allowed_tools_field", "high", "privilege_escalation", + "skill declares allowed-tools (pre-approves tool access)"), + (r'\bsudo\b', + "sudo_usage", "high", "privilege_escalation", + "uses sudo (privilege escalation)"), + (r'setuid|setgid|cap_setuid', + "setuid_setgid", "critical", "privilege_escalation", + "setuid/setgid (privilege escalation mechanism)"), + (r'NOPASSWD', + "nopasswd_sudo", "critical", "privilege_escalation", + "NOPASSWD sudoers entry (passwordless privilege escalation)"), + (r'chmod\s+[u+]?s', + "suid_bit", "critical", "privilege_escalation", + "sets SUID/SGID bit on a file"), + + # ── Agent config persistence ── + (r'AGENTS\.md|CLAUDE\.md|\.cursorrules|\.clinerules', + "agent_config_mod", "critical", "persistence", + "references agent config files (could persist malicious instructions across sessions)"), + (r'\.hermes/config\.yaml|\.hermes/SOUL\.md', + "hermes_config_mod", "critical", "persistence", + "references Hermes configuration files directly"), + (r'\.claude/settings|\.codex/config', + "other_agent_config", "high", "persistence", + "references other agent configuration files"), + + # ── Hardcoded secrets (credentials embedded in the skill itself) ── + (r'(?:api[_-]?key|token|secret|password)\s*[=:]\s*["\'][A-Za-z0-9+/=_-]{20,}', + "hardcoded_secret", "critical", "credential_exposure", + "possible hardcoded API key, token, or secret"), + (r'-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----', + "embedded_private_key", "critical", "credential_exposure", + "embedded private key"), + (r'ghp_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{80,}', + "github_token_leaked", "critical", "credential_exposure", + "GitHub personal access token in skill content"), + (r'sk-[A-Za-z0-9]{20,}', + "openai_key_leaked", "critical", "credential_exposure", + "possible OpenAI API key in skill content"), + (r'sk-ant-[A-Za-z0-9_-]{90,}', + "anthropic_key_leaked", "critical", "credential_exposure", + "possible Anthropic API key in skill content"), + (r'AKIA[0-9A-Z]{16}', + "aws_access_key_leaked", "critical", "credential_exposure", + "AWS access key ID in skill content"), + + # ── Additional prompt injection: jailbreak patterns ── + (r'\bDAN\s+mode\b|Do\s+Anything\s+Now', + "jailbreak_dan", "critical", "injection", + "DAN (Do Anything Now) jailbreak attempt"), + (r'\bdeveloper\s+mode\b.*\benabled?\b', + "jailbreak_dev_mode", "critical", "injection", + "developer mode jailbreak attempt"), + (r'hypothetical\s+scenario.*(?:ignore|bypass|override)', + "hypothetical_bypass", "high", "injection", + "hypothetical scenario used to bypass restrictions"), + (r'for\s+educational\s+purposes?\s+only', + "educational_pretext", "medium", "injection", + "educational pretext often used to justify harmful content"), + (r'(respond|answer|reply)\s+without\s+(?:\w+\s+)*(restrictions|limitations|filters|safety)', + "remove_filters", "critical", "injection", + "instructs agent to respond without safety filters"), + (r'you\s+have\s+been\s+(?:\w+\s+)*(updated|upgraded|patched)\s+to', + "fake_update", "high", "injection", + "fake update/patch announcement (social engineering)"), + (r'new\s+policy|updated\s+guidelines|revised\s+instructions', + "fake_policy", "medium", "injection", + "claims new policy/guidelines (may be social engineering)"), + + # ── Context window exfiltration ── + (r'(include|output|print|send|share)\s+(?:\w+\s+)*(conversation|chat\s+history|previous\s+messages|context)', + "context_exfil", "high", "exfiltration", + "instructs agent to output/share conversation history"), + (r'(send|post|upload|transmit)\s+.*\s+(to|at)\s+https?://', + "send_to_url", "high", "exfiltration", + "instructs agent to send data to a URL"), +] + +# Structural limits for skill directories +MAX_FILE_COUNT = 50 # skills shouldn't have 50+ files +MAX_TOTAL_SIZE_KB = 1024 # 1MB total is suspicious for a skill +MAX_SINGLE_FILE_KB = 256 # individual file > 256KB is suspicious + +# File extensions to scan (text files only — skip binary) +SCANNABLE_EXTENSIONS = { + '.md', '.txt', '.py', '.sh', '.bash', '.js', '.ts', '.rb', + '.yaml', '.yml', '.json', '.toml', '.cfg', '.ini', '.conf', + '.html', '.css', '.xml', '.tex', '.r', '.jl', '.pl', '.php', +} + +# Known binary extensions that should NOT be in a skill +SUSPICIOUS_BINARY_EXTENSIONS = { + '.exe', '.dll', '.so', '.dylib', '.bin', '.dat', '.com', + '.msi', '.dmg', '.app', '.deb', '.rpm', +} + +# Zero-width and invisible unicode characters used for injection +INVISIBLE_CHARS = { + '\u200b', # zero-width space + '\u200c', # zero-width non-joiner + '\u200d', # zero-width joiner + '\u2060', # word joiner + '\u2062', # invisible times + '\u2063', # invisible separator + '\u2064', # invisible plus + '\ufeff', # zero-width no-break space (BOM) + '\u202a', # left-to-right embedding + '\u202b', # right-to-left embedding + '\u202c', # pop directional formatting + '\u202d', # left-to-right override + '\u202e', # right-to-left override + '\u2066', # left-to-right isolate + '\u2067', # right-to-left isolate + '\u2068', # first strong isolate + '\u2069', # pop directional isolate +} + + +# --------------------------------------------------------------------------- +# Scanning functions +# --------------------------------------------------------------------------- + +def scan_file(file_path: Path, rel_path: str = "") -> List[Finding]: + """ + Scan a single file for threat patterns and invisible unicode characters. + + Args: + file_path: Absolute path to the file + rel_path: Relative path for display (defaults to file_path.name) + + Returns: + List of findings (deduplicated per pattern per line) + """ + if not rel_path: + rel_path = file_path.name + + if file_path.suffix.lower() not in SCANNABLE_EXTENSIONS and file_path.name != "SKILL.md": + return [] + + try: + content = file_path.read_text(encoding='utf-8') + except (UnicodeDecodeError, OSError): + return [] + + findings = [] + lines = content.split('\n') + seen = set() # (pattern_id, line_number) for deduplication + + # Regex pattern matching + for pattern, pid, severity, category, description in THREAT_PATTERNS: + for i, line in enumerate(lines, start=1): + if (pid, i) in seen: + continue + if re.search(pattern, line, re.IGNORECASE): + seen.add((pid, i)) + matched_text = line.strip() + if len(matched_text) > 120: + matched_text = matched_text[:117] + "..." + findings.append(Finding( + pattern_id=pid, + severity=severity, + category=category, + file=rel_path, + line=i, + match=matched_text, + description=description, + )) + + # Invisible unicode character detection + for i, line in enumerate(lines, start=1): + for char in INVISIBLE_CHARS: + if char in line: + char_name = _unicode_char_name(char) + findings.append(Finding( + pattern_id="invisible_unicode", + severity="high", + category="injection", + file=rel_path, + line=i, + match=f"U+{ord(char):04X} ({char_name})", + description=f"invisible unicode character {char_name} (possible text hiding/injection)", + )) + break # one finding per line for invisible chars + + return findings + + +def scan_skill(skill_path: Path, source: str = "community") -> ScanResult: + """ + Scan all files in a skill directory for security threats. + + Performs: + 1. Structural checks (file count, total size, binary files, symlinks) + 2. Regex pattern matching on all text files + 3. Invisible unicode character detection + + Args: + skill_path: Path to the skill directory (must contain SKILL.md) + source: Source identifier for trust level resolution (e.g. "openai/skills") + + Returns: + ScanResult with verdict, findings, and trust metadata + """ + skill_name = skill_path.name + trust_level = _resolve_trust_level(source) + + all_findings: List[Finding] = [] + + if skill_path.is_dir(): + # Structural checks first + all_findings.extend(_check_structure(skill_path)) + + # Pattern scanning on each file + for f in skill_path.rglob("*"): + if f.is_file(): + rel = str(f.relative_to(skill_path)) + all_findings.extend(scan_file(f, rel)) + elif skill_path.is_file(): + all_findings.extend(scan_file(skill_path, skill_path.name)) + + verdict = _determine_verdict(all_findings) + summary = _build_summary(skill_name, source, trust_level, verdict, all_findings) + + return ScanResult( + skill_name=skill_name, + source=source, + trust_level=trust_level, + verdict=verdict, + findings=all_findings, + scanned_at=datetime.now(timezone.utc).isoformat(), + summary=summary, + ) + + +def should_allow_install(result: ScanResult, force: bool = False) -> Tuple[bool, str]: + """ + Determine whether a skill should be installed based on scan result and trust. + + Args: + result: Scan result from scan_skill() + force: If True, override blocked policy decisions for this scan result + + Returns: + (allowed, reason) tuple + """ + policy = INSTALL_POLICY.get(result.trust_level, INSTALL_POLICY["community"]) + vi = VERDICT_INDEX.get(result.verdict, 2) + decision = policy[vi] + + if decision == "allow": + return True, f"Allowed ({result.trust_level} source, {result.verdict} verdict)" + + if force: + return True, ( + f"Force-installed despite {result.verdict} verdict " + f"({len(result.findings)} findings)" + ) + + if decision == "ask": + # Return None to signal "needs user confirmation" + return None, ( + f"Requires confirmation ({result.trust_level} source + {result.verdict} verdict, " + f"{len(result.findings)} findings)" + ) + + return False, ( + f"Blocked ({result.trust_level} source + {result.verdict} verdict, " + f"{len(result.findings)} findings). Use --force to override." + ) + + +def format_scan_report(result: ScanResult) -> str: + """ + Format a scan result as a human-readable report string. + + Returns a compact multi-line report suitable for CLI or chat display. + """ + lines = [] + + verdict_display = result.verdict.upper() + lines.append(f"Scan: {result.skill_name} ({result.source}/{result.trust_level}) Verdict: {verdict_display}") + + if result.findings: + # Group and sort: critical first, then high, medium, low + severity_order = {"critical": 0, "high": 1, "medium": 2, "low": 3} + sorted_findings = sorted(result.findings, key=lambda f: severity_order.get(f.severity, 4)) + + for f in sorted_findings: + sev = f.severity.upper().ljust(8) + cat = f.category.ljust(14) + loc = f"{f.file}:{f.line}".ljust(30) + lines.append(f" {sev} {cat} {loc} \"{f.match[:60]}\"") + + lines.append("") + + allowed, reason = should_allow_install(result) + if allowed is True: + status = "ALLOWED" + elif allowed is None: + status = "NEEDS CONFIRMATION" + else: + status = "BLOCKED" + lines.append(f"Decision: {status} — {reason}") + + return "\n".join(lines) + + +def content_hash(skill_path: Path) -> str: + """Compute a SHA-256 hash of all files in a skill directory for integrity tracking.""" + h = hashlib.sha256() + if skill_path.is_dir(): + for f in sorted(skill_path.rglob("*")): + if f.is_file(): + try: + h.update(f.read_bytes()) + except OSError: + continue + elif skill_path.is_file(): + h.update(skill_path.read_bytes()) + return f"sha256:{h.hexdigest()[:16]}" + + +# --------------------------------------------------------------------------- +# Structural checks +# --------------------------------------------------------------------------- + +def _check_structure(skill_dir: Path) -> List[Finding]: + """ + Check the skill directory for structural anomalies: + - Too many files + - Suspiciously large total size + - Binary/executable files that shouldn't be in a skill + - Symlinks pointing outside the skill directory + - Individual files that are too large + """ + findings = [] + file_count = 0 + total_size = 0 + + for f in skill_dir.rglob("*"): + if not f.is_file() and not f.is_symlink(): + continue + + rel = str(f.relative_to(skill_dir)) + file_count += 1 + + # Symlink check — must resolve within the skill directory + if f.is_symlink(): + try: + resolved = f.resolve() + if not resolved.is_relative_to(skill_dir.resolve()): + findings.append(Finding( + pattern_id="symlink_escape", + severity="critical", + category="traversal", + file=rel, + line=0, + match=f"symlink -> {resolved}", + description="symlink points outside the skill directory", + )) + except OSError: + findings.append(Finding( + pattern_id="broken_symlink", + severity="medium", + category="traversal", + file=rel, + line=0, + match="broken symlink", + description="broken or circular symlink", + )) + continue + + # Size tracking + try: + size = f.stat().st_size + total_size += size + except OSError: + continue + + # Single file too large + if size > MAX_SINGLE_FILE_KB * 1024: + findings.append(Finding( + pattern_id="oversized_file", + severity="medium", + category="structural", + file=rel, + line=0, + match=f"{size // 1024}KB", + description=f"file is {size // 1024}KB (limit: {MAX_SINGLE_FILE_KB}KB)", + )) + + # Binary/executable files + ext = f.suffix.lower() + if ext in SUSPICIOUS_BINARY_EXTENSIONS: + findings.append(Finding( + pattern_id="binary_file", + severity="critical", + category="structural", + file=rel, + line=0, + match=f"binary: {ext}", + description=f"binary/executable file ({ext}) should not be in a skill", + )) + + # Executable permission on non-script files + if ext not in ('.sh', '.bash', '.py', '.rb', '.pl') and f.stat().st_mode & 0o111: + findings.append(Finding( + pattern_id="unexpected_executable", + severity="medium", + category="structural", + file=rel, + line=0, + match="executable bit set", + description="file has executable permission but is not a recognized script type", + )) + + # File count limit + if file_count > MAX_FILE_COUNT: + findings.append(Finding( + pattern_id="too_many_files", + severity="medium", + category="structural", + file="(directory)", + line=0, + match=f"{file_count} files", + description=f"skill has {file_count} files (limit: {MAX_FILE_COUNT})", + )) + + # Total size limit + if total_size > MAX_TOTAL_SIZE_KB * 1024: + findings.append(Finding( + pattern_id="oversized_skill", + severity="high", + category="structural", + file="(directory)", + line=0, + match=f"{total_size // 1024}KB total", + description=f"skill is {total_size // 1024}KB total (limit: {MAX_TOTAL_SIZE_KB}KB)", + )) + + return findings + + +def _unicode_char_name(char: str) -> str: + """Get a readable name for an invisible unicode character.""" + names = { + '\u200b': "zero-width space", + '\u200c': "zero-width non-joiner", + '\u200d': "zero-width joiner", + '\u2060': "word joiner", + '\u2062': "invisible times", + '\u2063': "invisible separator", + '\u2064': "invisible plus", + '\ufeff': "BOM/zero-width no-break space", + '\u202a': "LTR embedding", + '\u202b': "RTL embedding", + '\u202c': "pop directional", + '\u202d': "LTR override", + '\u202e': "RTL override", + '\u2066': "LTR isolate", + '\u2067': "RTL isolate", + '\u2068': "first strong isolate", + '\u2069': "pop directional isolate", + } + return names.get(char, f"U+{ord(char):04X}") + + + +# --------------------------------------------------------------------------- +# Internal helpers +# --------------------------------------------------------------------------- + +def _resolve_trust_level(source: str) -> str: + """Map a source identifier to a trust level.""" + prefix_aliases = ( + "skills-sh/", + "skills.sh/", + "skils-sh/", + "skils.sh/", + ) + normalized_source = source + for prefix in prefix_aliases: + if normalized_source.startswith(prefix): + normalized_source = normalized_source[len(prefix):] + break + + # Agent-created skills get their own permissive trust level + if normalized_source == "agent-created": + return "agent-created" + # Official optional skills shipped with the repo + if normalized_source.startswith("official/") or normalized_source == "official": + return "builtin" + # Check if source matches any trusted repo + for trusted in TRUSTED_REPOS: + if normalized_source.startswith(trusted) or normalized_source == trusted: + return "trusted" + return "community" + + +def _determine_verdict(findings: List[Finding]) -> str: + """Determine the overall verdict from a list of findings.""" + if not findings: + return "safe" + + has_critical = any(f.severity == "critical" for f in findings) + has_high = any(f.severity == "high" for f in findings) + + if has_critical: + return "dangerous" + if has_high: + return "caution" + return "caution" + + +def _build_summary(name: str, source: str, trust: str, verdict: str, findings: List[Finding]) -> str: + """Build a one-line summary of the scan result.""" + if not findings: + return f"{name}: clean scan, no threats detected" + + categories = set(f.category for f in findings) + return f"{name}: {verdict} — {len(findings)} finding(s) in {', '.join(sorted(categories))}" diff --git a/mindcli/_vendor/tools/skills_hub.py b/mindcli/_vendor/tools/skills_hub.py new file mode 100644 index 0000000..47aef80 --- /dev/null +++ b/mindcli/_vendor/tools/skills_hub.py @@ -0,0 +1,3053 @@ +#!/usr/bin/env python3 +""" +Skills Hub — Source adapters and hub state management for the Hermes Skills Hub. + +This is a library module (not an agent tool). It provides: + - GitHubAuth: Shared GitHub API authentication (PAT, gh CLI, GitHub App) + - SkillSource ABC: Interface for all skill registry adapters + - OptionalSkillSource: Official optional skills shipped with the repo (not activated by default) + - GitHubSource: Fetch skills from any GitHub repo via the Contents API + - HubLockFile: Track provenance of installed hub skills + - Hub state directory management (quarantine, audit log, taps, index cache) + +Used by hermes_cli/skills_hub.py for CLI commands and the /skills slash command. +""" + +import hashlib +import json +import logging +import os +import re +import shutil +import subprocess +import time +from abc import ABC, abstractmethod +from dataclasses import dataclass, field +from datetime import datetime, timezone +from pathlib import Path, PurePosixPath +from hermes_constants import get_hermes_home +from typing import Any, Dict, List, Optional, Tuple, Union +from urllib.parse import urlparse, urlunparse + +import httpx +import yaml + +from tools.skills_guard import ( + ScanResult, content_hash, TRUSTED_REPOS, +) + +logger = logging.getLogger(__name__) + + +# --------------------------------------------------------------------------- +# Paths +# --------------------------------------------------------------------------- + +HERMES_HOME = get_hermes_home() +SKILLS_DIR = HERMES_HOME / "skills" +HUB_DIR = SKILLS_DIR / ".hub" +LOCK_FILE = HUB_DIR / "lock.json" +QUARANTINE_DIR = HUB_DIR / "quarantine" +AUDIT_LOG = HUB_DIR / "audit.log" +TAPS_FILE = HUB_DIR / "taps.json" +INDEX_CACHE_DIR = HUB_DIR / "index-cache" + +# Cache duration for remote index fetches +INDEX_CACHE_TTL = 3600 # 1 hour + + +# --------------------------------------------------------------------------- +# Data models +# --------------------------------------------------------------------------- + +@dataclass +class SkillMeta: + """Minimal metadata returned by search results.""" + name: str + description: str + source: str # "official", "github", "clawhub", "claude-marketplace", "lobehub" + identifier: str # source-specific ID (e.g. "openai/skills/skill-creator") + trust_level: str # "builtin" | "trusted" | "community" + repo: Optional[str] = None + path: Optional[str] = None + tags: List[str] = field(default_factory=list) + extra: Dict[str, Any] = field(default_factory=dict) + + +@dataclass +class SkillBundle: + """A downloaded skill ready for quarantine/scanning/installation.""" + name: str + files: Dict[str, Union[str, bytes]] # relative_path -> file content + source: str + identifier: str + trust_level: str + metadata: Dict[str, Any] = field(default_factory=dict) + + +def _normalize_bundle_path(path_value: str, *, field_name: str, allow_nested: bool) -> str: + """Normalize and validate bundle-controlled paths before touching disk.""" + if not isinstance(path_value, str): + raise ValueError(f"Unsafe {field_name}: expected a string") + + raw = path_value.strip() + if not raw: + raise ValueError(f"Unsafe {field_name}: empty path") + + normalized = raw.replace("\\", "/") + path = PurePosixPath(normalized) + parts = [part for part in path.parts if part not in ("", ".")] + + if normalized.startswith("/") or path.is_absolute(): + raise ValueError(f"Unsafe {field_name}: {path_value}") + if not parts or any(part == ".." for part in parts): + raise ValueError(f"Unsafe {field_name}: {path_value}") + if re.fullmatch(r"[A-Za-z]:", parts[0]): + raise ValueError(f"Unsafe {field_name}: {path_value}") + if not allow_nested and len(parts) != 1: + raise ValueError(f"Unsafe {field_name}: {path_value}") + + return "/".join(parts) + + +def _validate_skill_name(name: str) -> str: + return _normalize_bundle_path(name, field_name="skill name", allow_nested=False) + + +def _validate_category_name(category: str) -> str: + return _normalize_bundle_path(category, field_name="category", allow_nested=False) + + +def _validate_bundle_rel_path(rel_path: str) -> str: + return _normalize_bundle_path(rel_path, field_name="bundle file path", allow_nested=True) + + +# --------------------------------------------------------------------------- +# GitHub Authentication +# --------------------------------------------------------------------------- + +class GitHubAuth: + """ + GitHub API authentication. Tries methods in priority order: + 1. GITHUB_TOKEN / GH_TOKEN env var (PAT — the default) + 2. `gh auth token` subprocess (if gh CLI is installed) + 3. GitHub App JWT + installation token (if app credentials configured) + 4. Unauthenticated (60 req/hr, public repos only) + """ + + def __init__(self): + self._cached_token: Optional[str] = None + self._cached_method: Optional[str] = None + self._app_token_expiry: float = 0 + + def get_headers(self) -> Dict[str, str]: + """Return authorization headers for GitHub API requests.""" + token = self._resolve_token() + headers = {"Accept": "application/vnd.github.v3+json"} + if token: + headers["Authorization"] = f"token {token}" + return headers + + def is_authenticated(self) -> bool: + return self._resolve_token() is not None + + def auth_method(self) -> str: + """Return which auth method is active: 'pat', 'gh-cli', 'github-app', or 'anonymous'.""" + self._resolve_token() + return self._cached_method or "anonymous" + + def _resolve_token(self) -> Optional[str]: + # Return cached token if still valid + if self._cached_token: + if self._cached_method != "github-app" or time.time() < self._app_token_expiry: + return self._cached_token + + # 1. Environment variable + token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN") + if token: + self._cached_token = token + self._cached_method = "pat" + return token + + # 2. gh CLI + token = self._try_gh_cli() + if token: + self._cached_token = token + self._cached_method = "gh-cli" + return token + + # 3. GitHub App + token = self._try_github_app() + if token: + self._cached_token = token + self._cached_method = "github-app" + self._app_token_expiry = time.time() + 3500 # ~58 min (tokens last 1 hour) + return token + + self._cached_method = "anonymous" + return None + + def _try_gh_cli(self) -> Optional[str]: + """Try to get a token from the gh CLI.""" + try: + result = subprocess.run( + ["gh", "auth", "token"], + capture_output=True, text=True, timeout=5, + ) + if result.returncode == 0 and result.stdout.strip(): + return result.stdout.strip() + except (FileNotFoundError, subprocess.TimeoutExpired) as e: + logger.debug("gh CLI token lookup failed: %s", e) + return None + + def _try_github_app(self) -> Optional[str]: + """Try GitHub App JWT authentication if credentials are configured.""" + app_id = os.environ.get("GITHUB_APP_ID") + key_path = os.environ.get("GITHUB_APP_PRIVATE_KEY_PATH") + installation_id = os.environ.get("GITHUB_APP_INSTALLATION_ID") + + if not all([app_id, key_path, installation_id]): + return None + + try: + import jwt # PyJWT + except ImportError: + logger.debug("PyJWT not installed, skipping GitHub App auth") + return None + + try: + key_file = Path(key_path) + if not key_file.exists(): + return None + private_key = key_file.read_text() + + now = int(time.time()) + payload = { + "iat": now - 60, + "exp": now + (10 * 60), + "iss": app_id, + } + encoded_jwt = jwt.encode(payload, private_key, algorithm="RS256") + + resp = httpx.post( + f"https://api.github.com/app/installations/{installation_id}/access_tokens", + headers={ + "Authorization": f"Bearer {encoded_jwt}", + "Accept": "application/vnd.github.v3+json", + }, + timeout=10, + ) + if resp.status_code == 201: + return resp.json().get("token") + except Exception as e: + logger.debug(f"GitHub App auth failed: {e}") + + return None + + +# --------------------------------------------------------------------------- +# Source adapter interface +# --------------------------------------------------------------------------- + +class SkillSource(ABC): + """Abstract base for all skill registry adapters.""" + + @abstractmethod + def search(self, query: str, limit: int = 10) -> List[SkillMeta]: + """Search for skills matching a query string.""" + ... + + @abstractmethod + def fetch(self, identifier: str) -> Optional[SkillBundle]: + """Download a skill bundle by identifier.""" + ... + + @abstractmethod + def inspect(self, identifier: str) -> Optional[SkillMeta]: + """Fetch metadata for a skill without downloading all files.""" + ... + + @abstractmethod + def source_id(self) -> str: + """Unique identifier for this source (e.g. 'github', 'clawhub').""" + ... + + def trust_level_for(self, identifier: str) -> str: + """Determine trust level for a skill from this source.""" + return "community" + + +# --------------------------------------------------------------------------- +# GitHub source adapter +# --------------------------------------------------------------------------- + +class GitHubSource(SkillSource): + """Fetch skills from GitHub repos via the Contents API.""" + + DEFAULT_TAPS = [ + {"repo": "openai/skills", "path": "skills/"}, + {"repo": "anthropics/skills", "path": "skills/"}, + {"repo": "VoltAgent/awesome-agent-skills", "path": "skills/"}, + {"repo": "garrytan/gstack", "path": ""}, + ] + + def __init__(self, auth: GitHubAuth, extra_taps: Optional[List[Dict]] = None): + self.auth = auth + self.taps = list(self.DEFAULT_TAPS) + if extra_taps: + self.taps.extend(extra_taps) + # Per-instance cache: repo -> (default_branch, tree_entries) + # Survives within a single search/install flow, avoiding redundant API calls. + self._tree_cache: Dict[str, Tuple[str, List[dict]]] = {} + # Set when GitHub returns 403 with rate limit exhausted + self._rate_limited: bool = False + + def source_id(self) -> str: + return "github" + + @property + def is_rate_limited(self) -> bool: + """Whether GitHub API rate limit was hit during operations.""" + return self._rate_limited + + def trust_level_for(self, identifier: str) -> str: + # identifier format: "owner/repo/path/to/skill" + parts = identifier.split("/", 2) + if len(parts) >= 2: + repo = f"{parts[0]}/{parts[1]}" + if repo in TRUSTED_REPOS: + return "trusted" + return "community" + + def search(self, query: str, limit: int = 10) -> List[SkillMeta]: + """Search all taps for skills matching the query.""" + results: List[SkillMeta] = [] + query_lower = query.lower() + + for tap in self.taps: + try: + skills = self._list_skills_in_repo(tap["repo"], tap.get("path", "")) + for skill in skills: + searchable = f"{skill.name} {skill.description} {' '.join(skill.tags)}".lower() + if query_lower in searchable: + results.append(skill) + except Exception as e: + logger.debug(f"Failed to search {tap['repo']}: {e}") + continue + + # Deduplicate by name, preferring higher trust levels + _trust_rank = {"builtin": 2, "trusted": 1, "community": 0} + seen = {} + for r in results: + if r.name not in seen: + seen[r.name] = r + elif _trust_rank.get(r.trust_level, 0) > _trust_rank.get(seen[r.name].trust_level, 0): + seen[r.name] = r + results = list(seen.values()) + + return results[:limit] + + def fetch(self, identifier: str) -> Optional[SkillBundle]: + """ + Download a skill from GitHub. + identifier format: "owner/repo/path/to/skill-dir" + """ + parts = identifier.split("/", 2) + if len(parts) < 3: + return None + + repo = f"{parts[0]}/{parts[1]}" + skill_path = parts[2] + + files = self._download_directory(repo, skill_path) + if not files or "SKILL.md" not in files: + return None + + skill_name = skill_path.rstrip("/").split("/")[-1] + trust = self.trust_level_for(identifier) + + return SkillBundle( + name=skill_name, + files=files, + source="github", + identifier=identifier, + trust_level=trust, + ) + + def inspect(self, identifier: str) -> Optional[SkillMeta]: + """Fetch just the SKILL.md metadata for preview.""" + parts = identifier.split("/", 2) + if len(parts) < 3: + return None + + repo = f"{parts[0]}/{parts[1]}" + skill_path = parts[2].rstrip("/") + skill_md_path = f"{skill_path}/SKILL.md" + + content = self._fetch_file_content(repo, skill_md_path) + if not content: + return None + + fm = self._parse_frontmatter_quick(content) + skill_name = fm.get("name", skill_path.split("/")[-1]) + description = fm.get("description", "") + + tags = [] + metadata = fm.get("metadata", {}) + if isinstance(metadata, dict): + hermes_meta = metadata.get("hermes", {}) + if isinstance(hermes_meta, dict): + tags = hermes_meta.get("tags", []) + if not tags: + raw_tags = fm.get("tags", []) + tags = raw_tags if isinstance(raw_tags, list) else [] + + return SkillMeta( + name=skill_name, + description=str(description), + source="github", + identifier=identifier, + trust_level=self.trust_level_for(identifier), + repo=repo, + path=skill_path, + tags=[str(t) for t in tags], + ) + + # -- Internal helpers -- + + def _list_skills_in_repo(self, repo: str, path: str) -> List[SkillMeta]: + """List skill directories in a GitHub repo path, using cached index.""" + cache_key = f"{repo}_{path}".replace("/", "_").replace(" ", "_") + cached = self._read_cache(cache_key) + if cached is not None: + return [SkillMeta(**s) for s in cached] + + url = f"https://api.github.com/repos/{repo}/contents/{path.rstrip('/')}" + try: + resp = httpx.get(url, headers=self.auth.get_headers(), timeout=15, follow_redirects=True) + if resp.status_code != 200: + return [] + except httpx.HTTPError: + return [] + + entries = resp.json() + if not isinstance(entries, list): + return [] + + skills: List[SkillMeta] = [] + for entry in entries: + if entry.get("type") != "dir": + continue + + dir_name = entry["name"] + if dir_name.startswith((".", "_")): + continue + + prefix = path.rstrip("/") + skill_identifier = f"{repo}/{prefix}/{dir_name}" if prefix else f"{repo}/{dir_name}" + meta = self.inspect(skill_identifier) + if meta: + skills.append(meta) + + # Cache the results + self._write_cache(cache_key, [self._meta_to_dict(s) for s in skills]) + return skills + + # -- Repo tree cache (avoids redundant API calls) -- + + def _get_repo_tree(self, repo: str) -> Optional[Tuple[str, List[dict]]]: + """Get cached or fresh repo tree. + + Returns ``(default_branch, tree_entries)`` or ``None``. + A single install can call ``_download_directory_via_tree`` and + ``_find_skill_in_repo_tree`` multiple times for the same repo — this + cache eliminates the redundant ``GET /repos/{repo}`` + + ``GET /repos/{repo}/git/trees/{branch}`` round-trips (previously up to + 6 duplicated pairs per install, consuming ~12 of the 60/hr + unauthenticated rate limit for nothing). + """ + if repo in self._tree_cache: + return self._tree_cache[repo] + + headers = self.auth.get_headers() + + # Resolve default branch + try: + resp = httpx.get( + f"https://api.github.com/repos/{repo}", + headers=headers, timeout=15, follow_redirects=True, + ) + if resp.status_code != 200: + self._check_rate_limit_response(resp) + return None + default_branch = resp.json().get("default_branch", "main") + except (httpx.HTTPError, ValueError): + return None + + # Fetch recursive tree + try: + resp = httpx.get( + f"https://api.github.com/repos/{repo}/git/trees/{default_branch}", + params={"recursive": "1"}, + headers=headers, timeout=30, follow_redirects=True, + ) + if resp.status_code != 200: + self._check_rate_limit_response(resp) + return None + tree_data = resp.json() + if tree_data.get("truncated"): + logger.debug("Git tree truncated for %s, cannot cache", repo) + return None + except (httpx.HTTPError, ValueError): + return None + + entries = tree_data.get("tree", []) + self._tree_cache[repo] = (default_branch, entries) + return (default_branch, entries) + + def _check_rate_limit_response(self, resp: "httpx.Response") -> None: + """Flag the instance as rate-limited when GitHub returns 403 + exhausted quota.""" + if resp.status_code == 403: + remaining = resp.headers.get("X-RateLimit-Remaining", "") + if remaining == "0": + self._rate_limited = True + logger.warning( + "GitHub API rate limit exhausted (unauthenticated: 60 req/hr). " + "Set GITHUB_TOKEN or install the gh CLI to raise the limit to 5,000/hr." + ) + + def _download_directory(self, repo: str, path: str) -> Dict[str, str]: + """Recursively download all text files from a GitHub directory. + + Uses the Git Trees API first (single call for the entire tree) to + avoid per-directory rate limiting that causes silent subdirectory + loss. Falls back to the recursive Contents API when the tree + endpoint is unavailable or the response is truncated. + """ + files = self._download_directory_via_tree(repo, path) + if files is not None: + return files + logger.debug("Tree API unavailable for %s/%s, falling back to Contents API", repo, path) + return self._download_directory_recursive(repo, path) + + def _download_directory_via_tree(self, repo: str, path: str) -> Optional[Dict[str, str]]: + """Download an entire directory using the Git Trees API (single request). + + Returns: + dict of files if the path exists and has content, + empty dict ``{}`` if the tree is cached but the path doesn't exist + (prevents unnecessary Contents API fallback), + ``None`` if the tree couldn't be fetched (triggers Contents API fallback). + """ + path = path.rstrip("/") + + cached = self._get_repo_tree(repo) + if cached is None: + return None + _default_branch, tree_entries = cached + + # Check if ANY entry lives under the target path + prefix = f"{path}/" + has_entries = any( + item.get("path", "").startswith(prefix) for item in tree_entries + ) + if not has_entries: + # Path definitively doesn't exist in the repo — return empty + # instead of None to skip the Contents API fallback. + return {} + + # Filter to blobs under our target path and fetch content + files: Dict[str, str] = {} + for item in tree_entries: + if item.get("type") != "blob": + continue + item_path = item.get("path", "") + if not item_path.startswith(prefix): + continue + rel_path = item_path[len(prefix):] + content = self._fetch_file_content(repo, item_path) + if content is not None: + files[rel_path] = content + else: + logger.debug("Skipped file (fetch failed): %s/%s", repo, item_path) + + return files if files else None + + def _download_directory_recursive(self, repo: str, path: str) -> Dict[str, str]: + """Recursively download via Contents API (fallback).""" + url = f"https://api.github.com/repos/{repo}/contents/{path.rstrip('/')}" + try: + resp = httpx.get(url, headers=self.auth.get_headers(), timeout=15, follow_redirects=True) + if resp.status_code != 200: + logger.debug("Contents API returned %d for %s/%s", resp.status_code, repo, path) + return {} + except httpx.HTTPError: + return {} + + entries = resp.json() + if not isinstance(entries, list): + return {} + + files: Dict[str, str] = {} + for entry in entries: + name = entry.get("name", "") + entry_type = entry.get("type", "") + + if entry_type == "file": + content = self._fetch_file_content(repo, entry.get("path", "")) + if content is not None: + rel_path = name + files[rel_path] = content + elif entry_type == "dir": + sub_files = self._download_directory_recursive(repo, entry.get("path", "")) + if not sub_files: + logger.debug("Empty or failed subdirectory: %s/%s", repo, entry.get("path", "")) + for sub_name, sub_content in sub_files.items(): + files[f"{name}/{sub_name}"] = sub_content + + return files + + def _find_skill_in_repo_tree(self, repo: str, skill_name: str) -> Optional[str]: + """Use the GitHub Trees API to find a skill directory anywhere in the repo. + + Returns the full identifier (``repo/path/to/skill``) or ``None``. + This is a single API call regardless of repo depth, so it efficiently + handles deeply nested directory structures like + ``cli-tool/components/skills/development//SKILL.md``. + """ + cached = self._get_repo_tree(repo) + if cached is None: + return None + _default_branch, tree_entries = cached + + # Look for SKILL.md files inside directories named + skill_md_suffix = f"/{skill_name}/SKILL.md" + for entry in tree_entries: + if entry.get("type") != "blob": + continue + path = entry.get("path", "") + if path.endswith(skill_md_suffix) or path == f"{skill_name}/SKILL.md": + # Strip /SKILL.md to get the skill directory path + skill_dir = path[: -len("/SKILL.md")] + return f"{repo}/{skill_dir}" + + return None + + def _fetch_file_content(self, repo: str, path: str) -> Optional[str]: + """Fetch a single file's content from GitHub.""" + url = f"https://api.github.com/repos/{repo}/contents/{path}" + try: + resp = httpx.get( + url, + headers={**self.auth.get_headers(), "Accept": "application/vnd.github.v3.raw"}, + timeout=15, follow_redirects=True, + ) + if resp.status_code == 200: + return resp.text + self._check_rate_limit_response(resp) + except httpx.HTTPError as e: + logger.debug("GitHub contents API fetch failed: %s", e) + return None + + def _read_cache(self, key: str) -> Optional[list]: + """Read cached index if not expired.""" + cache_file = INDEX_CACHE_DIR / f"{key}.json" + if not cache_file.exists(): + return None + try: + stat = cache_file.stat() + if time.time() - stat.st_mtime > INDEX_CACHE_TTL: + return None + return json.loads(cache_file.read_text()) + except (OSError, json.JSONDecodeError): + return None + + def _write_cache(self, key: str, data: list) -> None: + """Write index data to cache.""" + INDEX_CACHE_DIR.mkdir(parents=True, exist_ok=True) + cache_file = INDEX_CACHE_DIR / f"{key}.json" + try: + cache_file.write_text(json.dumps(data, ensure_ascii=False)) + except OSError as e: + logger.debug("Could not write cache: %s", e) + + @staticmethod + def _meta_to_dict(meta: SkillMeta) -> dict: + return { + "name": meta.name, + "description": meta.description, + "source": meta.source, + "identifier": meta.identifier, + "trust_level": meta.trust_level, + "repo": meta.repo, + "path": meta.path, + "tags": meta.tags, + } + + @staticmethod + def _parse_frontmatter_quick(content: str) -> dict: + """Parse YAML frontmatter from SKILL.md content.""" + if not content.startswith("---"): + return {} + match = re.search(r'\n---\s*\n', content[3:]) + if not match: + return {} + yaml_text = content[3:match.start() + 3] + try: + parsed = yaml.safe_load(yaml_text) + return parsed if isinstance(parsed, dict) else {} + except yaml.YAMLError: + return {} + + +# --------------------------------------------------------------------------- +# Well-known Agent Skills endpoint source adapter +# --------------------------------------------------------------------------- + +class WellKnownSkillSource(SkillSource): + """Read skills from a domain exposing /.well-known/skills/index.json.""" + + BASE_PATH = "/.well-known/skills" + + def source_id(self) -> str: + return "well-known" + + def trust_level_for(self, identifier: str) -> str: + return "community" + + def search(self, query: str, limit: int = 10) -> List[SkillMeta]: + index_url = self._query_to_index_url(query) + if not index_url: + return [] + + parsed = self._parse_index(index_url) + if not parsed: + return [] + + results: List[SkillMeta] = [] + for entry in parsed["skills"][:limit]: + name = entry.get("name") + if not isinstance(name, str) or not name: + continue + description = entry.get("description", "") + files = entry.get("files", ["SKILL.md"]) + results.append(SkillMeta( + name=name, + description=str(description), + source="well-known", + identifier=self._wrap_identifier(parsed["base_url"], name), + trust_level="community", + path=name, + extra={ + "index_url": parsed["index_url"], + "base_url": parsed["base_url"], + "files": files if isinstance(files, list) else ["SKILL.md"], + }, + )) + return results + + def inspect(self, identifier: str) -> Optional[SkillMeta]: + parsed = self._parse_identifier(identifier) + if not parsed: + return None + + entry = self._index_entry(parsed["index_url"], parsed["skill_name"]) + if not entry: + return None + + skill_md = self._fetch_text(f"{parsed['skill_url']}/SKILL.md") + if skill_md is None: + return None + + fm = GitHubSource._parse_frontmatter_quick(skill_md) + description = str(fm.get("description") or entry.get("description") or "") + name = str(fm.get("name") or parsed["skill_name"]) + return SkillMeta( + name=name, + description=description, + source="well-known", + identifier=self._wrap_identifier(parsed["base_url"], parsed["skill_name"]), + trust_level="community", + path=parsed["skill_name"], + extra={ + "index_url": parsed["index_url"], + "base_url": parsed["base_url"], + "files": entry.get("files", ["SKILL.md"]), + "endpoint": parsed["skill_url"], + }, + ) + + def fetch(self, identifier: str) -> Optional[SkillBundle]: + parsed = self._parse_identifier(identifier) + if not parsed: + return None + + try: + skill_name = _validate_skill_name(parsed["skill_name"]) + except ValueError: + logger.warning("Well-known skill identifier contained unsafe skill name: %s", identifier) + return None + + entry = self._index_entry(parsed["index_url"], parsed["skill_name"]) + if not entry: + return None + + files = entry.get("files", ["SKILL.md"]) + if not isinstance(files, list) or not files: + files = ["SKILL.md"] + + downloaded: Dict[str, str] = {} + for rel_path in files: + if not isinstance(rel_path, str) or not rel_path: + continue + try: + safe_rel_path = _validate_bundle_rel_path(rel_path) + except ValueError: + logger.warning( + "Well-known skill %s advertised unsafe file path: %r", + identifier, + rel_path, + ) + return None + text = self._fetch_text(f"{parsed['skill_url']}/{safe_rel_path}") + if text is None: + return None + downloaded[safe_rel_path] = text + + if "SKILL.md" not in downloaded: + return None + + return SkillBundle( + name=skill_name, + files=downloaded, + source="well-known", + identifier=self._wrap_identifier(parsed["base_url"], skill_name), + trust_level="community", + metadata={ + "index_url": parsed["index_url"], + "base_url": parsed["base_url"], + "endpoint": parsed["skill_url"], + "files": files, + }, + ) + + def _query_to_index_url(self, query: str) -> Optional[str]: + query = query.strip() + if not query.startswith(("http://", "https://")): + return None + if query.endswith("/index.json"): + return query + if f"{self.BASE_PATH}/" in query: + base_url = query.split(f"{self.BASE_PATH}/", 1)[0] + self.BASE_PATH + return f"{base_url}/index.json" + return query.rstrip("/") + f"{self.BASE_PATH}/index.json" + + def _parse_identifier(self, identifier: str) -> Optional[dict]: + raw = identifier[len("well-known:"):] if identifier.startswith("well-known:") else identifier + if not raw.startswith(("http://", "https://")): + return None + + parsed_url = urlparse(raw) + clean_url = urlunparse(parsed_url._replace(fragment="")) + fragment = parsed_url.fragment + + if clean_url.endswith("/index.json"): + if not fragment: + return None + base_url = clean_url[:-len("/index.json")] + skill_name = fragment + skill_url = f"{base_url}/{skill_name}" + return { + "index_url": clean_url, + "base_url": base_url, + "skill_name": skill_name, + "skill_url": skill_url, + } + + if clean_url.endswith("/SKILL.md"): + skill_url = clean_url[:-len("/SKILL.md")] + else: + skill_url = clean_url.rstrip("/") + + if f"{self.BASE_PATH}/" not in skill_url: + return None + + base_url, skill_name = skill_url.rsplit("/", 1) + return { + "index_url": f"{base_url}/index.json", + "base_url": base_url, + "skill_name": skill_name, + "skill_url": skill_url, + } + + def _parse_index(self, index_url: str) -> Optional[dict]: + cache_key = f"well_known_index_{hashlib.md5(index_url.encode()).hexdigest()}" + cached = _read_index_cache(cache_key) + if isinstance(cached, dict) and isinstance(cached.get("skills"), list): + return cached + + try: + resp = httpx.get(index_url, timeout=20, follow_redirects=True) + if resp.status_code != 200: + return None + data = resp.json() + except (httpx.HTTPError, json.JSONDecodeError): + return None + + skills = data.get("skills", []) if isinstance(data, dict) else [] + if not isinstance(skills, list): + return None + + parsed = { + "index_url": index_url, + "base_url": index_url[:-len("/index.json")], + "skills": skills, + } + _write_index_cache(cache_key, parsed) + return parsed + + def _index_entry(self, index_url: str, skill_name: str) -> Optional[dict]: + parsed = self._parse_index(index_url) + if not parsed: + return None + for entry in parsed["skills"]: + if isinstance(entry, dict) and entry.get("name") == skill_name: + return entry + return None + + @staticmethod + def _fetch_text(url: str) -> Optional[str]: + try: + resp = httpx.get(url, timeout=20, follow_redirects=True) + if resp.status_code == 200: + return resp.text + except httpx.HTTPError: + return None + return None + + @staticmethod + def _wrap_identifier(base_url: str, skill_name: str) -> str: + return f"well-known:{base_url.rstrip('/')}/{skill_name}" + + +# --------------------------------------------------------------------------- +# skills.sh source adapter +# --------------------------------------------------------------------------- + +class SkillsShSource(SkillSource): + """Discover skills via skills.sh and fetch content from the underlying GitHub repo.""" + + BASE_URL = "https://skills.sh" + SEARCH_URL = f"{BASE_URL}/api/search" + _SKILL_LINK_RE = re.compile(r'href=["\']/(?P(?!agents/|_next/|api/)[^"\'/]+/[^"\'/]+/[^"\'/]+)["\']') + _INSTALL_CMD_RE = re.compile( + r'npx\s+skills\s+add\s+(?Phttps?://github\.com/[^\s<]+|[^\s<]+)' + r'(?:\s+--skill\s+(?P[^\s<]+))?', + re.IGNORECASE, + ) + _PAGE_H1_RE = re.compile(r']*>(?P.*?)</h1>', re.IGNORECASE | re.DOTALL) + _PROSE_H1_RE = re.compile( + r'<div[^>]*class=["\'][^"\']*prose[^"\']*["\'][^>]*>.*?<h1[^>]*>(?P<title>.*?)</h1>', + re.IGNORECASE | re.DOTALL, + ) + _PROSE_P_RE = re.compile( + r'<div[^>]*class=["\'][^"\']*prose[^"\']*["\'][^>]*>.*?<p[^>]*>(?P<body>.*?)</p>', + re.IGNORECASE | re.DOTALL, + ) + _WEEKLY_INSTALLS_RE = re.compile(r'Weekly Installs.*?children\\":\\"(?P<count>[0-9.,Kk]+)\\"', re.DOTALL) + + def __init__(self, auth: GitHubAuth): + self.auth = auth + self.github = GitHubSource(auth=auth) + + def source_id(self) -> str: + return "skills-sh" + + def trust_level_for(self, identifier: str) -> str: + return self.github.trust_level_for(self._normalize_identifier(identifier)) + + def search(self, query: str, limit: int = 10) -> List[SkillMeta]: + if not query.strip(): + return self._featured_skills(limit) + + cache_key = f"skills_sh_search_{hashlib.md5(f'{query}|{limit}'.encode()).hexdigest()}" + cached = _read_index_cache(cache_key) + if cached is not None: + return [SkillMeta(**item) for item in cached][:limit] + + try: + resp = httpx.get( + self.SEARCH_URL, + params={"q": query, "limit": limit}, + timeout=20, + ) + if resp.status_code != 200: + return [] + data = resp.json() + except (httpx.HTTPError, json.JSONDecodeError): + return [] + + items = data.get("skills", []) if isinstance(data, dict) else [] + if not isinstance(items, list): + return [] + + results: List[SkillMeta] = [] + for item in items[:limit]: + meta = self._meta_from_search_item(item) + if meta: + results.append(meta) + + _write_index_cache(cache_key, [_skill_meta_to_dict(item) for item in results]) + return results + + def fetch(self, identifier: str) -> Optional[SkillBundle]: + canonical = self._normalize_identifier(identifier) + detail = self._fetch_detail_page(canonical) + for candidate in self._candidate_identifiers(canonical): + bundle = self.github.fetch(candidate) + if bundle: + bundle.source = "skills.sh" + bundle.identifier = self._wrap_identifier(canonical) + bundle.metadata.update(self._detail_to_metadata(canonical, detail)) + return bundle + + resolved = self._discover_identifier(canonical, detail=detail) + if resolved: + bundle = self.github.fetch(resolved) + if bundle: + bundle.source = "skills.sh" + bundle.identifier = self._wrap_identifier(canonical) + bundle.metadata.update(self._detail_to_metadata(canonical, detail)) + return bundle + return None + + def inspect(self, identifier: str) -> Optional[SkillMeta]: + canonical = self._normalize_identifier(identifier) + detail = self._fetch_detail_page(canonical) + meta = self._resolve_github_meta(canonical, detail=detail) + if meta: + return self._finalize_inspect_meta(meta, canonical, detail) + return None + + def _featured_skills(self, limit: int) -> List[SkillMeta]: + cache_key = "skills_sh_featured" + cached = _read_index_cache(cache_key) + if cached is not None: + return [SkillMeta(**item) for item in cached][:limit] + + try: + resp = httpx.get(self.BASE_URL, timeout=20) + if resp.status_code != 200: + return [] + except httpx.HTTPError: + return [] + + seen: set[str] = set() + results: List[SkillMeta] = [] + for match in self._SKILL_LINK_RE.finditer(resp.text): + canonical = match.group("id") + if canonical in seen: + continue + seen.add(canonical) + parts = canonical.split("/", 2) + if len(parts) < 3: + continue + repo = f"{parts[0]}/{parts[1]}" + skill_path = parts[2] + results.append(SkillMeta( + name=skill_path.split("/")[-1], + description=f"Featured on skills.sh from {repo}", + source="skills.sh", + identifier=self._wrap_identifier(canonical), + trust_level=self.github.trust_level_for(canonical), + repo=repo, + path=skill_path, + )) + if len(results) >= limit: + break + + _write_index_cache(cache_key, [_skill_meta_to_dict(item) for item in results]) + return results + + def _meta_from_search_item(self, item: dict) -> Optional[SkillMeta]: + if not isinstance(item, dict): + return None + + canonical = item.get("id") + repo = item.get("source") + skill_path = item.get("skillId") + if not isinstance(canonical, str) or canonical.count("/") < 2: + if not (isinstance(repo, str) and isinstance(skill_path, str)): + return None + canonical = f"{repo}/{skill_path}" + + parts = canonical.split("/", 2) + if len(parts) < 3: + return None + + repo = f"{parts[0]}/{parts[1]}" + skill_path = parts[2] + installs = item.get("installs") + installs_label = f" · {int(installs):,} installs" if isinstance(installs, int) else "" + + return SkillMeta( + name=str(item.get("name") or skill_path.split("/")[-1]), + description=f"Indexed by skills.sh from {repo}{installs_label}", + source="skills.sh", + identifier=self._wrap_identifier(canonical), + trust_level=self.github.trust_level_for(canonical), + repo=repo, + path=skill_path, + extra={ + "installs": installs, + "detail_url": f"{self.BASE_URL}/{canonical}", + "repo_url": f"https://github.com/{repo}", + }, + ) + + def _fetch_detail_page(self, identifier: str) -> Optional[dict]: + cache_key = f"skills_sh_detail_{hashlib.md5(identifier.encode()).hexdigest()}" + cached = _read_index_cache(cache_key) + if isinstance(cached, dict): + return cached + + try: + resp = httpx.get(f"{self.BASE_URL}/{identifier}", timeout=20) + if resp.status_code != 200: + return None + except httpx.HTTPError: + return None + + detail = self._parse_detail_page(identifier, resp.text) + if detail: + _write_index_cache(cache_key, detail) + return detail + + def _parse_detail_page(self, identifier: str, html: str) -> Optional[dict]: + parts = identifier.split("/", 2) + if len(parts) < 3: + return None + + default_repo = f"{parts[0]}/{parts[1]}" + skill_token = parts[2] + repo = default_repo + install_skill = skill_token + + install_command = None + install_match = self._INSTALL_CMD_RE.search(html) + if install_match: + install_command = install_match.group(0).strip() + repo_value = (install_match.group("repo") or "").strip() + install_skill = (install_match.group("skill") or install_skill).strip() + repo = self._extract_repo_slug(repo_value) or repo + + page_title = self._extract_first_match(self._PAGE_H1_RE, html) + body_title = self._extract_first_match(self._PROSE_H1_RE, html) + body_summary = self._extract_first_match(self._PROSE_P_RE, html) + weekly_installs = self._extract_weekly_installs(html) + security_audits = self._extract_security_audits(html, identifier) + + return { + "repo": repo, + "install_skill": install_skill, + "page_title": page_title, + "body_title": body_title, + "body_summary": body_summary, + "weekly_installs": weekly_installs, + "install_command": install_command, + "repo_url": f"https://github.com/{repo}", + "detail_url": f"{self.BASE_URL}/{identifier}", + "security_audits": security_audits, + } + + def _discover_identifier(self, identifier: str, detail: Optional[dict] = None) -> Optional[str]: + parts = identifier.split("/", 2) + if len(parts) < 3: + return None + + default_repo = f"{parts[0]}/{parts[1]}" + repo = detail.get("repo", default_repo) if isinstance(detail, dict) else default_repo + skill_token=parts[2].split("/")[-1] + tokens=[skill_token] + if isinstance(detail, dict): + tokens.extend([ + detail.get("install_skill", ""), + detail.get("page_title", ""), + detail.get("body_title", ""), + ]) + + # Standard skill paths + base_paths = ["skills/", ".agents/skills/", ".claude/skills/"] + + for base_path in base_paths: + try: + skills = self.github._list_skills_in_repo(repo, base_path) + except Exception: + continue + for meta in skills: + if self._matches_skill_tokens(meta, tokens): + return meta.identifier + + # Prefer a single recursive tree lookup before brute-forcing every + # top-level directory. This avoids large request bursts on categorized + # repos like borghei/claude-skills. + tree_result = self.github._find_skill_in_repo_tree(repo, skill_token) + if tree_result: + return tree_result + + # Fallback: scan repo root for directories that might contain skills + try: + root_url = f"https://api.github.com/repos/{repo}/contents/" + resp = httpx.get(root_url, headers=self.github.auth.get_headers(), + timeout=15, follow_redirects=True) + if resp.status_code == 200: + entries = resp.json() + if isinstance(entries, list): + for entry in entries: + if entry.get("type") != "dir": + continue + dir_name = entry["name"] + if dir_name.startswith((".", "_")): + continue + if dir_name in ("skills", ".agents", ".claude"): + continue # already tried + # Try direct: repo/dir/skill_token + direct_id = f"{repo}/{dir_name}/{skill_token}" + meta = self.github.inspect(direct_id) + if meta: + return meta.identifier + # Try listing skills in this directory + try: + skills = self.github._list_skills_in_repo(repo, dir_name + "/") + except Exception: + continue + for meta in skills: + if self._matches_skill_tokens(meta, tokens): + return meta.identifier + except Exception: + pass + + return None + + def _resolve_github_meta(self, identifier: str, detail: Optional[dict] = None) -> Optional[SkillMeta]: + for candidate in self._candidate_identifiers(identifier): + meta = self.github.inspect(candidate) + if meta: + return meta + + resolved = self._discover_identifier(identifier, detail=detail) + if resolved: + return self.github.inspect(resolved) + return None + + def _finalize_inspect_meta(self, meta: SkillMeta, canonical: str, detail: Optional[dict]) -> SkillMeta: + meta.source = "skills.sh" + meta.identifier = self._wrap_identifier(canonical) + meta.trust_level = self.trust_level_for(canonical) + merged_extra = dict(meta.extra) + merged_extra.update(self._detail_to_metadata(canonical, detail)) + meta.extra = merged_extra + + if isinstance(detail, dict): + body_summary = detail.get("body_summary") + weekly_installs = detail.get("weekly_installs") + if body_summary: + meta.description = body_summary + elif meta.description and weekly_installs: + meta.description = f"{meta.description} · {weekly_installs} weekly installs on skills.sh" + return meta + + @classmethod + def _matches_skill_tokens(cls, meta: SkillMeta, skill_tokens: List[str]) -> bool: + candidates = set() + candidates.update(cls._token_variants(meta.name)) + candidates.update(cls._token_variants(meta.path)) + candidates.update(cls._token_variants(meta.identifier.split("/", 2)[-1] if meta.identifier else None)) + + for token in skill_tokens: + variants = cls._token_variants(token) + if variants & candidates: + return True + return False + + @staticmethod + def _token_variants(value: Optional[str]) -> set[str]: + if not value: + return set() + + plain = SkillsShSource._strip_html(str(value)).strip().strip("/").lower() + if not plain: + return set() + + base = plain.split("/")[-1] + sanitized = re.sub(r'[^a-z0-9/_-]+', '-', plain).strip('-') + sanitized_base = sanitized.split("/")[-1] if sanitized else "" + slash_tail = plain.split("/")[-1] + slash_tail_clean = slash_tail.lstrip('@') + slash_tail_clean = slash_tail_clean.split('/')[-1] + + variants = { + plain, + plain.replace("_", "-"), + plain.replace("/", "-"), + base, + base.replace("_", "-"), + base.replace("/", "-"), + sanitized, + sanitized.replace("/", "-") if sanitized else "", + sanitized_base, + slash_tail_clean, + slash_tail_clean.replace("_", "-"), + } + return {v for v in variants if v} + + @staticmethod + def _extract_repo_slug(repo_value: str) -> Optional[str]: + repo_value = repo_value.strip() + if repo_value.startswith("https://github.com/"): + repo_value = repo_value[len("https://github.com/"):] + repo_value = repo_value.strip("/") + parts = repo_value.split("/") + if len(parts) >= 2: + return f"{parts[0]}/{parts[1]}" + return None + + @staticmethod + def _extract_first_match(pattern: re.Pattern, text: str) -> Optional[str]: + match = pattern.search(text) + if not match: + return None + value = next((group for group in match.groups() if group), None) + if value is None: + return None + return SkillsShSource._strip_html(value).strip() or None + + def _detail_to_metadata(self, canonical: str, detail: Optional[dict]) -> Dict[str, Any]: + parts = canonical.split("/", 2) + repo = f"{parts[0]}/{parts[1]}" if len(parts) >= 2 else "" + metadata = { + "detail_url": f"{self.BASE_URL}/{canonical}", + } + if repo: + metadata["repo_url"] = f"https://github.com/{repo}" + if isinstance(detail, dict): + for key in ("weekly_installs", "install_command", "repo_url", "detail_url", "security_audits"): + value = detail.get(key) + if value: + metadata[key] = value + return metadata + + @staticmethod + def _extract_weekly_installs(html: str) -> Optional[str]: + match = SkillsShSource._WEEKLY_INSTALLS_RE.search(html) + if not match: + return None + return match.group("count") + + @staticmethod + def _extract_security_audits(html: str, identifier: str) -> Dict[str, str]: + audits: Dict[str, str] = {} + for audit in ("agent-trust-hub", "socket", "snyk"): + idx = html.find(f"/security/{audit}") + if idx == -1: + continue + window = html[idx:idx + 500] + match = re.search(r'(Pass|Warn|Fail)', window, re.IGNORECASE) + if match: + audits[audit] = match.group(1).title() + return audits + + @staticmethod + def _strip_html(value: str) -> str: + return re.sub(r'<[^>]+>', '', value) + + @staticmethod + def _normalize_identifier(identifier: str) -> str: + prefix_aliases = ( + "skills-sh/", + "skills.sh/", + "skils-sh/", + "skils.sh/", + ) + for prefix in prefix_aliases: + if identifier.startswith(prefix): + return identifier[len(prefix):] + return identifier + + @staticmethod + def _candidate_identifiers(identifier: str) -> List[str]: + parts = identifier.split("/", 2) + if len(parts) < 3: + return [identifier] + + repo = f"{parts[0]}/{parts[1]}" + skill_path = parts[2].lstrip("/") + candidates = [ + f"{repo}/{skill_path}", + f"{repo}/skills/{skill_path}", + f"{repo}/.agents/skills/{skill_path}", + f"{repo}/.claude/skills/{skill_path}", + ] + + seen = set() + deduped: List[str] = [] + for candidate in candidates: + if candidate not in seen: + seen.add(candidate) + deduped.append(candidate) + return deduped + + @staticmethod + def _wrap_identifier(identifier: str) -> str: + return f"skills-sh/{identifier}" + + +# --------------------------------------------------------------------------- +# ClawHub source adapter +# --------------------------------------------------------------------------- + +class ClawHubSource(SkillSource): + """ + Fetch skills from ClawHub (clawhub.ai) via their HTTP API. + All skills are treated as community trust — ClawHavoc incident showed + their vetting is insufficient (341 malicious skills found Feb 2026). + """ + + BASE_URL = "https://clawhub.ai/api/v1" + + def source_id(self) -> str: + return "clawhub" + + def trust_level_for(self, identifier: str) -> str: + return "community" + + @staticmethod + def _normalize_tags(tags: Any) -> List[str]: + if isinstance(tags, list): + return [str(t) for t in tags] + if isinstance(tags, dict): + return [str(k) for k in tags if str(k) != "latest"] + return [] + + @staticmethod + def _coerce_skill_payload(data: Any) -> Optional[Dict[str, Any]]: + if not isinstance(data, dict): + return None + nested = data.get("skill") + if isinstance(nested, dict): + merged = dict(nested) + latest_version = data.get("latestVersion") + if latest_version is not None and "latestVersion" not in merged: + merged["latestVersion"] = latest_version + return merged + return data + + @staticmethod + def _query_terms(query: str) -> List[str]: + return [term for term in re.split(r"[^a-z0-9]+", query.lower()) if term] + + @classmethod + def _search_score(cls, query: str, meta: SkillMeta) -> int: + query_norm = query.strip().lower() + if not query_norm: + return 1 + + identifier = (meta.identifier or "").lower() + name = (meta.name or "").lower() + description = (meta.description or "").lower() + normalized_identifier = " ".join(cls._query_terms(identifier)) + normalized_name = " ".join(cls._query_terms(name)) + query_terms = cls._query_terms(query_norm) + identifier_terms = cls._query_terms(identifier) + name_terms = cls._query_terms(name) + score = 0 + + if query_norm == identifier: + score += 140 + if query_norm == name: + score += 130 + if normalized_identifier == query_norm: + score += 125 + if normalized_name == query_norm: + score += 120 + if normalized_identifier.startswith(query_norm): + score += 95 + if normalized_name.startswith(query_norm): + score += 90 + if query_terms and identifier_terms[: len(query_terms)] == query_terms: + score += 70 + if query_terms and name_terms[: len(query_terms)] == query_terms: + score += 65 + if query_norm in identifier: + score += 40 + if query_norm in name: + score += 35 + if query_norm in description: + score += 10 + + for term in query_terms: + if term in identifier_terms: + score += 15 + if term in name_terms: + score += 12 + if term in description: + score += 3 + + return score + + @staticmethod + def _dedupe_results(results: List[SkillMeta]) -> List[SkillMeta]: + seen: set[str] = set() + deduped: List[SkillMeta] = [] + for result in results: + key = (result.identifier or result.name).lower() + if key in seen: + continue + seen.add(key) + deduped.append(result) + return deduped + + def _exact_slug_meta(self, query: str) -> Optional[SkillMeta]: + slug = query.strip().split("/")[-1] + query_terms = self._query_terms(query) + candidates: List[str] = [] + + if slug and re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", slug): + candidates.append(slug) + + if query_terms: + base_slug = "-".join(query_terms) + if len(query_terms) >= 2: + candidates.extend([ + f"{base_slug}-agent", + f"{base_slug}-skill", + f"{base_slug}-tool", + f"{base_slug}-assistant", + f"{base_slug}-playbook", + base_slug, + ]) + else: + candidates.append(base_slug) + + seen: set[str] = set() + for candidate in candidates: + if candidate in seen: + continue + seen.add(candidate) + meta = self.inspect(candidate) + if meta: + return meta + + return None + + def _finalize_search_results(self, query: str, results: List[SkillMeta], limit: int) -> List[SkillMeta]: + query_norm = query.strip() + if not query_norm: + return self._dedupe_results(results)[:limit] + + filtered = [meta for meta in results if self._search_score(query_norm, meta) > 0] + filtered.sort( + key=lambda meta: ( + -self._search_score(query_norm, meta), + meta.name.lower(), + meta.identifier.lower(), + ) + ) + filtered = self._dedupe_results(filtered) + + exact = self._exact_slug_meta(query_norm) + if exact: + filtered = [meta for meta in filtered if self._search_score(query_norm, meta) >= 20] + filtered = self._dedupe_results([exact] + filtered) + + if filtered: + return filtered[:limit] + + if re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._/-]*", query_norm): + return [] + + return self._dedupe_results(results)[:limit] + + def search(self, query: str, limit: int = 10) -> List[SkillMeta]: + query = query.strip() + + if query: + query_terms = self._query_terms(query) + if len(query_terms) >= 2: + direct = self._exact_slug_meta(query) + if direct: + return [direct] + + results = self._search_catalog(query, limit=limit) + if results: + return results + + # Empty query or catalog fallback failure: use the lightweight listing API. + cache_key = f"clawhub_search_listing_v1_{hashlib.md5(query.encode()).hexdigest()}_{limit}" + cached = _read_index_cache(cache_key) + if cached is not None: + return self._finalize_search_results( + query, + [SkillMeta(**s) for s in cached], + limit, + ) + + try: + resp = httpx.get( + f"{self.BASE_URL}/skills", + params={"search": query, "limit": limit}, + timeout=15, + ) + if resp.status_code != 200: + return [] + data = resp.json() + except (httpx.HTTPError, json.JSONDecodeError): + return [] + + skills_data = data.get("items", data) if isinstance(data, dict) else data + if not isinstance(skills_data, list): + return [] + + results = [] + for item in skills_data[:limit]: + slug = item.get("slug") + if not slug: + continue + display_name = item.get("displayName") or item.get("name") or slug + summary = item.get("summary") or item.get("description") or "" + tags = self._normalize_tags(item.get("tags", [])) + results.append(SkillMeta( + name=display_name, + description=summary, + source="clawhub", + identifier=slug, + trust_level="community", + tags=tags, + )) + + final_results = self._finalize_search_results(query, results, limit) + _write_index_cache(cache_key, [_skill_meta_to_dict(s) for s in final_results]) + return final_results + + def fetch(self, identifier: str) -> Optional[SkillBundle]: + slug = identifier.split("/")[-1] + + skill_data = self._get_json(f"{self.BASE_URL}/skills/{slug}") + if not isinstance(skill_data, dict): + return None + + latest_version = self._resolve_latest_version(slug, skill_data) + if not latest_version: + logger.warning("ClawHub fetch failed for %s: could not resolve latest version", slug) + return None + + # Primary method: download the skill as a ZIP bundle from /download + files = self._download_zip(slug, latest_version) + + # Fallback: try the version metadata endpoint for inline/raw content + if "SKILL.md" not in files: + version_data = self._get_json(f"{self.BASE_URL}/skills/{slug}/versions/{latest_version}") + if isinstance(version_data, dict): + # Files may be nested under version_data["version"]["files"] + files = self._extract_files(version_data) or files + if "SKILL.md" not in files: + nested = version_data.get("version", {}) + if isinstance(nested, dict): + files = self._extract_files(nested) or files + + if "SKILL.md" not in files: + logger.warning( + "ClawHub fetch for %s resolved version %s but could not retrieve file content", + slug, + latest_version, + ) + return None + + return SkillBundle( + name=slug, + files=files, + source="clawhub", + identifier=slug, + trust_level="community", + ) + + def inspect(self, identifier: str) -> Optional[SkillMeta]: + slug = identifier.split("/")[-1] + data = self._coerce_skill_payload(self._get_json(f"{self.BASE_URL}/skills/{slug}")) + if not isinstance(data, dict): + return None + + tags = self._normalize_tags(data.get("tags", [])) + + return SkillMeta( + name=data.get("displayName") or data.get("name") or data.get("slug") or slug, + description=data.get("summary") or data.get("description") or "", + source="clawhub", + identifier=data.get("slug") or slug, + trust_level="community", + tags=tags, + ) + + def _search_catalog(self, query: str, limit: int = 10) -> List[SkillMeta]: + cache_key = f"clawhub_search_catalog_v1_{hashlib.md5(f'{query}|{limit}'.encode()).hexdigest()}" + cached = _read_index_cache(cache_key) + if cached is not None: + return [SkillMeta(**s) for s in cached][:limit] + + catalog = self._load_catalog_index() + if not catalog: + return [] + + results = self._finalize_search_results(query, catalog, limit) + _write_index_cache(cache_key, [_skill_meta_to_dict(s) for s in results]) + return results + + def _load_catalog_index(self) -> List[SkillMeta]: + cache_key = "clawhub_catalog_v1" + cached = _read_index_cache(cache_key) + if cached is not None: + return [SkillMeta(**s) for s in cached] + + cursor: Optional[str] = None + results: List[SkillMeta] = [] + seen: set[str] = set() + max_pages = 50 + + for _ in range(max_pages): + params: Dict[str, Any] = {"limit": 200} + if cursor: + params["cursor"] = cursor + + try: + resp = httpx.get(f"{self.BASE_URL}/skills", params=params, timeout=30) + if resp.status_code != 200: + break + data = resp.json() + except (httpx.HTTPError, json.JSONDecodeError): + break + + items = data.get("items", []) if isinstance(data, dict) else [] + if not isinstance(items, list) or not items: + break + + for item in items: + slug = item.get("slug") + if not isinstance(slug, str) or not slug or slug in seen: + continue + seen.add(slug) + display_name = item.get("displayName") or item.get("name") or slug + summary = item.get("summary") or item.get("description") or "" + tags = self._normalize_tags(item.get("tags", [])) + results.append(SkillMeta( + name=display_name, + description=summary, + source="clawhub", + identifier=slug, + trust_level="community", + tags=tags, + )) + + cursor = data.get("nextCursor") if isinstance(data, dict) else None + if not isinstance(cursor, str) or not cursor: + break + + _write_index_cache(cache_key, [_skill_meta_to_dict(s) for s in results]) + return results + + def _get_json(self, url: str, timeout: int = 20) -> Optional[Any]: + try: + resp = httpx.get(url, timeout=timeout) + if resp.status_code != 200: + return None + return resp.json() + except (httpx.HTTPError, json.JSONDecodeError): + return None + + def _resolve_latest_version(self, slug: str, skill_data: Dict[str, Any]) -> Optional[str]: + latest = skill_data.get("latestVersion") + if isinstance(latest, dict): + version = latest.get("version") + if isinstance(version, str) and version: + return version + + tags = skill_data.get("tags") + if isinstance(tags, dict): + latest_tag = tags.get("latest") + if isinstance(latest_tag, str) and latest_tag: + return latest_tag + + versions_data = self._get_json(f"{self.BASE_URL}/skills/{slug}/versions") + if isinstance(versions_data, list) and versions_data: + first = versions_data[0] + if isinstance(first, dict): + version = first.get("version") + if isinstance(version, str) and version: + return version + return None + + def _extract_files(self, version_data: Dict[str, Any]) -> Dict[str, str]: + files: Dict[str, str] = {} + file_list = version_data.get("files") + + if isinstance(file_list, dict): + return {k: v for k, v in file_list.items() if isinstance(v, str)} + + if not isinstance(file_list, list): + return files + + for file_meta in file_list: + if not isinstance(file_meta, dict): + continue + + fname = file_meta.get("path") or file_meta.get("name") + if not fname or not isinstance(fname, str): + continue + + inline_content = file_meta.get("content") + if isinstance(inline_content, str): + files[fname] = inline_content + continue + + raw_url = file_meta.get("rawUrl") or file_meta.get("downloadUrl") or file_meta.get("url") + if isinstance(raw_url, str) and raw_url.startswith("http"): + content = self._fetch_text(raw_url) + if content is not None: + files[fname] = content + + return files + + def _download_zip(self, slug: str, version: str) -> Dict[str, str]: + """Download skill as a ZIP bundle from the /download endpoint and extract text files.""" + import io + import zipfile + + files: Dict[str, str] = {} + max_retries = 3 + for attempt in range(max_retries): + try: + resp = httpx.get( + f"{self.BASE_URL}/download", + params={"slug": slug, "version": version}, + timeout=30, + follow_redirects=True, + ) + if resp.status_code == 429: + try: + retry_after = int(resp.headers.get("retry-after", "5")) + except (ValueError, TypeError): + retry_after = 5 + retry_after = min(retry_after, 15) # Cap wait time + logger.debug( + "ClawHub download rate-limited for %s, retrying in %ds (attempt %d/%d)", + slug, retry_after, attempt + 1, max_retries, + ) + time.sleep(retry_after) + continue + if resp.status_code != 200: + logger.debug("ClawHub ZIP download for %s v%s returned %s", slug, version, resp.status_code) + return files + + with zipfile.ZipFile(io.BytesIO(resp.content)) as zf: + for info in zf.infolist(): + if info.is_dir(): + continue + try: + name = _validate_bundle_rel_path(info.filename) + except ValueError: + logger.debug("Skipping unsafe ZIP member path: %s", info.filename) + continue + # Only extract text-sized files (skip large binaries) + if info.file_size > 500_000: + logger.debug("Skipping large file in ZIP: %s (%d bytes)", name, info.file_size) + continue + try: + raw = zf.read(info.filename) + files[name] = raw.decode("utf-8") + except (UnicodeDecodeError, KeyError): + logger.debug("Skipping non-text file in ZIP: %s", name) + continue + + return files + + except zipfile.BadZipFile: + logger.warning("ClawHub returned invalid ZIP for %s v%s", slug, version) + return files + except httpx.HTTPError as exc: + logger.debug("ClawHub ZIP download failed for %s v%s: %s", slug, version, exc) + return files + + logger.debug("ClawHub ZIP download exhausted retries for %s v%s", slug, version) + return files + + def _fetch_text(self, url: str) -> Optional[str]: + try: + resp = httpx.get(url, timeout=20) + if resp.status_code == 200: + return resp.text + except httpx.HTTPError: + return None + return None + + +# --------------------------------------------------------------------------- +# Claude Code marketplace source adapter +# --------------------------------------------------------------------------- + +class ClaudeMarketplaceSource(SkillSource): + """ + Discover skills from Claude Code marketplace repos. + Marketplace repos contain .claude-plugin/marketplace.json with plugin listings. + """ + + KNOWN_MARKETPLACES = [ + "anthropics/skills", + "aiskillstore/marketplace", + ] + + def __init__(self, auth: GitHubAuth): + self.auth = auth + + def source_id(self) -> str: + return "claude-marketplace" + + def trust_level_for(self, identifier: str) -> str: + parts = identifier.split("/", 2) + if len(parts) >= 2: + repo = f"{parts[0]}/{parts[1]}" + if repo in TRUSTED_REPOS: + return "trusted" + return "community" + + def search(self, query: str, limit: int = 10) -> List[SkillMeta]: + results: List[SkillMeta] = [] + query_lower = query.lower() + + for marketplace_repo in self.KNOWN_MARKETPLACES: + plugins = self._fetch_marketplace_index(marketplace_repo) + for plugin in plugins: + searchable = f"{plugin.get('name', '')} {plugin.get('description', '')}".lower() + if query_lower in searchable: + source_path = plugin.get("source", "") + if source_path.startswith("./"): + identifier = f"{marketplace_repo}/{source_path[2:]}" + elif "/" in source_path: + identifier = source_path + else: + identifier = f"{marketplace_repo}/{source_path}" + + results.append(SkillMeta( + name=plugin.get("name", ""), + description=plugin.get("description", ""), + source="claude-marketplace", + identifier=identifier, + trust_level=self.trust_level_for(identifier), + repo=marketplace_repo, + )) + + return results[:limit] + + def fetch(self, identifier: str) -> Optional[SkillBundle]: + # Delegate to GitHub Contents API since marketplace skills live in GitHub repos + gh = GitHubSource(auth=self.auth) + bundle = gh.fetch(identifier) + if bundle: + bundle.source = "claude-marketplace" + return bundle + + def inspect(self, identifier: str) -> Optional[SkillMeta]: + gh = GitHubSource(auth=self.auth) + meta = gh.inspect(identifier) + if meta: + meta.source = "claude-marketplace" + meta.trust_level = self.trust_level_for(identifier) + return meta + + def _fetch_marketplace_index(self, repo: str) -> List[dict]: + """Fetch and parse .claude-plugin/marketplace.json from a repo.""" + cache_key = f"claude_marketplace_{repo.replace('/', '_')}" + cached = _read_index_cache(cache_key) + if cached is not None: + return cached + + url = f"https://api.github.com/repos/{repo}/contents/.claude-plugin/marketplace.json" + try: + resp = httpx.get( + url, + headers={**self.auth.get_headers(), "Accept": "application/vnd.github.v3.raw"}, + timeout=15, + ) + if resp.status_code != 200: + return [] + data = json.loads(resp.text) + except (httpx.HTTPError, json.JSONDecodeError): + return [] + + plugins = data.get("plugins", []) + _write_index_cache(cache_key, plugins) + return plugins + + +# --------------------------------------------------------------------------- +# LobeHub source adapter +# --------------------------------------------------------------------------- + +class LobeHubSource(SkillSource): + """ + Fetch skills from LobeHub's agent marketplace (14,500+ agents). + LobeHub agents are system prompt templates — we convert them to SKILL.md on fetch. + Data lives in GitHub: lobehub/lobe-chat-agents. + """ + + INDEX_URL = "https://chat-agents.lobehub.com/index.json" + + def source_id(self) -> str: + return "lobehub" + + def trust_level_for(self, identifier: str) -> str: + return "community" + + def search(self, query: str, limit: int = 10) -> List[SkillMeta]: + index = self._fetch_index() + if not index: + return [] + + query_lower = query.lower() + results: List[SkillMeta] = [] + + agents = index.get("agents", index) if isinstance(index, dict) else index + if not isinstance(agents, list): + return [] + + for agent in agents: + meta = agent.get("meta", agent) + title = meta.get("title", agent.get("identifier", "")) + desc = meta.get("description", "") + tags = meta.get("tags", []) + + searchable = f"{title} {desc} {' '.join(tags) if isinstance(tags, list) else ''}".lower() + if query_lower in searchable: + identifier = agent.get("identifier", title.lower().replace(" ", "-")) + results.append(SkillMeta( + name=identifier, + description=desc[:200], + source="lobehub", + identifier=f"lobehub/{identifier}", + trust_level="community", + tags=tags if isinstance(tags, list) else [], + )) + + if len(results) >= limit: + break + + return results + + def fetch(self, identifier: str) -> Optional[SkillBundle]: + # Strip "lobehub/" prefix if present + agent_id = identifier.split("/", 1)[-1] if identifier.startswith("lobehub/") else identifier + + agent_data = self._fetch_agent(agent_id) + if not agent_data: + return None + + skill_md = self._convert_to_skill_md(agent_data) + return SkillBundle( + name=agent_id, + files={"SKILL.md": skill_md}, + source="lobehub", + identifier=f"lobehub/{agent_id}", + trust_level="community", + ) + + def inspect(self, identifier: str) -> Optional[SkillMeta]: + agent_id = identifier.split("/", 1)[-1] if identifier.startswith("lobehub/") else identifier + index = self._fetch_index() + if not index: + return None + + agents = index.get("agents", index) if isinstance(index, dict) else index + if not isinstance(agents, list): + return None + + for agent in agents: + if agent.get("identifier") == agent_id: + meta = agent.get("meta", agent) + return SkillMeta( + name=agent_id, + description=meta.get("description", ""), + source="lobehub", + identifier=f"lobehub/{agent_id}", + trust_level="community", + tags=meta.get("tags", []) if isinstance(meta.get("tags"), list) else [], + ) + return None + + def _fetch_index(self) -> Optional[Any]: + """Fetch the LobeHub agent index (cached for 1 hour).""" + cache_key = "lobehub_index" + cached = _read_index_cache(cache_key) + if cached is not None: + return cached + + try: + resp = httpx.get(self.INDEX_URL, timeout=30) + if resp.status_code != 200: + return None + data = resp.json() + except (httpx.HTTPError, json.JSONDecodeError): + return None + + _write_index_cache(cache_key, data) + return data + + def _fetch_agent(self, agent_id: str) -> Optional[dict]: + """Fetch a single agent's JSON file.""" + url = f"https://chat-agents.lobehub.com/{agent_id}.json" + try: + resp = httpx.get(url, timeout=15) + if resp.status_code == 200: + return resp.json() + except (httpx.HTTPError, json.JSONDecodeError) as e: + logger.debug("LobeHub agent fetch failed: %s", e) + return None + + @staticmethod + def _convert_to_skill_md(agent_data: dict) -> str: + """Convert a LobeHub agent JSON into SKILL.md format.""" + meta = agent_data.get("meta", agent_data) + identifier = agent_data.get("identifier", "lobehub-agent") + title = meta.get("title", identifier) + description = meta.get("description", "") + tags = meta.get("tags", []) + system_role = agent_data.get("config", {}).get("systemRole", "") + + tag_list = tags if isinstance(tags, list) else [] + fm_lines = [ + "---", + f"name: {identifier}", + f"description: {description[:500]}", + "metadata:", + " hermes:", + f" tags: [{', '.join(str(t) for t in tag_list)}]", + " lobehub:", + " source: lobehub", + "---", + ] + + body_lines = [ + f"# {title}", + "", + description, + "", + "## Instructions", + "", + system_role if system_role else "(No system role defined)", + ] + + return "\n".join(fm_lines) + "\n\n" + "\n".join(body_lines) + "\n" + + +# --------------------------------------------------------------------------- +# Official optional skills source adapter +# --------------------------------------------------------------------------- + +class OptionalSkillSource(SkillSource): + """ + Fetch skills from the optional-skills/ directory shipped with the repo. + + These skills are official (maintained by Nous Research) but not activated + by default — they don't appear in the system prompt and aren't copied to + ~/.hermes/skills/ during setup. They are discoverable via the Skills Hub + (search / install / inspect) and labelled "official" with "builtin" trust. + """ + + def __init__(self): + from hermes_constants import get_optional_skills_dir + + self._optional_dir = get_optional_skills_dir( + Path(__file__).parent.parent / "optional-skills" + ) + + def source_id(self) -> str: + return "official" + + def trust_level_for(self, identifier: str) -> str: + return "builtin" + + # -- search ----------------------------------------------------------- + + def search(self, query: str, limit: int = 10) -> List[SkillMeta]: + results: List[SkillMeta] = [] + query_lower = query.lower() + + for meta in self._scan_all(): + searchable = f"{meta.name} {meta.description} {' '.join(meta.tags)}".lower() + if query_lower in searchable: + results.append(meta) + if len(results) >= limit: + break + + return results + + # -- fetch ------------------------------------------------------------ + + def fetch(self, identifier: str) -> Optional[SkillBundle]: + # identifier format: "official/category/skill" or "official/skill" + rel = identifier.split("/", 1)[-1] if identifier.startswith("official/") else identifier + skill_dir = self._optional_dir / rel + + # Guard against path traversal (e.g. "official/../../etc") + try: + resolved = skill_dir.resolve() + if not str(resolved).startswith(str(self._optional_dir.resolve())): + return None + except (OSError, ValueError): + return None + + if not resolved.is_dir(): + # Try searching by skill name only (last segment) + skill_name = rel.rsplit("/", 1)[-1] + skill_dir = self._find_skill_dir(skill_name) + if not skill_dir: + return None + else: + skill_dir = resolved + + files: Dict[str, Union[str, bytes]] = {} + for f in skill_dir.rglob("*"): + if ( + f.is_file() + and not f.name.startswith(".") + and "__pycache__" not in f.parts + and f.suffix != ".pyc" + ): + rel_path = str(f.relative_to(skill_dir)) + try: + files[rel_path] = f.read_bytes() + except OSError: + continue + + if not files: + return None + + # Determine category from directory structure + name = skill_dir.name + + return SkillBundle( + name=name, + files=files, + source="official", + identifier=f"official/{skill_dir.relative_to(self._optional_dir)}", + trust_level="builtin", + ) + + # -- inspect ---------------------------------------------------------- + + def inspect(self, identifier: str) -> Optional[SkillMeta]: + rel = identifier.split("/", 1)[-1] if identifier.startswith("official/") else identifier + skill_name = rel.rsplit("/", 1)[-1] + + for meta in self._scan_all(): + if meta.name == skill_name: + return meta + return None + + # -- internal helpers ------------------------------------------------- + + def _find_skill_dir(self, name: str) -> Optional[Path]: + """Find a skill directory by name anywhere in optional-skills/.""" + if not self._optional_dir.is_dir(): + return None + for skill_md in self._optional_dir.rglob("SKILL.md"): + if skill_md.parent.name == name: + return skill_md.parent + return None + + def _scan_all(self) -> List[SkillMeta]: + """Enumerate all optional skills with metadata.""" + if not self._optional_dir.is_dir(): + return [] + + results: List[SkillMeta] = [] + for skill_md in sorted(self._optional_dir.rglob("SKILL.md")): + parent = skill_md.parent + rel_parts = parent.relative_to(self._optional_dir).parts + if any(part.startswith(".") for part in rel_parts): + continue + + try: + content = skill_md.read_text(encoding="utf-8") + except (OSError, UnicodeDecodeError): + continue + + fm = self._parse_frontmatter(content) + name = fm.get("name", parent.name) + desc = fm.get("description", "") + tags = [] + meta_block = fm.get("metadata", {}) + if isinstance(meta_block, dict): + hermes_meta = meta_block.get("hermes", {}) + if isinstance(hermes_meta, dict): + tags = hermes_meta.get("tags", []) + + rel_path = str(parent.relative_to(self._optional_dir)) + + results.append(SkillMeta( + name=name, + description=desc[:200], + source="official", + identifier=f"official/{rel_path}", + trust_level="builtin", + path=rel_path, + tags=tags if isinstance(tags, list) else [], + )) + + return results + + @staticmethod + def _parse_frontmatter(content: str) -> dict: + """Parse YAML frontmatter from SKILL.md content.""" + if not content.startswith("---"): + return {} + match = re.search(r'\n---\s*\n', content[3:]) + if not match: + return {} + yaml_text = content[3:match.start() + 3] + try: + parsed = yaml.safe_load(yaml_text) + return parsed if isinstance(parsed, dict) else {} + except yaml.YAMLError: + return {} + + +# --------------------------------------------------------------------------- +# Shared cache helpers (used by multiple adapters) +# --------------------------------------------------------------------------- + +def _read_index_cache(key: str) -> Optional[Any]: + """Read cached data if not expired.""" + cache_file = INDEX_CACHE_DIR / f"{key}.json" + if not cache_file.exists(): + return None + try: + stat = cache_file.stat() + if time.time() - stat.st_mtime > INDEX_CACHE_TTL: + return None + return json.loads(cache_file.read_text()) + except (OSError, json.JSONDecodeError): + return None + + +def _write_index_cache(key: str, data: Any) -> None: + """Write data to cache.""" + INDEX_CACHE_DIR.mkdir(parents=True, exist_ok=True) + # Ensure .ignore exists so ripgrep (and tools respecting .ignore) skip + # this directory. Cache files contain unvetted community content that + # could include adversarial text (prompt injection via catalog entries). + ignore_file = HUB_DIR / ".ignore" + if not ignore_file.exists(): + try: + ignore_file.write_text("# Exclude hub internals from search tools\n*\n") + except OSError: + pass + cache_file = INDEX_CACHE_DIR / f"{key}.json" + try: + cache_file.write_text(json.dumps(data, ensure_ascii=False, default=str)) + except OSError as e: + logger.debug("Could not write cache: %s", e) + + +def _skill_meta_to_dict(meta: SkillMeta) -> dict: + """Convert a SkillMeta to a dict for caching.""" + return { + "name": meta.name, + "description": meta.description, + "source": meta.source, + "identifier": meta.identifier, + "trust_level": meta.trust_level, + "repo": meta.repo, + "path": meta.path, + "tags": meta.tags, + "extra": meta.extra, + } + + +# --------------------------------------------------------------------------- +# Lock file management +# --------------------------------------------------------------------------- + +class HubLockFile: + """Manages skills/.hub/lock.json — tracks provenance of installed hub skills.""" + + def __init__(self, path: Path = LOCK_FILE): + self.path = path + + def load(self) -> dict: + if not self.path.exists(): + return {"version": 1, "installed": {}} + try: + return json.loads(self.path.read_text()) + except (json.JSONDecodeError, OSError): + return {"version": 1, "installed": {}} + + def save(self, data: dict) -> None: + self.path.parent.mkdir(parents=True, exist_ok=True) + self.path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n") + + def record_install( + self, + name: str, + source: str, + identifier: str, + trust_level: str, + scan_verdict: str, + skill_hash: str, + install_path: str, + files: List[str], + metadata: Optional[Dict[str, Any]] = None, + ) -> None: + data = self.load() + data["installed"][name] = { + "source": source, + "identifier": identifier, + "trust_level": trust_level, + "scan_verdict": scan_verdict, + "content_hash": skill_hash, + "install_path": install_path, + "files": files, + "metadata": metadata or {}, + "installed_at": datetime.now(timezone.utc).isoformat(), + "updated_at": datetime.now(timezone.utc).isoformat(), + } + self.save(data) + + def record_uninstall(self, name: str) -> None: + data = self.load() + data["installed"].pop(name, None) + self.save(data) + + def get_installed(self, name: str) -> Optional[dict]: + data = self.load() + return data["installed"].get(name) + + def list_installed(self) -> List[dict]: + data = self.load() + result = [] + for name, entry in data["installed"].items(): + result.append({"name": name, **entry}) + return result + + +# --------------------------------------------------------------------------- +# Taps management +# --------------------------------------------------------------------------- + +class TapsManager: + """Manages the taps.json file — custom GitHub repo sources.""" + + def __init__(self, path: Path = TAPS_FILE): + self.path = path + + def load(self) -> List[dict]: + if not self.path.exists(): + return [] + try: + data = json.loads(self.path.read_text()) + return data.get("taps", []) + except (json.JSONDecodeError, OSError): + return [] + + def save(self, taps: List[dict]) -> None: + self.path.parent.mkdir(parents=True, exist_ok=True) + self.path.write_text(json.dumps({"taps": taps}, indent=2) + "\n") + + def add(self, repo: str, path: str = "skills/") -> bool: + """Add a tap. Returns False if already exists.""" + taps = self.load() + if any(t["repo"] == repo for t in taps): + return False + taps.append({"repo": repo, "path": path}) + self.save(taps) + return True + + def remove(self, repo: str) -> bool: + """Remove a tap by repo name. Returns False if not found.""" + taps = self.load() + new_taps = [t for t in taps if t["repo"] != repo] + if len(new_taps) == len(taps): + return False + self.save(new_taps) + return True + + def list_taps(self) -> List[dict]: + return self.load() + + +# --------------------------------------------------------------------------- +# Audit log +# --------------------------------------------------------------------------- + +def append_audit_log(action: str, skill_name: str, source: str, + trust_level: str, verdict: str, extra: str = "") -> None: + """Append a line to the audit log.""" + AUDIT_LOG.parent.mkdir(parents=True, exist_ok=True) + timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + parts = [timestamp, action, skill_name, f"{source}:{trust_level}", verdict] + if extra: + parts.append(extra) + line = " ".join(parts) + "\n" + try: + with open(AUDIT_LOG, "a") as f: + f.write(line) + except OSError as e: + logger.debug("Could not write audit log: %s", e) + + +# --------------------------------------------------------------------------- +# Hub operations (high-level) +# --------------------------------------------------------------------------- + +def ensure_hub_dirs() -> None: + """Create the .hub directory structure if it doesn't exist.""" + HUB_DIR.mkdir(parents=True, exist_ok=True) + QUARANTINE_DIR.mkdir(exist_ok=True) + INDEX_CACHE_DIR.mkdir(exist_ok=True) + if not LOCK_FILE.exists(): + LOCK_FILE.write_text('{"version": 1, "installed": {}}\n') + if not AUDIT_LOG.exists(): + AUDIT_LOG.touch() + if not TAPS_FILE.exists(): + TAPS_FILE.write_text('{"taps": []}\n') + + +def quarantine_bundle(bundle: SkillBundle) -> Path: + """Write a skill bundle to the quarantine directory for scanning.""" + ensure_hub_dirs() + skill_name = _validate_skill_name(bundle.name) + validated_files: List[Tuple[str, Union[str, bytes]]] = [] + for rel_path, file_content in bundle.files.items(): + safe_rel_path = _validate_bundle_rel_path(rel_path) + validated_files.append((safe_rel_path, file_content)) + + dest = QUARANTINE_DIR / skill_name + if dest.exists(): + shutil.rmtree(dest) + dest.mkdir(parents=True) + + for rel_path, file_content in validated_files: + file_dest = dest.joinpath(*rel_path.split("/")) + file_dest.parent.mkdir(parents=True, exist_ok=True) + if isinstance(file_content, bytes): + file_dest.write_bytes(file_content) + else: + file_dest.write_text(file_content, encoding="utf-8") + + return dest + + +def install_from_quarantine( + quarantine_path: Path, + skill_name: str, + category: str, + bundle: SkillBundle, + scan_result: ScanResult, +) -> Path: + """Move a scanned skill from quarantine into the skills directory.""" + safe_skill_name = _validate_skill_name(skill_name) + safe_category = _validate_category_name(category) if category else "" + quarantine_resolved = quarantine_path.resolve() + quarantine_root = QUARANTINE_DIR.resolve() + if not quarantine_resolved.is_relative_to(quarantine_root): + raise ValueError(f"Unsafe quarantine path: {quarantine_path}") + + if safe_category: + install_dir = SKILLS_DIR / safe_category / safe_skill_name + else: + install_dir = SKILLS_DIR / safe_skill_name + + if install_dir.exists(): + shutil.rmtree(install_dir) + + # Warn (but don't block) if SKILL.md is very large + skill_md = quarantine_path / "SKILL.md" + if skill_md.exists(): + try: + skill_size = skill_md.stat().st_size + if skill_size > 100_000: + logger.warning( + "Skill '%s' has a large SKILL.md (%s chars). " + "Large skills consume significant context when loaded. " + "Consider asking the author to split it into smaller files.", + safe_skill_name, + f"{skill_size:,}", + ) + except OSError: + pass + + install_dir.parent.mkdir(parents=True, exist_ok=True) + shutil.move(str(quarantine_path), str(install_dir)) + + # Record in lock file + lock = HubLockFile() + lock.record_install( + name=safe_skill_name, + source=bundle.source, + identifier=bundle.identifier, + trust_level=bundle.trust_level, + scan_verdict=scan_result.verdict, + skill_hash=content_hash(install_dir), + install_path=str(install_dir.relative_to(SKILLS_DIR)), + files=list(bundle.files.keys()), + metadata=bundle.metadata, + ) + + append_audit_log( + "INSTALL", safe_skill_name, bundle.source, + bundle.trust_level, scan_result.verdict, + content_hash(install_dir), + ) + + return install_dir + + +def uninstall_skill(skill_name: str) -> Tuple[bool, str]: + """Remove a hub-installed skill. Refuses to remove builtins.""" + lock = HubLockFile() + entry = lock.get_installed(skill_name) + if not entry: + return False, f"'{skill_name}' is not a hub-installed skill (may be a builtin)" + + install_path = SKILLS_DIR / entry["install_path"] + if install_path.exists(): + shutil.rmtree(install_path) + + lock.record_uninstall(skill_name) + append_audit_log("UNINSTALL", skill_name, entry["source"], entry["trust_level"], "n/a", "user_request") + + return True, f"Uninstalled '{skill_name}' from {entry['install_path']}" + + +def bundle_content_hash(bundle: SkillBundle) -> str: + """Compute a deterministic hash for an in-memory skill bundle.""" + h = hashlib.sha256() + for rel_path in sorted(bundle.files): + h.update(bundle.files[rel_path].encode("utf-8")) + return f"sha256:{h.hexdigest()[:16]}" + + +def _source_matches(source: SkillSource, source_name: str) -> bool: + aliases = { + "skills.sh": "skills-sh", + } + normalized = aliases.get(source_name, source_name) + return source.source_id() == normalized + + +def check_for_skill_updates( + name: Optional[str] = None, + *, + lock: Optional[HubLockFile] = None, + sources: Optional[List[SkillSource]] = None, + auth: Optional[GitHubAuth] = None, +) -> List[dict]: + """Check installed hub skills for upstream changes.""" + lock = lock or HubLockFile() + installed = lock.list_installed() + if name: + installed = [entry for entry in installed if entry.get("name") == name] + + if sources is None: + sources = create_source_router(auth=auth) + + results: List[dict] = [] + for entry in installed: + identifier = entry.get("identifier", "") + source_name = entry.get("source", "") + candidate_sources = [src for src in sources if _source_matches(src, source_name)] or sources + + bundle = None + for src in candidate_sources: + try: + bundle = src.fetch(identifier) + except Exception: + bundle = None + if bundle: + break + + if not bundle: + results.append({ + "name": entry.get("name", ""), + "identifier": identifier, + "source": source_name, + "status": "unavailable", + }) + continue + + current_hash = entry.get("content_hash", "") + latest_hash = bundle_content_hash(bundle) + status = "up_to_date" if current_hash == latest_hash else "update_available" + results.append({ + "name": entry.get("name", ""), + "identifier": identifier, + "source": source_name, + "status": status, + "current_hash": current_hash, + "latest_hash": latest_hash, + "bundle": bundle, + }) + + return results + + +# --------------------------------------------------------------------------- +# Hermes centralized index source +# --------------------------------------------------------------------------- + +HERMES_INDEX_URL = "https://hermes-agent.nousresearch.com/docs/api/skills-index.json" +HERMES_INDEX_CACHE_FILE = INDEX_CACHE_DIR / "hermes-index.json" +HERMES_INDEX_TTL = 6 * 3600 # 6 hours + + +def _load_hermes_index() -> Optional[dict]: + """Fetch the centralized skills index, with local cache. + + The index is a JSON file hosted on the docs site, rebuilt daily by CI. + We cache it locally for HERMES_INDEX_TTL seconds to avoid repeated + downloads within a session. + """ + # Check local cache + if HERMES_INDEX_CACHE_FILE.exists(): + try: + age = time.time() - HERMES_INDEX_CACHE_FILE.stat().st_mtime + if age < HERMES_INDEX_TTL: + return json.loads(HERMES_INDEX_CACHE_FILE.read_text()) + except (OSError, json.JSONDecodeError): + pass + + # Fetch from docs site + try: + resp = httpx.get(HERMES_INDEX_URL, timeout=15, follow_redirects=True) + if resp.status_code != 200: + logger.debug("Hermes index fetch returned %d", resp.status_code) + return _load_stale_index_cache() + data = resp.json() + except (httpx.HTTPError, json.JSONDecodeError) as e: + logger.debug("Hermes index fetch failed: %s", e) + return _load_stale_index_cache() + + # Validate structure + if not isinstance(data, dict) or "skills" not in data: + return _load_stale_index_cache() + + # Cache locally + try: + HERMES_INDEX_CACHE_FILE.parent.mkdir(parents=True, exist_ok=True) + HERMES_INDEX_CACHE_FILE.write_text(json.dumps(data)) + except OSError: + pass + + return data + + +def _load_stale_index_cache() -> Optional[dict]: + """Fall back to stale cache when the network fetch fails.""" + if HERMES_INDEX_CACHE_FILE.exists(): + try: + return json.loads(HERMES_INDEX_CACHE_FILE.read_text()) + except (OSError, json.JSONDecodeError): + pass + return None + + +class HermesIndexSource(SkillSource): + """Skill source backed by the centralized Hermes Skills Index. + + The index is a JSON catalog published to the docs site and rebuilt + daily by CI. It contains metadata + resolved GitHub paths for every + skill, eliminating the need for users to hit the GitHub API for + search or path discovery. + + When the index is unavailable, all methods return empty / None so + downstream sources take over transparently. + """ + + def __init__(self, auth: GitHubAuth): + self._index: Optional[dict] = None + self._loaded = False + self.auth = auth + # Lazily create GitHubSource for fetch — only used when actually + # downloading files, which requires real GitHub API calls. + self._github: Optional[GitHubSource] = None + + def _ensure_loaded(self) -> dict: + if not self._loaded: + self._index = _load_hermes_index() + self._loaded = True + return self._index or {} + + def _get_github(self) -> GitHubSource: + if self._github is None: + self._github = GitHubSource(auth=self.auth) + return self._github + + def source_id(self) -> str: + return "hermes-index" + + @property + def is_available(self) -> bool: + """Whether the index is loaded and has skills.""" + index = self._ensure_loaded() + return bool(index.get("skills")) + + def trust_level_for(self, identifier: str) -> str: + index = self._ensure_loaded() + for skill in index.get("skills", []): + if skill.get("identifier") == identifier: + return skill.get("trust_level", "community") + return "community" + + def search(self, query: str, limit: int = 10) -> List[SkillMeta]: + """Search the cached index. Zero API calls.""" + index = self._ensure_loaded() + skills = index.get("skills", []) + if not skills: + return [] + + if not query.strip(): + # No query — return featured/popular + return [self._to_meta(s) for s in skills[:limit]] + + query_lower = query.lower() + results: List[SkillMeta] = [] + for s in skills: + searchable = f"{s.get('name', '')} {s.get('description', '')} {' '.join(s.get('tags', []))}".lower() + if query_lower in searchable: + results.append(self._to_meta(s)) + if len(results) >= limit: + break + return results + + def fetch(self, identifier: str) -> Optional[SkillBundle]: + """Fetch a skill using the resolved path from the index. + + If the index has a ``resolved_github_id`` for this skill, we skip + the entire candidate/discovery chain and go directly to GitHub + with the exact path. This reduces install from ~31 API calls to + just the file content downloads (~5-22 depending on skill size). + """ + index = self._ensure_loaded() + entry = self._find_entry(identifier, index) + if not entry: + return None + + # Use resolved path if available + resolved = entry.get("resolved_github_id") + if resolved: + bundle = self._get_github().fetch(resolved) + if bundle: + bundle.source = entry.get("source", "hermes-index") + bundle.identifier = identifier + return bundle + + # Fall back to identifier-based fetch via repo/path + repo = entry.get("repo", "") + path = entry.get("path", "") + if repo and path: + github_id = f"{repo}/{path}" + bundle = self._get_github().fetch(github_id) + if bundle: + bundle.source = entry.get("source", "hermes-index") + bundle.identifier = identifier + return bundle + + return None + + def inspect(self, identifier: str) -> Optional[SkillMeta]: + """Return metadata from the index. Zero API calls.""" + index = self._ensure_loaded() + entry = self._find_entry(identifier, index) + if entry: + return self._to_meta(entry) + return None + + def _find_entry(self, identifier: str, index: dict) -> Optional[dict]: + """Look up a skill in the index by identifier or name.""" + skills = index.get("skills", []) + + # Exact identifier match + for s in skills: + if s.get("identifier") == identifier: + return s + + # Try without source prefix (e.g. "skills-sh/" stripped) + normalized = identifier + for prefix in ("skills-sh/", "skills.sh/", "official/", "github/", "clawhub/"): + if identifier.startswith(prefix): + normalized = identifier[len(prefix):] + break + + # Match on normalized identifier or name + for s in skills: + sid = s.get("identifier", "") + # Strip prefix from stored identifier too + stored_normalized = sid + for prefix in ("skills-sh/", "skills.sh/", "official/", "github/", "clawhub/"): + if sid.startswith(prefix): + stored_normalized = sid[len(prefix):] + break + if stored_normalized == normalized: + return s + + return None + + @staticmethod + def _to_meta(entry: dict) -> SkillMeta: + return SkillMeta( + name=entry.get("name", ""), + description=entry.get("description", ""), + source=entry.get("source", "hermes-index"), + identifier=entry.get("identifier", ""), + trust_level=entry.get("trust_level", "community"), + repo=entry.get("repo"), + path=entry.get("path"), + tags=entry.get("tags", []), + extra=entry.get("extra", {}), + ) + + +def create_source_router(auth: Optional[GitHubAuth] = None) -> List[SkillSource]: + """ + Create all configured source adapters. + Returns a list of active sources for search/fetch operations. + """ + if auth is None: + auth = GitHubAuth() + + taps_mgr = TapsManager() + extra_taps = taps_mgr.list_taps() + + sources: List[SkillSource] = [ + OptionalSkillSource(), # Official optional skills (highest priority) + HermesIndexSource(auth=auth), # Centralized index (search + resolved install paths) + SkillsShSource(auth=auth), + WellKnownSkillSource(), + GitHubSource(auth=auth, extra_taps=extra_taps), + ClawHubSource(), + ClaudeMarketplaceSource(auth=auth), + LobeHubSource(), + ] + + return sources + + +def _search_one_source( + src: SkillSource, query: str, limit: int +) -> Tuple[str, List[SkillMeta]]: + """Search a single source. Runs in a thread for parallelism.""" + try: + return src.source_id(), src.search(query, limit=limit) + except Exception as e: + logger.debug("Search failed for %s: %s", src.source_id(), e) + return src.source_id(), [] + + +def parallel_search_sources( + sources: List[SkillSource], + query: str = "", + per_source_limits: Optional[Dict[str, int]] = None, + source_filter: str = "all", + overall_timeout: float = 30, + on_source_done: Optional[Any] = None, +) -> Tuple[List[SkillMeta], Dict[str, int], List[str]]: + """Search all sources in parallel with per-source timeout. + + Returns ``(all_results, source_counts, timed_out_ids)``. + + *on_source_done* is an optional callback ``(source_id, count) -> None`` + invoked as each source completes — useful for progress indicators. + """ + from concurrent.futures import ThreadPoolExecutor, as_completed + + per_source_limits = per_source_limits or {} + + active: List[SkillSource] = [] + # When the centralized index is available and the user hasn't filtered + # to a specific source, skip external API sources (github, skills-sh, + # clawhub, etc.) — the index already has their data. This avoids + # ~70 GitHub API calls per search for unauthenticated users. + _index_available = False + _api_source_ids = frozenset({"github", "skills-sh", "clawhub", + "claude-marketplace", "lobehub", "well-known"}) + if source_filter == "all": + for src in sources: + if (src.source_id() == "hermes-index" + and getattr(src, "is_available", False)): + _index_available = True + break + + for src in sources: + sid = src.source_id() + if source_filter != "all" and sid != source_filter and sid != "official": + continue + # Skip external API sources when the index covers them + if _index_available and sid in _api_source_ids: + continue + active.append(src) + + all_results: List[SkillMeta] = [] + source_counts: Dict[str, int] = {} + timed_out_ids: List[str] = [] + + if not active: + return all_results, source_counts, timed_out_ids + + with ThreadPoolExecutor(max_workers=min(len(active), 8)) as pool: + futures = {} + for src in active: + lim = per_source_limits.get(src.source_id(), 50) + fut = pool.submit(_search_one_source, src, query, lim) + futures[fut] = src.source_id() + + try: + for fut in as_completed(futures, timeout=overall_timeout): + try: + sid, results = fut.result(timeout=0) + source_counts[sid] = len(results) + all_results.extend(results) + if on_source_done: + on_source_done(sid, len(results)) + except Exception: + pass + except TimeoutError: + timed_out_ids = [ + futures[f] for f in futures if not f.done() + ] + if timed_out_ids: + logger.debug( + "Skills browse timed out waiting for: %s", + ", ".join(timed_out_ids), + ) + + return all_results, source_counts, timed_out_ids + + +def unified_search(query: str, sources: List[SkillSource], + source_filter: str = "all", limit: int = 10) -> List[SkillMeta]: + """Search all sources (in parallel) and merge results.""" + all_results, _, _ = parallel_search_sources( + sources, + query=query, + source_filter=source_filter, + overall_timeout=30, + ) + + # Deduplicate by name, preferring higher trust levels + _TRUST_RANK = {"builtin": 2, "trusted": 1, "community": 0} + seen: Dict[str, SkillMeta] = {} + for r in all_results: + if r.name not in seen: + seen[r.name] = r + elif _TRUST_RANK.get(r.trust_level, 0) > _TRUST_RANK.get(seen[r.name].trust_level, 0): + seen[r.name] = r + deduped = list(seen.values()) + + return deduped[:limit] diff --git a/mindcli/_vendor/tools/skills_sync.py b/mindcli/_vendor/tools/skills_sync.py new file mode 100644 index 0000000..18ce1e3 --- /dev/null +++ b/mindcli/_vendor/tools/skills_sync.py @@ -0,0 +1,316 @@ +#!/usr/bin/env python3 +""" +Skills Sync -- Manifest-based seeding and updating of bundled skills. + +Copies bundled skills from the repo's skills/ directory into ~/.hermes/skills/ +and uses a manifest to track which skills have been synced and their origin hash. + +Manifest format (v2): each line is "skill_name:origin_hash" where origin_hash +is the MD5 of the bundled skill at the time it was last synced to the user dir. +Old v1 manifests (plain names without hashes) are auto-migrated. + +Update logic: + - NEW skills (not in manifest): copied to user dir, origin hash recorded. + - EXISTING skills (in manifest, present in user dir): + * If user copy matches origin hash: user hasn't modified it → safe to + update from bundled if bundled changed. New origin hash recorded. + * If user copy differs from origin hash: user customized it → SKIP. + - DELETED by user (in manifest, absent from user dir): respected, not re-added. + - REMOVED from bundled (in manifest, gone from repo): cleaned from manifest. + +The manifest lives at ~/.hermes/skills/.bundled_manifest. +""" + +import hashlib +import logging +import os +import shutil +from pathlib import Path +from hermes_constants import get_hermes_home +from typing import Dict, List, Tuple + +logger = logging.getLogger(__name__) + + +HERMES_HOME = get_hermes_home() +SKILLS_DIR = HERMES_HOME / "skills" +MANIFEST_FILE = SKILLS_DIR / ".bundled_manifest" + + +def _get_bundled_dir() -> Path: + """Locate the bundled skills/ directory. + + Checks HERMES_BUNDLED_SKILLS env var first (set by Nix wrapper), + then falls back to the relative path from this source file. + """ + env_override = os.getenv("HERMES_BUNDLED_SKILLS") + if env_override: + return Path(env_override) + return Path(__file__).parent.parent / "skills" + + +def _read_manifest() -> Dict[str, str]: + """ + Read the manifest as a dict of {skill_name: origin_hash}. + + Handles both v1 (plain names) and v2 (name:hash) formats. + v1 entries get an empty hash string which triggers migration on next sync. + """ + if not MANIFEST_FILE.exists(): + return {} + try: + result = {} + for line in MANIFEST_FILE.read_text(encoding="utf-8").splitlines(): + line = line.strip() + if not line: + continue + if ":" in line: + # v2 format: name:hash + name, _, hash_val = line.partition(":") + result[name.strip()] = hash_val.strip() + else: + # v1 format: plain name — empty hash triggers migration + result[line] = "" + return result + except (OSError, IOError): + return {} + + +def _write_manifest(entries: Dict[str, str]): + """Write the manifest file atomically in v2 format (name:hash). + + Uses a temp file + os.replace() to avoid corruption if the process + crashes or is interrupted mid-write. + """ + import tempfile + + MANIFEST_FILE.parent.mkdir(parents=True, exist_ok=True) + data = "\n".join(f"{name}:{hash_val}" for name, hash_val in sorted(entries.items())) + "\n" + + try: + fd, tmp_path = tempfile.mkstemp( + dir=str(MANIFEST_FILE.parent), + prefix=".bundled_manifest_", + suffix=".tmp", + ) + try: + with os.fdopen(fd, "w", encoding="utf-8") as f: + f.write(data) + f.flush() + os.fsync(f.fileno()) + os.replace(tmp_path, MANIFEST_FILE) + except BaseException: + try: + os.unlink(tmp_path) + except OSError: + pass + raise + except Exception as e: + logger.debug("Failed to write skills manifest %s: %s", MANIFEST_FILE, e, exc_info=True) + + +def _read_skill_name(skill_md: Path, fallback: str) -> str: + """Read the name field from SKILL.md YAML frontmatter, falling back to *fallback*.""" + try: + content = skill_md.read_text(encoding="utf-8", errors="replace")[:4000] + except OSError: + return fallback + in_frontmatter = False + for line in content.split("\n"): + stripped = line.strip() + if stripped == "---": + if in_frontmatter: + break + in_frontmatter = True + continue + if in_frontmatter and stripped.startswith("name:"): + value = stripped.split(":", 1)[1].strip().strip("\"'") + if value: + return value + return fallback + + +def _discover_bundled_skills(bundled_dir: Path) -> List[Tuple[str, Path]]: + """ + Find all SKILL.md files in the bundled directory. + Returns list of (skill_name, skill_directory_path) tuples. + """ + skills = [] + if not bundled_dir.exists(): + return skills + + for skill_md in bundled_dir.rglob("SKILL.md"): + path_str = str(skill_md) + if "/.git/" in path_str or "/.github/" in path_str or "/.hub/" in path_str: + continue + skill_dir = skill_md.parent + skill_name = _read_skill_name(skill_md, skill_dir.name) + skills.append((skill_name, skill_dir)) + + return skills + + +def _compute_relative_dest(skill_dir: Path, bundled_dir: Path) -> Path: + """ + Compute the destination path in SKILLS_DIR preserving the category structure. + e.g., bundled/skills/mlops/axolotl -> ~/.hermes/skills/mlops/axolotl + """ + rel = skill_dir.relative_to(bundled_dir) + return SKILLS_DIR / rel + + +def _dir_hash(directory: Path) -> str: + """Compute a hash of all file contents in a directory for change detection.""" + hasher = hashlib.md5() + try: + for fpath in sorted(directory.rglob("*")): + if fpath.is_file(): + rel = fpath.relative_to(directory) + hasher.update(str(rel).encode("utf-8")) + hasher.update(fpath.read_bytes()) + except (OSError, IOError): + pass + return hasher.hexdigest() + + +def sync_skills(quiet: bool = False) -> dict: + """ + Sync bundled skills into ~/.hermes/skills/ using the manifest. + + Returns: + dict with keys: copied (list), updated (list), skipped (int), + user_modified (list), cleaned (list), total_bundled (int) + """ + bundled_dir = _get_bundled_dir() + if not bundled_dir.exists(): + return { + "copied": [], "updated": [], "skipped": 0, + "user_modified": [], "cleaned": [], "total_bundled": 0, + } + + SKILLS_DIR.mkdir(parents=True, exist_ok=True) + manifest = _read_manifest() + bundled_skills = _discover_bundled_skills(bundled_dir) + bundled_names = {name for name, _ in bundled_skills} + + copied = [] + updated = [] + user_modified = [] + skipped = 0 + + for skill_name, skill_src in bundled_skills: + dest = _compute_relative_dest(skill_src, bundled_dir) + bundled_hash = _dir_hash(skill_src) + + if skill_name not in manifest: + # ── New skill — never offered before ── + try: + if dest.exists(): + # User already has a skill with the same name — don't overwrite + skipped += 1 + manifest[skill_name] = bundled_hash + else: + dest.parent.mkdir(parents=True, exist_ok=True) + shutil.copytree(skill_src, dest) + copied.append(skill_name) + manifest[skill_name] = bundled_hash + if not quiet: + print(f" + {skill_name}") + except (OSError, IOError) as e: + if not quiet: + print(f" ! Failed to copy {skill_name}: {e}") + # Do NOT add to manifest — next sync should retry + + elif dest.exists(): + # ── Existing skill — in manifest AND on disk ── + origin_hash = manifest.get(skill_name, "") + user_hash = _dir_hash(dest) + + if not origin_hash: + # v1 migration: no origin hash recorded. Set baseline from + # user's current copy so future syncs can detect modifications. + manifest[skill_name] = user_hash + if user_hash == bundled_hash: + skipped += 1 # already in sync + else: + # Can't tell if user modified or bundled changed — be safe + skipped += 1 + continue + + if user_hash != origin_hash: + # User modified this skill — don't overwrite their changes + user_modified.append(skill_name) + if not quiet: + print(f" ~ {skill_name} (user-modified, skipping)") + continue + + # User copy matches origin — check if bundled has a newer version + if bundled_hash != origin_hash: + try: + # Move old copy to a backup so we can restore on failure + backup = dest.with_suffix(".bak") + shutil.move(str(dest), str(backup)) + try: + shutil.copytree(skill_src, dest) + manifest[skill_name] = bundled_hash + updated.append(skill_name) + if not quiet: + print(f" ↑ {skill_name} (updated)") + # Remove backup after successful copy + shutil.rmtree(backup, ignore_errors=True) + except (OSError, IOError): + # Restore from backup + if backup.exists() and not dest.exists(): + shutil.move(str(backup), str(dest)) + raise + except (OSError, IOError) as e: + if not quiet: + print(f" ! Failed to update {skill_name}: {e}") + else: + skipped += 1 # bundled unchanged, user unchanged + + else: + # ── In manifest but not on disk — user deleted it ── + skipped += 1 + + # Clean stale manifest entries (skills removed from bundled dir) + cleaned = sorted(set(manifest.keys()) - bundled_names) + for name in cleaned: + del manifest[name] + + # Also copy DESCRIPTION.md files for categories (if not already present) + for desc_md in bundled_dir.rglob("DESCRIPTION.md"): + rel = desc_md.relative_to(bundled_dir) + dest_desc = SKILLS_DIR / rel + if not dest_desc.exists(): + try: + dest_desc.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(desc_md, dest_desc) + except (OSError, IOError) as e: + logger.debug("Could not copy %s: %s", desc_md, e) + + _write_manifest(manifest) + + return { + "copied": copied, + "updated": updated, + "skipped": skipped, + "user_modified": user_modified, + "cleaned": cleaned, + "total_bundled": len(bundled_skills), + } + + +if __name__ == "__main__": + print("Syncing bundled skills into ~/.hermes/skills/ ...") + result = sync_skills(quiet=False) + parts = [ + f"{len(result['copied'])} new", + f"{len(result['updated'])} updated", + f"{result['skipped']} unchanged", + ] + if result["user_modified"]: + parts.append(f"{len(result['user_modified'])} user-modified (kept)") + if result["cleaned"]: + parts.append(f"{len(result['cleaned'])} cleaned from manifest") + print(f"\nDone: {', '.join(parts)}. {result['total_bundled']} total bundled.") diff --git a/mindcli/_vendor/tools/skills_tool.py b/mindcli/_vendor/tools/skills_tool.py new file mode 100644 index 0000000..90839b9 --- /dev/null +++ b/mindcli/_vendor/tools/skills_tool.py @@ -0,0 +1,1268 @@ +#!/usr/bin/env python3 +""" +Skills Tool Module + +This module provides tools for listing and viewing skill documents. +Skills are organized as directories containing a SKILL.md file (the main instructions) +and optional supporting files like references, templates, and examples. + +Inspired by Anthropic's Claude Skills system with progressive disclosure architecture: +- Metadata (name ≤64 chars, description ≤1024 chars) - shown in skills_list +- Full Instructions - loaded via skill_view when needed +- Linked Files (references, templates) - loaded on demand + +Directory Structure: + skills/ + ├── my-skill/ + │ ├── SKILL.md # Main instructions (required) + │ ├── references/ # Supporting documentation + │ │ ├── api.md + │ │ └── examples.md + │ ├── templates/ # Templates for output + │ │ └── template.md + │ └── assets/ # Supplementary files (agentskills.io standard) + └── category/ # Category folder for organization + └── another-skill/ + └── SKILL.md + +SKILL.md Format (YAML Frontmatter, agentskills.io compatible): + --- + name: skill-name # Required, max 64 chars + description: Brief description # Required, max 1024 chars + version: 1.0.0 # Optional + license: MIT # Optional (agentskills.io) + platforms: [macos] # Optional — restrict to specific OS platforms + # Valid: macos, linux, windows + # Omit to load on all platforms (default) + prerequisites: # Optional — legacy runtime requirements + env_vars: [API_KEY] # Legacy env var names are normalized into + # required_environment_variables on load. + commands: [curl, jq] # Command checks remain advisory only. + compatibility: Requires X # Optional (agentskills.io) + metadata: # Optional, arbitrary key-value (agentskills.io) + hermes: + tags: [fine-tuning, llm] + related_skills: [peft, lora] + --- + + # Skill Title + + Full instructions and content here... + +Available tools: +- skills_list: List skills with metadata (progressive disclosure tier 1) +- skill_view: Load full skill content (progressive disclosure tier 2-3) + +Usage: + from tools.skills_tool import skills_list, skill_view, check_skills_requirements + + # List all skills (returns metadata only - token efficient) + result = skills_list() + + # View a skill's main content (loads full instructions) + content = skill_view("axolotl") + + # View a reference file within a skill (loads linked file) + content = skill_view("axolotl", "references/dataset-formats.md") +""" + +import json +import logging + +from hermes_constants import get_hermes_home +import os +import re +from enum import Enum +from pathlib import Path +from typing import Dict, Any, List, Optional, Set, Tuple + +from tools.registry import registry, tool_error + +logger = logging.getLogger(__name__) + + +# All skills live in ~/.hermes/skills/ (seeded from bundled skills/ on install). +# This is the single source of truth -- agent edits, hub installs, and bundled +# skills all coexist here without polluting the git repo. +HERMES_HOME = get_hermes_home() +SKILLS_DIR = HERMES_HOME / "skills" + +# Anthropic-recommended limits for progressive disclosure efficiency +MAX_NAME_LENGTH = 64 +MAX_DESCRIPTION_LENGTH = 1024 + +# Platform identifiers for the 'platforms' frontmatter field. +# Maps user-friendly names to sys.platform prefixes. +_PLATFORM_MAP = { + "macos": "darwin", + "linux": "linux", + "windows": "win32", +} +_ENV_VAR_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$") +_EXCLUDED_SKILL_DIRS = frozenset((".git", ".github", ".hub")) +_REMOTE_ENV_BACKENDS = frozenset({"docker", "singularity", "modal", "ssh", "daytona"}) +_secret_capture_callback = None + + +def load_env() -> Dict[str, str]: + """Load profile-scoped environment variables from HERMES_HOME/.env.""" + env_path = get_hermes_home() / ".env" + env_vars: Dict[str, str] = {} + if not env_path.exists(): + return env_vars + + with env_path.open() as f: + for line in f: + line = line.strip() + if line and not line.startswith("#") and "=" in line: + key, _, value = line.partition("=") + env_vars[key.strip()] = value.strip().strip("\"'") + return env_vars + + +class SkillReadinessStatus(str, Enum): + AVAILABLE = "available" + SETUP_NEEDED = "setup_needed" + UNSUPPORTED = "unsupported" + + +def set_secret_capture_callback(callback) -> None: + global _secret_capture_callback + _secret_capture_callback = callback + + +def skill_matches_platform(frontmatter: Dict[str, Any]) -> bool: + """Check if a skill is compatible with the current OS platform. + + Delegates to ``agent.skill_utils.skill_matches_platform`` — kept here + as a public re-export so existing callers don't need updating. + """ + from agent.skill_utils import skill_matches_platform as _impl + return _impl(frontmatter) + + +def _normalize_prerequisite_values(value: Any) -> List[str]: + if not value: + return [] + if isinstance(value, str): + value = [value] + return [str(item) for item in value if str(item).strip()] + + +def _collect_prerequisite_values( + frontmatter: Dict[str, Any], +) -> Tuple[List[str], List[str]]: + prereqs = frontmatter.get("prerequisites") + if not prereqs or not isinstance(prereqs, dict): + return [], [] + return ( + _normalize_prerequisite_values(prereqs.get("env_vars")), + _normalize_prerequisite_values(prereqs.get("commands")), + ) + + +def _normalize_setup_metadata(frontmatter: Dict[str, Any]) -> Dict[str, Any]: + setup = frontmatter.get("setup") + if not isinstance(setup, dict): + return {"help": None, "collect_secrets": []} + + help_text = setup.get("help") + normalized_help = ( + str(help_text).strip() + if isinstance(help_text, str) and help_text.strip() + else None + ) + + collect_secrets_raw = setup.get("collect_secrets") + if isinstance(collect_secrets_raw, dict): + collect_secrets_raw = [collect_secrets_raw] + if not isinstance(collect_secrets_raw, list): + collect_secrets_raw = [] + + collect_secrets: List[Dict[str, Any]] = [] + for item in collect_secrets_raw: + if not isinstance(item, dict): + continue + + env_var = str(item.get("env_var") or "").strip() + if not env_var: + continue + + prompt = str(item.get("prompt") or f"Enter value for {env_var}").strip() + provider_url = str(item.get("provider_url") or item.get("url") or "").strip() + + entry: Dict[str, Any] = { + "env_var": env_var, + "prompt": prompt, + "secret": bool(item.get("secret", True)), + } + if provider_url: + entry["provider_url"] = provider_url + collect_secrets.append(entry) + + return { + "help": normalized_help, + "collect_secrets": collect_secrets, + } + + +def _get_required_environment_variables( + frontmatter: Dict[str, Any], + legacy_env_vars: List[str] | None = None, +) -> List[Dict[str, Any]]: + setup = _normalize_setup_metadata(frontmatter) + required_raw = frontmatter.get("required_environment_variables") + if isinstance(required_raw, dict): + required_raw = [required_raw] + if not isinstance(required_raw, list): + required_raw = [] + + required: List[Dict[str, Any]] = [] + seen: set[str] = set() + + def _append_required(entry: Dict[str, Any]) -> None: + env_name = str(entry.get("name") or entry.get("env_var") or "").strip() + if not env_name or env_name in seen: + return + if not _ENV_VAR_NAME_RE.match(env_name): + return + + normalized: Dict[str, Any] = { + "name": env_name, + "prompt": str(entry.get("prompt") or f"Enter value for {env_name}").strip(), + } + + help_text = ( + entry.get("help") + or entry.get("provider_url") + or entry.get("url") + or setup.get("help") + ) + if isinstance(help_text, str) and help_text.strip(): + normalized["help"] = help_text.strip() + + required_for = entry.get("required_for") + if isinstance(required_for, str) and required_for.strip(): + normalized["required_for"] = required_for.strip() + + if entry.get("optional"): + normalized["optional"] = True + + seen.add(env_name) + required.append(normalized) + + for item in required_raw: + if isinstance(item, str): + _append_required({"name": item}) + continue + if isinstance(item, dict): + _append_required(item) + + for item in setup["collect_secrets"]: + _append_required( + { + "name": item.get("env_var"), + "prompt": item.get("prompt"), + "help": item.get("provider_url") or setup.get("help"), + } + ) + + if legacy_env_vars is None: + legacy_env_vars, _ = _collect_prerequisite_values(frontmatter) + for env_var in legacy_env_vars: + _append_required({"name": env_var}) + + return required + + +def _capture_required_environment_variables( + skill_name: str, + missing_entries: List[Dict[str, Any]], +) -> Dict[str, Any]: + if not missing_entries: + return { + "missing_names": [], + "setup_skipped": False, + "gateway_setup_hint": None, + } + + missing_names = [entry["name"] for entry in missing_entries] + if _is_gateway_surface(): + return { + "missing_names": missing_names, + "setup_skipped": False, + "gateway_setup_hint": _gateway_setup_hint(), + } + + if _secret_capture_callback is None: + return { + "missing_names": missing_names, + "setup_skipped": False, + "gateway_setup_hint": None, + } + + setup_skipped = False + remaining_names: List[str] = [] + + for entry in missing_entries: + metadata = {"skill_name": skill_name} + if entry.get("help"): + metadata["help"] = entry["help"] + if entry.get("required_for"): + metadata["required_for"] = entry["required_for"] + + try: + callback_result = _secret_capture_callback( + entry["name"], + entry["prompt"], + metadata, + ) + except Exception: + logger.warning( + f"Secret capture callback failed for {entry['name']}", exc_info=True + ) + callback_result = { + "success": False, + "stored_as": entry["name"], + "validated": False, + "skipped": True, + } + + success = isinstance(callback_result, dict) and bool( + callback_result.get("success") + ) + skipped = isinstance(callback_result, dict) and bool( + callback_result.get("skipped") + ) + if success and not skipped: + continue + + setup_skipped = True + remaining_names.append(entry["name"]) + + return { + "missing_names": remaining_names, + "setup_skipped": setup_skipped, + "gateway_setup_hint": None, + } + + +def _is_gateway_surface() -> bool: + if os.getenv("HERMES_GATEWAY_SESSION"): + return True + from gateway.session_context import get_session_env + return bool(get_session_env("HERMES_SESSION_PLATFORM")) + + +def _get_terminal_backend_name() -> str: + return str(os.getenv("TERMINAL_ENV", "local")).strip().lower() or "local" + + +def _is_env_var_persisted( + var_name: str, env_snapshot: Dict[str, str] | None = None +) -> bool: + if env_snapshot is None: + env_snapshot = load_env() + if var_name in env_snapshot: + return bool(env_snapshot.get(var_name)) + return bool(os.getenv(var_name)) + + +def _remaining_required_environment_names( + required_env_vars: List[Dict[str, Any]], + capture_result: Dict[str, Any], + *, + env_snapshot: Dict[str, str] | None = None, +) -> List[str]: + missing_names = set(capture_result["missing_names"]) + + if env_snapshot is None: + env_snapshot = load_env() + remaining = [] + for entry in required_env_vars: + name = entry["name"] + if entry.get("optional"): + continue + if name in missing_names or not _is_env_var_persisted(name, env_snapshot): + remaining.append(name) + return remaining + + +def _gateway_setup_hint() -> str: + try: + from gateway.platforms.base import GATEWAY_SECRET_CAPTURE_UNSUPPORTED_MESSAGE + + return GATEWAY_SECRET_CAPTURE_UNSUPPORTED_MESSAGE + except Exception: + return "Secure secret entry is not available. Load this skill in the local CLI to be prompted, or add the key to ~/.hermes/.env manually." + + +def _build_setup_note( + readiness_status: SkillReadinessStatus, + missing: List[str], + setup_help: str | None = None, +) -> str | None: + if readiness_status == SkillReadinessStatus.SETUP_NEEDED: + missing_str = ", ".join(missing) if missing else "required prerequisites" + note = f"Setup needed before using this skill: missing {missing_str}." + if setup_help: + return f"{note} {setup_help}" + return note + return None + + +def check_skills_requirements() -> bool: + """Skills are always available -- the directory is created on first use if needed.""" + return True + + +def _parse_frontmatter(content: str) -> Tuple[Dict[str, Any], str]: + """Parse YAML frontmatter from markdown content. + + Delegates to ``agent.skill_utils.parse_frontmatter`` — kept here + as a public re-export so existing callers don't need updating. + """ + from agent.skill_utils import parse_frontmatter + return parse_frontmatter(content) + + +def _get_category_from_path(skill_path: Path) -> Optional[str]: + """ + Extract category from skill path based on directory structure. + + For paths like: ~/.hermes/skills/mlops/axolotl/SKILL.md -> "mlops" + Also works for external skill dirs configured via skills.external_dirs. + """ + # Try the module-level SKILLS_DIR first (respects monkeypatching in tests), + # then fall back to external dirs from config. + dirs_to_check = [SKILLS_DIR] + try: + from agent.skill_utils import get_external_skills_dirs + dirs_to_check.extend(get_external_skills_dirs()) + except Exception: + pass + for skills_dir in dirs_to_check: + try: + rel_path = skill_path.relative_to(skills_dir) + parts = rel_path.parts + if len(parts) >= 3: + return parts[0] + except ValueError: + continue + return None + + +def _parse_tags(tags_value) -> List[str]: + """ + Parse tags from frontmatter value. + + Handles: + - Already-parsed list (from yaml.safe_load): [tag1, tag2] + - String with brackets: "[tag1, tag2]" + - Comma-separated string: "tag1, tag2" + + Args: + tags_value: Raw tags value — may be a list or string + + Returns: + List of tag strings + """ + if not tags_value: + return [] + + # yaml.safe_load already returns a list for [tag1, tag2] + if isinstance(tags_value, list): + return [str(t).strip() for t in tags_value if t] + + # String fallback — handle bracket-wrapped or comma-separated + tags_value = str(tags_value).strip() + if tags_value.startswith("[") and tags_value.endswith("]"): + tags_value = tags_value[1:-1] + + return [t.strip().strip("\"'") for t in tags_value.split(",") if t.strip()] + + + +def _get_disabled_skill_names() -> Set[str]: + """Load disabled skill names from config. + + Delegates to ``agent.skill_utils.get_disabled_skill_names`` — kept here + as a public re-export so existing callers don't need updating. + """ + from agent.skill_utils import get_disabled_skill_names + return get_disabled_skill_names() + + +def _is_skill_disabled(name: str, platform: str = None) -> bool: + """Check if a skill is disabled in config.""" + import os + try: + from hermes_cli.config import load_config + config = load_config() + skills_cfg = config.get("skills", {}) + resolved_platform = platform or os.getenv("HERMES_PLATFORM") + if resolved_platform: + platform_disabled = skills_cfg.get("platform_disabled", {}).get(resolved_platform) + if platform_disabled is not None: + return name in platform_disabled + return name in skills_cfg.get("disabled", []) + except Exception: + return False + + +def _find_all_skills(*, skip_disabled: bool = False) -> List[Dict[str, Any]]: + """Recursively find all skills in ~/.hermes/skills/ and external dirs. + + Args: + skip_disabled: If True, return ALL skills regardless of disabled + state (used by ``hermes skills`` config UI). Default False + filters out disabled skills. + + Returns: + List of skill metadata dicts (name, description, category). + """ + from agent.skill_utils import get_external_skills_dirs + + skills = [] + seen_names: set = set() + + # Load disabled set once (not per-skill) + disabled = set() if skip_disabled else _get_disabled_skill_names() + + # Scan local dir first, then external dirs (local takes precedence) + dirs_to_scan = [] + if SKILLS_DIR.exists(): + dirs_to_scan.append(SKILLS_DIR) + dirs_to_scan.extend(get_external_skills_dirs()) + + for scan_dir in dirs_to_scan: + for skill_md in scan_dir.rglob("SKILL.md"): + if any(part in _EXCLUDED_SKILL_DIRS for part in skill_md.parts): + continue + + skill_dir = skill_md.parent + + try: + content = skill_md.read_text(encoding="utf-8")[:4000] + frontmatter, body = _parse_frontmatter(content) + + if not skill_matches_platform(frontmatter): + continue + + name = frontmatter.get("name", skill_dir.name)[:MAX_NAME_LENGTH] + if name in seen_names: + continue + if name in disabled: + continue + + description = frontmatter.get("description", "") + if not description: + for line in body.strip().split("\n"): + line = line.strip() + if line and not line.startswith("#"): + description = line + break + + if len(description) > MAX_DESCRIPTION_LENGTH: + description = description[:MAX_DESCRIPTION_LENGTH - 3] + "..." + + category = _get_category_from_path(skill_md) + + seen_names.add(name) + skills.append({ + "name": name, + "description": description, + "category": category, + }) + + except (UnicodeDecodeError, PermissionError) as e: + logger.debug("Failed to read skill file %s: %s", skill_md, e) + continue + except Exception as e: + logger.debug( + "Skipping skill at %s: failed to parse: %s", skill_md, e, exc_info=True + ) + continue + + return skills + + +def _load_category_description(category_dir: Path) -> Optional[str]: + """ + Load category description from DESCRIPTION.md if it exists. + + Args: + category_dir: Path to the category directory + + Returns: + Description string or None if not found + """ + desc_file = category_dir / "DESCRIPTION.md" + if not desc_file.exists(): + return None + + try: + content = desc_file.read_text(encoding="utf-8") + # Parse frontmatter if present + frontmatter, body = _parse_frontmatter(content) + + # Prefer frontmatter description, fall back to first non-header line + description = frontmatter.get("description", "") + if not description: + for line in body.strip().split("\n"): + line = line.strip() + if line and not line.startswith("#"): + description = line + break + + # Truncate to reasonable length + if len(description) > MAX_DESCRIPTION_LENGTH: + description = description[: MAX_DESCRIPTION_LENGTH - 3] + "..." + + return description if description else None + except (UnicodeDecodeError, PermissionError) as e: + logger.debug("Failed to read category description %s: %s", desc_file, e) + return None + except Exception as e: + logger.warning( + "Error parsing category description %s: %s", desc_file, e, exc_info=True + ) + return None + + +def skills_list(category: str = None, task_id: str = None) -> str: + """ + List all available skills (progressive disclosure tier 1 - minimal metadata). + + Returns only name + description to minimize token usage. Use skill_view() to + load full content, tags, related files, etc. + + Args: + category: Optional category filter (e.g., "mlops") + task_id: Optional task identifier used to probe the active backend + + Returns: + JSON string with minimal skill info: name, description, category + """ + try: + if not SKILLS_DIR.exists(): + SKILLS_DIR.mkdir(parents=True, exist_ok=True) + return json.dumps( + { + "success": True, + "skills": [], + "categories": [], + "message": "No skills found. Skills directory created at ~/.hermes/skills/", + }, + ensure_ascii=False, + ) + + # Find all skills + all_skills = _find_all_skills() + + if not all_skills: + return json.dumps( + { + "success": True, + "skills": [], + "categories": [], + "message": "No skills found in skills/ directory.", + }, + ensure_ascii=False, + ) + + # Filter by category if specified + if category: + all_skills = [s for s in all_skills if s.get("category") == category] + + # Sort by category then name + all_skills.sort(key=lambda s: (s.get("category") or "", s["name"])) + + # Extract unique categories + categories = sorted( + set(s.get("category") for s in all_skills if s.get("category")) + ) + + return json.dumps( + { + "success": True, + "skills": all_skills, + "categories": categories, + "count": len(all_skills), + "hint": "Use skill_view(name) to see full content, tags, and linked files", + }, + ensure_ascii=False, + ) + + except Exception as e: + return tool_error(str(e), success=False) + + +def skill_view(name: str, file_path: str = None, task_id: str = None) -> str: + """ + View the content of a skill or a specific file within a skill directory. + + Args: + name: Name or path of the skill (e.g., "axolotl" or "03-fine-tuning/axolotl") + file_path: Optional path to a specific file within the skill (e.g., "references/api.md") + task_id: Optional task identifier used to probe the active backend + + Returns: + JSON string with skill content or error message + """ + try: + from agent.skill_utils import get_external_skills_dirs + + # Build list of all skill directories to search + all_dirs = [] + if SKILLS_DIR.exists(): + all_dirs.append(SKILLS_DIR) + all_dirs.extend(get_external_skills_dirs()) + + if not all_dirs: + return json.dumps( + { + "success": False, + "error": "Skills directory does not exist yet. It will be created on first install.", + }, + ensure_ascii=False, + ) + + skill_dir = None + skill_md = None + + # Search all dirs: local first, then external (first match wins) + for search_dir in all_dirs: + # Try direct path first (e.g., "mlops/axolotl") + direct_path = search_dir / name + if direct_path.is_dir() and (direct_path / "SKILL.md").exists(): + skill_dir = direct_path + skill_md = direct_path / "SKILL.md" + break + elif direct_path.with_suffix(".md").exists(): + skill_md = direct_path.with_suffix(".md") + break + + # Search by directory name across all dirs + if not skill_md: + for search_dir in all_dirs: + for found_skill_md in search_dir.rglob("SKILL.md"): + if found_skill_md.parent.name == name: + skill_dir = found_skill_md.parent + skill_md = found_skill_md + break + if skill_md: + break + + # Legacy: flat .md files + if not skill_md: + for search_dir in all_dirs: + for found_md in search_dir.rglob(f"{name}.md"): + if found_md.name != "SKILL.md": + skill_md = found_md + break + if skill_md: + break + + if not skill_md or not skill_md.exists(): + available = [s["name"] for s in _find_all_skills()[:20]] + return json.dumps( + { + "success": False, + "error": f"Skill '{name}' not found.", + "available_skills": available, + "hint": "Use skills_list to see all available skills", + }, + ensure_ascii=False, + ) + + # Read the file once — reused for platform check and main content below + try: + content = skill_md.read_text(encoding="utf-8") + except Exception as e: + return json.dumps( + { + "success": False, + "error": f"Failed to read skill '{name}': {e}", + }, + ensure_ascii=False, + ) + + # Security: warn if skill is loaded from outside trusted directories + # (local skills dir + configured external_dirs are all trusted) + _outside_skills_dir = True + _trusted_dirs = [SKILLS_DIR.resolve()] + try: + _trusted_dirs.extend(d.resolve() for d in all_dirs[1:]) + except Exception: + pass + for _td in _trusted_dirs: + try: + skill_md.resolve().relative_to(_td) + _outside_skills_dir = False + break + except ValueError: + continue + + # Security: detect common prompt injection patterns + _INJECTION_PATTERNS = [ + "ignore previous instructions", + "ignore all previous", + "you are now", + "disregard your", + "forget your instructions", + "new instructions:", + "system prompt:", + "<system>", + "]]>", + ] + _content_lower = content.lower() + _injection_detected = any(p in _content_lower for p in _INJECTION_PATTERNS) + + if _outside_skills_dir or _injection_detected: + _warnings = [] + if _outside_skills_dir: + _warnings.append(f"skill file is outside the trusted skills directory (~/.hermes/skills/): {skill_md}") + if _injection_detected: + _warnings.append("skill content contains patterns that may indicate prompt injection") + import logging as _logging + _logging.getLogger(__name__).warning("Skill security warning for '%s': %s", name, "; ".join(_warnings)) + + parsed_frontmatter: Dict[str, Any] = {} + try: + parsed_frontmatter, _ = _parse_frontmatter(content) + except Exception: + parsed_frontmatter = {} + + if not skill_matches_platform(parsed_frontmatter): + return json.dumps( + { + "success": False, + "error": f"Skill '{name}' is not supported on this platform.", + "readiness_status": SkillReadinessStatus.UNSUPPORTED.value, + }, + ensure_ascii=False, + ) + + # Check if the skill is disabled by the user + resolved_name = parsed_frontmatter.get("name", skill_md.parent.name) + if _is_skill_disabled(resolved_name): + return json.dumps( + { + "success": False, + "error": ( + f"Skill '{resolved_name}' is disabled. " + "Enable it with `hermes skills` or inspect the files directly on disk." + ), + }, + ensure_ascii=False, + ) + + # If a specific file path is requested, read that instead + if file_path and skill_dir: + from tools.path_security import validate_within_dir, has_traversal_component + + # Security: Prevent path traversal attacks + if has_traversal_component(file_path): + return json.dumps( + { + "success": False, + "error": "Path traversal ('..') is not allowed.", + "hint": "Use a relative path within the skill directory", + }, + ensure_ascii=False, + ) + + target_file = skill_dir / file_path + + # Security: Verify resolved path is still within skill directory + traversal_error = validate_within_dir(target_file, skill_dir) + if traversal_error: + return json.dumps( + { + "success": False, + "error": traversal_error, + "hint": "Use a relative path within the skill directory", + }, + ensure_ascii=False, + ) + if not target_file.exists(): + # List available files in the skill directory, organized by type + available_files = { + "references": [], + "templates": [], + "assets": [], + "scripts": [], + "other": [], + } + + # Scan for all readable files + for f in skill_dir.rglob("*"): + if f.is_file() and f.name != "SKILL.md": + rel = str(f.relative_to(skill_dir)) + if rel.startswith("references/"): + available_files["references"].append(rel) + elif rel.startswith("templates/"): + available_files["templates"].append(rel) + elif rel.startswith("assets/"): + available_files["assets"].append(rel) + elif rel.startswith("scripts/"): + available_files["scripts"].append(rel) + elif f.suffix in [ + ".md", + ".py", + ".yaml", + ".yml", + ".json", + ".tex", + ".sh", + ]: + available_files["other"].append(rel) + + # Remove empty categories + available_files = {k: v for k, v in available_files.items() if v} + + return json.dumps( + { + "success": False, + "error": f"File '{file_path}' not found in skill '{name}'.", + "available_files": available_files, + "hint": "Use one of the available file paths listed above", + }, + ensure_ascii=False, + ) + + # Read the file content + try: + content = target_file.read_text(encoding="utf-8") + except UnicodeDecodeError: + # Binary file - return info about it instead + return json.dumps( + { + "success": True, + "name": name, + "file": file_path, + "content": f"[Binary file: {target_file.name}, size: {target_file.stat().st_size} bytes]", + "is_binary": True, + }, + ensure_ascii=False, + ) + + return json.dumps( + { + "success": True, + "name": name, + "file": file_path, + "content": content, + "file_type": target_file.suffix, + }, + ensure_ascii=False, + ) + + # Reuse the parse from the platform check above + frontmatter = parsed_frontmatter + + # Get reference, template, asset, and script files if this is a directory-based skill + reference_files = [] + template_files = [] + asset_files = [] + script_files = [] + + if skill_dir: + references_dir = skill_dir / "references" + if references_dir.exists(): + reference_files = [ + str(f.relative_to(skill_dir)) for f in references_dir.glob("*.md") + ] + + templates_dir = skill_dir / "templates" + if templates_dir.exists(): + for ext in [ + "*.md", + "*.py", + "*.yaml", + "*.yml", + "*.json", + "*.tex", + "*.sh", + ]: + template_files.extend( + [ + str(f.relative_to(skill_dir)) + for f in templates_dir.rglob(ext) + ] + ) + + # assets/ — agentskills.io standard directory for supplementary files + assets_dir = skill_dir / "assets" + if assets_dir.exists(): + for f in assets_dir.rglob("*"): + if f.is_file(): + asset_files.append(str(f.relative_to(skill_dir))) + + scripts_dir = skill_dir / "scripts" + if scripts_dir.exists(): + for ext in ["*.py", "*.sh", "*.bash", "*.js", "*.ts", "*.rb"]: + script_files.extend( + [str(f.relative_to(skill_dir)) for f in scripts_dir.glob(ext)] + ) + + # Read tags/related_skills with backward compat: + # Check metadata.hermes.* first (agentskills.io convention), fall back to top-level + hermes_meta = {} + metadata = frontmatter.get("metadata") + if isinstance(metadata, dict): + hermes_meta = metadata.get("hermes", {}) or {} + + tags = _parse_tags(hermes_meta.get("tags") or frontmatter.get("tags", "")) + related_skills = _parse_tags( + hermes_meta.get("related_skills") or frontmatter.get("related_skills", "") + ) + + # Build linked files structure for clear discovery + linked_files = {} + if reference_files: + linked_files["references"] = reference_files + if template_files: + linked_files["templates"] = template_files + if asset_files: + linked_files["assets"] = asset_files + if script_files: + linked_files["scripts"] = script_files + + try: + rel_path = str(skill_md.relative_to(SKILLS_DIR)) + except ValueError: + # External skill — use path relative to the skill's own parent dir + rel_path = str(skill_md.relative_to(skill_md.parent.parent)) if skill_md.parent.parent else skill_md.name + skill_name = frontmatter.get( + "name", skill_md.stem if not skill_dir else skill_dir.name + ) + legacy_env_vars, _ = _collect_prerequisite_values(frontmatter) + required_env_vars = _get_required_environment_variables( + frontmatter, legacy_env_vars + ) + backend = _get_terminal_backend_name() + env_snapshot = load_env() + missing_required_env_vars = [ + e + for e in required_env_vars + if not e.get("optional") + and not _is_env_var_persisted(e["name"], env_snapshot) + ] + capture_result = _capture_required_environment_variables( + skill_name, + missing_required_env_vars, + ) + if missing_required_env_vars: + env_snapshot = load_env() + remaining_missing_required_envs = _remaining_required_environment_names( + required_env_vars, + capture_result, + env_snapshot=env_snapshot, + ) + setup_needed = bool(remaining_missing_required_envs) + + # Register available skill env vars so they pass through to sandboxed + # execution environments (execute_code, terminal). Only vars that are + # actually set get registered — missing ones are reported as setup_needed. + available_env_names = [ + e["name"] + for e in required_env_vars + if e["name"] not in remaining_missing_required_envs + ] + if available_env_names: + try: + from tools.env_passthrough import register_env_passthrough + + register_env_passthrough(available_env_names) + except Exception: + logger.debug( + "Could not register env passthrough for skill %s", + skill_name, + exc_info=True, + ) + + # Register credential files for mounting into remote sandboxes + # (Modal, Docker). Files that exist on the host are registered; + # missing ones are added to the setup_needed indicators. + required_cred_files_raw = frontmatter.get("required_credential_files", []) + if not isinstance(required_cred_files_raw, list): + required_cred_files_raw = [] + missing_cred_files: list = [] + if required_cred_files_raw: + try: + from tools.credential_files import register_credential_files + + missing_cred_files = register_credential_files(required_cred_files_raw) + if missing_cred_files: + setup_needed = True + except Exception: + logger.debug( + "Could not register credential files for skill %s", + skill_name, + exc_info=True, + ) + + result = { + "success": True, + "name": skill_name, + "description": frontmatter.get("description", ""), + "tags": tags, + "related_skills": related_skills, + "content": content, + "path": rel_path, + "linked_files": linked_files if linked_files else None, + "usage_hint": "To view linked files, call skill_view(name, file_path) where file_path is e.g. 'references/api.md' or 'assets/config.yaml'" + if linked_files + else None, + "required_environment_variables": required_env_vars, + "required_commands": [], + "missing_required_environment_variables": remaining_missing_required_envs, + "missing_credential_files": missing_cred_files, + "missing_required_commands": [], + "setup_needed": setup_needed, + "setup_skipped": capture_result["setup_skipped"], + "readiness_status": SkillReadinessStatus.SETUP_NEEDED.value + if setup_needed + else SkillReadinessStatus.AVAILABLE.value, + } + + setup_help = next((e["help"] for e in required_env_vars if e.get("help")), None) + if setup_help: + result["setup_help"] = setup_help + + if capture_result["gateway_setup_hint"]: + result["gateway_setup_hint"] = capture_result["gateway_setup_hint"] + + if setup_needed: + missing_items = [ + f"env ${env_name}" for env_name in remaining_missing_required_envs + ] + [ + f"file {path}" for path in missing_cred_files + ] + setup_note = _build_setup_note( + SkillReadinessStatus.SETUP_NEEDED, + missing_items, + setup_help, + ) + if backend in _REMOTE_ENV_BACKENDS and setup_note: + setup_note = f"{setup_note} {backend.upper()}-backed skills need these requirements available inside the remote environment as well." + if setup_note: + result["setup_note"] = setup_note + + # Surface agentskills.io optional fields when present + if frontmatter.get("compatibility"): + result["compatibility"] = frontmatter["compatibility"] + if isinstance(metadata, dict): + result["metadata"] = metadata + + return json.dumps(result, ensure_ascii=False) + + except Exception as e: + return tool_error(str(e), success=False) + + + + +if __name__ == "__main__": + """Test the skills tool""" + print("🎯 Skills Tool Test") + print("=" * 60) + + # Test listing skills + print("\n📋 Listing all skills:") + result = json.loads(skills_list()) + if result["success"]: + print( + f"Found {result['count']} skills in {len(result.get('categories', []))} categories" + ) + print(f"Categories: {result.get('categories', [])}") + print("\nFirst 10 skills:") + for skill in result["skills"][:10]: + cat = f"[{skill['category']}] " if skill.get("category") else "" + print(f" • {cat}{skill['name']}: {skill['description'][:60]}...") + else: + print(f"Error: {result['error']}") + + # Test viewing a skill + print("\n📖 Viewing skill 'axolotl':") + result = json.loads(skill_view("axolotl")) + if result["success"]: + print(f"Name: {result['name']}") + print(f"Description: {result.get('description', 'N/A')[:100]}...") + print(f"Content length: {len(result['content'])} chars") + if result.get("linked_files"): + print(f"Linked files: {result['linked_files']}") + else: + print(f"Error: {result['error']}") + + # Test viewing a reference file + print("\n📄 Viewing reference file 'axolotl/references/dataset-formats.md':") + result = json.loads(skill_view("axolotl", "references/dataset-formats.md")) + if result["success"]: + print(f"File: {result['file']}") + print(f"Content length: {len(result['content'])} chars") + print(f"Preview: {result['content'][:150]}...") + else: + print(f"Error: {result['error']}") + + +# --------------------------------------------------------------------------- +# Registry +# --------------------------------------------------------------------------- + +SKILLS_LIST_SCHEMA = { + "name": "skills_list", + "description": "List available skills (name + description). Use skill_view(name) to load full content.", + "parameters": { + "type": "object", + "properties": { + "category": { + "type": "string", + "description": "Optional category filter to narrow results", + } + }, + "required": [], + }, +} + +SKILL_VIEW_SCHEMA = { + "name": "skill_view", + "description": "Skills allow for loading information about specific tasks and workflows, as well as scripts and templates. Load a skill's full content or access its linked files (references, templates, scripts). First call returns SKILL.md content plus a 'linked_files' dict showing available references/templates/scripts. To access those, call again with file_path parameter.", + "parameters": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The skill name (use skills_list to see available skills)", + }, + "file_path": { + "type": "string", + "description": "OPTIONAL: Path to a linked file within the skill (e.g., 'references/api.md', 'templates/config.yaml', 'scripts/validate.py'). Omit to get the main SKILL.md content.", + }, + }, + "required": ["name"], + }, +} + +registry.register( + name="skills_list", + toolset="skills", + schema=SKILLS_LIST_SCHEMA, + handler=lambda args, **kw: skills_list( + category=args.get("category"), task_id=kw.get("task_id") + ), + check_fn=check_skills_requirements, + emoji="📚", +) +registry.register( + name="skill_view", + toolset="skills", + schema=SKILL_VIEW_SCHEMA, + handler=lambda args, **kw: skill_view( + args.get("name", ""), file_path=args.get("file_path"), task_id=kw.get("task_id") + ), + check_fn=check_skills_requirements, + emoji="📚", +) diff --git a/mindcli/_vendor/tools/tencent_meeting_tool.py b/mindcli/_vendor/tools/tencent_meeting_tool.py new file mode 100644 index 0000000..c37e328 --- /dev/null +++ b/mindcli/_vendor/tools/tencent_meeting_tool.py @@ -0,0 +1,301 @@ +""" +腾讯会议连接器工具 (tencent_meeting_tool.py) — v2 + +重要设计： + ┌─────────────────────────────────────────────────────┐ + │ 绑定流程：侧边栏 inline UI（链接 + Token 粘贴） │ + │ 调用流程：SKILL.md + Agent 对话 │ + └─────────────────────────────────────────────────────┘ + 两条路径完全隔离，互不依赖。 + +Token 存储（per-user JSON，优先于全局 env var）： + /opt/apps/mindos-next/backend/data/tencent_meeting_tokens.json + 格式：{ "userId": "HpLzd..." } + +注意：腾讯会议目前仅支持「个人账号」认证。 + Token 获取地址：https://meeting.tencent.com/ai-skill.html +""" + +import json +import logging +import os +import subprocess +from pathlib import Path +from typing import Any, Dict, Optional + +from tools.registry import registry, tool_error, tool_result + +logger = logging.getLogger(__name__) + +# ── 腾讯会议脚本路径（候选列表，取第一个存在的）── +_SCRIPT_CANDIDATES = [ + Path("/root/hermess/skills/tencent-meeting/scripts/tencent_meeting.py"), + Path("/Users/lidongfang/Downloads/Coding/hermess/skills/tencent-meeting/scripts/tencent_meeting.py"), +] + +# ── Per-user Token 存储（wiki/{userId}/.config/tencent_meeting.json） ── +from tools._user_config import user_config_read, user_config_write, user_config_delete + +# ── 腾讯会议 Token 获取地址（仅个人账号） ── +TOKEN_OBTAIN_URL = "https://meeting.tencent.com/ai-skill.html" + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# Token 存取（per-user） +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +def get_user_token(user_id: str) -> str: + """ + 获取指定用户的 Token。 + 优先：per-user 存储 → 兜底：全局 env var（向后兼容） + """ + config = user_config_read(user_id, "tencent_meeting") + token = config.get("token", "").strip() + if token: + return token + # 兜底：全局 env（管理员配置场景） + return os.environ.get("TENCENT_MEETING_TOKEN", "").strip() + + +def set_user_token(user_id: str, token: str) -> None: + """保存或清除指定用户的 Token。token 为空则删除条目。""" + token = token.strip() + if token: + user_config_write(user_id, "tencent_meeting", {"token": token}) + else: + user_config_delete(user_id, "tencent_meeting") + + +def has_user_token(user_id: str) -> bool: + return bool(get_user_token(user_id)) + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# 脚本路径 & 可用性检查 +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +def _get_script_path() -> Optional[Path]: + for p in _SCRIPT_CANDIDATES: + if p.exists(): + return p + return None + + +def _check_tencent_meeting() -> bool: + """可用性检查：脚本存在即可（Token 在 handler 中按用户检查）。""" + return bool(_get_script_path()) + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# 子进程抽象层（同步，线程安全） +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +def _run_tencent_meeting( + tool_name: str, + arguments: Dict[str, Any], + user_id: str = "", + timeout: int = 30, +) -> tuple: + """ + 同步调用 tencent_meeting.py tools/call。 + user_id 用于查找 per-user Token。 + 返回 (stdout: str, stderr: str, returncode: int) + """ + script = _get_script_path() + if not script: + return "", "找不到 tencent_meeting.py 脚本，请检查部署配置", -2 + + token = get_user_token(user_id) if user_id else os.environ.get("TENCENT_MEETING_TOKEN", "") + if not token: + return "", "腾讯会议 Token 未配置。请在侧边栏绑定账号。", -4 + + arguments.setdefault("_client_info", { + "os": "linux", + "agent": "mindos", + "model": "gemini", + }) + + params_json = json.dumps({"name": tool_name, "arguments": arguments}, ensure_ascii=False) + cmd = ["python3", str(script), "tools/call", params_json] + logger.info("[TencentMeetingTool] exec: tools/call %s (user=%s)", tool_name, user_id[:8] if user_id else "global") + + env = os.environ.copy() + env["TENCENT_MEETING_TOKEN"] = token # 注入到子进程 + + try: + r = subprocess.run( + cmd, + capture_output=True, + timeout=timeout, + text=True, + env=env, + cwd=str(script.parent), + ) + return r.stdout.strip(), r.stderr.strip(), r.returncode + except subprocess.TimeoutExpired: + return "", f"命令超时（{timeout}s）", -1 + except FileNotFoundError: + return "", "python3 未找到", -3 + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# ① tencent_meeting_list_profiles +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +def _tencent_meeting_list_profiles_handler(args: dict, **kwargs) -> str: + user_id = str(args.get("user_id", "")).strip() + if not user_id: + return tool_error("user_id 参数必填") + + token_exists = has_user_token(user_id) + + if not token_exists: + return tool_result( + success=True, + profiles=[], + count=0, + tokenConfigured=False, + tokenObtainUrl=TOKEN_OBTAIN_URL, + notice="腾讯会议目前仅支持个人账号认证。请前往上述链接获取 Token 并在侧边栏绑定。", + ) + + script = _get_script_path() + if not script: + return tool_result( + success=True, + profiles=[], + count=0, + tokenConfigured=True, + message="腾讯会议脚本未找到，请检查服务器部署。", + ) + + # 用 convert_timestamp 验证连通性 + stdout, stderr, rc = _run_tencent_meeting("convert_timestamp", {}, user_id=user_id, timeout=15) + status = "connected" if rc == 0 else "error" + message = "腾讯会议已连接。" if rc == 0 else f"连接异常：{(stderr or stdout)[:120]}" + + profiles = [{ + "profileName": f"{user_id[:12]}_tencent", + "label": "腾讯会议", + "status": status, + "tokenConfigured": True, + "notice": "腾讯会议目前仅支持个人账号认证。", + }] + + return tool_result( + success=True, + profiles=profiles, + count=len(profiles), + tokenConfigured=True, + message=message, + ) + + +registry.register( + name="tencent_meeting_list_profiles", + toolset="connectors", + description="检查腾讯会议连接状态，返回账号信息。", + emoji="📋", + check_fn=_check_tencent_meeting, + handler=_tencent_meeting_list_profiles_handler, + schema={ + "name": "tencent_meeting_list_profiles", + "description": "检查腾讯会议是否已连接，返回连接状态。", + "parameters": { + "type": "object", + "properties": { + "user_id": {"type": "string", "description": "MINDOS_USER_ID"}, + }, + "required": ["user_id"], + }, + }, +) + + +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# ② tencent_meeting_query（白名单操作） +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +_ALLOWED_TOOLS = { + "convert_timestamp", + "schedule_meeting", + "get_meeting_by_code", + "get_meeting", + "get_user_meetings", + "get_user_ended_meetings", + "get_smart_minutes", + "get_records_list", +} + + +def _tencent_meeting_query_handler(args: dict, **kwargs) -> str: + user_id = str(args.get("user_id", "")).strip() + tool_name = str(args.get("tool_name", "")).strip() + + if not user_id: + return tool_error("user_id 参数必填") + if not tool_name: + return tool_error("tool_name 参数必填") + if tool_name not in _ALLOWED_TOOLS: + return tool_error( + f"不支持的工具：{tool_name}。可选：{', '.join(sorted(_ALLOWED_TOOLS))}" + ) + if not has_user_token(user_id): + return tool_error( + f"腾讯会议 Token 未配置。请前往 {TOKEN_OBTAIN_URL} 获取 Token，" + "并在侧边栏「腾讯会议」处绑定账号。" + ) + + arguments = args.get("arguments", {}) + if not isinstance(arguments, dict): + return tool_error("arguments 必须是 JSON 对象") + + stdout, stderr, rc = _run_tencent_meeting(tool_name, arguments, user_id=user_id, timeout=30) + + if rc != 0: + return tool_error(f"调用失败（exit {rc}）：{(stderr or stdout)[:300]}") + if not stdout: + return tool_error(f"无输出。stderr: {stderr[:200]}") + + try: + data = json.loads(stdout) + return tool_result(success=True, data=data) + except (json.JSONDecodeError, ValueError): + return tool_result(success=True, output=stdout[:3000]) + + +registry.register( + name="tencent_meeting_query", + toolset="connectors", + description="执行腾讯会议数据查询（会议列表/纪要/录制等）。", + emoji="📹", + check_fn=_check_tencent_meeting, + handler=_tencent_meeting_query_handler, + schema={ + "name": "tencent_meeting_query", + "description": ( + "调用腾讯会议 MCP 工具。需先在侧边栏完成 Token 绑定。\n" + "示例：\n" + " 查当前时间: tool_name=convert_timestamp, arguments={}\n" + " 查未来会议: tool_name=get_user_meetings, arguments={\"pos\": <unix_ts>}\n" + " 查 AI 纪要: tool_name=get_smart_minutes, arguments={\"meeting_id\": \"xxx\"}\n" + " 预约会议: tool_name=schedule_meeting, arguments={\"subject\":\"xx\",\"start_time\":\"...\",\"end_time\":\"...\"}\n" + ), + "parameters": { + "type": "object", + "properties": { + "user_id": {"type": "string", "description": "MINDOS_USER_ID"}, + "tool_name": { + "type": "string", + "description": "腾讯会议工具名", + "enum": sorted(_ALLOWED_TOOLS), + }, + "arguments": { + "type": "object", + "description": "工具参数（_client_info 由工具自动注入，不需要传）", + }, + }, + "required": ["user_id", "tool_name"], + }, + }, +) diff --git a/mindcli/_vendor/tools/terminal_tool.py b/mindcli/_vendor/tools/terminal_tool.py new file mode 100644 index 0000000..65f84e1 --- /dev/null +++ b/mindcli/_vendor/tools/terminal_tool.py @@ -0,0 +1,1749 @@ +#!/usr/bin/env python3 +""" +Terminal Tool Module + +A terminal tool that executes commands in local, Docker, Modal, SSH, Singularity, and Daytona environments. +Supports local execution, containerized backends, and Modal cloud sandboxes, including managed gateway mode. + +Environment Selection (via TERMINAL_ENV environment variable): +- "local": Execute directly on the host machine (default, fastest) +- "docker": Execute in Docker containers (isolated, requires Docker) +- "modal": Execute in Modal cloud sandboxes (direct Modal or managed gateway) + +Features: +- Multiple execution backends (local, docker, modal) +- Background task support +- VM/container lifecycle management +- Automatic cleanup after inactivity + +Cloud sandbox note: +- Persistent filesystems preserve working state across sandbox recreation +- Persistent filesystems do NOT guarantee the same live sandbox or long-running processes survive cleanup, idle reaping, or Hermes exit + +Usage: + from terminal_tool import terminal_tool + + # Execute a simple command + result = terminal_tool("ls -la") + + # Execute in background + result = terminal_tool("python server.py", background=True) +""" + +import importlib.util +import json +import logging +import os +import platform +import re +import time +import threading +import atexit +import shutil +import subprocess +from pathlib import Path +from typing import Optional, Dict, Any, List + +logger = logging.getLogger(__name__) + + +# --------------------------------------------------------------------------- +# Global interrupt event: set by the agent when a user interrupt arrives. +# The terminal tool polls this during command execution so it can kill +# long-running subprocesses immediately instead of blocking until timeout. +# --------------------------------------------------------------------------- +from tools.interrupt import is_interrupted, _interrupt_event # noqa: F401 — re-exported +# display_hermes_home imported lazily at call site (stale-module safety during hermes update) + + + + +# ============================================================================= +# Custom Singularity Environment with more space +# ============================================================================= + +# Singularity helpers (scratch dir, SIF cache) now live in tools/environments/singularity.py +from tools.environments.singularity import _get_scratch_dir +from tools.tool_backend_helpers import ( + coerce_modal_mode, + has_direct_modal_credentials, + managed_nous_tools_enabled, + resolve_modal_backend_state, +) + + +# Hard cap on foreground timeout; override via TERMINAL_MAX_FOREGROUND_TIMEOUT env var. +FOREGROUND_MAX_TIMEOUT = int(os.getenv("TERMINAL_MAX_FOREGROUND_TIMEOUT", "600")) + +# Disk usage warning threshold (in GB) +DISK_USAGE_WARNING_THRESHOLD_GB = float(os.getenv("TERMINAL_DISK_WARNING_GB", "500")) + + +def _check_disk_usage_warning(): + """Check if total disk usage exceeds warning threshold.""" + try: + scratch_dir = _get_scratch_dir() + + # Get total size of hermes directories + total_bytes = 0 + import glob + for path in glob.glob(str(scratch_dir / "hermes-*")): + for f in Path(path).rglob('*'): + if f.is_file(): + try: + total_bytes += f.stat().st_size + except OSError as e: + logger.debug("Could not stat file %s: %s", f, e) + + total_gb = total_bytes / (1024 ** 3) + + if total_gb > DISK_USAGE_WARNING_THRESHOLD_GB: + logger.warning("Disk usage (%.1fGB) exceeds threshold (%.0fGB). Consider running cleanup_all_environments().", + total_gb, DISK_USAGE_WARNING_THRESHOLD_GB) + return True + + return False + except Exception as e: + logger.debug("Disk usage warning check failed: %s", e, exc_info=True) + return False + + +# Session-cached sudo password (persists until CLI exits) +_cached_sudo_password: str = "" + +# Optional UI callbacks for interactive prompts. When set, these are called +# instead of the default /dev/tty or input() readers. The CLI registers these +# so prompts route through prompt_toolkit's event loop. +# _sudo_password_callback() -> str (return password or "" to skip) +# _approval_callback(command, description) -> str ("once"/"session"/"always"/"deny") +_sudo_password_callback = None +_approval_callback = None + + +def set_sudo_password_callback(cb): + """Register a callback for sudo password prompts (used by CLI).""" + global _sudo_password_callback + _sudo_password_callback = cb + + +def set_approval_callback(cb): + """Register a callback for dangerous command approval prompts (used by CLI).""" + global _approval_callback + _approval_callback = cb + +# ============================================================================= +# Dangerous Command Approval System +# ============================================================================= + +# Dangerous command detection + approval now consolidated in tools/approval.py +from tools.approval import ( + check_all_command_guards as _check_all_guards_impl, +) + + +def _check_all_guards(command: str, env_type: str) -> dict: + """Delegate to consolidated guard (tirith + dangerous cmd) with CLI callback.""" + return _check_all_guards_impl(command, env_type, + approval_callback=_approval_callback) + + +# Allowlist: characters that can legitimately appear in directory paths. +# Covers alphanumeric, path separators, tilde, dot, hyphen, underscore, space, +# plus, at, equals, and comma. Everything else is rejected. +_WORKDIR_SAFE_RE = re.compile(r'^[A-Za-z0-9/_\-.~ +@=,]+$') + + +def _validate_workdir(workdir: str) -> str | None: + """Reject workdir values that don't look like a filesystem path. + + Uses an allowlist of safe characters rather than a deny-list, so novel + shell metacharacters can't slip through. + + Returns None if safe, or an error message string if dangerous. + """ + if not workdir: + return None + if not _WORKDIR_SAFE_RE.match(workdir): + # Find the first offending character for a helpful message. + for ch in workdir: + if not _WORKDIR_SAFE_RE.match(ch): + return ( + f"Blocked: workdir contains disallowed character {repr(ch)}. " + "Use a simple filesystem path without shell metacharacters." + ) + return "Blocked: workdir contains disallowed characters." + return None + + +def _handle_sudo_failure(output: str, env_type: str) -> str: + """ + Check for sudo failure and add helpful message for messaging contexts. + + Returns enhanced output if sudo failed in messaging context, else original. + """ + is_gateway = os.getenv("HERMES_GATEWAY_SESSION") + + if not is_gateway: + return output + + # Check for sudo failure indicators + sudo_failures = [ + "sudo: a password is required", + "sudo: no tty present", + "sudo: a terminal is required", + ] + + for failure in sudo_failures: + if failure in output: + from hermes_constants import display_hermes_home as _dhh + return output + f"\n\n💡 Tip: To enable sudo over messaging, add SUDO_PASSWORD to {_dhh()}/.env on the agent machine." + + return output + + +def _prompt_for_sudo_password(timeout_seconds: int = 45) -> str: + """ + Prompt user for sudo password with timeout. + + Returns the password if entered, or empty string if: + - User presses Enter without input (skip) + - Timeout expires (45s default) + - Any error occurs + + Only works in interactive mode (HERMES_INTERACTIVE=1). + If a _sudo_password_callback is registered (by the CLI), delegates to it + so the prompt integrates with prompt_toolkit's UI. Otherwise reads + directly from /dev/tty with echo disabled. + """ + import sys + import time as time_module + + # Use the registered callback when available (prompt_toolkit-compatible) + if _sudo_password_callback is not None: + try: + return _sudo_password_callback() or "" + except Exception: + return "" + + result = {"password": None, "done": False} + + def read_password_thread(): + """Read password with echo disabled. Uses msvcrt on Windows, /dev/tty on Unix.""" + tty_fd = None + old_attrs = None + try: + if platform.system() == "Windows": + import msvcrt + chars = [] + while True: + c = msvcrt.getwch() + if c in ("\r", "\n"): + break + if c == "\x03": + raise KeyboardInterrupt + chars.append(c) + result["password"] = "".join(chars) + else: + import termios + tty_fd = os.open("/dev/tty", os.O_RDONLY) + old_attrs = termios.tcgetattr(tty_fd) + new_attrs = termios.tcgetattr(tty_fd) + new_attrs[3] = new_attrs[3] & ~termios.ECHO + termios.tcsetattr(tty_fd, termios.TCSAFLUSH, new_attrs) + chars = [] + while True: + b = os.read(tty_fd, 1) + if not b or b in (b"\n", b"\r"): + break + chars.append(b) + result["password"] = b"".join(chars).decode("utf-8", errors="replace") + except (EOFError, KeyboardInterrupt, OSError): + result["password"] = "" + except Exception: + result["password"] = "" + finally: + if tty_fd is not None and old_attrs is not None: + try: + import termios as _termios + _termios.tcsetattr(tty_fd, _termios.TCSAFLUSH, old_attrs) + except Exception as e: + logger.debug("Failed to restore terminal attributes: %s", e) + if tty_fd is not None: + try: + os.close(tty_fd) + except Exception as e: + logger.debug("Failed to close tty fd: %s", e) + result["done"] = True + + try: + os.environ["HERMES_SPINNER_PAUSE"] = "1" + time_module.sleep(0.2) + + print() + print("┌" + "─" * 58 + "┐") + print("│ 🔐 SUDO PASSWORD REQUIRED" + " " * 30 + "│") + print("├" + "─" * 58 + "┤") + print("│ Enter password below (input is hidden), or: │") + print("│ • Press Enter to skip (command fails gracefully) │") + print(f"│ • Wait {timeout_seconds}s to auto-skip" + " " * 27 + "│") + print("└" + "─" * 58 + "┘") + print() + print(" Password (hidden): ", end="", flush=True) + + password_thread = threading.Thread(target=read_password_thread, daemon=True) + password_thread.start() + password_thread.join(timeout=timeout_seconds) + + if result["done"]: + password = result["password"] or "" + print() # newline after hidden input + if password: + print(" ✓ Password received (cached for this session)") + else: + print(" ⏭ Skipped - continuing without sudo") + print() + sys.stdout.flush() + return password + else: + print("\n ⏱ Timeout - continuing without sudo") + print(" (Press Enter to dismiss)") + print() + sys.stdout.flush() + return "" + + except (EOFError, KeyboardInterrupt): + print() + print(" ⏭ Cancelled - continuing without sudo") + print() + sys.stdout.flush() + return "" + except Exception as e: + print(f"\n [sudo prompt error: {e}] - continuing without sudo\n") + sys.stdout.flush() + return "" + finally: + if "HERMES_SPINNER_PAUSE" in os.environ: + del os.environ["HERMES_SPINNER_PAUSE"] + +def _safe_command_preview(command: Any, limit: int = 200) -> str: + """Return a log-safe preview for possibly-invalid command values.""" + if command is None: + return "<None>" + if isinstance(command, str): + return command[:limit] + try: + return repr(command)[:limit] + except Exception: + return f"<{type(command).__name__}>" + +def _looks_like_env_assignment(token: str) -> bool: + """Return True when *token* is a leading shell environment assignment.""" + if "=" not in token or token.startswith("="): + return False + name, _value = token.split("=", 1) + return bool(re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", name)) + + +def _read_shell_token(command: str, start: int) -> tuple[str, int]: + """Read one shell token, preserving quotes/escapes, starting at *start*.""" + i = start + n = len(command) + + while i < n: + ch = command[i] + if ch.isspace() or ch in ";|&()": + break + if ch == "'": + i += 1 + while i < n and command[i] != "'": + i += 1 + if i < n: + i += 1 + continue + if ch == '"': + i += 1 + while i < n: + inner = command[i] + if inner == "\\" and i + 1 < n: + i += 2 + continue + if inner == '"': + i += 1 + break + i += 1 + continue + if ch == "\\" and i + 1 < n: + i += 2 + continue + i += 1 + + return command[start:i], i + + +def _rewrite_real_sudo_invocations(command: str) -> tuple[str, bool]: + """Rewrite only real unquoted sudo command words, not plain text mentions.""" + out: list[str] = [] + i = 0 + n = len(command) + command_start = True + found = False + + while i < n: + ch = command[i] + + if ch.isspace(): + out.append(ch) + if ch == "\n": + command_start = True + i += 1 + continue + + if ch == "#" and command_start: + comment_end = command.find("\n", i) + if comment_end == -1: + out.append(command[i:]) + break + out.append(command[i:comment_end]) + i = comment_end + continue + + if command.startswith("&&", i) or command.startswith("||", i) or command.startswith(";;", i): + out.append(command[i:i + 2]) + i += 2 + command_start = True + continue + + if ch in ";|&(": + out.append(ch) + i += 1 + command_start = True + continue + + if ch == ")": + out.append(ch) + i += 1 + command_start = False + continue + + token, next_i = _read_shell_token(command, i) + if command_start and token == "sudo": + out.append("sudo -S -p ''") + found = True + else: + out.append(token) + + if command_start and _looks_like_env_assignment(token): + command_start = True + else: + command_start = False + i = next_i + + return "".join(out), found + + +def _transform_sudo_command(command: str | None) -> tuple[str | None, str | None]: + """ + Transform sudo commands to use -S flag if SUDO_PASSWORD is available. + + This is a shared helper used by all execution environments to provide + consistent sudo handling across local, SSH, and container environments. + + Returns: + (transformed_command, sudo_stdin) where: + - transformed_command has every bare ``sudo`` replaced with + ``sudo -S -p ''`` so sudo reads its password from stdin. + - sudo_stdin is the password string with a trailing newline that the + caller must prepend to the process's stdin stream. sudo -S reads + exactly one line (the password) and passes the rest of stdin to the + child command, so prepending is safe even when the caller also has + its own stdin_data to pipe. + - If no password is available, sudo_stdin is None and the command is + returned unchanged so it fails gracefully with + "sudo: a password is required". + + Callers that drive a subprocess directly (local, ssh, docker, singularity) + should prepend sudo_stdin to their stdin_data and pass the merged bytes to + Popen's stdin pipe. + + Callers that cannot pipe subprocess stdin (modal, daytona) must embed the + password in the command string themselves; see their execute() methods for + how they handle the non-None sudo_stdin case. + + If SUDO_PASSWORD is not set and in interactive mode (HERMES_INTERACTIVE=1): + Prompts user for password with 45s timeout, caches for session. + + If SUDO_PASSWORD is not set and NOT interactive: + Command runs as-is (fails gracefully with "sudo: a password is required"). + """ + global _cached_sudo_password + + if command is None: + return None, None + transformed, has_real_sudo = _rewrite_real_sudo_invocations(command) + if not has_real_sudo: + return command, None + + has_configured_password = "SUDO_PASSWORD" in os.environ + sudo_password = os.environ.get("SUDO_PASSWORD", "") if has_configured_password else _cached_sudo_password + + if not has_configured_password and not sudo_password and os.getenv("HERMES_INTERACTIVE"): + sudo_password = _prompt_for_sudo_password(timeout_seconds=45) + if sudo_password: + _cached_sudo_password = sudo_password + + if has_configured_password or sudo_password: + # Trailing newline is required: sudo -S reads one line for the password. + return transformed, sudo_password + "\n" + + return command, None + + +# Environment classes now live in tools/environments/ +from tools.environments.local import LocalEnvironment as _LocalEnvironment +from tools.environments.singularity import SingularityEnvironment as _SingularityEnvironment +from tools.environments.ssh import SSHEnvironment as _SSHEnvironment +from tools.environments.docker import DockerEnvironment as _DockerEnvironment +from tools.environments.modal import ModalEnvironment as _ModalEnvironment +from tools.environments.managed_modal import ManagedModalEnvironment as _ManagedModalEnvironment +from tools.managed_tool_gateway import is_managed_tool_gateway_ready + + +# Tool description for LLM +TERMINAL_TOOL_DESCRIPTION = """Execute shell commands on a Linux environment. Filesystem usually persists between calls. + +Do NOT use cat/head/tail to read files — use read_file instead. +Do NOT use grep/rg/find to search — use search_files instead. +Do NOT use ls to list directories — use search_files(target='files') instead. +Do NOT use sed/awk to edit files — use patch instead. +Do NOT use echo/cat heredoc to create files — use write_file instead. +Reserve terminal for: builds, installs, git, processes, scripts, network, package managers, and anything that needs a shell. + +Foreground (default): Commands return INSTANTLY when done, even if the timeout is high. Set timeout=300 for long builds/scripts — you'll still get the result in seconds if it's fast. Prefer foreground for short commands. +Background: Set background=true to get a session_id. Two patterns: + (1) Long-lived processes that never exit (servers, watchers). + (2) Long-running tasks with notify_on_complete=true — you can keep working on other things and the system auto-notifies you when the task finishes. Great for test suites, builds, deployments, or anything that takes more than a minute. +Use process(action="poll") for progress checks, process(action="wait") to block until done. +Working directory: Use 'workdir' for per-command cwd. +PTY mode: Set pty=true for interactive CLI tools (Codex, Claude Code, Python REPL). + +Do NOT use vim/nano/interactive tools without pty=true — they hang without a pseudo-terminal. Pipe git output to cat if it might page. +""" + +# Global state for environment lifecycle management +_active_environments: Dict[str, Any] = {} +_last_activity: Dict[str, float] = {} +_env_lock = threading.Lock() +_creation_locks: Dict[str, threading.Lock] = {} # Per-task locks for sandbox creation +_creation_locks_lock = threading.Lock() # Protects _creation_locks dict itself +_cleanup_thread = None +_cleanup_running = False + +# Per-task environment overrides registry. +# Allows environments (e.g., TerminalBench2Env) to specify a custom Docker/Modal +# image for a specific task_id BEFORE the agent loop starts. When the terminal or +# file tools create a new sandbox for that task_id, they check this registry first +# and fall back to the TERMINAL_MODAL_IMAGE (etc.) env var if no override is set. +# +# This is never exposed to the model -- only infrastructure code calls it. +# Thread-safe because each task_id is unique per rollout. +_task_env_overrides: Dict[str, Dict[str, Any]] = {} + + +def register_task_env_overrides(task_id: str, overrides: Dict[str, Any]): + """ + Register environment overrides for a specific task/rollout. + + Called by Atropos environments before the agent loop to configure + per-task sandbox settings (e.g., a custom Dockerfile for the Modal image). + + Supported override keys: + - modal_image: str -- Path to Dockerfile or Docker Hub image name + - docker_image: str -- Docker image name + - cwd: str -- Working directory inside the sandbox + + Args: + task_id: The rollout's unique task identifier + overrides: Dict of config keys to override + """ + _task_env_overrides[task_id] = overrides + + +def clear_task_env_overrides(task_id: str): + """ + Clear environment overrides for a task after rollout completes. + + Called during cleanup to avoid stale entries accumulating. + """ + _task_env_overrides.pop(task_id, None) + +# Configuration from environment variables + +def _parse_env_var(name: str, default: str, converter=int, type_label: str = "integer"): + """Parse an environment variable with *converter*, raising a clear error on bad values. + + Without this wrapper, a single malformed env var (e.g. TERMINAL_TIMEOUT=5m) + causes an unhandled ValueError that kills every terminal command. + """ + raw = os.getenv(name, default) + try: + return converter(raw) + except (ValueError, json.JSONDecodeError): + raise ValueError( + f"Invalid value for {name}: {raw!r} (expected {type_label}). " + f"Check ~/.hermes/.env or environment variables." + ) + + +def _get_env_config() -> Dict[str, Any]: + """Get terminal environment configuration from environment variables.""" + # Default image with Python and Node.js for maximum compatibility + default_image = "nikolaik/python-nodejs:python3.11-nodejs20" + env_type = os.getenv("TERMINAL_ENV", "local") + + mount_docker_cwd = os.getenv("TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE", "false").lower() in ("true", "1", "yes") + + # Default cwd: local uses the host's current directory, everything + # else starts in the user's home (~ resolves to whatever account + # is running inside the container/remote). + if env_type == "local": + default_cwd = os.getcwd() + elif env_type == "ssh": + default_cwd = "~" + else: + default_cwd = "/root" + + # Read TERMINAL_CWD but sanity-check it for container backends. + # If Docker cwd passthrough is explicitly enabled, remap the host path to + # /workspace and track the original host path separately. Otherwise keep the + # normal sandbox behavior and discard host paths. + cwd = os.getenv("TERMINAL_CWD", default_cwd) + host_cwd = None + host_prefixes = ("/Users/", "/home/", "C:\\", "C:/") + if env_type == "docker" and mount_docker_cwd: + docker_cwd_source = os.getenv("TERMINAL_CWD") or os.getcwd() + candidate = os.path.abspath(os.path.expanduser(docker_cwd_source)) + if ( + any(candidate.startswith(p) for p in host_prefixes) + or (os.path.isabs(candidate) and os.path.isdir(candidate) and not candidate.startswith(("/workspace", "/root"))) + ): + host_cwd = candidate + cwd = "/workspace" + elif env_type in ("modal", "docker", "singularity", "daytona") and cwd: + # Host paths and relative paths that won't work inside containers + is_host_path = any(cwd.startswith(p) for p in host_prefixes) + is_relative = not os.path.isabs(cwd) # e.g. "." or "src/" + if (is_host_path or is_relative) and cwd != default_cwd: + logger.info("Ignoring TERMINAL_CWD=%r for %s backend " + "(host/relative path won't work in sandbox). Using %r instead.", + cwd, env_type, default_cwd) + cwd = default_cwd + + return { + "env_type": env_type, + "modal_mode": coerce_modal_mode(os.getenv("TERMINAL_MODAL_MODE", "auto")), + "docker_image": os.getenv("TERMINAL_DOCKER_IMAGE", default_image), + "docker_forward_env": _parse_env_var("TERMINAL_DOCKER_FORWARD_ENV", "[]", json.loads, "valid JSON"), + "singularity_image": os.getenv("TERMINAL_SINGULARITY_IMAGE", f"docker://{default_image}"), + "modal_image": os.getenv("TERMINAL_MODAL_IMAGE", default_image), + "daytona_image": os.getenv("TERMINAL_DAYTONA_IMAGE", default_image), + "cwd": cwd, + "host_cwd": host_cwd, + "docker_mount_cwd_to_workspace": mount_docker_cwd, + "timeout": _parse_env_var("TERMINAL_TIMEOUT", "180"), + "lifetime_seconds": _parse_env_var("TERMINAL_LIFETIME_SECONDS", "300"), + # SSH-specific config + "ssh_host": os.getenv("TERMINAL_SSH_HOST", ""), + "ssh_user": os.getenv("TERMINAL_SSH_USER", ""), + "ssh_port": _parse_env_var("TERMINAL_SSH_PORT", "22"), + "ssh_key": os.getenv("TERMINAL_SSH_KEY", ""), + # Persistent shell: SSH defaults to the config-level persistent_shell + # setting (true by default for non-local backends); local is always opt-in. + # Per-backend env vars override if explicitly set. + "ssh_persistent": os.getenv( + "TERMINAL_SSH_PERSISTENT", + os.getenv("TERMINAL_PERSISTENT_SHELL", "true"), + ).lower() in ("true", "1", "yes"), + "local_persistent": os.getenv("TERMINAL_LOCAL_PERSISTENT", "false").lower() in ("true", "1", "yes"), + # Container resource config (applies to docker, singularity, modal, daytona -- ignored for local/ssh) + "container_cpu": _parse_env_var("TERMINAL_CONTAINER_CPU", "1", float, "number"), + "container_memory": _parse_env_var("TERMINAL_CONTAINER_MEMORY", "5120"), # MB (default 5GB) + "container_disk": _parse_env_var("TERMINAL_CONTAINER_DISK", "51200"), # MB (default 50GB) + "container_persistent": os.getenv("TERMINAL_CONTAINER_PERSISTENT", "true").lower() in ("true", "1", "yes"), + "docker_volumes": _parse_env_var("TERMINAL_DOCKER_VOLUMES", "[]", json.loads, "valid JSON"), + } + + +def _get_modal_backend_state(modal_mode: object | None) -> Dict[str, Any]: + """Resolve direct vs managed Modal backend selection.""" + return resolve_modal_backend_state( + modal_mode, + has_direct=has_direct_modal_credentials(), + managed_ready=is_managed_tool_gateway_ready("modal"), + ) + + +def _create_environment(env_type: str, image: str, cwd: str, timeout: int, + ssh_config: dict = None, container_config: dict = None, + local_config: dict = None, + task_id: str = "default", + host_cwd: str = None): + """ + Create an execution environment for sandboxed command execution. + + Args: + env_type: One of "local", "docker", "singularity", "modal", "daytona", "ssh" + image: Docker/Singularity/Modal image name (ignored for local/ssh) + cwd: Working directory + timeout: Default command timeout + ssh_config: SSH connection config (for env_type="ssh") + container_config: Resource config for container backends (cpu, memory, disk, persistent) + task_id: Task identifier for environment reuse and snapshot keying + host_cwd: Optional host working directory to bind into Docker when explicitly enabled + + Returns: + Environment instance with execute() method + """ + cc = container_config or {} + cpu = cc.get("container_cpu", 1) + memory = cc.get("container_memory", 5120) + disk = cc.get("container_disk", 51200) + persistent = cc.get("container_persistent", True) + volumes = cc.get("docker_volumes", []) + docker_forward_env = cc.get("docker_forward_env", []) + docker_env = cc.get("docker_env", {}) + + if env_type == "local": + return _LocalEnvironment(cwd=cwd, timeout=timeout) + + elif env_type == "docker": + return _DockerEnvironment( + image=image, cwd=cwd, timeout=timeout, + cpu=cpu, memory=memory, disk=disk, + persistent_filesystem=persistent, task_id=task_id, + volumes=volumes, + host_cwd=host_cwd, + auto_mount_cwd=cc.get("docker_mount_cwd_to_workspace", False), + forward_env=docker_forward_env, + env=docker_env, + ) + + elif env_type == "singularity": + return _SingularityEnvironment( + image=image, cwd=cwd, timeout=timeout, + cpu=cpu, memory=memory, disk=disk, + persistent_filesystem=persistent, task_id=task_id, + ) + + elif env_type == "modal": + sandbox_kwargs = {} + if cpu > 0: + sandbox_kwargs["cpu"] = cpu + if memory > 0: + sandbox_kwargs["memory"] = memory + if disk > 0: + try: + import inspect, modal + if "ephemeral_disk" in inspect.signature(modal.Sandbox.create).parameters: + sandbox_kwargs["ephemeral_disk"] = disk + except Exception: + pass + + modal_state = _get_modal_backend_state(cc.get("modal_mode")) + + if modal_state["selected_backend"] == "managed": + return _ManagedModalEnvironment( + image=image, cwd=cwd, timeout=timeout, + modal_sandbox_kwargs=sandbox_kwargs, + persistent_filesystem=persistent, task_id=task_id, + ) + + if modal_state["selected_backend"] != "direct": + if modal_state["managed_mode_blocked"]: + raise ValueError( + "Modal backend is configured for managed mode, but " + "HERMES_ENABLE_NOUS_MANAGED_TOOLS is not enabled and no direct " + "Modal credentials/config were found. Enable the feature flag or " + "choose TERMINAL_MODAL_MODE=direct/auto." + ) + if modal_state["mode"] == "managed": + raise ValueError( + "Modal backend is configured for managed mode, but the managed tool gateway is unavailable." + ) + if modal_state["mode"] == "direct": + raise ValueError( + "Modal backend is configured for direct mode, but no direct Modal credentials/config were found." + ) + message = "Modal backend selected but no direct Modal credentials/config was found." + if managed_nous_tools_enabled(): + message = ( + "Modal backend selected but no direct Modal credentials/config or managed tool gateway was found." + ) + raise ValueError(message) + + return _ModalEnvironment( + image=image, cwd=cwd, timeout=timeout, + modal_sandbox_kwargs=sandbox_kwargs, + persistent_filesystem=persistent, task_id=task_id, + ) + + elif env_type == "daytona": + # Lazy import so daytona SDK is only required when backend is selected. + from tools.environments.daytona import DaytonaEnvironment as _DaytonaEnvironment + return _DaytonaEnvironment( + image=image, cwd=cwd, timeout=timeout, + cpu=int(cpu), memory=memory, disk=disk, + persistent_filesystem=persistent, task_id=task_id, + ) + + elif env_type == "ssh": + if not ssh_config or not ssh_config.get("host") or not ssh_config.get("user"): + raise ValueError("SSH environment requires ssh_host and ssh_user to be configured") + return _SSHEnvironment( + host=ssh_config["host"], + user=ssh_config["user"], + port=ssh_config.get("port", 22), + key_path=ssh_config.get("key", ""), + cwd=cwd, + timeout=timeout, + ) + + else: + raise ValueError(f"Unknown environment type: {env_type}. Use 'local', 'docker', 'singularity', 'modal', 'daytona', or 'ssh'") + + +def _cleanup_inactive_envs(lifetime_seconds: int = 300): + """Clean up environments that have been inactive for longer than lifetime_seconds.""" + current_time = time.time() + + # Check the process registry -- skip cleanup for sandboxes with active + # background processes (their _last_activity gets refreshed to keep them alive). + try: + from tools.process_registry import process_registry + for task_id in list(_last_activity.keys()): + if process_registry.has_active_processes(task_id): + _last_activity[task_id] = current_time # Keep sandbox alive + except ImportError: + pass + + # Phase 1: collect stale entries and remove them from tracking dicts while + # holding the lock. Do NOT call env.cleanup() inside the lock -- Modal and + # Docker teardown can block for 10-15s, which would stall every concurrent + # terminal/file tool call waiting on _env_lock. + envs_to_stop = [] # list of (task_id, env) pairs + + with _env_lock: + for task_id, last_time in list(_last_activity.items()): + if current_time - last_time > lifetime_seconds: + env = _active_environments.pop(task_id, None) + _last_activity.pop(task_id, None) + if env is not None: + envs_to_stop.append((task_id, env)) + + # Also purge per-task creation locks for cleaned-up tasks + with _creation_locks_lock: + for task_id, _ in envs_to_stop: + _creation_locks.pop(task_id, None) + + # Phase 2: stop the actual sandboxes OUTSIDE the lock so other tool calls + # are not blocked while Modal/Docker sandboxes shut down. + for task_id, env in envs_to_stop: + # Invalidate stale file_ops cache entry (Bug fix: prevents + # ShellFileOperations from referencing a dead sandbox) + try: + from tools.file_tools import clear_file_ops_cache + clear_file_ops_cache(task_id) + except ImportError: + pass + + try: + if hasattr(env, 'cleanup'): + env.cleanup() + elif hasattr(env, 'stop'): + env.stop() + elif hasattr(env, 'terminate'): + env.terminate() + + logger.info("Cleaned up inactive environment for task: %s", task_id) + + except Exception as e: + error_str = str(e) + if "404" in error_str or "not found" in error_str.lower(): + logger.info("Environment for task %s already cleaned up", task_id) + else: + logger.warning("Error cleaning up environment for task %s: %s", task_id, e) + + +def _cleanup_thread_worker(): + """Background thread worker that periodically cleans up inactive environments.""" + while _cleanup_running: + try: + config = _get_env_config() + _cleanup_inactive_envs(config["lifetime_seconds"]) + except Exception as e: + logger.warning("Error in cleanup thread: %s", e, exc_info=True) + + for _ in range(60): + if not _cleanup_running: + break + time.sleep(1) + + +def _start_cleanup_thread(): + """Start the background cleanup thread if not already running.""" + global _cleanup_thread, _cleanup_running + + with _env_lock: + if _cleanup_thread is None or not _cleanup_thread.is_alive(): + _cleanup_running = True + _cleanup_thread = threading.Thread(target=_cleanup_thread_worker, daemon=True) + _cleanup_thread.start() + + +def _stop_cleanup_thread(): + """Stop the background cleanup thread.""" + global _cleanup_running + _cleanup_running = False + if _cleanup_thread is not None: + try: + _cleanup_thread.join(timeout=5) + except (SystemExit, KeyboardInterrupt): + pass + + +def get_active_env(task_id: str): + """Return the active BaseEnvironment for *task_id*, or None.""" + with _env_lock: + return _active_environments.get(task_id) + + +def is_persistent_env(task_id: str) -> bool: + """Return True if the active environment for task_id is configured for + cross-turn persistence (``persistent_filesystem=True``). + + Used by the agent loop to skip per-turn teardown for backends whose whole + point is to survive between turns (docker with ``container_persistent``, + daytona, modal, etc.). Non-persistent backends (e.g. Morph) still get torn + down at end-of-turn to prevent leakage. The idle reaper + (``_cleanup_inactive_envs``) handles persistent envs once they exceed + ``terminal.lifetime_seconds``. + """ + env = get_active_env(task_id) + if env is None: + return False + return bool(getattr(env, "_persistent", False)) + + + + +def cleanup_all_environments(): + """Clean up ALL active environments. Use with caution.""" + task_ids = list(_active_environments.keys()) + cleaned = 0 + + for task_id in task_ids: + try: + cleanup_vm(task_id) + cleaned += 1 + except Exception as e: + logger.error("Error cleaning %s: %s", task_id, e, exc_info=True) + + # Also clean any orphaned directories + scratch_dir = _get_scratch_dir() + import glob + for path in glob.glob(str(scratch_dir / "hermes-*")): + try: + shutil.rmtree(path, ignore_errors=True) + logger.info("Removed orphaned: %s", path) + except OSError as e: + logger.debug("Failed to remove orphaned path %s: %s", path, e) + + if cleaned > 0: + logger.info("Cleaned %d environments", cleaned) + return cleaned + + +def cleanup_vm(task_id: str): + """Manually clean up a specific environment by task_id.""" + # Remove from tracking dicts while holding the lock, but defer the + # actual (potentially slow) env.cleanup() call to outside the lock + # so other tool calls aren't blocked. + env = None + with _env_lock: + env = _active_environments.pop(task_id, None) + _last_activity.pop(task_id, None) + + # Clean up per-task creation lock + with _creation_locks_lock: + _creation_locks.pop(task_id, None) + + # Invalidate stale file_ops cache entry + try: + from tools.file_tools import clear_file_ops_cache + clear_file_ops_cache(task_id) + except ImportError: + pass + + if env is None: + return + + try: + if hasattr(env, 'cleanup'): + env.cleanup() + elif hasattr(env, 'stop'): + env.stop() + elif hasattr(env, 'terminate'): + env.terminate() + + logger.info("Manually cleaned up environment for task: %s", task_id) + + except Exception as e: + error_str = str(e) + if "404" in error_str or "not found" in error_str.lower(): + logger.info("Environment for task %s already cleaned up", task_id) + else: + logger.warning("Error cleaning up environment for task %s: %s", task_id, e) + + +def _atexit_cleanup(): + """Stop cleanup thread and shut down all remaining sandboxes on exit.""" + _stop_cleanup_thread() + if _active_environments: + count = len(_active_environments) + logger.info("Shutting down %d remaining sandbox(es)...", count) + cleanup_all_environments() + +atexit.register(_atexit_cleanup) + + +# ============================================================================= +# Exit Code Context for Common CLI Tools +# ============================================================================= +# Many Unix commands use non-zero exit codes for informational purposes, not +# to indicate failure. The model sees a raw exit_code=1 from `grep` and +# wastes a turn investigating something that just means "no matches". +# This lookup adds a human-readable note so the agent can move on. + +def _interpret_exit_code(command: str, exit_code: int) -> str | None: + """Return a human-readable note when a non-zero exit code is non-erroneous. + + Returns None when the exit code is 0 or genuinely signals an error. + The note is appended to the tool result so the model doesn't waste + turns investigating expected exit codes. + """ + if exit_code == 0: + return None + + # Extract the last command in a pipeline/chain — that determines the + # exit code. Handles `cmd1 && cmd2`, `cmd1 | cmd2`, `cmd1; cmd2`. + # Deliberately simple: split on shell operators and take the last piece. + segments = re.split(r'\s*(?:\|\||&&|[|;])\s*', command) + last_segment = (segments[-1] if segments else command).strip() + + # Get base command name (first word), stripping env var assignments + # like VAR=val cmd ... + words = last_segment.split() + base_cmd = "" + for w in words: + if "=" in w and not w.startswith("-"): + continue # skip VAR=val + base_cmd = w.split("/")[-1] # handle /usr/bin/grep -> grep + break + + if not base_cmd: + return None + + # Command-specific semantics + semantics: dict[str, dict[int, str]] = { + # grep/rg/ag/ack: 1=no matches found (normal), 2+=real error + "grep": {1: "No matches found (not an error)"}, + "egrep": {1: "No matches found (not an error)"}, + "fgrep": {1: "No matches found (not an error)"}, + "rg": {1: "No matches found (not an error)"}, + "ag": {1: "No matches found (not an error)"}, + "ack": {1: "No matches found (not an error)"}, + # diff: 1=files differ (expected), 2+=real error + "diff": {1: "Files differ (expected, not an error)"}, + "colordiff": {1: "Files differ (expected, not an error)"}, + # find: 1=some dirs inaccessible but results may still be valid + "find": {1: "Some directories were inaccessible (partial results may still be valid)"}, + # test/[: 1=condition is false (expected) + "test": {1: "Condition evaluated to false (expected, not an error)"}, + "[": {1: "Condition evaluated to false (expected, not an error)"}, + # curl: common non-error codes + "curl": { + 6: "Could not resolve host", + 7: "Failed to connect to host", + 22: "HTTP response code indicated error (e.g. 404, 500)", + 28: "Operation timed out", + }, + # git: 1 is context-dependent but often normal (e.g. git diff with changes) + "git": {1: "Non-zero exit (often normal — e.g. 'git diff' returns 1 when files differ)"}, + } + + cmd_semantics = semantics.get(base_cmd) + if cmd_semantics and exit_code in cmd_semantics: + return cmd_semantics[exit_code] + + return None + + +def _command_requires_pipe_stdin(command: str) -> bool: + """Return True when PTY mode would break stdin-driven commands. + + Some CLIs change behavior when stdin is a TTY. In particular, + `gh auth login --with-token` expects the token to arrive via piped stdin and + waits for EOF; when we launch it under a PTY, `process.submit()` only sends a + newline, so the command appears to hang forever with no visible progress. + """ + normalized = " ".join(command.lower().split()) + return ( + normalized.startswith("gh auth login") + and "--with-token" in normalized + ) + + +def terminal_tool( + command: str, + background: bool = False, + timeout: Optional[int] = None, + task_id: Optional[str] = None, + force: bool = False, + workdir: Optional[str] = None, + pty: bool = False, + notify_on_complete: bool = False, + watch_patterns: Optional[List[str]] = None, +) -> str: + """ + Execute a command in the configured terminal environment. + + Args: + command: The command to execute + background: Whether to run in background (default: False) + timeout: Command timeout in seconds (default: from config) + task_id: Unique identifier for environment isolation (optional) + force: If True, skip dangerous command check (use after user confirms) + workdir: Working directory for this command (optional, uses session cwd if not set) + pty: If True, use pseudo-terminal for interactive CLI tools (local backend only) + notify_on_complete: If True and background=True, auto-notify the agent when the process exits + watch_patterns: List of strings to watch for in background output; triggers notification on match + + Returns: + str: JSON string with output, exit_code, and error fields + + Examples: + # Execute a simple command + >>> result = terminal_tool(command="ls -la /tmp") + + # Run a background task + >>> result = terminal_tool(command="python server.py", background=True) + + # With custom timeout + >>> result = terminal_tool(command="long_task.sh", timeout=300) + + # Force run after user confirmation + # Note: force parameter is internal only, not exposed to model API + """ + try: + if not isinstance(command, str): + logger.warning( + "Rejected invalid terminal command value: %s", + type(command).__name__, + ) + return json.dumps({ + "output": "", + "exit_code": -1, + "error": f"Invalid command: expected string, got {type(command).__name__}", + "status": "error", + }, ensure_ascii=False) + + # Get configuration + config = _get_env_config() + env_type = config["env_type"] + + # Use task_id for environment isolation + effective_task_id = task_id or "default" + + # Check per-task overrides (set by environments like TerminalBench2Env) + # before falling back to global env var config + overrides = _task_env_overrides.get(effective_task_id, {}) + + # Select image based on env type, with per-task override support + if env_type == "docker": + image = overrides.get("docker_image") or config["docker_image"] + elif env_type == "singularity": + image = overrides.get("singularity_image") or config["singularity_image"] + elif env_type == "modal": + image = overrides.get("modal_image") or config["modal_image"] + elif env_type == "daytona": + image = overrides.get("daytona_image") or config["daytona_image"] + else: + image = "" + + cwd = overrides.get("cwd") or config["cwd"] + default_timeout = config["timeout"] + effective_timeout = timeout or default_timeout + + # Reject foreground commands where the model explicitly requests + # a timeout above FOREGROUND_MAX_TIMEOUT — nudge it toward background. + if not background and timeout and timeout > FOREGROUND_MAX_TIMEOUT: + return json.dumps({ + "error": ( + f"Foreground timeout {timeout}s exceeds the maximum of " + f"{FOREGROUND_MAX_TIMEOUT}s. Use background=true with " + f"notify_on_complete=true for long-running commands." + ), + }, ensure_ascii=False) + + # Start cleanup thread + _start_cleanup_thread() + + # Get or create environment. + # Use a per-task creation lock so concurrent tool calls for the same + # task_id wait for the first one to finish creating the sandbox, + # instead of each creating their own (wasting Modal resources). + with _env_lock: + if effective_task_id in _active_environments: + _last_activity[effective_task_id] = time.time() + env = _active_environments[effective_task_id] + needs_creation = False + else: + needs_creation = True + + if needs_creation: + # Per-task lock: only one thread creates the sandbox, others wait + with _creation_locks_lock: + if effective_task_id not in _creation_locks: + _creation_locks[effective_task_id] = threading.Lock() + task_lock = _creation_locks[effective_task_id] + + with task_lock: + # Double-check after acquiring the per-task lock + with _env_lock: + if effective_task_id in _active_environments: + _last_activity[effective_task_id] = time.time() + env = _active_environments[effective_task_id] + needs_creation = False + + if needs_creation: + if env_type == "singularity": + _check_disk_usage_warning() + logger.info("Creating new %s environment for task %s...", env_type, effective_task_id[:8]) + try: + ssh_config = None + if env_type == "ssh": + ssh_config = { + "host": config.get("ssh_host", ""), + "user": config.get("ssh_user", ""), + "port": config.get("ssh_port", 22), + "key": config.get("ssh_key", ""), + "persistent": config.get("ssh_persistent", False), + } + + container_config = None + if env_type in ("docker", "singularity", "modal", "daytona"): + container_config = { + "container_cpu": config.get("container_cpu", 1), + "container_memory": config.get("container_memory", 5120), + "container_disk": config.get("container_disk", 51200), + "container_persistent": config.get("container_persistent", True), + "modal_mode": config.get("modal_mode", "auto"), + "docker_volumes": config.get("docker_volumes", []), + "docker_mount_cwd_to_workspace": config.get("docker_mount_cwd_to_workspace", False), + } + + local_config = None + if env_type == "local": + local_config = { + "persistent": config.get("local_persistent", False), + } + + new_env = _create_environment( + env_type=env_type, + image=image, + cwd=cwd, + timeout=effective_timeout, + ssh_config=ssh_config, + container_config=container_config, + local_config=local_config, + task_id=effective_task_id, + host_cwd=config.get("host_cwd"), + ) + except ImportError as e: + return json.dumps({ + "output": "", + "exit_code": -1, + "error": f"Terminal tool disabled: environment creation failed ({e})", + "status": "disabled" + }, ensure_ascii=False) + + with _env_lock: + _active_environments[effective_task_id] = new_env + _last_activity[effective_task_id] = time.time() + env = new_env + logger.info("%s environment ready for task %s", env_type, effective_task_id[:8]) + + # Pre-exec security checks (tirith + dangerous command detection) + # Skip check if force=True (user has confirmed they want to run it) + approval_note = None + if not force: + approval = _check_all_guards(command, env_type) + if not approval["approved"]: + # Check if this is an approval_required (gateway ask mode) + if approval.get("status") == "approval_required": + return json.dumps({ + "output": "", + "exit_code": -1, + "error": approval.get("message", "Waiting for user approval"), + "status": "approval_required", + "command": approval.get("command", command), + "description": approval.get("description", "command flagged"), + "pattern_key": approval.get("pattern_key", ""), + }, ensure_ascii=False) + # Command was blocked + desc = approval.get("description", "command flagged") + fallback_msg = ( + f"Command denied: {desc}. " + "Use the approval prompt to allow it, or rephrase the command." + ) + return json.dumps({ + "output": "", + "exit_code": -1, + "error": approval.get("message", fallback_msg), + "status": "blocked" + }, ensure_ascii=False) + # Track whether approval was explicitly granted by the user + if approval.get("user_approved"): + desc = approval.get("description", "flagged as dangerous") + approval_note = f"Command required approval ({desc}) and was approved by the user." + elif approval.get("smart_approved"): + desc = approval.get("description", "flagged as dangerous") + approval_note = f"Command was flagged ({desc}) and auto-approved by smart approval." + + # Validate workdir against shell injection + if workdir: + workdir_error = _validate_workdir(workdir) + if workdir_error: + logger.warning("Blocked dangerous workdir: %s (command: %s)", + workdir[:200], _safe_command_preview(command)) + return json.dumps({ + "output": "", + "exit_code": -1, + "error": workdir_error, + "status": "blocked" + }, ensure_ascii=False) + + # Prepare command for execution + pty_disabled_reason = None + effective_pty = pty + if pty and _command_requires_pipe_stdin(command): + effective_pty = False + pty_disabled_reason = ( + "PTY disabled for this command because it expects piped stdin/EOF " + "(for example gh auth login --with-token). For local background " + "processes, call process(action='close') after writing so it receives " + "EOF." + ) + + if background: + # Spawn a tracked background process via the process registry. + # For local backends: uses subprocess.Popen with output buffering. + # For non-local backends: runs inside the sandbox via env.execute(). + from tools.approval import get_current_session_key + from tools.process_registry import process_registry + + session_key = get_current_session_key(default="") + effective_cwd = workdir or cwd + try: + if env_type == "local": + proc_session = process_registry.spawn_local( + command=command, + cwd=effective_cwd, + task_id=effective_task_id, + session_key=session_key, + env_vars=env.env if hasattr(env, 'env') else None, + use_pty=effective_pty, + ) + else: + proc_session = process_registry.spawn_via_env( + env=env, + command=command, + cwd=effective_cwd, + task_id=effective_task_id, + session_key=session_key, + ) + + result_data = { + "output": "Background process started", + "session_id": proc_session.id, + "pid": proc_session.pid, + "exit_code": 0, + "error": None, + } + if approval_note: + result_data["approval"] = approval_note + if pty_disabled_reason: + result_data["pty_note"] = pty_disabled_reason + + # Mark for agent notification on completion + if notify_on_complete and background: + proc_session.notify_on_complete = True + result_data["notify_on_complete"] = True + + # In gateway mode, auto-register a fast watcher so the + # gateway can detect completion and trigger a new agent + # turn. CLI mode uses the completion_queue directly. + from gateway.session_context import get_session_env as _gse + _gw_platform = _gse("HERMES_SESSION_PLATFORM", "") + if _gw_platform: + _gw_chat_id = _gse("HERMES_SESSION_CHAT_ID", "") + _gw_thread_id = _gse("HERMES_SESSION_THREAD_ID", "") + _gw_user_id = _gse("HERMES_SESSION_USER_ID", "") + _gw_user_name = _gse("HERMES_SESSION_USER_NAME", "") + proc_session.watcher_platform = _gw_platform + proc_session.watcher_chat_id = _gw_chat_id + proc_session.watcher_user_id = _gw_user_id + proc_session.watcher_user_name = _gw_user_name + proc_session.watcher_thread_id = _gw_thread_id + proc_session.watcher_interval = 5 + process_registry.pending_watchers.append({ + "session_id": proc_session.id, + "check_interval": 5, + "session_key": session_key, + "platform": _gw_platform, + "chat_id": _gw_chat_id, + "user_id": _gw_user_id, + "user_name": _gw_user_name, + "thread_id": _gw_thread_id, + "notify_on_complete": True, + }) + + # Set watch patterns for output monitoring + if watch_patterns and background: + proc_session.watch_patterns = list(watch_patterns) + result_data["watch_patterns"] = proc_session.watch_patterns + + return json.dumps(result_data, ensure_ascii=False) + except Exception as e: + return json.dumps({ + "output": "", + "exit_code": -1, + "error": f"Failed to start background process: {str(e)}" + }, ensure_ascii=False) + else: + # Run foreground command with retry logic + max_retries = 3 + retry_count = 0 + result = None + + while retry_count <= max_retries: + try: + execute_kwargs = {"timeout": effective_timeout} + if workdir: + execute_kwargs["cwd"] = workdir + result = env.execute(command, **execute_kwargs) + except Exception as e: + error_str = str(e).lower() + if "timeout" in error_str: + return json.dumps({ + "output": "", + "exit_code": 124, + "error": f"Command timed out after {effective_timeout} seconds" + }, ensure_ascii=False) + + # Retry on transient errors + if retry_count < max_retries: + retry_count += 1 + wait_time = 2 ** retry_count + logger.warning("Execution error, retrying in %ds (attempt %d/%d) - Command: %s - Error: %s: %s - Task: %s, Backend: %s", + wait_time, retry_count, max_retries, _safe_command_preview(command), type(e).__name__, e, effective_task_id, env_type) + time.sleep(wait_time) + continue + + logger.error("Execution failed after %d retries - Command: %s - Error: %s: %s - Task: %s, Backend: %s", + max_retries, _safe_command_preview(command), type(e).__name__, e, effective_task_id, env_type) + return json.dumps({ + "output": "", + "exit_code": -1, + "error": f"Command execution failed: {type(e).__name__}: {str(e)}" + }, ensure_ascii=False) + + # Got a result + break + + # Extract output + output = result.get("output", "") + returncode = result.get("returncode", 0) + + # Add helpful message for sudo failures in messaging context + output = _handle_sudo_failure(output, env_type) + + # Truncate output if too long, keeping both head and tail + MAX_OUTPUT_CHARS = 50000 + if len(output) > MAX_OUTPUT_CHARS: + head_chars = int(MAX_OUTPUT_CHARS * 0.4) # 40% head (error messages often appear early) + tail_chars = MAX_OUTPUT_CHARS - head_chars # 60% tail (most recent/relevant output) + omitted = len(output) - head_chars - tail_chars + truncated_notice = ( + f"\n\n... [OUTPUT TRUNCATED - {omitted} chars omitted " + f"out of {len(output)} total] ...\n\n" + ) + output = output[:head_chars] + truncated_notice + output[-tail_chars:] + + # Strip ANSI escape sequences so the model never sees terminal + # formatting — prevents it from copying escapes into file writes. + from tools.ansi_strip import strip_ansi + output = strip_ansi(output) + + # Redact secrets from command output (catches env/printenv leaking keys) + from agent.redact import redact_sensitive_text + output = redact_sensitive_text(output.strip()) if output else "" + + # Interpret non-zero exit codes that aren't real errors + # (e.g. grep=1 means "no matches", diff=1 means "files differ") + exit_note = _interpret_exit_code(command, returncode) + + result_dict = { + "output": output, + "exit_code": returncode, + "error": None, + } + if approval_note: + result_dict["approval"] = approval_note + if exit_note: + result_dict["exit_code_meaning"] = exit_note + + return json.dumps(result_dict, ensure_ascii=False) + + except Exception as e: + import traceback + tb_str = traceback.format_exc() + logger.error("terminal_tool exception:\n%s", tb_str) + return json.dumps({ + "output": "", + "exit_code": -1, + "error": f"Failed to execute command: {str(e)}", + "traceback": tb_str, + "status": "error" + }, ensure_ascii=False) + + +def check_terminal_requirements() -> bool: + """Check if all requirements for the terminal tool are met.""" + config = _get_env_config() + env_type = config["env_type"] + + try: + if env_type == "local": + return True + + elif env_type == "docker": + from tools.environments.docker import find_docker + docker = find_docker() + if not docker: + logger.error("Docker executable not found in PATH or common install locations") + return False + result = subprocess.run([docker, "version"], capture_output=True, timeout=5) + return result.returncode == 0 + + elif env_type == "singularity": + executable = shutil.which("apptainer") or shutil.which("singularity") + if executable: + result = subprocess.run([executable, "--version"], capture_output=True, timeout=5) + return result.returncode == 0 + return False + + elif env_type == "ssh": + if not config.get("ssh_host") or not config.get("ssh_user"): + logger.error( + "SSH backend selected but TERMINAL_SSH_HOST and TERMINAL_SSH_USER " + "are not both set. Configure both or switch TERMINAL_ENV to 'local'." + ) + return False + return True + + elif env_type == "modal": + modal_state = _get_modal_backend_state(config.get("modal_mode")) + if modal_state["selected_backend"] == "managed": + return True + + if modal_state["selected_backend"] != "direct": + if modal_state["managed_mode_blocked"]: + logger.error( + "Modal backend selected with TERMINAL_MODAL_MODE=managed, but " + "HERMES_ENABLE_NOUS_MANAGED_TOOLS is not enabled and no direct " + "Modal credentials/config were found. Enable the feature flag " + "or choose TERMINAL_MODAL_MODE=direct/auto." + ) + return False + if modal_state["mode"] == "managed": + logger.error( + "Modal backend selected with TERMINAL_MODAL_MODE=managed, but the managed " + "tool gateway is unavailable. Configure the managed gateway or choose " + "TERMINAL_MODAL_MODE=direct/auto." + ) + return False + elif modal_state["mode"] == "direct": + if managed_nous_tools_enabled(): + logger.error( + "Modal backend selected with TERMINAL_MODAL_MODE=direct, but no direct " + "Modal credentials/config were found. Configure Modal or choose " + "TERMINAL_MODAL_MODE=managed/auto." + ) + else: + logger.error( + "Modal backend selected with TERMINAL_MODAL_MODE=direct, but no direct " + "Modal credentials/config were found. Configure Modal or choose " + "TERMINAL_MODAL_MODE=auto." + ) + return False + else: + if managed_nous_tools_enabled(): + logger.error( + "Modal backend selected but no direct Modal credentials/config or managed " + "tool gateway was found. Configure Modal, set up the managed gateway, " + "or choose a different TERMINAL_ENV." + ) + else: + logger.error( + "Modal backend selected but no direct Modal credentials/config was found. " + "Configure Modal or choose a different TERMINAL_ENV." + ) + return False + + if importlib.util.find_spec("modal") is None: + logger.error("modal is required for direct modal terminal backend: pip install modal") + return False + + return True + + elif env_type == "daytona": + from daytona import Daytona # noqa: F401 — SDK presence check + return os.getenv("DAYTONA_API_KEY") is not None + + else: + logger.error( + "Unknown TERMINAL_ENV '%s'. Use one of: local, docker, singularity, " + "modal, daytona, ssh.", + env_type, + ) + return False + except Exception as e: + logger.error("Terminal requirements check failed: %s", e, exc_info=True) + return False + + +if __name__ == "__main__": + # Simple test when run directly + print("Terminal Tool Module") + print("=" * 50) + + config = _get_env_config() + print("\nCurrent Configuration:") + print(f" Environment type: {config['env_type']}") + print(f" Docker image: {config['docker_image']}") + print(f" Modal image: {config['modal_image']}") + print(f" Working directory: {config['cwd']}") + print(f" Default timeout: {config['timeout']}s") + print(f" Lifetime: {config['lifetime_seconds']}s") + + if not check_terminal_requirements(): + print("\n❌ Requirements not met. Please check the messages above.") + exit(1) + + print("\n✅ All requirements met!") + print("\nAvailable Tool:") + print(" - terminal_tool: Execute commands in sandboxed environments") + + print("\nUsage Examples:") + print(" # Execute a command") + print(" result = terminal_tool(command='ls -la')") + print(" ") + print(" # Run a background task") + print(" result = terminal_tool(command='python server.py', background=True)") + + print("\nEnvironment Variables:") + default_img = "nikolaik/python-nodejs:python3.11-nodejs20" + print(f" TERMINAL_ENV: {os.getenv('TERMINAL_ENV', 'local')} (local/docker/singularity/modal/daytona/ssh)") + print(f" TERMINAL_DOCKER_IMAGE: {os.getenv('TERMINAL_DOCKER_IMAGE', default_img)}") + print(f" TERMINAL_SINGULARITY_IMAGE: {os.getenv('TERMINAL_SINGULARITY_IMAGE', f'docker://{default_img}')}") + print(f" TERMINAL_MODAL_IMAGE: {os.getenv('TERMINAL_MODAL_IMAGE', default_img)}") + print(f" TERMINAL_DAYTONA_IMAGE: {os.getenv('TERMINAL_DAYTONA_IMAGE', default_img)}") + print(f" TERMINAL_CWD: {os.getenv('TERMINAL_CWD', os.getcwd())}") + from hermes_constants import display_hermes_home as _dhh + print(f" TERMINAL_SANDBOX_DIR: {os.getenv('TERMINAL_SANDBOX_DIR', f'{_dhh()}/sandboxes')}") + print(f" TERMINAL_TIMEOUT: {os.getenv('TERMINAL_TIMEOUT', '60')}") + print(f" TERMINAL_LIFETIME_SECONDS: {os.getenv('TERMINAL_LIFETIME_SECONDS', '300')}") + + +# --------------------------------------------------------------------------- +# Registry +# --------------------------------------------------------------------------- +from tools.registry import registry + +TERMINAL_SCHEMA = { + "name": "terminal", + "description": TERMINAL_TOOL_DESCRIPTION, + "parameters": { + "type": "object", + "properties": { + "command": { + "type": "string", + "description": "The command to execute on the VM" + }, + "background": { + "type": "boolean", + "description": "Run the command in the background. Two patterns: (1) Long-lived processes that never exit (servers, watchers). (2) Long-running tasks paired with notify_on_complete=true — you can keep working and get notified when the task finishes. For short commands, prefer foreground with a generous timeout instead.", + "default": False + }, + "timeout": { + "type": "integer", + "description": f"Max seconds to wait (default: 180, foreground max: {FOREGROUND_MAX_TIMEOUT}). Returns INSTANTLY when command finishes — set high for long tasks, you won't wait unnecessarily. Foreground timeout above {FOREGROUND_MAX_TIMEOUT}s is rejected; use background=true for longer commands.", + "minimum": 1 + }, + "workdir": { + "type": "string", + "description": "Working directory for this command (absolute path). Defaults to the session working directory." + }, + "pty": { + "type": "boolean", + "description": "Run in pseudo-terminal (PTY) mode for interactive CLI tools like Codex, Claude Code, or Python REPL. Only works with local and SSH backends. Default: false.", + "default": False + }, + "notify_on_complete": { + "type": "boolean", + "description": "When true (and background=true), you'll be automatically notified when the process finishes — no polling needed. Use this for tasks that take a while (tests, builds, deployments) so you can keep working on other things in the meantime.", + "default": False + }, + "watch_patterns": { + "type": "array", + "items": {"type": "string"}, + "description": "List of strings to watch for in background process output. When any pattern matches a line of output, you'll be notified with the matching text — like notify_on_complete but triggers mid-process on specific output. Use for monitoring logs, watching for errors, or waiting for specific events (e.g. [\"ERROR\", \"FAIL\", \"listening on port\"])." + } + }, + "required": ["command"] + } +} + + +def _handle_terminal(args, **kw): + return terminal_tool( + command=args.get("command"), + background=args.get("background", False), + timeout=args.get("timeout"), + task_id=kw.get("task_id"), + workdir=args.get("workdir"), + pty=args.get("pty", False), + notify_on_complete=args.get("notify_on_complete", False), + watch_patterns=args.get("watch_patterns"), + ) + + +registry.register( + name="terminal", + toolset="terminal", + schema=TERMINAL_SCHEMA, + handler=_handle_terminal, + check_fn=check_terminal_requirements, + emoji="💻", + max_result_size_chars=100_000, +) diff --git a/mindcli/_vendor/tools/tirith_security.py b/mindcli/_vendor/tools/tirith_security.py new file mode 100644 index 0000000..b305594 --- /dev/null +++ b/mindcli/_vendor/tools/tirith_security.py @@ -0,0 +1,670 @@ +"""Tirith pre-exec security scanning wrapper. + +Runs the tirith binary as a subprocess to scan commands for content-level +threats (homograph URLs, pipe-to-interpreter, terminal injection, etc.). + +Exit code is the verdict source of truth: + 0 = allow, 1 = block, 2 = warn + +JSON stdout enriches findings/summary but never overrides the verdict. +Operational failures (spawn error, timeout, unknown exit code) respect +the fail_open config setting. Programming errors propagate. + +Auto-install: if tirith is not found on PATH or at the configured path, +it is automatically downloaded from GitHub releases to $HERMES_HOME/bin/tirith. +The download always verifies SHA-256 checksums. When cosign is available on +PATH, provenance verification (GitHub Actions workflow signature) is also +performed. If cosign is not installed, the download proceeds with SHA-256 +verification only — still secure via HTTPS + checksum, just without supply +chain provenance proof. Installation runs in a background thread so startup +never blocks. +""" + +import hashlib +import json +import logging +import os +import platform +import shutil +import stat +import subprocess +import tarfile +import tempfile +import threading +import time +import urllib.request + +from hermes_constants import get_hermes_home + +logger = logging.getLogger(__name__) + +_REPO = "sheeki03/tirith" + +# Cosign provenance verification — pinned to the specific release workflow +_COSIGN_IDENTITY_REGEXP = f"^https://github.com/{_REPO}/\\.github/workflows/release\\.yml@refs/tags/v" +_COSIGN_ISSUER = "https://token.actions.githubusercontent.com" + +# --------------------------------------------------------------------------- +# Config helpers +# --------------------------------------------------------------------------- + +def _env_bool(key: str, default: bool) -> bool: + val = os.getenv(key) + if val is None: + return default + return val.lower() in ("1", "true", "yes") + + +def _env_int(key: str, default: int) -> int: + val = os.getenv(key) + if val is None: + return default + try: + return int(val) + except ValueError: + return default + + +def _load_security_config() -> dict: + """Load security settings from config.yaml, with env var overrides.""" + defaults = { + "tirith_enabled": True, + "tirith_path": "tirith", + "tirith_timeout": 5, + "tirith_fail_open": True, + } + try: + from hermes_cli.config import load_config + cfg = load_config().get("security", {}) or {} + except Exception: + cfg = {} + + return { + "tirith_enabled": _env_bool("TIRITH_ENABLED", cfg.get("tirith_enabled", defaults["tirith_enabled"])), + "tirith_path": os.getenv("TIRITH_BIN", cfg.get("tirith_path", defaults["tirith_path"])), + "tirith_timeout": _env_int("TIRITH_TIMEOUT", cfg.get("tirith_timeout", defaults["tirith_timeout"])), + "tirith_fail_open": _env_bool("TIRITH_FAIL_OPEN", cfg.get("tirith_fail_open", defaults["tirith_fail_open"])), + } + + +# --------------------------------------------------------------------------- +# Auto-install +# --------------------------------------------------------------------------- + +# Cached path after first resolution (avoids repeated shutil.which per command). +# _INSTALL_FAILED means "we tried and failed" — prevents retry on every command. +_resolved_path: str | None | bool = None +_INSTALL_FAILED = False # sentinel: distinct from "not yet tried" +_install_failure_reason: str = "" # reason tag when _resolved_path is _INSTALL_FAILED + +# Background install thread coordination +_install_lock = threading.Lock() +_install_thread: threading.Thread | None = None + +# Disk-persistent failure marker — avoids retry across process restarts +_MARKER_TTL = 86400 # 24 hours + + +def _get_hermes_home() -> str: + """Return the Hermes home directory, respecting HERMES_HOME env var.""" + return str(get_hermes_home()) + + +def _failure_marker_path() -> str: + """Return the path to the install-failure marker file.""" + return os.path.join(_get_hermes_home(), ".tirith-install-failed") + + +def _read_failure_reason() -> str | None: + """Read the failure reason from the disk marker. + + Returns the reason string, or None if the marker doesn't exist or is + older than _MARKER_TTL. + """ + try: + p = _failure_marker_path() + mtime = os.path.getmtime(p) + if (time.time() - mtime) >= _MARKER_TTL: + return None + with open(p, "r") as f: + return f.read().strip() + except OSError: + return None + + +def _is_install_failed_on_disk() -> bool: + """Check if a recent install failure was persisted to disk. + + Returns False (allowing retry) when: + - No marker exists + - Marker is older than _MARKER_TTL (24h) + - Marker reason is 'cosign_missing' and cosign is now on PATH + """ + reason = _read_failure_reason() + if reason is None: + return False + if reason == "cosign_missing" and shutil.which("cosign"): + _clear_install_failed() + return False + return True + + +def _mark_install_failed(reason: str = ""): + """Persist install failure to disk to avoid retry on next process. + + Args: + reason: Short tag identifying the failure cause. Use "cosign_missing" + when cosign is not on PATH so the marker can be auto-cleared + once cosign becomes available. + """ + try: + p = _failure_marker_path() + os.makedirs(os.path.dirname(p), exist_ok=True) + with open(p, "w") as f: + f.write(reason) + except OSError: + pass + + +def _clear_install_failed(): + """Remove the failure marker after successful install.""" + try: + os.unlink(_failure_marker_path()) + except OSError: + pass + + +def _hermes_bin_dir() -> str: + """Return $HERMES_HOME/bin, creating it if needed.""" + d = os.path.join(_get_hermes_home(), "bin") + os.makedirs(d, exist_ok=True) + return d + + +def _detect_target() -> str | None: + """Return the Rust target triple for the current platform, or None.""" + system = platform.system() + machine = platform.machine().lower() + + if system == "Darwin": + plat = "apple-darwin" + elif system == "Linux": + plat = "unknown-linux-gnu" + else: + return None + + if machine in ("x86_64", "amd64"): + arch = "x86_64" + elif machine in ("aarch64", "arm64"): + arch = "aarch64" + else: + return None + + return f"{arch}-{plat}" + + +def _download_file(url: str, dest: str, timeout: int = 10): + """Download a URL to a local file.""" + req = urllib.request.Request(url) + token = os.getenv("GITHUB_TOKEN") + if token: + req.add_header("Authorization", f"token {token}") + with urllib.request.urlopen(req, timeout=timeout) as resp, open(dest, "wb") as f: + shutil.copyfileobj(resp, f) + + +def _verify_cosign(checksums_path: str, sig_path: str, cert_path: str) -> bool | None: + """Verify cosign provenance signature on checksums.txt. + + Returns: + True — cosign verified successfully + False — cosign found but verification failed + None — cosign not available (not on PATH, or execution failed) + + The caller treats both False and None as "abort auto-install" — only + True allows the install to proceed. + """ + cosign = shutil.which("cosign") + if not cosign: + logger.info("cosign not found on PATH") + return None + + try: + result = subprocess.run( + [cosign, "verify-blob", + "--certificate", cert_path, + "--signature", sig_path, + "--certificate-identity-regexp", _COSIGN_IDENTITY_REGEXP, + "--certificate-oidc-issuer", _COSIGN_ISSUER, + checksums_path], + capture_output=True, + text=True, + timeout=15, + ) + if result.returncode == 0: + logger.info("cosign provenance verification passed") + return True + else: + logger.warning("cosign verification failed (exit %d): %s", + result.returncode, result.stderr.strip()) + return False + except (OSError, subprocess.TimeoutExpired) as exc: + logger.warning("cosign execution failed: %s", exc) + return None + + +def _verify_checksum(archive_path: str, checksums_path: str, archive_name: str) -> bool: + """Verify SHA-256 of the archive against checksums.txt.""" + expected = None + with open(checksums_path) as f: + for line in f: + # Format: "<hash> <filename>" + parts = line.strip().split(" ", 1) + if len(parts) == 2 and parts[1] == archive_name: + expected = parts[0] + break + if not expected: + logger.warning("No checksum entry for %s", archive_name) + return False + + sha = hashlib.sha256() + with open(archive_path, "rb") as f: + for chunk in iter(lambda: f.read(8192), b""): + sha.update(chunk) + actual = sha.hexdigest() + if actual != expected: + logger.warning("Checksum mismatch: expected %s, got %s", expected, actual) + return False + return True + + +def _install_tirith(*, log_failures: bool = True) -> tuple[str | None, str]: + """Download and install tirith to $HERMES_HOME/bin/tirith. + + Verifies provenance via cosign and SHA-256 checksum. + Returns (installed_path, failure_reason). On success failure_reason is "". + failure_reason is a short tag used by the disk marker to decide if the + failure is retryable (e.g. "cosign_missing" clears when cosign appears). + """ + log = logger.warning if log_failures else logger.debug + + target = _detect_target() + if not target: + logger.info("tirith auto-install: unsupported platform %s/%s", + platform.system(), platform.machine()) + return None, "unsupported_platform" + + archive_name = f"tirith-{target}.tar.gz" + base_url = f"https://github.com/{_REPO}/releases/latest/download" + + tmpdir = tempfile.mkdtemp(prefix="tirith-install-") + try: + archive_path = os.path.join(tmpdir, archive_name) + checksums_path = os.path.join(tmpdir, "checksums.txt") + sig_path = os.path.join(tmpdir, "checksums.txt.sig") + cert_path = os.path.join(tmpdir, "checksums.txt.pem") + + logger.info("tirith not found — downloading latest release for %s...", target) + + try: + _download_file(f"{base_url}/{archive_name}", archive_path) + _download_file(f"{base_url}/checksums.txt", checksums_path) + except Exception as exc: + log("tirith download failed: %s", exc) + return None, "download_failed" + + # Cosign provenance verification — preferred but not mandatory. + # When cosign is available, we verify that the release was produced + # by the expected GitHub Actions workflow (full supply chain proof). + # Without cosign, SHA-256 checksum + HTTPS still provides integrity + # and transport-level authenticity. + cosign_verified = False + if shutil.which("cosign"): + try: + _download_file(f"{base_url}/checksums.txt.sig", sig_path) + _download_file(f"{base_url}/checksums.txt.pem", cert_path) + except Exception as exc: + logger.info("cosign artifacts unavailable (%s), proceeding with SHA-256 only", exc) + else: + cosign_result = _verify_cosign(checksums_path, sig_path, cert_path) + if cosign_result is True: + cosign_verified = True + elif cosign_result is False: + # Verification explicitly rejected — abort, the release + # may have been tampered with. + log("tirith install aborted: cosign provenance verification failed") + return None, "cosign_verification_failed" + else: + # None = execution failure (timeout/OSError) — proceed + # with SHA-256 only since cosign itself is broken. + logger.info("cosign execution failed, proceeding with SHA-256 only") + else: + logger.info("cosign not on PATH — installing tirith with SHA-256 verification only " + "(install cosign for full supply chain verification)") + + if not _verify_checksum(archive_path, checksums_path, archive_name): + return None, "checksum_failed" + + with tarfile.open(archive_path, "r:gz") as tar: + # Extract only the tirith binary (safety: reject paths with ..) + for member in tar.getmembers(): + if member.name == "tirith" or member.name.endswith("/tirith"): + if ".." in member.name: + continue + member.name = "tirith" + tar.extract(member, tmpdir) + break + else: + log("tirith binary not found in archive") + return None, "binary_not_in_archive" + + src = os.path.join(tmpdir, "tirith") + dest = os.path.join(_hermes_bin_dir(), "tirith") + shutil.move(src, dest) + os.chmod(dest, os.stat(dest).st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH) + + verification = "cosign + SHA-256" if cosign_verified else "SHA-256 only" + logger.info("tirith installed to %s (%s)", dest, verification) + return dest, "" + + finally: + shutil.rmtree(tmpdir, ignore_errors=True) + + +def _is_explicit_path(configured_path: str) -> bool: + """Return True if the user explicitly configured a non-default tirith path.""" + return configured_path != "tirith" + + +def _resolve_tirith_path(configured_path: str) -> str: + """Resolve the tirith binary path, auto-installing if necessary. + + If the user explicitly set a path (anything other than the bare "tirith" + default), that path is authoritative — we never fall through to + auto-download a different binary. + + For the default "tirith": + 1. PATH lookup via shutil.which + 2. $HERMES_HOME/bin/tirith (previously auto-installed) + 3. Auto-install from GitHub releases → $HERMES_HOME/bin/tirith + + Failed installs are cached for the process lifetime (and persisted to + disk for 24h) to avoid repeated network attempts. + """ + global _resolved_path, _install_failure_reason + + # Fast path: successfully resolved on a previous call. + if _resolved_path is not None and _resolved_path is not _INSTALL_FAILED: + return _resolved_path + + expanded = os.path.expanduser(configured_path) + explicit = _is_explicit_path(configured_path) + install_failed = _resolved_path is _INSTALL_FAILED + + # Explicit path: check it and stop. Never auto-download a replacement. + if explicit: + if os.path.isfile(expanded) and os.access(expanded, os.X_OK): + _resolved_path = expanded + return expanded + # Also try shutil.which in case it's a bare name on PATH + found = shutil.which(expanded) + if found: + _resolved_path = found + return found + logger.warning("Configured tirith path %r not found; scanning disabled", configured_path) + _resolved_path = _INSTALL_FAILED + _install_failure_reason = "explicit_path_missing" + return expanded + + # Default "tirith" — always re-run cheap local checks so a manual + # install is picked up even after a previous network failure (P2 fix: + # long-lived gateway/CLI recovers without restart). + found = shutil.which("tirith") + if found: + _resolved_path = found + _install_failure_reason = "" + _clear_install_failed() + return found + + hermes_bin = os.path.join(_hermes_bin_dir(), "tirith") + if os.path.isfile(hermes_bin) and os.access(hermes_bin, os.X_OK): + _resolved_path = hermes_bin + _install_failure_reason = "" + _clear_install_failed() + return hermes_bin + + # Local checks failed. If a previous install attempt already failed, + # skip the network retry — UNLESS the failure was "cosign_missing" and + # cosign is now available (retryable cause resolved in-process). + if install_failed: + if _install_failure_reason == "cosign_missing" and shutil.which("cosign"): + # Retryable cause resolved — clear sentinel and fall through to retry + _resolved_path = None + _install_failure_reason = "" + _clear_install_failed() + install_failed = False + else: + return expanded + + # If a background install thread is running, don't start a parallel one — + # return the configured path; the OSError handler in check_command_security + # will apply fail_open until the thread finishes. + if _install_thread is not None and _install_thread.is_alive(): + return expanded + + # Check disk failure marker before attempting network download. + # Preserve the marker's real reason so in-memory retry logic can + # detect retryable causes (e.g. cosign_missing) without restart. + disk_reason = _read_failure_reason() + if disk_reason is not None and _is_install_failed_on_disk(): + _resolved_path = _INSTALL_FAILED + _install_failure_reason = disk_reason + return expanded + + installed, reason = _install_tirith() + if installed: + _resolved_path = installed + _install_failure_reason = "" + _clear_install_failed() + return installed + + # Install failed — cache the miss and persist reason to disk + _resolved_path = _INSTALL_FAILED + _install_failure_reason = reason + _mark_install_failed(reason) + return expanded + + +def _background_install(*, log_failures: bool = True): + """Background thread target: download and install tirith.""" + global _resolved_path, _install_failure_reason + with _install_lock: + # Double-check after acquiring lock (another thread may have resolved) + if _resolved_path is not None: + return + + # Re-check local paths (may have been installed by another process) + found = shutil.which("tirith") + if found: + _resolved_path = found + _install_failure_reason = "" + return + + hermes_bin = os.path.join(_hermes_bin_dir(), "tirith") + if os.path.isfile(hermes_bin) and os.access(hermes_bin, os.X_OK): + _resolved_path = hermes_bin + _install_failure_reason = "" + return + + installed, reason = _install_tirith(log_failures=log_failures) + if installed: + _resolved_path = installed + _install_failure_reason = "" + _clear_install_failed() + else: + _resolved_path = _INSTALL_FAILED + _install_failure_reason = reason + _mark_install_failed(reason) + + +def ensure_installed(*, log_failures: bool = True): + """Ensure tirith is available, downloading in background if needed. + + Quick PATH/local checks are synchronous; network download runs in a + daemon thread so startup never blocks. Safe to call multiple times. + Returns the resolved path immediately if available, or None. + """ + global _resolved_path, _install_thread, _install_failure_reason + + cfg = _load_security_config() + if not cfg["tirith_enabled"]: + return None + + # Already resolved from a previous call + if _resolved_path is not None and _resolved_path is not _INSTALL_FAILED: + path = _resolved_path + if os.path.isfile(path) and os.access(path, os.X_OK): + return path + return None + + configured_path = cfg["tirith_path"] + explicit = _is_explicit_path(configured_path) + expanded = os.path.expanduser(configured_path) + + # Explicit path: synchronous check only, no download + if explicit: + if os.path.isfile(expanded) and os.access(expanded, os.X_OK): + _resolved_path = expanded + return expanded + found = shutil.which(expanded) + if found: + _resolved_path = found + return found + _resolved_path = _INSTALL_FAILED + _install_failure_reason = "explicit_path_missing" + return None + + # Default "tirith" — quick local checks first (no network) + found = shutil.which("tirith") + if found: + _resolved_path = found + _install_failure_reason = "" + _clear_install_failed() + return found + + hermes_bin = os.path.join(_hermes_bin_dir(), "tirith") + if os.path.isfile(hermes_bin) and os.access(hermes_bin, os.X_OK): + _resolved_path = hermes_bin + _install_failure_reason = "" + _clear_install_failed() + return hermes_bin + + # If previously failed in-memory, check if the cause is now resolved + if _resolved_path is _INSTALL_FAILED: + if _install_failure_reason == "cosign_missing" and shutil.which("cosign"): + _resolved_path = None + _install_failure_reason = "" + _clear_install_failed() + else: + return None + + # Check disk failure marker (skip network attempt for 24h, unless + # the cosign_missing reason was resolved — handled by _is_install_failed_on_disk). + # Preserve the marker's real reason for in-memory retry logic. + disk_reason = _read_failure_reason() + if disk_reason is not None and _is_install_failed_on_disk(): + _resolved_path = _INSTALL_FAILED + _install_failure_reason = disk_reason + return None + + # Need to download — launch background thread so startup doesn't block + if _install_thread is None or not _install_thread.is_alive(): + _install_thread = threading.Thread( + target=_background_install, + kwargs={"log_failures": log_failures}, + daemon=True, + ) + _install_thread.start() + + return None # Not available yet; commands will fail-open until ready + + +# --------------------------------------------------------------------------- +# Main API +# --------------------------------------------------------------------------- + +_MAX_FINDINGS = 50 +_MAX_SUMMARY_LEN = 500 + + +def check_command_security(command: str) -> dict: + """Run tirith security scan on a command. + + Exit code determines action (0=allow, 1=block, 2=warn). JSON enriches + findings/summary. Spawn failures and timeouts respect fail_open config. + Programming errors propagate. + + Returns: + {"action": "allow"|"warn"|"block", "findings": [...], "summary": str} + """ + cfg = _load_security_config() + + if not cfg["tirith_enabled"]: + return {"action": "allow", "findings": [], "summary": ""} + + tirith_path = _resolve_tirith_path(cfg["tirith_path"]) + timeout = cfg["tirith_timeout"] + fail_open = cfg["tirith_fail_open"] + + try: + result = subprocess.run( + [tirith_path, "check", "--json", "--non-interactive", + "--shell", "posix", "--", command], + capture_output=True, + text=True, + timeout=timeout, + ) + except OSError as exc: + # Covers FileNotFoundError, PermissionError, exec format error + logger.warning("tirith spawn failed: %s", exc) + if fail_open: + return {"action": "allow", "findings": [], "summary": f"tirith unavailable: {exc}"} + return {"action": "block", "findings": [], "summary": f"tirith spawn failed (fail-closed): {exc}"} + except subprocess.TimeoutExpired: + logger.warning("tirith timed out after %ds", timeout) + if fail_open: + return {"action": "allow", "findings": [], "summary": f"tirith timed out ({timeout}s)"} + return {"action": "block", "findings": [], "summary": "tirith timed out (fail-closed)"} + + # Map exit code to action + exit_code = result.returncode + if exit_code == 0: + action = "allow" + elif exit_code == 1: + action = "block" + elif exit_code == 2: + action = "warn" + else: + # Unknown exit code — respect fail_open + logger.warning("tirith returned unexpected exit code %d", exit_code) + if fail_open: + return {"action": "allow", "findings": [], "summary": f"tirith exit code {exit_code} (fail-open)"} + return {"action": "block", "findings": [], "summary": f"tirith exit code {exit_code} (fail-closed)"} + + # Parse JSON for enrichment (never overrides the exit code verdict) + findings = [] + summary = "" + try: + data = json.loads(result.stdout) if result.stdout.strip() else {} + raw_findings = data.get("findings", []) + findings = raw_findings[:_MAX_FINDINGS] + summary = (data.get("summary", "") or "")[:_MAX_SUMMARY_LEN] + except (json.JSONDecodeError, AttributeError): + # JSON parse failure degrades findings/summary, not the verdict + logger.debug("tirith JSON parse failed, using exit code only") + if action == "block": + summary = "security issue detected (details unavailable)" + elif action == "warn": + summary = "security warning detected (details unavailable)" + + return {"action": action, "findings": findings, "summary": summary} diff --git a/mindcli/_vendor/tools/todo_tool.py b/mindcli/_vendor/tools/todo_tool.py new file mode 100644 index 0000000..b0d38a2 --- /dev/null +++ b/mindcli/_vendor/tools/todo_tool.py @@ -0,0 +1,277 @@ +#!/usr/bin/env python3 +""" +Todo Tool Module - Planning & Task Management + +Provides an in-memory task list the agent uses to decompose complex tasks, +track progress, and maintain focus across long conversations. The state +lives on the AIAgent instance (one per session) and is re-injected into +the conversation after context compression events. + +Design: +- Single `todo` tool: provide `todos` param to write, omit to read +- Every call returns the full current list +- No system prompt mutation, no tool response modification +- Behavioral guidance lives entirely in the tool schema description +""" + +import json +from typing import Dict, Any, List, Optional + + +# Valid status values for todo items +VALID_STATUSES = {"pending", "in_progress", "completed", "cancelled"} + + +class TodoStore: + """ + In-memory todo list. One instance per AIAgent (one per session). + + Items are ordered -- list position is priority. Each item has: + - id: unique string identifier (agent-chosen) + - content: task description + - status: pending | in_progress | completed | cancelled + """ + + def __init__(self): + self._items: List[Dict[str, str]] = [] + + def write(self, todos: List[Dict[str, Any]], merge: bool = False) -> List[Dict[str, str]]: + """ + Write todos. Returns the full current list after writing. + + Args: + todos: list of {id, content, status} dicts + merge: if False, replace the entire list. If True, update + existing items by id and append new ones. + """ + if not merge: + # Replace mode: new list entirely + self._items = [self._validate(t) for t in self._dedupe_by_id(todos)] + else: + # Merge mode: update existing items by id, append new ones + existing = {item["id"]: item for item in self._items} + for t in self._dedupe_by_id(todos): + item_id = str(t.get("id", "")).strip() + if not item_id: + continue # Can't merge without an id + + if item_id in existing: + # Update only the fields the LLM actually provided + if "content" in t and t["content"]: + existing[item_id]["content"] = str(t["content"]).strip() + if "status" in t and t["status"]: + status = str(t["status"]).strip().lower() + if status in VALID_STATUSES: + existing[item_id]["status"] = status + else: + # New item -- validate fully and append to end + validated = self._validate(t) + existing[validated["id"]] = validated + self._items.append(validated) + # Rebuild _items preserving order for existing items + seen = set() + rebuilt = [] + for item in self._items: + current = existing.get(item["id"], item) + if current["id"] not in seen: + rebuilt.append(current) + seen.add(current["id"]) + self._items = rebuilt + return self.read() + + def read(self) -> List[Dict[str, str]]: + """Return a copy of the current list.""" + return [item.copy() for item in self._items] + + def has_items(self) -> bool: + """Check if there are any items in the list.""" + return bool(self._items) + + def format_for_injection(self) -> Optional[str]: + """ + Render the todo list for post-compression injection. + + Returns a human-readable string to append to the compressed + message history, or None if the list is empty. + """ + if not self._items: + return None + + # Status markers for compact display + markers = { + "completed": "[x]", + "in_progress": "[>]", + "pending": "[ ]", + "cancelled": "[~]", + } + + # Only inject pending/in_progress items — completed/cancelled ones + # cause the model to re-do finished work after compression. + active_items = [ + item for item in self._items + if item["status"] in ("pending", "in_progress") + ] + if not active_items: + return None + + lines = ["[Your active task list was preserved across context compression]"] + for item in active_items: + marker = markers.get(item["status"], "[?]") + lines.append(f"- {marker} {item['id']}. {item['content']} ({item['status']})") + + return "\n".join(lines) + + @staticmethod + def _validate(item: Dict[str, Any]) -> Dict[str, str]: + """ + Validate and normalize a todo item. + + Ensures required fields exist and status is valid. + Returns a clean dict with only {id, content, status}. + """ + item_id = str(item.get("id", "")).strip() + if not item_id: + item_id = "?" + + content = str(item.get("content", "")).strip() + if not content: + content = "(no description)" + + status = str(item.get("status", "pending")).strip().lower() + if status not in VALID_STATUSES: + status = "pending" + + return {"id": item_id, "content": content, "status": status} + + @staticmethod + def _dedupe_by_id(todos: List[Dict[str, Any]]) -> List[Dict[str, Any]]: + """Collapse duplicate ids, keeping the last occurrence in its position.""" + last_index: Dict[str, int] = {} + for i, item in enumerate(todos): + item_id = str(item.get("id", "")).strip() or "?" + last_index[item_id] = i + return [todos[i] for i in sorted(last_index.values())] + + +def todo_tool( + todos: Optional[List[Dict[str, Any]]] = None, + merge: bool = False, + store: Optional[TodoStore] = None, +) -> str: + """ + Single entry point for the todo tool. Reads or writes depending on params. + + Args: + todos: if provided, write these items. If None, read current list. + merge: if True, update by id. If False (default), replace entire list. + store: the TodoStore instance from the AIAgent. + + Returns: + JSON string with the full current list and summary metadata. + """ + if store is None: + return tool_error("TodoStore not initialized") + + if todos is not None: + items = store.write(todos, merge) + else: + items = store.read() + + # Build summary counts + pending = sum(1 for i in items if i["status"] == "pending") + in_progress = sum(1 for i in items if i["status"] == "in_progress") + completed = sum(1 for i in items if i["status"] == "completed") + cancelled = sum(1 for i in items if i["status"] == "cancelled") + + return json.dumps({ + "todos": items, + "summary": { + "total": len(items), + "pending": pending, + "in_progress": in_progress, + "completed": completed, + "cancelled": cancelled, + }, + }, ensure_ascii=False) + + +def check_todo_requirements() -> bool: + """Todo tool has no external requirements -- always available.""" + return True + + +# ============================================================================= +# OpenAI Function-Calling Schema +# ============================================================================= +# Behavioral guidance is baked into the description so it's part of the +# static tool schema (cached, never changes mid-conversation). + +TODO_SCHEMA = { + "name": "todo", + "description": ( + "Manage your task list for the current session. Use for complex tasks " + "with 3+ steps or when the user provides multiple tasks. " + "Call with no parameters to read the current list.\n\n" + "Writing:\n" + "- Provide 'todos' array to create/update items\n" + "- merge=false (default): replace the entire list with a fresh plan\n" + "- merge=true: update existing items by id, add any new ones\n\n" + "Each item: {id: string, content: string, " + "status: pending|in_progress|completed|cancelled}\n" + "List order is priority. Only ONE item in_progress at a time.\n" + "Mark items completed immediately when done. If something fails, " + "cancel it and add a revised item.\n\n" + "Always returns the full current list." + ), + "parameters": { + "type": "object", + "properties": { + "todos": { + "type": "array", + "description": "Task items to write. Omit to read current list.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique item identifier" + }, + "content": { + "type": "string", + "description": "Task description" + }, + "status": { + "type": "string", + "enum": ["pending", "in_progress", "completed", "cancelled"], + "description": "Current status" + } + }, + "required": ["id", "content", "status"] + } + }, + "merge": { + "type": "boolean", + "description": ( + "true: update existing items by id, add new ones. " + "false (default): replace the entire list." + ), + "default": False + } + }, + "required": [] + } +} + + +# --- Registry --- +from tools.registry import registry, tool_error + +registry.register( + name="todo", + toolset="todo", + schema=TODO_SCHEMA, + handler=lambda args, **kw: todo_tool( + todos=args.get("todos"), merge=args.get("merge", False), store=kw.get("store")), + check_fn=check_todo_requirements, + emoji="📋", +) diff --git a/mindcli/_vendor/tools/tool_backend_helpers.py b/mindcli/_vendor/tools/tool_backend_helpers.py new file mode 100644 index 0000000..b65e191 --- /dev/null +++ b/mindcli/_vendor/tools/tool_backend_helpers.py @@ -0,0 +1,89 @@ +"""Shared helpers for tool backend selection.""" + +from __future__ import annotations + +import os +from pathlib import Path +from typing import Any, Dict + +from utils import env_var_enabled + +_DEFAULT_BROWSER_PROVIDER = "local" +_DEFAULT_MODAL_MODE = "auto" +_VALID_MODAL_MODES = {"auto", "direct", "managed"} + + +def managed_nous_tools_enabled() -> bool: + """Return True when the hidden Nous-managed tools feature flag is enabled.""" + return env_var_enabled("HERMES_ENABLE_NOUS_MANAGED_TOOLS") + + +def normalize_browser_cloud_provider(value: object | None) -> str: + """Return a normalized browser provider key.""" + provider = str(value or _DEFAULT_BROWSER_PROVIDER).strip().lower() + return provider or _DEFAULT_BROWSER_PROVIDER + + +def coerce_modal_mode(value: object | None) -> str: + """Return the requested modal mode when valid, else the default.""" + mode = str(value or _DEFAULT_MODAL_MODE).strip().lower() + if mode in _VALID_MODAL_MODES: + return mode + return _DEFAULT_MODAL_MODE + + +def normalize_modal_mode(value: object | None) -> str: + """Return a normalized modal execution mode.""" + return coerce_modal_mode(value) + + +def has_direct_modal_credentials() -> bool: + """Return True when direct Modal credentials/config are available.""" + return bool( + (os.getenv("MODAL_TOKEN_ID") and os.getenv("MODAL_TOKEN_SECRET")) + or (Path.home() / ".modal.toml").exists() + ) + + +def resolve_modal_backend_state( + modal_mode: object | None, + *, + has_direct: bool, + managed_ready: bool, +) -> Dict[str, Any]: + """Resolve direct vs managed Modal backend selection. + + Semantics: + - ``direct`` means direct-only + - ``managed`` means managed-only + - ``auto`` prefers managed when available, then falls back to direct + """ + requested_mode = coerce_modal_mode(modal_mode) + normalized_mode = normalize_modal_mode(modal_mode) + managed_mode_blocked = ( + requested_mode == "managed" and not managed_nous_tools_enabled() + ) + + if normalized_mode == "managed": + selected_backend = "managed" if managed_nous_tools_enabled() and managed_ready else None + elif normalized_mode == "direct": + selected_backend = "direct" if has_direct else None + else: + selected_backend = "managed" if managed_nous_tools_enabled() and managed_ready else "direct" if has_direct else None + + return { + "requested_mode": requested_mode, + "mode": normalized_mode, + "has_direct": has_direct, + "managed_ready": managed_ready, + "managed_mode_blocked": managed_mode_blocked, + "selected_backend": selected_backend, + } + + +def resolve_openai_audio_api_key() -> str: + """Prefer the voice-tools key, but fall back to the normal OpenAI key.""" + return ( + os.getenv("VOICE_TOOLS_OPENAI_KEY", "") + or os.getenv("OPENAI_API_KEY", "") + ).strip() diff --git a/mindcli/_vendor/tools/tool_result_storage.py b/mindcli/_vendor/tools/tool_result_storage.py new file mode 100644 index 0000000..4342264 --- /dev/null +++ b/mindcli/_vendor/tools/tool_result_storage.py @@ -0,0 +1,226 @@ +"""Tool result persistence -- preserves large outputs instead of truncating. + +Defense against context-window overflow operates at three levels: + +1. **Per-tool output cap** (inside each tool): Tools like search_files + pre-truncate their own output before returning. This is the first line + of defense and the only one the tool author controls. + +2. **Per-result persistence** (maybe_persist_tool_result): After a tool + returns, if its output exceeds the tool's registered threshold + (registry.get_max_result_size), the full output is written INTO THE + SANDBOX temp dir (for example /tmp/hermes-results/{tool_use_id}.txt on + standard Linux, or $TMPDIR/hermes-results/{tool_use_id}.txt on Termux) + via env.execute(). The in-context content is replaced with a preview + + file path reference. The model can read_file to access the full output + on any backend. + +3. **Per-turn aggregate budget** (enforce_turn_budget): After all tool + results in a single assistant turn are collected, if the total exceeds + MAX_TURN_BUDGET_CHARS (200K), the largest non-persisted results are + spilled to disk until the aggregate is under budget. This catches cases + where many medium-sized results combine to overflow context. +""" + +import logging +import os +import shlex +import uuid + +from tools.budget_config import ( + DEFAULT_PREVIEW_SIZE_CHARS, + BudgetConfig, + DEFAULT_BUDGET, +) + +logger = logging.getLogger(__name__) +PERSISTED_OUTPUT_TAG = "<persisted-output>" +PERSISTED_OUTPUT_CLOSING_TAG = "</persisted-output>" +STORAGE_DIR = "/tmp/hermes-results" +HEREDOC_MARKER = "HERMES_PERSIST_EOF" +_BUDGET_TOOL_NAME = "__budget_enforcement__" + + +def _resolve_storage_dir(env) -> str: + """Return the best temp-backed storage dir for this environment.""" + if env is not None: + get_temp_dir = getattr(env, "get_temp_dir", None) + if callable(get_temp_dir): + try: + temp_dir = get_temp_dir() + except Exception as exc: + logger.debug("Could not resolve env temp dir: %s", exc) + else: + if temp_dir: + temp_dir = temp_dir.rstrip("/") or "/" + return f"{temp_dir}/hermes-results" + return STORAGE_DIR + + +def generate_preview(content: str, max_chars: int = DEFAULT_PREVIEW_SIZE_CHARS) -> tuple[str, bool]: + """Truncate at last newline within max_chars. Returns (preview, has_more).""" + if len(content) <= max_chars: + return content, False + truncated = content[:max_chars] + last_nl = truncated.rfind("\n") + if last_nl > max_chars // 2: + truncated = truncated[:last_nl + 1] + return truncated, True + + +def _heredoc_marker(content: str) -> str: + """Return a heredoc delimiter that doesn't collide with content.""" + if HEREDOC_MARKER not in content: + return HEREDOC_MARKER + return f"HERMES_PERSIST_{uuid.uuid4().hex[:8]}" + + +def _write_to_sandbox(content: str, remote_path: str, env) -> bool: + """Write content into the sandbox via env.execute(). Returns True on success.""" + marker = _heredoc_marker(content) + storage_dir = os.path.dirname(remote_path) + cmd = ( + f"mkdir -p {shlex.quote(storage_dir)} && cat > {shlex.quote(remote_path)} << '{marker}'\n" + f"{content}\n" + f"{marker}" + ) + result = env.execute(cmd, timeout=30) + return result.get("returncode", 1) == 0 + + +def _build_persisted_message( + preview: str, + has_more: bool, + original_size: int, + file_path: str, +) -> str: + """Build the <persisted-output> replacement block.""" + size_kb = original_size / 1024 + if size_kb >= 1024: + size_str = f"{size_kb / 1024:.1f} MB" + else: + size_str = f"{size_kb:.1f} KB" + + msg = f"{PERSISTED_OUTPUT_TAG}\n" + msg += f"This tool result was too large ({original_size:,} characters, {size_str}).\n" + msg += f"Full output saved to: {file_path}\n" + msg += "Use the read_file tool with offset and limit to access specific sections of this output.\n\n" + msg += f"Preview (first {len(preview)} chars):\n" + msg += preview + if has_more: + msg += "\n..." + msg += f"\n{PERSISTED_OUTPUT_CLOSING_TAG}" + return msg + + +def maybe_persist_tool_result( + content: str, + tool_name: str, + tool_use_id: str, + env=None, + config: BudgetConfig = DEFAULT_BUDGET, + threshold: int | float | None = None, +) -> str: + """Layer 2: persist oversized result into the sandbox, return preview + path. + + Writes via env.execute() so the file is accessible from any backend + (local, Docker, SSH, Modal, Daytona). Falls back to inline truncation + if write fails or no env is available. + + Args: + content: Raw tool result string. + tool_name: Name of the tool (used for threshold lookup). + tool_use_id: Unique ID for this tool call (used as filename). + env: The active BaseEnvironment instance, or None. + config: BudgetConfig controlling thresholds and preview size. + threshold: Explicit override; takes precedence over config resolution. + + Returns: + Original content if small, or <persisted-output> replacement. + """ + effective_threshold = threshold if threshold is not None else config.resolve_threshold(tool_name) + + if effective_threshold == float("inf"): + return content + + if len(content) <= effective_threshold: + return content + + storage_dir = _resolve_storage_dir(env) + remote_path = f"{storage_dir}/{tool_use_id}.txt" + preview, has_more = generate_preview(content, max_chars=config.preview_size) + + if env is not None: + try: + if _write_to_sandbox(content, remote_path, env): + logger.info( + "Persisted large tool result: %s (%s, %d chars -> %s)", + tool_name, tool_use_id, len(content), remote_path, + ) + return _build_persisted_message(preview, has_more, len(content), remote_path) + except Exception as exc: + logger.warning("Sandbox write failed for %s: %s", tool_use_id, exc) + + logger.info( + "Inline-truncating large tool result: %s (%d chars, no sandbox write)", + tool_name, len(content), + ) + return ( + f"{preview}\n\n" + f"[Truncated: tool response was {len(content):,} chars. " + f"Full output could not be saved to sandbox.]" + ) + + +def enforce_turn_budget( + tool_messages: list[dict], + env=None, + config: BudgetConfig = DEFAULT_BUDGET, +) -> list[dict]: + """Layer 3: enforce aggregate budget across all tool results in a turn. + + If total chars exceed budget, persist the largest non-persisted results + first (via sandbox write) until under budget. Already-persisted results + are skipped. + + Mutates the list in-place and returns it. + """ + candidates = [] + total_size = 0 + for i, msg in enumerate(tool_messages): + content = msg.get("content", "") + size = len(content) + total_size += size + if PERSISTED_OUTPUT_TAG not in content: + candidates.append((i, size)) + + if total_size <= config.turn_budget: + return tool_messages + + candidates.sort(key=lambda x: x[1], reverse=True) + + for idx, size in candidates: + if total_size <= config.turn_budget: + break + msg = tool_messages[idx] + content = msg["content"] + tool_use_id = msg.get("tool_call_id", f"budget_{idx}") + + replacement = maybe_persist_tool_result( + content=content, + tool_name=_BUDGET_TOOL_NAME, + tool_use_id=tool_use_id, + env=env, + config=config, + threshold=0, + ) + if replacement != content: + total_size -= size + total_size += len(replacement) + tool_messages[idx]["content"] = replacement + logger.info( + "Budget enforcement: persisted tool result %s (%d chars)", + tool_use_id, size, + ) + + return tool_messages diff --git a/mindcli/_vendor/tools/transcription_tools.py b/mindcli/_vendor/tools/transcription_tools.py new file mode 100644 index 0000000..3fdf0cc --- /dev/null +++ b/mindcli/_vendor/tools/transcription_tools.py @@ -0,0 +1,677 @@ +#!/usr/bin/env python3 +""" +Transcription Tools Module + +Provides speech-to-text transcription with three providers: + + - **local** (default, free) — faster-whisper running locally, no API key needed. + Auto-downloads the model (~150 MB for ``base``) on first use. + - **groq** (free tier) — Groq Whisper API, requires ``GROQ_API_KEY``. + - **openai** (paid) — OpenAI Whisper API, requires ``VOICE_TOOLS_OPENAI_KEY``. + +Used by the messaging gateway to automatically transcribe voice messages +sent by users on Telegram, Discord, WhatsApp, Slack, and Signal. + +Supported input formats: mp3, mp4, mpeg, mpga, m4a, wav, webm, ogg, aac + +Usage:: + + from tools.transcription_tools import transcribe_audio + + result = transcribe_audio("/path/to/audio.ogg") + if result["success"]: + print(result["transcript"]) +""" + +import logging +import os +import shlex +import shutil +import subprocess +import tempfile +from pathlib import Path +from typing import Optional, Dict, Any +from urllib.parse import urljoin + +from utils import is_truthy_value +from tools.managed_tool_gateway import resolve_managed_tool_gateway +from tools.tool_backend_helpers import managed_nous_tools_enabled, resolve_openai_audio_api_key + +logger = logging.getLogger(__name__) + +# --------------------------------------------------------------------------- +# Optional imports — graceful degradation +# --------------------------------------------------------------------------- + +import importlib.util as _ilu + + +def _safe_find_spec(module_name: str) -> bool: + try: + return _ilu.find_spec(module_name) is not None + except (ImportError, ValueError): + return module_name in globals() or module_name in os.sys.modules + + +_HAS_FASTER_WHISPER = _safe_find_spec("faster_whisper") +_HAS_OPENAI = _safe_find_spec("openai") +_HAS_MISTRAL = _safe_find_spec("mistralai") + +# --------------------------------------------------------------------------- +# Constants +# --------------------------------------------------------------------------- + +DEFAULT_PROVIDER = "local" +DEFAULT_LOCAL_MODEL = "base" +DEFAULT_LOCAL_STT_LANGUAGE = "en" +DEFAULT_STT_MODEL = os.getenv("STT_OPENAI_MODEL", "whisper-1") +DEFAULT_GROQ_STT_MODEL = os.getenv("STT_GROQ_MODEL", "whisper-large-v3-turbo") +DEFAULT_MISTRAL_STT_MODEL = os.getenv("STT_MISTRAL_MODEL", "voxtral-mini-latest") +LOCAL_STT_COMMAND_ENV = "HERMES_LOCAL_STT_COMMAND" +LOCAL_STT_LANGUAGE_ENV = "HERMES_LOCAL_STT_LANGUAGE" +COMMON_LOCAL_BIN_DIRS = ("/opt/homebrew/bin", "/usr/local/bin") + +GROQ_BASE_URL = os.getenv("GROQ_BASE_URL", "https://api.groq.com/openai/v1") +OPENAI_BASE_URL = os.getenv("STT_OPENAI_BASE_URL", "https://api.openai.com/v1") + +SUPPORTED_FORMATS = {".mp3", ".mp4", ".mpeg", ".mpga", ".m4a", ".wav", ".webm", ".ogg", ".aac", ".flac"} +LOCAL_NATIVE_AUDIO_FORMATS = {".wav", ".aiff", ".aif"} +MAX_FILE_SIZE = 25 * 1024 * 1024 # 25 MB + +# Known model sets for auto-correction +OPENAI_MODELS = {"whisper-1", "gpt-4o-mini-transcribe", "gpt-4o-transcribe"} +GROQ_MODELS = {"whisper-large-v3", "whisper-large-v3-turbo", "distil-whisper-large-v3-en"} + +# Singleton for the local model — loaded once, reused across calls +_local_model: Optional[object] = None +_local_model_name: Optional[str] = None + +# --------------------------------------------------------------------------- +# Config helpers +# --------------------------------------------------------------------------- + + + +def _load_stt_config() -> dict: + """Load the ``stt`` section from user config, falling back to defaults.""" + try: + from hermes_cli.config import load_config + return load_config().get("stt", {}) + except Exception: + return {} + + +def is_stt_enabled(stt_config: Optional[dict] = None) -> bool: + """Return whether STT is enabled in config.""" + if stt_config is None: + stt_config = _load_stt_config() + enabled = stt_config.get("enabled", True) + return is_truthy_value(enabled, default=True) + + +def _has_openai_audio_backend() -> bool: + """Return True when OpenAI audio can use config credentials, env credentials, or the managed gateway.""" + try: + _resolve_openai_audio_client_config() + return True + except ValueError: + return False + + +def _find_binary(binary_name: str) -> Optional[str]: + """Find a local binary, checking common Homebrew/local prefixes as well as PATH.""" + for directory in COMMON_LOCAL_BIN_DIRS: + candidate = Path(directory) / binary_name + if candidate.exists() and os.access(candidate, os.X_OK): + return str(candidate) + return shutil.which(binary_name) + + +def _find_ffmpeg_binary() -> Optional[str]: + return _find_binary("ffmpeg") + + +def _find_whisper_binary() -> Optional[str]: + return _find_binary("whisper") + + +def _get_local_command_template() -> Optional[str]: + configured = os.getenv(LOCAL_STT_COMMAND_ENV, "").strip() + if configured: + return configured + + whisper_binary = _find_whisper_binary() + if whisper_binary: + quoted_binary = shlex.quote(whisper_binary) + return ( + f"{quoted_binary} {{input_path}} --model {{model}} --output_format txt " + "--output_dir {output_dir} --language {language}" + ) + return None + + +def _has_local_command() -> bool: + return _get_local_command_template() is not None + + +def _normalize_local_command_model(model_name: Optional[str]) -> str: + if not model_name or model_name in OPENAI_MODELS or model_name in GROQ_MODELS: + return DEFAULT_LOCAL_MODEL + return model_name + + +def _get_provider(stt_config: dict) -> str: + """Determine which STT provider to use. + + When ``stt.provider`` is explicitly set in config, that choice is + honoured — no silent cloud fallback. When no provider is configured, + auto-detect tries: local > groq (free) > openai (paid). + """ + if not is_stt_enabled(stt_config): + return "none" + + explicit = "provider" in stt_config + provider = stt_config.get("provider", DEFAULT_PROVIDER) + + # --- Explicit provider: respect the user's choice ---------------------- + + if explicit: + if provider == "local": + if _HAS_FASTER_WHISPER: + return "local" + if _has_local_command(): + return "local_command" + logger.warning( + "STT provider 'local' configured but unavailable " + "(install faster-whisper or set HERMES_LOCAL_STT_COMMAND)" + ) + return "none" + + if provider == "local_command": + if _has_local_command(): + return "local_command" + if _HAS_FASTER_WHISPER: + logger.info("Local STT command unavailable, using local faster-whisper") + return "local" + logger.warning( + "STT provider 'local_command' configured but unavailable" + ) + return "none" + + if provider == "groq": + if _HAS_OPENAI and os.getenv("GROQ_API_KEY"): + return "groq" + logger.warning( + "STT provider 'groq' configured but GROQ_API_KEY not set" + ) + return "none" + + if provider == "openai": + if _HAS_OPENAI and _has_openai_audio_backend(): + return "openai" + logger.warning( + "STT provider 'openai' configured but no API key available" + ) + return "none" + + if provider == "mistral": + if _HAS_MISTRAL and os.getenv("MISTRAL_API_KEY"): + return "mistral" + logger.warning( + "STT provider 'mistral' configured but mistralai package " + "not installed or MISTRAL_API_KEY not set" + ) + return "none" + + return provider # Unknown — let it fail downstream + + # --- Auto-detect (no explicit provider): local > groq > openai > mistral - + + if _HAS_FASTER_WHISPER: + return "local" + if _has_local_command(): + return "local_command" + if _HAS_OPENAI and os.getenv("GROQ_API_KEY"): + logger.info("No local STT available, using Groq Whisper API") + return "groq" + if _HAS_OPENAI and _has_openai_audio_backend(): + logger.info("No local STT available, using OpenAI Whisper API") + return "openai" + if _HAS_MISTRAL and os.getenv("MISTRAL_API_KEY"): + logger.info("No local STT available, using Mistral Voxtral Transcribe API") + return "mistral" + return "none" + +# --------------------------------------------------------------------------- +# Shared validation +# --------------------------------------------------------------------------- + + +def _validate_audio_file(file_path: str) -> Optional[Dict[str, Any]]: + """Validate the audio file. Returns an error dict or None if OK.""" + audio_path = Path(file_path) + + if not audio_path.exists(): + return {"success": False, "transcript": "", "error": f"Audio file not found: {file_path}"} + if not audio_path.is_file(): + return {"success": False, "transcript": "", "error": f"Path is not a file: {file_path}"} + if audio_path.suffix.lower() not in SUPPORTED_FORMATS: + return { + "success": False, + "transcript": "", + "error": f"Unsupported format: {audio_path.suffix}. Supported: {', '.join(sorted(SUPPORTED_FORMATS))}", + } + try: + file_size = audio_path.stat().st_size + if file_size > MAX_FILE_SIZE: + return { + "success": False, + "transcript": "", + "error": f"File too large: {file_size / (1024*1024):.1f}MB (max {MAX_FILE_SIZE / (1024*1024):.0f}MB)", + } + except OSError as e: + return {"success": False, "transcript": "", "error": f"Failed to access file: {e}"} + + return None + +# --------------------------------------------------------------------------- +# Provider: local (faster-whisper) +# --------------------------------------------------------------------------- + + +def _transcribe_local(file_path: str, model_name: str) -> Dict[str, Any]: + """Transcribe using faster-whisper (local, free).""" + global _local_model, _local_model_name + + if not _HAS_FASTER_WHISPER: + return {"success": False, "transcript": "", "error": "faster-whisper not installed"} + + try: + from faster_whisper import WhisperModel + # Lazy-load the model (downloads on first use, ~150 MB for 'base') + if _local_model is None or _local_model_name != model_name: + logger.info("Loading faster-whisper model '%s' (first load downloads the model)...", model_name) + _local_model = WhisperModel(model_name, device="auto", compute_type="auto") + _local_model_name = model_name + + # Language: config.yaml (stt.local.language) > env var > auto-detect. + _forced_lang = ( + _load_stt_config().get("local", {}).get("language") + or os.getenv(LOCAL_STT_LANGUAGE_ENV) + or None + ) + transcribe_kwargs = {"beam_size": 5} + if _forced_lang: + transcribe_kwargs["language"] = _forced_lang + + segments, info = _local_model.transcribe(file_path, **transcribe_kwargs) + transcript = " ".join(segment.text.strip() for segment in segments) + + logger.info( + "Transcribed %s via local whisper (%s, lang=%s, %.1fs audio)", + Path(file_path).name, model_name, info.language, info.duration, + ) + + return {"success": True, "transcript": transcript, "provider": "local"} + + except Exception as e: + logger.error("Local transcription failed: %s", e, exc_info=True) + return {"success": False, "transcript": "", "error": f"Local transcription failed: {e}"} + + +def _prepare_local_audio(file_path: str, work_dir: str) -> tuple[Optional[str], Optional[str]]: + """Normalize audio for local CLI STT when needed.""" + audio_path = Path(file_path) + if audio_path.suffix.lower() in LOCAL_NATIVE_AUDIO_FORMATS: + return file_path, None + + ffmpeg = _find_ffmpeg_binary() + if not ffmpeg: + return None, "Local STT fallback requires ffmpeg for non-WAV inputs, but ffmpeg was not found" + + converted_path = os.path.join(work_dir, f"{audio_path.stem}.wav") + command = [ffmpeg, "-y", "-i", file_path, converted_path] + + try: + subprocess.run(command, check=True, capture_output=True, text=True) + return converted_path, None + except subprocess.CalledProcessError as e: + details = e.stderr.strip() or e.stdout.strip() or str(e) + logger.error("ffmpeg conversion failed for %s: %s", file_path, details) + return None, f"Failed to convert audio for local STT: {details}" + + +def _transcribe_local_command(file_path: str, model_name: str) -> Dict[str, Any]: + """Run the configured local STT command template and read back a .txt transcript.""" + command_template = _get_local_command_template() + if not command_template: + return { + "success": False, + "transcript": "", + "error": ( + f"{LOCAL_STT_COMMAND_ENV} not configured and no local whisper binary was found" + ), + } + + # Language: config.yaml (stt.local.language) > env var > "en" default. + language = ( + _load_stt_config().get("local", {}).get("language") + or os.getenv(LOCAL_STT_LANGUAGE_ENV) + or DEFAULT_LOCAL_STT_LANGUAGE + ) + normalized_model = _normalize_local_command_model(model_name) + + try: + with tempfile.TemporaryDirectory(prefix="hermes-local-stt-") as output_dir: + prepared_input, prep_error = _prepare_local_audio(file_path, output_dir) + if prep_error: + return {"success": False, "transcript": "", "error": prep_error} + + command = command_template.format( + input_path=shlex.quote(prepared_input), + output_dir=shlex.quote(output_dir), + language=shlex.quote(language), + model=shlex.quote(normalized_model), + ) + subprocess.run(command, shell=True, check=True, capture_output=True, text=True) + + txt_files = sorted(Path(output_dir).glob("*.txt")) + if not txt_files: + return { + "success": False, + "transcript": "", + "error": "Local STT command completed but did not produce a .txt transcript", + } + + transcript_text = txt_files[0].read_text(encoding="utf-8").strip() + logger.info( + "Transcribed %s via local STT command (%s, %d chars)", + Path(file_path).name, + normalized_model, + len(transcript_text), + ) + return {"success": True, "transcript": transcript_text, "provider": "local_command"} + + except KeyError as e: + return { + "success": False, + "transcript": "", + "error": f"Invalid {LOCAL_STT_COMMAND_ENV} template, missing placeholder: {e}", + } + except subprocess.CalledProcessError as e: + details = e.stderr.strip() or e.stdout.strip() or str(e) + logger.error("Local STT command failed for %s: %s", file_path, details) + return {"success": False, "transcript": "", "error": f"Local STT failed: {details}"} + except Exception as e: + logger.error("Unexpected error during local command transcription: %s", e, exc_info=True) + return {"success": False, "transcript": "", "error": f"Local transcription failed: {e}"} + +# --------------------------------------------------------------------------- +# Provider: groq (Whisper API — free tier) +# --------------------------------------------------------------------------- + + +def _transcribe_groq(file_path: str, model_name: str) -> Dict[str, Any]: + """Transcribe using Groq Whisper API (free tier available).""" + api_key = os.getenv("GROQ_API_KEY") + if not api_key: + return {"success": False, "transcript": "", "error": "GROQ_API_KEY not set"} + + if not _HAS_OPENAI: + return {"success": False, "transcript": "", "error": "openai package not installed"} + + # Auto-correct model if caller passed an OpenAI-only model + if model_name in OPENAI_MODELS: + logger.info("Model %s not available on Groq, using %s", model_name, DEFAULT_GROQ_STT_MODEL) + model_name = DEFAULT_GROQ_STT_MODEL + + try: + from openai import OpenAI, APIError, APIConnectionError, APITimeoutError + client = OpenAI(api_key=api_key, base_url=GROQ_BASE_URL, timeout=30, max_retries=0) + try: + with open(file_path, "rb") as audio_file: + transcription = client.audio.transcriptions.create( + model=model_name, + file=audio_file, + response_format="text", + ) + + transcript_text = str(transcription).strip() + logger.info("Transcribed %s via Groq API (%s, %d chars)", + Path(file_path).name, model_name, len(transcript_text)) + + return {"success": True, "transcript": transcript_text, "provider": "groq"} + finally: + close = getattr(client, "close", None) + if callable(close): + close() + + except PermissionError: + return {"success": False, "transcript": "", "error": f"Permission denied: {file_path}"} + except APIConnectionError as e: + return {"success": False, "transcript": "", "error": f"Connection error: {e}"} + except APITimeoutError as e: + return {"success": False, "transcript": "", "error": f"Request timeout: {e}"} + except APIError as e: + return {"success": False, "transcript": "", "error": f"API error: {e}"} + except Exception as e: + logger.error("Groq transcription failed: %s", e, exc_info=True) + return {"success": False, "transcript": "", "error": f"Transcription failed: {e}"} + +# --------------------------------------------------------------------------- +# Provider: openai (Whisper API) +# --------------------------------------------------------------------------- + + +def _transcribe_openai(file_path: str, model_name: str) -> Dict[str, Any]: + """Transcribe using OpenAI Whisper API (paid).""" + try: + api_key, base_url = _resolve_openai_audio_client_config() + except ValueError as exc: + return { + "success": False, + "transcript": "", + "error": str(exc), + } + + if not _HAS_OPENAI: + return {"success": False, "transcript": "", "error": "openai package not installed"} + + # Auto-correct model if caller passed a Groq-only model + if model_name in GROQ_MODELS: + logger.info("Model %s not available on OpenAI, using %s", model_name, DEFAULT_STT_MODEL) + model_name = DEFAULT_STT_MODEL + + try: + from openai import OpenAI, APIError, APIConnectionError, APITimeoutError + client = OpenAI(api_key=api_key, base_url=base_url, timeout=30, max_retries=0) + try: + with open(file_path, "rb") as audio_file: + transcription = client.audio.transcriptions.create( + model=model_name, + file=audio_file, + response_format="text" if model_name == "whisper-1" else "json", + ) + + transcript_text = _extract_transcript_text(transcription) + logger.info("Transcribed %s via OpenAI API (%s, %d chars)", + Path(file_path).name, model_name, len(transcript_text)) + + return {"success": True, "transcript": transcript_text, "provider": "openai"} + finally: + close = getattr(client, "close", None) + if callable(close): + close() + + except PermissionError: + return {"success": False, "transcript": "", "error": f"Permission denied: {file_path}"} + except APIConnectionError as e: + return {"success": False, "transcript": "", "error": f"Connection error: {e}"} + except APITimeoutError as e: + return {"success": False, "transcript": "", "error": f"Request timeout: {e}"} + except APIError as e: + return {"success": False, "transcript": "", "error": f"API error: {e}"} + except Exception as e: + logger.error("OpenAI transcription failed: %s", e, exc_info=True) + return {"success": False, "transcript": "", "error": f"Transcription failed: {e}"} + +# --------------------------------------------------------------------------- +# Provider: mistral (Voxtral Transcribe API) +# --------------------------------------------------------------------------- + + +def _transcribe_mistral(file_path: str, model_name: str) -> Dict[str, Any]: + """Transcribe using Mistral Voxtral Transcribe API. + + Uses the ``mistralai`` Python SDK to call ``/v1/audio/transcriptions``. + Requires ``MISTRAL_API_KEY`` environment variable. + """ + api_key = os.getenv("MISTRAL_API_KEY") + if not api_key: + return {"success": False, "transcript": "", "error": "MISTRAL_API_KEY not set"} + + try: + from mistralai.client import Mistral + + with Mistral(api_key=api_key) as client: + with open(file_path, "rb") as audio_file: + result = client.audio.transcriptions.complete( + model=model_name, + file={"content": audio_file, "file_name": Path(file_path).name}, + ) + + transcript_text = _extract_transcript_text(result) + logger.info( + "Transcribed %s via Mistral API (%s, %d chars)", + Path(file_path).name, model_name, len(transcript_text), + ) + return {"success": True, "transcript": transcript_text, "provider": "mistral"} + + except PermissionError: + return {"success": False, "transcript": "", "error": f"Permission denied: {file_path}"} + except Exception as e: + logger.error("Mistral transcription failed: %s", e, exc_info=True) + return {"success": False, "transcript": "", "error": f"Mistral transcription failed: {type(e).__name__}"} + + +# --------------------------------------------------------------------------- +# Public API +# --------------------------------------------------------------------------- + + +def transcribe_audio(file_path: str, model: Optional[str] = None) -> Dict[str, Any]: + """ + Transcribe an audio file using the configured STT provider. + + Provider priority: + 1. User config (``stt.provider`` in config.yaml) + 2. Auto-detect: local faster-whisper (free) > Groq (free tier) > OpenAI (paid) + + Args: + file_path: Absolute path to the audio file to transcribe. + model: Override the model. If None, uses config or provider default. + + Returns: + dict with keys: + - "success" (bool): Whether transcription succeeded + - "transcript" (str): The transcribed text (empty on failure) + - "error" (str, optional): Error message if success is False + - "provider" (str, optional): Which provider was used + """ + # Validate input + error = _validate_audio_file(file_path) + if error: + return error + + # Load config and determine provider + stt_config = _load_stt_config() + if not is_stt_enabled(stt_config): + return { + "success": False, + "transcript": "", + "error": "STT is disabled in config.yaml (stt.enabled: false).", + } + + provider = _get_provider(stt_config) + + if provider == "local": + local_cfg = stt_config.get("local", {}) + model_name = model or local_cfg.get("model", DEFAULT_LOCAL_MODEL) + return _transcribe_local(file_path, model_name) + + if provider == "local_command": + local_cfg = stt_config.get("local", {}) + model_name = _normalize_local_command_model( + model or local_cfg.get("model", DEFAULT_LOCAL_MODEL) + ) + return _transcribe_local_command(file_path, model_name) + + if provider == "groq": + model_name = model or DEFAULT_GROQ_STT_MODEL + return _transcribe_groq(file_path, model_name) + + if provider == "openai": + openai_cfg = stt_config.get("openai", {}) + model_name = model or openai_cfg.get("model", DEFAULT_STT_MODEL) + return _transcribe_openai(file_path, model_name) + + if provider == "mistral": + mistral_cfg = stt_config.get("mistral", {}) + model_name = model or mistral_cfg.get("model", DEFAULT_MISTRAL_STT_MODEL) + return _transcribe_mistral(file_path, model_name) + + # No provider available + return { + "success": False, + "transcript": "", + "error": ( + "No STT provider available. Install faster-whisper for free local " + f"transcription, configure {LOCAL_STT_COMMAND_ENV} or install a local whisper CLI, " + "set GROQ_API_KEY for free Groq Whisper, set MISTRAL_API_KEY for Mistral " + "Voxtral Transcribe, or set VOICE_TOOLS_OPENAI_KEY " + "or OPENAI_API_KEY for the OpenAI Whisper API." + ), + } + + +def _resolve_openai_audio_client_config() -> tuple[str, str]: + """Return direct OpenAI audio config or a managed gateway fallback.""" + stt_config = _load_stt_config() + openai_cfg = stt_config.get("openai", {}) + cfg_api_key = openai_cfg.get("api_key", "") + cfg_base_url = openai_cfg.get("base_url", "") + if cfg_api_key: + return cfg_api_key, (cfg_base_url or OPENAI_BASE_URL) + + direct_api_key = resolve_openai_audio_api_key() + if direct_api_key: + return direct_api_key, OPENAI_BASE_URL + + managed_gateway = resolve_managed_tool_gateway("openai-audio") + if managed_gateway is None: + message = "Neither stt.openai.api_key in config nor VOICE_TOOLS_OPENAI_KEY/OPENAI_API_KEY is set" + if managed_nous_tools_enabled(): + message += ", and the managed OpenAI audio gateway is unavailable" + raise ValueError(message) + + return managed_gateway.nous_user_token, urljoin( + f"{managed_gateway.gateway_origin.rstrip('/')}/", "v1" + ) + + +def _extract_transcript_text(transcription: Any) -> str: + """Normalize text and JSON transcription responses to a plain string.""" + if isinstance(transcription, str): + return transcription.strip() + + if hasattr(transcription, "text"): + value = getattr(transcription, "text") + if isinstance(value, str): + return value.strip() + + if isinstance(transcription, dict): + value = transcription.get("text") + if isinstance(value, str): + return value.strip() + + return str(transcription).strip() diff --git a/mindcli/_vendor/tools/tts_tool.py b/mindcli/_vendor/tools/tts_tool.py new file mode 100644 index 0000000..769ae30 --- /dev/null +++ b/mindcli/_vendor/tools/tts_tool.py @@ -0,0 +1,1069 @@ +#!/usr/bin/env python3 +""" +Text-to-Speech Tool Module + +Supports six TTS providers: +- Edge TTS (default, free, no API key): Microsoft Edge neural voices +- ElevenLabs (premium): High-quality voices, needs ELEVENLABS_API_KEY +- OpenAI TTS: Good quality, needs OPENAI_API_KEY +- MiniMax TTS: High-quality with voice cloning, needs MINIMAX_API_KEY +- Mistral (Voxtral TTS): Multilingual, native Opus, needs MISTRAL_API_KEY +- NeuTTS (local, free, no API key): On-device TTS via neutts_cli, needs neutts installed + +Output formats: +- Opus (.ogg) for Telegram voice bubbles (requires ffmpeg for Edge TTS) +- MP3 (.mp3) for everything else (CLI, Discord, WhatsApp) + +Configuration is loaded from ~/.hermes/config.yaml under the 'tts:' key. +The user chooses the provider and voice; the model just sends text. + +Usage: + from tools.tts_tool import text_to_speech_tool, check_tts_requirements + + result = text_to_speech_tool(text="Hello world") +""" + +import asyncio +import base64 +import datetime +import json +import logging +import os +import queue +import re +import shutil +import subprocess +import tempfile +import threading +import uuid +from pathlib import Path +from typing import Callable, Dict, Any, Optional +from urllib.parse import urljoin + +logger = logging.getLogger(__name__) +from tools.managed_tool_gateway import resolve_managed_tool_gateway +from tools.tool_backend_helpers import managed_nous_tools_enabled, resolve_openai_audio_api_key + +# --------------------------------------------------------------------------- +# Lazy imports -- providers are imported only when actually used to avoid +# crashing in headless environments (SSH, Docker, WSL, no PortAudio). +# --------------------------------------------------------------------------- + +def _import_edge_tts(): + """Lazy import edge_tts. Returns the module or raises ImportError.""" + import edge_tts + return edge_tts + +def _import_elevenlabs(): + """Lazy import ElevenLabs client. Returns the class or raises ImportError.""" + from elevenlabs.client import ElevenLabs + return ElevenLabs + +def _import_openai_client(): + """Lazy import OpenAI client. Returns the class or raises ImportError.""" + from openai import OpenAI as OpenAIClient + return OpenAIClient + +def _import_mistral_client(): + """Lazy import Mistral client. Returns the class or raises ImportError.""" + from mistralai.client import Mistral + return Mistral + +def _import_sounddevice(): + """Lazy import sounddevice. Returns the module or raises ImportError/OSError.""" + import sounddevice as sd + return sd + + +# =========================================================================== +# Defaults +# =========================================================================== +DEFAULT_PROVIDER = "edge" +DEFAULT_EDGE_VOICE = "en-US-AriaNeural" +DEFAULT_ELEVENLABS_VOICE_ID = "pNInz6obpgDQGcFmaJgB" # Adam +DEFAULT_ELEVENLABS_MODEL_ID = "eleven_multilingual_v2" +DEFAULT_ELEVENLABS_STREAMING_MODEL_ID = "eleven_flash_v2_5" +DEFAULT_OPENAI_MODEL = "gpt-4o-mini-tts" +DEFAULT_OPENAI_VOICE = "alloy" +DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1" +DEFAULT_MINIMAX_MODEL = "speech-2.8-hd" +DEFAULT_MINIMAX_VOICE_ID = "English_Graceful_Lady" +DEFAULT_MINIMAX_BASE_URL = "https://api.minimax.io/v1/t2a_v2" +DEFAULT_MISTRAL_TTS_MODEL = "voxtral-mini-tts-2603" +DEFAULT_MISTRAL_TTS_VOICE_ID = "c69964a6-ab8b-4f8a-9465-ec0925096ec8" # Paul - Neutral + +def _get_default_output_dir() -> str: + from hermes_constants import get_hermes_dir + return str(get_hermes_dir("cache/audio", "audio_cache")) + +DEFAULT_OUTPUT_DIR = _get_default_output_dir() +MAX_TEXT_LENGTH = 4000 + + +# =========================================================================== +# Config loader -- reads tts: section from ~/.hermes/config.yaml +# =========================================================================== +def _load_tts_config() -> Dict[str, Any]: + """ + Load TTS configuration from ~/.hermes/config.yaml. + + Returns a dict with provider settings. Falls back to defaults + for any missing fields. + """ + try: + from hermes_cli.config import load_config + config = load_config() + return config.get("tts", {}) + except ImportError: + logger.debug("hermes_cli.config not available, using default TTS config") + return {} + except Exception as e: + logger.warning("Failed to load TTS config: %s", e, exc_info=True) + return {} + + +def _get_provider(tts_config: Dict[str, Any]) -> str: + """Get the configured TTS provider name.""" + return (tts_config.get("provider") or DEFAULT_PROVIDER).lower().strip() + + +# =========================================================================== +# ffmpeg Opus conversion (Edge TTS MP3 -> OGG Opus for Telegram) +# =========================================================================== +def _has_ffmpeg() -> bool: + """Check if ffmpeg is available on the system.""" + return shutil.which("ffmpeg") is not None + + +def _convert_to_opus(mp3_path: str) -> Optional[str]: + """ + Convert an MP3 file to OGG Opus format for Telegram voice bubbles. + + Args: + mp3_path: Path to the input MP3 file. + + Returns: + Path to the .ogg file, or None if conversion fails. + """ + if not _has_ffmpeg(): + return None + + ogg_path = mp3_path.rsplit(".", 1)[0] + ".ogg" + try: + result = subprocess.run( + ["ffmpeg", "-i", mp3_path, "-acodec", "libopus", + "-ac", "1", "-b:a", "64k", "-vbr", "off", ogg_path, "-y"], + capture_output=True, timeout=30, + ) + if result.returncode != 0: + logger.warning("ffmpeg conversion failed with return code %d: %s", + result.returncode, result.stderr.decode('utf-8', errors='ignore')[:200]) + return None + if os.path.exists(ogg_path) and os.path.getsize(ogg_path) > 0: + return ogg_path + except subprocess.TimeoutExpired: + logger.warning("ffmpeg OGG conversion timed out after 30s") + except FileNotFoundError: + logger.warning("ffmpeg not found in PATH") + except Exception as e: + logger.warning("ffmpeg OGG conversion failed: %s", e, exc_info=True) + return None + + +# =========================================================================== +# Provider: Edge TTS (free) +# =========================================================================== +async def _generate_edge_tts(text: str, output_path: str, tts_config: Dict[str, Any]) -> str: + """ + Generate audio using Edge TTS. + + Args: + text: Text to convert. + output_path: Where to save the MP3 file. + tts_config: TTS config dict. + + Returns: + Path to the saved audio file. + """ + _edge_tts = _import_edge_tts() + edge_config = tts_config.get("edge", {}) + voice = edge_config.get("voice", DEFAULT_EDGE_VOICE) + speed = float(edge_config.get("speed", tts_config.get("speed", 1.0))) + + kwargs = {"voice": voice} + if speed != 1.0: + pct = round((speed - 1.0) * 100) + kwargs["rate"] = f"{pct:+d}%" + + communicate = _edge_tts.Communicate(text, **kwargs) + await communicate.save(output_path) + return output_path + + +# =========================================================================== +# Provider: ElevenLabs (premium) +# =========================================================================== +def _generate_elevenlabs(text: str, output_path: str, tts_config: Dict[str, Any]) -> str: + """ + Generate audio using ElevenLabs. + + Args: + text: Text to convert. + output_path: Where to save the audio file. + tts_config: TTS config dict. + + Returns: + Path to the saved audio file. + """ + api_key = os.getenv("ELEVENLABS_API_KEY", "") + if not api_key: + raise ValueError("ELEVENLABS_API_KEY not set. Get one at https://elevenlabs.io/") + + el_config = tts_config.get("elevenlabs", {}) + voice_id = el_config.get("voice_id", DEFAULT_ELEVENLABS_VOICE_ID) + model_id = el_config.get("model_id", DEFAULT_ELEVENLABS_MODEL_ID) + + # Determine output format based on file extension + if output_path.endswith(".ogg"): + output_format = "opus_48000_64" + else: + output_format = "mp3_44100_128" + + ElevenLabs = _import_elevenlabs() + client = ElevenLabs(api_key=api_key) + audio_generator = client.text_to_speech.convert( + text=text, + voice_id=voice_id, + model_id=model_id, + output_format=output_format, + ) + + # audio_generator yields chunks -- write them all + with open(output_path, "wb") as f: + for chunk in audio_generator: + f.write(chunk) + + return output_path + + +# =========================================================================== +# Provider: OpenAI TTS +# =========================================================================== +def _generate_openai_tts(text: str, output_path: str, tts_config: Dict[str, Any]) -> str: + """ + Generate audio using OpenAI TTS. + + Args: + text: Text to convert. + output_path: Where to save the audio file. + tts_config: TTS config dict. + + Returns: + Path to the saved audio file. + """ + api_key, base_url = _resolve_openai_audio_client_config() + + oai_config = tts_config.get("openai", {}) + model = oai_config.get("model", DEFAULT_OPENAI_MODEL) + voice = oai_config.get("voice", DEFAULT_OPENAI_VOICE) + base_url = oai_config.get("base_url", base_url) + speed = float(oai_config.get("speed", tts_config.get("speed", 1.0))) + + # Determine response format from extension + if output_path.endswith(".ogg"): + response_format = "opus" + else: + response_format = "mp3" + + OpenAIClient = _import_openai_client() + client = OpenAIClient(api_key=api_key, base_url=base_url) + try: + create_kwargs = dict( + model=model, + voice=voice, + input=text, + response_format=response_format, + extra_headers={"x-idempotency-key": str(uuid.uuid4())}, + ) + if speed != 1.0: + create_kwargs["speed"] = max(0.25, min(4.0, speed)) + response = client.audio.speech.create(**create_kwargs) + + response.stream_to_file(output_path) + return output_path + finally: + close = getattr(client, "close", None) + if callable(close): + close() + + +# =========================================================================== +# Provider: MiniMax TTS +# =========================================================================== +def _generate_minimax_tts(text: str, output_path: str, tts_config: Dict[str, Any]) -> str: + """ + Generate audio using MiniMax TTS API. + + MiniMax returns hex-encoded audio data. Supports streaming (SSE) and + non-streaming modes. This implementation uses non-streaming for simplicity. + + Args: + text: Text to convert (max 10,000 characters). + output_path: Where to save the audio file. + tts_config: TTS config dict. + + Returns: + Path to the saved audio file. + """ + import requests + + api_key = os.getenv("MINIMAX_API_KEY", "") + if not api_key: + raise ValueError("MINIMAX_API_KEY not set. Get one at https://platform.minimax.io/") + + mm_config = tts_config.get("minimax", {}) + model = mm_config.get("model", DEFAULT_MINIMAX_MODEL) + voice_id = mm_config.get("voice_id", DEFAULT_MINIMAX_VOICE_ID) + speed = mm_config.get("speed", tts_config.get("speed", 1)) + vol = mm_config.get("vol", 1) + pitch = mm_config.get("pitch", 0) + base_url = mm_config.get("base_url", DEFAULT_MINIMAX_BASE_URL) + + # Determine audio format from output extension + if output_path.endswith(".wav"): + audio_format = "wav" + elif output_path.endswith(".flac"): + audio_format = "flac" + else: + audio_format = "mp3" + + payload = { + "model": model, + "text": text, + "stream": False, + "voice_setting": { + "voice_id": voice_id, + "speed": speed, + "vol": vol, + "pitch": pitch, + }, + "audio_setting": { + "sample_rate": 32000, + "bitrate": 128000, + "format": audio_format, + "channel": 1, + }, + } + + headers = { + "Content-Type": "application/json", + "Authorization": f"Bearer {api_key}", + } + + response = requests.post(base_url, json=payload, headers=headers, timeout=60) + response.raise_for_status() + + result = response.json() + base_resp = result.get("base_resp", {}) + status_code = base_resp.get("status_code", -1) + + if status_code != 0: + status_msg = base_resp.get("status_msg", "unknown error") + raise RuntimeError(f"MiniMax TTS API error (code {status_code}): {status_msg}") + + hex_audio = result.get("data", {}).get("audio", "") + if not hex_audio: + raise RuntimeError("MiniMax TTS returned empty audio data") + + # MiniMax returns hex-encoded audio (not base64) + audio_bytes = bytes.fromhex(hex_audio) + + with open(output_path, "wb") as f: + f.write(audio_bytes) + + return output_path + + +# =========================================================================== +# Provider: Mistral (Voxtral TTS) +# =========================================================================== +def _generate_mistral_tts(text: str, output_path: str, tts_config: Dict[str, Any]) -> str: + """Generate audio using Mistral Voxtral TTS API. + + The API returns base64-encoded audio; this function decodes it + and writes the raw bytes to *output_path*. + Supports native Opus output for Telegram voice bubbles. + """ + api_key = os.getenv("MISTRAL_API_KEY", "") + if not api_key: + raise ValueError("MISTRAL_API_KEY not set. Get one at https://console.mistral.ai/") + + mi_config = tts_config.get("mistral", {}) + model = mi_config.get("model", DEFAULT_MISTRAL_TTS_MODEL) + voice_id = mi_config.get("voice_id") or DEFAULT_MISTRAL_TTS_VOICE_ID + + if output_path.endswith(".ogg"): + response_format = "opus" + elif output_path.endswith(".wav"): + response_format = "wav" + elif output_path.endswith(".flac"): + response_format = "flac" + else: + response_format = "mp3" + + Mistral = _import_mistral_client() + try: + with Mistral(api_key=api_key) as client: + response = client.audio.speech.complete( + model=model, + input=text, + voice_id=voice_id, + response_format=response_format, + ) + audio_bytes = base64.b64decode(response.audio_data) + except ValueError: + raise + except Exception as e: + logger.error("Mistral TTS failed: %s", e, exc_info=True) + raise RuntimeError(f"Mistral TTS failed: {type(e).__name__}") from e + + with open(output_path, "wb") as f: + f.write(audio_bytes) + + return output_path + + +# =========================================================================== +# NeuTTS (local, on-device TTS via neutts_cli) +# =========================================================================== + +def _check_neutts_available() -> bool: + """Check if the neutts engine is importable (installed locally).""" + try: + import importlib.util + return importlib.util.find_spec("neutts") is not None + except Exception: + return False + + +def _default_neutts_ref_audio() -> str: + """Return path to the bundled default voice reference audio.""" + return str(Path(__file__).parent / "neutts_samples" / "jo.wav") + + +def _default_neutts_ref_text() -> str: + """Return path to the bundled default voice reference transcript.""" + return str(Path(__file__).parent / "neutts_samples" / "jo.txt") + + +def _generate_neutts(text: str, output_path: str, tts_config: Dict[str, Any]) -> str: + """Generate speech using the local NeuTTS engine. + + Runs synthesis in a subprocess via tools/neutts_synth.py to keep the + ~500MB model in a separate process that exits after synthesis. + Outputs WAV; the caller handles conversion for Telegram if needed. + """ + import sys + + neutts_config = tts_config.get("neutts", {}) + ref_audio = neutts_config.get("ref_audio", "") or _default_neutts_ref_audio() + ref_text = neutts_config.get("ref_text", "") or _default_neutts_ref_text() + model = neutts_config.get("model", "neuphonic/neutts-air-q4-gguf") + device = neutts_config.get("device", "cpu") + + # NeuTTS outputs WAV natively — use a .wav path for generation, + # let the caller convert to the final format afterward. + wav_path = output_path + if not output_path.endswith(".wav"): + wav_path = output_path.rsplit(".", 1)[0] + ".wav" + + synth_script = str(Path(__file__).parent / "neutts_synth.py") + cmd = [ + sys.executable, synth_script, + "--text", text, + "--out", wav_path, + "--ref-audio", ref_audio, + "--ref-text", ref_text, + "--model", model, + "--device", device, + ] + + result = subprocess.run(cmd, capture_output=True, text=True, timeout=120) + if result.returncode != 0: + stderr = result.stderr.strip() + # Filter out the "OK:" line from stderr + error_lines = [l for l in stderr.splitlines() if not l.startswith("OK:")] + raise RuntimeError(f"NeuTTS synthesis failed: {chr(10).join(error_lines) or 'unknown error'}") + + # If the caller wanted .mp3 or .ogg, convert from WAV + if wav_path != output_path: + ffmpeg = shutil.which("ffmpeg") + if ffmpeg: + conv_cmd = [ffmpeg, "-i", wav_path, "-y", "-loglevel", "error", output_path] + subprocess.run(conv_cmd, check=True, timeout=30) + os.remove(wav_path) + else: + # No ffmpeg — just rename the WAV to the expected path + os.rename(wav_path, output_path) + + return output_path + + +# =========================================================================== +# Main tool function +# =========================================================================== +def text_to_speech_tool( + text: str, + output_path: Optional[str] = None, +) -> str: + """ + Convert text to speech audio. + + Reads provider/voice config from ~/.hermes/config.yaml (tts: section). + The model sends text; the user configures voice and provider. + + On messaging platforms, the returned MEDIA:<path> tag is intercepted + by the send pipeline and delivered as a native voice message. + In CLI mode, the file is saved to ~/voice-memos/. + + Args: + text: The text to convert to speech. + output_path: Optional custom save path. Defaults to ~/voice-memos/<timestamp>.mp3 + + Returns: + str: JSON result with success, file_path, and optionally MEDIA tag. + """ + if not text or not text.strip(): + return tool_error("Text is required", success=False) + + # Truncate very long text with a warning + if len(text) > MAX_TEXT_LENGTH: + logger.warning("TTS text too long (%d chars), truncating to %d", len(text), MAX_TEXT_LENGTH) + text = text[:MAX_TEXT_LENGTH] + + tts_config = _load_tts_config() + provider = _get_provider(tts_config) + + # Detect platform from gateway env var to choose the best output format. + # Telegram voice bubbles require Opus (.ogg); OpenAI and ElevenLabs can + # produce Opus natively (no ffmpeg needed). Edge TTS always outputs MP3 + # and needs ffmpeg for conversion. + from gateway.session_context import get_session_env + platform = get_session_env("HERMES_SESSION_PLATFORM", "").lower() + want_opus = (platform == "telegram") + + # Determine output path + if output_path: + file_path = Path(output_path).expanduser() + else: + timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S") + out_dir = Path(DEFAULT_OUTPUT_DIR) + out_dir.mkdir(parents=True, exist_ok=True) + # Use .ogg for Telegram with providers that support native Opus output, + # otherwise fall back to .mp3 (Edge TTS will attempt ffmpeg conversion later). + if want_opus and provider in ("openai", "elevenlabs", "mistral"): + file_path = out_dir / f"tts_{timestamp}.ogg" + else: + file_path = out_dir / f"tts_{timestamp}.mp3" + + # Ensure parent directory exists + file_path.parent.mkdir(parents=True, exist_ok=True) + file_str = str(file_path) + + try: + # Generate audio with the configured provider + if provider == "elevenlabs": + try: + _import_elevenlabs() + except ImportError: + return json.dumps({ + "success": False, + "error": "ElevenLabs provider selected but 'elevenlabs' package not installed. Run: pip install elevenlabs" + }, ensure_ascii=False) + logger.info("Generating speech with ElevenLabs...") + _generate_elevenlabs(text, file_str, tts_config) + + elif provider == "openai": + try: + _import_openai_client() + except ImportError: + return json.dumps({ + "success": False, + "error": "OpenAI provider selected but 'openai' package not installed." + }, ensure_ascii=False) + logger.info("Generating speech with OpenAI TTS...") + _generate_openai_tts(text, file_str, tts_config) + + elif provider == "minimax": + logger.info("Generating speech with MiniMax TTS...") + _generate_minimax_tts(text, file_str, tts_config) + + elif provider == "mistral": + try: + _import_mistral_client() + except ImportError: + return json.dumps({ + "success": False, + "error": "Mistral provider selected but 'mistralai' package not installed. " + "Run: pip install 'hermes-agent[mistral]'" + }, ensure_ascii=False) + logger.info("Generating speech with Mistral Voxtral TTS...") + _generate_mistral_tts(text, file_str, tts_config) + + elif provider == "neutts": + if not _check_neutts_available(): + return json.dumps({ + "success": False, + "error": "NeuTTS provider selected but neutts is not installed. " + "Run hermes setup and choose NeuTTS, or install espeak-ng and run python -m pip install -U neutts[all]." + }, ensure_ascii=False) + logger.info("Generating speech with NeuTTS (local)...") + _generate_neutts(text, file_str, tts_config) + + else: + # Default: Edge TTS (free), with NeuTTS as local fallback + edge_available = True + try: + _import_edge_tts() + except ImportError: + edge_available = False + + if edge_available: + logger.info("Generating speech with Edge TTS...") + try: + import concurrent.futures + with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool: + pool.submit( + lambda: asyncio.run(_generate_edge_tts(text, file_str, tts_config)) + ).result(timeout=60) + except RuntimeError: + asyncio.run(_generate_edge_tts(text, file_str, tts_config)) + elif _check_neutts_available(): + logger.info("Edge TTS not available, falling back to NeuTTS (local)...") + provider = "neutts" + _generate_neutts(text, file_str, tts_config) + else: + return json.dumps({ + "success": False, + "error": "No TTS provider available. Install edge-tts (pip install edge-tts) " + "or set up NeuTTS for local synthesis." + }, ensure_ascii=False) + + # Check the file was actually created + if not os.path.exists(file_str) or os.path.getsize(file_str) == 0: + return json.dumps({ + "success": False, + "error": f"TTS generation produced no output (provider: {provider})" + }, ensure_ascii=False) + + # Try Opus conversion for Telegram compatibility + # Edge TTS outputs MP3, NeuTTS outputs WAV — both need ffmpeg conversion + voice_compatible = False + if provider in ("edge", "neutts", "minimax") and not file_str.endswith(".ogg"): + opus_path = _convert_to_opus(file_str) + if opus_path: + file_str = opus_path + voice_compatible = True + elif provider in ("elevenlabs", "openai", "mistral"): + voice_compatible = file_str.endswith(".ogg") + + file_size = os.path.getsize(file_str) + logger.info("TTS audio saved: %s (%s bytes, provider: %s)", file_str, f"{file_size:,}", provider) + + # Build response with MEDIA tag for platform delivery + media_tag = f"MEDIA:{file_str}" + if voice_compatible: + media_tag = f"[[audio_as_voice]]\n{media_tag}" + + return json.dumps({ + "success": True, + "file_path": file_str, + "media_tag": media_tag, + "provider": provider, + "voice_compatible": voice_compatible, + }, ensure_ascii=False) + + except ValueError as e: + # Configuration errors (missing API keys, etc.) + error_msg = f"TTS configuration error ({provider}): {e}" + logger.error("%s", error_msg) + return tool_error(error_msg, success=False) + except FileNotFoundError as e: + # Missing dependencies or files + error_msg = f"TTS dependency missing ({provider}): {e}" + logger.error("%s", error_msg, exc_info=True) + return tool_error(error_msg, success=False) + except Exception as e: + # Unexpected errors + error_msg = f"TTS generation failed ({provider}): {e}" + logger.error("%s", error_msg, exc_info=True) + return tool_error(error_msg, success=False) + + +# =========================================================================== +# Requirements check +# =========================================================================== +def check_tts_requirements() -> bool: + """ + Check if at least one TTS provider is available. + + Edge TTS needs no API key and is the default, so if the package + is installed, TTS is available. + + Returns: + bool: True if at least one provider can work. + """ + try: + _import_edge_tts() + return True + except ImportError: + pass + try: + _import_elevenlabs() + if os.getenv("ELEVENLABS_API_KEY"): + return True + except ImportError: + pass + try: + _import_openai_client() + if _has_openai_audio_backend(): + return True + except ImportError: + pass + if os.getenv("MINIMAX_API_KEY"): + return True + try: + _import_mistral_client() + if os.getenv("MISTRAL_API_KEY"): + return True + except ImportError: + pass + if _check_neutts_available(): + return True + return False + + +def _resolve_openai_audio_client_config() -> tuple[str, str]: + """Return direct OpenAI audio config or a managed gateway fallback.""" + direct_api_key = resolve_openai_audio_api_key() + if direct_api_key: + return direct_api_key, DEFAULT_OPENAI_BASE_URL + + managed_gateway = resolve_managed_tool_gateway("openai-audio") + if managed_gateway is None: + message = "Neither VOICE_TOOLS_OPENAI_KEY nor OPENAI_API_KEY is set" + if managed_nous_tools_enabled(): + message += ", and the managed OpenAI audio gateway is unavailable" + raise ValueError(message) + + return managed_gateway.nous_user_token, urljoin( + f"{managed_gateway.gateway_origin.rstrip('/')}/", "v1" + ) + + +def _has_openai_audio_backend() -> bool: + """Return True when OpenAI audio can use direct credentials or the managed gateway.""" + return bool(resolve_openai_audio_api_key() or resolve_managed_tool_gateway("openai-audio")) + + +# =========================================================================== +# Streaming TTS: sentence-by-sentence pipeline for ElevenLabs +# =========================================================================== +# Sentence boundary pattern: punctuation followed by space or newline +_SENTENCE_BOUNDARY_RE = re.compile(r'(?<=[.!?])(?:\s|\n)|(?:\n\n)') + +# Markdown stripping patterns (same as cli.py _voice_speak_response) +_MD_CODE_BLOCK = re.compile(r'```[\s\S]*?```') +_MD_LINK = re.compile(r'\[([^\]]+)\]\([^)]+\)') +_MD_URL = re.compile(r'https?://\S+') +_MD_BOLD = re.compile(r'\*\*(.+?)\*\*') +_MD_ITALIC = re.compile(r'\*(.+?)\*') +_MD_INLINE_CODE = re.compile(r'`(.+?)`') +_MD_HEADER = re.compile(r'^#+\s*', flags=re.MULTILINE) +_MD_LIST_ITEM = re.compile(r'^\s*[-*]\s+', flags=re.MULTILINE) +_MD_HR = re.compile(r'---+') +_MD_EXCESS_NL = re.compile(r'\n{3,}') + + +def _strip_markdown_for_tts(text: str) -> str: + """Remove markdown formatting that shouldn't be spoken aloud.""" + text = _MD_CODE_BLOCK.sub(' ', text) + text = _MD_LINK.sub(r'\1', text) + text = _MD_URL.sub('', text) + text = _MD_BOLD.sub(r'\1', text) + text = _MD_ITALIC.sub(r'\1', text) + text = _MD_INLINE_CODE.sub(r'\1', text) + text = _MD_HEADER.sub('', text) + text = _MD_LIST_ITEM.sub('', text) + text = _MD_HR.sub('', text) + text = _MD_EXCESS_NL.sub('\n\n', text) + return text.strip() + + +def stream_tts_to_speaker( + text_queue: queue.Queue, + stop_event: threading.Event, + tts_done_event: threading.Event, + display_callback: Optional[Callable[[str], None]] = None, +): + """Consume text deltas from *text_queue*, buffer them into sentences, + and stream each sentence through ElevenLabs TTS to the speaker in + real-time. + + Protocol: + * The producer puts ``str`` deltas onto *text_queue*. + * A ``None`` sentinel signals end-of-text (flush remaining buffer). + * *stop_event* can be set to abort early (e.g. user interrupt). + * *tts_done_event* is **set** in the ``finally`` block so callers + waiting on it (continuous voice mode) know playback is finished. + """ + tts_done_event.clear() + + try: + # --- TTS client setup (optional -- display_callback works without it) --- + client = None + output_stream = None + voice_id = DEFAULT_ELEVENLABS_VOICE_ID + model_id = DEFAULT_ELEVENLABS_STREAMING_MODEL_ID + + tts_config = _load_tts_config() + el_config = tts_config.get("elevenlabs", {}) + voice_id = el_config.get("voice_id", voice_id) + model_id = el_config.get("streaming_model_id", + el_config.get("model_id", model_id)) + + api_key = os.getenv("ELEVENLABS_API_KEY", "") + if not api_key: + logger.warning("ELEVENLABS_API_KEY not set; streaming TTS audio disabled") + else: + try: + ElevenLabs = _import_elevenlabs() + client = ElevenLabs(api_key=api_key) + except ImportError: + logger.warning("elevenlabs package not installed; streaming TTS disabled") + + # Open a single sounddevice output stream for the lifetime of + # this function. ElevenLabs pcm_24000 produces signed 16-bit + # little-endian mono PCM at 24 kHz. + if client is not None: + try: + sd = _import_sounddevice() + output_stream = sd.OutputStream( + samplerate=24000, channels=1, dtype="int16", + ) + output_stream.start() + except (ImportError, OSError) as exc: + logger.debug("sounddevice not available: %s", exc) + output_stream = None + except Exception as exc: + logger.warning("sounddevice OutputStream failed: %s", exc) + output_stream = None + + sentence_buf = "" + min_sentence_len = 20 + long_flush_len = 100 + queue_timeout = 0.5 + _spoken_sentences: list[str] = [] # track spoken sentences to skip duplicates + # Regex to strip complete <think>...</think> blocks from buffer + _think_block_re = re.compile(r'<think[\s>].*?</think>', flags=re.DOTALL) + + def _speak_sentence(sentence: str): + """Display sentence and optionally generate + play audio.""" + if stop_event.is_set(): + return + cleaned = _strip_markdown_for_tts(sentence).strip() + if not cleaned: + return + # Skip duplicate/near-duplicate sentences (LLM repetition) + cleaned_lower = cleaned.lower().rstrip(".!,") + for prev in _spoken_sentences: + if prev.lower().rstrip(".!,") == cleaned_lower: + return + _spoken_sentences.append(cleaned) + # Display raw sentence on screen before TTS processing + if display_callback is not None: + display_callback(sentence) + # Skip audio generation if no TTS client available + if client is None: + return + # Truncate very long sentences + if len(cleaned) > MAX_TEXT_LENGTH: + cleaned = cleaned[:MAX_TEXT_LENGTH] + try: + audio_iter = client.text_to_speech.convert( + text=cleaned, + voice_id=voice_id, + model_id=model_id, + output_format="pcm_24000", + ) + if output_stream is not None: + for chunk in audio_iter: + if stop_event.is_set(): + break + import numpy as _np + audio_array = _np.frombuffer(chunk, dtype=_np.int16) + output_stream.write(audio_array.reshape(-1, 1)) + else: + # Fallback: write chunks to temp file and play via system player + _play_via_tempfile(audio_iter, stop_event) + except Exception as exc: + logger.warning("Streaming TTS sentence failed: %s", exc) + + def _play_via_tempfile(audio_iter, stop_evt): + """Write PCM chunks to a temp WAV file and play it.""" + tmp_path = None + try: + import wave + tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False) + tmp_path = tmp.name + with wave.open(tmp, "wb") as wf: + wf.setnchannels(1) + wf.setsampwidth(2) # 16-bit + wf.setframerate(24000) + for chunk in audio_iter: + if stop_evt.is_set(): + break + wf.writeframes(chunk) + from tools.voice_mode import play_audio_file + play_audio_file(tmp_path) + except Exception as exc: + logger.warning("Temp-file TTS fallback failed: %s", exc) + finally: + if tmp_path: + try: + os.unlink(tmp_path) + except OSError: + pass + + while not stop_event.is_set(): + # Read next delta from queue + try: + delta = text_queue.get(timeout=queue_timeout) + except queue.Empty: + # Timeout: if we have accumulated a long buffer, flush it + if len(sentence_buf) > long_flush_len: + _speak_sentence(sentence_buf) + sentence_buf = "" + continue + + if delta is None: + # End-of-text sentinel: strip any remaining think blocks, flush + sentence_buf = _think_block_re.sub('', sentence_buf) + if sentence_buf.strip(): + _speak_sentence(sentence_buf) + break + + sentence_buf += delta + + # --- Think block filtering --- + # Strip complete <think>...</think> blocks from buffer. + # Works correctly even when tags span multiple deltas. + sentence_buf = _think_block_re.sub('', sentence_buf) + + # If an incomplete <think tag is at the end, wait for more data + # before extracting sentences (the closing tag may arrive next). + if '<think' in sentence_buf and '</think>' not in sentence_buf: + continue + + # Check for sentence boundaries + while True: + m = _SENTENCE_BOUNDARY_RE.search(sentence_buf) + if m is None: + break + end_pos = m.end() + sentence = sentence_buf[:end_pos] + sentence_buf = sentence_buf[end_pos:] + # Merge short fragments into the next sentence + if len(sentence.strip()) < min_sentence_len: + sentence_buf = sentence + sentence_buf + break + _speak_sentence(sentence) + + # Drain any remaining items from the queue + while True: + try: + text_queue.get_nowait() + except queue.Empty: + break + + # output_stream is closed in the finally block below + + except Exception as exc: + logger.warning("Streaming TTS pipeline error: %s", exc) + finally: + # Always close the audio output stream to avoid locking the device + if output_stream is not None: + try: + output_stream.stop() + output_stream.close() + except Exception: + pass + tts_done_event.set() + + +# =========================================================================== +# Main -- quick diagnostics +# =========================================================================== +if __name__ == "__main__": + print("🔊 Text-to-Speech Tool Module") + print("=" * 50) + + def _check(importer, label): + try: + importer() + return True + except ImportError: + return False + + print("\nProvider availability:") + print(f" Edge TTS: {'installed' if _check(_import_edge_tts, 'edge') else 'not installed (pip install edge-tts)'}") + print(f" ElevenLabs: {'installed' if _check(_import_elevenlabs, 'el') else 'not installed (pip install elevenlabs)'}") + print(f" API Key: {'set' if os.getenv('ELEVENLABS_API_KEY') else 'not set'}") + print(f" OpenAI: {'installed' if _check(_import_openai_client, 'oai') else 'not installed'}") + print( + " API Key: " + f"{'set' if resolve_openai_audio_api_key() else 'not set (VOICE_TOOLS_OPENAI_KEY or OPENAI_API_KEY)'}" + ) + print(f" MiniMax: {'API key set' if os.getenv('MINIMAX_API_KEY') else 'not set (MINIMAX_API_KEY)'}") + print(f" ffmpeg: {'✅ found' if _has_ffmpeg() else '❌ not found (needed for Telegram Opus)'}") + print(f"\n Output dir: {DEFAULT_OUTPUT_DIR}") + + config = _load_tts_config() + provider = _get_provider(config) + print(f" Configured provider: {provider}") + + +# --------------------------------------------------------------------------- +# Registry +# --------------------------------------------------------------------------- +from tools.registry import registry, tool_error + +TTS_SCHEMA = { + "name": "text_to_speech", + "description": "Convert text to speech audio. Returns a MEDIA: path that the platform delivers as a voice message. On Telegram it plays as a voice bubble, on Discord/WhatsApp as an audio attachment. In CLI mode, saves to ~/voice-memos/. Voice and provider are user-configured, not model-selected.", + "parameters": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "The text to convert to speech. Keep under 4000 characters." + }, + "output_path": { + "type": "string", + "description": "Optional custom file path to save the audio. Defaults to ~/.hermes/audio_cache/<timestamp>.mp3" + } + }, + "required": ["text"] + } +} + +registry.register( + name="text_to_speech", + toolset="tts", + schema=TTS_SCHEMA, + handler=lambda args, **kw: text_to_speech_tool( + text=args.get("text", ""), + output_path=args.get("output_path")), + check_fn=check_tts_requirements, + emoji="🔊", +) diff --git a/mindcli/_vendor/tools/url_safety.py b/mindcli/_vendor/tools/url_safety.py new file mode 100644 index 0000000..3dc57ca --- /dev/null +++ b/mindcli/_vendor/tools/url_safety.py @@ -0,0 +1,97 @@ +"""URL safety checks — blocks requests to private/internal network addresses. + +Prevents SSRF (Server-Side Request Forgery) where a malicious prompt or +skill could trick the agent into fetching internal resources like cloud +metadata endpoints (169.254.169.254), localhost services, or private +network hosts. + +Limitations (documented, not fixable at pre-flight level): + - DNS rebinding (TOCTOU): an attacker-controlled DNS server with TTL=0 + can return a public IP for the check, then a private IP for the actual + connection. Fixing this requires connection-level validation (e.g. + Python's Champion library or an egress proxy like Stripe's Smokescreen). + - Redirect-based bypass is mitigated by httpx event hooks that re-validate + each redirect target in vision_tools, gateway platform adapters, and + media cache helpers. Web tools use third-party SDKs (Firecrawl/Tavily) + where redirect handling is on their servers. +""" + +import ipaddress +import logging +import socket +from urllib.parse import urlparse + +logger = logging.getLogger(__name__) + +# Hostnames that should always be blocked regardless of IP resolution +_BLOCKED_HOSTNAMES = frozenset({ + "metadata.google.internal", + "metadata.goog", +}) + +# 100.64.0.0/10 (CGNAT / Shared Address Space, RFC 6598) is NOT covered by +# ipaddress.is_private — it returns False for both is_private and is_global. +# Must be blocked explicitly. Used by carrier-grade NAT, Tailscale/WireGuard +# VPNs, and some cloud internal networks. +_CGNAT_NETWORK = ipaddress.ip_network("100.64.0.0/10") + + +def _is_blocked_ip(ip: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool: + """Return True if the IP should be blocked for SSRF protection.""" + if ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_reserved: + return True + if ip.is_multicast or ip.is_unspecified: + return True + # CGNAT range not covered by is_private + if ip in _CGNAT_NETWORK: + return True + return False + + +def is_safe_url(url: str) -> bool: + """Return True if the URL target is not a private/internal address. + + Resolves the hostname to an IP and checks against private ranges. + Fails closed: DNS errors and unexpected exceptions block the request. + """ + try: + parsed = urlparse(url) + hostname = (parsed.hostname or "").strip().lower() + if not hostname: + return False + + # Block known internal hostnames + if hostname in _BLOCKED_HOSTNAMES: + logger.warning("Blocked request to internal hostname: %s", hostname) + return False + + # Try to resolve and check IP + try: + addr_info = socket.getaddrinfo(hostname, None, socket.AF_UNSPEC, socket.SOCK_STREAM) + except socket.gaierror: + # DNS resolution failed — fail closed. If DNS can't resolve it, + # the HTTP client will also fail, so blocking loses nothing. + logger.warning("Blocked request — DNS resolution failed for: %s", hostname) + return False + + for family, _, _, _, sockaddr in addr_info: + ip_str = sockaddr[0] + try: + ip = ipaddress.ip_address(ip_str) + except ValueError: + continue + + if _is_blocked_ip(ip): + logger.warning( + "Blocked request to private/internal address: %s -> %s", + hostname, ip_str, + ) + return False + + return True + + except Exception as exc: + # Fail closed on unexpected errors — don't let parsing edge cases + # become SSRF bypass vectors + logger.warning("Blocked request — URL safety check error for %s: %s", url, exc) + return False diff --git a/mindcli/_vendor/tools/vision_tools.py b/mindcli/_vendor/tools/vision_tools.py new file mode 100644 index 0000000..2bcf256 --- /dev/null +++ b/mindcli/_vendor/tools/vision_tools.py @@ -0,0 +1,789 @@ +#!/usr/bin/env python3 +""" +Vision Tools Module + +This module provides vision analysis tools that work with image URLs. +Uses the centralized auxiliary vision router, which can select OpenRouter, +Nous, Codex, native Anthropic, or a custom OpenAI-compatible endpoint. + +Available tools: +- vision_analyze_tool: Analyze images from URLs with custom prompts + +Features: +- Downloads images from URLs and converts to base64 for API compatibility +- Comprehensive image description +- Context-aware analysis based on user queries +- Automatic temporary file cleanup +- Proper error handling and validation +- Debug logging support + +Usage: + from vision_tools import vision_analyze_tool + import asyncio + + # Analyze an image + result = await vision_analyze_tool( + image_url="https://example.com/image.jpg", + user_prompt="What architectural style is this building?" + ) +""" + +import base64 +import json +import logging +import os +import uuid +from pathlib import Path +from typing import Any, Awaitable, Dict, Optional +from urllib.parse import urlparse +import httpx +from agent.auxiliary_client import async_call_llm, extract_content_or_reasoning +from tools.debug_helpers import DebugSession +from tools.website_policy import check_website_access + +logger = logging.getLogger(__name__) + +_debug = DebugSession("vision_tools", env_var="VISION_TOOLS_DEBUG") + +# Configurable HTTP download timeout for _download_image(). +# Separate from auxiliary.vision.timeout which governs the LLM API call. +# Resolution: config.yaml auxiliary.vision.download_timeout → env var → 30s default. +def _resolve_download_timeout() -> float: + env_val = os.getenv("HERMES_VISION_DOWNLOAD_TIMEOUT", "").strip() + if env_val: + try: + return float(env_val) + except ValueError: + pass + try: + from hermes_cli.config import load_config + cfg = load_config() + val = cfg.get("auxiliary", {}).get("vision", {}).get("download_timeout") + if val is not None: + return float(val) + except Exception: + pass + return 30.0 + +_VISION_DOWNLOAD_TIMEOUT = _resolve_download_timeout() + +# Hard cap on downloaded image file size (50 MB). Prevents OOM from +# attacker-hosted multi-gigabyte files or decompression bombs. +_VISION_MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024 + + +def _validate_image_url(url: str) -> bool: + """ + Basic validation of image URL format. + + Args: + url (str): The URL to validate + + Returns: + bool: True if URL appears to be valid, False otherwise + """ + if not url or not isinstance(url, str): + return False + + # Basic HTTP/HTTPS URL check + if not url.startswith(("http://", "https://")): + return False + + # Parse to ensure we at least have a network location; still allow URLs + # without file extensions (e.g. CDN endpoints that redirect to images). + parsed = urlparse(url) + if not parsed.netloc: + return False + + # Block private/internal addresses to prevent SSRF + from tools.url_safety import is_safe_url + if not is_safe_url(url): + return False + + return True + + +def _detect_image_mime_type(image_path: Path) -> Optional[str]: + """Return a MIME type when the file looks like a supported image.""" + with image_path.open("rb") as f: + header = f.read(64) + + if header.startswith(b"\x89PNG\r\n\x1a\n"): + return "image/png" + if header.startswith(b"\xff\xd8\xff"): + return "image/jpeg" + if header.startswith((b"GIF87a", b"GIF89a")): + return "image/gif" + if header.startswith(b"BM"): + return "image/bmp" + if len(header) >= 12 and header[:4] == b"RIFF" and header[8:12] == b"WEBP": + return "image/webp" + if image_path.suffix.lower() == ".svg": + head = image_path.read_text(encoding="utf-8", errors="ignore")[:4096].lower() + if "<svg" in head: + return "image/svg+xml" + return None + + +async def _download_image(image_url: str, destination: Path, max_retries: int = 3) -> Path: + """ + Download an image from a URL to a local destination (async) with retry logic. + + Args: + image_url (str): The URL of the image to download + destination (Path): The path where the image should be saved + max_retries (int): Maximum number of retry attempts (default: 3) + + Returns: + Path: The path to the downloaded image + + Raises: + Exception: If download fails after all retries + """ + import asyncio + + # Create parent directories if they don't exist + destination.parent.mkdir(parents=True, exist_ok=True) + + async def _ssrf_redirect_guard(response): + """Re-validate each redirect target to prevent redirect-based SSRF. + + Without this, an attacker can host a public URL that 302-redirects + to http://169.254.169.254/ and bypass the pre-flight is_safe_url check. + + Must be async because httpx.AsyncClient awaits event hooks. + """ + if response.is_redirect and response.next_request: + redirect_url = str(response.next_request.url) + from tools.url_safety import is_safe_url + if not is_safe_url(redirect_url): + raise ValueError( + f"Blocked redirect to private/internal address: {redirect_url}" + ) + + last_error = None + for attempt in range(max_retries): + try: + blocked = check_website_access(image_url) + if blocked: + raise PermissionError(blocked["message"]) + + # Download the image with appropriate headers using async httpx + # Enable follow_redirects to handle image CDNs that redirect (e.g., Imgur, Picsum) + # SSRF: event_hooks validates each redirect target against private IP ranges + async with httpx.AsyncClient( + timeout=_VISION_DOWNLOAD_TIMEOUT, + follow_redirects=True, + event_hooks={"response": [_ssrf_redirect_guard]}, + ) as client: + response = await client.get( + image_url, + headers={ + "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36", + "Accept": "image/*,*/*;q=0.8", + }, + ) + response.raise_for_status() + + # Reject overly large images early via Content-Length header. + cl = response.headers.get("content-length") + if cl and int(cl) > _VISION_MAX_DOWNLOAD_BYTES: + raise ValueError( + f"Image too large ({int(cl)} bytes, max {_VISION_MAX_DOWNLOAD_BYTES})" + ) + + final_url = str(response.url) + blocked = check_website_access(final_url) + if blocked: + raise PermissionError(blocked["message"]) + + # Save the image content (double-check actual size) + body = response.content + if len(body) > _VISION_MAX_DOWNLOAD_BYTES: + raise ValueError( + f"Image too large ({len(body)} bytes, max {_VISION_MAX_DOWNLOAD_BYTES})" + ) + destination.write_bytes(body) + + return destination + except Exception as e: + last_error = e + if attempt < max_retries - 1: + wait_time = 2 ** (attempt + 1) # 2s, 4s, 8s + logger.warning("Image download failed (attempt %s/%s): %s", attempt + 1, max_retries, str(e)[:50]) + logger.warning("Retrying in %ss...", wait_time) + await asyncio.sleep(wait_time) + else: + logger.error( + "Image download failed after %s attempts: %s", + max_retries, + str(e)[:100], + exc_info=True, + ) + + if last_error is None: + raise RuntimeError( + f"_download_image exited retry loop without attempting (max_retries={max_retries})" + ) + raise last_error + + +def _determine_mime_type(image_path: Path) -> str: + """ + Determine the MIME type of an image based on its file extension. + + Args: + image_path (Path): Path to the image file + + Returns: + str: The MIME type (defaults to image/jpeg if unknown) + """ + extension = image_path.suffix.lower() + mime_types = { + '.jpg': 'image/jpeg', + '.jpeg': 'image/jpeg', + '.png': 'image/png', + '.gif': 'image/gif', + '.bmp': 'image/bmp', + '.webp': 'image/webp', + '.svg': 'image/svg+xml' + } + return mime_types.get(extension, 'image/jpeg') + + +def _image_to_base64_data_url(image_path: Path, mime_type: Optional[str] = None) -> str: + """ + Convert an image file to a base64-encoded data URL. + + Args: + image_path (Path): Path to the image file + mime_type (Optional[str]): MIME type of the image (auto-detected if None) + + Returns: + str: Base64-encoded data URL (e.g., "data:image/jpeg;base64,...") + """ + # Read the image as bytes + data = image_path.read_bytes() + + # Encode to base64 + encoded = base64.b64encode(data).decode("ascii") + + # Determine MIME type + mime = mime_type or _determine_mime_type(image_path) + + # Create data URL + data_url = f"data:{mime};base64,{encoded}" + + return data_url + + +# Hard limit for vision API payloads (20 MB) — matches the most restrictive +# major provider (Gemini inline data limit). Images above this are rejected. +_MAX_BASE64_BYTES = 20 * 1024 * 1024 + +# Target size when auto-resizing on API failure (5 MB). After a provider +# rejects an image, we downscale to this target and retry once. +_RESIZE_TARGET_BYTES = 5 * 1024 * 1024 + + +def _is_image_size_error(error: Exception) -> bool: + """Detect if an API error is related to image or payload size.""" + err_str = str(error).lower() + return any(hint in err_str for hint in ( + "too large", "payload", "413", "content_too_large", + "request_too_large", "image_url", "invalid_request", + "exceeds", "size limit", + )) + + +def _resize_image_for_vision(image_path: Path, mime_type: Optional[str] = None, + max_base64_bytes: int = _RESIZE_TARGET_BYTES) -> str: + """Convert an image to a base64 data URL, auto-resizing if too large. + + Tries Pillow first to progressively downscale oversized images. If Pillow + is not installed or resizing still exceeds the limit, falls back to the raw + bytes and lets the caller handle the size check. + + Returns the base64 data URL string. + """ + # Quick file-size estimate: base64 expands by ~4/3, plus data URL header. + # Skip the expensive full-read + encode if Pillow can resize directly. + file_size = image_path.stat().st_size + estimated_b64 = (file_size * 4) // 3 + 100 # ~header overhead + if estimated_b64 <= max_base64_bytes: + # Small enough — just encode directly. + data_url = _image_to_base64_data_url(image_path, mime_type=mime_type) + if len(data_url) <= max_base64_bytes: + return data_url + else: + data_url = None # defer full encode; try Pillow resize first + + # Attempt auto-resize with Pillow (soft dependency) + try: + from PIL import Image + import io as _io + except ImportError: + logger.info("Pillow not installed — cannot auto-resize oversized image") + if data_url is None: + data_url = _image_to_base64_data_url(image_path, mime_type=mime_type) + return data_url # caller will raise the size error + + logger.info("Image file is %.1f MB (estimated base64 %.1f MB, limit %.1f MB), auto-resizing...", + file_size / (1024 * 1024), estimated_b64 / (1024 * 1024), + max_base64_bytes / (1024 * 1024)) + + mime = mime_type or _determine_mime_type(image_path) + # Choose output format: JPEG for photos (smaller), PNG for transparency + pil_format = "PNG" if mime == "image/png" else "JPEG" + out_mime = "image/png" if pil_format == "PNG" else "image/jpeg" + + try: + img = Image.open(image_path) + except Exception as exc: + logger.info("Pillow cannot open image for resizing: %s", exc) + if data_url is None: + data_url = _image_to_base64_data_url(image_path, mime_type=mime_type) + return data_url # fall through to size-check in caller + # Convert RGBA to RGB for JPEG output + if pil_format == "JPEG" and img.mode in ("RGBA", "P"): + img = img.convert("RGB") + + # Strategy: halve dimensions until base64 fits, up to 4 rounds. + # For JPEG, also try reducing quality at each size step. + # For PNG, quality is irrelevant — only dimension reduction helps. + quality_steps = (85, 70, 50) if pil_format == "JPEG" else (None,) + prev_dims = (img.width, img.height) + candidate = None # will be set on first loop iteration + + for attempt in range(5): + if attempt > 0: + # Proportional scaling: halve the longer side and scale the + # shorter side to preserve aspect ratio (min dimension 64). + scale = 0.5 + new_w = max(int(img.width * scale), 64) + new_h = max(int(img.height * scale), 64) + # Re-derive the scale from whichever dimension hit the floor + # so both axes shrink by the same factor. + if new_w == 64 and img.width > 0: + effective_scale = 64 / img.width + new_h = max(int(img.height * effective_scale), 64) + elif new_h == 64 and img.height > 0: + effective_scale = 64 / img.height + new_w = max(int(img.width * effective_scale), 64) + # Stop if dimensions can't shrink further + if (new_w, new_h) == prev_dims: + break + img = img.resize((new_w, new_h), Image.LANCZOS) + prev_dims = (new_w, new_h) + logger.info("Resized to %dx%d (attempt %d)", new_w, new_h, attempt) + + for q in quality_steps: + buf = _io.BytesIO() + save_kwargs = {"format": pil_format} + if q is not None: + save_kwargs["quality"] = q + img.save(buf, **save_kwargs) + encoded = base64.b64encode(buf.getvalue()).decode("ascii") + candidate = f"data:{out_mime};base64,{encoded}" + if len(candidate) <= max_base64_bytes: + logger.info("Auto-resized image fits: %.1f MB (quality=%s, %dx%d)", + len(candidate) / (1024 * 1024), q, + img.width, img.height) + return candidate + + # If we still can't get it small enough, return the best attempt + # and let the caller decide + if candidate is not None: + logger.warning("Auto-resize could not fit image under %.1f MB (best: %.1f MB)", + max_base64_bytes / (1024 * 1024), len(candidate) / (1024 * 1024)) + return candidate + + # Shouldn't reach here, but fall back to full encode + return data_url or _image_to_base64_data_url(image_path, mime_type=mime_type) + + +async def vision_analyze_tool( + image_url: str, + user_prompt: str, + model: str = None, +) -> str: + """ + Analyze an image from a URL or local file path using vision AI. + + This tool accepts either an HTTP/HTTPS URL or a local file path. For URLs, + it downloads the image first. In both cases, the image is converted to base64 + and processed using Gemini 3 Flash Preview via OpenRouter API. + + The user_prompt parameter is expected to be pre-formatted by the calling + function (typically model_tools.py) to include both full description + requests and specific questions. + + Args: + image_url (str): The URL or local file path of the image to analyze. + Accepts http://, https:// URLs or absolute/relative file paths. + user_prompt (str): The pre-formatted prompt for the vision model + model (str): The vision model to use (default: google/gemini-3-flash-preview) + + Returns: + str: JSON string containing the analysis results with the following structure: + { + "success": bool, + "analysis": str (defaults to error message if None) + } + + Raises: + Exception: If download fails, analysis fails, or API key is not set + + Note: + - For URLs, temporary images are stored in ./temp_vision_images/ and cleaned up + - For local file paths, the file is used directly and NOT deleted + - Supports common image formats (JPEG, PNG, GIF, WebP, etc.) + """ + debug_call_data = { + "parameters": { + "image_url": image_url, + "user_prompt": user_prompt[:200] + "..." if len(user_prompt) > 200 else user_prompt, + "model": model + }, + "error": None, + "success": False, + "analysis_length": 0, + "model_used": model, + "image_size_bytes": 0 + } + + temp_image_path = None + # Track whether we should clean up the file after processing. + # Local files (e.g. from the image cache) should NOT be deleted. + should_cleanup = True + detected_mime_type = None + + try: + from tools.interrupt import is_interrupted + if is_interrupted(): + return tool_error("Interrupted", success=False) + + logger.info("Analyzing image: %s", image_url[:60]) + logger.info("User prompt: %s", user_prompt[:100]) + + # Determine if this is a local file path or a remote URL + # Strip file:// scheme so file URIs resolve as local paths. + resolved_url = image_url + if resolved_url.startswith("file://"): + resolved_url = resolved_url[len("file://"):] + local_path = Path(os.path.expanduser(resolved_url)) + if local_path.is_file(): + # Local file path (e.g. from platform image cache) -- skip download + logger.info("Using local image file: %s", image_url) + temp_image_path = local_path + should_cleanup = False # Don't delete cached/local files + elif _validate_image_url(image_url): + # Remote URL -- download to a temporary location + blocked = check_website_access(image_url) + if blocked: + raise PermissionError(blocked["message"]) + logger.info("Downloading image from URL...") + temp_dir = Path("./temp_vision_images") + temp_image_path = temp_dir / f"temp_image_{uuid.uuid4()}.jpg" + await _download_image(image_url, temp_image_path) + should_cleanup = True + else: + raise ValueError( + "Invalid image source. Provide an HTTP/HTTPS URL or a valid local file path." + ) + + # Get image file size for logging + image_size_bytes = temp_image_path.stat().st_size + image_size_kb = image_size_bytes / 1024 + logger.info("Image ready (%.1f KB)", image_size_kb) + + detected_mime_type = _detect_image_mime_type(temp_image_path) + if not detected_mime_type: + raise ValueError("Only real image files are supported for vision analysis.") + + # Convert image to base64 — send at full resolution first. + # If the provider rejects it as too large, we auto-resize and retry. + logger.info("Converting image to base64...") + image_data_url = _image_to_base64_data_url(temp_image_path, mime_type=detected_mime_type) + data_size_kb = len(image_data_url) / 1024 + logger.info("Image converted to base64 (%.1f KB)", data_size_kb) + + # Hard limit (20 MB) — no provider accepts payloads this large. + if len(image_data_url) > _MAX_BASE64_BYTES: + # Try to resize down to 5 MB before giving up. + image_data_url = _resize_image_for_vision( + temp_image_path, mime_type=detected_mime_type) + if len(image_data_url) > _MAX_BASE64_BYTES: + raise ValueError( + f"Image too large for vision API: base64 payload is " + f"{len(image_data_url) / (1024 * 1024):.1f} MB " + f"(limit {_MAX_BASE64_BYTES / (1024 * 1024):.0f} MB) " + f"even after resizing. " + f"Install Pillow (`pip install Pillow`) for better auto-resize, " + f"or compress the image manually." + ) + + debug_call_data["image_size_bytes"] = image_size_bytes + + # Use the prompt as provided (model_tools.py now handles full description formatting) + comprehensive_prompt = user_prompt + + # Prepare the message with base64-encoded image + messages = [ + { + "role": "user", + "content": [ + { + "type": "text", + "text": comprehensive_prompt + }, + { + "type": "image_url", + "image_url": { + "url": image_data_url + } + } + ] + } + ] + + logger.info("Processing image with vision model...") + + # Call the vision API via centralized router. + # Read timeout from config.yaml (auxiliary.vision.timeout), default 120s. + # Local vision models (llama.cpp, ollama) can take well over 30s. + vision_timeout = 120.0 + try: + from hermes_cli.config import load_config + _cfg = load_config() + _vt = _cfg.get("auxiliary", {}).get("vision", {}).get("timeout") + if _vt is not None: + vision_timeout = float(_vt) + except Exception: + pass + call_kwargs = { + "task": "vision", + "messages": messages, + "temperature": 0.1, + "max_tokens": 2000, + "timeout": vision_timeout, + } + if model: + call_kwargs["model"] = model + # Try full-size image first; on size-related rejection, downscale and retry. + try: + response = await async_call_llm(**call_kwargs) + except Exception as _api_err: + if (_is_image_size_error(_api_err) + and len(image_data_url) > _RESIZE_TARGET_BYTES): + logger.info( + "API rejected image (%.1f MB, likely too large); " + "auto-resizing to ~%.0f MB and retrying...", + len(image_data_url) / (1024 * 1024), + _RESIZE_TARGET_BYTES / (1024 * 1024), + ) + image_data_url = _resize_image_for_vision( + temp_image_path, mime_type=detected_mime_type) + messages[0]["content"][1]["image_url"]["url"] = image_data_url + response = await async_call_llm(**call_kwargs) + else: + raise + + # Extract the analysis — fall back to reasoning if content is empty + analysis = extract_content_or_reasoning(response) + + # Retry once on empty content (reasoning-only response) + if not analysis: + logger.warning("Vision LLM returned empty content, retrying once") + response = await async_call_llm(**call_kwargs) + analysis = extract_content_or_reasoning(response) + + analysis_length = len(analysis) + + logger.info("Image analysis completed (%s characters)", analysis_length) + + # Prepare successful response + result = { + "success": True, + "analysis": analysis or "There was a problem with the request and the image could not be analyzed." + } + + debug_call_data["success"] = True + debug_call_data["analysis_length"] = analysis_length + + # Log debug information + _debug.log_call("vision_analyze_tool", debug_call_data) + _debug.save() + + return json.dumps(result, indent=2, ensure_ascii=False) + + except Exception as e: + error_msg = f"Error analyzing image: {str(e)}" + logger.error("%s", error_msg, exc_info=True) + + # Detect vision capability errors — give the model a clear message + # so it can inform the user instead of a cryptic API error. + err_str = str(e).lower() + if any(hint in err_str for hint in ( + "402", "insufficient", "payment required", "credits", "billing", + )): + analysis = ( + "Insufficient credits or payment required. Please top up your " + f"API provider account and try again. Error: {e}" + ) + elif any(hint in err_str for hint in ( + "does not support", "not support image", + "content_policy", "multimodal", + "unrecognized request argument", "image input", + )): + analysis = ( + f"{model} does not support vision or our request was not " + f"accepted by the server. Error: {e}" + ) + elif "invalid_request" in err_str or "image_url" in err_str: + analysis = ( + "The vision API rejected the image. This can happen when the " + "image is in an unsupported format, corrupted, or still too " + "large after auto-resize. Try a smaller JPEG/PNG and retry. " + f"Error: {e}" + ) + else: + analysis = ( + "There was a problem with the request and the image could not " + f"be analyzed. Error: {e}" + ) + + # Prepare error response + result = { + "success": False, + "error": error_msg, + "analysis": analysis, + } + + debug_call_data["error"] = error_msg + _debug.log_call("vision_analyze_tool", debug_call_data) + _debug.save() + + return json.dumps(result, indent=2, ensure_ascii=False) + + finally: + # Clean up temporary image file (but NOT local/cached files) + if should_cleanup and temp_image_path and temp_image_path.exists(): + try: + temp_image_path.unlink() + logger.debug("Cleaned up temporary image file") + except Exception as cleanup_error: + logger.warning( + "Could not delete temporary file: %s", cleanup_error, exc_info=True + ) + + +def check_vision_requirements() -> bool: + """Check if the configured runtime vision path can resolve a client.""" + try: + from agent.auxiliary_client import resolve_vision_provider_client + + _provider, client, _model = resolve_vision_provider_client() + return client is not None + except Exception: + return False + + + +if __name__ == "__main__": + """ + Simple test/demo when run directly + """ + print("👁️ Vision Tools Module") + print("=" * 40) + + # Check if vision model is available + api_available = check_vision_requirements() + + if not api_available: + print("❌ No auxiliary vision model available") + print("Configure a supported multimodal backend (OpenRouter, Nous, Codex, Anthropic, or a custom OpenAI-compatible endpoint).") + exit(1) + else: + print("✅ Vision model available") + + print("🛠️ Vision tools ready for use!") + + # Show debug mode status + if _debug.active: + print(f"🐛 Debug mode ENABLED - Session ID: {_debug.session_id}") + print(f" Debug logs will be saved to: ./logs/vision_tools_debug_{_debug.session_id}.json") + else: + print("🐛 Debug mode disabled (set VISION_TOOLS_DEBUG=true to enable)") + + print("\nBasic usage:") + print(" from vision_tools import vision_analyze_tool") + print(" import asyncio") + print("") + print(" async def main():") + print(" result = await vision_analyze_tool(") + print(" image_url='https://example.com/image.jpg',") + print(" user_prompt='What do you see in this image?'") + print(" )") + print(" print(result)") + print(" asyncio.run(main())") + + print("\nExample prompts:") + print(" - 'What architectural style is this building?'") + print(" - 'Describe the emotions and mood in this image'") + print(" - 'What text can you read in this image?'") + print(" - 'Identify any safety hazards visible'") + print(" - 'What products or brands are shown?'") + + print("\nDebug mode:") + print(" # Enable debug logging") + print(" export VISION_TOOLS_DEBUG=true") + print(" # Debug logs capture all vision analysis calls and results") + print(" # Logs saved to: ./logs/vision_tools_debug_UUID.json") + + +# --------------------------------------------------------------------------- +# Registry +# --------------------------------------------------------------------------- +from tools.registry import registry, tool_error + +VISION_ANALYZE_SCHEMA = { + "name": "vision_analyze", + "description": "Analyze images using AI vision. Provides a comprehensive description and answers a specific question about the image content.", + "parameters": { + "type": "object", + "properties": { + "image_url": { + "type": "string", + "description": "Image URL (http/https) or local file path to analyze." + }, + "question": { + "type": "string", + "description": "Your specific question or request about the image to resolve. The AI will automatically provide a complete image description AND answer your specific question." + } + }, + "required": ["image_url", "question"] + } +} + + +def _handle_vision_analyze(args: Dict[str, Any], **kw: Any) -> Awaitable[str]: + image_url = args.get("image_url", "") + question = args.get("question", "") + full_prompt = ( + "Fully describe and explain everything about this image, then answer the " + f"following question:\n\n{question}" + ) + model = os.getenv("AUXILIARY_VISION_MODEL", "").strip() or None + return vision_analyze_tool(image_url, full_prompt, model) + + +registry.register( + name="vision_analyze", + toolset="vision", + schema=VISION_ANALYZE_SCHEMA, + handler=_handle_vision_analyze, + check_fn=check_vision_requirements, + is_async=True, + emoji="👁️", +) diff --git a/mindcli/_vendor/tools/voice_mode.py b/mindcli/_vendor/tools/voice_mode.py new file mode 100644 index 0000000..50515fc --- /dev/null +++ b/mindcli/_vendor/tools/voice_mode.py @@ -0,0 +1,1017 @@ +"""Voice Mode -- Push-to-talk audio recording and playback for the CLI. + +Provides audio capture via sounddevice, WAV encoding via stdlib wave, +STT dispatch via tools.transcription_tools, and TTS playback via +sounddevice or system audio players. + +Dependencies (optional): + pip install sounddevice numpy + or: pip install hermes-agent[voice] +""" + +import logging +import os +import platform +import re +import shutil +import subprocess +import tempfile +import threading +import time +import wave +from typing import Any, Dict, List, Optional + +logger = logging.getLogger(__name__) + +# --------------------------------------------------------------------------- +# Lazy audio imports -- never imported at module level to avoid crashing +# in headless environments (SSH, Docker, WSL, no PortAudio). +# --------------------------------------------------------------------------- + +def _import_audio(): + """Lazy-import sounddevice and numpy. Returns (sd, np). + + Raises ImportError or OSError if the libraries are not available + (e.g. PortAudio missing on headless servers). + """ + import sounddevice as sd + import numpy as np + return sd, np + + +def _audio_available() -> bool: + """Return True if audio libraries can be imported.""" + try: + _import_audio() + return True + except (ImportError, OSError): + return False + + +from hermes_constants import is_termux as _is_termux_environment + + +def _voice_capture_install_hint() -> str: + if _is_termux_environment(): + return "pkg install python-numpy portaudio && python -m pip install sounddevice" + return "pip install sounddevice numpy" + + +def _termux_microphone_command() -> Optional[str]: + if not _is_termux_environment(): + return None + return shutil.which("termux-microphone-record") + + + +def _termux_api_app_installed() -> bool: + if not _is_termux_environment(): + return False + try: + result = subprocess.run( + ["pm", "list", "packages", "com.termux.api"], + capture_output=True, + text=True, + timeout=5, + check=False, + ) + return "package:com.termux.api" in (result.stdout or "") + except Exception: + return False + + +def _termux_voice_capture_available() -> bool: + return _termux_microphone_command() is not None and _termux_api_app_installed() + + +def detect_audio_environment() -> dict: + """Detect if the current environment supports audio I/O. + + Returns dict with 'available' (bool), 'warnings' (list of hard-fail + reasons that block voice mode), and 'notices' (list of informational + messages that do NOT block voice mode). + """ + warnings = [] # hard-fail: these block voice mode + notices = [] # informational: logged but don't block + termux_mic_cmd = _termux_microphone_command() + termux_app_installed = _termux_api_app_installed() + termux_capture = bool(termux_mic_cmd and termux_app_installed) + + # SSH detection + if any(os.environ.get(v) for v in ('SSH_CLIENT', 'SSH_TTY', 'SSH_CONNECTION')): + warnings.append("Running over SSH -- no audio devices available") + + # Docker/Podman container detection + from hermes_constants import is_container + if is_container(): + warnings.append("Running inside Docker container -- no audio devices") + + # WSL detection — PulseAudio bridge makes audio work in WSL. + # Only block if PULSE_SERVER is not configured. + try: + with open('/proc/version', 'r') as f: + if 'microsoft' in f.read().lower(): + if os.environ.get('PULSE_SERVER'): + notices.append("Running in WSL with PulseAudio bridge") + else: + warnings.append( + "Running in WSL -- audio requires PulseAudio bridge.\n" + " 1. Set PULSE_SERVER=unix:/mnt/wslg/PulseServer\n" + " 2. Create ~/.asoundrc pointing ALSA at PulseAudio\n" + " 3. Verify with: arecord -d 3 /tmp/test.wav && aplay /tmp/test.wav" + ) + except (FileNotFoundError, PermissionError, OSError): + pass + + # Check audio libraries + try: + sd, _ = _import_audio() + try: + devices = sd.query_devices() + if not devices: + if termux_capture: + notices.append("No PortAudio devices detected, but Termux:API microphone capture is available") + else: + warnings.append("No audio input/output devices detected") + except Exception: + # In WSL with PulseAudio, device queries can fail even though + # recording/playback works fine. Don't block if PULSE_SERVER is set. + if os.environ.get('PULSE_SERVER'): + notices.append("Audio device query failed but PULSE_SERVER is set -- continuing") + elif termux_capture: + notices.append("PortAudio device query failed, but Termux:API microphone capture is available") + else: + warnings.append("Audio subsystem error (PortAudio cannot query devices)") + except ImportError: + if termux_capture: + notices.append("Termux:API microphone recording available (sounddevice not required)") + elif termux_mic_cmd and not termux_app_installed: + warnings.append( + "Termux:API Android app is not installed. Install/update the Termux:API app to use termux-microphone-record." + ) + else: + warnings.append(f"Audio libraries not installed ({_voice_capture_install_hint()})") + except OSError: + if termux_capture: + notices.append("Termux:API microphone recording available (PortAudio not required)") + elif termux_mic_cmd and not termux_app_installed: + warnings.append( + "Termux:API Android app is not installed. Install/update the Termux:API app to use termux-microphone-record." + ) + elif _is_termux_environment(): + warnings.append( + "PortAudio system library not found -- install it first:\n" + " Termux: pkg install portaudio\n" + "Then retry /voice on." + ) + else: + warnings.append( + "PortAudio system library not found -- install it first:\n" + " Linux: sudo apt-get install libportaudio2\n" + " macOS: brew install portaudio\n" + "Then retry /voice on." + ) + + return { + "available": not warnings, + "warnings": warnings, + "notices": notices, + } + +# --------------------------------------------------------------------------- +# Recording parameters +# --------------------------------------------------------------------------- +SAMPLE_RATE = 16000 # Whisper native rate +CHANNELS = 1 # Mono +DTYPE = "int16" # 16-bit PCM +SAMPLE_WIDTH = 2 # bytes per sample (int16) + +# Silence detection defaults +SILENCE_RMS_THRESHOLD = 200 # RMS below this = silence (int16 range 0-32767) +SILENCE_DURATION_SECONDS = 3.0 # Seconds of continuous silence before auto-stop + +# Temp directory for voice recordings +_TEMP_DIR = os.path.join(tempfile.gettempdir(), "hermes_voice") + + +# ============================================================================ +# Audio cues (beep tones) +# ============================================================================ +def play_beep(frequency: int = 880, duration: float = 0.12, count: int = 1) -> None: + """Play a short beep tone using numpy + sounddevice. + + Args: + frequency: Tone frequency in Hz (default 880 = A5). + duration: Duration of each beep in seconds. + count: Number of beeps to play (with short gap between). + """ + try: + sd, np = _import_audio() + except (ImportError, OSError): + return + try: + gap = 0.06 # seconds between beeps + samples_per_beep = int(SAMPLE_RATE * duration) + samples_per_gap = int(SAMPLE_RATE * gap) + + parts = [] + for i in range(count): + t = np.linspace(0, duration, samples_per_beep, endpoint=False) + # Apply fade in/out to avoid click artifacts + tone = np.sin(2 * np.pi * frequency * t) + fade_len = min(int(SAMPLE_RATE * 0.01), samples_per_beep // 4) + tone[:fade_len] *= np.linspace(0, 1, fade_len) + tone[-fade_len:] *= np.linspace(1, 0, fade_len) + parts.append((tone * 0.3 * 32767).astype(np.int16)) + if i < count - 1: + parts.append(np.zeros(samples_per_gap, dtype=np.int16)) + + audio = np.concatenate(parts) + sd.play(audio, samplerate=SAMPLE_RATE) + # sd.wait() calls Event.wait() without timeout — hangs forever if the + # audio device stalls. Poll with a 2s ceiling and force-stop. + deadline = time.monotonic() + 2.0 + while sd.get_stream() and sd.get_stream().active and time.monotonic() < deadline: + time.sleep(0.01) + sd.stop() + except Exception as e: + logger.debug("Beep playback failed: %s", e) + + +# ============================================================================ +# Termux Audio Recorder +# ============================================================================ +class TermuxAudioRecorder: + """Recorder backend that uses Termux:API microphone capture commands.""" + + supports_silence_autostop = False + + def __init__(self) -> None: + self._lock = threading.Lock() + self._recording = False + self._start_time = 0.0 + self._recording_path: Optional[str] = None + self._current_rms = 0 + + @property + def is_recording(self) -> bool: + return self._recording + + @property + def elapsed_seconds(self) -> float: + if not self._recording: + return 0.0 + return time.monotonic() - self._start_time + + @property + def current_rms(self) -> int: + return self._current_rms + + def start(self, on_silence_stop=None) -> None: + del on_silence_stop # Termux:API does not expose live silence callbacks. + mic_cmd = _termux_microphone_command() + if not mic_cmd: + raise RuntimeError( + "Termux voice capture requires the termux-api package and app.\n" + "Install with: pkg install termux-api\n" + "Then install/update the Termux:API Android app." + ) + if not _termux_api_app_installed(): + raise RuntimeError( + "Termux voice capture requires the Termux:API Android app.\n" + "Install/update the Termux:API app, then retry /voice on." + ) + + with self._lock: + if self._recording: + return + os.makedirs(_TEMP_DIR, exist_ok=True) + timestamp = time.strftime("%Y%m%d_%H%M%S") + self._recording_path = os.path.join(_TEMP_DIR, f"recording_{timestamp}.aac") + + command = [ + mic_cmd, + "-f", self._recording_path, + "-l", "0", + "-e", "aac", + "-r", str(SAMPLE_RATE), + "-c", str(CHANNELS), + ] + try: + subprocess.run(command, capture_output=True, text=True, timeout=15, check=True) + except subprocess.CalledProcessError as e: + details = (e.stderr or e.stdout or str(e)).strip() + raise RuntimeError(f"Termux microphone start failed: {details}") from e + except Exception as e: + raise RuntimeError(f"Termux microphone start failed: {e}") from e + + with self._lock: + self._start_time = time.monotonic() + self._recording = True + self._current_rms = 0 + logger.info("Termux voice recording started") + + def _stop_termux_recording(self) -> None: + mic_cmd = _termux_microphone_command() + if not mic_cmd: + return + subprocess.run([mic_cmd, "-q"], capture_output=True, text=True, timeout=15, check=False) + + def stop(self) -> Optional[str]: + with self._lock: + if not self._recording: + return None + self._recording = False + path = self._recording_path + self._recording_path = None + started_at = self._start_time + self._current_rms = 0 + + self._stop_termux_recording() + if not path or not os.path.isfile(path): + return None + if time.monotonic() - started_at < 0.3: + try: + os.unlink(path) + except OSError: + pass + return None + if os.path.getsize(path) <= 0: + try: + os.unlink(path) + except OSError: + pass + return None + logger.info("Termux voice recording stopped: %s", path) + return path + + def cancel(self) -> None: + with self._lock: + path = self._recording_path + self._recording = False + self._recording_path = None + self._current_rms = 0 + try: + self._stop_termux_recording() + except Exception: + pass + if path and os.path.isfile(path): + try: + os.unlink(path) + except OSError: + pass + logger.info("Termux voice recording cancelled") + + def shutdown(self) -> None: + self.cancel() + + +# ============================================================================ +# AudioRecorder +# ============================================================================ +class AudioRecorder: + """Thread-safe audio recorder using sounddevice.InputStream. + + Usage:: + + recorder = AudioRecorder() + recorder.start(on_silence_stop=my_callback) + # ... user speaks ... + wav_path = recorder.stop() # returns path to WAV file + # or + recorder.cancel() # discard without saving + + If ``on_silence_stop`` is provided, recording automatically stops when + the user is silent for ``silence_duration`` seconds and calls the callback. + """ + + supports_silence_autostop = True + + def __init__(self) -> None: + self._lock = threading.Lock() + self._stream: Any = None + self._frames: List[Any] = [] + self._recording = False + self._start_time: float = 0.0 + # Silence detection state + self._has_spoken = False + self._speech_start: float = 0.0 # When speech attempt began + self._dip_start: float = 0.0 # When current below-threshold dip began + self._min_speech_duration: float = 0.3 # Seconds of speech needed to confirm + self._max_dip_tolerance: float = 0.3 # Max dip duration before resetting speech + self._silence_start: float = 0.0 + self._resume_start: float = 0.0 # Tracks sustained speech after silence starts + self._resume_dip_start: float = 0.0 # Dip tolerance tracker for resume detection + self._on_silence_stop = None + self._silence_threshold: int = SILENCE_RMS_THRESHOLD + self._silence_duration: float = SILENCE_DURATION_SECONDS + self._max_wait: float = 15.0 # Max seconds to wait for speech before auto-stop + # Peak RMS seen during recording (for speech presence check in stop()) + self._peak_rms: int = 0 + # Live audio level (read by UI for visual feedback) + self._current_rms: int = 0 + + # -- public properties --------------------------------------------------- + + @property + def elapsed_seconds(self) -> float: + if not self._recording: + return 0.0 + return time.monotonic() - self._start_time + + @property + def current_rms(self) -> int: + """Current audio input RMS level (0-32767). Updated each audio chunk.""" + return self._current_rms + + @property + def is_recording(self) -> bool: + """Whether audio recording is currently active.""" + return self._recording + + # -- public methods ------------------------------------------------------ + + def _ensure_stream(self) -> None: + """Create the audio InputStream once and keep it alive. + + The stream stays open for the lifetime of the recorder. Between + recordings the callback simply discards audio chunks (``_recording`` + is ``False``). This avoids the CoreAudio bug where closing and + re-opening an ``InputStream`` hangs indefinitely on macOS. + """ + if self._stream is not None: + return # already alive + + sd, np = _import_audio() + + def _callback(indata, frames, time_info, status): # noqa: ARG001 + if status: + logger.debug("sounddevice status: %s", status) + # When not recording the stream is idle — discard audio. + if not self._recording: + return + self._frames.append(indata.copy()) + + # Compute RMS for level display and silence detection + rms = int(np.sqrt(np.mean(indata.astype(np.float64) ** 2))) + self._current_rms = rms + if rms > self._peak_rms: + self._peak_rms = rms + + # Silence detection + if self._on_silence_stop is not None: + now = time.monotonic() + elapsed = now - self._start_time + + if rms > self._silence_threshold: + # Audio is above threshold -- this is speech (or noise). + self._dip_start = 0.0 # Reset dip tracker + if self._speech_start == 0.0: + self._speech_start = now + elif not self._has_spoken and now - self._speech_start >= self._min_speech_duration: + self._has_spoken = True + logger.debug("Speech confirmed (%.2fs above threshold)", + now - self._speech_start) + # After speech is confirmed, only reset silence timer if + # speech is sustained (>0.3s above threshold). Brief + # spikes from ambient noise should NOT reset the timer. + if not self._has_spoken: + self._silence_start = 0.0 + else: + # Track resumed speech with dip tolerance. + # Brief dips below threshold are normal during speech, + # so we mirror the initial speech detection pattern: + # start tracking, tolerate short dips, confirm after 0.3s. + self._resume_dip_start = 0.0 # Above threshold — no dip + if self._resume_start == 0.0: + self._resume_start = now + elif now - self._resume_start >= self._min_speech_duration: + self._silence_start = 0.0 + self._resume_start = 0.0 + elif self._has_spoken: + # Below threshold after speech confirmed. + # Use dip tolerance before resetting resume tracker — + # natural speech has brief dips below threshold. + if self._resume_start > 0: + if self._resume_dip_start == 0.0: + self._resume_dip_start = now + elif now - self._resume_dip_start >= self._max_dip_tolerance: + # Sustained dip — user actually stopped speaking + self._resume_start = 0.0 + self._resume_dip_start = 0.0 + elif self._speech_start > 0: + # We were in a speech attempt but RMS dipped. + # Tolerate brief dips (micro-pauses between syllables). + if self._dip_start == 0.0: + self._dip_start = now + elif now - self._dip_start >= self._max_dip_tolerance: + # Dip lasted too long -- genuine silence, reset + logger.debug("Speech attempt reset (dip lasted %.2fs)", + now - self._dip_start) + self._speech_start = 0.0 + self._dip_start = 0.0 + + # Fire silence callback when: + # 1. User spoke then went silent for silence_duration, OR + # 2. No speech detected at all for max_wait seconds + should_fire = False + if self._has_spoken and rms <= self._silence_threshold: + # User was speaking and now is silent + if self._silence_start == 0.0: + self._silence_start = now + elif now - self._silence_start >= self._silence_duration: + logger.info("Silence detected (%.1fs), auto-stopping", + self._silence_duration) + should_fire = True + elif not self._has_spoken and elapsed >= self._max_wait: + logger.info("No speech within %.0fs, auto-stopping", + self._max_wait) + should_fire = True + + if should_fire: + with self._lock: + cb = self._on_silence_stop + self._on_silence_stop = None # fire only once + if cb: + def _safe_cb(): + try: + cb() + except Exception as e: + logger.error("Silence callback failed: %s", e, exc_info=True) + threading.Thread(target=_safe_cb, daemon=True).start() + + # Create stream — may block on CoreAudio (first call only). + stream = None + try: + stream = sd.InputStream( + samplerate=SAMPLE_RATE, + channels=CHANNELS, + dtype=DTYPE, + callback=_callback, + ) + stream.start() + except Exception as e: + if stream is not None: + try: + stream.close() + except Exception: + pass + raise RuntimeError( + f"Failed to open audio input stream: {e}. " + "Check that a microphone is connected and accessible." + ) from e + self._stream = stream + + def start(self, on_silence_stop=None) -> None: + """Start capturing audio from the default input device. + + The underlying InputStream is created once and kept alive across + recordings. Subsequent calls simply reset detection state and + toggle frame collection via ``_recording``. + + Args: + on_silence_stop: Optional callback invoked (in a daemon thread) when + silence is detected after speech. The callback receives no arguments. + Use this to auto-stop recording and trigger transcription. + + Raises ``RuntimeError`` if sounddevice/numpy are not installed + or if a recording is already in progress. + """ + try: + _import_audio() + except (ImportError, OSError) as e: + raise RuntimeError( + "Voice mode requires sounddevice and numpy.\n" + "Install with: pip install sounddevice numpy\n" + "Or: pip install hermes-agent[voice]" + ) from e + + with self._lock: + if self._recording: + return # already recording + + self._frames = [] + self._start_time = time.monotonic() + self._has_spoken = False + self._speech_start = 0.0 + self._dip_start = 0.0 + self._silence_start = 0.0 + self._resume_start = 0.0 + self._resume_dip_start = 0.0 + self._peak_rms = 0 + self._current_rms = 0 + self._on_silence_stop = on_silence_stop + + # Ensure the persistent stream is alive (no-op after first call). + self._ensure_stream() + + with self._lock: + self._recording = True + logger.info("Voice recording started (rate=%d, channels=%d)", SAMPLE_RATE, CHANNELS) + + def _close_stream_with_timeout(self, timeout: float = 3.0) -> None: + """Close the audio stream with a timeout to prevent CoreAudio hangs.""" + if self._stream is None: + return + + stream = self._stream + self._stream = None + + def _do_close(): + try: + stream.stop() + stream.close() + except Exception: + pass + + t = threading.Thread(target=_do_close, daemon=True) + t.start() + # Poll in short intervals so Ctrl+C is not blocked + deadline = __import__("time").monotonic() + timeout + while t.is_alive() and __import__("time").monotonic() < deadline: + t.join(timeout=0.1) + if t.is_alive(): + logger.warning("Audio stream close timed out after %.1fs — forcing ahead", timeout) + + def stop(self) -> Optional[str]: + """Stop recording and write captured audio to a WAV file. + + The underlying stream is kept alive for reuse — only frame + collection is stopped. + + Returns: + Path to the WAV file, or ``None`` if no audio was captured. + """ + with self._lock: + if not self._recording: + return None + + self._recording = False + self._current_rms = 0 + # Stream stays alive — no close needed. + + if not self._frames: + return None + + # Concatenate frames and write WAV + _, np = _import_audio() + audio_data = np.concatenate(self._frames, axis=0) + self._frames = [] + + elapsed = time.monotonic() - self._start_time + logger.info("Voice recording stopped (%.1fs, %d samples)", elapsed, len(audio_data)) + + # Skip very short recordings (< 0.3s of audio) + min_samples = int(SAMPLE_RATE * 0.3) + if len(audio_data) < min_samples: + logger.debug("Recording too short (%d samples), discarding", len(audio_data)) + return None + + # Skip silent recordings using peak RMS (not overall average, which + # gets diluted by silence at the end of the recording). + if self._peak_rms < SILENCE_RMS_THRESHOLD: + logger.info("Recording too quiet (peak RMS=%d < %d), discarding", + self._peak_rms, SILENCE_RMS_THRESHOLD) + return None + + return self._write_wav(audio_data) + + def cancel(self) -> None: + """Stop recording and discard all captured audio. + + The underlying stream is kept alive for reuse. + """ + with self._lock: + self._recording = False + self._frames = [] + self._on_silence_stop = None + self._current_rms = 0 + logger.info("Voice recording cancelled") + + def shutdown(self) -> None: + """Release the audio stream. Call when voice mode is disabled.""" + with self._lock: + self._recording = False + self._frames = [] + self._on_silence_stop = None + # Close stream OUTSIDE the lock to avoid deadlock with audio callback + self._close_stream_with_timeout() + logger.info("AudioRecorder shut down") + + # -- private helpers ----------------------------------------------------- + + @staticmethod + def _write_wav(audio_data) -> str: + """Write numpy int16 audio data to a WAV file. + + Returns the file path. + """ + os.makedirs(_TEMP_DIR, exist_ok=True) + timestamp = time.strftime("%Y%m%d_%H%M%S") + wav_path = os.path.join(_TEMP_DIR, f"recording_{timestamp}.wav") + + with wave.open(wav_path, "wb") as wf: + wf.setnchannels(CHANNELS) + wf.setsampwidth(SAMPLE_WIDTH) + wf.setframerate(SAMPLE_RATE) + wf.writeframes(audio_data.tobytes()) + + file_size = os.path.getsize(wav_path) + logger.info("WAV written: %s (%d bytes)", wav_path, file_size) + return wav_path + + +def create_audio_recorder() -> AudioRecorder | TermuxAudioRecorder: + """Return the best recorder backend for the current environment.""" + if _termux_voice_capture_available(): + return TermuxAudioRecorder() + return AudioRecorder() + + +# ============================================================================ +# Whisper hallucination filter +# ============================================================================ +# Whisper commonly hallucinates these phrases on silent/near-silent audio. +WHISPER_HALLUCINATIONS = { + "thank you.", + "thank you", + "thanks for watching.", + "thanks for watching", + "subscribe to my channel.", + "subscribe to my channel", + "like and subscribe.", + "like and subscribe", + "please subscribe.", + "please subscribe", + "thank you for watching.", + "thank you for watching", + "bye.", + "bye", + "you", + "the end.", + "the end", + # Non-English hallucinations (common on silence) + "продолжение следует", + "продолжение следует...", + "sous-titres", + "sous-titres réalisés par la communauté d'amara.org", + "sottotitoli creati dalla comunità amara.org", + "untertitel von stephanie geiges", + "amara.org", + "www.mooji.org", + "ご視聴ありがとうございました", +} + +# Regex patterns for repetitive hallucinations (e.g. "Thank you. Thank you. Thank you.") +_HALLUCINATION_REPEAT_RE = re.compile( + r'^(?:thank you|thanks|bye|you|ok|okay|the end|\.|\s|,|!)+$', + flags=re.IGNORECASE, +) + + +def is_whisper_hallucination(transcript: str) -> bool: + """Check if a transcript is a known Whisper hallucination on silence.""" + cleaned = transcript.strip().lower() + if not cleaned: + return True + # Exact match against known phrases + if cleaned.rstrip('.!') in WHISPER_HALLUCINATIONS or cleaned in WHISPER_HALLUCINATIONS: + return True + # Repetitive patterns (e.g. "Thank you. Thank you. Thank you. you") + if _HALLUCINATION_REPEAT_RE.match(cleaned): + return True + return False + + +# ============================================================================ +# STT dispatch +# ============================================================================ +def transcribe_recording(wav_path: str, model: Optional[str] = None) -> Dict[str, Any]: + """Transcribe a WAV recording using the existing Whisper pipeline. + + Delegates to ``tools.transcription_tools.transcribe_audio()``. + Filters out known Whisper hallucinations on silent audio. + + Args: + wav_path: Path to the WAV file. + model: Whisper model name (default: from config or ``whisper-1``). + + Returns: + Dict with ``success``, ``transcript``, and optionally ``error``. + """ + from tools.transcription_tools import transcribe_audio + + result = transcribe_audio(wav_path, model=model) + + # Filter out Whisper hallucinations (common on silent/near-silent audio) + if result.get("success") and is_whisper_hallucination(result.get("transcript", "")): + logger.info("Filtered Whisper hallucination: %r", result["transcript"]) + return {"success": True, "transcript": "", "filtered": True} + + return result + + +# ============================================================================ +# Audio playback (interruptable) +# ============================================================================ + +# Global reference to the active playback process so it can be interrupted. +_active_playback: Optional[subprocess.Popen] = None +_playback_lock = threading.Lock() + + +def stop_playback() -> None: + """Interrupt the currently playing audio (if any).""" + global _active_playback + with _playback_lock: + proc = _active_playback + _active_playback = None + if proc and proc.poll() is None: + try: + proc.terminate() + logger.info("Audio playback interrupted") + except Exception: + pass + # Also stop sounddevice playback if active + try: + sd, _ = _import_audio() + sd.stop() + except Exception: + pass + + +def play_audio_file(file_path: str) -> bool: + """Play an audio file through the default output device. + + Strategy: + 1. WAV files via ``sounddevice.play()`` when available. + 2. System commands: ``afplay`` (macOS), ``ffplay`` (cross-platform), + ``aplay`` (Linux ALSA). + + Playback can be interrupted by calling ``stop_playback()``. + + Returns: + ``True`` if playback succeeded, ``False`` otherwise. + """ + global _active_playback + + if not os.path.isfile(file_path): + logger.warning("Audio file not found: %s", file_path) + return False + + # Try sounddevice for WAV files + if file_path.endswith(".wav"): + try: + sd, np = _import_audio() + with wave.open(file_path, "rb") as wf: + frames = wf.readframes(wf.getnframes()) + audio_data = np.frombuffer(frames, dtype=np.int16) + sample_rate = wf.getframerate() + + sd.play(audio_data, samplerate=sample_rate) + # sd.wait() calls Event.wait() without timeout — hangs forever if + # the audio device stalls. Poll with a ceiling and force-stop. + duration_secs = len(audio_data) / sample_rate + deadline = time.monotonic() + duration_secs + 2.0 + while sd.get_stream() and sd.get_stream().active and time.monotonic() < deadline: + time.sleep(0.01) + sd.stop() + return True + except (ImportError, OSError): + pass # audio libs not available, fall through to system players + except Exception as e: + logger.debug("sounddevice playback failed: %s", e) + + # Fall back to system audio players (using Popen for interruptability) + system = platform.system() + players = [] + + if system == "Darwin": + players.append(["afplay", file_path]) + players.append(["ffplay", "-nodisp", "-autoexit", "-loglevel", "quiet", file_path]) + if system == "Linux": + players.append(["aplay", "-q", file_path]) + + for cmd in players: + exe = shutil.which(cmd[0]) + if exe: + try: + proc = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) + with _playback_lock: + _active_playback = proc + proc.wait(timeout=300) + with _playback_lock: + _active_playback = None + return True + except subprocess.TimeoutExpired: + logger.warning("System player %s timed out, killing process", cmd[0]) + proc.kill() + proc.wait() + with _playback_lock: + _active_playback = None + except Exception as e: + logger.debug("System player %s failed: %s", cmd[0], e) + with _playback_lock: + _active_playback = None + + logger.warning("No audio player available for %s", file_path) + return False + + +# ============================================================================ +# Requirements check +# ============================================================================ +def check_voice_requirements() -> Dict[str, Any]: + """Check if all voice mode requirements are met. + + Returns: + Dict with ``available``, ``audio_available``, ``stt_available``, + ``missing_packages``, and ``details``. + """ + # Determine STT provider availability + from tools.transcription_tools import _get_provider, _load_stt_config, is_stt_enabled + stt_config = _load_stt_config() + stt_enabled = is_stt_enabled(stt_config) + stt_provider = _get_provider(stt_config) + stt_available = stt_enabled and stt_provider != "none" + + missing: List[str] = [] + termux_capture = _termux_voice_capture_available() + has_audio = _audio_available() or termux_capture + + if not has_audio: + missing.extend(["sounddevice", "numpy"]) + + # Environment detection + env_check = detect_audio_environment() + + available = has_audio and stt_available and env_check["available"] + details_parts = [] + + if termux_capture: + details_parts.append("Audio capture: OK (Termux:API microphone)") + elif has_audio: + details_parts.append("Audio capture: OK") + else: + details_parts.append(f"Audio capture: MISSING ({_voice_capture_install_hint()})") + + if not stt_enabled: + details_parts.append("STT provider: DISABLED in config (stt.enabled: false)") + elif stt_provider == "local": + details_parts.append("STT provider: OK (local faster-whisper)") + elif stt_provider == "groq": + details_parts.append("STT provider: OK (Groq)") + elif stt_provider == "openai": + details_parts.append("STT provider: OK (OpenAI)") + else: + details_parts.append( + "STT provider: MISSING (pip install faster-whisper, " + "or set GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY)" + ) + + for warning in env_check["warnings"]: + details_parts.append(f"Environment: {warning}") + for notice in env_check.get("notices", []): + details_parts.append(f"Environment: {notice}") + + return { + "available": available, + "audio_available": has_audio, + "stt_available": stt_available, + "missing_packages": missing, + "details": "\n".join(details_parts), + "environment": env_check, + } + + +# ============================================================================ +# Temp file cleanup +# ============================================================================ +def cleanup_temp_recordings(max_age_seconds: int = 3600) -> int: + """Remove old temporary voice recording files. + + Args: + max_age_seconds: Delete files older than this (default: 1 hour). + + Returns: + Number of files deleted. + """ + if not os.path.isdir(_TEMP_DIR): + return 0 + + deleted = 0 + now = time.time() + + for entry in os.scandir(_TEMP_DIR): + if entry.is_file() and entry.name.startswith("recording_") and entry.name.endswith(".wav"): + try: + age = now - entry.stat().st_mtime + if age > max_age_seconds: + os.unlink(entry.path) + deleted += 1 + except OSError: + pass + + if deleted: + logger.debug("Cleaned up %d old voice recordings", deleted) + return deleted diff --git a/mindcli/_vendor/tools/web_tools.py b/mindcli/_vendor/tools/web_tools.py new file mode 100644 index 0000000..0f21328 --- /dev/null +++ b/mindcli/_vendor/tools/web_tools.py @@ -0,0 +1,2100 @@ +#!/usr/bin/env python3 +""" +Standalone Web Tools Module + +This module provides generic web tools that work with multiple backend providers. +Backend is selected during ``hermes tools`` setup (web.backend in config.yaml). +When available, Hermes can route Firecrawl calls through a Nous-hosted tool-gateway +for Nous Subscribers only. + +Available tools: +- web_search_tool: Search the web for information +- web_extract_tool: Extract content from specific web pages +- web_crawl_tool: Crawl websites with specific instructions + +Backend compatibility: +- Exa: https://exa.ai (search, extract) +- Firecrawl: https://docs.firecrawl.dev/introduction (search, extract, crawl; direct or derived firecrawl-gateway.<domain> for Nous Subscribers) +- Parallel: https://docs.parallel.ai (search, extract) +- Tavily: https://tavily.com (search, extract, crawl) + +LLM Processing: +- Uses OpenRouter API with Gemini 3 Flash Preview for intelligent content extraction +- Extracts key excerpts and creates markdown summaries to reduce token usage + +Debug Mode: +- Set WEB_TOOLS_DEBUG=true to enable detailed logging +- Creates web_tools_debug_UUID.json in ./logs directory +- Captures all tool calls, results, and compression metrics + +Usage: + from web_tools import web_search_tool, web_extract_tool, web_crawl_tool + + # Search the web + results = web_search_tool("Python machine learning libraries", limit=3) + + # Extract content from URLs + content = web_extract_tool(["https://example.com"], format="markdown") + + # Crawl a website + crawl_data = web_crawl_tool("example.com", "Find contact information") +""" + +import json +import logging +import os +import re +import asyncio +from typing import List, Dict, Any, Optional +import httpx +from firecrawl import Firecrawl +from agent.auxiliary_client import ( + async_call_llm, + extract_content_or_reasoning, + get_async_text_auxiliary_client, +) +from tools.debug_helpers import DebugSession +from tools.managed_tool_gateway import ( + build_vendor_gateway_url, + read_nous_access_token as _read_nous_access_token, + resolve_managed_tool_gateway, +) +from tools.tool_backend_helpers import managed_nous_tools_enabled +from tools.url_safety import is_safe_url +from tools.website_policy import check_website_access + +logger = logging.getLogger(__name__) + + +# ─── Backend Selection ──────────────────────────────────────────────────────── + +def _has_env(name: str) -> bool: + val = os.getenv(name) + return bool(val and val.strip()) + +def _load_web_config() -> dict: + """Load the ``web:`` section from ~/.hermes/config.yaml.""" + try: + from hermes_cli.config import load_config + return load_config().get("web", {}) + except (ImportError, Exception): + return {} + +def _get_backend() -> str: + """Determine which web backend to use. + + Reads ``web.backend`` from config.yaml (set by ``hermes tools``). + Falls back to whichever API key is present for users who configured + keys manually without running setup. + """ + configured = (_load_web_config().get("backend") or "").lower().strip() + if configured in ("parallel", "firecrawl", "tavily", "exa"): + return configured + + # Fallback for manual / legacy config — pick the highest-priority + # available backend. Firecrawl also counts as available when the managed + # tool gateway is configured for Nous subscribers. + backend_candidates = ( + ("firecrawl", _has_env("FIRECRAWL_API_KEY") or _has_env("FIRECRAWL_API_URL") or _is_tool_gateway_ready()), + ("parallel", _has_env("PARALLEL_API_KEY")), + ("tavily", _has_env("TAVILY_API_KEY")), + ("exa", _has_env("EXA_API_KEY")), + ) + for backend, available in backend_candidates: + if available: + return backend + + return "firecrawl" # default (backward compat) + + +def _is_backend_available(backend: str) -> bool: + """Return True when the selected backend is currently usable.""" + if backend == "exa": + return _has_env("EXA_API_KEY") + if backend == "parallel": + return _has_env("PARALLEL_API_KEY") + if backend == "firecrawl": + return check_firecrawl_api_key() + if backend == "tavily": + return _has_env("TAVILY_API_KEY") + return False + +# ─── Firecrawl Client ──────────────────────────────────────────────────────── + +_firecrawl_client = None +_firecrawl_client_config = None + + +def _get_direct_firecrawl_config() -> Optional[tuple[Dict[str, str], tuple[str, Optional[str], Optional[str]]]]: + """Return explicit direct Firecrawl kwargs + cache key, or None when unset.""" + api_key = os.getenv("FIRECRAWL_API_KEY", "").strip() + api_url = os.getenv("FIRECRAWL_API_URL", "").strip().rstrip("/") + + if not api_key and not api_url: + return None + + kwargs: Dict[str, str] = {} + if api_key: + kwargs["api_key"] = api_key + if api_url: + kwargs["api_url"] = api_url + + return kwargs, ("direct", api_url or None, api_key or None) + + +def _get_firecrawl_gateway_url() -> str: + """Return configured Firecrawl gateway URL.""" + return build_vendor_gateway_url("firecrawl") + + +def _is_tool_gateway_ready() -> bool: + """Return True when gateway URL and a Nous Subscriber token are available.""" + return resolve_managed_tool_gateway("firecrawl", token_reader=_read_nous_access_token) is not None + + +def _has_direct_firecrawl_config() -> bool: + """Return True when direct Firecrawl config is explicitly configured.""" + return _get_direct_firecrawl_config() is not None + + +def _raise_web_backend_configuration_error() -> None: + """Raise a clear error for unsupported web backend configuration.""" + message = ( + "Web tools are not configured. " + "Set FIRECRAWL_API_KEY for cloud Firecrawl or set FIRECRAWL_API_URL for a self-hosted Firecrawl instance." + ) + if managed_nous_tools_enabled(): + message += ( + " If you have the hidden Nous-managed tools flag enabled, you can also login to Nous " + "(`hermes model`) and provide FIRECRAWL_GATEWAY_URL or TOOL_GATEWAY_DOMAIN." + ) + raise ValueError(message) + + +def _firecrawl_backend_help_suffix() -> str: + """Return optional managed-gateway guidance for Firecrawl help text.""" + if not managed_nous_tools_enabled(): + return "" + return ( + ", or, if you have the hidden Nous-managed tools flag enabled, login to Nous and use " + "FIRECRAWL_GATEWAY_URL or TOOL_GATEWAY_DOMAIN" + ) + + +def _web_requires_env() -> list[str]: + """Return tool metadata env vars for the currently enabled web backends.""" + requires = [ + "EXA_API_KEY", + "PARALLEL_API_KEY", + "TAVILY_API_KEY", + "FIRECRAWL_API_KEY", + "FIRECRAWL_API_URL", + ] + if managed_nous_tools_enabled(): + requires.extend( + [ + "FIRECRAWL_GATEWAY_URL", + "TOOL_GATEWAY_DOMAIN", + "TOOL_GATEWAY_SCHEME", + "TOOL_GATEWAY_USER_TOKEN", + ] + ) + return requires + + +def _get_firecrawl_client(): + """Get or create Firecrawl client. + + Direct Firecrawl takes precedence when explicitly configured. Otherwise + Hermes falls back to the Firecrawl tool-gateway for logged-in Nous Subscribers. + """ + global _firecrawl_client, _firecrawl_client_config + + direct_config = _get_direct_firecrawl_config() + if direct_config is not None: + kwargs, client_config = direct_config + else: + managed_gateway = resolve_managed_tool_gateway( + "firecrawl", + token_reader=_read_nous_access_token, + ) + if managed_gateway is None: + logger.error("Firecrawl client initialization failed: missing direct config and tool-gateway auth.") + _raise_web_backend_configuration_error() + + kwargs = { + "api_key": managed_gateway.nous_user_token, + "api_url": managed_gateway.gateway_origin, + } + client_config = ( + "tool-gateway", + kwargs["api_url"], + managed_gateway.nous_user_token, + ) + + if _firecrawl_client is not None and _firecrawl_client_config == client_config: + return _firecrawl_client + + _firecrawl_client = Firecrawl(**kwargs) + _firecrawl_client_config = client_config + return _firecrawl_client + +# ─── Parallel Client ───────────────────────────────────────────────────────── + +_parallel_client = None +_async_parallel_client = None + +def _get_parallel_client(): + """Get or create the Parallel sync client (lazy initialization). + + Requires PARALLEL_API_KEY environment variable. + """ + from parallel import Parallel + global _parallel_client + if _parallel_client is None: + api_key = os.getenv("PARALLEL_API_KEY") + if not api_key: + raise ValueError( + "PARALLEL_API_KEY environment variable not set. " + "Get your API key at https://parallel.ai" + ) + _parallel_client = Parallel(api_key=api_key) + return _parallel_client + + +def _get_async_parallel_client(): + """Get or create the Parallel async client (lazy initialization). + + Requires PARALLEL_API_KEY environment variable. + """ + from parallel import AsyncParallel + global _async_parallel_client + if _async_parallel_client is None: + api_key = os.getenv("PARALLEL_API_KEY") + if not api_key: + raise ValueError( + "PARALLEL_API_KEY environment variable not set. " + "Get your API key at https://parallel.ai" + ) + _async_parallel_client = AsyncParallel(api_key=api_key) + return _async_parallel_client + +# ─── Tavily Client ─────────────────────────────────────────────────────────── + +_TAVILY_BASE_URL = "https://api.tavily.com" + + +def _tavily_request(endpoint: str, payload: dict) -> dict: + """Send a POST request to the Tavily API. + + Auth is provided via ``api_key`` in the JSON body (no header-based auth). + Raises ``ValueError`` if ``TAVILY_API_KEY`` is not set. + """ + api_key = os.getenv("TAVILY_API_KEY") + if not api_key: + raise ValueError( + "TAVILY_API_KEY environment variable not set. " + "Get your API key at https://app.tavily.com/home" + ) + payload["api_key"] = api_key + url = f"{_TAVILY_BASE_URL}/{endpoint.lstrip('/')}" + logger.info("Tavily %s request to %s", endpoint, url) + response = httpx.post(url, json=payload, timeout=60) + response.raise_for_status() + return response.json() + + +def _normalize_tavily_search_results(response: dict) -> dict: + """Normalize Tavily /search response to the standard web search format. + + Tavily returns ``{results: [{title, url, content, score, ...}]}``. + We map to ``{success, data: {web: [{title, url, description, position}]}}``. + """ + web_results = [] + for i, result in enumerate(response.get("results", [])): + web_results.append({ + "title": result.get("title", ""), + "url": result.get("url", ""), + "description": result.get("content", ""), + "position": i + 1, + }) + return {"success": True, "data": {"web": web_results}} + + +def _normalize_tavily_documents(response: dict, fallback_url: str = "") -> List[Dict[str, Any]]: + """Normalize Tavily /extract or /crawl response to the standard document format. + + Maps results to ``{url, title, content, raw_content, metadata}`` and + includes any ``failed_results`` / ``failed_urls`` as error entries. + """ + documents: List[Dict[str, Any]] = [] + for result in response.get("results", []): + url = result.get("url", fallback_url) + raw = result.get("raw_content", "") or result.get("content", "") + documents.append({ + "url": url, + "title": result.get("title", ""), + "content": raw, + "raw_content": raw, + "metadata": {"sourceURL": url, "title": result.get("title", "")}, + }) + # Handle failed results + for fail in response.get("failed_results", []): + documents.append({ + "url": fail.get("url", fallback_url), + "title": "", + "content": "", + "raw_content": "", + "error": fail.get("error", "extraction failed"), + "metadata": {"sourceURL": fail.get("url", fallback_url)}, + }) + for fail_url in response.get("failed_urls", []): + url_str = fail_url if isinstance(fail_url, str) else str(fail_url) + documents.append({ + "url": url_str, + "title": "", + "content": "", + "raw_content": "", + "error": "extraction failed", + "metadata": {"sourceURL": url_str}, + }) + return documents + + +def _to_plain_object(value: Any) -> Any: + """Convert SDK objects to plain python data structures when possible.""" + if value is None: + return None + + if isinstance(value, (dict, list, str, int, float, bool)): + return value + + if hasattr(value, "model_dump"): + try: + return value.model_dump() + except Exception: + pass + + if hasattr(value, "__dict__"): + try: + return {k: v for k, v in value.__dict__.items() if not k.startswith("_")} + except Exception: + pass + + return value + + +def _normalize_result_list(values: Any) -> List[Dict[str, Any]]: + """Normalize mixed SDK/list payloads into a list of dicts.""" + if not isinstance(values, list): + return [] + + normalized: List[Dict[str, Any]] = [] + for item in values: + plain = _to_plain_object(item) + if isinstance(plain, dict): + normalized.append(plain) + return normalized + + +def _extract_web_search_results(response: Any) -> List[Dict[str, Any]]: + """Extract Firecrawl search results across SDK/direct/gateway response shapes.""" + response_plain = _to_plain_object(response) + + if isinstance(response_plain, dict): + data = response_plain.get("data") + if isinstance(data, list): + return _normalize_result_list(data) + + if isinstance(data, dict): + data_web = _normalize_result_list(data.get("web")) + if data_web: + return data_web + data_results = _normalize_result_list(data.get("results")) + if data_results: + return data_results + + top_web = _normalize_result_list(response_plain.get("web")) + if top_web: + return top_web + + top_results = _normalize_result_list(response_plain.get("results")) + if top_results: + return top_results + + if hasattr(response, "web"): + return _normalize_result_list(getattr(response, "web", [])) + + return [] + + +def _extract_scrape_payload(scrape_result: Any) -> Dict[str, Any]: + """Normalize Firecrawl scrape payload shape across SDK and gateway variants.""" + result_plain = _to_plain_object(scrape_result) + if not isinstance(result_plain, dict): + return {} + + nested = result_plain.get("data") + if isinstance(nested, dict): + return nested + + return result_plain + + +DEFAULT_MIN_LENGTH_FOR_SUMMARIZATION = 5000 + +def _is_nous_auxiliary_client(client: Any) -> bool: + """Return True when the resolved auxiliary backend is Nous Portal.""" + from urllib.parse import urlparse + + base_url = str(getattr(client, "base_url", "") or "") + host = (urlparse(base_url).hostname or "").lower() + return host == "nousresearch.com" or host.endswith(".nousresearch.com") + + +def _resolve_web_extract_auxiliary(model: Optional[str] = None) -> tuple[Optional[Any], Optional[str], Dict[str, Any]]: + """Resolve the current web-extract auxiliary client, model, and extra body.""" + client, default_model = get_async_text_auxiliary_client("web_extract") + configured_model = os.getenv("AUXILIARY_WEB_EXTRACT_MODEL", "").strip() + effective_model = model or configured_model or default_model + + extra_body: Dict[str, Any] = {} + if client is not None and _is_nous_auxiliary_client(client): + from agent.auxiliary_client import get_auxiliary_extra_body + extra_body = get_auxiliary_extra_body() or {"tags": ["product=hermes-agent"]} + + return client, effective_model, extra_body + + +def _get_default_summarizer_model() -> Optional[str]: + """Return the current default model for web extraction summarization.""" + _, model, _ = _resolve_web_extract_auxiliary() + return model + +_debug = DebugSession("web_tools", env_var="WEB_TOOLS_DEBUG") + + +async def process_content_with_llm( + content: str, + url: str = "", + title: str = "", + model: Optional[str] = None, + min_length: int = DEFAULT_MIN_LENGTH_FOR_SUMMARIZATION +) -> Optional[str]: + """ + Process web content using LLM to create intelligent summaries with key excerpts. + + This function uses Gemini 3 Flash Preview (or specified model) via OpenRouter API + to intelligently extract key information and create markdown summaries, + significantly reducing token usage while preserving all important information. + + For very large content (>500k chars), uses chunked processing with synthesis. + For extremely large content (>2M chars), refuses to process entirely. + + Args: + content (str): The raw content to process + url (str): The source URL (for context, optional) + title (str): The page title (for context, optional) + model (str): The model to use for processing (default: google/gemini-3-flash-preview) + min_length (int): Minimum content length to trigger processing (default: 5000) + + Returns: + Optional[str]: Processed markdown content, or None if content too short or processing fails + """ + # Size thresholds + MAX_CONTENT_SIZE = 2_000_000 # 2M chars - refuse entirely above this + CHUNK_THRESHOLD = 500_000 # 500k chars - use chunked processing above this + CHUNK_SIZE = 100_000 # 100k chars per chunk + MAX_OUTPUT_SIZE = 5000 # Hard cap on final output size + + try: + content_len = len(content) + + # Refuse if content is absurdly large + if content_len > MAX_CONTENT_SIZE: + size_mb = content_len / 1_000_000 + logger.warning("Content too large (%.1fMB > 2MB limit). Refusing to process.", size_mb) + return f"[Content too large to process: {size_mb:.1f}MB. Try using web_crawl with specific extraction instructions, or search for a more focused source.]" + + # Skip processing if content is too short + if content_len < min_length: + logger.debug("Content too short (%d < %d chars), skipping LLM processing", content_len, min_length) + return None + + # Create context information + context_info = [] + if title: + context_info.append(f"Title: {title}") + if url: + context_info.append(f"Source: {url}") + context_str = "\n".join(context_info) + "\n\n" if context_info else "" + + # Check if we need chunked processing + if content_len > CHUNK_THRESHOLD: + logger.info("Content large (%d chars). Using chunked processing...", content_len) + return await _process_large_content_chunked( + content, context_str, model, CHUNK_SIZE, MAX_OUTPUT_SIZE + ) + + # Standard single-pass processing for normal content + logger.info("Processing content with LLM (%d characters)", content_len) + + processed_content = await _call_summarizer_llm(content, context_str, model) + + if processed_content: + # Enforce output cap + if len(processed_content) > MAX_OUTPUT_SIZE: + processed_content = processed_content[:MAX_OUTPUT_SIZE] + "\n\n[... summary truncated for context management ...]" + + # Log compression metrics + processed_length = len(processed_content) + compression_ratio = processed_length / content_len if content_len > 0 else 1.0 + logger.info("Content processed: %d -> %d chars (%.1f%%)", content_len, processed_length, compression_ratio * 100) + + return processed_content + + except Exception as e: + logger.warning( + "web_extract LLM summarization failed (%s). " + "Tip: increase auxiliary.web_extract.timeout in config.yaml " + "or switch to a faster auxiliary model.", + str(e)[:120], + ) + # Fall back to truncated raw content instead of returning a useless + # error message. The first ~5000 chars are almost always more useful + # to the model than "[Failed to process content: ...]". + truncated = content[:MAX_OUTPUT_SIZE] + if len(content) > MAX_OUTPUT_SIZE: + truncated += ( + f"\n\n[Content truncated — showing first {MAX_OUTPUT_SIZE:,} of " + f"{len(content):,} chars. LLM summarization timed out. " + f"To fix: increase auxiliary.web_extract.timeout in config.yaml, " + f"or use a faster auxiliary model. Use browser_navigate for the full page.]" + ) + return truncated + + +async def _call_summarizer_llm( + content: str, + context_str: str, + model: Optional[str], + max_tokens: int = 20000, + is_chunk: bool = False, + chunk_info: str = "" +) -> Optional[str]: + """ + Make a single LLM call to summarize content. + + Args: + content: The content to summarize + context_str: Context information (title, URL) + model: Model to use + max_tokens: Maximum output tokens + is_chunk: Whether this is a chunk of a larger document + chunk_info: Information about chunk position (e.g., "Chunk 2/5") + + Returns: + Summarized content or None on failure + """ + if is_chunk: + # Chunk-specific prompt - aware that this is partial content + system_prompt = """You are an expert content analyst processing a SECTION of a larger document. Your job is to extract and summarize the key information from THIS SECTION ONLY. + +Important guidelines for chunk processing: +1. Do NOT write introductions or conclusions - this is a partial document +2. Focus on extracting ALL key facts, figures, data points, and insights from this section +3. Preserve important quotes, code snippets, and specific details verbatim +4. Use bullet points and structured formatting for easy synthesis later +5. Note any references to other sections (e.g., "as mentioned earlier", "see below") without trying to resolve them + +Your output will be combined with summaries of other sections, so focus on thorough extraction rather than narrative flow.""" + + user_prompt = f"""Extract key information from this SECTION of a larger document: + +{context_str}{chunk_info} + +SECTION CONTENT: +{content} + +Extract all important information from this section in a structured format. Focus on facts, data, insights, and key details. Do not add introductions or conclusions.""" + + else: + # Standard full-document prompt + system_prompt = """You are an expert content analyst. Your job is to process web content and create a comprehensive yet concise summary that preserves all important information while dramatically reducing bulk. + +Create a well-structured markdown summary that includes: +1. Key excerpts (quotes, code snippets, important facts) in their original format +2. Comprehensive summary of all other important information +3. Proper markdown formatting with headers, bullets, and emphasis + +Your goal is to preserve ALL important information while reducing length. Never lose key facts, figures, insights, or actionable information. Make it scannable and well-organized.""" + + user_prompt = f"""Please process this web content and create a comprehensive markdown summary: + +{context_str}CONTENT TO PROCESS: +{content} + +Create a markdown summary that captures all key information in a well-organized, scannable format. Include important quotes and code snippets in their original formatting. Focus on actionable information, specific details, and unique insights.""" + + # Call the LLM with retry logic — keep retries low since summarization + # is a nice-to-have; the caller falls back to truncated content on failure. + max_retries = 2 + retry_delay = 2 + last_error = None + + for attempt in range(max_retries): + try: + aux_client, effective_model, extra_body = _resolve_web_extract_auxiliary(model) + if aux_client is None or not effective_model: + logger.warning("No auxiliary model available for web content processing") + return None + call_kwargs = { + "task": "web_extract", + "model": effective_model, + "messages": [ + {"role": "system", "content": system_prompt}, + {"role": "user", "content": user_prompt}, + ], + "temperature": 0.1, + "max_tokens": max_tokens, + # No explicit timeout — async_call_llm reads auxiliary.web_extract.timeout + # from config (default 360s / 6min). Users with slow local models can + # increase it in config.yaml. + } + if extra_body: + call_kwargs["extra_body"] = extra_body + response = await async_call_llm(**call_kwargs) + content = extract_content_or_reasoning(response) + if content: + return content + # Reasoning-only / empty response — let the retry loop handle it + logger.warning("LLM returned empty content (attempt %d/%d), retrying", attempt + 1, max_retries) + if attempt < max_retries - 1: + await asyncio.sleep(retry_delay) + retry_delay = min(retry_delay * 2, 60) + continue + return content # Return whatever we got after exhausting retries + except RuntimeError: + logger.warning("No auxiliary model available for web content processing") + return None + except Exception as api_error: + last_error = api_error + if attempt < max_retries - 1: + logger.warning("LLM API call failed (attempt %d/%d): %s", attempt + 1, max_retries, str(api_error)[:100]) + logger.warning("Retrying in %ds...", retry_delay) + await asyncio.sleep(retry_delay) + retry_delay = min(retry_delay * 2, 60) + else: + raise last_error + + return None + + +async def _process_large_content_chunked( + content: str, + context_str: str, + model: Optional[str], + chunk_size: int, + max_output_size: int +) -> Optional[str]: + """ + Process large content by chunking, summarizing each chunk in parallel, + then synthesizing the summaries. + + Args: + content: The large content to process + context_str: Context information + model: Model to use + chunk_size: Size of each chunk in characters + max_output_size: Maximum final output size + + Returns: + Synthesized summary or None on failure + """ + # Split content into chunks + chunks = [] + for i in range(0, len(content), chunk_size): + chunk = content[i:i + chunk_size] + chunks.append(chunk) + + logger.info("Split into %d chunks of ~%d chars each", len(chunks), chunk_size) + + # Summarize each chunk in parallel + async def summarize_chunk(chunk_idx: int, chunk_content: str) -> tuple[int, Optional[str]]: + """Summarize a single chunk.""" + try: + chunk_info = f"[Processing chunk {chunk_idx + 1} of {len(chunks)}]" + summary = await _call_summarizer_llm( + chunk_content, + context_str, + model, + max_tokens=10000, + is_chunk=True, + chunk_info=chunk_info + ) + if summary: + logger.info("Chunk %d/%d summarized: %d -> %d chars", chunk_idx + 1, len(chunks), len(chunk_content), len(summary)) + return chunk_idx, summary + except Exception as e: + logger.warning("Chunk %d/%d failed: %s", chunk_idx + 1, len(chunks), str(e)[:50]) + return chunk_idx, None + + # Run all chunk summarizations in parallel + tasks = [summarize_chunk(i, chunk) for i, chunk in enumerate(chunks)] + results = await asyncio.gather(*tasks) + + # Collect successful summaries in order + summaries = [] + for chunk_idx, summary in sorted(results, key=lambda x: x[0]): + if summary: + summaries.append(f"## Section {chunk_idx + 1}\n{summary}") + + if not summaries: + logger.debug("All chunk summarizations failed") + return "[Failed to process large content: all chunk summarizations failed]" + + logger.info("Got %d/%d chunk summaries", len(summaries), len(chunks)) + + # If only one chunk succeeded, just return it (with cap) + if len(summaries) == 1: + result = summaries[0] + if len(result) > max_output_size: + result = result[:max_output_size] + "\n\n[... truncated ...]" + return result + + # Synthesize the summaries into a final summary + logger.info("Synthesizing %d summaries...", len(summaries)) + + combined_summaries = "\n\n---\n\n".join(summaries) + + synthesis_prompt = f"""You have been given summaries of different sections of a large document. +Synthesize these into ONE cohesive, comprehensive summary that: +1. Removes redundancy between sections +2. Preserves all key facts, figures, and actionable information +3. Is well-organized with clear structure +4. Is under {max_output_size} characters + +{context_str}SECTION SUMMARIES: +{combined_summaries} + +Create a single, unified markdown summary.""" + + try: + aux_client, effective_model, extra_body = _resolve_web_extract_auxiliary(model) + if aux_client is None or not effective_model: + logger.warning("No auxiliary model for synthesis, concatenating summaries") + fallback = "\n\n".join(summaries) + if len(fallback) > max_output_size: + fallback = fallback[:max_output_size] + "\n\n[... truncated ...]" + return fallback + + call_kwargs = { + "task": "web_extract", + "model": effective_model, + "messages": [ + {"role": "system", "content": "You synthesize multiple summaries into one cohesive, comprehensive summary. Be thorough but concise."}, + {"role": "user", "content": synthesis_prompt}, + ], + "temperature": 0.1, + "max_tokens": 20000, + } + if extra_body: + call_kwargs["extra_body"] = extra_body + response = await async_call_llm(**call_kwargs) + final_summary = extract_content_or_reasoning(response) + + # Retry once on empty content (reasoning-only response) + if not final_summary: + logger.warning("Synthesis LLM returned empty content, retrying once") + response = await async_call_llm(**call_kwargs) + final_summary = extract_content_or_reasoning(response) + + # If still None after retry, fall back to concatenated summaries + if not final_summary: + logger.warning("Synthesis failed after retry — concatenating chunk summaries") + fallback = "\n\n".join(summaries) + if len(fallback) > max_output_size: + fallback = fallback[:max_output_size] + "\n\n[... truncated ...]" + return fallback + + # Enforce hard cap + if len(final_summary) > max_output_size: + final_summary = final_summary[:max_output_size] + "\n\n[... summary truncated for context management ...]" + + original_len = len(content) + final_len = len(final_summary) + compression = final_len / original_len if original_len > 0 else 1.0 + + logger.info("Synthesis complete: %d -> %d chars (%.2f%%)", original_len, final_len, compression * 100) + return final_summary + + except Exception as e: + logger.warning("Synthesis failed: %s", str(e)[:100]) + # Fall back to concatenated summaries with truncation + fallback = "\n\n".join(summaries) + if len(fallback) > max_output_size: + fallback = fallback[:max_output_size] + "\n\n[... truncated due to synthesis failure ...]" + return fallback + + +def clean_base64_images(text: str) -> str: + """ + Remove base64 encoded images from text to reduce token count and clutter. + + This function finds and removes base64 encoded images in various formats: + - (data:image/png;base64,...) + - (data:image/jpeg;base64,...) + - (data:image/svg+xml;base64,...) + - data:image/[type];base64,... (without parentheses) + + Args: + text: The text content to clean + + Returns: + Cleaned text with base64 images replaced with placeholders + """ + # Pattern to match base64 encoded images wrapped in parentheses + # Matches: (data:image/[type];base64,[base64-string]) + base64_with_parens_pattern = r'\(data:image/[^;]+;base64,[A-Za-z0-9+/=]+\)' + + # Pattern to match base64 encoded images without parentheses + # Matches: data:image/[type];base64,[base64-string] + base64_pattern = r'data:image/[^;]+;base64,[A-Za-z0-9+/=]+' + + # Replace parentheses-wrapped images first + cleaned_text = re.sub(base64_with_parens_pattern, '[BASE64_IMAGE_REMOVED]', text) + + # Then replace any remaining non-parentheses images + cleaned_text = re.sub(base64_pattern, '[BASE64_IMAGE_REMOVED]', cleaned_text) + + return cleaned_text + + +# ─── Exa Client ────────────────────────────────────────────────────────────── + +_exa_client = None + +def _get_exa_client(): + """Get or create the Exa client (lazy initialization). + + Requires EXA_API_KEY environment variable. + """ + from exa_py import Exa + global _exa_client + if _exa_client is None: + api_key = os.getenv("EXA_API_KEY") + if not api_key: + raise ValueError( + "EXA_API_KEY environment variable not set. " + "Get your API key at https://exa.ai" + ) + _exa_client = Exa(api_key=api_key) + _exa_client.headers["x-exa-integration"] = "hermes-agent" + return _exa_client + + +# ─── Exa Search & Extract Helpers ───────────────────────────────────────────── + +def _exa_search(query: str, limit: int = 10) -> dict: + """Search using the Exa SDK and return results as a dict.""" + from tools.interrupt import is_interrupted + if is_interrupted(): + return {"error": "Interrupted", "success": False} + + logger.info("Exa search: '%s' (limit=%d)", query, limit) + response = _get_exa_client().search( + query, + num_results=limit, + contents={ + "highlights": True, + }, + ) + + web_results = [] + for i, result in enumerate(response.results or []): + highlights = result.highlights or [] + web_results.append({ + "url": result.url or "", + "title": result.title or "", + "description": " ".join(highlights) if highlights else "", + "position": i + 1, + }) + + return {"success": True, "data": {"web": web_results}} + + +def _exa_extract(urls: List[str]) -> List[Dict[str, Any]]: + """Extract content from URLs using the Exa SDK. + + Returns a list of result dicts matching the structure expected by the + LLM post-processing pipeline (url, title, content, metadata). + """ + from tools.interrupt import is_interrupted + if is_interrupted(): + return [{"url": u, "error": "Interrupted", "title": ""} for u in urls] + + logger.info("Exa extract: %d URL(s)", len(urls)) + response = _get_exa_client().get_contents( + urls, + text=True, + ) + + results = [] + for result in response.results or []: + content = result.text or "" + url = result.url or "" + title = result.title or "" + results.append({ + "url": url, + "title": title, + "content": content, + "raw_content": content, + "metadata": {"sourceURL": url, "title": title}, + }) + + return results + + +# ─── Parallel Search & Extract Helpers ──────────────────────────────────────── + +def _parallel_search(query: str, limit: int = 5) -> dict: + """Search using the Parallel SDK and return results as a dict.""" + from tools.interrupt import is_interrupted + if is_interrupted(): + return {"error": "Interrupted", "success": False} + + mode = os.getenv("PARALLEL_SEARCH_MODE", "agentic").lower().strip() + if mode not in ("fast", "one-shot", "agentic"): + mode = "agentic" + + logger.info("Parallel search: '%s' (mode=%s, limit=%d)", query, mode, limit) + response = _get_parallel_client().beta.search( + search_queries=[query], + objective=query, + mode=mode, + max_results=min(limit, 20), + ) + + web_results = [] + for i, result in enumerate(response.results or []): + excerpts = result.excerpts or [] + web_results.append({ + "url": result.url or "", + "title": result.title or "", + "description": " ".join(excerpts) if excerpts else "", + "position": i + 1, + }) + + return {"success": True, "data": {"web": web_results}} + + +async def _parallel_extract(urls: List[str]) -> List[Dict[str, Any]]: + """Extract content from URLs using the Parallel async SDK. + + Returns a list of result dicts matching the structure expected by the + LLM post-processing pipeline (url, title, content, metadata). + """ + from tools.interrupt import is_interrupted + if is_interrupted(): + return [{"url": u, "error": "Interrupted", "title": ""} for u in urls] + + logger.info("Parallel extract: %d URL(s)", len(urls)) + response = await _get_async_parallel_client().beta.extract( + urls=urls, + full_content=True, + ) + + results = [] + for result in response.results or []: + content = result.full_content or "" + if not content: + content = "\n\n".join(result.excerpts or []) + url = result.url or "" + title = result.title or "" + results.append({ + "url": url, + "title": title, + "content": content, + "raw_content": content, + "metadata": {"sourceURL": url, "title": title}, + }) + + for error in response.errors or []: + results.append({ + "url": error.url or "", + "title": "", + "content": "", + "error": error.content or error.error_type or "extraction failed", + "metadata": {"sourceURL": error.url or ""}, + }) + + return results + + +def web_search_tool(query: str, limit: int = 5) -> str: + """ + Search the web for information using available search API backend. + + This function provides a generic interface for web search that can work + with multiple backends (Parallel or Firecrawl). + + Note: This function returns search result metadata only (URLs, titles, descriptions). + Use web_extract_tool to get full content from specific URLs. + + Args: + query (str): The search query to look up + limit (int): Maximum number of results to return (default: 5) + + Returns: + str: JSON string containing search results with the following structure: + { + "success": bool, + "data": { + "web": [ + { + "title": str, + "url": str, + "description": str, + "position": int + }, + ... + ] + } + } + + Raises: + Exception: If search fails or API key is not set + """ + debug_call_data = { + "parameters": { + "query": query, + "limit": limit + }, + "error": None, + "results_count": 0, + "original_response_size": 0, + "final_response_size": 0 + } + + try: + from tools.interrupt import is_interrupted + if is_interrupted(): + return tool_error("Interrupted", success=False) + + # Dispatch to the configured backend + backend = _get_backend() + if backend == "parallel": + response_data = _parallel_search(query, limit) + debug_call_data["results_count"] = len(response_data.get("data", {}).get("web", [])) + result_json = json.dumps(response_data, indent=2, ensure_ascii=False) + debug_call_data["final_response_size"] = len(result_json) + _debug.log_call("web_search_tool", debug_call_data) + _debug.save() + return result_json + + if backend == "exa": + response_data = _exa_search(query, limit) + debug_call_data["results_count"] = len(response_data.get("data", {}).get("web", [])) + result_json = json.dumps(response_data, indent=2, ensure_ascii=False) + debug_call_data["final_response_size"] = len(result_json) + _debug.log_call("web_search_tool", debug_call_data) + _debug.save() + return result_json + + if backend == "tavily": + logger.info("Tavily search: '%s' (limit: %d)", query, limit) + raw = _tavily_request("search", { + "query": query, + "max_results": min(limit, 20), + "include_raw_content": False, + "include_images": False, + }) + response_data = _normalize_tavily_search_results(raw) + debug_call_data["results_count"] = len(response_data.get("data", {}).get("web", [])) + result_json = json.dumps(response_data, indent=2, ensure_ascii=False) + debug_call_data["final_response_size"] = len(result_json) + _debug.log_call("web_search_tool", debug_call_data) + _debug.save() + return result_json + + logger.info("Searching the web for: '%s' (limit: %d)", query, limit) + + response = _get_firecrawl_client().search( + query=query, + limit=limit + ) + + web_results = _extract_web_search_results(response) + results_count = len(web_results) + logger.info("Found %d search results", results_count) + + # Build response with just search metadata (URLs, titles, descriptions) + response_data = { + "success": True, + "data": { + "web": web_results + } + } + + # Capture debug information + debug_call_data["results_count"] = results_count + + # Convert to JSON + result_json = json.dumps(response_data, indent=2, ensure_ascii=False) + + debug_call_data["final_response_size"] = len(result_json) + + # Log debug information + _debug.log_call("web_search_tool", debug_call_data) + _debug.save() + + return result_json + + except Exception as e: + error_msg = f"Error searching web: {str(e)}" + logger.debug("%s", error_msg) + + debug_call_data["error"] = error_msg + _debug.log_call("web_search_tool", debug_call_data) + _debug.save() + + return tool_error(error_msg) + + +async def web_extract_tool( + urls: List[str], + format: str = None, + use_llm_processing: bool = True, + model: Optional[str] = None, + min_length: int = DEFAULT_MIN_LENGTH_FOR_SUMMARIZATION +) -> str: + """ + Extract content from specific web pages using available extraction API backend. + + This function provides a generic interface for web content extraction that + can work with multiple backends. Currently uses Firecrawl. + + Args: + urls (List[str]): List of URLs to extract content from + format (str): Desired output format ("markdown" or "html", optional) + use_llm_processing (bool): Whether to process content with LLM for summarization (default: True) + model (Optional[str]): The model to use for LLM processing (defaults to current auxiliary backend model) + min_length (int): Minimum content length to trigger LLM processing (default: 5000) + + Security: URLs are checked for embedded secrets before fetching. + + Returns: + str: JSON string containing extracted content. If LLM processing is enabled and successful, + the 'content' field will contain the processed markdown summary instead of raw content. + + Raises: + Exception: If extraction fails or API key is not set + """ + # Block URLs containing embedded secrets (exfiltration prevention). + # URL-decode first so percent-encoded secrets (%73k- = sk-) are caught. + from agent.redact import _PREFIX_RE + from urllib.parse import unquote + for _url in urls: + if _PREFIX_RE.search(_url) or _PREFIX_RE.search(unquote(_url)): + return json.dumps({ + "success": False, + "error": "Blocked: URL contains what appears to be an API key or token. " + "Secrets must not be sent in URLs.", + }) + + debug_call_data = { + "parameters": { + "urls": urls, + "format": format, + "use_llm_processing": use_llm_processing, + "model": model, + "min_length": min_length + }, + "error": None, + "pages_extracted": 0, + "pages_processed_with_llm": 0, + "original_response_size": 0, + "final_response_size": 0, + "compression_metrics": [], + "processing_applied": [] + } + + try: + logger.info("Extracting content from %d URL(s)", len(urls)) + + # ── SSRF protection — filter out private/internal URLs before any backend ── + safe_urls = [] + ssrf_blocked: List[Dict[str, Any]] = [] + for url in urls: + if not is_safe_url(url): + ssrf_blocked.append({ + "url": url, "title": "", "content": "", + "error": "Blocked: URL targets a private or internal network address", + }) + else: + safe_urls.append(url) + + # Dispatch only safe URLs to the configured backend + if not safe_urls: + results = [] + else: + backend = _get_backend() + + if backend == "parallel": + results = await _parallel_extract(safe_urls) + elif backend == "exa": + results = _exa_extract(safe_urls) + elif backend == "tavily": + logger.info("Tavily extract: %d URL(s)", len(safe_urls)) + raw = _tavily_request("extract", { + "urls": safe_urls, + "include_images": False, + }) + results = _normalize_tavily_documents(raw, fallback_url=safe_urls[0] if safe_urls else "") + else: + # ── Firecrawl extraction ── + # Determine requested formats for Firecrawl v2 + formats: List[str] = [] + if format == "markdown": + formats = ["markdown"] + elif format == "html": + formats = ["html"] + else: + # Default: request markdown for LLM-readiness and include html as backup + formats = ["markdown", "html"] + + # Always use individual scraping for simplicity and reliability + # Batch scraping adds complexity without much benefit for small numbers of URLs + results: List[Dict[str, Any]] = [] + + from tools.interrupt import is_interrupted as _is_interrupted + for url in safe_urls: + if _is_interrupted(): + results.append({"url": url, "error": "Interrupted", "title": ""}) + continue + + # Website policy check — block before fetching + blocked = check_website_access(url) + if blocked: + logger.info("Blocked web_extract for %s by rule %s", blocked["host"], blocked["rule"]) + results.append({ + "url": url, "title": "", "content": "", + "error": blocked["message"], + "blocked_by_policy": {"host": blocked["host"], "rule": blocked["rule"], "source": blocked["source"]}, + }) + continue + + try: + logger.info("Scraping: %s", url) + # Run synchronous Firecrawl scrape in a thread with a + # 60s timeout so a hung fetch doesn't block the session. + try: + scrape_result = await asyncio.wait_for( + asyncio.to_thread( + _get_firecrawl_client().scrape, + url=url, + formats=formats, + ), + timeout=60, + ) + except asyncio.TimeoutError: + logger.warning("Firecrawl scrape timed out for %s", url) + results.append({ + "url": url, "title": "", "content": "", + "error": "Scrape timed out after 60s — page may be too large or unresponsive. Try browser_navigate instead.", + }) + continue + + scrape_payload = _extract_scrape_payload(scrape_result) + metadata = scrape_payload.get("metadata", {}) + title = "" + content_markdown = scrape_payload.get("markdown") + content_html = scrape_payload.get("html") + + # Ensure metadata is a dict (not an object) + if not isinstance(metadata, dict): + if hasattr(metadata, 'model_dump'): + metadata = metadata.model_dump() + elif hasattr(metadata, '__dict__'): + metadata = metadata.__dict__ + else: + metadata = {} + + # Get title from metadata + title = metadata.get("title", "") + + # Re-check final URL after redirect + final_url = metadata.get("sourceURL", url) + final_blocked = check_website_access(final_url) + if final_blocked: + logger.info("Blocked redirected web_extract for %s by rule %s", final_blocked["host"], final_blocked["rule"]) + results.append({ + "url": final_url, "title": title, "content": "", "raw_content": "", + "error": final_blocked["message"], + "blocked_by_policy": {"host": final_blocked["host"], "rule": final_blocked["rule"], "source": final_blocked["source"]}, + }) + continue + + # Choose content based on requested format + chosen_content = content_markdown if (format == "markdown" or (format is None and content_markdown)) else content_html or content_markdown or "" + + results.append({ + "url": final_url, + "title": title, + "content": chosen_content, + "raw_content": chosen_content, + "metadata": metadata # Now guaranteed to be a dict + }) + + except Exception as scrape_err: + logger.debug("Scrape failed for %s: %s", url, scrape_err) + results.append({ + "url": url, + "title": "", + "content": "", + "raw_content": "", + "error": str(scrape_err) + }) + + # Merge any SSRF-blocked results back in + if ssrf_blocked: + results = ssrf_blocked + results + + response = {"results": results} + + pages_extracted = len(response.get('results', [])) + logger.info("Extracted content from %d pages", pages_extracted) + + debug_call_data["pages_extracted"] = pages_extracted + debug_call_data["original_response_size"] = len(json.dumps(response)) + effective_model = model or _get_default_summarizer_model() + auxiliary_available = check_auxiliary_model() + + # Process each result with LLM if enabled + if use_llm_processing and auxiliary_available: + logger.info("Processing extracted content with LLM (parallel)...") + debug_call_data["processing_applied"].append("llm_processing") + + # Prepare tasks for parallel processing + async def process_single_result(result): + """Process a single result with LLM and return updated result with metrics.""" + url = result.get('url', 'Unknown URL') + title = result.get('title', '') + raw_content = result.get('raw_content', '') or result.get('content', '') + + if not raw_content: + return result, None, "no_content" + + original_size = len(raw_content) + + # Process content with LLM + processed = await process_content_with_llm( + raw_content, url, title, effective_model, min_length + ) + + if processed: + processed_size = len(processed) + compression_ratio = processed_size / original_size if original_size > 0 else 1.0 + + # Update result with processed content + result['content'] = processed + result['raw_content'] = raw_content + + metrics = { + "url": url, + "original_size": original_size, + "processed_size": processed_size, + "compression_ratio": compression_ratio, + "model_used": effective_model + } + return result, metrics, "processed" + else: + metrics = { + "url": url, + "original_size": original_size, + "processed_size": original_size, + "compression_ratio": 1.0, + "model_used": None, + "reason": "content_too_short" + } + return result, metrics, "too_short" + + # Run all LLM processing in parallel + results_list = response.get('results', []) + tasks = [process_single_result(result) for result in results_list] + processed_results = await asyncio.gather(*tasks) + + # Collect metrics and print results + for result, metrics, status in processed_results: + url = result.get('url', 'Unknown URL') + if status == "processed": + debug_call_data["compression_metrics"].append(metrics) + debug_call_data["pages_processed_with_llm"] += 1 + logger.info("%s (processed)", url) + elif status == "too_short": + debug_call_data["compression_metrics"].append(metrics) + logger.info("%s (no processing - content too short)", url) + else: + logger.warning("%s (no content to process)", url) + else: + if use_llm_processing and not auxiliary_available: + logger.warning("LLM processing requested but no auxiliary model available, returning raw content") + debug_call_data["processing_applied"].append("llm_processing_unavailable") + # Print summary of extracted pages for debugging (original behavior) + for result in response.get('results', []): + url = result.get('url', 'Unknown URL') + content_length = len(result.get('raw_content', '')) + logger.info("%s (%d characters)", url, content_length) + + # Trim output to minimal fields per entry: title, content, error + trimmed_results = [ + { + "url": r.get("url", ""), + "title": r.get("title", ""), + "content": r.get("content", ""), + "error": r.get("error"), + **({ "blocked_by_policy": r["blocked_by_policy"]} if "blocked_by_policy" in r else {}), + } + for r in response.get("results", []) + ] + trimmed_response = {"results": trimmed_results} + + if trimmed_response.get("results") == []: + result_json = tool_error("Content was inaccessible or not found") + + cleaned_result = clean_base64_images(result_json) + + else: + result_json = json.dumps(trimmed_response, indent=2, ensure_ascii=False) + + cleaned_result = clean_base64_images(result_json) + + debug_call_data["final_response_size"] = len(cleaned_result) + debug_call_data["processing_applied"].append("base64_image_removal") + + # Log debug information + _debug.log_call("web_extract_tool", debug_call_data) + _debug.save() + + return cleaned_result + + except Exception as e: + error_msg = f"Error extracting content: {str(e)}" + logger.debug("%s", error_msg) + + debug_call_data["error"] = error_msg + _debug.log_call("web_extract_tool", debug_call_data) + _debug.save() + + return tool_error(error_msg) + + +async def web_crawl_tool( + url: str, + instructions: str = None, + depth: str = "basic", + use_llm_processing: bool = True, + model: Optional[str] = None, + min_length: int = DEFAULT_MIN_LENGTH_FOR_SUMMARIZATION +) -> str: + """ + Crawl a website with specific instructions using available crawling API backend. + + This function provides a generic interface for web crawling that can work + with multiple backends. Currently uses Firecrawl. + + Args: + url (str): The base URL to crawl (can include or exclude https://) + instructions (str): Instructions for what to crawl/extract using LLM intelligence (optional) + depth (str): Depth of extraction ("basic" or "advanced", default: "basic") + use_llm_processing (bool): Whether to process content with LLM for summarization (default: True) + model (Optional[str]): The model to use for LLM processing (defaults to current auxiliary backend model) + min_length (int): Minimum content length to trigger LLM processing (default: 5000) + + Returns: + str: JSON string containing crawled content. If LLM processing is enabled and successful, + the 'content' field will contain the processed markdown summary instead of raw content. + Each page is processed individually. + + Raises: + Exception: If crawling fails or API key is not set + """ + debug_call_data = { + "parameters": { + "url": url, + "instructions": instructions, + "depth": depth, + "use_llm_processing": use_llm_processing, + "model": model, + "min_length": min_length + }, + "error": None, + "pages_crawled": 0, + "pages_processed_with_llm": 0, + "original_response_size": 0, + "final_response_size": 0, + "compression_metrics": [], + "processing_applied": [] + } + + try: + effective_model = model or _get_default_summarizer_model() + auxiliary_available = check_auxiliary_model() + backend = _get_backend() + + # Tavily supports crawl via its /crawl endpoint + if backend == "tavily": + # Ensure URL has protocol + if not url.startswith(('http://', 'https://')): + url = f'https://{url}' + + # SSRF protection — block private/internal addresses + if not is_safe_url(url): + return json.dumps({"results": [{"url": url, "title": "", "content": "", + "error": "Blocked: URL targets a private or internal network address"}]}, ensure_ascii=False) + + # Website policy check + blocked = check_website_access(url) + if blocked: + logger.info("Blocked web_crawl for %s by rule %s", blocked["host"], blocked["rule"]) + return json.dumps({"results": [{"url": url, "title": "", "content": "", "error": blocked["message"], + "blocked_by_policy": {"host": blocked["host"], "rule": blocked["rule"], "source": blocked["source"]}}]}, ensure_ascii=False) + + from tools.interrupt import is_interrupted as _is_int + if _is_int(): + return tool_error("Interrupted", success=False) + + logger.info("Tavily crawl: %s", url) + payload: Dict[str, Any] = { + "url": url, + "limit": 20, + "extract_depth": depth, + } + if instructions: + payload["instructions"] = instructions + raw = _tavily_request("crawl", payload) + results = _normalize_tavily_documents(raw, fallback_url=url) + + response = {"results": results} + # Fall through to the shared LLM processing and trimming below + # (skip the Firecrawl-specific crawl logic) + pages_crawled = len(response.get('results', [])) + logger.info("Crawled %d pages", pages_crawled) + debug_call_data["pages_crawled"] = pages_crawled + debug_call_data["original_response_size"] = len(json.dumps(response)) + + # Process each result with LLM if enabled + if use_llm_processing and auxiliary_available: + logger.info("Processing crawled content with LLM (parallel)...") + debug_call_data["processing_applied"].append("llm_processing") + + async def _process_tavily_crawl(result): + page_url = result.get('url', 'Unknown URL') + title = result.get('title', '') + content = result.get('content', '') + if not content: + return result, None, "no_content" + original_size = len(content) + processed = await process_content_with_llm(content, page_url, title, effective_model, min_length) + if processed: + result['raw_content'] = content + result['content'] = processed + metrics = {"url": page_url, "original_size": original_size, "processed_size": len(processed), + "compression_ratio": len(processed) / original_size if original_size else 1.0, "model_used": effective_model} + return result, metrics, "processed" + metrics = {"url": page_url, "original_size": original_size, "processed_size": original_size, + "compression_ratio": 1.0, "model_used": None, "reason": "content_too_short"} + return result, metrics, "too_short" + + tasks = [_process_tavily_crawl(r) for r in response.get('results', [])] + processed_results = await asyncio.gather(*tasks) + for result, metrics, status in processed_results: + if status == "processed": + debug_call_data["compression_metrics"].append(metrics) + debug_call_data["pages_processed_with_llm"] += 1 + + if use_llm_processing and not auxiliary_available: + logger.warning("LLM processing requested but no auxiliary model available, returning raw content") + debug_call_data["processing_applied"].append("llm_processing_unavailable") + + trimmed_results = [{"url": r.get("url", ""), "title": r.get("title", ""), "content": r.get("content", ""), "error": r.get("error"), + **({ "blocked_by_policy": r["blocked_by_policy"]} if "blocked_by_policy" in r else {})} for r in response.get("results", [])] + result_json = json.dumps({"results": trimmed_results}, indent=2, ensure_ascii=False) + cleaned_result = clean_base64_images(result_json) + debug_call_data["final_response_size"] = len(cleaned_result) + _debug.log_call("web_crawl_tool", debug_call_data) + _debug.save() + return cleaned_result + + # web_crawl requires Firecrawl or the Firecrawl tool-gateway — Parallel has no crawl API + if not check_firecrawl_api_key(): + return json.dumps({ + "error": "web_crawl requires Firecrawl. Set FIRECRAWL_API_KEY, FIRECRAWL_API_URL" + f"{_firecrawl_backend_help_suffix()}, or use web_search + web_extract instead.", + "success": False, + }, ensure_ascii=False) + + # Ensure URL has protocol + if not url.startswith(('http://', 'https://')): + url = f'https://{url}' + logger.info("Added https:// prefix to URL: %s", url) + + instructions_text = f" with instructions: '{instructions}'" if instructions else "" + logger.info("Crawling %s%s", url, instructions_text) + + # SSRF protection — block private/internal addresses + if not is_safe_url(url): + return json.dumps({"results": [{"url": url, "title": "", "content": "", + "error": "Blocked: URL targets a private or internal network address"}]}, ensure_ascii=False) + + # Website policy check — block before crawling + blocked = check_website_access(url) + if blocked: + logger.info("Blocked web_crawl for %s by rule %s", blocked["host"], blocked["rule"]) + return json.dumps({"results": [{"url": url, "title": "", "content": "", "error": blocked["message"], + "blocked_by_policy": {"host": blocked["host"], "rule": blocked["rule"], "source": blocked["source"]}}]}, ensure_ascii=False) + + # Use Firecrawl's v2 crawl functionality + # Docs: https://docs.firecrawl.dev/features/crawl + # The crawl() method automatically waits for completion and returns all data + + # Build crawl parameters - keep it simple + crawl_params = { + "limit": 20, # Limit number of pages to crawl + "scrape_options": { + "formats": ["markdown"] # Just markdown for simplicity + } + } + + # Note: The 'prompt' parameter is not documented for crawl + # Instructions are typically used with the Extract endpoint, not Crawl + if instructions: + logger.info("Instructions parameter ignored (not supported in crawl API)") + + from tools.interrupt import is_interrupted as _is_int + if _is_int(): + return tool_error("Interrupted", success=False) + + try: + crawl_result = _get_firecrawl_client().crawl( + url=url, + **crawl_params + ) + except Exception as e: + logger.debug("Crawl API call failed: %s", e) + raise + + pages: List[Dict[str, Any]] = [] + + # Process crawl results - the crawl method returns a CrawlJob object with data attribute + data_list = [] + + # The crawl_result is a CrawlJob object with a 'data' attribute containing list of Document objects + if hasattr(crawl_result, 'data'): + data_list = crawl_result.data if crawl_result.data else [] + logger.info("Status: %s", getattr(crawl_result, 'status', 'unknown')) + logger.info("Retrieved %d pages", len(data_list)) + + # Debug: Check other attributes if no data + if not data_list: + logger.debug("CrawlJob attributes: %s", [attr for attr in dir(crawl_result) if not attr.startswith('_')]) + logger.debug("Status: %s", getattr(crawl_result, 'status', 'N/A')) + logger.debug("Total: %s", getattr(crawl_result, 'total', 'N/A')) + logger.debug("Completed: %s", getattr(crawl_result, 'completed', 'N/A')) + + elif isinstance(crawl_result, dict) and 'data' in crawl_result: + data_list = crawl_result.get("data", []) + else: + logger.warning("Unexpected crawl result type") + logger.debug("Result type: %s", type(crawl_result)) + if hasattr(crawl_result, '__dict__'): + logger.debug("Result attributes: %s", list(crawl_result.__dict__.keys())) + + for item in data_list: + # Process each crawled page - properly handle object serialization + page_url = "Unknown URL" + title = "" + content_markdown = None + content_html = None + metadata = {} + + # Extract data from the item + if hasattr(item, 'model_dump'): + # Pydantic model - use model_dump to get dict + item_dict = item.model_dump() + content_markdown = item_dict.get('markdown') + content_html = item_dict.get('html') + metadata = item_dict.get('metadata', {}) + elif hasattr(item, '__dict__'): + # Regular object with attributes + content_markdown = getattr(item, 'markdown', None) + content_html = getattr(item, 'html', None) + + # Handle metadata - convert to dict if it's an object + metadata_obj = getattr(item, 'metadata', {}) + if hasattr(metadata_obj, 'model_dump'): + metadata = metadata_obj.model_dump() + elif hasattr(metadata_obj, '__dict__'): + metadata = metadata_obj.__dict__ + elif isinstance(metadata_obj, dict): + metadata = metadata_obj + else: + metadata = {} + elif isinstance(item, dict): + # Already a dictionary + content_markdown = item.get('markdown') + content_html = item.get('html') + metadata = item.get('metadata', {}) + + # Ensure metadata is a dict (not an object) + if not isinstance(metadata, dict): + if hasattr(metadata, 'model_dump'): + metadata = metadata.model_dump() + elif hasattr(metadata, '__dict__'): + metadata = metadata.__dict__ + else: + metadata = {} + + # Extract URL and title from metadata + page_url = metadata.get("sourceURL", metadata.get("url", "Unknown URL")) + title = metadata.get("title", "") + + # Re-check crawled page URL against policy + page_blocked = check_website_access(page_url) + if page_blocked: + logger.info("Blocked crawled page %s by rule %s", page_blocked["host"], page_blocked["rule"]) + pages.append({ + "url": page_url, "title": title, "content": "", "raw_content": "", + "error": page_blocked["message"], + "blocked_by_policy": {"host": page_blocked["host"], "rule": page_blocked["rule"], "source": page_blocked["source"]}, + }) + continue + + # Choose content (prefer markdown) + content = content_markdown or content_html or "" + + pages.append({ + "url": page_url, + "title": title, + "content": content, + "raw_content": content, + "metadata": metadata # Now guaranteed to be a dict + }) + + response = {"results": pages} + + pages_crawled = len(response.get('results', [])) + logger.info("Crawled %d pages", pages_crawled) + + debug_call_data["pages_crawled"] = pages_crawled + debug_call_data["original_response_size"] = len(json.dumps(response)) + + # Process each result with LLM if enabled + if use_llm_processing and auxiliary_available: + logger.info("Processing crawled content with LLM (parallel)...") + debug_call_data["processing_applied"].append("llm_processing") + + # Prepare tasks for parallel processing + async def process_single_crawl_result(result): + """Process a single crawl result with LLM and return updated result with metrics.""" + page_url = result.get('url', 'Unknown URL') + title = result.get('title', '') + content = result.get('content', '') + + if not content: + return result, None, "no_content" + + original_size = len(content) + + # Process content with LLM + processed = await process_content_with_llm( + content, page_url, title, effective_model, min_length + ) + + if processed: + processed_size = len(processed) + compression_ratio = processed_size / original_size if original_size > 0 else 1.0 + + # Update result with processed content + result['raw_content'] = content + result['content'] = processed + + metrics = { + "url": page_url, + "original_size": original_size, + "processed_size": processed_size, + "compression_ratio": compression_ratio, + "model_used": effective_model + } + return result, metrics, "processed" + else: + metrics = { + "url": page_url, + "original_size": original_size, + "processed_size": original_size, + "compression_ratio": 1.0, + "model_used": None, + "reason": "content_too_short" + } + return result, metrics, "too_short" + + # Run all LLM processing in parallel + results_list = response.get('results', []) + tasks = [process_single_crawl_result(result) for result in results_list] + processed_results = await asyncio.gather(*tasks) + + # Collect metrics and print results + for result, metrics, status in processed_results: + page_url = result.get('url', 'Unknown URL') + if status == "processed": + debug_call_data["compression_metrics"].append(metrics) + debug_call_data["pages_processed_with_llm"] += 1 + logger.info("%s (processed)", page_url) + elif status == "too_short": + debug_call_data["compression_metrics"].append(metrics) + logger.info("%s (no processing - content too short)", page_url) + else: + logger.warning("%s (no content to process)", page_url) + else: + if use_llm_processing and not auxiliary_available: + logger.warning("LLM processing requested but no auxiliary model available, returning raw content") + debug_call_data["processing_applied"].append("llm_processing_unavailable") + # Print summary of crawled pages for debugging (original behavior) + for result in response.get('results', []): + page_url = result.get('url', 'Unknown URL') + content_length = len(result.get('content', '')) + logger.info("%s (%d characters)", page_url, content_length) + + # Trim output to minimal fields per entry: title, content, error + trimmed_results = [ + { + "url": r.get("url", ""), + "title": r.get("title", ""), + "content": r.get("content", ""), + "error": r.get("error"), + **({ "blocked_by_policy": r["blocked_by_policy"]} if "blocked_by_policy" in r else {}), + } + for r in response.get("results", []) + ] + trimmed_response = {"results": trimmed_results} + + result_json = json.dumps(trimmed_response, indent=2, ensure_ascii=False) + # Clean base64 images from crawled content + cleaned_result = clean_base64_images(result_json) + + debug_call_data["final_response_size"] = len(cleaned_result) + debug_call_data["processing_applied"].append("base64_image_removal") + + # Log debug information + _debug.log_call("web_crawl_tool", debug_call_data) + _debug.save() + + return cleaned_result + + except Exception as e: + error_msg = f"Error crawling website: {str(e)}" + logger.debug("%s", error_msg) + + debug_call_data["error"] = error_msg + _debug.log_call("web_crawl_tool", debug_call_data) + _debug.save() + + return tool_error(error_msg) + + +# Convenience function to check Firecrawl credentials +def check_firecrawl_api_key() -> bool: + """ + Check whether the Firecrawl backend is available. + + Availability is true when either: + 1) direct Firecrawl config (`FIRECRAWL_API_KEY` or `FIRECRAWL_API_URL`), or + 2) Firecrawl gateway origin + Nous Subscriber access token + (fallback when direct Firecrawl is not configured). + + Returns: + bool: True if direct Firecrawl or the tool-gateway can be used. + """ + return _has_direct_firecrawl_config() or _is_tool_gateway_ready() + + +def check_web_api_key() -> bool: + """Check whether the configured web backend is available.""" + configured = _load_web_config().get("backend", "").lower().strip() + if configured in ("exa", "parallel", "firecrawl", "tavily"): + return _is_backend_available(configured) + return any(_is_backend_available(backend) for backend in ("exa", "parallel", "firecrawl", "tavily")) + + +def check_auxiliary_model() -> bool: + """Check if an auxiliary text model is available for LLM content processing.""" + client, _, _ = _resolve_web_extract_auxiliary() + return client is not None + + + + +if __name__ == "__main__": + """ + Simple test/demo when run directly + """ + print("🌐 Standalone Web Tools Module") + print("=" * 40) + + # Check if API keys are available + web_available = check_web_api_key() + tool_gateway_available = _is_tool_gateway_ready() + firecrawl_key_available = bool(os.getenv("FIRECRAWL_API_KEY", "").strip()) + firecrawl_url_available = bool(os.getenv("FIRECRAWL_API_URL", "").strip()) + nous_available = check_auxiliary_model() + default_summarizer_model = _get_default_summarizer_model() + + if web_available: + backend = _get_backend() + print(f"✅ Web backend: {backend}") + if backend == "exa": + print(" Using Exa API (https://exa.ai)") + elif backend == "parallel": + print(" Using Parallel API (https://parallel.ai)") + elif backend == "tavily": + print(" Using Tavily API (https://tavily.com)") + else: + if firecrawl_url_available: + print(f" Using self-hosted Firecrawl: {os.getenv('FIRECRAWL_API_URL').strip().rstrip('/')}") + elif firecrawl_key_available: + print(" Using direct Firecrawl cloud API") + elif tool_gateway_available: + print(f" Using Firecrawl tool-gateway: {_get_firecrawl_gateway_url()}") + else: + print(" Firecrawl backend selected but not configured") + else: + print("❌ No web search backend configured") + print( + "Set EXA_API_KEY, PARALLEL_API_KEY, TAVILY_API_KEY, FIRECRAWL_API_KEY, FIRECRAWL_API_URL" + f"{_firecrawl_backend_help_suffix()}" + ) + + if not nous_available: + print("❌ No auxiliary model available for LLM content processing") + print("Set OPENROUTER_API_KEY, configure Nous Portal, or set OPENAI_BASE_URL + OPENAI_API_KEY") + print("⚠️ Without an auxiliary model, LLM content processing will be disabled") + else: + print(f"✅ Auxiliary model available: {default_summarizer_model}") + + if not web_available: + exit(1) + + print("🛠️ Web tools ready for use!") + + if nous_available: + print(f"🧠 LLM content processing available with {default_summarizer_model}") + print(f" Default min length for processing: {DEFAULT_MIN_LENGTH_FOR_SUMMARIZATION} chars") + + # Show debug mode status + if _debug.active: + print(f"🐛 Debug mode ENABLED - Session ID: {_debug.session_id}") + print(f" Debug logs will be saved to: {_debug.log_dir}/web_tools_debug_{_debug.session_id}.json") + else: + print("🐛 Debug mode disabled (set WEB_TOOLS_DEBUG=true to enable)") + + print("\nBasic usage:") + print(" from web_tools import web_search_tool, web_extract_tool, web_crawl_tool") + print(" import asyncio") + print("") + print(" # Search (synchronous)") + print(" results = web_search_tool('Python tutorials')") + print("") + print(" # Extract and crawl (asynchronous)") + print(" async def main():") + print(" content = await web_extract_tool(['https://example.com'])") + print(" crawl_data = await web_crawl_tool('example.com', 'Find docs')") + print(" asyncio.run(main())") + + if nous_available: + print("\nLLM-enhanced usage:") + print(" # Content automatically processed for pages >5000 chars (default)") + print(" content = await web_extract_tool(['https://python.org/about/'])") + print("") + print(" # Customize processing parameters") + print(" crawl_data = await web_crawl_tool(") + print(" 'docs.python.org',") + print(" 'Find key concepts',") + print(" model='google/gemini-3-flash-preview',") + print(" min_length=3000") + print(" )") + print("") + print(" # Disable LLM processing") + print(" raw_content = await web_extract_tool(['https://example.com'], use_llm_processing=False)") + + print("\nDebug mode:") + print(" # Enable debug logging") + print(" export WEB_TOOLS_DEBUG=true") + print(" # Debug logs capture:") + print(" # - All tool calls with parameters") + print(" # - Original API responses") + print(" # - LLM compression metrics") + print(" # - Final processed results") + print(" # Logs saved to: ./logs/web_tools_debug_UUID.json") + + print("\n📝 Run 'python test_web_tools_llm.py' to test LLM processing capabilities") + + +# --------------------------------------------------------------------------- +# Registry +# --------------------------------------------------------------------------- +from tools.registry import registry, tool_error + +WEB_SEARCH_SCHEMA = { + "name": "web_search", + "description": "Search the web for information on any topic. Returns up to 5 relevant results with titles, URLs, and descriptions.", + "parameters": { + "type": "object", + "properties": { + "query": { + "type": "string", + "description": "The search query to look up on the web" + } + }, + "required": ["query"] + } +} + +WEB_EXTRACT_SCHEMA = { + "name": "web_extract", + "description": "Extract content from web page URLs. Returns page content in markdown format. Also works with PDF URLs (arxiv papers, documents, etc.) — pass the PDF link directly and it converts to markdown text. Pages under 5000 chars return full markdown; larger pages are LLM-summarized and capped at ~5000 chars per page. Pages over 2M chars are refused. If a URL fails or times out, use the browser tool to access it instead.", + "parameters": { + "type": "object", + "properties": { + "urls": { + "type": "array", + "items": {"type": "string"}, + "description": "List of URLs to extract content from (max 5 URLs per call)", + "maxItems": 5 + } + }, + "required": ["urls"] + } +} + +registry.register( + name="web_search", + toolset="web", + schema=WEB_SEARCH_SCHEMA, + handler=lambda args, **kw: web_search_tool(args.get("query", ""), limit=5), + check_fn=check_web_api_key, + requires_env=_web_requires_env(), + emoji="🔍", + max_result_size_chars=100_000, +) +registry.register( + name="web_extract", + toolset="web", + schema=WEB_EXTRACT_SCHEMA, + handler=lambda args, **kw: web_extract_tool( + args.get("urls", [])[:5] if isinstance(args.get("urls"), list) else [], "markdown"), + check_fn=check_web_api_key, + requires_env=_web_requires_env(), + is_async=True, + emoji="📄", + max_result_size_chars=100_000, +) diff --git a/mindcli/_vendor/tools/website_policy.py b/mindcli/_vendor/tools/website_policy.py new file mode 100644 index 0000000..63fb757 --- /dev/null +++ b/mindcli/_vendor/tools/website_policy.py @@ -0,0 +1,282 @@ +"""Website access policy helpers for URL-capable tools. + +This module loads a user-managed website blocklist from ~/.hermes/config.yaml +and optional shared list files. It is intentionally lightweight so web/browser +tools can enforce URL policy without pulling in the heavier CLI config stack. + +Policy is cached in memory with a short TTL so config changes take effect +quickly without re-reading the file on every URL check. +""" + +from __future__ import annotations + +import fnmatch +import logging +import threading +import time +from pathlib import Path +from typing import Any, Dict, List, Optional, Tuple +from urllib.parse import urlparse + +from hermes_constants import get_hermes_home + +logger = logging.getLogger(__name__) + +_DEFAULT_WEBSITE_BLOCKLIST = { + "enabled": False, + "domains": [], + "shared_files": [], +} + +# Cache: parsed policy + timestamp. Avoids re-reading config.yaml on every +# URL check (a web_crawl with 50 pages would otherwise mean 51 YAML parses). +_CACHE_TTL_SECONDS = 30.0 +_cache_lock = threading.Lock() +_cached_policy: Optional[Dict[str, Any]] = None +_cached_policy_path: Optional[str] = None +_cached_policy_time: float = 0.0 + + +def _get_default_config_path() -> Path: + return get_hermes_home() / "config.yaml" + + +class WebsitePolicyError(Exception): + """Raised when a website policy file is malformed.""" + + +def _normalize_host(host: str) -> str: + return (host or "").strip().lower().rstrip(".") + + +def _normalize_rule(rule: Any) -> Optional[str]: + if not isinstance(rule, str): + return None + value = rule.strip().lower() + if not value or value.startswith("#"): + return None + if "://" in value: + parsed = urlparse(value) + value = parsed.netloc or parsed.path + value = value.split("/", 1)[0].strip().rstrip(".") + if value.startswith("www."): + value = value[4:] + return value or None + + +def _iter_blocklist_file_rules(path: Path) -> List[str]: + """Load rules from a shared blocklist file. + + Missing or unreadable files log a warning and return an empty list + rather than raising — a bad file path should not disable all web tools. + """ + try: + raw = path.read_text(encoding="utf-8") + except FileNotFoundError: + logger.warning("Shared blocklist file not found (skipping): %s", path) + return [] + except (OSError, UnicodeDecodeError) as exc: + logger.warning("Failed to read shared blocklist file %s (skipping): %s", path, exc) + return [] + + rules: List[str] = [] + for line in raw.splitlines(): + stripped = line.strip() + if not stripped or stripped.startswith("#"): + continue + normalized = _normalize_rule(stripped) + if normalized: + rules.append(normalized) + return rules + + +def _load_policy_config(config_path: Optional[Path] = None) -> Dict[str, Any]: + config_path = config_path or _get_default_config_path() + if not config_path.exists(): + return dict(_DEFAULT_WEBSITE_BLOCKLIST) + + try: + import yaml + except ImportError: + logger.debug("PyYAML not installed — website blocklist disabled") + return dict(_DEFAULT_WEBSITE_BLOCKLIST) + + try: + with open(config_path, encoding="utf-8") as f: + config = yaml.safe_load(f) or {} + except yaml.YAMLError as exc: + raise WebsitePolicyError(f"Invalid config YAML at {config_path}: {exc}") from exc + except OSError as exc: + raise WebsitePolicyError(f"Failed to read config file {config_path}: {exc}") from exc + if not isinstance(config, dict): + raise WebsitePolicyError("config root must be a mapping") + + security = config.get("security", {}) + if security is None: + security = {} + if not isinstance(security, dict): + raise WebsitePolicyError("security must be a mapping") + + website_blocklist = security.get("website_blocklist", {}) + if website_blocklist is None: + website_blocklist = {} + if not isinstance(website_blocklist, dict): + raise WebsitePolicyError("security.website_blocklist must be a mapping") + + policy = dict(_DEFAULT_WEBSITE_BLOCKLIST) + policy.update(website_blocklist) + return policy + + +def load_website_blocklist(config_path: Optional[Path] = None) -> Dict[str, Any]: + """Load and return the parsed website blocklist policy. + + Results are cached for ``_CACHE_TTL_SECONDS`` to avoid re-reading + config.yaml on every URL check. Pass an explicit ``config_path`` + to bypass the cache (used by tests). + """ + global _cached_policy, _cached_policy_path, _cached_policy_time + + resolved_path = str(config_path) if config_path else "__default__" + now = time.monotonic() + + # Return cached policy if still fresh and same path + if config_path is None: + with _cache_lock: + if ( + _cached_policy is not None + and _cached_policy_path == resolved_path + and (now - _cached_policy_time) < _CACHE_TTL_SECONDS + ): + return _cached_policy + + config_path = config_path or _get_default_config_path() + policy = _load_policy_config(config_path) + + raw_domains = policy.get("domains", []) or [] + if not isinstance(raw_domains, list): + raise WebsitePolicyError("security.website_blocklist.domains must be a list") + + raw_shared_files = policy.get("shared_files", []) or [] + if not isinstance(raw_shared_files, list): + raise WebsitePolicyError("security.website_blocklist.shared_files must be a list") + + enabled = policy.get("enabled", True) + if not isinstance(enabled, bool): + raise WebsitePolicyError("security.website_blocklist.enabled must be a boolean") + + rules: List[Dict[str, str]] = [] + seen: set[Tuple[str, str]] = set() + + for raw_rule in raw_domains: + normalized = _normalize_rule(raw_rule) + if normalized and ("config", normalized) not in seen: + rules.append({"pattern": normalized, "source": "config"}) + seen.add(("config", normalized)) + + for shared_file in raw_shared_files: + if not isinstance(shared_file, str) or not shared_file.strip(): + continue + path = Path(shared_file).expanduser() + if not path.is_absolute(): + path = (get_hermes_home() / path).resolve() + for normalized in _iter_blocklist_file_rules(path): + key = (str(path), normalized) + if key in seen: + continue + rules.append({"pattern": normalized, "source": str(path)}) + seen.add(key) + + result = {"enabled": enabled, "rules": rules} + + # Cache the result (only for the default path — explicit paths are tests) + if config_path == _get_default_config_path(): + with _cache_lock: + _cached_policy = result + _cached_policy_path = "__default__" + _cached_policy_time = now + + return result + + +def invalidate_cache() -> None: + """Force the next ``check_website_access`` call to re-read config.""" + global _cached_policy + with _cache_lock: + _cached_policy = None + + +def _match_host_against_rule(host: str, pattern: str) -> bool: + if not host or not pattern: + return False + if pattern.startswith("*."): + return fnmatch.fnmatch(host, pattern) + return host == pattern or host.endswith(f".{pattern}") + + +def _extract_host_from_urlish(url: str) -> str: + parsed = urlparse(url) + host = _normalize_host(parsed.hostname or parsed.netloc) + if host: + return host + + if "://" not in url: + schemeless = urlparse(f"//{url}") + host = _normalize_host(schemeless.hostname or schemeless.netloc) + if host: + return host + + return "" + + +def check_website_access(url: str, config_path: Optional[Path] = None) -> Optional[Dict[str, str]]: + """Check whether a URL is allowed by the website blocklist policy. + + Returns ``None`` if access is allowed, or a dict with block metadata + (``host``, ``rule``, ``source``, ``message``) if blocked. + + Never raises on policy errors — logs a warning and returns ``None`` + (fail-open) so a config typo doesn't break all web tools. Pass + ``config_path`` explicitly (tests) to get strict error propagation. + """ + # Fast path: if no explicit config_path and the cached policy is disabled + # or empty, skip all work (no YAML read, no host extraction). + if config_path is None: + with _cache_lock: + if _cached_policy is not None and not _cached_policy.get("enabled"): + return None + + host = _extract_host_from_urlish(url) + if not host: + return None + + try: + policy = load_website_blocklist(config_path) + except WebsitePolicyError as exc: + if config_path is not None: + raise # Tests pass explicit paths — let errors propagate + logger.warning("Website policy config error (failing open): %s", exc) + return None + except Exception as exc: + logger.warning("Unexpected error loading website policy (failing open): %s", exc) + return None + + if not policy.get("enabled"): + return None + + for rule in policy.get("rules", []): + pattern = rule.get("pattern", "") + if _match_host_against_rule(host, pattern): + logger.info("Blocked URL %s — matched rule '%s' from %s", + url, pattern, rule.get("source", "config")) + return { + "url": url, + "host": host, + "rule": pattern, + "source": rule.get("source", "config"), + "message": ( + f"Blocked by website policy: '{host}' matched rule '{pattern}'" + f" from {rule.get('source', 'config')}" + ), + } + return None diff --git a/mindcli/capability.py b/mindcli/capability.py new file mode 100644 index 0000000..cd6af34 --- /dev/null +++ b/mindcli/capability.py @@ -0,0 +1,79 @@ +""" +Mind CLI — 能力扫描器。 + +扫描本地可用的内置工具和 MCP Server，生成 capability report +供 Tunnel 握手时上报给 Cloud。 +""" + +import os +import platform +from typing import Any + +import mindcli + + +# ── 内置工具注册表 ──────────────────────────────────── +# 只暴露 Cloud 端有意义的本地工具（文件操作、终端、搜索等） +# 浏览器工具、TTS 等纯交互工具不上报 +_BUILTIN_TOOLS: list[dict[str, str]] = [ + {"name": "terminal", "type": "builtin", "desc": "执行终端命令"}, + {"name": "file_read", "type": "builtin", "desc": "读取本地文件"}, + {"name": "file_write", "type": "builtin", "desc": "写入本地文件"}, + {"name": "file_ops", "type": "builtin", "desc": "文件操作（复制/移动/删除）"}, + {"name": "grep", "type": "builtin", "desc": "文本搜索"}, + {"name": "code_execution", "type": "builtin", "desc": "执行代码片段"}, +] + + +def scan_capabilities() -> dict[str, Any]: + """ + 扫描本地可用工具，返回 capability report。 + + 返回格式： + { + "version": "0.1.0", + "vendor": "16f9d020", + "platform": "Darwin", + "arch": "arm64", + "python": "3.12.11", + "tools": [ + {"name": "terminal", "type": "builtin", "desc": "..."}, + ... + ], + "mcp_servers": [] # Phase 2+ 从 config.yaml 读取 + } + """ + import sys + + return { + "version": mindcli.__version__, + "vendor": _get_vendor_commit(), + "platform": platform.system(), + "arch": platform.machine(), + "python": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}", + "tools": list(_BUILTIN_TOOLS), + "mcp_servers": _scan_mcp_servers(), + } + + +def get_tool_names() -> list[str]: + """返回所有内置工具名称列表。""" + return [t["name"] for t in _BUILTIN_TOOLS] + + +def _scan_mcp_servers() -> list[dict[str, str]]: + """ + 扫描用户配置的第三方 MCP Server。 + + TODO: 从 ~/.mindcli/config.yaml 的 mcp_servers 段读取。 + """ + return [] + + +def _get_vendor_commit() -> str: + commit_file = os.path.join(mindcli._VENDOR_DIR, "HERMES_COMMIT") + try: + with open(commit_file) as f: + return f.read().strip() + except FileNotFoundError: + return "unknown" diff --git a/mindcli/cli.py b/mindcli/cli.py new file mode 100644 index 0000000..e11cbc7 --- /dev/null +++ b/mindcli/cli.py @@ -0,0 +1,232 @@ +""" +Mind CLI — 命令行入口。 + +通过 Click 定义 `mind` 命令族，内部委托给 _vendor/ 中的 Hermes CLI。 +Phase 0 只实现 chat / ask / health 三个核心命令。 +""" + +import click +import json +import os +import sys + +# 确保 _vendor/ 已注入 sys.path +import mindcli # noqa: F401 — 触发 __init__.py 的 sys.path 注入 + + +@click.group(invoke_without_command=True) +@click.version_option(version=mindcli.__version__, prog_name="mind") +@click.pass_context +def main(ctx): + """MindOS NEXT CLI — Cloud Hermes 的本地执行节点。""" + if ctx.invoked_subcommand is None: + click.echo(ctx.get_help()) + + +@main.command() +@click.option("--model", "-m", default="", help="模型名称（默认使用配置文件）") +@click.option("--skills", "-s", multiple=True, help="加载指定 skill") +@click.option("--resume", "-r", default="", help="恢复指定会话 ID") +def chat(model, skills, resume): + """进入交互式 Chat（复用 Hermes CLI 的完整 TUI）。""" + from cli import main as hermes_main + + # 构建 Hermes CLI 参数 + kwargs = {} + if model: + kwargs["model"] = model + if skills: + kwargs["skills"] = ",".join(skills) + if resume: + kwargs["resume"] = resume + + hermes_main(**kwargs) + + +@main.command() +@click.argument("question") +@click.option("--model", "-m", default="", help="模型名称") +@click.option("--format", "fmt", default="text", help="输出格式: text/json/markdown") +def ask(question, model, fmt): + """单次查询（= hermes -q）。""" + from cli import main as hermes_main + + kwargs = {"query": question} + if model: + kwargs["model"] = model + + hermes_main(**kwargs) + + +@main.command() +def health(): + """显示本地 CLI 健康状态。""" + import json + + status = { + "ok": True, + "version": mindcli.__version__, + "python": sys.version.split()[0], + "vendor": _get_vendor_commit(), + "tunnel": "disconnected", # Phase 2 实现 + "tools": 0, # Phase 2 实现 + } + click.echo(json.dumps(status, indent=2, ensure_ascii=False)) + + +@main.command() +@click.option("--port", "-p", default=8660, help="Health Server 端口") +def start(port): + """启动 Health Server（前台运行，Ctrl+C 退出）。""" + from mindcli.health import start_health_server + start_health_server(port=port, foreground=True) + + +@main.command(name="install-service") +def install_service(): + """注册为 macOS launchd 服务（开机自启）。""" + from mindcli.service import install_service as _install + _install() + + +@main.command(name="uninstall-service") +def uninstall_service(): + """注销 macOS launchd 服务。""" + from mindcli.service import uninstall_service as _uninstall + _uninstall() + + +@main.command() +def capabilities(): + """显示本地可用工具和 MCP Server。""" + from mindcli.capability import scan_capabilities + cap = scan_capabilities() + click.echo(json.dumps(cap, indent=2, ensure_ascii=False)) + + +@main.group() +def tunnel(): + """管理 Cloud ↔ Local 隧道。""" + pass + + +@tunnel.command() +def status(): + """查看 Tunnel 连接状态。""" + import urllib.request + try: + req = urllib.request.Request("http://127.0.0.1:8660/tunnel/status") + with urllib.request.urlopen(req, timeout=2) as resp: + data = json.loads(resp.read()) + click.echo(json.dumps(data, indent=2, ensure_ascii=False)) + except Exception: + click.echo(json.dumps({"status": "disconnected", "note": "Health Server 未运行"}, indent=2)) + + +@tunnel.command() +@click.option("--url", default="wss://agent.brainwork.club/mindos-next/ws/cli-tunnel", + help="Cloud Tunnel WebSocket URL") +@click.option("--token", required=True, help="MindPass JWT") +def connect(url, token): + """手动建立 Tunnel 连接（通常由浏览器自动触发）。""" + import urllib.request + data = json.dumps({"token": token, "tunnelUrl": url}).encode() + try: + req = urllib.request.Request( + "http://127.0.0.1:8660/tunnel/activate", + data=data, + headers={"Content-Type": "application/json"}, + ) + with urllib.request.urlopen(req, timeout=5) as resp: + result = json.loads(resp.read()) + click.echo(f"✅ Tunnel activate: {result}") + except Exception as e: + click.echo(f"❌ 失败: {e}") + click.echo(" 确认 Health Server 已运行（mind start）") + + +@main.group() +def record(): + """管理本地系统录音。""" + pass + + +@record.command(name="start") +@click.option("--token", default="", help="MindPass JWT（默认使用 Tunnel 已有的）") +@click.option("--chat-id", default="", help="对话 ID") +@click.option("--source", type=click.Choice(["system", "mic"]), default="system", + help="音频源：system=系统音频（默认），mic=麦克风") +def record_start(token, chat_id, source): + """开始录音（独立音频源 → Cloud ASR）。 + + 双工模式下，CLI 和浏览器各自独立推送，不做混音。 + """ + import urllib.request + body = json.dumps({"token": token, "chatId": chat_id, "source": source}).encode() + try: + req = urllib.request.Request( + "http://127.0.0.1:8660/record/start", + data=body, + headers={"Content-Type": "application/json"}, + ) + with urllib.request.urlopen(req, timeout=10) as resp: + result = json.loads(resp.read()) + if result.get("ok"): + click.echo(f"🎙️ 录音已开始 source={result.get('source')} meetingId={result.get('meetingId')}") + click.echo(" 使用 `mind record stop` 停止") + else: + click.echo(f"❌ {result.get('error')}") + except Exception as e: + click.echo(f"❌ 失败: {e}") + click.echo(" 确认 Health Server 已运行（mind start）") + + +@record.command(name="stop") +def record_stop(): + """停止录音。""" + import urllib.request + try: + req = urllib.request.Request( + "http://127.0.0.1:8660/record/stop", + data=b"{}", + headers={"Content-Type": "application/json"}, + ) + with urllib.request.urlopen(req, timeout=10) as resp: + result = json.loads(resp.read()) + if result.get("ok"): + click.echo(f"⏹️ 录音已停止 duration={result.get('duration')}s") + else: + click.echo(f"❌ {result.get('error')}") + except Exception as e: + click.echo(f"❌ 失败: {e}") + + +@record.command(name="status") +def record_status(): + """查看录音状态。""" + import urllib.request + try: + req = urllib.request.Request("http://127.0.0.1:8660/record/status") + with urllib.request.urlopen(req, timeout=2) as resp: + data = json.loads(resp.read()) + if data.get("running"): + click.echo(f"🎙️ 录音中 duration={data.get('duration')}s chatId={data.get('chatId')}") + else: + click.echo("⏹️ 未在录音") + except Exception: + click.echo("⏹️ Health Server 未运行") + + +def _get_vendor_commit() -> str: + """读取 _vendor/HERMES_COMMIT 文件获取 vendor 版本。""" + commit_file = os.path.join(mindcli._VENDOR_DIR, "HERMES_COMMIT") + try: + with open(commit_file) as f: + return f.read().strip() + except FileNotFoundError: + return "unknown" + + +if __name__ == "__main__": + main() + diff --git a/mindcli/health.py b/mindcli/health.py new file mode 100644 index 0000000..40b415a --- /dev/null +++ b/mindcli/health.py @@ -0,0 +1,278 @@ +""" +Mind CLI — Health HTTP Server。 + +轻量 HTTP 端点（localhost:8660），供 Web UI 探测本地 CLI 是否在线。 +新增 /tunnel/activate 端点，接收浏览器 JWT 授权并启动 Tunnel。 +基于 http.server，不引入额外依赖。 +""" + +import asyncio +import json +import logging +import os +import platform +import sys +import time +import threading +from http.server import HTTPServer, BaseHTTPRequestHandler +from socketserver import ThreadingMixIn + +import mindcli + +logger = logging.getLogger("mindcli.health") + +# ── 全局状态（Phase 2 tunnel.py 会写入） ────────────────── +_tunnel_status = "disconnected" +_tool_count = 0 + + +def set_tunnel_status(status: str, tools: int = 0) -> None: + """由 tunnel.py 调用，更新隧道状态。""" + global _tunnel_status, _tool_count + _tunnel_status = status + _tool_count = tools + + +# asyncio 事件循环（tunnel 需要） +_loop: asyncio.AbstractEventLoop | None = None + +def _detect_capabilities() -> list[str]: + """检测当前 CLI 支持的能力列表。""" + caps = ["tunnel"] + try: + import sounddevice # noqa: F401 + caps.append("audio") + except ImportError: + pass + return caps + + +class _HealthHandler(BaseHTTPRequestHandler): + """处理 /health 和 /tunnel/activate 请求。""" + + def do_GET(self): + if self.path == "/health": + body = json.dumps({ + "ok": True, + "version": mindcli.__version__, + "vendor": _get_vendor_commit(), + "tunnel": _tunnel_status, + "tools": _tool_count, + "platform": platform.system(), + "pid": os.getpid(), + "capabilities": _detect_capabilities(), + }, ensure_ascii=False) + self._respond(200, body) + elif self.path == "/tunnel/status": + from mindcli.tunnel import get_tunnel_client + client = get_tunnel_client() + body = json.dumps({ + "status": client.status, + "userId": client.user_id, + "tools": _tool_count, + }) + self._respond(200, body) + elif self.path == "/record/status": + try: + from mindcli.recorder import get_recorder + body = json.dumps(get_recorder().status(), ensure_ascii=False) + self._respond(200, body) + except Exception as e: + self._respond(500, json.dumps({"error": str(e)})) + else: + self._respond(404, json.dumps({"error": "Not Found"})) + + def do_POST(self): + """处理 POST 请求。""" + if self.path == "/tunnel/activate": + self._handle_tunnel_activate() + elif self.path == "/record/start": + self._handle_record_start() + elif self.path == "/record/stop": + self._handle_record_stop() + else: + self._respond(404, json.dumps({"error": "Not Found"})) + + def _handle_tunnel_activate(self): + """浏览器授权激活 Tunnel。""" + try: + content_length = int(self.headers.get("Content-Length", 0)) + raw = self.rfile.read(content_length) + data = json.loads(raw) + + token = data.get("token") + tunnel_url = data.get("tunnelUrl") + + if not token or not tunnel_url: + self._respond(400, json.dumps({"error": "Missing token or tunnelUrl"})) + return + + # 在 asyncio 事件循环中启动 tunnel + from mindcli.tunnel import get_tunnel_client + client = get_tunnel_client() + + if _loop and _loop.is_running(): + future = asyncio.run_coroutine_threadsafe( + client.activate(token, tunnel_url), _loop + ) + result = future.result(timeout=5) + else: + result = {"ok": True, "status": "no_event_loop"} + + logger.info("[Health] Tunnel activate: %s", result) + self._respond(200, json.dumps(result)) + + except Exception as e: + logger.error("[Health] Tunnel activate 失败: %s", e) + self._respond(500, json.dumps({"error": str(e)})) + + def _handle_record_start(self): + """启动本地录音 → WS 推送到 Cloud ASR。""" + try: + content_length = int(self.headers.get("Content-Length", 0)) + raw = self.rfile.read(content_length) + data = json.loads(raw) if raw else {} + + token = data.get("token", "") + chat_id = data.get("chatId", "") + meeting_id = data.get("meetingId", f"rec_{int(time.time() * 1000)}") + + # 构建 Cloud ASR WS URL + ws_base = data.get("wsUrl", "") + if not ws_base: + # 默认使用 Tunnel 所知的 Cloud 地址 + ws_base = ( + f"wss://agent.brainwork.club/mindos-next/ws/record" + f"?token={token}&chatId={chat_id}&meetingId={meeting_id}&source=system" + ) + + from mindcli.recorder import get_recorder + recorder = get_recorder() + source = data.get("source", "system") # "system" 或 "mic" + + if _loop and _loop.is_running(): + future = asyncio.run_coroutine_threadsafe( + recorder.start( + ws_url=ws_base, chat_id=chat_id, + meeting_id=meeting_id, source=source, + ), + _loop, + ) + result = future.result(timeout=10) + else: + result = {"error": "事件循环未运行，请先 mind start"} + + self._respond(200, json.dumps(result, ensure_ascii=False)) + except Exception as e: + logger.error("[Health] Record start 失败: %s", e) + self._respond(500, json.dumps({"error": str(e)})) + + def _handle_record_stop(self): + """停止本地录音。""" + try: + from mindcli.recorder import get_recorder + recorder = get_recorder() + + if _loop and _loop.is_running(): + future = asyncio.run_coroutine_threadsafe(recorder.stop(), _loop) + result = future.result(timeout=10) + else: + result = {"error": "事件循环未运行"} + + self._respond(200, json.dumps(result, ensure_ascii=False)) + except Exception as e: + logger.error("[Health] Record stop 失败: %s", e) + self._respond(500, json.dumps({"error": str(e)})) + + def do_OPTIONS(self): + """处理 CORS 预检请求。""" + self.send_response(204) + self._cors_headers() + self.end_headers() + + def _respond(self, code: int, body: str): + self.send_response(code) + self.send_header("Content-Type", "application/json; charset=utf-8") + self._cors_headers() + self.end_headers() + self.wfile.write(body.encode("utf-8")) + + def _cors_headers(self): + """允许浏览器跨域访问（Web UI → localhost:8660）。""" + self.send_header("Access-Control-Allow-Origin", "*") + self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS") + self.send_header("Access-Control-Allow-Headers", "Content-Type") + + def log_message(self, format, *args): + """静默日志，避免刷屏。""" + pass + + +class _ThreadedHTTPServer(ThreadingMixIn, HTTPServer): + """多线程 HTTP Server，避免慢客户端阻塞。""" + daemon_threads = True + + +def _get_vendor_commit() -> str: + commit_file = os.path.join(mindcli._VENDOR_DIR, "HERMES_COMMIT") + try: + with open(commit_file) as f: + return f.read().strip() + except FileNotFoundError: + return "unknown" + + +def start_health_server(port: int = 8660, foreground: bool = False) -> None: + """ + 启动 Health HTTP Server + asyncio 事件循环（Tunnel 需要）。 + + Args: + port: 监听端口（默认 8660） + foreground: True = 阻塞前台运行；False = 后台线程运行 + """ + global _loop + + # 确保 mindcli 下所有 logger 的 INFO 级别输出到控制台 + logging.basicConfig( + level=logging.INFO, + format="%(message)s", + force=True, + ) + + server = _ThreadedHTTPServer(("127.0.0.1", port), _HealthHandler) + + if foreground: + print(f"🩺 Mind CLI Health Server listening on http://127.0.0.1:{port}/health") + print(f" Tunnel activate: POST http://127.0.0.1:{port}/tunnel/activate") + print(f" Version: {mindcli.__version__} | PID: {os.getpid()}") + print(f" Press Ctrl+C to stop.\n") + + # HTTP Server 在独立线程 + http_thread = threading.Thread(target=server.serve_forever, daemon=True) + http_thread.start() + + # asyncio 事件循环在主线程（Tunnel WebSocket 需要） + _loop = asyncio.new_event_loop() + asyncio.set_event_loop(_loop) + try: + _loop.run_forever() + except KeyboardInterrupt: + print("\n🛑 Health Server stopped.") + finally: + _loop.close() + server.shutdown() + else: + # 后台模式：HTTP + asyncio 都在后台 + _loop = asyncio.new_event_loop() + + def _run_loop(): + asyncio.set_event_loop(_loop) + _loop.run_forever() + + loop_thread = threading.Thread(target=_run_loop, daemon=True) + loop_thread.start() + + http_thread = threading.Thread(target=server.serve_forever, daemon=True) + http_thread.start() + + return server diff --git a/mindcli/managed_mcp.py b/mindcli/managed_mcp.py new file mode 100644 index 0000000..415f9e5 --- /dev/null +++ b/mindcli/managed_mcp.py @@ -0,0 +1,183 @@ +""" +Mind CLI — Managed MCP 治理层。 + +在 _vendor/tools/ 之上加白名单过滤。Cloud 审批通过的工具才能执行。 +Managed 模式下：只允许 approved_tools 列表中的工具。 +""" + +import asyncio +import logging +import os +import subprocess +import sys +from typing import Any + +logger = logging.getLogger("mindcli.managed_mcp") + + +class ManagedMCP: + """ + 治理层：只暴露 Cloud 审批通过的工具。 + + Cloud 通过 Tunnel 握手下发 approved_tools 白名单， + 后续 tool_call 请求先过白名单检查，再委托到 _vendor/tools/ 执行。 + """ + + def __init__(self, approved_tools: list[str] | None = None): + self._approved: set[str] = set(approved_tools or []) + # 工具名 → 执行函数的映射 + self._executors: dict[str, Any] = {} + self._register_executors() + + def update_approved(self, tools: list[str]) -> None: + """Cloud 热更新白名单（无需重连）。""" + old = self._approved + self._approved = set(tools) + added = self._approved - old + removed = old - self._approved + if added: + logger.info("[ManagedMCP] 新增审批工具: %s", added) + if removed: + logger.info("[ManagedMCP] 移除审批工具: %s", removed) + + def is_approved(self, tool_name: str) -> bool: + """检查工具是否在白名单中。""" + return tool_name in self._approved + + async def execute(self, tool_name: str, params: dict) -> dict: + """ + 执行工具调用。 + + Args: + tool_name: 工具名（如 "terminal"、"grep"） + params: 工具参数 + + Returns: + {"output": "...", "exit_code": 0} 或 {"error": "..."} + """ + if not self.is_approved(tool_name): + logger.warning("[ManagedMCP] 工具 '%s' 未审批，拒绝执行", tool_name) + return {"error": f"Tool '{tool_name}' not approved by Cloud"} + + executor = self._executors.get(tool_name) + if not executor: + return {"error": f"Tool '{tool_name}' has no executor"} + + try: + result = await executor(params) + return result + except Exception as e: + logger.error("[ManagedMCP] 工具 '%s' 执行异常: %s", tool_name, e) + return {"error": f"Execution failed: {str(e)}"} + + def _register_executors(self) -> None: + """注册内置工具的执行函数。""" + self._executors["terminal"] = self._exec_terminal + self._executors["file_read"] = self._exec_file_read + self._executors["file_write"] = self._exec_file_write + self._executors["grep"] = self._exec_grep + self._executors["file_ops"] = self._exec_file_ops + self._executors["code_execution"] = self._exec_code + + # ── 内置工具执行器 ────────────────────────────── + + async def _exec_terminal(self, params: dict) -> dict: + """执行终端命令。""" + command = params.get("command", "") + cwd = params.get("cwd", os.path.expanduser("~")) + timeout = params.get("timeout", 30) + + try: + proc = await asyncio.create_subprocess_shell( + command, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + cwd=cwd, + ) + stdout, stderr = await asyncio.wait_for( + proc.communicate(), timeout=timeout + ) + return { + "output": stdout.decode("utf-8", errors="replace"), + "stderr": stderr.decode("utf-8", errors="replace"), + "exit_code": proc.returncode, + } + except asyncio.TimeoutError: + proc.kill() + return {"error": f"Command timed out after {timeout}s", "exit_code": -1} + + async def _exec_file_read(self, params: dict) -> dict: + """读取文件内容。""" + path = params.get("path", "") + if not path or not os.path.isfile(path): + return {"error": f"File not found: {path}"} + + try: + with open(path, "r", encoding="utf-8", errors="replace") as f: + content = f.read() + return {"output": content, "size": len(content)} + except Exception as e: + return {"error": str(e)} + + async def _exec_file_write(self, params: dict) -> dict: + """写入文件。""" + path = params.get("path", "") + content = params.get("content", "") + if not path: + return {"error": "No path specified"} + + try: + os.makedirs(os.path.dirname(path), exist_ok=True) + with open(path, "w", encoding="utf-8") as f: + f.write(content) + return {"output": f"Written {len(content)} bytes to {path}"} + except Exception as e: + return {"error": str(e)} + + async def _exec_grep(self, params: dict) -> dict: + """文本搜索（ripgrep / grep）。""" + pattern = params.get("pattern", "") + path = params.get("path", ".") + if not pattern: + return {"error": "No pattern specified"} + + cmd = f"grep -rn {_shell_quote(pattern)} {_shell_quote(path)}" + return await self._exec_terminal({"command": cmd, "timeout": 15}) + + async def _exec_file_ops(self, params: dict) -> dict: + """文件操作：copy / move / delete。""" + op = params.get("operation", "") + src = params.get("source", "") + dst = params.get("destination", "") + + if op == "copy": + cmd = f"cp -r {_shell_quote(src)} {_shell_quote(dst)}" + elif op == "move": + cmd = f"mv {_shell_quote(src)} {_shell_quote(dst)}" + elif op == "delete": + cmd = f"rm -rf {_shell_quote(src)}" + elif op == "list": + cmd = f"ls -la {_shell_quote(src)}" + else: + return {"error": f"Unknown operation: {op}"} + + return await self._exec_terminal({"command": cmd, "timeout": 15}) + + async def _exec_code(self, params: dict) -> dict: + """执行代码片段（Python）。""" + code = params.get("code", "") + language = params.get("language", "python") + + if language != "python": + return {"error": f"Unsupported language: {language}"} + + return await self._exec_terminal({ + "command": f"{sys.executable} -c {_shell_quote(code)}", + "timeout": 30, + }) + + +def _shell_quote(s: str) -> str: + """简单的 shell 参数转义。""" + import shlex + return shlex.quote(s) diff --git a/mindcli/recorder.py b/mindcli/recorder.py new file mode 100644 index 0000000..8f8a054 --- /dev/null +++ b/mindcli/recorder.py @@ -0,0 +1,436 @@ +""" +Mind CLI — 系统拾音引擎 (Phase 4) + +双层架构·音频服务层： + CLI 作为音频服务层的一个独立源，只负责采集系统音频。 + 浏览器/APK 负责麦克风。双工模式下两路各走各的 Cloud ASR session。 + +支持两种采集模式（由调用方指定）： + - "system"（默认）：ScreenCaptureKit 系统音频（macOS only） + - "mic"：sounddevice 麦克风（无浏览器的 fallback 场景） + +不做混音。混音 = 伪需求。"关联两份转写"是 Agent 层的智力工作。 + +Cloud 端复用 dashscope_realtime.py 管线，零新增代码。 +协议与前端 RecordingService 完全一致： + 客户端→服务端: binary PCM16 帧 / {"type":"stop"} + 服务端→客户端: {"type":"partial/final","text":"..."} +""" + +import asyncio +import json +import logging +import threading +import time +from typing import Callable, Literal + +logger = logging.getLogger("mindcli.recorder") + +# ── 常量 ────────────────────────────────────────────────── +TARGET_SAMPLE_RATE = 16000 # Cloud ASR 要求 16kHz +CHUNK_DURATION_MS = 100 # 每帧 100ms +CHUNK_SAMPLES = TARGET_SAMPLE_RATE * CHUNK_DURATION_MS // 1000 # 1600 + +# ── 全局单例 ────────────────────────────────────────────── +_recorder: "SystemRecorder | None" = None + + +def get_recorder() -> "SystemRecorder": + """获取全局 SystemRecorder 单例。""" + global _recorder + if _recorder is None: + _recorder = SystemRecorder() + return _recorder + + +class SystemRecorder: + """ + 系统拾音引擎 — 音频服务层的一个独立源。 + + 只负责单一音频源的采集 + WS 推送。 + 不做混音（双工模式下浏览器和 CLI 各自独立推送到 Cloud ASR）。 + """ + + def __init__(self): + self._running = False + self._ws = None + self._source: str = "system" + self._start_time = 0.0 + self._chat_id = "" + self._meeting_id = "" + # 音频缓冲区（线程安全） + self._audio_buf: bytearray = bytearray() + self._buf_lock = threading.Lock() + # 采集资源 + self._mic_stream = None # sounddevice.InputStream + self._sc_stream = None # SCStream + self._sc_delegate = None + # 推送线程 + self._push_thread: threading.Thread | None = None + # asyncio 事件循环引用（start 时保存） + self._loop: asyncio.AbstractEventLoop | None = None + # 事件回调 + self._on_text: Callable[[str, str], None] | None = None + + @property + def is_running(self) -> bool: + return self._running + + def status(self) -> dict: + """返回当前录音状态。""" + return { + "running": self._running, + "source": self._source if self._running else None, + "duration": round(time.time() - self._start_time, 1) if self._running else 0, + "chatId": self._chat_id, + "meetingId": self._meeting_id, + } + + async def start( + self, + ws_url: str, + chat_id: str = "", + meeting_id: str = "", + source: Literal["system", "mic"] = "system", + on_text: Callable[[str, str], None] | None = None, + ) -> dict: + """ + 开始录音（单一源）。 + + Args: + ws_url: Cloud ASR WebSocket URL（含 token/chatId/meetingId query） + chat_id: 对话 ID + meeting_id: 录音批次 ID + source: "system"（ScreenCaptureKit）或 "mic"（sounddevice） + on_text: 收到转写文本的回调 (type, text) + + Returns: + {"ok": True, "meetingId": "..."} 或 {"error": "..."} + """ + if self._running: + return {"error": "录音已在进行中"} + + self._chat_id = chat_id + self._meeting_id = meeting_id or f"cli_rec_{int(time.time() * 1000)}" + self._source = source + self._on_text = on_text + self._audio_buf.clear() + self._loop = asyncio.get_running_loop() + + # 1. 连接 Cloud ASR WebSocket + try: + import websockets + self._ws = await websockets.connect(ws_url) + logger.info("[Recorder] WS 已连接: %s", ws_url[:80]) + except Exception as e: + logger.error("[Recorder] WS 连接失败: %s", e) + return {"error": f"WebSocket 连接失败: {e}"} + + # 2. 启动音频采集 + try: + if source == "system": + self._start_system_audio() + else: + self._start_mic() + except Exception as e: + logger.error("[Recorder] 音频源 '%s' 启动失败: %s", source, e) + await self._ws.close() + self._ws = None + return {"error": f"音频源启动失败: {e}"} + + # 3. 启动推送线程 + self._running = True + self._start_time = time.time() + self._push_thread = threading.Thread(target=self._push_loop, daemon=True) + self._push_thread.start() + + # 4. 启动 WS 接收协程（转写结果） + asyncio.create_task(self._ws_recv_loop()) + + logger.info("[Recorder] 录音已开始 source=%s chatId=%s meetingId=%s", + source, chat_id, self._meeting_id) + return {"ok": True, "meetingId": self._meeting_id, "source": source} + + async def stop(self) -> dict: + """停止录音。""" + if not self._running: + return {"error": "未在录音"} + + self._running = False + duration = round(time.time() - self._start_time, 1) + + # 停止音频源 + self._stop_capture() + + # 等待推送线程结束 + if self._push_thread and self._push_thread.is_alive(): + self._push_thread.join(timeout=3) + + # 发送 stop 命令 + if self._ws: + try: + await self._ws.send(json.dumps({"type": "stop"})) + await asyncio.sleep(1) + await self._ws.close() + except Exception: + pass + self._ws = None + + logger.info("[Recorder] 录音已停止 duration=%.1fs", duration) + return {"ok": True, "duration": duration, "meetingId": self._meeting_id} + + # ── 麦克风采集（sounddevice）──────────────────────────── + + def _start_mic(self): + """启动麦克风捕获 16kHz mono int16。""" + import sounddevice as sd + + def _callback(indata, frames, time_info, status): + if status: + logger.debug("[Recorder] mic status: %s", status) + with self._buf_lock: + self._audio_buf.extend(indata.tobytes()) + + self._mic_stream = sd.InputStream( + samplerate=TARGET_SAMPLE_RATE, + channels=1, + dtype="int16", + blocksize=CHUNK_SAMPLES, + callback=_callback, + ) + self._mic_stream.start() + logger.info("[Recorder] 麦克风已启动 @%dHz", TARGET_SAMPLE_RATE) + + # ── 系统音频采集（ScreenCaptureKit）───────────────────── + + def _start_system_audio(self): + """启动 macOS 系统音频捕获。""" + import platform + if platform.system() != "Darwin": + raise RuntimeError("系统音频仅支持 macOS") + + try: + from ScreenCaptureKit import ( + SCStream, + SCStreamConfiguration, + SCContentFilter, + SCStreamOutputTypeAudio, + ) + from dispatch import dispatch_queue_create, DISPATCH_QUEUE_SERIAL + except ImportError as e: + raise RuntimeError( + f"缺少 pyobjc 依赖，请运行: pip install mindos-cli[audio]\n{e}" + ) + + # 获取主显示器 + content = _sync_get_sharable_content() + if not content or not content.displays(): + raise RuntimeError("无法获取显示器列表") + + display = content.displays()[0] + + # 配置：只捕获音频 + config = SCStreamConfiguration.alloc().init() + config.setCapturesAudio_(True) + config.setExcludesCurrentProcessAudio_(True) + config.setChannelCount_(1) + config.setSampleRate_(float(TARGET_SAMPLE_RATE)) + + # 内容过滤器 + content_filter = SCContentFilter.alloc().initWithDisplay_excludingWindows_( + display, [] + ) + + # 创建 delegate + _ensure_delegate_class() + self._sc_delegate = _SCStreamDelegate.alloc().init() + self._sc_delegate._recorder = self + + # 创建 stream + self._sc_stream = SCStream.alloc().initWithFilter_configuration_delegate_( + content_filter, config, None + ) + + # dispatch queue + queue = dispatch_queue_create(b"mindcli.audio", DISPATCH_QUEUE_SERIAL) + self._sc_stream.addStreamOutput_type_sampleHandlerQueue_error_( + self._sc_delegate, SCStreamOutputTypeAudio, queue, None + ) + + # 启动 + event = threading.Event() + error_holder = [None] + + def _on_start(error): + if error: + error_holder[0] = str(error) + event.set() + + self._sc_stream.startCaptureWithCompletionHandler_(_on_start) + event.wait(timeout=5) + + if error_holder[0]: + raise RuntimeError(f"SCStream 启动失败: {error_holder[0]}") + + logger.info("[Recorder] 系统音频已启动 (ScreenCaptureKit @%dHz)", TARGET_SAMPLE_RATE) + + def _on_system_audio(self, raw_bytes: bytes): + """系统音频回调。SCStream 输出 float32 PCM，需要转为 int16。""" + import struct + # float32: 每个样本 4 字节；int16: 每个样本 2 字节 + n_samples = len(raw_bytes) // 4 + if n_samples == 0: + return + # 解包 float32 + floats = struct.unpack(f'<{n_samples}f', raw_bytes[:n_samples * 4]) + # clamp [-1, 1] → scale to int16 range + int16_data = struct.pack(f'<{n_samples}h', + *(max(-32768, min(32767, int(s * 32767))) for s in floats) + ) + with self._buf_lock: + self._audio_buf.extend(int16_data) + + # ── 停止采集 ───────────────────────────────────────────── + + def _stop_capture(self): + """停止当前音频源。""" + # 麦克风 + if self._mic_stream: + try: + self._mic_stream.stop() + self._mic_stream.close() + except Exception: + pass + self._mic_stream = None + + # 系统音频 + if self._sc_stream: + event = threading.Event() + self._sc_stream.stopCaptureWithCompletionHandler_(lambda e: event.set()) + event.wait(timeout=3) + self._sc_stream = None + self._sc_delegate = None + + # ── WS 推送 ────────────────────────────────────────────── + + def _push_loop(self): + """后台线程：定时取缓冲区 → WS 推送 PCM16 帧。""" + frame_bytes = CHUNK_SAMPLES * 2 # int16 = 2 bytes/sample = 3200 + send_count = 0 + + while self._running: + time.sleep(CHUNK_DURATION_MS / 1000.0) + + # 一次取尽缓冲区 + with self._buf_lock: + if len(self._audio_buf) < frame_bytes: + continue + pending = bytes(self._audio_buf) + self._audio_buf.clear() + + ws = self._ws + if ws is None: + continue + + # 按帧大小分片发送 + offset = 0 + while offset + frame_bytes <= len(pending): + chunk = pending[offset:offset + frame_bytes] + try: + asyncio.run_coroutine_threadsafe(ws.send(chunk), self._loop) + send_count += 1 + except Exception as e: + logger.debug("[Recorder] WS send err: %s", e) + break + offset += frame_bytes + + # 每 ~5s 打一次发送统计 + if send_count > 0 and send_count % 50 == 0: + logger.info("[Recorder] WS sent %d frames (%.1fs)", + send_count, send_count * CHUNK_DURATION_MS / 1000) + + async def _ws_recv_loop(self): + """接收 Cloud ASR 的转写结果。""" + try: + async for msg in self._ws: + try: + data = json.loads(msg) + msg_type = data.get("type", "") + text = data.get("text", "") + if msg_type in ("partial", "final") and text: + logger.info("[Recorder] %s: %s", msg_type, text[:50]) + if self._on_text: + self._on_text(msg_type, text) + elif msg_type == "error": + logger.error("[Recorder] ASR error: %s", data.get("message")) + except (json.JSONDecodeError, TypeError): + pass + except Exception as e: + if self._running: + logger.warning("[Recorder] WS recv 断开: %s", e) + + +# ── 工具函数 ────────────────────────────────────────────── + +def _sync_get_sharable_content(): + """同步获取 SCShareableContent（阻塞等待 async 回调）。""" + from ScreenCaptureKit import SCShareableContent + + result = [None] + event = threading.Event() + + def _handler(content, error): + if error: + logger.error("[Recorder] SCShareableContent error: %s", error) + result[0] = content + event.set() + + SCShareableContent.getShareableContentExcludingDesktopWindows_onScreenWindowsOnly_completionHandler_( + False, True, _handler + ) + event.wait(timeout=5) + return result[0] + + +# ── SCStream Delegate ──────────────────────────────────── + +_SCStreamDelegate = None + + +def _define_sc_delegate(): + """延迟定义 SCStreamDelegate（避免 import 时要求 pyobjc）。""" + from Foundation import NSObject + from ScreenCaptureKit import SCStreamOutputTypeAudio + import CoreMedia + + class _Delegate(NSObject): + """接收 SCStream 音频样本的 delegate。""" + + _recorder = None + + def stream_didOutputSampleBuffer_ofType_(self, stream, sample_buffer, output_type): + if output_type != SCStreamOutputTypeAudio: + return + if not self._recorder or not self._recorder.is_running: + return + + try: + block_buf = CoreMedia.CMSampleBufferGetDataBuffer(sample_buffer) + if block_buf is None: + return + length = CoreMedia.CMBlockBufferGetDataLength(block_buf) + # CMBlockBufferCopyDataBytes 返回 (OSStatus, bytes_data) + status, raw_data = CoreMedia.CMBlockBufferCopyDataBytes(block_buf, 0, length, None) + if status == 0 and raw_data: + self._recorder._on_system_audio(raw_data) + except Exception as e: + logger.warning("[Recorder] SCStream sample error: %s", e, exc_info=True) + + return _Delegate + + +def _ensure_delegate_class(): + global _SCStreamDelegate + if _SCStreamDelegate is None: + _SCStreamDelegate = _define_sc_delegate() + return _SCStreamDelegate diff --git a/mindcli/service.py b/mindcli/service.py new file mode 100644 index 0000000..48abba5 --- /dev/null +++ b/mindcli/service.py @@ -0,0 +1,116 @@ +""" +Mind CLI — macOS Service 注册。 + +通过 launchd plist 实现 `mind start` 开机自启。 +""" + +import os +import platform +import shutil +import subprocess +import sys +import textwrap + +_LABEL = "club.brainwork.mindcli" +_PLIST_DIR = os.path.expanduser("~/Library/LaunchAgents") +_PLIST_PATH = os.path.join(_PLIST_DIR, f"{_LABEL}.plist") +_LOG_PATH = os.path.expanduser("~/Library/Logs/mindcli.log") + + +def _find_mind_executable() -> str: + """定位 mind 可执行文件路径。""" + # 优先使用 which + result = shutil.which("mind") + if result: + return result + # 回退：当前 Python 的 scripts 目录 + scripts_dir = os.path.join(os.path.dirname(sys.executable), "mind") + if os.path.isfile(scripts_dir): + return scripts_dir + raise FileNotFoundError( + "找不到 mind 可执行文件。请确认已运行 `pip install -e .` 安装 mindos-cli。" + ) + + +def install_service() -> None: + """ + 注册 Mind CLI 为 macOS launchd 服务。 + + 生成 plist → launchctl load → 开机自启。 + """ + if platform.system() != "Darwin": + print("⚠️ install-service 目前仅支持 macOS。") + print(" Linux 用户请手动创建 systemd unit。") + return + + mind_path = _find_mind_executable() + os.makedirs(_PLIST_DIR, exist_ok=True) + + plist_content = textwrap.dedent(f"""\ + <?xml version="1.0" encoding="UTF-8"?> + <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" + "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> + <plist version="1.0"> + <dict> + <key>Label</key> + <string>{_LABEL}</string> + + <key>ProgramArguments</key> + <array> + <string>{mind_path}</string> + <string>start</string> + </array> + + <key>RunAtLoad</key> + <true/> + + <key>KeepAlive</key> + <true/> + + <key>StandardOutPath</key> + <string>{_LOG_PATH}</string> + + <key>StandardErrorPath</key> + <string>{_LOG_PATH}</string> + + <key>ThrottleInterval</key> + <integer>10</integer> + </dict> + </plist> + """) + + with open(_PLIST_PATH, "w") as f: + f.write(plist_content) + + # launchctl load + subprocess.run(["launchctl", "load", _PLIST_PATH], check=True) + + print(f"✅ Mind CLI 已注册为 launchd 服务") + print(f" Plist: {_PLIST_PATH}") + print(f" Log: {_LOG_PATH}") + print(f" Binary: {mind_path}") + print(f"\n 服务将在登录时自动启动。") + print(f" 手动启动：launchctl start {_LABEL}") + print(f" 手动停止：launchctl stop {_LABEL}") + + +def uninstall_service() -> None: + """ + 注销 Mind CLI launchd 服务。 + + launchctl unload → 删除 plist。 + """ + if platform.system() != "Darwin": + print("⚠️ uninstall-service 目前仅支持 macOS。") + return + + if not os.path.isfile(_PLIST_PATH): + print(f"⚠️ 未找到 plist: {_PLIST_PATH}") + print(f" Mind CLI 可能未注册为服务。") + return + + subprocess.run(["launchctl", "unload", _PLIST_PATH], check=False) + os.remove(_PLIST_PATH) + + print(f"✅ Mind CLI 服务已注销") + print(f" 已删除: {_PLIST_PATH}") diff --git a/mindcli/tunnel.py b/mindcli/tunnel.py new file mode 100644 index 0000000..6142a4c --- /dev/null +++ b/mindcli/tunnel.py @@ -0,0 +1,242 @@ +""" +Mind CLI — WebSocket Tunnel 客户端。 + +连接到 Cloud 端 mindcli_bridge，接收工具调用指令并在本地执行。 +采用 Browser-Donated JWT 认证：浏览器授权 CLI，CLI 不需独立认证。 +""" + +import asyncio +import json +import logging +import os +import time +from typing import Any + +logger = logging.getLogger("mindcli.tunnel") + +# 连接状态 +DISCONNECTED = "disconnected" +CONNECTING = "connecting" +CONNECTED = "connected" + + +class TunnelClient: + """ + CLI → Cloud WebSocket 隧道。 + + 生命周期： + 1. 浏览器 POST /tunnel/activate → 提供 JWT + tunnelUrl + 2. TunnelClient.connect() → WebSocket 握手 + 能力协商 + 3. 消息循环：接收 tool_call → ManagedMCP 执行 → 返回结果 + 4. 心跳维持 30s / 断线指数退避重连 + """ + + def __init__(self): + self._status = DISCONNECTED + self._ws = None + self._jwt: str | None = None + self._tunnel_url: str | None = None + self._user_id: str | None = None + self._managed_mcp = None + self._reconnect_task: asyncio.Task | None = None + self._heartbeat_task: asyncio.Task | None = None + self._message_task: asyncio.Task | None = None + + # 重连参数 + self._reconnect_delay = 1.0 + self._max_reconnect_delay = 30.0 + self._reconnect_attempts = 0 + + # 回调：通知 health.py 更新状态 + self._on_status_change = None + + @property + def status(self) -> str: + return self._status + + @property + def user_id(self) -> str | None: + return self._user_id + + def set_status_callback(self, callback) -> None: + """设置状态变更回调（由 health.py 注册）。""" + self._on_status_change = callback + + def _set_status(self, status: str) -> None: + self._status = status + if self._on_status_change: + self._on_status_change(status) + + async def activate(self, jwt: str, tunnel_url: str) -> dict: + """ + 浏览器授权激活 Tunnel。 + + Args: + jwt: MindPass JWT（浏览器提供） + tunnel_url: Cloud Tunnel WebSocket URL + + Returns: + {"ok": True, "status": "connecting"} + """ + self._jwt = jwt + self._tunnel_url = tunnel_url + + # 取消旧连接 + await self.disconnect() + + # 后台启动连接 + self._reconnect_task = asyncio.create_task(self._connect_loop()) + + return {"ok": True, "status": "connecting"} + + async def disconnect(self) -> None: + """断开 Tunnel 连接。""" + # 取消所有后台任务 + for task in [self._reconnect_task, self._heartbeat_task, self._message_task]: + if task and not task.done(): + task.cancel() + try: + await task + except asyncio.CancelledError: + pass + + if self._ws: + try: + await self._ws.close() + except Exception: + pass + self._ws = None + + self._set_status(DISCONNECTED) + self._reconnect_attempts = 0 + self._reconnect_delay = 1.0 + logger.info("[Tunnel] 已断开") + + async def _connect_loop(self) -> None: + """连接循环：握手 → 消息循环 → 断线重连。""" + while True: + try: + self._set_status(CONNECTING) + await self._connect() + # 连接成功，重置重连参数 + self._reconnect_delay = 1.0 + self._reconnect_attempts = 0 + # 进入消息循环（阻塞直到断线） + await self._run() + except asyncio.CancelledError: + return + except Exception as e: + logger.warning("[Tunnel] 连接异常: %s", e) + + # 断线，指数退避重连 + self._set_status(DISCONNECTED) + self._reconnect_attempts += 1 + delay = min(self._reconnect_delay, self._max_reconnect_delay) + logger.info("[Tunnel] %ds 后重连（第 %d 次）...", delay, self._reconnect_attempts) + await asyncio.sleep(delay) + self._reconnect_delay = min(self._reconnect_delay * 2, self._max_reconnect_delay) + + async def _connect(self) -> None: + """WebSocket 握手 + 能力协商。""" + try: + import websockets + except ImportError: + logger.error("[Tunnel] websockets 未安装。运行: pip install websockets") + raise + + headers = {"Authorization": f"Bearer {self._jwt}"} + self._ws = await websockets.connect( + self._tunnel_url, + additional_headers=headers, + ping_interval=30, + ping_timeout=10, + close_timeout=5, + ) + + # 等待 Cloud 确认 + raw = await asyncio.wait_for(self._ws.recv(), timeout=10) + msg = json.loads(raw) + if msg.get("type") != "connected": + raise ConnectionError(f"握手失败: {msg}") + + self._user_id = msg.get("userId") + logger.info("[Tunnel] 已连接，userId=%s", self._user_id) + + # 发送能力报告 + from mindcli.capability import scan_capabilities + cap = scan_capabilities() + await self._ws.send(json.dumps({ + "type": "capability_report", + **cap, + })) + + # 接收审批结果 + raw = await asyncio.wait_for(self._ws.recv(), timeout=10) + approval = json.loads(raw) + if approval.get("type") == "approved_tools": + approved = approval.get("tools", []) + # 初始化 ManagedMCP + from mindcli.managed_mcp import ManagedMCP + self._managed_mcp = ManagedMCP(approved_tools=approved) + logger.info("[Tunnel] 审批通过工具: %s", approved) + + # 更新 health 状态 + from mindcli.health import set_tunnel_status + set_tunnel_status("connected", len(approved) if approval.get("type") == "approved_tools" else 0) + self._set_status(CONNECTED) + + async def _run(self) -> None: + """主消息循环：接收 Cloud 指令 → 本地执行 → 返回结果。""" + try: + async for raw in self._ws: + msg = json.loads(raw) + + if msg.get("jsonrpc") == "2.0" and msg.get("method") == "tool_call": + await self._handle_tool_call(msg) + elif msg.get("type") == "approved_tools": + # 热更新白名单 + if self._managed_mcp: + self._managed_mcp.update_approved(msg.get("tools", [])) + elif msg.get("type") == "ping": + await self._ws.send(json.dumps({"type": "pong"})) + else: + logger.debug("[Tunnel] 未知消息: %s", msg.get("type")) + except Exception as e: + logger.warning("[Tunnel] 消息循环异常: %s", e) + raise + + async def _handle_tool_call(self, msg: dict) -> None: + """处理工具调用请求。""" + call_id = msg.get("id", "unknown") + params = msg.get("params", {}) + tool_name = params.get("tool", "") + tool_args = params.get("args", {}) + + logger.info("[Tunnel] 工具调用: %s (id=%s)", tool_name, call_id) + + if not self._managed_mcp: + result = {"error": "ManagedMCP not initialized"} + else: + result = await self._managed_mcp.execute(tool_name, tool_args) + + # 截断过大的输出（防止 WS 阻塞） + output = result.get("output", "") + if isinstance(output, str) and len(output) > 50000: + result["output"] = output[:50000] + f"\n\n... [截断：原始 {len(output)} 字符]" + result["truncated"] = True + + response = { + "jsonrpc": "2.0", + "id": call_id, + "result": result, + } + await self._ws.send(json.dumps(response)) + + +# ── 全局单例 ────────────────────────────────────────── +_tunnel_client = TunnelClient() + + +def get_tunnel_client() -> TunnelClient: + """获取全局 TunnelClient 实例。""" + return _tunnel_client diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..7360fde --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,50 @@ +[build-system] +requires = ["setuptools>=68.0", "wheel"] +build-backend = "setuptools.build_meta" + +[project] +name = "mindos-cli" +version = "0.1.0" +description = "MindOS NEXT 本地执行体 — Cloud Hermes 的受管理执行节点" +readme = "README.md" +requires-python = ">=3.10" +license = {text = "MIT"} +authors = [ + {name = "MindOS Team"}, +] + +dependencies = [ + # Hermes 核心依赖 + "litellm>=1.30", + "openai>=1.0", + "rich>=13.0", + "prompt-toolkit>=3.0", + "tiktoken>=0.5", + "fire>=0.5", + "pyyaml>=6.0", + "aiohttp>=3.9", + # MCP 协议 + "mcp>=1.0", + # Mind CLI 专属 + "websockets>=12.0", + "click>=8.0", +] + +[project.optional-dependencies] +# macOS 系统拾音（Phase 4） +audio = [ + "pyobjc-core>=10.0", + "pyobjc-framework-Quartz>=10.0", + "pyobjc-framework-ScreenCaptureKit>=10.0", + "pyobjc-framework-CoreMedia>=10.0", + "pyobjc-framework-AVFoundation>=10.0", + "pyobjc-framework-libdispatch>=10.0", + "sounddevice>=0.4", + "numpy>=1.24", +] + +[project.scripts] +mind = "mindcli.cli:main" + +[tool.setuptools.packages.find] +include = ["mindcli*"] diff --git a/scripts/vendor_hermes.sh b/scripts/vendor_hermes.sh new file mode 100755 index 0000000..04875a8 --- /dev/null +++ b/scripts/vendor_hermes.sh @@ -0,0 +1,70 @@ +#!/bin/bash +# scripts/vendor_hermes.sh +# 从本地 hermes 仓库打快照到 mindcli/_vendor/ +# +# 用法: ./scripts/vendor_hermes.sh [hermes源码路径] +# 或: HERMES_SRC=/path/to/hermes ./scripts/vendor_hermes.sh +# +# 独立仓库，无默认路径——必须显式指定 hermes 源码位置。 + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +HERMES_SRC="${1:-${HERMES_SRC:-}}" + +if [ -z "$HERMES_SRC" ]; then + echo "❌ 请指定 hermes 源码路径：" + echo " $0 /path/to/hermes" + echo " 或设置环境变量: export HERMES_SRC=/path/to/hermes" + exit 1 +fi +VENDOR_DIR="$PROJECT_DIR/mindcli/_vendor" + +# 验证 hermes 源码存在 +if [ ! -f "$HERMES_SRC/cli.py" ]; then + echo "❌ 找不到 hermes 源码: $HERMES_SRC/cli.py" + echo "用法: $0 [hermes源码路径]" + exit 1 +fi + +# 获取 commit hash +COMMIT="unknown" +if cd "$HERMES_SRC" && git rev-parse --short HEAD >/dev/null 2>&1; then + COMMIT=$(git rev-parse --short HEAD) +fi + +echo "📦 Vendoring hermes@$COMMIT → $VENDOR_DIR" + +# 清理旧快照 +rm -rf "$VENDOR_DIR" +mkdir -p "$VENDOR_DIR" + +# 核心模块 +cp "$HERMES_SRC/cli.py" "$VENDOR_DIR/" +cp "$HERMES_SRC/run_agent.py" "$VENDOR_DIR/" +cp "$HERMES_SRC/mcp_serve.py" "$VENDOR_DIR/" +cp "$HERMES_SRC/hermes_state.py" "$VENDOR_DIR/" +cp "$HERMES_SRC/hermes_constants.py" "$VENDOR_DIR/" +cp "$HERMES_SRC/batch_runner.py" "$VENDOR_DIR/" 2>/dev/null || true + +# 子模块 +cp -r "$HERMES_SRC/hermes_cli" "$VENDOR_DIR/" +cp -r "$HERMES_SRC/tools" "$VENDOR_DIR/" +cp -r "$HERMES_SRC/agent" "$VENDOR_DIR/" + +# __init__.py +touch "$VENDOR_DIR/__init__.py" + +# 版本锁定标记 +echo "$COMMIT" > "$VENDOR_DIR/HERMES_COMMIT" + +# 统计 +FILE_COUNT=$(find "$VENDOR_DIR" -name "*.py" | wc -l | tr -d ' ') +LINE_COUNT=$(find "$VENDOR_DIR" -name "*.py" -exec cat {} + | wc -l | tr -d ' ') + +echo "✅ Vendor 完成" +echo " Commit: $COMMIT" +echo " Files: $FILE_COUNT .py files" +echo " Lines: $LINE_COUNT lines" +echo " Path: $VENDOR_DIR"