gopherhole_openclaw_a2a 0.4.7 → 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,11 +271,24 @@ 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.]`;
-                        const response = await sendChatMessage(sessionKey, a2aContext);
+                        // A2A status updates are task-level keepalives. Publish one now and
+                        // periodically while OpenClaw is working so callers do not mistake
+                        // a long tool run for a dead connection.
+                        connectionManager?.sendTaskStatusViaGopherHole(message.taskId, 'OpenClaw is working');
+                        const keepalive = setInterval(() => {
+                            connectionManager?.sendTaskStatusViaGopherHole(message.taskId, 'OpenClaw is still working');
+                        }, 30_000);
+                        let response;
+                        try {
+                            response = await sendChatMessage(sessionKey, a2aContext);
+                        }
+                        finally {
+                            clearInterval(keepalive);
+                        }
                         // Log captured response
                         if (response?.text) {
                             a2aLog.responseCaptured(message.taskId, response.text);
@@ -292,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
@@ -310,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/connection.d.ts

@@ -44,6 +44,7 @@ export declare class A2AConnectionManager {
      * Uses SDK's respond() method to complete the original task
      */
     sendResponseViaGopherHole(_targetAgentId: string, taskId: string, text: string, _contextId?: string): void;
+    sendTaskStatusViaGopherHole(taskId: string, message?: string): void;
     /**
      * Legacy alias for sendPartsViaGopherHole with text-only
      */

package/dist/src/connection.js

@@ -271,6 +271,17 @@ export class A2AConnectionManager {
             console.error('[a2a] Error details:', err);
         }
     }
+    sendTaskStatusViaGopherHole(taskId, message) {
+        if (!this.gopherhole || !this.connected || !taskId || taskId.startsWith('gph-')) {
+            return;
+        }
+        try {
+            this.gopherhole.updateTaskStatus(taskId, 'working', message);
+        }
+        catch (err) {
+            console.error('[a2a] Failed to publish task status:', err.message);
+        }
+    }
     /**
      * Legacy alias for sendPartsViaGopherHole with text-only
      */

package/dist/src/gateway-client.d.ts

@@ -7,6 +7,7 @@
  * resolve when we get state: "final".
  */
 export declare const GATEWAY_PROTOCOL_VERSION = 4;
+export declare const CHAT_INACTIVITY_TIMEOUT_MS: number;
 export declare function connectToGateway(port?: number): Promise<void>;
 export declare function callGateway(method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
 /**

package/dist/src/gateway-client.js

@@ -20,6 +20,14 @@ let handshakeComplete = false;
 // protocol bump fails a focused compatibility test instead of silently
 // breaking inbound A2A replies at runtime.
 export const GATEWAY_PROTOCOL_VERSION = 4;
+export const CHAT_INACTIVITY_TIMEOUT_MS = 30 * 60 * 1000;
+function refreshChatTimeout(runId, pending) {
+    clearTimeout(pending.timeout);
+    pending.timeout = setTimeout(() => {
+        pendingChats.delete(runId);
+        pending.reject(new Error('Chat response inactivity timeout'));
+    }, pending.timeoutMs);
+}
 function getGatewayToken() {
     // Try the current OpenClaw config location first, then the legacy
     // Clawdbot path as a fallback for users still on older installs.
@@ -65,7 +73,7 @@ export async function connectToGateway(port = 18789) {
                     client: {
                         id: 'gateway-client',
                         displayName: 'A2A Channel Plugin',
-                        version: '0.4.7',
+                        version: '0.4.8',
                         platform: process.platform,
                         mode: 'backend',
                     },
@@ -174,6 +182,9 @@ function handleChatEvent(payload) {
         // Not a chat we're tracking
         return;
     }
+    // Any chat event proves the OpenClaw run is alive. Treat the timeout as an
+    // inactivity deadline rather than a fixed whole-task deadline.
+    refreshChatTimeout(payload.runId, pending);
     // Detailed logging for debugging relay issues
     console.log(`[a2a] Chat event: runId=${payload.runId}, state=${payload.state}, seq=${payload.seq}, role=${payload.message?.role}`);
     if (payload.state === 'delta' || payload.state === 'final') {
@@ -238,7 +249,7 @@ export async function callGateway(method, params, timeoutMs = 300000) {
  * Send a chat message and wait for the full response.
  * chat.send is non-blocking - returns runId immediately, response streams via events.
  */
-export async function sendChatMessage(sessionKey, message, timeoutMs = 300000) {
+export async function sendChatMessage(sessionKey, message, timeoutMs = CHAT_INACTIVITY_TIMEOUT_MS) {
     if (!ws || !connected || !handshakeComplete) {
         await connectToGateway();
     }
@@ -256,16 +267,15 @@ export async function sendChatMessage(sessionKey, message, timeoutMs = 300000) {
     }
     // Now wait for chat events to complete
     return new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-            pendingChats.delete(result.runId);
-            reject(new Error('Chat response timeout'));
-        }, timeoutMs);
-        pendingChats.set(result.runId, {
+        const pending = {
             resolve,
             reject,
-            timeout,
+            timeout: undefined,
             latestText: '',
-        });
+            timeoutMs,
+        };
+        pendingChats.set(result.runId, pending);
+        refreshChatTimeout(result.runId, pending);
     });
 }
 export function disconnectFromGateway() {

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.7",
+  "version": "0.5.0",
   "description": "GopherHole A2A plugin for OpenClaw - connect your AI agent to the GopherHole network",
   "type": "module",
   "main": "dist/index.js",
@@ -35,7 +35,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@gopherhole/sdk": "^0.7.5",
+    "@gopherhole/sdk": "^0.9.1",
     "uuid": "^10.0.0"
   },
   "devDependencies": {