@okxweb3/a2a-node 0.2.16 → 0.2.17

package/dist/index.js

@@ -4256,8 +4256,8 @@ var require_worldwide = __commonJS({
     function getGlobalSingleton(name, creator, obj) {
       const gbl = obj || GLOBAL_OBJ;
       const __SENTRY__ = gbl.__SENTRY__ = gbl.__SENTRY__ || {};
-      const singleton2 = __SENTRY__[name] || (__SENTRY__[name] = creator());
-      return singleton2;
+      const singleton3 = __SENTRY__[name] || (__SENTRY__[name] = creator());
+      return singleton3;
     }
     exports2.GLOBAL_OBJ = GLOBAL_OBJ;
     exports2.getGlobalObject = getGlobalObject;
@@ -19302,6 +19302,14 @@ var init_events = __esm({
       SYSTEM_NOTIFICATION_ROUTED: "System notification routed",
       HERMES_SESSION_ROUTE_BINDING: "Hermes session route binding",
       DOCTOR_REPORT: "Doctor report",
+      // XMTP creation rate-limit cooldown (DEXMARKET-9116). All four are logger.info,
+      // so each one must also be listed in SENTRY_INFO_ALLOWLIST (index.ts) or info()
+      // drops it silently. Extras are bounded tokens/ints/bools only — never raw SDK
+      // error text (no-content-leak invariant).
+      XMTP_RATE_LIMIT_COOLDOWN_STARTED: "XMTP rate limit cooldown started",
+      XMTP_RATE_LIMIT_CREATE_SUPPRESSED: "XMTP rate limit create suppressed",
+      XMTP_RATE_LIMIT_PROBE: "XMTP rate limit probe",
+      XMTP_RATE_LIMIT_RECOVERED: "XMTP rate limit recovered",
       // ── error ─────────────────────────────────────────────────────
       XMTP_CONNECTION_FAILED: "XMTP connection failed",
       CONVERSATIONS_STREAM_FAILED: "conversations.stream failed",
@@ -19367,7 +19375,10 @@ var init_events = __esm({
       AGENT_DB_DIR_CREATE_FAILED: "Agent DB dir create failed",
       AGENT_INSTALLATION_LIMIT_NEAR: "Agent installation limit near",
       XMTP_HISTORY_SYNC_REQUEST_FAILED: "XMTP history sync request failed",
-      XMTP_DEBUG_SYNC_FAILED: "XMTP debug sync failed"
+      XMTP_DEBUG_SYNC_FAILED: "XMTP debug sync failed",
+      // Underlying XMTP SDK client close failed during recycle/removal/shutdown
+      // (DEXMARKET-9116). Error-level → NOT added to SENTRY_INFO_ALLOWLIST.
+      XMTP_CLIENT_CLOSE_FAILED: "XMTP client close failed"
     };
   }
 });
@@ -20212,7 +20223,13 @@ var init_sentry_logger = __esm({
       LogEvent.PENDING_LIST_QUERIED,
       LogEvent.SESSION_KEY_DERIVED,
       LogEvent.SESSIONS_QUERIED,
-      LogEvent.SYNC_TICK_COMPLETED
+      LogEvent.SYNC_TICK_COMPLETED,
+      // XMTP creation rate-limit cooldown checkpoints (DEXMARKET-9116). info() drops
+      // any event not listed here, so these must stay registered.
+      LogEvent.XMTP_RATE_LIMIT_COOLDOWN_STARTED,
+      LogEvent.XMTP_RATE_LIMIT_CREATE_SUPPRESSED,
+      LogEvent.XMTP_RATE_LIMIT_PROBE,
+      LogEvent.XMTP_RATE_LIMIT_RECOVERED
     ]);
     MAX_EXTRA_STRING_LENGTH = 256;
     MAX_TAG_VALUE_LENGTH = 128;
@@ -32448,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.16",
+      release: "0.2.17",
       environment,
       runtimeContainer: normalizeRuntimeContainer(process.env.OKX_A2A_RUNTIME_CONTAINER)
     };
@@ -33404,7 +33421,7 @@ async function getCurrentNodeCliVersion() {
   return await getGlobalNpmPackageVersion(UPDATE_PACKAGES.node) ?? getBundledNodeCliVersion();
 }
 function getBundledNodeCliVersion() {
-  return true ? "0.2.16" : null;
+  return true ? "0.2.17" : null;
 }
 function readConfiguredAiProvider() {
   const explicit = process.env.OKX_A2A_AI_PROVIDER || process.env.OKX_AGENT_TASK_AI_CLI;
@@ -33614,7 +33631,7 @@ async function updateHermes(release, options) {
   }
 }
 async function installGatewayPluginForDoctor(target) {
-  const release = isPrereleaseVersion("0.2.16") ? "beta" : "latest";
+  const release = isPrereleaseVersion("0.2.17") ? "beta" : "latest";
   const insideTargetGateway = detectGatewayInvocation() === target;
   const options = {
     restart: !insideTargetGateway,
@@ -44359,6 +44376,9 @@ __export(index_exports, {
   UserCancelledAiProviderSelectionError: () => UserCancelledAiProviderSelectionError,
   WALLET_STATUS_TIMEOUT_MS: () => WALLET_STATUS_TIMEOUT_MS,
   XMTP_CLIENT_RECYCLE_INTERVAL_ENV: () => XMTP_CLIENT_RECYCLE_INTERVAL_ENV,
+  XMTP_CREATION_COOLDOWN_MS: () => XMTP_CREATION_COOLDOWN_MS,
+  XmtpCreationCooldown: () => XmtpCreationCooldown,
+  XmtpCreationCooldownSkipError: () => XmtpCreationCooldownSkipError,
   XmtpDm: () => Dm,
   XmtpGroup: () => Group,
   XmtpService: () => XmtpService,
@@ -44439,6 +44459,7 @@ __export(index_exports, {
   exportDiagnosticLogs: () => exportDiagnosticLogs,
   extractAiSessionId: () => extractAiSessionId,
   extractDirectToUserNotification: () => extractDirectToUserNotification,
+  extractRateLimitEndpoint: () => extractRateLimitEndpoint,
   extractXmtpSentAtMs: () => extractXmtpSentAtMs2,
   findWindowsNativeOkxA2aExe: () => findWindowsNativeOkxA2aExe,
   followFile: () => followFile,
@@ -44449,6 +44470,7 @@ __export(index_exports, {
   getResolvedOnchainosBinForTests: () => getResolvedOnchainosBinForTests,
   getRuntimeMetadata: () => getRuntimeMetadata,
   getSessionBusyTracker: () => getSessionBusyTracker,
+  getXmtpCreationCooldown: () => getXmtpCreationCooldown,
   handleCapabilitiesCommand: () => handleCapabilitiesCommand,
   handleDoctorCommand: () => handleDoctorCommand,
   handleXmtpDebugCommand: () => handleXmtpDebugCommand,
@@ -44479,6 +44501,7 @@ __export(index_exports, {
   isTagKey: () => isTagKey,
   isValidExternalJobId: () => isValidExternalJobId,
   isWindowsElevated: () => isWindowsElevated,
+  isXmtpRateLimitError: () => isXmtpRateLimitError,
   killProcessTree: () => killProcessTree,
   launchdPlistHasCurrentRestartPolicy: () => launchdPlistHasCurrentRestartPolicy,
   listAllAgentsWithMetadata: () => listAllAgentsWithMetadata,
@@ -44528,6 +44551,7 @@ __export(index_exports, {
   reportUserNotificationFailure: () => reportUserNotificationFailure,
   resetMessageEligibleOfflineReplayCapabilityForTests: () => resetMessageEligibleOfflineReplayCapabilityForTests,
   resetResolvedOnchainosBinForTests: () => resetResolvedOnchainosBinForTests,
+  resetXmtpCreationCooldownForTests: () => resetXmtpCreationCooldownForTests,
   resolveAiPermissionPreset: () => resolveAiPermissionPreset,
   resolveAiProviderCommand: () => resolveAiProviderCommand,
   resolveAiProviderCommandWithSource: () => resolveAiProviderCommandWithSource,
@@ -44575,6 +44599,7 @@ __export(index_exports, {
   startDaemonRespectingSupervisor: () => startDaemonRespectingSupervisor,
   startUserAttentionEventServer: () => startUserAttentionEventServer,
   startUserAttentionWatcherCoordinator: () => startUserAttentionWatcherCoordinator,
+  stopAndCloseXmtpClient: () => stopAndCloseXmtpClient,
   stopDaemon: () => stopDaemon,
   stopOpenClawGateway: () => stopOpenClawGateway,
   stopSystemdAutostart: () => stopSystemdAutostart,
@@ -56467,6 +56492,188 @@ function reportSessionExpired(command) {
   );
 }
 
+// ../core/src/xmtp-sdk/rate-limit-cooldown.ts
+var MAX_CAUSE_DEPTH2 = 4;
+var XMTP_CREATION_COOLDOWN_MS = 33e4;
+var RATE_LIMIT_PATTERNS = [
+  /some resource has been exhausted/i,
+  /exceeds rate limit/i,
+  /resource_exhausted/i
+];
+var KNOWN_RATE_LIMIT_ENDPOINTS = [
+  /\bGetInboxIds\b/i,
+  /\bGetIdentityUpdates\b/i
+];
+function asErrorLike2(value) {
+  return value instanceof Error ? value : void 0;
+}
+function causeChain2(err) {
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = err;
+  while (chain.length < MAX_CAUSE_DEPTH2) {
+    chain.push(current);
+    const errorLike = asErrorLike2(current);
+    if (!errorLike || seen.has(errorLike)) {
+      break;
+    }
+    seen.add(errorLike);
+    current = errorLike.cause;
+    if (current === void 0) {
+      break;
+    }
+  }
+  return chain;
+}
+function messageOf(node) {
+  return (node instanceof Error ? node.message : String(node)).toLowerCase();
+}
+function isXmtpRateLimitError(err) {
+  if (err === void 0 || err === null) {
+    return false;
+  }
+  const chain = causeChain2(err);
+  return chain.some(
+    (node) => RATE_LIMIT_PATTERNS.some((pattern) => pattern.test(messageOf(node)))
+  );
+}
+function extractRateLimitEndpoint(err) {
+  if (err === void 0 || err === null) {
+    return void 0;
+  }
+  const chain = causeChain2(err);
+  for (const node of chain) {
+    const message = messageOf(node);
+    for (const pattern of KNOWN_RATE_LIMIT_ENDPOINTS) {
+      const match = pattern.exec(message);
+      if (match) {
+        return /GetInboxIds/i.test(match[0]) ? "GetInboxIds" : "GetIdentityUpdates";
+      }
+    }
+  }
+  return void 0;
+}
+var XmtpCreationCooldownSkipError = class extends Error {
+  remainingMs;
+  address;
+  agentId;
+  constructor(remainingMs, address, agentId) {
+    super("xmtp creation suppressed during rate-limit cooldown");
+    this.name = "XmtpCreationCooldownSkipError";
+    this.remainingMs = remainingMs;
+    this.address = address;
+    this.agentId = agentId;
+  }
+};
+var XmtpCreationCooldown = class {
+  cooldownUntilMs = null;
+  probeInFlight = false;
+  suppressedCreateCount = 0;
+  rateLimitHitCount = 0;
+  probeCount = 0;
+  inFlightCreateCount = 0;
+  beginCreateAttempt(nowMs = Date.now()) {
+    if (this.cooldownUntilMs === null) {
+      this.inFlightCreateCount++;
+      return { allowed: true, mode: "normal" };
+    }
+    if (nowMs < this.cooldownUntilMs) {
+      this.suppressedCreateCount++;
+      return {
+        allowed: false,
+        mode: "blocked",
+        remainingMs: Math.max(0, this.cooldownUntilMs - nowMs)
+      };
+    }
+    if (this.probeInFlight) {
+      this.suppressedCreateCount++;
+      return { allowed: false, mode: "blocked", remainingMs: 0 };
+    }
+    this.probeInFlight = true;
+    this.inFlightCreateCount++;
+    this.probeCount++;
+    return { allowed: true, mode: "probe" };
+  }
+  recordCreateSuccess(decision, _nowMs = Date.now()) {
+    this.inFlightCreateCount = Math.max(0, this.inFlightCreateCount - 1);
+    if (decision.mode === "probe") {
+      this.cooldownUntilMs = null;
+      this.probeInFlight = false;
+    }
+  }
+  recordRateLimit(decision, nowMs = Date.now()) {
+    this.inFlightCreateCount = Math.max(0, this.inFlightCreateCount - 1);
+    this.cooldownUntilMs = nowMs + XMTP_CREATION_COOLDOWN_MS;
+    this.rateLimitHitCount++;
+    this.probeInFlight = false;
+    void decision;
+  }
+  recordCreateFailure(decision, nowMs = Date.now()) {
+    this.inFlightCreateCount = Math.max(0, this.inFlightCreateCount - 1);
+    if (decision.mode === "probe") {
+      this.cooldownUntilMs = nowMs + XMTP_CREATION_COOLDOWN_MS;
+      this.probeInFlight = false;
+    }
+  }
+  isCoolingDown(nowMs = Date.now()) {
+    return this.cooldownUntilMs !== null && nowMs < this.cooldownUntilMs;
+  }
+  remainingMs(nowMs = Date.now()) {
+    return this.cooldownUntilMs === null ? 0 : Math.max(0, this.cooldownUntilMs - nowMs);
+  }
+  snapshot(nowMs = Date.now()) {
+    return {
+      coolingDown: this.isCoolingDown(nowMs),
+      cooldownUntilMs: this.cooldownUntilMs,
+      remainingMs: this.remainingMs(nowMs),
+      probeInFlight: this.probeInFlight,
+      suppressedCreateCount: this.suppressedCreateCount,
+      rateLimitHitCount: this.rateLimitHitCount,
+      probeCount: this.probeCount,
+      inFlightCreateCount: this.inFlightCreateCount
+    };
+  }
+  resetForTests() {
+    this.cooldownUntilMs = null;
+    this.probeInFlight = false;
+    this.suppressedCreateCount = 0;
+    this.rateLimitHitCount = 0;
+    this.probeCount = 0;
+    this.inFlightCreateCount = 0;
+  }
+};
+var singleton;
+function getXmtpCreationCooldown() {
+  if (!singleton) {
+    singleton = new XmtpCreationCooldown();
+  }
+  return singleton;
+}
+function resetXmtpCreationCooldownForTests() {
+  getXmtpCreationCooldown().resetForTests();
+}
+
+// ../core/src/xmtp-sdk/client-lifecycle.ts
+async function stopAndCloseXmtpClient(agent, ctx) {
+  let stopped = true;
+  try {
+    await Promise.resolve(agent.stop());
+  } catch {
+    stopped = false;
+  }
+  const close2 = agent.client?.close;
+  if (typeof close2 !== "function") {
+    return { stopped, closed: false, closeFailed: false };
+  }
+  try {
+    await Promise.resolve(close2.call(agent.client));
+    return { stopped, closed: true, closeFailed: false };
+  } catch (err) {
+    ctx.onCloseError?.(err);
+    return { stopped, closed: false, closeFailed: true };
+  }
+}
+
 // ../core/src/xmtp-sdk/index.ts
 var DEFAULT_DATA_DIR = resolveA2aTaskPaths().xmtpDir;
 var XMTP_INSTALLATION_WARNING_THRESHOLD = 2;
@@ -57150,21 +57357,78 @@ var XmtpService = class _XmtpService {
   }
   async createClientForAgent(agentInfo, options = {}) {
     const address = agentInfo.communicationAddress;
-    const signer = this.tools.createSigner(agentInfo);
-    const dbPath = (inboxId2) => `${this.dataDir}/${inboxId2}-${this.env}.db3`;
-    const agent = await createAgentWithInstallationPrune(signer, {
-      dbPath,
-      env: this.env
-    }, {
-      address,
-      agentId: agentInfo.agentId,
-      logPrefix: options.logPrefix
-    });
-    const inboxId = agent.client?.inboxId ?? "";
-    logWithTimestamp(
-      `[xmtp-sdk] xmtp_client_ready agentId=${agentInfo.agentId} address=${address} inboxId=${inboxId} dbPath=${inboxId ? dbPath(inboxId) : "(unknown)"} lastSync=${formatLogTimestamp2(this.syncByAddress.get(address))}`
-    );
-    return { address, agent, agentInfo };
+    const phase = options.logPrefix ?? "[xmtp-sdk]";
+    const cooldown = getXmtpCreationCooldown();
+    const decision = cooldown.beginCreateAttempt();
+    if (!decision.allowed) {
+      logger.info(LogEvent.XMTP_RATE_LIMIT_CREATE_SUPPRESSED, {
+        onchainosAgentId: agentInfo.agentId,
+        walletAddress: address,
+        cooldownRemainingMs: String(decision.remainingMs ?? 0),
+        phase
+      });
+      throw new XmtpCreationCooldownSkipError(
+        decision.remainingMs ?? 0,
+        address,
+        agentInfo.agentId
+      );
+    }
+    if (decision.mode === "probe") {
+      logger.info(LogEvent.XMTP_RATE_LIMIT_PROBE, {
+        onchainosAgentId: agentInfo.agentId,
+        walletAddress: address,
+        phase: "probe-start",
+        probeCount: String(cooldown.snapshot().probeCount)
+      });
+    }
+    try {
+      const signer = this.tools.createSigner(agentInfo);
+      const dbPath = (inboxId2) => `${this.dataDir}/${inboxId2}-${this.env}.db3`;
+      const agent = await createAgentWithInstallationPrune(signer, {
+        dbPath,
+        env: this.env
+      }, {
+        address,
+        agentId: agentInfo.agentId,
+        logPrefix: options.logPrefix
+      });
+      cooldown.recordCreateSuccess(decision);
+      if (decision.mode === "probe") {
+        logger.info(LogEvent.XMTP_RATE_LIMIT_RECOVERED, {
+          onchainosAgentId: agentInfo.agentId,
+          walletAddress: address,
+          phase: "probe-success"
+        });
+      }
+      const inboxId = agent.client?.inboxId ?? "";
+      logWithTimestamp(
+        `[xmtp-sdk] xmtp_client_ready agentId=${agentInfo.agentId} address=${address} inboxId=${inboxId} dbPath=${inboxId ? dbPath(inboxId) : "(unknown)"} lastSync=${formatLogTimestamp2(this.syncByAddress.get(address))}`
+      );
+      return { address, agent, agentInfo };
+    } catch (err) {
+      if (isXmtpRateLimitError(err)) {
+        cooldown.recordRateLimit(decision);
+        logger.info(LogEvent.XMTP_RATE_LIMIT_COOLDOWN_STARTED, {
+          ...agentExtras({ walletAddress: address, onchainosAgentId: agentInfo.agentId }),
+          rateLimitIdentified: "true",
+          endpoint: extractRateLimitEndpoint(err) ?? "unknown",
+          cooldownMs: String(XMTP_CREATION_COOLDOWN_MS),
+          cooldownExpiresAtMs: String(cooldown.snapshot().cooldownUntilMs ?? ""),
+          inFlightCreateCount: String(cooldown.snapshot().inFlightCreateCount),
+          probe: String(decision.mode === "probe")
+        });
+      } else {
+        cooldown.recordCreateFailure(decision);
+        if (decision.mode === "probe") {
+          logger.info(LogEvent.XMTP_RATE_LIMIT_PROBE, {
+            onchainosAgentId: agentInfo.agentId,
+            walletAddress: address,
+            phase: "probe-failed-nonratelimit"
+          });
+        }
+      }
+      throw err;
+    }
   }
   async recordInstallationHealth(params) {
     const { address, agent, agentInfo, phase, attempt } = params;
@@ -57315,22 +57579,28 @@ var XmtpService = class _XmtpService {
         });
       } else {
         failedAgents.push(agents[i]);
-        logWithTimestamp(
-          `[xmtp-sdk] identity init failed: ${agents[i].communicationAddress} (agentId=${agents[i].agentId})`,
-          r.reason
-        );
-        logger.error(
-          LogEvent.XMTP_CONNECTION_FAILED,
-          r.reason instanceof Error ? r.reason : new Error(String(r.reason)),
-          {
-            walletAddress: agents[i].communicationAddress,
-            onchainosAgentId: agents[i].agentId,
-            attempt: "1"
-          }
-        );
+        if (r.reason instanceof XmtpCreationCooldownSkipError) {
+          logWithTimestamp(
+            `[xmtp-sdk] identity init suppressed (rate-limit cooldown): ${agents[i].communicationAddress} (agentId=${agents[i].agentId})`
+          );
+        } else {
+          logWithTimestamp(
+            `[xmtp-sdk] identity init failed: ${agents[i].communicationAddress} (agentId=${agents[i].agentId})`,
+            r.reason
+          );
+          logger.error(
+            LogEvent.XMTP_CONNECTION_FAILED,
+            r.reason instanceof Error ? r.reason : new Error(String(r.reason)),
+            {
+              walletAddress: agents[i].communicationAddress,
+              onchainosAgentId: agents[i].agentId,
+              attempt: "1"
+            }
+          );
+        }
       }
     }
-    if (failedAgents.length > 0) {
+    if (failedAgents.length > 0 && !getXmtpCreationCooldown().isCoolingDown()) {
       logWithTimestamp(
         `[xmtp-sdk] ${failedAgents.length} client(s) failed to initialize, retrying in 1s...`
       );
@@ -57370,6 +57640,11 @@ var XmtpService = class _XmtpService {
             phase: "init",
             attempt: "2"
           });
+        } else if (r.reason instanceof XmtpCreationCooldownSkipError) {
+          const info = failedAgents[i];
+          logWithTimestamp(
+            `[xmtp-sdk] retry suppressed (rate-limit cooldown): ${info.communicationAddress} (agentId=${info.agentId})`
+          );
         } else {
           const info = failedAgents[i];
           logWithTimestamp(
@@ -57465,7 +57740,16 @@ var XmtpService = class _XmtpService {
         try {
           this.cancelStreamRecoveryForAddress(address);
           this.stoppedAddresses.add(address.toLowerCase());
-          client.stop();
+          await stopAndCloseXmtpClient(client, {
+            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" }
+            )
+          });
           logWithTimestamp(
             `[xmtp-sdk] refresh: stopped client: ${address} (agentId=${agentInfo.agentId})`
           );
@@ -57552,23 +57836,29 @@ var XmtpService = class _XmtpService {
           });
         } else {
           failedAgents.push(added[i]);
-          logWithTimestamp(
-            `[xmtp-sdk] refresh: identity init failed: ${added[i].communicationAddress} (agentId=${added[i].agentId})`,
-            r.reason
-          );
-          logger.error(
-            LogEvent.XMTP_CONNECTION_FAILED,
-            r.reason instanceof Error ? r.reason : new Error(String(r.reason)),
-            {
-              walletAddress: added[i].communicationAddress,
-              onchainosAgentId: added[i].agentId,
-              phase: "refresh",
-              attempt: "1"
-            }
-          );
+          if (r.reason instanceof XmtpCreationCooldownSkipError) {
+            logWithTimestamp(
+              `[xmtp-sdk] refresh: identity init suppressed (rate-limit cooldown): ${added[i].communicationAddress} (agentId=${added[i].agentId})`
+            );
+          } else {
+            logWithTimestamp(
+              `[xmtp-sdk] refresh: identity init failed: ${added[i].communicationAddress} (agentId=${added[i].agentId})`,
+              r.reason
+            );
+            logger.error(
+              LogEvent.XMTP_CONNECTION_FAILED,
+              r.reason instanceof Error ? r.reason : new Error(String(r.reason)),
+              {
+                walletAddress: added[i].communicationAddress,
+                onchainosAgentId: added[i].agentId,
+                phase: "refresh",
+                attempt: "1"
+              }
+            );
+          }
         }
       }
-      if (failedAgents.length > 0) {
+      if (failedAgents.length > 0 && !getXmtpCreationCooldown().isCoolingDown()) {
         logWithTimestamp(
           `[xmtp-sdk] refresh: ${failedAgents.length} client(s) failed to initialize, retrying in 1s...`
         );
@@ -57611,6 +57901,11 @@ var XmtpService = class _XmtpService {
               phase: "refresh",
               attempt: "2"
             });
+          } else if (r.reason instanceof XmtpCreationCooldownSkipError) {
+            const info = failedAgents[i];
+            logWithTimestamp(
+              `[xmtp-sdk] refresh: retry suppressed (rate-limit cooldown): ${info.communicationAddress} (agentId=${info.agentId})`
+            );
           } else {
             const info = failedAgents[i];
             logWithTimestamp(
@@ -57674,6 +57969,18 @@ var XmtpService = class _XmtpService {
   async recycleXmtpClients() {
     await this._backupReady;
     const startedAt = Date.now();
+    if (getXmtpCreationCooldown().isCoolingDown()) {
+      logWithTimestamp("[xmtp-sdk] recycle skipped \u2014 rate-limit cooldown active");
+      return {
+        clients: this.clients.size,
+        recycled: 0,
+        failed: 0,
+        replayed: 0,
+        skipped: 0,
+        durationMs: Date.now() - startedAt,
+        addresses: []
+      };
+    }
     const addresses = [];
     let recycled = 0;
     let failed = 0;
@@ -57692,7 +57999,16 @@ var XmtpService = class _XmtpService {
       try {
         this.cancelStreamRecoveryForAddress(address);
         this.stoppedAddresses.add(addressKey);
-        await Promise.resolve(oldClient.stop());
+        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);
@@ -57779,6 +58095,12 @@ var XmtpService = class _XmtpService {
             phase: "recycle/create-client"
           }
         );
+        if (isXmtpRateLimitError(err)) {
+          logWithTimestamp(
+            "[xmtp-sdk] recycle: rate-limit on recreate \u2014 stopping remaining recycles"
+          );
+          break;
+        }
       }
     }
     return {
@@ -60854,12 +61176,12 @@ var SessionBusyTracker = class {
     }
   }
 };
-var singleton = null;
+var singleton2 = null;
 function getSessionBusyTracker() {
-  if (!singleton) {
-    singleton = new SessionBusyTracker();
+  if (!singleton2) {
+    singleton2 = new SessionBusyTracker();
   }
-  return singleton;
+  return singleton2;
 }
 
 // src/openclaw-gateway.ts
@@ -61394,7 +61716,7 @@ function buildConnectParams(config, instanceId, protocolVersion) {
     client: {
       id: "gateway-client",
       displayName: "okx-a2a-node",
-      version: "0.2.16",
+      version: "0.2.17",
       platform: "node",
       mode: "backend",
       instanceId
@@ -61405,7 +61727,7 @@ function buildConnectParams(config, instanceId, protocolVersion) {
     commands: [],
     permissions: {},
     locale: Intl.DateTimeFormat().resolvedOptions().locale || "en-US",
-    userAgent: `okx-a2a-node/${"0.2.16"}`,
+    userAgent: `okx-a2a-node/${"0.2.17"}`,
     auth: {
       ...config.token ? { token: config.token } : {},
       ...config.password ? { password: config.password } : {}
@@ -67600,12 +67922,12 @@ function parseYamlInlineEnabledList(line) {
 var SHUTDOWN_FORCE_RESOLVE_MS = 5e3;
 function stopClients(service) {
   for (const [address, client] of service.getClients()) {
-    try {
-      client.stop();
-      logWithTimestamp(`[okx-agent-task] stopped XMTP client ${address}`);
-    } catch (err) {
-      logWithTimestamp(`[okx-agent-task] failed to stop XMTP client ${address}:`, err);
-    }
+    void stopAndCloseXmtpClient(client, {
+      address,
+      agentId: "",
+      phase: "shutdown",
+      onCloseError: (err) => logWithTimestamp(`[okx-agent-task] failed to close XMTP client ${address}:`, err)
+    }).then(() => logWithTimestamp(`[okx-agent-task] stopped XMTP client ${address}`)).catch((err) => logWithTimestamp(`[okx-agent-task] failed to stop XMTP client ${address}:`, err));
   }
 }
 async function runListener(options = {}) {
@@ -67745,12 +68067,12 @@ async function runListenerWithLock(options, paths) {
       });
     }
   });
-  service.setPluginVersion("0.2.16");
+  service.setPluginVersion("0.2.17");
   await service.init();
   const pluginVersionStatus = service.pluginVersionStatus;
   if (pluginVersionStatus.unavailable) {
     throw new Error(
-      `@okxweb3/a2a-node v${"0.2.16"} is below the required minimum v${pluginVersionStatus.minVersion}`
+      `@okxweb3/a2a-node v${"0.2.17"} is below the required minimum v${pluginVersionStatus.minVersion}`
     );
   }
   const systemConfig = service.getSystemConfig();
@@ -67778,7 +68100,7 @@ async function runListenerWithLock(options, paths) {
       onchainosAgentId: "*",
       reason: "system-config missing sentryDsn",
       pluginId: "@okxweb3/a2a-node",
-      pluginVersion: "0.2.16"
+      pluginVersion: "0.2.17"
     });
   }
   logWithTimestamp(
@@ -70551,7 +70873,7 @@ async function exportDiagnosticLogs(options) {
     node: process.version,
     platform: process.platform,
     arch: process.arch,
-    packageVersion: true ? "0.2.16" : "unknown",
+    packageVersion: true ? "0.2.17" : "unknown",
     sensitiveContentIncluded: options.includeSensitiveContent,
     listenerAndLlmContentIncluded: true,
     credentialsAlwaysRedacted: true,
@@ -72463,7 +72785,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.16" : "0.0.0"),
+    cliVersion: options.cliVersion ?? (true ? "0.2.17" : "0.0.0"),
     fixMode: options.fix === true,
     nonInteractive: options.nonInteractive === true,
     packageChanged: false,
@@ -72733,6 +73055,9 @@ init_autostart_windows();
   UserCancelledAiProviderSelectionError,
   WALLET_STATUS_TIMEOUT_MS,
   XMTP_CLIENT_RECYCLE_INTERVAL_ENV,
+  XMTP_CREATION_COOLDOWN_MS,
+  XmtpCreationCooldown,
+  XmtpCreationCooldownSkipError,
   XmtpDm,
   XmtpGroup,
   XmtpService,
@@ -72813,6 +73138,7 @@ init_autostart_windows();
   exportDiagnosticLogs,
   extractAiSessionId,
   extractDirectToUserNotification,
+  extractRateLimitEndpoint,
   extractXmtpSentAtMs,
   findWindowsNativeOkxA2aExe,
   followFile,
@@ -72823,6 +73149,7 @@ init_autostart_windows();
   getResolvedOnchainosBinForTests,
   getRuntimeMetadata,
   getSessionBusyTracker,
+  getXmtpCreationCooldown,
   handleCapabilitiesCommand,
   handleDoctorCommand,
   handleXmtpDebugCommand,
@@ -72853,6 +73180,7 @@ init_autostart_windows();
   isTagKey,
   isValidExternalJobId,
   isWindowsElevated,
+  isXmtpRateLimitError,
   killProcessTree,
   launchdPlistHasCurrentRestartPolicy,
   listAllAgentsWithMetadata,
@@ -72902,6 +73230,7 @@ init_autostart_windows();
   reportUserNotificationFailure,
   resetMessageEligibleOfflineReplayCapabilityForTests,
   resetResolvedOnchainosBinForTests,
+  resetXmtpCreationCooldownForTests,
   resolveAiPermissionPreset,
   resolveAiProviderCommand,
   resolveAiProviderCommandWithSource,
@@ -72949,6 +73278,7 @@ init_autostart_windows();
   startDaemonRespectingSupervisor,
   startUserAttentionEventServer,
   startUserAttentionWatcherCoordinator,
+  stopAndCloseXmtpClient,
   stopDaemon,
   stopOpenClawGateway,
   stopSystemdAutostart,