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

package/dist/cli.js

@@ -9433,7 +9433,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
@@ -9444,7 +9444,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 } : {}
@@ -25471,12 +25471,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",
@@ -25511,6 +25514,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",
@@ -25520,6 +25525,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.
@@ -25817,7 +25823,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",
@@ -25836,6 +25845,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 {
@@ -25881,6 +26074,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_crypto5.randomUUID)();
@@ -25968,14 +26162,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",
@@ -25999,17 +26202,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",
@@ -26057,6 +26267,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,
@@ -26072,6 +26283,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,
@@ -26203,19 +26417,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
               }
             });
           });
@@ -27414,7 +27633,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)
     };
@@ -38584,7 +38803,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,
@@ -39466,6 +39685,47 @@ var init_logs_export = __esm({
   }
 });
 
+// src/capabilities-cli.ts
+var capabilities_cli_exports = {};
+__export(capabilities_cli_exports, {
+  getA2ACapabilities: () => getA2ACapabilities,
+  handleCapabilitiesCommand: () => handleCapabilitiesCommand
+});
+function getA2ACapabilities() {
+  return {
+    messageEligibleOfflineReplay: {
+      ok: true,
+      fixCommands: [],
+      message: ""
+    }
+  };
+}
+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)}
+`);
+}
+var CAPABILITIES_USAGE;
+var init_capabilities_cli = __esm({
+  "src/capabilities-cli.ts"() {
+    "use strict";
+    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";
+  }
+});
+
 // ../core/src/xmtp-sdk/onchainos/bin.ts
 async function resolve9() {
   if (resolvedBin) {
@@ -39688,7 +39948,7 @@ async function exec(args) {
     );
     logger.error(
       LogEvent.ONCHAINOS_CLI_ERROR,
-      new Error("onchainos command failed"),
+      err2 instanceof Error ? err2 : new Error("onchainos command failed"),
       {
         component: "onchainos_cli",
         source: "onchainos",
@@ -54416,6 +54676,171 @@ var init_dist4 = __esm({
   }
 });
 
+// ../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);
+}
+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;
+}
+function createKeyedFlight(discriminator, operation) {
+  let resolve14;
+  let reject;
+  const promise = new Promise((resolvePromise, rejectPromise) => {
+    resolve14 = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { discriminator, operation, promise, resolve: resolve14, reject };
+}
+var TRANSPORT_FAILURE_PATTERNS, KNOWN_CAUSE_CODES, KNOWN_CAUSE_KINDS, KNOWN_GRPC_METHODS, StreamRecoveryTelemetry, KeyedSingleFlight;
+var init_stream_recovery_telemetry = __esm({
+  "../core/src/xmtp-sdk/stream-recovery-telemetry.ts"() {
+    "use strict";
+    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"]
+    ];
+    KNOWN_CAUSE_CODES = /* @__PURE__ */ new Set(["GenericFailure"]);
+    KNOWN_CAUSE_KINDS = /* @__PURE__ */ new Map([
+      ["SubscribeError::BoxError", ["SubscribeError", "BoxError"]]
+    ]);
+    KNOWN_GRPC_METHODS = /* @__PURE__ */ new Set([
+      "SubscribeGroupMessages",
+      "SubscribeWelcomeMessages"
+    ]);
+    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;
+      }
+    };
+    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);
+      }
+    };
+  }
+});
+
 // ../core/src/xmtp-sdk/extract-job-id.ts
 function extractJobIdFromContent(content2) {
   const raw = typeof content2 === "string" ? content2 : stringifyJsonForEnvelope(content2);
@@ -55216,6 +55641,9 @@ function parseGroupPayload(content2) {
     return null;
   }
 }
+function isOfflineReplayForTrigger(trigger) {
+  return trigger === "startup";
+}
 function createOfflineReplayAddressSummary(address) {
   return {
     address,
@@ -55233,7 +55661,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, SENSITIVE_WORDS_LAZY_RETRY_COOLDOWN_MS, SESSION_EXPIRED_RE, InboundReplayGate, SYSTEM_CONFIG_DEFAULTS, 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, 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 init_xmtp_sdk = __esm({
   "../core/src/xmtp-sdk/index.ts"() {
     "use strict";
@@ -55243,6 +55671,7 @@ var init_xmtp_sdk = __esm({
     init_dist4();
     init_dist2();
     init_sentry_logger();
+    init_stream_recovery_telemetry();
     init_extract_job_id();
     init_self_filter();
     init_logging();
@@ -55260,10 +55689,11 @@ var init_xmtp_sdk = __esm({
         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;
         }
@@ -55272,19 +55702,55 @@ var init_xmtp_sdk = __esm({
       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 (err2) {
             this.queue.unshift(item);
+            this.holds = Math.max(1, this.holds);
             throw err2;
           }
           drained++;
         }
-        this.buffering = false;
         return drained;
       }
     };
@@ -55300,6 +55766,9 @@ var init_xmtp_sdk = __esm({
         }
       }
     };
+    STREAM_RECOVERY_ALERT_THRESHOLD_MS = 3e4;
+    REPLAY_GATE_DRAIN_MAX_ATTEMPTS = 3;
+    REPLAY_GATE_DRAIN_RETRY_DELAY_MS = 100;
     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-]+)*)?$/;
     isRecord5 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
     isPositiveNumber = (value) => typeof value === "number" && Number.isFinite(value) && value > 0;
@@ -55344,7 +55813,11 @@ var init_xmtp_sdk = __esm({
       };
       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()
@@ -55799,6 +56272,7 @@ var init_xmtp_sdk = __esm({
           const client = this.clients.get(address);
           if (client) {
             try {
+              this.cancelStreamRecoveryForAddress(address);
               this.stoppedAddresses.add(address.toLowerCase());
               client.stop();
               logWithTimestamp(
@@ -55972,7 +56446,10 @@ var init_xmtp_sdk = __esm({
               logWithTimestamp(
                 `[xmtp-sdk] refresh: ${address} has a prior sync timestamp, triggering offline replay`
               );
-              void this.replayOfflineMessagesForAddress(address).catch((err2) => {
+              void this.replayOfflineMessagesForAddressSingleFlight(
+                address,
+                "agent_refresh"
+              ).catch((err2) => {
                 logWithTimestamp(`[xmtp-sdk] refresh: ${address} offline replay failed:`, err2);
                 logger.error(
                   LogEvent.OFFLINE_REPLAY_FAILED,
@@ -56014,6 +56491,7 @@ var init_xmtp_sdk = __esm({
           }
           const addressKey = address.toLowerCase();
           try {
+            this.cancelStreamRecoveryForAddress(address);
             this.stoppedAddresses.add(addressKey);
             await Promise.resolve(oldClient.stop());
             this.clients.delete(address);
@@ -56072,7 +56550,10 @@ var init_xmtp_sdk = __esm({
             await this.startListeningForAddresses([address]);
             let replaySummary;
             try {
-              replaySummary = await this.replayOfflineMessagesForAddress(address);
+              replaySummary = await this.replayOfflineMessagesForAddressSingleFlight(
+                address,
+                "client_recycle"
+              );
             } finally {
               await this.drainInboundReplayGate(address);
             }
@@ -56082,6 +56563,7 @@ var init_xmtp_sdk = __esm({
             recycled++;
           } catch (err2) {
             failed++;
+            this.cancelStreamRecoveryForAddress(address);
             this.clients.delete(address);
             logWithTimestamp(`[xmtp-sdk] recycle: failed to recreate client: ${address}`, err2);
             logger.error(
@@ -56482,16 +56964,80 @@ var init_xmtp_sdk = __esm({
       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 (err2) {
+            attempt++;
+            logWithTimestamp(
+              `[xmtp-sdk:${address}] replay barrier drain failed attempt=${attempt}/${REPLAY_GATE_DRAIN_MAX_ATTEMPTS}:`,
+              err2
+            );
+            if (attempt < REPLAY_GATE_DRAIN_MAX_ATTEMPTS) {
+              releaseHold = true;
+              await new Promise(
+                (resolve14) => setTimeout(resolve14, REPLAY_GATE_DRAIN_RETRY_DELAY_MS * attempt)
+              );
+              continue;
+            }
+            const abandoned = gate.abandonFailedAndRelease();
+            logger.error(
+              LogEvent.INBOUND_REPLAY_GATE_DRAIN_FAILED,
+              err2 instanceof Error ? err2 : 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;
@@ -56525,7 +57071,7 @@ var init_xmtp_sdk = __esm({
        * 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);
         }
@@ -56536,6 +57082,8 @@ var init_xmtp_sdk = __esm({
         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 = {
@@ -56638,14 +57186,131 @@ var init_xmtp_sdk = __esm({
             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", (err2) => {
+            if (recoveryDisposed || this.clients.get(address) !== agent || this.stoppedAddresses.has(addressKey)) {
+              return;
+            }
+            if (!isAgentStreamRecoveryError(err2)) {
+              logWithTimestamp(`${tag} agent unhandled error:`, err2);
+              logger.error(LogEvent.AGENT_UNHANDLED_ERROR, err2, agentExtras(identity));
+              return;
+            }
+            const recovery = streamRecovery.markError();
+            const errorTelemetry = extractStreamErrorTelemetry(err2);
+            if (!recovery.alreadyRecovering) {
+              pendingRecoveryGate = this.holdInboundReplayGate(address);
+            }
             logWithTimestamp(`${tag} agent stream error:`, err2);
-            logger.error(LogEvent.AGENT_STREAM_ERROR, err2, 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 (err2) {
+                  logWithTimestamp(`${tag} recovery offline replay failed:`, err2);
+                  logger.error(
+                    LogEvent.OFFLINE_REPLAY_FAILED,
+                    err2 instanceof Error ? err2 : new Error(String(err2)),
+                    {
+                      ...agentExtras(identity),
+                      clientGeneration: String(clientGeneration),
+                      recoverySequence: String(recovery.recoverySequence),
+                      stage: "streamRecovery/replay"
+                    }
+                  );
+                } finally {
+                  try {
+                    await this.drainInboundReplayGate(address, recoveryGate);
+                  } catch (err2) {
+                    logWithTimestamp(`${tag} recovery replay gate drain failed:`, err2);
+                    logger.error(
+                      LogEvent.OFFLINE_REPLAY_FAILED,
+                      err2 instanceof Error ? err2 : new Error(String(err2)),
+                      {
+                        ...agentExtras(identity),
+                        clientGeneration: String(clientGeneration),
+                        recoverySequence: String(recovery.recoverySequence),
+                        stage: "streamRecovery/drain-gate"
+                      }
+                    );
+                  }
+                }
+              })();
+            }
             if (process.env.XMTP_FORCE_DEBUG === "true") {
               void logDetails(agent).catch((err2) => {
                 logWithTimestamp(`${tag} agent debug details failed:`, err2);
@@ -56663,9 +57328,10 @@ var init_xmtp_sdk = __esm({
           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;
@@ -56789,7 +57455,8 @@ var init_xmtp_sdk = __esm({
                 };
                 const handleStartedAt = Date.now();
                 const handled = await processOffline(fakeCtx, handlerDeps, {
-                  skipNotify: true
+                  skipNotify: true,
+                  isOfflineReplay
                 });
                 const handleMs = Date.now() - handleStartedAt;
                 summary.handleMs += handleMs;
@@ -56871,14 +57538,28 @@ var init_xmtp_sdk = __esm({
         );
         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;
@@ -56987,6 +57668,111 @@ var init_session_expired = __esm({
   }
 });
 
+// ../core/src/xmtp-sdk/onchainos/offline-replay-capability.ts
+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";
+}
+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((err2) => {
+      logWithTimestamp("[onchainos] tools.notifyUpgradeRecommendation async delivery failed:", err2);
+    });
+  } catch (err2) {
+    logWithTimestamp("[onchainos] tools.notifyUpgradeRecommendation threw:", err2);
+  }
+}
+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 (err2) {
+        logWithTimestamp(
+          "[onchainos] message-eligible --help probe failed; treating offline-replay as unsupported (legacy):",
+          err2
+        );
+        return false;
+      }
+    })().then((supported) => {
+      maybeRecommendOnchainosUpgrade(supported);
+      return supported;
+    });
+  }
+  return capabilityProbe;
+}
+var MESSAGE_ELIGIBLE_OFFLINE_REPLAY_FLAG, MESSAGE_ELIGIBLE_OFFLINE_REPLAY_HELP_TOKEN, UPGRADE_RECOMMENDATION_PAIR_KEY, UPGRADE_RECOMMENDATION_REASON, capabilityProbe, recommendedPairs;
+var init_offline_replay_capability = __esm({
+  "../core/src/xmtp-sdk/onchainos/offline-replay-capability.ts"() {
+    "use strict";
+    init_log();
+    init_bin();
+    init_xmtp_sdk();
+    MESSAGE_ELIGIBLE_OFFLINE_REPLAY_FLAG = "--is-offline-replay";
+    MESSAGE_ELIGIBLE_OFFLINE_REPLAY_HELP_TOKEN = "is-offline-replay";
+    UPGRADE_RECOMMENDATION_PAIR_KEY = "onchainos:message-eligible-offline-replay";
+    UPGRADE_RECOMMENDATION_REASON = "OnchainOS does not support the offline-replay eligibility argument; using the legacy message-eligible contract.";
+    capabilityProbe = null;
+    recommendedPairs = /* @__PURE__ */ new Set();
+  }
+});
+
 // ../core/src/xmtp-sdk/onchainos/system-config.ts
 function notifyExpired(command, options) {
   if (options?.notifySessionExpired) {
@@ -57385,35 +58171,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 (err2) {
     guardCatchSessionExpired2(err2, "message-eligible");
+    emitEligibilityChecked("failed", "unknown");
     throw messageEligibleUnavailableError({
       reason: "message-eligible-cli-error",
       stdout: typeof err2?.stdout === "string" ? err2.stdout : "",
@@ -57438,6 +58221,7 @@ async function checkMessageEligible(params) {
       providerSecurityRate: String(params.providerSecurityRate)
     });
   } catch (err2) {
+    emitEligibilityChecked("failed", "unknown");
     throw messageEligibleUnavailableError({
       reason: "message-eligible-json-parse-failed",
       stdout,
@@ -57467,6 +58251,7 @@ async function checkMessageEligible(params) {
         reason: "ok=false"
       })
     );
+    emitEligibilityChecked("failed", "unknown");
     throw messageEligibleUnavailableError({
       reason: "message-eligible-ok-false",
       stdout,
@@ -57476,6 +58261,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() {
@@ -57529,6 +58315,7 @@ var init_onchainos = __esm({
     init_xmtp_sdk();
     init_cli_response();
     init_session_expired();
+    init_offline_replay_capability();
     init_cli_response();
     init_session_expired();
     init_system_config();
@@ -58394,7 +59181,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)}`
@@ -63996,6 +64785,7 @@ async function verifyInboundA2AGroupMessage(params) {
     messageId,
     consentState,
     trustedSystemSender = false,
+    isOfflineReplay = false,
     timing
   } = params;
   if (!isA2AEnvelope(payload)) {
@@ -64099,7 +64889,8 @@ async function verifyInboundA2AGroupMessage(params) {
         jobId,
         groupId,
         direction: isSenderClient ? "client_to_provider" : "provider_to_client",
-        providerSecurityRate
+        providerSecurityRate,
+        isOfflineReplay
       });
       timing?.mark("eligibilityCheck", eligibilityStartedAt);
       logWithTimestamp(
@@ -64548,6 +65339,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) {
@@ -65272,14 +66064,28 @@ async function runListenerWithLock(options, paths) {
           reason: "append_backup_failed"
         });
       });
+    },
+    notifyUpgradeRecommendation: (input) => {
+      const content2 = "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: content2,
+        store: sessionStore,
+        idempotencyKey: UPGRADE_RECOMMENDATION_IDEMPOTENCY_KEY
+      }).catch((err2) => {
+        logWithTimestamp(
+          `[okx-agent-task] upgrade recommendation notify failed component=${input.component} capability=${input.capability}:`,
+          err2
+        );
+      });
     }
   });
-  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();
@@ -65297,12 +66103,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`
@@ -65440,7 +66248,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)), {
@@ -65671,7 +66479,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, 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, UPGRADE_RECOMMENDATION_IDEMPOTENCY_KEY, SHUTDOWN_FORCE_RESOLVE_MS;
 var init_listener = __esm({
   "src/listener.ts"() {
     "use strict";
@@ -65682,6 +66490,7 @@ var init_listener = __esm({
     import_node_path30 = require("node:path");
     init_onchainos();
     init_system_config();
+    init_offline_replay_capability();
     init_signer();
     init_xmtp_sdk();
     init_file_store();
@@ -65690,6 +66499,7 @@ var init_listener = __esm({
     init_command_store();
     init_ai_dispatch_queue();
     init_message_handler();
+    init_agent_message_notice();
     init_paths();
     init_user_attention_ipc();
     init_user_attention_watchers();
@@ -65702,6 +66512,7 @@ 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;
+    UPGRADE_RECOMMENDATION_IDEMPOTENCY_KEY = "system:onchainos-offline-replay-upgrade";
     SHUTDOWN_FORCE_RESOLVE_MS = 5e3;
   }
 });
@@ -65960,6 +66771,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);
@@ -65992,6 +66804,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;
@@ -66013,7 +66837,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,
@@ -66021,6 +66847,7 @@ function summarizeXmtpTestEvents(runId, events) {
     nodeHandlerMs: summarizeDurations([...nodeDurations.values()]),
     replayLagMs: summarizeDurations([...replayLags.values()]),
     replayHandleMs: summarizeDurations([...replayHandles.values()]),
+    streamRecoveryMs: summarizeDurations([...streamRecoveries.values()]),
     agents
   };
 }
@@ -66035,6 +66862,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}
@@ -66043,7 +66872,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) {
@@ -113372,7 +114202,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;
@@ -113582,7 +114412,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,
@@ -114570,7 +115400,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,
@@ -115538,7 +116368,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.0"}
+  console.log(`okx-a2a ${"0.2.1-beta-8ae7a0d300-260807181806"}
 
 Usage:
   okx-a2a <command> [options]
@@ -115568,6 +116398,7 @@ Commands:
               Alias for runtime switch-current
   job-provider Manage job-to-provider bindings
   xmtp-send    Queue an XMTP message through the running daemon
+  capabilities Print machine-readable A2A capability negotiation status (used by OnchainOS)
 
 Global options:
   -h, --help     Show help
@@ -115577,7 +116408,7 @@ Run \`okx-a2a <command> -h\` for command-specific help.
 `);
 }
 function printVersion() {
-  console.log("0.2.0");
+  console.log("0.2.1-beta-8ae7a0d300-260807181806");
 }
 function printDaemonUsage() {
   console.log(`Usage: okx-a2a daemon <start|restart|stop|status|autostart> [options]
@@ -116924,6 +117755,11 @@ async function main() {
   if (hasHelpFlag5(args) && !shouldDeferHelpToNestedHandler(command, args) && printCommandUsage(command)) {
     return;
   }
+  if (command === "capabilities") {
+    const { handleCapabilitiesCommand: handleCapabilitiesCommand2 } = await Promise.resolve().then(() => (init_capabilities_cli(), capabilities_cli_exports));
+    handleCapabilitiesCommand2(process.argv.slice(3));
+    return;
+  }
   if (command === "daemon") {
     if (hasHelpFlag5(args)) {
       printDaemonUsage();
@@ -116983,7 +117819,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.0",
+      packageVersion: "0.2.1-beta-8ae7a0d300-260807181806",
       agentSdkVersion: "2.3.0",
       nodeSdkVersion: "6.1.0",
       nodeBindingsVersion: "1.11.0"