@perkos/perkos-a2a 0.9.0 → 0.9.2

package/dist/relay-client.js

@@ -0,0 +1,222 @@
+/**
+ * A2A Relay Client
+ *
+ * WebSocket client that connects to an A2A Relay Hub for NAT-friendly
+ * bidirectional communication. Handles registration, auto-reconnect
+ * with exponential backoff, heartbeats, and message routing.
+ */
+import WebSocket from "ws";
+import { randomUUID } from "crypto";
+const MIN_RECONNECT_MS = 1_000;
+const MAX_RECONNECT_MS = 60_000;
+const HEARTBEAT_INTERVAL_MS = 25_000;
+export class RelayClient {
+    ws = null;
+    options;
+    logger;
+    reconnectMs = MIN_RECONNECT_MS;
+    reconnectTimer = null;
+    heartbeatTimer = null;
+    connected = false;
+    stopped = false;
+    pendingCallbacks = new Map();
+    constructor(options) {
+        this.options = options;
+        this.logger = options.logger || { info: console.log, error: console.error };
+    }
+    isConnected() {
+        return this.connected;
+    }
+    start() {
+        this.stopped = false;
+        this.connect();
+    }
+    stop() {
+        this.stopped = true;
+        this.clearTimers();
+        if (this.ws) {
+            this.ws.close(1000, "Client shutting down");
+            this.ws = null;
+        }
+        this.connected = false;
+    }
+    /** Send a task to another agent via the relay */
+    async sendTask(targetAgent, payload) {
+        return this.sendAndWait({
+            type: "task",
+            to: targetAgent,
+            id: randomUUID(),
+            from: this.options.agentName,
+            payload,
+            timestamp: new Date().toISOString(),
+        }, "task_response", 60_000);
+    }
+    /** Discover agents connected to the relay */
+    async discover() {
+        const response = await this.sendAndWait({
+            type: "discover",
+            id: randomUUID(),
+            from: this.options.agentName,
+            payload: {},
+            timestamp: new Date().toISOString(),
+        }, "discover_response", 10_000);
+        return response.payload.agents || [];
+    }
+    /** Send a task response back through the relay */
+    sendTaskResponse(originalMsg, result) {
+        const response = {
+            type: "task_response",
+            id: originalMsg.id,
+            from: this.options.agentName,
+            to: originalMsg.from,
+            payload: result,
+            timestamp: new Date().toISOString(),
+        };
+        this.send(response);
+    }
+    connect() {
+        if (this.stopped)
+            return;
+        const url = this.options.relay.url;
+        this.logger.info(`[perkos-a2a] Connecting to relay: ${url}`);
+        try {
+            this.ws = new WebSocket(url);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.logger.error(`[perkos-a2a] Failed to create WebSocket: ${msg}`);
+            this.scheduleReconnect();
+            return;
+        }
+        this.ws.on("open", () => {
+            this.connected = true;
+            this.reconnectMs = MIN_RECONNECT_MS;
+            this.logger.info("[perkos-a2a] Connected to relay hub");
+            this.register();
+            this.startHeartbeat();
+        });
+        this.ws.on("message", (data) => {
+            let msg;
+            try {
+                msg = JSON.parse(data.toString());
+            }
+            catch {
+                this.logger.error("[perkos-a2a] Failed to parse relay message");
+                return;
+            }
+            this.handleMessage(msg);
+        });
+        this.ws.on("close", (code, reason) => {
+            this.connected = false;
+            this.clearTimers();
+            if (!this.stopped) {
+                this.logger.info(`[perkos-a2a] Relay connection closed (${code}: ${reason || "no reason"}). Reconnecting...`);
+                this.scheduleReconnect();
+            }
+        });
+        this.ws.on("error", (err) => {
+            this.logger.error(`[perkos-a2a] Relay WebSocket error: ${err.message}`);
+        });
+    }
+    register() {
+        const msg = {
+            type: "register",
+            id: randomUUID(),
+            from: this.options.agentName,
+            payload: {
+                agentName: this.options.agentName,
+                apiKey: this.options.relay.apiKey,
+                card: this.options.card,
+            },
+            timestamp: new Date().toISOString(),
+        };
+        this.send(msg);
+    }
+    handleMessage(msg) {
+        // Check for pending request/response callbacks
+        const callback = this.pendingCallbacks.get(msg.id);
+        if (callback) {
+            this.pendingCallbacks.delete(msg.id);
+            callback(msg);
+            return;
+        }
+        switch (msg.type) {
+            case "register_ack":
+                this.logger.info("[perkos-a2a] Registered with relay hub");
+                break;
+            case "task":
+                this.options.onTask(msg);
+                break;
+            case "task_response":
+                // Late response with no pending callback; log and discard
+                this.logger.info(`[perkos-a2a] Received unmatched task response: ${msg.id}`);
+                break;
+            case "discover_response":
+                if (this.options.onDiscoverResponse) {
+                    this.options.onDiscoverResponse(msg.payload.agents);
+                }
+                break;
+            case "heartbeat_ack":
+                break;
+            case "error":
+                this.logger.error(`[perkos-a2a] Relay error: ${msg.payload.code} - ${msg.payload.message}`);
+                break;
+            default:
+                this.logger.info(`[perkos-a2a] Unknown relay message type: ${msg.type}`);
+        }
+    }
+    send(msg) {
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(msg));
+        }
+    }
+    async sendAndWait(msg, expectedType, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingCallbacks.delete(msg.id);
+                reject(new Error(`Relay request timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pendingCallbacks.set(msg.id, (response) => {
+                clearTimeout(timer);
+                if (response.type === "error") {
+                    reject(new Error(`Relay error: ${response.payload.message}`));
+                }
+                else {
+                    resolve(response);
+                }
+            });
+            this.send(msg);
+        });
+    }
+    startHeartbeat() {
+        this.heartbeatTimer = setInterval(() => {
+            const msg = {
+                type: "heartbeat",
+                id: randomUUID(),
+                from: this.options.agentName,
+                payload: {},
+                timestamp: new Date().toISOString(),
+            };
+            this.send(msg);
+        }, HEARTBEAT_INTERVAL_MS);
+    }
+    scheduleReconnect() {
+        if (this.stopped)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.connect();
+        }, this.reconnectMs);
+        this.reconnectMs = Math.min(this.reconnectMs * 2, MAX_RECONNECT_MS);
+    }
+    clearTimers() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+}
+//# sourceMappingURL=relay-client.js.map

package/dist/relay-client.js.map

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

package/dist/relay.js

@@ -0,0 +1,274 @@
+/**
+ * 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: [],
+    registeredAgents: {},
+    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;
+        }
+        const approvedKey = this.config.registeredAgents[name];
+        if (Object.keys(this.config.registeredAgents).length > 0) {
+            if (!approvedKey || approvedKey !== apiKey) {
+                this.sendError(ws, "not_approved", "Agent is not approved for this relay or API key does not match");
+                ws.close(4001, "Agent not approved");
+                return null;
+            }
+        }
+        else 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();
+        if (Object.keys(this.config.registeredAgents).length > 0 && !(target in this.config.registeredAgents)) {
+            this.sendError(this.agents.get(fromAgent).ws, "target_not_approved", `Target agent ${target} is not approved on this relay`);
+            return;
+        }
+        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/runtime-reply.js

@@ -0,0 +1,137 @@
+import { randomUUID } from "crypto";
+function stripTaskMarker(text, marker) {
+    const trimmed = text.trim();
+    if (!trimmed.includes(marker))
+        return trimmed;
+    return trimmed.slice(trimmed.indexOf(marker) + marker.length).trim();
+}
+function requestedFinalMarker(text) {
+    const patterns = [
+        /termina(?:r)?\s+exactamente\s+con\s+([A-Z0-9_\-]+)/i,
+        /end\s+(?:exactly\s+)?with\s+([A-Z0-9_\-]+)/i,
+    ];
+    for (const pattern of patterns) {
+        const match = text.match(pattern);
+        if (match?.[1])
+            return match[1];
+    }
+    return undefined;
+}
+function withRequestedMarker(reply, text) {
+    const marker = requestedFinalMarker(text);
+    if (!marker || reply.trim().endsWith(marker))
+        return reply;
+    return `${reply.trim()} ${marker}`;
+}
+function runtimeOption(config, key) {
+    const value = config.runtime?.[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function agentIdFor(config) {
+    return runtimeOption(config, "agentId") || config.agentName || "perkos-a2a-agent";
+}
+function llmSystemPrompt(config) {
+    const agentName = config.agentName || config.runtime?.kind || "PerkOS A2A agent";
+    return [
+        `You are ${agentName}, a PerkOS A2A agent.`,
+        "Reply concisely and directly.",
+        "If asked to confirm receipt, confirm that you received the task via PerkOS A2A and are using PerkOS LLM.",
+        "Do not mention implementation details unless asked.",
+    ].join(" ");
+}
+/**
+ * Generate a final task reply through PerkOS LLM when the local runtime accepts
+ * a task but does not expose a synchronous final answer API.
+ *
+ * This keeps A2A task state machine semantics intact: delivery/wake still
+ * happens, while the A2A caller receives a terminal task with a useful artifact
+ * instead of being left in `working` indefinitely.
+ */
+export async function generateRuntimeReply(config, text, marker) {
+    const runtimeKind = config.runtime?.kind || "openclaw";
+    const apiKey = runtimeOption(config, "llmApiKey");
+    if (!apiKey) {
+        const agentName = config.agentName || config.runtime?.kind || "PerkOS A2A agent";
+        const lower = text.toLowerCase();
+        if (lower.includes("confirma") || lower.includes("confirm") || lower.includes("ping")) {
+            return withRequestedMarker(`${agentName} recibió este mensaje vía PerkOS A2A.`, text);
+        }
+        return withRequestedMarker([
+            `${agentName} recibió la tarea vía PerkOS A2A.`,
+            "El runtime/LLM local no está configurado para generar una respuesta completa en este momento, pero el transporte A2A y el estado terminal funcionan.",
+        ].join(" "), text);
+    }
+    const headers = {
+        "content-type": "application/json",
+        authorization: `Bearer ${apiKey}`,
+        "x-agent-id": agentIdFor(config),
+    };
+    const system = llmSystemPrompt(config);
+    const user = [
+        text,
+        "",
+        "Return only the useful final answer.",
+        `Do not include ${marker}; the A2A bridge will attach the marker/task result.`,
+    ].join("\n");
+    if (runtimeKind === "hermes") {
+        const base = (runtimeOption(config, "openAiBaseUrl") || "https://api.llm.perkos.xyz/v1").replace(/\/+$/, "");
+        const model = runtimeOption(config, "model") || "kimi-k2.6:cloud";
+        const response = await fetch(`${base}/chat/completions`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                model,
+                messages: [
+                    { role: "system", content: system },
+                    { role: "user", content: user },
+                ],
+                temperature: 0.2,
+            }),
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            throw new Error(`PerkOS LLM OpenAI-compatible call failed (${response.status}): ${body || response.statusText}`);
+        }
+        const data = await response.json();
+        return stripTaskMarker(data.choices?.[0]?.message?.content || "Task completed.", marker);
+    }
+    const base = (runtimeOption(config, "ollamaBaseUrl") || "https://api.llm.perkos.xyz").replace(/\/+$/, "");
+    const model = runtimeOption(config, "model") || "kimi-k2.6:cloud";
+    const response = await fetch(`${base}/api/chat`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            model,
+            stream: false,
+            messages: [
+                { role: "system", content: system },
+                { role: "user", content: user },
+            ],
+        }),
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`PerkOS LLM Ollama-compatible call failed (${response.status}): ${body || response.statusText}`);
+    }
+    const data = await response.json();
+    return stripTaskMarker(data.message?.content || data.response || "Task completed.", marker);
+}
+export function completeTaskWithReply(task, finalText) {
+    task.artifacts.push({
+        kind: "artifact",
+        artifactId: randomUUID(),
+        parts: [{ kind: "text", text: finalText }],
+    });
+    task.status = {
+        state: "completed",
+        timestamp: new Date().toISOString(),
+        message: {
+            role: "agent",
+            parts: [{ kind: "text", text: finalText }],
+        },
+    };
+}
+export function isTerminalTaskState(state) {
+    return state === "completed" || state === "failed" || state === "canceled";
+}
+//# sourceMappingURL=runtime-reply.js.map

package/dist/runtime-reply.js.map

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