Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat(settings): add saved LLM profiles (BE) (#14146)

Vasco Schiavo23b3b188c45f
diff --git a/enterprise/migrations/versions/109_add_llm_profiles_to_user.py b/enterprise/migrations/versions/109_add_llm_profiles_to_user.py
new file mode 100644
index 0000000000..1cec889f61
--- /dev/null
+++ b/enterprise/migrations/versions/109_add_llm_profiles_to_user.py
@@ -0,0 +1,36 @@
+"""Add llm_profiles column to user table.
+
+The Settings model exposes ``llm_profiles`` (saved LLM configurations plus
+the active profile name), but the SaaS path persists a flattened Settings
+dump onto the User/Org rows. Without a column here the field is silently
+dropped on store() and always defaults to empty on load(), so saved
+profiles disappear after any settings update or page refresh.
+
+The column is plain ``String`` because the ORM-level ``EncryptedJSON``
+TypeDecorator stores JSON-serialized profiles as a JWE-encrypted string β€”
+profiles can carry per-profile ``api_key`` values, so the at-rest
+representation must match the existing org/member encrypted-secret pattern.
+
+Revision ID: 109
+Revises: 108
+Create Date: 2026-04-28
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = '109'
+down_revision: Union[str, None] = '108'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+ op.add_column('user', sa.Column('llm_profiles', sa.String(), nullable=True))
+
+
+def downgrade() -> None:
+ op.drop_column('user', 'llm_profiles')
diff --git a/enterprise/storage/encrypt_utils.py b/enterprise/storage/encrypt_utils.py
index a612a2ca0a..a4b83be0f1 100644
--- a/enterprise/storage/encrypt_utils.py
+++ b/enterprise/storage/encrypt_utils.py
@@ -1,10 +1,14 @@
import binascii
import hashlib
+import json
from base64 import b64decode, b64encode
+from typing import Any
from cryptography.fernet import Fernet, InvalidToken
from pydantic import SecretStr
from server.config import get_config
+from sqlalchemy import String, TypeDecorator
+from sqlalchemy.engine.interfaces import Dialect
_jwt_service = None
_fernet = None
@@ -135,3 +139,31 @@ def model_to_kwargs(model_instance):
column.name: getattr(model_instance, column.name)
for column in model_instance.__table__.columns
}
+
+
+class EncryptedJSON(TypeDecorator[dict[str, Any]]):
+ """JSON column whose serialized payload is encrypted at rest.
+
+ Use for JSON dicts that may contain secrets (e.g. nested ``api_key``
+ fields) where the existing ``_<field>`` String + property pattern is
+ awkward β€” this keeps the column accessible as a normal ORM attribute
+ while encrypting the entire JSON blob via the same JWE service used
+ by ``encrypt_value``/``decrypt_value``.
+ """
+
+ impl = String
+ cache_ok = True
+
+ def process_bind_param(
+ self, value: dict[str, Any] | None, dialect: Dialect
+ ) -> str | None:
+ if value is None:
+ return None
+ return encrypt_value(json.dumps(value))
+
+ def process_result_value(
+ self, value: str | None, dialect: Dialect
+ ) -> dict[str, Any] | None:
+ if value is None:
+ return None
+ return json.loads(decrypt_value(value))
diff --git a/enterprise/storage/saas_settings_store.py b/enterprise/storage/saas_settings_store.py
index 4f240a6d7f..1aae3e4342 100644
--- a/enterprise/storage/saas_settings_store.py
+++ b/enterprise/storage/saas_settings_store.py
@@ -148,6 +148,10 @@ class SaasSettingsStore(SettingsStore):
# Apply default if sandbox_grouping_strategy is None in the database
if kwargs.get('sandbox_grouping_strategy') is None:
kwargs.pop('sandbox_grouping_strategy', None)
+ # Pre-migration rows read back as None; Settings.llm_profiles is
+ # non-nullable, so let the default_factory take over.
+ if kwargs.get('llm_profiles') is None:
+ kwargs.pop('llm_profiles', None)
return Settings(**kwargs)
diff --git a/enterprise/storage/user.py b/enterprise/storage/user.py
index f1eb639c57..ef63b52f7d 100644
--- a/enterprise/storage/user.py
+++ b/enterprise/storage/user.py
@@ -3,13 +3,14 @@ SQLAlchemy model for User.
"""
from datetime import datetime
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
from uuid import UUID, uuid4
from sqlalchemy import DateTime, ForeignKey, String
from sqlalchemy.dialects.postgresql import JSON
from sqlalchemy.orm import Mapped, mapped_column, relationship
from storage.base import Base
+from storage.encrypt_utils import EncryptedJSON
if TYPE_CHECKING:
from storage.org import Org
@@ -36,6 +37,9 @@ class User(Base):
git_user_email: Mapped[str | None] = mapped_column(String, nullable=True)
sandbox_grouping_strategy: Mapped[str | None] = mapped_column(String, nullable=True)
disabled_skills: Mapped[list[str] | None] = mapped_column(JSON, nullable=True)
+ llm_profiles: Mapped[dict[str, Any] | None] = mapped_column(
+ EncryptedJSON, nullable=True
+ )
onboarding_completed: Mapped[bool | None] = mapped_column(
nullable=True, default=False
)
diff --git a/enterprise/tests/unit/test_saas_settings_store.py b/enterprise/tests/unit/test_saas_settings_store.py
index d48ea4a376..2672819269 100644
--- a/enterprise/tests/unit/test_saas_settings_store.py
+++ b/enterprise/tests/unit/test_saas_settings_store.py
@@ -175,6 +175,8 @@ def settings_store(async_session_maker, mock_config):
del item_dict['email_verified']
if 'secrets_store' in item_dict:
del item_dict['secrets_store']
+ if 'llm_profiles' in item_dict:
+ del item_dict['llm_profiles']
# Encrypt the data before storing
for key in ('llm_api_key', 'search_api_key', 'sandbox_api_key'):
@@ -772,3 +774,181 @@ async def test_store_and_load_mcp_config_via_agent_settings(
loaded.agent_settings.mcp_config.mcpServers['admin'].url
== 'https://admin-private-server.com'
)
+
+
+async def test_store_and_load_llm_profiles_round_trip(
+ async_session_maker, mock_config, org_with_multiple_members_fixture
+):
+ """Saved llm_profiles must persist on the User row and round-trip through
+ store β†’ load. Without the user.llm_profiles column they are silently
+ dropped on store and always default to empty on load."""
+ from openhands.sdk.llm import LLM
+
+ fixture = org_with_multiple_members_fixture
+ admin_user_id = str(fixture['admin_user_id'])
+ admin_store = SaasSettingsStore(admin_user_id, mock_config)
+
+ settings = DataSettings()
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'llm': {
+ 'model': 'anthropic/claude-sonnet-4-5-20250929',
+ 'base_url': 'https://api.anthropic.com/v1',
+ 'api_key': 'active-key',
+ },
+ },
+ }
+ )
+ settings.llm_profiles.save(
+ 'work',
+ LLM(
+ model='anthropic/claude-sonnet-4-5-20250929',
+ base_url='https://api.anthropic.com/v1',
+ api_key=SecretStr('work-key'),
+ ),
+ )
+ settings.llm_profiles.save(
+ 'personal',
+ LLM(
+ model='openai/gpt-5.2',
+ base_url='https://api.openai.com/v1',
+ api_key=SecretStr('personal-key'),
+ ),
+ )
+ settings.llm_profiles.active = 'work'
+
+ with patch('storage.saas_settings_store.a_session_maker', async_session_maker):
+ await admin_store.store(settings)
+
+ with (
+ patch('storage.saas_settings_store.a_session_maker', async_session_maker),
+ patch('storage.user_store.a_session_maker', async_session_maker),
+ patch('storage.org_store.a_session_maker', async_session_maker),
+ ):
+ loaded = await admin_store.load()
+
+ assert loaded is not None
+ assert set(loaded.llm_profiles.profiles.keys()) == {'work', 'personal'}
+ assert loaded.llm_profiles.active == 'work'
+
+ work = loaded.llm_profiles.require('work')
+ assert work.model == 'anthropic/claude-sonnet-4-5-20250929'
+ assert work.base_url == 'https://api.anthropic.com/v1'
+ assert work.api_key is not None
+ assert work.api_key.get_secret_value() == 'work-key'
+
+ personal = loaded.llm_profiles.require('personal')
+ assert personal.model == 'openai/gpt-5.2'
+ assert personal.api_key.get_secret_value() == 'personal-key'
+
+
+async def test_load_with_null_llm_profiles_column_uses_default_factory(
+ async_session_maker, mock_config, org_with_multiple_members_fixture
+):
+ """Rows predating the user.llm_profiles column read back as None.
+ Settings.llm_profiles is non-nullable (default_factory=LLMProfiles), so
+ load() must drop the None and let the factory produce an empty container
+ rather than crashing validation."""
+ from sqlalchemy import update
+ from storage.user import User
+
+ fixture = org_with_multiple_members_fixture
+ admin_user_id = fixture['admin_user_id']
+ admin_store = SaasSettingsStore(str(admin_user_id), mock_config)
+
+ seed_settings = _make_settings(
+ model='anthropic/claude-sonnet-4-5-20250929',
+ api_key='seed-key',
+ base_url='https://api.anthropic.com/v1',
+ )
+ with patch('storage.saas_settings_store.a_session_maker', async_session_maker):
+ await admin_store.store(seed_settings)
+
+ async with async_session_maker() as session:
+ await session.execute(
+ update(User).where(User.id == admin_user_id).values(llm_profiles=None)
+ )
+ await session.commit()
+
+ with (
+ patch('storage.saas_settings_store.a_session_maker', async_session_maker),
+ patch('storage.user_store.a_session_maker', async_session_maker),
+ patch('storage.org_store.a_session_maker', async_session_maker),
+ ):
+ loaded = await admin_store.load()
+
+ assert loaded is not None
+ assert loaded.llm_profiles.profiles == {}
+ assert loaded.llm_profiles.active is None
+
+
+async def test_llm_profiles_are_encrypted_at_rest(
+ async_session_maker, mock_config, org_with_multiple_members_fixture
+):
+ """The raw value in the user.llm_profiles column must be ciphertext, not
+ a JSON dict β€” profile api_keys would otherwise leak in DB dumps,
+ replicas, and backups. Mirrors the encryption invariant org and
+ org_member already enforce on _llm_api_key."""
+ from sqlalchemy import select, text
+ from storage.user import User
+
+ from openhands.sdk.llm import LLM
+
+ fixture = org_with_multiple_members_fixture
+ admin_user_id = fixture['admin_user_id']
+ admin_store = SaasSettingsStore(str(admin_user_id), mock_config)
+
+ settings = DataSettings()
+ settings.update(
+ {
+ 'agent_settings_diff': {
+ 'llm': {
+ 'model': 'anthropic/claude-sonnet-4-5-20250929',
+ 'base_url': 'https://api.anthropic.com/v1',
+ 'api_key': 'active-key',
+ },
+ },
+ }
+ )
+ settings.llm_profiles.save(
+ 'work',
+ LLM(
+ model='anthropic/claude-sonnet-4-5-20250929',
+ base_url='https://api.anthropic.com/v1',
+ api_key=SecretStr('super-secret-byok'),
+ ),
+ )
+ with patch('storage.saas_settings_store.a_session_maker', async_session_maker):
+ await admin_store.store(settings)
+
+ async with async_session_maker() as session:
+ # Bypass the ORM-level TypeDecorator by reading the raw cell.
+ # SQLite stores UUIDs hyphen-stripped, so normalize both sides.
+ rows = (
+ await session.execute(text('SELECT id, llm_profiles FROM "user"'))
+ ).all()
+ raw = next(
+ (r[1] for r in rows if str(r[0]).replace('-', '') == admin_user_id.hex),
+ None,
+ )
+ assert raw is not None
+ # The plaintext secret must not appear anywhere in the at-rest payload.
+ assert 'super-secret-byok' not in raw
+ # And the raw payload must not be parseable as JSON β€” i.e. it's
+ # encrypted, not a serialized profiles dict.
+ import json as _json
+
+ with pytest.raises(_json.JSONDecodeError):
+ _json.loads(raw)
+
+ # Sanity: ORM read still decrypts correctly.
+ async with async_session_maker() as session:
+ user = (
+ await session.execute(select(User).where(User.id == admin_user_id))
+ ).scalar_one()
+ assert user.llm_profiles is not None
+ assert user.llm_profiles['profiles']['work']['api_key'] == 'super-secret-byok'
diff --git a/openhands/app_server/settings/settings_models.py b/openhands/app_server/settings/settings_models.py
index 3a4a257e74..965dfd5224 100644
--- a/openhands/app_server/settings/settings_models.py
+++ b/openhands/app_server/settings/settings_models.py
@@ -30,6 +30,7 @@ from openhands.core.config.utils import load_openhands_config
from openhands.integrations.provider import ProviderToken
from openhands.integrations.service_types import ProviderType
from openhands.sdk.settings import ConversationSettings
+from openhands.storage.data_models.llm_profiles import LLMProfiles
from openhands.utils.jsonpatch_compat import deep_merge
from openhands.utils.sdk_settings_compat import (
ACPAgentSettings,
@@ -106,7 +107,14 @@ class SandboxGroupingStrategy(str, Enum):
ADD_TO_ANY = 'ADD_TO_ANY' # Add to any available sandbox (first found)
-_SETTINGS_FROZEN_FIELDS = frozenset(['secrets_store'])
+# Fields the batch ``update()`` method refuses to touch:
+# - ``secrets_store`` is frozen (Pydantic would raise).
+# - ``llm_profiles`` is off-limits for the generic settings POST; profile
+# mutations go through ``/api/v1/settings/profiles/...`` which validate
+# inputs, enforce the count cap, and take the per-user lock. Accepting a
+# raw dict here both bypassed those guards and crashed downstream
+# serialisation.
+_SETTINGS_UPDATE_IGNORED_FIELDS = frozenset(['secrets_store', 'llm_profiles'])
class Settings(BaseModel):
@@ -144,6 +152,13 @@ class Settings(BaseModel):
sandbox_grouping_strategy: SandboxGroupingStrategy = (
SandboxGroupingStrategy.NO_GROUPING
)
+ llm_profiles: LLMProfiles = Field(
+ default_factory=LLMProfiles,
+ description=(
+ 'Saved LLM profiles and the currently active profile name. '
+ 'See ``LLMProfiles`` for the profile-management API.'
+ ),
+ )
model_config = ConfigDict(populate_by_name=True)
@@ -167,6 +182,22 @@ class Settings(BaseModel):
# ── Batch update ────────────────────────────────────────────────
+ def reconcile_active_profile(self) -> None:
+ """Clear ``llm_profiles.active`` when the current LLM diverges from it.
+
+ The active profile is a pointer into ``llm_profiles.profiles``; if the
+ user edits ``agent_settings.llm`` directly (via the main settings
+ endpoint), the pointer becomes a lie. Rather than mutate the saved
+ profile, we drop the active marker so the frontend stops claiming a
+ profile is "in use" that no longer matches what's actually running.
+ """
+ active = self.llm_profiles.active
+ if active is None:
+ return
+ saved = self.llm_profiles.get(active)
+ if saved is None or saved != self.agent_settings.llm:
+ self.llm_profiles.active = None
+
def update(self, payload: dict[str, Any]) -> None:
"""Apply a batch of changes from a nested dict.
@@ -222,7 +253,10 @@ class Settings(BaseModel):
for key, value in payload.items():
if key in ('agent_settings_diff', 'conversation_settings_diff'):
continue
- if key in Settings.model_fields and key not in _SETTINGS_FROZEN_FIELDS:
+ if (
+ key in Settings.model_fields
+ and key not in _SETTINGS_UPDATE_IGNORED_FIELDS
+ ):
field_info = Settings.model_fields[key]
# Coerce plain strings to SecretStr when the field type expects it
if value is not None and isinstance(value, str):
@@ -234,6 +268,8 @@ class Settings(BaseModel):
value = SecretStr(value) if value else None
setattr(self, key, value)
+ self.reconcile_active_profile()
+
# ── Serialization ───────────────────────────────────────────────
@field_serializer('search_api_key')
@@ -261,6 +297,21 @@ class Settings(BaseModel):
)
return agent_settings.model_dump(mode='json')
+ # ── Profile management ─────────────────────────────────────────
+ #
+ # Pure profile operations (get/save/delete/summaries) live on
+ # ``LLMProfiles``. ``switch_to_profile`` remains here because it
+ # touches ``agent_settings.llm``.
+
+ def switch_to_profile(self, name: str) -> None:
+ """Switch ``agent_settings.llm`` to a saved profile.
+
+ Raises :class:`ProfileNotFoundError` if ``name`` isn't a saved profile.
+ """
+ llm = self.llm_profiles.require(name)
+ self.agent_settings = self.agent_settings.model_copy(update={'llm': llm})
+ self.llm_profiles.active = name
+
@model_validator(mode='before')
@classmethod
def _normalize_inputs(cls, data: dict | object) -> dict | object:
diff --git a/openhands/app_server/settings/settings_router.py b/openhands/app_server/settings/settings_router.py
index 7af19ea4f2..cd3d804fb7 100644
--- a/openhands/app_server/settings/settings_router.py
+++ b/openhands/app_server/settings/settings_router.py
@@ -3,11 +3,14 @@
This module provides the V1 API routes for user settings under /api/v1/settings.
"""
+import asyncio
import os
-from typing import Any
+from collections import defaultdict
+from typing import Annotated, Any
-from fastapi import APIRouter, Depends, status
+from fastapi import APIRouter, Body, Depends, HTTPException, Path, status
from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
from openhands.app_server.secrets.secrets_models import Secrets
from openhands.app_server.secrets.secrets_store import SecretsStore
@@ -22,14 +25,22 @@ from openhands.integrations.provider import (
PROVIDER_TOKEN_TYPE,
ProviderType,
)
+from openhands.sdk.llm import LLM
from openhands.sdk.settings import ConversationSettings
from openhands.server.shared import config
from openhands.server.user_auth import (
get_provider_tokens,
get_secrets_store,
+ get_user_id,
get_user_settings,
get_user_settings_store,
)
+from openhands.storage.data_models.llm_profiles import (
+ ProfileAlreadyExistsError,
+ ProfileLimitExceededError,
+ ProfileNotFoundError,
+ StrictLLM,
+)
from openhands.utils.llm import (
get_provider_api_base,
is_openhands_model,
@@ -291,3 +302,311 @@ async def invalidate_legacy_secrets_store(
return user_secrets
return None
+
+
+# ── LLM Profile endpoints ─────────────────────────────────────────
+
+# Profile name constraints: alphanumerics + . _ - only, 1-64 chars. This
+# blocks empty names, path-traversal fragments, slash-in-name routing
+# ambiguity, and pathological long inputs. Applied via ``Path`` so FastAPI
+# rejects the request before the handler runs.
+_NAME_PATTERN = r'^[A-Za-z0-9._-]{1,64}$'
+ProfileName = Annotated[
+ str,
+ Path(min_length=1, max_length=64, pattern=_NAME_PATTERN),
+]
+
+# Per-user asyncio lock serializing the read-modify-write cycle for profile
+# writes. This eliminates the lost-update race between concurrent
+# save/delete/activate calls *within a single worker process*. In
+# multi-worker SaaS deployments, DB-level row locks or optimistic
+# concurrency tokens are still required for full safety β€” but this closes
+# the single-process hole. The dict grows with distinct user ids; acceptable
+# because each lock is tiny and users are bounded per-process in practice.
+_user_profile_locks: defaultdict[str, asyncio.Lock] = defaultdict(asyncio.Lock)
+
+
+def _profile_lock_key(user_id: str | None) -> str:
+ return user_id or '<anonymous>'
+
+
+class ProfileInfo(BaseModel):
+ """Profile summary returned by the list endpoint.
+
+ ``api_key_set`` follows the same convention as ``llm_api_key_set`` on
+ the main settings response β€” the frontend uses it to show "key stored"
+ without exposing (or accidentally round-tripping) a mask string.
+ """
+
+ name: str
+ model: str | None = None
+ base_url: str | None = None
+ api_key_set: bool = False
+
+
+class ProfileListResponse(BaseModel):
+ """Response body for listing profiles."""
+
+ profiles: list[ProfileInfo]
+ active_profile: str | None = None
+
+
+class ProfileDetailResponse(BaseModel):
+ """Response body for fetching a single profile.
+
+ ``config.api_key`` is always ``None`` in the response; the sibling
+ ``api_key_set`` bool reports whether a key is stored. This matches
+ the ``/api/v1/settings`` convention and prevents the "GET β†’ edit β†’
+ POST" flow from poisoning the stored key with a mask string.
+ """
+
+ name: str
+ config: dict[str, Any]
+ api_key_set: bool = False
+
+
+class ProfileMutationResponse(BaseModel):
+ """Response body for save/delete operations."""
+
+ name: str
+ message: str
+
+
+class ActivateProfileResponse(BaseModel):
+ """Response body for activating a profile."""
+
+ name: str
+ message: str
+ model: str | None = None
+
+
+class RenameProfileRequest(BaseModel):
+ """Request body for renaming a profile.
+
+ ``new_name`` is validated against the same regex as the path-level
+ ``{name}`` param so the two stay in sync.
+ """
+
+ new_name: str = Field(
+ ...,
+ min_length=1,
+ max_length=64,
+ pattern=_NAME_PATTERN,
+ )
+
+
+class SaveProfileRequest(BaseModel):
+ """Request body for saving a profile.
+
+ If ``llm`` is provided, it is used as the profile config; otherwise the
+ current ``agent_settings.llm`` is saved. The ``llm`` field is typed as
+ :class:`StrictLLM`, which forbids unknown keys β€” so a typo like
+ ``{"llm": {"custom_header": "x"}}`` returns 422 instead of being silently
+ dropped.
+
+ **Security note:** when ``llm.api_key`` is included in the request body,
+ it is transmitted in plaintext over the wire and present in any request
+ log or error trace that captures request bodies. ``SecretStr`` masks it
+ in Pydantic reprs, but callers and operators should still avoid logging
+ raw request bodies on this endpoint.
+ """
+
+ include_secrets: bool = True
+ llm: StrictLLM | None = None
+
+
[email protected]('/profiles', response_model=ProfileListResponse)
+async def list_profiles(
+ settings: Settings | None = Depends(get_user_settings),
+) -> ProfileListResponse:
+ """List all saved LLM profiles.
+
+ Returns profile names with basic model info. API keys are never exposed.
+ """
+ if settings is None:
+ return ProfileListResponse(profiles=[], active_profile=None)
+
+ return ProfileListResponse(
+ profiles=[ProfileInfo(**p) for p in settings.llm_profiles.summaries()],
+ active_profile=settings.llm_profiles.active,
+ )
+
+
[email protected]('/profiles/{name}', response_model=ProfileDetailResponse)
+async def get_profile(
+ name: ProfileName,
+ settings: Settings | None = Depends(get_user_settings),
+) -> ProfileDetailResponse:
+ """Get a specific profile's configuration.
+
+ Returns the full LLM config with ``api_key`` nulled out; the sibling
+ ``api_key_set`` flag reports whether a key is stored.
+ """
+ profile = settings.llm_profiles.get(name) if settings is not None else None
+ if profile is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Profile '{name}' not found",
+ )
+
+ api_key_set = profile.api_key is not None
+ config = profile.model_dump(mode='json')
+ config['api_key'] = None # never echo a mask; use api_key_set instead
+
+ return ProfileDetailResponse(name=name, config=config, api_key_set=api_key_set)
+
+
+ '/profiles/{name}',
+ response_model=ProfileMutationResponse,
+ status_code=status.HTTP_201_CREATED,
+)
+async def save_profile(
+ name: ProfileName,
+ request: Annotated[SaveProfileRequest | None, Body()] = None,
+ user_id: str | None = Depends(get_user_id),
+ settings_store: SettingsStore = Depends(get_user_settings_store),
+) -> ProfileMutationResponse:
+ """Save an LLM configuration as a named profile.
+
+ If ``request.llm`` is supplied, it is saved as the profile's config.
+ Otherwise the current ``agent_settings.llm`` is snapshotted. Existing
+ profiles with the same name are overwritten.
+
+ Runs inside a per-user lock to prevent lost updates between concurrent
+ profile writes. Returns 409 if the user is already at the profile
+ cap (:data:`MAX_PROFILES_PER_USER`).
+ """
+ if request is None:
+ request = SaveProfileRequest()
+
+ async with _user_profile_locks[_profile_lock_key(user_id)]:
+ settings = await settings_store.load()
+ if settings is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail='Settings not found',
+ )
+
+ llm: LLM
+ if request.llm is not None:
+ llm = request.llm
+ # Preserve the existing api_key when the caller omits it on
+ # update (e.g. a frontend round-tripping a GET response where
+ # the key was nulled out). Mirrors the deep-merge behaviour
+ # the main ``POST /api/v1/settings`` relies on.
+ if llm.api_key is None:
+ existing = settings.llm_profiles.get(name)
+ if existing is not None and existing.api_key is not None:
+ llm = llm.model_copy(update={'api_key': existing.api_key})
+ else:
+ llm = settings.agent_settings.llm
+
+ try:
+ settings.llm_profiles.save(
+ name, llm, include_secrets=request.include_secrets
+ )
+ except ProfileLimitExceededError as exc:
+ raise HTTPException(
+ status_code=status.HTTP_409_CONFLICT, detail=str(exc)
+ ) from exc
+ # Without this, overwriting the active profile leaves
+ # agent_settings.llm stale β€” active would lie about what's running.
+ settings.reconcile_active_profile()
+ await settings_store.store(settings)
+
+ return ProfileMutationResponse(name=name, message=f"Profile '{name}' saved")
+
+
[email protected]('/profiles/{name}', response_model=ProfileMutationResponse)
+async def delete_profile(
+ name: ProfileName,
+ user_id: str | None = Depends(get_user_id),
+ settings_store: SettingsStore = Depends(get_user_settings_store),
+) -> ProfileMutationResponse:
+ """Delete a saved profile.
+
+ Idempotent: returns success even if the profile didn't exist.
+ """
+ async with _user_profile_locks[_profile_lock_key(user_id)]:
+ settings = await settings_store.load()
+ if settings is not None and settings.llm_profiles.delete(name):
+ await settings_store.store(settings)
+
+ return ProfileMutationResponse(name=name, message=f"Profile '{name}' deleted")
+
+
[email protected]('/profiles/{name}/activate', response_model=ActivateProfileResponse)
+async def activate_profile(
+ name: ProfileName,
+ user_id: str | None = Depends(get_user_id),
+ settings_store: SettingsStore = Depends(get_user_settings_store),
+) -> ActivateProfileResponse:
+ """Switch ``agent_settings.llm`` to use a saved profile.
+
+ Applies the same ``base_url`` fixups as ``POST /api/v1/settings``, so
+ activating a profile that omits ``base_url`` still points at the
+ provider's default endpoint.
+ """
+ async with _user_profile_locks[_profile_lock_key(user_id)]:
+ settings = await settings_store.load()
+ if settings is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Profile '{name}' not found",
+ )
+
+ try:
+ settings.switch_to_profile(name)
+ except ProfileNotFoundError as exc:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=str(exc),
+ ) from exc
+
+ _post_merge_llm_fixups(settings)
+ await settings_store.store(settings)
+
+ return ActivateProfileResponse(
+ name=name,
+ message=f"Switched to profile '{name}'",
+ model=settings.agent_settings.llm.model,
+ )
+
+
[email protected]('/profiles/{name}/rename', response_model=ProfileMutationResponse)
+async def rename_profile(
+ name: ProfileName,
+ request: RenameProfileRequest,
+ user_id: str | None = Depends(get_user_id),
+ settings_store: SettingsStore = Depends(get_user_settings_store),
+) -> ProfileMutationResponse:
+ """Rename a saved profile.
+
+ Preserves the stored LLM config (including the api_key) and the active
+ flag if the renamed profile was active. Returns 409 if ``new_name`` is
+ already in use by a different profile.
+ """
+ async with _user_profile_locks[_profile_lock_key(user_id)]:
+ settings = await settings_store.load()
+ if settings is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail='Settings not found',
+ )
+ try:
+ settings.llm_profiles.rename(name, request.new_name)
+ except ProfileNotFoundError as exc:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)
+ ) from exc
+ except ProfileAlreadyExistsError as exc:
+ raise HTTPException(
+ status_code=status.HTTP_409_CONFLICT, detail=str(exc)
+ ) from exc
+ await settings_store.store(settings)
+
+ return ProfileMutationResponse(
+ name=request.new_name,
+ message=f"Profile '{name}' renamed to '{request.new_name}'",
+ )
diff --git a/openhands/storage/data_models/llm_profiles.py b/openhands/storage/data_models/llm_profiles.py
new file mode 100644
index 0000000000..b36a1b294f
--- /dev/null
+++ b/openhands/storage/data_models/llm_profiles.py
@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+from typing import Any, Final
+
+from pydantic import (
+ BaseModel,
+ ConfigDict,
+ Field,
+ SerializationInfo,
+ ValidationError,
+ field_serializer,
+ field_validator,
+ model_validator,
+)
+
+from openhands.core.logger import openhands_logger as logger
+from openhands.sdk.llm import LLM
+
+# Soft cap β€” keeps Settings payload bounded and blocks per-user storage
+# blow-ups. Tune if product requirements change.
+MAX_PROFILES_PER_USER: Final[int] = 10
+
+
+class ProfileNotFoundError(LookupError):
+ """Raised when a profile lookup or activation references an unknown name."""
+
+ def __init__(self, name: str) -> None:
+ self.name = name
+ super().__init__(f"Profile '{name}' not found")
+
+
+class ProfileLimitExceededError(ValueError):
+ """Raised when saving a new profile would exceed :data:`MAX_PROFILES_PER_USER`."""
+
+ def __init__(self, limit: int) -> None:
+ self.limit = limit
+ super().__init__(
+ f'Profile limit reached ({limit}). Delete a profile before saving a new one.'
+ )
+
+
+class ProfileAlreadyExistsError(ValueError):
+ """Raised when a rename target collides with an existing profile."""
+
+ def __init__(self, name: str) -> None:
+ self.name = name
+ super().__init__(f"Profile '{name}' already exists")
+
+
+class StrictLLM(LLM):
+ """LLM variant that rejects unknown fields.
+
+ The base ``LLM`` model has ``extra='ignore'``, so typos and renamed keys
+ silently disappear. For API input we want to fail loud, otherwise users
+ can POST ``{"llm": {"custom_header": "x"}}`` and get a 201 with the
+ field quietly dropped.
+ """
+
+ model_config = ConfigDict(extra='forbid')
+
+
+class LLMProfiles(BaseModel):
+ """Container for saved LLM configurations.
+
+ Stores a named collection of ``LLM`` configurations plus the name of the
+ currently active one (if any). All profile-management logic lives here;
+ ``Settings`` holds a single ``LLMProfiles`` instance and delegates to it.
+
+ Invariants (enforced on validate + assignment):
+ - ``active`` is either ``None`` or a key of ``profiles``.
+ - Individual profiles that fail to parse (schema drift) are dropped with
+ a warning rather than failing the whole ``Settings`` load.
+ """
+
+ model_config = ConfigDict(validate_assignment=True)
+
+ profiles: dict[str, LLM] = Field(default_factory=dict)
+ active: str | None = None
+
+ # ── Validation ─────────────────────────────────────────────────
+
+ @field_validator('profiles', mode='before')
+ @classmethod
+ def _skip_invalid_profiles(cls, value: Any) -> Any:
+ """Best-effort per-profile load: skip entries that fail to validate.
+
+ Guards against schema drift β€” if a single stored profile becomes
+ invalid after an LLM-model upgrade, the user's other profiles and
+ the rest of their settings still load.
+ """
+ if not isinstance(value, dict):
+ return value
+ valid: dict[str, Any] = {}
+ for name, raw in value.items():
+ if isinstance(raw, LLM):
+ valid[name] = raw
+ continue
+ try:
+ valid[name] = LLM.model_validate(raw)
+ except ValidationError as exc:
+ logger.warning('Skipping invalid LLM profile %r: %s', name, exc)
+ return valid
+
+ @model_validator(mode='after')
+ def _reconcile_active(self) -> LLMProfiles:
+ if self.active is not None and self.active not in self.profiles:
+ # Bypass validate_assignment to avoid re-entering this validator.
+ object.__setattr__(self, 'active', None)
+ return self
+
+ # ── Queries ────────────────────────────────────────────────────
+
+ def get(self, name: str) -> LLM | None:
+ """Return the profile's LLM or ``None`` if it doesn't exist."""
+ return self.profiles.get(name)
+
+ def require(self, name: str) -> LLM:
+ """Return the profile's LLM or raise :class:`ProfileNotFoundError`."""
+ llm = self.profiles.get(name)
+ if llm is None:
+ raise ProfileNotFoundError(name)
+ return llm
+
+ def has(self, name: str) -> bool:
+ return name in self.profiles
+
+ def summaries(self) -> list[dict[str, Any]]:
+ """Return a ``{name, model, base_url, api_key_set}`` dict per profile.
+
+ ``api_key_set`` mirrors the ``llm_api_key_set`` convention the main
+ settings endpoint already uses, so the frontend can render
+ "key stored" vs. "needs key" without fetching each profile.
+ """
+ return [
+ {
+ 'name': name,
+ 'model': llm.model,
+ 'base_url': llm.base_url,
+ 'api_key_set': llm.api_key is not None,
+ }
+ for name, llm in self.profiles.items()
+ ]
+
+ # ── Mutations ──────────────────────────────────────────────────
+
+ def save(self, name: str, llm: LLM, include_secrets: bool = True) -> None:
+ """Save ``llm`` under ``name``. Overwrites if the name exists.
+
+ Always stores a copy so later caller-side mutations do not bleed into
+ the stored profile. Raises :class:`ProfileLimitExceededError` if
+ saving a *new* profile would push the count past
+ :data:`MAX_PROFILES_PER_USER`.
+ """
+ if name not in self.profiles and len(self.profiles) >= MAX_PROFILES_PER_USER:
+ raise ProfileLimitExceededError(MAX_PROFILES_PER_USER)
+
+ update = {} if include_secrets else {'api_key': None}
+ self.profiles[name] = llm.model_copy(update=update)
+
+ def rename(self, old_name: str, new_name: str) -> None:
+ """Rename a profile, preserving stored LLM config, insertion order, and
+ the active flag (if the renamed profile was active).
+
+ Raises :class:`ProfileNotFoundError` if ``old_name`` doesn't exist,
+ or :class:`ProfileAlreadyExistsError` if ``new_name`` is already taken
+ by a different profile.
+ """
+ if old_name not in self.profiles:
+ raise ProfileNotFoundError(old_name)
+ if new_name == old_name:
+ return
+ if new_name in self.profiles:
+ raise ProfileAlreadyExistsError(new_name)
+
+ # Capture the active name *before* reassigning ``profiles`` β€” the
+ # model_validator runs on assignment and would null out ``active``
+ # (old_name no longer exists in the rebuilt dict), so we'd lose the
+ # signal otherwise.
+ was_active = self.active == old_name
+
+ # Rebuild to preserve insertion order β€” the renamed profile keeps
+ # the slot of the old one rather than moving to the end.
+ renamed: dict[str, LLM] = {
+ (new_name if key == old_name else key): llm
+ for key, llm in self.profiles.items()
+ }
+ self.profiles = renamed
+ if was_active:
+ # Bypass validate_assignment since we know the invariant holds
+ # (new_name is now a key of self.profiles).
+ object.__setattr__(self, 'active', new_name)
+
+ def delete(self, name: str) -> bool:
+ """Delete a profile. Returns True if the profile existed.
+
+ Clears ``active`` if the deleted profile was active.
+ """
+ if name not in self.profiles:
+ return False
+ del self.profiles[name]
+ if self.active == name:
+ # Bypass validate_assignment since we already know the invariant holds.
+ object.__setattr__(self, 'active', None)
+ return True
+
+ # ── Serialization ──────────────────────────────────────────────
+
+ @field_serializer('profiles')
+ def _profiles_serializer(
+ self,
+ profiles: dict[str, LLM],
+ info: SerializationInfo,
+ ) -> dict[str, Any]:
+ return {
+ name: llm.model_dump(mode='json', context=info.context)
+ for name, llm in profiles.items()
+ }
diff --git a/tests/unit/app_server/test_profiles_api.py b/tests/unit/app_server/test_profiles_api.py
new file mode 100644
index 0000000000..f2c7f5f355
--- /dev/null
+++ b/tests/unit/app_server/test_profiles_api.py
@@ -0,0 +1,979 @@
+"""Integration tests for the LLM profile endpoints in the settings router.
+
+Covers every endpoint under ``/api/v1/settings/profiles``:
+- list / get / save / delete / activate β€” happy paths and 404s.
+- 422 on malformed ``llm`` payload (Pydantic validates the request body).
+"""
+
+import os
+from contextlib import contextmanager
+from pathlib import Path
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from fastapi import Request
+from fastapi.testclient import TestClient
+from pydantic import SecretStr
+
+from openhands.app_server.secrets.secrets_models import Secrets
+from openhands.app_server.secrets.secrets_store import SecretsStore
+from openhands.app_server.settings.file_settings_store import FileSettingsStore
+from openhands.app_server.settings.settings_models import Settings
+from openhands.app_server.settings.settings_router import _user_profile_locks
+from openhands.app_server.settings.settings_store import SettingsStore
+from openhands.integrations.provider import ProviderToken, ProviderType
+from openhands.integrations.service_types import UserGitInfo
+from openhands.sdk.llm import LLM
+from openhands.sdk.settings import AgentSettings
+from openhands.server.app import app
+from openhands.server.user_auth.user_auth import UserAuth
+from openhands.storage.data_models.llm_profiles import MAX_PROFILES_PER_USER
+
+
[email protected](autouse=True)
+def _reset_profile_locks():
+ """Locks bind to the event loop that first awaited them; FastAPI TestClient
+ spins a fresh loop per test, so any stale Lock carried over from a previous
+ test would be attached to a dead loop. Clearing between tests fixes it."""
+ _user_profile_locks.clear()
+ yield
+ _user_profile_locks.clear()
+
+
+class _MockUserAuth(UserAuth):
+ def __init__(self, settings_store: SettingsStore) -> None:
+ self._settings = None
+ self._settings_store = settings_store
+
+ async def get_user_id(self) -> str | None:
+ return 'test-user'
+
+ async def get_user_email(self) -> str | None:
+
+ async def get_access_token(self) -> SecretStr | None:
+ return SecretStr('test-token')
+
+ async def get_provider_tokens(
+ self,
+ ) -> dict[ProviderType, ProviderToken] | None:
+ return None
+
+ async def get_user_settings_store(self) -> SettingsStore | None:
+ return self._settings_store
+
+ async def get_secrets_store(self) -> SecretsStore | None:
+ return None
+
+ async def get_secrets(self) -> Secrets | None:
+ return None
+
+ async def get_mcp_api_key(self) -> str | None:
+ return None
+
+ async def get_user_git_info(self) -> UserGitInfo | None:
+ return None
+
+ @classmethod
+ async def get_instance(cls, request: Request) -> UserAuth:
+ raise NotImplementedError # patched per-test
+
+ @classmethod
+ async def get_for_user(cls, user_id: str) -> UserAuth:
+ raise NotImplementedError # patched per-test
+
+
+def settings_store(tmp_path: Path) -> FileSettingsStore:
+ return FileSettingsStore(root_dir=tmp_path)
+
+
+def test_client(settings_store):
+ """TestClient wired to an in-memory settings store the test can seed directly."""
+ auth = _MockUserAuth(settings_store)
+ with (
+ patch.dict(
+ os.environ,
+ {'SESSION_API_KEY': '', 'ALLOW_SHORT_CONTEXT_WINDOWS': 'true'},
+ clear=False,
+ ),
+ patch('openhands.app_server.utils.dependencies._SESSION_API_KEY', None),
+ patch(
+ 'openhands.server.user_auth.user_auth.UserAuth.get_instance',
+ return_value=auth,
+ ),
+ patch(
+ 'openhands.app_server.settings.file_settings_store.FileSettingsStore.get_instance',
+ AsyncMock(return_value=settings_store),
+ ),
+ ):
+ yield TestClient(app)
+
+
+def _base_settings() -> Settings:
+ """A Settings instance with an LLM configured so 'snapshot current' works."""
+ return Settings(
+ agent_settings=AgentSettings(
+ llm=LLM(
+ model='openai/gpt-4o',
+ api_key=SecretStr('sk-current'),
+ ),
+ ),
+ )
+
+
+async def _seed(store: FileSettingsStore, settings: Settings) -> None:
+ await store.store(settings)
+
+
+@contextmanager
+def _client_for_user(user_id: str, store: FileSettingsStore):
+ """Yield a TestClient scoped to a specific user_id + settings store.
+
+ Used by multi-user isolation tests; the module-level ``test_client``
+ fixture is pinned to a single mock user.
+ """
+
+ class _Scoped(_MockUserAuth):
+ async def get_user_id(self) -> str | None: # type: ignore[override]
+ return user_id
+
+ auth = _Scoped(store)
+ with (
+ patch.dict(
+ os.environ,
+ {'SESSION_API_KEY': '', 'ALLOW_SHORT_CONTEXT_WINDOWS': 'true'},
+ clear=False,
+ ),
+ patch('openhands.app_server.utils.dependencies._SESSION_API_KEY', None),
+ patch(
+ 'openhands.server.user_auth.user_auth.UserAuth.get_instance',
+ return_value=auth,
+ ),
+ patch(
+ 'openhands.app_server.settings.file_settings_store.FileSettingsStore.get_instance',
+ AsyncMock(return_value=store),
+ ),
+ ):
+ yield TestClient(app)
+
+
+# ── GET /profiles ────────────────────────────────────────────────
+
+
+def test_list_profiles_returns_empty_when_no_settings(test_client):
+ response = test_client.get('/api/v1/settings/profiles')
+
+ assert response.status_code == 200
+ assert response.json() == {'profiles': [], 'active_profile': None}
+
+
+async def test_list_profiles_returns_saved_profiles(test_client, settings_store):
+ settings = _base_settings()
+ settings.llm_profiles.save(
+ 'my-gpt4',
+ LLM(model='openai/gpt-4o', api_key=SecretStr('sk-1')),
+ )
+ settings.llm_profiles.save('my-claude', LLM(model='anthropic/claude-opus-4'))
+ settings.llm_profiles.active = 'my-claude'
+ await _seed(settings_store, settings)
+
+ response = test_client.get('/api/v1/settings/profiles')
+
+ assert response.status_code == 200
+ body = response.json()
+ assert body['active_profile'] == 'my-claude'
+ names = {p['name'] for p in body['profiles']}
+ assert names == {'my-gpt4', 'my-claude'}
+
+
+# ── GET /profiles/{name} ─────────────────────────────────────────
+
+
+async def test_get_profile_returns_null_api_key_with_set_flag(
+ test_client, settings_store
+):
+ """``api_key`` is never echoed β€” the sibling ``api_key_set`` flag
+ tells the UI whether a key is stored. Prevents the GET→edit→POST
+ round-trip from poisoning the stored key with a mask string."""
+ settings = _base_settings()
+ settings.llm_profiles.save(
+ 'p', LLM(model='openai/gpt-4o', api_key=SecretStr('sk-secret'))
+ )
+ await _seed(settings_store, settings)
+
+ response = test_client.get('/api/v1/settings/profiles/p')
+
+ assert response.status_code == 200
+ body = response.json()
+ assert body['name'] == 'p'
+ assert body['config']['model'] == 'openai/gpt-4o'
+ assert body['config']['api_key'] is None
+ assert body['api_key_set'] is True
+
+
+def test_get_profile_returns_404_when_unknown(test_client):
+ response = test_client.get('/api/v1/settings/profiles/nope')
+
+ assert response.status_code == 404
+ assert "'nope'" in response.json()['detail']
+
+
+# ── POST /profiles/{name} ────────────────────────────────────────
+
+
+async def test_save_profile_with_explicit_llm_persists(test_client, settings_store):
+ await _seed(settings_store, _base_settings())
+
+ response = test_client.post(
+ '/api/v1/settings/profiles/my-new',
+ json={
+ 'llm': {
+ 'model': 'anthropic/claude-opus-4',
+ 'api_key': 'sk-new',
+ },
+ },
+ )
+
+ assert response.status_code == 201
+ assert response.json()['name'] == 'my-new'
+
+ stored = await settings_store.load()
+ assert stored.llm_profiles.has('my-new')
+ saved_llm = stored.llm_profiles.get('my-new')
+ assert saved_llm.model == 'anthropic/claude-opus-4'
+ assert saved_llm.api_key.get_secret_value() == 'sk-new'
+
+
+async def test_save_profile_snapshots_current_llm_when_no_body(
+ test_client, settings_store
+):
+ await _seed(settings_store, _base_settings())
+
+ response = test_client.post('/api/v1/settings/profiles/snapshot', json={})
+
+ assert response.status_code == 201
+ stored = await settings_store.load()
+ snap = stored.llm_profiles.get('snapshot')
+ assert snap is not None
+ assert snap.model == 'openai/gpt-4o'
+ assert snap.api_key.get_secret_value() == 'sk-current'
+
+
+async def test_save_profile_without_secrets_clears_api_key(test_client, settings_store):
+ await _seed(settings_store, _base_settings())
+
+ response = test_client.post(
+ '/api/v1/settings/profiles/no-key',
+ json={
+ 'include_secrets': False,
+ 'llm': {'model': 'openai/gpt-4o', 'api_key': 'sk-abc'},
+ },
+ )
+
+ assert response.status_code == 201
+ stored = await settings_store.load()
+ assert stored.llm_profiles.get('no-key').api_key is None
+
+
+async def test_save_profile_overwrites_existing(test_client, settings_store):
+ settings = _base_settings()
+ settings.llm_profiles.save('p', LLM(model='openai/gpt-4o'))
+ await _seed(settings_store, settings)
+
+ response = test_client.post(
+ '/api/v1/settings/profiles/p',
+ json={'llm': {'model': 'anthropic/claude-opus-4'}},
+ )
+
+ assert response.status_code == 201
+ stored = await settings_store.load()
+ assert stored.llm_profiles.get('p').model == 'anthropic/claude-opus-4'
+
+
+async def test_save_overwrite_of_active_profile_clears_active(
+ test_client, settings_store
+):
+ """Overwriting the currently-active profile must drop ``active`` β€”
+ otherwise the UI claims profile X is in use while ``agent_settings.llm``
+ still points at the *old* X. Mirrors the safety net the main settings
+ POST already enforces via ``reconcile_active_profile``.
+ """
+ settings = _base_settings()
+ settings.llm_profiles.save('p', LLM(model='openai/gpt-4o'))
+ settings.switch_to_profile('p') # makes 'p' active *and* the running llm
+ await _seed(settings_store, settings)
+ assert test_client.get('/api/v1/settings/profiles').json()['active_profile'] == 'p'
+
+ # Save a different config under the same name.
+ response = test_client.post(
+ '/api/v1/settings/profiles/p',
+ json={'llm': {'model': 'anthropic/claude-opus-4'}},
+ )
+ assert response.status_code == 201
+
+ body = test_client.get('/api/v1/settings/profiles').json()
+ assert body['active_profile'] is None
+ # The saved profile reflects the new config; the active marker is gone
+ # because agent_settings.llm still runs the previous one.
+ stored = await settings_store.load()
+ assert stored.llm_profiles.get('p').model == 'anthropic/claude-opus-4'
+ assert stored.agent_settings.llm.model == 'openai/gpt-4o'
+
+
+async def test_save_overwrite_of_inactive_profile_preserves_active(
+ test_client, settings_store
+):
+ """Overwriting a non-active profile must NOT touch the active marker β€”
+ only the active profile can diverge from agent_settings.llm.
+ """
+ settings = _base_settings()
+ settings.llm_profiles.save('active', LLM(model='openai/gpt-4o'))
+ settings.llm_profiles.save('other', LLM(model='openai/gpt-4o'))
+ settings.switch_to_profile('active')
+ await _seed(settings_store, settings)
+
+ test_client.post(
+ '/api/v1/settings/profiles/other',
+ json={'llm': {'model': 'anthropic/claude-opus-4'}},
+ )
+
+ body = test_client.get('/api/v1/settings/profiles').json()
+ assert body['active_profile'] == 'active'
+
+
+async def test_save_profile_rejects_invalid_llm_with_422(test_client, settings_store):
+ await _seed(settings_store, _base_settings())
+
+ # Missing required `model`; StrictLLM would also reject the unknown key.
+ response = test_client.post(
+ '/api/v1/settings/profiles/bad',
+ json={'llm': {'not_a_real_llm_field': True}},
+ )
+
+ assert response.status_code == 422
+
+
+async def test_edit_profile_round_trip_preserves_api_key(test_client, settings_store):
+ """Frontend GET→edit→POST flow must not corrupt the stored key.
+
+ The GET response returns ``api_key: null``; when the frontend echoes
+ that back in the POST body, the server has to preserve the stored
+ key rather than overwrite with None. This is the concrete
+ mask-poisoning regression we fixed.
+ """
+ await _seed(settings_store, _base_settings())
+ test_client.post(
+ '/api/v1/settings/profiles/p',
+ json={'llm': {'model': 'openai/gpt-4o', 'api_key': 'REAL-KEY-42'}},
+ )
+
+ fetched = test_client.get('/api/v1/settings/profiles/p').json()
+ fetched['config']['model'] = 'anthropic/claude-opus-4' # user edits model
+ assert fetched['config']['api_key'] is None # GET returns null, not mask
+
+ resp = test_client.post(
+ '/api/v1/settings/profiles/p', json={'llm': fetched['config']}
+ )
+ assert resp.status_code == 201
+
+ stored = await settings_store.load()
+ preserved = stored.llm_profiles.get('p')
+ assert preserved.model == 'anthropic/claude-opus-4'
+ assert preserved.api_key.get_secret_value() == 'REAL-KEY-42'
+
+
+async def test_edit_profile_with_new_api_key_replaces_old(test_client, settings_store):
+ """Counter-test to the round-trip guard: when the user actually types
+ a new api_key in the edit form, the server must replace the stored
+ one. Catches a logic regression where ``preserve`` runs
+ unconditionally and swallows intentional updates.
+ """
+ await _seed(settings_store, _base_settings())
+ test_client.post(
+ '/api/v1/settings/profiles/p',
+ json={'llm': {'model': 'openai/gpt-4o', 'api_key': 'OLD-KEY'}},
+ )
+
+ resp = test_client.post(
+ '/api/v1/settings/profiles/p',
+ json={'llm': {'model': 'openai/gpt-4o', 'api_key': 'NEW-KEY'}},
+ )
+ assert resp.status_code == 201
+
+ stored = await settings_store.load()
+ assert stored.llm_profiles.get('p').api_key.get_secret_value() == 'NEW-KEY'
+
+
+async def test_list_profiles_reports_api_key_set_per_row(test_client, settings_store):
+ settings = _base_settings()
+ settings.llm_profiles.save(
+ 'with-key',
+ LLM(model='openai/gpt-4o', api_key=SecretStr('sk-abc')),
+ )
+ settings.llm_profiles.save(
+ 'no-key',
+ LLM(model='ollama/llama3', base_url='http://localhost:11434'),
+ )
+ await _seed(settings_store, settings)
+
+ rows = {
+ p['name']: p
+ for p in test_client.get('/api/v1/settings/profiles').json()['profiles']
+ }
+
+ assert rows['with-key']['api_key_set'] is True
+ assert rows['no-key']['api_key_set'] is False
+
+
+async def test_save_profile_rejects_unknown_llm_field(test_client, settings_store):
+ """StrictLLM forbids extras β†’ typo in an LLM field returns 422 instead of a silent 201."""
+ await _seed(settings_store, _base_settings())
+
+ response = test_client.post(
+ '/api/v1/settings/profiles/typo',
+ json={'llm': {'model': 'openai/gpt-4o', 'custom_header': 'x'}},
+ )
+
+ assert response.status_code == 422
+
+
+# ── DELETE /profiles/{name} ──────────────────────────────────────
+
+
+async def test_delete_profile_removes_it(test_client, settings_store):
+ settings = _base_settings()
+ settings.llm_profiles.save('p', LLM(model='openai/gpt-4o'))
+ await _seed(settings_store, settings)
+
+ response = test_client.delete('/api/v1/settings/profiles/p')
+
+ assert response.status_code == 200
+ stored = await settings_store.load()
+ assert not stored.llm_profiles.has('p')
+
+
+async def test_delete_profile_is_idempotent(test_client, settings_store):
+ await _seed(settings_store, _base_settings())
+
+ response = test_client.delete('/api/v1/settings/profiles/never-existed')
+
+ assert response.status_code == 200
+ assert response.json()['name'] == 'never-existed'
+
+
+# ── POST /profiles/{name}/activate ───────────────────────────────
+
+
+async def test_activate_profile_updates_agent_llm(test_client, settings_store):
+ settings = _base_settings()
+ settings.llm_profiles.save(
+ 'my-claude',
+ LLM(
+ model='anthropic/claude-opus-4',
+ api_key=SecretStr('sk-claude'),
+ ),
+ )
+ await _seed(settings_store, settings)
+
+ response = test_client.post('/api/v1/settings/profiles/my-claude/activate')
+
+ assert response.status_code == 200
+ body = response.json()
+ assert body['name'] == 'my-claude'
+ assert body['model'] == 'anthropic/claude-opus-4'
+
+ stored = await settings_store.load()
+ assert stored.agent_settings.llm.model == 'anthropic/claude-opus-4'
+ assert stored.llm_profiles.active == 'my-claude'
+
+
+def test_activate_profile_returns_404_when_unknown(test_client):
+ response = test_client.post('/api/v1/settings/profiles/ghost/activate')
+
+ assert response.status_code == 404
+ assert "'ghost'" in response.json()['detail']
+
+
+async def test_activate_profile_applies_base_url_fixup(test_client, settings_store):
+ """Activating a profile with no base_url should get the provider default."""
+ settings = _base_settings()
+ settings.llm_profiles.save(
+ 'oh-profile',
+ LLM(model='openhands/claude-sonnet-4-20250514'),
+ )
+ await _seed(settings_store, settings)
+
+ response = test_client.post('/api/v1/settings/profiles/oh-profile/activate')
+ assert response.status_code == 200
+
+ stored = await settings_store.load()
+ # Fixup inferred the proxy URL; profile itself remains unchanged.
+ assert stored.agent_settings.llm.base_url is not None
+
+
+# ── POST /profiles/{name}/rename ─────────────────────────────────
+
+
+async def test_rename_profile_renames_and_preserves_api_key(
+ test_client, settings_store
+):
+ settings = _base_settings()
+ settings.llm_profiles.save(
+ 'old',
+ LLM(model='openai/gpt-4o', api_key=SecretStr('sk-keep')),
+ )
+ await _seed(settings_store, settings)
+
+ response = test_client.post(
+ '/api/v1/settings/profiles/old/rename',
+ json={'new_name': 'new'},
+ )
+
+ assert response.status_code == 200
+ body = response.json()
+ assert body['name'] == 'new'
+
+ stored = await settings_store.load()
+ assert stored.llm_profiles.get('old') is None
+ renamed = stored.llm_profiles.get('new')
+ assert renamed is not None
+ assert renamed.api_key.get_secret_value() == 'sk-keep'
+
+
+async def test_rename_profile_preserves_active_flag(test_client, settings_store):
+ settings = _base_settings()
+ settings.llm_profiles.save('p', LLM(model='openai/gpt-4o'))
+ settings.llm_profiles.active = 'p'
+ await _seed(settings_store, settings)
+
+ response = test_client.post(
+ '/api/v1/settings/profiles/p/rename',
+ json={'new_name': 'q'},
+ )
+ assert response.status_code == 200
+
+ stored = await settings_store.load()
+ assert stored.llm_profiles.active == 'q'
+
+
+async def test_rename_profile_returns_404_when_unknown(test_client, settings_store):
+ await _seed(settings_store, _base_settings())
+
+ response = test_client.post(
+ '/api/v1/settings/profiles/ghost/rename',
+ json={'new_name': 'new'},
+ )
+
+ assert response.status_code == 404
+ assert "'ghost'" in response.json()['detail']
+
+
+async def test_rename_profile_returns_409_when_target_exists(
+ test_client, settings_store
+):
+ settings = _base_settings()
+ settings.llm_profiles.save('a', LLM(model='openai/gpt-4o'))
+ settings.llm_profiles.save('b', LLM(model='anthropic/claude-opus-4'))
+ await _seed(settings_store, settings)
+
+ response = test_client.post(
+ '/api/v1/settings/profiles/a/rename',
+ json={'new_name': 'b'},
+ )
+
+ assert response.status_code == 409
+ assert "'b'" in response.json()['detail']
+
+ # Both originals should be intact after the failed rename.
+ stored = await settings_store.load()
+ assert stored.llm_profiles.has('a')
+ assert stored.llm_profiles.has('b')
+
+
+async def test_rename_profile_to_same_name_is_noop(test_client, settings_store):
+ settings = _base_settings()
+ settings.llm_profiles.save('p', LLM(model='openai/gpt-4o'))
+ await _seed(settings_store, settings)
+
+ response = test_client.post(
+ '/api/v1/settings/profiles/p/rename',
+ json={'new_name': 'p'},
+ )
+
+ assert response.status_code == 200
+ stored = await settings_store.load()
+ assert stored.llm_profiles.has('p')
+
+
+async def test_rename_profile_rejects_invalid_new_name(test_client, settings_store):
+ settings = _base_settings()
+ settings.llm_profiles.save('p', LLM(model='openai/gpt-4o'))
+ await _seed(settings_store, settings)
+
+ response = test_client.post(
+ '/api/v1/settings/profiles/p/rename',
+ json={'new_name': 'has space'},
+ )
+
+ assert response.status_code == 422
+
+
+# ── Name validation ──────────────────────────────────────────────
+
+
+ 'bad_name',
+ [
+ 'a' * 65, # too long
+ 'with space', # disallowed char
+ 'with/slash', # slash splits the path β†’ endpoint not matched
+ 'weird$chars', # disallowed char
+ ],
+)
+def test_save_profile_rejects_invalid_name(test_client, bad_name):
+ response = test_client.post(
+ f'/api/v1/settings/profiles/{bad_name}',
+ json={'llm': {'model': 'openai/gpt-4o'}},
+ )
+ # Invalid chars/length β†’ 422 from Path validation; slash β†’ 404 routing miss.
+ assert response.status_code in (404, 422)
+
+
+# ── Profile count cap ────────────────────────────────────────────
+
+
+async def test_save_profile_returns_409_past_limit(test_client, settings_store):
+ settings = _base_settings()
+ for i in range(MAX_PROFILES_PER_USER):
+ settings.llm_profiles.save(f'p{i}', LLM(model='openai/gpt-4o'))
+ await _seed(settings_store, settings)
+
+ response = test_client.post(
+ '/api/v1/settings/profiles/one-too-many',
+ json={'llm': {'model': 'openai/gpt-4o'}},
+ )
+
+ assert response.status_code == 409
+ assert 'limit' in response.json()['detail'].lower()
+
+
+async def test_save_profile_at_limit_can_still_overwrite(test_client, settings_store):
+ settings = _base_settings()
+ for i in range(MAX_PROFILES_PER_USER):
+ settings.llm_profiles.save(f'p{i}', LLM(model='openai/gpt-4o'))
+ await _seed(settings_store, settings)
+
+ response = test_client.post(
+ '/api/v1/settings/profiles/p0',
+ json={'llm': {'model': 'anthropic/claude-opus-4'}},
+ )
+
+ assert response.status_code == 201
+ stored = await settings_store.load()
+ assert stored.llm_profiles.get('p0').model == 'anthropic/claude-opus-4'
+
+
+# ── Orphan active auto-heals ─────────────────────────────────────
+
+
+async def test_list_profiles_clears_orphan_active(test_client, settings_store):
+ """A persisted state with active pointing at a missing profile should
+ self-heal on the next load β€” ``active_profile`` is reported as None."""
+ settings = _base_settings()
+ settings.llm_profiles.save('real', LLM(model='openai/gpt-4o'))
+ # Bypass the invariant validator to persist a corrupt state.
+ object.__setattr__(settings.llm_profiles, 'active', 'ghost')
+ await _seed(settings_store, settings)
+
+ response = test_client.get('/api/v1/settings/profiles')
+
+ assert response.status_code == 200
+ assert response.json()['active_profile'] is None
+
+
+# ── Real-world scenarios ─────────────────────────────────────────
+#
+# Each test below maps to a specific production risk surfaced by the
+# ``.pr/probe_profiles.py`` exploration script. Single assertion-per-
+# behaviour; one test per risk.
+#
+# Scenario 1 β€” API key never leaks in any response
+# Scenario 2 β€” Direct LLM edits invalidate a previously-active profile
+# Scenario 3 β€” The generic settings POST cannot inject or mutate profiles
+# Scenario 4 β€” The profile-count cap frees a slot when a profile is deleted
+
+
+_SECRET = 'sk-PROBE-MUST-NOT-LEAK'
+
+
+async def test_api_key_never_leaks_across_response_paths(test_client, settings_store):
+ """Scenario 1 β€” API key never leaks in any response.
+
+ User saves a profile that carries an api_key, then exercises every
+ endpoint that might echo the stored LLM back: the save response
+ itself, ``GET /profiles/{name}``, the activate response, and the
+ big ``GET /api/v1/settings`` payload that embeds all profiles. One
+ regression in any serializer would leak the key in logs, UI, or
+ exported settings β€” this test catches that across the full surface.
+ """
+ await _seed(settings_store, _base_settings())
+
+ save = test_client.post(
+ '/api/v1/settings/profiles/leak-check',
+ json={'llm': {'model': 'openai/gpt-4o', 'api_key': _SECRET}},
+ )
+ assert save.status_code == 201 and _SECRET not in save.text
+ assert _SECRET not in test_client.get('/api/v1/settings/profiles/leak-check').text
+ assert (
+ _SECRET
+ not in test_client.post('/api/v1/settings/profiles/leak-check/activate').text
+ )
+ assert _SECRET not in test_client.get('/api/v1/settings').text
+
+
+async def test_journey_direct_llm_edit_clears_active(test_client, settings_store):
+ """Scenario 2 β€” direct LLM edits invalidate a previously-active profile.
+
+ User saves profile ``j``, activates it, then opens the main Settings
+ page and edits the model/api_key. The currently-running LLM now
+ differs from the saved profile, so the UI must stop showing ``j`` as
+ active. This end-to-end HTTP flow exercises the same reconciliation
+ the unit tests cover, but through the real ``POST /api/v1/settings``
+ path users actually hit.
+ """
+ await _seed(settings_store, _base_settings())
+ test_client.post(
+ '/api/v1/settings/profiles/j',
+ json={'llm': {'model': 'openai/gpt-4o'}},
+ )
+ test_client.post('/api/v1/settings/profiles/j/activate')
+ assert test_client.get('/api/v1/settings/profiles').json()['active_profile'] == 'j'
+
+ test_client.post(
+ '/api/v1/settings',
+ json={'agent_settings_diff': {'llm': {'model': 'anthropic/claude-opus-4'}}},
+ )
+
+ assert test_client.get('/api/v1/settings/profiles').json()['active_profile'] is None
+
+
+async def test_main_settings_endpoint_ignores_llm_profiles_payload(
+ test_client, settings_store
+):
+ """Scenario 3 β€” the generic settings POST cannot inject or mutate profiles.
+
+ A malicious or buggy client might stuff ``llm_profiles`` into a
+ ``POST /api/v1/settings`` body to bypass the dedicated profile
+ endpoints (which enforce name rules, the count cap, and the per-user
+ lock). The probe found this path used to crash with 500; the server
+ must now silently drop the key instead, keeping all profile state
+ untouched and returning 200.
+ """
+ await _seed(settings_store, _base_settings())
+
+ resp = test_client.post(
+ '/api/v1/settings',
+ json={
+ 'llm_profiles': {
+ 'profiles': {'ATTACKER': {'model': 'openai/gpt-4o'}},
+ 'active': 'ATTACKER',
+ },
+ },
+ )
+
+ assert resp.status_code == 200 # silently ignored, not crashed
+ listing = test_client.get('/api/v1/settings/profiles').json()
+ assert 'ATTACKER' not in {p['name'] for p in listing['profiles']}
+
+
+async def test_delete_active_profile_clears_active_and_allows_recovery(
+ test_client, settings_store
+):
+ """Scenario 5 β€” Delete the currently-active profile.
+
+ User activates profile ``A``, then deletes it (misclick or intentional).
+ ``GET /profiles`` must show ``active_profile: null`` afterwards, and
+ the user must be able to immediately save and activate a replacement
+ β€” i.e. the in-memory state is not wedged by removing the active entry.
+ """
+ await _seed(settings_store, _base_settings())
+ test_client.post(
+ '/api/v1/settings/profiles/A',
+ json={'llm': {'model': 'openai/gpt-4o'}},
+ )
+ test_client.post('/api/v1/settings/profiles/A/activate')
+
+ test_client.delete('/api/v1/settings/profiles/A')
+
+ assert test_client.get('/api/v1/settings/profiles').json()['active_profile'] is None
+
+ # Recovery: save + activate a replacement.
+ test_client.post(
+ '/api/v1/settings/profiles/B',
+ json={'llm': {'model': 'anthropic/claude-opus-4'}},
+ )
+ assert test_client.post('/api/v1/settings/profiles/B/activate').status_code == 200
+
+
+async def test_switching_between_profiles_updates_active_and_model(
+ test_client, settings_store
+):
+ """Scenario 6 β€” Switch from profile A to profile B.
+
+ Two-profile user activates ``A`` first, then ``B``. ``active_profile``
+ must flip and ``agent_settings.llm.model`` must follow β€” no stale
+ caching or residual state from the previous activation.
+ """
+ await _seed(settings_store, _base_settings())
+ test_client.post(
+ '/api/v1/settings/profiles/A',
+ json={'llm': {'model': 'openai/gpt-4o'}},
+ )
+ test_client.post(
+ '/api/v1/settings/profiles/B',
+ json={'llm': {'model': 'anthropic/claude-opus-4'}},
+ )
+
+ test_client.post('/api/v1/settings/profiles/A/activate')
+ s1 = test_client.get('/api/v1/settings').json()
+ assert s1['agent_settings']['llm']['model'] == 'openai/gpt-4o'
+ assert test_client.get('/api/v1/settings/profiles').json()['active_profile'] == 'A'
+
+ test_client.post('/api/v1/settings/profiles/B/activate')
+ s2 = test_client.get('/api/v1/settings').json()
+ assert s2['agent_settings']['llm']['model'] == 'anthropic/claude-opus-4'
+ assert test_client.get('/api/v1/settings/profiles').json()['active_profile'] == 'B'
+
+
+async def test_profiles_are_isolated_between_users(tmp_path_factory):
+ """Scenario 7 β€” One user's profiles don't appear in another user's response.
+
+ Alice saves a profile against her store; Bob lists profiles against
+ his store. Bob must see none of Alice's β€” this pins the absence of
+ router-level cross-user state leaks (e.g. module-level caches that
+ don't key on user_id, or settings stores that accidentally share
+ data).
+ """
+ store_a = FileSettingsStore(root_dir=tmp_path_factory.mktemp('alice'))
+ store_b = FileSettingsStore(root_dir=tmp_path_factory.mktemp('bob'))
+ await store_a.store(_base_settings())
+ await store_b.store(_base_settings())
+
+ with _client_for_user('alice', store_a) as ca:
+ assert (
+ ca.post(
+ '/api/v1/settings/profiles/alice-only',
+ json={'llm': {'model': 'openai/gpt-4o'}},
+ ).status_code
+ == 201
+ )
+
+ with _client_for_user('bob', store_b) as cb:
+ body = cb.get('/api/v1/settings/profiles').json()
+ assert 'alice-only' not in {p['name'] for p in body['profiles']}
+
+
+async def test_cap_frees_after_delete(test_client, settings_store):
+ """Scenario 4 β€” the profile-count cap frees a slot when a profile is deleted.
+
+ User already has ``MAX_PROFILES_PER_USER`` profiles and tries to
+ save another (409). They delete one profile via the UI, then retry
+ the save: it must now succeed. Without this, a user who hits the
+ cap once is stuck forever.
+ """
+ settings = _base_settings()
+ for i in range(MAX_PROFILES_PER_USER):
+ settings.llm_profiles.save(f'p{i}', LLM(model='openai/gpt-4o'))
+ await _seed(settings_store, settings)
+
+ assert (
+ test_client.post(
+ '/api/v1/settings/profiles/over',
+ json={'llm': {'model': 'openai/gpt-4o'}},
+ ).status_code
+ == 409
+ )
+
+ test_client.delete('/api/v1/settings/profiles/p0')
+
+ assert (
+ test_client.post(
+ '/api/v1/settings/profiles/over',
+ json={'llm': {'model': 'openai/gpt-4o'}},
+ ).status_code
+ == 201
+ )
+
+
+# ── Lost-update race ─────────────────────────────────────────────
+
+
+async def test_concurrent_writes_all_persist(tmp_path: Path):
+ """Drive the handler under a single event loop with N truly concurrent
+ coroutines. Each handler loads β†’ mutates β†’ stores under the per-user
+ lock; all N profiles must land without any getting clobbered.
+
+ Bypasses ``TestClient`` (which spawns its own loop per request and makes
+ the module-level ``asyncio.Lock`` unreachable across calls)."""
+ import asyncio
+
+ from openhands.app_server.settings.settings_router import (
+ SaveProfileRequest,
+ save_profile,
+ )
+
+ store = FileSettingsStore(root_dir=tmp_path)
+ await store.store(_base_settings())
+
+ async def _save_one(i: int) -> None:
+ await save_profile(
+ name=f'p{i}',
+ request=SaveProfileRequest.model_validate(
+ {'llm': {'model': 'openai/gpt-4o'}}
+ ),
+ user_id='same-user',
+ settings_store=store,
+ )
+
+ await asyncio.gather(*(_save_one(i) for i in range(10)))
+
+ stored = await store.load()
+ assert {p['name'] for p in stored.llm_profiles.summaries()} == {
+ f'p{i}' for i in range(10)
+ }
diff --git a/tests/unit/storage/data_models/test_llm_profiles.py b/tests/unit/storage/data_models/test_llm_profiles.py
new file mode 100644
index 0000000000..53393b3b5d
--- /dev/null
+++ b/tests/unit/storage/data_models/test_llm_profiles.py
@@ -0,0 +1,330 @@
+"""Unit tests for :class:`LLMProfiles` (pure profile operations).
+
+Settings-integration tests (``switch_to_profile`` + serializer round-trip
+through ``Settings``) live in ``test_settings.py``.
+"""
+
+import pytest
+from pydantic import SecretStr, ValidationError
+
+from openhands.sdk.llm import LLM
+from openhands.storage.data_models.llm_profiles import (
+ MAX_PROFILES_PER_USER,
+ LLMProfiles,
+ ProfileAlreadyExistsError,
+ ProfileLimitExceededError,
+ ProfileNotFoundError,
+ StrictLLM,
+)
+
+
+def _make_llm(model: str = 'openai/gpt-4o', api_key: str | None = None) -> LLM:
+ return LLM(
+ model=model,
+ api_key=SecretStr(api_key) if api_key is not None else None,
+ )
+
+
+# ── Queries ───────────────────────────────────────────────────────
+
+
+def test_has_reflects_presence():
+ profiles = LLMProfiles()
+ assert profiles.has('x') is False
+ profiles.save('x', _make_llm())
+ assert profiles.has('x') is True
+
+
+def test_require_returns_llm_for_present():
+ profiles = LLMProfiles()
+ profiles.save('x', _make_llm(model='anthropic/claude-opus-4'))
+
+ llm = profiles.require('x')
+
+ assert isinstance(llm, LLM)
+ assert llm.model == 'anthropic/claude-opus-4'
+
+
+def test_require_raises_profile_not_found_with_name():
+ profiles = LLMProfiles()
+
+ with pytest.raises(ProfileNotFoundError) as exc_info:
+ profiles.require('missing')
+
+ assert exc_info.value.name == 'missing'
+ assert "'missing'" in str(exc_info.value)
+
+
+def test_summaries_returns_name_model_base_url_and_api_key_set():
+ profiles = LLMProfiles()
+ profiles.save('p1', _make_llm(model='openai/gpt-4o', api_key='sk-1'))
+ profiles.save(
+ 'p2',
+ LLM(model='anthropic/claude-opus-4', base_url='https://example.com'),
+ )
+
+ summaries = {s['name']: s for s in profiles.summaries()}
+
+ assert summaries['p1'] == {
+ 'name': 'p1',
+ 'model': 'openai/gpt-4o',
+ 'base_url': None,
+ 'api_key_set': True,
+ }
+ assert summaries['p2'] == {
+ 'name': 'p2',
+ 'model': 'anthropic/claude-opus-4',
+ 'base_url': 'https://example.com',
+ 'api_key_set': False,
+ }
+
+
+def test_summaries_empty_by_default():
+ assert LLMProfiles().summaries() == []
+
+
+# ── Mutations ─────────────────────────────────────────────────────
+
+
+def test_save_overwrites_existing_entry():
+ profiles = LLMProfiles()
+ profiles.save('p', _make_llm(model='a'))
+ profiles.save('p', _make_llm(model='b'))
+
+ assert profiles.get('p').model == 'b'
+ assert len(profiles.profiles) == 1
+
+
+def test_save_api_key_handling():
+ """Default keeps the api_key; ``include_secrets=False`` clears it."""
+ profiles = LLMProfiles()
+ profiles.save('keep', _make_llm(api_key='sk-abc'))
+ profiles.save('drop', _make_llm(api_key='sk-xyz'), include_secrets=False)
+
+ assert profiles.get('keep').api_key.get_secret_value() == 'sk-abc'
+ assert profiles.get('drop').api_key is None
+
+
+def test_save_stores_a_copy_not_the_caller_reference():
+ """Profiles must own their LLM config so caller-side mutations can't leak."""
+ profiles = LLMProfiles()
+ original = _make_llm(model='openai/gpt-4o', api_key='sk-abc')
+
+ profiles.save('p', original)
+
+ assert profiles.get('p') is not original
+
+
+def test_delete_returns_true_then_false():
+ profiles = LLMProfiles()
+ profiles.save('p', _make_llm())
+
+ assert profiles.delete('p') is True
+ assert profiles.get('p') is None
+ assert profiles.delete('p') is False
+
+
+def test_delete_clears_active_when_active_removed():
+ profiles = LLMProfiles()
+ profiles.save('p', _make_llm())
+ profiles.active = 'p'
+
+ profiles.delete('p')
+
+ assert profiles.active is None
+
+
+def test_delete_leaves_active_alone_when_other_removed():
+ profiles = LLMProfiles()
+ profiles.save('p1', _make_llm())
+ profiles.save('p2', _make_llm())
+ profiles.active = 'p1'
+
+ profiles.delete('p2')
+
+ assert profiles.active == 'p1'
+
+
+# ── Rename ────────────────────────────────────────────────────────
+
+
+def test_rename_preserves_llm_config():
+ profiles = LLMProfiles()
+ profiles.save('old', _make_llm(model='openai/gpt-4o', api_key='secret'))
+
+ profiles.rename('old', 'new')
+
+ assert profiles.get('old') is None
+ renamed = profiles.get('new')
+ assert renamed is not None
+ assert renamed.model == 'openai/gpt-4o'
+ assert renamed.api_key.get_secret_value() == 'secret'
+
+
+def test_rename_preserves_active_flag_when_renamed_was_active():
+ profiles = LLMProfiles()
+ profiles.save('p', _make_llm())
+ profiles.active = 'p'
+
+ profiles.rename('p', 'q')
+
+ assert profiles.active == 'q'
+
+
+def test_rename_leaves_active_alone_when_renaming_other():
+ profiles = LLMProfiles()
+ profiles.save('p1', _make_llm())
+ profiles.save('p2', _make_llm())
+ profiles.active = 'p1'
+
+ profiles.rename('p2', 'p2-renamed')
+
+ assert profiles.active == 'p1'
+
+
+def test_rename_to_same_name_is_noop():
+ profiles = LLMProfiles()
+ profiles.save('p', _make_llm())
+ profiles.active = 'p'
+
+ profiles.rename('p', 'p')
+
+ assert profiles.has('p')
+ assert profiles.active == 'p'
+
+
+def test_rename_unknown_raises_profile_not_found():
+ profiles = LLMProfiles()
+ with pytest.raises(ProfileNotFoundError, match='ghost'):
+ profiles.rename('ghost', 'new')
+
+
+def test_rename_to_existing_name_raises():
+ profiles = LLMProfiles()
+ profiles.save('a', _make_llm())
+ profiles.save('b', _make_llm())
+
+ with pytest.raises(ProfileAlreadyExistsError, match='b'):
+ profiles.rename('a', 'b')
+
+ # Original entries untouched.
+ assert profiles.has('a')
+ assert profiles.has('b')
+
+
+def test_rename_preserves_insertion_order():
+ profiles = LLMProfiles()
+ profiles.save('a', _make_llm())
+ profiles.save('b', _make_llm())
+ profiles.save('c', _make_llm())
+
+ profiles.rename('b', 'B')
+
+ assert list(profiles.profiles.keys()) == ['a', 'B', 'c']
+
+
+# ── Serialization ─────────────────────────────────────────────────
+
+
+def test_masking_and_roundtrip():
+ """Masked by default, exposed with context, reconstructible via model_validate."""
+ profiles = LLMProfiles()
+ profiles.save('p', _make_llm(api_key='secret'))
+ profiles.active = 'p'
+
+ assert profiles.model_dump(mode='json')['profiles']['p']['api_key'] != 'secret'
+ exposed = profiles.model_dump(mode='json', context={'expose_secrets': True})
+ assert exposed['profiles']['p']['api_key'] == 'secret'
+
+ rehydrated = LLMProfiles.model_validate(exposed)
+ assert rehydrated.active == 'p'
+ assert rehydrated.get('p').api_key.get_secret_value() == 'secret'
+
+
+# ── Invariants ────────────────────────────────────────────────────
+
+
+def test_active_stays_in_profiles_at_all_entry_points():
+ """``active`` must point at an existing profile β€” enforced both at
+ validate time (loading corrupted state) and at assignment time."""
+ # Validate-time: orphan active in persisted data is auto-cleared.
+ loaded = LLMProfiles.model_validate(
+ {'profiles': {'a': {'model': 'openai/gpt-4o'}}, 'active': 'ghost'}
+ )
+ assert loaded.active is None
+
+ # Assignment-time: setting to an unknown name clears; known keeps.
+ profiles = LLMProfiles()
+ profiles.save('a', _make_llm())
+ profiles.active = 'ghost'
+ assert profiles.active is None
+ profiles.active = 'a'
+ assert profiles.active == 'a'
+
+
+def test_orphan_active_heals_on_roundtrip():
+ """Disaster-recovery path: if something bypasses the invariant (rogue
+ DB write, manual file edit, deserialising old data), the next
+ validate cycle must drop the orphan rather than keep a dangling pointer.
+ """
+ profiles = LLMProfiles()
+ profiles.save('real', _make_llm())
+ object.__setattr__(profiles, 'active', 'ghost') # bypass validator
+
+ data = profiles.model_dump(mode='json')
+ rehydrated = LLMProfiles.model_validate(data)
+
+ assert rehydrated.active is None
+ assert rehydrated.has('real')
+
+
+# ── Per-profile best-effort load ──────────────────────────────────
+
+
+def test_invalid_profile_entry_is_skipped_not_fatal():
+ """A single bad profile must not prevent the rest from loading."""
+ data = {
+ 'profiles': {
+ 'ok': {'model': 'openai/gpt-4o'},
+ 'bad': {}, # missing required 'model' β†’ LLM validation fails
+ },
+ }
+
+ profiles = LLMProfiles.model_validate(data)
+
+ assert list(profiles.profiles) == ['ok']
+
+
+# ── Count cap ─────────────────────────────────────────────────────
+
+
+def test_save_fails_past_limit():
+ profiles = LLMProfiles()
+ for i in range(MAX_PROFILES_PER_USER):
+ profiles.save(f'p{i}', _make_llm())
+
+ with pytest.raises(ProfileLimitExceededError) as exc_info:
+ profiles.save('one-too-many', _make_llm())
+
+ assert exc_info.value.limit == MAX_PROFILES_PER_USER
+
+
+def test_save_at_limit_can_overwrite_existing():
+ profiles = LLMProfiles()
+ for i in range(MAX_PROFILES_PER_USER):
+ profiles.save(f'p{i}', _make_llm(model='openai/gpt-4o'))
+
+ # Overwriting an existing slot must succeed even at the cap.
+ profiles.save('p0', _make_llm(model='anthropic/claude-opus-4'))
+
+ assert profiles.get('p0').model == 'anthropic/claude-opus-4'
+
+
+# ── StrictLLM ─────────────────────────────────────────────────────
+
+
+def test_strict_llm_rejects_unknown_fields():
+ with pytest.raises(ValidationError):
+ StrictLLM.model_validate(
+ {'model': 'openai/gpt-4o', 'totally_made_up_field': 'x'}
+ )
diff --git a/tests/unit/storage/data_models/test_settings.py b/tests/unit/storage/data_models/test_settings.py
index a2665718d3..dbccb29795 100644
--- a/tests/unit/storage/data_models/test_settings.py
+++ b/tests/unit/storage/data_models/test_settings.py
@@ -1,3 +1,4 @@
+import importlib
import warnings
from unittest.mock import patch
@@ -5,6 +6,7 @@ import pytest
from fastmcp.mcp_config import MCPConfig
from pydantic import SecretStr
+import openhands.app_server.settings.settings_models as settings_module
from openhands.app_server.settings.settings_models import Settings
from openhands.app_server.settings.settings_router import LITE_LLM_API_URL
from openhands.core.config.llm_config import LLMConfig
@@ -18,6 +20,7 @@ from openhands.sdk.settings import (
ConversationSettings,
)
from openhands.sdk.settings.model import CondenserSettings, VerificationSettings
+from openhands.storage.data_models.llm_profiles import ProfileNotFoundError
def test_settings_from_config():
@@ -304,6 +307,138 @@ def test_settings_update_batch():
assert settings.conversation_settings.max_iterations == 200
+# ── LLM profiles: Settings-integration tests ────────────────────────
+# Pure LLMProfiles behaviour lives in test_llm_profiles.py.
+
+
+def test_switch_to_profile_updates_agent_settings_llm():
+ settings = Settings()
+ settings.llm_profiles.save('my-profile', LLM(model='openai/gpt-4o'))
+
+ settings.switch_to_profile('my-profile')
+
+ assert settings.agent_settings.llm.model == 'openai/gpt-4o'
+ assert settings.llm_profiles.active == 'my-profile'
+
+
+def test_switch_to_nonexistent_profile_raises():
+ settings = Settings()
+
+ with pytest.raises(ProfileNotFoundError) as exc_info:
+ settings.switch_to_profile('nonexistent')
+
+ assert exc_info.value.name == 'nonexistent'
+ assert settings.llm_profiles.active is None
+
+
+def test_llm_profiles_masking_and_roundtrip():
+ """Masked by default, exposed with context, and reconstructible via ``model_validate``."""
+ settings = Settings()
+ settings.llm_profiles.save(
+ 'p', LLM(model='openai/gpt-4o', api_key=SecretStr('secret'))
+ )
+
+ masked = settings.model_dump(mode='json')
+ exposed = settings.model_dump(mode='json', context={'expose_secrets': True})
+ assert masked['llm_profiles']['profiles']['p']['api_key'] != 'secret'
+ assert exposed['llm_profiles']['profiles']['p']['api_key'] == 'secret'
+
+ rehydrated = Settings.model_validate(exposed)
+ assert rehydrated.llm_profiles.get('p').api_key.get_secret_value() == 'secret'
+
+
+def test_switch_to_profile_preserves_other_agent_settings():
+ """Switching the LLM must not wipe condenser/verification/mcp_config.
+
+ Real user: has condenser+verification configured, switches LLM profile β€”
+ expects everything else to stay. A bare-field reassign in
+ ``switch_to_profile`` would silently drop those sibling configs.
+ """
+ settings = Settings(
+ agent_settings=AgentSettings(
+ llm=LLM(model='openai/gpt-4o'),
+ condenser=CondenserSettings(enabled=True, max_size=321),
+ verification=VerificationSettings(
+ critic_enabled=True, critic_mode='all_actions'
+ ),
+ mcp_config=MCPConfig(
+ mcpServers={
+ 's': {
+ 'transport': 'http',
+ 'url': 'https://example.com/mcp',
+ }
+ }
+ ),
+ ),
+ )
+ settings.llm_profiles.save('p', LLM(model='anthropic/claude-opus-4'))
+
+ settings.switch_to_profile('p')
+
+ assert settings.agent_settings.llm.model == 'anthropic/claude-opus-4'
+ assert settings.agent_settings.condenser.max_size == 321
+ assert settings.agent_settings.verification.critic_mode == 'all_actions'
+ assert settings.agent_settings.mcp_config is not None
+ assert 's' in settings.agent_settings.mcp_config.mcpServers
+
+
+def test_update_ignores_llm_profiles_payload():
+ """``Settings.update`` refuses to mutate ``llm_profiles``; profile changes
+ must go through the dedicated endpoints (which enforce name rules, the
+ count cap, and the per-user lock)."""
+ settings = Settings()
+
+ settings.update(
+ {
+ 'llm_profiles': {
+ 'profiles': {'X': {'model': 'openai/gpt-4o'}},
+ 'active': 'X',
+ }
+ }
+ )
+
+ assert settings.llm_profiles.profiles == {}
+ assert settings.llm_profiles.active is None
+
+
+def test_update_clears_active_when_llm_diverges():
+ """Editing agent_settings.llm via ``update`` must drop a now-stale active profile."""
+ settings = Settings(
+ agent_settings=AgentSettings(
+ llm=LLM(model='openai/gpt-4o', api_key=SecretStr('sk-a'))
+ )
+ )
+ settings.llm_profiles.save(
+ 'p', LLM(model='openai/gpt-4o', api_key=SecretStr('sk-a'))
+ )
+ settings.switch_to_profile('p')
+ assert settings.llm_profiles.active == 'p'
+
+ settings.update(
+ {'agent_settings_diff': {'llm': {'model': 'anthropic/claude-opus-4'}}}
+ )
+
+ assert settings.llm_profiles.active is None
+
+
+def test_update_keeps_active_when_llm_unchanged():
+ """A no-op LLM update must not spuriously clear ``active``."""
+ settings = Settings(
+ agent_settings=AgentSettings(
+ llm=LLM(model='openai/gpt-4o', api_key=SecretStr('sk-a'))
+ )
+ )
+ settings.llm_profiles.save(
+ 'p', LLM(model='openai/gpt-4o', api_key=SecretStr('sk-a'))
+ )
+ settings.switch_to_profile('p')
+
+ # Update an unrelated field.
+ settings.update({'language': 'fr'})
+
+ assert settings.llm_profiles.active == 'p'
+
+
def test_settings_update_batch_accepts_diff_keys():
settings = Settings()
settings.update(
@@ -335,12 +470,7 @@ def test_settings_no_pydantic_frozen_field_warning():
"""Test that Settings model does not trigger Pydantic UnsupportedFieldAttributeWarning."""
with warnings.catch_warnings(record=True) as w:
warnings.simplefilter('always')
-
- import importlib
-
- import openhands.app_server.settings.settings_models
-
- importlib.reload(openhands.app_server.settings.settings_models)
+ importlib.reload(settings_module)
frozen_warnings = [
warning for warning in w if 'frozen' in str(warning.message).lower()