pythinker-code 0.8.0__py3-none-any.whl

pythinker_code/tools/file/replace.py

@@ -0,0 +1,204 @@
+from collections.abc import Callable
+from pathlib import Path
+from typing import override
+
+from pydantic import BaseModel, Field
+from pythinker_core.tooling import CallableTool2, ToolError, ToolReturnValue
+from pythinker_host.path import HostPath
+
+from pythinker_code.soul.agent import Runtime
+from pythinker_code.soul.approval import Approval
+from pythinker_code.soul.permission import check_file_mutation_allowed
+from pythinker_code.tools.display import DisplayBlock
+from pythinker_code.tools.file import FileActions
+from pythinker_code.tools.file.plan_mode import inspect_plan_edit_target
+from pythinker_code.tools.utils import load_desc
+from pythinker_code.utils.diff import build_diff_blocks
+from pythinker_code.utils.logging import logger
+from pythinker_code.utils.path import is_within_workspace
+
+_BASE_DESCRIPTION = load_desc(Path(__file__).parent / "replace.md")
+
+
+class Edit(BaseModel):
+    old: str = Field(description="The old string to replace. Can be multi-line.")
+    new: str = Field(description="The new string to replace with. Can be multi-line.")
+    replace_all: bool = Field(description="Whether to replace all occurrences.", default=False)
+
+
+class Params(BaseModel):
+    path: str = Field(
+        description=(
+            "The path to the file to edit. Absolute paths are required when editing files "
+            "outside the working directory."
+        )
+    )
+    edit: Edit | list[Edit] = Field(
+        description=(
+            "The edit(s) to apply to the file. "
+            "You can provide a single edit or a list of edits here."
+        )
+    )
+
+
+class StrReplaceFile(CallableTool2[Params]):
+    name: str = "StrReplaceFile"
+    description: str = _BASE_DESCRIPTION
+    params: type[Params] = Params
+
+    def __init__(self, runtime: Runtime, approval: Approval):
+        super().__init__()
+        self._runtime = runtime
+        self._work_dir = runtime.builtin_args.PYTHINKER_WORK_DIR
+        self._additional_dirs = runtime.additional_dirs
+        self._approval = approval
+        self._plan_mode_checker: Callable[[], bool] | None = None
+        self._plan_file_path_getter: Callable[[], Path | None] | None = None
+
+    def bind_plan_mode(
+        self, checker: Callable[[], bool], path_getter: Callable[[], Path | None]
+    ) -> None:
+        """Bind plan mode state checker and plan file path getter."""
+        self._plan_mode_checker = checker
+        self._plan_file_path_getter = path_getter
+
+    async def _validate_path(self, path: HostPath) -> ToolError | None:
+        """Validate that the path is safe to edit."""
+        resolved_path = path.canonical()
+
+        if (
+            not is_within_workspace(resolved_path, self._work_dir, self._additional_dirs)
+            and not path.is_absolute()
+        ):
+            return ToolError(
+                message=(
+                    f"`{path}` is not an absolute path. "
+                    "You must provide an absolute path to edit a file "
+                    "outside the working directory."
+                ),
+                brief="Invalid path",
+            )
+        return None
+
+    def _apply_edit(self, content: str, edit: Edit) -> str:
+        """Apply a single edit to the content."""
+        if edit.replace_all:
+            return content.replace(edit.old, edit.new)
+        else:
+            return content.replace(edit.old, edit.new, 1)
+
+    @override
+    async def __call__(self, params: Params) -> ToolReturnValue:
+        if not params.path:
+            return ToolError(
+                message="File path cannot be empty.",
+                brief="Empty file path",
+            )
+
+        try:
+            p = HostPath(params.path).expanduser()
+            if err := await self._validate_path(p):
+                return err
+            p = p.canonical()
+
+            plan_target = inspect_plan_edit_target(
+                p,
+                plan_mode_checker=self._plan_mode_checker,
+                plan_file_path_getter=self._plan_file_path_getter,
+            )
+            if isinstance(plan_target, ToolError):
+                return plan_target
+
+            is_plan_file_edit = plan_target.is_plan_target
+            if err := check_file_mutation_allowed(
+                self._runtime, is_plan_artifact=is_plan_file_edit
+            ):
+                return err
+
+            if not await p.exists():
+                if is_plan_file_edit:
+                    return ToolError(
+                        message=(
+                            "The current plan file does not exist yet. "
+                            "Use WriteFile to create it before calling StrReplaceFile."
+                        ),
+                        brief="Plan file not created",
+                    )
+                return ToolError(
+                    message=f"`{params.path}` does not exist.",
+                    brief="File not found",
+                )
+            if not await p.is_file():
+                return ToolError(
+                    message=f"`{params.path}` is not a file.",
+                    brief="Invalid path",
+                )
+
+            # Read the file content
+            content = await p.read_text(encoding="utf-8", errors="replace")
+
+            original_content = content
+            edits = [params.edit] if isinstance(params.edit, Edit) else params.edit
+
+            # Apply all edits
+            for edit in edits:
+                content = self._apply_edit(content, edit)
+
+            # Check if any changes were made
+            if content == original_content:
+                return ToolError(
+                    message="No replacements were made. The old string was not found in the file.",
+                    brief="No replacements made",
+                )
+
+            diff_blocks: list[DisplayBlock] = await build_diff_blocks(
+                str(p), original_content, content
+            )
+
+            action = (
+                FileActions.EDIT
+                if is_within_workspace(p, self._work_dir, self._additional_dirs)
+                else FileActions.EDIT_OUTSIDE
+            )
+
+            # Plan file edits are auto-approved; all other edits need approval.
+            if not is_plan_file_edit:
+                result = await self._approval.request(
+                    self.name,
+                    action,
+                    f"Edit file `{p}`",
+                    display=diff_blocks,
+                )
+                if not result:
+                    return result.rejection_error()
+
+            # Write the modified content back to the file
+            await p.write_text(content, encoding="utf-8", errors="replace")
+
+            # Count changes for success message
+            total_replacements = 0
+            for edit in edits:
+                if edit.replace_all:
+                    total_replacements += original_content.count(edit.old)
+                else:
+                    total_replacements += 1 if edit.old in original_content else 0
+
+            return ToolReturnValue(
+                is_error=False,
+                output="",
+                message=(
+                    f"File successfully edited. "
+                    f"Applied {len(edits)} edit(s) with {total_replacements} total replacement(s)."
+                ),
+                display=diff_blocks,
+            )
+
+        except Exception as e:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(e, site="tool.replace", tool="StrReplaceFile")
+            logger.warning("StrReplaceFile failed: {path}: {error}", path=params.path, error=e)
+            return ToolError(
+                message=f"Failed to edit. Error: {e}",
+                brief="Failed to edit file",
+            )

pythinker_code/tools/file/utils.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+import mimetypes
+from dataclasses import dataclass
+from pathlib import PurePath
+from typing import Literal
+
+MEDIA_SNIFF_BYTES = 512
+
+_EXTRA_MIME_TYPES = {
+    ".avif": "image/avif",
+    ".heic": "image/heic",
+    ".heif": "image/heif",
+    ".mkv": "video/x-matroska",
+    ".m4v": "video/x-m4v",
+    ".3gp": "video/3gpp",
+    ".3g2": "video/3gpp2",
+    # TypeScript files: override mimetypes default (video/mp2t for MPEG Transport Stream)
+    ".ts": "text/typescript",
+    ".tsx": "text/typescript",
+    ".mts": "text/typescript",
+    ".cts": "text/typescript",
+}
+
+for suffix, mime_type in _EXTRA_MIME_TYPES.items():
+    mimetypes.add_type(mime_type, suffix)
+
+_IMAGE_MIME_BY_SUFFIX = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".bmp": "image/bmp",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+    ".webp": "image/webp",
+    ".ico": "image/x-icon",
+    ".heic": "image/heic",
+    ".heif": "image/heif",
+    ".avif": "image/avif",
+    ".svgz": "image/svg+xml",
+}
+_VIDEO_MIME_BY_SUFFIX = {
+    ".mp4": "video/mp4",
+    ".mkv": "video/x-matroska",
+    ".avi": "video/x-msvideo",
+    ".mov": "video/quicktime",
+    ".wmv": "video/x-ms-wmv",
+    ".webm": "video/webm",
+    ".m4v": "video/x-m4v",
+    ".flv": "video/x-flv",
+    ".3gp": "video/3gpp",
+    ".3g2": "video/3gpp2",
+}
+_TEXT_MIME_BY_SUFFIX = {
+    ".svg": "image/svg+xml",
+}
+
+_ASF_HEADER = b"\x30\x26\xb2\x75\x8e\x66\xcf\x11\xa6\xd9\x00\xaa\x00\x62\xce\x6c"
+_FTYP_IMAGE_BRANDS = {
+    "avif": "image/avif",
+    "avis": "image/avif",
+    "heic": "image/heic",
+    "heif": "image/heif",
+    "heix": "image/heif",
+    "hevc": "image/heic",
+    "mif1": "image/heif",
+    "msf1": "image/heif",
+}
+_FTYP_VIDEO_BRANDS = {
+    "isom": "video/mp4",
+    "iso2": "video/mp4",
+    "iso5": "video/mp4",
+    "mp41": "video/mp4",
+    "mp42": "video/mp4",
+    "avc1": "video/mp4",
+    "mp4v": "video/mp4",
+    "m4v": "video/x-m4v",
+    "qt": "video/quicktime",
+    "3gp4": "video/3gpp",
+    "3gp5": "video/3gpp",
+    "3gp6": "video/3gpp",
+    "3gp7": "video/3gpp",
+    "3g2": "video/3gpp2",
+}
+
+_NON_TEXT_SUFFIXES = {
+    ".icns",
+    ".psd",
+    ".ai",
+    ".eps",
+    # Documents / office formats
+    ".pdf",
+    ".doc",
+    ".docx",
+    ".dot",
+    ".dotx",
+    ".rtf",
+    ".odt",
+    ".xls",
+    ".xlsx",
+    ".xlsm",
+    ".xlt",
+    ".xltx",
+    ".xltm",
+    ".ods",
+    ".ppt",
+    ".pptx",
+    ".pptm",
+    ".pps",
+    ".ppsx",
+    ".odp",
+    ".pages",
+    ".numbers",
+    ".key",
+    # Archives / compressed
+    ".zip",
+    ".rar",
+    ".7z",
+    ".tar",
+    ".gz",
+    ".tgz",
+    ".bz2",
+    ".xz",
+    ".zst",
+    ".lz",
+    ".lz4",
+    ".br",
+    ".cab",
+    ".ar",
+    ".deb",
+    ".rpm",
+    # Audio
+    ".mp3",
+    ".wav",
+    ".flac",
+    ".ogg",
+    ".oga",
+    ".opus",
+    ".aac",
+    ".m4a",
+    ".wma",
+    # Fonts
+    ".ttf",
+    ".otf",
+    ".woff",
+    ".woff2",
+    # Binaries / bundles
+    ".exe",
+    ".dll",
+    ".so",
+    ".dylib",
+    ".bin",
+    ".apk",
+    ".ipa",
+    ".jar",
+    ".class",
+    ".pyc",
+    ".pyo",
+    ".wasm",
+    # Disk images / databases
+    ".dmg",
+    ".iso",
+    ".img",
+    ".sqlite",
+    ".sqlite3",
+    ".db",
+    ".db3",
+}
+
+
+@dataclass(frozen=True)
+class FileType:
+    kind: Literal["text", "image", "video", "unknown"]
+    mime_type: str
+
+
+def _sniff_ftyp_brand(header: bytes) -> str | None:
+    if len(header) < 12 or header[4:8] != b"ftyp":
+        return None
+    brand = header[8:12].decode("utf-8", errors="replace").lower()
+    return brand.strip()
+
+
+def sniff_media_from_magic(data: bytes) -> FileType | None:
+    header = data[:MEDIA_SNIFF_BYTES]
+    if header.startswith(b"\x89PNG\r\n\x1a\n"):
+        return FileType(kind="image", mime_type="image/png")
+    if header.startswith(b"\xff\xd8\xff"):
+        return FileType(kind="image", mime_type="image/jpeg")
+    if header.startswith((b"GIF87a", b"GIF89a")):
+        return FileType(kind="image", mime_type="image/gif")
+    if header.startswith(b"BM"):
+        return FileType(kind="image", mime_type="image/bmp")
+    if header.startswith((b"II*\x00", b"MM\x00*")):
+        return FileType(kind="image", mime_type="image/tiff")
+    if header.startswith(b"\x00\x00\x01\x00"):
+        return FileType(kind="image", mime_type="image/x-icon")
+    if header.startswith(b"RIFF") and len(header) >= 12:
+        chunk = header[8:12]
+        if chunk == b"WEBP":
+            return FileType(kind="image", mime_type="image/webp")
+        if chunk == b"AVI ":
+            return FileType(kind="video", mime_type="video/x-msvideo")
+    if header.startswith(b"FLV"):
+        return FileType(kind="video", mime_type="video/x-flv")
+    if header.startswith(_ASF_HEADER):
+        return FileType(kind="video", mime_type="video/x-ms-wmv")
+    if header.startswith(b"\x1a\x45\xdf\xa3"):
+        lowered = header.lower()
+        if b"webm" in lowered:
+            return FileType(kind="video", mime_type="video/webm")
+        if b"matroska" in lowered:
+            return FileType(kind="video", mime_type="video/x-matroska")
+    if brand := _sniff_ftyp_brand(header):
+        if brand in _FTYP_IMAGE_BRANDS:
+            return FileType(kind="image", mime_type=_FTYP_IMAGE_BRANDS[brand])
+        if brand in _FTYP_VIDEO_BRANDS:
+            return FileType(kind="video", mime_type=_FTYP_VIDEO_BRANDS[brand])
+    return None
+
+
+def detect_file_type(path: str | PurePath, header: bytes | None = None) -> FileType:
+    suffix = PurePath(str(path)).suffix.lower()
+    media_hint: FileType | None = None
+    if suffix in _TEXT_MIME_BY_SUFFIX:
+        media_hint = FileType(kind="text", mime_type=_TEXT_MIME_BY_SUFFIX[suffix])
+    elif suffix in _IMAGE_MIME_BY_SUFFIX:
+        media_hint = FileType(kind="image", mime_type=_IMAGE_MIME_BY_SUFFIX[suffix])
+    elif suffix in _VIDEO_MIME_BY_SUFFIX:
+        media_hint = FileType(kind="video", mime_type=_VIDEO_MIME_BY_SUFFIX[suffix])
+    else:
+        mime_type, _ = mimetypes.guess_type(str(path))
+        if mime_type:
+            if mime_type.startswith("image/"):
+                media_hint = FileType(kind="image", mime_type=mime_type)
+            elif mime_type.startswith("video/"):
+                media_hint = FileType(kind="video", mime_type=mime_type)
+
+    if media_hint and media_hint.kind in ("image", "video"):
+        return media_hint
+
+    if header is not None:
+        sniffed = sniff_media_from_magic(header)
+        if sniffed:
+            if media_hint and sniffed.kind != media_hint.kind:
+                return FileType(kind="unknown", mime_type="")
+            return sniffed
+        # NUL bytes are a strong signal of binary content.
+        if b"\x00" in header:
+            return FileType(kind="unknown", mime_type="")
+
+    if media_hint:
+        return media_hint
+    if suffix in _NON_TEXT_SUFFIXES:
+        return FileType(kind="unknown", mime_type="")
+    return FileType(kind="text", mime_type="text/plain")

pythinker_code/tools/file/write.md

@@ -0,0 +1,5 @@
+Write content to a file.
+
+**Tips:**
+- When `mode` is not specified, it defaults to `overwrite`. Always write with caution.
+- When the content to write is too long (e.g. > 100 lines), use this tool multiple times instead of a single call. Use `overwrite` mode at the first time, then use `append` mode after the first write.

pythinker_code/tools/file/write.py

@@ -0,0 +1,186 @@
+from collections.abc import Callable
+from pathlib import Path
+from typing import Literal, override
+
+from pydantic import BaseModel, Field
+from pythinker_core.tooling import CallableTool2, ToolError, ToolReturnValue
+from pythinker_host.path import HostPath
+
+from pythinker_code.soul.agent import Runtime
+from pythinker_code.soul.approval import Approval
+from pythinker_code.soul.permission import check_file_mutation_allowed
+from pythinker_code.tools.display import DisplayBlock
+from pythinker_code.tools.file import FileActions
+from pythinker_code.tools.file.plan_mode import inspect_plan_edit_target
+from pythinker_code.tools.utils import load_desc
+from pythinker_code.utils.diff import build_diff_blocks
+from pythinker_code.utils.logging import logger
+from pythinker_code.utils.path import is_within_workspace
+
+_BASE_DESCRIPTION = load_desc(Path(__file__).parent / "write.md")
+
+
+class Params(BaseModel):
+    path: str = Field(
+        description=(
+            "The path to the file to write. Absolute paths are required when writing files "
+            "outside the working directory."
+        )
+    )
+    content: str = Field(description="The content to write to the file")
+    mode: Literal["overwrite", "append"] = Field(
+        description=(
+            "The mode to use to write to the file. "
+            "Two modes are supported: `overwrite` for overwriting the whole file and "
+            "`append` for appending to the end of an existing file."
+        ),
+        default="overwrite",
+    )
+
+
+class WriteFile(CallableTool2[Params]):
+    name: str = "WriteFile"
+    description: str = _BASE_DESCRIPTION
+    params: type[Params] = Params
+
+    def __init__(self, runtime: Runtime, approval: Approval):
+        super().__init__()
+        self._runtime = runtime
+        self._work_dir = runtime.builtin_args.PYTHINKER_WORK_DIR
+        self._additional_dirs = runtime.additional_dirs
+        self._approval = approval
+        self._plan_mode_checker: Callable[[], bool] | None = None
+        self._plan_file_path_getter: Callable[[], Path | None] | None = None
+
+    def bind_plan_mode(
+        self, checker: Callable[[], bool], path_getter: Callable[[], Path | None]
+    ) -> None:
+        """Bind plan mode state checker and plan file path getter."""
+        self._plan_mode_checker = checker
+        self._plan_file_path_getter = path_getter
+
+    async def _validate_path(self, path: HostPath) -> ToolError | None:
+        """Validate that the path is safe to write."""
+        resolved_path = path.canonical()
+
+        if (
+            not is_within_workspace(resolved_path, self._work_dir, self._additional_dirs)
+            and not path.is_absolute()
+        ):
+            return ToolError(
+                message=(
+                    f"`{path}` is not an absolute path. "
+                    "You must provide an absolute path to write a file "
+                    "outside the working directory."
+                ),
+                brief="Invalid path",
+            )
+        return None
+
+    @override
+    async def __call__(self, params: Params) -> ToolReturnValue:
+        # TODO: checks:
+        # - check if the path may contain secrets
+        if not params.path:
+            return ToolError(
+                message="File path cannot be empty.",
+                brief="Empty file path",
+            )
+
+        try:
+            p = HostPath(params.path).expanduser()
+
+            if err := await self._validate_path(p):
+                return err
+            p = p.canonical()
+
+            plan_target = inspect_plan_edit_target(
+                p,
+                plan_mode_checker=self._plan_mode_checker,
+                plan_file_path_getter=self._plan_file_path_getter,
+            )
+            if isinstance(plan_target, ToolError):
+                return plan_target
+
+            is_plan_file_write = plan_target.is_plan_target
+            if err := check_file_mutation_allowed(
+                self._runtime, is_plan_artifact=is_plan_file_write
+            ):
+                return err
+            if is_plan_file_write and plan_target.plan_path is not None:
+                plan_target.plan_path.parent.mkdir(parents=True, exist_ok=True)
+
+            if not await p.parent.exists():
+                return ToolError(
+                    message=f"`{params.path}` parent directory does not exist.",
+                    brief="Parent directory not found",
+                )
+
+            # Validate mode parameter
+            if params.mode not in ["overwrite", "append"]:
+                return ToolError(
+                    message=(
+                        f"Invalid write mode: `{params.mode}`. "
+                        "Mode must be either `overwrite` or `append`."
+                    ),
+                    brief="Invalid write mode",
+                )
+
+            file_existed = await p.exists()
+            old_text = None
+            if file_existed:
+                old_text = await p.read_text(encoding="utf-8", errors="replace")
+
+            new_text = (
+                params.content if params.mode == "overwrite" else (old_text or "") + params.content
+            )
+            diff_blocks: list[DisplayBlock] = await build_diff_blocks(
+                str(p),
+                old_text or "",
+                new_text,
+            )
+
+            # Plan file writes are auto-approved; other writes need approval
+            if not is_plan_file_write:
+                action = (
+                    FileActions.EDIT
+                    if is_within_workspace(p, self._work_dir, self._additional_dirs)
+                    else FileActions.EDIT_OUTSIDE
+                )
+
+                # Request approval
+                result = await self._approval.request(
+                    self.name,
+                    action,
+                    f"Write file `{p}`",
+                    display=diff_blocks,
+                )
+                if not result:
+                    return result.rejection_error()
+
+            # Write content to file
+            match params.mode:
+                case "overwrite":
+                    await p.write_text(params.content, encoding="utf-8")
+                case "append":
+                    await p.append_text(params.content)
+
+            # Get file info for success message
+            file_size = (await p.stat()).st_size
+            action = "overwritten" if params.mode == "overwrite" else "appended to"
+            return ToolReturnValue(
+                is_error=False,
+                output="",
+                message=(f"File successfully {action}. Current size: {file_size} bytes."),
+                display=diff_blocks,
+            )
+
+        except Exception as e:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(e, site="tool.write", tool="WriteFile")
+            logger.warning("WriteFile failed: {path}: {error}", path=params.path, error=e)
+            return ToolError(
+                message=f"Failed to write to {params.path}. Error: {e}",
+                brief="Failed to write file",
+            )