Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat(settings): use from_persisted for stored settings (#14126)

Graham Neubig60f5c1cf4ab4
diff --git a/containers/dev/compose.yml b/containers/dev/compose.yml
index 89512c4934..889ebd8e05 100644
--- a/containers/dev/compose.yml
+++ b/containers/dev/compose.yml
@@ -13,7 +13,7 @@ services:
- DOCKER_HOST_ADDR=host.docker.internal
#
- AGENT_SERVER_IMAGE_REPOSITORY=${AGENT_SERVER_IMAGE_REPOSITORY:-ghcr.io/openhands/agent-server}
- - AGENT_SERVER_IMAGE_TAG=${AGENT_SERVER_IMAGE_TAG:-1.15.0-python}
+ - AGENT_SERVER_IMAGE_TAG=${AGENT_SERVER_IMAGE_TAG:-1.19.1-python}
- SANDBOX_USER_ID=${SANDBOX_USER_ID:-1234}
- WORKSPACE_MOUNT_PATH=${WORKSPACE_BASE:-$PWD/workspace}
ports:
diff --git a/dev_config/python/.pre-commit-config.yaml b/dev_config/python/.pre-commit-config.yaml
index 8e89931889..490e85caa1 100644
--- a/dev_config/python/.pre-commit-config.yaml
+++ b/dev_config/python/.pre-commit-config.yaml
@@ -58,8 +58,8 @@ repos:
types-Markdown,
pydantic,
lxml,
- "openhands-sdk==1.17.0",
- "openhands-tools==1.17.0",
+ "openhands-sdk==1.19.1",
+ "openhands-tools==1.19.1",
"sqlalchemy>=2.0",
]
# To see gaps add `--html-report mypy-report/`
diff --git a/docker-compose.yml b/docker-compose.yml
index 23d353621a..148d3a1b85 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -8,7 +8,7 @@ services:
container_name: openhands-app-${DATE:-}
environment:
- AGENT_SERVER_IMAGE_REPOSITORY=${AGENT_SERVER_IMAGE_REPOSITORY:-ghcr.io/openhands/agent-server}
- - AGENT_SERVER_IMAGE_TAG=${AGENT_SERVER_IMAGE_TAG:-1.15.0-python}
+ - AGENT_SERVER_IMAGE_TAG=${AGENT_SERVER_IMAGE_TAG:-1.19.1-python}
#- SANDBOX_USER_ID=${SANDBOX_USER_ID:-1234} # enable this only if you want a specific non-root sandbox user but you will have to manually adjust permissions of ~/.openhands for this user
- WORKSPACE_MOUNT_PATH=${WORKSPACE_BASE:-$PWD/workspace}
ports:
diff --git a/enterprise/server/routes/org_models.py b/enterprise/server/routes/org_models.py
index 3410701ab4..5e724f7e77 100644
--- a/enterprise/server/routes/org_models.py
+++ b/enterprise/server/routes/org_models.py
@@ -14,6 +14,10 @@ from storage.org import Org
from storage.org_member import OrgMember
from storage.role import Role
+from openhands.app_server.settings.settings_models import (
+ _load_persisted_agent_settings,
+ _load_persisted_conversation_settings,
+)
from openhands.app_server.utils.llm import MASKED_API_KEY, resolve_llm_base_url
from openhands.sdk.settings import ConversationSettings, OpenHandsAgentSettings
@@ -23,14 +27,18 @@ def _validate_persisted_agent_settings(
) -> OpenHandsAgentSettings:
"""Validate persisted ``org.agent_settings`` against the canonical schema.
- Older rows carry the legacy ``agent_kind: 'llm'`` discriminator from the
- pre-rename SDK; force ``'openhands'`` so the canonical class accepts both
- shapes. Mirrors :func:`OrgStore.get_agent_settings_from_org` β€” kept inline
- to avoid a circular import (``org_store`` already imports from this module).
+ Routes the raw payload through the shared SDK loader so any schema
+ migrations registered with the SDK are applied first. Older rows carry
+ the legacy ``agent_kind: 'llm'`` discriminator from the pre-rename SDK;
+ force ``'openhands'`` after migration so the canonical class accepts
+ both shapes. Mirrors :func:`OrgStore.get_agent_settings_from_org` β€” kept
+ inline to avoid a circular import (``org_store`` already imports from this
+ module).
"""
- kwargs = dict(raw) if raw else {}
- kwargs['agent_kind'] = 'openhands'
- return OpenHandsAgentSettings.model_validate(kwargs)
+ loaded = _load_persisted_agent_settings(raw or {})
+ payload = loaded.model_dump(mode='json', context={'expose_secrets': True})
+ payload['agent_kind'] = 'openhands'
+ return OpenHandsAgentSettings.model_validate(payload)
class OrgCreationError(Exception):
@@ -203,8 +211,8 @@ class OrgResponse(BaseModel):
sandbox_runtime_container_image=org.sandbox_runtime_container_image,
org_version=org.org_version if org.org_version is not None else 0,
agent_settings=_validate_persisted_agent_settings(org.agent_settings),
- conversation_settings=ConversationSettings.model_validate(
- dict(org.conversation_settings) if org.conversation_settings else {}
+ conversation_settings=_load_persisted_conversation_settings(
+ org.conversation_settings
),
search_api_key=None,
sandbox_api_key=None,
@@ -423,8 +431,8 @@ class OrgDefaultsSettingsResponse(BaseModel):
cls._denormalize_llm_for_response(agent_settings)
return cls(
agent_settings=agent_settings,
- conversation_settings=ConversationSettings.model_validate(
- dict(org.conversation_settings) if org.conversation_settings else {}
+ conversation_settings=_load_persisted_conversation_settings(
+ org.conversation_settings
),
llm_api_key_set=org.llm_api_key is not None,
search_api_key=cls._mask_key(org.search_api_key),
diff --git a/enterprise/storage/org_store.py b/enterprise/storage/org_store.py
index 1557e6d0b6..4dd8c6cd3c 100644
--- a/enterprise/storage/org_store.py
+++ b/enterprise/storage/org_store.py
@@ -24,7 +24,11 @@ from storage.org_member import OrgMember
from storage.user import User
from storage.user_settings import UserSettings
-from openhands.app_server.settings.settings_models import Settings
+from openhands.app_server.settings.settings_models import (
+ Settings,
+ _load_persisted_agent_settings,
+ _load_persisted_conversation_settings,
+)
from openhands.app_server.utils.jsonpatch_compat import deep_merge
from openhands.app_server.utils.llm import is_openhands_model
from openhands.app_server.utils.logger import openhands_logger as logger
@@ -50,15 +54,19 @@ class OrgStore:
@staticmethod
def get_agent_settings_from_org(org: Org) -> OpenHandsAgentSettings:
- kwargs = dict(org.agent_settings)
-
- # Some saved entries have 'llm' in here which is invalid.
- kwargs['agent_kind'] = 'openhands'
- return OpenHandsAgentSettings.model_validate(kwargs)
+ # Apply persisted-settings migrations via the shared SDK loader,
+ # then coerce the legacy ``agent_kind: 'llm'`` discriminator onto
+ # the canonical class. Some saved entries still carry that
+ # pre-rename shape and would otherwise validate as
+ # ``LLMAgentSettings``.
+ loaded = _load_persisted_agent_settings(dict(org.agent_settings))
+ payload = loaded.model_dump(mode='json', context={'expose_secrets': True})
+ payload['agent_kind'] = 'openhands'
+ return OpenHandsAgentSettings.model_validate(payload)
@staticmethod
def get_conversation_settings_from_org(org: Org) -> ConversationSettings:
- return ConversationSettings.model_validate(dict(org.conversation_settings))
+ return _load_persisted_conversation_settings(dict(org.conversation_settings))
@staticmethod
def sync_agent_settings(org: Org) -> None:
@@ -247,9 +255,27 @@ class OrgStore:
settings_diff: dict[str, Any],
settings_type: type[OpenHandsAgentSettings] | type[ConversationSettings],
) -> OpenHandsAgentSettings | ConversationSettings:
- """Deep-merge a sparse settings diff and validate the merged result."""
- merged_settings = deep_merge(current_settings or {}, settings_diff)
- return settings_type.model_validate(merged_settings)
+ """Deep-merge a sparse settings diff and validate the merged result.
+
+ The persisted base is routed through the SDK ``from_persisted`` loader
+ first so any registered schema migrations are applied before the diff
+ is merged. Agent settings additionally coerce the legacy
+ ``agent_kind: 'llm'`` discriminator onto the canonical class.
+ """
+ if settings_type is OpenHandsAgentSettings:
+ base_settings = _load_persisted_agent_settings(current_settings or {})
+ merged_settings = deep_merge(
+ base_settings.model_dump(mode='json', context={'expose_secrets': True}),
+ settings_diff,
+ )
+ merged_settings['agent_kind'] = 'openhands'
+ return OpenHandsAgentSettings.model_validate(merged_settings)
+
+ base_settings = _load_persisted_conversation_settings(current_settings)
+ merged_settings = deep_merge(
+ base_settings.model_dump(mode='json'), settings_diff
+ )
+ return ConversationSettings.model_validate(merged_settings)
@staticmethod
async def update_org(
diff --git a/enterprise/storage/user_settings.py b/enterprise/storage/user_settings.py
index b687e42466..17a2f416fc 100644
--- a/enterprise/storage/user_settings.py
+++ b/enterprise/storage/user_settings.py
@@ -86,11 +86,8 @@ class UserSettings(Base):
def to_settings(self):
from openhands.app_server.settings.settings_models import Settings
- from openhands.sdk.settings import AgentSettings, ConversationSettings
return Settings(
- agent_settings=AgentSettings.model_validate(self.agent_settings or {}),
- conversation_settings=ConversationSettings.model_validate(
- self.conversation_settings or {}
- ),
+ agent_settings=self.agent_settings or {},
+ conversation_settings=self.conversation_settings or {},
)
diff --git a/enterprise/tests/unit/test_org_store.py b/enterprise/tests/unit/test_org_store.py
index 13a7337e38..7ddbccaef4 100644
--- a/enterprise/tests/unit/test_org_store.py
+++ b/enterprise/tests/unit/test_org_store.py
@@ -134,6 +134,31 @@ async def test_update_org(async_session_maker, mock_litellm_api):
assert agent_settings.llm.model == 'litellm_proxy/claude-3'
+def test_get_org_settings_from_org_use_persisted_loaders():
+ org = MagicMock(spec=Org)
+ org.agent_settings = {'legacy': True}
+ org.conversation_settings = {'legacy': True}
+
+ loaded_agent_settings = OpenHandsAgentSettings(agent='MigratedAgent')
+ loaded_conversation_settings = ConversationSettings(max_iterations=77)
+
+ with (
+ patch(
+ 'storage.org_store._load_persisted_agent_settings',
+ return_value=loaded_agent_settings,
+ ) as agent_loader,
+ patch(
+ 'storage.org_store._load_persisted_conversation_settings',
+ return_value=loaded_conversation_settings,
+ ) as conversation_loader,
+ ):
+ assert OrgStore.get_agent_settings_from_org(org).agent == 'MigratedAgent'
+ assert OrgStore.get_conversation_settings_from_org(org).max_iterations == 77
+
+ agent_loader.assert_called_once_with({'legacy': True})
+ conversation_loader.assert_called_once_with({'legacy': True})
+
+
@pytest.mark.asyncio
async def test_update_org_not_found(async_session_maker):
# Test updating org that doesn't exist
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 0fd378bf15..b2667e0d95 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
@@ -1028,6 +1028,9 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
mcp_servers: Dictionary to add servers to
user: User information containing custom MCP config
"""
+ if isinstance(user.agent_settings, ACPAgentSettings):
+ return
+
sdk_mcp = user.agent_settings.mcp_config
if not sdk_mcp or not sdk_mcp.mcpServers:
return
diff --git a/openhands/app_server/settings/settings_models.py b/openhands/app_server/settings/settings_models.py
index bb7a3dd1ac..aa77b7afae 100644
--- a/openhands/app_server/settings/settings_models.py
+++ b/openhands/app_server/settings/settings_models.py
@@ -31,6 +31,7 @@ from openhands.app_server.settings.llm_profiles import LLMProfiles
from openhands.app_server.utils.jsonpatch_compat import deep_merge
from openhands.sdk.settings import (
ACPAgentSettings,
+ AgentSettings,
AgentSettingsConfig,
ConversationSettings,
OpenHandsAgentSettings,
@@ -59,6 +60,23 @@ def _coerce_dict_secrets(d: dict[str, Any]) -> dict[str, Any]:
return out
+def _load_persisted_agent_settings(
+ data: Any,
+) -> OpenHandsAgentSettings | ACPAgentSettings:
+ """Load persisted agent settings via the SDK loader.
+
+ Routes the raw payload through :meth:`AgentSettings.from_persisted` so any
+ schema migrations registered with the SDK are applied before validation
+ against the discriminated :data:`AgentSettingsConfig` union.
+ """
+ return AgentSettings.from_persisted(data or {})
+
+
+def _load_persisted_conversation_settings(data: Any) -> ConversationSettings:
+ """Load persisted conversation settings via the SDK loader."""
+ return ConversationSettings.from_persisted(data or {})
+
+
class SandboxGroupingStrategy(str, Enum):
"""Strategy for grouping conversations within sandboxes."""
@@ -313,7 +331,9 @@ class Settings(BaseModel):
# --- Agent settings: coerce SecretStr leaves to plain strings ---
agent_settings = data.get('agent_settings')
if isinstance(agent_settings, dict):
- data['agent_settings'] = _coerce_dict_secrets(agent_settings)
+ data['agent_settings'] = _load_persisted_agent_settings(
+ _coerce_dict_secrets(agent_settings)
+ ).model_dump(mode='json', context={'expose_secrets': True})
elif isinstance(agent_settings, (OpenHandsAgentSettings, ACPAgentSettings)):
data['agent_settings'] = agent_settings.model_dump(
mode='json', context={'expose_secrets': True}
@@ -321,7 +341,11 @@ class Settings(BaseModel):
# --- Conversation settings: normalize ---
conversation_settings = data.get('conversation_settings')
- if isinstance(conversation_settings, ConversationSettings):
+ if isinstance(conversation_settings, dict):
+ data['conversation_settings'] = _load_persisted_conversation_settings(
+ conversation_settings
+ ).model_dump(mode='json')
+ elif isinstance(conversation_settings, ConversationSettings):
data['conversation_settings'] = conversation_settings.model_dump(
mode='json'
)
diff --git a/tests/unit/storage/data_models/test_settings.py b/tests/unit/storage/data_models/test_settings.py
index 2b2217c346..2ed4cc0010 100644
--- a/tests/unit/storage/data_models/test_settings.py
+++ b/tests/unit/storage/data_models/test_settings.py
@@ -1,5 +1,6 @@
import importlib
import warnings
+from unittest.mock import patch
import pytest
from fastmcp.mcp_config import MCPConfig
@@ -42,6 +43,33 @@ def test_settings_handles_sensitive_data():
assert llm_api_key.get_secret_value() == 'test-key'
+def test_settings_loads_persisted_settings_via_from_persisted():
+ loaded_agent_settings = AgentSettings(agent='migrated-agent')
+ loaded_conversation_settings = ConversationSettings(max_iterations=77)
+
+ with (
+ patch.object(
+ AgentSettings,
+ 'from_persisted',
+ return_value=loaded_agent_settings,
+ ) as agent_loader,
+ patch.object(
+ ConversationSettings,
+ 'from_persisted',
+ return_value=loaded_conversation_settings,
+ ) as conversation_loader,
+ ):
+ settings = Settings(
+ agent_settings={'legacy': True},
+ conversation_settings={'legacy': True},
+ )
+
+ agent_loader.assert_called_once_with({'legacy': True})
+ conversation_loader.assert_called_once_with({'legacy': True})
+ assert settings.agent_settings.agent == 'migrated-agent'
+ assert settings.conversation_settings.max_iterations == 77
+
+
def test_settings_update_deep_merges_agent_settings():
"""Updating agent_settings with a partial dict must not overwrite sibling sub-fields."""
settings = Settings(