@xmoxmo/bncr 0.2.4 → 0.2.6

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

@@ -0,0 +1,329 @@
+import type { BncrRoute, OutboxEntry } from '../../core/types.ts';
+import { buildReplyMediaFallbackDebugInfo } from './diagnostics.ts';
+import { normalizeOutboundReplyToId } from './reply-target-policy.ts';
+
+export type ReplyPayloadInput = {
+  text?: string;
+  mediaUrl?: string;
+  mediaUrls?: string[];
+  asVoice?: boolean;
+  audioAsVoice?: boolean;
+  kind?: 'tool' | 'block' | 'final';
+  replyToId?: string;
+};
+
+export type NormalizedReplyPayload = {
+  text: string;
+  mediaUrl: string;
+  mediaUrls?: string[];
+  mediaList: string[];
+  asVoice: boolean;
+  audioAsVoice: boolean;
+  kind?: 'tool' | 'block' | 'final';
+  replyToId: string;
+};
+
+export type ReplyMediaEntriesParams = {
+  accountId: string;
+  sessionKey: string;
+  route: BncrRoute;
+  payload: NormalizedReplyPayload;
+  mediaLocalRoots?: readonly string[];
+};
+
+export type EnqueueNormalizedReplyPayloadParams = {
+  accountId: string;
+  sessionKey: string;
+  route: BncrRoute;
+  payload: NormalizedReplyPayload;
+  mediaLocalRoots?: readonly string[];
+};
+
+export type ReplyMediaFileTransferParams = {
+  accountId: string;
+  sessionKey: string;
+  route: BncrRoute;
+  mediaUrl: string;
+  mediaLocalRoots?: readonly string[];
+  text: string;
+  normalizedText: string;
+  asVoice: boolean;
+  audioAsVoice: boolean;
+  kind?: 'tool' | 'block' | 'final';
+  replyToId: string;
+  createdAt: number;
+};
+
+export type EnqueueSingleReplyMediaEntryParams = {
+  params: ReplyMediaEntriesParams;
+  mediaUrl: string;
+  normalizedText: string;
+  text: string;
+  fallback: { text: string; reason: string } | null;
+  currentTime: number;
+};
+
+export type ReplyMediaFallbackTextEntryParams = {
+  accountId: string;
+  sessionKey: string;
+  route: BncrRoute;
+  mediaUrl: string;
+  kind?: 'tool' | 'block' | 'final';
+  replyToId: string;
+  fallback: { text: string; reason: string };
+};
+
+export function hasReplyMediaEntries(payload: NormalizedReplyPayload) {
+  return payload.mediaList.length > 0;
+}
+
+export function buildReplyTextOutboxEntry(
+  params: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    text: string;
+    kind?: 'tool' | 'block' | 'final';
+    replyToId: string;
+  },
+  helpers: {
+    buildTextOutboxEntry: (args: {
+      accountId: string;
+      sessionKey: string;
+      route: BncrRoute;
+      text: string;
+      kind?: 'tool' | 'block' | 'final';
+      replyToId?: string;
+    }) => OutboxEntry;
+  },
+): OutboxEntry {
+  return helpers.buildTextOutboxEntry({
+    accountId: params.accountId,
+    sessionKey: params.sessionKey,
+    route: params.route,
+    text: params.text,
+    kind: params.kind,
+    replyToId: params.replyToId || undefined,
+  });
+}
+
+export function enqueueReplyTextEntry(
+  params: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    payload: NormalizedReplyPayload;
+  },
+  helpers: {
+    enqueueOutbound: (entry: OutboxEntry) => void;
+    buildTextOutboxEntry: (args: {
+      accountId: string;
+      sessionKey: string;
+      route: BncrRoute;
+      text: string;
+      kind?: 'tool' | 'block' | 'final';
+      replyToId?: string;
+    }) => OutboxEntry;
+  },
+): void {
+  if (!params.payload.text) return;
+
+  helpers.enqueueOutbound(
+    buildReplyTextOutboxEntry(
+      {
+        accountId: params.accountId,
+        sessionKey: params.sessionKey,
+        route: params.route,
+        text: params.payload.text,
+        kind: params.payload.kind,
+        replyToId: params.payload.replyToId,
+      },
+      { buildTextOutboxEntry: helpers.buildTextOutboxEntry },
+    ),
+  );
+}
+
+export function enqueueReplyMediaFallbackTextEntry(
+  params: ReplyMediaFallbackTextEntryParams,
+  helpers: {
+    logInfo: (scope: string | undefined, message: string, options?: { debugOnly?: boolean }) => void;
+    enqueueOutbound: (entry: OutboxEntry) => void;
+    buildTextOutboxEntry: (args: {
+      accountId: string;
+      sessionKey: string;
+      route: BncrRoute;
+      text: string;
+      kind?: 'tool' | 'block' | 'final';
+      replyToId?: string;
+    }) => OutboxEntry;
+  },
+): void {
+  helpers.logInfo(
+    'outbound',
+    `media-dedupe-hit ${JSON.stringify(buildReplyMediaFallbackDebugInfo(params))}`,
+    { debugOnly: true },
+  );
+  helpers.enqueueOutbound(
+    buildReplyTextOutboxEntry(
+      {
+        accountId: params.accountId,
+        sessionKey: params.sessionKey,
+        route: params.route,
+        text: params.fallback.text,
+        kind: params.kind,
+        replyToId: params.replyToId,
+      },
+      { buildTextOutboxEntry: helpers.buildTextOutboxEntry },
+    ),
+  );
+}
+
+export function enqueueReplyMediaFileTransferEntry(
+  params: ReplyMediaFileTransferParams,
+  helpers: {
+    enqueueOutbound: (entry: OutboxEntry) => void;
+    buildFileTransferOutboxEntry: (args: {
+      accountId: string;
+      sessionKey: string;
+      route: BncrRoute;
+      mediaUrl: string;
+      mediaLocalRoots?: readonly string[];
+      text: string;
+      asVoice: boolean;
+      audioAsVoice: boolean;
+      kind?: 'tool' | 'block' | 'final';
+      replyToId?: string;
+    }) => OutboxEntry;
+    rememberRecentMediaSend: (args: {
+      sessionKey: string;
+      mediaUrl: string;
+      text: string;
+      replyToId: string;
+      createdAt: number;
+    }) => void;
+  },
+): void {
+  helpers.enqueueOutbound(
+    helpers.buildFileTransferOutboxEntry({
+      accountId: params.accountId,
+      sessionKey: params.sessionKey,
+      route: params.route,
+      mediaUrl: params.mediaUrl,
+      mediaLocalRoots: params.mediaLocalRoots,
+      text: params.text,
+      asVoice: params.asVoice,
+      audioAsVoice: params.audioAsVoice,
+      kind: params.kind,
+      replyToId: params.replyToId || undefined,
+    }),
+  );
+  helpers.rememberRecentMediaSend({
+    sessionKey: params.sessionKey,
+    mediaUrl: params.mediaUrl,
+    text: params.normalizedText,
+    replyToId: params.replyToId,
+    createdAt: params.createdAt,
+  });
+}
+
+export function enqueueSingleReplyMediaEntry(
+  params: EnqueueSingleReplyMediaEntryParams,
+  helpers: {
+    enqueueReplyMediaFallbackTextEntry: (params: ReplyMediaFallbackTextEntryParams) => void;
+    enqueueReplyMediaFileTransferEntry: (params: ReplyMediaFileTransferParams) => void;
+  },
+): void {
+  if (params.fallback !== null) {
+    helpers.enqueueReplyMediaFallbackTextEntry({
+      accountId: params.params.accountId,
+      sessionKey: params.params.sessionKey,
+      route: params.params.route,
+      mediaUrl: params.mediaUrl,
+      kind: params.params.payload.kind,
+      replyToId: params.params.payload.replyToId,
+      fallback: params.fallback,
+    });
+    return;
+  }
+
+  helpers.enqueueReplyMediaFileTransferEntry({
+    accountId: params.params.accountId,
+    sessionKey: params.params.sessionKey,
+    route: params.params.route,
+    mediaUrl: params.mediaUrl,
+    mediaLocalRoots: params.params.mediaLocalRoots,
+    text: params.text,
+    normalizedText: params.normalizedText,
+    asVoice: params.params.payload.asVoice,
+    audioAsVoice: params.params.payload.audioAsVoice,
+    kind: params.params.payload.kind,
+    replyToId: params.params.payload.replyToId,
+    createdAt: params.currentTime,
+  });
+}
+
+export function enqueueNormalizedReplyPayload(
+  params: EnqueueNormalizedReplyPayloadParams,
+  helpers: {
+    logEnqueueFromReply: (args: {
+      accountId: string;
+      sessionKey: string;
+      route: BncrRoute;
+      payload: NormalizedReplyPayload;
+    }) => void;
+    hasReplyMediaEntries: (payload: NormalizedReplyPayload) => boolean;
+    enqueueReplyMediaEntries: (params: ReplyMediaEntriesParams) => void;
+    enqueueReplyTextEntry: (params: {
+      accountId: string;
+      sessionKey: string;
+      route: BncrRoute;
+      payload: NormalizedReplyPayload;
+    }) => void;
+  },
+): void {
+  helpers.logEnqueueFromReply({
+    accountId: params.accountId,
+    sessionKey: params.sessionKey,
+    route: params.route,
+    payload: params.payload,
+  });
+
+  if (helpers.hasReplyMediaEntries(params.payload)) {
+    helpers.enqueueReplyMediaEntries({
+      accountId: params.accountId,
+      sessionKey: params.sessionKey,
+      route: params.route,
+      payload: params.payload,
+      mediaLocalRoots: params.mediaLocalRoots,
+    });
+    return;
+  }
+
+  helpers.enqueueReplyTextEntry({
+    accountId: params.accountId,
+    sessionKey: params.sessionKey,
+    route: params.route,
+    payload: params.payload,
+  });
+}
+
+export function normalizeReplyPayload(
+  payload: ReplyPayloadInput,
+  helpers: { asString: (value: unknown, fallback?: string) => string },
+): NormalizedReplyPayload {
+  const text = helpers.asString(payload?.text || '').trim();
+  const mediaUrl = helpers.asString(payload?.mediaUrl || '').trim();
+  const mediaUrls = Array.isArray(payload?.mediaUrls)
+    ? payload.mediaUrls.map((v) => helpers.asString(v || '').trim()).filter(Boolean)
+    : undefined;
+  return {
+    text,
+    mediaUrl,
+    mediaUrls,
+    mediaList: mediaUrls?.length ? mediaUrls : mediaUrl ? [mediaUrl] : [],
+    asVoice: payload?.asVoice === true,
+    audioAsVoice: payload?.audioAsVoice === true,
+    kind: payload?.kind,
+    replyToId: normalizeOutboundReplyToId({ kind: payload?.kind, replyToId: payload?.replyToId }),
+  };
+}

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

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

package/src/messaging/outbound/retry-policy.ts

@@ -0,0 +1,142 @@
+import type { BncrRoute } from '../../channel.ts';
+
+function finiteNonNegativeIntegerOr(value: unknown, fallback: number): number {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return fallback;
+  return Math.floor(n);
+}
+
+export type RetryRerouteDecisionInput = {
+  nowMs: number;
+  maxRetry: number;
+  requireAck: boolean;
+  currentRetryCount: number;
+  currentRouteAttemptRound: number;
+  currentFastReroutePending: boolean;
+  lastError?: string;
+  currentConnId?: string;
+  attemptedConnIds: string[];
+  availableConnIds: string[];
+};
+
+export type RetryRerouteDecision =
+  | {
+      kind: 'dead-letter';
+      terminalReason: string;
+      nextRetryCount: number;
+      lastAttemptAt: number;
+    }
+  | {
+      kind: 'retry';
+      nextRetryCount: number;
+      lastAttemptAt: number;
+      nextAttemptAt: number;
+      lastError: string;
+      attemptedConnIds: string[];
+      fastReroutePending: boolean;
+      routeAttemptRound: number;
+      hasUntriedAlternative: boolean;
+      shouldFastReroute: boolean;
+      revalidatedConnIds: string[];
+    };
+
+export function computeRetryRerouteDecision(
+  input: RetryRerouteDecisionInput,
+  deps: { backoffMs: (retryCount: number) => number },
+): RetryRerouteDecision {
+  const attemptedConnIds = Array.isArray(input.attemptedConnIds)
+    ? input.attemptedConnIds.filter((v): v is string => typeof v === 'string' && !!v)
+    : [];
+  const currentConnId = `${input.currentConnId || ''}`.trim();
+  if (currentConnId && !attemptedConnIds.includes(currentConnId)) attemptedConnIds.push(currentConnId);
+
+  const availableConnIds = Array.isArray(input.availableConnIds)
+    ? input.availableConnIds.filter((v): v is string => typeof v === 'string' && !!v)
+    : [];
+  const revalidatedConnIds = attemptedConnIds.filter((connId) => availableConnIds.includes(connId));
+  const hasUntriedAlternative = availableConnIds.some((connId) => !attemptedConnIds.includes(connId));
+  const shouldFastReroute = input.requireAck && input.currentFastReroutePending !== true && hasUntriedAlternative;
+
+  const currentRetryCount = finiteNonNegativeIntegerOr(input.currentRetryCount, 0);
+  const currentRouteAttemptRound = finiteNonNegativeIntegerOr(input.currentRouteAttemptRound, 0);
+  const nextRetryCount = currentRetryCount + 1;
+  const lastAttemptAt = input.nowMs;
+  const terminalReason =
+    input.lastError || (input.requireAck ? 'push-ack-timeout' : 'push-delivery-unconfirmed');
+
+  if (nextRetryCount > input.maxRetry) {
+    return {
+      kind: 'dead-letter',
+      terminalReason,
+      nextRetryCount,
+      lastAttemptAt,
+    };
+  }
+
+  const nextAttemptAt = shouldFastReroute ? input.nowMs + 1_000 : input.nowMs + deps.backoffMs(nextRetryCount);
+  const lastError = input.requireAck ? 'push-ack-timeout' : 'push-delivery-unconfirmed';
+  const routeAttemptRound = hasUntriedAlternative ? currentRouteAttemptRound : currentRouteAttemptRound + 1;
+  const fastReroutePending = hasUntriedAlternative ? shouldFastReroute || input.currentFastReroutePending === true : false;
+
+  return {
+    kind: 'retry',
+    nextRetryCount,
+    lastAttemptAt,
+    nextAttemptAt,
+    lastError,
+    attemptedConnIds: hasUntriedAlternative ? attemptedConnIds : [],
+    fastReroutePending,
+    routeAttemptRound,
+    hasUntriedAlternative,
+    shouldFastReroute,
+    revalidatedConnIds,
+  };
+}
+
+export type PushFailureDecisionInput = {
+  nowMs: number;
+  maxRetry: number;
+  currentRetryCount: number;
+  lastError?: string;
+};
+
+export type PushFailureDecision =
+  | {
+      kind: 'dead-letter';
+      terminalReason: string;
+      nextRetryCount: number;
+      lastAttemptAt: number;
+    }
+  | {
+      kind: 'retry';
+      nextRetryCount: number;
+      lastAttemptAt: number;
+      nextAttemptAt: number;
+      lastError: string;
+    };
+
+export function computePushFailureDecision(
+  input: PushFailureDecisionInput,
+  deps: { backoffMs: (retryCount: number) => number },
+): PushFailureDecision {
+  const currentRetryCount = finiteNonNegativeIntegerOr(input.currentRetryCount, 0);
+  const nextRetryCount = currentRetryCount + 1;
+  const lastAttemptAt = input.nowMs;
+
+  if (nextRetryCount > input.maxRetry) {
+    return {
+      kind: 'dead-letter',
+      terminalReason: input.lastError || 'push-retry-limit',
+      nextRetryCount,
+      lastAttemptAt,
+    };
+  }
+
+  return {
+    kind: 'retry',
+    nextRetryCount,
+    lastAttemptAt,
+    nextAttemptAt: input.nowMs + deps.backoffMs(nextRetryCount),
+    lastError: input.lastError || 'push-retry',
+  };
+}

package/src/messaging/outbound/send.ts

@@ -3,6 +3,7 @@ export async function sendBncrText(params: {
   accountId: string;
   to: string;
   text: string;
+  kind?: 'tool' | 'block' | 'final';
   replyToId?: string;
   mediaLocalRoots?: readonly string[];
   resolveVerifiedTarget: (
@@ -18,6 +19,7 @@ export async function sendBncrText(params: {
       text?: string;
       mediaUrl?: string;
       mediaUrls?: string[];
+      kind?: 'tool' | 'block' | 'final';
       replyToId?: string;
     };
     mediaLocalRoots?: readonly string[];
@@ -33,6 +35,7 @@ export async function sendBncrText(params: {
     route: verified.route,
     payload: {
       text: params.text,
+      kind: params.kind,
       replyToId: params.replyToId,
     },
     mediaLocalRoots: params.mediaLocalRoots,
@@ -54,6 +57,7 @@ export async function sendBncrMedia(params: {
   mediaUrls?: string[];
   asVoice?: boolean;
   audioAsVoice?: boolean;
+  kind?: 'tool' | 'block' | 'final';
   replyToId?: string;
   mediaLocalRoots?: readonly string[];
   resolveVerifiedTarget: (
@@ -71,6 +75,7 @@ export async function sendBncrMedia(params: {
       mediaUrls?: string[];
       asVoice?: boolean;
       audioAsVoice?: boolean;
+      kind?: 'tool' | 'block' | 'final';
       replyToId?: string;
     };
     mediaLocalRoots?: readonly string[];
@@ -90,6 +95,7 @@ export async function sendBncrMedia(params: {
       mediaUrls: params.mediaUrls?.length ? params.mediaUrls : undefined,
       asVoice: params.asVoice === true ? true : undefined,
       audioAsVoice: params.audioAsVoice === true ? true : undefined,
+      kind: params.kind,
       replyToId: params.replyToId,
     },
     mediaLocalRoots: params.mediaLocalRoots,

package/src/messaging/outbound/session-route.ts

@@ -26,6 +26,28 @@ function asString(v: unknown, fallback = ''): string {
   return String(v);
 }
 
+function attachBncrChannelRouteRefFields(args: {
+  built: Record<string, unknown>;
+  channel: string;
+  accountId?: string;
+  to: string;
+  chatType: 'direct' | 'group';
+  threadId?: string;
+}) {
+  const { built, channel, accountId, to, chatType, threadId } = args;
+  return {
+    ...built,
+    channel,
+    ...(accountId !== undefined ? { accountId } : {}),
+    target: {
+      to,
+      rawTo: to,
+      chatType,
+    },
+    ...(threadId !== undefined ? { thread: { id: threadId } } : {}),
+  };
+}
+
 export function resolveBncrOutboundSessionRoute(params: ResolveBncrOutboundSessionRouteParams) {
   const raw = asString(params.resolvedTarget?.to || params.target).trim();
   if (!raw) return null;
@@ -65,9 +87,16 @@ export function resolveBncrOutboundSessionRoute(params: ResolveBncrOutboundSessi
     ...(params.threadId !== undefined ? { threadId: params.threadId } : {}),
   });
 
-  return {
-    ...built,
-    sessionKey,
-    baseSessionKey: sessionKey,
-  };
+  return attachBncrChannelRouteRefFields({
+    built: {
+      ...built,
+      sessionKey,
+      baseSessionKey: sessionKey,
+    },
+    channel: params.channel,
+    accountId: params.accountId,
+    to: displayTo,
+    chatType: 'direct',
+    threadId: params.threadId,
+  });
 }