Implement versioned migrations for persisted AgentSettings payloads

[neubig]

Summary

The SDK currently defines the canonical AgentSettings schema, but it does not yet provide a versioned migration path for persisted settings payloads.

Today, products can validate stored settings against the current AgentSettings model, but there is no SDK-owned mechanism to:

• carry a canonical settings schema version,
• migrate persisted payloads from older versions to newer versions,
• validate only after those migrations have been applied, and
• re-serialize/save the latest canonical form.

Why this matters

OpenHands and Enterprise currently need to handle compatibility around persisted settings themselves. That works for additive changes, but it becomes brittle for breaking schema changes such as field renames, moves, or removals.

The SDK should own the migration story for the canonical AgentSettings payload so all consumers get the same upgrade behavior.

Proposed approach

Implement a canonical persisted-settings migration flow in the SDK:

1. Introduce a canonical persisted payload/version contract for AgentSettings.
2. Add SDK-owned migration functions (for example v1 -> v2, v2 -> v3).
3. Migrate on load, then validate using the latest AgentSettings model.
4. Re-serialize in the latest canonical format.
5. Keep storage/layout concerns (for example org/member overlay semantics) in consuming products, but keep canonical settings-schema evolution in the SDK.

Acceptance criteria

• Persisted settings have a documented canonical version contract.
• The SDK exposes a clear API for loading persisted settings with migrations applied.
• Migration logic lives in one place in the SDK instead of being duplicated in consumers.
• Tests cover at least one older-version payload being migrated into the current AgentSettings schema.

Context

This came up while reviewing OpenHands/OpenHands PR #13306, where we needed to reason carefully about how SDK settings schema evolution should behave in both solo and org workspaces.

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

[openhands-ai]

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

[openhands-ai]

Final summary:

• The request has been completely addressed.
• Added the SDK-owned versioned persistence/migration flow for AgentSettings.
• Added test coverage for migrating a legacy persisted payload into the current schema.
• Ran the requested validation (pre-commit on changed files and targeted pytest), and the checks passed.
• Followed the GitHub workflow instructions: created a branch, committed, pushed, and opened a PR.

Conciseness check:

• The code changes are focused and minimal.
• Only the relevant implementation file, its test file, and AGENTS.md repository memory were changed.
• No extra application code changes were introduced beyond what was needed for issue Implement versioned migrations for persisted AgentSettings payloads #2788.

No new code changes were made after the previous update; I only confirmed completion and clean handoff status.

PR: #2789