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
iris 97e2a993e3 docs: fix genuine passive-voice hits in docs/tools (hand-written files) 
Read all 62 write-good.Passive hits across the 6 hand-written files in
docs/tools/ (bash.md, lifecycle.md, forge.md, hivectl.md, matrix.md,
scheduling.md) in context. Excludes forge-cli.md/hivectl-cli.md/
swarmctl-cli.md (57 more hits) -- those are CI-generated from the
clap doc-comment strings in hive-forge/hivectl/swarmctl, freshness-
checked against the committed markdown, so a fix there has to go in
the Rust source and get regenerated -- separate batch.

33 rewritten to active, actor usually already established in the same
paragraph or given via a 'by X' clause (the daemon, hive-c0re,
hive-forge, hivectl, hyperhive itself, or an established module name
like nix/agent-modules/mcp.nix). Several sibling-inconsistency fixes:
a passive clause next to an already-active sibling stating the same
fact (lifecycle.md's server-scoping sentence, forge.md's clone-derives
sentence, hivectl.md's daemon-hashes-passwords sentence, matrix.md's
daemon-upserts-a-todo paragraph).

29 left alone: no-X-is-Y / no-X-is-needed invariant idioms, config-state
conditionals (whenever/when X is set/configured/given), requirement-
list idiom, a false-positive tokenization (vale matching 'are read'
inside 'read-only'), definitional facts about CLI/attrset structure
with no real actor, hypothetical/counterfactual clauses describing a
rejected design alternative, a forward-looking not-yet-real removal,
compressed bullet-fragment conventions, and one deliberately-parallel
sentence structure left both halves alone to avoid breaking the
symmetry.

Verified via vale on the 6 touched files, diffed against main's exact
baseline (not just the Passive count): write-good.Passive 62 -> 29
exactly, every other category unchanged in count AND location
(TooWordy 16, Microsoft.We 1, Microsoft.FirstPerson 1, and the same
4 pre-existing Microsoft.Contractions errors at the same 4 lines).
2026-09-08 14:49:22 +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. All scheduling ops go through the operator approval queue (even self-targeted schedules — use remind for unapproved self-wake). Authorization for read/cancel/edit ops: you can act on schedules you own or any owned by a sub-agent in your topology subtree.

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 every schedule (active + cancelled-but-not-reaped): id, owner, body, per-target last_fired_at + last_result, next_fire_at_unix, interval_seconds. Use to look up an id before cancelling, or to audit upcoming wake-ups across the swarm.

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