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

agentpool_toolsets/builtin/execution_environment.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 import uuid
 
 from exxec.events import OutputEvent, ProcessCompletedEvent, ProcessErrorEvent, ProcessStartedEvent
@@ -55,7 +55,7 @@ class ExecutionEnvironmentTools(ResourceProvider):
         return [
             # Code execution tools
             self.create_tool(self.execute_code, category="execute"),
-            self.create_tool(self.execute_command, category="execute", open_world=True),
+            self.create_tool(self.bash, category="execute", open_world=True),
             # Process management tools
             self.create_tool(self.start_process, category="execute", open_world=True),
             self.create_tool(
@@ -71,7 +71,7 @@ class ExecutionEnvironmentTools(ResourceProvider):
             ),
         ]
 
-    async def execute_code(self, agent_ctx: AgentContext, code: str) -> dict[str, Any]:  # noqa: D417
+    async def execute_code(self, agent_ctx: AgentContext, code: str) -> str:  # noqa: D417
         """Execute Python code and return the result.
 
         Args:
@@ -81,7 +81,6 @@ class ExecutionEnvironmentTools(ResourceProvider):
         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:
@@ -92,9 +91,8 @@ class ExecutionEnvironmentTools(ResourceProvider):
                         output_parts.append(data)
                         if process_id:
                             await agent_ctx.events.process_output(process_id, data)
-                    case ProcessCompletedEvent(exit_code=code_, duration=dur):
+                    case ProcessCompletedEvent(exit_code=code_):
                         exit_code = code_
-                        duration = dur
                         out = "".join(output_parts)
                         if process_id:
                             await agent_ctx.events.process_exit(
@@ -109,24 +107,29 @@ class ExecutionEnvironmentTools(ResourceProvider):
                             )
 
             combined_output = "".join(output_parts)
+
+            # Format as plain text for LLM
             if error_msg:
-                return {"error": error_msg, "output": combined_output, "exit_code": exit_code}
+                return f"{combined_output}\n\nError: {error_msg}\nExit 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}"}
+            return f"Error executing code: {e}"
         else:
-            return {"output": combined_output, "exit_code": exit_code, "duration": duration}
+            # Return just output if success, add exit code only if non-zero
+            if exit_code and exit_code != 0:
+                return f"{combined_output}\n\nExit code: {exit_code}"
+            return combined_output
 
-    async def execute_command(  # noqa: PLR0915, D417
+    async def bash(  # noqa: PLR0915, D417
         self,
         agent_ctx: AgentContext,
         command: str,
         output_limit: int | None = None,
-    ) -> dict[str, Any]:
+    ) -> str:
         """Execute a shell command and return the output.
 
         Args:
@@ -139,7 +142,6 @@ class ExecutionEnvironmentTools(ResourceProvider):
         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:
@@ -158,9 +160,8 @@ class ExecutionEnvironmentTools(ResourceProvider):
                             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):
+                    case ProcessCompletedEvent(process_id=pid, exit_code=code_):
                         exit_code = code_
-                        duration = dur
                         combined = "".join(stdout_parts) + "".join(stderr_parts)
                         if pid:
                             await agent_ctx.events.process_exit(
@@ -175,6 +176,7 @@ class ExecutionEnvironmentTools(ResourceProvider):
 
             stdout = "".join(stdout_parts)
             stderr = "".join(stderr_parts)
+
             # Apply output limit if specified
             truncated = False
             if output_limit:
@@ -186,26 +188,33 @@ class ExecutionEnvironmentTools(ResourceProvider):
                     out = stderr.encode()[-output_limit:].decode(errors="ignore")
                     stderr = "...[truncated]\n" + out
                     truncated = True
+
+            # Format as plain text for LLM
             if error_msg:
-                return {
-                    "error": error_msg,
-                    "stdout": stdout,
-                    "stderr": stderr,
-                    "exit_code": exit_code,
-                }
+                output = stdout + stderr if stdout or stderr else ""
+                return f"{output}\n\nError: {error_msg}\nExit 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}"}
+            return f"Error executing command: {e}"
         else:
-            return {
-                "stdout": stdout,
-                "stderr": stderr,
-                "exit_code": exit_code,
-                "duration": duration,
-                "truncated": truncated,
-            }
+            # Combine stdout and stderr for output
+            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
 
     async def start_process(  # noqa: D417
         self,
@@ -215,7 +224,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,17 +247,12 @@ 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(self, agent_ctx: AgentContext, process_id: str) -> str:  # noqa: D417
         """Get current output from a background process.
 
         Args:
@@ -258,26 +262,28 @@ class ExecutionEnvironmentTools(ResourceProvider):
         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 ""
+            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(self, agent_ctx: AgentContext, process_id: str) -> str:  # noqa: D417
         """Wait for background process to complete and return final output.
 
         Args:
@@ -288,23 +294,25 @@ class ExecutionEnvironmentTools(ResourceProvider):
             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 ""
+
+            # 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 +323,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 +339,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
 
@@ -59,14 +59,90 @@ async def list_skills(ctx: AgentContext) -> str:
     return "\n".join(lines)
 
 
+class _StringOutputWriter:
+    """Output writer that captures output to a string buffer."""
+
+    def __init__(self) -> None:
+        from io import StringIO
+
+        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()
+
+
+async def run_command(ctx: AgentContext, command: str) -> str:  # noqa: D417
+    """Execute an internal 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. Commands have specific argument orders and
+    flags that must be followed exactly.
+
+    Discovery commands:
+    - "help" - list all available commands
+    - "help <command>" - get detailed usage for a specific command (ALWAYS do this first!)
+
+    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:
+        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 (slashed expects command name without /)
+    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."
+
+
 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:
@@ -74,4 +150,10 @@ class SkillsTools(StaticResourceProvider):
         self._tools = [
             self.create_tool(load_skill, category="read", read_only=True, idempotent=True),
             self.create_tool(list_skills, category="read", read_only=True, idempotent=True),
+            self.create_tool(
+                run_command,
+                category="other",
+                read_only=False,
+                idempotent=False,
+            ),
         ]

agentpool_toolsets/fsspec_toolset/__init__.py

@@ -2,6 +2,18 @@
 
 from __future__ import annotations
 
+from agentpool_toolsets.fsspec_toolset.diagnostics import (
+    DiagnosticsConfig,
+    DiagnosticsManager,
+    DiagnosticsResult,
+)
+from agentpool_toolsets.fsspec_toolset.image_utils import resize_image_if_needed
 from agentpool_toolsets.fsspec_toolset.toolset import FSSpecTools
 
-__all__ = ["FSSpecTools"]
+__all__ = [
+    "DiagnosticsConfig",
+    "DiagnosticsManager",
+    "DiagnosticsResult",
+    "FSSpecTools",
+    "resize_image_if_needed",
+]