feat(orchestrator): slice 5 — build the consolidated sidecar bundle image (#352)

Answers "where do we build the consolidated sidecar": nowhere, until now.

  * sidecar.py — `Sidecar.ensure_built()` (default no-op) + `DockerSidecar`
    now defaults its image to the real bundle (`bot-bottle-sidecars`) and
    `ensure_built()` builds it from `Dockerfile.sidecars` when
    `docker image inspect` shows it's missing (no-op when present or when no
    dockerfile is configured, e.g. a pre-pulled image). `image_exists()`
    added.
  * service.py — `ensure_sidecar()` now builds then runs.
  * __main__.py — `--sidecar` runs the consolidated bundle (build-if-missing).

Scope note: this builds + launches the bundle *container*; making the
running instance functional across bottles needs the per-bottle,
source-IP-keyed multi-tenant config + registration/reload, and routing
agent bottles to it — the next slices (added to PRD 0070's roadmap).

Tests: unit (docker mocked) — image_exists, ensure_built builds when
missing / no-op when present / no-op without a dockerfile / raises on build
failure; ensure_sidecar builds-then-runs; integration (gated, no heavy
build) — image_exists reflects real docker state. Full suite green (only
pre-existing /bin/sleep errors).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WBMWTEtQdJ4W5UrWuLHCck

bot_bottle/orchestrator/__main__.py

@@ -38,8 +38,8 @@ def main(argv: list[str] | None = None) -> int:
         help="launch broker: 'stub' records requests; 'docker' runs containers",
     )
     parser.add_argument(
-        "--sidecar-image", default=None,
-        help="if set, run one consolidated per-host sidecar from this image",
+        "--sidecar", action="store_true",
+        help="run one consolidated per-host sidecar bundle (build-if-missing)",
     )
     args = parser.parse_args(argv)
 
@@ -51,10 +51,11 @@ def main(argv: list[str] | None = None) -> int:
     # anything; 'docker' runs real containers (firecracker drops in later).
     secret = secrets.token_bytes(32)
     broker: LaunchBroker = DockerBroker(secret) if args.broker == "docker" else StubBroker(secret)
-    sidecar: Sidecar | None = DockerSidecar(args.sidecar_image) if args.sidecar_image else None
+    sidecar: Sidecar | None = DockerSidecar() if args.sidecar else None
     orchestrator = Orchestrator(registry, broker, secret, sidecar)
 
-    # One persistent per-host sidecar, shared by every bottle (idempotent).
+    # One persistent per-host sidecar, shared by every bottle: build the
+    # bundle image if missing, then bring the singleton up (idempotent).
     if sidecar is not None:
         orchestrator.ensure_sidecar()
         log.info("consolidated sidecar ensured", context={"name": sidecar.name})

bot_bottle/orchestrator/service.py

@@ -83,9 +83,10 @@ class Orchestrator:
     # --- consolidated sidecar ----------------------------------------------
 
     def ensure_sidecar(self) -> None:
-        """Bring the single per-host sidecar up (idempotent). No-op when no
-        sidecar is configured."""
+        """Ensure the single per-host sidecar is built and up (idempotent).
+        No-op when no sidecar is configured."""
         if self._sidecar is not None:
+            self._sidecar.ensure_built()
             self._sidecar.ensure_running()
 
     def sidecar_status(self) -> dict[str, object]:

bot_bottle/orchestrator/sidecar.py

@@ -18,15 +18,25 @@ launches never spawn N sidecars.
 from __future__ import annotations
 
 import abc
+import os
+from pathlib import Path
 
 from ..docker_cmd import run_docker
 
 SIDECAR_NAME = "bot-bottle-orch-sidecar"
 SIDECAR_LABEL = "bot-bottle-orch-sidecar=1"
 
+# The real sidecar-bundle image + its Dockerfile. Kept as a local constant
+# rather than imported from backend.docker.sidecar_bundle, which would drag
+# the whole backend layer into the lean orchestrator (see #359); unify when
+# that lands. Env override matches the backend's BOT_BOTTLE_SIDECAR_IMAGE.
+SIDECAR_BUNDLE_IMAGE = os.environ.get("BOT_BOTTLE_SIDECAR_IMAGE", "bot-bottle-sidecars:latest")
+SIDECAR_DOCKERFILE = "Dockerfile.sidecars"
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+
 
 class SidecarError(Exception):
-    """The shared sidecar failed to start/stop (non-zero `docker` exit)."""
+    """The shared sidecar failed to build/start/stop (non-zero `docker` exit)."""
 
 
 class Sidecar(abc.ABC):
@@ -34,10 +44,16 @@ class Sidecar(abc.ABC):
 
     name: str
 
+    def ensure_built(self) -> None:
+        """Ensure the sidecar's image / rootfs exists, building it if needed.
+        Default: nothing to build (e.g. a stub or a pre-pulled image)."""
+        return
+
     @abc.abstractmethod
     def ensure_running(self) -> None:
         """Start the sidecar if it isn't already up. Idempotent: a no-op
-        when it's already running (that's the whole point — one per host)."""
+        when it's already running (that's the whole point — one per host).
+        Assumes the image exists — call `ensure_built()` first."""
 
     @abc.abstractmethod
     def is_running(self) -> bool:
@@ -49,11 +65,43 @@ class Sidecar(abc.ABC):
 
 
 class DockerSidecar(Sidecar):
-    """The consolidated sidecar as a single, fixed-name Docker container."""
+    """The consolidated sidecar as a single, fixed-name Docker container.
 
-    def __init__(self, image_ref: str, *, name: str = SIDECAR_NAME) -> None:
+    `image_ref` defaults to the real sidecar-bundle image; `ensure_built`
+    builds it from `Dockerfile.sidecars` when it's missing. (Note: slice 5
+    builds + launches the bundle container; wiring its per-bottle,
+    source-IP-keyed config is a later slice — see PRD 0070.)"""
+
+    def __init__(
+        self,
+        image_ref: str = SIDECAR_BUNDLE_IMAGE,
+        *,
+        name: str = SIDECAR_NAME,
+        build_context: Path | None = None,
+        dockerfile: str | None = SIDECAR_DOCKERFILE,
+    ) -> None:
         self.image_ref = image_ref
         self.name = name
+        self._build_context = build_context or _REPO_ROOT
+        self._dockerfile = dockerfile
+
+    def image_exists(self) -> bool:
+        return run_docker(["docker", "image", "inspect", self.image_ref]).returncode == 0
+
+    def ensure_built(self) -> None:
+        """Build the bundle image from its Dockerfile when it's missing.
+        No-op when the image is already present, or when no dockerfile is
+        configured (e.g. a pre-pulled image)."""
+        if self._dockerfile is None or self.image_exists():
+            return
+        proc = run_docker([
+            "docker", "build",
+            "-t", self.image_ref,
+            "-f", str(self._build_context / self._dockerfile),
+            str(self._build_context),
+        ])
+        if proc.returncode != 0:
+            raise SidecarError(f"sidecar image build failed: {proc.stderr.strip()}")
 
     def is_running(self) -> bool:
         proc = run_docker([
@@ -85,4 +133,7 @@ class DockerSidecar(Sidecar):
             raise SidecarError(f"sidecar failed to stop: {proc.stderr.strip()}")
 
 
-__all__ = ["Sidecar", "DockerSidecar", "SidecarError", "SIDECAR_NAME", "SIDECAR_LABEL"]
+__all__ = [
+    "Sidecar", "DockerSidecar", "SidecarError",
+    "SIDECAR_NAME", "SIDECAR_LABEL", "SIDECAR_BUNDLE_IMAGE",
+]