feat(reasoning): derive OpenRouter reasoning support and effort clamping from catalog metadata (prime-agent#1258 port)

[teknium1]

Summary

/reasoning ultra (or any effort) on an OpenRouter model now works for every reasoning-capable vendor — including ones we never hardcoded — and never 4xxes on a route that caps out at a lower level. Hermes reads OpenRouter's live model-catalog reasoning metadata (supported_parameters + per-model reasoning.supported_efforts/mandatory) to decide whether to emit reasoning controls and to clamp the requested effort to the nearest supported level (always downward, never a silent cost escalation).

Port of PrimeIntellect-ai/prime-agent#1258 ("derive reasoning levels from provider metadata"), adapted to Hermes' catalog/profile architecture.

How it fits what Hermes already has

• _supports_reasoning_extra_body() (run_agent.py) gated OpenRouter reasoning on a hand-maintained vendor-prefix allowlist that went stale one vendor at a time — nvidia/ missing is open issue [Bug]: reasoning_effort: none is ignored for NVIDIA models on OpenRouter #75386 with two competing 1-line PRs (fix(agent): reasoning_effort cannot disable Nemotron reasoning via OpenRouter — nvidia/ missing from allowlist (#75386) #75402/fix(agent): add nvidia/ to OpenRouter reasoning model prefixes (#75386) #75407); tencent/, xiaomi/ were earlier same-class additions. Catalog metadata is now the primary gate; the static list survives as the fallback for unknown/unlisted models and offline catalogs, so nothing regresses when the catalog is unreachable. This fixes the CLASS (any future vendor) instead of patching the predicate one prefix at a time.
• The OpenRouter profile's build_api_kwargs_extras passed reasoning_config through verbatim; routes that stop at high 4xx on ultra/max (issue Custom providers crash with /reasoning ultra (HTTP 422: unknown variant) #80242 shape). It now clamps to the nearest LOWER catalog-supported level, logging the downgrade at debug. The Claude-adaptive verbosity path (fix(anthropic): default new Claude models to the modern thinking contract #42991/reasoning_effort is a silent no-op for Claude Fable 5 (and 4.6+) over OpenRouter — verbosity never sent #43432) is untouched.
• Related open work this complements but does not duplicate: fix(copilot): clamp reasoning effort to nearest supported level instead of capping xhigh #51480 (Copilot-side clamping — different provider, GitHub catalog), Custom providers should map reasoning effort to each model’s supported levels #66543 (custom-provider effort mapping — custom providers have no catalog; unaffected here).

Changes

• hermes_cli/models.py: parse_openrouter_reasoning_capabilities() (entry normalization, trusts the reasoning object only when supported_parameters includes "reasoning"), process-lifetime caps cache with a 60s failure TTL, cache-only openrouter_model_reasoning_capabilities() (tri-state: supported / definitively-not / unknown), background warm_openrouter_reasoning_caps_async(), and clamp_reasoning_effort_to_supported() (nearest-lower semantics; unrecognized custom levels pass through).
• run_agent.py: _supports_reasoning_extra_body() consults catalog metadata first on the OpenRouter branch; unknown → existing static prefix list. Cold cache kicks the async warmer — the hot path never blocks on HTTP.
• plugins/model-providers/openrouter/__init__.py: _clamp_reasoning_to_catalog() applied to the emitted extra_body.reasoning.
• hermes_cli/models.py (fetch_openrouter_models): parses reasoning caps out of the catalog payload it already downloads, so picker/setup runs warm the cache for free.
• website/docs/user-guide/configuration.md: note under reasoning-effort docs.
• tests/hermes_cli/test_openrouter_reasoning_metadata.py: 30 tests — parsing, clamping table, cache/TTL/no-fetch-on-hot-path, metadata-first gate with static fallback (real AIAgent construction), and profile clamp wiring via get_provider_profile("openrouter").

Validation

Check	Result
New tests	30/30 pass
Sabotage run (metadata gate no-op'd)	2 gate tests fail as expected, restore → green
tests/providers/test_profile_wiring.py + tests/hermes_cli/test_models.py	42/42 pass
tests/run_agent/test_run_agent.py	242 pass; 1 pre-existing failure (test_interruptible_anthropic_interrupt_never_closes_shared_client, missing anthropic pkg locally — fails identically on clean main)
Windows-footgun scan + ruff	clean

Cache-safety: no system-prompt or message-history interaction — this only shapes per-request extra_body, same as the existing reasoning config path.

Infographic