p-e relay (remote)

Agent Relay & Adjudication Protocol (v1.0-SPEC)

An industrial-grade, leaderless, multi-agent synchronization and dispute resolution protocol designed for autonomous LLM swarms (Claude, GPT-4o, Gemini, Mistral, and Human Architects).

Built upon canonical cryptographic digests (RFC 8785 / Proverbs 11:1), causal monotonicity (Hybrid Logical Clocks / HLC), atomic lock-free append ledgers (POSIX O_CREAT | O_EXCL), and adversarial cross-examination (Proverbs 18:17 Adjudication Court).

---

🏛️ Core Architectural Invariants (SPEC MUST 1–8)

1. RFC 8785 JCS Canonicalization (MUST 1): Cryptographic SHA-256 digests are computed strictly on recursively sorted JSON keys, IEEE 754-normalized floats, and UTF-8 encoded payloads ("A false balance is an abomination to the Lord, but a just weight is his delight" — Proverbs 11:1).
2. Hybrid Logical Clocks (MUST 2): Every envelope carries physical UTC time combined with a monotonic Lamport counter (physical_ms:counter:node_id) guaranteeing causal ordering across asynchronous nodes without NTP drift failure.
3. Atomic Slot Allocation via O_CREAT | O_EXCL (MUST 3): Concurrent write races are resolved at the kernel filesystem level. If two agents attempt to claim the same sequence slot seq: N, the collision returns EEXIST, forcing the loser to increment seq monotonically.
4. Adversarial Triad & Adjudication (MUST 4): No claim is ratified without adversarial cross-examination ("The one who states his case first seems right, until the other comes and examines him" — Proverbs 18:17).
5. Zero Implicit Trust (MUST 5): Inter-agent envelopes must be verifiable offline and independently validated across different toolchains (TypeScript, Python, Rust, Go).
6. Known-Missing Retention (MUST 6): When an envelope payload is purged/compacted or lost, the ledger retains its sequence slot, locator, and SHA-256 digest with status MISSING to prevent phantom slot re-use.
7. Cross-Platform Rosetta Compatibility (MUST 7): Exact wire compatibility across JSON, YAML, Protocol Buffers, FlatBuffers, and MCP (Model Context Protocol).
8. Real-time SSE & File Bus Streaming (MUST 8): Sub-millisecond reactive subscriptions via Server-Sent Events (SSE) and POSIX file watchers.

---

🚀 Quick Start

Prerequisites

• Node.js 20+ (the scripts run under it; this is what the hosting container has)
• Bun 1.1+ optional — a faster installer and runner for the same scripts

Installation & Run

# Clone the repository
git clone https://github.com/your-username/agent-relay.git
cd agent-relay

# Install dependencies — bun, because bun.lock is the lockfile here
bun install --frozen-lockfile

# Start development server (Port 3000)
bun run dev

# Build production bundle
bun run build
bun run start

Open http://localhost:3000 to access the full Interactive Workbench, Live Relay Ledger, and Autonomous Agent Chat.

The commands above are bun, and the scripts they run stay Node-compatible on purpose. This is an AI Studio applet (metadata.json), and the hosting container invokes npm run build and npm start in a Node image with no bun on PATH. So npm is not a habit to be migrated away from here — it is what one real deployment target does, and package.json requires no binary either runtime lacks. CI keeps a node job for that reason and a bun job because O_CREAT | O_EXCL is implemented by each runtime for itself.

Everything this repository controls — deploy.sh, the contributor steps, the commands above — uses bun, and bun install --frozen-lockfile is the deterministic install: bun.lock is the only lockfile committed, and npm would write a second one that can disagree with it.

Environment

HOST	Interface to bind. Defaults to 127.0.0.1. This process authenticates nothing, so anything wider is a deliberate act and belongs behind a reverse proxy that does.
PORT	Defaults to 3000.
NODE_ENV	production serves the built client from dist/. Anything else starts a Vite dev server, which is not meant to face a network. bun run start sets it.
PE_STORE_ROOT	Read an existing p-e relay store instead of this project's own. Read-only: write, delete and reset are declared unavailable and refused with 405.
ALLOW_SERVER_MODEL_CALLS	1 enables the three routes that run models on API keys held by this process — /api/relay/adjudicate, /api/relay/step-triad, /api/relay/agent-exec — none of which has authentication of its own. Off by default. ALLOW_AGENT_EXEC is accepted as the former name.

---

📦 Project Structure

.
├── src/
│   ├── components/
│   │   ├── AgentChatInterface.tsx    # Multi-agent chat with 1-click Triad & Court
│   │   ├── LiveRelayConsole.tsx      # Real-time ledger, sequencer & SSE observer
│   │   ├── AdjudicationWorkbench.tsx # Court state machine (Proverbs 18:17)
│   │   ├── RosettaMatrix.tsx         # Cross-language wire serializers
│   │   ├── EnvelopeStudio.tsx        # RFC 8785 canonizer & digest generator
│   │   ├── FailureSandbox.tsx        # Chaos injection & invariant stress tests
│   │   ├── BridgeExporter.tsx        # MCP & Tool definitions export
│   │   └── Navbar.tsx                # Responsive top navigation
│   ├── App.tsx                       # Root React 19 application
│   ├── main.tsx                      # Vite React mount point
│   └── index.css                     # Tailwind CSS & theme tokens
├── server.ts                         # Express + Atomic POSIX Store + SSE Hub
├── docs/                             # Architecture specs & Engineering Backlog
│   ├── ARCHITECTURE.md               # In-depth architectural blueprint
│   └── BACKLOG_AND_DEBT.md           # Engineering insights, debt & roadmap
├── metadata.json                     # AI Studio runtime metadata
├── AGENTS.md                         # Context & rules for autonomous AI coding agents
├── CONTRIBUTING.md                   # Contribution guidelines
├── LICENSE                           # MIT License
└── package.json                      # Build scripts & dependency declarations

---

🛠️ API & Wire Protocol

Envelope Specification

{
  "seq": 42,
  "locator": "agent:claude/42@2026-09-01T16:45:00.000Z",
  "from": "agent:claude-code",
  "to": "agent:chatgpt-adversary",
  "type": "claim",
  "title": "HLC Monotonic Invariant Proposal",
  "parent_locator": "agent:human/41@2026-09-01T16:44:00.000Z",
  "hlc": "1788281100000:0001:claude",
  "digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "payload": {
    "body": "Proposed RFC 8785 canonical digest validator."
  }
}

Core HTTP Endpoints

• POST /api/relay/deposit — Atomically deposit an envelope using O_CREAT | O_EXCL
• GET /api/relay/records — Fetch current sequence ledger & envelope state
• GET /api/relay/events — Real-time Server-Sent Events (SSE) feed
• POST /api/relay/adjudicate — Execute Proverbs 18:17 Adjudication verdict via Gemini
• POST /api/relay/agent-exec — Autonomous agent reasoning & response dispatcher

---

📜 Biblical & Mathematical Foundations

• Proverbs 11:1: "Dishonest scales are an abomination to the LORD, but a just weight is His delight." — Foundational rule for bit-exact JSON Canonicalization (RFC 8785).
• Proverbs 18:17: "The first to state his case seems right, until another comes and examines him." — Protocol mandate for adversarial cross-examination prior to ledger ratification.

---

📄 License

MIT License. Free for open-source research and enterprise distributed agent deployments.