REST API policy encoding

[enyst]

The REST API checks workflow would fail with: Error: Breaking REST API change detected without MINOR version bump (1.14.0 -> 1.14.0) if a breaking change happens on a PR.

Understand the workflow, and make sure you read the deprecation policies in AGENTS.md including the respective file in agent-server package. The error is a bit weird because it says a minor version bump is enough. But it shouldn't be enough: we need 5 minor versions of deprecation time.

Look at Griffe workflow, I think it enforces those 5 releases for Python API. Let's do the same for REST API.

[openhands-ai]

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

[openhands-ai]

Final summary:

Checklist

• Understood the REST API breakage workflow and the agent-server deprecation policy.
• Replaced the incorrect “MINOR version bump is enough” behavior with enforcement based on the documented REST deprecation runway.
• Made REST operation removals pass only when the baseline OpenAPI description includes a scheduled removal version and the current version has reached it.
• Made other in-place breaking REST contract changes fail, with guidance that the old contract must remain available for the 5-minor-release runway.
• Added focused tests covering the new behavior, including the same-version scheduled-removal case from the issue.
• Ran the required validation:
  • uv run pre-commit run --files .github/scripts/check_agent_server_rest_api_breakage.py tests/ci_scripts/test_check_agent_server_rest_api_breakage.py openhands-agent-server/AGENTS.md
  • uv run pytest tests/ci_scripts/test_check_agent_server_rest_api_breakage.py
• Created and pushed a branch with the required openhands/ prefix.
• Opened a PR that closes the issue and follows the PR template.

Conciseness check

• The changes are limited to 3 relevant files:
  • .github/scripts/check_agent_server_rest_api_breakage.py
  • tests/ci_scripts/test_check_agent_server_rest_api_breakage.py
  • openhands-agent-server/AGENTS.md
• No extraneous files or unrelated changes were included.

Git / PR

• Branch: openhands/rest-api-policy-encoding
• Commit: f1fd2acb
• PR: Enforce REST API deprecation runway in breakage checks #2464

In short: issue #2463 is addressed by making REST API CI enforce the 5-minor-release deprecation policy rather than allowing breaking changes after only a MINOR bump.