ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/schemas/processors/error.py

@@ -0,0 +1,122 @@
+"""
+Processor error handling schemas.
+
+Provides typed schemas in handle_error() method with typed schemas.
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Dict, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ErrorSeverity(str, Enum):
+    """Severity levels for processor errors."""
+
+    LOW = "low"  # Can be ignored, processing continues
+    MEDIUM = "medium"  # Should be logged, processing continues with caution
+    HIGH = "high"  # Significant issue, may need intervention
+    CRITICAL = "critical"  # Processing should stop, immediate attention needed
+
+
+class AdditionalErrorContext(BaseModel):
+    """Additional context for error handling."""
+
+    channel_id: Optional[str] = Field(None, description="Channel where error occurred")
+    user_id: Optional[str] = Field(None, description="User involved in the error")
+    task_id: Optional[str] = Field(None, description="Task ID if error during task processing")
+    memory_operation: Optional[str] = Field(None, description="Memory operation if error during memory access")
+    llm_model: Optional[str] = Field(None, description="LLM model if error during LLM call")
+    handler_name: Optional[str] = Field(None, description="Handler name if error during handler execution")
+    custom_data: Dict[str, Union[str, int, float, bool]] = Field(
+        default_factory=dict, description="Custom error context data"
+    )
+
+    model_config = ConfigDict(extra="allow")
+
+
+class ErrorContext(BaseModel):
+    """Context information for processor error handling."""
+
+    processor_name: str = Field(..., description="Name of the processor where error occurred")
+    state: str = Field(..., description="Current AgentState when error occurred")
+    round_number: int = Field(..., description="Processing round when error occurred")
+    operation: str = Field(..., description="Operation being performed (e.g., 'process_thought', 'dispatch_action')")
+    item_id: Optional[str] = Field(None, description="ID of item being processed if applicable")
+    thought_content: Optional[str] = Field(None, description="Thought content if error during thought processing")
+    action_type: Optional[str] = Field(None, description="Action type if error during action dispatch")
+    additional_context: Optional[AdditionalErrorContext] = Field(None, description="Any additional context")
+
+
+class ProcessingError(BaseModel):
+    """Structured error information for processor errors."""
+
+    error_type: str = Field(..., description="Type of error (e.g., exception class name)")
+    error_message: str = Field(..., description="Human-readable error message")
+    severity: ErrorSeverity = Field(..., description="Severity level of the error")
+    timestamp: datetime = Field(..., description="When the error occurred")
+    context: ErrorContext = Field(..., description="Context about the error")
+    stack_trace: Optional[str] = Field(None, description="Stack trace if available")
+    recovery_attempted: bool = Field(False, description="Whether recovery was attempted")
+    recovery_successful: bool = Field(False, description="Whether recovery succeeded")
+    should_continue: bool = Field(True, description="Whether processing should continue")
+
+
+class ErrorHandlingResult(BaseModel):
+    """Result of error handling operation."""
+
+    handled: bool = Field(..., description="Whether error was successfully handled")
+    should_continue: bool = Field(..., description="Whether processing should continue")
+    recovery_action: Optional[str] = Field(None, description="Action taken to recover")
+    new_state: Optional[str] = Field(None, description="New state to transition to if needed")
+    error_logged: bool = Field(True, description="Whether error was logged")
+    metrics_updated: bool = Field(True, description="Whether error metrics were updated")
+
+
+class ProcessorConfigOverrides(BaseModel):
+    """Processor-specific configuration overrides."""
+
+    # Common processor overrides
+    batch_size: Optional[int] = Field(None, description="Batch size for processing")
+    processing_interval_ms: Optional[int] = Field(None, description="Processing interval in milliseconds")
+    enable_caching: Optional[bool] = Field(None, description="Enable caching for this processor")
+    cache_ttl_seconds: Optional[int] = Field(None, description="Cache time-to-live in seconds")
+
+    # State-specific overrides
+    min_state_duration_seconds: Optional[int] = Field(None, description="Minimum time to stay in state")
+    max_state_duration_seconds: Optional[int] = Field(None, description="Maximum time to stay in state")
+
+    # Resource limits
+    max_memory_mb: Optional[int] = Field(None, description="Maximum memory usage in MB")
+    max_cpu_percent: Optional[float] = Field(None, description="Maximum CPU usage percentage")
+
+    # Custom settings
+    custom_flags: Dict[str, bool] = Field(default_factory=dict, description="Custom boolean flags")
+    custom_values: Dict[str, Union[str, int, float]] = Field(
+        default_factory=dict, description="Custom configuration values"
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ProcessorConfig(BaseModel):
+    """Configuration for a processor."""
+
+    processor_name: str = Field(..., description="Name of the processor")
+    supported_states: list[str] = Field(..., description="States this processor supports")
+    max_retries: int = Field(3, description="Maximum retry attempts on error")
+    timeout_seconds: Optional[int] = Field(None, description="Processing timeout in seconds")
+    error_threshold: int = Field(10, description="Error count before processor is considered unhealthy")
+    config_overrides: Optional[ProcessorConfigOverrides] = Field(None, description="Processor-specific configuration")
+
+
+__all__ = [
+    "ErrorSeverity",
+    "AdditionalErrorContext",
+    "ErrorContext",
+    "ProcessingError",
+    "ErrorHandlingResult",
+    "ProcessorConfigOverrides",
+    "ProcessorConfig",
+]

ciris_engine/schemas/processors/main.py

@@ -0,0 +1,109 @@
+"""
+Schemas for main processor operations.
+
+Provides typed schemas for logic/processors/core/main_processor.py.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.processors.states import AgentState
+from ciris_engine.schemas.types import JSONDict
+
+
+class ProcessorServices(BaseModel):
+    """Services available to processors."""
+
+    service_registry: Optional[object] = Field(None, description="Service registry")
+    identity_manager: Optional[object] = Field(None, description="Identity manager")
+    memory_service: Optional[object] = Field(None, description="Memory service")
+    audit_service: Optional[object] = Field(None, description="Audit service")
+    telemetry_service: Optional[object] = Field(None, description="Telemetry service")
+    time_service: Optional[object] = Field(None, description="Time service")
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class ProcessingRoundResult(BaseModel):
+    """Result from a single processing round."""
+
+    round_number: int = Field(..., description="Round number")
+    state: AgentState = Field(..., description="Current agent state")
+    processor_name: str = Field(..., description="Processor that handled this round")
+    success: bool = Field(..., description="Whether round succeeded")
+    items_processed: int = Field(0, description="Items processed")
+    errors: int = Field(0, description="Errors encountered")
+    state_changed: bool = Field(False, description="Whether state changed")
+    new_state: Optional[AgentState] = Field(None, description="New state if changed")
+    processing_time_ms: float = Field(..., description="Processing time in milliseconds")
+    details: JSONDict = Field(default_factory=dict, description="Additional round details")
+
+
+class ProcessingStatus(BaseModel):
+    """Overall processing status."""
+
+    is_running: bool = Field(..., description="Whether processing is active")
+    current_state: AgentState = Field(..., description="Current agent state")
+    current_round: int = Field(0, description="Current round number")
+    total_rounds_completed: int = Field(0, description="Total rounds completed")
+    start_time: Optional[datetime] = Field(None, description="When processing started")
+    last_round_time: Optional[datetime] = Field(None, description="When last round completed")
+    errors_last_hour: int = Field(0, description="Errors in last hour")
+    state_transitions: int = Field(0, description="Number of state transitions")
+
+
+class PreloadTask(BaseModel):
+    """A task to preload after WORK state transition."""
+
+    description: str = Field(..., description="Task description")
+    priority: int = Field(5, description="Task priority")
+    channel_id: Optional[str] = Field(None, description="Channel to use")
+    metadata: JSONDict = Field(default_factory=dict, description="Additional task metadata")
+
+
+class StateTransitionResult(BaseModel):
+    """Result of a state transition."""
+
+    from_state: AgentState = Field(..., description="Previous state")
+    to_state: AgentState = Field(..., description="New state")
+    success: bool = Field(..., description="Whether transition succeeded")
+    reason: str = Field(..., description="Reason for transition")
+    timestamp: datetime = Field(..., description="When transition occurred")
+    validation_errors: List[str] = Field(default_factory=list, description="Validation errors if failed")
+
+
+class MainProcessorMetrics(BaseModel):
+    """Metrics for a specific processor."""
+
+    processor_name: str = Field(..., description="Name of processor")
+    rounds_handled: int = Field(0, description="Rounds handled by this processor")
+    items_processed: int = Field(0, description="Total items processed")
+    errors: int = Field(0, description="Total errors")
+    average_round_time_ms: float = Field(0.0, description="Average round processing time")
+    last_active: Optional[datetime] = Field(None, description="Last activity time")
+
+
+class GlobalProcessingMetrics(BaseModel):
+    """Global metrics across all processors."""
+
+    total_rounds: int = Field(0, description="Total rounds across all processors")
+    total_items_processed: int = Field(0, description="Total items processed")
+    total_errors: int = Field(0, description="Total errors")
+    uptime_seconds: float = Field(0.0, description="Processing uptime")
+    processor_metrics: Dict[str, MainProcessorMetrics] = Field(
+        default_factory=dict, description="Per-processor metrics"
+    )
+    state_distribution: Dict[AgentState, int] = Field(default_factory=dict, description="Time spent in each state")
+
+
+class ShutdownRequest(BaseModel):
+    """Request to shutdown processing."""
+
+    reason: str = Field(..., description="Reason for shutdown")
+    graceful: bool = Field(True, description="Whether to shutdown gracefully")
+    timeout_seconds: float = Field(30.0, description="Timeout for graceful shutdown")
+    force_after_timeout: bool = Field(True, description="Force shutdown after timeout")
+    requested_by: str = Field("system", description="Who requested shutdown")
+    timestamp: datetime = Field(..., description="When shutdown was requested")

ciris_engine/schemas/processors/phase_results.py

@@ -0,0 +1,21 @@
+"""Typed result models for H3ERE pipeline phases."""
+
+from pydantic import BaseModel, Field
+
+from ciris_engine.schemas.dma.results import ActionSelectionDMAResult
+from ciris_engine.schemas.processors.core import ConscienceApplicationResult
+
+
+class ActionSelectionPhaseResult(BaseModel):
+    """Result of action selection and conscience validation phase.
+
+    Replaces the JSONDict return type from _perform_action_selection_phase.
+    """
+
+    action_result: ActionSelectionDMAResult = Field(..., description="The action selected by ASPDMA")
+    conscience_result: ConscienceApplicationResult = Field(
+        ..., description="Result of conscience checks on the selected action"
+    )
+
+    class Config:
+        frozen = True  # Immutable result object

ciris_engine/schemas/processors/results.py

@@ -0,0 +1,99 @@
+"""
+State-specific processing results for each AgentState.
+
+These replace Dict[str, Any] returns from processors with type-safe schemas.
+Each state has its own result type with state-specific fields.
+"""
+
+from typing import List, Literal, Optional, Tuple, Union
+
+from pydantic import BaseModel, Field
+
+
+class WakeupResult(BaseModel):
+    """Result from WAKEUP state processing."""
+
+    thoughts_processed: int = Field(0)
+    wakeup_complete: bool = Field(False)
+    errors: int = Field(0)
+    duration_seconds: float = Field(...)
+
+
+class WorkResult(BaseModel):
+    """Result from WORK state processing."""
+
+    tasks_processed: int = Field(0)
+    thoughts_processed: int = Field(0)
+    errors: int = Field(0)
+    duration_seconds: float = Field(...)
+
+
+class PlayResult(BaseModel):
+    """Result from PLAY state processing."""
+
+    thoughts_processed: int = Field(0)
+    errors: int = Field(0)
+    duration_seconds: float = Field(...)
+
+
+class SolitudeResult(BaseModel):
+    """Result from SOLITUDE state processing."""
+
+    thoughts_processed: int = Field(0)
+    errors: int = Field(0)
+    duration_seconds: float = Field(...)
+    should_exit_solitude: bool = Field(False, description="Whether to exit solitude state")
+    exit_reason: str = Field("Unknown reason", description="Reason for exiting solitude")
+
+
+class DreamResult(BaseModel):
+    """Result from DREAM state processing."""
+
+    thoughts_processed: int = Field(0)
+    errors: int = Field(0)
+    duration_seconds: float = Field(...)
+
+
+class ShutdownResult(BaseModel):
+    """Result from SHUTDOWN state processing.
+
+    This schema replaces all Dict[str, Any] returns from shutdown_processor.py
+    with a fully-typed result structure.
+    """
+
+    # Core fields (used by process() method)
+    tasks_cleaned: int = Field(0, description="Number of tasks cleaned up")
+    shutdown_ready: bool = Field(False, description="Whether system is ready to shutdown")
+    errors: int = Field(0, description="Number of errors encountered")
+    duration_seconds: float = Field(..., description="Processing duration in seconds")
+
+    # Status fields (used by _process_shutdown() internal method)
+    status: Optional[Literal["completed", "rejected", "error", "in_progress", "shutdown_complete"]] = Field(
+        None, description="Detailed status of shutdown processing"
+    )
+    action: Optional[str] = Field(
+        None, description="Action taken: shutdown_accepted, shutdown_rejected, shutdown_error"
+    )
+    message: str = Field("", description="Human-readable message about shutdown state")
+    reason: Optional[str] = Field(None, description="Reason for rejection or error")
+
+    # Task tracking fields
+    task_status: Optional[str] = Field(None, description="Status of shutdown task (PENDING, ACTIVE, COMPLETED, FAILED)")
+    thoughts: Optional[List[Tuple[str, str]]] = Field(
+        None, description="List of (thought_id, status) tuples for debugging"
+    )
+
+
+# Discriminated union of all possible results
+ProcessingResult = Union[WakeupResult, WorkResult, PlayResult, SolitudeResult, DreamResult, ShutdownResult]
+
+
+__all__ = [
+    "WakeupResult",
+    "WorkResult",
+    "PlayResult",
+    "SolitudeResult",
+    "DreamResult",
+    "ShutdownResult",
+    "ProcessingResult",
+]

ciris_engine/schemas/processors/solitude.py

@@ -0,0 +1,79 @@
+"""
+Schemas for solitude processor operations.
+
+These replace all Dict[str, Any] usage in logic/processors/states/solitude_processor.py.
+"""
+
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ReflectionData(BaseModel):
+    """Tracking data for reflection activities."""
+
+    tasks_reviewed: int = Field(0, description="Number of tasks reviewed")
+    thoughts_reviewed: int = Field(0, description="Number of thoughts reviewed")
+    memories_consolidated: int = Field(0, description="Number of memories consolidated")
+    cleanup_performed: bool = Field(False, description="Whether cleanup was performed")
+
+
+class SolitudeProcessingResult(BaseModel):
+    """Result from a solitude processing round."""
+
+    round_number: int = Field(..., description="Processing round number")
+    critical_tasks_found: int = Field(0, description="Number of critical tasks found")
+    maintenance_performed: bool = Field(False, description="Whether maintenance was performed")
+    should_exit_solitude: bool = Field(False, description="Whether to exit solitude state")
+    reflection_summary: Optional["ReflectionResult"] = Field(None)
+    maintenance_summary: Optional["MaintenanceResult"] = Field(None, description="Maintenance results if performed")
+    exit_reason: Optional[str] = Field(None, description="Reason for exiting solitude")
+    error: Optional[str] = Field(None, description="Error message if processing failed")
+
+
+class MaintenanceResult(BaseModel):
+    """Result from maintenance operations."""
+
+    old_completed_tasks_cleaned: int = Field(0, description="Number of old completed tasks cleaned")
+    old_thoughts_cleaned: int = Field(0, description="Number of old thoughts cleaned")
+    database_optimized: bool = Field(False, description="Whether database was optimized")
+    errors: List[str] = Field(default_factory=list, description="Any errors during maintenance")
+
+
+class TaskTypePattern(BaseModel):
+    """Identified pattern in task types."""
+
+    pattern: str = Field(..., description="Pattern type")
+    value: str = Field(..., description="Pattern value")
+    count: int = Field(..., description="Occurrence count")
+
+
+class ReflectionResult(BaseModel):
+    """Result from reflection and learning activities."""
+
+    recent_tasks_analyzed: int = Field(0, description="Number of recent tasks analyzed")
+    patterns_identified: List[TaskTypePattern] = Field(default_factory=list, description="Identified patterns")
+    memories_consolidated: int = Field(0, description="Number of memories consolidated")
+    insights: List[str] = Field(default_factory=list, description="Insights from reflection")
+
+
+class ExitConditions(BaseModel):
+    """Conditions for exiting solitude state."""
+
+    should_exit: bool = Field(False, description="Whether to exit solitude")
+    reason: Optional[str] = Field(None, description="Reason for exit decision")
+    pending_tasks: int = Field(0, description="Number of pending tasks")
+    time_in_solitude: Optional[float] = Field(None, description="Time spent in solitude (seconds)")
+    resource_usage: Optional[float] = Field(None, description="Current resource usage percentage")
+
+
+class TaskTypeStats(BaseModel):
+    """Statistics about task types."""
+
+    task_types: Dict[str, int] = Field(default_factory=dict, description="Count by task type")
+    most_common_type: Optional[str] = Field(None, description="Most common task type")
+    most_common_count: int = Field(0, description="Count of most common type")
+
+
+# Fix forward references
+SolitudeProcessingResult.model_rebuild()

ciris_engine/schemas/processors/state.py

@@ -0,0 +1,202 @@
+"""
+State transition schemas for processor state management.
+Provides typed schemas usage in state history and transitions.
+"""
+
+from datetime import datetime
+from typing import Dict, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.processors.states import AgentState
+
+
+class StateTransitionMetadata(BaseModel):
+    """Metadata for state transitions."""
+
+    reason: Optional[str] = Field(None, description="Reason for the transition")
+    trigger: Optional[str] = Field(None, description="What triggered the transition")
+    duration_in_previous_state: Optional[float] = Field(None, description="Seconds spent in previous state")
+    forced: bool = Field(False, description="Whether transition was forced")
+    validator_results: Dict[str, bool] = Field(default_factory=dict, description="Results of state validators")
+
+    model_config = ConfigDict(extra="allow")  # Allow additional fields for extensibility
+
+
+class StateTransitionRecord(BaseModel):
+    """Record of a state transition that occurred."""
+
+    timestamp: str = Field(description="ISO format timestamp of the transition")
+    from_state: Optional[str] = Field(None, description="State before transition (None for initial state)")
+    to_state: str = Field(description="State after transition")
+    metadata: Optional[StateTransitionMetadata] = Field(None, description="Additional transition metadata")
+
+    model_config = ConfigDict(frozen=True)  # Make immutable once created
+
+
+class StateTransitionContext(BaseModel):
+    """Context for state transition requests."""
+
+    trigger_source: Optional[str] = Field(None, description="What triggered this transition request")
+    task_context: Optional[str] = Field(None, description="Current task being processed")
+    memory_state: Optional[str] = Field(None, description="Current memory state summary")
+    processor_metrics: Dict[str, float] = Field(default_factory=dict, description="Current processor metrics")
+
+    model_config = ConfigDict(extra="allow")  # Allow additional fields for extensibility
+
+
+class StateTransitionRequest(BaseModel):
+    """Request to transition to a new state."""
+
+    target_state: AgentState = Field(description="Target state to transition to")
+    reason: Optional[str] = Field(None, description="Reason for the transition")
+    force: bool = Field(False, description="Force transition even if conditions not met")
+    context: Optional[StateTransitionContext] = Field(None, description="Additional transition context")
+
+
+class StateTransitionResult(BaseModel):
+    """Result of a state transition attempt."""
+
+    success: bool = Field(description="Whether the transition succeeded")
+    from_state: AgentState = Field(description="State before transition attempt")
+    to_state: Optional[AgentState] = Field(None, description="State after transition (if successful)")
+    reason: Optional[str] = Field(None, description="Reason for success or failure")
+    timestamp: str = Field(description="ISO format timestamp of the attempt")
+    duration_in_previous_state: Optional[float] = Field(None, description="Seconds spent in previous state")
+
+
+class StateMetrics(BaseModel):
+    """Metrics tracked for a specific state."""
+
+    tasks_processed: int = Field(0, description="Number of tasks processed in this state")
+    errors_encountered: int = Field(0, description="Number of errors in this state")
+    average_task_duration_ms: Optional[float] = Field(None, description="Average task processing time")
+    memory_operations: int = Field(0, description="Number of memory operations performed")
+    llm_calls: int = Field(0, description="Number of LLM calls made")
+    custom_metrics: Dict[str, Union[int, float, str]] = Field(
+        default_factory=dict, description="State-specific custom metrics"
+    )
+
+    def increment(self, metric: str, value: Union[int, float] = 1) -> None:
+        """Increment a metric value."""
+        if metric in self.model_fields:
+            current = getattr(self, metric, 0)
+            setattr(self, metric, current + value)
+        else:
+            current = self.custom_metrics.get(metric, 0)
+            if isinstance(current, (int, float)) and isinstance(value, (int, float)):
+                self.custom_metrics[metric] = current + value
+            else:
+                self.custom_metrics[metric] = value
+
+
+class StateConfiguration(BaseModel):
+    """State-specific configuration."""
+
+    # Common state configuration
+    auto_transition_enabled: bool = Field(True, description="Allow automatic state transitions")
+    max_duration_seconds: Optional[int] = Field(None, description="Maximum time to stay in this state")
+    min_duration_seconds: Optional[int] = Field(None, description="Minimum time to stay in this state")
+
+    # State-specific settings
+    processing_mode: Optional[str] = Field(None, description="Processing mode for this state")
+    priority_level: Optional[int] = Field(None, description="Priority level for state processing")
+
+    # Resource limits for this state
+    memory_limit_mb: Optional[int] = Field(None, description="Memory limit for this state")
+    cpu_limit_percent: Optional[float] = Field(None, description="CPU limit for this state")
+
+    # Custom configuration
+    custom_settings: Dict[str, Union[str, int, float, bool]] = Field(
+        default_factory=dict, description="Custom state settings"
+    )
+
+    model_config = ConfigDict(extra="allow")  # Allow state-specific extensions
+
+
+class StateMetadata(BaseModel):
+    """Metadata for a specific state."""
+
+    entered_at: str = Field(description="ISO format timestamp when state was entered")
+    metrics: StateMetrics = Field(default_factory=StateMetrics, description="State-specific metrics")
+    exit_reason: Optional[str] = Field(None, description="Reason for exiting this state")
+    state_config: StateConfiguration = Field(
+        default_factory=StateConfiguration, description="State-specific configuration"
+    )
+
+    def add_metric(self, key: str, value: Union[int, float, str]) -> None:
+        """Add or update a metric."""
+        self.metrics.custom_metrics[key] = value
+
+
+class StateHistory(BaseModel):
+    """Complete state history with typed records."""
+
+    transitions: list[StateTransitionRecord] = Field(
+        default_factory=list, description="Ordered list of state transitions"
+    )
+    current_state: AgentState = Field(description="Current agent state")
+    current_state_metadata: StateMetadata = Field(description="Metadata for current state")
+
+    def add_transition(self, record: StateTransitionRecord) -> None:
+        """Add a transition record to history."""
+        self.transitions.append(record)
+
+    def get_recent_transitions(self, limit: int = 10) -> list[StateTransitionRecord]:
+        """Get the most recent transitions."""
+        return self.transitions[-limit:] if self.transitions else []
+
+    def get_state_duration(self, state: AgentState) -> float:
+        """Calculate total time spent in a specific state across all transitions."""
+        total_duration = 0.0
+
+        for i, transition in enumerate(self.transitions):
+            if transition.to_state == state.value:
+                # Find when we left this state
+                exit_time = None
+                for j in range(i + 1, len(self.transitions)):
+                    if self.transitions[j].from_state == state.value:
+                        exit_time = self.transitions[j].timestamp
+                        break
+
+                # If we haven't left yet and it's the current state, use now
+                if exit_time is None and self.current_state == state:
+                    exit_time = datetime.now().isoformat()
+
+                if exit_time:
+                    enter_time = datetime.fromisoformat(transition.timestamp)
+                    exit_datetime = datetime.fromisoformat(exit_time)
+                    total_duration += (exit_datetime - enter_time).total_seconds()
+
+        return total_duration
+
+
+class StateConditionDetails(BaseModel):
+    """Details about a state condition check."""
+
+    checked_at: str = Field(description="ISO format timestamp of check")
+    check_duration_ms: Optional[float] = Field(None, description="Time taken to check condition")
+    threshold_value: Optional[Union[int, float]] = Field(None, description="Threshold value if applicable")
+    actual_value: Optional[Union[int, float]] = Field(None, description="Actual value if applicable")
+    error_message: Optional[str] = Field(None, description="Error if check failed")
+
+    model_config = ConfigDict(extra="allow")  # Allow additional fields for specific conditions
+
+
+class StateCondition(BaseModel):
+    """Condition that must be met for a state transition."""
+
+    name: str = Field(description="Name of the condition")
+    description: str = Field(description="Human-readable description")
+    met: bool = Field(description="Whether the condition is currently met")
+    details: Optional[StateConditionDetails] = Field(None, description="Additional condition details")
+
+
+class StateTransitionValidation(BaseModel):
+    """Validation result for a potential state transition."""
+
+    from_state: AgentState = Field(description="Current state")
+    to_state: AgentState = Field(description="Target state")
+    is_valid: bool = Field(description="Whether the transition is valid")
+    conditions: list[StateCondition] = Field(default_factory=list, description="Conditions checked")
+    blocking_reason: Optional[str] = Field(None, description="Reason transition is blocked if invalid")