agent-circus 0.1.0__py3-none-any.whl

agent_circus/__init__.py

@@ -0,0 +1,5 @@
+"""Agent Circus - CLI for managing agent containers."""
+
+from importlib.metadata import version as distribution_version
+
+__version__ = distribution_version("agent-circus")

agent_circus/agent_config.py

@@ -0,0 +1,357 @@
+"""Agent configuration templating for Agent Circus.
+
+Reads each agent's original configuration file, merges in additions
+(e.g. MCP servers), writes the result to the state directory, and
+generates a Docker Compose override that bind-mounts the merged
+files into agent containers.
+
+The user's host files are never modified.
+"""
+
+import json
+import logging
+import tomllib
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+import tomli_w
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Handler protocol
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class AgentConfigHandler(Protocol):
+    """Structural interface for agent-specific configuration handlers."""
+
+    agent_name: str
+    """Docker Compose service name (e.g. ``"claude-code"``)."""
+
+    host_config_path: Path
+    """Path to the user's original config file on the host."""
+
+    container_config_path: str
+    """Absolute path where the config is expected inside the container."""
+
+    output_filename: str
+    """Filename for the merged config in the state directory."""
+
+    def read(self) -> dict[str, Any]:
+        """Read and deserialize the user's original config.
+
+        Returns an empty dict if the file does not exist.
+        """
+        ...
+
+    def merge(self, base: dict[str, Any], additions: dict[str, Any]) -> dict[str, Any]:
+        """Merge *additions* into *base* config.
+
+        :param base: The user's original (deserialized) config.
+        :param additions: Values to merge in (e.g. ``{"mcp_servers": [...]}``)
+        :returns: Merged config.
+        """
+        ...
+
+    def write(self, config: dict[str, Any], output_path: Path) -> None:
+        """Serialize *config* and write it to *output_path*."""
+        ...
+
+
+def build_handler(
+    handler: AgentConfigHandler,
+    additions: dict[str, Any],
+    output_dir: Path,
+) -> Path:
+    """Read → merge → write using the given handler.
+
+    :param handler: Agent config handler to use.
+    :param additions: Values to merge into the user's config.
+    :param output_dir: Directory to write the merged config to.
+    :returns: Path to the written file.
+    """
+    base = handler.read()
+    merged = handler.merge(base, additions)
+    output_path = output_dir / handler.output_filename
+    handler.write(merged, output_path)
+    logger.debug("Built merged config for %s: %s", handler.agent_name, output_path)
+    return output_path
+
+
+# ---------------------------------------------------------------------------
+# JSON-based handlers (Claude Code, OpenCode)
+# ---------------------------------------------------------------------------
+
+
+class ClaudeCodeConfigHandler:
+    """Handler for Claude Code configuration (JSON)."""
+
+    agent_name = "claude-code"
+    container_config_path = "/home/node/.claude/.claude.json"
+    output_filename = "claude-code.json"
+
+    def __init__(self) -> None:
+        self.host_config_path = Path.home() / ".claude" / ".claude.json"
+
+    def read(self) -> dict[str, Any]:
+        if not self.host_config_path.is_file():
+            return {}
+        with open(self.host_config_path) as f:
+            return json.load(f)
+
+    def merge(self, base: dict[str, Any], additions: dict[str, Any]) -> dict[str, Any]:
+        merged = base.copy()
+        for key, value in additions.items():
+            if (
+                key in merged
+                and isinstance(merged[key], dict)
+                and isinstance(value, dict)
+            ):
+                # Dict-level merge (e.g. mcpServers): additions overwrite conflicts.
+                merged[key] = {**merged[key], **value}
+            else:
+                merged[key] = value
+        return merged
+
+    def write(self, config: dict[str, Any], output_path: Path) -> None:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, "w") as f:
+            json.dump(config, f, indent=2)
+            f.write("\n")
+
+
+class OpenCodeConfigHandler:
+    """Handler for OpenCode configuration (JSON)."""
+
+    agent_name = "opencode"
+    container_config_path = "/home/node/.config/opencode/opencode.json"
+    output_filename = "opencode.json"
+
+    def __init__(self) -> None:
+        self.host_config_path = Path.home() / ".config" / "opencode" / "opencode.json"
+
+    def read(self) -> dict[str, Any]:
+        if not self.host_config_path.is_file():
+            return {}
+        with open(self.host_config_path) as f:
+            return json.load(f)
+
+    def merge(self, base: dict[str, Any], additions: dict[str, Any]) -> dict[str, Any]:
+        merged = base.copy()
+        for key, value in additions.items():
+            if (
+                key in merged
+                and isinstance(merged[key], dict)
+                and isinstance(value, dict)
+            ):
+                # Dict-level merge (e.g. mcp): additions overwrite conflicts.
+                merged[key] = {**merged[key], **value}
+            else:
+                merged[key] = value
+        return merged
+
+    def write(self, config: dict[str, Any], output_path: Path) -> None:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, "w") as f:
+            json.dump(config, f, indent=2)
+            f.write("\n")
+
+
+# ---------------------------------------------------------------------------
+# TOML-based handlers (Codex, Vibe)
+# ---------------------------------------------------------------------------
+
+
+class _TomlConfigHandler:
+    """Base handler for TOML-based agent configs (Codex, Vibe)."""
+
+    host_config_path: Path
+
+    def read(self) -> dict[str, Any]:
+        if not self.host_config_path.is_file():
+            return {}
+        with open(self.host_config_path, "rb") as f:
+            return tomllib.load(f)
+
+    def merge(self, base: dict[str, Any], additions: dict[str, Any]) -> dict[str, Any]:
+        merged = base.copy()
+        for key, value in additions.items():
+            if (
+                key in merged
+                and isinstance(merged[key], list)
+                and isinstance(value, list)
+            ):
+                # Array merge by "name" field: additions overwrite entries
+                # with the same name, new entries are appended.
+                merged[key] = _merge_named_arrays(merged[key], value)
+            elif (
+                key in merged
+                and isinstance(merged[key], dict)
+                and isinstance(value, dict)
+            ):
+                merged[key] = {**merged[key], **value}
+            else:
+                merged[key] = value
+        return merged
+
+    def write(self, config: dict[str, Any], output_path: Path) -> None:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, "wb") as f:
+            tomli_w.dump(config, f)
+
+
+class CodexConfigHandler(_TomlConfigHandler):
+    """Handler for Codex configuration (TOML)."""
+
+    agent_name = "codex"
+    container_config_path = "/home/node/.codex/config.toml"
+    output_filename = "codex.toml"
+
+    def __init__(self) -> None:
+        self.host_config_path = Path.home() / ".codex" / "config.toml"
+
+
+class VibeConfigHandler(_TomlConfigHandler):
+    """Handler for Mistral Vibe configuration (TOML)."""
+
+    agent_name = "mistral-vibe"
+    container_config_path = "/home/node/.vibe/config.toml"
+    output_filename = "mistral-vibe.toml"
+
+    def __init__(self) -> None:
+        self.host_config_path = Path.home() / ".vibe" / "config.toml"
+
+
+# ---------------------------------------------------------------------------
+# Merge helpers
+# ---------------------------------------------------------------------------
+
+
+def _merge_named_arrays(
+    base: list[dict[str, Any]], additions: list[dict[str, Any]]
+) -> list[dict[str, Any]]:
+    """Merge two lists of dicts by the ``name`` field.
+
+    Entries in *additions* overwrite base entries with the same name.
+    New entries are appended.  Order: base entries first (updated
+    in-place), then new additions.
+
+    Falls back to simple concatenation if entries lack ``name`` fields.
+
+    :param base: Original list of entries.
+    :param additions: Entries to merge in.
+    :returns: Merged list.
+    """
+    # Check if entries have "name" fields for keyed merging.
+    if not all(isinstance(e, dict) and "name" in e for e in [*base, *additions]):
+        return [*base, *additions]
+
+    by_name: dict[str, dict[str, Any]] = {e["name"]: e for e in base}
+    order: list[str] = [e["name"] for e in base]
+
+    for entry in additions:
+        name = entry["name"]
+        if name not in by_name:
+            order.append(name)
+        by_name[name] = entry
+
+    return [by_name[name] for name in order]
+
+
+# ---------------------------------------------------------------------------
+# All handlers
+# ---------------------------------------------------------------------------
+
+
+HANDLERS: list[type[AgentConfigHandler]] = [
+    ClaudeCodeConfigHandler,
+    CodexConfigHandler,
+    VibeConfigHandler,
+    OpenCodeConfigHandler,
+]
+
+
+# ---------------------------------------------------------------------------
+# Compose override generation
+# ---------------------------------------------------------------------------
+
+
+def build_agent_configs_override(
+    additions: dict[str, dict[str, Any]],
+    output_dir: Path,
+    excluded_agents: set[str] | None = None,
+) -> str:
+    """Build merged agent configs and return a Compose override JSON string.
+
+    For each agent, reads the user's original config, merges in
+    *additions*, writes the result to *output_dir*, and produces a
+    Compose override that bind-mounts the merged files into the
+    corresponding containers.
+
+    :param additions: Per-agent additions dict, keyed by agent name.
+        Example::
+
+            {
+                "claude-code": {"mcpServers": {...}},
+                "codex": {"mcp_servers": [...]},
+                "mistral-vibe": {"mcp_servers": [...]},
+                "opencode": {"mcp": {...}},
+            }
+
+    :param output_dir: Directory to write merged config files to.
+    :type output_dir: Path
+    :param excluded_agents: Agents whose config is managed through another
+        writable mount, such as a project data store.
+    :returns: Compose override as a JSON string.
+    :rtype: str
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
+    services: dict[str, Any] = {}
+    excluded_agents = excluded_agents or set()
+
+    for handler_cls in HANDLERS:
+        handler = handler_cls()
+        if handler.agent_name in excluded_agents:
+            continue
+        agent_additions = additions.get(handler.agent_name, {})
+        if not agent_additions:
+            continue
+
+        output_path = build_handler(handler, agent_additions, output_dir)
+        services[handler.agent_name] = {
+            "volumes": [
+                f"{output_path}:{handler.container_config_path}",
+            ],
+        }
+
+    return json.dumps({"services": services})
+
+
+def merge_agent_config_store(
+    agent_name: str,
+    additions: dict[str, Any],
+    store_dir: Path,
+) -> Path:
+    """Merge generated additions into an agent config data store.
+
+    :param agent_name: Agent service whose native config should be updated.
+    :param additions: Values to merge into the native agent configuration.
+    :param store_dir: Host directory mounted at the agent's config directory.
+    :returns: Path to the updated native configuration file.
+    :raises ValueError: If ``agent_name`` has no configuration handler.
+    """
+    for handler_cls in HANDLERS:
+        handler = handler_cls()
+        if handler.agent_name != agent_name:
+            continue
+
+        config_path = store_dir / Path(handler.container_config_path).name
+        handler.host_config_path = config_path
+        merged = handler.merge(handler.read(), additions)
+        handler.write(merged, config_path)
+        return config_path
+
+    raise ValueError(f"Unsupported agent config store: {agent_name}")

agent_circus/cli.py

@@ -0,0 +1,73 @@
+"""Main CLI entry point for Agent Circus."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from agent_circus.commands import (
+    build,
+    config_store,
+    destroy,
+    exec_,
+    init,
+    ps,
+    remove,
+    up,
+)
+from agent_circus.config import load_user_config
+from agent_circus.utils import setup_logging
+
+app = typer.Typer(
+    name="agent-circus",
+    help="CLI for managing agent containers.",
+    no_args_is_help=True,
+)
+
+
+@app.callback()
+def main(
+    log_level: Annotated[
+        str | None,
+        typer.Option(
+            "--log-level",
+            envvar="LOGLEVEL",
+            help="Set the log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).",
+        ),
+    ] = None,
+    log_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--log-file",
+            envvar="LOGFILE",
+            help="Path to a log file. Logs are written to both stdout and this file.",
+        ),
+    ] = None,
+) -> None:
+    """CLI for managing agent containers."""
+    logging_cfg = load_user_config().get("logging", {})
+    setup_logging(
+        level=log_level or logging_cfg.get("level", "INFO"),
+        log_file=log_file
+        or (Path(logging_cfg["file"]) if logging_cfg.get("file") else None),
+    )
+
+
+app.command()(init.init)
+app.command()(build.build)
+app.command()(up.up)
+app.command()(ps.ps)
+app.command(name="exec")(exec_.exec_cmd)
+app.command()(remove.remove)
+app.command(name="rm", hidden=True)(remove.remove)
+app.command()(destroy.destroy)
+app.add_typer(config_store.app, name="config")
+
+
+def run_cli() -> None:
+    """Entry point for the CLI."""
+    app()
+
+
+if __name__ == "__main__":
+    run_cli()

agent_circus/commands/__init__.py

@@ -0,0 +1,5 @@
+"""Command modules for Agent Circus CLI."""
+
+from agent_circus.commands import build, config_store, destroy, exec_, init, remove, up
+
+__all__ = ["build", "config_store", "destroy", "exec_", "init", "remove", "up"]

agent_circus/commands/build.py

@@ -0,0 +1,83 @@
+"""Build agent container images."""
+
+import logging
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from agent_circus.compose import compose_build
+from agent_circus.config import (
+    AVAILABLE_SERVICES,
+    get_workspace_path,
+    validate_services,
+)
+from agent_circus.context import build_compose_context
+from agent_circus.exceptions import AgentCircusError
+
+logger = logging.getLogger(__name__)
+
+
+def build(
+    services: Annotated[
+        list[str] | None,
+        typer.Argument(
+            help=f"Services to build. Available: {', '.join(AVAILABLE_SERVICES)}",
+        ),
+    ] = None,
+    workspace: Annotated[
+        Path | None,
+        typer.Option(
+            "--workspace",
+            "-w",
+            help="Workspace directory path.",
+            exists=True,
+            file_okay=False,
+            resolve_path=True,
+        ),
+    ] = None,
+    no_cache: Annotated[
+        bool,
+        typer.Option(
+            "--no-cache",
+            help="Build without using cache.",
+        ),
+    ] = False,
+    runtime: Annotated[
+        str | None,
+        typer.Option(
+            "--runtime",
+            help="Container runtime backend to use: docker or podman.",
+        ),
+    ] = None,
+) -> None:
+    """Build agent container images.
+
+    Builds container images for the specified services using the selected
+    runtime's Compose implementation.
+    If no services are specified, all services will be built.
+
+    Examples:
+        agent-circus build                    # Build all services
+        agent-circus build claude-code        # Build only claude-code
+        agent-circus build codex mistral-vibe # Build multiple services
+        agent-circus build --no-cache         # Build without cache
+    """
+    workspace = workspace or get_workspace_path()
+
+    try:
+        services_to_build = validate_services(services or [])
+
+        if services:
+            typer.echo(f"Building services: {', '.join(services_to_build)}")
+        else:
+            typer.echo("Building all services...")
+
+        context_kwargs = {"runtime": runtime} if runtime is not None else {}
+        with build_compose_context(workspace, **context_kwargs) as ctx:
+            compose_build(ctx, services_to_build, no_cache=no_cache)
+        typer.echo("Build completed successfully.")
+
+    except AgentCircusError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1) from e

agent_circus/commands/config_store.py

@@ -0,0 +1,104 @@
+"""Manage project-local writable agent configuration stores."""
+
+import shutil
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from agent_circus.compose import compose_is_service_running
+from agent_circus.config import (
+    AVAILABLE_SERVICES,
+    get_agent_config_data_stores,
+    get_workspace_path,
+    load_config,
+    validate_services,
+)
+from agent_circus.context import build_compose_context
+from agent_circus.exceptions import AgentCircusError, ConfigurationError
+from agent_circus.state import get_agent_config_store_dir, get_data_store_dir
+
+app = typer.Typer(help="Manage writable agent configuration stores.")
+
+
+def _config_store_path(workspace: Path, agent_name: str) -> Path:
+    """Return the active writable config store path for an agent.
+
+    :param workspace: Workspace directory.
+    :param agent_name: Agent service name.
+    :returns: Built-in or explicitly configured store path.
+    """
+    owners = get_agent_config_data_stores(load_config(workspace).get("data_stores", []))
+    explicit_store = owners.get(agent_name)
+    if explicit_store:
+        return get_data_store_dir(workspace, explicit_store)
+    return get_agent_config_store_dir(workspace, agent_name)
+
+
+@app.command()
+def reset(
+    agent: Annotated[
+        str | None,
+        typer.Argument(
+            help=f"Agent to reset. Available: {', '.join(AVAILABLE_SERVICES)}"
+        ),
+    ] = None,
+    all_agents: Annotated[
+        bool,
+        typer.Option("--all", help="Reset configuration stores for every agent."),
+    ] = False,
+    workspace: Annotated[
+        Path | None,
+        typer.Option(
+            "--workspace",
+            "-w",
+            help="Workspace directory path.",
+            exists=True,
+            file_okay=False,
+            resolve_path=True,
+        ),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Skip the confirmation prompt."),
+    ] = False,
+    runtime: Annotated[
+        str | None,
+        typer.Option(
+            "--runtime",
+            help="Container runtime backend to use: docker or podman.",
+        ),
+    ] = None,
+) -> None:
+    """Delete writable config stores so the next start seeds them again."""
+    workspace = workspace or get_workspace_path()
+
+    try:
+        if all_agents == (agent is not None):
+            raise ConfigurationError("Specify exactly one agent or --all")
+        agents = AVAILABLE_SERVICES if all_agents else validate_services([agent or ""])
+
+        context_kwargs = {"runtime": runtime} if runtime is not None else {}
+        with build_compose_context(workspace, **context_kwargs) as ctx:
+            running = [name for name in agents if compose_is_service_running(ctx, name)]
+        if running:
+            raise ConfigurationError(
+                "Cannot reset config for running services: " + ", ".join(running)
+            )
+
+        if not force:
+            typer.echo(
+                "This will delete writable config for: " + ", ".join(agents) + "."
+            )
+            if not typer.confirm("Are you sure you want to continue?"):
+                typer.echo("Aborted.")
+                raise typer.Exit(code=0)
+
+        for name in agents:
+            store_path = _config_store_path(workspace, name)
+            if store_path.exists():
+                shutil.rmtree(store_path)
+            typer.echo(f"Reset {name} config store: {store_path}")
+    except AgentCircusError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1) from e