kubiya-control-plane-api 0.9.15__py3-none-any.whl

control_plane_api/worker/utils/tool_validation.py

@@ -0,0 +1,332 @@
+"""
+Universal Tool Name Validation for All LLM Providers
+
+This module provides strict tool name validation that works across ALL major LLM providers:
+- OpenAI/Azure OpenAI
+- Anthropic Claude
+- Google Vertex AI/Gemini
+- AWS Bedrock
+
+The validation rules are the strictest common denominator to ensure compatibility everywhere.
+"""
+
+import re
+import structlog
+from typing import List, Tuple, Dict, Any
+
+logger = structlog.get_logger(__name__)
+
+# Universal tool name pattern - works for ALL LLM providers
+# Rules:
+# 1. Must start with letter (a-z, A-Z) or underscore (_)
+# 2. Can only contain: letters, numbers, underscores
+# 3. Maximum length: 64 characters
+# 4. Minimum length: 1 character
+UNIVERSAL_TOOL_NAME_PATTERN = re.compile(r'^[a-zA-Z_][a-zA-Z0-9_]{0,63}$')
+
+# Characters that are safe across all providers
+SAFE_CHARS = set('abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_')
+
+
+class ToolValidationError(Exception):
+    """Raised when tool validation fails and cannot be auto-fixed."""
+    pass
+
+
+def validate_tool_name(name: str, provider_context: str = "universal") -> Tuple[bool, str, List[str]]:
+    """
+    Validate a tool name against universal LLM provider requirements.
+
+    Args:
+        name: The tool name to validate
+        provider_context: Context string for logging (e.g., "vertex_ai", "openai")
+
+    Returns:
+        Tuple of (is_valid, error_message, list_of_violations)
+
+    Example:
+        >>> validate_tool_name("my_tool")
+        (True, "", [])
+        >>> validate_tool_name("123invalid")
+        (False, "Tool name must start with letter or underscore", ["invalid_start"])
+    """
+    violations = []
+
+    if not name:
+        return False, "Tool name cannot be empty", ["empty_name"]
+
+    if not isinstance(name, str):
+        return False, f"Tool name must be string, got {type(name)}", ["invalid_type"]
+
+    # Check length
+    if len(name) > 64:
+        violations.append("exceeds_max_length")
+
+    if len(name) == 0:
+        return False, "Tool name cannot be empty", ["empty_name"]
+
+    # Check first character
+    if not (name[0].isalpha() or name[0] == '_'):
+        violations.append("invalid_start")
+
+    # Check for invalid characters
+    invalid_chars = set()
+    for char in name:
+        if char not in SAFE_CHARS:
+            invalid_chars.add(char)
+
+    if invalid_chars:
+        violations.append(f"invalid_chars_{','.join(sorted(invalid_chars))}")
+
+    # Check full pattern
+    if not UNIVERSAL_TOOL_NAME_PATTERN.match(name):
+        if "invalid_start" not in violations and "exceeds_max_length" not in violations:
+            violations.append("pattern_mismatch")
+
+    if violations:
+        error_msg = f"Tool name '{name}' is invalid for {provider_context}: {', '.join(violations)}"
+        return False, error_msg, violations
+
+    return True, "", []
+
+
+def sanitize_tool_name(name: str, prefix: str = "", max_length: int = 64) -> str:
+    """
+    Sanitize a tool name to make it valid for all LLM providers.
+
+    This function aggressively cleans tool names to ensure compatibility:
+    - Replaces invalid characters with underscores
+    - Ensures it starts with letter or underscore
+    - Truncates to max_length
+    - Collapses multiple underscores
+
+    Args:
+        name: The tool name to sanitize
+        prefix: Optional prefix to add (useful for namespacing)
+        max_length: Maximum allowed length (default 64)
+
+    Returns:
+        Sanitized tool name that passes validation
+
+    Example:
+        >>> sanitize_tool_name("my-tool!")
+        "my_tool"
+        >>> sanitize_tool_name("123tool")
+        "_123tool"
+        >>> sanitize_tool_name("grounding::query_data")
+        "grounding_query_data"
+    """
+    if not name:
+        return "unnamed_tool"
+
+    # Add prefix if provided
+    if prefix:
+        name = f"{prefix}_{name}"
+
+    # Replace all invalid characters with underscores
+    sanitized = ""
+    for char in name:
+        if char in SAFE_CHARS:
+            sanitized += char
+        else:
+            sanitized += "_"
+
+    # Collapse multiple underscores
+    while "__" in sanitized:
+        sanitized = sanitized.replace("__", "_")
+
+    # Remove leading/trailing underscores except one if needed for start
+    sanitized = sanitized.strip("_")
+
+    # Ensure starts with letter or underscore
+    if sanitized and not (sanitized[0].isalpha() or sanitized[0] == '_'):
+        sanitized = f"_{sanitized}"
+
+    # Handle empty result
+    if not sanitized:
+        sanitized = "tool" if not prefix else prefix
+
+    # Truncate to max length
+    if len(sanitized) > max_length:
+        sanitized = sanitized[:max_length]
+        # Ensure we didn't cut in a way that makes it invalid
+        sanitized = sanitized.rstrip("_")
+
+    # Final validation - if still invalid, use fallback
+    is_valid, _, _ = validate_tool_name(sanitized)
+    if not is_valid:
+        logger.warning(f"Sanitization failed for '{name}', using fallback name")
+        return "sanitized_tool"
+
+    return sanitized
+
+
+def validate_and_sanitize_tools(
+    tools: List[Any],
+    tool_name_getter: callable = lambda t: getattr(t, 'name', str(t)),
+    auto_fix: bool = True,
+    provider_context: str = "universal"
+) -> Tuple[List[Any], List[Dict[str, Any]]]:
+    """
+    Validate and optionally sanitize a list of tools.
+
+    Args:
+        tools: List of tool objects to validate
+        tool_name_getter: Function to extract tool name from tool object
+        auto_fix: If True, sanitize invalid tool names; if False, filter them out
+        provider_context: Context for error messages
+
+    Returns:
+        Tuple of (validated_tools, validation_report)
+        - validated_tools: List of tools with valid names
+        - validation_report: List of dicts with validation details
+
+    Example:
+        >>> tools = [Tool(name="valid_tool"), Tool(name="invalid-tool!")]
+        >>> valid_tools, report = validate_and_sanitize_tools(tools)
+        >>> len(valid_tools)
+        2
+        >>> report[1]['action']
+        'sanitized'
+    """
+    validated_tools = []
+    validation_report = []
+
+    for i, tool in enumerate(tools):
+        try:
+            original_name = tool_name_getter(tool)
+            is_valid, error_msg, violations = validate_tool_name(original_name, provider_context)
+
+            if is_valid:
+                validated_tools.append(tool)
+                validation_report.append({
+                    "index": i,
+                    "original_name": original_name,
+                    "final_name": original_name,
+                    "action": "passed",
+                    "violations": []
+                })
+            else:
+                if auto_fix:
+                    # Try to sanitize
+                    sanitized_name = sanitize_tool_name(original_name)
+
+                    # Update tool name if possible
+                    if hasattr(tool, 'name'):
+                        tool.name = sanitized_name
+
+                    validated_tools.append(tool)
+                    validation_report.append({
+                        "index": i,
+                        "original_name": original_name,
+                        "final_name": sanitized_name,
+                        "action": "sanitized",
+                        "violations": violations,
+                        "error": error_msg
+                    })
+
+                    logger.warning(
+                        f"Tool name sanitized for {provider_context}: "
+                        f"'{original_name}' -> '{sanitized_name}' (violations: {violations})"
+                    )
+                else:
+                    # Filter out invalid tool
+                    validation_report.append({
+                        "index": i,
+                        "original_name": original_name,
+                        "final_name": None,
+                        "action": "filtered",
+                        "violations": violations,
+                        "error": error_msg
+                    })
+
+                    logger.error(
+                        f"Tool filtered out for {provider_context}: "
+                        f"'{original_name}' - {error_msg}"
+                    )
+        except Exception as e:
+            logger.error(f"Error validating tool at index {i}: {e}")
+            validation_report.append({
+                "index": i,
+                "original_name": "unknown",
+                "final_name": None,
+                "action": "error",
+                "violations": ["exception"],
+                "error": str(e)
+            })
+
+    return validated_tools, validation_report
+
+
+def validate_tool_definition(tool_def: Dict[str, Any]) -> Tuple[bool, str]:
+    """
+    Validate a tool definition dictionary (OpenAI/Anthropic format).
+
+    Args:
+        tool_def: Tool definition dict with 'name' and optionally 'function'
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    if not isinstance(tool_def, dict):
+        return False, "Tool definition must be a dictionary"
+
+    # Check for function.name (OpenAI format)
+    if "function" in tool_def:
+        if "name" not in tool_def["function"]:
+            return False, "Tool function missing 'name' field"
+        tool_name = tool_def["function"]["name"]
+    # Check for name (Anthropic format)
+    elif "name" in tool_def:
+        tool_name = tool_def["name"]
+    else:
+        return False, "Tool definition missing 'name' field"
+
+    is_valid, error_msg, _ = validate_tool_name(tool_name)
+    return is_valid, error_msg
+
+
+def get_provider_specific_requirements() -> Dict[str, Dict[str, Any]]:
+    """
+    Get provider-specific tool name requirements for reference.
+
+    Returns:
+        Dict mapping provider name to their requirements
+    """
+    return {
+        "openai": {
+            "pattern": r'^[a-zA-Z0-9_-]{1,64}$',
+            "description": "1-64 chars, letters, numbers, hyphens, underscores"
+        },
+        "anthropic": {
+            "pattern": r'^[a-zA-Z0-9_]{1,64}$',
+            "description": "1-64 chars, letters, numbers, underscores"
+        },
+        "vertex_ai": {
+            "pattern": r'^[a-zA-Z_][a-zA-Z0-9_\.\:\-]{0,63}$',
+            "description": "Start with letter/underscore, letters, numbers, underscore, dot, colon, dash, max 64"
+        },
+        "bedrock": {
+            "pattern": r'^[a-zA-Z][a-zA-Z0-9_]{0,63}$',
+            "description": "Start with letter, letters, numbers, underscores, max 64"
+        },
+        "universal": {
+            "pattern": UNIVERSAL_TOOL_NAME_PATTERN.pattern,
+            "description": "Start with letter/underscore, letters, numbers, underscores only, max 64 (strictest common)"
+        }
+    }
+
+
+# Quick validation functions for common use cases
+
+def is_valid_tool_name(name: str) -> bool:
+    """Quick check if a tool name is valid."""
+    is_valid, _, _ = validate_tool_name(name)
+    return is_valid
+
+
+def assert_valid_tool_name(name: str, context: str = ""):
+    """Assert tool name is valid, raise exception if not."""
+    is_valid, error_msg, _ = validate_tool_name(name, context)
+    if not is_valid:
+        raise ToolValidationError(f"{context}: {error_msg}" if context else error_msg)

control_plane_api/worker/utils/workspace_manager.py

@@ -0,0 +1,163 @@
+"""Workspace management for execution isolation.
+
+Provides utilities for creating and managing execution-scoped workspaces
+where skills can safely operate without affecting global filesystem.
+
+Pattern: .kubiya/workspaces/<execution-id>/
+"""
+
+from pathlib import Path
+import re
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+# Module-level constants
+WORKSPACE_ROOT = ".kubiya/workspaces"
+MAX_EXECUTION_ID_LENGTH = 200
+
+# Unsafe filesystem characters to sanitize
+UNSAFE_CHARS_PATTERN = re.compile(r'[/\\:*?"<>|]')
+
+
+def ensure_workspace(execution_id: str) -> Path:
+    """
+    Create or return a workspace directory path for a given execution ID.
+
+    Purpose:
+    - Provides an isolated directory for each execution
+    - Used by file_system and shell skills for bounded operations
+    - Prevents global filesystem modifications
+
+    Path Created:
+    - .kubiya/workspaces/<execution-id>/
+
+    Behavior:
+    - Creates directory if it doesn't exist
+    - Returns existing path if already created
+    - Parent directories created automatically with proper permissions
+
+    Args:
+        execution_id: Unique execution identifier (from RuntimeExecutionContext)
+
+    Returns:
+        Path object pointing to the workspace directory
+        (Caller converts to str with str(workspace_path))
+
+    Raises:
+        ValueError: If execution_id is None/empty or unsafe for filesystem
+        OSError: If directory creation fails (permission denied, etc.)
+
+    Usage:
+        workspace_path = ensure_workspace(execution_id)
+        skill_instance = FileSystemTools(base_directory=str(workspace_path))
+    """
+    # Validate execution_id
+    if not execution_id:
+        logger.error(
+            "workspace_creation_failed",
+            error="execution_id is None or empty",
+            error_type="ValueError",
+        )
+        raise ValueError("execution_id must be a non-empty string")
+
+    # Sanitize execution_id for filesystem safety
+    sanitized_id = UNSAFE_CHARS_PATTERN.sub("_", execution_id)
+
+    # Truncate if too long
+    if len(sanitized_id) > MAX_EXECUTION_ID_LENGTH:
+        original_length = len(sanitized_id)
+        sanitized_id = sanitized_id[:MAX_EXECUTION_ID_LENGTH]
+        logger.warning(
+            "workspace_execution_id_truncated",
+            original_length=original_length,
+            max_length=MAX_EXECUTION_ID_LENGTH,
+            execution_id=sanitized_id[:8] if len(sanitized_id) >= 8 else sanitized_id,
+        )
+
+    # Log warning if sanitization was applied
+    if sanitized_id != execution_id:
+        logger.warning(
+            "workspace_execution_id_sanitized",
+            original=execution_id[:50] if len(execution_id) >= 50 else execution_id,
+            sanitized=sanitized_id[:50] if len(sanitized_id) >= 50 else sanitized_id,
+        )
+
+    # Build workspace path relative to current working directory
+    workspace_path = Path.cwd() / WORKSPACE_ROOT / sanitized_id
+
+    # Create directory (idempotent with exist_ok=True)
+    try:
+        workspace_path.mkdir(parents=True, exist_ok=True)
+
+        logger.info(
+            "execution_workspace_ensured",
+            execution_id=sanitized_id[:8] if len(sanitized_id) >= 8 else sanitized_id,
+            path=str(workspace_path),
+        )
+
+        return workspace_path
+
+    except OSError as e:
+        logger.error(
+            "workspace_directory_creation_failed",
+            execution_id=sanitized_id[:8] if len(sanitized_id) >= 8 else sanitized_id,
+            path=str(workspace_path),
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+        # Let exception propagate - caller handles with try/except
+        raise
+
+
+def should_use_custom_base_directory(skill_data: dict) -> bool:
+    """
+    Check if skill has explicitly configured base_directory.
+
+    Purpose:
+    - Prevents overriding user-specified base directories
+    - Allows skills to use custom paths when explicitly configured
+
+    Configuration Structure:
+        skill_data = {
+            "name": "file_system",
+            "type": "file_system",
+            "configuration": {
+                "base_directory": "/custom/path",  # If present, return True
+                ...
+            },
+            "enabled": True,
+            "execution_id": "..."
+        }
+
+    Args:
+        skill_data: Skill configuration dict from Control Plane
+
+    Returns:
+        True if skill_data["configuration"]["base_directory"] is set to a non-empty value
+        False if base_directory is missing, None, empty string, or invalid
+
+    Usage:
+        if not should_use_custom_base_directory(skill_data):
+            config["base_directory"] = workspace_path
+    """
+    # Safe dictionary access with defaults
+    if not skill_data:
+        return False
+
+    configuration = skill_data.get("configuration", {})
+    if not configuration:
+        return False
+
+    base_directory = configuration.get("base_directory")
+
+    # Check if base_directory is set to a non-empty value
+    if base_directory is None:
+        return False
+
+    # Handle empty strings and whitespace
+    if isinstance(base_directory, str) and not base_directory.strip():
+        return False
+
+    # base_directory is explicitly set
+    return True