fix: control buildkit cache exports

[simonrosenberg]

Summary

• disable shared registry cache-to export by default while keeping shared cache-from
• add OPENHANDS_BUILDKIT_CACHE_MODE=off|min|max so callers can disable or reduce cache-to exports
• add tests covering shared cache tag scoping, default non-export behavior, opt-in shared export, and fully disabled cache export

Scope

The prebuilt SDK sdist feature from this branch already merged separately in #2426, so this PR now carries only the remaining BuildKit cache export controls.

Behavior change

• shared registry cache export is opt-in via OPENHANDS_SHARED_REGISTRY_CACHE_EXPORT=1
• OPENHANDS_BUILDKIT_CACHE_MODE=max|min|off controls all cache-to exports
  • max keeps full cache export behavior
  • min exports a smaller cache
  • off disables all cache-to exports while preserving cache-from

Validation

• uv run pytest tests/agent_server/test_docker_build.py
• uv run pre-commit run --files openhands-agent-server/openhands/agent_server/docker/build.py tests/agent_server/test_docker_build.py

---

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:9c0379f-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

• Each variant tag (e.g., 9c0379f-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., 9c0379f-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)

::error title=openhands-agent-server REST API::Breaking REST API change detected without MINOR version bump (1.14.0 -> 1.14.0).

Breaking REST API changes detected compared to baseline release:
- added '#/components/schemas/ACPAgent-Output, #/components/schemas/Agent-Output' to the '/items/anyOf[subschema #1: ConversationInfo]/agent' response property 'oneOf' list for the response status '200'
- the '/items/anyOf[subschema #1: ConversationInfo]/agent' response's property type/format changed from 'object'/'' to ''/'' for status '200'
- removed the required property '/items/anyOf[subschema #1: ConversationInfo]/agent/kind' from the response with the '200' status
- removed the required property '/items/anyOf[subschema #1: ConversationInfo]/agent/llm' from the response with the '200' status
- the 'agent' request property type/format changed from 'object'/'' to ''/''
- added '#/components/schemas/ACPAgent-Output, #/components/schemas/Agent-Output' to the 'agent' response property 'oneOf' li

Action log

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-agent-server/openhands/agent_server/docker
build.py	533	159	70%	73, 76–77, 91, 96, 100–102, 106, 111, 128–133, 136, 159, 161, 169, 171–172, 174–178, 180, 184, 187, 190–193, 195–197, 199, 201, 203, 205, 295–296, 300–301, 305–306, 310–311, 324, 326–334, 407, 509, 523, 526, 530–531, 535–536, 540, 556–558, 561, 567–570, 580, 595, 613, 618, 625, 629, 649, 652, 679, 698–699, 703–705, 750, 849, 859–860, 931–932, 937, 940, 947, 952, 957, 963, 968, 975–976, 981, 986, 992, 998, 1003, 1012, 1015–1021, 1024–1026, 1029, 1043–1048, 1050–1051, 1053–1055, 1058–1059, 1063–1066, 1068, 1077, 1089, 1092, 1108–1113, 1115–1116, 1118–1122, 1124, 1131, 1135
TOTAL	20321	9130	55%

[all-hands-bot]

🟢 Good taste - Clean, pragmatic solution solving a real performance problem. No over-engineering, just straightforward implementation: optional parameter, conditional build skip, proper cleanup. Backward compatible, well-tested. This is how code should be written. LGTM! 🚀