feat(bundle): write a built image as its build context when its deploys build it in their VMs

[earakely-scale]

Until now, a bundle always built its images on this machine. Preflight refused them on any remote provider, so a bundle with its own agents or servers could run only with --sandbox local.

This PR has the bundle write each image in the form its deploys can run:

• Every deploy on the local provider: built on this machine with docker, as before.
• Every deploy on providers whose VMs build images (beta_scale, modal_vm, e2b, sail_vm): written with put_context, so the image is only its build context. Each VM builds it (feat(images): build context-only images in VM sandboxes #133), and no local docker is needed.
• Refused before anything is written:
  • a run that deploys an image both ways, including a chain such as modal_vm,local;
  • a deploy on a provider that runs an image by name: Modal containers, Modal's gateway, or a lone server.

The decision belongs to preflight, which already resolves each deploy's provider. preflight_run returns the ids of the images it writes as build contexts, and materialize(..., contexts=) writes those with put_context.

Ledger: a build context's digest also covers its form and its platform (linux/amd64). Both are added only for a build context, so an image built on this machine hashes exactly as before. Every existing ledger row stays reusable, and the golden digests don't change. Switching an image's form rewrites it and its agent or env, and says why: "now written as a build context, which its VMs build, not an image built on this machine".

Dry run: a new "Images:" section lists each built image and its form.

Tests

• Unit tests:
  • preflight's form decision for agents and envs;
  • the by-name and mixed refusals, including the chain case;
  • a context write that runs no build and needs no docker, and whose source_digest matches the folder;
  • a form switch rewriting the image and its agent;
  • the dry-run listing;
  • an @local context, which no store can sign, pushed over exec and then built.
• Full unit tier: 7008 passed.

Live, beta_scale, @local ids only

• The integration tests' bundle: its four agent Dockerfile shapes (plain, COPY . with .dockerignore and a link, a Dockerfile in a subfolder, multi-stage) plus an MCP server through the gateway, run with --sandbox beta_scale.
  • All 15 writes finished with no docker build.
  • Each agent replied with what its build should contain. The four tasks passed in 58–69 s each, and the gateway deploy took 106 s.
  • All 5 sandboxes were torn down.
• Dry runs:
  • A rerun reuses every image.
  • --sandbox local would rewrite each image with the form-switch reason.
  • --sandbox modal and beta_scale,modal are refused at every deploy before anything is written.
• Build timing: the heaviest image I could find, a Claude Code agent (two base images, a global npm install, apt and pip, 1.26 GB), builds in 88 s from cold inside a 2 vCPU / 8 GB beta_scale VM.

Known limits

• Modal: containers can't build an image yet, so a chain that includes modal is refused for these images. The next change makes Modal build them.
• Rebuild cost: each VM builds its images from scratch. A gateway VM builds its servers one at a time, and no cache is shared across VMs.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; the earlier provider concern is addressed and no new issue was established.

Findings

1.  Plugin environment skips image choice ▶

Fix with agent prompt

### Issue 1
src/agent_env/bundle/preflight.py:undefined-200
If a plugin environment provider deploys a bundle-built image on a remote VM, `_env` returns before this new `_use` call. Preflight never selects the build-context form, so materialization builds the image locally and the remote VM cannot build it from the bundle's context. Include these deploys in the form decision or refuse them before writing.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Bundles can now write built images as contexts for VM providers to build, while local deployments keep using local image builds. Preflight selects the form from each image’s deployments, and dry runs show the planned form.

• Built images use the form their deployments can run.
• The ledger tracks whether a bundle image is local or VM-built.
• Dry runs list each built image and its planned form.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  P[Preflight checks deploys] --> L[Local only]
  P --> V[VM providers only]
  P --> R[Mixed or unsupported]
  L --> B[Build with local Docker]
  V --> C[Write build context]
  R --> X[Refuse before writing]
  B --> D[Ledger records image]
  C --> D

Loading

_{Reviews (3) · Last reviewed commit: "fix(bundle): refuse a build context on a..." · Reviewed by Greptile}

[greptile-apps]

Plugin environment skips image choice

If a plugin environment provider deploys a bundle-built image on a remote VM, _env returns before this new _use call. Preflight never selects the build-context form, so materialization builds the image locally and the remote VM cannot build it from the bundle's context. Include these deploys in the form decision or refuse them before writing.

Knowledge Base Used: Bundle authoring, installation, and execution

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agent_env/bundle/preflight.py
Line: 200

Comment:
**Plugin environment skips image choice**

If a plugin environment provider deploys a bundle-built image on a remote VM, `_env` returns before this new `_use` call. Preflight never selects the build-context form, so materialization builds the image locally and the remote VM cannot build it from the bundle's context. Include these deploys in the form decision or refuse them before writing.

**Knowledge Base Used:** [Bundle authoring, installation, and execution](https://app.greptile.com/scale-ai/-/custom-context/knowledge-base/scaleapi/agentenv-framework/-/docs/bundle-authoring-and-execution.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[earakely-scale]

This is unchanged here: a deploy_env on a plugin's env provider returned before the image checks before this PR too, so its images were never checked by preflight, which can't tell how a plugin's provider runs them. Such a deploy is left to deploy_env's own preflight, as before, and the image is written as it was before this PR (built on this machine).

[greptile-apps]

That’s a valid distinction. Plugin environment providers are intentionally left to deploy_env’s own preflight because this bundle preflight cannot know their deployment semantics; the early return preserves the existing behavior, including locally materializing their images. Since this PR does not change that contract, Issue 2 is not a regression and does not need a fix. I’m withdrawing that finding.

[earakely-scale]

@greptileai review