openhands-agent-server 1.26.0__tar.gz → 1.27.0__tar.gz

{openhands_agent_server-1.26.0 → openhands_agent_server-1.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-agent-server
-Version: 1.26.0
+Version: 1.27.0
 Summary: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent
 Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
 Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk

{openhands_agent_server-1.26.0 → openhands_agent_server-1.27.0}/openhands/agent_server/api.py

@@ -2,6 +2,7 @@ import asyncio
 import os
 import tempfile
 import traceback
+import uuid
 from collections.abc import AsyncIterator, Sequence
 from contextlib import asynccontextmanager, suppress
 from pathlib import Path
@@ -24,7 +25,6 @@ from openhands.agent_server.config import (
     get_default_config,
 )
 from openhands.agent_server.conversation_router import conversation_router
-from openhands.agent_server.conversation_router_acp import conversation_router_acp
 from openhands.agent_server.conversation_service import (
     get_default_conversation_service,
 )
@@ -300,7 +300,6 @@ def _add_api_routes(app: FastAPI, config: Config) -> None:
     api_router = APIRouter(prefix="/api", dependencies=dependencies)
     api_router.include_router(event_router)
     api_router.include_router(conversation_router)
-    api_router.include_router(conversation_router_acp)
     api_router.include_router(tool_router)
     api_router.include_router(bash_router)
     api_router.include_router(git_router)
@@ -431,18 +430,24 @@ def _add_exception_handlers(api: FastAPI) -> None:
         request: Request, exc: Exception
     ) -> JSONResponse:
         """Handle unhandled exceptions."""
+        # Correlation id that ties the 500 a caller receives to the server-side
+        # log line (with full traceback) for this failure, so an otherwise
+        # opaque 500 can be matched to its traceback in the server logs.
+        error_id = uuid.uuid4().hex
         # Always log that we're in the exception handler for debugging
         logger.debug(
-            "Exception handler called for %s %s with %s: %s",
+            "Exception handler called for %s %s with %s: %s [error_id=%s]",
             request.method,
             request.url.path,
             type(exc).__name__,
             str(exc),
+            error_id,
         )
 
         content = {
             "detail": "Internal Server Error",
             "exception": str(exc),
+            "error_id": error_id,
         }
         # In DEBUG mode, include stack trace in response
         if DEBUG:
@@ -458,9 +463,10 @@ def _add_exception_handlers(api: FastAPI) -> None:
                 return await _http_exception_handler(request, http_exc)
             # If no HTTPException found, treat as unhandled exception
             logger.error(
-                "Unhandled ExceptionGroup on %s %s",
+                "Unhandled ExceptionGroup on %s %s [error_id=%s]",
                 request.method,
                 request.url.path,
+                error_id,
                 exc_info=(type(exc), exc, exc.__traceback__),
             )
             return JSONResponse(status_code=500, content=content)
@@ -468,9 +474,10 @@ def _add_exception_handlers(api: FastAPI) -> None:
         # Logs full stack trace for any unhandled error that FastAPI would
         # turn into a 500
         logger.error(
-            "Unhandled exception on %s %s",
+            "Unhandled exception on %s %s [error_id=%s]",
             request.method,
             request.url.path,
+            error_id,
             exc_info=(type(exc), exc, exc.__traceback__),
         )
         return JSONResponse(status_code=500, content=content)

{openhands_agent_server-1.26.0 → openhands_agent_server-1.27.0}/openhands/agent_server/conversation_service.py

@@ -1256,9 +1256,15 @@ class WebhookSubscriber(Subscriber):
         if self.session_api_key:
             headers["X-Session-API-Key"] = self.session_api_key
 
-        # Convert events to serializable format
+        # Convert events to a JSON-serializable format. mode="json" is required
+        # so types like set and SecretStr become JSON-safe primitives; without
+        # it httpx's encoder raises "Object of type set/SecretStr is not JSON
+        # serializable", every retry fails identically, and the events are
+        # dropped. (Mirrors ConversationWebhookSubscriber.post_conversation_info.)
         event_data = [
-            event.model_dump() if hasattr(event, "model_dump") else event.__dict__
+            event.model_dump(mode="json")
+            if hasattr(event, "model_dump")
+            else event.__dict__
             for event in events_to_post
         ]
 

{openhands_agent_server-1.26.0 → openhands_agent_server-1.27.0}/openhands/agent_server/persistence/models.py

@@ -34,16 +34,23 @@ from openhands.sdk.utils.pydantic_secrets import serialize_secret, validate_secr
 class SettingsUpdatePayload(TypedDict, total=False):
     """Typed payload for PersistedSettings.update() method.
 
-    The ``*_diff`` dicts are deep-merged via :func:`_deep_merge`: nested
+    All three ``*_diff`` dicts are deep-merged via :func:`_deep_merge`: nested
     objects merge recursively, and a ``None`` value *inside a nested map*
     deletes that entry (the "unset" primitive) — e.g. send
     ``{"acp_env": {"NAME": None}}`` to drop one env-var without re-sending the
     whole map. A ``None`` on a top-level *field* is not treated as delete; it
     flows to validation as before.
+
+    ``misc_settings_diff`` is deep-merged into the persisted ``misc_settings``
+    block. The agent-server treats ``misc_settings`` as opaque
+    frontend-owned data (it persists and merges, but does not interpret), so
+    any shape the client chooses is valid; lists are replaced wholesale by
+    the deep-merge.
     """
 
     agent_settings_diff: dict[str, Any]
     conversation_settings_diff: dict[str, Any]
+    misc_settings_diff: dict[str, Any]
     active_profile: str | None
 
 
@@ -97,7 +104,7 @@ def _deep_merge(
     return result
 
 
-PERSISTED_SETTINGS_SCHEMA_VERSION = 1
+PERSISTED_SETTINGS_SCHEMA_VERSION = 2
 
 
 class PersistedSettings(BaseModel):
@@ -109,6 +116,12 @@ class PersistedSettings(BaseModel):
 
     The ``active_profile`` field tracks which LLM profile was last activated,
     allowing frontends to display which profile is currently in use.
+
+    The ``misc_settings`` field is an opaque dict the agent-server persists
+    on behalf of the frontend. The agent-server never reads its contents and
+    has no schema for it; clients are free to store any JSON-serializable
+    structure they need (e.g. app/UI preferences, analytics consent, git
+    identity used for in-conversation commits, etc.).
     """
 
     schema_version: int = Field(
@@ -124,6 +137,14 @@ class PersistedSettings(BaseModel):
         default=None,
         description="Name of the currently active LLM profile.",
     )
+    misc_settings: dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Opaque dict the agent-server persists on behalf of the frontend. "
+            "Updated through misc_settings_diff (deep-merged); contents are "
+            "never read or validated by the agent-server."
+        ),
+    )
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -173,7 +194,7 @@ class PersistedSettings(BaseModel):
         agent_update = payload.get("agent_settings_diff")
         conv_update = payload.get("conversation_settings_diff")
 
-        # Phase 1: Validate both updates before any mutations
+        # Phase 1: Validate all updates before any mutations
         new_agent: AgentSettingsConfig | None = None
         new_conv: ConversationSettings | None = None
         agent_merged: dict | None = None
@@ -232,11 +253,23 @@ class PersistedSettings(BaseModel):
                         f"Failed to update conversation settings: {type(e).__name__}"
                     ) from None
 
+            # ``misc_settings`` is opaque: deep-merge without schema
+            # validation. The agent-server doesn't interpret what's inside,
+            # and ``misc_settings`` is not a secret container — the merged
+            # dict is therefore stored directly without the post-commit
+            # clear-down used by ``agent_settings`` / ``conversation_settings``.
+            misc_update = payload.get("misc_settings_diff")
+            new_misc: dict[str, Any] | None = None
+            if isinstance(misc_update, dict):
+                new_misc = _deep_merge(self.misc_settings, misc_update)
+
             # Phase 2: Apply validated changes atomically
             if new_agent is not None:
                 self.agent_settings = new_agent
             if new_conv is not None:
                 self.conversation_settings = new_conv
+            if new_misc is not None:
+                self.misc_settings = new_misc
 
             # Update active_profile if explicitly provided (including None to clear)
             if "active_profile" in payload:
@@ -252,7 +285,14 @@ class PersistedSettings(BaseModel):
     def from_persisted(
         cls, data: Any, *, context: dict[str, Any] | None = None
     ) -> PersistedSettings:
-        """Load persisted settings, applying top-level and nested migrations."""
+        """Load persisted settings.
+
+        Schema-version history:
+
+        - **v1**: ``agent_settings`` + ``conversation_settings`` only.
+          Missing ``misc_settings`` defaults to an empty dict.
+        - **v2** (current): adds the opaque ``misc_settings`` container.
+        """
         if not isinstance(data, dict):
             return cls.model_validate(data, context=context)
 
@@ -266,6 +306,7 @@ class PersistedSettings(BaseModel):
                 f"{version} is newer than supported version "
                 f"{PERSISTED_SETTINGS_SCHEMA_VERSION}"
             )
+
         payload["schema_version"] = PERSISTED_SETTINGS_SCHEMA_VERSION
         return cls.model_validate(payload, context=context)
 

{openhands_agent_server-1.26.0 → openhands_agent_server-1.27.0}/openhands/agent_server/settings_router.py

@@ -160,6 +160,7 @@ async def get_settings(request: Request) -> SettingsResponse:
                 mode="json"
             ),
             llm_api_key_is_set=settings.llm_api_key_is_set,
+            misc_settings=settings.misc_settings,
         )
 
 
@@ -169,11 +170,12 @@ async def update_settings(
 ) -> SettingsResponse:
     """Update settings with partial changes.
 
-    Accepts ``agent_settings_diff`` and/or ``conversation_settings_diff``
-    for incremental updates. Diffs are deep-merged; nested objects merge
-    recursively, and a ``null`` value **inside a nested map deletes that
-    entry** — the "unset" primitive that lets a client remove a single map
-    key without round-tripping the whole map. To drop one ACP env-var::
+    Accepts ``agent_settings_diff``, ``conversation_settings_diff``, and/or
+    ``misc_settings_diff`` for incremental updates. All three are deep-merged;
+    nested objects merge recursively, and a ``null`` value **inside a nested
+    map deletes that entry** — the "unset" primitive that lets a client
+    remove a single map key without round-tripping the whole map. To drop one
+    ACP env-var::
 
         PATCH /api/settings
         {"agent_settings_diff": {"acp_env": {"STALE_KEY": null}}}
@@ -187,6 +189,11 @@ async def update_settings(
     is **not** an unset — it flows to model validation as before, so it still
     fails loudly rather than silently resetting the field to its default.
 
+    ``misc_settings_diff`` is deep-merged into the persisted ``misc_settings``
+    block. The agent-server treats ``misc_settings`` as opaque frontend-owned
+    data: nested dicts are merged recursively, lists are replaced wholesale,
+    and the contents are never read or validated server-side.
+
     Uses file locking to prevent concurrent updates from overwriting each other.
 
     Raises:
@@ -201,8 +208,9 @@ async def update_settings(
         raise HTTPException(
             status_code=400,
             detail=(
-                "At least one of agent_settings_diff or "
-                "conversation_settings_diff must be provided"
+                "At least one of agent_settings_diff, "
+                "conversation_settings_diff, or misc_settings_diff "
+                "must be provided"
             ),
         )
 
@@ -223,6 +231,7 @@ async def update_settings(
                 "conversation_settings_modified": (
                     "conversation_settings_diff" in update_data
                 ),
+                "misc_settings_modified": "misc_settings_diff" in update_data,
             },
         )
     except (ValueError, ValidationError):
@@ -256,6 +265,7 @@ async def update_settings(
         agent_settings=settings.agent_settings.model_dump(mode="json"),
         conversation_settings=settings.conversation_settings.model_dump(mode="json"),
         llm_api_key_is_set=settings.llm_api_key_is_set,
+        misc_settings=settings.misc_settings,
     )
 
 

{openhands_agent_server-1.26.0 → openhands_agent_server-1.27.0}/openhands_agent_server.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-agent-server
-Version: 1.26.0
+Version: 1.27.0
 Summary: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent
 Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
 Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk

{openhands_agent_server-1.26.0 → openhands_agent_server-1.27.0}/openhands_agent_server.egg-info/SOURCES.txt

@@ -10,7 +10,6 @@ pyproject.toml
 ./openhands/agent_server/config.py
 ./openhands/agent_server/conversation_lease.py
 ./openhands/agent_server/conversation_router.py
-./openhands/agent_server/conversation_router_acp.py
 ./openhands/agent_server/conversation_service.py
 ./openhands/agent_server/dependencies.py
 ./openhands/agent_server/desktop_router.py
@@ -62,7 +61,6 @@ openhands/agent_server/cloud_proxy_router.py
 openhands/agent_server/config.py
 openhands/agent_server/conversation_lease.py
 openhands/agent_server/conversation_router.py
-openhands/agent_server/conversation_router_acp.py
 openhands/agent_server/conversation_service.py
 openhands/agent_server/dependencies.py
 openhands/agent_server/desktop_router.py

{openhands_agent_server-1.26.0 → openhands_agent_server-1.27.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openhands-agent-server"
-version = "1.26.0"
+version = "1.27.0"
 description = "OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent"
 
 requires-python = ">=3.12"

openhands_agent_server-1.26.0/openhands/agent_server/conversation_router_acp.py

@@ -1,185 +0,0 @@
-"""ACP-capable conversation routes for the schema-sensitive endpoints."""
-
-# Deprecated REST contract: all /api/acp/conversations routes were deprecated
-# in v1.22.0 and are scheduled for removal in v1.27.0. The standard
-# FastAPI/OpenAPI deprecation marker for routes is ``deprecated=True`` on each
-# route decorator; keep matching docstring notices for CI deprecation checks.
-
-from typing import Annotated
-from uuid import UUID
-
-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.dependencies import get_conversation_service
-from openhands.agent_server.models import (
-    INCLUDE_SKILLS_PARAM_TITLE,
-    ACPConversationInfo,
-    ACPConversationPage,
-    ConversationSortOrder,
-    SendMessageRequest,
-    StartACPConversationRequest,
-    trim_conversation_response_skills,
-)
-from openhands.sdk import LLM, Agent, TextContent
-from openhands.sdk.agent.acp_agent import ACPAgent
-from openhands.sdk.conversation.state import ConversationExecutionStatus
-from openhands.sdk.workspace import LocalWorkspace
-from openhands.tools.preset.default import get_default_tools
-
-
-conversation_router_acp = APIRouter(
-    prefix="/acp/conversations",
-    tags=["ACP Conversations"],
-)
-
-START_ACP_CONVERSATION_EXAMPLES = [
-    StartACPConversationRequest(
-        agent=Agent(
-            llm=LLM(
-                usage_id="your-llm-service",
-                model="your-model-provider/your-model-name",
-                api_key=SecretStr("your-api-key-here"),
-            ),
-            tools=get_default_tools(enable_browser=True),
-        ),
-        workspace=LocalWorkspace(working_dir="workspace/project"),
-        initial_message=SendMessageRequest(
-            role="user", content=[TextContent(text="Flip a coin!")]
-        ),
-    ).model_dump(exclude_defaults=True, mode="json"),
-    StartACPConversationRequest(
-        agent=ACPAgent(acp_command=["npx", "-y", "claude-agent-acp"]),
-        workspace=LocalWorkspace(working_dir="workspace/project"),
-        initial_message=SendMessageRequest(
-            role="user",
-            content=[TextContent(text="Inspect the repository and summarize it.")],
-        ),
-    ).model_dump(exclude_defaults=True, mode="json"),
-]
-
-
-@conversation_router_acp.get("/search", deprecated=True)
-async def search_acp_conversations(
-    page_id: Annotated[
-        str | None,
-        Query(title="Optional next_page_id from the previously returned page"),
-    ] = None,
-    limit: Annotated[
-        int,
-        Query(title="The max number of results in the page", gt=0, lte=100),
-    ] = 100,
-    status: Annotated[
-        ConversationExecutionStatus | None,
-        Query(title="Optional filter by conversation execution status"),
-    ] = None,
-    sort_order: Annotated[
-        ConversationSortOrder,
-        Query(title="Sort order for conversations"),
-    ] = ConversationSortOrder.CREATED_AT_DESC,
-    include_skills: Annotated[bool, Query(title=INCLUDE_SKILLS_PARAM_TITLE)] = False,
-    conversation_service: ConversationService = Depends(get_conversation_service),
-) -> ACPConversationPage:
-    """Search conversations using the ACP-capable contract.
-
-    Deprecated since v1.22.0 and scheduled for removal in v1.27.0.
-    Use ``/api/conversations/search`` instead.
-    """
-    assert limit > 0
-    assert limit <= 100
-    page = await conversation_service.search_acp_conversations(
-        page_id, limit, status, sort_order
-    )
-    if not include_skills:
-        page = page.model_copy(
-            update={
-                "items": [
-                    trim_conversation_response_skills(item) for item in page.items
-                ]
-            }
-        )
-    return page
-
-
-@conversation_router_acp.get("/count", deprecated=True)
-async def count_acp_conversations(
-    status: Annotated[
-        ConversationExecutionStatus | None,
-        Query(title="Optional filter by conversation execution status"),
-    ] = None,
-    conversation_service: ConversationService = Depends(get_conversation_service),
-) -> int:
-    """Count conversations using the ACP-capable contract.
-
-    Deprecated since v1.22.0 and scheduled for removal in v1.27.0.
-    Use ``/api/conversations/count`` instead.
-    """
-    return await conversation_service.count_conversations(status)
-
-
-@conversation_router_acp.get(
-    "/{conversation_id}",
-    responses={404: {"description": "Item not found"}},
-    deprecated=True,
-)
-async def get_acp_conversation(
-    conversation_id: UUID,
-    include_skills: Annotated[bool, Query(title=INCLUDE_SKILLS_PARAM_TITLE)] = False,
-    conversation_service: ConversationService = Depends(get_conversation_service),
-) -> ACPConversationInfo:
-    """Get a conversation using the ACP-capable contract.
-
-    Deprecated since v1.22.0 and scheduled for removal in v1.27.0.
-    Use ``/api/conversations/{conversation_id}`` instead.
-    """
-    conversation = await conversation_service.get_acp_conversation(conversation_id)
-    if conversation is None:
-        raise HTTPException(status.HTTP_404_NOT_FOUND)
-    if not include_skills:
-        conversation = trim_conversation_response_skills(conversation)
-    return conversation
-
-
-@conversation_router_acp.get("", deprecated=True)
-async def batch_get_acp_conversations(
-    ids: Annotated[list[UUID], Query()],
-    include_skills: Annotated[bool, Query(title=INCLUDE_SKILLS_PARAM_TITLE)] = False,
-    conversation_service: ConversationService = Depends(get_conversation_service),
-) -> list[ACPConversationInfo | None]:
-    """Batch get conversations using the ACP-capable contract.
-
-    Deprecated since v1.22.0 and scheduled for removal in v1.27.0.
-    Use ``/api/conversations`` instead.
-    """
-    assert len(ids) < 100
-    conversations = await conversation_service.batch_get_acp_conversations(ids)
-    if not include_skills:
-        return [
-            trim_conversation_response_skills(c) if c is not None else None
-            for c in conversations
-        ]
-    return conversations
-
-
-@conversation_router_acp.post("", deprecated=True)
-async def start_acp_conversation(
-    request: Annotated[
-        StartACPConversationRequest,
-        Body(examples=START_ACP_CONVERSATION_EXAMPLES),
-    ],
-    response: Response,
-    include_skills: Annotated[bool, Query(title=INCLUDE_SKILLS_PARAM_TITLE)] = False,
-    conversation_service: ConversationService = Depends(get_conversation_service),
-) -> ACPConversationInfo:
-    """Start a conversation using the ACP-capable contract.
-
-    Deprecated since v1.22.0 and scheduled for removal in v1.27.0.
-    Use ``/api/conversations`` instead; it now accepts ACP agents and
-    ``agent_settings`` payloads.
-    """
-    info, is_new = await conversation_service.start_acp_conversation(request)
-    response.status_code = status.HTTP_201_CREATED if is_new else status.HTTP_200_OK
-    if not include_skills:
-        info = trim_conversation_response_skills(info)
-    return info