codexa 0.4.0__py3-none-any.whl

semantic_code_intelligence/tools/executor.py

@@ -0,0 +1,232 @@
+"""Tool execution engine — validates, routes, and executes tool invocations.
+
+Wraps the existing ``ToolRegistry`` with:
+- Argument validation against ``TOOL_DEFINITIONS`` schemas
+- Structured ``ToolInvocation`` → ``ToolExecutionResult`` pipeline
+- Plugin-registered tool support via ``REGISTER_TOOL`` hook
+- Safety guardrails (deterministic, no arbitrary code execution)
+
+Usage::
+
+    executor = ToolExecutor(Path("."))
+    result = executor.execute(ToolInvocation(tool_name="semantic_search",
+                                              arguments={"query": "parse"}))
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+from semantic_code_intelligence.tools import TOOL_DEFINITIONS, ToolRegistry
+from semantic_code_intelligence.tools.protocol import (
+    ToolError,
+    ToolErrorCode,
+    ToolExecutionResult,
+    ToolInvocation,
+)
+from semantic_code_intelligence.utils.logging import get_logger
+
+logger = get_logger("tools.executor")
+
+# Type alias for plugin-registered tool handlers
+ToolHandler = Callable[..., dict[str, Any]]
+
+
+# ---------------------------------------------------------------------------
+# Allowed tool names (safety guardrail)
+# ---------------------------------------------------------------------------
+
+_BUILTIN_TOOL_NAMES: frozenset[str] = frozenset(
+    t["name"] for t in TOOL_DEFINITIONS
+)
+
+
+class ToolExecutor:
+    """Validates and executes tool invocations against the registry.
+
+    Adds a structured protocol layer on top of ToolRegistry:
+    - Input validation against declared schemas
+    - Typed error handling with ToolError / ToolErrorCode
+    - Plugin-registered tool dispatch
+    - Timing and correlation tracking
+    """
+
+    def __init__(self, project_root: Path) -> None:
+        self._registry = ToolRegistry(project_root)
+        self._plugin_tools: dict[str, dict[str, Any]] = {}
+        self._plugin_handlers: dict[str, ToolHandler] = {}
+
+    # ── tool discovery ────────────────────────────────────────────────
+
+    @property
+    def available_tools(self) -> list[dict[str, Any]]:
+        """Return schemas of all available tools (built-in + plugin)."""
+        tools = list(TOOL_DEFINITIONS)
+        for name, schema in self._plugin_tools.items():
+            tools.append(schema)
+        return tools
+
+    def list_tool_names(self) -> list[str]:
+        """Return names of all available tools."""
+        return [t["name"] for t in self.available_tools]
+
+    def get_tool_schema(self, tool_name: str) -> dict[str, Any] | None:
+        """Return the schema definition for a specific tool, or None."""
+        for t in self.available_tools:
+            if t["name"] == tool_name:
+                return t
+        return None
+
+    # ── plugin tool registration ──────────────────────────────────────
+
+    def register_plugin_tool(
+        self,
+        name: str,
+        description: str,
+        parameters: dict[str, Any],
+        handler: ToolHandler,
+    ) -> None:
+        """Register a tool provided by a plugin.
+
+        Args:
+            name: Tool name (must not collide with built-in names).
+            description: Human-readable purpose of the tool.
+            parameters: Parameter schema matching TOOL_DEFINITIONS format.
+            handler: Callable(**kwargs) → dict[str, Any].
+        """
+        if name in _BUILTIN_TOOL_NAMES:
+            raise ValueError(
+                f"Cannot register plugin tool '{name}': collides with built-in tool"
+            )
+        self._plugin_tools[name] = {
+            "name": name,
+            "description": description,
+            "parameters": parameters,
+            "source": "plugin",
+        }
+        self._plugin_handlers[name] = handler
+        logger.info("Registered plugin tool: %s", name)
+
+    def unregister_plugin_tool(self, name: str) -> bool:
+        """Remove a plugin-registered tool. Returns True if it existed."""
+        removed = name in self._plugin_tools
+        self._plugin_tools.pop(name, None)
+        self._plugin_handlers.pop(name, None)
+        return removed
+
+    # ── validation ────────────────────────────────────────────────────
+
+    def _validate_arguments(
+        self, invocation: ToolInvocation
+    ) -> ToolError | None:
+        """Validate invocation arguments against the tool schema.
+
+        Returns a ToolError if validation fails, otherwise None.
+        """
+        schema = self.get_tool_schema(invocation.tool_name)
+        if schema is None:
+            return ToolError(
+                tool_name=invocation.tool_name,
+                error_code=ToolErrorCode.UNKNOWN_TOOL,
+                error_message=f"Unknown tool: {invocation.tool_name}",
+                request_id=invocation.request_id,
+            )
+
+        params_schema = schema.get("parameters", {})
+        for param_name, param_def in params_schema.items():
+            if param_def.get("required", False) and param_name not in invocation.arguments:
+                return ToolError(
+                    tool_name=invocation.tool_name,
+                    error_code=ToolErrorCode.MISSING_REQUIRED_ARG,
+                    error_message=f"Missing required argument: {param_name}",
+                    request_id=invocation.request_id,
+                )
+
+        return None
+
+    # ── execution ─────────────────────────────────────────────────────
+
+    def execute(self, invocation: ToolInvocation) -> ToolExecutionResult:
+        """Execute a tool invocation with full validation and error handling.
+
+        Pipeline:
+        1. Validate tool name and arguments
+        2. Route to ToolRegistry (built-in) or plugin handler
+        3. Wrap result in ToolExecutionResult with timing
+        """
+        # 1. validate
+        validation_error = self._validate_arguments(invocation)
+        if validation_error is not None:
+            return ToolExecutionResult(
+                tool_name=invocation.tool_name,
+                request_id=invocation.request_id,
+                success=False,
+                error=validation_error,
+            )
+
+        # 2. route + execute
+        start = time.monotonic()
+        try:
+            if invocation.tool_name in self._plugin_handlers:
+                # Plugin tool
+                handler = self._plugin_handlers[invocation.tool_name]
+                data = handler(**invocation.arguments)
+                success = True
+                error = None
+            else:
+                # Built-in tool via ToolRegistry
+                tool_result = self._registry.invoke(
+                    invocation.tool_name, **invocation.arguments
+                )
+                data = tool_result.to_dict()
+                success = tool_result.success
+                error = None
+                if not success:
+                    error = ToolError(
+                        tool_name=invocation.tool_name,
+                        error_code=ToolErrorCode.EXECUTION_ERROR,
+                        error_message=tool_result.error or "Tool execution failed",
+                        request_id=invocation.request_id,
+                    )
+        except Exception as exc:
+            elapsed = (time.monotonic() - start) * 1000
+            logger.exception("Tool execution failed: %s", invocation.tool_name)
+            return ToolExecutionResult(
+                tool_name=invocation.tool_name,
+                request_id=invocation.request_id,
+                success=False,
+                error=ToolError(
+                    tool_name=invocation.tool_name,
+                    error_code=ToolErrorCode.EXECUTION_ERROR,
+                    error_message=str(exc),
+                    request_id=invocation.request_id,
+                ),
+                execution_time_ms=elapsed,
+            )
+
+        elapsed = (time.monotonic() - start) * 1000
+
+        # 3. wrap result
+        return ToolExecutionResult(
+            tool_name=invocation.tool_name,
+            request_id=invocation.request_id,
+            success=success,
+            result_payload=data if success else {},
+            error=error,
+            execution_time_ms=elapsed,
+        )
+
+    def execute_batch(
+        self, invocations: list[ToolInvocation]
+    ) -> list[ToolExecutionResult]:
+        """Execute multiple tool invocations sequentially."""
+        return [self.execute(inv) for inv in invocations]
+
+    # ── convenience ───────────────────────────────────────────────────
+
+    @property
+    def registry(self) -> ToolRegistry:
+        """Access the underlying ToolRegistry (for indexing etc.)."""
+        return self._registry

semantic_code_intelligence/tools/protocol.py

@@ -0,0 +1,200 @@
+"""Tool invocation protocol — structured request/response types for AI agent tool use.
+
+Defines the data structures that AI coding agents use to invoke CodexA
+tools in a deterministic, type-safe manner:
+
+- ``ToolInvocation``: a request to execute a specific tool with arguments
+- ``ToolExecutionResult``: the structured outcome of a tool execution
+- ``ToolError``: a typed error emitted when a tool invocation fails
+
+All types are JSON-serializable with ``to_dict()`` / ``from_dict()``
+round-trip support, so agents can reliably parse and construct them.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# Error codes
+# ---------------------------------------------------------------------------
+
+class ToolErrorCode(str, Enum):
+    """Typed error codes for tool failures."""
+
+    UNKNOWN_TOOL = "unknown_tool"
+    INVALID_ARGUMENTS = "invalid_arguments"
+    MISSING_REQUIRED_ARG = "missing_required_arg"
+    EXECUTION_ERROR = "execution_error"
+    TIMEOUT = "timeout"
+    PERMISSION_DENIED = "permission_denied"
+
+
+# ---------------------------------------------------------------------------
+# Tool Invocation (request)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ToolInvocation:
+    """A request to execute a specific CodexA tool.
+
+    Attributes:
+        tool_name: Name of the tool to invoke (must match a registered tool).
+        arguments: Key-value arguments required by the tool.
+        request_id: Caller-assigned correlation ID (auto-generated if empty).
+        timestamp: Unix timestamp of the invocation.
+    """
+
+    tool_name: str
+    arguments: dict[str, Any] = field(default_factory=dict)
+    request_id: str = ""
+    timestamp: float = 0.0
+
+    def __post_init__(self) -> None:
+        if not self.request_id:
+            self.request_id = uuid.uuid4().hex[:12]
+        if self.timestamp == 0.0:
+            self.timestamp = time.time()
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the invocation to a plain dictionary."""
+        return {
+            "tool_name": self.tool_name,
+            "arguments": self.arguments,
+            "request_id": self.request_id,
+            "timestamp": self.timestamp,
+        }
+
+    def to_json(self, indent: int | None = None) -> str:
+        """Serialise the invocation to a JSON string."""
+        return json.dumps(self.to_dict(), indent=indent)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ToolInvocation:
+        """Construct a :class:`ToolInvocation` from a dictionary."""
+        return cls(
+            tool_name=data.get("tool_name", ""),
+            arguments=data.get("arguments", {}),
+            request_id=data.get("request_id", ""),
+            timestamp=data.get("timestamp", 0.0),
+        )
+
+    @classmethod
+    def from_json(cls, text: str) -> ToolInvocation:
+        """Construct a :class:`ToolInvocation` from a JSON string."""
+        return cls.from_dict(json.loads(text))
+
+
+# ---------------------------------------------------------------------------
+# Tool Error
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ToolError:
+    """A typed error from a failed tool invocation.
+
+    Attributes:
+        tool_name: The tool that failed.
+        error_code: Machine-readable error classification.
+        error_message: Human-readable description of what went wrong.
+        request_id: Correlation ID from the original invocation.
+    """
+
+    tool_name: str
+    error_code: str
+    error_message: str
+    request_id: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the error to a plain dictionary."""
+        return {
+            "tool_name": self.tool_name,
+            "error_code": self.error_code,
+            "error_message": self.error_message,
+            "request_id": self.request_id,
+        }
+
+    def to_json(self, indent: int | None = None) -> str:
+        """Serialise the error to a JSON string."""
+        return json.dumps(self.to_dict(), indent=indent)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ToolError:
+        """Construct a :class:`ToolError` from a dictionary."""
+        return cls(
+            tool_name=data.get("tool_name", ""),
+            error_code=data.get("error_code", ""),
+            error_message=data.get("error_message", ""),
+            request_id=data.get("request_id", ""),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Tool Execution Result (response)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ToolExecutionResult:
+    """Structured outcome of a tool invocation.
+
+    Attributes:
+        tool_name: Name of the tool that was executed.
+        request_id: Correlation ID from the original invocation.
+        success: Whether the tool completed without error.
+        result_payload: Tool output data (only present when success=True).
+        error: Typed error (only present when success=False).
+        execution_time_ms: Wall-clock execution time in milliseconds.
+        timestamp: Unix timestamp of result creation.
+    """
+
+    tool_name: str
+    request_id: str = ""
+    success: bool = True
+    result_payload: dict[str, Any] = field(default_factory=dict)
+    error: ToolError | None = None
+    execution_time_ms: float = 0.0
+    timestamp: float = 0.0
+
+    def __post_init__(self) -> None:
+        if self.timestamp == 0.0:
+            self.timestamp = time.time()
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the execution result to a plain dictionary."""
+        result: dict[str, Any] = {
+            "tool_name": self.tool_name,
+            "request_id": self.request_id,
+            "success": self.success,
+            "execution_time_ms": round(self.execution_time_ms, 2),
+            "timestamp": self.timestamp,
+        }
+        if self.success:
+            result["result_payload"] = self.result_payload
+        else:
+            result["error"] = self.error.to_dict() if self.error else None
+        return result
+
+    def to_json(self, indent: int | None = None) -> str:
+        """Serialise the execution result to a JSON string."""
+        return json.dumps(self.to_dict(), indent=indent)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ToolExecutionResult:
+        """Construct a :class:`ToolExecutionResult` from a dictionary."""
+        error_data = data.get("error")
+        error = ToolError.from_dict(error_data) if error_data else None
+        return cls(
+            tool_name=data.get("tool_name", ""),
+            request_id=data.get("request_id", ""),
+            success=data.get("success", True),
+            result_payload=data.get("result_payload", {}),
+            error=error,
+            execution_time_ms=data.get("execution_time_ms", 0.0),
+            timestamp=data.get("timestamp", 0.0),
+        )