diff --git a/TODO.md b/TODO.md index 3fc599a..3933ba5 100644 --- a/TODO.md +++ b/TODO.md @@ -3,21 +3,6 @@ Pick anything from here when relevant. Cross-cutting design notes live in [CLAUDE.md](CLAUDE.md); high-level project intro in [README.md](README.md). -## Turn loop - -- **`recv` with no `wait_seconds` should return immediately.** - Today omitting the argument falls through to the 30s - default long-poll (`RECV_LONG_POLL_DEFAULT` in - `hive-c0re/src/agent_server.rs`); a manager that wants a - cheap "anything in the inbox right now?" peek has to - explicitly pass `wait_seconds: 0`. Flip the semantics so - `None` = no sleep, returning `None` (or the empty inbox - shape) right away. The agent opts into the long-poll by - setting a positive value. Update both `AgentRequest::Recv` - and `ManagerRequest::Recv` handlers + the prompt language - in `prompts/{agent,manager}.md`. Tighten the cap (180s) - too — only meaningful when the agent is choosing to wait. - ## Permissions / policy - **Per-agent send allow-list.** Today any agent can `send` to any diff --git a/docs/turn-loop.md b/docs/turn-loop.md index daca2b8..83a1f1e 100644 --- a/docs/turn-loop.md +++ b/docs/turn-loop.md @@ -102,11 +102,11 @@ it as a stdio child via `--mcp-config`. The hyperhive socket name is - `send(to, body)` — message a peer (logical agent name), another agent, or the operator (recipient `operator`, surfaces in the dashboard inbox). -- `recv(wait_seconds?)` — drain one inbox message. Long-polls - server-side; `wait_seconds` is capped at 180 (default 30 when - omitted). Agents use a long wait to park their turn waiting for - work instead of busy-looping with short polls — they wake - instantly when a message arrives. +- `recv(wait_seconds?)` — drain one inbox message. Without + `wait_seconds` (or with `0`) returns immediately, a cheap + "anything pending?" peek. Positive value parks the turn up + to that many seconds (cap 180) — incoming messages wake + instantly, otherwise returns empty at the timeout. - `ask_operator(question, options?, multi?, ttl_seconds?)` — surface a question on the dashboard. Same shape as the manager's; answer routes back to the asker's own inbox as diff --git a/hive-ag3nt/prompts/agent.md b/hive-ag3nt/prompts/agent.md index b3d4d20..88a2d69 100644 --- a/hive-ag3nt/prompts/agent.md +++ b/hive-ag3nt/prompts/agent.md @@ -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____` — 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. diff --git a/hive-ag3nt/prompts/manager.md b/hive-ag3nt/prompts/manager.md index 37485e3..84f0b52 100644 --- a/hive-ag3nt/prompts/manager.md +++ b/hive-ag3nt/prompts/manager.md @@ -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. diff --git a/hive-ag3nt/src/bin/hive-ag3nt.rs b/hive-ag3nt/src/bin/hive-ag3nt.rs index bd87393..23f3c9b 100644 --- a/hive-ag3nt/src/bin/hive-ag3nt.rs +++ b/hive-ag3nt/src/bin/hive-ag3nt.rs @@ -140,7 +140,17 @@ async fn serve( let _ = state; // reserved for future state transitions (turn-loop -> needs-login) loop { let recv: Result = - 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"); diff --git a/hive-ag3nt/src/bin/hive-m1nd.rs b/hive-ag3nt/src/bin/hive-m1nd.rs index 9e50806..42062e5 100644 --- a/hive-ag3nt/src/bin/hive-m1nd.rs +++ b/hive-ag3nt/src/bin/hive-m1nd.rs @@ -92,7 +92,16 @@ async fn serve( tracing::info!(socket = %socket.display(), "hive-m1nd serve"); loop { let recv: Result = - 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 { diff --git a/hive-ag3nt/src/mcp.rs b/hive-ag3nt/src/mcp.rs index d8831b4..fa87b57 100644 --- a/hive-ag3nt/src/mcp.rs +++ b/hive-ag3nt/src/mcp.rs @@ -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) -> 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) -> String { let log = format!("{args:?}"); diff --git a/hive-c0re/src/agent_server.rs b/hive-c0re/src/agent_server.rs index c12e02c..564b150 100644 --- a/hive-c0re/src/agent_server.rs +++ b/hive-c0re/src/agent_server.rs @@ -81,19 +81,20 @@ async fn serve(stream: UnixStream, agent: String, coord: Arc) -> Re } } -/// Default and max long-poll window for `Recv`. Caller can request a -/// shorter (or longer up to `RECV_LONG_POLL_MAX`) wait via the -/// `wait_seconds` field; values above the cap are clamped. 180s -/// max keeps us under typical TCP/proxy idle limits while letting -/// agents park their turn until a message lands instead of busy- -/// looping with short waits. -const RECV_LONG_POLL_DEFAULT: std::time::Duration = std::time::Duration::from_secs(30); +/// Max long-poll window the caller can ask for; values above the +/// cap are clamped. 180s keeps us under typical TCP/proxy idle +/// limits while still letting agents park their turn until a +/// message arrives. Omitting `wait_seconds` (or passing `0`) means +/// "peek, don't wait" — claude can call recv whenever it wants a +/// cheap "is there anything pending?" check without blocking the +/// turn for 30 seconds. To actually park, the caller passes a +/// positive `wait_seconds`. const RECV_LONG_POLL_MAX: std::time::Duration = std::time::Duration::from_secs(180); fn recv_timeout(wait_seconds: Option) -> std::time::Duration { match wait_seconds { Some(s) => std::time::Duration::from_secs(s).min(RECV_LONG_POLL_MAX), - None => RECV_LONG_POLL_DEFAULT, + None => std::time::Duration::ZERO, } } diff --git a/hive-c0re/src/manager_server.rs b/hive-c0re/src/manager_server.rs index 907c612..47c1854 100644 --- a/hive-c0re/src/manager_server.rs +++ b/hive-c0re/src/manager_server.rs @@ -69,15 +69,16 @@ async fn serve(stream: UnixStream, coord: Arc) -> Result<()> { } } -/// Default and max long-poll window for manager `Recv`. Caller can -/// request a shorter or longer (up to MAX) wait via `wait_seconds`. -const MANAGER_RECV_LONG_POLL_DEFAULT: std::time::Duration = std::time::Duration::from_secs(30); +/// Max long-poll window for manager `Recv`. Same semantics as the +/// sub-agent socket: omitted `wait_seconds` (or `0`) = peek and +/// return immediately, positive value = park up to that many +/// seconds (clamped at MAX). const MANAGER_RECV_LONG_POLL_MAX: std::time::Duration = std::time::Duration::from_secs(180); fn manager_recv_timeout(wait_seconds: Option) -> std::time::Duration { match wait_seconds { Some(s) => std::time::Duration::from_secs(s).min(MANAGER_RECV_LONG_POLL_MAX), - None => MANAGER_RECV_LONG_POLL_DEFAULT, + None => std::time::Duration::ZERO, } }