@xmoxmo/bncr 0.5.6 → 0.5.8

package/src/plugin/outbox-unified-push-flow.ts

@@ -0,0 +1,307 @@
+import {
+  buildFileTransferPushOkArgs,
+  buildFileTransferPushSuccessArgs,
+} from '../core/outbox-file-transfer-bookkeeping.ts';
+import { resolveFileTransferGuard } from '../core/outbox-file-transfer-guards.ts';
+import {
+  prepareRouteSelection,
+  prepareRouteSelection as prepareTextPushRouteSelection,
+} from '../core/outbox-file-transfer-prep.ts';
+import {
+  buildFileTransferBroadcastPayload,
+  buildFileTransferRouteSelectArgs,
+} from '../core/outbox-file-transfer-success.ts';
+import { resolveTextPushGuard } from '../core/outbox-text-push-guards.ts';
+import {
+  buildTextPushBroadcastPayload,
+  buildTextPushOkArgs,
+  buildTextPushRouteSelectArgs,
+  buildTextPushSuccessArgs,
+} from '../core/outbox-text-push-success.ts';
+import type { BncrConnection, BncrRoute, OutboxEntry } from '../core/types.ts';
+import { isPlainObject } from '../core/value-sanitize.ts';
+import {
+  selectOutboxFileTransferRouteCandidates,
+  selectOutboxRouteCandidates,
+} from '../messaging/outbound/queue-selectors.ts';
+
+type FileTransferGuardFailure = {
+  reason: 'media-url-missing' | 'no-gateway-context' | 'no-active-connection';
+  lastError: string;
+  recentInboundReachable?: boolean;
+};
+
+export type RunBncrOutboxPushArgs = {
+  entry: OutboxEntry;
+  gatewayContext: unknown;
+  owner: BncrConnection | null;
+  resolvePushConnIds: (accountId: string) => Set<string>;
+  resolveRecentInboundConnIds: (accountId: string) => Set<string>;
+  hasRecentInboundReachability: (accountId: string) => boolean;
+  isRevalidatedAttemptedConn: (connId: string) => boolean;
+  // Route + guard failure
+  recordOutboxPrePushFailure: (args: {
+    entry: OutboxEntry;
+    lastError: string;
+    persist?: boolean;
+  }) => void;
+  logOutboxPushSkip: (args: {
+    messageId: string;
+    accountId: string;
+    reason: string;
+    recentInboundReachable?: boolean;
+    routeReason?: string;
+    connIds?: Iterable<string>;
+    ownerConnId?: string;
+    ownerClientId?: string;
+  }) => void;
+  handleFileTransferPushGuardFailure: (args: {
+    entry: OutboxEntry;
+    guard: FileTransferGuardFailure & { ok: false };
+  }) => void;
+  // Broadcast + bookkeeping (unified)
+  pushEvent: string;
+  gatewayBroadcastToConnIds: (
+    event: string,
+    payload: unknown,
+    connIds: ReadonlySet<string>,
+  ) => void;
+  recordOutboxPushSuccess: (args: {
+    entry: OutboxEntry;
+    connIds: Iterable<string>;
+    ownerConnId?: string;
+    ownerClientId?: string;
+  }) => void;
+  logOutboxRouteSelect: (args: {
+    messageId: string;
+    accountId: string;
+    kind?: 'file-transfer';
+    routeReason: string;
+    connIds: Iterable<string>;
+    ownerConnId: string;
+    ownerClientId: string;
+    recentInboundReachable: boolean;
+    event: string;
+  }) => void;
+  logOutboxPushOkSummary: (messageId: string) => void;
+  logOutboundSummary: (entry: OutboxEntry) => void;
+  logOutboxPushOk: (args: {
+    messageId: string;
+    accountId: string;
+    kind?: 'file-transfer';
+    connIds: Iterable<string>;
+    ownerConnId: string;
+    ownerClientId: string;
+    recentInboundReachable: boolean;
+    event: string;
+  }) => void;
+  // Failure handlers
+  handleTextPushFailure: (args: { entry: OutboxEntry; error: unknown }) => void;
+  handleFileTransferPushFailure: (args: { entry: OutboxEntry; error: unknown }) => void;
+  // Media-specific (optional)
+  transferMediaToBncrClient?: (params: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    mediaUrl: string;
+    mediaLocalRoots?: readonly string[];
+    downloadMedia?: boolean;
+  }) => Promise<{
+    mode: 'base64' | 'chunk';
+    mimeType?: string;
+    fileName?: string;
+    base64?: string;
+    path?: string;
+  }>;
+  buildFileTransferOutboundFrame?: (params: {
+    entry: OutboxEntry;
+    msg: Record<string, unknown>;
+    media: { fileName?: string; mimeType?: string; path?: string; base64?: string; type?: string };
+    mediaUrl: string;
+  }) => Record<string, unknown>;
+};
+
+export async function runBncrOutboxPush(args: RunBncrOutboxPushArgs): Promise<boolean> {
+  const entry = args.entry;
+  const msg =
+    isPlainObject(entry.payload) &&
+    isPlainObject((entry.payload as Record<string, unknown>).message)
+      ? ((entry.payload as Record<string, unknown>).message as Record<string, unknown>)
+      : null;
+  const transferMode = msg?.transferMode === 'media' ? 'media' : 'text';
+
+  // Route selection
+  const selection =
+    transferMode === 'media'
+      ? prepareRouteSelection({
+          entry,
+          owner: args.owner,
+          resolvePushConnIds: args.resolvePushConnIds,
+          resolveRecentInboundConnIds: args.resolveRecentInboundConnIds,
+          hasRecentInboundReachability: args.hasRecentInboundReachability,
+          isRevalidatedAttemptedConn: args.isRevalidatedAttemptedConn,
+          selectRouteCandidates: selectOutboxFileTransferRouteCandidates,
+        })
+      : prepareTextPushRouteSelection({
+          entry,
+          owner: args.owner,
+          resolvePushConnIds: args.resolvePushConnIds,
+          resolveRecentInboundConnIds: args.resolveRecentInboundConnIds,
+          hasRecentInboundReachability: args.hasRecentInboundReachability,
+          isRevalidatedAttemptedConn: args.isRevalidatedAttemptedConn,
+          selectRouteCandidates: selectOutboxRouteCandidates,
+        });
+
+  // Guard + dispatch
+  if (transferMode === 'media') {
+    const guard = resolveFileTransferGuard({
+      gatewayContext: args.gatewayContext,
+      entry,
+      owner: args.owner,
+      routeSelection: selection,
+      mediaUrl: String(msg!.mediaUrl || '').trim(),
+    });
+    if (!guard.ok) {
+      args.handleFileTransferPushGuardFailure({
+        entry,
+        guard: guard as FileTransferGuardFailure & { ok: false },
+      });
+      return false;
+    }
+
+    // ── Media success path (inline) ──
+    try {
+      const media = await args.transferMediaToBncrClient!({
+        accountId: entry.accountId,
+        sessionKey: entry.sessionKey,
+        route: entry.route,
+        mediaUrl: guard.mediaUrl,
+        mediaLocalRoots: Array.isArray(msg!.mediaLocalRoots)
+          ? (msg!.mediaLocalRoots as readonly string[])
+          : undefined,
+        downloadMedia: msg!.downloadMedia as boolean | undefined,
+      });
+      const frame = args.buildFileTransferOutboundFrame!({
+        entry,
+        msg: msg!,
+        media,
+        mediaUrl: guard.mediaUrl,
+      });
+
+      args.gatewayBroadcastToConnIds(
+        args.pushEvent,
+        buildFileTransferBroadcastPayload({ frame, messageId: entry.messageId }),
+        new Set(guard.connIds),
+      );
+      args.logOutboxRouteSelect(
+        buildFileTransferRouteSelectArgs({
+          entry,
+          connIds: guard.connIds,
+          routeReason: guard.routeReason,
+          recentInboundReachable: guard.recentInboundReachable,
+          owner: args.owner,
+          event: args.pushEvent,
+        }),
+      );
+      args.recordOutboxPushSuccess(
+        buildFileTransferPushSuccessArgs({
+          entry,
+          connIds: guard.connIds,
+          owner: args.owner,
+        }),
+      );
+      args.logOutboxPushOkSummary(entry.messageId);
+      // Sync entry type from the resolved frame
+      const frameMsg = frame?.message as Record<string, unknown> | undefined;
+      if (frameMsg?.type !== undefined) {
+        (msg! as Record<string, unknown>).type = frameMsg.type;
+      }
+      args.logOutboundSummary(entry);
+      args.logOutboxPushOk(
+        buildFileTransferPushOkArgs({
+          entry,
+          connIds: guard.connIds,
+          recentInboundReachable: guard.recentInboundReachable,
+          event: args.pushEvent,
+        }),
+      );
+      return true;
+    } catch (error) {
+      args.handleFileTransferPushFailure({ entry, error });
+      return false;
+    }
+  }
+
+  // ── Text ──
+  const textGuard = resolveTextPushGuard({
+    gatewayContext: args.gatewayContext,
+    entry,
+    routeSelection: selection,
+  });
+  if (!textGuard.ok) {
+    args.recordOutboxPrePushFailure({
+      entry,
+      lastError:
+        textGuard.reason === 'no-gateway-context'
+          ? 'gateway context unavailable'
+          : 'no active bncr client',
+      persist: true,
+    });
+    args.logOutboxPushSkip({
+      messageId: entry.messageId,
+      accountId: entry.accountId,
+      reason: textGuard.reason,
+      recentInboundReachable:
+        textGuard.reason === 'no-active-connection' ? textGuard.recentInboundReachable : undefined,
+      routeReason: selection.routeReason,
+      connIds: selection.connIds,
+      ownerConnId: selection.ownerConnId,
+      ownerClientId: args.owner?.clientId,
+    });
+    return false;
+  }
+
+  // ── Text success path (inline) ──
+  try {
+    args.gatewayBroadcastToConnIds(
+      args.pushEvent,
+      buildTextPushBroadcastPayload({
+        payload: entry.payload,
+        messageId: entry.messageId,
+      }),
+      new Set(textGuard.connIds),
+    );
+    args.logOutboxRouteSelect(
+      buildTextPushRouteSelectArgs({
+        entry,
+        connIds: textGuard.connIds,
+        routeReason: textGuard.routeReason,
+        recentInboundReachable: textGuard.recentInboundReachable,
+        owner: args.owner,
+        event: args.pushEvent,
+      }),
+    );
+    args.recordOutboxPushSuccess(
+      buildTextPushSuccessArgs({
+        entry,
+        connIds: textGuard.connIds,
+        ownerConnId: textGuard.ownerConnId,
+        ownerClientId: textGuard.ownerConnId ? args.owner?.clientId : undefined,
+      }),
+    );
+    args.logOutboxPushOkSummary(entry.messageId);
+    args.logOutboundSummary(entry);
+    args.logOutboxPushOk(
+      buildTextPushOkArgs({
+        entry,
+        connIds: textGuard.connIds,
+        recentInboundReachable: textGuard.recentInboundReachable,
+        event: args.pushEvent,
+      }),
+    );
+    return true;
+  } catch (error) {
+    args.handleTextPushFailure({ entry, error });
+    return false;
+  }
+}

package/src/plugin/scene-registry.ts

@@ -36,7 +36,7 @@ export function buildSceneKey(parsed: ParsedInbound): string {
     : `${parsed.platform}:${parsed.userId}`;
 }
 
-export function buildSceneRecord(args: {
+function buildSceneRecord(args: {
   parsed: ParsedInbound;
   sceneKey: string;
   kind: BncrSceneKind;

package/src/plugin/target-runtime.ts

@@ -6,15 +6,10 @@ import {
   routeKey,
 } from '../core/targets.ts';
 import type { BncrRoute } from '../core/types.ts';
+import { asString } from '../core/value-sanitize.ts';
 import { getOpenClawRuntimeConfigOrDefault } from '../openclaw/config-runtime.ts';
 import type { BncrChannelConfigRoot } from './channel-runtime-types.ts';
 
-function asString(v: unknown, fallback = ''): string {
-  if (typeof v === 'string') return v;
-  if (v == null) return fallback;
-  return String(v);
-}
-
 export function createBncrTargetRuntime(runtime: {
   api: Parameters<typeof getOpenClawRuntimeConfigOrDefault>[0];
   channelId: string;

package/src/runtime/log-dedupe.ts

@@ -5,10 +5,10 @@ export type LogDedupeStateEntry = {
 
 export type LogDedupeState = Map<string, LogDedupeStateEntry>;
 
-export const LOG_DEDUPE_STATE_TTL_MS = 10 * 60 * 1000;
-export const LOG_DEDUPE_STATE_MAX_ENTRIES = 1_000;
+const LOG_DEDUPE_STATE_TTL_MS = 10 * 60 * 1000;
+const LOG_DEDUPE_STATE_MAX_ENTRIES = 1_000;
 
-export function pruneLogDedupeState(
+function pruneLogDedupeState(
   state: LogDedupeState,
   currentTime: number,
   options?: {

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

@@ -1,4 +1,5 @@
 import type { BncrAckObservability, BncrAckStrategy } from '../core/types.ts';
+import { asString, finiteNumberOr } from '../core/value-sanitize.ts';
 
 type ComputeBncrRecommendedAckTimeoutArgs = {
   lateAckOkCount: number;
@@ -41,9 +42,7 @@ function isAdaptiveAckRecovered(args: {
   );
 }
 
-export function computeBncrRecommendedAckTimeoutReason(
-  args: ComputeBncrRecommendedAckTimeoutReasonArgs,
-) {
+function computeBncrRecommendedAckTimeoutReason(args: ComputeBncrRecommendedAckTimeoutReasonArgs) {
   if (args.recentAckTimeoutCount <= 0) return 'no-timeout-evidence';
   if (args.lateAckOkCount <= 0) return 'no-late-ack-evidence';
   if (typeof args.lastLateAckPushLatencyMs !== 'number') return 'missing-latency';
@@ -53,7 +52,7 @@ export function computeBncrRecommendedAckTimeoutReason(
   return 'late-ack-observed';
 }
 
-export function computeBncrRecommendedAckTimeoutMs(args: ComputeBncrRecommendedAckTimeoutArgs) {
+function computeBncrRecommendedAckTimeoutMs(args: ComputeBncrRecommendedAckTimeoutArgs) {
   if (
     args.lateAckOkCount <= 0 ||
     args.recentAckTimeoutCount <= 0 ||
@@ -76,14 +75,6 @@ export function resolveBncrRuntimeAckTimeoutDecision(args: ComputeBncrRecommende
   return { timeoutMs, reason };
 }
 
-function finiteNumberOr(value: unknown, fallback: number) {
-  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
-}
-
-function asString(value: unknown, fallback = '') {
-  return typeof value === 'string' ? value : fallback;
-}
-
 export function buildBncrRuntimeAckStrategy(args: {
   ackObservability: BncrAckObservability;
   defaultAckTimeoutMs: number;

package/src/runtime/outbox-transitions.ts

@@ -1,4 +1,5 @@
 import type { OutboxEntry } from '../core/types.ts';
+import { finiteNumberOr } from '../core/value-sanitize.ts';
 import type {
   PushFailureDecision,
   RetryRerouteDecision,
@@ -83,10 +84,6 @@ export function buildBncrOutboxPushSuccessEntryPatch(args: {
   };
 }
 
-function finiteNumberOr(value: unknown, fallback: number): number {
-  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
-}
-
 export function buildBncrAckOkTelemetryPatch(args: {
   entry: OutboxEntry;
   ackAt: number;

package/src/runtime/status-snapshots.ts

@@ -34,7 +34,7 @@ function getCounter(map: Map<string, number>, accountId: string): number {
   return map.get(normalizeAccountId(accountId)) || 0;
 }
 
-export function buildRuntimeQueueSnapshot(args: {
+function buildRuntimeQueueSnapshot(args: {
   accountId: string;
   outboxEntries: Iterable<OutboxEntry>;
   deadLetterEntries: Iterable<OutboxEntry>;
@@ -59,7 +59,7 @@ export function buildRuntimeQueueSnapshot(args: {
   };
 }
 
-export function buildRuntimeEventCounters(args: {
+function buildRuntimeEventCounters(args: {
   accountId: string;
   connectEventsByAccount: Map<string, number>;
   inboundEventsByAccount: Map<string, number>;

package/src/runtime/status-worker.ts

@@ -1,5 +1,6 @@
 import { normalizeAccountId } from '../core/accounts.ts';
 import type { BncrDiagnosticsSummary } from '../core/types.ts';
+import { finiteNumberOr, nonNegativeFiniteNumberOr } from '../core/value-sanitize.ts';
 
 type StatusRuntimeMeta = {
   pending?: number;
@@ -48,7 +49,7 @@ export type ChannelAccountWorkerHandle = {
   healthLogState?: HealthStatusLogState;
 };
 
-export const HEALTH_STATUS_STABLE_WINDOW_MS = 10_000;
+const HEALTH_STATUS_STABLE_WINDOW_MS = 10_000;
 
 export type HealthStatusLogState = {
   emittedSig: string | null;
@@ -60,15 +61,6 @@ export function createHealthStatusLogState(): HealthStatusLogState {
   return { emittedSig: null, pendingSig: null, pendingSince: 0 };
 }
 
-function finiteNumberOr(value: unknown, fallback: number): number {
-  const n = Number(value);
-  return Number.isFinite(n) ? n : fallback;
-}
-
-function nonNegativeFiniteNumberOr(value: unknown, fallback: number): number {
-  return Math.max(0, finiteNumberOr(value, fallback));
-}
-
 export function updateHealthStatusLogState(args: {
   state: HealthStatusLogState;
   sig: string;
@@ -120,11 +112,7 @@ type StatusWorkerRuntime = {
   hooks: StatusWorkerHooks;
 };
 
-export function clearBncrStatusWorker(
-  runtime: StatusWorkerRuntime,
-  accountId: string,
-  reason: string,
-) {
+function clearBncrStatusWorker(runtime: StatusWorkerRuntime, accountId: string, reason: string) {
   const worker = runtime.workers.get(accountId);
   if (!worker) return false;
   worker.finish(reason);

package/src/core/outbox-text-push-prep.ts

@@ -1,36 +0,0 @@
-import type { BncrConnection, OutboxEntry } from './types.ts';
-
-export function prepareTextPushRouteSelection(args: {
-  entry: OutboxEntry;
-  owner: BncrConnection | null;
-  resolvePushConnIds: (accountId: string) => Iterable<string>;
-  resolveRecentInboundConnIds: (accountId: string) => Iterable<string>;
-  hasRecentInboundReachability: (accountId: string) => boolean;
-  isRevalidatedAttemptedConn: (connId: string) => boolean;
-  selectOutboxRouteCandidates: (args: {
-    routeCandidates: Iterable<string>;
-    attemptedConnIds: string[];
-    recentInboundConnIds: Iterable<string>;
-    ownerConnId?: string;
-    recentInboundReachable: boolean;
-    isRevalidatedAttemptedConn: (connId: string) => boolean;
-  }) => {
-    connIds: Iterable<string>;
-    recentInboundReachable: boolean;
-    routeReason: string;
-    ownerConnId?: string;
-  };
-}) {
-  const attemptedConnIds = Array.isArray(args.entry.routeAttemptConnIds)
-    ? args.entry.routeAttemptConnIds.filter((v): v is string => typeof v === 'string' && !!v)
-    : [];
-
-  return args.selectOutboxRouteCandidates({
-    routeCandidates: args.resolvePushConnIds(args.entry.accountId),
-    attemptedConnIds,
-    recentInboundConnIds: args.resolveRecentInboundConnIds(args.entry.accountId),
-    ownerConnId: args.owner?.connId,
-    recentInboundReachable: args.hasRecentInboundReachability(args.entry.accountId),
-    isRevalidatedAttemptedConn: args.isRevalidatedAttemptedConn,
-  });
-}

package/src/messaging/outbound/build-send-action.ts

@@ -1,130 +0,0 @@
-import { randomUUID } from 'node:crypto';
-
-type MinimalBncrSendInput = {
-  channel?: string;
-  action?: string;
-  idempotencyKey?: string;
-  accountId?: string;
-  to?: string;
-  message?: string;
-  caption?: string;
-  path?: string;
-  media?: string;
-  filePath?: string;
-  mediaUrl?: string;
-  mediaUrls?: string[];
-  asVoice?: boolean;
-  audioAsVoice?: boolean;
-  params?: Record<string, unknown>;
-};
-
-type BuiltBncrMessageAction = {
-  channel: string;
-  action: string;
-  idempotencyKey: string;
-  accountId?: string;
-  params: Record<string, unknown>;
-};
-
-function asString(v: unknown, fallback = ''): string {
-  if (typeof v === 'string') return v;
-  if (v == null) return fallback;
-  return String(v);
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function pickFirstString(...values: unknown[]): string | undefined {
-  for (const value of values) {
-    if (typeof value !== 'string') continue;
-    if (value.length === 0) return '';
-    return value;
-  }
-  return undefined;
-}
-
-function pickFirstBoolean(...values: unknown[]): boolean | undefined {
-  for (const value of values) {
-    if (typeof value === 'boolean') return value;
-  }
-  return undefined;
-}
-
-export function buildBncrMessageAction(input: MinimalBncrSendInput): BuiltBncrMessageAction {
-  const paramsObj = isPlainObject(input.params) ? input.params : {};
-
-  const channel = asString(input.channel || 'bncr').trim() || 'bncr';
-  const action = asString(input.action || 'send').trim() || 'send';
-  const idempotencyKey = asString(input.idempotencyKey || '').trim() || `bncr-${randomUUID()}`;
-  const accountId =
-    asString(pickFirstString(paramsObj.accountId, input.accountId) || '').trim() || undefined;
-
-  const to = asString(pickFirstString(paramsObj.to, input.to) || '').trim();
-  if (!to) throw new Error('bncr send requires to');
-
-  const mediaPath = pickFirstString(
-    paramsObj.media,
-    paramsObj.path,
-    paramsObj.filePath,
-    paramsObj.mediaUrl,
-    input.media,
-    input.path,
-    input.filePath,
-    input.mediaUrl,
-  );
-  const rawMediaUrls = Array.isArray(paramsObj.mediaUrls)
-    ? paramsObj.mediaUrls
-    : Array.isArray(input.mediaUrls)
-      ? input.mediaUrls
-      : undefined;
-  const mediaUrls = rawMediaUrls?.map((value) => asString(value || '').trim()).filter(Boolean);
-
-  const message = pickFirstString(paramsObj.message, input.message) ?? '';
-  const explicitCaption = pickFirstString(paramsObj.caption, input.caption) ?? '';
-  const asVoice = pickFirstBoolean(paramsObj.asVoice, input.asVoice);
-  const audioAsVoice = pickFirstBoolean(paramsObj.audioAsVoice, input.audioAsVoice);
-
-  if ((asVoice === true || audioAsVoice === true) && !mediaPath && !mediaUrls?.length) {
-    throw new Error('bncr voice send requires media path');
-  }
-
-  const normalizedParams: Record<string, unknown> = {
-    ...paramsObj,
-    to,
-  };
-
-  if (mediaPath) {
-    normalizedParams.path = mediaPath;
-    const finalCaption = explicitCaption || message;
-    if (finalCaption) normalizedParams.caption = finalCaption;
-    delete normalizedParams.message;
-    if (mediaUrls?.length) normalizedParams.mediaUrls = mediaUrls;
-  } else {
-    if (mediaUrls?.length) {
-      normalizedParams.mediaUrls = mediaUrls;
-      const finalCaption = explicitCaption || message;
-      if (finalCaption) normalizedParams.caption = finalCaption;
-      delete normalizedParams.message;
-      delete normalizedParams.path;
-    } else {
-      const finalMessage = message || explicitCaption;
-      if (!finalMessage.trim()) throw new Error('bncr send requires message or media');
-      normalizedParams.message = finalMessage;
-      delete normalizedParams.caption;
-    }
-  }
-
-  if (asVoice === true) normalizedParams.asVoice = true;
-  if (audioAsVoice === true) normalizedParams.audioAsVoice = true;
-  if (accountId) normalizedParams.accountId = accountId;
-
-  return {
-    channel,
-    action,
-    idempotencyKey,
-    ...(accountId ? { accountId } : {}),
-    params: normalizedParams,
-  };
-}