Repository navigation
Description
Is there an existing feature request for this?
- I have searched existing issues and feature requests, and this is not a duplicate.
Problem or Use Case
The agent server's conversation and event services declare their exceptions inline: event_service.py has ServiceInactive, ConversationRunLimitExceeded, CondensationUnavailable and CredentialBindingActivationTooLate; conversation_service.py has InvalidParentConversation, UnavailableAgentTool and CredentialBindingActivationRequired. Both services raise ServiceInactive, so conversation_service.py imports an exception from event_service.py, and routers, sockets and credential_binding.py import exception types from the 2,000+ line service modules. errors.py is the HTTP mapping for SDK domain errors, not a home for them.
Desired Behavior
An openhands/agent_server/exceptions.py module, like the SDK's openhands/sdk/conversation/exceptions.py, holding the service exceptions. Callers import from there.
Acceptance Criteria
- The seven classes above live in
agent_server/exceptions.pywith the same names, bases and messages. - No exception class definitions are left in
event_service.pyorconversation_service.py. - No behavior change: REST answers, socket error codes (
ConversationRunLimitExceededasServerErrorEvent.code) and tests stay the same.
Alternatives Considered
Also moving the self-contained modules' exceptions (conversation_lease.py, pub_sub.py, git_provider_service.py, docker_runtime/registry.py, openai/service.py). Those belong to their own small modules and are fine where they are.
Priority / Severity
Low - Nice to have
Estimated Scope
Small - API addition, config option, or minor change
Feature Area
- Agent Server
Additional Context
Follow-up to #6909 / #6910, which added ServiceInactive.
OpenHands AI triage
The following comments and acceptance criteria were added by the OpenHands AI agent.
Triage
Verified against main: the seven exception classes are defined inline in event_service.py (ServiceInactive, ConversationRunLimitExceeded, CondensationUnavailable, CredentialBindingActivationTooLate) and conversation_service.py (CredentialBindingActivationRequired, InvalidParentConversation, UnavailableAgentTool), and callers in conversation_router.py, event_router.py, session_socket.py, sockets.py, and credential_binding.py import them from these two service modules. errors.py is only the HTTP status mapping for SDK domain errors, so a new openhands/agent_server/exceptions.py mirroring openhands/sdk/conversation/exceptions.py is the authoritative home for them.
Scope is limited to relocating the seven classes to that module and repointing imports; names, bases, constructor behavior, and messages stay identical, so REST error payloads, socket ServerErrorEvent.code values (for example "ConversationRunLimitExceeded"), and the "inactive_service" message are all unchanged. Non-goals: no changes to errors.py or ERROR_STATUS, no relocation of the self-contained modules' exceptions (conversation_lease.py, pub_sub.py, git_provider_service.py, docker_runtime/registry.py, openai/service.py), no REST/OpenAPI contract changes, and no other restructuring of the service modules.
Acceptance Criteria
-
openhands/agent_server/exceptions.pydefinesServiceInactive,ConversationRunLimitExceeded,CondensationUnavailable,CredentialBindingActivationTooLate,CredentialBindingActivationRequired,InvalidParentConversation, andUnavailableAgentToolwith the same names, bases, constructor signatures, and messages as on pre-changemain. -
event_service.pyandconversation_service.pycontain noclassdefinitions for those seven exceptions and import them fromopenhands.agent_server.exceptions. - No module in
openhands-agent-server/ortests/imports any of the seven exception names fromevent_serviceorconversation_service; all importers, includingconversation_router.py,event_router.py,session_socket.py,sockets.py,credential_binding.py, and the tests that reference these names, import fromopenhands.agent_server.exceptions. - The
tests/agent_serversuite passes with only exception import-path updates, keeping unchanged assertions on REST error payloads, the"inactive_service"message, and socketServerErrorEvent.codevalues. - The OpenAPI-schema CI check (
Agent server REST API breakage checks) reports no breaking changes against the previous release baseline, confirming this is a pure import relocation.
Activity