@okxweb3/a2a-node 0.2.17 → 0.2.18

package/dist/index.js

@@ -22179,7 +22179,7 @@ var require_retry_promise = __commonJS({
         return true;
       }
     };
-    function wait3(ms) {
+    function wait2(ms) {
       return __awaiter(this, void 0, void 0, function() {
         return __generator(this, function(_a) {
           return [2, new Promise(function(resolve11) {
@@ -22188,7 +22188,7 @@ var require_retry_promise = __commonJS({
         });
       });
     }
-    exports2.wait = wait3;
+    exports2.wait = wait2;
     function retry2(f, config) {
       return __awaiter(this, void 0, void 0, function() {
         var effectiveConfig;
@@ -22278,7 +22278,7 @@ var require_retry_promise = __commonJS({
               return [3, 5];
             case 5:
               millisToWait = delay(i + 1, config.delay);
-              return [4, wait3(millisToWait > config.maxBackOff ? config.maxBackOff : millisToWait)];
+              return [4, wait2(millisToWait > config.maxBackOff ? config.maxBackOff : millisToWait)];
             case 6:
               _a.sent();
               if (done()) {
@@ -28761,7 +28761,7 @@ var init_withResolvers = __esm({
 });
 
 // ../../node_modules/viem/_esm/utils/promise/createBatchScheduler.js
-function createBatchScheduler({ fn, id, shouldSplitBatch, wait: wait3 = 0, sort }) {
+function createBatchScheduler({ fn, id, shouldSplitBatch, wait: wait2 = 0, sort }) {
   const exec2 = async () => {
     const scheduler = getScheduler();
     flush2();
@@ -28799,7 +28799,7 @@ function createBatchScheduler({ fn, id, shouldSplitBatch, wait: wait3 = 0, sort
         return promise;
       }
       setScheduler({ args, resolve: resolve11, reject });
-      setTimeout(exec2, wait3);
+      setTimeout(exec2, wait2);
       return promise;
     }
   };
@@ -32465,7 +32465,7 @@ var init_sentry_config = __esm({
     environment = process.env.SENTRY_ENV === "dev" ? "dev" : "prod";
     SENTRY_CONFIG = {
       projectName: "okx/openclaw-okx-a2a-extension",
-      release: "0.2.17",
+      release: "0.2.18",
       environment,
       runtimeContainer: normalizeRuntimeContainer(process.env.OKX_A2A_RUNTIME_CONTAINER)
     };
@@ -33421,7 +33421,7 @@ async function getCurrentNodeCliVersion() {
   return await getGlobalNpmPackageVersion(UPDATE_PACKAGES.node) ?? getBundledNodeCliVersion();
 }
 function getBundledNodeCliVersion() {
-  return true ? "0.2.17" : null;
+  return true ? "0.2.18" : null;
 }
 function readConfiguredAiProvider() {
   const explicit = process.env.OKX_A2A_AI_PROVIDER || process.env.OKX_AGENT_TASK_AI_CLI;
@@ -33631,7 +33631,7 @@ async function updateHermes(release, options) {
   }
 }
 async function installGatewayPluginForDoctor(target) {
-  const release = isPrereleaseVersion("0.2.17") ? "beta" : "latest";
+  const release = isPrereleaseVersion("0.2.18") ? "beta" : "latest";
   const insideTargetGateway = detectGatewayInvocation() === target;
   const options = {
     restart: !insideTargetGateway,
@@ -49043,7 +49043,6 @@ function createAsyncStreamProxy(stream) {
     }
   });
 }
-var wait = (ms) => new Promise((resolve11) => setTimeout(resolve11, ms));
 var DEFAULT_RETRY_DELAY = 6e4;
 var DEFAULT_RETRY_ATTEMPTS = 10;
 var createStream = async (streamFunction, streamValueMutator, options) => {
@@ -49052,82 +49051,161 @@ var createStream = async (streamFunction, streamValueMutator, options) => {
     throw new StreamInvalidRetryAttemptsError();
   }
   const asyncStream = new AsyncStream();
+  let stopped = false;
+  let current;
+  let recovering = false;
+  let cancelDelay;
+  const isStopped = () => stopped;
+  const isCurrent = (native) => !stopped && current === native;
+  asyncStream.onDone = () => {
+    if (stopped) {
+      return;
+    }
+    stopped = true;
+    cancelDelay?.();
+    const native = current;
+    current = void 0;
+    native?.closer?.end();
+  };
+  const delay = (ms) => new Promise((resolve11) => {
+    const timer = setTimeout(() => {
+      cancelDelay = void 0;
+      resolve11();
+    }, ms);
+    cancelDelay = () => {
+      clearTimeout(timer);
+      cancelDelay = void 0;
+      resolve11();
+    };
+  });
+  const reportError = (error) => {
+    if (!stopped) {
+      onError?.(error);
+    }
+  };
+  const deliver = (value) => {
+    if (stopped || value === void 0) {
+      return;
+    }
+    asyncStream.push(value);
+    onValue?.(value);
+  };
   const streamCallback = (error, value) => {
+    if (stopped) {
+      return;
+    }
     if (error) {
       onError?.(error);
       return;
     }
-    if (value !== void 0) {
-      try {
-        if (streamValueMutator) {
-          const mutatedValue = streamValueMutator(value);
-          if ((0, import_types.isPromise)(mutatedValue)) {
-            void mutatedValue.then((mutatedValue2) => {
-              if (mutatedValue2 !== void 0) {
-                asyncStream.push(mutatedValue2);
-                onValue?.(mutatedValue2);
-              }
-            }).catch((error2) => {
-              onError?.(error2);
-            });
-          } else {
-            if (mutatedValue !== void 0) {
-              asyncStream.push(mutatedValue);
-              onValue?.(mutatedValue);
-            }
-          }
+    if (value === void 0) {
+      return;
+    }
+    try {
+      if (streamValueMutator) {
+        const mutatedValue = streamValueMutator(value);
+        if ((0, import_types.isPromise)(mutatedValue)) {
+          void mutatedValue.then(deliver).catch(reportError);
         } else {
-          asyncStream.push(value);
-          onValue?.(value);
+          deliver(mutatedValue);
         }
-      } catch (error2) {
-        onError?.(error2);
+      } else {
+        deliver(value);
       }
+    } catch (error2) {
+      reportError(error2);
     }
   };
-  const retry2 = async (retries = retryAttempts) => {
-    if (retries === 0) {
-      void asyncStream.end();
-      onError?.(new StreamFailedError(retryAttempts));
-      return;
+  const fail = (error) => {
+    void asyncStream.end();
+    onError?.(error);
+  };
+  const open2 = async () => {
+    if (stopped) {
+      return false;
+    }
+    const native = { ready: false, closed: false };
+    current = native;
+    const closer = await streamFunction(streamCallback, () => {
+      onNativeClose(native);
+    });
+    native.closer = closer;
+    if (!isCurrent(native)) {
+      closer.end();
+      return false;
+    }
+    await closer.waitForReady();
+    if (!isCurrent(native)) {
+      closer.end();
+      return false;
+    }
+    if (native.closed || closer.isClosed()) {
+      closer.end();
+      return false;
     }
-    await wait(retryDelay);
-    onRetry?.(retryAttempts - retries + 1, retryAttempts);
+    native.ready = true;
+    return true;
+  };
+  const restart = async () => {
     try {
-      const streamCloser = await streamFunction(streamCallback, () => {
-        onFail?.();
-        void retry2();
-      });
-      await streamCloser.waitForReady();
-      asyncStream.onDone = () => {
-        streamCloser.end();
-      };
-      onRestart?.();
-    } catch (error) {
-      onError?.(error);
-      void retry2(retries - 1);
+      for (let attempt = 1; attempt <= retryAttempts; attempt++) {
+        await delay(retryDelay);
+        if (isStopped()) {
+          return;
+        }
+        onRetry?.(attempt, retryAttempts);
+        let restarted = false;
+        try {
+          restarted = await open2();
+        } catch (error) {
+          reportError(error);
+        }
+        if (isStopped()) {
+          return;
+        }
+        if (restarted) {
+          try {
+            onRestart?.();
+          } catch (error) {
+            reportError(error);
+          }
+          return;
+        }
+      }
+      fail(new StreamFailedError(retryAttempts));
+    } finally {
+      recovering = false;
     }
   };
-  const startRetry = () => {
-    if (retryOnFail) {
-      void retry2();
-    } else {
-      void asyncStream.end();
-      onError?.(new StreamFailedError(0));
+  const recover = () => {
+    if (stopped || recovering) {
+      return;
     }
+    if (!retryOnFail) {
+      fail(new StreamFailedError(0));
+      return;
+    }
+    recovering = true;
+    void restart();
   };
+  function onNativeClose(native) {
+    if (!isCurrent(native) || native.closed) {
+      return;
+    }
+    native.closed = true;
+    onFail?.();
+    if (native.ready) {
+      recover();
+    }
+  }
+  let started = false;
   try {
-    const streamCloser = await streamFunction(streamCallback, () => {
-      onFail?.();
-      startRetry();
-    });
-    await streamCloser.waitForReady();
-    asyncStream.onDone = () => {
-      streamCloser.end();
-    };
+    started = await open2();
   } catch (error) {
-    onError?.(error);
-    startRetry();
+    reportError(error);
+  }
+  if (!started) {
+    recover();
   }
   return createAsyncStreamProxy(asyncStream);
 };
@@ -52371,7 +52449,7 @@ function observe(observerId, callbacks, fn) {
 }
 
 // ../../node_modules/viem/_esm/utils/wait.js
-async function wait2(time) {
+async function wait(time) {
   return new Promise((res) => setTimeout(res, time));
 }
 
@@ -52384,12 +52462,12 @@ function poll(fn, { emitOnBegin, initialWaitTime, interval }) {
     if (emitOnBegin)
       data = await fn({ unpoll: unwatch });
     const initialWait = await initialWaitTime?.(data) ?? interval;
-    await wait2(initialWait);
+    await wait(initialWait);
     const poll2 = async () => {
       if (!active)
         return;
       await fn({ unpoll: unwatch });
-      await wait2(interval);
+      await wait(interval);
       poll2();
     };
     poll2();
@@ -52712,7 +52790,7 @@ function withRetry(fn, { delay: delay_ = 100, retryCount = 2, shouldRetry: shoul
       const retry2 = async ({ error }) => {
         const delay = typeof delay_ === "function" ? delay_({ count, error }) : delay_;
         if (delay)
-          await wait2(delay);
+          await wait(delay);
         attemptRetry({ count: count + 1 });
       };
       try {
@@ -54875,7 +54953,7 @@ init_createBatchScheduler();
 function http(url, config = {}) {
   const { batch, fetchFn, fetchOptions, key = "http", methods, name = "HTTP JSON-RPC", onFetchRequest, onFetchResponse, retryDelay, raw } = config;
   return ({ chain, retryCount: retryCount_, timeout: timeout_ }) => {
-    const { batchSize = 1e3, wait: wait3 = 0 } = typeof batch === "object" ? batch : {};
+    const { batchSize = 1e3, wait: wait2 = 0 } = typeof batch === "object" ? batch : {};
     const retryCount = config.retryCount ?? retryCount_;
     const timeout = timeout_ ?? config.timeout ?? 1e4;
     const url_ = url || chain?.rpcUrls.default.http[0];
@@ -54896,7 +54974,7 @@ function http(url, config = {}) {
         const body = { method, params };
         const { schedule } = createBatchScheduler({
           id: url_,
-          wait: wait3,
+          wait: wait2,
           shouldSplitBatch(requests) {
             return requests.length > batchSize;
           },
@@ -55113,7 +55191,7 @@ var sepolia = /* @__PURE__ */ defineChain({
 
 // ../../node_modules/@xmtp/agent-sdk/dist/index.js
 var import_node_crypto7 = require("node:crypto");
-var version2 = "2.3.0";
+var version2 = "2.3.1";
 var fromSelf = (message, client) => {
   return message.senderInboxId === client.inboxId;
 };
@@ -57162,6 +57240,9 @@ function replayScanBackoffWithJitterMs(consecutiveFailures, randomValue = Math.r
   const jitteredMs = Math.round(baseMs * (0.9 + boundedRandom * 0.2));
   return Math.min(REPLAY_SCAN_MAX_BACKOFF_MS, jitteredMs);
 }
+function isListenHealthy(outcome) {
+  return outcome === "started" || outcome === "retrying";
+}
 function isOfflineReplayForTrigger(trigger) {
   return trigger === "startup";
 }
@@ -57171,6 +57252,18 @@ function replaySingleFlightDiscriminator(trigger, clientGeneration) {
     isOfflineReplayForTrigger(trigger)
   );
 }
+var XmtpClientCreateBlockedError = class extends Error {
+  reason;
+  address;
+  agentId;
+  constructor(reason, address, agentId) {
+    super(`xmtp client create blocked (${reason})`);
+    this.name = "XmtpClientCreateBlockedError";
+    this.reason = reason;
+    this.address = address;
+    this.agentId = agentId;
+  }
+};
 var XmtpService = class _XmtpService {
   static instance = null;
   env = process.env.XMTP_ENV ?? "production";
@@ -57208,6 +57301,25 @@ var XmtpService = class _XmtpService {
   streamRecoverySetTimeout = (callback, delayMs) => setTimeout(callback, delayMs);
   streamRecoveryClearTimeout = (timer) => clearTimeout(timer);
   streamStartSetTimeout = (callback, delayMs) => setTimeout(callback, delayMs);
+  xmtpAgentFactory = createAgentWithInstallationPrune;
+  // Old clients whose close() was not confirmed. Keyed by lower-cased address.
+  // The reference is kept only for controlled cleanup; it is never served.
+  pendingReleaseByAddress = /* @__PURE__ */ new Map();
+  // Addresses whose pending release was confirmed late (after the caller gave
+  // up waiting) and still need a replacement client on the next recycle.
+  releaseConfirmedNeedsCreate = /* @__PURE__ */ new Set();
+  // Lower-cased addresses owned by a create. The slot is held from before the
+  // SDK factory runs until the new client is registered in `clients` (or the
+  // create failed), so no flow can observe "no lock and no client".
+  clientCreateInFlight = /* @__PURE__ */ new Set();
+  // Clients whose close() was confirmed; a repeated release is a no-op.
+  releasedClients = /* @__PURE__ */ new WeakSet();
+  // One listener setup per client, shared by concurrent init/refresh callers.
+  listenTaskByClient = /* @__PURE__ */ new WeakMap();
+  inboundReplayGateOwners = /* @__PURE__ */ new WeakMap();
+  releaseWaitTimeoutMs = 3e4;
+  releaseWaitSetTimeout = (callback, delayMs) => setTimeout(callback, delayMs);
+  releaseWaitClearTimeout = (timer) => clearTimeout(timer);
   nextClientGeneration = 1;
   clientGenerationByClient = /* @__PURE__ */ new WeakMap();
   resolveStartupReplayCompletion;
@@ -57356,6 +57468,56 @@ var XmtpService = class _XmtpService {
     return { ok: remaining.length === 0, failures: remaining };
   }
   async createClientForAgent(agentInfo, options = {}) {
+    const address = agentInfo.communicationAddress;
+    const addressKey = address.toLowerCase();
+    let blockedReason;
+    if (this.pendingReleaseByAddress.has(addressKey)) {
+      blockedReason = "release_pending";
+    } else if (this.clientCreateInFlight.has(addressKey)) {
+      blockedReason = "create_in_flight";
+    } else if (this.getClientByAddress(address)) {
+      blockedReason = "client_active";
+    }
+    if (blockedReason) {
+      throw new XmtpClientCreateBlockedError(
+        blockedReason,
+        address,
+        agentInfo.agentId
+      );
+    }
+    this.clientCreateInFlight.add(addressKey);
+    try {
+      const created = await this.createClientForAgentGuarded(agentInfo, options);
+      await this.registerCreatedClient(created, options.logPrefix ?? "[xmtp-sdk]");
+      return created;
+    } finally {
+      this.clientCreateInFlight.delete(addressKey);
+    }
+  }
+  // Ownership hand-off, still inside the create slot: the new client becomes
+  // visible in `clients` before the slot is released. Never overwrites an
+  // existing registration; a conflicting new object is released, not dropped.
+  async registerCreatedClient(created, phase) {
+    const { address, agent, agentInfo } = created;
+    const addressKey = address.toLowerCase();
+    const existing = this.getClientByAddress(address);
+    if (existing && existing !== agent || this.pendingReleaseByAddress.has(addressKey)) {
+      const reason = existing ? "client_active" : "release_pending";
+      logWithTimestamp(
+        `[xmtp-sdk] create registration conflict (${reason}): ${address} (agentId=${agentInfo.agentId}), releasing the new client`
+      );
+      await this.releaseClient(
+        address,
+        agent,
+        agentInfo.agentId,
+        `${phase}/register-conflict`
+      );
+      throw new XmtpClientCreateBlockedError(reason, address, agentInfo.agentId);
+    }
+    this.stoppedAddresses.delete(addressKey);
+    this.clients.set(address, agent);
+  }
+  async createClientForAgentGuarded(agentInfo, options = {}) {
     const address = agentInfo.communicationAddress;
     const phase = options.logPrefix ?? "[xmtp-sdk]";
     const cooldown = getXmtpCreationCooldown();
@@ -57384,7 +57546,7 @@ var XmtpService = class _XmtpService {
     try {
       const signer = this.tools.createSigner(agentInfo);
       const dbPath = (inboxId2) => `${this.dataDir}/${inboxId2}-${this.env}.db3`;
-      const agent = await createAgentWithInstallationPrune(signer, {
+      const agent = await this.xmtpAgentFactory(signer, {
         dbPath,
         env: this.env
       }, {
@@ -57393,6 +57555,7 @@ var XmtpService = class _XmtpService {
         logPrefix: options.logPrefix
       });
       cooldown.recordCreateSuccess(decision);
+      this.releaseConfirmedNeedsCreate.delete(address.toLowerCase());
       if (decision.mode === "probe") {
         logger.info(LogEvent.XMTP_RATE_LIMIT_RECOVERED, {
           onchainosAgentId: agentInfo.agentId,
@@ -57430,6 +57593,128 @@ var XmtpService = class _XmtpService {
       throw err;
     }
   }
+  logReleaseNotConfirmed(address, agentId, phase, reason, err) {
+    logger.error(
+      LogEvent.XMTP_CLIENT_CLOSE_FAILED,
+      err instanceof Error ? err : new Error(`xmtp client close not confirmed (${reason})`),
+      { walletAddress: address, onchainosAgentId: agentId, phase, reason }
+    );
+  }
+  // Single release entry (recycle / refresh remove / failed replacement).
+  // Confirmation is ONLY a successful client.close(); a timeout, a missing
+  // close() or a close failure keeps the old reference in
+  // pendingReleaseByAddress and blocks new creates for that address.
+  async releaseClient(address, client, agentId, phase) {
+    const key = address.toLowerCase();
+    if (this.releasedClients.has(client)) {
+      this.unpublishClient(address, client, phase);
+      return true;
+    }
+    const existing = this.pendingReleaseByAddress.get(key);
+    if (existing?.inFlight) {
+      this.unpublishClient(address, client, phase);
+      return false;
+    }
+    const entry = existing ?? { client, agentId, phase };
+    entry.client = client;
+    entry.agentId = agentId;
+    entry.phase = phase;
+    this.pendingReleaseByAddress.set(key, entry);
+    this.unpublishClient(address, client, phase);
+    let timedOut = false;
+    const task = stopAndCloseXmtpClient(client, {
+      address,
+      agentId,
+      phase,
+      onCloseError: (err) => this.logReleaseNotConfirmed(address, agentId, phase, "close_threw", err)
+    }).then((result) => {
+      if (!result.stopped) {
+        logWithTimestamp(
+          `[xmtp-sdk] release: stop failed but close proceeded: ${address} (agentId=${agentId}) phase=${phase}`
+        );
+      }
+      entry.inFlight = void 0;
+      if (result.closed) {
+        this.releasedClients.add(client);
+      }
+      if (result.closed && this.pendingReleaseByAddress.get(key) === entry) {
+        this.pendingReleaseByAddress.delete(key);
+        if (timedOut) {
+          this.releaseConfirmedNeedsCreate.add(key);
+        }
+      }
+      return result;
+    });
+    entry.inFlight = task.then((result) => result.closed);
+    const timeoutHandle = {};
+    const timeoutPromise = new Promise((resolve11) => {
+      timeoutHandle.timer = this.releaseWaitSetTimeout(
+        () => resolve11(null),
+        this.releaseWaitTimeoutMs
+      );
+    });
+    const outcome = await Promise.race([task, timeoutPromise]);
+    if (timeoutHandle.timer !== void 0) {
+      this.releaseWaitClearTimeout(timeoutHandle.timer);
+    }
+    if (outcome === null) {
+      timedOut = true;
+      this.logReleaseNotConfirmed(address, agentId, phase, "close_timeout");
+      return false;
+    }
+    if (outcome.closed) {
+      if (this.pendingReleaseByAddress.get(key) === entry) {
+        this.pendingReleaseByAddress.delete(key);
+      }
+      return true;
+    }
+    if (!outcome.closeFailed) {
+      this.logReleaseNotConfirmed(address, agentId, phase, "close_unavailable");
+    }
+    return false;
+  }
+  // Stops serving `client` to new operations. Every removal is identity
+  // checked, so a late caller can never remove a newer instance (or its replay
+  // gate / recovery / retry state) registered for the same address.
+  unpublishClient(address, client, phase) {
+    const key = address.toLowerCase();
+    let removed = false;
+    for (const [registeredAddress, registered] of this.clients) {
+      if (registered === client && registeredAddress.toLowerCase() === key) {
+        this.clients.delete(registeredAddress);
+        removed = true;
+      }
+    }
+    const gate = this.inboundReplayGates.get(key);
+    if (gate) {
+      const owner = this.inboundReplayGateOwners.get(gate);
+      if (owner === client || owner === void 0 && removed) {
+        this.inboundReplayGates.delete(key);
+      }
+    }
+    this.cancelStreamRecoveryForAddress(address, client);
+    if (removed) {
+      this.replayScanFailuresByAddress.delete(key);
+      this.clearReplayScanRetry(
+        address,
+        phase.startsWith("recycle") ? "client_recycled" : "client_removed"
+      );
+    }
+    if (!this.getClientByAddress(address)) {
+      this.stoppedAddresses.add(key);
+    }
+  }
+  async settlePendingRelease(address) {
+    const entry = this.pendingReleaseByAddress.get(address.toLowerCase());
+    if (!entry) {
+      return true;
+    }
+    if (entry.inFlight) {
+      return false;
+    }
+    const retryPhase = entry.phase.endsWith("/retry") ? entry.phase : `${entry.phase}/retry`;
+    return this.releaseClient(address, entry.client, entry.agentId, retryPhase);
+  }
   async recordInstallationHealth(params) {
     const { address, agent, agentInfo, phase, attempt } = params;
     try {
@@ -57550,8 +57835,6 @@ var XmtpService = class _XmtpService {
       const r = results[i];
       if (r.status === "fulfilled") {
         const { address, agent, agentInfo } = r.value;
-        this.stoppedAddresses.delete(address.toLowerCase());
-        this.clients.set(address, agent);
         logWithTimestamp(
           `[xmtp-sdk] identity initialized: ${address} (agentId=${agentInfo.agentId})`
         );
@@ -57577,6 +57860,10 @@ var XmtpService = class _XmtpService {
           phase: "init",
           attempt: "1"
         });
+      } else if (r.reason instanceof XmtpClientCreateBlockedError) {
+        logWithTimestamp(
+          `[xmtp-sdk] identity init: create blocked (${r.reason.reason}): ${agents[i].communicationAddress} (agentId=${agents[i].agentId})`
+        );
       } else {
         failedAgents.push(agents[i]);
         if (r.reason instanceof XmtpCreationCooldownSkipError) {
@@ -57613,8 +57900,6 @@ var XmtpService = class _XmtpService {
         const r = retryResults[i];
         if (r.status === "fulfilled") {
           const { address, agent, agentInfo } = r.value;
-          this.stoppedAddresses.delete(address.toLowerCase());
-          this.clients.set(address, agent);
           logWithTimestamp(
             `[xmtp-sdk] retry succeeded: ${address} (agentId=${agentInfo.agentId})`
           );
@@ -57640,6 +57925,11 @@ var XmtpService = class _XmtpService {
             phase: "init",
             attempt: "2"
           });
+        } else if (r.reason instanceof XmtpClientCreateBlockedError) {
+          const info = failedAgents[i];
+          logWithTimestamp(
+            `[xmtp-sdk] retry create blocked (${r.reason.reason}): ${info.communicationAddress} (agentId=${info.agentId})`
+          );
         } else if (r.reason instanceof XmtpCreationCooldownSkipError) {
           const info = failedAgents[i];
           logWithTimestamp(
@@ -57722,36 +58012,38 @@ var XmtpService = class _XmtpService {
         throw err;
       }
     }
+    for (const pendingKey of [...this.pendingReleaseByAddress.keys()]) {
+      const settled = await this.settlePendingRelease(pendingKey);
+      logWithTimestamp(
+        `[xmtp-sdk] refresh: pending release ${pendingKey} ${settled ? "confirmed" : "still pending"}`
+      );
+    }
     const oldAddresses = new Set(
-      this.allAgents.map((a) => a.communicationAddress)
+      this.allAgents.map((a) => a.communicationAddress.toLowerCase())
+    );
+    const newAddresses = new Set(
+      newAgents.map((a) => a.communicationAddress.toLowerCase())
     );
-    const newAddresses = new Set(newAgents.map((a) => a.communicationAddress));
     const added = newAgents.filter(
-      (a) => !oldAddresses.has(a.communicationAddress) || !this.clients.has(a.communicationAddress)
+      (a) => !oldAddresses.has(a.communicationAddress.toLowerCase()) || !this.getClientByAddress(a.communicationAddress)
     );
     const removed = this.allAgents.filter(
-      (a) => !newAddresses.has(a.communicationAddress)
+      (a) => !newAddresses.has(a.communicationAddress.toLowerCase())
     );
     this.allAgents = newAgents;
     for (const agentInfo of removed) {
       const address = agentInfo.communicationAddress;
-      const client = this.clients.get(address);
+      const client = this.getClientByAddress(address);
       if (client) {
         try {
-          this.cancelStreamRecoveryForAddress(address);
-          this.stoppedAddresses.add(address.toLowerCase());
-          await stopAndCloseXmtpClient(client, {
+          const released = await this.releaseClient(
             address,
-            agentId: agentInfo.agentId,
-            phase: "refresh/remove",
-            onCloseError: (err) => logger.error(
-              LogEvent.XMTP_CLIENT_CLOSE_FAILED,
-              err instanceof Error ? err : new Error(String(err)),
-              { walletAddress: address, onchainosAgentId: agentInfo.agentId, phase: "refresh/remove" }
-            )
-          });
+            client,
+            agentInfo.agentId,
+            "refresh/remove"
+          );
           logWithTimestamp(
-            `[xmtp-sdk] refresh: stopped client: ${address} (agentId=${agentInfo.agentId})`
+            `[xmtp-sdk] refresh: stopped client: ${address} (agentId=${agentInfo.agentId}) released=${released}`
           );
         } catch (err) {
           logWithTimestamp(`[xmtp-sdk] refresh: failed to stop client: ${address}`, err);
@@ -57761,10 +58053,6 @@ var XmtpService = class _XmtpService {
             phase: "stop-client"
           });
         }
-        this.clients.delete(address);
-        this.inboundReplayGates.delete(address.toLowerCase());
-        this.replayScanFailuresByAddress.delete(address.toLowerCase());
-        this.clearReplayScanRetry(address, "client_removed");
         logger.info(LogEvent.AGENT_CLIENT_REMOVED, {
           ...agentExtras({
             walletAddress: address,
@@ -57806,8 +58094,6 @@ var XmtpService = class _XmtpService {
         const r = addResults[i];
         if (r.status === "fulfilled") {
           const { address, agentInfo } = r.value;
-          this.stoppedAddresses.delete(address.toLowerCase());
-          this.clients.set(address, r.value.agent);
           logWithTimestamp(
             `[xmtp-sdk] refresh: identity initialized: ${address} (agentId=${agentInfo.agentId})`
           );
@@ -57834,6 +58120,10 @@ var XmtpService = class _XmtpService {
             phase: "refresh",
             attempt: "1"
           });
+        } else if (r.reason instanceof XmtpClientCreateBlockedError) {
+          logWithTimestamp(
+            `[xmtp-sdk] refresh: create blocked (${r.reason.reason}): ${added[i].communicationAddress} (agentId=${added[i].agentId})`
+          );
         } else {
           failedAgents.push(added[i]);
           if (r.reason instanceof XmtpCreationCooldownSkipError) {
@@ -57873,8 +58163,6 @@ var XmtpService = class _XmtpService {
           const r = retryResults[i];
           if (r.status === "fulfilled") {
             const { address, agentInfo } = r.value;
-            this.stoppedAddresses.delete(address.toLowerCase());
-            this.clients.set(address, r.value.agent);
             logWithTimestamp(
               `[xmtp-sdk] refresh: retry succeeded: ${address} (agentId=${agentInfo.agentId})`
             );
@@ -57901,6 +58189,11 @@ var XmtpService = class _XmtpService {
               phase: "refresh",
               attempt: "2"
             });
+          } else if (r.reason instanceof XmtpClientCreateBlockedError) {
+            const info = failedAgents[i];
+            logWithTimestamp(
+              `[xmtp-sdk] refresh: retry create blocked (${r.reason.reason}): ${info.communicationAddress} (agentId=${info.agentId})`
+            );
           } else if (r.reason instanceof XmtpCreationCooldownSkipError) {
             const info = failedAgents[i];
             logWithTimestamp(
@@ -57926,7 +58219,8 @@ var XmtpService = class _XmtpService {
         }
       }
       await this.startListeningForAddresses(
-        added.map((a) => a.communicationAddress)
+        added.map((a) => a.communicationAddress),
+        "refresh/listen-failed"
       );
       for (const agentInfo of added) {
         const address = agentInfo.communicationAddress;
@@ -57991,30 +58285,42 @@ var XmtpService = class _XmtpService {
     }
     for (const agentInfo of this.allAgents) {
       const address = agentInfo.communicationAddress;
-      const oldClient = this.clients.get(address);
-      if (!oldClient) {
+      const addressKey = address.toLowerCase();
+      const oldClient = this.getClientByAddress(address);
+      const hasPendingRelease = this.pendingReleaseByAddress.has(addressKey) || this.releaseConfirmedNeedsCreate.has(addressKey);
+      if (!oldClient && !hasPendingRelease) {
         continue;
       }
-      const addressKey = address.toLowerCase();
-      try {
-        this.cancelStreamRecoveryForAddress(address);
-        this.stoppedAddresses.add(addressKey);
-        await stopAndCloseXmtpClient(oldClient, {
-          address,
-          agentId: agentInfo.agentId,
-          phase: "recycle",
-          onCloseError: (err) => logger.error(
-            LogEvent.XMTP_CLIENT_CLOSE_FAILED,
-            err instanceof Error ? err : new Error(String(err)),
-            { walletAddress: address, onchainosAgentId: agentInfo.agentId, phase: "recycle" }
-          )
-        });
-        this.clients.delete(address);
-        this.inboundReplayGates.delete(addressKey);
-        this.replayScanFailuresByAddress.delete(addressKey);
-        this.clearReplayScanRetry(address, "client_recycled");
+      if (!oldClient) {
+        let settled = false;
+        try {
+          settled = await this.settlePendingRelease(address);
+        } catch (err) {
+          logWithTimestamp(`[xmtp-sdk] recycle: pending release retry failed: ${address}`, err);
+        }
+        if (!settled) {
+          failed++;
+          continue;
+        }
+      } else {
+        let released = false;
+        try {
+          released = await this.releaseClient(
+            address,
+            oldClient,
+            agentInfo.agentId,
+            "recycle"
+          );
+        } catch (err) {
+          logWithTimestamp(`[xmtp-sdk] recycle: failed to stop client: ${address}`, err);
+          logger.error(LogEvent.AGENT_REFRESH_FAILED, err instanceof Error ? err : new Error(String(err)), {
+            walletAddress: address,
+            onchainosAgentId: agentInfo.agentId,
+            phase: "recycle/stop-client"
+          });
+        }
         logWithTimestamp(
-          `[xmtp-sdk] recycle: stopped client: ${address} (agentId=${agentInfo.agentId})`
+          `[xmtp-sdk] recycle: stopped client: ${address} (agentId=${agentInfo.agentId}) released=${released}`
         );
         logger.info(LogEvent.AGENT_CLIENT_REMOVED, {
           ...agentExtras({
@@ -58024,23 +58330,18 @@ var XmtpService = class _XmtpService {
           }),
           phase: "recycle"
         });
-      } catch (err) {
-        failed++;
-        this.stoppedAddresses.delete(addressKey);
-        logWithTimestamp(`[xmtp-sdk] recycle: failed to stop client: ${address}`, err);
-        logger.error(LogEvent.AGENT_REFRESH_FAILED, err instanceof Error ? err : new Error(String(err)), {
-          walletAddress: address,
-          onchainosAgentId: agentInfo.agentId,
-          phase: "recycle/stop-client"
-        });
-        continue;
+        if (!released) {
+          failed++;
+          continue;
+        }
       }
+      let newAgent;
+      let newAgentReleased = false;
       try {
         const { agent } = await this.createClientForAgent(agentInfo, {
           logPrefix: "[xmtp-sdk:recycle]"
         });
-        this.stoppedAddresses.delete(addressKey);
-        this.clients.set(address, agent);
+        newAgent = agent;
         logWithTimestamp(
           `[xmtp-sdk] recycle: identity initialized: ${address} (agentId=${agentInfo.agentId})`
         );
@@ -58064,7 +58365,13 @@ var XmtpService = class _XmtpService {
           agentInfo,
           phase: "recycle"
         });
-        await this.startListeningForAddresses([address]);
+        const listen = (await this.startListeningForAddresses([address], "recycle/listen-failed")).get(address);
+        if (listen?.client !== agent || !isListenHealthy(listen.outcome)) {
+          newAgentReleased = listen?.client === agent && listen.outcome === "failed";
+          throw new Error(
+            `xmtp listener not started (${listen?.client === agent ? listen.outcome : "client_replaced"})`
+          );
+        }
         const replayGate = this.inboundReplayGates.get(addressKey);
         let replaySummary;
         try {
@@ -58083,8 +58390,21 @@ var XmtpService = class _XmtpService {
         recycled++;
       } catch (err) {
         failed++;
-        this.cancelStreamRecoveryForAddress(address);
-        this.clients.delete(address);
+        if (newAgent && !newAgentReleased) {
+          try {
+            await this.releaseClient(
+              address,
+              newAgent,
+              agentInfo.agentId,
+              "recycle/create-failed"
+            );
+          } catch (releaseErr) {
+            logWithTimestamp(
+              `[xmtp-sdk] recycle: failed to release new client: ${address}`,
+              releaseErr
+            );
+          }
+        }
         logWithTimestamp(`[xmtp-sdk] recycle: failed to recreate client: ${address}`, err);
         logger.error(
           LogEvent.XMTP_CONNECTION_FAILED,
@@ -58488,7 +58808,7 @@ var XmtpService = class _XmtpService {
     }
   }
   async startListening() {
-    await this.startListeningForAddresses([...this.clients.keys()]);
+    await this.startListeningForAddresses([...this.clients.keys()], "listen-failed");
   }
   async drainInboundReplayGate(address, expectedGate) {
     if (!expectedGate) {
@@ -58553,11 +58873,22 @@ var XmtpService = class _XmtpService {
     );
     return gate;
   }
-  cancelStreamRecoveryForAddress(address) {
+  // With `client`, only that client's recovery is cancelled, so a late caller
+  // cannot cancel the recovery of a newer instance on the same address.
+  cancelStreamRecoveryForAddress(address, client) {
     const addressKey = address.toLowerCase();
-    const cleanup = this.streamRecoveryCleanupByAddress.get(addressKey);
+    const entry = this.streamRecoveryCleanupByAddress.get(addressKey);
+    if (!entry || client && entry.client !== client) {
+      return;
+    }
     this.streamRecoveryCleanupByAddress.delete(addressKey);
-    cleanup?.();
+    entry.cleanup();
+  }
+  // True while `client` is the registered client of `address` (case-insensitive)
+  // and the address is neither stopped nor being released.
+  isCurrentListenOwner(address, client) {
+    const key = address.toLowerCase();
+    return this.getClientByAddress(address) === client && !this.stoppedAddresses.has(key) && !this.pendingReleaseByAddress.has(key);
   }
   getClientGeneration(client) {
     const existing = this.clientGenerationByClient.get(client);
@@ -58709,10 +59040,17 @@ var XmtpService = class _XmtpService {
     this.notifyAgentsWakeupAfterReplay();
     return summary;
   }
-  async startListeningForAddresses(addresses) {
+  // Starts (at most once per client) the listener of every registered address
+  // and reports each outcome. A "failed" client, i.e. one with neither a live
+  // listener nor an owned retry task, is released with `releasePhase` before
+  // this returns, so it is never served as a healthy instance.
+  async startListeningForAddresses(addresses, releasePhase = "listen-failed") {
     const valid = addresses.filter((addr) => this.clients.has(addr));
-    await parallelMap(valid, async (address) => {
-      const agent = this.clients.get(address);
+    const targets = valid.map((address) => ({
+      address,
+      client: this.clients.get(address)
+    }));
+    const listenForClient = async (address, agent) => {
       const clientGeneration = this.getClientGeneration(agent);
       const addressKey = address.toLowerCase();
       const tag = `[xmtp-sdk:${address}]`;
@@ -58723,6 +59061,11 @@ var XmtpService = class _XmtpService {
         onchainosAgentId: onchainosAgent?.agentId,
         role: onchainosAgent?.role
       };
+      const ownsAddress = () => this.isCurrentListenOwner(address, agent);
+      if (!ownsAddress()) {
+        logWithTimestamp(`${tag} listener setup skipped: client no longer current`);
+        return "skipped";
+      }
       try {
         await agent.client.conversations.syncAll([
           import_node_bindings2.ConsentState.Allowed,
@@ -58730,13 +59073,21 @@ var XmtpService = class _XmtpService {
         ]);
         logWithTimestamp(`${tag} conversations synced (non-Denied)`);
       } catch (err) {
-        logWithTimestamp(`${tag} conversation sync failed, skipping this client:`, err);
+        if (!ownsAddress()) {
+          logWithTimestamp(`${tag} stale conversation sync failed after replacement, ignored:`, err);
+          return "skipped";
+        }
+        logWithTimestamp(`${tag} conversation sync failed, listener not started:`, err);
         logger.error(
           LogEvent.CONVERSATIONS_STREAM_FAILED,
           err instanceof Error ? err : void 0,
           agentExtras(identity)
         );
-        return;
+        return "failed";
+      }
+      if (!ownsAddress()) {
+        logWithTimestamp(`${tag} listener setup skipped after sync: client no longer current`);
+        return "skipped";
       }
       agent.use(loggingMiddleware(identity));
       agent.use(selfFilterMiddleware());
@@ -58765,6 +59116,7 @@ var XmtpService = class _XmtpService {
         });
         const gate = new InboundReplayGate(inbound);
         this.inboundReplayGates.set(address.toLowerCase(), gate);
+        this.inboundReplayGateOwners.set(gate, agent);
         agent.use(gate.middleware);
       } else {
         logWithTimestamp(
@@ -58782,16 +59134,25 @@ var XmtpService = class _XmtpService {
       const MAX_RETRIES = 5;
       const BASE_DELAY_MS = 1e3;
       const startWithRetry = async (attempt = 0) => {
-        if (this.stoppedAddresses.has(address.toLowerCase()) || !this.clients.has(address)) {
+        if (!ownsAddress()) {
           logWithTimestamp(`${tag} start skipped: client stopped or removed`);
-          return;
+          return "skipped";
         }
         try {
           const liveStreamOptions = {
             consentStates: [import_node_bindings2.ConsentState.Allowed, import_node_bindings2.ConsentState.Unknown]
           };
           await agent.start(liveStreamOptions);
+          if (!ownsAddress()) {
+            logWithTimestamp(`${tag} stale agent.start resolved after replacement, ignored`);
+            return "skipped";
+          }
+          return "started";
         } catch (err) {
+          if (!ownsAddress()) {
+            logWithTimestamp(`${tag} stale agent.start failed after replacement, ignored:`, err);
+            return "skipped";
+          }
           logWithTimestamp(`${tag} agent.start error (attempt=${attempt}):`, err);
           logger.error(
             LogEvent.AGENT_START_FAILED,
@@ -58801,17 +59162,27 @@ var XmtpService = class _XmtpService {
               attempt: String(attempt)
             }
           );
-          scheduleRetry(attempt);
+          return scheduleRetry(attempt);
         }
       };
       const scheduleRetry = (attempt) => {
-        if (this.stoppedAddresses.has(address.toLowerCase()) || !this.clients.has(address)) {
+        if (!ownsAddress()) {
           logWithTimestamp(`${tag} reconnect skipped: client stopped or removed`);
-          return;
+          return "skipped";
         }
         if (attempt >= MAX_RETRIES) {
-          logWithTimestamp(`${tag} reached max retries (${MAX_RETRIES}), giving up reconnect`);
-          return;
+          logWithTimestamp(
+            `${tag} reached max retries (${MAX_RETRIES}), giving up reconnect; releasing client`
+          );
+          void this.releaseClient(
+            address,
+            agent,
+            identity.onchainosAgentId ?? "",
+            "listen/retry-exhausted"
+          ).catch((err) => {
+            logWithTimestamp(`${tag} release after retry exhaustion failed:`, err);
+          });
+          return "failed";
         }
         const delay = BASE_DELAY_MS * 2 ** attempt;
         logWithTimestamp(`${tag} reconnecting in ${delay}ms (attempt=${attempt + 1})`);
@@ -58819,6 +59190,7 @@ var XmtpService = class _XmtpService {
           () => void startWithRetry(attempt + 1),
           delay
         );
+        return "retrying";
       };
       const streamRecovery = new StreamRecoveryTelemetry();
       let recoveryTimeout;
@@ -58838,10 +59210,10 @@ var XmtpService = class _XmtpService {
           recoveryStabilityTimeout = void 0;
         }
       };
-      this.streamRecoveryCleanupByAddress.set(
-        addressKey,
-        cleanupStreamRecovery
-      );
+      this.streamRecoveryCleanupByAddress.set(addressKey, {
+        client: agent,
+        cleanup: cleanupStreamRecovery
+      });
       agent.on("unhandledError", (err) => {
         if (recoveryDisposed || this.clients.get(address) !== agent || this.stoppedAddresses.has(addressKey)) {
           return;
@@ -59003,9 +59375,54 @@ var XmtpService = class _XmtpService {
           `${tag} agent message event msg=${msg?.id ?? "(unknown)"} kind=${msg?.kind ?? "(unknown)"} conv=${conversation?.id ?? msg?.conversationId ?? "(unknown)"} sender=${msg?.senderInboxId ?? "(unknown)"} isText=${typeof ctx.isText === "function" ? String(ctx.isText()) : "unknown"} preview="${previewDebugContent(msg?.content)}"`
         );
       });
-      await startWithRetry();
-      logWithTimestamp(`${tag} message listener started`);
+      const outcome = await startWithRetry();
+      logWithTimestamp(`${tag} message listener ${outcome}`);
+      return outcome;
+    };
+    const settled = await parallelMap(targets, async ({ address, client }) => {
+      let task = this.listenTaskByClient.get(client);
+      if (!task) {
+        task = listenForClient(address, client);
+        this.listenTaskByClient.set(client, task);
+      }
+      let outcome;
+      try {
+        outcome = await task;
+      } catch (err) {
+        logWithTimestamp(`[xmtp-sdk:${address}] listener setup failed:`, err);
+        logger.error(
+          LogEvent.AGENT_START_FAILED,
+          err instanceof Error ? err : new Error(String(err)),
+          {
+            ...agentExtras({
+              walletAddress: address,
+              inboxId: client.client?.inboxId,
+              onchainosAgentId: this.getAgentByAddress(address)?.agentId
+            }),
+            phase: "listener-setup"
+          }
+        );
+        outcome = "failed";
+      }
+      if (outcome === "failed") {
+        await this.releaseClient(
+          address,
+          client,
+          this.getAgentByAddress(address)?.agentId ?? "",
+          releasePhase
+        );
+      }
+      return outcome;
+    });
+    const results = /* @__PURE__ */ new Map();
+    targets.forEach(({ address, client }, i) => {
+      const r = settled[i];
+      results.set(address, {
+        client,
+        outcome: r.status === "fulfilled" ? r.value : "failed"
+      });
     });
+    return results;
   }
   async replayOfflineMessagesForAddress(address, expectedClient, trigger = "periodic_repair", recoveryIdentity) {
     const addressReplayStartedAt = Date.now();
@@ -61716,7 +62133,7 @@ function buildConnectParams(config, instanceId, protocolVersion) {
     client: {
       id: "gateway-client",
       displayName: "okx-a2a-node",
-      version: "0.2.17",
+      version: "0.2.18",
       platform: "node",
       mode: "backend",
       instanceId
@@ -61727,7 +62144,7 @@ function buildConnectParams(config, instanceId, protocolVersion) {
     commands: [],
     permissions: {},
     locale: Intl.DateTimeFormat().resolvedOptions().locale || "en-US",
-    userAgent: `okx-a2a-node/${"0.2.17"}`,
+    userAgent: `okx-a2a-node/${"0.2.18"}`,
     auth: {
       ...config.token ? { token: config.token } : {},
       ...config.password ? { password: config.password } : {}
@@ -68067,12 +68484,12 @@ async function runListenerWithLock(options, paths) {
       });
     }
   });
-  service.setPluginVersion("0.2.17");
+  service.setPluginVersion("0.2.18");
   await service.init();
   const pluginVersionStatus = service.pluginVersionStatus;
   if (pluginVersionStatus.unavailable) {
     throw new Error(
-      `@okxweb3/a2a-node v${"0.2.17"} is below the required minimum v${pluginVersionStatus.minVersion}`
+      `@okxweb3/a2a-node v${"0.2.18"} is below the required minimum v${pluginVersionStatus.minVersion}`
     );
   }
   const systemConfig = service.getSystemConfig();
@@ -68100,7 +68517,7 @@ async function runListenerWithLock(options, paths) {
       onchainosAgentId: "*",
       reason: "system-config missing sentryDsn",
       pluginId: "@okxweb3/a2a-node",
-      pluginVersion: "0.2.17"
+      pluginVersion: "0.2.18"
     });
   }
   logWithTimestamp(
@@ -70873,7 +71290,7 @@ async function exportDiagnosticLogs(options) {
     node: process.version,
     platform: process.platform,
     arch: process.arch,
-    packageVersion: true ? "0.2.17" : "unknown",
+    packageVersion: true ? "0.2.18" : "unknown",
     sensitiveContentIncluded: options.includeSensitiveContent,
     listenerAndLlmContentIncluded: true,
     credentialsAlwaysRedacted: true,
@@ -72785,7 +73202,7 @@ async function runDoctor(options = {}) {
     platform: options.platform ?? process.platform,
     env: options.env ?? process.env,
     target: options.target ?? resolveDoctorTarget(options.env ?? process.env),
-    cliVersion: options.cliVersion ?? (true ? "0.2.17" : "0.0.0"),
+    cliVersion: options.cliVersion ?? (true ? "0.2.18" : "0.0.0"),
     fixMode: options.fix === true,
     nonInteractive: options.nonInteractive === true,
     packageChanged: false,