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

agentpool/tool_impls/agent_cli/tool.py

@@ -0,0 +1,95 @@
+"""AgentCli tool implementation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from io import StringIO
+from typing import TYPE_CHECKING
+
+from agentpool.agents.context import AgentContext  # noqa: TC001
+from agentpool.tools.base import Tool
+
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+
+class _StringOutputWriter:
+    """Output writer that captures output to a string buffer."""
+
+    def __init__(self) -> None:
+        self._buffer = StringIO()
+
+    async def print(self, message: str) -> None:
+        """Write a message to the buffer."""
+        self._buffer.write(message)
+        self._buffer.write("\n")
+
+    def getvalue(self) -> str:
+        """Get the captured output."""
+        return self._buffer.getvalue()
+
+
+@dataclass
+class AgentCliTool(Tool[str]):
+    """Tool for executing internal agent management commands.
+
+    Provides access to the agent's internal CLI for management operations
+    like creating agents, managing tools, connecting nodes, etc.
+    """
+
+    def get_callable(self) -> Callable[..., Awaitable[str]]:
+        """Get the tool callable."""
+        return self._execute
+
+    async def _execute(self, ctx: AgentContext, command: str) -> str:
+        """Execute an internal agent management command.
+
+        This provides access to the agent's internal CLI for management operations.
+
+        IMPORTANT: Before using any command for the first time, call "help <command>"
+        to learn the correct syntax and available options.
+
+        Discovery commands:
+        - "help" - list all available commands
+        - "help <command>" - get detailed usage for a specific command
+
+        Command categories:
+        - Agent/team management: create-agent, create-team, list-agents
+        - Tool management: list-tools, register-tool, enable-tool, disable-tool
+        - MCP servers: add-mcp-server, add-remote-mcp-server, list-mcp-servers
+        - Connections: connect, disconnect, connections
+        - Workers: add-worker, remove-worker, list-workers
+
+        Args:
+            ctx: Agent execution context.
+            command: The command to execute. Leading slash is optional.
+
+        Returns:
+            Command output or error message.
+        """
+        from slashed import CommandContext
+
+        if not ctx.agent.command_store:
+            return "No command store available"
+
+        # Remove leading slash if present
+        cmd = command.lstrip("/")
+
+        # Create output capture
+        output = _StringOutputWriter()
+
+        # Create CommandContext with output capture and AgentContext as data
+        cmd_ctx = CommandContext(
+            output=output,
+            data=ctx,
+            command_store=ctx.agent.command_store,
+        )
+
+        try:
+            await ctx.agent.command_store.execute_command(cmd, cmd_ctx)
+            result = output.getvalue()
+        except Exception as e:  # noqa: BLE001
+            return f"Command failed: {e}"
+        else:
+            return result if result else "Command executed successfully."

agentpool/tool_impls/bash/__init__.py

@@ -0,0 +1,64 @@
+"""Bash command execution tool."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from agentpool.tool_impls.bash.tool import BashTool
+from agentpool_config.tools import ToolHints
+
+
+if TYPE_CHECKING:
+    from exxec import ExecutionEnvironment
+
+__all__ = ["BashTool", "create_bash_tool"]
+
+# Tool metadata defaults
+NAME = "bash"
+DESCRIPTION = "Execute a shell command and return the output."
+CATEGORY: Literal["execute"] = "execute"
+HINTS = ToolHints(open_world=True)
+
+
+def create_bash_tool(
+    *,
+    env: ExecutionEnvironment | None = None,
+    output_limit: int | None = None,
+    timeout: float | None = None,
+    name: str = NAME,
+    description: str = DESCRIPTION,
+    requires_confirmation: bool = False,
+) -> BashTool:
+    """Create a configured BashTool instance.
+
+    Args:
+        env: Execution environment to use. Falls back to agent.env if not set.
+        output_limit: Default maximum bytes of output to return.
+        timeout: Default command timeout in seconds. None means no timeout.
+        name: Tool name override.
+        description: Tool description override.
+        requires_confirmation: Whether tool execution needs confirmation.
+
+    Returns:
+        Configured BashTool instance.
+
+    Example:
+        # Basic
+        bash = create_bash_tool()
+
+        # With limits
+        bash = create_bash_tool(output_limit=10000, timeout=30.0)
+
+        # Require confirmation for dangerous commands
+        bash = create_bash_tool(requires_confirmation=True)
+    """
+    return BashTool(
+        name=name,
+        description=description,
+        category=CATEGORY,
+        hints=HINTS,
+        env=env,
+        output_limit=output_limit,
+        timeout=timeout,
+        requires_confirmation=requires_confirmation,
+    )

agentpool/tool_impls/bash/helpers.py

@@ -0,0 +1,35 @@
+"""Helper functions for bash tool output formatting."""
+
+from __future__ import annotations
+
+
+def truncate_output(output: str, limit: int) -> tuple[str, bool]:
+    """Truncate output to limit bytes, returning (output, was_truncated)."""
+    if len(output.encode()) <= limit:
+        return output, False
+    truncated = output.encode()[-limit:].decode(errors="ignore")
+    return f"...[truncated]\n{truncated}", True
+
+
+def format_output(
+    stdout: str,
+    stderr: str,
+    exit_code: int | None,
+    truncated: bool,
+) -> str:
+    """Format the final output string."""
+    # Combine stdout and stderr
+    output = stdout
+    if stderr:
+        output = f"{stdout}\n\nSTDERR:\n{stderr}" if stdout else f"STDERR:\n{stderr}"
+
+    # Add metadata only when relevant
+    suffix_parts = []
+    if truncated:
+        suffix_parts.append("[output truncated]")
+    if exit_code and exit_code != 0:
+        suffix_parts.append(f"Exit code: {exit_code}")
+
+    if suffix_parts:
+        return f"{output}\n\n{' | '.join(suffix_parts)}"
+    return output

agentpool/tool_impls/bash/tool.py

@@ -0,0 +1,171 @@
+"""Bash command execution tool."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from typing import TYPE_CHECKING
+import uuid
+
+from exxec.events import (
+    OutputEvent,
+    ProcessCompletedEvent,
+    ProcessErrorEvent,
+    ProcessStartedEvent,
+)
+
+from agentpool.agents.context import AgentContext  # noqa: TC001
+from agentpool.log import get_logger
+from agentpool.tool_impls.bash.helpers import format_output, truncate_output
+from agentpool.tools.base import Tool, ToolResult
+
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from exxec import ExecutionEnvironment
+
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class BashTool(Tool[ToolResult]):
+    """Execute shell commands and return the output.
+
+    A standalone, configurable tool for running bash commands. Can be configured
+    with a specific execution environment and output limits.
+
+    Use create_bash_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."""
+
+    output_limit: int | None = None
+    """Default maximum bytes of output to return."""
+
+    timeout: float | None = None
+    """Default command timeout in seconds. None means no timeout."""
+
+    def get_callable(self) -> Callable[..., Awaitable[ToolResult]]:
+        """Return the execute method as the callable."""
+        return self._execute
+
+    def _get_env(self, ctx: AgentContext) -> ExecutionEnvironment:
+        """Get execution environment, falling back to agent's env."""
+        if self.env is not None:
+            return self.env
+        return ctx.agent.env
+
+    async def _execute(  # noqa: PLR0915
+        self,
+        ctx: AgentContext,
+        command: str,
+        output_limit: int | None = None,
+        timeout: float | None = None,
+        filter_lines: str | None = None,
+    ) -> ToolResult:
+        """Execute a shell command and return the output.
+
+        Args:
+            ctx: Agent context for event emission and environment access
+            command: Shell command to execute
+            output_limit: Maximum bytes of output to return (overrides default)
+            timeout: Command timeout in seconds (overrides default)
+            filter_lines: Optional regex pattern to filter output lines
+                          (only matching lines returned)
+        """
+        effective_limit = output_limit or self.output_limit
+        effective_timeout = timeout if timeout is not None else self.timeout
+        process_id: str | None = None
+        stdout_parts: list[str] = []
+        stderr_parts: list[str] = []
+        exit_code: int | None = None
+        error_msg: str | None = None
+        env = self._get_env(ctx)
+
+        # Check if we're running in ACP - terminal streams client-side
+        from exxec.acp_provider import ACPExecutionEnvironment
+
+        is_acp = isinstance(env, ACPExecutionEnvironment)
+
+        try:
+            async for event in env.stream_command(command, timeout=effective_timeout):
+                match event:
+                    case ProcessStartedEvent(process_id=pid, command=cmd):
+                        process_id = pid
+                        await ctx.events.process_started(pid, cmd, success=True)
+                    case OutputEvent(process_id=pid, data=data, stream=stream):
+                        if stream == "stderr":
+                            stderr_parts.append(data)
+                        else:
+                            stdout_parts.append(data)
+                        # Skip progress events for ACP - terminal streams client-side
+                        if not is_acp:
+                            await ctx.events.process_output(pid, data)
+                    case ProcessCompletedEvent(process_id=pid, exit_code=code_):
+                        exit_code = code_
+                        # Skip exit event for ACP - completion handled by FunctionToolResultEvent
+                        if not is_acp:
+                            combined = "".join(stdout_parts) + "".join(stderr_parts)
+                            await ctx.events.process_exit(pid, exit_code, final_output=combined)
+                    case ProcessErrorEvent(error=err, exit_code=code_):
+                        error_msg = err
+                        exit_code = code_
+
+            stdout = "".join(stdout_parts)
+            stderr = "".join(stderr_parts)
+
+            # Apply regex filter if specified
+            if filter_lines:
+                try:
+                    pattern = re.compile(filter_lines)
+                    stdout_lines = [
+                        line for line in stdout.splitlines(keepends=True) if pattern.search(line)
+                    ]
+                    stderr_lines = [
+                        line for line in stderr.splitlines(keepends=True) if pattern.search(line)
+                    ]
+                    stdout = "".join(stdout_lines)
+                    stderr = "".join(stderr_lines)
+                except re.error as regex_err:
+                    error_msg = f"Invalid filter regex: {regex_err}"
+                    return ToolResult(
+                        content=error_msg,
+                        metadata={"output": "", "exit": None, "description": command},
+                    )
+
+            # Apply output limit if specified
+            truncated = False
+            if effective_limit:
+                stdout, stdout_truncated = truncate_output(stdout, effective_limit)
+                stderr, stderr_truncated = truncate_output(stderr, effective_limit)
+                truncated = stdout_truncated or stderr_truncated
+
+            # Format error response
+            if error_msg:
+                output = stdout + stderr if stdout or stderr else ""
+                result_output = f"{output}\n\nError: {error_msg}\nExit code: {exit_code}"
+                return ToolResult(
+                    content=result_output,
+                    metadata={"output": output, "exit": exit_code, "description": command},
+                )
+
+        except Exception as e:  # noqa: BLE001
+            error_id = process_id or f"cmd_{uuid.uuid4().hex[:8]}"
+            await ctx.events.process_started(error_id, command, success=False, error=str(e))
+            error_msg = f"Error executing command: {e}"
+            return ToolResult(
+                content=error_msg,
+                metadata={"output": "", "exit": None, "description": command},
+            )
+
+        # Format success response
+        formatted_output = format_output(stdout, stderr, exit_code, truncated)
+        combined_output = stdout + stderr
+        return ToolResult(
+            content=formatted_output,
+            metadata={"output": combined_output, "exit": exit_code, "description": command},
+        )

agentpool/tool_impls/delete_path/__init__.py

@@ -0,0 +1,70 @@
+"""Delete path tool."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from agentpool.tool_impls.delete_path.tool import DeletePathTool
+from agentpool_config.tools import ToolHints
+
+
+if TYPE_CHECKING:
+    from exxec import ExecutionEnvironment
+
+__all__ = ["DeletePathTool", "create_delete_path_tool"]
+
+# Tool metadata defaults
+NAME = "delete_path"
+DESCRIPTION = """Delete a file or directory from the filesystem.
+
+Supports:
+- File deletion
+- Directory deletion with safety checks
+- Recursive directory deletion
+- Empty directory validation"""
+CATEGORY: Literal["delete"] = "delete"
+HINTS = ToolHints(destructive=True)
+
+
+def create_delete_path_tool(
+    *,
+    env: ExecutionEnvironment | None = None,
+    cwd: str | None = None,
+    name: str = NAME,
+    description: str = DESCRIPTION,
+    requires_confirmation: bool = False,
+) -> DeletePathTool:
+    """Create a configured DeletePathTool instance.
+
+    Args:
+        env: Execution environment to use. Falls back to agent.env if not set.
+        cwd: Working directory for resolving relative paths.
+        name: Tool name override.
+        description: Tool description override.
+        requires_confirmation: Whether tool execution needs confirmation.
+
+    Returns:
+        Configured DeletePathTool instance.
+
+    Example:
+        # Basic usage
+        delete = create_delete_path_tool()
+
+        # With confirmation required for safety
+        delete = create_delete_path_tool(requires_confirmation=True)
+
+        # With specific environment
+        delete = create_delete_path_tool(
+            env=my_env,
+            cwd="/workspace",
+        )
+    """
+    return DeletePathTool(
+        name=name,
+        description=description,
+        category=CATEGORY,
+        hints=HINTS,
+        env=env,
+        cwd=cwd,
+        requires_confirmation=requires_confirmation,
+    )

agentpool/tool_impls/delete_path/tool.py

@@ -0,0 +1,142 @@
+"""Delete path tool implementation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+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
+
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from exxec import ExecutionEnvironment
+    from fsspec.asyn import AsyncFileSystem
+
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class DeletePathTool(Tool[dict[str, Any]]):
+    """Delete files or directories from the filesystem.
+
+    A standalone tool for deleting paths with:
+    - File and directory deletion
+    - Recursive directory deletion with safety checks
+    - Empty directory validation
+    - Detailed operation results
+
+    Use create_delete_path_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."""
+
+    def get_callable(self) -> Callable[..., Awaitable[dict[str, Any]]]:
+        """Return the delete_path method as the callable."""
+        return self._delete_path
+
+    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 _delete_path(
+        self,
+        ctx: AgentContext,
+        path: str,
+        recursive: bool = False,
+    ) -> dict[str, Any]:
+        """Delete a file or directory.
+
+        Args:
+            ctx: Agent context for event emission and filesystem access
+            path: Path to delete
+            recursive: Whether to delete directories recursively
+
+        Returns:
+            Dictionary with operation result
+        """
+        path = self._resolve_path(path, ctx)
+        msg = f"Deleting path: {path}"
+        await ctx.events.tool_call_start(title=msg, kind="delete", locations=[path])
+
+        try:
+            # Check if path exists and get its type
+            fs = self._get_fs(ctx)
+            try:
+                info = await fs._info(path)
+                path_type = info.get("type", "unknown")
+            except FileNotFoundError:
+                msg = f"Path does not exist: {path}"
+                await ctx.events.file_operation("delete", path=path, success=False, error=msg)
+                return {"error": msg}
+            except (OSError, ValueError) as e:
+                msg = f"Could not check path {path}: {e}"
+                await ctx.events.file_operation("delete", path=path, success=False, error=msg)
+                return {"error": msg}
+
+            if path_type == "directory":
+                if not recursive:
+                    try:
+                        contents = await fs._ls(path)
+                        if contents:  # Check if directory is empty
+                            error_msg = (
+                                f"Directory {path} is not empty. "
+                                f"Use recursive=True to delete non-empty directories"
+                            )
+
+                            # Emit failure event
+                            await ctx.events.file_operation(
+                                "delete", path=path, success=False, error=error_msg
+                            )
+
+                            return {"error": error_msg}
+                    except (OSError, ValueError):
+                        pass  # Continue with deletion attempt
+
+                await fs._rm(path, recursive=recursive)
+            else:  # It's a file
+                await fs._rm(path)
+
+        except Exception as e:  # noqa: BLE001
+            await ctx.events.file_operation("delete", path=path, success=False, error=str(e))
+            return {"error": f"Failed to delete {path}: {e}"}
+        else:
+            result = {
+                "path": path,
+                "deleted": True,
+                "type": path_type,
+                "recursive": recursive,
+            }
+            await ctx.events.file_operation("delete", path=path, success=True)
+            return result

agentpool/tool_impls/download_file/__init__.py

@@ -0,0 +1,80 @@
+"""Download file tool."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from agentpool.tool_impls.download_file.tool import DownloadFileTool
+from agentpool_config.tools import ToolHints
+
+
+if TYPE_CHECKING:
+    from exxec import ExecutionEnvironment
+
+__all__ = ["DownloadFileTool", "create_download_file_tool"]
+
+# Tool metadata defaults
+NAME = "download_file"
+DESCRIPTION = """Download a file from a URL to the filesystem.
+
+Supports:
+- HTTP/HTTPS downloads
+- Progress tracking
+- Speed monitoring
+- Automatic directory creation
+- Configurable chunk size and timeout"""
+CATEGORY: Literal["read"] = "read"
+HINTS = ToolHints(open_world=True)
+
+
+def create_download_file_tool(
+    *,
+    env: ExecutionEnvironment | None = None,
+    cwd: str | None = None,
+    chunk_size: int = 8192,
+    timeout: float = 30.0,
+    name: str = NAME,
+    description: str = DESCRIPTION,
+    requires_confirmation: bool = False,
+) -> DownloadFileTool:
+    """Create a configured DownloadFileTool instance.
+
+    Args:
+        env: Execution environment to use. Falls back to agent.env if not set.
+        cwd: Working directory for resolving relative paths.
+        chunk_size: Size of chunks to download in bytes (default: 8192).
+        timeout: Request timeout in seconds (default: 30.0).
+        name: Tool name override.
+        description: Tool description override.
+        requires_confirmation: Whether tool execution needs confirmation.
+
+    Returns:
+        Configured DownloadFileTool instance.
+
+    Example:
+        # Basic usage
+        download = create_download_file_tool()
+
+        # With custom settings
+        download = create_download_file_tool(
+            chunk_size=16384,
+            timeout=60.0,
+        )
+
+        # With specific environment
+        download = create_download_file_tool(
+            env=my_env,
+            cwd="/workspace/downloads",
+        )
+    """
+    return DownloadFileTool(
+        name=name,
+        description=description,
+        category=CATEGORY,
+        hints=HINTS,
+        env=env,
+        cwd=cwd,
+        chunk_size=chunk_size,
+        timeout=timeout,
+        requires_confirmation=requires_confirmation,
+    )