using ControlCenter.Models;

namespace ControlCenter.Repositories;

/// <summary>
/// Repository interface for querying and updating agent state.
///
/// <para>Provides the data-access contract used by controllers,
/// background services, and SignalR hubs to read and mutate
/// persistent agent state.</para>
///
/// <para>Implementation should use <see cref="Data.ControlCenterDbContext"/>
/// via EF Core with PostgreSQL (snake_case columns).</para>
/// </summary>
public interface IAgentStateRepository
{
    /// <summary>
    /// Returns all agent states from the database.
    /// </summary>
    /// <returns>A collection of all <see cref="AgentState"/> records.</returns>
    Task<IEnumerable<AgentState>> GetAllAsync();

    /// <summary>
    /// Finds an agent state by its session key.
    /// </summary>
    /// <param name="sessionKey">The full session key, e.g. "agent:dex:telegram:direct:...".</param>
    /// <returns>The matching <see cref="AgentState"/>, or null if not found.</returns>
    Task<AgentState?> GetBySessionKeyAsync(string sessionKey);

    /// <summary>
    /// Updates the status of an agent state record.
    /// Also updates <c>LastActivity</c> to <see cref="DateTime.UtcNow"/>.
    /// </summary>
    /// <param name="id">The unique identifier of the agent state record.</param>
    /// <param name="status">The new status value ("active", "idle", "thinking", "error").</param>
    /// <returns>The updated <see cref="AgentState"/>, or null if the record was not found.</returns>
    Task<AgentState?> UpdateStatusAsync(Guid id, string status);
}