agent: embedded MCP server (rmcp) with send/recv tools

hive-ag3nt/src/mcp.rs

@@ -0,0 +1,103 @@
+//! Embedded MCP server. Claude Code (running inside the agent container)
+//! launches this as a stdio child via `--mcp-config`; tool calls land here
+//! and are translated to `AgentRequest::Send`/`Recv` against hyperhive's
+//! own per-agent unix socket at `/run/hive/mcp.sock`.
+//!
+//! Two protocols, two surfaces:
+//! - **hyperhive socket** at `/run/hive/mcp.sock` — JSON-line, our
+//!   broker-routed Send/Recv. Unaffected by this module.
+//! - **MCP stdio** owned by this module — what claude actually speaks.
+//!
+//! The agent surface today is intentionally tiny (send/recv); the manager
+//! surface (Phase 8 follow-up) will add `request_spawn`, `request_kill`,
+//! `request_apply_commit`.
+
+use std::path::PathBuf;
+
+use anyhow::Result;
+use rmcp::{
+    ServerHandler, ServiceExt,
+    handler::server::wrapper::Parameters,
+    schemars, tool, tool_handler, tool_router,
+    transport::stdio,
+};
+
+use crate::client;
+
+#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
+pub struct SendArgs {
+    /// Logical agent name to deliver the message to (e.g. `"manager"`,
+    /// `"alice"`, or the literal `"operator"` for the dashboard's T4LK box).
+    pub to: String,
+    /// Message body. Plain text; the broker doesn't parse it.
+    pub body: String,
+}
+
+#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
+pub struct RecvArgs {}
+
+/// Per-agent tool surface. Holds the socket path so each tool call doesn't
+/// re-derive it; the socket itself is the per-container `/run/hive/mcp.sock`.
+#[derive(Debug, Clone)]
+pub struct AgentServer {
+    socket: PathBuf,
+}
+
+impl AgentServer {
+    #[must_use]
+    pub fn new(socket: PathBuf) -> Self {
+        Self { socket }
+    }
+}
+
+#[tool_router]
+impl AgentServer {
+    #[tool(
+        description = "Send a message to another hyperhive agent (or to the operator). \
+            Use this to talk to peers or to surface output for the human at the dashboard."
+    )]
+    async fn send(&self, Parameters(args): Parameters<SendArgs>) -> String {
+        let req = hive_sh4re::AgentRequest::Send {
+            to: args.to.clone(),
+            body: args.body,
+        };
+        match client::request::<_, hive_sh4re::AgentResponse>(&self.socket, &req).await {
+            Ok(hive_sh4re::AgentResponse::Ok) => format!("sent to {}", args.to),
+            Ok(hive_sh4re::AgentResponse::Err { message }) => format!("send failed: {message}"),
+            Ok(other) => format!("send unexpected response: {other:?}"),
+            Err(e) => format!("send transport error: {e:#}"),
+        }
+    }
+
+    #[tool(
+        description = "Pop one message from this agent's inbox. Returns the sender and body, \
+            or an empty marker if nothing is waiting."
+    )]
+    async fn recv(&self, Parameters(_): Parameters<RecvArgs>) -> String {
+        let req = hive_sh4re::AgentRequest::Recv;
+        match client::request::<_, hive_sh4re::AgentResponse>(&self.socket, &req).await {
+            Ok(hive_sh4re::AgentResponse::Message { from, body }) => {
+                format!("from: {from}\n\n{body}")
+            }
+            Ok(hive_sh4re::AgentResponse::Empty) => "(empty)".into(),
+            Ok(hive_sh4re::AgentResponse::Err { message }) => format!("recv failed: {message}"),
+            Ok(other) => format!("recv unexpected response: {other:?}"),
+            Err(e) => format!("recv transport error: {e:#}"),
+        }
+    }
+}
+
+#[tool_handler(
+    instructions = "You are a hyperhive agent. Use `send` to talk to peers (by their logical \
+        name) or to the operator (recipient `operator`). Use `recv` to drain your inbox one \
+        message at a time."
+)]
+impl ServerHandler for AgentServer {}
+
+/// Run the MCP server over stdio. Returns when the client disconnects.
+pub async fn serve_stdio(socket: PathBuf) -> Result<()> {
+    let server = AgentServer::new(socket);
+    let service = server.serve(stdio()).await?;
+    service.waiting().await?;
+    Ok(())
+}