@perkos/perkos-a2a 0.3.5 → 0.5.0

package/dist/relay.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A2A Relay Hub
+ *
+ * Lightweight WebSocket broker for NAT traversal. Agents connect outbound
+ * to the relay, which routes messages between them. Supports API key auth,
+ * rate limiting, agent presence registry, and offline message queuing.
+ *
+ * Can run standalone via bin/relay.ts or embedded in full mode.
+ */
+import type { RelayAgentEntry } from "./types.js";
+export interface RelayHubConfig {
+    port: number;
+    /** Accepted API keys. If empty, auth is disabled. */
+    apiKeys: string[];
+    /** Maximum queued messages per offline agent */
+    maxQueuePerAgent: number;
+    /** Rate limit: max messages per agent per minute */
+    rateLimitPerMinute: number;
+    /** Heartbeat interval in milliseconds */
+    heartbeatIntervalMs: number;
+    /** Consider agent dead after this many missed heartbeats */
+    heartbeatTimeoutMs: number;
+}
+export declare class RelayHub {
+    private wss;
+    private agents;
+    private offlineQueue;
+    private rateCounts;
+    private config;
+    private heartbeatTimer;
+    private logger;
+    constructor(config?: Partial<RelayHubConfig>, logger?: {
+        info: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+    });
+    start(): void;
+    stop(): void;
+    getRegistry(): RelayAgentEntry[];
+    private handleConnection;
+    private handleRegister;
+    private routeMessage;
+    private drainQueue;
+    private handleDiscover;
+    private handleHeartbeat;
+    private checkHeartbeats;
+    private checkRateLimit;
+    private sendError;
+}
+//# sourceMappingURL=relay.d.ts.map

package/dist/relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../src/relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAgB,eAAe,EAAa,MAAM,YAAY,CAAC;AAgB3E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yCAAyC;IACzC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,4DAA4D;IAC5D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAWD,qBAAa,QAAQ;IACnB,OAAO,CAAC,GAAG,CAAgC;IAC3C,OAAO,CAAC,MAAM,CAA0C;IACxD,OAAO,CAAC,YAAY,CAA2C;IAC/D,OAAO,CAAC,UAAU,CAAkE;IACpF,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,MAAM,CAA8E;gBAG1F,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,EAChC,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE;IAMtF,KAAK,IAAI,IAAI;IAab,IAAI,IAAI,IAAI;IAeZ,WAAW,IAAI,eAAe,EAAE;IAahC,OAAO,CAAC,gBAAgB;IAuDxB,OAAO,CAAC,cAAc;IAgDtB,OAAO,CAAC,YAAY;IAgCpB,OAAO,CAAC,UAAU;IAalB,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,eAAe;IAkBvB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,SAAS;CAYlB"}

package/dist/relay.js

@@ -0,0 +1,261 @@
+/**
+ * A2A Relay Hub
+ *
+ * Lightweight WebSocket broker for NAT traversal. Agents connect outbound
+ * to the relay, which routes messages between them. Supports API key auth,
+ * rate limiting, agent presence registry, and offline message queuing.
+ *
+ * Can run standalone via bin/relay.ts or embedded in full mode.
+ */
+import { WebSocketServer, WebSocket } from "ws";
+import { randomUUID } from "crypto";
+const DEFAULT_CONFIG = {
+    port: 6060,
+    apiKeys: [],
+    maxQueuePerAgent: 200,
+    rateLimitPerMinute: 60,
+    heartbeatIntervalMs: 30_000,
+    heartbeatTimeoutMs: 90_000,
+};
+export class RelayHub {
+    wss = null;
+    agents = new Map();
+    offlineQueue = new Map();
+    rateCounts = new Map();
+    config;
+    heartbeatTimer = null;
+    logger;
+    constructor(config, logger) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.logger = logger || { info: console.log, error: console.error };
+    }
+    start() {
+        this.wss = new WebSocketServer({ port: this.config.port });
+        this.logger.info(`[perkos-a2a] Relay hub listening on port ${this.config.port}`);
+        this.wss.on("connection", (ws, req) => {
+            const remoteAddr = req.socket.remoteAddress || "unknown";
+            this.logger.info(`[perkos-a2a] Relay connection from ${remoteAddr}`);
+            this.handleConnection(ws);
+        });
+        this.heartbeatTimer = setInterval(() => this.checkHeartbeats(), this.config.heartbeatIntervalMs);
+    }
+    stop() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.wss) {
+            for (const agent of this.agents.values()) {
+                agent.ws.close(1001, "Relay shutting down");
+            }
+            this.wss.close();
+            this.wss = null;
+            this.logger.info("[perkos-a2a] Relay hub stopped");
+        }
+    }
+    getRegistry() {
+        const entries = [];
+        for (const agent of this.agents.values()) {
+            entries.push({
+                name: agent.name,
+                connectedAt: agent.connectedAt,
+                lastHeartbeat: agent.lastHeartbeat,
+                card: agent.card,
+            });
+        }
+        return entries;
+    }
+    handleConnection(ws) {
+        let agentName = null;
+        ws.on("message", (data) => {
+            let msg;
+            try {
+                msg = JSON.parse(data.toString());
+            }
+            catch {
+                this.sendError(ws, "invalid_json", "Failed to parse message");
+                return;
+            }
+            if (msg.type === "register") {
+                agentName = this.handleRegister(ws, msg);
+                return;
+            }
+            if (!agentName) {
+                this.sendError(ws, "not_registered", "Must register before sending messages");
+                return;
+            }
+            if (!this.checkRateLimit(agentName)) {
+                this.sendError(ws, "rate_limited", "Rate limit exceeded");
+                return;
+            }
+            switch (msg.type) {
+                case "task":
+                case "task_response":
+                    this.routeMessage(agentName, msg);
+                    break;
+                case "discover":
+                    this.handleDiscover(ws, msg);
+                    break;
+                case "heartbeat":
+                    this.handleHeartbeat(agentName, msg);
+                    break;
+                default:
+                    this.sendError(ws, "unknown_type", `Unknown message type: ${msg.type}`);
+            }
+        });
+        ws.on("close", () => {
+            if (agentName) {
+                this.agents.delete(agentName);
+                this.logger.info(`[perkos-a2a] Agent disconnected: ${agentName}`);
+            }
+        });
+        ws.on("error", (err) => {
+            this.logger.error(`[perkos-a2a] WebSocket error for ${agentName || "unknown"}: ${err.message}`);
+        });
+    }
+    handleRegister(ws, msg) {
+        const name = msg.payload.agentName;
+        const apiKey = msg.payload.apiKey;
+        if (!name) {
+            this.sendError(ws, "missing_name", "agentName is required for registration");
+            return null;
+        }
+        if (this.config.apiKeys.length > 0 && !this.config.apiKeys.includes(apiKey)) {
+            this.sendError(ws, "auth_failed", "Invalid API key");
+            ws.close(4001, "Authentication failed");
+            return null;
+        }
+        // Disconnect existing connection for same agent name
+        const existing = this.agents.get(name);
+        if (existing) {
+            existing.ws.close(4002, "Replaced by new connection");
+        }
+        const now = new Date().toISOString();
+        this.agents.set(name, {
+            name,
+            ws,
+            apiKey: apiKey || "",
+            card: msg.payload.card,
+            connectedAt: now,
+            lastHeartbeat: now,
+        });
+        this.logger.info(`[perkos-a2a] Agent registered: ${name}`);
+        const ack = {
+            type: "register_ack",
+            id: msg.id,
+            from: "relay",
+            payload: { status: "ok", agentName: name },
+            timestamp: now,
+        };
+        ws.send(JSON.stringify(ack));
+        // Deliver queued messages
+        this.drainQueue(name, ws);
+        return name;
+    }
+    routeMessage(fromAgent, msg) {
+        const target = msg.to;
+        if (!target) {
+            this.sendError(this.agents.get(fromAgent).ws, "missing_target", "Message requires 'to' field");
+            return;
+        }
+        msg.from = fromAgent;
+        msg.timestamp = new Date().toISOString();
+        const targetAgent = this.agents.get(target);
+        if (targetAgent && targetAgent.ws.readyState === WebSocket.OPEN) {
+            targetAgent.ws.send(JSON.stringify(msg));
+        }
+        else {
+            // Queue for offline delivery
+            if (!this.offlineQueue.has(target)) {
+                this.offlineQueue.set(target, []);
+            }
+            const queue = this.offlineQueue.get(target);
+            if (queue.length < this.config.maxQueuePerAgent) {
+                queue.push({ message: msg, queuedAt: new Date().toISOString() });
+                this.logger.info(`[perkos-a2a] Queued message for offline agent: ${target} (${queue.length} pending)`);
+            }
+            else {
+                this.logger.info(`[perkos-a2a] Queue full for agent: ${target}, dropping message`);
+                const sender = this.agents.get(fromAgent);
+                if (sender) {
+                    this.sendError(sender.ws, "queue_full", `Target agent ${target} queue is full`);
+                }
+            }
+        }
+    }
+    drainQueue(agentName, ws) {
+        const queue = this.offlineQueue.get(agentName);
+        if (!queue || queue.length === 0)
+            return;
+        this.logger.info(`[perkos-a2a] Delivering ${queue.length} queued messages to ${agentName}`);
+        for (const item of queue) {
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.send(JSON.stringify(item.message));
+            }
+        }
+        this.offlineQueue.delete(agentName);
+    }
+    handleDiscover(ws, msg) {
+        const agents = this.getRegistry();
+        const response = {
+            type: "discover_response",
+            id: msg.id,
+            from: "relay",
+            payload: { agents },
+            timestamp: new Date().toISOString(),
+        };
+        ws.send(JSON.stringify(response));
+    }
+    handleHeartbeat(agentName, msg) {
+        const agent = this.agents.get(agentName);
+        if (agent) {
+            agent.lastHeartbeat = new Date().toISOString();
+        }
+        const ack = {
+            type: "heartbeat_ack",
+            id: msg.id,
+            from: "relay",
+            payload: {},
+            timestamp: new Date().toISOString(),
+        };
+        const ws = agent?.ws;
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify(ack));
+        }
+    }
+    checkHeartbeats() {
+        const now = Date.now();
+        for (const [name, agent] of this.agents) {
+            const lastBeat = new Date(agent.lastHeartbeat).getTime();
+            if (now - lastBeat > this.config.heartbeatTimeoutMs) {
+                this.logger.info(`[perkos-a2a] Agent ${name} timed out (no heartbeat)`);
+                agent.ws.close(4003, "Heartbeat timeout");
+                this.agents.delete(name);
+            }
+        }
+    }
+    checkRateLimit(agentName) {
+        const now = Date.now();
+        const window = 60_000;
+        let entry = this.rateCounts.get(agentName);
+        if (!entry || now - entry.windowStart > window) {
+            entry = { count: 0, windowStart: now };
+            this.rateCounts.set(agentName, entry);
+        }
+        entry.count++;
+        return entry.count <= this.config.rateLimitPerMinute;
+    }
+    sendError(ws, code, message) {
+        const errorMsg = {
+            type: "error",
+            id: randomUUID(),
+            from: "relay",
+            payload: { code, message },
+            timestamp: new Date().toISOString(),
+        };
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify(errorMsg));
+        }
+    }
+}
+//# sourceMappingURL=relay.js.map

package/dist/relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.js","sourceRoot":"","sources":["../src/relay.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -1,35 +1,60 @@
 /**
  * A2A Protocol Server
- * Express-based JSON-RPC 2.0 server with Agent Card discovery
+ * Express-based JSON-RPC 2.0 server with Agent Card discovery.
+ * Supports full, client-only, relay, and auto modes.
+ * Integrates with the relay hub for NAT traversal when configured.
  */
 import express from "express";
 import type { AgentCard, JsonRpcResponse, A2APluginConfig } from "./types.js";
+/** Detect if the host is behind NAT by comparing public IP to local interfaces */
+export declare function detectNetworking(): Promise<{
+    isBehindNat: boolean;
+    publicIp: string | null;
+    localIps: string[];
+    hasTailscale: boolean;
+    tailscaleIp: string | null;
+}>;
 export declare class A2AServer {
     private app;
     private tasks;
     private agentCard;
     private config;
     private logger;
+    private clientOnly;
+    private relayClient;
+    private relayHub;
+    private messageInjector;
     constructor(config: A2APluginConfig, logger?: {
         info: (...args: unknown[]) => void;
         error: (...args: unknown[]) => void;
     });
+    /** Set the message injector for delivering tasks into the agent session */
+    setMessageInjector(injector: (text: string, metadata?: Record<string, unknown>) => void): void;
+    isClientOnly(): boolean;
+    isRelayConnected(): boolean;
+    private authMiddleware;
     private setupRoutes;
     private handleSendMessage;
     private processTask;
     private handleGetTask;
     private handleListTasks;
     private handleCancelTask;
-    /** Send a task to a peer agent via A2A protocol */
+    /** Send a task to a peer agent via A2A protocol (direct HTTP or relay) */
     sendTask(targetAgent: string, messageText: string): Promise<JsonRpcResponse>;
-    /** Discover all peer agents */
+    private sendTaskDirect;
+    private sendTaskViaRelay;
+    /** Discover all peer agents (direct + relay) */
     discoverPeers(): Promise<Record<string, {
         status: string;
         card?: AgentCard;
     }>>;
     private success;
     private error;
-    start(): void;
+    /** Handle an inbound task received via the relay */
+    private handleRelayTask;
+    private startRelayClient;
+    private startRelayHub;
+    start(): Promise<void>;
     private tryListen;
     getExpressApp(): express.Express;
 }

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,OAAO,MAAM,SAAS,CAAC;AAG9B,OAAO,KAAK,EACV,SAAS,EAGT,eAAe,EACf,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,qBAAa,SAAS;IACpB,OAAO,CAAC,GAAG,CAAkB;IAC7B,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,MAAM,CAA8E;gBAG1F,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE;IAsBtF,OAAO,CAAC,WAAW;YAgFL,iBAAiB;YA+BjB,WAAW;IA4DzB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,gBAAgB;IAaxB,mDAAmD;IAC7C,QAAQ,CACZ,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC;IAgC3B,+BAA+B;IACzB,aAAa,IAAI,OAAO,CAC5B,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC,CACrD;IAeD,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,KAAK;IAIb,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,SAAS;IA2BjB,aAAa,IAAI,OAAO,CAAC,OAAO;CAGjC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,OAAO,MAAM,SAAS,CAAC;AAK9B,OAAO,KAAK,EACV,SAAS,EAGT,eAAe,EACf,eAAe,EAGhB,MAAM,YAAY,CAAC;AAEpB,kFAAkF;AAClF,wBAAsB,gBAAgB,IAAI,OAAO,CAAC;IAChD,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC,CAwCD;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,GAAG,CAAkB;IAC7B,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,MAAM,CAA8E;IAC5F,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,eAAe,CAA6E;gBAGlG,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE;IAsBtF,2EAA2E;IAC3E,kBAAkB,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,IAAI;IAI9F,YAAY,IAAI,OAAO;IAIvB,gBAAgB,IAAI,OAAO;IAI3B,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,WAAW;YAqEL,iBAAiB;YA6BjB,WAAW;IA0EzB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,gBAAgB;IAaxB,0EAA0E;IACpE,QAAQ,CACZ,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC;YA6Bb,cAAc;YAqCd,gBAAgB;IAuB9B,gDAAgD;IAC1C,aAAa,IAAI,OAAO,CAC5B,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC,CACrD;IAsCD,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,KAAK;IAIb,oDAAoD;IACpD,OAAO,CAAC,eAAe;IAcvB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,aAAa;IAgBf,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyD5B,OAAO,CAAC,SAAS;IA6BjB,aAAa,IAAI,OAAO,CAAC,OAAO;CAGjC"}