hyperhive/docs/tools/scheduling.md

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, body is fanned 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. Clearing interval_seconds to null flips recurring → one-shot. 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 auto-cancels 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. One-shot schedules are consumed by the manual fire and cancelled 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 (e.g. "gui") — hive-c0re resolves the machine name (h-<name>). lines defaults to 50, host-capped at 500.

See also

• remind (no-approval self-wake path) — documented in docs/turn-loop.md.
• docs/approvals.md — approval flow for request_schedule_prompt.