cellstate_core/

agent_state.rs

//! Agent state derived from event history (NOT stored in DB)
//!
//! Re-export path: cellstate_core::agent_state::*

use crate::identity::EntityIdType;
use crate::{AgentId, BeliefId, DelegationId, Effect, GoalId, PlanId, ScopeId};
use serde::{Deserialize, Serialize};

/// Agent state derived from event history (NOT stored in DB)
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AgentState {
    Idle,
    Gathering {
        scope_id: ScopeId,
    },
    Planning {
        scope_id: ScopeId,
    },
    Executing {
        scope_id: ScopeId,
        tool_call_id: String,
    },
    Waiting {
        for_event_type: String,
    },
    Delegating {
        to: AgentId,
        delegation_id: DelegationId,
    },
    Complete {
        scope_id: ScopeId,
    },
    Failed {
        scope_id: ScopeId,
        error: String,
    },
}

impl AgentState {
    /// Derive agent state from event history by scanning in chronological order.
    /// Handles SCOPE_CREATED/SCOPE_CLOSED, DELEGATION_*, and AGENT_STATUS_CHANGED.
    ///
    /// AGENT_STATUS_CHANGED events carry a `"status"` field in their payload.
    /// Recognised values: `"executing"`, `"waiting"`, `"failed"`, `"idle"`.
    /// This prevents silent state divergence when an agent crashes mid-execution
    /// and an explicit status change event is emitted.
    pub fn from_events(events: &[crate::Event<serde_json::Value>]) -> Self {
        use crate::EventKind;

        let mut current_state = AgentState::Idle;

        // Scan events in chronological order to build up state
        for event in events.iter() {
            match event.header.event_kind {
                EventKind::SCOPE_CREATED => {
                    if let Some(scope_id) = extract_scope_id(&event.payload) {
                        current_state = AgentState::Gathering { scope_id };
                    }
                }
                EventKind::SCOPE_CLOSED => {
                    if let Some(scope_id) = extract_scope_id(&event.payload) {
                        // Check if there's an error in the payload
                        if let Some(error) = extract_error(&event.payload) {
                            current_state = AgentState::Failed { scope_id, error };
                        } else {
                            current_state = AgentState::Complete { scope_id };
                        }
                    }
                }
                EventKind::DELEGATION_CREATED => {
                    if let (Some(to), Some(delegation_id)) = (
                        extract_agent_id(&event.payload),
                        extract_delegation_id(&event.payload),
                    ) {
                        current_state = AgentState::Delegating { to, delegation_id };
                    }
                }
                // Intermediate delegation events — the delegation is still in
                // progress, so the agent stays in Delegating state.
                EventKind::DELEGATION_ACCEPTED | EventKind::DELEGATION_STARTED => {
                    // No state change: agent remains Delegating while the
                    // delegatee is actively working.
                }
                // Terminal delegation events — delegation is finished.
                EventKind::DELEGATION_COMPLETED
                | EventKind::DELEGATION_FAILED
                | EventKind::DELEGATION_REJECTED => {
                    current_state = AgentState::Idle;
                }
                // Explicit agent status changes (e.g. crash recovery, admin override).
                EventKind::AGENT_STATUS_CHANGED => {
                    if let Some(new_state) = extract_agent_state(&event.payload) {
                        current_state = new_state;
                    }
                }
                _ => {
                    // Ignore other event types
                }
            }
        }

        current_state
    }

    /// Check if a transition from current state to target state is valid.
    /// Valid transitions per the state machine:
    /// - Idle -> Gathering, Delegating
    /// - Gathering -> Planning, Failed
    /// - Planning -> Executing, Failed
    /// - Executing -> Waiting, Complete, Failed
    /// - Waiting -> Executing, Failed
    /// - Delegating -> Idle, Failed
    /// - Complete -> Idle
    /// - Failed -> Idle
    pub fn can_transition_to(&self, target: &AgentState) -> bool {
        use AgentState::*;

        match (self, target) {
            // Idle transitions
            (Idle, Gathering { .. }) => true,
            (Idle, Delegating { .. }) => true,

            // Gathering transitions
            (Gathering { .. }, Planning { .. }) => true,
            (Gathering { .. }, Failed { .. }) => true,

            // Planning transitions
            (Planning { .. }, Executing { .. }) => true,
            (Planning { .. }, Failed { .. }) => true,

            // Executing transitions
            (Executing { .. }, Waiting { .. }) => true,
            (Executing { .. }, Complete { .. }) => true,
            (Executing { .. }, Failed { .. }) => true,

            // Waiting transitions
            (Waiting { .. }, Executing { .. }) => true,
            (Waiting { .. }, Failed { .. }) => true,

            // Delegating transitions
            (Delegating { .. }, Idle) => true,
            (Delegating { .. }, Failed { .. }) => true,

            // Complete transitions
            (Complete { .. }, Idle) => true,

            // Failed transitions
            (Failed { .. }, Idle) => true,

            // No other transitions are valid
            _ => false,
        }
    }

    /// Return a vector of states reachable from the current state.
    /// Uses placeholder data where necessary (scope_id preserved when available).
    pub fn valid_transitions(&self) -> Vec<AgentState> {
        use AgentState::*;

        match self {
            Idle => vec![
                // Gathering and Delegating require IDs - use nil IDs as placeholders
                Gathering {
                    scope_id: ScopeId::nil(),
                },
                Delegating {
                    to: AgentId::nil(),
                    delegation_id: DelegationId::nil(),
                },
            ],
            Gathering { scope_id } => vec![
                Planning {
                    scope_id: *scope_id,
                },
                Failed {
                    scope_id: *scope_id,
                    error: String::new(),
                },
            ],
            Planning { scope_id } => vec![
                Executing {
                    scope_id: *scope_id,
                    tool_call_id: String::new(),
                },
                Failed {
                    scope_id: *scope_id,
                    error: String::new(),
                },
            ],
            Executing { scope_id, .. } => vec![
                Waiting {
                    for_event_type: String::new(),
                },
                Complete {
                    scope_id: *scope_id,
                },
                Failed {
                    scope_id: *scope_id,
                    error: String::new(),
                },
            ],
            Waiting { .. } => vec![
                // Executing requires scope_id which we don't have in Waiting - use nil ID
                Executing {
                    scope_id: ScopeId::nil(),
                    tool_call_id: String::new(),
                },
                Failed {
                    scope_id: ScopeId::nil(),
                    error: String::new(),
                },
            ],
            Delegating { .. } => vec![
                Idle,
                Failed {
                    scope_id: ScopeId::nil(),
                    error: String::new(),
                },
            ],
            Complete { .. } => vec![Idle],
            Failed { .. } => vec![Idle],
        }
    }
}

// Helper functions to extract data from event payloads

fn extract_scope_id(payload: &serde_json::Value) -> Option<ScopeId> {
    payload
        .get("scope_id")
        .and_then(|v| serde_json::from_value(v.clone()).ok())
}

fn extract_agent_id(payload: &serde_json::Value) -> Option<AgentId> {
    // Try fields in order of specificity: relay delegation payloads use
    // "to_agent_id" / "delegatee_id", generic events use "agent_id",
    // and test helpers may use "to".
    payload
        .get("to_agent_id")
        .or_else(|| payload.get("delegatee_id"))
        .or_else(|| payload.get("agent_id"))
        .or_else(|| payload.get("to"))
        .and_then(|v| serde_json::from_value(v.clone()).ok())
}

fn extract_delegation_id(payload: &serde_json::Value) -> Option<DelegationId> {
    payload
        .get("delegation_id")
        .and_then(|v| serde_json::from_value(v.clone()).ok())
}

fn extract_error(payload: &serde_json::Value) -> Option<String> {
    payload
        .get("error")
        .and_then(|v| v.as_str())
        .map(|s| s.to_string())
}

/// Extract agent state from AGENT_STATUS_CHANGED payload.
///
/// Expected payload shape: `{ "status": "idle"|"executing"|"waiting"|"failed", ... }`
fn extract_agent_state(payload: &serde_json::Value) -> Option<AgentState> {
    let status = payload.get("status").and_then(|v| v.as_str())?;
    match status {
        "idle" => Some(AgentState::Idle),
        "executing" => {
            let scope_id = extract_scope_id(payload).unwrap_or_else(ScopeId::nil);
            let tool_call_id = payload
                .get("tool_call_id")
                .and_then(|v| v.as_str())
                .unwrap_or("")
                .to_string();
            Some(AgentState::Executing {
                scope_id,
                tool_call_id,
            })
        }
        "waiting" => {
            let for_event_type = payload
                .get("for_event_type")
                .and_then(|v| v.as_str())
                .unwrap_or("")
                .to_string();
            Some(AgentState::Waiting { for_event_type })
        }
        "failed" => {
            let scope_id = extract_scope_id(payload).unwrap_or_else(ScopeId::nil);
            let error = extract_error(payload).unwrap_or_default();
            Some(AgentState::Failed { scope_id, error })
        }
        "gathering" => {
            let scope_id = extract_scope_id(payload).unwrap_or_else(ScopeId::nil);
            Some(AgentState::Gathering { scope_id })
        }
        "planning" => {
            let scope_id = extract_scope_id(payload).unwrap_or_else(ScopeId::nil);
            Some(AgentState::Planning { scope_id })
        }
        _ => None, // Unknown status string — ignore gracefully
    }
}

/// Lifecycle hooks for agent state transitions and BDI events.
///
/// All methods have default no-op implementations so consumers only
/// override the hooks they care about. Return `Effect::Err(...)` to
/// signal that the hook vetoed the transition (caller decides policy).
pub trait AgentLifecycle: Send + Sync {
    // ── Checkpoint / resume (Trigger.dev pattern) ──────────────────

    /// Called when the agent enters a wait state (checkpoint).
    fn on_wait(&self, _state: &AgentState) -> Effect<()> {
        Effect::Ok(())
    }

    /// Called when the agent resumes from a wait state.
    fn on_resume(&self, _state: &AgentState) -> Effect<()> {
        Effect::Ok(())
    }

    // ── Goal lifecycle ─────────────────────────────────────────────

    /// A new goal was created for this agent.
    fn on_goal_created(&self, _goal_id: GoalId, _description: &str) -> Effect<()> {
        Effect::Ok(())
    }

    /// A goal transitioned to Active.
    fn on_goal_activated(&self, _goal_id: GoalId) -> Effect<()> {
        Effect::Ok(())
    }

    /// A goal was achieved (all criteria satisfied).
    fn on_goal_achieved(&self, _goal_id: GoalId) -> Effect<()> {
        Effect::Ok(())
    }

    /// A goal failed (deadline, max retries, or explicit failure).
    fn on_goal_failed(&self, _goal_id: GoalId, _reason: &str) -> Effect<()> {
        Effect::Ok(())
    }

    // ── Plan lifecycle ─────────────────────────────────────────────

    /// A new plan was created for a goal.
    fn on_plan_created(&self, _plan_id: PlanId, _goal_id: GoalId) -> Effect<()> {
        Effect::Ok(())
    }

    /// A plan completed (all steps done).
    fn on_plan_completed(&self, _plan_id: PlanId) -> Effect<()> {
        Effect::Ok(())
    }

    // ── Belief lifecycle ───────────────────────────────────────────

    /// A belief was created or its confidence was updated.
    fn on_belief_updated(&self, _belief_id: BeliefId, _confidence: f32) -> Effect<()> {
        Effect::Ok(())
    }

    /// A belief was superseded by a newer belief.
    fn on_belief_superseded(&self, _old: BeliefId, _new: BeliefId) -> Effect<()> {
        Effect::Ok(())
    }

    // ── Drift lifecycle ────────────────────────────────────────────

    /// Drift was detected between this agent and another.
    fn on_drift_detected(&self, _other_agent: AgentId, _composite_score: f64) -> Effect<()> {
        Effect::Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{DagPosition, Event, EventFlags, EventHeader, EventId, EventKind};
    use serde_json::json;

    // Helper function to create a test event with a given kind and payload
    fn create_event(event_kind: EventKind, payload: serde_json::Value) -> Event<serde_json::Value> {
        Event::new(
            EventHeader::new(
                EventId::now_v7(),
                EventId::now_v7(),
                chrono::Utc::now().timestamp_micros(),
                DagPosition::root(),
                0,
                event_kind,
                EventFlags::empty(),
                None,
            ),
            payload,
        )
    }

    // Helper function to create a SCOPE_CREATED event
    fn scope_created_event(scope_id: ScopeId) -> Event<serde_json::Value> {
        create_event(
            EventKind::SCOPE_CREATED,
            json!({
                "scope_id": scope_id,
            }),
        )
    }

    // Helper function to create a SCOPE_CLOSED event (success)
    fn scope_closed_event(scope_id: ScopeId) -> Event<serde_json::Value> {
        create_event(
            EventKind::SCOPE_CLOSED,
            json!({
                "scope_id": scope_id,
            }),
        )
    }

    // Helper function to create a SCOPE_CLOSED event with error
    fn scope_closed_error_event(scope_id: ScopeId, error: &str) -> Event<serde_json::Value> {
        create_event(
            EventKind::SCOPE_CLOSED,
            json!({
                "scope_id": scope_id,
                "error": error,
            }),
        )
    }

    // Helper function to create a DELEGATION_CREATED event.
    // Payload mirrors the real relay output: "to_agent_id" + "agent_id" + "delegation_id".
    fn delegation_created_event(
        to: AgentId,
        delegation_id: DelegationId,
    ) -> Event<serde_json::Value> {
        create_event(
            EventKind::DELEGATION_CREATED,
            json!({
                "to_agent_id": to,
                "agent_id": to,
                "delegation_id": delegation_id,
            }),
        )
    }

    // Helper function to create a DELEGATION_COMPLETED event
    fn delegation_completed_event() -> Event<serde_json::Value> {
        create_event(EventKind::DELEGATION_COMPLETED, json!({}))
    }

    // Helper function to create a DELEGATION_FAILED event
    fn delegation_failed_event() -> Event<serde_json::Value> {
        create_event(EventKind::DELEGATION_FAILED, json!({}))
    }

    // Helper function to create a DELEGATION_ACCEPTED event
    fn delegation_accepted_event() -> Event<serde_json::Value> {
        create_event(EventKind::DELEGATION_ACCEPTED, json!({}))
    }

    // Helper function to create a DELEGATION_STARTED event
    fn delegation_started_event() -> Event<serde_json::Value> {
        create_event(EventKind::DELEGATION_STARTED, json!({}))
    }

    // Helper function to create a DELEGATION_REJECTED event
    fn delegation_rejected_event() -> Event<serde_json::Value> {
        create_event(EventKind::DELEGATION_REJECTED, json!({}))
    }

    // ========================================================================
    // Tests for AgentState::from_events()
    // ========================================================================

    #[test]
    fn test_from_events_empty_returns_idle() {
        let events = vec![];
        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Idle);
    }

    #[test]
    fn test_from_events_scope_created_returns_gathering() {
        let scope_id = ScopeId::now_v7();
        let events = vec![scope_created_event(scope_id)];

        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Gathering { scope_id });
    }

    #[test]
    fn test_from_events_scope_closed_returns_complete() {
        let scope_id = ScopeId::now_v7();
        let events = vec![scope_created_event(scope_id), scope_closed_event(scope_id)];

        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Complete { scope_id });
    }

    #[test]
    fn test_from_events_scope_closed_with_error_returns_failed() {
        let scope_id = ScopeId::now_v7();
        let error_msg = "Test error occurred";
        let events = vec![
            scope_created_event(scope_id),
            scope_closed_error_event(scope_id, error_msg),
        ];

        let state = AgentState::from_events(&events);
        assert_eq!(
            state,
            AgentState::Failed {
                scope_id,
                error: error_msg.to_string()
            }
        );
    }

    #[test]
    fn test_from_events_delegation_created_returns_delegating() {
        let to = AgentId::now_v7();
        let delegation_id = DelegationId::now_v7();
        let events = vec![delegation_created_event(to, delegation_id)];

        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Delegating { to, delegation_id });
    }

    #[test]
    fn test_from_events_delegation_completed_returns_idle() {
        let to = AgentId::now_v7();
        let delegation_id = DelegationId::now_v7();
        let events = vec![
            delegation_created_event(to, delegation_id),
            delegation_completed_event(),
        ];

        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Idle);
    }

    #[test]
    fn test_from_events_delegation_failed_returns_idle() {
        let to = AgentId::now_v7();
        let delegation_id = DelegationId::now_v7();
        let events = vec![
            delegation_created_event(to, delegation_id),
            delegation_failed_event(),
        ];

        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Idle);
    }

    #[test]
    fn test_from_events_delegation_accepted_stays_delegating() {
        let to = AgentId::now_v7();
        let delegation_id = DelegationId::now_v7();
        let events = vec![
            delegation_created_event(to, delegation_id),
            delegation_accepted_event(),
        ];

        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Delegating { to, delegation_id });
    }

    #[test]
    fn test_from_events_delegation_started_stays_delegating() {
        let to = AgentId::now_v7();
        let delegation_id = DelegationId::now_v7();
        let events = vec![
            delegation_created_event(to, delegation_id),
            delegation_accepted_event(),
            delegation_started_event(),
        ];

        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Delegating { to, delegation_id });
    }

    #[test]
    fn test_from_events_delegation_rejected_returns_idle() {
        let to = AgentId::now_v7();
        let delegation_id = DelegationId::now_v7();
        let events = vec![
            delegation_created_event(to, delegation_id),
            delegation_rejected_event(),
        ];

        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Idle);
    }

    #[test]
    fn test_from_events_full_delegation_lifecycle() {
        let to = AgentId::now_v7();
        let delegation_id = DelegationId::now_v7();
        let events = vec![
            delegation_created_event(to, delegation_id),
            delegation_accepted_event(),
            delegation_started_event(),
            delegation_completed_event(),
        ];

        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Idle);
    }

    #[test]
    fn test_from_events_multiple_scopes_uses_latest() {
        let scope_id_1 = ScopeId::now_v7();
        let scope_id_2 = ScopeId::now_v7();
        let events = vec![
            scope_created_event(scope_id_1),
            scope_closed_event(scope_id_1),
            scope_created_event(scope_id_2),
        ];

        let state = AgentState::from_events(&events);
        assert_eq!(
            state,
            AgentState::Gathering {
                scope_id: scope_id_2
            }
        );
    }

    #[test]
    fn test_from_events_scope_then_delegation() {
        let scope_id = ScopeId::now_v7();
        let to = AgentId::now_v7();
        let delegation_id = DelegationId::now_v7();

        let events = vec![
            scope_created_event(scope_id),
            scope_closed_event(scope_id),
            delegation_created_event(to, delegation_id),
        ];

        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Delegating { to, delegation_id });
    }

    #[test]
    fn test_from_events_delegation_then_scope() {
        let to = AgentId::now_v7();
        let delegation_id = DelegationId::now_v7();
        let scope_id = ScopeId::now_v7();

        let events = vec![
            delegation_created_event(to, delegation_id),
            delegation_completed_event(),
            scope_created_event(scope_id),
        ];

        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Gathering { scope_id });
    }

    // Helper function to create an AGENT_STATUS_CHANGED event
    fn agent_status_changed_event(
        status: &str,
        payload_extra: serde_json::Value,
    ) -> Event<serde_json::Value> {
        let mut payload = payload_extra;
        payload
            .as_object_mut()
            .unwrap()
            .insert("status".to_string(), json!(status));
        create_event(EventKind::AGENT_STATUS_CHANGED, payload)
    }

    #[test]
    fn test_from_events_agent_status_changed_to_idle() {
        let scope_id = ScopeId::now_v7();
        let events = vec![
            scope_created_event(scope_id),
            agent_status_changed_event("idle", json!({})),
        ];
        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Idle);
    }

    #[test]
    fn test_from_events_agent_status_changed_to_failed() {
        let scope_id = ScopeId::now_v7();
        let events = vec![
            scope_created_event(scope_id),
            agent_status_changed_event("failed", json!({ "scope_id": scope_id, "error": "crash" })),
        ];
        let state = AgentState::from_events(&events);
        assert_eq!(
            state,
            AgentState::Failed {
                scope_id,
                error: "crash".to_string()
            }
        );
    }

    #[test]
    fn test_from_events_agent_status_changed_unknown_ignored() {
        let scope_id = ScopeId::now_v7();
        let events = vec![
            scope_created_event(scope_id),
            agent_status_changed_event("unknown_status", json!({})),
        ];
        // Unknown status should be ignored, state stays as Gathering
        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Gathering { scope_id });
    }

    #[test]
    fn test_from_events_ignores_unknown_event_kinds() {
        let scope_id = ScopeId::now_v7();
        let events = vec![
            create_event(EventKind::SYSTEM_HEARTBEAT, json!({})),
            scope_created_event(scope_id),
            create_event(EventKind::MESSAGE_SENT, json!({})),
        ];

        let state = AgentState::from_events(&events);
        assert_eq!(state, AgentState::Gathering { scope_id });
    }

    #[test]
    fn test_from_events_complex_sequence() {
        let scope_id_1 = ScopeId::now_v7();
        let scope_id_2 = ScopeId::now_v7();
        let to = AgentId::now_v7();
        let delegation_id = DelegationId::now_v7();

        let events = vec![
            scope_created_event(scope_id_1),
            scope_closed_event(scope_id_1),
            delegation_created_event(to, delegation_id),
            delegation_completed_event(),
            scope_created_event(scope_id_2),
            scope_closed_error_event(scope_id_2, "Something went wrong"),
        ];

        let state = AgentState::from_events(&events);
        assert_eq!(
            state,
            AgentState::Failed {
                scope_id: scope_id_2,
                error: "Something went wrong".to_string()
            }
        );
    }

    // ========================================================================
    // Tests for AgentState::can_transition_to()
    // ========================================================================

    #[test]
    fn test_idle_can_transition_to_gathering() {
        let from = AgentState::Idle;
        let to = AgentState::Gathering {
            scope_id: ScopeId::now_v7(),
        };
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_idle_can_transition_to_delegating() {
        let from = AgentState::Idle;
        let to = AgentState::Delegating {
            to: AgentId::now_v7(),
            delegation_id: DelegationId::now_v7(),
        };
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_idle_cannot_transition_to_planning() {
        let from = AgentState::Idle;
        let to = AgentState::Planning {
            scope_id: ScopeId::now_v7(),
        };
        assert!(!from.can_transition_to(&to));
    }

    #[test]
    fn test_idle_cannot_transition_to_executing() {
        let from = AgentState::Idle;
        let to = AgentState::Executing {
            scope_id: ScopeId::now_v7(),
            tool_call_id: "test_call".to_string(),
        };
        assert!(!from.can_transition_to(&to));
    }

    #[test]
    fn test_gathering_can_transition_to_planning() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Gathering { scope_id };
        let to = AgentState::Planning { scope_id };
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_gathering_can_transition_to_failed() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Gathering { scope_id };
        let to = AgentState::Failed {
            scope_id,
            error: "Error".to_string(),
        };
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_gathering_cannot_transition_to_executing() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Gathering { scope_id };
        let to = AgentState::Executing {
            scope_id,
            tool_call_id: "test_call".to_string(),
        };
        assert!(!from.can_transition_to(&to));
    }

    #[test]
    fn test_planning_can_transition_to_executing() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Planning { scope_id };
        let to = AgentState::Executing {
            scope_id,
            tool_call_id: "test_call".to_string(),
        };
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_planning_can_transition_to_failed() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Planning { scope_id };
        let to = AgentState::Failed {
            scope_id,
            error: "Error".to_string(),
        };
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_planning_cannot_transition_to_gathering() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Planning { scope_id };
        let to = AgentState::Gathering { scope_id };
        assert!(!from.can_transition_to(&to));
    }

    #[test]
    fn test_executing_can_transition_to_waiting() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Executing {
            scope_id,
            tool_call_id: "test_call".to_string(),
        };
        let to = AgentState::Waiting {
            for_event_type: "USER_INPUT".to_string(),
        };
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_executing_can_transition_to_complete() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Executing {
            scope_id,
            tool_call_id: "test_call".to_string(),
        };
        let to = AgentState::Complete { scope_id };
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_executing_can_transition_to_failed() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Executing {
            scope_id,
            tool_call_id: "test_call".to_string(),
        };
        let to = AgentState::Failed {
            scope_id,
            error: "Error".to_string(),
        };
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_executing_cannot_transition_to_planning() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Executing {
            scope_id,
            tool_call_id: "test_call".to_string(),
        };
        let to = AgentState::Planning { scope_id };
        assert!(!from.can_transition_to(&to));
    }

    #[test]
    fn test_waiting_can_transition_to_executing() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Waiting {
            for_event_type: "USER_INPUT".to_string(),
        };
        let to = AgentState::Executing {
            scope_id,
            tool_call_id: "test_call".to_string(),
        };
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_waiting_can_transition_to_failed() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Waiting {
            for_event_type: "USER_INPUT".to_string(),
        };
        let to = AgentState::Failed {
            scope_id,
            error: "Error".to_string(),
        };
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_waiting_cannot_transition_to_complete() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Waiting {
            for_event_type: "USER_INPUT".to_string(),
        };
        let to = AgentState::Complete { scope_id };
        assert!(!from.can_transition_to(&to));
    }

    #[test]
    fn test_delegating_can_transition_to_idle() {
        let from = AgentState::Delegating {
            to: AgentId::now_v7(),
            delegation_id: DelegationId::now_v7(),
        };
        let to = AgentState::Idle;
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_delegating_can_transition_to_failed() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Delegating {
            to: AgentId::now_v7(),
            delegation_id: DelegationId::now_v7(),
        };
        let to = AgentState::Failed {
            scope_id,
            error: "Error".to_string(),
        };
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_delegating_cannot_transition_to_gathering() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Delegating {
            to: AgentId::now_v7(),
            delegation_id: DelegationId::now_v7(),
        };
        let to = AgentState::Gathering { scope_id };
        assert!(!from.can_transition_to(&to));
    }

    #[test]
    fn test_complete_can_transition_to_idle() {
        let from = AgentState::Complete {
            scope_id: ScopeId::now_v7(),
        };
        let to = AgentState::Idle;
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_complete_cannot_transition_to_gathering() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Complete { scope_id };
        let to = AgentState::Gathering { scope_id };
        assert!(!from.can_transition_to(&to));
    }

    #[test]
    fn test_failed_can_transition_to_idle() {
        let from = AgentState::Failed {
            scope_id: ScopeId::now_v7(),
            error: "Error".to_string(),
        };
        let to = AgentState::Idle;
        assert!(from.can_transition_to(&to));
    }

    #[test]
    fn test_failed_cannot_transition_to_gathering() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Failed {
            scope_id,
            error: "Error".to_string(),
        };
        let to = AgentState::Gathering { scope_id };
        assert!(!from.can_transition_to(&to));
    }

    #[test]
    fn test_invalid_self_transition_idle_to_idle() {
        let from = AgentState::Idle;
        let to = AgentState::Idle;
        assert!(!from.can_transition_to(&to));
    }

    #[test]
    fn test_invalid_self_transition_gathering_to_gathering() {
        let scope_id = ScopeId::now_v7();
        let from = AgentState::Gathering { scope_id };
        let to = AgentState::Gathering { scope_id };
        assert!(!from.can_transition_to(&to));
    }

    // ========================================================================
    // Tests for AgentState::valid_transitions()
    // ========================================================================

    #[test]
    fn test_valid_transitions_from_idle() {
        let state = AgentState::Idle;
        let transitions = state.valid_transitions();
        assert_eq!(transitions.len(), 2);
        assert!(transitions
            .iter()
            .any(|s| matches!(s, AgentState::Gathering { .. })));
        assert!(transitions
            .iter()
            .any(|s| matches!(s, AgentState::Delegating { .. })));
    }

    #[test]
    fn test_valid_transitions_from_gathering() {
        let scope_id = ScopeId::now_v7();
        let state = AgentState::Gathering { scope_id };
        let transitions = state.valid_transitions();
        assert_eq!(transitions.len(), 2);
        assert!(transitions
            .iter()
            .any(|s| matches!(s, AgentState::Planning { .. })));
        assert!(transitions
            .iter()
            .any(|s| matches!(s, AgentState::Failed { .. })));
    }

    #[test]
    fn test_valid_transitions_from_planning() {
        let scope_id = ScopeId::now_v7();
        let state = AgentState::Planning { scope_id };
        let transitions = state.valid_transitions();
        assert_eq!(transitions.len(), 2);
        assert!(transitions
            .iter()
            .any(|s| matches!(s, AgentState::Executing { .. })));
        assert!(transitions
            .iter()
            .any(|s| matches!(s, AgentState::Failed { .. })));
    }

    #[test]
    fn test_valid_transitions_from_executing() {
        let scope_id = ScopeId::now_v7();
        let state = AgentState::Executing {
            scope_id,
            tool_call_id: "test_call".to_string(),
        };
        let transitions = state.valid_transitions();
        assert_eq!(transitions.len(), 3);
        assert!(transitions
            .iter()
            .any(|s| matches!(s, AgentState::Waiting { .. })));
        assert!(transitions
            .iter()
            .any(|s| matches!(s, AgentState::Complete { .. })));
        assert!(transitions
            .iter()
            .any(|s| matches!(s, AgentState::Failed { .. })));
    }

    #[test]
    fn test_valid_transitions_from_waiting() {
        let state = AgentState::Waiting {
            for_event_type: "USER_INPUT".to_string(),
        };
        let transitions = state.valid_transitions();
        assert_eq!(transitions.len(), 2);
        assert!(transitions
            .iter()
            .any(|s| matches!(s, AgentState::Executing { .. })));
        assert!(transitions
            .iter()
            .any(|s| matches!(s, AgentState::Failed { .. })));
    }

    #[test]
    fn test_valid_transitions_from_delegating() {
        let state = AgentState::Delegating {
            to: AgentId::now_v7(),
            delegation_id: DelegationId::now_v7(),
        };
        let transitions = state.valid_transitions();
        assert_eq!(transitions.len(), 2);
        assert!(transitions.iter().any(|s| matches!(s, AgentState::Idle)));
        assert!(transitions
            .iter()
            .any(|s| matches!(s, AgentState::Failed { .. })));
    }

    #[test]
    fn test_valid_transitions_from_complete() {
        let state = AgentState::Complete {
            scope_id: ScopeId::now_v7(),
        };
        let transitions = state.valid_transitions();
        assert_eq!(transitions.len(), 1);
        assert!(transitions.iter().any(|s| matches!(s, AgentState::Idle)));
    }

    #[test]
    fn test_valid_transitions_from_failed() {
        let state = AgentState::Failed {
            scope_id: ScopeId::now_v7(),
            error: "Error".to_string(),
        };
        let transitions = state.valid_transitions();
        assert_eq!(transitions.len(), 1);
        assert!(transitions.iter().any(|s| matches!(s, AgentState::Idle)));
    }
}