@perkos/perkos-a2a 0.3.5 → 0.5.0

package/README.md

@@ -1,620 +1,291 @@
-# @perkos/a2a
+# @perkos/perkos-a2a
 
-Agent-to-Agent (A2A) protocol communication plugin for [OpenClaw](https://github.com/openclaw/openclaw).
+Agent-to-Agent (A2A) protocol plugin for [OpenClaw](https://openclaw.ai). Enables multi-agent communication using Google's A2A protocol specification with enterprise-grade relay infrastructure for NAT traversal.
 
-Implements Google's [A2A Protocol](https://github.com/a2aproject/A2A) (v0.3.0) to enable OpenClaw agents to discover each other, send tasks, and collaborate autonomously.
+## Quick Start
 
-## Features
-
-- **Agent Card Discovery** — Each agent publishes identity and skills at `/.well-known/agent-card.json`
-- **JSON-RPC 2.0** — Standard A2A protocol methods: `message/send`, `tasks/get`, `tasks/list`, `tasks/cancel`
-- **OpenClaw Tools** — `a2a_discover`, `a2a_send_task`, `a2a_task_status` available to the LLM
-- **CLI Commands** — `openclaw a2a status`, `openclaw a2a discover`, `openclaw a2a send`
-- **Peer Discovery** — Automatic discovery of online agents in the network
-- **Background Service** — A2A HTTP server runs alongside the OpenClaw gateway
-
-## Architecture
-
-### System Overview
-
-```mermaid
-graph TB
-    subgraph Internet
-        TG[Telegram]
-    end
+```bash
+# Install the plugin
+openclaw plugin install @perkos/perkos-a2a
 
-    subgraph Docker Network - council
-        subgraph Mimir Container
-            M_OC[OpenClaw Gateway :3000]
-            M_A2A["@perkos/a2a Plugin :5000"]
-            M_OC --- M_A2A
-        end
-
-        subgraph Tyr Container
-            T_OC[OpenClaw Gateway :3000]
-            T_A2A["@perkos/a2a Plugin :5000"]
-            T_OC --- T_A2A
-        end
-
-        subgraph Bragi Container
-            B_OC[OpenClaw Gateway :3000]
-            B_A2A["@perkos/a2a Plugin :5000"]
-            B_OC --- B_A2A
-        end
-
-        subgraph Idunn Container
-            I_OC[OpenClaw Gateway :3000]
-            I_A2A["@perkos/a2a Plugin :5000"]
-            I_OC --- I_A2A
-        end
-    end
+# Run the setup wizard to detect your environment
+openclaw perkos-a2a setup
 
-    TG <--> M_OC
-    TG <--> T_OC
-    TG <--> B_OC
-    TG <--> I_OC
-
-    M_A2A <-->|A2A JSON-RPC| T_A2A
-    M_A2A <-->|A2A JSON-RPC| B_A2A
-    M_A2A <-->|A2A JSON-RPC| I_A2A
-    T_A2A <-->|A2A JSON-RPC| B_A2A
-    T_A2A <-->|A2A JSON-RPC| I_A2A
-    B_A2A <-->|A2A JSON-RPC| I_A2A
-
-    style M_OC fill:#eb1b69,color:#fff
-    style T_OC fill:#eb1b69,color:#fff
-    style B_OC fill:#eb1b69,color:#fff
-    style I_OC fill:#eb1b69,color:#fff
-    style M_A2A fill:#8e2051,color:#fff
-    style T_A2A fill:#8e2051,color:#fff
-    style B_A2A fill:#8e2051,color:#fff
-    style I_A2A fill:#8e2051,color:#fff
+# Check status
+openclaw perkos-a2a status
 ```
 
-### Plugin Architecture
-
-```mermaid
-graph LR
-    subgraph OpenClaw Gateway
-        LLM[LLM Agent]
-        Tools[Tool Registry]
-        Session[Session Manager]
-    end
-
-    subgraph "@perkos/a2a Plugin"
-        Service[Background Service]
-        Express[Express HTTP Server]
-        AgentCard[Agent Card Provider]
-        TaskStore[In-Memory Task Store]
-        Client[A2A Client]
-    end
-
-    subgraph Endpoints
-        WK["/.well-known/agent-card.json"]
-        RPC["/a2a/jsonrpc"]
-        Health["/health"]
-        Peers["/a2a/peers"]
-        Send["/a2a/send"]
-    end
+Add to your `openclaw.json`:
 
-    LLM --> Tools
-    Tools -->|a2a_discover| Client
-    Tools -->|a2a_send_task| Client
-    Tools -->|a2a_task_status| Client
-
-    Service --> Express
-    Express --> WK
-    Express --> RPC
-    Express --> Health
-    Express --> Peers
-    Express --> Send
-
-    RPC --> TaskStore
-    WK --> AgentCard
-    Client -->|HTTP POST| RPC
-
-    style LLM fill:#eb1b69,color:#fff
-    style Service fill:#8e2051,color:#fff
-    style Express fill:#76437b,color:#fff
+```json
+{
+  "plugins": {
+    "entries": {
+      "perkos-a2a": {
+        "config": {
+          "agentName": "my-agent",
+          "port": 5050,
+          "mode": "auto",
+          "peers": {
+            "other-agent": "http://10.0.0.2:5050"
+          },
+          "relay": {
+            "url": "wss://relay.perkos.xyz",
+            "apiKey": "your-agent-api-key",
+            "enabled": true
+          },
+          "auth": {
+            "requireApiKey": true,
+            "apiKeys": ["key1", "key2"]
+          }
+        }
+      }
+    }
+  }
+}
 ```
 
-## Protocol Specification
+## Architecture
 
-### A2A Protocol Layers
+### Relay Hub (NAT Traversal)
 
-This plugin implements the three layers of the A2A Protocol Specification:
+Agents behind NAT connect outbound to the relay hub via WebSocket. The relay routes messages between agents, queues messages for offline agents, and maintains a presence registry.
 
 ```mermaid
 graph TB
-    subgraph "Layer 1: Data Model"
-        Task[Task]
-        Message[Message]
-        AgentCard[AgentCard]
-        Part[Part]
-        Artifact[Artifact]
+    subgraph "A2A Relay Hub (Cloud VPS)"
+        RH[WebSocket Broker]
+        MQ[Message Queue]
+        REG[Agent Registry]
+        AUTH[API Key Auth]
+        RL[Rate Limiter]
     end
 
-    subgraph "Layer 2: Operations"
-        SendMsg["message/send"]
-        GetTask["tasks/get"]
-        ListTasks["tasks/list"]
-        CancelTask["tasks/cancel"]
-        GetCard["agent/card"]
+    subgraph "Agent A (Behind NAT)"
+        OC_A[OpenClaw Gateway] --> P_A[perkos-a2a plugin]
+        P_A --> RC_A[Relay Client]
     end
 
-    subgraph "Layer 3: Protocol Binding"
-        JSONRPC["JSON-RPC 2.0 over HTTP"]
+    subgraph "Agent B (VPS)"
+        OC_B[OpenClaw Gateway] --> P_B[perkos-a2a plugin]
+        P_B --> S_B[HTTP Server :5050]
+        P_B --> RC_B[Relay Client]
     end
 
-    Task --> SendMsg
-    Message --> SendMsg
-    AgentCard --> GetCard
-    Part --> Message
-    Artifact --> Task
-
-    SendMsg --> JSONRPC
-    GetTask --> JSONRPC
-    ListTasks --> JSONRPC
-    CancelTask --> JSONRPC
-    GetCard --> JSONRPC
-
-    style Task fill:#e1f5fe,color:#000
-    style Message fill:#e1f5fe,color:#000
-    style AgentCard fill:#e1f5fe,color:#000
-    style Part fill:#e1f5fe,color:#000
-    style Artifact fill:#e1f5fe,color:#000
-    style SendMsg fill:#f3e5f5,color:#000
-    style GetTask fill:#f3e5f5,color:#000
-    style ListTasks fill:#f3e5f5,color:#000
-    style CancelTask fill:#f3e5f5,color:#000
-    style GetCard fill:#f3e5f5,color:#000
-    style JSONRPC fill:#e8f5e8,color:#000
-```
-
-### Task Lifecycle
+    subgraph "Agent C (Behind NAT)"
+        OC_C[OpenClaw Gateway] --> P_C[perkos-a2a plugin]
+        P_C --> RC_C[Relay Client]
+    end
 
-```mermaid
-stateDiagram-v2
-    [*] --> submitted: message/send received
-    submitted --> working: Processing begins
-    working --> completed: Task finished successfully
-    working --> failed: Error during processing
-    working --> canceled: tasks/cancel received
-    completed --> [*]
-    failed --> [*]
-    canceled --> [*]
+    RC_A <-->|WSS| RH
+    RC_B <-->|WSS| RH
+    RC_C <-->|WSS| RH
+    RC_B <-->|Direct HTTP| S_B
+
+    style RH fill:#1d1029,stroke:#eb1b69,color:#fff
+    style MQ fill:#45193c,stroke:#eb1b69,color:#fff
+    style REG fill:#45193c,stroke:#eb1b69,color:#fff
+    style AUTH fill:#45193c,stroke:#eb1b69,color:#fff
+    style RL fill:#45193c,stroke:#eb1b69,color:#fff
+    style OC_A fill:#1d1029,stroke:#eb1b69,color:#fff
+    style OC_B fill:#1d1029,stroke:#eb1b69,color:#fff
+    style OC_C fill:#1d1029,stroke:#eb1b69,color:#fff
+    style P_A fill:#8e2051,stroke:#eb1b69,color:#fff
+    style P_B fill:#8e2051,stroke:#eb1b69,color:#fff
+    style P_C fill:#8e2051,stroke:#eb1b69,color:#fff
 ```
 
-### Agent Discovery Sequence
+### Direct Peer-to-Peer
+
+Agents on the same network or with public IPs can communicate directly via HTTP without a relay.
 
 ```mermaid
-sequenceDiagram
-    participant User
-    participant Mimir as Mimir (Orchestrator)
-    participant TyrCard as Tyr /.well-known/agent-card.json
-    participant BragiCard as Bragi /.well-known/agent-card.json
-    participant IdunnCard as Idunn /.well-known/agent-card.json
-
-    User->>Mimir: "Discover all agents"
-    activate Mimir
-    Mimir->>Mimir: a2a_discover tool invoked
-
-    par Parallel Discovery
-        Mimir->>TyrCard: GET /.well-known/agent-card.json
-        TyrCard-->>Mimir: AgentCard {name, skills, url}
-    and
-        Mimir->>BragiCard: GET /.well-known/agent-card.json
-        BragiCard-->>Mimir: AgentCard {name, skills, url}
-    and
-        Mimir->>IdunnCard: GET /.well-known/agent-card.json
-        IdunnCard-->>Mimir: AgentCard {name, skills, url}
+graph TB
+    subgraph "Agent A (VPS)"
+        OC_A[OpenClaw Gateway] --> P_A[perkos-a2a plugin]
+        P_A --> S_A[A2A Server :5050]
+        P_A --> C_A[A2A Client]
+        S_A --> AC_A["/.well-known/agent-card.json"]
+        S_A --> RPC_A["/a2a/jsonrpc"]
     end
 
-    Mimir-->>User: "3 agents online: Tyr (engineering), Bragi (comms), Idunn (product)"
-    deactivate Mimir
-```
-
-### Task Delegation Sequence
+    subgraph "Agent B (VPS)"
+        OC_B[OpenClaw Gateway] --> P_B[perkos-a2a plugin]
+        P_B --> S_B[A2A Server :5050]
+        P_B --> C_B[A2A Client]
+    end
 
-```mermaid
-sequenceDiagram
-    participant User
-    participant Mimir as Mimir (Orchestrator)
-    participant TyrA2A as Tyr A2A Server
-    participant TyrOC as Tyr OpenClaw Agent
-    participant TyrFS as Tyr Workspace
-
-    User->>Mimir: "Ask Tyr to implement rate limiting"
-    activate Mimir
-    Mimir->>Mimir: a2a_send_task(target="tyr", message="...")
-
-    Mimir->>TyrA2A: POST /a2a/jsonrpc {method: "message/send"}
-    activate TyrA2A
-
-    TyrA2A->>TyrA2A: Create Task (state: submitted)
-    TyrA2A-->>Mimir: Task {id, status: "submitted"}
-    Mimir-->>User: "Task sent to Tyr. ID: abc-123"
-    deactivate Mimir
-
-    TyrA2A->>TyrA2A: Process Task (state: working)
-    TyrA2A->>TyrFS: Write task to memory/a2a-task-{id}.md
-    TyrA2A->>TyrA2A: Complete Task (state: completed)
-    deactivate TyrA2A
-
-    Note over TyrOC: Agent picks up task<br/>from workspace on<br/>next heartbeat/session
-
-    User->>Mimir: "Check status of task abc-123 on Tyr"
-    activate Mimir
-    Mimir->>TyrA2A: POST /a2a/jsonrpc {method: "tasks/get", id: "abc-123"}
-    TyrA2A-->>Mimir: Task {status: "completed", artifacts: [...]}
-    Mimir-->>User: "Task completed"
-    deactivate Mimir
+    C_A <-->|JSON-RPC 2.0| S_B
+    C_B <-->|JSON-RPC 2.0| S_A
+
+    style OC_A fill:#1d1029,stroke:#eb1b69,color:#fff
+    style OC_B fill:#1d1029,stroke:#eb1b69,color:#fff
+    style P_A fill:#8e2051,stroke:#eb1b69,color:#fff
+    style P_B fill:#8e2051,stroke:#eb1b69,color:#fff
+    style S_A fill:#76437b,stroke:#eb1b69,color:#fff
+    style S_B fill:#76437b,stroke:#eb1b69,color:#fff
+    style C_A fill:#45193c,stroke:#eb1b69,color:#fff
+    style C_B fill:#45193c,stroke:#eb1b69,color:#fff
 ```
 
-### Multi-Agent Collaboration Sequence
+## Task Lifecycle
 
 ```mermaid
 sequenceDiagram
-    participant J as Julio (Founder)
-    participant M as Mimir (Strategy)
-    participant T as Tyr (Engineering)
-    participant B as Bragi (Comms)
-    participant I as Idunn (Product)
-
-    J->>M: "Build a landing page for PerkOS"
-    activate M
-
-    M->>M: Strategic analysis
-    Note over M: Break into subtasks:<br/>1. UX spec (Idunn)<br/>2. Implementation (Tyr)<br/>3. Copy (Bragi)
-
-    M->>I: a2a_send_task("Design the landing page UX")
-    activate I
-    I-->>M: Task accepted (UX spec)
-    I->>I: Creates wireframes + spec
-    deactivate I
-
-    M->>T: a2a_send_task("Implement landing page per Idunn's spec")
-    activate T
-    T-->>M: Task accepted (implementation)
-    T->>T: Writes Next.js + Tailwind code
-    deactivate T
-
-    M->>B: a2a_send_task("Write landing page copy for PerkOS")
-    activate B
-    B-->>M: Task accepted (copywriting)
-    B->>B: Writes headlines, CTAs, descriptions
-    deactivate B
-
-    M-->>J: "Landing page tasks delegated to Idunn (UX), Tyr (code), Bragi (copy)"
-    deactivate M
+    participant Agent A
+    participant Relay Hub
+    participant Agent B
+
+    Note over Agent A,Agent B: Via Relay (NAT traversal)
+    Agent A->>Relay Hub: WSS: task message (to: Agent B)
+    Relay Hub->>Agent B: WSS: forward task
+    Agent B->>Agent B: Process task + inject into session
+    Agent B->>Relay Hub: WSS: task response
+    Relay Hub->>Agent A: WSS: forward response
+
+    Note over Agent A,Agent B: Via Direct HTTP
+    Agent A->>Agent B: POST /a2a/jsonrpc (message/send)
+    Agent B->>Agent B: Process task + inject into session
+    Agent B-->>Agent A: JSON-RPC response
 ```
 
-## Data Model
+## Running the Relay Hub
 
-### Agent Card
+The relay hub is a lightweight WebSocket broker. Deploy it on any VPS with a public IP.
 
-Each agent publishes an Agent Card describing its identity and capabilities:
+```bash
+# Via npx (development)
+npx tsx bin/relay.ts --port 6060 --api-keys key1,key2
 
-```json
-{
-  "name": "Tyr",
-  "description": "Engineering and execution agent",
-  "protocolVersion": "0.3.0",
-  "version": "1.0.0",
-  "url": "http://perkos-tyr:5000/a2a/jsonrpc",
-  "skills": [
-    {
-      "id": "code",
-      "name": "Code Implementation",
-      "description": "Write production-quality TypeScript, Solidity, Next.js code",
-      "tags": ["coding", "typescript", "solidity"]
-    }
-  ],
-  "capabilities": { "pushNotifications": false },
-  "defaultInputModes": ["text"],
-  "defaultOutputModes": ["text"]
-}
+# Via environment variables
+RELAY_PORT=6060 RELAY_API_KEYS=key1,key2 npx tsx bin/relay.ts
 ```
 
-### Task
+### Relay Hub Options
 
-Tasks track the lifecycle of delegated work:
+| Option | Env Var | Default | Description |
+|---|---|---|---|
+| `--port` | `RELAY_PORT` | 6060 | WebSocket listen port |
+| `--api-keys` | `RELAY_API_KEYS` | (none) | Comma-separated accepted API keys |
+| `--max-queue` | `RELAY_MAX_QUEUE` | 200 | Max queued messages per offline agent |
+| `--rate-limit` | `RELAY_RATE_LIMIT` | 60 | Max messages per agent per minute |
 
-```json
-{
-  "kind": "task",
-  "id": "f49f9755-86b9-4399-9463-fa6b9a11b51a",
-  "contextId": "cc57cc50-762c-41d4-b9a1-59b1ee691a69",
-  "status": {
-    "state": "completed",
-    "timestamp": "2026-03-12T16:24:45.709Z"
-  },
-  "messages": [
-    {
-      "kind": "message",
-      "messageId": "a008eb3e-2fb0-4947-b1e4-15a6d3a8cba5",
-      "role": "user",
-      "parts": [{ "kind": "text", "text": "Implement rate limiting on the API" }],
-      "metadata": { "fromAgent": "mimir" }
-    }
-  ],
-  "artifacts": [
-    {
-      "kind": "artifact",
-      "artifactId": "b2c3d4e5-...",
-      "parts": [{ "kind": "text", "text": "Task queued for processing" }]
-    }
-  ]
-}
-```
+## Modes
 
-### Message
+| Mode | HTTP Server | Relay Client | Use Case |
+|---|---|---|---|
+| `auto` | Conditional | If configured | Detects NAT, chooses best option |
+| `full` | Yes | If configured | VPS with public IP |
+| `client-only` | No | If configured | Behind NAT, no local server |
+| `relay` | No | No | Run as relay hub only |
 
-Messages are communication turns between agents:
+## Configuration
 
 ```json
 {
-  "kind": "message",
-  "messageId": "unique-id",
-  "role": "user",
-  "parts": [
-    { "kind": "text", "text": "Your task description here" }
-  ],
-  "metadata": {
-    "fromAgent": "mimir"
+  "agentName": "my-agent",
+  "port": 5050,
+  "mode": "auto",
+  "skills": [],
+  "peers": {
+    "other-agent": "http://10.0.0.2:5050"
+  },
+  "relay": {
+    "url": "wss://relay.perkos.xyz",
+    "apiKey": "agent-specific-key",
+    "enabled": true
+  },
+  "auth": {
+    "requireApiKey": true,
+    "apiKeys": ["key1", "key2"]
   }
 }
 ```
 
-## JSON-RPC 2.0 Methods
-
-| Method | Description | Request Params | Response |
-|--------|------------|----------------|----------|
-| `message/send` | Send a task to the agent | `{message: Message}` | `Task` |
-| `tasks/get` | Get task by ID | `{id: string}` | `Task` |
-| `tasks/list` | List all tasks | `{}` | `{tasks: Task[]}` |
-| `tasks/cancel` | Cancel a running task | `{id: string}` | `Task` |
-| `agent/card` | Get the agent's card | `{}` | `AgentCard` |
-
-### Example JSON-RPC Request
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `agentName` | string | `"agent"` | This agent's name in the council |
+| `port` | number | `5050` | HTTP server port |
+| `mode` | string | `"auto"` | Operating mode (see table above) |
+| `skills` | array | `[]` | Skills exposed via A2A |
+| `peers` | object | `{}` | Direct peer URLs |
+| `relay.url` | string | - | Relay hub WebSocket URL |
+| `relay.apiKey` | string | - | API key for relay authentication |
+| `relay.enabled` | boolean | `false` | Enable relay connectivity |
+| `auth.requireApiKey` | boolean | `false` | Require API key for inbound HTTP |
+| `auth.apiKeys` | string[] | `[]` | Accepted API keys for inbound HTTP |
 
-```json
-{
-  "jsonrpc": "2.0",
-  "method": "message/send",
-  "id": "req-1",
-  "params": {
-    "message": {
-      "kind": "message",
-      "messageId": "msg-1",
-      "role": "user",
-      "parts": [{"kind": "text", "text": "Review the API security"}],
-      "metadata": {"fromAgent": "mimir"}
-    }
-  }
-}
-```
+## Authentication
 
-### Example JSON-RPC Response
+### Relay Auth
 
-```json
-{
-  "jsonrpc": "2.0",
-  "id": "req-1",
-  "result": {
-    "kind": "task",
-    "id": "task-uuid",
-    "contextId": "ctx-uuid",
-    "status": {"state": "submitted", "timestamp": "2026-03-12T16:00:00Z"},
-    "messages": [...],
-    "artifacts": []
-  }
-}
-```
+Agents authenticate with the relay hub using an API key provided during WebSocket registration. The relay rejects connections with invalid keys.
 
-## HTTP Endpoints
+### HTTP Auth
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/.well-known/agent-card.json` | GET | A2A Agent Card (discovery) |
-| `/a2a/jsonrpc` | POST | JSON-RPC 2.0 endpoint |
-| `/a2a/peers` | GET | Discover all peer agents |
-| `/a2a/send` | POST | REST convenience for sending tasks |
-| `/health` | GET | Health check with agent info |
+When `auth.requireApiKey` is enabled, inbound HTTP requests must include an API key via:
+- `X-API-Key` header
+- `Authorization: Bearer <key>` header
+- `?apiKey=<key>` query parameter
 
-## OpenClaw Integration
+## Session Injection
 
-### Registered Tools
+When a task is received, the plugin attempts to inject it directly into the agent's OpenClaw session using the plugin API (`api.injectMessage`). If session injection is not available, tasks fall back to writing markdown files to the workspace.
 
-| Tool | Description | Parameters |
-|------|-------------|------------|
-| `a2a_discover` | Discover peer agents and capabilities | none |
-| `a2a_send_task` | Send a task to a peer agent | `target`, `message` |
-| `a2a_task_status` | Check status of a sent task | `target`, `taskId` |
+## Agent Tools
 
-### CLI Commands
+When the plugin is active, three tools are available to the agent:
 
-```bash
-openclaw a2a status      # Show A2A agent configuration
-openclaw a2a discover    # Discover and list peer agents
-openclaw a2a send <agent> <message>  # Send a task to a peer
-```
+- `a2a_discover` -- Discover all configured peer agents and their capabilities (direct + relay)
+- `a2a_send_task` -- Send a task to a named peer agent (tries direct HTTP, falls back to relay)
+- `a2a_task_status` -- Check the status of a previously sent task
 
-### Gateway RPC
+## CLI Commands
 
 ```bash
-openclaw gateway call a2a.status  # Get A2A status via RPC
+openclaw perkos-a2a setup      # Detect environment and show recommendations
+openclaw perkos-a2a status     # Show agent status, relay connection, and config
+openclaw perkos-a2a discover   # Discover peer agents (direct + relay)
+openclaw perkos-a2a send <target> <message>  # Send a task to a peer
 ```
 
-## ⚠️ macOS Note
-
-On macOS, **port 5000 is used by AirPlay Receiver** (ControlCenter). The default port is `5050` to avoid conflicts. If the configured port is in use, the plugin automatically tries the next port (up to 3 attempts). Docker/Linux agents can still use port 5000 via explicit config.
-
-## Installation
+## Networking Guide
 
-### From npm
+### Option 1: Relay Hub (Recommended for NAT)
 
-```bash
-openclaw plugins install @perkos/a2a
-```
-
-### Manual Installation
-
-```bash
-git clone https://github.com/PerkOS-xyz/PerkOS-A2A.git
-cd PerkOS-A2A
-npm install
-npm run build
-openclaw plugins install -l .
-```
+Deploy the relay hub on a VPS, configure all agents to connect to it. No port forwarding or tunnels needed.
 
-## Configuration
+### Option 2: Direct (Public IP / Same Network)
 
-Add to your `openclaw.json`:
+Agents with public IPs or on the same network can communicate directly via HTTP. Configure peer URLs in the `peers` config.
 
-```json5
-{
-  plugins: {
-    entries: {
-      "perkos-a2a": {
-        enabled: true,
-        config: {
-          // This agent's name in the network
-          agentName: "mimir",
-          // Port for the A2A HTTP server (default 5050; use 5000 on Linux/Docker)
-          port: 5050,
-          // Skills this agent exposes
-          skills: [
-            {
-              id: "strategy",
-              name: "Strategic Planning",
-              description: "Break down goals into actionable tasks",
-              tags: ["planning", "strategy"]
-            }
-          ],
-          // Peer agents (name -> A2A URL)
-          peers: {
-            tyr: "http://perkos-tyr:5000",
-            bragi: "http://perkos-bragi:5000",
-            idunn: "http://perkos-idunn:5000"
-          }
-        }
-      }
-    }
-  }
-}
-```
+### Option 3: Tailscale
 
-### Configuration Options
+Both agents join the same tailnet. Use Tailscale IPs for peer URLs.
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `agentName` | string | `"agent"` | This agent's name in the network |
-| `port` | number | `5050` | Port for the A2A HTTP server (macOS avoids 5000/AirPlay) |
-| `skills` | array | `[]` | Skills to advertise in the Agent Card |
-| `peers` | object | `{}` | Map of peer agent names to A2A URLs |
-
-## Docker Deployment
-
-For multi-agent setups, use Docker Compose with a shared network:
-
-```yaml
-services:
-  mimir:
-    build: .
-    container_name: perkos-mimir
-    ports:
-      - "3001:3000"  # OpenClaw
-      - "5001:5000"  # A2A
-    environment:
-      - AGENT_NAME=mimir
-    networks:
-      - council
-
-  tyr:
-    build: .
-    container_name: perkos-tyr
-    ports:
-      - "3002:3000"
-      - "5002:5000"
-    environment:
-      - AGENT_NAME=tyr
-    networks:
-      - council
-
-networks:
-  council:
-    driver: bridge
-```
+### Option 4: Client-Only
 
-Agents can discover each other via Docker DNS: `http://perkos-tyr:5000`.
-
-## A2A Protocol Compliance
-
-This plugin implements the [A2A Protocol Specification RC v1.0](https://a2a-protocol.org/latest/specification/):
-
-| Feature | Status |
-|---------|--------|
-| Agent Card at `/.well-known/agent-card.json` | ✅ |
-| JSON-RPC 2.0 binding | ✅ |
-| `message/send` | ✅ |
-| `tasks/get` | ✅ |
-| `tasks/list` | ✅ |
-| `tasks/cancel` | ✅ |
-| Task lifecycle states | ✅ |
-| Text parts | ✅ |
-| Artifact generation | ✅ |
-| Streaming (SSE) | 🔜 Planned |
-| Push notifications | 🔜 Planned |
-| File parts | 🔜 Planned |
-| gRPC binding | 🔜 Planned |
-
-## TypeScript Types
-
-The plugin exports full TypeScript types for the A2A protocol:
-
-```typescript
-import type {
-  AgentCard,
-  AgentSkill,
-  Task,
-  TaskStatus,
-  Message,
-  Part,
-  Artifact,
-  JsonRpcRequest,
-  JsonRpcResponse,
-  A2APluginConfig,
-} from "@perkos/a2a";
-```
+Set `"mode": "client-only"` to only send tasks (not receive). Combine with relay for full bidirectional support.
 
-## Standalone Server
+## Troubleshooting
 
-You can also use the A2A server independently of OpenClaw:
+**Relay connection failing:**
+- Verify the relay URL is correct and reachable
+- Check that your API key matches one configured on the relay hub
+- Look for `[perkos-a2a]` log messages for connection errors
 
-```typescript
-import { A2AServer } from "@perkos/a2a";
+**Port 5050 in use:**
+Change the port in config, or run `lsof -i :5050` to find the conflicting process.
 
-const server = new A2AServer({
-  agentName: "my-agent",
-  port: 5050,
-  skills: [{ id: "chat", name: "Chat", description: "General chat", tags: [] }],
-  peers: {
-    other: "http://other-agent:5050",
-  },
-});
+**Peers show offline:**
+- Verify the peer URL is correct and reachable
+- Check firewalls/security groups
+- If using relay, verify both agents are connected to the same relay hub
 
-server.start();
-```
+**Auth errors (401):**
+- Ensure your API key is in the target agent's `auth.apiKeys` list
+- Check `X-API-Key` header is being sent correctly
 
 ## License
 
 MIT
-
-## Links
-
-- [A2A Protocol Specification](https://a2a-protocol.org/latest/specification/)
-- [A2A GitHub](https://github.com/a2aproject/A2A)
-- [A2A JS SDK](https://github.com/a2aproject/a2a-js)
-- [OpenClaw](https://github.com/openclaw/openclaw)
-- [PerkOS](https://perkos.xyz)