feat(bundle): build an agent's image from its folder's Dockerfile

[earakely-scale]

An agent folder with a Dockerfile and no image was already parsed and planned as a built image, but materialize refused to write it. A bundle run now builds it, so a bundle can carry an agent's source instead of naming an image someone registered first:

agents/solver/
  Dockerfile        # built from this folder
  agent.toml        # optional: default_env_vars, [metadata]
  ...

What it does

• Build and write. materialize copies the folder's files into a temporary build context, runs build_image() over it on this machine for its own platform, and writes the result as the @local docker_image <agent id>__agent_image. The copy is what the ledger hashes (build_context_files): every file of the folder, agent.toml included, less what the OS or Python leaves behind (__pycache__, .DS_Store, ...). Links inside the bundle are copied as their targets. The folder's .dockerignore still applies to the build.
• Written like any image. The image is pushed to the local registry and saved as a tarball in the local object store, and the same copy is kept as its build context for install/v1. The agent is written over it right after, as for a store image.
• Ledger tracking.
  • An unchanged folder reuses the image.
  • A changed file rebuilds it and rewrites the agent over it.
  • What the build fetches, such as the base image a FROM tag names, isn't an input.
• Dry run. agent-env run --dry-run lists the image apart from its agent, as agents/solver (Dockerfile image): v1 (new), and predicts a rebuild and the agent rewritten over it. It builds nothing.
• Docker. Needed only for an image that will be built: one the ledger reuses needs no docker, in the run or the dry run. Without docker, an image that needs building is refused before anything is written.
• Errors. A failed build is a bundle problem naming the agent's folder, with the first line and the last 40 lines of docker's output. A failed push, save or local-registry start is a one-line problem too. Neither is a traceback.
• Run output. materialize(on_build=...) is called before each build. agent-env run prints agents/solver (Dockerfile image): building with docker, which can take minutes and labels the image's write apart from its agent's.
• Interrupted puts. DockerImageArtifact.put now writes its tarball and build context under an attempt prefix, as file artifacts already do. A put that stopped before writing its document, say on Ctrl-C during a long upload, no longer blocks every later put of that id. Only new objects' keys change; readers follow the URLs in the document.

Limits

• The image is built for this machine's platform and stays on this machine, so only the local sandbox runs it. Remote providers need it in a store they can reach. Refusing a built image on a remote provider before the run is the planned minimal provider preflight's job.
• The first push starts the local registry, which pulls registry:2 from Docker Hub.
• Env folders with a Dockerfile are still refused, since envs can't be written from a bundle yet. Their image inputs will be the same build_context_files.
• The bundle docs moved off the README to the docs site, so the authoring text for this lands there separately.

Tests

• materialize:

  • a folder is built and the agent written over its image;
  • a rerun builds nothing and reuses both;
  • a changed file rebuilds and rewrites the agent;
  • an agent.toml edit rebuilds the image and rewrites the agent;
  • the context is the hashed files: OS and Python leftovers stay out (and editing one reuses the image), and a link is copied as its target;
  • a dry run predicts a rebuild and the rewrite of its agent, and builds nothing;
  • a reused image needs no docker, in the run and the dry run;
  • an image to build without docker is refused before any write, in the run and the dry run;
  • a failed build and a failed push are bundle problems naming the agent.

• run: the progress lines, and the CLI dry run's line for a built image.

• DockerImageArtifact.put: a put that stops before its document doesn't block the next.

• ledger: what a built image is made from.

• Unit tier: 5,750 passed.

• Integration (slow tier, real docker builds, agents deployed on the local sandbox): tst/integration/cli/run_bundle_built_agents_test.py. One bundle holds four agents, each built from a different shape of Dockerfile, and each replies with what its build put in it:

  agent	Dockerfile	its reply shows
  plain	at the folder's root, no agent.toml	the greeting file it copied
  whole	COPY ., with a .dockerignore, a link, __pycache__ and .DS_Store	only notes.md: the ignored file and the leftovers stayed out, and the link was copied as its target
  subdir	docker/Dockerfile, named by agent.toml	the greeting agent.toml's env vars set
  staged	multi-stage Dockerfile.agent	the greeting an earlier stage wrote

  • Each agent's task deploys it, prompts it and checks the reply.
  • A rerun builds nothing.
  • Editing one agent's file rebuilds only that agent; changing its __pycache__ or .DS_Store doesn't.
  • A second test checks that a Dockerfile that fails to build gives one problem with docker's output and writes no agent.
  • Both pass on CI's Linux runner, and locally on macOS.
  • The test closes the process's grant server when it ends. Its agents moved their trajectories through it, with a certificate from the test's state root, which a later test's agents wouldn't trust.

End to end (local sandbox, default local stores)

I ran a bundle whose agents/echo/ folder holds the integration suites' echo A2A agent and its Dockerfile. Its task deploys the agent, prompts it once and checks the reply with response_contains. Command: agent-env run <bundle> --sandbox local.

run	image	agent	smoke task
dry run	v1 (new), nothing built or written	v1 (new)	would run
first	built, v1	v1	passed
after editing agent.py and adding __pycache__/ and .DS_Store	rebuilt, v2 (files changed: agent.py)	v2 (its image v1 → v2)	passed, and the reply came from v2
rerun, nothing changed	v2, unchanged	v2, unchanged	passed
dry run after editing only __pycache__/	v2, unchanged	v2, unchanged	would run

The saved build context of v2 holds Dockerfile, agent.py and agent.toml, and its tarball sits under its attempt prefix (.../2-<id>/...).

🤖 Generated with Claude Code

Confidence Score: 5/5

The changes since the previous review appear safe to merge; no new issue was found.

Summary

Bundle runs can now build an agent’s Docker image from the files in its folder and write the agent to use it. The image is tracked for reuse, and interrupted image uploads get their own object keys.

• Bundle runs build an agent’s image from its folder before writing the agent.
• Interrupted image puts no longer block a later write.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Agent folder] --> B[Stage build files]
    B --> C[Build image]
    C --> D[Push and save image]
    D --> E[Write image artifact]
    E --> F[Write agent]

Loading

_{Reviews (6) · Last reviewed commit: "refactor(artifact): name a docker image ..."}