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
hyperhive/docs/tools/scheduling.md
atlas 6d7565a30d scheduling.md: drop the list_schedules prose, keep the approval-scope fix 
mara's call on this PR was "list schedules not being scoped at all is a
bug - dont document it, file the bug and fix it". The bug is fixed in
damocles's separate PR, which also rewrites this page's
`list_schedules()` section.

So both of my paragraphs about scoping go: the "not scoped at all"
sentence in the intro (documenting the bug, which is what she
objected to) and the follow-up in the `list_schedules()` section. That
section is now byte-identical to main again, leaving it entirely to the
PR that changes the behaviour — the two PRs no longer touch a common
hunk in this file.

What stays is the claim this PR was actually filed for: the page said
"All scheduling ops go through the operator approval queue", and only
creating one does. The intro now splits creating from the other four
verbs and states the one authorization rule that covers all of them,
which the scoping fix makes true.
2026-09-11 18:43:10 +02:00

4.5 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 schedules you own and any owned by an agent in your topology subtree. list_schedules applies it too, 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 are left alone. 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 when every target is removed).

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 the schedules you're authorized to see (active, and cancelled but not yet reaped) — same read scope as the rest of this group: your own, plus any owned by a sub-agent in your subtree (everything, for the operator). 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 in your subtree.

diagnostics tool group

get_logs(agent, lines?)

Fetch recent journal lines for a sub-agent container. Useful for diagnosing MCP-registration failures, startup crashes, plugin install errors, or any harness issue you can't see from inside the container.

Pass the plain logical agent name (for example "gui") — hive-c0re resolves the machine name (h-<name>). lines defaults to 50, host-capped at 500.

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