didericis/bot-bottle
1
0
Fork 0
Code Issues 5 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

refactor(commit): introduce Freezer class hierarchy across backends

Browse Source 
Adds a Freezer ABC (backend/freeze.py) that encapsulates the
stop-commit-mark-preserved flow for all backends, following the same
pattern as BottleBackend. Each backend gets its own Freezer subclass:

  DockerFreezer           — docker commit
  MacosContainerFreezer   — container export + image rebuild; prompts
                            to stop if the container is running
  SmolmachinesFreezer     — smolvm pack create --from-vm

The base class owns write_committed_image, mark_preserved, and the
resume hint. Subclasses implement _freeze() and optionally override
_export_hint() for migration instructions.

Freezer.commit(agent, bottle) is the primary entry point for use
within a live launch context. Freezer.commit_slug(slug) is a
convenience wrapper for cmd_commit, which no longer branches on
backend names itself.

get_freezer(backend_name) is the factory, analogous to
get_bottle_backend(). CommitCancelled is raised by MacosContainerFreezer
when the user declines the stop prompt; cmd_commit catches it and
returns 0.
This commit is contained in:
didericis (claude)
2026-06-23 07:41:48 +00:00
committed by didericis
parent 8c4861abde
commit b1ecf73fd2
8 changed files with 540 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files
bot_bottle/backend/__init__.py
+8
View File
@@ -526,6 +526,11 @@ from .docker import DockerBottleBackend # noqa: E402 # pylint: disable=wrong-i
from .macos_container import MacosContainerBottleBackend # noqa: E402 # pylint: disable=wrong-import-position
from .smolmachines import SmolmachinesBottleBackend # noqa: E402 # pylint: disable=wrong-import-position
# Freezer is imported after the backend classes for the same reason —
# Freezer.commit_slug constructs ActiveAgent, so the dataclass must be
# fully defined first.
from .freeze import CommitCancelled, Freezer, get_freezer # noqa: E402 # pylint: disable=wrong-import-position
# The dict is heterogeneous: each value is a BottleBackend specialized
# over its own plan type. Concrete plan types are erased here because
@@ -613,9 +618,12 @@ __all__ = [
"BottleCleanupPlan",
"BottlePlan",
"BottleSpec",
"CommitCancelled",
"ExecResult",
"Freezer",
"enumerate_active_agents",
"get_bottle_backend",
"get_freezer",
"has_backend",
"known_backend_names",
]
bot_bottle/backend/docker/freezer.py
+22
View File
@@ -0,0 +1,22 @@
"""DockerFreezer — snapshot a Docker bottle via `docker commit`."""
from __future__ import annotations
from .. import ActiveAgent, Bottle
from ..freeze import Freezer
from .util import commit_container
from ...log import info
class DockerFreezer(Freezer):
"""Freezes a Docker bottle by running `docker commit`."""
backend_name = "docker"
def _freeze(self, agent: ActiveAgent, bottle: Bottle) -> str:
image_tag = f"bot-bottle-committed-{agent.slug}:latest"
commit_container(bottle.name, image_tag)
return image_tag
def _export_hint(self, slug: str, image_ref: str) -> None:
info(f"to export for migration: docker save {image_ref} -o {slug}.tar")
bot_bottle/backend/freeze.py
+131
View File
@@ -0,0 +1,131 @@
"""Freezer — snapshot a running bottle to a resumable artifact.
Follows the same pattern as BottleBackend: a shared base class with
common post-freeze steps (write committed-image path, mark preserved,
print resume hint) and backend-specific subclasses in their respective
backend directories.
Entry points:
Freezer.commit(agent, bottle) — for use within a live launch context
Freezer.commit_slug(slug) — for cmd_commit when no live Bottle exists
get_freezer(backend_name) — factory
"""
from __future__ import annotations
from abc import ABC, abstractmethod
from . import ActiveAgent, Bottle, ExecResult
from ..bottle_state import mark_preserved, write_committed_image
from ..log import die, info
class CommitCancelled(Exception):
"""Raised by Freezer._freeze when the user declines a confirmation prompt."""
class Freezer(ABC):
"""Freezes a running bottle to a resumable artifact.
The base class owns the shared post-commit steps:
- write_committed_image — records the artifact path in per-bottle state
- mark_preserved — prevents teardown from removing the state dir
- resume hint — printed to stderr after the snapshot
Subclasses implement _freeze with the backend-specific snapshot
operation and optionally override _export_hint for migration hints.
"""
backend_name: str
def commit(self, agent: ActiveAgent, bottle: Bottle) -> None:
"""Freeze `bottle` to a resumable artifact.
Calls _freeze for the backend-specific snapshot, then writes the
committed image reference to per-bottle state and marks the bottle
preserved so the next `./cli.py resume` boots from the snapshot.
Raises CommitCancelled if the user declines an interactive
confirmation prompt (e.g. the macos-container stop prompt).
"""
image_ref = self._freeze(agent, bottle)
write_committed_image(agent.slug, image_ref)
mark_preserved(agent.slug)
info(f"to resume from this snapshot: ./cli.py resume {agent.slug}")
self._export_hint(agent.slug, image_ref)
@abstractmethod
def _freeze(self, agent: ActiveAgent, bottle: Bottle) -> str:
"""Backend-specific snapshot. Returns the image tag or artifact path
stored by write_committed_image. Raises CommitCancelled if the user
declines a stop-confirmation prompt."""
def _export_hint(self, slug: str, image_ref: str) -> None:
"""Optionally print an export-for-migration hint after committing.
Overridden by backends that provide a meaningful export command."""
def commit_slug(self, slug: str) -> None:
"""Convenience entry for cmd_commit when no live Bottle is available.
Constructs a minimal ActiveAgent from per-bottle state and a
name-only Bottle stub, then delegates to commit(). Freezer
subclasses must not call exec / exec_agent / cp_in on the stub."""
from ..bottle_state import read_metadata
metadata = read_metadata(slug)
agent = ActiveAgent(
backend_name=self.backend_name,
slug=slug,
agent_name=metadata.agent_name if metadata else "",
started_at=metadata.started_at if metadata else "",
services=(),
)
bottle: Bottle = _NamedBottle(f"bot-bottle-{slug}")
self.commit(agent, bottle)
class _NamedBottle(Bottle):
"""Name-only Bottle stub for Freezer.commit_slug.
Only `name` is meaningful. All runtime operations raise
NotImplementedError — Freezer._freeze implementations must only
access bottle.name."""
def __init__(self, name: str) -> None:
self.name = name
def agent_argv(self, argv: list[str], *, tty: bool = True) -> list[str]:
raise NotImplementedError
def exec_agent(self, argv: list[str], *, tty: bool = True) -> int:
raise NotImplementedError
def exec(self, script: str, *, user: str = "node") -> ExecResult:
raise NotImplementedError
def cp_in(self, host_path: str, container_path: str) -> None:
raise NotImplementedError
def close(self) -> None:
pass
def get_freezer(backend_name: str) -> Freezer:
"""Return the Freezer for the named backend.
backend_name "" is treated as "docker" for backward compatibility
with state dirs written before the backend field was added."""
resolved = backend_name or "docker"
if resolved == "docker":
from .docker.freezer import DockerFreezer
return DockerFreezer()
if resolved == "macos-container":
from .macos_container.freezer import MacosContainerFreezer
return MacosContainerFreezer()
if resolved == "smolmachines":
from .smolmachines.freezer import SmolmachinesFreezer
return SmolmachinesFreezer()
die(
f"commit is only supported for docker, macos-container, and "
f"smolmachines; backend {backend_name!r} has no freezer"
)
raise AssertionError("unreachable")
bot_bottle/backend/macos_container/freezer.py
+50
View File
@@ -0,0 +1,50 @@
"""MacosContainerFreezer — snapshot a macOS container bottle.
Apple's `container export` requires the container to be stopped first.
When the container is running the freezer prompts the user to confirm
the stop before proceeding."""
from __future__ import annotations
import sys
from .. import ActiveAgent, Bottle
from ..freeze import CommitCancelled, Freezer
from .util import commit_container, container_is_running, stop_container
from ...log import info
class MacosContainerFreezer(Freezer):
"""Freezes a macOS-container bottle via `container export` + image rebuild."""
backend_name = "macos-container"
def _freeze(self, agent: ActiveAgent, bottle: Bottle) -> str:
image_tag = f"bot-bottle-committed-{agent.slug}:latest"
if container_is_running(bottle.name):
sys.stderr.write(
f"bot-bottle: bottle {agent.slug!r} is running; "
"commit will stop it. Continue? [y/N] "
)
sys.stderr.flush()
reply = _read_tty_line().strip().lower()
if reply not in ("y", "yes"):
raise CommitCancelled
stop_container(bottle.name)
commit_container(bottle.name, image_tag)
return image_tag
def _export_hint(self, slug: str, image_ref: str) -> None:
info(
f"to export for migration: "
f"container image save {image_ref} -o {slug}.tar"
)
def _read_tty_line() -> str:
"""Read one line from /dev/tty, falling back to stdin."""
try:
with open("/dev/tty", "r", encoding="utf-8") as tty:
return tty.readline().rstrip("\n")
except OSError:
return sys.stdin.readline().rstrip("\n")
bot_bottle/backend/smolmachines/freezer.py
+25
View File
@@ -0,0 +1,25 @@
"""SmolmachinesFreezer — snapshot a smolmachines bottle via smolvm pack."""
from __future__ import annotations
from .. import ActiveAgent, Bottle
from ..freeze import Freezer
from .smolvm import pack_create_from_vm
from ...bottle_state import bottle_state_dir
from ...log import info
class SmolmachinesFreezer(Freezer):
"""Freezes a smolmachines bottle via `smolvm pack create --from-vm`."""
backend_name = "smolmachines"
def _freeze(self, agent: ActiveAgent, bottle: Bottle) -> str:
output = bottle_state_dir(agent.slug) / "committed-smolmachine"
output.parent.mkdir(parents=True, exist_ok=True)
pack_create_from_vm(bottle.name, output)
artifact = output.with_name(f"{output.name}.smolmachine")
return str(artifact)
def _export_hint(self, slug: str, image_ref: str) -> None:
info(f"to export for migration: cp {image_ref} {slug}.smolmachine")
bot_bottle/cli/commit.py
+8 -92
View File
@@ -11,49 +11,15 @@ snapshot instead of rebuilding from the Dockerfile.
from __future__ import annotations
import argparse
import sys
from pathlib import Path
from ..backend import enumerate_active_agents
from ..backend.docker.util import commit_container as docker_commit_container
from ..backend.macos_container.util import commit_container as macos_commit_container
from ..backend.macos_container.util import container_is_running as macos_container_is_running
from ..backend.macos_container.util import stop_container as macos_stop_container
from ..backend.smolmachines.smolvm import pack_create_from_vm
from ..bottle_state import bottle_state_dir
from ..bottle_state import mark_preserved, read_metadata, write_committed_image
from ..log import die, info
from ._common import PROG, read_tty_line
from ..backend.freeze import CommitCancelled, get_freezer
from ..bottle_state import read_metadata
from ..log import die
from ._common import PROG
from . import tui
_COMMITTED_IMAGE_PREFIX = "bot-bottle-committed-"
_DOCKER_BACKENDS = {"docker", ""}
_MACOS_CONTAINER_BACKEND = "macos-container"
_SMOLMACHINES_BACKEND = "smolmachines"
def _committed_image_tag(slug: str) -> str:
return f"{_COMMITTED_IMAGE_PREFIX}{slug}:latest"
def _agent_container_name(slug: str) -> str:
return f"bot-bottle-{slug}"
def _agent_machine_name(slug: str) -> str:
return f"bot-bottle-{slug}"
def _committed_smolmachine_output(slug: str) -> Path:
return bottle_state_dir(slug) / "committed-smolmachine"
def _committed_smolmachine_artifact(slug: str) -> Path:
output = _committed_smolmachine_output(slug)
return output.with_name(f"{output.name}.smolmachine")
def cmd_commit(argv: list[str]) -> int:
parser = argparse.ArgumentParser(prog=f"{PROG} commit", add_help=True)
parser.add_argument(
@@ -79,59 +45,9 @@ def cmd_commit(argv: list[str]) -> int:
metadata = read_metadata(slug)
backend = metadata.backend if metadata else ""
if backend in _DOCKER_BACKENDS:
container = _agent_container_name(slug)
image_tag = _committed_image_tag(slug)
docker_commit_container(container, image_tag)
write_committed_image(slug, image_tag)
mark_preserved(slug)
info(f"to resume from this snapshot: ./cli.py resume {slug}")
info(f"to export for migration: docker save {image_tag} -o {slug}.tar")
try:
get_freezer(backend).commit_slug(slug)
except CommitCancelled:
return 0
if backend == _MACOS_CONTAINER_BACKEND:
container = _agent_container_name(slug)
image_tag = _committed_image_tag(slug)
if macos_container_is_running(container):
sys.stderr.write(
f"bot-bottle: bottle {slug!r} is running; "
"commit will stop it. Continue? [y/N] "
)
sys.stderr.flush()
reply = read_tty_line().strip().lower()
if reply not in ("y", "yes"):
return 0
macos_stop_container(container)
macos_commit_container(container, image_tag)
write_committed_image(slug, image_tag)
mark_preserved(slug)
info(f"to resume from this snapshot: ./cli.py resume {slug}")
info(
f"to export for migration: "
f"container image save {image_tag} -o {slug}.tar"
)
return 0
if backend == _SMOLMACHINES_BACKEND:
machine = _agent_machine_name(slug)
output = _committed_smolmachine_output(slug)
output.parent.mkdir(parents=True, exist_ok=True)
pack_create_from_vm(machine, output)
artifact = _committed_smolmachine_artifact(slug)
write_committed_image(slug, str(artifact))
mark_preserved(slug)
info(f"to resume from this snapshot: ./cli.py resume {slug}")
info(f"to export for migration: cp {artifact} {slug}.smolmachine")
return 0
if backend:
die(
f"commit is only supported for docker, macos-container, and "
f"smolmachines; "
f"bottle {slug!r} uses {backend!r}"
)
die(f"commit cannot determine the backend for bottle {slug!r}")
return 1
return 0