78021ce982
Apply contraction fixes across ~40 doc files (setup, integrations, lifecycle, networking, scheduler, swarm, tools, trust-boundary, UI, etc.). Skipped 14 hits: - 10 where words appear in ALL CAPS for deliberate emphasis (is NOT, do NOT, etc.) - 4 where text could not be safely located due to markdown formatting or column position Applied via systematic scan with checks for fenced code blocks, inline code spans, and intentional caps. Preserves sentence-initial capitalization throughout.
96 lines
4.1 KiB
Markdown
96 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. 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.
|
|
`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
|
|
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.
|
|
|
|
## `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 (e.g. `hive-c0re.service`).
|
|
- `container` — nspawn machine name verbatim. Agent containers use
|
|
the `h-<name>` prefix (e.g. `h-iris`); infrastructure containers
|
|
use their full name (e.g. `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 (e.g. `-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`.
|