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

agentpool_toolsets/builtin/execution_environment.py

@@ -1,11 +1,9 @@
-"""Provider for execution environment tools with event emission."""
+"""Provider for process management tools with event emission."""
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
-import uuid
-
-from exxec.events import OutputEvent, ProcessCompletedEvent, ProcessErrorEvent, ProcessStartedEvent
+import re
+from typing import TYPE_CHECKING
 
 from agentpool import log
 from agentpool.agents.context import AgentContext  # noqa: TC001
@@ -16,26 +14,29 @@ logger = log.get_logger(__name__)
 
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     from exxec import ExecutionEnvironment
 
     from agentpool.tools.base import Tool
 
 
-class ExecutionEnvironmentTools(ResourceProvider):
-    """Provider for execution environment tools.
+class ProcessManagementTools(ResourceProvider):
+    """Provider for background process management tools.
 
-    Combines code execution and process management capabilities
-    using any ExecutionEnvironment backend. Emits events via AgentContext.
+    Provides tools for starting, monitoring, and controlling background processes.
+    Uses any ExecutionEnvironment backend and 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.
+    For code execution and bash commands, use the standalone tools:
+    - agentpool.tool_impls.bash.BashTool
+    - agentpool.tool_impls.execute_code.ExecuteCodeTool
     """
 
-    def __init__(self, env: ExecutionEnvironment | None = None, name: str = "execution") -> None:
-        """Initialize execution environment toolset.
+    def __init__(self, env: ExecutionEnvironment | None = None, name: str = "process") -> None:
+        """Initialize process management toolset.
 
         Args:
-            env: Execution environment to use (defaults to LocalExecutionEnvironment)
+            env: Execution environment to use (defaults to agent.env)
             name: The name of the toolset
         """
         super().__init__(name=name)
@@ -51,12 +52,8 @@ class ExecutionEnvironmentTools(ResourceProvider):
             return self._env
         return agent_ctx.agent.env
 
-    async def get_tools(self) -> list[Tool]:
+    async def get_tools(self) -> Sequence[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
@@ -71,142 +68,6 @@ class ExecutionEnvironmentTools(ResourceProvider):
             ),
         ]
 
-    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,
@@ -215,7 +76,7 @@ class ExecutionEnvironmentTools(ResourceProvider):
         cwd: str | None = None,
         env: dict[str, str] | None = None,
         output_limit: int | None = None,
-    ) -> dict[str, Any]:
+    ) -> str:
         """Start a command in the background and return process ID.
 
         Args:
@@ -238,73 +99,109 @@ class ExecutionEnvironmentTools(ResourceProvider):
 
         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}"}
+            return 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
+            full_cmd = f"{command} {' '.join(args)}" if args else command
+            return f"Started background process {process_id}\nCommand: {full_cmd}"
+
+    async def get_process_output(  # noqa: D417
+        self,
+        agent_ctx: AgentContext,
+        process_id: str,
+        filter_lines: str | None = None,
+    ) -> str:
         """Get current output from a background process.
 
         Args:
             process_id: Process identifier from start_process
+            filter_lines: Optional regex pattern to filter output lines
+                          (only matching lines returned)
         """
         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,
-            }
+
+            combined = output.combined or ""
+
+            # Apply regex filter if specified
+            if filter_lines and combined:
+                try:
+                    pattern = re.compile(filter_lines)
+                    filtered_lines = [
+                        line for line in combined.splitlines(keepends=True) if pattern.search(line)
+                    ]
+                    combined = "".join(filtered_lines)
+                except re.error as regex_err:
+                    return f"Invalid filter regex: {regex_err}"
+
+            status = "completed" if output.exit_code is not None else "running"
+
+            # Format as plain text
+            suffix_parts = [f"Status: {status}"]
             if output.exit_code is not None:
-                result["exit_code"] = output.exit_code
-                result["status"] = "completed"
-            else:
-                result["status"] = "running"
+                suffix_parts.append(f"Exit code: {output.exit_code}")
+            if output.truncated:
+                suffix_parts.append("[output truncated]")
+
+            return (
+                f"{combined}\n\n{' | '.join(suffix_parts)}"
+                if combined
+                else " | ".join(suffix_parts)
+            )
         except ValueError as e:
-            return {"error": str(e)}
+            return f"Error: {e}"
         except Exception as e:  # noqa: BLE001
-            return {"error": f"Error getting process output: {e}"}
-        else:
-            return result
+            return f"Error getting process output: {e}"
 
-    async def wait_for_process(self, agent_ctx: AgentContext, process_id: str) -> dict[str, Any]:  # noqa: D417
+    async def wait_for_process(  # noqa: D417
+        self,
+        agent_ctx: AgentContext,
+        process_id: str,
+        filter_lines: str | None = None,
+    ) -> str:
         """Wait for background process to complete and return final output.
 
         Args:
             process_id: Process identifier from start_process
+            filter_lines: Optional regex pattern to filter output lines
+                          (only matching lines returned)
         """
         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)}
+            return f"Error: {e}"
         except Exception as e:  # noqa: BLE001
-            return {"error": f"Error waiting for process: {e}"}
+            return 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
+            combined = output.combined or ""
+
+            # Apply regex filter if specified
+            if filter_lines and combined:
+                try:
+                    pattern = re.compile(filter_lines)
+                    filtered_lines = [
+                        line for line in combined.splitlines(keepends=True) if pattern.search(line)
+                    ]
+                    combined = "".join(filtered_lines)
+                except re.error as regex_err:
+                    return f"Invalid filter regex: {regex_err}"
+
+            # Format as plain text
+            suffix_parts = []
+            if output.truncated:
+                suffix_parts.append("[output truncated]")
+            if exit_code != 0:
+                suffix_parts.append(f"Exit code: {exit_code}")
+
+            if suffix_parts:
+                return f"{combined}\n\n{' | '.join(suffix_parts)}"
+            return combined
+
+    async def kill_process(self, agent_ctx: AgentContext, process_id: str) -> str:  # noqa: D417
         """Terminate a background process.
 
         Args:
@@ -315,18 +212,14 @@ class ExecutionEnvironmentTools(ResourceProvider):
             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)}
+            return f"Error: {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}"}
+            return f"Error killing process: {e}"
         else:
-            return {
-                "process_id": process_id,
-                "status": "killed",
-                "message": f"Process {process_id} has been terminated",
-            }
+            return f"Process {process_id} has been terminated"
 
-    async def release_process(self, agent_ctx: AgentContext, process_id: str) -> dict[str, Any]:  # noqa: D417
+    async def release_process(self, agent_ctx: AgentContext, process_id: str) -> str:  # noqa: D417
         """Release resources for a background process.
 
         Args:
@@ -335,47 +228,39 @@ class ExecutionEnvironmentTools(ResourceProvider):
         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)}
+            return f"Error: {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}"}
+            return f"Error releasing process: {e}"
         else:
-            return {
-                "process_id": process_id,
-                "status": "released",
-                "message": f"Process {process_id} resources have been released",
-            }
+            return f"Process {process_id} resources have been released"
 
-    async def list_processes(self, agent_ctx: AgentContext) -> dict[str, Any]:
+    async def list_processes(self, agent_ctx: AgentContext) -> str:
         """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"}
+                return "No active background processes"
 
-            processes = []
+            lines = [f"Active processes ({len(process_ids)}):"]
             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"),
-                    })
+                    command = info["command"]
+                    args = info.get("args", [])
+                    full_cmd = f"{command} {' '.join(args)}" if args else command
+                    status = "running" if info.get("is_running", False) else "stopped"
+                    exit_code = info.get("exit_code")
+                    status_str = (
+                        f"{status}" if exit_code is None else f"{status} (exit {exit_code})"
+                    )
+                    lines.append(f"  - {process_id}: {full_cmd} [{status_str}]")
                 except Exception as e:  # noqa: BLE001
-                    processes.append({
-                        "process_id": process_id,
-                        "error": f"Error getting info: {e}",
-                    })
+                    lines.append(f"  - {process_id}: [error getting info: {e}]")
 
-            return {"processes": processes, "count": len(processes)}
+            return "\n".join(lines)
         except Exception as e:  # noqa: BLE001
-            return {"error": f"Error listing processes: {e}"}
+            return f"Error listing processes: {e}"

agentpool_toolsets/builtin/file_edit/file_edit.py

@@ -479,9 +479,22 @@ def _trim_diff(diff_text: str) -> str:
 
 
 def replace_content(
-    content: str, old_string: str, new_string: str, replace_all: bool = False
+    content: str,
+    old_string: str,
+    new_string: str,
+    replace_all: bool = False,
+    line_hint: int | None = None,
 ) -> str:
-    """Replace content using multiple fallback strategies with detailed error messages."""
+    """Replace content using multiple fallback strategies with detailed error messages.
+
+    Args:
+        content: The file content to edit
+        old_string: Text to find and replace
+        new_string: Replacement text
+        replace_all: If True, replace all occurrences
+        line_hint: If provided and multiple matches exist, use the match closest to this line.
+            Useful for disambiguation after getting a "multiple matches" error.
+    """
     if old_string == new_string:
         msg = "old_string and new_string must be different"
         raise ValueError(msg)
@@ -518,6 +531,16 @@ def replace_content(
             # Check if there are multiple occurrences
             last_index = content.rfind(search_text)
             if index != last_index:
+                # Multiple occurrences found
+                if line_hint is not None:
+                    # Use line_hint to pick the closest match
+                    best_index = _find_closest_match(content, search_text, line_hint)
+                    if best_index is not None:
+                        return (
+                            content[:best_index]
+                            + new_string
+                            + content[best_index + len(search_text) :]
+                        )
                 continue  # Multiple occurrences, need more context
 
             # Single occurrence - replace it
@@ -528,11 +551,9 @@ def replace_content(
         error_msg = _build_not_found_error(content, old_string)
         raise ValueError(error_msg)
 
-    msg = (
-        "old_string found multiple times and requires more code context "
-        "to uniquely identify the intended match"
-    )
-    raise ValueError(msg)
+    # Multiple matches found - provide helpful error with locations
+    error_msg = _build_multiple_matches_error(content, old_string)
+    raise ValueError(error_msg)
 
 
 def _find_best_fuzzy_match(
@@ -614,6 +635,93 @@ def _create_unified_diff(text1: str, text2: str) -> str:
     return result.rstrip()
 
 
+def _find_all_match_locations(content: str, search_text: str) -> list[int]:
+    """Find all line numbers where search_text starts.
+
+    Returns 1-based line numbers for each occurrence.
+    """
+    lines = content.split("\n")
+    locations: list[int] = []
+
+    # For single-line search, find direct matches
+    search_lines = search_text.split("\n")
+    first_search_line = search_lines[0] if search_lines else search_text
+
+    for i, line in enumerate(lines):
+        if first_search_line in line:
+            # Verify full match if multi-line
+            if len(search_lines) > 1:
+                window = "\n".join(lines[i : i + len(search_lines)])
+                if search_text in window:
+                    locations.append(i + 1)  # 1-based
+            else:
+                locations.append(i + 1)  # 1-based
+
+    return locations
+
+
+def _find_closest_match(content: str, search_text: str, line_hint: int) -> int | None:
+    """Find the occurrence of search_text closest to line_hint.
+
+    Args:
+        content: The file content
+        search_text: Text to search for
+        line_hint: Target line number (1-based)
+
+    Returns:
+        The character index of the closest match, or None if no matches found.
+    """
+    matches: list[tuple[int, int]] = []  # (line_number, char_index)
+
+    # Find all occurrences with their positions
+    start = 0
+    while True:
+        index = content.find(search_text, start)
+        if index == -1:
+            break
+        # Calculate line number for this index
+        line_num = content[:index].count("\n") + 1
+        matches.append((line_num, index))
+        start = index + 1
+
+    if not matches:
+        return None
+
+    # Find the match closest to line_hint
+    closest = min(matches, key=lambda m: abs(m[0] - line_hint))
+    return closest[1]
+
+
+def _build_multiple_matches_error(content: str, old_string: str) -> str:
+    """Build a helpful error message when old_string matches multiple locations."""
+    locations = _find_all_match_locations(content, old_string)
+
+    if not locations:
+        # Fallback - shouldn't happen but be safe
+        return (
+            "old_string found multiple times and requires more code context "
+            "to uniquely identify the intended match"
+        )
+
+    # Show first few lines of the search text for context
+    search_preview = old_string.split("\n")[0][:60]
+    if len(old_string.split("\n")[0]) > 60:  # noqa: PLR2004
+        search_preview += "..."
+
+    location_str = ", ".join(str(loc) for loc in locations[:5])
+    if len(locations) > 5:  # noqa: PLR2004
+        location_str += f", ... ({len(locations)} total)"
+
+    error_parts = [
+        f"Pattern found at multiple locations (lines: {location_str}).",
+        f"\nSearch text starts with: {search_preview!r}",
+        "\n\nTo fix, include more surrounding context in old_string to uniquely identify "
+        "the target location, or use replace_all=True to replace all occurrences.",
+    ]
+
+    return "".join(error_parts)
+
+
 def _build_not_found_error(content: str, old_string: str) -> str:
     """Build a helpful error message when old_string is not found."""
     lines = content.split("\n")

agentpool_toolsets/builtin/skills.py

@@ -1,4 +1,4 @@
-"""Provider for skills tools."""
+"""Provider for skills and commands tools."""
 
 from __future__ import annotations
 
@@ -60,13 +60,18 @@ async def list_skills(ctx: AgentContext) -> str:
 
 
 class SkillsTools(StaticResourceProvider):
-    """Provider for Claude Code Skills tools.
+    """Provider for skills and commands tools.
+
+    Provides tools to:
+    - Discover and load skills from the pool's skills registry
+    - Execute internal commands via the agent's command system
 
-    Provides tools to discover and load skills from the pool's skills registry.
     Skills are discovered from configured directories (e.g., ~/.claude/skills/,
     .claude/skills/).
 
-    The pool manages skill discovery; this toolset just provides access to them.
+    Commands provide access to management operations like creating agents,
+    managing tools, connecting nodes, etc. Use run_command("/help") to discover
+    available commands.
     """
 
     def __init__(self, name: str = "skills") -> None: