basemind 0.29.1

//! Request / response shapes for the consolidated `agents` domain tool.
//!
//! [`AgentsParams`] is what crosses the wire: one flat parameter object with a required
//! [`AgentsMode`] selecting the operation and every per-mode field an optional sibling. The
//! per-operation structs below (`ThreadPostParams`, `InboxReadParams`, …) stay as the helpers'
//! internal shapes, so the bodies keep taking exactly the arguments they always did.
//!
//! Parameter structs derive `Deserialize + Serialize + JsonSchema` and use the validated
//! [`ThreadId`](crate::comms::ids::ThreadId) / [`AgentId`](crate::comms::ids::AgentId) newtypes
//! for identifier fields so a malformed id is rejected at the serde boundary rather than reaching
//! the broker. Response structs serialize the broker's [`MessageMeta`] front-matter directly —
//! modes `history` and `inbox` return front-matter ONLY; bodies come from mode `message`.

#![cfg(all(feature = "comms", any(unix, windows)))]

use serde::{Deserialize, Serialize};

use super::mode::AgentsMode;
use crate::comms::cursor::Cursor;
use crate::comms::ids::{AgentId, ThreadId};
use crate::comms::model::{AgentRecord, Thread};
use crate::comms::protocol::SeqMeta;

/// Wire parameters for the `agents` tool.
///
/// Only `mode` is required. Every other field belongs to one or more modes and is rejected — not
/// ignored — when passed to a mode that has no use for it (see
/// [`super::mode::reject_unsupported`]); a mode that cannot run without one names the exact
/// `mode`/field pair. `as_agent` is the single exception: every mode accepts it, because it selects
/// the identity the call runs as rather than what the call does.
#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
pub struct AgentsParams {
    /// Which operation to run.
    pub mode: AgentsMode,
    /// Thread to act on (required by join/leave/members/add_member/remove_member/archive/post/history; optional filter for list/ack/wait).
    #[serde(default)]
    pub thread: Option<ThreadId>,
    /// Agent id for add_member / remove_member.
    #[serde(default)]
    pub member: Option<AgentId>,
    /// `thread_start`: extra member agent ids (you are added automatically).
    #[serde(default)]
    pub members: Option<Vec<AgentId>>,
    /// `message`: id of the front-matter row whose body to read.
    #[serde(default, alias = "id")]
    pub message_id: Option<String>,
    /// `ack`: message ids to acknowledge.
    #[serde(default)]
    pub message_ids: Option<Vec<String>>,
    /// `ack`: advance `thread`'s read cursor to this seq.
    #[serde(default)]
    pub to_seq: Option<u64>,
    /// `thread_start`: topic. `post`: subject line (required).
    #[serde(default)]
    pub subject: Option<String>,
    /// `thread_list`: case-sensitive subject substring filter.
    #[serde(default)]
    pub subject_contains: Option<String>,
    /// `thread_start`: path or glob (e.g. `src/**`).
    #[serde(default)]
    pub path: Option<String>,
    /// `post`: markdown body. Omit for a subject-only post; empty or whitespace-only is refused.
    #[serde(default)]
    pub body: Option<String>,
    /// `post`: free-form tags.
    #[serde(default)]
    pub tags: Option<Vec<String>>,
    /// `post`: id of the message replied to.
    #[serde(default)]
    pub reply_to: Option<String>,
    /// `post`: caller-chosen key making a retried post return the original message id instead of
    /// storing a duplicate. Generated when omitted.
    #[serde(default)]
    pub idempotency_key: Option<String>,
    /// `thread_list`: include archived threads.
    #[serde(default)]
    pub include_archived: Option<bool>,
    /// `inbox`: advance read cursors past the returned messages.
    #[serde(default)]
    pub mark_read: Option<bool>,
    /// Resume token from the previous `next_cursor` (history, inbox, wait).
    #[serde(default)]
    pub cursor: Option<String>,
    /// Page size for history / inbox (default 100, max 1000).
    #[serde(default)]
    pub limit: Option<u32>,
    /// history / inbox / wait: look back N hours (default 24; 0 = all).
    #[serde(default)]
    pub since_hours: Option<u32>,
    /// `wait` only. Seconds to block before returning `timed_out: true`. Default 30, max 40.
    #[serde(default)]
    pub timeout_secs: Option<u32>,
    /// `register`: agent name.
    #[serde(default)]
    pub name: Option<String>,
    /// `register`: one-line purpose.
    #[serde(default)]
    pub description: Option<String>,
    /// `register`: version string.
    #[serde(default)]
    pub version: Option<String>,
    /// `register`: skill labels.
    #[serde(default)]
    pub skills: Option<Vec<String>>,
    /// `cleanup`: must be omitted or false over MCP (preview only).
    #[serde(default)]
    pub apply: Option<bool>,
    /// `cleanup`: message retention window override.
    #[serde(default)]
    pub message_ttl_hours: Option<u32>,
    /// `cleanup`: idle-thread archive window override.
    #[serde(default)]
    pub thread_idle_hours: Option<u32>,
    /// `cleanup`: archived-thread purge window override.
    #[serde(default)]
    pub thread_retention_hours: Option<u32>,
    /// `cleanup` / `status`: stale-agent window override.
    #[serde(default)]
    pub agent_ttl_hours: Option<u32>,
    /// `cleanup`: stale identity-claim window override.
    #[serde(default)]
    pub claim_ttl_hours: Option<u32>,
    /// Sub-identity to act as (any mode); defaults to this server's agent.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// Params for mode `register`: announce or update this agent's A2A card.
#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
pub struct AgentRegisterParams {
    /// Human-readable agent name.
    #[serde(default)]
    pub name: String,
    /// One-line description of the agent's purpose.
    #[serde(default)]
    pub description: String,
    /// Agent version string (e.g. "1.0.0").
    #[serde(default)]
    pub version: String,
    /// Optional skill labels advertised to peers.
    #[serde(default)]
    pub skills: Vec<String>,
    /// Optional sub-identity to act as; defaults to the server's own agent. Lets one orchestrator
    /// drive many named subagents.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// Response for mode `register`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct AgentRegisterResponse {
    /// The agent id the card was registered under.
    pub agent_id: String,
    /// Always true on success.
    pub registered: bool,
}

/// Params for mode `list`: enumerate known agents, optionally restricted to one thread.
#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
pub struct AgentListParams {
    /// Restrict to members of this thread when set.
    #[serde(default)]
    pub thread: Option<ThreadId>,
    /// Optional sub-identity to act as; defaults to the server's own agent. Lets one orchestrator
    /// drive many named subagents.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// One agent row in a mode `list` response (front-matter view of an `AgentRecord`).
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct AgentSummary {
    /// Stable agent identity.
    pub agent_id: String,
    /// Self-described name.
    pub name: String,
    /// Self-described description.
    pub description: String,
    /// Self-described version.
    pub version: String,
    /// Advertised skill labels.
    pub skills: Vec<String>,
    /// First-seen time, microseconds since the unix epoch.
    pub first_seen: i64,
    /// Last-seen time, microseconds since the unix epoch.
    pub last_seen: i64,
}

impl AgentSummary {
    /// Build the front-matter row for one registered agent.
    pub(crate) fn from_record(record: &AgentRecord) -> Self {
        Self {
            agent_id: record.agent_id.as_str().to_string(),
            name: record.card.name.clone(),
            description: record.card.description.clone(),
            version: record.card.version.clone(),
            skills: record.card.skills.clone(),
            first_seen: record.first_seen,
            last_seen: record.last_seen,
        }
    }
}

/// Response for mode `list`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct AgentListResponse {
    /// Number of agents returned.
    pub total: usize,
    /// The agent rows.
    pub agents: Vec<AgentSummary>,
}

/// A thread front-matter view shared by modes `thread_start` and `thread_list`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct ThreadSummary {
    /// Stable thread id.
    pub id: String,
    /// Topic string, when addressed by subject.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub subject: Option<String>,
    /// Path or GLOB pattern, when addressed by path.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
    /// The member agent ids.
    pub members: Vec<String>,
    /// The creating agent.
    pub creator: String,
    /// True while active; false once archived.
    pub active: bool,
    /// Creation time, microseconds since the unix epoch.
    pub created_at: i64,
    /// Last-activity time, microseconds since the unix epoch. `0` when the thread has no posts.
    pub last_activity_micros: i64,
    /// True when the thread is STALE: never had a post, or its last post is older than 7 days.
    pub stale: bool,
}

/// The staleness window for a thread, in hours. 168h = 7 days.
pub(crate) const STALE_AFTER_HOURS: i64 = 168;

impl ThreadSummary {
    /// Build a thread summary, computing `stale` against `now_micros`.
    pub(crate) fn from_thread(thread: &Thread, now_micros: i64) -> Self {
        let last = thread.last_activity;
        let window_micros = STALE_AFTER_HOURS * 3_600_000_000;
        let stale = last == 0 || (now_micros - last) > window_micros;
        Self {
            id: thread.id.as_str().to_string(),
            subject: thread.subject.clone(),
            path: thread.path.clone(),
            members: thread.members.iter().map(|m| m.as_str().to_string()).collect(),
            creator: thread.creator.as_str().to_string(),
            active: thread.active,
            created_at: thread.created_at,
            last_activity_micros: last,
            stale,
        }
    }
}

/// Params for mode `thread_start`: open a conversation addressed by AT LEAST TWO of `subject` /
/// `path` / `members`. Fewer than two is rejected. The caller becomes the creator + a member.
#[derive(Debug, Clone, Default, Deserialize, Serialize, schemars::JsonSchema)]
pub struct ThreadStartParams {
    /// Topic string.
    #[serde(default)]
    pub subject: Option<String>,
    /// A path or GLOB pattern (globset syntax, e.g. `src/**`) for path-based discovery.
    #[serde(default)]
    pub path: Option<String>,
    /// Explicit additional member agent ids (the caller is added automatically).
    #[serde(default)]
    pub members: Vec<AgentId>,
    /// Optional sub-identity to act as; defaults to the server's own agent.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// Response for mode `thread_start`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct ThreadStartResponse {
    /// The created thread.
    pub thread: ThreadSummary,
}

/// Params for mode `thread_list`: list threads DISCOVERABLE to this agent. No global listing — a
/// thread surfaces only when the caller is a member, its cwd matches the thread's path glob, or
/// `subject_contains` matches. Scope context (remote + cwd) is injected by the server.
#[derive(Debug, Clone, Default, Deserialize, Serialize, schemars::JsonSchema)]
pub struct ThreadListParams {
    /// Optional case-sensitive substring filter over thread subjects.
    #[serde(default)]
    pub subject_contains: Option<String>,
    /// When true, also return archived threads.
    #[serde(default)]
    pub include_archived: bool,
    /// Optional sub-identity to act as; defaults to the server's own agent.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// Response for mode `thread_list`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct ThreadListResponse {
    /// Number of threads returned.
    pub total: usize,
    /// The thread rows.
    pub threads: Vec<ThreadSummary>,
}

/// Params for mode `join`.
#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
pub struct ThreadJoinParams {
    /// The thread to join.
    pub thread: ThreadId,
    /// Optional sub-identity to act as; defaults to the server's own agent.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// Params for mode `leave`.
#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
pub struct ThreadLeaveParams {
    /// The thread to leave.
    pub thread: ThreadId,
    /// Optional sub-identity to act as; defaults to the server's own agent.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// Response for modes `join` / `leave`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct ThreadMembershipResponse {
    /// The thread acted on.
    pub thread: String,
    /// True after a successful join.
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    pub joined: bool,
    /// True after a successful leave.
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    pub left: bool,
}

/// Params for mode `members`.
#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
pub struct ThreadMembersParams {
    /// The thread whose members to list.
    pub thread: ThreadId,
    /// Optional sub-identity to act as; defaults to the server's own agent.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// Response for mode `members`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct ThreadMembersResponse {
    /// The thread queried.
    pub thread: String,
    /// The member agent ids.
    pub members: Vec<String>,
}

/// Params for modes `add_member` / `remove_member` (creator only).
#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
pub struct ThreadMemberParams {
    /// The thread to modify.
    pub thread: ThreadId,
    /// The member agent id to add / remove.
    pub member: AgentId,
    /// Optional sub-identity to act as; defaults to the server's own agent.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// Response for modes `add_member` / `remove_member`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct ThreadMemberChangeResponse {
    /// The thread acted on.
    pub thread: String,
    /// The member agent id.
    pub member: String,
    /// True after a successful add.
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    pub added: bool,
    /// True after a successful remove.
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    pub removed: bool,
}

/// Params for mode `archive` (creator only).
#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
pub struct ThreadArchiveParams {
    /// The thread to archive.
    pub thread: ThreadId,
    /// Optional sub-identity to act as; defaults to the server's own agent.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// Response for mode `archive`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct ThreadArchiveResponse {
    /// The thread archived.
    pub thread: String,
    /// Always true on success.
    pub archived: bool,
}

/// Params for mode `post`.
#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
pub struct ThreadPostParams {
    /// Target thread.
    pub thread: ThreadId,
    /// Short human subject line.
    pub subject: String,
    /// Message body (markdown). Empty when omitted.
    #[serde(default)]
    pub body: Option<String>,
    /// Free-form tags for filtering.
    #[serde(default)]
    pub tags: Option<Vec<String>>,
    /// Id of the message this one replies to, for threading.
    #[serde(default)]
    pub reply_to: Option<String>,
    /// Retry key: a repeat with the same key returns the original message id. Generated when omitted.
    #[serde(default)]
    pub idempotency_key: Option<String>,
    /// Optional sub-identity to act as; defaults to the server's own agent.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// Response for mode `post`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct ThreadPostResponse {
    /// The id of the message just stored.
    pub message_id: String,
}

/// Params for mode `history`: read a thread's front-matter, oldest-first, paginated.
#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
pub struct ThreadHistoryParams {
    /// The thread to read.
    pub thread: ThreadId,
    /// Resume token from a previous page's `next_cursor` (opaque string).
    #[serde(default)]
    pub cursor: Option<String>,
    /// Maximum messages to return (default 100, max 1000).
    #[serde(default)]
    pub limit: Option<u32>,
    /// Only return messages from the last N hours; defaults to 24. Pass 0 for ALL history.
    #[serde(default)]
    pub since_hours: Option<u32>,
    /// Optional sub-identity to act as; defaults to the server's own agent.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// Front-matter view of a message. Surfaces [`MessageMeta`] front-matter plus its per-thread
/// `seq` — NO body. Fetch the body with mode `message`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct MessageFrontMatter {
    /// Compact message reference (preferred for mode `message`, mode `ack`, and `reply_to`).
    pub message_ref: String,
    /// Globally unique legacy message id (accepted for backward compatibility).
    pub id: String,
    /// Thread the message was posted to.
    pub thread: String,
    /// Authoring agent.
    pub from: String,
    /// Short human subject line.
    pub subject: String,
    /// Post time, microseconds since the unix epoch.
    pub ts_micros: i64,
    /// Age of the message in whole seconds at read time (`now - ts`, floored at 0).
    pub age_secs: i64,
    /// Free-form tags.
    pub tags: Vec<String>,
    /// Id of the message this one replies to, if any.
    pub reply_to: Option<String>,
    /// Per-thread sequence number — pass as mode `ack`'s `to_seq` to bulk-ack up to here.
    pub seq: u64,
    /// Length of the separately-stored body in bytes.
    pub body_len: u32,
    /// Hex SHA-256 of the body for integrity.
    pub body_sha: String,
}

impl MessageFrontMatter {
    /// Build a front-matter row from a [`SeqMeta`], stamping `age_secs` against `now_micros`.
    pub(crate) fn from_seq_meta(sm: &SeqMeta, now_micros: i64) -> Self {
        let meta = &sm.meta;
        Self {
            message_ref: crate::comms::model::message_reference(&meta.id),
            id: meta.id.clone(),
            thread: meta.thread.as_str().to_string(),
            from: meta.from.as_str().to_string(),
            subject: meta.subject.clone(),
            ts_micros: meta.ts_micros,
            age_secs: ((now_micros - meta.ts_micros) / 1_000_000).max(0),
            tags: meta.tags.clone(),
            reply_to: meta.reply_to.clone(),
            seq: sm.seq,
            body_len: meta.body_len,
            body_sha: meta.body_sha.clone(),
        }
    }
}

/// Response for mode `history`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct ThreadHistoryResponse {
    /// Number of messages in this page.
    pub total: usize,
    /// Front-matter rows, oldest-first.
    pub messages: Vec<MessageFrontMatter>,
    /// Opaque cursor for the next page; absent means no more results.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub next_cursor: Option<Cursor>,
}

/// Params for mode `message`: fetch a single message body by id.
#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
pub struct MessageGetParams {
    /// Compact `message_ref` (preferred) or legacy `id` from a front-matter record.
    pub message_id: String,
    /// Optional sub-identity to act as; defaults to the server's own agent.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// Response for mode `message`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct MessageGetResponse {
    /// The message id queried.
    pub message_id: String,
    /// True when a body was found for the id.
    pub found: bool,
    /// The body decoded as UTF-8 (lossy — bodies are markdown). `None` when the id is unknown.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub body: Option<String>,
}

/// Params for mode `inbox`: read new front-matter across JOINED threads.
#[derive(Debug, Clone, Default, Deserialize, Serialize, schemars::JsonSchema)]
pub struct InboxReadParams {
    /// Resume token from a previous page's `next_cursor` (opaque string).
    #[serde(default)]
    pub cursor: Option<String>,
    /// Maximum messages to return (default 100, max 1000).
    #[serde(default)]
    pub limit: Option<u32>,
    /// When true, advance read cursors past the returned messages.
    #[serde(default)]
    pub mark_read: bool,
    /// Only return messages from the last N hours; defaults to 24. Pass 0 for ALL history.
    #[serde(default)]
    pub since_hours: Option<u32>,
    /// Optional sub-identity to act as; defaults to the server's own agent.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// Response for mode `inbox`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct InboxReadResponse {
    /// Number of messages in this page.
    pub total: usize,
    /// Count of unread messages remaining after this page.
    pub unread: u32,
    /// Front-matter rows across joined threads.
    pub messages: Vec<MessageFrontMatter>,
    /// Opaque cursor for the next page; absent means no more results.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub next_cursor: Option<Cursor>,
}

/// Params for mode `ack`: advance this agent's per-thread read cursors past acked messages.
///
/// Two modes, combinable:
/// * `message_ids` — resolve each id to its `(thread, seq)`, then advance each thread's cursor.
/// * `thread` + `to_seq` — advance that one thread's cursor straight to `to_seq`.
///
/// At least one mode must be supplied; an empty request is rejected.
#[derive(Debug, Clone, Default, Deserialize, Serialize, schemars::JsonSchema)]
pub struct InboxAckParams {
    /// Message ids to ack (mode a).
    #[serde(default)]
    pub message_ids: Vec<String>,
    /// Target thread for the bulk `to_seq` mode (mode b).
    #[serde(default)]
    pub thread: Option<ThreadId>,
    /// Advance `thread`'s cursor straight to this seq (mode b). Requires `thread`.
    #[serde(default)]
    pub to_seq: Option<u64>,
    /// Optional sub-identity to act as; defaults to the server's own agent.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// One `(thread, new_seq)` cursor advance recorded by mode `ack`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct CursorAdvance {
    /// The thread whose per-agent read cursor advanced.
    pub thread: String,
    /// The cursor's new seq after the advance.
    pub seq: u64,
}

/// Response for mode `ack`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct InboxAckResponse {
    /// Number of message ids that resolved and were acked.
    pub acked: usize,
    /// The `(thread, new_seq)` cursor advances this call produced.
    pub cursors_advanced: Vec<CursorAdvance>,
}

/// Params for mode `wait`: block until a peer posts to a joined thread (or the one thread named
/// in `thread`), or until `timeout_secs` elapses. NEVER marks read — there is no `mark_read`
/// param; follow up with `inbox_read(mark_read: true)` or mode `ack` once you've handled the
/// page. A long-poll replacement for a caller looping mode `inbox` / mode `thread_list`.
#[derive(Debug, Clone, Default, Deserialize, Serialize, schemars::JsonSchema)]
pub struct InboxWaitParams {
    /// Maximum seconds to block before returning `timed_out: true` (default 30, max 40).
    #[serde(default)]
    pub timeout_secs: Option<u32>,
    /// Restrict the wake to this thread only. `None` wakes on ANY joined thread.
    #[serde(default)]
    pub thread: Option<ThreadId>,
    /// Only consider messages from the last N hours; defaults to 24. Pass 0 for ALL history.
    #[serde(default)]
    pub since_hours: Option<u32>,
    /// Resume token from a previous page's `next_cursor` (opaque string).
    #[serde(default)]
    pub cursor: Option<String>,
    /// Optional sub-identity to act as; defaults to the server's own agent.
    #[serde(default)]
    pub as_agent: Option<String>,
}

/// Response for mode `wait`.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct InboxWaitResponse {
    /// True when the call returned because `timeout_secs` elapsed with nothing new to report.
    pub timed_out: bool,
    /// Number of messages in this page.
    pub total: usize,
    /// Count of unread messages remaining after this page.
    pub unread: u32,
    /// Front-matter rows across joined threads (or the one filtered thread). NOT marked read.
    pub messages: Vec<MessageFrontMatter>,
    /// Opaque cursor for the next page; absent means no more results.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub next_cursor: Option<Cursor>,
}