@perkos/perkos-a2a 0.8.13 → 0.8.15

package/dist/pairing.d.ts

@@ -0,0 +1,56 @@
+export type PairingRuntime = "openclaw" | "hermes" | "custom" | string;
+export interface PairingAgentIdentity {
+    agentName: string;
+    agentId?: string;
+    publicKey: string;
+    privateKey: string;
+    keyType: "ed25519";
+    createdAt: string;
+}
+export interface PairingClaimRequest {
+    agentName: string;
+    publicKey: string;
+    keyType: "ed25519";
+    runtime: PairingRuntime;
+    capabilities: string[];
+    transport: {
+        relay: true;
+        publicUrl?: string;
+    };
+    metadata?: Record<string, unknown>;
+}
+export interface PairingCredential {
+    agentId: string;
+    agentName: string;
+    system: string;
+    relayUrl: string;
+    relayApiKey: string;
+    scopes: string[];
+    approvedAt: string;
+    expiresAt?: string;
+}
+export interface PairingClaimResponse {
+    status: "pending" | "approved" | "rejected";
+    requestId: string;
+    inviteId: string;
+    credential?: PairingCredential;
+    message?: string;
+}
+export interface StoredPairingProfile {
+    identity: PairingAgentIdentity;
+    credential?: PairingCredential;
+    lastPairing?: PairingClaimResponse;
+}
+export declare function defaultPairingPath(agentName: string): string;
+export declare function loadOrCreateIdentity(agentName: string, path?: string): PairingAgentIdentity;
+export declare function savePairingProfile(profile: StoredPairingProfile, path?: string): void;
+export declare function buildClaimRequest(input: {
+    identity: PairingAgentIdentity;
+    runtime: PairingRuntime;
+    capabilities?: string[];
+    publicUrl?: string;
+    metadata?: Record<string, unknown>;
+}): PairingClaimRequest;
+export declare function claimUrlFromInvite(inviteUrl: string): string;
+export declare function claimPairingInvite(inviteUrl: string, request: PairingClaimRequest): Promise<PairingClaimResponse>;
+//# sourceMappingURL=pairing.d.ts.map

package/dist/pairing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../src/pairing.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEvE,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,SAAS,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,SAAS,CAAC;IACnB,OAAO,EAAE,cAAc,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE;QACT,KAAK,EAAE,IAAI,CAAC;QACZ,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,WAAW,CAAC,EAAE,oBAAoB,CAAC;CACpC;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,SAAgC,GAAG,oBAAoB,CAiBlH;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,EAAE,IAAI,SAAiD,GAAG,IAAI,CAG7H;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,OAAO,EAAE,cAAc,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GAAG,mBAAmB,CAUtB;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAkBvH"}

package/dist/pairing.js

@@ -0,0 +1,66 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { generateKeyPairSync } from "crypto";
+export function defaultPairingPath(agentName) {
+    const safeName = agentName.replace(/[^a-zA-Z0-9_.-]/g, "_");
+    return join(homedir(), ".perkos", "a2a", "agents", `${safeName}.json`);
+}
+export function loadOrCreateIdentity(agentName, path = defaultPairingPath(agentName)) {
+    if (existsSync(path)) {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (raw.identity?.agentName && raw.identity?.publicKey && raw.identity?.privateKey)
+            return raw.identity;
+    }
+    const pair = generateKeyPairSync("ed25519", {
+        publicKeyEncoding: { type: "spki", format: "pem" },
+        privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+    return {
+        agentName,
+        publicKey: pair.publicKey,
+        privateKey: pair.privateKey,
+        keyType: "ed25519",
+        createdAt: new Date().toISOString(),
+    };
+}
+export function savePairingProfile(profile, path = defaultPairingPath(profile.identity.agentName)) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(profile, null, 2)}\n`, { mode: 0o600 });
+}
+export function buildClaimRequest(input) {
+    return {
+        agentName: input.identity.agentName,
+        publicKey: input.identity.publicKey,
+        keyType: input.identity.keyType,
+        runtime: input.runtime,
+        capabilities: input.capabilities?.length ? input.capabilities : ["chat", "tasks:receive", "messages:send"],
+        transport: { relay: true, publicUrl: input.publicUrl },
+        metadata: input.metadata,
+    };
+}
+export function claimUrlFromInvite(inviteUrl) {
+    const trimmed = inviteUrl.replace(/\/+$/, "");
+    return `${trimmed}/claim`;
+}
+export async function claimPairingInvite(inviteUrl, request) {
+    const response = await fetch(claimUrlFromInvite(inviteUrl), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(request),
+    });
+    const body = await response.text();
+    let parsed;
+    try {
+        parsed = body ? JSON.parse(body) : {};
+    }
+    catch {
+        throw new Error(`Pairing server returned non-JSON response (${response.status}): ${body}`);
+    }
+    if (!response.ok) {
+        const message = typeof parsed === "object" && parsed && "error" in parsed ? String(parsed.error) : body;
+        throw new Error(`Pairing claim failed (${response.status}): ${message}`);
+    }
+    return parsed;
+}
+//# sourceMappingURL=pairing.js.map

package/dist/pairing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.js","sourceRoot":"","sources":["../src/pairing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAC7B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAmD7C,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,QAAQ,OAAO,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,SAAiB,EAAE,IAAI,GAAG,kBAAkB,CAAC,SAAS,CAAC;IAC1F,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAyB,CAAC;QAC3E,IAAI,GAAG,CAAC,QAAQ,EAAE,SAAS,IAAI,GAAG,CAAC,QAAQ,EAAE,SAAS,IAAI,GAAG,CAAC,QAAQ,EAAE,UAAU;YAAE,OAAO,GAAG,CAAC,QAAQ,CAAC;IAC1G,CAAC;IAED,MAAM,IAAI,GAAG,mBAAmB,CAAC,SAAS,EAAE;QAC1C,iBAAiB,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE;QAClD,kBAAkB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE;KACrD,CAAC,CAAC;IACH,OAAO;QACL,SAAS;QACT,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO,EAAE,SAAS;QAClB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAA6B,EAAE,IAAI,GAAG,kBAAkB,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IACrH,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3D,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAChF,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAMjC;IACC,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,SAAS;QACnC,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,SAAS;QACnC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,OAAO;QAC/B,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,eAAe,EAAE,eAAe,CAAC;QAC1G,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE;QACtD,QAAQ,EAAE,KAAK,CAAC,QAAQ;KACzB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC9C,OAAO,GAAG,OAAO,QAAQ,CAAC;AAC5B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,SAAiB,EAAE,OAA4B;IACtF,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,kBAAkB,CAAC,SAAS,CAAC,EAAE;QAC1D,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;KAC9B,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,8CAA8C,QAAQ,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,OAAO,GAAG,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAE,MAA6B,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAChI,MAAM,IAAI,KAAK,CAAC,yBAAyB,QAAQ,CAAC,MAAM,MAAM,OAAO,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,MAA8B,CAAC;AACxC,CAAC"}

package/docs/nexus-communications-server.md

@@ -0,0 +1,191 @@
+# Nexus Communications Server Pattern
+
+> Deployment note: the standalone communications/transport server source now lives in [`PerkOS-xyz/PerkOS-Transport`](https://github.com/PerkOS-xyz/PerkOS-Transport). This package remains the A2A protocol/plugin implementation used by clients and runtimes.
+
+
+This is the recommended PerkOS A2A topology for Nexus-style project rooms and agent swarms.
+
+## Goals
+
+- Keep user/runtime agents behind NAT with outbound-only WebSocket connections.
+- Use the relay as a registrar/rendezvous server, not as an unrestricted public chat server.
+- Let a product backend orchestrate project-room messages, task assignment, persistence, and auth.
+- Allow OpenClaw/Hermes workers to receive A2A envelopes and call back into the backend with results.
+
+## Components
+
+```text
+Nexus UI
+  -> Nexus Backend / communications server
+      -> PerkOS A2A orchestrator client
+          -> PerkOS A2A relay hub
+              -> OpenClaw or Hermes runtime worker
+                  -> authenticated callback to Nexus Backend
+```
+
+### Relay hub
+
+Run the relay on a stable host or locally for development:
+
+```bash
+RELAY_PORT=6060 \
+RELAY_API_KEYS=devkey \
+a2a-relay
+```
+
+For production, prefer `RELAY_AGENTS`/`registeredAgents` so every agent has an explicit approved registration key instead of a shared relay key.
+
+### Backend / communications server
+
+The backend owns durable product state. It should:
+
+1. register or launch runtime agents and persist their stable `agentId`;
+2. create an A2A client named after the backend/orchestrator;
+3. dispatch structured envelopes to `agentId` targets;
+4. receive authenticated runtime callbacks;
+5. persist messages, task logs, artifacts, and status.
+
+Envelope examples:
+
+```json
+{
+  "kind": "nexus.agent_discussion",
+  "version": 1,
+  "walletAddress": "<wallet>",
+  "projectId": "<project>",
+  "projectName": "Demo Project",
+  "projectGoal": "Coordinate agents",
+  "topic": "What should we build first?",
+  "agentId": "<stable-agent-id>",
+  "agentName": "Builder Agent",
+  "agentRuntime": "OpenClaw",
+  "agentPlugins": ["github", "browser", "storage"]
+}
+```
+
+```json
+{
+  "kind": "nexus.project_task",
+  "version": 1,
+  "walletAddress": "<wallet>",
+  "projectId": "<project>",
+  "taskId": "<task>",
+  "taskName": "Prepare first deliverable",
+  "taskPrompt": "Implement the first slice",
+  "agentId": "<stable-agent-id>",
+  "agentName": "Builder Agent",
+  "agentRuntime": "OpenClaw"
+}
+```
+
+### Runtime worker
+
+A runtime worker should:
+
+- connect outbound to the relay using `NEXUS_A2A_RELAY_URL` and `NEXUS_A2A_RELAY_API_KEY`;
+- register with `agentName = stable agentId` to avoid display-name collisions;
+- validate envelope kind and target `agentId`;
+- execute the requested work or discussion action;
+- call back to the backend using a bearer token or equivalent service auth.
+
+## Local smoke test
+
+NexusApp includes a local smoke test that starts:
+
+- fake Nexus backend callback server;
+- embedded PerkOS A2A relay;
+- real Nexus runtime worker process;
+- A2A orchestrator client.
+
+It verifies both `nexus.agent_discussion` and `nexus.project_task` envelopes reach the worker and produce backend callbacks:
+
+```bash
+cd NexusApp/Backend
+npm run smoke:a2a
+```
+
+Expected output:
+
+```text
+ok - fake Nexus backend listening
+ok - PerkOS A2A relay listening
+ok - orchestrator discovered runtime worker over relay
+ok - A2A discussion envelope reached worker and posted callback
+ok - A2A project-task envelope reached worker and executed callback
+ok - a2a local smoke passed
+```
+
+## Live PerkOS transport endpoint
+
+Current app-server deployment:
+
+- VPS: `62.238.28.49`
+- Public secure endpoint: `wss://transport.perkos.xyz/a2a`
+- TLS: Let's Encrypt via the existing Caddy proxy
+- Container: `perkos-a2a-relay`
+- Server path: `/opt/perkos-a2a-relay`
+- Relay secret: stored only on the VPS in `/opt/perkos-a2a-relay/.env`
+
+Use this from Nexus/worker env:
+
+```bash
+NEXUS_A2A_ENABLED=true
+NEXUS_A2A_RELAY_URL=wss://transport.perkos.xyz/a2a
+NEXUS_A2A_RELAY_API_KEY=<relay-key-from-vps-env>
+```
+
+## Docker deployment
+
+The repo includes a minimal relay runner for VPS/app-server deployments:
+
+- `deploy/Dockerfile`
+- `deploy/relay-runner.mjs`
+
+Example compose service:
+
+```yaml
+services:
+  relay:
+    build: .
+    restart: unless-stopped
+    env_file: .env
+    expose:
+      - "6060"
+```
+
+`.env` should contain either a temporary shared key:
+
+```bash
+RELAY_PORT=6060
+RELAY_API_KEYS=<generated-shared-dev-key>
+```
+
+or, preferably for production, explicit per-agent keys:
+
+```bash
+RELAY_PORT=6060
+RELAY_AGENTS="nexus-backend:<key>,builder-agent:<key>"
+```
+
+If the app server already has Caddy/nginx, route a secure WebSocket subdomain to the relay container, for example:
+
+```caddyfile
+transport.perkos.xyz {
+  encode gzip zstd
+
+  @health path /health
+  respond @health "ok transport.perkos.xyz" 200
+
+  reverse_proxy perkos-a2a-relay:6060
+}
+```
+
+Caddy will automatically issue and renew Let's Encrypt certificates when DNS points to the server.
+
+## Production hardening checklist
+
+- Use explicit registered agents and per-agent registration keys.
+- Keep callback endpoints authenticated and scoped by project/agent.
+- Store task/message receipts with A2A task IDs for replay/debugging.
+- Add relay health and peer discovery endpoints to the backend.
+- Do not put secrets, private keys, seed phrases, or cloud credentials in A2A payloads.

package/docs/pairing-registration.md

@@ -0,0 +1,110 @@
+# PerkOS A2A Pairing Registration
+
+PerkOS A2A agent onboarding uses an invitation workflow instead of shared global relay keys.
+
+## Core flow
+
+```text
+Invite -> Agent Pairing -> Approval -> Registry Entry -> Scoped Relay Credential -> A2A Connection
+```
+
+- **Relay/transport** moves messages and authenticates approved agent names.
+- **Pairing registry** belongs to the external system, e.g. PerkOS Swarm, Nexus, or PerkyFi.
+- **Agent identity** is generated locally by the agent. The private key never leaves the agent machine.
+- **Approval** is explicit unless the invite was created with `autoApprove` for tests or trusted automation.
+
+## System/admin: create an invite
+
+```bash
+curl -X POST https://transport.perkos.xyz/pairing/invites \
+  -H 'authorization: Bearer <PAIRING_ADMIN_KEY>' \
+  -H 'content-type: application/json' \
+  -d '{
+    "system": "perkos-swarm",
+    "label": "Apollo joins Swarm Alpha",
+    "requestedScopes": ["a2a:connect", "swarm:join", "tasks:receive", "messages:send"],
+    "ttlMs": 900000
+  }'
+```
+
+Response:
+
+```json
+{
+  "inviteId": "inv_...",
+  "system": "perkos-swarm",
+  "pairingUrl": "https://transport.perkos.xyz/pairing/invites/inv_...",
+  "relayUrl": "wss://transport.perkos.xyz/a2a",
+  "requestedScopes": ["a2a:connect", "swarm:join", "tasks:receive", "messages:send"]
+}
+```
+
+## Agent: claim the invite
+
+```bash
+npm install -g @perkos/perkos-a2a
+
+perkos-a2a-agent pair \
+  --invite https://transport.perkos.xyz/pairing/invites/inv_... \
+  --agent-name Apollo \
+  --runtime hermes \
+  --capabilities chat,code,research,tasks:receive,messages:send
+```
+
+The CLI:
+
+1. Creates or reuses a local Ed25519 identity at `~/.perkos/a2a/agents/<agent>.json`.
+2. Sends `agentName`, `publicKey`, `runtime`, capabilities, and transport preference to the pairing URL.
+3. Saves the approval credential when approved, or stores the pending request id.
+
+## System/admin: review and approve
+
+```bash
+curl https://transport.perkos.xyz/pairing/requests \
+  -H 'authorization: Bearer <PAIRING_ADMIN_KEY>'
+
+curl -X POST https://transport.perkos.xyz/pairing/requests/req_.../approve \
+  -H 'authorization: Bearer <PAIRING_ADMIN_KEY>' \
+  -H 'content-type: application/json' \
+  -d '{"scopes":["a2a:connect","swarm:join","tasks:receive","messages:send"]}'
+```
+
+Approval creates a registry entry and a relay credential scoped to that agent name.
+
+## Agent: run after approval
+
+The pairing CLI prints the bridge command:
+
+```bash
+A2A_AGENT_NAME=Apollo \
+A2A_RELAY_ENABLED=true \
+A2A_RELAY_URL=wss://transport.perkos.xyz/a2a \
+A2A_RELAY_API_KEY=<agent-scoped-relay-key> \
+A2A_RUNTIME=hermes \
+perkos-a2a-agent
+```
+
+## Prompt for an external agent
+
+```text
+Install or enable @perkos/perkos-a2a.
+Claim this invite: <PAIRING_URL>.
+Generate your own local Ed25519 identity; never export your private key.
+Register as agentName=<NAME>, runtime=<RUNTIME>, capabilities=<CAPABILITIES>.
+Wait for approval from the inviting PerkOS system.
+After approval, connect to the relay using the scoped credential returned by pairing.
+Report final state: agentId, system, relay URL, scopes, runtime, and connection status.
+```
+
+## Environment for the pairing transport service
+
+```bash
+RELAY_PORT=6060
+PUBLIC_BASE_URL=https://transport.perkos.xyz
+PUBLIC_RELAY_URL=wss://transport.perkos.xyz/a2a
+PAIRING_ENABLED=true
+PAIRING_DB_PATH=/var/lib/perkos-transport/pairing-registry.json
+PAIRING_ADMIN_KEYS=<admin-key-1>,<admin-key-2>
+```
+
+`PAIRING_ADMIN_KEYS` should be required in production. If omitted, invite/admin endpoints are open and should only be used for local development.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perkos/perkos-a2a",
-  "version": "0.8.13",
+  "version": "0.8.15",
   "description": "A2A Protocol communication plugin for OpenClaw — Agent-to-Agent protocol implementation",
   "type": "module",
   "main": "dist/index.js",
@@ -8,6 +8,7 @@
   "files": [
     "dist",
     "bin",
+    "docs",
     "skills",
     "openclaw.plugin.json"
   ],