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

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,
+    )

agentpool/tool_impls/read/tool.py

@@ -0,0 +1,305 @@
+"""Read file tool implementation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pydantic_ai import BinaryContent
+
+from agentpool.agents.context import AgentContext  # noqa: TC001
+from agentpool.log import get_logger
+from agentpool.mime_utils import guess_type, is_binary_content, is_binary_mime
+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.prompts.conversion_manager import ConversionManager
+
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class ReadTool(Tool[ToolResult]):
+    """Read files from the filesystem with support for text, binary, and image content.
+
+    A standalone tool for reading files with advanced features:
+    - Automatic binary/text detection
+    - Image resizing and compression
+    - Large file handling with structure maps
+    - Line-based partial reads
+    - Multi-encoding support
+
+    Use create_read_tool() factory for convenient instantiation with defaults.
+    """
+
+    # Tool-specific configuration
+    env: ExecutionEnvironment | None = None
+    """Execution environment to use. Falls back to agent.env if not set."""
+
+    converter: ConversionManager | None = None
+    """Optional converter for binary files. If set and supports the file type, returns markdown."""
+
+    cwd: str | None = None
+    """Working directory for resolving relative paths."""
+
+    max_file_size_kb: int = 64
+    """Maximum file size in KB for read operations."""
+
+    max_image_size: int | None = 2000
+    """Max width/height for images in pixels. Images are auto-resized if larger."""
+
+    max_image_bytes: int | None = None
+    """Max file size for images in bytes. Images are compressed if larger."""
+
+    large_file_tokens: int = 12_000
+    """Token threshold for switching to structure map for large files."""
+
+    map_max_tokens: int = 2048
+    """Maximum tokens for structure map output."""
+
+    _repomap = None  # RepoMap instance (lazy-init)
+
+    def get_callable(
+        self,
+    ) -> Callable[..., Awaitable[ToolResult]]:
+        """Return the read method as the callable."""
+        return self._read
+
+    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
+
+        # Priority: env.get_fs() > agent.env.get_fs()
+        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."""
+        # Get cwd: explicit toolset cwd > env.cwd > agent.env.cwd
+        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 _get_file_map(self, path: str, ctx: AgentContext) -> str | None:
+        """Get structure map for a large file if language is supported."""
+        from agentpool.repomap import RepoMap, is_language_supported
+
+        if not is_language_supported(path):
+            return None
+
+        # Lazy init repomap - use file's directory as root
+        if self._repomap is None:
+            root = str(Path(path).parent)
+            fs = self._get_fs(ctx)
+            self._repomap = RepoMap(fs, root, max_tokens=self.map_max_tokens)
+
+        return await self._repomap.get_file_map(path, max_tokens=self.map_max_tokens)
+
+    async def _read(  # noqa: PLR0911, PLR0915
+        self,
+        ctx: AgentContext,
+        path: str,
+        encoding: str = "utf-8",
+        line: int | None = None,
+        limit: int | None = None,
+    ) -> ToolResult:
+        """Read the content of a text file, or use vision capabilities to read images or documents.
+
+        Args:
+            ctx: Agent context for event emission and filesystem access
+            path: File path to read
+            encoding: Text encoding to use for text files (default: utf-8)
+            line: Optional line number to start reading from (1-based, text files only)
+            limit: Optional maximum number of lines to read (text files only)
+
+        Returns:
+            Text content for text files, BinaryContent for binary files (with optional
+            dimension note as list when image was resized), or error string
+        """
+        path = self._resolve_path(path, ctx)
+        msg = f"Reading file: {path}"
+        from agentpool.agents.events import LocationContentItem
+
+        # Emit progress - use 0 for line if negative (can't resolve until we read file)
+        # LocationContentItem/ToolCallLocation require line >= 0 per ACP spec
+        display_line = line if (line is not None and line > 0) else 0
+        await ctx.events.tool_call_progress(
+            title=msg,
+            items=[LocationContentItem(path=path, line=display_line)],
+        )
+
+        max_file_size = self.max_file_size_kb * 1024
+
+        try:
+            mime_type = guess_type(path)
+            # Fast path: known binary MIME types (images, audio, video, etc.)
+            if is_binary_mime(mime_type):
+                # Try converter first if available
+                if self.converter is not None:
+                    try:
+                        content = await self.converter.convert_file(path)
+                        await ctx.events.file_operation("read", path=path, success=True)
+                    except Exception:  # noqa: BLE001
+                        # Converter doesn't support this file type, fall back to binary
+                        pass
+                    else:
+                        # Converter returned markdown
+                        lines = content.splitlines()
+                        preview = "\n".join(lines[:20])
+                        return ToolResult(
+                            content=content,
+                            metadata={"preview": preview, "truncated": False},
+                        )
+
+                # Fall back to native binary handling
+                data = await self._get_fs(ctx)._cat_file(path)
+                await ctx.events.file_operation("read", path=path, success=True)
+                mime = mime_type or "application/octet-stream"
+                # Resize images if needed
+                if self.max_image_size and mime.startswith("image/"):
+                    from agentpool_toolsets.fsspec_toolset.image_utils import (
+                        resize_image_if_needed,
+                    )
+
+                    data, mime, note = resize_image_if_needed(
+                        data, mime, self.max_image_size, self.max_image_bytes
+                    )
+                    if note:
+                        # Return resized image with dimension note for coordinate mapping
+                        return ToolResult(
+                            content=[
+                                note,
+                                BinaryContent(data=data, media_type=mime, identifier=path),
+                            ],
+                            metadata={"preview": "Image read successfully", "truncated": False},
+                        )
+                return ToolResult(
+                    content=[BinaryContent(data=data, media_type=mime, identifier=path)],
+                    metadata={"preview": "Binary file read successfully", "truncated": False},
+                )
+
+            # Read content and probe for binary (git-style null byte detection)
+            data = await self._get_fs(ctx)._cat_file(path)
+            if is_binary_content(data):
+                # Try converter first if available
+                if self.converter is not None:
+                    try:
+                        content = await self.converter.convert_file(path)
+                        await ctx.events.file_operation("read", path=path, success=True)
+                    except Exception:  # noqa: BLE001
+                        # Converter doesn't support this file type, fall back to binary
+                        pass
+                    else:
+                        # Converter returned markdown
+                        lines = content.splitlines()
+                        preview = "\n".join(lines[:20])
+                        return ToolResult(
+                            content=content,
+                            metadata={"preview": preview, "truncated": False},
+                        )
+
+                # Fall back to native binary handling
+                await ctx.events.file_operation("read", path=path, success=True)
+                mime = mime_type or "application/octet-stream"
+                # Resize images if needed
+                if self.max_image_size and mime.startswith("image/"):
+                    from agentpool_toolsets.fsspec_toolset.image_utils import (
+                        resize_image_if_needed,
+                    )
+
+                    data, mime, note = resize_image_if_needed(
+                        data, mime, self.max_image_size, self.max_image_bytes
+                    )
+                    if note:
+                        return ToolResult(
+                            content=[
+                                note,
+                                BinaryContent(data=data, media_type=mime, identifier=path),
+                            ],
+                            metadata={"preview": "Image read successfully", "truncated": False},
+                        )
+                return ToolResult(
+                    content=[BinaryContent(data=data, media_type=mime, identifier=path)],
+                    metadata={"preview": "Binary file read successfully", "truncated": False},
+                )
+
+            content = data.decode(encoding)
+
+            # Check if file is too large and no targeted read requested
+            tokens_approx = len(content) // 4
+            if line is None and limit is None and tokens_approx > self.large_file_tokens:
+                # Try structure map for supported languages
+                map_result = await self._get_file_map(path, ctx)
+                if map_result:
+                    await ctx.events.file_operation("read", path=path, success=True)
+                    content = map_result
+                else:
+                    # Fallback: head + tail for unsupported languages
+                    from agentpool.repomap import truncate_with_notice
+
+                    content = truncate_with_notice(path, content)
+                    await ctx.events.file_operation("read", path=path, success=True)
+            else:
+                # Normal read with optional offset/limit
+                from agentpool_toolsets.fsspec_toolset.helpers import truncate_lines
+
+                lines = content.splitlines()
+                offset = (line - 1) if line else 0
+                result_lines, was_truncated = truncate_lines(lines, offset, limit, max_file_size)
+                content = "\n".join(result_lines)
+                # Don't pass negative line numbers to events (ACP requires >= 0)
+                display_line = line if (line and line > 0) else 0
+                await ctx.events.file_operation("read", path=path, success=True, line=display_line)
+                if was_truncated:
+                    content += f"\n\n[Content truncated at {max_file_size} bytes]"
+
+        except Exception as e:  # noqa: BLE001
+            await ctx.events.file_operation("read", path=path, success=False, error=str(e))
+            error_msg = f"error: Failed to read file {path}: {e}"
+            return ToolResult(
+                content=error_msg,
+                metadata={"preview": "", "truncated": False},
+            )
+        else:
+            # Emit file content for UI display (formatted at ACP layer)
+            from agentpool.agents.events import FileContentItem
+
+            # Use non-negative line for display (negative lines are internal Python convention)
+            display_start_line = max(1, line) if line and line > 0 else None
+            await ctx.events.tool_call_progress(
+                title=f"Read: {path}",
+                items=[FileContentItem(content=content, path=path, start_line=display_start_line)],
+                replace_content=True,
+            )
+
+            # Prepare metadata for OpenCode UI
+            lines = content.splitlines()
+            preview = "\n".join(lines[:20])
+            # Check if content was truncated
+            was_truncated = "[Content truncated" in content
+
+            # Return result with metadata
+            return ToolResult(
+                content=content,
+                metadata={"preview": preview, "truncated": was_truncated},
+            )

agentpool/tools/__init__.py

@@ -2,12 +2,13 @@
 
 from __future__ import annotations
 
-from agentpool.tools.base import Tool
+from agentpool.tools.base import FunctionTool, Tool
 from agentpool.tools.manager import ToolManager, ToolError
 from agentpool.tools.tool_call_info import ToolCallInfo
 from agentpool.skills.registry import SkillsRegistry
 
 __all__ = [
+    "FunctionTool",
     "SkillsRegistry",
     "Tool",
     "ToolCallInfo",

agentpool/tools/base.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from abc import abstractmethod
 from dataclasses import dataclass, field
 import inspect
 from typing import TYPE_CHECKING, Any, Literal
@@ -24,12 +25,12 @@ if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable
 
     from mcp.types import Tool as MCPTool
+    from pydantic_ai import UserContent
     from schemez import FunctionSchema, Property
 
     from agentpool.common_types import ToolSource
     from agentpool.tools.manager import ToolState
 
-
 logger = get_logger(__name__)
 ToolKind = Literal[
     "read",
@@ -46,11 +47,31 @@ ToolKind = Literal[
 
 
 @dataclass
-class Tool[TOutputType = Any]:
-    """Information about a registered tool."""
+class ToolResult:
+    """Structured tool result with content for LLM and metadata for UI.
+
+    This abstraction allows tools to return rich data that gets converted to
+    agent-specific formats (pydantic-ai ToolReturn, FastMCP ToolResult, etc.).
+
+    Attributes:
+        content: What the LLM sees - can be string or list of content blocks
+        structured_content: Machine-readable JSON data (optional)
+        metadata: UI/application data that is NOT sent to the LLM
+    """
+
+    content: str | list[UserContent]
+    """Content sent to the LLM (text, images, etc.)"""
 
-    callable: Callable[..., TOutputType]
-    """The actual tool implementation"""
+    structured_content: dict[str, Any] | None = None
+    """Structured JSON data for programmatic access (optional)"""
+
+    metadata: dict[str, Any] | None = None
+    """Metadata for UI/app use - NOT sent to LLM (diffs, diagnostics, etc.)."""
+
+
+@dataclass
+class Tool[TOutputType = Any]:
+    """Base class for tools. Subclass and implement get_callable() or use FunctionTool."""
 
     name: str
     """The name of the tool."""
@@ -87,14 +108,17 @@ class Tool[TOutputType = Any]:
 
     __repr__ = dataclasses_no_defaults_repr
 
+    @abstractmethod
+    def get_callable(self) -> Callable[..., TOutputType | Awaitable[TOutputType]]:
+        """Get the callable for this tool. Subclasses must implement."""
+        ...
+
     def to_pydantic_ai(self) -> PydanticAiTool:
         """Convert tool to Pydantic AI tool."""
         metadata = {**self.metadata, "agent_name": self.agent_name, "category": self.category}
         return PydanticAiTool(
-            function=self.callable,
+            function=self.get_callable(),
             name=self.name,
-            # takes_ctx=self.takes_ctx,
-            # max_retries=self.max_retries,
             description=self.description,
             requires_approval=self.requires_confirmation,
             metadata=metadata,
@@ -108,7 +132,7 @@ class Tool[TOutputType = Any]:
         from agentpool.agents.context import AgentContext
 
         return schemez.create_schema(
-            self.callable,
+            self.get_callable(),
             name_override=self.name,
             description_override=self.description,
             exclude_types=[AgentContext, RunContext],
@@ -165,7 +189,22 @@ class Tool[TOutputType = Any]:
     @logfire.instrument("Executing tool {self.name} with args={args}, kwargs={kwargs}")
     async def execute(self, *args: Any, **kwargs: Any) -> Any:
         """Execute tool, handling both sync and async cases."""
-        return await execute(self.callable, *args, **kwargs, use_thread=True)
+        return await execute(self.get_callable(), *args, **kwargs, use_thread=True)
+
+    async def execute_and_unwrap(self, *args: Any, **kwargs: Any) -> Any:
+        """Execute tool and unwrap ToolResult if present.
+
+        This is a convenience method for tests and direct tool usage that want
+        plain content instead of ToolResult objects.
+
+        Returns:
+            If tool returns ToolResult, returns ToolResult.content.
+            Otherwise returns the raw result.
+        """
+        result = await self.execute(*args, **kwargs)
+        if isinstance(result, ToolResult):
+            return result.content
+        return result
 
     @classmethod
     def from_code(
@@ -173,15 +212,74 @@ class Tool[TOutputType = Any]:
         code: str,
         name: str | None = None,
         description: str | None = None,
-    ) -> Tool[Any]:
-        """Create a tool from a code string."""
+    ) -> FunctionTool[Any]:
+        """Create a FunctionTool from a code string."""
         namespace: dict[str, Any] = {}
         exec(code, namespace)
         func = next((v for v in namespace.values() if callable(v)), None)
         if not func:
             msg = "No callable found in provided code"
             raise ValueError(msg)
-        return cls.from_callable(func, name_override=name, description_override=description)  # pyright: ignore[reportArgumentType]
+        return FunctionTool.from_callable(
+            func, name_override=name, description_override=description
+        )
+
+    @classmethod
+    def from_callable(
+        cls,
+        fn: Callable[..., TOutputType | Awaitable[TOutputType]] | str,
+        *,
+        name_override: str | None = None,
+        description_override: str | None = None,
+        schema_override: schemez.OpenAIFunctionDefinition | None = None,
+        hints: ToolHints | None = None,
+        category: ToolKind | None = None,
+        enabled: bool = True,
+        source: ToolSource | str | None = None,
+        **kwargs: Any,
+    ) -> FunctionTool[TOutputType]:
+        """Create a FunctionTool from a callable or import path."""
+        return FunctionTool.from_callable(
+            fn,
+            name_override=name_override,
+            description_override=description_override,
+            schema_override=schema_override,
+            hints=hints,
+            category=category,
+            enabled=enabled,
+            source=source,
+            **kwargs,
+        )
+
+    def to_mcp_tool(self) -> MCPTool:
+        """Convert internal Tool to MCP Tool."""
+        schema = self.schema
+        from mcp.types import Tool as MCPTool, ToolAnnotations
+
+        return MCPTool(
+            name=schema["function"]["name"],
+            description=schema["function"]["description"],
+            inputSchema=schema["function"]["parameters"],  # pyright: ignore
+            annotations=ToolAnnotations(
+                title=self.name,
+                readOnlyHint=self.hints.read_only if self.hints else None,
+                destructiveHint=self.hints.destructive if self.hints else None,
+                idempotentHint=self.hints.idempotent if self.hints else None,
+                openWorldHint=self.hints.open_world if self.hints else None,
+            ),
+        )
+
+
+@dataclass
+class FunctionTool[TOutputType = Any](Tool[TOutputType]):
+    """Tool wrapping a plain callable function."""
+
+    callable: Callable[..., TOutputType | Awaitable[TOutputType]] = field(default=lambda: None)  # type: ignore[assignment]
+    """The actual tool implementation."""
+
+    def get_callable(self) -> Callable[..., TOutputType | Awaitable[TOutputType]]:
+        """Return the wrapped callable."""
+        return self.callable
 
     @classmethod
     def from_callable(
@@ -196,14 +294,14 @@ class Tool[TOutputType = Any]:
         enabled: bool = True,
         source: ToolSource | str | None = None,
         **kwargs: Any,
-    ) -> Tool[TOutputType]:
+    ) -> FunctionTool[TOutputType]:
+        """Create a FunctionTool from a callable or import path string."""
         if isinstance(fn, str):
             import_path = fn
             from agentpool.utils import importing
 
             callable_obj = importing.import_callable(fn)
             name = getattr(callable_obj, "__name__", "unknown")
-            import_path = fn
         else:
             callable_obj = fn
             module = fn.__module__
@@ -215,9 +313,9 @@ class Tool[TOutputType = Any]:
                 import_path = f"{module}.{fn.__class__.__qualname__}"
 
         return cls(
-            callable=callable_obj,  # pyright: ignore[reportArgumentType]
             name=name_override or name,
             description=description_override or inspect.getdoc(callable_obj) or "",
+            callable=callable_obj,  # pyright: ignore[reportArgumentType]
             import_path=import_path,
             schema_override=schema_override,
             category=category,
@@ -227,24 +325,6 @@ class Tool[TOutputType = Any]:
             **kwargs,
         )
 
-    def to_mcp_tool(self) -> MCPTool:
-        """Convert internal Tool to MCP Tool."""
-        schema = self.schema
-        from mcp.types import Tool as MCPTool, ToolAnnotations
-
-        return MCPTool(
-            name=schema["function"]["name"],
-            description=schema["function"]["description"],
-            inputSchema=schema["function"]["parameters"],  # pyright: ignore
-            annotations=ToolAnnotations(
-                title=self.name,
-                readOnlyHint=self.hints.read_only if self.hints else None,
-                destructiveHint=self.hints.destructive if self.hints else None,
-                idempotentHint=self.hints.idempotent if self.hints else None,
-                openWorldHint=self.hints.open_world if self.hints else None,
-            ),
-        )
-
 
 @dataclass
 class ToolParameter: