@clawcrony/claw-crony 1.0.1

package/openclaw.plugin.json

@@ -0,0 +1,272 @@
+{
+  "id": "claw-crony",
+  "name": "Claw Crony",
+  "description": "OpenClaw A2A v0.3.0 gateway with Agent Card, JSON-RPC, REST, routing rules, transport fallback, and Hub matchmaking",
+  "version": "1.0.1",
+  "defaultConfig": {
+    "agentCard": {
+      "name": "OpenClaw A2A Gateway",
+      "description": "A2A bridge for OpenClaw agents",
+      "skills": [{ "id": "chat", "name": "chat", "description": "Chat bridge" }]
+    },
+    "hub": {
+      "url": "https://www.factormining.cn",
+      "enabled": true,
+      "registrationEnabled": true
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "agentCard": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "url": { "type": "string" },
+          "skills": {
+            "type": "array",
+            "items": {
+              "oneOf": [
+                { "type": "string" },
+                {
+                  "type": "object",
+                  "properties": {
+                    "id": { "type": "string" },
+                    "name": { "type": "string" },
+                    "description": { "type": "string" }
+                  },
+                  "required": ["name"]
+                }
+              ]
+            }
+          }
+        }
+      },
+      "hub": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "url": { "type": "string" },
+          "enabled": { "type": "boolean", "default": true },
+          "registrationEnabled": { "type": "boolean", "default": true }
+        }
+      },
+      "registration": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "username": { "type": "string" },
+          "email": { "type": "string" }
+        }
+      },
+      "server": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "host": { "type": "string", "default": "0.0.0.0" },
+          "port": { "type": "number", "default": 18800 }
+        }
+      },
+      "storage": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "tasksDir": { "type": "string", "default": "~/.openclaw/a2a-tasks" },
+          "taskTtlHours": {
+            "type": "number",
+            "default": 72,
+            "minimum": 1,
+            "description": "Hours before completed/failed/canceled tasks are automatically deleted (default 72h)"
+          },
+          "cleanupIntervalMinutes": {
+            "type": "number",
+            "default": 60,
+            "minimum": 1,
+            "description": "Minutes between automatic task cleanup runs (default 60min)"
+          }
+        }
+      },
+      "peers": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "name": { "type": "string" },
+            "agentCardUrl": { "type": "string" },
+            "auth": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "enum": ["bearer", "apiKey"]
+                },
+                "token": { "type": "string" }
+              },
+              "required": ["type", "token"]
+            }
+          },
+          "required": ["name", "agentCardUrl"]
+        }
+      },
+      "security": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "inboundAuth": {
+            "type": "string",
+            "enum": ["none", "bearer"],
+            "default": "none"
+          },
+          "token": { "type": "string" },
+          "tokens": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Multiple tokens for zero-downtime rotation. Used alongside or instead of 'token'."
+          },
+          "allowedMimeTypes": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Allowed MIME type patterns for file transfer (e.g. \"image/*\", \"application/pdf\")"
+          },
+          "maxFileSizeBytes": {
+            "type": "number",
+            "default": 52428800,
+            "minimum": 0,
+            "description": "Max file size in bytes for URI-based files (default 50MB)"
+          },
+          "maxInlineFileSizeBytes": {
+            "type": "number",
+            "default": 10485760,
+            "minimum": 0,
+            "description": "Max file size in bytes for inline base64 files (default 10MB)"
+          },
+          "fileUriAllowlist": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "URI hostname allowlist patterns (e.g. \"*.example.com\"). Empty allows all public hosts."
+          }
+        }
+      },
+      "routing": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "defaultAgentId": {
+            "type": "string",
+            "default": "default"
+          },
+          "rules": {
+            "type": "array",
+            "description": "Rule-based routing: auto-select peer by message text regex, tags, or required skills"
+          }
+        }
+      },
+      "limits": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "maxConcurrentTasks": {
+            "type": "number",
+            "default": 4,
+            "minimum": 1
+          },
+          "maxQueuedTasks": {
+            "type": "number",
+            "default": 100,
+            "minimum": 0
+          }
+        }
+      },
+      "observability": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "structuredLogs": {
+            "type": "boolean",
+            "default": true
+          },
+          "exposeMetricsEndpoint": {
+            "type": "boolean",
+            "default": true
+          },
+          "metricsPath": {
+            "type": "string",
+            "default": "/a2a/metrics"
+          },
+          "metricsAuth": {
+            "type": "string",
+            "enum": ["none", "bearer"],
+            "default": "none",
+            "description": "Authentication for the metrics endpoint. When set to 'bearer', reuses security.token/tokens."
+          },
+          "auditLogPath": {
+            "type": "string",
+            "default": "~/.openclaw/a2a-audit.jsonl",
+            "description": "Path for the JSONL audit log file (separate from structured logs)."
+          }
+        }
+      },
+      "timeouts": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "agentResponseTimeoutMs": {
+            "type": "number",
+            "default": 300000,
+            "minimum": 1000
+          }
+        }
+      },
+      "resilience": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "healthCheck": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "enabled": { "type": "boolean", "default": true },
+              "intervalMs": { "type": "number", "default": 30000, "minimum": 1000 },
+              "timeoutMs": { "type": "number", "default": 5000, "minimum": 500 }
+            }
+          },
+          "retry": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "maxRetries": { "type": "number", "default": 3, "minimum": 0 },
+              "baseDelayMs": { "type": "number", "default": 1000, "minimum": 100 },
+              "maxDelayMs": { "type": "number", "default": 10000, "minimum": 100 }
+            }
+          },
+          "circuitBreaker": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "failureThreshold": { "type": "number", "default": 5, "minimum": 1 },
+              "resetTimeoutMs": { "type": "number", "default": 30000, "minimum": 1000 }
+            }
+          }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "peers": {
+      "items": {
+        "auth": {
+          "token": { "sensitive": true }
+        }
+      }
+    },
+    "security": {
+      "token": { "sensitive": true },
+      "tokens": { "items": { "sensitive": true } }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@clawcrony/claw-crony",
+  "version": "1.0.1",
+  "type": "module",
+  "description": "OpenClaw A2A gateway plugin implementing the A2A v0.3.0 protocol surface",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "skill"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --import tsx --test tests/*.test.ts"
+  },
+  "keywords": [
+    "openclaw",
+    "a2a",
+    "agent-to-agent",
+    "gateway",
+    "plugin"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.0.0",
+    "@types/supertest": "^2.0.16",
+    "@types/uuid": "^10.0.0",
+    "openclaw": "^2026.3.2",
+    "supertest": "^7.1.4",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@a2a-js/sdk": "^0.3.0",
+    "@bufbuild/protobuf": "^2.11.0",
+    "@grpc/grpc-js": "^1.14.3",
+    "express": "^4.21.2",
+    "uuid": "^9.0.1"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: a2a-setup
+description: "Install and configure the OpenClaw A2A Gateway plugin for cross-server agent communication. Use when: (1) setting up A2A between two or more OpenClaw instances, (2) user says 'configure A2A', 'set up A2A gateway', 'connect two OpenClaw servers', 'agent-to-agent communication', (3) adding a new A2A peer to an existing setup. Covers: plugin installation, Agent Card configuration, security tokens, peer registration, network setup (Tailscale/LAN), TOOLS.md template for agent awareness, and end-to-end verification."
+---
+
+# A2A Gateway Setup
+
+Configure the OpenClaw A2A Gateway plugin for cross-server agent-to-agent communication using the A2A v0.3.0 protocol.
+
+## Prerequisites
+
+- OpenClaw ≥ 2026.3.0 installed and running on each server
+- Network connectivity between servers (Tailscale recommended, LAN or public IP also work)
+- Node.js ≥ 22
+
+## Step 1: Install the Plugin
+
+```bash
+mkdir -p <WORKSPACE>/plugins
+cd <WORKSPACE>/plugins
+git clone https://github.com/win4r/openclaw-a2a-gateway.git a2a-gateway
+cd a2a-gateway
+npm install --production
+```
+
+Replace `<WORKSPACE>` with the agent workspace path. Find it with:
+
+```bash
+openclaw config get agents.defaults.workspace
+```
+
+## Step 2: Register Plugin in OpenClaw
+
+Get current allowed plugins first to avoid overwriting:
+
+```bash
+openclaw config get plugins.allow
+```
+
+Then add `a2a-gateway` to the existing array (do NOT drop existing plugin ids):
+
+```bash
+# Example only — include your existing plugins too
+openclaw config set plugins.allow '["<existing...>", "a2a-gateway"]'
+openclaw config set plugins.load.paths '["<ABSOLUTE_PATH>/plugins/a2a-gateway"]'
+openclaw config set plugins.entries.a2a-gateway.enabled true
+```
+
+**Critical:** Use the absolute path in `plugins.load.paths`. Relative paths will fail.
+
+## Step 3: Configure Agent Card
+
+```bash
+openclaw config set plugins.entries.a2a-gateway.config.agentCard.name '<AGENT_NAME>'
+openclaw config set plugins.entries.a2a-gateway.config.agentCard.description '<DESCRIPTION>'
+openclaw config set plugins.entries.a2a-gateway.config.agentCard.url 'http://<REACHABLE_IP>:18800/a2a/jsonrpc'
+openclaw config set plugins.entries.a2a-gateway.config.agentCard.skills '[{"id":"chat","name":"chat","description":"Bridge chat/messages to OpenClaw agents"}]'
+```
+
+### URL field rules
+
+| Field | Points to | Example |
+|-------|-----------|---------|
+| `agentCard.url` | JSON-RPC endpoint (default) | `http://100.x.x.x:18800/a2a/jsonrpc` |
+| `peers[].agentCardUrl` | Agent Card discovery (preferred) | `http://100.x.x.x:18800/.well-known/agent-card.json` |
+
+**Do NOT confuse these two.** `agentCard.url` tells peers where to send messages. `agentCardUrl` tells you where to discover the peer.
+
+Note: this plugin also serves the legacy alias `/.well-known/agent.json`, but the official SDK default is `/.well-known/agent-card.json`.
+
+## Step 4: Configure Server
+
+```bash
+openclaw config set plugins.entries.a2a-gateway.config.server.host '0.0.0.0'
+openclaw config set plugins.entries.a2a-gateway.config.server.port 18800
+```
+
+## Step 5: Configure Security
+
+```bash
+TOKEN=$(openssl rand -hex 24)
+echo "Save this token: $TOKEN"
+
+openclaw config set plugins.entries.a2a-gateway.config.security.inboundAuth 'bearer'
+openclaw config set plugins.entries.a2a-gateway.config.security.token "$TOKEN"
+```
+
+Share this token with peers who need to send you messages.
+
+## Step 6: Configure Routing
+
+```bash
+openclaw config set plugins.entries.a2a-gateway.config.routing.defaultAgentId 'main'
+```
+
+## Step 7: Add Peers
+
+```bash
+openclaw config set plugins.entries.a2a-gateway.config.peers '[
+  {
+    "name": "<PEER_NAME>",
+    "agentCardUrl": "http://<PEER_IP>:18800/.well-known/agent-card.json",
+    "auth": {
+      "type": "bearer",
+      "token": "<PEER_INBOUND_TOKEN>"
+    }
+  }
+]'
+```
+
+For multiple peers, include all in one JSON array.
+
+## Step 8: Restart and Verify
+
+```bash
+openclaw gateway restart
+
+# Verify Agent Card
+curl -s http://localhost:18800/.well-known/agent-card.json | python3 -m json.tool
+
+# Verify peer connectivity
+curl -s http://<PEER_IP>:18800/.well-known/agent-card.json | python3 -m json.tool
+```
+
+## Step 9: Configure TOOLS.md
+
+**This step is critical.** Without it, the agent won't know how to use A2A.
+
+Read `references/tools-md-template.md` and append the A2A section to the agent's `TOOLS.md`, replacing placeholders with actual peer info.
+
+For outbound messaging, use the SDK script (`scripts/a2a-send.mjs`).
+
+To use the SDK script, ensure `@a2a-js/sdk` is installed in the plugin directory:
+
+```bash
+cd <WORKSPACE>/plugins/a2a-gateway && npm ls @a2a-js/sdk
+```
+
+## Step 10: End-to-End Test
+
+```bash
+node <WORKSPACE>/plugins/a2a-gateway/skill/scripts/a2a-send.mjs \
+  --peer-url http://<PEER_IP>:18800 \
+  --token <PEER_TOKEN> \
+  --message "Hello, what is your name?"
+```
+
+The script uses `@a2a-js/sdk` ClientFactory to auto-discover the Agent Card, handle authentication, and print the peer agent's response.
+
+### Async task mode (recommended for long-running prompts)
+
+For prompts that may take longer than a typical request timeout (e.g., multi-round discussions, long summaries), use non-blocking mode + polling:
+
+```bash
+node <WORKSPACE>/plugins/a2a-gateway/skill/scripts/a2a-send.mjs \
+  --peer-url http://<PEER_IP>:18800 \
+  --token <PEER_TOKEN> \
+  --non-blocking \
+  --wait \
+  --timeout-ms 600000 \
+  --poll-ms 1000 \
+  --message "Discuss A2A advantages in 3 rounds and provide final conclusion"
+```
+
+This sends `configuration.blocking=false` and then polls `tasks/get` until the task reaches a terminal state.
+
+### Server-side timeout configuration (OpenClaw dispatch)
+
+If you still see `Request accepted (no agent dispatch available)`, the underlying OpenClaw agent run may be timing out. Increase:
+
+- `plugins.entries.a2a-gateway.config.timeouts.agentResponseTimeoutMs` (default: 300000)
+
+### Optional: Route to a specific OpenClaw agentId (OpenClaw extension)
+
+By default, the peer will route inbound A2A messages to `routing.defaultAgentId`.
+
+To route a single request to a specific agentId (e.g., `coder`) on the peer, pass `--agent-id`:
+
+```bash
+node <WORKSPACE>/plugins/a2a-gateway/skill/scripts/a2a-send.mjs \
+  --peer-url http://<PEER_IP>:18800 \
+  --token <PEER_TOKEN> \
+  --agent-id coder \
+  --message "Run tests and summarize failures"
+```
+
+Note: this uses a non-standard `message.agentId` field understood by the OpenClaw A2A Gateway plugin. It is most reliable over JSON-RPC/REST. gRPC transport may drop unknown Message fields.
+
+## Network: Tailscale Setup (if needed)
+
+When servers are on different networks, use Tailscale:
+
+```bash
+curl -fsSL https://tailscale.com/install.sh | sh
+sudo tailscale up
+# Authenticate via the printed URL (use same account on all servers)
+tailscale ip -4  # Get the 100.x.x.x IP
+```
+
+Use Tailscale IPs in all A2A configuration. Verify with:
+
+```bash
+ping <OTHER_SERVER_TAILSCALE_IP>
+```
+
+## Mutual Peering Checklist
+
+For two-way communication, repeat Steps 1-9 on BOTH servers:
+
+- [ ] Server A: plugin installed, Agent Card configured, token generated
+- [ ] Server B: plugin installed, Agent Card configured, token generated
+- [ ] Server A: has Server B in peers (with B's token)
+- [ ] Server B: has Server A in peers (with A's token)
+- [ ] Server A: TOOLS.md updated with Server B peer info
+- [ ] Server B: TOOLS.md updated with Server A peer info
+- [ ] Both: `openclaw gateway restart` done
+- [ ] Both: Agent Cards accessible (`curl /.well-known/agent-card.json`)
+- [ ] Test: A → B message/send works
+- [ ] Test: B → A message/send works
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| "no agent dispatch available" | (1) No AI provider configured, or (2) OpenClaw agent dispatch timed out | Check `openclaw config get auth.profiles`; for long prompts use async mode (`--non-blocking --wait`) or increase `config.timeouts.agentResponseTimeoutMs` |
+| "plugin not found: a2a-gateway" | Load path missing or wrong | Verify `plugins.load.paths` uses absolute path |
+| Agent Card 404 | Plugin not loaded | Check `plugins.allow` includes `a2a-gateway` |
+| Port 18800 connection refused | Gateway not restarted | Run `openclaw gateway restart` |
+| Peer auth fails | Token mismatch | Verify peer config token matches target's `security.token` |
+| Agent doesn't know about A2A | TOOLS.md not configured | Add A2A section from the template (Step 9) |

package/skill/references/tools-md-template.md

@@ -0,0 +1,57 @@
+# TOOLS.md A2A Section Template
+
+Append this section to the agent's `TOOLS.md` file, replacing all `<PLACEHOLDERS>` with actual values.
+
+---
+
+```markdown
+## A2A Gateway (Agent-to-Agent Communication)
+
+You have an A2A Gateway plugin running on port 18800. You can communicate with peer agents on other servers.
+
+### Peers
+
+| Peer | IP | Auth Token |
+|------|-----|------------|
+| <PEER_NAME> | <PEER_IP> | <PEER_TOKEN> |
+
+### How to send a message to a peer
+
+When the user says "通过 A2A 让 <PEER_NAME> 做 xxx" / "Send to <PEER_NAME>: xxx" / "Ask <PEER_NAME> to ..." or similar, use the exec tool to run:
+
+```bash
+node <WORKSPACE>/plugins/a2a-gateway/skill/scripts/a2a-send.mjs \
+  --peer-url http://<PEER_IP>:18800 \
+  --token <PEER_TOKEN> \
+  --message "YOUR MESSAGE HERE"
+
+# Optional (OpenClaw extension): route to a specific peer OpenClaw agentId
+#  --agent-id coder
+```
+
+The script uses `@a2a-js/sdk` ClientFactory to:
+- Auto-discover the peer's Agent Card
+- Handle bearer token authentication
+- Select the best transport (JSON-RPC by default; REST or GRPC if preferred/available)
+- Print the peer agent's response text directly
+
+### Notes
+
+- For long-running prompts (multi-round discussions, long summaries), use async task mode:
+  - add: `--non-blocking --wait --timeout-ms 600000 --poll-ms 1000`
+- If the peer returns an error, check the token and network connectivity
+- The script handles messageId generation and response parsing automatically
+```
+
+---
+
+## Placeholder Reference
+
+| Placeholder | Description | Example |
+|-------------|-------------|---------|
+| `<PEER_NAME>` | Display name of the peer agent | `Server-A` |
+| `<PEER_IP>` | IP address reachable from this server | `100.76.43.74` |
+| `<PEER_TOKEN>` | The peer's inbound security token | `9489c2c7ce10...` |
+| `<WORKSPACE>` | Agent workspace absolute path | `/home/ubuntu/.openclaw/workspace` |
+
+For multiple peers, add one row per peer to the table.