regcode 0.1.0__py3-none-any.whl

regcode/sandbox.py

@@ -0,0 +1,382 @@
+"""Sandbox for secure, isolated code execution.
+
+Provides resource-limited execution environments with:
+- Process-level isolation via resource limits (rlimit)
+- Network restriction (can be toggled)
+- Time limits
+- Memory limits
+- Disk I/O sandboxing (chroot-like with temp dir)
+- Environment variable isolation
+
+Designed as a thin layer over Python's subprocess + resource module.
+Architecture supports swapping in actual microVMs (Firecracker, gVisor) later.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class SandboxConfig:
+    """Configuration for the execution sandbox."""
+
+    # Time limits
+    max_timeout: float = 30.0  # Max execution time in seconds
+    default_timeout: float = 15.0
+
+    # Memory limits (in bytes)
+    max_memory_mb: int = 256
+
+    # Disk limits (in bytes)
+    max_disk_mb: int = 50
+
+    # Network restriction
+    restrict_network: bool = True
+
+    # Max output size
+    max_output_bytes: int = 65536
+
+    # Working directory (sandbox root)
+    sandbox_dir: Path | None = None
+
+    # Additional environment variables
+    extra_env: dict[str, str] = field(default_factory=dict)
+
+    # Whether to allow subprocess execution
+    allow_subprocess: bool = False
+
+    # Allowed files (whitelist)
+    allowed_files: list[str] = field(default_factory=list)
+
+
+class SandboxError(Exception):
+    """Raised when sandbox execution fails."""
+
+    def __init__(
+        self,
+        message: str,
+        stdout: str = "",
+        stderr: str = "",
+        exit_code: int = -1,
+    ):
+        super().__init__(message)
+        self.stdout = stdout
+        self.stderr = stderr
+        self.exit_code = exit_code
+
+
+@dataclass
+class SandboxResult:
+    """Result from a sandboxed execution."""
+
+    stdout: str
+    stderr: str
+    exit_code: int
+    execution_time: float
+    memory_used_mb: float = 0.0
+
+    @property
+    def success(self) -> bool:
+        return self.exit_code == 0 and not self.stdout.startswith("SANDBOX_ERROR")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "stdout": self.stdout,
+            "stderr": self.stderr,
+            "exit_code": self.exit_code,
+            "execution_time": round(self.execution_time, 3),
+            "memory_used_mb": round(self.memory_used_mb, 2),
+            "success": self.success,
+        }
+
+
+class Sandbox:
+    """Resource-limited execution sandbox for code running.
+
+    Provides isolation using:
+    - Process resource limits (CPU, memory, file size)
+    - Temporary working directory
+    - Environment variable isolation
+    - Network restriction (optional)
+    - Timeout enforcement
+    - Output size limiting
+
+    Architecture note: Currently uses Python subprocess + resource module.
+    For production-grade isolation, swap in Firecracker microVMs or gVisor.
+    """
+
+    def __init__(self, config: SandboxConfig | None = None):
+        self.config = config or SandboxConfig()
+        self._sandbox_root: Path | None = None
+
+    @property
+    def sandbox_root(self) -> Path:
+        """Get or create the sandbox working directory."""
+        if self._sandbox_root is None:
+            base = self.config.sandbox_dir or Path(
+                tempfile.mkdtemp(prefix="regcode_sandbox_")
+            )
+            self._sandbox_root = base / f"session_{int(time.time())}"
+            self._sandbox_root.mkdir(parents=True, exist_ok=True)
+        return self._sandbox_root
+
+    def cleanup(self) -> None:
+        """Clean up sandbox resources."""
+        if self._sandbox_root and self._sandbox_root.exists():
+            shutil.rmtree(self._sandbox_root, ignore_errors=True)
+        self._sandbox_root = None
+
+    def __del__(self) -> None:
+        self.cleanup()
+
+    def run(
+        self,
+        command: list[str],
+        stdin: str | None = None,
+        timeout: float | None = None,
+    ) -> SandboxResult:
+        """Execute a command in the sandbox with resource limits.
+
+        Args:
+            command: Command and arguments to execute.
+            stdin: Optional stdin content.
+            timeout: Override timeout for this execution.
+
+        Returns:
+            SandboxResult with stdout, stderr, exit_code.
+        """
+        timeout = timeout or self.config.default_timeout
+
+        # Set up environment
+        env = self._build_env()
+
+        try:
+            process = subprocess.Popen(
+                command,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                cwd=str(self.sandbox_root),
+                env=env,
+            )
+
+            try:
+                stdout, stderr = process.communicate(
+                    input=stdin.encode() if stdin else None,
+                    timeout=timeout,
+                )
+            except subprocess.TimeoutExpired:
+                process.kill()
+                stdout, stderr = process.communicate()
+                return SandboxResult(
+                    stdout="SANDBOX_ERROR: Execution timed out",
+                    stderr=stderr.decode("utf-8", errors="replace"),
+                    exit_code=-1,
+                    execution_time=timeout,
+                )
+
+            # Decode and limit output
+            stdout_decoded = stdout.decode(
+                "utf-8", errors="replace"
+            )[: self.config.max_output_bytes]
+            stderr_decoded = stderr.decode(
+                "utf-8", errors="replace"
+            )[: self.config.max_output_bytes]
+
+        except FileNotFoundError:
+            return SandboxResult(
+                stdout=f"SANDBOX_ERROR: Command not found: {command[0]}",
+                stderr="",
+                exit_code=127,
+                execution_time=0,
+            )
+        except OSError as e:
+            return SandboxResult(
+                stdout=f"SANDBOX_ERROR: {str(e)}",
+                stderr="",
+                exit_code=1,
+                execution_time=0,
+            )
+
+        start_time = time.monotonic()
+        end_time = time.monotonic()
+        elapsed = end_time - start_time
+
+        # Check if output was truncated
+        truncated = len(stdout) > self.config.max_output_bytes
+
+        return SandboxResult(
+            stdout=stdout_decoded + (
+                " [output truncated]" if truncated else ""
+            ),
+            stderr=stderr_decoded,
+            exit_code=process.returncode,
+            execution_time=elapsed,
+        )
+
+    def run_python(
+        self,
+        code: str,
+        timeout: float | None = None,
+        stdin: str | None = None,
+    ) -> SandboxResult:
+        """Execute Python code in the sandbox.
+
+        Args:
+            code: Python code string to execute.
+            timeout: Override timeout.
+            stdin: Optional stdin.
+
+        Returns:
+            SandboxResult.
+        """
+        # Write code to a temporary file in the sandbox
+        script_path = self.sandbox_root / "sandbox_script.py"
+        script_path.write_text(code)
+
+        # Determine Python interpreter
+        python_cmd = shutil.which("python3") or shutil.which("python") or "python3"
+
+        return self.run([python_cmd, str(script_path)], stdin=stdin, timeout=timeout)
+
+    def run_shell(
+        self,
+        command: str,
+        timeout: float | None = None,
+    ) -> SandboxResult:
+        """Execute a shell command in the sandbox.
+
+        Args:
+            command: Shell command string.
+            timeout: Override timeout.
+
+        Returns:
+            SandboxResult.
+        """
+        return self.run(["bash", "-c", command], timeout=timeout)
+
+    def read_file(self, path: str) -> SandboxResult:
+        """Read a file from the sandbox filesystem.
+
+        Args:
+            path: Path to read.
+
+        Returns:
+            SandboxResult with file content.
+        """
+        sandbox_path = self.sandbox_root / path
+        try:
+            if not sandbox_path.exists():
+                return SandboxResult(
+                    stdout=f"File not found: {path}",
+                    stderr="",
+                    exit_code=1,
+                    execution_time=0,
+                )
+            content = sandbox_path.read_text()
+            return SandboxResult(
+                stdout=content,
+                stderr="",
+                exit_code=0,
+                execution_time=0,
+            )
+        except Exception as e:
+            return SandboxResult(
+                stdout=f"Error reading file: {str(e)}",
+                stderr="",
+                exit_code=1,
+                execution_time=0,
+            )
+
+    def write_file(self, path: str, content: str) -> SandboxResult:
+        """Write content to a file in the sandbox.
+
+        Args:
+            path: Path to write to.
+            content: Content to write.
+
+        Returns:
+            SandboxResult.
+        """
+        sandbox_path = self.sandbox_root / path
+        try:
+            sandbox_path.parent.mkdir(parents=True, exist_ok=True)
+            sandbox_path.write_text(content)
+            return SandboxResult(
+                stdout=f"Written {len(content)} bytes to {path}",
+                stderr="",
+                exit_code=0,
+                execution_time=0,
+            )
+        except Exception as e:
+            return SandboxResult(
+                stdout=f"Error writing file: {str(e)}",
+                stderr="",
+                exit_code=1,
+                execution_time=0,
+            )
+
+    def list_dir(self, path: str = ".") -> SandboxResult:
+        """List contents of a directory in the sandbox.
+
+        Args:
+            path: Directory path.
+
+        Returns:
+            SandboxResult with listing.
+        """
+        sandbox_path = self.sandbox_root / path
+        try:
+            if not sandbox_path.exists():
+                return SandboxResult(
+                    stdout=f"Directory not found: {path}",
+                    stderr="",
+                    exit_code=1,
+                    execution_time=0,
+                )
+            entries = sorted(sandbox_path.iterdir())
+            lines = []
+            for entry in entries:
+                marker = "/" if entry.is_dir() else ""
+                lines.append(f"{entry.name}{marker}")
+            return SandboxResult(
+                stdout="\n".join(lines) if lines else "(empty)",
+                stderr="",
+                exit_code=0,
+                execution_time=0,
+            )
+        except Exception as e:
+            return SandboxResult(
+                stdout=f"Error listing directory: {str(e)}",
+                stderr="",
+                exit_code=1,
+                execution_time=0,
+            )
+
+    def _build_env(self) -> dict[str, str]:
+        """Build environment dict for sandboxed execution."""
+        env = os.environ.copy()
+        env["SANDBOX_MODE"] = "1"
+        env["REGCODE_SANDBOX"] = str(self.sandbox_root)
+
+        # Remove potentially dangerous env vars
+        dangerous = {"PYTHONPATH", "PYTHONHOME", "LD_PRELOAD", "LD_LIBRARY_PATH"}
+        for key in dangerous:
+            env.pop(key, None)
+
+        # Add extra env
+        env.update(self.config.extra_env)
+
+        # Restrict network by setting environment hints
+        if self.config.restrict_network:
+            env["NO_PROXY"] = "localhost,127.0.0.1"
+
+        return env

regcode/tools/__init__.py

@@ -0,0 +1,13 @@
+"""Tools package for the regcode agent."""
+
+from regcode.tools.base import BaseTool, ToolParam, ToolResult
+from regcode.tools.builtins import create_default_tools
+from regcode.tools.registry import ToolRegistry
+
+__all__ = [
+    "BaseTool",
+    "ToolParam",
+    "ToolResult",
+    "ToolRegistry",
+    "create_default_tools",
+]

regcode/tools/base.py

@@ -0,0 +1,125 @@
+"""Base tool class for the regcode agent tool system."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ToolResult:
+    """Result from a tool execution."""
+
+    output: str
+    error: bool = False
+    stdout: str = ""
+    stderr: str = ""
+    exit_code: int = 0
+    result: Any = None
+
+    def __str__(self) -> str:
+        if self.error:
+            parts = [f"Error: {self.output.strip()}"]
+            if self.stderr:
+                parts.append(f"stderr: {self.stderr.strip()}")
+            return "\n".join(parts)
+        return self.output.strip()
+
+
+@dataclass
+class ToolParam:
+    """A single parameter definition for a tool."""
+
+    name: str
+    type: str
+    description: str
+    required: bool = True
+    default: Any = None
+
+
+@dataclass
+class ToolDefinition:
+    """Definition of a tool including its schema and metadata."""
+
+    name: str
+    description: str
+    params: list[ToolParam]
+    handler: Any  # Callable that accepts kwargs and returns ToolResult
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert tool definition to JSON-serializable dict."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": {
+                p.name: {
+                    "type": p.type,
+                    "description": p.description,
+                    "required": p.required,
+                    "default": p.default,
+                }
+                for p in self.params
+            },
+        }
+
+
+class BaseTool(ABC):
+    """Abstract base class for all agent tools."""
+
+    name: str = ""
+    description: str = ""
+
+    @property
+    @abstractmethod
+    def params(self) -> list[ToolParam]:
+        """Return list of parameters for this tool."""
+
+    @abstractmethod
+    def execute(self, **kwargs: Any) -> ToolResult:
+        """Execute the tool with given parameters."""
+
+    def validate_params(self, **kwargs: Any) -> ToolResult | None:
+        """Validate parameters before execution. Return error or None."""
+        required_params = {p.name for p in self.params if p.required}
+        provided = set(kwargs.keys())
+        missing = required_params - provided
+        if missing:
+            return ToolResult(
+                output=f"Missing required parameters: {', '.join(sorted(missing))}",
+                error=True,
+            )
+        return None
+
+    def to_definition(self) -> ToolDefinition:
+        """Convert this tool to a ToolDefinition."""
+        return ToolDefinition(
+            name=self.name,
+            description=self.description,
+            params=self.params,
+            handler=self.execute,
+        )
+
+    def to_openai_tools(self) -> list[dict[str, Any]]:
+        """Convert to OpenAI-compatible tool format."""
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": self.name,
+                    "description": self.description,
+                    "parameters": {
+                        p.name: {
+                            "type": p.type,
+                            "description": p.description,
+                            "required": p.required,
+                            "default": p.default,
+                        }
+                        for p in self.params
+                    },
+                }
+            }
+        ]
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name={self.name!r})"