@xmoxmo/bncr 0.3.4 → 0.3.6

package/src/messaging/outbound/diagnostics.ts

@@ -1,7 +1,226 @@
-import type { BncrConnection } from '../../core/types.ts';
+import type { BncrConnection, OutboxEntry } from '../../core/types.ts';
 import { OUTBOUND_TERMINAL_REASON, type OutboundScheduleSource } from './reasons.ts';
 import type { RetryRerouteDecision } from './retry-policy.ts';
 
+type OutboxIncidentSummaryInput = {
+  pending: number;
+  oldestPendingAt?: number | null;
+  lastAttemptAt?: number | null;
+  lastPushAt?: number | null;
+  lastPushError?: string | null;
+  hasGatewayContext: boolean;
+  activeOutboundConnection: boolean;
+  activeOutboundConnectionCount: number;
+  prePushGuardSkipCount?: number;
+  lastPrePushGuardSkipAt?: number | null;
+  lastPrePushGuardSkipReason?: string | null;
+  lastAckQueueLatencyMs?: number | null;
+  lastAckPushLatencyMs?: number | null;
+  lastLateAckQueueLatencyMs?: number | null;
+  lastLateAckPushLatencyMs?: number | null;
+  lastLateAckOkAt?: number | null;
+  adaptiveAckTimeoutMs?: number | null;
+  adaptiveAckTimeoutReason?: string | null;
+  nowMs?: number;
+};
+
+function finiteNumberOrNull(value: unknown): number | null {
+  if (value == null) return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+function positiveAgeMs(nowMs: number, at: unknown): number | null {
+  const n = finiteNumberOrNull(at);
+  if (n === null || n < 0) return null;
+  return Math.max(0, nowMs - n);
+}
+
+export function buildOutboxIncidentSummary(input: OutboxIncidentSummaryInput) {
+  const pending = Math.max(0, Math.floor(finiteNumberOrNull(input.pending) || 0));
+  const nowMs = finiteNumberOrNull(input.nowMs) || Date.now();
+  const lastPushError =
+    typeof input.lastPushError === 'string' && input.lastPushError ? input.lastPushError : null;
+  const lastPrePushGuardSkipReason =
+    typeof input.lastPrePushGuardSkipReason === 'string' && input.lastPrePushGuardSkipReason
+      ? input.lastPrePushGuardSkipReason
+      : null;
+  const oldestPendingAgeMs = positiveAgeMs(nowMs, input.oldestPendingAt);
+  const lastLateAckAgeMs = positiveAgeMs(nowMs, input.lastLateAckOkAt);
+  const adaptiveAckTimeoutReason =
+    typeof input.adaptiveAckTimeoutReason === 'string' && input.adaptiveAckTimeoutReason
+      ? input.adaptiveAckTimeoutReason
+      : null;
+  const hasRecentLateAck = lastLateAckAgeMs !== null && lastLateAckAgeMs <= 3_600_000;
+  const hasActiveAdaptiveAck =
+    adaptiveAckTimeoutReason !== null &&
+    ![
+      'no-timeout-evidence',
+      'no-late-ack-evidence',
+      'missing-latency',
+      'late-ack-expired',
+      'recovered',
+    ].includes(adaptiveAckTimeoutReason);
+
+  let type = 'none';
+  let severity: 'ok' | 'warning' | 'critical' = 'ok';
+  let recommendedAction = 'none';
+
+  if (pending > 0 && !input.hasGatewayContext) {
+    type = 'no-gateway-context';
+    severity = 'critical';
+    recommendedAction = 'check-channel-message-runtime-context';
+  } else if (pending > 0 && !input.activeOutboundConnection) {
+    type = 'no-active-outbound-connection';
+    severity = 'critical';
+    recommendedAction = 'reconnect-bncr-client';
+  } else if (pending > 0 && lastPrePushGuardSkipReason) {
+    type = lastPrePushGuardSkipReason;
+    severity = 'warning';
+    recommendedAction = 'inspect-pre-push-guard';
+  } else if (pending > 0 && lastPushError) {
+    type =
+      lastPushError.includes('ack') || lastPushError.includes('timeout')
+        ? 'ack-timeout'
+        : lastPushError;
+    severity = type === 'ack-timeout' ? 'critical' : 'warning';
+    recommendedAction = 'inspect-ack-and-route-state';
+  } else if (pending > 0 && oldestPendingAgeMs !== null && oldestPendingAgeMs >= 120_000) {
+    type = 'outbox-backlog';
+    severity = 'warning';
+    recommendedAction = 'inspect-outbox-drain';
+  } else if (pending > 0) {
+    type = 'pending-outbox';
+    severity = 'warning';
+    recommendedAction = 'inspect-outbox-drain';
+  } else if (hasRecentLateAck || hasActiveAdaptiveAck) {
+    type = 'slow-or-late-ack';
+    severity = 'warning';
+    recommendedAction = 'inspect-ack-latency';
+  }
+
+  return {
+    active: type !== 'none',
+    type,
+    severity,
+    recommendedAction,
+    pending,
+    oldestPendingAgeMs,
+    lastAttemptAgeMs: positiveAgeMs(nowMs, input.lastAttemptAt),
+    lastPushAgeMs: positiveAgeMs(nowMs, input.lastPushAt),
+    lastPushError,
+    hasGatewayContext: input.hasGatewayContext,
+    activeOutboundConnection: input.activeOutboundConnection,
+    activeOutboundConnectionCount: Math.max(
+      0,
+      Math.floor(finiteNumberOrNull(input.activeOutboundConnectionCount) || 0),
+    ),
+    prePushGuardSkipCount: Math.max(
+      0,
+      Math.floor(finiteNumberOrNull(input.prePushGuardSkipCount) || 0),
+    ),
+    lastPrePushGuardSkipAgeMs: positiveAgeMs(nowMs, input.lastPrePushGuardSkipAt),
+    lastPrePushGuardSkipReason,
+    ack: {
+      lastQueueLatencyMs: finiteNumberOrNull(input.lastAckQueueLatencyMs),
+      lastPushLatencyMs: finiteNumberOrNull(input.lastAckPushLatencyMs),
+      lastLateQueueLatencyMs: finiteNumberOrNull(input.lastLateAckQueueLatencyMs),
+      lastLatePushLatencyMs: finiteNumberOrNull(input.lastLateAckPushLatencyMs),
+      lastLateAckAgeMs,
+      adaptiveTimeoutMs: finiteNumberOrNull(input.adaptiveAckTimeoutMs),
+      adaptiveTimeoutReason: adaptiveAckTimeoutReason,
+    },
+  };
+}
+
+export function buildExtendedOutboundDiagnostics(input: {
+  outbox: Record<string, any>;
+  enqueueCount: number;
+  lastEnqueueAt?: number | null;
+  prePushGuardSkipCount: number;
+  lastPrePushGuardSkipAt?: number | null;
+  lastPrePushGuardSkipReason?: string | null;
+  hasGatewayContext: boolean;
+  lastGatewayContextAt?: number | null;
+  ackObservability: Record<string, any>;
+  nowMs?: number;
+}) {
+  const lastEnqueueAt = finiteNumberOrNull(input.lastEnqueueAt);
+  const lastPrePushGuardSkipAt = finiteNumberOrNull(input.lastPrePushGuardSkipAt);
+  const lastGatewayContextAt = finiteNumberOrNull(input.lastGatewayContextAt);
+  return {
+    ...input.outbox,
+    enqueueCount: input.enqueueCount,
+    lastEnqueueAt,
+    prePushGuardSkipCount: input.prePushGuardSkipCount,
+    lastPrePushGuardSkipAt,
+    lastPrePushGuardSkipReason: input.lastPrePushGuardSkipReason || null,
+    hasGatewayContext: input.hasGatewayContext,
+    lastGatewayContextAt,
+    incident: buildOutboxIncidentSummary({
+      ...input.outbox,
+      hasGatewayContext: input.hasGatewayContext,
+      prePushGuardSkipCount: input.prePushGuardSkipCount,
+      lastPrePushGuardSkipAt,
+      lastPrePushGuardSkipReason: input.lastPrePushGuardSkipReason || null,
+      lastAckQueueLatencyMs: input.ackObservability.lastAckQueueLatencyMs,
+      lastAckPushLatencyMs: input.ackObservability.lastAckPushLatencyMs,
+      lastLateAckQueueLatencyMs: input.ackObservability.lastLateAckQueueLatencyMs,
+      lastLateAckPushLatencyMs: input.ackObservability.lastLateAckPushLatencyMs,
+      lastLateAckOkAt: input.ackObservability.lastLateAckOkAt,
+      adaptiveAckTimeoutMs: input.ackObservability.currentAckTimeoutMs,
+      adaptiveAckTimeoutReason: input.ackObservability.recommendedAckTimeoutReason,
+      nowMs: input.nowMs,
+    }),
+  };
+}
+
+export function buildOutboxQueueDiagnostics(args: {
+  accountId: string;
+  outboxEntries: Iterable<OutboxEntry>;
+  pendingAllAccounts: number;
+  pushConnIds: Iterable<string>;
+}) {
+  const accountEntries = Array.from(args.outboxEntries).filter(
+    (entry) => entry.accountId === args.accountId,
+  );
+  let oldestPendingAt: number | null = null;
+  let newestPendingAt: number | null = null;
+  let lastAttemptAt: number | null = null;
+  let lastPushAt: number | null = null;
+  let lastError: string | null = null;
+
+  for (const entry of accountEntries) {
+    const createdAt = Number(entry.createdAt);
+    if (Number.isFinite(createdAt)) {
+      oldestPendingAt = oldestPendingAt === null ? createdAt : Math.min(oldestPendingAt, createdAt);
+      newestPendingAt = newestPendingAt === null ? createdAt : Math.max(newestPendingAt, createdAt);
+    }
+    const attemptAt = Number(entry.lastAttemptAt);
+    if (Number.isFinite(attemptAt) && (lastAttemptAt === null || attemptAt > lastAttemptAt)) {
+      lastAttemptAt = attemptAt;
+    }
+    const pushAt = Number(entry.lastPushAt);
+    if (Number.isFinite(pushAt) && (lastPushAt === null || pushAt > lastPushAt)) {
+      lastPushAt = pushAt;
+      lastError = entry.lastError || null;
+    }
+  }
+
+  const pushConnIds = Array.from(args.pushConnIds);
+  return {
+    pending: accountEntries.length,
+    pendingAllAccounts: args.pendingAllAccounts,
+    oldestPendingAt,
+    newestPendingAt,
+    lastAttemptAt,
+    lastPushAt,
+    lastPushError: lastError,
+    activeOutboundConnection: pushConnIds.length > 0,
+    activeOutboundConnectionCount: pushConnIds.length,
+  };
+}
+
 export function buildOutboxScheduleDebugInfo(args: {
   bridgeId: string;
   accountId?: string | null;
@@ -187,7 +406,7 @@ export function buildOutboxDrainStuckDebugInfo(args: {
     outboxSize: args.outboxSize,
     pending: args.pending,
     runningMs: args.runningMs,
-    runningSince: args.runningSince || null,
+    runningSince: args.runningSince ?? null,
     hasGatewayContext: args.hasGatewayContext,
     activeConnectionCount: args.activeConnectionCount,
     waiters: {

package/src/messaging/outbound/reply-enqueue.ts

@@ -1,7 +1,10 @@
 import type { BncrRoute, OutboxEntry } from '../../core/types.ts';
 import { buildReplyMediaFallbackDebugInfo } from './diagnostics.ts';
+import type { OutboundReplyTargetPolicy } from './reply-target-policy.ts';
 import { normalizeOutboundReplyToId } from './reply-target-policy.ts';
 
+export type { OutboundReplyTargetPolicy } from './reply-target-policy.ts';
+
 export type ReplyPayloadInput = {
   text?: string;
   mediaUrl?: string;
@@ -21,6 +24,7 @@ export type NormalizedReplyPayload = {
   audioAsVoice: boolean;
   kind?: 'tool' | 'block' | 'final';
   replyToId: string;
+  replyTargetPolicy: OutboundReplyTargetPolicy;
 };
 
 export type ReplyMediaEntriesParams = {
@@ -51,6 +55,7 @@ export type ReplyMediaFileTransferParams = {
   audioAsVoice: boolean;
   kind?: 'tool' | 'block' | 'final';
   replyToId: string;
+  replyTargetPolicy: OutboundReplyTargetPolicy;
   createdAt: number;
 };
 
@@ -70,13 +75,29 @@ export type ReplyMediaFallbackTextEntryParams = {
   mediaUrl: string;
   kind?: 'tool' | 'block' | 'final';
   replyToId: string;
+  replyTargetPolicy: OutboundReplyTargetPolicy;
   fallback: { text: string; reason: string };
 };
 
+const MEDIA_TEXT_SPLIT_THRESHOLD = 1020;
+
 export function hasReplyMediaEntries(payload: NormalizedReplyPayload) {
   return payload.mediaList.length > 0;
 }
 
+export function shouldSplitReplyMediaText(payload: NormalizedReplyPayload) {
+  if (!payload.text) return false;
+  if (payload.mediaList.length > 1) return true;
+  return payload.text.length > MEDIA_TEXT_SPLIT_THRESHOLD;
+}
+
+function withoutReplyMediaText(payload: NormalizedReplyPayload): NormalizedReplyPayload {
+  return {
+    ...payload,
+    text: '',
+  };
+}
+
 export function buildReplyTextOutboxEntry(
   params: {
     accountId: string;
@@ -85,6 +106,7 @@ export function buildReplyTextOutboxEntry(
     text: string;
     kind?: 'tool' | 'block' | 'final';
     replyToId: string;
+    replyTargetPolicy: OutboundReplyTargetPolicy;
   },
   helpers: {
     buildTextOutboxEntry: (args: {
@@ -94,6 +116,7 @@ export function buildReplyTextOutboxEntry(
       text: string;
       kind?: 'tool' | 'block' | 'final';
       replyToId?: string;
+      replyTargetPolicy?: OutboundReplyTargetPolicy;
     }) => OutboxEntry;
   },
 ): OutboxEntry {
@@ -104,6 +127,7 @@ export function buildReplyTextOutboxEntry(
     text: params.text,
     kind: params.kind,
     replyToId: params.replyToId || undefined,
+    replyTargetPolicy: params.replyTargetPolicy,
   });
 }
 
@@ -123,6 +147,7 @@ export function enqueueReplyTextEntry(
       text: string;
       kind?: 'tool' | 'block' | 'final';
       replyToId?: string;
+      replyTargetPolicy?: OutboundReplyTargetPolicy;
     }) => OutboxEntry;
   },
 ): void {
@@ -137,6 +162,7 @@ export function enqueueReplyTextEntry(
         text: params.payload.text,
         kind: params.payload.kind,
         replyToId: params.payload.replyToId,
+        replyTargetPolicy: params.payload.replyTargetPolicy,
       },
       { buildTextOutboxEntry: helpers.buildTextOutboxEntry },
     ),
@@ -159,6 +185,7 @@ export function enqueueReplyMediaFallbackTextEntry(
       text: string;
       kind?: 'tool' | 'block' | 'final';
       replyToId?: string;
+      replyTargetPolicy?: OutboundReplyTargetPolicy;
     }) => OutboxEntry;
   },
 ): void {
@@ -176,6 +203,7 @@ export function enqueueReplyMediaFallbackTextEntry(
         text: params.fallback.text,
         kind: params.kind,
         replyToId: params.replyToId,
+        replyTargetPolicy: params.replyTargetPolicy,
       },
       { buildTextOutboxEntry: helpers.buildTextOutboxEntry },
     ),
@@ -197,6 +225,7 @@ export function enqueueReplyMediaFileTransferEntry(
       audioAsVoice: boolean;
       kind?: 'tool' | 'block' | 'final';
       replyToId?: string;
+      replyTargetPolicy?: OutboundReplyTargetPolicy;
     }) => OutboxEntry;
     rememberRecentMediaSend: (args: {
       sessionKey: string;
@@ -219,6 +248,7 @@ export function enqueueReplyMediaFileTransferEntry(
       audioAsVoice: params.audioAsVoice,
       kind: params.kind,
       replyToId: params.replyToId || undefined,
+      replyTargetPolicy: params.replyTargetPolicy,
     }),
   );
   helpers.rememberRecentMediaSend({
@@ -245,6 +275,7 @@ export function enqueueSingleReplyMediaEntry(
       mediaUrl: params.mediaUrl,
       kind: params.params.payload.kind,
       replyToId: params.params.payload.replyToId,
+      replyTargetPolicy: params.params.payload.replyTargetPolicy,
       fallback: params.fallback,
     });
     return;
@@ -262,6 +293,7 @@ export function enqueueSingleReplyMediaEntry(
     audioAsVoice: params.params.payload.audioAsVoice,
     kind: params.params.payload.kind,
     replyToId: params.params.payload.replyToId,
+    replyTargetPolicy: params.params.payload.replyTargetPolicy,
     createdAt: params.currentTime,
   });
 }
@@ -293,6 +325,23 @@ export function enqueueNormalizedReplyPayload(
   });
 
   if (helpers.hasReplyMediaEntries(params.payload)) {
+    if (shouldSplitReplyMediaText(params.payload)) {
+      helpers.enqueueReplyTextEntry({
+        accountId: params.accountId,
+        sessionKey: params.sessionKey,
+        route: params.route,
+        payload: params.payload,
+      });
+      helpers.enqueueReplyMediaEntries({
+        accountId: params.accountId,
+        sessionKey: params.sessionKey,
+        route: params.route,
+        payload: withoutReplyMediaText(params.payload),
+        mediaLocalRoots: params.mediaLocalRoots,
+      });
+      return;
+    }
+
     helpers.enqueueReplyMediaEntries({
       accountId: params.accountId,
       sessionKey: params.sessionKey,
@@ -314,6 +363,7 @@ export function enqueueNormalizedReplyPayload(
 export function normalizeReplyPayload(
   payload: ReplyPayloadInput,
   helpers: { asString: (value: unknown, fallback?: string) => string },
+  options?: { replyTargetPolicy?: OutboundReplyTargetPolicy },
 ): NormalizedReplyPayload {
   const text = helpers.asString(payload?.text || '').trim();
   const mediaUrl = helpers.asString(payload?.mediaUrl || '').trim();
@@ -328,6 +378,11 @@ export function normalizeReplyPayload(
     asVoice: payload?.asVoice === true,
     audioAsVoice: payload?.audioAsVoice === true,
     kind: payload?.kind,
-    replyToId: normalizeOutboundReplyToId({ kind: payload?.kind, replyToId: payload?.replyToId }),
+    replyTargetPolicy: options?.replyTargetPolicy ?? 'agent-default',
+    replyToId: normalizeOutboundReplyToId({
+      kind: payload?.kind,
+      replyToId: payload?.replyToId,
+      replyTargetPolicy: options?.replyTargetPolicy,
+    }),
   };
 }

package/src/messaging/outbound/reply-target-policy.ts

@@ -1,13 +1,16 @@
 import { normalizeReplyToId } from './media-dedupe.ts';
 
 export type OutboundReplyKind = 'tool' | 'block' | 'final';
+export type OutboundReplyTargetPolicy = 'agent-default' | 'preserve';
 
 const STRIP_TOOL_REPLY_TO_ID = true;
 
 export function normalizeOutboundReplyToId(params: {
   kind?: OutboundReplyKind;
   replyToId?: string | null;
+  replyTargetPolicy?: OutboundReplyTargetPolicy;
 }) {
-  if (params.kind === 'tool' && STRIP_TOOL_REPLY_TO_ID) return '';
+  if (params.kind === 'tool' && STRIP_TOOL_REPLY_TO_ID && params.replyTargetPolicy !== 'preserve')
+    return '';
   return normalizeReplyToId(params.replyToId);
 }

package/src/messaging/outbound/send-params.ts

@@ -0,0 +1,56 @@
+import { normalizeAccountId } from '../../core/accounts.ts';
+import { readOpenClawBooleanParam, readOpenClawStringParam } from '../../openclaw/sdk-helpers.ts';
+
+export type NormalizedBncrSendParams = {
+  to: string;
+  accountId: string;
+  message: string;
+  caption: string;
+  mediaUrl?: string;
+  asVoice: boolean;
+  audioAsVoice: boolean;
+};
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function normalizeBncrSendParams(input: {
+  params: unknown;
+  accountId: string;
+}): NormalizedBncrSendParams {
+  const paramsObj = isPlainObject(input.params) ? input.params : {};
+  const to = readOpenClawStringParam(paramsObj, 'to', { required: true });
+  const resolvedAccountId = normalizeAccountId(
+    readOpenClawStringParam(paramsObj, 'accountId') ?? input.accountId,
+  );
+
+  const message = readOpenClawStringParam(paramsObj, 'message', { allowEmpty: true }) ?? '';
+  const caption = readOpenClawStringParam(paramsObj, 'caption', { allowEmpty: true }) ?? '';
+  const mediaUrl =
+    readOpenClawStringParam(paramsObj, 'media', { trim: false }) ??
+    readOpenClawStringParam(paramsObj, 'path', { trim: false }) ??
+    readOpenClawStringParam(paramsObj, 'filePath', { trim: false }) ??
+    readOpenClawStringParam(paramsObj, 'mediaUrl', { trim: false });
+  const asVoice = readOpenClawBooleanParam(paramsObj, 'asVoice') ?? false;
+  const audioAsVoice = readOpenClawBooleanParam(paramsObj, 'audioAsVoice') ?? false;
+
+  if (asVoice && !mediaUrl) throw new Error('send voice requires media path');
+
+  const normalizedMessage = mediaUrl ? '' : message || caption || '';
+  const normalizedCaption = mediaUrl ? caption || message || '' : '';
+
+  if (!normalizedMessage.trim() && !normalizedCaption.trim() && !mediaUrl) {
+    throw new Error('send requires message or media');
+  }
+
+  return {
+    to,
+    accountId: resolvedAccountId,
+    message: normalizedMessage,
+    caption: normalizedCaption,
+    mediaUrl: mediaUrl || undefined,
+    asVoice,
+    audioAsVoice,
+  };
+}

package/src/openclaw/runtime-surface.ts

@@ -0,0 +1,29 @@
+export type OpenClawChannelRuntimeSurfaceDiagnostics = {
+  channel: {
+    inbound: boolean;
+    media: boolean;
+    reply: boolean;
+    routing: boolean;
+    session: boolean;
+  };
+  missing: string[];
+};
+
+export function buildOpenClawChannelRuntimeSurfaceDiagnostics(
+  api: unknown,
+): OpenClawChannelRuntimeSurfaceDiagnostics {
+  const channelRuntime = (api as any)?.runtime?.channel;
+  const surfaces = {
+    inbound: Boolean(channelRuntime?.inbound),
+    media: Boolean(channelRuntime?.media),
+    reply: Boolean(channelRuntime?.reply),
+    routing: Boolean(channelRuntime?.routing),
+    session: Boolean(channelRuntime?.session),
+  };
+  return {
+    channel: surfaces,
+    missing: Object.entries(surfaces)
+      .filter(([, present]) => !present)
+      .map(([name]) => name),
+  };
+}

package/src/plugin/gateway-methods.ts

@@ -4,6 +4,8 @@ export const BNCR_GATEWAY_METHODS = [
   'bncr.activity',
   'bncr.ack',
   'bncr.diagnostics',
+  'bncr.deadLetter.inspect',
+  'bncr.deadLetter.prune',
   'bncr.file.init',
   'bncr.file.chunk',
   'bncr.file.complete',

package/src/plugin/status.ts

@@ -22,13 +22,19 @@ export function createBncrStatusSurface(getBridge: () => BncrStatusBridge) {
     },
     buildAccountSnapshot: async ({ account, runtime }: any) => {
       const runtimeBridge = getBridge();
-      const rt = runtime || runtimeBridge.getAccountRuntimeSnapshot(account?.accountId);
+      const accountId = account?.accountId || BNCR_DEFAULT_ACCOUNT_ID;
+      const snapshotAccount = {
+        accountId,
+        name: account?.name,
+        enabled: account?.enabled,
+      };
+      const rt = runtime || runtimeBridge.getAccountRuntimeSnapshot(accountId);
       return buildAccountStatusSnapshot({
-        account,
+        account: snapshotAccount,
         runtime: rt,
-        healthSummary: runtimeBridge.getStatusHeadline(account?.accountId),
+        healthSummary: runtimeBridge.getStatusHeadline(accountId),
         // default 名不可隐藏时，统一展示稳定默认值
-        displayName: resolveDefaultDisplayName(account?.name, account?.accountId),
+        displayName: resolveDefaultDisplayName(account?.name, accountId),
       });
     },
     resolveAccountState: ({ enabled, configured, account, cfg, runtime }: any) => {

package/src/runtime/outbound-ack-timeout.ts

@@ -65,6 +65,15 @@ export function computeBncrRecommendedAckTimeoutMs(args: ComputeBncrRecommendedA
   return Math.min(args.maxAckTimeoutMs, Math.max(args.minAckTimeoutMs, recommended));
 }
 
+export function resolveBncrRuntimeAckTimeoutDecision(args: ComputeBncrRecommendedAckTimeoutArgs) {
+  const timeoutMs = computeBncrRecommendedAckTimeoutMs(args);
+  const reason = computeBncrRecommendedAckTimeoutReason({
+    ...args,
+    recommendedAckTimeoutMs: timeoutMs,
+  });
+  return { timeoutMs, reason };
+}
+
 function finiteNumberOr(value: unknown, fallback: number) {
   return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
 }
@@ -94,3 +103,67 @@ export function buildBncrRuntimeAckStrategy(args: {
     recovered: ackObservability.adaptiveAckRecovered === true,
   };
 }
+
+export function buildBncrRuntimeAckObservability(args: {
+  lastAckOkAt: number | null;
+  lastAckTimeoutAt: number | null;
+  recentAckTimeoutCount: number;
+  lateAckOkCount: number;
+  lastLateAckOkAt: number | null;
+  adaptiveAckRecoveryOkCount: number;
+  lastAckQueueLatencyMs: number | null;
+  lastAckPushLatencyMs: number | null;
+  lastLateAckQueueLatencyMs: number | null;
+  lastLateAckPushLatencyMs: number | null;
+  adaptiveAckTimeoutEnabled: boolean;
+  defaultAckTimeoutMs: number;
+  currentAckTimeoutMs: number;
+  minAckTimeoutMs: number;
+  maxAckTimeoutMs: number;
+  lateAckObservationTtlMs: number;
+  recoveryOkThreshold: number;
+  nowMs: number;
+}) {
+  const lastLateAckAgeMs =
+    typeof args.lastLateAckOkAt === 'number' && args.lastLateAckOkAt > 0
+      ? Math.max(0, args.nowMs - args.lastLateAckOkAt)
+      : null;
+  const lateAckObservationExpired =
+    typeof lastLateAckAgeMs === 'number' && lastLateAckAgeMs > args.lateAckObservationTtlMs;
+  const adaptiveAckRecovered = args.adaptiveAckRecoveryOkCount >= args.recoveryOkThreshold;
+  const ackTimeoutDecision = resolveBncrRuntimeAckTimeoutDecision({
+    lateAckOkCount: args.lateAckOkCount,
+    recentAckTimeoutCount: args.recentAckTimeoutCount,
+    lastLateAckPushLatencyMs: args.lastLateAckPushLatencyMs,
+    lastLateAckOkAt: args.lastLateAckOkAt,
+    adaptiveAckRecoveryOkCount: args.adaptiveAckRecoveryOkCount,
+    nowMs: args.nowMs,
+    defaultAckTimeoutMs: args.defaultAckTimeoutMs,
+    minAckTimeoutMs: args.minAckTimeoutMs,
+    maxAckTimeoutMs: args.maxAckTimeoutMs,
+    lateAckObservationTtlMs: args.lateAckObservationTtlMs,
+    recoveryOkThreshold: args.recoveryOkThreshold,
+  });
+  return {
+    lastAckOkAt: args.lastAckOkAt,
+    lastAckTimeoutAt: args.lastAckTimeoutAt,
+    recentAckTimeoutCount: args.recentAckTimeoutCount,
+    lateAckOkCount: args.lateAckOkCount,
+    lastLateAckOkAt: args.lastLateAckOkAt,
+    lastLateAckAgeMs,
+    lateAckObservationTtlMs: args.lateAckObservationTtlMs,
+    lateAckObservationExpired,
+    adaptiveAckRecoveryOkCount: args.adaptiveAckRecoveryOkCount,
+    adaptiveAckRecoveryOkThreshold: args.recoveryOkThreshold,
+    adaptiveAckRecovered,
+    lastAckQueueLatencyMs: args.lastAckQueueLatencyMs,
+    lastAckPushLatencyMs: args.lastAckPushLatencyMs,
+    lastLateAckQueueLatencyMs: args.lastLateAckQueueLatencyMs,
+    lastLateAckPushLatencyMs: args.lastLateAckPushLatencyMs,
+    adaptiveAckTimeoutEnabled: args.adaptiveAckTimeoutEnabled,
+    defaultAckTimeoutMs: args.defaultAckTimeoutMs,
+    currentAckTimeoutMs: args.currentAckTimeoutMs,
+    recommendedAckTimeoutMs: ackTimeoutDecision.timeoutMs,
+    recommendedAckTimeoutReason: ackTimeoutDecision.reason,
+  };
+}