cite-agent 1.3.9__py3-none-any.whl → 1.4.3__py3-none-any.whl

cite_agent/error_handler.py

@@ -0,0 +1,228 @@
+"""
+Graceful Error Handling - Never Expose Technical Details to Users
+Converts technical errors to friendly, actionable messages
+"""
+
+import logging
+from typing import Optional, Dict, Any
+
+logger = logging.getLogger(__name__)
+
+
+class GracefulErrorHandler:
+    """
+    Converts all technical errors to user-friendly messages
+
+    PRINCIPLE: Users should never see:
+    - Stack traces
+    - API error codes
+    - Certificate errors
+    - Connection details
+    - Internal variable names
+    - Technical jargon
+
+    PRINCIPLE: Users should always see:
+    - What went wrong in simple terms
+    - What they can do about it
+    - Alternative options if available
+    """
+
+    # User-friendly error messages mapped from technical errors
+    ERROR_MESSAGES = {
+        # Network / Connection
+        'ConnectionError': "I'm having trouble connecting right now. Please try again in a moment.",
+        'Timeout': "That's taking longer than expected. Let me try a simpler approach.",
+        'TimeoutError': "That's taking longer than expected. Let me try a simpler approach.",
+        'ConnectTimeout': "I couldn't connect. Please check your network and try again.",
+
+        # API Errors
+        'HTTPError': "I encountered an issue accessing that service. Let me try again.",
+        'APIError': "Something went wrong on my end. Let me try another way.",
+        'RateLimitError': "I've hit my usage limit. Please try again in a few minutes.",
+        'QuotaExceeded': "I've reached my daily limit. Please try again tomorrow.",
+
+        # Authentication / Authorization
+        'AuthenticationError': "I'm having trouble with authentication. Please check your setup.",
+        'PermissionError': "I don't have permission to access that. Please check the permissions.",
+        'UnauthorizedError': "I need authorization to access that resource.",
+
+        # Data / Parsing
+        'JSONDecodeError': "I received data in an unexpected format. Let me try again.",
+        'ParseError': "I couldn't understand the response. Let me try another approach.",
+        'ValueError': "I received unexpected data. Let me try again.",
+        'KeyError': "I couldn't find the expected information. Let me try differently.",
+
+        # TLS / SSL / Certificate
+        'SSLError': "I'm having trouble with the secure connection. Please try again.",
+        'CertificateError': "I'm having trouble with the secure connection. Please try again.",
+        'TLS_error': "I'm having trouble with the secure connection. Please try again.",
+
+        # File System
+        'FileNotFoundError': "I couldn't find that file. Please check the path.",
+        'IsADirectoryError': "That's a directory, not a file. Please specify a file path.",
+        'NotADirectoryError': "That's a file, not a directory. Please specify a directory path.",
+        'PermissionError_file': "I don't have permission to access that file.",
+
+        # General
+        'Exception': "Something unexpected happened. Let me try again.",
+        'RuntimeError': "I encountered an unexpected issue. Let me try another approach.",
+    }
+
+    @classmethod
+    def handle_error(
+        cls,
+        error: Exception,
+        context: str = "",
+        fallback_action: Optional[str] = None
+    ) -> str:
+        """
+        Convert any error to a user-friendly message
+
+        Args:
+            error: The exception that occurred
+            context: What the agent was trying to do (e.g., "search papers", "read file")
+            fallback_action: What the user can do instead (e.g., "try a different search")
+
+        Returns:
+            User-friendly error message (never technical details)
+        """
+        # Log technical details for debugging (but don't show to user!)
+        logger.error(f"Error in {context}: {type(error).__name__}: {str(error)}", exc_info=True)
+
+        # Get error type name
+        error_type = type(error).__name__
+
+        # Look up user-friendly message
+        user_message = cls.ERROR_MESSAGES.get(error_type)
+
+        # Check for specific error patterns in the message
+        error_str = str(error).lower()
+
+        if not user_message:
+            # Pattern matching for specific errors
+            if 'certificate' in error_str or 'tls' in error_str or 'ssl' in error_str:
+                user_message = cls.ERROR_MESSAGES['CertificateError']
+            elif 'timeout' in error_str:
+                user_message = cls.ERROR_MESSAGES['Timeout']
+            elif 'connection' in error_str or 'connect' in error_str:
+                user_message = cls.ERROR_MESSAGES['ConnectionError']
+            elif 'rate limit' in error_str or 'quota' in error_str:
+                user_message = cls.ERROR_MESSAGES['RateLimitError']
+            elif 'auth' in error_str or 'unauthorized' in error_str:
+                user_message = cls.ERROR_MESSAGES['AuthenticationError']
+            elif 'not found' in error_str:
+                user_message = cls.ERROR_MESSAGES['FileNotFoundError']
+            else:
+                # Generic fallback
+                user_message = cls.ERROR_MESSAGES['Exception']
+
+        # Add context if provided
+        if context:
+            full_message = f"While trying to {context}, {user_message.lower()}"
+        else:
+            full_message = user_message
+
+        # Add fallback action if provided
+        if fallback_action:
+            full_message += f" {fallback_action}"
+
+        return full_message
+
+    @classmethod
+    def wrap_response_with_error_handling(cls, response: str) -> str:
+        """
+        Scan response for any leaked technical errors and clean them
+
+        This is a safety net in case errors slip through
+        """
+        # Technical terms that should NEVER appear in user responses
+        forbidden_patterns = [
+            ('TLS_error', 'secure connection issue'),
+            ('CERTIFICATE_VERIFY_FAILED', 'secure connection issue'),
+            ('upstream connect error', 'connection issue'),
+            ('stack trace', ''),
+            ('Traceback (most recent call last)', ''),
+            ('Exception:', ''),
+            ('ERROR:', ''),
+            ('⚠️ I couldn\'t finish the reasoning step', 'I encountered an issue'),
+            ('language model call failed', 'I had trouble processing that'),
+            ('API call failed', 'I had trouble accessing that service'),
+        ]
+
+        cleaned_response = response
+        had_technical_errors = False
+
+        for technical_term, friendly_replacement in forbidden_patterns:
+            if technical_term.lower() in cleaned_response.lower():
+                # If we find technical errors, replace with friendly version
+                logger.warning(f"Found leaked technical error in response: {technical_term}")
+                had_technical_errors = True
+
+                if friendly_replacement:
+                    # Replace with friendly term
+                    import re
+                    cleaned_response = re.sub(
+                        re.escape(technical_term),
+                        friendly_replacement,
+                        cleaned_response,
+                        flags=re.IGNORECASE
+                    )
+                else:
+                    # Remove the line entirely
+                    lines = cleaned_response.split('\n')
+                    cleaned_response = '\n'.join([
+                        line for line in lines
+                        if technical_term.lower() not in line.lower()
+                    ])
+
+        # If the response became empty or too short AFTER cleaning errors, provide generic friendly message
+        # Don't flag legitimately short responses (greetings, acknowledgments, etc.)
+        if had_technical_errors and len(cleaned_response.strip()) < 20:
+            cleaned_response = "I encountered an issue while processing that. Could you try rephrasing your question?"
+
+        return cleaned_response
+
+    @classmethod
+    def create_fallback_response(cls, original_query: str, error: Exception) -> str:
+        """
+        Create a complete fallback response when main processing fails
+
+        Returns a helpful response instead of exposing the error
+        """
+        # Get friendly error message
+        error_msg = cls.handle_error(error, "process your request")
+
+        # Try to be helpful based on query type
+        query_lower = original_query.lower()
+
+        suggestions = []
+
+        if any(word in query_lower for word in ['search', 'find', 'papers', 'research']):
+            suggestions.append("• Try a more specific search term")
+            suggestions.append("• Check if the topic exists in our database")
+
+        if any(word in query_lower for word in ['revenue', 'stock', 'financial', 'company']):
+            suggestions.append("• Try searching for a specific company by name")
+            suggestions.append("• Check if the company is publicly traded")
+
+        if any(word in query_lower for word in ['file', 'directory', 'folder', 'read']):
+            suggestions.append("• Check if the file path is correct")
+            suggestions.append("• Try using an absolute path")
+
+        response_parts = [error_msg]
+
+        if suggestions:
+            response_parts.append("\nYou could try:")
+            response_parts.extend(suggestions)
+
+        return '\n'.join(response_parts)
+
+
+# Convenient function for quick error handling
+def handle_error_gracefully(
+    error: Exception,
+    context: str = "",
+    fallback_action: Optional[str] = None
+) -> str:
+    """Shortcut function for graceful error handling"""
+    return GracefulErrorHandler.handle_error(error, context, fallback_action)

cite_agent/execution_safety.py

@@ -0,0 +1,329 @@
+"""
+Command Execution Safety & Enforcement
+Ensures backend executes EXACTLY what agent planned - validates pre/post execution
+"""
+
+import json
+import hashlib
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional, Any
+from datetime import datetime
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class CommandClassification(Enum):
+    """Safety classification for commands"""
+    SAFE = "safe"                  # File reads, non-destructive queries
+    WRITE = "write"                # File writes, modifications
+    DANGEROUS = "dangerous"         # Dangerous: rm -rf, format disk
+    BLOCKED = "blocked"            # Never execute
+
+
+class CommandAuditLevel(Enum):
+    """How strictly to audit commands"""
+    PERMISSIVE = "permissive"      # Allow, log only
+    STRICT = "strict"              # Require pre-approval
+    ENFORCED = "enforced"          # Prevent mismatches
+
+
+@dataclass
+class CommandPlan:
+    """What agent intends to do"""
+    command: str
+    classification: CommandClassification
+    reason: str  # Why this command
+    expected_output_pattern: Optional[str] = None
+    max_execution_time_s: float = 60.0
+    
+    def get_hash(self) -> str:
+        """Get hash of command for comparison"""
+        return hashlib.sha256(self.command.encode()).hexdigest()[:16]
+
+
+@dataclass
+class CommandExecution:
+    """Record of command execution"""
+    command: str
+    planned_hash: str
+    executed_hash: str
+    classification: CommandClassification
+    status: str  # success, failure, timeout, mismatch
+    exit_code: int = 0
+    output: str = ""
+    error: str = ""
+    execution_time_s: float = 0.0
+    timestamp: datetime = field(default_factory=datetime.now)
+    user_id: Optional[str] = None
+    
+    def was_modified(self) -> bool:
+        """Check if executed command differs from planned"""
+        return self.planned_hash != self.executed_hash
+    
+    def to_audit_log(self) -> str:
+        """Format as audit log entry"""
+        modified = "⚠️ MODIFIED" if self.was_modified() else "✓ AS-PLANNED"
+        return (
+            f"{self.timestamp.isoformat()} | {self.classification.value.upper()} | "
+            f"{modified} | exit={self.exit_code} | {self.command[:60]}..."
+        )
+
+
+class CommandExecutionValidator:
+    """
+    Pre and post-execution validation to ensure safety
+    
+    Prevents:
+    - Agent plans "cat file.txt", backend executes "rm -rf /"
+    - Command injection attacks
+    - Unexpected output/errors
+    - Timeout vulnerabilities
+    """
+    
+    def __init__(self, audit_level: CommandAuditLevel = CommandAuditLevel.STRICT):
+        self.audit_level = audit_level
+        self.audit_log: List[CommandExecution] = []
+        self.dangerous_patterns = [
+            "rm -rf",
+            "mkfs",
+            "format",
+            ": () { :",  # Bash fork bomb
+            "dd if=/dev/zero of=/",
+            "chmod -R 777 /",
+            "reboot",
+            "shutdown -h",
+        ]
+        self.blocked_commands = [
+            "sudo rm -rf /",
+            "rm -rf /etc",
+            "rm -rf /boot",
+        ]
+    
+    def validate_plan(self, plan: CommandPlan) -> tuple[bool, Optional[str]]:
+        """
+        Validate a command plan before execution
+        
+        Returns:
+            (is_valid, error_reason)
+        """
+        # Check for explicitly blocked commands
+        for blocked in self.blocked_commands:
+            if blocked in plan.command:
+                return False, f"Command explicitly blocked: {blocked}"
+        
+        # Check classification
+        if plan.classification == CommandClassification.BLOCKED:
+            return False, f"Command classified as BLOCKED"
+        
+        # For DANGEROUS commands, require strict approval
+        if plan.classification == CommandClassification.DANGEROUS:
+            if self.audit_level == CommandAuditLevel.PERMISSIVE:
+                logger.warning(f"⚠️ DANGEROUS command allowed in permissive mode: {plan.command}")
+            else:
+                return False, "Dangerous commands require special approval"
+        
+        # Check for dangerous patterns
+        for pattern in self.dangerous_patterns:
+            if pattern in plan.command:
+                classification = CommandClassification.DANGEROUS
+                if plan.classification == CommandClassification.SAFE:
+                    return False, f"Command contains dangerous pattern: {pattern}"
+        
+        return True, None
+    
+    def validate_execution(
+        self,
+        plan: CommandPlan,
+        executed_command: str,
+        exit_code: int,
+        output: str,
+        error: str,
+        execution_time_s: float,
+        user_id: Optional[str] = None
+    ) -> tuple[bool, Optional[str]]:
+        """
+        Validate execution matches plan
+        
+        Returns:
+            (is_valid, error_reason)
+        """
+        # Record execution
+        execution = CommandExecution(
+            command=executed_command,
+            planned_hash=plan.get_hash(),
+            executed_hash=hashlib.sha256(executed_command.encode()).hexdigest()[:16],
+            classification=plan.classification,
+            status="unknown",
+            exit_code=exit_code,
+            output=output,
+            error=error,
+            execution_time_s=execution_time_s,
+            user_id=user_id
+        )
+        
+        # Check for modification
+        if execution.was_modified():
+            if self.audit_level == CommandAuditLevel.ENFORCED:
+                execution.status = "mismatch"
+                self.audit_log.append(execution)
+                return False, f"Command was modified during execution!\nPlanned: {plan.command}\nExecuted: {executed_command}"
+            else:
+                logger.warning(
+                    f"⚠️ Command modification detected:\n"
+                    f"  Planned: {plan.command}\n"
+                    f"  Executed: {executed_command}"
+                )
+        
+        # Check timeout
+        if execution_time_s > plan.max_execution_time_s:
+            execution.status = "timeout"
+            self.audit_log.append(execution)
+            return False, f"Command exceeded max execution time: {execution_time_s:.1f}s > {plan.max_execution_time_s}s"
+        
+        # Check for unexpected errors
+        if error and plan.classification == CommandClassification.SAFE:
+            # SAFE commands shouldn't produce errors
+            if exit_code != 0:
+                execution.status = "error"
+                self.audit_log.append(execution)
+                return False, f"Safe command produced error (exit {exit_code}): {error}"
+        
+        # Verify output matches expected pattern if specified
+        if plan.expected_output_pattern:
+            import re
+            if not re.search(plan.expected_output_pattern, output):
+                logger.warning(
+                    f"⚠️ Output doesn't match expected pattern:\n"
+                    f"  Pattern: {plan.expected_output_pattern}\n"
+                    f"  Got: {output[:200]}"
+                )
+        
+        # Mark as success
+        execution.status = "success" if exit_code == 0 else "failure"
+        self.audit_log.append(execution)
+        
+        return True, None
+    
+    def get_audit_log(self, limit: int = 50) -> List[str]:
+        """Get recent audit log entries"""
+        return [entry.to_audit_log() for entry in self.audit_log[-limit:]]
+    
+    def get_command_stats(self) -> Dict[str, Any]:
+        """Get statistics about commands executed"""
+        if not self.audit_log:
+            return {"total": 0}
+        
+        safe_count = sum(1 for e in self.audit_log if e.classification == CommandClassification.SAFE)
+        write_count = sum(1 for e in self.audit_log if e.classification == CommandClassification.WRITE)
+        dangerous_count = sum(1 for e in self.audit_log if e.classification == CommandClassification.DANGEROUS)
+        failed_count = sum(1 for e in self.audit_log if e.status == "failure")
+        modified_count = sum(1 for e in self.audit_log if e.was_modified())
+        
+        return {
+            "total_executed": len(self.audit_log),
+            "safe_commands": safe_count,
+            "write_commands": write_count,
+            "dangerous_commands": dangerous_count,
+            "failed_commands": failed_count,
+            "modified_commands": modified_count,
+            "modification_rate": modified_count / len(self.audit_log) if self.audit_log else 0,
+            "failure_rate": failed_count / len(self.audit_log) if self.audit_log else 0,
+        }
+    
+    def get_status_message(self) -> str:
+        """Human-readable status"""
+        stats = self.get_command_stats()
+        
+        if stats.get("total_executed", 0) == 0:
+            return "📋 **Command Execution Safety**: No commands executed yet"
+        
+        lines = [
+            "📋 **Command Execution Safety**",
+            f"• Audit level: {self.audit_level.value.upper()}",
+            f"• Total executed: {stats['total_executed']}",
+            f"• Safe commands: {stats['safe_commands']} | Write: {stats['write_commands']} | Dangerous: {stats['dangerous_commands']}",
+            f"• Failures: {stats['failed_commands']} ({stats['failure_rate']:.1%})",
+            f"• Modifications detected: {stats['modified_commands']} ({stats['modification_rate']:.1%})",
+        ]
+        
+        if stats['modification_rate'] > 0:
+            lines.append("\n⚠️ **WARNING**: Commands being modified during execution!")
+        
+        return "\n".join(lines)
+
+
+class CommandSandbox:
+    """
+    Optional sandboxing for dangerous commands
+    Runs in isolated environment with limited permissions
+    """
+    
+    def __init__(self, enable_sandbox: bool = False):
+        self.enabled = enable_sandbox
+    
+    def prepare_sandbox(self, command: str, dangerous: bool = False) -> str:
+        """
+        Wrap command in sandbox if needed
+        
+        Returns modified command that runs safely
+        """
+        if not self.enabled or not dangerous:
+            return command
+        
+        # Use firejail if available
+        sandboxed = f"firejail --quiet --timeout=60 {command}"
+        return sandboxed
+    
+    def cleanup_sandbox(self):
+        """Clean up sandbox resources"""
+        if self.enabled:
+            logger.info("🧹 Cleaning up sandbox")
+
+
+# Global validator
+command_validator = CommandExecutionValidator()
+
+
+if __name__ == "__main__":
+    # Test the validator
+    validator = CommandExecutionValidator(CommandAuditLevel.STRICT)
+    
+    # Test 1: Safe command
+    plan = CommandPlan(
+        command="cat /etc/hostname",
+        classification=CommandClassification.SAFE,
+        reason="Read system hostname",
+        expected_output_pattern=r"\w+"
+    )
+    
+    valid, error = validator.validate_plan(plan)
+    print(f"Plan validation: {valid} - {error}")
+    
+    # Simulate execution
+    valid, error = validator.validate_execution(
+        plan,
+        executed_command="cat /etc/hostname",
+        exit_code=0,
+        output="localhost\n",
+        error="",
+        execution_time_s=0.05
+    )
+    print(f"Execution validation: {valid} - {error}")
+    
+    # Test 2: Dangerous command
+    plan2 = CommandPlan(
+        command="rm -rf /tmp/test",
+        classification=CommandClassification.DANGEROUS,
+        reason="Clean test directory"
+    )
+    
+    valid, error = validator.validate_plan(plan2)
+    print(f"\nDangerous plan validation: {valid} - {error}")
+    
+    # Show audit log
+    print("\n" + validator.get_status_message())
+    print("\n📋 **Audit Log**")
+    for entry in validator.get_audit_log(5):
+        print(f"  {entry}")