hdsp-jupyter-extension 2.0.6__py3-none-any.whl → 2.0.8__py3-none-any.whl

agent_server/langchain/tools/file_tools.py

@@ -4,6 +4,7 @@ File Tools for LangChain Agent
 Provides tools for file system operations:
 - read_file: Read file content
 - write_file: Write content to file (requires approval)
+- edit_file: Edit file with string replacement (requires approval)
 - list_files: List directory contents
 """
 
@@ -13,34 +14,81 @@ from typing import Any, Dict, List, Optional
 from langchain_core.tools import tool
 from pydantic import BaseModel, Field
 
+# Default constants for file reading (aligned with DeepAgents best practices)
+DEFAULT_READ_LIMIT = 500  # Conservative default to prevent context overflow
+DEFAULT_READ_OFFSET = 0
+
 
 class ReadFileInput(BaseModel):
     """Input schema for read_file tool"""
+
     path: str = Field(description="Relative path to the file to read")
     encoding: str = Field(default="utf-8", description="File encoding")
+    offset: int = Field(
+        default=DEFAULT_READ_OFFSET,
+        description="Line offset to start reading from (0-indexed). Use for pagination.",
+    )
+    limit: int = Field(
+        default=DEFAULT_READ_LIMIT,
+        description="Maximum number of lines to read (default: 500). Use pagination for large files.",
+    )
+    execution_result: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Optional execution result payload from the client",
+    )
 
 
 class WriteFileInput(BaseModel):
     """Input schema for write_file tool"""
+
     path: str = Field(description="Relative path to the file to write")
     content: str = Field(description="Content to write to the file")
     encoding: str = Field(default="utf-8", description="File encoding")
+    overwrite: bool = Field(
+        default=False,
+        description="Whether to overwrite an existing file (default: false)",
+    )
+    execution_result: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Optional execution result payload from the client",
+    )
+
+
+class EditFileInput(BaseModel):
+    """Input schema for edit_file tool"""
+
+    path: str = Field(description="Relative path to the file to edit")
+    old_string: str = Field(description="The exact string to find and replace")
+    new_string: str = Field(description="The replacement string")
+    replace_all: bool = Field(
+        default=False,
+        description="Whether to replace all occurrences (default: false, requires unique match)",
+    )
+    execution_result: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Optional execution result payload from the client",
+    )
 
 
 class ListFilesInput(BaseModel):
     """Input schema for list_files tool"""
+
     path: str = Field(default=".", description="Directory path to list")
     recursive: bool = Field(default=False, description="Whether to list recursively")
     pattern: Optional[str] = Field(
         default=None,
-        description="Glob pattern to filter files (e.g., '*.py', '*.ipynb')"
+        description="Glob pattern to filter files (e.g., '*.py', '*.ipynb')",
+    )
+    execution_result: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Optional execution result payload from the client",
     )
 
 
 def _validate_path(path: str, workspace_root: str = ".") -> str:
     """
     Validate and resolve file path.
-    
+
     Security checks:
     - No absolute paths allowed
     - No parent directory traversal (..)
@@ -70,93 +118,97 @@ def _validate_path(path: str, workspace_root: str = ".") -> str:
 def read_file_tool(
     path: str,
     encoding: str = "utf-8",
-    workspace_root: str = "."
+    offset: int = DEFAULT_READ_OFFSET,
+    limit: int = DEFAULT_READ_LIMIT,
+    execution_result: Optional[Dict[str, Any]] = None,
+    workspace_root: str = ".",
 ) -> Dict[str, Any]:
     """
-    Read content from a file.
-    
+    Read content from a file with pagination support.
+
     Only relative paths within the workspace are allowed.
     Absolute paths and parent directory traversal (..) are blocked.
-    
+
+    **IMPORTANT for large files**: Use pagination with offset and limit to avoid context overflow.
+    - First scan: read_file(path, limit=100) to see file structure
+    - Read more: read_file(path, offset=100, limit=200) for next 200 lines
+    - Only omit limit when necessary for immediate editing
+
     Args:
         path: Relative path to the file
         encoding: File encoding (default: utf-8)
-        
+        offset: Line offset to start reading from (0-indexed)
+        limit: Maximum number of lines to read (default: 500)
+
     Returns:
         Dict with file content or error
     """
-    try:
-        resolved_path = _validate_path(path, workspace_root)
-
-        if not os.path.exists(resolved_path):
-            return {
-                "tool": "read_file",
-                "success": False,
-                "error": f"File not found: {path}",
-                "path": path,
-            }
-
-        if not os.path.isfile(resolved_path):
-            return {
-                "tool": "read_file",
-                "success": False,
-                "error": f"Not a file: {path}",
-                "path": path,
-            }
-
-        with open(resolved_path, "r", encoding=encoding) as f:
-            content = f.read()
-
-        return {
-            "tool": "read_file",
-            "success": True,
-            "path": path,
-            "content": content,
-            "size": len(content),
-        }
-
-    except ValueError as e:
+    if os.path.isabs(path):
         return {
-            "tool": "read_file",
+            "tool": "read_file_tool",
             "success": False,
-            "error": str(e),
+            "error": f"Absolute paths not allowed: {path}",
             "path": path,
         }
-    except Exception as e:
+    if ".." in path:
         return {
-            "tool": "read_file",
+            "tool": "read_file_tool",
             "success": False,
-            "error": f"Failed to read file: {str(e)}",
+            "error": f"Parent directory traversal not allowed: {path}",
             "path": path,
         }
 
+    response: Dict[str, Any] = {
+        "tool": "read_file_tool",
+        "parameters": {
+            "path": path,
+            "encoding": encoding,
+            "offset": offset,
+            "limit": limit,
+        },
+        "status": "pending_execution",
+        "message": "File read queued for execution by client",
+    }
+    if execution_result is not None:
+        response["execution_result"] = execution_result
+        response["status"] = "complete"
+        response["message"] = "File read executed with client-reported results"
+    return response
+
 
 @tool(args_schema=WriteFileInput)
 def write_file_tool(
     path: str,
     content: str,
     encoding: str = "utf-8",
-    workspace_root: str = "."
+    overwrite: bool = False,
+    execution_result: Optional[Dict[str, Any]] = None,
+    workspace_root: str = ".",
 ) -> Dict[str, Any]:
     """
     Write content to a file.
-    
+
     This operation requires user approval before execution.
     Only relative paths within the workspace are allowed.
-    
+
     Args:
         path: Relative path to the file
         content: Content to write
         encoding: File encoding (default: utf-8)
-        
+
     Returns:
         Dict with operation status (pending approval)
     """
     try:
         resolved_path = _validate_path(path, workspace_root)
 
-        return {
-            "tool": "write_file",
+        response: Dict[str, Any] = {
+            "tool": "write_file_tool",
+            "parameters": {
+                "path": path,
+                "encoding": encoding,
+                "overwrite": overwrite,
+            },
             "status": "pending_approval",
             "path": path,
             "resolved_path": resolved_path,
@@ -164,10 +216,99 @@ def write_file_tool(
             "content_length": len(content),
             "message": "File write operation requires user approval",
         }
+        if execution_result is not None:
+            response["execution_result"] = execution_result
+            response["status"] = "complete"
+            response["message"] = "File write executed with client-reported results"
+        return response
 
     except ValueError as e:
         return {
-            "tool": "write_file",
+            "tool": "write_file_tool",
+            "success": False,
+            "error": str(e),
+            "path": path,
+        }
+
+
+@tool(args_schema=EditFileInput)
+def edit_file_tool(
+    path: str,
+    old_string: str,
+    new_string: str,
+    replace_all: bool = False,
+    execution_result: Optional[Dict[str, Any]] = None,
+    workspace_root: str = ".",
+) -> Dict[str, Any]:
+    """
+    Edit a file by replacing a specific string with another.
+
+    This operation requires user approval before execution.
+    The old_string must be unique in the file unless replace_all=True.
+
+    Args:
+        path: Relative path to the file
+        old_string: The exact string to find and replace
+        new_string: The replacement string
+        replace_all: Whether to replace all occurrences
+
+    Returns:
+        Dict with operation status and diff preview (pending approval)
+    """
+    # Security validation
+    if os.path.isabs(path):
+        return {
+            "tool": "edit_file_tool",
+            "success": False,
+            "error": f"Absolute paths not allowed: {path}",
+            "path": path,
+        }
+    if ".." in path:
+        return {
+            "tool": "edit_file_tool",
+            "success": False,
+            "error": f"Parent directory traversal not allowed: {path}",
+            "path": path,
+        }
+
+    try:
+        resolved_path = _validate_path(path, workspace_root)
+
+        # Build response with diff preview
+        # Note: actual file content will be read by client for diff generation
+        old_preview = old_string[:200] + "..." if len(old_string) > 200 else old_string
+        new_preview = new_string[:200] + "..." if len(new_string) > 200 else new_string
+
+        response: Dict[str, Any] = {
+            "tool": "edit_file_tool",
+            "parameters": {
+                "path": path,
+                "old_string": old_string,
+                "new_string": new_string,
+                "replace_all": replace_all,
+            },
+            "status": "pending_approval",
+            "path": path,
+            "resolved_path": resolved_path,
+            "old_string_preview": old_preview,
+            "new_string_preview": new_preview,
+            "replace_all": replace_all,
+            "message": "File edit operation requires user approval",
+        }
+
+        if execution_result is not None:
+            response["execution_result"] = execution_result
+            response["status"] = "complete"
+            response["message"] = "File edit executed with client-reported results"
+            # Include diff if provided by client
+            if "diff" in execution_result:
+                response["diff"] = execution_result["diff"]
+
+        return response
+
+    except ValueError as e:
+        return {
+            "tool": "edit_file_tool",
             "success": False,
             "error": str(e),
             "path": path,
@@ -179,94 +320,191 @@ def list_files_tool(
     path: str = ".",
     recursive: bool = False,
     pattern: Optional[str] = None,
-    workspace_root: str = "."
+    execution_result: Optional[Dict[str, Any]] = None,
+    workspace_root: str = ".",
 ) -> Dict[str, Any]:
     """
     List files and directories.
-    
+
     Args:
         path: Directory path to list (default: current directory)
         recursive: Whether to list recursively
         pattern: Optional glob pattern to filter (e.g., '*.py')
-        
+
     Returns:
         Dict with list of files and directories
     """
-    import fnmatch
+    response: Dict[str, Any] = {
+        "tool": "list_files_tool",
+        "parameters": {
+            "path": path,
+            "recursive": recursive,
+            "pattern": pattern,
+        },
+        "status": "pending_execution",
+        "message": "File listing queued for execution by client",
+    }
+    if execution_result is not None:
+        response["execution_result"] = execution_result
+        response["status"] = "complete"
+        response["message"] = "File listing executed with client-reported results"
+    return response
+
+
+class EditOperation(BaseModel):
+    """Single edit operation for multiedit_file tool"""
+
+    old_string: str = Field(description="The exact string to find and replace")
+    new_string: str = Field(description="The replacement string")
+    replace_all: bool = Field(
+        default=False,
+        description="Whether to replace all occurrences (default: false)"
+    )
 
-    try:
-        resolved_path = _validate_path(path, workspace_root)
 
-        if not os.path.exists(resolved_path):
-            return {
-                "tool": "list_files",
-                "success": False,
-                "error": f"Directory not found: {path}",
-                "path": path,
-            }
+class MultiEditInput(BaseModel):
+    """Input schema for multiedit_file tool"""
 
-        if not os.path.isdir(resolved_path):
-            return {
-                "tool": "list_files",
-                "success": False,
-                "error": f"Not a directory: {path}",
-                "path": path,
-            }
-
-        files: List[Dict[str, Any]] = []
-        dirs: List[str] = []
-
-        if recursive:
-            for root, dirnames, filenames in os.walk(resolved_path):
-                rel_root = os.path.relpath(root, resolved_path)
-                for dirname in dirnames:
-                    dir_path = os.path.join(rel_root, dirname) if rel_root != "." else dirname
-                    dirs.append(dir_path)
-                for filename in filenames:
-                    if pattern and not fnmatch.fnmatch(filename, pattern):
-                        continue
-                    file_path = os.path.join(rel_root, filename) if rel_root != "." else filename
-                    full_path = os.path.join(root, filename)
-                    files.append({
-                        "name": filename,
-                        "path": file_path,
-                        "size": os.path.getsize(full_path),
-                    })
-        else:
-            for entry in os.scandir(resolved_path):
-                if entry.is_dir():
-                    dirs.append(entry.name)
-                elif entry.is_file():
-                    if pattern and not fnmatch.fnmatch(entry.name, pattern):
-                        continue
-                    files.append({
-                        "name": entry.name,
-                        "path": entry.name,
-                        "size": entry.stat().st_size,
-                    })
+    path: str = Field(description="Relative path to the file to edit")
+    edits: List[EditOperation] = Field(
+        description="List of edit operations to apply sequentially"
+    )
+    execution_result: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Optional execution result payload from the client",
+    )
 
+
+@tool(args_schema=MultiEditInput)
+def multiedit_file_tool(
+    path: str,
+    edits: List[EditOperation],
+    execution_result: Optional[Dict[str, Any]] = None,
+    workspace_root: str = ".",
+) -> Dict[str, Any]:
+    """
+    Apply multiple sequential edits to a single file atomically.
+
+    This is more efficient than multiple edit_file_tool calls when you need
+    to make several changes to the same file. All edits are validated before
+    any are applied - if one fails, none are applied.
+
+    Use this tool when:
+    - Making multiple related changes to a file
+    - Updating several config values at once
+    - Refactoring multiple sections of code
+
+    Args:
+        path: Relative path to the file
+        edits: List of edit operations, each containing:
+            - old_string: The exact string to find and replace
+            - new_string: The replacement string
+            - replace_all: (optional) Whether to replace all occurrences
+
+    Returns:
+        Dict with operation status, edits_applied count, and diff preview
+
+    Example:
+        multiedit_file_tool(
+            path="config.py",
+            edits=[
+                {"old_string": "DEBUG = True", "new_string": "DEBUG = False"},
+                {"old_string": "LOG_LEVEL = 'INFO'", "new_string": "LOG_LEVEL = 'WARNING'"}
+            ]
+        )
+    """
+    # Security validation
+    if os.path.isabs(path):
+        return {
+            "tool": "multiedit_file_tool",
+            "success": False,
+            "error": f"Absolute paths not allowed: {path}",
+            "path": path,
+        }
+    if ".." in path:
         return {
-            "tool": "list_files",
-            "success": True,
+            "tool": "multiedit_file_tool",
+            "success": False,
+            "error": f"Parent directory traversal not allowed: {path}",
             "path": path,
-            "directories": sorted(dirs),
-            "files": sorted(files, key=lambda x: x["name"]),
-            "total_dirs": len(dirs),
-            "total_files": len(files),
         }
 
-    except ValueError as e:
+    if not edits or len(edits) == 0:
         return {
-            "tool": "list_files",
+            "tool": "multiedit_file_tool",
             "success": False,
-            "error": str(e),
+            "error": "At least one edit is required",
+            "path": path,
+        }
+
+    try:
+        resolved_path = _validate_path(path, workspace_root)
+
+        # Build edits preview (handle both EditOperation objects and dicts)
+        edits_preview = []
+        edits_as_dicts = []
+        for i, edit in enumerate(edits[:5]):  # Preview first 5
+            # Support both Pydantic model and dict access
+            if hasattr(edit, "old_string"):
+                old_str = edit.old_string
+                new_str = edit.new_string
+                replace_all_val = edit.replace_all
+            else:
+                old_str = edit.get("old_string", "")
+                new_str = edit.get("new_string", "")
+                replace_all_val = edit.get("replace_all", False)
+
+            old_preview = (old_str[:50] + "...") if len(old_str) > 50 else old_str
+            new_preview = (new_str[:50] + "...") if len(new_str) > 50 else new_str
+            edits_preview.append({
+                "index": i,
+                "old_preview": old_preview,
+                "new_preview": new_preview,
+                "replace_all": replace_all_val
+            })
+
+        # Convert all edits to dicts for serialization
+        for edit in edits:
+            if hasattr(edit, "model_dump"):
+                edits_as_dicts.append(edit.model_dump())
+            elif hasattr(edit, "dict"):
+                edits_as_dicts.append(edit.dict())
+            else:
+                edits_as_dicts.append(edit)
+
+        response: Dict[str, Any] = {
+            "tool": "multiedit_file_tool",
+            "parameters": {
+                "path": path,
+                "edits_count": len(edits),
+                "edits": edits_as_dicts,
+            },
+            "status": "pending_approval",
             "path": path,
+            "resolved_path": resolved_path,
+            "edits_preview": edits_preview,
+            "total_edits": len(edits),
+            "message": f"Multi-edit operation ({len(edits)} edits) requires user approval",
         }
-    except Exception as e:
+
+        if execution_result is not None:
+            response["execution_result"] = execution_result
+            response["status"] = "complete"
+            response["message"] = "Multi-edit executed with client-reported results"
+            if "diff" in execution_result:
+                response["diff"] = execution_result["diff"]
+            if "edits_applied" in execution_result:
+                response["edits_applied"] = execution_result["edits_applied"]
+            if "edits_failed" in execution_result:
+                response["edits_failed"] = execution_result["edits_failed"]
+
+        return response
+
+    except ValueError as e:
         return {
-            "tool": "list_files",
+            "tool": "multiedit_file_tool",
             "success": False,
-            "error": f"Failed to list directory: {str(e)}",
+            "error": str(e),
             "path": path,
         }
 
@@ -275,5 +513,7 @@ def list_files_tool(
 FILE_TOOLS = [
     read_file_tool,
     write_file_tool,
+    edit_file_tool,
+    multiedit_file_tool,
     list_files_tool,
 ]