// <copyright file="IAgentRegistrationService.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under the BUSL-1.1.
// </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);
}