code-muse 0.0.1__py3-none-any.whl

code_muse/plugins/universal_constructor/models.py

@@ -0,0 +1,136 @@
+"""Pydantic models for Universal Constructor tools and responses.
+
+This module defines the data structures used throughout the UC plugin
+for representing tool metadata, tool information, and operation responses.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ToolMeta(BaseModel):
+    """Metadata for a UC tool.
+
+    This is the structure expected in the TOOL_META dictionary
+    at the top of each tool file.
+    """
+
+    name: str = Field(..., description="Human-readable tool name")
+    namespace: str = Field(
+        default="", description="Namespace for the tool (from subdirectory path)"
+    )
+    description: str = Field(..., description="What the tool does")
+    enabled: bool = Field(default=True, description="Whether the tool is active")
+    version: str = Field(default="1.0.0", description="Semantic version of the tool")
+    author: str = Field(default="", description="Tool author or creator")
+    created_at: str | None = Field(
+        default=None, description="When the tool was created (ISO format string)"
+    )
+
+    model_config = {"extra": "allow"}  # Allow additional metadata fields
+
+
+class UCToolInfo(BaseModel):
+    """Full information about a UC tool.
+
+    Combines metadata with runtime information like function signature
+    and source file location.
+    """
+
+    meta: ToolMeta = Field(..., description="Tool metadata")
+    signature: str = Field(..., description="Function signature string")
+    source_path: str = Field(..., description="Path to the tool source file")
+    function_name: str = Field(default="", description="Name of the callable function")
+    docstring: str | None = Field(default=None, description="Function docstring")
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    @property
+    def full_name(self) -> str:
+        """Get the fully qualified tool name including namespace."""
+        if self.meta.namespace:
+            return f"{self.meta.namespace}.{self.meta.name}"
+        return self.meta.name
+
+
+# Response models for UC operations
+
+
+class UCListOutput(BaseModel):
+    """Response model for listing UC tools."""
+
+    tools: list[UCToolInfo] = Field(
+        default_factory=list, description="List of available tools"
+    )
+    total_count: int = Field(default=0, description="Total number of tools")
+    enabled_count: int = Field(default=0, description="Number of enabled tools")
+    error: str | None = Field(default=None, description="Error message if any")
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class UCCallOutput(BaseModel):
+    """Response model for calling a UC tool."""
+
+    success: bool = Field(..., description="Whether the call succeeded")
+    tool_name: str = Field(..., description="Name of the tool that was called")
+    result: Any = Field(default=None, description="Return value from the tool")
+    error: str | None = Field(default=None, description="Error message if failed")
+    execution_time: float | None = Field(
+        default=None, description="Execution time in seconds"
+    )
+    source_preview: str | None = Field(
+        default=None, description="Preview of the tool's source code that was executed"
+    )
+
+
+class UCCreateOutput(BaseModel):
+    """Response model for creating a UC tool."""
+
+    success: bool = Field(..., description="Whether creation succeeded")
+    tool_name: str = Field(default="", description="Name of the created tool")
+    source_path: str | None = Field(
+        default=None, description="Path where tool was saved"
+    )
+    preview: str | None = Field(
+        default=None, description="Preview of the first 10 lines of source code"
+    )
+    error: str | None = Field(default=None, description="Error message if failed")
+    validation_warnings: list[str] = Field(
+        default_factory=list, description="Non-fatal validation warnings"
+    )
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class UCUpdateOutput(BaseModel):
+    """Response model for updating a UC tool."""
+
+    success: bool = Field(..., description="Whether update succeeded")
+    tool_name: str = Field(default="", description="Name of the updated tool")
+    source_path: str | None = Field(
+        default=None, description="Path to the updated tool"
+    )
+    preview: str | None = Field(
+        default=None, description="Preview of the first 10 lines of updated source code"
+    )
+    error: str | None = Field(default=None, description="Error message if failed")
+    changes_applied: list[str] = Field(
+        default_factory=list, description="List of changes that were applied"
+    )
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class UCInfoOutput(BaseModel):
+    """Response model for getting info about a specific UC tool."""
+
+    success: bool = Field(..., description="Whether lookup succeeded")
+    tool: UCToolInfo | None = Field(
+        default=None, description="Tool information if found"
+    )
+    source_code: str | None = Field(default=None, description="Source code of the tool")
+    error: str | None = Field(default=None, description="Error message if failed")
+
+    model_config = {"arbitrary_types_allowed": True}

code_muse/plugins/universal_constructor/register_callbacks.py

@@ -0,0 +1,47 @@
+"""Callback registration for the Universal Constructor plugin.
+
+This module registers callbacks to integrate UC with the rest of
+Muse. It ensures the plugin is properly loaded and initialized.
+"""
+
+import logging
+
+from code_muse.callbacks import register_callback
+
+from . import USER_UC_DIR
+from .registry import get_registry
+
+logger = logging.getLogger(__name__)
+
+
+def _on_startup() -> None:
+    """Initialize UC plugin on application startup."""
+    from code_muse.config import get_universal_constructor_enabled
+
+    # Skip initialization if UC is disabled
+    if not get_universal_constructor_enabled():
+        logger.debug("Universal Constructor is disabled, skipping initialization")
+        return
+
+    logger.debug("Universal Constructor plugin initializing...")
+
+    # Ensure the user tools directory exists
+    USER_UC_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Do an initial scan of tools (lazy - will happen on first access)
+    registry = get_registry()
+    logger.debug(f"UC registry initialized, tools dir: {registry._tools_dir}")
+
+    # Log plugin info at startup
+    tools = registry.list_tools(include_disabled=True)
+    enabled = [t for t in tools if t.meta.enabled]
+    logger.debug(
+        f"UC plugin loaded: {len(enabled)}/{len(tools)} tools enabled "
+        f"from {USER_UC_DIR}"
+    )
+
+
+# Register startup callback
+register_callback("startup", _on_startup)
+
+logger.debug("Universal Constructor plugin callbacks registered")

code_muse/plugins/universal_constructor/registry.py

@@ -0,0 +1,390 @@
+"""UC Tool Registry - discovers and manages user-created tools.
+
+This module provides the core registry that scans the user's UC directory,
+loads tool metadata, extracts function signatures, and provides access
+to enabled tools for the LLM.
+
+Hardened to parse TOOL_META via AST before importing, and to skip
+disabled or untrusted tools during scan.
+"""
+
+import ast
+import importlib.util
+import inspect
+import logging
+import sys
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+from types import ModuleType
+
+from . import USER_UC_DIR
+from .models import ToolMeta, UCToolInfo
+from .safety import (
+    UCApprovalStore,
+    check_code_safety,
+    is_path_within_uc_dir,
+    validate_full_tool_name,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class UCRegistry:
+    """Registry for discovering and managing UC tools.
+
+    Scans the user's UC directory recursively, loading tool metadata
+    and providing access to enabled tools. Supports namespacing via
+    subdirectories (e.g., api/weather.py → "api.weather").
+    """
+
+    def __init__(self, tools_dir: Path | None = None):
+        """Initialize the registry.
+
+        Args:
+            tools_dir: Directory to scan for tools. Defaults to USER_UC_DIR.
+        """
+        self._tools_dir = tools_dir or USER_UC_DIR
+        self._tools: dict[str, UCToolInfo] = {}
+        self._modules: dict[str, ModuleType] = {}
+        self._last_scan: datetime | None = None
+
+    def ensure_tools_dir(self) -> Path:
+        """Ensure the tools directory exists.
+
+        Returns:
+            Path to the tools directory.
+        """
+        self._tools_dir.mkdir(parents=True, exist_ok=True)
+        return self._tools_dir
+
+    def scan(self) -> int:
+        """Scan the tools directory and load all tools.
+
+        Returns:
+            Number of tools found.
+        """
+        self._tools.clear()
+        self._modules.clear()
+
+        if not self._tools_dir.exists():
+            logger.debug(f"Tools directory does not exist: {self._tools_dir}")
+            return 0
+
+        # Find all Python files recursively
+        tool_files = list(self._tools_dir.rglob("*.py"))
+
+        for tool_file in tool_files:
+            # Skip __init__.py and hidden files
+            if tool_file.name.startswith("_") or tool_file.name.startswith("."):
+                continue
+
+            try:
+                tool_info = self._load_tool_file(tool_file)
+                if tool_info:
+                    self._tools[tool_info.full_name] = tool_info
+                    logger.debug(f"Loaded tool: {tool_info.full_name}")
+            except Exception as e:
+                logger.warning(f"Failed to load tool from {tool_file}: {e}")
+
+        self._last_scan = datetime.now()
+        logger.info(f"Scanned {len(self._tools)} tools from {self._tools_dir}")
+        return len(self._tools)
+
+    def _load_tool_file(self, file_path: Path) -> UCToolInfo | None:
+        """Load a tool from a Python file.
+
+        Hardened flow:
+        1. Parse TOOL_META via AST before importing the module.
+        2. Validate tool name for path traversal / reserved names.
+        3. Skip disabled tools (no import needed).
+        4. For enabled tools with dangerous code, require approval.
+        5. Only import if the tool passes safety and trust checks.
+
+        Args:
+            file_path: Path to the Python file.
+
+        Returns:
+            UCToolInfo if valid tool, None otherwise.
+        """
+        # Safety: file must be within tools directory
+        if not is_path_within_uc_dir(file_path, self._tools_dir):
+            logger.warning(f"Tool file outside UC directory: {file_path}")
+            return None
+
+        # Calculate namespace from relative path
+        try:
+            rel_path = file_path.relative_to(self._tools_dir)
+            namespace_parts = list(rel_path.parent.parts)
+            namespace = ".".join(namespace_parts) if namespace_parts else ""
+        except ValueError:
+            namespace = ""
+
+        # Step 1: Parse TOOL_META via AST without importing
+        try:
+            code = file_path.read_text(encoding="utf-8")
+            tree = ast.parse(code)
+        except (SyntaxError, OSError) as e:
+            logger.warning(f"Cannot parse {file_path}: {e}")
+            return None
+
+        raw_meta = self._extract_tool_meta_from_ast(tree)
+        if raw_meta is None:
+            logger.debug(f"No TOOL_META found in {file_path}")
+            return None
+        if not isinstance(raw_meta, dict):
+            logger.warning(f"TOOL_META is not a dict in {file_path}")
+            return None
+
+        # Set namespace from directory structure
+        raw_meta["namespace"] = namespace
+
+        # Parse metadata
+        try:
+            meta = ToolMeta(**raw_meta)
+        except Exception as e:
+            logger.warning(f"Invalid TOOL_META in {file_path}: {e}")
+            return None
+
+        # Validate tool name
+        full_name = f"{namespace}.{meta.name}" if namespace else meta.name
+        name_error = validate_full_tool_name(full_name)
+        if name_error:
+            logger.warning(f"Invalid tool name '{full_name}': {name_error}")
+            return None
+
+        # Step 2: Skip disabled tools without importing
+        if not meta.enabled:
+            return UCToolInfo(
+                meta=meta,
+                signature=f"{meta.name}(...)",
+                source_path=str(file_path),
+                function_name=meta.name,
+                docstring=None,
+            )
+
+        # Step 3: Safety check for enabled tools
+        safety = check_code_safety(code)
+        if safety.blocked:
+            logger.warning(
+                f"Tool '{full_name}' blocked by safety check: {safety.errors}"
+            )
+            return UCToolInfo(
+                meta=meta,
+                signature=f"{meta.name}(...)",
+                source_path=str(file_path),
+                function_name=meta.name,
+                docstring=None,
+            )
+
+        if safety.requires_approval:
+            approval_store = UCApprovalStore()
+            if not approval_store.is_approved(full_name, safety.code_hash):
+                logger.warning(
+                    f"Tool '{full_name}' requires approval (dangerous patterns). "
+                    f"Run /approve-uc {full_name} to enable."
+                )
+                return UCToolInfo(
+                    meta=meta,
+                    signature=f"{meta.name}(...)",
+                    source_path=str(file_path),
+                    function_name=meta.name,
+                    docstring=None,
+                )
+
+        # Step 4: Only import if we passed safety/trust
+        module = self._load_module(file_path)
+        if module is None:
+            return None
+
+        # Find the callable function
+        func, func_name = self._find_tool_function(module, meta.name)
+        if func is None:
+            logger.warning(f"No callable function found in {file_path}")
+            return None
+
+        # Extract signature
+        try:
+            sig = inspect.signature(func)
+            signature_str = f"{func_name}{sig}"
+        except ValueError, TypeError:
+            signature_str = f"{func_name}(...)"
+
+        # Extract docstring
+        docstring = inspect.getdoc(func)
+
+        # Store module reference for later calls
+        self._modules[full_name] = module
+
+        return UCToolInfo(
+            meta=meta,
+            signature=signature_str,
+            source_path=str(file_path),
+            function_name=func_name,
+            docstring=docstring,
+        )
+
+    @staticmethod
+    def _extract_tool_meta_from_ast(tree: ast.AST) -> dict | None:
+        """Extract TOOL_META dict from an AST without executing code."""
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if isinstance(target, ast.Name) and target.id == "TOOL_META":
+                        if isinstance(node.value, ast.Dict):
+                            try:
+                                meta_str = ast.unparse(node.value)
+                                return ast.literal_eval(meta_str)
+                            except ValueError, SyntaxError:
+                                return None
+        return None
+
+    def _load_module(self, file_path: Path) -> ModuleType | None:
+        """Load a Python module from a file path.
+
+        Args:
+            file_path: Path to the Python file.
+
+        Returns:
+            Loaded module or None if failed.
+        """
+        module_name = f"uc_tool_{file_path.stem}_{hash(str(file_path))}"
+
+        try:
+            spec = importlib.util.spec_from_file_location(module_name, file_path)
+            if spec is None or spec.loader is None:
+                return None
+
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[module_name] = module
+            spec.loader.exec_module(module)
+            return module
+        except Exception:
+            return None
+
+    def _find_tool_function(
+        self, module: ModuleType, tool_name: str
+    ) -> tuple[Callable | None, str]:
+        """Find the callable function in a tool module.
+
+        Looks for:
+        1. A function with the same name as the tool
+        2. A function named 'run'
+        3. A function named 'execute'
+        4. Any public function (not starting with _)
+
+        Args:
+            module: The loaded module.
+            tool_name: The tool name from metadata.
+
+        Returns:
+            Tuple of (function, function_name) or (None, "") if not found.
+        """
+        # Priority order for finding the function
+        candidates = [tool_name, "run", "execute"]
+
+        for name in candidates:
+            if hasattr(module, name):
+                func = getattr(module, name)
+                if callable(func) and not isinstance(func, type):
+                    return func, name
+
+        # Fall back to first public callable
+        for name in dir(module):
+            if name.startswith("_"):
+                continue
+            obj = getattr(module, name)
+            if callable(obj) and not isinstance(obj, type):
+                return obj, name
+
+        return None, ""
+
+    def list_tools(self, include_disabled: bool = False) -> list[UCToolInfo]:
+        """List all discovered tools.
+
+        Args:
+            include_disabled: Whether to include disabled tools.
+
+        Returns:
+            List of tool info objects.
+        """
+        if not self._tools:
+            self.scan()
+
+        tools = list(self._tools.values())
+        if not include_disabled:
+            tools = [t for t in tools if t.meta.enabled]
+
+        return sorted(tools, key=lambda t: t.full_name)
+
+    def get_tool(self, name: str) -> UCToolInfo | None:
+        """Get a specific tool by name.
+
+        Args:
+            name: Full tool name (including namespace).
+
+        Returns:
+            Tool info or None if not found.
+        """
+        if not self._tools:
+            self.scan()
+
+        return self._tools.get(name)
+
+    def get_tool_function(self, name: str) -> Callable | None:
+        """Get the callable function for a tool.
+
+        Args:
+            name: Full tool name (including namespace).
+
+        Returns:
+            Callable function or None if not found.
+        """
+        tool = self.get_tool(name)
+        if tool is None:
+            return None
+
+        module = self._modules.get(name)
+        if module is None:
+            return None
+
+        func, _ = self._find_tool_function(module, tool.meta.name)
+        return func
+
+    def load_tool_module(self, name: str) -> ModuleType | None:
+        """Get the loaded module for a tool.
+
+        Args:
+            name: Full tool name (including namespace).
+
+        Returns:
+            Module or None if not found.
+        """
+        if not self._tools:
+            self.scan()
+
+        return self._modules.get(name)
+
+    def reload(self) -> int:
+        """Force a rescan of all tools.
+
+        Returns:
+            Number of tools found.
+        """
+        return self.scan()
+
+
+# Global registry instance
+_registry: UCRegistry | None = None
+
+
+def get_registry() -> UCRegistry:
+    """Get the global UC registry instance.
+
+    Returns:
+        The global UCRegistry instance.
+    """
+    global _registry
+    if _registry is None:
+        _registry = UCRegistry()
+    return _registry