skilllite 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

skilllite/quick.py

@@ -92,7 +92,8 @@ class SkillRunner:
         allow_network: Optional[bool] = None,
         enable_sandbox: Optional[bool] = None,
         execution_timeout: Optional[int] = None,
-        max_memory_mb: Optional[int] = None
+        max_memory_mb: Optional[int] = None,
+        confirmation_callback: Optional[Callable[[str, str], bool]] = None
     ):
         """
         Initialize SkillRunner.
@@ -122,6 +123,9 @@ class SkillRunner:
             enable_sandbox: Whether to enable sandbox protection (defaults from .env or True)
             execution_timeout: Skill execution timeout in seconds (defaults from .env or 120)
             max_memory_mb: Maximum memory limit in MB (defaults from .env or 512)
+            confirmation_callback: Callback for security confirmation when sandbox_level=3.
+                Signature: (security_report: str, scan_id: str) -> bool
+                If None and sandbox_level=3, will use interactive terminal confirmation.
         """
         # Load .env
         load_env(env_file)
@@ -161,7 +165,11 @@ class SkillRunner:
         
         self.custom_tool_executor = custom_tool_executor
         self.use_enhanced_loop = use_enhanced_loop
-        
+
+        # Security confirmation callback
+        # If None and sandbox_level=3, will use interactive terminal confirmation
+        self.confirmation_callback = confirmation_callback
+
         # Lazy initialization
         self._client = None
         self._manager = None
@@ -282,7 +290,8 @@ Example of CORRECT approach:
                 model=self.model,
                 max_iterations=self.max_iterations,
                 custom_tools=self.custom_tools if self.custom_tools else None,
-                custom_tool_executor=tool_executor
+                custom_tool_executor=tool_executor,
+                confirmation_callback=self.confirmation_callback
             )
         else:
             # Use basic AgenticLoop (backward compatible)
@@ -290,7 +299,8 @@ Example of CORRECT approach:
                 client=self.client,
                 model=self.model,
                 system_prompt=self.system_context,
-                max_iterations=self.max_iterations
+                max_iterations=self.max_iterations,
+                confirmation_callback=self.confirmation_callback
             )
         
         response = loop.run(user_message)

skilllite/sandbox/context.py

@@ -0,0 +1,155 @@
+"""
+Execution Context - Encapsulates all configuration for a single execution.
+
+This module provides the ExecutionContext class which is the single source of truth
+for execution configuration. It reads from environment variables at runtime,
+ensuring that any changes to environment variables are immediately reflected.
+
+Design Principles:
+1. Read configuration at runtime, not at initialization
+2. Never cache configuration values
+3. Support temporary overrides via with_override()
+4. Immutable - create new instances for modifications
+"""
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# Default configuration values
+DEFAULT_SANDBOX_LEVEL = "3"
+DEFAULT_TIMEOUT = 120
+DEFAULT_MAX_MEMORY_MB = 512
+DEFAULT_ALLOW_NETWORK = False
+DEFAULT_AUTO_APPROVE = False
+
+
+def _parse_bool_env(key: str, default: bool) -> bool:
+    """Parse a boolean value from environment variable."""
+    value = os.environ.get(key)
+    if value is None:
+        return default
+    value_lower = value.lower().strip()
+    if value_lower in ("true", "1", "yes", "on"):
+        return True
+    elif value_lower in ("false", "0", "no", "off", ""):
+        return False
+    return default
+
+
+@dataclass(frozen=True)
+class ExecutionContext:
+    """
+    Execution context - all configuration for a single execution.
+    
+    This class is immutable (frozen=True). To modify, use with_override()
+    which returns a new instance.
+    
+    Attributes:
+        sandbox_level: Sandbox security level ("1", "2", or "3")
+        allow_network: Whether to allow network access
+        timeout: Execution timeout in seconds
+        max_memory_mb: Maximum memory limit in MB
+        auto_approve: Whether to auto-approve security prompts
+        confirmed: Whether user has confirmed execution (for security flow)
+        scan_id: Scan ID from security scan (for verification)
+        requires_elevated: Whether skill requires elevated permissions
+    """
+    sandbox_level: str = DEFAULT_SANDBOX_LEVEL
+    allow_network: bool = DEFAULT_ALLOW_NETWORK
+    timeout: int = DEFAULT_TIMEOUT
+    max_memory_mb: int = DEFAULT_MAX_MEMORY_MB
+    auto_approve: bool = DEFAULT_AUTO_APPROVE
+    confirmed: bool = False
+    scan_id: Optional[str] = None
+    requires_elevated: bool = False
+    
+    @classmethod
+    def from_current_env(cls) -> "ExecutionContext":
+        """
+        Create context from current environment variables.
+        
+        This method reads from environment variables at call time,
+        ensuring the latest values are used.
+        
+        Environment Variables:
+            SKILLBOX_SANDBOX_LEVEL: Sandbox level (1/2/3, default: 3)
+            SKILLBOX_ALLOW_NETWORK: Allow network access (true/false)
+            SKILLBOX_TIMEOUT_SECS: Execution timeout in seconds
+            SKILLBOX_MAX_MEMORY_MB: Maximum memory in MB
+            SKILLBOX_AUTO_APPROVE: Auto-approve security prompts
+        """
+        return cls(
+            sandbox_level=os.environ.get("SKILLBOX_SANDBOX_LEVEL", DEFAULT_SANDBOX_LEVEL),
+            allow_network=_parse_bool_env("SKILLBOX_ALLOW_NETWORK", DEFAULT_ALLOW_NETWORK),
+            timeout=int(os.environ.get("SKILLBOX_TIMEOUT_SECS", str(DEFAULT_TIMEOUT))),
+            max_memory_mb=int(os.environ.get("SKILLBOX_MAX_MEMORY_MB", str(DEFAULT_MAX_MEMORY_MB))),
+            auto_approve=_parse_bool_env("SKILLBOX_AUTO_APPROVE", DEFAULT_AUTO_APPROVE),
+        )
+    
+    def with_override(
+        self,
+        sandbox_level: Optional[str] = None,
+        allow_network: Optional[bool] = None,
+        timeout: Optional[int] = None,
+        max_memory_mb: Optional[int] = None,
+        auto_approve: Optional[bool] = None,
+        confirmed: bool = False,
+        scan_id: Optional[str] = None,
+        requires_elevated: Optional[bool] = None,
+    ) -> "ExecutionContext":
+        """
+        Create a new context with specified overrides.
+        
+        Args:
+            sandbox_level: Override sandbox level
+            allow_network: Override network setting
+            timeout: Override timeout
+            max_memory_mb: Override memory limit
+            auto_approve: Override auto-approve setting
+            confirmed: Set confirmed flag
+            scan_id: Set scan ID
+            requires_elevated: Set requires elevated flag
+            
+        Returns:
+            New ExecutionContext with overrides applied
+        """
+        return ExecutionContext(
+            sandbox_level=sandbox_level if sandbox_level is not None else self.sandbox_level,
+            allow_network=allow_network if allow_network is not None else self.allow_network,
+            timeout=timeout if timeout is not None else self.timeout,
+            max_memory_mb=max_memory_mb if max_memory_mb is not None else self.max_memory_mb,
+            auto_approve=auto_approve if auto_approve is not None else self.auto_approve,
+            confirmed=confirmed if confirmed else self.confirmed,
+            scan_id=scan_id if scan_id is not None else self.scan_id,
+            requires_elevated=requires_elevated if requires_elevated is not None else self.requires_elevated,
+        )
+    
+    def with_user_confirmation(self, scan_id: str) -> "ExecutionContext":
+        """
+        Create a new context after user confirmation.
+        
+        This downgrades sandbox level to 1 (no sandbox) since user has approved.
+        """
+        return self.with_override(
+            sandbox_level="1",
+            confirmed=True,
+            scan_id=scan_id,
+        )
+    
+    def with_elevated_permissions(self) -> "ExecutionContext":
+        """
+        Create a new context with elevated permissions.
+        
+        This downgrades sandbox level to 1 for skills that require
+        elevated permissions (e.g., skill-creator).
+        """
+        return self.with_override(
+            sandbox_level="1",
+            requires_elevated=True,
+        )
+
+
+__all__ = ["ExecutionContext", "DEFAULT_SANDBOX_LEVEL", "DEFAULT_TIMEOUT", "DEFAULT_MAX_MEMORY_MB"]
+

skilllite/sandbox/execution_service.py

@@ -0,0 +1,254 @@
+"""
+Unified Execution Service - High-level execution service for all entry points.
+
+This module provides the UnifiedExecutionService class which is the single entry point
+for all skill execution. It integrates security scanning, user confirmation, and
+execution into a unified flow.
+
+All entry points (AgenticLoop, LangChain, LlamaIndex, MCP) should use this service.
+
+Key Features:
+1. Unified security scanning
+2. Unified confirmation flow
+3. Unified execution
+4. Context management
+5. Temporary context overrides
+"""
+
+import os
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional, TYPE_CHECKING
+
+from .base import ExecutionResult
+from .context import ExecutionContext
+from .unified_executor import UnifiedExecutor
+
+if TYPE_CHECKING:
+    from ..core.skill_info import SkillInfo
+
+
+# Type alias for confirmation callback
+ConfirmationCallback = Callable[[str, str], bool]
+
+
+class UnifiedExecutionService:
+    """
+    Unified execution service - single entry point for all skill execution.
+    
+    This service integrates:
+    1. Security scanning (via UnifiedSecurityScanner)
+    2. User confirmation flow
+    3. Skill execution (via UnifiedExecutor)
+    
+    Usage:
+        service = UnifiedExecutionService.get_instance()
+        result = service.execute_skill(skill_info, input_data, confirmation_callback)
+    """
+    
+    _instance: Optional["UnifiedExecutionService"] = None
+    
+    @classmethod
+    def get_instance(cls) -> "UnifiedExecutionService":
+        """Get singleton instance of the service."""
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+    
+    @classmethod
+    def reset_instance(cls) -> None:
+        """Reset singleton instance (for testing)."""
+        cls._instance = None
+    
+    def __init__(self):
+        """Initialize the service."""
+        self._executor = UnifiedExecutor()
+        self._scanner = None  # Lazy initialization
+    
+    def _get_scanner(self):
+        """Get security scanner (lazy initialization)."""
+        if self._scanner is None:
+            from ..core.security import SecurityScanner
+            self._scanner = SecurityScanner()
+        return self._scanner
+    
+    def execute_skill(
+        self,
+        skill_info: "SkillInfo",
+        input_data: Dict[str, Any],
+        entry_point: Optional[str] = None,
+        confirmation_callback: Optional[ConfirmationCallback] = None,
+        allow_network: Optional[bool] = None,
+        timeout: Optional[int] = None,
+    ) -> ExecutionResult:
+        """
+        Execute a skill with unified security and confirmation flow.
+        
+        Flow:
+        1. Read current execution context from environment
+        2. Check if skill requires elevated permissions
+        3. Perform security scan (if Level 3)
+        4. Request user confirmation (if high-severity issues)
+        5. Adjust context based on confirmation
+        6. Execute skill
+        
+        Args:
+            skill_info: SkillInfo object with skill metadata
+            input_data: Input data for the skill
+            entry_point: Optional specific script to execute
+            confirmation_callback: Callback for security confirmation
+            allow_network: Override network setting
+            timeout: Override timeout setting
+            
+        Returns:
+            ExecutionResult with output or error
+        """
+        # 1. Read current context from environment
+        context = ExecutionContext.from_current_env()
+
+        # 2. Apply overrides
+        if allow_network is not None or timeout is not None:
+            context = context.with_override(
+                allow_network=allow_network,
+                timeout=timeout,
+            )
+
+        # 3. Check if skill requires elevated permissions
+        requires_elevated = self._requires_elevated_permissions(skill_info)
+        if requires_elevated:
+            context = context.with_elevated_permissions()
+        
+        # 4. Security scan and confirmation (Level 3 only)
+        if context.sandbox_level == "3":
+            scan_result = self._perform_security_scan(skill_info, input_data)
+            
+            if scan_result and scan_result.requires_confirmation:
+                if confirmation_callback:
+                    report = scan_result.format_report()
+                    confirmed = confirmation_callback(report, scan_result.scan_id)
+                    
+                    if confirmed:
+                        # User confirmed -> downgrade to Level 1
+                        context = context.with_user_confirmation(scan_result.scan_id)
+                    else:
+                        return ExecutionResult(
+                            success=False,
+                            error="Execution cancelled by user after security review",
+                            exit_code=1,
+                        )
+                else:
+                    # No callback, return security report
+                    return ExecutionResult(
+                        success=False,
+                        error=f"Security confirmation required:\n{scan_result.format_report()}",
+                        exit_code=2,
+                    )
+        
+        # 5. Execute skill
+        return self._executor.execute(
+            context=context,
+            skill_dir=skill_info.path,
+            input_data=input_data,
+            entry_point=entry_point,
+        )
+
+    def execute_with_context(
+        self,
+        context: ExecutionContext,
+        skill_dir: Path,
+        input_data: Dict[str, Any],
+        entry_point: Optional[str] = None,
+        args: Optional[list] = None,
+    ) -> ExecutionResult:
+        """
+        Execute with explicit context (bypasses security scan).
+
+        Use this when you've already performed security checks
+        and have a prepared context.
+
+        Args:
+            context: Pre-configured execution context
+            skill_dir: Path to skill directory
+            input_data: Input data for the skill
+            entry_point: Optional specific script to execute
+            args: Optional command line arguments
+
+        Returns:
+            ExecutionResult with output or error
+        """
+        return self._executor.execute(
+            context=context,
+            skill_dir=skill_dir,
+            input_data=input_data,
+            entry_point=entry_point,
+            args=args,
+        )
+
+    def _requires_elevated_permissions(self, skill_info: "SkillInfo") -> bool:
+        """Check if skill requires elevated permissions."""
+        if skill_info.metadata:
+            return getattr(skill_info.metadata, 'requires_elevated_permissions', False)
+        return False
+
+    def _perform_security_scan(
+        self,
+        skill_info: "SkillInfo",
+        input_data: Dict[str, Any],
+    ):
+        """Perform security scan on skill."""
+        try:
+            scanner = self._get_scanner()
+            return scanner.scan_skill(skill_info, input_data)
+        except Exception:
+            return None
+
+    @contextmanager
+    def temporary_context(
+        self,
+        sandbox_level: Optional[str] = None,
+        allow_network: Optional[bool] = None,
+    ):
+        """
+        Context manager for temporary execution context changes.
+
+        This temporarily modifies environment variables and restores
+        them when the context exits.
+
+        Usage:
+            with service.temporary_context(sandbox_level="1"):
+                result = service.execute_skill(...)
+
+        Args:
+            sandbox_level: Temporary sandbox level
+            allow_network: Temporary network setting
+        """
+        old_sandbox_level = os.environ.get("SKILLBOX_SANDBOX_LEVEL")
+        old_allow_network = os.environ.get("SKILLBOX_ALLOW_NETWORK")
+
+        try:
+            if sandbox_level is not None:
+                os.environ["SKILLBOX_SANDBOX_LEVEL"] = sandbox_level
+            if allow_network is not None:
+                os.environ["SKILLBOX_ALLOW_NETWORK"] = "true" if allow_network else "false"
+            yield
+        finally:
+            # Restore original values
+            if sandbox_level is not None:
+                if old_sandbox_level is not None:
+                    os.environ["SKILLBOX_SANDBOX_LEVEL"] = old_sandbox_level
+                elif "SKILLBOX_SANDBOX_LEVEL" in os.environ:
+                    del os.environ["SKILLBOX_SANDBOX_LEVEL"]
+
+            if allow_network is not None:
+                if old_allow_network is not None:
+                    os.environ["SKILLBOX_ALLOW_NETWORK"] = old_allow_network
+                elif "SKILLBOX_ALLOW_NETWORK" in os.environ:
+                    del os.environ["SKILLBOX_ALLOW_NETWORK"]
+
+    def get_current_context(self) -> ExecutionContext:
+        """Get current execution context from environment."""
+        return ExecutionContext.from_current_env()
+
+
+__all__ = ["UnifiedExecutionService", "ConfirmationCallback"]
+

skilllite/sandbox/skillbox/executor.py

@@ -156,14 +156,18 @@ class SkillboxExecutor(SandboxExecutor):
     def _build_skill_env(self, skill_dir: Path, timeout: Optional[int] = None) -> Dict[str, str]:
         """
         Build environment variables for skill execution.
-        
+
         Args:
             skill_dir: Path to the skill directory
             timeout: Optional timeout override
-            
+
         Returns:
             Environment dictionary
         """
+        # Allow runtime override of sandbox level via environment variable
+        # This enables Python-layer security confirmation to skip skillbox confirmation
+        effective_sandbox_level = os.environ.get("SKILLBOX_SANDBOX_LEVEL", self.sandbox_level)
+
         return {
             **os.environ,
             "PYTHONUNBUFFERED": "1",
@@ -171,12 +175,81 @@ class SkillboxExecutor(SandboxExecutor):
             "SKILL_ASSETS_DIR": str(skill_dir / "assets"),
             "SKILL_REFERENCES_DIR": str(skill_dir / "references"),
             "SKILL_SCRIPTS_DIR": str(skill_dir / "scripts"),
-            "SKILLBOX_SANDBOX_LEVEL": self.sandbox_level,
+            "SKILLBOX_SANDBOX_LEVEL": effective_sandbox_level,
             "SKILLBOX_MAX_MEMORY_MB": str(self.max_memory_mb),
             "SKILLBOX_TIMEOUT_SECS": str(timeout if timeout is not None else self.execution_timeout),
             "SKILLBOX_AUTO_APPROVE": os.environ.get("SKILLBOX_AUTO_APPROVE", ""),
         }
-    
+
+    def _format_sandbox_error(self, error_msg: str) -> str:
+        """
+        Format sandbox restriction errors into user-friendly messages.
+
+        Args:
+            error_msg: Raw error message from subprocess
+
+        Returns:
+            Formatted error message
+        """
+        # Check for common sandbox restriction patterns
+        sandbox_errors = {
+            "BlockingIOError": "🔒 Sandbox blocked process creation (fork/exec not allowed)",
+            "Resource temporarily unavailable": "🔒 Sandbox blocked system resource access",
+            "Operation not permitted": "🔒 Sandbox blocked this operation",
+            "Permission denied": "🔒 Sandbox denied file/resource access",
+            "sandbox-exec": "🔒 Sandbox restriction triggered",
+        }
+
+        for pattern, friendly_msg in sandbox_errors.items():
+            if pattern in error_msg:
+                # Return only the friendly message, hide the traceback
+                return f"{friendly_msg}\n\n💡 This skill requires operations that are blocked by the sandbox for security reasons."
+
+        return error_msg
+
+    def _extract_json_from_output(self, output: str) -> Optional[Any]:
+        """
+        Try to extract JSON from skillbox output that may contain log lines.
+
+        Skillbox output format may include:
+        - [INFO] ... log lines
+        - [WARN] ... log lines
+        - Error: ... messages
+        - Then the actual JSON object
+
+        Args:
+            output: Raw output from skillbox
+
+        Returns:
+            Parsed JSON object if found, None otherwise
+        """
+        if not output:
+            return None
+
+        # First try: parse entire output as JSON
+        try:
+            return json.loads(output.strip())
+        except json.JSONDecodeError:
+            pass
+
+        # Second try: find JSON object by looking for { and matching }
+        # This handles cases where JSON contains newlines (like \n in strings)
+        brace_start = output.rfind('{')
+        if brace_start == -1:
+            return None
+
+        brace_end = output.rfind('}')
+        if brace_end == -1 or brace_end < brace_start:
+            return None
+
+        json_str = output[brace_start:brace_end + 1]
+        try:
+            return json.loads(json_str)
+        except json.JSONDecodeError:
+            pass
+
+        return None
+
     def _parse_output(self, stdout: str, stderr: str, returncode: int) -> ExecutionResult:
         """
         Parse subprocess output into ExecutionResult.
@@ -209,9 +282,13 @@ class SkillboxExecutor(SandboxExecutor):
                     stderr=stderr
                 )
         else:
+            # Check for sandbox restriction errors and provide friendly messages
+            error_msg = stderr or stdout or f"Exit code: {returncode}"
+            error_msg = self._format_sandbox_error(error_msg)
+
             return ExecutionResult(
                 success=False,
-                error=stderr or f"Exit code: {returncode}",
+                error=error_msg,
                 exit_code=returncode,
                 stdout=stdout,
                 stderr=stderr
@@ -284,10 +361,12 @@ class SkillboxExecutor(SandboxExecutor):
         
         if allow_network:
             cmd.append("--allow-network")
-        
-        if enable_sandbox:
-            cmd.append("--enable-sandbox")
-        
+
+        # Use --sandbox-level instead of --enable-sandbox
+        # sandbox_level: 1=no sandbox, 2=sandbox only, 3=sandbox+scan
+        if self.sandbox_level:
+            cmd.extend(["--sandbox-level", str(self.sandbox_level)])
+
         if self.cache_dir:
             cmd.extend(["--cache-dir", self.cache_dir])
         
@@ -537,20 +616,25 @@ class SkillboxExecutor(SandboxExecutor):
             cmd.extend(["--cache-dir", self.cache_dir])
         
         skill_env = self._build_skill_env(skill_dir, timeout)
-        
+
+        # Get effective sandbox level (may be overridden by environment variable)
+        effective_sandbox_level = skill_env.get("SKILLBOX_SANDBOX_LEVEL", self.sandbox_level)
+
         # Execute with Level 3 user interaction support
         try:
-            if self.sandbox_level == "3":
+            if effective_sandbox_level == "3":
+                # Level 3: Allow user interaction for authorization prompts
                 result = subprocess.run(
                     cmd,
                     stdin=None,
                     stdout=subprocess.PIPE,
-                    stderr=None,
+                    stderr=None,  # Let stderr flow to terminal for authorization prompts
                     text=True,
                     timeout=effective_timeout,
                     env=skill_env
                 )
             else:
+                # Level 1/2: Capture all output
                 result = subprocess.run(
                     cmd,
                     capture_output=True,
@@ -560,10 +644,14 @@ class SkillboxExecutor(SandboxExecutor):
                 )
             
             stderr = result.stderr if hasattr(result, 'stderr') and result.stderr else ""
-            
+
+            # Combine stdout and stderr for JSON extraction
+            # skillbox may output JSON to either stream
+            combined_output = result.stdout + stderr
+
             if result.returncode == 0:
-                try:
-                    output = json.loads(result.stdout.strip())
+                output = self._extract_json_from_output(combined_output)
+                if output is not None:
                     return ExecutionResult(
                         success=True,
                         output=output,
@@ -571,18 +659,35 @@ class SkillboxExecutor(SandboxExecutor):
                         stdout=result.stdout,
                         stderr=stderr
                     )
-                except json.JSONDecodeError as e:
+                else:
+                    # No JSON found, return raw output as success
                     return ExecutionResult(
-                        success=False,
-                        error=f"Invalid JSON output: {e}",
+                        success=True,
+                        output={"raw_output": result.stdout.strip()},
                         exit_code=result.returncode,
                         stdout=result.stdout,
                         stderr=stderr
                     )
             else:
+                # Check if there's valid JSON in combined output (skillbox may still output results)
+                output = self._extract_json_from_output(combined_output)
+                if output is not None:
+                    # If we found valid JSON with exit_code=0, treat as success
+                    if isinstance(output, dict) and output.get("exit_code") == 0:
+                        return ExecutionResult(
+                            success=True,
+                            output=output,
+                            exit_code=0,
+                            stdout=result.stdout,
+                            stderr=stderr
+                        )
+
+                error_msg = stderr or result.stdout or f"Exit code: {result.returncode}"
+                error_msg = self._format_sandbox_error(error_msg)
+
                 return ExecutionResult(
                     success=False,
-                    error=stderr or f"Exit code: {result.returncode}",
+                    error=error_msg,
                     exit_code=result.returncode,
                     stdout=result.stdout,
                     stderr=stderr