4121e11d87
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
99 lines
4.1 KiB
Markdown
99 lines
4.1 KiB
Markdown
# 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?)`
|
|
|
|
<!-- vale write-good.Passive = NO -->
|
|
|
|
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.
|
|
|
|
<!-- vale write-good.Passive = YES -->
|
|
|
|
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?)`
|
|
|
|
<!-- vale write-good.Passive = NO -->
|
|
|
|
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).
|
|
|
|
<!-- vale write-good.Passive = YES -->
|
|
|
|
### `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
|
|
|
|
- `remind` (no-approval self-wake path) — documented in
|
|
[`docs/turn-loop/`](../turn-loop/README.md).
|
|
- [`docs/agent-lifecycle/approvals.md`](../agent-lifecycle/approvals.md) — approval flow for
|
|
`request_schedule_prompt`.
|