Merge pull request 'CUB-55: Add SendStatusUpdate method to AgentStatusHub' (#25) from agent/dex/CUB-55-signalr-broadcast into dev

Reviewed-on: #25

backend/ControlCenter/Hubs/AgentStatusHub.cs

@@ -37,6 +37,33 @@ public class AgentStatusHub : Hub<IAgentStatusClient>
         _logger = logger;
     }
 
+    /// <summary>
+    /// Broadcasts an agent status update to all connected clients.
+    ///
+    /// <para>
+    /// Any connected client (or server-side caller) can invoke this method
+    /// to push a status update to every subscriber. The DTO is converted to
+    /// an <see cref="AgentStatusUpdate"/> record and relayed through the
+    /// <see cref="IAgentStatusClient.AgentStatusChanged"/> callback.
+    /// </para>
+    /// </summary>
+    /// <param name="update">The agent status update DTO to broadcast.</param>
+    public async Task SendStatusUpdate(AgentStatusUpdateDto update)
+    {
+        _logger.LogInformation(
+            "Broadcasting status update for agent {AgentId}: {Status}",
+            update.AgentId, update.Status);
+
+        var agentUpdate = update.ToUpdate();
+
+        // Broadcast to all connected clients
+        await Clients.All.AgentStatusChanged(agentUpdate);
+
+        // Also push to the specific agent's group
+        var agentGroup = AgentGroupName(update.AgentId);
+        await Clients.Group(agentGroup).AgentStatusChanged(agentUpdate);
+    }
+
     /// <summary>
     /// Adds the calling connection to the fleet group.
     /// Once joined, the client will receive all agent status changes

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.