zrb 1.15.3__py3-none-any.whl → 1.21.29__py3-none-any.whl

zrb/builtin/llm/tool/file.py

@@ -2,28 +2,15 @@ import fnmatch
 import json
 import os
 import re
-import sys
 from typing import Any, Optional
 
 from zrb.builtin.llm.tool.sub_agent import create_sub_agent_tool
 from zrb.config.config import CFG
 from zrb.config.llm_rate_limitter import llm_rate_limitter
 from zrb.context.any_context import AnyContext
+from zrb.task.llm.file_tool_model import FileReplacement, FileToRead, FileToWrite
 from zrb.util.file import read_file, read_file_with_line_numbers, write_file
 
-if sys.version_info >= (3, 12):
-    from typing import TypedDict
-else:
-    from typing_extensions import TypedDict
-
-
-class FileToWrite(TypedDict):
-    """Represents a file to be written, with a 'path' and 'content'."""
-
-    path: str
-    content: str
-
-
 DEFAULT_EXCLUDED_PATTERNS = [
     # Common Python artifacts
     "__pycache__",
@@ -95,36 +82,25 @@ DEFAULT_EXCLUDED_PATTERNS = [
 
 def list_files(
     path: str = ".",
-    recursive: bool = True,
     include_hidden: bool = False,
+    depth: int = 3,
     excluded_patterns: Optional[list[str]] = None,
-) -> str:
+) -> dict[str, list[str]]:
     """
-    Lists the files and directories within a specified path.
+    Lists files recursively up to a specified depth.
 
-    This is a fundamental tool for exploring the file system. Use it to
-    discover the structure of a directory, find specific files, or get a
-    general overview of the project layout before performing other operations.
+    Example:
+    list_files(path='src', include_hidden=False, depth=2)
 
     Args:
-        path (str, optional): The directory path to list. Defaults to the
-            current directory (".").
-        recursive (bool, optional): If True, lists files and directories
-            recursively. If False, lists only the top-level contents.
-            Defaults to True.
-        include_hidden (bool, optional): If True, includes hidden files and
-            directories (those starting with a dot). Defaults to False.
-        excluded_patterns (list[str], optional): A list of glob patterns to
-            exclude from the listing. This is useful for ignoring irrelevant
-            files like build artifacts or virtual environments. Defaults to a
-            standard list of common exclusion patterns.
+        path (str): Directory path. Defaults to current directory.
+        include_hidden (bool): Include hidden files. Defaults to False.
+        depth (int): Maximum depth to traverse. Defaults to 3.
+            Minimum depth is 1 (current directory only).
+        excluded_patterns (list[str]): Glob patterns to exclude.
 
     Returns:
-        str: A JSON string containing a list of file and directory paths
-            relative to the input path.
-            Example: '{"files": ["src/main.py", "README.md"]}'
-    Raises:
-        FileNotFoundError: If the specified path does not exist.
+        dict: {'files': [relative_paths]}
     """
     all_files: list[str] = []
     abs_path = os.path.abspath(os.path.expanduser(path))
@@ -138,50 +114,30 @@ def list_files(
         if excluded_patterns is not None
         else DEFAULT_EXCLUDED_PATTERNS
     )
+    if depth <= 0:
+        depth = 1
     try:
-        if recursive:
-            for root, dirs, files in os.walk(abs_path, topdown=True):
-                # Filter directories in-place
-                dirs[:] = [
-                    d
-                    for d in dirs
-                    if (include_hidden or not _is_hidden(d))
-                    and not is_excluded(d, patterns_to_exclude)
-                ]
-                # Process files
-                for filename in files:
-                    if (include_hidden or not _is_hidden(filename)) and not is_excluded(
-                        filename, patterns_to_exclude
-                    ):
-                        full_path = os.path.join(root, filename)
-                        # Check rel path for patterns like '**/node_modules/*'
-                        rel_full_path = os.path.relpath(full_path, abs_path)
-                        is_rel_path_excluded = is_excluded(
-                            rel_full_path, patterns_to_exclude
-                        )
-                        if not is_rel_path_excluded:
-                            all_files.append(full_path)
-        else:
-            # Non-recursive listing (top-level only)
-            for item in os.listdir(abs_path):
-                full_path = os.path.join(abs_path, item)
-                # Include both files and directories if not recursive
-                if (include_hidden or not _is_hidden(item)) and not is_excluded(
-                    item, patterns_to_exclude
+        initial_depth = abs_path.rstrip(os.sep).count(os.sep)
+        for root, dirs, files in os.walk(abs_path, topdown=True):
+            current_depth = root.rstrip(os.sep).count(os.sep) - initial_depth
+            if current_depth >= depth - 1:
+                del dirs[:]
+            dirs[:] = [
+                d
+                for d in dirs
+                if (include_hidden or not _is_hidden(d))
+                and not is_excluded(d, patterns_to_exclude)
+            ]
+            for filename in files:
+                if (include_hidden or not _is_hidden(filename)) and not is_excluded(
+                    filename, patterns_to_exclude
                 ):
-                    all_files.append(full_path)
-        # Return paths relative to the original path requested
-        try:
-            rel_files = [os.path.relpath(f, abs_path) for f in all_files]
-            return json.dumps({"files": sorted(rel_files)})
-        except (
-            ValueError
-        ) as e:  # Handle case where path is '.' and abs_path is CWD root
-            if "path is on mount '" in str(e) and "' which is not on mount '" in str(e):
-                # If paths are on different mounts, just use absolute paths
-                rel_files = all_files
-                return json.dumps({"files": sorted(rel_files)})
-            raise
+                    full_path = os.path.join(root, filename)
+                    rel_full_path = os.path.relpath(full_path, abs_path)
+                    if not is_excluded(rel_full_path, patterns_to_exclude):
+                        all_files.append(rel_full_path)
+        return {"files": sorted(all_files)}
+
     except (OSError, IOError) as e:
         raise OSError(f"Error listing files in {path}: {e}")
     except Exception as e:
@@ -218,113 +174,146 @@ def is_excluded(name: str, patterns: list[str]) -> bool:
 
 
 def read_from_file(
-    path: str,
-    start_line: Optional[int] = None,
-    end_line: Optional[int] = None,
-) -> str:
+    file: FileToRead | list[FileToRead],
+) -> dict[str, Any]:
     """
-        Reads the content of a file, optionally from a specific start line to an
-        end line.
-
-        This tool is essential for inspecting file contents. It can read both text
-        and PDF files. The returned content is prefixed with line numbers, which is
-        crucial for providing context when you need to modify the file later with
-        the `apply_diff` tool.
-
-        Use this tool to:
-        - Examine the source code of a file.
-        - Read configuration files.
-        - Check the contents of a document.
-
-        Args:
-            path (str): The path to the file to read.
-            start_line (int, optional): The 1-based line number to start reading
-                from. If omitted, reading starts from the beginning of the file.
-            end_line (int, optional): The 1-based line number to stop reading at
-                (inclusive). If omitted, reads to the end of the file.
-
-        Returns:
-            str: A JSON object containing the file path, the requested content
-                with line numbers, the start and end lines, and the total number
-                of lines in the file.
-                Example: '{"path": "src/main.py", "content": "1| import os\n2|
-    3| print(\"Hello, World!\")", "start_line": 1, "end_line": 3,
-                "total_lines": 3}'
-        Raises:
-            FileNotFoundError: If the specified file does not exist.
+    Reads content from one or more files, optionally specifying line ranges.
+
+    Examples:
+    ```
+    # Read entire content of a single file
+    read_from_file(file={'path': 'path/to/file.txt'})
+
+    # Read specific lines from a file
+    # The content will be returned with line numbers in the format: "LINE_NUMBER | line content"
+    read_from_file(file={'path': 'path/to/large_file.log', 'start_line': 100, 'end_line': 150})
+
+    # Read multiple files
+    read_from_file(file=[
+        {'path': 'path/to/file1.txt'},
+        {'path': 'path/to/file2.txt', 'start_line': 1, 'end_line': 5}
+    ])
+    ```
+
+    Args:
+        file (FileToRead | list[FileToRead]): A single file configuration or a list of them.
+
+    Returns:
+        dict: Content and metadata for a single file, or a dict of results for multiple files.
+        The `content` field in the returned dictionary will have line numbers in the format: "LINE_NUMBER | line content"
     """
+    is_list = isinstance(file, list)
+    files = file if is_list else [file]
 
-    abs_path = os.path.abspath(os.path.expanduser(path))
-    # Check if file exists
-    if not os.path.exists(abs_path):
-        raise FileNotFoundError(f"File not found: {path}")
-    try:
-        content = read_file_with_line_numbers(abs_path)
-        lines = content.splitlines()
-        total_lines = len(lines)
-        # Adjust line indices (convert from 1-based to 0-based)
-        start_idx = (start_line - 1) if start_line is not None else 0
-        end_idx = end_line if end_line is not None else total_lines
-        # Validate indices
-        if start_idx < 0:
-            start_idx = 0
-        if end_idx > total_lines:
-            end_idx = total_lines
-        if start_idx > end_idx:
-            start_idx = end_idx
-        # Select the lines for the result
-        selected_lines = lines[start_idx:end_idx]
-        content_result = "\n".join(selected_lines)
-        return json.dumps(
-            {
+    results = {}
+    for file_config in files:
+        path = file_config["path"]
+        start_line = file_config.get("start_line", None)
+        end_line = file_config.get("end_line", None)
+        try:
+            abs_path = os.path.abspath(os.path.expanduser(path))
+            if not os.path.exists(abs_path):
+                raise FileNotFoundError(f"File not found: {path}")
+
+            content = read_file_with_line_numbers(abs_path)
+            lines = content.splitlines()
+            total_lines = len(lines)
+
+            start_idx = (start_line - 1) if start_line is not None else 0
+            end_idx = end_line if end_line is not None else total_lines
+
+            if start_idx < 0:
+                start_idx = 0
+            if end_idx > total_lines:
+                end_idx = total_lines
+            if start_idx > end_idx:
+                start_idx = end_idx
+
+            selected_lines = lines[start_idx:end_idx]
+            content_result = "\n".join(selected_lines)
+
+            results[path] = {
                 "path": path,
                 "content": content_result,
-                "start_line": start_idx + 1,  # Convert back to 1-based for output
-                "end_line": end_idx,  # end_idx is already exclusive upper bound
+                "start_line": start_idx + 1,
+                "end_line": end_idx,
                 "total_lines": total_lines,
             }
-        )
-    except (OSError, IOError) as e:
-        raise OSError(f"Error reading file {path}: {e}")
-    except Exception as e:
-        raise RuntimeError(f"Unexpected error reading file {path}: {e}")
+        except Exception as e:
+            if not is_list:
+                if isinstance(e, (OSError, IOError)):
+                    raise OSError(f"Error reading file {path}: {e}") from e
+                raise RuntimeError(f"Unexpected error reading file {path}: {e}") from e
+            results[path] = f"Error reading file: {e}"
+
+    if is_list:
+        return results
+
+    return results[files[0]["path"]]
 
 
 def write_to_file(
-    path: str,
-    content: str,
-) -> str:
+    file: FileToWrite | list[FileToWrite],
+) -> str | dict[str, Any]:
     """
-    Writes content to a file, completely overwriting it if it exists or
-    creating it if it doesn't.
-
-    Use this tool to create new files or to replace the entire content of
-    existing files. This is a destructive operation, so be certain of your
-    actions. Always read the file first to understand its contents before
-    overwriting it, unless you are creating a new file.
+    Writes content to one or more files, with options for overwrite, append, or exclusive
+    creation.
+
+    **CRITICAL - PREVENT JSON ERRORS:**
+    1. **ESCAPING:** Do NOT double-escape quotes.
+       - CORRECT: "content": "He said \"Hello\""
+       - WRONG:   "content": "He said \\"Hello\\""  <-- This breaks JSON parsing!
+    2. **SIZE LIMIT:** Content MUST NOT exceed 4000 characters.
+       - Exceeding this causes truncation and EOF errors.
+       - Split larger content into multiple sequential calls (first 'w', then 'a').
+
+    Examples:
+    ```
+    # Overwrite 'file.txt' with initial content
+    write_to_file(file={'path': 'path/to/file.txt', 'content': 'Initial content.'})
+
+    # Append a second chunk to 'file.txt' (note the newline at the beginning of the content)
+    write_to_file(file={'path': 'path/to/file.txt', 'content': '\nSecond chunk.', 'mode': 'a'})
+
+    # Write to multiple files
+    write_to_file(file=[
+        {'path': 'path/to/file1.txt', 'content': 'Content for file 1'},
+        {'path': 'path/to/file2.txt', 'content': 'Content for file 2', 'mode': 'w'}
+    ])
+    ```
 
     Args:
-        path (str): The path to the file to write to.
-        content (str): The full, complete content to be written to the file.
-            Do not use partial content or omit any lines.
+        file (FileToWrite | list[FileToWrite]): A single file configuration or a list of them.
 
     Returns:
-        str: A JSON object indicating success or failure.
-             Example: '{"success": true, "path": "new_file.txt"}'
+        Success message for single file, or dict with success/errors for multiple files.
     """
-    try:
-        abs_path = os.path.abspath(os.path.expanduser(path))
-        # Ensure directory exists
-        directory = os.path.dirname(abs_path)
-        if directory and not os.path.exists(directory):
-            os.makedirs(directory, exist_ok=True)
-        write_file(abs_path, content)
-        result_data = {"success": True, "path": path}
-        return json.dumps(result_data)
-    except (OSError, IOError) as e:
-        raise OSError(f"Error writing file {path}: {e}")
-    except Exception as e:
-        raise RuntimeError(f"Unexpected error writing file {path}: {e}")
+    # Normalize to list
+    files = file if isinstance(file, list) else [file]
+
+    success = []
+    errors = {}
+    for file_config in files:
+        path = file_config["path"]
+        content = file_config["content"]
+        mode = file_config.get("mode", "w")
+        try:
+            abs_path = os.path.abspath(os.path.expanduser(path))
+            # The underlying utility creates the directory, so we don't need to do it here.
+            write_file(abs_path, content, mode=mode)
+            success.append(path)
+        except Exception as e:
+            errors[path] = f"Error writing file: {e}"
+
+    # Return appropriate response based on input type
+    if isinstance(file, list):
+        return {"success": success, "errors": errors}
+    else:
+        if errors:
+            raise RuntimeError(
+                f"Error writing file {file['path']}: {errors[file['path']]}"
+            )
+        return f"Successfully wrote to file: {file['path']} in mode '{file.get('mode', 'w')}'"
 
 
 def search_files(
@@ -332,32 +321,21 @@ def search_files(
     regex: str,
     file_pattern: Optional[str] = None,
     include_hidden: bool = True,
-) -> str:
+) -> dict[str, Any]:
     """
-    Searches for a regular expression (regex) pattern within files in a
-    specified directory.
+    Searches for a regex pattern in files within a directory.
 
-    This tool is invaluable for finding specific code, configuration, or text
-    across multiple files. Use it to locate function definitions, variable
-    assignments, error messages, or any other text pattern.
+    Example:
+    search_files(path='src', regex='class \\w+', file_pattern='*.py', include_hidden=False)
 
     Args:
-        path (str): The directory path to start the search from.
-        regex (str): The Python-compatible regular expression pattern to search
-            for.
-        file_pattern (str, optional): A glob pattern to filter which files get
-            searched (e.g., "*.py", "*.md"). If omitted, all files are
-            searched.
-        include_hidden (bool, optional): If True, the search will include
-            hidden files and directories. Defaults to True.
+        path (str): Directory to search.
+        regex (str): Regex pattern.
+        file_pattern (str): Glob pattern filter.
+        include_hidden (bool): Include hidden files.
 
     Returns:
-        str: A JSON object containing a summary of the search and a list of
-            results. Each result includes the file path and a list of matches,
-            with each match showing the line number, line content, and a few
-            lines of context from before and after the match.
-    Raises:
-        ValueError: If the provided `regex` pattern is invalid.
+        dict: Summary and list of matches.
     """
     try:
         pattern = re.compile(regex)
@@ -404,9 +382,7 @@ def search_files(
                 f"Found {match_count} matches in {file_match_count} files "
                 f"(searched {searched_file_count} files)."
             )
-        return json.dumps(
-            search_results
-        )  # No need for pretty printing for LLM consumption
+        return search_results
     except (OSError, IOError) as e:
         raise OSError(f"Error searching files in {path}: {e}")
     except Exception as e:
@@ -414,7 +390,9 @@ def search_files(
 
 
 def _get_file_matches(
-    file_path: str, pattern: re.Pattern, context_lines: int = 2
+    file_path: str,
+    pattern: re.Pattern,
+    context_lines: int = 2,
 ) -> list[dict[str, Any]]:
     """Search for regex matches in a file with context."""
     try:
@@ -445,182 +423,138 @@ def _get_file_matches(
 
 
 def replace_in_file(
-    path: str,
-    old_string: str,
-    new_string: str,
-) -> str:
+    file: FileReplacement | list[FileReplacement],
+) -> str | dict[str, Any]:
     """
-    Replaces the first occurrence of a string in a file.
-
-    This tool is for making targeted modifications to a file. It is a
-    single-step operation that is generally safer and more ergonomic than
-    `write_to_file` for small changes.
+    Replaces exact text in files.
+
+    **CRITICAL INSTRUCTIONS:**
+    1. **READ FIRST:** Use `read_file` to get exact content. Do not guess.
+    2. **EXACT MATCH:** `old_text` must match file content EXACTLY (whitespace, newlines).
+    3. **ESCAPING:** Do NOT double-escape quotes in `new_text`. Use `\"`, not `\\"`.
+    4. **SIZE LIMIT:** `new_text` MUST NOT exceed 4000 chars to avoid truncation/EOF errors.
+    5. **MINIMAL CONTEXT:** Keep `old_text` small (target lines + 2-3 context lines).
+    6. **DEFAULT:** Replaces **ALL** occurrences. Set `count=1` for first occurrence only.
+
+    Examples:
+    ```
+    # Replace ALL occurrences
+    replace_in_file(file=[
+        {'path': 'file.txt', 'old_text': 'foo', 'new_text': 'bar'},
+        {'path': 'file.txt', 'old_text': 'baz', 'new_text': 'qux'}
+    ])
+
+    # Replace ONLY the first occurrence
+    replace_in_file(
+        file={'path': 'file.txt', 'old_text': 'foo', 'new_text': 'bar', 'count': 1}
+    )
 
-    To ensure the replacement is applied correctly and to avoid ambiguity, the
-    `old_string` parameter should be a unique, multi-line string that includes
-    context from before and after the code you want to change.
+    # Replace code block (include context for safety)
+    replace_in_file(
+        file={
+            'path': 'app.py',
+            'old_text': '    def old_fn():\n        pass',
+            'new_text': '    def new_fn():\n        pass'
+        }
+    )
+    ```
 
     Args:
-        path (str): The path of the file to modify.
-        old_string (str): The exact, verbatim string to search for and replace.
-            This should be a unique, multi-line block of text.
-        new_string (str): The new string that will replace the `old_string`.
+        file: Single replacement config or list of them.
 
     Returns:
-        str: A JSON object indicating the success or failure of the operation.
-    Raises:
-        FileNotFoundError: If the specified file does not exist.
-        ValueError: If the `old_string` is not found in the file.
+        Success message or error dict.
     """
-    abs_path = os.path.abspath(os.path.expanduser(path))
-    if not os.path.exists(abs_path):
-        raise FileNotFoundError(f"File not found: {path}")
-    try:
-        content = read_file(abs_path)
-        if old_string not in content:
-            raise ValueError(f"old_string not found in file: {path}")
-        new_content = content.replace(old_string, new_string, 1)
-        write_file(abs_path, new_content)
-        return json.dumps({"success": True, "path": path})
-    except ValueError as e:
-        raise e
-    except (OSError, IOError) as e:
-        raise OSError(f"Error applying replacement to {path}: {e}")
-    except Exception as e:
-        raise RuntimeError(f"Unexpected error applying replacement to {path}: {e}")
+    # Normalize to list
+    file_replacements = file if isinstance(file, list) else [file]
+    # Group replacements by file path to minimize file I/O
+    replacements_by_path: dict[str, list[FileReplacement]] = {}
+    for r in file_replacements:
+        path = r["path"]
+        if path not in replacements_by_path:
+            replacements_by_path[path] = []
+        replacements_by_path[path].append(r)
+    success = []
+    errors = {}
+    for path, replacements in replacements_by_path.items():
+        try:
+            abs_path = os.path.abspath(os.path.expanduser(path))
+            if not os.path.exists(abs_path):
+                raise FileNotFoundError(f"File not found: {path}")
+            content = read_file(abs_path)
+            original_content = content
+            # Apply all replacements for this file
+            for replacement in replacements:
+                old_text = replacement["old_text"]
+                new_text = replacement["new_text"]
+                count = replacement.get("count", -1)
+                if old_text not in content:
+                    raise ValueError(f"old_text not found in file: {path}")
+                # Replace occurrences
+                content = content.replace(old_text, new_text, count)
+            # Only write if content actually changed
+            if content != original_content:
+                write_file(abs_path, content)
+                success.append(path)
+            else:
+                success.append(f"{path} (no changes needed)")
+        except Exception as e:
+            errors[path] = f"Error applying replacement to {path}: {e}"
+    # Return appropriate response based on input type
+    if isinstance(file, list):
+        return {"success": success, "errors": errors}
+    path = file["path"]
+    if errors:
+        error_message = errors[path]
+        raise RuntimeError(f"Error applying replacement to {path}: {error_message}")
+    return f"Successfully applied replacement(s) to {path}"
 
 
 async def analyze_file(
-    ctx: AnyContext, path: str, query: str, token_limit: int | None = None
-) -> str:
+    ctx: AnyContext, path: str, query: str, token_threshold: int | None = None
+) -> dict[str, Any]:
     """
-    Performs a deep, goal-oriented analysis of a single file using a sub-agent.
-
-    This tool is ideal for complex questions about a single file that go beyond
-    simple reading or searching. It uses a specialized sub-agent to analyze the
-    file's content in relation to a specific query.
+    Analyzes a file using a sub-agent for complex questions.
 
-    To ensure a focused and effective analysis, it is crucial to provide a
-    clear and specific query. Vague queries will result in a vague analysis
-    and may cause the tool to run for a long time.
-
-    Use this tool to:
-    - Summarize the purpose and functionality of a script or configuration file.
-    - Extract the structure of a file (e.g., "List all the function names in
-      this Python file").
-    - Perform a detailed code review of a specific file.
-    - Answer complex questions like, "How is the 'User' class used in this
-      file?".
+    Example:
+    analyze_file(path='src/main.py', query='Summarize the main function.')
 
     Args:
-        path (str): The path to the file to be analyzed.
-        query (str): A clear and specific question or instruction about what to
-            analyze in the file.
-            - Good query: "What is the purpose of the 'User' class in this
-              file?"
-            - Good query: "List all the function names in this Python file."
-            - Bad query: "Analyze this file."
-            - Bad query: "Tell me about this code."
-        token_limit (int, optional): The maximum token length of the file
-            content to be passed to the analysis sub-agent.
+        ctx (AnyContext): The execution context.
+        path (str): The path to the file to analyze.
+        query (str): A specific analysis query with clear guidelines and
+            necessary information.
+        token_threshold (int | None): Max tokens.
 
     Returns:
-        str: A detailed, markdown-formatted analysis of the file, tailored to
-            the specified query.
-    Raises:
-        FileNotFoundError: If the specified file does not exist.
+        Analysis results.
     """
-    if token_limit is None:
-        token_limit = CFG.LLM_FILE_ANALYSIS_TOKEN_LIMIT
+    if token_threshold is None:
+        token_threshold = CFG.LLM_FILE_ANALYSIS_TOKEN_THRESHOLD
     abs_path = os.path.abspath(os.path.expanduser(path))
     if not os.path.exists(abs_path):
         raise FileNotFoundError(f"File not found: {path}")
     file_content = read_file(abs_path)
     _analyze_file = create_sub_agent_tool(
         tool_name="analyze_file",
-        tool_description="analyze file with LLM capability",
+        tool_description=(
+            "Analyze file content using LLM sub-agent "
+            "for complex questions about code structure, documentation "
+            "quality, or file-specific analysis. Use for questions that "
+            "require understanding beyond simple text reading."
+        ),
         system_prompt=CFG.LLM_FILE_EXTRACTOR_SYSTEM_PROMPT,
         tools=[read_from_file, search_files],
+        auto_summarize=False,
+        remember_history=False,
     )
     payload = json.dumps(
-        {"instruction": query, "file_path": abs_path, "file_content": file_content}
+        {
+            "instruction": query,
+            "file_path": abs_path,
+            "file_content": llm_rate_limitter.clip_prompt(
+                file_content, token_threshold
+            ),
+        }
     )
-    clipped_payload = llm_rate_limitter.clip_prompt(payload, token_limit)
-    return await _analyze_file(ctx, clipped_payload)
-
-
-def read_many_files(paths: list[str]) -> str:
-    """
-    Reads and returns the full content of multiple files at once.
-
-    This tool is highly efficient for gathering context from several files
-    simultaneously. Use it when you need to understand how different files in a
-    project relate to each other, or when you need to inspect a set of related
-    configuration or source code files.
-
-    Args:
-        paths (list[str]): A list of paths to the files you want to read. It is
-            crucial to provide accurate paths. Use the `list_files` tool first
-            if you are unsure about the exact file locations.
-
-    Returns:
-        str: A JSON object where keys are the file paths and values are their
-            corresponding contents, prefixed with line numbers. If a file
-            cannot be read, its value will be an error message.
-            Example: '{"results": {"src/api.py": "1| import ...",
-            "config.yaml": "1| key: value"}}'
-    """
-    results = {}
-    for path in paths:
-        try:
-            abs_path = os.path.abspath(os.path.expanduser(path))
-            if not os.path.exists(abs_path):
-                raise FileNotFoundError(f"File not found: {path}")
-            content = read_file_with_line_numbers(abs_path)
-            results[path] = content
-        except Exception as e:
-            results[path] = f"Error reading file: {e}"
-    return json.dumps({"results": results})
-
-
-def write_many_files(files: list[FileToWrite]) -> str:
-    """
-    Writes content to multiple files in a single, atomic operation.
-
-    This tool is for applying widespread changes to a project, such as
-    creating a set of new files from a template, updating multiple
-    configuration files, or performing a large-scale refactoring.
-
-    Each file's content is completely replaced. If a file does not exist, it
-    will be created. If it exists, its current content will be entirely
-    overwritten. Therefore, you must provide the full, intended content for
-    each file.
-
-    Args:
-        files: A list of file objects, where each object is a dictionary
-            containing a 'path' and the complete 'content'.
-
-    Returns:
-        str: A JSON object summarizing the operation, listing successfully
-            written files and any files that failed, along with corresponding
-            error messages.
-            Example: '{"success": ["file1.py", "file2.txt"], "errors": {}}'
-    """
-    success = []
-    errors = {}
-    # 4. Access the data using dictionary key-lookup syntax.
-    for file in files:
-        try:
-            # Use file['path'] and file['content'] instead of file.path
-            path = file["path"]
-            content = file["content"]
-
-            abs_path = os.path.abspath(os.path.expanduser(path))
-            directory = os.path.dirname(abs_path)
-            if directory and not os.path.exists(directory):
-                os.makedirs(directory, exist_ok=True)
-            write_file(abs_path, content)
-            success.append(path)
-        except Exception as e:
-            errors[path] = f"Error writing file: {e}"
-    return json.dumps({"success": success, "errors": errors})
+    return await _analyze_file(ctx, payload)