refactor(hive-ag3nt): split hive bin into hive-agent / hive-agent-mcp / hive-agent-wake

hive-ag3nt/src/bin/hive-agent-mcp.rs

@@ -0,0 +1,43 @@
+//! MCP-server binary. Default is stdio — spawned by `claude` via
+//! `--mcp-config`; tools dispatch through `/run/hive/mcp.sock` back into
+//! the hyperhive broker. Pass `--http <addr>` to instead run a long-lived
+//! streamable-http listener (persistent daemon, the `hive-mcp-http`
+//! systemd unit) that claude reconnects to each turn, avoiding the
+//! per-turn stdio re-registration race. Sibling of `hive-agent` (the
+//! serve loop that renders the `--mcp-config` blob pointing here) and
+//! `hive-agent-wake`.
+
+use std::path::PathBuf;
+
+use anyhow::Result;
+use clap::Parser;
+use hive_ag3nt::{DEFAULT_SOCKET, mcp};
+
+#[derive(Parser)]
+#[command(name = "hive-agent-mcp", about = "hyperhive MCP server")]
+struct Cli {
+    /// Path to the per-agent MCP socket (bind-mounted from the host).
+    #[arg(long, default_value = DEFAULT_SOCKET)]
+    socket: PathBuf,
+
+    /// Serve over streamable-http on this address (e.g.
+    /// `127.0.0.1:8790`) instead of stdio. Bind loopback only.
+    #[arg(long)]
+    http: Option<std::net::SocketAddr>,
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::try_from_default_env()
+                .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")),
+        )
+        .init();
+
+    let cli = Cli::parse();
+    match cli.http {
+        Some(addr) => mcp::serve_http(cli.socket, addr).await,
+        None => mcp::serve_agent_stdio(cli.socket).await,
+    }
+}

hive-ag3nt/src/bin/hive-agent-wake.rs

@@ -0,0 +1,60 @@
+//! Wake CLI: inject a wake-up event into this container's harness inbox
+//! so the next turn fires with the given body. Intended for extra MCP
+//! servers / helpers (scraper, webhook listener, etc.) that need to
+//! nudge claude on external events; the built-in daemons (matrix, bash)
+//! talk to the socket directly instead. Sibling of `hive-agent` and
+//! `hive-agent-mcp`.
+
+use std::path::PathBuf;
+
+use anyhow::Result;
+use clap::Parser;
+use hive_ag3nt::{DEFAULT_SOCKET, client};
+use hive_sh4re::{AgentRequest, AgentResponse};
+
+#[derive(Parser)]
+#[command(name = "hive-agent-wake", about = "hyperhive harness wake signal")]
+struct Cli {
+    /// Path to the per-agent MCP socket (bind-mounted from the host).
+    #[arg(long, default_value = DEFAULT_SOCKET)]
+    socket: PathBuf,
+
+    #[arg(long)]
+    from: String,
+
+    /// Body of the wake message. Pass `-` to read from stdin.
+    #[arg(long)]
+    body: String,
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::try_from_default_env()
+                .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")),
+        )
+        .init();
+
+    let cli = Cli::parse();
+    let body = if cli.body == "-" {
+        let mut buf = String::new();
+        std::io::Read::read_to_string(&mut std::io::stdin(), &mut buf)?;
+        buf
+    } else {
+        cli.body
+    };
+    let resp: AgentResponse = client::request(
+        &cli.socket,
+        &AgentRequest::Wake {
+            from: cli.from,
+            body,
+        },
+    )
+    .await?;
+    match resp {
+        AgentResponse::Ok => Ok(()),
+        AgentResponse::Err { message } => anyhow::bail!("wake: {message}"),
+        other => anyhow::bail!("wake: unexpected response {other:?}"),
+    }
+}

hive-ag3nt/src/bin/hive-agent.rs

@@ -1,7 +1,9 @@
-//! Unified hyperhive harness binary. Dispatches one of three subcommands
-//! (`serve` / `mcp` / `wake`). There is one role: agent. The `Surface`
+//! Harness serve-loop binary. Long-polls the broker inbox and drives one
+//! claude turn per message. There is one role: agent. The `Surface`
 //! trait + `AgentSurface` zero-sized type tag keeps the turn loop
-//! generic and testable. Architecture lives in
+//! generic and testable. Siblings: `hive-agent-mcp` (the MCP server this
+//! loop points claude at) and `hive-agent-wake` (external wake CLI).
+//! Architecture lives in
 //! [`docs/turn-loop.md::Harness binary shape`](../../../docs/turn-loop.md).
 
 use std::path::{Path, PathBuf};
@@ -9,58 +11,23 @@ use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
 use anyhow::Result;
-use clap::{Parser, Subcommand};
+use clap::Parser;
 use hive_ag3nt::events::{Bus, LiveEvent, TurnState};
 use hive_ag3nt::login::{self, LoginState};
 use hive_ag3nt::turn_stats::TurnStats;
-use hive_ag3nt::{
-    DEFAULT_SOCKET, DEFAULT_WEB_PORT, client, mcp, plugins, serve_common, turn, web_ui,
-};
+use hive_ag3nt::{DEFAULT_SOCKET, DEFAULT_WEB_PORT, client, plugins, serve_common, turn, web_ui};
 use hive_sh4re::{AgentRequest, AgentResponse, HelperEvent, SYSTEM_SENDER};
 
 #[derive(Parser)]
-#[command(name = "hive", about = "hyperhive harness")]
+#[command(name = "hive-agent", about = "hyperhive harness serve loop")]
 struct Cli {
     /// Path to the per-agent MCP socket (bind-mounted from the host).
-    #[arg(long, global = true, default_value = DEFAULT_SOCKET)]
+    #[arg(long, default_value = DEFAULT_SOCKET)]
     socket: PathBuf,
 
-    #[command(subcommand)]
-    cmd: Cmd,
-}
-
-#[derive(Subcommand)]
-enum Cmd {
-    /// Run the long-lived harness loop. Polls inbox; replies via
-    /// `claude --print` when available.
-    Serve {
-        /// Inbox poll interval in milliseconds.
-        #[arg(long, default_value_t = 1000)]
-        poll_ms: u64,
-    },
-    /// Run the MCP server. Default is stdio — spawned by `claude` via
-    /// `--mcp-config`; tools dispatch through `/run/hive/mcp.sock` back
-    /// into the hyperhive broker. Pass `--http <addr>` to instead run a
-    /// long-lived streamable-http listener (persistent daemon) that
-    /// claude reconnects to each turn, avoiding the per-turn stdio
-    /// re-registration race.
-    Mcp {
-        /// Serve over streamable-http on this address (e.g.
-        /// `127.0.0.1:8790`) instead of stdio. Bind loopback only.
-        #[arg(long)]
-        http: Option<std::net::SocketAddr>,
-    },
-    /// Inject a wake-up event into this harness's inbox so the next
-    /// turn fires with the given body. Intended for extra MCP servers
-    /// / helpers (matrix bridge, scraper, webhook listener, etc.) that
-    /// need to nudge claude on external events.
-    Wake {
-        #[arg(long)]
-        from: String,
-        /// Body of the wake message. Pass `-` to read from stdin.
-        #[arg(long)]
-        body: String,
-    },
+    /// Inbox poll interval in milliseconds.
+    #[arg(long, default_value_t = 1000)]
+    poll_ms: u64,
 }
 
 #[tokio::main]
@@ -73,15 +40,7 @@ async fn main() -> Result<()> {
         .init();
 
     let cli = Cli::parse();
-
-    match cli.cmd {
-        Cmd::Serve { poll_ms } => serve_main::<AgentSurface>(&cli.socket, poll_ms).await,
-        Cmd::Mcp { http } => match http {
-            Some(addr) => mcp::serve_http(cli.socket, addr).await,
-            None => mcp::serve_agent_stdio(cli.socket).await,
-        },
-        Cmd::Wake { from, body } => wake::<AgentSurface>(&cli.socket, from, body).await,
-    }
+    serve_main::<AgentSurface>(&cli.socket, cli.poll_ms).await
 }
 
 // ---------- shared turn helpers ----------
@@ -261,13 +220,6 @@ trait Surface {
     /// generic `serve_loop` doesn't need the per-role Response enum
     /// at all.
     fn recv_next(socket: &Path) -> impl Future<Output = RecvOutcome>;
-
-    /// External `wake` subcommand (the `hive wake` CLI command, used
-    /// by co-process daemons like matrix to push events into the
-    /// harness inbox). Errors out via `anyhow::bail!` so the calling
-    /// binary surfaces them on stderr.
-    fn wake_external(socket: &Path, from: String, body: String)
-    -> impl Future<Output = Result<()>>;
 }
 
 // ---------- AgentSurface ----------
@@ -383,16 +335,6 @@ impl Surface for AgentSurface {
             }
         }
     }
-
-    async fn wake_external(socket: &Path, from: String, body: String) -> Result<()> {
-        let resp: AgentResponse =
-            client::request(socket, &AgentRequest::Wake { from, body }).await?;
-        match resp {
-            AgentResponse::Ok => Ok(()),
-            AgentResponse::Err { message } => anyhow::bail!("wake: {message}"),
-            other => anyhow::bail!("wake: unexpected response {other:?}"),
-        }
-    }
 }
 
 // ---------- generic turn loop ----------
@@ -673,20 +615,6 @@ async fn handle_turn<S: Surface>(
     }
 }
 
-/// External `hive wake` subcommand — push a message into our own
-/// inbox so the next turn fires with the given body. Reads the body
-/// from stdin when `body == "-"`.
-async fn wake<S: Surface>(socket: &Path, from: String, body: String) -> Result<()> {
-    let body = if body == "-" {
-        let mut buf = String::new();
-        std::io::Read::read_to_string(&mut std::io::stdin(), &mut buf)?;
-        buf
-    } else {
-        body
-    };
-    S::wake_external(socket, from, body).await
-}
-
 #[cfg(test)]
 mod continue_tests {
     use super::{TurnControl, should_self_continue, synthetic_continue};