feat(azure-foundry): add Microsoft Entra ID auth

Use azure-identity DefaultAzureCredential for keyless Foundry auth.

Preserve refreshable callable credentials through OpenAI and Anthropic client paths.

Add setup, doctor, auth status, docs, and tests for Entra auth.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

agent/agent_init.py

@@ -560,7 +560,16 @@ def init_agent(
             agent._client_kwargs = {}
             if not agent.quiet_mode:
                 print(f"🤖 AI Agent initialized with model: {agent.model} (Anthropic native)")
-                if effective_key and len(effective_key) > 12:
+                # ``effective_key`` may be a callable Entra ID bearer
+                # provider for Azure Foundry anthropic_messages mode.
+                # The Anthropic adapter installs an httpx event hook
+                # that mints a fresh JWT per request — we never
+                # invoke or inspect the callable in the banner.
+                from agent.azure_identity_adapter import is_token_provider
+
+                if is_token_provider(effective_key):
+                    print("🔑 Using credentials: Microsoft Entra ID")
+                elif isinstance(effective_key, str) and len(effective_key) > 12:
                     print(f"🔑 Using token: {effective_key[:8]}...{effective_key[-4:]}")
     elif agent.api_mode == "bedrock_converse":
         # AWS Bedrock — uses boto3 directly, no OpenAI client needed.
@@ -764,12 +773,19 @@ def init_agent(
                 print(f"🤖 AI Agent initialized with model: {agent.model}")
                 if base_url:
                     print(f"🔗 Using custom base URL: {base_url}")
-                # Always show API key info (masked) for debugging auth issues
+                # ``api_key`` may be a callable Entra ID bearer
+                # provider (Azure Foundry). The OpenAI SDK mints a
+                # fresh JWT per request internally — the banner
+                # never invokes or inspects the callable.
+                from agent.azure_identity_adapter import is_token_provider
+
                 key_used = client_kwargs.get("api_key", "none")
-                if key_used and key_used != "dummy-key" and len(key_used) > 12:
+                if is_token_provider(key_used):
+                    print("🔑 Using credentials: Microsoft Entra ID")
+                elif isinstance(key_used, str) and 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'}...')")
+                    print("⚠️  Warning: API key appears invalid or missing")
         except Exception as e:
             raise RuntimeError(f"Failed to initialize OpenAI client: {e}")
     
@@ -1395,7 +1411,12 @@ def init_agent(
             _ra().logger.debug("Invalid ollama_num_ctx config value: %r", _ollama_num_ctx_override)
     if agent._ollama_num_ctx is None and agent.base_url and is_local_endpoint(agent.base_url):
         try:
-            _detected = query_ollama_num_ctx(agent.model, agent.base_url, api_key=agent.api_key or "")
+            # ``agent.api_key`` may be a callable (Entra token provider).
+            # Ollama detection makes a manual HTTP request and expects a
+            # string — Azure Foundry isn't a local endpoint so this branch
+            # never fires for Entra, but guard defensively.
+            _key_for_ollama = agent.api_key if isinstance(agent.api_key, str) else ""
+            _detected = query_ollama_num_ctx(agent.model, agent.base_url, api_key=_key_for_ollama or "")
             if _detected and _detected > 0:
                 agent._ollama_num_ctx = _detected
         except Exception as exc:

agent/agent_runtime_helpers.py

@@ -1390,10 +1390,16 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
             _sm_custom_providers = get_compatible_custom_providers(_sm_cfg)
         except Exception:
             _sm_custom_providers = None
+        # ``agent.api_key`` may be a callable (Azure Foundry Entra ID
+        # token provider). ``get_model_context_length`` expects a
+        # string for its live-probe paths; for Foundry the context
+        # length normally resolves via config or static catalogs and
+        # never hits a probe, but coerce to empty string defensively.
+        _ctx_api_key = agent.api_key if isinstance(agent.api_key, str) else ""
         new_context_length = get_model_context_length(
             agent.model,
             base_url=agent.base_url,
-            api_key=agent.api_key,
+            api_key=_ctx_api_key,
             provider=agent.provider,
             config_context_length=getattr(agent, "_config_context_length", None),
             custom_providers=_sm_custom_providers,
@@ -1402,7 +1408,7 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
             model=agent.model,
             context_length=new_context_length,
             base_url=agent.base_url,
-            api_key=getattr(agent, "api_key", ""),
+            api_key=agent.api_key,  # context_compressor forwards to call_llm; callable preserved
             provider=agent.provider,
             api_mode=agent.api_mode,
         )

agent/anthropic_adapter.py

@@ -17,6 +17,7 @@ import os
 import platform
 import subprocess
 from pathlib import Path
+from urllib.parse import urlparse
 
 from hermes_constants import get_hermes_home
 from typing import Any, Dict, List, Optional, Tuple
@@ -364,7 +365,7 @@ def _normalize_base_url_text(base_url) -> str:
 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
+    Third-party proxies (Microsoft 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.
     """
@@ -508,6 +509,29 @@ def _is_minimax_anthropic_endpoint(base_url: str | None) -> bool:
     )
 
 
+def _is_azure_anthropic_endpoint(base_url: str | None) -> bool:
+    """Return True for Azure-hosted Anthropic Messages endpoints.
+
+    Covers both the modern Foundry host family (``*.services.ai.azure.*``)
+    and the legacy Azure OpenAI host family (``*.openai.azure.*``) when
+    serving Anthropic's ``/anthropic`` route. Used to opt-in those hosts
+    to the ``api-version`` query-param plumbing required by Azure.
+
+    Intentionally avoids a finite allow-list of TLD suffixes so it works
+    across sovereign / private Azure clouds.
+    """
+    normalized = _normalize_base_url_text(base_url)
+    if not normalized:
+        return False
+    parsed = urlparse(normalized)
+    host = (parsed.hostname or "").lower().rstrip(".")
+    path = (parsed.path or "").lower()
+    host_padded = f".{host}."
+    is_foundry_host = ".services.ai.azure." in host_padded
+    is_legacy_azoai_host = ".openai.azure." in host_padded
+    return (is_foundry_host or is_legacy_azoai_host) and "/anthropic" in path
+
+
 def _common_betas_for_base_url(
     base_url: str | None,
     *,
@@ -523,7 +547,7 @@ def _common_betas_for_base_url(
 
     The ``context-1m-2025-08-07`` beta is not sent to native Anthropic by
     default because some subscriptions reject it. Add it only for endpoint
-    families that still require it for 1M context, currently Azure AI Foundry.
+    families that still require it for 1M context, currently Microsoft Foundry.
     Bedrock uses its own client helper below and opts in explicitly.
 
     ``drop_context_1m_beta=True`` strips the 1M-context beta from any path that
@@ -540,8 +564,81 @@ def _common_betas_for_base_url(
     return betas
 
 
+def _build_anthropic_client_with_bearer_hook(
+    token_provider,
+    base_url: str = None,
+    timeout: float = None,
+    *,
+    drop_context_1m_beta: bool = False,
+):
+    """Anthropic-on-Foundry Entra ID variant of :func:`build_anthropic_client`.
+
+    Anthropic SDK 0.86.0 stores ``api_key`` / ``auth_token`` as static
+    strings; there is no callable-token contract. To get per-request
+    bearer refresh (Microsoft's documented Foundry pattern), we hand
+    the SDK a custom ``httpx.Client`` whose request event hook mints a
+    fresh JWT from the Entra credential chain and rewrites
+    ``Authorization: Bearer <jwt>`` on every outbound request. The SDK
+    ignores its own auth logic when ``http_client`` is provided (the
+    hook strips any pre-set Authorization).
+
+    The placeholder ``auth_token`` is required because the SDK raises
+    ``AnthropicError`` at construction if neither ``api_key`` nor
+    ``auth_token`` is set — but the hook overrides it per-request so
+    the placeholder value never reaches Azure.
+    """
+    _anthropic_sdk = _get_anthropic_sdk()
+    if _anthropic_sdk is None:
+        raise ImportError(
+            "The 'anthropic' package is required for Azure Foundry Anthropic-style "
+            "endpoints with Entra ID auth. Install with: pip install 'anthropic>=0.39.0'"
+        )
+
+    normalize_proxy_env_vars()
+
+    from httpx import Timeout
+    from agent.azure_identity_adapter import build_bearer_http_client
+
+    _read_timeout = timeout if (isinstance(timeout, (int, float)) and timeout > 0) else 900.0
+    timeout_obj = Timeout(timeout=float(_read_timeout), connect=10.0)
+
+    # Strip any trailing /v1 — the Anthropic SDK appends /v1/messages.
+    normalized_base_url = _normalize_base_url_text(base_url)
+    if normalized_base_url:
+        import re as _re
+        normalized_base_url = _re.sub(r"/v1/?$", "", normalized_base_url.rstrip("/"))
+
+    http_client = build_bearer_http_client(token_provider, timeout=timeout_obj)
+
+    kwargs = {
+        "timeout": timeout_obj,
+        "http_client": http_client,
+        # The SDK requires *something* for api_key/auth_token. Our
+        # event hook overrides Authorization per request so this value
+        # is never sent. The sentinel string makes accidental leaks
+        # diagnosable in logs.
+        "auth_token": "entra-id-bearer-via-http-hook",
+    }
+
+    if normalized_base_url:
+        if _is_azure_anthropic_endpoint(normalized_base_url) and "api-version" not in normalized_base_url:
+            kwargs["base_url"] = normalized_base_url
+            kwargs["default_query"] = {"api-version": "2025-04-15"}
+        else:
+            kwargs["base_url"] = normalized_base_url
+
+    common_betas = _common_betas_for_base_url(
+        normalized_base_url,
+        drop_context_1m_beta=drop_context_1m_beta,
+    )
+    if common_betas:
+        kwargs["default_headers"] = {"anthropic-beta": ",".join(common_betas)}
+
+    return _anthropic_sdk.Anthropic(**kwargs)
+
+
 def build_anthropic_client(
-    api_key: str,
+    api_key,
     base_url: str = None,
     timeout: float = None,
     *,
@@ -549,6 +646,17 @@ def build_anthropic_client(
 ):
     """Create an Anthropic client, auto-detecting setup-tokens vs API keys.
 
+    ``api_key`` accepts either:
+
+    * a static ``str`` — the historical contract for all key-based and
+      OAuth flows.
+    * a ``Callable[[], str]`` — an Entra ID bearer token provider from
+      :mod:`agent.azure_identity_adapter`. The Anthropic SDK itself
+      requires a static string, so when given a callable we construct
+      a custom ``httpx.Client`` with a request event hook that mints a
+      fresh JWT per outbound request and rewrites the ``Authorization``
+      header. The SDK never sees the callable directly.
+
     If *timeout* is provided it overrides the default 900s read timeout.  The
     connect timeout stays at 10s.  Callers pass this from the per-provider /
     per-model ``request_timeout_seconds`` config so Anthropic-native and
@@ -570,6 +678,14 @@ def build_anthropic_client(
             "Install it with: pip install 'anthropic>=0.39.0'"
         )
 
+    # Callable api_key → Entra ID bearer provider path. Delegated to a
+    # helper so the existing static-key code below stays unchanged.
+    if callable(api_key) and not isinstance(api_key, str):
+        return _build_anthropic_client_with_bearer_hook(
+            api_key, base_url, timeout,
+            drop_context_1m_beta=drop_context_1m_beta,
+        )
+
     normalize_proxy_env_vars()
 
     from httpx import Timeout
@@ -584,8 +700,7 @@ def build_anthropic_client(
         # Pass it via default_query so the SDK appends it to every request URL
         # without corrupting the base_url (appending it directly produces
         # malformed paths like /anthropic?api-version=.../v1/messages).
-        _is_azure_endpoint = "azure.com" in normalized_base_url.lower()
-        if _is_azure_endpoint and "api-version" not in normalized_base_url:
+        if _is_azure_anthropic_endpoint(normalized_base_url) and "api-version" not in normalized_base_url:
             kwargs["base_url"] = normalized_base_url.rstrip("/")
             kwargs["default_query"] = {"api-version": "2025-04-15"}
         else:
@@ -615,7 +730,7 @@ def build_anthropic_client(
         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
+        # Third-party proxies (Microsoft 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.
@@ -1757,7 +1872,7 @@ def convert_messages_to_anthropic(
     # causing HTTP 400 "Invalid signature in thinking block".
     #
     # Signatures are Anthropic-proprietary.  Third-party endpoints
-    # (MiniMax, Azure AI Foundry, self-hosted proxies) cannot validate
+    # (MiniMax, Microsoft 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
@@ -2103,5 +2218,3 @@ def build_anthropic_kwargs(
         kwargs["extra_headers"] = {"anthropic-beta": ",".join(betas)}
 
     return kwargs
-
-

agent/auxiliary_client.py

@@ -1902,6 +1902,120 @@ def _build_codex_client(model: str) -> Tuple[Optional[Any], Optional[str]]:
     return CodexAuxiliaryClient(real_client, model), model
 
 
+def _try_azure_foundry(
+    *,
+    model: Optional[str] = None,
+    explicit_api_key: Optional[str] = None,
+    explicit_base_url: Optional[str] = None,
+    api_mode: Optional[str] = None,
+) -> Tuple[Optional[Any], Optional[str]]:
+    """Resolve an Azure Foundry auxiliary client via the runtime resolver.
+
+    Mirrors the ``_try_anthropic`` / ``_try_nous`` shape but delegates to
+    :func:`hermes_cli.runtime_provider._resolve_azure_foundry_runtime` —
+    the same resolver the main agent uses — so:
+
+    * ``auth_mode: api_key`` (default) gets the static
+      ``AZURE_FOUNDRY_API_KEY`` string.
+    * ``auth_mode: entra_id`` gets a callable bearer-token provider
+      (``Callable[[], str]`` from
+      :mod:`agent.azure_identity_adapter`).
+    * Per-model ``api_mode`` auto-routing for GPT-5.x / o-series /
+      codex models works.
+    * ``model.entra.{tenant_id,client_id,authority,scope}`` config
+      fields propagate.
+    * Non-default ``model.base_url`` overrides are honored.
+
+    The OpenAI SDK accepts both shapes for ``api_key`` so the caller
+    can forward the result without coercion.
+
+    Returns ``(client, model)`` or ``(None, None)`` on failure.
+    """
+    try:
+        from hermes_cli.runtime_provider import _resolve_azure_foundry_runtime
+        from hermes_cli.auth import AuthError
+        from hermes_cli.config import load_config
+    except ImportError:
+        return None, None
+
+    try:
+        cfg = load_config()
+        model_cfg = cfg.get("model") if isinstance(cfg, dict) else {}
+        if not isinstance(model_cfg, dict):
+            model_cfg = {}
+    except Exception:
+        model_cfg = {}
+
+    try:
+        runtime = _resolve_azure_foundry_runtime(
+            requested_provider="azure-foundry",
+            model_cfg=model_cfg,
+            explicit_api_key=explicit_api_key,
+            explicit_base_url=explicit_base_url,
+            target_model=model,
+        )
+    except AuthError as exc:
+        logger.debug("Auxiliary azure-foundry: %s", exc)
+        return None, None
+    except Exception as exc:
+        logger.debug("Auxiliary azure-foundry runtime error: %s", exc)
+        return None, None
+
+    api_key = runtime.get("api_key")
+    base_url = str(runtime.get("base_url", "") or "")
+    runtime_api_mode = api_mode or runtime.get("api_mode") or "chat_completions"
+
+    # Empty-string check on api_key here would be wrong for callable
+    # token providers (callables are truthy and non-empty by definition).
+    # Bail only when api_key is None / empty string.
+    _has_key = bool(api_key) if not callable(api_key) else True
+    if not _has_key or not base_url:
+        return None, None
+
+    final_model = _normalize_resolved_model(
+        model or str(model_cfg.get("default") or ""),
+        "azure-foundry",
+    )
+    if not final_model:
+        # No fallback aux model for Azure — the user must have a
+        # deployment name. Surface that as "no client" so the auto
+        # chain falls through to the next provider rather than 404ing.
+        logger.debug(
+            "Auxiliary azure-foundry: no model resolved (model=%r, default=%r)",
+            model, model_cfg.get("default"),
+        )
+        return None, None
+
+    # Azure pre-v1 endpoints sometimes carry api-version query params
+    # in the base URL; the OpenAI SDK drops them when joining paths,
+    # so lift them out and pass via default_query.
+    extra: Dict[str, Any] = {}
+    _clean_base, _dq = _extract_url_query_params(base_url)
+    if _dq:
+        extra["default_query"] = _dq
+
+    client = OpenAI(api_key=api_key, base_url=_clean_base, **extra)
+
+    if runtime_api_mode == "codex_responses":
+        # GPT-5.x / o-series / codex models on Azure Foundry are
+        # Responses-API-only — wrap so chat.completions.create() is
+        # translated to /responses behind the scenes.
+        return CodexAuxiliaryClient(client, final_model), final_model
+
+    if runtime_api_mode == "anthropic_messages":
+        # Forward ``api_key`` verbatim — for static keys it's a string,
+        # for Entra ID it's a callable. ``_maybe_wrap_anthropic`` →
+        # ``build_anthropic_client`` detects the callable and installs
+        # the bearer-injecting httpx hook.
+        return _maybe_wrap_anthropic(
+            client, final_model, api_key,
+            base_url, runtime_api_mode,
+        ), final_model
+
+    # chat_completions — return the plain OpenAI client.
+    return client, final_model
+
+
 def _try_anthropic(explicit_api_key: str = None) -> Tuple[Optional[Any], Optional[str]]:
     try:
         from agent.anthropic_adapter import build_anthropic_client, resolve_anthropic_token
@@ -1957,20 +2071,31 @@ _AUTO_PROVIDER_LABELS = {
     "_resolve_api_key_provider": "api-key",
 }
 
-_MAIN_RUNTIME_FIELDS = ("provider", "model", "base_url", "api_key", "api_mode")
+_MAIN_RUNTIME_FIELDS = ("provider", "model", "base_url", "api_key", "api_mode", "auth_mode")
 
 
-def _normalize_main_runtime(main_runtime: Optional[Dict[str, Any]]) -> Dict[str, str]:
-    """Return a sanitized copy of a live main-runtime override."""
+def _normalize_main_runtime(main_runtime: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """Return a sanitized copy of a live main-runtime override.
+
+    Most fields are stripped strings. ``api_key`` may legitimately be a
+    zero-arg callable (Azure Foundry Entra ID token provider) — preserve
+    those as-is so auxiliary clients inherit the same authentication
+    surface as the main agent. The OpenAI SDK accepts ``Callable[[], str]``
+    for ``api_key`` and calls it before every request.
+    """
     if not isinstance(main_runtime, dict):
         return {}
-    normalized: Dict[str, str] = {}
+    normalized: Dict[str, Any] = {}
     for field in _MAIN_RUNTIME_FIELDS:
         value = main_runtime.get(field)
+        # Preserve a callable api_key (Entra ID bearer provider) unchanged.
+        if field == "api_key" and callable(value) and not isinstance(value, str):
+            normalized[field] = value
+            continue
         if isinstance(value, str) and value.strip():
             normalized[field] = value.strip()
     provider = normalized.get("provider")
-    if provider:
+    if isinstance(provider, str):
         normalized["provider"] = provider.lower()
     return normalized
 
@@ -2762,10 +2887,10 @@ def _resolve_auto(main_runtime: Optional[Dict[str, Any]] = None) -> Tuple[Option
     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_model = str(runtime.get("model") or "")
+    runtime_base_url = str(runtime.get("base_url") or "")
     runtime_api_key = runtime.get("api_key", "")
-    runtime_api_mode = runtime.get("api_mode", "")
+    runtime_api_mode = str(runtime.get("api_mode") or "")
 
     # ── Warn once if OPENAI_BASE_URL is set but config.yaml uses a named
     #    provider (not 'custom').  This catches the common "env poisoning"
@@ -2793,8 +2918,8 @@ def _resolve_auto(main_runtime: Optional[Dict[str, Any]] = None) -> Tuple[Option
     # on aggregators (OpenRouter, Nous) who previously got routed to a
     # cheap provider-side default.  Explicit per-task overrides set via
     # config.yaml (auxiliary.<task>.provider) still win over this.
-    main_provider = runtime_provider or _read_main_provider()
-    main_model = runtime_model or _read_main_model()
+    main_provider = str(runtime_provider or _read_main_provider() or "")
+    main_model = str(runtime_model or _read_main_model() or "")
     if (main_provider and main_model
             and main_provider not in {"auto", ""}):
         resolved_provider = main_provider
@@ -3188,7 +3313,11 @@ def resolve_provider_client(
             if client is not None:
                 final_model = _normalize_resolved_model(model or default, provider)
                 _cbase = str(getattr(client, "base_url", "") or "")
-                _ckey = str(getattr(client, "api_key", "") or "")
+                # ``client.api_key`` may be a callable (Azure Foundry Entra
+                # bearer provider). Pass empty string for the wrapper-detection
+                # path — wrapping decisions are based on base_url + api_mode.
+                _raw_ckey = getattr(client, "api_key", "")
+                _ckey = "" if (callable(_raw_ckey) and not isinstance(_raw_ckey, str)) else str(_raw_ckey or "")
                 client = _wrap_if_needed(client, final_model, _cbase, _ckey)
                 return (_to_async_client(client, final_model, is_vision=is_vision) if async_mode
                         else (client, final_model))
@@ -3300,6 +3429,40 @@ def resolve_provider_client(
     except ImportError:
         pass
 
+    # ── Azure Foundry (delegates to runtime resolver for auth_mode-aware routing) ─
+    #
+    # The generic PROVIDER_REGISTRY path below uses
+    # ``resolve_api_key_provider_credentials`` which only knows about the
+    # static ``AZURE_FOUNDRY_API_KEY`` env var. That misses two important
+    # cases for the ``azure-foundry`` provider:
+    #
+    #   1. ``model.auth_mode: entra_id`` — no static key exists; we need
+    #      a callable bearer-token provider from ``azure_identity_adapter``.
+    #   2. Non-default ``model.base_url`` (Foundry projects path) — the
+    #      env-var-only resolver doesn't apply config-yaml-driven URL
+    #      overrides.
+    #
+    # Delegate to the same runtime resolver the main agent uses so
+    # auxiliary tasks (title generation, compression, vision, embedding,
+    # session search) inherit the user's full Azure config.
+    if provider == "azure-foundry":
+        client, default_model = _try_azure_foundry(
+            model=model,
+            explicit_api_key=explicit_api_key,
+            explicit_base_url=explicit_base_url,
+            api_mode=api_mode,
+        )
+        if client is None:
+            logger.warning(
+                "resolve_provider_client: azure-foundry requested but "
+                "runtime resolution failed (run: hermes doctor for "
+                "diagnostics)"
+            )
+            return None, None
+        final_model = _normalize_resolved_model(model or default_model, provider)
+        return (_to_async_client(client, final_model, is_vision=is_vision) if async_mode
+                else (client, final_model))
+
     # ── API-key providers from PROVIDER_REGISTRY ─────────────────────
     try:
         from hermes_cli.auth import (

agent/azure_identity_adapter.py

@@ -0,0 +1,555 @@
+"""Microsoft Entra ID adapter for Microsoft Foundry.
+
+Provides keyless authentication for Microsoft Foundry deployments using the
+`azure-identity` SDK's `DefaultAzureCredential` chain (env service principal
+→ workload identity → managed identity → VS Code → Azure CLI → azd →
+PowerShell → broker).
+
+Architecture mirrors `agent/bedrock_adapter.py`:
+
+* Lazy import. `azure-identity` is only loaded when ``model.auth_mode =
+  entra_id`` is selected. Users who stick with `AZURE_FOUNDRY_API_KEY`
+  never pay the import cost.
+* SDK-callable contract. The public entry point ``build_token_provider``
+  returns a zero-arg callable produced by ``get_bearer_token_provider`` —
+  this is exactly the value Microsoft's documented sample plugs into
+  ``OpenAI(api_key=token_provider, base_url=...)``. The OpenAI SDK calls
+  it before every request, so token refresh is transparent.
+* Three explicit consumer-side helpers (display / cache / http-bearer)
+  rather than one generic "materialize" function — splitting them by
+  purpose prevents accidental token-minting in logging paths or token
+  leakage into cache keys / dashboard JSON.
+* No persisted JWT. ``azure-identity`` caches in-process and (where
+  available) in the OS keychain or ``~/.IdentityService``. Hermes does
+  not duplicate that storage in ``auth.json``.
+
+Reference: https://learn.microsoft.com/azure/ai-foundry/foundry-models/how-to/configure-entra-id
+
+Requires: ``azure-identity`` (optional dependency — only needed when
+``model.auth_mode = entra_id``).
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import os
+import threading
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+# Microsoft-documented scope for Foundry inference auth. Both the new
+# Foundry portal and the legacy Azure OpenAI managed-identity docs use
+# this scope for ALL Foundry endpoint shapes (*.openai.azure.com,
+# *.services.ai.azure.com, *.ai.azure.com). The older control-plane
+# scope ``https://cognitiveservices.azure.com/.default`` is for ARM
+# resource management and is rejected for inference by newer
+# resources — users with that requirement override via
+# ``model.entra.scope`` in config.yaml.
+SCOPE_AI_AZURE_DEFAULT = "https://ai.azure.com/.default"
+
+# ---------------------------------------------------------------------------
+# Lazy SDK import — only loaded when the Entra path is actually used.
+# ---------------------------------------------------------------------------
+
+_AZURE_IDENTITY_FEATURE = "provider.azure_identity"
+
+
+def has_azure_identity_installed() -> bool:
+    """Return True if `azure-identity` can be imported right now.
+
+    Cheap check — does not walk the credential chain.
+    """
+    try:
+        import azure.identity  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+
+def _require_azure_identity():
+    """Import ``azure.identity``, lazy-installing it if allowed.
+
+    Raises ``ImportError`` with a clear actionable message when the
+    package is missing and lazy installs are disabled.
+    """
+    try:
+        import azure.identity as _ai
+        return _ai
+    except ImportError:
+        try:
+            from tools.lazy_deps import ensure, FeatureUnavailable
+        except ImportError as exc:
+            raise ImportError(
+                "The 'azure-identity' package is required for Azure AI "
+                "Foundry Entra ID authentication. Install it with: "
+                "pip install azure-identity"
+            ) from exc
+
+        try:
+            ensure(_AZURE_IDENTITY_FEATURE, prompt=False)
+        except FeatureUnavailable as exc:
+            raise ImportError(
+                "The 'azure-identity' package is required for Azure AI "
+                "Foundry Entra ID authentication. " + str(exc)
+            ) from exc
+
+        # Retry import after lazy install.
+        import azure.identity as _ai  # noqa: WPS440
+        return _ai
+
+
+def reset_credential_cache() -> None:
+    """Clear the cached ``DefaultAzureCredential``. Used by tests and
+    profile switches.
+
+    Defensive against tests that ``monkeypatch.setattr`` over
+    ``build_credential`` with a plain (non-lru-cached) function — those
+    won't expose ``cache_clear()`` until pytest reverts the patch.
+    """
+    cache_clear = getattr(build_credential, "cache_clear", None)
+    if callable(cache_clear):
+        cache_clear()
+
+
+# ---------------------------------------------------------------------------
+# Token-provider construction
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class EntraIdentityConfig:
+    """Serializable Entra ID config.
+
+    Captures the Hermes-managed Entra knobs we need outside Azure SDK
+    environment configuration. Everything else
+    (tenant ID, service principal secret, federated token file, sovereign
+    cloud authority, etc.) flows through azure-identity's standard
+    ``AZURE_*`` env vars — see the Bedrock pattern in
+    ``hermes_cli/runtime_provider.py:1310-1377`` for the analogous
+    "let the SDK read env" approach.
+
+    ``scope`` is Microsoft's documented Foundry inference audience. Almost
+    everyone uses the default; sovereign-cloud / non-standard tenants can
+    override via ``model.entra.scope``. Identity selection (user-assigned
+    managed identity, workload identity, service principal, tenant, authority)
+    stays in the standard Azure SDK env vars such as ``AZURE_CLIENT_ID``.
+
+    ``exclude_interactive_browser`` is kept as an internal constructor knob
+    so probes stay non-interactive by default. It is not written by the setup
+    wizard.
+
+    The dataclass is frozen so it's hashable for ``functools.lru_cache``
+    keying, and serializable across multiprocessing boundaries (workers
+    rebuild the credential inside their own process).
+    """
+
+    scope: str = SCOPE_AI_AZURE_DEFAULT
+    exclude_interactive_browser: bool = True
+
+    def __post_init__(self) -> None:
+        scope = str(self.scope or "").strip() or SCOPE_AI_AZURE_DEFAULT
+        object.__setattr__(self, "scope", scope)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "scope": self.scope,
+            "exclude_interactive_browser": self.exclude_interactive_browser,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]],
+                  *, default_scope: Optional[str] = None) -> "EntraIdentityConfig":
+        data = data or {}
+        scope = str(data.get("scope") or "").strip() or default_scope or SCOPE_AI_AZURE_DEFAULT
+        exclude_browser = bool(data.get("exclude_interactive_browser", True))
+        return cls(
+            scope=scope,
+            exclude_interactive_browser=exclude_browser,
+        )
+
+
+def _build_default_credential(config: EntraIdentityConfig) -> Any:
+    """Construct a ``DefaultAzureCredential`` for ``config``.
+
+    Only Hermes-selected knobs are passed as kwargs. Everything else
+    (tenant, service principal secret, federated token file, sovereign
+    cloud authority, etc.) is read by ``azure-identity`` from the
+    standard ``AZURE_*`` environment variables — see Microsoft's
+    documented credential resolution chain. Users configure those in
+    ``~/.hermes/.env`` or the deployment environment.
+    """
+    ai = _require_azure_identity()
+    kwargs: Dict[str, Any] = {}
+    # SDK default is True (browser excluded); only pass when the user
+    # explicitly opts in to interactive browser auth.
+    if not config.exclude_interactive_browser:
+        kwargs["exclude_interactive_browser_credential"] = False
+    return ai.DefaultAzureCredential(**kwargs)
+
+
+@functools.lru_cache(maxsize=1)
+def build_credential(config: EntraIdentityConfig) -> Any:
+    """Return the cached ``DefaultAzureCredential`` for ``config``.
+
+    Hermes processes use exactly one Entra config at a time (the
+    ``model.entra.*`` block in config.yaml drives every aux task,
+    subagent, and credential probe in the session). ``maxsize=1`` is
+    intentional: it reflects the actual usage pattern and keeps the
+    cache trivially small.
+
+    ``EntraIdentityConfig`` is a frozen dataclass, so it's hashable and
+    safe as an LRU-cache key. ``functools.lru_cache`` is thread-safe in
+    CPython.
+
+    If two distinct configs are ever passed (tests do this; production
+    rarely), the LRU eviction handles it correctly — each call still
+    returns a credential matching its config; only one is cached at a
+    time. Use :func:`reset_credential_cache` to clear (e.g. in tests).
+    """
+    return _build_default_credential(config)
+
+
+def build_token_provider(scope: Optional[str] = None,
+                         *,
+                         config: Optional[EntraIdentityConfig] = None,
+                         base_url: Optional[str] = None,
+                         exclude_interactive_browser: bool = True,
+                         ) -> Callable[[], str]:
+    """Return a zero-arg callable that mints a fresh Entra bearer JWT.
+
+    The returned callable is exactly what Microsoft's documented Foundry
+    sample expects::
+
+        from openai import OpenAI
+        client = OpenAI(
+            base_url="https://my-resource.openai.azure.com/openai/v1/",
+            api_key=build_token_provider(),
+        )
+
+    Scope resolution order:
+      1. ``config.scope`` when a config object is supplied
+      2. explicit ``scope`` kwarg
+      3. ``SCOPE_AI_AZURE_DEFAULT`` (Microsoft's documented Foundry scope)
+
+    ``base_url`` is unused today and kept for back-compat. Tenant /
+    service-principal / sovereign-cloud configuration flows through
+    ``azure-identity``'s standard ``AZURE_*`` environment variables —
+    see :func:`_build_default_credential` for the rationale.
+
+    NOT serializable across process boundaries. For multiprocessing
+    workers, serialize the ``EntraIdentityConfig`` and rebuild the
+    provider inside the worker.
+    """
+    ai = _require_azure_identity()
+    if config is None:
+        config = EntraIdentityConfig(
+            scope=scope or SCOPE_AI_AZURE_DEFAULT,
+            exclude_interactive_browser=exclude_interactive_browser,
+        )
+    credential = build_credential(config)
+    return ai.get_bearer_token_provider(credential, config.scope)
+
+
+# ---------------------------------------------------------------------------
+# Credential probing
+# ---------------------------------------------------------------------------
+
+
+def has_azure_identity_credentials(scope: Optional[str] = None,
+                                   *,
+                                   config: Optional[EntraIdentityConfig] = None,
+                                   timeout_seconds: float = 10.0,
+                                   allow_install: bool = True,
+                                   **overrides: Any) -> bool:
+    """Best-effort probe: can `DefaultAzureCredential` mint a token now?
+
+    Runs ``credential.get_token(scope)`` under a thread-based timeout so
+    a slow token service can't hang the caller. Returns False on any
+    error — never raises. Use for ``hermes doctor`` /
+    ``hermes auth status`` / wizard preflight.
+
+    ``allow_install``: when True (default) and ``azure-identity`` is not
+    importable, the adapter triggers the standard lazy-install path
+    (subject to ``security.allow_lazy_installs``) before probing. Set
+    False to make this strictly an "is installed?" check — used on hot
+    paths like CLI startup where we never want pip to run.
+
+    NOT used by ``is_provider_configured()`` — that path is structural
+    only (no token mint), so CLI startup doesn't pay this latency.
+    """
+    if not has_azure_identity_installed():
+        if not allow_install:
+            return False
+        try:
+            _require_azure_identity()
+        except ImportError as exc:
+            logger.debug("azure-identity lazy install unavailable: %s", exc)
+            return False
+    if config is None:
+        effective_scope = (scope or "").strip() or SCOPE_AI_AZURE_DEFAULT
+        config = EntraIdentityConfig(scope=effective_scope, **overrides)
+
+    result = {"ok": False}
+
+    def _probe() -> None:
+        try:
+            credential = build_credential(config)
+            tok = credential.get_token(config.scope)
+            result["ok"] = bool(getattr(tok, "token", None))
+        except Exception as exc:
+            logger.debug("Entra credential probe failed: %s", exc)
+            result["ok"] = False
+
+    thread = threading.Thread(target=_probe, daemon=True)
+    thread.start()
+    thread.join(timeout=max(0.01, timeout_seconds))
+    if thread.is_alive():
+        logger.debug("Entra token service probe timed out after %ss", timeout_seconds)
+        return False
+    return bool(result.get("ok"))
+
+
+def describe_active_credential(config: Optional[EntraIdentityConfig] = None,
+                               *,
+                               scope: Optional[str] = None,
+                               timeout_seconds: float = 10.0,
+                               allow_install: bool = True,
+                               **overrides: Any) -> Dict[str, Any]:
+    """Return diagnostic info about the active credential chain.
+
+    Best-effort: runs ``get_token()`` and inspects what came back.
+    Designed for ``hermes doctor`` and the wizard preflight — never
+    raises, returns ``{"ok": False, "error": ...}`` on failure.
+
+    ``allow_install``: when True (default) and ``azure-identity`` is not
+    importable, the adapter triggers the standard lazy-install path
+    (subject to ``security.allow_lazy_installs``) before probing. The
+    install failure is surfaced as the diagnostic error when it fails.
+    Set False for hot CLI paths that should never trigger pip.
+
+    ``azure-identity`` doesn't expose the winning inner credential as
+    a public field, so we report a coarse picture (env vars present,
+    token expiry, claims-derived tenant) rather than the credential
+    class name. Users wanting the precise class can run with
+    ``AZURE_LOG_LEVEL=DEBUG``.
+    """
+    info: Dict[str, Any] = {"ok": False}
+    if not has_azure_identity_installed():
+        if not allow_install:
+            info["error"] = "azure-identity not installed"
+            info["hint"] = (
+                "pip install azure-identity (or rely on lazy install at "
+                "first use)"
+            )
+            return info
+        try:
+            _require_azure_identity()
+        except ImportError as exc:
+            info["error"] = str(exc) or "azure-identity not installed"
+            info["hint"] = (
+                "pip install azure-identity manually, or enable lazy "
+                "installs (security.allow_lazy_installs: true in "
+                "config.yaml)."
+            )
+            return info
+
+    if config is None:
+        effective_scope = (scope or "").strip() or SCOPE_AI_AZURE_DEFAULT
+        config = EntraIdentityConfig(scope=effective_scope, **overrides)
+
+    info["scope"] = config.scope
+    # Tenant / authority / service-principal config flow through the
+    # standard ``AZURE_*`` env vars; surface them below.
+    if os.environ.get("AZURE_TENANT_ID", "").strip():
+        info["tenant_id_env"] = os.environ["AZURE_TENANT_ID"].strip()
+
+    # Surface which env-var sources are present without minting yet.
+    env_sources = []
+    if os.environ.get("AZURE_FEDERATED_TOKEN_FILE", "").strip():
+        env_sources.append("WorkloadIdentityCredential (AZURE_FEDERATED_TOKEN_FILE)")
+    if (os.environ.get("AZURE_CLIENT_ID", "").strip()
+            and os.environ.get("AZURE_CLIENT_SECRET", "").strip()
+            and os.environ.get("AZURE_TENANT_ID", "").strip()):
+        env_sources.append("EnvironmentCredential (client secret)")
+    if os.environ.get("IDENTITY_ENDPOINT", "").strip() or os.environ.get("MSI_ENDPOINT", "").strip():
+        env_sources.append("ManagedIdentityCredential (IDENTITY_ENDPOINT)")
+    info["env_sources"] = env_sources
+
+    # Now try minting.
+    result: Dict[str, Any] = {}
+
+    def _probe() -> None:
+        try:
+            credential = build_credential(config)
+            tok = credential.get_token(config.scope)
+            result["token"] = tok
+        except Exception as exc:
+            result["error"] = str(exc)
+
+    thread = threading.Thread(target=_probe, daemon=True)
+    thread.start()
+    thread.join(timeout=max(0.01, timeout_seconds))
+    if thread.is_alive():
+        info["error"] = f"Token probe timed out after {timeout_seconds:.0f}s"
+        info["hint"] = (
+            "DefaultAzureCredential can be slow when the token service is unreachable "
+            "or when az login state is stale. Try `az login` or set "
+            "AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_CLIENT_SECRET."
+        )
+        return info
+
+    if "error" in result:
+        info["error"] = result["error"]
+        return info
+
+    token = result.get("token")
+    if token is None:
+        info["error"] = "credential chain exhausted"
+        return info
+
+    info["ok"] = True
+    info["expires_on"] = getattr(token, "expires_on", None)
+    return info
+
+
+# ---------------------------------------------------------------------------
+# Consumer-side helpers — split by purpose to prevent accidental token
+# minting in logging / cache-key / dashboard paths.
+# ---------------------------------------------------------------------------
+
+
+def is_token_provider(value: Any) -> bool:
+    """Return True when ``value`` is a callable Entra token provider.
+
+    Used at the seams where a consumer must decide between
+    string-API-key semantics and bearer-callable semantics.
+    """
+    return callable(value) and not isinstance(value, str)
+
+
+def materialize_bearer_for_http(value: Any) -> str:
+    """Return a fresh Bearer JWT for a manual HTTP request.
+
+    Only call this at sites that must construct an ``Authorization``
+    header outside the OpenAI SDK (e.g. ``hermes_cli/azure_detect.py``).
+    Calls the callable exactly once and returns the resulting token.
+
+    **Anthropic SDK integration:** the Anthropic Python SDK does not
+    accept a ``Callable[[], str]`` for ``auth_token``. Instead,
+    :func:`build_bearer_http_client` returns an ``httpx.Client`` whose
+    request event hook calls this function and rewrites the
+    ``Authorization`` header per request — and that client is passed to
+    the Anthropic SDK via ``http_client=...``. See
+    :func:`agent.anthropic_adapter.build_anthropic_client` for the
+    consumer.
+
+    Raises ``ValueError`` if ``value`` is not a callable token provider
+    or non-empty string.
+    """
+    if is_token_provider(value):
+        token = value()
+        if not isinstance(token, str) or not token:
+            raise ValueError("token provider returned empty value")
+        return token
+    if isinstance(value, str) and value:
+        return value
+    raise ValueError("no usable api_key / token provider")
+
+
+def build_bearer_http_client(token_provider: Callable[[], str], **httpx_kwargs: Any) -> Any:
+    """Return an ``httpx.Client`` that mints a fresh Entra bearer JWT
+    per outbound request.
+
+    The Anthropic SDK (≤ 0.86.0 at the time of writing) stores
+    ``api_key`` / ``auth_token`` as static strings and computes the
+    ``Authorization`` header at construction time. To get per-request
+    token refresh (the Microsoft-recommended Foundry pattern for
+    callable bearer providers), we install an httpx ``request`` event
+    hook on a custom client and pass that client to the SDK via
+    ``http_client=...``. The hook:
+
+      1. Calls :func:`materialize_bearer_for_http` to mint a fresh JWT
+         (azure-identity caches internally — this is cheap when the
+         cached token is still valid).
+      2. Strips any pre-set ``Authorization`` / ``api-key`` /
+         ``x-api-key`` headers the SDK may have added (avoids
+         conflicting auth values).
+      3. Sets ``Authorization: Bearer <fresh-jwt>``.
+
+    ``token_provider`` must be a zero-arg callable returning a string —
+    typically the result of :func:`build_token_provider`.
+
+    ``httpx_kwargs`` are forwarded verbatim to ``httpx.Client(...)`` so
+    callers can attach a ``timeout``, ``transport``, ``proxy``, etc.
+
+    Raises ``ImportError`` if ``httpx`` is not installed (it is a
+    transitive dependency of both ``openai`` and ``anthropic`` SDKs, so
+    in practice always available when this helper is reached).
+    """
+    if not is_token_provider(token_provider):
+        raise ValueError(
+            "build_bearer_http_client requires a zero-arg callable "
+            "token provider"
+        )
+
+    try:
+        import httpx
+    except ImportError as exc:  # pragma: no cover — httpx ships with openai/anthropic
+        raise ImportError(
+            "httpx is required for Entra ID bearer auth on Microsoft Foundry "
+            "Anthropic-style endpoints. It is normally a transitive "
+            "dependency of the openai/anthropic SDKs."
+        ) from exc
+
+    def _inject_bearer(request: "httpx.Request") -> None:
+        try:
+            token = materialize_bearer_for_http(token_provider)
+        except ValueError as exc:
+            # Token provider failed (chain exhausted, token service unreachable,
+            # az login expired, etc.). Strip any auth headers the SDK
+            # may have set — including our own placeholder sentinel
+            # ``entra-id-bearer-via-http-hook`` from
+            # ``_build_anthropic_client_with_bearer_hook`` — so the
+            # outbound request hits Azure with NO Authorization rather
+            # than with the placeholder. Azure returns a clean 401
+            # "missing auth" that is easier to diagnose than a 401
+            # against the sentinel string, and the sentinel never
+            # appears in upstream access logs.
+            #
+            # Log at WARNING (not DEBUG) so the misconfiguration is
+            # visible at default log levels.
+            logger.warning(
+                "Bearer hook: Entra ID token provider returned empty (%s) "
+                "— stripping Authorization headers. Azure will respond 401. "
+                "Run `hermes doctor` or `az login` to recover.",
+                exc,
+            )
+            for header_name in ("Authorization", "authorization", "Api-Key", "api-key", "X-Api-Key", "x-api-key"):
+                request.headers.pop(header_name, None)
+            return
+        for header_name in ("Authorization", "authorization", "Api-Key", "api-key", "X-Api-Key", "x-api-key"):
+            request.headers.pop(header_name, None)
+        request.headers["Authorization"] = f"Bearer {token}"
+
+    return httpx.Client(
+        event_hooks={"request": [_inject_bearer]},
+        **httpx_kwargs,
+    )
+
+
+__all__ = [
+    "EntraIdentityConfig",
+    "SCOPE_AI_AZURE_DEFAULT",
+    "build_bearer_http_client",
+    "build_credential",
+    "build_token_provider",
+    "describe_active_credential",
+    "has_azure_identity_credentials",
+    "has_azure_identity_installed",
+    "is_token_provider",
+    "materialize_bearer_for_http",
+    "reset_credential_cache",
+]

agent/chat_completion_helpers.py

@@ -866,9 +866,14 @@ def try_activate_fallback(agent, reason: "FailoverReason | None" = None) -> bool
         # the fallback activation drops to 128K even when config says 204800.
         if hasattr(agent, 'context_compressor') and agent.context_compressor:
             from agent.model_metadata import get_model_context_length
+            # ``agent.api_key`` may be callable (Entra ID); the
+            # context-length resolver expects a string for live
+            # probes. Foundry typically resolves via config/static
+            # catalogs anyway, so coerce defensively.
+            _fb_ctx_api_key = agent.api_key if isinstance(agent.api_key, str) else ""
             fb_context_length = get_model_context_length(
                 agent.model, base_url=agent.base_url,
-                api_key=agent.api_key, provider=agent.provider,
+                api_key=_fb_ctx_api_key, provider=agent.provider,
                 config_context_length=getattr(agent, "_config_context_length", None),
                 custom_providers=getattr(agent, "_custom_providers", None),
             )
@@ -876,7 +881,7 @@ def try_activate_fallback(agent, reason: "FailoverReason | None" = None) -> bool
                 model=agent.model,
                 context_length=fb_context_length,
                 base_url=agent.base_url,
-                api_key=getattr(agent, "api_key", ""),
+                api_key=getattr(agent, "api_key", ""),  # callable preserved → call_llm
                 provider=agent.provider,
             )
 

agent/context_compressor.py

@@ -486,7 +486,7 @@ class ContextCompressor(ContextEngine):
         model: str,
         context_length: int,
         base_url: str = "",
-        api_key: str = "",
+        api_key: Any = "",
         provider: str = "",
         api_mode: str = "",
     ) -> None:

agent/conversation_compression.py

@@ -103,7 +103,15 @@ def check_compression_model_feasibility(agent: Any) -> None:
             return
 
         aux_base_url = str(getattr(client, "base_url", ""))
-        aux_api_key = str(getattr(client, "api_key", ""))
+        # ``client.api_key`` may be a callable (Azure Foundry Entra ID
+        # bearer provider). The context-length resolver chain expects a
+        # string, but it only needs a key for live catalogue probes
+        # (provider model lists). For Entra clients the model-metadata
+        # chain still resolves via models.dev + hardcoded family
+        # fallbacks, which don't require auth — pass empty string rather
+        # than minting a bearer JWT just to look up a context length.
+        _raw_aux_key = getattr(client, "api_key", "")
+        aux_api_key = "" if (callable(_raw_aux_key) and not isinstance(_raw_aux_key, str)) else str(_raw_aux_key or "")
 
         aux_context = get_model_context_length(
             aux_model,

agent/conversation_loop.py

@@ -1807,7 +1807,11 @@ def run_conversation(
                         # that survives message/tool sanitization (#6843).
                         _credential_sanitized = False
                         _raw_key = getattr(agent, "api_key", None) or ""
-                        if _raw_key:
+                        # Entra ID bearer providers are callables — their
+                        # minted JWTs are always ASCII, so no sanitization
+                        # is needed (and ``_strip_non_ascii`` would crash
+                        # on a callable input).
+                        if _raw_key and isinstance(_raw_key, str):
                             _clean_key = _strip_non_ascii(_raw_key)
                             if _clean_key != _raw_key:
                                 agent.api_key = _clean_key
@@ -2080,15 +2084,26 @@ def run_conversation(
                 ):
                     anthropic_auth_retry_attempted = True
                     from agent.anthropic_adapter import _is_oauth_token
+                    from agent.azure_identity_adapter import is_token_provider
                     if agent._try_refresh_anthropic_client_credentials():
                         print(f"{agent.log_prefix}🔐 Anthropic credentials refreshed after 401. Retrying request...")
                         continue
                     # Credential refresh didn't help — show diagnostic info
                     key = agent._anthropic_api_key
-                    auth_method = "Bearer (OAuth/setup-token)" if _is_oauth_token(key) else "x-api-key (API key)"
                     print(f"{agent.log_prefix}🔐 Anthropic 401 — authentication failed.")
-                    print(f"{agent.log_prefix}   Auth method: {auth_method}")
-                    print(f"{agent.log_prefix}   Token prefix: {key[:12]}..." if key and len(key) > 12 else f"{agent.log_prefix}   Token: (empty or short)")
+                    if is_token_provider(key):
+                        # Azure Foundry Entra ID — the bearer token is
+                        # minted per-request by an httpx event hook on a
+                        # custom http_client passed to the SDK. The 401
+                        # means Azure rejected the JWT (RBAC role missing,
+                        # az login expired, IMDS unreachable, etc.).
+                        print(f"{agent.log_prefix}   Auth method: Microsoft Entra ID (httpx event hook)")
+                        print(f"{agent.log_prefix}   Run `hermes doctor` for credential-chain diagnostics, or")
+                        print(f"{agent.log_prefix}   `az login` if your developer session expired.")
+                    else:
+                        auth_method = "Bearer (OAuth/setup-token)" if _is_oauth_token(key) else "x-api-key (API key)"
+                        print(f"{agent.log_prefix}   Auth method: {auth_method}")
+                        print(f"{agent.log_prefix}   Token prefix: {key[:12]}..." if isinstance(key, str) and len(key) > 12 else f"{agent.log_prefix}   Token: (empty or short)")
                     print(f"{agent.log_prefix}   Troubleshooting:")
                     from hermes_constants import display_hermes_home as _dhh_fn
                     _dhh = _dhh_fn()