The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
feat(providers): missing-credential guidance seams for plugin providers
Tekniumd74fe78713a5
diff --git a/agent/acp_client.py b/agent/acp_client.pyindex 81169977105..2b00a9490f0 100644--- a/agent/acp_client.py+++ b/agent/acp_client.py@@ -43,6 +43,8 @@ from agent.runtime_cwd import resolve_agent_cwdlogger = logging.getLogger(__name__)_DEFAULT_TIMEOUT_SECONDS = 900.0+# ACP JSON-RPC error code meaning "authentication required" (the agent CLI is not signed in).+_ACP_AUTH_REQUIRED = -32000_ROLE_LABELS = {"system": "System", "user": "User", "assistant": "Assistant", "tool": "Tool", "context": "Context"}# Probe verdicts per binary path (~50ms --help paid once per process). Only definitive# True/False is cached, so a CLI installed mid-session is picked up.@@ -290,6 +292,9 @@ class ACPClient:label: str = "ACP"#: Error text after "Could not start <label> command '<cmd>'." (default names ``command_env_vars``).missing_command_hint: str = ""+ #: Sentence appended when the agent answers a request with ACP's auth-required error (code -32000),+ #: e.g. the CLI's own login command; None = the agent's message alone.+ auth_required_hint: str | None = None#: Error text after the ``--acp`` probe rejects the CLI.unsupported_transport_hint: str = ("Either install a CLI release that supports --acp, or point the provider at a working command/args pair.")@@ -309,6 +314,11 @@ class ACPClient:override = os.getenv(self.args_env_var, "").strip() if self.args_env_var else ""return shlex.split(override) or list(self.default_args)+ def _request_error(self, method: str, err: Any) -> str:+ text = f"{self.label} {method} failed: {(err.get('message') if isinstance(err, dict) else None) or err}"+ auth_required = isinstance(err, dict) and err.get("code") == _ACP_AUTH_REQUIRED+ return f"{text} {self.auth_required_hint}" if auth_required and self.auth_required_hint else text+def _missing_command_hint(self) -> str:if self.missing_command_hint:return self.missing_command_hint@@ -455,8 +465,7 @@ class ACPClient:) or msg.get("id") != request_id:continueif "error" in msg:- err = msg.get("error") or {}- raise RuntimeError(f"{self.label} {method} failed: {err.get('message') or err}")+ raise RuntimeError(self._request_error(method, msg.get("error") or {}))return msg.get("result")if proc.poll() is not None:# The pump can still hold the crash text when poll() first sees the exit; readingdiff --git a/hermes_cli/runtime_provider.py b/hermes_cli/runtime_provider.pyindex 607a47aee69..14045da9f6a 100644--- a/hermes_cli/runtime_provider.py+++ b/hermes_cli/runtime_provider.py@@ -902,7 +902,8 @@ def _api_key_provider_runtime(provider, pconfig, requested_provider, model_cfg,# An explicitly selected API-key provider is authoritative: an empty key would defer failure# to the first request and make a later fallback look like a silent provider switch.if not has_usable_secret(creds.get("api_key")):- hint = f" Set {', '.join(pconfig.api_key_env_vars)}." if pconfig.api_key_env_vars else ""+ from hermes_cli.runtime_readiness import missing_credentials_suffix+ hint = (f" Set {', '.join(pconfig.api_key_env_vars)}." if pconfig.api_key_env_vars else "") + missing_credentials_suffix(provider)raise AuthError(f"No usable credentials found for provider '{provider}'.{hint}", provider=provider, code="missing_api_key")# Honour model.base_url when the configured provider matches (e.g. api.minimaxi.com China endpoint).base_url = _actual_url(provider, _config_base_url_for_provider(model_cfg, provider) or creds.get("base_url", "").rstrip("/"))diff --git a/hermes_cli/runtime_readiness.py b/hermes_cli/runtime_readiness.pyindex 9dfd87b8643..9be83f1308e 100644--- a/hermes_cli/runtime_readiness.py+++ b/hermes_cli/runtime_readiness.py@@ -6,6 +6,15 @@ failure (naming the configured pin, never the fallback chain's tail), ``free_tie"""+def missing_credentials_suffix(provider) -> str:+ """``" <hint>"`` from *provider*'s profile (``ProviderProfile.missing_credentials_hint``) for a+ "No usable credentials found" message, else ``""``."""+ from providers import get_provider_profile+ profile = get_provider_profile(str(provider or "").strip().lower()) if provider else None+ hint = profile.missing_credentials_hint() if profile is not None else None+ return f" {hint.strip()}" if hint and hint.strip() else ""++def check_runtime_readiness(requested=None, *, strict_profile_scope=False, resolve=None):"""ok/error verdict for the runtime a session would be built with.@@ -52,7 +61,7 @@ def check_runtime_readiness(requested=None, *, strict_profile_scope=False, resolapi_key_text = '' if callable(api_key) else str(api_key or '').strip()if not (callable(api_key) or api_key_text in {'aws-sdk', 'no-key-required'}or has_usable_secret(api_key_text) or bool(runtime.get('command'))):- return fail(f'No usable credentials found for {blamed}.', runtime.get('source'))+ return fail(f'No usable credentials found for {blamed}.{missing_credentials_suffix(blamed)}', runtime.get('source'))from hermes_cli.anon_auth import route_is_welcome_host# free_tier_route is keyed on the SELECTED route (the welcome host serves only nous/welcome), not# on profile state: a paid Nous key beside a free-tier identity must not read as free.diff --git a/providers/base.py b/providers/base.pyindex c51c7bdcfbc..254d3bd8419 100644--- a/providers/base.py+++ b/providers/base.py@@ -663,6 +663,11 @@ class ProviderProfile:"""Subprocess-free ``(verified, source)`` login evidence for an external CLI; None = binary resolves."""return None+ def missing_credentials_hint(self) -> str | None:+ """One sentence appended to every "No usable credentials found" surface (runtime resolution, CLI and+ Desktop readiness), e.g. the provider's own sign-in command; None = the generic message alone."""+ return None+# ── Lane L3: Responses-route quirks and message-level reasoning carriers ───# Every field and hook below applies only on hosts the profile declares in ``hostnames``;# the defaults are the generic wire. Hot path: answers must be pure and cheap (no I/O). A hook thatdiff --git a/tests/providers/test_missing_credentials_hints.py b/tests/providers/test_missing_credentials_hints.pynew file mode 100644index 00000000000..7103725dca1--- /dev/null+++ b/tests/providers/test_missing_credentials_hints.py@@ -0,0 +1,85 @@+"""Missing-credential guidance seams: ``ProviderProfile.missing_credentials_hint`` on every "No usable+credentials found" surface and ``ACPClient.auth_required_hint`` on ACP's auth-required error."""++import sys++import pytest++from agent.acp_client import ACPClient+from providers.base import ProviderProfile++_HINT = "Run `fake-cli login` to sign in."+++class _HintedProfile(ProviderProfile):+ def missing_credentials_hint(self):+ return _HINT+++def hinted_provider(tmp_path, monkeypatch):+ """A registry api-key provider (a plugin profile) whose key is unset, with or without a hint."""+ monkeypatch.setenv("HERMES_HOME", str(tmp_path))+ monkeypatch.delenv("FAKE_HINTED_KEY", raising=False)+ import providers+ from hermes_cli.auth import PROVIDER_REGISTRY, ProviderConfig++ def install(profile_cls):+ profile = profile_cls(name="fake-hinted", auth_type="api_key", env_vars=("FAKE_HINTED_KEY",),+ base_url="https://api.fake-hinted.test/v1")+ monkeypatch.setattr(providers, "get_provider_profile",+ lambda name: profile if name == "fake-hinted" else None)+ monkeypatch.setitem(PROVIDER_REGISTRY, "fake-hinted", ProviderConfig(+ id="fake-hinted", name="Fake", auth_type="api_key", inference_base_url=profile.base_url,+ api_key_env_vars=("FAKE_HINTED_KEY",)))+ return profile+ return install++[email protected]("profile_cls, suffix", [(_HintedProfile, f" {_HINT}"), (ProviderProfile, "")])+def test_runtime_resolution_appends_the_profile_hint(hinted_provider, profile_cls, suffix):+ hinted_provider(profile_cls)+ from hermes_cli.auth import AuthError+ from hermes_cli.runtime_provider import resolve_runtime_provider++ with pytest.raises(AuthError) as excinfo:+ resolve_runtime_provider(requested="fake-hinted")+ assert str(excinfo.value) == f"No usable credentials found for provider 'fake-hinted'. Set FAKE_HINTED_KEY.{suffix}"++[email protected]("profile_cls, suffix", [(_HintedProfile, f" {_HINT}"), (ProviderProfile, "")])+def test_readiness_check_appends_the_profile_hint(hinted_provider, profile_cls, suffix):+ hinted_provider(profile_cls)+ from hermes_cli.runtime_readiness import check_runtime_readiness++ verdict = check_runtime_readiness(+ "fake-hinted", resolve=lambda: ("m", {"provider": "fake-hinted", "api_key": "", "source": "none"}))+ assert verdict["ok"] is False+ assert verdict["error"] == f"No usable credentials found for fake-hinted.{suffix}"+++_AUTH_REQUIRED_AGENT = """import json, sys+for line in sys.stdin:+ request = json.loads(line)+ if request.get("method") == "initialize":+ reply = {"result": {"protocolVersion": 1, "authMethods": [{"id": "fake", "name": "Fake login"}]}}+ else:+ reply = {"error": {"code": -32000, "message": "Authentication required"}}+ print(json.dumps({"jsonrpc": "2.0", "id": request["id"], **reply}), flush=True)+"""+++class _FakeLoginClient(ACPClient):+ label = "Fake ACP"+ auth_required_hint = _HINT++[email protected]("client_cls, suffix", [(_FakeLoginClient, f" {_HINT}"), (ACPClient, "")])+def test_acp_auth_required_error_carries_the_client_hint(tmp_path, client_cls, suffix):+ agent = tmp_path / "auth_required_agent.py"+ agent.write_text(_AUTH_REQUIRED_AGENT, encoding="utf-8")+ client = client_cls(command=sys.executable, args=[str(agent)], acp_cwd=str(tmp_path))+ with pytest.raises(RuntimeError) as excinfo:+ with client._session(30):+ pass+ assert str(excinfo.value) == f"{client_cls.label} session/new failed: Authentication required{suffix}"diff --git a/tui_gateway/methods_config.py b/tui_gateway/methods_config.pyindex 3148436fb8a..d3641cb9079 100644--- a/tui_gateway/methods_config.py+++ b/tui_gateway/methods_config.py@@ -467,7 +467,9 @@ def _(rid, params: dict) -> dict:api_key_text = "" if callable(api_key) else str(api_key or "").strip()if not (callable(api_key) or api_key_text in {"aws-sdk", "no-key-required"}or has_usable_secret(api_key_text) or bool(runtime.get("command"))):- return fail(f"No usable credentials found for {blamed}.", runtime.get("source"))+ from hermes_cli.runtime_readiness import missing_credentials_suffix+ return fail(f"No usable credentials found for {blamed}.{missing_credentials_suffix(blamed)}",+ runtime.get("source"))from hermes_cli.anon_auth import route_is_welcome_host# free_tier_route is keyed on the SELECTED route (the welcome host serves only nous/welcome), not# on profile state: a paid Nous key beside a free-tier identity must not read as free.diff --git a/website/docs/developer-guide/model-provider-plugin.md b/website/docs/developer-guide/model-provider-plugin.mdindex 97979eb6f71..e4b51e01b3c 100644--- a/website/docs/developer-guide/model-provider-plugin.md+++ b/website/docs/developer-guide/model-provider-plugin.md@@ -308,6 +308,7 @@ meaning says otherwise.| `credential_refresh_notice()` | Status line after a successful runtime refresh | `""` (generic wording) || `request_rejection_hint()` | User-facing lines for an endpoint's hard rejection of any route | `()` || `external_auth_evidence()` | Subprocess-free `(verified, source)` login evidence for an external CLI | `None` (binary resolves) |+| `missing_credentials_hint()` | One sentence appended to every "No usable credentials found" message (runtime resolution, CLI and Desktop readiness), e.g. the provider's sign-in command | `None` || `responses_replay_item_ids` | Replayed Responses `message` items keep their `id` | `True` || `responses_prompt_cache_key` | The Responses body carries `prompt_cache_key` | `True` || `responses_issuer_kind` | Persisted issuer stamp for encrypted reasoning minted here | `""` (URL-derived) |@@ -406,6 +407,7 @@ class MyAgentClient(ACPClient):marker_base_url = "acp://myagent"placeholder_model = "myagent-acp" # "session default": never sent as a model selectionlabel = "MyAgent ACP" # product name in errors and logs+ auth_required_hint = "Run `myagent login`, then retry." # optional: added to ACP's auth-required error (-32000)def model_entry_disabled(self, entry): # optional: vendor _meta marking a model unavailablereturn False