Control-Center/backend/ControlCenter/Hubs/Models/AgentStatusModels.cs

namespace ControlCenter;

/// <summary>
/// Agent operational status derived from OpenClaw Gateway session activity.
/// Maps to the frontend AgentStatus type: 'active' | 'idle' | 'thinking' | 'error'.
/// </summary>
public enum AgentStatus
{
    /// <summary>Agent is currently processing a turn.</summary>
    Active,

    /// <summary>Agent completed its last turn; no active work.</summary>
    Idle,

    /// <summary>LLM call in flight; tokens streaming.</summary>
    Thinking,

    /// <summary>Agent encountered an unhandled error.</summary>
    Error
}

/// <summary>
/// Extended lifecycle status including offline — not all agents have active sessions.
/// Used internally; clients only see <see cref="AgentStatus"/> (offline maps to idle).
/// </summary>
public enum AgentLifecycleStatus
{
    Active,
    Idle,
    Thinking,
    Error,
    Offline
}

/// <summary>
/// Pushed to SignalR clients when an agent's status changes.
/// Matches the TypeScript <c>AgentStatusUpdate</c> interface from the design spec.
/// </summary>
/// <param name="AgentId">Agent identifier, e.g. "otto", "dex".</param>
/// <param name="DisplayName">Human-readable name, e.g. "Otto".</param>
/// <param name="Role">Role description, e.g. "Orchestrator Agent".</param>
/// <param name="Status">Current operational status.</param>
/// <param name="CurrentTask">Description of the current task, if any.</param>
/// <param name="SessionKey">Full session key, e.g. "agent:otto:telegram:direct:8787451565".</param>
/// <param name="Channel">Channel the agent is operating on, e.g. "telegram".</param>
/// <param name="LastActivity">ISO 8601 timestamp of last activity.</param>
/// <param name="ErrorMessage">Error message when status is 'error'.</param>
public record AgentStatusUpdate(
    string AgentId,
    string DisplayName,
    string Role,
    string Status,
    string? CurrentTask,
    string SessionKey,
    string Channel,
    string LastActivity,
    string? ErrorMessage = null
);

/// <summary>
/// Pushed to SignalR clients when an agent's task progress updates.
/// Matches the TypeScript <c>TaskProgressUpdate</c> interface from the design spec.
/// </summary>
/// <param name="AgentId">Agent identifier.</param>
/// <param name="TaskDescription">Description of the current task.</param>
/// <param name="Progress">Task progress percentage (0–100), if trackable.</param>
/// <param name="Elapsed">Elapsed time string, e.g. "04m 12s".</param>
public record TaskProgressUpdate(
    string AgentId,
    string TaskDescription,
    int? Progress,
    string? Elapsed
);

/// <summary>
/// Data transfer object for broadcasting agent status updates
/// to all connected SignalR clients via the hub's SendStatusUpdate method.
///
/// <para>This DTO provides a mutable, serialization-friendly alternative to
/// <see cref="AgentStatusUpdate"/> for callers that construct updates
/// from external data sources (e.g., HTTP API payloads).</para>
/// </summary>
public class AgentStatusUpdateDto
{
    /// <summary>
    /// Agent identifier, e.g. "otto", "dex", "rex".
    /// </summary>
    public string AgentId { get; set; } = string.Empty;

    /// <summary>
    /// Human-readable display name, e.g. "Otto", "Dex".
    /// </summary>
    public string DisplayName { get; set; } = string.Empty;

    /// <summary>
    /// Role description, e.g. "Orchestrator Agent", "Backend Specialist".
    /// </summary>
    public string Role { get; set; } = string.Empty;

    /// <summary>
    /// Current operational status of the agent as lowercase string:
    /// "active", "idle", "thinking", "error".
    /// </summary>
    public string Status { get; set; } = string.Empty;

    /// <summary>
    /// Description of the agent's current task, if any.
    /// </summary>
    public string? CurrentTask { get; set; }

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

    /// <summary>
    /// Communication channel, e.g. "telegram", "discord", "slack".
    /// </summary>
    public string Channel { get; set; } = string.Empty;

    /// <summary>
    /// ISO 8601 timestamp of the agent's last activity.
    /// </summary>
    public string LastActivity { get; set; } = string.Empty;

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

    /// <summary>
    /// Converts this DTO to an immutable <see cref="AgentStatusUpdate"/> record
    /// for use with the typed SignalR client interface.
    /// </summary>
    /// <returns>An <see cref="AgentStatusUpdate"/> with equivalent field values.</returns>
    public AgentStatusUpdate ToUpdate() => new(
        AgentId,
        DisplayName,
        Role,
        Status,
        CurrentTask,
        SessionKey,
        Channel,
        LastActivity,
        ErrorMessage
    );
}

/// <summary>
/// Snapshot of an agent's full card data, sent on initial connection
/// or when the fleet state is requested.
/// Matches the TypeScript <c>AgentCardData</c> interface from the design spec.
/// </summary>
public record AgentCardData(
    string Id,
    string DisplayName,
    string Role,
    string Status,
    string? CurrentTask,
    int? TaskProgress,
    string? TaskElapsed,
    string SessionKey,
    string Channel,
    string LastActivity,
    string? ErrorMessage
);