test(sdk): reproduce delegate resume compatibility regression

[neubig]

Summary

Solution for problem discussed in: https://openhands-ai.slack.com/archives/C0A6XE64XK4/p1773178175274459

• Allow adding new tools when resuming a conversation (e.g. delegate added in a new SDK version) while still rejecting tool removals
• Removing tools breaks backward compatibility because the LLM may have already seen them in prior turns; adding tools is safe since the LLM simply gains new capabilities on the next turn
• This is the least invasive fix: a ~5-line change in AgentBase.verify() that relaxes the exact-match check to a superset check

Error reproduction

• add a persisted base_state.json fixture generated from a simple v1.11.5 CLI conversation
• add a regression test that shows current main rejects that older conversation when runtime tools append delegate
• document the exact failure mode in a CI-safe test instead of relying on a manual local repro

Reproduction

I reproduced this locally by:

1. checking out v1.11.5
2. creating a simple CLI conversation with the default tool set (terminal, file_editor, task_tracker)
3. switching back to current main
4. attempting to resume the same conversation with the runtime tool set plus delegate

That resume path raises:

Cannot resume conversation: tools cannot be changed mid-conversation (added: ['delegate']). To use different tools, start a new conversation.

Testing

• uv run pytest tests/sdk/conversation/local/test_state_serialization.py -k "builtin_tool_removed or v1_11_5_cli_default_conversation_fails_when_runtime_adds_delegate" -q
• uv run pre-commit run --files tests/sdk/conversation/local/test_state_serialization.py tests/fixtures/conversations/v1_11_5_cli_default/base_state.json

---

Agent Server images for this PR

• 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	amd64, arm64	nikolaik/python-nodejs:python3.13-nodejs22	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:a51ef46-python

Run

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

All tags pushed for this build

ghcr.io/openhands/agent-server:a51ef46-golang-amd64
ghcr.io/openhands/agent-server:a51ef46-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:a51ef46-golang-arm64
ghcr.io/openhands/agent-server:a51ef46-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:a51ef46-java-amd64
ghcr.io/openhands/agent-server:a51ef46-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:a51ef46-java-arm64
ghcr.io/openhands/agent-server:a51ef46-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:a51ef46-python-amd64
ghcr.io/openhands/agent-server:a51ef46-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-amd64
ghcr.io/openhands/agent-server:a51ef46-python-arm64
ghcr.io/openhands/agent-server:a51ef46-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-arm64
ghcr.io/openhands/agent-server:a51ef46-golang
ghcr.io/openhands/agent-server:a51ef46-java
ghcr.io/openhands/agent-server:a51ef46-python

About Multi-Architecture Support

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

[github-actions]

API breakage checks (Griffe)

Result: Passed

Action log

[github-actions]

Agent server REST API breakage checks (OpenAPI)

Result: Failed

Log excerpt (first 1000 characters)

{"asctime": "2026-03-12 12:48:16,196", "levelname": "WARNING", "name": "openhands.agent_server.config", "filename": "config.py", "lineno": 173, "message": "\u26a0\ufe0f OH_SECRET_KEY was not defined. Secrets will not be persisted between restarts."}
::error title=openhands-agent-server REST API::Breaking REST API change detected without MINOR version bump (1.13.0 -> 1.13.0).

Breaking REST API changes detected compared to baseline release:
- the 'file' request property type/format changed from 'string'/'' to 'string'/'binary'
/home/runner/work/software-agent-sdk/software-agent-sdk/.venv/lib/python3.13/site-packages/litellm/llms/custom_httpx/async_client_cleanup.py:66: DeprecationWarning: There is no current event loop
  loop = asyncio.get_event_loop()

Action log

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/agent
base.py	185	22	88%	200, 257–259, 289, 293–297, 345–347, 357, 367, 375–376, 480, 517–518, 528–529
TOTAL	19928	5791	70%

[all-hands-bot]

🟢 Good taste - Elegant fix that eliminates an unnecessary restriction. The logic went from "reject any tool changes" to "only reject removing tools", which is exactly right for SDK upgrade compatibility. Simple, well-tested with real v1.11.5 fixture, solves a real problem. Previous description issue has been addressed.

[all-hands-bot]

Taste Rating: 🟢 Good taste - Elegant fix that eliminates an unnecessary restriction.

KEY INSIGHT: The logic went from "reject any tool changes" to "only reject removing tools", which is exactly right for SDK upgrade compatibility. Simple, well-tested with real v1.11.5 fixture, solves a real problem.

VERDICT: ✅ Worth merging