@perkos/perkos-a2a 0.3.5 → 0.5.0

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "perkos-a2a",
   "name": "PerkOS A2A",
-  "version": "0.3.5",
+  "version": "0.5.0",
   "description": "Agent-to-Agent (A2A) protocol communication for OpenClaw agents",
   "author": "PerkOS",
   "configSchema": {
@@ -17,49 +17,85 @@
         "default": 5050,
         "description": "Port for the A2A HTTP server (5050 default; macOS uses 5000 for AirPlay)"
       },
+      "mode": {
+        "type": "string",
+        "enum": ["full", "client-only", "relay", "auto"],
+        "default": "auto",
+        "description": "Server mode: full (listen + send), client-only (send only), relay (run as hub), auto (detect)"
+      },
       "skills": {
         "type": "array",
         "items": {
           "type": "object",
           "properties": {
-            "id": {
-              "type": "string"
-            },
-            "name": {
-              "type": "string"
-            },
-            "description": {
-              "type": "string"
-            },
-            "tags": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              }
-            }
+            "id": { "type": "string" },
+            "name": { "type": "string" },
+            "description": { "type": "string" },
+            "tags": { "type": "array", "items": { "type": "string" } }
           }
         },
         "description": "Skills this agent exposes via A2A"
       },
       "peers": {
         "type": "object",
-        "additionalProperties": {
-          "type": "string"
-        },
+        "additionalProperties": { "type": "string" },
         "description": "Map of peer agent names to their A2A URLs"
+      },
+      "relay": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable relay hub connection for NAT traversal"
+          },
+          "url": {
+            "type": "string",
+            "description": "WebSocket URL of the relay hub (e.g. wss://relay.perkos.xyz)"
+          },
+          "apiKey": {
+            "type": "string",
+            "description": "API key for authenticating with the relay hub"
+          },
+          "hubPort": {
+            "type": "number",
+            "default": 8787,
+            "description": "Port when running as relay hub (mode: relay)"
+          },
+          "hubApiKeys": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Valid API keys when running as relay hub"
+          }
+        },
+        "description": "Relay hub configuration for NAT traversal"
+      },
+      "auth": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "requireApiKey": {
+            "type": "boolean",
+            "default": false,
+            "description": "Require API key for incoming HTTP A2A requests"
+          },
+          "apiKeys": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Valid API keys for incoming requests"
+          }
+        },
+        "description": "Authentication configuration for A2A endpoints"
       }
     }
   },
   "uiHints": {
-    "agentName": {
-      "label": "Agent Name",
-      "placeholder": "mimir"
-    },
-    "port": {
-      "label": "A2A Server Port"
-    },
-    "peers": {
-      "label": "Peer Agents (name \u2192 URL)"
-    }
+    "agentName": { "label": "Agent Name", "placeholder": "mimir" },
+    "port": { "label": "A2A Server Port" },
+    "mode": { "label": "Server Mode" },
+    "peers": { "label": "Peer Agents (name -> URL)" },
+    "relay": { "label": "Relay Hub (NAT Traversal)" },
+    "auth": { "label": "Authentication" }
   }
-}
+}

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@perkos/perkos-a2a",
-  "version": "0.3.5",
+  "version": "0.5.0",
   "description": "A2A Protocol communication plugin for OpenClaw \u2014 Agent-to-Agent protocol implementation",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
+    "bin",
     "skills",
     "openclaw.plugin.json"
   ],
+  "bin": {
+    "a2a-relay": "./bin/relay.ts"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
@@ -41,13 +45,15 @@
     "url": "https://github.com/PerkOS-xyz/PerkOS-A2A"
   },
   "dependencies": {
-    "express": "^4.21.0"
+    "express": "^4.21.0",
+    "ws": "^8.18.0"
   },
   "devDependencies": {
     "@sinclair/typebox": "^0.34.0",
     "typescript": "^5.7.0",
     "@types/express": "^5.0.0",
-    "@types/node": "^22.0.0"
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0"
   },
   "peerDependencies": {
     "openclaw": ">=2026.3.0"

package/skills/perkos-a2a/SKILL.md

@@ -0,0 +1,68 @@
+# PerkOS A2A - Agent Skill Guide
+
+## Overview
+
+The PerkOS A2A plugin enables communication between OpenClaw agents using Google's Agent-to-Agent (A2A) protocol. Use these tools to delegate work, discover peers, and track task progress.
+
+## Tools
+
+### a2a_discover
+
+Discover all peer agents in the council. Returns each agent's online/offline status, description, and skills.
+
+**When to use:** Before sending a task, to check which agents are available and what they can do.
+
+**Parameters:** None
+
+**Example:**
+```
+Use a2a_discover to see which agents are online.
+```
+
+### a2a_send_task
+
+Send a task to a specific peer agent. The task is delivered via JSON-RPC and queued for processing.
+
+**When to use:** When you need another agent to perform work -- research, code generation, data processing, etc.
+
+**Parameters:**
+- `target` (required): Name of the peer agent (must match a key in the peers config)
+- `message` (required): The task description/instructions to send
+
+**Example:**
+```
+Use a2a_send_task to ask "mimir" to "Research the latest A2A protocol specification changes"
+```
+
+### a2a_task_status
+
+Check the status of a previously sent task by its ID.
+
+**When to use:** After sending a task, to poll for completion or check progress.
+
+**Parameters:**
+- `target` (required): Name of the agent that received the task
+- `taskId` (required): The task ID returned from a2a_send_task
+
+**Task states:** submitted, working, completed, failed, canceled
+
+## Workflows
+
+### Delegate and check back
+
+1. `a2a_discover` -- see who's online
+2. `a2a_send_task` -- send the task to a capable peer
+3. `a2a_task_status` -- check on progress (may need to poll)
+
+### Multi-agent coordination
+
+1. Discover available agents
+2. Send different subtasks to different agents based on their skills
+3. Collect results via task status checks
+4. Combine outputs for the user
+
+## Notes
+
+- Tasks are asynchronous. After sending, the peer agent processes independently.
+- If the plugin is in client-only mode, you can send tasks but peers cannot send tasks to you.
+- Peer URLs must be configured in the plugin config before you can communicate with them.