#[derive(Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct SessionId(Uuid);

#[must_use]
pub fn generate() -> Self;

#[must_use]
pub const fn from_uuid(uuid: Uuid) -> Self;

#[must_use]
pub const fn as_uuid(&self) -> &Uuid;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SessionState {
    /// Agent has completed identity verification
    AgentBootstrapped,
    /// Session has been established
    SessionStarted,
    /// Capabilities have been granted to the agent
    CapabilitiesGranted,
    /// Agent is actively using tools
    ToolUse,
    /// Session or tokens are being renewed
    Renewal,
    /// Privilege escalation is in progress
    Escalation,
    /// Session has ended
    SessionEnded,
}

#[must_use]
pub const fn can_use_tools(&self) -> bool;

#[must_use]
pub const fn can_request_capabilities(&self) -> bool;

#[must_use]
pub const fn is_terminal(&self) -> bool;

#[must_use]
pub const fn is_active(&self) -> bool;

#[must_use]
pub fn valid_transitions(&self) -> &'static [SessionState];

#[must_use]
pub fn can_transition_to(&self, target: SessionState) -> bool;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SessionEndReason {
    /// Normal completion
    Completed,
    /// Explicit logout
    Logout,
    /// Session timeout
    Timeout,
    /// Token expired
    TokenExpired,
    /// Revoked by administrator
    Revoked,
    /// Security violation detected
    SecurityViolation,
    /// Policy violation
    PolicyViolation,
    /// System shutdown
    SystemShutdown,
    /// Error during session
    Error(String),
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentSession {
/// Unique session identifier

pub id: SessionId,
/// Tenant this session belongs to

pub tenant_id: TenantId,
/// Agent identity

pub agent_id: AgentId,
/// Principal (user/service) that initiated the session

#[serde(skip_serializing_if = "Option::is_none")]
pub principal_id: Option<PrincipalId>,
/// Current state

pub state: SessionState,
/// When the session was created

pub created_at: chrono::DateTime<chrono::Utc>,
/// When the session was last active

pub last_activity_at: chrono::DateTime<chrono::Utc>,
/// When the session expires

pub expires_at: chrono::DateTime<chrono::Utc>,
/// Session metadata

#[serde(default)]
pub metadata: std::collections::HashMap<String, String>,
/// Reason for session end (if ended)

#[serde(skip_serializing_if = "Option::is_none")]
pub end_reason: Option<SessionEndReason>
}

#[must_use]
pub fn new(tenant_id: TenantId, agent_id: AgentId, ttl_seconds: u64) -> Self;

#[must_use]
pub fn with_principal(mut self, principal_id: PrincipalId) -> Self;

pub fn transition_to(
        &mut self,
        new_state: SessionState,
        reason: Option<String>,
    ) -> ArsenalResult<()>;

pub fn start(&mut self) -> ArsenalResult<()>;

pub fn grant_capabilities(&mut self, scopes: &ScopeSet) -> ArsenalResult<()>;

pub fn begin_tool_use(&mut self) -> ArsenalResult<()>;

pub fn begin_renewal(&mut self) -> ArsenalResult<()>;

pub fn complete_renewal(
        &mut self,
        new_expires_at: chrono::DateTime<chrono::Utc>,
    ) -> ArsenalResult<()>;

pub fn begin_escalation(&mut self) -> ArsenalResult<()>;

pub fn end(&mut self, reason: SessionEndReason) -> ArsenalResult<()>;

pub fn add_token(&mut self, token_id: TokenId);

pub fn remove_token(&mut self, token_id: &TokenId);

#[must_use]
pub fn active_tokens(&self) -> &HashSet<TokenId>;

#[must_use]
pub fn granted_scopes(&self) -> &ScopeSet;

#[must_use]
pub fn is_expired(&self) -> bool;

#[must_use]
pub fn is_active(&self) -> bool;

pub fn touch(&mut self);

#[must_use]
pub fn state_history_len(&self) -> usize;

pub fn extend(&mut self, additional_seconds: u64);

pub fn set_metadata(&mut self, key: impl Into<String>, value: impl Into<String>);

#[must_use]
pub fn get_metadata(&self, key: &str) -> Option<&String>;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SessionConfig {
/// Default session TTL in seconds

pub default_ttl_seconds: u64,
/// Maximum session TTL in seconds

pub max_ttl_seconds: u64,
/// Idle timeout in seconds

pub idle_timeout_seconds: u64,
/// Maximum concurrent sessions per agent

pub max_concurrent_sessions: u32,
/// Allow session extension

pub allow_extension: bool,
/// Maximum extensions allowed

pub max_extensions: u32
}