🙌 OpenHands: AI-Driven Development
feat: OHE multi-model LLM discovery + BYOK gating (proxy discovery, catalogue union, UX) (#14773)
Alonaa6bce82148c6
diff --git a/enterprise/server/verified_models/litellm_proxy_model_router.py b/enterprise/server/verified_models/litellm_proxy_model_router.pynew file mode 100644index 0000000000..a037721d1f--- /dev/null+++ b/enterprise/server/verified_models/litellm_proxy_model_router.py@@ -0,0 +1,291 @@+"""LiteLLM-proxy-backed LLM model discovery for self-hosted enterprise (OHE).++Self-hosted enterprise installs bundle a LiteLLM proxy, and the set of models+that actually works for a customer is exactly the set configured on that+proxy. This service discovers models from the proxy's ``GET /model/info``+endpoint instead of unioning the static litellm catalogue and the SaaS+``verified_models`` database table, so the model dropdown only shows models+that genuinely exist on the customer's proxy.++Activate via the environment variable::++ OH_LLM_MODEL_KIND=server.verified_models.litellm_proxy_model_router.LiteLLMProxyModelServiceInjector+"""++import asyncio+import logging+import time+from typing import Any, AsyncGenerator, ClassVar++import httpx+from fastapi import Request+from server.constants import (+ LITE_LLM_API_KEY,+ LITE_LLM_API_URL,+ get_default_litellm_model,+)++from openhands.app_server.config_api.default_llm_model_service import (+ DefaultLLMModelService,+)+from openhands.app_server.config_api.llm_model_service import (+ LLMModelService,+ LLMModelServiceInjector,+)+from openhands.app_server.services.injector import InjectorState+from openhands.app_server.utils.http_session import httpx_verify_option+from openhands.app_server.utils.llm import ModelsResponse, get_supported_llm_models++_logger = logging.getLogger(__name__)++# Timeout (seconds) for the proxy /model/info request.+MODEL_INFO_TIMEOUT = 5.0+# How long (seconds) a successful discovery result is reused before refetching.+CACHE_TTL_SECONDS = 60.0++# The proxy-transport prefix used by LITELLM_DEFAULT_MODEL.+_LITELLM_PROXY_PREFIX = 'litellm_proxy/'+# The public/stored prefix used by the app. The SDK translates+# ``openhands/`` -> ``litellm_proxy/`` at the transport boundary.+_OPENHANDS_PREFIX = 'openhands/'+++def _derive_default_model() -> str:+ """Translate the env-derived default model to the public prefix.++ ``LITELLM_DEFAULT_MODEL`` holds the default as ``litellm_proxy/<name>``;+ the app stores and displays models as ``openhands/<name>``. An already-+ ``openhands/``-prefixed default is kept as-is; a bare name is prefixed.+ """+ default = get_default_litellm_model()+ if default.startswith(_LITELLM_PROXY_PREFIX):+ return _OPENHANDS_PREFIX + default[len(_LITELLM_PROXY_PREFIX) :]+ if default.startswith(_OPENHANDS_PREFIX):+ return default+ return _OPENHANDS_PREFIX + default+++class LiteLLMProxyModelService(DefaultLLMModelService):+ """Model discovery backed by the bundled LiteLLM proxy.++ Inherits filtering, pagination, and provider logic from+ ``DefaultLLMModelService`` — only the model list source is different.++ Results are cached at class level (the injector creates a new service per+ request) with a short TTL. On fetch failure the last-good result is+ served regardless of age; if there has never been a successful fetch an+ empty model list is returned. Discovery never raises out of the request+ path just because the proxy is briefly unreachable.+ """++ # Shared across instances; one service instance is created per request.+ _shared_response: ClassVar[ModelsResponse | None] = None+ _shared_fetched_at: ClassVar[float] = 0.0+ _fetch_lock: ClassVar[asyncio.Lock] = asyncio.Lock()++ @classmethod+ def _reset_cache(cls) -> None:+ """Clear the shared cache (intended for tests)."""+ cls._shared_response = None+ cls._shared_fetched_at = 0.0++ @staticmethod+ def _now() -> float:+ """Monotonic clock; isolated for tests."""+ return time.monotonic()++ async def _fetch_proxy_model_names(+ self,+ ) -> tuple[list[str], list[str], dict[str, str]]:+ """Fetch ``(visible, hidden, canonicals)`` model names from the proxy.++ Entries flagged ``model_info.openhands_hidden`` (legacy alias routes+ the proxy still serves after a rename) are collected separately: they+ must not be offered as dropdown options, but a saved setting that+ references one is still valid. A hidden entry may carry+ ``model_info.openhands_canonical`` naming the visible route it+ aliases; ``canonicals`` maps hidden name -> canonical name, dropping+ mappings whose target is not among the visible names. A duplicated+ ``model_name`` is an intentional load-balanced deployment — it is+ reported once, and is hidden only when *every* entry carrying that+ name is hidden. Proxy order is preserved. ``litellm_params`` are+ never propagated.+ """+ url = LITE_LLM_API_URL.rstrip('/') + '/model/info'+ headers: dict[str, str] = {}+ if LITE_LLM_API_KEY:+ headers['Authorization'] = f'Bearer {LITE_LLM_API_KEY}'+ async with httpx.AsyncClient(+ verify=httpx_verify_option(), timeout=MODEL_INFO_TIMEOUT+ ) as client:+ response = await client.get(url, headers=headers)+ response.raise_for_status()+ payload = response.json()++ order: list[str] = []+ hidden_by_name: dict[str, bool] = {}+ canonical_by_name: dict[str, str] = {}+ for entry in payload.get('data') or []:+ if not isinstance(entry, dict):+ continue+ name = entry.get('model_name')+ if not name or not isinstance(name, str):+ continue+ model_info: Any = entry.get('model_info') or {}+ hidden = isinstance(model_info, dict) and bool(+ model_info.get('openhands_hidden')+ )+ if hidden and name not in canonical_by_name:+ canonical = model_info.get('openhands_canonical')+ if canonical and isinstance(canonical, str):+ canonical_by_name[name] = canonical+ if name not in hidden_by_name:+ order.append(name)+ hidden_by_name[name] = hidden+ elif not hidden:+ # Any visible deployment makes the name visible.+ hidden_by_name[name] = False+ visible = [name for name in order if not hidden_by_name[name]]+ hidden_names = [name for name in order if hidden_by_name[name]]+ visible_set = set(visible)+ canonicals = {+ name: canonical_by_name[name]+ for name in hidden_names+ if canonical_by_name.get(name) in visible_set+ }+ return visible, hidden_names, canonicals++ @staticmethod+ def _build_response(+ model_names: list[str],+ hidden_model_names: list[str] | None = None,+ hidden_model_canonicals: dict[str, str] | None = None,+ ) -> ModelsResponse:+ return ModelsResponse(+ models=[_OPENHANDS_PREFIX + name for name in model_names],+ verified_models=list(model_names),+ verified_providers=['openhands'],+ default_model=_derive_default_model(),+ hidden_models=[+ _OPENHANDS_PREFIX + name for name in hidden_model_names or []+ ],+ hidden_model_canonicals={+ _OPENHANDS_PREFIX + alias: _OPENHANDS_PREFIX + canonical+ for alias, canonical in (hidden_model_canonicals or {}).items()+ },+ )++ async def _byok_enabled(self) -> bool:+ """Whether BYOK is on. Read from the resolved web-client config so+ discovery and the UI gate agree on the same value."""+ from openhands.app_server.config import get_global_config++ config = await get_global_config().web_client.get_web_client_config()+ return config.feature_flags.allow_user_llm_configuration++ async def _union_with_catalogue(+ self, proxy_response: ModelsResponse+ ) -> ModelsResponse:+ """BYOK on: add the full SDK provider catalogue so users can pick any+ provider and bring their own key (matches SaaS). Proxy models stay the+ managed/verified set; catalogue models land unverified ("Other"). BYOK+ off: return the managed proxy list unchanged."""+ if not await self._byok_enabled():+ return proxy_response+ catalogue = get_supported_llm_models()+ proxy_models = set(proxy_response.models)+ extra = [+ m+ for m in catalogue.models+ if not m.startswith(_OPENHANDS_PREFIX) and m not in proxy_models+ ]+ return ModelsResponse(+ models=proxy_response.models + extra,+ verified_models=proxy_response.verified_models,+ verified_providers=proxy_response.verified_providers,+ default_model=proxy_response.default_model,+ hidden_models=proxy_response.hidden_models,+ hidden_model_canonicals=proxy_response.hidden_model_canonicals,+ )++ def _is_model_verified(+ self, model_name: str, name: str, models_response: ModelsResponse+ ) -> bool:+ # Managed proxy models are verified; the unioned SDK catalogue (BYOK)+ # is not. Require the openhands/ prefix so a catalogue model whose bare+ # name collides with a proxy one (openai/gpt-5 vs proxy gpt-5) isn't+ # falsely verified.+ return model_name.startswith(_OPENHANDS_PREFIX) and name in set(+ models_response.verified_models+ )++ async def _get_models_response(+ self,+ verified_models: list[str] | None = None,+ ) -> ModelsResponse:+ cls = LiteLLMProxyModelService+ response = cls._shared_response+ if (+ response is not None+ and self._now() - cls._shared_fetched_at < CACHE_TTL_SECONDS+ ):+ return response++ async with cls._fetch_lock:+ # Re-check after acquiring the lock — a concurrent request may+ # have refreshed the cache while this one was waiting.+ response = cls._shared_response+ if (+ response is not None+ and self._now() - cls._shared_fetched_at < CACHE_TTL_SECONDS+ ):+ return response++ try:+ (+ model_names,+ hidden_model_names,+ hidden_model_canonicals,+ ) = await self._fetch_proxy_model_names()+ except Exception:+ if response is not None:+ # Serve the last-good result regardless of age. The next+ # request retries because the timestamp is not refreshed.+ _logger.warning(+ 'Failed to fetch models from the LiteLLM proxy; '+ 'serving the last successful result',+ exc_info=True,+ )+ return response+ _logger.error(+ 'Failed to fetch models from the LiteLLM proxy and no '+ 'previous result is cached; returning an empty model list',+ exc_info=True,+ )+ # Not cached, so the next request retries immediately. Still+ # union the catalogue so BYOK users can bring a key while the+ # proxy is unreachable.+ return await self._union_with_catalogue(self._build_response([]))++ response = await self._union_with_catalogue(+ self._build_response(+ model_names, hidden_model_names, hidden_model_canonicals+ )+ )+ cls._shared_response = response+ cls._shared_fetched_at = self._now()+ return response+++class LiteLLMProxyModelServiceInjector(LLMModelServiceInjector):+ """Injector that provides the LiteLLM-proxy-backed model service.++ Activate via the environment variable::++ OH_LLM_MODEL_KIND=server.verified_models.litellm_proxy_model_router.LiteLLMProxyModelServiceInjector+ """++ async def inject(+ self, state: InjectorState, request: Request | None = None+ ) -> AsyncGenerator[LLMModelService, None]:+ yield LiteLLMProxyModelService()diff --git a/enterprise/tests/unit/test_verified_model/test_litellm_proxy_model_service.py b/enterprise/tests/unit/test_verified_model/test_litellm_proxy_model_service.pynew file mode 100644index 0000000000..c9782381cb--- /dev/null+++ b/enterprise/tests/unit/test_verified_model/test_litellm_proxy_model_service.py@@ -0,0 +1,525 @@+"""Unit tests for the LiteLLM-proxy-backed model discovery service."""++import logging++import httpx+import pytest+from server.verified_models import litellm_proxy_model_router as router_module+from server.verified_models.litellm_proxy_model_router import (+ LiteLLMProxyModelService,+ LiteLLMProxyModelServiceInjector,+ _derive_default_model,+)++from openhands.app_server.utils.llm import ModelsResponse++LOGGER_NAME = 'server.verified_models.litellm_proxy_model_router'++HAPPY_PAYLOAD = {+ 'data': [+ {+ 'model_name': 'claude-sonnet-4-5',+ 'litellm_params': {'model': 'anthropic/claude-sonnet-4-5'},+ 'model_info': {'openhands_default': True},+ },+ {+ 'model_name': 'hidden-model',+ 'litellm_params': {'model': 'openai/gpt-5'},+ 'model_info': {+ 'openhands_hidden': True,+ 'openhands_canonical': 'claude-sonnet-4-5',+ },+ },+ {+ # Duplicate of the first entry — a load-balanced deployment.+ 'model_name': 'claude-sonnet-4-5',+ 'litellm_params': {'model': 'bedrock/claude-sonnet-4-5'},+ 'model_info': {},+ },+ {+ 'model_name': 'gpt-5',+ 'litellm_params': {'model': 'openai/gpt-5'},+ 'model_info': {},+ },+ {+ # Entry without a model_name is skipped.+ 'litellm_params': {'model': 'openai/gpt-4o'},+ },+ 'not-a-dict',+ ]+}+++class FakeResponse:+ def __init__(self, payload, status_code: int = 200):+ self._payload = payload+ self.status_code = status_code++ def raise_for_status(self):+ if self.status_code >= 400:+ raise httpx.HTTPStatusError(+ f'HTTP {self.status_code}',+ request=httpx.Request('GET', 'http://litellm.test/model/info'),+ response=httpx.Response(self.status_code),+ )++ def json(self):+ return self._payload+++def make_fake_client(response=None, error=None):+ """Build a fake httpx.AsyncClient class that records calls."""++ calls: list[dict] = []++ class FakeAsyncClient:+ def __init__(self, **kwargs):+ self.init_kwargs = kwargs++ async def __aenter__(self):+ return self++ async def __aexit__(self, *exc_info):+ return False++ async def get(self, url, headers=None):+ calls.append({'url': url, 'headers': headers or {}})+ if error is not None:+ raise error+ return response++ return FakeAsyncClient, calls++[email protected](autouse=True)+def reset_cache():+ LiteLLMProxyModelService._reset_cache()+ yield+ LiteLLMProxyModelService._reset_cache()++[email protected](autouse=True)+def proxy_env(monkeypatch):+ monkeypatch.setattr(router_module, 'LITE_LLM_API_URL', 'http://litellm.test')+ monkeypatch.setattr(router_module, 'LITE_LLM_API_KEY', 'test-master-key')+ monkeypatch.setattr(+ router_module,+ 'get_default_litellm_model',+ lambda: 'litellm_proxy/claude-sonnet-4-5',+ )++[email protected](autouse=True)+def byok_off(monkeypatch):+ """Default BYOK off so the proxy-only tests are unaffected; the union+ tests opt in via ``byok_on``. (BYOK defaults *on* in real config, so+ without this every test would hit the real web-client config lookup.)"""++ async def _off(self):+ return False++ monkeypatch.setattr(LiteLLMProxyModelService, '_byok_enabled', _off)+++# A deterministic stand-in for the SDK catalogue. Two bare names collide with+# the proxy's (``gpt-5``, ``claude-sonnet-4-5``) to exercise the verified-flag+# guard; an ``openhands/``-prefixed entry must be dropped from the union.+STUB_CATALOGUE = ModelsResponse(+ models=[+ 'anthropic/claude-sonnet-4-5',+ 'openai/gpt-5',+ 'openai/gpt-4o',+ 'gemini/gemini-2.0-flash',+ 'openhands/should-be-dropped',+ ],+ verified_models=['anthropic/claude-sonnet-4-5'],+ verified_providers=['anthropic'],+ default_model='anthropic/claude-sonnet-4-5',+ hidden_models=[],+ hidden_model_canonicals={},+)+++def byok_on(monkeypatch, catalogue=STUB_CATALOGUE):+ """Turn BYOK on and pin the SDK catalogue the union pulls from."""++ async def _on(self):+ return True++ monkeypatch.setattr(LiteLLMProxyModelService, '_byok_enabled', _on)+ monkeypatch.setattr(+ router_module, 'get_supported_llm_models', lambda *a, **k: catalogue+ )+++def fake_clock(monkeypatch):+ """Controllable monotonic clock injected into the service."""+ state = {'now': 1000.0}+ monkeypatch.setattr(+ LiteLLMProxyModelService, '_now', staticmethod(lambda: state['now'])+ )+ return state+++def install_client(monkeypatch, response=None, error=None):+ fake_client, calls = make_fake_client(response=response, error=error)+ monkeypatch.setattr(router_module.httpx, 'AsyncClient', fake_client)+ return calls+++class TestHappyPath:+ async def test_models_response_shape(self, monkeypatch):+ calls = install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))+ service = LiteLLMProxyModelService()++ response = await service._get_models_response()++ # Hidden models kept out of the visible list, duplicates removed,+ # proxy order preserved, every model exposed under the public+ # openhands/ prefix.+ assert response.models == ['openhands/claude-sonnet-4-5', 'openhands/gpt-5']+ assert response.verified_models == ['claude-sonnet-4-5', 'gpt-5']+ assert response.verified_providers == ['openhands']+ # Hidden alias routes are still reported so saved settings that+ # reference them count as available.+ assert response.hidden_models == ['openhands/hidden-model']+ # The alias carries its canonical mapping (canonical is visible).+ assert response.hidden_model_canonicals == {+ 'openhands/hidden-model': 'openhands/claude-sonnet-4-5'+ }+ # litellm_proxy/ prefix translated to openhands/.+ assert response.default_model == 'openhands/claude-sonnet-4-5'++ assert len(calls) == 1+ assert calls[0]['url'] == 'http://litellm.test/model/info'+ assert calls[0]['headers']['Authorization'] == 'Bearer test-master-key'++ async def test_search_llm_models_uses_proxy_models(self, monkeypatch):+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))+ service = LiteLLMProxyModelService()++ page = await service.search_llm_models()++ names = [(m.provider, m.name, m.hidden, m.canonical) for m in page.items]+ assert names == [+ ('openhands', 'claude-sonnet-4-5', False, None),+ ('openhands', 'gpt-5', False, None),+ # Hidden alias routes ride along flagged hidden=True so the+ # frontend can exclude them from dropdown options while still+ # treating saved settings that reference them as available;+ # canonical names the visible model the alias routes to.+ ('openhands', 'hidden-model', True, 'claude-sonnet-4-5'),+ ]++ async def test_hidden_only_when_all_duplicate_entries_hidden(self, monkeypatch):+ # A load-balanced group is hidden only when every deployment that+ # carries the name is hidden; one visible entry wins.+ payload = {+ 'data': [+ {+ 'model_name': 'mixed-model',+ 'model_info': {'openhands_hidden': True},+ },+ {'model_name': 'mixed-model', 'model_info': {}},+ {+ 'model_name': 'legacy-alias',+ 'model_info': {'openhands_hidden': True},+ },+ {+ # Duplicate hidden entry — reported once.+ 'model_name': 'legacy-alias',+ 'model_info': {'openhands_hidden': True},+ },+ ]+ }+ install_client(monkeypatch, response=FakeResponse(payload))+ service = LiteLLMProxyModelService()++ response = await service._get_models_response()++ assert response.models == ['openhands/mixed-model']+ assert response.hidden_models == ['openhands/legacy-alias']+ # No openhands_canonical tags anywhere -> no mappings.+ assert response.hidden_model_canonicals == {}++ async def test_canonical_skipped_when_not_visible(self, monkeypatch):+ # A canonical tag pointing at a name the proxy does not serve+ # visibly is dropped; a tag on a visible entry is ignored.+ payload = {+ 'data': [+ {'model_name': 'real-model', 'model_info': {}},+ {+ 'model_name': 'alias-to-missing',+ 'model_info': {+ 'openhands_hidden': True,+ 'openhands_canonical': 'removed-model',+ },+ },+ {+ 'model_name': 'alias-to-hidden',+ 'model_info': {+ 'openhands_hidden': True,+ 'openhands_canonical': 'other-alias',+ },+ },+ {+ 'model_name': 'other-alias',+ 'model_info': {'openhands_hidden': True},+ },+ ]+ }+ install_client(monkeypatch, response=FakeResponse(payload))+ service = LiteLLMProxyModelService()++ response = await service._get_models_response()++ assert response.models == ['openhands/real-model']+ assert response.hidden_models == [+ 'openhands/alias-to-missing',+ 'openhands/alias-to-hidden',+ 'openhands/other-alias',+ ]+ assert response.hidden_model_canonicals == {}++ page = await service.search_llm_models()+ assert all(m.canonical is None for m in page.items)++ async def test_canonical_mapped_for_visible_target(self, monkeypatch):+ payload = {+ 'data': [+ {'model_name': 'real-model', 'model_info': {}},+ {+ 'model_name': 'legacy-alias',+ 'model_info': {+ 'openhands_hidden': True,+ 'openhands_canonical': 'real-model',+ },+ },+ {+ # Hidden alias without a canonical tag -> no mapping.+ 'model_name': 'untagged-alias',+ 'model_info': {'openhands_hidden': True},+ },+ ]+ }+ install_client(monkeypatch, response=FakeResponse(payload))+ service = LiteLLMProxyModelService()++ response = await service._get_models_response()++ assert response.hidden_model_canonicals == {+ 'openhands/legacy-alias': 'openhands/real-model'+ }++ async def test_search_providers_only_openhands(self, monkeypatch):+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))+ service = LiteLLMProxyModelService()++ page = await service.search_providers()++ assert [(p.name, p.verified) for p in page.items] == [('openhands', True)]++ async def test_no_auth_header_without_key(self, monkeypatch):+ monkeypatch.setattr(router_module, 'LITE_LLM_API_KEY', None)+ calls = install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))+ service = LiteLLMProxyModelService()++ await service._get_models_response()++ assert 'Authorization' not in calls[0]['headers']+++class TestDefaultModelTranslation:+ def test_litellm_proxy_prefix_translated(self, monkeypatch):+ monkeypatch.setattr(+ router_module, 'get_default_litellm_model', lambda: 'litellm_proxy/gpt-5'+ )+ assert _derive_default_model() == 'openhands/gpt-5'++ def test_openhands_prefix_preserved(self, monkeypatch):+ monkeypatch.setattr(+ router_module, 'get_default_litellm_model', lambda: 'openhands/gpt-5'+ )+ assert _derive_default_model() == 'openhands/gpt-5'++ def test_bare_name_prefixed(self, monkeypatch):+ monkeypatch.setattr(router_module, 'get_default_litellm_model', lambda: 'gpt-5')+ assert _derive_default_model() == 'openhands/gpt-5'+++class TestFailurePaths:+ async def test_cold_failure_returns_empty_without_raising(+ self, monkeypatch, caplog+ ):+ install_client(monkeypatch, error=httpx.ConnectError('boom'))+ service = LiteLLMProxyModelService()++ with caplog.at_level(logging.ERROR, logger=LOGGER_NAME):+ response = await service._get_models_response()++ assert response.models == []+ assert response.verified_models == []+ assert response.hidden_models == []+ assert response.hidden_model_canonicals == {}+ # The env-derived default is still communicated.+ assert response.default_model == 'openhands/claude-sonnet-4-5'+ assert any(+ 'no previous result is cached' in record.message+ for record in caplog.records+ )++ async def test_cold_failure_is_not_cached(self, monkeypatch):+ install_client(monkeypatch, error=httpx.ConnectError('boom'))+ service = LiteLLMProxyModelService()+ assert (await service._get_models_response()).models == []++ # The proxy recovers; the very next request succeeds (the failure+ # result was not cached).+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))+ response = await LiteLLMProxyModelService()._get_models_response()+ assert response.models == ['openhands/claude-sonnet-4-5', 'openhands/gpt-5']++ async def test_http_error_status_returns_empty(self, monkeypatch):+ install_client(monkeypatch, response=FakeResponse({}, status_code=500))+ service = LiteLLMProxyModelService()++ response = await service._get_models_response()++ assert response.models == []++ async def test_stale_cache_served_on_failure(self, monkeypatch, fake_clock, caplog):+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))+ first = await LiteLLMProxyModelService()._get_models_response()+ assert first.models == ['openhands/claude-sonnet-4-5', 'openhands/gpt-5']++ # Far beyond the TTL the proxy starts failing — the last-good result+ # is served regardless of age.+ fake_clock['now'] += 10_000.0+ install_client(monkeypatch, error=httpx.ConnectError('boom'))+ with caplog.at_level(logging.WARNING, logger=LOGGER_NAME):+ second = await LiteLLMProxyModelService()._get_models_response()++ assert second is first+ assert any(+ 'serving the last successful result' in record.message+ for record in caplog.records+ )+++class TestCacheTtl:+ async def test_within_ttl_no_refetch(self, monkeypatch, fake_clock):+ calls = install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))+ first = await LiteLLMProxyModelService()._get_models_response()++ fake_clock['now'] += router_module.CACHE_TTL_SECONDS - 1.0+ second = await LiteLLMProxyModelService()._get_models_response()++ assert second is first+ assert len(calls) == 1++ async def test_after_ttl_refetches(self, monkeypatch, fake_clock):+ calls = install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))+ await LiteLLMProxyModelService()._get_models_response()++ fake_clock['now'] += router_module.CACHE_TTL_SECONDS + 1.0+ updated_payload = {'data': [{'model_name': 'new-model', 'model_info': {}}]}+ calls2 = install_client(monkeypatch, response=FakeResponse(updated_payload))+ response = await LiteLLMProxyModelService()._get_models_response()++ assert len(calls) == 1+ assert len(calls2) == 1+ assert response.models == ['openhands/new-model']+++class TestByokUnion:+ """BYOK on unions the SDK catalogue so users can bring their own provider+ (SaaS parity); BYOK off keeps the managed proxy list only."""++ async def test_byok_off_ignores_catalogue(self, monkeypatch):+ # Catalogue is available but BYOK is off (autouse default) -> proxy only.+ monkeypatch.setattr(+ router_module, 'get_supported_llm_models', lambda *a, **k: STUB_CATALOGUE+ )+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))++ response = await LiteLLMProxyModelService()._get_models_response()++ assert response.models == ['openhands/claude-sonnet-4-5', 'openhands/gpt-5']++ async def test_byok_on_unions_catalogue(self, monkeypatch):+ byok_on(monkeypatch)+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))++ response = await LiteLLMProxyModelService()._get_models_response()++ # Managed proxy models first (order preserved), then catalogue extras;+ # the openhands/-prefixed catalogue entry is dropped.+ assert response.models == [+ 'openhands/claude-sonnet-4-5',+ 'openhands/gpt-5',+ 'anthropic/claude-sonnet-4-5',+ 'openai/gpt-5',+ 'openai/gpt-4o',+ 'gemini/gemini-2.0-flash',+ ]+ assert len(response.models) == len(set(response.models))+ # Proxy stays the verified/default authority; catalogue opinions ignored.+ assert response.verified_models == ['claude-sonnet-4-5', 'gpt-5']+ assert response.verified_providers == ['openhands']+ assert response.default_model == 'openhands/claude-sonnet-4-5'++ async def test_byok_on_only_managed_models_verified(self, monkeypatch):+ # Regression: a catalogue model whose bare name collides with a proxy+ # one (openai/gpt-5 vs proxy gpt-5; anthropic/claude-sonnet-4-5 vs+ # proxy claude-sonnet-4-5) must NOT be marked verified.+ byok_on(monkeypatch)+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))++ page = await LiteLLMProxyModelService().search_llm_models()+ verified = {+ (m.provider, m.name) for m in page.items if m.verified and not m.hidden+ }++ assert verified == {('openhands', 'claude-sonnet-4-5'), ('openhands', 'gpt-5')}++ async def test_byok_on_exposes_catalogue_providers(self, monkeypatch):+ byok_on(monkeypatch)+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))++ page = await LiteLLMProxyModelService().search_providers()++ # openhands stays the verified managed provider, listed first; catalogue+ # providers ride along unverified so the picker shows for BYOK users.+ assert [(p.name, p.verified) for p in page.items] == [+ ('openhands', True),+ ('anthropic', False),+ ('gemini', False),+ ('openai', False),+ ]++ async def test_byok_on_serves_catalogue_when_proxy_down(self, monkeypatch):+ # Proxy unreachable + BYOK on: no managed models, but the catalogue is+ # still offered so a BYOK user can bring their own key.+ byok_on(monkeypatch)+ install_client(monkeypatch, error=httpx.ConnectError('boom'))++ response = await LiteLLMProxyModelService()._get_models_response()++ assert response.models == [+ 'anthropic/claude-sonnet-4-5',+ 'openai/gpt-5',+ 'openai/gpt-4o',+ 'gemini/gemini-2.0-flash',+ ]+ assert response.verified_models == []+++class TestInjector:+ async def test_injector_yields_service(self):+ injector = LiteLLMProxyModelServiceInjector()+ generator = injector.inject(None) # type: ignore[arg-type]+ service = await generator.__anext__()+ assert isinstance(service, LiteLLMProxyModelService)+ with pytest.raises(StopAsyncIteration):+ await generator.__anext__()diff --git a/frontend/__tests__/components/modals/settings/model-selector.test.tsx b/frontend/__tests__/components/modals/settings/model-selector.test.tsxindex 215c0c115c..65484aa7c4 100644--- a/frontend/__tests__/components/modals/settings/model-selector.test.tsx+++ b/frontend/__tests__/components/modals/settings/model-selector.test.tsx@@ -12,6 +12,9 @@ const mockProviders: LLMProvider[] = [{ name: "openai", verified: true },{ name: "azure", verified: false },{ name: "vertex_ai", verified: false },+ // Provider whose model list comes back empty (no entry in+ // mockModelsByProvider) — used by the unavailable-model warning tests.+ { name: "groq", verified: false },];const mockModelsByProvider: Record<string, LLMModel[]> = {@@ -22,6 +25,10 @@ const mockModelsByProvider: Record<string, LLMModel[]> = {azure: [{ provider: "azure", name: "ada", verified: false },{ provider: "azure", name: "gpt-35-turbo", verified: false },+ // Served-but-not-promoted alias route (e.g. a legacy name a managed+ // proxy keeps serving after a rename): never a dropdown option, but a+ // saved setting referencing it still counts as available.+ { provider: "azure", name: "legacy-alias", verified: false, hidden: true },],vertex_ai: [{ provider: "vertex_ai", name: "chat-bison", verified: false },@@ -108,6 +115,8 @@ describe("ModelSelector", () => {expect(screen.getByText("ada")).toBeInTheDocument();expect(screen.getByText("gpt-35-turbo")).toBeInTheDocument();+ // Hidden alias routes are served by the backend but never promoted.+ expect(screen.queryByText("legacy-alias")).not.toBeInTheDocument();});it("should call onChange when the provider and model change", async () => {@@ -142,4 +151,74 @@ describe("ModelSelector", () => {expect(container.firstChild).toHaveClass("w-full");});++ describe("unavailable model warning", () => {+ it("shows a warning when the saved model is missing from a non-empty model list", async () => {+ renderWithQuery(<ModelSelector currentModel="azure/removed-model" />);++ await waitFor(() => {+ expect(+ screen.getByTestId("model-unavailable-warning"),+ ).toBeInTheDocument();+ });+ });++ it("does not show a warning when the saved model matches a hidden alias", async () => {+ // "legacy-alias" is served by the backend (hidden=true) but is not a+ // dropdown option — the saved setting still routes, so no warning.+ renderWithQuery(<ModelSelector currentModel="azure/legacy-alias" />);++ await waitFor(() => {+ expect(screen.getByLabelText("LLM Provider")).toHaveValue("Azure");+ });+ expect(+ screen.queryByTestId("model-unavailable-warning"),+ ).not.toBeInTheDocument();+ });++ it("does not show a warning when the saved model is in the model list", async () => {+ renderWithQuery(<ModelSelector currentModel="azure/ada" />);++ await waitFor(() => {+ expect(screen.getByLabelText("LLM Model")).toHaveValue("ada");+ });+ expect(+ screen.queryByTestId("model-unavailable-warning"),+ ).not.toBeInTheDocument();+ });++ it("does not show a warning when the provider's model list is empty", async () => {+ // "groq" has no entry in mockModelsByProvider, so the hook returns []+ // — an empty list must not cast doubt on the saved model.+ renderWithQuery(<ModelSelector currentModel="groq/llama3-70b" />);++ await waitFor(() => {+ expect(screen.getByLabelText("LLM Provider")).toHaveValue("Groq");+ });+ expect(+ screen.queryByTestId("model-unavailable-warning"),+ ).not.toBeInTheDocument();+ });++ it("clears the warning when the user picks an available model", async () => {+ const user = userEvent.setup();+ renderWithQuery(<ModelSelector currentModel="azure/removed-model" />);++ await waitFor(() => {+ expect(+ screen.getByTestId("model-unavailable-warning"),+ ).toBeInTheDocument();+ });++ const modelSelector = screen.getByLabelText("LLM Model");+ await user.click(modelSelector);+ await user.click(screen.getByText("ada"));++ await waitFor(() => {+ expect(+ screen.queryByTestId("model-unavailable-warning"),+ ).not.toBeInTheDocument();+ });+ });+ });});diff --git a/frontend/__tests__/routes/llm-settings.test.tsx b/frontend/__tests__/routes/llm-settings.test.tsxindex 39f9f967c2..9bf34f3d37 100644--- a/frontend/__tests__/routes/llm-settings.test.tsx+++ b/frontend/__tests__/routes/llm-settings.test.tsx@@ -3,6 +3,7 @@ import { render, screen, waitFor, within } from "@testing-library/react";import userEvent from "@testing-library/user-event";import { beforeEach, describe, expect, it, vi } from "vitest";import { MemoryRouter } from "react-router";+import { http, HttpResponse } from "msw";import OrgProfilesService from "#/api/organization-service/org-profiles-service.api";import { organizationService } from "#/api/organization-service/organization-service.api";@@ -14,6 +15,7 @@ import {MOCK_DEFAULT_USER_SETTINGS,resetTestHandlersMockSettings,} from "#/mocks/handlers";+import { server } from "#/mocks/node";import LlmSettingsScreen, { clientLoader } from "#/routes/llm-settings";import { useSelectedOrganizationStore } from "#/stores/selected-organization-store";import { Organization, OrganizationMember } from "#/types/org";@@ -272,6 +274,7 @@ async function renderLlmSettingsScreen({scope = "personal",view = "form",profile,+ featureFlags,}: {appMode?: "oss" | "saas";organizationId?: string;@@ -289,6 +292,9 @@ async function renderLlmSettingsScreen({// Override fields on the seeded edit profile when a test needs it to// *differ* from the active settings.profile?: Partial<LlmProfileSummary>;+ // Web-client feature flags merged into the mocked /config payload, e.g.+ // ``{ allow_user_llm_configuration: false }`` for managed OHE installs.+ featureFlags?: Record<string, unknown>;} = {}) {const queryClient = new QueryClient({defaultOptions: {@@ -298,7 +304,10 @@ async function renderLlmSettingsScreen({useSelectedOrganizationStore.setState({ organizationId });mockUseConfig.mockReturnValue({- data: { app_mode: appMode },+ data: {+ app_mode: appMode,+ ...(featureFlags ? { feature_flags: featureFlags } : {}),+ },isLoading: false,});@@ -826,16 +835,33 @@ describe("LlmSettingsScreen", () => {).not.toBeInTheDocument();});- it("hides the API key input for OpenHands provider in SaaS mode", async () => {+ it("hides the API key input for OpenHands provider on enterprise cloud", async () => {vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());- await renderLlmSettingsScreen({ appMode: "saas" });+ await renderLlmSettingsScreen({+ appMode: "saas",+ featureFlags: { deployment_mode: "cloud" },+ });await screen.findByTestId("llm-settings-screen");expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();expect(screen.getByTestId("openhands-api-key-help")).toBeInTheDocument();});+ it("hides the OpenHands API key help on self-hosted OHE", async () => {+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());++ await renderLlmSettingsScreen({+ appMode: "saas",+ featureFlags: { deployment_mode: "self_hosted" },+ });++ await screen.findByTestId("llm-settings-screen");+ expect(+ screen.queryByTestId("openhands-api-key-help"),+ ).not.toBeInTheDocument();+ });+it("shows the API key input for non-OpenHands providers in SaaS mode", async () => {vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings({@@ -2755,9 +2781,7 @@ describe("LlmSettingsScreen", () => {expect(screen.getByTestId("llm-model-input")).toHaveValue("");// No provider selected yet, so the API key input isn't rendered (it// appears once a key-taking provider is chosen).- expect(- screen.queryByTestId("llm-api-key-input"),- ).not.toBeInTheDocument();+ expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();await userEvent.click(screen.getByTestId("sdk-section-advanced-toggle"));@@ -2790,9 +2814,7 @@ describe("LlmSettingsScreen", () => {// rendering it only to remove it again when a managed provider is// picked was jarring.await screen.findByTestId("llm-settings-form-basic");- expect(- screen.queryByTestId("llm-api-key-input"),- ).not.toBeInTheDocument();+ expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();// Picking a key-taking provider reveals the input.await selectProvider("OpenAI");@@ -2801,9 +2823,7 @@ describe("LlmSettingsScreen", () => {// The managed OpenHands provider keeps it hidden in SaaS mode (keys// are auto-provisioned).await selectProvider("OpenHands");- expect(- screen.queryByTestId("llm-api-key-input"),- ).not.toBeInTheDocument();+ expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();});it("keeps Save disabled in the create form until a model is chosen", async () => {@@ -2969,6 +2989,119 @@ describe("LlmSettingsScreen", () => {});});+ it("hydrates the edit form with the canonical model when the profile stores a hidden alias", async () => {+ // Legacy profile model "openhands/custom-llm" is a hidden alias that+ // the catalog maps to the visible claude-sonnet model.+ server.use(+ http.get("/api/v1/config/models/search", () =>+ HttpResponse.json({+ items: [+ {+ provider: "openhands",+ name: "claude-sonnet-4-5-20250929",+ verified: true,+ },+ {+ provider: "openhands",+ name: "custom-llm",+ verified: false,+ hidden: true,+ canonical: "claude-sonnet-4-5-20250929",+ },+ ],+ next_page_id: null,+ }),+ ),+ );+ const saveSettingsSpy = vi+ .spyOn(SettingsService, "saveSettings")+ .mockResolvedValue(true);++ await renderLlmSettingsScreen({+ appMode: "oss",+ profile: {+ name: "legacy-profile",+ model: "openhands/custom-llm",+ base_url: null,+ },+ });++ await screen.findByTestId("llm-settings-form-basic");+ await waitFor(() => {+ expect(screen.getByTestId("llm-provider-input")).toHaveValue(+ "OpenHands",+ );+ expect(screen.getByTestId("llm-model-input")).toHaveValue(+ "claude-sonnet-4-5-20250929",+ );+ });+ expect(+ screen.queryByTestId("model-unavailable-warning"),+ ).not.toBeInTheDocument();++ // A pristine save persists the canonical id — deliberately migrating+ // the profile off the legacy alias (both names route on the proxy).+ await userEvent.click(screen.getByTestId("save-button"));+ await waitFor(() => {+ expect(saveSettingsSpy).toHaveBeenCalledWith(+ expect.objectContaining({+ agent_settings_diff: expect.objectContaining({+ llm: expect.objectContaining({+ model: "openhands/claude-sonnet-4-5-20250929",+ }),+ }),+ }),+ );+ });+ });++ it("keeps the stored alias when a hidden model has no canonical mapping", async () => {+ server.use(+ http.get("/api/v1/config/models/search", () =>+ HttpResponse.json({+ items: [+ {+ provider: "openhands",+ name: "claude-sonnet-4-5-20250929",+ verified: true,+ },+ // Hidden but with no canonical mapping — nothing to translate.+ {+ provider: "openhands",+ name: "orphan-alias",+ verified: false,+ hidden: true,+ },+ ],+ next_page_id: null,+ }),+ ),+ );++ await renderLlmSettingsScreen({+ appMode: "oss",+ profile: {+ name: "orphan-profile",+ model: "openhands/orphan-alias",+ base_url: null,+ },+ });++ await screen.findByTestId("llm-settings-form-basic");+ await waitFor(() => {+ expect(screen.getByTestId("llm-provider-input")).toHaveValue(+ "OpenHands",+ );+ });+ // Unchanged today-behavior: hidden aliases are never dropdown options,+ // so the selection renders empty — and no unavailable badge, since the+ // proxy still serves the alias.+ expect(screen.getByTestId("llm-model-input")).toHaveValue("");+ expect(+ screen.queryByTestId("model-unavailable-warning"),+ ).not.toBeInTheDocument();+ });+it("opens edit on advanced with the profile's custom base URL while the active settings are plain", async () => {vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings({@@ -3098,4 +3231,137 @@ describe("LlmSettingsScreen", () => {);});});++ describe("managed LLM configuration gating (allow_user_llm_configuration=false)", () => {+ const MANAGED_FLAGS = { allow_user_llm_configuration: false };++ it("hides BYOK inputs and lands on the model dropdown even when a custom base URL is saved", async () => {+ // A saved custom base URL normally opens the advanced form with the+ // custom-model + base-URL inputs. With BYOK disallowed the user lands+ // on the managed dropdown instead — the saved settings themselves are+ // untouched and keep working at runtime.+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(+ buildSettings({+ llm_model: "openai/gpt-4o",+ llm_base_url: "https://custom.example/v1",+ agent_settings: {+ llm: {+ model: "openai/gpt-4o",+ base_url: "https://custom.example/v1",+ },+ },+ }),+ );++ await renderLlmSettingsScreen({+ appMode: "oss",+ featureFlags: MANAGED_FLAGS,+ });++ await screen.findByTestId("llm-settings-form-basic");+ expect(screen.getByTestId("llm-provider-input")).toBeInTheDocument();+ expect(screen.getByTestId("llm-model-input")).toBeInTheDocument();+ expect(screen.getByTestId("save-button")).toBeInTheDocument();++ expect(+ screen.queryByTestId("llm-settings-form-advanced"),+ ).not.toBeInTheDocument();+ expect(+ screen.queryByTestId("llm-custom-model-input"),+ ).not.toBeInTheDocument();+ expect(screen.queryByTestId("base-url-input")).not.toBeInTheDocument();+ expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();+ // No BYOK and no schema-driven advanced fields → no Advanced toggle.+ expect(+ screen.queryByTestId("sdk-section-advanced-toggle"),+ ).not.toBeInTheDocument();+ });++ it("suppresses the Advanced toggle when BYOK is off, even with schema-driven advanced fields", async () => {+ // Without BYOK the LLM Advanced view (custom model + base URL) has+ // nothing to show, so Basic and Advanced would be identical. The+ // Advanced toggle is hidden entirely — even when the schema carries+ // advanced fields that would otherwise surface it.+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(+ buildSettingsWithAdvancedToggle({+ llm_model: "openai/gpt-4o",+ agent_settings: { llm: { model: "openai/gpt-4o" } },+ }),+ );++ await renderLlmSettingsScreen({+ appMode: "oss",+ featureFlags: MANAGED_FLAGS,+ });++ await screen.findByTestId("llm-settings-form-basic");++ expect(+ screen.queryByTestId("sdk-section-advanced-toggle"),+ ).not.toBeInTheDocument();+ expect(screen.getByTestId("llm-settings-form-basic")).toBeInTheDocument();+ expect(+ screen.queryByTestId("llm-settings-form-advanced"),+ ).not.toBeInTheDocument();+ expect(+ screen.queryByTestId("llm-custom-model-input"),+ ).not.toBeInTheDocument();+ expect(screen.queryByTestId("base-url-input")).not.toBeInTheDocument();+ expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();+ });++ it("hides BYOK inputs on the org-defaults form in SaaS mode", async () => {+ vi.spyOn(+ organizationService,+ "getOrganizationSettings",+ ).mockResolvedValue(+ buildSettings({+ agent_settings: { llm: { model: "openai/gpt-4o" } },+ }),+ );++ await renderLlmSettingsScreen({+ appMode: "saas",+ scope: "org",+ featureFlags: MANAGED_FLAGS,+ });++ await screen.findByTestId("llm-settings-form-basic");+ expect(screen.getByTestId("llm-provider-input")).toBeInTheDocument();+ expect(screen.getByTestId("llm-model-input")).toBeInTheDocument();+ expect(+ screen.queryByTestId("sdk-section-advanced-toggle"),+ ).not.toBeInTheDocument();+ expect(+ screen.queryByTestId("llm-custom-model-input"),+ ).not.toBeInTheDocument();+ expect(screen.queryByTestId("base-url-input")).not.toBeInTheDocument();+ expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();+ });++ it("keeps BYOK inputs when the flag is explicitly true", async () => {+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(+ buildSettings(),+ );++ await renderLlmSettingsScreen({+ appMode: "oss",+ featureFlags: { allow_user_llm_configuration: true },+ });++ await screen.findByTestId("llm-settings-form-basic");+ expect(screen.getByTestId("llm-api-key-input")).toBeInTheDocument();+ expect(+ screen.getByTestId("sdk-section-advanced-toggle"),+ ).toBeInTheDocument();++ await userEvent.click(screen.getByTestId("sdk-section-advanced-toggle"));++ expect(+ screen.getByTestId("llm-settings-form-advanced"),+ ).toBeInTheDocument();+ expect(screen.getByTestId("llm-custom-model-input")).toBeInTheDocument();+ expect(screen.getByTestId("base-url-input")).toBeInTheDocument();+ });+ });});diff --git a/frontend/src/api/config-service/config-service.types.ts b/frontend/src/api/config-service/config-service.types.tsindex dc8e7235bb..adfdd627b5 100644--- a/frontend/src/api/config-service/config-service.types.ts+++ b/frontend/src/api/config-service/config-service.types.ts@@ -4,6 +4,14 @@ export interface LLMModel {provider: string | null;name: string;verified: boolean;+ /** Served but not promoted (e.g. a legacy alias route on a managed+ * LiteLLM proxy): never offered as a dropdown option, yet a saved+ * setting that references it still counts as available. Optional so+ * older backends (no field) behave as before. */+ hidden?: boolean;+ /** Bare name of the visible model a hidden alias routes to (same+ * provider); mirrors the backend LLMModelInfo.canonical contract. */+ canonical?: string;}export interface LLMModelPage {diff --git a/frontend/src/api/option-service/option.types.ts b/frontend/src/api/option-service/option.types.tsindex be92dcdee7..968e9fac44 100644--- a/frontend/src/api/option-service/option.types.ts+++ b/frontend/src/api/option-service/option.types.ts@@ -17,6 +17,11 @@ export interface ModelsResponse {verified_providers: string[];/** Recommended default model id (e.g. ``openhands/claude-opus-4-5-20251101``). */default_model: string;+ /** ``provider/model`` strings the backend serves but does not promote+ * (e.g. legacy alias routes on a managed LiteLLM proxy): not dropdown+ * options, but saved settings referencing them still count as available.+ * Optional so older backends (no field) behave as before. */+ hidden_models?: string[];}export interface WebClientFeatureFlags {@@ -31,6 +36,11 @@ export interface WebClientFeatureFlags {/** Hide personal workspaces from the org list/selector for users who* belong to at least one team org (OHE "org-only" installs). */hide_personal_workspaces?: boolean;+ /** When false, hide the BYOK editing UI (custom model, base URL, API key)+ * in LLM settings — users only pick from the managed model dropdown.+ * Defaults to true (absent ⇒ allowed) so SaaS/existing installs are+ * unaffected. Saved BYOK settings keep working at runtime either way. */+ allow_user_llm_configuration?: boolean;enable_acp?: boolean;deployment_mode?: DeploymentMode;enable_onboarding: boolean;diff --git a/frontend/src/components/features/settings/sdk-settings/sdk-section-page.tsx b/frontend/src/components/features/settings/sdk-settings/sdk-section-page.tsxindex 44dc9f958d..00c91ca334 100644--- a/frontend/src/components/features/settings/sdk-settings/sdk-section-page.tsx+++ b/frontend/src/components/features/settings/sdk-settings/sdk-section-page.tsx@@ -142,6 +142,7 @@ export function SdkSectionPage({initialValueOverrides,isSaveDisabled,forceShowAdvancedView = false,+ allowAdvancedView = true,allowAllView = true,trailingActions,testId = "sdk-section-settings-screen",@@ -192,6 +193,10 @@ export function SdkSectionPage({// navigation button into the same row.trailingActions?: React.ReactNode;forceShowAdvancedView?: boolean;+ // Master gate for the Advanced tier. When false the Advanced toggle never+ // shows, even if the schema has advanced fields — e.g. the LLM page when+ // BYOK is off, where Basic and Advanced would otherwise be identical.+ allowAdvancedView?: boolean;allowAllView?: boolean;testId?: string;}) {@@ -276,8 +281,9 @@ export function SdkSectionPage({);const showAdvanced =- forceShowAdvancedView ||- resolvedSources.some((src) => hasAdvancedSettings(src.filteredSchema));+ allowAdvancedView &&+ (forceShowAdvancedView ||+ resolvedSources.some((src) => hasAdvancedSettings(src.filteredSchema)));const showAll =allowAllView &&resolvedSources.some((src) => hasMinorSettings(src.filteredSchema));diff --git a/frontend/src/components/shared/modals/settings/model-selector.tsx b/frontend/src/components/shared/modals/settings/model-selector.tsxindex 4f00ef60d7..3aa4e33140 100644--- a/frontend/src/components/shared/modals/settings/model-selector.tsx+++ b/frontend/src/components/shared/modals/settings/model-selector.tsx@@ -59,13 +59,35 @@ export function ModelSelector({[providers],);- const verifiedModels = React.useMemo(- () => providerModels.filter((m) => m.verified),+ // Hidden models (e.g. legacy alias routes a managed proxy still serves+ // after a rename) are never offered as dropdown options, but they do+ // count as available for the saved-model check below.+ const dropdownModels = React.useMemo(+ () => providerModels.filter((m) => !m.hidden),[providerModels],);+ const verifiedModels = React.useMemo(+ () => dropdownModels.filter((m) => m.verified),+ [dropdownModels],+ );const unverifiedModels = React.useMemo(- () => providerModels.filter((m) => !m.verified),- [providerModels],+ () => dropdownModels.filter((m) => !m.verified),+ [dropdownModels],+ );++ // Truthful-but-gentle signal that the displayed model no longer exists in+ // the provider's model list (e.g. an admin removed it from a managed+ // proxy). Only shown when the list actually loaded non-empty — a fetch+ // error or an unknown provider must not cast doubt on a working config.+ // Hidden models count as available: the proxy still serves them.+ const isSelectedModelUnavailable = React.useMemo(+ () =>+ !!selectedModel &&+ !isLoadingModels &&+ !modelsError &&+ providerModels.length > 0 &&+ !providerModels.some((m) => m.name === selectedModel),+ [selectedModel, isLoadingModels, modelsError, providerModels],);React.useEffect(() => {@@ -79,6 +101,17 @@ export function ModelSelector({}}, [currentModel]);+ // With a single provider (e.g. managed OHE's bundled proxy) there is nothing+ // to pick — auto-select it so the picker below can be hidden.+ React.useEffect(() => {+ if (providers.length === 1 && !selectedProvider && !currentModel) {+ const provider = providers[0].name;+ setSelectedProvider(provider);+ setLitellmId(`${provider}/`);+ onChange?.(provider, null);+ }+ }, [providers, selectedProvider, currentModel]);+const handleChangeProvider = (provider: string) => {setSelectedProvider(provider);setSelectedModel(null);@@ -111,56 +144,70 @@ export function ModelSelector({wrapperClassName,)}>- <fieldset className="flex flex-col gap-2.5 w-full">- <label className={cn("text-sm", labelClassName)}>- {t(I18nKey.LLM$PROVIDER)}- </label>- <Autocomplete- data-testid="llm-provider-input"- isRequired- isVirtualized={false}- name="llm-provider-input"- isDisabled={isDisabled}- aria-label={t(I18nKey.LLM$PROVIDER)}- placeholder={t(I18nKey.LLM$SELECT_PROVIDER_PLACEHOLDER)}- isClearable={false}- onSelectionChange={(e) => {- if (e?.toString()) handleChangeProvider(e.toString());- }}- onInputChange={(value) => !value && clear()}- defaultSelectedKey={selectedProvider ?? undefined}- selectedKey={selectedProvider}- classNames={{- popoverContent: "bg-tertiary rounded-xl border border-[#717888]",- }}- inputProps={{- classNames: {- inputWrapper:- "bg-tertiary border border-[#717888] h-10 w-full rounded-sm p-2 placeholder:italic",- },- }}- >- <AutocompleteSection title={t(I18nKey.MODEL_SELECTOR$VERIFIED)}>- {verifiedProviders.map((provider) => (- <AutocompleteItem- data-testid={`provider-item-${provider.name}`}- key={provider.name}- >- {mapProvider(provider.name)}- </AutocompleteItem>- ))}- </AutocompleteSection>- {unverifiedProviders.length > 0 ? (- <AutocompleteSection title={t(I18nKey.MODEL_SELECTOR$OTHERS)}>- {unverifiedProviders.map((provider) => (- <AutocompleteItem key={provider.name}>+ {providers.length !== 1 ? (+ <fieldset className="flex flex-col gap-2.5 w-full">+ <label className={cn("text-sm", labelClassName)}>+ {t(I18nKey.LLM$PROVIDER)}+ </label>+ <Autocomplete+ data-testid="llm-provider-input"+ isRequired+ isVirtualized={false}+ name="llm-provider-input"+ isDisabled={isDisabled}+ aria-label={t(I18nKey.LLM$PROVIDER)}+ placeholder={t(I18nKey.LLM$SELECT_PROVIDER_PLACEHOLDER)}+ isClearable={false}+ onSelectionChange={(e) => {+ if (e?.toString()) handleChangeProvider(e.toString());+ }}+ onInputChange={(value) => !value && clear()}+ defaultSelectedKey={selectedProvider ?? undefined}+ selectedKey={selectedProvider}+ classNames={{+ popoverContent: "bg-tertiary rounded-xl border border-[#717888]",+ }}+ inputProps={{+ classNames: {+ inputWrapper:+ "bg-tertiary border border-[#717888] h-10 w-full rounded-sm p-2 placeholder:italic",+ },+ }}+ >+ <AutocompleteSection+ title={+ unverifiedProviders.length > 0+ ? t(I18nKey.MODEL_SELECTOR$VERIFIED)+ : undefined+ }+ >+ {verifiedProviders.map((provider) => (+ <AutocompleteItem+ data-testid={`provider-item-${provider.name}`}+ key={provider.name}+ >{mapProvider(provider.name)}</AutocompleteItem>))}</AutocompleteSection>- ) : null}- </Autocomplete>- </fieldset>+ {unverifiedProviders.length > 0 ? (+ <AutocompleteSection+ title={+ verifiedProviders.length > 0+ ? t(I18nKey.MODEL_SELECTOR$OTHERS)+ : undefined+ }+ >+ {unverifiedProviders.map((provider) => (+ <AutocompleteItem key={provider.name}>+ {mapProvider(provider.name)}+ </AutocompleteItem>+ ))}+ </AutocompleteSection>+ ) : null}+ </Autocomplete>+ </fieldset>+ ) : null}{selectedProvider === "openhands" && isEnterpriseCloud && (<HelpLink@@ -202,13 +249,25 @@ export function ModelSelector({},}}>- <AutocompleteSection title={t(I18nKey.MODEL_SELECTOR$VERIFIED)}>+ <AutocompleteSection+ title={+ unverifiedModels.length > 0+ ? t(I18nKey.MODEL_SELECTOR$VERIFIED)+ : undefined+ }+ >{verifiedModels.map((model) => (<AutocompleteItem key={model.name}>{model.name}</AutocompleteItem>))}</AutocompleteSection>{unverifiedModels.length > 0 ? (- <AutocompleteSection title={t(I18nKey.MODEL_SELECTOR$OTHERS)}>+ <AutocompleteSection+ title={+ verifiedModels.length > 0+ ? t(I18nKey.MODEL_SELECTOR$OTHERS)+ : undefined+ }+ >{unverifiedModels.map((model) => (<AutocompleteItemdata-testid={`model-item-${model.name}`}@@ -225,6 +284,14 @@ export function ModelSelector({{t(I18nKey.CONFIGURATION$ERROR_FETCH_MODELS)}</p>)}+ {isSelectedModelUnavailable && (+ <p+ data-testid="model-unavailable-warning"+ className="text-yellow-400 text-xs"+ >+ {t(I18nKey.SETTINGS$MODEL_NO_LONGER_AVAILABLE)}+ </p>+ )}</fieldset></div>);diff --git a/frontend/src/hooks/query/use-provider-models.ts b/frontend/src/hooks/query/use-provider-models.tsindex d9dab7e58e..95e66387ca 100644--- a/frontend/src/hooks/query/use-provider-models.ts+++ b/frontend/src/hooks/query/use-provider-models.ts@@ -1,4 +1,4 @@-import { useQuery } from "@tanstack/react-query";+import { queryOptions, useQuery } from "@tanstack/react-query";import ConfigService from "#/api/config-service/config-service.api";import type { LLMModel } from "#/api/config-service/config-service.types";@@ -26,11 +26,18 @@ async function fetchPage(return page.items;}-export const useProviderModels = (provider: string | null) =>- useQuery({+// Shared with imperative queryClient.fetchQuery callers so they reuse the+// same cache entry (and staleness rules) as the hook.+export const providerModelsQueryOptions = (provider: string | null) =>+ queryOptions({queryKey: ["config", "models", provider],queryFn: () => fetchPage(provider!),- enabled: !!provider,staleTime: 1000 * 60 * 5,gcTime: 1000 * 60 * 15,});++export const useProviderModels = (provider: string | null) =>+ useQuery({+ ...providerModelsQueryOptions(provider),+ enabled: !!provider,+ });diff --git a/frontend/src/i18n/declaration.ts b/frontend/src/i18n/declaration.tsindex 73dfbb8353..8aa14eacff 100644--- a/frontend/src/i18n/declaration.ts+++ b/frontend/src/i18n/declaration.ts@@ -384,6 +384,7 @@ export enum I18nKey {SETTINGS$SEARCH_API_KEY = "SETTINGS$SEARCH_API_KEY",SETTINGS$SEARCH_API_KEY_OPTIONAL = "SETTINGS$SEARCH_API_KEY_OPTIONAL",SETTINGS$SEARCH_API_KEY_INSTRUCTIONS = "SETTINGS$SEARCH_API_KEY_INSTRUCTIONS",+ SETTINGS$MODEL_NO_LONGER_AVAILABLE = "SETTINGS$MODEL_NO_LONGER_AVAILABLE",SETTINGS$CUSTOM_MODEL = "SETTINGS$CUSTOM_MODEL",GITHUB$CODE_NOT_IN_GITHUB = "GITHUB$CODE_NOT_IN_GITHUB",GITHUB$START_FROM_SCRATCH = "GITHUB$START_FROM_SCRATCH",diff --git a/frontend/src/i18n/translation.json b/frontend/src/i18n/translation.jsonindex f96871600b..ae1c9912af 100644--- a/frontend/src/i18n/translation.json+++ b/frontend/src/i18n/translation.json@@ -4947,21 +4947,21 @@"ca": "Aquesta configuració està gestionada per l'administrador de la teva organització"},"SETTINGS$ORG_DEFAULTS_INFO": {- "en": "These organization defaults are applied first. Members can still add their own credentials or personal overrides where allowed.",- "ja": "これらの組織のデフォルト設定が最初に適用されます。メンバーは許可されている範囲で、自分の認証情報や個人設定を追加できます。",- "zh-CN": "这些组织默认设置会首先应用。成员仍然可以在允许的范围内添加自己的凭据或个人覆盖设置。",- "zh-TW": "這些組織預設設定會首先套用。成員仍然可以在允許的範圍內新增自己的憑證或個人覆蓋設定。",- "ko-KR": "이 조직 기본 설정이 먼저 적용됩니다. 구성원은 허용되는 범위 내에서 자체 자격 증명이나 개인 재정의를 추가할 수 있습니다.",- "no": "Disse organisasjonsstandardene brukes først. Medlemmer kan fortsatt legge til egne legitimasjoner eller personlige overstyringer der det er tillatt.",- "it": "Queste impostazioni predefinite dell'organizzazione vengono applicate per prime. I membri possono comunque aggiungere le proprie credenziali o sostituzioni personali dove consentito.",- "pt": "Esses padrões da organização são aplicados primeiro. Os membros ainda podem adicionar suas próprias credenciais ou substituições pessoais onde permitido.",- "es": "Estos valores predeterminados de la organización se aplican primero. Los miembros aún pueden agregar sus propias credenciales o anulaciones personales donde esté permitido.",- "ar": "يتم تطبيق إعدادات المؤسسة الافتراضية أولاً. لا يزال بإمكان الأعضاء إضافة بيانات اعتمادهم أو تجاوزاتهم الشخصية حيثما كان ذلك مسموحًا.",- "fr": "Ces paramètres par défaut de l'organisation sont appliqués en premier. Les membres peuvent toujours ajouter leurs propres identifiants ou remplacements personnels lorsque cela est autorisé.",- "tr": "Bu organizasyon varsayılanları önce uygulanır. Üyeler izin verilen yerlerde kendi kimlik bilgilerini veya kişisel geçersiz kılmalarını ekleyebilir.",- "de": "Diese Organisationsstandards werden zuerst angewendet. Mitglieder können weiterhin eigene Anmeldedaten oder persönliche Überschreibungen hinzufügen, wo dies erlaubt ist.",- "uk": "Ці стандартні налаштування організації застосовуються першими. Учасники все ще можуть додавати власні облікові дані або особисті перевизначення там, де це дозволено.",- "ca": "Aquests valors predeterminats de l'organització s'apliquen primer. Els membres encara poden afegir les seves pròpies credencials o substitucions personals on estigui permès."+ "en": "These organization defaults are applied first. Members can apply personal overrides where allowed.",+ "ja": "これらの組織のデフォルト設定が最初に適用されます。メンバーは許可されている範囲で個人設定を適用できます。",+ "zh-CN": "这些组织默认设置会首先应用。成员可以在允许的范围内应用个人覆盖设置。",+ "zh-TW": "這些組織預設設定會首先套用。成員可以在允許的範圍內套用個人覆蓋設定。",+ "ko-KR": "이 조직 기본 설정이 먼저 적용됩니다. 구성원은 허용되는 범위 내에서 개인 재정의를 적용할 수 있습니다.",+ "no": "Disse organisasjonsstandardene brukes først. Medlemmer kan bruke personlige overstyringer der det er tillatt.",+ "it": "Queste impostazioni predefinite dell'organizzazione vengono applicate per prime. I membri possono applicare sostituzioni personali dove consentito.",+ "pt": "Esses padrões da organização são aplicados primeiro. Os membros podem aplicar substituições pessoais onde permitido.",+ "es": "Estos valores predeterminados de la organización se aplican primero. Los miembros pueden aplicar anulaciones personales donde esté permitido.",+ "ar": "يتم تطبيق إعدادات المؤسسة الافتراضية أولاً. يمكن للأعضاء تطبيق التجاوزات الشخصية حيثما كان ذلك مسموحًا.",+ "fr": "Ces paramètres par défaut de l'organisation sont appliqués en premier. Les membres peuvent appliquer des remplacements personnels lorsque cela est autorisé.",+ "tr": "Bu organizasyon varsayılanları önce uygulanır. Üyeler izin verilen yerlerde kişisel geçersiz kılmaları uygulayabilir.",+ "de": "Diese Organisationsstandards werden zuerst angewendet. Mitglieder können persönliche Überschreibungen anwenden, wo dies erlaubt ist.",+ "uk": "Ці стандартні налаштування організації застосовуються першими. Учасники можуть застосовувати особисті перевизначення там, де це дозволено.",+ "ca": "Aquests valors predeterminats de l'organització s'apliquen primer. Els membres poden aplicar substitucions personals on estigui permès."},"SETTINGS$PERSONAL_AGENT_INFO": {"en": "These settings only affect your own work. Organization defaults still apply unless you override them here.",@@ -6527,6 +6527,23 @@"uk": "Отримайте свій ключ API від Tavily","ca": "Obteniu la vostra clau d'API a Tavily"},+ "SETTINGS$MODEL_NO_LONGER_AVAILABLE": {+ "en": "No longer available",+ "ja": "現在は利用できません",+ "zh-CN": "已不再可用",+ "zh-TW": "已不再可用",+ "ko-KR": "더 이상 사용할 수 없음",+ "de": "Nicht mehr verfügbar",+ "no": "Ikke lenger tilgjengelig",+ "it": "Non più disponibile",+ "pt": "Não está mais disponível",+ "es": "Ya no está disponible",+ "ar": "لم يعد متاحًا",+ "fr": "N'est plus disponible",+ "tr": "Artık mevcut değil",+ "uk": "Більше недоступна",+ "ca": "Ja no està disponible"+ },"SETTINGS$CUSTOM_MODEL": {"en": "Custom Model","ja": "カスタムモデル",diff --git a/frontend/src/routes/llm-settings.tsx b/frontend/src/routes/llm-settings.tsxindex ddb1c7c108..c380d7bc2d 100644--- a/frontend/src/routes/llm-settings.tsx+++ b/frontend/src/routes/llm-settings.tsx@@ -1,4 +1,5 @@import React from "react";+import { useQueryClient } from "@tanstack/react-query";import { useSearchParams } from "react-router";import { useTranslation } from "react-i18next";import { FaChevronLeft } from "react-icons/fa6";@@ -45,7 +46,9 @@ import { LlmProfilesManager } from "#/components/features/settings/llm-profiles-import { OrgLlmProfilesManager } from "#/components/features/settings/org-llm-profiles-manager";import { ProfileNameInput } from "#/components/features/settings/profile-name-input";import { Typography } from "#/ui/typography";+import { providerModelsQueryOptions } from "#/hooks/query/use-provider-models";import { useOrgTypeAndAccess } from "#/hooks/use-org-type-and-access";+import { useAppMode } from "#/hooks/use-app-mode";import { useMe } from "#/hooks/query/use-me";import { usePermission } from "#/hooks/organizations/use-permissions";@@ -111,6 +114,7 @@ export function LlmSettingsScreen({}) {const { t } = useTranslation();const [searchParams, setSearchParams] = useSearchParams();+ const queryClient = useQueryClient();const { data: settings } = useSettings(scope);const { data: schema } = useAgentSettingsSchema(@@ -185,6 +189,14 @@ export function LlmSettingsScreen({);const isSaasMode = config?.app_mode === "saas";+ const { isEnterpriseCloud } = useAppMode();++ // OHE installs can disable BYOK via OH_ALLOW_USER_LLM_CONFIGURATION; absent+ // (SaaS / existing installs) means allowed. This hides the *editing* UI for+ // custom model / base URL / API key only — saved BYOK settings keep working+ // at runtime, and the managed model dropdown stays fully functional.+ const allowUserLlmConfiguration =+ config?.feature_flags?.allow_user_llm_configuration !== false;React.useEffect(() => {// An open profile form owns the provider selection (blank for create,@@ -222,6 +234,12 @@ export function LlmSettingsScreen({currentSettings: Settings,filteredSchema: SettingsSchema,): SettingsView => {+ // Without BYOK there is nothing for the advanced/all tiers to reveal in+ // the custom header, so always land on the managed model dropdown.+ if (!allowUserLlmConfiguration) {+ return "basic";+ }+// A hint set by the Profiles mirror-strip beats every other rule —// the user explicitly asked for this tier when leaving profiles.if (initialViewHint) {@@ -272,7 +290,14 @@ export function LlmSettingsScreen({return hasCustomBaseUrl ? "all" : "basic";},- [editingProfile, initialViewHint, isSaasMode, profileFormMode, scope],+ [+ allowUserLlmConfiguration,+ editingProfile,+ initialViewHint,+ isSaasMode,+ profileFormMode,+ scope,+ ],);const buildHeader = React.useCallback(@@ -292,7 +317,12 @@ export function LlmSettingsScreen({: derivedProvider;const shouldUseOpenHandsKey =isSaasMode && activeProvider === "openhands";- const showOpenHandsApiKeyHelp = modelValue.startsWith("openhands/");+ // The OpenHands key help links to OpenHands Cloud keys/pricing — only+ // meaningful on enterprise cloud, not self-hosted managed installs.+ const showOpenHandsApiKeyHelp =+ isEnterpriseCloud &&+ modelValue.startsWith("openhands/") &&+ allowUserLlmConfiguration;// While editing, the set-but-unfetchable key indicator must reflect// the clicked profile, not whichever profile is currently active.const apiKeySet =@@ -301,6 +331,12 @@ export function LlmSettingsScreen({: settings?.llm_api_key_set;const renderApiKeyInput = (testId: string, helpTestId: string) => {+ // Managed installs: the admin owns provider keys on the bundled+ // proxy; users never enter one.+ if (!allowUserLlmConfiguration) {+ return null;+ }+if (shouldUseOpenHandsKey) {return null;}@@ -361,7 +397,7 @@ export function LlmSettingsScreen({/>) : null}- {view === "basic" ? (+ {view === "basic" || !allowUserLlmConfiguration ? (<divclassName="flex flex-col gap-6"data-testid="llm-settings-form-basic"@@ -434,6 +470,7 @@ export function LlmSettingsScreen({);},[+ allowUserLlmConfiguration,editingProfile,infoMessageKey,isSaasMode,@@ -608,22 +645,52 @@ export function LlmSettingsScreen({scope,]);- const openForm = (+ // Legacy profiles can store a hidden catalog alias (e.g. a pre-rename+ // proxy route). When the alias maps to a visible model, hydrate the edit+ // form with that canonical id so the dropdown shows a real selection.+ const resolveCanonicalModel = async (model: string): Promise<string> => {+ const { provider, model: modelName } = extractModelAndProvider(model);+ if (!provider) return model;+ try {+ const models = await queryClient.fetchQuery(+ providerModelsQueryOptions(provider),+ );+ const match = models.find((m) => m.name === modelName);+ if (match?.hidden && match.canonical) {+ return `${provider}/${match.canonical}`;+ }+ } catch {+ // Catalog unavailable — open with the stored model, exactly as today.+ }+ return model;+ };++ const openForm = async (view: SettingsView | null,profile: LlmProfileSummary | null = null,) => {// The profiles list passes the profile only when editing; Add Profile// opens a blank create form.- const isEdit = profile !== null;+ let editProfile = profile;+ if (editProfile?.model) {+ // Resolved *before* the form opens: SdkSectionPage re-hydrates (and+ // resets dirty state) whenever the initial-value overrides change, so+ // a post-mount translation could clobber in-progress user edits.+ const canonicalModel = await resolveCanonicalModel(editProfile.model);+ if (canonicalModel !== editProfile.model) {+ editProfile = { ...editProfile, model: canonicalModel };+ }+ }+ const isEdit = editProfile !== null;setProfileFormMode(isEdit ? "edit" : "create");- setEditingProfile(profile);- setProfileName(profile?.name ?? "");- setInitialProfileName(profile?.name ?? "");+ setEditingProfile(editProfile);+ setProfileName(editProfile?.name ?? "");+ setInitialProfileName(editProfile?.name ?? "");setInitialViewHint(view);// Blank for create; the edited profile's provider for edit.setSelectedProvider(- profile?.model- ? extractModelAndProvider(profile.model).provider || null+ editProfile?.model+ ? extractModelAndProvider(editProfile.model).provider || null: null,);setShowProfiles(false);@@ -741,7 +808,10 @@ export function LlmSettingsScreen({values["llm.model"].trim().length > 0)}- forceShowAdvancedView+ // Advanced (custom model + base URL) only exists under BYOK; gate the+ // toggle on it so Basic/Advanced aren't identical when BYOK is off.+ forceShowAdvancedView={allowUserLlmConfiguration}+ allowAdvancedView={allowUserLlmConfiguration}allowAllView={!isSaasMode}testId="llm-settings-screen"/>diff --git a/openhands/app_server/config_api/config_models.py b/openhands/app_server/config_api/config_models.pyindex e725e1a953..a435b744a4 100644--- a/openhands/app_server/config_api/config_models.py+++ b/openhands/app_server/config_api/config_models.py@@ -20,6 +20,23 @@ class LLMModel(BaseModel):verified: bool = Field(default=False, description='Whether the model is verified by OpenHands')+ hidden: bool = Field(+ default=False,+ description=(+ 'Whether the model is served but not promoted: it must not be '+ 'offered as a dropdown option, yet an already-saved setting '+ 'referencing it is still valid (e.g. a legacy alias route on a '+ 'managed LiteLLM proxy)'+ ),+ )+ canonical: str | None = Field(+ default=None,+ description=(+ 'For a hidden model only: the name of the visible model (same '+ 'provider) this one aliases, so clients can display a saved '+ 'hidden model under its canonical name'+ ),+ )class LLMModelPage(BaseModel):diff --git a/openhands/app_server/config_api/default_llm_model_service.py b/openhands/app_server/config_api/default_llm_model_service.pyindex ef90317605..093991aab1 100644--- a/openhands/app_server/config_api/default_llm_model_service.py+++ b/openhands/app_server/config_api/default_llm_model_service.py@@ -6,7 +6,7 @@ in-memory so that the router stays thin."""import logging-from typing import Any, AsyncGenerator+from typing import Any, AsyncGenerator, Callableimport httpxfrom fastapi import Request@@ -40,21 +40,48 @@ _VERIFIED_MODEL_SET: set[str] = {}-def _to_llm_models(models_response: ModelsResponse) -> list[LLMModel]:- """Convert raw model strings into ``LLMModel`` objects with verified flags."""+def _to_llm_models(+ models_response: ModelsResponse,+ is_verified: Callable[[str, str, ModelsResponse], bool] | None = None,+) -> list[LLMModel]:+ """Convert raw model strings into ``LLMModel`` objects with verified flags.++ Hidden models (served by the backend but not promoted, e.g. legacy alias+ routes on a managed LiteLLM proxy) are appended after the visible ones+ with ``hidden=True`` so clients can keep them out of dropdown options+ while still treating saved settings that reference them as available.+ A hidden model with a known canonical mapping carries the visible model+ name it aliases in ``canonical``.+ """results: list[LLMModel] = []- for model_name in models_response.models:+ flagged_models = [(m, False) for m in models_response.models] + [+ (m, True) for m in models_response.hidden_models+ ]+ for model_name, hidden in flagged_models:parts = model_name.split('/', 1)if len(parts) == 2:provider, name = partselse:provider = Nonename = parts[0]+ canonical = None+ if hidden:+ canonical_full = models_response.hidden_model_canonicals.get(model_name)+ if canonical_full:+ # Same bare-name convention as ``name`` — the alias and its+ # canonical model always share the provider.+ canonical = canonical_full.split('/', 1)[-1]results.append(LLMModel(provider=provider,name=name,- verified=model_name in _VERIFIED_MODEL_SET,+ verified=(+ is_verified(model_name, name, models_response)+ if is_verified is not None+ else model_name in _VERIFIED_MODEL_SET+ ),+ hidden=hidden,+ canonical=canonical,))return results@@ -153,6 +180,13 @@ class DefaultLLMModelService(LLMModelService):)return self._cached_response+ def _is_model_verified(+ self, model_name: str, name: str, models_response: ModelsResponse+ ) -> bool:+ """Whether a model is shown as "verified". Default is the static SDK+ catalogue; subclasses (e.g. the managed proxy) override this."""+ return model_name in _VERIFIED_MODEL_SET+# ------------------------------------------------------------------# LLMModelService interface# ------------------------------------------------------------------@@ -167,7 +201,7 @@ class DefaultLLMModelService(LLMModelService):limit: int = 50,) -> LLMModelPage:raw = await self._get_models_response()- models = _to_llm_models(raw)+ models = _to_llm_models(raw, self._is_model_verified)if query is not None:query_lower = query.lower()diff --git a/openhands/app_server/utils/llm.py b/openhands/app_server/utils/llm.pyindex 8f9b78f3c8..324c857392 100644--- a/openhands/app_server/utils/llm.py+++ b/openhands/app_server/utils/llm.py@@ -81,12 +81,24 @@ class ModelsResponse(BaseModel):* ``verified_providers`` — provider names shown in the "Verified"section of the model selector.* ``default_model`` — the recommended default model id.+ * ``hidden_models`` — ``provider/model`` strings that the backend still+ serves but does not promote: they must not be offered as dropdown+ options, yet an already-saved setting referencing one is still valid+ (e.g. legacy alias routes on a managed LiteLLM proxy). Default empty,+ so SaaS / default discovery behavior is unchanged.+ * ``hidden_model_canonicals`` — maps a hidden ``provider/model`` string+ to the visible ``provider/model`` it aliases, so clients can display a+ saved hidden model under its canonical name. Only mappings whose+ target is in ``models`` are included. Default empty, so SaaS / default+ discovery behavior is unchanged."""models: list[str]verified_models: list[str]verified_providers: list[str]default_model: str+ hidden_models: list[str] = []+ hidden_model_canonicals: dict[str, str] = {}def is_openhands_model(model: str | None) -> bool:diff --git a/openhands/app_server/web_client/default_web_client_config_injector.py b/openhands/app_server/web_client/default_web_client_config_injector.pyindex ed625cda7b..c73db026dc 100644--- a/openhands/app_server/web_client/default_web_client_config_injector.py+++ b/openhands/app_server/web_client/default_web_client_config_injector.py@@ -163,6 +163,9 @@ def _get_feature_flags() -> WebClientFeatureFlags:HIDE_PERSONAL_WORKSPACES, ENABLE_ACP, and OH_ENABLE_ONBOARDING fromenvironment. Each flag is True only if the corresponding env var isexactly 'true', otherwise False.++ OH_ALLOW_USER_LLM_CONFIGURATION is the exception: it defaults to 'true'+ when unset so SaaS and existing installs keep the BYOK editing UI."""return WebClientFeatureFlags(enable_billing=os.getenv('ENABLE_BILLING', 'false') == 'true',@@ -175,6 +178,10 @@ def _get_feature_flags() -> WebClientFeatureFlags:hide_integrations_page=os.getenv('HIDE_INTEGRATIONS_PAGE', 'false') == 'true',hide_personal_workspaces=os.getenv('HIDE_PERSONAL_WORKSPACES', 'false')== 'true',+ allow_user_llm_configuration=os.getenv(+ 'OH_ALLOW_USER_LLM_CONFIGURATION', 'true'+ )+ == 'true',enable_acp=os.getenv('ENABLE_ACP', 'false') == 'true',enable_onboarding=os.getenv('OH_ENABLE_ONBOARDING', 'false') == 'true',)diff --git a/openhands/app_server/web_client/web_client_models.py b/openhands/app_server/web_client/web_client_models.pyindex 63472f5591..521736cea2 100644--- a/openhands/app_server/web_client/web_client_models.py+++ b/openhands/app_server/web_client/web_client_models.py@@ -26,6 +26,13 @@ class WebClientFeatureFlags(BaseModel):# workspace users see. UI-level only — the orgs API still returns# personal orgs, and disabling the flag restores them.hide_personal_workspaces: bool = False+ # When false, the web client hides the BYOK editing UI (custom model+ # string, base URL, and API key inputs) in LLM settings, leaving only the+ # managed model dropdown. Used by OHE installs where admins curate the+ # model list on the bundled LiteLLM proxy. Defaults to True so SaaS and+ # existing installs are unaffected. UI-level only — previously saved BYOK+ # settings keep working at runtime.+ allow_user_llm_configuration: bool = Trueenable_acp: bool = Falsedeployment_mode: DeploymentMode | None = Noneenable_onboarding: bool = Falsediff --git a/tests/unit/app_server/test_default_web_client_config_injector.py b/tests/unit/app_server/test_default_web_client_config_injector.pyindex 7a5755eee5..da92f66d65 100644--- a/tests/unit/app_server/test_default_web_client_config_injector.py+++ b/tests/unit/app_server/test_default_web_client_config_injector.py@@ -216,6 +216,40 @@ class TestGetFeatureFlags:result = _get_feature_flags()assert result.enable_linear is True+ def test_allow_user_llm_configuration_true_when_env_var_unset(self):+ """OH_ALLOW_USER_LLM_CONFIGURATION defaults to True when unset.++ Critical: SaaS and existing installs never set this env var, so the+ BYOK editing UI must stay visible for them.+ """+ from openhands.app_server.web_client.default_web_client_config_injector import (+ _get_feature_flags,+ )++ with patch.dict(os.environ, {}, clear=True):+ result = _get_feature_flags()+ assert result.allow_user_llm_configuration is True++ def test_allow_user_llm_configuration_true_when_env_var_true(self):+ """When OH_ALLOW_USER_LLM_CONFIGURATION is 'true', the flag is True."""+ from openhands.app_server.web_client.default_web_client_config_injector import (+ _get_feature_flags,+ )++ with patch.dict(os.environ, {'OH_ALLOW_USER_LLM_CONFIGURATION': 'true'}):+ result = _get_feature_flags()+ assert result.allow_user_llm_configuration is True++ def test_allow_user_llm_configuration_false_when_env_var_false(self):+ """When OH_ALLOW_USER_LLM_CONFIGURATION is 'false', the flag is False."""+ from openhands.app_server.web_client.default_web_client_config_injector import (+ _get_feature_flags,+ )++ with patch.dict(os.environ, {'OH_ALLOW_USER_LLM_CONFIGURATION': 'false'}):+ result = _get_feature_flags()+ assert result.allow_user_llm_configuration is False+def test_multiple_flags_can_be_set(self):"""Multiple feature flags can be enabled simultaneously."""from openhands.app_server.web_client.default_web_client_config_injector import (diff --git a/tests/unit/app_server/test_llm_model_service.py b/tests/unit/app_server/test_llm_model_service.pyindex bb48b1063a..3db824bd24 100644--- a/tests/unit/app_server/test_llm_model_service.py+++ b/tests/unit/app_server/test_llm_model_service.py@@ -11,8 +11,10 @@ from openhands.app_server.config_api.config_models import (from openhands.app_server.config_api.default_llm_model_service import (DefaultLLMModelService,DefaultLLMModelServiceInjector,+ _to_llm_models,)from openhands.app_server.config_api.llm_model_service import LLMModelService+from openhands.app_server.utils.llm import ModelsResponseclass TestDefaultLLMModelServiceSearchModels:@@ -173,6 +175,42 @@ class TestDefaultLLMModelServiceSearchModels:]+class TestToLLMModelsHiddenCanonical:+ """Hidden models and their canonical mappings flow into LLMModel items."""++ def test_canonical_set_only_on_mapped_hidden_models(self):+ response = ModelsResponse(+ models=['openhands/real-model'],+ verified_models=['real-model'],+ verified_providers=['openhands'],+ default_model='openhands/real-model',+ hidden_models=['openhands/legacy-alias', 'openhands/untagged-alias'],+ hidden_model_canonicals={'openhands/legacy-alias': 'openhands/real-model'},+ )++ by_name = {m.name: m for m in _to_llm_models(response)}++ assert by_name['real-model'].hidden is False+ assert by_name['real-model'].canonical is None+ assert by_name['legacy-alias'].hidden is True+ # Canonical is reported as a bare model name, like ``name``.+ assert by_name['legacy-alias'].canonical == 'real-model'+ assert by_name['untagged-alias'].hidden is True+ assert by_name['untagged-alias'].canonical is None++ def test_defaults_empty_no_hidden_items(self):+ response = ModelsResponse(+ models=['openhands/real-model'],+ verified_models=['real-model'],+ verified_providers=['openhands'],+ default_model='openhands/real-model',+ )++ models = _to_llm_models(response)++ assert all(not m.hidden and m.canonical is None for m in models)++class TestDefaultLLMModelServiceSearchProviders:"""Test suite for DefaultLLMModelService.search_providers."""