feat: support reusing prebuilt SDK sdists

[simonrosenberg]

Summary

• add BuildOptions.prebuilt_sdist as a public API for reusing a prebuilt SDK sdist
• teach _make_build_context() and the CLI to use a provided sdist instead of always running uv build --sdist
• add tests covering no redundant sdist build, preserved docker args/tags, and repeated sdist reuse

Scope

This intentionally carries only the original prebuilt-sdist feature from #2399. It does not include the later BuildKit cache export changes.

Validation

• uv run pytest 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:6c88624-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

• Each variant tag (e.g., 6c88624-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., 6c88624-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: 🟢 Good taste - Clean, pragmatic solution

What This Does Right:

1. Solves Real Problem: Eliminates redundant uv build --sdist calls in CI/CD pipelines where sdist is already built
2. Simple Design: Optional prebuilt_sdist parameter with clean fallback to existing behavior - no special cases
3. Proper Data Flow: Either build OR reuse, with correct cleanup logic in both paths
4. Backward Compatible: Default None preserves all existing behavior
5. Real Tests: Tests verify actual behavior (no uv build called, sdist reusable), not just mock assertions

Code Quality:

• No deep nesting (< 3 levels) ✅
• Clear error handling (FileNotFoundError with helpful message) ✅
• Proper resource cleanup (conditional rmtree for sdist_dir) ✅
• Good logging at decision points ✅

Testing Assessment:
The tests exercise real code paths and assert on outcomes:

• test_make_build_context_reuses_prebuilt_sdist_without_running_uv_build: Verifies no uv build call AND content extraction works
• test_build_with_prebuilt_sdist_preserves_tags_and_docker_args: Integration test verifying docker build command structure
• test_build_can_reuse_same_prebuilt_sdist_multiple_times: Proves reusability claim

No mocking of the unit under test - just mocking infrastructure (docker commands). Good.

Verdict: ✅ LGTM - This is how features should be built: solving real problems with simple, testable code.

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-agent-server/openhands/agent_server/docker
build.py	497	160	67%	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, 209–210, 295–296, 300–301, 305–306, 310–311, 324, 326–334, 407, 435–436, 438, 509, 523, 526, 530–531, 535–536, 540, 556–558, 561, 567–570, 580, 595, 616, 619, 646, 665–666, 670–672, 717, 784, 794–795, 862–863, 868, 871, 878, 883, 888, 894, 899, 906–907, 912, 917, 923, 929, 934, 943, 946–952, 955–957, 960, 974–979, 981–982, 984–986, 989–990, 994–997, 999, 1008, 1020, 1023, 1039–1044, 1046–1047, 1049–1053, 1055, 1062, 1066
TOTAL	19886	8831	55%