@xmoxmo/bncr 0.5.5 → 0.5.7

package/src/plugin/channel-send.ts

@@ -3,12 +3,38 @@ 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 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';
 
-function normalizeReplyKind(value: unknown): ReplyPayloadInput['kind'] {
-  return value === 'tool' || value === 'block' || value === 'final' ? value : undefined;
+/**
+ * Resolve downloadMedia with cascade: override (host/user) > ctx > scene.
+ * Marker-level downloadMedia is extracted downstream by the orchestrator's
+ * normalisation and has highest priority (overrides whatever we pass).
+ */
+
+/** Override fields shared by sendDispatch and messageSendDispatch. */
+type ChannelSendOverrideFields = {
+  text?: string;
+  mediaUrl?: string;
+  mediaUrls?: unknown;
+  asVoice?: boolean;
+  audioAsVoice?: boolean;
+  downloadMedia?: boolean;
+  type?: string;
+  kind?: string;
+  replyToId?: string;
+};
+
+function resolveDownloadMedia(
+  to: string,
+  overrideValue: boolean | undefined,
+  ctxValue: boolean | undefined,
+  runtime: BncrChannelSendRuntime,
+): boolean | undefined {
+  if (overrideValue !== undefined) return overrideValue;
+  if (ctxValue !== undefined) return ctxValue;
+  return runtime.resolveSceneDownloadMedia?.(to);
 }
 
 export type BncrChannelSendRuntime = {
@@ -26,54 +52,10 @@ export type BncrChannelSendRuntime = {
     mediaLocalRoots?: readonly string[];
   }) => Promise<void>;
   listOutboxEntries: () => OutboxEntry[];
+  /** Resolve downloadMedia from scene config: marker > scene > global > default(false). */
+  resolveSceneDownloadMedia?: (to: string) => boolean | undefined;
 };
 
-function resolveChannelSendReplyToId(
-  asString: BncrChannelSendRuntime['asString'],
-  ctx: BncrChannelSendContext,
-) {
-  return asString(ctx?.replyToId || ctx?.replyToMessageId || '').trim() || undefined;
-}
-
-function logChannelSendEntry(
-  runtime: BncrChannelSendRuntime,
-  args: {
-    kind: 'text' | 'media';
-    accountId: string;
-    to: string;
-    ctx: BncrChannelSendContext;
-    payload: {
-      text: string;
-      mediaUrl: string;
-      mediaUrls?: string[];
-      asVoice?: boolean;
-      audioAsVoice?: boolean;
-    };
-  },
-) {
-  runtime.logInfo(
-    'outbound',
-    buildBncrDebugJsonMessage(`send-entry:${args.kind}`, {
-      accountId: args.accountId,
-      to: args.to,
-      text: args.payload.text,
-      mediaUrl: args.payload.mediaUrl,
-      mediaUrls: args.payload.mediaUrls,
-      asVoice: args.payload.asVoice,
-      audioAsVoice: args.payload.audioAsVoice,
-      sessionKey: runtime.asString(args.ctx?.sessionKey || ''),
-      mirrorSessionKey: runtime.asString(args.ctx?.mirror?.sessionKey || ''),
-      rawCtx: {
-        to: args.ctx?.to,
-        accountId: args.ctx?.accountId,
-        threadId: args.ctx?.threadId,
-        replyToId: args.ctx?.replyToId,
-      },
-    }),
-    { debugOnly: true },
-  );
-}
-
 async function enqueueChannelMessageHandoff(
   runtime: BncrChannelSendRuntime,
   ctx: BncrChannelSendContext,
@@ -98,129 +80,234 @@ async function enqueueChannelMessageHandoff(
   return entries[entries.length - 1];
 }
 
+/**
+ * Resolve downloadMedia from scene config when not already set by marker/host.
+ * Scene cascade: marker > scene config > global > default(false).
+ */
+
 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 || ''),
-        },
-      });
+  /** Extract media-related override fields from a channel send context. */
+  function mediaOverrides(ctx: BncrChannelSendContext) {
+    return {
+      mediaUrl: runtime.asString(ctx.mediaUrl || ''),
+      mediaUrls: ctx.mediaUrls,
+      asVoice: ctx.asVoice === true,
+      audioAsVoice: ctx.audioAsVoice === true,
+      type: runtime.asString(ctx.type || '').trim() || undefined,
+    };
+  }
 
-      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(),
-      });
+  function extractSendFields(
+    ctx: BncrChannelSendContext,
+    overrides?: ChannelSendOverrideFields,
+  ): {
+    accountId: string;
+    to: string;
+    text: string;
+    mediaUrl: string;
+    mediaUrls: unknown;
+    asVoice: boolean;
+    audioAsVoice: boolean;
+    type: string | undefined;
+    kind: unknown;
+    replyToId: string | undefined;
+    extra: Record<string, unknown> | undefined;
+    downloadMedia: boolean | undefined;
+  } {
+    const to = runtime.asString(ctx.to || '').trim();
+
+    // Extract fields from context / overrides WITHOUT normalising markers.
+    // Raw text (with markers) is passed downstream; the orchestrator handles
+    // all normalisation including marker parsing, pre-send, and media routing.
+    const text = overrides?.text !== undefined ? overrides.text : runtime.asString(ctx.text || '');
+    const mediaUrl =
+      overrides?.mediaUrl !== undefined ? overrides.mediaUrl : runtime.asString(ctx.mediaUrl || '');
+    const mediaUrls = overrides?.mediaUrls !== undefined ? overrides.mediaUrls : ctx.mediaUrls;
+    const asVoice = overrides?.asVoice ?? ctx.asVoice === true;
+    const audioAsVoice = overrides?.audioAsVoice ?? ctx.audioAsVoice === true;
+    const type =
+      overrides?.type !== undefined
+        ? overrides.type
+        : runtime.asString(ctx.type || '').trim() || undefined;
+    const kind = overrides?.kind ?? ctx.kind;
+    const replyToId =
+      (overrides?.replyToId ??
+        runtime.asString(ctx.replyToId || ctx.replyToMessageId || '').trim()) ||
+      undefined;
+    const extra =
+      typeof ctx.extra === 'object' && ctx.extra !== null ? { ...ctx.extra } : undefined;
+    const downloadMedia = resolveDownloadMedia(
+      to,
+      overrides?.downloadMedia,
+      ctx.downloadMedia,
+      runtime,
+    );
+
+    return {
+      accountId: normalizeAccountId(ctx.accountId),
+      to,
+      text: text,
+      mediaUrl: mediaUrl,
+      mediaUrls,
+      asVoice,
+      audioAsVoice,
+      type,
+      kind,
+      replyToId,
+      extra,
+      downloadMedia,
+    };
+  }
+
+  /**
+   * Single dispatch path for channelSendText / channelSendMedia.
+   * Both normalize first then branch media vs text via hasMedia.
+   * channelSendMedia passes mediaOverrides(ctx) to ensure media routing,
+   * channelSendText passes no overrides and relies on ctx content alone.
+   */
+  async function sendDispatch(
+    ctx: BncrChannelSendContext,
+    overrides?: {
+      text?: string;
+      mediaUrl?: string;
+      mediaUrls?: unknown;
+      asVoice?: boolean;
+      audioAsVoice?: boolean;
+      downloadMedia?: boolean;
+      type?: string;
+      kind?: string;
+      replyToId?: string;
     },
+  ) {
+    await runtime.syncDebugFlag();
+    const {
+      accountId,
+      to,
+      text,
+      mediaUrl,
+      mediaUrls,
+      asVoice,
+      audioAsVoice,
+      type,
+      kind,
+      replyToId,
+      extra,
+      downloadMedia,
+    } = extractSendFields(ctx, overrides);
 
-    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',
+    runtime.logInfo(
+      'outbound',
+      buildBncrDebugJsonMessage('send-raw', {
         accountId,
         to,
-        ctx,
-        payload: {
-          text: runtime.asString(ctx?.text || ''),
-          mediaUrl: runtime.asString(ctx?.mediaUrl || ''),
-          mediaUrls: Array.isArray(ctx?.mediaUrls) ? ctx.mediaUrls : undefined,
-          asVoice,
-          audioAsVoice,
-        },
-      });
+        textLen: text.length,
+        hasMedia: Boolean(mediaUrl || (Array.isArray(mediaUrls) && mediaUrls.length)),
+        downloadMedia,
+      }),
+      { debugOnly: true },
+    );
 
-      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,
-        asVoice,
-        audioAsVoice,
+    const verified = runtime.resolveVerifiedTarget(to, accountId);
+    runtime.rememberSessionRoute(verified.sessionKey, accountId, verified.route);
+
+    await runtime.enqueueFromReply({
+      accountId,
+      sessionKey: verified.sessionKey,
+      route: verified.route,
+      payload: {
+        text: text,
+        mediaUrl: mediaUrl || undefined,
+        mediaUrls: Array.isArray(mediaUrls) && mediaUrls.length ? mediaUrls : undefined,
+        asVoice: asVoice || undefined,
+        audioAsVoice: audioAsVoice || undefined,
+        downloadMedia,
         type,
-        kind: normalizeReplyKind(ctx?.kind),
+        extra,
+        kind: kind as 'tool' | 'block' | 'final' | undefined,
         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(),
-      });
-    },
+      },
+      mediaLocalRoots: ctx.mediaLocalRoots,
+    });
 
-    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 {
+      channel: runtime.channelId,
+      messageId: randomUUID(),
+      chatId: verified.sessionKey,
+    };
+  }
 
-    channelMessageSendMedia: async (ctx: BncrChannelSendContext) => {
-      const entry = await enqueueChannelMessageHandoff(runtime, ctx, {
-        text: runtime.asString(ctx.text || ''),
-        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,
-        kind: normalizeReplyKind(ctx?.kind),
-        replyToId: resolveChannelSendReplyToId(runtime.asString, ctx),
-      });
-      return buildBncrDurableQueuedResult({ entry });
+  /**
+   * Durable channel.message path: same normalize, then enqueue handoff.
+   */
+  async function messageSendDispatch(
+    ctx: BncrChannelSendContext,
+    overrides?: {
+      text?: string;
+      mediaUrl?: string;
+      mediaUrls?: unknown;
+      asVoice?: boolean;
+      audioAsVoice?: boolean;
+      downloadMedia?: boolean;
+      type?: string;
+      kind?: string;
+      replyToId?: string;
     },
+  ) {
+    const {
+      text,
+      mediaUrl,
+      mediaUrls,
+      asVoice,
+      audioAsVoice,
+      type,
+      kind,
+      replyToId,
+      extra,
+      downloadMedia,
+    } = extractSendFields(ctx, overrides);
+
+    const entry = await enqueueChannelMessageHandoff(runtime, ctx, {
+      text: text,
+      mediaUrl: mediaUrl || '',
+      mediaUrls: Array.isArray(mediaUrls) && mediaUrls.length ? mediaUrls : undefined,
+      asVoice,
+      audioAsVoice,
+      downloadMedia,
+      type,
+      extra,
+      kind: kind as 'tool' | 'block' | 'final' | undefined,
+      replyToId,
+    });
+    return buildBncrDurableQueuedResult({ entry });
+  }
+
+  return {
+    channelSendText: (ctx: BncrChannelSendContext) => sendDispatch(ctx),
+    channelSendMedia: (ctx: BncrChannelSendContext) => sendDispatch(ctx, mediaOverrides(ctx)),
+
+    channelMessageSendText: async (ctx: BncrChannelSendContext) => messageSendDispatch(ctx),
+
+    channelMessageSendMedia: async (ctx: BncrChannelSendContext) =>
+      messageSendDispatch(ctx, mediaOverrides(ctx)),
 
     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 as boolean | undefined,
+        type: runtime.asString(p.type || '').trim() || undefined,
+        kind: typeof p.kind === 'string' ? p.kind : 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/channel-utils.ts

@@ -1,40 +1,19 @@
 import path from 'node:path';
+import {
+  asString,
+  clampFiniteNumber,
+  finiteNumberOr,
+  isPlainObject,
+  now,
+} from '../core/value-sanitize.ts';
 
-export function now() {
-  return Date.now();
-}
-
-export function asString(v: unknown, fallback = ''): string {
-  if (typeof v === 'string') return v;
-  if (v == null) return fallback;
-  return String(v);
-}
-
-export function finiteNumberOr(value: unknown, fallback: number): number {
-  const n = Number(value);
-  return Number.isFinite(n) ? n : fallback;
-}
+export { asString, clampFiniteNumber, finiteNumberOr, isPlainObject, now };
 
 export function finiteNonNegativeNumberOrNull(value: unknown): number | null {
   const n = Number(value);
   return Number.isFinite(n) && n >= 0 ? n : null;
 }
 
-export function clampFiniteNumber(
-  value: unknown,
-  fallback: number,
-  min: number,
-  max: number,
-): number {
-  const n = Number(value);
-  const finite = Number.isFinite(n) ? n : fallback;
-  return Math.max(min, Math.min(finite, max));
-}
-
-export function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 export function backoffMs(retryCount: number): number {
   return Math.max(1_000, 1_000 * 2 ** Math.max(0, retryCount - 1));
 }

package/src/plugin/connection-handlers-helpers.ts

@@ -203,21 +203,6 @@ export function hasTerminalFileAckState(state: FileAckState | undefined): state
   return state?.status === 'completed' || state?.status === 'aborted';
 }
 
-export function matchesTransferOwner(args: {
-  transfer: FileAckState | undefined;
-  connId: string;
-  clientId?: string;
-}) {
-  const { transfer, connId, clientId } = args;
-  const sameConn = !!transfer?.ownerConnId && transfer.ownerConnId === connId;
-  const sameClient =
-    !transfer?.ownerConnId &&
-    !!transfer?.ownerClientId &&
-    !!clientId &&
-    transfer.ownerClientId === clientId;
-  return { sameConn, sameClient };
-}
-
 export function applyFileAckState(args: {
   transfer: FileSendTransferState;
   stage: BncrFileAckStage;

package/src/plugin/connection-handlers.ts

@@ -1,5 +1,6 @@
 import type { GatewayRequestHandlerOptions } from 'openclaw/plugin-sdk/core';
 import { CHANNEL_ID } from '../core/accounts.ts';
+import { matchesTransferOwner } from '../core/lease-state.ts';
 import type { FileSendTransferState } from '../core/types.ts';
 import {
   applyFileAckState,
@@ -16,7 +17,6 @@ import {
   hasTerminalFileAckState,
   isBncrFileAckStage,
   type LeaseEventPayload,
-  matchesTransferOwner,
   type PreparedAckHandling,
   resolveFileAckLeaseEventKind,
 } from './connection-handlers-helpers.ts';
@@ -363,20 +363,21 @@ export function createBncrConnectionHandlers(runtime: BncrConnectionHandlersRunt
       let resolvedState = activeTransfer?.status ?? 'late';
 
       if (staleObserved.stale) {
-        const { sameConn, sameClient } = matchesTransferOwner({
-          transfer: activeTransfer,
+        const sameOwner = matchesTransferOwner({
+          ownerConnId: transferOwnerConnId,
+          ownerClientId: transferOwnerClientId,
           connId,
           clientId,
         });
         const adopted =
-          !(sameConn || sameClient) &&
+          !sameOwner &&
           runtime.tryAdoptTransferOwner({
             accountId,
             transfer: activeTransfer,
             connId,
             clientId,
           });
-        if (!(sameConn || sameClient || adopted)) {
+        if (!sameOwner && !adopted) {
           runtime.logWarn(
             'stale',
             `ignore kind=file.ack accountId=${accountId} connId=${connId} clientId=${clientId || '-'} transferId=${transferId} stage=${stage} reason=owner-mismatch ownerConnId=${transferOwnerConnId || '-'} ownerClientId=${transferOwnerClientId || '-'}`,

package/src/plugin/file-inbound-abort.ts

@@ -59,6 +59,11 @@ export function createBncrFileInboundAbortHandler(runtime: BncrFileInboundRuntim
     }
 
     const staleObserved = runtime.observeLease('file.abort', params ?? {});
+    // #not-merged Intentionally duplicated across complete/chunk/abort.
+    // Each handler emits a distinct logWarn message with its own event-kind
+    // in the format string, and the surrounding logic diverges in more than
+    // just the event name.  Merging would add parameter-gluing boilerplate
+    // with no reduction in total LOC.  See also the sibling files.
     if (staleObserved.stale) {
       if (
         !runtime.matchesTransferOwner({

package/src/plugin/file-inbound-chunk.ts

@@ -78,6 +78,11 @@ export function createBncrFileInboundChunkHandler(runtime: BncrFileInboundRuntim
     }
 
     const staleObserved = runtime.observeLease('file.chunk', params ?? {});
+    // #not-merged Intentionally duplicated across complete/chunk/abort.
+    // Each handler emits a distinct logWarn message with its own event-kind
+    // in the format string, and the surrounding logic diverges in more than
+    // just the event name.  Merging would add parameter-gluing boilerplate
+    // with no reduction in total LOC.  See also the sibling files.
     if (staleObserved.stale) {
       if (
         !runtime.matchesTransferOwner({

package/src/plugin/file-inbound-complete.ts

@@ -63,6 +63,11 @@ export function createBncrFileInboundCompleteHandler(runtime: BncrFileInboundRun
     }
 
     const staleObserved = runtime.observeLease('file.complete', params ?? {});
+    // #not-merged Intentionally duplicated across complete/chunk/abort.
+    // Each handler emits a distinct logWarn message with its own event-kind
+    // in the format string, and the surrounding logic diverges in more than
+    // just the event name.  Merging would add parameter-gluing boilerplate
+    // with no reduction in total LOC.  See also the sibling files.
     if (staleObserved.stale) {
       if (
         !runtime.matchesTransferOwner({