Split SDK conversation settings from agent settings

Co-authored-by: openhands <openhands@all-hands.dev>

Author: openhands-agent

openhands-agent-server/openhands/agent_server/event_service.py

@@ -498,8 +498,8 @@ async def start(self):
             tags=self.stored.tags,
         )
 
-        # Set confirmation mode if enabled
         conversation.set_confirmation_policy(self.stored.confirmation_policy)
+        conversation.set_security_analyzer(self.stored.security_analyzer)
         self._conversation = conversation
 
         # Register state change callback to automatically publish updates

openhands-agent-server/openhands/agent_server/models.py

@@ -7,7 +7,14 @@
 from pydantic import BaseModel, Discriminator, Field, Tag, field_validator
 
 from openhands.agent_server.utils import OpenHandsUUID, utc_now
-from openhands.sdk import LLM, Agent, ImageContent, Message, TextContent
+from openhands.sdk import (
+    LLM,
+    Agent,
+    ConversationSettings,
+    ImageContent,
+    Message,
+    TextContent,
+)
 from openhands.sdk.agent.acp_agent import ACPAgent
 from openhands.sdk.conversation.conversation_stats import ConversationStats
 from openhands.sdk.conversation.secret_registry import SecretRegistry
@@ -105,6 +112,10 @@ class _StartConversationRequestBase(BaseModel):
         description="Controls when the conversation will prompt the user before "
         "continuing. Defaults to never.",
     )
+    security_analyzer: SecurityAnalyzerBase | None = Field(
+        default=None,
+        description="Optional security analyzer to evaluate action risks.",
+    )
     initial_message: SendMessageRequest | None = Field(
         default=None, description="Initial message to pass to the LLM"
     )
@@ -181,12 +192,42 @@ class StartConversationRequest(_StartConversationRequestBase):
 
     agent: Agent
 
+    @classmethod
+    def from_settings(
+        cls,
+        *,
+        agent: Agent,
+        workspace: LocalWorkspace,
+        conversation_settings: ConversationSettings | None = None,
+        **kwargs: Any,
+    ) -> "StartConversationRequest":
+        payload = dict(kwargs)
+        if conversation_settings is not None:
+            for key, value in conversation_settings.to_start_request_kwargs().items():
+                payload.setdefault(key, value)
+        return cls(agent=agent, workspace=workspace, **payload)
+
 
 class StartACPConversationRequest(_StartConversationRequestBase):
     """Payload to create a conversation with ACP-capable agent support."""
 
     agent: ACPEnabledAgent
 
+    @classmethod
+    def from_settings(
+        cls,
+        *,
+        agent: ACPEnabledAgent,
+        workspace: LocalWorkspace,
+        conversation_settings: ConversationSettings | None = None,
+        **kwargs: Any,
+    ) -> "StartACPConversationRequest":
+        payload = dict(kwargs)
+        if conversation_settings is not None:
+            for key, value in conversation_settings.to_start_request_kwargs().items():
+                payload.setdefault(key, value)
+        return cls(agent=agent, workspace=workspace, **payload)
+
 
 class StoredConversation(StartACPConversationRequest):
     """Stored details about a conversation.

openhands-agent-server/openhands/agent_server/settings_router.py

@@ -2,7 +2,7 @@
 
 from fastapi import APIRouter
 
-from openhands.sdk.settings import AgentSettings, SettingsSchema
+from openhands.sdk.settings import AgentSettings, ConversationSettings, SettingsSchema
 
 
 settings_router = APIRouter(prefix="/settings", tags=["Settings"])
@@ -13,7 +13,18 @@ def _get_agent_settings_schema() -> SettingsSchema:
     return AgentSettings.export_schema()
 
 
+@lru_cache(maxsize=1)
+def _get_conversation_settings_schema() -> SettingsSchema:
+    return ConversationSettings.export_schema()
+
+
 @settings_router.get("/schema", response_model=SettingsSchema)
 async def get_agent_settings_schema() -> SettingsSchema:
     """Return the schema used to render AgentSettings-based settings forms."""
     return _get_agent_settings_schema()
+
+
+@settings_router.get("/conversation-schema", response_model=SettingsSchema)
+async def get_conversation_settings_schema() -> SettingsSchema:
+    """Return the schema used to render ConversationSettings-based forms."""
+    return _get_conversation_settings_schema()

openhands-sdk/openhands/sdk/__init__.py

@@ -52,6 +52,8 @@
 from openhands.sdk.settings import (
     AgentSettings,
     CondenserSettings,
+    ConversationSettings,
+    ConversationVerificationSettings,
     SettingsChoice,
     SettingsFieldSchema,
     SettingsSchema,
@@ -137,6 +139,8 @@
     "AgentContext",
     "LLMSummarizingCondenser",
     "CondenserSettings",
+    "ConversationSettings",
+    "ConversationVerificationSettings",
     "VerificationSettings",
     "AgentSettings",
     "SettingsChoice",

openhands-sdk/openhands/sdk/settings/__init__.py

@@ -16,6 +16,8 @@
     from .model import (
         AgentSettings,
         CondenserSettings,
+        ConversationSettings,
+        ConversationVerificationSettings,
         SettingsChoice,
         SettingsFieldSchema,
         SettingsSchema,
@@ -27,6 +29,8 @@
 _MODEL_EXPORTS = {
     "AgentSettings",
     "CondenserSettings",
+    "ConversationSettings",
+    "ConversationVerificationSettings",
     "SettingsChoice",
     "SettingsFieldSchema",
     "SettingsSchema",
@@ -38,6 +42,8 @@
 __all__ = [
     "AgentSettings",
     "CondenserSettings",
+    "ConversationSettings",
+    "ConversationVerificationSettings",
     "SETTINGS_METADATA_KEY",
     "SETTINGS_SECTION_METADATA_KEY",
     "SettingProminence",

openhands-sdk/openhands/sdk/settings/model.py

@@ -100,7 +100,7 @@ class CondenserSettings(BaseModel):
 
 
 class VerificationSettings(BaseModel):
-    """Combined critic and security settings."""
+    """Critic and iterative-refinement settings for the agent."""
 
     # -- Critic --
     critic_enabled: bool = Field(
@@ -192,7 +192,10 @@ class VerificationSettings(BaseModel):
         },
     )
 
-    # -- Security --
+
+class ConversationVerificationSettings(BaseModel):
+    """Conversation-level confirmation and security settings."""
+
     confirmation_mode: bool = Field(
         default=False,
         description="Require user confirmation before executing risky actions.",
@@ -204,7 +207,7 @@ class VerificationSettings(BaseModel):
         },
     )
     security_analyzer: SecurityAnalyzerType | None = Field(
-        default=None,
+        default="llm",
         description="Security analyzer that evaluates actions before execution.",
         json_schema_extra={
             SETTINGS_METADATA_KEY: SettingsFieldMetadata(
@@ -375,6 +378,161 @@ def _diff_payload(base: Mapping[str, Any], target: Mapping[str, Any]) -> dict[st
     return diff
 
 
+_LEGACY_CONVERSATION_SETTINGS_VERSION = 1
+_CURRENT_CONVERSATION_SETTINGS_VERSION = 1
+
+
+def _coerce_persisted_conversation_settings_payload(
+    payload: Mapping[str, Any],
+) -> dict[str, Any]:
+    if (
+        _LEGACY_WRAPPED_SETTINGS_VERSION_KEY in payload
+        or _LEGACY_WRAPPED_SETTINGS_SETTINGS_KEY in payload
+    ):
+        settings_payload = payload.get(_LEGACY_WRAPPED_SETTINGS_SETTINGS_KEY)
+        if not isinstance(settings_payload, Mapping):
+            raise TypeError(
+                "Persisted ConversationSettings settings payload must be a mapping."
+            )
+        version = payload.get(_LEGACY_WRAPPED_SETTINGS_VERSION_KEY)
+        if version is None:
+            return dict(settings_payload)
+        if not isinstance(version, int) or isinstance(version, bool):
+            raise TypeError(
+                "Persisted ConversationSettings version must be an integer"
+                " when provided."
+            )
+        migrated_payload = dict(settings_payload)
+        migrated_payload[_PERSISTED_AGENT_SETTINGS_VERSION_KEY] = version
+        return migrated_payload
+
+    return dict(payload)
+
+
+def _migrate_persisted_conversation_settings_payload(
+    payload: Mapping[str, Any],
+) -> dict[str, Any]:
+    migrated_payload = _coerce_persisted_conversation_settings_payload(payload)
+    version = migrated_payload.get(
+        _PERSISTED_AGENT_SETTINGS_VERSION_KEY,
+        _LEGACY_CONVERSATION_SETTINGS_VERSION,
+    )
+    if not isinstance(version, int) or isinstance(version, bool):
+        raise TypeError(
+            "Persisted ConversationSettings schema_version must be an integer."
+        )
+    if version < _LEGACY_CONVERSATION_SETTINGS_VERSION:
+        raise ValueError(
+            f"Unsupported persisted ConversationSettings version {version}."
+        )
+    if version > _CURRENT_CONVERSATION_SETTINGS_VERSION:
+        raise ValueError(
+            "Persisted ConversationSettings version is newer than this SDK supports."
+        )
+
+    migrated_payload[_PERSISTED_AGENT_SETTINGS_VERSION_KEY] = (
+        _CURRENT_CONVERSATION_SETTINGS_VERSION
+    )
+    return migrated_payload
+
+
+class ConversationSettings(BaseModel):
+    CURRENT_PERSISTED_VERSION: ClassVar[int] = _CURRENT_CONVERSATION_SETTINGS_VERSION
+
+    schema_version: int = Field(default=_CURRENT_CONVERSATION_SETTINGS_VERSION, ge=1)
+    max_iterations: int = Field(
+        default=500,
+        ge=1,
+        description=(
+            "Maximum number of iterations the conversation will run before stopping."
+        ),
+        json_schema_extra={
+            SETTINGS_METADATA_KEY: SettingsFieldMetadata(
+                label="Max iterations",
+                prominence=SettingProminence.MAJOR,
+            ).model_dump()
+        },
+    )
+    verification: ConversationVerificationSettings = Field(
+        default_factory=ConversationVerificationSettings,
+        description="Conversation confirmation and security settings.",
+        json_schema_extra={
+            SETTINGS_SECTION_METADATA_KEY: SettingsSectionMetadata(
+                key="verification",
+                label="Verification",
+            ).model_dump()
+        },
+    )
+
+    @classmethod
+    def export_schema(cls) -> SettingsSchema:
+        """Export a structured schema describing configurable conversation settings."""
+        return export_settings_schema(cls)
+
+    @classmethod
+    def migrate_persisted_payload(cls, payload: Mapping[str, Any]) -> dict[str, Any]:
+        """Return the latest canonical persisted ConversationSettings payload."""
+        return _migrate_persisted_conversation_settings_payload(payload)
+
+    @classmethod
+    def from_persisted(cls, payload: Mapping[str, Any]) -> ConversationSettings:
+        """Load persisted ConversationSettings after applying SDK-owned migrations."""
+        return cls.model_validate(cls.migrate_persisted_payload(payload))
+
+    def patch(self, payload: Mapping[str, Any]) -> ConversationSettings:
+        """Return a new settings object with a persisted patch applied."""
+        base_payload = self.model_dump(mode="json")
+        merged_payload = _merge_patch_payload(
+            base_payload, _normalize_patch_payload(payload)
+        )
+        merged_payload[_PERSISTED_AGENT_SETTINGS_VERSION_KEY] = (
+            self.CURRENT_PERSISTED_VERSION
+        )
+        return type(self).from_persisted(merged_payload)
+
+    def diff(self, target: ConversationSettings | Mapping[str, Any]) -> dict[str, Any]:
+        """Return the minimal persisted patch from these settings to ``target``."""
+        target_settings = (
+            target
+            if isinstance(target, ConversationSettings)
+            else type(self).from_persisted(target)
+        )
+        base_payload = self.model_dump(mode="json")
+        target_payload = target_settings.model_dump(mode="json")
+        return _diff_payload(base_payload, target_payload)
+
+    def build_confirmation_policy(self):
+        from openhands.sdk.security.confirmation_policy import (
+            AlwaysConfirm,
+            ConfirmRisky,
+            NeverConfirm,
+        )
+
+        if not self.verification.confirmation_mode:
+            return NeverConfirm()
+        if (self.verification.security_analyzer or "").lower() == "llm":
+            return ConfirmRisky()
+        return AlwaysConfirm()
+
+    def build_security_analyzer(self):
+        analyzer_kind = (self.verification.security_analyzer or "").lower()
+        if not analyzer_kind or analyzer_kind == "none":
+            return None
+        if analyzer_kind == "llm":
+            from openhands.sdk.security.llm_analyzer import LLMSecurityAnalyzer
+
+            return LLMSecurityAnalyzer()
+        return None
+
+    def to_start_request_kwargs(self) -> dict[str, Any]:
+        """Return StartConversationRequest-compatible kwargs for these settings."""
+        return {
+            "confirmation_policy": self.build_confirmation_policy(),
+            "security_analyzer": self.build_security_analyzer(),
+            "max_iterations": self.max_iterations,
+        }
+
+
 class AgentSettings(BaseModel):
     CURRENT_PERSISTED_VERSION: ClassVar[int] = _CURRENT_AGENT_SETTINGS_VERSION
 

tests/agent_server/test_settings_router.py

@@ -18,6 +18,27 @@ def test_get_agent_settings_schema():
     assert "condenser" in section_keys
     assert "verification" in section_keys
 
+    verification_section = next(
+        section for section in body["sections"] if section["key"] == "verification"
+    )
+    verification_field_keys = {field["key"] for field in verification_section["fields"]}
+    assert "verification.critic_enabled" in verification_field_keys
+    assert "verification.confirmation_mode" not in verification_field_keys
+    assert "verification.security_analyzer" not in verification_field_keys
+
+
+def test_get_conversation_settings_schema():
+    client = TestClient(create_app(Config(static_files_path=None, session_api_keys=[])))
+
+    response = client.get("/api/settings/conversation-schema")
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["model_name"] == "ConversationSettings"
+
+    section_keys = [section["key"] for section in body["sections"]]
+    assert section_keys == ["general", "verification"]
+
     verification_section = next(
         section for section in body["sections"] if section["key"] == "verification"
     )