From d23385f0b348d379483ef5a4d6b9e3959993a212 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Tue, 17 Nov 2026 17:12:09 -0800 Subject: [PATCH 1/3] fix(bundle): register fails when a computer env it writes has no build a deploy can boot A registration whose compose of a computer env failed, a builder's disk full say, wrote the env and the tasks that deploy it and exited 0, though no deploy could boot it. With bootable, as a registration materializes, a computer env written or reused whose compose recorded builds but none ready or unverified stops it once every entity is written, before any task or eval, naming each build's status and reason. Registering again composes what it has left. Co-Authored-By: Claude Opus 5.5 --- src/agent_env/bundle/materialize.py | 29 +++++++++++++++++- src/agent_env/bundle/register.py | 6 ++-- src/agent_env/cli/bundle.py | 3 +- tst/unit/bundle/computer_env_folder_test.py | 34 +++++++++++++++++++++ tst/unit/bundle/register_test.py | 32 +++++++++++++++++++ 5 files changed, 100 insertions(+), 4 deletions(-) diff --git a/src/agent_env/bundle/materialize.py b/src/agent_env/bundle/materialize.py index ef3990380..8558162b5 100644 --- a/src/agent_env/bundle/materialize.py +++ b/src/agent_env/bundle/materialize.py @@ -30,6 +30,7 @@ from agent_env.env import Env from agent_env.env.envs.computer.env import ComputerEnv from agent_env.env.envs.computer.utils import composer +from agent_env.env.envs.computer.utils.composed import BUILT, stale from agent_env.env.envs.computer.utils.composer import Composing from agent_env.env.registry import get_env_registry from agent_env.eval import Eval, EvalTask @@ -91,6 +92,7 @@ def materialize( composing: Composing = Composing(), on_progress: Callable[[Write, str], None] | None = None, sandbox: str | None = None, + bootable: bool = False, ) -> Materialization: """Write ``plan``'s entities, tasks and evals. The first write that fails stops it, and every earlier one stays: they're in the ledger, so the next run reuses them. ``on_wait`` is called when another run @@ -107,7 +109,9 @@ def materialize( reading what the run would write first isn't preflighted, since the store doesn't hold it yet. Each computer env written is composed as ``composing`` says, and so is what one reused has left, as ``agent-env - env build`` does; ``on_progress``, when given, is told how each goes, a line at a time with its write. + env build`` does; ``on_progress``, when given, is told how each goes, a line at a time with its write. With + ``bootable``, as a registration has it, a computer env written or reused whose compose left no build a deploy can + boot stops it once every entity is written, before any task or eval, raising BundleError naming each such env. ``ledger`` keeps the rows, this run's in the ``@local`` namespace's store unless given; it also says whether each task and eval names the versions it reads (``Ledger.pins_references``) and whether each image the bundle builds is @@ -122,6 +126,7 @@ def materialize( evals = [write for write in plan.writes if write.kind is BundleKind.EVAL] done: dict[tuple[str, str], Materialized] = {} left: list[str] = [] + unbootable: list[str] = [] def through_ledger(write: Write, write_fn: Callable[[], int]) -> None: with _noted(plan, write, "checking" if dry_run else "writing"): @@ -151,6 +156,11 @@ def through_ledger(write: Write, write_fn: Callable[[], int]) -> None: if write.kind is BundleKind.ENV and done[_key(write)].reused and _compose_reused( write, done[_key(write)].version, _composing(composing, on_progress, write), dry_run): left.append(write.id) + if bootable and not dry_run and write.kind is BundleKind.ENV and ( + why := _unbootable(plan, write, done[_key(write)].version)): + unbootable.append(why) + if unbootable: + raise BundleError(unbootable) unwritten = {_key(item.write) for item in done.values() if not item.reused} if dry_run else set() written = done if ledger.pins_references else None built, problems, unchecked = {}, [], [] @@ -338,6 +348,23 @@ def _compose_reused(write: Write, version: int, composing: Composing, dry_run: b return True +def _unbootable(plan: Plan, write: Write, version: int) -> str | None: + """Why the computer env ``write`` left at ``version`` can't be deployed, when its compose recorded builds but none a + deploy boots: each failed, was skipped, or another agent-env recorded it.""" + env = Env.get(write.id, version) + if not isinstance(env, ComputerEnv) or env.computer is None: + return None + records = [(f"{form}/{arch}", record) for form, by_arch in env.metadata.get("composed", {}).items() + for arch, record in by_arch.items()] + if not records or any(record.get("status") in BUILT and not stale(record) for _, record in records): + return None + statuses = env.build_statuses() + builds = "; ".join(f"{pair} {statuses[pair]}" + (f" ({reason[:300]})" if (reason := record.get("reason")) else "") + for pair, record in records) + return (f"{_path(plan, write)}: {write.id} v{version} has no build a deploy can boot ({builds}); register again " + f"to compose them again, or run agent-env env build --id {write.id} --version {version}") + + def _write_env(plan: Plan, write: Write, composing: Composing = Composing()) -> int: entry = write.source.entry cls = get_env_registry()[entry.type] diff --git a/src/agent_env/bundle/register.py b/src/agent_env/bundle/register.py index 2924bbeb9..a0b2efa09 100644 --- a/src/agent_env/bundle/register.py +++ b/src/agent_env/bundle/register.py @@ -92,7 +92,9 @@ def register_bundle( the env's, emulating an arch no link runs natively unless ``emulate`` is False, which leaves it skipped. It turns namespace routing on while it runs. Raises BundleError listing every problem found before anything is - written; a write that fails stops it, and every earlier one stays, in the ledger, for the next run to reuse.""" + written; a write that fails stops it, and every earlier one stays, in the ledger, for the next run to reuse. So does + a computer env whose compose left no build a deploy can boot, once every entity is written and before any task: + registering again composes what it has left.""" composing = Composing(build_sandbox_provider(sandbox) if sandbox else None, emulate) with namespace_routing(): bundle = parse_bundle(Path(root)) @@ -116,7 +118,7 @@ def register_bundle( on_wait=lambda: say("waiting for another agent-env run to finish writing this bundle's ids"), on_build=lambda write: say(f" {_label(registered, write)}: building with docker and pushing"), on_write=lambda done: say(f" {registered_line(registered, done)}"), composing=composing, - on_progress=lambda write, line: say(f" {_label(registered, write)}: {line}")) + on_progress=lambda write, line: say(f" {_label(registered, write)}: {line}"), bootable=True) return Registration(registered, materialization, ids, tuple(_floating(registered)), identity, shared, requires) diff --git a/src/agent_env/cli/bundle.py b/src/agent_env/cli/bundle.py index 5f635c9ca..bb2cc494c 100644 --- a/src/agent_env/cli/bundle.py +++ b/src/agent_env/cli/bundle.py @@ -109,7 +109,8 @@ def register(folder: Path, tasks: tuple[str, ...], evals: tuple[str, ...], prefi registration. The plugin packages the bundle's bundle.toml requires must be installed, as for a run; a folder with no bundle.toml that uses plugin packages is given one. An id the store holds already takes a new version, whoever wrote it. A store other than this machine's is written only after you confirm, or with --yes. Registering - again writes only what changed since.""" + again writes only what changed since. A computer env whose compose leaves no build a deploy can boot fails the + registration once every entity is written, before any task: registering again composes it again.""" options = {"tasks": tasks, "evals": evals, "prefix": prefix, "sandbox": sandbox, "emulate": not no_emulate} click.echo(f"Registering {folder} into:") for line in describe_target(): diff --git a/tst/unit/bundle/computer_env_folder_test.py b/tst/unit/bundle/computer_env_folder_test.py index 9f4b9392c..63f76ee40 100644 --- a/tst/unit/bundle/computer_env_folder_test.py +++ b/tst/unit/bundle/computer_env_folder_test.py @@ -15,9 +15,12 @@ from agent_env.bundle.run import dry_run_bundle from agent_env.env import Env from agent_env.env.envs.computer.utils.composed import composition +from agent_env.env.envs.computer.utils import composer as composer_module from agent_env.env.envs.computer.utils.composer import Composing from agent_env.env.envs.computer.env import ComputerEnv from agent_env.env.envs.multi_env import MultiEnv +from agent_env.store.base import NotFoundError +from agent_env.task import Task from agent_env.providers.sandbox_providers.local_docker.provider import LocalSandboxProvider from tst.unit.bundle._support import layout, local_builds from tst.unit.bundle.computer_app_env_test import APP, TOML as APP_TOML @@ -108,6 +111,37 @@ def test_a_reused_computer_env_composes_what_it_has_left_on_the_runs_provider_an ("disk", "amd64"), ("disk", "arm64")])] +def test_a_computer_env_no_deploy_could_boot_stops_its_tasks_until_composing_it_again_builds_one(tmp_path, composed, + monkeypatch): + """With ``bootable``, as a registration materializes: the env stays written, and its reuse composes what it has + left.""" + results = iter(["failed", "ready"]) + + def compose(env, pairs=None, composing=Composing()): + composed.append(pairs) + env.update_metadata({**env.metadata, "composed": {"container": { + "amd64": {"status": next(results), "composer": composition()}, + "arm64": {"status": "ready", "composer": "another agent-env's"}}}}) + + monkeypatch.setattr(composer_module, "compose", compose) + root = _bundle(tmp_path / "desk") + env_id, task_id = (f"{_plan(root).bundle.bundle.id_root}/{name}" for name in ("desktop", "t")) + + with pytest.raises(BundleError) as stopped: + materialize(_plan(root), build_here=local_builds(_plan(root)), bootable=True) + assert stopped.value.problems == ( + f"envs/desktop: {env_id} v1 has no build a deploy can boot (container/amd64 failed; container/arm64 ready, by " + f"another composer); register again to compose them again, or run agent-env env build --id {env_id} " + "--version 1",) + with pytest.raises(NotFoundError): + Task.get(task_id) + + again = materialize(_plan(root), build_here=local_builds(_plan(root)), bootable=True) + + assert composed == [None, [("container", "amd64"), ("container", "arm64"), ("disk", "amd64"), ("disk", "arm64")]] + assert [done.write.id for done in again.writes if not done.reused] == [task_id] + + def test_a_dry_run_says_what_it_would_compose_of_a_reused_computer_env(tmp_path, composed): """Only the forms its deploys on the run's sandbox boot: local Docker's, the containers.""" root = _bundle(tmp_path / "desk") diff --git a/tst/unit/bundle/register_test.py b/tst/unit/bundle/register_test.py index 9584dfd94..b8d1d1e3b 100644 --- a/tst/unit/bundle/register_test.py +++ b/tst/unit/bundle/register_test.py @@ -19,6 +19,8 @@ from agent_env.bundle import register as register_module from agent_env.artifact.artifacts import computer as computer_artifact_module from agent_env.env import store as env_store_module +from agent_env.env.envs.computer.utils import composer as composer_module +from agent_env.env.envs.computer.utils.composed import composition from agent_env.env.published_images import COMPUTER_IMAGES from agent_env.bundle.register import REGISTRATIONS, _remote_name, register_bundle from agent_env.cli import cli @@ -511,6 +513,36 @@ def test_chromium_registers_into_a_shared_store_with_its_driver_and_base_compute assert (chromium.type, chromium.computer.id, chromium.driver.id) == ("computer_app", "ubuntu-24.04-browser", "page") +def test_a_computer_env_whose_compose_leaves_nothing_a_deploy_boots_fails_the_registration_before_its_tasks( + home, composed, monkeypatch): + """As a builder whose disk filled.""" + for module in (register_module, env_store_module): + monkeypatch.setattr(module, "shared_store", lambda store: True) + bases = {image.ref() for image in COMPUTER_IMAGES} + monkeypatch.setattr("agent_env.env.published_images._registry_digest", lambda ref: DIGEST if ref in bases else None) + monkeypatch.setattr(computer_artifact_module, "_inspect", + lambda image, arches, read: computer_artifact_module._unread(arches, "no registry in a test")) + + def compose(env, pairs=None, composing=None): + env.update_metadata({**env.metadata, "composed": {"container": { + "amd64": {"status": "failed", "reason": "no space left on device", "composer": composition()}, + "arm64": {"status": "skipped", "reason": "no link runs linux/arm64 natively", "composer": composition()}}}}) + + monkeypatch.setattr(composer_module, "compose", compose) + files = {"envs/desktop/env.toml": 'type = "computer"\ncomputer = "ubuntu-24.04"\ndriver = "reference"\n', + "tasks/t.json": json.dumps([{"id": "env", "type": "deploy_env", "env_id": "desktop"}])} + + result = CliRunner().invoke(cli, ["bundle", "register", str(layout(home / "desk", files)), "--yes"]) + + assert result.exit_code == 1, result.output + assert ("envs/desktop: desk-desktop v1 has no build a deploy can boot (container/amd64 failed (no space left on " + "device); container/arm64 skipped (no link runs linux/arm64 natively)); register again to compose them " + "again, or run agent-env env build --id desk-desktop --version 1") in result.output + assert Env.get("desk-desktop").version == 1 + with pytest.raises(NotFoundError): + Task.get("desk-t") + + def test_a_write_that_fails_leaves_no_pending_row(home, monkeypatch): def failing(*args, **kwargs): raise RuntimeError("the store went away") From 2431a6d1bc3fab77a57a038633578fe637b97fa9 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Tue, 17 Nov 2026 17:22:51 -0800 Subject: [PATCH 2/3] fix(bundle): the unbootable message says no task was written and how a skipped arch builds Co-Authored-By: Claude Opus 5.5 --- src/agent_env/bundle/materialize.py | 7 +++++-- tst/unit/bundle/computer_env_folder_test.py | 4 ++-- tst/unit/bundle/register_test.py | 6 ++++-- 3 files changed, 11 insertions(+), 6 deletions(-) diff --git a/src/agent_env/bundle/materialize.py b/src/agent_env/bundle/materialize.py index 8558162b5..ea612d01b 100644 --- a/src/agent_env/bundle/materialize.py +++ b/src/agent_env/bundle/materialize.py @@ -361,8 +361,11 @@ def _unbootable(plan: Plan, write: Write, version: int) -> str | None: statuses = env.build_statuses() builds = "; ".join(f"{pair} {statuses[pair]}" + (f" ({reason[:300]})" if (reason := record.get("reason")) else "") for pair, record in records) - return (f"{_path(plan, write)}: {write.id} v{version} has no build a deploy can boot ({builds}); register again " - f"to compose them again, or run agent-env env build --id {write.id} --version {version}") + how = (", emulating a skipped arch or on a --sandbox that runs it natively" + if any(record.get("status") == "skipped" for _, record in records) else "") + return (f"{_path(plan, write)}: {write.id} v{version} has no build a deploy can boot ({builds}), so no task was " + f"written: register again to compose what it left{how}, or compose it with agent-env env build --id " + f"{write.id} --version {version} and then register again") def _write_env(plan: Plan, write: Write, composing: Composing = Composing()) -> int: diff --git a/tst/unit/bundle/computer_env_folder_test.py b/tst/unit/bundle/computer_env_folder_test.py index 63f76ee40..294c8a779 100644 --- a/tst/unit/bundle/computer_env_folder_test.py +++ b/tst/unit/bundle/computer_env_folder_test.py @@ -131,8 +131,8 @@ def compose(env, pairs=None, composing=Composing()): materialize(_plan(root), build_here=local_builds(_plan(root)), bootable=True) assert stopped.value.problems == ( f"envs/desktop: {env_id} v1 has no build a deploy can boot (container/amd64 failed; container/arm64 ready, by " - f"another composer); register again to compose them again, or run agent-env env build --id {env_id} " - "--version 1",) + f"another composer), so no task was written: register again to compose what it left, or compose it with " + f"agent-env env build --id {env_id} --version 1 and then register again",) with pytest.raises(NotFoundError): Task.get(task_id) diff --git a/tst/unit/bundle/register_test.py b/tst/unit/bundle/register_test.py index b8d1d1e3b..ab1c81fb1 100644 --- a/tst/unit/bundle/register_test.py +++ b/tst/unit/bundle/register_test.py @@ -536,8 +536,10 @@ def compose(env, pairs=None, composing=None): assert result.exit_code == 1, result.output assert ("envs/desktop: desk-desktop v1 has no build a deploy can boot (container/amd64 failed (no space left on " - "device); container/arm64 skipped (no link runs linux/arm64 natively)); register again to compose them " - "again, or run agent-env env build --id desk-desktop --version 1") in result.output + "device); container/arm64 skipped (no link runs linux/arm64 natively)), so no task was written: register " + "again to compose what it left, emulating a skipped arch or on a --sandbox that runs it natively, or " + "compose it with agent-env env build --id desk-desktop --version 1 and then register again" + ) in result.output assert Env.get("desk-desktop").version == 1 with pytest.raises(NotFoundError): Task.get("desk-t") From 359bd1ac32ef5a83fb9e29e2bfa54f974352dafb Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Tue, 17 Nov 2026 17:35:45 -0800 Subject: [PATCH 3/3] refactor(bundle): name how much of a build's reason the unbootable problem quotes Co-Authored-By: Claude Opus 5.5 --- src/agent_env/bundle/materialize.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/agent_env/bundle/materialize.py b/src/agent_env/bundle/materialize.py index ea612d01b..b5dedd51a 100644 --- a/src/agent_env/bundle/materialize.py +++ b/src/agent_env/bundle/materialize.py @@ -50,6 +50,10 @@ from .plan import Plan, Write, artifact_writer, env_writer, unpinned_store_refs from .resolve import BuiltImage, BundleImage, ReferencedImage, build_step +#: How much of each build's reason the problem naming a computer env no deploy can boot quotes: a failed build's reason +#: holds the build's error, which can run to pages. +_REASON_CHARS = 300 + @dataclass(frozen=True) class Materialized: @@ -359,8 +363,8 @@ def _unbootable(plan: Plan, write: Write, version: int) -> str | None: if not records or any(record.get("status") in BUILT and not stale(record) for _, record in records): return None statuses = env.build_statuses() - builds = "; ".join(f"{pair} {statuses[pair]}" + (f" ({reason[:300]})" if (reason := record.get("reason")) else "") - for pair, record in records) + quoted = {pair: f" ({record['reason'][:_REASON_CHARS]})" for pair, record in records if record.get("reason")} + builds = "; ".join(f"{pair} {statuses[pair]}{quoted.get(pair, '')}" for pair, _ in records) how = (", emulating a skipped arch or on a --sandbox that runs it natively" if any(record.get("status") == "skipped" for _, record in records) else "") return (f"{_path(plan, write)}: {write.id} v{version} has no build a deploy can boot ({builds}), so no task was "