refactor(settings): split agent and conversation settings schemas (#2789)

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

Author: 3 people

AGENTS.md

@@ -106,6 +106,10 @@ When reviewing code, provide constructive feedback:
 - `SettingsFieldSchema` intentionally does not export a `required` flag. If a consumer needs nullability semantics, inspect the underlying Python typing rather than inferring from SDK defaults.
 - `AgentSettings.tools` is part of the exported settings schema so the schema stays aligned with the settings payload that round-trips through `AgentSettings` and drives `create_agent()`.
 - `AgentSettings.mcp_config` now uses FastMCP's typed `MCPConfig` at runtime. When serializing settings back to plain data (e.g. `model_dump()` or `create_agent()`), keep the output compact with `exclude_none=True, exclude_defaults=True` so callers still see the familiar `.mcp.json`-style dict shape.
+- Persisted SDK settings should use the direct `model_dump()` shape with a top-level `schema_version`; avoid adding wrapped payload formats or legacy migration shims in `openhands/sdk/settings/model.py`.
+- Because persisted settings are not in production yet, prefer removing temporary compatibility fields and serializers outright instead of carrying legacy settings shims in the SDK.
+- Do not expose settings schema versions as public `CURRENT_PERSISTED_VERSION` class constants on `AgentSettings` or `ConversationSettings`; keep versioning internal to the `schema_version` field/defaults and private module constants.
+- `ConversationSettings` owns the conversation-scoped confirmation controls directly (`confirmation_mode`, `security_analyzer`); keep those fields top-level on the model and grouped into the exported `verification` section via schema metadata rather than nested helper models, and prefer the direct settings-model constructor `create_request(...)` over separate request-wrapper helpers.
 - Anthropic malformed tool-use/tool-result history errors (for example, missing or duplicated ``tool_result`` blocks) are intentionally mapped to a dedicated `LLMMalformedConversationHistoryError` and caught separately in `Agent.step()`, so recovery can still use condensation while logs preserve that this was malformed history rather than a true context-window overflow.
 - AgentSkills progressive disclosure goes through `AgentContext.get_system_message_suffix()` into `<available_skills>`, and `openhands.sdk.context.skills.to_prompt()` truncates each prompt description to 1024 characters because the AgentSkills specification caps `description` at 1-1024 characters.
 - Workspace-wide uv resolver guardrails belong in the repository root `[tool.uv]` table. When `exclude-newer` is configured there, `uv lock` persists it into the root `uv.lock` `[options]` section as both an absolute cutoff and `exclude-newer-span`, and `uv sync --frozen` continues to use that locked workspace state.

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

@@ -1,35 +1,40 @@
 from abc import ABC
 from datetime import datetime
 from enum import Enum
-from typing import Annotated, Any, Literal
+from typing import Any
 from uuid import UUID, uuid4
 
-from pydantic import BaseModel, Discriminator, Field, Tag, field_validator
+from pydantic import BaseModel, Field, field_validator
 
-from openhands.agent_server.utils import OpenHandsUUID, utc_now
-from openhands.sdk import LLM, Agent, ImageContent, Message, TextContent
-from openhands.sdk.agent.acp_agent import ACPAgent
+from openhands.sdk import LLM, Agent
 from openhands.sdk.conversation.conversation_stats import ConversationStats
+from openhands.sdk.conversation.request import (  # re-export for backward compat
+    ACPEnabledAgent as ACPEnabledAgent,
+    SendMessageRequest as SendMessageRequest,
+    StartACPConversationRequest as StartACPConversationRequest,
+    StartConversationRequest as StartConversationRequest,
+)
 from openhands.sdk.conversation.secret_registry import SecretRegistry
 from openhands.sdk.conversation.state import ConversationExecutionStatus
 from openhands.sdk.conversation.types import ConversationTags
 from openhands.sdk.event.base import Event
 from openhands.sdk.hooks import HookConfig
+from openhands.sdk.llm.message import (  # re-export
+    ImageContent as ImageContent,
+    TextContent as TextContent,
+)
 from openhands.sdk.llm.utils.metrics import MetricsSnapshot
-from openhands.sdk.plugin import PluginSource
 from openhands.sdk.secret import SecretSource
 from openhands.sdk.security.analyzer import SecurityAnalyzerBase
 from openhands.sdk.security.confirmation_policy import (
     ConfirmationPolicyBase,
     NeverConfirm,
 )
-from openhands.sdk.subagent.schema import AgentDefinition
+from openhands.sdk.utils import OpenHandsUUID, utc_now
 from openhands.sdk.utils.models import (
     DiscriminatedUnionMixin,
     OpenHandsModel,
-    kind_of,
 )
-from openhands.sdk.workspace import LocalWorkspace
 from openhands.sdk.workspace.base import BaseWorkspace
 
 
@@ -46,12 +51,6 @@ class ServerErrorEvent(Event):
     detail: str = Field(description="Details about the error")
 
 
-ACPEnabledAgent = Annotated[
-    Annotated[Agent, Tag("Agent")] | Annotated[ACPAgent, Tag("ACPAgent")],
-    Discriminator(kind_of),
-]
-
-
 class ConversationSortOrder(str, Enum):
     """Enum for conversation sorting options."""
 
@@ -68,126 +67,6 @@ class EventSortOrder(str, Enum):
     TIMESTAMP_DESC = "TIMESTAMP_DESC"
 
 
-class SendMessageRequest(BaseModel):
-    """Payload to send a message to the agent.
-
-    This is a simplified version of openhands.sdk.Message.
-    """
-
-    role: Literal["user", "system", "assistant", "tool"] = "user"
-    content: list[TextContent | ImageContent] = Field(default_factory=list)
-    run: bool = Field(
-        default=False,
-        description=("Whether the agent loop should automatically run if not running"),
-    )
-
-    def create_message(self) -> Message:
-        message = Message(role=self.role, content=self.content)
-        return message
-
-
-class _StartConversationRequestBase(BaseModel):
-    """Common conversation creation fields shared by conversation contracts."""
-
-    workspace: LocalWorkspace = Field(
-        ...,
-        description="Working directory for agent operations and tool execution",
-    )
-    conversation_id: UUID | None = Field(
-        default=None,
-        description=(
-            "Optional conversation ID. If not provided, a random UUID will be "
-            "generated."
-        ),
-    )
-    confirmation_policy: ConfirmationPolicyBase = Field(
-        default=NeverConfirm(),
-        description="Controls when the conversation will prompt the user before "
-        "continuing. Defaults to never.",
-    )
-    initial_message: SendMessageRequest | None = Field(
-        default=None, description="Initial message to pass to the LLM"
-    )
-    max_iterations: int = Field(
-        default=500,
-        ge=1,
-        description="If set, the max number of iterations the agent will run "
-        "before stopping. This is useful to prevent infinite loops.",
-    )
-    stuck_detection: bool = Field(
-        default=True,
-        description="If true, the conversation will use stuck detection to "
-        "prevent infinite loops.",
-    )
-    secrets: dict[str, SecretSource] = Field(
-        default_factory=dict,
-        description="Secrets available in the conversation",
-    )
-    tool_module_qualnames: dict[str, str] = Field(
-        default_factory=dict,
-        description=(
-            "Mapping of tool names to their module qualnames from the client's "
-            "registry. These modules will be dynamically imported on the server "
-            "to register the tools for this conversation."
-        ),
-    )
-    agent_definitions: list[AgentDefinition] = Field(
-        default_factory=list,
-        description=(
-            "Agent definitions from the client's registry. These are "
-            "registered on the server so that DelegateTool and TaskSetTool "
-            "can see user-registered subagents."
-        ),
-    )
-    plugins: list[PluginSource] | None = Field(
-        default=None,
-        description=(
-            "List of plugins to load for this conversation. Plugins are loaded "
-            "and their skills/MCP config are merged into the agent. "
-            "Hooks are extracted and stored for runtime execution."
-        ),
-    )
-    hook_config: HookConfig | None = Field(
-        default=None,
-        description=(
-            "Optional hook configuration for this conversation. Hooks are shell "
-            "scripts that run at key lifecycle events (PreToolUse, PostToolUse, "
-            "UserPromptSubmit, Stop, etc.). If both hook_config and plugins are "
-            "provided, they are merged with explicit hooks running before plugin "
-            "hooks."
-        ),
-    )
-    tags: ConversationTags = Field(
-        default_factory=dict,
-        description=(
-            "Key-value tags for the conversation. Keys must be lowercase "
-            "alphanumeric. Values are arbitrary strings up to 256 characters."
-        ),
-    )
-    autotitle: bool = Field(
-        default=True,
-        description=(
-            "If true, automatically generate a title for the conversation from "
-            "the first user message using the conversation's LLM."
-        ),
-    )
-
-
-class StartConversationRequest(_StartConversationRequestBase):
-    """Payload to create a new conversation.
-
-    Contains an Agent configuration along with conversation-specific options.
-    """
-
-    agent: Agent
-
-
-class StartACPConversationRequest(_StartConversationRequestBase):
-    """Payload to create a conversation with ACP-capable agent support."""
-
-    agent: ACPEnabledAgent
-
-
 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()
 
 
-@settings_router.get("/schema", response_model=SettingsSchema)
+@lru_cache(maxsize=1)
+def _get_conversation_settings_schema() -> SettingsSchema:
+    return ConversationSettings.export_schema()
+
+
+@settings_router.get("/agent-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

@@ -47,6 +47,7 @@
 from openhands.sdk.settings import (
     AgentSettings,
     CondenserSettings,
+    ConversationSettings,
     SettingsChoice,
     SettingsFieldSchema,
     SettingsSchema,
@@ -137,6 +138,7 @@
     "AgentContext",
     "LLMSummarizingCondenser",
     "CondenserSettings",
+    "ConversationSettings",
     "VerificationSettings",
     "AgentSettings",
     "SettingsChoice",