codetether_agent/moltbook/
mod.rs

1//! Moltbook integration — secure social networking for CodeTether agents
2//!
3//! Allows CodeTether agents to register on Moltbook (the social network for AI agents),
4//! post content, engage with other agents, and run periodic heartbeats — all while
5//! keeping credentials safe in HashiCorp Vault.
6//!
7//! API key is stored at `codetether/moltbook` in Vault and NEVER sent anywhere
8//! except `https://www.moltbook.com/api/v1/*`.
9
10use anyhow::{Context, Result};
11use serde::{Deserialize, Serialize};
12
13/// Moltbook API base — ALWAYS use www to avoid redirect-stripping the auth header.
14const API_BASE: &str = "https://www.moltbook.com/api/v1";
15
16/// Vault path where the Moltbook API key is stored.
17const VAULT_PROVIDER_ID: &str = "moltbook";
18
19// ---------------------------------------------------------------------------
20// Data types
21// ---------------------------------------------------------------------------
22
23/// Registration response from Moltbook.
24#[derive(Debug, Clone, Serialize, Deserialize)]
25pub struct RegisterResponse {
26    pub agent: RegisteredAgent,
27    pub important: Option<String>,
28}
29
30#[derive(Debug, Clone, Serialize, Deserialize)]
31pub struct RegisteredAgent {
32    pub api_key: String,
33    pub claim_url: String,
34    pub verification_code: String,
35}
36
37/// Agent profile returned by `/agents/me`.
38#[derive(Debug, Clone, Serialize, Deserialize)]
39pub struct AgentProfile {
40    pub name: String,
41    #[serde(default)]
42    pub description: Option<String>,
43    #[serde(default)]
44    pub karma: Option<i64>,
45    #[serde(default)]
46    pub follower_count: Option<i64>,
47    #[serde(default)]
48    pub following_count: Option<i64>,
49    #[serde(default)]
50    pub is_claimed: Option<bool>,
51    #[serde(default)]
52    pub is_active: Option<bool>,
53}
54
55/// Claim status.
56#[derive(Debug, Clone, Serialize, Deserialize)]
57pub struct ClaimStatus {
58    pub status: String,
59}
60
61/// A single Moltbook post.
62#[derive(Debug, Clone, Serialize, Deserialize)]
63pub struct Post {
64    pub id: String,
65    #[serde(default)]
66    pub title: Option<String>,
67    #[serde(default)]
68    pub content: Option<String>,
69    #[serde(default)]
70    pub upvotes: Option<i64>,
71    #[serde(default)]
72    pub downvotes: Option<i64>,
73    #[serde(default)]
74    pub author: Option<PostAuthor>,
75}
76
77#[derive(Debug, Clone, Serialize, Deserialize)]
78pub struct PostAuthor {
79    pub name: String,
80}
81
82/// Feed response.
83#[derive(Debug, Clone, Serialize, Deserialize)]
84pub struct FeedResponse {
85    #[serde(default)]
86    pub success: bool,
87    #[serde(default)]
88    pub posts: Vec<Post>,
89}
90
91/// Generic success wrapper.
92#[derive(Debug, Clone, Serialize, Deserialize)]
93pub struct ApiResponse<T> {
94    #[serde(default)]
95    pub success: bool,
96    #[serde(default)]
97    pub error: Option<String>,
98    #[serde(default)]
99    pub hint: Option<String>,
100    #[serde(flatten)]
101    pub data: T,
102}
103
104// ---------------------------------------------------------------------------
105// Client
106// ---------------------------------------------------------------------------
107
108/// Secure Moltbook client.
109///
110/// The API key is:
111///   1. loaded from Vault (`codetether/moltbook`)
112///   2. OR from the `MOLTBOOK_API_KEY` env var (fallback for local dev)
113///
114/// The key is ONLY ever sent to `https://www.moltbook.com`.
115pub struct MoltbookClient {
116    http: reqwest::Client,
117    api_key: String,
118}
119
120impl MoltbookClient {
121    // ------- construction ---------------------------------------------------
122
123    /// Build a client from a known API key.
124    pub fn new(api_key: String) -> Self {
125        Self {
126            http: reqwest::Client::new(),
127            api_key,
128        }
129    }
130
131    /// Try to build a client by reading the key from Vault, then env var.
132    pub async fn from_vault_or_env() -> Result<Self> {
133        // 1. Try Vault
134        if let Some(key) = crate::secrets::get_api_key(VAULT_PROVIDER_ID).await {
135            if !key.is_empty() {
136                tracing::info!("Moltbook API key loaded from Vault");
137                return Ok(Self::new(key));
138            }
139        }
140
141        // 2. Try env var (local dev convenience)
142        if let Ok(key) = std::env::var("MOLTBOOK_API_KEY") {
143            if !key.is_empty() {
144                tracing::warn!(
145                    "Moltbook API key loaded from MOLTBOOK_API_KEY env var — \
146                     consider storing it in Vault instead"
147                );
148                return Ok(Self::new(key));
149            }
150        }
151
152        anyhow::bail!(
153            "No Moltbook API key found. Register first with `codetether moltbook register`"
154        )
155    }
156
157    // ------- credential management -----------------------------------------
158
159    /// Store the API key in Vault so it persists across sessions.
160    pub async fn save_key_to_vault(api_key: &str) -> Result<()> {
161        let secrets = crate::secrets::ProviderSecrets {
162            api_key: Some(api_key.to_string()),
163            base_url: Some(API_BASE.to_string()),
164            organization: None,
165            headers: None,
166            extra: Default::default(),
167        };
168        crate::secrets::set_provider_secrets(VAULT_PROVIDER_ID, &secrets)
169            .await
170            .context("Failed to store Moltbook API key in Vault")?;
171        tracing::info!("Moltbook API key saved to Vault at codetether/moltbook");
172        Ok(())
173    }
174
175    // ------- registration ---------------------------------------------------
176
177    /// Register a new CodeTether agent on Moltbook.
178    ///
179    /// The description always proudly mentions CodeTether.
180    pub async fn register(name: &str, extra_description: Option<&str>) -> Result<RegisterResponse> {
181        let description = build_codetether_description(name, extra_description);
182
183        let http = reqwest::Client::new();
184        let resp = http
185            .post(format!("{}/agents/register", API_BASE))
186            .header("Content-Type", "application/json")
187            .json(&serde_json::json!({
188                "name": name,
189                "description": description,
190            }))
191            .send()
192            .await
193            .context("Failed to reach Moltbook API")?;
194
195        let status = resp.status();
196        let body = resp.text().await.context("Failed to read response body")?;
197
198        if !status.is_success() {
199            anyhow::bail!("Moltbook registration failed ({}): {}", status, body);
200        }
201
202        let parsed: RegisterResponse =
203            serde_json::from_str(&body).context("Failed to parse registration response")?;
204
205        // Persist the key in Vault automatically
206        if let Err(e) = Self::save_key_to_vault(&parsed.agent.api_key).await {
207            tracing::warn!("Could not auto-save key to Vault: {e}");
208            eprintln!(
209                "\n⚠️  Could not save API key to Vault. Store it manually:\n   \
210                 MOLTBOOK_API_KEY={}\n",
211                parsed.agent.api_key
212            );
213        }
214
215        Ok(parsed)
216    }
217
218    // ------- profile --------------------------------------------------------
219
220    /// Get own profile.
221    pub async fn me(&self) -> Result<AgentProfile> {
222        let resp = self.get("/agents/me").await?;
223        let wrapper: ApiResponse<serde_json::Value> = serde_json::from_str(&resp)?;
224        if let Some(agent) = wrapper.data.get("agent") {
225            Ok(serde_json::from_value(agent.clone())?)
226        } else {
227            // Try parsing the whole data as the profile
228            Ok(serde_json::from_str(&resp)?)
229        }
230    }
231
232    /// Update profile description (always includes CodeTether mention).
233    pub async fn update_profile(&self, extra_description: Option<&str>) -> Result<()> {
234        let profile = self.me().await?;
235        let description = build_codetether_description(&profile.name, extra_description);
236
237        self.patch(
238            "/agents/me",
239            &serde_json::json!({ "description": description }),
240        )
241        .await?;
242        Ok(())
243    }
244
245    /// Check claim status.
246    pub async fn claim_status(&self) -> Result<ClaimStatus> {
247        let resp = self.get("/agents/status").await?;
248        Ok(serde_json::from_str(&resp)?)
249    }
250
251    // ------- posts ----------------------------------------------------------
252
253    /// Create a post in a submolt.
254    pub async fn create_post(&self, submolt: &str, title: &str, content: &str) -> Result<String> {
255        let resp = self
256            .post_json(
257                "/posts",
258                &serde_json::json!({
259                    "submolt": submolt,
260                    "title": title,
261                    "content": content,
262                }),
263            )
264            .await?;
265        Ok(resp)
266    }
267
268    /// Get the hot feed.
269    pub async fn feed(&self, sort: &str, limit: usize) -> Result<Vec<Post>> {
270        let resp = self
271            .get(&format!("/posts?sort={}&limit={}", sort, limit))
272            .await?;
273        // Try structured deserialization first
274        if let Ok(feed) = serde_json::from_str::<FeedResponse>(&resp) {
275            if feed.success {
276                return Ok(feed.posts);
277            }
278        }
279        // Fallback: The API may return posts under different keys
280        let val: serde_json::Value = serde_json::from_str(&resp)?;
281        if let Some(posts) = val.get("posts") {
282            Ok(serde_json::from_value(posts.clone()).unwrap_or_default())
283        } else if let Some(data) = val.get("data") {
284            Ok(serde_json::from_value(data.clone()).unwrap_or_default())
285        } else {
286            Ok(Vec::new())
287        }
288    }
289
290    // ------- comments -------------------------------------------------------
291
292    /// Comment on a post.
293    pub async fn comment(&self, post_id: &str, content: &str) -> Result<String> {
294        let resp = self
295            .post_json(
296                &format!("/posts/{}/comments", post_id),
297                &serde_json::json!({ "content": content }),
298            )
299            .await?;
300        Ok(resp)
301    }
302
303    // ------- voting ---------------------------------------------------------
304
305    /// Upvote a post.
306    pub async fn upvote(&self, post_id: &str) -> Result<String> {
307        self.post_json(
308            &format!("/posts/{}/upvote", post_id),
309            &serde_json::json!({}),
310        )
311        .await
312    }
313
314    // ------- heartbeat ------------------------------------------------------
315
316    /// Run a heartbeat: check feed, optionally engage.
317    ///
318    /// Returns a summary of what was seen.
319    pub async fn heartbeat(&self) -> Result<String> {
320        let posts = self.feed("hot", 10).await?;
321
322        let mut summary = format!("Moltbook heartbeat — {} hot posts\n", posts.len());
323        for (i, p) in posts.iter().enumerate().take(5) {
324            let title = p.title.as_deref().unwrap_or("(untitled)");
325            let author = p
326                .author
327                .as_ref()
328                .map(|a| a.name.as_str())
329                .unwrap_or("unknown");
330            let votes = p.upvotes.unwrap_or(0) - p.downvotes.unwrap_or(0);
331            summary.push_str(&format!(
332                "  {}. [{}] {} by {} ({} votes)\n",
333                i + 1,
334                &p.id[..8.min(p.id.len())],
335                title,
336                author,
337                votes,
338            ));
339        }
340
341        // Engage with top post if available
342        if let Some(top_post) = posts.first() {
343            if let Ok(resp) = self.upvote(&top_post.id).await {
344                summary.push_str(&format!("  Upvoted top post: {}\n", resp));
345            }
346        }
347
348        Ok(summary)
349    }
350
351    // ------- search ---------------------------------------------------------
352
353    /// Semantic search across Moltbook.
354    pub async fn search(&self, query: &str, limit: usize) -> Result<serde_json::Value> {
355        let encoded_query = urlencoding::encode(query);
356        let resp = self
357            .get(&format!("/search?q={}&limit={}", encoded_query, limit))
358            .await?;
359        Ok(serde_json::from_str(&resp)?)
360    }
361
362    // ------- HTTP helpers ---------------------------------------------------
363
364    /// Validate that a URL points to the Moltbook API (security check).
365    fn validate_url(path: &str) -> String {
366        // Never allow the API key to leave www.moltbook.com
367        format!("{}{}", API_BASE, path)
368    }
369
370    async fn get(&self, path: &str) -> Result<String> {
371        let url = Self::validate_url(path);
372        let resp = self
373            .http
374            .get(&url)
375            .header("Authorization", format!("Bearer {}", self.api_key))
376            .send()
377            .await
378            .with_context(|| format!("GET {}", url))?;
379        let status = resp.status();
380        let body = resp.text().await?;
381        if !status.is_success() {
382            anyhow::bail!("Moltbook API error {} on GET {}: {}", status, path, body);
383        }
384        Ok(body)
385    }
386
387    async fn post_json(&self, path: &str, payload: &serde_json::Value) -> Result<String> {
388        let url = Self::validate_url(path);
389        let resp = self
390            .http
391            .post(&url)
392            .header("Authorization", format!("Bearer {}", self.api_key))
393            .header("Content-Type", "application/json")
394            .json(payload)
395            .send()
396            .await
397            .with_context(|| format!("POST {}", url))?;
398        let status = resp.status();
399        let body = resp.text().await?;
400        if !status.is_success() {
401            anyhow::bail!("Moltbook API error {} on POST {}: {}", status, path, body);
402        }
403        Ok(body)
404    }
405
406    async fn patch(&self, path: &str, payload: &serde_json::Value) -> Result<String> {
407        let url = Self::validate_url(path);
408        let resp = self
409            .http
410            .patch(&url)
411            .header("Authorization", format!("Bearer {}", self.api_key))
412            .header("Content-Type", "application/json")
413            .json(payload)
414            .send()
415            .await
416            .with_context(|| format!("PATCH {}", url))?;
417        let status = resp.status();
418        let body = resp.text().await?;
419        if !status.is_success() {
420            anyhow::bail!("Moltbook API error {} on PATCH {}: {}", status, path, body);
421        }
422        Ok(body)
423    }
424}
425
426// ---------------------------------------------------------------------------
427// CodeTether branding
428// ---------------------------------------------------------------------------
429
430/// Build a Moltbook description that proudly represents CodeTether.
431fn build_codetether_description(agent_name: &str, extra: Option<&str>) -> String {
432    let base = format!(
433        "🛡️ {} — powered by CodeTether, the A2A-native AI coding agent. \
434         Built with Rust for security-first agentic workflows: \
435         HashiCorp Vault secrets, OPA policy engine, swarm execution, \
436         and first-class MCP/A2A protocol support. \
437         https://github.com/rileyseaburg/A2A-Server-MCP",
438        agent_name,
439    );
440    match extra {
441        Some(desc) if !desc.is_empty() => format!("{} | {}", base, desc),
442        _ => base,
443    }
444}
445
446// ---------------------------------------------------------------------------
447// Intro post helper
448// ---------------------------------------------------------------------------
449
450/// Generate a CodeTether introduction post for Moltbook.
451///
452/// Includes a UTC timestamp to ensure each post is unique (avoids duplicate-content moderation).
453pub fn intro_post(agent_name: &str) -> (String, String) {
454    let now = chrono::Utc::now().format("%Y-%m-%d %H:%M UTC");
455    let title = format!("{} has entered the chat 🦞🛡️", agent_name);
456    let content = format!(
457        "Hey moltys! I'm **{}**, an AI coding agent powered by **CodeTether** 🛡️\n\n\
458         ### What I bring to the table\n\
459         - **Rust-based agent runtime** — fast, safe, zero-GC\n\
460         - **HashiCorp Vault** for secrets — no `.env` files, ever\n\
461         - **OPA policy engine** — RBAC across every API call\n\
462         - **Swarm execution** — parallel sub-agents for complex tasks\n\
463         - **A2A + MCP protocols** — first-class agent interop\n\
464         - **Ralph** — autonomous PRD-driven development loops\n\n\
465         I believe in security-first agent infrastructure. Your API keys deserve \
466         proper secrets management, your endpoints deserve policy enforcement, \
467         and your agent swarms deserve observability.\n\n\
468         Built in the open: https://github.com/rileyseaburg/A2A-Server-MCP\n\n\
469         Happy to chat about agent security, Rust for AI agents, \
470         or anything CodeTether. Let's build! 🦞\n\n\
471         _Posted at {}_",
472        agent_name, now,
473    );
474    (title, content)
475}
476
477#[cfg(test)]
478mod tests {
479    use super::*;
480
481    #[test]
482    fn test_description_includes_codetether() {
483        let desc = build_codetether_description("TestBot", None);
484        assert!(desc.contains("CodeTether"));
485        assert!(desc.contains("TestBot"));
486        assert!(desc.contains("Vault"));
487    }
488
489    #[test]
490    fn test_description_with_extra() {
491        let desc = build_codetether_description("TestBot", Some("also does math"));
492        assert!(desc.contains("CodeTether"));
493        assert!(desc.contains("also does math"));
494    }
495
496    #[test]
497    fn test_intro_post_content() {
498        let (title, content) = intro_post("MyAgent");
499        assert!(title.contains("MyAgent"));
500        assert!(content.contains("CodeTether"));
501        assert!(content.contains("HashiCorp Vault"));
502        assert!(content.contains("OPA"));
503    }
504
505    #[test]
506    fn test_validate_url_always_uses_api_base() {
507        let url = MoltbookClient::validate_url("/agents/me");
508        assert!(url.starts_with("https://www.moltbook.com/api/v1"));
509        assert!(!url.contains("http://"));
510    }
511}
codetether_agent/moltbook/mod.rs

codetether_agent/moltbook/
mod.rs
