hive-sh4re + docs: extract LooseEnd wire-shape prose (#717 batch 4)
This commit is contained in:
parent
a0b15ed6a4
commit
22b3e542c5
2 changed files with 69 additions and 51 deletions
|
|
@ -91,6 +91,58 @@ each id in a per-recipient in-memory set so the next `Recv` can tag
|
|||
the row with `redelivered: true`. Idempotent + cheap when there's
|
||||
nothing in flight, so the at-boot fire is unconditional.
|
||||
|
||||
### Loose-ends wire shape
|
||||
|
||||
`LooseEnd` is the per-row response shape for `GetLooseEnds` (both
|
||||
the agent-flavour and manager-flavour requests). Tagged enum so
|
||||
new thread kinds (forge PRs, long-running approvals from a
|
||||
privileged bot, etc.) can land later without breaking existing
|
||||
handlers. Each row carries enough context that the caller renders
|
||||
it directly as a bulleted list, no follow-up fetch needed.
|
||||
|
||||
Per-flavour scoping is uniform across the three variants:
|
||||
|
||||
- **agent-flavour** `GetLooseEnds` only surfaces rows the calling
|
||||
agent has standing in. `Approval` rows only appear when the
|
||||
calling agent is the manager (sub-agents don't submit
|
||||
approvals). `Question` rows surface where the agent is `asker`
|
||||
OR `target` (the routing semantics from the Ask/Answer
|
||||
subsection above). `Reminder` rows are scoped to `owner ==
|
||||
self`.
|
||||
- **manager-flavour** `GetLooseEnds` lists every pending row in
|
||||
the swarm — full audit view.
|
||||
|
||||
Per-variant fields:
|
||||
|
||||
- `Approval { id, agent, commit_ref, description?, age_seconds }`
|
||||
— `agent` is the affected agent (target of the spawn / config
|
||||
commit), not the asker. `description` is the manager's free-text
|
||||
blurb shown on the dashboard card. `commit_ref` is the
|
||||
kind-specific payload (see `docs/approvals.md::Approval kinds
|
||||
(wire shapes)`).
|
||||
- `Question { id, asker, target?, question, age_seconds }` —
|
||||
`target = None` = operator-routed (dashboard); `Some(agent)` =
|
||||
peer-to-peer thread.
|
||||
- `Reminder { id, owner, message, due_at, age_seconds }` —
|
||||
`due_at` is the absolute unix timestamp the scheduler is
|
||||
targeting; clients compute time-until-fire as `due_at - now`.
|
||||
|
||||
`age_seconds` saturates at zero on any clock anomaly (back-step,
|
||||
unsynchronised wall clock, etc.) so the bulleted list never
|
||||
shows nonsense ages.
|
||||
|
||||
`CancelLooseEnd { kind, id }` is the matching write surface. The
|
||||
`kind` enum (`Question` / `Reminder` / `Approval`) selects which
|
||||
underlying store the dispatcher reaches into. `Question` and
|
||||
`Reminder` cancel from either surface subject to ownership
|
||||
checks (asker for the question, scheduler for the reminder).
|
||||
`Approval` is manager-only — sub-agents don't submit approvals
|
||||
so they have nothing of their own to withdraw; their wire
|
||||
surface returns a clear error if they try. Cancelling an approval
|
||||
transitions the row to `ApprovalStatus::Cancelled` and fires
|
||||
`ApprovalResolved { status: "cancelled" }` so the dashboard pulls
|
||||
the card out of the pending pane.
|
||||
|
||||
## Async forms
|
||||
|
||||
Dashboard + per-agent mutating forms carry `data-async`; a delegated
|
||||
|
|
|
|||
Loading…
Reference in a new issue