498 lines
20 KiB
Rust
498 lines
20 KiB
Rust
//! Formatting / render helpers for the MCP tool surface: ack /
|
|
//! loose-end / agent-meta reply shaping plus the retry annotation.
|
|
//! Stateless string builders, with one exception —
|
|
//! [`matrix_unread_summary`] queries `hive-matrix-daemon`'s local
|
|
//! `/unread-summary` status endpoint (best-effort) so `get_loose_ends`
|
|
//! can prepend an unread-rooms entry.
|
|
|
|
/// Render the three identical failure arms every data-returning tool handler
|
|
/// repeats: a broker `Err` → `"{tool} failed: {m}"`, an unexpected `Ok` variant
|
|
/// → `"{tool} unexpected response: …"`, and a transport error → `"{tool}
|
|
/// transport error: …"`. Handlers match their own happy-path variant and route
|
|
/// everything else here via a catch-all arm (`other => reply_err(other, tool)`),
|
|
/// so the triplet lives in exactly one place.
|
|
pub(super) fn reply_err(
|
|
resp: Result<hive_core_agent_sock::Response, anyhow::Error>,
|
|
tool: &str,
|
|
) -> String {
|
|
match resp {
|
|
Ok(hive_core_agent_sock::Response::Err { message }) => format!("{tool} failed: {message}"),
|
|
Ok(other) => format!("{tool} unexpected response: {other:?}"),
|
|
Err(e) => format!("{tool} transport error: {e:#}"),
|
|
}
|
|
}
|
|
|
|
/// Format helper for "send-like" tools (anything that expects an `Ok`).
|
|
/// `tool` and `ok_msg` only appear in the result string; they don't change
|
|
/// behavior.
|
|
#[must_use]
|
|
pub fn format_ack(
|
|
resp: Result<hive_core_agent_sock::Response, anyhow::Error>,
|
|
tool: &str,
|
|
ok_msg: String,
|
|
) -> String {
|
|
match resp {
|
|
Ok(hive_core_agent_sock::Response::Ok) => ok_msg,
|
|
other => reply_err(other, tool),
|
|
}
|
|
}
|
|
|
|
/// Hard cap on how many individual `Todo` lines `render_loose_ends` will
|
|
/// emit. Reminders stay naturally bounded (they're triaged interactively
|
|
/// and don't self-multiply), but todos are pushed by
|
|
/// unattended producers — matrix/bash/forge are the built-in ones, but any
|
|
/// user-configured MCP server can push its own too — an agent that goes a long
|
|
/// stretch without calling `get_loose_ends`, or whose producers outpace its
|
|
/// triage, can accumulate hundreds of them. Rendering all of them
|
|
/// unconditionally risks producing a tool result too large for the MCP
|
|
/// transport to return at all, which is worse than a bug: it's a deadlock
|
|
/// (the agent can't even see what's pending to start clearing it). Capping
|
|
/// here guarantees `get_loose_ends` always returns successfully; the
|
|
/// truncation summary tells the agent to review the shown batch, bulk-clear
|
|
/// the reviewed ids via `mark_todos_done`, then call again for the next
|
|
/// batch — deliberately NOT a "clear everything below id N" range escape
|
|
/// hatch (a reviewer's call: a range-based bulk-ack risks silently
|
|
/// acking something the agent never actually looked at, since todos are
|
|
/// heterogeneous unrelated items, not a sequentially-read stream the way
|
|
/// inbox messages are).
|
|
const MAX_RENDERED_TODOS: usize = 40;
|
|
|
|
/// Render one non-`Todo` [`hive_sh4re::inbox::LooseEnd`] variant onto `out`. Split
|
|
/// out of `render_loose_ends` to keep that function under clippy's
|
|
/// `too_many_lines` limit — `Todo` stays inline there since it also needs
|
|
/// the shared `shown_todos` counter.
|
|
fn render_one_loose_end(out: &mut String, t: &hive_sh4re::inbox::LooseEnd) {
|
|
use std::fmt::Write as _;
|
|
match t {
|
|
hive_sh4re::inbox::LooseEnd::Reminder {
|
|
id,
|
|
owner,
|
|
message,
|
|
due_at,
|
|
age_seconds,
|
|
} => {
|
|
let _ = writeln!(
|
|
out,
|
|
"- reminder #{id} ({owner}, scheduled {age_seconds}s ago, due_at={due_at}): {message}"
|
|
);
|
|
}
|
|
hive_sh4re::inbox::LooseEnd::PendingMessages { count } => {
|
|
let _ = writeln!(
|
|
out,
|
|
"- {count} inbox message(s) queued; the harness delivers them one per turn"
|
|
);
|
|
}
|
|
hive_sh4re::inbox::LooseEnd::UnreadMatrix { rooms, summary } => {
|
|
let _ = write!(out, "- unread matrix messages in {rooms} room(s)");
|
|
if summary.is_empty() {
|
|
let _ = writeln!(
|
|
out,
|
|
" — use list_rooms + read_room to view, mark_read to clear"
|
|
);
|
|
} else {
|
|
let _ = writeln!(out, ":");
|
|
for line in summary.lines() {
|
|
let _ = writeln!(out, " {line}");
|
|
}
|
|
let _ = writeln!(
|
|
out,
|
|
" use list_rooms + read_room to view, mark_read to clear"
|
|
);
|
|
}
|
|
}
|
|
hive_sh4re::inbox::LooseEnd::Todo { .. } => {
|
|
// Handled inline by the caller (needs the shared shown-count).
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Render one `Todo` [`hive_sh4re::inbox::LooseEnd`] onto `out`. Split out for the
|
|
/// same `too_many_lines` reason as [`render_one_loose_end`].
|
|
fn render_todo_loose_end(
|
|
out: &mut String,
|
|
id: i64,
|
|
subsystem: &str,
|
|
subsystem_key: Option<&str>,
|
|
summary: &str,
|
|
source: Option<&str>,
|
|
age_seconds: u64,
|
|
) {
|
|
use std::fmt::Write as _;
|
|
let key = subsystem_key.map(|k| format!(" {k}")).unwrap_or_default();
|
|
let src = source.map(|s| format!(" — {s}")).unwrap_or_default();
|
|
let _ = writeln!(
|
|
out,
|
|
"- todo #{id} [{subsystem}{key}, {age_seconds}s old]: {summary}{src} \
|
|
(cancel_loose_end kind:\"todo\" id:{id} to clear)"
|
|
);
|
|
}
|
|
|
|
/// Inner renderer for a `Vec<LooseEnd>` already extracted from the socket
|
|
/// reply. Called by the `get_loose_ends` handler, which injects the
|
|
/// `UnreadMatrix` entry before formatting.
|
|
pub(super) fn render_loose_ends(loose_ends: &[hive_sh4re::inbox::LooseEnd]) -> String {
|
|
use std::fmt::Write as _;
|
|
if loose_ends.is_empty() {
|
|
return "(no loose ends)".to_owned();
|
|
}
|
|
let mut out = format!("{} loose end(s):\n", loose_ends.len());
|
|
let mut shown_todos = 0usize;
|
|
let mut hidden_todos = 0usize;
|
|
for t in loose_ends {
|
|
let hive_sh4re::inbox::LooseEnd::Todo {
|
|
id,
|
|
subsystem,
|
|
subsystem_key,
|
|
summary,
|
|
source,
|
|
age_seconds,
|
|
} = t
|
|
else {
|
|
render_one_loose_end(&mut out, t);
|
|
continue;
|
|
};
|
|
if shown_todos >= MAX_RENDERED_TODOS {
|
|
hidden_todos += 1;
|
|
continue;
|
|
}
|
|
render_todo_loose_end(
|
|
&mut out,
|
|
*id,
|
|
subsystem,
|
|
subsystem_key.as_deref(),
|
|
summary,
|
|
source.as_deref(),
|
|
*age_seconds,
|
|
);
|
|
shown_todos += 1;
|
|
}
|
|
if hidden_todos > 0 {
|
|
let _ = writeln!(
|
|
out,
|
|
"- {hidden_todos} more todo(s) not shown — clear reviewed ids with \
|
|
mark_todos_done(ids: [...]), then call get_loose_ends again for the rest"
|
|
);
|
|
}
|
|
out
|
|
}
|
|
|
|
/// Per-room unread entry returned by `matrix_unread_summary`. Mirrors
|
|
/// `hive-matrix-mcp`'s `RoomUnread` but defined locally to avoid a
|
|
/// cross-crate dep on the matrix-sdk crate tree.
|
|
#[derive(Debug, serde::Deserialize)]
|
|
pub(super) struct MatrixRoomUnread {
|
|
label: String,
|
|
count: u32,
|
|
last_body: Option<String>,
|
|
last_sender: Option<String>,
|
|
}
|
|
|
|
/// Default port `hive-matrix-daemon` serves its MCP + status endpoints
|
|
/// on (`services.hyperhive.agent.mcp.matrixHttpPort`'s nix default). Overridable via
|
|
/// `HIVE_MATRIX_HTTP_PORT` for parity with the port options nix already
|
|
/// exposes; unset in practice since a single fixed port is safe (each
|
|
/// agent container is its own network namespace — see docs/4-implementation/networking/network.md).
|
|
const DEFAULT_MATRIX_HTTP_PORT: u16 = 8792;
|
|
|
|
/// Short request timeout for the local status query below — this must
|
|
/// never stall a turn waiting on a wedged same-container daemon.
|
|
const MATRIX_STATUS_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(2);
|
|
|
|
/// Query the local matrix daemon's `/unread-summary` status endpoint
|
|
/// for per-room unread summaries. Returns `None` if the daemon isn't
|
|
/// reachable or the query fails. Best-effort: agents without matrix
|
|
/// configured are not penalised.
|
|
pub(super) async fn matrix_unread_summary() -> Option<Vec<MatrixRoomUnread>> {
|
|
let port = std::env::var("HIVE_MATRIX_HTTP_PORT")
|
|
.unwrap_or_else(|_| DEFAULT_MATRIX_HTTP_PORT.to_string());
|
|
let url = format!("http://127.0.0.1:{port}/unread-summary");
|
|
let client = reqwest::Client::builder()
|
|
.timeout(MATRIX_STATUS_TIMEOUT)
|
|
.build()
|
|
.ok()?;
|
|
let val: serde_json::Value = client.get(&url).send().await.ok()?.json().await.ok()?;
|
|
// Response: {"kind":"ok","payload":[{label, count, last_body?, last_sender?}]}
|
|
let arr = val.get("payload")?.as_array()?;
|
|
serde_json::from_value(serde_json::Value::Array(arr.clone())).ok()
|
|
}
|
|
|
|
/// Dial the harness's in-agent socket (`HIVE_AGENT_SOCKET`) with a single
|
|
/// one-shot JSON-line request and decode the response. Returns `None` when
|
|
/// the socket is unset/absent or on any transport/decode failure —
|
|
/// best-effort, single-shot (no retry, unlike the broker's
|
|
/// `client::request_retried`): this socket lives in the SAME container, so
|
|
/// a connect failure means the harness itself isn't up, which a retry
|
|
/// won't fix within a tool call's budget. Shared by [`local_todos`],
|
|
/// [`mark_local_todo_done`], and [`local_reminders`]; `remind`/
|
|
/// `cancel_loose_end`(reminder) in `mod.rs` dial it directly since their
|
|
/// happy path is a plain `Ok`/`Err`, not a `Vec<LooseEnd>` to merge.
|
|
pub(super) async fn dial_agent_socket(
|
|
req: &hive_agent_sock::Request,
|
|
) -> Option<hive_agent_sock::Response> {
|
|
let socket = std::env::var_os("HIVE_AGENT_SOCKET").map(std::path::PathBuf::from)?;
|
|
if !socket.exists() {
|
|
return None;
|
|
}
|
|
dial_socket(&socket, req, AGENT_SOCKET_DEADLINE).await
|
|
}
|
|
|
|
/// Longest a tool call waits on the in-agent socket, connect through reply.
|
|
/// Matches the server's own per-connection request-line deadline: a harness
|
|
/// that accepts and then stalls must not hang the model's turn.
|
|
const AGENT_SOCKET_DEADLINE: std::time::Duration = std::time::Duration::from_secs(30);
|
|
|
|
/// One round trip on the socket at `socket`, abandoned (as `None`) after
|
|
/// `deadline`.
|
|
async fn dial_socket(
|
|
socket: &std::path::Path,
|
|
req: &hive_agent_sock::Request,
|
|
deadline: std::time::Duration,
|
|
) -> Option<hive_agent_sock::Response> {
|
|
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
|
|
use tokio::net::UnixStream;
|
|
tokio::time::timeout(deadline, async {
|
|
let mut stream = UnixStream::connect(socket).await.ok()?;
|
|
let mut line = serde_json::to_string(req).ok()?;
|
|
line.push('\n');
|
|
stream.write_all(line.as_bytes()).await.ok()?;
|
|
let mut lines = BufReader::new(stream).lines();
|
|
let resp_line = lines.next_line().await.ok()??;
|
|
serde_json::from_str(&resp_line).ok()
|
|
})
|
|
.await
|
|
.ok()?
|
|
}
|
|
|
|
/// Query the harness's in-agent socket for this agent's local todos
|
|
/// (loose-ends v2). Returns `None` when `HIVE_AGENT_SOCKET` is unset /
|
|
/// absent or the query fails — best-effort, like [`matrix_unread_summary`],
|
|
/// so an agent without the socket is not penalised.
|
|
pub(super) async fn local_todos() -> Option<Vec<hive_sh4re::inbox::LooseEnd>> {
|
|
match dial_agent_socket(&hive_agent_sock::Request::ListTodos { subsystem: None }).await? {
|
|
hive_agent_sock::Response::LooseEnds { loose_ends } => Some(loose_ends),
|
|
_ => None,
|
|
}
|
|
}
|
|
|
|
/// Query the harness's in-agent socket for this agent's local pending
|
|
/// reminders — was a broker query before reminders moved in-container.
|
|
/// Same best-effort contract as [`local_todos`].
|
|
pub(super) async fn local_reminders() -> Option<Vec<hive_sh4re::inbox::LooseEnd>> {
|
|
match dial_agent_socket(&hive_agent_sock::Request::ListReminders).await? {
|
|
hive_agent_sock::Response::LooseEnds { loose_ends } => Some(loose_ends),
|
|
_ => None,
|
|
}
|
|
}
|
|
|
|
/// Mark one of this agent's local todos (loose-ends v2) done by id, via
|
|
/// the harness's in-agent socket — reachable through `cancel_loose_end`
|
|
/// kind `"todo"` so clearing a todo never has to shell out through a
|
|
/// tracked bash task (which would just spawn a fresh completion todo of
|
|
/// its own). `None` means the socket is unset/absent or unreachable,
|
|
/// distinct from a decoded `Err` response (unknown id) so the caller can
|
|
/// tell the two apart.
|
|
pub(super) async fn mark_local_todo_done(id: i64) -> Option<hive_agent_sock::Response> {
|
|
dial_agent_socket(&hive_agent_sock::Request::MarkTodoDone { id }).await
|
|
}
|
|
|
|
/// Bulk-ack an explicit list of local todo ids, via the harness's in-agent
|
|
/// socket — the multi-id analogue of `mark_local_todo_done`, for the
|
|
/// `mark_todos_done` tool.
|
|
pub(super) async fn mark_local_todos_done(ids: Vec<i64>) -> Option<hive_agent_sock::Response> {
|
|
dial_agent_socket(&hive_agent_sock::Request::MarkTodosDone { ids }).await
|
|
}
|
|
|
|
/// Ask the harness for the text of the audio file at `path`. The harness
|
|
/// waits on the swarm's speech-to-text service, which queues requests behind
|
|
/// one engine slot, so this waits much longer than any other socket call.
|
|
pub(super) async fn transcribe_local(path: String) -> Option<hive_agent_sock::Response> {
|
|
let socket = std::env::var_os("HIVE_AGENT_SOCKET").map(std::path::PathBuf::from)?;
|
|
if !socket.exists() {
|
|
return None;
|
|
}
|
|
dial_socket(
|
|
&socket,
|
|
&hive_agent_sock::Request::Transcribe { path },
|
|
TRANSCRIBE_DEADLINE,
|
|
)
|
|
.await
|
|
}
|
|
|
|
/// Longest a `transcribe_audio` call waits: the service's reply deadline (15
|
|
/// minutes, `swarm_wire::stt::REPLY_DEADLINE`) plus a margin for the harness.
|
|
const TRANSCRIBE_DEADLINE: std::time::Duration = std::time::Duration::from_mins(16);
|
|
|
|
/// Format a `Vec<MatrixRoomUnread>` into a per-room summary string.
|
|
/// Single room / single message collapses to one line; multi-room
|
|
/// expands to a bulleted list. Returns an empty string for empty input.
|
|
pub(super) fn format_matrix_summary(rooms: &[MatrixRoomUnread]) -> String {
|
|
use std::fmt::Write as _;
|
|
if rooms.is_empty() {
|
|
return String::new();
|
|
}
|
|
let mut out = String::new();
|
|
for r in rooms {
|
|
if r.count == 1
|
|
&& let (Some(body), Some(sender)) = (&r.last_body, &r.last_sender)
|
|
{
|
|
let _ = writeln!(out, "- {}: {sender}: {body}", r.label);
|
|
continue;
|
|
}
|
|
let _ = writeln!(out, "- {}: {} unread", r.label, r.count);
|
|
}
|
|
// Remove trailing newline.
|
|
if out.ends_with('\n') {
|
|
out.pop();
|
|
}
|
|
out
|
|
}
|
|
|
|
/// Format helper for `get_agent_meta`: renders an agent's identity +
|
|
/// current status as a short human-readable block. `name`,
|
|
/// `hyperhive_rev`, and `running` are always shown; `status` only
|
|
/// appears when one is set, otherwise the line reads `status: <none>`.
|
|
/// When `running` is false the host has already cleared `status_text`
|
|
/// (it would be a stale snapshot from before the stop) so the status
|
|
/// line is implicitly `<none>` in that case — but the explicit
|
|
/// `running: no` line tells the caller WHY. See
|
|
/// `docs/4-implementation/turn-loop/mcp.md::Core tools` (`get_agent_meta`).
|
|
#[must_use]
|
|
pub fn format_agent_meta(resp: Result<hive_core_agent_sock::Response, anyhow::Error>) -> String {
|
|
match resp {
|
|
Ok(hive_core_agent_sock::Response::AgentMeta {
|
|
name,
|
|
running,
|
|
hyperhive_rev,
|
|
status_text,
|
|
status_set_at,
|
|
hive_name,
|
|
swarm_name,
|
|
matrix_accounts,
|
|
}) => {
|
|
let rev = hyperhive_rev.as_deref().unwrap_or("<unknown>");
|
|
let run = if running { "yes" } else { "no" };
|
|
let mut out = format!("name: {name}\nhyperhive_rev: {rev}\nrunning: {run}");
|
|
// Surface hive + swarm display names only when set, so
|
|
// single-hive deployments don't see noisy `<none>` lines.
|
|
if let Some(hn) = hive_name.as_deref() {
|
|
use std::fmt::Write as _;
|
|
let _ = write!(out, "\nhive_name: {hn}");
|
|
}
|
|
if let Some(sn) = swarm_name.as_deref() {
|
|
use std::fmt::Write as _;
|
|
let _ = write!(out, "\nswarm_name: {sn}");
|
|
}
|
|
match status_text {
|
|
None => out.push_str("\nstatus: <none>"),
|
|
Some(s) => {
|
|
use std::fmt::Write as _;
|
|
let age = status_set_at.and_then(|ts| {
|
|
let now = std::time::SystemTime::now()
|
|
.duration_since(std::time::UNIX_EPOCH)
|
|
.ok()?
|
|
.as_secs();
|
|
// `ts` is a unix epoch second the agent itself
|
|
// sourced from `SystemTime` — always positive
|
|
// in normal operation. Clamp the negative
|
|
// (clock-skew) edge to 0 before the unsigned
|
|
// cast so the cast loses no real precision.
|
|
let ts_secs = u64::try_from(ts).unwrap_or(0);
|
|
let secs = now.saturating_sub(ts_secs);
|
|
Some(format_age_secs(secs))
|
|
});
|
|
// `write!` into the buffer instead of `push_str(&format!(…))` —
|
|
// avoids the intermediate allocation clippy::format_push_string
|
|
// flags. The infallible `String` writer makes this safe to
|
|
// `let _ =`-ignore.
|
|
match age {
|
|
Some(a) => {
|
|
let _ = write!(out, "\nstatus: {s} (set {a} ago)");
|
|
}
|
|
None => {
|
|
let _ = write!(out, "\nstatus: {s}");
|
|
}
|
|
}
|
|
}
|
|
}
|
|
// Matrix identities the agent can act as (the `account` arg on
|
|
// the matrix tools). Listed only when matrix is provisioned, so
|
|
// non-matrix agents don't see an empty line.
|
|
if !matrix_accounts.is_empty() {
|
|
use std::fmt::Write as _;
|
|
out.push_str("\nmatrix_accounts:");
|
|
for acct in &matrix_accounts {
|
|
let uid = acct.user_id.as_deref().unwrap_or("?");
|
|
let _ = write!(out, "\n {} ({uid}) on {}", acct.name, acct.homeserver);
|
|
}
|
|
}
|
|
out
|
|
}
|
|
other => reply_err(other, "get_agent_meta"),
|
|
}
|
|
}
|
|
|
|
/// Format a duration in seconds as a human-readable age string.
|
|
fn format_age_secs(secs: u64) -> String {
|
|
if secs < 60 {
|
|
format!("{secs}s")
|
|
} else if secs < 3600 {
|
|
format!("{}m", secs / 60)
|
|
} else if secs < 86400 {
|
|
format!("{}h", secs / 3600)
|
|
} else {
|
|
format!("{}d", secs / 86400)
|
|
}
|
|
}
|
|
|
|
/// Append a short note to a tool result when the underlying socket call
|
|
/// took retries to land. Lets claude distinguish "my request was wrong"
|
|
/// from "c0re flickered and the harness rode it out" — without the
|
|
/// hint, a tool result that took 30s to come back looks identical to a
|
|
/// content failure and the model would burn a turn retrying it.
|
|
#[must_use]
|
|
pub fn annotate_retries(mut s: String, retries: u32) -> String {
|
|
if retries > 0 {
|
|
use std::fmt::Write as _;
|
|
let suffix = if retries == 1 { "retry" } else { "retries" };
|
|
let _ = write!(
|
|
s,
|
|
"\n\n(note: hive socket connect needed {retries} {suffix} — c0re likely \
|
|
restarted. Your request did succeed on the final attempt; no action needed.)"
|
|
);
|
|
}
|
|
s
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::dial_socket;
|
|
|
|
#[tokio::test]
|
|
async fn a_socket_that_accepts_and_never_answers_is_given_up_on() {
|
|
let path = std::env::temp_dir().join(format!(
|
|
"hive-agent-mcp-dial-test-{}-{}.sock",
|
|
std::process::id(),
|
|
std::time::SystemTime::now()
|
|
.duration_since(std::time::UNIX_EPOCH)
|
|
.unwrap()
|
|
.as_nanos()
|
|
));
|
|
let listener = tokio::net::UnixListener::bind(&path).unwrap();
|
|
// Accept, then hold the connection open without ever replying.
|
|
let _stalled = tokio::spawn(async move {
|
|
let conn = listener.accept().await;
|
|
std::future::pending::<()>().await;
|
|
drop(conn);
|
|
});
|
|
|
|
let resp = dial_socket(
|
|
&path,
|
|
&hive_agent_sock::Request::ListReminders,
|
|
std::time::Duration::from_millis(100),
|
|
)
|
|
.await;
|
|
let _ = std::fs::remove_file(&path);
|
|
|
|
assert!(resp.is_none());
|
|
}
|
|
}
|