| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594 |
- """Configuration-file checks for hermes doctor: .env, config.yaml validation, drift, deprecations.
- Split out of ``hermes_cli/doctor.py``."""
- from __future__ import annotations
- import os
- from hermes_cli.doctor_report import (
- Finding, _fail_and_issue, _section, check_bool, check_fail, check_info, check_ok, check_warn, doctor_check,
- warn_on_error,
- )
- def _has_provider_env_config(content: str) -> bool:
- """Return True when ~/.hermes/.env contains provider auth/base URL settings."""
- from hermes_cli.doctor import _PROVIDER_ENV_HINTS
- return any(key in content for key in _PROVIDER_ENV_HINTS)
- # Legacy config keys still read for back-compat: warn-only with the modern replacement, never auto-migrated
- # (migrations live in config.py). (section, key, replacement)
- _DEPRECATED_CONFIG_KEYS: tuple[tuple[str, str, str], ...] = (
- ("display", "tool_progress_overrides", "display.platforms"),
- ("delegation", "max_async_children", "delegation.max_concurrent_children"),
- ("compression", "summary_model", "auxiliary.compression"),
- ("compression", "summary_provider", "auxiliary.compression"), ("compression", "summary_base_url", "auxiliary.compression"),
- )
- # Deprecated env vars (checked in the .env FILE, not process env, so config→env bridges like terminal.cwd →
- # TERMINAL_CWD do not false-positive). HERMES_TOOL_PROGRESS is silently ignored since the v12 config floor
- # removed its only consumer; HERMES_TOOL_PROGRESS_MODE is still read by the gateway as a back-compat fallback.
- _DEPRECATED_ENV_VARS: tuple[tuple[str, str], ...] = (
- ("HERMES_TOOL_PROGRESS", "display.tool_progress in config.yaml — ignored/unsupported since config floor v12"),
- ("HERMES_TOOL_PROGRESS_MODE", "display.tool_progress in config.yaml"),
- ("TERMINAL_CWD", "terminal.cwd in config.yaml"), ("MESSAGING_CWD", "terminal.cwd in config.yaml"),
- ("QQ_HOME_CHANNEL", "QQBOT_HOME_CHANNEL"), ("QQ_HOME_CHANNEL_NAME", "QQBOT_HOME_CHANNEL_NAME"),
- )
- def collect_deprecated_config_keys(raw_config: dict | None) -> list[tuple[str, str]]:
- """``(legacy_path, replacement)`` for deprecated keys in the on-disk YAML (empty containers still count)."""
- if not isinstance(raw_config, dict):
- return []
- return [(f"{section}.{key}", replacement) for section, key, replacement in _DEPRECATED_CONFIG_KEYS
- if isinstance(raw_config.get(section), dict) and key in raw_config[section]]
- def collect_deprecated_env_vars(env_map: dict | None) -> list[tuple[str, str]]:
- """``(legacy_env, replacement)`` for deprecated vars in *env_map* (the on-disk ``.env``, not ``os.environ``,
- so bridged runtime vars do not false-positive)."""
- if not isinstance(env_map, dict):
- return []
- return [(name, replacement) for name, replacement in _DEPRECATED_ENV_VARS
- if env_map.get(name) is not None and str(env_map[name]).strip() != ""]
- def collect_relay_plugin_cutover_findings(raw_config: dict | None, env_map: dict | None) -> list[tuple[str, str]]:
- """Return actionable findings for the removed Hermes Relay plugin."""
- from hermes_cli.relay_plugin_cutover import (LEGACY_RELAY_EXPORT_ENV_VARS, RELAY_PLUGINS_CONFIG_ENV,
- configured_legacy_relay_env_vars, legacy_relay_plugin_keys)
- findings: list[tuple[str, str]] = []
- plugins = raw_config.get("plugins") if isinstance(raw_config, dict) else None
- if isinstance(plugins, dict):
- findings += [(f"plugins.enabled: {key}", "remove it and configure a standard user or system Relay plugins.toml; "
- f"use {RELAY_PLUGINS_CONFIG_ENV} for an explicit user-file override")
- for key in legacy_relay_plugin_keys(plugins.get("enabled"))]
- effective_env = dict(env_map or {})
- # Fall through to process env ONLY when no explicit env_map was given: run_doctor passes None and wants
- # live-process vars, but an explicit map describes a complete environment (merging os.environ breaks hermeticity).
- if env_map is None:
- for name in (*LEGACY_RELAY_EXPORT_ENV_VARS, RELAY_PLUGINS_CONFIG_ENV):
- if name not in effective_env and os.environ.get(name) is not None:
- effective_env[name] = os.environ[name]
- if not str(effective_env.get(RELAY_PLUGINS_CONFIG_ENV, "")).strip():
- findings += [(name, f"run `hermes migrate relay` to generate relay-plugins.toml and set {RELAY_PLUGINS_CONFIG_ENV}; "
- "this legacy variable is now ignored and does not configure an exporter")
- for name in configured_legacy_relay_env_vars(effective_env)]
- return findings
- def report_deprecated_config_and_env(raw_config: dict | None = None, env_map: dict | None = None) -> list[tuple[str, str]]:
- """Emit non-failing doctor warnings for deprecated config keys and env vars; returns the findings reported.
- Does not mutate config/env and does not append to the blocking ``issues`` list."""
- deprecated = collect_deprecated_config_keys(raw_config) + collect_deprecated_env_vars(env_map)
- relay_cutover = collect_relay_plugin_cutover_findings(raw_config, env_map)
- findings = deprecated + relay_cutover
- if not findings:
- check_ok("No deprecated config keys or env vars")
- return findings
- for legacy, replacement in deprecated:
- check_warn(f"Deprecated: {legacy}", f"(use {replacement} instead)")
- check_info(f"Replace {legacy} → {replacement} (warn-only; not auto-migrated here)")
- for legacy, replacement in relay_cutover:
- check_warn(f"Breaking Relay migration: {legacy}", f"({replacement})")
- check_info(f"Migrate {legacy}: {replacement}")
- return findings
- @doctor_check("Relay plugin check failed: {e}")
- def _check_relay_plugins(should_fix: bool, f: Finding) -> None:
- """Name the plugins.toml files Relay applies to Hermes, including ones outside the Hermes home."""
- from agent.relay_runtime import resolve_plugin_sources
- try:
- sources = resolve_plugin_sources()
- except ModuleNotFoundError as exc:
- if exc.name != "nemo_relay":
- raise
- check_ok("NeMo Relay is not available on this platform")
- return
- except Exception as exc:
- check_warn("Relay plugin configuration could not be read", "(Hermes runs without Relay plugins)")
- _relay_info_lines(cause for cause in (exc, exc.__cause__) if cause is not None)
- f.manual_issues.append("Fix the Relay plugin configuration shown under NeMo Relay Plugins.")
- return
- if not sources.config_paths:
- check_ok("No Relay plugin files found")
- return
- if sources.errors:
- check_warn("Relay will reject this plugin configuration", "(Hermes runs without Relay plugins)")
- f.manual_issues.append("Fix the Relay plugin configuration shown under NeMo Relay Plugins.")
- else:
- # Validation cannot load dynamic plugins, so Relay reports what it cannot confirm as a warning.
- report = check_warn if sources.warnings else check_ok
- if sources.enabled:
- report("Relay plugins enabled", "(applies to every profile a Hermes process hosts)")
- else:
- report("Relay plugin files found, nothing enabled")
- _relay_info_lines((*sources.config_paths, *sources.errors, *sources.warnings))
- def _relay_info_lines(lines) -> None:
- """Print Relay paths and messages as doctor detail rows, keeping multi-line parser errors indented."""
- for line in lines:
- check_info("\n ".join(part for part in str(line).strip().splitlines() if part.strip()))
- def managed_scope_check() -> None:
- """Report the active managed scope (resolved dir + pinned key counts); silent when none. A HERMES_MANAGED_DIR
- override is surfaced too — a redirected scope is the documented foot-gun (docs/design/managed-scope.md §7)."""
- managed_dir = None
- with warn_on_error(""): # diagnostics must never crash
- from hermes_cli import managed_scope
- managed_dir = managed_scope.get_managed_dir()
- if managed_dir is None:
- return
- n_cfg, n_env = len(managed_scope.managed_config_keys()), len(managed_scope.load_managed_env())
- check_ok(f"Managed scope active: {n_cfg} config key(s), {n_env} env key(s) pinned by {managed_dir}")
- if os.environ.get("HERMES_MANAGED_DIR", "").strip():
- check_info(f"managed dir set via HERMES_MANAGED_DIR={managed_dir}")
- @doctor_check("MCP security check failed: {e}")
- def _check_mcp_security(should_fix: bool, f: Finding) -> None:
- """Flag mcp_servers entries with suspicious stdio commands."""
- from hermes_cli.config import load_config
- from hermes_cli.mcp_security import validate_mcp_server_entry
- servers = load_config().get("mcp_servers") or {}
- suspicious = 0
- for name, entry in sorted(servers.items()) if isinstance(servers, dict) else ():
- issues_found = validate_mcp_server_entry(name, entry) if isinstance(entry, dict) else None
- if not issues_found:
- continue
- suspicious += 1
- check_warn(f"MCP server '{name}' has suspicious stdio command", "; ".join(issues_found))
- f.manual_issues.append(f"Review/remove mcp_servers.{name} in config.yaml; rotate any credentials that may have been exposed.")
- if suspicious == 0:
- check_ok("No suspicious MCP stdio commands")
- @doctor_check()
- def _check_env_file(should_fix: bool, f: Finding) -> None:
- """Managed scope plus ~/.hermes/.env presence and provider credentials."""
- from hermes_cli.doctor import HERMES_HOME, PROJECT_ROOT, _DHH
- managed_scope_check()
- env_path = HERMES_HOME / '.env'
- if env_path.exists():
- check_ok(f"{_DHH}/.env file exists")
- # UTF-8 first; latin-1 fallback for Windows Notepad/cp1252 files (matches env_loader._load_dotenv_with_fallback).
- try:
- content = env_path.read_text(encoding="utf-8-sig")
- except UnicodeDecodeError:
- content = env_path.read_text(encoding="latin-1")
- if not check_bool(_has_provider_env_config(content), "API key or custom endpoint configured", f"No API key found in {_DHH}/.env"):
- f.issues.append("Run 'hermes setup' to configure API keys")
- elif (PROJECT_ROOT / '.env').exists(): # project root as fallback
- 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()
- # .env holds API keys — touch() obeys umask (commonly 0o022, world-readable); tighten explicitly.
- with warn_on_error(""):
- os.chmod(str(env_path), 0o600)
- check_ok(f"Created empty {_DHH}/.env")
- check_info("Run 'hermes setup' to configure API keys")
- f.fixed += 1
- else:
- check_info("Run 'hermes setup' to create one")
- f.issues.append("Run 'hermes setup' to create .env")
- def _known_provider_ids(cfg: dict) -> tuple[set, list, object, object, object]:
- """Return (known ids, custom providers, resolve_auth, normalize, resolve_full); any import failure leaves
- the matching resolver as None so validation degrades to "unavailable" rather than crashing doctor."""
- known: set = set()
- resolve_auth = normalize = resolve_full = aliases = None
- custom_providers: list = []
- with warn_on_error(""):
- from hermes_cli.auth import PROVIDER_REGISTRY, resolve_provider as resolve_auth
- known = set(PROVIDER_REGISTRY.keys()) | {"openrouter", "custom", "auto", "moa"}
- with warn_on_error(""):
- from hermes_cli.config import get_compatible_custom_providers
- from hermes_cli.providers import custom_provider_aliases as aliases, normalize_provider as normalize, resolve_provider_full as resolve_full
- with warn_on_error(""):
- custom_providers = get_compatible_custom_providers(cfg)
- user_providers = cfg.get("providers")
- if isinstance(user_providers, dict):
- from hermes_cli.config import is_provider_enabled
- known.update(str(name).strip().lower() for name, prov_cfg in user_providers.items()
- if str(name).strip() and is_provider_enabled(prov_cfg))
- for entry in custom_providers if aliases is not None else ():
- name = str(entry.get("name") or "").strip() if isinstance(entry, dict) else ""
- if name:
- known.update(aliases(name, str(entry.get("provider_key") or "").strip()))
- return known, custom_providers, resolve_auth, normalize, resolve_full
- # Vendor/model slugs are valid on aggregators and any custom provider; Fireworks' native IDs are slash-form
- # (accounts/fireworks/models/...) and DeepInfra's catalog is exclusively vendor/model.
- _VENDOR_SLUG_PROVIDERS = {
- "openrouter", "auto", "ai-gateway", "kilocode", "opencode-zen", "huggingface", "lmstudio", "nous", "nvidia",
- "fireworks", "deepinfra",
- }
- def _provider_has_credentials(runtime_provider: str) -> bool:
- """Only API-key providers in PROVIDER_REGISTRY are checked — OAuth/SDK/custom providers have their own
- checks elsewhere, and get_auth_status() returns a bare {logged_in: False} for anything it doesn't dispatch."""
- if runtime_provider == "openrouter":
- from hermes_cli.config import get_env_value
- return any(str(get_env_value(k) or "").strip() for k in ("OPENROUTER_API_KEY", "OPENAI_API_KEY"))
- from hermes_cli.auth import PROVIDER_REGISTRY, get_auth_status
- pconfig = PROVIDER_REGISTRY.get(runtime_provider)
- if pconfig and getattr(pconfig, "auth_type", "") == "api_key":
- status = get_auth_status(runtime_provider) or {}
- return bool(status.get("configured") or status.get("logged_in") or status.get("api_key"))
- return True
- def _validate_model_config(config_path, issues: list) -> None:
- """Validate model.provider / model.default against the provider registry (raw file)."""
- # Detect stale root-level model keys (known bug source — PR #4329)
- from hermes_cli.config import read_user_config_raw
- cfg = read_user_config_raw(config_path)
- model_section = cfg.get("model") or {}
- provider_raw = (model_section.get("provider") or "").strip()
- provider = provider_raw.lower()
- default_model = (model_section.get("default") or model_section.get("model") or "").strip()
- known_providers, custom_providers, resolve_auth, normalize, resolve_full = _known_provider_ids(cfg)
- valid_provider_ids = set(known_providers)
- accept = {provider} if provider else set()
- for known_provider in known_providers if normalize is not None else ():
- try:
- valid_provider_ids.add(normalize(known_provider))
- except Exception:
- continue
- runtime_provider = catalog_provider = provider
- if provider and provider not in {"auto", "custom"}:
- if resolve_auth is not None:
- try:
- runtime_provider = resolve_auth(provider)
- accept.add(runtime_provider)
- except Exception:
- runtime_provider = provider
- if resolve_full is not None:
- provider_def = resolve_full(provider, cfg.get("providers"), custom_providers)
- catalog_provider = provider_def.id if provider_def is not None else None
- accept.update({catalog_provider} - {None})
- if provider and provider != "auto" and (catalog_provider is None or (known_providers and not (accept & valid_provider_ids))):
- known_list = ", ".join(sorted(known_providers)) if known_providers else "(unavailable)"
- _fail_and_issue(f"model.provider '{provider_raw}' is not a recognised provider", f"(known: {known_list})",
- f"model.provider '{provider_raw}' is unknown. Valid providers: {known_list}. "
- f"Fix: run 'hermes config set model.provider <valid_provider>'", issues)
- policy_id = str(runtime_provider or catalog_provider or "").strip().lower()
- accepts_vendor_slug = policy_id in _VENDOR_SLUG_PROVIDERS or policy_id == "custom" or policy_id.startswith("custom:")
- # openai-api pointed at a non-OpenAI endpoint (local router, proxy) is an aggregator in all but name:
- # the router owns the model namespace, so vendor/model slugs are the correct IDs there.
- model_base_url = str(model_section.get("base_url") or "").strip()
- if policy_id == "openai-api" and model_base_url:
- from utils import base_url_host_matches
- accepts_vendor_slug = accepts_vendor_slug or not base_url_host_matches(model_base_url, "api.openai.com")
- if default_model and "/" in default_model and policy_id and not accepts_vendor_slug:
- check_warn(f"model.default '{default_model}' uses a vendor/model slug but provider is '{provider_raw}'",
- "(vendor-prefixed slugs belong to aggregators like openrouter)")
- issues.append(f"model.default '{default_model}' is vendor-prefixed but model.provider is '{provider_raw}'. "
- "Either set model.provider to 'openrouter', or drop the vendor prefix.")
- if runtime_provider and runtime_provider not in ("auto", "custom"):
- from hermes_cli.doctor import _DHH
- with warn_on_error(""):
- if not _provider_has_credentials(runtime_provider):
- _fail_and_issue(f"model.provider '{runtime_provider}' is set but no API key is configured",
- f"(add it to {_DHH}/.env or run 'hermes setup')",
- f"No credentials found for provider '{runtime_provider}'. Run 'hermes setup' or set the provider's "
- f"API key in {_DHH}/.env, or switch providers with 'hermes config set model.provider <name>'", issues)
- def _validate_auxiliary_config(config_path, issues: list) -> None:
- """Resolve every routed ``auxiliary.<task>`` block through the real entry point the tasks use and report
- the ones that fail — an unresolvable block otherwise silently runs the task on the main model (#116055)."""
- from hermes_cli.config import read_user_config_raw
- from hermes_cli.left_core_migration import provider_install_hint
- from hermes_cli.runtime_provider import resolve_runtime_provider
- from utils import base_url_hostname
- aux = read_user_config_raw(config_path).get("auxiliary")
- routed = {name: block for name, block in (aux.items() if isinstance(aux, dict) else ())
- if isinstance(block, dict) and str(block.get("provider") or "").strip().lower() not in ("", "auto")}
- ok = []
- for task, block in sorted(routed.items()):
- provider, model, base_url, api_key = (str(block.get(k) or "").strip() or None for k in ("provider", "model", "base_url", "api_key"))
- try:
- runtime = resolve_runtime_provider(requested=provider, target_model=model, explicit_api_key=api_key, explicit_base_url=base_url)
- except Exception as exc:
- reason, moved = str(exc).splitlines()[0], provider_install_hint(provider or "")
- _fail_and_issue(f"auxiliary.{task}.provider '{provider}' does not resolve", f"({reason})",
- f"auxiliary.{task}.provider '{provider}' cannot be resolved ({reason}); the task silently runs "
- f"on the main model. " + (moved or f"Fix the provider name/credentials in auxiliary.{task}."),
- issues)
- continue
- if not runtime.get("api_key") and not runtime.get("command"):
- check_warn(f"auxiliary.{task}.provider '{provider}' resolved without credentials", f"({runtime.get('provider')} @ {runtime.get('base_url')})")
- continue
- ok.append(f"{task}→{runtime.get('provider')}@{base_url_hostname(str(runtime.get('base_url') or '')) or '?'}")
- if ok:
- check_ok("auxiliary task routing resolves: " + ", ".join(ok))
- @doctor_check()
- def _check_config_file(should_fix: bool, f: Finding) -> None:
- """config.yaml presence (project cli-config.yaml as fallback); model/provider validation."""
- from hermes_cli.config_backend import config_exists, get_config_backend
- from hermes_cli.doctor import HERMES_HOME, PROJECT_ROOT, _DHH
- config_path = HERMES_HOME / 'config.yaml'
- backend = get_config_backend()
- if not backend.supports_file_tooling() and not _check_config_backend(backend, HERMES_HOME, f):
- return
- if config_exists(config_path):
- if backend.supports_file_tooling():
- check_ok(f"{_DHH}/config.yaml exists")
- with warn_on_error("Could not validate model/provider config"):
- _validate_model_config(config_path, f.issues)
- with warn_on_error("Could not validate auxiliary task routing"):
- _validate_auxiliary_config(config_path, f.issues)
- elif (PROJECT_ROOT / 'cli-config.yaml').exists():
- check_ok("cli-config.yaml exists (in project directory)")
- elif should_fix:
- from hermes_cli.config import seed_config_file
- from_template = seed_config_file(config_path, PROJECT_ROOT / 'cli-config.yaml.example')
- check_ok(f"Created {_DHH}/config.yaml from {'cli-config.yaml.example' if from_template else 'defaults'}")
- f.fixed += 1
- else:
- check_warn("config.yaml not found", "(using defaults)")
- def _check_config_backend(backend, home, f: Finding) -> bool:
- """A backend without a config file (§4.7): report where config comes from instead of the file
- checks, plus the backend's own warnings (remote mode flags an ignored managed config.yaml, D18)."""
- try:
- backend.read_user_doc(home)
- check_ok(f"Config backend: {backend.describe(home)}")
- except SystemExit as exc: # ConfigBackendUnavailable: the plane cannot serve this profile
- check_fail(f"Config backend {backend.name!r} unavailable", str(exc.code or ""))
- f.issues.append(f"Config backend {backend.name!r} cannot serve config for {home}")
- return False
- for warning, hint, issue in backend.doctor_warnings(home):
- check_warn(warning, hint)
- f.issues.append(issue)
- return True
- def _drift_config_version(f: Finding, should_fix: bool, config_path) -> None:
- from hermes_cli.config import check_config_version, migrate_config
- current_ver, latest_ver = check_config_version()
- outdated = (f"Config version outdated (v{current_ver} → v{latest_ver})", "(new settings available)")
- if check_bool(current_ver >= latest_ver, f"Config version up to date (v{current_ver})", outdated):
- return
- if not should_fix:
- f.issues.append("Run 'hermes doctor --fix' or 'hermes setup' to migrate config")
- return
- try:
- migrate_config(interactive=False, quiet=False)
- check_ok("Config migrated to latest version")
- f.fixed += 1
- except Exception as mig_err:
- check_warn(f"Auto-migration failed: {mig_err}")
- f.issues.append("Run 'hermes setup' to migrate config")
- def _drift_stale_root_keys(f: Finding, should_fix: bool, config_path) -> None:
- """Root-level ``provider``/``base_url`` belong under ``model:`` (raw-file diagnostic)."""
- from hermes_cli.config import atomic_config_replace, read_user_config_raw
- raw_config = read_user_config_raw(config_path)
- stale_root_keys = [k for k in ("provider", "base_url") if k in raw_config and isinstance(raw_config[k], str)]
- if not stale_root_keys:
- return
- check_warn(f"Stale root-level config keys: {', '.join(stale_root_keys)}", "(should be under 'model:' section)")
- if not should_fix:
- f.issues.append("Stale root-level provider/base_url in config.yaml — run 'hermes doctor --fix'")
- return
- # Coerce scalar/None ``model:`` into a dict before mutation (setdefault would hand back a scalar).
- raw_model = raw_config.get("model")
- if not isinstance(raw_model, dict):
- raw_model = raw_config["model"] = {"default": raw_model.strip()} if isinstance(raw_model, str) and raw_model.strip() else {}
- for k in stale_root_keys:
- value = raw_config.pop(k)
- if not raw_model.get(k):
- raw_model[k] = value
- atomic_config_replace(config_path, raw_config)
- check_ok("Migrated stale root-level keys into model section")
- f.fixed += 1
- def _drift_max_iterations_ghost(f: Finding, should_fix: bool, config_path) -> None:
- """A stale HERMES_MAX_ITERATIONS in .env shadows agent.max_turns in config.yaml.
- The setup wizard used to dual-write the budget. The gateway bridge derives HERMES_MAX_ITERATIONS from
- agent.max_turns, but if it bails on an earlier config-parse error the .env value silently wins. Read the
- .env FILE (load_env), not get_env_value/os.environ, which the bridge may have overridden already.
- """
- from hermes_cli.doctor import _DHH
- # Detect stale HERMES_MAX_ITERATIONS ghost in .env shadowing agent.max_turns in config.yaml (issue
- # #17534). The setup wizard used to dual-write the iteration budget to both stores; users who later edit
- # only config.yaml are left with a .env ghost. The gateway bridge normally derives HERMES_MAX_ITERATIONS
- # from agent.max_turns at startup, but if that bridge bails (any earlier config-parse error), the stale
- # .env value silently wins and the agent runs at the wrong budget — e.g. config says 400 but the
- # activity line reads N/90.
- from hermes_cli.config import load_env, read_user_config_raw, remove_env_value
- raw_config = read_user_config_raw(config_path)
- agent_cfg = raw_config.get("agent")
- cfg_max_turns = agent_cfg.get("max_turns") if isinstance(agent_cfg, dict) else None
- if cfg_max_turns is None:
- cfg_max_turns = raw_config.get("max_turns") # legacy root-level key counts too
- env_ghost = load_env().get("HERMES_MAX_ITERATIONS")
- if cfg_max_turns is None or env_ghost is None or str(cfg_max_turns).strip() == str(env_ghost).strip():
- return
- check_warn(f"HERMES_MAX_ITERATIONS={env_ghost} in .env shadows agent.max_turns={cfg_max_turns} in config.yaml",
- "(stale ghost from an earlier `hermes setup` run)")
- if not should_fix:
- f.issues.append("Stale HERMES_MAX_ITERATIONS in .env shadows config.yaml — run 'hermes doctor --fix'")
- elif remove_env_value("HERMES_MAX_ITERATIONS"):
- check_ok(f"Removed stale HERMES_MAX_ITERATIONS from .env (config.yaml agent.max_turns={cfg_max_turns} is now authoritative)")
- f.fixed += 1
- else:
- check_warn("Could not remove HERMES_MAX_ITERATIONS from .env")
- f.manual_issues.append(f"Manually delete the HERMES_MAX_ITERATIONS line from {_DHH}/.env — config.yaml agent.max_turns is authoritative.")
- def _drift_deprecations(f: Finding, should_fix: bool, config_path) -> None:
- """Warn-only deprecation sweep over the raw file + on-disk .env (process env would false-positive)."""
- from hermes_cli.config import load_env, read_user_config_raw
- raw = read_user_config_raw(config_path) if config_path is not None else {}
- env = {}
- with warn_on_error(""):
- env = load_env()
- report_deprecated_config_and_env(raw, env)
- def _drift_structure(f: Finding, should_fix: bool, config_path) -> None:
- """Structural validation (malformed custom_providers, etc.)."""
- from hermes_cli.config import validate_config_structure
- config_issues = validate_config_structure()
- if not config_issues:
- return
- _section("Config Structure")
- for ci in config_issues:
- (check_fail if ci.severity == "error" else check_warn)(ci.message)
- for hint_line in ci.hint.splitlines():
- check_info(hint_line)
- f.issues.append(ci.message)
- def _endpoint_url(entry: dict) -> str:
- """Comparable endpoint URL of a legacy list entry (``base_url``/``url``) or a ``providers:`` entry (``api``)."""
- url = entry.get("api") or entry.get("base_url") or entry.get("url") or ""
- return str(url).strip().rstrip("/").lower()
- def _drift_legacy_custom_providers(f: Finding, should_fix: bool, config_path) -> None:
- """Legacy ``custom_providers`` list entries with no ``providers:`` twin (raw-file diagnostic).
- The v11→v12 migration (config_migrations._migrate_to_12) moves the list into ``providers:`` ONCE, at
- the version bump; an entry hand-written afterwards lives on in the retired list store (dual-read by the
- picker and the Custom Endpoints page) instead of the ``providers:`` map every other surface edits.
- """
- from hermes_cli.config import read_user_config_raw
- raw_config = read_user_config_raw(config_path)
- legacy = raw_config.get("custom_providers")
- if not isinstance(legacy, list):
- return
- providers = raw_config.get("providers")
- twins = {_endpoint_url(e) for e in (providers.values() if isinstance(providers, dict) else ()) if isinstance(e, dict)}
- for entry in legacy:
- if not isinstance(entry, dict) or not _endpoint_url(entry) or _endpoint_url(entry) in twins:
- continue
- label = str(entry.get("name") or "").strip() or _endpoint_url(entry)
- check_warn(f"Legacy custom_providers entry '{label}' has no providers: twin",
- "(still read from the retired list store; every other surface edits providers:)")
- f.manual_issues.append(
- f"Move custom_providers entry '{label}' into config.yaml providers: as `providers.<key>.api: "
- f"{_endpoint_url(entry)}` and delete it from the list — the v12 list migration ran once and does not re-fire")
- _CONFIG_DRIFT_STEPS = (
- _drift_config_version, _drift_stale_root_keys, _drift_max_iterations_ghost, _drift_deprecations, _drift_structure,
- _drift_legacy_custom_providers,
- )
- def _check_channel_record_hygiene() -> None:
- """Stale per-install channel records (``update.installs.<sha16>``).
- Same report-don't-delete posture as the state sweep. Three shapes
- (hermes_cli.update_channel.stale_channel_records): a record whose path
- holds a DIFFERENT install now (``replaced``), a record whose path is
- gone (``missing``), and a record no live install-state folder claims
- (``unclaimed``). Keep-on-doubt: doctor names the config key, the user
- removes it.
- """
- try:
- from hermes_cli.config import load_config
- from hermes_cli.update_channel import stale_channel_records
- stale = stale_channel_records(load_config() or {})
- except Exception as exc:
- check_warn("Channel-record hygiene unreadable", f"({exc})")
- return
- if not stale:
- return
- for sha16, record, reason in stale:
- recorded = record.get("path") or "<no path>"
- if reason == "replaced":
- detail = f"(the install at {recorded} is a different install now — stale channel entry)"
- elif reason == "missing":
- detail = f"(nothing at {recorded} — safe to remove update.installs.{sha16})"
- else: # unclaimed
- detail = f"(no live install claims {sha16} — safe to remove update.installs.{sha16})"
- check_warn(f"Stale channel record: {sha16}", detail)
- @doctor_check()
- def _check_config_drift(should_fix: bool, f: Finding) -> None:
- """Config version, stale root keys, HERMES_MAX_ITERATIONS ghost, deprecations, structure.
- Each step is independent and best-effort: a failure in one never hides the next.
- """
- from hermes_cli.config_backend import config_exists
- from hermes_cli.doctor import HERMES_HOME
- config_path = HERMES_HOME / 'config.yaml'
- if not config_exists(config_path):
- config_path = None
- for step in _CONFIG_DRIFT_STEPS if config_path else (_drift_deprecations,):
- with warn_on_error(""):
- step(f, should_fix, config_path)
- # Stale per-install update-channel records (update.installs.<sha16>):
- # report-don't-delete, same posture as the state sweep.
- _check_channel_record_hygiene()
- @doctor_check("xAI retirement check skipped", "({e})")
- def _check_xai_retirement(should_fix: bool, f: Finding) -> None:
- from hermes_cli.config import load_config
- from hermes_cli.xai_retirement import MIGRATION_GUIDE_URL, find_retired_xai_refs, format_issue
- retired_refs = find_retired_xai_refs(load_config())
- if not retired_refs:
- check_ok("No retired xAI models in config")
- return
- for ref in retired_refs:
- check_warn(format_issue(ref))
- check_info(f"Migration guide: {MIGRATION_GUIDE_URL}")
- f.manual_issues.append(f"Update {len(retired_refs)} retired xAI model reference(s) in config.yaml — see {MIGRATION_GUIDE_URL}")
- @doctor_check("Session reset check skipped", "({e})")
- def _check_retired_session_reset(should_fix: bool, f: Finding) -> None:
- from hermes_cli.config_effective import load_user_config_effective
- from hermes_cli.session_reset_retirement import format_notice, reset_plugin_enabled, retired_reset_policy
- found = retired_reset_policy(load_user_config_effective())
- if found is None:
- check_ok("No idle/daily session_reset policy configured")
- elif reset_plugin_enabled():
- check_ok(f"{found[0]}.mode: {found[1]} is applied by the session reset plugin")
- else:
- check_warn(format_notice(*found))
- f.manual_issues.append(format_notice(*found))
|