From e61a9c6296c4a97b936d72d72b8751b1fdd93def Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Mon, 9 Nov 2026 12:59:57 -0800 Subject: [PATCH] feat(run-docker-container): run a docker_image artifact without building run_docker_container always staged a build context and ran docker build, even for an image that already existed, so a task run many times paid a build per run. It now also takes image_artifact_id / image_artifact_version, a docker_image artifact it runs as it is: the image is put on the sandbox with load_docker_images, as install_agent puts an agent's there, and started with nothing staged or built. On the local sandbox a context-only image is built once per sources and kept across runs. Co-Authored-By: Claude Opus 5.5 --- .../task_steps/run_docker_container.py | 127 +++++++++++------- .../cli/run_bundle_task_image_test.py | 69 ++++++++++ .../test_run_docker_container_local.py | 40 +++++- .../task_step/run_docker_container_test.py | 64 ++++++++- tst/unit/task_step/test_field_scopes.py | 2 +- 5 files changed, 248 insertions(+), 54 deletions(-) create mode 100644 tst/integration/cli/run_bundle_task_image_test.py diff --git a/src/agent_env/task_step/task_steps/run_docker_container.py b/src/agent_env/task_step/task_steps/run_docker_container.py index 71a88780a..15280d4db 100644 --- a/src/agent_env/task_step/task_steps/run_docker_container.py +++ b/src/agent_env/task_step/task_steps/run_docker_container.py @@ -1,14 +1,16 @@ -"""Run a Docker container task step — builds a user-provided Dockerfile on a -pre-deployed VM sandbox and runs the resulting container in the background.""" +"""Run a Docker container task step: builds a user-provided Dockerfile on a pre-deployed VM sandbox, or puts a +docker_image artifact's image there, and runs the container in the background.""" from __future__ import annotations +import asyncio import logging import posixpath import shlex from typing import ClassVar, Optional from urllib.parse import urlparse +from agent_env.artifact.artifacts.docker_image import DockerImageArtifact from agent_env.task_step.context import TaskStepContext from agent_env.entity.refs import EntityRef from agent_env.entity.scopes import FieldScope @@ -27,6 +29,7 @@ class RunDockerContainerTaskStep(TaskStep): version_field="docker_context_artifact_version", artifact_type="file_artifact_universe", ), + EntityRef.artifact("image_artifact_id", version_field="image_artifact_version", artifact_type="docker_image"), ) field_scopes = {**TaskStep.field_scopes, "docker_context_url": FieldScope.USER} @@ -38,6 +41,8 @@ def __init__( docker_context_artifact_id: Optional[str] = None, docker_context_artifact_version: Optional[int] = None, docker_context_url: Optional[str] = None, + image_artifact_id: Optional[str] = None, + image_artifact_version: Optional[int] = None, dockerfile_path: str = "Dockerfile", container_name: str = "task-container", image_tag: Optional[str] = None, @@ -58,8 +63,8 @@ def __init__( fail_task_on_error: bool = True, ): super().__init__(id, version, depends_on=depends_on, fail_task_on_error=fail_task_on_error) - if docker_context_artifact_id is not None and docker_context_url is not None: - raise ValueError("Pass either `docker_context_artifact_id` or `docker_context_url`, not both") + if sum(source is not None for source in (docker_context_artifact_id, docker_context_url, image_artifact_id)) > 1: + raise ValueError("Pass one of `image_artifact_id`, `docker_context_artifact_id` and `docker_context_url`") if command_override and keep_alive_with_base_command: raise ValueError( "Pass either `command_override` or `keep_alive_with_base_command`, not both" @@ -68,6 +73,8 @@ def __init__( self.docker_context_artifact_id = docker_context_artifact_id self.docker_context_artifact_version = docker_context_artifact_version self.docker_context_url = docker_context_url + self.image_artifact_id = image_artifact_id + self.image_artifact_version = image_artifact_version self.dockerfile_path = dockerfile_path self.container_name = container_name self.image_tag = image_tag @@ -95,6 +102,8 @@ def to_dict(self) -> dict: base["docker_context_artifact_id"] = self.docker_context_artifact_id base["docker_context_artifact_version"] = self.docker_context_artifact_version base["docker_context_url"] = self.docker_context_url + base["image_artifact_id"] = self.image_artifact_id + base["image_artifact_version"] = self.image_artifact_version base["dockerfile_path"] = self.dockerfile_path base["container_name"] = self.container_name base["image_tag"] = self.image_tag @@ -121,6 +130,8 @@ def from_dict(cls, data: dict) -> RunDockerContainerTaskStep: docker_context_artifact_id=data.get("docker_context_artifact_id"), docker_context_artifact_version=data.get("docker_context_artifact_version"), docker_context_url=data.get("docker_context_url"), + image_artifact_id=data.get("image_artifact_id"), + image_artifact_version=data.get("image_artifact_version"), dockerfile_path=data.get("dockerfile_path", "Dockerfile"), container_name=data.get("container_name", "task-container"), image_tag=data.get("image_tag"), @@ -140,15 +151,16 @@ def from_dict(cls, data: dict) -> RunDockerContainerTaskStep: ) def config_problems(self) -> list[str]: - """A step naming no build context to run.""" - return [] if self._names_a_context() else [self._no_context()] - - def _names_a_context(self) -> bool: - return self.docker_context_artifact_id is not None or self.docker_context_url is not None - - def _no_context(self) -> str: - return (f"run_docker_container '{self.id}': names no build context; set docker_context_artifact_id or " - "docker_context_url (docker_context_url is user scope, so an import leaves it out)") + """A step naming no image or build context to run, or build options beside an image it runs as it is.""" + if self.image_artifact_id is not None: + build_only = [name for name in ("image_tag", "build_args") if getattr(self, name)] + return [f"run_docker_container '{self.id}': {' and '.join(build_only)} only apply to a build, and " + f"image_artifact_id names an image it runs as it is"] if build_only else [] + if self.docker_context_artifact_id is None and self.docker_context_url is None: + return [f"run_docker_container '{self.id}': names no image or build context; set image_artifact_id, " + "docker_context_artifact_id or docker_context_url (docker_context_url is user scope, so an import " + "leaves it out)"] + return [] async def execute(self, context: TaskStepContext) -> TaskStepContext: from agent_env.providers.sandbox_providers.sandbox_provider import ( @@ -181,44 +193,11 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: sandbox = await provider.get_sandbox(ds.sandbox_id) container = sandbox.scoped_name(self.container_name) - image_tag = sandbox.scoped_name(self.image_tag) if self.image_tag else f"{container}:latest" - - work_dir = f"/tmp/docker-context-{container}" - await sandbox.exec_script( - f"rm -rf {shlex.quote(work_dir)} && mkdir -p {shlex.quote(work_dir)}" - ) - - if self.docker_context_artifact_id is not None: - await self._stage_from_universe(sandbox, ds.sandbox_id, work_dir) - else: - await self._stage_zip_from_url(sandbox, self.docker_context_url, work_dir) - - dockerfile_abs = posixpath.join(work_dir, self.dockerfile_path) - await sandbox.exec_script( - f"test -f {shlex.quote(dockerfile_abs)} " - f"|| (echo {shlex.quote(f'Dockerfile not found at {self.dockerfile_path} inside the build context')} >&2; " - f"exit 1)" - ) - - build_arg_flags = "" - if self.build_args: - build_arg_flags = " ".join( - f"--build-arg {shlex.quote(f'{k}={v}')}" for k, v in self.build_args.items() - ) label = shlex.quote(f"{SANDBOX_LABEL}={ds.sandbox_id}") - build_cmd = ( - f"cd {shlex.quote(work_dir)} && " - f"docker build --label {label} " - f"-f {shlex.quote(self.dockerfile_path)} " - f"-t {shlex.quote(image_tag)} " - f"{build_arg_flags} ." - ) - logger.info( - f"Building docker image '{image_tag}' on sandbox {ds.sandbox_id} " - f"(dockerfile={self.dockerfile_path})" - ) - await _build(sandbox, build_cmd) - await sandbox.exec_script(f"rm -rf {shlex.quote(work_dir)}") + if self.image_artifact_id is not None: + image_tag = await self._load_image(sandbox, ds.sandbox_id) + else: + image_tag = await self._build_image(sandbox, ds.sandbox_id, container, label) network_flag = "" if self.network: @@ -300,6 +279,54 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: }) return context + async def _load_image(self, sandbox, sandbox_id: str) -> str: + """Put the image artifact's image on the sandbox, as an agent's is: pulled, loaded or built from its context + only where the sandbox doesn't hold it; its name.""" + image = await asyncio.to_thread(DockerImageArtifact.get, self.image_artifact_id, self.image_artifact_version) + logger.info(f"Loading docker image '{image.image_name}' onto sandbox {sandbox_id}") + await sandbox.load_docker_images([image]) + return image.image_name + + async def _build_image(self, sandbox, sandbox_id: str, container: str, label: str) -> str: + """Stage the build context on the sandbox and build it; the image's tag.""" + image_tag = sandbox.scoped_name(self.image_tag) if self.image_tag else f"{container}:latest" + work_dir = f"/tmp/docker-context-{container}" + await sandbox.exec_script( + f"rm -rf {shlex.quote(work_dir)} && mkdir -p {shlex.quote(work_dir)}" + ) + + if self.docker_context_artifact_id is not None: + await self._stage_from_universe(sandbox, sandbox_id, work_dir) + else: + await self._stage_zip_from_url(sandbox, self.docker_context_url, work_dir) + + dockerfile_abs = posixpath.join(work_dir, self.dockerfile_path) + await sandbox.exec_script( + f"test -f {shlex.quote(dockerfile_abs)} " + f"|| (echo {shlex.quote(f'Dockerfile not found at {self.dockerfile_path} inside the build context')} >&2; " + f"exit 1)" + ) + + build_arg_flags = "" + if self.build_args: + build_arg_flags = " ".join( + f"--build-arg {shlex.quote(f'{k}={v}')}" for k, v in self.build_args.items() + ) + build_cmd = ( + f"cd {shlex.quote(work_dir)} && " + f"docker build --label {label} " + f"-f {shlex.quote(self.dockerfile_path)} " + f"-t {shlex.quote(image_tag)} " + f"{build_arg_flags} ." + ) + logger.info( + f"Building docker image '{image_tag}' on sandbox {sandbox_id} " + f"(dockerfile={self.dockerfile_path})" + ) + await _build(sandbox, build_cmd) + await sandbox.exec_script(f"rm -rf {shlex.quote(work_dir)}") + return image_tag + async def _ensure_network(self, sandbox, name: str) -> str: # host / none / bridge / container: are Docker built-in modes, not user bridges -- nothing to create. if name in ("host", "none", "bridge"): diff --git a/tst/integration/cli/run_bundle_task_image_test.py b/tst/integration/cli/run_bundle_task_image_test.py new file mode 100644 index 000000000..f1a32e024 --- /dev/null +++ b/tst/integration/cli/run_bundle_task_image_test.py @@ -0,0 +1,69 @@ +"""``agent-env run`` on a bundle whose task starts its container from an image folder, ``artifacts//``, named as +``image_artifact_id``: the bundle writes the folder as its build context, the first run builds the image once where it +starts the container, as an agent's image is built where it's installed, a rerun builds nothing, and the grader in the +container writes the reward its score is. Needs a Docker daemon.""" + +import json +import logging + +import pytest +from click.testing import CliRunner + +from agent_env.artifact.store import reset_artifact_store +from agent_env.cli import cli +from agent_env.config import configure, reset_config +from agent_env.providers.sandbox_providers import host_images + +pytestmark = [pytest.mark.integration, pytest.mark.int_test_slow] + +TASK = json.dumps([ + {"id": "box", "type": "deploy_sandbox", "sandbox_name": "box", "sandbox_mode": "vm", "sandbox_type": "local"}, + {"id": "task", "type": "run_docker_container", "sandbox_name": "box", "container_name": "task", + "image_artifact_id": "task-image", "command_override": "sleep infinity", "depends_on": ["box"]}, + {"id": "grade", "type": "run_container_unit_tests_verifier", "sandbox_name": "box", "container_name": "task", + "verifier_id": "tests", "reward_path": "/logs/verifier/reward.txt", "depends_on": ["task"], + "command": "mkdir -p /logs/verifier && grep -qx built /built && echo 1 > /logs/verifier/reward.txt"}, + {"id": "down", "type": "teardown_sandboxes", "sandbox_names": ["box"], "depends_on": ["grade"]}, +]) + + +@pytest.fixture +def state(monkeypatch, tmp_path): + """Local stores under this test's folder. Whatever ran, no sandbox work folder may be left behind.""" + sandboxes = tmp_path / "sandboxes" + monkeypatch.chdir(tmp_path) + monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path / "state")) + monkeypatch.setenv("AGENT_ENV_DOCUMENT_STORE", "local") + monkeypatch.setenv("AGENT_ENV_OBJECT_STORE", "local") + monkeypatch.setenv("AGENT_ENV_LOCAL_SANDBOX_DIR", str(sandboxes)) + configure() + reset_artifact_store() + logging.disable(logging.CRITICAL) # pytest's live logging would take CliRunner's stdout + try: + yield tmp_path + assert not sandboxes.exists() or not any(sandboxes.iterdir()), "a run left a sandbox work folder" + finally: + logging.disable(logging.NOTSET) + reset_artifact_store() + reset_config() + + +def test_a_task_container_from_an_image_folder_is_built_by_the_first_run_alone(state, monkeypatch): + root = state / "bundle" + (root / "artifacts/task-image").mkdir(parents=True) + (root / "artifacts/task-image/Dockerfile").write_text( + "FROM mirror.gcr.io/library/debian:bookworm-slim\nRUN echo built > /built\n") + (root / "tasks").mkdir() + (root / "tasks/grade.json").write_text(TASK) + builds, build = [], host_images._build + monkeypatch.setattr(host_images, "_build", lambda *args: builds.append(args[2]) or build(*args)) + + first = CliRunner().invoke(cli, ["run", str(root)]) + + assert first.exit_code == 0 and "tasks/grade.json v1: passed" in first.output, first.output + assert len(builds) == 1, (first.output, builds) + + again = CliRunner().invoke(cli, ["run", str(root)]) + + assert again.exit_code == 0 and "tasks/grade.json v1: passed" in again.output, again.output + assert "building with docker" not in again.output and len(builds) == 1, (again.output, builds) diff --git a/tst/integration/task_step/test_run_docker_container_local.py b/tst/integration/task_step/test_run_docker_container_local.py index 805605601..997a0fb90 100644 --- a/tst/integration/task_step/test_run_docker_container_local.py +++ b/tst/integration/task_step/test_run_docker_container_local.py @@ -1,4 +1,5 @@ -"""What run_docker_container starts on a local sandbox is gone once the run is torn down. +"""What run_docker_container starts on a local sandbox is gone once the run is torn down, and an image artifact it +runs is built once and kept for the next run. A VM takes its containers down with it; a local sandbox shares this host's Docker, so it removes what carries its label. Needs Docker and a pull of a small public image. @@ -15,9 +16,10 @@ import httpx import pytest -from agent_env.artifact import FileArtifact, FileArtifactUniverse +from agent_env.artifact import DockerImageArtifact, FileArtifact, FileArtifactUniverse from agent_env.artifact.store import reset_artifact_store from agent_env.config import configure, reset_config +from agent_env.providers.sandbox_providers import host_images from agent_env.task.teardown import teardown_run from agent_env.task_step.context import TaskStepContext from agent_env.task_step.task_steps.deploy_sandbox import DeploySandboxTaskStep @@ -161,3 +163,37 @@ async def test_urls_load_into_a_run_docker_container_container(local_backends): report = await teardown_run(context) assert not report.still_up + + +@pytest.mark.asyncio +async def test_runs_of_an_image_artifact_build_it_once_and_teardown_leaves_it_for_the_next(local_backends, monkeypatch): + """The first run builds the image from its context, a later run starts its container from it with nothing built, + and a sandbox's teardown removes only what it started.""" + suffix = uuid.uuid4().hex[:8] + (local_backends / "image").mkdir() + (local_backends / "image/Dockerfile").write_text( + f"FROM mirror.gcr.io/library/debian:bookworm-slim\nRUN echo {suffix} > /built\n") + image = DockerImageArtifact.put_context(f"rdc4-img-{suffix}", description="a task image", + context_path=str(local_backends / "image"), dockerfile_path="Dockerfile", + platform=None) + builds, build = [], host_images._build + monkeypatch.setattr(host_images, "_build", lambda *args: builds.append(args[2]) or build(*args)) + try: + for run in "ab": + context = TaskStepContext(instance_id=f"rdc4-{run}-{suffix}") + try: + await DeploySandboxTaskStep( + id="box", version=None, sandbox_name="box", sandbox_mode="vm", sandbox_type="local", + ).execute(context) + await RunDockerContainerTaskStep( + id="ctr", version=None, sandbox_name="box", image_artifact_id=image.id, container_name="task", + command_override="sleep infinity", + ).execute(context) + assert _docker("exec", f"task-{context.deployed_sandboxes[0].sandbox_id}", "cat", "/built") == suffix + finally: + report = await teardown_run(context) + assert not report.still_up + assert builds == [image.image_name] + assert _docker("images", "-q", image.image_name) + finally: + subprocess.run(["docker", "rmi", "-f", image.image_name], capture_output=True) diff --git a/tst/unit/task_step/run_docker_container_test.py b/tst/unit/task_step/run_docker_container_test.py index 24dc37d27..b9392ea26 100644 --- a/tst/unit/task_step/run_docker_container_test.py +++ b/tst/unit/task_step/run_docker_container_test.py @@ -1,4 +1,4 @@ -"""Unit tests for RunDockerContainerTaskStep's keep_alive_with_base_command flag.""" +"""Unit tests for RunDockerContainerTaskStep: its fields, its build context, and an image it runs as it is.""" from __future__ import annotations @@ -13,6 +13,7 @@ from agent_env.providers.sandbox_providers import sandbox_provider from agent_env.providers.sandbox_providers.local_docker.provider import LocalSandbox from agent_env.task_step.context import DeployedSandbox, TaskStepContext +from agent_env.task_step.task_steps import run_docker_container from agent_env.task_step.task_steps.run_docker_container import ( RunDockerContainerTaskStep as Step, ) @@ -265,3 +266,64 @@ async def test_what_it_starts_maps_the_sandboxs_extra_hosts(monkeypatch, extra_h (run,) = [s for s in sandbox.scripts if "docker run -d" in s] assert ("--add-host host.docker.internal:host-gateway" in run) is bool(extra_hosts) + + +def test_an_image_artifact_roundtrips_in_place_of_a_build_context(): + step = Step(id="s", version=None, sandbox_name="h", image_artifact_id="ota-task-7", image_artifact_version=3) + + restored = Step.from_dict(step.to_dict()) + + assert (restored.image_artifact_id, restored.image_artifact_version) == ("ota-task-7", 3) + assert restored.config_problems() == [] + + +@pytest.mark.parametrize("sources", [ + {"image_artifact_id": "img", "docker_context_artifact_id": "u"}, + {"image_artifact_id": "img", "docker_context_url": "https://example.com/ctx.zip"}, + {"docker_context_artifact_id": "u", "docker_context_url": "https://example.com/ctx.zip"}, +], ids=["image-and-context", "image-and-url", "context-and-url"]) +def test_a_step_naming_two_sources_is_refused(sources): + with pytest.raises(ValueError, match="Pass one of `image_artifact_id`, `docker_context_artifact_id` and"): + Step(id="s", version=None, sandbox_name="h", **sources) + + +@pytest.mark.parametrize(("build_only", "named"), [ + ({"image_tag": "task:latest"}, "image_tag"), + ({"build_args": {"PY": "3.12"}}, "build_args"), + ({"image_tag": "task:latest", "build_args": {"PY": "3.12"}}, "image_tag and build_args"), +]) +def test_build_options_beside_an_image_artifact_are_a_config_problem(build_only, named): + step = Step(id="s", version=None, sandbox_name="h", image_artifact_id="img", **build_only) + + assert step.config_problems() == [f"run_docker_container 's': {named} only apply to a build, and " + "image_artifact_id names an image it runs as it is"] + + +class _ImageSandbox(_RunSandbox): + def __init__(self): + super().__init__() + self.loaded_images: list = [] + + async def load_docker_images(self, artifacts): + self.loaded_images.extend(artifacts) + + +@pytest.mark.asyncio +async def test_an_image_artifact_is_put_on_the_sandbox_and_run_with_nothing_staged_or_built(monkeypatch): + sandbox, image, got = _ImageSandbox(), SimpleNamespace(image_name="ota/task-7:base"), [] + monkeypatch.setattr(run_docker_container, "DockerImageArtifact", + SimpleNamespace(get=lambda id, version: got.append((id, version)) or image)) + monkeypatch.setattr(sandbox_provider, "build_sandbox_provider", + lambda _type: SimpleNamespace(get_sandbox=AsyncMock(return_value=sandbox))) + context = TaskStepContext(deployed_sandboxes=[ + DeployedSandbox(sandbox_name="h", sandbox_id="local-1", sandbox_mode="vm", sandbox_type="local"), + ]) + + await Step(id="s", version=None, sandbox_name="h", image_artifact_id="ota-task-7", image_artifact_version=3, + container_name="task", command_override="sleep infinity").execute(context) + + assert got == [("ota-task-7", 3)] and sandbox.loaded_images == [image] + assert not [s for s in sandbox.scripts if "docker build" in s or "docker-context" in s] + (run,) = [s for s in sandbox.scripts if "docker run -d" in s] + assert run.endswith(" ota/task-7:base sleep infinity") + assert context.metadata["deployed_docker_containers"][0]["image_tag"] == "ota/task-7:base" diff --git a/tst/unit/task_step/test_field_scopes.py b/tst/unit/task_step/test_field_scopes.py index fb6f71c83..d05bd5c25 100644 --- a/tst/unit/task_step/test_field_scopes.py +++ b/tst/unit/task_step/test_field_scopes.py @@ -29,7 +29,7 @@ UNSOURCED = { "add_skills": "add_skills 's': skill 'notes' names no source", "load_artifact": "load_artifact 's': names nothing to load", - "run_docker_container": "run_docker_container 's': names no build context", + "run_docker_container": "run_docker_container 's': names no image or build context", }