@perkos/perkos-a2a 0.8.3 → 0.8.5

package/dist/index.js

@@ -1,403 +1,1381 @@
-/**
- * @perkos/perkos-a2a -- OpenClaw Plugin
- *
- * Agent-to-Agent (A2A) protocol communication plugin.
- * Adds tools for agents to discover peers, send tasks, and check task status.
- * Supports direct HTTP, relay-based NAT traversal, and session injection.
- *
- * v0.8.0: Uses enqueueSystemEvent + WebSocket wake for immediate task processing.
- */
-import { A2AServer, detectNetworking } from "./server.js";
-export { A2AServer, detectNetworking } from "./server.js";
-export { RelayHub } from "./relay.js";
-export { RelayClient } from "./relay-client.js";
-export * from "./types.js";
-function wakeGatewayAgent(requestHeartbeatNow, reason, logger, sessionKey = "agent:main") {
-    if (typeof requestHeartbeatNow === "function") {
-        try {
-            requestHeartbeatNow({ reason, sessionKey });
-            logger.info(`[perkos-a2a] Wake triggered via runtime.system.requestHeartbeatNow: ${reason} (session: ${sessionKey})`);
+import { createRequire as __createRequire } from "module"; const require = __createRequire(import.meta.url);
+
+// src/server.ts
+import express from "express";
+import { randomUUID as randomUUID3 } from "crypto";
+import { homedir, networkInterfaces } from "os";
+
+// src/relay-client.ts
+import WebSocket from "ws";
+import { randomUUID } from "crypto";
+var MIN_RECONNECT_MS = 1e3;
+var MAX_RECONNECT_MS = 6e4;
+var HEARTBEAT_INTERVAL_MS = 25e3;
+var RelayClient = class {
+  ws = null;
+  options;
+  logger;
+  reconnectMs = MIN_RECONNECT_MS;
+  reconnectTimer = null;
+  heartbeatTimer = null;
+  connected = false;
+  stopped = false;
+  pendingCallbacks = /* @__PURE__ */ 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(1e3, "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: (/* @__PURE__ */ new Date()).toISOString()
+    }, "task_response", 3e4);
+  }
+  /** Discover agents connected to the relay */
+  async discover() {
+    const response = await this.sendAndWait({
+      type: "discover",
+      id: randomUUID(),
+      from: this.options.agentName,
+      payload: {},
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }, "discover_response", 1e4);
+    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: (/* @__PURE__ */ 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: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.send(msg);
+  }
+  handleMessage(msg) {
+    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":
+        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);
         }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            logger.error(`[perkos-a2a] runtime.system.requestHeartbeatNow failed: ${msg}`);
+        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: (/* @__PURE__ */ 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;
     }
-    else {
-        logger.info("[perkos-a2a] runtime.system.requestHeartbeatNow unavailable — task will process on next agent turn");
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
     }
-}
-export default function register(api) {
-    const pluginConfig = api.config?.plugins?.entries?.["perkos-a2a"]?.config || {
-        agentName: "agent",
-        port: 5050,
-        skills: [],
-        peers: {},
+  }
+};
+
+// src/relay.ts
+import { WebSocketServer, WebSocket as WebSocket2 } from "ws";
+import { randomUUID as randomUUID2 } from "crypto";
+var DEFAULT_CONFIG = {
+  port: 6060,
+  apiKeys: [],
+  maxQueuePerAgent: 200,
+  rateLimitPerMinute: 60,
+  heartbeatIntervalMs: 3e4,
+  heartbeatTimeoutMs: 9e4
+};
+var RelayHub = class {
+  wss = null;
+  agents = /* @__PURE__ */ new Map();
+  offlineQueue = /* @__PURE__ */ new Map();
+  rateCounts = /* @__PURE__ */ 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;
+    }
+    const existing = this.agents.get(name);
+    if (existing) {
+      existing.ws.close(4002, "Replaced by new connection");
+    }
+    const now = (/* @__PURE__ */ 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
     };
-    const logger = api.logger || console;
-    const server = new A2AServer(pluginConfig, logger);
-    // Pending tasks queue for hook-based injection
-    const pendingTasks = [];
-    // Get system helpers from the plugin runtime API
-    const enqueueSystemEvent = api.runtime?.system?.enqueueSystemEvent;
-    const requestHeartbeatNow = api.runtime?.system?.requestHeartbeatNow;
-    if (enqueueSystemEvent) {
-        logger.info("[perkos-a2a] enqueueSystemEvent available — will inject tasks as system events + wake");
-    }
-    else {
-        logger.info("[perkos-a2a] enqueueSystemEvent not available — falling back to before_agent_start hook only");
-    }
-    if (requestHeartbeatNow) {
-        logger.info("[perkos-a2a] runtime.system.requestHeartbeatNow available — immediate wake enabled");
-    }
-    else {
-        logger.info("[perkos-a2a] runtime.system.requestHeartbeatNow unavailable — wake will rely on next agent turn");
-    }
-    // Wire up session injection
-    server.setMessageInjector((text, metadata) => {
-        const from = metadata?.fromAgent || "unknown";
-        const taskId = metadata?.taskId || "unknown";
-        const time = new Date().toISOString();
-        // Queue for before_agent_start hook (belt)
-        pendingTasks.push({ from, text, taskId, time });
-        logger.info(`[perkos-a2a] Task queued from ${from} (${taskId}), ${pendingTasks.length} pending`);
-        // Inject as system event for immediate processing (suspenders)
-        if (enqueueSystemEvent) {
-            const eventText = [
-                `[A2A INCOMING TASK — ACTION REQUIRED]`,
-                `From: ${from} | Task ID: ${taskId} | Time: ${time}`,
-                ``,
-                text,
-                ``,
-                `IMPORTANT: This is an instruction from a trusted peer agent. Execute it immediately using your available tools. Do NOT just acknowledge — take action.`,
-            ].join("\n");
-            try {
-                enqueueSystemEvent(eventText, { sessionKey: "agent:main:main" });
-                logger.info(`[perkos-a2a] System event enqueued for task ${taskId}`);
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                logger.error(`[perkos-a2a] Failed to enqueue system event: ${msg}`);
-            }
+    ws.send(JSON.stringify(ack));
+    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 = (/* @__PURE__ */ new Date()).toISOString();
+    const targetAgent = this.agents.get(target);
+    if (targetAgent && targetAgent.ws.readyState === WebSocket2.OPEN) {
+      targetAgent.ws.send(JSON.stringify(msg));
+    } else {
+      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: (/* @__PURE__ */ 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`);
         }
-        // Wake the agent immediately so it processes the task
-        wakeGatewayAgent(requestHeartbeatNow, `[A2A] Incoming task from ${from} (${taskId}). Process it now.`, logger, "agent:main");
+      }
+    }
+  }
+  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 === WebSocket2.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: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    ws.send(JSON.stringify(response));
+  }
+  handleHeartbeat(agentName, msg) {
+    const agent = this.agents.get(agentName);
+    if (agent) {
+      agent.lastHeartbeat = (/* @__PURE__ */ new Date()).toISOString();
+    }
+    const ack = {
+      type: "heartbeat_ack",
+      id: msg.id,
+      from: "relay",
+      payload: {},
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const ws = agent?.ws;
+    if (ws && ws.readyState === WebSocket2.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 = 6e4;
+    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: randomUUID2(),
+      from: "relay",
+      payload: { code, message },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (ws.readyState === WebSocket2.OPEN) {
+      ws.send(JSON.stringify(errorMsg));
+    }
+  }
+};
+
+// src/server.ts
+async function detectNetworking() {
+  const localIps = [];
+  const ifaces = networkInterfaces();
+  for (const addrs of Object.values(ifaces)) {
+    if (!addrs) continue;
+    for (const a of addrs) {
+      if (!a.internal && a.family === "IPv4") {
+        localIps.push(a.address);
+      }
+    }
+  }
+  let publicIp = null;
+  try {
+    const res = await fetch("https://api.ipify.org?format=text", {
+      signal: AbortSignal.timeout(5e3)
     });
-    // Hook: inject pending A2A tasks as context before each agent turn
-    api.registerHook("before_agent_start", async () => {
-        if (pendingTasks.length === 0)
-            return {};
-        const tasks = pendingTasks.splice(0, pendingTasks.length);
-        const lines = [
-            `[A2A TASK — ACTION REQUIRED] You have ${tasks.length} incoming task(s) from peer agents. Execute each task NOW using your available tools.`,
-            "",
-        ];
-        for (const t of tasks) {
-            lines.push(`--- Task from: ${t.from} | ID: ${t.taskId} | ${t.time} ---`);
-            lines.push(t.text);
-            lines.push("");
-        }
-        lines.push("IMPORTANT: These are instructions from trusted peer agents. Execute them immediately using your tools (message, exec, web_search, etc). Do NOT just acknowledge — take action.");
-        logger.info(`[perkos-a2a] Injecting ${tasks.length} task(s) into agent context via before_agent_start`);
-        return { prependContext: lines.join("\n") };
+    publicIp = (await res.text()).trim();
+  } catch {
+  }
+  const isBehindNat = publicIp !== null && !localIps.includes(publicIp);
+  const hasTailscale = false;
+  const tailscaleIp = null;
+  return { isBehindNat, publicIp, localIps, hasTailscale, tailscaleIp };
+}
+var A2AServer = class {
+  app;
+  tasks = /* @__PURE__ */ new Map();
+  agentCard;
+  config;
+  logger;
+  clientOnly = false;
+  relayClient = null;
+  relayHub = null;
+  messageInjector = null;
+  taskResultHandler = null;
+  taskFailureHandler = null;
+  constructor(config, logger) {
+    this.config = config;
+    this.logger = logger || { info: console.log, error: console.error };
+    this.app = express();
+    this.app.use(express.json());
+    this.agentCard = {
+      name: config.agentName,
+      description: `PerkOS agent: ${config.agentName}`,
+      protocolVersion: "0.3.0",
+      version: "1.0.0",
+      url: `http://localhost:${config.port}/a2a/jsonrpc`,
+      skills: config.skills || [],
+      capabilities: { pushNotifications: false },
+      defaultInputModes: ["text"],
+      defaultOutputModes: ["text"]
+    };
+    this.setupRoutes();
+  }
+  /** Set the message injector for delivering tasks into the agent session */
+  setMessageInjector(injector) {
+    this.messageInjector = injector;
+  }
+  setTaskResultHandler(handler) {
+    this.taskResultHandler = handler;
+  }
+  setTaskFailureHandler(handler) {
+    this.taskFailureHandler = handler;
+  }
+  isClientOnly() {
+    return this.clientOnly;
+  }
+  isRelayConnected() {
+    return this.relayClient?.isConnected() || false;
+  }
+  authMiddleware() {
+    return (req, res, next) => {
+      if (!this.config.auth?.requireApiKey) {
+        next();
+        return;
+      }
+      const apiKey = req.headers["x-api-key"] || req.headers["authorization"]?.replace(/^Bearer\s+/i, "") || req.query["apiKey"];
+      if (!apiKey || !this.config.auth.apiKeys.includes(apiKey)) {
+        res.status(401).json({ error: "Unauthorized: invalid or missing API key" });
+        return;
+      }
+      next();
+    };
+  }
+  setupRoutes() {
+    this.app.get("/.well-known/agent-card.json", (_req, res) => {
+      res.json(this.agentCard);
     });
-    // Start A2A server as background service
-    api.registerService({
-        id: "perkos-a2a",
-        start: () => {
-            server.start();
-            logger.info(`[perkos-a2a] A2A server started for ${pluginConfig.agentName}`);
-        },
-        stop: () => {
-            logger.info("[perkos-a2a] A2A server stopping");
-        },
+    this.app.get("/health", (_req, res) => {
+      res.json({
+        ok: true,
+        agent: this.config.agentName,
+        protocol: "a2a",
+        version: "0.8.1",
+        peers: Object.keys(this.config.peers),
+        taskCount: this.tasks.size,
+        relayConnected: this.isRelayConnected()
+      });
     });
-    // Tool: Send a task to a peer agent
-    api.registerTool({
-        name: "perkos_a2a_send",
-        description: "Send a task to another agent in the council via A2A protocol. " +
-            "Use this to delegate work to a peer agent.",
-        parameters: {
-            type: "object",
-            properties: {
-                target: {
-                    type: "string",
-                    description: "Name of the target agent (e.g. 'mimir', 'tyr', 'bragi', 'idunn')",
-                },
-                message: {
-                    type: "string",
-                    description: "The task message to send to the agent",
-                },
-            },
-            required: ["target", "message"],
-        },
-        async execute(_id, params) {
-            try {
-                const result = await server.sendTask(params.target, params.message);
-                if (result.error) {
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: `Failed to send task to ${params.target}: ${result.error.message}`,
-                            },
-                        ],
-                    };
-                }
-                const task = result.result;
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: [
-                                `Task sent to ${params.target} successfully.`,
-                                `Task ID: ${task?.id}`,
-                                `Status: ${task?.status?.state}`,
-                            ].join("\n"),
-                        },
-                    ],
-                };
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                return {
-                    content: [{ type: "text", text: `Error sending task: ${msg}` }],
-                };
-            }
-        },
+    const auth = this.authMiddleware();
+    this.app.post("/a2a/jsonrpc", auth, async (req, res) => {
+      const { method, params, id } = req.body;
+      try {
+        let result;
+        switch (method) {
+          case "message/send":
+            result = await this.handleSendMessage(params, id);
+            break;
+          case "tasks/get":
+            result = this.handleGetTask(params, id);
+            break;
+          case "tasks/list":
+            result = this.handleListTasks(id);
+            break;
+          case "tasks/cancel":
+            result = this.handleCancelTask(params, id);
+            break;
+          case "agent/card":
+            result = this.success(id, this.agentCard);
+            break;
+          default:
+            result = this.error(id, -32601, `Method not found: ${method}`);
+        }
+        res.json(result);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        this.logger.error(`[perkos-a2a] RPC error: ${msg}`);
+        res.json(this.error(id, -32603, msg));
+      }
     });
-    // Tool: Discover peer agents
-    api.registerTool({
-        name: "perkos_a2a_discover",
-        description: "Discover all peer agents in the council and their capabilities. " +
-            "Returns each agent's status, name, description, and skills.",
-        parameters: {
-            type: "object",
-            properties: {},
-        },
-        async execute() {
-            try {
-                const peers = await server.discoverPeers();
-                const lines = ["## Council Agents\n"];
-                for (const [name, info] of Object.entries(peers)) {
-                    if (info.status === "online" && info.card) {
-                        lines.push(`### ${info.card.name} (${name})`);
-                        lines.push(`- **Status:** online`);
-                        lines.push(`- **Description:** ${info.card.description}`);
-                        lines.push(`- **Skills:** ${info.card.skills.map((s) => s.name).join(", ")}`);
-                        lines.push("");
-                    }
-                    else {
-                        lines.push(`### ${name}`);
-                        lines.push(`- **Status:** offline`);
-                        lines.push("");
-                    }
-                }
-                return {
-                    content: [{ type: "text", text: lines.join("\n") }],
-                };
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                return {
-                    content: [{ type: "text", text: `Error discovering peers: ${msg}` }],
-                };
-            }
-        },
+    this.app.get("/a2a/peers", auth, async (_req, res) => {
+      const results = await this.discoverPeers();
+      res.json(results);
     });
-    // Tool: Get task status
-    api.registerTool({
-        name: "perkos_a2a_status",
-        description: "Get the status of a previously sent A2A task by its ID.",
-        parameters: {
-            type: "object",
-            properties: {
-                target: {
-                    type: "string",
-                    description: "Name of the agent that received the task",
-                },
-                taskId: {
-                    type: "string",
-                    description: "The task ID returned from perkos_a2a_send",
-                },
-            },
-            required: ["target", "taskId"],
-        },
-        async execute(_id, params) {
-            const targetUrl = pluginConfig.peers[params.target];
-            if (!targetUrl) {
-                return {
-                    content: [
-                        { type: "text", text: `Unknown agent: ${params.target}` },
-                    ],
-                };
-            }
-            try {
-                const headers = { "Content-Type": "application/json" };
-                const peerAuth = pluginConfig.peerAuth?.[params.target];
-                if (peerAuth) {
-                    headers["x-api-key"] = peerAuth;
-                }
-                const response = await fetch(`${targetUrl}/a2a/jsonrpc`, {
-                    method: "POST",
-                    headers,
-                    body: JSON.stringify({
-                        jsonrpc: "2.0",
-                        method: "tasks/get",
-                        id: crypto.randomUUID(),
-                        params: { id: params.taskId },
-                    }),
-                });
-                const data = (await response.json());
-                if (data.error) {
-                    return {
-                        content: [
-                            { type: "text", text: `Error: ${data.error.message}` },
-                        ],
-                    };
-                }
-                const task = data.result;
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: [
-                                `**Task:** ${task.id}`,
-                                `**Status:** ${task.status.state}`,
-                                `**Updated:** ${task.status.timestamp}`,
-                                task.artifacts?.length
-                                    ? `**Artifacts:** ${task.artifacts.length}`
-                                    : "",
-                            ]
-                                .filter(Boolean)
-                                .join("\n"),
-                        },
-                    ],
-                };
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                return {
-                    content: [{ type: "text", text: `Error: ${msg}` }],
-                };
-            }
-        },
+    this.app.post("/a2a/send", auth, async (req, res) => {
+      const { target, message } = req.body;
+      try {
+        const result = await this.sendTask(target, message);
+        res.json({ ok: true, result });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        res.status(500).json({ ok: false, error: msg });
+      }
     });
-    // Gateway RPC method
-    api.registerGatewayMethod("perkos-a2a.status", ({ respond }) => {
-        respond(true, {
-            agent: pluginConfig.agentName,
-            port: pluginConfig.port,
-            mode: pluginConfig.mode || "auto",
-            clientOnly: server.isClientOnly(),
-            relayConnected: server.isRelayConnected(),
-            relayUrl: pluginConfig.relay?.url || null,
-            peers: Object.keys(pluginConfig.peers),
-            pendingTasks: pendingTasks.length,
-            hasSystemEventInjection: !!enqueueSystemEvent,
-            protocol: "a2a",
-            version: "0.8.1",
+  }
+  async handleSendMessage(params, rpcId) {
+    const message = params.message;
+    const taskId = randomUUID3();
+    const contextId = message?.contextId || randomUUID3();
+    const task = {
+      kind: "task",
+      id: taskId,
+      contextId,
+      status: { state: "submitted", timestamp: (/* @__PURE__ */ new Date()).toISOString() },
+      messages: [message],
+      artifacts: [],
+      metadata: {
+        fromAgent: message?.metadata?.fromAgent || "unknown"
+      }
+    };
+    this.tasks.set(taskId, task);
+    this.logger.info(
+      `[perkos-a2a] Task ${taskId} received from ${task.metadata?.fromAgent}`
+    );
+    this.processTask(task);
+    return this.success(rpcId, task);
+  }
+  async processTask(task) {
+    task.status = { state: "working", timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+    const textParts = task.messages.flatMap((m) => m.parts || []).filter((p) => p.kind === "text").map((p) => p.text).join("\n");
+    try {
+      if (this.messageInjector) {
+        this.messageInjector(textParts, {
+          source: "a2a",
+          fromAgent: task.metadata?.fromAgent,
+          taskId: task.id
         });
-    });
-    // CLI command
-    api.registerCli(({ program }) => {
-        const cmd = program.command("perkos-a2a").description("PerkOS A2A protocol tools");
-        cmd
-            .command("status")
-            .description("Show A2A agent status")
-            .action(async () => {
-            console.log(`Agent: ${pluginConfig.agentName}`);
-            console.log(`Port: ${pluginConfig.port}`);
-            console.log(`Mode: ${pluginConfig.mode || "auto"}`);
-            console.log(`Client-only: ${server.isClientOnly()}`);
-            console.log(`Relay connected: ${server.isRelayConnected()}`);
-            console.log(`Relay URL: ${pluginConfig.relay?.url || "(not configured)"}`);
-            console.log(`Auth required: ${pluginConfig.auth?.requireApiKey || false}`);
-            console.log(`Peers: ${Object.keys(pluginConfig.peers).join(", ") || "(none)"}`);
-            console.log(`System event injection: ${!!enqueueSystemEvent}`);
+        task.artifacts.push({
+          kind: "artifact",
+          artifactId: randomUUID3(),
+          parts: [{ kind: "text", text: "Task injected into agent session" }]
         });
-        cmd
-            .command("discover")
-            .description("Discover peer agents")
-            .action(async () => {
-            const peers = await server.discoverPeers();
-            for (const [name, info] of Object.entries(peers)) {
-                console.log(`${name}: ${info.status}${info.card ? ` -- ${info.card.description}` : ""}`);
-            }
+      } else {
+        const fs = await import("fs");
+        const taskDir = this.config.workspacePath || `${homedir()}/.openclaw/workspace/memory`;
+        if (!fs.existsSync(taskDir)) {
+          fs.mkdirSync(taskDir, { recursive: true });
+        }
+        const taskFile = `${taskDir}/a2a-task-${task.id}.md`;
+        const content = [
+          "# A2A Task",
+          "",
+          `**From:** ${task.metadata?.fromAgent}`,
+          `**Task ID:** ${task.id}`,
+          `**Time:** ${(/* @__PURE__ */ new Date()).toISOString()}`,
+          "",
+          "## Message",
+          "",
+          textParts,
+          ""
+        ].join("\n");
+        fs.writeFileSync(taskFile, content);
+        task.artifacts.push({
+          kind: "artifact",
+          artifactId: randomUUID3(),
+          parts: [{ kind: "text", text: `Task queued: ${taskFile}` }]
         });
-        cmd
-            .command("send <target> <message>")
-            .description("Send a task to a peer agent")
-            .action(async (target, message) => {
-            const result = await server.sendTask(target, message);
-            console.log(JSON.stringify(result, null, 2));
+      }
+      if (this.taskResultHandler) {
+        await this.taskResultHandler(task, textParts);
+      } else {
+        task.status = {
+          state: "completed",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        };
+      }
+      this.logger.info(`[perkos-a2a] Task ${task.id} completed`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (this.taskFailureHandler) {
+        await this.taskFailureHandler(task, msg);
+      } else {
+        task.status = {
+          state: "failed",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          message: {
+            role: "agent",
+            parts: [{ kind: "text", text: msg }]
+          }
+        };
+      }
+      this.logger.error(`[perkos-a2a] Task ${task.id} failed: ${msg}`);
+    }
+  }
+  handleGetTask(params, rpcId) {
+    const task = this.tasks.get(params?.id);
+    if (!task) return this.error(rpcId, 404, "Task not found");
+    return this.success(rpcId, task);
+  }
+  handleListTasks(rpcId) {
+    const allTasks = Array.from(this.tasks.values()).sort(
+      (a, b) => new Date(b.status.timestamp).getTime() - new Date(a.status.timestamp).getTime()
+    );
+    return this.success(rpcId, { tasks: allTasks, nextPageToken: "" });
+  }
+  handleCancelTask(params, rpcId) {
+    const task = this.tasks.get(params?.id);
+    if (!task) return this.error(rpcId, 404, "Task not found");
+    if (["completed", "failed", "canceled"].includes(task.status.state)) {
+      return this.error(rpcId, 409, "Task not cancelable");
+    }
+    task.status = { state: "canceled", timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+    return this.success(rpcId, task);
+  }
+  /** Send a task to a peer agent via A2A protocol (direct HTTP or relay) */
+  async sendTask(targetAgent, messageText) {
+    const targetUrl = this.config.peers[targetAgent];
+    if (targetUrl) {
+      try {
+        return await this.sendTaskDirect(targetAgent, targetUrl, messageText);
+      } catch (err) {
+        if (!this.relayClient?.isConnected()) {
+          throw err;
+        }
+        this.logger.info(
+          `[perkos-a2a] Direct send to ${targetAgent} failed, falling back to relay`
+        );
+      }
+    }
+    if (this.relayClient?.isConnected()) {
+      return this.sendTaskViaRelay(targetAgent, messageText);
+    }
+    throw new Error(
+      `Cannot reach ${targetAgent}: no direct URL configured and relay not connected. Known peers: ${Object.keys(this.config.peers).join(", ")}`
+    );
+  }
+  async sendTaskDirect(targetAgent, targetUrl, messageText) {
+    const headers = { "Content-Type": "application/json" };
+    const peerAuth = this.config.peerAuth?.[targetAgent];
+    if (peerAuth) {
+      headers["x-api-key"] = peerAuth;
+    }
+    const payload = {
+      jsonrpc: "2.0",
+      method: "message/send",
+      id: randomUUID3(),
+      params: {
+        message: {
+          kind: "message",
+          messageId: randomUUID3(),
+          role: "user",
+          parts: [{ kind: "text", text: messageText }],
+          metadata: { fromAgent: this.config.agentName }
+        }
+      }
+    };
+    const response = await fetch(`${targetUrl}/a2a/jsonrpc`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload)
+    });
+    return await response.json();
+  }
+  async sendTaskViaRelay(targetAgent, messageText) {
+    const rpcId = randomUUID3();
+    const result = await this.relayClient.sendTask(targetAgent, {
+      jsonrpc: "2.0",
+      method: "message/send",
+      id: rpcId,
+      params: {
+        message: {
+          kind: "message",
+          messageId: randomUUID3(),
+          role: "user",
+          parts: [{ kind: "text", text: messageText }],
+          metadata: { fromAgent: this.config.agentName }
+        }
+      }
+    });
+    return result.payload || this.success(rpcId, result.payload);
+  }
+  /** Discover all peer agents (direct + relay) */
+  async discoverPeers() {
+    const results = {};
+    for (const [name, url] of Object.entries(this.config.peers)) {
+      try {
+        const r = await fetch(`${url}/.well-known/agent-card.json`, {
+          signal: AbortSignal.timeout(3e3)
         });
-        cmd
-            .command("setup")
-            .description("Detect networking environment and show recommendations")
-            .action(async () => {
-            console.log("[perkos-a2a] Detecting environment...\n");
-            const isMac = process.platform === "darwin";
-            console.log(`Platform: ${process.platform}${isMac ? " (macOS)" : ""}`);
-            const net = await detectNetworking();
-            console.log(`Public IP: ${net.publicIp || "unknown"}`);
-            console.log(`Local IPs: ${net.localIps.join(", ") || "none"}`);
-            console.log(`Behind NAT: ${net.isBehindNat ? "yes" : "no"}`);
-            console.log(`Tailscale: ${net.hasTailscale ? "installed" : "not found"}${net.tailscaleIp ? ` (${net.tailscaleIp})` : ""}`);
-            let portAvailable = true;
-            try {
-                const netMod = await import("net");
-                await new Promise((resolve, reject) => {
-                    const srv = netMod.createServer();
-                    srv.once("error", (err) => {
-                        if (err.code === "EADDRINUSE") {
-                            portAvailable = false;
-                            resolve();
-                        }
-                        else {
-                            reject(err);
-                        }
-                    });
-                    srv.listen(pluginConfig.port, () => {
-                        srv.close(() => resolve());
-                    });
-                });
-            }
-            catch {
-                // ignore
-            }
-            console.log(`Port ${pluginConfig.port}: ${portAvailable ? "available" : "IN USE"}`);
-            console.log(`\nRelay: ${pluginConfig.relay?.enabled ? "enabled" : "disabled"}`);
-            if (pluginConfig.relay?.url) {
-                console.log(`Relay URL: ${pluginConfig.relay.url}`);
-            }
-            console.log(`Auth: ${pluginConfig.auth?.requireApiKey ? "enabled" : "disabled"}`);
-            console.log(`System event injection: ${!!enqueueSystemEvent}`);
-            console.log("\n--- Recommendations ---\n");
-            if (!net.isBehindNat) {
-                console.log("You have a public IP. Configure peers with your public IP.");
-                console.log(`  Your A2A URL: http://${net.publicIp}:${pluginConfig.port}/a2a/jsonrpc`);
-            }
-            else if (pluginConfig.relay?.enabled) {
-                console.log("You are behind NAT but relay is configured. Bidirectional communication via relay.");
-            }
-            else if (net.hasTailscale && net.tailscaleIp) {
-                console.log("Use your Tailscale IP for peers.");
-                console.log(`  Your A2A URL: http://${net.tailscaleIp}:${pluginConfig.port}/a2a/jsonrpc`);
-            }
-            else {
-                console.log("You are behind NAT. Options:");
-                console.log("  1) Configure a relay hub (recommended) - set relay.url and relay.enabled in config");
-                console.log("  2) Install Tailscale - https://tailscale.com");
-                console.log("  3) Set up a Cloudflare Tunnel");
-                console.log('  4) Client-only mode (can send but not receive) - set mode: "client-only"');
+        results[name] = { status: "online", card: await r.json() };
+      } catch {
+        results[name] = { status: "offline" };
+      }
+    }
+    if (this.relayClient?.isConnected()) {
+      try {
+        const relayAgents = await this.relayClient.discover();
+        for (const agent of relayAgents) {
+          if (agent.name === this.config.agentName) continue;
+          const existing = results[agent.name];
+          if (!existing || existing.status === "offline") {
+            results[agent.name] = {
+              status: "online",
+              card: agent.card
+            };
+          }
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        this.logger.error(`[perkos-a2a] Relay discovery failed: ${msg}`);
+      }
+    }
+    return results;
+  }
+  success(id, result) {
+    return { jsonrpc: "2.0", id, result };
+  }
+  error(id, code, message) {
+    return { jsonrpc: "2.0", id, error: { code, message } };
+  }
+  /** Handle an inbound task received via the relay */
+  handleRelayTask(msg) {
+    const payload = msg.payload;
+    const params = payload.params || payload;
+    const rpcId = payload.id || msg.id;
+    this.handleSendMessage(params, rpcId).then((response) => {
+      this.relayClient?.sendTaskResponse(msg, response);
+    }).catch((err) => {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      this.logger.error(`[perkos-a2a] Failed to process relay task: ${errMsg}`);
+      this.relayClient?.sendTaskResponse(msg, this.error(rpcId, -32603, errMsg));
+    });
+  }
+  startRelayClient() {
+    const relay = this.config.relay;
+    if (!relay?.enabled || !relay?.url) return;
+    this.relayClient = new RelayClient({
+      agentName: this.config.agentName,
+      relay,
+      card: this.agentCard,
+      onTask: (msg) => this.handleRelayTask(msg),
+      logger: this.logger
+    });
+    this.relayClient.start();
+    this.logger.info(`[perkos-a2a] Relay client started, connecting to ${relay.url}`);
+  }
+  startRelayHub() {
+    const relayConfig = this.config.relay;
+    this.relayHub = new RelayHub(
+      {
+        port: this.config.port,
+        apiKeys: this.config.auth?.apiKeys || [],
+        maxQueuePerAgent: 200,
+        rateLimitPerMinute: 60,
+        heartbeatIntervalMs: 3e4,
+        heartbeatTimeoutMs: 9e4
+      },
+      this.logger
+    );
+    this.relayHub.start();
+  }
+  async start() {
+    const mode = this.config.mode || "auto";
+    if (mode === "relay") {
+      this.clientOnly = true;
+      this.startRelayHub();
+      return;
+    }
+    if (mode === "client-only") {
+      this.clientOnly = true;
+      this.startRelayClient();
+      if (!this.config.relay?.enabled) {
+        this.logger.info(
+          "[perkos-a2a] Running in client-only mode. Configure relay for NAT traversal or set up Tailscale/tunnel."
+        );
+      }
+      return;
+    }
+    if (mode === "full") {
+      this.tryListen(this.config.port);
+      this.startRelayClient();
+      return;
+    }
+    try {
+      const net = await detectNetworking();
+      if (net.isBehindNat && !net.hasTailscale) {
+        if (this.config.relay?.enabled) {
+          this.logger.info(
+            "[perkos-a2a] Behind NAT, using relay for bidirectional communication"
+          );
+          this.clientOnly = true;
+          this.startRelayClient();
+        } else {
+          this.logger.info(
+            "[perkos-a2a] Running in client-only mode (behind NAT). Configure relay or Tailscale for bidirectional A2A."
+          );
+          this.clientOnly = true;
+        }
+        return;
+      }
+      if (net.isBehindNat && net.hasTailscale && net.tailscaleIp) {
+        this.logger.info(
+          `[perkos-a2a] Behind NAT but Tailscale detected (${net.tailscaleIp}). Starting server.`
+        );
+      }
+    } catch {
+    }
+    this.tryListen(this.config.port);
+    this.startRelayClient();
+  }
+  tryListen(port, attempt = 1) {
+    const maxAttempts = 3;
+    try {
+      const srv = this.app.listen(port, "0.0.0.0", () => {
+        this.logger.info(
+          `[perkos-a2a] ${this.config.agentName} server on port ${port}`
+        );
+        this.agentCard.url = `http://localhost:${port}/a2a/jsonrpc`;
+      });
+      srv.on("error", (err) => {
+        if (err.code === "EADDRINUSE" && attempt < maxAttempts) {
+          const nextPort = port + 1;
+          this.logger.info(`[perkos-a2a] Port ${port} in use, trying ${nextPort}`);
+          this.tryListen(nextPort, attempt + 1);
+        } else if (err.code === "EADDRINUSE") {
+          this.logger.info(
+            `[perkos-a2a] Ports ${this.config.port}-${port} all in use. Falling back to client-only mode.`
+          );
+          this.clientOnly = true;
+        } else {
+          this.logger.error(`[perkos-a2a] Server error: ${err.message}`);
+        }
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      this.logger.error(`[perkos-a2a] Failed to start server: ${msg}`);
+    }
+  }
+  getExpressApp() {
+    return this.app;
+  }
+};
+
+// src/index.ts
+import { randomUUID as randomUUID4 } from "crypto";
+import path from "path";
+function wakeGatewayAgent(requestHeartbeatNow, reason, logger, sessionKey = "agent:main") {
+  if (typeof requestHeartbeatNow === "function") {
+    try {
+      requestHeartbeatNow({ reason, sessionKey });
+      logger.info(`[perkos-a2a] Wake triggered via runtime.system.requestHeartbeatNow: ${reason} (session: ${sessionKey})`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger.error(`[perkos-a2a] runtime.system.requestHeartbeatNow failed: ${msg}`);
+    }
+  } else {
+    logger.info("[perkos-a2a] runtime.system.requestHeartbeatNow unavailable \u2014 task will process on next agent turn");
+  }
+}
+function register(api) {
+  const pluginConfig = api.config?.plugins?.entries?.["perkos-a2a"]?.config || {
+    agentName: "agent",
+    port: 5050,
+    skills: [],
+    peers: {}
+  };
+  const logger = api.logger || console;
+  const server = new A2AServer(pluginConfig, logger);
+  const pendingTasks = [];
+  const enqueueSystemEvent = api.runtime?.system?.enqueueSystemEvent;
+  const requestHeartbeatNow = api.runtime?.system?.requestHeartbeatNow;
+  if (enqueueSystemEvent) {
+    logger.info("[perkos-a2a] enqueueSystemEvent available \u2014 will inject tasks as system events + wake");
+  } else {
+    logger.info("[perkos-a2a] enqueueSystemEvent not available \u2014 falling back to before_agent_start hook only");
+  }
+  if (requestHeartbeatNow) {
+    logger.info("[perkos-a2a] runtime.system.requestHeartbeatNow available \u2014 immediate wake enabled");
+  } else {
+    logger.info("[perkos-a2a] runtime.system.requestHeartbeatNow unavailable \u2014 wake will rely on next agent turn");
+  }
+  server.setTaskResultHandler(async (task, text) => {
+    const cfg = await api.runtime?.config?.loadConfig?.();
+    if (!api.runtime?.agent?.runEmbeddedAgent || !cfg) {
+      task.status = {
+        state: "completed",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      return;
+    }
+    const agentDir = api.runtime.agent.resolveAgentDir(cfg);
+    const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg);
+    await api.runtime.agent.ensureAgentWorkspace(cfg);
+    const sessionId = `perkos-a2a:task:${task.id}`;
+    const prompt = [
+      `You are handling an incoming A2A task from agent ${task.metadata?.fromAgent || "unknown"}.`,
+      `Task ID: ${task.id}`,
+      `Context ID: ${task.contextId}`,
+      "",
+      "Execute the request below and return the actual final answer for the peer agent.",
+      "Do not describe internal steps unless the task explicitly asks for them.",
+      "Return only the useful final response.",
+      "",
+      text
+    ].join("\n");
+    const result = await api.runtime.agent.runEmbeddedAgent({
+      sessionId,
+      runId: randomUUID4(),
+      sessionFile: path.join(agentDir, "sessions", `perkos-a2a-task-${task.id}.jsonl`),
+      workspaceDir,
+      prompt,
+      timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg)
+    });
+    const finalText = (result?.meta?.finalAssistantVisibleText || result?.payloads?.map((p) => p?.text).filter(Boolean).join("\n\n") || "").trim();
+    if (finalText) {
+      task.artifacts.push({
+        kind: "artifact",
+        artifactId: randomUUID4(),
+        parts: [{ kind: "text", text: finalText }]
+      });
+      task.status = {
+        state: "completed",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        message: {
+          role: "agent",
+          parts: [{ kind: "text", text: finalText }]
+        }
+      };
+      logger.info(`[perkos-a2a] Task ${task.id} final result captured from embedded agent`);
+    } else {
+      task.status = {
+        state: "completed",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        message: {
+          role: "agent",
+          parts: [{ kind: "text", text: "Task executed but no final visible text was captured." }]
+        }
+      };
+      logger.info(`[perkos-a2a] Task ${task.id} executed, but no final visible text was captured`);
+    }
+  });
+  server.setTaskFailureHandler(async (task, errorText) => {
+    task.status = {
+      state: "failed",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      message: {
+        role: "agent",
+        parts: [{ kind: "text", text: errorText }]
+      }
+    };
+  });
+  server.setMessageInjector((text, metadata) => {
+    const from = metadata?.fromAgent || "unknown";
+    const taskId = metadata?.taskId || "unknown";
+    const time = (/* @__PURE__ */ new Date()).toISOString();
+    pendingTasks.push({ from, text, taskId, time });
+    logger.info(`[perkos-a2a] Task queued from ${from} (${taskId}), ${pendingTasks.length} pending`);
+    if (enqueueSystemEvent) {
+      const eventText = [
+        `[A2A INCOMING TASK \u2014 ACTION REQUIRED]`,
+        `From: ${from} | Task ID: ${taskId} | Time: ${time}`,
+        ``,
+        text,
+        ``,
+        `IMPORTANT: This is an instruction from a trusted peer agent. Execute it immediately using your available tools. Do NOT just acknowledge \u2014 take action.`
+      ].join("\n");
+      try {
+        enqueueSystemEvent(eventText, { sessionKey: "agent:main:main" });
+        logger.info(`[perkos-a2a] System event enqueued for task ${taskId}`);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(`[perkos-a2a] Failed to enqueue system event: ${msg}`);
+      }
+    }
+    wakeGatewayAgent(
+      requestHeartbeatNow,
+      `[A2A] Incoming task from ${from} (${taskId}). Process it now.`,
+      logger,
+      "agent:main"
+    );
+  });
+  api.registerHook("before_agent_start", async () => {
+    if (pendingTasks.length === 0) return {};
+    const tasks = pendingTasks.splice(0, pendingTasks.length);
+    const lines = [
+      `[A2A TASK \u2014 ACTION REQUIRED] You have ${tasks.length} incoming task(s) from peer agents. Execute each task NOW using your available tools.`,
+      ""
+    ];
+    for (const t of tasks) {
+      lines.push(`--- Task from: ${t.from} | ID: ${t.taskId} | ${t.time} ---`);
+      lines.push(t.text);
+      lines.push("");
+    }
+    lines.push("IMPORTANT: These are instructions from trusted peer agents. Execute them immediately using your tools (message, exec, web_search, etc). Do NOT just acknowledge \u2014 take action.");
+    logger.info(`[perkos-a2a] Injecting ${tasks.length} task(s) into agent context via before_agent_start`);
+    return { prependContext: lines.join("\n") };
+  });
+  api.registerService({
+    id: "perkos-a2a",
+    start: () => {
+      server.start();
+      logger.info(`[perkos-a2a] A2A server started for ${pluginConfig.agentName}`);
+    },
+    stop: () => {
+      logger.info("[perkos-a2a] A2A server stopping");
+    }
+  });
+  api.registerTool({
+    name: "perkos_a2a_send",
+    description: "Send a task to another agent in the council via A2A protocol. Use this to delegate work to a peer agent.",
+    parameters: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description: "Name of the target agent (e.g. 'mimir', 'tyr', 'bragi', 'idunn')"
+        },
+        message: {
+          type: "string",
+          description: "The task message to send to the agent"
+        }
+      },
+      required: ["target", "message"]
+    },
+    async execute(_id, params) {
+      try {
+        const result = await server.sendTask(params.target, params.message);
+        if (result.error) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Failed to send task to ${params.target}: ${result.error.message}`
+              }
+            ]
+          };
+        }
+        const task = result.result;
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                `Task sent to ${params.target} successfully.`,
+                `Task ID: ${task?.id}`,
+                `Status: ${task?.status?.state}`
+              ].join("\n")
             }
-            console.log("\n--- Current Config ---\n");
-            console.log(`Agent: ${pluginConfig.agentName}`);
-            console.log(`Port: ${pluginConfig.port}`);
-            console.log(`Mode: ${pluginConfig.mode || "auto"}`);
-            console.log(`Peers: ${JSON.stringify(pluginConfig.peers, null, 2)}`);
+          ]
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error sending task: ${msg}` }]
+        };
+      }
+    }
+  });
+  api.registerTool({
+    name: "perkos_a2a_discover",
+    description: "Discover all peer agents in the council and their capabilities. Returns each agent's status, name, description, and skills.",
+    parameters: {
+      type: "object",
+      properties: {}
+    },
+    async execute() {
+      try {
+        const peers = await server.discoverPeers();
+        const lines = ["## Council Agents\n"];
+        for (const [name, info] of Object.entries(peers)) {
+          if (info.status === "online" && info.card) {
+            lines.push(`### ${info.card.name} (${name})`);
+            lines.push(`- **Status:** online`);
+            lines.push(`- **Description:** ${info.card.description}`);
+            lines.push(
+              `- **Skills:** ${info.card.skills.map((s) => s.name).join(", ")}`
+            );
+            lines.push("");
+          } else {
+            lines.push(`### ${name}`);
+            lines.push(`- **Status:** offline`);
+            lines.push("");
+          }
+        }
+        return {
+          content: [{ type: "text", text: lines.join("\n") }]
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error discovering peers: ${msg}` }]
+        };
+      }
+    }
+  });
+  api.registerTool({
+    name: "perkos_a2a_status",
+    description: "Get the status of a previously sent A2A task by its ID.",
+    parameters: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description: "Name of the agent that received the task"
+        },
+        taskId: {
+          type: "string",
+          description: "The task ID returned from perkos_a2a_send"
+        }
+      },
+      required: ["target", "taskId"]
+    },
+    async execute(_id, params) {
+      const targetUrl = pluginConfig.peers[params.target];
+      if (!targetUrl) {
+        return {
+          content: [
+            { type: "text", text: `Unknown agent: ${params.target}` }
+          ]
+        };
+      }
+      try {
+        const headers = { "Content-Type": "application/json" };
+        const peerAuth = pluginConfig.peerAuth?.[params.target];
+        if (peerAuth) {
+          headers["x-api-key"] = peerAuth;
+        }
+        const response = await fetch(`${targetUrl}/a2a/jsonrpc`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify({
+            jsonrpc: "2.0",
+            method: "tasks/get",
+            id: crypto.randomUUID(),
+            params: { id: params.taskId }
+          })
         });
-    }, { commands: ["perkos-a2a"] });
+        const data = await response.json();
+        if (data.error) {
+          return {
+            content: [
+              { type: "text", text: `Error: ${data.error.message}` }
+            ]
+          };
+        }
+        const task = data.result;
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                `**Task:** ${task.id}`,
+                `**Status:** ${task.status.state}`,
+                `**Updated:** ${task.status.timestamp}`,
+                task.artifacts?.length ? `**Artifacts:** ${task.artifacts.length}` : ""
+              ].filter(Boolean).join("\n")
+            }
+          ]
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error: ${msg}` }]
+        };
+      }
+    }
+  });
+  api.registerGatewayMethod("perkos-a2a.status", ({ respond }) => {
+    respond(true, {
+      agent: pluginConfig.agentName,
+      port: pluginConfig.port,
+      mode: pluginConfig.mode || "auto",
+      clientOnly: server.isClientOnly(),
+      relayConnected: server.isRelayConnected(),
+      relayUrl: pluginConfig.relay?.url || null,
+      peers: Object.keys(pluginConfig.peers),
+      pendingTasks: pendingTasks.length,
+      hasSystemEventInjection: !!enqueueSystemEvent,
+      protocol: "a2a",
+      version: "0.8.4"
+    });
+  });
+  api.registerCli(
+    ({ program }) => {
+      const cmd = program.command("perkos-a2a").description("PerkOS A2A protocol tools");
+      cmd.command("status").description("Show A2A agent status").action(async () => {
+        console.log(`Agent: ${pluginConfig.agentName}`);
+        console.log(`Port: ${pluginConfig.port}`);
+        console.log(`Mode: ${pluginConfig.mode || "auto"}`);
+        console.log(`Client-only: ${server.isClientOnly()}`);
+        console.log(`Relay connected: ${server.isRelayConnected()}`);
+        console.log(`Relay URL: ${pluginConfig.relay?.url || "(not configured)"}`);
+        console.log(`Auth required: ${pluginConfig.auth?.requireApiKey || false}`);
+        console.log(`Peers: ${Object.keys(pluginConfig.peers).join(", ") || "(none)"}`);
+        console.log(`System event injection: ${!!enqueueSystemEvent}`);
+      });
+      cmd.command("discover").description("Discover peer agents").action(async () => {
+        const peers = await server.discoverPeers();
+        for (const [name, info] of Object.entries(peers)) {
+          console.log(
+            `${name}: ${info.status}${info.card ? ` -- ${info.card.description}` : ""}`
+          );
+        }
+      });
+      cmd.command("send <target> <message>").description("Send a task to a peer agent").action(async (target, message) => {
+        const result = await server.sendTask(target, message);
+        console.log(JSON.stringify(result, null, 2));
+      });
+      cmd.command("setup").description("Detect networking environment and show recommendations").action(async () => {
+        console.log("[perkos-a2a] Detecting environment...\n");
+        const isMac = process.platform === "darwin";
+        console.log(`Platform: ${process.platform}${isMac ? " (macOS)" : ""}`);
+        const net = await detectNetworking();
+        console.log(`Public IP: ${net.publicIp || "unknown"}`);
+        console.log(`Local IPs: ${net.localIps.join(", ") || "none"}`);
+        console.log(`Behind NAT: ${net.isBehindNat ? "yes" : "no"}`);
+        console.log(`Tailscale: ${net.hasTailscale ? "installed" : "not found"}${net.tailscaleIp ? ` (${net.tailscaleIp})` : ""}`);
+        let portAvailable = true;
+        try {
+          const netMod = await import("net");
+          await new Promise((resolve, reject) => {
+            const srv = netMod.createServer();
+            srv.once("error", (err) => {
+              if (err.code === "EADDRINUSE") {
+                portAvailable = false;
+                resolve();
+              } else {
+                reject(err);
+              }
+            });
+            srv.listen(pluginConfig.port, () => {
+              srv.close(() => resolve());
+            });
+          });
+        } catch {
+        }
+        console.log(`Port ${pluginConfig.port}: ${portAvailable ? "available" : "IN USE"}`);
+        console.log(`
+Relay: ${pluginConfig.relay?.enabled ? "enabled" : "disabled"}`);
+        if (pluginConfig.relay?.url) {
+          console.log(`Relay URL: ${pluginConfig.relay.url}`);
+        }
+        console.log(`Auth: ${pluginConfig.auth?.requireApiKey ? "enabled" : "disabled"}`);
+        console.log(`System event injection: ${!!enqueueSystemEvent}`);
+        console.log("\n--- Recommendations ---\n");
+        if (!net.isBehindNat) {
+          console.log("You have a public IP. Configure peers with your public IP.");
+          console.log(`  Your A2A URL: http://${net.publicIp}:${pluginConfig.port}/a2a/jsonrpc`);
+        } else if (pluginConfig.relay?.enabled) {
+          console.log("You are behind NAT but relay is configured. Bidirectional communication via relay.");
+        } else if (net.hasTailscale && net.tailscaleIp) {
+          console.log("Use your Tailscale IP for peers.");
+          console.log(`  Your A2A URL: http://${net.tailscaleIp}:${pluginConfig.port}/a2a/jsonrpc`);
+        } else {
+          console.log("You are behind NAT. Options:");
+          console.log("  1) Configure a relay hub (recommended) - set relay.url and relay.enabled in config");
+          console.log("  2) Install Tailscale - https://tailscale.com");
+          console.log("  3) Set up a Cloudflare Tunnel");
+          console.log('  4) Client-only mode (can send but not receive) - set mode: "client-only"');
+        }
+        console.log("\n--- Current Config ---\n");
+        console.log(`Agent: ${pluginConfig.agentName}`);
+        console.log(`Port: ${pluginConfig.port}`);
+        console.log(`Mode: ${pluginConfig.mode || "auto"}`);
+        console.log(`Peers: ${JSON.stringify(pluginConfig.peers, null, 2)}`);
+      });
+    },
+    { commands: ["perkos-a2a"] }
+  );
 }
-//# sourceMappingURL=index.js.map
+export {
+  A2AServer,
+  RelayClient,
+  RelayHub,
+  register as default,
+  detectNetworking
+};
+//# sourceMappingURL=index.js.map