minimalcode 1.5.2__py3-none-any.whl

minimalcode/tools/process.py

@@ -0,0 +1,164 @@
+"""Shell and subagent execution tools."""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+from ..errors import ToolError
+from ..provider.anthropic_env import ANTHROPIC_ENV_PROVIDER
+from ..shell import MAX_TIMEOUT_SECONDS, powershell_heredoc_delimiter, run_shell
+from ..subagent import PREAMBLE as SUBAGENT_PREAMBLE
+from ..subagent import build_command as build_subagent_command
+from ..subagent import child_env as subagent_env
+
+_POWERSHELL_KINDS = frozenset({"pwsh7", "windows_powershell"})
+
+
+def _clamp_timeout(value: float) -> float:
+    """Apply the ceiling `run_shell` enforces, so the reported value is real."""
+    return max(1.0, min(value, MAX_TIMEOUT_SECONDS))
+
+
+class ProcessToolsMixin:
+    """Run commands and nested agents inside the active sandbox policy."""
+
+    def _subagent_sandbox_options(self) -> tuple[list[str], list[tuple[str, str]]]:
+        """Mirror the current in-memory sandbox policy onto the child command.
+
+        CLI flags are applied to ``settings.data`` in memory only; without this
+        the child reloads ``settings.json`` and silently drops ``--sandbox``,
+        ``--sandbox-network``, and the other per-run overrides.
+        """
+        policy = self.sandbox.policy
+        if not policy.enabled:
+            return ["--no-sandbox"], []
+        flags = ["--sandbox"]
+        options: list[tuple[str, str]] = [
+            ("--sandbox-backend", policy.backend),
+            ("--sandbox-network", policy.network_policy),
+            ("--sandbox-timeout", f"{policy.timeout_seconds:g}"),
+            ("--sandbox-max-output", str(policy.max_output_chars)),
+        ]
+        for root in policy.allowed_roots:
+            options.append(("--sandbox-root", str(root)))
+        for host in policy.allowed_hosts:
+            options.append(("--sandbox-allow-host", host))
+        flags.append(
+            "--sandbox-allow-sensitive"
+            if policy.allow_sensitive_files
+            else "--no-sandbox-allow-sensitive"
+        )
+        return flags, options
+
+    def shell(
+        self, command: str, timeout: float | None = None, cwd: str = "."
+    ) -> dict[str, Any]:
+        """Run one command in the configured shell and workspace."""
+        if not isinstance(command, str):
+            raise ToolError("command must be a string")
+        if self.shell_spec.kind in _POWERSHELL_KINDS:
+            delimiter = powershell_heredoc_delimiter(command)
+            if delimiter is not None:
+                raise ToolError(
+                    f"{self.shell_spec.label} does not support bash heredocs "
+                    f"(<<{delimiter}). Write the payload with write/append_file "
+                    "and run the file, use a PowerShell here-string (@'...'@), "
+                    "or pass stdin; the same command will fail again."
+                )
+        workdir = self._path(cwd, operation="execute")
+        if not workdir.is_dir():
+            raise ToolError(f"working directory not found: {workdir}")
+        if timeout is not None and (
+            isinstance(timeout, bool) or not isinstance(timeout, (int, float))
+        ):
+            raise ToolError("timeout must be a number")
+        try:
+            requested_timeout = float(
+                timeout if timeout is not None else self.shell_timeout
+            )
+        except (OverflowError, ValueError) as exc:
+            raise ToolError("timeout must be a number") from exc
+        if math.isnan(requested_timeout):
+            raise ToolError("timeout must be a number")
+        # The configured value is both the default and the hard ceiling.
+        effective_timeout = max(1.0, min(requested_timeout, self.shell_timeout))
+        return run_shell(
+            command,
+            shell=self.shell_spec,
+            cwd=workdir,
+            timeout=effective_timeout,
+            max_output_chars=self.max_output_chars,
+            sandbox=self.sandbox,
+        )
+
+    def subagent(
+        self,
+        task: str,
+        cwd: str = ".",
+        timeout: float | None = None,
+        max_turns: int | None = None,
+    ) -> dict[str, Any]:
+        """Run a nested ``minimalcode -p`` process and return its answer."""
+        if not self.subagent_enabled:
+            raise ToolError(
+                "subagent is disabled here: set subagent.enabled or raise "
+                f"subagent.max_depth (currently {self.subagent_max_depth})"
+            )
+        if not isinstance(task, str) or not task.strip():
+            raise ToolError("task must be a non-empty string")
+        workdir = self._path(cwd, operation="execute")
+        if not workdir.is_dir():
+            raise ToolError(f"working directory not found: {workdir}")
+        if timeout is not None and (
+            isinstance(timeout, bool) or not isinstance(timeout, (int, float))
+        ):
+            raise ToolError("timeout must be a number")
+        try:
+            requested_timeout = float(
+                timeout if timeout is not None else self.subagent_timeout
+            )
+        except (OverflowError, ValueError) as exc:
+            raise ToolError("timeout must be a number") from exc
+        if math.isnan(requested_timeout):
+            raise ToolError("timeout must be a number")
+        limits = [requested_timeout, self.subagent_timeout]
+        if self.sandbox.policy.enabled:
+            # Only an active sandbox caps the child's runtime.
+            limits.append(self.sandbox.policy.timeout_seconds)
+        effective_timeout = _clamp_timeout(min(limits))
+        turns = self.subagent_max_turns if max_turns is None else max_turns
+        if isinstance(turns, bool) or not isinstance(turns, int):
+            raise ToolError("max_turns must be an integer")
+        turns = max(1, min(turns, self.subagent_max_turns))
+
+        sandbox_flags, sandbox_options = self._subagent_sandbox_options()
+        extra_flags = list(sandbox_flags)
+        provider = self.provider_name
+        if provider == ANTHROPIC_ENV_PROVIDER:
+            # The env-derived provider exists only in this process; the child
+            # must rebuild it from the inherited ANTHROPIC_* environment.
+            extra_flags.append("--anthropic-env")
+            provider = None
+        command = build_subagent_command(
+            self.shell_spec,
+            cwd=workdir,
+            home=self.settings.home,
+            provider=provider,
+            model=self.model,
+            thinking=self.thinking,
+            max_turns=turns,
+            extra_flags=extra_flags,
+            extra_options=sandbox_options,
+        )
+        result = run_shell(
+            command,
+            shell=self.shell_spec,
+            cwd=workdir,
+            timeout=effective_timeout,
+            max_output_chars=self.max_output_chars,
+            env=subagent_env(self.subagent_depth + 1),
+            stdin_text=SUBAGENT_PREAMBLE + task.strip(),
+            sandbox=self.sandbox,
+        )
+        return {**result, "command": command, "timeout_seconds": effective_timeout}

minimalcode/tools/remote.py

@@ -0,0 +1,74 @@
+"""Optional provider-backed tools: image understanding and web access."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..errors import ToolError
+from ..vision import SUPPORTED_IMAGE_FORMATS, image_media_type
+
+
+class RemoteToolsMixin:
+    """Tools that delegate to a configured provider client."""
+
+    def read_image(self, path: str, prompt: str | None = None) -> dict[str, Any]:
+        """Describe a workspace image through the provider's vision model."""
+        if not self.vision_enabled or self.vision_client is None:
+            raise ToolError("read_image is not enabled for the current provider")
+        if prompt is not None and not isinstance(prompt, str):
+            raise ToolError("prompt must be a string or null")
+        target = self._path(path, operation="read")
+        if not target.is_file():
+            raise ToolError(f"file not found: {target}")
+        try:
+            # Read one byte past the limit instead of trusting stat(): the file
+            # can grow between the check and the read.
+            with target.open("rb") as handle:
+                data = handle.read(self.vision_client.max_image_bytes + 1)
+        except OSError as exc:
+            raise ToolError(f"cannot read image: {target}: {exc}") from exc
+        if len(data) > self.vision_client.max_image_bytes:
+            raise ToolError(
+                f"image is too large: more than "
+                f"vision.max_image_bytes ({self.vision_client.max_image_bytes})"
+            )
+        media_type = image_media_type(data)
+        if media_type is None:
+            raise ToolError(
+                f"unsupported image format; expected {SUPPORTED_IMAGE_FORMATS}"
+            )
+        description = self.vision_client.describe(
+            media_type, data, question=prompt or None
+        )
+        return {
+            "status": "success",
+            "path": str(target),
+            "media_type": media_type,
+            "bytes": len(data),
+            "description": description,
+        }
+
+    def web_search(
+        self,
+        query: str,
+        count: int | None = None,
+        need_content: bool = False,
+        ori_question: str | None = None,
+        localization: str | None = None,
+    ) -> dict[str, Any]:
+        """Search the web through the configured provider client."""
+        if not self.web_enabled or self.web_client is None:
+            raise ToolError("web tools are not enabled for the current provider")
+        return self.web_client.search(
+            query,
+            count=count,
+            need_content=need_content,
+            ori_question=ori_question,
+            localization=localization,
+        )
+
+    def web_fetch(self, url: str) -> dict[str, Any]:
+        """Fetch one HTTP(S) page through the configured provider client."""
+        if not self.web_enabled or self.web_client is None:
+            raise ToolError("web tools are not enabled for the current provider")
+        return self.web_client.fetch(url)

minimalcode/tools/runtime.py

@@ -0,0 +1,219 @@
+"""The ToolRuntime facade: configuration, path policy, and dispatch."""
+
+from __future__ import annotations
+
+import inspect
+from pathlib import Path
+from typing import Any
+
+from ..config import Settings
+from ..errors import ConfigError, ToolError
+from ..sandbox import SandboxRunner
+from ..shell import ShellSpec
+from ..subagent import depth_from_env as subagent_depth_from_env
+from ..vision import ProviderVisionClient
+from ..web import ProviderWebClient
+from .files import FileToolsMixin
+from .process import ProcessToolsMixin
+from .remote import RemoteToolsMixin
+from .schemas import READ_ONLY_TOOLS, TOOL_NAMES
+from .search_tools import SearchToolsMixin
+from .validation import check_argument_types, clip
+
+
+class ToolRuntime(
+    FileToolsMixin,
+    SearchToolsMixin,
+    ProcessToolsMixin,
+    RemoteToolsMixin,
+):
+    """Execute model tool calls with workspace and sandbox enforcement.
+
+    The methods are grouped into mixins by concern; this class owns the shared
+    settings, path resolver, and dispatcher so every tool sees one policy.
+    """
+
+    def __init__(
+        self,
+        settings: Settings,
+        cwd: Path,
+        shell: ShellSpec,
+        *,
+        web_client: ProviderWebClient | None = None,
+        vision_client: ProviderVisionClient | None = None,
+        provider_name: str | None = None,
+        model: str | None = None,
+        thinking: str | None = None,
+        read_only: bool = False,
+    ):
+        self.settings = settings
+        self.cwd = cwd.resolve()
+        self.shell_spec = shell
+        self.web_client = web_client
+        self.web_enabled = bool(web_client and web_client.enabled)
+        self.vision_client = vision_client
+        self.vision_enabled = bool(vision_client and vision_client.enabled)
+        self.provider_name = provider_name
+        self.model = model
+        self.thinking = thinking
+
+        # Subagent depth is inherited from the child environment so a nested
+        # process cannot recurse without bound.
+        self.subagent_depth = subagent_depth_from_env()
+        self.subagent_max_depth = int(settings.get("subagent.max_depth", 2))
+        self.subagent_enabled = (
+            bool(settings.get("subagent.enabled", True))
+            and self.subagent_depth < self.subagent_max_depth
+        )
+        self.subagent_timeout = float(settings.get("subagent.timeout_seconds", 900))
+        self.subagent_max_turns = int(settings.get("subagent.max_turns", 40))
+        self.subagent_max_parallel = max(
+            1, int(settings.get("subagent.max_parallel", 4))
+        )
+
+        self.allow_outside = bool(settings.get("tools.allow_outside_workspace", False))
+        self.max_file_chars = int(settings.get("tools.max_file_chars", 160_000))
+        self.max_file_bytes = int(settings.get("tools.max_file_bytes", 5_000_000))
+        self.max_results = int(settings.get("tools.max_results", 200))
+        self.max_parallel = max(1, int(settings.get("tools.max_parallel", 4)))
+        # ``tools.allow`` and ``--read-only`` narrow the same set, so the two
+        # compose instead of the flag silently widening what the file allows.
+        self.read_only = bool(read_only)
+        self.allowed_tools = self._allowed_tool_names(
+            settings, read_only=self.read_only
+        )
+        self.shell_timeout = float(settings.get("shell.timeout_seconds", 120))
+        self.max_output_chars = int(settings.get("shell.max_output_chars", 60_000))
+        self.sandbox = SandboxRunner.from_settings(settings, self.cwd)
+        if self.sandbox.policy.enabled:
+            cap = self.sandbox.policy.timeout_seconds
+            if self.subagent_timeout > cap:
+                # A subagent is one sandboxed command, so the policy cap always
+                # wins. Clamp here so the value the tool reports is the value
+                # that actually applies, instead of silently killing the child
+                # at the sandbox timeout.
+                self.subagent_timeout = cap
+                self.sandbox.audit.note(
+                    "subagent.timeout_seconds capped by sandbox.timeout_seconds "
+                    f"({cap:g}s)"
+                )
+
+    @staticmethod
+    def _allowed_tool_names(settings: Settings, *, read_only: bool) -> frozenset[str]:
+        """Resolve ``tools.allow`` and ``--read-only`` into one name set.
+
+        A typo in ``tools.allow`` would otherwise intersect down to an empty
+        set, silently leaving an agent that cannot do anything, so unknown
+        names are a configuration error rather than a no-op.
+        """
+        configured = settings.get("tools.allow")
+        allowed = set(TOOL_NAMES)
+        if configured is not None:
+            if not isinstance(configured, list) or not configured:
+                raise ConfigError("tools.allow must be a non-empty list of tool names")
+            unknown = sorted(
+                str(name)
+                for name in configured
+                if not isinstance(name, str) or name not in TOOL_NAMES
+            )
+            if unknown:
+                raise ConfigError(
+                    "tools.allow contains unknown tools: " + ", ".join(unknown)
+                )
+            allowed &= {name for name in configured if isinstance(name, str)}
+        if read_only:
+            allowed &= READ_ONLY_TOOLS
+        if not allowed:
+            raise ConfigError(
+                "no tools are enabled; widen tools.allow or drop --read-only"
+            )
+        return frozenset(allowed)
+
+    def _path(self, raw: str, *, operation: str = "read") -> Path:
+        """Resolve a tool path through the sandbox's shared policy."""
+        return self.sandbox.resolve_path(
+            raw,
+            cwd=self.cwd,
+            operation=operation,
+            allow_outside=self.allow_outside,
+        )
+
+    def sandbox_summary(self) -> dict[str, Any]:
+        """Return the serializable sandbox status used by the CLI."""
+        return self.sandbox.summary()
+
+    def dispatch(self, name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        """Validate and run one named tool call.
+
+        Lookup is explicit rather than ``getattr`` so a model cannot reach
+        helper methods or private attributes by name.
+        """
+        handlers = {
+            "read": self.read,
+            "read_range": self.read_range,
+            "write": self.write,
+            "append_file": self.append_file,
+            "edit": self.edit,
+            "shell": self.shell,
+            "subagent": self.subagent,
+            "grep": self.grep,
+            "find": self.find,
+            "read_image": self.read_image,
+            "web_search": self.web_search,
+            "web_fetch": self.web_fetch,
+        }
+        handler = handlers.get(name)
+        if handler is None:
+            raise ToolError(f"unknown tool: {name}")
+        if name not in self.allowed_tools:
+            # The model can only ask for what was advertised, but a replayed
+            # session or a provider that ignores the schema list must still be
+            # stopped here: this is the enforcement point, not the schema.
+            reason = (
+                "--read-only"
+                if self.read_only and name not in READ_ONLY_TOOLS
+                else "tools.allow"
+            )
+            raise ToolError(f"tool {name!r} is disabled by {reason}")
+        if not isinstance(arguments, dict):
+            raise ToolError("tool arguments must be an object")
+        try:
+            inspect.signature(handler).bind(**arguments)
+        except TypeError as exc:
+            raise ToolError(f"invalid arguments for {name}: {exc}") from exc
+        check_argument_types(name, handler, arguments)
+        return handler(**arguments)
+
+    @staticmethod
+    def activity(name: str, arguments: dict[str, Any]) -> str:
+        """Return a short one-line preview for the terminal activity stream."""
+        if name == "shell":
+            detail = clip(str(arguments.get("command", "")))
+        elif name == "subagent":
+            detail = clip(str(arguments.get("task", "")))
+        elif name in {
+            "read",
+            "read_range",
+            "write",
+            "append_file",
+            "edit",
+            "read_image",
+        }:
+            detail = clip(str(arguments.get("path", "")))
+        elif name == "grep":
+            detail = (
+                f"{clip(str(arguments.get('pattern', '')))} in "
+                f"{clip(str(arguments.get('path', '.')))}"
+            )
+        elif name == "find":
+            detail = (
+                f"{clip(str(arguments.get('pattern', '*')))} in "
+                f"{clip(str(arguments.get('path', '.')))}"
+            )
+        elif name == "web_search":
+            detail = clip(str(arguments.get("query", "")))
+        elif name == "web_fetch":
+            detail = clip(str(arguments.get("url", "")))
+        else:
+            detail = ""
+        return f"[{name}] {detail}".rstrip()