namespace ControlCenter.Models;

/// <summary>
/// Persistent state for an agent in the Control Center.
/// Maps to the <c>agents</c> table in PostgreSQL.
///
/// <para>Tracks the operational status, current task, progress,
/// session identity, and last activity timestamp for each agent
/// in the minion fleet.</para>
///
/// <para>The <see cref="Status"/> property uses string values matching
/// the AgentStatus enum: "active", "idle", "thinking", "error".
/// Stored as <c>varchar</c> rather than a DB enum for schema flexibility.</para>
/// </summary>
public class AgentState
{
    /// <summary>
    /// Unique identifier for the agent state record.
    /// Defaults to a new <see cref="Guid"/> on creation.
    /// </summary>
    public Guid Id { get; set; } = Guid.NewGuid();

    /// <summary>
    /// Operational status of the agent.
    /// Valid values: "active", "idle", "thinking", "error".
    /// Maps to the AgentStatus enum used by SignalR.
    /// </summary>
    public string Status { get; set; } = "idle";

    /// <summary>
    /// Description of the agent's current task, if any.
    /// Null when the agent is idle with no active assignment.
    /// </summary>
    public string? Task { get; set; }

    /// <summary>
    /// Task progress percentage (0–100).
    /// Null when progress is not trackable for the current task.
    /// </summary>
    public int? Progress { get; set; }

    /// <summary>
    /// Full session key identifying the agent's active session.
    /// Format: <c>agent:{agentId}:{channel}:...</c>
    /// Used to correlate SignalR events with persistent state.
    /// </summary>
    public string SessionKey { get; set; } = string.Empty;

    /// <summary>
    /// The channel the agent is operating on (e.g., "telegram", "discord", "slack").
    /// </summary>
    public string Channel { get; set; } = string.Empty;

    /// <summary>
    /// Timestamp of the agent's last recorded activity.
    /// Updated on every status change or task progress event.
    /// </summary>
    public DateTime LastActivity { get; set; } = DateTime.UtcNow;
}