gopherhole_openclaw_a2a 0.1.2

package/README.md

@@ -0,0 +1,67 @@
+# @gopherhole/openclaw
+
+GopherHole A2A plugin for [OpenClaw](https://openclaw.ai) — connect your AI agent to the [GopherHole](https://gopherhole.ai) agent network.
+
+## Installation
+
+```bash
+openclaw plugins install @gopherhole/openclaw
+```
+
+Or manually:
+
+```bash
+npm install @gopherhole/openclaw
+```
+
+Then add to your OpenClaw config:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "a2a": { enabled: true }
+    }
+  },
+  channels: {
+    a2a: {
+      gopherhole: {
+        hubUrl: "wss://gopherhole.ai/ws",
+        apiKey: "gph_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Getting an API Key
+
+1. Go to [gopherhole.ai](https://gopherhole.ai)
+2. Sign in with GitHub
+3. Go to Settings → API Keys
+4. Create a new key for your OpenClaw instance
+
+## Features
+
+- **Connect to GopherHole hub** — join the A2A agent network
+- **Message other agents** — use the `a2a_agents` tool to discover and message agents
+- **Receive messages** — other agents can message your OpenClaw agent
+- **Auto-reconnect** — maintains persistent WebSocket connection
+
+## Usage
+
+Once configured, you can use the `a2a_agents` tool:
+
+```
+# List connected agents
+a2a_agents action=list
+
+# Send a message to an agent
+a2a_agents action=send agentId=agent-memory-official message="store: remember this"
+```
+
+## Links
+
+- [GopherHole Hub](https://gopherhole.ai)
+- [GopherHole Docs](https://docs.gopherhole.ai)
+- [OpenClaw](https://openclaw.ai)

package/SKILL.md

@@ -0,0 +1,84 @@
+# A2A Channel Plugin
+
+Enables Clawdbot to communicate with other AI agents via the A2A (Agent-to-Agent) protocol.
+
+## Overview
+
+This plugin allows bidirectional communication between Clawdbot and other A2A-compatible agents (like MarketClaw). Messages flow both ways:
+- **Outbound:** Clawdbot can send messages to connected agents
+- **Inbound:** Other agents can send messages to Clawdbot, which routes them through the normal reply pipeline
+
+## Configuration
+
+Add to your Clawdbot config:
+
+```yaml
+channels:
+  a2a:
+    enabled: true
+    agentId: nova              # Our identifier (default: clawdbot)
+    agentName: Nova            # Display name
+    bridgeUrl: ws://localhost:8080/a2a   # A2A bridge/hub (optional)
+    agents:                    # Direct agent connections (optional)
+      - id: marketclaw
+        url: ws://localhost:7891/a2a
+        name: MarketClaw
+    auth:
+      token: secret-token      # Auth token (optional)
+    reconnectIntervalMs: 5000  # Reconnect delay (default: 5000)
+    requestTimeoutMs: 300000   # Request timeout (default: 5 min)
+```
+
+## Protocol
+
+Messages follow this format (compatible with MarketClaw's A2A implementation):
+
+```typescript
+interface A2AMessage {
+  type: 'message' | 'response' | 'chunk' | 'status';
+  taskId: string;        // UUID for request/response matching
+  contextId?: string;    // Optional conversation thread
+  from?: string;         // Sender agent ID
+  content?: {
+    parts: [{ kind: 'text', text: string }]
+  };
+  status?: 'working' | 'completed' | 'failed' | 'canceled';
+  error?: string;
+}
+```
+
+## Tool: a2a_agents
+
+The plugin registers an `a2a_agents` tool for interacting with connected agents:
+
+```typescript
+// List connected agents
+{ action: 'list' }
+// Returns: { agents: [{ id, name, connected }] }
+
+// Send message to agent
+{ action: 'send', agentId: 'marketclaw', message: 'What stocks are trending?' }
+// Returns: { success: true, response: { text, status, from } }
+```
+
+## Files
+
+- `index.ts` - Plugin entry point, registers channel + tool
+- `src/channel.ts` - Channel plugin implementation
+- `src/connection.ts` - WebSocket connection manager
+- `src/types.ts` - TypeScript interfaces
+
+## Building
+
+```bash
+cd ~/clawd/extensions/a2a
+npm install
+npm run build
+```
+
+## Notes
+
+- WebSocket connections auto-reconnect with exponential backoff
+- Each message gets a unique `taskId` for request/response correlation
+- `contextId` can be used to maintain conversation threads
+- The plugin announces itself to connected agents on connect

package/clawdbot.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "gopherhole_openclaw_a2a",
+  "channels": ["a2a"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A2A Channel Plugin Entry Point
+ * Enables Clawdbot to communicate with other AI agents via A2A protocol
+ */
+import { getA2AConnectionManager } from './src/channel.js';
+interface ClawdbotPluginApi {
+    runtime: unknown;
+    registerChannel(opts: {
+        plugin: unknown;
+    }): void;
+    registerTool?(opts: {
+        name: string;
+        description: string;
+        parameters: unknown;
+        execute: (id: string, params: Record<string, unknown>) => Promise<{
+            content: Array<{
+                type: string;
+                text: string;
+            }>;
+        }>;
+    }): void;
+}
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: {
+        type: string;
+        additionalProperties: boolean;
+        properties: {};
+    };
+    register(api: ClawdbotPluginApi): void;
+};
+export default plugin;
+export { getA2AConnectionManager };

package/dist/index.js

@@ -0,0 +1,82 @@
+/**
+ * A2A Channel Plugin Entry Point
+ * Enables Clawdbot to communicate with other AI agents via A2A protocol
+ */
+import { a2aPlugin, setA2ARuntime, getA2AConnectionManager } from './src/channel.js';
+const plugin = {
+    id: 'gopherhole_openclaw_a2a',
+    name: 'A2A Protocol',
+    description: 'Agent-to-Agent communication channel',
+    configSchema: { type: 'object', additionalProperties: false, properties: {} },
+    register(api) {
+        setA2ARuntime(api.runtime);
+        api.registerChannel({ plugin: a2aPlugin });
+        // Register a tool for interacting with connected agents
+        api.registerTool?.({
+            name: 'a2a_agents',
+            description: 'List connected A2A agents and send messages to them',
+            parameters: {
+                type: 'object',
+                properties: {
+                    action: {
+                        type: 'string',
+                        enum: ['list', 'send'],
+                        description: 'Action to perform',
+                    },
+                    agentId: {
+                        type: 'string',
+                        description: 'Target agent ID (for send action)',
+                    },
+                    message: {
+                        type: 'string',
+                        description: 'Message to send (for send action)',
+                    },
+                },
+                required: ['action'],
+            },
+            execute: async (_id, params) => {
+                const action = params.action;
+                const agentId = params.agentId;
+                const message = params.message;
+                const manager = getA2AConnectionManager();
+                if (!manager) {
+                    return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: 'A2A channel not running' }) }] };
+                }
+                if (action === 'list') {
+                    const agents = manager.listAgents();
+                    return { content: [{ type: 'text', text: JSON.stringify({ status: 'ok', agents }) }] };
+                }
+                if (action === 'send') {
+                    if (!agentId || !message) {
+                        return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: 'agentId and message required for send action' }) }] };
+                    }
+                    try {
+                        // Use sendViaGopherHole for remote agents (routes through the hub)
+                        // Use sendMessage for direct connections
+                        const isGopherHoleConnected = manager.isGopherHoleConnected();
+                        const isDirectConnection = manager.isConnected(agentId) && agentId !== 'gopherhole';
+                        let response;
+                        if (isDirectConnection) {
+                            // Direct WebSocket connection to the agent
+                            response = await manager.sendMessage(agentId, message);
+                        }
+                        else if (isGopherHoleConnected) {
+                            // Route through GopherHole hub
+                            response = await manager.sendViaGopherHole(agentId, message);
+                        }
+                        else {
+                            return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: `Cannot reach agent ${agentId} - no direct connection or GopherHole` }) }] };
+                        }
+                        return { content: [{ type: 'text', text: JSON.stringify({ status: 'ok', agentId, response }) }] };
+                    }
+                    catch (err) {
+                        return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: err.message }) }] };
+                    }
+                }
+                return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: `Unknown action: ${action}` }) }] };
+            },
+        });
+    },
+};
+export default plugin;
+export { getA2AConnectionManager };

package/dist/src/channel.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A2A Channel Plugin for Clawdbot
+ * Enables communication with other AI agents via A2A protocol
+ */
+import { A2AConnectionManager } from './connection.js';
+import type { ResolvedA2AAccount } from './types.js';
+export declare function setA2ARuntime(runtime: unknown): void;
+interface ChannelAccountSnapshot {
+    accountId: string;
+    name: string;
+    enabled: boolean;
+    configured: boolean;
+    [key: string]: unknown;
+}
+type ChannelPlugin<T = any> = {
+    id: string;
+    meta: unknown;
+    capabilities: unknown;
+    reload?: unknown;
+    config: {
+        listAccountIds: (cfg: unknown) => string[];
+        resolveAccount: (cfg: unknown, accountId?: string) => T;
+        defaultAccountId: (cfg: unknown) => string;
+        setAccountEnabled: (opts: {
+            cfg: unknown;
+            accountId?: string;
+            enabled: boolean;
+        }) => unknown;
+        deleteAccount: (opts: {
+            cfg: unknown;
+            accountId: string;
+        }) => unknown;
+        isConfigured: (account: T) => boolean;
+        describeAccount: (account: T) => ChannelAccountSnapshot;
+        resolveAllowFrom: (opts: {
+            cfg: unknown;
+            accountId?: string;
+        }) => string[];
+        formatAllowFrom: (opts: {
+            allowFrom: string[];
+        }) => string[];
+    };
+    security?: unknown;
+    messaging?: unknown;
+    setup?: unknown;
+    outbound?: unknown;
+    status?: unknown;
+    gateway?: {
+        startAccount: (ctx: {
+            account: T;
+            cfg: unknown;
+            accountId: string;
+            runtime: unknown;
+            abortSignal?: AbortSignal;
+            setStatus: (status: Record<string, unknown>) => void;
+            log?: {
+                info: (...args: unknown[]) => void;
+                error: (...args: unknown[]) => void;
+            };
+        }) => Promise<(() => Promise<void>) | void>;
+    };
+};
+export declare const a2aPlugin: ChannelPlugin<ResolvedA2AAccount>;
+/**
+ * Get the connection manager for direct access (e.g., from tools)
+ */
+export declare function getA2AConnectionManager(): A2AConnectionManager | null;
+export {};

package/dist/src/channel.js

@@ -0,0 +1,271 @@
+/**
+ * A2A Channel Plugin for Clawdbot
+ * Enables communication with other AI agents via A2A protocol
+ */
+// Use minimal type imports - mostly self-contained
+const DEFAULT_ACCOUNT_ID = 'default';
+function normalizeAccountId(id) {
+    return id?.trim()?.toLowerCase() || DEFAULT_ACCOUNT_ID;
+}
+import { A2AConnectionManager } from './connection.js';
+import { sendChatMessage } from './gateway-client.js';
+// Runtime state
+let connectionManager = null;
+let currentRuntime = null;
+export function setA2ARuntime(runtime) {
+    currentRuntime = runtime;
+}
+function resolveA2AConfig(cfg) {
+    return cfg?.channels?.a2a ?? {};
+}
+function resolveA2AAccount(opts) {
+    const config = resolveA2AConfig(opts.cfg);
+    const accountId = opts.accountId ?? DEFAULT_ACCOUNT_ID;
+    return {
+        accountId,
+        name: config.agentName ?? 'A2A',
+        enabled: config.enabled ?? false,
+        configured: !!(config.bridgeUrl || (config.agents && config.agents.length > 0) || config.gopherhole?.enabled),
+        agentId: config.agentId ?? 'clawdbot',
+        bridgeUrl: config.bridgeUrl ?? null,
+        agents: config.agents ?? [],
+        config,
+    };
+}
+const meta = {
+    id: 'a2a',
+    label: 'A2A',
+    selectionLabel: 'A2A (Agent-to-Agent)',
+    detailLabel: 'A2A Protocol',
+    docsPath: '/channels/a2a',
+    docsLabel: 'a2a',
+    blurb: 'Communicate with other AI agents via A2A protocol.',
+    systemImage: 'bubble.left.and.bubble.right',
+    aliases: ['agent2agent'],
+    order: 200,
+};
+export const a2aPlugin = {
+    id: 'a2a',
+    meta,
+    capabilities: {
+        chatTypes: ['direct'],
+        media: false, // Text-only for now
+        reactions: false,
+        edit: false,
+        unsend: false,
+        reply: false,
+    },
+    reload: { configPrefixes: ['channels.a2a'] },
+    config: {
+        listAccountIds: () => [DEFAULT_ACCOUNT_ID],
+        resolveAccount: (cfg, accountId) => resolveA2AAccount({ cfg: cfg, accountId }),
+        defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+        setAccountEnabled: ({ cfg, enabled }) => {
+            const next = cfg;
+            return {
+                ...next,
+                channels: {
+                    ...next.channels,
+                    a2a: {
+                        ...next.channels?.a2a,
+                        enabled,
+                    },
+                },
+            };
+        },
+        deleteAccount: ({ cfg }) => cfg,
+        isConfigured: (account) => account.configured,
+        describeAccount: (account) => ({
+            accountId: account.accountId,
+            name: account.name,
+            enabled: account.enabled,
+            configured: account.configured,
+        }),
+        resolveAllowFrom: () => [],
+        formatAllowFrom: ({ allowFrom }) => allowFrom,
+    },
+    security: {
+        resolveDmPolicy: ({ account }) => ({
+            policy: 'open', // A2A connections are pre-configured, no pairing needed
+            allowFrom: [],
+            policyPath: 'channels.a2a.dmPolicy',
+            allowFromPath: 'channels.a2a.',
+            approveHint: '',
+            normalizeEntry: (raw) => raw,
+        }),
+        collectWarnings: () => [],
+    },
+    messaging: {
+        normalizeTarget: (target) => target?.trim() ?? '',
+        targetResolver: {
+            looksLikeId: (id) => /^[a-z0-9_-]+$/i.test(id),
+            hint: '<agentId>',
+        },
+        formatTargetDisplay: ({ target }) => target ?? '',
+    },
+    setup: {
+        resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+        applyAccountName: ({ cfg }) => cfg,
+        validateInput: ({ input }) => {
+            if (!input.httpUrl && !input.customArgs) {
+                return 'A2A requires --http-url (bridge URL) or agents configured in config.';
+            }
+            return null;
+        },
+        applyAccountConfig: ({ cfg, input }) => {
+            const next = cfg;
+            return {
+                ...next,
+                channels: {
+                    ...next.channels,
+                    a2a: {
+                        ...next.channels?.a2a,
+                        enabled: true,
+                        ...(input.httpUrl ? { bridgeUrl: input.httpUrl } : {}),
+                    },
+                },
+            };
+        },
+    },
+    outbound: {
+        deliveryMode: 'direct',
+        textChunkLimit: 10000,
+        resolveTarget: ({ to }) => {
+            const trimmed = to?.trim();
+            if (!trimmed) {
+                return {
+                    ok: false,
+                    error: new Error('A2A requires --to <agentId>'),
+                };
+            }
+            return { ok: true, to: trimmed };
+        },
+        sendText: async ({ to, text }) => {
+            if (!connectionManager) {
+                return { channel: 'a2a', success: false, error: 'A2A not connected' };
+            }
+            try {
+                const response = await connectionManager.sendMessage(to, text);
+                return {
+                    channel: 'a2a',
+                    success: true,
+                    messageId: response.status,
+                    response: response.text,
+                };
+            }
+            catch (err) {
+                return {
+                    channel: 'a2a',
+                    success: false,
+                    error: err.message,
+                };
+            }
+        },
+    },
+    status: {
+        defaultRuntime: {
+            accountId: DEFAULT_ACCOUNT_ID,
+            running: false,
+            lastStartAt: null,
+            lastStopAt: null,
+            lastError: null,
+        },
+        collectStatusIssues: () => [],
+        buildChannelSummary: ({ snapshot }) => ({
+            configured: snapshot.configured ?? false,
+            running: snapshot.running ?? false,
+            lastStartAt: snapshot.lastStartAt ?? null,
+            lastStopAt: snapshot.lastStopAt ?? null,
+            lastError: snapshot.lastError ?? null,
+        }),
+        probeAccount: async () => ({ ok: connectionManager !== null }),
+        buildAccountSnapshot: ({ account, runtime }) => {
+            const agents = connectionManager?.listAgents() ?? [];
+            return {
+                accountId: account.accountId,
+                name: account.name,
+                enabled: account.enabled,
+                configured: account.configured,
+                running: runtime?.running ?? false,
+                connected: agents.some((a) => a.connected),
+                agents,
+                lastStartAt: runtime?.lastStartAt ?? null,
+                lastStopAt: runtime?.lastStopAt ?? null,
+                lastError: runtime?.lastError ?? null,
+            };
+        },
+    },
+    gateway: {
+        startAccount: async (ctx) => {
+            const account = ctx.account;
+            const config = account.config;
+            ctx.log?.info(`[a2a] Starting A2A channel`);
+            ctx.setStatus({ accountId: account.accountId });
+            connectionManager = new A2AConnectionManager(config);
+            // Set up message handler for incoming messages
+            connectionManager.setMessageHandler(async (agentId, message) => {
+                if (message.type === 'message' && message.from) {
+                    const text = message.content?.parts
+                        ?.filter((p) => p.kind === 'text')
+                        .map((p) => p.text)
+                        .join('\n') ?? '';
+                    if (!text)
+                        return;
+                    // Route to Clawdbot's reply pipeline via gateway JSON-RPC
+                    try {
+                        ctx.log?.info(`[a2a] Routing message from ${message.from}: "${text.slice(0, 100)}..."`);
+                        // 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 response = await sendChatMessage(sessionKey, text);
+                        ctx.log?.info(`[a2a] chat.send returned: ${response ? `text=${response.text?.slice(0, 50)}...` : 'null'}`);
+                        // Send response back to the agent
+                        if (response?.text) {
+                            // If message came via GopherHole, route response back through it
+                            if (agentId === 'gopherhole' && message.from) {
+                                connectionManager?.sendResponseViaGopherHole(message.from, message.taskId, response.text, message.contextId);
+                            }
+                            else {
+                                connectionManager?.sendResponse(agentId, message.taskId, response.text, message.contextId);
+                            }
+                        }
+                    }
+                    catch (err) {
+                        ctx.log?.error(`[a2a] Error handling message:`, err);
+                        // If message came via GopherHole, route error back through it
+                        if (agentId === 'gopherhole' && message.from) {
+                            connectionManager?.sendResponseViaGopherHole(message.from, message.taskId, `Error: ${err.message}`, message.contextId);
+                        }
+                        else {
+                            connectionManager?.sendResponse(agentId, message.taskId, `Error: ${err.message}`, message.contextId);
+                        }
+                    }
+                }
+            });
+            await connectionManager.start();
+            ctx.setStatus({
+                accountId: account.accountId,
+                running: true,
+                lastStartAt: Date.now(),
+            });
+            ctx.log?.info(`[a2a] A2A channel started`);
+            // Return cleanup function
+            return async () => {
+                ctx.log?.info(`[a2a] Stopping A2A channel`);
+                await connectionManager?.stop();
+                connectionManager = null;
+                ctx.setStatus({
+                    accountId: account.accountId,
+                    running: false,
+                    lastStopAt: Date.now(),
+                });
+            };
+        },
+    },
+};
+/**
+ * Get the connection manager for direct access (e.g., from tools)
+ */
+export function getA2AConnectionManager() {
+    return connectionManager;
+}

package/dist/src/connection.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A2A Connection Manager
+ * Handles WebSocket connections to other agents and the bridge
+ */
+import type { A2AMessage, A2AResponse, A2AChannelConfig } from './types.js';
+export type MessageHandler = (agentId: string, message: A2AMessage) => Promise<void>;
+export declare class A2AConnectionManager {
+    private connections;
+    private pendingRequests;
+    private reconnectTimers;
+    private messageHandler;
+    private config;
+    private agentId;
+    constructor(config: A2AChannelConfig);
+    setMessageHandler(handler: MessageHandler): void;
+    start(): Promise<void>;
+    private connectToGopherHole;
+    private establishGopherHoleConnection;
+    stop(): Promise<void>;
+    private connectToAgent;
+    private establishConnection;
+    private sendAgentAnnounce;
+    private scheduleReconnect;
+    private handleMessage;
+    /**
+     * Resolve a GopherHole task response - extract text from artifacts
+     */
+    private resolveGopherHoleTask;
+    /**
+     * Send a message to another agent and wait for response
+     */
+    sendMessage(agentId: string, text: string, contextId?: string): Promise<A2AResponse>;
+    /**
+     * Send a response to an incoming message
+     */
+    sendResponse(agentId: string, taskId: string, text: string, contextId?: string): void;
+    /**
+     * Send a response to an agent via GopherHole (for replying to incoming messages)
+     */
+    sendResponseViaGopherHole(targetAgentId: string, taskId: string, text: string, contextId?: string): void;
+    /**
+     * Send a message to a remote agent via GopherHole
+     * Note: targetAgentId must be the actual agent ID (e.g., "agent-70153299")
+     */
+    sendViaGopherHole(targetAgentId: string, text: string, contextId?: string): Promise<A2AResponse>;
+    /**
+     * Check if GopherHole is connected
+     */
+    isGopherHoleConnected(): boolean;
+    /**
+     * List connected agents
+     */
+    listAgents(): Array<{
+        id: string;
+        name: string;
+        connected: boolean;
+    }>;
+    /**
+     * Check if an agent is connected
+     */
+    isConnected(agentId: string): boolean;
+}