aicage 0.5.12__tar.gz → 0.7.0__tar.gz

{aicage-0.5.12 → aicage-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aicage
-Version: 0.5.12
+Version: 0.7.0
 Summary: Runs agentic coding assistants in docker containers
 Author: Stefan Kuhn
 License:                                  Apache License
@@ -278,11 +278,12 @@ preferences and credentials.
 ## aicage options
 
 - `--dry-run` prints the composed `docker run` command without executing it.
-- `--entrypoint PATH` mounts a custom entrypoint script to `/usr/local/bin/entrypoint.sh`.
+- `--aicage-entrypoint PATH` mounts a custom entrypoint script to `/usr/local/bin/entrypoint.sh`.
 - `--docker` mounts `/run/docker.sock` into the container to enable Docker-in-Docker workflows.
 - `--config print` prints the project config path and its contents.
 
-Configuration file formats are documented in [CONFIG.md](CONFIG.md).
+Configuration file formats are documented in [CONFIG.md](CONFIG.md). Extension authoring is documented in
+[doc/extensions.md](doc/extensions.md).
 
 ## Why cage agents?
 

{aicage-0.5.12 → aicage-0.7.0}/README.md

@@ -65,11 +65,12 @@ preferences and credentials.
 ## aicage options
 
 - `--dry-run` prints the composed `docker run` command without executing it.
-- `--entrypoint PATH` mounts a custom entrypoint script to `/usr/local/bin/entrypoint.sh`.
+- `--aicage-entrypoint PATH` mounts a custom entrypoint script to `/usr/local/bin/entrypoint.sh`.
 - `--docker` mounts `/run/docker.sock` into the container to enable Docker-in-Docker workflows.
 - `--config print` prints the project config path and its contents.
 
-Configuration file formats are documented in [CONFIG.md](CONFIG.md).
+Configuration file formats are documented in [CONFIG.md](CONFIG.md). Extension authoring is documented in
+[doc/extensions.md](doc/extensions.md).
 
 ## Why cage agents?
 

{aicage-0.5.12 → aicage-0.7.0}/config/agent-build/Dockerfile

@@ -1,4 +1,3 @@
-# syntax=docker/dockerfile:1.7-labs
 ARG BASE_IMAGE=base
 ARG AGENT=codex
 
@@ -18,4 +17,6 @@ RUN --mount=type=bind,source=agents/,target=/tmp/agents,readonly \
     /tmp/agents/${AGENT}/install.sh
 
 ENV AGENT=${AGENT}
-CMD ["sh", "-c", "$AGENT"]
+
+# entrypoint.sh uses this variable
+ENV AICAGE_ENTRYPOINT_CMD=${AGENT}

{aicage-0.5.12 → aicage-0.7.0}/config/agent-build/agents/claude/agent.yaml

@@ -1,4 +1,5 @@
 agent_path: ~/.claude
 agent_full_name: Claude Code
 agent_homepage: https://claude.com/product/claude-code
-redistributable: false
+# Build locally because the license does not allow redistributing prebuilt images.
+build_local: true

aicage-0.7.0/config/agent-build/agents/claude/install.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Install Claude using the official installer.
+curl -fsSL https://claude.ai/install.sh | bash
+
+# Ensure the binary is on the global PATH for the runtime user.
+if [[ -x "/root/.local/bin/claude" ]]; then
+  install -m 0755 /root/.local/bin/claude /usr/local/bin/claude
+elif command -v claude >/dev/null 2>&1; then
+  # Fallback: copy whatever the installer placed on PATH.
+  install -m 0755 "$(command -v claude)" /usr/local/bin/claude
+fi
+
+if ! command -v claude >/dev/null 2>&1; then
+  echo "[install_claude] 'claude' executable not found after installation." >&2
+  exit 1
+fi

aicage-0.7.0/config/agent-build/agents/claude/version.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Use npm to determine version despite installing with non-rpm
+# Reason: Claude infrastructure reports wrong/old version
+#
+# The official installer way leads to this url:
+# https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/stable
+# but there this version is reported:
+# 2.0.67
+# while actually this version is currently correct:
+# 2.0.76
+#
+# See bug: https://github.com/anthropics/claude-code/issues/13888
+#
+# The official installer is preferred as only then does Claude support syntax-highlighting
+
+npm view @anthropic-ai/claude-code version

aicage-0.7.0/config/agent-build/agents/droid/agent.yaml

@@ -0,0 +1,5 @@
+agent_path: ~/.factory
+agent_full_name: Factory CLI
+agent_homepage: https://factory.ai/product/cli
+# Build locally because the license does not allow redistributing prebuilt images.
+build_local: true

{aicage-0.5.12 → aicage-0.7.0}/config/config.yaml

@@ -5,3 +5,4 @@ image_repository: aicage/aicage
 image_base_repository: aicage/aicage-image-base
 default_image_base: ubuntu
 version_check_image: ghcr.io/aicage/aicage-image-util:agent-version
+local_image_repository: aicage

aicage-0.7.0/config/extension-build/Dockerfile

@@ -0,0 +1,12 @@
+ARG BASE_IMAGE=base
+FROM ${BASE_IMAGE} AS runtime
+
+SHELL ["/bin/bash", "-o", "pipefail", "-c"]
+
+RUN --mount=type=bind,source=scripts,target=/tmp/aicage/scripts,readonly \
+    set -e; \
+    shopt -s nullglob; \
+    mkdir -p /tmp/aicage/scripts-run; \
+    for script in /tmp/aicage/scripts/*.sh; do cp "$script" /tmp/aicage/scripts-run/; done; \
+    for script in /tmp/aicage/scripts-run/*.sh; do chmod +x "$script"; "$script"; done; \
+    rm -rf /tmp/aicage/scripts-run

{aicage-0.5.12 → aicage-0.7.0}/config/images-metadata.yaml

@@ -1,7 +1,7 @@
 aicage-image:
-  version: 0.5.10
+  version: 0.7.0
 aicage-image-base:
-  version: 0.5.7
+  version: 0.7.0
 bases:
   act:
     root_image: ghcr.io/catthehacker/ubuntu:act-latest
@@ -50,20 +50,21 @@ agent:
     agent_path: ~/.claude
     agent_full_name: Claude Code
     agent_homepage: https://claude.com/product/claude-code
-    redistributable: false
+    # Build locally because the license does not allow redistributing prebuilt images.
+    build_local: true
     valid_bases:
-      act: ghcr.io/aicage/aicage:claude-act
-      alpine: ghcr.io/aicage/aicage:claude-alpine
-      debian: ghcr.io/aicage/aicage:claude-debian
-      fedora: ghcr.io/aicage/aicage:claude-fedora
-      minimal: ghcr.io/aicage/aicage:claude-minimal
-      node: ghcr.io/aicage/aicage:claude-node
-      ubuntu: ghcr.io/aicage/aicage:claude-ubuntu
+      act: aicage:claude-act
+      alpine: aicage:claude-alpine
+      debian: aicage:claude-debian
+      fedora: aicage:claude-fedora
+      minimal: aicage:claude-minimal
+      node: aicage:claude-node
+      ubuntu: aicage:claude-ubuntu
   codex:
     agent_path: ~/.codex
     agent_full_name: Codex CLI
     agent_homepage: https://developers.openai.com/codex/cli
-    redistributable: true
+    build_local: false
     valid_bases:
       act: ghcr.io/aicage/aicage:codex-act
       alpine: ghcr.io/aicage/aicage:codex-alpine
@@ -76,7 +77,7 @@ agent:
     agent_path: ~/.copilot
     agent_full_name: GitHub Copilot CLI
     agent_homepage: https://github.com/features/copilot/cli
-    redistributable: true
+    build_local: false
     base_exclude:
       - alpine
       - minimal
@@ -92,7 +93,7 @@ agent:
     agent_path: ~/.local/share/crush
     agent_full_name: Crush
     agent_homepage: https://github.com/charmbracelet/crush
-    redistributable: true
+    build_local: false
     valid_bases:
       act: ghcr.io/aicage/aicage:crush-act
       alpine: ghcr.io/aicage/aicage:crush-alpine
@@ -105,20 +106,21 @@ agent:
     agent_path: ~/.factory
     agent_full_name: Factory CLI
     agent_homepage: https://factory.ai/product/cli
-    redistributable: false
+    # Build locally because the license does not allow redistributing prebuilt images.
+    build_local: true
     valid_bases:
-      act: ghcr.io/aicage/aicage:droid-act
-      alpine: ghcr.io/aicage/aicage:droid-alpine
-      debian: ghcr.io/aicage/aicage:droid-debian
-      fedora: ghcr.io/aicage/aicage:droid-fedora
-      minimal: ghcr.io/aicage/aicage:droid-minimal
-      node: ghcr.io/aicage/aicage:droid-node
-      ubuntu: ghcr.io/aicage/aicage:droid-ubuntu
+      act: aicage:droid-act
+      alpine: aicage:droid-alpine
+      debian: aicage:droid-debian
+      fedora: aicage:droid-fedora
+      minimal: aicage:droid-minimal
+      node: aicage:droid-node
+      ubuntu: aicage:droid-ubuntu
   gemini:
     agent_path: ~/.gemini
     agent_full_name: Gemini CLI
     agent_homepage: https://geminicli.com
-    redistributable: true
+    build_local: false
     valid_bases:
       act: ghcr.io/aicage/aicage:gemini-act
       alpine: ghcr.io/aicage/aicage:gemini-alpine
@@ -131,7 +133,7 @@ agent:
     agent_path: ~/.config/goose
     agent_full_name: Goose CLI
     agent_homepage: https://block.github.io/goose
-    redistributable: true
+    build_local: false
     valid_bases:
       act: ghcr.io/aicage/aicage:goose-act
       alpine: ghcr.io/aicage/aicage:goose-alpine
@@ -144,7 +146,7 @@ agent:
     agent_path: ~/.qwen
     agent_full_name: Qwen Code
     agent_homepage: https://github.com/QwenLM/qwen-code
-    redistributable: true
+    build_local: false
     valid_bases:
       act: ghcr.io/aicage/aicage:qwen-act
       alpine: ghcr.io/aicage/aicage:qwen-alpine

aicage-0.7.0/config/validation/agent.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AICAGE agent definition",
+  "type": "object",
+  "required": [
+    "agent_path",
+    "agent_full_name",
+    "agent_homepage"
+  ],
+  "properties": {
+    "agent_path": {
+      "type": "string"
+    },
+    "agent_full_name": {
+      "type": "string"
+    },
+    "agent_homepage": {
+      "type": "string"
+    },
+    "build_local": {
+      "type": "boolean",
+      "default": true
+    },
+    "base_exclude": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "base_distro_exclude": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "additionalProperties": false
+}

{aicage-0.5.12 → aicage-0.7.0}/pyproject.toml

@@ -26,12 +26,16 @@ packages = ["src/aicage"]
 "config/config.yaml" = "config/config.yaml"
 "config/images-metadata.yaml" = "config/images-metadata.yaml"
 "config/agent-build" = "config/agent-build"
+"config/extension-build" = "config/extension-build"
+"config/validation/agent.schema.json" = "config/validation/agent.schema.json"
 
 [tool.hatch.build]
 include = [
   "config/config.yaml",
   "config/images-metadata.yaml",
   "config/agent-build/**",
+  "config/extension-build/**",
+  "config/validation/agent.schema.json",
 ]
 
 [tool.hatch.build.targets.sdist]
@@ -40,6 +44,8 @@ include = [
   "config/config.yaml",
   "config/images-metadata.yaml",
   "config/agent-build/**",
+  "config/extension-build/**",
+  "config/validation/agent.schema.json",
   "LICENSE",
   "README.md",
   "pyproject.toml",

{aicage-0.5.12 → aicage-0.7.0}/src/aicage/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.5.12'
-__version_tuple__ = version_tuple = (0, 5, 12)
+__version__ = version = '0.7.0'
+__version_tuple__ = version_tuple = (0, 7, 0)
 
 __commit_id__ = commit_id = None

{aicage-0.5.12 → aicage-0.7.0}/src/aicage/cli/_parse.py

@@ -6,7 +6,7 @@ from aicage._logging import get_logger
 from aicage.cli_types import ParsedArgs
 from aicage.errors import CliError
 
-MIN_REMAINING_FOR_DOCKER_ARGS = 2
+_MIN_REMAINING_WITH_AGENT = 2
 
 
 def parse_cli(argv: Sequence[str]) -> ParsedArgs:
@@ -16,7 +16,11 @@ def parse_cli(argv: Sequence[str]) -> ParsedArgs:
     """
     parser = argparse.ArgumentParser(add_help=False)
     parser.add_argument("--dry-run", action="store_true", help="Print docker run command without executing.")
-    parser.add_argument("--entrypoint", help="Override the container entrypoint with a host path.")
+    parser.add_argument(
+        "--aicage-entrypoint",
+        dest="entrypoint",
+        help="Override the container entrypoint with a host path.",
+    )
     parser.add_argument("--docker", action="store_true", help="Mount the host Docker socket into the container.")
     parser.add_argument("--config", help="Perform config actions such as 'print'.")
     parser.add_argument("-h", "--help", action="store_true", help="Show help message and exit.")
@@ -30,8 +34,8 @@ def parse_cli(argv: Sequence[str]) -> ParsedArgs:
         usage: str = (
             "Usage:\n"
             "  aicage <agent>\n"
-            "  aicage [--dry-run] [--docker] [--entrypoint PATH] -- <agent> [<agent-args>]\n"
-            "  aicage [--dry-run] [--docker] [--entrypoint PATH] <docker-args> -- <agent> [<agent-args>]\n"
+            "  aicage [--dry-run] [--docker] [--aicage-entrypoint PATH] -- <agent> [<agent-args>]\n"
+            "  aicage [--dry-run] [--docker] [--aicage-entrypoint PATH] <docker-args> -- <agent> [<agent-args>]\n"
             "  aicage --config print\n\n"
             "Any arguments between aicage and the agent require a '--' separator before the agent.\n"
             "<docker-args> are any arguments not recognized by aicage.\n"
@@ -102,6 +106,8 @@ def _parse_agent_section(
     if not remaining:
         raise CliError("Missing arguments. Provide an agent name (and optional docker args).")
     first: str = remaining[0]
-    if len(remaining) >= MIN_REMAINING_FOR_DOCKER_ARGS and (first.startswith("-") or "=" in first):
+    if first.startswith("-") or "=" in first:
+        if len(remaining) < _MIN_REMAINING_WITH_AGENT:
+            raise CliError("Missing agent name after docker args. Use '--' before the agent.")
         return first, remaining[1], remaining[2:]
     return "", first, remaining[1:]

{aicage-0.5.12 → aicage-0.7.0}/src/aicage/cli/entrypoint.py

@@ -7,9 +7,11 @@ from aicage._logging import get_logger
 from aicage.cli._parse import parse_cli
 from aicage.cli._print_config import print_project_config
 from aicage.cli_types import ParsedArgs
-from aicage.config import ConfigError, RunConfig, load_run_config
+from aicage.config import ConfigError
+from aicage.config.runtime_config import RunConfig, load_run_config
 from aicage.errors import CliError
 from aicage.registry.image_pull import pull_image
+from aicage.registry.local_build.ensure_extended_image import ensure_extended_image
 from aicage.registry.local_build.ensure_local_image import ensure_local_image
 from aicage.runtime.run_args import DockerRunArgs, assemble_docker_run
 from aicage.runtime.run_plan import build_run_args
@@ -26,10 +28,12 @@ def main(argv: Sequence[str] | None = None) -> int:
         run_config: RunConfig = load_run_config(parsed.agent, parsed)
         logger.info("Resolved run config for agent %s", run_config.agent)
         agent_metadata = run_config.images_metadata.agents[run_config.agent]
-        if not agent_metadata.redistributable and not agent_metadata.is_custom:
-            ensure_local_image(run_config)
-        else:
+        if run_config.extensions:
+            ensure_extended_image(run_config)
+        elif agent_metadata.local_definition_dir is None:
             pull_image(run_config)
+        else:
+            ensure_local_image(run_config)
         run_args: DockerRunArgs = build_run_args(config=run_config, parsed=parsed)
 
         run_cmd: list[str] = assemble_docker_run(run_args)

aicage-0.7.0/src/aicage/config/__init__.py

@@ -0,0 +1,4 @@
+from .config_store import SettingsStore as SettingsStore
+from .errors import ConfigError as ConfigError
+from .global_config import GlobalConfig as GlobalConfig
+from .project_config import ProjectConfig as ProjectConfig

{aicage-0.5.12 → aicage-0.7.0}/src/aicage/config/config_store.py

@@ -7,12 +7,13 @@ from typing import Any
 
 import yaml
 
+from aicage.paths import CONFIG_FILENAME
+
 from .errors import ConfigError
 from .global_config import GlobalConfig
 from .project_config import ProjectConfig
 from .resources import find_packaged_path
 
-_CONFIG_FILENAME = "config.yaml"
 _DEFAULT_BASE_DIR = "~/.aicage"
 _PROJECTS_SUBDIR = "projects"
 
@@ -66,7 +67,7 @@ class SettingsStore:
         """
         Returns the path to the packaged global config file.
         """
-        return find_packaged_path(_CONFIG_FILENAME)
+        return find_packaged_path(CONFIG_FILENAME)
 
     def project_config_path(self, project_realpath: Path) -> Path:
         """

{aicage-0.5.12 → aicage-0.7.0}/src/aicage/config/context.py

@@ -20,11 +20,11 @@ class ConfigContext:
         return f"{self.global_cfg.image_registry}/{self.global_cfg.image_repository}"
 
 
-def build_config_context() -> ConfigContext:
+def _build_config_context() -> ConfigContext:
     store = SettingsStore()
     project_path = Path.cwd().resolve()
     global_cfg = store.load_global()
-    images_metadata = load_images_metadata()
+    images_metadata = load_images_metadata(global_cfg.local_image_repository)
     project_cfg = store.load_project(project_path)
     return ConfigContext(
         store=store,
@@ -32,5 +32,3 @@ def build_config_context() -> ConfigContext:
         global_cfg=global_cfg,
         images_metadata=images_metadata,
     )
-
-

aicage-0.7.0/src/aicage/config/global_config.py

@@ -0,0 +1,67 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import ConfigError
+
+_IMAGE_REGISTRY_KEY: str = "image_registry"
+_IMAGE_REGISTRY_API_URL_KEY: str = "image_registry_api_url"
+_IMAGE_REGISTRY_API_TOKEN_URL_KEY: str = "image_registry_api_token_url"
+_IMAGE_REPOSITORY_KEY: str = "image_repository"
+_IMAGE_BASE_REPOSITORY_KEY: str = "image_base_repository"
+_DEFAULT_IMAGE_BASE_KEY: str = "default_image_base"
+_VERSION_CHECK_IMAGE_KEY: str = "version_check_image"
+_LOCAL_IMAGE_REPOSITORY_KEY: str = "local_image_repository"
+_GLOBAL_AGENTS_KEY: str = "agents"
+
+
+@dataclass
+class GlobalConfig:
+    image_registry: str
+    image_registry_api_url: str
+    image_registry_api_token_url: str
+    image_repository: str
+    image_base_repository: str
+    default_image_base: str
+    version_check_image: str
+    local_image_repository: str
+    agents: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+    @classmethod
+    def from_mapping(cls, data: dict[str, Any]) -> "GlobalConfig":
+        required = (
+            _IMAGE_REGISTRY_KEY,
+            _IMAGE_REGISTRY_API_URL_KEY,
+            _IMAGE_REGISTRY_API_TOKEN_URL_KEY,
+            _IMAGE_REPOSITORY_KEY,
+            _IMAGE_BASE_REPOSITORY_KEY,
+            _DEFAULT_IMAGE_BASE_KEY,
+            _VERSION_CHECK_IMAGE_KEY,
+            _LOCAL_IMAGE_REPOSITORY_KEY,
+        )
+        missing = [key for key in required if key not in data]
+        if missing:
+            raise ConfigError(f"Missing required config values: {', '.join(missing)}.")
+        return cls(
+            image_registry=data[_IMAGE_REGISTRY_KEY],
+            image_registry_api_url=data[_IMAGE_REGISTRY_API_URL_KEY],
+            image_registry_api_token_url=data[_IMAGE_REGISTRY_API_TOKEN_URL_KEY],
+            image_repository=data[_IMAGE_REPOSITORY_KEY],
+            image_base_repository=data[_IMAGE_BASE_REPOSITORY_KEY],
+            default_image_base=data[_DEFAULT_IMAGE_BASE_KEY],
+            version_check_image=data[_VERSION_CHECK_IMAGE_KEY],
+            local_image_repository=data[_LOCAL_IMAGE_REPOSITORY_KEY],
+            agents=data.get(_GLOBAL_AGENTS_KEY, {}) or {},
+        )
+
+    def to_mapping(self) -> dict[str, Any]:
+        return {
+            _IMAGE_REGISTRY_KEY: self.image_registry,
+            _IMAGE_REGISTRY_API_URL_KEY: self.image_registry_api_url,
+            _IMAGE_REGISTRY_API_TOKEN_URL_KEY: self.image_registry_api_token_url,
+            _IMAGE_REPOSITORY_KEY: self.image_repository,
+            _IMAGE_BASE_REPOSITORY_KEY: self.image_base_repository,
+            _DEFAULT_IMAGE_BASE_KEY: self.default_image_base,
+            _VERSION_CHECK_IMAGE_KEY: self.version_check_image,
+            _LOCAL_IMAGE_REPOSITORY_KEY: self.local_image_repository,
+            _GLOBAL_AGENTS_KEY: self.agents,
+        }

aicage-0.7.0/src/aicage/config/project_config.py

@@ -0,0 +1,116 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+_PROJECT_PATH_KEY: str = "path"
+_PROJECT_AGENTS_KEY: str = "agents"
+_DOCKER_ARGS_KEY: str = "docker_args"
+
+AGENT_BASE_KEY: str = "base"
+_AGENT_ENTRYPOINT_KEY: str = "entrypoint"
+_AGENT_MOUNTS_KEY: str = "mounts"
+_AGENT_IMAGE_REF_KEY: str = "image_ref"
+_AGENT_EXTENSIONS_KEY: str = "extensions"
+
+_MOUNT_GITCONFIG_KEY: str = "gitconfig"
+_MOUNT_GNUPG_KEY: str = "gnupg"
+_MOUNT_SSH_KEY: str = "ssh"
+_MOUNT_DOCKER_KEY: str = "docker"
+
+
+@dataclass
+class _AgentMounts:
+    gitconfig: bool | None = None
+    gnupg: bool | None = None
+    ssh: bool | None = None
+    docker: bool | None = None
+
+    @classmethod
+    def from_mapping(cls, data: dict[str, Any]) -> "_AgentMounts":
+        return cls(
+            gitconfig=data.get(_MOUNT_GITCONFIG_KEY),
+            gnupg=data.get(_MOUNT_GNUPG_KEY),
+            ssh=data.get(_MOUNT_SSH_KEY),
+            docker=data.get(_MOUNT_DOCKER_KEY),
+        )
+
+    def to_mapping(self) -> dict[str, bool]:
+        payload: dict[str, bool] = {}
+        if self.gitconfig is not None:
+            payload[_MOUNT_GITCONFIG_KEY] = self.gitconfig
+        if self.gnupg is not None:
+            payload[_MOUNT_GNUPG_KEY] = self.gnupg
+        if self.ssh is not None:
+            payload[_MOUNT_SSH_KEY] = self.ssh
+        if self.docker is not None:
+            payload[_MOUNT_DOCKER_KEY] = self.docker
+        return payload
+
+
+@dataclass
+class AgentConfig:
+    base: str | None = None
+    docker_args: str = ""
+    entrypoint: str | None = None
+    mounts: _AgentMounts = field(default_factory=_AgentMounts)
+    image_ref: str | None = None
+    extensions: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_mapping(cls, data: dict[str, Any]) -> "AgentConfig":
+        mounts = _AgentMounts.from_mapping(data.get(_AGENT_MOUNTS_KEY, {}) or {})
+        return cls(
+            base=data.get(AGENT_BASE_KEY),
+            docker_args=data.get(_DOCKER_ARGS_KEY, "") or "",
+            entrypoint=data.get(_AGENT_ENTRYPOINT_KEY),
+            mounts=mounts,
+            image_ref=data.get(_AGENT_IMAGE_REF_KEY),
+            extensions=_read_str_list(data.get(_AGENT_EXTENSIONS_KEY)),
+        )
+
+    def to_mapping(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {}
+        if self.base:
+            payload[AGENT_BASE_KEY] = self.base
+        if self.docker_args:
+            payload[_DOCKER_ARGS_KEY] = self.docker_args
+        if self.entrypoint:
+            payload[_AGENT_ENTRYPOINT_KEY] = self.entrypoint
+        mounts = self.mounts.to_mapping()
+        if mounts:
+            payload[_AGENT_MOUNTS_KEY] = mounts
+        if self.image_ref:
+            payload[_AGENT_IMAGE_REF_KEY] = self.image_ref
+        if self.extensions:
+            payload[_AGENT_EXTENSIONS_KEY] = list(self.extensions)
+        return payload
+
+
+@dataclass
+class ProjectConfig:
+    path: str
+    agents: dict[str, AgentConfig] = field(default_factory=dict)
+
+    @classmethod
+    def from_mapping(cls, project_path: Path, data: dict[str, Any]) -> "ProjectConfig":
+        raw_agents = data.get(_PROJECT_AGENTS_KEY, {}) or {}
+        agents = {name: AgentConfig.from_mapping(cfg) for name, cfg in raw_agents.items()}
+        legacy_docker_args = data.get(_DOCKER_ARGS_KEY, "")
+        if legacy_docker_args:
+            for agent_cfg in agents.values():
+                if not agent_cfg.docker_args:
+                    agent_cfg.docker_args = legacy_docker_args
+        return cls(
+            path=data.get(_PROJECT_PATH_KEY, str(project_path)),
+            agents=agents,
+        )
+
+    def to_mapping(self) -> dict[str, Any]:
+        agents_payload = {name: cfg.to_mapping() for name, cfg in self.agents.items()}
+        return {_PROJECT_PATH_KEY: self.path, _PROJECT_AGENTS_KEY: agents_payload}
+
+
+def _read_str_list(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [item for item in value if isinstance(item, str) and item]