hdsp-jupyter-extension 2.0.7__py3-none-any.whl → 2.0.10__py3-none-any.whl

agent_server/langchain/tools/file_tools.py

@@ -4,24 +4,32 @@ File Tools for LangChain Agent
 Provides tools for file system operations:
 - read_file: Read file content
 - write_file: Write content to file (requires approval)
-- list_files: List directory contents
+- edit_file: Edit file with string replacement (requires approval)
 """
 
 import os
-from typing import Any, Dict, Optional
+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")
-    max_lines: Optional[int] = Field(
-        default=None,
-        description="Maximum number of lines to read",
+    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,
@@ -45,14 +53,15 @@ class WriteFileInput(BaseModel):
     )
 
 
-class ListFilesInput(BaseModel):
-    """Input schema for list_files tool"""
+class EditFileInput(BaseModel):
+    """Input schema for edit_file 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')",
+    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,
@@ -93,19 +102,27 @@ def _validate_path(path: str, workspace_root: str = ".") -> str:
 def read_file_tool(
     path: str,
     encoding: str = "utf-8",
-    max_lines: Optional[int] = None,
+    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
@@ -130,7 +147,8 @@ def read_file_tool(
         "parameters": {
             "path": path,
             "encoding": encoding,
-            "max_lines": max_lines,
+            "offset": offset,
+            "limit": limit,
         },
         "status": "pending_execution",
         "message": "File read queued for execution by client",
@@ -197,45 +215,253 @@ def write_file_tool(
         }
 
 
-@tool(args_schema=ListFilesInput)
-def list_files_tool(
-    path: str = ".",
-    recursive: bool = False,
-    pattern: Optional[str] = None,
+@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]:
     """
-    List files and directories.
+    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: Directory path to list (default: current directory)
-        recursive: Whether to list recursively
-        pattern: Optional glob pattern to filter (e.g., '*.py')
+        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 list of files and directories
+        Dict with operation status and diff preview (pending approval)
     """
-    response: Dict[str, Any] = {
-        "tool": "list_files_tool",
-        "parameters": {
+    # Security validation
+    if os.path.isabs(path):
+        return {
+            "tool": "edit_file_tool",
+            "success": False,
+            "error": f"Absolute paths not allowed: {path}",
             "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
+        }
+    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,
+        }
+
+
+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)"
+    )
+
+
+class MultiEditInput(BaseModel):
+    """Input schema for multiedit_file tool"""
+
+    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": "multiedit_file_tool",
+            "success": False,
+            "error": f"Parent directory traversal not allowed: {path}",
+            "path": path,
+        }
+
+    if not edits or len(edits) == 0:
+        return {
+            "tool": "multiedit_file_tool",
+            "success": False,
+            "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",
+        }
+
+        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": "multiedit_file_tool",
+            "success": False,
+            "error": str(e),
+            "path": path,
+        }
 
 
 # Export all tools
 FILE_TOOLS = [
     read_file_tool,
     write_file_tool,
-    list_files_tool,
+    edit_file_tool,
+    multiedit_file_tool,
 ]