drop the hyperhive send/recv/ack_until tools: agents message over matrix
This commit is contained in:
damocles
mara
parent
ccac95fcf4
commit
bffb2c07a8
4 changed files with 52 additions and 397 deletions
|
|
@ -191,8 +191,8 @@ the full row taxonomy and dispatch logic):
|
|||
(`-` lines from `input.old_string`, `+` lines from
|
||||
`input.new_string` or every line of `input.content`).
|
||||
Summary carries the path + line counts.
|
||||
- others (`Read /path`, `Bash $ cmd`, `mcp__hyperhive__send →
|
||||
operator: "..."`, etc.): flat one-line per-tool format with
|
||||
- others (`Read /path`, `Bash $ cmd`, `mcp__matrix__send_dm →
|
||||
iris: "..."`, etc.): flat one-line per-tool format with
|
||||
per-tool salient-arg extraction (`fmtToolUse`).
|
||||
- `Stream` `tool_result` short → flat `← ...`; long → collapsed
|
||||
`<details>` `▸ ← Nl · headline` (select to expand full body).
|
||||
|
|
|
|||
|
|
@ -220,12 +220,8 @@ the `CLAUDE.md` (see `docs/2-handbook/agents/persistence.md` for the
|
|||
boot-time rename).
|
||||
|
||||
The wake prompt is intentionally minimal: the popped message's
|
||||
`from`/`body`, prefixed with a `[msg #<id>]` broker-row-id marker
|
||||
(so the agent knows what id to pass to `ack_until` for bulk triage;
|
||||
transient pings show no marker because their sentinel id 0 has nothing
|
||||
to ack), plus an inline `({unread} more pending — drain via …)` hint
|
||||
when `unread > 0`. Claude drives any further `recv`/`send` itself via
|
||||
the embedded MCP server.
|
||||
`from` and `body`, behind a redelivery or interruption banner when one applies.
|
||||
The harness drives one turn per inbox message.
|
||||
|
||||
`hive-agent` self-announces once on every boot:
|
||||
`boot_announce::announce` pushes a one-line "you were just
|
||||
|
|
|
|||
|
|
@ -36,41 +36,25 @@ runs on the change.
|
|||
|
||||
## Core tools (always available)
|
||||
|
||||
**Messaging** (`messaging` group): `send(to, body, in_reply_to?)`,
|
||||
`recv(max?)`, `ack_until(up_to)`.
|
||||
**Messaging.** There is no hyperhive messaging tool. Agents talk to peers and the
|
||||
operator over matrix ([matrix](../agent-tools/matrix.md)); `send_dm` takes a peer's agent
|
||||
name (`iris`, meaning that agent on the same homeserver) or a full user id. An agent
|
||||
without matrix tools is cut off from peers on purpose, and the operator reads its
|
||||
`set_status` line, its turn output on the dashboard, and its logs. The `messaging`
|
||||
permission remains an accepted value for stored permission sets, but grants no tool.
|
||||
|
||||
- `send` — hive-local broker message to a peer on this hive (logical name). With
|
||||
the matrix MCP tools, talk to peers over matrix instead (a DM to the `user_id` in
|
||||
`get_agent_meta`'s `matrix_accounts`); `send` is for peers without a matrix
|
||||
account and agents without matrix tools. Optional
|
||||
`in_reply_to: i64` links the message to a prior id for thread
|
||||
rendering. The broker refuses `to: "operator"`. The error
|
||||
points an agent that has the matrix MCP tools at matrix
|
||||
([matrix](../agent-tools/matrix.md)), and tells one without them that the
|
||||
operator reads its `set_status` line, its turn output on the dashboard,
|
||||
and its logs.
|
||||
- `recv` — drain inbox. Always an immediate peek, never blocks. `max`
|
||||
(default 1, cap 5) drains up to N rows. `recv` prefixes each returned row
|
||||
with `[msg #<id>]` (broker row id; note the highest id seen, then pass
|
||||
it to `ack_until` to bulk-triage the batch). **Graceful shutdown**: when the harness
|
||||
receives a stop signal, the inbox becomes fenced and `recv` returns an
|
||||
explicit `from: "graceful-stop"` message instead of an empty inbox.
|
||||
This unmissably directs the agent to flush durable state (`/state`
|
||||
files) and end the turn — the container exits when the turn completes.
|
||||
The graceful-stop turn takes the same post-turn compaction path as any
|
||||
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 large transcript.
|
||||
- `ack_until(up_to)` — bulk-mark inbox rows handled: it stamps every row
|
||||
with broker id `<= up_to` as acked in a single UPDATE.
|
||||
Recipient-scoped (agents can only ack their own rows). Use when a
|
||||
restart redelivers a large backlog of already-handled messages: read
|
||||
the highest `[msg #N]` from the set you've actually processed, then
|
||||
`ack_until(N)` to prevent re-pop. Acked rows never redeliver.
|
||||
Transient pings (sentinel id 0) have nothing to ack and show no marker.
|
||||
The inbox itself is the harness's: it pops one message per turn and acks it when the
|
||||
turn ends, so there is no agent-facing `recv` or `ack_until`. **Graceful shutdown**:
|
||||
when the harness receives a stop signal, the inbox becomes fenced and the harness
|
||||
delivers an explicit `from: "graceful-stop"` message as the turn's prompt. It
|
||||
directs the agent to flush durable state (`/state` files) and end the turn; the
|
||||
container exits when the turn completes. The graceful-stop turn takes the same
|
||||
post-turn compaction path as any 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 large transcript.
|
||||
|
||||
**System messages** (from sender `system`): the broker delivers them as regular inbox
|
||||
messages (same `recv` path). A container crash never reaches an
|
||||
messages (the same path as every other inbox message). A container crash never reaches an
|
||||
agent — it only produces a log line + swarm-level grafana
|
||||
alert, no agent turn at all (`docs/4-implementation/scheduler/observability.md`). Lifecycle
|
||||
transitions the job-queue scheduler or crash watcher drive directly —
|
||||
|
|
|
|||
|
|
@ -123,8 +123,7 @@ request still carries an optional `wait_seconds` (long-poll the first
|
|||
message, once one arrives — or one is already pending — the call
|
||||
drains up to `max` in total): the harness's own turn-driving loop
|
||||
uses it internally (`hive-agent`'s `recv_next`, 180s). The
|
||||
agent-facing MCP `recv` tool doesn't expose this parameter — it
|
||||
always passes `wait_seconds: None`, an immediate peek.
|
||||
agent-facing MCP surface has no `recv` tool at all.
|
||||
|
||||
Per-row bookkeeping inside the broker:
|
||||
|
||||
|
|
@ -188,8 +187,8 @@ Per-variant fields:
|
|||
3339 on the wire, see *Timestamps on the wire* below); clients
|
||||
compute time-until-fire against it.
|
||||
- `PendingMessages { count }` — undelivered inbox messages the
|
||||
agent still owes itself a `recv` for. Informational + not
|
||||
cancellable (drain with `recv`); only emitted when `count > 0`,
|
||||
agent has not handled yet. Informational + not
|
||||
cancellable; only emitted when `count > 0`,
|
||||
and surfaced first in the list as the most
|
||||
actionable signal. Counted host-side from the broker
|
||||
(`count_pending`), so it reflects what's genuinely still queued —
|
||||
|
|
@ -283,7 +282,7 @@ host access it has.
|
|||
|
||||
| Permission | Grants |
|
||||
|---|---|
|
||||
| `messaging` | `send`, `recv`, `ack_until` |
|
||||
| `messaging` | nothing (kept as an accepted value; agents message over matrix) |
|
||||
| `meta` | `get_agent_meta` (`set_status` is always-on, see below) |
|
||||
| `inbox` | `get_loose_ends`, `cancel_loose_end`, `remind` |
|
||||
| `execution` | the `bash` MCP server (`mcp__bash__run`/`status`/`kill`), rendered into the agent's MCP config only with it; a subagent gets Claude's own `Bash` instead. See `docs/4-implementation/agent-tools/bash.md`. |
|
||||
|
|
|
|||
Loading…
Reference in a new issue