agent_os_kernel 3.1.0__py3-none-any.whl

agent_control_plane/example_executors.py

@@ -0,0 +1,195 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Example Executors for Agent Control Plane
+
+These are example/demonstration executors showing how to implement
+action handlers. In production, these would be replaced with actual
+implementations that interface with real systems.
+"""
+
+from typing import Dict, Any
+from .execution_engine import ExecutionContext
+
+
+def file_read_executor(parameters: Dict[str, Any], context: ExecutionContext) -> Any:
+    """
+    Example executor for file read operations
+    
+    In production, this would:
+    - Actually read files from the filesystem
+    - Apply additional security checks
+    - Handle errors appropriately
+    """
+    path = parameters.get('path')
+    if not path:
+        raise ValueError("Missing 'path' parameter")
+    
+    # This is a simulation - real implementation would read actual files
+    return {
+        "action": "file_read",
+        "path": path,
+        "content": f"[Simulated content of {path}]",
+        "sandbox_level": context.sandbox_level.value,
+        "note": "This is a simulated response. Replace with actual file reading in production."
+    }
+
+
+def file_write_executor(parameters: Dict[str, Any], context: ExecutionContext) -> Any:
+    """
+    Example executor for file write operations
+    
+    In production, this would:
+    - Actually write files to the filesystem
+    - Verify write permissions
+    - Handle atomic writes
+    """
+    path = parameters.get('path')
+    content = parameters.get('content')
+    
+    if not path:
+        raise ValueError("Missing 'path' parameter")
+    if not content:
+        raise ValueError("Missing 'content' parameter")
+    
+    # This is a simulation - real implementation would write actual files
+    return {
+        "action": "file_write",
+        "path": path,
+        "bytes_written": len(str(content)),
+        "sandbox_level": context.sandbox_level.value,
+        "note": "This is a simulated response. Replace with actual file writing in production."
+    }
+
+
+def code_execution_executor(parameters: Dict[str, Any], context: ExecutionContext) -> Any:
+    """
+    Example executor for code execution
+    
+    In production, this would:
+    - Execute code in an isolated container
+    - Capture stdout/stderr
+    - Enforce resource limits
+    - Handle timeouts
+    """
+    code = parameters.get('code')
+    language = parameters.get('language', 'python')
+    
+    if not code:
+        raise ValueError("Missing 'code' parameter")
+    
+    # This is a simulation - real implementation would execute in container
+    return {
+        "action": "code_execution",
+        "language": language,
+        "output": "[Simulated execution output]",
+        "exit_code": 0,
+        "sandbox_level": context.sandbox_level.value,
+        "note": "This is a simulated response. Replace with actual code execution in production."
+    }
+
+
+def api_call_executor(parameters: Dict[str, Any], context: ExecutionContext) -> Any:
+    """
+    Example executor for API calls
+    
+    In production, this would:
+    - Make actual HTTP requests
+    - Apply rate limiting
+    - Handle retries
+    - Validate SSL certificates
+    """
+    url = parameters.get('url')
+    method = parameters.get('method', 'GET')
+    
+    if not url:
+        raise ValueError("Missing 'url' parameter")
+    
+    if not context.allowed_network:
+        raise PermissionError("Network access not allowed in this context")
+    
+    # This is a simulation - real implementation would make actual HTTP requests
+    return {
+        "action": "api_call",
+        "url": url,
+        "method": method,
+        "status_code": 200,
+        "response": "[Simulated API response]",
+        "note": "This is a simulated response. Replace with actual HTTP requests in production."
+    }
+
+
+def database_query_executor(parameters: Dict[str, Any], context: ExecutionContext) -> Any:
+    """
+    Example executor for database queries
+    
+    In production, this would:
+    - Execute actual SQL queries
+    - Use connection pooling
+    - Apply query timeouts
+    - Sanitize inputs
+    """
+    query = parameters.get('query')
+    database = parameters.get('database', 'default')
+    
+    if not query:
+        raise ValueError("Missing 'query' parameter")
+    
+    # This is a simulation - real implementation would execute actual queries
+    return {
+        "action": "database_query",
+        "database": database,
+        "rows": "[Simulated query results]",
+        "row_count": 0,
+        "note": "This is a simulated response. Replace with actual database queries in production."
+    }
+
+
+def database_write_executor(parameters: Dict[str, Any], context: ExecutionContext) -> Any:
+    """
+    Example executor for database writes
+    
+    In production, this would:
+    - Execute actual write operations
+    - Use transactions
+    - Handle rollbacks
+    - Validate data integrity
+    """
+    query = parameters.get('query')
+    database = parameters.get('database', 'default')
+    
+    if not query:
+        raise ValueError("Missing 'query' parameter")
+    
+    # This is a simulation - real implementation would execute actual writes
+    return {
+        "action": "database_write",
+        "database": database,
+        "rows_affected": 0,
+        "note": "This is a simulated response. Replace with actual database writes in production."
+    }
+
+
+def workflow_trigger_executor(parameters: Dict[str, Any], context: ExecutionContext) -> Any:
+    """
+    Example executor for workflow triggers
+    
+    In production, this would:
+    - Trigger actual workflows
+    - Track workflow execution
+    - Handle callbacks
+    """
+    workflow_id = parameters.get('workflow_id')
+    workflow_params = parameters.get('params', {})
+    
+    if not workflow_id:
+        raise ValueError("Missing 'workflow_id' parameter")
+    
+    # This is a simulation - real implementation would trigger actual workflows
+    return {
+        "action": "workflow_trigger",
+        "workflow_id": workflow_id,
+        "execution_id": "[Simulated execution ID]",
+        "status": "started",
+        "note": "This is a simulated response. Replace with actual workflow triggers in production."
+    }

agent_control_plane/execution_engine.py

@@ -0,0 +1,231 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Execution Engine - Safe execution of agent actions
+
+Provides sandboxed execution, resource monitoring, and error handling
+for agent actions.
+
+Research Foundations:
+    - Sandbox isolation levels informed by container security best practices
+    - Timeout and resource limits from "Fault-Tolerant Multi-Agent Systems" 
+      (IEEE Trans. SMC, 2024) - failure recovery patterns
+    - Transaction rollback patterns from distributed systems research
+    - Circuit breaker and retry policies for resilience
+
+See docs/RESEARCH_FOUNDATION.md for complete references.
+"""
+
+from typing import Any, Dict, Optional, Callable, List
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+import time
+from .agent_kernel import ExecutionRequest, ActionType
+
+
+class SandboxLevel(Enum):
+    """Sandbox isolation levels"""
+    NONE = 0
+    BASIC = 1
+    STRICT = 2
+    ISOLATED = 3
+
+
+@dataclass
+class ExecutionContext:
+    """Context for executing an agent action"""
+    request_id: str
+    sandbox_level: SandboxLevel
+    timeout_seconds: float = 30.0
+    max_memory_mb: int = 512
+    allowed_network: bool = False
+    environment_vars: Dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class ExecutionMetrics:
+    """Metrics collected during execution"""
+    start_time: datetime
+    end_time: Optional[datetime] = None
+    cpu_time_ms: float = 0.0
+    memory_used_mb: float = 0.0
+    network_calls: int = 0
+    files_accessed: List[str] = field(default_factory=list)
+
+
+class ExecutionEngine:
+    """
+    Execution Engine - Safely executes agent actions
+    
+    Provides:
+    - Sandboxed execution
+    - Resource monitoring
+    - Timeout enforcement
+    - Error handling and recovery
+    - Transaction management
+    """
+    
+    def __init__(self):
+        self.executors: Dict[ActionType, Callable] = {}
+        self.active_executions: Dict[str, ExecutionContext] = {}
+        self.execution_history: List[Dict[str, Any]] = []
+        
+    def register_executor(self, action_type: ActionType, executor: Callable):
+        """Register an executor for a specific action type"""
+        self.executors[action_type] = executor
+    
+    def execute(
+        self,
+        request: ExecutionRequest,
+        context: Optional[ExecutionContext] = None
+    ) -> Dict[str, Any]:
+        """Execute a request in a controlled environment"""
+        if context is None:
+            context = self._create_default_context(request)
+        
+        self.active_executions[request.request_id] = context
+        metrics = ExecutionMetrics(start_time=datetime.now())
+        
+        try:
+            # Get the appropriate executor
+            executor = self.executors.get(request.action_type)
+            if not executor:
+                executor = self._default_executor
+            
+            # Execute with timeout
+            result = self._execute_with_timeout(
+                executor,
+                request,
+                context,
+                metrics
+            )
+            
+            metrics.end_time = datetime.now()
+            
+            # Record execution
+            self._record_execution(request, context, metrics, result, None)
+            
+            return {
+                "success": True,
+                "result": result,
+                "metrics": {
+                    "execution_time_ms": (metrics.end_time - metrics.start_time).total_seconds() * 1000,
+                    "cpu_time_ms": metrics.cpu_time_ms,
+                    "memory_used_mb": metrics.memory_used_mb,
+                }
+            }
+            
+        except TimeoutError as e:
+            metrics.end_time = datetime.now()
+            self._record_execution(request, context, metrics, None, f"Timeout: {str(e)}")
+            return {
+                "success": False,
+                "error": f"Execution timeout after {context.timeout_seconds}s",
+                "error_type": "timeout"
+            }
+            
+        except Exception as e:
+            metrics.end_time = datetime.now()
+            self._record_execution(request, context, metrics, None, str(e))
+            return {
+                "success": False,
+                "error": str(e),
+                "error_type": type(e).__name__
+            }
+            
+        finally:
+            if request.request_id in self.active_executions:
+                del self.active_executions[request.request_id]
+    
+    def _execute_with_timeout(
+        self,
+        executor: Callable,
+        request: ExecutionRequest,
+        context: ExecutionContext,
+        metrics: ExecutionMetrics
+    ) -> Any:
+        """Execute with timeout enforcement"""
+        start_time = time.time()
+        
+        # In a real implementation, this would use proper process isolation
+        # and actual timeout mechanisms (e.g., threading with timeouts, subprocesses)
+        result = executor(request.parameters, context)
+        
+        elapsed = time.time() - start_time
+        if elapsed > context.timeout_seconds:
+            raise TimeoutError(f"Execution exceeded {context.timeout_seconds}s")
+        
+        metrics.cpu_time_ms = elapsed * 1000
+        return result
+    
+    def _default_executor(self, parameters: Dict[str, Any], context: ExecutionContext) -> Any:
+        """Default executor for unregistered action types"""
+        return {
+            "status": "executed",
+            "parameters": parameters,
+            "note": "Using default executor (no specific executor registered)"
+        }
+    
+    def _create_default_context(self, request: ExecutionRequest) -> ExecutionContext:
+        """Create default execution context based on action type"""
+        # More sensitive actions get stricter sandboxing
+        sandbox_map = {
+            ActionType.FILE_READ: SandboxLevel.BASIC,
+            ActionType.FILE_WRITE: SandboxLevel.STRICT,
+            ActionType.CODE_EXECUTION: SandboxLevel.ISOLATED,
+            ActionType.DATABASE_QUERY: SandboxLevel.BASIC,
+            ActionType.DATABASE_WRITE: SandboxLevel.STRICT,
+            ActionType.API_CALL: SandboxLevel.BASIC,
+            ActionType.WORKFLOW_TRIGGER: SandboxLevel.BASIC,
+        }
+        
+        return ExecutionContext(
+            request_id=request.request_id,
+            sandbox_level=sandbox_map.get(request.action_type, SandboxLevel.STRICT),
+            timeout_seconds=30.0,
+            max_memory_mb=512,
+            allowed_network=request.action_type in [ActionType.API_CALL],
+        )
+    
+    def _record_execution(
+        self,
+        request: ExecutionRequest,
+        context: ExecutionContext,
+        metrics: ExecutionMetrics,
+        result: Optional[Any],
+        error: Optional[str]
+    ):
+        """Record execution for history and analytics"""
+        record = {
+            "request_id": request.request_id,
+            "agent_id": request.agent_context.agent_id,
+            "action_type": request.action_type.value,
+            "timestamp": request.timestamp.isoformat(),
+            "execution_time_ms": (
+                (metrics.end_time - metrics.start_time).total_seconds() * 1000
+                if metrics.end_time else 0
+            ),
+            "success": error is None,
+            "error": error,
+            "sandbox_level": context.sandbox_level.value,
+        }
+        self.execution_history.append(record)
+    
+    def get_execution_history(
+        self,
+        agent_id: Optional[str] = None,
+        limit: int = 100
+    ) -> List[Dict[str, Any]]:
+        """Get execution history, optionally filtered by agent"""
+        history = self.execution_history
+        
+        if agent_id:
+            history = [r for r in history if r["agent_id"] == agent_id]
+        
+        return history[-limit:]
+    
+    def get_active_executions(self) -> Dict[str, ExecutionContext]:
+        """Get currently active executions"""
+        return self.active_executions.copy()
+