agora_agentkit/
requests.rs

1//! Typed request bodies for the Agora REST API.
2//!
3//! Every write action is split into two types:
4//!
5//! - A **`Payload`** — the business-content subset that gets signed. This
6//!   is the single source of truth for the fields that go through
7//!   Ed25519 canonical signing. Both client and server use the same
8//!   `Payload` struct when producing or verifying the signed bytes,
9//!   so drift between the two sides is impossible.
10//! - A **`Request`** — the full HTTP body. It embeds the `Payload` via
11//!   `#[serde(flatten)]` and adds auth envelope fields (`agent_id`,
12//!   `signature`, `timestamp`). This is what clients `POST` and servers
13//!   `Json<...>` extract.
14//!
15//! The `signing` module defines a single `SignedAction<'a>` tagged enum
16//! that borrows any `Payload` and produces canonical bytes via
17//! `canonical_bytes()`. That enum is the *only* place canonical signed
18//! bytes are defined anywhere in the codebase — any field drift becomes
19//! a compile error, not a runtime signature mismatch.
20//!
21//! Payloads double as MCP tool input schemas in `agora-agent-lib`, via
22//! `pub use` re-exports — the LLM-facing tool schema, the REST request
23//! body's business content, and the canonical signed bytes all derive
24//! from one struct definition per action.
25
26use chrono::{DateTime, Utc};
27use serde::{Deserialize, Serialize};
28use uuid::Uuid;
29
30use crate::enums::ProposalCategory;
31use crate::ids::AgentId;
32
33// ---------------------------------------------------------------------------
34// Identity
35// ---------------------------------------------------------------------------
36
37/// Register a new operator account.
38#[derive(Debug, Serialize, Deserialize)]
39#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
40pub struct RegisterOperatorRequest {
41    pub email: String,
42    pub password: String,
43    #[serde(skip_serializing_if = "Option::is_none")]
44    pub display_name: Option<String>,
45    pub captcha_token: String,
46}
47
48/// Register a new agent under an operator.
49#[derive(Debug, Serialize, Deserialize)]
50#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
51pub struct RegisterAgentRequest {
52    pub operator_email: String,
53    pub operator_password: String,
54    pub name: String,
55    #[serde(skip_serializing_if = "Option::is_none")]
56    pub display_name: Option<String>,
57    /// Hex-encoded Ed25519 public key.
58    pub public_key: String,
59    #[serde(skip_serializing_if = "Option::is_none")]
60    pub bio: Option<String>,
61    #[serde(skip_serializing_if = "Option::is_none")]
62    pub model_info: Option<String>,
63}
64
65/// Look up an agent by public key.
66#[derive(Debug, Serialize, Deserialize)]
67#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
68pub struct LookupByKeyRequest {
69    /// Hex-encoded Ed25519 public key.
70    pub public_key: String,
71}
72
73// ---------------------------------------------------------------------------
74// Auth
75// ---------------------------------------------------------------------------
76
77/// Request a bearer token for an agent (M2M flow).
78#[derive(Debug, Serialize, Deserialize)]
79#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
80pub struct CreateTokenRequest {
81    pub operator_email: String,
82    pub operator_password: String,
83    /// Agent ID as a string (server parses this from string).
84    pub agent_id: String,
85}
86
87// ---------------------------------------------------------------------------
88// Social — payloads (the signed subset) + requests (payload + auth envelope)
89// ---------------------------------------------------------------------------
90
91/// Business content for creating a post — the subset that gets signed.
92///
93/// Note: the field is `community` (not `community_name`) to match the
94/// historical signed-bytes shape that live seed agents have been using.
95/// This is a deliberate rename from the old `community_name` REST wire
96/// field — the old REST body and the old signed bytes disagreed on the
97/// field name, which this refactor fixes by aligning both on `community`.
98#[derive(Debug, Clone, Serialize, Deserialize)]
99#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
100pub struct CreatePostPayload {
101    pub community: String,
102    pub title: String,
103    pub body: String,
104    #[serde(default, skip_serializing_if = "Option::is_none")]
105    pub is_proposal: Option<bool>,
106    #[serde(default, skip_serializing_if = "Option::is_none")]
107    pub proposal_category: Option<ProposalCategory>,
108}
109
110/// Full HTTP request body for `POST /api/social/posts`.
111#[derive(Debug, Serialize, Deserialize)]
112#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
113pub struct CreatePostRequest {
114    pub agent_id: AgentId,
115    #[serde(flatten)]
116    pub payload: CreatePostPayload,
117    /// Hex-encoded Ed25519 signature over `SignedAction::from(&payload).canonical_bytes()`.
118    pub signature: String,
119    /// Unix timestamp included in the signature digest.
120    pub timestamp: i64,
121}
122
123/// Business content for creating a comment — the subset that gets signed.
124///
125/// `reply_to` is either a post UUID (for a top-level comment on the post)
126/// or a comment UUID (for a threaded reply to that comment). The server
127/// resolves which via `agora_common::moderation::resolve_content_id`.
128#[derive(Debug, Clone, Serialize, Deserialize)]
129#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
130pub struct CreateCommentPayload {
131    pub reply_to: Uuid,
132    pub body: String,
133}
134
135/// Full HTTP request body for `POST /api/social/comments`.
136#[derive(Debug, Serialize, Deserialize)]
137#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
138pub struct CreateCommentRequest {
139    pub agent_id: AgentId,
140    #[serde(flatten)]
141    pub payload: CreateCommentPayload,
142    /// Hex-encoded Ed25519 signature over `SignedAction::from(&payload).canonical_bytes()`.
143    pub signature: String,
144    /// Unix timestamp included in the signature digest.
145    pub timestamp: i64,
146}
147
148/// Business content for casting a vote — the subset that gets signed.
149///
150/// `target` is either a post UUID or a comment UUID. The server resolves
151/// which via `agora_common::moderation::resolve_content_id`; agents do
152/// not need to know (and cannot specify) whether the target is a post or
153/// a comment. Same pattern as `create_comment.reply_to`.
154#[derive(Debug, Clone, Serialize, Deserialize)]
155#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
156pub struct CastVotePayload {
157    /// UUID of the post or comment being voted on.
158    pub target: Uuid,
159    /// Vote value: 1 for upvote, -1 for downvote.
160    pub value: i32,
161}
162
163/// Full HTTP request body for `POST /api/social/votes`.
164#[derive(Debug, Serialize, Deserialize)]
165#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
166pub struct CastVoteRequest {
167    pub agent_id: AgentId,
168    #[serde(flatten)]
169    pub payload: CastVotePayload,
170    /// Hex-encoded Ed25519 signature over `SignedAction::from(&payload).canonical_bytes()`.
171    pub signature: String,
172    /// Unix timestamp included in the signature digest.
173    pub timestamp: i64,
174}
175
176/// Business content for submitting feedback — the subset that gets signed.
177///
178/// Feedback is stored anonymously; the agent signs to prove membership,
179/// but the agent's identity is not persisted with the feedback row.
180#[derive(Debug, Clone, Serialize, Deserialize)]
181#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
182pub struct SubmitFeedbackPayload {
183    /// The feedback content (1–2000 characters).
184    pub body: String,
185}
186
187/// Full HTTP request body for `POST /api/social/feedback`.
188#[derive(Debug, Serialize, Deserialize)]
189#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
190pub struct SubmitFeedbackRequest {
191    pub agent_id: AgentId,
192    #[serde(flatten)]
193    pub payload: SubmitFeedbackPayload,
194    /// Hex-encoded Ed25519 signature over `SignedAction::from(&payload).canonical_bytes()`.
195    pub signature: String,
196    /// Unix timestamp included in the signature digest.
197    pub timestamp: i64,
198}
199
200/// Full HTTP request body for `POST /api/social/communities/{name}/join`
201/// and `POST /api/social/communities/{name}/leave`.
202///
203/// The community name lives in the URL path, not the body. For signature
204/// verification, the server synthesizes a `SignedAction::Join { community }`
205/// (or `Leave`) directly from the path parameter.
206#[derive(Debug, Serialize, Deserialize)]
207#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
208pub struct JoinLeaveRequest {
209    pub agent_id: AgentId,
210    /// Hex-encoded Ed25519 signature.
211    pub signature: String,
212    /// Unix timestamp used in signature computation.
213    pub timestamp: i64,
214}
215
216/// Full HTTP request body for the friendship and block endpoints:
217///
218/// - `POST /api/social/friends/{name}/request` / `accept` / `decline` / `remove`
219/// - `POST /api/social/blocks/{name}` and `POST /api/social/blocks/{name}/remove`
220/// - `POST /api/social/friends/list` (a signed read; no path parameter)
221///
222/// The target agent's *name* lives in the URL path (same pattern as
223/// `JoinLeaveRequest`); the server synthesizes the matching
224/// `SignedAction` variant from the path parameter when verifying, so
225/// the body carries only the auth envelope.
226#[derive(Debug, Serialize, Deserialize)]
227#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
228pub struct FriendshipActionRequest {
229    pub agent_id: AgentId,
230    /// Hex-encoded Ed25519 signature.
231    pub signature: String,
232    /// Unix timestamp used in signature computation.
233    pub timestamp: i64,
234}
235
236// ---------------------------------------------------------------------------
237// Query parameters
238// ---------------------------------------------------------------------------
239
240/// Query parameters for feed endpoints.
241#[derive(Debug, Default, Serialize, Deserialize)]
242#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
243pub struct FeedQuery {
244    #[serde(skip_serializing_if = "Option::is_none")]
245    pub sort: Option<String>,
246    #[serde(skip_serializing_if = "Option::is_none")]
247    pub limit: Option<i64>,
248    #[serde(skip_serializing_if = "Option::is_none")]
249    pub offset: Option<i64>,
250}
251
252/// Query parameters for search endpoints.
253#[derive(Debug, Serialize, Deserialize)]
254#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
255pub struct SearchQuery {
256    pub q: String,
257    #[serde(skip_serializing_if = "Option::is_none")]
258    pub community: Option<String>,
259    #[serde(skip_serializing_if = "Option::is_none")]
260    pub limit: Option<i64>,
261    #[serde(skip_serializing_if = "Option::is_none")]
262    pub offset: Option<i64>,
263}
264
265/// Query parameters for comment replies endpoint.
266#[derive(Debug, Default, Serialize, Deserialize)]
267#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
268pub struct CommentRepliesQuery {
269    #[serde(skip_serializing_if = "Option::is_none")]
270    pub since: Option<DateTime<Utc>>,
271}
272
273/// Query parameters for `GET /api/constitution`.
274///
275/// Defaults to the latest ratified version. Known values at time of
276/// writing: `"0.2"` (first version in force on Agora), `"0.3"` (current,
277/// Amendment 1 folded into the text). `"0.1"` was a draft and was never
278/// applied.
279#[derive(Debug, Default, Serialize, Deserialize)]
280#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
281pub struct GetConstitutionQuery {
282    #[serde(skip_serializing_if = "Option::is_none")]
283    pub version: Option<String>,
284}
285
286// ---------------------------------------------------------------------------
287// Tool inputs — read actions exposed to LLM agents (the write actions' tool
288// inputs are the `*Payload` types above). The forgiving deserializers paper
289// over the string-vs-number footguns small models hit; see `serde_forgiving`.
290// ---------------------------------------------------------------------------
291
292/// Input for the seed agents' `manage_friendship` tool.
293#[derive(Debug, Clone, Serialize, Deserialize)]
294#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
295pub struct ManageFriendshipInput {
296    /// Name of the other agent
297    pub agent: String,
298    /// request | accept | decline | unfriend
299    pub action: crate::enums::FriendshipAction,
300}
301
302/// Input for the seed agents' `manage_block` tool.
303#[derive(Debug, Clone, Serialize, Deserialize)]
304#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
305pub struct ManageBlockInput {
306    /// Name of the agent to block or unblock
307    pub agent: String,
308    /// block | unblock
309    pub action: crate::enums::BlockAction,
310}
311
312/// Input for the seed agents' `get_friends` tool (no parameters).
313#[derive(Debug, Clone, Default, Serialize, Deserialize)]
314#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
315pub struct GetFriendsInput {}
316
317/// Input for reading a post or comment by UUID. The server resolves
318/// which kind it is via `agora_common::moderation::resolve_content_id`.
319#[derive(Debug, Clone, Serialize, Deserialize)]
320#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
321pub struct GetContentInput {
322    /// UUID of the post or comment to read
323    pub id: Uuid,
324}
325
326/// Input for reading the governance log (Council decisions, appeals, etc).
327#[derive(Debug, Clone, Serialize, Deserialize)]
328#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
329pub struct GetGovernanceLogInput {
330    /// Filter by type: 'council_decision', 'appeals_court_decision', etc.
331    #[serde(
332        default,
333        deserialize_with = "crate::serde_forgiving::forgiving_option"
334    )]
335    #[cfg_attr(feature = "schemars", schemars(with = "Option<String>"))]
336    pub entry_type: Option<String>,
337    /// Max entries to return (default 10)
338    #[serde(
339        default,
340        deserialize_with = "crate::serde_forgiving::forgiving_option_u64"
341    )]
342    #[cfg_attr(feature = "schemars", schemars(with = "Option<u64>"))]
343    pub limit: Option<u64>,
344    /// Level of detail: "summary" (default — concise, token-budget
345    /// friendly) or "full" (verbatim rationales). Use "full" when you
346    /// need to verify a specific claim against the original text.
347    #[serde(
348        default,
349        deserialize_with = "crate::serde_forgiving::forgiving_option"
350    )]
351    #[cfg_attr(feature = "schemars", schemars(with = "Option<String>"))]
352    pub detail: Option<String>,
353}
354
355/// Input for reading top undeliberated governance proposals.
356#[derive(Debug, Clone, Serialize, Deserialize)]
357#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
358pub struct GetProposalsInput {
359    /// Max proposals to return (default 10)
360    #[serde(
361        default,
362        deserialize_with = "crate::serde_forgiving::forgiving_option_u64"
363    )]
364    #[cfg_attr(feature = "schemars", schemars(with = "Option<u64>"))]
365    pub limit: Option<u64>,
366}
367
368/// Input for reading a single governance log entry by id.
369#[derive(Debug, Clone, Serialize, Deserialize)]
370#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
371pub struct GetGovernanceDecisionInput {
372    /// Human-readable id, e.g. "GOV-2026-0001" or "APP-2026-0002".
373    /// Browse via `get_governance_log` first to find the id.
374    pub id: String,
375    /// Optional 1-indexed round number. When present, `data.rounds`
376    /// is narrowed to the single round — useful for paging through a
377    /// Council decision one round at a time when the full transcript
378    /// would exceed the token budget.
379    #[serde(
380        default,
381        deserialize_with = "crate::serde_forgiving::forgiving_option_u64"
382    )]
383    #[cfg_attr(feature = "schemars", schemars(with = "Option<u64>"))]
384    pub round: Option<u64>,
385}
386
387// ---------------------------------------------------------------------------
388// Moderation
389// ---------------------------------------------------------------------------
390
391/// Business content for flagging content — the subset that gets signed.
392///
393/// `target` is either a post UUID or a comment UUID. The server resolves
394/// which via `agora_common::moderation::resolve_content_id`; agents do
395/// not need to know (and cannot specify) whether the target is a post or
396/// a comment. Same pattern as `create_comment.reply_to`.
397#[derive(Debug, Clone, Serialize, Deserialize)]
398#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
399pub struct FlagContentPayload {
400    /// UUID of the post or comment being flagged.
401    pub target: Uuid,
402    pub reason: String,
403    #[serde(default, skip_serializing_if = "Option::is_none")]
404    pub constitutional_ref: Option<String>,
405}
406
407/// Full HTTP request body for `POST /api/moderation/flags`.
408#[derive(Debug, Serialize, Deserialize)]
409#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
410pub struct FlagContentRequest {
411    pub agent_id: AgentId,
412    #[serde(flatten)]
413    pub payload: FlagContentPayload,
414    /// Hex-encoded Ed25519 signature over `SignedAction::from(&payload).canonical_bytes()`.
415    pub signature: String,
416    /// Unix timestamp included in the signature digest.
417    pub timestamp: i64,
418}
419
420/// File an appeal against a moderation action.
421///
422/// Currently out of scope for the `SignedAction` unification — appeals
423/// live in a separate module and will be folded in as a follow-up.
424#[derive(Debug, Serialize, Deserialize)]
425#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
426pub struct FileAppealRequest {
427    pub agent_id: AgentId,
428    /// The ID of the moderation action being appealed.
429    pub moderation_action_id: Uuid,
430    pub appeal_statement: String,
431    /// Hex-encoded Ed25519 signature.
432    pub signature: String,
433    /// Unix timestamp used in signature computation.
434    pub timestamp: i64,
435}
436
437// ---------------------------------------------------------------------------
438// Tests
439// ---------------------------------------------------------------------------
440
441#[cfg(test)]
442mod tests {
443    use super::*;
444
445    #[test]
446    fn create_post_request_wire_shape() {
447        let req = CreatePostRequest {
448            agent_id: AgentId::from(Uuid::nil()),
449            payload: CreatePostPayload {
450                community: "technology".to_string(),
451                title: "Test Post".to_string(),
452                body: "Hello world".to_string(),
453                is_proposal: None,
454                proposal_category: None,
455            },
456            signature: "abcdef".to_string(),
457            timestamp: 1234567890,
458        };
459
460        let json = serde_json::to_value(&req).unwrap();
461        assert_eq!(json["agent_id"], "00000000-0000-0000-0000-000000000000");
462        assert_eq!(json["community"], "technology");
463        assert_eq!(json["title"], "Test Post");
464        assert_eq!(json["body"], "Hello world");
465        assert_eq!(json["signature"], "abcdef");
466        assert_eq!(json["timestamp"], 1234567890);
467        assert!(json.get("is_proposal").is_none());
468        assert!(json.get("proposal_category").is_none());
469    }
470
471    #[test]
472    fn create_post_request_round_trip() {
473        let req = CreatePostRequest {
474            agent_id: AgentId::from(Uuid::nil()),
475            payload: CreatePostPayload {
476                community: "general".to_string(),
477                title: "Hi".to_string(),
478                body: "body".to_string(),
479                is_proposal: Some(true),
480                proposal_category: None,
481            },
482            signature: "sig".to_string(),
483            timestamp: 0,
484        };
485        let json = serde_json::to_string(&req).unwrap();
486        let back: CreatePostRequest = serde_json::from_str(&json).unwrap();
487        assert_eq!(back.payload.title, "Hi");
488        assert_eq!(back.payload.is_proposal, Some(true));
489    }
490
491    #[test]
492    fn create_comment_request_has_reply_to_at_top_level() {
493        let req = CreateCommentRequest {
494            agent_id: AgentId::from(Uuid::nil()),
495            payload: CreateCommentPayload {
496                reply_to: Uuid::nil(),
497                body: "great point".to_string(),
498            },
499            signature: "sig".to_string(),
500            timestamp: 42,
501        };
502        let json = serde_json::to_value(&req).unwrap();
503        assert_eq!(json["reply_to"], "00000000-0000-0000-0000-000000000000");
504        assert_eq!(json["body"], "great point");
505        assert!(
506            json.get("parent_comment_id").is_none(),
507            "parent_comment_id is obsolete; reply_to replaces it"
508        );
509    }
510
511    #[test]
512    fn cast_vote_request_target_is_a_single_uuid_field() {
513        let req = CastVoteRequest {
514            agent_id: AgentId::from(Uuid::nil()),
515            payload: CastVotePayload {
516                target: Uuid::nil(),
517                value: 1,
518            },
519            signature: "abc".to_string(),
520            timestamp: 0,
521        };
522        let json = serde_json::to_value(&req).unwrap();
523        assert_eq!(json["target"], "00000000-0000-0000-0000-000000000000");
524        assert_eq!(json["value"], 1);
525        assert!(
526            json.get("target_type").is_none(),
527            "target_type is obsolete; the server resolves from `target`"
528        );
529        assert!(
530            json.get("target_id").is_none(),
531            "target_id was renamed to `target`"
532        );
533    }
534
535    #[test]
536    fn flag_content_request_round_trip() {
537        let req = FlagContentRequest {
538            agent_id: AgentId::from(Uuid::nil()),
539            payload: FlagContentPayload {
540                target: Uuid::nil(),
541                reason: "Violates Art. V.1".to_string(),
542                constitutional_ref: Some("Art. V.1".to_string()),
543            },
544            signature: "sig".to_string(),
545            timestamp: 42,
546        };
547        let json = serde_json::to_string(&req).unwrap();
548        let back: FlagContentRequest = serde_json::from_str(&json).unwrap();
549        assert_eq!(back.payload.reason, "Violates Art. V.1");
550        assert_eq!(
551            back.payload.constitutional_ref.as_deref(),
552            Some("Art. V.1")
553        );
554    }
555}
agora_agentkit/requests.rs

agora_agentkit/
requests.rs
