shotgun-sh 0.3.3.dev1__py3-none-any.whl → 0.6.2__py3-none-any.whl

shotgun/agents/tools/codebase/directory_lister.py

@@ -19,60 +19,48 @@ logger = get_logger(__name__)
     key_arg="directory",
 )
 async def directory_lister(
-    ctx: RunContext[AgentDeps], graph_id: str, directory: str = "."
+    ctx: RunContext[AgentDeps], directory: str = ".", graph_id: str = ""
 ) -> DirectoryListResult:
-    """List directory contents in codebase.
+    """List directory contents in codebase or current working directory.
 
     Args:
         ctx: RunContext containing AgentDeps with codebase service
-        graph_id: Graph ID to identify the repository
-        directory: Path to directory relative to repository root (default: ".")
+        directory: Path to directory relative to repository root or CWD (default: ".")
+        graph_id: Graph ID to identify the repository (optional - uses CWD if not provided)
 
     Returns:
         DirectoryListResult with formatted output via __str__
     """
-    logger.debug("🔧 Listing directory: %s in graph %s", directory, graph_id)
+    logger.debug("🔧 Listing directory: %s in graph %s", directory, graph_id or "(CWD)")
 
     try:
-        if not ctx.deps.codebase_service:
-            return DirectoryListResult(
-                success=False,
-                directory=directory,
-                full_path="",
-                error="No codebase indexed",
-            )
-
-        # Get the graph to find the repository path
-        try:
-            graphs = await ctx.deps.codebase_service.list_graphs()
-            graph = next((g for g in graphs if g.graph_id == graph_id), None)
-        except Exception as e:
-            logger.error("Error getting graph: %s", e)
-            return DirectoryListResult(
-                success=False,
-                directory=directory,
-                full_path="",
-                error=f"Could not find graph with ID '{graph_id}'",
-            )
-
-        if not graph:
-            return DirectoryListResult(
-                success=False,
-                directory=directory,
-                full_path="",
-                error=f"Graph '{graph_id}' not found",
-            )
-
-        # Validate the directory path is within the repository
-        repo_path = Path(graph.repo_path).resolve()
+        # Determine the root path - either from indexed codebase or CWD
+        repo_path: Path | None = None
+
+        if graph_id and ctx.deps.codebase_service:
+            # Try to get the graph to find the repository path
+            try:
+                graphs = await ctx.deps.codebase_service.list_graphs()
+                graph = next((g for g in graphs if g.graph_id == graph_id), None)
+                if graph:
+                    repo_path = Path(graph.repo_path).resolve()
+            except Exception as e:
+                logger.debug("Could not find graph '%s': %s", graph_id, e)
+
+        # Fall back to CWD if no graph found or no graph_id provided
+        if repo_path is None:
+            repo_path = Path.cwd().resolve()
+            logger.debug("📂 Using CWD as root: %s", repo_path)
+
+        # Validate the directory path is within the root
         full_dir_path = (repo_path / directory).resolve()
 
-        # Security check: ensure the resolved path is within the repository
+        # Security check: ensure the resolved path is within the root directory
         try:
             full_dir_path.relative_to(repo_path)
         except ValueError:
             error_msg = (
-                f"Access denied: Path '{directory}' is outside repository bounds"
+                f"Access denied: Path '{directory}' is outside allowed directory bounds"
             )
             logger.warning("🚨 Security violation attempt: %s", error_msg)
             return DirectoryListResult(
@@ -88,7 +76,7 @@ async def directory_lister(
                 success=False,
                 directory=directory,
                 full_path=str(full_dir_path),
-                error=f"Directory '{directory}' not found in repository",
+                error=f"Directory not found: {directory}",
             )
 
         if not full_dir_path.is_dir():

shotgun/agents/tools/codebase/file_read.py

@@ -21,57 +21,48 @@ logger = get_logger(__name__)
     key_arg="file_path",
 )
 async def file_read(
-    ctx: RunContext[AgentDeps], graph_id: str, file_path: str
+    ctx: RunContext[AgentDeps], file_path: str, graph_id: str = ""
 ) -> FileReadResult:
-    """Read file contents from codebase.
+    """Read file contents from codebase or current working directory.
 
     Args:
         ctx: RunContext containing AgentDeps with codebase service
-        graph_id: Graph ID to identify the repository
-        file_path: Path to file relative to repository root
+        file_path: Path to file relative to repository root or CWD
+        graph_id: Graph ID to identify the repository (optional - uses CWD if not provided)
 
     Returns:
         FileReadResult with formatted output via __str__
     """
-    logger.debug("🔧 Reading file: %s in graph %s", file_path, graph_id)
+    logger.debug("🔧 Reading file: %s in graph %s", file_path, graph_id or "(CWD)")
 
     try:
-        if not ctx.deps.codebase_service:
-            return FileReadResult(
-                success=False,
-                file_path=file_path,
-                error="No codebase indexed",
-            )
-
-        # Get the graph to find the repository path
-        try:
-            graphs = await ctx.deps.codebase_service.list_graphs()
-            graph = next((g for g in graphs if g.graph_id == graph_id), None)
-        except Exception as e:
-            logger.error("Error getting graph: %s", e)
-            return FileReadResult(
-                success=False,
-                file_path=file_path,
-                error=f"Could not find graph with ID '{graph_id}'",
-            )
-
-        if not graph:
-            return FileReadResult(
-                success=False,
-                file_path=file_path,
-                error=f"Graph '{graph_id}' not found",
-            )
+        # Determine the root path - either from indexed codebase or CWD
+        repo_path: Path | None = None
 
-        # Validate the file path is within the repository
-        repo_path = Path(graph.repo_path).resolve()
+        if graph_id and ctx.deps.codebase_service:
+            # Try to get the graph to find the repository path
+            try:
+                graphs = await ctx.deps.codebase_service.list_graphs()
+                graph = next((g for g in graphs if g.graph_id == graph_id), None)
+                if graph:
+                    repo_path = Path(graph.repo_path).resolve()
+            except Exception as e:
+                logger.debug("Could not find graph '%s': %s", graph_id, e)
+
+        # Fall back to CWD if no graph found or no graph_id provided
+        if repo_path is None:
+            repo_path = Path.cwd().resolve()
+            logger.debug("📂 Using CWD as root: %s", repo_path)
+
+        # Validate the file path is within the root
         full_file_path = (repo_path / file_path).resolve()
 
-        # Security check: ensure the resolved path is within the repository
+        # Security check: ensure the resolved path is within the root directory
         try:
             full_file_path.relative_to(repo_path)
         except ValueError:
             error_msg = (
-                f"Access denied: Path '{file_path}' is outside repository bounds"
+                f"Access denied: Path '{file_path}' is outside allowed directory bounds"
             )
             logger.warning("🚨 Security violation attempt: %s", error_msg)
             return FileReadResult(success=False, file_path=file_path, error=error_msg)
@@ -81,7 +72,7 @@ async def file_read(
             return FileReadResult(
                 success=False,
                 file_path=file_path,
-                error=f"File '{file_path}' not found in repository",
+                error=f"File not found: {file_path}",
             )
 
         if full_file_path.is_dir():

shotgun/agents/tools/codebase/query_graph.py

@@ -4,6 +4,7 @@ from pydantic_ai import RunContext
 
 from shotgun.agents.models import AgentDeps
 from shotgun.agents.tools.registry import ToolCategory, register_tool
+from shotgun.codebase.indexing_state import IndexingState
 from shotgun.codebase.models import QueryType
 from shotgun.logging_config import get_logger
 
@@ -40,6 +41,14 @@ async def query_graph(
                 error="No codebase indexed",
             )
 
+        # Check if graph is currently being indexed
+        if ctx.deps.codebase_service.indexing.is_active(graph_id):
+            return QueryGraphResult(
+                success=False,
+                query=query,
+                error=IndexingState.INDEXING_IN_PROGRESS_ERROR,
+            )
+
         # Execute natural language query
         result = await ctx.deps.codebase_service.execute_query(
             graph_id=graph_id,

shotgun/agents/tools/codebase/retrieve_code.py

@@ -8,6 +8,7 @@ from shotgun.agents.models import AgentDeps
 from shotgun.agents.tools.registry import ToolCategory, register_tool
 from shotgun.codebase.core.code_retrieval import retrieve_code_by_qualified_name
 from shotgun.codebase.core.language_config import get_language_config
+from shotgun.codebase.indexing_state import IndexingState
 from shotgun.logging_config import get_logger
 
 from .models import CodeSnippetResult
@@ -43,6 +44,14 @@ async def retrieve_code(
                 error="No codebase indexed",
             )
 
+        # Check if graph is currently being indexed
+        if ctx.deps.codebase_service.indexing.is_active(graph_id):
+            return CodeSnippetResult(
+                found=False,
+                qualified_name=qualified_name,
+                error=IndexingState.INDEXING_IN_PROGRESS_ERROR,
+            )
+
         # Use the existing code retrieval functionality
         code_snippet = await retrieve_code_by_qualified_name(
             manager=ctx.deps.codebase_service.manager,

shotgun/agents/tools/file_management.py

@@ -23,7 +23,10 @@ logger = get_logger(__name__)
 # - A list of Paths: multiple allowed files/directories (e.g., [Path("specification.md"), Path("contracts")])
 # - "*": any file except protected files (for export agent)
 AGENT_DIRECTORIES: dict[AgentType, str | Path | list[Path]] = {
-    AgentType.RESEARCH: Path("research.md"),
+    AgentType.RESEARCH: [
+        Path("research.md"),
+        Path("research"),
+    ],  # Research can write main file and research folder
     AgentType.SPECIFY: [
         Path("specification.md"),
         Path("contracts"),
@@ -160,19 +163,33 @@ def _validate_shotgun_path(filename: str) -> Path:
     return full_path
 
 
+# Binary file extensions that should be loaded via file_requests
+BINARY_EXTENSIONS = {".pdf", ".png", ".jpg", ".jpeg", ".gif", ".webp"}
+
+
 @register_tool(
     category=ToolCategory.ARTIFACT_MANAGEMENT,
     display_text="Reading file",
     key_arg="filename",
 )
 async def read_file(ctx: RunContext[AgentDeps], filename: str) -> str:
-    """Read a file from the .shotgun directory.
+    """Read a TEXT file from the .shotgun directory.
+
+    IMPORTANT: This tool is for TEXT files only (.md, .txt, .json, etc.).
+
+    For BINARY files (PDFs, images), DO NOT use this tool. Instead:
+    - Use file_requests in your response to load binary files
+    - Example: {"response": "Let me check that.", "file_requests": ["/path/to/file.pdf"]}
+
+    Binary file extensions that require file_requests instead:
+    - .pdf, .png, .jpg, .jpeg, .gif, .webp
 
     Args:
         filename: Relative path to file within .shotgun directory
 
     Returns:
-        File contents as string
+        File contents as string. For binary files, returns instructions
+        with the absolute path to use in file_requests.
 
     Raises:
         ValueError: If path is outside .shotgun directory
@@ -186,6 +203,22 @@ async def read_file(ctx: RunContext[AgentDeps], filename: str) -> str:
         if not await aiofiles.os.path.exists(file_path):
             raise FileNotFoundError(f"File not found: {filename}")
 
+        # Check if it's a binary file type (PDF, image)
+        suffix = file_path.suffix.lower()
+        if suffix in BINARY_EXTENSIONS:
+            # Return info for the agent to use file_requests
+            logger.debug(
+                "📎 Binary file detected (%s), returning path for file_requests: %s",
+                suffix,
+                file_path,
+            )
+            return (
+                f"This is a binary file ({suffix}) that cannot be read as text. "
+                f"To view its contents, include the absolute path in your "
+                f"`file_requests` response field:\n\n"
+                f"Absolute path: {file_path}"
+            )
+
         async with aiofiles.open(file_path, encoding="utf-8") as f:
             content = await f.read()
         logger.debug("📄 Read %d characters from %s", len(content), filename)
@@ -282,3 +315,48 @@ async def append_file(ctx: RunContext[AgentDeps], filename: str, content: str) -
         Success message or error message
     """
     return await write_file(ctx, filename, content, mode="a")
+
+
+@register_tool(
+    category=ToolCategory.ARTIFACT_MANAGEMENT,
+    display_text="Deleting file",
+    key_arg="filename",
+)
+async def delete_file(ctx: RunContext[AgentDeps], filename: str) -> str:
+    """Delete a file from the .shotgun directory.
+
+    Uses the same permission model as write_file - agents can only delete
+    files they have permission to write to.
+
+    Args:
+        filename: Relative path to file within .shotgun directory
+
+    Returns:
+        Success message or error message
+
+    Raises:
+        ValueError: If path is outside .shotgun directory or agent lacks permission
+        FileNotFoundError: If file does not exist
+    """
+    logger.debug("🔧 Deleting file: %s", filename)
+
+    try:
+        # Use agent-scoped validation (same as write_file)
+        file_path = _validate_agent_scoped_path(filename, ctx.deps.agent_mode)
+
+        if not await aiofiles.os.path.exists(file_path):
+            raise FileNotFoundError(f"File not found: {filename}")
+
+        # Delete the file
+        await aiofiles.os.remove(file_path)
+        logger.debug("🗑️ Deleted file: %s", filename)
+
+        # Track the file operation
+        ctx.deps.file_tracker.add_operation(file_path, FileOperationType.DELETED)
+
+        return f"Successfully deleted {filename}"
+
+    except Exception as e:
+        error_msg = f"Error deleting file '{filename}': {str(e)}"
+        logger.error("❌ File delete failed: %s", error_msg)
+        return error_msg

shotgun/agents/tools/file_read_tools/__init__.py

@@ -0,0 +1,7 @@
+"""File reading tools for the FileRead agent."""
+
+from shotgun.agents.tools.file_read_tools.multimodal_file_read import (
+    multimodal_file_read,
+)
+
+__all__ = ["multimodal_file_read"]

shotgun/agents/tools/file_read_tools/multimodal_file_read.py

@@ -0,0 +1,167 @@
+"""Multimodal file reading tool that verifies files exist and returns paths.
+
+This tool verifies PDFs/images exist and returns their paths for the agent
+to include in `files_found`. The Router then loads these via `file_requests`.
+"""
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+from pydantic_ai import RunContext, ToolReturn
+
+from shotgun.agents.models import AgentDeps
+from shotgun.agents.tools.registry import ToolCategory, register_tool
+from shotgun.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+# MIME type mapping for supported file types
+MIME_TYPES: dict[str, str] = {
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+}
+
+# Maximum file size for multimodal reading (32MB - Anthropic's limit)
+MAX_FILE_SIZE_BYTES = 32 * 1024 * 1024
+
+
+class MultimodalFileReadResult(BaseModel):
+    """Result from multimodal file read."""
+
+    success: bool = Field(description="Whether the file was successfully found")
+    file_path: str = Field(description="The absolute path to the file")
+    file_name: str = Field(default="", description="The file name")
+    file_size_bytes: int = Field(default=0, description="File size in bytes")
+    mime_type: str = Field(default="", description="MIME type of the file")
+    error: str | None = Field(default=None, description="Error message if failed")
+
+    def __str__(self) -> str:
+        if not self.success:
+            return f"Error: {self.error}"
+        return (
+            f"Found: {self.file_name} ({self.file_size_bytes} bytes, {self.mime_type})"
+        )
+
+
+def _get_mime_type(file_path: Path) -> str | None:
+    """Get MIME type for a file based on extension."""
+    suffix = file_path.suffix.lower()
+    return MIME_TYPES.get(suffix)
+
+
+def _format_file_size(size_bytes: int) -> str:
+    """Format file size in human-readable format."""
+    if size_bytes < 1024:
+        return f"{size_bytes} B"
+    elif size_bytes < 1024 * 1024:
+        return f"{size_bytes / 1024:.1f} KB"
+    else:
+        return f"{size_bytes / (1024 * 1024):.1f} MB"
+
+
+@register_tool(
+    category=ToolCategory.CODEBASE_UNDERSTANDING,
+    display_text="Reading file (multimodal)",
+    key_arg="file_path",
+)
+async def multimodal_file_read(
+    ctx: RunContext[AgentDeps],
+    file_path: str,
+) -> ToolReturn:
+    """Verify a PDF or image file exists and return its path.
+
+    This tool checks that the file exists and is a supported type (PDF, image),
+    then returns the absolute path. Include this path in your `files_found`
+    response so the Router can load it for visual analysis.
+
+    Args:
+        ctx: RunContext containing AgentDeps
+        file_path: Path to the file (absolute or relative to CWD)
+
+    Returns:
+        ToolReturn with file info and absolute path
+    """
+    logger.debug("Checking multimodal file: %s", file_path)
+
+    try:
+        # Resolve the path
+        path = Path(file_path).expanduser().resolve()
+
+        # Check if file exists
+        if not path.exists():
+            error_result = MultimodalFileReadResult(
+                success=False,
+                file_path=str(path),
+                error=f"File not found: {file_path}",
+            )
+            return ToolReturn(return_value=str(error_result))
+
+        if path.is_dir():
+            error_result = MultimodalFileReadResult(
+                success=False,
+                file_path=str(path),
+                error=f"'{file_path}' is a directory, not a file",
+            )
+            return ToolReturn(return_value=str(error_result))
+
+        # Check MIME type
+        mime_type = _get_mime_type(path)
+        if mime_type is None:
+            supported = ", ".join(MIME_TYPES.keys())
+            error_result = MultimodalFileReadResult(
+                success=False,
+                file_path=str(path),
+                error=f"Unsupported file type: {path.suffix}. Supported: {supported}",
+            )
+            return ToolReturn(return_value=str(error_result))
+
+        # Check file size
+        file_size = path.stat().st_size
+        if file_size > MAX_FILE_SIZE_BYTES:
+            error_result = MultimodalFileReadResult(
+                success=False,
+                file_path=str(path),
+                file_size_bytes=file_size,
+                error=f"File too large: {_format_file_size(file_size)} (max: {_format_file_size(MAX_FILE_SIZE_BYTES)})",
+            )
+            return ToolReturn(return_value=str(error_result))
+
+        logger.debug(
+            "Found multimodal file: %s (%s, %s)",
+            path.name,
+            _format_file_size(file_size),
+            mime_type,
+        )
+
+        # Return file info with absolute path
+        file_type = "PDF" if mime_type == "application/pdf" else "Image"
+        summary = f"""{file_type} found: {path.name}
+Size: {_format_file_size(file_size)}
+Type: {mime_type}
+Absolute path: {path}
+
+IMPORTANT: Include the absolute path above in your `files_found` response field.
+The Router will then be able to load and analyze this file's visual content."""
+
+        return ToolReturn(return_value=summary)
+
+    except PermissionError:
+        error_result = MultimodalFileReadResult(
+            success=False,
+            file_path=file_path,
+            error=f"Permission denied: {file_path}",
+        )
+        return ToolReturn(return_value=str(error_result))
+
+    except Exception as e:
+        logger.error("Error checking multimodal file: %s", str(e))
+        error_result = MultimodalFileReadResult(
+            success=False,
+            file_path=file_path,
+            error=f"Error: {str(e)}",
+        )
+        return ToolReturn(return_value=str(error_result))

shotgun/agents/tools/markdown_tools/__init__.py

@@ -0,0 +1,62 @@
+"""Markdown manipulation tools for Pydantic AI agents."""
+
+from .insert_section import insert_markdown_section
+from .models import (
+    CloseMatch,
+    HeadingList,
+    HeadingMatch,
+    MarkdownFileContext,
+    MarkdownHeading,
+    SectionMatchResult,
+    SectionNumber,
+)
+from .remove_section import remove_markdown_section
+from .replace_section import replace_markdown_section
+from .utils import (
+    decrement_section_number,
+    detect_line_ending,
+    extract_headings,
+    find_and_validate_section,
+    find_close_matches,
+    find_matching_heading,
+    find_section_bounds,
+    get_heading_level,
+    increment_section_number,
+    load_markdown_file,
+    normalize_section_content,
+    parse_section_number,
+    renumber_headings_after,
+    split_normalized_content,
+    write_markdown_file,
+)
+
+__all__ = [
+    # Tools
+    "replace_markdown_section",
+    "insert_markdown_section",
+    "remove_markdown_section",
+    # Models
+    "MarkdownHeading",
+    "HeadingList",
+    "HeadingMatch",
+    "CloseMatch",
+    "SectionNumber",
+    "MarkdownFileContext",
+    "SectionMatchResult",
+    # Utilities
+    "get_heading_level",
+    "extract_headings",
+    "find_matching_heading",
+    "find_close_matches",
+    "find_section_bounds",
+    "detect_line_ending",
+    "normalize_section_content",
+    "split_normalized_content",
+    "parse_section_number",
+    "increment_section_number",
+    "decrement_section_number",
+    "renumber_headings_after",
+    "load_markdown_file",
+    "find_and_validate_section",
+    "write_markdown_file",
+]