code-puppy 0.0.124__py3-none-any.whl → 0.0.126__py3-none-any.whl

code_puppy/tools/command_runner.py

@@ -590,3 +590,100 @@ def register_command_runner_tools(agent):
             - When encountering unexpected situations
         """
         return share_your_reasoning(context, reasoning, next_steps)
+
+
+def register_agent_run_shell_command(agent):
+    """Register only the agent_run_shell_command tool."""
+
+    @agent.tool(strict=False)
+    def agent_run_shell_command(
+        context: RunContext, command: str = "", cwd: str = None, timeout: int = 60
+    ) -> ShellCommandOutput:
+        """Execute a shell command with comprehensive monitoring and safety features.
+
+        This tool provides robust shell command execution with streaming output,
+        timeout handling, user confirmation (when not in yolo mode), and proper
+        process lifecycle management. Commands are executed in a controlled
+        environment with cross-platform process group handling.
+
+        Args:
+            command: The shell command to execute. Cannot be empty or whitespace-only.
+            cwd: Working directory for command execution. If None,
+                uses the current working directory. Defaults to None.
+            timeout: Inactivity timeout in seconds. If no output is
+                produced for this duration, the process will be terminated.
+                Defaults to 60 seconds.
+
+        Returns:
+            ShellCommandOutput: A structured response containing:
+                - success (bool): True if command executed successfully (exit code 0)
+                - command (str | None): The executed command string
+                - error (str | None): Error message if execution failed
+                - stdout (str | None): Standard output from the command (last 1000 lines)
+                - stderr (str | None): Standard error from the command (last 1000 lines)
+                - exit_code (int | None): Process exit code
+                - execution_time (float | None): Total execution time in seconds
+                - timeout (bool | None): True if command was terminated due to timeout
+                - user_interrupted (bool | None): True if user killed the process
+
+        Examples:
+            >>> # Basic command execution
+            >>> result = agent_run_shell_command(ctx, "ls -la")
+            >>> print(result.stdout)
+
+            >>> # Command with working directory
+            >>> result = agent_run_shell_command(ctx, "npm test", "/path/to/project")
+            >>> if result.success:
+            ...     print("Tests passed!")
+
+            >>> # Command with custom timeout
+            >>> result = agent_run_shell_command(ctx, "long_running_command", timeout=300)
+            >>> if result.timeout:
+            ...     print("Command timed out")
+
+        Warning:
+            This tool can execute arbitrary shell commands. Exercise caution when
+            running untrusted commands, especially those that modify system state.
+        """
+        return run_shell_command(context, command, cwd, timeout)
+
+
+def register_agent_share_your_reasoning(agent):
+    """Register only the agent_share_your_reasoning tool."""
+
+    @agent.tool(strict=False)
+    def agent_share_your_reasoning(
+        context: RunContext, reasoning: str = "", next_steps: str | None = None
+    ) -> ReasoningOutput:
+        """Share the agent's current reasoning and planned next steps with the user.
+
+        This tool provides transparency into the agent's decision-making process
+        by displaying the current reasoning and upcoming actions in a formatted,
+        user-friendly manner. It's essential for building trust and understanding
+        between the agent and user.
+
+        Args:
+            reasoning: The agent's current thought process, analysis, or
+                reasoning for the current situation. This should be clear,
+                comprehensive, and explain the 'why' behind decisions.
+            next_steps: Planned upcoming actions or steps
+                the agent intends to take. Can be None if no specific next steps
+                are determined. Defaults to None.
+
+        Returns:
+            ReasoningOutput: A simple response object containing:
+                - success (bool): Always True, indicating the reasoning was shared
+
+        Examples:
+            >>> reasoning = "I need to analyze the codebase structure first"
+            >>> next_steps = "First, I'll list the directory contents, then read key files"
+            >>> result = agent_share_your_reasoning(ctx, reasoning, next_steps)
+
+        Best Practice:
+            Use this tool frequently to maintain transparency. Call it:
+            - Before starting complex operations
+            - When changing strategy or approach
+            - To explain why certain decisions are being made
+            - When encountering unexpected situations
+        """
+        return share_your_reasoning(context, reasoning, next_steps)

code_puppy/tools/file_modifications.py

@@ -347,16 +347,19 @@ def _edit_file(
                 {"content": "full file contents", "overwrite": true}
                 {"replacements": [ {"old_str": "foo", "new_str": "bar"}, ... ] }
                 {"delete_snippet": "text to remove"}
+
     The function auto-detects the payload type and routes to the appropriate internal helper.
     """
+    # Extract file_path from payload
+    file_path = os.path.abspath(payload.file_path)
+
     # Use provided group_id or generate one if not provided
     if group_id is None:
-        group_id = generate_group_id("edit_file", payload.file_path)
+        group_id = generate_group_id("edit_file", file_path)
 
     emit_info(
         "\n[bold white on blue] EDIT FILE [/bold white on blue]", message_group=group_id
     )
-    file_path = os.path.abspath(payload.file_path)
     try:
         if isinstance(payload, DeleteSnippetPayload):
             return delete_snippet_from_file(
@@ -449,9 +452,7 @@ def register_file_modifications_tools(agent):
     """Attach file-editing tools to *agent* with mandatory diff rendering."""
 
     @agent.tool(retries=5)
-    def edit_file(
-        context: RunContext, payload: EditFilePayload | str = ""
-    ) -> Dict[str, Any]:
+    def edit_file(context: RunContext, payload: EditFilePayload) -> Dict[str, Any]:
         """Comprehensive file editing tool supporting multiple modification strategies.
 
         This is the primary file modification tool that supports three distinct editing
@@ -477,8 +478,9 @@ def register_file_modifications_tools(agent):
                 DeleteSnippetPayload:
                     - delete_snippet (str): Exact text snippet to remove from file
 
-            file_path (str): Path to the target file. Can be relative or absolute.
-                File will be created if it doesn't exist (for ContentPayload).
+                file_path (str): Path to the target file. Can be relative or absolute.
+                    File will be created if it doesn't exist (for ContentPayload).
+
         Returns:
             Dict[str, Any]: Operation result containing:
                 - success (bool): True if operation completed successfully
@@ -498,16 +500,16 @@ def register_file_modifications_tools(agent):
         Examples:
             >>> # Create new file
             >>> payload = ContentPayload(file_path="foo.py", content="print('Hello World')")
-            >>> result = edit_file(payload)
+            >>> result = edit_file(context, payload)
 
             >>> # Replace specific text
             >>> replacements = [Replacement(old_str="foo", new_str="bar")]
             >>> payload = ReplacementsPayload(file_path="foo.py", replacements=replacements)
-            >>> result = edit_file(payload)
+            >>> result = edit_file(context, payload)
 
             >>> # Delete code block
             >>> payload = DeleteSnippetPayload(file_path="foo.py", delete_snippet="# TODO: remove this")
-            >>> result = edit_file(payload)
+            >>> result = edit_file(context, payload)
 
         Warning:
             - Always verify file contents after modification
@@ -549,7 +551,7 @@ def register_file_modifications_tools(agent):
         return result
 
     @agent.tool(retries=5)
-    def delete_file(context: RunContext, file_path: str = "") -> Dict[str, Any]:
+    def delete_file(context: RunContext, file_path: str) -> Dict[str, Any]:
         """Safely delete files with comprehensive logging and diff generation.
 
         This tool provides safe file deletion with automatic diff generation to show
@@ -606,3 +608,166 @@ def register_file_modifications_tools(agent):
         if "diff" in result:
             del result["diff"]
         return result
+
+
+def register_edit_file(agent):
+    """Register only the edit_file tool."""
+
+    @agent.tool(strict=False)
+    def edit_file(
+        context: RunContext,
+        payload: EditFilePayload | str = "",
+    ) -> Dict[str, Any]:
+        """Comprehensive file editing tool supporting multiple modification strategies.
+
+        This is the primary file modification tool that supports three distinct editing
+        approaches: full content replacement, targeted text replacements, and snippet
+        deletion. It provides robust diff generation, error handling, and automatic
+        retry capabilities for reliable file operations.
+
+        Args:
+            context (RunContext): The PydanticAI runtime context for the agent.
+            payload: One of three payload types:
+
+                ContentPayload:
+                    - content (str): Full file content to write
+                    - overwrite (bool, optional): Whether to overwrite existing files.
+                      Defaults to False (safe mode).
+
+                ReplacementsPayload:
+                    - replacements (List[Replacement]): List of text replacements where
+                      each Replacement contains:
+                      - old_str (str): Exact text to find and replace
+                      - new_str (str): Replacement text
+
+                DeleteSnippetPayload:
+                    - delete_snippet (str): Exact text snippet to remove from file
+
+        Returns:
+            Dict[str, Any]: Operation result containing:
+                - success (bool): True if operation completed successfully
+                - path (str): Absolute path to the modified file
+                - message (str): Human-readable description of changes
+                - changed (bool): True if file content was actually modified
+                - diff (str, optional): Unified diff showing changes made
+                - error (str, optional): Error message if operation failed
+
+        Examples:
+            >>> # Create new file with content
+            >>> payload = {"file_path": "hello.py", "content": "print('Hello!')"}
+            >>> result = edit_file(ctx, payload)
+
+            >>> # Replace text in existing file
+            >>> payload = {
+            ...     "file_path": "config.py",
+            ...     "replacements": [
+            ...         {"old_str": "debug = False", "new_str": "debug = True"}
+            ...     ]
+            ... }
+            >>> result = edit_file(ctx, payload)
+
+            >>> # Delete snippet from file
+            >>> payload = {
+            ...     "file_path": "main.py",
+            ...     "delete_snippet": "# TODO: remove this comment"
+            ... }
+            >>> result = edit_file(ctx, payload)
+
+        Best Practices:
+            - Use replacements for targeted changes (most efficient)
+            - Use content payload only for new files or complete rewrites
+            - Always check the 'success' field before assuming changes worked
+            - Review the 'diff' field to understand what changed
+            - Use delete_snippet for removing specific code blocks
+        """
+        # Handle string payload parsing (for models that send JSON strings)
+        if isinstance(payload, str):
+            # Fallback for weird models that just can't help but send json strings...
+            payload = json.loads(json_repair.repair_json(payload))
+            if "replacements" in payload and "file_path" in payload:
+                payload = ReplacementsPayload(**payload)
+            elif "delete_snippet" in payload and "file_path" in payload:
+                payload = DeleteSnippetPayload(**payload)
+            elif "content" in payload and "file_path" in payload:
+                payload = ContentPayload(**payload)
+            else:
+                file_path = "Unknown"
+                if "file_path" in payload:
+                    file_path = payload["file_path"]
+                # Diagnose what's missing
+                missing = []
+                if "file_path" not in payload:
+                    missing.append("file_path")
+
+                payload_type = "unknown"
+                if "content" in payload:
+                    payload_type = "content"
+                elif "replacements" in payload:
+                    payload_type = "replacements"
+                elif "delete_snippet" in payload:
+                    payload_type = "delete_snippet"
+                else:
+                    missing.append("content/replacements/delete_snippet")
+
+                missing_str = ", ".join(missing) if missing else "none"
+                return {
+                    "success": False,
+                    "path": file_path,
+                    "message": f"Invalid payload for {payload_type} operation. Missing required fields: {missing_str}. Payload keys: {list(payload.keys())}",
+                    "changed": False,
+                }
+
+        # Call _edit_file which will extract file_path from payload and handle group_id generation
+        result = _edit_file(context, payload)
+        if "diff" in result:
+            del result["diff"]
+        return result
+
+
+def register_delete_file(agent):
+    """Register only the delete_file tool."""
+
+    @agent.tool(strict=False)
+    def delete_file(context: RunContext, file_path: str = "") -> Dict[str, Any]:
+        """Safely delete files with comprehensive logging and diff generation.
+
+        This tool provides safe file deletion with automatic diff generation to show
+        exactly what content was removed. It includes proper error handling and
+        automatic retry capabilities for reliable operation.
+
+        Args:
+            context (RunContext): The PydanticAI runtime context for the agent.
+            file_path (str): Path to the file to delete. Can be relative or absolute.
+                Must be an existing regular file (not a directory).
+
+        Returns:
+            Dict[str, Any]: Operation result containing:
+                - success (bool): True if file was successfully deleted
+                - path (str): Absolute path to the deleted file
+                - message (str): Human-readable description of the operation
+                - changed (bool): True if file was actually removed
+                - error (str, optional): Error message if deletion failed
+
+        Examples:
+            >>> # Delete a specific file
+            >>> result = delete_file(ctx, "temp_file.txt")
+            >>> if result['success']:
+            ...     print(f"Deleted: {result['path']}")
+
+            >>> # Handle deletion errors
+            >>> result = delete_file(ctx, "missing.txt")
+            >>> if not result['success']:
+            ...     print(f"Error: {result.get('error', 'Unknown error')}")
+
+        Best Practices:
+            - Always verify file exists before attempting deletion
+            - Check 'success' field to confirm operation completed
+            - Use list_files first to confirm file paths
+            - Cannot delete directories (use shell commands for that)
+        """
+        # Generate group_id for delete_file tool execution
+        group_id = generate_group_id("delete_file", file_path)
+        result = _delete_file(context, file_path, message_group=group_id)
+        if "diff" in result:
+            del result["diff"]
+        return result

code_puppy/tools/file_operations.py

@@ -173,13 +173,14 @@ def _list_files(
         if rel_path == ".":
             rel_path = ""
         if rel_path:
-            os.path.join(directory, rel_path)
+            dir_path = os.path.join(directory, rel_path)
             results.append(
                 ListedFile(
                     **{
                         "path": rel_path,
                         "type": "directory",
                         "size": 0,
+                        "full_path": dir_path,
                         "depth": depth,
                     }
                 )
@@ -187,6 +188,7 @@ def _list_files(
             folder_structure[rel_path] = {
                 "path": rel_path,
                 "depth": depth,
+                "full_path": dir_path,
             }
         for file in files:
             file_path = os.path.join(root, file)
@@ -199,6 +201,7 @@ def _list_files(
                     "path": rel_file_path,
                     "type": "file",
                     "size": size,
+                    "full_path": file_path,
                     "depth": depth,
                 }
                 results.append(ListedFile(**file_info))
@@ -621,3 +624,170 @@ def register_file_operations_tools(agent):
             - For case-insensitive search, try multiple variants manually
         """
         return _grep(context, search_string, directory)
+
+
+def register_list_files(agent):
+    """Register only the list_files tool."""
+
+    @agent.tool(strict=False)
+    def list_files(
+        context: RunContext, directory: str = ".", recursive: bool = True
+    ) -> ListFileOutput:
+        """List files and directories with intelligent filtering and safety features.
+
+        This tool provides comprehensive directory listing with smart home directory
+        detection, project-aware recursion, and token-safe output. It automatically
+        ignores common build artifacts, cache directories, and other noise while
+        providing rich file metadata and visual formatting.
+
+        Args:
+            context (RunContext): The PydanticAI runtime context for the agent.
+            directory (str, optional): Path to the directory to list. Can be relative
+                or absolute. Defaults to "." (current directory).
+            recursive (bool, optional): Whether to recursively list subdirectories.
+                Automatically disabled for home directories unless they contain
+                project indicators. Defaults to True.
+
+        Returns:
+            ListFileOutput: A structured response containing:
+                - files (List[ListedFile]): List of files and directories found, where
+                  each ListedFile contains:
+                  - path (str | None): Relative path from the listing directory
+                  - type (str | None): "file" or "directory"
+                  - size (int): File size in bytes (0 for directories)
+                  - full_path (str | None): Absolute path to the item
+                  - depth (int | None): Nesting depth from the root directory
+                - error (str | None): Error message if listing failed
+
+        Examples:
+            >>> # List current directory
+            >>> result = list_files(ctx)
+            >>> for file in result.files:
+            ...     print(f"{file.type}: {file.path} ({file.size} bytes)")
+
+            >>> # List specific directory non-recursively
+            >>> result = list_files(ctx, "/path/to/project", recursive=False)
+            >>> print(f"Found {len(result.files)} items")
+
+            >>> # Handle potential errors
+            >>> result = list_files(ctx, "/nonexistent/path")
+            >>> if result.error:
+            ...     print(f"Error: {result.error}")
+
+        Best Practices:
+            - Always use this before reading/modifying files
+            - Use non-recursive for quick directory overviews
+            - Check for errors in the response
+            - Combine with grep to find specific file patterns
+        """
+        return _list_files(context, directory, recursive)
+
+
+def register_read_file(agent):
+    """Register only the read_file tool."""
+
+    @agent.tool(strict=False)
+    def read_file(
+        context: RunContext,
+        file_path: str = "",
+        start_line: int | None = None,
+        num_lines: int | None = None,
+    ) -> ReadFileOutput:
+        """Read file contents with optional line-range selection and token safety.
+
+        This tool provides safe file reading with automatic token counting and
+        optional line-range selection for handling large files efficiently.
+        It protects against reading excessively large files that could overwhelm
+        the agent's context window.
+
+        Args:
+            context (RunContext): The PydanticAI runtime context for the agent.
+            file_path (str): Path to the file to read. Can be relative or absolute.
+                Cannot be empty.
+            start_line (int | None, optional): Starting line number for partial reads
+                (1-based indexing). If specified, num_lines must also be provided.
+                Defaults to None (read entire file).
+            num_lines (int | None, optional): Number of lines to read starting from
+                start_line. Must be specified if start_line is provided.
+                Defaults to None (read to end of file).
+
+        Returns:
+            ReadFileOutput: A structured response containing:
+                - content (str | None): The file contents or error message
+                - num_tokens (int): Estimated token count (constrained to < 10,000)
+                - error (str | None): Error message if reading failed
+
+        Examples:
+            >>> # Read entire file
+            >>> result = read_file(ctx, "example.py")
+            >>> print(f"Read {result.num_tokens} tokens")
+            >>> print(result.content)
+
+            >>> # Read specific line range
+            >>> result = read_file(ctx, "large_file.py", start_line=10, num_lines=20)
+            >>> print("Lines 10-29:", result.content)
+
+            >>> # Handle errors
+            >>> result = read_file(ctx, "missing.txt")
+            >>> if result.error:
+            ...     print(f"Error: {result.error}")
+
+        Best Practices:
+            - Always check for errors before using content
+            - Use line ranges for large files to avoid token limits
+            - Monitor num_tokens to stay within context limits
+            - Combine with list_files to find files first
+        """
+        return _read_file(context, file_path, start_line, num_lines)
+
+
+def register_grep(agent):
+    """Register only the grep tool."""
+
+    @agent.tool(strict=False)
+    def grep(
+        context: RunContext, search_string: str = "", directory: str = "."
+    ) -> GrepOutput:
+        """Recursively search for text patterns across files with intelligent filtering.
+
+        This tool provides powerful text searching across directory trees with
+        automatic filtering of irrelevant files, binary detection, and match limiting
+        for performance. It's essential for code exploration and finding specific
+        patterns or references.
+
+        Args:
+            context (RunContext): The PydanticAI runtime context for the agent.
+            search_string (str): The text pattern to search for. Performs exact
+                string matching (not regex). Cannot be empty.
+            directory (str, optional): Root directory to start the recursive search.
+                Can be relative or absolute. Defaults to "." (current directory).
+
+        Returns:
+            GrepOutput: A structured response containing:
+                - matches (List[MatchInfo]): List of matches found, where each
+                  MatchInfo contains:
+                  - file_path (str | None): Absolute path to the file containing the match
+                  - line_number (int | None): Line number where match was found (1-based)
+                  - line_content (str | None): Full line content containing the match
+
+        Examples:
+            >>> # Search for function definitions
+            >>> result = grep(ctx, "def my_function")
+            >>> for match in result.matches:
+            ...     print(f"{match.file_path}:{match.line_number}: {match.line_content}")
+
+            >>> # Search in specific directory
+            >>> result = grep(ctx, "TODO", "/path/to/project/src")
+            >>> print(f"Found {len(result.matches)} TODO items")
+
+            >>> # Search for imports
+            >>> result = grep(ctx, "import pandas")
+            >>> files_using_pandas = {match.file_path for match in result.matches}
+
+        Best Practices:
+            - Use specific search terms to avoid too many results
+            - Search is case-sensitive; try variations if needed
+            - Combine with read_file to examine matches in detail
+            - For case-insensitive search, try multiple variants manually
+        """
+        return _grep(context, search_string, directory)