kimi-cli 0.44__py3-none-any.whl → 0.78__py3-none-any.whl

kimi_cli/tools/file/read.py

@@ -1,20 +1,35 @@
+import base64
 from pathlib import Path
 from typing import override
 
-import aiofiles
-from kosong.tooling import CallableTool2, ToolError, ToolOk, ToolReturnType
+from kaos.path import KaosPath
+from kosong.tooling import CallableTool2, ToolError, ToolOk, ToolReturnValue
 from pydantic import BaseModel, Field
 
-from kimi_cli.soul.runtime import BuiltinSystemPromptArgs
-from kimi_cli.tools.utils import load_desc, truncate_line
+from kimi_cli.soul.agent import Runtime
+from kimi_cli.tools.file.utils import MEDIA_SNIFF_BYTES, FileType, detect_file_type
+from kimi_cli.tools.utils import load_desc_jinja, truncate_line
+from kimi_cli.utils.path import is_within_directory
+from kimi_cli.wire.types import ImageURLPart, VideoURLPart
 
 MAX_LINES = 1000
 MAX_LINE_LENGTH = 2000
 MAX_BYTES = 100 << 10  # 100KB
+MAX_MEDIA_BYTES = 80 << 20  # 80MB
+
+
+def _to_data_url(mime_type: str, data: bytes) -> str:
+    encoded = base64.b64encode(data).decode("ascii")
+    return f"data:{mime_type};base64,{encoded}"
 
 
 class Params(BaseModel):
-    path: str = Field(description="The absolute path to the file to read")
+    path: str = Field(
+        description=(
+            "The path to the file to read. Absolute paths are required when reading files "
+            "outside the working directory."
+        )
+    )
     line_offset: int = Field(
         description=(
             "The line number to start reading from. "
@@ -37,78 +52,147 @@ class Params(BaseModel):
 
 class ReadFile(CallableTool2[Params]):
     name: str = "ReadFile"
-    description: str = load_desc(
-        Path(__file__).parent / "read.md",
-        {
-            "MAX_LINES": str(MAX_LINES),
-            "MAX_LINE_LENGTH": str(MAX_LINE_LENGTH),
-            "MAX_BYTES": str(MAX_BYTES),
-        },
-    )
     params: type[Params] = Params
 
-    def __init__(self, builtin_args: BuiltinSystemPromptArgs, **kwargs):
-        super().__init__(**kwargs)
-        self._work_dir = builtin_args.KIMI_WORK_DIR
+    def __init__(self, runtime: Runtime) -> None:
+        capabilities = runtime.llm.capabilities if runtime.llm else set[str]()
+        description = load_desc_jinja(
+            Path(__file__).parent / "read.md",
+            {
+                "MAX_LINES": MAX_LINES,
+                "MAX_LINE_LENGTH": MAX_LINE_LENGTH,
+                "MAX_BYTES": MAX_BYTES,
+                "MAX_MEDIA_BYTES": MAX_MEDIA_BYTES,
+                "capabilities": capabilities,
+            },
+        )
+        super().__init__(description=description)
+        self._work_dir = runtime.builtin_args.KIMI_WORK_DIR
+
+    async def _validate_path(self, path: KaosPath) -> ToolError | None:
+        """Validate that the path is safe to read."""
+        # Check for path traversal attempts
+        resolved_path = path.canonical()
+
+        if not is_within_directory(resolved_path, self._work_dir) and not path.is_absolute():
+            # Outside files can only be read with absolute paths
+            return ToolError(
+                message=(
+                    f"`{path}` is not an absolute path. "
+                    "You must provide an absolute path to read a file "
+                    "outside the working directory."
+                ),
+                brief="Invalid path",
+            )
+        return None
+
+    async def _read_media(self, path: KaosPath, file_type: FileType) -> ToolReturnValue:
+        assert file_type.kind in ("image", "video")
+
+        stat = await path.stat()
+        size = stat.st_size
+        if size == 0:
+            return ToolError(
+                message=f"`{path}` is empty.",
+                brief="Empty file",
+            )
+        if size > MAX_MEDIA_BYTES:
+            return ToolError(
+                message=(
+                    f"`{path}` is {size} bytes, which exceeds the max "
+                    f"{MAX_MEDIA_BYTES} bytes for media files."
+                ),
+                brief="File too large",
+            )
+
+        data = await path.read_bytes()
+        data_url = _to_data_url(file_type.mime_type, data)
+        match file_type.kind:
+            case "image":
+                part = ImageURLPart(image_url=ImageURLPart.ImageURL(url=data_url))
+            case "video":
+                part = VideoURLPart(video_url=VideoURLPart.VideoURL(url=data_url))
+        return ToolOk(
+            output=part,
+            message=(
+                f"Loaded {file_type.kind} file `{path}` ({file_type.mime_type}, {size} bytes)."
+            ),
+        )
 
     @override
-    async def __call__(self, params: Params) -> ToolReturnType:
+    async def __call__(self, params: Params) -> ToolReturnValue:
         # TODO: checks:
         # - check if the path may contain secrets
-        # - check if the file format is readable
+
+        if not params.path:
+            return ToolError(
+                message="File path cannot be empty.",
+                brief="Empty file path",
+            )
+
         try:
-            p = Path(params.path)
+            p = KaosPath(params.path).expanduser()
 
-            if not p.is_absolute():
-                return ToolError(
-                    message=(
-                        f"`{params.path}` is not an absolute path. "
-                        "You must provide an absolute path to read a file."
-                    ),
-                    brief="Invalid path",
-                )
+            if err := await self._validate_path(p):
+                return err
 
-            if not p.exists():
+            if not await p.exists():
                 return ToolError(
                     message=f"`{params.path}` does not exist.",
                     brief="File not found",
                 )
-            if not p.is_file():
+            if not await p.is_file():
                 return ToolError(
                     message=f"`{params.path}` is not a file.",
                     brief="Invalid path",
                 )
 
+            header = await p.read_bytes(MEDIA_SNIFF_BYTES)
+            file_type = detect_file_type(str(p), header=header)
+            if file_type.kind in ("image", "video"):
+                return await self._read_media(p, file_type)
+
+            if file_type.kind == "unknown":
+                return ToolError(
+                    message=(
+                        f"`{params.path}` seems not readable. "
+                        "You may need to read it with proper shell commands, Python tools "
+                        "or MCP tools if available. "
+                        "If you read/operate it with Python, you MUST ensure that any "
+                        "third-party packages are installed in a virtual environment (venv)."
+                    ),
+                    brief="File not readable",
+                )
+
             assert params.line_offset >= 1
             assert params.n_lines >= 1
 
             lines: list[str] = []
             n_bytes = 0
-            truncated_line_numbers = []
+            truncated_line_numbers: list[int] = []
             max_lines_reached = False
             max_bytes_reached = False
-            async with aiofiles.open(p, encoding="utf-8", errors="replace") as f:
-                current_line_no = 0
-                async for line in f:
-                    current_line_no += 1
-                    if current_line_no < params.line_offset:
-                        continue
-                    truncated = truncate_line(line, MAX_LINE_LENGTH)
-                    if truncated != line:
-                        truncated_line_numbers.append(current_line_no)
-                    lines.append(truncated)
-                    n_bytes += len(truncated.encode("utf-8"))
-                    if len(lines) >= params.n_lines:
-                        break
-                    if len(lines) >= MAX_LINES:
-                        max_lines_reached = True
-                        break
-                    if n_bytes >= MAX_BYTES:
-                        max_bytes_reached = True
-                        break
+            current_line_no = 0
+            async for line in p.read_lines(errors="replace"):
+                current_line_no += 1
+                if current_line_no < params.line_offset:
+                    continue
+                truncated = truncate_line(line, MAX_LINE_LENGTH)
+                if truncated != line:
+                    truncated_line_numbers.append(current_line_no)
+                lines.append(truncated)
+                n_bytes += len(truncated.encode("utf-8"))
+                if len(lines) >= params.n_lines:
+                    break
+                if len(lines) >= MAX_LINES:
+                    max_lines_reached = True
+                    break
+                if n_bytes >= MAX_BYTES:
+                    max_bytes_reached = True
+                    break
 
             # Format output with line numbers like `cat -n`
-            lines_with_no = []
+            lines_with_no: list[str] = []
             for line_num, line in zip(
                 range(params.line_offset, params.line_offset + len(lines)), lines, strict=True
             ):

kimi_cli/tools/file/replace.md

@@ -4,4 +4,4 @@ Replace specific strings within a specified file.
 - Only use this tool on text files.
 - Multi-line strings are supported.
 - Can specify a single edit or a list of edits in one call.
-- You should prefer this tool over WriteFile tool and Bash `sed` command.
+- You should prefer this tool over WriteFile tool and Shell `sed` command.

kimi_cli/tools/file/replace.py

@@ -1,14 +1,17 @@
 from pathlib import Path
 from typing import override
 
-import aiofiles
-from kosong.tooling import CallableTool2, ToolError, ToolOk, ToolReturnType
+from kaos.path import KaosPath
+from kosong.tooling import CallableTool2, ToolError, ToolReturnValue
 from pydantic import BaseModel, Field
 
+from kimi_cli.soul.agent import BuiltinSystemPromptArgs
 from kimi_cli.soul.approval import Approval
-from kimi_cli.soul.runtime import BuiltinSystemPromptArgs
+from kimi_cli.tools.display import DisplayBlock
 from kimi_cli.tools.file import FileActions
-from kimi_cli.tools.utils import ToolRejectedError
+from kimi_cli.tools.file.utils import build_diff_blocks
+from kimi_cli.tools.utils import ToolRejectedError, load_desc
+from kimi_cli.utils.path import is_within_directory
 
 
 class Edit(BaseModel):
@@ -29,22 +32,21 @@ class Params(BaseModel):
 
 class StrReplaceFile(CallableTool2[Params]):
     name: str = "StrReplaceFile"
-    description: str = (Path(__file__).parent / "replace.md").read_text(encoding="utf-8")
+    description: str = load_desc(Path(__file__).parent / "replace.md")
     params: type[Params] = Params
 
-    def __init__(self, builtin_args: BuiltinSystemPromptArgs, approval: Approval, **kwargs):
-        super().__init__(**kwargs)
+    def __init__(self, builtin_args: BuiltinSystemPromptArgs, approval: Approval):
+        super().__init__()
         self._work_dir = builtin_args.KIMI_WORK_DIR
         self._approval = approval
 
-    def _validate_path(self, path: Path) -> ToolError | None:
+    async def _validate_path(self, path: KaosPath) -> ToolError | None:
         """Validate that the path is safe to edit."""
         # Check for path traversal attempts
-        resolved_path = path.resolve()
-        resolved_work_dir = self._work_dir.resolve()
+        resolved_path = path.canonical()
 
         # Ensure the path is within work directory
-        if not str(resolved_path).startswith(str(resolved_work_dir)):
+        if not is_within_directory(resolved_path, self._work_dir):
             return ToolError(
                 message=(
                     f"`{path}` is outside the working directory. "
@@ -62,9 +64,9 @@ class StrReplaceFile(CallableTool2[Params]):
             return content.replace(edit.old, edit.new, 1)
 
     @override
-    async def __call__(self, params: Params) -> ToolReturnType:
+    async def __call__(self, params: Params) -> ToolReturnValue:
         try:
-            p = Path(params.path)
+            p = KaosPath(params.path)
 
             if not p.is_absolute():
                 return ToolError(
@@ -76,32 +78,23 @@ class StrReplaceFile(CallableTool2[Params]):
                 )
 
             # Validate path safety
-            path_error = self._validate_path(p)
+            path_error = await self._validate_path(p)
             if path_error:
                 return path_error
 
-            if not p.exists():
+            if not await p.exists():
                 return ToolError(
                     message=f"`{params.path}` does not exist.",
                     brief="File not found",
                 )
-            if not p.is_file():
+            if not await p.is_file():
                 return ToolError(
                     message=f"`{params.path}` is not a file.",
                     brief="Invalid path",
                 )
 
-            # Request approval
-            if not await self._approval.request(
-                self.name,
-                FileActions.EDIT,
-                f"Edit file `{params.path}`",
-            ):
-                return ToolRejectedError()
-
             # Read the file content
-            async with aiofiles.open(p, encoding="utf-8", errors="replace") as f:
-                content = await f.read()
+            content = await p.read_text(errors="replace")
 
             original_content = content
             edits = [params.edit] if isinstance(params.edit, Edit) else params.edit
@@ -117,9 +110,21 @@ class StrReplaceFile(CallableTool2[Params]):
                     brief="No replacements made",
                 )
 
+            diff_blocks: list[DisplayBlock] = list(
+                build_diff_blocks(params.path, original_content, content)
+            )
+
+            # Request approval
+            if not await self._approval.request(
+                self.name,
+                FileActions.EDIT,
+                f"Edit file `{params.path}`",
+                display=diff_blocks,
+            ):
+                return ToolRejectedError()
+
             # Write the modified content back to the file
-            async with aiofiles.open(p, mode="w", encoding="utf-8") as f:
-                await f.write(content)
+            await p.write_text(content, errors="replace")
 
             # Count changes for success message
             total_replacements = 0
@@ -129,12 +134,14 @@ class StrReplaceFile(CallableTool2[Params]):
                 else:
                     total_replacements += 1 if edit.old in original_content else 0
 
-            return ToolOk(
+            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:

kimi_cli/tools/file/utils.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+import mimetypes
+from dataclasses import dataclass
+from difflib import SequenceMatcher
+from pathlib import PurePath
+from typing import Literal
+
+from kimi_cli.tools.display import DiffDisplayBlock
+
+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",
+    ".svg": "image/svg+xml",
+    ".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",
+}
+
+_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",
+    "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("ascii", errors="ignore").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 _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 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")
+
+
+N_CONTEXT_LINES = 3
+
+
+def build_diff_blocks(
+    path: str,
+    old_text: str,
+    new_text: str,
+) -> list[DiffDisplayBlock]:
+    """Build diff display blocks grouped with small context windows."""
+    old_lines = old_text.splitlines()
+    new_lines = new_text.splitlines()
+    matcher = SequenceMatcher(None, old_lines, new_lines, autojunk=False)
+    blocks: list[DiffDisplayBlock] = []
+    for group in matcher.get_grouped_opcodes(n=N_CONTEXT_LINES):
+        if not group:
+            continue
+        i1 = group[0][1]
+        i2 = group[-1][2]
+        j1 = group[0][3]
+        j2 = group[-1][4]
+        blocks.append(
+            DiffDisplayBlock(
+                path=path,
+                old_text="\n".join(old_lines[i1:i2]),
+                new_text="\n".join(new_lines[j1:j2]),
+            )
+        )
+    return blocks