agentpool 2.1.9__py3-none-any.whl → 2.5.0__py3-none-any.whl

agentpool_toolsets/fsspec_toolset/toolset.py

@@ -7,18 +7,20 @@ from fnmatch import fnmatch
 import os
 from pathlib import Path
 import time
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 from urllib.parse import urlparse
 
 import anyio
 from exxec.base import ExecutionEnvironment
 from pydantic_ai import (
     BinaryContent,
+    ModelResponse,
     PartDeltaEvent,
     PartStartEvent,
     RunContext,  # noqa: TC002
     TextPart,
     TextPartDelta,
+    ToolCallPart,
 )
 from upathtools import is_directory
 
@@ -26,9 +28,19 @@ from agentpool.agents.context import AgentContext  # noqa: TC001
 from agentpool.log import get_logger
 from agentpool.mime_utils import guess_type, is_binary_content, is_binary_mime
 from agentpool.resource_providers import ResourceProvider
+from agentpool.tool_impls.delete_path import create_delete_path_tool
+from agentpool.tool_impls.download_file import create_download_file_tool
+from agentpool.tool_impls.grep import create_grep_tool
+from agentpool.tool_impls.list_directory import create_list_directory_tool
+from agentpool.tool_impls.read import create_read_tool
+from agentpool.tools.base import ToolResult  # noqa: TC001
 from agentpool_toolsets.builtin.file_edit import replace_content
 from agentpool_toolsets.builtin.file_edit.fuzzy_matcher import StreamingFuzzyMatcher
-from agentpool_toolsets.fsspec_toolset.diagnostics import DiagnosticsManager
+from agentpool_toolsets.fsspec_toolset.diagnostics import (
+    DiagnosticsConfig,
+    DiagnosticsManager,
+    format_diagnostics_table,
+)
 from agentpool_toolsets.fsspec_toolset.grep import GrepBackend
 from agentpool_toolsets.fsspec_toolset.helpers import (
     format_directory_listing,
@@ -43,9 +55,11 @@ from agentpool_toolsets.fsspec_toolset.streaming_diff_parser import (
 
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     import fsspec
     from fsspec.asyn import AsyncFileSystem
-    from pydantic_ai.messages import ModelResponse
+    from pydantic_ai import ModelRequest
 
     from agentpool.agents.base_agent import BaseAgent
     from agentpool.common_types import ModelType
@@ -78,6 +92,9 @@ class FSSpecTools(ResourceProvider):
         enable_diagnostics: bool = False,
         large_file_tokens: int = 12_000,
         map_max_tokens: int = 2048,
+        edit_tool: Literal["simple", "batch", "agentic"] = "simple",
+        max_image_size: int | None = 2000,
+        max_image_bytes: int | None = None,
     ) -> None:
         """Initialize with an fsspec filesystem or execution environment.
 
@@ -94,6 +111,12 @@ class FSSpecTools(ResourceProvider):
             enable_diagnostics: Run LSP CLI diagnostics after file writes (default: False)
             large_file_tokens: Token threshold for switching to structure map (default: 12000)
             map_max_tokens: Maximum tokens for structure map output (default: 2048)
+            edit_tool: Which edit variant to expose ("simple" or "batch")
+            max_image_size: Max width/height for images in pixels. Larger images are
+                auto-resized for better model compatibility. Set to None to disable.
+            max_image_bytes: Max file size for images in bytes. Images exceeding this
+                are compressed using progressive quality/dimension reduction.
+                Default: 4.5MB (below Anthropic's 5MB limit).
         """
         from fsspec.asyn import AsyncFileSystem
         from fsspec.implementations.asyn_wrapper import AsyncFileSystemWrapper
@@ -124,8 +147,11 @@ class FSSpecTools(ResourceProvider):
         self._large_file_tokens = large_file_tokens
         self._map_max_tokens = map_max_tokens
         self._repomap: RepoMap | None = None
+        self._edit_tool = edit_tool
+        self._max_image_size = max_image_size
+        self._max_image_bytes = max_image_bytes
 
-    def get_fs(self, agent_ctx: AgentContext) -> AsyncFileSystem:
+    def _get_fs(self, agent_ctx: AgentContext) -> AsyncFileSystem:
         """Get filesystem, falling back to agent's env if not set.
 
         Args:
@@ -139,11 +165,15 @@ class FSSpecTools(ResourceProvider):
         fs = agent_ctx.agent.env.get_fs()
         return fs if isinstance(fs, AsyncFileSystem) else AsyncFileSystemWrapper(fs)
 
-    def _get_diagnostics_manager(self, agent_ctx: AgentContext) -> DiagnosticsManager:
+    def _get_diagnostics_manager(self, agent_ctx: AgentContext) -> DiagnosticsManager | None:
         """Get or create the diagnostics manager."""
+        if not self._enable_diagnostics:
+            return None
         if self._diagnostics is None:
             env = self.execution_env or agent_ctx.agent.env
-            self._diagnostics = DiagnosticsManager(env if self._enable_diagnostics else None)
+            # Default to rust-only for fast feedback after edits
+            config = DiagnosticsConfig(rust_only=True, max_servers_per_language=1)
+            self._diagnostics = DiagnosticsManager(env, config=config)
         return self._diagnostics
 
     async def _run_diagnostics(self, agent_ctx: AgentContext, path: str) -> str | None:
@@ -151,12 +181,12 @@ class FSSpecTools(ResourceProvider):
 
         Returns formatted diagnostics string if issues found, None otherwise.
         """
-        if not self._enable_diagnostics:
-            return None
         mgr = self._get_diagnostics_manager(agent_ctx)
-        diagnostics = await mgr.run_for_file(path)
-        if diagnostics:
-            return mgr.format_diagnostics(diagnostics)
+        if mgr is None:
+            return None
+        result = await mgr.run_for_file(path)
+        if result.diagnostics:
+            return format_diagnostics_table(result.diagnostics)
         return None
 
     async def _get_file_map(self, path: str, agent_ctx: AgentContext) -> str | None:
@@ -177,7 +207,7 @@ class FSSpecTools(ResourceProvider):
         # Lazy init repomap - use file's directory as root
         if self._repomap is None:
             root = str(Path(path).parent)
-            fs = self.get_fs(agent_ctx)
+            fs = self._get_fs(agent_ctx)
             self._repomap = RepoMap(fs, root, max_tokens=self._map_max_tokens)
 
         return await self._repomap.get_file_map(path, max_tokens=self._map_max_tokens)
@@ -202,31 +232,66 @@ class FSSpecTools(ResourceProvider):
             return str(Path(cwd) / path)
         return path
 
-    async def get_tools(self) -> list[Tool]:
+    async def get_tools(self) -> Sequence[Tool]:
         """Get filesystem tools."""
         if self._tools is not None:
             return self._tools
 
+        # Create standalone tools with toolset's configuration
+        list_dir_tool = create_list_directory_tool(
+            env=self.execution_env,
+            cwd=self.cwd,
+        )
+
+        read_tool = create_read_tool(
+            env=self.execution_env,
+            converter=self.converter,  # Pass converter for automatic markdown conversion
+            cwd=self.cwd,
+            max_file_size_kb=self.max_file_size // 1024,
+            max_image_size=self._max_image_size,
+            max_image_bytes=self._max_image_bytes,
+            large_file_tokens=self._large_file_tokens,
+            map_max_tokens=self._map_max_tokens,
+        )
+
+        grep_tool = create_grep_tool(
+            env=self.execution_env,
+            cwd=self.cwd,
+            max_output_kb=self.max_grep_output // 1024,
+            use_subprocess_grep=self.use_subprocess_grep,
+        )
+
+        delete_tool = create_delete_path_tool(
+            env=self.execution_env,
+            cwd=self.cwd,
+        )
+
+        download_tool = create_download_file_tool(
+            env=self.execution_env,
+            cwd=self.cwd,
+        )
+
         self._tools = [
-            self.create_tool(self.list_directory, category="read", read_only=True, idempotent=True),
-            self.create_tool(self.read_file, category="read", read_only=True, idempotent=True),
-            self.create_tool(self.grep, category="search", read_only=True, idempotent=True),
-            self.create_tool(self.write_file, category="edit"),
-            self.create_tool(self.delete_path, category="delete", destructive=True),
-            self.create_tool(self.edit_file, category="edit"),
-            self.create_tool(self.agentic_edit, category="edit"),
-            self.create_tool(self.download_file, category="read", open_world=True),
+            list_dir_tool,
+            read_tool,
+            grep_tool,
+            self.create_tool(self.write, category="edit"),
+            delete_tool,
+            download_tool,
         ]
 
-        if self.converter:  # Only add read_as_markdown if converter is available
+        # Add edit tool based on config - mutually exclusive
+        if self._edit_tool == "agentic":
+            self._tools.append(self.create_tool(self.agentic_edit, category="edit"))
+        elif self._edit_tool == "batch":
             self._tools.append(
-                self.create_tool(
-                    self.read_as_markdown,
-                    category="read",
-                    read_only=True,
-                    idempotent=True,
-                )
+                self.create_tool(self.edit_batch, category="edit", name_override="edit")
             )
+        else:  # simple
+            self._tools.append(self.create_tool(self.edit, category="edit"))
+
+        # Add regex line editing tool
+        self._tools.append(self.create_tool(self.regex_replace_lines, category="edit"))
 
         return self._tools
 
@@ -258,7 +323,7 @@ class FSSpecTools(ResourceProvider):
         await agent_ctx.events.tool_call_start(title=msg, kind="read", locations=[path])
 
         try:
-            fs = self.get_fs(agent_ctx)
+            fs = self._get_fs(agent_ctx)
             # Check if path exists
             if not await fs._exists(path):
                 error_msg = f"Path does not exist: {path}"
@@ -329,14 +394,14 @@ class FSSpecTools(ResourceProvider):
         else:
             return result
 
-    async def read_file(  # noqa: D417
+    async def read(  # noqa: D417
         self,
         agent_ctx: AgentContext,
         path: str,
         encoding: str = "utf-8",
         line: int | None = None,
         limit: int | None = None,
-    ) -> str | BinaryContent:
+    ) -> str | BinaryContent | list[str | BinaryContent]:
         """Read the context of a text file, or use vision capabilites to read images or documents.
 
         Args:
@@ -346,30 +411,57 @@ class FSSpecTools(ResourceProvider):
             limit: Optional maximum number of lines to read (text files only)
 
         Returns:
-            Text content for text files, BinaryContent for binary files, or dict with error
+            Text content for text files, BinaryContent for binary files (with optional
+            dimension note as list when image was resized), or dict with error
         """
         path = self._resolve_path(path, agent_ctx)
         msg = f"Reading file: {path}"
         from agentpool.agents.events import LocationContentItem
 
+        # Emit progress - use 0 for line if negative (can't resolve until we read file)
+        # LocationContentItem/ToolCallLocation require line >= 0 per ACP spec
+        display_line = line if (line is not None and line > 0) else 0
         await agent_ctx.events.tool_call_progress(
             title=msg,
-            items=[LocationContentItem(path=path)],
+            items=[LocationContentItem(path=path, line=display_line)],
         )
         try:
             mime_type = guess_type(path)
             # Fast path: known binary MIME types (images, audio, video, etc.)
             if is_binary_mime(mime_type):
-                data = await self.get_fs(agent_ctx)._cat_file(path)
+                data = await self._get_fs(agent_ctx)._cat_file(path)
                 await agent_ctx.events.file_operation("read", path=path, success=True)
                 mime = mime_type or "application/octet-stream"
+                # Resize images if needed
+                if self._max_image_size and mime.startswith("image/"):
+                    from agentpool_toolsets.fsspec_toolset.image_utils import (
+                        resize_image_if_needed,
+                    )
+
+                    data, mime, note = resize_image_if_needed(
+                        data, mime, self._max_image_size, self._max_image_bytes
+                    )
+                    if note:
+                        # Return resized image with dimension note for coordinate mapping
+                        return [note, BinaryContent(data=data, media_type=mime, identifier=path)]
                 return BinaryContent(data=data, media_type=mime, identifier=path)
             # Read content and probe for binary (git-style null byte detection)
-            data = await self.get_fs(agent_ctx)._cat_file(path)
+            data = await self._get_fs(agent_ctx)._cat_file(path)
             if is_binary_content(data):
                 # Binary file - return as BinaryContent for native model handling
                 await agent_ctx.events.file_operation("read", path=path, success=True)
                 mime = mime_type or "application/octet-stream"
+                # Resize images if needed
+                if self._max_image_size and mime.startswith("image/"):
+                    from agentpool_toolsets.fsspec_toolset.image_utils import (
+                        resize_image_if_needed,
+                    )
+
+                    data, mime, note = resize_image_if_needed(
+                        data, mime, self._max_image_size, self._max_image_bytes
+                    )
+                    if note:
+                        return [note, BinaryContent(data=data, media_type=mime, identifier=path)]
                 return BinaryContent(data=data, media_type=mime, identifier=path)
             content = data.decode(encoding)
 
@@ -395,7 +487,11 @@ class FSSpecTools(ResourceProvider):
                     lines, offset, limit, self.max_file_size
                 )
                 content = "\n".join(result_lines)
-                await agent_ctx.events.file_operation("read", path=path, success=True)
+                # Don't pass negative line numbers to events (ACP requires >= 0)
+                display_line = line if (line and line > 0) else 0
+                await agent_ctx.events.file_operation(
+                    "read", path=path, success=True, line=display_line
+                )
                 if was_truncated:
                     content += f"\n\n[Content truncated at {self.max_file_size} bytes]"
 
@@ -406,9 +502,11 @@ class FSSpecTools(ResourceProvider):
             # Emit file content for UI display (formatted at ACP layer)
             from agentpool.agents.events import FileContentItem
 
+            # Use non-negative line for display (negative lines are internal Python convention)
+            display_start_line = max(1, line) if line and line > 0 else None
             await agent_ctx.events.tool_call_progress(
                 title=f"Read: {path}",
-                items=[FileContentItem(content=content, path=path)],
+                items=[FileContentItem(content=content, path=path, start_line=display_start_line)],
                 replace_content=True,
             )
             # Return raw content for agent
@@ -445,14 +543,14 @@ class FSSpecTools(ResourceProvider):
         else:
             return content
 
-    async def write_file(  # noqa: D417
+    async def write(  # noqa: D417
         self,
         agent_ctx: AgentContext,
         path: str,
         content: str,
         mode: str = "w",
         overwrite: bool = False,
-    ) -> dict[str, Any]:
+    ) -> str | ToolResult:
         """Write content to a file.
 
         Args:
@@ -462,8 +560,11 @@ class FSSpecTools(ResourceProvider):
             overwrite: Must be True to overwrite existing files (safety check)
 
         Returns:
-            Dictionary with success info or error details
+            Success message or ToolResult with metadata
         """
+        from agentpool.agents.events import DiffContentItem
+        from agentpool.tools.base import ToolResult
+
         path = self._resolve_path(path, agent_ctx)
         msg = f"Writing file: {path}"
         await agent_ctx.events.tool_call_start(title=msg, kind="edit", locations=[path])
@@ -474,7 +575,7 @@ class FSSpecTools(ResourceProvider):
             if mode not in ("w", "a"):
                 msg = f"Invalid mode '{mode}'. Use 'w' (write) or 'a' (append)"
                 await agent_ctx.events.file_operation("write", path=path, success=False, error=msg)
-                return {"error": msg}
+                return f"Error: {msg}"
 
             # Check size limit
             if content_bytes > self.max_file_size:
@@ -483,10 +584,10 @@ class FSSpecTools(ResourceProvider):
                     f"({self.max_file_size} bytes)"
                 )
                 await agent_ctx.events.file_operation("write", path=path, success=False, error=msg)
-                return {"error": msg}
+                return f"Error: {msg}"
 
             # Check if file exists and overwrite protection
-            fs = self.get_fs(agent_ctx)
+            fs = self._get_fs(agent_ctx)
             file_exists = await fs._exists(path)
 
             if file_exists and mode == "w" and not overwrite:
@@ -495,7 +596,7 @@ class FSSpecTools(ResourceProvider):
                     f"This is a safety measure to prevent accidental data loss."
                 )
                 await agent_ctx.events.file_operation("write", path=path, success=False, error=msg)
-                return {"error": msg}
+                return f"Error: {msg}"
 
             # Handle append mode: read existing content and prepend it
             if mode == "a" and file_exists:
@@ -508,30 +609,47 @@ class FSSpecTools(ResourceProvider):
                     pass  # If we can't read, just write new content
 
             await self._write(agent_ctx, path, content)
+            await agent_ctx.events.tool_call_progress(
+                title=f"Wrote: {path}",
+                items=[
+                    DiffContentItem(path=path, old_text="", new_text=content),
+                ],
+            )
 
-            try:
-                info = await fs._info(path)
-                size = info.get("size", content_bytes)
-            except (OSError, KeyError):
-                size = content_bytes
-
-            result: dict[str, Any] = {
-                "path": path,
-                "size": size,
-                "mode": mode,
-                "file_existed": file_exists,
-                "bytes_written": content_bytes,
-            }
-            await agent_ctx.events.file_operation("write", path=path, success=True)
-
-            # Run diagnostics if enabled
+            # Run diagnostics if enabled (include in message for agent)
+            diagnostics_msg = ""
             if diagnostics_output := await self._run_diagnostics(agent_ctx, path):
-                result["diagnostics"] = diagnostics_output
+                diagnostics_msg = f"\n\nDiagnostics:\n{diagnostics_output}"
+
+            action = "Appended to" if mode == "a" and file_exists else "Wrote"
+            success_msg = f"{action} {path} ({content_bytes} bytes){diagnostics_msg}"
+
+            # TODO: Include diagnostics in metadata for UI display
+            # Expected metadata shape:
+            # {
+            #   "diagnostics": {
+            #     "<file_path>": [
+            #       {
+            #         "range": {"start": {"line": 0, "character": 0}, "end": {...}},
+            #         "message": "...",
+            #         "severity": 1  # 1=error, 2=warning, 3=info, 4=hint
+            #       }
+            #     ]
+            #   }
+            # }
+
+            return ToolResult(
+                content=success_msg,  # Agent sees this (includes diagnostics text)
+                metadata={
+                    # Include file content for UI display (used by OpenCode TUI)
+                    "filePath": str(Path(path).absolute()),
+                    "content": content,
+                    # TODO: Add structured diagnostics here for UI
+                },
+            )
         except Exception as e:  # noqa: BLE001
             await agent_ctx.events.file_operation("write", path=path, success=False, error=str(e))
-            return {"error": f"Failed to write file {path}: {e}"}
-        else:
-            return result
+            return f"Error: Failed to write file {path}: {e}"
 
     async def delete_path(  # noqa: D417
         self, agent_ctx: AgentContext, path: str, recursive: bool = False
@@ -550,7 +668,7 @@ class FSSpecTools(ResourceProvider):
         await agent_ctx.events.tool_call_start(title=msg, kind="delete", locations=[path])
         try:
             # Check if path exists and get its type
-            fs = self.get_fs(agent_ctx)
+            fs = self._get_fs(agent_ctx)
             try:
                 info = await fs._info(path)
                 path_type = info.get("type", "unknown")
@@ -599,7 +717,7 @@ class FSSpecTools(ResourceProvider):
             await agent_ctx.events.file_operation("delete", path=path, success=True)
             return result
 
-    async def edit_file(  # noqa: D417
+    async def edit(  # noqa: D417
         self,
         agent_ctx: AgentContext,
         path: str,
@@ -607,7 +725,8 @@ class FSSpecTools(ResourceProvider):
         new_string: str,
         description: str,
         replace_all: bool = False,
-    ) -> str:
+        line_hint: int | None = None,
+    ) -> str | ToolResult:
         r"""Edit a file by replacing specific content with smart matching.
 
         Uses sophisticated matching strategies to handle whitespace, indentation,
@@ -619,32 +738,95 @@ class FSSpecTools(ResourceProvider):
             new_string: Text content to replace it with
             description: Human-readable description of what the edit accomplishes
             replace_all: Whether to replace all occurrences (default: False)
+            line_hint: Line number hint to disambiguate when multiple matches exist.
+                If the pattern matches multiple locations, the match closest to this
+                line will be used. Useful after getting a "multiple matches" error.
 
         Returns:
             Success message with edit summary
         """
+        return await self.edit_batch(
+            agent_ctx,
+            path,
+            replacements=[(old_string, new_string)],
+            description=description,
+            replace_all=replace_all,
+            line_hint=line_hint,
+        )
+
+    async def edit_batch(  # noqa: D417
+        self,
+        agent_ctx: AgentContext,
+        path: str,
+        replacements: list[tuple[str, str]],
+        description: str,
+        replace_all: bool = False,
+        line_hint: int | None = None,
+    ) -> str | ToolResult:
+        r"""Edit a file by applying multiple replacements in one operation.
+
+        Uses sophisticated matching strategies to handle whitespace, indentation,
+        and other variations. Shows the changes as a diff in the UI.
+
+        Replacements are applied sequentially, so later replacements see the result
+        of earlier ones. Each old_string must uniquely match one location (unless
+        replace_all=True). If a pattern matches multiple locations, include more
+        surrounding context to disambiguate.
+
+        Args:
+            path: File path (absolute or relative to session cwd)
+            replacements: List of (old_string, new_string) tuples to apply sequentially.
+                IMPORTANT: Must be a list of pairs, like:
+                  [("old text", "new text"), ("another old", "another new")]
+
+                Each old_string should include enough context to uniquely identify
+                the target location. For multi-line edits, include the full block.
+            description: Human-readable description of what the edit accomplishes
+            replace_all: Whether to replace all occurrences of each pattern (default: False)
+            line_hint: Line number hint to disambiguate when multiple matches exist.
+                Only applies when there is a single replacement. If the pattern matches
+                multiple locations, the match closest to this line will be used.
+
+        Returns:
+            Success message with edit summary
+
+        Example:
+            replacements=[
+                ("def old_name(", "def new_name("),
+                ("old_name()", "new_name()"),  # Update call sites
+            ]
+        """
         path = self._resolve_path(path, agent_ctx)
         msg = f"Editing file: {path}"
         await agent_ctx.events.tool_call_start(title=msg, kind="edit", locations=[path])
-        if old_string == new_string:
-            return "Error: old_string and new_string must be different"
 
-        # Send initial pending notification
-        await agent_ctx.events.file_operation("edit", path=path, success=True)
+        if not replacements:
+            return "Error: replacements list cannot be empty"
+
+        for old_str, new_str in replacements:
+            if old_str == new_str:
+                return f"Error: old_string and new_string must be different: {old_str!r}"
 
         try:  # Read current file content
             original_content = await self._read(agent_ctx, path)
             if isinstance(original_content, bytes):
                 original_content = original_content.decode("utf-8")
 
-            try:  # Apply smart content replacement
-                new_content = replace_content(original_content, old_string, new_string, replace_all)
-            except ValueError as e:
-                error_msg = f"Edit failed: {e}"
-                await agent_ctx.events.file_operation(
-                    "edit", path=path, success=False, error=error_msg
-                )
-                return error_msg
+            # Apply all replacements sequentially
+            new_content = original_content
+            # line_hint only makes sense for single replacements
+            hint = line_hint if len(replacements) == 1 else None
+            for old_str, new_str in replacements:
+                try:
+                    new_content = replace_content(
+                        new_content, old_str, new_str, replace_all, line_hint=hint
+                    )
+                except ValueError as e:
+                    error_msg = f"Edit failed on replacement {old_str!r}: {e}"
+                    await agent_ctx.events.file_operation(
+                        "edit", path=path, success=False, error=error_msg
+                    )
+                    return error_msg
 
             await self._write(agent_ctx, path, new_content)
             success_msg = f"Successfully edited {Path(path).name}: {description}"
@@ -666,9 +848,238 @@ class FSSpecTools(ResourceProvider):
             error_msg = f"Error editing file: {e}"
             await agent_ctx.events.file_operation("edit", path=path, success=False, error=error_msg)
             return error_msg
+        else:
+            # Generate unified diff for OpenCode UI
+            from difflib import unified_diff
+
+            from agentpool.tools.base import ToolResult
+
+            # Ensure content ends with newline for proper diff formatting
+            original_for_diff = (
+                original_content if original_content.endswith("\n") else original_content + "\n"
+            )
+            new_for_diff = new_content if new_content.endswith("\n") else new_content + "\n"
+
+            diff_lines = unified_diff(
+                original_for_diff.splitlines(keepends=True),
+                new_for_diff.splitlines(keepends=True),
+                fromfile=f"a/{Path(path).name}",
+                tofile=f"b/{Path(path).name}",
+            )
+            diff = "".join(diff_lines)
+
+            # Count additions and deletions
+            original_lines = set(original_content.splitlines())
+            new_lines = set(new_content.splitlines())
+            additions = len(new_lines - original_lines)
+            deletions = len(original_lines - new_lines)
+
+            return ToolResult(
+                content=success_msg,
+                metadata={
+                    "diff": diff,
+                    "filediff": {
+                        "file": str(Path(path).absolute()),
+                        "before": original_content,
+                        "after": new_content,
+                        "additions": additions,
+                        "deletions": deletions,
+                    },
+                },
+            )
+
+    async def regex_replace_lines(  # noqa: PLR0915
+        self,
+        agent_ctx: AgentContext,
+        path: str,
+        start: int | str,
+        end: int | str,
+        pattern: str,
+        replacement: str,
+        *,
+        count: int = 0,
+    ) -> str:
+        r"""Apply regex replacement to a line range specified by line numbers or text markers.
+
+        Useful for systematic edits:
+        - Remove/add indentation
+        - Comment/uncomment blocks
+        - Rename variables within scope
+        - Delete line ranges
+
+        Args:
+            agent_ctx: Agent execution context
+            path: File path to edit
+            start: Start of range - int (1-based line number) or str (unique text marker)
+            end: End of range - int (1-based line number) or str (first occurrence after start)
+            pattern: Regex pattern to search for within the range
+            replacement: Replacement string (supports \1, \2 capture groups; empty removes)
+            count: Max replacements per line (0 = unlimited)
+
+        Returns:
+            Success message with statistics
+
+        Examples:
+            # Remove a function
+            regex_replace_lines(ctx, "file.py", "def old_func(", "    return", r".*\n", "")
+
+            # Indent by line numbers
+            regex_replace_lines(ctx, "file.py", 10, 20, r"^", "    ")
+
+            # Uncomment a section
+            regex_replace_lines(ctx, "file.py", "# START", "# END", r"^# ", "")
+        """
+        import re
+
+        path = self._resolve_path(path, agent_ctx)
+        msg = f"Regex editing file: {path}"
+        await agent_ctx.events.tool_call_start(title=msg, kind="edit", locations=[path])
+
+        try:
+            # Read original content
+            original_content = await self._read(agent_ctx, path)
+            if isinstance(original_content, bytes):
+                original_content = original_content.decode("utf-8")
+
+            lines = original_content.splitlines(keepends=True)
+            total_lines = len(lines)
+
+            # Resolve start position
+            if isinstance(start, int):
+                if start < 1:
+                    msg = f"start line must be >= 1, got {start}"
+                    raise ValueError(msg)  # noqa: TRY301
+                start_line = start
+            else:
+                # Find unique occurrence of start string (raises ValueError if not found/unique)
+                start_line = self._find_unique_line(lines, start, "start")
+
+            # Resolve end position
+            if isinstance(end, int):
+                if end < start_line:
+                    msg = f"end line {end} must be >= start line {start_line}"
+                    raise ValueError(msg)  # noqa: TRY301
+                end_line = end
+            else:
+                # Find first occurrence of end string after start (raises ValueError if not found)
+                end_line = self._find_first_after(lines, end, start_line, "end")
+
+            # Validate range
+            if end_line > total_lines:
+                msg = f"end_line {end_line} exceeds file length {total_lines}"
+                raise ValueError(msg)  # noqa: TRY301
+
+            # Convert to 0-based indexing for array access
+            start_idx = start_line - 1
+            end_idx = end_line  # end_line is inclusive, but list slice is exclusive
+
+            # Compile regex pattern
+            regex = re.compile(pattern)
+
+            # Apply replacements to the specified line range
+            modified_count = 0
+            replacement_count = 0
+
+            for i in range(start_idx, end_idx):
+                original = lines[i]
+                modified, num_subs = regex.subn(replacement, original, count=count)
+                if num_subs > 0:
+                    lines[i] = modified
+                    modified_count += 1
+                    replacement_count += num_subs
+
+            # Build new content
+            new_content = "".join(lines)
+
+            # Write back
+            await self._write(agent_ctx, path, new_content)
+
+            # Build success message
+            success_msg = (
+                f"Successfully applied regex to lines {start_line}-{end_line} in {Path(path).name}"
+            )
+            if modified_count > 0:
+                success_msg += (
+                    f" ({modified_count} lines modified, {replacement_count} replacements)"
+                )
+
+            # Emit file edit event for diff display
+            await agent_ctx.events.file_edit_progress(
+                path=path,
+                old_text=original_content,
+                new_text=new_content,
+                status="completed",
+            )
+
+            # Run diagnostics if enabled
+            if diagnostics_output := await self._run_diagnostics(agent_ctx, path):
+                success_msg += f"\n\nDiagnostics:\n{diagnostics_output}"
+        except Exception as e:  # noqa: BLE001
+            error_msg = f"Error applying regex to file: {e}"
+            await agent_ctx.events.file_operation("edit", path=path, success=False, error=error_msg)
+            return error_msg
         else:
             return success_msg
 
+    @staticmethod
+    def _find_unique_line(lines: list[str], search_text: str, param_name: str) -> int:
+        """Find unique occurrence of text in lines.
+
+        Args:
+            lines: File lines
+            search_text: Text to search for
+            param_name: Parameter name for error messages
+
+        Returns:
+            Line number (1-based)
+
+        Raises:
+            ValueError: If text not found or matches multiple lines
+        """
+        matches = []
+        for i, line in enumerate(lines, start=1):
+            if search_text in line:
+                matches.append(i)
+
+        if not matches:
+            msg = f"{param_name} text not found: {search_text!r}"
+            raise ValueError(msg)
+        if len(matches) > 1:
+            match_lines = ", ".join(str(m) for m in matches[:5])
+            more = f" and {len(matches) - 5} more" if len(matches) > 5 else ""  # noqa: PLR2004
+            msg = (
+                f"{param_name} text matches multiple lines ({match_lines}{more}). "
+                f"Include more context to make it unique."
+            )
+            raise ValueError(msg)
+
+        return matches[0]
+
+    @staticmethod
+    def _find_first_after(
+        lines: list[str], search_text: str, after_line: int, param_name: str
+    ) -> int:
+        """Find first occurrence of text after a given line.
+
+        Args:
+            lines: File lines
+            search_text: Text to search for
+            after_line: Line number to search after (1-based)
+            param_name: Parameter name for error messages
+
+        Returns:
+            Line number (1-based)
+
+        Raises:
+            ValueError: If text not found after the specified line
+        """
+        for i in range(after_line - 1, len(lines)):
+            if search_text in lines[i]:
+                return i + 1
+
+        msg = f"{param_name} text not found after line {after_line}: {search_text!r}"
+        raise ValueError(msg)
+
     async def grep(  # noqa: D417
         self,
         agent_ctx: AgentContext,
@@ -731,7 +1142,7 @@ class FSSpecTools(ResourceProvider):
 
             # Fallback to fsspec grep if subprocess didn't work
             if result is None or "error" in result:
-                fs = self.get_fs(agent_ctx)
+                fs = self._get_fs(agent_ctx)
                 result = await grep_with_fsspec(
                     fs=fs,
                     pattern=pattern,
@@ -774,12 +1185,12 @@ class FSSpecTools(ResourceProvider):
     async def _read(self, agent_ctx: AgentContext, path: str, encoding: str = "utf-8") -> str:
         # with self.fs.open(path, "r", encoding="utf-8") as f:
         #     return f.read()
-        return await self.get_fs(agent_ctx)._cat(path)  # type: ignore[no-any-return]
+        return await self._get_fs(agent_ctx)._cat(path)  # type: ignore[no-any-return]
 
     async def _write(self, agent_ctx: AgentContext, path: str, content: str | bytes) -> None:
         if isinstance(content, str):
             content = content.encode()
-        await self.get_fs(agent_ctx)._pipe_file(path, content)
+        await self._get_fs(agent_ctx)._pipe_file(path, content)
 
     async def download_file(  # noqa: D417
         self,
@@ -813,7 +1224,7 @@ class FSSpecTools(ResourceProvider):
         full_path = f"{target_dir.rstrip('/')}/{filename}"
 
         try:
-            fs = self.get_fs(agent_ctx)
+            fs = self._get_fs(agent_ctx)
             # Ensure target directory exists
             await fs._makedirs(target_dir, exist_ok=True)
 
@@ -876,7 +1287,7 @@ class FSSpecTools(ResourceProvider):
             await agent_ctx.events.file_operation("read", path=url, success=False, error=error_msg)
             return {"error": error_msg}
 
-    async def agentic_edit(  # noqa: D417, PLR0915
+    async def agentic_edit(  # noqa: D417
         self,
         run_ctx: RunContext,
         agent_ctx: AgentContext,
@@ -906,8 +1317,6 @@ class FSSpecTools(ResourceProvider):
         Returns:
             Success message with edit summary
         """
-        from pydantic_ai.messages import CachePoint, ModelRequest
-
         from agentpool.messaging import ChatMessage, MessageHistory
 
         path = self._resolve_path(path, agent_ctx)
@@ -941,10 +1350,8 @@ class FSSpecTools(ResourceProvider):
             # 1. Stored history (previous runs) from agent.conversation
             # 2. Current run messages from run_ctx.messages (not yet stored)
             stored_history = agent.conversation.get_history()
-
             # Build complete message list
             all_messages: list[ModelRequest | ModelResponse] = []
-
             # Add stored history from previous runs
             for chat_msg in stored_history:
                 all_messages.extend(chat_msg.to_pydantic_ai())
@@ -952,7 +1359,6 @@ class FSSpecTools(ResourceProvider):
             # Add current run's messages (not yet in stored history)
             # But exclude the last message if it contains the current agentic_edit tool call
             # to avoid the sub-agent seeing "I'm calling agentic_edit" in its context
-            from pydantic_ai.messages import ModelResponse, ToolCallPart
 
             for msg in run_ctx.messages:
                 if isinstance(msg, ModelResponse):
@@ -967,17 +1373,16 @@ class FSSpecTools(ResourceProvider):
                 else:
                     all_messages.append(msg)
 
-            # Inject CachePoint to cache everything up to this point
-            if all_messages:
-                cache_request: ModelRequest = ModelRequest(parts=[CachePoint()])  # type: ignore[list-item]
-                all_messages.append(cache_request)
+                # Inject CachePoint to cache everything up to this point
+                # if all_messages:
+                #     cache_request: ModelRequest = ModelRequest(parts=[CachePoint()])
+                #     all_messages.append(cache_request)
 
                 # Wrap in a single ChatMessage for the forked history
                 fork_history = MessageHistory(
                     messages=[ChatMessage(messages=all_messages, role="user", content="")]
                 )
-            else:
-                fork_history = MessageHistory()
+            fork_history = MessageHistory()
 
             # Stream the edit using the same agent but with forked history
             if mode == "edit" and matcher == "zed":