feat(auth): same-provider credential pools with rotation, custom endpoint support, and interactive CLI (#2647)
* feat(auth): add same-provider credential pools and rotation UX Add same-provider credential pooling so Hermes can rotate across multiple credentials for a single provider, recover from exhausted credentials without jumping providers immediately, and configure that behavior directly in hermes setup. - agent/credential_pool.py: persisted per-provider credential pools - hermes auth add/list/remove/reset CLI commands - 429/402/401 recovery with pool rotation in run_agent.py - Setup wizard integration for pool strategy configuration - Auto-seeding from env vars and existing OAuth state Co-authored-by: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com> Salvaged from PR #2647 * fix(tests): prevent pool auto-seeding from host env in credential pool tests Tests for non-pool Anthropic paths and auth remove were failing when host env vars (ANTHROPIC_API_KEY) or file-backed OAuth credentials were present. The pool auto-seeding picked these up, causing unexpected pool entries in tests. - Mock _select_pool_entry in auxiliary_client OAuth flag tests - Clear Anthropic env vars and mock _seed_from_singletons in auth remove test * feat(auth): add thread safety, least_used strategy, and request counting - Add threading.Lock to CredentialPool for gateway thread safety (concurrent requests from multiple gateway sessions could race on pool state mutations without this) - Add 'least_used' rotation strategy that selects the credential with the lowest request_count, distributing load more evenly - Add request_count field to PooledCredential for usage tracking - Add mark_used() method to increment per-credential request counts - Wrap select(), mark_exhausted_and_rotate(), and try_refresh_current() with lock acquisition - Add tests: least_used selection, mark_used counting, concurrent thread safety (4 threads × 20 selects with no corruption) * feat(auth): add interactive mode for bare 'hermes auth' command When 'hermes auth' is called without a subcommand, it now launches an interactive wizard that: 1. Shows full credential pool status across all providers 2. Offers a menu: add, remove, reset cooldowns, set strategy 3. For OAuth-capable providers (anthropic, nous, openai-codex), the add flow explicitly asks 'API key or OAuth login?' — making it clear that both auth types are supported for the same provider 4. Strategy picker shows all 4 options (fill_first, round_robin, least_used, random) with the current selection marked 5. Remove flow shows entries with indices for easy selection The subcommand paths (hermes auth add/list/remove/reset) still work exactly as before for scripted/non-interactive use. * fix(tests): update runtime_provider tests for config.yaml source of truth (#4165) Tests were using OPENAI_BASE_URL env var which is no longer consulted after #4165. Updated to use model config (provider, base_url, api_key) which is the new single source of truth for custom endpoint URLs. * feat(auth): support custom endpoint credential pools keyed by provider name Custom OpenAI-compatible endpoints all share provider='custom', making the provider-keyed pool useless. Now pools for custom endpoints are keyed by 'custom:<normalized_name>' where the name comes from the custom_providers config list (auto-generated from URL hostname). - Pool key format: 'custom:together.ai', 'custom:local-(localhost:8080)' - load_pool('custom:name') seeds from custom_providers api_key AND model.api_key when base_url matches - hermes auth add/list now shows custom endpoints alongside registry providers - _resolve_openrouter_runtime and _resolve_named_custom_runtime check pool before falling back to single config key - 6 new tests covering custom pool keying, seeding, and listing * docs: add Excalidraw diagram of full credential pool flow Comprehensive architecture diagram showing: - Credential sources (env vars, auth.json OAuth, config.yaml, CLI) - Pool storage and auto-seeding - Runtime resolution paths (registry, custom, OpenRouter) - Error recovery (429 retry-then-rotate, 402 immediate, 401 refresh) - CLI management commands and strategy configuration Open at: https://excalidraw.com/#json=2Ycqhqpi6f12E_3ITyiwh,c7u9jSt5BwrmiVzHGbm87g * fix(tests): update setup wizard pool tests for unified select_provider_and_model flow The setup wizard now delegates to select_provider_and_model() instead of using its own prompt_choice-based provider picker. Tests needed: - Mock select_provider_and_model as no-op (provider pre-written to config) - Call _stub_tts BEFORE custom prompt_choice mock (it overwrites it) - Pre-write model.provider to config so the pool step is reached * docs: add comprehensive credential pool documentation - New page: website/docs/user-guide/features/credential-pools.md Full guide covering quick start, CLI commands, rotation strategies, error recovery, custom endpoint pools, auto-discovery, thread safety, architecture, and storage format. - Updated fallback-providers.md to reference credential pools as the first layer of resilience (same-provider rotation before cross-provider) - Added hermes auth to CLI commands reference with usage examples - Added credential_pool_strategies to configuration guide * chore: remove excalidraw diagram from repo (external link only) * refactor: simplify credential pool code — extract helpers, collapse extras, dedup patterns - _load_config_safe(): replace 4 identical try/except/import blocks - _iter_custom_providers(): shared generator for custom provider iteration - PooledCredential.extra dict: collapse 11 round-trip-only fields (token_type, scope, client_id, portal_base_url, obtained_at, expires_in, agent_key_id, agent_key_expires_in, agent_key_reused, agent_key_obtained_at, tls) into a single extra dict with __getattr__ for backward-compatible access - _available_entries(): shared exhaustion-check between select and peek - Dedup anthropic OAuth seeding (hermes_pkce + claude_code identical) - SimpleNamespace replaces class _Args boilerplate in auth_commands - _try_resolve_from_custom_pool(): shared pool-check in runtime_provider Net -17 lines. All 383 targeted tests pass. --------- Co-authored-by: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
This commit is contained in:
Teknium
@@ -54,6 +54,32 @@ def _set_default_model(config: Dict[str, Any], model_name: str) -> None:
|
||||
config["model"] = model_cfg
|
||||
|
||||
|
||||
def _get_credential_pool_strategies(config: Dict[str, Any]) -> Dict[str, str]:
|
||||
strategies = config.get("credential_pool_strategies")
|
||||
return dict(strategies) if isinstance(strategies, dict) else {}
|
||||
|
||||
|
||||
def _set_credential_pool_strategy(config: Dict[str, Any], provider: str, strategy: str) -> None:
|
||||
if not provider:
|
||||
return
|
||||
strategies = _get_credential_pool_strategies(config)
|
||||
strategies[provider] = strategy
|
||||
config["credential_pool_strategies"] = strategies
|
||||
|
||||
|
||||
def _supports_same_provider_pool_setup(provider: str) -> bool:
|
||||
if not provider or provider == "custom":
|
||||
return False
|
||||
if provider == "openrouter":
|
||||
return True
|
||||
from hermes_cli.auth import PROVIDER_REGISTRY
|
||||
|
||||
pconfig = PROVIDER_REGISTRY.get(provider)
|
||||
if not pconfig:
|
||||
return False
|
||||
return pconfig.auth_type in {"api_key", "oauth_device_code"}
|
||||
|
||||
|
||||
# Default model lists per provider — used as fallback when the live
|
||||
# /models endpoint can't be reached.
|
||||
_DEFAULT_PROVIDER_MODELS = {
|
||||
@@ -849,6 +875,85 @@ def setup_model_provider(config: dict):
|
||||
selected_provider = _m.get("provider")
|
||||
|
||||
|
||||
# ── Same-provider fallback & rotation setup ──
|
||||
if _supports_same_provider_pool_setup(selected_provider):
|
||||
try:
|
||||
from types import SimpleNamespace
|
||||
from agent.credential_pool import load_pool
|
||||
from hermes_cli.auth_commands import auth_add_command
|
||||
|
||||
pool = load_pool(selected_provider)
|
||||
entries = pool.entries()
|
||||
entry_count = len(entries)
|
||||
manual_count = sum(1 for entry in entries if str(getattr(entry, "source", "")).startswith("manual"))
|
||||
auto_count = entry_count - manual_count
|
||||
print()
|
||||
print_header("Same-Provider Fallback & Rotation")
|
||||
print_info(
|
||||
"Hermes can keep multiple credentials for one provider and rotate between"
|
||||
)
|
||||
print_info(
|
||||
"them when a credential is exhausted or rate-limited. This preserves"
|
||||
)
|
||||
print_info(
|
||||
"your primary provider while reducing interruptions from quota issues."
|
||||
)
|
||||
print()
|
||||
if auto_count > 0:
|
||||
print_info(
|
||||
f"Current pooled credentials for {selected_provider}: {entry_count} "
|
||||
f"({manual_count} manual, {auto_count} auto-detected from env/shared auth)"
|
||||
)
|
||||
else:
|
||||
print_info(f"Current pooled credentials for {selected_provider}: {entry_count}")
|
||||
|
||||
while prompt_yes_no("Add another credential for same-provider fallback?", False):
|
||||
auth_add_command(
|
||||
SimpleNamespace(
|
||||
provider=selected_provider,
|
||||
auth_type="",
|
||||
label=None,
|
||||
api_key=None,
|
||||
portal_url=None,
|
||||
inference_url=None,
|
||||
client_id=None,
|
||||
scope=None,
|
||||
no_browser=False,
|
||||
timeout=15.0,
|
||||
insecure=False,
|
||||
ca_bundle=None,
|
||||
min_key_ttl_seconds=5 * 60,
|
||||
)
|
||||
)
|
||||
pool = load_pool(selected_provider)
|
||||
entry_count = len(pool.entries())
|
||||
print_info(f"Provider pool now has {entry_count} credential(s).")
|
||||
|
||||
if entry_count > 1:
|
||||
strategy_labels = [
|
||||
"Fill-first / sticky — keep using the first healthy credential until it is exhausted",
|
||||
"Round robin — rotate to the next healthy credential after each selection",
|
||||
"Random — pick a random healthy credential each time",
|
||||
]
|
||||
current_strategy = _get_credential_pool_strategies(config).get(selected_provider, "fill_first")
|
||||
default_strategy_idx = {
|
||||
"fill_first": 0,
|
||||
"round_robin": 1,
|
||||
"random": 2,
|
||||
}.get(current_strategy, 0)
|
||||
strategy_idx = prompt_choice(
|
||||
"Select same-provider rotation strategy:",
|
||||
strategy_labels,
|
||||
default_strategy_idx,
|
||||
)
|
||||
strategy_value = ["fill_first", "round_robin", "random"][strategy_idx]
|
||||
_set_credential_pool_strategy(config, selected_provider, strategy_value)
|
||||
print_success(f"Saved {selected_provider} rotation strategy: {strategy_value}")
|
||||
else:
|
||||
_set_credential_pool_strategy(config, selected_provider, "fill_first")
|
||||
except Exception as exc:
|
||||
logger.debug("Could not configure same-provider fallback in setup: %s", exc)
|
||||
|
||||
# ── Vision & Image Analysis Setup ──
|
||||
# Keep setup aligned with the actual runtime resolver the vision tools use.
|
||||
try:
|
||||
|
||||
Reference in New Issue
Block a user