@xmoxmo/bncr 0.3.6 → 0.3.8

package/src/plugin/channel-send.ts

@@ -0,0 +1,226 @@
+import { randomUUID } from 'node:crypto';
+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;
+}
+
+export type BncrChannelSendRuntime = {
+  channelId: string;
+  asString: (value: unknown, fallback?: string) => string;
+  syncDebugFlag: () => Promise<void>;
+  logInfo: (scope: string, message: string, options?: Record<string, unknown>) => void;
+  resolveVerifiedTarget: (to: string, accountId: string) => BncrVerifiedTarget;
+  rememberSessionRoute: (sessionKey: string, accountId: string, route: BncrRoute) => void;
+  enqueueFromReply: (args: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    payload: ReplyPayloadInput;
+    mediaLocalRoots?: readonly string[];
+  }) => Promise<void>;
+  listOutboxEntries: () => OutboxEntry[];
+};
+
+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,
+  payload: ReplyPayloadInput,
+) {
+  const accountId = normalizeAccountId(ctx.accountId);
+  const to = runtime.asString(ctx.to || '').trim();
+  const verified = runtime.resolveVerifiedTarget(to, accountId);
+  runtime.rememberSessionRoute(verified.sessionKey, accountId, verified.route);
+  const before = new Set(runtime.listOutboxEntries().map((entry) => entry.messageId));
+  await runtime.enqueueFromReply({
+    accountId,
+    sessionKey: verified.sessionKey,
+    route: verified.route,
+    payload,
+    mediaLocalRoots: ctx.mediaLocalRoots,
+  });
+  const entries = runtime.listOutboxEntries().filter((entry) => !before.has(entry.messageId));
+  if (!entries.length) {
+    throw new Error('bncr channel.message handoff did not enqueue an outbox entry');
+  }
+  return entries[entries.length - 1];
+}
+
+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 || ''),
+        },
+      });
+
+      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(),
+      });
+    },
+
+    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,
+        },
+      });
+
+      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,
+        type,
+        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(),
+      });
+    },
+
+    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 });
+    },
+
+    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 });
+    },
+
+    channelMessageSendPayload: async (ctx: BncrChannelSendContext) => {
+      const payload = ctx?.payload || {};
+      if (!payload || typeof payload !== '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),
+        replyToId:
+          runtime
+            .asString(payload.replyToId || ctx?.replyToId || ctx?.replyToMessageId || '')
+            .trim() || undefined,
+      });
+      return buildBncrDurableQueuedResult({ entry });
+    },
+  };
+}

package/src/plugin/channel-utils.ts

@@ -0,0 +1,102 @@
+import path from 'node:path';
+
+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 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));
+}
+
+function fileExtFromMime(mimeType?: string): string {
+  const mt = asString(mimeType || '').toLowerCase();
+  const map: Record<string, string> = {
+    'image/jpeg': '.jpg',
+    'image/jpg': '.jpg',
+    'image/png': '.png',
+    'image/webp': '.webp',
+    'image/gif': '.gif',
+    'video/mp4': '.mp4',
+    'video/webm': '.webm',
+    'video/quicktime': '.mov',
+    'audio/mpeg': '.mp3',
+    'audio/mp4': '.m4a',
+    'application/pdf': '.pdf',
+    'text/plain': '.txt',
+  };
+  return map[mt] || '';
+}
+
+function sanitizeFileName(rawName?: string, fallback = 'file.bin'): string {
+  const name = asString(rawName || '').trim();
+  const base = name || fallback;
+  const cleaned = Array.from(base, (ch) => {
+    const code = ch.charCodeAt(0);
+    if (code <= 0x1f) return '_';
+    if ('\\/:*?"<>|'.includes(ch)) return '_';
+    return ch;
+  })
+    .join('')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return cleaned || fallback;
+}
+
+function buildTimestampFileName(mimeType?: string): string {
+  const d = new Date();
+  const pad = (n: number) => String(n).padStart(2, '0');
+  const ts = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+  const ext = fileExtFromMime(mimeType) || '.bin';
+  return `bncr_${ts}_${Math.random().toString(16).slice(2, 8)}${ext}`;
+}
+
+export function resolveOutboundFileName(params: {
+  mediaUrl?: string;
+  fileName?: string;
+  mimeType?: string;
+}): string {
+  const mediaUrl = asString(params.mediaUrl || '').trim();
+  const mimeType = asString(params.mimeType || '').trim();
+
+  if (/^https?:\/\//i.test(mediaUrl)) {
+    return buildTimestampFileName(mimeType);
+  }
+
+  const candidate = sanitizeFileName(params.fileName, 'file.bin');
+  if (candidate.length <= 80) return candidate;
+
+  const ext = path.extname(candidate);
+  const stem = candidate.slice(0, Math.max(1, 80 - ext.length));
+  return `${stem}${ext}`;
+}

package/src/plugin/config.ts

@@ -7,10 +7,31 @@ import {
 import { resolveBncrChannelPolicy } from '../core/policy.ts';
 import { setOpenClawAccountEnabledInConfigSection } from '../openclaw/sdk-helpers.ts';
 
+type BncrConfigSurfaceRoot = {
+  channels?: {
+    [CHANNEL_ID]?: {
+      enabled?: boolean;
+      accounts?: Record<string, unknown>;
+    } & Record<string, unknown>;
+  } & Record<string, unknown>;
+};
+
+type BncrConfigSurfaceAccount = {
+  accountId: string;
+  name?: unknown;
+  enabled?: boolean;
+};
+
+type BncrSetAccountEnabledArgs = {
+  cfg: BncrConfigSurfaceRoot;
+  accountId: string;
+  enabled: boolean;
+};
+
 export const BNCR_CONFIG_SURFACE = {
   listAccountIds,
   resolveAccount,
-  setAccountEnabled: ({ cfg, accountId, enabled }: any) =>
+  setAccountEnabled: ({ cfg, accountId, enabled }: BncrSetAccountEnabledArgs) =>
     setOpenClawAccountEnabledInConfigSection({
       cfg,
       sectionKey: CHANNEL_ID,
@@ -18,12 +39,12 @@ export const BNCR_CONFIG_SURFACE = {
       enabled,
       allowTopLevel: true,
     }),
-  isEnabled: (account: any, cfg: any) => {
+  isEnabled: (account: BncrConfigSurfaceAccount, cfg: BncrConfigSurfaceRoot) => {
     const policy = resolveBncrChannelPolicy(cfg?.channels?.[CHANNEL_ID] || {});
     return policy.enabled !== false && account?.enabled !== false;
   },
   isConfigured: () => true,
-  describeAccount: (account: any) => {
+  describeAccount: (account: BncrConfigSurfaceAccount) => {
     const displayName = resolveDefaultDisplayName(account?.name, account?.accountId);
     return {
       accountId: account.accountId,

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

@@ -0,0 +1,254 @@
+import type { FileSendTransferState, OutboxEntry } from '../core/types.ts';
+
+export type LeaseEventPayload = { leaseId?: string; connectionEpoch?: number };
+
+export type ConnectionRuntimeFlags = Record<string, unknown>;
+export type ConnectionQueueCounters = Record<string, unknown>;
+export type ConnectionDiagnostics = Record<string, unknown>;
+
+export type PreparedAckHandling = {
+  accountId: string;
+  connId: string;
+  clientId?: string;
+  messageId: string;
+  entry: OutboxEntry;
+  staleObserved: { stale: boolean };
+};
+
+export type FileAckPayload = {
+  ok: boolean;
+  transferId: string;
+  stage: string;
+  path: string;
+  errorCode: string;
+  errorMessage: string;
+};
+
+type FileAckState = Pick<
+  FileSendTransferState,
+  | 'status'
+  | 'ownerConnId'
+  | 'ownerClientId'
+  | 'error'
+  | 'terminalAt'
+  | 'completedPath'
+  | 'ackedChunks'
+  | 'failedChunks'
+>;
+
+const BNCR_FILE_ACK_STAGES = ['init', 'chunk', 'complete', 'abort'] as const;
+
+export type BncrFileAckStage = (typeof BNCR_FILE_ACK_STAGES)[number];
+
+export function buildConnectionHandlerConnectResponse(args: {
+  channelId: string;
+  accountId: string;
+  bridgeVersion: number;
+  pushEvent: string;
+  online: boolean;
+  isPrimary: boolean;
+  queueCounters: ConnectionQueueCounters;
+  diagnostics: ConnectionDiagnostics;
+  runtimeFlags: ConnectionRuntimeFlags;
+  messageAckWaiters: number;
+  fileAckWaiters: number;
+  leaseId: string;
+  connectionEpoch: number;
+  acceptedAt: number;
+  serverPid: number;
+  bridgeId: string;
+  now: number;
+}) {
+  return {
+    channel: args.channelId,
+    accountId: args.accountId,
+    bridgeVersion: args.bridgeVersion,
+    pushEvent: args.pushEvent,
+    online: args.online,
+    isPrimary: args.isPrimary,
+    ...args.queueCounters,
+    diagnostics: args.diagnostics,
+    runtimeFlags: args.runtimeFlags,
+    waiters: {
+      messageAck: args.messageAckWaiters,
+      fileAck: args.fileAckWaiters,
+    },
+    leaseId: args.leaseId,
+    connectionEpoch: args.connectionEpoch,
+    protocolVersion: 2,
+    acceptedAt: args.acceptedAt,
+    serverPid: args.serverPid,
+    bridgeId: args.bridgeId,
+    now: args.now,
+  };
+}
+
+export function buildConnectionHandlerActivityResponse(args: {
+  accountId: string;
+  queueCounters: ConnectionQueueCounters;
+  now: number;
+}) {
+  return {
+    accountId: args.accountId,
+    ok: true,
+    event: 'activity',
+    ...args.queueCounters,
+    now: args.now,
+  };
+}
+
+export function buildGatewayDebugFields(args: {
+  bridgeId: string;
+  accountId: string;
+  connId: string;
+  clientId?: string;
+  hasContext?: boolean;
+  outboundReady?: boolean;
+  preferredForOutbound?: boolean;
+  inboundOnly?: boolean;
+}) {
+  return {
+    bridge: args.bridgeId,
+    accountId: args.accountId,
+    connId: args.connId,
+    clientId: args.clientId,
+    ...(typeof args.outboundReady === 'boolean' ? { outboundReady: args.outboundReady } : {}),
+    ...(typeof args.preferredForOutbound === 'boolean'
+      ? { preferredForOutbound: args.preferredForOutbound }
+      : {}),
+    ...(typeof args.inboundOnly === 'boolean' ? { inboundOnly: args.inboundOnly } : {}),
+    ...(typeof args.hasContext === 'boolean' ? { hasContext: args.hasContext } : {}),
+  };
+}
+
+export function isBncrFileAckStage(stage: string): stage is BncrFileAckStage {
+  return BNCR_FILE_ACK_STAGES.includes(stage as BncrFileAckStage);
+}
+
+export function resolveFileAckLeaseEventKind(stage: BncrFileAckStage) {
+  if (stage === 'init') return 'file.init';
+  if (stage === 'chunk') return 'file.chunk';
+  if (stage === 'abort') return 'file.abort';
+  return 'file.complete';
+}
+
+export function buildTerminalFileAckResponse(args: {
+  transferId: string;
+  stage: string;
+  state: string;
+  stale: boolean;
+}) {
+  return args.stale
+    ? {
+        ok: true,
+        transferId: args.transferId,
+        stage: args.stage,
+        state: args.state,
+        stale: true,
+        ignored: true,
+        terminal: true,
+      }
+    : {
+        ok: true,
+        transferId: args.transferId,
+        stage: args.stage,
+        state: args.state,
+        ignored: true,
+        terminal: true,
+      };
+}
+
+export function buildHandledFileAckResponse(args: {
+  transferId: string;
+  stage: string;
+  state: string;
+  stale: boolean;
+}) {
+  return args.stale
+    ? {
+        ok: true,
+        transferId: args.transferId,
+        stage: args.stage,
+        state: args.state,
+        stale: true,
+        staleAccepted: true,
+      }
+    : {
+        ok: true,
+        transferId: args.transferId,
+        stage: args.stage,
+        state: args.state,
+      };
+}
+
+export function buildFileAckPayload(args: {
+  ok: boolean;
+  transferId: string;
+  stage: string;
+  path: string;
+  errorCode: string;
+  errorMessage: string;
+}): FileAckPayload {
+  return {
+    ok: args.ok,
+    transferId: args.transferId,
+    stage: args.stage,
+    path: args.path,
+    errorCode: args.errorCode,
+    errorMessage: args.errorMessage,
+  };
+}
+
+export function hasTerminalFileAckState(state: FileAckState | undefined): state is FileAckState {
+  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;
+  ok: boolean;
+  chunkIndex: number | null;
+  now: number;
+  path: string;
+  errorCode: string;
+  errorMessage: string;
+}) {
+  const { transfer, stage, ok, chunkIndex, now, path, errorCode, errorMessage } = args;
+  if (!ok) {
+    transfer.error = `${errorCode || 'ACK_FAILED'}:${errorMessage || 'ack failed'}`;
+    if (stage === 'chunk' && chunkIndex != null) {
+      transfer.failedChunks.set(chunkIndex, transfer.error);
+    }
+    if (stage === 'complete') {
+      transfer.status = 'aborted';
+      transfer.terminalAt = now;
+    }
+    return;
+  }
+
+  if (stage === 'chunk' && chunkIndex != null) {
+    transfer.ackedChunks.add(chunkIndex);
+    transfer.status = 'transferring';
+  }
+
+  if (stage === 'complete') {
+    transfer.status = 'completed';
+    transfer.terminalAt = now;
+    transfer.completedPath = path || transfer.completedPath;
+  }
+}