68 lines
2.7 KiB
Markdown
68 lines
2.7 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. 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`](../turn-loop.md).
|
|
- [`docs/approvals.md`](../approvals.md) — approval flow for
|
|
`request_schedule_prompt`.
|