docs/hive-c0re: fix ask/answer removal doc gaps argus caught on #3741
This commit is contained in:
parent
2850270829
commit
16ac84ca63
10 changed files with 37 additions and 49 deletions
|
|
@ -629,6 +629,7 @@ root agent. Variants (`hive_sh4re::manager::HelperEvent`):
|
|||
- `NeedsUpdate { agent }` — sub-agent's recorded flake rev is
|
||||
stale. The root agent calls `update(name)` to rebuild — idempotent,
|
||||
no approval required.
|
||||
|
||||
The remaining lower-urgency lifecycle notices — `Rebuilt`, `Killed`,
|
||||
`Destroyed`, `NeedsLogin`, `LoggedIn`, `ConfigReady` — are "FYI, check
|
||||
when convenient" events with no reason to drive an immediate turn, so
|
||||
|
|
|
|||
|
|
@ -23,8 +23,7 @@ preset (`AGENT_DEFAULT`) includes `messaging`, `meta`, `inbox`, and
|
|||
## Core tools (always available)
|
||||
|
||||
**Messaging** (`messaging` group): `send(to, body, in_reply_to?)`,
|
||||
`recv(max?)`, `ask(question, options?, multi?,
|
||||
ttl_seconds?, to?)`, `answer(id, answer)`, `ack_until(up_to)`.
|
||||
`recv(max?)`, `ack_until(up_to)`.
|
||||
|
||||
- `send` — message a peer (logical name) or the operator
|
||||
(`to: "operator"`). Use `to: "<parent>"` to address the topology
|
||||
|
|
@ -48,13 +47,6 @@ ttl_seconds?, to?)`, `answer(id, answer)`, `ack_until(up_to)`.
|
|||
other turn: if the context crossed the watermark the harness runs a
|
||||
notes-checkpoint turn and then `/compact`. Compacting before shutdown
|
||||
keeps a later cold start cheap instead of re-uploading a huge transcript.
|
||||
- `ask` — surface a structured question to the operator (default) or
|
||||
a peer agent (`to: "<agent>"`). Non-blocking — returns a question
|
||||
id; the answer arrives as a `question_answered` system event in the
|
||||
asker's inbox. `options` is advisory; `multi=true` renders as
|
||||
checkboxes; `ttl_seconds` auto-cancels with answer `[expired]`.
|
||||
- `answer` — respond to a `question_asked` event routed to this
|
||||
agent. Strict authorisation: only the declared target can answer.
|
||||
- `ack_until(up_to)` — bulk-mark inbox rows handled: every row with
|
||||
broker id `<= up_to` is stamped as acked in a single UPDATE.
|
||||
Recipient-scoped (agents can only ack their own rows). Use when a
|
||||
|
|
@ -64,14 +56,12 @@ ttl_seconds?, to?)`, `answer(id, answer)`, `ack_until(up_to)`.
|
|||
Transient pings (sentinel id 0) have nothing to ack and show no marker.
|
||||
|
||||
**System messages** (from sender `system`): the higher-urgency
|
||||
lifecycle + Q&A events (`hive_sh4re::manager::HelperEvent`) are
|
||||
lifecycle events (`hive_sh4re::manager::HelperEvent`) are
|
||||
delivered as regular inbox messages (same `recv` path; body is a JSON
|
||||
object with an `event` discriminant field). The **submitting agent**
|
||||
(the root agent for top-level containers; an agent with the `approvals`
|
||||
tool group for its own subtree) receives `container_crash`,
|
||||
`needs_update`, and `approval_resolved` this way. Any agent receives
|
||||
Q&A events when it is the declared target (`question_asked`) or the
|
||||
asker (`question_answered`). The remaining, lower-urgency lifecycle
|
||||
`needs_update`, and `approval_resolved` this way. The remaining, lower-urgency lifecycle
|
||||
notices — `spawned`, `rebuilt`, `killed`, `destroyed`, `needs_login`,
|
||||
`logged_in`, `config_ready` — skip the inbox entirely: they land as
|
||||
todos on the submitting agent's in-container todo socket instead
|
||||
|
|
@ -86,18 +76,19 @@ payload shapes and routing logic in
|
|||
`cancel_loose_end(kind, id)`, `remind(message, delay_seconds? |
|
||||
at_unix_timestamp?)`.
|
||||
|
||||
- `get_loose_ends(agent?)` — list pending questions (asked/owed),
|
||||
scheduled reminders, and active local tasks published by external MCP
|
||||
daemons (e.g. running bash tasks from `hive-bash-daemon`). Each row
|
||||
carries an id + kind for `cancel_loose_end`. Omit `agent` to list
|
||||
your own threads. Pass `agent: "<name>"` to inspect a direct child
|
||||
agent (always accessible per topology enforcement); non-children
|
||||
require the `query_agent_state` capability. The `"*"` hive-wide
|
||||
query is not available on the agent socket.
|
||||
- `cancel_loose_end` — withdraw a `question` (posts `[cancelled by
|
||||
<self>]`), hard-delete a `reminder`, or cancel a pending `approval`
|
||||
row. Agents may only cancel rows they own; the `approval` kind is
|
||||
further restricted to the root agent (`ruth`) server-side.
|
||||
- `get_loose_ends(agent?)` — list scheduled reminders, pending
|
||||
approvals you submitted, and active local tasks published by
|
||||
external MCP daemons (e.g. running bash tasks from
|
||||
`hive-bash-daemon`). Each row carries an id + kind for
|
||||
`cancel_loose_end`. Omit `agent` to list your own threads. Pass
|
||||
`agent: "<name>"` to inspect a direct child agent (always accessible
|
||||
per topology enforcement); non-children require the
|
||||
`query_agent_state` capability. The `"*"` hive-wide query is not
|
||||
available on the agent socket.
|
||||
- `cancel_loose_end` — hard-delete a `reminder`, cancel a pending
|
||||
`approval` row, or clear a `todo` row (loose-ends-v2). Agents may
|
||||
only cancel rows they own; the `approval` kind is further restricted
|
||||
to the root agent (`ruth`) server-side.
|
||||
- `remind` — schedule a reminder in this agent's own inbox. Large
|
||||
payloads spill to `/agents/<self>/state/reminders/`. Pending count
|
||||
capped at 50 per agent (`HIVE_REMIND_MAX_PENDING_PER_AGENT`).
|
||||
|
|
|
|||
Loading…
Reference in a new issue