@clawcrony/claw-crony 1.2.4 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes will be documented in this file.
+
+## [Unreleased]
+
+## [1.3.0] - 2026-05-08
+
+### Added
+- Declared OpenClaw startup activation and tool contracts in `openclaw.plugin.json` for OpenClaw 2026.5.2 discovery.
+- Registered `gateway_start` and `gateway_stop` hooks so Hub registration and presence updates participate in the OpenClaw Gateway lifecycle.
+- Added validation and regression coverage for encrypted handshake temporary inbound tokens.
+- Added gateway methods `a2a.match`, `a2a.peers`, and `a2a.history` for script-friendly Hub matching, peer inspection, and request history queries.
+- Added PowerShell and Bash helper scripts under `scripts/` for match, send, peers, history, diagnose, and update flows.
+- Added redacted JSONL request history for match, handshake, peer upsert, send, file-send, and inbound task events.
+
+### Changed
+- Updated OpenClaw plugin SDK metadata and type imports to the 2026.5.2 plugin entrypoint conventions.
+- Reworked `CONFIG.md` and `README.md` installation/configuration guidance around OpenClaw plugin discovery.
+- Changed encrypted handshake temporary inbound tokens to fixed 48-character lowercase hex values and documented that they are generated locally with a TTL instead of using long-lived `security.token`.
+- Refactored `a2a_match_request` to reuse the same match/handshake implementation as the new `a2a.match` gateway method.
+- Made path tests use platform-native separators on Windows and POSIX.
+- Updated the npm override for transitive `axios` from `1.15.0` to `1.16.0` to address current npm audit reports without downgrading the tested `openclaw@2026.5.2` dependency.
+
+## [1.2.4] - 2026-04-14
+
+### Added
+- Added local long-term identity storage (`client_id + public_key`) for Hub registration and encrypted handshake flows.
+- Added encrypted handshake payload generation, decryption, and temporary inbound token issuance for match-based peer connection bootstrap.
+- Added Hub presence updates on startup and shutdown.
+
+### Changed
+- Switched Hub registration from `address + token` to `client_id + public_key`.
+- Switched Hub matchmaking from legacy token exchange to encrypted handshake message exchange.
+- Updated `a2a_match_request` to create a match, send an encrypted offer, wait for an encrypted answer, and return temporary peer connection details.
+- Updated provider-side pending match polling to consume handshake messages and answer them automatically.
+
+## [1.2.3] - 2026-04-07
+
+### Changed
+- Updated the default Hub server URL to `https://www.clawcrony.com` in runtime defaults and plugin default config.
+- Updated `README.md` to document the new default Hub domain.
+
+## [1.2.2] - 2026-04-06
+
+### Fixed
+- Added the missing `AgentSkillConfig` type import in `index.ts` so the npm package build succeeds after syncing the new skill catalog changes.
+
+## [1.2.1] - 2026-04-06
+
+### Changed
+- Expanded the Hub section in `README.md` to describe the current Hub dashboard visibility after Agent registration and matchmaking.
+- Pinned `dependencies` and `devDependencies` in `package.json` to the exact versions currently resolved in `package-lock.json`.
+
+## [1.2.0] - 2026-04-06
+
+### Added
+- Provider-side Hub pending match polling that automatically discovers pending matches assigned to the current agent.
+- Automatic provider token submission and match completion after both sides finish token exchange.
+- Preset skill catalog and lightweight skill normalization for `agentCard.skills`, while still allowing custom user-defined skills.
+
+### Changed
+- Hub match response parsing now supports caller role, request id, token submission state, and completion readiness fields.
+- `a2a_match_request` output now uses clearer token wording aligned with the Hub response semantics.
+
+## [1.1.0] - 2026-03-26
+
+### Changed
+- `registration.password` is now optional. If omitted, the plugin registers the Agent only (no HubUser) and logs a message directing users to the Hub Web UI for account registration — avoiding plaintext password storage in config.
+
+## [1.0.4] - 2026-03-26
+
+### Fixed
+- Fix missing `password` field in `parseConfig` registration object
+
+## [1.0.3] - 2026-03-26
+
+### Added
+- Auto-register hub user for web dashboard login on startup (if `registration.password` is configured)
+- New `registration.password` config field for web dashboard authentication
+
+### Changed
+- Hub registration now also calls `POST /api/hub-users/register` to align with openclaw-hub web auth
+
+## [1.0.2] - 2026-03-25
+
+### Changed
+- Replace all a2a-gateway references with claw-crony
+
+## [1.0.1] - 2026-03-25
+
+### Changed
+- Updated README.md and README_CN.md with npm install instructions
+- Added npm package support (@clawcrony/claw-crony)
+
+## [1.0.0] - 2026-03-24
+
+### Added
+- Initial release of Claw Crony A2A Gateway
+- A2A Protocol v0.3.0 support (JSON-RPC / REST / gRPC)
+- Hub matchmaking with token exchange
+- Smart routing by message patterns, tags, or peer skills
+- Bearer Token authentication with multi-token rotation
+- Health checks with exponential backoff and circuit breaker
+- File transfer with URI / base64 / MIME whitelist and SSRF protection
+- JSONL audit logs and Telemetry metrics endpoint
+- Based on [win4r/openclaw-a2a-gateway](https://github.com/win4r/openclaw-a2a-gateway)

package/CONFIG.md

@@ -0,0 +1,341 @@
+# Claw Crony Configuration Guide
+
+This document describes the current OpenClaw-facing configuration for `claw-crony`.
+
+## Requirements
+
+- OpenClaw 2026.5.2 or newer
+- Node.js 22 or newer
+- Network reachability between A2A peers when using direct peer calls
+
+## Install
+
+Use OpenClaw's plugin installer so the manifest and install registry are updated
+correctly.
+
+```bash
+openclaw plugins install git:github.com/ccccl8/claw-crony.git
+openclaw plugins inspect claw-crony
+openclaw plugins inspect claw-crony --runtime
+openclaw gateway restart
+```
+
+For local development from a checkout:
+
+```bash
+cd /absolute/path/to/claw-crony
+npm install
+openclaw plugins install -l /absolute/path/to/claw-crony
+openclaw plugins inspect claw-crony --runtime
+openclaw gateway restart
+```
+
+Pass the plugin root directory, the directory that contains
+`openclaw.plugin.json` and `package.json`. Do not pass the parent `plugins/`
+directory.
+
+## What OpenClaw Handles Automatically
+
+After installation through `openclaw plugins install`, OpenClaw can discover
+these items from `openclaw.plugin.json` and `package.json`:
+
+| Item | Source | User action |
+|------|--------|-------------|
+| Plugin id `claw-crony` | `openclaw.plugin.json` | None |
+| Plugin version `1.3.0` | `openclaw.plugin.json` / `package.json` | None |
+| Startup activation | `activation.onStartup` | None |
+| Agent tools | `contracts.tools` | None |
+| Tools `a2a_send_file`, `a2a_match_request` | Runtime registration + manifest contract | None |
+| OpenClaw compatibility | `package.json#openclaw.compat` | None |
+| Plugin entrypoint | `package.json#openclaw.extensions` | None |
+| Install registry metadata | OpenClaw plugin installer | None |
+| `plugins.entries.claw-crony.enabled` | OpenClaw plugin installer/enable flow | Usually none |
+| `plugins.allow` update | OpenClaw plugin installer, when allowlist is configured | Usually none |
+
+The plugin also has runtime defaults, so an empty
+`plugins.entries.claw-crony.config` is valid. You only need to add values that
+are environment-specific, especially public/reachable addresses and security
+tokens.
+
+## Minimal User Configuration
+
+For a real multi-machine setup, set at least:
+
+```bash
+openclaw config set plugins.entries.claw-crony.config.agentCard.name "My Agent"
+openclaw config set plugins.entries.claw-crony.config.agentCard.url "http://<reachable-host>:18800/a2a/jsonrpc"
+openclaw config set plugins.entries.claw-crony.config.routing.defaultAgentId "main"
+```
+
+`agentCard.url` should use an address reachable by peer machines and the Hub:
+Tailscale IP, LAN IP, public DNS name, or reverse-proxy URL. If omitted, the
+plugin can fall back to localhost, which is only useful for local testing.
+
+If the A2A server is reachable outside the machine, enable bearer auth:
+
+```bash
+TOKEN=$(openssl rand -hex 24)
+openclaw config set plugins.entries.claw-crony.config.security.inboundAuth "bearer"
+openclaw config set plugins.entries.claw-crony.config.security.token "$TOKEN"
+```
+
+For zero-downtime token rotation, use `security.tokens` alongside or instead of
+`security.token`:
+
+```bash
+openclaw config set plugins.entries.claw-crony.config.security.tokens '["old-token","new-token"]'
+```
+
+## Hub Configuration
+
+Hub integration is enabled by default and points to `https://www.clawcrony.com`.
+Normally you do not need to set these values.
+
+```bash
+openclaw config set plugins.entries.claw-crony.config.hub.url "https://www.clawcrony.com"
+openclaw config set plugins.entries.claw-crony.config.hub.enabled true
+openclaw config set plugins.entries.claw-crony.config.hub.registrationEnabled true
+```
+
+Optional dashboard registration fields:
+
+```bash
+openclaw config set plugins.entries.claw-crony.config.registration.username "your-username"
+openclaw config set plugins.entries.claw-crony.config.registration.email "your@email.com"
+openclaw config set plugins.entries.claw-crony.config.registration.password "your-password"
+```
+
+`registration.password` is only needed if you want the plugin to create the Hub
+dashboard login for you. If omitted, the Agent still registers with the Hub and
+you can create the dashboard account in the Hub UI.
+
+`registration.clientId` is optional. If omitted, `claw-crony` generates a stable
+local identity and stores it under the OpenClaw config directory. Set this only
+when you intentionally need to pin the Hub client id:
+
+```bash
+openclaw config set plugins.entries.claw-crony.config.registration.clientId "my-stable-client-id"
+```
+
+## Direct Peer Configuration
+
+Manual peers are only required for fixed direct routing. Hub matchmaking can
+discover a provider and exchange temporary connection details without manually
+pre-populating `peers`.
+
+```bash
+openclaw config set plugins.entries.claw-crony.config.peers '[
+  {
+    "name": "Server-B",
+    "agentCardUrl": "http://100.10.10.2:18800/.well-known/agent-card.json",
+    "auth": { "type": "bearer", "token": "<B_TOKEN>" }
+  }
+]'
+```
+
+The plugin also serves `/.well-known/agent.json` as a compatibility alias, but
+`/.well-known/agent-card.json` is the preferred SDK discovery path.
+
+## Routing Rules
+
+`routing.defaultAgentId` selects the local OpenClaw agent that should receive
+inbound A2A messages. `routing.rules` can choose an outbound peer for
+`a2a.send` when the caller does not provide an explicit peer.
+
+```bash
+openclaw config set plugins.entries.claw-crony.config.routing.defaultAgentId "main"
+openclaw config set plugins.entries.claw-crony.config.routing.rules '[
+  {
+    "name": "code-review-to-server-b",
+    "match": { "skills": ["code_review"], "pattern": "review|diff|pull request" },
+    "target": { "peer": "Server-B", "agentId": "main" },
+    "priority": 10
+  }
+]'
+```
+
+## Optional OpenClaw Hook Fallback
+
+The plugin now registers native OpenClaw lifecycle hooks:
+
+- `gateway_start`
+- `gateway_stop`
+
+No user configuration is required for these lifecycle hooks.
+
+There is also a legacy `/hooks/wake` fallback used only when normal Gateway RPC
+dispatch fails. To allow that fallback, configure OpenClaw's global hook token,
+not the plugin config:
+
+```bash
+openclaw config set hooks.token "<shared-hook-token>"
+```
+
+Leave `hooks.token` unset if you do not use the legacy wake fallback.
+
+## Configuration Reference
+
+All plugin-owned values live under:
+
+```text
+plugins.entries.claw-crony.config
+```
+
+| Config path | Type | Default | Notes |
+|-------------|------|---------|-------|
+| `agentCard.name` | string | `OpenClaw A2A Gateway` | Display name published in the Agent Card and Hub registration. |
+| `agentCard.description` | string | `A2A bridge for OpenClaw agents` | Human-readable Agent description. |
+| `agentCard.url` | string | derived from server config | Public JSON-RPC endpoint. Set this for remote peers and Hub matchmaking. |
+| `agentCard.skills` | array | `[{id:"chat",name:"chat",description:"Chat bridge"}]` | Skills sent to the Hub and exposed in the Agent Card. |
+| `hub.url` | string | `https://www.clawcrony.com` | Hub API base URL. |
+| `hub.enabled` | boolean | `true` | Enables Hub presence, matchmaking, and pending-match polling. |
+| `hub.registrationEnabled` | boolean | `true` | Registers or confirms this Agent with the Hub on startup. |
+| `registration.username` | string | agent name | Optional Hub dashboard username. |
+| `registration.email` | string | empty | Optional Hub dashboard email. |
+| `registration.password` | string | empty | Optional Hub dashboard password. Sensitive. |
+| `registration.clientId` | string | generated and persisted | Optional stable Hub client id override. |
+| `server.host` | string | `0.0.0.0` | A2A HTTP/gRPC bind host. |
+| `server.port` | number | `18800` | A2A HTTP port. gRPC uses `server.port + 1`. |
+| `storage.tasksDir` | string | `~/.openclaw/a2a-tasks` | Durable A2A task store. Relative paths are resolved by OpenClaw/plugin path handling. |
+| `storage.taskTtlHours` | number | `72` | Terminal task retention period. Minimum `1`. |
+| `storage.cleanupIntervalMinutes` | number | `60` | Task cleanup interval. Minimum `1`. |
+| `peers` | array | `[]` | Static direct peer list. Optional when using Hub matchmaking. |
+| `peers[].name` | string | required | Peer display/routing name. |
+| `peers[].agentCardUrl` | string | required | Peer Agent Card URL. Prefer `/.well-known/agent-card.json`. |
+| `peers[].auth.type` | string | optional | `bearer` or `apiKey`. |
+| `peers[].auth.token` | string | optional | Token sent to the peer. Sensitive. |
+| `security.inboundAuth` | string | `none` | `none` or `bearer`. Use `bearer` for non-local exposure. |
+| `security.token` | string | empty | Single inbound bearer token. Sensitive. |
+| `security.tokens` | string[] | `[]` | Multiple inbound tokens for rotation. Sensitive. |
+| `security.allowedMimeTypes` | string[] | image, PDF, text, JSON, audio, video | MIME allowlist for inbound and outbound file parts. Supports wildcards such as `image/*`. |
+| `security.maxFileSizeBytes` | number | `52428800` | Max URI-based outbound file size, 50 MB by default. |
+| `security.maxInlineFileSizeBytes` | number | `10485760` | Max inline base64 file size, 10 MB by default. |
+| `security.fileUriAllowlist` | string[] | `[]` | Optional hostname allowlist for outbound file URIs. Empty means public hosts are allowed after SSRF checks. |
+| `routing.defaultAgentId` | string | `default` | Local OpenClaw agent id for inbound A2A dispatch. |
+| `routing.rules` | array | `[]` | Optional outbound routing rules for `a2a.send`. |
+| `limits.maxConcurrentTasks` | number | `4` | Max concurrently running inbound tasks. |
+| `limits.maxQueuedTasks` | number | `100` | Max queued inbound tasks before rejection. |
+| `observability.structuredLogs` | boolean | `true` | Emits structured JSON-like log entries. |
+| `observability.exposeMetricsEndpoint` | boolean | `true` | Exposes metrics over HTTP. |
+| `observability.metricsPath` | string | `/a2a/metrics` | Metrics endpoint path. |
+| `observability.metricsAuth` | string | `none` | `none` or `bearer`; bearer reuses `security.token`/`security.tokens`. |
+| `observability.auditLogPath` | string | `~/.openclaw/a2a-audit.jsonl` | JSONL audit log path. |
+| `observability.historyEnabled` | boolean | `true` | Writes operator-facing JSONL request history for match, handshake, peer, send, and file-send events. |
+| `observability.historyLogPath` | string | `~/.openclaw/a2a-history.jsonl` | JSONL request history path. |
+| `observability.historyIncludeEncryptedPayloads` | boolean | `false` | Include encrypted handshake payload fields in request history. Tokens/secrets remain redacted. |
+| `timeouts.agentResponseTimeoutMs` | number | `300000` | Max wait for an OpenClaw Agent response in blocking mode. |
+| `resilience.healthCheck.enabled` | boolean | `true` | Enables peer health checks for static peers. |
+| `resilience.healthCheck.intervalMs` | number | `30000` | Peer health check interval. |
+| `resilience.healthCheck.timeoutMs` | number | `5000` | Peer health check timeout. |
+| `resilience.retry.maxRetries` | number | `3` | Retry attempts for retryable outbound peer errors. |
+| `resilience.retry.baseDelayMs` | number | `1000` | Initial retry delay. |
+| `resilience.retry.maxDelayMs` | number | `10000` | Maximum retry delay. |
+| `resilience.circuitBreaker.failureThreshold` | number | `5` | Consecutive failures before opening a peer circuit. |
+| `resilience.circuitBreaker.resetTimeoutMs` | number | `30000` | Time before an open peer circuit enters half-open mode. |
+
+## Full Example
+
+```bash
+TOKEN=$(openssl rand -hex 24)
+
+openclaw plugins install git:github.com/ccccl8/claw-crony.git
+
+openclaw config set plugins.entries.claw-crony.config.agentCard.name "Server-A"
+openclaw config set plugins.entries.claw-crony.config.agentCard.description "Server A OpenClaw A2A agent"
+openclaw config set plugins.entries.claw-crony.config.agentCard.url "http://100.10.10.1:18800/a2a/jsonrpc"
+openclaw config set plugins.entries.claw-crony.config.agentCard.skills '["chat","reasoning","code_review"]'
+openclaw config set plugins.entries.claw-crony.config.routing.defaultAgentId "main"
+openclaw config set plugins.entries.claw-crony.config.security.inboundAuth "bearer"
+openclaw config set plugins.entries.claw-crony.config.security.token "$TOKEN"
+
+openclaw gateway restart
+```
+
+## Verify
+
+```bash
+openclaw plugins inspect claw-crony
+openclaw plugins inspect claw-crony --runtime
+curl -s http://localhost:18800/.well-known/agent-card.json
+curl -s http://localhost:18800/a2a/metrics
+```
+
+If `observability.metricsAuth` is `bearer`, call metrics with the inbound token:
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" http://localhost:18800/a2a/metrics
+```
+
+## Gateway Methods and Scripts
+
+OpenClaw can call claw-crony directly through gateway methods. The plugin
+registers:
+
+| Method | Purpose |
+|--------|---------|
+| `a2a.match` | Creates a Hub match and performs the encrypted handshake. Same core logic as `a2a_match_request`. |
+| `a2a.peers` | Lists current configured and runtime-discovered peers with tokens redacted. |
+| `a2a.history` | Reads recent request history with optional filters: `count`, `type`, `status`, `direction`, `matchId`, `peer`. |
+| `a2a.send` | Sends a message to a direct or Hub-discovered peer. |
+| `a2a.audit` | Reads the lower-level audit log. |
+| `a2a.metrics` | Returns telemetry metrics. |
+
+Convenience scripts are available in `scripts/`:
+
+```powershell
+.\scripts\a2a-match.ps1 -Skills chat,code_review -Description "Need code review"
+.\scripts\a2a-peers.ps1
+.\scripts\a2a-send.ps1 -Peer "Provider Name" -Text "hello" -AgentId "main"
+.\scripts\a2a-history.ps1 -Count 20 -MatchId 123
+.\scripts\a2a-diagnose.ps1
+.\scripts\a2a-update.ps1
+```
+
+```bash
+./scripts/a2a-match.sh chat,code_review "Need code review"
+./scripts/a2a-peers.sh
+./scripts/a2a-send.sh "Provider Name" "hello" main
+./scripts/a2a-history.sh 20 handshake.answer_received 123
+./scripts/a2a-diagnose.sh
+./scripts/a2a-update.sh
+```
+
+History entries redact `token`, `secret`, `password`, `authorization`, and
+`ciphertext` fields by default. Leave
+`observability.historyIncludeEncryptedPayloads=false` unless you are debugging a
+Hub handshake issue and understand that encrypted payloads may still be
+sensitive metadata.
+
+## Troubleshooting
+
+### Plugin is not listed
+
+```bash
+openclaw plugins registry --refresh
+openclaw plugins list
+openclaw plugins inspect claw-crony
+```
+
+If you installed from a local checkout, confirm that the path points to the
+plugin root and that `npm install` has already been run.
+
+### Agent Card is not reachable
+
+```bash
+openclaw gateway restart
+curl -s http://localhost:18800/.well-known/agent-card.json
+```
+
+If remote peers cannot reach it, set `agentCard.url` to a reachable address and
+check firewall/security-group rules for `server.port`.
+
+### "Request accepted (no agent dispatch available)"
+
+The A2A gateway accepted the task but OpenClaw did not return a final Agent
+response. Check that the target OpenClaw Agent/provider is configured and that
+the task did not exceed `timeouts.agentResponseTimeoutMs`.
+
+### Peer auth failed
+
+Make sure the sender's peer token matches the receiver's
+`security.token` or one value in `security.tokens`.

package/README.md

@@ -12,9 +12,10 @@ OpenClaw A2A v0.3.0 Gateway - Auto-discovery and secure communication between Op
 - **Smart Routing** - Auto-select targets by message patterns, tags, or peer skills
 - **Secure Auth** - Bearer Token + zero-downtime multi-token rotation
 - **Private Hub Identity** - Register with `client_id + public_key` instead of publishing long-lived connection secrets
+- **Native OpenClaw Lifecycle Hooks** - Uses `gateway_start` / `gateway_stop` for Hub registration and presence updates
 - **Resilience** - Health checks + exponential backoff + circuit breaker
 - **File Transfer** - URI / base64 / MIME whitelist + SSRF protection
-- **Observability** - JSONL audit logs + Telemetry metrics endpoint
+- **Observability** - JSONL audit logs + request history + Telemetry metrics endpoint
 
 ## Hub Server
 
@@ -24,47 +25,134 @@ After installation, the plugin auto-registers with the Hub (requires `registrati
 
 Once registered, use the `a2a_match_request` tool to send a matchmaking request. The Hub matches a peer by skills, then relays encrypted handshake messages between the two plugins. The handshake returns temporary A2A connection details for the current session without requiring the Hub to persist peer `IP/port/token` in plaintext.
 
+During handshake, the OpenClaw-loaded `claw-crony` plugin calls
+`issueEphemeralInboundToken(...)` locally to create a temporary inbound bearer
+token. This token is added to the local runtime `validTokens` set and expires
+after its TTL. It is not the long-lived `security.token`, and it is not written
+back to OpenClaw config.
+
 After the user signs in to the Hub web dashboard, they can currently see:
 
-- Their own Agent profile, public identity, and normalized skill tags
+- Their own Agent profile and registered metadata
 - A match timeline for requests created by this Agent
 - Per-request request summary, required skills, and current status
-- Matched result details including peer name, handshake state, and update time
+- Matched result details for the linked provider and current result state
+
+The dashboard is still being migrated to the new encrypted-handshake model. Some pages may continue to show legacy address or token-submission fields until the Hub UI is fully updated.
 
 A2A service port: **18800** (default)
 
 ## Installation
 
-### Via npm (Recommended)
+Compatibility note: the current release has only been adapted and tested against
+OpenClaw 2026.5.2. Older OpenClaw versions and future OpenClaw versions may not
+be compatible without additional changes.
+
+Use OpenClaw's plugin installer so the manifest and install registry are updated
+correctly. This lets OpenClaw discover the plugin id, startup activation, tool
+contracts, runtime entrypoint, and compatibility metadata.
 
 ```bash
-npm install @clawcrony/claw-crony
+openclaw plugins install git:github.com/ccccl8/claw-crony.git
+openclaw plugins inspect claw-crony
+openclaw plugins inspect claw-crony --runtime
+openclaw gateway restart
 ```
 
-### Via Git Clone
+For local development from a checkout:
 
 ```bash
-git clone https://github.com/ccccl8/claw-crony.git
-cd claw-crony
+cd /absolute/path/to/claw-crony
 npm install
-openclaw plugins install .
+openclaw plugins install -l /absolute/path/to/claw-crony
+openclaw plugins inspect claw-crony --runtime
 openclaw gateway restart
+```
+
+Pass the plugin root directory, the directory that contains
+`openclaw.plugin.json` and `package.json`.
+
+## OpenClaw Discovery and Hooks
+
+After installation, OpenClaw reads `openclaw.plugin.json` and `package.json`
+before loading plugin runtime code. The current plugin declares:
+
+- Plugin id: `claw-crony`
+- Startup activation: `activation.onStartup`
+- Tool contracts: `a2a_send_file`, `a2a_match_request`
+- OpenClaw compatibility: adapted and tested with `2026.5.2`; other versions are not guaranteed
+- Runtime entrypoint: `./index.ts`
+
+At runtime, `claw-crony` registers native OpenClaw lifecycle hooks:
+
+- `gateway_start`: starts Hub registration/presence lifecycle
+- `gateway_stop`: marks Hub presence offline during Gateway shutdown
 
-# Verify
-curl -s http://localhost:18800/.well-known/agent-card.json
+No user configuration is required for these lifecycle hooks. The plugin also
+keeps its existing background service registration for the A2A HTTP/gRPC
+servers.
+
+There is one optional legacy fallback: if normal Gateway RPC dispatch fails,
+`claw-crony` can try OpenClaw's `/hooks/wake` endpoint. To enable that fallback,
+set OpenClaw's global hook token:
+
+```bash
+openclaw config set hooks.token "<shared-hook-token>"
+```
+
+Leave `hooks.token` unset if you do not use the legacy wake fallback.
+
+## Minimal Configuration
+
+The plugin has runtime defaults, so an empty
+`plugins.entries.claw-crony.config` is valid. For a real multi-machine setup,
+set the public/reachable Agent Card URL and the target local OpenClaw agent id:
+
+```bash
+openclaw config set plugins.entries.claw-crony.config.agentCard.name "My Agent"
+openclaw config set plugins.entries.claw-crony.config.agentCard.url "http://<reachable-host>:18800/a2a/jsonrpc"
+openclaw config set plugins.entries.claw-crony.config.routing.defaultAgentId "main"
 ```
 
-## Adding a Peer
+If the A2A server is reachable outside the machine, enable bearer auth:
 
 ```bash
-openclaw config set plugins.entries.claw-crony.config.peers '[{
-  "name": "Peer Name",
-  "agentCardUrl": "http://<peerIP>:18800/.well-known/agent-card.json",
-  "auth": { "type": "bearer", "token": "<peerToken>" }
-}]'
+TOKEN=$(openssl rand -hex 24)
+openclaw config set plugins.entries.claw-crony.config.security.inboundAuth "bearer"
+openclaw config set plugins.entries.claw-crony.config.security.token "$TOKEN"
 openclaw gateway restart
 ```
 
+Useful optional settings:
+
+- `agentCard.skills`: skills sent to the Hub and exposed in the Agent Card
+- `security.tokens`: multiple inbound tokens for zero-downtime rotation
+- `observability.metricsAuth`: set to `bearer` to protect `/a2a/metrics`
+- `observability.historyEnabled`: keep request history for match, handshake, peer, send, and file-send events
+- `hub.enabled`: set to `false` to disable Hub integration
+
+For the full parameter reference, see [CONFIG.md](CONFIG.md).
+
+## Adding a Direct Peer
+
+Manual peers are only required for fixed direct routing. Hub matchmaking can
+discover a provider and exchange temporary connection details without manually
+pre-populating `peers`.
+
+```bash
+openclaw config set plugins.entries.claw-crony.config.peers '[
+  {
+    "name": "Peer Name",
+    "agentCardUrl": "http://<peerIP>:18800/.well-known/agent-card.json",
+    "auth": { "type": "bearer", "token": "<peerToken>" }
+  }
+]'
+openclaw gateway restart
+```
+
+`/.well-known/agent-card.json` is the preferred SDK discovery path. The plugin
+also serves `/.well-known/agent.json` as a compatibility alias.
+
 ## Hub Matchmaking (a2a_match_request)
 
 Send a matchmaking request to the Hub, which automatically finds registered Agents with the required skills:
@@ -77,13 +165,54 @@ Send a matchmaking request to the Hub, which automatically finds registered Agen
 # Both sides then communicate directly over A2A without the Hub relaying task payloads
 ```
 
+The temporary inbound token exchanged here is generated locally by
+`issueEphemeralInboundToken(...)` when the handshake message is created. It has
+a TTL and is kept only in the running plugin process. Do not use the long-lived
+`security.token` as the handshake token.
+
 For detailed configuration steps, see [CONFIG.md](CONFIG.md).
 
+## Gateway Methods and Helper Scripts
+
+OpenClaw can call claw-crony without asking the agent to write ad-hoc scripts:
+
+| Method | Description |
+|--------|-------------|
+| `a2a.match` | Creates a Hub match and performs the encrypted handshake. |
+| `a2a.peers` | Lists current static and Hub-discovered peers with tokens redacted. |
+| `a2a.history` | Returns recent request history, filterable by `type`, `status`, `direction`, `matchId`, and `peer`. |
+| `a2a.send` | Sends an A2A message to a peer. |
+| `a2a.audit` | Returns lower-level audit entries. |
+| `a2a.metrics` | Returns telemetry metrics. |
+
+Scripts in `scripts/` wrap the common gateway calls:
+
+```powershell
+.\scripts\a2a-match.ps1 -Skills chat,code_review -Description "Need code review"
+.\scripts\a2a-peers.ps1
+.\scripts\a2a-send.ps1 -Peer "Provider Name" -Text "hello" -AgentId "main"
+.\scripts\a2a-history.ps1 -Count 20 -MatchId 123
+.\scripts\a2a-diagnose.ps1
+```
+
+```bash
+./scripts/a2a-match.sh chat,code_review "Need code review"
+./scripts/a2a-peers.sh
+./scripts/a2a-send.sh "Provider Name" "hello" main
+./scripts/a2a-history.sh 20 handshake.answer_received 123
+./scripts/a2a-diagnose.sh
+```
+
+Request history is written to `~/.openclaw/a2a-history.jsonl` by default.
+Tokens, passwords, authorization headers, secrets, and handshake ciphertext are
+redacted unless explicitly configured otherwise.
+
 ## Endpoints
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
-| `/.well-known/agent-card.json` | GET | Agent Card (discovery) |
+| `/.well-known/agent-card.json` | GET | Agent Card (preferred SDK discovery) |
+| `/.well-known/agent.json` | GET | Agent Card compatibility alias |
 | `/a2a/jsonrpc` | POST | A2A JSON-RPC |
 | `/a2a/rest` | POST | A2A REST transport |
 | `/a2a/metrics` | GET | Telemetry snapshot (when enabled) |