agents-function-tools 0.2.0__py3-none-any.whl

function_tools/command.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import FoundationToolError
+from .workspace import Workspace
+
+
+@dataclass(frozen=True)
+class CommandPolicy:
+    """Host-owned aliases for executables that an Agent may invoke."""
+
+    programs: Mapping[str, str] = field(default_factory=dict)
+    max_timeout_seconds: int = 300
+    max_output_chars: int = 65_536
+    max_arguments: int = 64
+
+    def __post_init__(self) -> None:
+        if self.max_timeout_seconds <= 0:
+            raise FoundationToolError("INVALID_LIMIT", "Command timeout limit must be positive.")
+        if self.max_output_chars <= 0:
+            raise FoundationToolError("INVALID_LIMIT", "Output limit must be positive.")
+        if self.max_arguments <= 0:
+            raise FoundationToolError("INVALID_LIMIT", "Argument limit must be positive.")
+
+    def executable_for(self, alias: str) -> str:
+        normalized = alias.strip()
+        if not normalized or normalized not in self.programs:
+            allowed = ", ".join(sorted(self.programs)) or "none"
+            raise FoundationToolError(
+                "PROGRAM_NOT_ALLOWED", f"Program alias is not allowed. Allowed aliases: {allowed}."
+            )
+        executable = self.programs[normalized]
+        if not executable or "\x00" in executable:
+            raise FoundationToolError(
+                "INVALID_PROGRAM_MAPPING", f"Program mapping for {normalized} is invalid."
+            )
+        return executable
+
+    def describe(self) -> dict[str, Any]:
+        """Return policy metadata without revealing host executable paths."""
+
+        return {
+            "program_aliases": sorted(self.programs),
+            "max_timeout_seconds": self.max_timeout_seconds,
+            "max_output_chars": self.max_output_chars,
+            "max_arguments": self.max_arguments,
+            "shell": False,
+        }
+
+
+class LocalCommandRunner:
+    """Run allowlisted commands without a shell inside a workspace directory."""
+
+    def __init__(self, workspace: Workspace, policy: CommandPolicy) -> None:
+        self.workspace = workspace
+        self.policy = policy
+
+    def run(
+        self,
+        program: str,
+        args: Sequence[str] = (),
+        *,
+        cwd: str = ".",
+        timeout_seconds: int = 30,
+    ) -> dict[str, Any]:
+        if not 1 <= timeout_seconds <= self.policy.max_timeout_seconds:
+            raise FoundationToolError(
+                "INVALID_TIMEOUT",
+                f"timeout_seconds must be between 1 and {self.policy.max_timeout_seconds}.",
+            )
+        if len(args) > self.policy.max_arguments:
+            raise FoundationToolError(
+                "TOO_MANY_ARGUMENTS",
+                f"Command cannot exceed {self.policy.max_arguments} arguments.",
+            )
+        normalized_args = [self._validate_argument(argument) for argument in args]
+        executable = self.policy.executable_for(program)
+        working_directory = self.workspace.resolve_directory(cwd)
+
+        command = [executable, *normalized_args]
+        popen_options: dict[str, Any] = {
+            "cwd": working_directory,
+            "env": self._restricted_environment(),
+            "stdin": subprocess.DEVNULL,
+            "stdout": subprocess.PIPE,
+            "stderr": subprocess.PIPE,
+            "text": True,
+            "encoding": "utf-8",
+            "errors": "replace",
+            "shell": False,
+        }
+        if os.name == "nt":
+            popen_options["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+        else:
+            popen_options["start_new_session"] = True
+
+        try:
+            process = subprocess.Popen(command, **popen_options)
+        except FileNotFoundError as error:
+            raise FoundationToolError(
+                "PROGRAM_NOT_FOUND", f"Configured executable for {program} was not found."
+            ) from error
+        except OSError as error:
+            raise FoundationToolError("COMMAND_START_FAILED", str(error)) from error
+
+        timed_out = False
+        try:
+            stdout, stderr = process.communicate(timeout=timeout_seconds)
+        except subprocess.TimeoutExpired:
+            timed_out = True
+            self._terminate_process_tree(process)
+            stdout, stderr = process.communicate()
+
+        stdout, stdout_truncated = self._truncate(stdout)
+        stderr, stderr_truncated = self._truncate(stderr)
+        return {
+            "program": program,
+            "args": normalized_args,
+            "cwd": self.workspace.relative_path(working_directory),
+            "return_code": 124 if timed_out else process.returncode,
+            "stdout": stdout,
+            "stderr": stderr,
+            "timed_out": timed_out,
+            "output_truncated": stdout_truncated or stderr_truncated,
+            "executor": "local_restricted",
+        }
+
+    def _validate_argument(self, argument: str) -> str:
+        if not isinstance(argument, str):
+            raise FoundationToolError("INVALID_ARGUMENT", "All command arguments must be strings.")
+        if "\x00" in argument:
+            raise FoundationToolError("INVALID_ARGUMENT", "Command arguments cannot contain NUL.")
+        if len(argument) > 4_096:
+            raise FoundationToolError(
+                "ARGUMENT_TOO_LONG", "A command argument cannot exceed 4096 characters."
+            )
+        return argument
+
+    def _restricted_environment(self) -> dict[str, str]:
+        names = ("PATH", "SYSTEMROOT", "WINDIR", "TEMP", "TMP", "LANG", "LC_ALL")
+        return {name: os.environ[name] for name in names if name in os.environ}
+
+    def _terminate_process_tree(self, process: subprocess.Popen[str]) -> None:
+        if process.poll() is not None:
+            return
+        try:
+            if os.name == "nt":
+                result = subprocess.run(
+                    ["taskkill", "/PID", str(process.pid), "/T", "/F"],
+                    stdin=subprocess.DEVNULL,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    check=False,
+                    shell=False,
+                )
+                if result.returncode != 0 or process.poll() is None:
+                    process.kill()
+            else:
+                os.killpg(process.pid, signal.SIGKILL)
+        except OSError:
+            process.kill()
+
+    def _truncate(self, value: str) -> tuple[str, bool]:
+        if len(value) <= self.policy.max_output_chars:
+            return value, False
+        return value[: self.policy.max_output_chars], True

function_tools/errors.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+
+class FoundationToolError(Exception):
+    """A safe, structured error that can be returned to an Agent."""
+
+    def __init__(self, code: str, message: str, *, retryable: bool = False) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.retryable = retryable

function_tools/host.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from collections.abc import Iterable
+from datetime import datetime, timezone
+from typing import Any
+
+from .errors import FoundationToolError
+
+
+class HostInspector:
+    """Non-sensitive host metadata exposed by explicit allowlist only."""
+
+    def __init__(self, environment_variables: Iterable[str] = ()) -> None:
+        self.environment_variables = frozenset(environment_variables)
+
+    def system_info(self) -> dict[str, Any]:
+        return {
+            "os_name": os.name,
+            "platform": platform.system(),
+            "platform_release": platform.release(),
+            "machine": platform.machine(),
+            "python_version": platform.python_version(),
+            "cpu_count": os.cpu_count(),
+        }
+
+    def current_time(self) -> dict[str, Any]:
+        now = datetime.now(timezone.utc)
+        return {"utc": now.isoformat(), "epoch_seconds": now.timestamp()}
+
+    def environment(self, name: str) -> dict[str, Any]:
+        if name not in self.environment_variables:
+            allowed = ", ".join(sorted(self.environment_variables)) or "none"
+            raise FoundationToolError(
+                "ENVIRONMENT_VARIABLE_NOT_ALLOWED",
+                f"Environment variable is not allowed. Allowed names: {allowed}.",
+            )
+        return {"name": name, "value": os.environ.get(name), "is_set": name in os.environ}
+
+    def runtime_info(self) -> dict[str, Any]:
+        return {"python_executable": sys.executable, "python_prefix": sys.prefix}

function_tools/http.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import ipaddress
+import socket
+import ssl
+from dataclasses import dataclass
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlparse
+from urllib.request import HTTPRedirectHandler, HTTPSHandler, Request, build_opener
+
+from .errors import FoundationToolError
+
+
+@dataclass(frozen=True)
+class HttpPolicy:
+    """Explicit egress policy for small, text-only HTTP reads."""
+
+    allowed_hosts: frozenset[str] = frozenset()
+    max_response_bytes: int = 1_000_000
+    timeout_seconds: int = 15
+    allow_private_addresses: bool = False
+
+    def __post_init__(self) -> None:
+        if self.max_response_bytes <= 0 or self.timeout_seconds <= 0:
+            raise FoundationToolError("INVALID_LIMIT", "HTTP limits must be positive.")
+
+
+class _RejectRedirects(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        raise HTTPError(req.full_url, code, "Redirects are not allowed.", headers, fp)
+
+
+class HttpTextClient:
+    """Fetch a bounded UTF-8 response from an exact host allowlist."""
+
+    def __init__(self, policy: HttpPolicy) -> None:
+        self.policy = policy
+
+    def fetch(self, url: str) -> dict[str, Any]:
+        parsed = self._validate_url(url)
+        self._validate_addresses(parsed.hostname or "")
+        request = Request(
+            url,
+            headers={
+                "User-Agent": "company-agent-service/0.1",
+                "Accept": "text/plain,text/html,application/json",
+            },
+        )
+        opener = build_opener(
+            _RejectRedirects(), HTTPSHandler(context=ssl.create_default_context())
+        )
+        try:
+            with opener.open(request, timeout=self.policy.timeout_seconds) as response:
+                content_type = response.headers.get_content_type()
+                if content_type not in {
+                    "text/plain",
+                    "text/html",
+                    "application/json",
+                    "application/xml",
+                    "text/xml",
+                }:
+                    raise FoundationToolError(
+                        "UNSUPPORTED_CONTENT_TYPE", f"Content type is not allowed: {content_type}."
+                    )
+                raw = response.read(self.policy.max_response_bytes + 1)
+                if len(raw) > self.policy.max_response_bytes:
+                    raise FoundationToolError(
+                        "RESPONSE_TOO_LARGE", "Response exceeds the configured byte limit."
+                    )
+                charset = response.headers.get_content_charset() or "utf-8"
+        except FoundationToolError:
+            raise
+        except HTTPError as error:
+            raise FoundationToolError(
+                "HTTP_ERROR",
+                f"HTTP request failed with status {error.code}.",
+                retryable=error.code >= 500,
+            ) from error
+        except (URLError, OSError) as error:
+            raise FoundationToolError(
+                "HTTP_FETCH_FAILED", "HTTP request could not be completed.", retryable=True
+            ) from error
+        try:
+            content = raw.decode(charset)
+        except (LookupError, UnicodeDecodeError) as error:
+            raise FoundationToolError(
+                "RESPONSE_NOT_TEXT", "Response cannot be decoded as declared text."
+            ) from error
+        return {"url": url, "content_type": content_type, "content": content, "bytes": len(raw)}
+
+    def _validate_url(self, url: str):
+        parsed = urlparse(url)
+        host = (parsed.hostname or "").lower()
+        try:
+            port = parsed.port
+        except ValueError as error:
+            raise FoundationToolError("INVALID_URL", "URL port is invalid.") from error
+        if (
+            parsed.scheme != "https"
+            or not host
+            or port not in {None, 443}
+            or parsed.username
+            or parsed.password
+        ):
+            raise FoundationToolError(
+                "INVALID_URL", "Only HTTPS default-port URLs without user credentials are allowed."
+            )
+        if host not in self.policy.allowed_hosts:
+            allowed = ", ".join(sorted(self.policy.allowed_hosts)) or "none"
+            raise FoundationToolError(
+                "HOST_NOT_ALLOWED", f"Host is not allowed. Allowed hosts: {allowed}."
+            )
+        return parsed
+
+    def _validate_addresses(self, hostname: str) -> None:
+        try:
+            addresses = {
+                item[4][0] for item in socket.getaddrinfo(hostname, None, type=socket.SOCK_STREAM)
+            }
+        except socket.gaierror as error:
+            raise FoundationToolError(
+                "DNS_LOOKUP_FAILED", "Allowed host could not be resolved.", retryable=True
+            ) from error
+        if not addresses:
+            raise FoundationToolError(
+                "DNS_LOOKUP_FAILED", "Allowed host has no resolved addresses."
+            )
+        if self.policy.allow_private_addresses:
+            return
+        for address in addresses:
+            ip = ipaddress.ip_address(address)
+            if not ip.is_global:
+                raise FoundationToolError(
+                    "PRIVATE_ADDRESS_BLOCKED", "Resolved address is not public."
+                )