@xmoxmo/bncr 0.3.6 → 0.3.7

package/src/plugin/ack-outbox-runtime-group.ts

@@ -0,0 +1,264 @@
+import type { GatewayRequestHandlerOptions } from 'openclaw/plugin-sdk/core';
+import type { OutboxEntry } from '../core/types.ts';
+import { createBncrMessageAckRuntime } from './message-ack-runtime.ts';
+import { createBncrOutboxAckLogs } from './outbox-ack-logs.ts';
+import {
+  type BncrOutboxAckOkTelemetryPatch,
+  createBncrOutboxAckOutcome,
+} from './outbox-ack-outcome.ts';
+import { createBncrOutboxDrainAck } from './outbox-drain-ack.ts';
+import { createBncrOutboxDrainRuntime } from './outbox-drain-runtime.ts';
+import { createBncrOutboxDrainSchedule } from './outbox-drain-schedule.ts';
+
+export function createBncrAckOutboxRuntimeGroup(runtime: {
+  bridgeId: string;
+  pushEvent: string;
+  now: () => number;
+  asString: (value: unknown, fallback?: string) => string;
+  backoffMs: (retryCount: number) => number;
+  isPlainObject: (value: unknown) => value is Record<string, unknown>;
+  clampFiniteNumber: (value: unknown, fallback: number, min?: number, max?: number) => number;
+  normalizeAccountId: (accountId: string) => string;
+  formatDisplayScope: (route: OutboxEntry['route']) => string;
+  isFileTransferEntry: (entry: OutboxEntry) => boolean;
+  recommendedAckTimeoutMaxMs: number;
+  adaptiveAckTimeoutEnabled: boolean;
+  defaultAckTimeoutMs: number;
+  stopped: () => boolean;
+  outbox: Map<string, OutboxEntry>;
+  deadLetter: () => OutboxEntry[];
+  connectionsValues: () => IterableIterator<{
+    accountId: string;
+    connId: string;
+    clientId?: string;
+    connectedAt: number;
+    lastSeenAt: number;
+    inboundOnly?: boolean;
+    outboundReady?: boolean;
+    preferredForOutbound?: boolean;
+    outboundReadyUntil?: number;
+    preferredForOutboundUntil?: number;
+    lastAckOkAt?: number;
+    lastPushTimeoutAt?: number;
+    pushFailureScore?: number;
+  }>;
+  gatewayContextAvailable: () => boolean;
+  messageAckWaiters: Map<
+    string,
+    {
+      promise: Promise<'acked' | 'timeout'>;
+      resolve: (result: 'acked' | 'timeout') => void;
+      timer: NodeJS.Timeout;
+    }
+  >;
+  fileAckWaiterCount: () => number;
+  activeConnectionCount: (accountId: string) => number;
+  getAccountPendingOutboxEntries: (accountId: string) => OutboxEntry[];
+  pushDrainRunningAccounts: Set<string>;
+  pushDrainRunningSinceByAccount: Map<string, number>;
+  pushDrainStuckWarnedAtByAccount: Map<string, number>;
+  isOnline: (accountId: string) => boolean;
+  hasRecentInboundReachability: (accountId: string) => boolean;
+  isOutboundAckRequired: (accountId?: string) => boolean;
+  resolveMessageAckTimeoutMs: (accountId: string) => number;
+  waitForMessageAck: (messageId: string, waitMs: number) => Promise<'acked' | 'timeout'>;
+  resolvePushConnIds: (accountId: string) => Iterable<string>;
+  sleepMs: (ms: number) => Promise<void>;
+  schedulePushDrain: (delayMs: number) => void;
+  tryPushEntry: (entry: OutboxEntry) => Promise<boolean>;
+  handleFileTransferPushFailure: (args: { entry: OutboxEntry; error: unknown }) => void;
+  handleTextPushFailure: (args: { entry: OutboxEntry; error: unknown }) => void;
+  isPrePushGuardDeferral: (entry: OutboxEntry) => boolean;
+  scheduleSave: () => void;
+  logInfo: (scope: string | undefined, message: string, options?: { debugOnly?: boolean }) => void;
+  logWarn: (scope: string | undefined, message: string, options?: { debugOnly?: boolean }) => void;
+  logError: (scope: string, message: string) => void;
+  observeLease: (
+    kind:
+      | 'connect'
+      | 'inbound'
+      | 'activity'
+      | 'ack'
+      | 'file.init'
+      | 'file.chunk'
+      | 'file.complete'
+      | 'file.abort',
+    payload: Record<string, unknown>,
+  ) => { stale: boolean };
+  rememberGatewayContext: (context: GatewayRequestHandlerOptions['context']) => void;
+  markSeen: (accountId: string, connId: string, clientId?: string) => void;
+  markOutboundCapability: (args: {
+    accountId: string;
+    connId: string;
+    clientId?: string;
+    outboundReady: boolean;
+    preferredForOutbound: boolean;
+  }) => void;
+  recordAckOkTelemetry: (args: {
+    accountId: string;
+    entry: OutboxEntry;
+    telemetryPatch: BncrOutboxAckOkTelemetryPatch;
+  }) => void;
+  deleteOutboxEntry: (messageId: string) => void;
+  setOutboxEntry: (messageId: string, entry: OutboxEntry) => void;
+  resolveMessageAck: (messageId: string, result: 'acked' | 'timeout') => boolean;
+  moveToDeadLetter: (entry: OutboxEntry, reason: string) => void;
+  recordAckTimeoutTelemetry: (accountId: string) => void;
+  degradeOutboundCapability: (args: {
+    accountId: string;
+    connId?: string;
+    clientId?: string;
+    reason: string;
+  }) => void;
+  flushPushQueueBestEffort: (args?: {
+    accountId?: string;
+    trigger?: string;
+    reason?: string;
+  }) => void;
+  flushTriggerTimer: string;
+  flushReasonScheduledDrain: string;
+  outboundFlushTriggerAckOk: string;
+  outboundFlushReasonMessageAcked: string;
+  pushDrainExceptionRetryLimit: number;
+  pushDrainExceptionRetryDelayMs: number;
+  pushDrainStuckWarnMs: number;
+  pushDrainIntervalMs: number;
+  pushDrainAccountTimeBudgetMs: number;
+  pushDrainAccountBudget: number;
+  pushAckTimeoutMs: number;
+  maxRetry: number;
+  prePushGuardRetryDelayMs: number;
+}) {
+  const outboxAckLogs = createBncrOutboxAckLogs({
+    bridgeId: runtime.bridgeId,
+    pushEvent: runtime.pushEvent,
+    now: runtime.now,
+    outboxSize: () => runtime.outbox.size,
+    adaptiveAckTimeoutEnabled: runtime.adaptiveAckTimeoutEnabled,
+    formatDisplayScope: runtime.formatDisplayScope,
+    isFileTransferEntry: runtime.isFileTransferEntry,
+    logInfo: runtime.logInfo,
+  });
+
+  const outboxAckOutcome = createBncrOutboxAckOutcome({
+    now: runtime.now,
+    defaultAckTimeoutMs: runtime.defaultAckTimeoutMs,
+    markOutboundCapability: runtime.markOutboundCapability,
+    recordAckOkTelemetry: runtime.recordAckOkTelemetry,
+    deleteOutboxEntry: runtime.deleteOutboxEntry,
+    setOutboxEntry: runtime.setOutboxEntry,
+    scheduleSave: runtime.scheduleSave,
+    resolveMessageAck: (messageId, result) => {
+      runtime.resolveMessageAck(messageId, result);
+    },
+    moveToDeadLetter: runtime.moveToDeadLetter,
+    logOutboxAckSummary: outboxAckLogs.logOutboxAckSummary,
+  });
+
+  const messageAckRuntime = createBncrMessageAckRuntime({
+    asString: runtime.asString,
+    now: runtime.now,
+    clampFiniteNumber: (value, fallback, min, max) =>
+      runtime.clampFiniteNumber(value, fallback, min ?? fallback, max ?? fallback),
+    normalizeAccountId: runtime.normalizeAccountId,
+    recommendedAckTimeoutMaxMs: runtime.recommendedAckTimeoutMaxMs,
+    messageAckWaiters: runtime.messageAckWaiters,
+    stopped: runtime.stopped,
+    outbox: runtime.outbox,
+    observeLease: runtime.observeLease,
+    rememberGatewayContext: runtime.rememberGatewayContext,
+    markSeen: runtime.markSeen,
+    logInfo: runtime.logInfo,
+    logWarn: runtime.logWarn,
+    handleAckOk: outboxAckOutcome.handleAckOk,
+    handleAckFatal: outboxAckOutcome.handleAckFatal,
+    handleAckRetry: outboxAckOutcome.handleAckRetry,
+    flushPushQueueBestEffort: runtime.flushPushQueueBestEffort,
+    outboundFlushTriggerAckOk: runtime.outboundFlushTriggerAckOk,
+    outboundFlushReasonMessageAcked: runtime.outboundFlushReasonMessageAcked,
+  });
+
+  const outboxDrainAck = createBncrOutboxDrainAck({
+    bridgeId: runtime.bridgeId,
+    pushEvent: runtime.pushEvent,
+    now: runtime.now,
+    defaultAckTimeoutMs: runtime.defaultAckTimeoutMs,
+    adaptiveAckTimeoutEnabled: runtime.adaptiveAckTimeoutEnabled,
+    outboxSize: () => runtime.outbox.size,
+    formatDisplayScope: runtime.formatDisplayScope,
+    isFileTransferEntry: runtime.isFileTransferEntry,
+    setOutboxEntry: runtime.setOutboxEntry,
+    scheduleSave: runtime.scheduleSave,
+    moveToDeadLetter: runtime.moveToDeadLetter,
+    recordAckTimeoutTelemetry: runtime.recordAckTimeoutTelemetry,
+    logInfo: runtime.logInfo,
+    logOutboxAckReroute: outboxAckLogs.logOutboxAckReroute,
+  });
+
+  const outboxDrainSchedule = createBncrOutboxDrainSchedule({
+    bridgeId: runtime.bridgeId,
+    logInfo: runtime.logInfo,
+  });
+
+  const outboxDrainRuntime = createBncrOutboxDrainRuntime({
+    bridgeId: runtime.bridgeId,
+    now: runtime.now,
+    asString: runtime.asString,
+    backoffMs: runtime.backoffMs,
+    isPlainObject: runtime.isPlainObject,
+    normalizeAccountId: runtime.normalizeAccountId,
+    stopped: runtime.stopped,
+    outbox: runtime.outbox,
+    deadLetter: runtime.deadLetter,
+    connectionsValues: runtime.connectionsValues,
+    gatewayContextAvailable: runtime.gatewayContextAvailable,
+    messageAckWaiterCount: () => runtime.messageAckWaiters.size,
+    fileAckWaiterCount: runtime.fileAckWaiterCount,
+    activeConnectionCount: runtime.activeConnectionCount,
+    getAccountPendingOutboxEntries: runtime.getAccountPendingOutboxEntries,
+    pushDrainRunningAccounts: runtime.pushDrainRunningAccounts,
+    pushDrainRunningSinceByAccount: runtime.pushDrainRunningSinceByAccount,
+    pushDrainStuckWarnedAtByAccount: runtime.pushDrainStuckWarnedAtByAccount,
+    isOnline: runtime.isOnline,
+    hasRecentInboundReachability: runtime.hasRecentInboundReachability,
+    isOutboundAckRequired: runtime.isOutboundAckRequired,
+    resolveMessageAckTimeoutMs: runtime.resolveMessageAckTimeoutMs,
+    waitForMessageAck: runtime.waitForMessageAck,
+    logOutboxAckWait: outboxAckLogs.logOutboxAckWait,
+    degradeOutboundCapability: runtime.degradeOutboundCapability,
+    resolvePushConnIds: runtime.resolvePushConnIds,
+    sleepMs: runtime.sleepMs,
+    schedulePushDrain: runtime.schedulePushDrain,
+    outboxDrainSchedule,
+    outboxDrainAck,
+    tryPushEntry: runtime.tryPushEntry,
+    handleFileTransferPushFailure: runtime.handleFileTransferPushFailure,
+    handleTextPushFailure: runtime.handleTextPushFailure,
+    isPrePushGuardDeferral: runtime.isPrePushGuardDeferral,
+    moveToDeadLetter: runtime.moveToDeadLetter,
+    scheduleSave: runtime.scheduleSave,
+    logInfo: runtime.logInfo,
+    logWarn: runtime.logWarn,
+    logError: runtime.logError,
+    flushTriggerTimer: runtime.flushTriggerTimer,
+    flushReasonScheduledDrain: runtime.flushReasonScheduledDrain,
+    pushDrainExceptionRetryLimit: runtime.pushDrainExceptionRetryLimit,
+    pushDrainExceptionRetryDelayMs: runtime.pushDrainExceptionRetryDelayMs,
+    pushDrainStuckWarnMs: runtime.pushDrainStuckWarnMs,
+    pushDrainIntervalMs: runtime.pushDrainIntervalMs,
+    pushDrainAccountTimeBudgetMs: runtime.pushDrainAccountTimeBudgetMs,
+    pushDrainAccountBudget: runtime.pushDrainAccountBudget,
+    pushAckTimeoutMs: runtime.pushAckTimeoutMs,
+    maxRetry: runtime.maxRetry,
+    prePushGuardRetryDelayMs: runtime.prePushGuardRetryDelayMs,
+  });
+
+  return {
+    outboxAckLogs,
+    outboxAckOutcome,
+    messageAckRuntime,
+    outboxDrainAck,
+    outboxDrainSchedule,
+    outboxDrainRuntime,
+  };
+}

package/src/plugin/bridge-ack-facade.ts

@@ -0,0 +1,137 @@
+import type { BncrAckObservability, BncrAckStrategy } from '../core/types.ts';
+import {
+  buildBncrRuntimeAckStrategy,
+  resolveBncrRuntimeAckTimeoutDecision,
+} from '../runtime/outbound-ack-timeout.ts';
+import type { createBncrFileAckRuntime } from './file-ack-runtime.ts';
+
+type FileAckRuntime = ReturnType<typeof createBncrFileAckRuntime>;
+type FileAckWaitParams = Parameters<FileAckRuntime['waitForFileAck']>[0];
+type FileAckWaitResult = Awaited<ReturnType<FileAckRuntime['waitForFileAck']>>;
+
+export function createBncrBridgeAckFacade(runtime: {
+  normalizeAccountId: (accountId: string) => string;
+  now: () => number;
+  pushAckTimeoutMs: number;
+  adaptiveAckTimeoutDefaultEnabled: boolean;
+  adaptiveAckTimeoutLogThrottleMs: number;
+  adaptiveAckTimeoutObservationTtlMs: number;
+  adaptiveAckTimeoutRecoveryOkThreshold: number;
+  recommendedAckTimeoutMinMs: number;
+  recommendedAckTimeoutMaxMs: number;
+  getCounter: (map: Map<string, number>, accountId: string) => number;
+  ackTimeoutCountByAccount: Map<string, number>;
+  lateAckOkCountByAccount: Map<string, number>;
+  lastLateAckPushLatencyMsByAccount: Map<string, number>;
+  lastLateAckOkByAccount: Map<string, number>;
+  adaptiveAckRecoveryOkCountByAccount: Map<string, number>;
+  adaptiveAckTimeoutLogStateByAccount: Map<
+    string,
+    { at: number; timeoutMs: number; reason: string }
+  >;
+  logInfo: (scope: string | undefined, message: string, options?: { debugOnly?: boolean }) => void;
+  buildRuntimeAckObservability: (accountId: string) => BncrAckObservability;
+  buildRuntimeAckStrategy?: (ackObservability: BncrAckObservability) => unknown;
+  waitForMessageAck: (messageId: string, waitMs: number) => Promise<'acked' | 'timeout'>;
+  resolveMessageAck: (messageId: string, result?: 'acked' | 'timeout') => boolean;
+  fileAckKey: (transferId: string, stage: string, chunkIndex?: number) => string;
+  waitForFileAck: (params: FileAckWaitParams) => Promise<FileAckWaitResult>;
+  resolveFileAck: (params: {
+    transferId: string;
+    stage: string;
+    chunkIndex?: number;
+    payload: Record<string, unknown>;
+    ok: boolean;
+  }) => boolean;
+}) {
+  const maybeLogAdaptiveAckTimeout = (args: {
+    accountId: string;
+    timeoutMs: number;
+    reason: string;
+    lastLateAckPushLatencyMs: number | null;
+    nowMs?: number;
+  }) => {
+    if (args.timeoutMs <= runtime.pushAckTimeoutMs) return;
+    const t = typeof args.nowMs === 'number' ? args.nowMs : runtime.now();
+    const previous = runtime.adaptiveAckTimeoutLogStateByAccount.get(args.accountId);
+    if (
+      previous &&
+      previous.timeoutMs === args.timeoutMs &&
+      previous.reason === args.reason &&
+      t - previous.at < runtime.adaptiveAckTimeoutLogThrottleMs
+    ) {
+      return;
+    }
+    runtime.adaptiveAckTimeoutLogStateByAccount.set(args.accountId, {
+      at: t,
+      timeoutMs: args.timeoutMs,
+      reason: args.reason,
+    });
+    const parts = [
+      args.accountId,
+      `current=${args.timeoutMs}`,
+      `default=${runtime.pushAckTimeoutMs}`,
+      `reason=${args.reason}`,
+    ];
+    if (typeof args.lastLateAckPushLatencyMs === 'number')
+      parts.push(`latePushMs=${args.lastLateAckPushLatencyMs}`);
+    runtime.logInfo('outbox ack timeout-adaptive', parts.join('|'));
+  };
+
+  const resolveMessageAckTimeoutMs = (accountId?: string) => {
+    if (!runtime.adaptiveAckTimeoutDefaultEnabled) return runtime.pushAckTimeoutMs;
+    const acc = runtime.normalizeAccountId(accountId || 'default');
+    const lateAckOkCount = runtime.getCounter(runtime.lateAckOkCountByAccount, acc);
+    const recentAckTimeoutCount = runtime.getCounter(runtime.ackTimeoutCountByAccount, acc);
+    const lastLateAckPushLatencyMs = runtime.lastLateAckPushLatencyMsByAccount.get(acc) || null;
+    const lastLateAckOkAt = runtime.lastLateAckOkByAccount.get(acc) || null;
+    const adaptiveAckRecoveryOkCount = runtime.getCounter(
+      runtime.adaptiveAckRecoveryOkCountByAccount,
+      acc,
+    );
+    const nowMs = runtime.now();
+    const { timeoutMs, reason } = resolveBncrRuntimeAckTimeoutDecision({
+      lateAckOkCount,
+      recentAckTimeoutCount,
+      lastLateAckPushLatencyMs,
+      lastLateAckOkAt,
+      adaptiveAckRecoveryOkCount,
+      nowMs,
+      defaultAckTimeoutMs: runtime.pushAckTimeoutMs,
+      minAckTimeoutMs: runtime.recommendedAckTimeoutMinMs,
+      maxAckTimeoutMs: runtime.recommendedAckTimeoutMaxMs,
+      lateAckObservationTtlMs: runtime.adaptiveAckTimeoutObservationTtlMs,
+      recoveryOkThreshold: runtime.adaptiveAckTimeoutRecoveryOkThreshold,
+    });
+    maybeLogAdaptiveAckTimeout({
+      accountId: acc,
+      timeoutMs,
+      reason,
+      lastLateAckPushLatencyMs,
+      nowMs,
+    });
+    return timeoutMs;
+  };
+
+  return {
+    maybeLogAdaptiveAckTimeout,
+    resolveMessageAckTimeoutMs,
+    buildRuntimeAckObservability: (accountId: string) =>
+      runtime.buildRuntimeAckObservability(accountId),
+    buildRuntimeAckStrategy: (ackObservability: BncrAckObservability): BncrAckStrategy => {
+      if (runtime.buildRuntimeAckStrategy) {
+        return runtime.buildRuntimeAckStrategy(ackObservability) as BncrAckStrategy;
+      }
+      return buildBncrRuntimeAckStrategy({
+        ackObservability,
+        defaultAckTimeoutMs: runtime.pushAckTimeoutMs,
+        maxAckTimeoutMs: runtime.recommendedAckTimeoutMaxMs,
+      });
+    },
+    fileAckKey: runtime.fileAckKey,
+    waitForFileAck: runtime.waitForFileAck,
+    resolveFileAck: runtime.resolveFileAck,
+    resolveMessageAck: runtime.resolveMessageAck,
+    waitForMessageAck: runtime.waitForMessageAck,
+  };
+}

package/src/plugin/bridge-connection-facade.ts

@@ -0,0 +1,111 @@
+import type { GatewayRequestHandlerOptions } from 'openclaw/plugin-sdk/core';
+import type {
+  BncrConnection,
+  FileRecvTransferState,
+  FileSendTransferState,
+  OutboxEntry,
+} from '../core/types.ts';
+import { getErrorMessage } from './error-message.ts';
+
+export function createBncrBridgeConnectionFacade(runtime: {
+  now: () => number;
+  asString: (value: unknown, fallback?: string) => string;
+  normalizeAccountId: (accountId: string) => string;
+  connectionState: {
+    hasRecentInboundReachability: (accountId: string) => boolean;
+    resolveRecentInboundConnIds: (accountId: string) => Set<string>;
+    isRecentlyReachableConn: (accountId: string, connId?: string, clientId?: string) => boolean;
+    isRevalidatedAttemptedConn: (entry: OutboxEntry, connId: string) => boolean;
+    tryAdoptTransferOwner: (args: {
+      accountId: string;
+      transfer: FileSendTransferState | FileRecvTransferState | undefined;
+      connId: string;
+      clientId?: string;
+    }) => boolean;
+    refreshLiveConnectionState: (args: {
+      accountId: string;
+      connId: string;
+      clientId?: string;
+      outboundReady: boolean;
+      preferredForOutbound: boolean;
+      inboundOnly: boolean;
+      context: GatewayRequestHandlerOptions['context'];
+    }) => void;
+    refreshAcceptedFileTransferLiveState: (args: {
+      accountId: string;
+      connId: string;
+      clientId?: string;
+      context: GatewayRequestHandlerOptions['context'];
+    }) => void;
+  };
+  outboxRoute: {
+    resolveOutboxPushOwner: (accountId: string) => BncrConnection | null;
+    resolvePushConnIds: (accountId: string) => Set<string>;
+  };
+  rememberGatewayContext: (context: GatewayRequestHandlerOptions['context']) => void;
+  markActivity: (accountId: string, at?: number) => void;
+}) {
+  const rememberGatewayContext = (context: GatewayRequestHandlerOptions['context']) => {
+    if (!context) return;
+    runtime.rememberGatewayContext(context);
+  };
+
+  const isRetryableFileTransferError = (error: unknown) => {
+    const msg = runtime.asString(getErrorMessage(error, '')).trim().toLowerCase();
+    if (!msg) return true;
+
+    const retryableMarkers = [
+      'gateway context unavailable',
+      'no active bncr client for file chunk transfer',
+      'chunk ack timeout',
+      'complete ack timeout',
+      'transfer state missing',
+      'transfer aborted',
+      'temporarily unavailable',
+      'timeout',
+      'econn',
+      'socket',
+      'network',
+    ];
+
+    return retryableMarkers.some((marker) => msg.includes(marker));
+  };
+
+  return {
+    rememberGatewayContext,
+    resolveOutboxPushOwner: (accountId: string) =>
+      runtime.outboxRoute.resolveOutboxPushOwner(accountId),
+    resolvePushConnIds: (accountId: string) => runtime.outboxRoute.resolvePushConnIds(accountId),
+    hasRecentInboundReachability: (accountId: string) =>
+      runtime.connectionState.hasRecentInboundReachability(accountId),
+    resolveRecentInboundConnIds: (accountId: string) =>
+      runtime.connectionState.resolveRecentInboundConnIds(accountId),
+    isRecentlyReachableConn: (accountId: string, connId?: string, clientId?: string) =>
+      runtime.connectionState.isRecentlyReachableConn(accountId, connId, clientId),
+    isRevalidatedAttemptedConn: (entry: OutboxEntry, connId: string) =>
+      runtime.connectionState.isRevalidatedAttemptedConn(entry, connId),
+    tryAdoptTransferOwner: (args: {
+      accountId: string;
+      transfer: FileSendTransferState | FileRecvTransferState | undefined;
+      connId: string;
+      clientId?: string;
+    }) => runtime.connectionState.tryAdoptTransferOwner(args),
+    refreshLiveConnectionState: (args: {
+      accountId: string;
+      connId: string;
+      clientId?: string;
+      outboundReady: boolean;
+      preferredForOutbound: boolean;
+      inboundOnly: boolean;
+      context: GatewayRequestHandlerOptions['context'];
+    }) => runtime.connectionState.refreshLiveConnectionState(args),
+    refreshAcceptedFileTransferLiveState: (args: {
+      accountId: string;
+      connId: string;
+      clientId?: string;
+      context: GatewayRequestHandlerOptions['context'];
+    }) => runtime.connectionState.refreshAcceptedFileTransferLiveState(args),
+    markActivity: (accountId: string, at = runtime.now()) => runtime.markActivity(accountId, at),
+    isRetryableFileTransferError,
+  };
+}

package/src/plugin/bridge-diagnostics-facade.ts

@@ -0,0 +1,23 @@
+export function createBncrBridgeDiagnosticsFacade<
+  TRuntimeFlags,
+  TQueueCounters,
+  TIntegratedDiagnostics,
+  TDownlinkHealth,
+  TRuntimeStatusInput = unknown,
+>(runtime: {
+  buildRuntimeFlags: (accountId?: string) => TRuntimeFlags;
+  buildAccountQueueCounters: (accountId: string) => TQueueCounters;
+  buildIntegratedDiagnostics: (
+    accountId: string,
+    runtimeStatusInput?: TRuntimeStatusInput,
+  ) => TIntegratedDiagnostics;
+  buildDownlinkHealth: (accountId: string) => TDownlinkHealth;
+}) {
+  return {
+    buildRuntimeFlags: (accountId?: string) => runtime.buildRuntimeFlags(accountId),
+    buildAccountQueueCounters: (accountId: string) => runtime.buildAccountQueueCounters(accountId),
+    buildIntegratedDiagnostics: (accountId: string, runtimeStatusInput?: TRuntimeStatusInput) =>
+      runtime.buildIntegratedDiagnostics(accountId, runtimeStatusInput),
+    buildDownlinkHealth: (accountId: string) => runtime.buildDownlinkHealth(accountId),
+  };
+}

package/src/plugin/bridge-drain-facade.ts

@@ -0,0 +1,98 @@
+import { buildOutboxScheduleDebugInfo } from '../messaging/outbound/diagnostics.ts';
+import { clampOutboxDrainDelay } from '../messaging/outbound/queue-selectors.ts';
+import {
+  OUTBOUND_FLUSH_REASON,
+  OUTBOUND_FLUSH_TRIGGER,
+  OUTBOUND_SCHEDULE_SOURCE,
+} from '../messaging/outbound/reasons.ts';
+import { buildFlushBestEffortError } from './bridge-surface-helpers.ts';
+
+export function createBncrBridgeDrainFacade(runtime: {
+  bridgeId: string;
+  asString: (value: unknown, fallback?: string) => string;
+  normalizeAccountId: (accountId: string) => string;
+  getApi: () => unknown;
+  getStopped: () => boolean;
+  getPushTimer: () => NodeJS.Timeout | null;
+  setPushTimer: (timer: NodeJS.Timeout | null) => void;
+  getRetryCount: () => number;
+  setRetryCount: (count: number) => void;
+  logInfo: (scope: string | undefined, message: string, options?: { debugOnly?: boolean }) => void;
+  logError: (scope: string, message: string) => void;
+  flushPushQueue: (args?: {
+    accountId?: string;
+    trigger?: string;
+    reason?: string;
+  }) => Promise<void>;
+  schedulePushDrain: (delayMs?: number) => void;
+  resolveOutboundAckRequired: (args: { api: unknown; accountId?: string }) => boolean;
+  retryLimit: number;
+  retryDelayMs: number;
+}) {
+  const schedulePushDrain = (delayMs = 0) => {
+    if (runtime.getStopped()) return;
+    if (runtime.getPushTimer()) return;
+    const delay = clampOutboxDrainDelay(delayMs);
+    runtime.logInfo(
+      'outbox',
+      `schedule ${JSON.stringify(
+        buildOutboxScheduleDebugInfo({
+          bridgeId: runtime.bridgeId,
+          source: OUTBOUND_SCHEDULE_SOURCE.SCHEDULE_PUSH_DRAIN,
+          wait: delay,
+        }),
+      )}`,
+      { debugOnly: true },
+    );
+    runtime.setPushTimer(
+      setTimeout(() => {
+        runtime.setPushTimer(null);
+        if (runtime.getStopped()) return;
+        flushPushQueueBestEffort({
+          trigger: OUTBOUND_FLUSH_TRIGGER.TIMER,
+          reason: OUTBOUND_FLUSH_REASON.SCHEDULED_DRAIN,
+        });
+      }, delay),
+    );
+  };
+
+  const flushPushQueueBestEffort = (args?: {
+    accountId?: string;
+    trigger?: string;
+    reason?: string;
+  }) => {
+    void runtime
+      .flushPushQueue(args)
+      .then(() => {
+        runtime.setRetryCount(0);
+      })
+      .catch((error) => {
+        const nextRetryCount = runtime.getRetryCount() + 1;
+        const flushError = buildFlushBestEffortError({
+          accountId: args?.accountId,
+          trigger: args?.trigger,
+          reason: args?.reason,
+          error,
+          asString: runtime.asString,
+          normalizeAccountId: runtime.normalizeAccountId,
+          nextRetryCount,
+          retryLimit: runtime.retryLimit,
+        });
+        runtime.setRetryCount(nextRetryCount);
+        runtime.logError(
+          'outbox drain fail',
+          `accountId=${flushError.accountId || '-'}|reason=${flushError.reason}|err=${flushError.err}|retry=${flushError.retryDisplay}|limit=${runtime.retryLimit}`,
+        );
+        if (flushError.willRetry) runtime.schedulePushDrain(runtime.retryDelayMs);
+      });
+  };
+
+  const isOutboundAckRequired = (accountId?: string) =>
+    runtime.resolveOutboundAckRequired({ api: runtime.getApi(), accountId });
+
+  return {
+    schedulePushDrain,
+    flushPushQueueBestEffort,
+    isOutboundAckRequired,
+  };
+}