Add cached image quickstart

bot_bottle/backend/smolmachines/launch.py

@@ -45,7 +45,8 @@ from ...git_gate import (
     provision_git_gate_dynamic_keys,
     revoke_git_gate_provisioned_keys,
 )
-from ...log import info, warn
+from ...image_cache import warn_if_stale_path
+from ...log import die, info, warn
 from ...bottle_state import (
     egress_state_dir,
     git_gate_state_dir,
@@ -182,10 +183,13 @@ def _start_bundle(
     plan = _provision_git_gate_keys(plan)
     bundle_spec = _bundle_launch_spec(plan, network, proxy_host)
     token_env = _resolve_token_env(plan, dict(os.environ))
-    artifact = _ensure_smolmachine(
-        bundle_spec.image,
-        dockerfile=_bundle.SIDECAR_BUNDLE_DOCKERFILE,
-    )
+    if _image_policy(plan) == "cached":
+        artifact = _cached_smolmachine(bundle_spec.image, label="sidecar")
+    else:
+        artifact = _ensure_smolmachine(
+            bundle_spec.image,
+            dockerfile=_bundle.SIDECAR_BUNDLE_DOCKERFILE,
+        )
     launch = _bundle.start_bundle_vm(
         bundle_spec,
         from_path=artifact,
@@ -467,8 +471,13 @@ def _agent_from_path(plan: SmolmachinesBottlePlan) -> Path:
         committed_path = Path(committed)
         if committed_path.is_file():
             info(f"using committed smolmachine {str(committed_path)!r}")
+            if _image_policy(plan) == "cached":
+                warn_if_stale_path("agent smolmachine artifact", committed_path)
             return committed_path
 
+    if _image_policy(plan) == "cached":
+        return _cached_smolmachine(plan.agent_image, label="agent")
+
     # Build the agent image and pack it into a `.smolmachine`
     # artifact (or hit the per-Dockerfile-digest cache). Runs here,
     # not in prepare, so the docker-build output doesn't garble the
@@ -479,6 +488,35 @@ def _agent_from_path(plan: SmolmachinesBottlePlan) -> Path:
     )
 
 
+def _image_policy(plan: object) -> str:
+    spec = getattr(plan, "spec", None)
+    return str(getattr(spec, "image_policy", "fresh"))
+
+
+def _cached_smolmachine(image_ref: str, *, label: str) -> Path:
+    """Return the cached smolmachine artifact for the current local image.
+
+    This is intentionally buildless: it inspects the existing local Docker
+    image ID and looks for the artifact keyed by that ID. If either side is
+    missing, the caller must use the fresh path to build/pack it.
+    """
+    if not docker_mod.image_exists(image_ref):
+        die(
+            f"cached {label} image {image_ref!r} not found; "
+            "run without --cached-images to build it"
+        )
+    digest = docker_mod.image_id(image_ref).split(":", 1)[-1][:16]
+    sidecar = _SMOLMACHINE_CACHE_DIR / f"{digest}.smolmachine.smolmachine"
+    if not sidecar.is_file():
+        die(
+            f"cached {label} smolmachine artifact for {image_ref!r} not found; "
+            "run without --cached-images to build it"
+        )
+    info(f"using cached {label} smolmachine {str(sidecar)!r}")
+    warn_if_stale_path(f"{label} smolmachine artifact", sidecar)
+    return sidecar
+
+
 def _ensure_smolmachine(image_ref: str, *, dockerfile: str = "") -> Path:
     """Build the agent docker image and convert it into a
     `.smolmachine` artifact, caching the result under