pulse-coding-agent 0.1.0__py3-none-any.whl

pulse/sandbox/process.py

@@ -0,0 +1,331 @@
+"""Portable subprocess lifecycle management for sandbox backends."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import signal
+import sys
+import typing
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class ProcessEnforcementLevel(str, Enum):
+    """Degrees to which process containment can be guaranteed."""
+    UNSUPPORTED = "unsupported"
+    BEST_EFFORT = "best_effort"
+    STRONGLY_ENFORCED = "strongly_enforced"
+
+
+from pulse.sandbox.resources import (
+    ExecutionMetrics,
+    ResourceController,
+    ResourceLimits,
+    ResourcePolicy,
+)
+from pulse.subprocesses import isolated_process_kwargs
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class ProcessResult:
+    """Outcome and resource observations for a managed process execution."""
+    command: str
+    exit_code: int
+    stdout: str
+    stderr: str
+    duration_ms: float
+    timed_out: bool = False
+    truncated: bool = False
+    pid: int | None = None
+    overlay_path: Path | None = None
+    metrics: ExecutionMetrics | None = None
+    termination_reason: str | None = None
+
+
+class ProcessManager:
+    """Runs isolated process groups with timeout, cancellation and output caps."""
+    def __init__(self) -> None:
+        self._active_processes: set[asyncio.subprocess.Process] = set()
+        # Backends may configure a process-wide default policy.  Per-call
+        # limits remain authoritative when supplied to ``execute``.
+        self.limits: ResourceLimits | ResourcePolicy = ResourcePolicy()
+
+    @property
+    def active_count(self) -> int:
+        return len(self._active_processes)
+
+    async def execute(self, command: str | list[str], cwd: Path | str | None = None, env: dict[str, str] | None = None, limits: ResourceLimits | ResourcePolicy | None = None, output_callback: typing.Callable[[str, bytes], typing.Awaitable[None]] | None = None, *, apply_native_limits: bool = True) -> ProcessResult:
+        effective_limits = limits if limits is not None else self.limits
+        controller = ResourceController(
+            effective_limits
+            if isinstance(effective_limits, ResourcePolicy)
+            else effective_limits.to_policy()
+        )
+        policy = controller.policy
+        cmd_str = command if isinstance(command, str) else " ".join(command)
+        extra_kwargs: dict[str, Any] = {
+            "close_fds": True,
+            **isolated_process_kwargs(),
+        }
+        if sys.platform != "win32":
+            extra_kwargs["start_new_session"] = True
+            if apply_native_limits:
+                extra_kwargs["preexec_fn"] = controller.make_preexec_fn()
+
+        proc: asyncio.subprocess.Process | None = None
+        stdout = b""
+        stderr = b""
+        captured: dict[str, bytearray] = {
+            "stdout": bytearray(),
+            "stderr": bytearray(),
+        }
+        reason: str | None = None
+        controller.monitor.start()
+        try:
+            if isinstance(command, str):
+                proc = await asyncio.create_subprocess_shell(command, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, cwd=str(cwd) if cwd else None, env=controller.sanitize_env(env), **extra_kwargs)
+            else:
+                proc = await asyncio.create_subprocess_exec(command[0], *command[1:], stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, cwd=str(cwd) if cwd else None, env=controller.sanitize_env(env), **extra_kwargs)
+            self._active_processes.add(proc)
+            try:
+                stdout, stderr, output_limited = await asyncio.wait_for(
+                    self._collect_output(
+                        proc,
+                        policy.max_output_bytes,
+                        output_callback,
+                        captured,
+                    ),
+                    timeout=policy.wall_time_seconds,
+                )
+                if output_limited:
+                    reason = "output_limit"
+            except TimeoutError:
+                reason = "timeout"
+                await self._terminate_tree(proc, policy.termination_grace_seconds)
+                remaining_stdout, remaining_stderr = await self._drain_output(proc)
+                stdout = bytes(captured["stdout"]) + remaining_stdout
+                stderr = bytes(captured["stderr"]) + remaining_stderr
+                stderr += b"\nProcess execution timed out."
+            except asyncio.CancelledError:
+                reason = "cancelled"
+                await self._terminate_tree(proc, policy.termination_grace_seconds)
+                raise
+        except asyncio.CancelledError:
+            raise
+        except Exception as error:  # noqa: BLE001, execution boundaries return structured result
+            reason = reason or "launch_error"
+            stderr += str(error).encode("utf-8", errors="replace")
+        finally:
+            if proc is not None:
+                if proc.returncode is None:
+                    await self._terminate_tree(proc, policy.termination_grace_seconds)
+                self._close_process_transport(proc)
+                self._active_processes.discard(proc)
+
+        exit_code = -9 if reason == "timeout" else (proc.returncode if proc and proc.returncode is not None else -1)
+        clean_stdout, stdout_truncated = self._truncate(stdout, policy.max_output_bytes)
+        clean_stderr, stderr_truncated = self._truncate(stderr, policy.max_output_bytes)
+        metrics = controller.monitor.finish(output_bytes=len(stdout) + len(stderr), exit_status=exit_code, termination_reason=reason)
+        if reason == "output_limit":
+            marker = "\n... [OUTPUT TRUNCATED BY SANDBOX RESOURCE LIMITER]"
+            if len(clean_stdout) >= len(clean_stderr):
+                clean_stdout += marker
+            else:
+                clean_stderr += marker
+        return ProcessResult(
+            cmd_str,
+            exit_code,
+            clean_stdout,
+            clean_stderr,
+            metrics.elapsed_ms,
+            reason == "timeout",
+            stdout_truncated or stderr_truncated or reason == "output_limit",
+            getattr(proc, "pid", None) if proc else None,
+            metrics=metrics,
+            termination_reason=reason,
+        )
+
+    async def _collect_output(self, proc: asyncio.subprocess.Process, max_bytes: int, output_callback: typing.Callable[[str, bytes], typing.Awaitable[None]] | None = None, captured: dict[str, bytearray] | None = None) -> tuple[bytes, bytes, bool]:
+        chunks = captured or {"stdout": bytearray(), "stderr": bytearray()}
+        total = 0
+        exceeded = False
+        lock = asyncio.Lock()
+
+        async def read_stream(stream: asyncio.StreamReader | None, name: str) -> None:
+            nonlocal total, exceeded
+            if stream is None:
+                return
+            while data := await stream.read(65_536):
+                async with lock:
+                    if output_callback:
+                        try:
+                            await output_callback(name, data)
+                        except OSError:
+                            logger.debug("output_callback failed for stream %s", name)
+                    remaining = max_bytes - total
+                    if remaining <= 0:
+                        exceeded = True
+                    else:
+                        chunks[name].extend(data[:remaining])
+                        total += min(len(data), remaining)
+                        exceeded = len(data) > remaining
+                if exceeded:
+                    await self._terminate_tree(proc, 0.1)
+                    return
+
+        await asyncio.gather(read_stream(proc.stdout, "stdout"), read_stream(proc.stderr, "stderr"))
+        await proc.wait()
+        return bytes(chunks["stdout"]), bytes(chunks["stderr"]), exceeded
+
+    @staticmethod
+    async def _drain_output(
+        proc: asyncio.subprocess.Process,
+    ) -> tuple[bytes, bytes]:
+        """Drain bytes emitted while a timed-out process is being terminated."""
+
+        async def read(stream: asyncio.StreamReader | None) -> bytes:
+            if stream is None:
+                return b""
+            try:
+                # Descendants can inherit a pipe after the direct child exits;
+                # never let diagnostic draining defeat the sandbox deadline.
+                return await asyncio.wait_for(stream.read(), timeout=0.5)
+            except TimeoutError:
+                return b""
+
+        return await asyncio.gather(read(proc.stdout), read(proc.stderr))
+
+    @staticmethod
+    def _truncate(content: bytes, max_bytes: int) -> tuple[str, bool]:
+        if len(content) <= max_bytes:
+            return content.decode("utf-8", errors="replace"), False
+        return content[:max_bytes].decode("utf-8", errors="ignore"), True
+
+    async def _terminate_tree(self, proc: asyncio.subprocess.Process, grace_seconds: float) -> None:
+        """Terminate the complete process tree, then force reap it if needed.
+
+        Security architecture:
+            On POSIX, ``start_new_session=True`` places the child in a new
+            process group whose pgid equals the child PID.  ``killpg()``
+            sends signals to every process in that group, covering all
+            descendants that have NOT called ``setsid()`` / ``setpgid()``.
+
+        Limitations:
+            A descendant that calls ``setsid()`` or ``setpgid(0, 0)``
+            creates a new process group and **escapes** ``killpg()``.
+            This is a fundamental POSIX limitation.  Container backends
+            (Docker/Podman) provide PID-namespace isolation which is the
+            definitive containment boundary for untrusted code.
+        """
+        if proc.returncode is not None:
+            return
+        try:
+            if sys.platform == "win32":
+                # CREATE_NEW_PROCESS_GROUP does not terminate descendants when
+                # the direct child is killed. Use taskkill's tree traversal,
+                # but bound the helper so it cannot defeat the sandbox timeout.
+                helper: asyncio.subprocess.Process | None = None
+                try:
+                    helper = await asyncio.create_subprocess_exec(
+                        "taskkill",
+                        "/PID",
+                        str(proc.pid),
+                        "/T",
+                        "/F",
+                        stdout=asyncio.subprocess.DEVNULL,
+                        stderr=asyncio.subprocess.DEVNULL,
+                        **isolated_process_kwargs(),
+                    )
+                    await asyncio.wait_for(
+                        helper.wait(), timeout=max(1.0, min(5.0, grace_seconds + 1.0))
+                    )
+                except (OSError, ProcessLookupError, TimeoutError):
+                    if helper is not None and helper.returncode is None:
+                        helper.kill()
+                        await helper.wait()
+
+                if proc.returncode is None:
+                    try:
+                        proc.kill()
+                    except ProcessLookupError:
+                        pass
+                try:
+                    await asyncio.wait_for(
+                        proc.wait(), timeout=max(1.0, grace_seconds + 1.0)
+                    )
+                except TimeoutError:
+                    logger.warning("Timed out reaping Windows process rooted at %s.", proc.pid)
+                return
+
+            # Cache pgid once to avoid PID-recycling race on repeated lookups.
+            try:
+                pgid = os.getpgid(proc.pid)
+            except (ProcessLookupError, PermissionError):
+                # Process already exited — nothing to kill.
+                return
+
+            # 1. Graceful SIGTERM to entire process group.
+            try:
+                os.killpg(pgid, signal.SIGTERM)
+            except (ProcessLookupError, PermissionError):
+                return
+
+            # 2. Wait for the grace period.
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=grace_seconds)
+            except TimeoutError:
+                # 3. Escalate to SIGKILL.
+                try:
+                    os.killpg(pgid, signal.SIGKILL)
+                except (ProcessLookupError, PermissionError):
+                    pass
+
+            # 4. Reap the direct child.
+            await proc.wait()
+
+            # 5. Best-effort reap of any remaining group members.
+            self._reap_remaining_group(pgid)
+
+        except (ProcessLookupError, PermissionError):
+            pass
+
+    @staticmethod
+    def _close_process_transport(proc: asyncio.subprocess.Process) -> None:
+        """Close subprocess pipes after output collection and reaping."""
+        transport = getattr(proc, "_transport", None)
+        if transport is not None:
+            transport.close()
+
+    @staticmethod
+    def _reap_remaining_group(pgid: int) -> None:
+        """Best-effort reap of orphaned members still in *pgid*.
+
+        Uses ``os.waitpid(-pgid, WNOHANG)`` which reaps any child of the
+        current process whose process-group equals *pgid*.  This covers
+        grandchildren that were re-parented to PID 1 / subreaper but are
+        still in the original process group.
+
+        Silently ignored on platforms where this is unsupported.
+        """
+        if sys.platform == "win32":
+            return
+        for _ in range(64):  # bounded loop to avoid infinite reaping
+            try:
+                pid, _ = os.waitpid(-pgid, os.WNOHANG)
+                if pid == 0:
+                    break  # no more waitable children in this group
+            except ChildProcessError:
+                break  # no children to wait for
+            except OSError:
+                break
+
+    async def terminate_all(self) -> None:
+        """Kill all tracked active processes and reap them."""
+        await asyncio.gather(*(self._terminate_tree(proc, 0.1) for proc in list(self._active_processes)), return_exceptions=True)
+        self._active_processes.clear()

pulse/sandbox/project.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from pulse.audit import AuditLog
+from pulse.config import SandboxConfig
+from pulse.mutations import MutationTracker
+
+
+class ProjectSandbox:
+    def __init__(self, config: SandboxConfig, audit: AuditLog, mutations: MutationTracker | None = None) -> None:
+        self.config = config
+        self.audit = audit
+        self.mutations = mutations or MutationTracker(config.workspace_root)
+
+    def list_files(self) -> list[str]:
+        ignored = {".git", ".agent", ".agents", ".venv", "__pycache__"}
+        files: list[str] = []
+
+        for path in self.config.workspace_root.rglob("*"):
+            if any(part in ignored for part in path.relative_to(self.config.workspace_root).parts):
+                continue
+            if path.is_file():
+                files.append(self._display_path(path))
+
+        return sorted(files)
+
+    def read_file(self, file: str, reason: str, *, auto_approve: bool = False) -> str | None:
+        if self.config.require_permission_for_reads and not auto_approve and not self._ask_permission("read", file, reason):
+            self.audit.record("read-denied", file, "User denied read permission.")
+            return None
+
+        path = self._assert_inside_workspace(file)
+        content = path.read_text(encoding="utf-8", errors="replace")
+        self.audit.record("read", file, "Read file with permission.")
+        return content[:12_000]
+
+    def request_project_action(self, action: str, file: str, reason: str) -> bool:
+        if self.config.require_permission_for_project_actions and not self._ask_permission(action, file, reason):
+            self.audit.record(f"{action}-denied", file, "User denied project action.")
+            return False
+
+        self.audit.record(action, file, reason)
+        return True
+
+    def write_file(self, file: str, content: str, reason: str) -> bool:
+        if not self.config.allow_writes:
+            self.audit.record("edit-blocked", file, "Writes are disabled by sandbox config.")
+            print(f"Writes are disabled. Skipped edit on {file}.")
+            return False
+
+        if not self.request_project_action("edit", file, reason):
+            return False
+
+        path = self._assert_inside_workspace(file)
+        with self.mutations.transaction():
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+        self.audit.record("edited", file, "Edited file with permission.")
+        return True
+
+    def read_file_for_edit(self, file: str) -> str | None:
+        """Read the complete current text for a proposed edit without prompting.
+
+        The proposal is not an action and the caller must still obtain explicit
+        approval before ``apply_approved_edit`` can write it.
+        """
+        path = self._assert_inside_workspace(file)
+        return path.read_text(encoding="utf-8", errors="replace") if path.exists() else None
+
+    def apply_approved_edit(self, file: str, content: str, reason: str) -> None:
+        """Apply an edit already approved by the edit workflow.
+
+        This deliberately does not consult ``allow_writes``: that setting keeps
+        unapproved/direct writes off by default, while this narrow method is
+        protected by the workflow's per-edit approval.
+        """
+        path = self._assert_inside_workspace(file)
+        with self.mutations.transaction(command="pulse approved edit"):
+            path.parent.mkdir(parents=True, exist_ok=True)
+            self._write_text_exact(path, content)
+        self.audit.record("edited", file, f"Approved edit: {reason}")
+
+    def record_rejected_edit(self, file: str, reason: str) -> None:
+        self.audit.record("edit-rejected", file, reason)
+
+    def rollback_last_approved_edit(self) -> bool:
+        events = self.mutations.last_approved_edit()
+        if not events:
+            return False
+        with self.mutations.transaction(command="pulse rollback"):
+            for event in events:
+                self._restore_event(event)
+        self.audit.record("rollback", ", ".join(str(event["file_path"]) for event in events), "Restored last approved edit.")
+        return True
+
+    def _restore_event(self, event: dict[str, object]) -> None:
+        file = str(event["file_path"])
+        if " -> " in file:
+            raise ValueError("Rollback does not support renamed files.")
+        path = self._assert_inside_workspace(file)
+        before = event.get("before_content")
+        if before is None:
+            if path.exists():
+                path.unlink()
+            return
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._write_text_exact(path, str(before))
+
+    @staticmethod
+    def _write_text_exact(path: Path, content: str) -> None:
+        """Avoid Windows newline conversion when restoring a tracked snapshot."""
+        with path.open("w", encoding="utf-8", newline="") as handle:
+            handle.write(content)
+
+    def delete_file(self, file: str, reason: str) -> bool:
+        if not self.config.allow_writes:
+            self.audit.record("delete-blocked", file, "Writes are disabled by sandbox config.")
+            return False
+        if not self.request_project_action("delete", file, reason):
+            return False
+        path = self._assert_inside_workspace(file)
+        with self.mutations.transaction():
+            path.unlink()
+        self.audit.record("deleted", file, "Deleted file with permission.")
+        return True
+
+    def rename_file(self, source: str, destination: str, reason: str) -> bool:
+        if not self.config.allow_writes:
+            self.audit.record("rename-blocked", source, "Writes are disabled by sandbox config.")
+            return False
+        if not self.request_project_action("rename", source, reason):
+            return False
+        source_path = self._assert_inside_workspace(source)
+        destination_path = self._assert_inside_workspace(destination)
+        with self.mutations.transaction():
+            destination_path.parent.mkdir(parents=True, exist_ok=True)
+            source_path.rename(destination_path)
+        self.audit.record("renamed", f"{source} -> {destination}", "Renamed file with permission.")
+        return True
+
+    def _ask_permission(self, action: str, file: str, reason: str) -> bool:
+        if not sys.stdin.isatty():
+            print(f"Denied {action} on {file}: no interactive terminal available for permission.")
+            return False
+
+        answer = input(f"Allow {action} on {file}? {reason} [y/N] ").strip().lower()
+        return answer in {"y", "yes"}
+
+    def _assert_inside_workspace(self, file: str) -> Path:
+        path = (self.config.workspace_root / file).resolve()
+        if path != self.config.workspace_root and self.config.workspace_root not in path.parents:
+            raise ValueError(f"Path is outside workspace: {file}")
+        return path
+
+    def _display_path(self, path: Path) -> str:
+        return str(path.relative_to(self.config.workspace_root))

pulse/sandbox/python_safe.py

@@ -0,0 +1,62 @@
+"""Policy-checked safe Python and package environment execution wrapper."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from pulse.sandbox.policy import ActionType, PolicyDecision
+from pulse.sandbox.process import ProcessResult
+
+if TYPE_CHECKING:
+    from pulse.sandbox.api import Sandbox
+
+
+class SafePython:
+    """Provides policy-gated access to Python interpreter and virtual environments."""
+
+    def __init__(self, sandbox: Sandbox, python_executable: str | None = None) -> None:
+        self.sandbox = sandbox
+        self.python_executable = python_executable or sys.executable
+
+    async def run_script(self, script_path: str, args: list[str] | None = None) -> ProcessResult:
+        decision = self.sandbox.policy.evaluate(ActionType.PYTHON, script_path)
+        if decision == PolicyDecision.DENY:
+            return ProcessResult(
+                command=f"python {script_path}",
+                exit_code=-1,
+                stdout="",
+                stderr="Policy denied Python script execution.",
+                duration_ms=0.0,
+            )
+
+        cmd = [self.python_executable, script_path] + (args or [])
+        return await self.sandbox.execute_command(cmd)
+
+    async def run_module(self, module: str, args: list[str] | None = None) -> ProcessResult:
+        decision = self.sandbox.policy.evaluate(ActionType.PYTHON, f"-m {module}")
+        if decision == PolicyDecision.DENY:
+            return ProcessResult(
+                command=f"python -m {module}",
+                exit_code=-1,
+                stdout="",
+                stderr="Policy denied Python module execution.",
+                duration_ms=0.0,
+            )
+
+        cmd = [self.python_executable, "-m", module] + (args or [])
+        return await self.sandbox.execute_command(cmd)
+
+    async def run_uv(self, uv_args: list[str]) -> ProcessResult:
+        decision = self.sandbox.policy.evaluate(ActionType.PYTHON, f"uv {' '.join(uv_args)}")
+        if decision == PolicyDecision.DENY:
+            return ProcessResult(
+                command=f"uv {' '.join(uv_args)}",
+                exit_code=-1,
+                stdout="",
+                stderr="Policy denied uv command execution.",
+                duration_ms=0.0,
+            )
+
+        cmd = ["uv"] + uv_args
+        return await self.sandbox.execute_command(cmd)

pulse/sandbox/remote/__init__.py

@@ -0,0 +1 @@
+"""Remote Sandbox Backend and Worker definitions."""