6d7565a30d
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.
105 lines
4.5 KiB
Markdown
105 lines
4.5 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 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
|
|
|
|
- `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`.
|