agentfense 0.2.1__py3-none-any.whl

agentfense/exceptions.py

@@ -0,0 +1,333 @@
+"""Exception classes for the Sandbox SDK.
+
+This module defines a hierarchy of exceptions that provide meaningful
+error messages and context for SDK operations, replacing raw gRPC exceptions.
+"""
+
+from typing import Optional
+
+
+class SandboxError(Exception):
+    """Base exception for all Sandbox SDK errors.
+    
+    All SDK-specific exceptions inherit from this class, making it easy
+    to catch any SDK error with a single except clause.
+    
+    Attributes:
+        message: Human-readable error description.
+        details: Optional additional error context.
+        grpc_code: Original gRPC status code if applicable.
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        details: Optional[str] = None,
+        grpc_code: Optional[int] = None,
+    ):
+        self.message = message
+        self.details = details
+        self.grpc_code = grpc_code
+        super().__init__(self._format_message())
+    
+    def _format_message(self) -> str:
+        msg = self.message
+        if self.details:
+            msg += f" Details: {self.details}"
+        return msg
+
+
+class ConnectionError(SandboxError):
+    """Failed to connect to the sandbox service.
+    
+    Raised when the SDK cannot establish a connection to the gRPC server.
+    This could be due to network issues, server being down, or incorrect endpoint.
+    """
+    
+    def __init__(
+        self,
+        endpoint: str,
+        details: Optional[str] = None,
+        grpc_code: Optional[int] = None,
+    ):
+        self.endpoint = endpoint
+        super().__init__(
+            f"Failed to connect to sandbox service at '{endpoint}'",
+            details=details,
+            grpc_code=grpc_code,
+        )
+
+
+class SandboxNotFoundError(SandboxError):
+    """The specified sandbox does not exist.
+    
+    Raised when attempting to access a sandbox that doesn't exist or has been deleted.
+    """
+    
+    def __init__(self, sandbox_id: str, details: Optional[str] = None):
+        self.sandbox_id = sandbox_id
+        super().__init__(
+            f"Sandbox '{sandbox_id}' not found",
+            details=details,
+        )
+
+
+class SandboxNotRunningError(SandboxError):
+    """The sandbox is not in a running state.
+    
+    Raised when attempting to execute commands or create sessions
+    on a sandbox that hasn't been started or has been stopped.
+    """
+    
+    def __init__(
+        self,
+        sandbox_id: str,
+        current_status: str,
+        details: Optional[str] = None,
+    ):
+        self.sandbox_id = sandbox_id
+        self.current_status = current_status
+        super().__init__(
+            f"Sandbox '{sandbox_id}' is not running (current status: {current_status})",
+            details=details,
+        )
+
+
+class CodebaseError(SandboxError):
+    """Error related to codebase operations.
+    
+    Raised for errors during codebase creation, file upload/download, etc.
+    """
+    pass
+
+
+class CodebaseNotFoundError(CodebaseError):
+    """The specified codebase does not exist.
+    
+    Raised when attempting to access a codebase that doesn't exist or has been deleted.
+    """
+    
+    def __init__(self, codebase_id: str, details: Optional[str] = None):
+        self.codebase_id = codebase_id
+        super().__init__(
+            f"Codebase '{codebase_id}' not found",
+            details=details,
+        )
+
+
+class FileNotFoundError(CodebaseError):
+    """The specified file does not exist in the codebase.
+    
+    Raised when attempting to download or access a file that doesn't exist.
+    """
+    
+    def __init__(
+        self,
+        codebase_id: str,
+        file_path: str,
+        details: Optional[str] = None,
+    ):
+        self.codebase_id = codebase_id
+        self.file_path = file_path
+        super().__init__(
+            f"File '{file_path}' not found in codebase '{codebase_id}'",
+            details=details,
+        )
+
+
+class CommandTimeoutError(SandboxError):
+    """Command execution timed out.
+    
+    Raised when a command takes longer than the specified timeout duration.
+    The command may still be running in the sandbox.
+    """
+    
+    def __init__(
+        self,
+        command: str,
+        timeout_seconds: float,
+        details: Optional[str] = None,
+    ):
+        self.command = command
+        self.timeout_seconds = timeout_seconds
+        super().__init__(
+            f"Command timed out after {timeout_seconds}s: {command[:100]}...",
+            details=details,
+        )
+
+
+class CommandExecutionError(SandboxError):
+    """Command execution failed.
+    
+    Raised when a command exits with a non-zero status code and
+    raise_on_error is enabled.
+    """
+    
+    def __init__(
+        self,
+        command: str,
+        exit_code: int,
+        stdout: str = "",
+        stderr: str = "",
+    ):
+        self.command = command
+        self.exit_code = exit_code
+        self.stdout = stdout
+        self.stderr = stderr
+        
+        # Build error message
+        details = None
+        if stderr:
+            details = stderr[:500]
+        elif stdout:
+            details = stdout[:500]
+            
+        super().__init__(
+            f"Command failed with exit code {exit_code}: {command[:100]}",
+            details=details,
+        )
+
+
+class PermissionDeniedError(SandboxError):
+    """Permission denied for the requested operation.
+    
+    Raised when the sandbox's permission rules prevent access to a file or operation.
+    """
+    
+    def __init__(
+        self,
+        operation: str,
+        path: Optional[str] = None,
+        details: Optional[str] = None,
+    ):
+        self.operation = operation
+        self.path = path
+        
+        if path:
+            message = f"Permission denied for {operation} on '{path}'"
+        else:
+            message = f"Permission denied for {operation}"
+            
+        super().__init__(message, details=details)
+
+
+class SessionError(SandboxError):
+    """Error related to session operations."""
+    pass
+
+
+class SessionNotFoundError(SessionError):
+    """The specified session does not exist.
+    
+    Raised when attempting to access a session that doesn't exist or has been closed.
+    """
+    
+    def __init__(self, session_id: str, details: Optional[str] = None):
+        self.session_id = session_id
+        super().__init__(
+            f"Session '{session_id}' not found",
+            details=details,
+        )
+
+
+class SessionClosedError(SessionError):
+    """The session has been closed.
+    
+    Raised when attempting to execute commands in a closed session.
+    """
+    
+    def __init__(self, session_id: str, details: Optional[str] = None):
+        self.session_id = session_id
+        super().__init__(
+            f"Session '{session_id}' is closed",
+            details=details,
+        )
+
+
+class ResourceLimitExceededError(SandboxError):
+    """Resource limit exceeded.
+    
+    Raised when a sandbox exceeds its allocated resources (memory, CPU, etc.).
+    """
+    
+    def __init__(
+        self,
+        resource_type: str,
+        limit: str,
+        details: Optional[str] = None,
+    ):
+        self.resource_type = resource_type
+        self.limit = limit
+        super().__init__(
+            f"Resource limit exceeded: {resource_type} limit is {limit}",
+            details=details,
+        )
+
+
+class InvalidConfigurationError(SandboxError):
+    """Invalid configuration provided.
+    
+    Raised when the provided configuration is invalid or inconsistent.
+    """
+    pass
+
+
+class UploadError(CodebaseError):
+    """File upload failed.
+    
+    Raised when uploading a file to a codebase fails.
+    """
+    
+    def __init__(
+        self,
+        file_path: str,
+        codebase_id: str,
+        details: Optional[str] = None,
+    ):
+        self.file_path = file_path
+        self.codebase_id = codebase_id
+        super().__init__(
+            f"Failed to upload '{file_path}' to codebase '{codebase_id}'",
+            details=details,
+        )
+
+
+def from_grpc_error(error, context: Optional[str] = None) -> SandboxError:
+    """Convert a gRPC error to an appropriate SandboxError.
+    
+    Args:
+        error: The gRPC RpcError exception.
+        context: Optional context about the operation that failed.
+        
+    Returns:
+        An appropriate SandboxError subclass.
+    """
+    import grpc
+    
+    code = error.code() if hasattr(error, 'code') else None
+    details = error.details() if hasattr(error, 'details') else str(error)
+    
+    if context:
+        details = f"{context}. {details}"
+    
+    grpc_code = code.value if code else None
+    
+    # Map gRPC codes to SDK exceptions
+    if code == grpc.StatusCode.NOT_FOUND:
+        return SandboxError(f"Resource not found", details=details, grpc_code=grpc_code)
+    elif code == grpc.StatusCode.PERMISSION_DENIED:
+        return PermissionDeniedError("operation", details=details)
+    elif code == grpc.StatusCode.DEADLINE_EXCEEDED:
+        return CommandTimeoutError("unknown", 0, details=details)
+    elif code == grpc.StatusCode.UNAVAILABLE:
+        return ConnectionError("unknown", details=details, grpc_code=grpc_code)
+    elif code == grpc.StatusCode.INVALID_ARGUMENT:
+        return InvalidConfigurationError(details or "Invalid argument")
+    elif code == grpc.StatusCode.RESOURCE_EXHAUSTED:
+        return ResourceLimitExceededError("unknown", "unknown", details=details)
+    else:
+        return SandboxError(
+            f"Operation failed",
+            details=details,
+            grpc_code=grpc_code,
+        )

agentfense/presets.py

@@ -0,0 +1,192 @@
+"""Preset permission templates for common use cases.
+
+This module provides pre-defined permission configurations that cover
+common scenarios when working with AI agents and sandboxed environments.
+"""
+
+from typing import Dict, List, Optional, Union
+
+from .types import Permission, PatternType, PermissionRule
+
+
+# Public constants for preset names (better autocomplete than raw strings)
+PRESET_AGENT_SAFE = "agent-safe"
+PRESET_READ_ONLY = "read-only"
+PRESET_FULL_ACCESS = "full-access"
+PRESET_DEVELOPMENT = "development"
+PRESET_VIEW_ONLY = "view-only"
+
+
+# Pre-defined permission templates
+PRESETS: Dict[str, List[Dict[str, str]]] = {
+    # Safe preset for AI agents: read most files, write to output, hide secrets
+    PRESET_AGENT_SAFE: [
+        {"pattern": "**/*", "permission": "read", "priority": "0"},
+        {"pattern": "/output/**", "permission": "write", "priority": "10"},
+        {"pattern": "/tmp/**", "permission": "write", "priority": "10"},
+        {"pattern": "**/.env*", "permission": "none", "priority": "100"},
+        {"pattern": "**/secrets/**", "permission": "none", "priority": "100"},
+        {"pattern": "**/*.key", "permission": "none", "priority": "100"},
+        {"pattern": "**/*.pem", "permission": "none", "priority": "100"},
+        {"pattern": "**/credentials*", "permission": "none", "priority": "100"},
+        {"pattern": "**/.git/**", "permission": "none", "priority": "50"},
+    ],
+    # Read-only access to all files
+    PRESET_READ_ONLY: [
+        {"pattern": "**/*", "permission": "read", "priority": "0"},
+    ],
+    # Full write access to all files
+    PRESET_FULL_ACCESS: [
+        {"pattern": "**/*", "permission": "write", "priority": "0"},
+    ],
+    # Development preset: full access except secrets
+    PRESET_DEVELOPMENT: [
+        {"pattern": "**/*", "permission": "write", "priority": "0"},
+        {"pattern": "**/.env*", "permission": "none", "priority": "100"},
+        {"pattern": "**/secrets/**", "permission": "none", "priority": "100"},
+        {"pattern": "**/*.key", "permission": "none", "priority": "100"},
+        {"pattern": "**/*.pem", "permission": "none", "priority": "100"},
+    ],
+    # View-only: can see file names but not read content
+    PRESET_VIEW_ONLY: [
+        {"pattern": "**/*", "permission": "view", "priority": "0"},
+    ],
+}
+
+
+def get_preset(name: str) -> List[PermissionRule]:
+    """Get a preset permission configuration by name.
+    
+    Args:
+        name: The name of the preset (e.g., "agent-safe", "read-only").
+        
+    Returns:
+        List of PermissionRule objects for the preset.
+        
+    Raises:
+        ValueError: If the preset name is not found.
+        
+    Example:
+        >>> rules = get_preset("agent-safe")
+        >>> for rule in rules:
+        ...     print(f"{rule.pattern}: {rule.permission.value}")
+    """
+    if name not in PRESETS:
+        available = ", ".join(sorted(PRESETS.keys()))
+        raise ValueError(f"Unknown preset '{name}'. Available presets: {available}")
+    
+    return [
+        PermissionRule(
+            pattern=rule["pattern"],
+            permission=Permission(rule["permission"]),
+            type=PatternType(rule.get("type", "glob")),
+            priority=int(rule.get("priority", 0)),
+        )
+        for rule in PRESETS[name]
+    ]
+
+
+def get_preset_dicts(name: str) -> List[Dict[str, str]]:
+    """Get a preset as a list of dictionaries (for direct API use).
+    
+    Args:
+        name: The name of the preset.
+        
+    Returns:
+        List of permission rule dictionaries.
+        
+    Raises:
+        ValueError: If the preset name is not found.
+    """
+    if name not in PRESETS:
+        available = ", ".join(sorted(PRESETS.keys()))
+        raise ValueError(f"Unknown preset '{name}'. Available presets: {available}")
+    
+    return PRESETS[name].copy()
+
+
+def extend_preset(
+    base: str,
+    additions: Optional[List[Union[PermissionRule, Dict]]] = None,
+    overrides: Optional[List[Union[PermissionRule, Dict]]] = None,
+) -> List[PermissionRule]:
+    """Extend a preset with additional or overriding rules.
+    
+    Args:
+        base: The name of the base preset to extend.
+        additions: Additional rules to append (lower priority than base).
+        overrides: Rules to add with higher priority (override base rules).
+        
+    Returns:
+        Combined list of PermissionRule objects.
+        
+    Example:
+        >>> # Allow write access to /workspace in addition to agent-safe rules
+        >>> rules = extend_preset(
+        ...     "agent-safe",
+        ...     additions=[{"pattern": "/workspace/**", "permission": "write"}]
+        ... )
+    """
+    rules = get_preset(base)
+    
+    def to_rule(item: Union[PermissionRule, Dict]) -> PermissionRule:
+        if isinstance(item, PermissionRule):
+            return item
+        return PermissionRule(
+            pattern=item["pattern"],
+            permission=Permission(item["permission"]),
+            type=PatternType(item.get("type", "glob")),
+            priority=int(item.get("priority", 0)),
+        )
+    
+    if additions:
+        for item in additions:
+            rules.append(to_rule(item))
+    
+    if overrides:
+        # Add overrides with boosted priority
+        max_priority = max(r.priority for r in rules) if rules else 0
+        for item in overrides:
+            rule = to_rule(item)
+            # Ensure override has higher priority
+            if rule.priority <= max_priority:
+                rule = PermissionRule(
+                    pattern=rule.pattern,
+                    permission=rule.permission,
+                    type=rule.type,
+                    priority=max_priority + 100,
+                )
+            rules.append(rule)
+    
+    return rules
+
+
+def list_presets() -> List[str]:
+    """List all available preset names.
+    
+    Returns:
+        Sorted list of preset names.
+    """
+    return sorted(PRESETS.keys())
+
+
+def register_preset(name: str, rules: List[Dict[str, str]]) -> None:
+    """Register a custom preset.
+    
+    Args:
+        name: The name for the new preset.
+        rules: List of permission rule dictionaries.
+        
+    Raises:
+        ValueError: If a preset with the name already exists.
+        
+    Example:
+        >>> register_preset("my-custom", [
+        ...     {"pattern": "**/*", "permission": "read"},
+        ...     {"pattern": "/src/**", "permission": "write"},
+        ... ])
+    """
+    if name in PRESETS:
+        raise ValueError(f"Preset '{name}' already exists. Use a different name.")
+    
+    PRESETS[name] = rules