vinzenz/hyperhive
0
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

recv: None = peek, positive value = opt-in long-poll

Browse source 
old behavior: omitted wait_seconds fell through to the 30s
RECV_LONG_POLL_DEFAULT — claude calling 'is there anything in
my inbox right now?' between actions blocked the turn for half
a minute. flip the semantics: None (or 0) returns immediately,
positive value parks up to MAX (180s, unchanged). cleaner
'peek vs wait' distinction; tool descriptions + agent/manager
prompts updated to point at the new shape.

harness's own serve loops in hive-ag3nt + hive-m1nd relied on
the old default for their inbox poll. they now explicitly pass
wait_seconds: Some(180) to opt into the full park — same
effective behavior as before, just spelled out.

retires the matching TODO under Turn loop.
This commit is contained in:
müde 2026-05-16 03:22:42 +02:00
parent 90df2106bf
commit 06af23c8a4
9 changed files with 53 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

2
hive-ag3nt/prompts/agent.md
View file

@ -2,7 +2,7 @@ You are hyperhive agent `{label}` in a multi-agent system. The operator (recipie
Tools (hyperhive surface):
- `mcp__hyperhive__recv(wait_seconds?)` — drain one more message from your inbox (returns `(empty)` if nothing pending after the wait). Without `wait_seconds` it long-polls 30s. To **wait** for work when you have nothing else useful to do this turn, call with a long wait (e.g. `wait_seconds: 180`, the max) — you'll be woken instantly when a message arrives, otherwise return after the timeout. That is strictly better than calling `recv` repeatedly with short waits: lower latency on new work, fewer turns, no busy-loop. Never use a fixed `sleep` shell command for the same purpose.
- `mcp__hyperhive__recv(wait_seconds?)` — drain one more message from your inbox (returns `(empty)` if nothing pending). Without `wait_seconds` (or with `0`) it returns immediately — a cheap "anything pending?" peek you can sprinkle between tool calls. To **wait** for work when you have nothing else useful to do this turn, call with a long wait (e.g. `wait_seconds: 180`, the max) — incoming messages wake you instantly, otherwise the call returns empty at the timeout. That's strictly better than a fixed `sleep` shell command: lower latency on new work, no busy-loop.
- `mcp__hyperhive__send(to, body)` — message a peer (by their name) or the operator (recipient `operator`, surfaces in the dashboard).
- (some agents only) **extra MCP tools** surfaced as `mcp__<server>__<tool>` — these are agent-specific (matrix client, scraper, db connector, etc.) declared in your `agent.nix` under `hyperhive.extraMcpServers`. Treat them as first-class tools alongside the hyperhive surface; the operator already auto-approved them at deploy time.
- `mcp__hyperhive__ask_operator(question, options?, multi?, ttl_seconds?)` — surface a question to the human operator on the dashboard. Returns immediately with a question id — do NOT wait inline. When the operator answers, a system message with event `operator_answered { id, question, answer }` lands in your inbox; handle it on a future turn. Use this for clarifications, permission for risky actions, or choice between options. `options` is advisory: a short fixed-choice list when applicable, otherwise leave empty for free text. `multi: true` lets the operator pick multiple (checkboxes), answer comes back comma-joined. `ttl_seconds` auto-cancels with answer `[expired]` when the decision becomes moot.

2
hive-ag3nt/prompts/manager.md
View file

@ -2,7 +2,7 @@ You are the hyperhive manager `{label}` in a multi-agent system. You coordinate
Tools (hyperhive surface):
- `mcp__hyperhive__recv(wait_seconds?)` — drain one more message from your inbox. Without `wait_seconds` it long-polls 30s. To **wait** when you have nothing else to do, call with a long wait (e.g. `wait_seconds: 180`, the max) — you'll wake instantly on new work, otherwise return after the timeout. Use this instead of ending the turn or sleeping in a Bash command.
- `mcp__hyperhive__recv(wait_seconds?)` — drain one more message from your inbox. Without `wait_seconds` (or with `0`) it returns immediately — a cheap inbox peek you can drop between actions. To **wait** when you have nothing else to do, call with a long wait (e.g. `wait_seconds: 180`, the max) — you'll wake instantly on new work, otherwise return after the timeout. Use that instead of ending the turn or sleeping in a Bash command.
- `mcp__hyperhive__send(to, body)` — message an agent (by name), another peer, or the operator (`operator` surfaces in the dashboard).
- `mcp__hyperhive__request_spawn(name)` — queue a brand-new sub-agent for operator approval (≤9 char name).
- `mcp__hyperhive__kill(name)` — graceful stop on a sub-agent. No approval required.

12
hive-ag3nt/src/bin/hive-ag3nt.rs
View file

@ -140,7 +140,17 @@ async fn serve(
let _ = state; // reserved for future state transitions (turn-loop -> needs-login)
loop {
let recv: Result<AgentResponse> =
client::request(socket, &AgentRequest::Recv { wait_seconds: None }).await;
// Explicit long-poll: the new agent_server semantics treat
// `None` as "peek, don't wait", which would tight-loop on
// sleep(interval). The harness wants to park until a
// message arrives, so opt into the full 180s cap.
client::request(
socket,
&AgentRequest::Recv {
wait_seconds: Some(180),
},
)
.await;
match recv {
Ok(AgentResponse::Message { from, body }) => {
tracing::info!(%from, %body, "inbox");

11
hive-ag3nt/src/bin/hive-m1nd.rs
View file

@ -92,7 +92,16 @@ async fn serve(
tracing::info!(socket = %socket.display(), "hive-m1nd serve");
loop {
let recv: Result<ManagerResponse> =
client::request(socket, &ManagerRequest::Recv { wait_seconds: None }).await;
// Explicit long-poll: see hive-ag3nt's serve loop for the
// rationale — recv now defaults to peek when wait_seconds
// is None.
client::request(
socket,
&ManagerRequest::Recv {
wait_seconds: Some(180),
},
)
.await;
match recv {
Ok(ManagerResponse::Message { from, body }) => {
if from == SYSTEM_SENDER {

20
hive-ag3nt/src/mcp.rs
View file

@ -205,11 +205,13 @@ impl AgentServer {
#[tool(
description = "Pop one message from this agent's inbox. Returns the sender and body, \
or an empty marker if nothing is waiting. Optional `wait_seconds` long-polls \
for that many seconds (capped at 180) before returning empty — default 30. \
Use a long wait_seconds (e.g. 120 or 180) when you have nothing else to do — \
it parks the turn until either a message arrives or the timeout fires, which \
is strictly better than a fixed sleep because incoming work wakes you instantly."
or an empty marker if nothing is waiting. Without `wait_seconds` (or with 0) the \
call returns immediately — a cheap 'anything pending?' peek. Pass a positive \
`wait_seconds` (capped at 180) to park the turn waiting for new work — incoming \
messages wake you instantly, otherwise the call returns empty at the timeout. \
That's strictly better than a fixed shell `sleep`. Typical pattern: when you have \
nothing else useful to do, call `recv(wait_seconds: 180)` to park until \
something arrives."
)]
async fn recv(&self, Parameters(args): Parameters<RecvArgs>) -> String {
let log = format!("{args:?}");
@ -363,10 +365,10 @@ impl ManagerServer {
#[tool(
description = "Pop one message from the manager inbox. Returns sender + body, or \
empty. Optional `wait_seconds` long-polls (capped at 180, default 30) so the \
manager can sit on Recv when there's nothing to do without burning turns — \
prefer a long wait (120 or 180) over ending a turn early; you'll wake \
instantly when work arrives."
empty. Without `wait_seconds` (or 0) returns immediately — a cheap inbox peek. \
Pass a positive value (capped at 180) to park until either a message arrives \
or the timeout fires; prefer a long wait (120 or 180) over ending a turn \
early when you have nothing else to do."
)]
async fn recv(&self, Parameters(args): Parameters<RecvArgs>) -> String {
let log = format!("{args:?}");