monkeybot 2.1.1__py3-none-any.whl

monkeybot/core/tools/permission.py

@@ -0,0 +1,284 @@
+"""Permission ruleset DSL: last-match-wins allow / ask / deny + session approvals.
+
+Soft preflight layer on top of hard execution constraints (command allowlists +
+sandbox). Patterns use ``fnmatch`` wildcards (``*``, ``?``) against tool name and
+a normalized resource string.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import logging
+import shlex
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal, cast
+
+import yaml
+
+from monkeybot.core.context import TurnContext
+from monkeybot.core.logging_utils import kv
+from monkeybot.core.tools.inspector import (
+    Decision,
+    InspectorToolCall,
+    norm_run_command_line,
+)
+from monkeybot.core.types.interfaces import MonkeybotError
+
+logger = logging.getLogger(__name__)
+
+Effect = Literal["allow", "ask", "deny"]
+
+
+class PermissionConfigError(MonkeybotError):
+    """Invalid or unloadable permissions YAML."""
+
+    def __init__(self, path: Path, reason: str) -> None:
+        self.path = path
+        self.reason = reason
+        super().__init__(f"{path}: {reason}")
+
+
+@dataclass(frozen=True)
+class PermissionRule:
+    """One ruleset entry. Evaluation is last-match-wins across the ordered list."""
+
+    tool: str
+    pattern: str
+    effect: Effect
+    message: str | None = None
+
+
+@dataclass(frozen=True)
+class PermissionRuleset:
+    """Loaded permissions config."""
+
+    rules: tuple[PermissionRule, ...]
+    default: Effect = "allow"
+
+
+def resource_for_call(call: InspectorToolCall) -> str:
+    """Normalize a tool call into a single resource string for pattern matching."""
+    if call.name == "run_command":
+        line = norm_run_command_line(call.args)
+        if line:
+            return line
+    path = call.args.get("path")
+    if isinstance(path, str) and path.strip():
+        return path.strip()
+    argv = call.args.get("argv")
+    if isinstance(argv, list) and argv:
+        return shlex.join(str(x) for x in argv)
+    command = call.args.get("command")
+    if isinstance(command, str) and command.strip():
+        return " ".join(command.strip().split())
+    # Stable fallback for tool calls with none of the recognized shapes above.
+    # Sort keys so the same logical args produce the same resource string
+    # regardless of dict insertion order (e.g. across provider round-trips).
+    return json.dumps(call.args, sort_keys=True, default=str)
+
+
+def _match(rule: PermissionRule, tool: str, resource: str) -> bool:
+    return fnmatch.fnmatchcase(tool, rule.tool) and fnmatch.fnmatchcase(
+        resource, rule.pattern
+    )
+
+
+def evaluate(tool: str, resource: str, rules: tuple[PermissionRule, ...]) -> PermissionRule | None:
+    """Return the last matching rule, or ``None`` if nothing matched."""
+    matched: PermissionRule | None = None
+    for rule in rules:
+        if _match(rule, tool, resource):
+            matched = rule
+    return matched
+
+
+def load_permissions(path: Path) -> PermissionRuleset:
+    """Load ``permissions.yaml`` (``default`` + ordered ``rules``)."""
+    raw_bytes = path.read_bytes()
+    try:
+        data = yaml.safe_load(raw_bytes)
+    except yaml.YAMLError as e:
+        raise PermissionConfigError(path, f"invalid YAML: {e}") from e
+
+    if data is None:
+        return PermissionRuleset(rules=(), default="allow")
+    if not isinstance(data, dict):
+        raise PermissionConfigError(path, "root must be a mapping")
+
+    default_raw = data.get("default", "allow")
+    if default_raw not in ("allow", "ask", "deny"):
+        raise PermissionConfigError(
+            path, f"'default' must be allow|ask|deny, got {default_raw!r}"
+        )
+    default = cast(Effect, default_raw)
+
+    rules_raw = data.get("rules", [])
+    if rules_raw is None:
+        rules_raw = []
+    if not isinstance(rules_raw, list):
+        raise PermissionConfigError(path, "'rules' must be a list")
+
+    rules: list[PermissionRule] = []
+    for i, item in enumerate(rules_raw):
+        if not isinstance(item, dict):
+            raise PermissionConfigError(path, f"rules[{i}] must be a mapping")
+        tool = item.get("tool")
+        pattern = item.get("pattern", "*")
+        effect = item.get("effect")
+        message = item.get("message")
+        if not isinstance(tool, str) or not tool.strip():
+            raise PermissionConfigError(path, f"rules[{i}].tool must be a non-empty string")
+        if not isinstance(pattern, str) or not pattern.strip():
+            raise PermissionConfigError(
+                path, f"rules[{i}].pattern must be a non-empty string"
+            )
+        if effect not in ("allow", "ask", "deny"):
+            raise PermissionConfigError(
+                path, f"rules[{i}].effect must be allow|ask|deny, got {effect!r}"
+            )
+        if message is not None and not isinstance(message, str):
+            raise PermissionConfigError(path, f"rules[{i}].message must be a string")
+        rules.append(
+            PermissionRule(
+                tool=tool.strip(),
+                pattern=pattern.strip(),
+                effect=cast(Effect, effect),
+                message=message,
+            )
+        )
+
+    return PermissionRuleset(rules=tuple(rules), default=default)
+
+
+@dataclass
+class SessionApprovals:
+    """In-memory session-scoped 'always allow' rememberies (OpenCode ``reply: always``).
+
+    Process-local only (same durability class as ``SessionBus.admission``): not
+    shared across gateway replicas and lost on restart.
+    """
+
+    _keys: set[tuple[str, str]] = field(default_factory=set)
+
+    def is_allowed(self, tool: str, resource: str) -> bool:
+        return (tool, resource) in self._keys
+
+    def remember(self, tool: str, resource: str) -> None:
+        self._keys.add((tool, resource))
+
+
+def remember_always_approval(bus: object | None, tool: str, resource: str) -> None:
+    """Record a session "always allow" approval on ``bus.session_approvals`` if present.
+
+    Shared by the text (``loop.py``) and realtime (``realtime_loop.py``) HITL confirm
+    paths so the ``payload.get("always")`` handling isn't duplicated across both.
+    No-op when ``bus`` is ``None`` or has no ``session_approvals`` attribute.
+    """
+    approvals = getattr(bus, "session_approvals", None)
+    if approvals is not None:
+        approvals.remember(tool, resource)
+
+
+def _decision_from_effect(effect: Effect, message: str | None) -> Decision:
+    if effect == "allow":
+        return Decision(kind="allow")
+    if effect == "deny":
+        return Decision(kind="deny", message=message or "denied by permission ruleset")
+    return Decision(kind="confirm", message=message or "Approval required for this tool call")
+
+
+class PermissionInspector:
+    """``ToolInspector`` that evaluates a last-match-wins permission ruleset.
+
+    Session approvals (when present on ``ctx.sse_bus.session_approvals``) short-circuit
+    to allow before ruleset evaluation.
+
+    ``allow_ask`` controls whether an ``ask`` effect may prompt interactively
+    (``confirm``, the default) or must resolve deterministically. Set
+    ``allow_ask=False`` for non-interactive callers (e.g. subagents) that have
+    no session to prompt: ``ask`` is then treated as ``deny`` rather than
+    surfacing a confirmation that can never be answered.
+    """
+
+    def __init__(self, ruleset: PermissionRuleset, *, allow_ask: bool = True) -> None:
+        self._ruleset = ruleset
+        self._allow_ask = allow_ask
+
+    @property
+    def ruleset(self) -> PermissionRuleset:
+        return self._ruleset
+
+    async def check(self, call: InspectorToolCall, ctx: TurnContext) -> Decision:
+        resource = resource_for_call(call)
+        bus = ctx.sse_bus
+        if bus is not None:
+            approvals = getattr(bus, "session_approvals", None)
+            if isinstance(approvals, SessionApprovals) and approvals.is_allowed(
+                call.name, resource
+            ):
+                logger.debug(
+                    "permission session allow %s",
+                    kv(tool=call.name, call_id=call.call_id, resource=resource),
+                )
+                return Decision(kind="allow")
+
+        matched = evaluate(call.name, resource, self._ruleset.rules)
+        effect = self._ruleset.default if matched is None else matched.effect
+        message = None if matched is None else matched.message
+        if effect == "ask" and not self._allow_ask:
+            logger.debug(
+                "permission ask->deny (no interactive session) %s",
+                kv(tool=call.name, call_id=call.call_id, resource=resource),
+            )
+            return Decision(
+                kind="deny",
+                message=message or "ask effect requires an interactive session; denied",
+            )
+        return _decision_from_effect(effect, message)
+
+
+def try_load_permission_inspector(
+    path: Path, *, allow_ask: bool = True
+) -> PermissionInspector | None:
+    """Load ``permissions.yaml`` into an inspector, or ``None`` if missing/invalid.
+
+    Missing file → ``None`` (logged at info). Invalid YAML → ``None`` (logged at
+    exception). Soft ruleset is fail-open; hard allowlists/sandbox still apply.
+    ``allow_ask`` is forwarded to :class:`PermissionInspector` (set ``False`` for
+    non-interactive callers such as subagents; ``ask`` then resolves to ``deny``).
+    """
+    try:
+        ruleset = load_permissions(path)
+    except FileNotFoundError:
+        logger.info("permissions.yaml missing (%s); soft ruleset disabled", path)
+        return None
+    except PermissionConfigError:
+        logger.exception("permission ruleset load failed (%s)", path)
+        return None
+    except Exception:
+        logger.exception("permission ruleset load failed (%s)", path)
+        return None
+    logger.info(
+        "permission ruleset loaded (%s rules, default=%s, allow_ask=%s)",
+        len(ruleset.rules),
+        ruleset.default,
+        allow_ask,
+    )
+    return PermissionInspector(ruleset, allow_ask=allow_ask)
+
+
+__all__ = [
+    "Effect",
+    "PermissionConfigError",
+    "PermissionInspector",
+    "PermissionRule",
+    "PermissionRuleset",
+    "SessionApprovals",
+    "evaluate",
+    "load_permissions",
+    "remember_always_approval",
+    "resource_for_call",
+    "try_load_permission_inspector",
+]

monkeybot/core/tools/sandbox_executor.py

@@ -0,0 +1,255 @@
+"""Sandbox-backed command executor using OpenSandbox.
+
+Drop-in replacement for TerminalExecutor when SANDBOX_ENABLED=true.
+Routes run_command through an isolated Docker container managed by the
+OpenSandbox server, while preserving the binary allowlist from TerminalExecutor.
+
+The workspace directory is mounted read-write into the sandbox container at
+the same absolute path, so file writes from run_command persist to the host
+filesystem immediately and all relative agent paths resolve identically.
+
+One sandbox is created per SandboxExecutor instance (session-scoped) and
+reused across all run_command calls in that session. The sandbox is created
+lazily on the first execute() call so there is zero overhead when run_command
+is never invoked.
+
+Configuration (all via env vars or monkeybot.yaml sandbox.*):
+    SANDBOX_ENABLED            - "true" to activate (default: "false")
+    SANDBOX_SERVER_URL         - OpenSandbox server URL (default: http://localhost:8080)
+    SANDBOX_IMAGE              - Container image to run (default: python:3.12)
+    SANDBOX_API_KEY            - API key for the server (env-only, optional)
+    SANDBOX_TTL_SECONDS        - Sandbox lifetime in seconds (env-only, default: 1800)
+    SANDBOX_USE_SERVER_PROXY   - default "true": route health/exec via OpenSandbox HTTP API
+      (required for Docker Desktop when the server runs in a container). "false" if the SDK
+      host can reach sandbox ports directly.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import shlex
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import timedelta
+from pathlib import Path
+from typing import Any
+
+from monkeybot.core.tools.terminal import ALLOWED_PATHS, ALLOWED_COMMANDS, ExecutionResult, SecurityError, build_skill_runtime_env
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SandboxConfig:
+    """Configuration for the OpenSandbox integration.
+
+    Populated from environment variables set by monkeybot.yaml or directly.
+    Only SANDBOX_ENABLED=true (exact, case-insensitive) activates the sandbox.
+    """
+
+    enabled: bool
+    server_url: str
+    api_key: str | None
+    image: str
+    ttl_seconds: int
+    use_server_proxy: bool = True
+
+    @classmethod
+    def from_env(cls) -> "SandboxConfig":
+        raw_ttl = os.getenv("SANDBOX_TTL_SECONDS", "1800")
+        try:
+            ttl = int(raw_ttl)
+        except ValueError:
+            raise ValueError(
+                f"SANDBOX_TTL_SECONDS must be an integer, got: {raw_ttl!r}"
+            )
+        api_key = os.getenv("SANDBOX_API_KEY") or None
+        proxy_raw = os.getenv("SANDBOX_USE_SERVER_PROXY", "true").strip().lower()
+        use_server_proxy = proxy_raw not in ("0", "false", "no", "off")
+        return cls(
+            enabled=os.getenv("SANDBOX_ENABLED", "false").lower() == "true",
+            server_url=os.getenv("SANDBOX_SERVER_URL", "http://localhost:8080"),
+            api_key=api_key,
+            image=os.getenv("SANDBOX_IMAGE", "python:3.12"),
+            ttl_seconds=ttl,
+            use_server_proxy=use_server_proxy,
+        )
+
+
+class SandboxExecutor:
+    """Command executor that routes shell commands through an OpenSandbox container.
+
+    Same interface as TerminalExecutor.execute(). Binary allowlist from
+    terminal.py is applied before dispatch (defense-in-depth — the container
+    provides OS-level isolation, the allowlist enforces the command policy).
+
+    The sandbox is created lazily on the first execute() call and reused for
+    the lifetime of this instance (session-scoped). The workspace directory is
+    mounted read-write at its absolute path inside the container so file writes
+    persist to the host filesystem immediately.
+
+    Call aclose() to destroy the sandbox early; otherwise it expires after
+    ttl_seconds automatically.
+    """
+
+    def __init__(
+        self,
+        config: SandboxConfig,
+        workspace_root: Path,
+        *,
+        allowed_commands: Sequence[str] | None = None,
+    ) -> None:
+        self._config = config
+        self._workspace_root = Path(workspace_root).resolve()
+        self._sandbox: Any = None
+        self._allowed_commands: tuple[str, ...] = (
+            tuple(allowed_commands) if allowed_commands is not None else tuple(ALLOWED_COMMANDS)
+        )
+
+    @property
+    def allowed_commands(self) -> tuple[str, ...]:
+        return self._allowed_commands
+
+    @property
+    def allowed_path_prefixes(self) -> tuple[str, ...]:
+        """Path prefixes allowed for ``run_command`` error hints (host uses :class:`TerminalExecutor`)."""
+        return tuple(ALLOWED_PATHS)
+
+    async def _ensure_sandbox(self) -> None:
+        if self._sandbox is not None:
+            return
+
+        try:
+            from opensandbox import Sandbox
+            from opensandbox.config import ConnectionConfig
+            from opensandbox.models.sandboxes import Host, Volume
+        except ImportError as exc:
+            raise RuntimeError(
+                "opensandbox SDK is required for sandbox execution but is not installed. "
+                "Install it with: pip install 'monkeybot[sandbox]'"
+            ) from exc
+
+        workspace_str = str(self._workspace_root)
+        logger.info(
+            "Creating sandbox: image=%s ttl=%ss workspace=%s",
+            self._config.image,
+            self._config.ttl_seconds,
+            workspace_str,
+        )
+
+        # Parse server_url into domain + protocol for ConnectionConfig.
+        # server_url format: "http://host:port" or "https://host:port"
+        match = re.fullmatch(r"(https?)://(.+)", self._config.server_url.rstrip("/"))
+        if not match:
+            raise ValueError(
+                f"SANDBOX_SERVER_URL must be http(s)://host[:port], got: {self._config.server_url!r}"
+            )
+        protocol, domain = match.group(1), match.group(2)
+
+        connection_config = ConnectionConfig(
+            domain=domain,
+            api_key=self._config.api_key,
+            protocol=protocol,
+            use_server_proxy=self._config.use_server_proxy,
+        )
+
+        # Derive a DNS-safe volume name from the workspace path (max 63 chars).
+        vol_name = re.sub(r"[^a-z0-9-]", "-", workspace_str.lower()).strip("-")[:63]
+
+        runtime_env = build_skill_runtime_env(cwd=self._workspace_root)
+        volumes = [
+            Volume(
+                name=vol_name or "workspace",
+                host=Host(path=workspace_str),
+                mountPath=workspace_str,
+                readOnly=False,
+            )
+        ]
+        mounted_paths = {workspace_str}
+        for cred_env in ("GOOGLE_APPLICATION_CREDENTIALS", "GCP_AUTH_FILE"):
+            cred_path = runtime_env.get(cred_env, "").strip()
+            if not cred_path or cred_path in mounted_paths:
+                continue
+            if not Path(cred_path).is_file():
+                continue
+            cred_vol_name = re.sub(r"[^a-z0-9-]", "-", cred_path.lower()).strip("-")[:63]
+            volumes.append(
+                Volume(
+                    name=cred_vol_name or "gcp-creds",
+                    host=Host(path=cred_path),
+                    mountPath=cred_path,
+                    readOnly=True,
+                )
+            )
+            mounted_paths.add(cred_path)
+
+        self._sandbox = await Sandbox.create(
+            self._config.image,
+            connection_config=connection_config,
+            timeout=timedelta(seconds=self._config.ttl_seconds),
+            env=runtime_env,
+            volumes=volumes,
+        )
+        logger.info("Sandbox created: id=%s", getattr(self._sandbox, "id", "unknown"))
+
+    async def execute(
+        self,
+        command: str,
+        args: list[str],
+        *,
+        timeout: int = 60,
+        cwd: Path | str | None = None,
+    ) -> ExecutionResult:
+        """Execute a command inside the sandbox container.
+
+        Binary allowlist from ALLOWED_COMMANDS is enforced before the sandbox
+        is created or contacted. A blocked command raises SecurityError without
+        ever touching the OpenSandbox server.
+        """
+        if command not in self._allowed_commands:
+            raise SecurityError(f"Command '{command}' not allowed")
+
+        await self._ensure_sandbox()
+
+        full_cmd = " ".join([command] + [shlex.quote(a) for a in args])
+        logger.info("Sandbox execute: %s", full_cmd)
+
+        from opensandbox.models.execd import RunCommandOpts
+
+        workdir = str(Path(cwd).resolve()) if cwd is not None else str(self._workspace_root)
+        execution = await self._sandbox.commands.run(
+            full_cmd,
+            opts=RunCommandOpts(
+                timeout=timedelta(seconds=timeout),
+                working_directory=workdir,
+            ),
+        )
+
+        stdout_entries = execution.logs.stdout or []
+        stderr_entries = execution.logs.stderr or []
+        stdout = "".join(getattr(e, "text", str(e)) for e in stdout_entries)
+        stderr = "".join(getattr(e, "text", str(e)) for e in stderr_entries)
+
+        return ExecutionResult(
+            stdout=stdout,
+            stderr=stderr,
+            exit_code=execution.exit_code if execution.exit_code is not None else 0,
+        )
+
+    async def aclose(self) -> None:
+        """Destroy the sandbox container.
+
+        Safe to call multiple times (idempotent). Exceptions from kill() are
+        swallowed so the gateway finally block always completes cleanly.
+        """
+        if self._sandbox is None:
+            return
+        sandbox = self._sandbox
+        self._sandbox = None
+        try:
+            await sandbox.kill()
+            logger.info("Sandbox destroyed")
+        except Exception:
+            logger.warning("Failed to destroy sandbox", exc_info=True)

monkeybot/core/tools/spill_inventory.py

@@ -0,0 +1,35 @@
+"""Spill-file inventory notes for large tool outputs."""
+
+from __future__ import annotations
+
+from monkeybot.core.runtime.context_budget import diff_inventory_lines
+
+_INVENTORY_PREFIX = "[Spill inventory —"
+
+
+def spill_inventory_note(text: str, rel_spill_path: str) -> str:
+    """Build an inventory note appended to large tool results."""
+    total_chars = len(text)
+    total_lines = text.count("\n") + (1 if text and not text.endswith("\n") else 0)
+    parts = [
+        f"{_INVENTORY_PREFIX} {total_chars} total chars, {total_lines} total lines.",
+    ]
+    paths = diff_inventory_lines(text)
+    if paths:
+        parts.append(f"Changed files ({len(paths)}): " + ", ".join(paths[:80]))
+        if len(paths) > 80:
+            parts.append(f"... and {len(paths) - 80} more paths")
+    parts.append(
+        f"Full output at: {rel_spill_path} — use read_file with offset/limit to page through it.]"
+    )
+    return "\n".join(parts)
+
+
+def spill_min_chars_from_env() -> int:
+    import os
+
+    raw = os.environ.get("MONKEYBOT_SPILL_MIN_CHARS", "8000").strip()
+    try:
+        return max(0, int(raw))
+    except ValueError:
+        return 8000