Skip to content

refactor(agent-server): typed "already running" errors instead of string matching - #7007

Merged
enyst merged 1 commit into
mainfrom
claude/project-thread-xwkk9b-typed-running
Nov 19, 2026
Merged

enyst merged 1 commit into
mainfrom
claude/project-thread-xwkk9b-typed-running

Conversation

@enyst

@enyst enyst commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

HUMAN:

Let's separate these 3 in their own PR from main now, and tell the thread on green CI to ask all-hands-bot for review


AGENT:

Why

EventService.run and the goal loop refused a busy conversation with ValueError("conversation_already_running") or ValueError("goal_already_running"), and every caller compared str(e) to tell those apart from other ValueErrors. The goal loop's messages also used the bare literal "goal" as their sender. This was split out of #6602, which builds on both.

Summary

  • New ConversationAlreadyRunning and GoalAlreadyRunning in openhands/agent_server/exceptions.py. Both are ValueError subclasses with the same messages as before, so callers that still catch ValueError and match the message keep working.
  • event_service.py raises them, and event_service.py and conversation_router.py catch the type instead of the string. Behavior is unchanged: other ValueErrors are still swallowed or re-raised exactly where they were.
  • GOAL_LOOP_SENDER = "goal" in openhands.sdk.conversation.types, used by the goal runner and EventService.send_message.

The third item Engel listed, the moved ASK_USER definition, is diff noise inside #6602 and has nothing to change on main, so it's fixed there instead.

Issue Number

Fixes #7008

How to Test

  • uv run pytest -n 8 tests/agent_server tests/sdk/conversation: 4414 passed, 1 failed. The failure, test_canvas_extension_backend.py::test_exited_leader_descendant_does_not_block_recovery[status], also fails on main in this environment.
  • ruff check, ruff format and pyright pass on the changed files.
  • No REST or OpenAPI change: the routes answer the same 409s.

Video/Screenshots

Not a visual change.

Type

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

Notes

#6602 keeps a copy of this change until this PR merges.

🤖 Generated with Claude Code

https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E


🐳 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:74a03a1-python

Run

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

All tags pushed for this build

ghcr.io/openhands/agent-server:74a03a1-golang-amd64
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-golang-amd64
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-golang-amd64
ghcr.io/openhands/agent-server:74a03a1-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:74a03a1-golang-arm64
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-golang-arm64
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-golang-arm64
ghcr.io/openhands/agent-server:74a03a1-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:74a03a1-java-amd64
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-java-amd64
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-java-amd64
ghcr.io/openhands/agent-server:74a03a1-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:74a03a1-java-arm64
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-java-arm64
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-java-arm64
ghcr.io/openhands/agent-server:74a03a1-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:74a03a1-python-amd64
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-python-amd64
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-python-amd64
ghcr.io/openhands/agent-server:74a03a1-python-node-runtime-amd64
ghcr.io/openhands/agent-server:74a03a1-python-arm64
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-python-arm64
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-python-arm64
ghcr.io/openhands/agent-server:74a03a1-python-node-runtime-arm64
ghcr.io/openhands/agent-server:74a03a1-python-minimal-amd64
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-python-minimal-amd64
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-python-minimal-amd64
ghcr.io/openhands/agent-server:74a03a1-python-node-runtime-minimal-amd64
ghcr.io/openhands/agent-server:74a03a1-python-minimal-arm64
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-python-minimal-arm64
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-python-minimal-arm64
ghcr.io/openhands/agent-server:74a03a1-python-node-runtime-minimal-arm64
ghcr.io/openhands/agent-server:74a03a1-python-slim-amd64
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-python-slim-amd64
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-python-slim-amd64
ghcr.io/openhands/agent-server:74a03a1-python-node-runtime-slim-amd64
ghcr.io/openhands/agent-server:74a03a1-python-slim-arm64
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-python-slim-arm64
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-python-slim-arm64
ghcr.io/openhands/agent-server:74a03a1-python-node-runtime-slim-arm64
ghcr.io/openhands/agent-server:74a03a1-golang
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-golang
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-golang
ghcr.io/openhands/agent-server:74a03a1-golang_tag_1.21-bookworm
ghcr.io/openhands/agent-server:74a03a1-java
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-java
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-java
ghcr.io/openhands/agent-server:74a03a1-eclipse-temurin_tag_17-jdk
ghcr.io/openhands/agent-server:74a03a1-python-minimal
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-python-minimal
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-python-minimal
ghcr.io/openhands/agent-server:74a03a1-python-node-runtime-minimal
ghcr.io/openhands/agent-server:74a03a1-python-slim
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-python-slim
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-python-slim
ghcr.io/openhands/agent-server:74a03a1-python-node-runtime-slim
ghcr.io/openhands/agent-server:74a03a1-python
ghcr.io/openhands/agent-server:74a03a1bdc31cc55879461dd88837376b45ed183-python
ghcr.io/openhands/agent-server:claude-project-thread-xwkk9b-typed-running-python
ghcr.io/openhands/agent-server:74a03a1-python-node-runtime

About Multi-Architecture Support

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

EventService.run and the goal loop raise ConversationAlreadyRunning and
GoalAlreadyRunning (ValueError subclasses with the same messages), and
callers catch the type instead of comparing str(e). The goal loop's
sender becomes the GOAL_LOOP_SENDER constant.

Co-authored-by: openhands <openhands@all-hands.dev>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Agent-server conversation start benchmark

Base main@45cf668c5e2af38c6cc8c2eb6ae4f0d6f828e4c3 vs this PR merge 635addaf48, 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.131 s [0.121, 0.139] 0.142 s [0.126, 0.146] +9% ≈ same
↳ first agent event 0.181 s [0.172, 0.188] 0.196 s [0.176, 0.201] +8% ≈ same
First create right after server start 0.403 s [0.198, 0.439] 0.408 s [0.339, 0.433] +1% ≈ same
↳ first agent event 0.584 s [0.431, 0.711] 0.612 s [0.509, 0.631] +5% ≈ same
First create 3 s after server start 0.166 s [0.112, 0.176] 0.170 s [0.161, 0.235] +2% ≈ same
↳ first agent event 0.337 s [0.240, 0.401] 0.347 s [0.343, 0.450] +3% ≈ same
Create in a new git worktree (warm, 0.5 s git fetch) 0.690 s [0.669, 0.701] 0.672 s [0.658, 0.695] -3% ≈ same
↳ first agent event 0.743 s [0.720, 0.751] 0.724 s [0.696, 0.739] -2% ≈ 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.130 s [1.121, 1.144] 1.127 s [1.115, 1.138] -0% ≈ same
↳ first agent event 3.841 s [3.762, 4.058] 3.817 s [3.760, 3.979] -1% ≈ same
Creates that stalled the server > 20 ms 1/35 (3%) 0/35 (0%) -3 pts ≈ same
Server startup (/alive) 4.722 s [4.414, 4.846] 4.696 s [4.438, 5.006] -1% ≈ 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-qpcrdrfeky7n622q, 176 environment variables. Run it locally with python scripts/agent_server_benchmarks/conversation_start.py --help.

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Coverage

Coverage Report •
FileStmtsMissCoverMissing
openhands-agent-server/openhands/agent_server
   conversation_router.py3662294%133–134, 137–138, 350, 482–483, 530, 616, 697, 713, 770, 774–775, 875, 937–939, 983, 1020–1021, 1052
   event_service.py115711490%198, 204–205, 345–346, 470, 474, 479, 506, 513, 548, 551–552, 556–557, 568, 574, 645–646, 652, 708–709, 830, 849, 878, 888, 911–912, 916, 976, 1011–1013, 1016, 1038–1039, 1050, 1057, 1063, 1276, 1309, 1312, 1395, 1413, 1427, 1602–1603, 1659, 1693, 1847–1849, 1898, 1902, 1909, 1923, 1939, 1947, 1971, 2018–2019, 2110, 2132, 2135–2136, 2163, 2170, 2186, 2188, 2195, 2203, 2205, 2222, 2240, 2287, 2298–2301, 2310, 2315, 2317, 2322, 2331–2332, 2338, 2350, 2360, 2398–2400, 2485–2486, 2488–2495, 2497–2498, 2508, 2518, 2534, 2545, 2569, 2575, 2586, 2595–2596, 2618, 2628
openhands-sdk/openhands/sdk/conversation
   types.py93595%130, 149, 151, 153, 158
openhands-sdk/openhands/sdk/conversation/goal
   runner.py19289%57, 65
TOTAL57747931584% 

@enyst enyst closed this Nov 19, 2026
@enyst enyst reopened this Nov 19, 2026
@enyst
enyst requested a review from all-hands-bot November 19, 2026 16:46
@all-hands-bot

Copy link
Copy Markdown
Collaborator

⏳ Review waiting on checks

The current head 74a03a1bdc31 still has checks that have not finished, so no review conversation was started:

  • Build & Push (golang-arm64)
  • Build & Push (java-amd64)
  • Build & Push (java-arm64)
  • Build & Push (python-amd64)
  • Build & Push (python-arm64)

No action is needed. The scheduled scan retries once every check on the head reports a conclusion.

This is an automated check - no AI was used to generate this comment.

@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).

Review

The refactor is correct and behavior-preserving. ConversationAlreadyRunning and GoalAlreadyRunning subclass ValueError and keep the exact previous messages, so every caller that still catches ValueError or matches the message (e.g. tests/agent_server/test_goal_loop.py pytest.raises(ValueError, match=...)) keeps working. All raise sites in EventService.run(), start_goal_loop(), and resume_goal_loop() were converted, and I traced each converted catch site against the base behavior: the send_message paths, the ACP-supersede path, and the confirm-acceptance path swallow/propagate other ValueErrors exactly as before, and the re-arm block in _run_and_publish still lets ServiceInactive and ConversationRunLimitExceeded propagate. GOAL_LOOP_SENDER is a pure constant extraction; no sender="goal" literals remain. REST semantics are unchanged (same 409 Conflict / 400 Invalid mapping, no OpenAPI change).

Verification on the current head 74a03a1b:

  • tests/agent_server/test_conversation_router.py, test_goal_loop.py, test_run_admission.py, and tests/sdk/conversation: 1274 passed.
  • ruff check and ruff format --check pass on the changed files.
  • The full tests/agent_server run in this sandbox shows 30 failures, all in canvas_extensions/, credential_binding, and launch-parity modules untouched by this diff; I reproduced two of them identically on origin/main, confirming they are pre-existing environment issues (sandbox git/config), not regressions.
  • GitHub CI on this head: all test, lint, type, OpenAPI, and compat checks green. The only failures are in the per-arch Docker Build & Push publish jobs (python-arm64 failed; java/golang/python-amd64 were cancelled downstream, and the manifest-consolidation summary job was cancelled with them). That is an image-publishing pipeline issue unrelated to this diff, so it does not block this refactor, but the failed image jobs may need a re-run before release automation picks up the 74a03a1-python tags.

Scope check: the change lives entirely in this repository's ownership (Agent Server exceptions/REST error mapping and SDK conversation types), matching the linked issue #7008 (ready-for-dev). No cross-repository or REST-contract concerns.

APPROVED

@enyst
enyst merged commit 4b9a723 into main Nov 19, 2026
126 of 136 checks passed
@enyst
enyst deleted the claude/project-thread-xwkk9b-typed-running branch November 19, 2026 18:49
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 tells "already running" errors apart by message text

3 participants