@xmoxmo/bncr 0.5.5 → 0.5.6

package/src/messaging/outbound/media.ts

@@ -8,11 +8,6 @@ function asString(v: unknown, fallback = ''): string {
   return String(v);
 }
 
-function isAudioMimeType(mimeType?: string): boolean {
-  const mt = asString(mimeType || '').toLowerCase();
-  return mt.startsWith('audio/');
-}
-
 function isBncrOutboundMessageType(value: string): value is BncrOutboundMessageType {
   return (
     value === 'text' ||
@@ -43,11 +38,7 @@ export function resolveBncrOutboundMessageType(params: {
   const isStandard = isBncrOutboundMessageType(hinted);
 
   if (hasPayload && major === 'text' && (hinted === 'text' || !isStandard)) return 'file';
-  if (hinted === 'voice') {
-    if (isAudioMimeType(mt)) return 'voice';
-    if (isMimeMajorOutboundMessageType(major)) return major;
-    return 'file';
-  }
+  if (hinted === 'voice') return 'voice';
   if (isStandard) return hinted;
   if (isMimeMajorOutboundMessageType(major)) return major;
   return 'file';
@@ -61,7 +52,7 @@ export function buildBncrMediaOutboundFrame(params: {
     mode: 'base64' | 'chunk';
     mimeType?: string;
     fileName?: string;
-    mediaBase64?: string;
+    base64?: string;
     path?: string;
   };
   mediaUrl: string;
@@ -87,17 +78,17 @@ export function buildBncrMediaOutboundFrame(params: {
       type: resolveBncrOutboundMessageType({
         mimeType: params.media.mimeType,
         fileName: params.media.fileName,
-        hasPayload: !!(params.media.path || params.media.mediaBase64),
+        hasPayload: !!(params.media.path || params.media.base64),
         hintedType: params.hintedType,
       }),
       kind: params.kind,
       mimeType: params.media.mimeType || '',
       msg: params.mediaMsg,
       path: params.media.path || params.mediaUrl,
-      base64: params.media.mediaBase64 || '',
+      base64: params.media.base64 || '',
       fileName: params.fileName,
       transferMode: params.media.mode,
-      ...(params.extra ? { extra: { ...params.extra } } : {}),
+      ...(params.extra ? { ...params.extra } : {}),
     },
     ts: params.now,
   };

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 { extractConsumptionFields, parseBncrMarker } from './marker-parser.ts';
 import { hasReplyMediaEntries } from './reply-enqueue-media.ts';
 import type { OutboundReplyTargetPolicy } from './reply-target-policy.ts';
 import { normalizeOutboundReplyToId } from './reply-target-policy.ts';
@@ -18,6 +19,7 @@ export type ReplyPayloadInput = {
   mediaUrls?: string[];
   asVoice?: boolean;
   audioAsVoice?: boolean;
+  downloadMedia?: boolean;
   type?: string;
   extra?: Record<string, unknown>;
   kind?: 'tool' | 'block' | 'final';
@@ -31,6 +33,7 @@ export type NormalizedReplyPayload = {
   mediaList: string[];
   asVoice: boolean;
   audioAsVoice: boolean;
+  downloadMedia?: boolean;
   type?: string;
   extra?: Record<string, unknown>;
   kind?: 'tool' | 'block' | 'final';
@@ -65,6 +68,7 @@ export type ReplyMediaFileTransferParams = {
   normalizedText: string;
   asVoice: boolean;
   audioAsVoice: boolean;
+  downloadMedia?: boolean;
   type?: string;
   extra?: Record<string, unknown>;
   kind?: 'tool' | 'block' | 'final';
@@ -127,6 +131,7 @@ export function buildReplyTextOutboxEntry(
     kind?: 'tool' | 'block' | 'final';
     replyToId: string;
     replyTargetPolicy: OutboundReplyTargetPolicy;
+    extra?: Record<string, unknown>;
   },
   helpers: {
     buildTextOutboxEntry: (args: {
@@ -137,6 +142,7 @@ export function buildReplyTextOutboxEntry(
       kind?: 'tool' | 'block' | 'final';
       replyToId?: string;
       replyTargetPolicy?: OutboundReplyTargetPolicy;
+      extra?: Record<string, unknown>;
     }) => OutboxEntry;
   },
 ): OutboxEntry {
@@ -148,6 +154,7 @@ export function buildReplyTextOutboxEntry(
     kind: params.kind,
     replyToId: params.replyToId || undefined,
     replyTargetPolicy: params.replyTargetPolicy,
+    extra: params.extra,
   });
 }
 
@@ -168,10 +175,11 @@ export function enqueueReplyTextEntry(
       kind?: 'tool' | 'block' | 'final';
       replyToId?: string;
       replyTargetPolicy?: OutboundReplyTargetPolicy;
+      extra?: Record<string, unknown>;
     }) => OutboxEntry;
   },
 ): void {
-  if (!params.payload.text) return;
+  if (!params.payload.text && !params.payload.extra) return;
 
   helpers.enqueueOutbound(
     buildReplyTextOutboxEntry(
@@ -180,6 +188,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,
@@ -257,12 +266,24 @@ export function normalizeReplyPayload(
   helpers: { asString: (value: unknown, fallback?: string) => string },
   options?: { replyTargetPolicy?: OutboundReplyTargetPolicy },
 ): NormalizedReplyPayload {
-  const text = helpers.asString(payload?.text || '').trim();
+  const rawText = helpers.asString(payload?.text || '').trim();
+  // Parse [BncrParam:...] marker from reply text
+  const { cleanText, params: markerParams } = parseBncrMarker(rawText);
+  const text = cleanText;
   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();
+  // Merge marker params with payload extra (marker wins), strip consumption fields
+  const mergedExtra: Record<string, unknown> = {
+    ...(payload?.extra ? { ...payload.extra } : {}),
+    ...markerParams,
+  };
+  const { remaining } = extractConsumptionFields(
+    Object.keys(mergedExtra).length > 0 ? mergedExtra : undefined,
+  );
+  const finalExtra = Object.keys(remaining).length > 0 ? remaining : undefined;
   return {
     text,
     mediaUrl,
@@ -270,8 +291,9 @@ export function normalizeReplyPayload(
     mediaList: mediaUrls?.length ? mediaUrls : mediaUrl ? [mediaUrl] : [],
     asVoice: payload?.asVoice === true,
     audioAsVoice: payload?.audioAsVoice === true,
+    downloadMedia: payload?.downloadMedia === true ? true : undefined,
     ...(type ? { type } : {}),
-    ...(payload?.extra ? { extra: { ...payload.extra } } : {}),
+    ...(finalExtra ? { extra: finalExtra } : {}),
     kind: payload?.kind,
     replyTargetPolicy: options?.replyTargetPolicy ?? 'agent-default',
     replyToId: normalizeOutboundReplyToId({

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

@@ -1,5 +1,6 @@
 import { normalizeAccountId } from '../../core/accounts.ts';
 import { readOpenClawBooleanParam, readOpenClawStringParam } from '../../openclaw/sdk-helpers.ts';
+import { extractConsumptionFields, parseBncrMarker } from './marker-parser.ts';
 
 export type NormalizedBncrSendParams = {
   to: string;
@@ -11,6 +12,7 @@ export type NormalizedBncrSendParams = {
   asVoice: boolean;
   audioAsVoice: boolean;
   type?: string;
+  downloadMedia?: boolean;
   extra?: Record<string, unknown>;
 };
 
@@ -28,8 +30,13 @@ export function normalizeBncrSendParams(input: {
     readOpenClawStringParam(paramsObj, 'accountId') ?? input.accountId,
   );
 
-  const message = readOpenClawStringParam(paramsObj, 'message', { allowEmpty: true }) ?? '';
-  const caption = readOpenClawStringParam(paramsObj, 'caption', { allowEmpty: true }) ?? '';
+  const rawMessage = readOpenClawStringParam(paramsObj, 'message', { allowEmpty: true }) ?? '';
+  const rawCaption = readOpenClawStringParam(paramsObj, 'caption', { allowEmpty: true }) ?? '';
+  // Parse [BncrParam:...] markers from message and caption text
+  const { cleanText: parsedMessage, params: msgMarker } = parseBncrMarker(rawMessage);
+  const { cleanText: parsedCaption, params: capMarker } = parseBncrMarker(rawCaption);
+  const message = parsedMessage;
+  const caption = parsedCaption;
   const mediaUrl =
     readOpenClawStringParam(paramsObj, 'media', { trim: false }) ??
     readOpenClawStringParam(paramsObj, 'path', { trim: false }) ??
@@ -53,18 +60,43 @@ export function normalizeBncrSendParams(input: {
   const audioAsVoice = readOpenClawBooleanParam(paramsObj, 'audioAsVoice') ?? false;
   const type = readOpenClawStringParam(paramsObj, 'type') || undefined;
   const rawExtra = paramsObj.extra;
-  const extra = isPlainObject(rawExtra) ? { ...rawExtra } : undefined;
+  const paramsExtra = isPlainObject(rawExtra) ? { ...rawExtra } : {};
+  // Merge marker params into extra (marker takes priority over direct extra)
+  const mergedExtra = { ...paramsExtra, ...msgMarker, ...capMarker };
+  const extra = Object.keys(mergedExtra).length > 0 ? mergedExtra : undefined;
+
+  // Extract consumption fields from merged extra - marker-specified values override params
+  const { consumed, remaining } = extractConsumptionFields(
+    Object.keys(mergedExtra).length > 0 ? mergedExtra : undefined,
+  );
+  const effectiveAsVoice = consumed.asVoice ?? asVoice;
+  const effectiveAudioAsVoice = consumed.audioAsVoice ?? audioAsVoice;
+  const effectiveDownloadMedia = consumed.downloadMedia === true;
+  const effectiveType = consumed.type ?? type;
+  const cleanedExtra = Object.keys(remaining).length > 0 ? remaining : undefined;
 
   const hasMedia = Boolean(mediaUrl || dedupedMediaUrls?.length);
 
-  if (asVoice && !hasMedia) throw new Error('send voice requires media path');
+  if (effectiveAsVoice && !hasMedia) throw new Error('send voice requires media path');
 
   const normalizedMessage = hasMedia ? '' : message || caption || '';
   const normalizedCaption = hasMedia ? caption || message || '' : '';
 
-  if (!normalizedMessage.trim() && !normalizedCaption.trim() && !hasMedia) {
-    throw new Error('send requires message or media');
+  if (!normalizedMessage.trim() && !normalizedCaption.trim() && !hasMedia && !extra) {
+    throw new Error('send requires message, media, or extra params');
   }
+  console.log(
+    '[bncr] normalizeBncrSendParams rawMessage=' +
+      JSON.stringify(rawMessage) +
+      '|msgMarker=' +
+      JSON.stringify(msgMarker) +
+      '|consumed=' +
+      JSON.stringify(consumed) +
+      '|effectiveDownloadMedia=' +
+      effectiveDownloadMedia +
+      '|mediaUrl=' +
+      JSON.stringify(mediaUrl),
+  );
 
   return {
     to,
@@ -73,9 +105,10 @@ export function normalizeBncrSendParams(input: {
     caption: normalizedCaption,
     mediaUrl: dedupedMediaUrls?.length ? undefined : mediaUrl || undefined,
     mediaUrls: dedupedMediaUrls,
-    asVoice,
-    audioAsVoice,
-    ...(type ? { type } : {}),
-    ...(extra ? { extra } : {}),
+    asVoice: effectiveAsVoice,
+    ...(effectiveDownloadMedia ? { downloadMedia: true } : {}),
+    audioAsVoice: effectiveAudioAsVoice,
+    ...(effectiveType ? { type: effectiveType } : {}),
+    ...(cleanedExtra ? { extra: cleanedExtra } : {}),
   };
 }

package/src/messaging/outbound/send.ts

@@ -6,6 +6,7 @@ function normalizeReplyKind(value: unknown): 'tool' | 'block' | 'final' | undefi
 
 export async function sendBncrText(params: {
   channelId: string;
+  extra?: Record<string, unknown>;
   accountId: string;
   to: string;
   text: string;
@@ -26,6 +27,7 @@ export async function sendBncrText(params: {
       mediaUrl?: string;
       mediaUrls?: string[];
       kind?: 'tool' | 'block' | 'final';
+      extra?: Record<string, unknown>;
       replyToId?: string;
     };
     mediaLocalRoots?: readonly string[];
@@ -43,6 +45,7 @@ export async function sendBncrText(params: {
       text: params.text,
       kind: normalizeReplyKind(params.kind),
       replyToId: params.replyToId,
+      extra: params.extra,
     },
     mediaLocalRoots: params.mediaLocalRoots,
   });
@@ -64,6 +67,7 @@ export async function sendBncrMedia(params: {
   asVoice?: boolean;
   audioAsVoice?: boolean;
   type?: string;
+  downloadMedia?: boolean;
   extra?: Record<string, unknown>;
   kind?: string;
   replyToId?: string;
@@ -84,6 +88,7 @@ export async function sendBncrMedia(params: {
       asVoice?: boolean;
       audioAsVoice?: boolean;
       type?: string;
+      downloadMedia?: boolean;
       extra?: Record<string, unknown>;
       kind?: 'tool' | 'block' | 'final';
       replyToId?: string;
@@ -105,6 +110,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,
+      downloadMedia: params.downloadMedia === true ? true : undefined,
       type: params.type,
       extra: params.extra,
       kind: normalizeReplyKind(params.kind),

package/src/plugin/bridge-file-transfer-push-facade.ts

@@ -19,11 +19,12 @@ export function createBncrBridgeFileTransferPushFacade(runtime: {
     route: BncrRoute;
     mediaUrl: string;
     mediaLocalRoots?: readonly string[];
+    downloadMedia?: boolean;
   }) => Promise<{
     mode: 'base64' | 'chunk';
     mimeType?: string;
     fileName?: string;
-    mediaBase64?: string;
+    base64?: string;
     path?: string;
   }>;
   buildFileTransferOutboundFrame: (params: {
@@ -88,6 +89,7 @@ export function createBncrBridgeFileTransferPushFacade(runtime: {
       mediaLocalRoots: Array.isArray(args.meta.mediaLocalRoots)
         ? args.meta.mediaLocalRoots.filter((v): v is string => typeof v === 'string')
         : undefined,
+      downloadMedia: args.meta.downloadMedia === true,
     });
     const frame = runtime.buildFileTransferOutboundFrame({
       entry: args.entry,

package/src/plugin/bridge-media-facade.ts

@@ -48,7 +48,7 @@ export function createBncrBridgeMediaFacade(runtime: {
       mode: 'base64' | 'chunk';
       mimeType?: string;
       fileName?: string;
-      mediaBase64?: string;
+      base64?: string;
       path?: string;
     }>;
   };
@@ -161,6 +161,7 @@ export function createBncrBridgeMediaFacade(runtime: {
   const loadOutboundTransferMedia = async (params: {
     mediaUrl: string;
     mediaLocalRoots?: readonly string[];
+    downloadMedia?: boolean;
   }): Promise<{
     loaded: OpenClawLoadedMedia;
     size: number;

package/src/plugin/channel-plugin-surface-group.ts

@@ -10,6 +10,7 @@ import { normalizeBncrSendParams } from '../messaging/outbound/send-params.ts';
 import type { OpenClawChannelToolSend, openClawJsonResult } from '../openclaw/sdk-helpers.ts';
 import type {
   BncrChannelConfigRoot,
+  BncrSceneRecord,
   BncrStatusRuntimeSnapshot,
   BncrVerifiedTarget,
   ChannelMessageActionAdapter,
@@ -37,6 +38,7 @@ type PluginSurfaceResult = ReturnType<typeof openClawJsonResult>;
 
 export function createBncrChannelPluginSurfaceGroup(runtime: {
   channelId: string;
+  sceneRegistry: Map<string, BncrSceneRecord>;
   getMessageSendBridge: () => {
     channelMessageSendText: (
       ctx: Record<string, unknown>,
@@ -138,6 +140,32 @@ export function createBncrChannelPluginSurfaceGroup(runtime: {
         throw new Error(`Action ${action} is not supported for provider ${runtime.channelId}.`);
       }
       const normalized = normalizeBncrSendParams({ params, accountId: accountId || '' });
+      console.log(
+        '[bncr] handleAction normalized.downloadMedia=' +
+          JSON.stringify(normalized.downloadMedia) +
+          '|mediaUrl=' +
+          JSON.stringify(normalized.mediaUrl) +
+          '|hasMedia=' +
+          Boolean(normalized.mediaUrl || normalized.mediaUrls?.length),
+      );
+
+      // Priority: marker → scene config → global default → false
+      if (normalized.downloadMedia === undefined) {
+        const parts = normalized.to.split(':');
+        if (parts.length >= 3) {
+          const sceneKey = `${parts[1]}:${parts[2]}`;
+          const scene = runtime.sceneRegistry.get(sceneKey);
+          if (scene?.downloadMedia === true) {
+            normalized.downloadMedia = true;
+          }
+          if (normalized.downloadMedia === undefined) {
+            const globalScene = runtime.sceneRegistry.get('__global__');
+            if (globalScene?.downloadMedia === true) {
+              normalized.downloadMedia = true;
+            }
+          }
+        }
+      }
 
       const toolActionBridge = runtime.getToolActionBridge();
       const result =
@@ -152,6 +180,7 @@ export function createBncrChannelPluginSurfaceGroup(runtime: {
               asVoice: normalized.asVoice,
               audioAsVoice: normalized.audioAsVoice,
               type: normalized.type,
+              downloadMedia: normalized.downloadMedia,
               extra: normalized.extra,
               mediaLocalRoots,
               resolveVerifiedTarget: (to, accountId) =>
@@ -166,6 +195,7 @@ export function createBncrChannelPluginSurfaceGroup(runtime: {
               accountId: normalized.accountId,
               to: normalized.to,
               text: normalized.message,
+              extra: normalized.extra,
               mediaLocalRoots,
               resolveVerifiedTarget: (to, accountId) =>
                 toolActionBridge.resolveVerifiedTarget(to, accountId),

package/src/plugin/channel-runtime-builders-delivery.ts

@@ -333,6 +333,7 @@ export function buildBncrMediaOrchestratorsRuntime(deps: {
     sessionKey: string;
     route: BncrRoute;
     text: string;
+    extra?: Record<string, unknown>;
     kind?: 'tool' | 'block' | 'final';
     replyToId?: string;
     replyTargetPolicy?: OutboundReplyTargetPolicy;
@@ -351,6 +352,7 @@ export function buildBncrMediaOrchestratorsRuntime(deps: {
     kind?: 'tool' | 'block' | 'final';
     replyToId?: string;
     replyTargetPolicy?: OutboundReplyTargetPolicy;
+    downloadMedia?: boolean;
   }) => OutboxEntry;
   rememberRecentMediaSend: (args: {
     sessionKey: string;

package/src/plugin/channel-runtime-types.ts

@@ -63,6 +63,7 @@ export type BncrSceneRecord = {
   groupReplyMode?: BncrGroupReplyMode;
   historyLimit?: number;
   historyForce?: boolean;
+  downloadMedia?: boolean;
   lastSeenAt: number;
 };
 
@@ -133,6 +134,13 @@ export type BncrChannelSendContext = {
   sessionKey?: string;
   mirror?: { sessionKey?: string };
   threadId?: string;
+  /** Pass-through fields from host - bncr plugin does NOT consume these. */
+  forceDocument?: boolean;
+  gifPlayback?: boolean;
+  silent?: boolean;
+  downloadMedia?: boolean;
+  /** Extra key-value pairs from marker parsing or direct pass-through. */
+  extra?: Record<string, unknown>;
 };
 
 export type BncrRegisterRuntimeSnapshot = {