refactor: unify AgentRequest/Response + ManagerRequest/Response into Request/Response (#691)

This commit is contained in:
damocles 2026-06-01 09:30:44 +02:00 committed by mara
commit 15617cef9a
6 changed files with 197 additions and 534 deletions

View file

@ -295,11 +295,15 @@ pub enum CancelLooseEndKind {
Approval,
}
/// Requests on a per-agent socket. The agent's identity is the socket
/// it came in on; `Send.from` is filled in by the server, not the client.
/// Unified request enum for both agent and manager sockets. The agent's
/// identity is the socket it arrived on. Manager-only variants are tagged
/// `// privileged` — an agent socket returns `Err` for them server-side.
///
/// `AgentRequest` and `ManagerRequest` are type aliases for this enum;
/// existing callers continue to compile unchanged.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "cmd", rename_all = "snake_case")]
pub enum AgentRequest {
pub enum Request {
/// Send a message to another agent.
Send {
to: String,
@ -367,23 +371,37 @@ pub enum AgentRequest {
#[serde(default)]
file_path: Option<String>,
},
/// Loose-ends view: every pending row against THIS agent.
/// Per-flavour scoping in
/// Loose-ends view. On the agent socket, scoped to the calling agent
/// (the `agent` field is ignored — agents can only see their own
/// loose ends). On the manager socket, `agent = None` scopes to the
/// manager itself, `Some("*")` is hive-wide, `Some("<name>")` is
/// that agent's loose ends. See
/// `docs/conventions.md::Loose-ends wire shape`.
GetLooseEnds,
/// Count of this agent's pending (un-delivered) reminders. Used
/// by the harness's per-turn stats sink to snapshot "what was
/// queued at turn-end time" without paying for a full list.
CountPendingReminders,
/// Reminder statistics for this agent: counts of scheduled, delivered,
/// and pending reminders over a time window. Used by the stats page
/// to display reminder activity. `since_secs` filters to reminders
/// created in the last N seconds (0 = all reminders).
GetLooseEnds {
#[serde(default, skip_serializing_if = "Option::is_none")]
agent: Option<String>,
},
/// Count of pending (un-delivered) reminders. On the agent socket
/// always scoped to the calling agent. On the manager socket,
/// `agent = None` means self, `Some("<name>")` means that agent.
/// Used by the harness's per-turn stats sink.
CountPendingReminders {
#[serde(default, skip_serializing_if = "Option::is_none")]
agent: Option<String>,
},
/// Reminder statistics: counts of scheduled, delivered, and pending
/// reminders over a time window. `since_secs` filters to reminders
/// created in the last N seconds (0 = all). On the manager socket
/// `agent = None` means self, `Some("<name>")` means that agent.
ReminderRollup {
/// Only count reminders created in the last N seconds from now.
/// Pass 0 to include all reminders.
#[serde(default)]
since_secs: u64,
/// Whose reminders to roll up. `None` = the caller's own.
/// Manager socket only: `Some("<name>")` = that agent's.
#[serde(default, skip_serializing_if = "Option::is_none")]
agent: Option<String>,
},
/// Set a free-text status string visible on the dashboard. Persisted
/// to `{state_dir}/hyperhive-status` so it survives harness restarts.
@ -409,12 +427,88 @@ pub enum AgentRequest {
/// crashed-mid-turn sessions. See
/// `docs/conventions.md::Broker delivery + ack cycle`.
RequeueInflight,
// ---- privileged: manager socket only -----------------------------------
/// Initialise a brand-new agent's proposed config repo and queue an
/// approval for the operator to review. // privileged
RequestInitConfig {
name: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
description: Option<String>,
},
/// Stop a sub-agent (graceful). // privileged
Kill { name: String },
/// Start a previously-stopped sub-agent container. // privileged
Start { name: String },
/// Restart a sub-agent container (stop + start). // privileged
Restart { name: String },
/// Rebuild a sub-agent against the current hyperhive flake + agent.nix.
/// No approval required. // privileged
Update { name: String },
/// Submit a config commit for the operator to approve. // privileged
RequestApplyCommit {
agent: String,
commit_ref: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
description: Option<String>,
},
/// Fetch recent journal lines for a sub-agent container. // privileged
GetLogs {
agent: String,
#[serde(default)]
lines: Option<u32>,
},
/// Queue an approval to run `nix flake update [inputs...]`. // privileged
RequestUpdateMetaInputs {
#[serde(default)]
inputs: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
description: Option<String>,
},
/// Queue an approval to add a scheduled prompt. // privileged
RequestSchedulePrompt(SchedulePromptPayload),
/// Cancel a scheduled prompt. // privileged
CancelSchedule {
id: i64,
#[serde(default, skip_serializing_if = "Option::is_none")]
targets: Option<Vec<String>>,
},
/// List every schedule in the queue. // privileged
ListSchedules,
/// Fire a scheduled prompt out of band immediately. // privileged
FireScheduleNow { id: i64 },
/// Edit an existing schedule's mutable fields. // privileged
EditSchedule {
id: i64,
#[serde(default, skip_serializing_if = "Option::is_none")]
body: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
description: Option<Option<String>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
interval_seconds: Option<Option<u64>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
next_fire_at_unix: Option<i64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
targets_add: Option<Vec<String>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
targets_remove: Option<Vec<String>>,
},
}
/// Responses on a per-agent socket.
/// Backwards-compatible aliases. Both sockets now speak the unified `Request`
/// / `Response` wire; the server-side privilege gate rejects manager-only
/// variants on agent sockets with `Err { message: "privileged variant..." }`.
pub type AgentRequest = Request;
pub type ManagerRequest = Request;
/// Unified response enum for both agent and manager sockets. Manager-only
/// variants (`Logs`, `Schedules`) are never returned on agent sockets.
///
/// `AgentResponse` and `ManagerResponse` are type aliases for this enum.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum AgentResponse {
pub enum Response {
/// `Send` succeeded.
Ok,
/// Either `Send` failed or `Recv` errored.
@ -458,8 +552,18 @@ pub enum AgentResponse {
#[serde(default, skip_serializing_if = "Option::is_none")]
swarm_name: Option<String>,
},
/// `GetLogs` result: journal lines for the requested container.
/// Returned on the manager socket only.
Logs { content: String },
/// `ListSchedules` result. Snapshot of every schedule.
/// Returned on the manager socket only.
Schedules { schedules: Vec<WireSchedule> },
}
/// Backwards-compatible response aliases.
pub type AgentResponse = Response;
pub type ManagerResponse = Response;
/// Serde default for the `running` field; keeps wire backwards-compat
/// with pre-running-field payloads. See
/// `docs/conventions.md::Agent metadata`.
@ -582,240 +686,6 @@ pub enum HelperEvent {
},
}
/// Requests on the manager socket. Manager has the agent surface (send/recv)
/// plus privileged lifecycle verbs.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "cmd", rename_all = "snake_case")]
pub enum ManagerRequest {
Send {
to: String,
body: String,
/// Optional id of the message being replied to. Mirror of
/// `AgentRequest::Send.in_reply_to`; see that doc.
#[serde(default, skip_serializing_if = "Option::is_none")]
in_reply_to: Option<i64>,
},
/// Same shape as `AgentRequest::Recv` — caller-tunable
/// `wait_seconds` (capped at 60s server-side, default 30s when
/// None) for first-message long-poll, plus `max` (default 1, cap
/// 32) to drain up to N popped rows in one round-trip.
Recv {
#[serde(default)]
wait_seconds: Option<u64>,
#[serde(default)]
max: Option<u32>,
},
/// Non-mutating: pending message count, used to render a status line
/// after each MCP tool call (mirrors `AgentRequest::Status`).
Status,
/// Operator-injected message TO the manager (from the manager's own web
/// UI). Same shape as `AgentRequest::OperatorMsg`.
OperatorMsg { body: String },
/// Last `limit` messages addressed to the manager, newest-first.
/// Non-mutating; mirror of `AgentRequest::Recent`.
Recent { limit: u64 },
/// Initialise a brand-new agent's proposed config repo and queue an
/// approval for the operator to review. On approval hive-c0re seeds
/// `/agents/<name>/config/` with the default `agent.nix` template,
/// giving the manager RW access so it can customise the config and
/// commit changes. After the `ConfigReady` event arrives, edit
/// `agent.nix`, commit, and call `request_apply_commit` — which
/// creates the container on the first deploy. Fails if a proposed
/// repo for this name already exists (use `request_apply_commit` to
/// update an existing agent's config).
RequestInitConfig {
name: String,
/// Optional description shown on the dashboard approval card.
#[serde(default, skip_serializing_if = "Option::is_none")]
description: Option<String>,
},
/// Stop a sub-agent (graceful).
Kill { name: String },
/// Start a previously-stopped sub-agent container.
Start { name: String },
/// Restart a sub-agent container (stop + start).
Restart { name: String },
/// Rebuild a sub-agent: re-applies the current hyperhive flake +
/// agent.nix, restarts the container. No approval required —
/// it's idempotent and the manager owns its own update cadence.
Update { name: String },
/// Submit a config commit for the user to approve. `commit_ref` must
/// be a commit sha (7-40 hex chars, short or full) in the agent's
/// proposed config repo — a branch or tag name is rejected so the
/// approval pins an immutable commit. On approval the host applies
/// the change via `nixos-container update`.
RequestApplyCommit {
agent: String,
commit_ref: String,
/// Optional description shown on the dashboard approval card so the
/// operator knows what the change does without opening the diff.
#[serde(default, skip_serializing_if = "Option::is_none")]
description: Option<String>,
},
/// Surface a question to either the operator or another agent.
/// Manager-flavour mirror of `AgentRequest::Ask` — routing + shape
/// docs in `docs/conventions.md::Question routing (Ask / Answer)`.
Ask {
question: String,
#[serde(default)]
options: Vec<String>,
#[serde(default)]
multi: bool,
#[serde(default)]
ttl_seconds: Option<u64>,
#[serde(default)]
to: Option<String>,
},
/// Answer a question previously routed to the manager via
/// `HelperEvent::QuestionAsked`. Mirror of `AgentRequest::Answer`;
/// see `docs/conventions.md::Question routing (Ask / Answer)`.
Answer { id: i64, answer: String },
/// Fetch recent journal lines for a sub-agent container. `agent`
/// is the logical agent name; hive-c0re resolves it to the
/// machine name (`gui` → `h-gui`) and runs `journalctl -M
/// <machine> -n <lines> --no-pager`, returning the output as a
/// string. Useful for diagnosing MCP registration failures,
/// startup crashes, and harness errors.
///
/// `lines` defaults to 50 when omitted.
GetLogs {
agent: String,
#[serde(default)]
lines: Option<u32>,
},
/// Mirror of `AgentRequest::Remind` on the manager surface — schedule
/// a reminder addressed to the manager itself. Same semantics: body
/// soft-caps at 4 KiB, oversize bodies auto-persist to
/// `/state/reminders/auto-<ts>.md` (the manager container's own state
/// mount) and the inbox sees a pointer.
Remind {
message: String,
timing: ReminderTiming,
#[serde(default)]
file_path: Option<String>,
},
/// Loose-ends view for the manager surface. The optional `agent`
/// field selects scope:
/// - `None` — the manager's own loose ends: approvals it
/// submitted + questions where it is asker/target + its own
/// pending reminders. This is the default.
/// - `Some("*")` — hive-wide: EVERY pending approval, unanswered
/// question, and pending reminder across the swarm.
/// - `Some("<name>")` — that specific agent's loose ends.
GetLooseEnds {
#[serde(default)]
agent: Option<String>,
},
/// Count of pending reminders. `agent` selects whose: `None` =
/// the manager's own, `Some("<name>")` = that agent's. Mirror of
/// `AgentRequest::CountPendingReminders` on the manager surface.
CountPendingReminders {
#[serde(default)]
agent: Option<String>,
},
/// Reminder statistics: counts of scheduled, delivered, and pending
/// reminders (manager-flavour). Mirror of `AgentRequest::ReminderRollup`.
ReminderRollup {
/// Only count reminders created in the last N seconds from now.
/// Pass 0 to include all reminders.
#[serde(default)]
since_secs: u64,
/// Whose reminders to roll up: `None` = the manager's own,
/// `Some("<name>")` = that agent's.
#[serde(default)]
agent: Option<String>,
},
/// Mirror of `AgentRequest::SetStatus` on the manager surface.
SetStatus { text: String },
/// Mirror of `AgentRequest::GetAgentMeta` on the manager surface.
/// See `docs/conventions.md::Agent metadata`.
GetAgentMeta {
#[serde(default, skip_serializing_if = "Option::is_none")]
name: Option<String>,
},
/// Cancel an open thread (question or reminder). Manager surface
/// can cancel any row (no owner check) — same dispatch as
/// `AgentRequest::CancelLooseEnd` but with privileged auth.
CancelLooseEnd { kind: CancelLooseEndKind, id: i64 },
/// Mirror of `AgentRequest::AckTurn` on the manager surface — fired
/// by the manager harness after `TurnOutcome::Ok` to close out
/// every message popped during the turn.
AckTurn,
/// Mirror of `AgentRequest::RequeueInflight` on the manager
/// surface — fired exactly once on manager harness boot.
RequeueInflight,
/// Mirror of `AgentRequest::Wake` on the manager surface. See
/// `docs/conventions.md::Wake injection`.
Wake { from: String, body: String },
/// Queue an approval to run `nix flake update [inputs...]` on the
/// meta flake. `inputs` is the list of named inputs to update
/// (e.g. `["bitburner-agent", "nixpkgs"]`). Pass an empty list to
/// update ALL inputs. On operator approval hive-c0re runs the lock
/// update and commits the result. The `UpdateMetaInputs` approval
/// resolves with `ApprovalResolved` in the manager inbox.
RequestUpdateMetaInputs {
#[serde(default)]
inputs: Vec<String>,
/// Optional description shown on the dashboard approval card.
#[serde(default, skip_serializing_if = "Option::is_none")]
description: Option<String>,
},
/// Queue an approval to add a scheduled prompt. The requester
/// (caller of this request) is recorded as the schedule owner; on
/// operator approval hive-c0re inserts the schedule and the worker
/// fans the body out at fire time. Even agent-self schedules go
/// through approval — the existing `remind` MCP tool is the
/// unapproved self-wake path.
RequestSchedulePrompt(SchedulePromptPayload),
/// Cancel a scheduled prompt. `targets = None` cancels the whole
/// schedule; `Some(list)` cancels just those recipients,
/// auto-cancelling the parent when no active targets remain.
/// Authorization: manager can cancel its own schedules + any
/// sub-agent schedules (i.e. owner reachable via topology); the
/// operator surface bypasses this check.
CancelSchedule {
id: i64,
#[serde(default, skip_serializing_if = "Option::is_none")]
targets: Option<Vec<String>>,
},
/// List every schedule in the queue. Manager-side this is
/// unfiltered — the dashboard does the topology-filter for the
/// per-agent view.
ListSchedules,
/// Fire a scheduled prompt out of band. Runs the per-target
/// fan-out once immediately without touching
/// `next_fire_at_unix` on recurring schedules; one-shots are
/// consumed by the manual fire. Authorization mirrors
/// `CancelSchedule`: the manager can fire its own schedules and
/// any owned by a sub-agent in its subtree per topology.json;
/// the operator surface bypasses the check.
FireScheduleNow { id: i64 },
/// Edit an existing schedule's mutable fields. Partial PATCH
/// semantics: `None` / missing JSON key = leave alone,
/// `Some(_)` = set. `interval_seconds` and `description` are
/// doubly-wrapped so `Some(None)` (set explicit null) can flip
/// a recurring schedule back to one-shot / clear the
/// description, while plain `None` keeps the current value.
/// `targets_add` / `targets_remove` mutate the recipient list
/// in the same transaction; re-adding a previously-cancelled
/// target drops the tombstone (replace-on-conflict). Refuses
/// cancelled rows. Authorization mirrors `CancelSchedule`.
EditSchedule {
id: i64,
#[serde(default, skip_serializing_if = "Option::is_none")]
body: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
description: Option<Option<String>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
interval_seconds: Option<Option<u64>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
next_fire_at_unix: Option<i64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
targets_add: Option<Vec<String>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
targets_remove: Option<Vec<String>>,
},
}
/// Submission payload for `RequestSchedulePrompt`. Lives outside the
/// enum so it can also serialize into the approval row's `commit_ref`
@ -882,72 +752,3 @@ pub struct WireScheduleTarget {
pub last_result: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ManagerResponse {
Ok,
Err {
message: String,
},
/// Mirror of `AgentResponse::Messages` on the manager surface.
/// Always-list shape: 0..=max popped rows, FIFO-ordered. Carries
/// per-row `id` + `redelivered` so the manager harness drives the
/// same ack + requeue-with-hint flow as a sub-agent.
Messages {
messages: Vec<DeliveredMessage>,
},
Status {
unread: u64,
},
/// Result of `Ask`: the queued question id. The actual answer
/// arrives later as a `HelperEvent::QuestionAnswered` in the
/// asker's inbox, so this returns immediately rather than blocking
/// the turn.
QuestionQueued {
id: i64,
},
/// `Recent` result: mirror of `AgentResponse::Recent`.
Recent {
rows: Vec<InboxRow>,
},
/// `GetLogs` result: journal lines for the requested container.
Logs {
content: String,
},
/// `ListSchedules` result. Snapshot of every schedule (active +
/// cancelled-but-not-yet-reaped); the dashboard does the
/// per-agent topology filter on top.
Schedules {
schedules: Vec<WireSchedule>,
},
/// `GetLooseEnds` result: hive-wide loose ends (approvals +
/// unanswered questions). Same `LooseEnd` variants as the
/// agent surface; the manager's view is unfiltered.
LooseEnds {
loose_ends: Vec<LooseEnd>,
},
/// `CountPendingReminders` result.
PendingRemindersCount {
count: u64,
},
/// `ReminderRollup` result: reminder activity stats for the manager.
ReminderRollup(ReminderStats),
/// Mirror of `AgentResponse::AgentMeta` on the manager surface.
/// See `docs/conventions.md::Agent metadata`.
AgentMeta {
name: String,
role: String,
#[serde(default = "default_true")]
running: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
hyperhive_rev: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
status_text: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
status_set_at: Option<i64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
hive_name: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
swarm_name: Option<String>,
},
}