feat(xai): detect retired xAI models (May 15, 2026) in doctor + chat startup

hermes_cli/doctor.py

@@ -657,6 +657,35 @@ def run_doctor(args):
         except Exception:
             pass
 
+    # =========================================================================
+    # Check: xAI model retirement (May 15, 2026)
+    # =========================================================================
+    print()
+    print(color("◆ xAI Model Retirement (May 15, 2026)", Colors.CYAN, Colors.BOLD))
+
+    try:
+        from hermes_cli.config import load_config
+        from hermes_cli.xai_retirement import (
+            MIGRATION_GUIDE_URL,
+            find_retired_xai_refs,
+            format_issue,
+        )
+
+        _xai_cfg = load_config()
+        retired_refs = find_retired_xai_refs(_xai_cfg)
+        if not retired_refs:
+            check_ok("No retired xAI models in config")
+        else:
+            for ref in retired_refs:
+                check_warn(format_issue(ref))
+            check_info(f"Migration guide: {MIGRATION_GUIDE_URL}")
+            manual_issues.append(
+                f"Update {len(retired_refs)} retired xAI model reference(s) "
+                f"in config.yaml — see {MIGRATION_GUIDE_URL}"
+            )
+    except Exception as _xai_check_err:
+        check_warn("xAI retirement check skipped", f"({_xai_check_err})")
+
     # =========================================================================
     # Check: Auth providers
     # =========================================================================

hermes_cli/main.py

@@ -1380,6 +1380,29 @@ def cmd_chat(args):
         # If resolution fails, keep the original value — _init_agent will
         # report "Session not found" with the original input
 
+    # xAI retirement warning — one-shot, non-blocking, never fails startup
+    try:
+        from hermes_cli.xai_retirement import (
+            MIGRATION_GUIDE_URL,
+            RETIREMENT_DATE,
+            find_retired_xai_refs,
+            format_issue,
+        )
+        from hermes_cli.config import load_config as _load_config_for_xai_check
+
+        _retired_xai_refs = find_retired_xai_refs(_load_config_for_xai_check())
+        if _retired_xai_refs:
+            sys.stderr.write(
+                f"\033[33m⚠ xAI retires {len(_retired_xai_refs)} model(s) "
+                f"in your config on {RETIREMENT_DATE}:\033[0m\n"
+            )
+            for _ref in _retired_xai_refs:
+                sys.stderr.write(f"  \033[33m⚠\033[0m {format_issue(_ref)}\n")
+            sys.stderr.write(f"  \033[2mMigration guide: {MIGRATION_GUIDE_URL}\033[0m\n")
+            sys.stderr.write("  \033[2mRun 'hermes doctor' for details.\033[0m\n\n")
+    except Exception:
+        pass
+
     # First-run guard: check if any provider is configured before launching
     if not _has_any_provider_configured():
         print()

hermes_cli/xai_retirement.py

@@ -0,0 +1,132 @@
+"""Detect xAI models retired on May 15, 2026.
+
+Source: https://docs.x.ai/developers/migration/may-15-retirement
+
+Pure logic: walks a Hermes config dict, returns issues for any reference
+to a retired xAI model. No I/O, no CLI dependencies — testable in isolation
+and reusable from both `hermes doctor` and a future `hermes migrate xai`.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+MIGRATION_GUIDE_URL = "https://docs.x.ai/developers/migration/may-15-retirement"
+RETIREMENT_DATE = "May 15, 2026"
+
+
+# Official mapping per xAI migration guide.
+# Some entries set ``reasoning_effort`` because non-reasoning variants don't
+# have a one-to-one replacement: ``grok-4.3`` reasons by default, so emulating
+# ``*-non-reasoning`` behavior on it requires ``reasoning_effort="none"``.
+_RETIRED_MODELS: Dict[str, Dict[str, Optional[str]]] = {
+    "grok-4-0709":                  {"replacement": "grok-4.3", "reasoning_effort": None,  "note": None},
+    "grok-4-fast-reasoning":        {"replacement": "grok-4.3", "reasoning_effort": None,  "note": None},
+    "grok-4-fast-non-reasoning":    {"replacement": "grok-4.3", "reasoning_effort": "none", "note": None},
+    "grok-4-1-fast-reasoning":      {"replacement": "grok-4.3", "reasoning_effort": None,  "note": None},
+    "grok-4-1-fast-non-reasoning":  {"replacement": "grok-4.3", "reasoning_effort": "none", "note": None},
+    "grok-code-fast-1":             {"replacement": "grok-4.3", "reasoning_effort": None,  "note": None},
+    "grok-3":                       {"replacement": "grok-4.3", "reasoning_effort": None,  "note": None},
+    "grok-imagine-image-pro":       {"replacement": "grok-imagine-image-quality", "reasoning_effort": None, "note": None},
+}
+
+
+@dataclass(frozen=True)
+class RetirementIssue:
+    """A reference to a retired xAI model found in a Hermes config."""
+
+    config_path: str            # e.g. "principal.model" or "auxiliary.vision.model"
+    current_model: str          # exact value found in config (preserves casing/prefix)
+    replacement: str            # recommended xAI replacement
+    reasoning_effort: Optional[str] = None  # set if non-reasoning variant migration
+    note: Optional[str] = None  # disambiguation note when applicable
+
+
+def _normalize(model_id: str) -> str:
+    """Strip provider prefix (``x-ai/grok-4`` → ``grok-4``) and lowercase."""
+    m = model_id.strip().lower()
+    for prefix in ("x-ai/", "xai/"):
+        if m.startswith(prefix):
+            m = m[len(prefix):]
+            break
+    return m
+
+
+def _looks_like_xai(model_id: Optional[str]) -> bool:
+    if not isinstance(model_id, str) or not model_id.strip():
+        return False
+    return _normalize(model_id).startswith("grok-")
+
+
+def find_retired_xai_refs(config: Dict[str, Any]) -> List[RetirementIssue]:
+    """Walk all model slots in a Hermes config and return retirement issues.
+
+    Slots scanned:
+      - ``principal.model``
+      - ``auxiliary.<any>.model`` (introspective — covers future aux slots)
+      - ``delegation.model``
+      - ``tts.xai.model``
+      - ``plugins.image_gen.xai.model``
+    """
+    issues: List[RetirementIssue] = []
+
+    def _check(path: str, model: Any) -> None:
+        if not _looks_like_xai(model):
+            return
+        norm = _normalize(model)
+        entry = _RETIRED_MODELS.get(norm)
+        if entry is None:
+            return
+        issues.append(RetirementIssue(
+            config_path=path,
+            current_model=model,
+            replacement=entry["replacement"],
+            reasoning_effort=entry.get("reasoning_effort"),
+            note=entry.get("note"),
+        ))
+
+    if not isinstance(config, dict):
+        return issues
+
+    principal = config.get("principal")
+    if isinstance(principal, dict):
+        _check("principal.model", principal.get("model"))
+
+    aux = config.get("auxiliary")
+    if isinstance(aux, dict):
+        for slot_name, slot_cfg in aux.items():
+            if isinstance(slot_cfg, dict):
+                _check(f"auxiliary.{slot_name}.model", slot_cfg.get("model"))
+
+    delegation = config.get("delegation")
+    if isinstance(delegation, dict):
+        _check("delegation.model", delegation.get("model"))
+
+    tts = config.get("tts")
+    if isinstance(tts, dict):
+        tts_xai = tts.get("xai")
+        if isinstance(tts_xai, dict):
+            _check("tts.xai.model", tts_xai.get("model"))
+
+    plugins = config.get("plugins")
+    if isinstance(plugins, dict):
+        image_gen = plugins.get("image_gen")
+        if isinstance(image_gen, dict):
+            ig_xai = image_gen.get("xai")
+            if isinstance(ig_xai, dict):
+                _check("plugins.image_gen.xai.model", ig_xai.get("model"))
+
+    return issues
+
+
+def format_issue(issue: RetirementIssue) -> str:
+    """One-line human-readable rendering of a retirement issue."""
+    parts = [
+        f"{issue.config_path}: {issue.current_model!r} → use {issue.replacement!r}"
+    ]
+    if issue.reasoning_effort:
+        parts.append(f'(set reasoning_effort: "{issue.reasoning_effort}")')
+    if issue.note:
+        parts.append(f"[note: {issue.note}]")
+    return " ".join(parts)