Update SDK

Bump SDK packages (openhands-sdk, openhands-agent-server, openhands-tools), pin them to unreleased commits for testing, and cut an OpenHands release.

Quick Summary — How Many Files Change?

The 3 auto-regenerated files are always: poetry.lock, uv.lock, enterprise/poetry.lock.

SDK Package Bump — 2 Files + 3 Lock Files

Land as a separate PR before the release. Examples: 929dcc3 (SDK 1.11.5), cd235cc (SDK 1.11.4).

Then regenerate lock files:

poetry lock && uv lock && cd enterprise && poetry lock && cd ..

Docker Image Locations — All Hardcoded References

For the complete inventory of every file containing a hardcoded Docker image tag or repository, see references/docker-image-locations.md. Key files that must stay in sync during an SDK bump:

CI enforcement: .github/workflows/check-version-consistency.yml validates version consistency and compose file image references on every PR and push to main.

⚠️ Docker Image Tag Gotcha (merge-commit SHA)

The SDK CI in software-agent-sdk repo tags Docker images with the GitHub Actions merge-commit SHA, NOT the PR head-commit SHA. When pinning to an SDK PR branch:

1. Check the SDK PR description for the actual image tag (look for the AGENT_SERVER_IMAGES section)
2. Or query the CI logs: the "Consolidate Build Information" job prints "short_sha": "<tag>"
3. The merge-commit SHA differs from the head SHA shown in the PR

For released SDK versions, images use a version tag (e.g., 1.12.0-python) — no merge-commit ambiguity.

Cutting a Release — 3 Files

A release commit updates the version string across 3 files. Gold-standard examples: 1.3.0 (d063c8c), 1.4.0 (495f48b).

Note: openhands/version.py reads the version from pyproject.toml at runtime — no manual edit needed there.

Compose Files (2 files)

Both compose files should use ghcr.io/openhands/agent-server with the current SDK version tag.

Release Workflow

Step 1: Verify the SDK bump has landed

grep -n "openhands-sdk\|openhands-agent-server\|openhands-tools" pyproject.toml
grep -n "AGENT_SERVER_IMAGE" openhands/app_server/sandbox/sandbox_spec_service.py
grep "AGENT_SERVER_IMAGE_TAG" docker-compose.yml containers/dev/compose.yml

Step 2: Bump version numbers

# Edit pyproject.toml, frontend/package.json, frontend/package-lock.json
git add pyproject.toml frontend/package.json frontend/package-lock.json
git commit -m "Release X.Y.Z"
git tag X.Y.Z

Create a saas-rel-X.Y.Z branch from the tagged commit for the SaaS deployment pipeline.

Step 3: Images get tagged automatically

Every push to main / saas-rel-* / oss-rel-* builds and publishes ghcr.io/openhands/openhands and ghcr.io/openhands/enterprise-server images for that commit (tagged by SHA, short SHA, and branch name).

Pushing a git tag X.Y.Z then tags the images for that commit with X.Y.Z, X.Y, X, and latest. Non-semver tags just get their literal name applied.

Requires the commit to already be built. If you push the tag too early, the retag CI job fails loudly — re-run it from the Actions UI once the build completes.

Development: Pin SDK to an Unreleased Commit

For detailed examples of all pinning formats (commit, branch, uv-only), see references/sdk-pinning-examples.md.

Files to change (3 manual + 3 lock files)

CI guard

The check-package-versions.yml workflow blocks merging to main if [tool.poetry.dependencies] contains any rev fields. This ensures unreleased SDK pins do not accidentally ship in a release.