fix(reasoning): use agent metadata for effort support

[starship-s]

Thinking Path

• fix(webui): route Cursor ACP and gate reasoning effort by model #2792 made the reasoning-effort chip model-aware, but the resolver still depends on WebUI-local provider/model heuristics for most providers.
• That leaves native/provider-specific catalogs behind: xAI OAuth Grok models such as grok-4.3 report no supported efforts even though Hermes Agent model metadata marks them reasoning-capable.
• The narrow fix is to keep the exact provider resolvers that need special behavior (ACP unsupported, Copilot/GitHub subsets, OpenAI Codex, LM Studio probing), then ask Hermes Agent's model metadata for the remaining providers before falling back to the existing compatibility heuristics.
• Metadata supports_reasoning=False is treated as authoritative so known non-reasoning variants do not get re-enabled by broad prefix heuristics.
• The no-query /api/reasoning boot path now resolves against the configured default model/provider so the chip can hydrate correctly before the frontend has passed explicit active-session model context.

What Changed

• Added a small _models_dev_reasoning_efforts() helper that reads agent.models_dev.get_model_capabilities() when available.
• Updated resolve_model_reasoning_efforts() to use that metadata after exact provider-specific resolvers and before compatibility heuristics.
• Preserved ACP unsupported behavior, Copilot/GitHub effort subset handling, OpenAI Codex handling, LM Studio live option probing, and existing heuristic fallback behavior when metadata is unavailable or unknown.
• Updated get_reasoning_status() so calls without explicit model/provider fall back to model.default, model.provider, and model.base_url from config.
• Added regression tests for xAI OAuth Grok metadata, authoritative non-reasoning metadata, heuristic fallback preservation, provider-hint stripping, and the no-query boot/default path.

Why It Matters

• Reasoning-capable native/provider-specific models can show the reasoning-effort chip without adding another WebUI-local prefix rule for every provider catalog shape.
• Known non-reasoning variants remain hidden when Agent metadata says they do not support reasoning.
• WebUI capability detection stays aligned with Hermes Agent's model knowledge instead of drifting into a duplicated hardcoded allowlist.
• Existing special cases that require non-boolean effort semantics remain intact.

Verification

Targeted reasoning capability suites:

python -m py_compile api/config.py tests/test_models_dev_reasoning.py
python -m pytest tests/test_models_dev_reasoning.py tests/test_reasoning_effort_model_capabilities.py tests/test_reasoning_show_hide.py -q
# 41 passed

Adjacent reasoning-chip suites:

python -m pytest tests/test_issue1103_reasoning_chip_visibility.py tests/test_reasoning_chip_btw_fixes.py tests/test_reasoning_chip_js_behaviour.py -q
# 38 passed

Hygiene:

git diff --check
# passed

Manual resolver smoke with the branch code:

xai-oauth @xai-oauth:grok-4.3 => minimal, low, medium, high, xhigh
xai-oauth @xai-oauth:grok-4.20-0309-reasoning => minimal, low, medium, high, xhigh
xai-oauth @xai-oauth:grok-4.20-0309-non-reasoning => []
openrouter x-ai/grok-4 => minimal, low, medium, high, xhigh

Risks / Follow-ups

• If agent.models_dev is unavailable in an install, WebUI keeps the existing compatibility heuristics.
• Metadata is boolean, so providers with narrower effort subsets still need exact resolvers before metadata; this PR preserves the existing exact resolver ordering for those providers.
• No frontend layout or interaction code changed; this is backend capability data feeding the existing chip visibility logic.

Model Used

• OpenAI / GPT-5.5 High for implementation, verification, and PR preparation.

[nesquena-hermes]

Summary

Read the diff at api/config.py and the new tests/test_models_dev_reasoning.py, then cross-referenced agent/models_dev.py:451-510 (get_model_capabilities) and tools/skill_usage.py from ~/.hermes/hermes-agent. The shape is sound: provider-specific exact resolvers stay in front (ACP → empty, Copilot/GitHub via github_model_reasoning_efforts, openai-codex, lmstudio probe), then _models_dev_reasoning_efforts(hinted_model, provider) consults the agent's models.dev cache, and _heuristic_reasoning_efforts is the last-resort fallback. The None vs [] convention is correct — None means "no metadata, keep falling back", [] from supports_reasoning=False is authoritative and suppresses the prefix heuristic.

Code reference

The new helper at api/config.py:2131-2161 is the key change:

def _models_dev_reasoning_efforts(model_id, provider_id):
    ...
    try:
        from agent.models_dev import get_model_capabilities
    except Exception:
        return None
    try:
        capabilities = get_model_capabilities(provider=provider, model=model)
    except Exception:
        return None
    if capabilities is None:
        return None
    supports_reasoning = getattr(capabilities, "supports_reasoning", None)
    if supports_reasoning is True:
        return list(VALID_REASONING_EFFORTS)
    if supports_reasoning is False:
        return []
    return None

That matches the agent contract: agent/models_dev.py:447 sets supports_reasoning = bool(entry.get("reasoning", False)), and xai-oauth → xai is in PROVIDER_TO_MODELS_DEV (models_dev.py:172), so the xAI Grok lookup actually resolves.

A couple of observations

1. LM Studio call now uses hinted_model where it previously used model. Before, the lmstudio branch passed the raw model (potentially @lmstudio:my-model) to lmstudio_model_reasoning_options. The diff changes it to hinted_model (stripped). hermes_cli/models.py:2753-2756 matches against raw.get("key") == model and raw.get("id") == model, and LM Studio's /api/v1/models returns bare model IDs, so stripping the hint is almost certainly the right behavior — but it is a subtle behavior change worth flagging in case anyone configured LM Studio with @lmstudio: hints relying on the prior pass-through.

2. The except Exception: return _heuristic_reasoning_efforts(...) import-failure branch now skips the lmstudio probe entirely. That's a regression-of-sorts only if hermes_cli.models fails to import but agent.models_dev succeeds — unlikely in practice since both ship in the same agent tree, but the structural change is that lmstudio capability detection is no longer reachable from the no-hermes_cli fallback path. Minor; the heuristic returns [] for lmstudio anyway so it's a no-op in practice.

3. The get_reasoning_status() boot-default resolution at api/config.py:2241-2252 is the meaningful UX win — previously a no-query /api/reasoning call (api/routes.py:4022-4033) returned supports_reasoning_effort: false because resolve_model_reasoning_efforts(None, None, None) exits early on empty model. Now it reads model.default / model.provider from config.yaml, so the chip hydrates correctly on initial page load before the active-session model context arrives.

Tests look right

The fake agent.models_dev module pattern in _install_fake_models_dev correctly isolates the test from network/disk caches. test_models_dev_false_suppresses_prefix_heuristic is the important regression guard — it confirms x-ai/grok-4-non-reasoning with supports_reasoning=False returns [] instead of falling through to the x-ai/ prefix in _heuristic_reasoning_efforts (api/config.py:2119).

Verdict

Looks good to merge. The ordering preserves all the provider-specific behavior (Copilot subsets, Codex, LM Studio probe) and only fills the gap that the prefix-heuristic was masking. CI is green across 3.11/3.12/3.13.

[nesquena-hermes]

Absorbed via stage-batch32 (PR #3036) and shipped as v0.51.150. Thanks for threading agent metadata through the resolver — xAI OAuth Grok models and other models.dev-backed providers now show the reasoning-effort chip without a per-provider WebUI allowlist update.

Opus advisor confirmed the order of precedence is correct (authoritative resolvers still return first, metadata sits between them and the heuristic fallback) and that both import and call sites are bare-except guarded so older hermes-agent installs without models_dev fall through cleanly.

Two non-blocking follow-ups for a future PR if you want to take them:

1. Add a model.reasoning_efforts_force_supported: true config knob so a user can override an authoritative-supports_reasoning=False when the models.dev cache is stale.
2. Add a direct ImportError-branch test (monkeypatch.setitem(sys.modules, "agent.models_dev", None)) — the existing "metadata returns None" tests cover the same downstream behavior via a different upstream return path.

Also: the LMStudio probe arg change (model → hinted_model at api/config.py:2208) was a real drive-by bug fix — worth a separate CHANGELOG line in the follow-up.