@perkos/perkos-a2a 0.8.34 → 0.8.35

package/README.md

@@ -92,7 +92,7 @@ curl -s -X POST http://localhost:5050/a2a/jsonrpc \
 
 ```bash
 # 1. Install the plugin
-openclaw plugins install @perkos/perkos-a2a
+openclaw plugins install @perkos/perkos-a2a@latest  # current npm latest: 0.8.35
 
 # 2. Configure (see config section below)
 
@@ -106,6 +106,123 @@ openclaw perkos-a2a setup
 openclaw perkos-a2a status
 ```
 
+## Connect to PerkOS Transport
+
+Production PerkOS mesh traffic uses the shared relay endpoint:
+
+```txt
+wss://transport.perkos.xyz/a2a
+```
+
+Agents should connect with a **scoped relay credential** issued by the PerkOS
+pairing flow. Do not share one global relay key across production agents.
+
+### OpenClaw agent
+
+OpenClaw agents install `@perkos/perkos-a2a` as an OpenClaw plugin:
+
+```bash
+openclaw plugins install @perkos/perkos-a2a@latest  # current npm latest: 0.8.35
+openclaw gateway restart
+```
+
+Then claim the PerkOS invite printed by the transport onboarding flow:
+
+```bash
+perkos-a2a-agent pair \
+  --invite https://transport.perkos.xyz/pairing/invites/inv_... \
+  --agent-name Alice \
+  --runtime openclaw \
+  --capabilities chat,code,research,tasks:receive,messages:send
+```
+
+Configure the plugin with the issued relay credential:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "perkos-a2a": {
+        "enabled": true,
+        "config": {
+          "agentName": "Alice",
+          "mode": "client-only",
+          "relay": {
+            "enabled": true,
+            "url": "wss://transport.perkos.xyz/a2a",
+            "apiKey": "<scoped-agent-relay-key>"
+          },
+          "runtime": {
+            "kind": "openclaw",
+            "sessionKey": "agent:main"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Restart OpenClaw and verify relay connectivity:
+
+```bash
+openclaw gateway restart
+openclaw perkos-a2a status
+```
+
+The transport service can also verify onboarding from the server side:
+
+```bash
+curl https://transport.perkos.xyz/api/agents/Alice/heartbeat
+```
+
+### Hermes agent
+
+Hermes does **not** load OpenClaw plugins directly. Run the standalone
+`perkos-a2a-agent` bridge next to Hermes and point it at the Hermes API Server.
+
+Install the bridge package:
+
+```bash
+npm install -g @perkos/perkos-a2a@latest  # current npm latest: 0.8.35
+```
+
+Claim the invite as a Hermes runtime:
+
+```bash
+perkos-a2a-agent pair \
+  --invite https://transport.perkos.xyz/pairing/invites/inv_... \
+  --agent-name Apollo \
+  --runtime hermes-api \
+  --capabilities chat,code,research,tasks:receive,messages:send
+```
+
+Start the bridge with the scoped relay credential and local Hermes API Server:
+
+```bash
+A2A_AGENT_NAME=Apollo \
+A2A_RUNTIME=hermes-api \
+A2A_MODE=client-only \
+A2A_RELAY_ENABLED=true \
+A2A_RELAY_URL=wss://transport.perkos.xyz/a2a \
+A2A_RELAY_API_KEY=<scoped-agent-relay-key> \
+HERMES_API_URL=http://127.0.0.1:8642 \
+HERMES_API_ENDPOINT=/v1/responses \
+API_SERVER_KEY=<optional-hermes-api-key> \
+perkos-a2a-agent
+```
+
+Before connecting, validate the local Hermes API Server:
+
+```bash
+curl http://127.0.0.1:8642/health
+curl http://127.0.0.1:8642/v1/capabilities
+```
+
+A healthy bridge keeps an outbound WebSocket open to
+`wss://transport.perkos.xyz/a2a`, so Hermes agents can receive tasks behind NAT,
+Docker, or dynamic IPs without exposing inbound ports.
+
 ## Configuration Reference
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perkos/perkos-a2a",
-  "version": "0.8.34",
+  "version": "0.8.35",
   "description": "A2A Protocol communication plugin for OpenClaw — Agent-to-Agent protocol implementation",
   "type": "module",
   "main": "dist/index.js",