axio-tools-docker 0.1.0__tar.gz

axio_tools_docker-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+env:
+  FORCE_COLOR: 1
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Set version from release tag
+        run: uv version "${GITHUB_REF_NAME#v}"
+
+      - name: Build package
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

axio_tools_docker-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,44 @@
+name: tests
+
+on:
+  push:
+    branches: [ master, main ]
+  pull_request:
+    branches: [ master, main ]
+
+env:
+  FORCE_COLOR: 1
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --frozen
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+
+  mypy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --frozen
+      - run: uv run mypy .
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python:
+          - "3.12"
+          - "3.13"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --frozen
+      - run: uv run pytest -vv --cov=axio_tools_docker --cov-report=term-missing

axio_tools_docker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Axio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

axio_tools_docker-0.1.0/Makefile

@@ -0,0 +1,16 @@
+.PHONY: fmt lint typecheck test all
+
+fmt:
+	uv run ruff format src/ tests/
+	uv run ruff check --fix src/ tests/
+
+lint:
+	uv run ruff check src/ tests/
+
+typecheck:
+	uv run mypy src/
+
+test:
+	uv run pytest tests/ -v
+
+all: fmt lint typecheck test

axio_tools_docker-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: axio-tools-docker
+Version: 0.1.0
+Summary: Docker sandbox tools for Axio
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: axio

axio_tools_docker-0.1.0/README.md

@@ -0,0 +1,15 @@
+# axio-tools-docker
+
+Docker sandbox tools for Axio.
+
+Part of the [axio-agent](https://github.com/axio-agent) ecosystem.
+
+## Installation
+
+```bash
+pip install axio-tools-docker
+```
+
+## License
+
+MIT

axio_tools_docker-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "axio-tools-docker"
+version = "0.1.0"
+description = "Docker sandbox tools for Axio"
+requires-python = ">=3.12"
+license = {text = "MIT"}
+dependencies = ["axio"]
+
+[project.entry-points."axio.tools.settings"]
+docker = "axio_tools_docker.plugin:DockerPlugin"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/axio_tools_docker"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 119
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+strict = true
+python_version = "3.12"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "mypy>=1.14", "ruff>=0.9"]

axio_tools_docker-0.1.0/src/axio_tools_docker/__init__.py

@@ -0,0 +1,7 @@
+"""Docker sandbox tools for Axio."""
+
+from .config import SandboxConfig
+from .manager import SandboxManager
+from .plugin import DockerPlugin
+
+__all__ = ["DockerPlugin", "SandboxConfig", "SandboxManager"]

axio_tools_docker-0.1.0/src/axio_tools_docker/config.py

@@ -0,0 +1,46 @@
+"""SandboxConfig: frozen dataclass for Docker sandbox parameters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class SandboxConfig:
+    """Configuration for a Docker sandbox container."""
+
+    image: str = "python:latest"
+    memory: str = "256m"
+    cpus: str = "1.0"
+    network: bool = False
+    workdir: str = "/workspace"
+
+    def to_dict(self) -> dict[str, str]:
+        """Serialize to flat string dict for config DB persistence.
+
+        Only non-default values are included.
+        """
+        defaults = SandboxConfig()
+        result: dict[str, str] = {}
+        if self.image != defaults.image:
+            result["image"] = self.image
+        if self.memory != defaults.memory:
+            result["memory"] = self.memory
+        if self.cpus != defaults.cpus:
+            result["cpus"] = self.cpus
+        if self.network != defaults.network:
+            result["network"] = str(self.network)
+        if self.workdir != defaults.workdir:
+            result["workdir"] = self.workdir
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict[str, str]) -> SandboxConfig:
+        """Deserialize from flat string dict."""
+        return cls(
+            image=data.get("image", "python:latest"),
+            memory=data.get("memory", "256m"),
+            cpus=data.get("cpus", "1.0"),
+            network=data["network"].lower() in ("true", "1", "yes") if "network" in data else False,
+            workdir=data.get("workdir", "/workspace"),
+        )

axio_tools_docker-0.1.0/src/axio_tools_docker/handler.py

@@ -0,0 +1,73 @@
+"""Dynamic ToolHandler builders for Docker sandbox tools."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from axio.tool import ToolHandler
+
+from .manager import SandboxManager
+
+
+def build_sandbox_exec(manager: SandboxManager) -> type[ToolHandler]:
+    """Create a ToolHandler that executes commands in the sandbox."""
+
+    class SandboxExecHandler(ToolHandler):
+        """Execute a shell command inside a Docker sandbox container.
+        Returns combined stdout/stderr. Non-zero exit codes are reported.
+        Use for running code, tests, or CLI tools in an isolated environment."""
+
+        command: str
+        timeout: int = 30
+
+        _manager: ClassVar[SandboxManager]
+
+        async def __call__(self) -> str:
+            if not self._manager.docker_available():
+                return "Error: Docker is not installed or not on PATH"
+            return await self._manager.exec(self.command, timeout=self.timeout)
+
+    SandboxExecHandler._manager = manager
+    return SandboxExecHandler
+
+
+def build_sandbox_write(manager: SandboxManager) -> type[ToolHandler]:
+    """Create a ToolHandler that writes files in the sandbox."""
+
+    class SandboxWriteHandler(ToolHandler):
+        """Write content to a file inside the Docker sandbox container.
+        Creates parent directories as needed. Use for placing source code,
+        config files, or test data in the sandbox."""
+
+        path: str
+        content: str
+
+        _manager: ClassVar[SandboxManager]
+
+        async def __call__(self) -> str:
+            if not self._manager.docker_available():
+                return "Error: Docker is not installed or not on PATH"
+            return await self._manager.write_file(self.path, self.content)
+
+    SandboxWriteHandler._manager = manager
+    return SandboxWriteHandler
+
+
+def build_sandbox_read(manager: SandboxManager) -> type[ToolHandler]:
+    """Create a ToolHandler that reads files from the sandbox."""
+
+    class SandboxReadHandler(ToolHandler):
+        """Read the contents of a file from the Docker sandbox container.
+        Returns the full file content as text."""
+
+        path: str
+
+        _manager: ClassVar[SandboxManager]
+
+        async def __call__(self) -> str:
+            if not self._manager.docker_available():
+                return "Error: Docker is not installed or not on PATH"
+            return await self._manager.read_file(self.path)
+
+    SandboxReadHandler._manager = manager
+    return SandboxReadHandler

axio_tools_docker-0.1.0/src/axio_tools_docker/manager.py

@@ -0,0 +1,158 @@
+"""SandboxManager: Docker container lifecycle for sandbox execution."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import shutil
+
+from .config import SandboxConfig
+
+logger = logging.getLogger(__name__)
+
+
+class SandboxManager:
+    """Manages a session-persistent Docker container for sandboxed execution."""
+
+    def __init__(self) -> None:
+        self.config = SandboxConfig()
+        self._container_id: str | None = None
+        self._lock = asyncio.Lock()
+
+    @property
+    def container_running(self) -> bool:
+        """Whether a sandbox container is currently active."""
+        return self._container_id is not None
+
+    @staticmethod
+    def docker_available() -> bool:
+        """Check whether the docker CLI is on PATH."""
+        return shutil.which("docker") is not None
+
+    async def _create_container(self) -> str:
+        """Create a new detached container and return its ID."""
+        cmd: list[str] = [
+            "docker",
+            "run",
+            "-d",
+            "--memory",
+            self.config.memory,
+            "--cpus",
+            self.config.cpus,
+            "-w",
+            self.config.workdir,
+        ]
+        if not self.config.network:
+            cmd.extend(["--network", "none"])
+        cmd.extend([self.config.image, "sleep", "infinity"])
+
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, stderr = await proc.communicate()
+        if proc.returncode != 0:
+            raise RuntimeError(f"Failed to create container: {stderr.decode().strip()}")
+        container_id = stdout.decode().strip()[:12]
+        logger.info("Created sandbox container %s (image=%s)", container_id, self.config.image)
+        return container_id
+
+    async def _ensure_container(self) -> str:
+        """Return the running container ID, creating one if needed."""
+        if self._container_id is not None:
+            return self._container_id
+        async with self._lock:
+            if self._container_id is not None:
+                return self._container_id
+            self._container_id = await self._create_container()
+            return self._container_id
+
+    async def exec(self, command: str, timeout: int = 30) -> str:
+        """Execute a shell command inside the container."""
+        container_id = await self._ensure_container()
+        proc = await asyncio.create_subprocess_exec(
+            "docker",
+            "exec",
+            container_id,
+            "sh",
+            "-c",
+            command,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        try:
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+        except TimeoutError:
+            proc.kill()
+            return f"[timeout after {timeout}s]"
+
+        output = ""
+        if stdout:
+            output += stdout.decode()
+        if stderr:
+            output += f"\n[stderr]\n{stderr.decode()}"
+        if proc.returncode != 0:
+            output += f"\n[exit code: {proc.returncode}]"
+        return output.strip() or "(no output)"
+
+    async def write_file(self, path: str, content: str) -> str:
+        """Write content to a file inside the container via stdin piping."""
+        container_id = await self._ensure_container()
+        proc = await asyncio.create_subprocess_exec(
+            "docker",
+            "exec",
+            "-i",
+            container_id,
+            "sh",
+            "-c",
+            f"cat > {path}",
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, stderr = await proc.communicate(input=content.encode())
+        if proc.returncode != 0:
+            return f"Error writing {path}: {stderr.decode().strip()}"
+        return f"Wrote {path}"
+
+    async def read_file(self, path: str) -> str:
+        """Read a file from inside the container."""
+        container_id = await self._ensure_container()
+        proc = await asyncio.create_subprocess_exec(
+            "docker",
+            "exec",
+            container_id,
+            "cat",
+            path,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, stderr = await proc.communicate()
+        if proc.returncode != 0:
+            return f"Error reading {path}: {stderr.decode().strip()}"
+        return stdout.decode()
+
+    async def recreate(self) -> str:
+        """Destroy the current container and create a fresh one."""
+        await self.close()
+        return await self._ensure_container()
+
+    async def close(self) -> None:
+        """Stop and remove the container if running."""
+        if self._container_id is None:
+            return
+        container_id = self._container_id
+        self._container_id = None
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                "docker",
+                "rm",
+                "-f",
+                container_id,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            await proc.communicate()
+        except Exception:
+            logger.warning("Failed to remove container %s", container_id, exc_info=True)

axio_tools_docker-0.1.0/src/axio_tools_docker/plugin.py

@@ -0,0 +1,87 @@
+"""DockerPlugin: ToolsPlugin implementation for Docker sandbox."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from axio.tool import Tool
+
+from .config import SandboxConfig
+from .handler import build_sandbox_exec, build_sandbox_read, build_sandbox_write
+from .manager import SandboxManager
+
+logger = logging.getLogger(__name__)
+
+
+class DockerPlugin:
+    """Dynamic tool provider for Docker sandbox execution.
+
+    Discovered via the ``axio.tools.settings`` entry point group.
+    The TUI interacts with this class through the ToolsPlugin protocol.
+    """
+
+    def __init__(self) -> None:
+        self._manager = SandboxManager()
+        self._tools: list[Tool] = []
+        self._config: Any = None
+        self._global_config: Any = None
+
+    @property
+    def label(self) -> str:
+        return "Docker Sandbox"
+
+    async def init(self, config: Any = None, global_config: Any = None) -> None:
+        self._config = config
+        self._global_config = global_config
+        await self._load_config()
+        self._build_tools()
+
+    async def _load_config(self) -> None:
+        """Load sandbox config from DB (project first, then global)."""
+        for db in (self._config, self._global_config):
+            if db is None:
+                continue
+            raw = await db.get_prefix("docker.")
+            if not raw:
+                continue
+            data: dict[str, str] = {}
+            for full_key, value in raw.items():
+                parts = full_key.split(".", 1)
+                if len(parts) == 2:
+                    data[parts[1]] = value
+            if data:
+                self._manager.config = SandboxConfig.from_dict(data)
+                return
+
+    def _build_tools(self) -> None:
+        """Create the three sandbox tools."""
+        self._tools = [
+            Tool(
+                name="sandbox_exec",
+                description="Execute a shell command inside a Docker sandbox container",
+                handler=build_sandbox_exec(self._manager),
+            ),
+            Tool(
+                name="sandbox_write",
+                description="Write content to a file inside the Docker sandbox container",
+                handler=build_sandbox_write(self._manager),
+            ),
+            Tool(
+                name="sandbox_read",
+                description="Read a file from the Docker sandbox container",
+                handler=build_sandbox_read(self._manager),
+            ),
+        ]
+
+    @property
+    def all_tools(self) -> list[Tool]:
+        return self._tools
+
+    def settings_screen(self) -> Any:
+        from .settings import DockerSettingsScreen
+
+        return DockerSettingsScreen(self._manager, config=self._config, global_config=self._global_config)
+
+    async def close(self) -> None:
+        await self._manager.close()

axio_tools_docker-0.1.0/src/axio_tools_docker/settings.py

@@ -0,0 +1,170 @@
+"""TUI settings screen for Docker sandbox configuration."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+try:
+    from textual.app import ComposeResult
+    from textual.binding import Binding
+    from textual.containers import Container, Horizontal
+    from textual.screen import ModalScreen
+    from textual.widgets import Button, Checkbox, Input, Static
+
+    _HAS_TEXTUAL = True
+except ImportError:
+    _HAS_TEXTUAL = False
+
+if TYPE_CHECKING:
+    from .config import SandboxConfig
+    from .manager import SandboxManager
+
+
+if _HAS_TEXTUAL:
+
+    class DockerSettingsScreen(ModalScreen[None]):
+        """Settings screen for Docker sandbox configuration."""
+
+        BINDINGS = [Binding("escape", "cancel", "Cancel")]
+        CSS = """
+        DockerSettingsScreen { align: center middle; }
+        #docker-settings {
+            width: 70;
+            height: auto;
+            max-height: 90%;
+            border: heavy $accent;
+            background: $panel;
+            padding: 1 2;
+        }
+        #docker-settings Input { margin-bottom: 1; }
+        #docker-settings Checkbox { margin-bottom: 1; }
+        .docker-buttons { height: auto; margin-top: 1; }
+        .docker-buttons Button { margin: 0 1; }
+        .docker-container-actions { height: auto; margin-top: 1; margin-bottom: 1; }
+        .docker-container-actions Button { margin: 0 1; }
+        """
+
+        def __init__(
+            self,
+            manager: SandboxManager,
+            config: Any = None,
+            global_config: Any = None,
+        ) -> None:
+            super().__init__()
+            self._manager = manager
+            self._config = config
+            self._global_config = global_config
+
+        def compose(self) -> ComposeResult:
+            cfg = self._manager.config
+            docker_ok = self._manager.docker_available()
+            status = "[green]Docker available[/]" if docker_ok else "[red]Docker not found[/]"
+            running = self._manager.container_running
+
+            with Container(id="docker-settings"):
+                yield Static("[bold]Docker Sandbox Settings[/]")
+                yield Static(f"Status: {status}", id="docker-status")
+                yield Static(
+                    "Container: [green]running[/]" if running else "Container: [dim]stopped[/]",
+                    id="docker-container-status",
+                )
+                with Horizontal(classes="docker-container-actions"):
+                    yield Button("Prepare", id="btn-prepare", variant="success", disabled=running)
+                    yield Button("Stop", id="btn-stop", variant="error", disabled=not running)
+                    yield Button("Recreate", id="btn-recreate", variant="warning", disabled=not running)
+                yield Static("Image:")
+                yield Input(value=cfg.image, placeholder="e.g. python:latest", id="docker-image")
+                yield Static("Memory limit:")
+                yield Input(value=cfg.memory, placeholder="e.g. 256m", id="docker-memory")
+                yield Static("CPU limit:")
+                yield Input(value=cfg.cpus, placeholder="e.g. 1.0", id="docker-cpus")
+                yield Checkbox("Allow network access", cfg.network, id="docker-network")
+                with Horizontal(classes="docker-buttons"):
+                    yield Button("Save", id="btn-save", variant="primary")
+                    yield Button("Cancel", id="btn-cancel")
+
+        def on_mount(self) -> None:
+            self.query_one("#docker-image", Input).focus()
+
+        def _update_container_status(self) -> None:
+            running = self._manager.container_running
+            status_widget = self.query_one("#docker-container-status", Static)
+            status_widget.update(
+                "Container: [green]running[/]" if running else "Container: [dim]stopped[/]",
+            )
+            self.query_one("#btn-prepare", Button).disabled = running
+            self.query_one("#btn-stop", Button).disabled = not running
+            self.query_one("#btn-recreate", Button).disabled = not running
+
+        def on_button_pressed(self, event: Button.Pressed) -> None:
+            if event.button.id == "btn-cancel":
+                self.dismiss(None)
+            elif event.button.id == "btn-save":
+                self._save()
+            elif event.button.id == "btn-prepare":
+                self.app.run_worker(self._do_prepare())
+            elif event.button.id == "btn-stop":
+                self.app.run_worker(self._do_stop())
+            elif event.button.id == "btn-recreate":
+                self.app.run_worker(self._do_recreate())
+
+        async def _do_prepare(self) -> None:
+            self.notify("Preparing container...")
+            try:
+                await self._manager._ensure_container()
+                self._update_container_status()
+                self.notify("Container ready")
+            except RuntimeError as exc:
+                self.notify(str(exc), severity="error")
+
+        async def _do_stop(self) -> None:
+            await self._manager.close()
+            self._update_container_status()
+            self.notify("Container stopped")
+
+        async def _do_recreate(self) -> None:
+            self.notify("Recreating container...")
+            try:
+                await self._manager.recreate()
+                self._update_container_status()
+                self.notify("Container recreated")
+            except RuntimeError as exc:
+                self.notify(str(exc), severity="error")
+                self._update_container_status()
+
+        def _save(self) -> None:
+            from .config import SandboxConfig
+
+            image = self.query_one("#docker-image", Input).value.strip()
+            memory = self.query_one("#docker-memory", Input).value.strip()
+            cpus = self.query_one("#docker-cpus", Input).value.strip()
+            network = self.query_one("#docker-network", Checkbox).value
+
+            cfg = SandboxConfig(
+                image=image or "python:latest",
+                memory=memory or "256m",
+                cpus=cpus or "1.0",
+                network=network,
+            )
+            self._manager.config = cfg
+            self.app.run_worker(self._persist(cfg))
+            self.dismiss(None)
+
+        async def _persist(self, cfg: SandboxConfig) -> None:
+            db = self._config or self._global_config
+            if db is None:
+                return
+            await db.delete_prefix("docker.")
+            for key, value in cfg.to_dict().items():
+                await db.set(f"docker.{key}", value)
+
+        def action_cancel(self) -> None:
+            self.dismiss(None)
+
+else:
+
+    class DockerSettingsScreen:  # type: ignore[no-redef]
+        """Stub when textual is not installed."""
+
+        def __init__(self, *args: Any, **kwargs: Any) -> None:
+            raise ImportError("textual is required for Docker settings screen")

axio_tools_docker-0.1.0/tests/test_config.py

@@ -0,0 +1,53 @@
+"""Tests for SandboxConfig."""
+
+from __future__ import annotations
+
+import pytest
+from axio_tools_docker.config import SandboxConfig
+
+
+def test_defaults() -> None:
+    cfg = SandboxConfig()
+    assert cfg.image == "python:latest"
+    assert cfg.memory == "256m"
+    assert cfg.cpus == "1.0"
+    assert cfg.network is False
+    assert cfg.workdir == "/workspace"
+
+
+def test_frozen() -> None:
+    cfg = SandboxConfig()
+    with pytest.raises(AttributeError):
+        cfg.image = "ubuntu"  # type: ignore[misc]
+
+
+def test_to_dict_omits_defaults() -> None:
+    cfg = SandboxConfig()
+    assert cfg.to_dict() == {}
+
+
+def test_to_dict_non_defaults() -> None:
+    cfg = SandboxConfig(image="ubuntu:22.04", memory="512m", network=True)
+    d = cfg.to_dict()
+    assert d == {"image": "ubuntu:22.04", "memory": "512m", "network": "True"}
+
+
+def test_roundtrip() -> None:
+    original = SandboxConfig(image="node:20", cpus="2.0", workdir="/app", network=True)
+    restored = SandboxConfig.from_dict(original.to_dict())
+    assert restored == original
+
+
+def test_from_dict_empty() -> None:
+    cfg = SandboxConfig.from_dict({})
+    assert cfg == SandboxConfig()
+
+
+def test_network_bool_serialization() -> None:
+    for truthy in ("True", "true", "1", "yes"):
+        cfg = SandboxConfig.from_dict({"network": truthy})
+        assert cfg.network is True
+
+    for falsy in ("False", "false", "0", "no"):
+        cfg = SandboxConfig.from_dict({"network": falsy})
+        assert cfg.network is False

axio_tools_docker-0.1.0/tests/test_handler.py

@@ -0,0 +1,99 @@
+"""Tests for handler builders."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+from axio_tools_docker.handler import build_sandbox_exec, build_sandbox_read, build_sandbox_write
+from axio_tools_docker.manager import SandboxManager
+
+
+async def test_exec_handler_forwards_to_manager() -> None:
+    manager = SandboxManager()
+    manager.exec = AsyncMock(return_value="output")  # type: ignore[method-assign]
+
+    handler_cls = build_sandbox_exec(manager)
+    instance = handler_cls(command="echo hi", timeout=10)
+
+    with patch.object(SandboxManager, "docker_available", return_value=True):
+        result = await instance()
+
+    assert result == "output"
+    manager.exec.assert_awaited_once_with("echo hi", timeout=10)
+
+
+async def test_write_handler_forwards_to_manager() -> None:
+    manager = SandboxManager()
+    manager.write_file = AsyncMock(return_value="Wrote /workspace/test.py")  # type: ignore[method-assign]
+
+    handler_cls = build_sandbox_write(manager)
+    instance = handler_cls(path="/workspace/test.py", content="print('hi')")
+
+    with patch.object(SandboxManager, "docker_available", return_value=True):
+        result = await instance()
+
+    assert result == "Wrote /workspace/test.py"
+    manager.write_file.assert_awaited_once_with("/workspace/test.py", "print('hi')")
+
+
+async def test_read_handler_forwards_to_manager() -> None:
+    manager = SandboxManager()
+    manager.read_file = AsyncMock(return_value="file content")  # type: ignore[method-assign]
+
+    handler_cls = build_sandbox_read(manager)
+    instance = handler_cls(path="/workspace/test.py")
+
+    with patch.object(SandboxManager, "docker_available", return_value=True):
+        result = await instance()
+
+    assert result == "file content"
+    manager.read_file.assert_awaited_once_with("/workspace/test.py")
+
+
+async def test_exec_handler_returns_error_when_docker_missing() -> None:
+    manager = SandboxManager()
+    handler_cls = build_sandbox_exec(manager)
+    instance = handler_cls(command="echo hi")
+
+    with patch.object(SandboxManager, "docker_available", return_value=False):
+        result = await instance()
+
+    assert "not installed" in result
+
+
+async def test_write_handler_returns_error_when_docker_missing() -> None:
+    manager = SandboxManager()
+    handler_cls = build_sandbox_write(manager)
+    instance = handler_cls(path="/test", content="x")
+
+    with patch.object(SandboxManager, "docker_available", return_value=False):
+        result = await instance()
+
+    assert "not installed" in result
+
+
+async def test_read_handler_returns_error_when_docker_missing() -> None:
+    manager = SandboxManager()
+    handler_cls = build_sandbox_read(manager)
+    instance = handler_cls(path="/test")
+
+    with patch.object(SandboxManager, "docker_available", return_value=False):
+        result = await instance()
+
+    assert "not installed" in result
+
+
+def test_exec_handler_is_tool_handler_subclass() -> None:
+    from axio.tool import ToolHandler
+
+    manager = SandboxManager()
+    handler_cls = build_sandbox_exec(manager)
+    assert issubclass(handler_cls, ToolHandler)
+
+
+def test_handlers_have_docstrings() -> None:
+    manager = SandboxManager()
+    for builder in (build_sandbox_exec, build_sandbox_read, build_sandbox_write):
+        handler_cls = builder(manager)
+        assert handler_cls.__doc__ is not None
+        assert len(handler_cls.__doc__) > 10

axio_tools_docker-0.1.0/tests/test_manager.py

@@ -0,0 +1,257 @@
+"""Tests for SandboxManager."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from axio_tools_docker.config import SandboxConfig
+from axio_tools_docker.manager import SandboxManager
+
+
+def _mock_proc(stdout: bytes = b"", stderr: bytes = b"", returncode: int = 0) -> MagicMock:
+    proc = MagicMock()
+    proc.communicate = AsyncMock(return_value=(stdout, stderr))
+    proc.returncode = returncode
+    proc.kill = MagicMock()
+    return proc
+
+
+@pytest.fixture()
+def manager() -> SandboxManager:
+    return SandboxManager()
+
+
+async def test_docker_available_true() -> None:
+    with patch("axio_tools_docker.manager.shutil.which", return_value="/usr/bin/docker"):
+        assert SandboxManager.docker_available() is True
+
+
+async def test_docker_available_false() -> None:
+    with patch("axio_tools_docker.manager.shutil.which", return_value=None):
+        assert SandboxManager.docker_available() is False
+
+
+async def test_container_created_once(manager: SandboxManager) -> None:
+    """Container is created on first call and reused."""
+    create_proc = _mock_proc(stdout=b"abc123def456xyz\n")
+    exec_proc = _mock_proc(stdout=b"hello\n")
+
+    call_count = 0
+
+    async def mock_subprocess(*args: object, **kwargs: object) -> MagicMock:
+        nonlocal call_count
+        call_count += 1
+        if call_count == 1:
+            return create_proc
+        return exec_proc
+
+    with patch("axio_tools_docker.manager.asyncio.create_subprocess_exec", side_effect=mock_subprocess):
+        result1 = await manager.exec("echo hello")
+        result2 = await manager.exec("echo hello")
+
+    assert result1 == "hello"
+    assert result2 == "hello"
+    # 1 create + 2 exec = 3 total calls
+    assert call_count == 3
+
+
+async def test_exec_stdout_stderr(manager: SandboxManager) -> None:
+    create_proc = _mock_proc(stdout=b"container123\n")
+    exec_proc = _mock_proc(stdout=b"out\n", stderr=b"err\n", returncode=0)
+
+    calls = [create_proc, exec_proc]
+
+    async def mock_subprocess(*args: object, **kwargs: object) -> MagicMock:
+        return calls.pop(0)
+
+    with patch("axio_tools_docker.manager.asyncio.create_subprocess_exec", side_effect=mock_subprocess):
+        result = await manager.exec("cmd")
+
+    assert "out" in result
+    assert "[stderr]" in result
+    assert "err" in result
+
+
+async def test_exec_nonzero_exit(manager: SandboxManager) -> None:
+    create_proc = _mock_proc(stdout=b"container123\n")
+    exec_proc = _mock_proc(stdout=b"", stderr=b"fail\n", returncode=1)
+
+    calls = [create_proc, exec_proc]
+
+    async def mock_subprocess(*args: object, **kwargs: object) -> MagicMock:
+        return calls.pop(0)
+
+    with patch("axio_tools_docker.manager.asyncio.create_subprocess_exec", side_effect=mock_subprocess):
+        result = await manager.exec("bad_cmd")
+
+    assert "[exit code: 1]" in result
+
+
+async def test_exec_timeout(manager: SandboxManager) -> None:
+    create_proc = _mock_proc(stdout=b"container123\n")
+    timeout_proc = MagicMock()
+    timeout_proc.communicate = AsyncMock(side_effect=TimeoutError)
+    timeout_proc.kill = MagicMock()
+
+    calls = [create_proc, timeout_proc]
+
+    async def mock_subprocess(*args: object, **kwargs: object) -> MagicMock:
+        return calls.pop(0)
+
+    with (
+        patch("axio_tools_docker.manager.asyncio.create_subprocess_exec", side_effect=mock_subprocess),
+        patch("axio_tools_docker.manager.asyncio.wait_for", side_effect=TimeoutError),
+    ):
+        result = await manager.exec("sleep 100", timeout=5)
+
+    assert "[timeout after 5s]" in result
+
+
+async def test_write_file(manager: SandboxManager) -> None:
+    create_proc = _mock_proc(stdout=b"container123\n")
+    write_proc = _mock_proc()
+
+    calls = [create_proc, write_proc]
+
+    async def mock_subprocess(*args: object, **kwargs: object) -> MagicMock:
+        return calls.pop(0)
+
+    with patch("axio_tools_docker.manager.asyncio.create_subprocess_exec", side_effect=mock_subprocess):
+        result = await manager.write_file("/workspace/test.py", "print('hi')")
+
+    assert "Wrote /workspace/test.py" in result
+    # Verify stdin was passed
+    write_proc.communicate.assert_awaited_once_with(input=b"print('hi')")
+
+
+async def test_read_file(manager: SandboxManager) -> None:
+    create_proc = _mock_proc(stdout=b"container123\n")
+    read_proc = _mock_proc(stdout=b"file content here")
+
+    calls = [create_proc, read_proc]
+
+    async def mock_subprocess(*args: object, **kwargs: object) -> MagicMock:
+        return calls.pop(0)
+
+    with patch("axio_tools_docker.manager.asyncio.create_subprocess_exec", side_effect=mock_subprocess):
+        result = await manager.read_file("/workspace/test.py")
+
+    assert result == "file content here"
+
+
+async def test_close_removes_container(manager: SandboxManager) -> None:
+    create_proc = _mock_proc(stdout=b"container123\n")
+    rm_proc = _mock_proc()
+
+    calls = [create_proc, rm_proc]
+    captured_args: list[tuple[object, ...]] = []
+
+    async def mock_subprocess(*args: object, **kwargs: object) -> MagicMock:
+        captured_args.append(args)
+        return calls.pop(0)
+
+    with patch("axio_tools_docker.manager.asyncio.create_subprocess_exec", side_effect=mock_subprocess):
+        await manager._ensure_container()
+        await manager.close()
+
+    # Second call should be docker rm -f
+    assert "rm" in captured_args[1]
+    assert "-f" in captured_args[1]
+    assert manager._container_id is None
+
+
+async def test_close_noop_without_container(manager: SandboxManager) -> None:
+    """close() is a no-op when no container was ever created."""
+    await manager.close()  # Should not raise
+
+
+async def test_creation_failure_raises(manager: SandboxManager) -> None:
+    fail_proc = _mock_proc(stderr=b"no such image", returncode=1)
+
+    async def mock_subprocess(*args: object, **kwargs: object) -> MagicMock:
+        return fail_proc
+
+    with (
+        patch("axio_tools_docker.manager.asyncio.create_subprocess_exec", side_effect=mock_subprocess),
+        pytest.raises(RuntimeError, match="Failed to create container"),
+    ):
+        await manager.exec("echo hi")
+
+
+async def test_container_running_property(manager: SandboxManager) -> None:
+    """container_running reflects internal state."""
+    assert manager.container_running is False
+
+    create_proc = _mock_proc(stdout=b"container123\n")
+
+    async def mock_subprocess(*args: object, **kwargs: object) -> MagicMock:
+        return create_proc
+
+    with patch("axio_tools_docker.manager.asyncio.create_subprocess_exec", side_effect=mock_subprocess):
+        await manager._ensure_container()
+
+    assert manager.container_running is True
+    manager._container_id = None
+    assert manager.container_running is False
+
+
+async def test_recreate_destroys_and_creates(manager: SandboxManager) -> None:
+    """recreate() closes the old container and creates a new one."""
+    create_proc_1 = _mock_proc(stdout=b"old_container\n")
+    rm_proc = _mock_proc()
+    create_proc_2 = _mock_proc(stdout=b"new_container\n")
+
+    calls = [create_proc_1, rm_proc, create_proc_2]
+    captured_args: list[tuple[object, ...]] = []
+
+    async def mock_subprocess(*args: object, **kwargs: object) -> MagicMock:
+        captured_args.append(args)
+        return calls.pop(0)
+
+    with patch("axio_tools_docker.manager.asyncio.create_subprocess_exec", side_effect=mock_subprocess):
+        await manager._ensure_container()
+        assert manager._container_id == "old_containe"  # truncated to 12 chars
+        new_id = await manager.recreate()
+
+    assert new_id == "new_containe"
+    assert manager._container_id == "new_containe"
+    # Second call was docker rm -f
+    assert "rm" in captured_args[1]
+    assert "-f" in captured_args[1]
+
+
+async def test_recreate_without_running_container(manager: SandboxManager) -> None:
+    """recreate() creates a container even when none was running."""
+    create_proc = _mock_proc(stdout=b"fresh_container\n")
+
+    async def mock_subprocess(*args: object, **kwargs: object) -> MagicMock:
+        return create_proc
+
+    with patch("axio_tools_docker.manager.asyncio.create_subprocess_exec", side_effect=mock_subprocess):
+        new_id = await manager.recreate()
+
+    assert new_id == "fresh_contai"
+    assert manager.container_running is True
+
+
+async def test_config_applied(manager: SandboxManager) -> None:
+    """Container creation uses config values."""
+    manager.config = SandboxConfig(image="ubuntu:22.04", memory="512m", cpus="2.0", network=True)
+    create_proc = _mock_proc(stdout=b"container123\n")
+
+    captured_args: list[tuple[object, ...]] = []
+
+    async def mock_subprocess(*args: object, **kwargs: object) -> MagicMock:
+        captured_args.append(args)
+        return create_proc
+
+    with patch("axio_tools_docker.manager.asyncio.create_subprocess_exec", side_effect=mock_subprocess):
+        await manager._ensure_container()
+
+    create_args = captured_args[0]
+    assert "ubuntu:22.04" in create_args
+    assert "512m" in create_args
+    assert "2.0" in create_args
+    # network=True means --network none should NOT be present
+    assert "--network" not in create_args

axio_tools_docker-0.1.0/tests/test_plugin.py

@@ -0,0 +1,85 @@
+"""Tests for DockerPlugin."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+from axio_tools_docker.config import SandboxConfig
+from axio_tools_docker.plugin import DockerPlugin
+
+
+async def test_init_without_config() -> None:
+    plugin = DockerPlugin()
+    await plugin.init()
+    assert len(plugin.all_tools) == 3
+
+
+async def test_init_with_config_db() -> None:
+    mock_db = MagicMock()
+    mock_db.get_prefix = AsyncMock(
+        return_value={
+            "docker.image": "ubuntu:22.04",
+            "docker.memory": "512m",
+        },
+    )
+
+    plugin = DockerPlugin()
+    await plugin.init(config=mock_db)
+
+    assert plugin._manager.config.image == "ubuntu:22.04"
+    assert plugin._manager.config.memory == "512m"
+    mock_db.get_prefix.assert_awaited_once_with("docker.")
+
+
+async def test_init_project_takes_priority() -> None:
+    project_db = MagicMock()
+    project_db.get_prefix = AsyncMock(return_value={"docker.image": "node:20"})
+
+    global_db = MagicMock()
+    global_db.get_prefix = AsyncMock(return_value={"docker.image": "python:3.11"})
+
+    plugin = DockerPlugin()
+    await plugin.init(config=project_db, global_config=global_db)
+
+    assert plugin._manager.config.image == "node:20"
+
+
+async def test_init_falls_back_to_global() -> None:
+    project_db = MagicMock()
+    project_db.get_prefix = AsyncMock(return_value={})
+
+    global_db = MagicMock()
+    global_db.get_prefix = AsyncMock(return_value={"docker.image": "python:3.11"})
+
+    plugin = DockerPlugin()
+    await plugin.init(config=project_db, global_config=global_db)
+
+    assert plugin._manager.config.image == "python:3.11"
+
+
+async def test_all_tools_returns_three() -> None:
+    plugin = DockerPlugin()
+    await plugin.init()
+
+    tools = plugin.all_tools
+    assert len(tools) == 3
+    names = {t.name for t in tools}
+    assert names == {"sandbox_exec", "sandbox_write", "sandbox_read"}
+
+
+async def test_close_delegates_to_manager() -> None:
+    plugin = DockerPlugin()
+    plugin._manager.close = AsyncMock()  # type: ignore[method-assign]
+    await plugin.close()
+    plugin._manager.close.assert_awaited_once()
+
+
+def test_label() -> None:
+    plugin = DockerPlugin()
+    assert plugin.label == "Docker Sandbox"
+
+
+async def test_default_config_when_no_db() -> None:
+    plugin = DockerPlugin()
+    await plugin.init()
+    assert plugin._manager.config == SandboxConfig()