@herbertgao/pi-extensions 2026.10.1 → 2026.10.3

package/node_modules/remote-pi/skills/agent-network/SKILL.md

@@ -1,310 +0,0 @@
----
-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.