agentpool 2.1.9__py3-none-any.whl

agentpool_toolsets/builtin/debug.py

@@ -0,0 +1,291 @@
+"""Debug toolset for agent self-introspection and runtime debugging."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+import logging
+from typing import Any, Literal
+
+from pydantic_ai import RunContext  # noqa: TC002
+
+from agentpool.agents.context import AgentContext  # noqa: TC001
+from agentpool.resource_providers import StaticResourceProvider
+
+
+LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+
+@dataclass
+class LogRecord:
+    """A captured log record."""
+
+    level: str
+    logger: str
+    message: str
+    timestamp: str
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+LEVEL_PRIORITY = {
+    "DEBUG": 10,
+    "INFO": 20,
+    "WARNING": 30,
+    "ERROR": 40,
+    "CRITICAL": 50,
+}
+
+
+class MemoryLogHandler(logging.Handler):
+    """A logging handler that stores records in memory for later retrieval."""
+
+    def __init__(self, max_records: int = 1000) -> None:
+        super().__init__()
+        self.max_records = max_records
+        self.records: deque[LogRecord] = deque(maxlen=max_records)
+        self.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s"))
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Store the log record."""
+        log_record = LogRecord(
+            level=record.levelname,
+            logger=record.name,
+            message=self.format(record),
+            timestamp=self.formatter.formatTime(record) if self.formatter else "",
+            extra={k: v for k, v in record.__dict__.items() if k not in logging.LogRecord.__dict__},
+        )
+        self.records.append(log_record)
+
+    def get_records(
+        self,
+        level: LogLevel | None = None,
+        logger_filter: str | None = None,
+        limit: int | None = None,
+    ) -> list[LogRecord]:
+        """Get filtered log records.
+
+        Args:
+            level: Minimum log level to include
+            logger_filter: Only include loggers containing this string
+            limit: Maximum number of records to return (newest first)
+
+        Returns:
+            List of matching log records
+        """
+        min_level = LEVEL_PRIORITY.get(level, 0) if level else 0
+        filtered = []
+        for record in reversed(self.records):
+            if LEVEL_PRIORITY.get(record.level, 0) < min_level:
+                continue
+            if logger_filter and logger_filter not in record.logger:
+                continue
+            filtered.append(record)
+            if limit and len(filtered) >= limit:
+                break
+
+        return filtered
+
+    def clear(self) -> None:
+        """Clear all stored records."""
+        self.records.clear()
+
+
+# Global memory handler instance
+_memory_handler: MemoryLogHandler | None = None
+
+
+def get_memory_handler() -> MemoryLogHandler:
+    """Get or create the global memory log handler."""
+    global _memory_handler  # noqa: PLW0603
+    if _memory_handler is None:
+        _memory_handler = MemoryLogHandler()
+        # Attach to root logger to capture everything
+        logging.getLogger().addHandler(_memory_handler)
+    return _memory_handler
+
+
+def install_memory_handler(max_records: int = 1000) -> MemoryLogHandler:
+    """Install the memory handler if not already installed.
+
+    Args:
+        max_records: Maximum number of records to keep in memory
+
+    Returns:
+        The memory handler instance
+    """
+    global _memory_handler  # noqa: PLW0603
+    if _memory_handler is None:
+        _memory_handler = MemoryLogHandler(max_records=max_records)
+        logging.getLogger().addHandler(_memory_handler)
+    return _memory_handler
+
+
+# =============================================================================
+# Introspection Tool
+# =============================================================================
+
+INTROSPECTION_USAGE = """
+Execute Python code with full access to your runtime context.
+
+Available in namespace:
+- ctx: AgentContext (ctx.agent, ctx.pool, ctx.config, ctx.definition, etc.)
+- run_ctx: pydantic-ai RunContext (current run state)
+- me: Shortcut for ctx.agent (your Agent instance)
+
+You can inspect yourself, the pool, other agents, your tools, and more.
+Write an async main() function that returns the result.
+
+Example - inspect your own tools:
+```python
+async def main():
+    tools = me.tools.list_tools()
+    return [t.name for t in tools]
+```
+
+Example - check pool state:
+```python
+async def main():
+    if ctx.pool:
+        agents = list(ctx.pool.agents.keys())
+        return f"Agents in pool: {agents}"
+    return "No pool available"
+```
+
+Example - explore with dir():
+```python
+async def main():
+    return dir(ctx)
+```
+"""
+
+
+async def execute_introspection(ctx: AgentContext, run_ctx: RunContext[Any], code: str) -> str:  # noqa: D417
+    """Execute Python code with access to your own runtime context.
+
+    This is a debugging/development tool that gives you full access to
+    inspect and interact with your runtime environment.
+
+    Args:
+        code: Python code with async main() function to execute
+
+    Returns:
+        Result of execution or error message
+    """
+    # Build namespace with runtime context
+    namespace: dict[str, Any] = {"ctx": ctx, "run_ctx": run_ctx, "me": ctx.agent}
+    try:
+        exec(code, namespace)
+        if "main" not in namespace:
+            return "Error: Code must define an async main() function"
+        result = await namespace["main"]()
+        return str(result) if result is not None else "Code executed successfully (no return value)"
+    except Exception as e:  # noqa: BLE001
+        return f"Error executing code: {type(e).__name__}: {e}"
+
+
+# =============================================================================
+# Log Tools
+# =============================================================================
+
+
+async def get_logs(
+    level: LogLevel = "INFO",
+    logger_filter: str | None = None,
+    limit: int = 50,
+) -> str:
+    """Get recent log entries from memory.
+
+    Args:
+        level: Minimum log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        logger_filter: Only show logs from loggers containing this string
+        limit: Maximum number of log entries to return
+
+    Returns:
+        Formatted log entries
+    """
+    handler = get_memory_handler()
+    records = handler.get_records(level=level, logger_filter=logger_filter, limit=limit)
+
+    if not records:
+        return "No log entries found matching criteria"
+
+    lines = [f"=== {len(records)} log entries (newest first) ===\n"]
+    for record in records:
+        lines.append(record.message)  # noqa: PERF401
+
+    return "\n".join(lines)
+
+
+async def clear_logs() -> str:
+    """Clear all captured log entries from memory.
+
+    Returns:
+        Confirmation message
+    """
+    handler = get_memory_handler()
+    count = len(handler.records)
+    handler.clear()
+    return f"Cleared {count} log entries"
+
+
+# =============================================================================
+# Path Tools
+# =============================================================================
+
+
+async def get_platform_paths() -> str:
+    """Get platform-specific paths for agentpool.
+
+    Returns:
+        Dictionary of platform paths
+    """
+    import platformdirs
+
+    paths = {
+        "config": platformdirs.user_config_dir("agentpool"),
+        "data": platformdirs.user_data_dir("agentpool"),
+        "cache": platformdirs.user_cache_dir("agentpool"),
+        "logs": platformdirs.user_log_dir("agentpool"),
+        "state": platformdirs.user_state_dir("agentpool"),
+    }
+
+    lines = ["Platform paths for agentpool:", ""]
+    for name, path in paths.items():
+        lines.append(f"  {name}: {path}")
+
+    return "\n".join(lines)
+
+
+# =============================================================================
+# Toolset Class
+# =============================================================================
+
+
+class DebugTools(StaticResourceProvider):
+    """Debug and introspection tools for agent development.
+
+    Provides tools for:
+    - Self-introspection via code execution with runtime context access
+    - Log inspection and management
+    - Platform path discovery
+    """
+
+    def __init__(self, name: str = "debug", install_log_handler: bool = True) -> None:
+        """Initialize debug tools.
+
+        Args:
+            name: Toolset name/namespace
+            install_log_handler: Whether to install the memory log handler
+        """
+        super().__init__(name=name)
+
+        if install_log_handler:
+            install_memory_handler()
+
+        desc = (execute_introspection.__doc__ or "") + "\n\n" + INTROSPECTION_USAGE
+        self._tools = [
+            self.create_tool(execute_introspection, category="other", description_override=desc),
+            self.create_tool(get_logs, category="other", read_only=True, idempotent=True),
+            self.create_tool(clear_logs, category="other"),
+            self.create_tool(get_platform_paths, category="other", read_only=True, idempotent=True),
+        ]

agentpool_toolsets/builtin/execution_environment.py

@@ -0,0 +1,381 @@
+"""Provider for execution environment tools with event emission."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+import uuid
+
+from exxec.events import OutputEvent, ProcessCompletedEvent, ProcessErrorEvent, ProcessStartedEvent
+
+from agentpool import log
+from agentpool.agents.context import AgentContext  # noqa: TC001
+from agentpool.resource_providers import ResourceProvider
+
+
+logger = log.get_logger(__name__)
+
+
+if TYPE_CHECKING:
+    from exxec import ExecutionEnvironment
+
+    from agentpool.tools.base import Tool
+
+
+class ExecutionEnvironmentTools(ResourceProvider):
+    """Provider for execution environment tools.
+
+    Combines code execution and process management capabilities
+    using any ExecutionEnvironment backend. Emits events via AgentContext.
+
+    NOTE: The ACP execution environment used handles the Terminal events of the protocol,
+    the toolset should deal with the ToolCall events for UI display purposes.
+    """
+
+    def __init__(self, env: ExecutionEnvironment | None = None, name: str = "execution") -> None:
+        """Initialize execution environment toolset.
+
+        Args:
+            env: Execution environment to use (defaults to LocalExecutionEnvironment)
+            name: The name of the toolset
+        """
+        super().__init__(name=name)
+        self._env = env
+
+    def get_env(self, agent_ctx: AgentContext) -> ExecutionEnvironment:
+        """Get execution environment, falling back to agent's env if not set.
+
+        Args:
+            agent_ctx: Agent context to get fallback env from
+        """
+        if self._env is not None:
+            return self._env
+        return agent_ctx.agent.env
+
+    async def get_tools(self) -> list[Tool]:
+        return [
+            # Code execution tools
+            self.create_tool(self.execute_code, category="execute"),
+            self.create_tool(self.execute_command, category="execute", open_world=True),
+            # Process management tools
+            self.create_tool(self.start_process, category="execute", open_world=True),
+            self.create_tool(
+                self.get_process_output, category="execute", read_only=True, idempotent=True
+            ),
+            self.create_tool(
+                self.wait_for_process, category="execute", read_only=True, idempotent=True
+            ),
+            self.create_tool(self.kill_process, category="execute", destructive=True),
+            self.create_tool(self.release_process, category="execute"),
+            self.create_tool(
+                self.list_processes, category="search", read_only=True, idempotent=True
+            ),
+        ]
+
+    async def execute_code(self, agent_ctx: AgentContext, code: str) -> dict[str, Any]:  # noqa: D417
+        """Execute Python code and return the result.
+
+        Args:
+            code: Python code to execute
+        """
+        process_id: str | None = None
+        output_parts: list[str] = []
+        exit_code: int | None = None
+        error_msg: str | None = None
+        duration: float | None = None
+        try:
+            async for event in self.get_env(agent_ctx).stream_code(code):
+                match event:
+                    case ProcessStartedEvent(process_id=pid, command=cmd):
+                        process_id = pid  # save for later on.
+                        await agent_ctx.events.process_started(pid, cmd, success=True)
+                    case OutputEvent(data=data):
+                        output_parts.append(data)
+                        if process_id:
+                            await agent_ctx.events.process_output(process_id, data)
+                    case ProcessCompletedEvent(exit_code=code_, duration=dur):
+                        exit_code = code_
+                        duration = dur
+                        out = "".join(output_parts)
+                        if process_id:
+                            await agent_ctx.events.process_exit(
+                                process_id, exit_code, final_output=out
+                            )
+                    case ProcessErrorEvent(error=err, exit_code=code_):
+                        error_msg = err
+                        exit_code = code_
+                        if process_id:
+                            await agent_ctx.events.process_exit(
+                                process_id, exit_code or 1, final_output=err
+                            )
+
+            combined_output = "".join(output_parts)
+            if error_msg:
+                return {"error": error_msg, "output": combined_output, "exit_code": exit_code}
+
+        except Exception as e:  # noqa: BLE001
+            error_id = process_id or f"code_{uuid.uuid4().hex[:8]}"
+            await agent_ctx.events.process_started(
+                error_id, "execute_code", success=False, error=str(e)
+            )
+            return {"error": f"Error executing code: {e}"}
+        else:
+            return {"output": combined_output, "exit_code": exit_code, "duration": duration}
+
+    async def execute_command(  # noqa: PLR0915, D417
+        self,
+        agent_ctx: AgentContext,
+        command: str,
+        output_limit: int | None = None,
+    ) -> dict[str, Any]:
+        """Execute a shell command and return the output.
+
+        Args:
+            command: Shell command to execute
+            output_limit: Maximum bytes of output to return
+        """
+        # process_id comes from exxec events (is terminal_id when using ACP)
+        process_id: str | None = None
+        stdout_parts: list[str] = []
+        stderr_parts: list[str] = []
+        exit_code: int | None = None
+        error_msg: str | None = None
+        duration: float | None = None
+        try:
+            async for event in self.get_env(agent_ctx).stream_command(command):
+                match event:
+                    case ProcessStartedEvent(process_id=pid, command=cmd):
+                        process_id = pid
+                        if pid:
+                            await agent_ctx.events.process_started(pid, cmd, success=True)
+                        else:
+                            logger.warning("ProcessStartedEvent missing process_id", command=cmd)
+                    case OutputEvent(process_id=pid, data=data, stream=stream):
+                        if stream == "stderr":
+                            stderr_parts.append(data)
+                        else:
+                            stdout_parts.append(data)
+                        if pid:
+                            await agent_ctx.events.process_output(pid, data)
+                        else:
+                            logger.warning("OutputEvent missing process_id", stream=stream)
+                    case ProcessCompletedEvent(process_id=pid, exit_code=code_, duration=dur):
+                        exit_code = code_
+                        duration = dur
+                        combined = "".join(stdout_parts) + "".join(stderr_parts)
+                        if pid:
+                            await agent_ctx.events.process_exit(
+                                pid, exit_code, final_output=combined
+                            )
+                        else:
+                            msg = "ProcessCompletedEvent missing process_id,"
+                            logger.warning(msg, exit_code=code_)
+                    case ProcessErrorEvent(process_id=pid, error=err, exit_code=code_):
+                        error_msg = err
+                        exit_code = code_
+
+            stdout = "".join(stdout_parts)
+            stderr = "".join(stderr_parts)
+            # Apply output limit if specified
+            truncated = False
+            if output_limit:
+                if len(stdout.encode()) > output_limit:
+                    out = stdout.encode()[-output_limit:].decode(errors="ignore")
+                    stdout = "...[truncated]\n" + out
+                    truncated = True
+                if len(stderr.encode()) > output_limit:
+                    out = stderr.encode()[-output_limit:].decode(errors="ignore")
+                    stderr = "...[truncated]\n" + out
+                    truncated = True
+            if error_msg:
+                return {
+                    "error": error_msg,
+                    "stdout": stdout,
+                    "stderr": stderr,
+                    "exit_code": exit_code,
+                }
+        except Exception as e:  # noqa: BLE001
+            # Use process_id from events if available, otherwise generate fallback
+            error_id = process_id or f"cmd_{uuid.uuid4().hex[:8]}"
+            await agent_ctx.events.process_started(error_id, command, success=False, error=str(e))
+            return {"success": False, "error": f"Error executing command: {e}"}
+        else:
+            return {
+                "stdout": stdout,
+                "stderr": stderr,
+                "exit_code": exit_code,
+                "duration": duration,
+                "truncated": truncated,
+            }
+
+    async def start_process(  # noqa: D417
+        self,
+        agent_ctx: AgentContext,
+        command: str,
+        args: list[str] | None = None,
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+        output_limit: int | None = None,
+    ) -> dict[str, Any]:
+        """Start a command in the background and return process ID.
+
+        Args:
+            command: Command to execute
+            args: Command arguments
+            cwd: Working directory
+            env: Environment variables (added to current env)
+            output_limit: Maximum bytes of output to retain
+        """
+        manager = self.get_env(agent_ctx).process_manager
+        try:
+            process_id = await manager.start_process(
+                command=command,
+                args=args,
+                cwd=cwd,
+                env=env,
+                output_limit=output_limit,
+            )
+            await agent_ctx.events.process_started(process_id, command, success=True)
+
+        except Exception as e:  # noqa: BLE001
+            await agent_ctx.events.process_started("", command, success=False, error=str(e))
+            return {"error": f"Failed to start process: {e}"}
+        else:
+            return {
+                "process_id": process_id,
+                "command": command,
+                "args": args or [],
+                "cwd": cwd,
+                "status": "started",
+            }
+
+    async def get_process_output(self, agent_ctx: AgentContext, process_id: str) -> dict[str, Any]:  # noqa: D417
+        """Get current output from a background process.
+
+        Args:
+            process_id: Process identifier from start_process
+        """
+        manager = self.get_env(agent_ctx).process_manager
+        try:
+            output = await manager.get_output(process_id)
+            await agent_ctx.events.process_output(process_id, output.combined or "")
+            result: dict[str, Any] = {
+                "process_id": process_id,
+                "stdout": output.stdout or "",
+                "stderr": output.stderr or "",
+                "combined": output.combined or "",
+                "truncated": output.truncated,
+            }
+            if output.exit_code is not None:
+                result["exit_code"] = output.exit_code
+                result["status"] = "completed"
+            else:
+                result["status"] = "running"
+        except ValueError as e:
+            return {"error": str(e)}
+        except Exception as e:  # noqa: BLE001
+            return {"error": f"Error getting process output: {e}"}
+        else:
+            return result
+
+    async def wait_for_process(self, agent_ctx: AgentContext, process_id: str) -> dict[str, Any]:  # noqa: D417
+        """Wait for background process to complete and return final output.
+
+        Args:
+            process_id: Process identifier from start_process
+        """
+        manager = self.get_env(agent_ctx).process_manager
+        try:
+            exit_code = await manager.wait_for_exit(process_id)
+            output = await manager.get_output(process_id)
+            await agent_ctx.events.process_exit(process_id, exit_code, final_output=output.combined)
+
+        except ValueError as e:
+            return {"error": str(e)}
+        except Exception as e:  # noqa: BLE001
+            return {"error": f"Error waiting for process: {e}"}
+        else:
+            return {
+                "process_id": process_id,
+                "exit_code": exit_code,
+                "status": "completed",
+                "stdout": output.stdout or "",
+                "stderr": output.stderr or "",
+                "combined": output.combined or "",
+                "truncated": output.truncated,
+            }
+
+    async def kill_process(self, agent_ctx: AgentContext, process_id: str) -> dict[str, Any]:  # noqa: D417
+        """Terminate a background process.
+
+        Args:
+            process_id: Process identifier from start_process
+        """
+        try:
+            await self.get_env(agent_ctx).process_manager.kill_process(process_id)
+            await agent_ctx.events.process_killed(process_id=process_id, success=True)
+        except ValueError as e:
+            await agent_ctx.events.process_killed(process_id, success=False, error=str(e))
+            return {"error": str(e)}
+        except Exception as e:  # noqa: BLE001
+            await agent_ctx.events.process_killed(process_id, success=False, error=str(e))
+            return {"error": f"Error killing process: {e}"}
+        else:
+            return {
+                "process_id": process_id,
+                "status": "killed",
+                "message": f"Process {process_id} has been terminated",
+            }
+
+    async def release_process(self, agent_ctx: AgentContext, process_id: str) -> dict[str, Any]:  # noqa: D417
+        """Release resources for a background process.
+
+        Args:
+            process_id: Process identifier from start_process
+        """
+        try:
+            await self.get_env(agent_ctx).process_manager.release_process(process_id)
+            await agent_ctx.events.process_released(process_id=process_id, success=True)
+
+        except ValueError as e:
+            await agent_ctx.events.process_released(process_id, success=False, error=str(e))
+            return {"error": str(e)}
+        except Exception as e:  # noqa: BLE001
+            await agent_ctx.events.process_released(process_id, success=False, error=str(e))
+            return {"error": f"Error releasing process: {e}"}
+        else:
+            return {
+                "process_id": process_id,
+                "status": "released",
+                "message": f"Process {process_id} resources have been released",
+            }
+
+    async def list_processes(self, agent_ctx: AgentContext) -> dict[str, Any]:
+        """List all active background processes."""
+        env = self.get_env(agent_ctx)
+        try:
+            process_ids = await env.process_manager.list_processes()
+            if not process_ids:
+                return {"processes": [], "count": 0, "message": "No active processes"}
+
+            processes = []
+            for process_id in process_ids:
+                try:
+                    info = await env.process_manager.get_process_info(process_id)
+                    processes.append({
+                        "process_id": process_id,
+                        "command": info["command"],
+                        "args": info.get("args", []),
+                        "cwd": info.get("cwd"),
+                        "is_running": info.get("is_running", False),
+                        "exit_code": info.get("exit_code"),
+                        "created_at": info.get("created_at"),
+                    })
+                except Exception as e:  # noqa: BLE001
+                    processes.append({
+                        "process_id": process_id,
+                        "error": f"Error getting info: {e}",
+                    })
+
+            return {"processes": processes, "count": len(processes)}
+        except Exception as e:  # noqa: BLE001
+            return {"error": f"Error listing processes: {e}"}

agentpool_toolsets/builtin/file_edit/__init__.py

@@ -0,0 +1,11 @@
+"""File edit AI tools."""
+
+from .file_edit import EditParams, edit_file_tool, edit_tool, replace_content
+
+
+__all__ = [
+    "EditParams",
+    "edit_file_tool",
+    "edit_tool",
+    "replace_content",
+]