feat(agent-server): Add file-based settings and secrets persistence

.github/scripts/check_agent_server_rest_api_breakage.py

@@ -532,20 +532,78 @@ def _validate_removed_schema_properties(
     }
 )
 
+# Breaking changes allowed for the settings persistence feature (PR #3026).
+# Making `agent` and `workspace` optional in StartConversationRequest enables
+# the server to build these from persisted settings. This is a backward-compatible
+# change: existing clients that provide these fields continue to work, while new
+# clients can omit them to use server-side defaults.
+#
+# oasdiff flags these as breaking because:
+# 1. The property type changes from `object` to `anyOf[object, null]`
+# 2. Nested properties appear "removed" from the old path structure
+#
+# NOTE: These patterns are for PR #3026 (making agent/workspace optional).
+# They use prefix matching because the anyOf wrapper causes oasdiff to report
+# ALL nested properties as "removed" - there's no practical way to enumerate
+# every possible nested path.
+#
+# IMPORTANT: Any genuine breaking changes to agent/ or workspace/ fields
+# should go through the normal deprecation process with explicit annotations.
+# Review changes carefully during code review - don't rely solely on CI.
+#
+# Pattern design rationale:
+# - Type/format changes are explicit (top-level only)
+# - Nested property patterns use prefix match because oasdiff reports the
+#   entire nested structure as removed when parent becomes anyOf[object, null]
+# - If you're modifying agent or workspace schema, verify changes manually
+_OPTIONAL_AGENT_WORKSPACE_PATTERNS = (
+    # Type changes for making agent/workspace optional (top-level only)
+    "the `agent` request property type/format changed",
+    "the `workspace` request property type/format changed",
+    # Nested properties reported as "removed" due to anyOf wrapper.
+    # Prefix match is intentional - oasdiff reports ALL nested paths.
+    "removed the request property `agent/",
+    "removed the request property `workspace/",
+    # Optional nested properties (oasdiff sometimes uses this format)
+    "removed the optional property `agent/",
+    "removed the optional property `workspace/",
+)
+
+# Separate allowlist for upstream deprecations unrelated to optional args.
+# These are breaking changes from upstream dependencies that we accept.
+_UPSTREAM_DEPRECATION_PATTERNS = (
+    # LLM safety_settings was removed in litellm - not related to optional args
+    "removed the request property `llm/safety_settings`",
+)
+
+
+def _is_allowed_optional_request_change(change_text: str) -> bool:
+    """Check if a breaking change is allowed as part of optional request args."""
+    return any(
+        pattern in change_text for pattern in _OPTIONAL_AGENT_WORKSPACE_PATTERNS
+    ) or any(pattern in change_text for pattern in _UPSTREAM_DEPRECATION_PATTERNS)
+
 
 def _split_breaking_changes(
     breaking_changes: list[dict],
-) -> tuple[list[dict], list[dict], list[dict], list[dict]]:
+) -> tuple[list[dict], list[dict], list[dict], list[dict], list[dict]]:
     """Split oasdiff results into allowlisted buckets and other breakages."""
     removed_operations: list[dict] = []
     removed_schema_properties: list[dict] = []
     additive_response_oneof: list[dict] = []
+    optional_request_changes: list[dict] = []
     other_breaking_changes: list[dict] = []
 
     for change in breaking_changes:
         change_id = str(change.get("id", ""))
+        change_text = str(change.get("text", ""))
         details = change.get("details", {})
 
+        # Check for allowed optional request property changes first
+        if _is_allowed_optional_request_change(change_text):
+            optional_request_changes.append(change)
+            continue
+
         if "removed" in change_id.lower() and "operation" in change_id.lower():
             removed_operations.append(
                 {
@@ -570,6 +628,7 @@ def _split_breaking_changes(
         removed_operations,
         removed_schema_properties,
         additive_response_oneof,
+        optional_request_changes,
         other_breaking_changes,
     )
 
@@ -712,6 +771,7 @@ def main() -> int:
             removed_operations,
             removed_schema_properties,
             additive_response_oneof,
+            optional_request_changes,
             other_breaking_changes,
         ) = _split_breaking_changes(breaking_changes)
         removal_errors = _validate_removed_operations(
@@ -738,6 +798,16 @@ def main() -> int:
             for item in additive_response_oneof:
                 print(f"  - {item.get('text', str(item))}")
 
+        if optional_request_changes:
+            print(
+                f"\n::notice title={PYPI_DISTRIBUTION} REST API::"
+                "Optional request property changes detected. Making agent/workspace "
+                "optional in StartConversationRequest is backward-compatible: existing "
+                "clients that provide these fields continue to work."
+            )
+            for item in optional_request_changes:
+                print(f"  - {item.get('text', str(item))}")
+
         if other_breaking_changes:
             print(
                 "::error "

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

@@ -9,6 +9,7 @@
 from openhands.agent_server.conversation_service import (
     ConversationContractMismatchError,
     ConversationService,
+    MissingSettingsError,
 )
 from openhands.agent_server.dependencies import get_conversation_service
 from openhands.agent_server.models import (
@@ -151,7 +152,10 @@ async def batch_get_conversations(
 
 @conversation_router.post(
     "",
-    responses={409: {"description": "Conversation contract mismatch"}},
+    responses={
+        422: {"description": "Missing required settings"},
+        409: {"description": "Conversation contract mismatch"},
+    },
 )
 async def start_conversation(
     request: Annotated[
@@ -168,6 +172,12 @@ async def start_conversation(
             status_code=status.HTTP_409_CONFLICT,
             detail=str(e),
         ) from e
+    except MissingSettingsError as e:
+        # 422 Unprocessable Entity - semantic validation failure after merging
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=str(e),
+        ) from e
     response.status_code = status.HTTP_201_CREATED if is_new else status.HTTP_200_OK
     return info
 

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

@@ -6,7 +6,10 @@
 from fastapi import APIRouter, Body, Depends, HTTPException, Query, Response, status
 from pydantic import SecretStr
 
-from openhands.agent_server.conversation_service import ConversationService
+from openhands.agent_server.conversation_service import (
+    ConversationService,
+    MissingSettingsError,
+)
 from openhands.agent_server.dependencies import get_conversation_service
 from openhands.agent_server.models import (
     ACPConversationInfo,
@@ -118,7 +121,10 @@ async def batch_get_acp_conversations(
     return await conversation_service.batch_get_acp_conversations(ids)
 
 
-@conversation_router_acp.post("")
+@conversation_router_acp.post(
+    "",
+    responses={422: {"description": "Missing required settings"}},
+)
 async def start_acp_conversation(
     request: Annotated[
         StartACPConversationRequest,
@@ -128,6 +134,13 @@ async def start_acp_conversation(
     conversation_service: ConversationService = Depends(get_conversation_service),
 ) -> ACPConversationInfo:
     """Start a conversation using the ACP-capable contract."""
-    info, is_new = await conversation_service.start_acp_conversation(request)
+    try:
+        info, is_new = await conversation_service.start_acp_conversation(request)
+    except MissingSettingsError as e:
+        # 422 Unprocessable Entity - semantic validation failure after merging
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=str(e),
+        ) from e
     response.status_code = status.HTTP_201_CREATED if is_new else status.HTTP_200_OK
     return info