From 9c12e0efccd8f3634affa4acde557203649eb294 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Tue, 17 Nov 2026 21:34:37 -0800 Subject: [PATCH 1/2] fix(bundle): bundle init pins a pulled image to the digest its store records An image bundle init writes as a registry ref (one with no context the folder can hold) was written as its image_name alone, so an image stored by digest, as bundle register stores a `{ ref = "@sha256:..." }` image, went into the folder as its bare repository: a run would pull whatever that repository's latest is. It's written as its pinned_name now, the name a sandbox pulls. Co-Authored-By: Claude Opus 5.5 --- src/agent_env/bundle/importer.py | 8 +++--- tst/unit/bundle/importer_entities_test.py | 34 +++++++++++++++++++++-- 2 files changed, 36 insertions(+), 6 deletions(-) diff --git a/src/agent_env/bundle/importer.py b/src/agent_env/bundle/importer.py index 60666da21..9698a2be4 100644 --- a/src/agent_env/bundle/importer.py +++ b/src/agent_env/bundle/importer.py @@ -312,8 +312,8 @@ def image(self, out: _EntityOut, artifact: DockerImageArtifact, key: str) -> str out.pulled.append(Pulled(out.folder, key, ref)) return {"ref": ref} if names_registry(artifact.image_name): - out.pulled.append(Pulled(out.folder, key, artifact.image_name)) - return {"ref": artifact.image_name} + out.pulled.append(Pulled(out.folder, key, artifact.pinned_name)) + return {"ref": artifact.pinned_name} why = (f"it's stored only as a docker save tarball, under {artifact.image_name}, which names no registry" if artifact.tar_gz_object_url else "it records neither a build context nor a registry to pull it from") self._unwritable((EntityKind.ARTIFACT, artifact.id, artifact.version), f"{out.folder}: {key}", why) @@ -419,8 +419,8 @@ def _image_left_in_store(self, job: ImageJob) -> None: return if names_registry(job.artifact.image_name): job.toml.clear() - job.toml["ref"] = job.artifact.image_name - self.pulled.append(Pulled(job.folder, job.key, job.artifact.image_name, job.problem)) + job.toml["ref"] = job.artifact.pinned_name + self.pulled.append(Pulled(job.folder, job.key, job.artifact.pinned_name, job.problem)) return key = (EntityKind.ARTIFACT, job.artifact.id, job.artifact.version) try: diff --git a/tst/unit/bundle/importer_entities_test.py b/tst/unit/bundle/importer_entities_test.py index e79dce6a9..a41e7bd94 100644 --- a/tst/unit/bundle/importer_entities_test.py +++ b/tst/unit/bundle/importer_entities_test.py @@ -52,9 +52,10 @@ def _toml(root, path): return tomllib.loads((root / path).read_text()) -def _tarball_image(id="crm-image", image_name="crm-image:v1"): +def _tarball_image(id="crm-image", image_name="crm-image:v1", image_digest=None): return get_artifact_store().put_document(DockerImageArtifact( - id=id, description=id, image_name=image_name, tar_gz_s3_url=f"file:///nowhere/{id}.tar.gz")) + id=id, description=id, image_name=image_name, image_digest=image_digest, + tar_gz_s3_url=f"file:///nowhere/{id}.tar.gz")) def test_an_image_stored_only_as_a_tarball_fails_an_import_naming_it_and_writes_nothing(home): @@ -334,6 +335,35 @@ def test_a_field_naming_an_entity_it_cant_take_is_left_out_and_said_so_and_the_e assert _toml(imported.root, "artifacts/vireo/artifact.toml")["type"] == "environment" +def test_an_image_its_registry_names_by_digest_is_written_pinned_to_it(home): + digest = "sha256:" + "c" * 64 + image = _tarball_image(image_name="registry.example.com/crm", image_digest=digest) + MCPServerEnv.put(id="crm", docker_image_artifact=image, environment_name="crm") + _task([DEPLOY]) + + imported = import_task("t", home / "t") + + assert _toml(imported.root, "envs/crm/env.toml")["image"] == {"ref": f"registry.example.com/crm@{digest}"} + assert [pull.image for pull in imported.pulled] == [f"registry.example.com/crm@{digest}"] + + +def test_an_image_whose_context_cant_be_written_is_pulled_pinned_to_its_digest(home): + digest = "sha256:" + "d" * 64 + context = context_image(home, "two-dockerfiles", {"mail/Dockerfile": "FROM python\nCOPY mail/ /app/\n", + "mail/website/Dockerfile": "FROM node\n", "mail/app.py": "app\n"}, + "mail/Dockerfile") + image = get_artifact_store().put_document(DockerImageArtifact( + id="mail-image", description="no dockerfile recorded", image_name="registry.example.com/mail", + image_digest=digest, build_context_s3_url=context.build_context_object_url)) + MCPServerEnv.put(id="crm", docker_image_artifact=image, environment_name="crm") + _task([DEPLOY]) + + imported = import_task("t", home / "t") + + assert _toml(imported.root, "envs/crm/env.toml")["image"] == {"ref": f"registry.example.com/mail@{digest}"} + assert [pull.image for pull in imported.pulled] == [f"registry.example.com/mail@{digest}"] + + def test_an_image_whose_context_cant_be_written_is_pulled_by_the_registry_ref_it_names_and_said_why(home): context = context_image(home, "two-dockerfiles", {"mail/Dockerfile": "FROM python\nCOPY mail/ /app/\n", "mail/website/Dockerfile": "FROM node\n", "mail/app.py": "app\n"}, From 9b5f48e78ade2d55933af081509ca557070f484c Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 07:57:25 -0800 Subject: [PATCH 2/2] fix(bundle): a pulled image is written by its digest alone A ref giving a tag beside its digest is refused once the tag moves, so the bundle's first run would stop before deploying an image its registry still serves by digest. A computer base named from a registry is written the same way. Co-Authored-By: Claude Opus 5.5 --- src/agent_env/bundle/importer.py | 11 ++++++----- .../store/image_store/registry_api.py | 7 +++++++ .../bundle/computer_to_toml_edges_test.py | 5 +++-- tst/unit/bundle/importer_entities_test.py | 18 +++++++++++------- tst/unit/store/registry_api_test.py | 19 +++++++++++++++++++ 5 files changed, 46 insertions(+), 14 deletions(-) diff --git a/src/agent_env/bundle/importer.py b/src/agent_env/bundle/importer.py index 9698a2be4..e5542378c 100644 --- a/src/agent_env/bundle/importer.py +++ b/src/agent_env/bundle/importer.py @@ -65,7 +65,7 @@ from agent_env.store.base import NotFoundError from agent_env.store.ids import LOCAL_PREFIX, is_local_id from agent_env.store.image_store.oci_registry_credentials import names_registry -from agent_env.store.image_store.registry_api import pin_digest +from agent_env.store.image_store.registry_api import by_digest, pin_digest from agent_env.task.task import Task from agent_env.task_step.registry import get_task_step_registry from agent_env.utils.paths import os_reason @@ -312,8 +312,9 @@ def image(self, out: _EntityOut, artifact: DockerImageArtifact, key: str) -> str out.pulled.append(Pulled(out.folder, key, ref)) return {"ref": ref} if names_registry(artifact.image_name): - out.pulled.append(Pulled(out.folder, key, artifact.pinned_name)) - return {"ref": artifact.pinned_name} + ref = by_digest(artifact.pinned_name) + out.pulled.append(Pulled(out.folder, key, ref)) + return {"ref": ref} why = (f"it's stored only as a docker save tarball, under {artifact.image_name}, which names no registry" if artifact.tar_gz_object_url else "it records neither a build context nor a registry to pull it from") self._unwritable((EntityKind.ARTIFACT, artifact.id, artifact.version), f"{out.folder}: {key}", why) @@ -419,8 +420,8 @@ def _image_left_in_store(self, job: ImageJob) -> None: return if names_registry(job.artifact.image_name): job.toml.clear() - job.toml["ref"] = job.artifact.pinned_name - self.pulled.append(Pulled(job.folder, job.key, job.artifact.pinned_name, job.problem)) + job.toml["ref"] = by_digest(job.artifact.pinned_name) + self.pulled.append(Pulled(job.folder, job.key, job.toml["ref"], job.problem)) return key = (EntityKind.ARTIFACT, job.artifact.id, job.artifact.version) try: diff --git a/src/agent_env/store/image_store/registry_api.py b/src/agent_env/store/image_store/registry_api.py index 07d92a8ed..c56e90596 100644 --- a/src/agent_env/store/image_store/registry_api.py +++ b/src/agent_env/store/image_store/registry_api.py @@ -78,6 +78,13 @@ def pin_if_served(ref: str, auth: RegistryAuth | None) -> str | None: return None +def by_digest(ref: str) -> str: + """``ref`` named by its digest alone, ``name@sha256:...``, when it gives one; else ``ref``. A tag beside the digest + may move later, and ``pin_digest`` refuses a ref whose tag no longer names its digest.""" + image = _parse(ref) + return f"{image.name}@{image.digest}" if image.digest else ref + + def pinned_from(pinned: str, ref: str) -> bool: """Whether ``pinned``, a ref as ``pin_digest`` returns it, pins ``ref``: ``ref`` itself when it gives a digest, else the same name and tag (``latest`` when none is given) with a digest.""" diff --git a/tst/unit/bundle/computer_to_toml_edges_test.py b/tst/unit/bundle/computer_to_toml_edges_test.py index 7015b98de..ae16ef0c6 100644 --- a/tst/unit/bundle/computer_to_toml_edges_test.py +++ b/tst/unit/bundle/computer_to_toml_edges_test.py @@ -108,9 +108,10 @@ def test_a_base_named_from_a_registry_with_a_disk_built_from_a_source_is_written assert sorted(path.name for path in (tmp_path / "out" / "artifacts" / "base").iterdir()) == ["artifact.toml"] assert [(pulled.folder, pulled.image) for pulled in imported.pulled] == [ - ("artifacts/base", f"ghcr.io/acme/desk:1@{DIGEST}")] + ("artifacts/base", f"ghcr.io/acme/desk@{DIGEST}")] read = ComputerArtifact.get(f"{_run(tmp_path / 'out')}/base") - assert read.image().image_name == stored.image().image_name == f"ghcr.io/acme/desk:1@{DIGEST}" + assert stored.image().image_name == f"ghcr.io/acme/desk:1@{DIGEST}" + assert read.image().image_name == f"ghcr.io/acme/desk@{DIGEST}" assert read.forms.disk == stored.forms.disk and read.forms.disk.source.url == "https://images.example/noble.img" diff --git a/tst/unit/bundle/importer_entities_test.py b/tst/unit/bundle/importer_entities_test.py index a41e7bd94..d97a43a9d 100644 --- a/tst/unit/bundle/importer_entities_test.py +++ b/tst/unit/bundle/importer_entities_test.py @@ -335,25 +335,29 @@ def test_a_field_naming_an_entity_it_cant_take_is_left_out_and_said_so_and_the_e assert _toml(imported.root, "artifacts/vireo/artifact.toml")["type"] == "environment" -def test_an_image_its_registry_names_by_digest_is_written_pinned_to_it(home): - digest = "sha256:" + "c" * 64 - image = _tarball_image(image_name="registry.example.com/crm", image_digest=digest) +@pytest.mark.parametrize("image_name, image_digest", [ + ("registry.example.com/crm:v1", "sha256:" + "c" * 64), + ("registry.example.com/crm:v1@sha256:" + "c" * 64, None), +], ids=["digest beside", "digest in the name"]) +def test_an_image_its_registry_names_by_digest_is_written_by_the_digest_alone(home, image_name, image_digest): + image = _tarball_image(image_name=image_name, image_digest=image_digest) MCPServerEnv.put(id="crm", docker_image_artifact=image, environment_name="crm") _task([DEPLOY]) imported = import_task("t", home / "t") - assert _toml(imported.root, "envs/crm/env.toml")["image"] == {"ref": f"registry.example.com/crm@{digest}"} - assert [pull.image for pull in imported.pulled] == [f"registry.example.com/crm@{digest}"] + pinned = "registry.example.com/crm@sha256:" + "c" * 64 + assert _toml(imported.root, "envs/crm/env.toml")["image"] == {"ref": pinned} + assert [pull.image for pull in imported.pulled] == [pinned] -def test_an_image_whose_context_cant_be_written_is_pulled_pinned_to_its_digest(home): +def test_an_image_whose_context_cant_be_written_is_pulled_by_its_digest_alone(home): digest = "sha256:" + "d" * 64 context = context_image(home, "two-dockerfiles", {"mail/Dockerfile": "FROM python\nCOPY mail/ /app/\n", "mail/website/Dockerfile": "FROM node\n", "mail/app.py": "app\n"}, "mail/Dockerfile") image = get_artifact_store().put_document(DockerImageArtifact( - id="mail-image", description="no dockerfile recorded", image_name="registry.example.com/mail", + id="mail-image", description="no dockerfile recorded", image_name="registry.example.com/mail:v2", image_digest=digest, build_context_s3_url=context.build_context_object_url)) MCPServerEnv.put(id="crm", docker_image_artifact=image, environment_name="crm") _task([DEPLOY]) diff --git a/tst/unit/store/registry_api_test.py b/tst/unit/store/registry_api_test.py index 120992dd8..80c892195 100644 --- a/tst/unit/store/registry_api_test.py +++ b/tst/unit/store/registry_api_test.py @@ -13,6 +13,7 @@ from agent_env.store.image_store.registry_api import ( NoSuchImageError, RegistryRefusedError, + by_digest, pin_digest, pin_if_served, pinned_from, @@ -232,6 +233,24 @@ def test_a_pin_pins_the_ref_it_was_pinned_from(pinned, ref, pins): assert pinned_from(pinned, ref) is pins +@pytest.mark.parametrize("ref, named", [ + (f"ghcr.io/acme/app:1@{DIGEST}", f"ghcr.io/acme/app@{DIGEST}"), + (f"localhost:5000/team/app:1@{DIGEST}", f"localhost:5000/team/app@{DIGEST}"), + (f"ghcr.io/acme/app@{DIGEST}", f"ghcr.io/acme/app@{DIGEST}"), + ("ghcr.io/acme/app:1", "ghcr.io/acme/app:1"), +], ids=["tag and digest", "loopback port", "digest", "tag"]) +def test_by_digest_drops_a_tag_beside_a_digest(ref, named): + assert by_digest(ref) == named + + +def test_a_ref_by_digest_alone_still_pins_once_its_tag_has_moved(fake_registry): + fake_registry(lambda request: _served(DIGEST if request.url.path.endswith(DIGEST) else OTHER)) + + with pytest.raises(ValueError, match="names"): + pin_digest(f"ghcr.io/acme/app:1@{DIGEST}", None) + assert pin_digest(by_digest(f"ghcr.io/acme/app:1@{DIGEST}"), None) == f"ghcr.io/acme/app@{DIGEST}" + + def _ghcr(served): """GHCR's anonymous token dance in front of ``served``, a handler for requests that carry the token.""" def handler(request):