@xmoxmo/bncr 0.5.5 → 0.5.7

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

@@ -0,0 +1,327 @@
+/**
+ * Unified outbound send normalization.
+ *
+ * All send entry points (tool action, channel.send, channel.message)
+ * fold into one shape first, then branch media vs text.
+ *
+ * Priority for control fields: marker/text-block > host/params extra > direct params.
+ * Marker-specified type is always preserved (in normalized.type or re-injected into extra
+ * for text branch) and never silently downgraded.
+ *
+ * Marker path/paths are media evidence unless ismedia is explicitly false.
+ */
+
+import { asString, isPlainObject } from '../../core/value-sanitize.ts';
+import { extractConsumptionFields, parseBncrMarker } from './marker-parser.ts';
+
+const MEDIA_SOURCE_EXTRA_KEYS = ['path', 'paths', 'mediaUrl', 'mediaUrls'] as const;
+
+export type UnifiedOutboundSendInput = {
+  /** Primary text body (channel text / tool message). */
+  text?: string;
+  message?: string;
+  caption?: string;
+  mediaUrl?: string;
+  media?: string;
+  path?: string;
+  filePath?: string;
+  mediaUrls?: unknown;
+  asVoice: boolean;
+  audioAsVoice: boolean;
+  downloadMedia?: boolean;
+  type?: string;
+  kind?: string;
+  replyToId?: string;
+  replyToMessageId?: string;
+  extra?: Record<string, unknown>;
+  forceDocument?: boolean;
+  gifPlayback?: boolean;
+  silent?: boolean;
+};
+
+export type NormalizedOutboundSend = {
+  markerHasMsg?: boolean;
+  text: string;
+  mediaUrl?: string;
+  mediaUrls?: string[];
+  asVoice: boolean;
+  audioAsVoice: boolean;
+  downloadMedia?: boolean;
+  type?: string;
+  hasMedia?: boolean;
+  extra?: Record<string, unknown>;
+  kind?: 'tool' | 'block' | 'final';
+  replyToId?: string;
+};
+
+function asTrimmedStringList(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const list = value.map((v) => (typeof v === 'string' ? v.trim() : '')).filter(Boolean);
+  return list.length > 0 ? list : undefined;
+}
+
+function normalizeReplyKind(value: unknown): 'tool' | 'block' | 'final' | undefined {
+  return value === 'tool' || value === 'block' || value === 'final' ? value : undefined;
+}
+
+/** Strip media-source keys so they cannot override resolved media frame fields. */
+function stripMediaSourceFieldsFromExtra(
+  extra: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (!extra) return undefined;
+  const next: Record<string, unknown> = { ...extra };
+  for (const key of MEDIA_SOURCE_EXTRA_KEYS) {
+    delete next[key];
+  }
+  return Object.keys(next).length > 0 ? next : undefined;
+}
+
+/**
+ * Build extra for the chosen branch.
+ * - media: strip media-source keys (path already resolved into mediaUrl)
+ * - text: re-inject consumed media type for adapter passthrough when present
+ */
+function buildBranchExtra(args: {
+  hasMedia?: boolean;
+  extra?: Record<string, unknown>;
+  consumedType?: string;
+}): Record<string, unknown> | undefined {
+  if (args.hasMedia) {
+    return stripMediaSourceFieldsFromExtra(args.extra);
+  }
+  const textExtra =
+    args.consumedType && args.extra
+      ? { ...args.extra, type: args.consumedType }
+      : args.consumedType
+        ? { type: args.consumedType }
+        : args.extra
+          ? { ...args.extra }
+          : undefined;
+  return textExtra && Object.keys(textExtra).length > 0 ? textExtra : undefined;
+}
+
+/**
+ * Parse markers from one or more text fields and merge extras.
+ * Marker params always override host/params extra and host control flags.
+ */
+export function mergeMarkerAndHostFields(args: {
+  texts: string[];
+  hostExtra?: Record<string, unknown>;
+  forceDocument?: boolean;
+  gifPlayback?: boolean;
+  silent?: boolean;
+}): {
+  cleanTexts: string[];
+  markerParams: Record<string, unknown>;
+  consumed: Partial<{
+    asVoice: boolean;
+    audioAsVoice: boolean;
+    type: string;
+    kind: string;
+    replyToId: string;
+    downloadMedia: boolean;
+    ismedia: boolean;
+  }>;
+  remaining: Record<string, unknown>;
+  markerHasMsg: boolean;
+} {
+  const markerParams: Record<string, unknown> = {};
+  const cleanTexts: string[] = [];
+
+  for (const raw of args.texts) {
+    const { cleanText, params } = parseBncrMarker(raw);
+    cleanTexts.push(cleanText);
+    Object.assign(markerParams, params);
+  }
+
+  const merged: Record<string, unknown> = {
+    ...(isPlainObject(args.hostExtra) ? { ...args.hostExtra } : {}),
+    ...markerParams,
+  };
+  if (args.forceDocument === true) merged.forceDocument = true;
+  if (args.gifPlayback === true) merged.gifPlayback = true;
+  if (args.silent === true) merged.silent = true;
+
+  // Marker wins over host force* when marker also set them (already via Object.assign order)
+
+  const { consumed, remaining } = extractConsumptionFields(
+    Object.keys(merged).length > 0 ? merged : undefined,
+  );
+
+  return {
+    cleanTexts,
+    markerParams,
+    consumed,
+    remaining,
+    markerHasMsg: typeof markerParams.msg === 'string',
+  };
+}
+
+function resolveHostMediaUrl(input: UnifiedOutboundSendInput): string {
+  return (
+    (typeof input.media === 'string' ? input.media : '') ||
+    (typeof input.path === 'string' ? input.path : '') ||
+    (typeof input.filePath === 'string' ? input.filePath : '') ||
+    (typeof input.mediaUrl === 'string' ? input.mediaUrl : '')
+  );
+}
+
+/**
+ * Resolve media sources after marker merge.
+ * Host mediaUrl/mediaUrls first; marker path/paths next.
+ * Marker path/paths are media evidence unless ismedia is explicitly false.
+ */
+function resolveDispatchMediaSources(args: {
+  hostMediaUrl?: string;
+  hostMediaUrls?: unknown;
+  remainingExtra: Record<string, unknown>;
+  consumedType?: string;
+  /** Tri-state: true=force, false=skip (ismedia explicitly false), undefined=default (path is media evidence). */
+  forceMedia?: boolean;
+}): {
+  mediaUrl?: string;
+  mediaUrls?: string[];
+  hasMedia?: boolean;
+} {
+  const hostMediaUrl = asString(args.hostMediaUrl || '').trim();
+  const markerPath = asString(
+    (args.remainingExtra.path as string) || (args.remainingExtra.mediaUrl as string) || '',
+  ).trim();
+  const markerPaths =
+    asTrimmedStringList(args.remainingExtra.paths) ||
+    asTrimmedStringList(args.remainingExtra.mediaUrls);
+  const useMarkerPath = Boolean(markerPath) && args.forceMedia !== false;
+
+  const singleFromHost = hostMediaUrl || undefined;
+  const multiFromHost = asTrimmedStringList(args.hostMediaUrls);
+  const mediaUrls = multiFromHost || markerPaths;
+  let mediaUrl = singleFromHost || (useMarkerPath ? markerPath : undefined);
+
+  // If mediaUrl is already in mediaUrls, drop single to avoid double-send.
+  if (mediaUrl && mediaUrls?.includes(mediaUrl)) {
+    mediaUrl = undefined;
+  } else if (mediaUrl && mediaUrls?.length) {
+    // Keep both: single + multi as mediaUrls list with single first
+    const merged = [mediaUrl, ...mediaUrls.filter((u) => u !== mediaUrl)];
+    return {
+      mediaUrl: undefined,
+      mediaUrls: merged,
+      hasMedia: true,
+    };
+  }
+
+  const hasMedia = Boolean(mediaUrl || mediaUrls?.length) || args.forceMedia === true;
+  return {
+    mediaUrl,
+    mediaUrls,
+    hasMedia,
+  };
+}
+
+/**
+ * Normalize any outbound send input into a single dispatch shape.
+ * Callers only need to branch on `hasMedia` after this.
+ */
+export function normalizeOutboundSend(input: UnifiedOutboundSendInput): NormalizedOutboundSend {
+  const rawText = asString(input.text ?? input.message ?? '', '');
+  const rawCaption = asString(input.caption ?? '', '');
+  // Prefer text/message; also parse caption so marker in either field works.
+  const textsToParse = rawCaption && rawCaption !== rawText ? [rawText, rawCaption] : [rawText];
+
+  const { cleanTexts, consumed, remaining, markerHasMsg } = mergeMarkerAndHostFields({
+    texts: textsToParse,
+    hostExtra: isPlainObject(input.extra) ? input.extra : undefined,
+    forceDocument: input.forceDocument,
+    gifPlayback: input.gifPlayback,
+    silent: input.silent,
+  });
+
+  const cleanText = cleanTexts[0] || '';
+  const cleanCaption = cleanTexts.length > 1 ? cleanTexts[1] || '' : '';
+
+  const forceMedia = consumed.ismedia;
+  const consumedType = typeof consumed.type === 'string' ? consumed.type : undefined;
+  const hostType = asString(input.type || '').trim() || undefined;
+
+  const media = resolveDispatchMediaSources({
+    hostMediaUrl: resolveHostMediaUrl(input),
+    hostMediaUrls: input.mediaUrls,
+    remainingExtra: remaining,
+    consumedType,
+    forceMedia,
+  });
+
+  const asVoice = typeof consumed.asVoice === 'boolean' ? consumed.asVoice : input.asVoice === true;
+  const audioAsVoice =
+    typeof consumed.audioAsVoice === 'boolean'
+      ? consumed.audioAsVoice
+      : input.audioAsVoice === true;
+  // Tri-state: marker boolean wins; otherwise host value; else undefined (scene cascade).
+  const downloadMedia =
+    typeof consumed.downloadMedia === 'boolean' ? consumed.downloadMedia : input.downloadMedia;
+  const type = consumedType ?? hostType;
+
+  // For media sends: text becomes caption (prefer caption field when both exist).
+  // For text sends: prefer message/text, fall back to caption.
+  const body = media.hasMedia ? cleanCaption || cleanText : cleanText || cleanCaption;
+
+  const kind = normalizeReplyKind(consumed.kind) ?? normalizeReplyKind(input.kind) ?? undefined;
+  const replyToId =
+    asString(consumed.replyToId || input.replyToId || input.replyToMessageId || '').trim() ||
+    undefined;
+
+  const extra = buildBranchExtra({
+    hasMedia: media.hasMedia,
+    extra: Object.keys(remaining).length > 0 ? remaining : undefined,
+    consumedType,
+  });
+
+  return {
+    text: body,
+    markerHasMsg,
+    mediaUrl: media.mediaUrl,
+    mediaUrls: media.mediaUrls,
+    asVoice,
+    audioAsVoice,
+    ...(downloadMedia !== undefined ? { downloadMedia } : {}),
+    ...(type ? { type } : {}),
+    hasMedia: media.hasMedia,
+    ...(extra ? { extra } : {}),
+    ...(kind ? { kind } : {}),
+    ...(replyToId ? { replyToId } : {}),
+  };
+}
+
+/**
+ * Given an already-normalized output, produce the full list of sends.
+ *
+ * When the marker supplies a `msg` field that will override the clean text
+ * body (non-empty `text` different from `extra.msg`), the list includes
+ * the clean text as a standalone text-only entry first, followed by the
+ * main payload.  Otherwise the list contains just the single entry.
+ */
+export function buildNormalizedSends(normalized: NormalizedOutboundSend): NormalizedOutboundSend[] {
+  if (
+    normalized.markerHasMsg &&
+    normalized.text &&
+    typeof normalized.extra?.msg === 'string' &&
+    normalized.extra.msg !== normalized.text
+  ) {
+    return [
+      // Pre-send: clean text only, no media, no extra
+      {
+        text: normalized.text,
+        markerHasMsg: true,
+        hasMedia: false,
+        asVoice: false,
+        audioAsVoice: false,
+        kind: normalized.kind,
+        replyToId: normalized.replyToId,
+      },
+      // Main send: as-is (adapter uses extra.msg as body)
+      normalized,
+    ];
+  }
+
+  return [normalized];
+}

package/src/messaging/outbound/queue-selectors.ts

@@ -1,4 +1,5 @@
 import type { BncrConnection, OutboxEntry } from '../../core/types.ts';
+import { finiteNumberOr } from '../../core/value-sanitize.ts';
 
 export type OutboxRouteSelection = {
   connIds: string[];
@@ -25,11 +26,6 @@ export type OutboxFileTransferRouteSelection = {
   ownerConnId?: string;
 };
 
-function finiteNumberOr(value: unknown, fallback: number): number {
-  const n = Number(value);
-  return Number.isFinite(n) ? n : fallback;
-}
-
 export function computeOutboxRetryWait(nextAttemptAt: number, nowMs: number): number {
   return Math.max(0, finiteNumberOr(nextAttemptAt, 0) - finiteNumberOr(nowMs, 0));
 }

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

@@ -24,6 +24,7 @@ export function enqueueReplyMediaFallbackTextEntry(
       sessionKey: string;
       route: BncrRoute;
       text: string;
+      extra?: Record<string, unknown>;
       kind?: 'tool' | 'block' | 'final';
       replyToId?: string;
       replyTargetPolicy?: OutboundReplyTargetPolicy;
@@ -61,6 +62,7 @@ export function enqueueReplyMediaFileTransferEntry(
       text: string;
       asVoice: boolean;
       audioAsVoice: boolean;
+      downloadMedia?: boolean;
       type?: string;
       extra?: Record<string, unknown>;
       kind?: 'tool' | 'block' | 'final';
@@ -86,6 +88,7 @@ export function enqueueReplyMediaFileTransferEntry(
       text: params.text,
       asVoice: params.asVoice,
       audioAsVoice: params.audioAsVoice,
+      downloadMedia: params.downloadMedia,
       type: params.type,
       extra: params.extra,
       kind: params.kind,
@@ -133,6 +136,7 @@ export function enqueueSingleReplyMediaEntry(
     normalizedText: params.normalizedText,
     asVoice: params.params.payload.asVoice,
     audioAsVoice: params.params.payload.audioAsVoice,
+    downloadMedia: params.params.payload.downloadMedia,
     type: params.params.payload.type,
     extra: params.params.payload.extra,
     kind: params.params.payload.kind,

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

@@ -1,4 +1,5 @@
 import type { BncrRoute, OutboxEntry } from '../../core/types.ts';
+import { buildNormalizedSends, normalizeOutboundSend } from './normalize-outbound-send.ts';
 import { hasReplyMediaEntries } from './reply-enqueue-media.ts';
 import type { OutboundReplyTargetPolicy } from './reply-target-policy.ts';
 import { normalizeOutboundReplyToId } from './reply-target-policy.ts';
@@ -18,7 +19,9 @@ export type ReplyPayloadInput = {
   mediaUrls?: string[];
   asVoice?: boolean;
   audioAsVoice?: boolean;
+  downloadMedia?: boolean;
   type?: string;
+  markerHasMsg?: boolean;
   extra?: Record<string, unknown>;
   kind?: 'tool' | 'block' | 'final';
   replyToId?: string;
@@ -31,7 +34,9 @@ export type NormalizedReplyPayload = {
   mediaList: string[];
   asVoice: boolean;
   audioAsVoice: boolean;
+  downloadMedia?: boolean;
   type?: string;
+  markerHasMsg?: boolean;
   extra?: Record<string, unknown>;
   kind?: 'tool' | 'block' | 'final';
   replyToId: string;
@@ -65,7 +70,9 @@ export type ReplyMediaFileTransferParams = {
   normalizedText: string;
   asVoice: boolean;
   audioAsVoice: boolean;
+  downloadMedia?: boolean;
   type?: string;
+  markerHasMsg?: boolean;
   extra?: Record<string, unknown>;
   kind?: 'tool' | 'block' | 'final';
   replyToId: string;
@@ -93,7 +100,7 @@ export type ReplyMediaFallbackTextEntryParams = {
   fallback: { text: string; reason: string };
 };
 
-export function shouldSplitReplyMediaText(payload: NormalizedReplyPayload) {
+function shouldSplitReplyMediaText(payload: NormalizedReplyPayload) {
   if (!payload.text) return false;
   if (payload.mediaList.length > 1) return true;
   return payload.text.length > MEDIA_TEXT_SPLIT_THRESHOLD;
@@ -111,14 +118,14 @@ export function buildReplyEnqueuePlan(payload: NormalizedReplyPayload): ReplyEnq
   return { kind: 'media-only', clearText: false };
 }
 
-export function withoutReplyMediaText(payload: NormalizedReplyPayload): NormalizedReplyPayload {
+function withoutReplyMediaText(payload: NormalizedReplyPayload): NormalizedReplyPayload {
   return {
     ...payload,
     text: '',
   };
 }
 
-export function buildReplyTextOutboxEntry(
+function buildReplyTextOutboxEntry(
   params: {
     accountId: string;
     sessionKey: string;
@@ -127,6 +134,8 @@ export function buildReplyTextOutboxEntry(
     kind?: 'tool' | 'block' | 'final';
     replyToId: string;
     replyTargetPolicy: OutboundReplyTargetPolicy;
+    markerHasMsg?: boolean;
+    extra?: Record<string, unknown>;
   },
   helpers: {
     buildTextOutboxEntry: (args: {
@@ -137,6 +146,8 @@ export function buildReplyTextOutboxEntry(
       kind?: 'tool' | 'block' | 'final';
       replyToId?: string;
       replyTargetPolicy?: OutboundReplyTargetPolicy;
+      markerHasMsg?: boolean;
+      extra?: Record<string, unknown>;
     }) => OutboxEntry;
   },
 ): OutboxEntry {
@@ -148,6 +159,7 @@ export function buildReplyTextOutboxEntry(
     kind: params.kind,
     replyToId: params.replyToId || undefined,
     replyTargetPolicy: params.replyTargetPolicy,
+    extra: params.extra,
   });
 }
 
@@ -168,10 +180,12 @@ export function enqueueReplyTextEntry(
       kind?: 'tool' | 'block' | 'final';
       replyToId?: string;
       replyTargetPolicy?: OutboundReplyTargetPolicy;
+      markerHasMsg?: boolean;
+      extra?: Record<string, unknown>;
     }) => OutboxEntry;
   },
 ): void {
-  if (!params.payload.text) return;
+  if (!params.payload.text && !params.payload.extra) return;
 
   helpers.enqueueOutbound(
     buildReplyTextOutboxEntry(
@@ -180,6 +194,7 @@ export function enqueueReplyTextEntry(
         sessionKey: params.sessionKey,
         route: params.route,
         text: params.payload.text,
+        extra: params.payload.extra,
         kind: params.payload.kind,
         replyToId: params.payload.replyToId,
         replyTargetPolicy: params.payload.replyTargetPolicy,
@@ -189,15 +204,16 @@ export function enqueueReplyTextEntry(
   );
 }
 
-export function enqueueNormalizedReplyPayload(
+/**
+ * Dispatch all entries from the normalisation plan through a unified path.
+ *
+ * `buildNormalizedSends` returns one or more sends (pre-send text-only +
+ * main payload).  Every entry goes through `buildReplyEnqueuePlan` → the same
+ * text/media dispatch.  There is no separate pre-send or main-send branch.
+ */
+function dispatchNormalizedSends(
   params: EnqueueNormalizedReplyPayloadParams,
   helpers: {
-    logEnqueueFromReply: (args: {
-      accountId: string;
-      sessionKey: string;
-      route: BncrRoute;
-      payload: NormalizedReplyPayload;
-    }) => void;
     enqueueReplyMediaEntries: (params: ReplyMediaEntriesParams) => void;
     enqueueReplyTextEntry: (params: {
       accountId: string;
@@ -207,49 +223,90 @@ export function enqueueNormalizedReplyPayload(
     }) => void;
   },
 ): void {
-  helpers.logEnqueueFromReply({
-    accountId: params.accountId,
-    sessionKey: params.sessionKey,
-    route: params.route,
-    payload: params.payload,
-  });
+  for (const entry of buildNormalizedSends(params.payload)) {
+    // Build a NormalizedReplyPayload from the plan entry.
+    const sendPayload: NormalizedReplyPayload = {
+      text: entry.text,
+      mediaUrl: entry.mediaUrl || '',
+      mediaUrls: entry.mediaUrls,
+      mediaList: entry.mediaUrl ? [entry.mediaUrl] : entry.mediaUrls?.length ? entry.mediaUrls : [],
+      asVoice: entry.asVoice,
+      audioAsVoice: entry.audioAsVoice,
+      downloadMedia: entry.downloadMedia,
+      type: entry.type,
+      extra: entry.extra,
+      kind: entry.kind,
+      replyToId: entry.replyToId ?? '',
+      replyTargetPolicy: params.payload.replyTargetPolicy,
+    };
 
-  const plan = buildReplyEnqueuePlan(params.payload);
+    const plan = buildReplyEnqueuePlan(sendPayload);
 
-  if (plan.kind === 'text-and-media') {
-    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;
-  }
+    if (plan.kind === 'text-and-media') {
+      helpers.enqueueReplyTextEntry({
+        accountId: params.accountId,
+        sessionKey: params.sessionKey,
+        route: params.route,
+        payload: sendPayload,
+      });
+      helpers.enqueueReplyMediaEntries({
+        accountId: params.accountId,
+        sessionKey: params.sessionKey,
+        route: params.route,
+        payload: withoutReplyMediaText(sendPayload),
+        mediaLocalRoots: params.mediaLocalRoots,
+      });
+      continue;
+    }
+
+    if (plan.kind !== 'text-only') {
+      helpers.enqueueReplyMediaEntries({
+        accountId: params.accountId,
+        sessionKey: params.sessionKey,
+        route: params.route,
+        payload: sendPayload,
+        mediaLocalRoots: params.mediaLocalRoots,
+      });
+      continue;
+    }
 
-  if (plan.kind !== 'text-only') {
-    helpers.enqueueReplyMediaEntries({
+    helpers.enqueueReplyTextEntry({
       accountId: params.accountId,
       sessionKey: params.sessionKey,
       route: params.route,
-      payload: params.payload,
-      mediaLocalRoots: params.mediaLocalRoots,
+      payload: sendPayload,
     });
-    return;
   }
+}
 
-  helpers.enqueueReplyTextEntry({
+export function enqueueNormalizedReplyPayload(
+  params: EnqueueNormalizedReplyPayloadParams,
+  helpers: {
+    logEnqueueFromReply: (args: {
+      accountId: string;
+      sessionKey: string;
+      route: BncrRoute;
+      payload: NormalizedReplyPayload;
+    }) => void;
+    enqueueReplyMediaEntries: (params: ReplyMediaEntriesParams) => void;
+    enqueueReplyTextEntry: (params: {
+      accountId: string;
+      sessionKey: string;
+      route: BncrRoute;
+      payload: NormalizedReplyPayload;
+    }) => void;
+  },
+): void {
+  // Log only the main (last) send entry for traceability.
+  helpers.logEnqueueFromReply({
     accountId: params.accountId,
     sessionKey: params.sessionKey,
     route: params.route,
     payload: params.payload,
   });
+
+  // Dispatch ALL entries (pre-send + main) through the same path.
+  dispatchNormalizedSends(params, helpers);
 }
 
 export function normalizeReplyPayload(
@@ -257,27 +314,43 @@ export function normalizeReplyPayload(
   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();
-  const mediaUrls = Array.isArray(payload?.mediaUrls)
-    ? payload.mediaUrls.map((v) => helpers.asString(v || '').trim()).filter(Boolean)
-    : undefined;
-  const type = helpers.asString(payload?.type || '').trim();
-  return {
-    text,
-    mediaUrl,
-    mediaUrls,
-    mediaList: mediaUrls?.length ? mediaUrls : mediaUrl ? [mediaUrl] : [],
+  const normalized = normalizeOutboundSend({
+    text: helpers.asString(payload?.text || ''),
+    mediaUrl: helpers.asString(payload?.mediaUrl || ''),
+    mediaUrls: payload?.mediaUrls,
     asVoice: payload?.asVoice === true,
     audioAsVoice: payload?.audioAsVoice === true,
-    ...(type ? { type } : {}),
-    ...(payload?.extra ? { extra: { ...payload.extra } } : {}),
+    downloadMedia: payload?.downloadMedia,
+    type: helpers.asString(payload?.type || '').trim() || undefined,
     kind: payload?.kind,
-    replyTargetPolicy: options?.replyTargetPolicy ?? 'agent-default',
+    replyToId: payload?.replyToId,
+    extra: payload?.extra,
+  });
+
+  const markerHasMsg = normalized.markerHasMsg === true;
+  const mediaUrl = helpers.asString(normalized.mediaUrl || '');
+  const mediaUrls = normalized.mediaUrls;
+  const mediaList = mediaUrls?.length ? mediaUrls : mediaUrl ? [mediaUrl] : [];
+  const kind = normalized.kind;
+  const replyTargetPolicy = options?.replyTargetPolicy ?? 'agent-default';
+
+  return {
+    text: normalized.text,
+    mediaUrl,
+    mediaUrls,
+    mediaList,
+    asVoice: normalized.asVoice,
+    audioAsVoice: normalized.audioAsVoice,
+    downloadMedia: normalized.downloadMedia,
+    ...(normalized.type ? { type: normalized.type } : {}),
+    ...(normalized.extra ? { extra: normalized.extra } : {}),
+    markerHasMsg,
+    kind,
+    replyTargetPolicy,
     replyToId: normalizeOutboundReplyToId({
-      kind: payload?.kind,
-      replyToId: payload?.replyToId,
-      replyTargetPolicy: options?.replyTargetPolicy,
+      kind,
+      replyToId: normalized.replyToId ?? payload?.replyToId,
+      replyTargetPolicy,
     }),
   };
 }