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

function_tools/workspace.py

@@ -0,0 +1,433 @@
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from fnmatch import fnmatchcase
+from hashlib import new as new_hash
+from pathlib import Path
+from typing import Any
+
+from .errors import FoundationToolError
+
+
+class Workspace:
+    """Filesystem operations confined to one configured directory."""
+
+    def __init__(
+        self,
+        root: str | Path,
+        *,
+        max_read_bytes: int = 1_000_000,
+        max_write_bytes: int = 1_000_000,
+    ) -> None:
+        resolved_root = Path(root).resolve(strict=True)
+        if not resolved_root.is_dir():
+            raise FoundationToolError("INVALID_ROOT", "Workspace root is not a directory.")
+        if max_read_bytes <= 0 or max_write_bytes <= 0:
+            raise FoundationToolError("INVALID_LIMIT", "File byte limits must be positive.")
+
+        self.root = resolved_root
+        self.max_read_bytes = max_read_bytes
+        self.max_write_bytes = max_write_bytes
+
+    def list_directory(
+        self, path: str = ".", *, recursive: bool = False, max_entries: int = 200
+    ) -> dict[str, Any]:
+        if not 1 <= max_entries <= 10_000:
+            raise FoundationToolError("INVALID_LIMIT", "max_entries must be between 1 and 10000.")
+        directory = self.resolve_directory(path)
+        entries: list[dict[str, Any]] = []
+        truncated = False
+
+        if recursive:
+            iterator = self._walk_entries(directory)
+        else:
+            iterator = iter(sorted(directory.iterdir(), key=lambda item: item.name.lower()))
+
+        for entry in iterator:
+            if len(entries) == max_entries:
+                truncated = True
+                break
+            entries.append(self._entry_metadata(entry))
+
+        return {
+            "path": self._relative(directory),
+            "entries": entries,
+            "truncated": truncated,
+        }
+
+    def read_text(self, path: str, *, max_bytes: int | None = None) -> dict[str, Any]:
+        file_path = self._resolve(path)
+        if not file_path.is_file():
+            raise FoundationToolError("NOT_A_FILE", "Path is not a regular file.")
+
+        limit = self.max_read_bytes if max_bytes is None else max_bytes
+        if not 1 <= limit <= self.max_read_bytes:
+            raise FoundationToolError(
+                "INVALID_LIMIT",
+                f"max_bytes must be between 1 and {self.max_read_bytes}.",
+            )
+        size = file_path.stat().st_size
+        if size > limit:
+            raise FoundationToolError(
+                "FILE_TOO_LARGE", f"File is {size} bytes; the read limit is {limit}."
+            )
+
+        try:
+            content = file_path.read_text(encoding="utf-8")
+        except UnicodeDecodeError as error:
+            raise FoundationToolError("NOT_UTF8", "Only UTF-8 text files can be read.") from error
+        except OSError as error:
+            raise FoundationToolError("READ_FAILED", str(error), retryable=True) from error
+
+        return {"path": self._relative(file_path), "content": content, "bytes": size}
+
+    def stat_path(self, path: str) -> dict[str, Any]:
+        """Return non-content metadata for one workspace path."""
+
+        target = self._resolve(path)
+        if not target.exists() and not target.is_symlink():
+            raise FoundationToolError("NOT_FOUND", "Path does not exist.")
+        metadata = self._entry_metadata(target)
+        try:
+            stat = target.lstat()
+        except OSError as error:
+            raise FoundationToolError("STAT_FAILED", str(error), retryable=True) from error
+        metadata.update(
+            {
+                "modified_at_epoch": stat.st_mtime,
+                "created_at_epoch": stat.st_ctime,
+            }
+        )
+        return metadata
+
+    def find_paths(
+        self,
+        pattern: str,
+        *,
+        path: str = ".",
+        kind: str = "any",
+        max_entries: int = 200,
+    ) -> dict[str, Any]:
+        """Find workspace entries using a case-insensitive glob-style filename pattern."""
+
+        if not pattern or "\x00" in pattern:
+            raise FoundationToolError("INVALID_PATTERN", "pattern must be a non-empty string.")
+        if kind not in {"any", "file", "directory", "symlink"}:
+            raise FoundationToolError(
+                "INVALID_KIND", "kind must be any, file, directory, or symlink."
+            )
+        if not 1 <= max_entries <= 10_000:
+            raise FoundationToolError("INVALID_LIMIT", "max_entries must be between 1 and 10000.")
+
+        directory = self.resolve_directory(path)
+        matches: list[dict[str, Any]] = []
+        truncated = False
+        for candidate in self._walk_entries(directory):
+            metadata = self._entry_metadata(candidate)
+            if kind != "any" and metadata["kind"] != kind:
+                continue
+            relative = self._relative(candidate)
+            if not (
+                fnmatchcase(relative.lower(), pattern.lower())
+                or fnmatchcase(Path(relative).name.lower(), pattern.lower())
+            ):
+                continue
+            if len(matches) == max_entries:
+                truncated = True
+                break
+            matches.append(metadata)
+        return {
+            "path": self._relative(directory),
+            "pattern": pattern,
+            "entries": matches,
+            "truncated": truncated,
+        }
+
+    def hash_file(self, path: str, *, algorithm: str = "sha256") -> dict[str, Any]:
+        """Calculate a bounded cryptographic hash for one regular file."""
+
+        if algorithm not in {"sha256", "sha512", "blake2b"}:
+            raise FoundationToolError(
+                "INVALID_ALGORITHM", "algorithm must be sha256, sha512, or blake2b."
+            )
+        file_path = self._resolve(path)
+        if not file_path.is_file():
+            raise FoundationToolError("NOT_A_FILE", "Path is not a regular file.")
+        size = file_path.stat().st_size
+        if size > self.max_read_bytes:
+            raise FoundationToolError(
+                "FILE_TOO_LARGE", f"File is {size} bytes; the hash limit is {self.max_read_bytes}."
+            )
+        digest = new_hash(algorithm)
+        try:
+            with file_path.open("rb") as handle:
+                for chunk in iter(lambda: handle.read(64 * 1024), b""):
+                    digest.update(chunk)
+        except OSError as error:
+            raise FoundationToolError("HASH_FAILED", str(error), retryable=True) from error
+        return {
+            "path": self._relative(file_path),
+            "algorithm": algorithm,
+            "digest": digest.hexdigest(),
+            "bytes": size,
+        }
+
+    def write_text(
+        self,
+        path: str,
+        content: str,
+        *,
+        overwrite: bool = False,
+        create_parents: bool = False,
+    ) -> dict[str, Any]:
+        file_path = self._resolve(path, allow_root=False)
+        encoded = content.encode("utf-8")
+        if len(encoded) > self.max_write_bytes:
+            raise FoundationToolError(
+                "CONTENT_TOO_LARGE",
+                f"Content is {len(encoded)} bytes; the write limit is {self.max_write_bytes}.",
+            )
+        if file_path.exists() and file_path.is_dir():
+            raise FoundationToolError("IS_DIRECTORY", "Cannot write text to a directory.")
+        if file_path.exists() and not overwrite:
+            raise FoundationToolError(
+                "ALREADY_EXISTS", "File exists; set overwrite=true to replace it."
+            )
+
+        parent = file_path.parent
+        try:
+            if create_parents:
+                parent.mkdir(parents=True, exist_ok=True)
+            elif not parent.is_dir():
+                raise FoundationToolError("PARENT_NOT_FOUND", "Parent directory does not exist.")
+
+            temporary_name: str | None = None
+            with tempfile.NamedTemporaryFile(
+                mode="wb", dir=parent, prefix=".agent-write-", delete=False
+            ) as temporary:
+                temporary.write(encoded)
+                temporary.flush()
+                os.fsync(temporary.fileno())
+                temporary_name = temporary.name
+            os.replace(temporary_name, file_path)
+        except FoundationToolError:
+            raise
+        except OSError as error:
+            if "temporary_name" in locals() and temporary_name:
+                Path(temporary_name).unlink(missing_ok=True)
+            raise FoundationToolError("WRITE_FAILED", str(error), retryable=True) from error
+
+        return {
+            "path": self._relative(file_path),
+            "bytes": len(encoded),
+            "overwritten": overwrite,
+        }
+
+    def create_directory(
+        self, path: str, *, parents: bool = True, exist_ok: bool = False
+    ) -> dict[str, Any]:
+        directory = self._resolve(path, allow_root=False)
+        try:
+            directory.mkdir(parents=parents, exist_ok=exist_ok)
+        except FileExistsError as error:
+            raise FoundationToolError("ALREADY_EXISTS", "Path already exists.") from error
+        except FileNotFoundError as error:
+            raise FoundationToolError(
+                "PARENT_NOT_FOUND", "Parent directory does not exist."
+            ) from error
+        except OSError as error:
+            raise FoundationToolError("CREATE_FAILED", str(error)) from error
+        return {"path": self._relative(directory), "created": True}
+
+    def copy_file(
+        self,
+        source: str,
+        destination: str,
+        *,
+        overwrite: bool = False,
+        create_parents: bool = False,
+    ) -> dict[str, Any]:
+        """Copy one regular file without following source symlinks."""
+
+        source_path = self._resolve(source)
+        destination_path = self._resolve(destination, allow_root=False)
+        if not source_path.is_file() or source_path.is_symlink():
+            raise FoundationToolError("NOT_A_FILE", "source must be a regular non-symlink file.")
+        size = source_path.stat().st_size
+        if size > self.max_write_bytes:
+            raise FoundationToolError(
+                "CONTENT_TOO_LARGE",
+                f"Source is {size} bytes; the copy limit is {self.max_write_bytes}.",
+            )
+        if destination_path.exists() and not overwrite:
+            raise FoundationToolError(
+                "ALREADY_EXISTS", "Destination exists; set overwrite=true to replace it."
+            )
+        if destination_path.exists() and destination_path.is_dir():
+            raise FoundationToolError("IS_DIRECTORY", "Destination cannot be a directory.")
+        try:
+            if create_parents:
+                destination_path.parent.mkdir(parents=True, exist_ok=True)
+            elif not destination_path.parent.is_dir():
+                raise FoundationToolError("PARENT_NOT_FOUND", "Parent directory does not exist.")
+            shutil.copy2(source_path, destination_path)
+        except FoundationToolError:
+            raise
+        except OSError as error:
+            raise FoundationToolError("COPY_FAILED", str(error), retryable=True) from error
+        return {
+            "source": self._relative(source_path),
+            "destination": self._relative(destination_path),
+            "bytes": size,
+            "overwritten": overwrite,
+        }
+
+    def move_path(
+        self,
+        source: str,
+        destination: str,
+        *,
+        overwrite: bool = False,
+        create_parents: bool = False,
+    ) -> dict[str, Any]:
+        """Move one workspace file or directory to a new workspace-relative path."""
+
+        source_path = self._resolve(source, allow_root=False)
+        destination_path = self._resolve(destination, allow_root=False)
+        if not source_path.exists() and not source_path.is_symlink():
+            raise FoundationToolError("NOT_FOUND", "Source path does not exist.")
+        if source_path == destination_path:
+            raise FoundationToolError("SAME_PATH", "Source and destination must differ.")
+        if destination_path.exists() or destination_path.is_symlink():
+            if not overwrite:
+                raise FoundationToolError(
+                    "ALREADY_EXISTS", "Destination exists; set overwrite=true to replace it."
+                )
+            if destination_path.is_dir() and not destination_path.is_symlink():
+                raise FoundationToolError(
+                    "DESTINATION_IS_DIRECTORY", "Cannot overwrite a destination directory."
+                )
+        try:
+            if create_parents:
+                destination_path.parent.mkdir(parents=True, exist_ok=True)
+            elif not destination_path.parent.is_dir():
+                raise FoundationToolError("PARENT_NOT_FOUND", "Parent directory does not exist.")
+            if destination_path.exists() or destination_path.is_symlink():
+                destination_path.unlink()
+            shutil.move(str(source_path), str(destination_path))
+        except FoundationToolError:
+            raise
+        except OSError as error:
+            raise FoundationToolError("MOVE_FAILED", str(error), retryable=True) from error
+        return {
+            "source": self._relative(source_path),
+            "destination": self._relative(destination_path),
+            "moved": True,
+        }
+
+    def disk_usage(self) -> dict[str, Any]:
+        """Return storage capacity visible to the configured workspace."""
+
+        try:
+            usage = shutil.disk_usage(self.root)
+        except OSError as error:
+            raise FoundationToolError("DISK_USAGE_FAILED", str(error), retryable=True) from error
+        return {
+            "path": ".",
+            "total_bytes": usage.total,
+            "used_bytes": usage.used,
+            "free_bytes": usage.free,
+        }
+
+    def delete_path(self, path: str, *, recursive: bool = False) -> dict[str, Any]:
+        target = self._resolve(path, allow_root=False)
+        if not target.exists() and not target.is_symlink():
+            raise FoundationToolError("NOT_FOUND", "Path does not exist.")
+
+        kind = "file"
+        try:
+            if target.is_symlink():
+                kind = "symlink"
+                target.unlink()
+            elif target.is_dir():
+                kind = "directory"
+                if recursive:
+                    shutil.rmtree(target)
+                else:
+                    try:
+                        target.rmdir()
+                    except OSError as error:
+                        raise FoundationToolError(
+                            "DIRECTORY_NOT_EMPTY",
+                            "Directory is not empty; set recursive=true to delete it.",
+                        ) from error
+            else:
+                target.unlink()
+        except FoundationToolError:
+            raise
+        except OSError as error:
+            raise FoundationToolError("DELETE_FAILED", str(error), retryable=True) from error
+
+        return {"path": self._relative(target), "deleted": True, "kind": kind}
+
+    def resolve_directory(self, path: str) -> Path:
+        directory = self._resolve(path)
+        if not directory.is_dir():
+            raise FoundationToolError("NOT_A_DIRECTORY", "Path is not a directory.")
+        return directory
+
+    def relative_path(self, path: Path) -> str:
+        """Return a workspace-relative display path for an already resolved path."""
+
+        return self._relative(path)
+
+    def _resolve(self, path: str, *, allow_root: bool = True) -> Path:
+        if not path or "\x00" in path:
+            raise FoundationToolError("INVALID_PATH", "Path must be a non-empty string.")
+        relative = Path(path)
+        if relative.is_absolute():
+            raise FoundationToolError("ABSOLUTE_PATH", "Absolute paths are not allowed.")
+
+        candidate = (self.root / relative).resolve(strict=False)
+        try:
+            candidate.relative_to(self.root)
+        except ValueError as error:
+            raise FoundationToolError(
+                "PATH_OUTSIDE_WORKSPACE", "Path resolves outside the workspace."
+            ) from error
+        if not allow_root and candidate == self.root:
+            raise FoundationToolError(
+                "WORKSPACE_ROOT_PROTECTED", "The workspace root cannot be modified or deleted."
+            )
+        return candidate
+
+    def _walk_entries(self, directory: Path):
+        for current, directories, files in os.walk(directory, followlinks=False):
+            current_path = Path(current)
+            directories.sort(key=str.lower)
+            files.sort(key=str.lower)
+            for name in directories:
+                yield current_path / name
+            for name in files:
+                yield current_path / name
+
+    def _entry_metadata(self, entry: Path) -> dict[str, Any]:
+        if entry.is_symlink():
+            kind = "symlink"
+            size = None
+        elif entry.is_dir():
+            kind = "directory"
+            size = None
+        elif entry.is_file():
+            kind = "file"
+            size = entry.stat().st_size
+        else:
+            kind = "other"
+            size = None
+        return {"path": self._relative(entry), "kind": kind, "bytes": size}
+
+    def _relative(self, path: Path) -> str:
+        relative = path.relative_to(self.root)
+        return "." if not relative.parts else relative.as_posix()