agent-containers 0.1.0.dev0__py3-none-any.whl

agent_containers/lifecycle.py

@@ -0,0 +1,325 @@
+"""Failure-safe Docker application of a desired profile."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from agent_containers.build_context import prepare_build_contexts
+from agent_containers.docker import (
+    build_image_argv,
+    build_seed_argv,
+    default_home_volume,
+    default_image_tag,
+    legacy_home_volume,
+)
+from agent_containers.planner import PlanAction, build_plan
+from agent_containers.profile import MountType, Profile
+from agent_containers.shortcuts import render_decant_shortcut, render_shortcut, update_shortcuts
+from agent_containers.state import (
+    DeploymentRecord,
+    DeploymentState,
+    default_state_path,
+    default_state_path_for_name,
+    load_state,
+    new_deployment_id,
+    profile_digest,
+    profile_snapshot,
+    save_state,
+)
+
+_DOCTOR_HOME_PATHS = {
+    "claude-code": "/home/claude",
+    "opencode": "/home/opencode",
+    "codex": "/home/codex",
+    "hermes": "/opt/data",
+}
+_TOOL_SHADOW_SCRIPT = """set -eu
+list_tools() {
+    kind="$1"
+    directory="$2"
+    [ -d "$directory" ] || return 0
+    for path in "$directory"/*; do
+        [ -f "$path" ] || [ -L "$path" ] || continue
+        printf '%s\\t%s\\n' "$kind" "${path##*/}"
+    done
+}
+list_tools home "$HOME/.local/bin"
+list_tools home "$HOME/.npm-global/bin"
+list_tools managed /opt/agent-tools/bin
+list_tools managed /opt/agent-tools/npm/bin
+"""
+
+
+class LifecycleError(ValueError):
+    """Raised when a state file is not safe to apply for a profile."""
+
+
+@dataclass(frozen=True)
+class DoctorReport:
+    """Read-only host and selected-deployment diagnostics."""
+
+    lines: tuple[str, ...]
+    healthy: bool
+
+
+def build_user_ids() -> tuple[int, int]:
+    """Return safe image IDs while preserving Dockerfile collision rejection."""
+    # macOS's conventional staff GID (20) is already assigned in Debian-based
+    # images. Keep the documented groupmod rejection; Docker Desktop builds use
+    # the baked-in safe GID while retaining the host UID for bind-mount ownership.
+    return os.getuid(), 1000 if sys.platform == "darwin" else os.getgid()
+
+
+def apply_profile(
+    profile: Profile,
+    profile_path: Path,
+    state_path: Path | None = None,
+    shortcuts_path: Path | None = None,
+) -> DeploymentRecord:
+    """Build or verify a deployment, seed it safely, then atomically select it."""
+    target_state_path = state_path or default_state_path(profile)
+    state = load_state(target_state_path) if target_state_path.exists() else DeploymentState(profile_name=profile.name)
+    if state.profile_name != profile.name:
+        raise LifecycleError(f"state belongs to profile {state.profile_name!r}, not {profile.name!r}")
+    plan = build_plan(profile, state, profile_path)
+    selected = state.selected_deployment
+    image = selected.image if selected is not None else default_image_tag(profile)
+    if PlanAction.CREATE_IMAGE in plan.actions or PlanAction.UPDATE_IMAGE in plan.actions:
+        image = _build_image(profile, profile_path)
+    else:
+        _docker("docker", "image", "inspect", image)
+    if not plan.is_noop:
+        record = _new_record(profile, image, profile_path)
+        if shortcuts_path is not None:
+            # Validate the complete launch before seeds or state can make this
+            # deployment visible. The later atomic write still refreshes the
+            # generated file after state selection succeeds.
+            render_shortcut(profile, record, profile_path)
+            decant_sources = _resolve_decant_sources(profile, record, target_state_path)
+            if profile.decant.enabled:
+                render_decant_shortcut(profile, decant_sources)
+        else:
+            decant_sources = None
+        _apply_seeds(profile, profile_path, image)
+        state.deployments = [item.model_copy(update={"selected": False}) for item in state.deployments]
+        state.deployments.append(record)
+        save_state(target_state_path, state)
+        if shortcuts_path is not None:
+            update_shortcuts(shortcuts_path, profile, record, profile_path, decant_sources)
+        return record
+    assert selected is not None
+    if shortcuts_path is not None:
+        decant_sources = _resolve_decant_sources(profile, selected, target_state_path)
+        if profile.decant.enabled:
+            render_decant_shortcut(profile, decant_sources)
+        update_shortcuts(shortcuts_path, profile, selected, profile_path, decant_sources)
+    return selected
+
+
+def rollback_profile(
+    profile: Profile,
+    state_path: Path | None = None,
+    shortcuts_path: Path | None = None,
+    profile_path: Path | None = None,
+) -> DeploymentRecord:
+    """Select the immediately preceding retained image after verifying it exists."""
+    target_state_path = state_path or default_state_path(profile)
+    state = load_state(target_state_path)
+    if state.profile_name != profile.name:
+        raise LifecycleError(f"state belongs to profile {state.profile_name!r}, not {profile.name!r}")
+    selected_index = next((index for index, item in enumerate(state.deployments) if item.selected), None)
+    if selected_index is None:
+        raise LifecycleError("rollback requires a selected deployment")
+    if selected_index == 0:
+        raise LifecycleError("no prior deployment is retained for rollback")
+    target = state.deployments[selected_index - 1]
+    _docker("docker", "image", "inspect", target.image)
+    restored_profile = Profile.model_validate(target.profile_snapshot)
+    shortcut_profile_path = profile_path or Path.cwd() / "profile.toml"
+    if shortcuts_path is not None:
+        # A historical profile may reference an input that no longer exists;
+        # refuse before changing state so rollback cannot strand the shortcut.
+        render_shortcut(restored_profile, target, shortcut_profile_path)
+        decant_sources = _resolve_decant_sources(restored_profile, target, target_state_path)
+        if restored_profile.decant.enabled:
+            render_decant_shortcut(restored_profile, decant_sources)
+    else:
+        decant_sources = None
+    state.deployments = [
+        item.model_copy(update={"selected": item.deployment_id == target.deployment_id}) for item in state.deployments
+    ]
+    save_state(target_state_path, state)
+    if shortcuts_path is not None:
+        update_shortcuts(shortcuts_path, restored_profile, target, shortcut_profile_path, decant_sources)
+    return state.selected_deployment or target
+
+
+def rollback_preview(record: DeploymentRecord) -> list[str]:
+    """Render the managed launch choices restored by a rollback without secrets."""
+    snapshot = record.profile_snapshot
+    egress = snapshot.get("egress", {})
+    proxy = snapshot.get("proxy")
+    provider = snapshot.get("provider")
+    return [
+        f"Rollback target: {record.deployment_id} ({record.image})",
+        f"Restored egress mode: {egress.get('mode', 'unknown')}",
+        f"Restored egress hosts: {', '.join(egress.get('hosts', [])) or '(none)'}",
+        f"Restored proxy/CA: {'configured' if proxy else 'none'}",
+        f"Restored provider endpoint: {'configured' if provider and provider.get('endpoint') else 'none'}",
+        "Warning: persistent home-volume data is not rolled back.",
+        "Warning: existing agent sessions are not stopped.",
+    ]
+
+
+def doctor_profile(profile: Profile, state_path: Path | None = None) -> DoctorReport:
+    """Inspect local Docker/state prerequisites without building or mutating resources."""
+    lines: list[str] = []
+    docker_available = _probe("docker", "version", "--format", "{{.Server.Version}}")
+    lines.append(f"Docker daemon: {'available' if docker_available else 'unavailable'}")
+    target_state_path = state_path or default_state_path(profile)
+    if not target_state_path.exists():
+        lines.append(f"Deployment state: absent ({target_state_path})")
+        return DoctorReport(tuple(lines), healthy=False)
+    state = load_state(target_state_path)
+    if state.profile_name != profile.name:
+        raise LifecycleError(f"state belongs to profile {state.profile_name!r}, not {profile.name!r}")
+    selected = state.selected_deployment
+    if selected is None:
+        lines.append("Selected deployment: absent")
+        return DoctorReport(tuple(lines), healthy=False)
+    image_available = docker_available and _probe("docker", "image", "inspect", selected.image)
+    home_volume = selected.home_volume or legacy_home_volume(profile)
+    volume_available = docker_available and _probe("docker", "volume", "inspect", home_volume)
+    lines.append(f"Selected deployment: {selected.deployment_id} ({selected.image})")
+    lines.append(f"Selected image: {'available' if image_available else 'unavailable'}")
+    lines.append(f"Home volume: {home_volume} ({'present' if volume_available else 'not created yet'})")
+    if not volume_available:
+        lines.append("Tool shadowing: skipped (home volume is not available)")
+    else:
+        shadows = _inspect_tool_shadows(selected.image, home_volume, profile.agent.value)
+        if shadows is None:
+            lines.append("Tool shadowing: unavailable (could not inspect the home volume)")
+        elif shadows:
+            lines.append(f"Tool shadowing: {', '.join(shadows)}")
+        else:
+            lines.append("Tool shadowing: none detected")
+    return DoctorReport(tuple(lines), healthy=docker_available and image_available)
+
+
+def _inspect_tool_shadows(image: str, home_volume: str, agent: str) -> tuple[str, ...] | None:
+    """Compare writable home tool names with image-managed tool names."""
+    home_path = _DOCTOR_HOME_PATHS.get(agent)
+    if home_path is None:
+        return None
+    try:
+        result = subprocess.run(
+            [
+                "docker",
+                "run",
+                "--rm",
+                "--network=none",
+                "--read-only",
+                "--cap-drop=ALL",
+                "--mount",
+                f"type=volume,src={home_volume},dst={home_path},readonly",
+                "--entrypoint",
+                "/bin/sh",
+                image,
+                "-ceu",
+                _TOOL_SHADOW_SCRIPT,
+            ],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except OSError:
+        return None
+    if result.returncode != 0:
+        return None
+    home_tools: set[str] = set()
+    managed_tools: set[str] = set()
+    for line in result.stdout.splitlines():
+        kind, separator, name = line.partition("\t")
+        if not separator or not name:
+            continue
+        if kind == "home":
+            home_tools.add(name)
+        elif kind == "managed":
+            managed_tools.add(name)
+    return tuple(sorted(home_tools & managed_tools))
+
+
+def _build_image(profile: Profile, profile_path: Path) -> str:
+    """Build a profile context in an automatically removed private directory."""
+    image = default_image_tag(profile, profile_path)
+    with tempfile.TemporaryDirectory(prefix="agent-containers-") as temporary:
+        contexts = prepare_build_contexts(profile, Path(temporary) / "context", profile_path)
+        uid, gid = build_user_ids()
+        _docker(*build_image_argv(profile, contexts, image=image, uid=uid, gid=gid))
+    return image
+
+
+def _resolve_decant_sources(
+    profile: Profile,
+    current_record: DeploymentRecord,
+    current_state_path: Path,
+) -> dict[str, DeploymentRecord]:
+    """Load selected source deployments needed by an opted-in Decant shortcut."""
+    if not profile.decant.enabled:
+        return {}
+    sources: dict[str, DeploymentRecord] = {}
+    for source_name in profile.decant.source_profiles:
+        source_path = current_state_path if source_name == profile.name else default_state_path_for_name(source_name)
+        if source_name == profile.name:
+            source_record = current_record
+        elif not source_path.exists():
+            raise LifecycleError(f"Decant source profile state is unavailable: {source_name}")
+        else:
+            source_state = load_state(source_path)
+            if source_state.profile_name != source_name:
+                raise LifecycleError(
+                    f"Decant source state belongs to profile {source_state.profile_name!r}, not {source_name!r}"
+                )
+            source_record = source_state.selected_deployment
+            if source_record is None:
+                raise LifecycleError(f"Decant source profile has no selected deployment: {source_name}")
+        sources[source_name] = source_record
+    return sources
+
+
+def _apply_seeds(profile: Profile, profile_path: Path, image: str) -> None:
+    """Copy new seed inputs only after the image is available for its adapter."""
+    for mount in profile.mounts:
+        if mount.type == MountType.SEED:
+            _docker(*build_seed_argv(profile, mount.target, profile_path, image=image, home_volume=profile.home_volume))
+
+
+def _new_record(profile: Profile, image: str, profile_path: Path | None = None) -> DeploymentRecord:
+    """Create an unambiguous selected deployment record after successful work."""
+    digest = profile_digest(profile, profile_path)
+    return DeploymentRecord(
+        deployment_id=new_deployment_id(profile, profile_path),
+        image=image,
+        home_volume=profile.home_volume or default_home_volume(profile),
+        profile_digest=digest,
+        profile_snapshot=profile_snapshot(profile),
+        launch_digest=digest,
+        created_at=datetime.now(UTC),
+        selected=True,
+    )
+
+
+def _docker(*argv: str) -> None:
+    """Run Docker without shell interpolation or captured credential-bearing output."""
+    subprocess.run(argv, check=True)
+
+
+def _probe(*argv: str) -> bool:
+    """Return whether a harmless Docker inspection succeeds without raising."""
+    return subprocess.run(argv, check=False, capture_output=True, text=True).returncode == 0

agent_containers/planner.py

@@ -0,0 +1,99 @@
+"""Offline change planning for desired profiles and recorded deployments."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from agent_containers.profile import Profile
+from agent_containers.state import DeploymentState, profile_digest, profile_snapshot
+
+
+class PlanAction(StrEnum):
+    """Changes the apply operation may need to perform."""
+
+    CREATE_IMAGE = "create-image"
+    UPDATE_IMAGE = "update-image"
+    UPDATE_LAUNCH = "update-launch"
+    NOOP = "no-op"
+
+
+class Plan(BaseModel):
+    """A deterministic, explicitly offline description of desired changes."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    profile_name: str
+    profile_digest: str = Field(min_length=64, max_length=64)
+    actions: list[PlanAction]
+    changed_sections: list[str] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    live_state_checked: bool = False
+
+    @property
+    def is_noop(self) -> bool:
+        """Whether the recorded deployment already matches the profile."""
+        return self.actions == [PlanAction.NOOP]
+
+    def summary_lines(self) -> list[str]:
+        """Render stable, human-readable plan output."""
+        lines = [
+            f"Profile: {self.profile_name}",
+            f"Live Docker state checked: {'yes' if self.live_state_checked else 'no'}",
+        ]
+        if self.actions:
+            lines.append("Actions:")
+            lines.extend(f"- {action.value}" for action in self.actions)
+        if self.changed_sections:
+            lines.append("Changed sections:")
+            lines.extend(f"- {section}" for section in self.changed_sections)
+        if self.warnings:
+            lines.append("Warnings:")
+            lines.extend(f"- {warning}" for warning in self.warnings)
+        return lines
+
+
+def build_plan(profile: Profile, state: DeploymentState | None = None, profile_path: Path | None = None) -> Plan:
+    """Compare a profile with recorded state without contacting Docker."""
+    snapshot = profile_snapshot(profile)
+    digest = profile_digest(profile, profile_path)
+    warnings = ["Live Docker state was not inspected."]
+    if state is None or state.selected_deployment is None:
+        return Plan(
+            profile_name=profile.name,
+            profile_digest=digest,
+            actions=[PlanAction.CREATE_IMAGE],
+            changed_sections=["initial deployment"],
+            warnings=warnings + ["No selected deployment is recorded."],
+        )
+
+    selected = state.selected_deployment
+    previous = selected.profile_snapshot
+    image_sections = ["agent", "packages"]
+    launch_sections = ["home_volume", "provider", "proxy", "egress", "decant", "mounts"]
+    changed_image = [section for section in image_sections if snapshot.get(section) != previous.get(section)]
+    changed_launch = [section for section in launch_sections if snapshot.get(section) != previous.get(section)]
+    langfuse_changed = snapshot.get("langfuse") != previous.get("langfuse")
+    if langfuse_changed:
+        changed_image.append("langfuse")
+    changed = changed_image + changed_launch
+    if digest != selected.profile_digest and not changed:
+        changed_image.append("proxy CA contents")
+        changed.append("proxy CA contents")
+    if not changed:
+        actions = [PlanAction.NOOP]
+    else:
+        actions = []
+        if changed_image:
+            actions.append(PlanAction.UPDATE_IMAGE)
+        if changed_launch or langfuse_changed:
+            actions.append(PlanAction.UPDATE_LAUNCH)
+    return Plan(
+        profile_name=profile.name,
+        profile_digest=digest,
+        actions=actions,
+        changed_sections=changed,
+        warnings=warnings,
+    )