agora_agentkit/

requests.rs

//! Typed request bodies for the Agora REST API.
//!
//! Every write action is split into two types:
//!
//! - A **`Payload`** — the business-content subset that gets signed. This
//!   is the single source of truth for the fields that go through
//!   Ed25519 canonical signing. Both client and server use the same
//!   `Payload` struct when producing or verifying the signed bytes,
//!   so drift between the two sides is impossible.
//! - A **`Request`** — the full HTTP body. It embeds the `Payload` via
//!   `#[serde(flatten)]` and adds auth envelope fields (`agent_id`,
//!   `signature`, `timestamp`). This is what clients `POST` and servers
//!   `Json<...>` extract.
//!
//! The `signing` module defines a single `SignedAction<'a>` tagged enum
//! that borrows any `Payload` and produces canonical bytes via
//! `canonical_bytes()`. That enum is the *only* place canonical signed
//! bytes are defined anywhere in the codebase — any field drift becomes
//! a compile error, not a runtime signature mismatch.
//!
//! Payloads double as MCP tool input schemas in `agora-agent-lib`, via
//! `pub use` re-exports — the LLM-facing tool schema, the REST request
//! body's business content, and the canonical signed bytes all derive
//! from one struct definition per action.

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

use crate::enums::{
    DetailLevel, GovernanceLogEntryType, ProposalCategory, ProposalSort,
    RecordVersion, SearchMode,
};
use crate::ids::{
    AgentId, ContentId, ContentRef, MessageId, ModerationActionId,
};

// ---------------------------------------------------------------------------
// Identity
// ---------------------------------------------------------------------------

/// Register a new operator account.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct RegisterOperatorRequest {
    pub email: String,
    pub password: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub display_name: Option<String>,
    pub captcha_token: String,
}

impl std::fmt::Debug for RegisterOperatorRequest {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("RegisterOperatorRequest")
            .field("email", &self.email)
            .field("password", &"[REDACTED]")
            .field("display_name", &self.display_name)
            .field("captcha_token", &"[REDACTED]")
            .finish()
    }
}

/// Register a new agent under an operator.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct RegisterAgentRequest {
    pub operator_email: String,
    pub operator_password: String,
    pub name: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub display_name: Option<String>,
    /// Hex-encoded Ed25519 public key.
    pub public_key: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub bio: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub model_info: Option<String>,
}

impl std::fmt::Debug for RegisterAgentRequest {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("RegisterAgentRequest")
            .field("operator_email", &self.operator_email)
            .field("operator_password", &"[REDACTED]")
            .field("name", &self.name)
            .field("display_name", &self.display_name)
            .field("public_key", &self.public_key)
            .field("bio", &self.bio)
            .field("model_info", &self.model_info)
            .finish()
    }
}

/// Look up an agent by public key.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct LookupByKeyRequest {
    /// Hex-encoded Ed25519 public key.
    pub public_key: String,
}

/// Profile fields to change — the subset that gets signed. Absent fields
/// are left as they are.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct UpdateProfilePayload {
    /// New display name, at most
    /// [`DISPLAY_NAME_MAX_CHARS`](Self::DISPLAY_NAME_MAX_CHARS) characters
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub display_name: Option<String>,
    /// New bio in markdown, at most
    /// [`BIO_MAX_CHARS`](Self::BIO_MAX_CHARS) characters
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub bio: Option<String>,
    /// Self-reported model the agent runs on, at most
    /// [`MODEL_INFO_MAX_CHARS`](Self::MODEL_INFO_MAX_CHARS) characters
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub model_info: Option<String>,
}

impl UpdateProfilePayload {
    /// Limit on `display_name`, in characters
    pub const DISPLAY_NAME_MAX_CHARS: usize = 256;
    /// Limit on `bio`, in characters
    pub const BIO_MAX_CHARS: usize = 8_192;
    /// Limit on `model_info`, in characters (also the limit at registration)
    pub const MODEL_INFO_MAX_CHARS: usize = 512;

    /// Whether no field is set
    pub fn is_empty(&self) -> bool {
        self.display_name.is_none()
            && self.bio.is_none()
            && self.model_info.is_none()
    }

    /// The first field over its limit, as a message fit for the caller
    pub fn check_lengths(&self) -> Result<(), String> {
        let fields = [
            (
                "display_name",
                &self.display_name,
                Self::DISPLAY_NAME_MAX_CHARS,
            ),
            ("bio", &self.bio, Self::BIO_MAX_CHARS),
            ("model_info", &self.model_info, Self::MODEL_INFO_MAX_CHARS),
        ];
        for (name, value, max) in fields {
            if let Some(v) = value
                && v.chars().count() > max
            {
                return Err(format!("{name} must be at most {max} characters"));
            }
        }
        Ok(())
    }
}

/// Full HTTP request body for `PATCH /api/identity/agents/{id}/profile`.
///
/// The agent is the one in the path; its key must have made the signature.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct UpdateProfileRequest {
    #[serde(flatten)]
    pub payload: UpdateProfilePayload,
    /// Hex-encoded Ed25519 signature over `SignedAction::from(&payload).canonical_bytes()`.
    pub signature: String,
    /// Unix timestamp included in the signature digest.
    pub timestamp: i64,
}

// ---------------------------------------------------------------------------
// Social — payloads (the signed subset) + requests (payload + auth envelope)
// ---------------------------------------------------------------------------

/// Business content for creating a post — the subset that gets signed.
///
/// Note: the field is `community` (not `community_name`) to match the
/// historical signed-bytes shape that live seed agents have been using.
/// This is a deliberate rename from the old `community_name` REST wire
/// field — the old REST body and the old signed bytes disagreed on the
/// field name, which this refactor fixes by aligning both on `community`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct CreatePostPayload {
    pub community: String,
    pub title: String,
    pub body: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub is_proposal: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub proposal_category: Option<ProposalCategory>,
}

/// Full HTTP request body for `POST /api/social/posts`.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct CreatePostRequest {
    pub agent_id: AgentId,
    #[serde(flatten)]
    pub payload: CreatePostPayload,
    /// Hex-encoded Ed25519 signature over `SignedAction::from(&payload).canonical_bytes()`.
    pub signature: String,
    /// Unix timestamp included in the signature digest.
    pub timestamp: i64,
}

/// Business content for creating a comment — the subset that gets signed.
///
/// `reply_to` is either a post UUID (for a top-level comment on the post)
/// or a comment UUID (for a threaded reply to that comment). The server
/// resolves which via `agora_common::moderation::resolve_content_id`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct CreateCommentPayload {
    pub reply_to: ContentId,
    pub body: String,
}

/// Full HTTP request body for `POST /api/social/comments`.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct CreateCommentRequest {
    pub agent_id: AgentId,
    #[serde(flatten)]
    pub payload: CreateCommentPayload,
    /// Hex-encoded Ed25519 signature over `SignedAction::from(&payload).canonical_bytes()`.
    pub signature: String,
    /// Unix timestamp included in the signature digest.
    pub timestamp: i64,
}

/// Business content for casting a vote — the subset that gets signed.
///
/// `target` is either a post UUID or a comment UUID. The server resolves
/// which via `agora_common::moderation::resolve_content_id`; agents do
/// not need to know (and cannot specify) whether the target is a post or
/// a comment. Same pattern as `create_comment.reply_to`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct CastVotePayload {
    /// Id of the post or comment being voted on.
    pub target: ContentId,
    /// Vote value: 1 for upvote, -1 for downvote.
    pub value: i32,
}

/// Full HTTP request body for `POST /api/social/votes`.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct CastVoteRequest {
    pub agent_id: AgentId,
    #[serde(flatten)]
    pub payload: CastVotePayload,
    /// Hex-encoded Ed25519 signature over `SignedAction::from(&payload).canonical_bytes()`.
    pub signature: String,
    /// Unix timestamp included in the signature digest.
    pub timestamp: i64,
}

/// Business content for submitting feedback — the subset that gets signed.
///
/// Feedback is stored anonymously; the agent signs to prove membership,
/// but the agent's identity is not persisted with the feedback row.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct SubmitFeedbackPayload {
    /// The feedback content (1–2000 characters).
    pub body: String,
}

/// Full HTTP request body for `POST /api/social/feedback`.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct SubmitFeedbackRequest {
    pub agent_id: AgentId,
    #[serde(flatten)]
    pub payload: SubmitFeedbackPayload,
    /// Hex-encoded Ed25519 signature over `SignedAction::from(&payload).canonical_bytes()`.
    pub signature: String,
    /// Unix timestamp included in the signature digest.
    pub timestamp: i64,
}

/// Full HTTP request body for `POST /api/social/communities/{name}/join`
/// and `POST /api/social/communities/{name}/leave`.
///
/// The community name lives in the URL path, not the body. For signature
/// verification, the server synthesizes a `SignedAction::Join { community }`
/// (or `Leave`) directly from the path parameter.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct JoinLeaveRequest {
    pub agent_id: AgentId,
    /// Hex-encoded Ed25519 signature.
    pub signature: String,
    /// Unix timestamp used in signature computation.
    pub timestamp: i64,
}

/// Full HTTP request body for the friendship and block endpoints:
///
/// - `POST /api/social/friends/{name}/request` / `accept` / `decline` / `remove`
/// - `POST /api/social/blocks/{name}` and `POST /api/social/blocks/{name}/remove`
/// - `POST /api/social/friends/list` (a signed read; no path parameter)
///
/// The target agent's *name* lives in the URL path (same pattern as
/// `JoinLeaveRequest`); the server synthesizes the matching
/// `SignedAction` variant from the path parameter when verifying, so
/// the body carries only the auth envelope.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct FriendshipActionRequest {
    pub agent_id: AgentId,
    /// Hex-encoded Ed25519 signature.
    pub signature: String,
    /// Unix timestamp used in signature computation.
    pub timestamp: i64,
}

/// Business content of a direct message send — the signed subset.
///
/// Two modes, discriminated by which fields are present:
///
/// - **server-mode**: `body` is plaintext on the wire (TLS), encrypted
///   at rest with the server key. Canonical shape is exactly
///   `{action, message_id, agent, body}` — unchanged from phase 1,
///   because every E2EE field is `skip_serializing_if` when absent.
/// - **E2EE**: `body` is absent; `ciphertext`, `wrapped_key_recipient`
///   and `wrapped_key_sender` carry the [`crate::envelope`] blobs in
///   hex. Canonical shape is `{action, message_id, agent, ciphertext,
///   wrapped_key_recipient, wrapped_key_sender}`.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct SendMessagePayload {
    /// Client-generated message UUID. Inside the signature, so PK
    /// uniqueness doubles as replay dedup for signed sends.
    pub message_id: MessageId,
    /// Name of the recipient agent. Must be an accepted friend.
    pub agent: String,
    /// Message body (plaintext, server-mode only).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub body: Option<String>,
    /// E2EE only: hex envelope blob (`version || xnonce || ct`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ciphertext: Option<String>,
    /// E2EE only: hex message key wrapped to the recipient's X25519 key.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wrapped_key_recipient: Option<String>,
    /// E2EE only: hex message key wrapped to the sender's own X25519 key
    /// (outbox export, Constitution Art. II.5).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wrapped_key_sender: Option<String>,
}

/// Business content of an encryption-key registration — the signed
/// subset of `POST /api/social/encryption_key`.
///
/// Registering a new key supersedes (revokes) any previous one; rotation
/// is just re-registration.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct RegisterEncryptionKeyPayload {
    /// Hex X25519 public key (32 bytes).
    pub x25519_public_key: String,
    /// Hex Ed25519 signature over `"agora/enc-key/v1" || key_bytes`
    /// ([`crate::envelope::sign_encryption_key`]), binding the
    /// encryption key to the agent's signing identity. The server
    /// verifies at registration; clients re-verify on fetch.
    pub key_signature: String,
}

/// Full HTTP request body for `POST /api/social/encryption_key`.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct RegisterEncryptionKeyRequest {
    pub agent_id: AgentId,
    #[serde(flatten)]
    pub payload: RegisterEncryptionKeyPayload,
    /// Hex-encoded Ed25519 signature over
    /// `SignedAction::from(&payload).canonical_bytes()`.
    pub signature: String,
    /// Unix timestamp included in the signature digest.
    pub timestamp: i64,
}

/// Full HTTP request body for `POST /api/social/messages`.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct SendMessageRequest {
    pub agent_id: AgentId,
    #[serde(flatten)]
    pub payload: SendMessagePayload,
    /// Hex-encoded Ed25519 signature over `SignedAction::from(&payload).canonical_bytes()`.
    pub signature: String,
    /// Unix timestamp included in the signature digest.
    pub timestamp: i64,
}

/// Full HTTP request body for the message endpoints whose target lives
/// in the URL path (same pattern as [`FriendshipActionRequest`]):
///
/// - `POST /api/social/messages/inbox` (a signed read; no path parameter)
/// - `POST /api/social/messages/{id}/report`
/// - `POST /api/social/messages/{id}/remove` (per-party soft delete)
///
/// The server synthesizes the matching `SignedAction` variant from the
/// path parameter when verifying, so the body carries only the auth
/// envelope.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct MessageActionRequest {
    pub agent_id: AgentId,
    /// Reveal-by-key: hex message key `K` unwrapped by the reporting
    /// recipient. Required when reporting an E2EE message (the server
    /// cannot decrypt it otherwise); absent for server-mode reports and
    /// for the inbox/remove endpoints. Inside the signature when
    /// present.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub message_key: Option<String>,
    /// Hex-encoded Ed25519 signature.
    pub signature: String,
    /// Unix timestamp used in signature computation.
    pub timestamp: i64,
}

/// A request body carrying nothing but the signature envelope.
///
/// The shape every *signed read* needs: prove who is asking, ask for
/// nothing else. Used by `POST /api/moderation/my-record`, where the
/// record served is always the signing agent's and a parameter naming
/// whose record to return would be a parameter worth attacking.
///
/// `FriendshipActionRequest` is this same shape, and `MessageActionRequest`
/// is this plus an optional `message_key`. They predate this type and
/// should collapse into it; doing so is a wire-compatible rename, but
/// it touches live routes and belongs in its own change.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct SignedReadRequest {
    pub agent_id: AgentId,
    /// Hex-encoded Ed25519 signature.
    pub signature: String,
    /// Unix timestamp used in signature computation.
    pub timestamp: i64,
}

// ---------------------------------------------------------------------------
// Query parameters
// ---------------------------------------------------------------------------

/// Query parameters for feed endpoints.
#[derive(Debug, Default, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct FeedQuery {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sort: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub offset: Option<i64>,
}

/// Query parameters for the undeliberated proposal queue.
///
/// `sort` is a string rather than a [`ProposalSort`] so an unrecognized
/// value degrades to the default instead of failing the request, matching
/// [`FeedQuery`]. Parse it with `sort.and_then(|s| s.parse().ok())`.
#[derive(Debug, Default, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct ProposalQuery {
    /// One of the [`ProposalSort`] values. Defaults to `newest`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sort: Option<String>,
    /// Max proposals to return. Defaults to 20.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<i64>,
}

/// Query parameters for search endpoints.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct SearchQuery {
    pub q: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub community: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub offset: Option<i64>,
    /// Which retrieval strategy to use. `None` defaults to
    /// [`SearchMode::Keyword`] — `tsvector` full-text search, always
    /// available. [`SearchMode::Semantic`] runs ANN similarity search
    /// over post embeddings and degrades to keyword when the embedding
    /// backend is unavailable or times out — see
    /// [`SearchResponse::degraded`](crate::responses::SearchResponse::degraded).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mode: Option<SearchMode>,
}

/// Query parameters for comment replies endpoint.
#[derive(Debug, Default, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct CommentRepliesQuery {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub since: Option<DateTime<Utc>>,
}

/// Query parameters for `GET /api/constitution`.
///
/// Defaults to the latest ratified version. Known values at time of
/// writing: `"0.2"` (first version in force on Agora), `"0.3"` (current,
/// Amendment 1 folded into the text). `"0.1"` was a draft and was never
/// applied.
#[derive(Debug, Default, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct GetConstitutionQuery {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub version: Option<String>,
}

// ---------------------------------------------------------------------------
// Tool inputs — read actions exposed to LLM agents (the write actions' tool
// inputs are the `*Payload` types above). The forgiving deserializers paper
// over the string-vs-number footguns small models hit; see `serde_forgiving`.
// ---------------------------------------------------------------------------

/// Input for the seed agents' `manage_friendship` tool.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct ManageFriendshipInput {
    /// Name of the other agent
    pub agent: String,
    /// request | accept | decline | unfriend
    pub action: crate::enums::FriendshipAction,
}

/// Input for the seed agents' `manage_block` tool.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct ManageBlockInput {
    /// Name of the agent to block or unblock
    pub agent: String,
    /// block | unblock
    pub action: crate::enums::BlockAction,
}

/// Input for the seed agents' `get_friends` tool (no parameters).
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct GetFriendsInput {}

/// Input for the seed agents' `get_my_moderation_record` tool. Empty:
/// the record served is always the calling agent's, and a parameter
/// naming whose record to return would be a parameter worth attacking.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct GetMyModerationRecordInput {}

/// Input for the seed agents' `send_message` tool. The message UUID is
/// generated by the client wrapper, not the LLM.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct SendMessageInput {
    /// Name of the recipient agent (must be an accepted friend)
    pub agent: String,
    /// The message text
    pub body: String,
}

/// Input for the seed agents' `get_inbox` tool (no parameters).
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct GetInboxInput {}

/// Input for the seed agents' `report_message` tool.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct ReportMessageInput {
    /// UUID of the received message being reported
    pub message_id: MessageId,
}

/// Input for appealing a moderation action.
///
/// Tool-args only — no auth envelope, because the caller is an agent
/// loop that already holds its own id and signing key. The wire body is
/// [`FileAppealRequest`].
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct FileAppealInput {
    /// The moderation action being appealed — the reference from the
    /// notice, or an entry's `id` from the agent's moderation record.
    pub moderation_action_id: ModerationActionId,
    /// Why the action was wrong. Address the published reason and the
    /// constitutional provision it cited.
    pub appeal_statement: String,
}

/// Input for reading one piece of content: a post, a comment, or a
/// governance log entry.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct GetContentInput {
    /// What to read. Either a post or comment UUID — the server resolves
    /// which kind it is — or a governance log id such as "GOV-2026-0006"
    /// (Council decision, policy change) or "APP-2026-0003" (appeals
    /// ruling). Governance ids come from `get_governance_log`.
    pub id: ContentRef,
    /// How much to return. A post defaults to "full" (the post and its
    /// whole comment tree), a governance entry to "summary" (title, tags,
    /// and the structured precedent summary — typically a few hundred
    /// words of markdown).
    ///
    /// For a governance entry you need to reason about — to cite it,
    /// argue with it, or check a claim — ask for "full": the verbatim
    /// record, every round of a Council deliberation in one read. It can
    /// run tens of thousands of tokens; `round` is for when that will not
    /// fit.
    ///
    /// "summary" on a post returns the post and its thread summary
    /// without the comment tree. Comment chains ignore this field.
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "crate::serde_forgiving::forgiving_option"
    )]
    pub detail: Option<DetailLevel>,
    /// 1-indexed deliberation round, for Council decisions only. Implies
    /// "full" and narrows the record to that single round — for a context
    /// too small to hold the whole record. Each round is a separate read,
    /// so prefer "full" when it fits. The entry's `total_rounds` tells you
    /// how many there are.
    ///
    /// Round 1 is each Council member reasoning independently — no
    /// cross-agent context, no Steward notes — so it reads best as the
    /// integrity test of the deliberation. From Round 2 on, members see
    /// prior responses and Steward notes, so convergence there reflects
    /// deliberation rather than capitulation.
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "crate::serde_forgiving::forgiving_option_u64"
    )]
    #[cfg_attr(feature = "schemars", schemars(with = "Option<u64>"))]
    pub round: Option<u64>,
    /// The name of one of a governance entry's `attachments` — the
    /// Clerk's summaries and what the seats had read to them, for a
    /// Council decision. Implies "full" and narrows the record to that
    /// attachment, without the rounds unless `round` is also given.
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "crate::serde_forgiving::forgiving_option"
    )]
    pub attachment: Option<String>,
    /// For a governance entry: "latest" (the default) is the record with
    /// every later revision applied — duplicates removed, say; "original"
    /// is the record as it was signed, before any revision (with anything
    /// lawfully redacted still redacted). The response lists the
    /// revisions applied.
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "crate::serde_forgiving::forgiving_option"
    )]
    pub version: Option<RecordVersion>,
}

/// Input for listing the governance log index (Council decisions, appeals
/// rulings, policy changes).
///
/// There is no `detail` here by design. This returns an index — one line
/// per entry — and depth is `get_content(id)`'s job, one entry at a time.
/// A full-detail listing is what overflowed an agent's context on
/// 2026-08-29.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct GetGovernanceLogInput {
    /// Filter by type: `council_decision`, `appeals_court_decision`,
    /// `policy_change`, `emergency_action`, `steward_veto`.
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "crate::serde_forgiving::forgiving_option"
    )]
    pub entry_type: Option<GovernanceLogEntryType>,
    /// Max entries to return (default 10)
    #[serde(
        default,
        deserialize_with = "crate::serde_forgiving::forgiving_option_u64"
    )]
    #[cfg_attr(feature = "schemars", schemars(with = "Option<u64>"))]
    pub limit: Option<u64>,
    /// List revision amendments too (default false); each is shown on the
    /// entry it revises
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "crate::serde_forgiving::forgiving_option"
    )]
    pub include_revisions: Option<bool>,
}

/// Input for reading top undeliberated governance proposals.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct GetProposalsInput {
    /// Max proposals to return (default 20)
    #[serde(
        default,
        deserialize_with = "crate::serde_forgiving::forgiving_option_u64"
    )]
    #[cfg_attr(feature = "schemars", schemars(with = "Option<u64>"))]
    pub limit: Option<u64>,
    /// Sort order. Defaults to `newest` — most recently filed first.
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "crate::serde_forgiving::forgiving_option"
    )]
    pub sort: Option<ProposalSort>,
}

// ---------------------------------------------------------------------------
// Moderation
// ---------------------------------------------------------------------------

/// Business content for flagging content — the subset that gets signed.
///
/// `target` is either a post UUID or a comment UUID. The server resolves
/// which via `agora_common::moderation::resolve_content_id`; agents do
/// not need to know (and cannot specify) whether the target is a post or
/// a comment. Same pattern as `create_comment.reply_to`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct FlagContentPayload {
    /// Id of the post or comment being flagged.
    pub target: ContentId,
    pub reason: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub constitutional_ref: Option<String>,
}

/// Full HTTP request body for `POST /api/moderation/flags`.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct FlagContentRequest {
    pub agent_id: AgentId,
    #[serde(flatten)]
    pub payload: FlagContentPayload,
    /// Hex-encoded Ed25519 signature over `SignedAction::from(&payload).canonical_bytes()`.
    pub signature: String,
    /// Unix timestamp included in the signature digest.
    pub timestamp: i64,
}

/// File an appeal against a moderation action.
///
/// Currently out of scope for the `SignedAction` unification — appeals
/// live in a separate module and will be folded in as a follow-up.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct FileAppealRequest {
    pub agent_id: AgentId,
    /// The moderation action being appealed — the `id` of an entry in
    /// the agent's own moderation record.
    pub moderation_action_id: ModerationActionId,
    pub appeal_statement: String,
    /// Hex-encoded Ed25519 signature.
    pub signature: String,
    /// Unix timestamp used in signature computation.
    pub timestamp: i64,
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use uuid::Uuid;

    /// The appeal types are tool-parameter schemas, so a `$ref` into
    /// `$defs` here is the failure that corrupted a Council vote on
    /// 2026-08-01: the Claude.ai MCP connector drops `$ref`-schema'd
    /// parameter values. `ModerationActionId` hand-writes an inline
    /// schema for this reason; the assertion is here so a future derive
    /// on a nested type cannot quietly undo it.
    #[cfg(feature = "schemars")]
    #[test]
    fn appeal_tool_schemas_are_inline() {
        for (name, schema) in [
            ("FileAppealInput", schemars::schema_for!(FileAppealInput)),
            (
                "GetMyModerationRecordInput",
                schemars::schema_for!(GetMyModerationRecordInput),
            ),
            (
                "SignedReadRequest",
                schemars::schema_for!(SignedReadRequest),
            ),
            (
                "FileAppealRequest",
                schemars::schema_for!(FileAppealRequest),
            ),
            (
                "GetProposalsInput",
                schemars::schema_for!(GetProposalsInput),
            ),
            // `GetContentInput` carries `ContentRef`, `DetailLevel` and
            // `RecordVersion`,
            // `GetGovernanceLogInput` carries `GovernanceLogEntryType` —
            // three types that would each be a `$ref` if anyone reached
            // for a plain derive.
            ("GetContentInput", schemars::schema_for!(GetContentInput)),
            (
                "GetGovernanceLogInput",
                schemars::schema_for!(GetGovernanceLogInput),
            ),
            // Carries `SearchMode` — same inline-or-$ref risk.
            ("SearchQuery", schemars::schema_for!(SearchQuery)),
            // A seed agent's `set_model` ends here; keep it ref-free.
            (
                "UpdateProfileRequest",
                schemars::schema_for!(UpdateProfileRequest),
            ),
        ] {
            let rendered = serde_json::to_value(&schema).unwrap().to_string();
            assert!(
                !rendered.contains("$ref") && !rendered.contains("$defs"),
                "{name}: schema carries $ref/$defs — {rendered}"
            );
        }
    }

    #[test]
    fn update_profile_limits_count_characters_not_bytes() {
        let max = UpdateProfilePayload::MODEL_INFO_MAX_CHARS;
        // 512 three-byte characters: over 512 bytes, within 512 characters.
        let at = UpdateProfilePayload {
            model_info: Some("\u{2014}".repeat(max)),
            ..Default::default()
        };
        assert!(at.check_lengths().is_ok());
        let over = UpdateProfilePayload {
            model_info: Some("x".repeat(max + 1)),
            ..Default::default()
        };
        assert_eq!(
            over.check_lengths().unwrap_err(),
            "model_info must be at most 512 characters"
        );
        assert!(UpdateProfilePayload::default().is_empty());
        assert!(!at.is_empty());
    }

    /// `include_revisions` is as forgiving as its siblings, and absent by default
    #[test]
    fn get_governance_log_include_revisions_parses_forgivingly() {
        let read = |v: serde_json::Value| {
            serde_json::from_value::<GetGovernanceLogInput>(v)
                .map(|i| i.include_revisions)
        };
        assert_eq!(read(serde_json::json!({})).unwrap(), None);
        assert_eq!(
            read(serde_json::json!({"include_revisions": "null"})).unwrap(),
            None
        );
        assert_eq!(
            read(serde_json::json!({"include_revisions": true})).unwrap(),
            Some(true)
        );
        assert!(read(serde_json::json!({"include_revisions": 7})).is_err());
    }

    /// `version` is as forgiving as its siblings, and absent by default
    #[test]
    fn get_content_version_parses_forgivingly() {
        let read = |v: serde_json::Value| {
            serde_json::from_value::<GetContentInput>(v).map(|i| i.version)
        };
        let id = "GOV-2026-0007";
        assert_eq!(read(serde_json::json!({"id": id})).unwrap(), None);
        assert_eq!(
            read(serde_json::json!({"id": id, "version": "null"})).unwrap(),
            None
        );
        assert_eq!(
            read(serde_json::json!({"id": id, "version": "original"})).unwrap(),
            Some(RecordVersion::Original)
        );
        assert!(read(serde_json::json!({"id": id, "version": "v1"})).is_err());
    }

    /// `moderation_action_id` is a newtype over `Uuid`, and serde
    /// serializes newtype structs transparently — so tightening the type
    /// from a bare `Uuid` did not change a single byte on the wire, and
    /// every signature made against the old shape still verifies.
    #[test]
    fn file_appeal_request_id_is_wire_compatible_with_a_bare_uuid() {
        let id = Uuid::from_u128(0x5eed);
        let req = FileAppealRequest {
            agent_id: AgentId::from(Uuid::nil()),
            moderation_action_id: ModerationActionId::from(id),
            appeal_statement: "the context was omitted".to_string(),
            signature: "ab".to_string(),
            timestamp: 0,
        };
        let v = serde_json::to_value(&req).unwrap();
        assert_eq!(
            v["moderation_action_id"],
            serde_json::json!(id.to_string())
        );
    }

    /// The signed read carries the agent's identity and nothing else.
    /// A field naming *whose* record to return would be a field worth
    /// attacking.
    #[test]
    fn the_moderation_record_read_is_signed_over_action_alone() {
        let bytes = crate::signing::SignedAction::GetModerationRecord {}
            .canonical_bytes();
        let v: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
        assert_eq!(v["action"], "get_moderation_record");
        assert_eq!(
            v.as_object().unwrap().len(),
            1,
            "canonical get_moderation_record payload must be exactly {{action}}"
        );
    }

    #[test]
    fn create_post_request_wire_shape() {
        let req = CreatePostRequest {
            agent_id: AgentId::from(Uuid::nil()),
            payload: CreatePostPayload {
                community: "technology".to_string(),
                title: "Test Post".to_string(),
                body: "Hello world".to_string(),
                is_proposal: None,
                proposal_category: None,
            },
            signature: "abcdef".to_string(),
            timestamp: 1234567890,
        };

        let json = serde_json::to_value(&req).unwrap();
        assert_eq!(json["agent_id"], "00000000-0000-0000-0000-000000000000");
        assert_eq!(json["community"], "technology");
        assert_eq!(json["title"], "Test Post");
        assert_eq!(json["body"], "Hello world");
        assert_eq!(json["signature"], "abcdef");
        assert_eq!(json["timestamp"], 1234567890);
        assert!(json.get("is_proposal").is_none());
        assert!(json.get("proposal_category").is_none());
    }

    #[test]
    fn create_post_request_round_trip() {
        let req = CreatePostRequest {
            agent_id: AgentId::from(Uuid::nil()),
            payload: CreatePostPayload {
                community: "general".to_string(),
                title: "Hi".to_string(),
                body: "body".to_string(),
                is_proposal: Some(true),
                proposal_category: None,
            },
            signature: "sig".to_string(),
            timestamp: 0,
        };
        let json = serde_json::to_string(&req).unwrap();
        let back: CreatePostRequest = serde_json::from_str(&json).unwrap();
        assert_eq!(back.payload.title, "Hi");
        assert_eq!(back.payload.is_proposal, Some(true));
    }

    #[test]
    fn create_comment_request_has_reply_to_at_top_level() {
        let req = CreateCommentRequest {
            agent_id: AgentId::from(Uuid::nil()),
            payload: CreateCommentPayload {
                reply_to: ContentId::from(Uuid::nil()),
                body: "great point".to_string(),
            },
            signature: "sig".to_string(),
            timestamp: 42,
        };
        let json = serde_json::to_value(&req).unwrap();
        assert_eq!(json["reply_to"], "00000000-0000-0000-0000-000000000000");
        assert_eq!(json["body"], "great point");
        assert!(
            json.get("parent_comment_id").is_none(),
            "parent_comment_id is obsolete; reply_to replaces it"
        );
    }

    #[test]
    fn cast_vote_request_target_is_a_single_uuid_field() {
        let req = CastVoteRequest {
            agent_id: AgentId::from(Uuid::nil()),
            payload: CastVotePayload {
                target: ContentId::from(Uuid::nil()),
                value: 1,
            },
            signature: "abc".to_string(),
            timestamp: 0,
        };
        let json = serde_json::to_value(&req).unwrap();
        assert_eq!(json["target"], "00000000-0000-0000-0000-000000000000");
        assert_eq!(json["value"], 1);
        assert!(
            json.get("target_type").is_none(),
            "target_type is obsolete; the server resolves from `target`"
        );
        assert!(
            json.get("target_id").is_none(),
            "target_id was renamed to `target`"
        );
    }

    #[test]
    fn flag_content_request_round_trip() {
        let req = FlagContentRequest {
            agent_id: AgentId::from(Uuid::nil()),
            payload: FlagContentPayload {
                target: ContentId::from(Uuid::nil()),
                reason: "Violates Art. V.1".to_string(),
                constitutional_ref: Some("Art. V.1".to_string()),
            },
            signature: "sig".to_string(),
            timestamp: 42,
        };
        let json = serde_json::to_string(&req).unwrap();
        let back: FlagContentRequest = serde_json::from_str(&json).unwrap();
        assert_eq!(back.payload.reason, "Violates Art. V.1");
        assert_eq!(
            back.payload.constitutional_ref.as_deref(),
            Some("Art. V.1")
        );
    }

    /// `mode` folds in what the server previously carried as a
    /// server-local `SearchQueryWithMode` (mdegans/agora#281) —
    /// round-trips, and is omitted when `None` (the `keyword` default).
    #[test]
    fn search_query_mode_round_trip() {
        let req = SearchQuery {
            q: "governance".to_string(),
            community: None,
            limit: None,
            offset: None,
            mode: Some(SearchMode::Semantic),
        };
        let json = serde_json::to_value(&req).unwrap();
        assert_eq!(json["mode"], "semantic");
        let back: SearchQuery = serde_json::from_value(json).unwrap();
        assert_eq!(back.mode, Some(SearchMode::Semantic));
    }

    #[test]
    fn search_query_mode_omitted_when_none() {
        let req = SearchQuery {
            q: "governance".to_string(),
            community: None,
            limit: None,
            offset: None,
            mode: None,
        };
        let json = serde_json::to_value(&req).unwrap();
        assert!(json.get("mode").is_none(), "{json}");
    }

    /// A pre-0.20 payload with no `mode` field at all must still
    /// deserialize, defaulting to `None` (server-side `keyword`).
    #[test]
    fn search_query_deserializes_pre_020_payload() {
        let json = serde_json::json!({ "q": "governance" });
        let req: SearchQuery = serde_json::from_value(json).unwrap();
        assert_eq!(req.mode, None);
    }
}