namespace ControlCenter.Api.Dtos;

/// <summary>
/// Data transfer object for broadcasting agent status updates
/// to all connected SignalR clients.
/// </summary>
public class AgentStatusUpdateDto
{
    /// <summary>
    /// Agent identifier, e.g. "otto", "dex", "rex".
    /// Not null — every update must identify the agent it refers to.
    /// </summary>
    public string AgentId { get; set; } = string.Empty;

    /// <summary>
    /// Human-readable display name, e.g. "Otto", "Dex".
    /// Not null — used by clients to render agent cards.
    /// </summary>
    public string DisplayName { get; set; } = string.Empty;

    /// <summary>
    /// Role description, e.g. "Orchestrator Agent", "Backend Specialist".
    /// Not null — provides context for the agent's function.
    /// </summary>
    public string Role { get; set; } = string.Empty;

    /// <summary>
    /// Current operational status of the agent.
    /// Maps to <see cref="Entities.AgentStatus"/> values as lowercase strings:
    /// "active", "idle", "thinking", "error".
    /// </summary>
    public string Status { get; set; } = string.Empty;

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

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

    /// <summary>
    /// Elapsed time string for the current task, e.g. "04m 12s".
    /// Null when no task is active.
    /// </summary>
    public string? TaskElapsed { get; set; }

    /// <summary>
    /// Full session key, e.g. "agent:otto:telegram:direct:8787451565".
    /// Not null — uniquely identifies the agent session.
    /// </summary>
    public string SessionKey { get; set; } = string.Empty;

    /// <summary>
    /// Communication channel the agent is operating on, e.g. "telegram", "discord", "slack".
    /// Not null — every agent session operates on exactly one channel.
    /// </summary>
    public string Channel { get; set; } = string.Empty;

    /// <summary>
    /// ISO 8601 timestamp of the agent's last activity.
    /// Not null — used by clients to detect stale connections.
    /// </summary>
    public string LastActivity { get; set; } = string.Empty;

    /// <summary>
    /// Error message when the agent status is "error".
    /// Null when the agent is not in an error state.
    /// </summary>
    public string? ErrorMessage { get; set; }
}