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

agent_containers/profile.py

@@ -0,0 +1,377 @@
+"""Versioned TOML profile model and validation helpers."""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import tomllib
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated, Self
+
+from pydantic import AnyHttpUrl, BaseModel, ConfigDict, Field, field_validator, model_validator
+
+_SCHEMA_VERSION = 1
+_NAME_PATTERN = re.compile(r"^[a-z][a-z0-9_-]{0,62}$")
+_ENV_PATTERN = re.compile(r"^[A-Z_][A-Z0-9_]*$")
+_VOLUME_NAME_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,254}$")
+
+
+class AgentName(StrEnum):
+    """Supported workload image adapters."""
+
+    CLAUDE_CODE = "claude-code"
+    OPENCODE = "opencode"
+    CODEX = "codex"
+    HERMES = "hermes"
+
+
+class MountType(StrEnum):
+    """Ways a profile can provide host content to a workload."""
+
+    BIND = "bind"
+    DIRECTORY = "directory"
+    SEED = "seed"
+
+
+class PackageSet(BaseModel):
+    """Optional build-time packages separated by installation ecosystem."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    apt: list[str] = Field(default_factory=list)
+    npm: list[str] = Field(default_factory=list)
+    uv_tools: list[str] = Field(default_factory=list)
+    uv_libraries: list[str] = Field(default_factory=list)
+
+    @field_validator("apt", "npm", "uv_tools", "uv_libraries")
+    @classmethod
+    def package_names_are_nonempty(cls, values: list[str]) -> list[str]:
+        """Reject blank or multiline package-list entries while preserving order."""
+        cleaned = [value.strip() for value in values]
+        if any(not value for value in cleaned):
+            raise ValueError("package names must not be blank")
+        if any("\n" in value or "\r" in value or "\x00" in value for value in cleaned):
+            raise ValueError("package names must be single-line text")
+        return cleaned
+
+
+class ProviderConfig(BaseModel):
+    """Provider connection details needed to construct a launch."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    kind: str = Field(min_length=1)
+    endpoint: AnyHttpUrl | None = None
+    model: str | None = Field(default=None, min_length=1)
+    api_key_env: str | None = None
+
+    @field_validator("kind")
+    @classmethod
+    def kind_is_normalized(cls, value: str) -> str:
+        """Keep provider identifiers stable in deployment records."""
+        return value.strip().lower()
+
+    @field_validator("api_key_env")
+    @classmethod
+    def environment_name_is_safe(cls, value: str | None) -> str | None:
+        """Allow secret references but never literal secret values."""
+        if value is not None and not _ENV_PATTERN.fullmatch(value):
+            raise ValueError("api_key_env must be an uppercase environment variable name")
+        return value
+
+
+class ProxyConfig(BaseModel):
+    """HTTP(S) proxy, bypass and runtime trust inputs."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    http: AnyHttpUrl | None = None
+    https: AnyHttpUrl | None = None
+    no_proxy: list[str] = Field(default_factory=list)
+    ca_file: str | None = Field(default=None, min_length=1)
+    ca_dir: str | None = Field(default=None, min_length=1)
+
+    @field_validator("no_proxy")
+    @classmethod
+    def no_proxy_entries_are_nonempty(cls, values: list[str]) -> list[str]:
+        """Reject accidental blank proxy bypass entries."""
+        cleaned = [value.strip() for value in values]
+        if any(not value for value in cleaned):
+            raise ValueError("no_proxy entries must not be blank")
+        return cleaned
+
+    @model_validator(mode="after")
+    def ca_inputs_are_exclusive(self) -> Self:
+        """Require one CA input shape at most: a file or a certificate directory."""
+        if self.ca_file is not None and self.ca_dir is not None:
+            raise ValueError("proxy ca_file and ca_dir are mutually exclusive")
+        return self
+
+
+class EgressConfig(BaseModel):
+    """Runtime egress policy and optional external gateway contract."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    mode: str = "allowlist"
+    hosts: list[str] = Field(default_factory=list)
+    gateway_host: str | None = Field(default=None, min_length=1)
+    gateway_port: Annotated[int | None, Field(default=None, ge=1, le=65535)] = None
+    gateway_user: str | None = Field(default=None, min_length=1)
+    gateway_access_hostname: str | None = Field(default=None, min_length=1)
+    gateway_bootstrap_allow: list[str] = Field(default_factory=list)
+    gateway_key_file: str | None = Field(default=None, min_length=1)
+    gateway_known_hosts_file: str | None = Field(default=None, min_length=1)
+
+    @field_validator("mode")
+    @classmethod
+    def mode_is_supported(cls, value: str) -> str:
+        """Accept only policy modes understood by the planner."""
+        normalized = value.strip().lower()
+        if normalized not in {"deny", "allowlist", "unrestricted"}:
+            raise ValueError("network mode must be deny, allowlist, or unrestricted")
+        return normalized
+
+    @field_validator("hosts")
+    @classmethod
+    def hosts_are_nonempty(cls, values: list[str]) -> list[str]:
+        """Reject accidental blank allowlist entries."""
+        cleaned = [value.strip() for value in values]
+        if any(not value for value in cleaned):
+            raise ValueError("egress hosts must not be blank")
+        return cleaned
+
+    @field_validator("gateway_bootstrap_allow")
+    @classmethod
+    def gateway_bootstrap_entries_are_nonempty(cls, values: list[str]) -> list[str]:
+        """Reject accidental blank gateway bootstrap entries."""
+        cleaned = [value.strip() for value in values]
+        if any(not value for value in cleaned):
+            raise ValueError("gateway bootstrap entries must not be blank")
+        for value in cleaned:
+            try:
+                ipaddress.ip_network(value, strict=False)
+            except ValueError as exc:
+                raise ValueError("gateway bootstrap entries must be IP addresses or CIDRs") from exc
+        return cleaned
+
+    @model_validator(mode="after")
+    def gateway_requires_port(self) -> Self:
+        """Require a complete gateway address when either part is supplied."""
+        if (self.gateway_host is None) != (self.gateway_port is None):
+            raise ValueError("gateway_host and gateway_port must be supplied together")
+        options = (
+            self.gateway_user,
+            self.gateway_access_hostname,
+            self.gateway_key_file,
+            self.gateway_known_hosts_file,
+        )
+        if self.gateway_host is None and (
+            any(option is not None for option in options) or self.gateway_bootstrap_allow
+        ):
+            raise ValueError("gateway options require gateway_host")
+        if (self.gateway_key_file is None) != (self.gateway_known_hosts_file is None):
+            raise ValueError("gateway_key_file and gateway_known_hosts_file must be supplied together")
+        return self
+
+
+class DecantConfig(BaseModel):
+    """Optional Decant session aggregation inputs."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = False
+    source_profiles: list[str] = Field(default_factory=list)
+    image: str | None = Field(default=None, min_length=1)
+    data_volume: str | None = Field(default=None, min_length=1)
+    bind_address: str = "127.0.0.1"
+    port: Annotated[int, Field(default=8787, ge=1, le=65535)] = 8787
+
+    @field_validator("source_profiles")
+    @classmethod
+    def source_names_are_nonempty(cls, values: list[str]) -> list[str]:
+        """Reject blank profile references."""
+        cleaned = [value.strip() for value in values]
+        if any(not value for value in cleaned):
+            raise ValueError("Decant source profile names must not be blank")
+        if any(not _NAME_PATTERN.fullmatch(value) for value in cleaned):
+            raise ValueError("Decant source profile names must be valid profile names")
+        return cleaned
+
+    @field_validator("image")
+    @classmethod
+    def image_is_single_line(cls, value: str | None) -> str | None:
+        """Keep the derived Decant image reference safe for argv rendering."""
+        if value is None:
+            return None
+        cleaned = value.strip()
+        if not cleaned or any(character.isspace() or ord(character) < 32 for character in cleaned):
+            raise ValueError("Decant image must be a single-line image reference")
+        return cleaned
+
+    @field_validator("data_volume")
+    @classmethod
+    def data_volume_is_safe(cls, value: str | None) -> str | None:
+        """Allow an optional reusable Docker named volume for Decant state."""
+        if value is None:
+            return None
+        cleaned = value.strip()
+        if not _VOLUME_NAME_PATTERN.fullmatch(cleaned):
+            raise ValueError("Decant data_volume must be a Docker named-volume name")
+        return cleaned
+
+    @field_validator("bind_address")
+    @classmethod
+    def bind_address_is_single_line(cls, value: str) -> str:
+        """Reject shell-like bind-address values before Docker sees them."""
+        cleaned = value.strip()
+        if not cleaned or any(character.isspace() or ord(character) < 32 for character in cleaned):
+            raise ValueError("Decant bind_address must be a single-line host address")
+        return cleaned
+
+    @model_validator(mode="after")
+    def enabled_requires_sources(self) -> Self:
+        """Require explicit source profiles when Decant is opted in."""
+        if self.enabled and not self.source_profiles:
+            raise ValueError("Decant support requires source_profiles when enabled")
+        return self
+
+
+class LangfuseConfig(BaseModel):
+    """Experimental, opt-in Langfuse observability settings."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = False
+    base_url: AnyHttpUrl | None = None
+    public_key_env: str = "LANGFUSE_PUBLIC_KEY"
+    secret_key_env: str = "LANGFUSE_SECRET_KEY"
+    environment: str | None = Field(default=None, min_length=1)
+    user_id: str | None = Field(default=None, min_length=1)
+
+    @field_validator("public_key_env", "secret_key_env")
+    @classmethod
+    def credential_environment_name_is_safe(cls, value: str) -> str:
+        """Allow only environment-variable references, never credential values."""
+        if not _ENV_PATTERN.fullmatch(value):
+            raise ValueError("Langfuse credential fields must be uppercase environment variable names")
+        return value
+
+    @model_validator(mode="after")
+    def enabled_requires_endpoint(self) -> Self:
+        """Require an explicit endpoint when the experimental integration is enabled."""
+        if self.enabled and self.base_url is None:
+            raise ValueError("Langfuse base_url is required when Langfuse is enabled")
+        if self.public_key_env == self.secret_key_env:
+            raise ValueError("Langfuse public_key_env and secret_key_env must differ")
+        return self
+
+
+class MountConfig(BaseModel):
+    """A custom file/directory input or copy-once seed."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: MountType = MountType.BIND
+    source: str = Field(min_length=1)
+    target: str = Field(min_length=1)
+    read_only: bool = True
+
+    @field_validator("source", "target")
+    @classmethod
+    def paths_are_trimmed(cls, value: str) -> str:
+        """Reject whitespace-only paths."""
+        cleaned = value.strip()
+        if not cleaned:
+            raise ValueError("mount paths must not be blank")
+        return cleaned
+
+    @field_validator("target")
+    @classmethod
+    def target_is_absolute(cls, value: str) -> str:
+        """Container targets must be absolute."""
+        if not value.startswith("/") or value == "/":
+            raise ValueError("mount target must be an absolute path other than /")
+        return value
+
+
+class Profile(BaseModel):
+    """Complete desired configuration for one named agent deployment."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: Annotated[int, Field(default=_SCHEMA_VERSION, ge=1)]
+    name: str
+    agent: AgentName
+    home_volume: str | None = Field(default=None, min_length=1)
+    packages: PackageSet = Field(default_factory=PackageSet)
+    provider: ProviderConfig | None = None
+    proxy: ProxyConfig | None = None
+    egress: EgressConfig = Field(default_factory=EgressConfig)
+    decant: DecantConfig = Field(default_factory=DecantConfig)
+    langfuse: LangfuseConfig = Field(default_factory=LangfuseConfig)
+    mounts: list[MountConfig] = Field(default_factory=list)
+
+    @field_validator("schema_version")
+    @classmethod
+    def schema_version_is_current(cls, value: int) -> int:
+        """Reject profiles newer than this CLI can interpret."""
+        if value != _SCHEMA_VERSION:
+            raise ValueError(f"unsupported profile schema_version {value}; expected {_SCHEMA_VERSION}")
+        return value
+
+    @field_validator("name")
+    @classmethod
+    def name_is_safe(cls, value: str) -> str:
+        """Constrain names used in Docker resource identifiers."""
+        cleaned = value.strip()
+        if not _NAME_PATTERN.fullmatch(cleaned):
+            raise ValueError("name must start with a lowercase letter and contain only a-z, 0-9, _ or -")
+        return cleaned
+
+    @field_validator("home_volume")
+    @classmethod
+    def home_volume_is_safe(cls, value: str | None) -> str | None:
+        """Allow explicit Docker volume names without shell/path syntax."""
+        if value is None:
+            return None
+        cleaned = value.strip()
+        if not _VOLUME_NAME_PATTERN.fullmatch(cleaned):
+            raise ValueError("home_volume must be a Docker named-volume name")
+        return cleaned
+
+    @model_validator(mode="after")
+    def mounts_do_not_conflict(self) -> Self:
+        """Reject duplicate or nested targets Docker would resolve ambiguously."""
+        targets = sorted(mount.target.rstrip("/") for mount in self.mounts)
+        for index, target in enumerate(targets):
+            if index and (target == targets[index - 1] or target.startswith(f"{targets[index - 1]}/")):
+                raise ValueError(f"mount targets overlap: {targets[index - 1]} and {target}")
+        return self
+
+    @model_validator(mode="after")
+    def experimental_integrations_are_supported(self) -> Self:
+        """Reject integrations for agent adapters that cannot consume them."""
+        if self.decant.enabled and self.agent not in {AgentName.CLAUDE_CODE, AgentName.CODEX}:
+            raise ValueError("experimental Decant support is limited to Claude Code and Codex")
+        if self.langfuse.enabled and self.agent not in {
+            AgentName.CLAUDE_CODE,
+            AgentName.CODEX,
+            AgentName.OPENCODE,
+        }:
+            raise ValueError("experimental Langfuse support is limited to Claude Code, Codex, and OpenCode")
+        return self
+
+
+def load_profile(path: Path) -> Profile:
+    """Load and validate a TOML profile from disk."""
+    with path.open("rb") as profile_file:
+        return Profile.model_validate(tomllib.load(profile_file))
+
+
+def resolve_mount_source(profile: Profile, mount: MountConfig, profile_path: Path) -> Path:
+    """Resolve a relative mount source against the profile file directory."""
+    del profile
+    source = Path(mount.source).expanduser()
+    return source if source.is_absolute() else (profile_path.parent / source).resolve()

agent_containers/shortcuts.py

@@ -0,0 +1,159 @@
+"""Generate namespaced shell shortcuts for selected profile deployments."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import tempfile
+from collections.abc import Mapping
+from pathlib import Path
+
+from agent_containers.docker import (
+    DockerCommandError,
+    build_decant_run_argv,
+    build_run_argv,
+    legacy_home_volume,
+)
+from agent_containers.profile import AgentName, Profile
+from agent_containers.state import DeploymentRecord
+
+_WORKSPACE_MOUNT = object()
+_WORKSPACE_TARGET = object()
+
+
+class ShortcutError(ValueError):
+    """Raised when a profile cannot be rendered as a safe shell shortcut."""
+
+
+def default_shortcuts_path() -> Path:
+    """Return the CLI-managed profile shortcut path under the XDG config home."""
+    config_home = os.environ.get("XDG_CONFIG_HOME")
+    root = Path(config_home).expanduser() if config_home else Path.home() / ".config"
+    return (root / "agent-containers" / "profiles.sh").resolve()
+
+
+def shortcut_function_name(profile: Profile) -> str:
+    """Return the reserved, namespaced shell function name for a profile."""
+    return f"agent_containers_{profile.name.replace('-', '_')}"
+
+
+def decant_shortcut_function_name(profile: Profile) -> str:
+    """Return the reserved function name for an experimental Decant launch."""
+    return f"agent_containers_decant_{profile.name.replace('-', '_')}"
+
+
+def render_shortcut(profile: Profile, record: DeploymentRecord, profile_path: Path) -> str:
+    """Render one profile function without embedding secrets or shell interpolation."""
+    workspace = profile_path.expanduser().resolve().parent
+    try:
+        argv = build_run_argv(
+            profile,
+            workspace,
+            profile_path,
+            image=record.image,
+            home_volume=record.home_volume or legacy_home_volume(profile),
+        )
+    except DockerCommandError as exc:
+        raise ShortcutError(str(exc)) from exc
+    workspace_mount = f"{workspace}:/workspace/{workspace.name}"
+    tokens: list[str | object] = [
+        _WORKSPACE_MOUNT
+        if token == workspace_mount
+        else _WORKSPACE_TARGET
+        if token == f"/workspace/{workspace.name}"
+        else token
+        for token in argv
+    ]
+    rendered = " \\\n    ".join(_render_token(token) for token in tokens)
+    name = shortcut_function_name(profile)
+    return f'# BEGIN agent-containers profile {profile.name}\n{name}() {{\n  {rendered} "$@"\n}}\n# END agent-containers profile {profile.name}\n'
+
+
+def render_decant_shortcut(profile: Profile, source_records: Mapping[str, DeploymentRecord]) -> str:
+    """Render a direct-mount Decant function from selected agent deployments."""
+    volumes: dict[AgentName, str] = {}
+    for source_name in profile.decant.source_profiles:
+        record = source_records.get(source_name)
+        if record is None:
+            raise ShortcutError(f"Decant source profile state is unavailable: {source_name}")
+        try:
+            source_profile = Profile.model_validate(record.profile_snapshot)
+        except ValueError as exc:
+            raise ShortcutError(f"Decant source profile state is invalid: {source_name}") from exc
+        if source_profile.agent not in {AgentName.CLAUDE_CODE, AgentName.CODEX}:
+            raise ShortcutError(f"Decant source profile must use Claude Code or Codex: {source_name}")
+        if source_profile.agent in volumes:
+            raise ShortcutError(f"Decant has multiple {source_profile.agent.value} source profiles")
+        volumes[source_profile.agent] = record.home_volume or legacy_home_volume(source_profile)
+    try:
+        argv = build_decant_run_argv(
+            profile,
+            claude_volume=volumes.get(AgentName.CLAUDE_CODE),
+            codex_volume=volumes.get(AgentName.CODEX),
+        )
+    except DockerCommandError as exc:
+        raise ShortcutError(str(exc)) from exc
+    rendered = " \\\n    ".join(shlex.quote(token) for token in argv)
+    name = decant_shortcut_function_name(profile)
+    return (
+        f"# BEGIN agent-containers decant {profile.name}\n"
+        f"{name}() {{\n"
+        f'  {rendered} "$@"\n'
+        f"}}\n"
+        f"# END agent-containers decant {profile.name}\n"
+    )
+
+
+def update_shortcuts(
+    path: Path,
+    profile: Profile,
+    record: DeploymentRecord,
+    profile_path: Path,
+    decant_sources: Mapping[str, DeploymentRecord] | None = None,
+) -> None:
+    """Atomically replace one generated profile block in the managed shortcuts file."""
+    path = path.expanduser().resolve()
+    existing = path.read_text(encoding="utf-8") if path.exists() else ""
+    block = render_shortcut(profile, record, profile_path)
+    content = _replace_block(existing, f"profile {profile.name}", block)
+    decant_begin = f"decant {profile.name}"
+    if profile.decant.enabled:
+        if decant_sources is None:
+            raise ShortcutError("Decant source deployments are required when Decant is enabled")
+        content = _replace_block(content, decant_begin, render_decant_shortcut(profile, decant_sources))
+    else:
+        content = _replace_block(content, decant_begin, "")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent, text=True)
+    temporary_path = Path(temporary)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as shortcuts_file:
+            shortcuts_file.write(content)
+            shortcuts_file.flush()
+            os.fsync(shortcuts_file.fileno())
+        temporary_path.chmod(0o600)
+        temporary_path.replace(path)
+    finally:
+        temporary_path.unlink(missing_ok=True)
+
+
+def _replace_block(existing: str, key: str, block: str) -> str:
+    """Replace or remove one generated block while preserving user shell text."""
+    begin = f"# BEGIN agent-containers {key}\n"
+    end = f"# END agent-containers {key}\n"
+    if begin in existing:
+        start = existing.index(begin)
+        finish = existing.index(end, start) + len(end)
+        replacement = block
+        return existing[:start] + replacement + existing[finish:]
+    if not block:
+        return existing
+    return existing.rstrip() + ("\n\n" if existing.strip() else "") + block
+
+
+def _render_token(token: str | object) -> str:
+    if token is _WORKSPACE_MOUNT:
+        return '"$PWD:/workspace/$(basename "$PWD")"'
+    if token is _WORKSPACE_TARGET:
+        return '"/workspace/$(basename "$PWD")"'
+    return shlex.quote(str(token))

agent_containers/state.py

@@ -0,0 +1,154 @@
+"""Machine-managed deployment state stored separately from user TOML."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Self
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from agent_containers.profile import Profile
+
+
+class DeploymentRecord(BaseModel):
+    """One retained image and managed launch configuration."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    deployment_id: str = Field(min_length=1)
+    image: str = Field(min_length=1)
+    home_volume: str | None = None
+    profile_digest: str = Field(min_length=64, max_length=64)
+    profile_snapshot: dict[str, Any]
+    launch_digest: str = Field(min_length=64, max_length=64)
+    created_at: datetime
+    selected: bool = False
+
+    @field_validator("created_at")
+    @classmethod
+    def timestamp_is_aware(cls, value: datetime) -> datetime:
+        """Keep state timestamps unambiguous across hosts."""
+        if value.tzinfo is None:
+            raise ValueError("created_at must include a timezone")
+        return value
+
+
+class DeploymentState(BaseModel):
+    """Current and retained deployment records for one profile."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: int = 1
+    profile_name: str = Field(min_length=1)
+    deployments: list[DeploymentRecord] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def has_at_most_one_selected(self) -> Self:
+        """Prevent ambiguous active deployment selection."""
+        if sum(record.selected for record in self.deployments) > 1:
+            raise ValueError("deployment state may select at most one deployment")
+        return self
+
+    @property
+    def selected_deployment(self) -> DeploymentRecord | None:
+        """Return the active record, if one has been applied."""
+        return next((record for record in self.deployments if record.selected), None)
+
+
+def profile_snapshot(profile: Profile) -> dict[str, Any]:
+    """Produce a JSON-compatible desired profile snapshot."""
+    snapshot = profile.model_dump(mode="json")
+    # Keep snapshots made before the optional explicit volume field compatible
+    # with the default profile representation. An omitted value means the
+    # same user-scoped default, so it must not force a spurious image rebuild.
+    if profile.home_volume is None:
+        snapshot.pop("home_volume", None)
+    decant = snapshot.get("decant")
+    if isinstance(decant, dict):
+        if decant.get("image") is None:
+            decant.pop("image", None)
+        if decant.get("data_volume") is None:
+            decant.pop("data_volume", None)
+    return snapshot
+
+
+def digest_snapshot(snapshot: dict[str, Any]) -> str:
+    """Hash a canonical snapshot for change detection."""
+    encoded = json.dumps(snapshot, sort_keys=True, separators=(",", ":")).encode()
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def profile_digest(profile: Profile, profile_path: Path | None = None) -> str:
+    """Return the canonical digest, including deployment CA input contents."""
+    snapshot = profile_snapshot(profile)
+    if profile_path is not None and profile.proxy is not None:
+        snapshot["_proxy_ca_digest"] = _proxy_ca_digest(profile, profile_path)
+    return digest_snapshot(snapshot)
+
+
+def load_state(path: Path) -> DeploymentState:
+    """Load machine-managed deployment state from JSON."""
+    with path.open(encoding="utf-8") as state_file:
+        return DeploymentState.model_validate_json(state_file.read())
+
+
+def default_state_path(profile: Profile) -> Path:
+    """Return the XDG-style per-user state path for one named profile."""
+    return default_state_path_for_name(profile.name)
+
+
+def default_state_path_for_name(name: str) -> Path:
+    """Return the XDG-style state path for a validated profile name."""
+    state_home = os.environ.get("XDG_STATE_HOME")
+    root = Path(state_home).expanduser() if state_home else Path.home() / ".local" / "state"
+    return (root / "agent-containers" / f"{name}.json").resolve()
+
+
+def save_state(path: Path, state: DeploymentState) -> None:
+    """Atomically write formatted JSON, creating its parent directory."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent, text=True)
+    temporary_path = Path(temporary)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as state_file:
+            state_file.write(state.model_dump_json(indent=2) + "\n")
+            state_file.flush()
+            os.fsync(state_file.fileno())
+        temporary_path.replace(path)
+    finally:
+        temporary_path.unlink(missing_ok=True)
+
+
+def new_deployment_id(profile: Profile, profile_path: Path | None = None) -> str:
+    """Create a timestamp-plus-digest identifier without using a secret."""
+    timestamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
+    return f"{profile.name}-{timestamp}-{profile_digest(profile, profile_path)[:12]}"
+
+
+def _proxy_ca_digest(profile: Profile, profile_path: Path) -> str:
+    """Hash profile CA inputs so certificate rotation triggers an image update."""
+    assert profile.proxy is not None
+    hasher = hashlib.sha256()
+    base = profile_path.expanduser().resolve().parent
+    if profile.proxy.ca_file is not None:
+        source = (base / profile.proxy.ca_file).resolve()
+        if not source.is_file():
+            raise ValueError(f"proxy CA file does not exist: {source}")
+        hasher.update(source.name.encode())
+        hasher.update(source.read_bytes())
+    if profile.proxy.ca_dir is not None:
+        source = (base / profile.proxy.ca_dir).resolve()
+        if not source.is_dir():
+            raise ValueError(f"proxy CA directory does not exist: {source}")
+        files = sorted(item for item in source.iterdir() if item.is_file())
+        if not files:
+            raise ValueError(f"proxy CA directory is empty: {source}")
+        for item in files:
+            hasher.update(item.name.encode())
+            hasher.update(item.read_bytes())
+    return hasher.hexdigest()