Skip to content

Agent server: move service exceptions out of event_service.py and conversation_service.py #6911

Closed

Description

@enyst

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.py with the same names, bases and messages.
  • No exception class definitions are left in event_service.py or conversation_service.py.
  • No behavior change: REST answers, socket error codes (ConversationRunLimitExceeded as ServerErrorEvent.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.py defines ServiceInactive, ConversationRunLimitExceeded, CondensationUnavailable, CredentialBindingActivationTooLate, CredentialBindingActivationRequired, InvalidParentConversation, and UnavailableAgentTool with the same names, bases, constructor signatures, and messages as on pre-change main.
  • event_service.py and conversation_service.py contain no class definitions for those seven exceptions and import them from openhands.agent_server.exceptions.
  • No module in openhands-agent-server/ or tests/ imports any of the seven exception names from event_service or conversation_service; all importers, including conversation_router.py, event_router.py, session_socket.py, sockets.py, credential_binding.py, and the tests that reference these names, import from openhands.agent_server.exceptions.
  • The tests/agent_server suite passes with only exception import-path updates, keeping unchanged assertions on REST error payloads, the "inactive_service" message, and socket ServerErrorEvent.code values.
  • 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

  1. added
    priority:lowFor bugs, affects only non-mainstream cases, or is annoying but with a clear workaround.
    ready-for-devIssue meets development readiness criteria
    on Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestpriority:lowFor bugs, affects only non-mainstream cases, or is annoying but with a clear workaround.ready-for-devIssue meets development readiness criteria

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions