pcli-agent 0.1.0__py3-none-any.whl

pcli/permissions/manager.py

@@ -0,0 +1,215 @@
+"""Gates a tool call: guardrails (hard deny) -> remembered grants -> ask.
+
+The `ask` callback is intentionally decoupled from Textual so this module
+stays testable without a running App; tui/screens/permission_modal.py
+supplies the real implementation via `push_screen_wait`.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import deque
+from collections.abc import Awaitable, Callable
+from typing import Any, Literal
+
+from pcli.permissions.guardrails import GuardrailsConfig
+from pcli.permissions.policy import PermissionPolicy
+from pcli.session.audit import append_audit_entry
+from pcli.session.models import PermissionGrant, Session
+
+PermissionDecision = Literal["allow", "deny"]
+RememberScope = Literal["once", "session", "always"]
+DecisionMechanism = Literal[
+    "rate_limit",
+    "guardrail_command",
+    "guardrail_path",
+    "guardrail_python_module",
+    "default_allow",
+    "remembered_policy",
+    "no_ui_fail_closed",
+    "interactive",
+]
+
+AskCallback = Callable[[str, dict[str, Any], str], Awaitable[tuple[PermissionDecision, RememberScope | None]]]
+
+
+class PermissionManager:
+    def __init__(
+        self,
+        *,
+        guardrails: GuardrailsConfig | None = None,
+        policy: PermissionPolicy | None = None,
+        audit_enabled: bool = False,
+    ) -> None:
+        self.guardrails = guardrails or GuardrailsConfig.load()
+        self.policy = policy or PermissionPolicy()
+        self._audit_enabled = audit_enabled
+        self._recent_tool_call_times: deque[float] = deque()
+
+    def _within_rate_limit(self) -> bool:
+        """guardrails.max_tool_calls_per_minute as a sliding 60s window,
+        shared across every tool call this manager gates (including a
+        subagent's, since it's handed the same PermissionManager instance) —
+        a global rate cap independent of any single turn's own tool-call
+        count (see max_tool_calls_per_turn in agent/loop.py)."""
+        limit = self.guardrails.max_tool_calls_per_minute
+        if limit <= 0:
+            return True
+        now = time.monotonic()
+        cutoff = now - 60.0
+        while self._recent_tool_call_times and self._recent_tool_call_times[0] < cutoff:
+            self._recent_tool_call_times.popleft()
+        if len(self._recent_tool_call_times) >= limit:
+            return False
+        self._recent_tool_call_times.append(now)
+        return True
+
+    async def check(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        *,
+        command: str | None = None,
+        path: str | None = None,
+        python_module: str | None = None,
+        ask: AskCallback | None = None,
+        risk_description: str = "",
+        default_allow: bool = False,
+        session: Session | None = None,
+    ) -> PermissionDecision:
+        """Thin wrapper over check_with_reason() for callers that only need
+        the decision, not why — kept so the (many) existing call sites
+        don't need to unpack a tuple."""
+        decision, _reason = await self.check_with_reason(
+            tool_name,
+            arguments,
+            command=command,
+            path=path,
+            python_module=python_module,
+            ask=ask,
+            risk_description=risk_description,
+            default_allow=default_allow,
+            session=session,
+        )
+        return decision
+
+    async def check_with_reason(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        *,
+        command: str | None = None,
+        path: str | None = None,
+        python_module: str | None = None,
+        ask: AskCallback | None = None,
+        risk_description: str = "",
+        default_allow: bool = False,
+        session: Session | None = None,
+    ) -> tuple[PermissionDecision, str | None]:
+        """Same decision logic as check(), but also returns a human-readable
+        reason for a "deny" — None for "allow", and also None for a plain
+        interactive "no" with nothing more specific to say than the user's
+        own judgment call. AgentLoop uses this (not check()) so a denied
+        tool call gives the model something to actually diagnose instead of
+        a bare "Permission denied.", which is otherwise toothless for this
+        exact class of failure despite the "Recovering from a failed tool
+        call" system-prompt guidance telling it to diagnose before retrying.
+
+        `default_allow=True` is for tools that don't need a user prompt
+        (e.g. read_file) but must still respect the hard guardrails below.
+
+        `session`, if given, gets a PermissionGrant record appended whenever
+        a "session" or "always" grant is remembered — a historical audit
+        trail that travels with session export/import. It's independent of
+        enforcement: "always" grants are enforced via self.policy (persisted
+        separately in permissions.json), and are deliberately not re-applied
+        from a session's own history on import, to avoid double-recording
+        the same grant into permissions.json.
+
+        When self._audit_enabled and session is given, also appends one
+        hash-chained AuditEntry (session/audit.py) per call recording the
+        decision, its reason, and which mechanism decided it - skipped only
+        for the default_allow/no-guardrail-hit case, since nothing was
+        actually decided there (see _decide's own docstring)."""
+        decision, reason, mechanism = await self._decide(
+            tool_name,
+            arguments,
+            command=command,
+            path=path,
+            python_module=python_module,
+            ask=ask,
+            risk_description=risk_description,
+            default_allow=default_allow,
+            session=session,
+        )
+        if self._audit_enabled and session is not None and mechanism != "default_allow":
+            append_audit_entry(
+                session,
+                kind="permission_decision",
+                summary=f"{tool_name} {decision}" + (f" ({mechanism})" if mechanism else ""),
+                detail={
+                    "tool_name": tool_name,
+                    "risk_description": risk_description,
+                    "decision": decision,
+                    "reason": reason,
+                    "mechanism": mechanism,
+                },
+            )
+        return decision, reason
+
+    async def _decide(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        *,
+        command: str | None,
+        path: str | None,
+        python_module: str | None,
+        ask: AskCallback | None,
+        risk_description: str,
+        default_allow: bool,
+        session: Session | None,
+    ) -> tuple[PermissionDecision, str | None, DecisionMechanism]:
+        """The actual decision logic, unchanged from before check_with_reason
+        was split in two - only the return shape grew a third element
+        (`mechanism`, for check_with_reason's own audit recording). Every
+        early return here corresponds to one DecisionMechanism value."""
+        if not self._within_rate_limit():
+            return "deny", "rate limit exceeded (max_tool_calls_per_minute)", "rate_limit"
+
+        if command is not None:
+            result = self.guardrails.evaluate_command(command)
+            if not result.allowed:
+                return "deny", result.reason, "guardrail_command"
+
+        if path is not None:
+            result = self.guardrails.evaluate_path(path)
+            if not result.allowed:
+                return "deny", result.reason, "guardrail_path"
+
+        if python_module is not None:
+            result = self.guardrails.evaluate_python_module(python_module)
+            if not result.allowed:
+                return "deny", result.reason, "guardrail_python_module"
+
+        if default_allow:
+            return "allow", None, "default_allow"
+
+        existing = self.policy.check(tool_name)
+        if existing is not None:
+            reason = "previously denied and remembered" if existing == "deny" else None
+            return existing, reason, "remembered_policy"
+
+        if ask is None:
+            # No UI available to ask through -> fail closed.
+            return "deny", "no UI available to request approval", "no_ui_fail_closed"
+
+        decision, remember_scope = await ask(tool_name, arguments, risk_description)
+        if remember_scope is not None and remember_scope != "once":
+            self.policy.remember(tool_name, scope=remember_scope, decision=decision)
+            if session is not None:
+                session.permission_grants.append(
+                    PermissionGrant(tool_name=tool_name, scope=remember_scope, decision=decision)
+                )
+        reason = "denied by the user" if decision == "deny" else None
+        return decision, reason, "interactive"

pcli/permissions/policy.py

@@ -0,0 +1,70 @@
+"""Tracks 'always allow/deny' grants (persisted to disk) and per-session
+grants (in-memory only for the life of the process)."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel
+
+from pcli.config.paths import permissions_file
+
+
+class StoredGrant(BaseModel):
+    tool_name: str
+    argument_pattern: str | None = None
+    decision: Literal["allow", "deny"] = "allow"
+
+
+class PermissionPolicy:
+    def __init__(self, *, persist_path: Path | None = None) -> None:
+        self._persist_path = persist_path or permissions_file()
+        self._always_grants: list[StoredGrant] = self._load()
+        self._session_grants: list[StoredGrant] = []
+
+    def _load(self) -> list[StoredGrant]:
+        if not self._persist_path.exists():
+            return []
+        raw = json.loads(self._persist_path.read_text(encoding="utf-8"))
+        return [StoredGrant.model_validate(g) for g in raw]
+
+    def _save(self) -> None:
+        self._persist_path.parent.mkdir(parents=True, exist_ok=True)
+        content = json.dumps([g.model_dump() for g in self._always_grants], indent=2)
+        tmp_path = self._persist_path.with_suffix(".tmp")
+        tmp_path.write_text(content, encoding="utf-8")
+        os.replace(tmp_path, self._persist_path)
+
+    def remember(
+        self,
+        tool_name: str,
+        *,
+        scope: Literal["session", "always"],
+        decision: Literal["allow", "deny"] = "allow",
+        argument_pattern: str | None = None,
+    ) -> None:
+        grant = StoredGrant(
+            tool_name=tool_name, argument_pattern=argument_pattern, decision=decision
+        )
+        if scope == "always":
+            self._always_grants.append(grant)
+            self._save()
+        else:
+            self._session_grants.append(grant)
+
+    def check(
+        self, tool_name: str, argument_pattern: str | None = None
+    ) -> Literal["allow", "deny"] | None:
+        for grant in (*self._session_grants, *self._always_grants):
+            if grant.tool_name != tool_name:
+                continue
+            if grant.argument_pattern is not None and grant.argument_pattern != argument_pattern:
+                continue
+            return grant.decision
+        return None
+
+    def session_grants_snapshot(self) -> list[StoredGrant]:
+        return list(self._session_grants)

pcli/sandbox/base.py

@@ -0,0 +1,50 @@
+"""Common interface both sandbox backends implement."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class ExecRequest:
+    command: list[str] | str
+    """A list is executed directly (argv, no shell); a str is run through the
+    platform shell (needed for pipes/redirection in ad hoc shell commands)."""
+    cwd: Path
+    env: dict[str, str] = field(default_factory=dict)
+    timeout_s: float = 30.0
+    stdin: str | None = None
+    network: bool = False
+
+
+@dataclass
+class ExecResult:
+    stdout: str
+    stderr: str
+    exit_code: int
+    timed_out: bool
+    backend_used: str
+
+
+@dataclass
+class SandboxCapabilities:
+    supports_network_isolation: bool
+    supports_memory_limit: bool
+    supports_cpu_limit: bool
+
+
+class Sandbox(ABC):
+    name: str = "base"
+
+    @abstractmethod
+    async def execute(self, request: ExecRequest) -> ExecResult: ...
+
+    @abstractmethod
+    def capabilities(self) -> SandboxCapabilities: ...
+
+
+class SandboxSecurityError(Exception):
+    """Raised when a request would escape the sandbox's containment (e.g. a
+    cwd outside the allowed roots). Distinct from a command simply failing."""

pcli/sandbox/docker_backend.py

@@ -0,0 +1,107 @@
+"""Docker-backed sandbox: one-shot `docker run --rm` per invocation, network
+off by default, bind-mounted working directory, resource limits.
+
+Shells out to the `docker` CLI rather than depending on the `docker` SDK, so
+this module has no hard dependency beyond the `docker` binary being on PATH.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from pcli.sandbox.base import ExecRequest, ExecResult, Sandbox, SandboxCapabilities
+
+
+def _truncate(data: bytes, max_bytes: int) -> str:
+    if len(data) <= max_bytes:
+        return data.decode(errors="replace")
+    return data[:max_bytes].decode(errors="replace") + "\n[...output truncated...]"
+
+
+class DockerSandbox(Sandbox):
+    name = "docker"
+
+    def __init__(
+        self,
+        *,
+        image: str = "python:3.12-slim",
+        memory: str = "512m",
+        cpus: str = "1",
+        pids_limit: int = 256,
+        max_output_bytes: int = 2_000_000,
+    ) -> None:
+        self._image = image
+        self._memory = memory
+        self._cpus = cpus
+        self._pids_limit = pids_limit
+        self._max_output_bytes = max_output_bytes
+
+    def capabilities(self) -> SandboxCapabilities:
+        return SandboxCapabilities(
+            supports_network_isolation=True, supports_memory_limit=True, supports_cpu_limit=True
+        )
+
+    async def execute(self, request: ExecRequest) -> ExecResult:
+        cwd = request.cwd.expanduser().resolve()
+        docker_args = [
+            "docker",
+            "run",
+            "--rm",
+            "-i",
+            "--network",
+            "bridge" if request.network else "none",
+            "--memory",
+            self._memory,
+            "--cpus",
+            self._cpus,
+            "--pids-limit",
+            str(self._pids_limit),
+            "-v",
+            f"{cwd}:/workspace:rw",
+            "-w",
+            "/workspace",
+        ]
+        for key, value in request.env.items():
+            docker_args += ["-e", f"{key}={value}"]
+        docker_args.append(self._image)
+        if isinstance(request.command, str):
+            docker_args += ["sh", "-c", request.command]
+        else:
+            docker_args += list(request.command)
+
+        proc = await asyncio.create_subprocess_exec(
+            *docker_args,
+            stdin=asyncio.subprocess.PIPE if request.stdin is not None else asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        timed_out = False
+        stdin_bytes = request.stdin.encode() if request.stdin is not None else None
+        try:
+            stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                proc.communicate(stdin_bytes), timeout=request.timeout_s
+            )
+        except TimeoutError:
+            timed_out = True
+            proc.kill()
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=5)
+            except TimeoutError:
+                pass
+            stdout_bytes, stderr_bytes = b"", b"[pcli] command timed out and was killed"
+        except asyncio.CancelledError:
+            # See the identical comment in subprocess_backend.py: this fires
+            # on caller-initiated cancellation (e.g. Esc+Esc), not our own
+            # wait_for's timeout — without killing here, the `docker run`
+            # process (and likely its container) is left running.
+            proc.kill()
+            raise
+
+        return ExecResult(
+            stdout=_truncate(stdout_bytes, self._max_output_bytes),
+            stderr=_truncate(stderr_bytes, self._max_output_bytes),
+            exit_code=proc.returncode if proc.returncode is not None else -1,
+            timed_out=timed_out,
+            backend_used=self.name,
+        )

pcli/sandbox/limits.py

@@ -0,0 +1,63 @@
+"""Cross-platform resource-limiting helpers.
+
+POSIX gets real rlimits via preexec_fn. Windows has no equivalent stdlib API
+(no `resource` module) — it relies solely on the wall-clock timeout plus
+psutil-based process-tree cleanup, which works identically on both platforms
+and is the actual safety net in RestrictedSubprocessSandbox either way.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+
+import psutil
+
+
+def is_posix() -> bool:
+    return sys.platform != "win32"
+
+
+def make_posix_preexec_fn(
+    *, cpu_seconds: int | None, memory_bytes: int | None
+) -> Callable[[], None] | None:
+    if not is_posix():
+        return None
+
+    def _preexec() -> None:
+        import resource
+
+        # No os.setsid() here: the caller already passes start_new_session=True
+        # to Popen/create_subprocess_exec, which calls setsid() itself right
+        # after forking, before running this preexec_fn. Calling it again on
+        # a process that's already a session leader raises EPERM, which
+        # crashes the whole preexec_fn (surfaces as "Exception occurred in
+        # preexec_fn.") and every single shell command would fail.
+        if cpu_seconds is not None:
+            try:
+                resource.setrlimit(resource.RLIMIT_CPU, (cpu_seconds, cpu_seconds))
+            except (ValueError, OSError):
+                pass
+        if memory_bytes is not None:
+            try:
+                resource.setrlimit(resource.RLIMIT_AS, (memory_bytes, memory_bytes))
+            except (ValueError, OSError):
+                pass  # not supported on every POSIX platform (notably macOS)
+
+    return _preexec
+
+
+def kill_process_tree(pid: int) -> None:
+    try:
+        parent = psutil.Process(pid)
+    except psutil.NoSuchProcess:
+        return
+    for child in parent.children(recursive=True):
+        try:
+            child.kill()
+        except psutil.NoSuchProcess:
+            pass
+    try:
+        parent.kill()
+    except psutil.NoSuchProcess:
+        pass

pcli/sandbox/null_backend.py

@@ -0,0 +1,92 @@
+"""No-op sandbox backend: runs commands directly, with none of
+RestrictedSubprocessSandbox's containment (no cwd jail, no env scrubbing, no
+resource limits) or Docker's isolation.
+
+Selected via sandbox_backend = "none" — an explicit, documented opt-out for
+users who already run pcli somewhere they trust fully (e.g. inside their own
+disposable container/VM), never the default. Guardrails and the permission
+system still gate tool calls as usual; this only removes the *execution*
+containment layer underneath them.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from pcli.sandbox.base import ExecRequest, ExecResult, Sandbox, SandboxCapabilities
+
+
+def _truncate(data: bytes, max_bytes: int) -> str:
+    if len(data) <= max_bytes:
+        return data.decode(errors="replace")
+    return data[:max_bytes].decode(errors="replace") + "\n[...output truncated...]"
+
+
+class NullSandbox(Sandbox):
+    name = "none"
+
+    def __init__(self, *, max_output_bytes: int = 2_000_000) -> None:
+        self._max_output_bytes = max_output_bytes
+
+    def capabilities(self) -> SandboxCapabilities:
+        return SandboxCapabilities(
+            supports_network_isolation=False,
+            supports_memory_limit=False,
+            supports_cpu_limit=False,
+        )
+
+    async def execute(self, request: ExecRequest) -> ExecResult:
+        # Full inherited environment (unlike RestrictedSubprocessSandbox's
+        # allowlist scrub) plus any extra vars the caller asked for layered
+        # on top — "no sandbox" means no restriction, not no environment.
+        env = {**os.environ, **request.env}
+
+        if isinstance(request.command, str):
+            proc = await asyncio.create_subprocess_shell(
+                request.command,
+                cwd=str(request.cwd),
+                env=env,
+                stdin=asyncio.subprocess.PIPE
+                if request.stdin is not None
+                else asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+        else:
+            proc = await asyncio.create_subprocess_exec(
+                *request.command,
+                cwd=str(request.cwd),
+                env=env,
+                stdin=asyncio.subprocess.PIPE
+                if request.stdin is not None
+                else asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+
+        timed_out = False
+        stdin_bytes = request.stdin.encode() if request.stdin is not None else None
+        try:
+            stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                proc.communicate(stdin_bytes), timeout=request.timeout_s
+            )
+        except TimeoutError:
+            timed_out = True
+            try:
+                proc.kill()
+            except ProcessLookupError:
+                pass
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=5)
+            except TimeoutError:
+                pass
+            stdout_bytes, stderr_bytes = b"", b"[pcli] command timed out and was killed"
+
+        return ExecResult(
+            stdout=_truncate(stdout_bytes, self._max_output_bytes),
+            stderr=_truncate(stderr_bytes, self._max_output_bytes),
+            exit_code=proc.returncode if proc.returncode is not None else -1,
+            timed_out=timed_out,
+            backend_used=self.name,
+        )

pcli/sandbox/selector.py

@@ -0,0 +1,75 @@
+"""Chooses a Sandbox backend once at startup: Docker if reachable, else the
+restricted-subprocess fallback. The chosen backend is surfaced in the status
+bar so the user always knows the isolation level in effect."""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+from pathlib import Path
+
+from pcli.sandbox.base import Sandbox
+from pcli.sandbox.docker_backend import DockerSandbox
+from pcli.sandbox.null_backend import NullSandbox
+from pcli.sandbox.subprocess_backend import RestrictedSubprocessSandbox
+
+
+async def probe_docker_available(*, timeout_s: float = 1.5) -> bool:
+    """True only for a reachable Docker daemon running Linux containers.
+    DockerSandbox shells out to Linux-only assumptions (`python3`, a
+    `/workspace` bind mount, `--pids-limit` - a cgroups-only flag) that
+    error out immediately against a daemon in Windows-container mode
+    (Docker Desktop's other mode, and what GitHub's windows-latest runners
+    default to) rather than just failing to start. Checking the daemon's
+    OSType here means that setup falls back to RestrictedSubprocessSandbox
+    automatically instead of every tool call failing with a cryptic Docker
+    CLI error."""
+    if shutil.which("docker") is None:
+        return False
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            "docker",
+            "info",
+            "--format",
+            "{{.OSType}}",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, _stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout_s)
+        return proc.returncode == 0 and stdout.decode().strip() == "linux"
+    except (TimeoutError, OSError):
+        return False
+
+
+async def select_sandbox(
+    *,
+    backend_override: str = "auto",
+    allowed_roots: list[Path] | None = None,
+    cpu_limit_s: int | None = 30,
+    memory_limit_bytes: int | None = None,
+) -> Sandbox:
+    """cpu_limit_s/memory_limit_bytes only affect RestrictedSubprocessSandbox
+    (POSIX only) - see Settings.sandbox_cpu_limit_s/sandbox_memory_limit_bytes
+    for why memory_limit_bytes defaults to None (RLIMIT_AS's virtual-vs-actual
+    memory mismatch breaks ordinary Go-based CLI tool calls, not just
+    runaway ones)."""
+    if backend_override == "docker":
+        return DockerSandbox()
+    if backend_override == "subprocess":
+        return RestrictedSubprocessSandbox(
+            allowed_roots=allowed_roots, cpu_seconds=cpu_limit_s, memory_bytes=memory_limit_bytes
+        )
+    if backend_override == "none":
+        return NullSandbox()
+    if backend_override not in ("auto", ""):
+        raise ValueError(
+            f"Unknown sandbox_backend '{backend_override}' — valid values are 'auto', 'docker', "
+            "'subprocess', or 'none'. Set sandbox_backend in config.toml or via "
+            "PCLI_SANDBOX_BACKEND."
+        )
+
+    if await probe_docker_available():
+        return DockerSandbox()
+    return RestrictedSubprocessSandbox(
+        allowed_roots=allowed_roots, cpu_seconds=cpu_limit_s, memory_bytes=memory_limit_bytes
+    )