feat(CUB-55): add SendStatusUpdate method to AgentStatusHub

backend/ControlCenter/Hubs/Models/AgentStatusModels.cs

@@ -72,6 +72,80 @@ public record TaskProgressUpdate(
     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.