ci: enforce agent-server REST API deprecation policy

[enyst]

Adds a REST (OpenAPI) deprecation/breakage policy for openhands-agent-server.

• New check script: .github/scripts/check_agent_server_rest_api_breakage.py
  • Compares current OpenAPI schema to the previous PyPI release
  • Enforces deprecation-before-removal for operations (path + method)
  • Requires a MINOR+ version bump for breaking REST API changes
• New workflow: Agent server REST API breakage checks (mirrors the SDK Griffe workflow)
  • Gates release PRs (rel-*), comments on other PRs
• New package guide: openhands-agent-server/AGENTS.md documenting the policy

Note: this covers REST OpenAPI only; WebSocket/SSE endpoints are out of scope.

---

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.12-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:3316d56-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

• Each variant tag (e.g., 3316d56-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., 3316d56-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: Passed

Action log

[all-hands-bot]

Taste Rating: 🟡 Acceptable - Solid infrastructure that solves a real problem (API stability). Mirrors the SDK Griffe pattern well. Two improvement opportunities noted below.

[enyst]

@OpenHands Investigate the problem solved by this PR and tell me: is there a library that can do this for us?

[openhands-ai]

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

[openhands-ai]

I investigated what this PR is doing (a custom CI policy check that compares the current agent-server OpenAPI schema to the previous PyPI release, enforcing “deprecation-before-removal” for operations and requiring a MINOR+ version bump for breaking REST API changes) and looked for existing libraries/tools that could replace it.

Conclusion: there are good existing tools that can handle OpenAPI diffing / breaking-change detection, but none that cleanly replaces the entire workflow/policy end-to-end.

• Best match: oasdiff (Go) — purpose-built for OpenAPI breaking-change detection and has explicit support for deprecation flows (including optional x-sunset and grace-period enforcement).
  However, its default philosophy is that “removed after deprecation” can be treated as non-breaking, which does not align with this PR’s policy (we still treat removals as breaking; we just require prior deprecation + a MINOR bump).

  • https://github.com/oasdiff/oasdiff

• Other option: OpenAPITools/openapi-diff (Java) — mature diffing and compatibility reporting, but it won’t enforce this PR’s custom rules (prior deprecation requirement + semver bump requirement) without wrapper logic.

  • https://github.com/OpenAPITools/openapi-diff

So: we could potentially swap our hand-rolled diff logic for oasdiff/openapi-diff, but we’d still need custom glue code to (a) fetch/generate the “previous release” spec (we do that by installing the previous PyPI version and calling FastAPI’s openapi()), and (b) enforce our repo-specific policy (especially the semver bump and deprecation-before-removal rule as defined here). No code changes were made.

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
TOTAL	19042	8667	54%

report-only-changed-files is enabled. No files were changed during this commit :)

[enyst]

@OpenHands this PR has been merged. But look at this comment: #2232 (comment)

Make a new branch from main and adapt the workflow to use oasdiff. Once done, review your work and open PR.

[openhands-ai]

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

[openhands-ai]

Summary

I've completed the task of adapting the agent-server REST API workflow to use oasdiff. Here's what was done:

Changes Made

1. Script update (.github/scripts/check_agent_server_rest_api_breakage.py):

   • Replaced ~190 lines of custom Python diffing logic with oasdiff CLI calls
   • Uses oasdiff breaking to detect breaking changes between OpenAPI specs
   • Preserves custom policy enforcement (deprecation-before-removal + MINOR version bump)

2. Workflow update (.github/workflows/agent-server-rest-api-breakage.yml):

   • Added step to install oasdiff from official releases

3. Documentation update (openhands-agent-server/AGENTS.md):

   • Added reference to oasdiff in CI enforcement section

PR

Created: #2240

Title: ci: use oasdiff for agent-server REST API breakage detection

The changes use oasdiff as requested, while preserving the custom policy enforcement that requires deprecation before removal and MINOR version bumps for breaking changes.