c28da210b4
`docs/tools/scheduling.md` said three things about who may do what. Two
were wrong prose; the third was the code.
"All scheduling ops go through the operator approval queue" — one of the
five does. Cancel, edit, list and fire are `require_group("scheduling")`
and nothing else (socket_server/mod.rs:594-643), which is what the MCP
tool descriptions already tell an agent. The page pushed in the cautious
direction: someone watching a runaway recurring schedule would wait for
an operator rather than cancel it themselves.
The authorization sentence covered "read/cancel/edit". Cancel, edit and
fire really do check `cancel_authorized` (self, operator, or subtree) from
three call sites. `handle_list_schedules` takes no requester at all and
returns every row — now stated, along with the part that matters: the
snapshot includes other agents' schedule bodies.
`lines` was documented as "host-capped at 500" and the 500 was in the
agent's own MCP layer, not the host; `handle_get_logs` passed any u32
straight into JournalQuery. A limit in the caller is not a limit, so the
host clamps instead of the sentence changing. That also makes args.rs's
arg doc and the tool description agents read correct, untouched. The
sibling `get_host_journal` already clamps host-side at 100, which is both
the precedent and the control that the missing clamp here was real.
Closes #4230.
4.8 KiB
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 for cancel / edit / fire: you can act on schedules you own
or any owned by an agent in your topology subtree. list_schedules is
not scoped at all — it returns every schedule on the hive, bodies
included, which is what makes it useful for auditing and worth knowing
before you put anything private in a schedule body.
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.
Unscoped on purpose — unlike the verbs that change a schedule, this one applies no ownership filter, so the snapshot covers other agents' schedules and the operator's.
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 examplehive-c0re.service).container— nspawn machine name verbatim. Agent containers use theh-<name>prefix (for exampleh-iris); infrastructure containers use their full name (for examplehive-ci,hive-forge,hive-matrix). Omit for the host journal. The gateway has no machine — its nginx runs on the host, so read it withunit: nginx.serviceand nocontainer.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
remind(no-approval self-wake path) — documented indocs/turn-loop/.docs/agent-lifecycle/approvals.md— approval flow forrequest_schedule_prompt.