fix(sdk): add versioned persisted AgentSettings migrations

[neubig]

Summary

• add a canonical persisted AgentSettings persistence contract with SDK-owned version migration helpers
• add AgentSettings.migrate_persisted_payload(), load_persisted(), and dump_persisted() so consumers migrate before validation and re-save the latest canonical form
• cover both legacy unversioned payloads and the current canonical payload in SDK tests

Testing

• uv run pre-commit run --files openhands-sdk/openhands/sdk/settings/model.py tests/sdk/test_settings.py
• uv run pre-commit run --files AGENTS.md
• uv run pytest tests/sdk/test_settings.py -q

Fixes #2788

This PR was created by an AI assistant (OpenHands) on behalf of the user.

@neubig can click here to continue refining the PR

---

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-slim	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:c8073b0-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

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

[github-actions]

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/settings
model.py	295	20	93%	251, 255, 258, 272, 279, 499, 524, 615, 620, 660, 692, 702, 704, 709, 727, 740, 742, 744, 746, 753
TOTAL	22359	6473	71%

[neubig]

@OpenHands

1. There is too much stuff to maintain legacy backward compatibility, just make the implementation clean.
2. Make ci pass
3. Then, update OpenHands/OpenHands PR 13306 to use the updated version

[openhands-ai]

I'm on it! neubig can track my progress at all-hands.dev

[neubig]

Addressed in 5ee469c.

• removed the extra conversation-settings split and other consumer-specific persistence helpers from this PR
• restored the clean SDK-owned persisted AgentSettings contract: legacy raw v1 payloads migrate to canonical v2 { "version": 2, "settings": ... } via AgentSettings.load_persisted() / dump_persisted()
• local validation passed with uv run pre-commit run --files ..., uv run pytest tests/sdk/test_settings.py tests/agent_server/test_settings_router.py -q, and uv run python .github/scripts/check_sdk_api_breakage.py

I'm updating OpenHands/OpenHands#13306 next to use the wrapper-based persisted format.

This comment was created by an AI assistant (OpenHands) on behalf of the user.

[openhands-ai]

Final update since my last summary:

• Sent a PR comment on OpenHands/software-agent-sdk#2789 referencing commit 5ee469c6 and explaining the cleanup.
• Waited for the refreshed CI on PR fix(sdk): add versioned persisted AgentSettings migrations #2789; all checks are now green.
• Updated OpenHands/OpenHands#13306 to align with the cleaned-up SDK change:
  • reverted the incompatible OpenHands-side conversation/runtime settings split
  • re-pinned openhands-sdk and openhands-agent-server to openhands/issue-2788-agent-settings-migrations at 5ee469c68decf0c2527c4d562b480c1d89d3ac48
  • updated pyproject.toml, poetry.lock, and uv.lock
• Pushed the OpenHands PR branch updates (0a5749ccf, 0a9f4b810).
• Commented on OpenHands/OpenHands#13306 summarizing that update.

Conciseness check:

• The new OpenHands changes were kept minimal: only the SDK pinning files plus reverting the incompatible split commit.
• No extra follow-up code changes were added beyond what was needed to realign PR #13306 with the final SDK shape.

So yes: the requested work has now been fully addressed.