Initial commit

server/tools/base.py

@@ -0,0 +1,71 @@
+"""
+tools/base.py — BaseTool abstract class.
+
+All tools inherit from this. The tool registry discovers them and builds
+the schema list sent to the AI provider on every agent call.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass
+class ToolResult:
+    """Normalised return value from every tool execution."""
+    success: bool
+    data: dict | list | str | None = None
+    error: str | None = None
+
+    def to_dict(self) -> dict:
+        if self.success:
+            return {"success": True, "data": self.data}
+        result: dict = {"success": False, "error": self.error}
+        if self.data is not None:
+            result["data"] = self.data
+        return result
+
+
+class BaseTool(ABC):
+    """
+    Abstract base for all aide tools.
+
+    Subclasses must set class-level attributes:
+        name            — used in tool schema and audit log
+        description     — what the AI sees
+        input_schema    — JSON Schema for parameters (Anthropic-native format)
+
+    Optional overrides:
+        requires_confirmation       — default False
+        allowed_in_scheduled_tasks  — default True
+    """
+
+    name: str
+    description: str
+    input_schema: dict
+
+    requires_confirmation: bool = False
+    allowed_in_scheduled_tasks: bool = True
+
+    @abstractmethod
+    async def execute(self, **kwargs) -> ToolResult:
+        """
+        Run the tool. Never raises — always returns a ToolResult.
+        The dispatcher catches any unexpected exceptions as a safety net.
+        """
+
+    def get_schema(self) -> dict:
+        """Return the tool schema in aide-internal / Anthropic-native format."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.input_schema,
+        }
+
+    def confirmation_description(self, **kwargs) -> str:
+        """
+        Human-readable description of the action shown to the user
+        when confirmation is required. Override for better messages.
+        """
+        args_str = ", ".join(f"{k}={v!r}" for k, v in kwargs.items())
+        return f"{self.name}({args_str})"