Add image build-or-wait helpers

[Dingway98]

Summary

Concurrent callers currently have to implement image lookup, naming, and build-conflict handling themselves. Add sync and async sandboxes.get_or_build_image() to reuse a ready image, join a compatible in-progress build, or create one from a Dockerfile context or local Docker image.

resolved = client.sandboxes.get_or_build_image(
    context_path="./app",
    image_name_prefix="my-app",
)
sandbox = client.sandboxes.create({
    "image_name": resolved.image_name,
    "image_id": resolved.image_id,
})

Changes

• Derive names from input content, platform, and normalized initialization options; return reused, joined, or created with the resolved image/build identifiers.
• Add exact, paginated find_ready_image() lookup, including completed images awaiting backup, and expose the shared naming helper through hyperbrowser.image_builds.
• Validate concurrent-build compatibility and preserve context/digest mutation checks. Each caller owns its polling deadline; canceling a wait leaves the accepted backend build running.
• Keep existing explicit-name build methods unchanged. Force mode skips ready-image reuse while allowing compatible active builds and existing layer/artifact caches. Lookup and creation remain separate API calls.
• Report an actionable Docker upgrade error for automatic local-image identity discovery when platform inspection is unsupported (API 1.49+, Docker 28.1+). Remote Dockerfile builds do not require local Docker, and the existing explicit-name import fallback is unchanged.
• Document the API, add sync/async and typing coverage, and prepare version 1.9.0. This supports the SDK integration in Harbor #3424.

Validation

• pytest tests --ignore=tests/sandbox/e2e -q: 555 passed, including typing checks. Ruff lint and changed-file formatting passed. GitHub checks for the updated commit passed Python 3.8–3.14, typing, and package validation.
• Live local server/vm-service tests: 24 simultaneous resolvers produced one build and 23 joins; canceled/timed-out waiters did not interrupt surviving callers. Four distinct builds completed concurrently, followed by 80 commands across four VMs.
• Live SDK/Harbor tests covered remote contexts, Docker 29 image import, exact-ID cache reuse, reuse before backup upload, cross-process joining, initialization overrides, force builds, failures, and cancellation/cleanup. The cloud build/cache flow also passed.
• Docker API boundary checks: 20 cases passed with real Docker 29.4.2 using API overrides 1.48/1.49 and native 1.54, covering sync/async/Harbor paths, plain/provenance images, and legacy plain-image fallback. API 1.48 rejects before HTTP; successful paths export real images and clean temporary resources. These checks use API overrides, not separately installed older engines.
• Fresh local end-to-end checks with the updated SDK: API 1.49 provenance-image import and sandbox execution, native-API async reuse of the same image, and Harbor API 1.49 import/start/exec all passed.
• Disposable test sandboxes and output images were cleaned up. One-off load/E2E harnesses are kept outside this PR.

---

Note

Medium Risk
New orchestration composes non-atomic lookup plus build APIs and local Docker identity inspection; mistakes could cause duplicate builds or wrong-name publishes, though digest/context mutation checks and conflict joining reduce that risk.

Overview
Adds sync/async sandboxes.get_or_build_image() so callers can resolve a sandbox image from a Dockerfile context or local Docker image without hand-rolling cache keys, lookups, and build-conflict handling. It derives a stable image_name from context fingerprint or image digest (plus platform and normalized image_init), then reuses a ready team image, joins a compatible image_build_in_progress 409, or submits a new build; results are returned as SandboxImageBuildResolution (reused / joined / created).

Supporting pieces include paginated find_ready_image(), shared image_resolution helpers and public hyperbrowser.image_builds.image_build_name, docker_image_digest() with clearer Docker API 1.49+ errors, and expected_image_digest checks on docker-image imports. force_build, optional precomputed fingerprints/digests, per-caller wait/upload timeouts, and non-cancellation of backend builds on client timeout are documented; explicit-name build APIs are unchanged. Version bumps to 1.9.0 with README and broad tests.

^{Reviewed by Cursor Bugbot for commit 144e913. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 80d1ea1. Configure here.}