@perkos/perkos-a2a 0.12.29 → 0.12.31

package/dist/index.js

@@ -4944,10 +4944,10 @@ var require_raw_body = __commonJS({
       if (done) {
         return readStream(stream, encoding, length, limit, wrap(done));
       }
-      return new Promise(function executor(resolve, reject) {
+      return new Promise(function executor(resolve3, reject) {
         readStream(stream, encoding, length, limit, function onRead(err, buf) {
           if (err) return reject(err);
-          resolve(buf);
+          resolve3(buf);
         });
       });
     }
@@ -18429,11 +18429,11 @@ var require_view = __commonJS({
     var debug = require_src()("express:view");
     var path = __require("path");
     var fs = __require("fs");
-    var dirname = path.dirname;
+    var dirname2 = path.dirname;
     var basename = path.basename;
     var extname = path.extname;
-    var join2 = path.join;
-    var resolve = path.resolve;
+    var join3 = path.join;
+    var resolve3 = path.resolve;
     module.exports = View;
     function View(name, options) {
       var opts = options || {};
@@ -18467,8 +18467,8 @@ var require_view = __commonJS({
       debug('lookup "%s"', name);
       for (var i = 0; i < roots.length && !path2; i++) {
         var root = roots[i];
-        var loc = resolve(root, name);
-        var dir = dirname(loc);
+        var loc = resolve3(root, name);
+        var dir = dirname2(loc);
         var file = basename(loc);
         path2 = this.resolve(dir, file);
       }
@@ -18478,14 +18478,14 @@ var require_view = __commonJS({
       debug('render "%s"', this.path);
       this.engine(this.path, options, callback);
     };
-    View.prototype.resolve = function resolve2(dir, file) {
+    View.prototype.resolve = function resolve4(dir, file) {
       var ext = this.ext;
-      var path2 = join2(dir, file);
+      var path2 = join3(dir, file);
       var stat = tryStat(path2);
       if (stat && stat.isFile()) {
         return path2;
       }
-      path2 = join2(dir, basename(file, ext), "index" + ext);
+      path2 = join3(dir, basename(file, ext), "index" + ext);
       stat = tryStat(path2);
       if (stat && stat.isFile()) {
         return path2;
@@ -19118,9 +19118,9 @@ var require_send = __commonJS({
     var Stream = __require("stream");
     var util = __require("util");
     var extname = path.extname;
-    var join2 = path.join;
+    var join3 = path.join;
     var normalize = path.normalize;
-    var resolve = path.resolve;
+    var resolve3 = path.resolve;
     var sep = path.sep;
     var BYTES_RANGE_REGEXP = /^ *bytes=/;
     var MAX_MAXAGE = 60 * 60 * 24 * 365 * 1e3;
@@ -19157,7 +19157,7 @@ var require_send = __commonJS({
       this._maxage = opts.maxAge || opts.maxage;
       this._maxage = typeof this._maxage === "string" ? ms(this._maxage) : Number(this._maxage);
       this._maxage = !isNaN(this._maxage) ? Math.min(Math.max(0, this._maxage), MAX_MAXAGE) : 0;
-      this._root = opts.root ? resolve(opts.root) : null;
+      this._root = opts.root ? resolve3(opts.root) : null;
       if (!this._root && opts.from) {
         this.from(opts.from);
       }
@@ -19181,7 +19181,7 @@ var require_send = __commonJS({
       return this;
     }, "send.index: pass index as option");
     SendStream.prototype.root = function root(path2) {
-      this._root = resolve(String(path2));
+      this._root = resolve3(String(path2));
       debug("root %s", this._root);
       return this;
     };
@@ -19337,7 +19337,7 @@ var require_send = __commonJS({
           return res;
         }
         parts = path2.split(sep);
-        path2 = normalize(join2(root, path2));
+        path2 = normalize(join3(root, path2));
       } else {
         if (UP_PATH_REGEXP.test(path2)) {
           debug('malicious path "%s"', path2);
@@ -19345,7 +19345,7 @@ var require_send = __commonJS({
           return res;
         }
         parts = normalize(path2).split(sep);
-        path2 = resolve(path2);
+        path2 = resolve3(path2);
       }
       if (containsDotFile(parts)) {
         var access = this._dotfiles;
@@ -19472,7 +19472,7 @@ var require_send = __commonJS({
           if (err) return self.onStatError(err);
           return self.error(404);
         }
-        var p = join2(path2, self._index[i]);
+        var p = join3(path2, self._index[i]);
         debug('stat "%s"', p);
         fs.stat(p, function(err2, stat) {
           if (err2) return next(err2);
@@ -20625,7 +20625,7 @@ var require_application = __commonJS({
     var deprecate = require_depd()("express");
     var flatten = require_array_flatten();
     var merge = require_utils_merge();
-    var resolve = __require("path").resolve;
+    var resolve3 = __require("path").resolve;
     var setPrototypeOf = require_setprototypeof();
     var hasOwnProperty = Object.prototype.hasOwnProperty;
     var slice = Array.prototype.slice;
@@ -20664,7 +20664,7 @@ var require_application = __commonJS({
       this.mountpath = "/";
       this.locals.settings = this.settings;
       this.set("view", View);
-      this.set("views", resolve("views"));
+      this.set("views", resolve3("views"));
       this.set("jsonp callback name", "callback");
       if (env === "production") {
         this.enable("view cache");
@@ -21909,7 +21909,7 @@ var require_response = __commonJS({
     var send = require_send();
     var extname = path.extname;
     var mime = send.mime;
-    var resolve = path.resolve;
+    var resolve3 = path.resolve;
     var vary = require_vary();
     var res = Object.create(http.ServerResponse.prototype);
     module.exports = res;
@@ -22168,7 +22168,7 @@ var require_response = __commonJS({
       }
       opts = Object.create(opts);
       opts.headers = headers;
-      var fullPath = !opts.root ? resolve(path2) : path2;
+      var fullPath = !opts.root ? resolve3(path2) : path2;
       return this.sendFile(fullPath, opts, done);
     };
     res.contentType = res.type = function contentType(type) {
@@ -22434,7 +22434,7 @@ var require_serve_static = __commonJS({
     var encodeUrl = require_encodeurl();
     var escapeHtml = require_escape_html();
     var parseUrl = require_parseurl();
-    var resolve = __require("path").resolve;
+    var resolve3 = __require("path").resolve;
     var send = require_send();
     var url = __require("url");
     module.exports = serveStatic;
@@ -22454,7 +22454,7 @@ var require_serve_static = __commonJS({
         throw new TypeError("option setHeaders must be function");
       }
       opts.maxage = opts.maxage || opts.maxAge || 0;
-      opts.root = resolve(root);
+      opts.root = resolve3(root);
       var onDirectory = redirect ? createRedirectDirectoryListener() : createNotFoundDirectoryListener();
       return function serveStatic2(req, res, next) {
         if (req.method !== "GET" && req.method !== "HEAD") {
@@ -26263,6 +26263,7 @@ var RelayClient = class {
   heartbeatTimer = null;
   connected = false;
   stopped = false;
+  generation = 0;
   pendingCallbacks = /* @__PURE__ */ new Map();
   /** Responses that arrived with nobody waiting, claimable by a retry. */
   orphanResponses = /* @__PURE__ */ new Map();
@@ -26274,17 +26275,46 @@ var RelayClient = class {
     return this.connected;
   }
   start() {
+    if (!this.stopped && this.ws) return;
     this.stopped = false;
-    this.connect();
+    const generation = ++this.generation;
+    this.connect(generation);
   }
   stop() {
-    this.stopped = true;
-    this.clearTimers();
-    if (this.ws) {
-      this.ws.close(1e3, "Client shutting down");
-      this.ws = null;
+    const socket = this.beginStop();
+    try {
+      socket?.close(1e3, "Client shutting down");
+    } catch {
     }
-    this.connected = false;
+  }
+  /** Stop reconnect activity and wait a bounded time for the socket to close. */
+  async stopAndWait(timeoutMs = 5e3) {
+    const socket = this.beginStop();
+    if (!socket || socket.readyState === wrapper_default.CLOSED) return { closeTimedOut: false };
+    return new Promise((resolve3) => {
+      let settled = false;
+      const finish = (closeTimedOut) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve3({ closeTimedOut });
+      };
+      const timer = setTimeout(() => {
+        finish(true);
+        try {
+          socket.terminate();
+        } catch {
+        }
+      }, timeoutMs);
+      timer.unref?.();
+      socket.once("close", () => finish(false));
+      socket.once("error", () => finish(false));
+      try {
+        socket.close(1e3, "Client shutting down");
+      } catch {
+        finish(false);
+      }
+    });
   }
   /**
    * Send a task to another agent via the relay.
@@ -26333,8 +26363,8 @@ var RelayClient = class {
     };
     this.send(response);
   }
-  connect() {
-    if (this.stopped) return;
+  connect(generation) {
+    if (!this.isCurrent(generation)) return;
     const url = this.options.relay.url;
     this.logger.info(`[perkos-a2a] Connecting to relay: ${url}`);
     try {
@@ -26342,17 +26372,23 @@ var RelayClient = class {
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       this.logger.error(`[perkos-a2a] Failed to create WebSocket: ${msg}`);
-      this.scheduleReconnect();
+      this.scheduleReconnect(generation);
       return;
     }
-    this.ws.on("open", () => {
+    const socket = this.ws;
+    socket.on("open", () => {
+      if (!this.isCurrent(generation, socket)) {
+        socket.close(1e3, "Stale relay generation");
+        return;
+      }
       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) => {
+    socket.on("message", (data) => {
+      if (!this.isCurrent(generation, socket)) return;
       let msg;
       try {
         msg = JSON.parse(data.toString());
@@ -26362,15 +26398,17 @@ var RelayClient = class {
       }
       this.handleMessage(msg);
     });
-    this.ws.on("close", (code, reason) => {
+    socket.on("close", (code, reason) => {
+      if (!this.isCurrent(generation, socket)) return;
       this.connected = false;
       this.clearTimers();
       if (!this.stopped) {
         this.logger.info(`[perkos-a2a] Relay connection closed (${code}: ${reason || "no reason"}). Reconnecting...`);
-        this.scheduleReconnect();
+        this.scheduleReconnect(generation);
       }
     });
-    this.ws.on("error", (err) => {
+    socket.on("error", (err) => {
+      if (!this.isCurrent(generation, socket)) return;
       this.logger.error(`[perkos-a2a] Relay WebSocket error: ${err.message}`);
     });
   }
@@ -26450,7 +26488,7 @@ var RelayClient = class {
     }
   }
   async sendAndWait(msg, expectedType, timeoutMs) {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve3, reject) => {
       const timer = setTimeout(() => {
         this.pendingCallbacks.delete(msg.id);
         reject(new Error(`Relay request timed out after ${timeoutMs}ms`));
@@ -26462,8 +26500,12 @@ var RelayClient = class {
           if (response.type === "error") {
             reject(new Error(`Relay error: ${response.payload.message}`));
           } else {
-            resolve(response);
+            resolve3(response);
           }
+        },
+        cancel: (error) => {
+          clearTimeout(timer);
+          reject(error);
         }
       });
       this.send(msg);
@@ -26481,10 +26523,10 @@ var RelayClient = class {
       this.send(msg);
     }, HEARTBEAT_INTERVAL_MS);
   }
-  scheduleReconnect() {
-    if (this.stopped) return;
+  scheduleReconnect(generation) {
+    if (!this.isCurrent(generation)) return;
     this.reconnectTimer = setTimeout(() => {
-      this.connect();
+      if (this.isCurrent(generation)) this.connect(generation);
     }, this.reconnectMs);
     this.reconnectMs = Math.min(this.reconnectMs * 2, MAX_RECONNECT_MS);
   }
@@ -26498,6 +26540,23 @@ var RelayClient = class {
       this.reconnectTimer = null;
     }
   }
+  isCurrent(generation, socket) {
+    return !this.stopped && generation === this.generation && (!socket || socket === this.ws);
+  }
+  beginStop() {
+    if (this.stopped && !this.ws) return null;
+    this.stopped = true;
+    this.generation += 1;
+    this.clearTimers();
+    const error = new Error("CLIENT_STOPPED");
+    for (const pending of this.pendingCallbacks.values()) pending.cancel(error);
+    this.pendingCallbacks.clear();
+    this.orphanResponses.clear();
+    const socket = this.ws;
+    this.ws = null;
+    this.connected = false;
+    return socket;
+  }
 };
 
 // src/relay.ts
@@ -26533,17 +26592,33 @@ var RelayHub = class {
     });
     this.heartbeatTimer = setInterval(() => this.checkHeartbeats(), this.config.heartbeatIntervalMs);
   }
-  stop() {
+  async stop(timeoutMs = 5e3) {
     if (this.heartbeatTimer) {
       clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;
     }
     if (this.wss) {
+      const wss = this.wss;
+      this.wss = null;
       for (const agent of this.agents.values()) {
         agent.ws.close(1001, "Relay shutting down");
       }
-      this.wss.close();
-      this.wss = null;
+      await new Promise((resolve3) => {
+        let settled = false;
+        const done = () => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          resolve3();
+        };
+        const timer = setTimeout(() => {
+          for (const client of wss.clients) client.terminate();
+          done();
+        }, timeoutMs);
+        timer.unref?.();
+        wss.close(() => done());
+      });
+      this.agents.clear();
       this.logger.info("[perkos-a2a] Relay hub stopped");
     }
   }
@@ -26938,6 +27013,12 @@ var A2AServer = class {
   taskResultHandler = null;
   taskFailureHandler = null;
   lastRuntimeDelivery = null;
+  httpServer = null;
+  lifecycleState = "new";
+  generation = 0;
+  startPromise = null;
+  stopPromise = null;
+  operations = /* @__PURE__ */ new Set();
   constructor(config, logger) {
     this.config = config;
     this.logger = logger || { info: console.log, error: console.error };
@@ -27068,6 +27149,9 @@ var A2AServer = class {
     });
   }
   async handleSendMessage(params, rpcId) {
+    if (this.lifecycleState === "stopping" || this.lifecycleState === "stopped") {
+      return this.error(rpcId, 503, "SERVER_RELOADING");
+    }
     const message = params.message;
     const taskId = randomUUID4();
     const contextId = message?.contextId || randomUUID4();
@@ -27088,10 +27172,11 @@ var A2AServer = class {
     this.logger.info(
       `[perkos-a2a] Task ${taskId} received from ${task.metadata?.fromAgent}`
     );
-    void this.processTask(task);
+    const generation = this.generation;
+    this.trackOperation(this.processTask(task, generation));
     return this.success(rpcId, task);
   }
-  async processTask(task) {
+  async processTask(task, generation) {
     task.status = { state: "working", timestamp: (/* @__PURE__ */ new Date()).toISOString() };
     this.tasks.set(task.id, structuredClone(task));
     const textParts = task.messages.flatMap((m) => m.parts || []).filter((p) => p.kind === "text").map((p) => p.text).join("\n");
@@ -27135,9 +27220,11 @@ var A2AServer = class {
           timestamp: (/* @__PURE__ */ new Date()).toISOString()
         };
       }
+      if (!this.isGenerationActive(generation)) return;
       this.tasks.set(task.id, structuredClone(task));
       this.logger.info(`[perkos-a2a] Task ${task.id} completed`);
     } catch (err) {
+      if (!this.isGenerationActive(generation)) return;
       const msg = err instanceof Error ? err.message : String(err);
       if (this.taskFailureHandler) {
         await this.taskFailureHandler(task, msg);
@@ -27237,7 +27324,7 @@ var A2AServer = class {
   async waitForRemoteTaskTerminal(targetUrl, headers, taskId, timeoutMs = 45e3, pollMs = 1e3) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-      await new Promise((resolve) => setTimeout(resolve, pollMs));
+      await new Promise((resolve3) => setTimeout(resolve3, pollMs));
       const response = await fetch(`${targetUrl}/a2a/jsonrpc`, {
         method: "POST",
         headers,
@@ -27261,7 +27348,7 @@ var A2AServer = class {
       if (task && isTerminalTaskState(task.status?.state)) {
         return this.success(randomUUID4(), structuredClone(task));
       }
-      await new Promise((resolve) => setTimeout(resolve, pollMs));
+      await new Promise((resolve3) => setTimeout(resolve3, pollMs));
     }
     return null;
   }
@@ -27324,10 +27411,17 @@ var A2AServer = class {
   }
   /** Handle an inbound task received via the relay */
   handleRelayTask(msg) {
+    if (this.lifecycleState !== "running") {
+      this.relayClient?.sendTaskResponse(
+        msg,
+        this.error(String(msg.payload?.id ?? msg.id), 503, "SERVER_RELOADING")
+      );
+      return;
+    }
     const payload = msg.payload;
     const params = payload.params || payload;
     const rpcId = payload.id || msg.id;
-    this.handleSendMessage(params, rpcId).then(async (response) => {
+    const operation = 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)) {
@@ -27358,6 +27452,7 @@ var A2AServer = class {
       this.logger.error(`[perkos-a2a] Failed to process relay task: ${errMsg2}`);
       this.relayClient?.sendTaskResponse(msg, this.error(rpcId, -32603, errMsg2));
     });
+    this.trackOperation(operation);
   }
   startRelayClient() {
     const relay = this.config.relay;
@@ -27389,13 +27484,30 @@ var A2AServer = class {
     this.relayHub.start();
   }
   async start() {
+    if (this.lifecycleState === "running") return;
+    if (this.lifecycleState === "starting" && this.startPromise) return this.startPromise;
+    if (this.lifecycleState === "stopping" && this.stopPromise) await this.stopPromise;
+    const generation = ++this.generation;
+    this.lifecycleState = "starting";
+    const startPromise = this.startGeneration(generation);
+    this.startPromise = startPromise;
+    try {
+      await startPromise;
+      if (this.isGenerationActive(generation, "starting")) this.lifecycleState = "running";
+    } finally {
+      if (this.startPromise === startPromise) this.startPromise = null;
+    }
+  }
+  async startGeneration(generation) {
     const mode = this.config.mode || "auto";
     if (mode === "relay") {
+      if (!this.isGenerationActive(generation, "starting")) return;
       this.clientOnly = true;
       this.startRelayHub();
       return;
     }
     if (mode === "client-only") {
+      if (!this.isGenerationActive(generation, "starting")) return;
       this.clientOnly = true;
       this.startRelayClient();
       if (!this.config.relay?.enabled) {
@@ -27406,12 +27518,14 @@ var A2AServer = class {
       return;
     }
     if (mode === "full") {
-      this.tryListen(this.config.port);
+      await this.tryListen(this.config.port, 1, generation);
+      if (!this.isGenerationActive(generation, "starting")) return;
       this.startRelayClient();
       return;
     }
     try {
       const net = await detectNetworking();
+      if (!this.isGenerationActive(generation, "starting")) return;
       if (net.isBehindNat && !net.hasTailscale) {
         if (this.config.relay?.enabled) {
           this.logger.info(
@@ -27434,37 +27548,129 @@ var A2AServer = class {
       }
     } catch {
     }
-    this.tryListen(this.config.port);
+    await this.tryListen(this.config.port, 1, generation);
+    if (!this.isGenerationActive(generation, "starting")) return;
     this.startRelayClient();
   }
-  tryListen(port, attempt = 1) {
+  stop(options = {}) {
+    if (this.lifecycleState === "stopping" && this.stopPromise) return this.stopPromise;
+    if (this.lifecycleState === "stopped" || this.lifecycleState === "new") {
+      this.lifecycleState = "stopped";
+      this.generation += 1;
+      return Promise.resolve();
+    }
+    this.lifecycleState = "stopping";
+    this.generation += 1;
+    const priorStart = this.startPromise;
+    let stopPromise;
+    stopPromise = (async () => {
+      try {
+        const timeoutMs = options.timeoutMs ?? 5e3;
+        const drainMs = Math.min(options.drainMs ?? 3e3, timeoutMs);
+        await this.teardownResources(timeoutMs);
+        await priorStart?.catch(() => void 0);
+        await this.teardownResources(timeoutMs);
+        await this.drainOperations(drainMs);
+        for (const task of this.tasks.values()) {
+          if (!isTerminalTaskState(task.status.state)) {
+            task.status = {
+              state: "failed",
+              timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+              message: { role: "agent", parts: [{ kind: "text", text: "interrupted_by_reload" }] }
+            };
+          }
+        }
+        this.lifecycleState = "stopped";
+        this.logger.info(`[perkos-a2a] A2A server stopped${options.reason ? ` (${options.reason})` : ""}`);
+      } finally {
+        if (this.stopPromise === stopPromise) this.stopPromise = null;
+      }
+    })();
+    this.stopPromise = stopPromise;
+    return stopPromise;
+  }
+  tryListen(port, attempt, generation) {
     const maxAttempts = 3;
-    try {
+    return new Promise((resolveStart) => {
+      if (!this.isGenerationActive(generation, "starting")) {
+        resolveStart();
+        return;
+      }
       const bindHost = this.config.bindHost || "0.0.0.0";
       const srv = this.app.listen(port, bindHost, () => {
+        if (!this.isGenerationActive(generation, "starting")) {
+          srv.close(() => resolveStart());
+          return;
+        }
+        this.httpServer = srv;
         this.logger.info(
           `[perkos-a2a] ${this.config.agentName} server on ${bindHost}:${port}`
         );
         this.agentCard.url = `${(this.config.publicUrl || `http://localhost:${port}`).replace(/\/+$/, "")}/a2a/jsonrpc`;
+        resolveStart();
       });
       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);
+          void this.tryListen(nextPort, attempt + 1, generation).then(resolveStart);
         } 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;
+          resolveStart();
         } else {
           this.logger.error(`[perkos-a2a] Server error: ${err.message}`);
+          resolveStart();
         }
       });
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      this.logger.error(`[perkos-a2a] Failed to start server: ${msg}`);
-    }
+    });
+  }
+  isGenerationActive(generation, expectedState) {
+    return generation === this.generation && (expectedState ? this.lifecycleState === expectedState : this.lifecycleState !== "stopping" && this.lifecycleState !== "stopped");
+  }
+  trackOperation(operation) {
+    this.operations.add(operation);
+    void operation.finally(() => this.operations.delete(operation)).catch(() => void 0);
+  }
+  async drainOperations(timeoutMs) {
+    if (this.operations.size === 0 || timeoutMs <= 0) return;
+    await Promise.race([
+      Promise.allSettled([...this.operations]),
+      new Promise((resolveDrain) => {
+        const timer = setTimeout(resolveDrain, timeoutMs);
+        timer.unref?.();
+      })
+    ]);
+  }
+  async teardownResources(timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    const remaining = () => Math.max(1, deadline - Date.now());
+    const relayClient = this.relayClient;
+    this.relayClient = null;
+    await relayClient?.stopAndWait(remaining());
+    const relayHub = this.relayHub;
+    this.relayHub = null;
+    await relayHub?.stop(remaining());
+    const httpServer = this.httpServer;
+    this.httpServer = null;
+    if (!httpServer) return;
+    await new Promise((resolveClose) => {
+      let settled = false;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolveClose();
+      };
+      const timer = setTimeout(() => {
+        httpServer.closeAllConnections?.();
+        done();
+      }, remaining());
+      timer.unref?.();
+      httpServer.close(() => done());
+    });
   }
   getExpressApp() {
     return this.app;
@@ -27473,6 +27679,9 @@ var A2AServer = class {
 
 // src/index.ts
 import { randomUUID as randomUUID6 } from "crypto";
+import { readFileSync as readFileSync3 } from "node:fs";
+import { dirname, resolve as resolve2 } from "node:path";
+import { fileURLToPath } from "node:url";
 
 // src/agentic-actions.ts
 var FALLBACK_AGENT_ALIASES = [
@@ -28017,7 +28226,7 @@ var ChatStore = class {
     let firstMessageAt = null;
     let lastMessageAt = null;
     let leftover = "";
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve3, reject) => {
       stream.on("data", (chunk) => {
         const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
         hash.update(text);
@@ -28057,7 +28266,7 @@ var ChatStore = class {
           hash.update(metaRaw);
         } catch {
         }
-        resolve({
+        resolve3({
           transcriptHash: hash.digest("hex"),
           hashAlgo: "sha256",
           messageCount,
@@ -28526,12 +28735,97 @@ function startPlatformHeartbeat(opts) {
   };
 }
 
+// src/runtime-evidence.ts
+import { createHmac } from "node:crypto";
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync as readFileSync2,
+  renameSync,
+  writeFileSync
+} from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join2, resolve } from "node:path";
+var RUNTIME_EVIDENCE_SCHEMA_VERSION = 1;
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, canonicalize(child)])
+  );
+}
+function canonicalConfigJson(config) {
+  return JSON.stringify({ schemaVersion: RUNTIME_EVIDENCE_SCHEMA_VERSION, config: canonicalize(config) });
+}
+function configFingerprint(config, hmacKeyHex) {
+  if (!/^[a-f0-9]{64}$/u.test(hmacKeyHex)) throw new Error("runtime evidence HMAC key is invalid");
+  return createHmac("sha256", Buffer.from(hmacKeyHex, "hex")).update(canonicalConfigJson(config)).digest("hex");
+}
+function runtimeEvidenceDir(stateDir) {
+  return resolve(stateDir ?? process.env.OPENCLAW_STATE_DIR ?? join2(homedir3(), ".openclaw"), "perkos-a2a");
+}
+function runtimeAttemptPath(stateDir) {
+  return join2(runtimeEvidenceDir(stateDir), "active-attempt.json");
+}
+function runtimeStatusPath(stateDir) {
+  return join2(runtimeEvidenceDir(stateDir), "runtime-status.json");
+}
+function configAgentId(config) {
+  if (config.platform?.agentId) return config.platform.agentId;
+  const match = config.platform?.heartbeatUrl?.match(/\/agents\/([^/]+)\/heartbeat/u);
+  return match?.[1] ?? "unknown";
+}
+function recordRuntimeLoadEvidence(input) {
+  const evidenceDir = runtimeEvidenceDir(input.stateDir);
+  let attempt;
+  try {
+    attempt = JSON.parse(readFileSync2(runtimeAttemptPath(input.stateDir), "utf8"));
+  } catch {
+    input.logger.info(`[perkos-a2a] config loaded version=${input.version} agentId=${configAgentId(input.config)} attemptId=none`);
+    return null;
+  }
+  const agentId = configAgentId(input.config);
+  if (attempt.schemaVersion !== RUNTIME_EVIDENCE_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 status = {
+    schemaVersion: RUNTIME_EVIDENCE_SCHEMA_VERSION,
+    loadedAt: (input.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
+    version: input.version,
+    agentId,
+    fingerprint: configFingerprint(input.config, attempt.hmacKeyHex),
+    attemptId: attempt.attemptId,
+    pid: process.pid,
+    pluginRoot: resolve(input.pluginRoot)
+  };
+  mkdirSync(evidenceDir, { recursive: true, mode: 448 });
+  const target = runtimeStatusPath(input.stateDir);
+  const temporary = `${target}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(status, null, 2)}
+`, { mode: 384 });
+  renameSync(temporary, target);
+  chmodSync(target, 384);
+  input.logger.info(
+    `[perkos-a2a] config loaded version=${status.version} agentId=${status.agentId} attemptId=${status.attemptId} fingerprint=${status.fingerprint}`
+  );
+  return status;
+}
+
 // src/types.ts
 function isWebhookEvent(msg) {
   return msg.type === "webhook_event";
 }
 
 // src/index.ts
+function loadedPluginVersion() {
+  try {
+    const manifest = JSON.parse(readFileSync3(new URL("../openclaw.plugin.json", import.meta.url), "utf8"));
+    return typeof manifest.version === "string" ? manifest.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
 function wakeGatewayAgent(requestHeartbeatNow, reason, logger, sessionKey = "agent:main") {
   if (typeof requestHeartbeatNow === "function") {
     try {
@@ -28783,6 +29077,28 @@ async function deliverToHermes(config, message, logger) {
   }
   logger.info(`[perkos-a2a] Delivered inbound A2A task to Hermes API session ${sessionKey} via ${url}`);
 }
+var A2A_LIFECYCLE_REGISTRY = /* @__PURE__ */ Symbol.for("@perkos/perkos-a2a:lifecycle-registry");
+function lifecycleRegistry() {
+  const root = globalThis;
+  return root[A2A_LIFECYCLE_REGISTRY] ??= /* @__PURE__ */ new Map();
+}
+function a2aLifecycleKey(config) {
+  const rawRelayUrl = (config.relay?.url || "no-relay").trim();
+  let relayUrl = rawRelayUrl.replace(/[?#].*$/u, "").replace(/\/+$/u, "").toLowerCase();
+  try {
+    const parsed = new URL(rawRelayUrl);
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    relayUrl = parsed.toString().replace(/\/+$/u, "").toLowerCase();
+  } catch {
+  }
+  const heartbeatUrl = config.platform?.heartbeatUrl || "";
+  const idFromHeartbeat = heartbeatUrl.match(/\/agents\/([^/]+)\/heartbeat(?:\?|$)/u)?.[1];
+  const agentId = config.platform?.agentId || idFromHeartbeat || config.agentName.trim().toLowerCase();
+  return `${relayUrl}|${agentId}`;
+}
 function register(api) {
   const pluginConfig = api.config?.plugins?.entries?.["perkos-a2a"]?.config || {
     agentName: "agent",
@@ -28791,7 +29107,16 @@ function register(api) {
     peers: {}
   };
   const logger = api.logger || console;
+  const pluginVersion = loadedPluginVersion();
+  recordRuntimeLoadEvidence({
+    config: pluginConfig,
+    version: pluginVersion,
+    pluginRoot: resolve2(dirname(fileURLToPath(import.meta.url)), ".."),
+    logger
+  });
   const server = new A2AServer(pluginConfig, logger);
+  const lifecycleKey = a2aLifecycleKey(pluginConfig);
+  const lifecycleInstanceId = randomUUID6();
   const pendingTasks = [];
   const enqueueSystemEvent = api.runtime?.system?.enqueueSystemEvent;
   const requestHeartbeatNow = api.runtime?.system?.requestHeartbeatNow;
@@ -28963,12 +29288,22 @@ function register(api) {
   });
   api.registerService({
     id: "perkos-a2a",
-    start: () => {
-      server.start();
+    start: async () => {
+      const registry = lifecycleRegistry();
+      const previous = registry.get(lifecycleKey);
+      if (previous && previous.instanceId !== lifecycleInstanceId) {
+        logger.info(`[perkos-a2a] Waiting for previous relay generation to stop for ${pluginConfig.agentName}`);
+        await previous.server.stop({ reason: "replaced", timeoutMs: 5e3, drainMs: 3e3 });
+      }
+      registry.set(lifecycleKey, { instanceId: lifecycleInstanceId, server });
+      await server.start();
       logger.info(`[perkos-a2a] A2A server started for ${pluginConfig.agentName}`);
     },
-    stop: () => {
+    stop: async () => {
       logger.info("[perkos-a2a] A2A server stopping");
+      await server.stop({ reason: "openclaw-service-stop", timeoutMs: 5e3, drainMs: 3e3 });
+      const registry = lifecycleRegistry();
+      if (registry.get(lifecycleKey)?.instanceId === lifecycleInstanceId) registry.delete(lifecycleKey);
     }
   });
   const chatApiKey = pluginConfig.chat?.apiKey || pluginConfig.relay?.apiKey;
@@ -29114,7 +29449,7 @@ function register(api) {
           url: pluginConfig.platform?.heartbeatUrl,
           relayKey: pluginConfig.relay?.apiKey,
           runtimeKind: "openclaw",
-          version: "0.12.26",
+          version: pluginVersion,
           intervalMs: pluginConfig.platform?.heartbeatIntervalMs
         });
       },
@@ -29443,18 +29778,18 @@ function register(api) {
         let portAvailable = true;
         try {
           const netMod = await import("net");
-          await new Promise((resolve, reject) => {
+          await new Promise((resolve3, reject) => {
             const srv = netMod.createServer();
             srv.once("error", (err) => {
               if (err.code === "EADDRINUSE") {
                 portAvailable = false;
-                resolve();
+                resolve3();
               } else {
                 reject(err);
               }
             });
             srv.listen(pluginConfig.port, () => {
-              srv.close(() => resolve());
+              srv.close(() => resolve3());
             });
           });
         } catch {
@@ -29505,6 +29840,7 @@ export {
   ChatStore,
   RelayClient,
   RelayHub,
+  a2aLifecycleKey,
   alignOpenClawChatSessionModel,
   register as default,
   detectNetworking,