package ai.intelliswarm.swarmai.state.reminder;

import java.time.Instant;
import java.util.Objects;
import java.util.UUID;

/**
 * A short, harness-authored note to be spliced into the agent's input stream
 * inside a {@code <system-reminder>} tag. Distinct from user input and tool
 * output: reminders carry runtime context the agent should be aware of but
 * that didn't come from the user (e.g. "drift budget at 4/5", "you have 2
 * in-progress tasks", "available skills updated").
 *
 * <p>Posted to a {@link SystemReminderChannel} by harness components and
 * consumed (drained) by whatever assembles the next LLM prompt.
 *
 * <p>Reminders are append-only, immutable, and identified by an autogenerated
 * id so listeners and renderers can deduplicate by reference.
 *
 * @param id        autogenerated UUID — never null
 * @param source    short label identifying the producer, e.g. {@code "task-list"},
 *                  {@code "drift-budget"}, {@code "replanner"}; never null
 * @param message   the reminder text shown to the agent; never null or blank
 * @param severity  {@link Severity#INFO} (default) or {@link Severity#WARN}
 * @param postedAt  wall-clock instant the reminder was created; never null
 */
public record SystemReminder(
        String id,
        String source,
        String message,
        Severity severity,
        Instant postedAt) {

    public SystemReminder {
        Objects.requireNonNull(id, "id");
        Objects.requireNonNull(source, "source");
        Objects.requireNonNull(message, "message");
        if (source.isBlank()) {
            throw new IllegalArgumentException("source must not be blank");
        }
        if (message.isBlank()) {
            throw new IllegalArgumentException("message must not be blank");
        }
        if (severity == null) severity = Severity.INFO;
        if (postedAt == null) postedAt = Instant.now();
    }

    /** Severity of the reminder — controls how the renderer tags it. */
    public enum Severity { INFO, WARN }

    /** Convenience: create an INFO reminder with autogenerated id and now timestamp. */
    public static SystemReminder info(String source, String message) {
        return new SystemReminder(UUID.randomUUID().toString(), source, message,
                Severity.INFO, Instant.now());
    }

    /** Convenience: create a WARN reminder. */
    public static SystemReminder warn(String source, String message) {
        return new SystemReminder(UUID.randomUUID().toString(), source, message,
                Severity.WARN, Instant.now());
    }
}
