Skip to content

refactor(agent-server): typed ServiceInactive instead of the "inactive_service" string - #6910

Merged
enyst merged 1 commit into
mainfrom
claude/project-thread-c8gf4k
Nov 16, 2026
Merged

enyst merged 1 commit into
mainfrom
claude/project-thread-c8gf4k

Conversation

@enyst

@enyst enyst commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

HUMAN:

lets open a PR to main for inactive service. in pr descr say where was it added, too, in what pr for what


AGENT:

Why

The agent server says "this service is not running" with raise ValueError("inactive_service"), and code that must tell it apart from a bad-input ValueError compares strings (if str(exc) == "inactive_service": raise). A reworded message or a typo would silently turn a server-state error into a 400. A type says the same thing and lets callers catch it.

Where "inactive_service" came from

  • Added in Ported over agent server code #317, "Ported over agent server code" (Tim O'Farrell, merged 2025-09-17), the PR that moved the agent server into this repo ("Moved from its temp home in OpenHands-Server"). It was there from the first version, as a lifecycle guard:
    • ConversationService raised it when _event_services is None, i.e. the service is used before __aenter__ or after __aexit__ (get/search/count/start/pause/resume/delete conversation).
    • EventService raised it when _conversation is None, i.e. before start() or after close (get/search/count events, send message).
  • Every later service method copied the same guard; it grew to 52 raises on main (18 in conversation_service.py, 34 in event_service.py; 87 lines mention the string across code and tests).
  • The string comparisons came later: the reactions route (feat(agent-server): Conversation reactions, the first experimental feature #6609) and the ask_user answer route (feat: ask_user tool for decision cards, behind an experimental feature #6852) re-raise it before mapping other ValueErrors to 400.
  • error_classification (feat(sdk): classify conversation errors #4316) lists "inactive_service" among the configuration-error texts it matches.

Summary

  • New ServiceInactive(ValueError) in event_service.py, next to CondensationUnavailable; its message is still "inactive_service". All 52 raises use it.
  • The reactions and ask_user routes catch ServiceInactive and re-raise it, instead of comparing str(exc).
  • Docstrings and comments name the type; tests assert the type. New router tests check that the reactions and ask_user routes do not turn it into a 400.
  • No external change: it is still a ValueError with the same message, so routes that map ValueError to 400 still do, and error_classification's text match still works.

Issue Number

Fixes #6909

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 without this change. Pre-commit (ruff, pycodestyle, pyright, the repo's custom checks) passes on the changed files. grep -rn 'ValueError("inactive_service")\|== "inactive_service"' openhands-agent-server finds nothing.

Video/Screenshots

Not a visual change.

Type

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

Notes


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:6a39a25-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

  • Each variant tag (e.g., 6a39a25-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., 6a39a25-python-amd64) are also available if needed

…e" string

ConversationService and EventService raised ValueError("inactive_service")
in 52 places when used outside their running lifetime, and two event routes
told it apart from bad requests by comparing str(exc). ServiceInactive
replaces the string. It stays a ValueError with the same message, so REST
answers and error classification do not change; the routes now catch the
type.

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:04
@github-actions

Copy link
Copy Markdown
Contributor

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

@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: In-repo and correctly placed — the agent server is owned by this repository, and the change follows the typed-refusal style established in #6602 (ValueError subclasses that keep the old message).

Verified against issue #6909's acceptance criteria on head 6a39a25a:

  • No raise ValueError("inactive_service") and no str(exc) == "inactive_service" remain in the agent server; all 52 raise sites now use ServiceInactive (18 in conversation_service.py, 34 in event_service.py). The only remaining "inactive_service" strings are the exception's own message and the error_classification text list, both intentional.
  • External behavior is preserved: ServiceInactive is still a ValueError with message "inactive_service", so routes that map ValueError to 400 keep doing so (e.g. switch_llm, switch_acp_model/effort, add_mcp_servers, load_plugin), and error_classification's substring match still classifies it as CONFIG. The substring-based handlers in navigate and fork are unaffected ("inactive_service" contains none of event_id/already exists/from_event_id, so those re-raise as before).
  • react_to_message and answer_ask_user re-raise the typed exception before the generic ValueError → 400 mapping, matching the previous string-comparison behavior, with new router tests covering it.
  • No REST/OpenAPI contract change (REST API OpenAPI and schema checks pass on this head).

Testing: Focused suites for all seven changed test files pass in the workspace (test_reactions_router, test_ask_user_router, test_event_socket_races, test_conversation_response, test_conversation_service, test_event_service, test_conversation_router — 436 tests). Completed CI on this head is green for the code checks (agent-server-api, agent-server-stress-tests, pre-commit, REST API (OpenAPI), Check OpenAPI Schema, security, sdk/workspace/tools/windows tests, smoke-test, endpoint-audit, public-type-budget, persisted-settings).

Note on the one failing check: "Validate PR description" fails only because linked issue #6909 (created 2026-11-16T23:03Z, after the rollout date) carries neither ready-for-dev nor a pre-rollout creation date. That is the repository's issue-readiness governance gate, not a defect in this head; issue labeling is owned by the automation flow and outside this review's scope.

No material correctness, security, or compatibility findings.

✅ APPROVED

@github-actions

Copy link
Copy Markdown
Contributor

Agent-server conversation start benchmark

Base main@1fab111222a6d141a97a360e0d12a348de98fe4c vs this PR merge d92eb543a8, 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.121 s [0.113, 0.149] 0.113 s [0.102, 0.127] -6% ≈ same
↳ first agent event 0.166 s [0.151, 0.196] 0.153 s [0.143, 0.168] -8% ≈ same
First create right after server start 0.202 s [0.112, 1.181] 0.238 s [0.137, 0.467] +18% ≈ same
↳ first agent event 0.390 s [0.231, 1.472] 0.372 s [0.255, 0.805] -5% ≈ same
First create 3 s after server start 0.130 s [0.119, 0.202] 0.143 s [0.125, 0.204] +10% ≈ same
↳ first agent event 0.282 s [0.253, 0.461] 0.334 s [0.297, 0.426] +18% ≈ same
Create in a new git worktree (warm, 0.5 s git fetch) 0.651 s [0.637, 0.696] 0.669 s [0.644, 0.733] +3% ≈ same
↳ first agent event 0.688 s [0.674, 0.749] 0.709 s [0.684, 0.782] +3% ≈ same
Worktree creates that stalled the server > 20 ms 0/20 (0%) 0/20 (0%) +0 pts ≈ same
Create with one stdio MCP server (warm, 3 s startup) 1.126 s [1.108, 1.142] 1.114 s [1.096, 1.190] -1% ≈ same
↳ first agent event 3.810 s [3.687, 3.959] 3.749 s [3.684, 4.075] -2% ≈ same
Creates that stalled the server > 20 ms 3/35 (9%) 3/35 (9%) +0 pts ≈ same
Server startup (/alive) 4.125 s [3.786, 5.162] 4.313 s [3.774, 4.650] +5% ≈ 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-y2amq6mtk53wguwo, 176 environment variables. Run it locally with python scripts/agent_server_benchmarks/conversation_start.py --help.

@github-actions

Copy link
Copy Markdown
Contributor

Coverage

Coverage Report •
FileStmtsMissCoverMissing
openhands-agent-server/openhands/agent_server
   conversation_router.py3311695%123–124, 127–128, 340, 474, 523, 608, 783, 845–847, 891, 928–929, 960
   conversation_service.py130010492%209–210, 292, 313, 502–503, 675, 682–683, 783, 834–835, 839, 844, 894, 946–947, 954, 987–988, 1004, 1036, 1040, 1053, 1073, 1094–1095, 1104, 1173, 1183, 1208, 1214–1215, 1219–1220, 1228, 1255, 1261, 1355, 1361, 1366, 1372, 1380–1381, 1390–1393, 1402, 1415, 1433, 1470, 1474–1478, 1501, 1550, 1570, 1580, 1847, 1874–1877, 1931, 2060, 2063, 2070–2072, 2075–2076, 2082, 2092, 2096, 2125, 2134, 2193–2195, 2226, 2358, 2361, 2388, 2398, 2403–2406, 2420, 2431, 2443–2444, 2476, 2576, 2643, 2701, 2716–2717, 3121, 3174, 3177
   event_router.py160696%343, 353, 356–357, 414–415
   event_service.py117111690%206, 212–213, 347–348, 472, 476, 481, 508, 515, 550, 553–554, 558–559, 570, 576, 647–648, 654, 710–711, 832, 852, 881, 891, 915–916, 920, 973, 1008, 1012–1013, 1048, 1055, 1061, 1278, 1311, 1314, 1392, 1410, 1424, 1597–1598, 1654, 1688, 1844–1847, 1851, 1898, 1902, 1909, 1923, 1939, 1947, 1971, 2018–2020, 2111, 2133, 2136–2137, 2164, 2172, 2188, 2190, 2197, 2205, 2207–2208, 2212, 2229, 2249, 2302, 2307–2311, 2316, 2325–2326, 2333, 2348, 2359, 2400–2403, 2487–2488, 2490–2497, 2499–2500, 2510, 2521, 2537–2538, 2549, 2576, 2582, 2593, 2602–2603, 2625, 2635
TOTAL570742173362% 

@enyst
enyst merged commit 98c8cd3 into main Nov 16, 2026
53 of 54 checks passed
@enyst
enyst deleted the claude/project-thread-c8gf4k branch November 16, 2026 23:23
enyst pushed a commit that referenced this pull request Nov 16, 2026
Projects' own inactive_service raises and the coordinator delivery now use
ServiceInactive too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
@enyst enyst mentioned this pull request Nov 17, 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: replace the "inactive_service" error string with a typed exception

3 participants