Update Sdk

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 auto-regenerated file is always uv.lock.

SDK Package Bump — 2 Files + 1 Lock File

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

Then regenerate the lock file (with the uv version pinned in containers/app/Dockerfile, see AGENTS.md):

uv lock

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: Merge the release PR

Don't bump versions or push tags by hand. release.yml runs release-please on every push to main, which keeps a draft release PR open; merging it bumps pyproject.toml, frontend/package.json, and frontend/package-lock.json and pushes the X.Y.Z tag.

Step 3: Images get tagged automatically

Every push to main builds and publishes a ghcr.io/openhands/enterprise-server image for that commit (tagged by SHA, short SHA, and branch name). It is the only image this repo publishes.

The X.Y.Z tag then aliases that commit's image as X.Y.Z, X.Y, X, and latest, and opens a chart PR in OpenHands/OpenHands-Cloud. 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 + 1 lock file)

CI guard

The check-package-versions.yml workflow blocks merging to main if pyproject.toml pins any dependency to a git ref or URL (a @ git+... direct reference in [project] dependencies or a dependency group, or a git/rev/branch entry in [tool.uv.sources]). This ensures unreleased SDK pins do not accidentally ship in a release.