devsquad 3.6.0__py3-none-any.whl

scripts/collaboration/null_providers.py

@@ -0,0 +1,297 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+DevSquad Null Providers
+
+Provides no-op implementations for all Protocol interfaces, used for:
+- Degradation: auto-switch when real Provider is unavailable
+- Test mocking: quick tests without real dependencies
+- Development: skip certain modules to focus on core logic
+
+Characteristics:
+- All methods succeed silently, never raise exceptions
+- is_available() returns False (marks as degraded implementation)
+- No actual operations performed (no side effects)
+
+Version: v1.0
+Created: 2026-05-01
+"""
+
+from typing import Optional, Dict, Any, List, Callable
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class NullCacheProvider:
+    """
+    No-op cache implementation.
+
+    Behavior:
+    - get() always returns None (cache miss)
+    - set() succeeds silently, no actual storage
+    - clear() succeeds silently
+    - is_available() returns False
+    """
+
+    def __init__(self):
+        self._call_count = 0
+        logger.info("NullCacheProvider initialized (degraded mode)")
+
+    def get(self, prompt: str, backend: str, model: str) -> Optional[str]:
+        """Retrieve cached response (always returns None)."""
+        self._call_count += 1
+        logger.debug("NullCacheProvider.get() called (miss) - call #%d", self._call_count)
+        return None
+
+    def set(self, prompt: str, response: str, backend: str, model: str, ttl: Optional[int] = None) -> None:
+        """Store response in cache (no-op)."""
+        self._call_count += 1
+        logger.debug("NullCacheProvider.set() called (no-op) - call #%d", self._call_count)
+
+    def clear(self) -> None:
+        """Clear cache (no-op)."""
+        logger.debug("NullCacheProvider.clear() called (no-op)")
+
+    def is_available(self) -> bool:
+        """Check if cache is available. Returns False (degraded)."""
+        return False
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Return empty cache statistics."""
+        return {
+            "hit_count": 0,
+            "miss_count": self._call_count,
+            "hit_rate": 0.0,
+            "total_size": 0,
+            "entry_count": 0,
+            "provider_type": "null",
+            "degraded": True
+        }
+
+
+class NullRetryProvider:
+    """
+    No-op retry implementation.
+
+    Behavior:
+    - retry_with_fallback() executes function directly, no retry
+    - On failure, calls fallback if provided
+    - is_available() returns False
+    """
+
+    def __init__(self):
+        self._call_count = 0
+        self._success_count = 0
+        self._failure_count = 0
+        self._fallback_count = 0
+        logger.info("NullRetryProvider initialized (degraded mode)")
+
+    def retry_with_fallback(
+        self,
+        func: Callable[[], Any],
+        max_attempts: int = 3,
+        fallback: Optional[Callable[[], Any]] = None
+    ) -> Any:
+        """Execute function without retry. Falls back on failure."""
+        self._call_count += 1
+
+        try:
+            result = func()
+            self._success_count += 1
+            logger.debug("NullRetryProvider: function succeeded (no retry) - call #%d", self._call_count)
+            return result
+        except Exception as e:
+            self._failure_count += 1
+            logger.debug("NullRetryProvider: function failed (no retry) - call #%d: %s", self._call_count, e)
+
+            if fallback:
+                self._fallback_count += 1
+                logger.debug("NullRetryProvider: calling fallback - call #%d", self._call_count)
+                return fallback()
+            else:
+                raise
+
+    def is_available(self) -> bool:
+        """Check if retry mechanism is available. Returns False (degraded)."""
+        return False
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Return retry statistics."""
+        return {
+            "total_attempts": self._call_count,
+            "success_count": self._success_count,
+            "failure_count": self._failure_count,
+            "fallback_count": self._fallback_count,
+            "avg_attempts": 1.0,
+            "provider_type": "null",
+            "degraded": True
+        }
+
+
+class NullMonitorProvider:
+    """
+    No-op monitoring implementation.
+
+    Behavior:
+    - record_*() succeeds silently, no actual recording
+    - generate_report() writes empty report
+    - is_available() returns False
+    """
+
+    def __init__(self):
+        self._llm_call_count = 0
+        self._agent_execution_count = 0
+        logger.info("NullMonitorProvider initialized (degraded mode)")
+
+    def record_llm_call(
+        self,
+        backend: str,
+        model: str,
+        duration: float,
+        token_count: int,
+        success: bool,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Record LLM call (no-op)."""
+        self._llm_call_count += 1
+        logger.debug("NullMonitorProvider.record_llm_call() called (no-op) - call #%d", self._llm_call_count)
+
+    def record_agent_execution(
+        self,
+        agent_role: str,
+        task: str,
+        duration: float,
+        success: bool,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Record agent execution (no-op)."""
+        self._agent_execution_count += 1
+        logger.debug("NullMonitorProvider.record_agent_execution() called (no-op) - call #%d", self._agent_execution_count)
+
+    def generate_report(self, output_path: str) -> None:
+        """Generate empty performance report."""
+        logger.debug("NullMonitorProvider.generate_report() called (empty report) - path: %s", output_path)
+        try:
+            with open(output_path, "w") as f:
+                f.write("# Performance Report (Degraded Mode)\n\n")
+                f.write("Monitoring is currently unavailable (NullMonitorProvider).\n")
+                f.write("No performance data was collected.\n")
+        except Exception as e:
+            logger.warning("NullMonitorProvider: failed to write empty report: %s", e)
+
+    def is_available(self) -> bool:
+        """Check if monitoring is available. Returns False (degraded)."""
+        return False
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Return empty monitoring statistics."""
+        return {
+            "total_llm_calls": 0,
+            "total_agent_executions": 0,
+            "avg_llm_duration": 0.0,
+            "avg_agent_duration": 0.0,
+            "total_tokens": 0,
+            "provider_type": "null",
+            "degraded": True
+        }
+
+
+class NullMemoryProvider:
+    """
+    No-op memory implementation.
+
+    Behavior:
+    - get_rules() returns empty list
+    - add_rule() / update_rule() / delete_rule() succeed silently
+    - is_available() returns False
+    """
+
+    def __init__(self):
+        self._call_count = 0
+        logger.info("NullMemoryProvider initialized (degraded mode)")
+
+    def get_rules(self, user_id: str, context: Optional[Dict[str, Any]] = None) -> List[str]:
+        """Retrieve user rules (always returns empty list)."""
+        self._call_count += 1
+        logger.debug("NullMemoryProvider.get_rules() called (empty) - user: %s, call #%d", user_id, self._call_count)
+        return []
+
+    def add_rule(self, user_id: str, rule: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        """Add user rule (no-op)."""
+        self._call_count += 1
+        logger.debug("NullMemoryProvider.add_rule() called (no-op) - user: %s, call #%d", user_id, self._call_count)
+
+    def update_rule(self, user_id: str, rule_id: str, rule: str) -> None:
+        """Update user rule (no-op)."""
+        self._call_count += 1
+        logger.debug("NullMemoryProvider.update_rule() called (no-op) - user: %s, rule: %s, call #%d", user_id, rule_id, self._call_count)
+
+    def delete_rule(self, user_id: str, rule_id: str) -> None:
+        """Delete user rule (no-op)."""
+        self._call_count += 1
+        logger.debug("NullMemoryProvider.delete_rule() called (no-op) - user: %s, rule: %s, call #%d", user_id, rule_id, self._call_count)
+
+    def is_available(self) -> bool:
+        """Check if memory system is available. Returns False (degraded)."""
+        return False
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Return empty memory statistics."""
+        return {
+            "total_users": 0,
+            "total_rules": 0,
+            "avg_rules_per_user": 0.0,
+            "provider_type": "null",
+            "degraded": True
+        }
+
+    def match_rules(self, task_description: str, user_id: str,
+                     role: Optional[str] = None, max_rules: int = 5) -> List[Dict[str, Any]]:
+        """Match rules based on task description (always returns empty list)."""
+        self._call_count += 1
+        logger.debug("NullMemoryProvider.match_rules() called (empty) - user: %s, call #%d", user_id, self._call_count)
+        return []
+
+    def format_rules_as_prompt(self, rules: List[Dict[str, Any]]) -> str:
+        """Format rules as prompt text (always returns empty string)."""
+        self._call_count += 1
+        logger.debug("NullMemoryProvider.format_rules_as_prompt() called (empty) - call #%d", self._call_count)
+        return ""
+
+
+# ============================================================================
+# Factory functions
+# ============================================================================
+
+def get_null_cache() -> NullCacheProvider:
+    """Get a null cache instance."""
+    return NullCacheProvider()
+
+
+def get_null_retry() -> NullRetryProvider:
+    """Get a null retry instance."""
+    return NullRetryProvider()
+
+
+def get_null_monitor() -> NullMonitorProvider:
+    """Get a null monitor instance."""
+    return NullMonitorProvider()
+
+
+def get_null_memory() -> NullMemoryProvider:
+    """Get a null memory instance."""
+    return NullMemoryProvider()
+
+
+__version__ = "1.0.0"
+__all__ = [
+    "NullCacheProvider",
+    "NullRetryProvider",
+    "NullMonitorProvider",
+    "NullMemoryProvider",
+    "get_null_cache",
+    "get_null_retry",
+    "get_null_monitor",
+    "get_null_memory",
+]

scripts/collaboration/operation_classifier.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+OperationCategory Extension for PermissionGuard (P1-2)
+
+Adds three-tier operation classification to existing 4-level permission model:
+  - ALWAYS_SAFE: Read-only, local queries (auto-approved at most levels)
+  - NEEDS_REVIEW: Write ops, external API calls (requires confirmation or AI check)
+  - FORBIDDEN: Dangerous ops (delete, secrets, eval) (denied unless BYPASS)
+
+Spec reference: SPEC_V35_Agent_Skills_Quality_Framework.md Section 7.2
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional, Tuple
+
+
+class OperationCategory(Enum):
+    """
+    Three-tier operation classification for fine-grained permission control.
+
+    Hierarchy:
+      ALWAYS_SAFE → Auto-approved at DEFAULT/AUTO levels
+      NEEDS_REVIEW → Requires explicit approval or AI risk assessment
+      FORBIDDEN     → Blocked unless BYPASS level + explicit override
+    """
+    ALWAYS_SAFE = "always_safe"
+    NEEDS_REVIEW = "needs_review"
+    FORBIDDEN = "forbidden"
+
+
+# Default classification mapping for common operations
+OPERATION_CLASSIFICATION: Dict[str, OperationCategory] = {
+    # === Always Safe Operations ===
+    "read_config": OperationCategory.ALWAYS_SAFE,
+    "read_file": OperationCategory.ALWAYS_SAFE,
+    "read_scratchpad": OperationCategory.ALWAYS_SAFE,
+    "list_directory": OperationCategory.ALWAYS_SAFE,
+    "query_status": OperationCategory.ALWAYS_SAFE,
+    "get_role_info": OperationCategory.ALWAYS_SAFE,
+    "validate_input": OperationCategory.ALWAYS_SAFE,
+
+    # === Needs Review Operations ===
+    "write_scratchpad": OperationCategory.NEEDS_REVIEW,
+    "write_file": OperationCategory.NEEDS_REVIEW,
+    "create_file": OperationCategory.NEEDS_REVIEW,
+    "modify_file": OperationCategory.NEEDS_REVIEW,
+    "call_llm": OperationCategory.NEEDS_REVIEW,
+    "network_request": OperationCategory.NEEDS_REVIEW,
+    "git_operation": OperationCategory.NEEDS_REVIEW,
+    "modify_config": OperationCategory.NEEDS_REVIEW,
+    "install_template": OperationCategory.NEEDS_REVIEW,
+    "publish_template": OperationCategory.NEEDS_REVIEW,
+
+    # === Forbidden Operations ===
+    "delete_file": OperationCategory.FORBIDDEN,
+    "execute_shell": OperationCategory.FORBIDDEN,
+    "access_secrets": OperationCategory.FORBIDDEN,
+    "eval_code": OperationCategory.FORBIDDEN,
+    "import_module": OperationCategory.FORBIDDEN,
+    "spawn_process": OperationCategory.FORBIDDEN,
+    "modify_system_path": OperationCategory.FORBIDDEN,
+    "environment_write": OperationCategory.FORBIDDEN,
+}
+
+
+@dataclass
+class ClassifiedOperation:
+    """An operation with its category classification."""
+    operation_id: str
+    category: OperationCategory
+    description: str
+    risk_factors: List[str]
+    requires_confirmation: bool
+    override_allowed: bool
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "operation_id": self.operation_id,
+            "category": self.category.value,
+            "description": self.description,
+            "risk_factors": self.risk_factors,
+            "requires_confirmation": self.requires_confirmation,
+            "override_allowed": self.override_allowed,
+        }
+
+
+class OperationClassifier:
+    """
+    Classifies operations into three-tier categories.
+
+    Usage:
+        classifier = OperationClassifier()
+        classified = classifier.classify("delete_file", "/tmp/important.txt")
+        if classified.category == OperationCategory.FORBIDDEN:
+            # Block or escalate
+            pass
+    """
+
+    def __init__(
+        self,
+        custom_classifications: Optional[Dict[str, OperationCategory]] = None,
+        strict_mode: bool = False,
+    ):
+        """
+        Initialize classifier.
+
+        Args:
+            custom_classifications: Override default classifications
+            strict_mode: If True, unknown operations are classified as FORBIDDEN
+                           If False (default), unknown operations are NEEDS_REVIEW
+        """
+        self._classifications = dict(OPERATION_CLASSIFICATION)
+        if custom_classifications:
+            self._classifications.update(custom_classifications)
+        self._strict_mode = strict_mode
+
+    def classify(
+        self,
+        operation_id: str,
+        target: Optional[str] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> ClassifiedOperation:
+        """
+        Classify an operation into a category.
+
+        Args:
+            operation_id: The operation identifier
+            target: Optional target path/URL for context
+            context: Additional context (source role, etc.)
+
+        Returns:
+            ClassifiedOperation with full details
+        """
+        base_category = self._classifications.get(operation_id)
+
+        if base_category is None:
+            if self._strict_mode:
+                base_category = OperationCategory.FORBIDDEN
+            else:
+                base_category = OperationCategory.NEEDS_REVIEW
+
+        description = self._get_description(operation_id)
+        risk_factors = self._assess_risk_factors(operation_id, target, context)
+
+        return ClassifiedOperation(
+            operation_id=operation_id,
+            category=base_category,
+            description=description,
+            risk_factors=risk_factors,
+            requires_confirmation=(
+                base_category == OperationCategory.NEEDS_REVIEW or
+                base_category == OperationCategory.FORBIDDEN
+            ),
+            override_allowed=base_category != OperationCategory.FORBIDDEN,
+        )
+
+    def batch_classify(
+        self,
+        operations: List[Dict[str, Any]],
+    ) -> List[ClassifiedOperation]:
+        """
+        Classify multiple operations at once.
+
+        Args:
+            operations: List of dicts with 'operation_id' and optional 'target', 'context'
+
+        Returns:
+            List of ClassifiedOperation results
+        """
+        return [
+            self.classify(
+                op.get('operation_id', ''),
+                op.get('target'),
+                op.get('context'),
+            )
+            for op in operations
+        ]
+
+    def is_allowed(
+        self,
+        operation_id: str,
+        permission_level: str = "DEFAULT",
+        target: Optional[str] = None,
+    ) -> tuple:
+        """
+        Quick check if operation is allowed at given permission level.
+
+        Returns:
+            (allowed: bool, reason: str)
+        """
+        classified = self.classify(operation_id, target)
+
+        if classified.category == OperationCategory.ALWAYS_SAFE:
+            return True, "Operation is always safe"
+
+        if classified.category == OperationCategory.FORBIDDEN:
+            if permission_level.upper() == "BYPASS":
+                return True, "Allowed via BYPASS override"
+            return False, f"Operation '{operation_id}' is forbidden"
+
+        if classified.category == OperationCategory.NEEDS_REVIEW:
+            if permission_level.upper() in ("AUTO", "BYPASS"):
+                return True, f"Auto-approved at {permission_level} level"
+            if permission_level.upper() == "PLAN":
+                return False, "Write operations denied in PLAN mode"
+            return True, "Requires user confirmation"
+
+        return False, "Unknown category"
+
+    def get_forbidden_operations(self) -> List[str]:
+        """Return list of all operations classified as FORBIDDEN."""
+        return [
+            op_id
+            for op_id, cat in self._classifications.items()
+            if cat == OperationCategory.FORBIDDEN
+        ]
+
+    def get_review_required_operations(self) -> List[str]:
+        """Return list of all operations classified as NEEDS_REVIEW."""
+        return [
+            op_id
+            for op_id, cat in self._classifications.items()
+            if cat == OperationCategory.NEEDS_REVIEW
+        ]
+
+    def add_custom_classification(
+        self,
+        operation_id: str,
+        category: OperationCategory,
+    ):
+        """Add or update custom operation classification."""
+        self._classifications[operation_id] = category
+
+    def _get_description(self, operation_id: str) -> str:
+        descriptions = {
+            "read_config": "Read configuration values",
+            "write_file": "Write or modify file contents",
+            "delete_file": "Delete file from filesystem",
+            "execute_shell": "Execute shell command",
+            "call_llm": "Call LLM API for inference",
+            "access_secrets": "Access secret keys or credentials",
+            "eval_code": "Evaluate arbitrary code string",
+            "read_scratchpad": "Read shared scratchpad data",
+            "write_scratchpad": "Write to shared scratchpad",
+        }
+        return descriptions.get(operation_id, f"Operation: {operation_id}")
+
+    def _assess_risk_factors(
+        self,
+        operation_id: str,
+        target: Optional[str],
+        context: Optional[Dict[str, Any]],
+    ) -> List[str]:
+        factors = []
+        category = self._classifications.get(operation_id, OperationCategory.NEEDS_REVIEW)
+
+        if category == OperationCategory.FORBIDDEN:
+            factors.append("High-risk operation category")
+
+        if target:
+            dangerous_patterns = ["/etc/", "/var/", ".env", "secret", "credential"]
+            for pattern in dangerous_patterns:
+                if pattern.lower() in target.lower():
+                    factors.append(f"Target contains sensitive pattern: {pattern}")
+
+        if context:
+            source_role = context.get("source_role_id", "")
+            if source_role == "solo-coder" and category == OperationCategory.FORBIDDEN:
+                factors.append("Coder attempting forbidden operation")
+
+        return factors
+
+
+def create_default_classifier() -> OperationClassifier:
+    """Create classifier with default classifications."""
+    return OperationClassifier()
+
+
+def create_strict_classifier(
+    custom_classifications: Optional[Dict[str, OperationCategory]] = None,
+) -> OperationClassifier:
+    """Create classifier in strict mode (unknown ops = FORBIDDEN)."""
+    return OperationClassifier(
+        custom_classifications=custom_classifications,
+        strict_mode=True,
+    )