@perkos/perkos-a2a 0.12.35 → 0.12.37

package/README.md

@@ -241,14 +241,17 @@ generation. Before accepting a newer generation, the supervisor waits for
 confirmed transport shutdown; a timeout fails closed with
 `OWNER_STOP_TIMEOUT`. A private TTL rollover lock serializes concurrent upgrades,
 and health certifies the supervisor package version and real install root. Lease
-and health evidence are owner-only files and never
-contain relay or chat credentials. This ownership boundary applies to OpenClaw;
+and health evidence are owner-only files and never contain relay or chat
+credentials. From 0.12.37, supervisor health is HMAC-bound to the active repair
+attempt and is authoritative after a real restart; runtime load status is
+written only by the claimed owner service. Incidental validation/doctor plugin
+loads are diagnostic and cannot invalidate signed owner health. This ownership boundary applies to OpenClaw;
 Hermes/custom runtimes keep their existing runtime-owned model and transport
 routing.
 
 ```bash
 A2A_RELAY_API_KEY='<credential-from-invitation>' \
-npx --yes @perkos/perkos-a2a@0.12.35 connect \
+npx --yes @perkos/perkos-a2a@0.12.37 connect \
   --artifact ./perkos-a2a.tgz \
   --sha256 '<sha256-from-the-official-invitation>' \
   --agent-name '<agent-name>' \

package/dist/index.d.ts

@@ -53,5 +53,12 @@ export declare function runOpenClawChatTurn(api: any, config: A2APluginConfig, s
 export declare function formatRecentChatContext(messages: ChatMessage[], currentMessageId: string): string;
 /** The identity the relay treats as exclusive; names are display metadata. */
 export declare function a2aLifecycleKey(config: A2APluginConfig): string;
+/**
+ * OpenClaw may briefly call register while a plugin entry is being rewritten.
+ * Treat partial/empty config as an inert, valid shape instead of crashing the
+ * whole service on string operations. The repair CLI restores the complete
+ * identity atomically before the service is enabled.
+ */
+export declare function normalizeOpenClawPluginConfig(value: unknown): A2APluginConfig;
 export default function register(api: any): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAGV,WAAW,EAEZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,cAAc,YAAY,CAAC;AA0C3B,kEAAkE;AAClE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAItF;AAED,KAAK,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AASpD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,EACd,oBAAoB,EAAE,MAAM,GAC3B,OAAO,CA2BT;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,oBAAoB,EAC3B,eAAe,CAAC,EAAE,MAAM,GACvB,oBAAoB,CA+BtB;AAiED,KAAK,qBAAqB,GAAG;IAC3B,QAAQ,CAAC,EAAE,KAAK,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,CAAC,CAAC;IACH,IAAI,CAAC,EAAE;QACL,yBAAyB,CAAC,EAAE,MAAM,CAAC;QACnC,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC;CACH,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI,CAYrF;AAQD,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;CAAE,GAClF,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAuFxB;AAYD,oFAAoF;AACpF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,WAAW,EAAE,EACvB,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAWR;AA4CD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAe/D;AAED,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,GAAG,QAuzBxC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAGV,WAAW,EAEZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,cAAc,YAAY,CAAC;AA0C3B,kEAAkE;AAClE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAItF;AAED,KAAK,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AASpD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,EACd,oBAAoB,EAAE,MAAM,GAC3B,OAAO,CA2BT;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,oBAAoB,EAC3B,eAAe,CAAC,EAAE,MAAM,GACvB,oBAAoB,CA+BtB;AAiED,KAAK,qBAAqB,GAAG;IAC3B,QAAQ,CAAC,EAAE,KAAK,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,CAAC,CAAC;IACH,IAAI,CAAC,EAAE;QACL,yBAAyB,CAAC,EAAE,MAAM,CAAC;QACnC,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC;CACH,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI,CAYrF;AAQD,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;CAAE,GAClF,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAuFxB;AAYD,oFAAoF;AACpF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,WAAW,EAAE,EACvB,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAWR;AA4CD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAe/D;AAMD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAc7E;AAED,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,GAAG,QAszBxC"}

package/dist/index.js

@@ -24817,7 +24817,7 @@ var require_websocket = __commonJS({
     var http = __require("http");
     var net2 = __require("net");
     var tls = __require("tls");
-    var { randomBytes, createHash: createHash3 } = __require("crypto");
+    var { randomBytes, createHash: createHash4 } = __require("crypto");
     var { Duplex, Readable } = __require("stream");
     var { URL: URL2 } = __require("url");
     var PerMessageDeflate2 = require_permessage_deflate();
@@ -25477,7 +25477,7 @@ var require_websocket = __commonJS({
           abortHandshake(websocket, socket, "Invalid Upgrade header");
           return;
         }
-        const digest = createHash3("sha1").update(key + GUID).digest("base64");
+        const digest = createHash4("sha1").update(key + GUID).digest("base64");
         if (res.headers["sec-websocket-accept"] !== digest) {
           abortHandshake(websocket, socket, "Invalid Sec-WebSocket-Accept header");
           return;
@@ -25844,7 +25844,7 @@ var require_websocket_server = __commonJS({
     var EventEmitter = __require("events");
     var http = __require("http");
     var { Duplex } = __require("stream");
-    var { createHash: createHash3 } = __require("crypto");
+    var { createHash: createHash4 } = __require("crypto");
     var extension2 = require_extension();
     var PerMessageDeflate2 = require_permessage_deflate();
     var subprotocol2 = require_subprotocol();
@@ -26145,7 +26145,7 @@ var require_websocket_server = __commonJS({
           );
         }
         if (this._state > RUNNING) return abortHandshake(socket, 503);
-        const digest = createHash3("sha1").update(key + GUID).digest("base64");
+        const digest = createHash4("sha1").update(key + GUID).digest("base64");
         const headers = [
           "HTTP/1.1 101 Switching Protocols",
           "Upgrade: websocket",
@@ -28469,7 +28469,7 @@ var OpenClawSupervisorClient = class {
         claim = await this.rolloverSupervisor("legacy-health-missing-target");
       }
       const health = claim?.health;
-      if (claim?.state !== "READY" || health?.schemaVersion !== 2 || health.authority !== "process-external-supervisor" || health.state !== "running" || health.ownerKey !== this.ownerHash || health.instanceId !== this.lease.instanceId || health.generation !== this.lease.generation || !this.healthMatchesTarget(health) || health.relayClientCount !== (this.config.relay?.enabled && this.config.relay.url ? 1 : 0) || !health.claimedAt) {
+      if (claim?.state !== "READY" || health?.schemaVersion !== 2 && health?.schemaVersion !== 3 || health.authority !== "process-external-supervisor" || health.state !== "running" || health.ownerKey !== this.ownerHash || health.instanceId !== this.lease.instanceId || health.generation !== this.lease.generation || !this.healthMatchesTarget(health) || health.relayClientCount !== (this.config.relay?.enabled && this.config.relay.url ? 1 : 0) || !health.claimedAt) {
         throw new Error("OWNERSHIP_PRIMITIVE_UNAVAILABLE:supervisor claim did not return certified READY/CLAIMED health");
       }
       this.health = health;
@@ -28530,17 +28530,42 @@ var OpenClawSupervisorClient = class {
       const oldHealth = this.health;
       this.closeSocket(new Error("SUPERVISOR_ROLLOVER"));
       await this.waitForSupervisorStop(oldHealth, 1e4);
-      await this.connectOrSpawn();
-      const target = await this.claimCurrentSupervisor();
-      if (!this.healthMatchesTarget(target.health)) {
-        throw new Error(`SUPERVISOR_ROLLOVER_TARGET_MISMATCH:${reason}`);
-      }
+      const target = await this.claimTargetAfterRollover(reason);
       this.logger.info(`[perkos-a2a] Supervisor rollover complete targetVersion=${this.config.version}`);
       return target;
     } finally {
       releaseLock();
     }
   }
+  /**
+   * OpenClaw can register two adjacent hot-reload generations while its config
+   * file is settling. The first generation may successfully bootstrap the
+   * target supervisor just as its client socket is replaced. Reconnect to that
+   * single fenced supervisor instead of abandoning the agent offline.
+   */
+  async claimTargetAfterRollover(reason) {
+    let lastError;
+    for (let attempt = 1; attempt <= 3; attempt += 1) {
+      try {
+        await this.connectOrSpawn();
+        const target = await this.claimCurrentSupervisor();
+        if (!this.healthMatchesTarget(target.health)) {
+          throw new Error(`SUPERVISOR_ROLLOVER_TARGET_MISMATCH:${reason}`);
+        }
+        return target;
+      } catch (error) {
+        lastError = error;
+        this.closeSocket(new Error("SUPERVISOR_ROLLOVER_TARGET_RETRY"));
+        this.logger.error(
+          `[perkos-a2a] Supervisor target claim retry ${attempt}/3: ${error instanceof Error ? error.message : String(error)}`
+        );
+        if (attempt < 3) await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+      }
+    }
+    throw new Error(
+      `SUPERVISOR_ROLLOVER_TARGET_START_FAILED:${lastError instanceof Error ? lastError.message : String(lastError)}`
+    );
+  }
   async acquireRolloverLock(timeoutMs = 15e3) {
     const path = supervisorRolloverLockPath(this.stateDir, this.ownerHash);
     mkdirSync2(dirname2(path), { recursive: true, mode: 448 });
@@ -28830,7 +28855,7 @@ var OpenClawSupervisorClient = class {
 };
 
 // src/runtime-evidence.ts
-import { createHmac } from "node:crypto";
+import { createHash as createHash3, createHmac, timingSafeEqual } from "node:crypto";
 import {
   chmodSync as chmodSync2,
   mkdirSync as mkdirSync3,
@@ -28840,7 +28865,8 @@ import {
 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
 import { join as join3, resolve as resolve2 } from "node:path";
-var RUNTIME_EVIDENCE_SCHEMA_VERSION = 2;
+var RUNTIME_ATTEMPT_SCHEMA_VERSION = 2;
+var RUNTIME_STATUS_SCHEMA_VERSION = 3;
 function canonicalize(value) {
   if (Array.isArray(value)) return value.map(canonicalize);
   if (!value || typeof value !== "object") return value;
@@ -28848,8 +28874,52 @@ function canonicalize(value) {
     Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, canonicalize(child)])
   );
 }
+function objectValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function normalizedServiceUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return void 0;
+  try {
+    const url = new URL(value);
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/+$/u, "");
+  } catch {
+    return value.trim().replace(/\/+$/u, "");
+  }
+}
+function configEvidenceProjection(config) {
+  const root = objectValue(config);
+  const relay = objectValue(root.relay);
+  const chat = objectValue(root.chat);
+  const platform = objectValue(root.platform);
+  const heartbeatUrl = typeof platform.heartbeatUrl === "string" ? platform.heartbeatUrl : "";
+  const heartbeatAgentId = heartbeatUrl.match(/\/agents\/([^/]+)\/heartbeat(?:\?|$)/u)?.[1];
+  const agentId = typeof root.agentId === "string" ? root.agentId : typeof platform.agentId === "string" ? platform.agentId : heartbeatAgentId;
+  return {
+    agentName: typeof root.agentName === "string" ? root.agentName.trim() : "",
+    agentId: agentId ?? "unknown",
+    relay: {
+      enabled: relay.enabled === true,
+      url: normalizedServiceUrl(relay.url) ?? ""
+    },
+    chat: {
+      enabled: chat.enabled === true,
+      url: normalizedServiceUrl(chat.url) ?? (chat.enabled === true ? "wss://chat.perkos.xyz/chat" : "")
+    },
+    platform: {
+      heartbeatAgentId: heartbeatAgentId ?? agentId ?? "unknown",
+      heartbeatIntervalMs: typeof platform.heartbeatIntervalMs === "number" ? platform.heartbeatIntervalMs : null
+    }
+  };
+}
 function canonicalConfigJson(config) {
-  return JSON.stringify({ schemaVersion: RUNTIME_EVIDENCE_SCHEMA_VERSION, config: canonicalize(config) });
+  return JSON.stringify({ schemaVersion: RUNTIME_STATUS_SCHEMA_VERSION, config: canonicalize(configEvidenceProjection(config)) });
+}
+function configDigest(config) {
+  return createHash3("sha256").update(canonicalConfigJson(config)).digest("hex");
 }
 function configFingerprint(config, hmacKeyHex) {
   if (!/^[a-f0-9]{64}$/u.test(hmacKeyHex)) throw new Error("runtime evidence HMAC key is invalid");
@@ -28879,17 +28949,22 @@ function recordRuntimeLoadEvidence(input) {
     return null;
   }
   const agentId = configAgentId(input.config);
-  if (attempt.schemaVersion !== RUNTIME_EVIDENCE_SCHEMA_VERSION || attempt.targetVersion !== input.version || attempt.expectedAgentId !== agentId) {
+  if (attempt.schemaVersion !== RUNTIME_ATTEMPT_SCHEMA_VERSION || attempt.targetVersion !== input.version || attempt.expectedAgentId !== agentId) {
     input.logger.warn?.("[perkos-a2a] runtime evidence attempt does not match the loaded plugin identity");
     return null;
   }
+  const digest = configDigest(input.config);
   const status = {
-    schemaVersion: RUNTIME_EVIDENCE_SCHEMA_VERSION,
+    schemaVersion: RUNTIME_STATUS_SCHEMA_VERSION,
     loadedAt: (input.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
     version: input.version,
     agentId,
     fingerprint: configFingerprint(input.config, attempt.hmacKeyHex),
+    configDigest: digest,
+    configRevision: `${input.generation}:${digest}`,
     attemptId: attempt.attemptId,
+    writerKind: "owner-plugin",
+    generation: input.generation,
     pid: process.pid,
     processStartTime: processStartIdentity(),
     bootId: currentBootId(),
@@ -29607,25 +29682,32 @@ function a2aLifecycleKey(config) {
   }
   const heartbeatUrl = config.platform?.heartbeatUrl || "";
   const idFromHeartbeat = heartbeatUrl.match(/\/agents\/([^/]+)\/heartbeat(?:\?|$)/u)?.[1];
-  const agentId = config.platform?.agentId || idFromHeartbeat || config.agentName.trim().toLowerCase();
+  const agentId = config.platform?.agentId || idFromHeartbeat || safeAgentName(config.agentName).toLowerCase();
   return `${relayUrl}|${agentId}`;
 }
-function register(api) {
-  const pluginConfig = api.config?.plugins?.entries?.["perkos-a2a"]?.config || {
-    agentName: "agent",
-    port: 5050,
-    skills: [],
-    peers: {}
+function safeAgentName(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "agent";
+}
+function normalizeOpenClawPluginConfig(value) {
+  const raw = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const platform = raw.platform && typeof raw.platform === "object" ? raw.platform : void 0;
+  const heartbeatAgentId = platform?.heartbeatUrl?.match(/\/agents\/([^/]+)\/heartbeat/u)?.[1];
+  const agentName = safeAgentName(raw.agentName || platform?.agentId || heartbeatAgentId);
+  return {
+    ...raw,
+    agentName,
+    port: typeof raw.port === "number" ? raw.port : 5050,
+    skills: Array.isArray(raw.skills) ? raw.skills : [],
+    peers: raw.peers && typeof raw.peers === "object" ? raw.peers : {}
   };
+}
+function register(api) {
+  const pluginConfig = normalizeOpenClawPluginConfig(
+    api.config?.plugins?.entries?.["perkos-a2a"]?.config
+  );
   const logger = api.logger || console;
   const pluginVersion = loadedPluginVersion();
   const pluginRoot = resolve3(dirname3(fileURLToPath2(import.meta.url)), "..");
-  recordRuntimeLoadEvidence({
-    config: pluginConfig,
-    version: pluginVersion,
-    pluginRoot,
-    logger
-  });
   const server = new A2AServer(pluginConfig, logger, { relayOwnership: "external-required" });
   const lifecycleKey = a2aLifecycleKey(pluginConfig);
   const lifecycleInstanceId = randomUUID7();
@@ -29880,7 +29962,7 @@ function register(api) {
   if (pluginConfig.chat?.enabled && !chatApiKey) {
     logger.error("[perkos-chat] chat.enabled=true but no apiKey (set chat.apiKey or fall back from relay.apiKey)");
   }
-  const platformAgentId = pluginConfig.platform?.agentId || pluginConfig.platform?.heartbeatUrl?.match(/\/agents\/([^/]+)\/heartbeat/u)?.[1] || pluginConfig.agentName.trim().toLowerCase();
+  const platformAgentId = pluginConfig.platform?.agentId || pluginConfig.platform?.heartbeatUrl?.match(/\/agents\/([^/]+)\/heartbeat/u)?.[1] || safeAgentName(pluginConfig.agentName).toLowerCase();
   supervisorClient = new OpenClawSupervisorClient({
     ownerHash: supervisorOwnerHash(lifecycleKey),
     generation: Date.now(),
@@ -29922,6 +30004,14 @@ function register(api) {
     start: async () => {
       try {
         await supervisorClient.start();
+        const ownerHealth = supervisorClient.currentHealth();
+        recordRuntimeLoadEvidence({
+          config: pluginConfig,
+          version: pluginVersion,
+          pluginRoot,
+          generation: ownerHealth?.generation ?? 0,
+          logger
+        });
         await server.start();
         logger.info(`[perkos-a2a] A2A server started for ${pluginConfig.agentName}`);
       } catch (error) {
@@ -30325,6 +30415,7 @@ export {
   extractOpenClawChatReply,
   formatRecentChatContext,
   isWebhookEvent,
+  normalizeOpenClawPluginConfig,
   omitUnavailableAgentHarness,
   openclawChatSessionKey,
   runOpenClawChatTurn