openhands-agent-server 1.27.1__tar.gz → 1.28.1__tar.gz

{openhands_agent_server-1.27.1 → openhands_agent_server-1.28.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-agent-server
-Version: 1.27.1
+Version: 1.28.1
 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
@@ -12,6 +12,7 @@ Requires-Dist: alembic>=1.13
 Requires-Dist: docker<8,>=7.1
 Requires-Dist: fastapi>=0.104
 Requires-Dist: openhands-sdk
+Requires-Dist: openai<3,>=2.33.0
 Requires-Dist: pydantic>=2
 Requires-Dist: sqlalchemy>=2
 Requires-Dist: uvicorn>=0.31.1

{openhands_agent_server-1.27.1 → openhands_agent_server-1.28.1}/openhands/agent_server/api.py

@@ -41,6 +41,10 @@ from openhands.agent_server.hooks_router import hooks_router
 from openhands.agent_server.llm_router import llm_router
 from openhands.agent_server.mcp_router import mcp_router
 from openhands.agent_server.middleware import CORSDispatcher
+from openhands.agent_server.openai.router import (
+    create_openai_api_key_dependency,
+    openai_router,
+)
 from openhands.agent_server.profiles_router import profiles_router
 from openhands.agent_server.server_details_router import (
     get_server_info,
@@ -319,6 +323,11 @@ def _add_api_routes(app: FastAPI, config: Config) -> None:
     api_router.include_router(auth_router)
     app.include_router(api_router)
 
+    openai_dependencies = []
+    if config.session_api_keys:
+        openai_dependencies.append(Depends(create_openai_api_key_dependency(config)))
+    app.include_router(openai_router, dependencies=openai_dependencies)
+
     # Workspace static-file routes get their own auth group that accepts
     # EITHER the X-Session-API-Key header OR the workspace session cookie.
     # The cookie is required so that <iframe src> / <img src> embeds of

{openhands_agent_server-1.27.1 → openhands_agent_server-1.28.1}/openhands/agent_server/auth_router.py

@@ -23,12 +23,10 @@ from openhands.agent_server.dependencies import WORKSPACE_SESSION_COOKIE_NAME
 
 auth_router = APIRouter(prefix="/auth", tags=["Auth"])
 
-# Cookie lifetime in seconds. Short enough that a stolen cookie isn't a
-# long-lived credential; long enough that a user previewing artifacts in
-# canvas isn't constantly re-authing. The cookie auto-renews on every call
-# to POST /api/auth/workspace-session, which the canvas frontend can do on
-# load.
-_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 8  # 8 hours
+# Cookie lifetime in seconds. Set to effectively "never expire" — browsers
+# (per RFC 6265bis, e.g. Chrome) clamp Max-Age to ~400 days regardless of
+# the value sent, so this is the longest persistence the spec allows.
+_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 365 * 10  # 10 years
 
 # Path scope: only sent on workspace-router URLs. Other /api/* endpoints
 # never see the cookie.

{openhands_agent_server-1.27.1 → openhands_agent_server-1.28.1}/openhands/agent_server/config.py

@@ -132,6 +132,12 @@ class Config(BaseModel):
             "The location of the directory where conversations and events are stored."
         ),
     )
+    workspace_path: Path = Field(
+        default=Path("workspace/project"),
+        description=(
+            "Default workspace directory for conversations created by the server."
+        ),
+    )
     bash_events_dir: Path = Field(
         default=Path("workspace/bash_events"),
         description=(

{openhands_agent_server-1.27.1 → openhands_agent_server-1.28.1}/openhands/agent_server/conversation_router.py

@@ -41,6 +41,7 @@ from openhands.agent_server.models import (
 )
 from openhands.sdk import LLM, Agent, TextContent
 from openhands.sdk.conversation.state import ConversationExecutionStatus
+from openhands.sdk.tool.client_tool import ClientToolRegistrationError
 from openhands.sdk.workspace import LocalWorkspace
 from openhands.tools.preset.default import get_default_tools
 
@@ -194,7 +195,12 @@ async def start_conversation(
     conversation_service: ConversationService = Depends(get_conversation_service),
 ) -> ConversationInfo:
     """Start a conversation in the local environment."""
-    info, is_new = await conversation_service.start_conversation(request)
+    try:
+        info, is_new = await conversation_service.start_conversation(request)
+    except ClientToolRegistrationError as e:
+        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
     if not include_skills:
         info = trim_conversation_response_skills(info)

{openhands_agent_server-1.27.1 → openhands_agent_server-1.28.1}/openhands/agent_server/conversation_service.py

@@ -5,7 +5,7 @@ from concurrent.futures import ThreadPoolExecutor
 from contextlib import suppress
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING, Any, cast
 from uuid import UUID, uuid4
 
 import httpx
@@ -42,6 +42,7 @@ from openhands.sdk.event import MessageEvent
 from openhands.sdk.event.conversation_state import ConversationStateUpdateEvent
 from openhands.sdk.git.exceptions import GitCommandError, GitRepositoryError
 from openhands.sdk.git.utils import run_git_command, validate_git_repository
+from openhands.sdk.tool.client_tool import register_client_tools
 from openhands.sdk.utils.cipher import Cipher
 from openhands.sdk.workspace import LocalWorkspace
 
@@ -307,6 +308,7 @@ def _compose_conversation_info(
         current_model_id=current_model_id,
         available_models=available_models,
         supports_runtime_model_switch=supports_runtime_model_switch,
+        client_tools=stored.client_tools,
     )
 
 
@@ -638,6 +640,22 @@ class ConversationService:
                     conversation_id,
                 )
 
+        # Register client-defined tools (JSON specs, no Python code). The
+        # ClientTool *class* is registered statelessly; each tool's schema
+        # travels with the conversation via the returned Tool.params, so
+        # concurrent conversations never clobber each other's schemas.
+        if request.client_tools:
+            client_tool_specs = register_client_tools(request.client_tools)
+            # Inject Tool specs into the agent so _initialize() resolves them
+            existing_names = {t.name for t in request.agent.tools}
+            new_tools = [
+                ts for ts in client_tool_specs if ts.name not in existing_names
+            ]
+            if new_tools:
+                request.agent = request.agent.model_copy(
+                    update={"tools": [*request.agent.tools, *new_tools]}
+                )
+
         # Register subagent definitions forwarded from the client
         if request.agent_definitions:
             _register_agent_definitions(
@@ -919,11 +937,25 @@ class ConversationService:
         fork_conv.close()
 
         # _start_event_service will resume from the persisted fork directory.
-        fork_stored = StoredConversation(
-            id=fork_conv_id,
-            agent=fork_agent,
-            workspace=fork_workspace,
-        )
+        # Copy the source's stored metadata so request-level configuration
+        # (client_tools, tool_module_qualnames, agent_definitions, plugins,
+        # secrets, ...) is preserved on the fork, then override only the
+        # fork-specific fields. Without this, e.g. a fork of a client-tool
+        # conversation would lose ``client_tools`` in meta.json and be unable
+        # to re-register its tools after a server restart.
+        fork_overrides: dict[str, Any] = {
+            "id": fork_conv_id,
+            "agent": fork_agent,
+            "workspace": fork_workspace,
+            "title": title,
+            "created_at": utc_now(),
+            "updated_at": utc_now(),
+        }
+        if reset_metrics:
+            fork_overrides["metrics"] = None
+        if tags is not None:
+            fork_overrides["tags"] = tags
+        fork_stored = source_service.stored.model_copy(update=fork_overrides)
         # If the service fails to start, clean up the orphaned persistence
         # directory so we don't leave stale state on disk.
         fork_dir = self.conversations_dir / fork_conv_id.hex
@@ -984,6 +1016,11 @@ class ConversationService:
                             f"resuming conversation {stored.id}: "
                             f"{list(stored.tool_module_qualnames.keys())}"
                         )
+                # Re-register client-defined tools when resuming. The agent's
+                # persisted tool specs already carry each schema via params, so
+                # we only need to (re-)register the ClientTool class per name.
+                if stored.client_tools:
+                    register_client_tools(stored.client_tools)
                 # Register agent definitions when resuming
                 if stored.agent_definitions:
                     _register_agent_definitions(

{openhands_agent_server-1.27.1 → openhands_agent_server-1.28.1}/openhands/agent_server/models.py

@@ -34,6 +34,7 @@ from openhands.sdk.security.confirmation_policy import (
     ConfirmationPolicyBase,
     NeverConfirm,
 )
+from openhands.sdk.tool.client_tool import ClientToolSpec
 from openhands.sdk.utils import OpenHandsUUID, utc_now
 from openhands.sdk.utils.models import (
     DiscriminatedUnionMixin,
@@ -242,6 +243,15 @@ class ConversationInfo(_ConversationInfoBase):
         ...,
         description="The agent running in the conversation.",
     )
+    client_tools: list[ClientToolSpec] = Field(
+        default_factory=list,
+        description=(
+            "Client-defined tool specs registered for this conversation. "
+            "Surfaced so that a client re-attaching by conversation id can "
+            "register the dynamic ClientAction_* action types before syncing "
+            "persisted events, avoiding 'Unknown kind' deserialization errors."
+        ),
+    )
 
 
 class ConversationPage(BaseModel):

openhands_agent_server-1.28.1/openhands/agent_server/openai/models.py

@@ -0,0 +1,59 @@
+"""Models for the OpenAI-compatible agent-server gateway."""
+
+from typing import Literal
+
+from openai.types import CompletionUsage, Model
+from openai.types.chat import ChatCompletion, ChatCompletionChunk
+from openai.types.chat.chat_completion import Choice
+from openai.types.chat.chat_completion_chunk import Choice as ChunkChoice, ChoiceDelta
+from openai.types.chat.chat_completion_message import ChatCompletionMessage
+from pydantic import BaseModel, ConfigDict
+
+
+OpenAIChatCompletionChoice = Choice
+OpenAIChatCompletionChunk = ChatCompletionChunk
+OpenAIChatCompletionChunkChoice = ChunkChoice
+OpenAIChatCompletionChunkChoiceDelta = ChoiceDelta
+OpenAIChatCompletionResponse = ChatCompletion
+OpenAIModel = Model
+OpenAIResponseMessage = ChatCompletionMessage
+OpenAIUsage = CompletionUsage
+
+
+class OpenAIImageURL(BaseModel):
+    url: str
+
+
+class OpenAIContentPart(BaseModel):
+    type: str
+    text: str | None = None
+    image_url: OpenAIImageURL | str | None = None
+
+    model_config = ConfigDict(extra="ignore")
+
+
+class OpenAIChatMessage(BaseModel):
+    role: Literal["system", "developer", "user", "assistant", "tool"]
+    content: str | list[OpenAIContentPart] | None = None
+
+    model_config = ConfigDict(extra="ignore")
+
+
+class OpenAIStreamOptions(BaseModel):
+    include_usage: bool = False
+
+    model_config = ConfigDict(extra="ignore")
+
+
+class OpenAIChatCompletionRequest(BaseModel):
+    model: str
+    messages: list[OpenAIChatMessage]
+    stream: bool = False
+    stream_options: OpenAIStreamOptions | None = None
+
+    model_config = ConfigDict(extra="ignore")
+
+
+class OpenAIModelListResponse(BaseModel):
+    object: Literal["list"] = "list"
+    data: list[OpenAIModel]

openhands_agent_server-1.28.1/openhands/agent_server/openai/router.py

@@ -0,0 +1,111 @@
+"""OpenAI-compatible gateway routes for the agent server."""
+
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Header, HTTPException, Request, Response, status
+from fastapi.responses import StreamingResponse
+from fastapi.security import APIKeyHeader, HTTPAuthorizationCredentials, HTTPBearer
+
+from openhands.agent_server.config import Config
+from openhands.agent_server.conversation_service import ConversationService
+from openhands.agent_server.dependencies import get_conversation_service
+from openhands.agent_server.openai.models import (
+    OpenAIChatCompletionRequest,
+    OpenAIChatCompletionResponse,
+    OpenAIModelListResponse,
+)
+from openhands.agent_server.openai.service import (
+    iter_openai_chat_completion_sse,
+    list_openai_models,
+    run_chat_completion,
+)
+
+
+openai_router = APIRouter(tags=["OpenAI Compatibility"])
+
+_SESSION_API_KEY_HEADER = APIKeyHeader(name="X-Session-API-Key", auto_error=False)
+_AUTHORIZATION_HEADER = HTTPBearer(auto_error=False)
+
+
+def create_openai_api_key_dependency(config: Config):
+    """Accept the same session key through OpenHands and OpenAI auth shapes.
+
+    ``X-Session-API-Key`` preserves compatibility with existing agent-server
+    clients, while ``Authorization: Bearer`` lets OpenAI-compatible clients use
+    their standard API-key header. Both forms validate against
+    ``config.session_api_keys``; this does not introduce a second credential
+    system. When no session keys are configured, the local server remains
+    unauthenticated like the existing agent-server API.
+    """
+
+    def check_openai_api_key(
+        session_api_key: str | None = Depends(_SESSION_API_KEY_HEADER),
+        authorization: HTTPAuthorizationCredentials | None = Depends(
+            _AUTHORIZATION_HEADER
+        ),
+    ) -> None:
+        if not config.session_api_keys:
+            return
+        bearer_token = authorization.credentials if authorization else None
+        if session_api_key in config.session_api_keys:
+            return
+        if bearer_token in config.session_api_keys:
+            return
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED)
+
+    return check_openai_api_key
+
+
+def _get_config(request: Request) -> Config:
+    config = getattr(request.app.state, "config", None)
+    if not isinstance(config, Config):
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Agent server config is not available",
+        )
+    return config
+
+
+@openai_router.get("/v1/models", response_model=OpenAIModelListResponse)
+async def get_openai_models(request: Request) -> OpenAIModelListResponse:
+    _get_config(request)
+    return await list_openai_models()
+
+
+@openai_router.post(
+    "/v1/chat/completions",
+    response_model=OpenAIChatCompletionResponse,
+    response_model_exclude_none=True,
+)
+async def create_chat_completion(
+    body: OpenAIChatCompletionRequest,
+    request: Request,
+    response: Response,
+    x_openhands_server_conversation_id: Annotated[
+        UUID | None, Header(alias="X-OpenHands-ServerConversation-ID")
+    ] = None,
+    conversation_service: ConversationService = Depends(get_conversation_service),
+) -> OpenAIChatCompletionResponse | StreamingResponse:
+    result = await run_chat_completion(
+        request=body.model_copy(update={"stream": False}) if body.stream else body,
+        config=_get_config(request),
+        conversation_service=conversation_service,
+        reusable_conversation_id=x_openhands_server_conversation_id,
+    )
+    conversation_id = str(result.conversation_id)
+    if body.stream:
+        include_usage = (
+            body.stream_options is not None and body.stream_options.include_usage
+        )
+        return StreamingResponse(
+            iter_openai_chat_completion_sse(
+                result.response,
+                include_usage=include_usage,
+            ),
+            media_type="text/event-stream",
+            headers={"X-OpenHands-ServerConversation-ID": conversation_id},
+        )
+
+    response.headers["X-OpenHands-ServerConversation-ID"] = conversation_id
+    return result.response

openhands_agent_server-1.28.1/openhands/agent_server/openai/service.py

@@ -0,0 +1,472 @@
+"""Service logic for the OpenAI-compatible agent-server gateway."""
+
+import asyncio
+import json
+import time
+from collections.abc import Iterator
+from dataclasses import dataclass
+from uuid import UUID, uuid4
+
+from fastapi import HTTPException, status
+
+from openhands.agent_server.config import Config
+from openhands.agent_server.conversation_service import ConversationService
+from openhands.agent_server.event_service import EventService
+from openhands.agent_server.openai.models import (
+    OpenAIChatCompletionChoice,
+    OpenAIChatCompletionChunk,
+    OpenAIChatCompletionChunkChoice,
+    OpenAIChatCompletionChunkChoiceDelta,
+    OpenAIChatCompletionRequest,
+    OpenAIChatCompletionResponse,
+    OpenAIChatMessage,
+    OpenAIModel,
+    OpenAIModelListResponse,
+    OpenAIResponseMessage,
+    OpenAIUsage,
+)
+from openhands.agent_server.persistence import PersistedSettings, get_settings_store
+from openhands.sdk import LLM, Message
+from openhands.sdk.context.agent_context import AgentContext
+from openhands.sdk.conversation.request import (
+    SendMessageRequest,
+    StartConversationRequest,
+)
+from openhands.sdk.conversation.state import (
+    ConversationExecutionStatus,
+    ConversationState,
+)
+from openhands.sdk.llm.llm_profile_store import LLMProfileStore
+from openhands.sdk.llm.message import ImageContent, TextContent
+from openhands.sdk.settings import ACPAgentSettings, OpenHandsAgentSettings
+from openhands.sdk.workspace import LocalWorkspace
+
+
+_MODEL_PREFIX = "openhands_"
+# Fixed gateway defaults are sufficient for the initial local-first endpoint;
+# promote them to Config only if clients need deployment-specific tuning.
+_GATEWAY_TIMEOUT_SECONDS = 120.0
+_POLL_INTERVAL_SECONDS = 2
+
+
+@dataclass(frozen=True)
+class OpenAIChatCompletionResult:
+    response: OpenAIChatCompletionResponse
+    conversation_id: UUID
+
+
+def _profile_name_from_model(model: str) -> str:
+    if model.startswith(_MODEL_PREFIX) and len(model) > len(_MODEL_PREFIX):
+        return model[len(_MODEL_PREFIX) :]
+    raise HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND,
+        detail=f"Unknown OpenHands model '{model}'. Use GET /v1/models.",
+    )
+
+
+def _load_profile_llm(profile_name: str, config: Config) -> LLM:
+    try:
+        return LLMProfileStore().load(profile_name, cipher=config.cipher)
+    except FileNotFoundError:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Profile '{profile_name}' not found",
+        )
+    except TimeoutError:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Profile store is busy. Please retry.",
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc))
+
+
+def _append_system_suffix(existing: str | None, system_text: str) -> str:
+    return "\n\n".join(
+        text for text in ((existing or "").strip(), system_text.strip()) if text
+    )
+
+
+def _with_profile_llm_and_system_text(
+    agent_settings: OpenHandsAgentSettings | ACPAgentSettings,
+    llm: LLM,
+    system_text: str,
+) -> OpenHandsAgentSettings | ACPAgentSettings:
+    updated = agent_settings.model_copy(update={"llm": llm})
+    if not system_text:
+        return updated
+
+    if isinstance(updated, OpenHandsAgentSettings):
+        context = updated.agent_context
+        suffix = _append_system_suffix(context.system_message_suffix, system_text)
+        return updated.model_copy(
+            update={
+                "agent_context": context.model_copy(
+                    update={"system_message_suffix": suffix}
+                )
+            }
+        )
+
+    context = updated.agent_context or AgentContext()
+    suffix = _append_system_suffix(context.system_message_suffix, system_text)
+    return updated.model_copy(
+        update={
+            "agent_context": context.model_copy(
+                update={"system_message_suffix": suffix}
+            )
+        }
+    )
+
+
+def _content_to_sdk_parts(
+    message: OpenAIChatMessage,
+) -> list[TextContent | ImageContent]:
+    content = message.content
+    if content is None:
+        return []
+    if isinstance(content, str):
+        return [TextContent(text=content)]
+
+    parts: list[TextContent | ImageContent] = []
+    for part in content:
+        if part.type == "text":
+            if part.text:
+                parts.append(TextContent(text=part.text))
+            continue
+        if part.type == "image_url":
+            if isinstance(part.image_url, str):
+                image_url = part.image_url
+            elif part.image_url is not None:
+                image_url = part.image_url.url
+            else:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="image_url content part is missing a url",
+                )
+            parts.append(ImageContent(image_urls=[image_url]))
+            continue
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Unsupported content part type: {part.type}",
+        )
+    return parts
+
+
+def _message_text(message: OpenAIChatMessage) -> str:
+    text_parts: list[str] = []
+    for part in _content_to_sdk_parts(message):
+        if isinstance(part, TextContent):
+            text_parts.append(part.text)
+    return "\n".join(text_parts)
+
+
+def _latest_user_message(messages: list[OpenAIChatMessage]) -> OpenAIChatMessage:
+    for message in reversed(messages):
+        if message.role == "user":
+            return message
+    raise HTTPException(
+        status_code=status.HTTP_400_BAD_REQUEST,
+        detail="At least one user message is required",
+    )
+
+
+def _system_text(messages: list[OpenAIChatMessage]) -> str:
+    text_parts: list[str] = []
+    for message in messages:
+        if message.role not in {"system", "developer"}:
+            continue
+        text = _message_text(message)
+        if text:
+            text_parts.append(text)
+    return "\n\n".join(text_parts)
+
+
+def _conversation_request(
+    *,
+    request: OpenAIChatCompletionRequest,
+    config: Config,
+    conversation_id: UUID | None,
+) -> StartConversationRequest:
+    profile_name = _profile_name_from_model(request.model)
+    llm = _load_profile_llm(profile_name, config)
+    settings = get_settings_store(config).load() or PersistedSettings()
+    agent_settings = _with_profile_llm_and_system_text(
+        settings.agent_settings,
+        llm,
+        _system_text(request.messages),
+    )
+    user_message = _latest_user_message(request.messages)
+    conversation_settings = settings.conversation_settings.model_copy(
+        update={"agent_settings": agent_settings}
+    )
+    return conversation_settings.create_request(
+        StartConversationRequest,
+        workspace=LocalWorkspace(working_dir=config.workspace_path),
+        conversation_id=conversation_id,
+        initial_message=SendMessageRequest(
+            role="user",
+            content=_content_to_sdk_parts(user_message),
+            run=True,
+        ),
+        autotitle=False,
+    )
+
+
+# Keep this server-side waiter close to the gateway for readability. It follows
+# the existing status-polling pattern, while RemoteConversation owns the richer
+# client-side WebSocket fallback; we can consolidate if this grows in follow-up.
+async def _wait_for_completion(
+    event_service: EventService,
+    *,
+    allow_existing_response: bool,
+    min_event_count: int | None = None,
+    timeout_seconds: float = _GATEWAY_TIMEOUT_SECONDS,
+) -> ConversationExecutionStatus:
+    deadline = time.monotonic() + timeout_seconds
+    observed_run = False
+    last_status = ConversationExecutionStatus.IDLE
+
+    while True:
+        state = await event_service.get_state()
+        last_status = state.execution_status
+        enough_new_events = (
+            min_event_count is None or len(state.events) > min_event_count
+        )
+        if last_status == ConversationExecutionStatus.RUNNING:
+            observed_run = True
+        elif last_status.is_terminal() and (
+            allow_existing_response or observed_run or enough_new_events
+        ):
+            return last_status
+        elif observed_run and enough_new_events:
+            return last_status
+        elif (
+            allow_existing_response
+            and enough_new_events
+            and await event_service.get_agent_final_response()
+        ):
+            return last_status
+
+        if time.monotonic() >= deadline:
+            raise HTTPException(
+                status_code=status.HTTP_504_GATEWAY_TIMEOUT,
+                detail="Agent run timed out",
+            )
+        await asyncio.sleep(_POLL_INTERVAL_SECONDS)
+
+
+def _raise_for_terminal_error(status_value: ConversationExecutionStatus) -> None:
+    if status_value in (
+        ConversationExecutionStatus.ERROR,
+        ConversationExecutionStatus.STUCK,
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Agent run ended with status: {status_value.value}",
+        )
+    if status_value in (
+        ConversationExecutionStatus.PAUSED,
+        ConversationExecutionStatus.WAITING_FOR_CONFIRMATION,
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Agent run ended with status: {status_value.value}",
+        )
+
+
+def _openai_usage_from_state(state: ConversationState) -> OpenAIUsage:
+    token_usage = state.stats.get_combined_metrics().accumulated_token_usage
+    if token_usage is None:
+        return OpenAIUsage(
+            prompt_tokens=0,
+            completion_tokens=0,
+            total_tokens=0,
+        )
+
+    prompt_tokens = token_usage.prompt_tokens
+    completion_tokens = token_usage.completion_tokens
+    return OpenAIUsage(
+        prompt_tokens=prompt_tokens,
+        completion_tokens=completion_tokens,
+        total_tokens=prompt_tokens + completion_tokens,
+    )
+
+
+def _openai_stream_event(payload: OpenAIChatCompletionChunk) -> str:
+    data = payload.model_dump(mode="json", exclude_none=True)
+    return f"data: {json.dumps(data, separators=(',', ':'))}\n\n"
+
+
+def iter_openai_chat_completion_sse(
+    response: OpenAIChatCompletionResponse,
+    *,
+    include_usage: bool,
+) -> Iterator[str]:
+    created = int(response.created)
+    completion_id = response.id
+    model = response.model
+    content = response.choices[0].message.content
+    finish_reason = response.choices[0].finish_reason
+
+    yield _openai_stream_event(
+        OpenAIChatCompletionChunk(
+            id=completion_id,
+            object="chat.completion.chunk",
+            created=created,
+            model=model,
+            choices=[
+                OpenAIChatCompletionChunkChoice(
+                    index=0,
+                    delta=OpenAIChatCompletionChunkChoiceDelta(role="assistant"),
+                    finish_reason=None,
+                )
+            ],
+        )
+    )
+    yield _openai_stream_event(
+        OpenAIChatCompletionChunk(
+            id=completion_id,
+            object="chat.completion.chunk",
+            created=created,
+            model=model,
+            choices=[
+                OpenAIChatCompletionChunkChoice(
+                    index=0,
+                    delta=OpenAIChatCompletionChunkChoiceDelta(content=content),
+                    finish_reason=None,
+                )
+            ],
+        )
+    )
+    yield _openai_stream_event(
+        OpenAIChatCompletionChunk(
+            id=completion_id,
+            object="chat.completion.chunk",
+            created=created,
+            model=model,
+            choices=[
+                OpenAIChatCompletionChunkChoice(
+                    index=0,
+                    delta=OpenAIChatCompletionChunkChoiceDelta(),
+                    finish_reason=finish_reason,
+                )
+            ],
+        )
+    )
+    if include_usage:
+        yield _openai_stream_event(
+            OpenAIChatCompletionChunk(
+                id=completion_id,
+                object="chat.completion.chunk",
+                created=created,
+                model=model,
+                choices=[],
+                usage=response.usage,
+            )
+        )
+    yield "data: [DONE]\n\n"
+
+
+async def list_openai_models() -> OpenAIModelListResponse:
+    try:
+        profiles = LLMProfileStore().list_summaries()
+    except TimeoutError:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Profile store is busy. Please retry.",
+        )
+    data = [
+        OpenAIModel(
+            id=f"{_MODEL_PREFIX}{profile['name']}",
+            object="model",
+            created=0,
+            owned_by="openhands",
+        )
+        for profile in profiles
+        if isinstance(profile.get("name"), str)
+    ]
+    data.sort(key=lambda model: model.id)
+    return OpenAIModelListResponse(data=data)
+
+
+async def run_chat_completion(
+    *,
+    request: OpenAIChatCompletionRequest,
+    config: Config,
+    conversation_service: ConversationService,
+    reusable_conversation_id: UUID | None,
+) -> OpenAIChatCompletionResult:
+    if request.stream:
+        # SSE streaming needs incremental agent-event forwarding; add it separately.
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Streaming chat completions are not supported yet",
+        )
+
+    start_request = _conversation_request(
+        request=request,
+        config=config,
+        conversation_id=reusable_conversation_id,
+    )
+    event_service = None
+    conversation_id = reusable_conversation_id
+    min_event_count: int | None = None
+
+    if reusable_conversation_id is not None:
+        event_service = await conversation_service.get_event_service(
+            reusable_conversation_id
+        )
+        if event_service is not None:
+            min_event_count = len((await event_service.get_state()).events) + 1
+            user_message = _latest_user_message(request.messages)
+            await event_service.send_message(
+                Message(role="user", content=_content_to_sdk_parts(user_message)),
+                run=True,
+            )
+    allow_existing_response = event_service is None
+
+    if event_service is None:
+        conversation_info, _ = await conversation_service.start_conversation(
+            start_request
+        )
+        conversation_id = conversation_info.id
+        event_service = await conversation_service.get_event_service(
+            conversation_info.id
+        )
+        if event_service is None:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Conversation did not start",
+            )
+
+    status_value = await _wait_for_completion(
+        event_service,
+        allow_existing_response=allow_existing_response,
+        min_event_count=min_event_count,
+    )
+    _raise_for_terminal_error(status_value)
+    state = await event_service.get_state()
+    final_response = await event_service.get_agent_final_response()
+    # EventService.get_agent_final_response() returns final text from the SDK's
+    # get_agent_final_response(), so the gateway emits assistant text only.
+    response = OpenAIChatCompletionResponse(
+        id=f"chatcmpl-{uuid4().hex}",
+        object="chat.completion",
+        created=int(time.time()),
+        model=request.model,
+        choices=[
+            OpenAIChatCompletionChoice(
+                index=0,
+                finish_reason="stop",
+                message=OpenAIResponseMessage(
+                    role="assistant",
+                    content=final_response,
+                ),
+            )
+        ],
+        usage=_openai_usage_from_state(state),
+    )
+    assert conversation_id is not None
+    return OpenAIChatCompletionResult(
+        response=response, conversation_id=conversation_id
+    )

{openhands_agent_server-1.27.1 → openhands_agent_server-1.28.1}/openhands/agent_server/persistence/models.py

@@ -289,8 +289,8 @@ class PersistedSettings(BaseModel):
 
         Schema-version history:
 
-        - **v1**: ``agent_settings`` + ``conversation_settings`` only.
-          Missing ``misc_settings`` defaults to an empty dict.
+        - **v1**: ``agent_settings`` + ``conversation_settings`` plus
+          ``active_profile``.
         - **v2** (current): adds the opaque ``misc_settings`` container.
         """
         if not isinstance(data, dict):

{openhands_agent_server-1.27.1 → openhands_agent_server-1.28.1}/openhands/agent_server/profiles_router.py

@@ -105,6 +105,23 @@ def _has_api_key(llm: LLM) -> bool:
     return bool(llm.api_key.get_secret_value().strip())
 
 
+def _set_active_profile_if_matches(
+    request: Request, old_name: str, new_name: str | None
+) -> bool:
+    config = get_config(request)
+    settings_store = get_settings_store(config)
+    settings = settings_store.load() or PersistedSettings()
+    if settings.active_profile != old_name:
+        return False
+
+    def update_active(settings: PersistedSettings) -> PersistedSettings:
+        settings.active_profile = new_name
+        return settings
+
+    settings_store.update(update_active)
+    return True
+
+
 @profiles_router.get("", response_model=ProfileListResponse)
 async def list_profiles(request: Request) -> ProfileListResponse:
     """List all saved LLM profiles.
@@ -207,11 +224,15 @@ async def save_profile(
 
 
 @profiles_router.delete("/{name}", response_model=ProfileMutationResponse)
-async def delete_profile(name: ProfileName) -> ProfileMutationResponse:
+async def delete_profile(
+    request: Request, name: ProfileName
+) -> ProfileMutationResponse:
     """Delete a saved profile (idempotent)."""
     store = LLMProfileStore()
     with _store_errors():
         store.delete(name)
+    if _set_active_profile_if_matches(request, name, None):
+        logger.info(f"Cleared active_profile for deleted profile '{name}'")
     logger.info(f"Deleted profile '{name}'")
     return ProfileMutationResponse(name=name, message=f"Profile '{name}' deleted")
 
@@ -245,21 +266,10 @@ async def rename_profile(
             detail=f"Profile '{body.new_name}' already exists",
         )
 
-    # Update active_profile if the renamed profile was the active one
-    if name != body.new_name:
-        config = get_config(request)
-        settings_store = get_settings_store(config)
-        settings = settings_store.load() or PersistedSettings()
-
-        if settings.active_profile == name:
-            new_name = body.new_name
-
-            def update_active(s: PersistedSettings) -> PersistedSettings:
-                s.active_profile = new_name
-                return s
-
-            settings_store.update(update_active)
-            logger.info(f"Updated active_profile from '{name}' to '{new_name}'")
+    if name != body.new_name and _set_active_profile_if_matches(
+        request, name, body.new_name
+    ):
+        logger.info(f"Updated active_profile from '{name}' to '{body.new_name}'")
 
     if name == body.new_name:
         message = f"Profile '{name}' unchanged (same name)"

{openhands_agent_server-1.27.1 → openhands_agent_server-1.28.1}/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,
+            active_profile=settings.active_profile,
             misc_settings=settings.misc_settings,
         )
 
@@ -170,12 +171,12 @@ async def update_settings(
 ) -> SettingsResponse:
     """Update settings with partial changes.
 
-    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::
+    Accepts ``agent_settings_diff``, ``conversation_settings_diff``,
+    ``misc_settings_diff``, and/or ``active_profile`` for incremental updates.
+    The three ``*_settings_diff`` fields 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}}}
@@ -203,14 +204,16 @@ async def update_settings(
     store = get_settings_store(config)
 
     update_data = payload.model_dump(exclude_none=True)
+    if "active_profile" in payload.model_fields_set:
+        update_data["active_profile"] = payload.active_profile
     if not update_data:
         # No updates provided - this is a client error
         raise HTTPException(
             status_code=400,
             detail=(
                 "At least one of agent_settings_diff, "
-                "conversation_settings_diff, or misc_settings_diff "
-                "must be provided"
+                "conversation_settings_diff, misc_settings_diff, "
+                "or active_profile must be provided"
             ),
         )
 
@@ -265,6 +268,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,
+        active_profile=settings.active_profile,
         misc_settings=settings.misc_settings,
     )
 

{openhands_agent_server-1.27.1 → openhands_agent_server-1.28.1}/openhands_agent_server.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-agent-server
-Version: 1.27.1
+Version: 1.28.1
 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
@@ -12,6 +12,7 @@ Requires-Dist: alembic>=1.13
 Requires-Dist: docker<8,>=7.1
 Requires-Dist: fastapi>=0.104
 Requires-Dist: openhands-sdk
+Requires-Dist: openai<3,>=2.33.0
 Requires-Dist: pydantic>=2
 Requires-Dist: sqlalchemy>=2
 Requires-Dist: uvicorn>=0.31.1

{openhands_agent_server-1.27.1 → openhands_agent_server-1.28.1}/openhands_agent_server.egg-info/SOURCES.txt

@@ -45,6 +45,10 @@ pyproject.toml
 ./openhands/agent_server/docker/Dockerfile
 ./openhands/agent_server/docker/build.py
 ./openhands/agent_server/docker/wallpaper.svg
+./openhands/agent_server/openai/__init__.py
+./openhands/agent_server/openai/models.py
+./openhands/agent_server/openai/router.py
+./openhands/agent_server/openai/service.py
 ./openhands/agent_server/persistence/__init__.py
 ./openhands/agent_server/persistence/models.py
 ./openhands/agent_server/persistence/store.py
@@ -96,6 +100,10 @@ openhands/agent_server/workspaces_router.py
 openhands/agent_server/docker/Dockerfile
 openhands/agent_server/docker/build.py
 openhands/agent_server/docker/wallpaper.svg
+openhands/agent_server/openai/__init__.py
+openhands/agent_server/openai/models.py
+openhands/agent_server/openai/router.py
+openhands/agent_server/openai/service.py
 openhands/agent_server/persistence/__init__.py
 openhands/agent_server/persistence/models.py
 openhands/agent_server/persistence/store.py

{openhands_agent_server-1.27.1 → openhands_agent_server-1.28.1}/openhands_agent_server.egg-info/requires.txt

@@ -3,6 +3,7 @@ alembic>=1.13
 docker<8,>=7.1
 fastapi>=0.104
 openhands-sdk
+openai<3,>=2.33.0
 pydantic>=2
 sqlalchemy>=2
 uvicorn>=0.31.1

{openhands_agent_server-1.27.1 → openhands_agent_server-1.28.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openhands-agent-server"
-version = "1.27.1"
+version = "1.28.1"
 description = "OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent"
 
 requires-python = ">=3.12"
@@ -10,6 +10,7 @@ dependencies = [
   "docker>=7.1,<8",
   "fastapi>=0.104",
   "openhands-sdk",
+  "openai>=2.33.0,<3",
   "pydantic>=2",
   "sqlalchemy>=2",
   "uvicorn>=0.31.1",