[earakely-scale]

Why. Every release publishes a new Claude Code image, even when nothing in the agent changed. There were four on 2026-10-22 alone, one each for v0.9.1344 to v0.9.1347. Each costs a build on two platforms.

The cause is the release itself. Before it computes tags, it rewrites each shipped agent's agentenv-framework-protocol requirement to an exact pin on the protocol version it ships (shipped_bundles.py pin). Every bump-version also bumps the protocol, so the agent's requirements.txt changes, its src-<digest> tag changes, and the image is built again.

Change

• shipped_bundles.py pin now pins only the shipped envs' and artifacts' requirements.txt. An agent keeps its floor, so its image is built only when its folder changes. It's built at the first release after the change and skipped after that, because its tag is already published.
  • The infra images already work this way.
  • The echo-mcp example env stays pinned. It isn't a published image, so the pin costs nothing.
• Pi's requirements.txt hard-coded ==0.1.305, which every release overwrote until now. It becomes >=0.1.305, the version Pi was written against; the protocol classes it uses date from 0.1.267.
• agent-build still runs after the protocol is published, because an agent that raises its floor can name the protocol the same release ships.
• A release still records every published image's digest in the wheel, whether or not it built it. infra_images.py write reads each image under its current tag.
• The workflow comments, the script docstrings, AGENTS.md and CONTRIBUTING.md now describe this.

Trade-off. An agent image now runs the newest protocol at or above its floor as of the build, not the protocol of each release that ships it. When an agent needs a newer protocol, raise its floor; that change rebuilds its image.

Verified

• Two simulated releases, protocol 0.1.400 then 0.1.401, with each image's source tag computed after the release's pin:

  Folder	main's script	this PR
  claude-code (published)	src-1779b92d… → src-b922ab25…, changes	src-dcd20d2f… both, same
  pi	changes	same
  echo-mcp env (not published)	changes	changes (pinned, as intended)

• Tests:

  • the pin tests cover env and artifact pins, an agent keeping its floor, and every shipped agent requiring the protocol by a floor;
  • the release test now asserts the pin changes no published image's sources;
  • the unit tier passes.

• After merge: the release that ships this builds one Claude Code image, since this PR edits its requirements.txt comment. The release after it should skip agent-build ("published already") and record the same digest.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge.

Summary

Agent requirements now keep their protocol floors instead of changing on every release.

• Agent images rebuild only when their folders change.

Intentional trade-off acknowledged by earakely-scale: agents keep the protocol installed when their image was built. Authors must raise an agent’s floor when it needs a newer protocol.

No actionable issues found. Tests were inspected but not run.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Release checkout] --> B[Pin env and artifact requirements]
  B --> C[Compute agent source tag]
  C --> D{Tag already published?}
  D -->|Yes| E[Reuse image]
  D -->|No| F[Build after protocol publish]
  F --> G[Publish image]
  E --> H[Record every image digest]
  G --> H
  H --> I[Include digest record in wheel]

Loading

_{Reviews (1) · Last reviewed commit: "ci(release): build an agent's image only..." · Reviewed by Greptile}