ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/logic/utils/incident_capture_handler.py

@@ -0,0 +1,303 @@
+"""
+Incident Capture Handler for capturing WARNING and ERROR level log messages as incidents.
+"""
+
+import asyncio
+import logging
+import traceback
+import uuid
+from pathlib import Path
+from typing import Any, Optional
+
+from ciris_engine.protocols.services import TimeServiceProtocol
+from ciris_engine.schemas.services.graph.incident import IncidentNode, IncidentSeverity, IncidentStatus
+from ciris_engine.schemas.services.graph_core import GraphScope, NodeType
+
+
+class IncidentCaptureHandler(logging.Handler):
+    """
+    A logging handler that captures WARNING and ERROR level messages as incidents.
+    These incidents are stored in the graph for analysis, pattern detection, and self-improvement.
+    """
+
+    def __init__(
+        self,
+        log_dir: str = "logs",
+        filename_prefix: str = "incidents",
+        time_service: Optional[TimeServiceProtocol] = None,
+        graph_audit_service: Any = None,
+    ) -> None:
+        super().__init__()
+        if not time_service:
+            raise RuntimeError("CRITICAL: TimeService is required for IncidentCaptureHandler")
+        self.log_dir = Path(log_dir)
+        self.log_dir.mkdir(parents=True, exist_ok=True)  # parents=True for subdirectories
+        self._time_service = time_service
+
+        self._graph_audit_service = graph_audit_service
+
+        # Create incident log file with timestamp
+        timestamp = self._time_service.now().strftime("%Y%m%d_%H%M%S")
+        self.log_file = self.log_dir / f"{filename_prefix}_{timestamp}.log"
+
+        # Create symlink to latest dead letter log
+        self.latest_link = self.log_dir / f"{filename_prefix}_latest.log"
+        self._create_symlink()
+
+        # Store the actual incident log filename for the telemetry endpoint
+        actual_incident_path = self.log_dir / ".current_incident_log"
+        try:
+            with open(actual_incident_path, "w") as f:
+                f.write(str(self.log_file.absolute()))
+        except Exception:
+            pass
+
+        # Set level to WARNING so we only capture WARNING and above
+        self.setLevel(logging.WARNING)
+
+        # Use a detailed format for dead letter messages
+        formatter = logging.Formatter(
+            "%(asctime)s.%(msecs)03d - %(levelname)-8s - %(name)s - %(filename)s:%(lineno)d - %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+        self.setFormatter(formatter)
+
+        # Write header to the file
+        with open(self.log_file, "w") as f:
+            f.write(f"=== Incident Log Started at {self._time_service.now_iso()} ===\n")
+            f.write("=== This file contains WARNING and ERROR messages captured as incidents ===\n\n")
+
+    def _create_symlink(self) -> None:
+        """Create or update the symlink to the latest incident log."""
+        try:
+            # Check if symlink exists (even if target is invalid)
+            if self.latest_link.is_symlink() or self.latest_link.exists():
+                self.latest_link.unlink()
+            self.latest_link.symlink_to(self.log_file.name)
+        except Exception as e:
+            # Symlinks might not work on all systems - log warning but don't fail
+            logging.warning(f"Failed to create/update incidents_latest.log symlink: {e}")
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """
+        Emit a record as an incident to both file and graph.
+
+        Only WARNING, ERROR, and CRITICAL messages are captured as incidents.
+        """
+        try:
+            # Only process WARNING and above
+            if record.levelno < logging.WARNING:
+                return
+
+            msg = self.format(record)
+
+            # Add extra context for errors
+            if record.levelno >= logging.ERROR and record.exc_info:
+                import traceback
+
+                msg += "\nException Traceback:\n"
+                msg += "".join(traceback.format_exception(*record.exc_info))
+
+            # Write to file with proper encoding
+            with open(self.log_file, "a", encoding="utf-8") as f:
+                f.write(msg + "\n")
+
+                # Add separator for ERROR and CRITICAL messages
+                if record.levelno >= logging.ERROR:
+                    f.write("-" * 80 + "\n")
+
+            # The IncidentManagementService will read from the incidents log file during dream cycles
+
+        except Exception:
+            # Failsafe - if we can't capture incident, don't crash
+            self.handleError(record)
+
+    async def _save_incident_to_graph(self, record: logging.LogRecord) -> None:
+        """Save log record as incident in graph."""
+        try:
+            # Map log level to incident severity
+            severity = self._map_log_level_to_severity(record.levelno)
+
+            # Extract correlation data from extra fields if available
+            correlation_id = getattr(record, "correlation_id", None)
+            task_id = getattr(record, "task_id", None)
+            thought_id = getattr(record, "thought_id", None)
+            handler_name = getattr(record, "handler_name", None)
+
+            # Create incident node
+            incident = IncidentNode(
+                id=f"incident_{uuid.uuid4()}",
+                type=NodeType.AUDIT_ENTRY,
+                scope=GraphScope.LOCAL,
+                attributes={},  # Required field for TypedGraphNode
+                incident_type=record.levelname,
+                severity=severity,
+                status=IncidentStatus.OPEN,
+                description=record.getMessage(),
+                source_component=record.name,
+                detected_at=self._time_service.now(),
+                # Correlation data
+                correlation_id=correlation_id,
+                task_id=task_id,
+                thought_id=thought_id,
+                handler_name=handler_name,
+                # Technical details
+                filename=record.filename,
+                line_number=record.lineno,
+                function_name=record.funcName,
+                # Exception data if present
+                exception_type=record.exc_info[0].__name__ if record.exc_info and record.exc_info[0] else None,
+                stack_trace="".join(traceback.format_exception(*record.exc_info)) if record.exc_info else None,
+                # Impact assessment (to be enhanced by analysis)
+                impact="TBD",
+                urgency=self._calculate_urgency(severity),
+                # Required base fields
+                updated_by="incident_capture_handler",
+                updated_at=self._time_service.now(),
+            )
+
+            # Store incident node directly in graph via memory bus
+            # The graph audit service has a memory_bus we can use
+            if hasattr(self._graph_audit_service, "_memory_bus") and self._graph_audit_service._memory_bus:
+                from ciris_engine.schemas.services.operations import MemoryOpStatus
+
+                result = await self._graph_audit_service._memory_bus.memorize(
+                    node=incident.to_graph_node(),
+                    handler_name="incident_capture_handler",
+                    metadata={"source": "logging", "captured_from": record.name, "auto_captured": True},
+                )
+                if result.status != MemoryOpStatus.OK:
+                    logging.getLogger(__name__).error(f"Failed to store incident in graph: {result.error}")
+            else:
+                logging.getLogger(__name__).error("Graph audit service does not have memory bus available")
+
+        except Exception as e:
+            # Log error but don't crash - incident capture should never break the system
+            logging.getLogger(__name__).error(f"Failed to save incident to graph: {e}")
+
+    def _map_log_level_to_severity(self, levelno: int) -> IncidentSeverity:
+        """Map Python log level to incident severity."""
+        if levelno >= logging.CRITICAL:
+            return IncidentSeverity.CRITICAL
+        elif levelno >= logging.ERROR:
+            return IncidentSeverity.HIGH
+        elif levelno >= logging.WARNING:
+            return IncidentSeverity.MEDIUM
+        else:
+            return IncidentSeverity.LOW
+
+    def _calculate_urgency(self, severity: IncidentSeverity) -> str:
+        """Calculate urgency based on severity."""
+        urgency_map = {
+            IncidentSeverity.CRITICAL: "IMMEDIATE",
+            IncidentSeverity.HIGH: "HIGH",
+            IncidentSeverity.MEDIUM: "MEDIUM",
+            IncidentSeverity.LOW: "LOW",
+        }
+        return urgency_map.get(severity, "MEDIUM")
+
+    def set_graph_audit_service(self, graph_audit_service: Any) -> None:
+        """Set the graph audit service for storing incidents in the graph.
+
+        This is called after service initialization when the GraphAuditService
+        is available.
+        """
+        self._graph_audit_service = graph_audit_service
+        logging.getLogger(__name__).info("Graph audit service injected into incident capture handler")
+
+        # Process any pending incidents now that we have the service
+        if hasattr(self, "_pending_incidents") and self._pending_incidents:
+            # Try to process them if we're in an async context
+            try:
+                loop = asyncio.get_running_loop()
+                for record in self._pending_incidents:
+                    loop.create_task(self._save_incident_to_graph(record))
+                logging.getLogger(__name__).info(f"Processing {len(self._pending_incidents)} queued incidents")
+                self._pending_incidents.clear()
+            except RuntimeError:
+                # Still no event loop, keep them queued
+                pass
+
+
+def add_incident_capture_handler(
+    logger_instance: Optional[logging.Logger] = None,
+    log_dir: str = "logs",
+    filename_prefix: str = "incidents",
+    time_service: Optional[TimeServiceProtocol] = None,
+    graph_audit_service: Any = None,
+) -> IncidentCaptureHandler:
+    """
+    Add an incident capture handler to the specified logger or root logger.
+
+    Args:
+        logger_instance: The logger to add the handler to (None for root logger)
+        log_dir: Directory for incident log files
+        filename_prefix: Prefix for incident log filenames
+        time_service: Time service for timestamps
+        graph_audit_service: Audit service for storing incidents in graph
+
+    Returns:
+        The created IncidentCaptureHandler instance
+    """
+    if not time_service:
+        raise RuntimeError("CRITICAL: TimeService is required for add_incident_capture_handler")
+    handler = IncidentCaptureHandler(
+        log_dir=log_dir,
+        filename_prefix=filename_prefix,
+        time_service=time_service,
+        graph_audit_service=graph_audit_service,
+    )
+
+    target_logger = logger_instance or logging.getLogger()
+    target_logger.addHandler(handler)
+
+    # Log that we've initialized the incident capture
+    logger = logging.getLogger(__name__)
+    logger.info(f"Incident capture handler initialized: {handler.log_file}")
+
+    return handler
+
+
+def inject_graph_audit_service_to_handlers(
+    graph_audit_service: Any, logger_instance: Optional[logging.Logger] = None
+) -> int:
+    """
+    Inject the graph audit service into all existing IncidentCaptureHandler instances.
+
+    This should be called after the GraphAuditService has been initialized.
+
+    Args:
+        graph_audit_service: The initialized GraphAuditService instance
+        logger_instance: The logger to search for handlers (None for root logger)
+
+    Returns:
+        Number of handlers that were updated
+    """
+    inject_logger = logging.getLogger(__name__)
+    target_logger = logger_instance or logging.getLogger()
+    updated_count = 0
+
+    # Search all handlers in the logger hierarchy
+    loggers_to_check = [target_logger]
+
+    # Also check all existing loggers
+    for name in logging.Logger.manager.loggerDict:
+        logger_obj = logging.getLogger(name)
+        if logger_obj not in loggers_to_check:
+            loggers_to_check.append(logger_obj)
+
+    for logger_obj in loggers_to_check:
+        for handler in logger_obj.handlers:
+            if isinstance(handler, IncidentCaptureHandler):
+                handler.set_graph_audit_service(graph_audit_service)
+                updated_count += 1
+                inject_logger.info(f"Injected graph audit service into handler for logger: {logger_obj.name}")
+
+    if updated_count == 0:
+        inject_logger.warning("No IncidentCaptureHandler instances found to inject graph audit service")
+    else:
+        inject_logger.info(
+            f"Successfully injected graph audit service into {updated_count} incident capture handler(s)"
+        )
+
+    return updated_count

ciris_engine/logic/utils/initialization_manager.py

@@ -0,0 +1,74 @@
+"""
+Initialization manager compatibility module.
+
+This module provides backwards compatibility for code that imports from
+the old initialization_manager location. The functionality is now provided by
+the InitializationService.
+"""
+
+import logging
+from typing import Callable, Optional
+
+from ciris_engine.logic.services.lifecycle.initialization import InitializationService
+from ciris_engine.schemas.services.operations import InitializationPhase, InitializationStatus
+
+logger = logging.getLogger(__name__)
+
+
+# Re-export for compatibility
+class InitializationError(Exception):
+    """Error during initialization."""
+
+
+# Re-export enums
+__all__ = ["InitializationPhase", "InitializationStatus", "InitializationError", "get_initialization_manager"]
+
+# Global instance for compatibility
+_global_initialization_service: Optional[InitializationService] = None
+
+
+def get_initialization_manager() -> InitializationService:
+    """Get or create the global initialization service instance."""
+    global _global_initialization_service
+    if _global_initialization_service is None:
+        from ciris_engine.logic.services.lifecycle.time import TimeService
+
+        time_service = TimeService()
+        _global_initialization_service = InitializationService(time_service=time_service)
+    return _global_initialization_service
+
+
+def register_initialization_callback(callback: Callable[[], None]) -> None:
+    """Register an initialization callback."""
+    # Legacy method - no longer supported
+    logger.warning("register_initialization_callback is deprecated - use register_step instead")
+
+
+async def initialize_components() -> None:
+    """Initialize all registered components."""
+    service = get_initialization_manager()
+    await service.initialize()
+
+
+def is_initialized() -> bool:
+    """Check if the system has been initialized."""
+    service = get_initialization_manager()
+    return service._initialization_complete
+
+
+def reset_initialization() -> None:
+    """Reset initialization state (for testing)."""
+    service = get_initialization_manager()
+    service._initialization_complete = False
+    service._completed_steps = []
+    service._error = None
+
+
+# Export for compatibility
+__all__ = [
+    "get_initialization_manager",
+    "register_initialization_callback",
+    "initialize_components",
+    "is_initialized",
+    "reset_initialization",
+]

ciris_engine/logic/utils/jsondict_helpers.py

@@ -0,0 +1,290 @@
+"""
+Helper functions for type-safe JSONDict access.
+
+These helpers provide type narrowing for MyPy when working with JSONDict/JSONValue types.
+Use these instead of direct dict access when you need to narrow union types.
+"""
+
+from typing import Any, Dict, List, Optional, TypeVar, Union, cast, overload
+
+from ciris_engine.schemas.types import JSONDict, JSONValue
+
+T = TypeVar("T")
+
+
+@overload
+def get_str(data: JSONDict, key: str, default: str = "") -> str: ...
+
+
+@overload
+def get_str(data: dict[str, object], key: str, default: str = "") -> str: ...
+
+
+def get_str(data: JSONDict | dict[str, object], key: str, default: str = "") -> str:
+    """
+    Get a string value from JSONDict with type narrowing.
+
+    Args:
+        data: The JSONDict to access
+        key: The key to retrieve
+        default: Default value if key is missing or not a string
+
+    Returns:
+        String value, narrowed from JSONValue union type
+    """
+    value = data.get(key, default)
+    if isinstance(value, str):
+        return value
+    return default
+
+
+@overload
+def get_str_optional(data: JSONDict, key: str) -> Optional[str]: ...
+
+
+@overload
+def get_str_optional(data: dict[str, object], key: str) -> Optional[str]: ...
+
+
+def get_str_optional(data: JSONDict | dict[str, object], key: str) -> Optional[str]:
+    """
+    Get an optional string value from JSONDict.
+
+    Args:
+        data: The JSONDict to access
+        key: The key to retrieve
+
+    Returns:
+        String value or None if key is missing or not a string
+    """
+    value = data.get(key)
+    if isinstance(value, str):
+        return value
+    return None
+
+
+def get_int(data: JSONDict, key: str, default: int = 0) -> int:
+    """
+    Get an integer value from JSONDict with type narrowing.
+
+    Args:
+        data: The JSONDict to access
+        key: The key to retrieve
+        default: Default value if key is missing or not an int
+
+    Returns:
+        Integer value, narrowed from JSONValue union type
+    """
+    value = data.get(key, default)
+    if isinstance(value, int) and not isinstance(value, bool):  # bool is subclass of int
+        return value
+    return default
+
+
+def get_int_optional(data: JSONDict, key: str) -> Optional[int]:
+    """
+    Get an optional integer value from JSONDict.
+
+    Args:
+        data: The JSONDict to access
+        key: The key to retrieve
+
+    Returns:
+        Integer value or None if key is missing or not an int
+    """
+    value = data.get(key)
+    if isinstance(value, int) and not isinstance(value, bool):
+        return value
+    return None
+
+
+def get_float(data: JSONDict, key: str, default: float = 0.0) -> float:
+    """
+    Get a float value from JSONDict with type narrowing.
+
+    Args:
+        data: The JSONDict to access
+        key: The key to retrieve
+        default: Default value if key is missing or not a float
+
+    Returns:
+        Float value, narrowed from JSONValue union type
+    """
+    value = data.get(key, default)
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+    return default
+
+
+def get_float_optional(data: JSONDict, key: str) -> Optional[float]:
+    """
+    Get an optional float value from JSONDict.
+
+    Args:
+        data: The JSONDict to access
+        key: The key to retrieve
+
+    Returns:
+        Float value or None if key is missing or not a numeric type
+    """
+    value = data.get(key)
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+    return None
+
+
+def get_bool(data: JSONDict, key: str, default: bool = False) -> bool:
+    """
+    Get a boolean value from JSONDict with type narrowing.
+
+    Args:
+        data: The JSONDict to access
+        key: The key to retrieve
+        default: Default value if key is missing or not a bool
+
+    Returns:
+        Boolean value, narrowed from JSONValue union type
+    """
+    value = data.get(key, default)
+    if isinstance(value, bool):
+        return value
+    return default
+
+
+def get_bool_optional(data: JSONDict, key: str) -> Optional[bool]:
+    """
+    Get an optional boolean value from JSONDict.
+
+    Args:
+        data: The JSONDict to access
+        key: The key to retrieve
+
+    Returns:
+        Boolean value or None if key is missing or not a bool
+    """
+    value = data.get(key)
+    if isinstance(value, bool):
+        return value
+    return None
+
+
+def get_list(data: JSONDict, key: str, default: Optional[List[Any]] = None) -> List[Any]:
+    """
+    Get a list value from JSONDict with type narrowing.
+
+    Args:
+        data: The JSONDict to access
+        key: The key to retrieve
+        default: Default value if key is missing or not a list
+
+    Returns:
+        List value, narrowed from JSONValue union type
+    """
+    if default is None:
+        default = []
+    value = data.get(key, default)
+    if isinstance(value, list):
+        return value
+    return default
+
+
+def get_list_optional(data: JSONDict, key: str) -> Optional[List[Any]]:
+    """
+    Get an optional list value from JSONDict.
+
+    Args:
+        data: The JSONDict to access
+        key: The key to retrieve
+
+    Returns:
+        List value or None if key is missing or not a list
+    """
+    value = data.get(key)
+    if isinstance(value, list):
+        return value
+    return None
+
+
+def get_dict(data: JSONDict, key: str, default: Optional[JSONDict] = None) -> JSONDict:
+    """
+    Get a dict value from JSONDict with type narrowing.
+
+    Args:
+        data: The JSONDict to access
+        key: The key to retrieve
+        default: Default value if key is missing or not a dict
+
+    Returns:
+        Dict value, narrowed from JSONValue union type
+    """
+    if default is None:
+        default = {}
+    value = data.get(key, default)
+    if isinstance(value, dict):
+        return cast(JSONDict, value)
+    return default
+
+
+def get_dict_optional(data: JSONDict, key: str) -> Optional[JSONDict]:
+    """
+    Get an optional dict value from JSONDict.
+
+    Args:
+        data: The JSONDict to access
+        key: The key to retrieve
+
+    Returns:
+        Dict value or None if key is missing or not a dict
+    """
+    value = data.get(key)
+    if isinstance(value, dict):
+        return cast(JSONDict, value)
+    return None
+
+
+def safe_cast_dict(value: Any) -> JSONDict:
+    """
+    Safely cast a value to JSONDict.
+
+    Args:
+        value: Value to cast
+
+    Returns:
+        JSONDict or empty dict if value is not a dict
+    """
+    if isinstance(value, dict):
+        return cast(JSONDict, value)
+    return {}
+
+
+def safe_cast_list(value: Any) -> List[Any]:
+    """
+    Safely cast a value to list.
+
+    Args:
+        value: Value to cast
+
+    Returns:
+        List or empty list if value is not a list
+    """
+    if isinstance(value, list):
+        return value
+    return []
+
+
+__all__ = [
+    "get_str",
+    "get_str_optional",
+    "get_int",
+    "get_int_optional",
+    "get_float",
+    "get_float_optional",
+    "get_bool",
+    "get_bool_optional",
+    "get_list",
+    "get_list_optional",
+    "get_dict",
+    "get_dict_optional",
+    "safe_cast_dict",
+    "safe_cast_list",
+]