axio-tools-docker 0.1.0__py3-none-any.whl

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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+axio_tools_docker/__init__.py,sha256=VlydIu0yrzEObMaquRpTTRRqyPIf2BgUJcmZtfRUJRs,204
+axio_tools_docker/config.py,sha256=5SeqSnvszaVtpSJ_JU_cap5EC_suqnX8VH47oQ-W0RA,1546
+axio_tools_docker/handler.py,sha256=gRXEVU5_r3RvzTkzEdaBwk_lYNeXT8xsIMy70wgZNaw,2472
+axio_tools_docker/manager.py,sha256=RnmDM66doxYynTL4rnEAKa_h7lZ1Bqr0VCpDxVRwOIY,5390
+axio_tools_docker/plugin.py,sha256=XSYx-55MGfYNcxf6FJ-hZOiunuijMJRFBwimuUcYAp8,2824
+axio_tools_docker/settings.py,sha256=68GsTim219YyK9-2ono2E5x6Cf9-EHidLxS3VomcJyY,6914
+axio_tools_docker-0.1.0.dist-info/METADATA,sha256=b2FyGPX2a6-s0kaPQ1YaETiK-lkS0zhVoYnCKixdpbA,179
+axio_tools_docker-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+axio_tools_docker-0.1.0.dist-info/entry_points.txt,sha256=IMGBwH0xSL1wAvarV1r8s8sVMW4NjgxW-_6S8uywOys,69
+axio_tools_docker-0.1.0.dist-info/licenses/LICENSE,sha256=ddOkAXgIM2QzvUDPydeis3tJXfhHxt1wKnmGjbwPPxQ,1074
+axio_tools_docker-0.1.0.dist-info/RECORD,,

axio_tools_docker-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

axio_tools_docker-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[axio.tools.settings]
+docker = axio_tools_docker.plugin:DockerPlugin

axio_tools_docker-0.1.0.dist-info/licenses/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.