@perkos/perkos-a2a 0.12.30 → 0.12.31

package/README.md

@@ -170,7 +170,7 @@ openclaw gateway restart
 
 #### Official idempotent connection
 
-Version 0.12.30+ ships the machine-readable `perkos-a2a connect` CLI. The
+Version 0.12.31+ 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
@@ -203,7 +203,7 @@ values are never printed.
 
 ```bash
 A2A_RELAY_API_KEY='<credential-from-invitation>' \
-npx --yes @perkos/perkos-a2a@0.12.30 connect \
+npx --yes @perkos/perkos-a2a@0.12.31 connect \
   --artifact ./perkos-a2a.tgz \
   --sha256 '<sha256-from-the-official-invitation>' \
   --agent-name '<agent-name>' \

package/dist/index.d.ts

@@ -51,5 +51,7 @@ export declare function runOpenClawChatTurn(api: any, config: A2APluginConfig, s
 }): Promise<string | null>;
 /** Build a bounded, agent-local transcript so every runtime turn has continuity. */
 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;
 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;AAYH,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,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,GAAG,QAq1BxC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,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;AAoDD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAe/D;AAED,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,GAAG,QAi2BxC"}

package/dist/index.js

@@ -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}`);
     });
   }
@@ -26464,6 +26502,10 @@ var RelayClient = class {
           } else {
             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);
@@ -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;
@@ -28871,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",
@@ -28887,6 +29115,8 @@ function register(api) {
     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;
@@ -29058,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;
@@ -29600,6 +29840,7 @@ export {
   ChatStore,
   RelayClient,
   RelayHub,
+  a2aLifecycleKey,
   alignOpenClawChatSessionModel,
   register as default,
   detectNetworking,