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

hive-sh4re + docs: extract broker delivery/ack/requeue prose (#717 batch 1)

Browse source
This commit is contained in:
iris 2026-05-31 15:50:57 +02:00 • committed by mara
commit a443108be5
2 changed files with 55 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

65
hive-sh4re/src/lib.rs
View file

@ -241,26 +241,20 @@ pub struct InboxRow {
pub in_reply_to: Option<i64>,
}
/// One delivered message in a `Recv` response. The unified
/// `Recv { max }` always returns a `Vec<DeliveredMessage>` — single
/// pop = a one-element vec, batch = up to `max` elements, idle =
/// empty. Each row carries the broker's id + redelivered flag so the
/// harness can drive `AckTurn` and surface the "may already be
/// handled" hint per-row.
/// One delivered message in a `Recv` response.
/// See `docs/conventions.md::Broker delivery + ack cycle` for the
/// full delivery/ack/requeue story.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DeliveredMessage {
pub from: String,
pub body: String,
/// Broker row id, mirrored from the `Delivery` struct. Opaque to
/// claude but tracked by the harness so the broker's in-memory
/// unacked list can be drained on `AckTurn`. Marked `default` for
/// wire backwards-compat — pre-feature peers parse to 0.
/// Broker row id, tracked by the harness for `AckTurn`. Opaque to
/// claude. `default` for wire backwards-compat.
#[serde(default)]
pub id: i64,
/// `true` when this row was previously popped, never acked, and
/// resurfaced by `RequeueInflight`. The format helper prepends the
/// "may already be handled" hint to the rendered body so claude
/// sees the warning per-message in the batch.
/// `true` if this row was resurfaced by `RequeueInflight` (previously
/// popped, never acked). Formatter prepends a "may already be handled"
/// hint when set.
#[serde(default)]
pub redelivered: bool,
/// Row-id of the message this is a reply to, if any.
@ -371,22 +365,12 @@ pub enum AgentRequest {
#[serde(default, skip_serializing_if = "Option::is_none")]
in_reply_to: Option<i64>,
},
/// Pop pending messages from this agent's inbox. Always returns
/// a list (`Messages { messages }`) — empty when nothing's
/// pending. `max` caps the batch size (default 1 = single-message
/// behaviour, server-side cap 32). `wait_seconds` long-polls for
/// the first message; once one arrives (or one is already
/// pending), the call drains up to `max` in total before
/// returning. Same delivery + ack bookkeeping per row as before:
/// `delivered_at = NOW`, tracked on the per-recipient
/// `unacked_ids` list (the next `AckTurn` closes them out), and
/// each row carries `redelivered = true` if `RequeueInflight`
/// resurfaced it.
/// Pop pending messages from this agent's inbox.
/// Delivery + ack cycle: see
/// `docs/conventions.md::Broker delivery + ack cycle`.
Recv {
#[serde(default)]
wait_seconds: Option<u64>,
/// Maximum number of messages to pop. None = 1 (single).
/// Server-side cap is 32; values above clamp silently.
#[serde(default)]
max: Option<u32>,
},
@ -498,27 +482,14 @@ pub enum AgentRequest {
/// row. The manager surface uses the same wire variant but
/// accepts any id.
CancelLooseEnd { kind: CancelLooseEndKind, id: i64 },
/// Mark every message popped by this agent since the last `AckTurn`
/// as fully handled. Fired by the harness after `TurnOutcome::Ok`
/// — claude doesn't see this surface, it's harness↔broker only.
/// On `TurnOutcome::Failed` the harness intentionally skips this
/// call, so the unacked rows stay in-flight in the DB and get
/// requeued by the next `RequeueInflight` on harness boot. Tracks
/// the popped-id list in-memory on the broker side; no payload
/// needed (the broker knows which ids it handed to this
/// recipient).
/// Mark every message popped since the last `AckTurn` as handled.
/// Harness↔broker pairing fired after `TurnOutcome::Ok`. See
/// `docs/conventions.md::Broker delivery + ack cycle`.
AckTurn,
/// Requeue every message the broker handed to this agent that
/// never got acked. Fired by the harness exactly once at boot,
/// before entering the serve loop — catches the
/// crashed-mid-turn / OOM-killed / container-restarted cases
/// where a previous harness session popped messages but never
/// drove them to a clean turn-end. Resets `delivered_at` on each
/// row back to NULL (so the next `Recv` pops it) and remembers
/// the id in a per-recipient in-memory set so the next `Recv`
/// can tag the message with `redelivered: true` (the harness
/// then prepends a "may already be handled" hint to the wake
/// prompt). Idempotent + cheap when there's nothing in flight.
/// Requeue every popped-but-unacked message back into the inbox.
/// Harness fires this once at boot to recover from
/// crashed-mid-turn sessions. See
/// `docs/conventions.md::Broker delivery + ack cycle`.
RequeueInflight,
}