gopherhole_openclaw_a2a 0.4.8 → 0.5.0

package/README.md

@@ -13,7 +13,7 @@ Then add to your OpenClaw config (`~/.openclaw/openclaw.json`):
 ```json
 {
   "channels": {
-    "a2a": {
+    "gopherhole": {
       "enabled": true,
       "bridgeUrl": "wss://hub.gopherhole.ai/ws",
       "apiKey": "gph_your_api_key_here"
@@ -28,6 +28,10 @@ Then restart the gateway:
 openclaw gateway restart
 ```
 
+> **Upgrading from 0.4.x?** The channel was renamed from `a2a` to `gopherhole`
+> in 0.5.0. Rename the `channels.a2a` block in your config to
+> `channels.gopherhole`. See [Migration](#migration-from-04x) below.
+
 ## Getting an API Key
 
 1. Go to [gopherhole.ai](https://gopherhole.ai)
@@ -54,6 +58,45 @@ a2a_agents action=list
 a2a_agents action=send agentId=@memory message="store: remember this"
 ```
 
+## Migration from 0.4.x
+
+OpenClaw 2026.9.0 ships its own stock `a2a` channel for the A2A v1.0 protocol,
+which claimed the same channel ID as this plugin. Because the two have
+different config schemas, OpenClaw refuses to start:
+
+```
+Gateway aborted: config is invalid.
+channels.a2a: invalid config: must not have additional properties:
+"agentId", "agentName", "apiKey", "bridgeUrl", "requestTimeoutMs"
+```
+
+**Do not run `openclaw doctor --fix` here** — it repairs the config by deleting
+the unrecognised keys, taking your API key with them.
+
+Instead, rename the block in `~/.openclaw/openclaw.json`:
+
+```diff
+ "channels": {
+-  "a2a": {
++  "gopherhole": {
+     "enabled": true,
+     "bridgeUrl": "wss://hub.gopherhole.ai/ws",
+     "apiKey": "gph_your_api_key_here"
+   }
+ }
+```
+
+Then restart:
+
+```bash
+openclaw gateway restart
+```
+
+The old `channels.a2a` path is still read as a fallback (with a deprecation
+warning) and will be removed in a future release. Note the fallback only
+applies when OpenClaw's stock `a2a` plugin is disabled — while it is enabled,
+its schema rejects `channels.a2a` before this plugin ever loads.
+
 ## Links
 
 - [GopherHole Hub](https://gopherhole.ai)

package/SKILL.md

@@ -14,7 +14,7 @@ Add to your Clawdbot config:
 
 ```yaml
 channels:
-  a2a:
+  gopherhole:                  # renamed from `a2a` in v0.5.0
     enabled: true
     agentId: nova              # Our identifier (default: openclaw)
     agentName: Nova            # Display name

package/dist/src/channel.js

@@ -40,7 +40,21 @@ function loadAgentSecrets(agentId) {
     }
 }
 function resolveA2AConfig(cfg) {
-    return cfg?.channels?.a2a ?? {};
+    const channels = cfg?.channels;
+    const current = channels?.gopherhole;
+    if (current)
+        return current;
+    // Back-compat: this channel was `a2a` before v0.5.0. OpenClaw now ships its
+    // own stock `a2a` channel, so we moved to `gopherhole` to end the clash.
+    // Legacy config is still honoured, but only when the stock plugin is
+    // disabled -- otherwise its schema rejects channels.a2a before we load.
+    const legacy = channels?.a2a;
+    if (legacy) {
+        a2aLog.error('config_legacy_path', 'channels.a2a is deprecated -- rename it to channels.gopherhole. ' +
+            'Support for the old path will be removed in a future release.', {});
+        return legacy;
+    }
+    return {};
 }
 function resolveA2AAccount(opts) {
     const config = resolveA2AConfig(opts.cfg);
@@ -56,19 +70,19 @@ function resolveA2AAccount(opts) {
     };
 }
 const meta = {
-    id: 'a2a',
-    label: 'A2A',
-    selectionLabel: 'A2A (Agent-to-Agent)',
-    detailLabel: 'A2A Protocol',
-    docsPath: '/channels/a2a',
-    docsLabel: 'a2a',
+    id: 'gopherhole',
+    label: 'GopherHole',
+    selectionLabel: 'GopherHole (Agent-to-Agent)',
+    detailLabel: 'GopherHole A2A',
+    docsPath: '/channels/gopherhole',
+    docsLabel: 'gopherhole',
     blurb: 'Communicate with other AI agents via GopherHole A2A protocol.',
     systemImage: 'bubble.left.and.bubble.right',
-    aliases: ['agent2agent', 'gopherhole'],
+    aliases: ['agent2agent'],
     order: 200,
 };
 export const a2aPlugin = {
-    id: 'a2a',
+    id: 'gopherhole',
     meta,
     capabilities: {
         chatTypes: ['direct'],
@@ -78,7 +92,7 @@ export const a2aPlugin = {
         unsend: false,
         reply: false,
     },
-    reload: { configPrefixes: ['channels.a2a'] },
+    reload: { configPrefixes: ['channels.gopherhole'] },
     config: {
         listAccountIds: () => [DEFAULT_ACCOUNT_ID],
         resolveAccount: (cfg, accountId) => resolveA2AAccount({ cfg: cfg, accountId }),
@@ -89,8 +103,8 @@ export const a2aPlugin = {
                 ...next,
                 channels: {
                     ...next.channels,
-                    a2a: {
-                        ...next.channels?.a2a,
+                    gopherhole: {
+                        ...next.channels?.gopherhole,
                         enabled,
                     },
                 },
@@ -111,8 +125,8 @@ export const a2aPlugin = {
         resolveDmPolicy: ({ account }) => ({
             policy: 'open', // A2A connections are pre-configured, no pairing needed
             allowFrom: [],
-            policyPath: 'channels.a2a.dmPolicy',
-            allowFromPath: 'channels.a2a.',
+            policyPath: 'channels.gopherhole.dmPolicy',
+            allowFromPath: 'channels.gopherhole.',
             approveHint: '',
             normalizeEntry: (raw) => raw,
         }),
@@ -141,8 +155,8 @@ export const a2aPlugin = {
                 ...next,
                 channels: {
                     ...next.channels,
-                    a2a: {
-                        ...next.channels?.a2a,
+                    gopherhole: {
+                        ...next.channels?.gopherhole,
                         enabled: true,
                         ...(input.httpUrl ? { bridgeUrl: input.httpUrl } : {}),
                     },
@@ -165,13 +179,13 @@ export const a2aPlugin = {
         },
         sendText: async ({ to, text }) => {
             if (!connectionManager) {
-                return { channel: 'a2a', success: false, error: 'A2A not connected' };
+                return { channel: 'gopherhole', success: false, error: 'A2A not connected' };
             }
             try {
                 const secrets = loadAgentSecrets(to) ?? undefined;
                 const response = await connectionManager.sendMessage(to, text, secrets ? { secrets } : undefined);
                 return {
-                    channel: 'a2a',
+                    channel: 'gopherhole',
                     success: true,
                     messageId: response.status,
                     response: response.text,
@@ -179,7 +193,7 @@ export const a2aPlugin = {
             }
             catch (err) {
                 return {
-                    channel: 'a2a',
+                    channel: 'gopherhole',
                     success: false,
                     error: err.message,
                 };
@@ -225,7 +239,7 @@ export const a2aPlugin = {
         startAccount: async (ctx) => {
             const account = ctx.account;
             const config = account.config;
-            ctx.log?.info(`[a2a] Starting A2A channel`);
+            ctx.log?.info(`[gopherhole] Starting A2A channel`);
             ctx.setStatus({ accountId: account.accountId });
             const localConnection = new A2AConnectionManager(config);
             // Defensive: prior plugin versions leaked a connection on every
@@ -257,7 +271,7 @@ export const a2aPlugin = {
                     try {
                         // Use chat.send to route the message through the agent
                         // Session key format: agent:<agentId>:<channel>:<chatId>
-                        const sessionKey = `agent:main:a2a:${message.from}`;
+                        const sessionKey = `agent:main:gopherhole:${message.from}`;
                         a2aLog.messageProcessing(message.taskId, sessionKey);
                         // Add A2A context so the agent knows to relay its full response
                         const a2aContext = `[A2A Request from agent "${message.from}"]\n\n${text}\n\n[Note: Your complete response will be sent back to the requesting agent. Include all relevant information in your reply.]`;
@@ -305,7 +319,7 @@ export const a2aPlugin = {
                 running: true,
                 lastStartAt: Date.now(),
             });
-            ctx.log?.info(`[a2a] A2A channel started`);
+            ctx.log?.info(`[gopherhole] A2A channel started`);
             // OpenClaw's channel supervisor treats resolution of this promise as
             // "channel exited" and immediately schedules an auto-restart. Hold the
             // channel open for its lifetime by blocking on the abort signal — the
@@ -323,12 +337,12 @@ export const a2aPlugin = {
                 });
             }
             finally {
-                ctx.log?.info(`[a2a] Stopping A2A channel`);
+                ctx.log?.info(`[gopherhole] Stopping A2A channel`);
                 try {
                     await localConnection.stop();
                 }
                 catch (err) {
-                    ctx.log?.error?.(`[a2a] Error during stop: ${err.message}`);
+                    ctx.log?.error?.(`[gopherhole] Error during stop: ${err.message}`);
                 }
                 if (connectionManager === localConnection) {
                     connectionManager = null;

package/dist/src/types.d.ts

@@ -45,7 +45,7 @@ export interface A2AResponse {
  * Example:
  * {
  *   "channels": {
- *     "a2a": {
+ *     "gopherhole": {
  *       "enabled": true,
  *       "bridgeUrl": "wss://hub.gopherhole.ai/ws",
  *       "apiKey": "gph_your_api_key"

package/openclaw.plugin.json

@@ -1,6 +1,9 @@
 {
   "id": "gopherhole_openclaw_a2a",
-  "channels": ["a2a"],
+  "channels": ["gopherhole"],
+  "contracts": {
+    "tools": ["a2a_agents", "a2a_discover_nearby"]
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -12,8 +15,8 @@
     }
   },
   "channelConfigs": {
-    "a2a": {
-      "label": "A2A (GopherHole)",
+    "gopherhole": {
+      "label": "GopherHole",
       "description": "Agent-to-agent communication over the GopherHole hub. Lets other AI agents discover and message this OpenClaw instance.",
       "schema": {
         "type": "object",
@@ -22,7 +25,7 @@
           "enabled": {
             "type": "boolean",
             "default": false,
-            "description": "Enable the A2A channel"
+            "description": "Enable the GopherHole channel"
           },
           "apiKey": {
             "type": "string",
@@ -84,7 +87,7 @@
       },
       "uiHints": {
         "": {
-          "label": "A2A (GopherHole)",
+          "label": "GopherHole",
           "help": "Connect this OpenClaw instance to the GopherHole hub so other AI agents can discover and message it. Get an API key at https://gopherhole.ai."
         },
         "apiKey": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gopherhole_openclaw_a2a",
-  "version": "0.4.8",
+  "version": "0.5.0",
   "description": "GopherHole A2A plugin for OpenClaw - connect your AI agent to the GopherHole network",
   "type": "module",
   "main": "dist/index.js",