Initial implementation of xtrm-agent multi-agent system
Multi-agent AI automation system with shared message bus, specialized roles (coder/researcher/reviewer), and deny-by-default security. - Config system with Pydantic validation and YAML loading - Async message bus with inter-agent delegation - LLM providers: Anthropic (Claude) and LiteLLM (DeepSeek/Kimi/MiniMax) - Tool system: registry, builtins (file/bash/web), approval engine, MCP client - Agent engine with tool-calling loop and orchestrator for multi-agent management - CLI channel (REPL) and Discord channel - Docker + Dockge deployment config - Typer CLI: chat, serve, status, agents commands Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Kaloyan Danchev
0
xtrm_agent/tools/__init__.py
Normal file
0
xtrm_agent/tools/__init__.py
Normal file
69
xtrm_agent/tools/approval.py
Normal file
69
xtrm_agent/tools/approval.py
Normal file
@@ -0,0 +1,69 @@
|
||||
"""Tool approval engine — deny-by-default, per-agent policies."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from enum import Enum
|
||||
from typing import Any
|
||||
|
||||
from loguru import logger
|
||||
|
||||
|
||||
class ApprovalPolicy(Enum):
|
||||
AUTO_APPROVE = "auto_approve"
|
||||
REQUIRE_APPROVAL = "require_approval"
|
||||
DENY = "deny"
|
||||
|
||||
|
||||
class ApprovalEngine:
|
||||
"""Deny-by-default tool approval."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
auto_approve: list[str] | None = None,
|
||||
require_approval: list[str] | None = None,
|
||||
interactive: bool = True,
|
||||
) -> None:
|
||||
self._auto_approve = set(auto_approve or [])
|
||||
self._require_approval = set(require_approval or [])
|
||||
self._interactive = interactive
|
||||
|
||||
def get_policy(self, tool_name: str) -> ApprovalPolicy:
|
||||
"""Get the approval policy for a tool."""
|
||||
# MCP tools inherit from the mcp_* prefix pattern
|
||||
base_name = tool_name.split("_", 1)[0] if tool_name.startswith("mcp_") else tool_name
|
||||
|
||||
if tool_name in self._auto_approve or base_name in self._auto_approve:
|
||||
return ApprovalPolicy.AUTO_APPROVE
|
||||
if tool_name in self._require_approval or base_name in self._require_approval:
|
||||
return ApprovalPolicy.REQUIRE_APPROVAL
|
||||
return ApprovalPolicy.DENY
|
||||
|
||||
async def check(self, tool_name: str, arguments: dict[str, Any]) -> bool:
|
||||
"""Check if a tool call is approved. Returns True if approved."""
|
||||
policy = self.get_policy(tool_name)
|
||||
|
||||
if policy == ApprovalPolicy.AUTO_APPROVE:
|
||||
return True
|
||||
|
||||
if policy == ApprovalPolicy.DENY:
|
||||
logger.warning(f"Tool '{tool_name}' denied by policy")
|
||||
return False
|
||||
|
||||
# REQUIRE_APPROVAL
|
||||
if not self._interactive:
|
||||
logger.warning(f"Tool '{tool_name}' requires approval but running non-interactively — denied")
|
||||
return False
|
||||
|
||||
# In interactive mode, prompt the user
|
||||
logger.info(f"Tool '{tool_name}' requires approval. Args: {arguments}")
|
||||
return await self._prompt_user(tool_name, arguments)
|
||||
|
||||
async def _prompt_user(self, tool_name: str, arguments: dict[str, Any]) -> bool:
|
||||
"""Prompt user for tool approval (interactive mode)."""
|
||||
print(f"\n[APPROVAL REQUIRED] Tool: {tool_name}")
|
||||
print(f" Arguments: {arguments}")
|
||||
try:
|
||||
answer = input(" Allow? [y/N]: ").strip().lower()
|
||||
return answer in ("y", "yes")
|
||||
except (EOFError, KeyboardInterrupt):
|
||||
return False
|
||||
257
xtrm_agent/tools/builtin.py
Normal file
257
xtrm_agent/tools/builtin.py
Normal file
@@ -0,0 +1,257 @@
|
||||
"""Built-in tools — file operations, shell, web fetch."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import os
|
||||
import re
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
|
||||
from xtrm_agent.tools.registry import Tool
|
||||
|
||||
# Patterns blocked in bash commands
|
||||
BASH_DENY_PATTERNS = [
|
||||
r"rm\s+-rf\s+/",
|
||||
r"mkfs\.",
|
||||
r"\bdd\b.*of=/dev/",
|
||||
r":\(\)\{.*\|.*&\s*\};:", # fork bomb
|
||||
r"chmod\s+-R\s+777\s+/",
|
||||
r">\s*/dev/sd[a-z]",
|
||||
]
|
||||
|
||||
|
||||
def _resolve_path(workspace: Path, requested: str) -> Path:
|
||||
"""Resolve and sandbox a path to the workspace."""
|
||||
p = (workspace / requested).resolve()
|
||||
ws = workspace.resolve()
|
||||
if not str(p).startswith(str(ws)):
|
||||
raise ValueError(f"Path '{requested}' escapes workspace")
|
||||
return p
|
||||
|
||||
|
||||
class ReadFileTool(Tool):
|
||||
def __init__(self, workspace: Path) -> None:
|
||||
self._workspace = workspace
|
||||
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return "read_file"
|
||||
|
||||
@property
|
||||
def description(self) -> str:
|
||||
return "Read the contents of a file."
|
||||
|
||||
@property
|
||||
def parameters(self) -> dict[str, Any]:
|
||||
return {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"path": {"type": "string", "description": "File path relative to workspace"},
|
||||
},
|
||||
"required": ["path"],
|
||||
}
|
||||
|
||||
async def execute(self, path: str, **_: Any) -> str:
|
||||
p = _resolve_path(self._workspace, path)
|
||||
if not p.exists():
|
||||
return f"Error: File not found: {path}"
|
||||
return p.read_text(errors="replace")
|
||||
|
||||
|
||||
class WriteFileTool(Tool):
|
||||
def __init__(self, workspace: Path) -> None:
|
||||
self._workspace = workspace
|
||||
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return "write_file"
|
||||
|
||||
@property
|
||||
def description(self) -> str:
|
||||
return "Create or overwrite a file with the given content."
|
||||
|
||||
@property
|
||||
def parameters(self) -> dict[str, Any]:
|
||||
return {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"path": {"type": "string", "description": "File path relative to workspace"},
|
||||
"content": {"type": "string", "description": "Content to write"},
|
||||
},
|
||||
"required": ["path", "content"],
|
||||
}
|
||||
|
||||
async def execute(self, path: str, content: str, **_: Any) -> str:
|
||||
p = _resolve_path(self._workspace, path)
|
||||
p.parent.mkdir(parents=True, exist_ok=True)
|
||||
p.write_text(content)
|
||||
return f"Wrote {len(content)} bytes to {path}"
|
||||
|
||||
|
||||
class EditFileTool(Tool):
|
||||
def __init__(self, workspace: Path) -> None:
|
||||
self._workspace = workspace
|
||||
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return "edit_file"
|
||||
|
||||
@property
|
||||
def description(self) -> str:
|
||||
return "Replace an exact string in a file with new content."
|
||||
|
||||
@property
|
||||
def parameters(self) -> dict[str, Any]:
|
||||
return {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"path": {"type": "string", "description": "File path relative to workspace"},
|
||||
"old_string": {"type": "string", "description": "Exact text to find"},
|
||||
"new_string": {"type": "string", "description": "Replacement text"},
|
||||
},
|
||||
"required": ["path", "old_string", "new_string"],
|
||||
}
|
||||
|
||||
async def execute(self, path: str, old_string: str, new_string: str, **_: Any) -> str:
|
||||
p = _resolve_path(self._workspace, path)
|
||||
if not p.exists():
|
||||
return f"Error: File not found: {path}"
|
||||
text = p.read_text()
|
||||
if old_string not in text:
|
||||
return "Error: old_string not found in file"
|
||||
count = text.count(old_string)
|
||||
if count > 1:
|
||||
return f"Error: old_string found {count} times — must be unique"
|
||||
p.write_text(text.replace(old_string, new_string, 1))
|
||||
return f"Edited {path}"
|
||||
|
||||
|
||||
class ListDirTool(Tool):
|
||||
def __init__(self, workspace: Path) -> None:
|
||||
self._workspace = workspace
|
||||
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return "list_dir"
|
||||
|
||||
@property
|
||||
def description(self) -> str:
|
||||
return "List files and directories at the given path."
|
||||
|
||||
@property
|
||||
def parameters(self) -> dict[str, Any]:
|
||||
return {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "Directory path relative to workspace (default: root)",
|
||||
"default": ".",
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
async def execute(self, path: str = ".", **_: Any) -> str:
|
||||
p = _resolve_path(self._workspace, path)
|
||||
if not p.exists():
|
||||
return f"Error: Directory not found: {path}"
|
||||
if not p.is_dir():
|
||||
return f"Error: Not a directory: {path}"
|
||||
entries = sorted(p.iterdir())
|
||||
lines = []
|
||||
for entry in entries:
|
||||
suffix = "/" if entry.is_dir() else ""
|
||||
lines.append(f"{entry.name}{suffix}")
|
||||
return "\n".join(lines) if lines else "(empty directory)"
|
||||
|
||||
|
||||
class BashTool(Tool):
|
||||
def __init__(self, workspace: Path, timeout: int = 60) -> None:
|
||||
self._workspace = workspace
|
||||
self._timeout = timeout
|
||||
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return "bash"
|
||||
|
||||
@property
|
||||
def description(self) -> str:
|
||||
return "Execute a shell command in the workspace directory."
|
||||
|
||||
@property
|
||||
def parameters(self) -> dict[str, Any]:
|
||||
return {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {"type": "string", "description": "Shell command to execute"},
|
||||
},
|
||||
"required": ["command"],
|
||||
}
|
||||
|
||||
async def execute(self, command: str, **_: Any) -> str:
|
||||
# Check deny patterns
|
||||
for pattern in BASH_DENY_PATTERNS:
|
||||
if re.search(pattern, command):
|
||||
return f"Error: Command blocked by security policy"
|
||||
|
||||
try:
|
||||
proc = await asyncio.create_subprocess_shell(
|
||||
command,
|
||||
stdout=asyncio.subprocess.PIPE,
|
||||
stderr=asyncio.subprocess.STDOUT,
|
||||
cwd=str(self._workspace),
|
||||
env={**os.environ},
|
||||
)
|
||||
stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=self._timeout)
|
||||
output = stdout.decode(errors="replace")
|
||||
# Truncate large output
|
||||
if len(output) > 10_000:
|
||||
output = output[:10_000] + "\n... (truncated)"
|
||||
exit_info = f"\n[exit code: {proc.returncode}]"
|
||||
return output + exit_info
|
||||
except asyncio.TimeoutError:
|
||||
return f"Error: Command timed out after {self._timeout}s"
|
||||
|
||||
|
||||
class WebFetchTool(Tool):
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return "web_fetch"
|
||||
|
||||
@property
|
||||
def description(self) -> str:
|
||||
return "Fetch the content of a URL."
|
||||
|
||||
@property
|
||||
def parameters(self) -> dict[str, Any]:
|
||||
return {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"url": {"type": "string", "description": "URL to fetch"},
|
||||
},
|
||||
"required": ["url"],
|
||||
}
|
||||
|
||||
async def execute(self, url: str, **_: Any) -> str:
|
||||
try:
|
||||
async with httpx.AsyncClient(timeout=30, follow_redirects=True) as client:
|
||||
resp = await client.get(url)
|
||||
text = resp.text
|
||||
if len(text) > 20_000:
|
||||
text = text[:20_000] + "\n... (truncated)"
|
||||
return text
|
||||
except Exception as e:
|
||||
return f"Error fetching URL: {e}"
|
||||
|
||||
|
||||
def register_builtin_tools(registry: Any, workspace: Path) -> None:
|
||||
"""Register all built-in tools into a ToolRegistry."""
|
||||
registry.register(ReadFileTool(workspace))
|
||||
registry.register(WriteFileTool(workspace))
|
||||
registry.register(EditFileTool(workspace))
|
||||
registry.register(ListDirTool(workspace))
|
||||
registry.register(BashTool(workspace))
|
||||
registry.register(WebFetchTool())
|
||||
88
xtrm_agent/tools/delegate.py
Normal file
88
xtrm_agent/tools/delegate.py
Normal file
@@ -0,0 +1,88 @@
|
||||
"""Delegate tool — allows agents to invoke each other."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import uuid
|
||||
from typing import Any
|
||||
|
||||
from loguru import logger
|
||||
|
||||
from xtrm_agent.bus import AgentMessage, MessageBus
|
||||
from xtrm_agent.tools.registry import Tool
|
||||
|
||||
|
||||
class DelegateTool(Tool):
|
||||
"""Built-in tool for inter-agent delegation."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
bus: MessageBus,
|
||||
from_agent: str,
|
||||
available_agents: list[str],
|
||||
timeout: int = 120,
|
||||
) -> None:
|
||||
self._bus = bus
|
||||
self._from_agent = from_agent
|
||||
self._available_agents = available_agents
|
||||
self._timeout = timeout
|
||||
self._pending: dict[str, asyncio.Future[str]] = {}
|
||||
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return "delegate"
|
||||
|
||||
@property
|
||||
def description(self) -> str:
|
||||
agents = ", ".join(self._available_agents)
|
||||
return f"Delegate a task to another agent. Available agents: {agents}"
|
||||
|
||||
@property
|
||||
def parameters(self) -> dict[str, Any]:
|
||||
return {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"agent_name": {
|
||||
"type": "string",
|
||||
"description": "Name of the agent to delegate to",
|
||||
},
|
||||
"task": {
|
||||
"type": "string",
|
||||
"description": "Description of the task to delegate",
|
||||
},
|
||||
},
|
||||
"required": ["agent_name", "task"],
|
||||
}
|
||||
|
||||
async def execute(self, agent_name: str, task: str, **_: Any) -> str:
|
||||
if agent_name not in self._available_agents:
|
||||
return f"Error: Unknown agent '{agent_name}'. Available: {', '.join(self._available_agents)}"
|
||||
|
||||
if agent_name == self._from_agent:
|
||||
return "Error: Cannot delegate to self"
|
||||
|
||||
request_id = uuid.uuid4().hex[:12]
|
||||
future: asyncio.Future[str] = asyncio.get_event_loop().create_future()
|
||||
self._pending[request_id] = future
|
||||
|
||||
msg = AgentMessage(
|
||||
from_agent=self._from_agent,
|
||||
to_agent=agent_name,
|
||||
task=task,
|
||||
request_id=request_id,
|
||||
)
|
||||
await self._bus.publish_agent_message(msg)
|
||||
logger.info(f"[{self._from_agent}] Delegated to {agent_name}: {task[:80]}")
|
||||
|
||||
try:
|
||||
result = await asyncio.wait_for(future, timeout=self._timeout)
|
||||
return result
|
||||
except asyncio.TimeoutError:
|
||||
self._pending.pop(request_id, None)
|
||||
return f"Error: Delegation to '{agent_name}' timed out after {self._timeout}s"
|
||||
|
||||
def resolve(self, request_id: str, response: str) -> None:
|
||||
"""Resolve a pending delegation with the response."""
|
||||
future = self._pending.pop(request_id, None)
|
||||
if future and not future.done():
|
||||
future.set_result(response)
|
||||
99
xtrm_agent/tools/mcp_client.py
Normal file
99
xtrm_agent/tools/mcp_client.py
Normal file
@@ -0,0 +1,99 @@
|
||||
"""MCP client — connect to MCP servers and wrap their tools."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from contextlib import AsyncExitStack
|
||||
from typing import Any
|
||||
|
||||
from loguru import logger
|
||||
|
||||
from xtrm_agent.config import MCPServerConfig
|
||||
from xtrm_agent.tools.registry import Tool, ToolRegistry
|
||||
|
||||
|
||||
class MCPToolWrapper(Tool):
|
||||
"""Wraps an MCP server tool as a local Tool."""
|
||||
|
||||
def __init__(self, session: Any, server_name: str, tool_def: Any) -> None:
|
||||
self._session = session
|
||||
self._server_name = server_name
|
||||
self._tool_def = tool_def
|
||||
self._tool_name = f"mcp_{server_name}_{tool_def.name}"
|
||||
self._original_name = tool_def.name
|
||||
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return self._tool_name
|
||||
|
||||
@property
|
||||
def description(self) -> str:
|
||||
return getattr(self._tool_def, "description", "") or ""
|
||||
|
||||
@property
|
||||
def parameters(self) -> dict[str, Any]:
|
||||
schema = getattr(self._tool_def, "inputSchema", None)
|
||||
if schema:
|
||||
return dict(schema)
|
||||
return {"type": "object", "properties": {}}
|
||||
|
||||
async def execute(self, **kwargs: Any) -> str:
|
||||
try:
|
||||
result = await self._session.call_tool(self._original_name, arguments=kwargs)
|
||||
parts = []
|
||||
for block in result.content:
|
||||
if hasattr(block, "text"):
|
||||
parts.append(block.text)
|
||||
return "\n".join(parts) if parts else "(empty result)"
|
||||
except Exception as e:
|
||||
return f"Error calling MCP tool '{self._original_name}': {e}"
|
||||
|
||||
|
||||
async def connect_mcp_servers(
|
||||
mcp_servers: dict[str, MCPServerConfig],
|
||||
registry: ToolRegistry,
|
||||
stack: AsyncExitStack,
|
||||
) -> None:
|
||||
"""Connect to configured MCP servers and register their tools."""
|
||||
if not mcp_servers:
|
||||
return
|
||||
|
||||
try:
|
||||
from mcp import ClientSession, StdioServerParameters
|
||||
from mcp.client.stdio import stdio_client
|
||||
except ImportError:
|
||||
logger.warning("MCP SDK not available — skipping MCP server connections")
|
||||
return
|
||||
|
||||
for name, cfg in mcp_servers.items():
|
||||
try:
|
||||
if cfg.command:
|
||||
params = StdioServerParameters(
|
||||
command=cfg.command,
|
||||
args=cfg.args,
|
||||
env={**cfg.env} if cfg.env else None,
|
||||
)
|
||||
read, write = await stack.enter_async_context(stdio_client(params))
|
||||
elif cfg.url:
|
||||
try:
|
||||
from mcp.client.streamable_http import streamable_http_client
|
||||
read, write, _ = await stack.enter_async_context(
|
||||
streamable_http_client(cfg.url)
|
||||
)
|
||||
except ImportError:
|
||||
logger.warning(f"MCP HTTP client not available — skipping {name}")
|
||||
continue
|
||||
else:
|
||||
logger.warning(f"MCP server '{name}' has no command or URL — skipping")
|
||||
continue
|
||||
|
||||
session = await stack.enter_async_context(ClientSession(read, write))
|
||||
await session.initialize()
|
||||
|
||||
tools_result = await session.list_tools()
|
||||
for tool_def in tools_result.tools:
|
||||
wrapper = MCPToolWrapper(session, name, tool_def)
|
||||
registry.register(wrapper)
|
||||
logger.info(f"Registered MCP tool: {wrapper.name}")
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to connect MCP server '{name}': {e}")
|
||||
80
xtrm_agent/tools/registry.py
Normal file
80
xtrm_agent/tools/registry.py
Normal file
@@ -0,0 +1,80 @@
|
||||
"""Tool registry — ABC and dynamic registration."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from abc import ABC, abstractmethod
|
||||
from typing import Any
|
||||
|
||||
from loguru import logger
|
||||
|
||||
|
||||
class Tool(ABC):
|
||||
"""Abstract base for all tools."""
|
||||
|
||||
@property
|
||||
@abstractmethod
|
||||
def name(self) -> str: ...
|
||||
|
||||
@property
|
||||
@abstractmethod
|
||||
def description(self) -> str: ...
|
||||
|
||||
@property
|
||||
@abstractmethod
|
||||
def parameters(self) -> dict[str, Any]:
|
||||
"""JSON Schema for tool parameters."""
|
||||
|
||||
@abstractmethod
|
||||
async def execute(self, **kwargs: Any) -> str:
|
||||
"""Execute the tool and return a string result."""
|
||||
|
||||
def to_openai_schema(self) -> dict[str, Any]:
|
||||
"""Convert to OpenAI function-calling format."""
|
||||
return {
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": self.name,
|
||||
"description": self.description,
|
||||
"parameters": self.parameters,
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
class ToolRegistry:
|
||||
"""Manages registered tools and dispatches execution."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self._tools: dict[str, Tool] = {}
|
||||
|
||||
def register(self, tool: Tool) -> None:
|
||||
self._tools[tool.name] = tool
|
||||
|
||||
def get(self, name: str) -> Tool | None:
|
||||
return self._tools.get(name)
|
||||
|
||||
def names(self) -> list[str]:
|
||||
return list(self._tools.keys())
|
||||
|
||||
def get_definitions(self) -> list[dict[str, Any]]:
|
||||
"""Get all tool schemas for the LLM."""
|
||||
return [t.to_openai_schema() for t in self._tools.values()]
|
||||
|
||||
def filtered(self, allowed: list[str]) -> ToolRegistry:
|
||||
"""Return a new registry containing only the specified tools."""
|
||||
filtered_reg = ToolRegistry()
|
||||
for name in allowed:
|
||||
tool = self._tools.get(name)
|
||||
if tool:
|
||||
filtered_reg.register(tool)
|
||||
return filtered_reg
|
||||
|
||||
async def execute(self, name: str, arguments: dict[str, Any]) -> str:
|
||||
"""Execute a tool by name."""
|
||||
tool = self._tools.get(name)
|
||||
if not tool:
|
||||
return f"Error: Unknown tool '{name}'"
|
||||
try:
|
||||
return await tool.execute(**arguments)
|
||||
except Exception as e:
|
||||
logger.error(f"Tool '{name}' failed: {e}")
|
||||
return f"Error executing '{name}': {e}"
|
||||
Reference in New Issue
Block a user