07b62612b0
Per mara's go-ahead on hyperhive#3902 ("getting started is good, but
terminal rendering does not go in there i think"):
Moved 21 top-level docs/*.md files into 7 new topic subdirectories
(existing web-ui/, turn-loop/, swarm/, tools/, crates/ untouched):
getting-started/ setup.md
agent-lifecycle/ agent-hierarchy.md, approvals.md, persistence.md
trust-boundary/ boundary.md, security.md
integrations/ forge.md, matrix.md, github.md, knowledge.md
networking/ gateway.md, network.md, snapshot-store.md
scheduler/ jobq.md, coordinator.md, ci.md, observability.md
process/ conventions.md, gotchas.md, pr-review-gate.md
web-ui/ terminal-rendering.md (moved into the EXISTING dir,
per mara's correction to the original getting-started
guess -- it's UI implementation detail, not onboarding)
The physical layout now matches docs/README.md's own topical headers,
which already amounted to this taxonomy -- see the scoping comment on
the issue for the two findings that motivated this (a genuine
duplication between CLAUDE.md's old "Reading paths" list and
docs/README.md's grouped one, since drifted out of sync with each
other; and the flat layout not matching the grouping we already had).
Fixed every cross-reference this moved across the whole repo (~120
files: docs/ internal links at every depth, Rust doc comments, nix
module option docs, crate READMEs) -- verified two ways: a grep sweep
confirming zero remaining references to any old path, and a script
that resolves every markdown link in docs/**/*.md + CLAUDE.md +
README.md against the filesystem and reports anything that doesn't
exist (zero broken links).
Collapsed CLAUDE.md's "Reading paths" section (the duplicate) down to
a pointer at docs/README.md, now the single index. Rewrote
docs/README.md itself to use the new subdirectory paths and added the
one doc it was missing that CLAUDE.md's old copy had (pr-review-gate.md).
Classified all 22 docs/*.md files first via a haiku subagent (mara's
suggestion) on two axes -- proposed grouping and operator-vs-
implementation focus -- before finalizing the taxonomy; spot-checked
the report and found internal inconsistencies (its classification
table disagreed with its own summary section for a few files), so this
taxonomy is my original proposal + the one correction mara gave
directly, not a blind application of the subagent's table. The
operator-focus data it gathered is still useful for a follow-up
content pass (docs skewing 'mixed' rather than pure operator-facing),
not addressed in this PR -- structure only.
nix fmt clean, both pre-push lints clean.
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 is not
|
|
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`.
|