Skip to content

refactor(agent-server): move service exceptions into an exceptions module - #6912

Merged
enyst merged 2 commits into
mainfrom
claude/project-thread-c8gf4k
Nov 18, 2026
Merged

enyst merged 2 commits into
mainfrom
claude/project-thread-c8gf4k

Conversation

@enyst

@enyst enyst commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

HUMAN:

ugh bunch of exceptions are defined inside event service, dont they belong in exceptions file or models somewhere?

yeah lets move them in an exceptions module
to clean up as you said


AGENT:

Why

The conversation and event services declared their exceptions inline. Both services raise ServiceInactive (#6910), so conversation_service.py imported an exception from event_service.py, and routers, sockets and credential_binding.py imported exception types from the two largest modules in the server. errors.py is the HTTP mapping for SDK domain errors, so it is not their home either.

Summary

  • New openhands/agent_server/exceptions.py, in the spirit of the SDK's openhands/sdk/conversation/exceptions.py, with the seven service exceptions: ServiceInactive, ConversationRunLimitExceeded, CondensationUnavailable, InvalidParentConversation, UnavailableAgentTool, CredentialBindingActivationRequired, CredentialBindingActivationTooLate.
  • Names, bases and messages are unchanged. CredentialBindingActivationTooLate gains a docstring (it was pass).
  • event_service.py and conversation_service.py no longer define exceptions; every caller (routers, sockets, credential_binding.py, tests) imports from exceptions.
  • Left in place on purpose: exceptions that belong to their own small modules (conversation_lease.py, pub_sub.py, git_provider_service.py, docker_runtime/registry.py, openai/service.py), and errors.py's ForwardedStatus.

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_server 3288 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 on main. 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 (ConversationRunLimitExceeded stays the ServerErrorEvent.code, since it is the class name).

Video/Screenshots

Not a visual change.

Type

  • Bug fix
  • Feature
  • Refactor
  • Breaking change
  • Docs / chore

Notes

Code that imported these classes from openhands.agent_server.event_service or openhands.agent_server.conversation_service must import them from openhands.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

Variant Architectures Base Image Docs / Tags
java amd64, arm64 eclipse-temurin:17-jdk Link
python-slim amd64, arm64 python-node-runtime Link
python-minimal amd64, arm64 python-node-runtime Link
python amd64, arm64 python-node-runtime Link
golang amd64, arm64 golang:1.21-bookworm Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:57e9ab8-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-57e9ab8-python \
  ghcr.io/openhands/agent-server:57e9ab8-python

All tags pushed for this build

ghcr.io/openhands/agent-server:57e9ab8-golang-amd64
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-golang-amd64
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-golang-amd64
ghcr.io/openhands/agent-server:57e9ab8-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:57e9ab8-golang-arm64
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-golang-arm64
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-golang-arm64
ghcr.io/openhands/agent-server:57e9ab8-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:57e9ab8-java-amd64
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-java-amd64
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-java-amd64
ghcr.io/openhands/agent-server:57e9ab8-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:57e9ab8-java-arm64
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-java-arm64
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-java-arm64
ghcr.io/openhands/agent-server:57e9ab8-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:57e9ab8-python-amd64
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-python-amd64
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-python-amd64
ghcr.io/openhands/agent-server:57e9ab8-python-node-runtime-amd64
ghcr.io/openhands/agent-server:57e9ab8-python-arm64
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-python-arm64
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-python-arm64
ghcr.io/openhands/agent-server:57e9ab8-python-node-runtime-arm64
ghcr.io/openhands/agent-server:57e9ab8-python-minimal-amd64
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-python-minimal-amd64
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-python-minimal-amd64
ghcr.io/openhands/agent-server:57e9ab8-python-node-runtime-minimal-amd64
ghcr.io/openhands/agent-server:57e9ab8-python-minimal-arm64
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-python-minimal-arm64
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-python-minimal-arm64
ghcr.io/openhands/agent-server:57e9ab8-python-node-runtime-minimal-arm64
ghcr.io/openhands/agent-server:57e9ab8-python-slim-amd64
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-python-slim-amd64
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-python-slim-amd64
ghcr.io/openhands/agent-server:57e9ab8-python-node-runtime-slim-amd64
ghcr.io/openhands/agent-server:57e9ab8-python-slim-arm64
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-python-slim-arm64
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-python-slim-arm64
ghcr.io/openhands/agent-server:57e9ab8-python-node-runtime-slim-arm64
ghcr.io/openhands/agent-server:57e9ab8-golang
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-golang
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-golang
ghcr.io/openhands/agent-server:57e9ab8-golang_tag_1.21-bookworm
ghcr.io/openhands/agent-server:57e9ab8-java
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-java
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-java
ghcr.io/openhands/agent-server:57e9ab8-eclipse-temurin_tag_17-jdk
ghcr.io/openhands/agent-server:57e9ab8-python-minimal
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-python-minimal
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-python-minimal
ghcr.io/openhands/agent-server:57e9ab8-python-node-runtime-minimal
ghcr.io/openhands/agent-server:57e9ab8-python-slim
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-python-slim
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-python-slim
ghcr.io/openhands/agent-server:57e9ab8-python-node-runtime-slim
ghcr.io/openhands/agent-server:57e9ab8-python
ghcr.io/openhands/agent-server:57e9ab8cde335335d4e1a3a8f7c9fd9ba1a0299d-python
ghcr.io/openhands/agent-server:claude-project-thread-c8gf4k-python
ghcr.io/openhands/agent-server:57e9ab8-python-node-runtime

About Multi-Architecture Support

  • Each variant tag (e.g., 57e9ab8-python) is a multi-arch manifest supporting both amd64 and arm64
  • Docker automatically pulls the correct architecture for your platform
  • Individual architecture tags (e.g., 57e9ab8-python-amd64) are also available if needed

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
@enyst enyst self-assigned this Nov 16, 2026
@enyst
enyst requested a review from all-hands-bot November 16, 2026 23:32
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Agent-server conversation start benchmark

Base main@f765648dd56dc01c4302b6de669ab067f5bd6ae9 vs this PR merge 6202102047, measured in the same job on the same runner, interleaved: 5 server starts per side and scenario. Medians with 95% bootstrap CIs. The LLM is a mock that answers instantly, so this is agent-server overhead only.

base this PR change
Create conversation (warm) 0.147 s [0.137, 0.163] 0.153 s [0.143, 0.162] +4% ≈ same
↳ first agent event 0.207 s [0.203, 0.234] 0.215 s [0.201, 0.230] +4% ≈ same
First create right after server start 0.462 s [0.145, 0.500] 0.786 s [0.445, 1.025] +70% ≈ same
↳ first agent event 0.734 s [0.312, 0.801] 1.052 s [0.638, 1.242] +43% ≈ same
First create 3 s after server start 0.177 s [0.150, 0.258] 0.177 s [0.162, 0.195] +0% ≈ same
↳ first agent event 0.410 s [0.371, 0.515] 0.409 s [0.350, 0.472] -0% ≈ same
Create in a new git worktree (warm, 0.5 s git fetch) 0.694 s [0.681, 0.702] 0.714 s [0.693, 0.743] +3% ≈ same
↳ first agent event 0.751 s [0.731, 0.770] 0.788 s [0.748, 0.809] +5% ≈ same
Worktree creates that stalled the server > 20 ms 1/20 (5%) 1/20 (5%) +0 pts ≈ same
Create with one stdio MCP server (warm, 3 s startup) 1.158 s [1.144, 1.168] 1.142 s [1.132, 1.159] -1% ≈ same
↳ first agent event 4.191 s [3.974, 4.272] 4.137 s [4.060, 4.237] -1% ≈ same
Creates that stalled the server > 20 ms 2/35 (6%) 1/35 (3%) -3 pts ≈ same
Server startup (/alive) 5.916 s [4.828, 6.367] 6.303 s [5.826, 6.677] +7% ≈ same
How this is measured

Each create is a Canvas-shaped POST /api/conversations (agent profile, worktree: true, first message included, so the request waits for agent startup). A side task polls /alive every 20 ms to catch event-loop stalls. Scenarios, each on its own server starts:

  • default: a fresh directory per create, 8 creates per start.
  • pause: the first create waits 3 s after startup, as a user opening the UI would.
  • worktree: every create branches a new worktree from a local repository whose origin answers fetches after 0.5 s.
  • mcp: the agent profile enables one stdio MCP server that starts after 3 s, like an npx/uvx launch.

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 /alive took over 20 ms; stall rows are flagged when the share of stalled creates moves by at least 20 points with a Fisher exact p below 0.01. The first-create rows have one sample per server start, so they are flagged only on a clear change. A "↳ first agent event" row times the create above it until the agent's first event arrives on a socket opened after the create returns, as Agent Canvas does, so it includes the connect and replay. Runner: blacksmith-2vcpu-ubuntu-2404-34qq65kzijpzchji, 176 environment variables. Run it locally with python scripts/agent_server_benchmarks/conversation_start.py --help.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Coverage

Coverage Report •
FileStmtsMissCoverMissing
openhands-agent-server/openhands/agent_server
   conversation_router.py3331695%125–126, 129–130, 342, 476, 525, 610, 785, 847–849, 893, 930–931, 962
   conversation_service.py130910492%210–211, 293, 314, 498–499, 672, 679–680, 780, 831–832, 836, 841, 891, 943–944, 951, 984–985, 1001, 1033, 1037, 1050, 1070, 1091–1092, 1101, 1170, 1180, 1205, 1211–1212, 1216–1217, 1225, 1252, 1258, 1352, 1358, 1363, 1369, 1377–1378, 1387–1390, 1399, 1412, 1430, 1467, 1471–1475, 1498, 1547, 1567, 1577, 1859, 1888–1891, 1945, 2073, 2076, 2083–2085, 2088–2089, 2095, 2105, 2109, 2138, 2147, 2209–2211, 2242, 2374, 2377, 2404, 2414, 2419–2422, 2436, 2447, 2459–2460, 2492, 2592, 2659, 2717, 2732–2733, 3137, 3190, 3193
   credential_binding.py84989%50, 65–66, 69–70, 89–90, 136, 149
   event_router.py181597%296, 389, 400, 462–463
   event_service.py115211190%193, 199–200, 340–341, 465, 469, 474, 501, 508, 543, 546–547, 551–552, 563, 569, 640–641, 647, 703–704, 825, 844, 873, 883, 906–907, 911, 971, 1006, 1010–1011, 1046, 1053, 1059, 1272, 1305, 1308, 1391, 1409, 1423, 1598–1599, 1655, 1689, 1843–1846, 1850, 1897, 1901, 1908, 1922, 1938, 1946, 1970, 2017–2019, 2110, 2132, 2135–2136, 2163, 2170, 2186, 2188, 2195, 2203, 2205–2206, 2210, 2227, 2245, 2292, 2298, 2300, 2305, 2314–2315, 2321, 2333, 2343, 2381–2383, 2468–2469, 2471–2478, 2480–2481, 2491, 2501, 2517, 2528, 2552, 2558, 2569, 2578–2579, 2601, 2611
   session_socket.py3194885%152, 156–157, 162, 164–167, 180–182, 369, 398, 403–404, 407, 417, 419–420, 423, 443–446, 449, 465, 468, 472, 476, 482, 498, 519, 557–558, 569, 581, 585–587, 592–597, 600–601, 604
   sockets.py2582291%161, 164, 167, 247–248, 252, 264–265, 268, 391–394, 399–400, 405–407, 479, 514, 541, 559
TOTAL573162160362% 

@all-hands-bot all-hands-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.py depends only on openhands.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 ErrorFrame codes are derived from type(e).__name__ (not __module__), so ConversationRunLimitExceeded and friends keep their wire codes; the __module__-qualified check in event_service.py filters event kinds, which these exceptions are not. No coupling in clients/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
@enyst
enyst requested a review from all-hands-bot November 18, 2026 20:04

@all-hands-bot all-hands-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@enyst
enyst merged commit a6b92c2 into main Nov 18, 2026
47 of 48 checks passed
@enyst
enyst deleted the claude/project-thread-c8gf4k branch November 18, 2026 20:26
@enyst enyst mentioned this pull request Nov 19, 2026
1 of 5 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

3 participants