Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat: Add org-level LLM profiles for SaaS users (#14406)

John-Mason P. Shackelford0a6cf00a4dd2
diff --git a/enterprise/migrations/versions/116_add_llm_profiles_to_org.py b/enterprise/migrations/versions/116_add_llm_profiles_to_org.py
new file mode 100644
index 0000000000..c11f381d0f
--- /dev/null
+++ b/enterprise/migrations/versions/116_add_llm_profiles_to_org.py
@@ -0,0 +1,36 @@
+"""Add llm_profiles column to org table.
+
+LLM profiles are stored at the organization level to support both personal
+workspaces (where the owner manages their own profiles) and team organizations
+(where admins manage profiles that members can activate).
+
+The column uses EncryptedJSON (stored as String) because profiles can contain
+per-profile API keys that must be encrypted at rest.
+
+Data migration: no backfill. Existing orgs read back with ``llm_profiles =
+NULL`` and ``_load_profiles`` treats that as an empty ``LLMProfiles``. The
+first save through the ``/api/organizations/{org_id}/profiles`` endpoints
+populates the column lazily, so no downtime or follow-up script is required.
+
+Revision ID: 116
+Revises: 115
+Create Date: 2025-05-13
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = '116'
+down_revision: Union[str, None] = '115'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+ op.add_column('org', sa.Column('llm_profiles', sa.String(), nullable=True))
+
+
+def downgrade() -> None:
+ op.drop_column('org', 'llm_profiles')
diff --git a/enterprise/saas_server.py b/enterprise/saas_server.py
index 385f83827d..c6af566953 100644
--- a/enterprise/saas_server.py
+++ b/enterprise/saas_server.py
@@ -45,6 +45,7 @@ from server.routes.org_invitations import ( # noqa: E402
from server.routes.org_invitations import ( # noqa: E402
invitation_router,
)
+from server.routes.org_profiles import router as org_profiles_router # noqa: E402
from server.routes.orgs import org_router # noqa: E402
from server.routes.readiness import readiness_router # noqa: E402
from server.routes.service import service_router # noqa: E402
@@ -131,6 +132,9 @@ if BITBUCKET_APP_CLIENT_ID:
base_app.include_router(api_keys_router) # Add routes for API key management
base_app.include_router(service_router) # Add routes for internal service API
base_app.include_router(org_router) # Add routes for organization management
+base_app.include_router(
+ org_profiles_router, prefix='/api/organizations'
+) # Add routes for org LLM profiles
base_app.include_router(
verified_models_router
) # Add routes for verified models management
diff --git a/enterprise/server/routes/org_profiles.py b/enterprise/server/routes/org_profiles.py
new file mode 100644
index 0000000000..90fc58bc60
--- /dev/null
+++ b/enterprise/server/routes/org_profiles.py
@@ -0,0 +1,367 @@
+"""Organization LLM profiles router.
+
+Provides CRUD operations for org-level LLM profiles. Profiles are stored on
+the organization and can be activated by members.
+
+Permission model:
+- CRUD (create, update, delete, rename): Requires EDIT_ORG_SETTINGS (owner/admin)
+- Activate: Requires EDIT_ORG_SETTINGS β€” the handler also writes the org-wide
+ ``profiles.active`` marker, so the permission must match the bigger of the
+ two side effects rather than the per-member one.
+"""
+
+import contextlib
+from typing import Any, AsyncIterator
+from uuid import UUID
+
+from fastapi import APIRouter, Body, Depends, HTTPException, Path, status
+from pydantic import BaseModel, Field, ValidationError
+from server.constants import LITE_LLM_API_URL
+from server.routes.org_models import (
+ OrgNotFoundError,
+ _validate_persisted_agent_settings,
+)
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from storage.database import a_session_maker
+from storage.org import Org
+from storage.org_member import OrgMember
+from storage.org_service import OrgService
+
+from openhands.app_server.settings.llm_profiles import (
+ LLMProfiles,
+ ProfileAlreadyExistsError,
+ ProfileLimitExceededError,
+ ProfileNotFoundError,
+ StrictLLM,
+)
+from openhands.app_server.utils.llm import MASKED_API_KEY, is_openhands_model
+from openhands.app_server.utils.logger import openhands_logger as logger
+
+from ..auth.authorization import Permission, require_permission
+
+router = APIRouter(tags=['Organization Profiles'])
+
+
+# ── Request/Response Models ────────────────────────────────────────────────
+
+
+class ProfileInfo(BaseModel):
+ """Summary info for a profile (no secrets)."""
+
+ name: str
+ model: str | None
+ base_url: str | None
+ api_key_set: bool
+
+
+class ProfileListResponse(BaseModel):
+ """Response for listing profiles."""
+
+ profiles: list[ProfileInfo]
+ active_profile: str | None
+
+
+class ProfileDetailResponse(BaseModel):
+ """Response for getting a single profile's details."""
+
+ name: str
+ llm: dict[str, Any]
+
+
+class ProfileMutationResponse(BaseModel):
+ """Response for profile mutations (save, delete, rename)."""
+
+ name: str
+ message: str
+
+
+class ActivateProfileResponse(BaseModel):
+ """Response for activating a profile."""
+
+ name: str
+ message: str
+ llm: dict[str, Any]
+
+
+class SaveProfileRequest(BaseModel):
+ """Request body for saving a profile."""
+
+ include_secrets: bool = True
+ llm: StrictLLM | None = None
+
+
+class RenameProfileRequest(BaseModel):
+ """Request body for renaming a profile."""
+
+ new_name: str = Field(..., min_length=1, max_length=100)
+
+
+# ── Helper Functions ────────────────────────────────────────────────────────
+
+
+def _load_profiles(org: Org) -> LLMProfiles:
+ """Load LLMProfiles from org row, defaulting to empty if not set."""
+ if org.llm_profiles is None:
+ return LLMProfiles()
+ try:
+ return LLMProfiles.model_validate(org.llm_profiles)
+ except ValidationError as exc:
+ # Schema drift / partially-invalid stored profiles: degrade to empty
+ # rather than 500-ing. Other exceptions (DB decrypt failures, etc.)
+ # bubble up so they're surfaced instead of silently masked.
+ logger.warning('Failed to load org profiles for %s: %s', org.id, exc)
+ return LLMProfiles()
+
+
+async def _get_org(org_id: UUID, user_id: str) -> Org:
+ """Get org, raising 404 if not found."""
+ try:
+ return await OrgService.get_org_by_id(org_id=org_id, user_id=user_id)
+ except OrgNotFoundError as e:
+ raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(e))
+
+
+async def _org_profiles_transaction(
+ org_id: UUID, user_id: str
+) -> AsyncIterator[tuple[AsyncSession, Org, LLMProfiles]]:
+ """Yield ``(session, org, profiles)`` for a single locked mutation.
+
+ Wraps read β†’ mutate β†’ write in one session with ``SELECT ... FOR UPDATE``
+ so concurrent profile mutations serialize at the database level instead
+ of racing on the ``llm_profiles`` column (last-writer-wins would silently
+ drop the loser's changes). The caller mutates ``profiles`` in place; on
+ normal exit the helper serializes it back onto the org row and commits.
+ Exceptions skip the commit, so partial state never lands β€” useful for
+ multi-write endpoints like activate that also update ``OrgMember``.
+ """
+ # Membership/access check (perms are enforced by the route's Depends; this
+ # is the same org-membership check the read endpoints do via _get_org).
+ await _get_org(org_id, user_id)
+
+ async with a_session_maker() as session:
+ result = await session.execute(
+ select(Org).filter(Org.id == org_id).with_for_update()
+ )
+ org = result.scalars().first()
+ if org is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f'Organization {org_id} not found',
+ )
+ profiles = _load_profiles(org)
+ yield session, org, profiles
+ org.llm_profiles = profiles.model_dump(
+ mode='json', context={'expose_secrets': True}
+ )
+ await session.commit()
+
+
+# ── Endpoints ────────────────────────────────────────────────────────────────
+
+
[email protected]('/{org_id}/profiles', response_model=ProfileListResponse)
+async def list_profiles(
+ org_id: UUID,
+ user_id: str = Depends(require_permission(Permission.VIEW_ORG_SETTINGS)),
+) -> ProfileListResponse:
+ """List all LLM profiles for this organization."""
+ org = await _get_org(org_id, user_id)
+ profiles = _load_profiles(org)
+ return ProfileListResponse(
+ profiles=[
+ ProfileInfo(**p)
+ for p in profiles.summaries(managed_proxy_url=LITE_LLM_API_URL)
+ ],
+ active_profile=profiles.active,
+ )
+
+
[email protected]('/{org_id}/profiles/{name}', response_model=ProfileDetailResponse)
+async def get_profile(
+ org_id: UUID,
+ name: str = Path(..., min_length=1),
+ user_id: str = Depends(require_permission(Permission.VIEW_ORG_SETTINGS)),
+) -> ProfileDetailResponse:
+ """Get details of a specific profile."""
+ org = await _get_org(org_id, user_id)
+ profiles = _load_profiles(org)
+ llm = profiles.get(name)
+ if llm is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Profile '{name}' not found",
+ )
+ return ProfileDetailResponse(
+ name=name,
+ llm=llm.model_dump(mode='json', context={'expose_secrets': False}),
+ )
+
+
[email protected]('/{org_id}/profiles/{name}', response_model=ProfileMutationResponse)
+async def save_profile(
+ org_id: UUID,
+ name: str = Path(..., min_length=1, max_length=100),
+ request: SaveProfileRequest = SaveProfileRequest(),
+ user_id: str = Depends(require_permission(Permission.EDIT_ORG_SETTINGS)),
+) -> ProfileMutationResponse:
+ """Create or update an LLM profile.
+
+ If ``llm`` is omitted, saves a copy of the current org LLM defaults.
+ """
+ async with _org_profiles_transaction(org_id, user_id) as (_session, org, profiles):
+ try:
+ if request.llm is not None:
+ profiles.save(
+ name, request.llm, include_secrets=request.include_secrets
+ )
+ else:
+ # Snapshot current org LLM settings. Route through the persisted
+ # loader so legacy/canonical ``agent_kind`` discriminator values
+ # ('llm' vs 'openhands') both validate.
+ agent_settings = _validate_persisted_agent_settings(org.agent_settings)
+ profiles.save(
+ name, agent_settings.llm, include_secrets=request.include_secrets
+ )
+ except ProfileLimitExceededError as exc:
+ raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(exc))
+
+ return ProfileMutationResponse(name=name, message=f"Profile '{name}' saved")
+
+
[email protected]('/{org_id}/profiles/{name}', response_model=ProfileMutationResponse)
+async def delete_profile(
+ org_id: UUID,
+ name: str = Path(..., min_length=1),
+ user_id: str = Depends(require_permission(Permission.EDIT_ORG_SETTINGS)),
+) -> ProfileMutationResponse:
+ """Delete an LLM profile."""
+ async with _org_profiles_transaction(org_id, user_id) as (
+ _session,
+ _org,
+ profiles,
+ ):
+ if not profiles.delete(name):
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Profile '{name}' not found",
+ )
+
+ return ProfileMutationResponse(name=name, message=f"Profile '{name}' deleted")
+
+
+ '/{org_id}/profiles/{name}/activate', response_model=ActivateProfileResponse
+)
+async def activate_profile(
+ org_id: UUID,
+ name: str = Path(..., min_length=1),
+ user_id: str = Depends(require_permission(Permission.EDIT_ORG_SETTINGS)),
+) -> ActivateProfileResponse:
+ """Activate a profile for the current user.
+
+ Two side effects: updates the org-wide ``profiles.active`` marker and
+ writes the profile's LLM into the calling member's
+ ``agent_settings_diff``. Both writes share a single transaction so a
+ failure in the second can't leave the org marker advanced without the
+ member's settings catching up. Because the first effect is org-level
+ state, this requires ``EDIT_ORG_SETTINGS`` β€” matching the CRUD endpoints
+ rather than the read-only listing. For personal orgs the owner has the
+ permission natively; for team orgs this scopes "set org default profile"
+ to admins.
+ """
+ async with _org_profiles_transaction(org_id, user_id) as (
+ session,
+ _org,
+ profiles,
+ ):
+ llm = profiles.get(name)
+ if llm is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Profile '{name}' not found",
+ )
+ profiles.active = name
+
+ # Same session as the org write so both side-effects commit atomically.
+ # Cast ``user_id`` explicitly: Postgres' UUID type tolerates string
+ # coercion, but SQLAlchemy's generic Uuid binding (used under SQLite
+ # in tests) doesn't.
+ member_result = await session.execute(
+ select(OrgMember).filter(
+ OrgMember.org_id == org_id, OrgMember.user_id == UUID(user_id)
+ )
+ )
+ member = member_result.scalars().first()
+ if member is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail='Organization membership not found',
+ )
+ # Apply the profile to the calling member. The profile's raw api_key
+ # must never land in ``agent_settings_diff`` (a plain, unencrypted JSON
+ # column): mask it there and lift the real value into the encrypted
+ # ``_llm_api_key`` column, mirroring the main settings path
+ # (OrgUpdate._lift_and_mask_llm_api_key / SaasSettingsStore.store). The
+ # effective api_key is resolved from ``_llm_api_key`` /
+ # ``has_custom_llm_api_key`` at load time, not from the diff β€” so a
+ # profile's key only takes effect if written there.
+ llm_dump = llm.model_dump(mode='json', context={'expose_secrets': True})
+ profile_api_key = llm_dump.get('api_key')
+ if profile_api_key and profile_api_key != MASKED_API_KEY:
+ llm_dump['api_key'] = MASKED_API_KEY
+ # Classify managed vs. BYOR exactly as SaasSettingsStore.store() so
+ # billing attribution stays correct.
+ base_url = llm_dump.get('base_url')
+ normalized_base_url = base_url.rstrip('/') if base_url else None
+ normalized_managed_base_url = LITE_LLM_API_URL.rstrip('/')
+ uses_managed_llm_key = (
+ normalized_base_url == normalized_managed_base_url
+ or (
+ normalized_base_url is None
+ and is_openhands_model(llm_dump.get('model'))
+ )
+ )
+ member.llm_api_key = profile_api_key
+ member.has_custom_llm_api_key = not uses_managed_llm_key
+ else:
+ # No per-profile key: fall back to the org/managed default rather
+ # than leaving a stale custom key from a previous activation in play.
+ member.has_custom_llm_api_key = False
+
+ member_diff = dict(member.agent_settings_diff or {})
+ member_diff['llm'] = llm_dump
+ member.agent_settings_diff = member_diff
+
+ return ActivateProfileResponse(
+ name=name,
+ message=f"Profile '{name}' activated",
+ llm=llm.model_dump(mode='json', context={'expose_secrets': False}),
+ )
+
+
[email protected]('/{org_id}/profiles/{name}/rename', response_model=ProfileMutationResponse)
+async def rename_profile(
+ org_id: UUID,
+ name: str = Path(..., min_length=1),
+ request: RenameProfileRequest = Body(...),
+ user_id: str = Depends(require_permission(Permission.EDIT_ORG_SETTINGS)),
+) -> ProfileMutationResponse:
+ """Rename an LLM profile."""
+ async with _org_profiles_transaction(org_id, user_id) as (
+ _session,
+ _org,
+ profiles,
+ ):
+ try:
+ profiles.rename(name, request.new_name)
+ except ProfileNotFoundError as exc:
+ raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc))
+ except ProfileAlreadyExistsError as exc:
+ raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(exc))
+
+ return ProfileMutationResponse(
+ name=request.new_name,
+ message=f"Profile renamed from '{name}' to '{request.new_name}'",
+ )
diff --git a/enterprise/storage/org.py b/enterprise/storage/org.py
index 39a1fee992..075ef68eda 100644
--- a/enterprise/storage/org.py
+++ b/enterprise/storage/org.py
@@ -10,7 +10,7 @@ from server.constants import DEFAULT_BILLING_MARGIN
from sqlalchemy import JSON, String
from sqlalchemy.orm import Mapped, mapped_column, relationship
from storage.base import Base
-from storage.encrypt_utils import decrypt_value, encrypt_value
+from storage.encrypt_utils import EncryptedJSON, decrypt_value, encrypt_value
if TYPE_CHECKING:
from storage.api_key import ApiKey
@@ -66,6 +66,10 @@ class Org(Base):
conversation_expiration: Mapped[int | None] = mapped_column(nullable=True)
byor_export_enabled: Mapped[bool] = mapped_column(nullable=False, default=False)
sandbox_grouping_strategy: Mapped[str | None] = mapped_column(String, nullable=True)
+ # Encrypted column for LLM profiles (contains API keys)
+ llm_profiles: Mapped[dict[str, Any] | None] = mapped_column(
+ EncryptedJSON, nullable=True
+ )
# Relationships
org_members: Mapped[list['OrgMember']] = relationship(
diff --git a/enterprise/storage/saas_settings_store.py b/enterprise/storage/saas_settings_store.py
index 09ef76c5b3..91ca7141c5 100644
--- a/enterprise/storage/saas_settings_store.py
+++ b/enterprise/storage/saas_settings_store.py
@@ -205,6 +205,15 @@ 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)
+ # Profiles in SaaS live on the org (managed via
+ # /api/organizations/{org_id}/profiles). Surface them through
+ # Settings.llm_profiles so the chat-layer endpoints
+ # (/api/v1/settings/profiles and /switch_profile) see them without
+ # needing a separate code path. Falls back to user.llm_profiles when
+ # the org has none β€” handles older personal accounts whose profiles
+ # never moved to the org column.
+ if org.llm_profiles:
+ kwargs['llm_profiles'] = org.llm_profiles
# 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:
diff --git a/enterprise/tests/unit/test_org_profiles.py b/enterprise/tests/unit/test_org_profiles.py
new file mode 100644
index 0000000000..8bdfa4a5a5
--- /dev/null
+++ b/enterprise/tests/unit/test_org_profiles.py
@@ -0,0 +1,504 @@
+"""Unit and integration tests for organization LLM profiles router."""
+
+import uuid
+from unittest.mock import MagicMock, patch
+
+import pytest
+from fastapi import HTTPException
+from sqlalchemy import select
+from storage.org import Org
+from storage.org_member import OrgMember
+from storage.role import Role
+from storage.user import User
+
+from openhands.app_server.settings.llm_profiles import (
+ MAX_PROFILES_PER_USER,
+ LLMProfiles,
+ StrictLLM,
+)
+from openhands.app_server.utils.llm import MASKED_API_KEY
+
+# Mock the database module before importing the router β€” matches the
+# test_saas_settings_store.py pattern so module-level imports don't try to
+# touch a real engine.
+with patch('storage.database.a_session_maker'):
+ from server.routes.org_profiles import (
+ ProfileListResponse,
+ ProfileMutationResponse,
+ RenameProfileRequest,
+ SaveProfileRequest,
+ _load_profiles,
+ activate_profile,
+ delete_profile,
+ get_profile,
+ list_profiles,
+ rename_profile,
+ save_profile,
+ )
+
+
+def sample_org():
+ """Create a sample org for testing."""
+ org = MagicMock(spec=Org)
+ org.id = uuid.uuid4()
+ org.llm_profiles = None
+ org.agent_settings = {'llm': {'model': 'gpt-4', 'api_key': 'test-key'}}
+ return org
+
+
+def org_with_profiles():
+ """Create an org with existing profiles."""
+ org = MagicMock(spec=Org)
+ org.id = uuid.uuid4()
+ org.llm_profiles = {
+ 'profiles': {
+ 'my-profile': {'model': 'claude-3', 'api_key': 'claude-key'},
+ 'backup': {'model': 'gpt-4o', 'api_key': 'openai-key'},
+ },
+ 'active': 'my-profile',
+ }
+ org.agent_settings = {'llm': {'model': 'gpt-4', 'api_key': 'test-key'}}
+ return org
+
+
+class TestLoadProfiles:
+ """Test the _load_profiles helper function."""
+
+ def test_load_profiles_empty(self, sample_org):
+ """Test loading profiles when org has none."""
+ profiles = _load_profiles(sample_org)
+ assert isinstance(profiles, LLMProfiles)
+ assert profiles.active is None
+ assert len(profiles.summaries()) == 0
+
+ def test_load_profiles_with_data(self, org_with_profiles):
+ """Test loading profiles when org has existing profiles."""
+ profiles = _load_profiles(org_with_profiles)
+ assert isinstance(profiles, LLMProfiles)
+ assert profiles.active == 'my-profile'
+ summaries = profiles.summaries()
+ assert len(summaries) == 2
+ names = [s['name'] for s in summaries]
+ assert 'my-profile' in names
+ assert 'backup' in names
+
+ def test_load_profiles_invalid_data(self, sample_org):
+ """Test loading profiles when org has invalid data."""
+ sample_org.llm_profiles = {'invalid': 'data'}
+ profiles = _load_profiles(sample_org)
+ # Should return empty profiles on parse error
+ assert isinstance(profiles, LLMProfiles)
+
+
+class TestProfileListResponse:
+ """Test ProfileListResponse model."""
+
+ def test_empty_list(self):
+ """Test empty profile list response."""
+ response = ProfileListResponse(profiles=[], active_profile=None)
+ assert response.profiles == []
+ assert response.active_profile is None
+
+ def test_with_profiles(self):
+ """Test profile list response with data."""
+ from server.routes.org_profiles import ProfileInfo
+
+ profiles = [
+ ProfileInfo(name='test', model='gpt-4', base_url=None, api_key_set=True),
+ ]
+ response = ProfileListResponse(profiles=profiles, active_profile='test')
+ assert len(response.profiles) == 1
+ assert response.active_profile == 'test'
+
+
+class TestProfileMutationResponse:
+ """Test ProfileMutationResponse model."""
+
+ def test_create_response(self):
+ """Test creating a mutation response."""
+ response = ProfileMutationResponse(
+ name='new-profile', message="Profile 'new-profile' saved"
+ )
+ assert response.name == 'new-profile'
+ assert 'saved' in response.message
+
+
+class TestSaveProfileRequest:
+ """Test SaveProfileRequest model."""
+
+ def test_default_values(self):
+ """Test default values for save request."""
+ request = SaveProfileRequest()
+ assert request.include_secrets is True
+ assert request.llm is None
+
+ def test_with_llm(self):
+ """Test save request with LLM config."""
+ request = SaveProfileRequest(
+ include_secrets=False, llm=StrictLLM(model='gpt-4')
+ )
+ assert request.include_secrets is False
+ assert request.llm is not None
+ assert request.llm.model == 'gpt-4'
+
+
+class TestRenameProfileRequest:
+ """Test RenameProfileRequest model."""
+
+ def test_valid_name(self):
+ """Test valid rename request."""
+ request = RenameProfileRequest(new_name='new-name')
+ assert request.new_name == 'new-name'
+
+ def test_name_validation(self):
+ """Test name length validation."""
+ # Should accept reasonable names
+ request = RenameProfileRequest(new_name='a' * 100)
+ assert len(request.new_name) == 100
+
+ # Should reject empty names (min_length=1)
+ with pytest.raises(ValueError):
+ RenameProfileRequest(new_name='')
+
+ # Should reject too-long names (max_length=100)
+ with pytest.raises(ValueError):
+ RenameProfileRequest(new_name='a' * 101)
+
+
+# ── Integration tests ──────────────────────────────────────────────────────
+#
+# Exercise the route handlers end-to-end against a real SQLite-backed Org +
+# OrgMember row. They verify the new ``SELECT FOR UPDATE`` transaction helper
+# round-trips correctly, the activate handler writes both the org marker and
+# the member diff atomically, and the exception-to-HTTP mapping for the
+# 404/409 paths.
+
+ORG_ID = uuid.UUID('5594c7b6-f959-4b81-92e9-b09c206f5081')
+ADMIN_USER_ID = uuid.UUID('5594c7b6-f959-4b81-92e9-b09c206f5082')
+
+
+def seeded_org(session_maker):
+ """Create a personal-org-shaped row with one admin member."""
+ with session_maker() as session:
+ session.add(Role(id=10, name='member', rank=3))
+ session.add(
+ Org(
+ id=ORG_ID,
+ name='profile-test-org',
+ org_version=1,
+ enable_proactive_conversation_starters=True,
+ )
+ )
+ session.add(
+ User(
+ id=ADMIN_USER_ID,
+ current_org_id=ORG_ID,
+ user_consents_to_analytics=True,
+ )
+ )
+ session.add(
+ OrgMember(
+ org_id=ORG_ID,
+ user_id=ADMIN_USER_ID,
+ role_id=10,
+ llm_api_key='initial-key',
+ agent_settings_diff={
+ 'llm': {'model': 'before-activate', 'base_url': None},
+ },
+ conversation_settings_diff={},
+ status='active',
+ )
+ )
+ session.commit()
+ return {'org_id': ORG_ID, 'admin_user_id': ADMIN_USER_ID}
+
+
+def patch_route_db(async_session_maker, seeded_org):
+ """Wire the router's db session + OrgService.get_org_by_id to the test
+ SQLite fixture so direct handler calls hit the real schema. ``get_org_by_id``
+ is patched (rather than seeding the full membership graph) because its
+ inner OrgMemberStore call opens sessions outside ``async_session_maker``.
+ """
+ org_id = seeded_org['org_id']
+
+ async def _fake_get_org(org_id, user_id): # noqa: ARG001
+ async with async_session_maker() as session:
+ result = await session.execute(select(Org).where(Org.id == org_id))
+ return result.scalars().first()
+
+ with (
+ patch(
+ 'server.routes.org_profiles.a_session_maker',
+ async_session_maker,
+ ),
+ patch(
+ 'server.routes.org_profiles.OrgService.get_org_by_id',
+ side_effect=_fake_get_org,
+ ),
+ ):
+ yield org_id
+
+
+async def _read_org(async_session_maker, org_id):
+ async with async_session_maker() as session:
+ result = await session.execute(select(Org).where(Org.id == org_id))
+ return result.scalars().first()
+
+
+async def _read_member(async_session_maker, org_id, user_id):
+ # ``user_id`` accepts either str or UUID β€” coerce so the SQLite test
+ # backend's strict Uuid binding doesn't error on str inputs.
+ user_uuid = user_id if isinstance(user_id, uuid.UUID) else uuid.UUID(user_id)
+ async with async_session_maker() as session:
+ result = await session.execute(
+ select(OrgMember).where(
+ OrgMember.org_id == org_id, OrgMember.user_id == user_uuid
+ )
+ )
+ return result.scalars().first()
+
+
+class TestProfileLifecycleIntegration:
+ """Round-trip CRUD against a real Org row."""
+
+ @pytest.mark.asyncio
+ async def test_save_then_list_persists_profile(
+ self, async_session_maker, patch_route_db
+ ):
+ org_id = patch_route_db
+
+ await save_profile(
+ org_id=org_id,
+ name='work',
+ request=SaveProfileRequest(
+ llm=StrictLLM(model='anthropic/claude-3-5-sonnet')
+ ),
+ user_id=str(ADMIN_USER_ID),
+ )
+
+ listing = await list_profiles(org_id=org_id, user_id=str(ADMIN_USER_ID))
+ assert [p.name for p in listing.profiles] == ['work']
+ assert listing.profiles[0].model == 'anthropic/claude-3-5-sonnet'
+ assert listing.active_profile is None
+
+ @pytest.mark.asyncio
+ async def test_get_profile_returns_details_without_secret(
+ self, async_session_maker, patch_route_db
+ ):
+ org_id = patch_route_db
+
+ await save_profile(
+ org_id=org_id,
+ name='work',
+ request=SaveProfileRequest(
+ llm=StrictLLM(
+ model='anthropic/claude-3-5-sonnet',
+ api_key='secret-value',
+ )
+ ),
+ user_id=str(ADMIN_USER_ID),
+ )
+
+ detail = await get_profile(
+ org_id=org_id, name='work', user_id=str(ADMIN_USER_ID)
+ )
+ assert detail.name == 'work'
+ assert detail.llm['model'] == 'anthropic/claude-3-5-sonnet'
+ # ``expose_secrets=False`` on the response masks the secret rather
+ # than dropping it (so the response shape is stable). Just confirm
+ # the raw value never leaks back.
+ assert detail.llm.get('api_key') != 'secret-value'
+
+ @pytest.mark.asyncio
+ async def test_delete_removes_profile_and_repeat_returns_404(
+ self, async_session_maker, patch_route_db
+ ):
+ org_id = patch_route_db
+
+ await save_profile(
+ org_id=org_id,
+ name='gone',
+ request=SaveProfileRequest(llm=StrictLLM(model='openai/gpt-4o')),
+ user_id=str(ADMIN_USER_ID),
+ )
+ await delete_profile(org_id=org_id, name='gone', user_id=str(ADMIN_USER_ID))
+
+ listing = await list_profiles(org_id=org_id, user_id=str(ADMIN_USER_ID))
+ assert listing.profiles == []
+
+ with pytest.raises(HTTPException) as exc:
+ await delete_profile(org_id=org_id, name='gone', user_id=str(ADMIN_USER_ID))
+ assert exc.value.status_code == 404
+
+
+class TestProfileErrorPaths:
+ """Exception-to-HTTP mapping for the mutating endpoints."""
+
+ @pytest.mark.asyncio
+ async def test_save_raises_409_at_profile_limit(
+ self, async_session_maker, patch_route_db
+ ):
+ org_id = patch_route_db
+ # Fill to the cap, then attempt a new name.
+ for i in range(MAX_PROFILES_PER_USER):
+ await save_profile(
+ org_id=org_id,
+ name=f'p{i}',
+ request=SaveProfileRequest(llm=StrictLLM(model=f'openai/m-{i}')),
+ user_id=str(ADMIN_USER_ID),
+ )
+
+ with pytest.raises(HTTPException) as exc:
+ await save_profile(
+ org_id=org_id,
+ name='overflow',
+ request=SaveProfileRequest(llm=StrictLLM(model='openai/m-x')),
+ user_id=str(ADMIN_USER_ID),
+ )
+ assert exc.value.status_code == 409
+
+ @pytest.mark.asyncio
+ async def test_rename_raises_409_on_name_collision(
+ self, async_session_maker, patch_route_db
+ ):
+ org_id = patch_route_db
+
+ for name in ('a', 'b'):
+ await save_profile(
+ org_id=org_id,
+ name=name,
+ request=SaveProfileRequest(llm=StrictLLM(model=f'openai/{name}')),
+ user_id=str(ADMIN_USER_ID),
+ )
+
+ with pytest.raises(HTTPException) as exc:
+ await rename_profile(
+ org_id=org_id,
+ name='a',
+ request=RenameProfileRequest(new_name='b'),
+ user_id=str(ADMIN_USER_ID),
+ )
+ assert exc.value.status_code == 409
+
+ @pytest.mark.asyncio
+ async def test_activate_raises_404_for_unknown_profile(
+ self, async_session_maker, patch_route_db
+ ):
+ org_id = patch_route_db
+
+ with pytest.raises(HTTPException) as exc:
+ await activate_profile(
+ org_id=org_id, name='missing', user_id=str(ADMIN_USER_ID)
+ )
+ assert exc.value.status_code == 404
+
+
+class TestActivateTransactionAtomicity:
+ """Activate must commit the org marker and the member diff together."""
+
+ @pytest.mark.asyncio
+ async def test_writes_org_active_and_member_diff_together(
+ self, async_session_maker, patch_route_db
+ ):
+ org_id = patch_route_db
+ await save_profile(
+ org_id=org_id,
+ name='work',
+ request=SaveProfileRequest(
+ llm=StrictLLM(
+ model='anthropic/claude-3-5-sonnet',
+ base_url='https://api.anthropic.com/v1',
+ api_key='activate-key',
+ )
+ ),
+ user_id=str(ADMIN_USER_ID),
+ )
+
+ await activate_profile(org_id=org_id, name='work', user_id=str(ADMIN_USER_ID))
+
+ org = await _read_org(async_session_maker, org_id)
+ assert org is not None
+ assert _load_profiles(org).active == 'work'
+
+ member = await _read_member(async_session_maker, org_id, ADMIN_USER_ID)
+ assert member is not None
+ assert (
+ member.agent_settings_diff['llm']['model'] == 'anthropic/claude-3-5-sonnet'
+ )
+
+ @pytest.mark.asyncio
+ async def test_member_lookup_failure_rolls_back_org_active(
+ self, async_session_maker, patch_route_db
+ ):
+ """If the member row vanishes between perm-check and the same-session
+ member read, the helper must roll back the org-side update so we
+ don't end up with the org marker advanced without the member diff
+ applied.
+ """
+ org_id = patch_route_db
+ await save_profile(
+ org_id=org_id,
+ name='work',
+ request=SaveProfileRequest(llm=StrictLLM(model='openai/gpt-4o')),
+ user_id=str(ADMIN_USER_ID),
+ )
+ # Sanity: no active profile yet.
+ org_before = await _read_org(async_session_maker, org_id)
+ assert _load_profiles(org_before).active is None
+
+ # Drop the member row so the in-transaction lookup raises 404.
+ async with async_session_maker() as session:
+ result = await session.execute(
+ select(OrgMember).where(OrgMember.org_id == org_id)
+ )
+ member = result.scalars().first()
+ await session.delete(member)
+ await session.commit()
+
+ with pytest.raises(HTTPException) as exc:
+ await activate_profile(
+ org_id=org_id, name='work', user_id=str(ADMIN_USER_ID)
+ )
+ assert exc.value.status_code == 404
+
+ org_after = await _read_org(async_session_maker, org_id)
+ # No commit happened β†’ org.active stays None.
+ assert _load_profiles(org_after).active is None
+
+ @pytest.mark.asyncio
+ async def test_activate_masks_key_in_diff_and_persists_real_key_encrypted(
+ self, async_session_maker, patch_route_db
+ ):
+ """A per-profile key must never be stored raw in the plain-JSON
+ ``agent_settings_diff`` column, and it must actually take effect: the
+ effective key resolves from the encrypted ``_llm_api_key`` column (via
+ ``has_custom_llm_api_key``), not from the diff.
+ """
+ org_id = patch_route_db
+ await save_profile(
+ org_id=org_id,
+ name='byor',
+ request=SaveProfileRequest(
+ llm=StrictLLM(
+ model='anthropic/claude-3-5-sonnet',
+ base_url='https://api.anthropic.com/v1',
+ api_key='byor-secret',
+ )
+ ),
+ user_id=str(ADMIN_USER_ID),
+ )
+
+ await activate_profile(org_id=org_id, name='byor', user_id=str(ADMIN_USER_ID))
+
+ member = await _read_member(async_session_maker, org_id, ADMIN_USER_ID)
+ assert member is not None
+ # The raw key never lands in the unencrypted diff column.
+ assert member.agent_settings_diff['llm']['api_key'] == MASKED_API_KEY
+ assert 'byor-secret' not in str(member.agent_settings_diff)
+ # A non-managed (BYOR) key takes effect via the encrypted member store.
+ assert member.has_custom_llm_api_key is True
+ assert member.llm_api_key.get_secret_value() == 'byor-secret'
diff --git a/frontend/__tests__/components/chat/model-messages.test.tsx b/frontend/__tests__/components/chat/model-messages.test.tsx
index 29ce3f580e..52032a79d3 100644
--- a/frontend/__tests__/components/chat/model-messages.test.tsx
+++ b/frontend/__tests__/components/chat/model-messages.test.tsx
@@ -73,10 +73,17 @@ describe("<ModelMessages />", () => {
).not.toBeInTheDocument();
});
- it("starts collapsed and reveals profile rows then row details on expansion", async () => {
- useModelStore
- .getState()
- .show(CONV, null, [profile("default"), profile("scratch")]);
+ it("starts collapsed, reveals profile rows, then model + base_url (no api_key) on row expansion", async () => {
+ useModelStore.getState().show(CONV, null, [
+ profile("default", {
+ model: "anthropic/claude-sonnet-4-6",
+ base_url: null,
+ }),
+ profile("scratch", {
+ model: "openai/gpt-5",
+ base_url: "https://api.example.com",
+ }),
+ ]);
const user = userEvent.setup();
render(<ModelMessages conversationId={CONV} anchorEventId={null} />);
@@ -88,11 +95,20 @@ describe("<ModelMessages />", () => {
await user.click(screen.getByRole("button", { name: /expand/i }));
- // Profile rows are now visible, but per-row details remain collapsed.
- expect(screen.queryByText(/api_key:/i)).toBeNull();
+ // Profile rows are now visible (as toggles), but their details stay
+ // collapsed until the row is opened.
+ expect(
+ screen.getByRole("button", { name: /default/i }),
+ ).toBeInTheDocument();
+ expect(screen.queryByText(/model:/i)).toBeNull();
+ // Opening a row reveals just its model and base_url β€” never the api_key.
await user.click(screen.getByRole("button", { name: /default/i }));
- expect(screen.getByText(/api_key:\s+set/i)).toBeInTheDocument();
+ expect(
+ screen.getByText(/model:\s+anthropic\/claude-sonnet-4-6/),
+ ).toBeInTheDocument();
+ expect(screen.getByText(/base_url:/i)).toBeInTheDocument();
+ expect(screen.queryByText(/api_key/i)).toBeNull();
});
it("only renders entries whose anchor matches the prop", () => {
diff --git a/frontend/__tests__/components/features/chat/switch-profile-button.test.tsx b/frontend/__tests__/components/features/chat/switch-profile-button.test.tsx
index 2a5171c2f3..dab76885b4 100644
--- a/frontend/__tests__/components/features/chat/switch-profile-button.test.tsx
+++ b/frontend/__tests__/components/features/chat/switch-profile-button.test.tsx
@@ -13,6 +13,9 @@ import type { LlmProfileSummary } from "#/api/settings-service/profiles-service.
const mockUseLlmProfiles = vi.hoisted(() => vi.fn());
const mockUseActiveConversation = vi.hoisted(() => vi.fn());
const mockSwitchAndLog = vi.hoisted(() => vi.fn());
+const mockModelStore = vi.hoisted(() => ({
+ activeProfileByConversation: {} as Record<string, string>,
+}));
vi.mock("#/hooks/query/use-llm-profiles", () => ({
useLlmProfiles: () => mockUseLlmProfiles(),
@@ -34,6 +37,14 @@ vi.mock("#/hooks/use-conversation-id", () => ({
useConversationId: () => ({ conversationId: "conv-1" }),
}));
+vi.mock("#/stores/model-store", () => ({
+ useModelStore: (
+ selector: (s: {
+ activeProfileByConversation: Record<string, string>;
+ }) => unknown,
+ ) => selector(mockModelStore),
+}));
+
const PROFILES: LlmProfileSummary[] = [
{
name: "default",
@@ -68,6 +79,7 @@ const setupHooks = (
activeProfile?: string | null;
conversationModel?: string | null;
agentKind?: "openhands" | "acp";
+ switchedProfile?: string;
} = {},
) => {
mockUseLlmProfiles.mockReturnValue({
@@ -82,6 +94,9 @@ const setupHooks = (
agent_kind: options.agentKind ?? "openhands",
},
});
+ mockModelStore.activeProfileByConversation = options.switchedProfile
+ ? { "conv-1": options.switchedProfile }
+ : {};
};
describe("SwitchProfileButton", () => {
@@ -135,6 +150,32 @@ describe("SwitchProfileButton", () => {
);
});
+ it("prefers an in-session switch over the llm_model match (by name, not model)", () => {
+ // The running model maps to "gpt-5", but the user just switched to
+ // "default" β€” the button must show the switched profile by name. This is
+ // what fixes SaaS, where managed profiles can share a model string and the
+ // model-match would otherwise resolve to the wrong (or a stale) profile.
+ setupHooks({
+ conversationModel: "openai/gpt-5",
+ switchedProfile: "default",
+ });
+ renderButton();
+ expect(screen.getByTestId("switch-profile-button")).toHaveTextContent(
+ "default",
+ );
+ });
+
+ it("ignores a switched profile that no longer exists and falls back to the model match", () => {
+ setupHooks({
+ conversationModel: "openai/gpt-5",
+ switchedProfile: "deleted-profile",
+ });
+ renderButton();
+ expect(screen.getByTestId("switch-profile-button")).toHaveTextContent(
+ "gpt-5",
+ );
+ });
+
it("toggles the menu open and closed on click", async () => {
const user = userEvent.setup();
setupHooks({ conversationModel: "openai/gpt-5" });
diff --git a/frontend/__tests__/components/features/chat/switch-profile-context-menu.test.tsx b/frontend/__tests__/components/features/chat/switch-profile-context-menu.test.tsx
index a38926a60c..d70e6a4e2f 100644
--- a/frontend/__tests__/components/features/chat/switch-profile-context-menu.test.tsx
+++ b/frontend/__tests__/components/features/chat/switch-profile-context-menu.test.tsx
@@ -62,6 +62,12 @@ describe("SwitchProfileContextMenu", () => {
).toBeInTheDocument();
});
+ it("shows each profile's provider/model under its name", () => {
+ renderMenu();
+ expect(screen.getByText("anthropic/claude-sonnet-4-6")).toBeInTheDocument();
+ expect(screen.getByText("openai/gpt-5")).toBeInTheDocument();
+ });
+
it("marks the active profile with aria-current=true and others without", () => {
renderMenu({ activeProfileName: "gpt-5" });
expect(screen.getByTestId("switch-profile-option-gpt-5")).toHaveAttribute(
diff --git a/frontend/__tests__/routes/llm-settings.test.tsx b/frontend/__tests__/routes/llm-settings.test.tsx
index afd465c699..4e232f8fa0 100644
--- a/frontend/__tests__/routes/llm-settings.test.tsx
+++ b/frontend/__tests__/routes/llm-settings.test.tsx
@@ -1899,7 +1899,7 @@ describe("LlmSettingsScreen", () => {
});
});
- it("should enable submit button when form is dirty", async () => {
+ it("keeps the submit button enabled in the profile form even when pristine", async () => {
vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
buildSettings({
llm_model: "openai/gpt-4o",
@@ -1915,8 +1915,14 @@ describe("LlmSettingsScreen", () => {
await screen.findByTestId("llm-settings-screen");
const submitButton = screen.getByTestId("save-button");
- expect(submitButton).toBeDisabled();
-
+ // The profile form snapshots the current config as a profile (the
+ // name is optional β€” it falls back to a model-derived default), so
+ // Save is available without first dirtying a field. This is what lets
+ // you save a profile in SaaS managed mode, where the model is fixed
+ // and there's no editable API key to make the form dirty.
+ expect(submitButton).not.toBeDisabled();
+
+ // Editing a field keeps it enabled.
await userEvent.type(
screen.getByTestId("llm-api-key-input"),
"test-api-key",
@@ -2020,7 +2026,7 @@ describe("LlmSettingsScreen", () => {
});
});
- it("should enable submit button when form is dirty", async () => {
+ it("keeps the submit button enabled in the profile form even when pristine", async () => {
vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
buildSettings({
llm_model: "openai/gpt-4o",
@@ -2036,8 +2042,14 @@ describe("LlmSettingsScreen", () => {
await screen.findByTestId("llm-settings-screen");
const submitButton = screen.getByTestId("save-button");
- expect(submitButton).toBeDisabled();
-
+ // The profile form snapshots the current config as a profile (the
+ // name is optional β€” it falls back to a model-derived default), so
+ // Save is available without first dirtying a field. This is what lets
+ // you save a profile in SaaS managed mode, where the model is fixed
+ // and there's no editable API key to make the form dirty.
+ expect(submitButton).not.toBeDisabled();
+
+ // Editing a field keeps it enabled.
await userEvent.type(
screen.getByTestId("llm-api-key-input"),
"test-api-key",
diff --git a/frontend/__tests__/stores/model-store.test.ts b/frontend/__tests__/stores/model-store.test.ts
index 6a43bc7b36..5480731a48 100644
--- a/frontend/__tests__/stores/model-store.test.ts
+++ b/frontend/__tests__/stores/model-store.test.ts
@@ -15,9 +15,15 @@ const profile = (name: string): LlmProfileSummary => ({
const entriesFor = (conv: string) =>
useModelStore.getState().entriesByConversation[conv] ?? [];
+const activeProfileFor = (conv: string) =>
+ useModelStore.getState().activeProfileByConversation[conv] ?? null;
+
describe("model store", () => {
beforeEach(() => {
- useModelStore.setState({ entriesByConversation: {} });
+ useModelStore.setState({
+ entriesByConversation: {},
+ activeProfileByConversation: {},
+ });
});
it("show appends an entry scoped to the given conversation", () => {
@@ -73,4 +79,25 @@ describe("model store", () => {
expect(entriesFor(CONV_A)[1].switchedTo).toBe("gpt-5");
expect(entriesFor(CONV_A)[1].profiles).toEqual([]);
});
+
+ it("recordSwitch tracks the active profile by name, per conversation, last-write-wins", () => {
+ useModelStore.getState().recordSwitch(CONV_A, null, "gpt-5");
+ expect(activeProfileFor(CONV_A)).toBe("gpt-5");
+ expect(activeProfileFor(CONV_B)).toBeNull();
+
+ // A later switch in the same conversation supersedes the previous one.
+ useModelStore.getState().recordSwitch(CONV_A, null, "default");
+ expect(activeProfileFor(CONV_A)).toBe("default");
+
+ // Other conversations are unaffected.
+ useModelStore.getState().recordSwitch(CONV_B, null, "claude");
+ expect(activeProfileFor(CONV_A)).toBe("default");
+ expect(activeProfileFor(CONV_B)).toBe("claude");
+ });
+
+ it("show does not change the tracked active profile", () => {
+ useModelStore.getState().recordSwitch(CONV_A, null, "gpt-5");
+ useModelStore.getState().show(CONV_A, null, [profile("default")]);
+ expect(activeProfileFor(CONV_A)).toBe("gpt-5");
+ });
});
diff --git a/frontend/src/api/organization-service/org-profiles-service.api.ts b/frontend/src/api/organization-service/org-profiles-service.api.ts
new file mode 100644
index 0000000000..dce728584f
--- /dev/null
+++ b/frontend/src/api/organization-service/org-profiles-service.api.ts
@@ -0,0 +1,77 @@
+import { openHands } from "../open-hands-axios";
+
+export interface OrgLlmProfileSummary {
+ name: string;
+ model: string | null;
+ base_url: string | null;
+ api_key_set: boolean;
+}
+
+interface OrgLlmProfileListResponse {
+ profiles: OrgLlmProfileSummary[];
+ active_profile: string | null;
+}
+
+export interface SaveOrgLlmProfileRequest {
+ include_secrets?: boolean;
+ llm?: {
+ model: string;
+ base_url?: string | null;
+ api_key?: string | null;
+ } & Record<string, unknown>;
+}
+
+class OrgProfilesService {
+ static async listProfiles(orgId: string): Promise<OrgLlmProfileListResponse> {
+ const { data } = await openHands.get<OrgLlmProfileListResponse>(
+ `/api/organizations/${orgId}/profiles`,
+ );
+ return data;
+ }
+
+ static async getProfile(
+ orgId: string,
+ name: string,
+ ): Promise<{ name: string; llm: Record<string, unknown> }> {
+ const { data } = await openHands.get(
+ `/api/organizations/${orgId}/profiles/${encodeURIComponent(name)}`,
+ );
+ return data;
+ }
+
+ static async saveProfile(
+ orgId: string,
+ name: string,
+ request: SaveOrgLlmProfileRequest = {},
+ ): Promise<void> {
+ await openHands.post(
+ `/api/organizations/${orgId}/profiles/${encodeURIComponent(name)}`,
+ request,
+ );
+ }
+
+ static async deleteProfile(orgId: string, name: string): Promise<void> {
+ await openHands.delete(
+ `/api/organizations/${orgId}/profiles/${encodeURIComponent(name)}`,
+ );
+ }
+
+ static async activateProfile(orgId: string, name: string): Promise<void> {
+ await openHands.post(
+ `/api/organizations/${orgId}/profiles/${encodeURIComponent(name)}/activate`,
+ );
+ }
+
+ static async renameProfile(
+ orgId: string,
+ name: string,
+ newName: string,
+ ): Promise<void> {
+ await openHands.post(
+ `/api/organizations/${orgId}/profiles/${encodeURIComponent(name)}/rename`,
+ { new_name: newName },
+ );
+ }
+}
+
+export default OrgProfilesService;
diff --git a/frontend/src/components/features/chat/model-messages.tsx b/frontend/src/components/features/chat/model-messages.tsx
index 783220354d..ce0f90324c 100644
--- a/frontend/src/components/features/chat/model-messages.tsx
+++ b/frontend/src/components/features/chat/model-messages.tsx
@@ -34,8 +34,7 @@ function ProfileRow({ profile }: ProfileRowProps) {
<hr className="border-neutral-700" />
<div className="px-3 py-2 text-xs text-neutral-300 font-mono whitespace-pre-wrap">
{`model: ${profile.model ?? "β€”"}\n` +
- `base_url: ${profile.base_url ?? "β€”"}\n` +
- `api_key: ${profile.api_key_set ? "set" : "not set"}`}
+ `base_url: ${profile.base_url ?? "β€”"}`}
</div>
</>
)}
diff --git a/frontend/src/components/features/chat/switch-profile-button.tsx b/frontend/src/components/features/chat/switch-profile-button.tsx
index 70fe714bc2..4eb1438e25 100644
--- a/frontend/src/components/features/chat/switch-profile-button.tsx
+++ b/frontend/src/components/features/chat/switch-profile-button.tsx
@@ -8,6 +8,7 @@ import { useLlmProfiles } from "#/hooks/query/use-llm-profiles";
import { useSwitchLlmProfileAndLog } from "#/hooks/mutation/use-switch-llm-profile-and-log";
import { useActiveConversation } from "#/hooks/query/use-active-conversation";
import { useConversationId } from "#/hooks/use-conversation-id";
+import { useModelStore } from "#/stores/model-store";
import { SwitchProfileContextMenu } from "./switch-profile-context-menu";
export function SwitchProfileButton() {
@@ -17,16 +18,37 @@ export function SwitchProfileButton() {
const { data } = useLlmProfiles();
const { data: conversation } = useActiveConversation();
const { switchAndLog, isPending } = useSwitchLlmProfileAndLog();
+ const switchedProfileName = useModelStore(
+ (s) => s.activeProfileByConversation[conversationId] ?? null,
+ );
const profiles = data?.profiles ?? [];
const conversationModel = conversation?.llm_model ?? null;
- // Match the running model first; only fall back to the user-level default
- // when the conversation has no model yet β€” otherwise we'd misrepresent the
- // running model after a per-conversation /model switch.
- const activeProfileName = conversationModel
- ? (profiles.find((p) => p.model === conversationModel)?.name ?? null)
- : (data?.active_profile ?? null);
+ // Resolve the active profile, most-authoritative source first:
+ // 1. A switch the user made this session (recorded by name, so it's exact
+ // even when several profiles share a model string, e.g. SaaS managed
+ // models behind the litellm_proxy, and instant β€” no refetch needed).
+ // 2. The running model, matched by `llm_model` (covers a freshly loaded
+ // conversation where no switch happened this session).
+ // 3. The user-level default, only when the conversation has no model yet β€”
+ // otherwise we'd misrepresent the running model.
+ const switchedProfileMatch =
+ switchedProfileName && profiles.some((p) => p.name === switchedProfileName)
+ ? switchedProfileName
+ : null;
+ const activeProfileName =
+ switchedProfileMatch ??
+ (conversationModel
+ ? (profiles.find((p) => p.model === conversationModel)?.name ?? null)
+ : (data?.active_profile ?? null));
+
+ // The active profile's provider/model, surfaced as a tooltip on the button
+ // (the dropdown shows it under each name). Matches agent-canvas.
+ const activeProfileModel =
+ profiles.find((p) => p.name === activeProfileName)?.model ??
+ conversationModel ??
+ null;
// LLM profiles don't apply to ACP conversations: the sub-agent
// (Claude Code / Codex / Gemini CLI) drives its own model selection,
@@ -58,6 +80,7 @@ export function SwitchProfileButton() {
onClick={handleClick}
disabled={isPending}
data-testid="switch-profile-button"
+ title={activeProfileModel ?? undefined}
aria-haspopup="menu"
aria-expanded={contextMenuOpen}
className="flex items-center gap-1 border border-[#4B505F] rounded-[100px] transition-opacity cursor-pointer hover:opacity-80 disabled:opacity-50 disabled:cursor-not-allowed pl-2 max-w-[200px]"
diff --git a/frontend/src/components/features/chat/switch-profile-context-menu.tsx b/frontend/src/components/features/chat/switch-profile-context-menu.tsx
index e5b5d2fadf..ab457f48ce 100644
--- a/frontend/src/components/features/chat/switch-profile-context-menu.tsx
+++ b/frontend/src/components/features/chat/switch-profile-context-menu.tsx
@@ -20,6 +20,10 @@ const itemClassName = cn(
CONTEXT_MENU_ICON_TEXT_CLASSNAME,
);
+// Profile rows are two lines (name + model), so they need auto height β€”
+// unlike `itemClassName`, which keeps the single-line Settings link compact.
+const profileItemClassName = "cursor-pointer p-0 h-auto hover:bg-transparent";
+
interface SwitchProfileContextMenuProps {
profiles: LlmProfileSummary[];
activeProfileName: string | null;
@@ -58,7 +62,7 @@ export function SwitchProfileContextMenu({
testId="switch-profile-context-menu"
position="top"
alignment="left"
- className="left-0 mb-2 bottom-full min-w-[220px] max-h-[60vh] overflow-y-auto"
+ className="left-0 mb-2 bottom-full min-w-[260px] max-h-[60vh] overflow-y-auto"
>
<SettingsNavHeader
text={I18nKey.SETTINGS$AVAILABLE_PROFILES}
@@ -71,20 +75,33 @@ export function SwitchProfileContextMenu({
key={profile.name}
testId={`switch-profile-option-${profile.name}`}
onClick={(event) => handleSelect(event, profile.name)}
- className={itemClassName}
+ className={profileItemClassName}
ariaCurrent={isActive ? "true" : undefined}
>
- <ToolsContextMenuIconText
- icon={<CircuitIcon width={16} height={16} />}
- text={profile.name}
- rightIcon={
- isActive ? <CheckIcon width={14} height={14} /> : undefined
- }
+ {/* Two lines: the profile name, with its provider/model beneath
+ (matches agent-canvas). Full model also in the title tooltip. */}
+ <div
+ title={profile.model ?? undefined}
className={cn(
- CONTEXT_MENU_ICON_TEXT_CLASSNAME,
- isActive && "bg-[#5C5D62]",
+ "flex flex-col gap-0.5 p-2 rounded",
+ isActive ? "bg-[#5C5D62]" : "hover:bg-[#5C5D62]",
+ )}
+ >
+ <div className="flex items-center justify-between gap-2">
+ <div className="flex items-center gap-2 min-w-0">
+ <CircuitIcon width={16} height={16} className="shrink-0" />
+ <span className="truncate">{profile.name}</span>
+ </div>
+ {isActive && (
+ <CheckIcon width={14} height={14} className="shrink-0" />
+ )}
+ </div>
+ {profile.model && (
+ <span className="block truncate text-xs leading-4 text-gray-400 pl-6">
+ {profile.model}
+ </span>
)}
- />
+ </div>
</ContextMenuListItem>
);
})}
diff --git a/frontend/src/components/features/conversation/conversation-name.tsx b/frontend/src/components/features/conversation/conversation-name.tsx
index 6ea493f6a8..0e0aff09e8 100644
--- a/frontend/src/components/features/conversation/conversation-name.tsx
+++ b/frontend/src/components/features/conversation/conversation-name.tsx
@@ -172,12 +172,12 @@ export function ConversationName() {
{titleMode !== "edit" && agentLabel && (
<span
- className="text-xs text-[#A3A3A3] max-w-[150px] flex items-center gap-1 overflow-hidden"
+ className="text-xs text-[#A3A3A3] flex items-center gap-1 whitespace-nowrap"
title={conversation.llm_model ?? agentLabel}
data-testid="conversation-name-llm-model"
>
<CircuitIcon width={12} height={12} className="shrink-0" />
- <Typography.Text className="text-xs text-[#A3A3A3] truncate">
+ <Typography.Text className="text-xs text-[#A3A3A3]">
{agentLabel}
</Typography.Text>
</span>
diff --git a/frontend/src/components/features/settings/org-delete-profile-modal.tsx b/frontend/src/components/features/settings/org-delete-profile-modal.tsx
new file mode 100644
index 0000000000..776168edd4
--- /dev/null
+++ b/frontend/src/components/features/settings/org-delete-profile-modal.tsx
@@ -0,0 +1,77 @@
+import { useTranslation } from "react-i18next";
+import { BrandButton } from "#/components/features/settings/brand-button";
+import { LoadingSpinner } from "#/components/shared/loading-spinner";
+import { ApiKeyModalBase } from "#/components/features/settings/api-key-modal-base";
+import { LlmProfileSummary } from "#/api/settings-service/profiles-service.api";
+import { useDeleteOrgLlmProfile } from "#/hooks/mutation/use-org-llm-profile-mutations";
+import { mutateWithToast } from "#/utils/mutate-with-toast";
+import { extractErrorMessage } from "#/utils/extract-error-message";
+import { I18nKey } from "#/i18n/declaration";
+import { Typography } from "#/ui/typography";
+
+interface OrgDeleteProfileModalProps {
+ orgId: string;
+ profile: LlmProfileSummary | null;
+ onClose: () => void;
+}
+
+export function OrgDeleteProfileModal({
+ orgId,
+ profile,
+ onClose,
+}: OrgDeleteProfileModalProps) {
+ const { t } = useTranslation();
+ const deleteProfile = useDeleteOrgLlmProfile(orgId);
+
+ if (!profile) return null;
+
+ const handleDelete = async () => {
+ const ok = await mutateWithToast(deleteProfile, profile.name, {
+ success: t(I18nKey.SETTINGS$PROFILE_DELETED, { name: profile.name }),
+ error: (err) => extractErrorMessage(err, t(I18nKey.ERROR$GENERIC)),
+ }).catch(() => null);
+ if (ok !== null) onClose();
+ };
+
+ const footer = (
+ <>
+ <BrandButton
+ testId="delete-profile-confirm"
+ type="button"
+ variant="danger"
+ className="grow"
+ onClick={handleDelete}
+ isDisabled={deleteProfile.isPending}
+ >
+ {deleteProfile.isPending ? (
+ <LoadingSpinner size="small" />
+ ) : (
+ t(I18nKey.BUTTON$DELETE)
+ )}
+ </BrandButton>
+ <BrandButton
+ type="button"
+ variant="secondary"
+ className="grow"
+ onClick={onClose}
+ isDisabled={deleteProfile.isPending}
+ >
+ {t(I18nKey.BUTTON$CANCEL)}
+ </BrandButton>
+ </>
+ );
+
+ return (
+ <ApiKeyModalBase
+ isOpen
+ title={t(I18nKey.SETTINGS$PROFILE_DELETE_TITLE)}
+ footer={footer}
+ >
+ <Typography.Paragraph className="text-sm break-all">
+ {t(I18nKey.SETTINGS$PROFILE_DELETE_CONFIRMATION, {
+ name: profile.name,
+ })}
+ </Typography.Paragraph>
+ </ApiKeyModalBase>
+ );
+}
diff --git a/frontend/src/components/features/settings/org-llm-profiles-manager.tsx b/frontend/src/components/features/settings/org-llm-profiles-manager.tsx
new file mode 100644
index 0000000000..d72fe0bc5d
--- /dev/null
+++ b/frontend/src/components/features/settings/org-llm-profiles-manager.tsx
@@ -0,0 +1,94 @@
+import { useState } from "react";
+import { useTranslation } from "react-i18next";
+import { BrandButton } from "#/components/features/settings/brand-button";
+import { OrgRenameProfileModal } from "#/components/features/settings/org-rename-profile-modal";
+import { OrgDeleteProfileModal } from "#/components/features/settings/org-delete-profile-modal";
+import { ProfilesBody } from "#/components/features/settings/profiles-body";
+import { LlmProfileSummary } from "#/api/settings-service/profiles-service.api";
+import { useOrgLlmProfiles } from "#/hooks/query/use-org-llm-profiles";
+import { useActivateOrgLlmProfile } from "#/hooks/mutation/use-org-llm-profile-mutations";
+import { mutateWithToast } from "#/utils/mutate-with-toast";
+import { extractErrorMessage } from "#/utils/extract-error-message";
+import { I18nKey } from "#/i18n/declaration";
+
+interface OrgLlmProfilesManagerProps {
+ orgId: string;
+ onAddProfile?: () => void;
+ onEditProfile?: (profile: LlmProfileSummary) => void;
+}
+
+export function OrgLlmProfilesManager({
+ orgId,
+ onAddProfile,
+ onEditProfile,
+}: OrgLlmProfilesManagerProps) {
+ const { t } = useTranslation();
+ const { data, isLoading, error } = useOrgLlmProfiles(orgId);
+ const activateProfile = useActivateOrgLlmProfile(orgId);
+
+ const [profileToRename, setProfileToRename] =
+ useState<LlmProfileSummary | null>(null);
+ const [profileToDelete, setProfileToDelete] =
+ useState<LlmProfileSummary | null>(null);
+
+ const profiles = data?.profiles ?? [];
+ const active = data?.active_profile ?? null;
+
+ const handleActivate = async (name: string) => {
+ await mutateWithToast(activateProfile, name, {
+ success: t(I18nKey.SETTINGS$PROFILE_ACTIVATED, { name }),
+ error: (err) => extractErrorMessage(err, t(I18nKey.ERROR$GENERIC)),
+ }).catch(() => null);
+ };
+
+ const handleEdit = (profile: LlmProfileSummary) => {
+ onEditProfile?.(profile);
+ };
+
+ return (
+ <>
+ <div className="flex flex-col gap-4">
+ <div className="flex flex-wrap items-center justify-between gap-3">
+ <h2 className="text-base font-semibold text-white">
+ {t(I18nKey.SETTINGS$AVAILABLE_PROFILES)}
+ </h2>
+ {onAddProfile ? (
+ <BrandButton
+ testId="add-llm-profile"
+ type="button"
+ variant="primary"
+ className="ml-auto"
+ onClick={onAddProfile}
+ >
+ {t(I18nKey.SETTINGS$ADD_LLM_PROFILE)}
+ </BrandButton>
+ ) : null}
+ </div>
+
+ <ProfilesBody
+ isLoading={isLoading}
+ loadError={error ?? null}
+ profiles={profiles}
+ active={active}
+ onActivate={handleActivate}
+ onEdit={handleEdit}
+ onRename={setProfileToRename}
+ onDelete={setProfileToDelete}
+ isActivating={activateProfile.isPending}
+ />
+ </div>
+
+ <OrgRenameProfileModal
+ orgId={orgId}
+ profile={profileToRename}
+ onClose={() => setProfileToRename(null)}
+ />
+
+ <OrgDeleteProfileModal
+ orgId={orgId}
+ profile={profileToDelete}
+ onClose={() => setProfileToDelete(null)}
+ />
+ </>
+ );
+}
diff --git a/frontend/src/components/features/settings/org-rename-profile-modal.tsx b/frontend/src/components/features/settings/org-rename-profile-modal.tsx
new file mode 100644
index 0000000000..a975105e95
--- /dev/null
+++ b/frontend/src/components/features/settings/org-rename-profile-modal.tsx
@@ -0,0 +1,107 @@
+import { useEffect, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { BrandButton } from "#/components/features/settings/brand-button";
+import { ProfileNameInput } from "#/components/features/settings/profile-name-input";
+import { LoadingSpinner } from "#/components/shared/loading-spinner";
+import { ApiKeyModalBase } from "#/components/features/settings/api-key-modal-base";
+import { LlmProfileSummary } from "#/api/settings-service/profiles-service.api";
+import { useRenameOrgLlmProfile } from "#/hooks/mutation/use-org-llm-profile-mutations";
+import { displayErrorToast } from "#/utils/custom-toast-handlers";
+import { mutateWithToast } from "#/utils/mutate-with-toast";
+import { extractErrorMessage } from "#/utils/extract-error-message";
+import { I18nKey } from "#/i18n/declaration";
+import { PROFILE_NAME_PATTERN } from "#/utils/derive-profile-name";
+
+interface OrgRenameProfileModalProps {
+ orgId: string;
+ profile: LlmProfileSummary | null;
+ onClose: () => void;
+}
+
+export function OrgRenameProfileModal({
+ orgId,
+ profile,
+ onClose,
+}: OrgRenameProfileModalProps) {
+ const { t } = useTranslation();
+ const [newName, setNewName] = useState("");
+ const renameProfile = useRenameOrgLlmProfile(orgId);
+
+ useEffect(() => {
+ setNewName(profile?.name ?? "");
+ }, [profile?.name]);
+
+ if (!profile) return null;
+
+ const trimmed = newName.trim();
+ const isUnchanged = trimmed === profile.name;
+ const isValid = PROFILE_NAME_PATTERN.test(trimmed);
+
+ const handleSubmit = async () => {
+ if (!isValid) {
+ displayErrorToast(t(I18nKey.SETTINGS$PROFILE_NAME_RULE));
+ return;
+ }
+ if (isUnchanged) {
+ onClose();
+ return;
+ }
+ const ok = await mutateWithToast(
+ renameProfile,
+ { name: profile.name, newName: trimmed },
+ {
+ success: t(I18nKey.SETTINGS$PROFILE_RENAMED, { name: trimmed }),
+ error: (err) => extractErrorMessage(err, t(I18nKey.ERROR$GENERIC)),
+ },
+ ).catch(() => null);
+ if (ok !== null) onClose();
+ };
+
+ const footer = (
+ <>
+ <BrandButton
+ testId="org-rename-profile-submit"
+ type="button"
+ variant="primary"
+ className="grow"
+ onClick={handleSubmit}
+ isDisabled={renameProfile.isPending || !isValid}
+ >
+ {renameProfile.isPending ? (
+ <LoadingSpinner size="small" />
+ ) : (
+ t(I18nKey.BUTTON$RENAME)
+ )}
+ </BrandButton>
+ <BrandButton
+ type="button"
+ variant="secondary"
+ className="grow"
+ onClick={onClose}
+ isDisabled={renameProfile.isPending}
+ >
+ {t(I18nKey.BUTTON$CANCEL)}
+ </BrandButton>
+ </>
+ );
+
+ return (
+ <ApiKeyModalBase
+ isOpen
+ title={t(I18nKey.SETTINGS$PROFILE_RENAME_TITLE)}
+ footer={footer}
+ >
+ <div
+ data-testid="org-rename-profile-modal"
+ className="flex flex-col gap-3"
+ >
+ <ProfileNameInput
+ testId="org-rename-profile-input"
+ ruleTestId="org-rename-profile-rule"
+ value={newName}
+ onChange={setNewName}
+ />
+ </div>
+ </ApiKeyModalBase>
+ );
+}
diff --git a/frontend/src/contexts/conversation-websocket-context.tsx b/frontend/src/contexts/conversation-websocket-context.tsx
index 25f651c1fe..071836a56a 100644
--- a/frontend/src/contexts/conversation-websocket-context.tsx
+++ b/frontend/src/contexts/conversation-websocket-context.tsx
@@ -10,6 +10,9 @@ import React, {
import { useQueryClient } from "@tanstack/react-query";
import { useWebSocket, WebSocketHookOptions } from "#/hooks/use-websocket";
import { useEventStore } from "#/stores/use-event-store";
+import { useModelStore } from "#/stores/model-store";
+import { getRenderedV1Events } from "#/components/v1/chat/event-content-helpers/should-render-event";
+import { updateConversationLlmModelInCache } from "#/hooks/mutation/conversation-mutation-utils";
import { useErrorMessageStore } from "#/stores/error-message-store";
import { useOptimisticUserMessageStore } from "#/stores/optimistic-user-message-store";
import { useV1ConversationStateStore } from "#/stores/v1-conversation-state-store";
@@ -24,6 +27,7 @@ import {
isFullStateConversationStateUpdateEvent,
isAgentStatusConversationStateUpdateEvent,
isStatsConversationStateUpdateEvent,
+ isSwitchLLMObservationEvent,
isExecuteBashActionEvent,
isExecuteBashObservationEvent,
isDisplayableErrorEvent,
@@ -456,6 +460,45 @@ export function ConversationWebSocketProvider({
}
}
+ // The agent switched its own LLM (via the built-in switch_llm tool).
+ // Mirror the manual-switch UX: record the new profile (so the
+ // switch-profile button flips by name, unambiguous even when several
+ // profiles share a model string) and patch the running model into the
+ // conversation cache so the chat header updates instantly.
+ //
+ // We deliberately do NOT invalidate the conversation query here. The
+ // app-server only learns of the switch via the webhook, which is
+ // batched (``event_buffer_size`` / ``flush_delay``), and the
+ // conversation endpoint reports the *persisted* ``llm_model`` (not the
+ // sandbox's live model). An immediate refetch would therefore read the
+ // pre-switch model and clobber the patch above. The persisted value
+ // catches up on the next poll once the webhook has flushed.
+ if (
+ conversationId &&
+ isSwitchLLMObservationEvent(event) &&
+ !event.observation.is_error
+ ) {
+ const last = getRenderedV1Events(
+ useEventStore.getState().uiEvents,
+ ).at(-1);
+ const anchorEventId = last ? String(last.id) : null;
+ useModelStore
+ .getState()
+ .recordSwitch(
+ conversationId,
+ anchorEventId,
+ event.observation.profile_name,
+ );
+
+ if (event.observation.active_model) {
+ updateConversationLlmModelInCache(
+ queryClient,
+ conversationId,
+ event.observation.active_model,
+ );
+ }
+ }
+
// Handle ExecuteBashAction events - add command as input to terminal
if (isExecuteBashActionEvent(event)) {
appendInput(event.action.command);
diff --git a/frontend/src/hooks/mutation/conversation-mutation-utils.ts b/frontend/src/hooks/mutation/conversation-mutation-utils.ts
index 9173266322..8982f3413e 100644
--- a/frontend/src/hooks/mutation/conversation-mutation-utils.ts
+++ b/frontend/src/hooks/mutation/conversation-mutation-utils.ts
@@ -132,6 +132,22 @@ export const updateConversationSandboxStatusInCache = (
});
};
+/**
+ * Optimistically updates the conversation's running model in the cache, so the
+ * chat header and switch-profile button reflect an agent-initiated LLM switch
+ * immediately (before the conversation query refetches).
+ */
+export const updateConversationLlmModelInCache = (
+ queryClient: QueryClient,
+ conversationId: string,
+ llm_model: string,
+): void => {
+ queryClient.setQueryData<V1AppConversation | null>(
+ ["user", "conversation", conversationId],
+ (oldData) => (oldData ? { ...oldData, llm_model } : oldData),
+ );
+};
+
/**
* Invalidates all queries related to conversation mutations (start/stop)
*/
diff --git a/frontend/src/hooks/mutation/use-org-llm-profile-mutations.ts b/frontend/src/hooks/mutation/use-org-llm-profile-mutations.ts
new file mode 100644
index 0000000000..98cb8ab754
--- /dev/null
+++ b/frontend/src/hooks/mutation/use-org-llm-profile-mutations.ts
@@ -0,0 +1,98 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import OrgProfilesService, {
+ SaveOrgLlmProfileRequest,
+} from "#/api/organization-service/org-profiles-service.api";
+import { ORG_LLM_PROFILES_QUERY_KEY } from "#/hooks/query/use-org-llm-profiles";
+import { LLM_PROFILES_QUERY_KEY } from "#/hooks/query/use-llm-profiles";
+import { SETTINGS_QUERY_KEYS } from "#/hooks/query/query-keys";
+
+// The chat-layer switch button and /model command read the personal
+// profiles query (/api/v1/settings/profiles), which surfaces org profiles
+// in SaaS mode via SaasSettingsStore. Invalidate that cache too so those
+// surfaces refresh after org-side CRUD without a full reload.
+const invalidateProfileCaches = (
+ queryClient: ReturnType<typeof useQueryClient>,
+ orgId: string | null | undefined,
+) => {
+ queryClient.invalidateQueries({
+ queryKey: [ORG_LLM_PROFILES_QUERY_KEY, orgId],
+ });
+ queryClient.invalidateQueries({
+ queryKey: [LLM_PROFILES_QUERY_KEY],
+ });
+};
+
+export function useSaveOrgLlmProfile(orgId: string | null | undefined) {
+ const queryClient = useQueryClient();
+
+ return useMutation({
+ mutationFn: async ({
+ name,
+ request,
+ }: {
+ name: string;
+ request?: SaveOrgLlmProfileRequest;
+ }) => {
+ if (!orgId) throw new Error("Organization ID is required");
+ await OrgProfilesService.saveProfile(orgId, name, request ?? {});
+ },
+ onSuccess: () => {
+ invalidateProfileCaches(queryClient, orgId);
+ },
+ });
+}
+
+export function useDeleteOrgLlmProfile(orgId: string | null | undefined) {
+ const queryClient = useQueryClient();
+
+ return useMutation({
+ mutationFn: async (name: string) => {
+ if (!orgId) throw new Error("Organization ID is required");
+ await OrgProfilesService.deleteProfile(orgId, name);
+ },
+ onSuccess: () => {
+ invalidateProfileCaches(queryClient, orgId);
+ },
+ });
+}
+
+export function useActivateOrgLlmProfile(orgId: string | null | undefined) {
+ const queryClient = useQueryClient();
+
+ return useMutation({
+ mutationFn: async (name: string) => {
+ if (!orgId) throw new Error("Organization ID is required");
+ await OrgProfilesService.activateProfile(orgId, name);
+ },
+ onSuccess: () => {
+ invalidateProfileCaches(queryClient, orgId);
+ // Activation writes the member's agent_settings_diff, whose effective
+ // settings surface under the *personal* scope (not just "org"). Invalidate
+ // all settings scopes β€” matching the personal useActivateLlmProfile hook β€”
+ // so every settings surface refetches the new active LLM config.
+ queryClient.invalidateQueries({
+ queryKey: SETTINGS_QUERY_KEYS.all,
+ });
+ },
+ });
+}
+
+export function useRenameOrgLlmProfile(orgId: string | null | undefined) {
+ const queryClient = useQueryClient();
+
+ return useMutation({
+ mutationFn: async ({
+ name,
+ newName,
+ }: {
+ name: string;
+ newName: string;
+ }) => {
+ if (!orgId) throw new Error("Organization ID is required");
+ await OrgProfilesService.renameProfile(orgId, name, newName);
+ },
+ onSuccess: () => {
+ invalidateProfileCaches(queryClient, orgId);
+ },
+ });
+}
diff --git a/frontend/src/hooks/query/use-org-llm-profiles.ts b/frontend/src/hooks/query/use-org-llm-profiles.ts
new file mode 100644
index 0000000000..6499348cb4
--- /dev/null
+++ b/frontend/src/hooks/query/use-org-llm-profiles.ts
@@ -0,0 +1,19 @@
+import { useQuery } from "@tanstack/react-query";
+import OrgProfilesService from "#/api/organization-service/org-profiles-service.api";
+import { useIsAuthed } from "./use-is-authed";
+
+export const ORG_LLM_PROFILES_QUERY_KEY = "org-llm-profiles";
+
+export function useOrgLlmProfiles(orgId: string | null | undefined) {
+ const { data: userIsAuthenticated } = useIsAuthed();
+
+ return useQuery({
+ queryKey: [ORG_LLM_PROFILES_QUERY_KEY, orgId],
+ queryFn: () => OrgProfilesService.listProfiles(orgId!),
+ enabled: !!userIsAuthenticated && !!orgId,
+ retry: (_, error) => error.status !== 404,
+ staleTime: 1000 * 60 * 5,
+ gcTime: 1000 * 60 * 15,
+ meta: { disableToast: true },
+ });
+}
diff --git a/frontend/src/routes/llm-settings.tsx b/frontend/src/routes/llm-settings.tsx
index bda0971841..de4272bfde 100644
--- a/frontend/src/routes/llm-settings.tsx
+++ b/frontend/src/routes/llm-settings.tsx
@@ -31,13 +31,20 @@ import { DEFAULT_SETTINGS } from "#/services/settings";
import { useSaveLlmProfile } from "#/hooks/mutation/use-save-llm-profile";
import { useActivateLlmProfile } from "#/hooks/mutation/use-activate-llm-profile";
import { useRenameLlmProfile } from "#/hooks/mutation/use-rename-llm-profile";
+import {
+ useSaveOrgLlmProfile,
+ useActivateOrgLlmProfile,
+ useRenameOrgLlmProfile,
+} from "#/hooks/mutation/use-org-llm-profile-mutations";
import {
deriveProfileNameFromModel,
PROFILE_NAME_PATTERN,
} from "#/utils/derive-profile-name";
import { LlmProfilesManager } from "#/components/features/settings/llm-profiles-manager";
+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 { useOrgTypeAndAccess } from "#/hooks/use-org-type-and-access";
const LLM_EXCLUDED_KEYS = new Set(["llm.model", "llm.api_key", "llm.base_url"]);
@@ -105,6 +112,7 @@ export function LlmSettingsScreen({
settings?.agent_settings_schema,
);
const { data: config } = useConfig();
+ const { isPersonalOrg, organizationId } = useOrgTypeAndAccess();
const [selectedProvider, setSelectedProvider] = React.useState<string | null>(
null,
@@ -113,16 +121,28 @@ export function LlmSettingsScreen({
// Captured during buildPayload so onSaveSuccess can derive a profile name
// from the exact model that was just persisted.
const lastSavedModelRef = React.useRef<string | null>(null);
+
+ // Personal profile hooks (for OSS mode)
const saveProfile = useSaveLlmProfile();
const activateProfile = useActivateLlmProfile();
const renameProfile = useRenameLlmProfile();
+ // Org profile hooks (for SaaS mode with personal orgs)
+ const saveOrgProfile = useSaveOrgLlmProfile(organizationId);
+ const activateOrgProfile = useActivateOrgLlmProfile(organizationId);
+ const renameOrgProfile = useRenameOrgLlmProfile(organizationId);
+
// Controls whether the LLM form or the Profiles list is shown. Flipping
// this unmounts the inactive branch, so the SdkSectionPage re-hydrates
// its view from ``initialViewHint`` when coming back from profiles.
- // Personal scope lands on the Available Models list first; org-scope
- // defaults (which don't have profiles) always open straight into the form.
- const [showProfiles, setShowProfiles] = React.useState(scope === "personal");
+ // Enable profiles for:
+ // - Personal scope (OSS mode)
+ // - Org scope with personal org (SaaS mode)
+ const shouldShowProfilesForScope =
+ scope === "personal" || (scope === "org" && isPersonalOrg);
+ const [showProfiles, setShowProfiles] = React.useState(
+ shouldShowProfilesForScope,
+ );
// User-supplied profile name. Empty β†’ fall back to deriveProfileNameFromModel
// in handleSaveSuccess. Reset on every form open so a stale name from the
// previous Add doesn't leak in.
@@ -137,7 +157,11 @@ export function LlmSettingsScreen({
// getInitialView below.
const [initialViewHint, setInitialViewHint] =
React.useState<SettingsView | null>(null);
- const isProfilesView = scope === "personal" && showProfiles;
+
+ // Show profiles view for personal scope OR org scope with personal org
+ const isProfilesView = shouldShowProfilesForScope && showProfiles;
+ // Use org-scoped profile operations when in org scope
+ const isOrgProfileMode = scope === "org" && isPersonalOrg;
const defaultModel = String(
(DEFAULT_SETTINGS.agent_settings?.llm as Record<string, unknown>)?.model ??
@@ -282,7 +306,7 @@ export function LlmSettingsScreen({
</Typography.Paragraph>
) : null}
- {scope === "personal" ? (
+ {shouldShowProfilesForScope ? (
<ProfileNameInput
testId="llm-profile-name-input"
ruleTestId="llm-profile-name-rule"
@@ -369,6 +393,7 @@ export function LlmSettingsScreen({
scope,
selectedProvider,
settings?.llm_api_key_set,
+ shouldShowProfilesForScope,
t,
],
);
@@ -423,7 +448,7 @@ export function LlmSettingsScreen({
return { agent_settings_diff: agentSettings };
},
- [isSaasMode, schema, selectedProvider],
+ [isSaasMode, schema, scope, selectedProvider],
);
const handleSaveSuccess = React.useCallback(async () => {
@@ -440,27 +465,49 @@ export function LlmSettingsScreen({
: null;
const name = userName ?? derivedName;
- // Auto-saved profiles are a personal-scope feature β€” organization default
- // LLM settings reuse this screen but shouldn't spawn per-user profiles.
- if (scope !== "org" && name) {
+ // Auto-saved profiles for:
+ // - Personal scope (OSS mode)
+ // - Org scope with personal org (SaaS mode)
+ const shouldSaveProfile =
+ (scope === "personal" || (scope === "org" && isPersonalOrg)) && name;
+
+ if (shouldSaveProfile) {
try {
+ // Use org profile hooks for org scope, personal hooks for personal scope
+ const useOrgHooks = scope === "org" && isPersonalOrg;
+
// Editing an existing profile and renaming it via the form should
// rename the record in place rather than spawning a new one and
// leaving the original orphaned.
if (initialProfileName && initialProfileName !== name) {
- await renameProfile.mutateAsync({
- name: initialProfileName,
- newName: name,
- });
+ if (useOrgHooks) {
+ await renameOrgProfile.mutateAsync({
+ name: initialProfileName,
+ newName: name,
+ });
+ } else {
+ await renameProfile.mutateAsync({
+ name: initialProfileName,
+ newName: name,
+ });
+ }
}
// Omit `llm` β†’ backend snapshots the just-saved agent_settings.llm
// (api_key and all). Saves us from having to hand-reconstruct the
// config and risk mangling the secret placeholder handling.
- await saveProfile.mutateAsync({
- name,
- request: { include_secrets: true },
- });
- await activateProfile.mutateAsync(name);
+ if (useOrgHooks) {
+ await saveOrgProfile.mutateAsync({
+ name,
+ request: { include_secrets: true },
+ });
+ await activateOrgProfile.mutateAsync(name);
+ } else {
+ await saveProfile.mutateAsync({
+ name,
+ request: { include_secrets: true },
+ });
+ await activateProfile.mutateAsync(name);
+ }
} catch {
// Best-effort: the settings save already succeeded. Profile cap
// (HTTP 409) and transient errors are surfaced on the Profiles page.
@@ -473,10 +520,14 @@ export function LlmSettingsScreen({
setShowProfiles(true);
}, [
activateProfile,
+ activateOrgProfile,
initialProfileName,
+ isPersonalOrg,
profileName,
renameProfile,
+ renameOrgProfile,
saveProfile,
+ saveOrgProfile,
scope,
]);
@@ -488,6 +539,17 @@ export function LlmSettingsScreen({
};
if (isProfilesView) {
+ // Use org profiles manager for personal orgs in SaaS mode
+ if (isOrgProfileMode && organizationId) {
+ return (
+ <OrgLlmProfilesManager
+ orgId={organizationId}
+ onAddProfile={() => openForm(null)}
+ onEditProfile={(profile) => openForm(null, profile.name)}
+ />
+ );
+ }
+ // Use personal profiles manager for OSS mode
return (
<LlmProfilesManager
onAddProfile={() => openForm(null)}
@@ -496,24 +558,23 @@ export function LlmSettingsScreen({
);
}
- // Sub-page back affordance (personal scope only β€” org-defaults has no
- // parent list to return to). Replaces the previous "Profiles" trailing
- // action so the form view follows the second-level settings pattern.
- const backToProfiles =
- scope === "personal" ? (
- <button
- data-testid="llm-back-to-profiles"
- type="button"
- onClick={() => {
- setInitialViewHint(null);
- setShowProfiles(true);
- }}
- className="flex items-center gap-2 self-start text-sm text-gray-300 hover:text-white cursor-pointer"
- >
- <FaChevronLeft size={12} aria-hidden="true" />
- {t(I18nKey.SETTINGS$BACK_TO_LLM_LIST)}
- </button>
- ) : null;
+ // Sub-page back affordance when profiles are enabled (personal scope or
+ // personal org). Replaces the previous "Profiles" trailing action so the
+ // form view follows the second-level settings pattern.
+ const backToProfiles = shouldShowProfilesForScope ? (
+ <button
+ data-testid="llm-back-to-profiles"
+ type="button"
+ onClick={() => {
+ setInitialViewHint(null);
+ setShowProfiles(true);
+ }}
+ className="flex items-center gap-2 self-start text-sm text-gray-300 hover:text-white cursor-pointer"
+ >
+ <FaChevronLeft size={12} aria-hidden="true" />
+ {t(I18nKey.SETTINGS$BACK_TO_LLM_LIST)}
+ </button>
+ ) : null;
return (
<div className="flex flex-col gap-4">
@@ -529,7 +590,13 @@ export function LlmSettingsScreen({
]}
header={buildHeader}
buildPayload={buildPayload}
- extraDirty={profileName.trim() !== initialProfileName.trim()}
+ // The profile form can always be saved: it snapshots the current LLM
+ // config as a profile, and the name is optional β€” it falls back to a
+ // model-derived default in handleSaveSuccess. So don't gate Save on the
+ // settings fields being dirty. This matters in SaaS managed mode, where
+ // the model is fixed and there's no editable API key, leaving the form
+ // pristine and Save stuck disabled.
+ extraDirty={shouldShowProfilesForScope}
onSaveSuccess={handleSaveSuccess}
getInitialView={getInitialView}
forceShowAdvancedView
diff --git a/frontend/src/stores/model-store.ts b/frontend/src/stores/model-store.ts
index a47e87a533..ab4ea69137 100644
--- a/frontend/src/stores/model-store.ts
+++ b/frontend/src/stores/model-store.ts
@@ -15,6 +15,15 @@ export interface ModelListEntry {
interface ModelState {
entriesByConversation: Record<string, ModelListEntry[]>;
+ /**
+ * The profile most recently switched-to per conversation, set optimistically
+ * when a switch succeeds. The chat switch button reads this so it reflects
+ * the choice immediately and unambiguously β€” without waiting for the
+ * conversation record's `llm_model` to round-trip back (which can lag, and in
+ * SaaS collides when several managed profiles share the same `litellm_proxy/`
+ * model string).
+ */
+ activeProfileByConversation: Record<string, string>;
}
interface ModelActions {
@@ -36,6 +45,7 @@ export const useModelStore = create<ModelStore>()(
devtools(
(set) => ({
entriesByConversation: {},
+ activeProfileByConversation: {},
show: (conversationId, anchorEventId, profiles) =>
set((s) => ({
entriesByConversation: {
@@ -60,6 +70,10 @@ export const useModelStore = create<ModelStore>()(
},
],
},
+ activeProfileByConversation: {
+ ...s.activeProfileByConversation,
+ [conversationId]: profileName,
+ },
})),
}),
{ name: "ModelStore" },
diff --git a/frontend/src/types/v1/core/base/base.ts b/frontend/src/types/v1/core/base/base.ts
index 1ab4492174..a98c443ea2 100644
--- a/frontend/src/types/v1/core/base/base.ts
+++ b/frontend/src/types/v1/core/base/base.ts
@@ -33,7 +33,8 @@ type ObservationEventType =
| `${EventType}Observation`
| "TerminalObservation"
| "GlobObservation"
- | "GrepObservation";
+ | "GrepObservation"
+ | "SwitchLLMObservation";
export interface ActionBase<T extends ActionEventType = ActionEventType> {
kind: T;
diff --git a/frontend/src/types/v1/core/base/observation.ts b/frontend/src/types/v1/core/base/observation.ts
index ac2a90fdf2..259a6f1643 100644
--- a/frontend/src/types/v1/core/base/observation.ts
+++ b/frontend/src/types/v1/core/base/observation.ts
@@ -275,6 +275,29 @@ export interface GrepObservation extends ObservationBase<"GrepObservation"> {
truncated: boolean;
}
+export interface SwitchLLMObservation extends ObservationBase<"SwitchLLMObservation"> {
+ /**
+ * Content returned from the switch LLM tool.
+ */
+ content: Array<TextContent | ImageContent>;
+ /**
+ * Whether the profile switch resulted in an error.
+ */
+ is_error: boolean;
+ /**
+ * Name of the profile the agent attempted to activate.
+ */
+ profile_name: string;
+ /**
+ * Reason the agent gave for the switch.
+ */
+ reason: string | null;
+ /**
+ * Model configured by the activated profile, when available.
+ */
+ active_model: string | null;
+}
+
export type Observation =
| MCPToolObservation
| FinishObservation
@@ -287,4 +310,5 @@ export type Observation =
| TaskTrackerObservation
| PlanningFileEditorObservation
| GlobObservation
- | GrepObservation;
+ | GrepObservation
+ | SwitchLLMObservation;
diff --git a/frontend/src/types/v1/type-guards.ts b/frontend/src/types/v1/type-guards.ts
index 835a8092ea..a75fc69e4b 100644
--- a/frontend/src/types/v1/type-guards.ts
+++ b/frontend/src/types/v1/type-guards.ts
@@ -8,6 +8,7 @@ import {
PlanningFileEditorObservation,
TerminalObservation,
BrowserObservation,
+ SwitchLLMObservation,
BrowserNavigateAction,
} from "./core";
import { AgentErrorEvent } from "./core/events/observation-event";
@@ -187,6 +188,16 @@ export const isStatsConversationStateUpdateEvent = (
event: ConversationStateUpdateEvent,
): event is ConversationStateUpdateEventStats => event.key === "stats";
+/**
+ * Type guard function to check if an observation event is a SwitchLLMObservation
+ * (emitted when the agent switches its LLM via the built-in switch_llm tool).
+ */
+export const isSwitchLLMObservationEvent = (
+ event: OpenHandsEvent,
+): event is ObservationEvent<SwitchLLMObservation> =>
+ isObservationEvent(event) &&
+ event.observation.kind === "SwitchLLMObservation";
+
/**
* Type guard function to check if an event is a conversation error event
*/
diff --git a/openhands/app_server/app_conversation/app_conversation_router.py b/openhands/app_server/app_conversation/app_conversation_router.py
index bd6a33f80b..1366876094 100644
--- a/openhands/app_server/app_conversation/app_conversation_router.py
+++ b/openhands/app_server/app_conversation/app_conversation_router.py
@@ -74,6 +74,7 @@ from openhands.app_server.services.httpx_client_injector import (
set_httpx_client_keep_open,
)
from openhands.app_server.services.injector import InjectorState
+from openhands.app_server.settings.llm_profiles import resolve_profile_llm
from openhands.app_server.settings.settings_models import Settings
from openhands.app_server.settings.settings_router import LITE_LLM_API_URL
from openhands.app_server.user.specifiy_user_context import USER_CONTEXT_ATTR
@@ -83,7 +84,6 @@ from openhands.app_server.utils.dependencies import get_dependencies
from openhands.app_server.utils.docker_utils import (
replace_localhost_hostname_for_docker,
)
-from openhands.app_server.utils.llm import resolve_llm_base_url
from openhands.sdk.skills import KeywordTrigger, TaskTrigger
from openhands.sdk.workspace.remote.async_remote_workspace import AsyncRemoteWorkspace
@@ -627,16 +627,15 @@ async def switch_conversation_profile(
detail=f"Profile '{request.profile_name}' not found",
)
- # Mirror the activate_profile fixup so a profile with an empty base_url
- # picks up the provider default (e.g. the OpenHands LiteLLM proxy).
- profile_llm = profile_llm.model_copy(
- update={
- 'base_url': resolve_llm_base_url(
- model=profile_llm.model,
- base_url=profile_llm.base_url,
- managed_proxy_url=LITE_LLM_API_URL,
- ),
- }
+ # Resolve the saved profile for the agent server: provider-default base_url,
+ # plus the effective settings key when the profile carries none (managed
+ # profiles persist a masked key, so without this the agent server would hit
+ # the litellm proxy unauthenticated). Locally, profiles carry their own key.
+ settings_llm = getattr(user_settings.agent_settings, 'llm', None)
+ profile_llm = resolve_profile_llm(
+ profile_llm,
+ managed_proxy_url=LITE_LLM_API_URL,
+ fallback_api_key=getattr(settings_llm, 'api_key', None),
)
# The agent-server's LLM registry is first-write-wins by ``usage_id``:
diff --git a/openhands/app_server/app_conversation/live_status_app_conversation_service.py b/openhands/app_server/app_conversation/live_status_app_conversation_service.py
index 9eb5226cae..7dca1eaf6a 100644
--- a/openhands/app_server/app_conversation/live_status_app_conversation_service.py
+++ b/openhands/app_server/app_conversation/live_status_app_conversation_service.py
@@ -83,6 +83,7 @@ from openhands.app_server.sandbox.sandbox_service import SandboxService
from openhands.app_server.sandbox.sandbox_spec_service import SandboxSpecService
from openhands.app_server.services.injector import InjectorState
from openhands.app_server.services.jwt_service import JwtService
+from openhands.app_server.settings.llm_profiles import resolve_profile_llm
from openhands.app_server.user.user_context import UserContext
from openhands.app_server.user.user_models import UserInfo
from openhands.app_server.utils.docker_utils import (
@@ -96,10 +97,12 @@ from openhands.app_server.utils.llm_metadata import (
from openhands.sdk import Agent, AgentContext, LocalWorkspace
from openhands.sdk.hooks import HookConfig
from openhands.sdk.llm import LLM
+from openhands.sdk.llm.llm_profile_store import PROFILE_NAME_REGEX
from openhands.sdk.plugin import PluginSource
from openhands.sdk.secret import LookupSecret, StaticSecret
from openhands.sdk.settings import ACPAgentSettings
from openhands.sdk.subagent import get_registered_agent_definitions
+from openhands.sdk.tool.builtins import SwitchLLMTool
from openhands.sdk.utils.paging import page_iterator
from openhands.sdk.utils.redact import (
redact_api_key_literals,
@@ -281,6 +284,12 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
assert sandbox is not None
agent_server_url = self._get_agent_server_url(sandbox)
+ # Mirror the user's LLM profiles into the sandbox so the agent's
+ # built-in switch_llm tool can resolve them (in SaaS profiles live
+ # on the app-server, not the sandbox filesystem). Before conversation
+ # creation, so the tool is enabled; re-runs on every start/resume.
+ await self._seed_sandbox_profiles(agent_server_url, sandbox.session_api_key)
+
# Get the working dir
sandbox_spec = await self.sandbox_spec_service.get_sandbox_spec(
sandbox.sandbox_spec_id
@@ -774,6 +783,83 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
httpx_client=self.httpx_client,
)
+ async def _seed_sandbox_profiles(
+ self, agent_server_url: str, session_api_key: str | None
+ ) -> None:
+ """Mirror the user's saved LLM profiles into the sandbox profile store.
+
+ The agent's built-in ``switch_llm`` tool resolves profiles from the
+ sandbox filesystem; in SaaS they live on the app-server, so without this
+ the tool sees none. Upserts the current profiles (so adds/edits/renames
+ land) and prunes ones deleted on the app-server, keeping the sandbox in
+ sync. Best-effort: failures are logged, never raised, so they can't block
+ the conversation.
+ """
+ # Imported lazily: settings_router transitively imports this service, so
+ # a module-level import would be circular.
+ from openhands.app_server.settings.settings_router import LITE_LLM_API_URL
+
+ headers = {'X-Session-API-Key': session_api_key} if session_api_key else {}
+ base_url = f'{agent_server_url}/api/profiles'
+ try:
+ user = await self.user_context.get_user_info()
+ profiles = user.llm_profiles.profiles
+ settings_llm = getattr(user.agent_settings, 'llm', None)
+ fallback_api_key = getattr(settings_llm, 'api_key', None)
+ except Exception:
+ _logger.exception(
+ 'Failed to load profiles for sandbox %s', agent_server_url
+ )
+ return
+
+ # Upsert each profile independently so one failure can't dark the rest.
+ for name, profile_llm in profiles.items():
+ # Org profile names aren't character-restricted, so skip any the
+ # agent-server's store would reject β€” both to avoid a futile call and
+ # to keep an exotic name (e.g. ``..``) from path-injecting the api-key
+ # payload into a different request URL.
+ if not PROFILE_NAME_REGEX.match(name):
+ continue
+ try:
+ resolved = resolve_profile_llm(
+ profile_llm,
+ managed_proxy_url=LITE_LLM_API_URL,
+ fallback_api_key=fallback_api_key,
+ )
+ response = await self.httpx_client.post(
+ f'{base_url}/{name}',
+ json={
+ 'include_secrets': True,
+ 'llm': resolved.model_dump(
+ mode='json',
+ exclude_none=True,
+ context={'expose_secrets': True},
+ ),
+ },
+ headers=headers,
+ timeout=30.0,
+ )
+ response.raise_for_status()
+ except Exception:
+ _logger.warning(
+ 'Failed to seed LLM profile %r into sandbox', name, exc_info=True
+ )
+
+ # Prune profiles deleted/renamed on the app-server so the agent can't
+ # switch to a stale one. Independent best-effort.
+ try:
+ listed = await self.httpx_client.get(
+ base_url, headers=headers, timeout=30.0
+ )
+ listed.raise_for_status()
+ stored = {p['name'] for p in listed.json().get('profiles', [])}
+ for stale_name in stored - set(profiles):
+ await self.httpx_client.delete(
+ f'{base_url}/{stale_name}', headers=headers, timeout=30.0
+ )
+ except Exception:
+ _logger.warning('Failed to prune sandbox profiles', exc_info=True)
+
def _get_agent_server_url(self, sandbox: SandboxInfo) -> str:
"""Get agent server url for running sandbox."""
exposed_urls = sandbox.exposed_urls
@@ -1362,6 +1448,30 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
}
)
agent = configured_agent_settings.create_agent()
+
+ # SaaS profiles live on the user/org record, not the sandbox
+ # filesystem, so we attach the agent's built-in switch_llm tool
+ # ourselves rather than relying on create_agent()'s gating. Enabled
+ # whenever there are at least two valid saved profiles (a switch needs
+ # a target).
+ valid_profile_names = [
+ name
+ for name in user.llm_profiles.profiles
+ if PROFILE_NAME_REGEX.match(name)
+ ]
+ if (
+ len(valid_profile_names) >= 2
+ and SwitchLLMTool.__name__ not in agent.include_default_tools
+ ):
+ agent = agent.model_copy(
+ update={
+ 'include_default_tools': [
+ *agent.include_default_tools,
+ SwitchLLMTool.__name__,
+ ]
+ }
+ )
+
agent = self._apply_server_agent_overrides(
agent, agent_type, mcp_config, conversation_id, user.id
)
diff --git a/openhands/app_server/event_callback/webhook_router.py b/openhands/app_server/event_callback/webhook_router.py
index 7ca3926a98..f313b79a52 100644
--- a/openhands/app_server/event_callback/webhook_router.py
+++ b/openhands/app_server/event_callback/webhook_router.py
@@ -51,7 +51,8 @@ from openhands.app_server.user_auth.user_auth import (
get_for_user as get_user_auth_for_user,
)
from openhands.sdk import ConversationExecutionStatus, Event
-from openhands.sdk.event import ConversationStateUpdateEvent
+from openhands.sdk.event import ConversationStateUpdateEvent, ObservationEvent
+from openhands.sdk.tool.builtins import SwitchLLMObservation
router = APIRouter(prefix='/webhooks', tags=['Webhooks'])
event_service_dependency = depends_event_service()
@@ -426,6 +427,29 @@ async def on_event(
event, conversation_id
)
+ # Reflect an agent-initiated LLM switch (via the built-in SwitchLLMTool)
+ # on the conversation record. The tool emits a ``SwitchLLMObservation``
+ # carrying the new ``active_model``; unlike the explicit switch_profile
+ # route, nothing else persists it here, so the chat header and
+ # switch-profile button would otherwise stay stale until the next full
+ # conversation-info webhook (which only fires on start/pause/interrupt/
+ # delete, never mid-run). ``active_model`` is only set on success.
+ switched_model: str | None = None
+ for event in events:
+ if (
+ isinstance(event, ObservationEvent)
+ and isinstance(event.observation, SwitchLLMObservation)
+ and event.observation.active_model
+ ):
+ switched_model = event.observation.active_model
+ if switched_model and app_conversation_info.llm_model != switched_model:
+ info = await app_conversation_info_service.get_app_conversation_info(
+ conversation_id
+ )
+ if info is not None and info.llm_model != switched_model:
+ info.llm_model = switched_model
+ await app_conversation_info_service.save_app_conversation_info(info)
+
# Analytics: conversation terminal state detection
for event in events:
if not isinstance(event, ConversationStateUpdateEvent):
diff --git a/openhands/app_server/settings/llm_profiles.py b/openhands/app_server/settings/llm_profiles.py
index 189ae4b5e3..452f24436f 100644
--- a/openhands/app_server/settings/llm_profiles.py
+++ b/openhands/app_server/settings/llm_profiles.py
@@ -14,6 +14,7 @@ from pydantic import (
model_validator,
)
+from openhands.app_server.utils.llm import resolve_llm_base_url
from openhands.app_server.utils.logger import openhands_logger as logger
from openhands.sdk.llm import LLM
@@ -33,6 +34,34 @@ def has_real_api_key(api_key: Any) -> bool:
return bool(secret_value and secret_value.strip())
+def resolve_profile_llm(
+ profile_llm: LLM,
+ *,
+ managed_proxy_url: str,
+ fallback_api_key: Any = None,
+) -> LLM:
+ """Resolve a saved profile's LLM for activation on the agent server.
+
+ Fills the provider-default ``base_url`` when the profile saved none, and
+ falls back to ``fallback_api_key`` (the user's effective settings key) when
+ the profile carries no real key. Managed profiles persist a masked key, so
+ without the fallback the agent server would call the LiteLLM proxy with no
+ credentials; BYOR profiles keep their own key (the fallback is skipped).
+ """
+ resolved = profile_llm.model_copy(
+ update={
+ 'base_url': resolve_llm_base_url(
+ model=profile_llm.model,
+ base_url=profile_llm.base_url,
+ managed_proxy_url=managed_proxy_url,
+ )
+ }
+ )
+ if not has_real_api_key(resolved.api_key) and has_real_api_key(fallback_api_key):
+ resolved = resolved.model_copy(update={'api_key': fallback_api_key})
+ return resolved
+
+
# 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
@@ -141,18 +170,31 @@ class LLMProfiles(BaseModel):
def has(self, name: str) -> bool:
return name in self.profiles
- def summaries(self) -> list[dict[str, Any]]:
+ def summaries(
+ self, *, managed_proxy_url: str | None = None
+ ) -> 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.
+
+ When ``managed_proxy_url`` is provided, ``base_url`` is resolved to the
+ value the profile will actually use at runtime β€” e.g. the managed proxy
+ for a ``litellm_proxy/`` model saved without one β€” so callers display
+ the effective endpoint instead of an empty value.
"""
return [
{
'name': name,
'model': llm.model,
- 'base_url': llm.base_url,
+ 'base_url': (
+ resolve_llm_base_url(
+ llm.model, llm.base_url, managed_proxy_url=managed_proxy_url
+ )
+ if managed_proxy_url is not None
+ else llm.base_url
+ ),
'api_key_set': has_real_api_key(llm.api_key),
}
for name, llm in self.profiles.items()
diff --git a/openhands/app_server/settings/settings_router.py b/openhands/app_server/settings/settings_router.py
index 1c3d3a8371..033c18bca1 100644
--- a/openhands/app_server/settings/settings_router.py
+++ b/openhands/app_server/settings/settings_router.py
@@ -431,7 +431,10 @@ async def list_profiles(
return ProfileListResponse(profiles=[], active_profile=None)
return ProfileListResponse(
- profiles=[ProfileInfo(**p) for p in settings.llm_profiles.summaries()],
+ profiles=[
+ ProfileInfo(**p)
+ for p in settings.llm_profiles.summaries(managed_proxy_url=LITE_LLM_API_URL)
+ ],
active_profile=settings.llm_profiles.active,
)
diff --git a/tests/unit/app_server/test_app_conversation_router.py b/tests/unit/app_server/test_app_conversation_router.py
index 29cc5a6e54..01e56c9b09 100644
--- a/tests/unit/app_server/test_app_conversation_router.py
+++ b/tests/unit/app_server/test_app_conversation_router.py
@@ -29,6 +29,7 @@ from openhands.app_server.sandbox.sandbox_models import SandboxStatus
from openhands.app_server.settings.llm_profiles import LLMProfiles
from openhands.app_server.settings.settings_models import Settings
from openhands.sdk.llm import LLM
+from openhands.sdk.settings import OpenHandsAgentSettings
def _make_mock_app_conversation(
@@ -398,6 +399,28 @@ def _make_settings_with_profile(
return Settings(llm_profiles=LLMProfiles(profiles={profile_name: llm}))
+def _make_settings_for_switch(
+ profile_name: str = 'managed',
+ model: str = 'litellm_proxy/minimax-m2.7',
+ profile_api_key: str | None = None,
+ settings_api_key: str | None = 'managed-proxy-key',
+) -> Settings:
+ """Build Settings where the profile and the effective agent settings carry
+ independent keys, so the switch endpoint's api_key fallback can be tested.
+
+ In SaaS the managed profile persists no key (``profile_api_key=None``) while
+ the effective ``agent_settings.llm.api_key`` holds the resolved managed key.
+ """
+ return Settings(
+ agent_settings=OpenHandsAgentSettings(
+ llm=LLM(model=model, api_key=settings_api_key)
+ ),
+ llm_profiles=LLMProfiles(
+ profiles={profile_name: LLM(model=model, api_key=profile_api_key)}
+ ),
+ )
+
+
def _make_agent_server_context(
conversation_id, llm_model: str | None = 'openai/old-model'
) -> AgentServerContext:
@@ -633,6 +656,83 @@ class TestSwitchConversationProfile:
assert post_kwargs['json']['llm']['model'] == new_model
assert post_kwargs['json']['llm']['usage_id'].startswith('profile:gpt-5:')
+ async def test_falls_back_to_settings_api_key_when_profile_has_none(self):
+ """SaaS: managed profiles persist no key, so the switch must source the
+ effective ``agent_settings.llm.api_key`` β€” otherwise the agent server
+ calls the litellm proxy unauthenticated and the request 401s.
+ """
+ conv_id = uuid4()
+ settings = _make_settings_for_switch(
+ profile_name='managed',
+ profile_api_key=None,
+ settings_api_key='managed-proxy-key',
+ )
+ ctx = _make_agent_server_context(conv_id)
+ ok_response = MagicMock()
+ ok_response.status_code = 200
+ ok_response.raise_for_status = MagicMock()
+ client = _make_httpx_client(post_return=ok_response)
+ info_service = MagicMock()
+ info_service.get_app_conversation_info = AsyncMock(return_value=None)
+ info_service.save_app_conversation_info = AsyncMock()
+
+ with patch(
+ 'openhands.app_server.app_conversation.app_conversation_router.'
+ '_get_agent_server_context',
+ new=AsyncMock(return_value=ctx),
+ ):
+ await switch_conversation_profile(
+ conversation_id=conv_id,
+ request=SwitchProfileRequest(profile_name='managed'),
+ user_settings=settings,
+ app_conversation_service=MagicMock(),
+ app_conversation_info_service=info_service,
+ sandbox_service=MagicMock(),
+ sandbox_spec_service=MagicMock(),
+ httpx_client=client,
+ )
+
+ post_kwargs = client.post.await_args.kwargs
+ assert post_kwargs['json']['llm']['api_key'] == 'managed-proxy-key'
+
+ async def test_keeps_profile_api_key_when_profile_has_one(self):
+ """A profile that carries its own key (BYOR / local GUI) is used as-is
+ and never overridden by the settings fallback.
+ """
+ conv_id = uuid4()
+ settings = _make_settings_for_switch(
+ profile_name='managed',
+ profile_api_key='byor-key',
+ settings_api_key='should-not-be-used',
+ )
+ ctx = _make_agent_server_context(conv_id)
+ ok_response = MagicMock()
+ ok_response.status_code = 200
+ ok_response.raise_for_status = MagicMock()
+ client = _make_httpx_client(post_return=ok_response)
+ info_service = MagicMock()
+ info_service.get_app_conversation_info = AsyncMock(return_value=None)
+ info_service.save_app_conversation_info = AsyncMock()
+
+ with patch(
+ 'openhands.app_server.app_conversation.app_conversation_router.'
+ '_get_agent_server_context',
+ new=AsyncMock(return_value=ctx),
+ ):
+ await switch_conversation_profile(
+ conversation_id=conv_id,
+ request=SwitchProfileRequest(profile_name='managed'),
+ user_settings=settings,
+ app_conversation_service=MagicMock(),
+ app_conversation_info_service=info_service,
+ sandbox_service=MagicMock(),
+ sandbox_spec_service=MagicMock(),
+ httpx_client=client,
+ )
+
+ post_kwargs = client.post.await_args.kwargs
+ assert post_kwargs['json']['llm']['api_key'] == 'byor-key'
+
async def test_success_skips_persist_when_model_unchanged(self):
"""If the conversation already records the new model, save is skipped."""
conv_id = uuid4()
diff --git a/tests/unit/app_server/test_live_status_app_conversation_service.py b/tests/unit/app_server/test_live_status_app_conversation_service.py
index 51f36bc8da..0419088f0c 100644
--- a/tests/unit/app_server/test_live_status_app_conversation_service.py
+++ b/tests/unit/app_server/test_live_status_app_conversation_service.py
@@ -36,6 +36,7 @@ from openhands.app_server.sandbox.sandbox_models import (
SandboxStatus,
)
from openhands.app_server.sandbox.sandbox_spec_models import SandboxSpecInfo
+from openhands.app_server.settings.llm_profiles import LLMProfiles
from openhands.app_server.settings.settings_models import (
SandboxGroupingStrategy,
Settings,
@@ -82,6 +83,19 @@ class _TestUserInfo(SimpleNamespace):
def agent_settings(self, value):
object.__setattr__(self, '_agent_settings_override', value)
+ @property
+ def llm_profiles(self) -> LLMProfiles:
+ # Real UserInfo always carries llm_profiles; default to empty unless a
+ # test sets profiles.
+ override = getattr(self, '_llm_profiles_override', None)
+ if override is not None:
+ return override
+ return LLMProfiles(profiles={})
+
+ @llm_profiles.setter
+ def llm_profiles(self, value):
+ object.__setattr__(self, '_llm_profiles_override', value)
+
@property
def conversation_settings(self) -> ConversationSettings:
kwargs: dict = {
@@ -183,6 +197,61 @@ class TestLiveStatusAppConversationService:
# Tests that specifically test hooks loading can override this mock
self.service._load_hooks_from_workspace = AsyncMock(return_value=None)
+ @pytest.mark.asyncio
+ async def test_seed_sandbox_profiles_upserts_resolved_keys_and_prunes(self):
+ """Pushes each profile to the sandbox with its key resolved (managed key
+ injected, BYOR key kept), then deletes profiles that no longer exist on
+ the app-server.
+ """
+ user = SimpleNamespace(
+ llm_profiles=LLMProfiles(
+ profiles={
+ 'Managed': LLM(model='litellm_proxy/minimax-m2.7', usage_id='p'),
+ 'BYOR': LLM(
+ model='anthropic/claude-sonnet-4-6',
+ api_key='byor-key',
+ usage_id='p',
+ ),
+ # Org names aren't character-restricted; this one must be
+ # skipped so it can't path-inject the request URL.
+ '../evil': LLM(model='openai/gpt-4o', usage_id='p'),
+ }
+ ),
+ agent_settings=SimpleNamespace(
+ llm=SimpleNamespace(api_key=SecretStr('managed-key'))
+ ),
+ )
+ self.mock_user_context.get_user_info = AsyncMock(return_value=user)
+
+ ok = Mock(raise_for_status=Mock())
+ listing = Mock(raise_for_status=Mock())
+ listing.json = Mock(
+ return_value={
+ 'profiles': [{'name': 'Managed'}, {'name': 'BYOR'}, {'name': 'Gone'}]
+ }
+ )
+ self.mock_httpx_client.post = AsyncMock(return_value=ok)
+ self.mock_httpx_client.get = AsyncMock(return_value=listing)
+ self.mock_httpx_client.delete = AsyncMock(return_value=ok)
+
+ await self.service._seed_sandbox_profiles('http://agent.test', 'sess-key')
+
+ base = 'http://agent.test/api/profiles'
+ pushed = {
+ call.args[0]: call.kwargs['json']['llm']
+ for call in self.mock_httpx_client.post.call_args_list
+ }
+ # Managed profile (no stored key) falls back to the effective key; BYOR
+ # keeps its own.
+ assert pushed[f'{base}/Managed']['api_key'] == 'managed-key'
+ assert pushed[f'{base}/BYOR']['api_key'] == 'byor-key'
+ # The unsafe-named profile is skipped entirely (never POSTed).
+ assert self.mock_httpx_client.post.await_count == 2
+ assert not any('evil' in url for url in pushed)
+ # The profile deleted on the app-server is pruned from the sandbox.
+ self.mock_httpx_client.delete.assert_awaited_once()
+ assert self.mock_httpx_client.delete.await_args.args[0] == f'{base}/Gone'
+
def test_apply_suggested_task_sets_prompt_and_trigger(self):
"""Test suggested task prompts populate initial message and trigger."""
suggested_task = SuggestedTask(
diff --git a/tests/unit/storage/data_models/test_llm_profiles.py b/tests/unit/storage/data_models/test_llm_profiles.py
index b712a8134e..21714c356d 100644
--- a/tests/unit/storage/data_models/test_llm_profiles.py
+++ b/tests/unit/storage/data_models/test_llm_profiles.py
@@ -83,6 +83,27 @@ def test_summaries_empty_by_default():
assert LLMProfiles().summaries() == []
+def test_summaries_resolves_base_url_with_managed_proxy_url():
+ profiles = LLMProfiles()
+ # Managed model saved without a base_url (would otherwise display as "β€”").
+ profiles.save('managed', LLM(model='litellm_proxy/minimax-m2.7'))
+ # BYOR model with its own base_url.
+ profiles.save(
+ 'byor', LLM(model='openai/gpt-4o', base_url='https://byor.example.com')
+ )
+
+ resolved = {
+ s['name']: s for s in profiles.summaries(managed_proxy_url='https://proxy.test')
+ }
+ # The managed profile resolves to the proxy it will actually use.
+ assert resolved['managed']['base_url'] == 'https://proxy.test'
+ # The BYOR profile keeps its own base_url.
+ assert resolved['byor']['base_url'] == 'https://byor.example.com'
+
+ # Without the proxy url, base_url is returned raw (None for the managed one).
+ assert {s['name']: s['base_url'] for s in profiles.summaries()}['managed'] is None
+
+
# ── Mutations ─────────────────────────────────────────────────────