@xmoxmo/bncr 0.5.5 → 0.5.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmoxmo/bncr",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "private": false,
   "type": "module",
   "license": "MIT",

package/src/channel.ts

@@ -288,6 +288,9 @@ class BncrBridgeRuntime {
     { accountId: string; route: BncrRoute; updatedAt: number }
   >();
   private sceneRegistry = new Map<string, BncrSceneRecord>();
+  getSceneRegistry(): Map<string, BncrSceneRecord> {
+    return this.sceneRegistry;
+  }
   private groupHistories: BncrGroupHistoryMap = new Map();
   private routeAliases = new Map<
     string,
@@ -1186,6 +1189,7 @@ class BncrBridgeRuntime {
     kind?: 'tool' | 'block' | 'final';
     replyToId?: string;
     replyTargetPolicy?: OutboundReplyTargetPolicy;
+    downloadMedia?: boolean;
   }): OutboxEntry {
     return buildFileTransferOutboxEntryFromRuntime({
       createMessageId: () => randomUUID(),
@@ -1205,6 +1209,7 @@ class BncrBridgeRuntime {
       kind: params.kind,
       replyToId: asString(params.replyToId || '').trim() || undefined,
       replyTargetPolicy: params.replyTargetPolicy,
+      downloadMedia: params.downloadMedia === true ? true : undefined,
     });
   }
 
@@ -1222,6 +1227,8 @@ class BncrBridgeRuntime {
     this.mediaDedupeRuntime.rememberRecentMediaSend(params);
   }
 
+  private HTTP_URL_RE = /^https?:\/\//i;
+
   private tryBuildMediaDedupeFallback(params: {
     sessionKey: string;
     mediaUrl: string;
@@ -1229,6 +1236,8 @@ class BncrBridgeRuntime {
     replyToId: string;
     currentTime?: number;
   }): { text: string; reason: 'same-text-sent-checkmark' | 'text-changed-downgrade' } | null {
+    // Only deduplicate local file paths - HTTP URLs bypass dedup
+    if (this.HTTP_URL_RE.test(params.mediaUrl)) return null;
     return this.mediaDedupeRuntime.tryBuildMediaDedupeFallback(params);
   }
 
@@ -1246,6 +1255,17 @@ class BncrBridgeRuntime {
         ? params.meta.messageKind
         : undefined;
 
+    const hasPayload = !!(params.media.base64 || params.media.path);
+    if (hasPayload) {
+      console.log(
+        '[bncr] outbound-media download=true|media=' +
+          (params.media.path || `base64:${(params.media.base64 || '').substring(0, 12)}...`) +
+          '|url=' +
+          params.mediaUrl.split('?')[0],
+      );
+    } else {
+      console.log(`[bncr] outbound-media pass-through|url=${params.mediaUrl.split('?')[0]}`);
+    }
     return buildBncrMediaOutboundFrame({
       messageId: params.entry.messageId,
       sessionKey: params.entry.sessionKey,
@@ -1254,7 +1274,7 @@ class BncrBridgeRuntime {
         mode: params.media.path ? 'chunk' : 'base64',
         mimeType: params.media.mimeType,
         fileName: params.media.fileName,
-        mediaBase64: params.media.base64,
+        base64: params.media.base64,
         path: params.media.path,
       },
       mediaUrl: params.mediaUrl,
@@ -1281,9 +1301,11 @@ class BncrBridgeRuntime {
     sessionKey: string;
     route: BncrRoute;
     text: string;
+    extra?: Record<string, unknown>;
     kind?: 'tool' | 'block' | 'final';
     replyToId?: string;
     replyTargetPolicy?: OutboundReplyTargetPolicy;
+    downloadMedia?: boolean;
   }): OutboxEntry {
     return buildTextOutboxEntryFromRuntime({
       createMessageId: () => randomUUID(),
@@ -1294,9 +1316,11 @@ class BncrBridgeRuntime {
       sessionKey: params.sessionKey,
       route: params.route,
       text: params.text,
+      extra: params.extra && Object.keys(params.extra).length > 0 ? { ...params.extra } : undefined,
       kind: params.kind,
       replyToId: params.replyToId,
       replyTargetPolicy: params.replyTargetPolicy,
+      downloadMedia: params.downloadMedia === true ? true : undefined,
     });
   }
 
@@ -2722,7 +2746,7 @@ class BncrBridgeRuntime {
     mode: 'base64' | 'chunk';
     mimeType?: string;
     fileName?: string;
-    mediaBase64?: string;
+    base64?: string;
     path?: string;
   }> {
     return this.bridgeMediaFacade.transferMediaToBncrClient(params);
@@ -2985,6 +3009,22 @@ class BncrBridgeRuntime {
     await stopBncrStatusWorker(this.buildStatusWorkerRuntime(), ctx);
   };
 
+  /**
+   * Merge host-level outbound fields (forceDocument, gifPlayback, silent)
+   * into extra before dispatching to channel-send runtime.
+   */
+  private mergeHostFields(ctx: BncrChannelSendContext): BncrChannelSendContext {
+    if (!ctx.forceDocument && !ctx.gifPlayback && !ctx.silent) {
+      return ctx;
+    }
+    const extra = { ...(typeof ctx.extra === 'object' && ctx.extra !== null ? ctx.extra : {}) };
+    if (ctx.forceDocument === true) extra.forceDocument = true;
+    if (ctx.gifPlayback === true) extra.gifPlayback = true;
+    if (ctx.silent === true) extra.silent = true;
+    // Clear original fields so resolveUnifiedOutboundExtra doesn't re-add and override marker values
+    return { ...ctx, extra, forceDocument: undefined, gifPlayback: undefined, silent: undefined };
+  }
+
   // Channel send surface assembly ------------------------------------------
   // This group backs the public channel send APIs and should stay adjacent to
   // the final exposed channel* methods for quick top-down scanning.
@@ -2996,19 +3036,19 @@ class BncrBridgeRuntime {
   private readonly channelSendRuntime = this.channelSendRuntimeGroup.channelSendRuntime;
 
   channelSendText = async (ctx: BncrChannelSendContext) =>
-    this.channelSendRuntime.channelSendText(ctx);
+    this.channelSendRuntime.channelSendText(this.mergeHostFields(ctx));
 
   channelSendMedia = async (ctx: BncrChannelSendContext) =>
-    this.channelSendRuntime.channelSendMedia(ctx);
+    this.channelSendRuntime.channelSendMedia(this.mergeHostFields(ctx));
 
   channelMessageSendText = async (ctx: BncrChannelSendContext) =>
-    this.channelSendRuntime.channelMessageSendText(ctx);
+    this.channelSendRuntime.channelMessageSendText(this.mergeHostFields(ctx));
 
   channelMessageSendMedia = async (ctx: BncrChannelSendContext) =>
-    this.channelSendRuntime.channelMessageSendMedia(ctx);
+    this.channelSendRuntime.channelMessageSendMedia(this.mergeHostFields(ctx));
 
   channelMessageSendPayload = async (ctx: BncrChannelSendContext) =>
-    this.channelSendRuntime.channelMessageSendPayload(ctx);
+    this.channelSendRuntime.channelMessageSendPayload(this.mergeHostFields(ctx));
 }
 
 // Plugin surface export -----------------------------------------------------
@@ -3029,6 +3069,7 @@ export function createBncrChannelPlugin(getBridge: () => BncrBridgeRuntime) {
 
   return createBncrChannelPluginSurfaceGroup({
     channelId: CHANNEL_ID,
+    sceneRegistry: getBridge().getSceneRegistry(),
     getMessageSendBridge: bridgeGroup.getMessageSendBridge,
     getOutboundBridge: bridgeGroup.getOutboundBridge,
     getMessagingBridge: bridgeGroup.getMessagingBridge,

package/src/core/outbox-entry-builders.ts

@@ -20,6 +20,7 @@ export function buildFileTransferOutboxEntry(args: {
   kind?: 'tool' | 'block' | 'final';
   replyToId?: string;
   replyTargetPolicy?: OutboundReplyTargetPolicy;
+  downloadMedia?: boolean;
 }): OutboxEntry {
   const messageId = args.createMessageId();
   const createdAt = args.now();
@@ -39,6 +40,7 @@ export function buildFileTransferOutboxEntry(args: {
         asVoice: args.asVoice === true,
         audioAsVoice: args.audioAsVoice === true,
         type: args.type,
+        downloadMedia: args.downloadMedia === true,
         ...(args.extra ? { extra: { ...args.extra } } : {}),
         finalEvent: args.pushEvent,
         replyToId:
@@ -62,12 +64,14 @@ export function buildTextOutboxEntry(args: {
   normalizeAccountId: (accountId?: string | null) => string;
   normalizeReplyToId: (value?: string | null) => string;
   accountId: string;
+  extra?: Record<string, unknown>;
   sessionKey: string;
   route: BncrRoute;
   text: string;
   kind?: 'tool' | 'block' | 'final';
   replyToId?: string;
   replyTargetPolicy?: OutboundReplyTargetPolicy;
+  downloadMedia?: boolean;
 }): OutboxEntry {
   const messageId = args.createMessageId();
   const createdAt = args.now();
@@ -92,6 +96,9 @@ export function buildTextOutboxEntry(args: {
       path: '',
       base64: '',
       fileName: '',
+      // Extra fields from marker/pipeline spread for adapter-specific data
+      // (e.g. type="appmsg", msg="<appmsg>..." from [BncrParam:...])
+      ...(args.extra ? { ...args.extra } : {}),
     },
     ts: createdAt,
   };

package/src/messaging/inbound/native-command.ts

@@ -50,15 +50,18 @@ const BNCR_HELP_TEXT = [
   '  • /bncr deny [<SceneId>]',
   '  • /bncr bind <agentId> [<SceneId>]',
   '  • /bncr mode help',
-  '  • /bncr mode <admin|mention|hybrid|all> [<SceneId>]',
+  '  • /bncr mode <admin|mention|hybrid|all|clear> [<SceneId>]',
   '  • /bncr revoke [<SceneId>]',
   '  • /bncr list pending [filters...]',
   '  • /bncr list scenes [filters...]',
   '',
   '📋 Group history',
   '  • /bncr history-help',
-  '  • /bncr history-limit [<number>] [<SceneId>]',
-  '  • /bncr history-force on|off [<SceneId>]',
+  '  • /bncr history-limit [<number>|clear] [<SceneId>]',
+  '  • /bncr history-force on|off|clear [<SceneId>]',
+  '',
+  '🌐 Remote media',
+  '  • /bncr download-media on|off|clear|default on|off [<SceneId>]',
 ].join('\n');
 
 const BNCR_NATIVE_COMMANDS = new Set([
@@ -77,6 +80,7 @@ const BNCR_NATIVE_COMMANDS = new Set([
   'history-limit',
   'history-help',
   'history-force',
+  'download-media',
 ]);
 
 export const BNCR_DIRECT_ALLOWED_BARE_COMMANDS = new Set([

package/src/messaging/inbound/scene-admin.ts

@@ -13,16 +13,22 @@ export type BncrSceneAdminCommand =
   | { kind: 'bind'; sceneKey?: string; agentId: string }
   | { kind: 'mode-help' }
   | { kind: 'mode-get'; sceneKey?: string }
-  | { kind: 'mode'; sceneKey: string; mode: BncrGroupReplyMode }
+  | { kind: 'mode'; sceneKey: string; mode: string }
   | { kind: 'list'; scope: 'pending' | 'scenes'; filters?: string[] }
   | { kind: 'history-limit-get'; sceneKey?: string }
-  | { kind: 'history-limit-set'; sceneKey: string; limit: number }
+  | { kind: 'history-limit-set'; sceneKey: string; limit: number | 'clear' }
   | { kind: 'history-force-get'; sceneKey?: string }
-  | { kind: 'history-force-set'; sceneKey: string; enabled: boolean }
-  | { kind: 'history-help' };
+  | { kind: 'history-force-set'; sceneKey: string; enabled: boolean | 'clear' }
+  | { kind: 'history-help' }
+  | { kind: 'download-media-get'; sceneKey?: string }
+  | { kind: 'download-media-set'; sceneKey: string; enabled: boolean }
+  | { kind: 'download-media-global-get' }
+  | { kind: 'download-media-global-set'; enabled: boolean };
 
 const GROUP_REPLY_MODES = new Set<BncrGroupReplyMode>(['admin', 'mention', 'hybrid', 'all']);
 
+const GLOBAL_SCENE_KEY = '__global__';
+
 const MODE_HELP_TEXT = [
   '💬 Bncr Group Reply Mode Configuration',
   '',
@@ -122,6 +128,13 @@ export function parseSceneAdminCommand(command: NativeCommand): ParsedSceneAdmin
         return { matched: true, valid: true, command: { kind: 'mode-get' } };
       }
       if (args.length === 1) {
+        if (args[0] === 'clear') {
+          return {
+            matched: true,
+            valid: true,
+            command: { kind: 'mode', sceneKey: '', mode: 'clear' as any },
+          };
+        }
         if (args[0] === 'help') {
           return {
             matched: true,
@@ -142,6 +155,13 @@ export function parseSceneAdminCommand(command: NativeCommand): ParsedSceneAdmin
           command: { kind: 'mode-get', sceneKey: args[0] },
         };
       }
+      if (args[0] === 'clear' && args[1]) {
+        return {
+          matched: true,
+          valid: true,
+          command: { kind: 'mode', sceneKey: args[1], mode: 'clear' as any },
+        };
+      }
       if (GROUP_REPLY_MODES.has(args[0] as BncrGroupReplyMode) && args[1]) {
         return {
           matched: true,
@@ -181,6 +201,13 @@ export function parseSceneAdminCommand(command: NativeCommand): ParsedSceneAdmin
         return { matched: true, valid: true, command: { kind: 'history-limit-get' } };
       }
       if (args.length === 1) {
+        if (args[0] === 'clear') {
+          return {
+            matched: true,
+            valid: true,
+            command: { kind: 'history-limit-set', sceneKey: '', limit: 'clear' as any },
+          };
+        }
         const num = parseInt(args[0], 10);
         if (Number.isFinite(num)) {
           return {
@@ -196,6 +223,13 @@ export function parseSceneAdminCommand(command: NativeCommand): ParsedSceneAdmin
         };
       }
       if (args.length === 2) {
+        if (args[0] === 'clear') {
+          return {
+            matched: true,
+            valid: true,
+            command: { kind: 'history-limit-set', sceneKey: args[1], limit: 'clear' as any },
+          };
+        }
         const num = parseInt(args[0], 10);
         if (Number.isFinite(num)) {
           return {
@@ -214,6 +248,20 @@ export function parseSceneAdminCommand(command: NativeCommand): ParsedSceneAdmin
       if (args.length === 0) {
         return { matched: true, valid: true, command: { kind: 'history-force-get' } };
       }
+      if (args[0] === 'clear') {
+        if (args.length === 1) {
+          return {
+            matched: true,
+            valid: true,
+            command: { kind: 'history-force-set', sceneKey: '', enabled: 'clear' as any },
+          };
+        }
+        return {
+          matched: true,
+          valid: true,
+          command: { kind: 'history-force-set', sceneKey: args[1], enabled: 'clear' as any },
+        };
+      }
       if (args[0] === 'on' || args[0] === 'off') {
         if (args.length === 1) {
           return {
@@ -233,6 +281,50 @@ export function parseSceneAdminCommand(command: NativeCommand): ParsedSceneAdmin
         valid: true,
         command: { kind: 'history-force-get', sceneKey: args[0] },
       };
+    case 'download-media':
+      if (args.length === 0) {
+        return { matched: true, valid: true, command: { kind: 'download-media-get' } };
+      }
+      if (args[0] === 'default') {
+        if (args[1] === 'on' || args[1] === 'off') {
+          return {
+            matched: true,
+            valid: true,
+            command: { kind: 'download-media-global-set', enabled: args[1] === 'on' },
+          };
+        }
+        return { matched: true, valid: true, command: { kind: 'download-media-global-get' } };
+      }
+      if (args[0] === 'clear') {
+        return {
+          matched: true,
+          valid: true,
+          command: {
+            kind: 'download-media-set',
+            sceneKey: args[1] || '',
+            enabled: undefined as any,
+          },
+        };
+      }
+      if (args[0] === 'on' || args[0] === 'off') {
+        if (args.length === 1) {
+          return {
+            matched: true,
+            valid: true,
+            command: { kind: 'download-media-set', sceneKey: '', enabled: args[0] === 'on' },
+          };
+        }
+        return {
+          matched: true,
+          valid: true,
+          command: { kind: 'download-media-set', sceneKey: args[1], enabled: args[0] === 'on' },
+        };
+      }
+      return {
+        matched: true,
+        valid: true,
+        command: { kind: 'download-media-get', sceneKey: args[0] },
+      };
     case 'history-help':
       return { matched: true, valid: true, command: { kind: 'history-help' } };
     default:
@@ -399,6 +491,11 @@ export function executeSceneAdminCommand(args: {
     }
     const sExisting = sceneRegistry.get(sSceneKey);
     if (!sExisting) return { ok: false, text: `Scene not found: ${sSceneKey}` };
+    if (command.limit === 'clear') {
+      const { historyLimit: _, ...rest } = sExisting;
+      sceneRegistry.set(sSceneKey, { ...rest, lastSeenAt: now() });
+      return { ok: true, text: `Cleared ${sSceneKey} history limit. Will use default (50).` };
+    }
     const rawLimit = command.limit;
     if (!Number.isFinite(rawLimit) || Number.isNaN(rawLimit)) {
       return { ok: false, text: 'Invalid number.' };
@@ -443,6 +540,11 @@ export function executeSceneAdminCommand(args: {
     }
     const sExisting = sceneRegistry.get(sSceneKey);
     if (!sExisting) return { ok: false, text: `Scene not found: ${sSceneKey}` };
+    if (command.enabled === 'clear') {
+      const { historyForce: _, ...rest } = sExisting;
+      sceneRegistry.set(sSceneKey, { ...rest, lastSeenAt: now() });
+      return { ok: true, text: `Cleared ${sSceneKey} history auto flush. Will use default (on).` };
+    }
     sceneRegistry.set(sSceneKey, {
       ...sExisting,
       historyForce: command.enabled,
@@ -454,6 +556,75 @@ export function executeSceneAdminCommand(args: {
     };
   }
 
+  if (command.kind === 'download-media-global-get') {
+    const g = sceneRegistry.get(GLOBAL_SCENE_KEY);
+    const enabled = g?.downloadMedia === true;
+    return { ok: true, text: `Global default download remote media is ${enabled ? 'on' : 'off'}.` };
+  }
+
+  if (command.kind === 'download-media-global-set') {
+    const g = sceneRegistry.get(GLOBAL_SCENE_KEY);
+    sceneRegistry.set(GLOBAL_SCENE_KEY, {
+      sceneKey: GLOBAL_SCENE_KEY,
+      kind: 'group',
+      status: 'allowed',
+      ...(g || { platform: 'bncr' }),
+      downloadMedia: command.enabled,
+      lastSeenAt: now(),
+    });
+    return {
+      ok: true,
+      text: `Global default download remote media set to ${command.enabled ? 'on' : 'off'}.`,
+    };
+  }
+
+  if (command.kind === 'download-media-get') {
+    const qSceneKey = command.sceneKey || resolveCurrentGroupSceneKey(parsed);
+    if (!qSceneKey) {
+      return {
+        ok: true,
+        text: `Global default download remote media is ${sceneRegistry.get(GLOBAL_SCENE_KEY)?.downloadMedia === true ? 'on' : 'off'}.`,
+      };
+    }
+    const s = sceneRegistry.get(qSceneKey);
+    if (!s) return { ok: true, text: 'Default download remote media is off.' };
+    const enabled = s.downloadMedia === true;
+    return {
+      ok: true,
+      text: `Current ${qSceneKey} download remote media is ${enabled ? 'on' : 'off'}.`,
+    };
+  }
+
+  if (command.kind === 'download-media-set') {
+    const sSceneKey = command.sceneKey || resolveCurrentGroupSceneKey(parsed);
+    if (!sSceneKey) {
+      return { ok: false, text: 'Current group shortcut only works inside a group chat.' };
+    }
+    const sExisting = sceneRegistry.get(sSceneKey);
+    if (command.enabled === undefined) {
+      // Clear per-group setting
+      if (sExisting) {
+        const { downloadMedia: _, ...rest } = sExisting;
+        sceneRegistry.set(sSceneKey, { ...rest, lastSeenAt: now() });
+        return {
+          ok: true,
+          text: `Cleared ${sSceneKey} download remote media. Will use global default.`,
+        };
+      }
+      return { ok: true, text: `No per-group config to clear for ${sSceneKey}.` };
+    }
+    if (!sExisting) return { ok: false, text: `Scene not found: ${sSceneKey}` };
+    sceneRegistry.set(sSceneKey, {
+      ...sExisting,
+      downloadMedia: command.enabled,
+      lastSeenAt: now(),
+    });
+    return {
+      ok: true,
+      text: `Set ${sSceneKey} download remote media to ${command.enabled ? 'on' : 'off'}.`,
+    };
+  }
+
   const sceneKey = command.sceneKey || resolveCurrentGroupSceneKey(parsed);
   if (!sceneKey) {
     return { ok: false, text: 'Current group shortcut only works inside a group chat.' };
@@ -482,9 +653,14 @@ export function executeSceneAdminCommand(args: {
     if (existing.kind !== 'group') {
       return { ok: false, text: `Scene ${sceneKey} is not a group scene.` };
     }
+    if (command.mode === 'clear') {
+      const { groupReplyMode: _, ...rest } = existing;
+      sceneRegistry.set(sceneKey, { ...rest, lastSeenAt: now() });
+      return { ok: true, text: `Cleared ${sceneKey} reply mode. Will use default (admin).` };
+    }
     sceneRegistry.set(sceneKey, {
       ...existing,
-      groupReplyMode: command.mode,
+      groupReplyMode: command.mode as BncrGroupReplyMode,
       lastSeenAt: now(),
     });
     return { ok: true, text: `Set ${sceneKey} reply mode to ${command.mode}.` };

package/src/messaging/outbound/marker-parser.ts

@@ -0,0 +1,154 @@
+/**
+ * [BncrParam:JSON] marker parser.
+ *
+ * Extracts embedded JSON control parameters from agent text, removes the
+ * marker from the visible message, and returns the parsed key-value pairs.
+ *
+ * Format: [BncrParam:{"key":"val","asVoice":true}]
+ *
+ * Incomplete markers (missing closing ]) are left in text unchanged.
+ * Invalid JSON within a complete marker - marker is removed but no params.
+ */
+
+const PREFIX = '[BncrParam:';
+
+export function parseBncrMarker(text: string): {
+  cleanText: string;
+  params: Record<string, unknown>;
+} {
+  const idx = text.indexOf(PREFIX);
+  if (idx === -1) return { cleanText: text, params: {} };
+
+  const start = idx + PREFIX.length;
+  if (start >= text.length) return { cleanText: text, params: {} };
+
+  // Scan character-by-character tracking brace/bracket depth so that
+  // ] inside JSON values (e.g. CDATA content) is not mistaken for
+  // the closing marker bracket.
+  let depth = 0;
+  let inString = false;
+  let esc = false;
+  let end = -1;
+  let started = false;
+
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+
+    if (esc) {
+      esc = false;
+      continue;
+    }
+    if (ch === '\\' && inString) {
+      esc = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+
+    if (!inString) {
+      if (!started) {
+        if (ch === '{' || ch === '[') {
+          started = true;
+          depth = 1;
+        }
+        continue;
+      }
+
+      if (ch === '{' || ch === '[') {
+        depth++;
+      } else if (ch === '}' || ch === ']') {
+        depth--;
+        if (depth === 0) {
+          // JSON content complete - expect ] to close the marker
+          if (i + 1 < text.length && text[i + 1] === ']') {
+            end = i + 1;
+          }
+          break;
+        }
+      }
+    }
+  }
+
+  if (end === -1) return { cleanText: text, params: {} };
+
+  const rawJson = text.slice(start, end);
+  let params: Record<string, unknown> = {};
+
+  try {
+    const parsed = JSON.parse(rawJson);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      params = parsed as Record<string, unknown>;
+    }
+  } catch {
+    // Invalid JSON — remove marker but don't apply params
+  }
+
+  const cleanText = (text.slice(0, idx) + text.slice(end + 1)).replace(/ {2,}/g, ' ').trim();
+  return { cleanText, params };
+}
+
+/**
+ * Media types that the pipeline internally routes as media sends.
+ * Only these types are consumed (stripped) from extra.
+ * Non-media types like "appmsg" remain in extra for downstream passthrough.
+ */
+const MEDIA_CONSUMPTION_TYPES = new Set(['file', 'image', 'video', 'audio', 'voice']);
+
+/**
+ * Known fields that the bncr plugin unconditionally consumes during outbound
+ * processing. These are stripped from extra at entry and set as independent
+ * pipeline params.  `type` is NOT in this set — it is consumed conditionally
+ * based on whether its value is a recognized media type.
+ */
+const CONSUMPTION_FIELDS_NO_TYPE = new Set([
+  'asVoice',
+  'audioAsVoice',
+  'kind',
+  'replyToId',
+  'downloadMedia',
+]);
+
+const CONSUMPTION_FIELDS = new Set([...CONSUMPTION_FIELDS_NO_TYPE]);
+
+export function extractConsumptionFields(extra: Record<string, unknown> | undefined): {
+  consumed: Partial<{
+    asVoice: boolean;
+    audioAsVoice: boolean;
+    type: string;
+    kind: string;
+    replyToId: string;
+    downloadMedia: boolean;
+  }>;
+  remaining: Record<string, unknown>;
+} {
+  const consumed: Record<string, unknown> = {};
+  const remaining: Record<string, unknown> = {};
+
+  if (!extra) return { consumed: {}, remaining: {} };
+
+  for (const [key, value] of Object.entries(extra)) {
+    // type is only consumed when its value is a recognized media type
+    // (file/image/video/audio/voice).  Non-media types like "appmsg"
+    // stay in remaining for downstream passthrough.
+    if (key === 'type' && typeof value === 'string') {
+      if (MEDIA_CONSUMPTION_TYPES.has(value.trim().toLowerCase())) {
+        consumed[key] = value;
+      } else {
+        remaining[key] = value;
+      }
+      continue;
+    }
+    if (CONSUMPTION_FIELDS.has(key)) {
+      consumed[key] = value;
+    } else {
+      remaining[key] = value;
+    }
+  }
+
+  return {
+    consumed: consumed as Record<string, unknown>,
+    remaining,
+  };
+}