agentpool 2.1.9__py3-none-any.whl → 2.5.0__py3-none-any.whl

agentpool/tool_impls/grep/tool.py

@@ -0,0 +1,200 @@
+"""Grep search tool implementation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from agentpool.agents.context import AgentContext  # noqa: TC001
+from agentpool.log import get_logger
+from agentpool.tools.base import Tool, ToolResult
+
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from exxec import ExecutionEnvironment
+    from fsspec.asyn import AsyncFileSystem
+
+    from agentpool_toolsets.fsspec_toolset.grep import GrepBackend
+
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class GrepTool(Tool[ToolResult]):
+    """Search file contents for patterns using grep.
+
+    A standalone tool for searching file contents with:
+    - Regex pattern matching
+    - File filtering with glob patterns
+    - Context lines before/after matches
+    - Subprocess grep (ripgrep/grep) or pure Python fallback
+    - Configurable output limits
+
+    Use create_grep_tool() factory for convenient instantiation.
+    """
+
+    # Tool-specific configuration
+    env: ExecutionEnvironment | None = None
+    """Execution environment to use. Falls back to agent.env if not set."""
+
+    cwd: str | None = None
+    """Working directory for resolving relative paths."""
+
+    max_output_kb: int = 64
+    """Maximum output size in KB."""
+
+    use_subprocess_grep: bool = True
+    """Use ripgrep/grep subprocess if available (faster for large codebases)."""
+
+    _grep_backend: GrepBackend | None = field(default=None, init=False)
+    """Cached grep backend detection."""
+
+    def get_callable(self) -> Callable[..., Awaitable[ToolResult]]:
+        """Return the grep method as the callable."""
+        return self._grep
+
+    def _get_fs(self, ctx: AgentContext) -> AsyncFileSystem:
+        """Get filesystem from env, falling back to agent's env if not set."""
+        from fsspec.asyn import AsyncFileSystem
+        from fsspec.implementations.asyn_wrapper import AsyncFileSystemWrapper
+
+        if self.env is not None:
+            fs = self.env.get_fs()
+            return fs if isinstance(fs, AsyncFileSystem) else AsyncFileSystemWrapper(fs)
+        fs = ctx.agent.env.get_fs()
+        return fs if isinstance(fs, AsyncFileSystem) else AsyncFileSystemWrapper(fs)
+
+    def _resolve_path(self, path: str, ctx: AgentContext) -> str:
+        """Resolve a potentially relative path to an absolute path."""
+        cwd: str | None = None
+        if self.cwd:
+            cwd = self.cwd
+        elif self.env and self.env.cwd:
+            cwd = self.env.cwd
+        elif ctx.agent.env and ctx.agent.env.cwd:
+            cwd = ctx.agent.env.cwd
+
+        if cwd and not (path.startswith("/") or (len(path) > 1 and path[1] == ":")):
+            return str(Path(cwd) / path)
+        return path
+
+    async def _grep(
+        self,
+        ctx: AgentContext,
+        pattern: str,
+        path: str,
+        *,
+        file_pattern: str = "**/*",
+        case_sensitive: bool = False,
+        max_matches: int = 100,
+        context_lines: int = 0,
+    ) -> ToolResult:
+        """Search file contents for a pattern.
+
+        Args:
+            ctx: Agent context for event emission and filesystem access
+            pattern: Regex pattern to search for
+            path: Base directory to search in
+            file_pattern: Glob pattern to filter files (e.g. "**/*.py")
+            case_sensitive: Whether search is case-sensitive
+            max_matches: Maximum number of matches to return
+            context_lines: Number of context lines before/after match
+
+        Returns:
+            Grep results as formatted text
+        """
+        from agentpool_toolsets.fsspec_toolset.grep import (
+            DEFAULT_EXCLUDE_PATTERNS,
+            GrepBackend,
+            detect_grep_backend,
+            grep_with_fsspec,
+            grep_with_subprocess,
+        )
+
+        resolved_path = self._resolve_path(path, ctx)
+        msg = f"Searching for {pattern!r} in {resolved_path}"
+        await ctx.events.tool_call_start(title=msg, kind="search", locations=[resolved_path])
+
+        max_output_bytes = self.max_output_kb * 1024
+        result: dict[str, Any] | None = None
+
+        try:
+            # Try subprocess grep if configured and available
+            if self.use_subprocess_grep:
+                # Get execution environment for running grep command
+                env = self.env or ctx.agent.env
+                if env is not None:
+                    # Detect and cache grep backend
+                    if self._grep_backend is None:
+                        self._grep_backend = await detect_grep_backend(env)
+                    # Only use subprocess if we have a real grep backend
+                    if self._grep_backend != GrepBackend.PYTHON:
+                        result = await grep_with_subprocess(
+                            env=env,
+                            pattern=pattern,
+                            path=resolved_path,
+                            backend=self._grep_backend,
+                            case_sensitive=case_sensitive,
+                            max_matches=max_matches,
+                            max_output_bytes=max_output_bytes,
+                            exclude_patterns=DEFAULT_EXCLUDE_PATTERNS,
+                            use_gitignore=True,
+                            context_lines=context_lines,
+                        )
+
+            # Fallback to fsspec grep if subprocess didn't work
+            if result is None or "error" in result:
+                fs = self._get_fs(ctx)
+                result = await grep_with_fsspec(
+                    fs=fs,
+                    pattern=pattern,
+                    path=resolved_path,
+                    file_pattern=file_pattern,
+                    case_sensitive=case_sensitive,
+                    max_matches=max_matches,
+                    max_output_bytes=max_output_bytes,
+                    context_lines=context_lines,
+                )
+
+            if "error" in result:
+                error_msg = f"Error: {result['error']}"
+                return ToolResult(
+                    content=error_msg,
+                    metadata={"matches": 0, "truncated": False},
+                )
+
+            # Format output
+            matches = result.get("matches", "")
+            match_count = result.get("match_count", 0)
+            was_truncated = result.get("was_truncated", False)
+
+            if not matches:
+                output = f"No matches found for pattern '{pattern}'"
+            else:
+                output = f"Found {match_count} matches:\n\n{matches}"
+                if was_truncated:
+                    output += "\n\n[Results truncated]"
+
+            # Emit formatted content for UI display
+            from agentpool.agents.events import TextContentItem
+
+            await ctx.events.tool_call_progress(
+                title=f"Found {match_count} matches",
+                items=[TextContentItem(text=output)],
+                replace_content=True,
+            )
+        except Exception as e:  # noqa: BLE001
+            error_msg = f"Error: Grep failed: {e}"
+            return ToolResult(
+                content=error_msg,
+                metadata={"matches": 0, "truncated": False},
+            )
+        else:
+            return ToolResult(
+                content=output,
+                metadata={"matches": match_count, "truncated": was_truncated},
+            )

agentpool/tool_impls/list_directory/__init__.py

@@ -0,0 +1,73 @@
+"""List directory tool."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from agentpool.tool_impls.list_directory.tool import ListDirectoryTool
+from agentpool_config.tools import ToolHints
+
+
+if TYPE_CHECKING:
+    from exxec import ExecutionEnvironment
+
+__all__ = ["ListDirectoryTool", "create_list_directory_tool"]
+
+# Tool metadata defaults
+NAME = "list_directory"
+DESCRIPTION = """List files in a directory with filtering support.
+
+Supports:
+- Glob pattern matching (*, **, *.py, etc.)
+- Exclude patterns for filtering
+- Recursive directory traversal with depth control
+- Safety limits to prevent overwhelming output"""
+CATEGORY: Literal["read"] = "read"
+HINTS = ToolHints(read_only=True, idempotent=True)
+
+
+def create_list_directory_tool(
+    *,
+    env: ExecutionEnvironment | None = None,
+    cwd: str | None = None,
+    max_items: int = 500,
+    name: str = NAME,
+    description: str = DESCRIPTION,
+    requires_confirmation: bool = False,
+) -> ListDirectoryTool:
+    """Create a configured ListDirectoryTool instance.
+
+    Args:
+        env: Execution environment to use. Falls back to agent.env if not set.
+        cwd: Working directory for resolving relative paths.
+        max_items: Maximum number of items to return (safety limit, default: 500).
+        name: Tool name override.
+        description: Tool description override.
+        requires_confirmation: Whether tool execution needs confirmation.
+
+    Returns:
+        Configured ListDirectoryTool instance.
+
+    Example:
+        # Basic usage
+        ls = create_list_directory_tool()
+
+        # With custom limits
+        ls = create_list_directory_tool(max_items=1000)
+
+        # With specific environment
+        ls = create_list_directory_tool(
+            env=my_env,
+            cwd="/workspace",
+        )
+    """
+    return ListDirectoryTool(
+        name=name,
+        description=description,
+        category=CATEGORY,
+        hints=HINTS,
+        env=env,
+        cwd=cwd,
+        max_items=max_items,
+        requires_confirmation=requires_confirmation,
+    )

agentpool/tool_impls/list_directory/tool.py

@@ -0,0 +1,197 @@
+"""List directory tool implementation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from fnmatch import fnmatch
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from upathtools import is_directory
+
+from agentpool.agents.context import AgentContext  # noqa: TC001
+from agentpool.log import get_logger
+from agentpool.tools.base import Tool, ToolResult
+
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from exxec import ExecutionEnvironment
+    from fsspec.asyn import AsyncFileSystem
+
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class ListDirectoryTool(Tool[ToolResult]):
+    """List files in a directory with filtering support.
+
+    A standalone tool for listing directory contents with:
+    - Glob pattern matching (*, **, *.py, etc.)
+    - Exclude patterns for filtering
+    - Recursive directory traversal with depth control
+    - Formatted markdown output
+
+    Use create_list_directory_tool() factory for convenient instantiation.
+    """
+
+    # Tool-specific configuration
+    env: ExecutionEnvironment | None = None
+    """Execution environment to use. Falls back to agent.env if not set."""
+
+    cwd: str | None = None
+    """Working directory for resolving relative paths."""
+
+    max_items: int = 500
+    """Maximum number of items to return (safety limit)."""
+
+    def get_callable(self) -> Callable[..., Awaitable[ToolResult]]:
+        """Return the list_directory method as the callable."""
+        return self._list_directory
+
+    def _get_fs(self, ctx: AgentContext) -> AsyncFileSystem:
+        """Get filesystem from env, falling back to agent's env if not set."""
+        from fsspec.asyn import AsyncFileSystem
+        from fsspec.implementations.asyn_wrapper import AsyncFileSystemWrapper
+
+        if self.env is not None:
+            fs = self.env.get_fs()
+            return fs if isinstance(fs, AsyncFileSystem) else AsyncFileSystemWrapper(fs)
+        fs = ctx.agent.env.get_fs()
+        return fs if isinstance(fs, AsyncFileSystem) else AsyncFileSystemWrapper(fs)
+
+    def _resolve_path(self, path: str, ctx: AgentContext) -> str:
+        """Resolve a potentially relative path to an absolute path."""
+        cwd: str | None = None
+        if self.cwd:
+            cwd = self.cwd
+        elif self.env and self.env.cwd:
+            cwd = self.env.cwd
+        elif ctx.agent.env and ctx.agent.env.cwd:
+            cwd = ctx.agent.env.cwd
+
+        if cwd and not (path.startswith("/") or (len(path) > 1 and path[1] == ":")):
+            return str(Path(cwd) / path)
+        return path
+
+    async def _list_directory(
+        self,
+        ctx: AgentContext,
+        path: str,
+        *,
+        pattern: str = "*",
+        exclude: list[str] | None = None,
+        max_depth: int = 1,
+    ) -> ToolResult:
+        """List files in a directory with filtering support.
+
+        Args:
+            ctx: Agent context for event emission and filesystem access
+            path: Base directory to list
+            pattern: Glob pattern to match files against. Use "*.py" to match Python
+                files in current directory only, or "**/*.py" to match recursively.
+                The max_depth parameter limits how deep "**" patterns search.
+            exclude: List of patterns to exclude (uses fnmatch against relative paths)
+            max_depth: Maximum directory depth to search (default: 1 = current dir only).
+                Only affects recursive "**" patterns.
+
+        Returns:
+            Markdown-formatted directory listing
+        """
+        from agentpool_toolsets.fsspec_toolset.helpers import format_directory_listing
+
+        path = self._resolve_path(path, ctx)
+        msg = f"Listing directory: {path}"
+        await ctx.events.tool_call_start(title=msg, kind="read", locations=[path])
+
+        try:
+            fs = self._get_fs(ctx)
+            # Check if path exists
+            if not await fs._exists(path):
+                error_msg = f"Path does not exist: {path}"
+                await ctx.events.file_operation("list", path=path, success=False, error=error_msg)
+                return ToolResult(
+                    content=f"Error: {error_msg}",
+                    metadata={"count": 0, "truncated": False},
+                )
+
+            # Build glob path
+            glob_pattern = f"{path.rstrip('/')}/{pattern}"
+            paths = await fs._glob(glob_pattern, maxdepth=max_depth, detail=True)
+
+            files: list[dict[str, Any]] = []
+            dirs: list[dict[str, Any]] = []
+
+            # Safety check - prevent returning too many items
+            total_found = len(paths)
+            if total_found > self.max_items:
+                suggestions = []
+                if pattern == "*":
+                    suggestions.append("Use a more specific pattern like '*.py', '*.txt', etc.")
+                if max_depth > 1:
+                    suggestions.append(f"Reduce max_depth from {max_depth} to 1 or 2.")
+                if not exclude:
+                    suggestions.append("Use exclude parameter to filter out unwanted directories.")
+
+                suggestion_text = " ".join(suggestions) if suggestions else ""
+                error_msg = f"Error: Too many items ({total_found:,}). {suggestion_text}"
+                return ToolResult(
+                    content=error_msg,
+                    metadata={"count": total_found, "truncated": True},
+                )
+
+            for file_path, file_info in paths.items():  # pyright: ignore[reportAttributeAccessIssue]
+                rel_path = os.path.relpath(str(file_path), path)
+
+                # Skip excluded patterns
+                if exclude and any(fnmatch(rel_path, pat) for pat in exclude):
+                    continue
+
+                # Use type from glob detail info, falling back to isdir only if needed
+                is_dir = await is_directory(fs, file_path, entry_type=file_info.get("type"))  # pyright: ignore[reportArgumentType]
+
+                item_info = {
+                    "name": Path(file_path).name,  # pyright: ignore[reportArgumentType]
+                    "path": file_path,
+                    "relative_path": rel_path,
+                    "size": file_info.get("size", 0),
+                    "type": "directory" if is_dir else "file",
+                }
+                if "mtime" in file_info:
+                    item_info["modified"] = file_info["mtime"]
+
+                if is_dir:
+                    dirs.append(item_info)
+                else:
+                    files.append(item_info)
+
+            await ctx.events.file_operation("list", path=path, success=True)
+            result = format_directory_listing(path, dirs, files, pattern)
+            # Emit formatted content for UI display
+            from agentpool.agents.events import TextContentItem
+
+            await ctx.events.tool_call_progress(
+                title=f"Listed: {path}",
+                items=[TextContentItem(text=result)],
+                replace_content=True,
+            )
+        except (OSError, ValueError, FileNotFoundError) as e:
+            await ctx.events.file_operation("list", path=path, success=False, error=str(e))
+            error_msg = (
+                f"Error: Could not list directory: {path}. Ensure path is absolute and exists."
+            )
+            return ToolResult(
+                content=error_msg,
+                metadata={"count": 0, "truncated": False},
+            )
+        else:
+            total_items = len(files) + len(dirs)
+            # Check if we hit the limit (truncation)
+            was_truncated = total_items >= self.max_items
+            return ToolResult(
+                content=result,
+                metadata={"count": total_items, "truncated": was_truncated},
+            )

agentpool/tool_impls/question/__init__.py

@@ -0,0 +1,42 @@
+"""User interaction tool for asking clarifying questions."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from agentpool.tool_impls.question.tool import QuestionTool
+from agentpool_config.tools import ToolHints
+
+
+__all__ = ["QuestionTool", "create_question_tool"]
+
+# Tool metadata defaults
+NAME = "question"
+DESCRIPTION = "Ask the user a clarifying question during processing."
+CATEGORY: Literal["other"] = "other"
+HINTS = ToolHints(open_world=True)
+
+
+def create_question_tool(
+    *,
+    name: str = NAME,
+    description: str = DESCRIPTION,
+    requires_confirmation: bool = False,
+) -> QuestionTool:
+    """Create a configured QuestionTool instance.
+
+    Args:
+        name: Tool name override.
+        description: Tool description override.
+        requires_confirmation: Whether tool execution needs confirmation.
+
+    Returns:
+        Configured QuestionTool instance.
+    """
+    return QuestionTool(
+        name=name,
+        description=description,
+        category=CATEGORY,
+        hints=HINTS,
+        requires_confirmation=requires_confirmation,
+    )

agentpool/tool_impls/question/tool.py

@@ -0,0 +1,127 @@
+"""AskUser tool implementation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, assert_never
+
+from agentpool.agents.context import AgentContext  # noqa: TC001
+from agentpool.tools.base import Tool, ToolResult
+
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+
+@dataclass
+class QuestionOption:
+    """Option for a question in OpenCode format.
+
+    Represents a single choice that can be presented to the user.
+    """
+
+    label: str
+    """Display text (1-5 words, concise)."""
+
+    description: str
+    """Explanation of the choice."""
+
+
+@dataclass
+class OpenCodeQuestionInfo:
+    """Question information in OpenCode format.
+
+    This matches OpenCode's QuestionInfo schema used by the TUI.
+    """
+
+    question: str
+    """Complete question text."""
+
+    header: str
+    """Very short label (max 12 chars) - used for tab headers in the TUI."""
+
+    options: list[QuestionOption]
+    """Available choices for the user to select from."""
+
+    multiple: bool = False
+    """Allow selecting multiple choices."""
+
+
+@dataclass
+class QuestionTool(Tool[ToolResult]):
+    """Tool for asking the user clarifying questions.
+
+    Enables agents to ask users for additional information or clarification
+    when needed to complete a task effectively.
+    """
+
+    def get_callable(self) -> Callable[..., Awaitable[ToolResult]]:
+        """Get the tool callable."""
+        return self._execute
+
+    async def _execute(
+        self,
+        ctx: AgentContext,
+        prompt: str,
+        response_schema: dict[str, Any] | None = None,
+    ) -> ToolResult:
+        """Ask the user a clarifying question.
+
+        Args:
+            ctx: Agent execution context.
+            prompt: Question to ask the user.
+            response_schema: Optional JSON schema for structured response.
+
+        Returns:
+            The user's response as a string.
+        """
+        from mcp.types import ElicitRequestFormParams, ElicitResult, ErrorData
+
+        schema = response_schema or {"type": "string"}
+        params = ElicitRequestFormParams(message=prompt, requestedSchema=schema)
+        result = await ctx.handle_elicitation(params)
+
+        match result:
+            case ElicitResult(action="accept", content=content):
+                # Content is a dict with "value" key per MCP spec
+                if isinstance(content, dict) and "value" in content:
+                    value = content["value"]
+                    # Handle list responses (multi-select)
+                    if isinstance(value, list):
+                        answer_str = ", ".join(str(v) for v in value)
+                        # OpenCode expects array of arrays (one per question)
+                        return ToolResult(
+                            content=answer_str,
+                            metadata={
+                                "answers": [value]
+                            },  # Single question, array of selected values
+                        )
+                    # Single answer
+                    answer_str = str(value)
+                    return ToolResult(
+                        content=answer_str,
+                        metadata={"answers": [[answer_str]]},  # Single question, single answer
+                    )
+                # Fallback for plain content
+                answer_str = str(content)
+                return ToolResult(
+                    content=answer_str,
+                    metadata={"answers": [[answer_str]]},
+                )
+            case ElicitResult(action="cancel"):
+                return ToolResult(
+                    content="User cancelled the request",
+                    metadata={"answers": []},
+                )
+            case ElicitResult():
+                return ToolResult(
+                    content="User declined to answer",
+                    metadata={"answers": []},
+                )
+            case ErrorData(message=message):
+                return ToolResult(
+                    content=f"Error: {message}",
+                    metadata={"answers": []},
+                )
+            case _ as unreachable:
+                assert_never(unreachable)