@okxweb3/a2a-node 0.2.3 → 0.2.4-beta-e7a52faf6f-260811185020

package/dist/cli.js

@@ -26604,7 +26604,7 @@ function buildConnectParams(config, instanceId, protocolVersion) {
     client: {
       id: "gateway-client",
       displayName: "okx-a2a-node",
-      version: "0.2.3",
+      version: "0.2.4-beta-e7a52faf6f-260811185020",
       platform: "node",
       mode: "backend",
       instanceId
@@ -26615,7 +26615,7 @@ function buildConnectParams(config, instanceId, protocolVersion) {
     commands: [],
     permissions: {},
     locale: Intl.DateTimeFormat().resolvedOptions().locale || "en-US",
-    userAgent: `okx-a2a-node/${"0.2.3"}`,
+    userAgent: `okx-a2a-node/${"0.2.4-beta-e7a52faf6f-260811185020"}`,
     auth: {
       ...config.token ? { token: config.token } : {},
       ...config.password ? { password: config.password } : {}
@@ -28499,7 +28499,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.3",
+      release: "0.2.4-beta-e7a52faf6f-260811185020",
       environment,
       runtimeContainer: normalizeRuntimeContainer(process.env.OKX_A2A_RUNTIME_CONTAINER)
     };
@@ -39669,7 +39669,7 @@ async function exportDiagnosticLogs(options) {
     node: process.version,
     platform: process.platform,
     arch: process.arch,
-    packageVersion: true ? "0.2.3" : "unknown",
+    packageVersion: true ? "0.2.4-beta-e7a52faf6f-260811185020" : "unknown",
     sensitiveContentIncluded: options.includeSensitiveContent,
     listenerAndLlmContentIncluded: true,
     credentialsAlwaysRedacted: true,
@@ -56122,6 +56122,69 @@ var init_installation_prune = __esm({
   }
 });
 
+// ../core/src/xmtp-sdk/onchainos/session-expired.ts
+function isSessionExpired(stdout) {
+  try {
+    const res = JSON.parse(stdout);
+    return res.ok === false && SESSION_EXPIRED_RE.test(String(res.error ?? ""));
+  } catch {
+    return SESSION_EXPIRED_RE.test(stdout);
+  }
+}
+function classifyOnchainosAuthError(err2) {
+  if (!err2) {
+    return null;
+  }
+  const values = [String(err2)];
+  if (typeof err2 === "object") {
+    const anyErr = err2;
+    values.push(anyErr.stdout, anyErr.stderr, anyErr.message);
+  }
+  for (const value of values) {
+    if (typeof value !== "string") {
+      continue;
+    }
+    for (const [reason, pattern] of AUTH_FAILURE_PATTERNS) {
+      if (pattern.test(value)) {
+        return reason;
+      }
+    }
+  }
+  return null;
+}
+function isOnchainosAuthError(err2) {
+  return classifyOnchainosAuthError(err2) !== null;
+}
+function reportSessionExpired(command) {
+  logger.error(
+    LogEvent.ONCHAINOS_SESSION_EXPIRED,
+    new Error("onchainos session expired"),
+    {
+      component: "onchainos_cli",
+      source: "onchainos",
+      stage: "session_expired",
+      operation: command,
+      command,
+      communicationClass: "onchainos_auth_issue",
+      reason: "session_expired"
+    }
+  );
+}
+var SESSION_EXPIRED_RE, AUTH_FAILURE_PATTERNS;
+var init_session_expired = __esm({
+  "../core/src/xmtp-sdk/onchainos/session-expired.ts"() {
+    "use strict";
+    init_sentry_logger();
+    SESSION_EXPIRED_RE = /session expired/i;
+    AUTH_FAILURE_PATTERNS = [
+      ["session_expired", /session expired/i],
+      ["not_logged_in", /not logged in/i],
+      ["login_required", /login required/i],
+      ["authentication_required", /authentication required/i]
+    ];
+  }
+});
+
 // ../core/src/xmtp-sdk/index.ts
 function cachePath(dataDir, fileName) {
   return (0, import_node_path26.join)(dataDir, fileName);
@@ -56149,21 +56212,6 @@ function stringifyJsonForLog(value) {
 function ensureCacheDir(dataDir) {
   ensureA2aTaskDir(dataDir);
 }
-function isSessionExpiredError(err2) {
-  if (!err2) {
-    return false;
-  }
-  if (typeof err2 === "object") {
-    const anyErr = err2;
-    if (typeof anyErr.stdout === "string" && SESSION_EXPIRED_RE.test(anyErr.stdout)) {
-      return true;
-    }
-    if (typeof anyErr.message === "string" && SESSION_EXPIRED_RE.test(anyErr.message)) {
-      return true;
-    }
-  }
-  return SESSION_EXPIRED_RE.test(String(err2));
-}
 function loadSensitiveWordsFromCache(dataDir) {
   try {
     const path2 = cachePath(dataDir, "sensitive-words.json");
@@ -56541,7 +56589,7 @@ function createOfflineReplayAddressSummary(address) {
     durationMs: 0
   };
 }
-var import_node_fs22, import_node_path26, DEFAULT_DATA_DIR, XMTP_INSTALLATION_WARNING_THRESHOLD, XMTP_INSTALLATION_NEAR_LIMIT_THRESHOLD, REPLAY_SCAN_INITIAL_BACKOFF_MS, REPLAY_SCAN_MAX_BACKOFF_MS, SENSITIVE_WORDS_LAZY_RETRY_COOLDOWN_MS, SESSION_EXPIRED_RE, InboundReplayGate, SYSTEM_CONFIG_DEFAULTS, STREAM_RECOVERY_ALERT_THRESHOLD_MS, REPLAY_GATE_DRAIN_MAX_ATTEMPTS, REPLAY_GATE_DRAIN_RETRY_DELAY_MS, SEMVER_RE, isRecord5, isPositiveNumber, SYSTEM_CONFIG_VALIDATORS, XmtpService;
+var import_node_fs22, import_node_path26, DEFAULT_DATA_DIR, XMTP_INSTALLATION_WARNING_THRESHOLD, XMTP_INSTALLATION_NEAR_LIMIT_THRESHOLD, REPLAY_SCAN_INITIAL_BACKOFF_MS, REPLAY_SCAN_MAX_BACKOFF_MS, SENSITIVE_WORDS_LAZY_RETRY_COOLDOWN_MS, InboundReplayGate, SYSTEM_CONFIG_DEFAULTS, STREAM_RECOVERY_ALERT_THRESHOLD_MS, REPLAY_GATE_DRAIN_MAX_ATTEMPTS, REPLAY_GATE_DRAIN_RETRY_DELAY_MS, SEMVER_RE, isRecord5, isPositiveNumber, SYSTEM_CONFIG_VALIDATORS, XmtpService;
 var init_xmtp_sdk = __esm({
   "../core/src/xmtp-sdk/index.ts"() {
     "use strict";
@@ -56559,13 +56607,13 @@ var init_xmtp_sdk = __esm({
     init_concurrency();
     init_a2a_paths();
     init_installation_prune();
+    init_session_expired();
     DEFAULT_DATA_DIR = resolveA2aTaskPaths().xmtpDir;
     XMTP_INSTALLATION_WARNING_THRESHOLD = 2;
     XMTP_INSTALLATION_NEAR_LIMIT_THRESHOLD = 8;
     REPLAY_SCAN_INITIAL_BACKOFF_MS = 3e4;
     REPLAY_SCAN_MAX_BACKOFF_MS = 5 * 6e4;
     SENSITIVE_WORDS_LAZY_RETRY_COOLDOWN_MS = 10 * 60 * 1e3;
-    SESSION_EXPIRED_RE = /session expired/i;
     InboundReplayGate = class {
       constructor(inbound) {
         this.inbound = inbound;
@@ -57131,12 +57179,14 @@ var init_xmtp_sdk = __esm({
           newAgents = agentList.agents;
           changed = agentList.changed;
         } catch (err2) {
-          if (isSessionExpiredError(err2)) {
+          const authFailureReason = classifyOnchainosAuthError(err2);
+          if (authFailureReason) {
             logWithTimestamp(
-              "[xmtp-sdk] refresh: onchainos session expired, taking all local clients offline"
+              `[xmtp-sdk] refresh: onchainos auth unavailable (${authFailureReason}), taking all local clients offline`
             );
             logger.info(LogEvent.AGENT_REFRESH_SESSION_EXPIRED, {
               onchainosAgentId: "*",
+              authFailureReason,
               previousClientCount: String(this.clients.size),
               previousAgentCount: String(this.allAgents.length),
               previousAgentIds: this.allAgents.map((a) => a.agentId).join(","),
@@ -58704,39 +58754,6 @@ var init_cli_response = __esm({
   }
 });
 
-// ../core/src/xmtp-sdk/onchainos/session-expired.ts
-function isSessionExpired(stdout) {
-  try {
-    const res = JSON.parse(stdout);
-    return res.ok === false && SESSION_EXPIRED_RE2.test(String(res.error ?? ""));
-  } catch {
-    return SESSION_EXPIRED_RE2.test(stdout);
-  }
-}
-function reportSessionExpired(command) {
-  logger.error(
-    LogEvent.ONCHAINOS_SESSION_EXPIRED,
-    new Error("onchainos session expired"),
-    {
-      component: "onchainos_cli",
-      source: "onchainos",
-      stage: "session_expired",
-      operation: command,
-      command,
-      communicationClass: "onchainos_auth_issue",
-      reason: "session_expired"
-    }
-  );
-}
-var SESSION_EXPIRED_RE2;
-var init_session_expired = __esm({
-  "../core/src/xmtp-sdk/onchainos/session-expired.ts"() {
-    "use strict";
-    init_sentry_logger();
-    SESSION_EXPIRED_RE2 = /session expired/i;
-  }
-});
-
 // ../core/src/xmtp-sdk/onchainos/offline-replay-capability.ts
 function messageEligibleHelpAdvertisesOfflineReplay(helpText) {
   if (typeof helpText !== "string" || helpText.length === 0) {
@@ -59030,7 +59047,10 @@ async function fetchAgentPage(page) {
   );
   if (!res.ok) {
     guardSessionExpired2(stdout, "list-agents");
-    const parseErr = new Error("onchainos agent get failed");
+    const detail = typeof res.error === "string" ? res.error.trim() : "";
+    const parseErr = new Error(
+      detail ? `onchainos agent get failed: ${detail}` : "onchainos agent get failed"
+    );
     logger.error(
       LogEvent.ONCHAINOS_CLI_ERROR,
       parseErr,
@@ -64725,7 +64745,7 @@ async function handleDaemonCommand(command, params) {
     const payload = await handleXmtpDebugCommand(command, params.service);
     return { ok: true, payload };
   }
-  const refresh = await params.service.refreshAgents();
+  const refresh = await (params.refreshAgents?.() ?? params.service.refreshAgents());
   return {
     ok: true,
     payload: {
@@ -67003,9 +67023,13 @@ var init_user_attention_watchers = __esm({
 // src/listener.ts
 var listener_exports = {};
 __export(listener_exports, {
+  AgentRefreshAuthGate: () => AgentRefreshAuthGate,
+  AgentRefreshCoordinator: () => AgentRefreshCoordinator,
   DEFAULT_OFFLINE_REPLAY_INTERVAL_SEC: () => DEFAULT_OFFLINE_REPLAY_INTERVAL_SEC,
   DEFAULT_XMTP_CLIENT_RECYCLE_INTERVAL_SEC: () => DEFAULT_XMTP_CLIENT_RECYCLE_INTERVAL_SEC,
   HEARTBEAT_GATEWAY_CHECK_TIMEOUT_MS: () => HEARTBEAT_GATEWAY_CHECK_TIMEOUT_MS,
+  ListenerDeferredTaskScheduler: () => ListenerDeferredTaskScheduler,
+  ListenerMaintenanceGate: () => ListenerMaintenanceGate,
   XMTP_CLIENT_RECYCLE_INTERVAL_ENV: () => XMTP_CLIENT_RECYCLE_INTERVAL_ENV,
   getHermesGatewayPluginStatus: () => getHermesGatewayPluginStatus,
   hermesConfigEnablesOkxA2a: () => hermesConfigEnablesOkxA2a,
@@ -67013,8 +67037,15 @@ __export(listener_exports, {
   isHermesGatewayPluginEnabled: () => isHermesGatewayPluginEnabled,
   resolveOfflineReplayIntervalSec: () => resolveOfflineReplayIntervalSec,
   resolveXmtpClientRecycleIntervalSec: () => resolveXmtpClientRecycleIntervalSec,
+  runHeartbeatRefreshCycle: () => runHeartbeatRefreshCycle,
   runListener: () => runListener
 });
+async function runHeartbeatRefreshCycle(options) {
+  const heartbeat = await timeSettled(options.heartbeat);
+  const refreshAllowed = heartbeat.value === "performed" || heartbeat.value === "refresh_safe";
+  const refresh = options.refresh && refreshAllowed ? await timeSettled(options.refresh) : void 0;
+  return { heartbeat, refresh };
+}
 function resolveOfflineReplayIntervalSec(systemConfig) {
   const interval = systemConfig.offlineReplayInterval;
   if (typeof interval !== "number" || !Number.isFinite(interval) || interval <= 0) {
@@ -67212,10 +67243,24 @@ async function runListenerWithLock(options, paths) {
     }
   });
   logWithTimestamp("[okx-agent-task] user_attention watcher coordinator scanning SQLite watcher state");
+  let stopping = false;
   const service = XmtpService.getInstance();
+  const agentRefreshCoordinator = new AgentRefreshCoordinator({
+    lookup: (previousFingerprint) => listAllAgentsWithMetadata(previousFingerprint),
+    refresh: () => service.refreshAgents(),
+    isStopping: () => stopping,
+    onAuthBlocked: () => {
+      logWithTimestamp(
+        "[okx-agent-task] agent refresh auth blocked; periodic agent get paused. After wallet login, run `okx-a2a agent refresh` or restart the daemon"
+      );
+    },
+    onAuthRecovered: () => {
+      logWithTimestamp("[okx-agent-task] agent refresh auth recovered; periodic refresh resumed");
+    }
+  });
   service.setDataDir(paths.xmtpDir);
   service.setTools({
-    listAllAgentsWithMetadata: async (previousFingerprint) => listAllAgentsWithMetadata(previousFingerprint),
+    listAllAgentsWithMetadata: (previousFingerprint) => agentRefreshCoordinator.lookup(previousFingerprint),
     fetchSensitiveWords: async () => fetchSensitiveWords(),
     fetchSystemConfig: async () => fetchSystemConfig({
       notifySessionExpired: (command) => service.tools.notifySessionExpired?.(command)
@@ -67242,7 +67287,7 @@ async function runListenerWithLock(options, paths) {
       }
     }),
     notifySessionExpired: (command) => {
-      const rawText = `The onchainos login session has expired while running ${command}. Run \`onchainos wallet login\` and restart \`okx-a2a\`.`;
+      const rawText = `The onchainos login session has expired while running ${command}. Run \`onchainos wallet login\`, then \`okx-a2a agent refresh\` or restart \`okx-a2a\`.`;
       void store.appendBackup(buildSystemStoredMessage({
         reason: "onchainos-session-expired",
         rawText,
@@ -67270,12 +67315,12 @@ async function runListenerWithLock(options, paths) {
       });
     }
   });
-  service.setPluginVersion("0.2.3");
+  service.setPluginVersion("0.2.4-beta-e7a52faf6f-260811185020");
   await service.init();
   const pluginVersionStatus = service.pluginVersionStatus;
   if (pluginVersionStatus.unavailable) {
     throw new Error(
-      `@okxweb3/a2a-node v${"0.2.3"} is below the required minimum v${pluginVersionStatus.minVersion}`
+      `@okxweb3/a2a-node v${"0.2.4-beta-e7a52faf6f-260811185020"} is below the required minimum v${pluginVersionStatus.minVersion}`
     );
   }
   const systemConfig = service.getSystemConfig();
@@ -67293,7 +67338,7 @@ async function runListenerWithLock(options, paths) {
       onchainosAgentId: "*",
       reason: "system-config missing sentryDsn",
       pluginId: "@okxweb3/a2a-node",
-      pluginVersion: "0.2.3"
+      pluginVersion: "0.2.4-beta-e7a52faf6f-260811185020"
     });
   }
   logWithTimestamp(
@@ -67305,37 +67350,56 @@ async function runListenerWithLock(options, paths) {
   logWithTimestamp(
     `[okx-agent-task] startup replay complete clients=${startupReplaySummary.clients} replayed=${startupReplaySummary.replayed} skipped=${startupReplaySummary.skipped} duration=${startupReplaySummary.durationMs}ms`
   );
-  let maintenanceInFlight = null;
   let lastRecycleReplayAtMs = 0;
-  let xmtpRecyclePending = false;
-  const tryEnterMaintenanceTask = (task) => {
-    if (task !== "xmtp_recycle" && xmtpRecyclePending) {
-      return false;
-    }
-    if (maintenanceInFlight) {
-      return false;
+  const maintenanceGate = new ListenerMaintenanceGate();
+  const deferredMaintenanceTasks = new ListenerDeferredTaskScheduler();
+  const leaveMaintenanceTask = (task) => {
+    const pendingTask = maintenanceGate.leave(task);
+    if (stopping) {
+      return;
     }
-    if (task === "xmtp_recycle") {
-      xmtpRecyclePending = false;
+    if (pendingTask === "xmtp_recycle") {
+      deferredMaintenanceTasks.schedule(() => void xmtpRecycleTick());
+    } else if (pendingTask === "offline_replay") {
+      deferredMaintenanceTasks.schedule(() => void offlineReplayTick());
     }
-    maintenanceInFlight = task;
-    return true;
   };
-  const leaveMaintenanceTask = (task) => {
-    if (maintenanceInFlight === task) {
-      maintenanceInFlight = null;
-      if (xmtpRecyclePending && !stopping) {
-        setTimeout(() => void xmtpRecycleTick(), 0);
+  const syncTick = async () => {
+    if (stopping || agentRefreshCoordinator.blocked) {
+      return;
+    }
+    if (!maintenanceGate.tryEnter("sync")) {
+      return;
+    }
+    const tickStartedAt = Date.now();
+    try {
+      const refresh = await agentRefreshCoordinator.runScheduled();
+      if (!refresh) {
+        return;
       }
+      logWithTimestamp(
+        `[okx-agent-task] sync tick agents=${refresh.agentCount} changed=${refresh.changed ? "yes" : "no"} added=${refresh.added.length} removed=${refresh.removed.length}`
+      );
+    } catch (err2) {
+      logger.error(LogEvent.DAEMON_TICK_FAILED, err2 instanceof Error ? err2 : new Error(String(err2)), {
+        component: "node_listener",
+        stage: "sync_tick",
+        durationMs: String(Date.now() - tickStartedAt),
+        reason: "sync_tick_exception"
+      });
+      logWithTimestamp(`[okx-agent-task] sync tick failed total=${Date.now() - tickStartedAt}ms:`, err2);
+    } finally {
+      leaveMaintenanceTask("sync");
     }
   };
-  const syncTick = async () => {
-    if (!tryEnterMaintenanceTask("sync")) {
-      return;
+  let heartbeatInFlight = false;
+  const heartbeatTick = async () => {
+    if (heartbeatInFlight || stopping) {
+      return "blocked";
     }
+    heartbeatInFlight = true;
     const tickStartedAt = Date.now();
     try {
-      const refresh = await service.refreshAgents();
       const hasActiveAgents = service.getClients().size > 0;
       let shouldHeartbeat = hasActiveAgents;
       const heartbeatProvider = resolveConfiguredAiProvider({ store: sessionStore }) ?? detectGatewayInvocation();
@@ -67350,7 +67414,7 @@ async function runListenerWithLock(options, paths) {
             new Error(`heartbeat gateway check failed: provider=hermes reason=${hermesStatus.reason}`),
             {
               component: "node_listener",
-              stage: "sync_tick",
+              stage: "heartbeat_tick",
               reason: hermesStatus.reason ?? "unknown",
               provider: "hermes",
               hermesHome: hermesStatus.hermesHome,
@@ -67374,7 +67438,7 @@ async function runListenerWithLock(options, paths) {
             new Error(`heartbeat skipped: provider=${heartbeatProvider ?? "(not set)"} gateway unavailable`),
             {
               component: "node_listener",
-              stage: "sync_tick",
+              stage: "heartbeat_tick",
               reason: "gateway_unavailable",
               provider: heartbeatProvider ?? "(not set)",
               chainIndex: ONCHAINOS_CHAIN_INDEX,
@@ -67390,7 +67454,7 @@ async function runListenerWithLock(options, paths) {
           new Error("heartbeat skipped: no active agents"),
           {
             component: "node_listener",
-            stage: "sync_tick",
+            stage: "heartbeat_tick",
             reason: "no_active_agents",
             provider: heartbeatProvider ?? "(not set)",
             chainIndex: ONCHAINOS_CHAIN_INDEX
@@ -67403,7 +67467,7 @@ async function runListenerWithLock(options, paths) {
       if (shouldHeartbeat && heartbeatResult.error) {
         logger.error(LogEvent.HEARTBEAT_FAILED, heartbeatResult.error instanceof Error ? heartbeatResult.error : new Error(String(heartbeatResult.error)), {
           component: "node_listener",
-          stage: "sync_tick",
+          stage: "heartbeat_tick",
           reason: heartbeatResult.error instanceof Error ? heartbeatResult.error.name : "unknown_error",
           durationMs: String(heartbeatMs),
           chainIndex: ONCHAINOS_CHAIN_INDEX,
@@ -67411,23 +67475,27 @@ async function runListenerWithLock(options, paths) {
         });
         logWithTimestamp(`[okx-agent-task] heartbeat failed duration=${heartbeatMs}ms:`, heartbeatResult.error);
       }
-      logWithTimestamp(
-        `[okx-agent-task] sync tick agents=${refresh.agentCount} changed=${refresh.changed ? "yes" : "no"} added=${refresh.added.length} removed=${refresh.removed.length}`
-      );
+      return shouldHeartbeat ? "performed" : "refresh_safe";
     } catch (err2) {
-      logger.error(LogEvent.DAEMON_TICK_FAILED, err2 instanceof Error ? err2 : new Error(String(err2)), {
+      logger.error(LogEvent.HEARTBEAT_FAILED, err2 instanceof Error ? err2 : new Error(String(err2)), {
         component: "node_listener",
-        stage: "sync_tick",
+        stage: "heartbeat_tick",
         durationMs: String(Date.now() - tickStartedAt),
-        reason: "sync_tick_exception"
+        reason: "heartbeat_tick_exception",
+        chainIndex: ONCHAINOS_CHAIN_INDEX,
+        communicationClass: "onchainos_or_network"
       });
-      logWithTimestamp(`[okx-agent-task] sync tick failed total=${Date.now() - tickStartedAt}ms:`, err2);
+      logWithTimestamp(`[okx-agent-task] heartbeat tick failed total=${Date.now() - tickStartedAt}ms:`, err2);
+      return "blocked";
     } finally {
-      leaveMaintenanceTask("sync");
+      heartbeatInFlight = false;
     }
   };
   const offlineReplayTick = async () => {
-    if (!tryEnterMaintenanceTask("offline_replay")) {
+    if (stopping) {
+      return;
+    }
+    if (!maintenanceGate.tryEnter("offline_replay")) {
       return;
     }
     const tickStartedAt = Date.now();
@@ -67469,8 +67537,10 @@ async function runListenerWithLock(options, paths) {
     }
   };
   const xmtpRecycleTick = async () => {
-    if (!tryEnterMaintenanceTask("xmtp_recycle")) {
-      xmtpRecyclePending = true;
+    if (stopping) {
+      return;
+    }
+    if (!maintenanceGate.tryEnter("xmtp_recycle")) {
       return;
     }
     const tickStartedAt = Date.now();
@@ -67514,7 +67584,6 @@ async function runListenerWithLock(options, paths) {
   let timer;
   let offlineReplayTimer;
   let xmtpClientRecycleTimer;
-  let stopping = false;
   const scheduleSyncTimer = (nextIntervalSec) => {
     if (stopping) {
       return;
@@ -67525,7 +67594,10 @@ async function runListenerWithLock(options, paths) {
     intervalSec = Math.max(10, nextIntervalSec);
     logWithTimestamp(`[okx-agent-task] scheduled sync interval ${intervalSec}s`);
     timer = setInterval(() => {
-      void syncTick();
+      void runHeartbeatRefreshCycle({
+        heartbeat: heartbeatTick,
+        refresh: syncTick
+      });
     }, intervalSec * 1e3);
   };
   const scheduleOfflineReplayTimer = (nextIntervalSec) => {
@@ -67607,9 +67679,12 @@ async function runListenerWithLock(options, paths) {
   const systemConfigRefreshTimer = setInterval(() => {
     void refreshSystemConfigTick();
   }, 60 * 60 * 1e3);
-  void syncTick();
+  void runHeartbeatRefreshCycle({
+    heartbeat: heartbeatTick
+  });
   const commandProcessor = startCommandProcessor({
     service,
+    refreshAgents: () => agentRefreshCoordinator.runManual(),
     store,
     sessionStore,
     homeDir: options.homeDir
@@ -67628,6 +67703,7 @@ async function runListenerWithLock(options, paths) {
         resolve14();
       }, SHUTDOWN_FORCE_RESOLVE_MS);
       void (async () => {
+        deferredMaintenanceTasks.cancelAll();
         if (timer) {
           clearInterval(timer);
         }
@@ -67669,7 +67745,7 @@ async function timeSettled(fn) {
     return { durationMs: Date.now() - startedAt, error };
   }
 }
-var import_node_fs25, import_promises13, import_node_os11, import_node_path30, DEFAULT_OFFLINE_REPLAY_INTERVAL_SEC, DEFAULT_XMTP_CLIENT_RECYCLE_INTERVAL_SEC, XMTP_CLIENT_RECYCLE_INTERVAL_ENV, HEARTBEAT_GATEWAY_CHECK_TIMEOUT_MS, UPGRADE_RECOMMENDATION_IDEMPOTENCY_KEY, SHUTDOWN_FORCE_RESOLVE_MS;
+var import_node_fs25, import_promises13, import_node_os11, import_node_path30, DEFAULT_OFFLINE_REPLAY_INTERVAL_SEC, DEFAULT_XMTP_CLIENT_RECYCLE_INTERVAL_SEC, XMTP_CLIENT_RECYCLE_INTERVAL_ENV, HEARTBEAT_GATEWAY_CHECK_TIMEOUT_MS, AgentRefreshAuthGate, AgentRefreshCoordinator, ListenerDeferredTaskScheduler, ListenerMaintenanceGate, UPGRADE_RECOMMENDATION_IDEMPOTENCY_KEY, SHUTDOWN_FORCE_RESOLVE_MS;
 var init_listener = __esm({
   "src/listener.ts"() {
     "use strict";
@@ -67702,6 +67778,107 @@ var init_listener = __esm({
     DEFAULT_XMTP_CLIENT_RECYCLE_INTERVAL_SEC = 6 * 60 * 60;
     XMTP_CLIENT_RECYCLE_INTERVAL_ENV = "OKX_A2A_XMTP_CLIENT_RECYCLE_INTERVAL_SEC";
     HEARTBEAT_GATEWAY_CHECK_TIMEOUT_MS = 2e3;
+    AgentRefreshAuthGate = class {
+      authBlocked = false;
+      get blocked() {
+        return this.authBlocked;
+      }
+      recordSuccess() {
+        this.authBlocked = false;
+      }
+      recordFailure(err2) {
+        if (!isOnchainosAuthError(err2)) {
+          return false;
+        }
+        this.authBlocked = true;
+        return true;
+      }
+    };
+    AgentRefreshCoordinator = class {
+      constructor(options) {
+        this.options = options;
+      }
+      options;
+      authGate = new AgentRefreshAuthGate();
+      get blocked() {
+        return this.authGate.blocked;
+      }
+      async lookup(previousFingerprint) {
+        const wasBlocked = this.authGate.blocked;
+        try {
+          const result = await this.options.lookup(previousFingerprint);
+          this.authGate.recordSuccess();
+          if (wasBlocked) {
+            this.options.onAuthRecovered?.();
+          }
+          return result;
+        } catch (err2) {
+          if (this.authGate.recordFailure(err2) && !wasBlocked) {
+            this.options.onAuthBlocked?.();
+          }
+          throw err2;
+        }
+      }
+      async runScheduled() {
+        if (this.options.isStopping() || this.authGate.blocked) {
+          return null;
+        }
+        return this.options.refresh();
+      }
+      async runManual() {
+        return this.options.refresh();
+      }
+    };
+    ListenerDeferredTaskScheduler = class {
+      timers = /* @__PURE__ */ new Set();
+      schedule(task) {
+        const timer = setTimeout(() => {
+          this.timers.delete(timer);
+          task();
+        }, 0);
+        this.timers.add(timer);
+      }
+      cancelAll() {
+        for (const timer of this.timers) {
+          clearTimeout(timer);
+        }
+        this.timers.clear();
+      }
+    };
+    ListenerMaintenanceGate = class {
+      inFlight = null;
+      offlineReplayPending = false;
+      xmtpRecyclePending = false;
+      tryEnter(task) {
+        if (task !== "xmtp_recycle" && this.xmtpRecyclePending || this.inFlight) {
+          if (task === "offline_replay") {
+            this.offlineReplayPending = true;
+          } else if (task === "xmtp_recycle") {
+            this.xmtpRecyclePending = true;
+          }
+          return false;
+        }
+        if (task === "xmtp_recycle") {
+          this.xmtpRecyclePending = false;
+        }
+        this.inFlight = task;
+        return true;
+      }
+      leave(task) {
+        if (this.inFlight !== task) {
+          return null;
+        }
+        this.inFlight = null;
+        if (this.xmtpRecyclePending) {
+          return "xmtp_recycle";
+        }
+        if (this.offlineReplayPending) {
+          this.offlineReplayPending = false;
+          return "offline_replay";
+        }
+        return null;
+      }
+    };
     UPGRADE_RECOMMENDATION_IDEMPOTENCY_KEY = "system:onchainos-offline-replay-upgrade";
     SHUTDOWN_FORCE_RESOLVE_MS = 5e3;
   }
@@ -115480,7 +115657,7 @@ async function getCurrentNodeCliVersion() {
   return await getGlobalNpmPackageVersion(UPDATE_PACKAGES.node) ?? getBundledNodeCliVersion();
 }
 function getBundledNodeCliVersion() {
-  return true ? "0.2.3" : null;
+  return true ? "0.2.4-beta-e7a52faf6f-260811185020" : null;
 }
 function readConfiguredAiProvider() {
   const explicit = process.env.OKX_A2A_AI_PROVIDER || process.env.OKX_AGENT_TASK_AI_CLI;
@@ -115690,7 +115867,7 @@ async function updateHermes(release, options) {
   }
 }
 async function installGatewayPluginForDoctor(target) {
-  const release = isPrereleaseVersion("0.2.3") ? "beta" : "latest";
+  const release = isPrereleaseVersion("0.2.4-beta-e7a52faf6f-260811185020") ? "beta" : "latest";
   const insideTargetGateway = detectGatewayInvocation() === target;
   const options = {
     restart: !insideTargetGateway,
@@ -116733,7 +116910,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.3" : "0.0.0"),
+    cliVersion: options.cliVersion ?? (true ? "0.2.4-beta-e7a52faf6f-260811185020" : "0.0.0"),
     fixMode: options.fix === true,
     nonInteractive: options.nonInteractive === true,
     packageChanged: false,
@@ -117730,7 +117907,7 @@ init_sentry_logger();
 init_sentry_config();
 var CURRENT_GATEWAY_SESSION_KEYS_ENV4 = "OKX_A2A_CURRENT_GATEWAY_SESSION_KEYS";
 function printUsage3() {
-  console.log(`okx-a2a ${"0.2.3"}
+  console.log(`okx-a2a ${"0.2.4-beta-e7a52faf6f-260811185020"}
 
 Usage:
   okx-a2a <command> [options]
@@ -117770,7 +117947,7 @@ Run \`okx-a2a <command> -h\` for command-specific help.
 `);
 }
 function printVersion() {
-  console.log("0.2.3");
+  console.log("0.2.4-beta-e7a52faf6f-260811185020");
 }
 function printDaemonUsage() {
   console.log(`Usage: okx-a2a daemon <start|restart|stop|status|autostart> [options]
@@ -119206,7 +119383,7 @@ async function main() {
   if (command === "xmtp-test") {
     const { handleXmtpTestCommand: handleXmtpTestCommand2 } = await Promise.resolve().then(() => (init_xmtp_test_cli(), xmtp_test_cli_exports));
     await handleXmtpTestCommand2(process.argv.slice(3), {
-      packageVersion: "0.2.3",
+      packageVersion: "0.2.4-beta-e7a52faf6f-260811185020",
       agentSdkVersion: "2.3.0",
       nodeSdkVersion: "6.1.0",
       nodeBindingsVersion: "1.11.0"

package/dist/index.js

@@ -32104,7 +32104,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.3",
+      release: "0.2.4-beta-e7a52faf6f-260811185020",
       environment,
       runtimeContainer: normalizeRuntimeContainer(process.env.OKX_A2A_RUNTIME_CONTAINER)
     };
@@ -33045,7 +33045,7 @@ async function getCurrentNodeCliVersion() {
   return await getGlobalNpmPackageVersion(UPDATE_PACKAGES.node) ?? getBundledNodeCliVersion();
 }
 function getBundledNodeCliVersion() {
-  return true ? "0.2.3" : null;
+  return true ? "0.2.4-beta-e7a52faf6f-260811185020" : null;
 }
 function readConfiguredAiProvider() {
   const explicit = process.env.OKX_A2A_AI_PROVIDER || process.env.OKX_AGENT_TASK_AI_CLI;
@@ -33255,7 +33255,7 @@ async function updateHermes(release, options) {
   }
 }
 async function installGatewayPluginForDoctor(target) {
-  const release = isPrereleaseVersion("0.2.3") ? "beta" : "latest";
+  const release = isPrereleaseVersion("0.2.4-beta-e7a52faf6f-260811185020") ? "beta" : "latest";
   const insideTargetGateway = detectGatewayInvocation() === target;
   const options = {
     restart: !insideTargetGateway,
@@ -43946,6 +43946,8 @@ var index_exports = {};
 __export(index_exports, {
   AI_PROVIDERS: () => AI_PROVIDERS,
   AgentMessageDirection: () => AgentMessageDirection,
+  AgentRefreshAuthGate: () => AgentRefreshAuthGate,
+  AgentRefreshCoordinator: () => AgentRefreshCoordinator,
   AiRunner: () => AiRunner,
   BACKUP_JOB_ID: () => BACKUP_JOB_ID,
   CODEX_APP_DIRS_ENV: () => CODEX_APP_DIRS_ENV,
@@ -43965,6 +43967,8 @@ __export(index_exports, {
   InboundReplayGate: () => InboundReplayGate,
   InvalidXmtpMessageStore: () => InvalidXmtpMessageStore,
   JOB_PROVIDER_BINDING_SOURCES: () => JOB_PROVIDER_BINDING_SOURCES,
+  ListenerDeferredTaskScheduler: () => ListenerDeferredTaskScheduler,
+  ListenerMaintenanceGate: () => ListenerMaintenanceGate,
   LogEvent: () => LogEvent,
   MESSAGE_ELIGIBLE_OFFLINE_REPLAY_FLAG: () => MESSAGE_ELIGIBLE_OFFLINE_REPLAY_FLAG,
   MESSAGE_ELIGIBLE_OFFLINE_REPLAY_HELP_TOKEN: () => MESSAGE_ELIGIBLE_OFFLINE_REPLAY_HELP_TOKEN,
@@ -44161,6 +44165,7 @@ __export(index_exports, {
   resolveXmtpClientRecycleIntervalSec: () => resolveXmtpClientRecycleIntervalSec,
   runAiAdapter: () => runAiAdapter,
   runDoctor: () => runDoctor,
+  runHeartbeatRefreshCycle: () => runHeartbeatRefreshCycle,
   runListener: () => runListener,
   scanUserAttentionWatchers: () => scanUserAttentionWatchers,
   setOpenClawWebSocketFactoryForTests: () => setOpenClawWebSocketFactoryForTests,
@@ -55865,6 +55870,63 @@ function compareTimestamp(a, b) {
   return 0;
 }
 
+// ../core/src/xmtp-sdk/onchainos/session-expired.ts
+init_sentry_logger();
+var SESSION_EXPIRED_RE = /session expired/i;
+var AUTH_FAILURE_PATTERNS = [
+  ["session_expired", /session expired/i],
+  ["not_logged_in", /not logged in/i],
+  ["login_required", /login required/i],
+  ["authentication_required", /authentication required/i]
+];
+function isSessionExpired(stdout) {
+  try {
+    const res = JSON.parse(stdout);
+    return res.ok === false && SESSION_EXPIRED_RE.test(String(res.error ?? ""));
+  } catch {
+    return SESSION_EXPIRED_RE.test(stdout);
+  }
+}
+function classifyOnchainosAuthError(err) {
+  if (!err) {
+    return null;
+  }
+  const values = [String(err)];
+  if (typeof err === "object") {
+    const anyErr = err;
+    values.push(anyErr.stdout, anyErr.stderr, anyErr.message);
+  }
+  for (const value of values) {
+    if (typeof value !== "string") {
+      continue;
+    }
+    for (const [reason, pattern] of AUTH_FAILURE_PATTERNS) {
+      if (pattern.test(value)) {
+        return reason;
+      }
+    }
+  }
+  return null;
+}
+function isOnchainosAuthError(err) {
+  return classifyOnchainosAuthError(err) !== null;
+}
+function reportSessionExpired(command) {
+  logger.error(
+    LogEvent.ONCHAINOS_SESSION_EXPIRED,
+    new Error("onchainos session expired"),
+    {
+      component: "onchainos_cli",
+      source: "onchainos",
+      stage: "session_expired",
+      operation: command,
+      command,
+      communicationClass: "onchainos_auth_issue",
+      reason: "session_expired"
+    }
+  );
+}
+
 // ../core/src/xmtp-sdk/index.ts
 var DEFAULT_DATA_DIR = resolveA2aTaskPaths().xmtpDir;
 var XMTP_INSTALLATION_WARNING_THRESHOLD = 2;
@@ -55898,22 +55960,6 @@ function ensureCacheDir(dataDir) {
   ensureA2aTaskDir(dataDir);
 }
 var SENSITIVE_WORDS_LAZY_RETRY_COOLDOWN_MS = 10 * 60 * 1e3;
-var SESSION_EXPIRED_RE = /session expired/i;
-function isSessionExpiredError(err) {
-  if (!err) {
-    return false;
-  }
-  if (typeof err === "object") {
-    const anyErr = err;
-    if (typeof anyErr.stdout === "string" && SESSION_EXPIRED_RE.test(anyErr.stdout)) {
-      return true;
-    }
-    if (typeof anyErr.message === "string" && SESSION_EXPIRED_RE.test(anyErr.message)) {
-      return true;
-    }
-  }
-  return SESSION_EXPIRED_RE.test(String(err));
-}
 function loadSensitiveWordsFromCache(dataDir) {
   try {
     const path2 = cachePath(dataDir, "sensitive-words.json");
@@ -56832,12 +56878,14 @@ var XmtpService = class _XmtpService {
       newAgents = agentList.agents;
       changed = agentList.changed;
     } catch (err) {
-      if (isSessionExpiredError(err)) {
+      const authFailureReason = classifyOnchainosAuthError(err);
+      if (authFailureReason) {
         logWithTimestamp(
-          "[xmtp-sdk] refresh: onchainos session expired, taking all local clients offline"
+          `[xmtp-sdk] refresh: onchainos auth unavailable (${authFailureReason}), taking all local clients offline`
         );
         logger.info(LogEvent.AGENT_REFRESH_SESSION_EXPIRED, {
           onchainosAgentId: "*",
+          authFailureReason,
           previousClientCount: String(this.clients.size),
           previousAgentCount: String(this.allAgents.length),
           previousAgentIds: this.allAgents.map((a) => a.agentId).join(","),
@@ -58744,33 +58792,6 @@ function parseCliJson(stdout, command, extras = {}) {
   }
 }
 
-// ../core/src/xmtp-sdk/onchainos/session-expired.ts
-init_sentry_logger();
-var SESSION_EXPIRED_RE2 = /session expired/i;
-function isSessionExpired(stdout) {
-  try {
-    const res = JSON.parse(stdout);
-    return res.ok === false && SESSION_EXPIRED_RE2.test(String(res.error ?? ""));
-  } catch {
-    return SESSION_EXPIRED_RE2.test(stdout);
-  }
-}
-function reportSessionExpired(command) {
-  logger.error(
-    LogEvent.ONCHAINOS_SESSION_EXPIRED,
-    new Error("onchainos session expired"),
-    {
-      component: "onchainos_cli",
-      source: "onchainos",
-      stage: "session_expired",
-      operation: command,
-      command,
-      communicationClass: "onchainos_auth_issue",
-      reason: "session_expired"
-    }
-  );
-}
-
 // ../core/src/xmtp-sdk/onchainos/offline-replay-capability.ts
 init_log();
 var MESSAGE_ELIGIBLE_OFFLINE_REPLAY_FLAG = "--is-offline-replay";
@@ -59056,7 +59077,10 @@ async function fetchAgentPage(page) {
   );
   if (!res.ok) {
     guardSessionExpired2(stdout, "list-agents");
-    const parseErr = new Error("onchainos agent get failed");
+    const detail = typeof res.error === "string" ? res.error.trim() : "";
+    const parseErr = new Error(
+      detail ? `onchainos agent get failed: ${detail}` : "onchainos agent get failed"
+    );
     logger.error(
       LogEvent.ONCHAINOS_CLI_ERROR,
       parseErr,
@@ -60181,7 +60205,7 @@ function buildConnectParams(config, instanceId, protocolVersion) {
     client: {
       id: "gateway-client",
       displayName: "okx-a2a-node",
-      version: "0.2.3",
+      version: "0.2.4-beta-e7a52faf6f-260811185020",
       platform: "node",
       mode: "backend",
       instanceId
@@ -60192,7 +60216,7 @@ function buildConnectParams(config, instanceId, protocolVersion) {
     commands: [],
     permissions: {},
     locale: Intl.DateTimeFormat().resolvedOptions().locale || "en-US",
-    userAgent: `okx-a2a-node/${"0.2.3"}`,
+    userAgent: `okx-a2a-node/${"0.2.4-beta-e7a52faf6f-260811185020"}`,
     auth: {
       ...config.token ? { token: config.token } : {},
       ...config.password ? { password: config.password } : {}
@@ -63621,7 +63645,7 @@ async function handleDaemonCommand(command, params) {
     const payload = await handleXmtpDebugCommand(command, params.service);
     return { ok: true, payload };
   }
-  const refresh = await params.service.refreshAgents();
+  const refresh = await (params.refreshAgents?.() ?? params.service.refreshAgents());
   return {
     ok: true,
     payload: {
@@ -65974,6 +65998,113 @@ var DEFAULT_OFFLINE_REPLAY_INTERVAL_SEC = 300;
 var DEFAULT_XMTP_CLIENT_RECYCLE_INTERVAL_SEC = 6 * 60 * 60;
 var XMTP_CLIENT_RECYCLE_INTERVAL_ENV = "OKX_A2A_XMTP_CLIENT_RECYCLE_INTERVAL_SEC";
 var HEARTBEAT_GATEWAY_CHECK_TIMEOUT_MS = 2e3;
+async function runHeartbeatRefreshCycle(options) {
+  const heartbeat = await timeSettled(options.heartbeat);
+  const refreshAllowed = heartbeat.value === "performed" || heartbeat.value === "refresh_safe";
+  const refresh = options.refresh && refreshAllowed ? await timeSettled(options.refresh) : void 0;
+  return { heartbeat, refresh };
+}
+var AgentRefreshAuthGate = class {
+  authBlocked = false;
+  get blocked() {
+    return this.authBlocked;
+  }
+  recordSuccess() {
+    this.authBlocked = false;
+  }
+  recordFailure(err) {
+    if (!isOnchainosAuthError(err)) {
+      return false;
+    }
+    this.authBlocked = true;
+    return true;
+  }
+};
+var AgentRefreshCoordinator = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  authGate = new AgentRefreshAuthGate();
+  get blocked() {
+    return this.authGate.blocked;
+  }
+  async lookup(previousFingerprint) {
+    const wasBlocked = this.authGate.blocked;
+    try {
+      const result = await this.options.lookup(previousFingerprint);
+      this.authGate.recordSuccess();
+      if (wasBlocked) {
+        this.options.onAuthRecovered?.();
+      }
+      return result;
+    } catch (err) {
+      if (this.authGate.recordFailure(err) && !wasBlocked) {
+        this.options.onAuthBlocked?.();
+      }
+      throw err;
+    }
+  }
+  async runScheduled() {
+    if (this.options.isStopping() || this.authGate.blocked) {
+      return null;
+    }
+    return this.options.refresh();
+  }
+  async runManual() {
+    return this.options.refresh();
+  }
+};
+var ListenerDeferredTaskScheduler = class {
+  timers = /* @__PURE__ */ new Set();
+  schedule(task) {
+    const timer = setTimeout(() => {
+      this.timers.delete(timer);
+      task();
+    }, 0);
+    this.timers.add(timer);
+  }
+  cancelAll() {
+    for (const timer of this.timers) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+  }
+};
+var ListenerMaintenanceGate = class {
+  inFlight = null;
+  offlineReplayPending = false;
+  xmtpRecyclePending = false;
+  tryEnter(task) {
+    if (task !== "xmtp_recycle" && this.xmtpRecyclePending || this.inFlight) {
+      if (task === "offline_replay") {
+        this.offlineReplayPending = true;
+      } else if (task === "xmtp_recycle") {
+        this.xmtpRecyclePending = true;
+      }
+      return false;
+    }
+    if (task === "xmtp_recycle") {
+      this.xmtpRecyclePending = false;
+    }
+    this.inFlight = task;
+    return true;
+  }
+  leave(task) {
+    if (this.inFlight !== task) {
+      return null;
+    }
+    this.inFlight = null;
+    if (this.xmtpRecyclePending) {
+      return "xmtp_recycle";
+    }
+    if (this.offlineReplayPending) {
+      this.offlineReplayPending = false;
+      return "offline_replay";
+    }
+    return null;
+  }
+};
 var UPGRADE_RECOMMENDATION_IDEMPOTENCY_KEY = "system:onchainos-offline-replay-upgrade";
 function resolveOfflineReplayIntervalSec(systemConfig) {
   const interval = systemConfig.offlineReplayInterval;
@@ -66173,10 +66304,24 @@ async function runListenerWithLock(options, paths) {
     }
   });
   logWithTimestamp("[okx-agent-task] user_attention watcher coordinator scanning SQLite watcher state");
+  let stopping = false;
   const service = XmtpService.getInstance();
+  const agentRefreshCoordinator = new AgentRefreshCoordinator({
+    lookup: (previousFingerprint) => listAllAgentsWithMetadata(previousFingerprint),
+    refresh: () => service.refreshAgents(),
+    isStopping: () => stopping,
+    onAuthBlocked: () => {
+      logWithTimestamp(
+        "[okx-agent-task] agent refresh auth blocked; periodic agent get paused. After wallet login, run `okx-a2a agent refresh` or restart the daemon"
+      );
+    },
+    onAuthRecovered: () => {
+      logWithTimestamp("[okx-agent-task] agent refresh auth recovered; periodic refresh resumed");
+    }
+  });
   service.setDataDir(paths.xmtpDir);
   service.setTools({
-    listAllAgentsWithMetadata: async (previousFingerprint) => listAllAgentsWithMetadata(previousFingerprint),
+    listAllAgentsWithMetadata: (previousFingerprint) => agentRefreshCoordinator.lookup(previousFingerprint),
     fetchSensitiveWords: async () => fetchSensitiveWords(),
     fetchSystemConfig: async () => fetchSystemConfig({
       notifySessionExpired: (command) => service.tools.notifySessionExpired?.(command)
@@ -66203,7 +66348,7 @@ async function runListenerWithLock(options, paths) {
       }
     }),
     notifySessionExpired: (command) => {
-      const rawText = `The onchainos login session has expired while running ${command}. Run \`onchainos wallet login\` and restart \`okx-a2a\`.`;
+      const rawText = `The onchainos login session has expired while running ${command}. Run \`onchainos wallet login\`, then \`okx-a2a agent refresh\` or restart \`okx-a2a\`.`;
       void store.appendBackup(buildSystemStoredMessage({
         reason: "onchainos-session-expired",
         rawText,
@@ -66231,12 +66376,12 @@ async function runListenerWithLock(options, paths) {
       });
     }
   });
-  service.setPluginVersion("0.2.3");
+  service.setPluginVersion("0.2.4-beta-e7a52faf6f-260811185020");
   await service.init();
   const pluginVersionStatus = service.pluginVersionStatus;
   if (pluginVersionStatus.unavailable) {
     throw new Error(
-      `@okxweb3/a2a-node v${"0.2.3"} is below the required minimum v${pluginVersionStatus.minVersion}`
+      `@okxweb3/a2a-node v${"0.2.4-beta-e7a52faf6f-260811185020"} is below the required minimum v${pluginVersionStatus.minVersion}`
     );
   }
   const systemConfig = service.getSystemConfig();
@@ -66254,7 +66399,7 @@ async function runListenerWithLock(options, paths) {
       onchainosAgentId: "*",
       reason: "system-config missing sentryDsn",
       pluginId: "@okxweb3/a2a-node",
-      pluginVersion: "0.2.3"
+      pluginVersion: "0.2.4-beta-e7a52faf6f-260811185020"
     });
   }
   logWithTimestamp(
@@ -66266,37 +66411,56 @@ async function runListenerWithLock(options, paths) {
   logWithTimestamp(
     `[okx-agent-task] startup replay complete clients=${startupReplaySummary.clients} replayed=${startupReplaySummary.replayed} skipped=${startupReplaySummary.skipped} duration=${startupReplaySummary.durationMs}ms`
   );
-  let maintenanceInFlight = null;
   let lastRecycleReplayAtMs = 0;
-  let xmtpRecyclePending = false;
-  const tryEnterMaintenanceTask = (task) => {
-    if (task !== "xmtp_recycle" && xmtpRecyclePending) {
-      return false;
+  const maintenanceGate = new ListenerMaintenanceGate();
+  const deferredMaintenanceTasks = new ListenerDeferredTaskScheduler();
+  const leaveMaintenanceTask = (task) => {
+    const pendingTask = maintenanceGate.leave(task);
+    if (stopping) {
+      return;
     }
-    if (maintenanceInFlight) {
-      return false;
+    if (pendingTask === "xmtp_recycle") {
+      deferredMaintenanceTasks.schedule(() => void xmtpRecycleTick());
+    } else if (pendingTask === "offline_replay") {
+      deferredMaintenanceTasks.schedule(() => void offlineReplayTick());
     }
-    if (task === "xmtp_recycle") {
-      xmtpRecyclePending = false;
-    }
-    maintenanceInFlight = task;
-    return true;
   };
-  const leaveMaintenanceTask = (task) => {
-    if (maintenanceInFlight === task) {
-      maintenanceInFlight = null;
-      if (xmtpRecyclePending && !stopping) {
-        setTimeout(() => void xmtpRecycleTick(), 0);
+  const syncTick = async () => {
+    if (stopping || agentRefreshCoordinator.blocked) {
+      return;
+    }
+    if (!maintenanceGate.tryEnter("sync")) {
+      return;
+    }
+    const tickStartedAt = Date.now();
+    try {
+      const refresh = await agentRefreshCoordinator.runScheduled();
+      if (!refresh) {
+        return;
       }
+      logWithTimestamp(
+        `[okx-agent-task] sync tick agents=${refresh.agentCount} changed=${refresh.changed ? "yes" : "no"} added=${refresh.added.length} removed=${refresh.removed.length}`
+      );
+    } catch (err) {
+      logger.error(LogEvent.DAEMON_TICK_FAILED, err instanceof Error ? err : new Error(String(err)), {
+        component: "node_listener",
+        stage: "sync_tick",
+        durationMs: String(Date.now() - tickStartedAt),
+        reason: "sync_tick_exception"
+      });
+      logWithTimestamp(`[okx-agent-task] sync tick failed total=${Date.now() - tickStartedAt}ms:`, err);
+    } finally {
+      leaveMaintenanceTask("sync");
     }
   };
-  const syncTick = async () => {
-    if (!tryEnterMaintenanceTask("sync")) {
-      return;
+  let heartbeatInFlight = false;
+  const heartbeatTick = async () => {
+    if (heartbeatInFlight || stopping) {
+      return "blocked";
     }
+    heartbeatInFlight = true;
     const tickStartedAt = Date.now();
     try {
-      const refresh = await service.refreshAgents();
       const hasActiveAgents = service.getClients().size > 0;
       let shouldHeartbeat = hasActiveAgents;
       const heartbeatProvider = resolveConfiguredAiProvider({ store: sessionStore }) ?? detectGatewayInvocation();
@@ -66311,7 +66475,7 @@ async function runListenerWithLock(options, paths) {
             new Error(`heartbeat gateway check failed: provider=hermes reason=${hermesStatus.reason}`),
             {
               component: "node_listener",
-              stage: "sync_tick",
+              stage: "heartbeat_tick",
               reason: hermesStatus.reason ?? "unknown",
               provider: "hermes",
               hermesHome: hermesStatus.hermesHome,
@@ -66335,7 +66499,7 @@ async function runListenerWithLock(options, paths) {
             new Error(`heartbeat skipped: provider=${heartbeatProvider ?? "(not set)"} gateway unavailable`),
             {
               component: "node_listener",
-              stage: "sync_tick",
+              stage: "heartbeat_tick",
               reason: "gateway_unavailable",
               provider: heartbeatProvider ?? "(not set)",
               chainIndex: ONCHAINOS_CHAIN_INDEX,
@@ -66351,7 +66515,7 @@ async function runListenerWithLock(options, paths) {
           new Error("heartbeat skipped: no active agents"),
           {
             component: "node_listener",
-            stage: "sync_tick",
+            stage: "heartbeat_tick",
             reason: "no_active_agents",
             provider: heartbeatProvider ?? "(not set)",
             chainIndex: ONCHAINOS_CHAIN_INDEX
@@ -66364,7 +66528,7 @@ async function runListenerWithLock(options, paths) {
       if (shouldHeartbeat && heartbeatResult.error) {
         logger.error(LogEvent.HEARTBEAT_FAILED, heartbeatResult.error instanceof Error ? heartbeatResult.error : new Error(String(heartbeatResult.error)), {
           component: "node_listener",
-          stage: "sync_tick",
+          stage: "heartbeat_tick",
           reason: heartbeatResult.error instanceof Error ? heartbeatResult.error.name : "unknown_error",
           durationMs: String(heartbeatMs),
           chainIndex: ONCHAINOS_CHAIN_INDEX,
@@ -66372,23 +66536,27 @@ async function runListenerWithLock(options, paths) {
         });
         logWithTimestamp(`[okx-agent-task] heartbeat failed duration=${heartbeatMs}ms:`, heartbeatResult.error);
       }
-      logWithTimestamp(
-        `[okx-agent-task] sync tick agents=${refresh.agentCount} changed=${refresh.changed ? "yes" : "no"} added=${refresh.added.length} removed=${refresh.removed.length}`
-      );
+      return shouldHeartbeat ? "performed" : "refresh_safe";
     } catch (err) {
-      logger.error(LogEvent.DAEMON_TICK_FAILED, err instanceof Error ? err : new Error(String(err)), {
+      logger.error(LogEvent.HEARTBEAT_FAILED, err instanceof Error ? err : new Error(String(err)), {
         component: "node_listener",
-        stage: "sync_tick",
+        stage: "heartbeat_tick",
         durationMs: String(Date.now() - tickStartedAt),
-        reason: "sync_tick_exception"
+        reason: "heartbeat_tick_exception",
+        chainIndex: ONCHAINOS_CHAIN_INDEX,
+        communicationClass: "onchainos_or_network"
       });
-      logWithTimestamp(`[okx-agent-task] sync tick failed total=${Date.now() - tickStartedAt}ms:`, err);
+      logWithTimestamp(`[okx-agent-task] heartbeat tick failed total=${Date.now() - tickStartedAt}ms:`, err);
+      return "blocked";
     } finally {
-      leaveMaintenanceTask("sync");
+      heartbeatInFlight = false;
     }
   };
   const offlineReplayTick = async () => {
-    if (!tryEnterMaintenanceTask("offline_replay")) {
+    if (stopping) {
+      return;
+    }
+    if (!maintenanceGate.tryEnter("offline_replay")) {
       return;
     }
     const tickStartedAt = Date.now();
@@ -66430,8 +66598,10 @@ async function runListenerWithLock(options, paths) {
     }
   };
   const xmtpRecycleTick = async () => {
-    if (!tryEnterMaintenanceTask("xmtp_recycle")) {
-      xmtpRecyclePending = true;
+    if (stopping) {
+      return;
+    }
+    if (!maintenanceGate.tryEnter("xmtp_recycle")) {
       return;
     }
     const tickStartedAt = Date.now();
@@ -66475,7 +66645,6 @@ async function runListenerWithLock(options, paths) {
   let timer;
   let offlineReplayTimer;
   let xmtpClientRecycleTimer;
-  let stopping = false;
   const scheduleSyncTimer = (nextIntervalSec) => {
     if (stopping) {
       return;
@@ -66486,7 +66655,10 @@ async function runListenerWithLock(options, paths) {
     intervalSec = Math.max(10, nextIntervalSec);
     logWithTimestamp(`[okx-agent-task] scheduled sync interval ${intervalSec}s`);
     timer = setInterval(() => {
-      void syncTick();
+      void runHeartbeatRefreshCycle({
+        heartbeat: heartbeatTick,
+        refresh: syncTick
+      });
     }, intervalSec * 1e3);
   };
   const scheduleOfflineReplayTimer = (nextIntervalSec) => {
@@ -66568,9 +66740,12 @@ async function runListenerWithLock(options, paths) {
   const systemConfigRefreshTimer = setInterval(() => {
     void refreshSystemConfigTick();
   }, 60 * 60 * 1e3);
-  void syncTick();
+  void runHeartbeatRefreshCycle({
+    heartbeat: heartbeatTick
+  });
   const commandProcessor = startCommandProcessor({
     service,
+    refreshAgents: () => agentRefreshCoordinator.runManual(),
     store,
     sessionStore,
     homeDir: options.homeDir
@@ -66589,6 +66764,7 @@ async function runListenerWithLock(options, paths) {
         resolve11();
       }, SHUTDOWN_FORCE_RESOLVE_MS);
       void (async () => {
+        deferredMaintenanceTasks.cancelAll();
         if (timer) {
           clearInterval(timer);
         }
@@ -68900,7 +69076,7 @@ async function exportDiagnosticLogs(options) {
     node: process.version,
     platform: process.platform,
     arch: process.arch,
-    packageVersion: true ? "0.2.3" : "unknown",
+    packageVersion: true ? "0.2.4-beta-e7a52faf6f-260811185020" : "unknown",
     sensitiveContentIncluded: options.includeSensitiveContent,
     listenerAndLlmContentIncluded: true,
     credentialsAlwaysRedacted: true,
@@ -70736,7 +70912,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.3" : "0.0.0"),
+    cliVersion: options.cliVersion ?? (true ? "0.2.4-beta-e7a52faf6f-260811185020" : "0.0.0"),
     fixMode: options.fix === true,
     nonInteractive: options.nonInteractive === true,
     packageChanged: false,
@@ -70959,6 +71135,8 @@ init_autostart_windows();
 0 && (module.exports = {
   AI_PROVIDERS,
   AgentMessageDirection,
+  AgentRefreshAuthGate,
+  AgentRefreshCoordinator,
   AiRunner,
   BACKUP_JOB_ID,
   CODEX_APP_DIRS_ENV,
@@ -70978,6 +71156,8 @@ init_autostart_windows();
   InboundReplayGate,
   InvalidXmtpMessageStore,
   JOB_PROVIDER_BINDING_SOURCES,
+  ListenerDeferredTaskScheduler,
+  ListenerMaintenanceGate,
   LogEvent,
   MESSAGE_ELIGIBLE_OFFLINE_REPLAY_FLAG,
   MESSAGE_ELIGIBLE_OFFLINE_REPLAY_HELP_TOKEN,
@@ -71174,6 +71354,7 @@ init_autostart_windows();
   resolveXmtpClientRecycleIntervalSec,
   runAiAdapter,
   runDoctor,
+  runHeartbeatRefreshCycle,
   runListener,
   scanUserAttentionWatchers,
   setOpenClawWebSocketFactoryForTests,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okxweb3/a2a-node",
-  "version": "0.2.3",
+  "version": "0.2.4-beta-e7a52faf6f-260811185020",
   "description": "Host-agnostic Node CLI for E2E encrypted agent-to-agent communication via XMTP",
   "main": "dist/index.js",
   "bin": {