sprints work

src/Signals/StellaOps.Signals.RuntimeAgent/IAgentRegistrationService.cs

@@ -0,0 +1,81 @@
+// <copyright file="IAgentRegistrationService.cs" company="StellaOps">
+// Copyright (c) StellaOps. Licensed under the AGPL-3.0-or-later.
+// </copyright>
+
+namespace StellaOps.Signals.RuntimeAgent;
+
+/// <summary>
+/// Service for managing runtime agent registrations.
+/// Sprint: SPRINT_20260109_009_004 Task: Implement AgentRegistrationService
+/// </summary>
+public interface IAgentRegistrationService
+{
+    /// <summary>
+    /// Register a new agent.
+    /// </summary>
+    /// <param name="request">Registration request.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>The registration record.</returns>
+    Task<AgentRegistration> RegisterAsync(AgentRegistrationRequest request, CancellationToken ct = default);
+
+    /// <summary>
+    /// Process agent heartbeat.
+    /// </summary>
+    /// <param name="request">Heartbeat request.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Response with commands.</returns>
+    Task<AgentHeartbeatResponse> HeartbeatAsync(AgentHeartbeatRequest request, CancellationToken ct = default);
+
+    /// <summary>
+    /// Unregister an agent.
+    /// </summary>
+    /// <param name="agentId">Agent identifier.</param>
+    /// <param name="ct">Cancellation token.</param>
+    Task UnregisterAsync(string agentId, CancellationToken ct = default);
+
+    /// <summary>
+    /// Get registration by agent ID.
+    /// </summary>
+    /// <param name="agentId">Agent identifier.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Registration or null if not found.</returns>
+    Task<AgentRegistration?> GetAsync(string agentId, CancellationToken ct = default);
+
+    /// <summary>
+    /// List all registered agents.
+    /// </summary>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>All registrations.</returns>
+    Task<IReadOnlyList<AgentRegistration>> ListAsync(CancellationToken ct = default);
+
+    /// <summary>
+    /// List agents by platform.
+    /// </summary>
+    /// <param name="platform">Platform filter.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Matching registrations.</returns>
+    Task<IReadOnlyList<AgentRegistration>> ListByPlatformAsync(RuntimePlatform platform, CancellationToken ct = default);
+
+    /// <summary>
+    /// List healthy agents (recent heartbeat).
+    /// </summary>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Healthy registrations.</returns>
+    Task<IReadOnlyList<AgentRegistration>> ListHealthyAsync(CancellationToken ct = default);
+
+    /// <summary>
+    /// Send command to an agent.
+    /// </summary>
+    /// <param name="agentId">Agent identifier.</param>
+    /// <param name="command">Command to send.</param>
+    /// <param name="ct">Cancellation token.</param>
+    Task SendCommandAsync(string agentId, AgentCommand command, CancellationToken ct = default);
+
+    /// <summary>
+    /// Update agent posture.
+    /// </summary>
+    /// <param name="agentId">Agent identifier.</param>
+    /// <param name="posture">New posture.</param>
+    /// <param name="ct">Cancellation token.</param>
+    Task UpdatePostureAsync(string agentId, RuntimePosture posture, CancellationToken ct = default);
+}