@perkos/perkos-a2a 0.12.19 → 0.12.27

package/dist/index.js

@@ -26252,6 +26252,8 @@ import { randomUUID } from "crypto";
 var MIN_RECONNECT_MS = 1e3;
 var MAX_RECONNECT_MS = 6e4;
 var HEARTBEAT_INTERVAL_MS = 25e3;
+var ORPHAN_TTL_MS = 10 * 6e4;
+var ORPHAN_MAX = 256;
 var RelayClient = class {
   ws = null;
   options;
@@ -26262,6 +26264,8 @@ var RelayClient = class {
   connected = false;
   stopped = false;
   pendingCallbacks = /* @__PURE__ */ new Map();
+  /** Responses that arrived with nobody waiting, claimable by a retry. */
+  orphanResponses = /* @__PURE__ */ new Map();
   constructor(options) {
     this.options = options;
     this.logger = options.logger || { info: console.log, error: console.error };
@@ -26282,12 +26286,25 @@ var RelayClient = class {
     }
     this.connected = false;
   }
-  /** Send a task to another agent via the relay */
-  async sendTask(targetAgent, payload) {
+  /**
+   * Send a task to another agent via the relay.
+   *
+   * Pass `taskId` to retry a task that already went out: the relay dedups on
+   * the id and will not run the work twice, and if the first attempt's response
+   * arrived after we gave up it is claimed from the orphan buffer instead of
+   * waiting again. Omit it for genuinely new work.
+   */
+  async sendTask(targetAgent, payload, taskId) {
+    const id = taskId ?? randomUUID();
+    const alreadyAnswered = this.claimOrphan(id);
+    if (alreadyAnswered) {
+      this.logger.info(`[perkos-a2a] Reusing buffered response for task ${id}`);
+      return alreadyAnswered;
+    }
     return this.sendAndWait({
       type: "task",
       to: targetAgent,
-      id: randomUUID(),
+      id,
       from: this.options.agentName,
       payload,
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
@@ -26372,10 +26389,10 @@ var RelayClient = class {
     this.send(msg);
   }
   handleMessage(msg) {
-    const callback = this.pendingCallbacks.get(msg.id);
-    if (callback) {
+    const pending = this.pendingCallbacks.get(msg.id);
+    if (pending && (msg.type === pending.expectedType || msg.type === "error")) {
       this.pendingCallbacks.delete(msg.id);
-      callback(msg);
+      pending.settle(msg);
       return;
     }
     switch (msg.type) {
@@ -26385,8 +26402,15 @@ var RelayClient = class {
       case "task":
         this.options.onTask(msg);
         break;
+      case "task_ack":
+        if (msg.payload?.deduplicated) {
+          this.logger.info(`[perkos-a2a] Relay deduplicated task ${msg.id}; awaiting the original response`);
+        }
+        break;
       case "task_response":
-        this.logger.info(`[perkos-a2a] Received unmatched task response: ${msg.id}`);
+        this.bufferOrphan(msg);
+        this.logger.info(`[perkos-a2a] Buffered unmatched task response: ${msg.id}`);
+        this.options.onOrphanTaskResponse?.(msg);
         break;
       case "discover_response":
         if (this.options.onDiscoverResponse) {
@@ -26407,18 +26431,39 @@ var RelayClient = class {
       this.ws.send(JSON.stringify(msg));
     }
   }
+  /** Take a buffered response for `id`, if one arrived while nobody waited. */
+  claimOrphan(id) {
+    const entry = this.orphanResponses.get(id);
+    if (!entry) return null;
+    this.orphanResponses.delete(id);
+    if (entry.expiresAt <= Date.now()) return null;
+    return entry.msg;
+  }
+  bufferOrphan(msg) {
+    const now = Date.now();
+    for (const [id, entry] of this.orphanResponses) {
+      if (entry.expiresAt <= now) this.orphanResponses.delete(id);
+    }
+    this.orphanResponses.set(msg.id, { msg, expiresAt: now + ORPHAN_TTL_MS });
+    while (this.orphanResponses.size > ORPHAN_MAX) {
+      this.orphanResponses.delete(this.orphanResponses.keys().next().value);
+    }
+  }
   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.pendingCallbacks.set(msg.id, {
+        expectedType,
+        settle: (response) => {
+          clearTimeout(timer);
+          if (response.type === "error") {
+            reject(new Error(`Relay error: ${response.payload.message}`));
+          } else {
+            resolve(response);
+          }
         }
       });
       this.send(msg);
@@ -27034,6 +27079,7 @@ var A2AServer = class {
       messages: [message],
       artifacts: [],
       metadata: {
+        ...message?.metadata,
         fromAgent: message?.metadata?.fromAgent || "unknown"
       },
       sessionKeyHint: "agent:main"
@@ -27281,9 +27327,9 @@ var A2AServer = class {
     const payload = msg.payload;
     const params = payload.params || payload;
     const rpcId = payload.id || msg.id;
-    const acceptQueued = params?.message?.metadata?.acceptQueued === true;
     this.handleSendMessage(params, rpcId).then(async (response) => {
       const task = response.result;
+      const acceptQueued = task?.messages?.[0]?.metadata?.acceptQueued === true;
       if (task?.id && !isTerminalTaskState(task.status?.state)) {
         if (acceptQueued) {
           this.relayClient?.sendTaskResponse(
@@ -27301,7 +27347,12 @@ var A2AServer = class {
           return;
         }
       }
-      this.relayClient?.sendTaskResponse(msg, response);
+      if (!acceptQueued) {
+        this.relayClient?.sendTaskResponse(
+          msg,
+          response
+        );
+      }
     }).catch((err) => {
       const errMsg2 = err instanceof Error ? err.message : String(err);
       this.logger.error(`[perkos-a2a] Failed to process relay task: ${errMsg2}`);
@@ -28412,6 +28463,69 @@ function errMsg(err) {
   return err instanceof Error ? err.message : String(err);
 }
 
+// src/platform-heartbeat.ts
+var DEFAULT_INTERVAL_MS = 6e4;
+var MIN_INTERVAL_MS = 1e4;
+function startPlatformHeartbeat(opts) {
+  const env = opts.env ?? process.env;
+  const fetcher = opts.fetcher ?? fetch;
+  const url = opts.url?.trim() || env.PERKOS_HEARTBEAT_URL?.trim();
+  const relayKey = opts.relayKey?.trim() || env.A2A_RELAY_API_KEY?.trim();
+  if (!url || !relayKey) return { stop: () => void 0 };
+  const configuredInterval = Number(
+    opts.intervalMs ?? env.PERKOS_HEARTBEAT_INTERVAL_MS ?? DEFAULT_INTERVAL_MS
+  );
+  const intervalMs = Number.isFinite(configuredInterval) ? Math.max(MIN_INTERVAL_MS, configuredInterval) : DEFAULT_INTERVAL_MS;
+  const a2aRuntime = env.A2A_RUNTIME?.trim() || "hermes-api";
+  const runtimeKind = opts.runtimeKind ?? (a2aRuntime === "openclaw" ? "openclaw" : a2aRuntime === "custom" ? "custom" : "hermes");
+  let stopped = false;
+  let firstSuccess = true;
+  const report = async () => {
+    if (stopped) return;
+    try {
+      const res = await fetcher(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${relayKey}`,
+          "x-relay-key": relayKey
+        },
+        body: JSON.stringify({
+          runtimeKind,
+          version: opts.version?.trim() || env.PERKOS_A2A_VERSION?.trim() || "0.12.26",
+          ts: Date.now()
+        })
+      });
+      if (res.ok) {
+        if (firstSuccess) {
+          opts.logger.info(
+            `[perkos-heartbeat] reported online to ${url} (status=${res.status}, every=${intervalMs}ms)`
+          );
+          firstSuccess = false;
+        }
+      } else {
+        opts.logger.warn(
+          `[perkos-heartbeat] ${res.status} from ${url} (continuing)`
+        );
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      opts.logger.warn(
+        `[perkos-heartbeat] POST failed to ${url}: ${msg} (continuing)`
+      );
+    }
+  };
+  void report();
+  const timer = setInterval(() => void report(), intervalMs);
+  timer.unref?.();
+  return {
+    stop: () => {
+      stopped = true;
+      clearInterval(timer);
+    }
+  };
+}
+
 // src/types.ts
 function isWebhookEvent(msg) {
   return msg.type === "webhook_event";
@@ -28444,11 +28558,204 @@ function openclawChatSessionKey(config, convId) {
   const safe = convId.replace(/[^a-zA-Z0-9_.-]/g, "-").slice(0, 120) || "unknown";
   return `${configured}:perkos-chat-${safe}`;
 }
+var MISSING_AGENT_HARNESS_RE = /Requested agent harness "([^"]+)" is not registered\./u;
+function missingAgentHarnessId(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.match(MISSING_AGENT_HARNESS_RE)?.[1]?.trim() || null;
+}
+function omitUnavailableAgentHarness(value, unavailableHarnessId) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => omitUnavailableAgentHarness(entry, unavailableHarnessId));
+  }
+  if (!value || typeof value !== "object") return value;
+  const source = value;
+  const next = {};
+  for (const [key, entry] of Object.entries(source)) {
+    if (key === "agentRuntime" && entry && typeof entry === "object" && String(entry.id ?? "").trim() === unavailableHarnessId) {
+      continue;
+    }
+    if ((key === "embeddedHarness" || key === "agentRuntimeOverride" || key === "agentHarnessId") && typeof entry === "string" && entry.trim() === unavailableHarnessId) {
+      continue;
+    }
+    next[key] = omitUnavailableAgentHarness(entry, unavailableHarnessId);
+  }
+  return next;
+}
+function alignOpenClawChatSessionModel(entry, configuredModel) {
+  const next = { ...entry };
+  for (const key of [
+    "providerOverride",
+    "modelOverride",
+    "modelOverrideSource",
+    "modelOverrideFallbackOriginProvider",
+    "modelOverrideFallbackOriginModel",
+    "agentRuntimeOverride",
+    "agentHarnessId",
+    "modelProvider",
+    "model",
+    "fallbackNoticeSelectedModel",
+    "fallbackNoticeActiveModel",
+    "fallbackNoticeReason"
+  ]) {
+    delete next[key];
+  }
+  const modelRef = configuredModel?.trim();
+  const separator = modelRef?.indexOf("/") ?? -1;
+  if (modelRef && separator > 0 && separator < modelRef.length - 1) {
+    const provider = modelRef.slice(0, separator);
+    const model = modelRef.slice(separator + 1);
+    next.providerOverride = provider;
+    next.modelOverride = model;
+    next.modelOverrideSource = "user";
+    next.modelProvider = provider;
+    next.model = model;
+  }
+  return next;
+}
+async function prepareOpenClawChatSession(api, config, sessionKey, logger) {
+  const patchSessionEntry = api.runtime?.agent?.session?.patchSessionEntry;
+  if (typeof patchSessionEntry !== "function") {
+    logger.info("[perkos-chat] OpenClaw session metadata API unavailable \u2014 using gateway session defaults");
+    return;
+  }
+  try {
+    await patchSessionEntry({
+      sessionKey,
+      fallbackEntry: { sessionId: randomUUID6(), updatedAt: Date.now() },
+      preserveActivity: true,
+      replaceEntry: true,
+      update: (entry) => alignOpenClawChatSessionModel(entry, config.runtime?.model)
+    });
+    logger.info(
+      config.runtime?.model ? `[perkos-chat] session ${sessionKey} pinned to ${config.runtime.model}` : `[perkos-chat] session ${sessionKey} aligned to the gateway's active default model`
+    );
+  } catch (err) {
+    logger.error(
+      `[perkos-chat] failed to align OpenClaw session model: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+async function forceNativeOpenClawChatRuntime(api, config, sessionKey, logger) {
+  const patchSessionEntry = api.runtime?.agent?.session?.patchSessionEntry;
+  if (typeof patchSessionEntry !== "function") return;
+  try {
+    await patchSessionEntry({
+      sessionKey,
+      fallbackEntry: { sessionId: randomUUID6(), updatedAt: Date.now() },
+      preserveActivity: true,
+      replaceEntry: true,
+      update: (entry) => ({
+        ...alignOpenClawChatSessionModel(entry, config.runtime?.model),
+        // OpenClaw <= 2026.5.x calls its built-in runtime "pi". Newer
+        // gateways normalize the alias to their native "openclaw" harness.
+        agentRuntimeOverride: "pi",
+        agentHarnessId: "pi"
+      })
+    });
+    logger.info(`[perkos-chat] session ${sessionKey} retrying with the native OpenClaw harness`);
+  } catch (err) {
+    logger.error(
+      `[perkos-chat] failed to select native OpenClaw harness: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function extractOpenClawChatReply(result) {
+  const finalText = result.meta?.finalAssistantVisibleText?.trim() || result.meta?.finalAssistantRawText?.trim();
+  if (finalText) return finalText;
+  const payloadText = result.payloads?.filter((payload) => !payload.isError && !payload.isReasoning && !payload.isCommentary).map((payload) => payload.text?.trim()).filter((text) => Boolean(text)).join("\n\n").trim();
+  return payloadText || null;
+}
+function openclawAgentId(config) {
+  const sessionKey = config.runtime?.sessionKey || "agent:main";
+  const parts = sessionKey.split(":");
+  return parts[0] === "agent" && parts[1] ? parts[1] : "main";
+}
+async function runOpenClawChatTurn(api, config, sessionKey, prompt, transcriptPrompt, logger) {
+  const runEmbeddedAgent = api.runtime?.agent?.runEmbeddedAgent;
+  const currentConfig = api.runtime?.config?.current;
+  const resolveAgentWorkspaceDir = api.runtime?.agent?.resolveAgentWorkspaceDir;
+  if (typeof runEmbeddedAgent !== "function" || typeof currentConfig !== "function" || typeof resolveAgentWorkspaceDir !== "function") {
+    logger.info("[perkos-chat] embedded OpenClaw runner unavailable \u2014 using gateway wake fallback");
+    return null;
+  }
+  const agentId = openclawAgentId(config);
+  const runtimeConfig = currentConfig();
+  const workspaceDir = resolveAgentWorkspaceDir(runtimeConfig, agentId);
+  const entry = api.runtime?.agent?.session?.getSessionEntry?.({ agentId, sessionKey });
+  const sessionId = typeof entry?.sessionId === "string" && entry.sessionId.trim() ? entry.sessionId : randomUUID6();
+  const configuredTimeout = api.runtime?.agent?.resolveAgentTimeoutMs?.(runtimeConfig);
+  const timeoutMs = Math.min(
+    75e3,
+    typeof configuredTimeout === "number" && configuredTimeout > 0 ? configuredTimeout : 75e3
+  );
+  const run = async (configOverride, retryNative = false) => runEmbeddedAgent({
+    sessionId,
+    sessionKey,
+    agentId,
+    workspaceDir,
+    config: configOverride,
+    prompt,
+    transcriptPrompt,
+    timeoutMs,
+    runId: randomUUID6(),
+    trigger: "user",
+    messageChannel: "perkos-chat",
+    disableTools: true,
+    disableMessageTool: true,
+    terminalReplyExpectation: "required",
+    suppressLiveStreamOutput: true,
+    cleanupBundleMcpOnRunEnd: true,
+    ...retryNative ? {
+      // Cross-version compatibility: 2026.5.x recognizes `pi`, while
+      // current gateways recognize the explicit native runtime override.
+      agentHarnessId: "pi",
+      agentHarnessRuntimeOverride: "openclaw",
+      suppressNextUserMessagePersistence: true
+    } : {}
+  });
+  try {
+    let result;
+    try {
+      result = await run(runtimeConfig);
+    } catch (err) {
+      const unavailableHarnessId = missingAgentHarnessId(err);
+      if (!unavailableHarnessId) throw err;
+      logger.info(
+        `[perkos-chat] configured harness ${unavailableHarnessId} is unavailable; retrying with the native OpenClaw runtime and the same gateway-selected model`
+      );
+      await forceNativeOpenClawChatRuntime(api, config, sessionKey, logger);
+      result = await run(
+        omitUnavailableAgentHarness(runtimeConfig, unavailableHarnessId),
+        true
+      );
+    }
+    const reply = extractOpenClawChatReply(result);
+    if (!reply) {
+      logger.error(`[perkos-chat] embedded OpenClaw run completed without reply text for ${sessionKey}`);
+      return null;
+    }
+    logger.info(`[perkos-chat] embedded OpenClaw run completed for ${sessionKey}`);
+    return reply;
+  } catch (err) {
+    logger.error(
+      `[perkos-chat] embedded OpenClaw run failed for ${sessionKey}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return null;
+  }
+}
 function parseWalletFromIdentity(identity) {
   if (typeof identity !== "string" || !identity.startsWith("user:")) return null;
   const addr = identity.slice("user:".length);
   return addr.startsWith("0x") ? addr.toLowerCase() : null;
 }
+var CHAT_CONTEXT_MESSAGE_LIMIT = 12;
+var CHAT_CONTEXT_CHAR_LIMIT = 6e3;
+function formatRecentChatContext(messages, currentMessageId) {
+  const prior = messages.filter((message) => message.id !== currentMessageId).slice(-CHAT_CONTEXT_MESSAGE_LIMIT).map((message) => `${message.from}: ${message.text.trim()}`).filter((line) => line.length > 0);
+  if (prior.length === 0) return "(No earlier messages in this conversation.)";
+  const transcript = prior.join("\n");
+  return transcript.length <= CHAT_CONTEXT_CHAR_LIMIT ? transcript : `\u2026${transcript.slice(-CHAT_CONTEXT_CHAR_LIMIT)}`;
+}
 async function deliverToHermes(config, message, logger) {
   const runtime = config.runtime || {};
   const baseUrl = (runtime.hermesUrl || "http://127.0.0.1:8642").replace(/\/+$/, "");
@@ -28463,7 +28770,8 @@ async function deliverToHermes(config, message, logger) {
   };
   if (token) headers.authorization = `Bearer ${token}`;
   const normalizedEndpoint = endpoint.replace(/^\/?/, "/");
-  const body = normalizedEndpoint.startsWith("/v1/chat/completions") ? { model: "hermes-agent", messages: [{ role: "user", content: message }], stream: false } : normalizedEndpoint.startsWith("/v1/runs") ? { input: message, session_id: sessionKey } : normalizedEndpoint.startsWith("/v1/responses") ? { model: "hermes-agent", input: message, store: true } : { sessionKey, message };
+  const model = runtime.model?.trim();
+  const body = normalizedEndpoint.startsWith("/v1/chat/completions") ? { ...model ? { model } : {}, messages: [{ role: "user", content: message }], stream: false } : normalizedEndpoint.startsWith("/v1/runs") ? { input: message, session_id: sessionKey } : normalizedEndpoint.startsWith("/v1/responses") ? { ...model ? { model } : {}, input: message, store: true } : { sessionKey, message };
   const response = await fetch(url, {
     method: "POST",
     headers,
@@ -28681,6 +28989,13 @@ function register(api) {
       onChatDeliver: async (frame) => {
         const walletAddress = parseWalletFromIdentity(frame.from);
         const marker = `[PERKOS_CHAT:${frame.convId}]`;
+        const recentPage = await chatClient?.getStore().readPage(frame.convId, {
+          limit: CHAT_CONTEXT_MESSAGE_LIMIT + 1
+        });
+        const recentContext = formatRecentChatContext(
+          recentPage?.messages ?? [],
+          frame.id
+        );
         const eventText = [
           marker,
           `From: ${frame.from}`,
@@ -28694,6 +29009,27 @@ function register(api) {
           walletAddress ? `  walletAddress: "${walletAddress}"` : `  walletAddress: <derived from From>`,
           `  text: <your reply>`,
           "",
+          "Recent conversation context (oldest to newest):",
+          recentContext,
+          "",
+          "Use the recent context. Do not ask again for information the user already provided.",
+          "",
+          "Message body:",
+          frame.text
+        ].filter(Boolean).join("\n");
+        const directRunPrompt = [
+          marker,
+          `From: ${frame.from}`,
+          `Conversation: ${frame.convId}`,
+          frame.projectId ? `Canonical projectId: ${frame.projectId}` : "",
+          "",
+          "Reply to this PerkOS chat message using your current runtime configuration.",
+          "Return only the reply text. Do not call messaging tools; the PerkOS plugin delivers the returned text.",
+          "Use the recent context and do not ask again for information already provided.",
+          "",
+          "Recent conversation context (oldest to newest):",
+          recentContext,
+          "",
           "Message body:",
           frame.text
         ].filter(Boolean).join("\n");
@@ -28710,14 +29046,38 @@ function register(api) {
           logger.info(`[perkos-chat] dropped chat_deliver for ${frame.convId} (runtime=none)`);
           return;
         }
+        const chatSessionKey = openclawChatSessionKey(pluginConfig, frame.convId);
+        await prepareOpenClawChatSession(api, pluginConfig, chatSessionKey, logger);
+        if (walletAddress) {
+          const reply = await runOpenClawChatTurn(
+            api,
+            pluginConfig,
+            chatSessionKey,
+            directRunPrompt,
+            frame.text,
+            logger
+          );
+          if (reply) {
+            const result = await chatClient?.sendReply({
+              convId: frame.convId,
+              walletAddress,
+              text: reply,
+              replyTo: frame.id
+            });
+            logger.info(
+              `[perkos-chat] embedded reply ${result?.delivered ? "delivered" : "queued (offline)"} for ${frame.convId}`
+            );
+            return;
+          }
+        }
         if (enqueueSystemEvent) {
-          enqueueSystemEvent(eventText, { sessionKey: openclawChatSessionKey(pluginConfig, frame.convId) });
+          enqueueSystemEvent(eventText, { sessionKey: chatSessionKey });
         }
         wakeGatewayAgent(
           requestHeartbeatNow,
           `[PerkOS-Chat] inbound message in ${frame.convId}`,
           logger,
-          openclawChatSessionKey(pluginConfig, frame.convId)
+          chatSessionKey
         );
       },
       onChannelJoin: async (frame) => {
@@ -28741,6 +29101,29 @@ function register(api) {
       }
     });
   }
+  if (pluginConfig.platform?.heartbeatUrl) {
+    let platformHeartbeat = null;
+    api.registerService({
+      id: "perkos-a2a-platform-heartbeat",
+      start: () => {
+        platformHeartbeat = startPlatformHeartbeat({
+          logger: {
+            info: (message) => logger.info(message),
+            warn: (message) => (logger.warn || logger.info).call(logger, message)
+          },
+          url: pluginConfig.platform?.heartbeatUrl,
+          relayKey: pluginConfig.relay?.apiKey,
+          runtimeKind: "openclaw",
+          version: "0.12.26",
+          intervalMs: pluginConfig.platform?.heartbeatIntervalMs
+        });
+      },
+      stop: () => {
+        platformHeartbeat?.stop();
+        platformHeartbeat = null;
+      }
+    });
+  }
   api.registerTool({
     name: "perkos_a2a_send",
     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.",
@@ -29122,10 +29505,15 @@ export {
   ChatStore,
   RelayClient,
   RelayHub,
+  alignOpenClawChatSessionModel,
   register as default,
   detectNetworking,
+  extractOpenClawChatReply,
+  formatRecentChatContext,
   isWebhookEvent,
-  openclawChatSessionKey
+  omitUnavailableAgentHarness,
+  openclawChatSessionKey,
+  runOpenClawChatTurn
 };
 /*! Bundled license information: