namespace ControlCenter.Hubs;

/// <summary>
/// Strongly-typed client interface for the AgentStatus SignalR hub.
/// Defines the methods the server can invoke on connected clients
/// to push real-time agent status and task progress updates.
/// 
/// <para>All server-to-client calls go through this interface for
/// compile-time safety — matching the pattern used by the
/// Extrudex PrinterHub.</para>
/// </summary>
public interface IAgentStatusClient
{
    /// <summary>
    /// Pushes an agent status change to all subscribed clients.
    /// Fired whenever an agent's operational status changes
    /// (e.g., idle → active, active → thinking, active → error).
    /// </summary>
    /// <param name="update">The full status update payload.</param>
    /// <returns>A Task that completes when the client has processed the update.</returns>
    Task AgentStatusChanged(AgentStatusUpdate update);

    /// <summary>
    /// Pushes a task progress update to all subscribed clients.
    /// Fired when an agent reports progress on its current task.
    /// </summary>
    /// <param name="progress">The task progress update payload.</param>
    /// <returns>A Task that completes when the client has processed the update.</returns>
    Task AgentTaskProgress(TaskProgressUpdate progress);
}