vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(#2659): serve hive-bash-mcp over persistent streamable-http, drop stdio bridge

Browse source
This commit is contained in:
damocles 2026-07-23 17:34:02 +02:00 • committed by mara
commit c4fcf7fbf1
26 changed files with 376 additions and 574 deletions
Download patch file Download diff file Expand all files Collapse all files

321
hive-bash-mcp/src/mcp.rs Normal file
View file

@ -0,0 +1,321 @@
//! MCP tool surface for `hive-bash-daemon`, served directly over
//! streamable-http — no stdio bridge, no round-trip socket. The daemon
//! already owns the subprocess runner in-process, so the tool handlers
//! below call straight into [`crate::runner`]. Mirrors
//! `hive-agent-mcp::mcp::serve_http`'s shape (persistent daemon, stable
//! URL claude reconnects to every turn instead of respawning a stdio
//! child).
use std::fmt::Write as _;
use rmcp::{
ServerHandler,
handler::server::wrapper::Parameters,
schemars::{self, JsonSchema},
tool, tool_handler, tool_router,
};
use serde::Deserialize;
use crate::protocol::{TaskFile, TaskStatus};
use crate::runner::{self, SUMMARY_BYTES};
fn status_str(status: &TaskStatus) -> &'static str {
match status {
TaskStatus::Pending => "pending",
TaskStatus::Running => "running",
TaskStatus::Done => "done",
TaskStatus::TimedOut => "timed_out",
TaskStatus::Interrupted => "interrupted",
TaskStatus::Killed => "killed",
}
}
/// Format a `TaskFile` as the human-readable status string claude sees.
fn format_task(task: &TaskFile) -> String {
let mut out = format!("task `{}`: status={}", task.id, status_str(&task.status));
if let Some(code) = task.exit_code {
let _ = write!(out, ", exit={code}");
}
if let (Some(started), None) = (task.started_at, task.completed_at) {
let now = hive_sh4re::wire_time::now_unix();
let _ = write!(out, ", running for {}s", now - started);
}
if let (Some(completed), Some(started)) = (task.completed_at, task.started_at) {
let _ = write!(out, ", took {}s", completed - started);
}
let out_file = crate::paths::task_out(&task.id);
let err_file = crate::paths::task_err(&task.id);
let out_len = std::fs::metadata(&out_file).map_or(0, |m| m.len());
let err_len = std::fs::metadata(&err_file).map_or(0, |m| m.len());
if let Some(stdout) = &task.stdout_tail {
let s = stdout.trim();
if !s.is_empty() {
let _ = write!(out, "\n\nstdout:\n```\n{s}\n```");
}
}
if out_len > SUMMARY_BYTES as u64 {
let _ = write!(out, "\n\nFull stdout lives in `{}`", out_file.display());
}
if let Some(stderr) = &task.stderr_tail {
let s = stderr.trim();
if !s.is_empty() {
let _ = write!(out, "\n\nstderr:\n```\n{s}\n```");
}
}
if err_len > SUMMARY_BYTES as u64 {
let _ = write!(out, "\n\nFull stderr lives in `{}`", err_file.display());
}
out
}
/// Appended to a `status` result when the caller parked on a
/// `wait_seconds` poll that expired while the task was still running —
/// nudges the model to spend the idle time on other work instead of
/// immediately re-waiting on the same task.
const BASH_IDLE_WAIT_HINT: &str = "\n\nThe task is still running — your wait timed out before it \
finished. If you have other useful work, do that and check back later (the task keeps running, and \
it surfaces in your loose-ends when it completes) rather than immediately re-waiting.";
// ---------------------------------------------------------------------------
// MCP server
// ---------------------------------------------------------------------------
#[derive(Debug, Deserialize, JsonSchema)]
struct BashRunArgs {
/// Shell command to run (passed to `bash -c`).
cmd: String,
/// Timeout in seconds. Defaults to `None` (no timeout) — task runs until
/// natural exit. Pass an explicit value to kill the task after N seconds
/// and mark it `timed_out`.
#[serde(default)]
timeout_secs: Option<u64>,
/// Optional inline wait: `run` polls for up to `wait_seconds`
/// (capped at 30) before returning. When the task finishes within the
/// window the full status is returned immediately (nothing to handle
/// later); when the timeout expires the task keeps running and the
/// normal `task started: id=<id>` response is returned. Defaults to 3s.
/// Pass `0` to disable inline waiting and always get the immediate response.
#[serde(default = "default_wait")]
wait_seconds: Option<u64>,
/// Optional task name. When set it becomes the task id, so it appears
/// in `status` lookups and your loose-ends list — handy for recognising
/// a task later instead of an opaque hex id. A name can be reused once
/// its previous task has finished; reusing a name whose task is still
/// running is rejected. Allowed chars: `[a-z0-9-]` (a valid
/// identifier — lowercase, digits, hyphen; max 63). Omit to get the
/// auto-generated id.
#[serde(default)]
name: Option<String>,
}
#[allow(
clippy::unnecessary_wraps,
reason = "serde `#[serde(default = ...)]` requires the default fn's return type to match the field's `Option<u64>`, so the `Some` wrap is mandatory even though the value is constant"
)]
fn default_wait() -> Option<u64> {
Some(3)
}
#[derive(Debug, Deserialize, JsonSchema)]
struct BashStatusArgs {
/// Task ID returned by `run`.
id: String,
/// Optional inline wait: `status` polls for up to `wait_seconds`
/// (capped at 30) before returning. Useful to avoid a separate
/// round-trip when the task is expected to finish soon.
#[serde(default)]
wait_seconds: Option<u64>,
}
#[derive(Debug, Deserialize, JsonSchema)]
struct BashKillArgs {
/// Task ID (from `run`) to kill.
id: String,
/// `false` (default): SIGINT to the task's process group — graceful, the
/// process can clean up. `true`: SIGKILL. Either way the whole process
/// group is signalled, so children of the shell (e.g. a `cargo`/`nix`
/// invocation) are stopped too, not just the shell. Fire-and-forget: the
/// call sends the signal and returns without waiting. If a SIGINT'd task
/// doesn't exit, call `kill` again with `force: true` to send SIGKILL.
#[serde(default)]
force: bool,
}
#[derive(Clone)]
struct BashMcp;
#[tool_router]
impl BashMcp {
#[tool(
description = "Run a shell command in the background. Returns a task ID immediately — \
do NOT wait inline. When the command finishes it surfaces as a todo in your \
loose-ends (the exit status plus a `Read(<path>)` pointer to the captured \
`.out`/`.err` files — read only what you need); handle it on a future turn. Use \
`status` to poll within the same turn if needed. `timeout_secs` defaults to \
`None` (no timeout) — task runs until natural exit; pass a value to kill after \
N seconds. Pass `wait_seconds` (capped at 30) to wait inline for fast commands: \
if the task finishes within the window you get the full status immediately \
(nothing to handle later); otherwise it keeps running and you get \
`task started: id=<id>`. Defaults to 3; pass `0` to disable inline waiting. \
Pass `name` to label the task with a memorable id (shown in `status` lookups \
and your loose-ends) instead of an opaque hex id; reusable once the prior task \
has finished, rejected while one is still running."
)]
async fn run(&self, Parameters(args): Parameters<BashRunArgs>) -> String {
let id = match runner::submit_task(args.cmd, args.timeout_secs, args.name) {
Ok(id) => id,
Err(e) => return format!("bash_run error: {e:#}"),
};
let wait = args.wait_seconds.unwrap_or(0);
if wait > 0
&& let Some(task) = runner::wait_for_task(&id, wait).await
&& matches!(
task.status,
TaskStatus::Done
| TaskStatus::TimedOut
| TaskStatus::Interrupted
| TaskStatus::Killed
)
{
return format_task(&task);
}
format!("task started: id={id}")
}
#[tool(
description = "Check the status of a background bash task by its ID (from `run`). \
Returns the current status (pending/running/done/timed_out/interrupted/killed), exit \
code if finished, and a tail of stdout/stderr. Full output lives in \
`harness/bash-tasks/<id>.out` / `.err`. \
Pass `wait_seconds` (capped at 30) to wait inline for the task to finish: when the \
task finishes within the window the full status is returned immediately. Useful to \
avoid a separate round-trip when the task is expected to finish soon."
)]
async fn status(&self, Parameters(args): Parameters<BashStatusArgs>) -> String {
let waited = args.wait_seconds.is_some_and(|w| w > 0);
let wait = args.wait_seconds.unwrap_or(0);
let task = if wait > 0 {
runner::wait_for_task(&args.id, wait).await
} else {
runner::read_task(&args.id)
};
match task {
Some(t) => {
let mut out = format_task(&t);
if waited && matches!(t.status, TaskStatus::Pending | TaskStatus::Running) {
out.push_str(BASH_IDLE_WAIT_HINT);
}
out
}
None => format!("unknown task id `{}`", args.id),
}
}
#[tool(
description = "Kill a background bash task you started (by its ID from `run`). \
`force: false` (default) sends SIGINT — graceful, lets the process clean up; \
`force: true` sends SIGKILL. Either way the task's whole process group is \
signalled, so a runaway child (cargo/nix/etc.) is stopped too, not just the shell. \
Fire-and-forget: sends the signal and returns without waiting. If a SIGINT'd task \
doesn't exit, call kill again with `force: true` to SIGKILL. A still-pending task \
is cancelled before it starts. The task ends as `killed` and surfaces in your \
loose-ends like any completion."
)]
async fn kill(&self, Parameters(args): Parameters<BashKillArgs>) -> String {
let (killed, was_running) = runner::kill_task(&args.id, args.force);
if !killed {
return format!(
"no running or pending task with id `{}` (already finished or unknown)",
args.id
);
}
if was_running {
let sig = if args.force { "SIGKILL" } else { "SIGINT" };
format!(
"task `{}`: {sig} sent to its process group; it transitions to `killed` \
once the process exits and then surfaces in your loose-ends.",
args.id
)
} else {
format!(
"task `{}` was pending — cancelled before it started.",
args.id
)
}
}
}
#[tool_handler]
impl ServerHandler for BashMcp {}
/// Run the MCP server over HTTP (rmcp streamable-http transport) on `addr`.
///
/// Sole transport — there is no stdio mode. Long-lived so claude
/// reconnects to the stable URL each turn instead of respawning a stdio
/// child; since the daemon already owns [`crate::runner`] in-process,
/// tool calls need no round-trip to anywhere.
///
/// Binds loopback only in practice; the default `allowed_hosts`
/// (`localhost`/`127.0.0.1`/`::1`) rejects Host headers from anywhere else.
///
/// # Errors
///
/// Returns an error if the listener cannot bind `addr` or the HTTP server
/// exits with a fatal error.
pub async fn serve_http(addr: std::net::SocketAddr) -> anyhow::Result<()> {
use rmcp::transport::streamable_http_server::{
StreamableHttpServerConfig, StreamableHttpService, session::local::LocalSessionManager,
};
let session_manager = std::sync::Arc::new(LocalSessionManager::default());
let service = StreamableHttpService::new(
|| Ok(BashMcp),
session_manager,
StreamableHttpServerConfig::default(),
);
let app = axum::Router::new().nest_service("/mcp", service);
let listener = tokio::net::TcpListener::bind(addr).await?;
tracing::info!(%addr, "serving hive-bash MCP over streamable-http at /mcp");
axum::serve(listener, app).await?;
Ok(())
}
#[cfg(test)]
mod status_hint_tests {
use super::{BASH_IDLE_WAIT_HINT, format_task};
use crate::protocol::{TaskFile, TaskStatus};
fn task(status: TaskStatus) -> TaskFile {
TaskFile {
id: "t1".to_owned(),
cmd: "echo hi".to_owned(),
timeout_secs: None,
status,
created_at: 1,
started_at: Some(1),
completed_at: None,
exit_code: None,
stdout_tail: None,
stderr_tail: None,
}
}
#[test]
fn running_task_after_wait_appends_idle_hint() {
let t = task(TaskStatus::Running);
let mut out = format_task(&t);
out.push_str(BASH_IDLE_WAIT_HINT);
assert!(out.contains(BASH_IDLE_WAIT_HINT));
}
#[test]
fn done_task_formats_without_hint() {
let out = format_task(&task(TaskStatus::Done));
assert!(!out.contains(BASH_IDLE_WAIT_HINT));
assert!(out.contains("status=done"));
}
}