@okxweb3/a2a-node 0.2.0 → 0.2.1-beta-8ae7a0d300-260807181806

package/dist/index.js

@@ -19597,12 +19597,15 @@ var init_events = __esm({
       INBOUND_DELIVERED: "Inbound delivered to session",
       DM_DELIVERED: "DM delivered to session",
       OUTBOUND_ELIGIBILITY_CHECKED: "Outbound eligibility checked",
+      MESSAGE_ELIGIBILITY_CHECKED: "Message eligibility checked",
       AGENT_CLIENT_CREATED: "Agent client created",
       AGENT_INSTALLATION_SUMMARY: "Agent installation summary",
       XMTP_HISTORY_SYNC_REQUESTED: "XMTP history sync requested",
       XMTP_DEBUG_SYNC_REQUESTED: "XMTP debug sync requested",
       XMTP_DEBUG_SYNC_COMPLETED: "XMTP debug sync completed",
       AGENT_CLIENT_REMOVED: "Agent client removed",
+      AGENT_STREAM_RECOVERED: "Agent stream recovered",
+      AGENT_STREAM_RECOVERY_REPLAY_COMPLETED: "Agent stream recovery replay completed",
       ADDRESS_SYNC_COMPLETED: "Address sync completed",
       AGENT_REFRESH_SESSION_EXPIRED: "Agent refresh aborted: onchainos session expired, local clients taken offline",
       OFFLINE_REPLAY_MESSAGE_REPLAYED: "Offline replay message replayed",
@@ -19637,6 +19640,8 @@ var init_events = __esm({
       CONVERSATIONS_STREAM_FAILED: "conversations.stream failed",
       AGENT_START_FAILED: "agent.start failed",
       AGENT_STREAM_ERROR: "agent stream error",
+      AGENT_UNHANDLED_ERROR: "Agent unhandled error",
+      AGENT_STREAM_RECOVERY_TIMEOUT: "Agent stream recovery timeout",
       BOOTSTRAP_FAILED: "Bootstrap failed",
       ONCHAINOS_SESSION_EXPIRED: "Onchainos session expired",
       ONCHAINOS_CLI_ERROR: "Onchainos CLI error",
@@ -19646,6 +19651,7 @@ var init_events = __esm({
       MESSAGE_PARSE_FAILED: "Message parse failed",
       MESSAGE_HANDLER_ERROR: "Message handler error",
       INBOUND_DISPATCH_FAILED: "Inbound dispatch failed",
+      INBOUND_REPLAY_GATE_DRAIN_FAILED: "Inbound replay gate drain failed",
       // Default name stamped on events that reach Sentry without going through this
       // logger — uncaught exceptions and unhandled rejections. Without it those
       // events carry no eventName and cannot be classified.
@@ -19943,7 +19949,10 @@ var init_xmtp_test_metrics = __esm({
       "Address sync completed",
       "Agent client created",
       "Agent client removed",
-      "Agent stream error",
+      "agent stream error",
+      "Agent stream recovered",
+      "Agent stream recovery replay completed",
+      "Agent stream recovery timeout",
       "conversations.stream failed",
       "Inbound delivered to session",
       "Inbound dispatch failed",
@@ -19962,6 +19971,190 @@ var init_xmtp_test_metrics = __esm({
   }
 });
 
+// ../core/src/sentry-logger/error-diagnostics.ts
+function asErrorLike(value) {
+  return value instanceof Error ? value : void 0;
+}
+function diagnosticToken(value) {
+  if (typeof value !== "string" && typeof value !== "number") {
+    return void 0;
+  }
+  const token = String(value).trim();
+  if (!token || /^(?:null|undefined|unknown)$/i.test(token)) {
+    return void 0;
+  }
+  if (!/^[A-Za-z0-9_.:-]+$/.test(token)) {
+    return void 0;
+  }
+  return token.slice(0, MAX_DIAGNOSTIC_TOKEN_LENGTH);
+}
+function syscallToken(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const operation = diagnosticToken(value.trim().split(/\s+/, 1)[0])?.toLowerCase();
+  return operation && KNOWN_SYSCALLS.has(operation) ? operation : void 0;
+}
+function knownErrorCode(value) {
+  const code = diagnosticToken(value)?.toUpperCase();
+  return code && KNOWN_ERROR_CODES.has(code) ? code : void 0;
+}
+function readCode(error) {
+  return knownErrorCode(error?.code) ?? knownErrorCode(error?.errno);
+}
+function classifyError(error, code) {
+  const normalizedCode = code?.toUpperCase();
+  const name = error?.name.toLowerCase() ?? "";
+  const message = error?.message.toLowerCase() ?? "";
+  if (normalizedCode && RESOURCE_EXHAUSTED_CODES.has(normalizedCode)) {
+    return "resource_exhausted";
+  }
+  if (normalizedCode && CONNECTION_INTERRUPTED_CODES.has(normalizedCode)) {
+    return "connection_interrupted";
+  }
+  if (normalizedCode && NETWORK_UNAVAILABLE_CODES.has(normalizedCode)) {
+    return "network_unavailable";
+  }
+  if (normalizedCode && TIMEOUT_CODES.has(normalizedCode)) {
+    return "timeout";
+  }
+  if (normalizedCode && PERMISSION_CODES.has(normalizedCode)) {
+    return "permission_denied";
+  }
+  if (normalizedCode === "ENOENT") {
+    return "missing_dependency";
+  }
+  if (normalizedCode === "ABORT_ERR" || name === "aborterror") {
+    return "cancelled";
+  }
+  if (name === "syntaxerror" || /(?:json|response).*(?:parse|invalid)/.test(message)) {
+    return "invalid_response";
+  }
+  if (/session\s+(?:is\s+)?expired|login\s+expired/.test(message)) {
+    return "session_expired";
+  }
+  if (/timed?\s*out|timeout/.test(message)) {
+    return "timeout";
+  }
+  return "unknown";
+}
+function retryabilityFor(category) {
+  switch (category) {
+    case "connection_interrupted":
+    case "network_unavailable":
+    case "resource_exhausted":
+    case "timeout":
+      return "retryable";
+    case "invalid_response":
+    case "missing_dependency":
+    case "permission_denied":
+    case "session_expired":
+      return "non_retryable";
+    default:
+      return "unknown";
+  }
+}
+function causeChain(error) {
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = error;
+  while (current && chain.length < MAX_CAUSE_DEPTH && !seen.has(current)) {
+    chain.push(current);
+    seen.add(current);
+    current = asErrorLike(current.cause);
+  }
+  return chain;
+}
+function buildErrorDiagnostics(eventName, error, existingExtra) {
+  const errorLike = asErrorLike(error);
+  const legacy = {};
+  if (errorLike) {
+    legacy.errorName = errorLike.name;
+    legacy.errorMessageLength = String(errorLike.message.length);
+  }
+  if (!errorLike || eventName === LogEvent.AGENT_STREAM_ERROR) {
+    return legacy;
+  }
+  const chain = causeChain(errorLike);
+  const primary = chain[0];
+  const cause = chain.length > 1 ? chain[chain.length - 1] : void 0;
+  const fallbackExitCode = diagnosticToken(existingExtra.exitCode);
+  const primaryCode = readCode(primary);
+  const primaryCategory = classifyError(primary, primaryCode);
+  const primarySyscall = syscallToken(primary.syscall);
+  const causeCode = readCode(cause);
+  const causeCategory = cause ? classifyError(cause, causeCode) : void 0;
+  const causeSyscall = syscallToken(cause?.syscall);
+  const classifiedCategory = primaryCategory === "unknown" && causeCategory ? causeCategory : primaryCategory;
+  const effectiveCategory = classifiedCategory === "unknown" && fallbackExitCode && fallbackExitCode !== "0" ? "process_exit" : classifiedCategory;
+  const effectiveCode = primaryCode ?? causeCode;
+  const effectiveSyscall = primarySyscall ?? causeSyscall;
+  return {
+    ...legacy,
+    errorCategory: effectiveCategory,
+    errorRetryability: retryabilityFor(effectiveCategory),
+    errorCauseDepth: String(Math.max(0, chain.length - 1)),
+    ...effectiveCode ? { errorCode: effectiveCode } : {},
+    ...effectiveSyscall ? { errorSyscall: effectiveSyscall } : {},
+    ...cause ? {
+      causeErrorMessageLength: String(cause.message.length),
+      causeErrorCategory: causeCategory ?? "unknown",
+      ...causeCode ? { causeErrorCode: causeCode } : {},
+      ...causeSyscall ? { causeErrorSyscall: causeSyscall } : {}
+    } : {}
+  };
+}
+var MAX_DIAGNOSTIC_TOKEN_LENGTH, MAX_CAUSE_DEPTH, RESOURCE_EXHAUSTED_CODES, CONNECTION_INTERRUPTED_CODES, NETWORK_UNAVAILABLE_CODES, TIMEOUT_CODES, PERMISSION_CODES, KNOWN_ERROR_CODES, KNOWN_SYSCALLS;
+var init_error_diagnostics = __esm({
+  "../core/src/sentry-logger/error-diagnostics.ts"() {
+    "use strict";
+    init_events();
+    MAX_DIAGNOSTIC_TOKEN_LENGTH = 64;
+    MAX_CAUSE_DEPTH = 4;
+    RESOURCE_EXHAUSTED_CODES = /* @__PURE__ */ new Set(["EAGAIN", "EMFILE", "ENFILE", "ENOMEM"]);
+    CONNECTION_INTERRUPTED_CODES = /* @__PURE__ */ new Set(["ECONNRESET", "EPIPE"]);
+    NETWORK_UNAVAILABLE_CODES = /* @__PURE__ */ new Set([
+      "EAI_AGAIN",
+      "ECONNREFUSED",
+      "EHOSTUNREACH",
+      "ENETDOWN",
+      "ENETUNREACH",
+      "ENOTFOUND"
+    ]);
+    TIMEOUT_CODES = /* @__PURE__ */ new Set(["ETIMEDOUT", "ESOCKETTIMEDOUT"]);
+    PERMISSION_CODES = /* @__PURE__ */ new Set(["EACCES", "EPERM"]);
+    KNOWN_ERROR_CODES = /* @__PURE__ */ new Set([
+      ...RESOURCE_EXHAUSTED_CODES,
+      ...CONNECTION_INTERRUPTED_CODES,
+      ...NETWORK_UNAVAILABLE_CODES,
+      ...TIMEOUT_CODES,
+      ...PERMISSION_CODES,
+      "ABORT_ERR",
+      "ENOENT"
+    ]);
+    KNOWN_SYSCALLS = /* @__PURE__ */ new Set([
+      "access",
+      "bind",
+      "close",
+      "connect",
+      "getaddrinfo",
+      "kill",
+      "listen",
+      "mkdir",
+      "open",
+      "read",
+      "readdir",
+      "readlink",
+      "rename",
+      "rmdir",
+      "spawn",
+      "stat",
+      "unlink",
+      "write"
+    ]);
+  }
+});
+
 // ../core/src/sentry-logger/index.ts
 function applyFatalEventDefaults(event) {
   try {
@@ -20007,6 +20200,7 @@ var init_sentry_logger = __esm({
     init_events();
     init_log_fields();
     init_xmtp_test_metrics();
+    init_error_diagnostics();
     init_events();
     init_log_fields();
     FLOW_ID = (0, import_node_crypto3.randomUUID)();
@@ -20094,14 +20288,23 @@ var init_sentry_logger = __esm({
       "agentId",
       "agentPlatform",
       "cacheName",
+      "causeCode",
+      "causeType",
+      "causeVariant",
       "checkpoint",
       "code",
       "communicationClass",
       "component",
       "eventFamily",
       "eventName",
+      "endpoint",
+      "errorCategory",
+      "errorCode",
+      "errorRetryability",
+      "errorSyscall",
       "exitCode",
       "fromAgentId",
+      "grpcMethod",
       "jobId",
       "kind",
       "method",
@@ -20125,17 +20328,24 @@ var init_sentry_logger = __esm({
       "source",
       "stage",
       "status",
+      "streamErrorCode",
+      "streamType",
       "subcommand",
       "systemEvent",
       "taskId",
       "taskMode",
       "toAgentId",
       "transport",
+      "transportFailure",
+      "transportProtocol",
       "type",
       "workloadClass"
     ]);
     SENTRY_FINGERPRINT_KEYS = [
       "eventName",
+      "errorCategory",
+      "errorCode",
+      "errorSyscall",
       "cacheName",
       "component",
       "method",
@@ -20183,6 +20393,7 @@ var init_sentry_logger = __esm({
       LogEvent.HERMES_SESSION_ROUTE_BINDING,
       LogEvent.INBOUND_BLOCKED_ADDRESS_MISMATCH,
       LogEvent.INBOUND_BLOCKED_INELIGIBLE,
+      LogEvent.MESSAGE_ELIGIBILITY_CHECKED,
       LogEvent.INBOUND_BLOCKED_SENSITIVE,
       LogEvent.INBOUND_DROP_DM_INVALID_PAYLOAD,
       LogEvent.INBOUND_DROP_DM_NON_SYSTEM,
@@ -20198,6 +20409,9 @@ var init_sentry_logger = __esm({
       LogEvent.MESSAGE_SENT,
       LogEvent.AGENT_CLIENT_CREATED,
       LogEvent.AGENT_CLIENT_REMOVED,
+      LogEvent.AGENT_STREAM_ERROR,
+      LogEvent.AGENT_STREAM_RECOVERED,
+      LogEvent.AGENT_STREAM_RECOVERY_REPLAY_COMPLETED,
       LogEvent.ADDRESS_SYNC_COMPLETED,
       LogEvent.AGENTS_REFRESHED,
       LogEvent.AGENTS_WAKEUP_NOTIFIED,
@@ -20329,19 +20543,24 @@ var init_sentry_logger = __esm({
       }
       captureError(message, error, extraWithFlow) {
         try {
+          const errorDiagnostics = buildErrorDiagnostics(
+            message,
+            error,
+            extraWithFlow
+          );
+          const diagnosticExtra = {
+            ...extraWithFlow,
+            ...errorDiagnostics
+          };
           Sentry.withScope((scope) => {
             scope.setLevel("error");
-            _SentryLogger.applyDiagnostics(scope, message, extraWithFlow);
+            _SentryLogger.applyDiagnostics(scope, message, diagnosticExtra);
             Sentry.captureException(_SentryLogger.createSentryEvent(message), {
               // eventName is unconditional: callers that pass no Error object are
               // still classified events, and without it they reach SLS anonymous.
               extra: {
-                ...extraWithFlow,
-                eventName: message,
-                ...error ? {
-                  errorName: error.name,
-                  errorMessageLength: String(error.message.length)
-                } : {}
+                ...diagnosticExtra,
+                eventName: message
               }
             });
           });
@@ -30930,7 +31149,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.0",
+      release: "0.2.1-beta-8ae7a0d300-260807181806",
       environment,
       runtimeContainer: normalizeRuntimeContainer(process.env.OKX_A2A_RUNTIME_CONTAINER)
     };
@@ -31860,7 +32079,7 @@ async function getCurrentNodeCliVersion() {
   return await getGlobalNpmPackageVersion(UPDATE_PACKAGES.node) ?? getBundledNodeCliVersion();
 }
 function getBundledNodeCliVersion() {
-  return true ? "0.2.0" : null;
+  return true ? "0.2.1-beta-8ae7a0d300-260807181806" : null;
 }
 function readConfiguredAiProvider() {
   const explicit = process.env.OKX_A2A_AI_PROVIDER || process.env.OKX_AGENT_TASK_AI_CLI;
@@ -32070,7 +32289,7 @@ async function updateHermes(release, options) {
   }
 }
 async function installGatewayPluginForDoctor(target) {
-  const release = isPrereleaseVersion("0.2.0") ? "beta" : "latest";
+  const release = isPrereleaseVersion("0.2.1-beta-8ae7a0d300-260807181806") ? "beta" : "latest";
   const insideTargetGateway = detectGatewayInvocation() === target;
   const options = {
     restart: !insideTargetGateway,
@@ -42740,6 +42959,8 @@ __export(index_exports, {
   HEARTBEAT_GATEWAY_CHECK_TIMEOUT_MS: () => HEARTBEAT_GATEWAY_CHECK_TIMEOUT_MS,
   InboundReplayGate: () => InboundReplayGate,
   InvalidXmtpMessageStore: () => InvalidXmtpMessageStore,
+  MESSAGE_ELIGIBLE_OFFLINE_REPLAY_FLAG: () => MESSAGE_ELIGIBLE_OFFLINE_REPLAY_FLAG,
+  MESSAGE_ELIGIBLE_OFFLINE_REPLAY_HELP_TOKEN: () => MESSAGE_ELIGIBLE_OFFLINE_REPLAY_HELP_TOKEN,
   NATIVE_LAUNCHER_EXE_NAME: () => NATIVE_LAUNCHER_EXE_NAME,
   OPENCLAW_GATEWAY_ROUTE_GROUP_ID: () => OPENCLAW_GATEWAY_ROUTE_GROUP_ID,
   SYSTEM_NOTIFICATION_SESSION_KEY: () => SYSTEM_NOTIFICATION_SESSION_KEY,
@@ -42757,6 +42978,7 @@ __export(index_exports, {
   XMTP_CLIENT_RECYCLE_INTERVAL_ENV: () => XMTP_CLIENT_RECYCLE_INTERVAL_ENV,
   XmtpDm: () => Dm,
   XmtpGroup: () => Group,
+  XmtpService: () => XmtpService,
   acquireDaemonLock: () => acquireDaemonLock,
   activeDaemonPointerPath: () => activeDaemonPointerPath,
   aiRunSentryExtra: () => aiRunSentryExtra,
@@ -42777,6 +42999,7 @@ __export(index_exports, {
   buildInboundTerminalExtras: () => buildInboundTerminalExtras,
   buildLaunchdPlist: () => buildLaunchdPlist,
   buildLauncherEntryJs: () => buildLauncherEntryJs,
+  buildMessageEligibleArgs: () => buildMessageEligibleArgs,
   buildPendingConversationBackupDispatch: () => buildPendingConversationBackupDispatch,
   buildSchtasksCreateArgs: () => buildSchtasksCreateArgs,
   buildSchtasksDeleteArgs: () => buildSchtasksDeleteArgs,
@@ -42808,6 +43031,7 @@ __export(index_exports, {
   detectAiProviders: () => detectAiProviders,
   detectCurrentAiProvider: () => detectCurrentAiProvider,
   detectGatewayInvocation: () => detectGatewayInvocation,
+  detectMessageEligibleOfflineReplaySupport: () => detectMessageEligibleOfflineReplaySupport,
   detectRuntime: () => detectRuntime,
   ensureDaemonReady: () => ensureDaemonReady,
   ensureDefaultAiProvider: () => ensureDefaultAiProvider,
@@ -42821,9 +43045,11 @@ __export(index_exports, {
   findWindowsNativeOkxA2aExe: () => findWindowsNativeOkxA2aExe,
   followFile: () => followFile,
   formatDoctorReportForHumans: () => formatDoctorReportForHumans,
+  getA2ACapabilities: () => getA2ACapabilities,
   getDaemonStatus: () => getDaemonStatus,
   getHermesGatewayPluginStatus: () => getHermesGatewayPluginStatus,
   getSessionBusyTracker: () => getSessionBusyTracker,
+  handleCapabilitiesCommand: () => handleCapabilitiesCommand,
   handleDoctorCommand: () => handleDoctorCommand,
   handleXmtpDebugCommand: () => handleXmtpDebugCommand,
   handleXmtpSendCommand: () => handleXmtpSendCommand,
@@ -42837,6 +43063,7 @@ __export(index_exports, {
   isDefaultTaskHome: () => isDefaultTaskHome,
   isGatewayAvailableForHeartbeat: () => isGatewayAvailableForHeartbeat,
   isHermesGatewayPluginEnabled: () => isHermesGatewayPluginEnabled,
+  isOfflineReplayForTrigger: () => isOfflineReplayForTrigger,
   isOpenClawA2aPluginAvailable: () => isOpenClawA2aPluginAvailable,
   isOpenClawGatewayAvailable: () => isOpenClawGatewayAvailable,
   isOriginalParentProcessAlive: () => isOriginalParentProcessAlive,
@@ -42848,6 +43075,8 @@ __export(index_exports, {
   launchdPlistHasCurrentRestartPolicy: () => launchdPlistHasCurrentRestartPolicy,
   logWinCompat: () => logWinCompat,
   logXmtpMessageSent: () => logXmtpMessageSent,
+  maybeRecommendOnchainosUpgrade: () => maybeRecommendOnchainosUpgrade,
+  messageEligibleHelpAdvertisesOfflineReplay: () => messageEligibleHelpAdvertisesOfflineReplay,
   nodeVersionSatisfies: () => nodeVersionSatisfies,
   normalizeAiProvider: () => normalizeAiProvider,
   normalizeHermesOkxA2aPluginConfig: () => normalizeHermesOkxA2aPluginConfig,
@@ -42873,6 +43102,7 @@ __export(index_exports, {
   removeUserAttentionWatcher: () => removeUserAttentionWatcher,
   reportDoctorRunToSentry: () => reportDoctorRunToSentry,
   reportUserNotificationFailure: () => reportUserNotificationFailure,
+  resetMessageEligibleOfflineReplayCapabilityForTests: () => resetMessageEligibleOfflineReplayCapabilityForTests,
   resetResolvedOnchainosBinForTests: () => resetResolvedOnchainosBinForTests,
   resolveAiPermissionPreset: () => resolveAiPermissionPreset,
   resolveAiProviderCommand: () => resolveAiProviderCommand,
@@ -42884,6 +43114,7 @@ __export(index_exports, {
   resolveDoctorTarget: () => resolveDoctorTarget,
   resolveEnvelopePayload: () => resolveEnvelopePayload,
   resolveNpmCmdShimScript: () => resolveNpmCmdShimScript,
+  resolveOfflineReplayCapabilityMarker: () => resolveOfflineReplayCapabilityMarker,
   resolveOfflineReplayIntervalSec: () => resolveOfflineReplayIntervalSec,
   resolveOpenClawGatewayConfig: () => resolveOpenClawGatewayConfig,
   resolveOpenClawGatewayRoute: () => resolveOpenClawGatewayRoute,
@@ -53982,6 +54213,165 @@ var cache = new LimitedMap(1e3);
 // ../core/src/xmtp-sdk/index.ts
 init_sentry_logger();
 
+// ../core/src/xmtp-sdk/stream-recovery-telemetry.ts
+function isAgentStreamRecoveryError(error) {
+  return error instanceof Error && error.constructor.name === "AgentStreamingError" && typeof error.code === "number" && [1002, 1004, 1005].includes(error.code);
+}
+var TRANSPORT_FAILURE_PATTERNS = [
+  [/broken\s*pipe|BrokenPipe/i, "broken_pipe"],
+  [/connection\s*reset|ConnectionReset/i, "connection_reset"],
+  [/timed?\s*out|TimedOut/i, "timeout"],
+  [/unexpected\s*eof|UnexpectedEof/i, "unexpected_eof"]
+];
+var KNOWN_CAUSE_CODES = /* @__PURE__ */ new Set(["GenericFailure"]);
+var KNOWN_CAUSE_KINDS = /* @__PURE__ */ new Map([
+  ["SubscribeError::BoxError", ["SubscribeError", "BoxError"]]
+]);
+var KNOWN_GRPC_METHODS = /* @__PURE__ */ new Set([
+  "SubscribeGroupMessages",
+  "SubscribeWelcomeMessages"
+]);
+function extractStreamErrorTelemetry(error) {
+  const telemetry = {};
+  if (typeof error.code === "number" && Number.isSafeInteger(error.code)) {
+    telemetry.streamErrorCode = String(error.code);
+    const streamType = {
+      1002: "conversation",
+      1004: "message",
+      1005: "setup"
+    };
+    if (streamType[error.code]) {
+      telemetry.streamType = streamType[error.code];
+    }
+  }
+  const cause = error.cause;
+  if (!(cause instanceof Error)) {
+    return telemetry;
+  }
+  telemetry.causeMessageLength = String(cause.message.length);
+  const causeCode = cause.code;
+  if (typeof causeCode === "string" && KNOWN_CAUSE_CODES.has(causeCode)) {
+    telemetry.causeCode = causeCode;
+  }
+  const causeKind = cause.message.match(
+    /^\[([A-Za-z][A-Za-z0-9]{0,63})::([A-Za-z][A-Za-z0-9]{0,63})\]/
+  );
+  const knownCauseKind = causeKind ? KNOWN_CAUSE_KINDS.get(`${causeKind[1]}::${causeKind[2]}`) : void 0;
+  if (knownCauseKind) {
+    telemetry.causeType = knownCauseKind[0];
+    telemetry.causeVariant = knownCauseKind[1];
+  }
+  const grpcMethod = cause.message.match(
+    /endpoint\s+["']\/[A-Za-z0-9_.]+\/([A-Za-z][A-Za-z0-9_]{0,63})["']/
+  );
+  if (grpcMethod && KNOWN_GRPC_METHODS.has(grpcMethod[1])) {
+    telemetry.grpcMethod = grpcMethod[1];
+    telemetry.endpoint = grpcMethod[1];
+  }
+  if (/\bh2 protocol error\b/i.test(cause.message)) {
+    telemetry.transportProtocol = "h2";
+  }
+  const transportFailure = TRANSPORT_FAILURE_PATTERNS.find(
+    ([pattern]) => pattern.test(cause.message)
+  );
+  if (transportFailure) {
+    telemetry.transportFailure = transportFailure[1];
+    telemetry.reason = transportFailure[1];
+  }
+  return telemetry;
+}
+var StreamRecoveryTelemetry = class {
+  nextSequence = 1;
+  activeRecovery;
+  get activeSequence() {
+    return this.activeRecovery?.sequence;
+  }
+  markError(nowMs = Date.now()) {
+    if (this.activeRecovery) {
+      return {
+        recoverySequence: this.activeRecovery.sequence,
+        alreadyRecovering: true
+      };
+    }
+    const sequence = this.nextSequence++;
+    this.activeRecovery = { sequence, startedAtMs: nowMs };
+    return { recoverySequence: sequence, alreadyRecovering: false };
+  }
+  markStarted(nowMs = Date.now()) {
+    if (!this.activeRecovery) {
+      return void 0;
+    }
+    const completed = {
+      recoverySequence: this.activeRecovery.sequence,
+      recoveryDurationMs: Math.max(0, nowMs - this.activeRecovery.startedAtMs)
+    };
+    this.activeRecovery = void 0;
+    return completed;
+  }
+  cancel() {
+    this.activeRecovery = void 0;
+  }
+};
+var KeyedSingleFlight = class {
+  inFlight = /* @__PURE__ */ new Map();
+  run(key, discriminator, operation) {
+    const normalizedKey = key.toLowerCase();
+    const state = this.inFlight.get(normalizedKey);
+    if (!state) {
+      const active = createKeyedFlight(discriminator, operation);
+      this.inFlight.set(normalizedKey, { active, queued: [] });
+      this.execute(normalizedKey, active);
+      return active.promise;
+    }
+    if (state.active.discriminator === discriminator) {
+      return state.active.promise;
+    }
+    const queued = state.queued.find(
+      (flight2) => flight2.discriminator === discriminator
+    );
+    if (queued) {
+      return queued.promise;
+    }
+    const flight = createKeyedFlight(discriminator, operation);
+    state.queued.push(flight);
+    return flight.promise;
+  }
+  execute(key, flight) {
+    void Promise.resolve().then(flight.operation).then(
+      (value) => {
+        flight.resolve(value);
+        this.advance(key, flight);
+      },
+      (error) => {
+        flight.reject(error);
+        this.advance(key, flight);
+      }
+    );
+  }
+  advance(key, completed) {
+    const state = this.inFlight.get(key);
+    if (state?.active !== completed) {
+      return;
+    }
+    const next = state.queued.shift();
+    if (!next) {
+      this.inFlight.delete(key);
+      return;
+    }
+    state.active = next;
+    this.execute(key, next);
+  }
+};
+function createKeyedFlight(discriminator, operation) {
+  let resolve11;
+  let reject;
+  const promise = new Promise((resolvePromise, rejectPromise) => {
+    resolve11 = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { discriminator, operation, promise, resolve: resolve11, reject };
+}
+
 // ../core/src/xmtp-sdk/extract-job-id.ts
 function extractJobIdFromContent(content) {
   const raw = typeof content === "string" ? content : stringifyJsonForEnvelope(content);
@@ -54588,10 +54978,11 @@ var InboundReplayGate = class {
     this.inbound = inbound;
   }
   inbound;
-  buffering = true;
+  holds = 1;
   queue = [];
+  drainInFlight;
   middleware = async (ctx, next) => {
-    if (!this.buffering) {
+    if (this.holds === 0 && !this.drainInFlight) {
       await this.inbound(ctx, next);
       return;
     }
@@ -54600,19 +54991,55 @@ var InboundReplayGate = class {
   get bufferedCount() {
     return this.queue.length;
   }
+  abandonFailedAndRelease() {
+    const abandoned = this.queue.length > 0 ? 1 : 0;
+    if (abandoned > 0) {
+      this.queue.shift();
+    }
+    if (this.holds > 0) {
+      this.holds--;
+    }
+    return abandoned;
+  }
+  hold() {
+    this.holds++;
+  }
   async drain() {
+    if (this.holds > 0) {
+      this.holds--;
+    }
+    return this.drainReleased();
+  }
+  async drainReleased() {
+    if (this.holds > 0) {
+      return 0;
+    }
+    if (this.drainInFlight) {
+      return this.drainInFlight;
+    }
+    const drain = Promise.resolve().then(() => this.drainQueue());
+    this.drainInFlight = drain;
+    try {
+      return await drain;
+    } finally {
+      if (this.drainInFlight === drain) {
+        this.drainInFlight = void 0;
+      }
+    }
+  }
+  async drainQueue() {
     let drained = 0;
-    while (this.queue.length > 0) {
+    while (this.holds === 0 && this.queue.length > 0) {
       const item = this.queue.shift();
       try {
         await this.inbound(item.ctx, item.next);
       } catch (err) {
         this.queue.unshift(item);
+        this.holds = Math.max(1, this.holds);
         throw err;
       }
       drained++;
     }
-    this.buffering = false;
     return drained;
   }
 };
@@ -54628,6 +55055,9 @@ var SYSTEM_CONFIG_DEFAULTS = {
     }
   }
 };
+var STREAM_RECOVERY_ALERT_THRESHOLD_MS = 3e4;
+var REPLAY_GATE_DRAIN_MAX_ATTEMPTS = 3;
+var REPLAY_GATE_DRAIN_RETRY_DELAY_MS = 100;
 var SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?$/;
 function normalizeSemverInput(v) {
   return v.trim().replace(/^v/, "");
@@ -54808,6 +55238,9 @@ function parseGroupPayload(content) {
     return null;
   }
 }
+function isOfflineReplayForTrigger(trigger) {
+  return trigger === "startup";
+}
 var XmtpService = class _XmtpService {
   static instance = null;
   env = process.env.XMTP_ENV ?? "production";
@@ -54833,7 +55266,11 @@ var XmtpService = class _XmtpService {
   };
   dataDir = DEFAULT_DATA_DIR;
   syncByAddress = /* @__PURE__ */ new Map();
+  offlineReplaySingleFlight = new KeyedSingleFlight();
   inboundReplayGates = /* @__PURE__ */ new Map();
+  streamRecoveryCleanupByAddress = /* @__PURE__ */ new Map();
+  nextClientGeneration = 1;
+  clientGenerationByClient = /* @__PURE__ */ new WeakMap();
   agentListFingerprint;
   // Only one refreshAgents can be in flight at a time; concurrent calls
   // coalesce onto the same promise. This avoids duplicate Agent.create()
@@ -55288,6 +55725,7 @@ var XmtpService = class _XmtpService {
       const client = this.clients.get(address);
       if (client) {
         try {
+          this.cancelStreamRecoveryForAddress(address);
           this.stoppedAddresses.add(address.toLowerCase());
           client.stop();
           logWithTimestamp(
@@ -55461,7 +55899,10 @@ var XmtpService = class _XmtpService {
           logWithTimestamp(
             `[xmtp-sdk] refresh: ${address} has a prior sync timestamp, triggering offline replay`
           );
-          void this.replayOfflineMessagesForAddress(address).catch((err) => {
+          void this.replayOfflineMessagesForAddressSingleFlight(
+            address,
+            "agent_refresh"
+          ).catch((err) => {
             logWithTimestamp(`[xmtp-sdk] refresh: ${address} offline replay failed:`, err);
             logger.error(
               LogEvent.OFFLINE_REPLAY_FAILED,
@@ -55503,6 +55944,7 @@ var XmtpService = class _XmtpService {
       }
       const addressKey = address.toLowerCase();
       try {
+        this.cancelStreamRecoveryForAddress(address);
         this.stoppedAddresses.add(addressKey);
         await Promise.resolve(oldClient.stop());
         this.clients.delete(address);
@@ -55561,7 +56003,10 @@ var XmtpService = class _XmtpService {
         await this.startListeningForAddresses([address]);
         let replaySummary;
         try {
-          replaySummary = await this.replayOfflineMessagesForAddress(address);
+          replaySummary = await this.replayOfflineMessagesForAddressSingleFlight(
+            address,
+            "client_recycle"
+          );
         } finally {
           await this.drainInboundReplayGate(address);
         }
@@ -55571,6 +56016,7 @@ var XmtpService = class _XmtpService {
         recycled++;
       } catch (err) {
         failed++;
+        this.cancelStreamRecoveryForAddress(address);
         this.clients.delete(address);
         logWithTimestamp(`[xmtp-sdk] recycle: failed to recreate client: ${address}`, err);
         logger.error(
@@ -55971,16 +56417,80 @@ var XmtpService = class _XmtpService {
   async startListening() {
     await this.startListeningForAddresses([...this.clients.keys()]);
   }
-  async drainInboundReplayGate(address) {
+  async drainInboundReplayGate(address, expectedGate) {
     const gate = this.inboundReplayGates.get(address.toLowerCase());
-    if (!gate) {
+    if (!gate || expectedGate && gate !== expectedGate) {
       return 0;
     }
-    const drained = await gate.drain();
+    let attempt = 0;
+    let totalDrained = 0;
+    let releaseHold = true;
+    while (true) {
+      try {
+        const drained = releaseHold ? await gate.drain() : await gate.drainReleased();
+        totalDrained += drained;
+        logWithTimestamp(
+          `[xmtp-sdk:${address}] replay barrier released, buffered=${totalDrained} attempt=${attempt + 1}`
+        );
+        return totalDrained;
+      } catch (err) {
+        attempt++;
+        logWithTimestamp(
+          `[xmtp-sdk:${address}] replay barrier drain failed attempt=${attempt}/${REPLAY_GATE_DRAIN_MAX_ATTEMPTS}:`,
+          err
+        );
+        if (attempt < REPLAY_GATE_DRAIN_MAX_ATTEMPTS) {
+          releaseHold = true;
+          await new Promise(
+            (resolve11) => setTimeout(resolve11, REPLAY_GATE_DRAIN_RETRY_DELAY_MS * attempt)
+          );
+          continue;
+        }
+        const abandoned = gate.abandonFailedAndRelease();
+        logger.error(
+          LogEvent.INBOUND_REPLAY_GATE_DRAIN_FAILED,
+          err instanceof Error ? err : void 0,
+          {
+            walletAddress: address,
+            attemptCount: String(REPLAY_GATE_DRAIN_MAX_ATTEMPTS),
+            abandonedCount: String(abandoned),
+            stage: "inboundReplayGate/fail-open",
+            reason: "drain_retry_exhausted"
+          }
+        );
+        logWithTimestamp(
+          `[xmtp-sdk:${address}] replay barrier fail-open after ${REPLAY_GATE_DRAIN_MAX_ATTEMPTS} failed attempts, abandoned=${abandoned}`
+        );
+        attempt = 0;
+        releaseHold = false;
+      }
+    }
+  }
+  holdInboundReplayGate(address) {
+    const gate = this.inboundReplayGates.get(address.toLowerCase());
+    if (!gate) {
+      return void 0;
+    }
+    gate.hold();
     logWithTimestamp(
-      `[xmtp-sdk:${address}] startup replay barrier opened, buffered=${drained}`
+      `[xmtp-sdk:${address}] replay barrier held, buffered=${gate.bufferedCount}`
     );
-    return drained;
+    return gate;
+  }
+  cancelStreamRecoveryForAddress(address) {
+    const addressKey = address.toLowerCase();
+    const cleanup = this.streamRecoveryCleanupByAddress.get(addressKey);
+    this.streamRecoveryCleanupByAddress.delete(addressKey);
+    cleanup?.();
+  }
+  getClientGeneration(client) {
+    const existing = this.clientGenerationByClient.get(client);
+    if (existing !== void 0) {
+      return existing;
+    }
+    const generation = this.nextClientGeneration++;
+    this.clientGenerationByClient.set(client, generation);
+    return generation;
   }
   notifyAgentsWakeupAfterReplay() {
     const notifyAgentsWakeup2 = this.tools.notifyAgentsWakeup;
@@ -56014,7 +56524,7 @@ var XmtpService = class _XmtpService {
    * cannot overtake the stored backlog.
    */
   async completeStartupReplay() {
-    const summary = await this.replayOfflineMessages();
+    const summary = await this.replayOfflineMessages("startup");
     for (const address of this.clients.keys()) {
       await this.drainInboundReplayGate(address);
     }
@@ -56025,6 +56535,8 @@ var XmtpService = class _XmtpService {
     const valid = addresses.filter((addr) => this.clients.has(addr));
     await parallelMap(valid, async (address) => {
       const agent = this.clients.get(address);
+      const clientGeneration = this.getClientGeneration(agent);
+      const addressKey = address.toLowerCase();
       const tag = `[xmtp-sdk:${address}]`;
       const onchainosAgent = this.getAgentByAddress(address);
       const identity = {
@@ -56127,14 +56639,131 @@ var XmtpService = class _XmtpService {
         logWithTimestamp(`${tag} reconnecting in ${delay}ms (attempt=${attempt + 1})`);
         setTimeout(() => void startWithRetry(attempt + 1), delay);
       };
+      const streamRecovery = new StreamRecoveryTelemetry();
+      let recoveryTimeout;
+      let pendingRecoveryGate;
+      let recoveryDisposed = false;
+      this.cancelStreamRecoveryForAddress(address);
+      const cleanupStreamRecovery = () => {
+        recoveryDisposed = true;
+        streamRecovery.cancel();
+        if (recoveryTimeout) {
+          clearTimeout(recoveryTimeout);
+          recoveryTimeout = void 0;
+        }
+      };
+      this.streamRecoveryCleanupByAddress.set(
+        addressKey,
+        cleanupStreamRecovery
+      );
       agent.on("unhandledError", (err) => {
+        if (recoveryDisposed || this.clients.get(address) !== agent || this.stoppedAddresses.has(addressKey)) {
+          return;
+        }
+        if (!isAgentStreamRecoveryError(err)) {
+          logWithTimestamp(`${tag} agent unhandled error:`, err);
+          logger.error(LogEvent.AGENT_UNHANDLED_ERROR, err, agentExtras(identity));
+          return;
+        }
+        const recovery = streamRecovery.markError();
+        const errorTelemetry = extractStreamErrorTelemetry(err);
+        if (!recovery.alreadyRecovering) {
+          pendingRecoveryGate = this.holdInboundReplayGate(address);
+        }
         logWithTimestamp(`${tag} agent stream error:`, err);
-        logger.error(LogEvent.AGENT_STREAM_ERROR, err, agentExtras(identity));
+        logger.info(LogEvent.AGENT_STREAM_ERROR, {
+          ...agentExtras(identity),
+          ...errorTelemetry,
+          clientGeneration: String(clientGeneration),
+          recoverySequence: String(recovery.recoverySequence),
+          recoveryAlreadyActive: String(recovery.alreadyRecovering)
+        });
+        if (!recovery.alreadyRecovering) {
+          recoveryTimeout = setTimeout(() => {
+            if (recoveryDisposed || this.clients.get(address) !== agent || this.stoppedAddresses.has(addressKey) || streamRecovery.activeSequence !== recovery.recoverySequence) {
+              return;
+            }
+            logger.error(LogEvent.AGENT_STREAM_RECOVERY_TIMEOUT, void 0, {
+              ...agentExtras(identity),
+              ...errorTelemetry,
+              clientGeneration: String(clientGeneration),
+              recoverySequence: String(recovery.recoverySequence),
+              recoveryDurationMs: String(STREAM_RECOVERY_ALERT_THRESHOLD_MS),
+              thresholdMs: String(STREAM_RECOVERY_ALERT_THRESHOLD_MS)
+            });
+          }, STREAM_RECOVERY_ALERT_THRESHOLD_MS);
+        }
       });
       agent.on("start", () => {
+        if (recoveryDisposed || this.clients.get(address) !== agent || this.stoppedAddresses.has(addressKey)) {
+          return;
+        }
+        const recovery = streamRecovery.markStarted();
+        if (recoveryTimeout) {
+          clearTimeout(recoveryTimeout);
+          recoveryTimeout = void 0;
+        }
         logWithTimestamp(
           `${tag} agent stream started agentId=${identity.onchainosAgentId ?? "(unknown)"} inboxId=${identity.inboxId ?? "(unknown)"} role=${identity.role ?? "(unknown)"} consentStates=Allowed,Unknown lastSync=${formatLogTimestamp2(this.syncByAddress.get(address))}`
         );
+        if (recovery) {
+          const recoveryGate = pendingRecoveryGate;
+          pendingRecoveryGate = void 0;
+          logger.info(LogEvent.AGENT_STREAM_RECOVERED, {
+            ...agentExtras(identity),
+            clientGeneration: String(clientGeneration),
+            recoverySequence: String(recovery.recoverySequence),
+            recoveryDurationMs: String(recovery.recoveryDurationMs)
+          });
+          void (async () => {
+            try {
+              const summary = await this.replayOfflineMessagesForAddressSingleFlight(
+                address,
+                "stream_recovery",
+                `${clientGeneration}:${recovery.recoverySequence}`
+              );
+              if (!recoveryDisposed && this.clients.get(address) === agent) {
+                logger.info(LogEvent.AGENT_STREAM_RECOVERY_REPLAY_COMPLETED, {
+                  ...agentExtras(identity),
+                  clientGeneration: String(clientGeneration),
+                  recoverySequence: String(recovery.recoverySequence),
+                  replayed: String(summary.replayed),
+                  skipped: String(summary.skipped),
+                  conversationCount: String(summary.conversations),
+                  replayDurationMs: String(summary.durationMs)
+                });
+              }
+            } catch (err) {
+              logWithTimestamp(`${tag} recovery offline replay failed:`, err);
+              logger.error(
+                LogEvent.OFFLINE_REPLAY_FAILED,
+                err instanceof Error ? err : new Error(String(err)),
+                {
+                  ...agentExtras(identity),
+                  clientGeneration: String(clientGeneration),
+                  recoverySequence: String(recovery.recoverySequence),
+                  stage: "streamRecovery/replay"
+                }
+              );
+            } finally {
+              try {
+                await this.drainInboundReplayGate(address, recoveryGate);
+              } catch (err) {
+                logWithTimestamp(`${tag} recovery replay gate drain failed:`, err);
+                logger.error(
+                  LogEvent.OFFLINE_REPLAY_FAILED,
+                  err instanceof Error ? err : new Error(String(err)),
+                  {
+                    ...agentExtras(identity),
+                    clientGeneration: String(clientGeneration),
+                    recoverySequence: String(recovery.recoverySequence),
+                    stage: "streamRecovery/drain-gate"
+                  }
+                );
+              }
+            }
+          })();
+        }
         if (process.env.XMTP_FORCE_DEBUG === "true") {
           void logDetails(agent).catch((err) => {
             logWithTimestamp(`${tag} agent debug details failed:`, err);
@@ -56152,9 +56781,10 @@ var XmtpService = class _XmtpService {
       logWithTimestamp(`${tag} message listener started`);
     });
   }
-  async replayOfflineMessagesForAddress(address) {
+  async replayOfflineMessagesForAddress(address, trigger = "periodic_repair") {
     const addressReplayStartedAt = Date.now();
     const summary = createOfflineReplayAddressSummary(address);
+    const isOfflineReplay = isOfflineReplayForTrigger(trigger);
     const agent = this.clients.get(address);
     if (!agent) {
       summary.durationMs = Date.now() - addressReplayStartedAt;
@@ -56278,7 +56908,8 @@ var XmtpService = class _XmtpService {
             };
             const handleStartedAt = Date.now();
             const handled = await processOffline(fakeCtx, handlerDeps, {
-              skipNotify: true
+              skipNotify: true,
+              isOfflineReplay
             });
             const handleMs = Date.now() - handleStartedAt;
             summary.handleMs += handleMs;
@@ -56360,14 +56991,28 @@ var XmtpService = class _XmtpService {
     );
     return summary;
   }
-  async replayOfflineMessages() {
+  replayOfflineMessagesForAddressSingleFlight(address, trigger = "periodic_repair", recoveryIdentity) {
+    const eligibilityClass = trigger === "stream_recovery" ? `stream_recovery:${recoveryIdentity ?? "unknown"}` : isOfflineReplayForTrigger(trigger) ? "startup_offline" : "online_repair";
+    return this.offlineReplaySingleFlight.run(
+      address,
+      eligibilityClass,
+      async () => {
+        await this._backupReady;
+        return this.replayOfflineMessagesForAddress(address, trigger);
+      }
+    );
+  }
+  async replayOfflineMessages(trigger = "periodic_repair") {
     await this._backupReady;
     const replayStartedAt = Date.now();
     let totalReplayed = 0;
     let totalSkipped = 0;
     const addresses = [];
     for (const address of this.clients.keys()) {
-      const summary2 = await this.replayOfflineMessagesForAddress(address);
+      const summary2 = await this.replayOfflineMessagesForAddressSingleFlight(
+        address,
+        trigger
+      );
       addresses.push(summary2);
       const { replayed, skipped: skipped2 } = summary2;
       totalReplayed += replayed;
@@ -56705,7 +57350,7 @@ async function exec(args) {
     );
     logger.error(
       LogEvent.ONCHAINOS_CLI_ERROR,
-      new Error("onchainos command failed"),
+      err instanceof Error ? err : new Error("onchainos command failed"),
       {
         component: "onchainos_cli",
         source: "onchainos",
@@ -56808,6 +57453,107 @@ function reportSessionExpired(command) {
   );
 }
 
+// ../core/src/xmtp-sdk/onchainos/offline-replay-capability.ts
+init_log();
+var MESSAGE_ELIGIBLE_OFFLINE_REPLAY_FLAG = "--is-offline-replay";
+var MESSAGE_ELIGIBLE_OFFLINE_REPLAY_HELP_TOKEN = "is-offline-replay";
+var UPGRADE_RECOMMENDATION_PAIR_KEY = "onchainos:message-eligible-offline-replay";
+var UPGRADE_RECOMMENDATION_REASON = "OnchainOS does not support the offline-replay eligibility argument; using the legacy message-eligible contract.";
+function messageEligibleHelpAdvertisesOfflineReplay(helpText) {
+  if (typeof helpText !== "string" || helpText.length === 0) {
+    return false;
+  }
+  return helpText.toLowerCase().includes(MESSAGE_ELIGIBLE_OFFLINE_REPLAY_HELP_TOKEN);
+}
+function buildMessageEligibleArgs(params, opts) {
+  const args = [
+    "agent",
+    "message-eligible",
+    "--agent-id",
+    params.agentId,
+    "--client-agent-id",
+    params.clientAgentId,
+    "--provider-agent-id",
+    params.providerAgentId,
+    "--client-communication-address",
+    params.clientCommunicationAddress,
+    "--provider-communication-address",
+    params.providerCommunicationAddress,
+    "--job-id",
+    params.jobId,
+    "--group-id",
+    params.groupId,
+    "--direction",
+    params.direction,
+    "--provider-security-rate",
+    String(params.providerSecurityRate)
+  ];
+  if (opts.offlineReplaySupported) {
+    args.push(MESSAGE_ELIGIBLE_OFFLINE_REPLAY_FLAG, String(params.isOfflineReplay));
+  }
+  return args;
+}
+function resolveOfflineReplayCapabilityMarker(supported) {
+  return supported ? "supported" : "legacy_downgrade";
+}
+var capabilityProbe = null;
+var recommendedPairs = /* @__PURE__ */ new Set();
+function resetMessageEligibleOfflineReplayCapabilityForTests() {
+  capabilityProbe = null;
+  recommendedPairs.clear();
+}
+function maybeRecommendOnchainosUpgrade(supported) {
+  if (supported || recommendedPairs.has(UPGRADE_RECOMMENDATION_PAIR_KEY)) {
+    return;
+  }
+  const hook = XmtpService.getInstance().tools.notifyUpgradeRecommendation;
+  if (!hook) {
+    logWithTimestamp(
+      "[onchainos] tools.notifyUpgradeRecommendation not injected \u2014 deferring offline-replay upgrade notice"
+    );
+    return;
+  }
+  recommendedPairs.add(UPGRADE_RECOMMENDATION_PAIR_KEY);
+  try {
+    void Promise.resolve(
+      hook({
+        component: "onchainos",
+        capability: MESSAGE_ELIGIBLE_OFFLINE_REPLAY_HELP_TOKEN,
+        reason: UPGRADE_RECOMMENDATION_REASON
+      })
+    ).catch((err) => {
+      logWithTimestamp("[onchainos] tools.notifyUpgradeRecommendation async delivery failed:", err);
+    });
+  } catch (err) {
+    logWithTimestamp("[onchainos] tools.notifyUpgradeRecommendation threw:", err);
+  }
+}
+function detectMessageEligibleOfflineReplaySupport(execFn = exec) {
+  if (!capabilityProbe) {
+    capabilityProbe = (async () => {
+      try {
+        const { stdout, stderr } = await execFn(["agent", "message-eligible", "--help"]);
+        const supported = messageEligibleHelpAdvertisesOfflineReplay(`${stdout}
+${stderr}`);
+        logWithTimestamp(
+          `[onchainos] message-eligible offline-replay capability: ${supported ? "supported" : "legacy_downgrade"}`
+        );
+        return supported;
+      } catch (err) {
+        logWithTimestamp(
+          "[onchainos] message-eligible --help probe failed; treating offline-replay as unsupported (legacy):",
+          err
+        );
+        return false;
+      }
+    })().then((supported) => {
+      maybeRecommendOnchainosUpgrade(supported);
+      return supported;
+    });
+  }
+  return capabilityProbe;
+}
+
 // ../core/src/xmtp-sdk/onchainos/system-config.ts
 init_log();
 init_sentry_logger();
@@ -57204,35 +57950,32 @@ async function sendHeartbeat(chainIndex) {
 }
 async function checkMessageEligible(params) {
   logWithTimestamp(
-    `[onchainos] checking message-eligible: job=${params.jobId} direction=${params.direction} providerSecurityRate=${params.providerSecurityRate}`
+    `[onchainos] checking message-eligible: job=${params.jobId} direction=${params.direction} providerSecurityRate=${params.providerSecurityRate} isOfflineReplay=${params.isOfflineReplay}`
   );
+  const offlineReplaySupported = await detectMessageEligibleOfflineReplaySupport();
+  const offlineReplayCapability = resolveOfflineReplayCapabilityMarker(offlineReplaySupported);
+  const emitEligibilityChecked = (outcome, eligible) => {
+    logger.info(LogEvent.MESSAGE_ELIGIBILITY_CHECKED, {
+      component: "onchainos_cli",
+      source: "onchainos",
+      stage: "eligibility_check",
+      direction: params.direction,
+      jobId: params.jobId,
+      isOfflineReplay: String(params.isOfflineReplay),
+      offlineReplayCapability,
+      outcome,
+      eligible
+    });
+  };
   let stdout;
   let stderr;
   try {
-    ({ stdout, stderr } = await exec([
-      "agent",
-      "message-eligible",
-      "--agent-id",
-      params.agentId,
-      "--client-agent-id",
-      params.clientAgentId,
-      "--provider-agent-id",
-      params.providerAgentId,
-      "--client-communication-address",
-      params.clientCommunicationAddress,
-      "--provider-communication-address",
-      params.providerCommunicationAddress,
-      "--job-id",
-      params.jobId,
-      "--group-id",
-      params.groupId,
-      "--direction",
-      params.direction,
-      "--provider-security-rate",
-      String(params.providerSecurityRate)
-    ]));
+    ({ stdout, stderr } = await exec(
+      buildMessageEligibleArgs(params, { offlineReplaySupported })
+    ));
   } catch (err) {
     guardCatchSessionExpired2(err, "message-eligible");
+    emitEligibilityChecked("failed", "unknown");
     throw messageEligibleUnavailableError({
       reason: "message-eligible-cli-error",
       stdout: typeof err?.stdout === "string" ? err.stdout : "",
@@ -57257,6 +58000,7 @@ async function checkMessageEligible(params) {
       providerSecurityRate: String(params.providerSecurityRate)
     });
   } catch (err) {
+    emitEligibilityChecked("failed", "unknown");
     throw messageEligibleUnavailableError({
       reason: "message-eligible-json-parse-failed",
       stdout,
@@ -57286,6 +58030,7 @@ async function checkMessageEligible(params) {
         reason: "ok=false"
       })
     );
+    emitEligibilityChecked("failed", "unknown");
     throw messageEligibleUnavailableError({
       reason: "message-eligible-ok-false",
       stdout,
@@ -57295,6 +58040,7 @@ async function checkMessageEligible(params) {
   logWithTimestamp(
     `[onchainos] message-eligible result: eligible=${res.data.eligible}`
   );
+  emitEligibilityChecked("success", String(res.data.eligible));
   return res.data;
 }
 async function fetchSensitiveWords() {
@@ -58117,7 +58863,7 @@ function buildConnectParams(config, instanceId, protocolVersion) {
     client: {
       id: "gateway-client",
       displayName: "okx-a2a-node",
-      version: "0.2.0",
+      version: "0.2.1-beta-8ae7a0d300-260807181806",
       platform: "node",
       mode: "backend",
       instanceId
@@ -58128,7 +58874,7 @@ function buildConnectParams(config, instanceId, protocolVersion) {
     commands: [],
     permissions: {},
     locale: Intl.DateTimeFormat().resolvedOptions().locale || "en-US",
-    userAgent: `okx-a2a-node/${"0.2.0"}`,
+    userAgent: `okx-a2a-node/${"0.2.1-beta-8ae7a0d300-260807181806"}`,
     auth: {
       ...config.token ? { token: config.token } : {},
       ...config.password ? { password: config.password } : {}
@@ -59890,7 +60636,9 @@ async function assertOutboundEligible(params) {
     jobId,
     groupId,
     direction: isSenderClient ? "client_to_provider" : "provider_to_client",
-    providerSecurityRate
+    providerSecurityRate,
+    // Outbound messages are never startup backlog recovery.
+    isOfflineReplay: false
   });
   logWithTimestamp(
     `[okx-agent-task] outbound message-eligible: senderAgentId=${senderAgent.agentId} receiverAgentId=${receiverAgent.agentId} job=${jobId} group=${groupId} result=${JSON.stringify(result)}`
@@ -62729,6 +63477,7 @@ async function verifyInboundA2AGroupMessage(params) {
     messageId,
     consentState,
     trustedSystemSender = false,
+    isOfflineReplay = false,
     timing
   } = params;
   if (!isA2AEnvelope(payload)) {
@@ -62832,7 +63581,8 @@ async function verifyInboundA2AGroupMessage(params) {
         jobId,
         groupId,
         direction: isSenderClient ? "client_to_provider" : "provider_to_client",
-        providerSecurityRate
+        providerSecurityRate,
+        isOfflineReplay
       });
       timing?.mark("eligibilityCheck", eligibilityStartedAt);
       logWithTimestamp(
@@ -63281,6 +64031,7 @@ async function processFileMessage(ctx, deps, options = {}) {
       messageId,
       consentState: ctx.conversation instanceof Group ? ctx.conversation.consentState() : void 0,
       trustedSystemSender,
+      isOfflineReplay: options.isOfflineReplay ?? false,
       timing
     });
     if (!accepted) {
@@ -63864,6 +64615,7 @@ 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;
+var UPGRADE_RECOMMENDATION_IDEMPOTENCY_KEY = "system:onchainos-offline-replay-upgrade";
 function resolveOfflineReplayIntervalSec(systemConfig) {
   const interval = systemConfig.offlineReplayInterval;
   if (typeof interval !== "number" || !Number.isFinite(interval) || interval <= 0) {
@@ -64104,14 +64856,28 @@ async function runListenerWithLock(options, paths) {
           reason: "append_backup_failed"
         });
       });
+    },
+    notifyUpgradeRecommendation: (input) => {
+      const content = "The installed OnchainOS version does not support offline-replay preferences. Subscription messages will continue to replay normally. Upgrade OnchainOS to enable this capability.\n\nSuggested command: onchainos upgrade";
+      void notifySystemMessageToUser({
+        title: "OnchainOS upgrade recommended",
+        content,
+        store: sessionStore,
+        idempotencyKey: UPGRADE_RECOMMENDATION_IDEMPOTENCY_KEY
+      }).catch((err) => {
+        logWithTimestamp(
+          `[okx-agent-task] upgrade recommendation notify failed component=${input.component} capability=${input.capability}:`,
+          err
+        );
+      });
     }
   });
-  service.setPluginVersion("0.2.0");
+  service.setPluginVersion("0.2.1-beta-8ae7a0d300-260807181806");
   await service.init();
   const pluginVersionStatus = service.pluginVersionStatus;
   if (pluginVersionStatus.unavailable) {
     throw new Error(
-      `@okxweb3/a2a-node v${"0.2.0"} is below the required minimum v${pluginVersionStatus.minVersion}`
+      `@okxweb3/a2a-node v${"0.2.1-beta-8ae7a0d300-260807181806"} is below the required minimum v${pluginVersionStatus.minVersion}`
     );
   }
   const systemConfig = service.getSystemConfig();
@@ -64129,12 +64895,14 @@ async function runListenerWithLock(options, paths) {
       onchainosAgentId: "*",
       reason: "system-config missing sentryDsn",
       pluginId: "@okxweb3/a2a-node",
-      pluginVersion: "0.2.0"
+      pluginVersion: "0.2.1-beta-8ae7a0d300-260807181806"
     });
   }
   logWithTimestamp(
     `[okx-agent-task] listener initialized, clients=${service.getClients().size}, home=${store.homeDir}`
   );
+  void detectMessageEligibleOfflineReplaySupport().catch(() => {
+  });
   const startupReplaySummary = await service.completeStartupReplay();
   logWithTimestamp(
     `[okx-agent-task] startup replay complete clients=${startupReplaySummary.clients} replayed=${startupReplaySummary.replayed} skipped=${startupReplaySummary.skipped} duration=${startupReplaySummary.durationMs}ms`
@@ -64272,7 +65040,7 @@ async function runListenerWithLock(options, paths) {
         );
         return;
       }
-      const replayResult = await timeSettled(() => service.replayOfflineMessages());
+      const replayResult = await timeSettled(() => service.replayOfflineMessages("periodic_repair"));
       const replayMs = replayResult.durationMs;
       if (replayResult.error) {
         logger.error(LogEvent.OFFLINE_REPLAY_FAILED, replayResult.error instanceof Error ? replayResult.error : new Error(String(replayResult.error)), {
@@ -64949,6 +65717,7 @@ function summarizeXmtpTestEvents(runId, events) {
   const nodeDurations = /* @__PURE__ */ new Map();
   const replayLags = /* @__PURE__ */ new Map();
   const replayHandles = /* @__PURE__ */ new Map();
+  const streamRecoveries = /* @__PURE__ */ new Map();
   const agentMap = /* @__PURE__ */ new Map();
   for (const event of events) {
     const key = deliveryKey(event);
@@ -64981,6 +65750,18 @@ function summarizeXmtpTestEvents(runId, events) {
         event.handlerTotalMs
       );
     }
+    if (event.eventName === "Agent stream recovered") {
+      setDuration(
+        streamRecoveries,
+        [
+          eventAgentId(event),
+          stringValue(event.clientGeneration) || "unknown-client",
+          stringValue(event.recoverySequence) || "unknown-recovery",
+          event.timestamp
+        ].join(":"),
+        event.recoveryDurationMs
+      );
+    }
   }
   const agents = [...agentMap.entries()].filter(([, value]) => value.live.size > 0 || value.replay.size > 0).map(([agentId, value]) => {
     const total = (/* @__PURE__ */ new Set([...value.live, ...value.replay])).size;
@@ -65002,7 +65783,9 @@ function summarizeXmtpTestEvents(runId, events) {
     duplicateEvents: countEvent(events, "Inbound ignored: duplicate message"),
     replayMessageFailures: countEvent(events, "Offline replay message failed"),
     replayScanFailures: countEvent(events, "Offline replay failed"),
-    streamFailures: countEvent(events, "conversations.stream failed") + countEvent(events, "Agent stream error"),
+    streamFailures: countEvent(events, "conversations.stream failed") + countEvent(events, "agent stream error"),
+    streamRecoveries: countEvent(events, "Agent stream recovered"),
+    streamRecoveryTimeouts: countEvent(events, "Agent stream recovery timeout"),
     connectionFailures: countEvent(events, "XMTP connection failed"),
     successfulReplayScans: countEvent(events, "Address sync completed"),
     replayScansWithMessages: events.filter((event) => event.eventName === "Address sync completed" && numericValue(event.replayed) > 0).length,
@@ -65010,6 +65793,7 @@ function summarizeXmtpTestEvents(runId, events) {
     nodeHandlerMs: summarizeDurations([...nodeDurations.values()]),
     replayLagMs: summarizeDurations([...replayLags.values()]),
     replayHandleMs: summarizeDurations([...replayHandles.values()]),
+    streamRecoveryMs: summarizeDurations([...streamRecoveries.values()]),
     agents
   };
 }
@@ -65024,6 +65808,8 @@ Reliability
   Replay message failures      ${summary.replayMessageFailures}
   Replay scan failures         ${summary.replayScanFailures}
   Stream failures              ${summary.streamFailures}
+  Stream recoveries            ${summary.streamRecoveries}
+  Recovery timeouts (>30s)     ${summary.streamRecoveryTimeouts}
   XMTP connection failures     ${summary.connectionFailures}
   Replay scans                 ${summary.successfulReplayScans}
   Scans with replay            ${summary.replayScansWithMessages}
@@ -65032,7 +65818,8 @@ Timing
   XMTP delivery p50/p95/max    ${formatDurationSummary(summary.xmtpDeliveryMs)}
   Node handler p50/p95/max     ${formatDurationSummary(summary.nodeHandlerMs)}
   Replay lag p50/p95/max       ${formatDurationSummary(summary.replayLagMs)}
-  Replay handler p50/p95/max   ${formatDurationSummary(summary.replayHandleMs)}`);
+  Replay handler p50/p95/max   ${formatDurationSummary(summary.replayHandleMs)}
+  Stream recovery p50/p95/max  ${formatDurationSummary(summary.streamRecoveryMs)}`);
   if (summary.agents.length > 0) {
     console.log("\nAgents");
     for (const agent of summary.agents) {
@@ -65378,6 +66165,36 @@ init_ai_command();
 init_update_cli();
 init_win_spawn();
 
+// src/capabilities-cli.ts
+function getA2ACapabilities() {
+  return {
+    messageEligibleOfflineReplay: {
+      ok: true,
+      fixCommands: [],
+      message: ""
+    }
+  };
+}
+var CAPABILITIES_USAGE = "Usage: okx-a2a capabilities [--json]\n\nPrint this package's machine-readable A2A capability negotiation status.\nOnchainOS runs `okx-a2a capabilities --json` to detect supported capabilities.\n";
+function handleCapabilitiesCommand(args) {
+  if (args.some((arg) => arg === "-h" || arg === "--help")) {
+    process.stdout.write(CAPABILITIES_USAGE);
+    return;
+  }
+  const unknown = args.filter((arg) => arg !== "--json");
+  if (unknown.length > 0) {
+    throw new Error(`Unknown capabilities option: ${unknown[0]}`);
+  }
+  const capabilities = getA2ACapabilities();
+  if (args.includes("--json")) {
+    process.stdout.write(`${JSON.stringify(capabilities)}
+`);
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(capabilities, null, 2)}
+`);
+}
+
 // src/logs-export.ts
 var import_node_child_process10 = require("node:child_process");
 var import_node_fs27 = require("node:fs");
@@ -66698,7 +67515,7 @@ async function exportDiagnosticLogs(options) {
     node: process.version,
     platform: process.platform,
     arch: process.arch,
-    packageVersion: true ? "0.2.0" : "unknown",
+    packageVersion: true ? "0.2.1-beta-8ae7a0d300-260807181806" : "unknown",
     sensitiveContentIncluded: options.includeSensitiveContent,
     listenerAndLlmContentIncluded: true,
     credentialsAlwaysRedacted: true,
@@ -68423,7 +69240,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.0" : "0.0.0"),
+    cliVersion: options.cliVersion ?? (true ? "0.2.1-beta-8ae7a0d300-260807181806" : "0.0.0"),
     fixMode: options.fix === true,
     nonInteractive: options.nonInteractive === true,
     packageChanged: false,
@@ -68657,6 +69474,8 @@ init_autostart_windows();
   HEARTBEAT_GATEWAY_CHECK_TIMEOUT_MS,
   InboundReplayGate,
   InvalidXmtpMessageStore,
+  MESSAGE_ELIGIBLE_OFFLINE_REPLAY_FLAG,
+  MESSAGE_ELIGIBLE_OFFLINE_REPLAY_HELP_TOKEN,
   NATIVE_LAUNCHER_EXE_NAME,
   OPENCLAW_GATEWAY_ROUTE_GROUP_ID,
   SYSTEM_NOTIFICATION_SESSION_KEY,
@@ -68674,6 +69493,7 @@ init_autostart_windows();
   XMTP_CLIENT_RECYCLE_INTERVAL_ENV,
   XmtpDm,
   XmtpGroup,
+  XmtpService,
   acquireDaemonLock,
   activeDaemonPointerPath,
   aiRunSentryExtra,
@@ -68694,6 +69514,7 @@ init_autostart_windows();
   buildInboundTerminalExtras,
   buildLaunchdPlist,
   buildLauncherEntryJs,
+  buildMessageEligibleArgs,
   buildPendingConversationBackupDispatch,
   buildSchtasksCreateArgs,
   buildSchtasksDeleteArgs,
@@ -68725,6 +69546,7 @@ init_autostart_windows();
   detectAiProviders,
   detectCurrentAiProvider,
   detectGatewayInvocation,
+  detectMessageEligibleOfflineReplaySupport,
   detectRuntime,
   ensureDaemonReady,
   ensureDefaultAiProvider,
@@ -68738,9 +69560,11 @@ init_autostart_windows();
   findWindowsNativeOkxA2aExe,
   followFile,
   formatDoctorReportForHumans,
+  getA2ACapabilities,
   getDaemonStatus,
   getHermesGatewayPluginStatus,
   getSessionBusyTracker,
+  handleCapabilitiesCommand,
   handleDoctorCommand,
   handleXmtpDebugCommand,
   handleXmtpSendCommand,
@@ -68754,6 +69578,7 @@ init_autostart_windows();
   isDefaultTaskHome,
   isGatewayAvailableForHeartbeat,
   isHermesGatewayPluginEnabled,
+  isOfflineReplayForTrigger,
   isOpenClawA2aPluginAvailable,
   isOpenClawGatewayAvailable,
   isOriginalParentProcessAlive,
@@ -68765,6 +69590,8 @@ init_autostart_windows();
   launchdPlistHasCurrentRestartPolicy,
   logWinCompat,
   logXmtpMessageSent,
+  maybeRecommendOnchainosUpgrade,
+  messageEligibleHelpAdvertisesOfflineReplay,
   nodeVersionSatisfies,
   normalizeAiProvider,
   normalizeHermesOkxA2aPluginConfig,
@@ -68790,6 +69617,7 @@ init_autostart_windows();
   removeUserAttentionWatcher,
   reportDoctorRunToSentry,
   reportUserNotificationFailure,
+  resetMessageEligibleOfflineReplayCapabilityForTests,
   resetResolvedOnchainosBinForTests,
   resolveAiPermissionPreset,
   resolveAiProviderCommand,
@@ -68801,6 +69629,7 @@ init_autostart_windows();
   resolveDoctorTarget,
   resolveEnvelopePayload,
   resolveNpmCmdShimScript,
+  resolveOfflineReplayCapabilityMarker,
   resolveOfflineReplayIntervalSec,
   resolveOpenClawGatewayConfig,
   resolveOpenClawGatewayRoute,