Repository navigation
refactor(agent-server): move service exceptions into an exceptions module - #6912
Conversation
ConversationService and EventService declared their exceptions inline, so conversation_service.py imported ServiceInactive from event_service.py and routers imported exceptions from the services. They now live in openhands/agent_server/exceptions.py: ServiceInactive, ConversationRunLimitExceeded, CondensationUnavailable, InvalidParentConversation, UnavailableAgentTool, CredentialBindingActivationRequired and CredentialBindingActivationTooLate. Names, bases and messages are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwLYPA4zfbsUTU75ee4
REST API breakage checks (OpenAPI) — ✅ PASSEDResult: ✅ PASSED |
Agent-server conversation start benchmarkBase
How this is measuredEach create is a Canvas-shaped
A timing is flagged when the 95% CIs do not overlap and the medians differ by at least 50 ms, or when a row with at least 8 samples per side moves by at least 150 ms and 25%. A create stalled the server when its slowest |
Coverage Report •
|
||||||||||||||||||||||||||||||||||||||||||||||||||
all-hands-bot
left a comment
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands).
Scope: The change belongs in this repository — it refactors agent-server Python code (the canonical REST/WebSocket API owner) and implements linked issue #6911 exactly as requested. Head 57e9ab8c matches, PR state is OPEN, and no earlier review exists on this head.
Review: Verified as a pure mechanical move. All seven exception classes were relocated verbatim to openhands/agent_server/exceptions.py (same names, bases, messages, and __init__ bodies; only CredentialBindingActivationTooLate gains a docstring, which is a pure improvement). Checked specifically for:
- Import graph:
exceptions.pydepends only onopenhands.sdk.errors, so no circular imports; every consumer (routers, sockets,credential_binding.py, tests) now imports from the new module, and grep across all packages, tests, and examples finds no stale importer of the old locations. - Wire compatibility: socket/gateway error codes and
ErrorFramecodes are derived fromtype(e).__name__(not__module__), soConversationRunLimitExceededand friends keep their wire codes; the__module__-qualified check inevent_service.pyfilters event kinds, which these exceptions are not. No coupling inclients/typescript. - HTTP mapping: re-verified
status_for()behavior (429 / 409 / 500 paths) is unchanged since bases are unchanged. - No cross-process exception transport (pickling) exists for these classes in the server.
Verification in workspace: focused agent-server tests on all touched paths pass identically on base and head (576/576 parity); test_credential_binding.py shows a byte-identical set of 13 pre-existing environment-related failures on both 98c8cd30 and this head, so not attributable to this PR. Pre-commit (ruff, pycodestyle, pyright, import dependency rules, secret and store-IO hooks) passes on all changed server files. No tracked files were modified.
Non-blocking CI note: the Validate PR description check fails on this head. It is a description-template linter result, not a code defect; the HUMAN: section is filled with the contributor's own words per repo policy, so no action is required from this review.
✅ APPROVED
…-c8gf4k # Conflicts: # openhands-agent-server/openhands/agent_server/event_router.py
all-hands-bot
left a comment
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands).
Fresh review of the new head 5036f663 (branch merged origin/main since the previous review of 57e9ab8c; re-requested, so re-verified — not a duplicate of the prior review of the old head). No human comments were posted since that review.
Scope: Unchanged — the PR belongs in this repository and implements open issue #6911 (currently labeled enhancement, priority:low, ready-for-dev).
PR content vs current main: The diff remains the identical pure move verified before — openhands/agent_server/exceptions.py is byte-identical to the previously reviewed head, with the same seven verbatim exception classes, +88/−78 across the same 16 files (services, routers, sockets, credential_binding.py, tests). Every consumer imports from exceptions; grep finds no stale importer of the old locations. The merge brought in unrelated main commits (GatewayTimeout headers, SenderError, run_state_op), but those are main's own content and do not alter the PR-only diff.
Current-head CI: All checks pass on 5036f663 — including Validate PR description (previously failing), agent-server-tests, cross-tests, integration-test, REST API (OpenAPI), CodeQL, and all image builds. No failing checks.
Verification in workspace (this exact SHA): Focused agent-server tests across all touched paths: 614 passed, 13 failed — and the 13 failures (test_credential_binding.py git-worktree environment issues) are a byte-identical set on merge-base f765648d, so not attributable to this PR. No tracked files were modified.
No material correctness, security, or compatibility findings.
✅ APPROVED
HUMAN:
AGENT:
Why
The conversation and event services declared their exceptions inline. Both services raise
ServiceInactive(#6910), soconversation_service.pyimported an exception fromevent_service.py, and routers, sockets andcredential_binding.pyimported exception types from the two largest modules in the server.errors.pyis the HTTP mapping for SDK domain errors, so it is not their home either.Summary
openhands/agent_server/exceptions.py, in the spirit of the SDK'sopenhands/sdk/conversation/exceptions.py, with the seven service exceptions:ServiceInactive,ConversationRunLimitExceeded,CondensationUnavailable,InvalidParentConversation,UnavailableAgentTool,CredentialBindingActivationRequired,CredentialBindingActivationTooLate.CredentialBindingActivationTooLategains a docstring (it waspass).event_service.pyandconversation_service.pyno longer define exceptions; every caller (routers, sockets,credential_binding.py, tests) imports fromexceptions.conversation_lease.py,pub_sub.py,git_provider_service.py,docker_runtime/registry.py,openai/service.py), anderrors.py'sForwardedStatus.Issue Number
Fixes #6911
How to Test
uv run pytest -n 8 tests/agent_server uv run pre-commit run --files $(git diff --name-only origin/main)Locally:
tests/agent_server3288 passed, 8 skipped, 1 failed. The failure,test_canvas_extension_backend.py::test_exited_leader_descendant_does_not_block_recovery[status], fails the same way onmain. Pre-commit (ruff, pycodestyle, pyright, import dependency rules and the repo's other checks) passes. Pure move: no REST, OpenAPI or socket error-code change (ConversationRunLimitExceededstays theServerErrorEvent.code, since it is the class name).Video/Screenshots
Not a visual change.
Type
Notes
Code that imported these classes from
openhands.agent_server.event_serviceoropenhands.agent_server.conversation_servicemust import them fromopenhands.agent_server.exceptions. Nothing outside this repo does today (checked OpenHands/OpenHands).Generated by Claude Code
🐳 Agent Server images for this PR — GHCR package, pull/run commands, and all pushed tags (click to expand)
• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server
Variants & Base Images
eclipse-temurin:17-jdkpython-node-runtimepython-node-runtimepython-node-runtimegolang:1.21-bookwormPull (multi-arch manifest)
# Each variant is a multi-arch manifest supporting both amd64 and arm64 docker pull ghcr.io/openhands/agent-server:57e9ab8-pythonRun
All tags pushed for this build
About Multi-Architecture Support
57e9ab8-python) is a multi-arch manifest supporting both amd64 and arm6457e9ab8-python-amd64) are also available if needed