@perkos/perkos-a2a 0.8.24 → 0.8.25

package/dist/index.js

@@ -27341,6 +27341,12 @@ var A2AServer = class {
 import { randomUUID as randomUUID5 } from "crypto";
 
 // src/agentic-actions.ts
+var FALLBACK_AGENT_ALIASES = [
+  ["Perkos-Claw-Tester", ["perkos-claw-tester", "openclaw", "open claw", "claw"]],
+  ["Perkos-Hermes-Tester", ["perkos-hermes-tester", "hermes"]],
+  ["Morpheus-A2A-Receiver", ["morpheus-a2a-receiver", "morpheus"]],
+  ["Apollo", ["apollo"]]
+];
 function includesAny(text, terms) {
   const lower = text.toLowerCase();
   return terms.some((term) => lower.includes(term.toLowerCase()));
@@ -27360,29 +27366,124 @@ function requestedMarker(text, fallback) {
 function stripDelegationNoise(text) {
   return text.replace(/^Delegated by .*?\.\s*/i, "").replace(/^Delegated request:\s*/i, "").replace(/^A2A-DELEGATION[^\n]*\n?/gim, "").replace(/End with DELEGATED_A2A_DONE\.?/gi, "").trim();
 }
-function detectTarget(text, selfName) {
-  const routingText = stripDelegationNoise(text);
-  const candidates = [
-    ["Perkos-Claw-Tester", ["perkos-claw-tester", "openclaw", "open claw", "claw"]],
-    ["Perkos-Hermes-Tester", ["perkos-hermes-tester", "hermes"]],
-    ["Morpheus-A2A-Receiver", ["morpheus-a2a-receiver", "morpheus"]]
-  ];
-  for (const [name, terms] of candidates) {
-    if (name === selfName) continue;
-    if (includesAny(routingText, terms)) return name;
+function normalizeKey(value) {
+  return value.toLowerCase().normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9]+/g, " ").trim().replace(/\s+/g, " ");
+}
+function compactKey(value) {
+  return normalizeKey(value).replace(/\s+/g, "");
+}
+function addAlias(aliases, alias, canonical) {
+  const normalized = normalizeKey(alias);
+  if (normalized) aliases.set(normalized, canonical);
+  const compact = compactKey(alias);
+  if (compact) aliases.set(compact, canonical);
+}
+function aliasesForName(name) {
+  const base = normalizeKey(name);
+  const compact = compactKey(name);
+  const withoutTester = base.replace(/\btester\b/g, "").replace(/\s+/g, " ").trim();
+  const parts = base.split(" ").filter(Boolean);
+  return Array.from(new Set([
+    name,
+    base,
+    compact,
+    withoutTester,
+    parts.at(-1) || "",
+    parts.at(0) || ""
+  ].filter(Boolean)));
+}
+async function buildAgentDirectory(server, selfName) {
+  const names = /* @__PURE__ */ new Set();
+  const aliases = /* @__PURE__ */ new Map();
+  names.add(selfName);
+  for (const [name, extraAliases] of FALLBACK_AGENT_ALIASES) {
+    names.add(name);
+    for (const alias of [name, ...extraAliases]) addAlias(aliases, alias, name);
+  }
+  if (server.discoverPeers) {
+    try {
+      const peers = await server.discoverPeers();
+      for (const [name, entry] of Object.entries(peers)) {
+        const canonical = entry.card?.name || name;
+        if (!canonical || canonical === selfName) continue;
+        names.add(canonical);
+        for (const alias of aliasesForName(canonical)) addAlias(aliases, alias, canonical);
+        if (name !== canonical) for (const alias of aliasesForName(name)) addAlias(aliases, alias, canonical);
+      }
+    } catch {
+    }
+  }
+  for (const name of names) for (const alias of aliasesForName(name)) addAlias(aliases, alias, name);
+  return { names: Array.from(names), aliases };
+}
+function resolveAgentName(raw, directory, selfName, allowSelf = false) {
+  const cleaned = raw.replace(/^@/, "").trim();
+  if (!cleaned) return void 0;
+  const normalized = normalizeKey(cleaned);
+  const compact = compactKey(cleaned);
+  for (const name of directory.names) {
+    if (!allowSelf && name === selfName) continue;
+    if (normalizeKey(name) === normalized || compactKey(name) === compact) return name;
+  }
+  const exact = directory.aliases.get(normalized) || directory.aliases.get(compact);
+  if (exact && (allowSelf || exact !== selfName)) return exact;
+  const entries = Array.from(directory.aliases.entries()).sort((a, b) => b[0].length - a[0].length);
+  for (const [alias, canonical] of entries) {
+    if (!allowSelf && canonical === selfName) continue;
+    if (alias.length < 4) continue;
+    if (normalized.includes(alias) || compact.includes(alias.replace(/\s+/g, ""))) return canonical;
   }
   return void 0;
 }
-function detectReplyTarget(text, selfName) {
-  const routingText = stripDelegationNoise(text);
-  if (selfName !== "Morpheus-A2A-Receiver" && includesAny(routingText, ["morpheus-a2a-receiver", "morpheus"])) {
-    return "Morpheus-A2A-Receiver";
+function findMentionedAgents(text, directory, selfName) {
+  const normalized = normalizeKey(stripDelegationNoise(text));
+  const compact = compactKey(stripDelegationNoise(text));
+  const hits = [];
+  const seen = /* @__PURE__ */ new Set();
+  const entries = Array.from(directory.aliases.entries()).sort((a, b) => b[0].length - a[0].length);
+  for (const [alias, canonical] of entries) {
+    if (canonical === selfName || alias.length < 3 || seen.has(canonical)) continue;
+    const idx = normalized.indexOf(alias);
+    const compactIdx = compact.indexOf(alias.replace(/\s+/g, ""));
+    const index = idx >= 0 ? idx : compactIdx;
+    if (index >= 0) {
+      hits.push({ name: canonical, index });
+      seen.add(canonical);
+    }
   }
-  if (selfName !== "Perkos-Claw-Tester" && includesAny(routingText, ["perkos-claw-tester", "openclaw", "open claw"])) {
-    return "Perkos-Claw-Tester";
+  return hits.sort((a, b) => a.index - b.index).map((hit) => hit.name);
+}
+function parseArrowRoute(text, directory, selfName) {
+  const clean = stripDelegationNoise(text);
+  const routeLine = clean.split(/\n/).find((line) => /(?:->|→|=>|➡)/.test(line));
+  if (!routeLine) return [];
+  const route = routeLine.split(/(?:->|→|=>|➡)/).map((part) => resolveAgentName(part, directory, selfName) || (normalizeKey(part).includes(normalizeKey(selfName)) ? selfName : void 0)).filter(Boolean);
+  return Array.from(new Set(route));
+}
+function detectTarget(text, selfName, directory) {
+  const route = parseDelegationEnvelope(text).route;
+  if (route.length) return nextRouteTarget(route, selfName);
+  const arrowRoute = parseArrowRoute(text, directory, selfName);
+  if (arrowRoute.length) return nextRouteTarget(arrowRoute, selfName) || arrowRoute.find((name) => name !== selfName);
+  return findMentionedAgents(text, directory, selfName)[0];
+}
+function detectReplyTarget(text, selfName, directory) {
+  const envelope = parseDelegationEnvelope(text);
+  if (envelope.notify && envelope.notify !== selfName) return envelope.notify;
+  const clean = stripDelegationNoise(text);
+  const patterns = [
+    /(?:reply|respond|notify|send|return|env[ií]a|enviar|responde|notifica)(?:\s+the\s+result)?\s+(?:to|a)\s+([A-Za-z0-9_. -]{2,80}?)(?:[.;,\n]|$)/i,
+    /(?:notify|notifica|reply|responde)\s+([A-Za-z0-9_. -]{2,80}?)(?:[.;,\n]|$)/i,
+    /(?:final|ultimo|último).*?(?:notify|notifica|responde|reply).*?(?:to|a)?\s+([A-Za-z0-9_. -]{2,80}?)(?:[.;,\n]|$)/i
+  ];
+  for (const pattern of patterns) {
+    const match = clean.match(pattern);
+    const resolved = match?.[1] ? resolveAgentName(match[1], directory, selfName, true) : void 0;
+    if (resolved) return resolved;
   }
-  if (selfName !== "Perkos-Hermes-Tester" && includesAny(routingText, ["perkos-hermes-tester", "hermes"])) {
-    return "Perkos-Hermes-Tester";
+  if (includesAny(clean, ["responda a", "env\xEDe", "envia", "send", "reply", "notify", "notifica", "morpheus"])) {
+    const mentioned = findMentionedAgents(clean, directory, selfName);
+    return mentioned.at(-1);
   }
   return void 0;
 }
@@ -27447,64 +27548,124 @@ function answerA2ARelay(selfName) {
     "It handles registration, discovery, message routing, heartbeats, and delivery fallback while each agent keeps its own runtime and local permissions."
   ].join("\n");
 }
+function parseDelegationEnvelope(text) {
+  const line = text.match(/^A2A-DELEGATION[^\n]*/im)?.[0] || "";
+  const routeRaw = line.match(/\broute=([^\s]+)/i)?.[1];
+  const notifyRaw = line.match(/\bnotify=([^\s]+)/i)?.[1];
+  const markerRaw = line.match(/\bmarker=([A-Z0-9_]{6,})/i)?.[1];
+  const depthRaw = line.match(/\bdepth=(\d+)/i)?.[1];
+  return {
+    route: routeRaw ? routeRaw.split(/[|,]/).map((x) => x.trim()).filter(Boolean) : [],
+    notify: notifyRaw && notifyRaw !== "none" ? notifyRaw : void 0,
+    marker: markerRaw,
+    depth: depthRaw ? Number(depthRaw) : 0
+  };
+}
 function delegationDepth(text) {
-  const match = text.match(/A2A-DELEGATION[^\n]*depth=(\d+)/i);
-  return match?.[1] ? Number(match[1]) : 0;
+  return parseDelegationEnvelope(text).depth;
+}
+function nextRouteTarget(route, selfName) {
+  const selfIndex = route.findIndex((name) => name === selfName);
+  if (selfIndex >= 0) return route.slice(selfIndex + 1).find((name) => name !== selfName);
+  return route.find((name) => name !== selfName);
 }
 function cleanNestedResult(text, finalMarker) {
   const escaped = finalMarker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return text.replace(new RegExp(`\\n?${escaped}\\s*$`, "g"), "").replace(/\n?DELEGATED_A2A_DONE\s*$/g, "").trim();
+  return text.replace(new RegExp(`
+?${escaped}s*$`, "g"), "").replace(/\n?DELEGATED_A2A_DONE\s*$/g, "").trim();
+}
+function routeForDelegation(selfName, target, text, directory) {
+  const envelopeRoute = parseDelegationEnvelope(text).route;
+  if (envelopeRoute.length) return Array.from(new Set(envelopeRoute));
+  const arrowRoute = parseArrowRoute(text, directory, selfName);
+  if (arrowRoute.length) return Array.from(new Set(arrowRoute.includes(selfName) ? arrowRoute : [selfName, ...arrowRoute]));
+  const mentions = findMentionedAgents(text, directory, selfName).filter((name) => name !== selfName);
+  const route = [selfName, target, ...mentions.filter((name) => name !== target)];
+  return Array.from(new Set(route));
 }
 function buildDelegatedMessage(input) {
-  const { originalText, selfName, target, marker } = input;
+  const { originalText, selfName, target, route, marker, notify } = input;
   const depth = delegationDepth(originalText) + 1;
   const clean = stripDelegationNoise(originalText);
-  const header = `A2A-DELEGATION origin=${selfName} target=${target} depth=${depth}`;
-  if (hasA2ARelayExplainTask(clean)) {
-    if (target === "Perkos-Hermes-Tester") {
-      return [
-        header,
-        "Complete this task directly. Briefly explain what an A2A relay is and why agents use it.",
-        "Do not delegate this request further unless explicitly required by a new instruction.",
-        "End with DELEGATED_A2A_DONE."
-      ].join("\n");
-    }
+  const header = `A2A-DELEGATION origin=${selfName} target=${target} route=${route.join("|")} notify=${notify || "none"} depth=${depth} marker=${marker}`;
+  if (hasA2ARelayExplainTask(clean) && !nextRouteTarget(route, target)) {
     return [
       header,
-      "Use A2A to ask Perkos-Hermes-Tester to briefly explain what an A2A relay is and why agents use it.",
-      "Return Hermes' useful result in your response.",
-      `End exactly with ${marker}.`
+      "Complete this task directly. Briefly explain what an A2A relay is and why agents use it.",
+      "Do not delegate this request further unless explicitly required by a new instruction.",
+      "End with DELEGATED_A2A_DONE."
     ].join("\n");
   }
   return [
     header,
-    "Complete or delegate the following task once. Do not echo this request back to agents already named in the route.",
+    "Complete or delegate the following task once. Follow the A2A-DELEGATION route exactly. Do not echo this request back to agents already named in the route.",
     clean,
+    notify ? `When the route is complete, send or return the final useful result to ${notify}.` : "Return the final useful result to the caller.",
     `End exactly with ${marker}.`
   ].join("\n");
 }
+async function completeTerminalTask(input) {
+  const { selfName, server, task, text, marker, replyTarget, runtimeResponder } = input;
+  const cleanText = stripDelegationNoise(text);
+  const wantsEthResearch = includesAny(cleanText, ["precio de eth", "eth price", "ethereum price", "precio actual de eth"]);
+  let finalText;
+  if (includesAny(cleanText, ["A2A_COMM_TEST", "communication test", "ping test"])) {
+    finalText = [`${selfName} received and completed the A2A communication test.`, marker].join("\n");
+  } else if (hasA2ARelayExplainTask(cleanText)) {
+    finalText = [answerA2ARelay(selfName), "", marker].join("\n");
+  } else if (wantsEthResearch) {
+    finalText = [await researchEthPrice(), "", marker].join("\n");
+  } else if (runtimeResponder) {
+    const reply = await runtimeResponder(cleanText, marker);
+    finalText = [reply, "", marker].join("\n");
+  } else {
+    finalText = [`${selfName} completed the delegated A2A task.`, cleanText, marker].join("\n");
+  }
+  if (replyTarget && replyTarget !== selfName) {
+    const replyResult = await server.sendTask(replyTarget, [
+      `Final A2A result from ${selfName}:`,
+      "",
+      cleanNestedResult(finalText, marker),
+      "",
+      "A2A_FINAL_NOTIFICATION_OK"
+    ].join("\n"));
+    finalText = [
+      cleanNestedResult(finalText, marker),
+      "",
+      `Forwarded final result to ${replyTarget}.`,
+      extractTaskFinalText(replyResult),
+      "",
+      marker
+    ].join("\n");
+  }
+  completeTaskWithReply(task, finalText);
+}
 async function tryHandleAgenticTask(input) {
-  const { selfName, server, task, text, logger } = input;
+  const { selfName, server, task, text, logger, runtimeResponder } = input;
+  const directory = await buildAgentDirectory(server, selfName);
+  const envelope = parseDelegationEnvelope(text);
   const cleanText = stripDelegationNoise(text);
-  const wantsDelegation = includesAny(cleanText, ["usa comunicaci\xF3n a2a", "usar comunicaci\xF3n a2a", "p\xEDdele", "dile a", "delegate", "delegar", "tell", "ask"]);
-  const wantsEthResearch = includesAny(text, ["precio de eth", "eth price", "ethereum price", "precio actual de eth"]);
-  const wantsReply = includesAny(text, ["responda a", "env\xEDe", "envia", "send", "reply", "morpheus"]);
-  if (includesAny(text, ["A2A_COMM_TEST", "communication test", "ping test"])) {
-    const marker = requestedMarker(text, "A2A_COMM_OK");
+  const wantsDelegation = includesAny(cleanText, ["usa comunicaci\xF3n a2a", "usar comunicaci\xF3n a2a", "p\xEDdele", "pidele", "dile a", "delegate", "delegar", "tell", "ask", "route", "chain", "handoff", "notify", "notifica"]);
+  const wantsEthResearch = includesAny(cleanText, ["precio de eth", "eth price", "ethereum price", "precio actual de eth"]);
+  const finalMarker = envelope.marker || requestedMarker(text, envelope.route.length ? "DELEGATED_A2A_DONE" : "TRI_HERMES_DONE");
+  if (/^(Final A2A result|Delegated result from|Research result from)\b/i.test(cleanText) && !envelope.route.length) {
+    completeTaskWithReply(task, [`${selfName} received the final A2A notification.`, "", cleanText, "", requestedMarker(text, "A2A_NOTIFICATION_RECEIVED")].join("\n"));
+    return true;
+  }
+  if (includesAny(cleanText, ["A2A_COMM_TEST", "communication test", "ping test"]) && !wantsDelegation && !envelope.route.length) {
     completeTaskWithReply(task, [
       `${selfName} received and completed the A2A communication test.`,
-      marker
+      finalMarker
     ].join("\n"));
     return true;
   }
-  if (hasA2ARelayExplainTask(cleanText) && (!wantsDelegation || cleanText.toLowerCase().startsWith("complete this task directly"))) {
-    const marker = requestedMarker(text, "DELEGATED_A2A_DONE");
-    completeTaskWithReply(task, [answerA2ARelay(selfName), "", marker].join("\n"));
+  if (hasA2ARelayExplainTask(cleanText) && !wantsDelegation && !envelope.route.length) {
+    completeTaskWithReply(task, [answerA2ARelay(selfName), "", finalMarker].join("\n"));
     return true;
   }
-  if (wantsEthResearch && (!wantsDelegation || text.trim().toLowerCase().startsWith("delegated research request"))) {
+  if (wantsEthResearch && !wantsDelegation && !envelope.route.length) {
     const research = await researchEthPrice();
-    const replyTarget2 = wantsReply ? detectReplyTarget(text, selfName) : void 0;
+    const replyTarget2 = detectReplyTarget(text, selfName, directory);
     let replyResultText2 = "";
     if (replyTarget2) {
       const replyResult = await server.sendTask(replyTarget2, [
@@ -27516,21 +27677,18 @@ async function tryHandleAgenticTask(input) {
       ].join("\n"));
       replyResultText2 = extractTaskFinalText(replyResult);
     }
-    const marker = requestedMarker(text, "ETH_RESEARCH_DONE");
     completeTaskWithReply(task, [
       research,
       "",
       replyTarget2 ? `Forwarded to ${replyTarget2}.` : void 0,
       replyResultText2 ? `Reply delivery result:
 ${replyResultText2}` : void 0,
-      marker
+      finalMarker
     ].filter(Boolean).join("\n"));
     return true;
   }
-  if (!wantsDelegation) return false;
-  const target = detectTarget(text, selfName);
-  if (!target) return false;
-  if (delegationDepth(text) >= 4) {
+  if (!wantsDelegation && !envelope.route.length) return false;
+  if (delegationDepth(text) >= Number(process.env.A2A_MAX_DELEGATION_DEPTH || 8)) {
     completeTaskWithReply(task, [
       `A2A delegation stopped by ${selfName}: max delegation depth reached.`,
       "This prevents routing loops across heterogeneous agents.",
@@ -27538,22 +27696,32 @@ ${replyResultText2}` : void 0,
     ].join("\n"));
     return true;
   }
-  const replyTarget = wantsReply ? detectReplyTarget(text, selfName) : void 0;
-  const finalMarker = requestedMarker(text, "TRI_HERMES_DONE");
+  const target = detectTarget(text, selfName, directory);
+  const replyTarget = detectReplyTarget(text, selfName, directory);
+  if (!target) {
+    await completeTerminalTask({ selfName, server, task, text, marker: finalMarker, replyTarget, runtimeResponder });
+    return true;
+  }
+  const route = routeForDelegation(selfName, target, text, directory);
+  const next = nextRouteTarget(route, selfName) || target;
+  if (!next || next === selfName) {
+    await completeTerminalTask({ selfName, server, task, text, marker: finalMarker, replyTarget, runtimeResponder });
+    return true;
+  }
   const delegatedMessage = wantsEthResearch ? [
-    `A2A-DELEGATION origin=${selfName} target=${target} depth=${delegationDepth(text) + 1}`,
+    `A2A-DELEGATION origin=${selfName} target=${next} route=${route.join("|")} notify=${replyTarget || "none"} depth=${delegationDepth(text) + 1} marker=${finalMarker}`,
     "Delegated research request. Research the current ETH price using available live/public APIs.",
     "Return concise findings with source names, timestamp if available, and limitations.",
-    replyTarget ? `If possible, send the final result to ${replyTarget} via A2A.` : "",
+    replyTarget ? `If possible, send the final result to ${replyTarget} via A2A.` : "Return the final useful result to the caller.",
     "End with DELEGATED_ETH_RESEARCH_DONE."
-  ].filter(Boolean).join("\n") : buildDelegatedMessage({ originalText: text, selfName, target, marker: finalMarker });
-  logger.info(`[perkos-a2a] Agentic delegation: ${selfName} -> ${target}${replyTarget ? ` -> ${replyTarget}` : ""}`);
-  const delegatedResult = await server.sendTask(target, delegatedMessage);
+  ].filter(Boolean).join("\n") : buildDelegatedMessage({ originalText: text, selfName, target: next, route, marker: finalMarker, notify: replyTarget });
+  logger.info(`[perkos-a2a] Agentic delegation: ${selfName} -> ${next}${replyTarget ? ` -> notify ${replyTarget}` : ""}; route=${route.join(" -> ")}`);
+  const delegatedResult = await server.sendTask(next, delegatedMessage);
   const delegatedText = cleanNestedResult(extractTaskFinalText(delegatedResult), finalMarker);
   let replyResultText = "";
-  if (replyTarget && replyTarget !== target) {
+  if (replyTarget && replyTarget !== next && !delegatedText.includes("Forwarded final result to")) {
     const replyMessage = [
-      `Delegated result from ${target}, forwarded by ${selfName}:`,
+      `Delegated result from ${next}, forwarded by ${selfName}:`,
       "",
       delegatedText,
       "",
@@ -27564,7 +27732,8 @@ ${replyResultText2}` : void 0,
   }
   completeTaskWithReply(task, [
     `Agentic A2A delegation completed by ${selfName}.`,
-    `Delegated target: ${target}`,
+    `Delegated target: ${next}`,
+    `Route: ${route.join(" -> ")}`,
     replyTarget ? `Reply target: ${replyTarget}` : void 0,
     "",
     "Delegated result:",
@@ -27671,7 +27840,8 @@ function register(api) {
       server,
       task,
       text,
-      logger
+      logger,
+      runtimeResponder: (prompt, resultMarker) => generateRuntimeReply(pluginConfig, prompt, resultMarker)
     }).catch((err) => {
       const msg = err instanceof Error ? err.message : String(err);
       logger.error(`[perkos-a2a] Agentic task handler failed: ${msg}`);
@@ -27809,7 +27979,7 @@ function register(api) {
   });
   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.",
+    description: "Send a task to another agent via PerkOS A2A. Use this to delegate work, ask a peer to research, or route a chain/circular workflow. The message may name additional agents and a final notification target; the bridge preserves the route and prevents loops.",
     parameters: {
       type: "object",
       properties: {
@@ -27819,7 +27989,7 @@ function register(api) {
         },
         message: {
           type: "string",
-          description: "The task message to send to the agent"
+          description: "The task message to send. You can include routes like 'Apollo -> OpenClaw -> Hermes -> Morpheus' or natural language such as 'ask Hermes to research X, then notify Morpheus'."
         }
       },
       required: ["target", "message"]