vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
hyperhive/docs/tools/scheduling.md
atlas 4121e11d87 hive-c0re: drop the subtree check from the scheduling verbs 
The topology predicate `is_descendant_of` gated the four schedule-
managing verbs: a caller could only name a schedule owned by an agent at
or below itself in `topology.json`. Those gates now permit any requester,
so the predicate, its pure `_in` form and the `schedule_authorized`
wrapper built on it are gone rather than left returning a constant. The
other two wrappers went earlier with the verbs they served —
`require_descendant` with the lifecycle MCP verbs in 87970a8c, and
`resolve_agent_state_target` with `get_loose_ends`'s agent parameter.

`require_group(agent, "scheduling", ...)` is untouched and still fires at
dispatch for every one of the five scheduling verbs, so holding the tool
group remains the gate; what goes is the ownership restriction layered on
top of it.

The three schedule-mutating verbs keep their row lookup as a plain
existence check, so a caller naming a schedule that does not exist still
gets `not found` rather than a message from deeper in the cancel path.
`list_schedules` stops filtering per row: it would only have hidden rows
the requester may act on anyway.

Error messages, tool descriptions and docs that described the subtree
relation are reworded — a refusal message naming a topology that no
longer decides anything is worse than none.

The six `is_descendant_of_in` unit tests go with the function they test;
the permit behaviour they leave unasserted is picked up by the next
commit.

Refs #4472
2026-09-21 17:20:44 +02:00

4.1 KiB
Raw Blame History

Scheduling and diagnostics tools

scheduling tool group

Scheduled prompts fan a message body out to one or more agent inboxes at a future time, optionally recurring.

Creating one goes through the operator approval queue, even when it targets only yourself — use remind for an unapproved self-wake. The other four verbs need no approval: holding the scheduling tool group is the whole gate.

Authorization is one rule for all four verbs: you reach every schedule in the hive, whoever owns it. list_schedules shows the same set, so the snapshot only ever shows schedules you could also cancel.

request_schedule_prompt(targets, body, first_fire_at_unix, interval_seconds?, description?)

Queue an operator-approval for a scheduled prompt. On approve, hive-c0re fans body out to each agent in targets at first_fire_at_unix (Unix timestamp). Recurring when interval_seconds is set, one-shot otherwise.

Catch-up clamp: if hive-c0re is down across multiple intervals, only ONE delayed fire happens on resume (per recurring schedule). The skipped-cycle count surfaces in the per-target last_result for audit.

edit_schedule(id, body?, description?, interval_seconds?, next_fire_at_unix?, targets_add?, targets_remove?)

Partial-update a schedule. Pass only the fields to change; absent fields stay untouched. targets_add / targets_remove mutate the recipient list in the same transaction — re-adding a previously cancelled target drops its tombstone and starts fresh. interval_seconds accepts positive values only via this tool (omit to keep the existing cadence; pass a new positive value to change it). Toggling recurring → one-shot (clearing the interval) is operator-only via the dashboard PATCH endpoint. Refuses cancelled rows (terminal state).

cancel_schedule(id, targets?)

Cancel a schedule. Omit targets / pass empty to cancel the whole schedule; pass a list to cancel just those recipients (the schedule autocancels once every target is gone).

fire_schedule_now(id)

Fire a scheduled prompt out of band immediately. Recurring schedules keep their cadence — the manual fire is additive. The manual fire consumes one-shot schedules and cancels them afterwards.

list_schedules()

Snapshot every schedule in the hive (active, and cancelled but not yet reaped) — same read scope as the rest of this group. Returns id, owner, body, per-target last_fired_at and last_result, next_fire_at_unix, interval_seconds. Use to look up an id before cancelling, or to audit upcoming wake-ups across the hive.

read_host_journal capability

Capability-gated (not a tool group) — the operator enables it in the P3RM1SS10NS C4P4B1L1T13S section. Unlike tool groups this isn't configurable from agent.nix.

get_host_journal(unit?, container?, lines?, priority?, grep?, since?, until?)

Fetch recent lines from the host journal (requires read_host_journal capability). Useful when you need visibility outside your own container — infrastructure services, hive-c0re lifecycle events, or another container's boot log.

  • unit — filter to a systemd unit (for example hive-c0re.service).
  • container — nspawn machine name verbatim. Agent containers use the h-<name> prefix (for example h-iris); infrastructure containers use their full name (for example hive-ci, hive-forge, hive-matrix). Omit for the host journal. The gateway has no machine — its nginx runs on the host, so read it with unit: nginx.service and no container.
  • lines — how many lines to return (default 30, max 100).
  • priority — minimum syslog level (emerg … debug).
  • grep — regex matched against log message fields (journalctl --grep).
  • since / until — time bounds (for example -1h, 2024-01-01 12:00:00).

See also