//! Per-agent + manager socket wire types (`/run/hive/mcp.sock`).
//!
//! The unified `Request` / `Response` protocol spoken between an agent's
//! in-container harness (and the manager) and the `hive-c0re` daemon over the
//! per-agent mcp socket. Re-homed out of `hive-sh4re` so this one socket owns
//! its own protocol crate, mirroring `hive-host-sock` / `hive-priv-sock`. The
//! shared payload types it references (`Message`, `LooseEnd`, `Approval`, …)
//! stay in `hive-sh4re`, which this crate depends on.

use hive_sh4re::{
    CancelLooseEndKind, ContainerInfo, DeliveredMessage, InboxRow, JournalPriority, LooseEnd,
    MatrixIdentity, ReminderStats, ReminderTiming, SchedulePromptPayload, WireSchedule,
};
use serde::{Deserialize, Serialize};

/// serde `default` helper for `Response::AgentMeta::running` (absent = true).
fn default_true() -> bool {
    true
}

/// Unified request enum for both agent and manager sockets. The agent's
/// identity is the socket it arrived on. Privileged variants are marked
/// `*(privileged)*` — an agent socket returns `Err` for them server-side.
///
/// `AgentRequest` and `ManagerRequest` are type aliases for this enum;
/// existing callers continue to compile unchanged.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "cmd", rename_all = "snake_case")]
pub enum Request {
    /// Send a message to another agent.
    Send {
        to: String,
        body: String,
        /// Optional id of the message being replied to. Stored in the
        /// broker DB and returned on `Recv` so the dashboard can render
        /// threads. Ignored if the id is unknown or out of retention.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        in_reply_to: Option<i64>,
    },
    /// Pop pending messages from this agent's inbox.
    /// Delivery + ack cycle: see
    /// `docs/conventions.md::Broker delivery + ack cycle`.
    Recv {
        #[serde(default)]
        wait_seconds: Option<u64>,
        #[serde(default)]
        max: Option<u32>,
    },
    /// Non-mutating: how many pending messages are addressed to me?
    /// Used by the harness to render a status line after each tool call.
    Status,
    /// Operator-injected message TO this agent (from this agent's own web
    /// UI). Recipient is implicit — `from` is `"operator"`. Effectively the
    /// per-agent equivalent of the old dashboard T4LK form, but scoped to
    /// the agent whose page the operator is on.
    OperatorMsg { body: String },
    /// Wake-up event injected from inside the container. Recipient is
    /// implicit (this agent); `from` is caller-chosen. See
    /// `docs/conventions.md::Wake injection` for the trust model and
    /// typical callers. The wake is persisted in the sqlite broker
    /// like any other message — the agent can ack it via `AckUntil`.
    Wake { from: String, body: String },
    /// Last `limit` messages addressed to this agent, newest-first.
    /// Non-mutating — pulls from the broker without delivering. The
    /// per-agent web UI uses this to render its own inbox section.
    Recent { limit: u64 },
    /// Surface a question to either the operator or another agent.
    /// Routing + shape: see
    /// `docs/conventions.md::Question routing (Ask / Answer)`.
    Ask {
        question: String,
        #[serde(default)]
        options: Vec<String>,
        #[serde(default)]
        multi: bool,
        #[serde(default)]
        ttl_seconds: Option<u64>,
        #[serde(default)]
        to: Option<String>,
    },
    /// Answer a question previously routed to this agent via
    /// `HelperEvent::QuestionAsked`. Authorised callers + threading
    /// back via `HelperEvent::QuestionAnswered`: see
    /// `docs/conventions.md::Question routing (Ask / Answer)`.
    Answer { id: i64, answer: String },
    /// Schedule a reminder message to be delivered to this agent at a
    /// future time. The reminder lands in the agent's inbox as an auto-sent
    /// message from `"reminder"`. Use for agent follow-ups (e.g. check task
    /// status, retry failed operation). Message length is limited; pass
    /// `file_path` to store in a file and get a path-reference message
    /// instead.
    Remind {
        message: String,
        timing: ReminderTiming,
        #[serde(default)]
        file_path: Option<String>,
    },
    /// Loose-ends view. On the agent socket: `None` = self; direct
    /// children are always accessible; non-children require the
    /// `query_agent_state` capability — rejected with an error otherwise;
    /// `"*"` is always rejected (use the manager socket). On the manager
    /// socket: `None` = manager self, `"*"` = hive-wide, any name =
    /// that agent. See `docs/conventions.md::Loose-ends wire shape`.
    GetLooseEnds {
        #[serde(default, skip_serializing_if = "Option::is_none")]
        agent: Option<String>,
    },
    /// Upsert a *todo* (loose-ends v2) from an in-container
    /// subsystem (matrix / forge / bash). `subsystem` is the producer
    /// marker; `key` is the optional subsystem-specific dedup key (a
    /// matrix room id, a bash task id). Re-pushing an identical keyed
    /// todo is a no-op; a new-or-changed one coalesces a wake to the
    /// agent. Keyless todos always insert as one-offs.
    UpsertTodo {
        subsystem: String,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        key: Option<String>,
        summary: String,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        source: Option<String>,
    },
    /// Clear producer-resolved todo(s) by `(subsystem, key)`. `key =
    /// Some(k)` clears the one keyed row; `key = None` clears **all** of
    /// the subsystem's keyless todos (rows with no key can't be told
    /// apart — clear a specific one via `MarkTodoDone` by id). `all =
    /// true` wipes the producer's whole set (cancel-and-recreate on
    /// daemon restart).
    ClearTodo {
        subsystem: String,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        key: Option<String>,
        #[serde(default)]
        all: bool,
    },
    /// List todos, optionally filtered to one `subsystem` (a producer
    /// enumerating its own set). `None` = all.
    ListTodos {
        #[serde(default, skip_serializing_if = "Option::is_none")]
        subsystem: Option<String>,
    },
    /// The agent marks one of its own todos done, by id.
    MarkTodoDone { id: i64 },
    /// Count of pending (un-delivered) reminders. On the agent socket:
    /// same target rules as `GetLooseEnds` (self/children free;
    /// non-children require `query_agent_state`; `"*"` rejected).
    /// On the manager socket: `None` = self, any name = that agent.
    /// Used by the harness's per-turn stats sink.
    CountPendingReminders {
        #[serde(default, skip_serializing_if = "Option::is_none")]
        agent: Option<String>,
    },
    /// Reminder statistics: counts of scheduled, delivered, and pending
    /// reminders over a time window. `since_secs` filters to reminders
    /// created in the last N seconds (0 = all). On the agent socket:
    /// same target rules as `GetLooseEnds` (self/children free;
    /// non-children require `query_agent_state`; `"*"` rejected).
    /// On the manager socket: `None` = self, any name = that agent.
    ReminderRollup {
        /// Only count reminders created in the last N seconds from now.
        /// Pass 0 to include all reminders.
        #[serde(default)]
        since_secs: u64,
        /// Whose reminders to roll up. `None` = the caller's own.
        /// `Some("<name>")` = that agent's (requires `query_agent_state`
        /// capability on the agent socket; always available on the manager
        /// socket).
        #[serde(default, skip_serializing_if = "Option::is_none")]
        agent: Option<String>,
    },
    /// Set a free-text status string visible on the dashboard. The harness
    /// writes `{state_dir}/hyperhive-status` locally before sending this
    /// request; hive-c0re just triggers a dashboard rescan on receipt.
    /// Pass an empty string to clear the status.
    SetStatus { text: String },
    /// Fetch identity + status for an agent. `name = None` =
    /// self-introspection; `Some(<agent>)` = target query. See
    /// `docs/conventions.md::Agent metadata`.
    GetAgentMeta {
        #[serde(default, skip_serializing_if = "Option::is_none")]
        name: Option<String>,
    },
    /// Cancel an open thread the agent owns. Authorisation +
    /// per-kind semantics in
    /// `docs/conventions.md::Loose-ends wire shape`.
    CancelLooseEnd { kind: CancelLooseEndKind, id: i64 },
    /// Create a git repo *through hive-c0re*. Agents can't create
    /// repos with their own forge token (`max_repo_creation = 0`); this is
    /// the sanctioned path. hive-c0re creates `repo` in the c0re-owned
    /// `agents` org, adds the calling agent as a write collaborator (not
    /// owner), and applies operator-team branch protection so the author
    /// can't merge its own PRs. Returns the new repo's full name.
    CreateRepo { repo: String },
    /// Mark every message popped since the last `AckTurn` as handled.
    /// Harness↔broker pairing fired after `TurnOutcome::Ok`. See
    /// `docs/conventions.md::Broker delivery + ack cycle`.
    AckTurn,
    /// Mark every inbox message with broker row id `<= up_to` as
    /// handled (`acked_at` set), whether still pending or already
    /// delivered. The agent-facing bulk-triage escape hatch for a
    /// redelivered / accumulated backlog: instead of popping and
    /// re-reading dozens of already-handled messages one turn at a
    /// time, the agent acks everything up to the id it has seen.
    /// Recipient-scoped — an agent can only ack its own rows. See
    /// `docs/conventions.md::Broker delivery + ack cycle`.
    AckUntil { up_to: i64 },
    /// Requeue every popped-but-unacked message back into the inbox.
    /// Harness fires this once at boot to recover from
    /// crashed-mid-turn sessions. See
    /// `docs/conventions.md::Broker delivery + ack cycle`.
    RequeueInflight,
    /// Harness → c0re: "I saw the `GracefulStop` signal, ran my
    /// stop-checkpoint turn (durable `/state` flushed) and am exiting my
    /// serve loop now." Lets the `GracefulStop` orchestration stop the
    /// container immediately instead of waiting out its timeout fallback.
    GracefulStopComplete,
    /// *(capability-gated: `read_host_journal`)* Fetch recent lines
    /// from the host journal. Filters are all optional; omitting all
    /// returns the last `lines` entries from the global journal.
    GetHostJournal {
        /// Filter to a specific systemd unit (e.g. `hive-c0re.service`).
        #[serde(default, skip_serializing_if = "Option::is_none")]
        unit: Option<String>,
        /// Machine name to pass to journalctl `-M` verbatim (e.g. `h-iris`).
        /// The caller is responsible for the correct nspawn machine name.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        container: Option<String>,
        /// Number of journal lines to return (default 30, max 100).
        #[serde(default, skip_serializing_if = "Option::is_none")]
        lines: Option<u32>,
        /// Minimum syslog priority level.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        priority: Option<JournalPriority>,
        /// Regex to match against log message fields (journalctl `--grep`).
        #[serde(default, skip_serializing_if = "Option::is_none")]
        grep: Option<String>,
        /// Show entries on or newer than this timestamp (journalctl `--since`).
        /// ISO 8601 or journalctl-accepted relative strings (e.g. `"-1h"`).
        #[serde(default, skip_serializing_if = "Option::is_none")]
        since: Option<String>,
        /// Show entries on or older than this timestamp (journalctl `--until`).
        #[serde(default, skip_serializing_if = "Option::is_none")]
        until: Option<String>,
    },

    // ---- privileged (manager socket only for now) ---------------------------
    /// *(privileged)* Initialise a brand-new agent's proposed config repo
    /// and queue an approval for the operator to review.
    RequestInitConfig {
        name: String,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        description: Option<String>,
    },
    /// *(privileged)* Stop a sub-agent (graceful).
    Kill { name: String },
    /// *(privileged)* Start a previously-stopped sub-agent container.
    Start { name: String },
    /// *(privileged)* Restart a sub-agent container (stop + start).
    Restart { name: String },
    /// *(privileged)* Rebuild a sub-agent against the current hyperhive
    /// flake + agent.nix. No approval required.
    Update { name: String },
    /// *(privileged)* Fetch recent journal lines for a sub-agent container.
    GetLogs {
        agent: String,
        #[serde(default)]
        lines: Option<u32>,
    },
    /// *(privileged)* Queue an approval to run `nix flake update [inputs...]`.
    RequestUpdateMetaInputs {
        #[serde(default)]
        inputs: Vec<String>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        description: Option<String>,
    },
    /// *(privileged)* Queue an approval to add a scheduled prompt.
    RequestSchedulePrompt(SchedulePromptPayload),
    /// *(privileged)* Cancel a scheduled prompt.
    CancelSchedule {
        id: i64,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        targets: Option<Vec<String>>,
    },
    /// *(privileged)* List every schedule in the queue.
    ListSchedules,
    /// List all containers that are topological descendants of the calling
    /// agent (direct children + their subtrees). Scoped to the caller's
    /// subtree; gated by the `lifecycle` tool group. The result includes all
    /// known descendants regardless of whether the container is currently
    /// running — use `running` to distinguish.
    ListDescendants,
    /// *(privileged)* Fire a scheduled prompt out of band immediately.
    FireScheduleNow { id: i64 },
    /// *(privileged)* Edit an existing schedule's mutable fields.
    EditSchedule {
        id: i64,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        body: Option<String>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        description: Option<Option<String>>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        interval_seconds: Option<Option<u64>>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        next_fire_at_unix: Option<i64>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        targets_add: Option<Vec<String>>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        targets_remove: Option<Vec<String>>,
    },
}

/// Backwards-compatible aliases. Both sockets now speak the unified `Request`
/// / `Response` wire; the server-side privilege gate rejects privileged
/// variants on agent sockets with `Err { message: "privileged variant..." }`.
pub type AgentRequest = Request;
pub type ManagerRequest = Request;

/// Unified response enum for both agent and manager sockets. Privileged
/// variants (`Logs`, `Schedules`) are never returned on agent sockets.
///
/// `AgentResponse` and `ManagerResponse` are type aliases for this enum.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum Response {
    /// `Send` succeeded.
    Ok,
    /// Either `Send` failed or `Recv` errored.
    Err { message: String },
    /// `Recv` result: zero or more messages, FIFO-ordered, never
    /// longer than the `max` the caller passed. Empty vec = nothing
    /// pending (the "(empty)" path for the formatter). Per-row `id` +
    /// `redelivered` carry the broker's row id (tracked by the harness
    /// for `AckTurn`, and surfaced to claude as a `[msg #<id>]` marker
    /// so `AckUntil` has something to reference) and the "previously
    /// popped, not acked" flag — see `DeliveredMessage` for details.
    /// `remaining` is the inbox depth *after* this batch was popped —
    /// how many still-pending messages the caller could drain next. The
    /// harness surfaces it to claude ("N more pending") so an in-turn
    /// `recv` learns whether the inbox is drained, mirroring the count
    /// the wake prompt already carries.
    Messages {
        messages: Vec<DeliveredMessage>,
        remaining: u64,
    },
    /// `Status` result: how many pending messages are in this agent's inbox.
    Status { unread: u64 },
    /// `AckUntil` result: how many rows were newly marked handled.
    Acked { count: u64 },
    /// `Recent` result: newest-first inbox rows.
    Recent { rows: Vec<InboxRow> },
    /// `Ask` result: the queued question id. The answer lands later
    /// as `HelperEvent::QuestionAnswered` in this agent's inbox.
    QuestionQueued { id: i64 },
    /// `GetLooseEnds` result: list of loose ends pending against
    /// this agent. Ordered newest-first within each kind.
    LooseEnds { loose_ends: Vec<LooseEnd> },
    /// `CountPendingReminders` result.
    PendingRemindersCount { count: u64 },
    /// `ReminderRollup` result: reminder activity stats for the agent.
    ReminderRollup(ReminderStats),
    /// `GetAgentMeta` result. Per-field semantics + serde defaults
    /// live in `docs/conventions.md::Agent metadata`.
    AgentMeta {
        name: String,
        #[serde(default = "default_true")]
        running: bool,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        hyperhive_rev: Option<String>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        status_text: Option<String>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        status_set_at: Option<i64>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        hive_name: Option<String>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        swarm_name: Option<String>,
        /// Matrix identities this agent can act as (one per configured +
        /// live account). Empty for agents with no matrix provisioning.
        #[serde(default, skip_serializing_if = "Vec::is_empty")]
        matrix_accounts: Vec<MatrixIdentity>,
    },
    /// `GetLogs` result: journal lines for the requested container.
    /// Returned on the manager socket only.
    Logs { content: String },
    /// `GetHostJournal` result: host journal lines matching the
    /// requested filters. Returned on the agent socket when the agent
    /// holds the `read_host_journal` capability.
    HostJournal { content: String },
    /// `ListSchedules` result. Snapshot of every schedule.
    /// Returned on the manager socket only.
    Schedules { schedules: Vec<WireSchedule> },
    /// `CreateRepo` result: the new repo's full name (`agents/<repo>`)
    /// and clone URL, so the agent can immediately `git clone` it.
    RepoCreated {
        full_name: String,
        clone_url: String,
    },
    /// `ListDescendants` result: all descendant containers, with running
    /// status. Ordered by topology depth (parents before children), then
    /// alphabetically within each depth tier.
    Containers { containers: Vec<ContainerInfo> },
    /// `Recv` result when a graceful stop is pending for this agent
    /// (set by hive-c0re's `GracefulStop` orchestration). Returned in
    /// place of `Messages` — it doubles as the inbound fence: the harness
    /// stops consuming normal inbox messages and instead runs one
    /// stop-checkpoint turn (flush durable `/state`), then reports
    /// `GracefulStopComplete` and exits its serve loop so the container
    /// can be stopped cleanly. New sends keep queueing in the broker for
    /// the agent's next start.
    GracefulStop,
}

/// Backwards-compatible response aliases.
pub type AgentResponse = Response;
pub type ManagerResponse = Response;