ragnarbot-ai 0.1.0__py3-none-any.whl

ragnarbot/agent/tools/cron.py

@@ -0,0 +1,114 @@
+"""Cron tool for scheduling reminders and tasks."""
+
+from typing import Any
+
+from ragnarbot.agent.tools.base import Tool
+from ragnarbot.cron.service import CronService
+from ragnarbot.cron.types import CronSchedule
+
+
+class CronTool(Tool):
+    """Tool to schedule reminders and recurring tasks."""
+    
+    def __init__(self, cron_service: CronService):
+        self._cron = cron_service
+        self._channel = ""
+        self._chat_id = ""
+    
+    def set_context(self, channel: str, chat_id: str) -> None:
+        """Set the current session context for delivery."""
+        self._channel = channel
+        self._chat_id = chat_id
+    
+    @property
+    def name(self) -> str:
+        return "cron"
+    
+    @property
+    def description(self) -> str:
+        return "Schedule reminders and recurring tasks. Actions: add, list, remove."
+    
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": ["add", "list", "remove"],
+                    "description": "Action to perform"
+                },
+                "message": {
+                    "type": "string",
+                    "description": "Reminder message (for add)"
+                },
+                "every_seconds": {
+                    "type": "integer",
+                    "description": "Interval in seconds (for recurring tasks)"
+                },
+                "cron_expr": {
+                    "type": "string",
+                    "description": "Cron expression like '0 9 * * *' (for scheduled tasks)"
+                },
+                "job_id": {
+                    "type": "string",
+                    "description": "Job ID (for remove)"
+                }
+            },
+            "required": ["action"]
+        }
+    
+    async def execute(
+        self,
+        action: str,
+        message: str = "",
+        every_seconds: int | None = None,
+        cron_expr: str | None = None,
+        job_id: str | None = None,
+        **kwargs: Any
+    ) -> str:
+        if action == "add":
+            return self._add_job(message, every_seconds, cron_expr)
+        elif action == "list":
+            return self._list_jobs()
+        elif action == "remove":
+            return self._remove_job(job_id)
+        return f"Unknown action: {action}"
+    
+    def _add_job(self, message: str, every_seconds: int | None, cron_expr: str | None) -> str:
+        if not message:
+            return "Error: message is required for add"
+        if not self._channel or not self._chat_id:
+            return "Error: no session context (channel/chat_id)"
+        
+        # Build schedule
+        if every_seconds:
+            schedule = CronSchedule(kind="every", every_ms=every_seconds * 1000)
+        elif cron_expr:
+            schedule = CronSchedule(kind="cron", expr=cron_expr)
+        else:
+            return "Error: either every_seconds or cron_expr is required"
+        
+        job = self._cron.add_job(
+            name=message[:30],
+            schedule=schedule,
+            message=message,
+            deliver=True,
+            channel=self._channel,
+            to=self._chat_id,
+        )
+        return f"Created job '{job.name}' (id: {job.id})"
+    
+    def _list_jobs(self) -> str:
+        jobs = self._cron.list_jobs()
+        if not jobs:
+            return "No scheduled jobs."
+        lines = [f"- {j.name} (id: {j.id}, {j.schedule.kind})" for j in jobs]
+        return "Scheduled jobs:\n" + "\n".join(lines)
+    
+    def _remove_job(self, job_id: str | None) -> str:
+        if not job_id:
+            return "Error: job_id is required for remove"
+        if self._cron.remove_job(job_id):
+            return f"Removed job {job_id}"
+        return f"Job {job_id} not found"

ragnarbot/agent/tools/filesystem.py

@@ -0,0 +1,191 @@
+"""File system tools: read, write, edit."""
+
+from pathlib import Path
+from typing import Any
+
+from ragnarbot.agent.tools.base import Tool
+
+
+class ReadFileTool(Tool):
+    """Tool to read file contents."""
+    
+    @property
+    def name(self) -> str:
+        return "read_file"
+    
+    @property
+    def description(self) -> str:
+        return "Read the contents of a file at the given path."
+    
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "The file path to read"
+                }
+            },
+            "required": ["path"]
+        }
+    
+    async def execute(self, path: str, **kwargs: Any) -> str:
+        try:
+            file_path = Path(path).expanduser()
+            if not file_path.exists():
+                return f"Error: File not found: {path}"
+            if not file_path.is_file():
+                return f"Error: Not a file: {path}"
+            
+            content = file_path.read_text(encoding="utf-8")
+            return content
+        except PermissionError:
+            return f"Error: Permission denied: {path}"
+        except Exception as e:
+            return f"Error reading file: {str(e)}"
+
+
+class WriteFileTool(Tool):
+    """Tool to write content to a file."""
+    
+    @property
+    def name(self) -> str:
+        return "write_file"
+    
+    @property
+    def description(self) -> str:
+        return "Write content to a file at the given path. Creates parent directories if needed."
+    
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "The file path to write to"
+                },
+                "content": {
+                    "type": "string",
+                    "description": "The content to write"
+                }
+            },
+            "required": ["path", "content"]
+        }
+    
+    async def execute(self, path: str, content: str, **kwargs: Any) -> str:
+        try:
+            file_path = Path(path).expanduser()
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+            file_path.write_text(content, encoding="utf-8")
+            return f"Successfully wrote {len(content)} bytes to {path}"
+        except PermissionError:
+            return f"Error: Permission denied: {path}"
+        except Exception as e:
+            return f"Error writing file: {str(e)}"
+
+
+class EditFileTool(Tool):
+    """Tool to edit a file by replacing text."""
+    
+    @property
+    def name(self) -> str:
+        return "edit_file"
+    
+    @property
+    def description(self) -> str:
+        return "Edit a file by replacing old_text with new_text. The old_text must exist exactly in the file."
+    
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "The file path to edit"
+                },
+                "old_text": {
+                    "type": "string",
+                    "description": "The exact text to find and replace"
+                },
+                "new_text": {
+                    "type": "string",
+                    "description": "The text to replace with"
+                }
+            },
+            "required": ["path", "old_text", "new_text"]
+        }
+    
+    async def execute(self, path: str, old_text: str, new_text: str, **kwargs: Any) -> str:
+        try:
+            file_path = Path(path).expanduser()
+            if not file_path.exists():
+                return f"Error: File not found: {path}"
+            
+            content = file_path.read_text(encoding="utf-8")
+            
+            if old_text not in content:
+                return f"Error: old_text not found in file. Make sure it matches exactly."
+            
+            # Count occurrences
+            count = content.count(old_text)
+            if count > 1:
+                return f"Warning: old_text appears {count} times. Please provide more context to make it unique."
+            
+            new_content = content.replace(old_text, new_text, 1)
+            file_path.write_text(new_content, encoding="utf-8")
+            
+            return f"Successfully edited {path}"
+        except PermissionError:
+            return f"Error: Permission denied: {path}"
+        except Exception as e:
+            return f"Error editing file: {str(e)}"
+
+
+class ListDirTool(Tool):
+    """Tool to list directory contents."""
+    
+    @property
+    def name(self) -> str:
+        return "list_dir"
+    
+    @property
+    def description(self) -> str:
+        return "List the contents of a directory."
+    
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "The directory path to list"
+                }
+            },
+            "required": ["path"]
+        }
+    
+    async def execute(self, path: str, **kwargs: Any) -> str:
+        try:
+            dir_path = Path(path).expanduser()
+            if not dir_path.exists():
+                return f"Error: Directory not found: {path}"
+            if not dir_path.is_dir():
+                return f"Error: Not a directory: {path}"
+            
+            items = []
+            for item in sorted(dir_path.iterdir()):
+                prefix = "📁 " if item.is_dir() else "📄 "
+                items.append(f"{prefix}{item.name}")
+            
+            if not items:
+                return f"Directory {path} is empty"
+            
+            return "\n".join(items)
+        except PermissionError:
+            return f"Error: Permission denied: {path}"
+        except Exception as e:
+            return f"Error listing directory: {str(e)}"

ragnarbot/agent/tools/message.py

@@ -0,0 +1,86 @@
+"""Message tool for sending messages to users."""
+
+from typing import Any, Callable, Awaitable
+
+from ragnarbot.agent.tools.base import Tool
+from ragnarbot.bus.events import OutboundMessage
+
+
+class MessageTool(Tool):
+    """Tool to send messages to users on chat channels."""
+    
+    def __init__(
+        self, 
+        send_callback: Callable[[OutboundMessage], Awaitable[None]] | None = None,
+        default_channel: str = "",
+        default_chat_id: str = ""
+    ):
+        self._send_callback = send_callback
+        self._default_channel = default_channel
+        self._default_chat_id = default_chat_id
+    
+    def set_context(self, channel: str, chat_id: str) -> None:
+        """Set the current message context."""
+        self._default_channel = channel
+        self._default_chat_id = chat_id
+    
+    def set_send_callback(self, callback: Callable[[OutboundMessage], Awaitable[None]]) -> None:
+        """Set the callback for sending messages."""
+        self._send_callback = callback
+    
+    @property
+    def name(self) -> str:
+        return "message"
+    
+    @property
+    def description(self) -> str:
+        return "Send a message to the user. Use this when you want to communicate something."
+    
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "content": {
+                    "type": "string",
+                    "description": "The message content to send"
+                },
+                "channel": {
+                    "type": "string",
+                    "description": "Optional: target channel (e.g. telegram)"
+                },
+                "chat_id": {
+                    "type": "string",
+                    "description": "Optional: target chat/user ID"
+                }
+            },
+            "required": ["content"]
+        }
+    
+    async def execute(
+        self, 
+        content: str, 
+        channel: str | None = None, 
+        chat_id: str | None = None,
+        **kwargs: Any
+    ) -> str:
+        channel = channel or self._default_channel
+        chat_id = chat_id or self._default_chat_id
+        
+        if not channel or not chat_id:
+            return "Error: No target channel/chat specified"
+        
+        if not self._send_callback:
+            return "Error: Message sending not configured"
+        
+        msg = OutboundMessage(
+            channel=channel,
+            chat_id=chat_id,
+            content=content
+        )
+        
+        try:
+            await self._send_callback(msg)
+            return f"Message sent to {channel}:{chat_id}"
+        except Exception as e:
+            return f"Error sending message: {str(e)}"

ragnarbot/agent/tools/registry.py

@@ -0,0 +1,73 @@
+"""Tool registry for dynamic tool management."""
+
+from typing import Any
+
+from ragnarbot.agent.tools.base import Tool
+
+
+class ToolRegistry:
+    """
+    Registry for agent tools.
+    
+    Allows dynamic registration and execution of tools.
+    """
+    
+    def __init__(self):
+        self._tools: dict[str, Tool] = {}
+    
+    def register(self, tool: Tool) -> None:
+        """Register a tool."""
+        self._tools[tool.name] = tool
+    
+    def unregister(self, name: str) -> None:
+        """Unregister a tool by name."""
+        self._tools.pop(name, None)
+    
+    def get(self, name: str) -> Tool | None:
+        """Get a tool by name."""
+        return self._tools.get(name)
+    
+    def has(self, name: str) -> bool:
+        """Check if a tool is registered."""
+        return name in self._tools
+    
+    def get_definitions(self) -> list[dict[str, Any]]:
+        """Get all tool definitions in OpenAI format."""
+        return [tool.to_schema() for tool in self._tools.values()]
+    
+    async def execute(self, name: str, params: dict[str, Any]) -> str:
+        """
+        Execute a tool by name with given parameters.
+        
+        Args:
+            name: Tool name.
+            params: Tool parameters.
+        
+        Returns:
+            Tool execution result as string.
+        
+        Raises:
+            KeyError: If tool not found.
+        """
+        tool = self._tools.get(name)
+        if not tool:
+            return f"Error: Tool '{name}' not found"
+
+        try:
+            errors = tool.validate_params(params)
+            if errors:
+                return f"Error: Invalid parameters for tool '{name}': " + "; ".join(errors)
+            return await tool.execute(**params)
+        except Exception as e:
+            return f"Error executing {name}: {str(e)}"
+    
+    @property
+    def tool_names(self) -> list[str]:
+        """Get list of registered tool names."""
+        return list(self._tools.keys())
+    
+    def __len__(self) -> int:
+        return len(self._tools)
+    
+    def __contains__(self, name: str) -> bool:
+        return name in self._tools

ragnarbot/agent/tools/shell.py

@@ -0,0 +1,141 @@
+"""Shell execution tool."""
+
+import asyncio
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+from ragnarbot.agent.tools.base import Tool
+
+
+class ExecTool(Tool):
+    """Tool to execute shell commands."""
+    
+    def __init__(
+        self,
+        timeout: int = 60,
+        working_dir: str | None = None,
+        deny_patterns: list[str] | None = None,
+        allow_patterns: list[str] | None = None,
+        restrict_to_workspace: bool = False,
+    ):
+        self.timeout = timeout
+        self.working_dir = working_dir
+        self.deny_patterns = deny_patterns or [
+            r"\brm\s+-[rf]{1,2}\b",          # rm -r, rm -rf, rm -fr
+            r"\bdel\s+/[fq]\b",              # del /f, del /q
+            r"\brmdir\s+/s\b",               # rmdir /s
+            r"\b(format|mkfs|diskpart)\b",   # disk operations
+            r"\bdd\s+if=",                   # dd
+            r">\s*/dev/sd",                  # write to disk
+            r"\b(shutdown|reboot|poweroff)\b",  # system power
+            r":\(\)\s*\{.*\};\s*:",          # fork bomb
+        ]
+        self.allow_patterns = allow_patterns or []
+        self.restrict_to_workspace = restrict_to_workspace
+    
+    @property
+    def name(self) -> str:
+        return "exec"
+    
+    @property
+    def description(self) -> str:
+        return "Execute a shell command and return its output. Use with caution."
+    
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "description": "The shell command to execute"
+                },
+                "working_dir": {
+                    "type": "string",
+                    "description": "Optional working directory for the command"
+                }
+            },
+            "required": ["command"]
+        }
+    
+    async def execute(self, command: str, working_dir: str | None = None, **kwargs: Any) -> str:
+        cwd = working_dir or self.working_dir or os.getcwd()
+        guard_error = self._guard_command(command, cwd)
+        if guard_error:
+            return guard_error
+        
+        try:
+            process = await asyncio.create_subprocess_shell(
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=cwd,
+            )
+            
+            try:
+                stdout, stderr = await asyncio.wait_for(
+                    process.communicate(),
+                    timeout=self.timeout
+                )
+            except asyncio.TimeoutError:
+                process.kill()
+                return f"Error: Command timed out after {self.timeout} seconds"
+            
+            output_parts = []
+            
+            if stdout:
+                output_parts.append(stdout.decode("utf-8", errors="replace"))
+            
+            if stderr:
+                stderr_text = stderr.decode("utf-8", errors="replace")
+                if stderr_text.strip():
+                    output_parts.append(f"STDERR:\n{stderr_text}")
+            
+            if process.returncode != 0:
+                output_parts.append(f"\nExit code: {process.returncode}")
+            
+            result = "\n".join(output_parts) if output_parts else "(no output)"
+            
+            # Truncate very long output
+            max_len = 10000
+            if len(result) > max_len:
+                result = result[:max_len] + f"\n... (truncated, {len(result) - max_len} more chars)"
+            
+            return result
+            
+        except Exception as e:
+            return f"Error executing command: {str(e)}"
+
+    def _guard_command(self, command: str, cwd: str) -> str | None:
+        """Best-effort safety guard for potentially destructive commands."""
+        cmd = command.strip()
+        lower = cmd.lower()
+
+        for pattern in self.deny_patterns:
+            if re.search(pattern, lower):
+                return "Error: Command blocked by safety guard (dangerous pattern detected)"
+
+        if self.allow_patterns:
+            if not any(re.search(p, lower) for p in self.allow_patterns):
+                return "Error: Command blocked by safety guard (not in allowlist)"
+
+        if self.restrict_to_workspace:
+            if "..\\" in cmd or "../" in cmd:
+                return "Error: Command blocked by safety guard (path traversal detected)"
+
+            cwd_path = Path(cwd).resolve()
+
+            win_paths = re.findall(r"[A-Za-z]:\\[^\\\"']+", cmd)
+            posix_paths = re.findall(r"/[^\s\"']+", cmd)
+
+            for raw in win_paths + posix_paths:
+                try:
+                    p = Path(raw).resolve()
+                except Exception:
+                    continue
+                if cwd_path not in p.parents and p != cwd_path:
+                    return "Error: Command blocked by safety guard (path outside working dir)"
+
+        return None

ragnarbot/agent/tools/spawn.py

@@ -0,0 +1,65 @@
+"""Spawn tool for creating background subagents."""
+
+from typing import Any, TYPE_CHECKING
+
+from ragnarbot.agent.tools.base import Tool
+
+if TYPE_CHECKING:
+    from ragnarbot.agent.subagent import SubagentManager
+
+
+class SpawnTool(Tool):
+    """
+    Tool to spawn a subagent for background task execution.
+    
+    The subagent runs asynchronously and announces its result back
+    to the main agent when complete.
+    """
+    
+    def __init__(self, manager: "SubagentManager"):
+        self._manager = manager
+        self._origin_channel = "cli"
+        self._origin_chat_id = "direct"
+    
+    def set_context(self, channel: str, chat_id: str) -> None:
+        """Set the origin context for subagent announcements."""
+        self._origin_channel = channel
+        self._origin_chat_id = chat_id
+    
+    @property
+    def name(self) -> str:
+        return "spawn"
+    
+    @property
+    def description(self) -> str:
+        return (
+            "Spawn a subagent to handle a task in the background. "
+            "Use this for complex or time-consuming tasks that can run independently. "
+            "The subagent will complete the task and report back when done."
+        )
+    
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "task": {
+                    "type": "string",
+                    "description": "The task for the subagent to complete",
+                },
+                "label": {
+                    "type": "string",
+                    "description": "Optional short label for the task (for display)",
+                },
+            },
+            "required": ["task"],
+        }
+    
+    async def execute(self, task: str, label: str | None = None, **kwargs: Any) -> str:
+        """Spawn a subagent to execute the given task."""
+        return await self._manager.spawn(
+            task=task,
+            label=label,
+            origin_channel=self._origin_channel,
+            origin_chat_id=self._origin_chat_id,
+        )