Skip to content

The agent that grows with you

feat(providers): missing-credential guidance seams for plugin providers

Tekniumd74fe78713a5
diff --git a/agent/acp_client.py b/agent/acp_client.py
index 81169977105..2b00a9490f0 100644
--- a/agent/acp_client.py
+++ b/agent/acp_client.py
@@ -43,6 +43,8 @@ from agent.runtime_cwd import resolve_agent_cwd
logger = 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:
continue
if "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; reading
diff --git a/hermes_cli/runtime_provider.py b/hermes_cli/runtime_provider.py
index 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.py
index 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, resol
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'))
+ 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.py
index 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 that
diff --git a/tests/providers/test_missing_credentials_hints.py b/tests/providers/test_missing_credentials_hints.py
new file mode 100644
index 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.py
index 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.md
index 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 selection
label = "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 unavailable
return False