axio-tools-local 0.2.2__tar.gz → 0.2.4__tar.gz

{axio_tools_local-0.2.2 → axio_tools_local-0.2.4}/PKG-INFO

@@ -1,9 +1,12 @@
 Metadata-Version: 2.4
 Name: axio-tools-local
-Version: 0.2.2
+Version: 0.2.4
 Summary: Core filesystem and execution tools for Axio
+Project-URL: Homepage, https://github.com/axio-agent/axio-tools-local
+Project-URL: Repository, https://github.com/axio-agent/axio-tools-local
 License: MIT
 License-File: LICENSE
+Keywords: agent,ai,filesystem,llm,shell,tools
 Requires-Python: >=3.12
 Requires-Dist: axio
 Description-Content-Type: text/markdown

{axio_tools_local-0.2.2 → axio_tools_local-0.2.4}/pyproject.toml

@@ -1,10 +1,11 @@
 [project]
 name = "axio-tools-local"
-version = "0.2.2"
+version = "0.2.4"
 description = "Core filesystem and execution tools for Axio"
 readme = "README.md"
 requires-python = ">=3.12"
 license = {text = "MIT"}
+keywords = ["llm", "agent", "ai", "tools", "filesystem", "shell"]
 dependencies = ["axio"]
 
 [project.entry-points."axio.tools"]
@@ -15,6 +16,10 @@ patch_file = "axio_tools_local.patch_file:PatchFile"
 read_file = "axio_tools_local.read_file:ReadFile"
 list_files = "axio_tools_local.list_files:ListFiles"
 
+
+[project.urls]
+Homepage = "https://github.com/axio-agent/axio-tools-local"
+Repository = "https://github.com/axio-agent/axio-tools-local"
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

{axio_tools_local-0.2.2 → axio_tools_local-0.2.4}/src/axio_tools_local/list_files.py

@@ -24,7 +24,11 @@ class ListFiles(ToolHandler):
             raise FileNotFoundError(f"{self.directory} is not a valid directory")
         lines: list[str] = []
         for fpath in sorted(path.glob("*"), key=lambda p: (not p.is_dir(), p.name)):
-            st = fpath.stat()
+            try:
+                st = fpath.stat()
+            except OSError:
+                lines.append(f"{'?':10} {'?':>8} {'?':12} {fpath.name} [broken symlink]")
+                continue
             mode = stat_module.filemode(st.st_mode)
             size = st.st_size
             mtime = datetime.fromtimestamp(st.st_mtime).strftime("%b %d %H:%M")

{axio_tools_local-0.2.2 → axio_tools_local-0.2.4}/src/axio_tools_local/patch_file.py

@@ -6,11 +6,12 @@ from axio.tool import ToolHandler
 
 
 class PatchFile(ToolHandler):
-    """Replace a range of lines in an existing file. Lines are 0-indexed:
-    from_line is inclusive, to_line is exclusive. The content string replaces
-    lines[from_line:to_line]. Always read the file first to get correct
-    line numbers. Use this for surgical edits instead of rewriting the
-    whole file with write_file."""
+    """Replace a range of lines in an existing file. Lines are 1-indexed:
+    from_line and to_line are both inclusive (from_line=2, to_line=4 replaces
+    lines 2, 3, 4). To insert without deleting, set to_line = from_line - 1.
+    Always read the file first with indexed=True to get correct line numbers.
+    Use this for surgical edits instead of rewriting the whole file with
+    write_file."""
 
     file_path: str
     mode: int = 0o644
@@ -33,11 +34,13 @@ class PatchFile(ToolHandler):
         with path.open("r") as f:
             lines = f.readlines()
 
-        # content lines
-        content = self.content.splitlines()
+        # content lines — preserve existing newlines
+        content_lines = self.content.splitlines(keepends=True)
+        if content_lines and not content_lines[-1].endswith("\n"):
+            content_lines[-1] += "\n"
 
-        # patch lines
-        new_lines = lines[: self.from_line] + content + lines[self.to_line :]
+        # patch lines (from_line/to_line are 1-indexed, both inclusive)
+        new_lines = lines[: self.from_line - 1] + content_lines + lines[self.to_line :]
         with path.open("w") as f:
             f.writelines(new_lines)
             return f"{f.tell()} bytes written to {self.file_path}"

axio_tools_local-0.2.4/src/axio_tools_local/read_file.py

@@ -0,0 +1,48 @@
+import asyncio
+import os
+
+from axio.tool import ToolHandler
+
+
+class ReadFile(ToolHandler):
+    """Read file contents. Returns text for text files, hex for binaries.
+    Lines are 1-indexed: start_line=1 is the first line, end_line=3 includes
+    line 3. Pass indexed=True to prefix each line with its 1-based line number
+    (tab-separated) — useful before calling patch_file. Large files are
+    truncated to max_chars. Always read the file before editing it with
+    write_file or patch_file."""
+
+    filename: str
+    max_chars: int = 32768
+    binary_as_hex: bool = True
+    start_line: int | None = None
+    end_line: int | None = None
+    indexed: bool = False
+
+    def __repr__(self) -> str:
+        return f"ReadFile(filename={self.filename!r})"
+
+    def _blocking(self) -> str:
+        path = os.path.join(os.getcwd(), self.filename)
+        with open(path, "rb") as f:
+            raw = f.read()
+        try:
+            text = raw.decode()
+        except UnicodeDecodeError:
+            if self.binary_as_hex:
+                return "Encoded binary data HEX: " + raw[: self.max_chars].hex()
+            raise
+        all_lines = text.splitlines(keepends=True)
+        start = 0 if self.start_line is None else self.start_line - 1
+        end = len(all_lines) if self.end_line is None else self.end_line
+        lines = all_lines[start:end]
+        if self.indexed:
+            result = "".join(f"{start + 1 + i}\t{line}" for i, line in enumerate(lines))
+        else:
+            result = "".join(lines)
+        if len(result) > self.max_chars:
+            return result[: self.max_chars] + "\n...[truncated]"
+        return result
+
+    async def __call__(self) -> str:
+        return await asyncio.to_thread(self._blocking)

{axio_tools_local-0.2.2 → axio_tools_local-0.2.4}/src/axio_tools_local/run_python.py

@@ -41,16 +41,18 @@ class RunPython(ToolHandler):
                     input=self.stdin if self.stdin is not None else None,
                     stdin=subprocess.DEVNULL if self.stdin is None else None,
                 )
-                output = ""
-                if result.stdout:
-                    output += result.stdout
-                if result.stderr:
-                    output += f"\n[stderr]\n{result.stderr}"
-                if result.returncode != 0:
-                    output += f"\n[exit code: {result.returncode}]"
-                return output.strip() or "(no output)"
+            except subprocess.TimeoutExpired:
+                return f"[timeout: code exceeded {self.timeout}s]"
             finally:
                 os.unlink(path)
+            output = ""
+            if result.stdout:
+                output += result.stdout
+            if result.stderr:
+                output += f"\n[stderr]\n{result.stderr}"
+            if result.returncode != 0:
+                output += f"\n[exit code: {result.returncode}]"
+            return output.strip() or "(no output)"
 
     async def __call__(self) -> str:
         return await asyncio.to_thread(self._blocking)

{axio_tools_local-0.2.2 → axio_tools_local-0.2.4}/src/axio_tools_local/shell.py

@@ -21,16 +21,19 @@ class Shell(ToolHandler):
         return f"Shell(command={_short(self.command)!r}, cwd={self.cwd!r})"
 
     def _blocking(self) -> str:
-        result = subprocess.run(
-            self.command,
-            shell=True,
-            capture_output=True,
-            text=True,
-            timeout=self.timeout,
-            cwd=self.cwd,
-            input=self.stdin if self.stdin is not None else None,
-            stdin=subprocess.DEVNULL if self.stdin is None else None,
-        )
+        try:
+            result = subprocess.run(
+                self.command,
+                shell=True,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout,
+                cwd=self.cwd,
+                input=self.stdin if self.stdin is not None else None,
+                stdin=subprocess.DEVNULL if self.stdin is None else None,
+            )
+        except subprocess.TimeoutExpired:
+            return f"[timeout: command exceeded {self.timeout}s]"
         output = ""
         if result.stdout:
             output += result.stdout

axio_tools_local-0.2.4/tests/test_list_files.py

@@ -0,0 +1,113 @@
+"""Tests for ListFiles tool handler."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+from axio_tools_local.list_files import ListFiles
+
+
+@pytest.fixture()
+def tmp_cwd(tmp_path: Path) -> Path:
+    old = os.getcwd()
+    os.chdir(tmp_path)
+    yield tmp_path
+    os.chdir(old)
+
+
+async def ls(directory: str = ".") -> str:
+    return await ListFiles(directory=directory)()
+
+
+class TestListFilesBasic:
+    async def test_lists_files_and_dirs(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "a.txt").write_text("a")
+        (tmp_cwd / "b.txt").write_text("b")
+        (tmp_cwd / "subdir").mkdir()
+        result = await ls()
+        assert "a.txt" in result
+        assert "b.txt" in result
+        assert "subdir/" in result
+
+    async def test_dirs_listed_before_files(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "z_file.txt").write_text("z")
+        (tmp_cwd / "a_dir").mkdir()
+        result = await ls()
+        lines = result.splitlines()
+        dir_idx = next(i for i, l in enumerate(lines) if "a_dir/" in l)
+        file_idx = next(i for i, l in enumerate(lines) if "z_file.txt" in l)
+        assert dir_idx < file_idx
+
+    async def test_empty_directory(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "empty").mkdir()
+        result = await ls("empty")
+        assert result == "(empty directory)"
+
+    async def test_default_directory_is_dot(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "file.txt").write_text("x")
+        result = await ls()
+        assert "file.txt" in result
+
+    async def test_subdirectory_path(self, tmp_cwd: Path) -> None:
+        sub = tmp_cwd / "sub"
+        sub.mkdir()
+        (sub / "inner.txt").write_text("x")
+        result = await ls("sub")
+        assert "inner.txt" in result
+
+    async def test_not_a_directory_raises(self, tmp_cwd: Path) -> None:
+        with pytest.raises(FileNotFoundError):
+            await ls("nope")
+
+    async def test_shows_permissions(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("x")
+        result = await ls()
+        # permissions line starts with '-' for files
+        assert any(line.startswith("-") for line in result.splitlines())
+
+    async def test_shows_size(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("hello")
+        result = await ls()
+        assert "5" in result
+
+    async def test_trailing_slash_on_dirs_only(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "mydir").mkdir()
+        (tmp_cwd / "myfile.txt").write_text("x")
+        result = await ls()
+        assert "mydir/" in result
+        assert "myfile.txt/" not in result
+
+
+class TestListFilesSymlinks:
+    async def test_broken_symlink_does_not_crash(self, tmp_cwd: Path) -> None:
+        """Broken symlink must produce a [broken symlink] entry, not an exception."""
+        link = tmp_cwd / "dead_link"
+        link.symlink_to(tmp_cwd / "nonexistent_target")
+        result = await ls()
+        assert "dead_link" in result
+        assert "[broken symlink]" in result
+
+    async def test_valid_symlink_to_file(self, tmp_cwd: Path) -> None:
+        target = tmp_cwd / "real.txt"
+        target.write_text("x")
+        (tmp_cwd / "link.txt").symlink_to(target)
+        result = await ls()
+        assert "link.txt" in result
+        assert "[broken symlink]" not in result
+
+    async def test_mixed_broken_and_valid(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "good.txt").write_text("x")
+        (tmp_cwd / "bad_link").symlink_to(tmp_cwd / "nowhere")
+        result = await ls()
+        assert "good.txt" in result
+        assert "bad_link" in result
+        assert "[broken symlink]" in result
+
+
+class TestListFilesMisc:
+    async def test_repr(self) -> None:
+        assert "." in repr(ListFiles())
+        assert "src" in repr(ListFiles(directory="src"))

axio_tools_local-0.2.4/tests/test_patch_file.py

@@ -0,0 +1,188 @@
+"""Tests for PatchFile tool handler.
+
+All line numbers are 1-indexed, both inclusive:
+  from_line=2, to_line=4 replaces lines 2, 3, 4.
+  Insert without deleting: to_line = from_line - 1.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+from axio_tools_local.patch_file import PatchFile
+
+
+@pytest.fixture()
+def tmp_cwd(tmp_path: Path) -> Path:
+    old = os.getcwd()
+    os.chdir(tmp_path)
+    yield tmp_path
+    os.chdir(old)
+
+
+async def patch(path: Path, from_line: int, to_line: int, content: str) -> str:
+    handler = PatchFile(file_path=path.name, from_line=from_line, to_line=to_line, content=content)
+    return await handler()
+
+
+class TestPatchBasic:
+    async def test_replace_middle_lines(self, tmp_cwd: Path) -> None:
+        f = tmp_cwd / "f.txt"
+        f.write_text("line1\nline2\nline3\nline4\n")
+        await patch(f, 2, 3, "replaced\n")
+        assert f.read_text() == "line1\nreplaced\nline4\n"
+
+    async def test_replace_first_line(self, tmp_cwd: Path) -> None:
+        f = tmp_cwd / "f.txt"
+        f.write_text("line1\nline2\nline3\n")
+        await patch(f, 1, 1, "new1\n")
+        assert f.read_text() == "new1\nline2\nline3\n"
+
+    async def test_replace_last_line(self, tmp_cwd: Path) -> None:
+        f = tmp_cwd / "f.txt"
+        f.write_text("line1\nline2\nline3\n")
+        await patch(f, 3, 3, "new3\n")
+        assert f.read_text() == "line1\nline2\nnew3\n"
+
+    async def test_replace_all_lines(self, tmp_cwd: Path) -> None:
+        f = tmp_cwd / "f.txt"
+        f.write_text("a\nb\nc\n")
+        await patch(f, 1, 3, "x\ny\n")
+        assert f.read_text() == "x\ny\n"
+
+    async def test_replace_with_more_lines(self, tmp_cwd: Path) -> None:
+        """Replacing 1 line with 3 lines."""
+        f = tmp_cwd / "f.txt"
+        f.write_text("a\nb\nc\n")
+        await patch(f, 2, 2, "x\ny\nz\n")
+        assert f.read_text() == "a\nx\ny\nz\nc\n"
+
+    async def test_replace_with_fewer_lines(self, tmp_cwd: Path) -> None:
+        """Replacing 3 lines with 1 line."""
+        f = tmp_cwd / "f.txt"
+        f.write_text("a\nb\nc\nd\n")
+        await patch(f, 1, 3, "only\n")
+        assert f.read_text() == "only\nd\n"
+
+
+class TestPatchInsertDelete:
+    async def test_insert_without_deleting(self, tmp_cwd: Path) -> None:
+        """to_line = from_line - 1 inserts before from_line without deleting."""
+        f = tmp_cwd / "f.txt"
+        f.write_text("a\nb\nc\n")
+        await patch(f, 2, 1, "inserted\n")
+        assert f.read_text() == "a\ninserted\nb\nc\n"
+
+    async def test_insert_at_start(self, tmp_cwd: Path) -> None:
+        f = tmp_cwd / "f.txt"
+        f.write_text("a\nb\n")
+        await patch(f, 1, 0, "before_a\n")
+        assert f.read_text() == "before_a\na\nb\n"
+
+    async def test_append_to_end(self, tmp_cwd: Path) -> None:
+        """Insert after last line: from_line = N+1, to_line = N."""
+        f = tmp_cwd / "f.txt"
+        f.write_text("a\nb\n")
+        await patch(f, 3, 2, "appended\n")
+        assert f.read_text() == "a\nb\nappended\n"
+
+    async def test_delete_lines_empty_content(self, tmp_cwd: Path) -> None:
+        """Empty content string deletes the specified lines."""
+        f = tmp_cwd / "f.txt"
+        f.write_text("a\nb\nc\n")
+        await patch(f, 2, 2, "")
+        assert f.read_text() == "a\nc\n"
+
+    async def test_delete_multiple_lines(self, tmp_cwd: Path) -> None:
+        f = tmp_cwd / "f.txt"
+        f.write_text("a\nb\nc\nd\n")
+        await patch(f, 2, 3, "")
+        assert f.read_text() == "a\nd\n"
+
+
+class TestNewlineHandling:
+    async def test_content_without_trailing_newline(self, tmp_cwd: Path) -> None:
+        """Content without \\n must not corrupt next line."""
+        f = tmp_cwd / "f.txt"
+        f.write_text("a\nb\nc\n")
+        await patch(f, 2, 2, "replaced")  # no trailing newline
+        assert f.read_text() == "a\nreplaced\nc\n"
+
+    async def test_multiline_content_no_trailing_newline(self, tmp_cwd: Path) -> None:
+        f = tmp_cwd / "f.txt"
+        f.write_text("a\nb\nc\n")
+        await patch(f, 2, 2, "x\ny")  # no trailing newline on last line
+        assert f.read_text() == "a\nx\ny\nc\n"
+
+    async def test_adjacent_lines_not_corrupted(self, tmp_cwd: Path) -> None:
+        """Lines before and after patch range are exactly preserved."""
+        f = tmp_cwd / "f.txt"
+        f.write_text("first\nsecond\nthird\nfourth\nfifth\n")
+        await patch(f, 3, 3, "REPLACED\n")
+        lines = f.read_text().splitlines()
+        assert lines == ["first", "second", "REPLACED", "fourth", "fifth"]
+
+    async def test_content_extra_trailing_newlines(self, tmp_cwd: Path) -> None:
+        """Content with extra trailing newlines creates blank lines."""
+        f = tmp_cwd / "f.txt"
+        f.write_text("a\nb\nc\n")
+        await patch(f, 2, 2, "x\n\n")
+        assert f.read_text() == "a\nx\n\nc\n"
+
+    async def test_single_line_file_replace(self, tmp_cwd: Path) -> None:
+        f = tmp_cwd / "f.txt"
+        f.write_text("only line\n")
+        await patch(f, 1, 1, "new line\n")
+        assert f.read_text() == "new line\n"
+
+    async def test_single_line_file_no_trailing_newline(self, tmp_cwd: Path) -> None:
+        f = tmp_cwd / "f.txt"
+        f.write_text("only line")
+        await patch(f, 1, 1, "replaced\n")
+        assert f.read_text() == "replaced\n"
+
+    async def test_file_no_trailing_newline_patch_middle(self, tmp_cwd: Path) -> None:
+        f = tmp_cwd / "f.txt"
+        f.write_text("a\nb\nc")  # c has no trailing newline
+        await patch(f, 2, 2, "B\n")
+        assert f.read_text() == "a\nB\nc"
+
+
+class TestEdgeCases:
+    async def test_file_not_found(self, tmp_cwd: Path) -> None:
+        with pytest.raises(FileNotFoundError):
+            await patch(tmp_cwd / "missing.txt", 1, 1, "x")
+
+    async def test_returns_bytes_written_message(self, tmp_cwd: Path) -> None:
+        f = tmp_cwd / "f.txt"
+        f.write_text("a\nb\n")
+        result = await patch(f, 1, 1, "x\n")
+        assert "bytes written" in result
+        assert "f.txt" in result
+
+    async def test_empty_file_append(self, tmp_cwd: Path) -> None:
+        f = tmp_cwd / "f.txt"
+        f.write_text("")
+        await patch(f, 1, 0, "new\n")
+        assert f.read_text() == "new\n"
+
+    async def test_indented_code_preserved(self, tmp_cwd: Path) -> None:
+        f = tmp_cwd / "f.py"
+        f.write_text("def foo():\n    return 1\n\ndef bar():\n    return 2\n")
+        await patch(f, 2, 2, "    return 42\n")
+        assert f.read_text() == "def foo():\n    return 42\n\ndef bar():\n    return 2\n"
+
+    async def test_unicode_content(self, tmp_cwd: Path) -> None:
+        f = tmp_cwd / "f.txt"
+        f.write_text("привет\nмир\n")
+        await patch(f, 1, 1, "hello\n")
+        assert f.read_text() == "hello\nмир\n"
+
+    async def test_repr(self) -> None:
+        h = PatchFile(file_path="f.py", from_line=5, to_line=10, content="code")
+        r = repr(h)
+        assert "f.py" in r
+        assert "5:10" in r

axio_tools_local-0.2.4/tests/test_read_file.py

@@ -0,0 +1,170 @@
+"""Tests for ReadFile tool handler."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+from axio_tools_local.read_file import ReadFile
+
+
+@pytest.fixture()
+def tmp_cwd(tmp_path: Path) -> Path:
+    old = os.getcwd()
+    os.chdir(tmp_path)
+    yield tmp_path
+    os.chdir(old)
+
+
+async def read(tmp_cwd: Path, filename: str, **kwargs: object) -> str:
+    return await ReadFile(filename=filename, **kwargs)()
+
+
+class TestReadFilePlain:
+    """indexed=False (default) — plain text, no line numbers."""
+
+    async def test_single_line(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("content here")
+        assert await read(tmp_cwd, "f.txt") == "content here"
+
+    async def test_multiline(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("a\nb\nc\n")
+        assert await read(tmp_cwd, "f.txt") == "a\nb\nc\n"
+
+    async def test_no_trailing_newline_preserved(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("no newline")
+        assert await read(tmp_cwd, "f.txt") == "no newline"
+
+    async def test_empty_file(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("")
+        assert await read(tmp_cwd, "f.txt") == ""
+
+    async def test_indentation_preserved(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.py").write_text("def f():\n    pass\n")
+        result = await read(tmp_cwd, "f.py")
+        assert "    pass" in result
+
+    async def test_unicode(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("привет\nмир\n")
+        result = await read(tmp_cwd, "f.txt")
+        assert "привет" in result
+        assert "мир" in result
+
+
+class TestReadFileIndexed:
+    """indexed=True — each line prefixed with 1-based number."""
+
+    async def test_first_line_is_1(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("hello\n")
+        result = await read(tmp_cwd, "f.txt", indexed=True)
+        assert result.startswith("1\t")
+
+    async def test_numbers_are_one_indexed(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("a\nb\nc\n")
+        result = await read(tmp_cwd, "f.txt", indexed=True)
+        lines = result.splitlines()
+        assert lines[0] == "1\ta"
+        assert lines[1] == "2\tb"
+        assert lines[2] == "3\tc"
+
+    async def test_no_line_numbers_without_indexed(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("a\nb\n")
+        result = await read(tmp_cwd, "f.txt")
+        assert not any(line[0].isdigit() for line in result.splitlines())
+
+    async def test_single_line_no_trailing_newline(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("only")
+        result = await read(tmp_cwd, "f.txt", indexed=True)
+        assert result == "1\tonly"
+
+    async def test_indentation_preserved_with_index(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.py").write_text("def f():\n    pass\n")
+        result = await read(tmp_cwd, "f.py", indexed=True)
+        assert "2\t    pass" in result
+
+
+class TestReadFileRange:
+    async def test_start_line_1_is_first(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("a\nb\nc\n")
+        result = await read(tmp_cwd, "f.txt", start_line=1)
+        assert "a" in result and "b" in result and "c" in result
+
+    async def test_start_line_skips_before(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("a\nb\nc\nd\n")
+        result = await read(tmp_cwd, "f.txt", start_line=3)
+        assert "a" not in result
+        assert "b" not in result
+        assert "c" in result
+        assert "d" in result
+
+    async def test_end_line_is_inclusive(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("a\nb\nc\nd\n")
+        result = await read(tmp_cwd, "f.txt", end_line=2)
+        assert "a" in result
+        assert "b" in result
+        assert "c" not in result
+        assert "d" not in result
+
+    async def test_start_and_end_line(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("a\nb\nc\nd\ne\n")
+        result = await read(tmp_cwd, "f.txt", start_line=2, end_line=4)
+        assert "a" not in result
+        assert "b" in result
+        assert "c" in result
+        assert "d" in result
+        assert "e" not in result
+
+    async def test_indexed_numbers_reflect_file_position(self, tmp_cwd: Path) -> None:
+        """Line numbers must reflect position in the file, not position in the slice."""
+        lines = [f"line{i}\n" for i in range(1, 11)]
+        (tmp_cwd / "f.txt").write_text("".join(lines))
+        result = await read(tmp_cwd, "f.txt", start_line=5, end_line=7, indexed=True)
+        out = result.splitlines()
+        assert out[0] == "5\tline5"
+        assert out[1] == "6\tline6"
+        assert out[2] == "7\tline7"
+
+    async def test_single_line_range(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("a\nb\nc\n")
+        result = await read(tmp_cwd, "f.txt", start_line=2, end_line=2)
+        assert result.strip() == "b"
+
+
+class TestReadFileTruncation:
+    async def test_truncated_at_max_chars(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("a" * 200)
+        result = await read(tmp_cwd, "f.txt", max_chars=10)
+        assert "[truncated]" in result
+
+    async def test_no_truncation_within_limit(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "f.txt").write_text("hello\n")
+        result = await read(tmp_cwd, "f.txt", max_chars=32768)
+        assert "[truncated]" not in result
+
+
+class TestReadFileBinary:
+    async def test_binary_as_hex(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "b.dat").write_bytes(b"\x80\x81\xff")
+        result = await read(tmp_cwd, "b.dat", binary_as_hex=True)
+        assert "8081ff" in result
+
+    async def test_binary_hex_truncated_to_max_chars(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "b.dat").write_bytes(bytes(range(256)))
+        result = await read(tmp_cwd, "b.dat", binary_as_hex=True, max_chars=20)
+        assert len(result) < 600
+
+    async def test_binary_raises_without_hex(self, tmp_cwd: Path) -> None:
+        (tmp_cwd / "b.dat").write_bytes(b"\x80\x81\xff")
+        with pytest.raises(UnicodeDecodeError):
+            await ReadFile(filename="b.dat", binary_as_hex=False)()
+
+
+class TestReadFileMisc:
+    async def test_file_not_found(self, tmp_cwd: Path) -> None:
+        with pytest.raises(FileNotFoundError):
+            await read(tmp_cwd, "nope.txt")
+
+    async def test_repr(self) -> None:
+        assert "test.py" in repr(ReadFile(filename="test.py"))