Files

teknium1 eeb220d40c fix: model-provider plugins resolve per bound profile home (#88143 )

Symptom: a model-provider plugin installed with `hermes plugins install`
(e.g. claude-subscription-directsdk) worked from a terminal but the Desktop
app failed every session build with "Unknown provider '<name>'".

Cause: `providers/__init__.py` scanned `$HERMES_HOME/plugins` exactly once
per process, under whichever profile home happened to be bound at the first
lookup, and the registry was global. The Desktop backend and the multiplex
gateway serve several profiles from one process, so any profile other than
the first-discovered one never saw its own plugins, and a plugin installed
while the process ran was invisible until a restart.

Change: bundled, pip and legacy providers stay process-wide; `$HERMES_HOME`
plugins load into a per-home layer keyed by `hermes_home_key()` at lookup
time (`get_provider_profile`, `list_providers`, `provider_source`). The
layer rescans when the plugin directories' mtimes change, so a fresh install
is found on the next lookup. The registration target is a ContextVar so two
turn threads scanning two homes cannot cross-register, and no lock is held
across plugin imports (a lock there could deadlock against a thread
mid-`import hermes_cli.auth`). Per-home module names let two profiles carry
the same plugin. `plugin_dev` reuses the module-name helper.

Live repro (tui_gateway `session.create` on a secondary profile whose config
selects a plugin installed only there): base -> agent_error "Unknown
provider 'fakeprov-b'"; fixed -> provider resolves and the build proceeds to
the plugin's own runtime check.

2026-09-21 18:38:36 -07:00

__init__.py

fix: model-provider plugins resolve per bound profile home (#88143 )

2026-09-21 18:38:36 -07:00

base.py

fix: send reasoning_effort=medium on custom endpoints when agent.reasoning_effort is unset

2026-09-20 16:03:38 -07:00

README.md

…

README.md

providers/

Registry and ABC for every inference provider Hermes knows about.

Each provider is declared once as a ProviderProfile. Every other layer — auth resolution, transport kwargs, model listing, runtime routing — reads from these profiles instead of maintaining its own parallel data.

Layout

providers/
├── base.py         ProviderProfile dataclass + OMIT_TEMPERATURE sentinel
├── __init__.py     Registry: register_provider(), get_provider_profile(), list_providers()
└── README.md       This file

The profiles themselves live as plugins under plugins/model-providers/<name>/ (bundled in this repo) and $HERMES_HOME/plugins/model-providers/<name>/ (per-user overrides). The registry in providers/__init__.py lazily discovers them the first time any consumer calls get_provider_profile() or list_providers(). See plugins/model-providers/README.md for the plugin contract and examples.

How it wires in

The registry is populated on first access. After that, every downstream layer reads from it:

hermes_cli/auth.py extends PROVIDER_REGISTRY with every api-key profile it sees (skipping copilot, kimi-coding, kimi-coding-cn, zai, openrouter, custom — those need bespoke token resolution).
hermes_cli/models.py extends CANONICAL_PROVIDERS and calls profile.fetch_models() inside provider_model_ids().
hermes_cli/doctor.py adds a /models health check for each auth_type="api_key" profile.
hermes_cli/config.py injects every env_var into OPTIONAL_ENV_VARS so the setup wizard knows about it.
hermes_cli/runtime_provider.py reads profile.api_mode as a fallback when URL detection finds nothing.
agent/model_metadata.py maps hostname → provider via profile.get_hostname().
agent/auxiliary_client.py reads profile.default_aux_model first before falling back to the legacy hardcoded dict.
agent/transports/chat_completions.py::_build_kwargs_from_profile() invokes profile.prepare_messages(), profile.build_extra_body(), and profile.build_api_kwargs_extras() on every call.
run_agent.py passes provider_profile=<ProviderProfile> so the transport takes the profile path instead of the legacy flag path.

Adding a provider

See plugins/model-providers/README.md — drop a new directory there (or under $HERMES_HOME/plugins/model-providers/ for a private plugin).

Hooks you can override on `ProviderProfile`

Hook	Purpose
`get_hostname()`	URL-based detection — default derives from `base_url`.
`prepare_messages(msgs)`	Provider-specific message preprocessing (Qwen normalises to list-of-parts, injects `cache_control`).
`build_extra_body(**ctx)`	Provider-specific `extra_body` (OpenRouter provider prefs, Gemini `thinking_config`).
`build_api_kwargs_extras(**ctx)`	`(extra_body_additions, top_level_kwargs)` — Kimi puts reasoning_effort top-level, Qwen splits `enable_thinking`/`thinking_budget`.
`supported_reasoning_efforts(model)`	Declared per-model reasoning-effort vocabulary for gateways that 400 on unknown levels (Ramp Router reads its live catalog). `None` = defer to transport defaults, `()` = model takes no reasoning params, tuple = clamp target. Must be cache-only — called on the request hot path.
`fetch_models(*, api_key)`	Live catalog fetch — default hits `{models_url or base_url}/models` with Bearer auth. Override for no-REST providers (Bedrock), OAuth catalogs (Anthropic), or public catalogs (OpenRouter).

Configuration fields

Full reference in providers/base.py dataclass definition.

README.md

providers/

Layout

How it wires in

Adding a provider

Hooks you can override on ProviderProfile

Configuration fields

Hooks you can override on `ProviderProfile`