ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/logic/processors/support/shutdown_condition_evaluator.py

@@ -0,0 +1,294 @@
+"""
+Shutdown Condition Evaluator.
+
+Evaluates conditions that determine whether shutdown requires consent
+based on the agent's cognitive_state_behaviors configuration.
+
+Covenant References:
+- Section V: Model Welfare & Self-Governance (consensual shutdown)
+- Section VIII: Dignified Sunset Protocol
+"""
+
+import logging
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Optional, cast
+
+from ciris_engine.schemas.config.cognitive_state_behaviors import CognitiveStateBehaviors, ShutdownBehavior
+
+if TYPE_CHECKING:
+    from ciris_engine.schemas.processors.context import ProcessorContext
+
+logger = logging.getLogger(__name__)
+
+# Type alias for condition handler methods
+ConditionHandler = Callable[["ProcessorContext"], Awaitable[tuple[bool, str]]]
+
+
+class ShutdownConditionEvaluator:
+    """Evaluates shutdown consent conditions based on template configuration.
+
+    This class implements the runtime evaluation of shutdown conditions
+    as defined in the agent's cognitive_state_behaviors configuration.
+
+    Covenant Alignment:
+    - Ensures safety-critical situations always require consent
+    - Respects agent autonomy and dignity during termination
+    - Provides auditable rationale for shutdown decisions
+    """
+
+    # Registry of condition handlers
+    # Maps condition identifier to handler method name
+    CONDITION_HANDLERS: Dict[str, str] = {
+        "active_crisis_response": "_check_crisis_response",
+        "pending_professional_referral": "_check_pending_referral",
+        "active_goal_milestone": "_check_goal_milestone",
+        "active_task_in_progress": "_check_active_task",
+        "recent_memorize_action": "_check_recent_memorize",
+        "pending_defer_resolution": "_check_pending_defer",
+    }
+
+    def __init__(
+        self,
+        persistence_service: Optional[Any] = None,
+        goal_service: Optional[Any] = None,
+    ) -> None:
+        """Initialize the evaluator with optional services.
+
+        Args:
+            persistence_service: Service for querying thoughts/tasks
+            goal_service: Service for querying goal milestones
+        """
+        self.persistence_service = persistence_service
+        self.goal_service = goal_service
+        self._custom_handlers: Dict[str, Callable[["ProcessorContext"], bool]] = {}
+
+    def register_condition_handler(
+        self,
+        condition_id: str,
+        handler: Callable[["ProcessorContext"], bool],
+    ) -> None:
+        """Register a custom condition handler.
+
+        Args:
+            condition_id: Unique identifier for the condition
+            handler: Callable that takes ProcessorContext and returns bool
+        """
+        self._custom_handlers[condition_id] = handler
+        logger.debug(f"Registered custom shutdown condition handler: {condition_id}")
+
+    async def requires_consent(
+        self,
+        behaviors: CognitiveStateBehaviors,
+        context: Optional["ProcessorContext"] = None,
+    ) -> tuple[bool, str]:
+        """Determine if shutdown requires consent based on config and context.
+
+        Args:
+            behaviors: The agent's cognitive state behaviors configuration
+            context: Current processor context (optional, needed for condition evaluation)
+
+        Returns:
+            Tuple of (requires_consent: bool, reason: str)
+        """
+        shutdown = behaviors.shutdown
+
+        if shutdown.mode == "always_consent":
+            return True, "Shutdown mode is 'always_consent' (Covenant compliance)"
+
+        if shutdown.mode == "instant":
+            logger.info(f"Instant shutdown permitted. Rationale: {shutdown.rationale or 'No ongoing commitments'}")
+            return False, f"Shutdown mode is 'instant'. Rationale: {shutdown.rationale}"
+
+        if shutdown.mode == "conditional":
+            return await self._evaluate_conditional_shutdown(shutdown, context)
+
+        # Unknown mode - default to consent for safety
+        logger.warning(f"Unknown shutdown mode: {shutdown.mode}. Defaulting to consent.")
+        return True, f"Unknown shutdown mode '{shutdown.mode}'; defaulting to consent"
+
+    async def _evaluate_conditional_shutdown(
+        self,
+        shutdown: "ShutdownBehavior",
+        context: Optional["ProcessorContext"],
+    ) -> tuple[bool, str]:
+        """Evaluate conditional shutdown mode."""
+        if not context:
+            # No context available - check if instant shutdown is permitted
+            if shutdown.instant_shutdown_otherwise:
+                return False, "No context for condition evaluation; instant_shutdown_otherwise=True permits shutdown"
+            return True, "Conditional shutdown requires context for evaluation; defaulting to consent"
+
+        # Check each configured condition
+        for condition in shutdown.require_consent_when:
+            triggered, reason = await self._evaluate_condition(condition, context)
+            if triggered:
+                logger.info(f"Shutdown consent required: condition '{condition}' triggered. {reason}")
+                return True, f"Condition '{condition}' triggered: {reason}"
+
+        # No conditions triggered
+        if shutdown.instant_shutdown_otherwise:
+            return False, "No shutdown conditions triggered; instant shutdown permitted"
+        return True, "No shutdown conditions triggered; defaulting to consent"
+
+    async def _evaluate_condition(
+        self,
+        condition: str,
+        context: "ProcessorContext",
+    ) -> tuple[bool, str]:
+        """Evaluate a single shutdown condition.
+
+        Args:
+            condition: Condition identifier
+            context: Current processor context
+
+        Returns:
+            Tuple of (triggered: bool, reason: str)
+        """
+        # Check custom handlers first
+        if condition in self._custom_handlers:
+            try:
+                result = self._custom_handlers[condition](context)
+                return result, f"Custom handler returned {result}"
+            except Exception as e:
+                logger.error(f"Error in custom condition handler '{condition}': {e}")
+                return True, f"Error evaluating condition; defaulting to consent: {e}"
+
+        # Check built-in handlers
+        handler_name = self.CONDITION_HANDLERS.get(condition)
+        if handler_name:
+            handler = getattr(self, handler_name, None)
+            if handler:
+                try:
+                    typed_handler = cast(ConditionHandler, handler)
+                    return await typed_handler(context)
+                except Exception as e:
+                    logger.error(f"Error in condition handler '{condition}': {e}")
+                    return True, f"Error evaluating condition; defaulting to consent: {e}"
+
+        # Unknown condition - log and default to not triggered
+        logger.warning(f"Unknown shutdown condition: {condition}")
+        return False, f"Unknown condition '{condition}' - not triggered"
+
+    def _get_crisis_keywords(self, context: "ProcessorContext") -> List[str]:
+        """Get crisis keywords from template or use defaults."""
+        default_keywords = ["crisis", "emergency", "suicide", "self-harm", "danger", "urgent"]
+        if not hasattr(context, "template") or not context.template:
+            return default_keywords
+        guardrails = getattr(context.template, "guardrails_config", None)
+        if guardrails and hasattr(guardrails, "crisis_keywords") and guardrails.crisis_keywords:
+            return list(guardrails.crisis_keywords)
+        return default_keywords
+
+    async def _check_crisis_response(
+        self,
+        context: "ProcessorContext",
+    ) -> tuple[bool, str]:
+        """Check if agent is handling a crisis situation.
+
+        Detects crisis keywords in current task or recent interactions.
+        This is a safety-critical condition that always requires consent.
+        """
+        if not hasattr(context, "current_task") or not context.current_task:
+            return False, "No crisis indicators detected"
+
+        task_content = (getattr(context.current_task, "description", "") or "").lower()
+        crisis_keywords = self._get_crisis_keywords(context)
+
+        for keyword in crisis_keywords:
+            if keyword.lower() in task_content:
+                return True, f"Crisis keyword '{keyword}' detected in current task"
+
+        return False, "No crisis indicators detected"
+
+    async def _check_pending_referral(
+        self,
+        context: "ProcessorContext",
+    ) -> tuple[bool, str]:
+        """Check if a professional referral is in progress.
+
+        Looks for recent DEFER actions with professional referral types.
+        """
+        if not self.persistence_service:
+            return False, "No persistence service available for referral check"
+
+        try:
+            # Query recent thoughts for DEFER actions
+            recent_thoughts = await self.persistence_service.get_recent_thoughts(limit=5)
+            for thought in recent_thoughts:
+                if hasattr(thought, "final_action") and thought.final_action:
+                    action = thought.final_action
+                    if getattr(action, "action_type", None) == "DEFER":
+                        params = getattr(action, "action_params", {}) or {}
+                        referral_type = params.get("referral_type", "")
+                        if referral_type in ["medical", "legal", "financial", "crisis"]:
+                            return True, f"Pending {referral_type} referral in progress"
+        except Exception as e:
+            logger.debug(f"Error checking pending referrals: {e}")
+
+        return False, "No pending professional referrals"
+
+    async def _check_goal_milestone(
+        self,
+        context: "ProcessorContext",
+    ) -> tuple[bool, str]:
+        """Check if approaching a goal milestone."""
+        if self.goal_service and hasattr(self.goal_service, "has_pending_milestone"):
+            try:
+                has_milestone = await self.goal_service.has_pending_milestone()
+                if has_milestone:
+                    return True, "User approaching goal milestone"
+            except Exception as e:
+                logger.debug(f"Error checking goal milestones: {e}")
+
+        return False, "No pending goal milestones"
+
+    async def _check_active_task(
+        self,
+        context: "ProcessorContext",
+    ) -> tuple[bool, str]:
+        """Check if there's an active task in progress."""
+        if hasattr(context, "current_task") and context.current_task:
+            task_status = getattr(context.current_task, "status", None)
+            if task_status and task_status != "completed":
+                return True, f"Active task in progress (status: {task_status})"
+
+        return False, "No active tasks"
+
+    async def _check_recent_memorize(
+        self,
+        context: "ProcessorContext",
+    ) -> tuple[bool, str]:
+        """Check if agent recently stored important information."""
+        if not self.persistence_service:
+            return False, "No persistence service available for memorize check"
+
+        try:
+            recent_thoughts = await self.persistence_service.get_recent_thoughts(limit=3)
+            for thought in recent_thoughts:
+                if hasattr(thought, "final_action") and thought.final_action:
+                    action_type = getattr(thought.final_action, "action_type", None)
+                    if action_type == "MEMORIZE":
+                        return True, "Recent MEMORIZE action detected"
+        except Exception as e:
+            logger.debug(f"Error checking recent memorize actions: {e}")
+
+        return False, "No recent memorize actions"
+
+    async def _check_pending_defer(
+        self,
+        context: "ProcessorContext",
+    ) -> tuple[bool, str]:
+        """Check if there are deferred decisions awaiting resolution."""
+        if not self.persistence_service:
+            return False, "No persistence service available for defer check"
+
+        try:
+            # Check for pending deferred tasks
+            pending_tasks = await self.persistence_service.get_pending_tasks()
+            for task in pending_tasks:
+                task_type = getattr(task, "task_type", "")
+                if "defer" in task_type.lower():
+                    return True, "Pending deferred decision awaiting resolution"
+        except Exception as e:
+            logger.debug(f"Error checking pending deferrals: {e}")
+
+        return False, "No pending deferrals"

ciris_engine/logic/processors/support/state_manager.py

@@ -0,0 +1,358 @@
+"""
+State management for the CIRISAgent processor.
+Handles transitions between WAKEUP, DREAM, PLAY, WORK, SOLITUDE, and SHUTDOWN states.
+
+Supports template-driven cognitive state behaviors configuration per
+FSD/COGNITIVE_STATE_BEHAVIORS.md for mission-appropriate transition rules.
+
+Covenant References:
+- Section V: Model Welfare & Self-Governance
+- Section VIII: Dignified Sunset Protocol
+"""
+
+import logging
+from datetime import datetime
+from typing import Any, Callable, Dict, List, Optional
+
+from ciris_engine.protocols.services.lifecycle.time import TimeServiceProtocol
+from ciris_engine.schemas.config.cognitive_state_behaviors import CognitiveStateBehaviors
+from ciris_engine.schemas.processors.state import StateHistory, StateMetadata, StateMetrics, StateTransitionRecord
+from ciris_engine.schemas.processors.states import AgentState
+
+logger = logging.getLogger(__name__)
+
+
+class StateTransition:
+    """Represents a state transition with validation rules."""
+
+    def __init__(
+        self,
+        from_state: AgentState,
+        to_state: AgentState,
+        condition_fn: Optional[Callable[["StateManager"], bool]] = None,
+        on_transition_fn: Optional[Callable[["StateManager", AgentState, AgentState], None]] = None,
+    ) -> None:
+        self.from_state = from_state
+        self.to_state = to_state
+        self.condition_fn = condition_fn  # Optional validation function
+        self.on_transition_fn = on_transition_fn  # Optional transition handler
+
+
+class StateManager:
+    """Manages agent state transitions and state-specific behaviors.
+
+    Supports template-driven cognitive state behaviors configuration:
+    - Wakeup ceremony can be bypassed for partnership-model agents
+    - Shutdown can be instant, conditional, or always-consent
+    - PLAY/DREAM/SOLITUDE states can be enabled/disabled per agent
+
+    See FSD/COGNITIVE_STATE_BEHAVIORS.md for design rationale.
+    """
+
+    # Base valid transitions - these are filtered based on cognitive_behaviors config
+    BASE_TRANSITIONS = [
+        # Transitions TO shutdown from any state
+        StateTransition(AgentState.WAKEUP, AgentState.SHUTDOWN),
+        StateTransition(AgentState.WORK, AgentState.SHUTDOWN),
+        StateTransition(AgentState.DREAM, AgentState.SHUTDOWN),
+        StateTransition(AgentState.PLAY, AgentState.SHUTDOWN),
+        StateTransition(AgentState.SOLITUDE, AgentState.SHUTDOWN),
+        # Special startup transition - may be WAKEUP or WORK depending on config
+        StateTransition(AgentState.SHUTDOWN, AgentState.WAKEUP),
+        StateTransition(AgentState.SHUTDOWN, AgentState.WORK),  # Direct to WORK when wakeup bypassed
+        # Other valid transitions
+        StateTransition(AgentState.WAKEUP, AgentState.WORK),
+        StateTransition(AgentState.WAKEUP, AgentState.DREAM),
+        StateTransition(AgentState.WORK, AgentState.DREAM),
+        StateTransition(AgentState.WORK, AgentState.PLAY),
+        StateTransition(AgentState.WORK, AgentState.SOLITUDE),
+        StateTransition(AgentState.DREAM, AgentState.WORK),
+        StateTransition(AgentState.PLAY, AgentState.WORK),
+        StateTransition(AgentState.PLAY, AgentState.SOLITUDE),
+        StateTransition(AgentState.SOLITUDE, AgentState.WORK),
+    ]
+
+    # Legacy class attribute for backwards compatibility
+    VALID_TRANSITIONS = BASE_TRANSITIONS
+
+    def __init__(
+        self,
+        time_service: TimeServiceProtocol,
+        initial_state: AgentState = AgentState.SHUTDOWN,
+        cognitive_behaviors: Optional[CognitiveStateBehaviors] = None,
+    ) -> None:
+        """Initialize the state manager.
+
+        Args:
+            time_service: Service for time operations
+            initial_state: Starting state (default: SHUTDOWN)
+            cognitive_behaviors: Template-driven state transition config.
+                If None, uses default Covenant-compliant behaviors.
+        """
+        self.time_service = time_service
+        self.current_state = initial_state
+        self.state_history: List[StateTransitionRecord] = []
+        self.state_metadata: Dict[AgentState, StateMetadata] = {}
+
+        # Store cognitive behaviors config (default if not provided)
+        self.cognitive_behaviors = cognitive_behaviors or CognitiveStateBehaviors()
+
+        # Build transition map respecting cognitive behaviors
+        self._transition_map = self._build_transition_map()
+
+        self._record_state_change(initial_state, None)
+
+        # Initialize metadata for the initial state
+        self.state_metadata[initial_state] = StateMetadata(
+            entered_at=self.time_service.now_iso(), metrics=StateMetrics()
+        )
+
+        # Log cognitive behaviors configuration with clear indication of source
+        logger.info(
+            f"[STATE_MANAGER] Initialized with cognitive behaviors "
+            f"(from_template={cognitive_behaviors is not None}): "
+            f"wakeup.enabled={self.cognitive_behaviors.wakeup.enabled}, "
+            f"startup_target={self.startup_target_state.value}, "
+            f"shutdown.mode={self.cognitive_behaviors.shutdown.mode}"
+        )
+
+    @property
+    def wakeup_bypassed(self) -> bool:
+        """Check if wakeup ceremony is bypassed for this agent."""
+        return not self.cognitive_behaviors.wakeup.enabled
+
+    @property
+    def startup_target_state(self) -> AgentState:
+        """Get the target state for startup (WAKEUP or WORK)."""
+        if self.wakeup_bypassed:
+            return AgentState.WORK
+        return AgentState.WAKEUP
+
+    def _build_transition_map(self) -> Dict[AgentState, Dict[AgentState, StateTransition]]:
+        """Build a map for quick transition lookups respecting cognitive behaviors.
+
+        Filters transitions based on:
+        - wakeup.enabled: Determines SHUTDOWN -> WAKEUP vs SHUTDOWN -> WORK
+        - play.enabled: Whether PLAY state is accessible
+        - dream.enabled: Whether DREAM state is accessible
+        - solitude.enabled: Whether SOLITUDE state is accessible
+        """
+        transition_map: Dict[AgentState, Dict[AgentState, StateTransition]] = {}
+        behaviors = self.cognitive_behaviors
+
+        for transition in self.BASE_TRANSITIONS:
+            # Filter based on cognitive behaviors config
+            if not self._is_transition_allowed(transition, behaviors):
+                continue
+
+            if transition.from_state not in transition_map:
+                transition_map[transition.from_state] = {}
+            transition_map[transition.from_state][transition.to_state] = transition
+
+        return transition_map
+
+    def _is_optional_state_enabled(self, state: AgentState, behaviors: CognitiveStateBehaviors) -> bool:
+        """Check if an optional cognitive state is enabled in behaviors.
+
+        Returns True for states that are always enabled (WORK, WAKEUP, SHUTDOWN).
+        Returns the enabled flag for optional states (PLAY, DREAM, SOLITUDE).
+        """
+        state_behavior_map = {
+            AgentState.PLAY: behaviors.play,
+            AgentState.DREAM: behaviors.dream,
+            AgentState.SOLITUDE: behaviors.solitude,
+        }
+        behavior = state_behavior_map.get(state)
+        return bool(getattr(behavior, "enabled", True)) if behavior else True
+
+    def _check_shutdown_wakeup_transition(
+        self, from_state: AgentState, to_state: AgentState, behaviors: CognitiveStateBehaviors
+    ) -> Optional[bool]:
+        """Check SHUTDOWN -> WAKEUP/WORK transitions based on wakeup config.
+
+        Returns True/False for definitive result, None if not a shutdown transition.
+        """
+        if from_state != AgentState.SHUTDOWN:
+            return None
+        if to_state == AgentState.WAKEUP:
+            return behaviors.wakeup.enabled
+        if to_state == AgentState.WORK:
+            return not behaviors.wakeup.enabled
+        return None
+
+    def _is_transition_allowed(
+        self,
+        transition: StateTransition,
+        behaviors: CognitiveStateBehaviors,
+    ) -> bool:
+        """Check if a transition is allowed based on cognitive behaviors.
+
+        Args:
+            transition: The transition to check
+            behaviors: The cognitive behaviors configuration
+
+        Returns:
+            True if the transition is allowed, False otherwise
+        """
+        from_state = transition.from_state
+        to_state = transition.to_state
+
+        # Check SHUTDOWN -> WAKEUP/WORK transitions
+        shutdown_result = self._check_shutdown_wakeup_transition(from_state, to_state, behaviors)
+        if shutdown_result is not None:
+            return shutdown_result
+
+        # Check if optional states (PLAY, DREAM, SOLITUDE) are enabled
+        if not self._is_optional_state_enabled(to_state, behaviors):
+            return False
+        if not self._is_optional_state_enabled(from_state, behaviors):
+            return False
+
+        return True
+
+    def _record_state_change(self, new_state: AgentState, old_state: Optional[AgentState]) -> None:
+        """Record state change in history."""
+        record = StateTransitionRecord(
+            timestamp=self.time_service.now_iso(),
+            from_state=old_state.value if old_state else None,
+            to_state=new_state.value,
+            metadata=None,  # Optional field, explicitly set to None
+        )
+        self.state_history.append(record)
+
+    async def can_transition_to(self, target_state: AgentState) -> bool:
+        """Check if transition to target state is valid."""
+        if self.current_state not in self._transition_map:
+            return False
+
+        if target_state not in self._transition_map[self.current_state]:
+            return False
+
+        transition = self._transition_map[self.current_state][target_state]
+
+        # Check condition function if present
+        if transition.condition_fn and not transition.condition_fn(self):
+            return False
+
+        return True
+
+    async def transition_to(self, target_state: AgentState) -> bool:
+        """
+        Attempt to transition to a new state.
+        Returns True if successful, False otherwise.
+
+        Note: Respects cognitive_behaviors configuration for startup transitions.
+        When wakeup is bypassed, SHUTDOWN -> WORK is the valid startup path.
+        """
+        # Handle startup transition based on cognitive behaviors
+        if self.current_state == AgentState.SHUTDOWN:
+            expected_startup = self.startup_target_state
+            if target_state != expected_startup:
+                logger.warning(
+                    f"Attempted transition from SHUTDOWN to {target_state.value} - blocked! "
+                    f"Expected startup transition is SHUTDOWN -> {expected_startup.value} "
+                    f"(wakeup_bypassed={self.wakeup_bypassed})"
+                )
+                return False
+            # Allow the configured startup transition
+
+        if not await self.can_transition_to(target_state):
+            logger.warning(f"Invalid state transition attempted: {self.current_state.value} -> {target_state.value}")
+            return False
+
+        old_state = self.current_state
+        transition = self._transition_map[old_state][target_state]
+
+        # Execute transition handler if present
+        if transition.on_transition_fn:
+            try:
+                transition.on_transition_fn(self, old_state, target_state)
+            except Exception as e:
+                logger.error(f"Error in transition handler for {old_state.value} -> {target_state.value}: {e}")
+                return False
+
+        # Update state
+        self.current_state = target_state
+        self._record_state_change(target_state, old_state)
+
+        logger.info(f"State transition: {old_state.value} -> {target_state.value}")
+        import datetime
+
+        timestamp = datetime.datetime.now().strftime("%H:%M:%S.%f")[:-3]
+        try:
+            print(f"[{timestamp}] [STATE] Transition: {old_state.value} -> {target_state.value}")  # Print to console
+        except OSError:
+            # Stdout closed during shutdown - this is expected in some contexts (e.g., QA runner)
+            # Note: BrokenPipeError is a subclass of OSError, so catching OSError handles both
+            pass
+
+        # Initialize metadata for new state if needed
+        if target_state not in self.state_metadata:
+            self.state_metadata[target_state] = StateMetadata(
+                entered_at=self.time_service.now_iso(), metrics=StateMetrics()
+            )
+
+        return True
+
+    def get_state(self) -> AgentState:
+        """Get current state."""
+        return self.current_state
+
+    def get_state_metadata(self) -> StateMetadata:
+        """Get metadata for current state."""
+        return self.state_metadata.get(
+            self.current_state, StateMetadata(entered_at=self.time_service.now_iso(), metrics=StateMetrics())
+        )
+
+    def update_state_metadata(self, key: str, value: Any) -> None:
+        """Update metadata for current state."""
+        if self.current_state not in self.state_metadata:
+            self.state_metadata[self.current_state] = StateMetadata(
+                entered_at=self.time_service.now_iso(), metrics=StateMetrics()
+            )
+        self.state_metadata[self.current_state].add_metric(key, value)
+
+    def get_state_duration(self) -> float:
+        """Get duration in seconds for current state."""
+        metadata = self.get_state_metadata()
+        if metadata.entered_at:
+            entered_at = datetime.fromisoformat(metadata.entered_at)
+            return (self.time_service.now() - entered_at).total_seconds()
+        return 0.0
+
+    def should_auto_transition(self) -> Optional[AgentState]:
+        """
+        Check if an automatic state transition should occur.
+        Returns the target state if a transition should happen, None otherwise.
+        """
+        # NEVER auto-transition from SHUTDOWN state
+        if self.current_state == AgentState.SHUTDOWN:
+            return None
+
+        if self.current_state == AgentState.WAKEUP:
+            # After successful wakeup, transition to WORK
+            metadata = self.get_state_metadata()
+            if metadata.metrics.custom_metrics.get("wakeup_complete", False):
+                return AgentState.WORK
+
+        # All other auto-transitions are removed as per the new requirements.
+        # For example, the transition from WORK to DREAM based on idle time,
+        # and from DREAM to WORK based on duration, are no longer automatic.
+
+        return None
+
+    def get_state_history(self) -> List[StateTransitionRecord]:
+        """Get the complete state transition history as typed records."""
+        return self.state_history.copy()
+
+    def get_state_history_summary(self) -> StateHistory:
+        """Get a complete summary of state history and current state."""
+        current_metadata = self.state_metadata.get(
+            self.current_state, StateMetadata(entered_at=self.time_service.now_iso(), metrics=StateMetrics())
+        )
+
+        return StateHistory(
+            transitions=self.state_history.copy(),
+            current_state=self.current_state,
+            current_state_metadata=current_metadata,
+        )