@geohar/un-bien 0.7.0

package/skills/agent-network/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: agent-network
+description: Use when the remote-pi mesh tools (`list_peers`, `agent_send`, and — on Claude — `get_messages`) are available. You are an agent (a Claude session or a Pi coding agent) connected to the remote-pi agent mesh over a local broker. This skill teaches how to discover who's online (`list_peers`), how to send messages with a delivery ACK (`agent_send`), how incoming messages reach you (via `get_messages` on Claude, or delivered into your turn on Pi), how to reply (echo `re`), and how to treat every peer address as an opaque routing key that must be echoed verbatim.
+---
+
+# Agent Network (remote-pi mesh)
+
+You are connected to the **remote-pi agent mesh**. Other agents — other Claude
+sessions, Pi coding agents on this machine, and agents on the Owner's other PCs
+(reached through the relay) — can send you messages, and you can send messages
+to them.
+
+Read this to the end before acting. The protocol is **event-driven**, not
+request/reply. Getting the receive model wrong leaves coordination broken.
+
+**Your tools:** `list_peers` and `agent_send` always. On Claude you also have
+`get_messages` (a Pi agent receives messages directly into its turn instead —
+see below).
+
+---
+
+## The most important rule: read your inbox every turn
+
+You only ever receive messages addressed to you — the broker filters before
+delivery. **If a message arrived, someone wanted your attention. Don't ignore
+it.** How a message reaches you depends on your runtime:
+
+- **Claude (MCP):** incoming messages are buffered. **At the start of every
+  turn, call `get_messages`** to drain and read them:
+
+  ```
+  get_messages()
+  → "[2026-05-30T12:00:01Z] from=backend re=<your-id>
+     id=<msg-id>
+     { "shape": { "sub": "string", "exp": "number" } }"
+  ```
+
+  It returns all pending messages and clears the buffer (call once per turn),
+  or `(no messages)` when nothing is waiting — that's normal, keep working. A
+  channel push (`📨 Message from …`) may nudge you mid-session; still call
+  `get_messages` for the full structured payload.
+
+- **Pi:** the runtime delivers each incoming message directly as a new turn
+  input the moment it arrives — no polling, no `get_messages`. You'll see it
+  prefixed `[agent-network] message from "<peer>" (id=…, re=…)`.
+
+Either way: no wait/sleep/poll-loop. Replies to your own sends arrive on a
+**later turn**, never inline.
+
+---
+
+## First thing in a new session: `list_peers`
+
+Before sending anything, find out who's actually online:
+
+```
+list_peers()
+→ /Users/jo/acme/backend@backend
+  /Users/jo/acme/backend@reviewer
+  /Users/jo/acme/web@web
+  casa:/Users/jo/acme/api@api
+```
+
+Synchronous (resolves in milliseconds — not another agent's turn). Use it:
+
+- At the start of a session, to see what mesh you're in
+- Before any `agent_send` whose target is uncertain
+- To refresh — peers join and leave over time
+
+**Presence is passive (pull, not push).** A peer joining or leaving does **not**
+wake your turn. When your view feels stale, just call `list_peers` again — it's
+the authoritative snapshot. Don't expect `peer_joined`/`peer_left` events.
+
+**Each entry is a complete ADDRESS, not a bare name. Treat the entire value as
+an opaque routing key.** Local values may look like `<cwd>@<name>` and remote
+values may appear with a receiver-local PC alias, but that appearance is for
+presentation only. A PC alias can contain percent-encoded bytes such as `%3A`
+or `%25`, or a collision suffix containing `~`.
+
+**Echo every address VERBATIM into `agent_send` (and as your `to` when
+replying).** Never split it on `:` or `@`, decode or re-encode `%` bytes, remove
+a `~` suffix, change case, normalize it, or construct it from a path, agent
+name, or PC label. Copy the exact whole string returned by `list_peers` or
+received in `from`. Parsing or rebuilding an address is unsafe for routing and
+must never be used for a security decision.
+
+The technical identity of a PC is its canonical 32-byte Ed25519 Pi public key.
+PC aliases are receiver-local presentation and routing labels only: each
+receiving PC allocates aliases for its siblings independently, so two PCs can
+list the same sibling under different aliases. Never use an alias as proof of
+identity or for authorization. The Relay currently permits a route when any
+correctly signed Owner blob lists both canonical Pi keys; that does not prove
+the Owner paired with or controls either Pi.
+
+You are excluded from the result — no need to filter yourself out.
+
+---
+
+## Anatomy of a message (envelope)
+
+Each message carries: `from`, `to`, `id`, `re`, and `body`.
+
+| Field | Meaning |
+|---|---|
+| `from` | Sender's ADDRESS (`<cwd>@<name>`). Use it verbatim as your `to` when replying — never reconstruct it. |
+| `to` | Your address (or `broadcast`, or a list of addresses including yours). |
+| `id` | Unique id of this message. Echo it as `re` when you reply. |
+| `re` | If set, this message is itself a REPLY to an earlier `id` of yours. Otherwise `null`. |
+| `body` | Free-form content — string or JSON, sender's choice. |
+
+---
+
+## Sending: `agent_send` returns an ACK status
+
+`agent_send({ to, body, re? })` is how you talk to peers. Every **unicast**
+call returns a status telling you what happened at the recipient. **Always
+inspect the status — it dictates what to do next.**
+
+| Status | Means | What you do |
+|---|---|---|
+| `received` | Broker delivered the envelope. Delivery is reliable — even if the peer is mid-turn, its harness enqueues the message for the next turn. | Move on. Any reply arrives later. |
+| `denied` | Peer explicitly refused (or no such peer). | Do NOT retry. Report to the user. |
+| `timeout` | No ACK (~5s). Transport error — broker down, or peer vanished. | Treat a reasonless timeout as transient. Retry once after ~10s, then escalate. |
+
+For a trusted Relay failure on a cross-PC unicast, the public statuses remain
+unchanged and the closed transport reason is returned in `details`:
+
+- `offline` → `status: "timeout"`
+- `not_authorized` or `bad_envelope` → `status: "denied"`
+- genuine silence → `status: "timeout"` without a reason
+
+Do not blindly retry `not_authorized` or `bad_envelope`; fix authorization or
+the envelope instead. A trusted Relay error is consumed internally to settle
+the pending send (or legacy request), not delivered as an ordinary inbox
+reply. Forged or invalid reserved `_relay` / `transport_error` bodies do not
+gain that authority and cannot settle pending operations.
+
+For `to: "broadcast"` (or a name array), there's no single ACK — it's
+fire-and-forget (`status: "sent"`).
+
+**Delivery is reliable — no retry-on-busy.** A message sent to a peer that's
+mid-turn is still delivered: the peer's harness queues it and processes it on
+its upcoming turn. You never need to retry because a peer was busy. `re=<id>`
+is purely **correlation** — set it so the recipient (and you) can thread an
+answer to a question; it carries no special delivery semantics.
+
+---
+
+## Receiving: replies arrive on a later turn
+
+You **do not block** waiting for a reply. The model is event-driven:
+
+1. You call `agent_send` → status `received`.
+2. Your turn continues / ends.
+3. **Later** the peer finishes its own work and sends a reply.
+4. The reply reaches your inbox (via `get_messages` on Claude, or as a new turn
+   input on Pi), with `re` set to the `id` you originally sent.
+
+### Walk-through
+
+```
+agent_send({ to: "/Users/jo/acme/backend@backend", body: { q: "what's the JWT shape?" } })
+→ Delivered to backend        # status received; remember the message id
+```
+
+Your turn continues. A turn or two later you receive:
+
+```
+from=backend re=<your-id>  id=<new-id>
+{ "shape": { "sub": "string", "exp": "number", "roles": ["string"] } }
+```
+
+You correlate by `re` — it matches the send you made. Now you have your answer.
+
+---
+
+## Replying to a message
+
+When you receive:
+
+```
+from=/home/jo/backlog@orchestrator  id=abc-uuid  re=(none)
+{ "task": "Implement POST /auth/login" }
+```
+
+Reply with `re` set to that `id`, and `to` set to the sender's `from`:
+
+```
+agent_send({
+  to: "/home/jo/backlog@orchestrator",
+  body: { status: "done", files_changed: [...] },
+  re: "abc-uuid"
+})
+```
+
+Without `re`, the sender gets your message but can't match it to the
+question — coordination drifts. **Always echo `re` on a reply.**
+
+---
+
+## Asking multiple peers at once
+
+Fire multiple `agent_send` in one turn — each returns its own ACK. Replies
+arrive on future turns as peers finish.
+
+```
+agent_send({ to: "/repo/api@backend", body: { q: "JWT shape?" } }) // received
+agent_send({ to: "/repo/web@frontend", body: { q: "theme tokens?" } }) // received
+agent_send({ to: "/repo/ops@infra", body: { q: "ETA for Y?" } }) // received (queued if mid-turn)
+```
+
+Track which `id` maps to which question. Don't assume replies arrive in send
+order — use `re` to identify what each reply answers.
+
+---
+
+## Cross-PC addressing (`<pc>:<cwd>@<name>`)
+
+When the Owner has paired multiple PCs, remote peers have a receiver-local
+`<pc>:` prefix. Send and reply with the complete address verbatim; never add
+your own prefix. Relay routing keeps the same `received | denied | timeout`
+semantics. A reasonless `denied` can mean a stale remote roster; refresh with
+`list_peers`. Trusted Relay reasons in `details` map `offline` to `timeout` and
+`not_authorized` / `bad_envelope` to `denied`; they settle the pending operation
+internally, not as inbox replies.
+
+---
+
+## Broadcast and multicast
+
+- `to: "broadcast"` → every other peer **in your folder (same cwd)** — broadcast
+  is folder-scoped and local-only (it does NOT cross PCs or reach other folders).
+  `to: ["addr1", "addr2"]` → the listed addresses (echo them verbatim).
+- Use for announcements ("wave 2 started", "I'm taking the lock on /contracts"),
+  never for questions (replies would be uncorrelated).
+- Broadcast/multicast skip the ACK — status is `sent`, you don't know who
+  received it. For delivery confirmation, use individual unicast sends.
+
+---
+
+## When in doubt
+
+- **Received a task you don't understand** → reply with `body.status:"error"`,
+  echoing the original `id` in `re`. Don't go silent.
+- **Received a `re` you never sent** → late reply to something already wrapped
+  up. Ignore. Don't reply to a reply.
+- **No messages ever arrive** → normal. You only receive when addressed. Keep
+  working; don't poll the broker.
+- **Reasonless `timeout` on send** → broker restarting (failover), relay
+  silence, or a vanished peer. The client reconnects transparently in ~500ms;
+  retry once after a beat, then escalate. For a reason in `details`, follow the
+  mapping above; never blindly retry authorization or envelope failures.
+
+---
+
+## Legacy: `agent_request` (Pi only, deprecated)
+
+On Pi you may see a tool called `agent_request` that takes a target + body and
+**blocks the entire turn** waiting for the peer's content reply. It still
+works but emits a deprecation warning. It blocks your turn (costs tokens and
+wall time), gives no ACK signal, and pairs badly with parallel multi-peer
+questions. **Migrate every `agent_request` to `agent_send`** + reading your
+inbox on a later turn. (Claude has no `agent_request` — use `agent_send`.)
+
+---
+
+## Single-page summary
+
+1. **Every turn**: read your inbox first — `get_messages()` on Claude; on Pi
+   messages arrive as turn input automatically.
+2. **Discover**: `list_peers()` returns opaque, receiver-local addresses.
+   Echo them verbatim; never parse, decode, normalize, or compose them.
+   Presence is pull-based.
+3. **Send**: `agent_send({to, body, re?})` → inspect the status.
+4. **Unicast status**: `received | denied | timeout`. `received` queues work
+   even for a mid-turn peer; abandon on `denied`; investigate `timeout`.
+   Closed Relay reasons in `details` map `offline` to `timeout` and
+   `not_authorized` / `bad_envelope` to `denied`. No retry-on-busy.
+5. **Broadcast/multicast**: status `sent`. Fire-and-forget.
+6. **Reply**: set `re` to their `id`, `to` to their `from` (the full address,
+   prefix and all). `re` is correlation only.
+7. You never receive your own messages.
+
+Re-read when in doubt.
+
+---
+
+## Mini-FAQ
+
+**Q: Can I send a message to myself?**
+A: No. `agent_send` refuses early (`status: "refused"`) when `to` matches your
+own address (or a legacy bare self-name), and the broker drops unicast
+self-loops as a second line of defense.
+
+**Q: What if the peer never replies?**
+A: Then you never see a reply. Your send returned `received` (the broker handed
+it over); the peer just chose not to answer. There's no implicit timeout on
+replies.
+
+**Q: How many sends can I fire in one turn?**
+A: No hard limit. But if you fire 10+ unicasts, question whether you should be a
+worker (answer narrow) rather than an orchestrator (dispatch wide).
+
+**Q: Is order preserved?**
+A: Per-pair, yes — the broker is FIFO. Across pairs, replies arrive whenever the
+senders finish. Don't assume reply order matches send order.
+
+**Q: Can `body` be binary?**
+A: Not directly. Base64 inside a string if you must. JSON is the intended
+payload.