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

agent_server/langchain/tools/file_tools.py

@@ -4,24 +4,33 @@ 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
 """
 
 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,6 +54,22 @@ class WriteFileInput(BaseModel):
     )
 
 
+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"""
 
@@ -93,19 +118,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 +163,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,6 +231,90 @@ def write_file_tool(
         }
 
 
+@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,
+        }
+
+
 @tool(args_schema=ListFilesInput)
 def list_files_tool(
     path: str = ".",
@@ -233,9 +351,169 @@ def list_files_tool(
     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)"
+    )
+
+
+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,
+    edit_file_tool,
+    multiedit_file_tool,
     list_files_tool,
 ]

agent_server/langchain/tools/file_utils.py

@@ -0,0 +1,334 @@
+"""
+File Utilities for LangChain Agent
+
+Provides utility functions for file operations:
+- perform_string_replacement: String replacement with occurrence validation
+- compute_unified_diff: Generate unified diff between before/after content
+- count_diff_changes: Count additions/deletions from diff
+- format_content_with_line_numbers: Format file content with line numbers (cat -n style)
+- check_empty_content: Check if content is empty and return warning message
+"""
+
+import difflib
+from typing import List, Optional, Tuple, Union
+
+# Constants for file reading (aligned with DeepAgents)
+EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents"
+MAX_LINE_LENGTH = 10000  # Chunk lines longer than this
+LINE_NUMBER_WIDTH = 6  # Width for line number padding
+
+
+def check_empty_content(content: str) -> Optional[str]:
+    """
+    Check if content is empty and return warning message.
+
+    Args:
+        content: Content to check
+
+    Returns:
+        Warning message if empty, None otherwise
+    """
+    if not content or content.strip() == "":
+        return EMPTY_CONTENT_WARNING
+    return None
+
+
+def format_content_with_line_numbers(
+    content: Union[str, List[str]],
+    start_line: int = 1,
+) -> str:
+    """
+    Format file content with line numbers (cat -n style).
+
+    Chunks lines longer than MAX_LINE_LENGTH with continuation markers (e.g., 5.1, 5.2).
+
+    Args:
+        content: File content as string or list of lines
+        start_line: Starting line number (default: 1)
+
+    Returns:
+        Formatted content with line numbers and continuation markers
+    """
+    if isinstance(content, str):
+        lines = content.split("\n")
+        # Remove trailing empty line if content ends with newline
+        if lines and lines[-1] == "":
+            lines = lines[:-1]
+    else:
+        lines = content
+
+    result_lines = []
+    for i, line in enumerate(lines):
+        line_num = i + start_line
+
+        if len(line) <= MAX_LINE_LENGTH:
+            result_lines.append(f"{line_num:{LINE_NUMBER_WIDTH}d}\t{line}")
+        else:
+            # Split long line into chunks with continuation markers
+            num_chunks = (len(line) + MAX_LINE_LENGTH - 1) // MAX_LINE_LENGTH
+            for chunk_idx in range(num_chunks):
+                start = chunk_idx * MAX_LINE_LENGTH
+                end = min(start + MAX_LINE_LENGTH, len(line))
+                chunk = line[start:end]
+                if chunk_idx == 0:
+                    # First chunk: use normal line number
+                    result_lines.append(f"{line_num:{LINE_NUMBER_WIDTH}d}\t{chunk}")
+                else:
+                    # Continuation chunks: use decimal notation (e.g., 5.1, 5.2)
+                    continuation_marker = f"{line_num}.{chunk_idx}"
+                    result_lines.append(
+                        f"{continuation_marker:>{LINE_NUMBER_WIDTH}}\t{chunk}"
+                    )
+
+    return "\n".join(result_lines)
+
+
+def format_read_response(
+    content: str,
+    offset: int = 0,
+    limit: int = 500,
+) -> str:
+    """
+    Format file content for read response with line numbers and pagination.
+
+    Args:
+        content: Full file content
+        offset: Line offset (0-indexed)
+        limit: Maximum number of lines to return
+
+    Returns:
+        Formatted content with line numbers, or error/warning message
+    """
+    # Check for empty content
+    empty_msg = check_empty_content(content)
+    if empty_msg:
+        return empty_msg
+
+    lines = content.splitlines()
+    total_lines = len(lines)
+
+    # Validate offset
+    if offset >= total_lines:
+        return f"Error: Line offset {offset} exceeds file length ({total_lines} lines)"
+
+    # Apply pagination
+    start_idx = offset
+    end_idx = min(start_idx + limit, total_lines)
+    selected_lines = lines[start_idx:end_idx]
+
+    # Format with line numbers
+    formatted = format_content_with_line_numbers(
+        selected_lines, start_line=start_idx + 1
+    )
+
+    # Add pagination info if truncated
+    if end_idx < total_lines:
+        remaining = total_lines - end_idx
+        formatted += f"\n\n[... {remaining} more lines. Use offset={end_idx} to continue reading]"
+
+    return formatted
+
+
+def _normalize_whitespace(text: str) -> str:
+    """Normalize line endings and trailing whitespace per line."""
+    lines = text.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    return "\n".join(line.rstrip() for line in lines)
+
+
+def perform_string_replacement(
+    content: str,
+    old_string: str,
+    new_string: str,
+    replace_all: bool = False,
+) -> Union[Tuple[str, int], str]:
+    """
+    Perform string replacement with occurrence validation.
+
+    Includes fallback strategies for more robust matching:
+    1. Exact match
+    2. Strip leading/trailing newlines from old_string
+    3. Normalize whitespace (line endings, trailing spaces)
+
+    Args:
+        content: Original file content
+        old_string: String to replace
+        new_string: Replacement string
+        replace_all: Whether to replace all occurrences
+
+    Returns:
+        Tuple of (new_content, occurrences) on success,
+        or error message string on failure
+    """
+    # Strategy 1: Exact match
+    occurrences = content.count(old_string)
+
+    if occurrences == 0:
+        # Strategy 2: Strip leading/trailing newlines from old_string
+        stripped_old = old_string.strip("\n")
+        occurrences = content.count(stripped_old)
+        if occurrences > 0:
+            old_string = stripped_old
+            # Also strip new_string's leading/trailing newlines to match
+            new_string = new_string.strip("\n")
+
+    if occurrences == 0:
+        # Strategy 3: Normalize whitespace (line endings, trailing spaces)
+        normalized_content = _normalize_whitespace(content)
+        normalized_old = _normalize_whitespace(old_string.strip("\n"))
+        occurrences = normalized_content.count(normalized_old)
+
+        if occurrences > 0:
+            # Find the original text in content that matches normalized version
+            # We need to do replacement on the normalized content first
+            normalized_new = _normalize_whitespace(new_string.strip("\n"))
+            if occurrences > 1 and not replace_all:
+                preview = (
+                    old_string[:50] + "..." if len(old_string) > 50 else old_string
+                )
+                return (
+                    f"Error: String '{preview}' appears {occurrences} times in file. "
+                    "Use replace_all=True to replace all instances, "
+                    "or provide a more specific string with surrounding context."
+                )
+            # Replace on normalized content, then return
+            new_content = normalized_content.replace(normalized_old, normalized_new)
+            return new_content, occurrences
+
+    if occurrences == 0:
+        # All strategies failed
+        preview = old_string[:100] + "..." if len(old_string) > 100 else old_string
+        return f"Error: String not found in file: '{preview}'"
+
+    if occurrences > 1 and not replace_all:
+        preview = old_string[:50] + "..." if len(old_string) > 50 else old_string
+        return (
+            f"Error: String '{preview}' appears {occurrences} times in file. "
+            "Use replace_all=True to replace all instances, "
+            "or provide a more specific string with surrounding context."
+        )
+
+    new_content = content.replace(old_string, new_string)
+    return new_content, occurrences
+
+
+def compute_unified_diff(
+    before: str,
+    after: str,
+    filepath: str,
+    max_lines: int = 100,
+    context_lines: int = 3,
+) -> Union[str, None]:
+    """
+    Compute a unified diff between before and after content.
+
+    Args:
+        before: Original content
+        after: New content
+        filepath: Path for display in diff headers
+        max_lines: Maximum number of diff lines (None for unlimited)
+        context_lines: Number of context lines around changes (default 3)
+
+    Returns:
+        Unified diff string or None if no changes
+    """
+    before_lines = before.splitlines()
+    after_lines = after.splitlines()
+
+    diff_lines = list(
+        difflib.unified_diff(
+            before_lines,
+            after_lines,
+            fromfile=f"{filepath} (before)",
+            tofile=f"{filepath} (after)",
+            lineterm="",
+            n=context_lines,
+        )
+    )
+
+    if not diff_lines:
+        return None
+
+    if max_lines and len(diff_lines) > max_lines:
+        truncated = diff_lines[: max_lines - 1]
+        truncated.append(
+            f"... [{len(diff_lines) - max_lines + 1} more lines truncated]"
+        )
+        return "\n".join(truncated)
+
+    return "\n".join(diff_lines)
+
+
+def count_diff_changes(diff: str) -> Tuple[int, int]:
+    """
+    Count additions and deletions from unified diff.
+
+    Args:
+        diff: Unified diff string
+
+    Returns:
+        Tuple of (additions, deletions) line counts
+    """
+    if not diff:
+        return 0, 0
+
+    additions = sum(
+        1
+        for line in diff.splitlines()
+        if line.startswith("+") and not line.startswith("+++")
+    )
+    deletions = sum(
+        1
+        for line in diff.splitlines()
+        if line.startswith("-") and not line.startswith("---")
+    )
+    return additions, deletions
+
+
+def build_edit_preview(
+    original_content: str,
+    old_string: str,
+    new_string: str,
+    replace_all: bool,
+    filepath: str,
+) -> dict:
+    """
+    Build a preview for edit_file operation including diff.
+
+    Args:
+        original_content: Current file content
+        old_string: String to replace
+        new_string: Replacement string
+        replace_all: Whether to replace all occurrences
+        filepath: File path for display
+
+    Returns:
+        Dict with diff, occurrences, and change counts
+    """
+    result = perform_string_replacement(
+        original_content, old_string, new_string, replace_all
+    )
+
+    if isinstance(result, str):
+        # Error case
+        return {
+            "success": False,
+            "error": result,
+            "diff": None,
+            "occurrences": 0,
+            "lines_added": 0,
+            "lines_removed": 0,
+        }
+
+    new_content, occurrences = result
+    diff = compute_unified_diff(original_content, new_content, filepath)
+    additions, deletions = count_diff_changes(diff) if diff else (0, 0)
+
+    return {
+        "success": True,
+        "error": None,
+        "diff": diff,
+        "occurrences": occurrences,
+        "lines_added": additions,
+        "lines_removed": deletions,
+        "new_content": new_content,
+    }