@xmoxmo/bncr 0.3.5 → 0.3.7

package/src/messaging/outbound/diagnostics.ts

@@ -1,6 +1,24 @@
-import type { BncrConnection, OutboxEntry } from '../../core/types.ts';
-import { OUTBOUND_TERMINAL_REASON, type OutboundScheduleSource } from './reasons.ts';
-import type { RetryRerouteDecision } from './retry-policy.ts';
+import type {
+  BncrAckObservability,
+  BncrExtendedOutboundDiagnostics,
+  BncrOutboxIncidentSummary,
+  BncrOutboxQueueDiagnostics,
+  OutboxEntry,
+} from '../../core/types.ts';
+
+export {
+  buildFlushDebugInfo,
+  buildOutboxAckDebugInfo,
+  buildOutboxDrainSkipDebugInfo,
+  buildOutboxDrainStuckDebugInfo,
+  buildOutboxPushOkDebugInfo,
+  buildOutboxPushSkipDebugInfo,
+  buildOutboxRouteSelectDebugInfo,
+  buildOutboxScheduleDebugInfo,
+  buildPushFailureDebugInfo,
+  buildReplyMediaFallbackDebugInfo,
+  buildRetryRerouteDebugInfo,
+} from './diagnostics-debug-builders.ts';
 
 type OutboxIncidentSummaryInput = {
   pending: number;
@@ -36,7 +54,9 @@ function positiveAgeMs(nowMs: number, at: unknown): number | null {
   return Math.max(0, nowMs - n);
 }
 
-export function buildOutboxIncidentSummary(input: OutboxIncidentSummaryInput) {
+export function buildOutboxIncidentSummary(
+  input: OutboxIncidentSummaryInput,
+): BncrOutboxIncidentSummary {
   const pending = Math.max(0, Math.floor(finiteNumberOrNull(input.pending) || 0));
   const nowMs = finiteNumberOrNull(input.nowMs) || Date.now();
   const lastPushError =
@@ -134,7 +154,7 @@ export function buildOutboxIncidentSummary(input: OutboxIncidentSummaryInput) {
 }
 
 export function buildExtendedOutboundDiagnostics(input: {
-  outbox: Record<string, any>;
+  outbox: BncrOutboxQueueDiagnostics;
   enqueueCount: number;
   lastEnqueueAt?: number | null;
   prePushGuardSkipCount: number;
@@ -142,9 +162,9 @@ export function buildExtendedOutboundDiagnostics(input: {
   lastPrePushGuardSkipReason?: string | null;
   hasGatewayContext: boolean;
   lastGatewayContextAt?: number | null;
-  ackObservability: Record<string, any>;
+  ackObservability: BncrAckObservability;
   nowMs?: number;
-}) {
+}): BncrExtendedOutboundDiagnostics {
   const lastEnqueueAt = finiteNumberOrNull(input.lastEnqueueAt);
   const lastPrePushGuardSkipAt = finiteNumberOrNull(input.lastPrePushGuardSkipAt);
   const lastGatewayContextAt = finiteNumberOrNull(input.lastGatewayContextAt);
@@ -159,7 +179,10 @@ export function buildExtendedOutboundDiagnostics(input: {
     lastGatewayContextAt,
     incident: buildOutboxIncidentSummary({
       ...input.outbox,
+      pending: Number(input.outbox.pending) || 0,
       hasGatewayContext: input.hasGatewayContext,
+      activeOutboundConnection: Boolean(input.outbox.activeOutboundConnection),
+      activeOutboundConnectionCount: Number(input.outbox.activeOutboundConnectionCount) || 0,
       prePushGuardSkipCount: input.prePushGuardSkipCount,
       lastPrePushGuardSkipAt,
       lastPrePushGuardSkipReason: input.lastPrePushGuardSkipReason || null,
@@ -180,7 +203,7 @@ export function buildOutboxQueueDiagnostics(args: {
   outboxEntries: Iterable<OutboxEntry>;
   pendingAllAccounts: number;
   pushConnIds: Iterable<string>;
-}) {
+}): BncrOutboxQueueDiagnostics {
   const accountEntries = Array.from(args.outboxEntries).filter(
     (entry) => entry.accountId === args.accountId,
   );
@@ -221,338 +244,6 @@ export function buildOutboxQueueDiagnostics(args: {
   };
 }
 
-export function buildOutboxScheduleDebugInfo(args: {
-  bridgeId: string;
-  accountId?: string | null;
-  // Account-local aggregated next delay after considering currently visible entries.
-  localNextDelay?: number | null;
-  // Bridge-global aggregated next delay after merging account-local scheduling decisions.
-  globalNextDelay?: number | null;
-  // Immediate wait observed for this specific scheduling event.
-  wait?: number | null;
-  source: OutboundScheduleSource;
-  messageId?: string;
-}) {
-  return {
-    bridge: args.bridgeId,
-    ...(args.accountId ? { accountId: args.accountId } : {}),
-    ...(args.messageId ? { messageId: args.messageId } : {}),
-    source: args.source,
-    ...(typeof args.wait === 'number' ? { wait: args.wait } : {}),
-    ...(typeof args.localNextDelay === 'number' ? { localNextDelay: args.localNextDelay } : {}),
-    ...(typeof args.globalNextDelay === 'number' ? { globalNextDelay: args.globalNextDelay } : {}),
-  };
-}
-
-export function buildOutboxPushSkipDebugInfo(args: {
-  messageId: string;
-  accountId: string;
-  reason: string;
-  recentInboundReachable?: boolean;
-  kind?: string;
-  routeReason?: string;
-  connIds?: Iterable<string>;
-  ownerConnId?: string;
-  ownerClientId?: string;
-  activeConnectionCount?: number;
-  connections?: Iterable<BncrConnection>;
-}) {
-  return {
-    messageId: args.messageId,
-    accountId: args.accountId,
-    ...(args.kind ? { kind: args.kind } : {}),
-    reason: args.reason,
-    ...(args.routeReason ? { routeReason: args.routeReason } : {}),
-    ...(args.connIds ? { connIds: Array.from(args.connIds) } : {}),
-    ...(args.ownerConnId ? { ownerConnId: args.ownerConnId } : {}),
-    ...(args.ownerClientId ? { ownerClientId: args.ownerClientId } : {}),
-    ...(typeof args.activeConnectionCount === 'number'
-      ? { activeConnectionCount: args.activeConnectionCount }
-      : {}),
-    ...(args.connections
-      ? {
-          connections: Array.from(args.connections)
-            .filter((c) => c.accountId === args.accountId)
-            .slice(0, 8)
-            .map((c) => ({
-              connId: c.connId,
-              clientId: c.clientId,
-              lastSeenAt: c.lastSeenAt,
-              outboundReadyUntil: (c as any).outboundReadyUntil,
-              preferredForOutboundUntil: (c as any).preferredForOutboundUntil,
-              inboundOnly: (c as any).inboundOnly,
-              lastAckOkAt: (c as any).lastAckOkAt,
-              lastPushTimeoutAt: (c as any).lastPushTimeoutAt,
-              pushFailureScore: (c as any).pushFailureScore,
-            })),
-        }
-      : {}),
-    ...(typeof args.recentInboundReachable === 'boolean'
-      ? { recentInboundReachable: args.recentInboundReachable }
-      : {}),
-  };
-}
-
-export function buildOutboxRouteSelectDebugInfo(args: {
-  messageId: string;
-  accountId: string;
-  routeReason: string;
-  connIds: Iterable<string>;
-  ownerConnId?: string;
-  ownerClientId?: string;
-  recentInboundReachable: boolean;
-  event: string;
-  kind?: string;
-}) {
-  return {
-    messageId: args.messageId,
-    accountId: args.accountId,
-    ...(args.kind ? { kind: args.kind } : {}),
-    routeReason: args.routeReason,
-    connIds: Array.from(args.connIds),
-    ownerConnId: args.ownerConnId || '',
-    ownerClientId: args.ownerClientId || '',
-    recentInboundReachable: args.recentInboundReachable,
-    event: args.event,
-  };
-}
-
-export function buildOutboxPushOkDebugInfo(args: {
-  messageId: string;
-  accountId: string;
-  connIds: Iterable<string>;
-  ownerConnId?: string;
-  ownerClientId?: string;
-  recentInboundReachable: boolean;
-  event: string;
-  kind?: string;
-}) {
-  return {
-    messageId: args.messageId,
-    accountId: args.accountId,
-    ...(args.kind ? { kind: args.kind } : {}),
-    connIds: Array.from(args.connIds),
-    ownerConnId: args.ownerConnId || '',
-    ownerClientId: args.ownerClientId || '',
-    recentInboundReachable: args.recentInboundReachable,
-    event: args.event,
-  };
-}
-
-export function buildFlushDebugInfo(args: {
-  bridgeId: string;
-  accountId: string | null;
-  targetAccounts: string[];
-  outboxSize: number;
-  trigger: string;
-  reason?: string;
-}) {
-  return {
-    bridge: args.bridgeId,
-    accountId: args.accountId,
-    targetAccounts: [...args.targetAccounts],
-    outboxSize: args.outboxSize,
-    trigger: args.trigger,
-    reason: args.reason,
-  };
-}
-
-export function buildOutboxDrainSkipDebugInfo(args: {
-  bridgeId: string;
-  accountId: string;
-  reason: string;
-  outboxSize: number;
-  trigger: string;
-}) {
-  return {
-    bridge: args.bridgeId,
-    accountId: args.accountId,
-    reason: args.reason,
-    outboxSize: args.outboxSize,
-    trigger: args.trigger,
-  };
-}
-
-export function buildOutboxDrainStuckDebugInfo(args: {
-  bridgeId: string;
-  accountId: string;
-  reason: string;
-  trigger: string;
-  outboxSize: number;
-  pending: number;
-  runningMs: number;
-  runningSince?: number | null;
-  hasGatewayContext: boolean;
-  activeConnectionCount: number;
-  messageAckWaiters: number;
-  fileAckWaiters: number;
-  pendingEntries?: Iterable<{
-    messageId?: string;
-    retryCount?: number;
-    nextAttemptAt?: number;
-    lastAttemptAt?: number;
-    lastError?: string;
-    lastPushAt?: number;
-    lastPushConnId?: string;
-    routeAttemptConnIds?: string[];
-  }>;
-  connections?: Iterable<BncrConnection>;
-}) {
-  return {
-    bridge: args.bridgeId,
-    accountId: args.accountId,
-    reason: args.reason,
-    trigger: args.trigger,
-    outboxSize: args.outboxSize,
-    pending: args.pending,
-    runningMs: args.runningMs,
-    runningSince: args.runningSince ?? null,
-    hasGatewayContext: args.hasGatewayContext,
-    activeConnectionCount: args.activeConnectionCount,
-    waiters: {
-      messageAck: args.messageAckWaiters,
-      fileAck: args.fileAckWaiters,
-    },
-    ...(args.pendingEntries
-      ? {
-          pendingEntries: Array.from(args.pendingEntries)
-            .slice(0, 8)
-            .map((entry) => ({
-              messageId: entry.messageId || '',
-              retryCount: entry.retryCount,
-              nextAttemptAt: entry.nextAttemptAt,
-              lastAttemptAt: entry.lastAttemptAt,
-              lastError: entry.lastError,
-              lastPushAt: entry.lastPushAt,
-              lastPushConnId: entry.lastPushConnId,
-              routeAttemptConnIds: entry.routeAttemptConnIds,
-            })),
-        }
-      : {}),
-    ...(args.connections
-      ? {
-          connections: Array.from(args.connections)
-            .filter((c) => c.accountId === args.accountId)
-            .slice(0, 8)
-            .map((c) => ({
-              connId: c.connId,
-              clientId: c.clientId,
-              connectedAt: c.connectedAt,
-              lastSeenAt: c.lastSeenAt,
-              outboundReadyUntil: (c as any).outboundReadyUntil,
-              preferredForOutboundUntil: (c as any).preferredForOutboundUntil,
-              inboundOnly: (c as any).inboundOnly,
-              lastAckOkAt: (c as any).lastAckOkAt,
-              lastPushTimeoutAt: (c as any).lastPushTimeoutAt,
-              pushFailureScore: (c as any).pushFailureScore,
-            })),
-        }
-      : {}),
-  };
-}
-
-export function buildOutboxAckDebugInfo(args: {
-  messageId: string;
-  accountId: string;
-  requireAck: boolean;
-  ackResult: 'acked' | 'timeout';
-  onlineNow: boolean;
-  recentInboundReachable: boolean;
-  connIds?: Iterable<string>;
-  ownerConnId?: string;
-  ownerClientId?: string;
-  sessionKey?: string;
-  to?: string;
-  ackStage?: string;
-  ackOutcome?: string;
-  reason?: string;
-  kind?: string;
-  event?: string;
-  ackTimeoutMs?: number;
-  adaptiveAckTimeoutEnabled?: boolean;
-}) {
-  return {
-    messageId: args.messageId,
-    accountId: args.accountId,
-    ...(args.sessionKey ? { sessionKey: args.sessionKey } : {}),
-    ...(args.to ? { to: args.to } : {}),
-    ...(args.kind ? { kind: args.kind } : {}),
-    requireAck: args.requireAck,
-    ackResult: args.ackResult,
-    ackStage: args.ackStage || 'message',
-    ackOutcome: args.ackOutcome || args.ackResult,
-    ...(args.reason ? { reason: args.reason } : {}),
-    ...(typeof args.ackTimeoutMs === 'number' ? { ackTimeoutMs: args.ackTimeoutMs } : {}),
-    ...(typeof args.adaptiveAckTimeoutEnabled === 'boolean'
-      ? { adaptiveAckTimeoutEnabled: args.adaptiveAckTimeoutEnabled }
-      : {}),
-    onlineNow: args.onlineNow,
-    recentInboundReachable: args.recentInboundReachable,
-    ...(args.connIds ? { connIds: Array.from(args.connIds) } : {}),
-    ...(args.ownerConnId ? { ownerConnId: args.ownerConnId } : {}),
-    ...(args.ownerClientId ? { ownerClientId: args.ownerClientId } : {}),
-    ...(args.event ? { event: args.event } : {}),
-  };
-}
-
-export function buildRetryRerouteDebugInfo(args: {
-  messageId: string;
-  accountId: string;
-  currentConnId: string;
-  decision: RetryRerouteDecision;
-  availableConnIds: string[];
-}) {
-  if (args.decision.kind !== 'retry') {
-    return {
-      messageId: args.messageId,
-      accountId: args.accountId,
-      currentConnId: args.currentConnId,
-      availableConnIds: [...args.availableConnIds],
-      kind: args.decision.kind,
-      terminalReason: args.decision.terminalReason,
-      nextRetryCount: args.decision.nextRetryCount,
-      lastAttemptAt: args.decision.lastAttemptAt,
-    };
-  }
-
-  return {
-    messageId: args.messageId,
-    accountId: args.accountId,
-    currentConnId: args.currentConnId,
-    attemptedConnIds: [...args.decision.attemptedConnIds],
-    availableConnIds: [...args.availableConnIds],
-    revalidatedConnIds: [...args.decision.revalidatedConnIds],
-    hasUntriedAlternative: args.decision.hasUntriedAlternative,
-    shouldFastReroute: args.decision.shouldFastReroute,
-    routeAttemptRound: args.decision.routeAttemptRound,
-    nextAttemptAt: args.decision.nextAttemptAt,
-    fastReroutePending: args.decision.fastReroutePending,
-    nextRetryCount: args.decision.nextRetryCount,
-    lastAttemptAt: args.decision.lastAttemptAt,
-    lastError: args.decision.lastError,
-    kind: args.decision.kind,
-  };
-}
-
-export function buildPushFailureDebugInfo(args: {
-  messageId: string;
-  accountId: string;
-  retryCount: number;
-  lastError?: string;
-  retryable?: boolean;
-  kind?: string;
-}) {
-  return {
-    messageId: args.messageId,
-    accountId: args.accountId,
-    ...(args.kind ? { kind: args.kind } : {}),
-    ...(typeof args.retryable === 'boolean' ? { retryable: args.retryable } : {}),
-    retryCount: args.retryCount,
-    error:
-      (typeof args.lastError === 'string' && args.lastError) || OUTBOUND_TERMINAL_REASON.PUSH_RETRY,
-  };
-}
-
 export function buildEnqueueFromReplyDebugInfo(args: {
   accountId: string;
   sessionKey: string;
@@ -586,18 +277,3 @@ export function buildEnqueueFromReplyDebugInfo(args: {
     },
   };
 }
-
-export function buildReplyMediaFallbackDebugInfo(args: {
-  sessionKey: string;
-  mediaUrl: string;
-  replyToId: string;
-  fallback: { text: string; reason: string };
-}) {
-  return {
-    sessionKey: args.sessionKey,
-    mediaUrl: args.mediaUrl,
-    replyToId: args.replyToId || undefined,
-    fallbackText: args.fallback.text,
-    reason: args.fallback.reason,
-  };
-}

package/src/messaging/outbound/durable-message-adapter.ts

@@ -6,6 +6,7 @@ import type {
   ChannelMessageSendTextContext,
 } from 'openclaw/plugin-sdk/channel-message';
 import { defineChannelMessageAdapter } from 'openclaw/plugin-sdk/channel-message';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk/core';
 
 import {
   buildFileTransferOutboxEntry,
@@ -14,23 +15,25 @@ import {
 import type { BncrRoute, OutboxEntry } from '../../core/types.ts';
 import { buildBncrDurableQueuedResult } from './durable-queue-adapter.ts';
 
-export type BncrDurableMessageQueuedAdapterDeps<TConfig = unknown> = {
-  enqueueText: (ctx: ChannelMessageSendTextContext<TConfig>) => Promise<OutboxEntry> | OutboxEntry;
+export type BncrDurableMessageQueuedAdapterDeps = {
+  enqueueText: (
+    ctx: ChannelMessageSendTextContext<OpenClawConfig>,
+  ) => Promise<OutboxEntry> | OutboxEntry;
   enqueueMedia?: (
-    ctx: ChannelMessageSendMediaContext<TConfig>,
+    ctx: ChannelMessageSendMediaContext<OpenClawConfig>,
   ) => Promise<OutboxEntry> | OutboxEntry;
   enqueuePayload?: (
-    ctx: ChannelMessageSendPayloadContext<TConfig>,
+    ctx: ChannelMessageSendPayloadContext<OpenClawConfig>,
   ) => Promise<OutboxEntry> | OutboxEntry;
   now?: () => number;
 };
 
-export type BncrDurableMessageQueuedAdapterBuilderDeps<TConfig = unknown> = {
+export type BncrDurableMessageQueuedAdapterBuilderDeps = {
   createMessageId: () => string;
   now: () => number;
   normalizeAccountId: (accountId?: string | null) => string;
   normalizeReplyToId: (value?: string | null) => string;
-  resolveTarget: (ctx: ChannelMessageSendTextContext<TConfig>) => {
+  resolveTarget: (ctx: ChannelMessageSendTextContext<OpenClawConfig>) => {
     route: BncrRoute;
     sessionKey: string;
     accountId?: string | null;
@@ -41,9 +44,9 @@ export type BncrDurableMessageQueuedAdapterBuilderDeps<TConfig = unknown> = {
 // This adapter intentionally models only the OpenClaw -> bncr-plugin handoff.
 // Once a message is accepted into bncr's own outbox, OpenClaw should stop managing it;
 // client/platform ACK, retry, and deadLetter remain owned by the bncr service framework.
-export function createBncrDurableMessageQueuedAdapter<TConfig = unknown>(
-  deps: BncrDurableMessageQueuedAdapterDeps<TConfig>,
-): ChannelMessageAdapterShape<TConfig, ChannelMessageSendResult> {
+export function createBncrDurableMessageQueuedAdapter(
+  deps: BncrDurableMessageQueuedAdapterDeps,
+): ChannelMessageAdapterShape<OpenClawConfig, ChannelMessageSendResult> {
   return defineChannelMessageAdapter({
     id: 'bncr-queued-outbox',
     receive: {
@@ -62,10 +65,10 @@ export function createBncrDurableMessageQueuedAdapter<TConfig = unknown>(
   });
 }
 
-export function createBncrDurableMessageQueuedAdapterFromBuilders<TConfig = unknown>(
-  deps: BncrDurableMessageQueuedAdapterBuilderDeps<TConfig>,
-): ChannelMessageAdapterShape<TConfig, ChannelMessageSendResult> {
-  return createBncrDurableMessageQueuedAdapter<TConfig>({
+export function createBncrDurableMessageQueuedAdapterFromBuilders(
+  deps: BncrDurableMessageQueuedAdapterBuilderDeps,
+): ChannelMessageAdapterShape<OpenClawConfig, ChannelMessageSendResult> {
+  return createBncrDurableMessageQueuedAdapter({
     now: deps.now,
     enqueueText: (ctx) => {
       const resolved = deps.resolveTarget(ctx);
@@ -74,7 +77,7 @@ export function createBncrDurableMessageQueuedAdapterFromBuilders<TConfig = unkn
         now: deps.now,
         normalizeAccountId: deps.normalizeAccountId,
         normalizeReplyToId: deps.normalizeReplyToId,
-        accountId: resolved.accountId ?? ctx.accountId ?? undefined,
+        accountId: resolved.accountId ?? ctx.accountId ?? '',
         sessionKey: resolved.sessionKey,
         route: resolved.route,
         text: ctx.text,
@@ -89,7 +92,7 @@ export function createBncrDurableMessageQueuedAdapterFromBuilders<TConfig = unkn
         now: deps.now,
         normalizeAccountId: deps.normalizeAccountId,
         pushEvent: deps.filePushEvent ?? 'bncr.file.push',
-        accountId: resolved.accountId ?? ctx.accountId ?? undefined,
+        accountId: resolved.accountId ?? ctx.accountId ?? '',
         sessionKey: resolved.sessionKey,
         route: resolved.route,
         mediaUrl: ctx.mediaUrl,
@@ -110,8 +113,9 @@ function toChannelMessageSendResult(
 ): ChannelMessageSendResult {
   if (!entry) throw new Error('bncr durable message adapter did not receive an outbox entry');
   const queued = buildBncrDurableQueuedResult({ entry, sentAt: now?.() });
+  const receipt: ChannelMessageSendResult['receipt'] = queued.receipt;
   return {
-    receipt: queued.receipt as any,
+    receipt,
     messageId: queued.receipt.primaryPlatformMessageId,
   };
 }

package/src/messaging/outbound/durable-queue-adapter.ts

@@ -65,6 +65,14 @@ export type BncrDurableQueuedResult = {
   }>;
 };
 
+type OutboxPayload = OutboxEntry['payload'];
+type OutboxMeta = NonNullable<OutboxPayload['_meta']>;
+type OutboxMessagePayload = { type?: unknown };
+
+function getOutboxPayload(entry: OutboxEntry): OutboxPayload {
+  return entry.payload;
+}
+
 export function buildBncrDurableQueuedResult(args: {
   entry: OutboxEntry;
   index?: number;
@@ -131,24 +139,29 @@ export function buildBncrDurableQueuedResult(args: {
 }
 
 function extractPayloadType(entry: OutboxEntry): string | undefined {
-  const payload = entry.payload as any;
+  const payload = getOutboxPayload(entry);
   return typeof payload?.type === 'string' ? payload.type : undefined;
 }
 
 function extractReplyToId(entry: OutboxEntry): string | undefined {
-  const payload = entry.payload as any;
-  const metaReply = payload?._meta?.replyToId;
+  const payload = getOutboxPayload(entry);
+  const metaReply = (payload?._meta as OutboxMeta | undefined)?.replyToId;
   const replyToId = payload?.replyToId ?? metaReply;
   return typeof replyToId === 'string' ? replyToId : undefined;
 }
 
 function inferReceiptKind(entry: OutboxEntry): 'text' | 'media' | 'voice' | 'unknown' {
-  const payload = entry.payload as any;
-  if (payload?._meta?.kind === 'file-transfer') {
-    if (payload?._meta?.asVoice === true || payload?._meta?.audioAsVoice === true) return 'voice';
+  const payload = getOutboxPayload(entry);
+  const meta = payload?._meta as OutboxMeta | undefined;
+  const message =
+    payload.message && typeof payload.message === 'object'
+      ? (payload.message as OutboxMessagePayload)
+      : null;
+  if (meta?.kind === 'file-transfer') {
+    if (meta.asVoice === true || meta.audioAsVoice === true) return 'voice';
     return 'media';
   }
-  if (payload?.message?.type === 'text') return 'text';
+  if (message?.type === 'text') return 'text';
   return 'unknown';
 }
 

package/src/messaging/outbound/media.ts

@@ -1,5 +1,7 @@
 import { normalizeOutboundReplyToId } from './reply-target-policy.ts';
 
+type BncrOutboundMessageType = 'text' | 'image' | 'video' | 'voice' | 'audio' | 'file';
+
 function asString(v: unknown, fallback = ''): string {
   if (typeof v === 'string') return v;
   if (v == null) return fallback;
@@ -11,34 +13,43 @@ function isAudioMimeType(mimeType?: string): boolean {
   return mt.startsWith('audio/');
 }
 
+function isBncrOutboundMessageType(value: string): value is BncrOutboundMessageType {
+  return (
+    value === 'text' ||
+    value === 'image' ||
+    value === 'video' ||
+    value === 'voice' ||
+    value === 'audio' ||
+    value === 'file'
+  );
+}
+
+function isMimeMajorOutboundMessageType(
+  value: string,
+): value is Exclude<BncrOutboundMessageType, 'voice' | 'file'> {
+  return value === 'text' || value === 'image' || value === 'video' || value === 'audio';
+}
+
 export function resolveBncrOutboundMessageType(params: {
   mimeType?: string;
   fileName?: string;
   hintedType?: string;
   hasPayload?: boolean;
-}): 'text' | 'image' | 'video' | 'voice' | 'audio' | 'file' {
+}): BncrOutboundMessageType {
   const hinted = asString(params.hintedType || '').toLowerCase();
   const hasPayload = !!params.hasPayload;
   const mt = asString(params.mimeType || '').toLowerCase();
   const major = mt.split('/')[0] || '';
-  const isStandard =
-    hinted === 'text' ||
-    hinted === 'image' ||
-    hinted === 'video' ||
-    hinted === 'voice' ||
-    hinted === 'audio' ||
-    hinted === 'file';
+  const isStandard = isBncrOutboundMessageType(hinted);
 
   if (hasPayload && major === 'text' && (hinted === 'text' || !isStandard)) return 'file';
   if (hinted === 'voice') {
     if (isAudioMimeType(mt)) return 'voice';
-    if (major === 'text' || major === 'image' || major === 'video' || major === 'audio')
-      return major as any;
+    if (isMimeMajorOutboundMessageType(major)) return major;
     return 'file';
   }
-  if (isStandard) return hinted as any;
-  if (major === 'text' || major === 'image' || major === 'video' || major === 'audio')
-    return major as any;
+  if (isStandard) return hinted;
+  if (isMimeMajorOutboundMessageType(major)) return major;
   return 'file';
 }