@perkos/perkos-a2a 0.12.32 → 0.12.33

package/README.md

@@ -170,7 +170,7 @@ openclaw gateway restart
 
 #### Official idempotent connection
 
-Version 0.12.32+ ships the machine-readable `perkos-a2a connect` CLI. The
+Version 0.12.33+ ships the machine-readable `perkos-a2a connect` CLI. The
 official PerkOS invitation supplies the artifact URL, SHA-256, agent name, and
 agent id; it invokes the exact npm version with `npx`. The same command performs
 a first install or repairs the matching existing identity, even when an invalid
@@ -206,11 +206,25 @@ failure is emitted as one JSON object; secret values are never printed.
 
 OpenClaw plugin reloads can briefly keep two JavaScript VMs alive. Starting the
 relay socket in each VM would register the same external identity twice. Version
-0.12.32 moves the relay WebSocket, PerkOS Chat socket, and platform heartbeat to
+0.12.33 moves the relay WebSocket, PerkOS Chat socket, and platform heartbeat to
 one process-external supervisor per normalized relay URL + agent id. Plugin VMs
 communicate with that owner through a private Unix socket and renew a 15-second
 lease.
 
+OpenClaw transport ownership is fail-closed: a plugin VM never falls back to a
+second in-process relay/chat/heartbeat client if the supervisor cannot become
+READY and accept the matching claim. The supervisor records its PID, process
+start identity, boot id, claim time, and transport counts in private health
+evidence so `connect` can distinguish a certified owner from stale files.
+
+For a clean first install, OpenClaw's PID 1 hot reload remains supported. When
+upgrading a pre-supervisor or otherwise uncertified installation, `connect`
+requires evidence that the gateway PID/start identity actually changed. If the
+current environment cannot perform that restart safely, it exits with the
+machine-readable action `ACTION_REQUIRED_REAL_RESTART`; rerunning the same
+idempotent command after the service/container restart resumes the migration
+without replacing identity or credentials.
+
 Each claim carries the parent PID/start identity, boot id, instance id, and
 generation. Before accepting a newer generation, the supervisor waits for
 confirmed transport shutdown; a timeout fails closed with
@@ -221,7 +235,7 @@ routing.
 
 ```bash
 A2A_RELAY_API_KEY='<credential-from-invitation>' \
-npx --yes @perkos/perkos-a2a@0.12.32 connect \
+npx --yes @perkos/perkos-a2a@0.12.33 connect \
   --artifact ./perkos-a2a.tgz \
   --sha256 '<sha256-from-the-official-invitation>' \
   --agent-name '<agent-name>' \

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,QA6yBxC"}
+{"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,QAqzBxC"}

package/dist/index.js

@@ -27009,6 +27009,7 @@ var A2AServer = class {
   clientOnly = false;
   relayClient = null;
   externalRelayTransport = false;
+  relayOwnership;
   relayHub = null;
   messageInjector = null;
   taskResultHandler = null;
@@ -27020,9 +27021,10 @@ var A2AServer = class {
   startPromise = null;
   stopPromise = null;
   operations = /* @__PURE__ */ new Set();
-  constructor(config, logger) {
+  constructor(config, logger, options = {}) {
     this.config = config;
     this.logger = logger || { info: console.log, error: console.error };
+    this.relayOwnership = options.relayOwnership ?? "local";
     this.app = (0, import_express.default)();
     this.app.use(import_express.default.json());
     this.agentCard = {
@@ -27490,6 +27492,9 @@ var A2AServer = class {
       this.logger.info(`[perkos-a2a] Relay transport delegated to supervisor for ${relay.url}`);
       return;
     }
+    if (this.relayOwnership === "external-required") {
+      throw new Error("OWNERSHIP_PRIMITIVE_UNAVAILABLE:OpenClaw relay transport requires the process-external supervisor");
+    }
     this.relayClient = new RelayClient({
       agentName: this.config.agentName,
       relay,
@@ -27712,7 +27717,7 @@ var A2AServer = class {
 
 // src/index.ts
 import { randomUUID as randomUUID7 } from "crypto";
-import { readFileSync as readFileSync4 } from "node:fs";
+import { readFileSync as readFileSync5 } from "node:fs";
 import { dirname as dirname2, resolve as resolve3 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
@@ -28334,6 +28339,7 @@ function isNotFound(err) {
 // src/openclaw-supervisor-client.ts
 import { randomUUID as randomUUID5 } from "node:crypto";
 import { spawn } from "node:child_process";
+import { existsSync, readFileSync as readFileSync3, unlinkSync } from "node:fs";
 import { homedir as homedir3 } from "node:os";
 import net from "node:net";
 import { resolve } from "node:path";
@@ -28344,7 +28350,7 @@ import { createHash as createHash2 } from "node:crypto";
 import { chmodSync, mkdirSync, readFileSync as readFileSync2, renameSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join as join2 } from "node:path";
-var SUPERVISOR_PROTOCOL_VERSION = 1;
+var SUPERVISOR_PROTOCOL_VERSION = 2;
 var SUPERVISOR_RENEW_MS = 5e3;
 function supervisorOwnerHash(lifecycleKey) {
   return createHash2("sha256").update(lifecycleKey).digest("hex");
@@ -28358,6 +28364,9 @@ function supervisorSocketPath(stateDir, ownerHash) {
   const uid = typeof process.getuid === "function" ? process.getuid() : "user";
   return join2(tmpdir(), `perkos-a2a-${uid}`, `${ownerHash.slice(0, 32)}.sock`);
 }
+function supervisorBootstrapPath(stateDir, ownerHash) {
+  return join2(supervisorDir(stateDir), `${ownerHash}.bootstrap.json`);
+}
 function currentBootId() {
   try {
     return readFileSync2("/proc/sys/kernel/random/boot_id", "utf8").trim();
@@ -28388,6 +28397,7 @@ var OpenClawSupervisorClient = class {
   config;
   logger;
   handlers;
+  supervisorCliPath;
   lease;
   socket = null;
   startPromise = null;
@@ -28403,6 +28413,7 @@ var OpenClawSupervisorClient = class {
     this.config = input.config;
     this.logger = input.logger;
     this.handlers = input.handlers;
+    this.supervisorCliPath = input.supervisorCliPath;
     this.lease = {
       ownerKey: input.ownerHash,
       instanceId: input.instanceId,
@@ -28428,13 +28439,18 @@ var OpenClawSupervisorClient = class {
     this.stopped = false;
     const starting = (async () => {
       await this.connectOrSpawn();
-      await this.requestWithMessage({
-        protocolVersion: 1,
+      const claim = await this.requestWithMessage({
+        protocolVersion: 2,
         type: "claim",
         requestId: randomUUID5(),
         lease: this.freshLease(),
         config: this.config
       }, 15e3);
+      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 || 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;
       this.renewTimer = setInterval(() => this.renew(), SUPERVISOR_RENEW_MS);
       this.renewTimer.unref?.();
       this.logger.info(`[perkos-a2a] Supervisor owner ready generation=${this.lease.generation} instanceId=${this.lease.instanceId}`);
@@ -28455,7 +28471,7 @@ var OpenClawSupervisorClient = class {
         const requestId = randomUUID5();
         try {
           await this.requestWithMessage({
-            protocolVersion: 1,
+            protocolVersion: 2,
             type: "release",
             requestId,
             lease: this.freshLease()
@@ -28484,14 +28500,14 @@ var OpenClawSupervisorClient = class {
     return await this.request("discover", {}, 15e3);
   }
   sendTaskResponse(original, result) {
-    this.write({ protocolVersion: 1, type: "relayTaskResult", lease: this.freshLease(), eventId: randomUUID5(), original, result });
+    this.write({ protocolVersion: 2, type: "relayTaskResult", lease: this.freshLease(), eventId: randomUUID5(), original, result });
   }
   async sendChatReply(payload) {
     return await this.request("chatReply", payload, 15e3);
   }
   async request(method, payload, timeoutMs) {
     const requestId = randomUUID5();
-    return this.requestWithMessage({ protocolVersion: 1, type: "request", requestId, lease: this.freshLease(), method, payload }, timeoutMs);
+    return this.requestWithMessage({ protocolVersion: 2, type: "request", requestId, lease: this.freshLease(), method, payload }, timeoutMs);
   }
   async requestWithMessage(message, timeoutMs) {
     return new Promise((resolveRequest, rejectRequest) => {
@@ -28516,7 +28532,7 @@ var OpenClawSupervisorClient = class {
   }
   renew() {
     if (this.stopped || !this.socket || this.socket.destroyed) return;
-    this.write({ protocolVersion: 1, type: "renew", lease: this.freshLease() });
+    this.write({ protocolVersion: 2, type: "renew", lease: this.freshLease() });
   }
   async connectOrSpawn() {
     try {
@@ -28524,12 +28540,27 @@ var OpenClawSupervisorClient = class {
       return;
     } catch {
     }
-    const cliPath = fileURLToPath(new URL("./openclaw-supervisor-cli.js", import.meta.url));
+    const cliPath = this.supervisorCliPath ?? fileURLToPath(new URL("./openclaw-supervisor-cli.js", import.meta.url));
+    if (!existsSync(cliPath)) {
+      throw new Error(`OWNERSHIP_PRIMITIVE_UNAVAILABLE:supervisor CLI is missing at ${cliPath}`);
+    }
+    const bootstrapPath = supervisorBootstrapPath(this.stateDir, this.ownerHash);
+    try {
+      unlinkSync(bootstrapPath);
+    } catch {
+    }
+    let childExit;
     const child = spawn(process.execPath, [cliPath, "--state-dir", this.stateDir, "--owner-key", this.ownerHash], {
       detached: true,
       stdio: "ignore",
       env: { ...process.env }
     });
+    child.once("error", (error) => {
+      childExit = `spawn error: ${error.message}`;
+    });
+    child.once("exit", (code, signal) => {
+      childExit = `exit code=${code ?? "null"} signal=${signal ?? "none"}`;
+    });
     child.unref();
     const deadline = Date.now() + 1e4;
     let lastError;
@@ -28541,9 +28572,22 @@ var OpenClawSupervisorClient = class {
       } catch (error) {
         lastError = error;
       }
+      const bootstrap = this.readBootstrapStatus(bootstrapPath);
+      if (bootstrap?.state === "failed") {
+        throw new Error(`OWNERSHIP_PRIMITIVE_UNAVAILABLE:${bootstrap.errorCode || "SUPERVISOR_BOOT_FAILED"}:${bootstrap.message || "supervisor failed before READY"}`);
+      }
+      if (childExit) throw new Error(`OWNERSHIP_PRIMITIVE_UNAVAILABLE:supervisor ${childExit}`);
     }
     throw new Error(`OWNERSHIP_PRIMITIVE_UNAVAILABLE:${lastError instanceof Error ? lastError.message : String(lastError)}`);
   }
+  readBootstrapStatus(path) {
+    try {
+      const value = JSON.parse(readFileSync3(path, "utf8"));
+      return value?.schemaVersion === 1 && value.ownerKey === this.ownerHash ? value : null;
+    } catch {
+      return null;
+    }
+  }
   connectSocket(timeoutMs) {
     this.closeSocket(new Error("SUPERVISOR_RECONNECT"));
     return new Promise((resolveConnect, rejectConnect) => {
@@ -28609,11 +28653,11 @@ var OpenClawSupervisorClient = class {
     if (event.type === "relayTask") {
       try {
         const result = await this.handlers.onRelayTask(event.message);
-        this.write({ protocolVersion: 1, type: "relayTaskResult", lease: this.freshLease(), eventId: event.eventId, original: event.message, result });
+        this.write({ protocolVersion: 2, type: "relayTaskResult", lease: this.freshLease(), eventId: event.eventId, original: event.message, result });
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         this.write({
-          protocolVersion: 1,
+          protocolVersion: 2,
           type: "relayTaskResult",
           lease: this.freshLease(),
           eventId: event.eventId,
@@ -28649,13 +28693,13 @@ import { createHmac } from "node:crypto";
 import {
   chmodSync as chmodSync2,
   mkdirSync as mkdirSync2,
-  readFileSync as readFileSync3,
+  readFileSync as readFileSync4,
   renameSync as renameSync2,
   writeFileSync as writeFileSync2
 } 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 = 1;
+var RUNTIME_EVIDENCE_SCHEMA_VERSION = 2;
 function canonicalize(value) {
   if (Array.isArray(value)) return value.map(canonicalize);
   if (!value || typeof value !== "object") return value;
@@ -28688,7 +28732,7 @@ function recordRuntimeLoadEvidence(input) {
   const evidenceDir = runtimeEvidenceDir(input.stateDir);
   let attempt;
   try {
-    attempt = JSON.parse(readFileSync3(runtimeAttemptPath(input.stateDir), "utf8"));
+    attempt = JSON.parse(readFileSync4(runtimeAttemptPath(input.stateDir), "utf8"));
   } catch {
     input.logger.info(`[perkos-a2a] config loaded version=${input.version} agentId=${configAgentId(input.config)} attemptId=none`);
     return null;
@@ -28706,6 +28750,8 @@ function recordRuntimeLoadEvidence(input) {
     fingerprint: configFingerprint(input.config, attempt.hmacKeyHex),
     attemptId: attempt.attemptId,
     pid: process.pid,
+    processStartTime: processStartIdentity(),
+    bootId: currentBootId(),
     pluginRoot: resolve2(input.pluginRoot)
   };
   mkdirSync2(evidenceDir, { recursive: true, mode: 448 });
@@ -29149,7 +29195,7 @@ function isWebhookEvent(msg) {
 // src/index.ts
 function loadedPluginVersion() {
   try {
-    const manifest = JSON.parse(readFileSync4(new URL("../openclaw.plugin.json", import.meta.url), "utf8"));
+    const manifest = JSON.parse(readFileSync5(new URL("../openclaw.plugin.json", import.meta.url), "utf8"));
     return typeof manifest.version === "string" ? manifest.version : "unknown";
   } catch {
     return "unknown";
@@ -29438,7 +29484,7 @@ function register(api) {
     pluginRoot: resolve3(dirname2(fileURLToPath2(import.meta.url)), ".."),
     logger
   });
-  const server = new A2AServer(pluginConfig, logger);
+  const server = new A2AServer(pluginConfig, logger, { relayOwnership: "external-required" });
   const lifecycleKey = a2aLifecycleKey(pluginConfig);
   const lifecycleInstanceId = randomUUID7();
   const pendingTasks = [];
@@ -29731,9 +29777,17 @@ function register(api) {
   api.registerService({
     id: "perkos-a2a",
     start: async () => {
-      await supervisorClient.start();
-      await server.start();
-      logger.info(`[perkos-a2a] A2A server started for ${pluginConfig.agentName}`);
+      try {
+        await supervisorClient.start();
+        await server.start();
+        logger.info(`[perkos-a2a] A2A server started for ${pluginConfig.agentName}`);
+      } catch (error) {
+        await server.stop({ reason: "openclaw-service-start-failed", timeoutMs: 2e3, drainMs: 0 }).catch(() => void 0);
+        await supervisorClient.stop().catch(() => void 0);
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error(`[perkos-a2a] OWNERSHIP_START_FAILED:${message}`);
+        throw error;
+      }
     },
     stop: async () => {
       logger.info("[perkos-a2a] A2A server stopping");