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

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)

agentpool/tool_impls/read/__init__.py

@@ -0,0 +1,104 @@
+"""Read file tool."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from agentpool.tool_impls.read.tool import ReadTool
+from agentpool_config.tools import ToolHints
+
+
+if TYPE_CHECKING:
+    from exxec import ExecutionEnvironment
+
+    from agentpool.prompts.conversion_manager import ConversionManager
+
+__all__ = ["ReadTool", "create_read_tool"]
+
+# Tool metadata defaults
+NAME = "read"
+DESCRIPTION = """Read the content of a text file, or use vision capabilities
+to read images or documents.
+
+Supports:
+- Text files with optional line-based partial reads
+- Binary files (images, PDFs, audio, video) returned as BinaryContent
+- Automatic image resizing for better model compatibility
+- Structure maps for large code files
+- Multiple text encodings"""
+CATEGORY: Literal["read"] = "read"
+HINTS = ToolHints(read_only=True, idempotent=True)
+
+
+def create_read_tool(
+    *,
+    env: ExecutionEnvironment | None = None,
+    converter: ConversionManager | None = None,
+    cwd: str | None = None,
+    max_file_size_kb: int = 64,
+    max_image_size: int | None = 2000,
+    max_image_bytes: int | None = None,
+    large_file_tokens: int = 12_000,
+    map_max_tokens: int = 2048,
+    name: str = NAME,
+    description: str = DESCRIPTION,
+    requires_confirmation: bool = False,
+) -> ReadTool:
+    """Create a configured ReadTool instance.
+
+    Args:
+        env: Execution environment to use. Falls back to agent.env if not set.
+        converter: Optional converter for binary files. If set, converts supported
+            file types to markdown instead of returning BinaryContent.
+        cwd: Working directory for resolving relative paths.
+        max_file_size_kb: Maximum file size in KB for read operations (default: 64KB).
+        max_image_size: Max width/height for images in pixels. Larger images are
+            auto-resized. Set to None to disable.
+        max_image_bytes: Max file size for images in bytes. Images exceeding this
+            are compressed. Default: None (uses 4.5MB).
+        large_file_tokens: Token threshold for switching to structure map (default: 12000).
+        map_max_tokens: Maximum tokens for structure map output (default: 2048).
+        name: Tool name override.
+        description: Tool description override.
+        requires_confirmation: Whether tool execution needs confirmation.
+
+    Returns:
+        Configured ReadTool instance.
+
+    Example:
+        # Basic usage
+        read = create_read_tool()
+
+        # With custom limits
+        read = create_read_tool(
+            max_file_size_kb=128,
+            max_image_size=1500,
+        )
+
+        # With specific environment and cwd
+        read = create_read_tool(
+            env=my_env,
+            cwd="/workspace/project",
+        )
+
+        # With converter for automatic markdown conversion
+        from agentpool.prompts.conversion_manager import ConversionManager
+        read = create_read_tool(
+            converter=ConversionManager(),
+        )
+    """
+    return ReadTool(
+        name=name,
+        description=description,
+        category=CATEGORY,
+        hints=HINTS,
+        env=env,
+        converter=converter,
+        cwd=cwd,
+        max_file_size_kb=max_file_size_kb,
+        max_image_size=max_image_size,
+        max_image_bytes=max_image_bytes,
+        large_file_tokens=large_file_tokens,
+        map_max_tokens=map_max_tokens,
+        requires_confirmation=requires_confirmation,
+    )