@xmoxmo/bncr 0.5.4 → 0.5.6

package/src/plugin/channel-send.ts

@@ -3,6 +3,7 @@ import { normalizeAccountId } from '../core/accounts.ts';
 import { buildBncrDebugJsonMessage } from '../core/logging.ts';
 import type { BncrRoute, OutboxEntry } from '../core/types.ts';
 import { buildBncrDurableQueuedResult } from '../messaging/outbound/durable-queue-adapter.ts';
+import { extractConsumptionFields, parseBncrMarker } from '../messaging/outbound/marker-parser.ts';
 import type { ReplyPayloadInput } from '../messaging/outbound/reply-enqueue.ts';
 import { sendBncrMedia, sendBncrText } from '../messaging/outbound/send.ts';
 import type { BncrChannelSendContext, BncrVerifiedTarget } from './channel-runtime-types.ts';
@@ -28,6 +29,47 @@ export type BncrChannelSendRuntime = {
   listOutboxEntries: () => OutboxEntry[];
 };
 
+/**
+ * Merge all extra sources (ctx.extra, marker params, host-level fields)
+ * into a single extra bag. Strips consumption fields and returns them
+ * as independent params, remaining extra passes through the pipeline.
+ */
+function resolveUnifiedOutboundExtra(ctx: BncrChannelSendContext): {
+  cleanText: string;
+  extra: Record<string, unknown>;
+  consumed: {
+    asVoice?: boolean;
+    audioAsVoice?: boolean;
+    downloadMedia?: boolean;
+    type?: string;
+    kind?: string;
+    replyToId?: string;
+  };
+} {
+  // 1. Parse marker from text
+  const { cleanText, params: markerParams } = parseBncrMarker(
+    typeof ctx.text === 'string' ? ctx.text : '',
+  );
+
+  // 2. Merge all sources: extra from ctx + marker params + host-level fields
+  const merged: Record<string, unknown> = {
+    ...(typeof ctx.extra === 'object' && ctx.extra !== null ? ctx.extra : {}),
+    ...markerParams,
+  };
+  if (ctx.forceDocument === true) merged.forceDocument = true;
+  if (ctx.gifPlayback === true) merged.gifPlayback = true;
+  if (ctx.silent === true) merged.silent = true;
+
+  // 3. Strip consumption fields
+  const { consumed, remaining } = extractConsumptionFields(merged);
+
+  return {
+    cleanText,
+    extra: remaining,
+    consumed,
+  };
+}
+
 function resolveChannelSendReplyToId(
   asString: BncrChannelSendRuntime['asString'],
   ctx: BncrChannelSendContext,
@@ -48,6 +90,7 @@ function logChannelSendEntry(
       mediaUrls?: string[];
       asVoice?: boolean;
       audioAsVoice?: boolean;
+      downloadMedia?: boolean;
     };
   },
 ) {
@@ -61,6 +104,7 @@ function logChannelSendEntry(
       mediaUrls: args.payload.mediaUrls,
       asVoice: args.payload.asVoice,
       audioAsVoice: args.payload.audioAsVoice,
+      downloadMedia: args.payload.downloadMedia,
       sessionKey: runtime.asString(args.ctx?.sessionKey || ''),
       mirrorSessionKey: runtime.asString(args.ctx?.mirror?.sessionKey || ''),
       rawCtx: {
@@ -78,7 +122,11 @@ async function enqueueChannelMessageHandoff(
   runtime: BncrChannelSendRuntime,
   ctx: BncrChannelSendContext,
   payload: ReplyPayloadInput,
+  extra?: Record<string, unknown>,
 ) {
+  if (extra && Object.keys(extra).length > 0) {
+    payload = { ...payload, extra: { ...extra } };
+  }
   const accountId = normalizeAccountId(ctx.accountId);
   const to = runtime.asString(ctx.to || '').trim();
   const verified = runtime.resolveVerifiedTarget(to, accountId);
@@ -99,128 +147,183 @@ async function enqueueChannelMessageHandoff(
 }
 
 export function createBncrChannelSendRuntime(runtime: BncrChannelSendRuntime) {
-  return {
-    channelSendText: async (ctx: BncrChannelSendContext) => {
-      await runtime.syncDebugFlag();
-      const accountId = normalizeAccountId(ctx.accountId);
-      const to = runtime.asString(ctx.to || '').trim();
-      const replyToId = resolveChannelSendReplyToId(runtime.asString, ctx);
-
-      logChannelSendEntry(runtime, {
-        kind: 'text',
-        accountId,
-        to,
-        ctx,
-        payload: {
-          text: runtime.asString(ctx?.text || ''),
-          mediaUrl: runtime.asString(ctx?.mediaUrl || ''),
-        },
-      });
+  /**
+   * Single dispatch: resolves unified extra (marker + ctx + host fields),
+   * determines text vs media route, and calls the appropriate send function.
+   */
+  async function sendDispatch(ctx: BncrChannelSendContext) {
+    await runtime.syncDebugFlag();
+    const accountId = normalizeAccountId(ctx.accountId);
+    const to = runtime.asString(ctx.to || '').trim();
+    const { cleanText, extra, consumed } = resolveUnifiedOutboundExtra(ctx);
+    const replyToId = resolveChannelSendReplyToId(runtime.asString, ctx);
 
-      return sendBncrText({
-        channelId: runtime.channelId,
-        accountId,
-        to,
-        text: runtime.asString(ctx.text || ''),
-        kind: normalizeReplyKind(ctx?.kind),
-        replyToId,
-        mediaLocalRoots: ctx.mediaLocalRoots,
-        resolveVerifiedTarget: (targetTo, targetAccountId) =>
-          runtime.resolveVerifiedTarget(targetTo, targetAccountId),
-        rememberSessionRoute: (sessionKey, routeAccountId, route) =>
-          runtime.rememberSessionRoute(sessionKey, routeAccountId, route),
-        enqueueFromReply: (args) => runtime.enqueueFromReply(args),
-        createMessageId: () => randomUUID(),
-      });
-    },
+    // Resolve effective media params: ctx.mediaUrl is the source of truth.
+    // extra.path/mediaUrl from marker only triggers media when:
+    //   - it is a local file path (starts with / or ./), OR
+    //   - consumed.type is a known media type (file/image/video/audio)
+    // Otherwise they are treated as metadata (e.g. appmsg thumbnail URL).
+    const ctxMediaUrl = runtime.asString(ctx.mediaUrl || '').trim();
+    const markerPath = runtime
+      .asString((extra.path as string) || (extra.mediaUrl as string) || '')
+      .trim();
+    const isLocalPath =
+      markerPath.startsWith('/') || markerPath.startsWith('./') || markerPath.startsWith('../');
+    const isMediaType = ['file', 'image', 'video', 'audio'].includes(consumed.type || '');
+    const effectiveMediaUrl = ctxMediaUrl || (isLocalPath || isMediaType ? markerPath : '');
+    const effectiveMediaUrls = Array.isArray(ctx?.mediaUrls) ? ctx.mediaUrls : undefined;
+    const asVoice = consumed.asVoice ?? ctx?.asVoice === true;
+    const audioAsVoice = consumed.audioAsVoice ?? ctx?.audioAsVoice === true;
+    const downloadMedia = consumed.downloadMedia ?? ctx?.downloadMedia ?? false;
+    const type = consumed.type ?? (runtime.asString(ctx?.type || '').trim() || undefined);
+    const hasMedia = !!(effectiveMediaUrl || effectiveMediaUrls?.length);
+    console.log(
+      '[bncr] send-dispatch cleanText=' +
+        JSON.stringify(cleanText) +
+        '|downloadMedia=' +
+        JSON.stringify(consumed.downloadMedia) +
+        '|hasMedia=' +
+        hasMedia +
+        '|mediaUrl=' +
+        JSON.stringify(effectiveMediaUrl),
+    );
 
-    channelSendMedia: async (ctx: BncrChannelSendContext) => {
-      await runtime.syncDebugFlag();
-      const accountId = normalizeAccountId(ctx.accountId);
-      const to = runtime.asString(ctx.to || '').trim();
-      const asVoice = ctx?.asVoice === true;
-      const audioAsVoice = ctx?.audioAsVoice === true;
-      const type = runtime.asString(ctx?.type || '').trim() || undefined;
-      const replyToId = resolveChannelSendReplyToId(runtime.asString, ctx);
-
-      logChannelSendEntry(runtime, {
-        kind: 'media',
-        accountId,
-        to,
-        ctx,
-        payload: {
-          text: runtime.asString(ctx?.text || ''),
-          mediaUrl: runtime.asString(ctx?.mediaUrl || ''),
-          mediaUrls: Array.isArray(ctx?.mediaUrls) ? ctx.mediaUrls : undefined,
-          asVoice,
-          audioAsVoice,
-        },
-      });
+    const kind: 'text' | 'media' = hasMedia ? 'media' : 'text';
+    logChannelSendEntry(runtime, {
+      kind,
+      accountId,
+      to,
+      ctx,
+      payload: {
+        text: cleanText,
+        mediaUrl: effectiveMediaUrl,
+        mediaUrls: effectiveMediaUrls,
+        asVoice,
+        audioAsVoice,
+      },
+    });
 
+    if (hasMedia) {
       return sendBncrMedia({
         channelId: runtime.channelId,
         accountId,
         to,
-        text: runtime.asString(ctx.text || ''),
-        mediaUrl: runtime.asString(ctx.mediaUrl || ''),
-        mediaUrls: Array.isArray(ctx?.mediaUrls) ? ctx.mediaUrls : undefined,
+        text: cleanText,
+        mediaUrl: effectiveMediaUrl,
+        mediaUrls: effectiveMediaUrls,
         asVoice,
         audioAsVoice,
+        downloadMedia,
         type,
+        extra: Object.keys(extra).length > 0 ? extra : undefined,
         kind: normalizeReplyKind(ctx?.kind),
         replyToId,
         mediaLocalRoots: ctx.mediaLocalRoots,
-        resolveVerifiedTarget: (targetTo, targetAccountId) =>
-          runtime.resolveVerifiedTarget(targetTo, targetAccountId),
-        rememberSessionRoute: (sessionKey, routeAccountId, route) =>
-          runtime.rememberSessionRoute(sessionKey, routeAccountId, route),
-        enqueueFromReply: (args) => runtime.enqueueFromReply(args),
+        resolveVerifiedTarget: (...a) => runtime.resolveVerifiedTarget(...a),
+        rememberSessionRoute: (...a) => runtime.rememberSessionRoute(...a),
+        enqueueFromReply: (a) => runtime.enqueueFromReply(a),
         createMessageId: () => randomUUID(),
       });
-    },
+    }
 
-    channelMessageSendText: async (ctx: BncrChannelSendContext) => {
-      const entry = await enqueueChannelMessageHandoff(runtime, ctx, {
-        text: runtime.asString(ctx.text || ''),
-        kind: normalizeReplyKind(ctx?.kind),
-        replyToId: resolveChannelSendReplyToId(runtime.asString, ctx),
-      });
-      return buildBncrDurableQueuedResult({ entry });
+    return sendBncrText({
+      channelId: runtime.channelId,
+      accountId,
+      to,
+      text: cleanText,
+      kind: normalizeReplyKind(ctx?.kind),
+      replyToId,
+      extra: Object.keys(extra).length > 0 ? extra : undefined,
+      mediaLocalRoots: ctx.mediaLocalRoots,
+      resolveVerifiedTarget: (...a) => runtime.resolveVerifiedTarget(...a),
+      rememberSessionRoute: (...a) => runtime.rememberSessionRoute(...a),
+      enqueueFromReply: (a) => runtime.enqueueFromReply(a),
+      createMessageId: () => randomUUID(),
+    });
+  }
+
+  /**
+   * Durable dispatch: same logic but enqueues via channel message handoff.
+   */
+  async function messageSendDispatch(
+    ctx: BncrChannelSendContext,
+    inputOverrides?: {
+      text?: string;
+      mediaUrl?: string;
+      mediaUrls?: string[];
+      asVoice?: boolean;
+      audioAsVoice?: boolean;
+      downloadMedia?: boolean;
+      type?: string;
+      kind?: ReplyPayloadInput['kind'];
+      replyToId?: string;
     },
+  ) {
+    // Merge inputOverrides text into ctx so marker parsing sees the effective text
+    const effectiveCtx =
+      inputOverrides?.text !== undefined ? { ...ctx, text: inputOverrides.text } : ctx;
+    const { cleanText, extra, consumed } = resolveUnifiedOutboundExtra(effectiveCtx);
+    const replyToId = resolveChannelSendReplyToId(runtime.asString, ctx);
+
+    console.log(
+      '[bncr] msg-dispatch cleanText=' +
+        JSON.stringify(cleanText) +
+        '|downloadMedia=' +
+        JSON.stringify(consumed.downloadMedia) +
+        '|mediaUrl=' +
+        JSON.stringify(inputOverrides?.mediaUrl),
+    );
+
+    const payload: ReplyPayloadInput = {
+      text: cleanText,
+      mediaUrl: inputOverrides?.mediaUrl || '',
+      mediaUrls: inputOverrides?.mediaUrls,
+      asVoice: consumed.asVoice ?? inputOverrides?.asVoice ?? false,
+      audioAsVoice: consumed.audioAsVoice ?? inputOverrides?.audioAsVoice ?? false,
+      downloadMedia: consumed.downloadMedia ?? inputOverrides?.downloadMedia ?? false,
+      type: consumed.type ?? inputOverrides?.type,
+      kind: normalizeReplyKind(consumed.kind) ?? inputOverrides?.kind,
+      replyToId: inputOverrides?.replyToId || replyToId,
+      ...(Object.keys(extra).length > 0 ? { extra: { ...extra } } : {}),
+    };
+    const entry = await enqueueChannelMessageHandoff(runtime, ctx, payload, extra);
+    return buildBncrDurableQueuedResult({ entry });
+  }
+
+  return {
+    channelSendText: sendDispatch,
+    channelSendMedia: sendDispatch,
 
-    channelMessageSendMedia: async (ctx: BncrChannelSendContext) => {
-      const entry = await enqueueChannelMessageHandoff(runtime, ctx, {
-        text: runtime.asString(ctx.text || ''),
+    channelMessageSendText: async (ctx: BncrChannelSendContext) =>
+      messageSendDispatch(ctx, { kind: normalizeReplyKind(ctx?.kind) }),
+
+    channelMessageSendMedia: async (ctx: BncrChannelSendContext) =>
+      messageSendDispatch(ctx, {
         mediaUrl: runtime.asString(ctx.mediaUrl || ''),
         mediaUrls: Array.isArray(ctx?.mediaUrls) ? ctx.mediaUrls : undefined,
         asVoice: ctx?.asVoice === true,
         audioAsVoice: ctx?.audioAsVoice === true,
-        type: runtime.asString(ctx?.type || '').trim() || undefined,
+        type: runtime.asString(ctx.type || '').trim() || undefined,
         kind: normalizeReplyKind(ctx?.kind),
-        replyToId: resolveChannelSendReplyToId(runtime.asString, ctx),
-      });
-      return buildBncrDurableQueuedResult({ entry });
-    },
+      }),
 
     channelMessageSendPayload: async (ctx: BncrChannelSendContext) => {
-      const payload = ctx?.payload || {};
-      if (!payload || typeof payload !== 'object') {
+      const p = ctx?.payload || {};
+      if (!p || typeof p !== 'object')
         throw new Error('bncr channel.message payload must be an object');
-      }
-      const entry = await enqueueChannelMessageHandoff(runtime, ctx, {
-        text: runtime.asString(payload.text || payload.message || payload.caption || ''),
-        mediaUrl: runtime.asString(payload.mediaUrl || ''),
-        mediaUrls: Array.isArray(payload.mediaUrls) ? payload.mediaUrls : undefined,
-        asVoice: payload.asVoice === true,
-        audioAsVoice: payload.audioAsVoice === true,
-        type: runtime.asString(payload.type || '').trim() || undefined,
-        kind: normalizeReplyKind(payload.kind),
+      return messageSendDispatch(ctx, {
+        text: runtime.asString(p.text || p.message || p.caption || ''),
+        mediaUrl: runtime.asString(p.mediaUrl || ''),
+        mediaUrls: Array.isArray(p.mediaUrls) ? p.mediaUrls : undefined,
+        asVoice: p.asVoice === true,
+        audioAsVoice: p.audioAsVoice === true,
+        downloadMedia: p.downloadMedia === true,
+        type: runtime.asString(p.type || '').trim() || undefined,
+        kind: normalizeReplyKind(p.kind) ?? normalizeReplyKind(ctx?.kind),
         replyToId:
-          runtime
-            .asString(payload.replyToId || ctx?.replyToId || ctx?.replyToMessageId || '')
-            .trim() || undefined,
+          runtime.asString(p.replyToId || ctx?.replyToId || ctx?.replyToMessageId || '').trim() ||
+          undefined,
       });
-      return buildBncrDurableQueuedResult({ entry });
     },
   };
 }

package/src/plugin/file-transfer-orchestrator.ts

@@ -1,6 +1,7 @@
 import { buildFileTransferInitPayload } from '../core/file-transfer-payloads.ts';
 import type { BncrRoute, FileSendTransferState } from '../core/types.ts';
 import { asSanitizedString, clampFiniteNumber } from '../core/value-sanitize.ts';
+import { resolveOutboundFileName } from './channel-utils.ts';
 import type { createBncrFileAckRuntime } from './file-ack-runtime.ts';
 import {
   abortChunkTransfer,
@@ -36,13 +37,13 @@ function getCompletedTransferPath(state?: FileSendTransferState): string | null
 function buildBase64TransferResult(prepared: {
   mimeType?: string;
   fileName?: string;
-  mediaBase64?: string;
+  base64?: string;
 }) {
   return {
     mode: 'base64' as const,
     mimeType: prepared.mimeType,
     fileName: prepared.fileName,
-    mediaBase64: prepared.mediaBase64,
+    base64: prepared.base64,
   };
 }
 
@@ -190,8 +191,96 @@ export function createBncrFileTransferOrchestrator(runtime: BncrFileTransferOrch
 
     return buildChunkTransferResult({ mimeType, fileName, path: done.path });
   };
+  const HTTP_URL_RE = /^https?:\/\//i;
+
+  /** Try HEAD for Content-Type; fall back to Range+sniff for magic bytes when unclear. */
+  async function resolveRemoteMediaType(url: string): Promise<{ mimeType?: string }> {
+    // 1) HEAD -> Content-Type
+    let headerType = '';
+    try {
+      const head = await fetch(url, { method: 'HEAD', signal: AbortSignal.timeout(10_000) });
+      if (head.ok) {
+        const raw = (head.headers.get('content-type') || '').trim().toLowerCase();
+        const parsed = raw.split(';')[0]?.trim() || '';
+        // Accept explicit types; reject octet-stream and generic application/*
+        if (parsed && parsed !== 'application/octet-stream') {
+          headerType = parsed;
+        }
+      }
+    } catch {
+      /* HEAD failed, fall through to Range sniff */
+    }
+
+    if (headerType) return { mimeType: headerType };
+
+    // 2) Range GET -> first 512 bytes -> magic byte sniff
+    try {
+      const range = await fetch(url, {
+        method: 'GET',
+        headers: { Range: 'bytes=0-511' },
+        signal: AbortSignal.timeout(10_000),
+      });
+      // Only accept 206 Partial Content; 200 (no Range support) or other statuses -> fall through
+      if (range.status !== 206) return {};
+      const buf = Buffer.from(await range.arrayBuffer());
+      if (buf.length < 4) return {};
+
+      const sniffed = sniffMimeFromMagic(buf);
+      if (!sniffed) return {};
+      return { mimeType: sniffed };
+    } catch {
+      return {};
+    }
+  }
+
+  /** Minimal magic-byte MIME sniffer for the first ~512 bytes. */
+  function sniffMimeFromMagic(buf: Buffer): string | undefined {
+    const eq = (off: number, ...bytes: number[]) =>
+      bytes.every((b, idx) => off + idx < buf.length && buf[off + idx] === b);
+
+    // JPEG: FF D8 FF
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff)
+      return 'image/jpeg';
+    // PNG: 89 50 4E 47
+    if (eq(0, 0x89, 0x50, 0x4e, 0x47)) return 'image/png';
+    // GIF: 47 49 46 38
+    if (eq(0, 0x47, 0x49, 0x46, 0x38)) return 'image/gif';
+    // WEBP: RIFF .... WEBP
+    if (eq(0, 0x52, 0x49, 0x46, 0x46) && buf.length >= 12 && eq(8, 0x57, 0x45, 0x42, 0x50))
+      return 'image/webp';
+    // BMP: 42 4D
+    if (eq(0, 0x42, 0x4d)) return 'image/bmp';
+    // MP4 / MOV / M4A: ftyp box
+    if (eq(4, 0x66, 0x74, 0x79, 0x70) && buf.length >= 12) {
+      const brand = String.fromCharCode(buf[8], buf[9], buf[10], buf[11]);
+      if (brand === 'M4A ' || brand === 'mp42') return 'audio/mp4';
+      return 'video/mp4';
+    }
+    // MP3: ID3 tag
+    if (eq(0, 0x49, 0x44, 0x33)) return 'audio/mpeg';
+    // MPEG audio sync word
+    if (buf[0] === 0xff && (buf[1] & 0xe0) === 0xe0) return 'audio/mpeg';
+    // OGG: 4F 67 67 53
+    if (eq(0, 0x4f, 0x67, 0x67, 0x53)) return 'audio/ogg';
+    // WAV: RIFF .... WAVE
+    if (eq(0, 0x52, 0x49, 0x46, 0x46) && buf.length >= 12 && eq(8, 0x57, 0x41, 0x56, 0x45))
+      return 'audio/wav';
+    // FLAC: 66 4C 61 43
+    if (eq(0, 0x66, 0x4c, 0x61, 0x43)) return 'audio/flac';
+    // PDF: 25 50 44 46
+    if (eq(0, 0x25, 0x50, 0x44, 0x46)) return 'application/pdf';
+    // WebM/Matroska: 1A 45 DF A3
+    if (eq(0, 0x1a, 0x45, 0xdf, 0xa3)) {
+      for (let i = 0; i < Math.min(buf.length, 200); i++) {
+        if (buf[i] === 0xae) return 'video/webm';
+      }
+      return 'audio/webm';
+    }
+    return undefined;
+  }
 
   const transferMediaToBncrClient = async (params: {
+    downloadMedia?: boolean;
     accountId: string;
     sessionKey: string;
     route: BncrRoute;
@@ -201,9 +290,22 @@ export function createBncrFileTransferOrchestrator(runtime: BncrFileTransferOrch
     mode: 'base64' | 'chunk';
     mimeType?: string;
     fileName?: string;
-    mediaBase64?: string;
+    base64?: string;
     path?: string;
   }> => {
+    // HTTP URL: skip download/chunk, pass URL through to client
+    if (HTTP_URL_RE.test(params.mediaUrl) && !params.downloadMedia) {
+      const { mimeType } = await resolveRemoteMediaType(params.mediaUrl);
+      const fileName = resolveOutboundFileName({
+        mediaUrl: params.mediaUrl,
+        mimeType,
+      });
+      return {
+        mode: 'base64' as const,
+        mimeType,
+        fileName,
+      };
+    }
     const prepared = await runtime.prepareOutboundTransfer({
       accountId: params.accountId,
       sessionKey: params.sessionKey,

package/src/plugin/file-transfer-setup.ts

@@ -116,7 +116,7 @@ export function createBncrFileTransferSetup(runtime: BncrFileTransferSetupRuntim
         mode: 'base64' as const,
         mimeType,
         fileName,
-        mediaBase64: loaded.buffer.toString('base64'),
+        base64: loaded.buffer.toString('base64'),
       };
     }
 

package/src/plugin/media-orchestrators-runtime-group.ts

@@ -53,6 +53,7 @@ function buildReplyMediaEntryHelpers(runtime: {
     kind?: 'tool' | 'block' | 'final';
     replyToId?: string;
     replyTargetPolicy?: OutboundReplyTargetPolicy;
+    downloadMedia?: boolean;
   }) => OutboxEntry;
   rememberRecentMediaSend: (args: {
     sessionKey: string;
@@ -208,6 +209,7 @@ export function createBncrMediaOrchestratorsRuntimeGroup(runtime: {
     kind?: 'tool' | 'block' | 'final';
     replyToId?: string;
     replyTargetPolicy?: OutboundReplyTargetPolicy;
+    downloadMedia?: boolean;
   }) => OutboxEntry;
   rememberRecentMediaSend: (args: {
     sessionKey: string;

package/src/plugin/outbound.ts

@@ -24,6 +24,10 @@ type BncrOutboundSendContext = {
   asVoice?: boolean;
   audioAsVoice?: boolean;
   mediaLocalRoots?: readonly string[];
+  /** Pass-through fields from host — bncr plugin does NOT consume these. */
+  forceDocument?: boolean;
+  gifPlayback?: boolean;
+  silent?: boolean;
 };
 
 type BncrOutboundReplyActionContext = {