hive-sh4re: per-agent socket protocol (Message/AgentRequest/AgentResponse)

hive-sh4re/src/lib.rs

@@ -2,7 +2,11 @@
 
 use serde::{Deserialize, Serialize};
 
-/// Requests on the host admin socket (`/run/hyperhive/host.sock`).
+// -----------------------------------------------------------------------------
+// Host admin socket — /run/hyperhive/host.sock
+// -----------------------------------------------------------------------------
+
+/// Requests on the host admin socket.
 ///
 /// Wire format: one JSON object per line.
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -52,3 +56,41 @@ impl HostResponse {
         }
     }
 }
+
+// -----------------------------------------------------------------------------
+// Per-agent socket — /run/hyperhive/agents/<name>/mcp.sock on the host,
+// bind-mounted into the container at /run/hive/mcp.sock.
+// -----------------------------------------------------------------------------
+
+/// A logical message between agents.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Message {
+    pub from: String,
+    pub to: String,
+    pub body: String,
+}
+
+/// Requests on a per-agent socket. The agent's identity is the socket
+/// it came in on; `Send.from` is filled in by the server, not the client.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "cmd", rename_all = "snake_case")]
+pub enum AgentRequest {
+    /// Send a message to another agent.
+    Send { to: String, body: String },
+    /// Pop one pending message from this agent's inbox.
+    Recv,
+}
+
+/// Responses on a per-agent socket.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum AgentResponse {
+    /// `Send` succeeded.
+    Ok,
+    /// Either `Send` failed or `Recv` errored.
+    Err { message: String },
+    /// `Recv` produced a message.
+    Message { from: String, body: String },
+    /// `Recv` found nothing pending.
+    Empty,
+}