@xmoxmo/bncr 0.2.7 → 0.2.8

package/src/core/extended-diagnostics.ts

@@ -2,6 +2,10 @@ import type { RegisterTraceEntry } from './register-trace.ts';
 
 type ExtendedDiagnosticsInput = {
   diagnostics: Record<string, any>;
+  runtimeSurface?: {
+    channel: Record<string, boolean>;
+    missing: string[];
+  };
   register: {
     bridgeId: string;
     gatewayPid: number;
@@ -48,6 +52,12 @@ type ExtendedDiagnosticsInput = {
 export function buildExtendedDiagnostics(input: ExtendedDiagnosticsInput) {
   return {
     ...input.diagnostics,
+    runtimeSurface: input.runtimeSurface
+      ? {
+          channel: { ...input.runtimeSurface.channel },
+          missing: input.runtimeSurface.missing.slice(),
+        }
+      : undefined,
     register: {
       ...input.register,
       traceRecent: input.register.traceRecent.slice(),

package/src/core/file-ack.ts

@@ -0,0 +1,9 @@
+export function buildFileAckKey(args: {
+  transferId: string;
+  stage: string;
+  chunkIndex?: number;
+}): string {
+  const n = Number(args.chunkIndex);
+  const idx = Number.isInteger(n) && n >= 0 ? String(n) : '-';
+  return `${args.transferId}|${args.stage}|${idx}`;
+}

package/src/core/file-transfer-payloads.ts

@@ -0,0 +1,72 @@
+import type { BncrRoute } from './accounts.ts';
+
+export function buildFileTransferInitPayload(args: {
+  transferId: string;
+  sessionKey: string;
+  route: BncrRoute;
+  fileName: string;
+  mimeType?: string;
+  fileSize: number;
+  chunkSize: number;
+  totalChunks: number;
+  fileSha256: string;
+  ts: number;
+}) {
+  return {
+    transferId: args.transferId,
+    direction: 'oc2bncr' as const,
+    sessionKey: args.sessionKey,
+    platform: args.route.platform,
+    groupId: args.route.groupId,
+    userId: args.route.userId,
+    fileName: args.fileName,
+    mimeType: args.mimeType,
+    fileSize: args.fileSize,
+    chunkSize: args.chunkSize,
+    totalChunks: args.totalChunks,
+    fileSha256: args.fileSha256,
+    ts: args.ts,
+  };
+}
+
+export function buildFileTransferChunkPayload(args: {
+  transferId: string;
+  chunkIndex: number;
+  offset: number;
+  size: number;
+  chunkSha256: string;
+  base64: string;
+  ts: number;
+}) {
+  return {
+    transferId: args.transferId,
+    chunkIndex: args.chunkIndex,
+    offset: args.offset,
+    size: args.size,
+    chunkSha256: args.chunkSha256,
+    base64: args.base64,
+    ts: args.ts,
+  };
+}
+
+export function buildFileTransferAbortPayload(args: {
+  transferId: string;
+  reason: string;
+  ts: number;
+}) {
+  return {
+    transferId: args.transferId,
+    reason: args.reason,
+    ts: args.ts,
+  };
+}
+
+export function buildFileTransferCompletePayload(args: {
+  transferId: string;
+  ts: number;
+}) {
+  return {
+    transferId: args.transferId,
+    ts: args.ts,
+  };
+}

package/src/core/register-trace.ts

@@ -33,6 +33,19 @@ export type RegisterTraceSummary = {
   likelyStartupFanoutOnly: boolean;
 };
 
+export type RegisterDriftSnapshot = {
+  capturedAt: number;
+  registerCount: number;
+  apiGeneration: number;
+  postWarmupRegisterCount: number;
+  apiInstanceId: string | null;
+  registryFingerprint: string | null;
+  dominantBucket: string | null;
+  sourceBuckets: Record<string, number>;
+  traceWindowSize: number;
+  traceRecent: Array<Record<string, unknown>>;
+};
+
 export function classifyRegisterTrace(stack: string) {
   if (
     stack.includes('prepareSecretsRuntimeSnapshot') ||
@@ -68,6 +81,72 @@ export function dominantRegisterBucket(sourceBuckets: Record<string, number>) {
   return winner;
 }
 
+export function buildRegisterTraceEntry(args: {
+  ts: number;
+  bridgeId: string;
+  gatewayPid: number;
+  registerCount: number;
+  apiGeneration: number;
+  apiRebound: boolean;
+  apiInstanceId: string | null;
+  registryFingerprint: string | null;
+  source: string | null;
+  pluginVersion: string | null;
+  stack: string;
+}): RegisterTraceEntry {
+  return {
+    ts: args.ts,
+    bridgeId: args.bridgeId,
+    gatewayPid: args.gatewayPid,
+    registerCount: args.registerCount,
+    apiGeneration: args.apiGeneration,
+    apiRebound: args.apiRebound,
+    apiInstanceId: args.apiInstanceId,
+    registryFingerprint: args.registryFingerprint,
+    source: args.source,
+    pluginVersion: args.pluginVersion,
+    stack: args.stack,
+    stackBucket: classifyRegisterTrace(args.stack),
+  };
+}
+
+export function appendBoundedRegisterTrace(
+  traceRecent: RegisterTraceEntry[],
+  trace: RegisterTraceEntry,
+  maxEntries = 12,
+) {
+  traceRecent.push(trace);
+  const cap = Math.max(0, Math.floor(finiteNumberOr(maxEntries, 12)));
+  if (cap === 0) {
+    traceRecent.splice(0, traceRecent.length);
+    return;
+  }
+  if (traceRecent.length > cap) traceRecent.splice(0, traceRecent.length - cap);
+}
+
+export function buildRegisterDriftSnapshot(args: {
+  capturedAt: number;
+  registerCount: number;
+  apiGeneration: number;
+  summary: RegisterTraceSummary;
+  apiInstanceId: string | null;
+  registryFingerprint: string | null;
+  traceRecent: RegisterTraceEntry[];
+}): RegisterDriftSnapshot {
+  return {
+    capturedAt: args.capturedAt,
+    registerCount: args.registerCount,
+    apiGeneration: args.apiGeneration,
+    postWarmupRegisterCount: args.summary.postWarmupRegisterCount,
+    apiInstanceId: args.apiInstanceId,
+    registryFingerprint: args.registryFingerprint,
+    dominantBucket: args.summary.dominantBucket,
+    sourceBuckets: { ...args.summary.sourceBuckets },
+    traceWindowSize: args.traceRecent.length,
+    traceRecent: args.traceRecent.map((trace) => ({ ...trace })),
+  };
+}
+
 export function buildRegisterTraceSummary(args: {
   traceRecent: RegisterTraceEntry[];
   firstRegisterAt: number | null;

package/src/messaging/inbound/runtime-compat.ts

@@ -20,9 +20,11 @@ export function resolveBncrChannelInboundRuntime(api: any): ChannelRuntimeCompat
   if (legacyTurnRuntime?.buildContext && legacyTurnRuntime?.run) {
     if (!warnedLegacyTurnRuntime) {
       warnedLegacyTurnRuntime = true;
+      const channelRuntimeKeys = Object.keys(channelRuntime ?? {}).sort().join(',') || 'none';
+      const inboundRuntimeKeys = Object.keys(inboundRuntime ?? {}).sort().join(',') || 'none';
       emitBncrLogLine(
         'warn',
-        '[bncr] using legacy runtime.channel.turn compatibility path; upgrade path prefers runtime.channel.inbound',
+        `[bncr] inbound runtime fallback=turn|preferred=inbound|channelKeys=${channelRuntimeKeys}|inboundKeys=${inboundRuntimeKeys}`,
       );
     }
     return {

package/src/plugin/capabilities.ts

@@ -0,0 +1,8 @@
+import type { ChatType } from 'openclaw/plugin-sdk';
+
+export const BNCR_CHANNEL_CAPABILITIES = {
+  chatTypes: ['direct'] as ChatType[],
+  media: true,
+  reply: true,
+  nativeCommands: true,
+};

package/src/plugin/config.ts

@@ -0,0 +1,35 @@
+import {
+  CHANNEL_ID,
+  listAccountIds,
+  resolveAccount,
+  resolveDefaultDisplayName,
+} from '../core/accounts.ts';
+import { resolveBncrChannelPolicy } from '../core/policy.ts';
+import { setOpenClawAccountEnabledInConfigSection } from '../openclaw/sdk-helpers.ts';
+
+export const BNCR_CONFIG_SURFACE = {
+  listAccountIds,
+  resolveAccount,
+  setAccountEnabled: ({ cfg, accountId, enabled }: any) =>
+    setOpenClawAccountEnabledInConfigSection({
+      cfg,
+      sectionKey: CHANNEL_ID,
+      accountId,
+      enabled,
+      allowTopLevel: true,
+    }),
+  isEnabled: (account: any, cfg: any) => {
+    const policy = resolveBncrChannelPolicy(cfg?.channels?.[CHANNEL_ID] || {});
+    return policy.enabled !== false && account?.enabled !== false;
+  },
+  isConfigured: () => true,
+  describeAccount: (account: any) => {
+    const displayName = resolveDefaultDisplayName(account?.name, account?.accountId);
+    return {
+      accountId: account.accountId,
+      name: displayName,
+      enabled: account.enabled !== false,
+      configured: true,
+    };
+  },
+};

package/src/plugin/gateway-methods.ts

@@ -0,0 +1,12 @@
+export const BNCR_GATEWAY_METHODS = [
+  'bncr.connect',
+  'bncr.inbound',
+  'bncr.activity',
+  'bncr.ack',
+  'bncr.diagnostics',
+  'bncr.file.init',
+  'bncr.file.chunk',
+  'bncr.file.complete',
+  'bncr.file.abort',
+  'bncr.file.ack',
+];

package/src/plugin/gateway-runtime.ts

@@ -0,0 +1,11 @@
+export type BncrGatewayAccountBridge = {
+  channelStartAccount: (ctx: any) => unknown | Promise<unknown>;
+  channelStopAccount: (ctx: any) => unknown | Promise<unknown>;
+};
+
+export function createBncrGatewayRuntime(getBridge: () => BncrGatewayAccountBridge) {
+  return {
+    startAccount: async (ctx: any) => getBridge().channelStartAccount(ctx),
+    stopAccount: async (ctx: any) => getBridge().channelStopAccount(ctx),
+  };
+}

package/src/plugin/message-policy.ts

@@ -0,0 +1,4 @@
+export const BNCR_MESSAGE_RECEIVE_POLICY = {
+  defaultAckPolicy: 'manual' as const,
+  supportedAckPolicies: ['manual'] as const,
+};

package/src/plugin/message-send.ts

@@ -0,0 +1,13 @@
+export type BncrMessageSendBridge = {
+  channelMessageSendText: (ctx: any) => unknown | Promise<unknown>;
+  channelMessageSendMedia: (ctx: any) => unknown | Promise<unknown>;
+  channelMessageSendPayload: (ctx: any) => unknown | Promise<unknown>;
+};
+
+export function createBncrMessageSend(getBridge: () => BncrMessageSendBridge) {
+  return {
+    text: async (ctx: any) => getBridge().channelMessageSendText(ctx),
+    media: async (ctx: any) => getBridge().channelMessageSendMedia(ctx),
+    payload: async (ctx: any) => getBridge().channelMessageSendPayload(ctx),
+  };
+}

package/src/plugin/messaging.ts

@@ -0,0 +1,142 @@
+import { BNCR_DEFAULT_ACCOUNT_ID, normalizeAccountId } from '../core/accounts.ts';
+import {
+  formatDisplayScope,
+  formatTargetDisplay,
+  parseExplicitTarget,
+} from '../core/targets.ts';
+import { resolveBncrOutboundSessionRoute } from '../messaging/outbound/session-route.ts';
+import {
+  looksLikeBncrExplicitTarget,
+  resolveBncrOutboundTarget,
+} from '../messaging/outbound/target-resolver.ts';
+
+type BncrMessagingRuntimeBridge = {
+  canonicalAgentId?: string;
+  ensureCanonicalAgentId: (params: { cfg: any; accountId: string }) => string;
+  resolveRouteBySession: (raw: string, accountId: string) => any;
+};
+
+function asString(v: unknown, fallback = ''): string {
+  return typeof v === 'string' ? v : fallback;
+}
+
+export function normalizeBncrMessagingTarget(raw: string) {
+  const input = asString(raw).trim();
+  return input || undefined;
+}
+
+export function formatBncrMessagingTargetDisplay({ target }: any) {
+  return formatTargetDisplay(target);
+}
+
+function resolveMessagingAccountId(accountId: unknown) {
+  return normalizeAccountId(asString(accountId || BNCR_DEFAULT_ACCOUNT_ID));
+}
+
+function resolveMessagingCanonicalAgentId(
+  runtimeBridge: BncrMessagingRuntimeBridge,
+  cfg: any,
+  accountId: string,
+) {
+  return (
+    runtimeBridge.canonicalAgentId ||
+    runtimeBridge.ensureCanonicalAgentId({ cfg, accountId })
+  );
+}
+
+export function createBncrMessagingExplicitTargetParser(
+  getBridge: () => BncrMessagingRuntimeBridge,
+) {
+  return ({ raw, accountId, cfg }: any) => {
+    const resolvedAccountId = resolveMessagingAccountId(accountId);
+    const runtimeBridge = getBridge();
+    const canonicalAgentId = resolveMessagingCanonicalAgentId(
+      runtimeBridge,
+      cfg,
+      resolvedAccountId,
+    );
+    return parseExplicitTarget(asString(raw).trim(), { canonicalAgentId });
+  };
+}
+
+export function createBncrMessagingSessionTargetResolver(
+  getBridge: () => BncrMessagingRuntimeBridge,
+) {
+  return ({ id, accountId, cfg }: any) => {
+    const raw = asString(id).trim();
+    if (!raw) return undefined;
+    const resolvedAccountId = resolveMessagingAccountId(accountId);
+    const runtimeBridge = getBridge();
+    const canonicalAgentId = resolveMessagingCanonicalAgentId(
+      runtimeBridge,
+      cfg,
+      resolvedAccountId,
+    );
+
+    let parsed = parseExplicitTarget(raw, { canonicalAgentId });
+    if (!parsed) {
+      const route = runtimeBridge.resolveRouteBySession(raw, resolvedAccountId);
+      if (route) {
+        parsed = parseExplicitTarget(formatDisplayScope(route), { canonicalAgentId });
+      }
+    }
+    return parsed?.displayScope || undefined;
+  };
+}
+
+export function createBncrMessagingOutboundSessionRouteResolver(
+  getBridge: () => BncrMessagingRuntimeBridge,
+) {
+  return (params: any) => {
+    const accountId = resolveMessagingAccountId(params?.accountId);
+    const runtimeBridge = getBridge();
+    const canonicalAgentId = resolveMessagingCanonicalAgentId(
+      runtimeBridge,
+      params?.cfg,
+      accountId,
+    );
+    return resolveBncrOutboundSessionRoute({
+      ...params,
+      canonicalAgentId,
+      resolveRouteBySession: (raw: string, acc: string) =>
+        runtimeBridge.resolveRouteBySession(raw, acc),
+    });
+  };
+}
+
+export function createBncrMessagingSurface(getBridge: () => BncrMessagingRuntimeBridge) {
+  return {
+    // 接收任意标签输入；不在 normalize 阶段做格式门槛，统一下沉到发送前验证。
+    normalizeTarget: normalizeBncrMessagingTarget,
+    parseExplicitTarget: createBncrMessagingExplicitTargetParser(getBridge),
+    formatTargetDisplay: formatBncrMessagingTargetDisplay,
+    resolveSessionTarget: createBncrMessagingSessionTargetResolver(getBridge),
+    resolveOutboundSessionRoute: createBncrMessagingOutboundSessionRouteResolver(getBridge),
+    targetResolver: createBncrMessagingTargetResolver(getBridge),
+  };
+}
+
+export function createBncrMessagingTargetResolver(getBridge: () => BncrMessagingRuntimeBridge) {
+  return {
+    looksLikeId: (raw: string, normalized?: string) => {
+      return looksLikeBncrExplicitTarget(asString(normalized || raw).trim());
+    },
+    resolveTarget: async ({ accountId, input, normalized }: any) => {
+      const runtimeBridge = getBridge();
+      const resolved = resolveBncrOutboundTarget({
+        target: asString(normalized || input).trim(),
+        accountId: resolveMessagingAccountId(accountId),
+        resolveRouteBySession: (raw: string, acc: string) =>
+          runtimeBridge.resolveRouteBySession(raw, acc),
+      });
+      if (!resolved) return null;
+      return {
+        to: resolved.displayScope,
+        kind: resolved.kind,
+        display: resolved.displayScope,
+        source: 'normalized' as const,
+      };
+    },
+    hint: 'Standard to=Bncr:<platform>:<group>:<user> or Bncr:<platform>:<user>; sessionKey keeps existing strict/legacy compatibility, canonical sessionKey=agent:<agentId>:bncr:direct:<hex>',
+  };
+}

package/src/plugin/meta.ts

@@ -0,0 +1,10 @@
+import { CHANNEL_ID } from '../core/accounts.ts';
+
+export const BNCR_CHANNEL_META = {
+  id: CHANNEL_ID,
+  label: 'Bncr',
+  selectionLabel: 'Bncr Client',
+  docsPath: '/channels/bncr',
+  blurb: 'Bncr Channel.',
+  aliases: ['bncr'],
+};

package/src/plugin/outbound.ts

@@ -0,0 +1,51 @@
+import { normalizeAccountId } from '../core/accounts.ts';
+import {
+  deleteBncrMessageAction,
+  editBncrMessageAction,
+  reactBncrMessageAction,
+  sendBncrReplyAction,
+} from '../messaging/outbound/actions.ts';
+
+function asString(v: unknown, fallback = ''): string {
+  return typeof v === 'string' ? v : v == null ? fallback : String(v);
+}
+
+export type BncrOutboundBridge = {
+  channelSendText: (ctx: any) => unknown | Promise<unknown>;
+  channelSendMedia: (ctx: any) => unknown | Promise<unknown>;
+};
+
+export function createBncrOutboundRuntime(getBridge: () => BncrOutboundBridge) {
+  return {
+    deliveryMode: 'gateway' as const,
+    sendText: async (ctx: any) => getBridge().channelSendText(ctx),
+    sendMedia: async (ctx: any) => getBridge().channelSendMedia(ctx),
+    replyAction: async (ctx: any) =>
+      sendBncrReplyAction({
+        accountId: normalizeAccountId(ctx?.accountId),
+        to: asString(ctx?.to || '').trim(),
+        text: asString(ctx?.text || ''),
+        replyToMessageId:
+          asString(ctx?.replyToId || ctx?.replyToMessageId || '').trim() || undefined,
+        sendText: async ({ accountId, to, text }) =>
+          getBridge().channelSendText({ accountId, to, text }),
+      }),
+    deleteAction: async (ctx: any) =>
+      deleteBncrMessageAction({
+        accountId: normalizeAccountId(ctx?.accountId),
+        targetMessageId: asString(ctx?.messageId || ctx?.targetMessageId || '').trim(),
+      }),
+    reactAction: async (ctx: any) =>
+      reactBncrMessageAction({
+        accountId: normalizeAccountId(ctx?.accountId),
+        targetMessageId: asString(ctx?.messageId || ctx?.targetMessageId || '').trim(),
+        emoji: asString(ctx?.emoji || '').trim(),
+      }),
+    editAction: async (ctx: any) =>
+      editBncrMessageAction({
+        accountId: normalizeAccountId(ctx?.accountId),
+        targetMessageId: asString(ctx?.messageId || ctx?.targetMessageId || '').trim(),
+        text: asString(ctx?.text || ''),
+      }),
+  };
+}

package/src/plugin/setup.ts

@@ -0,0 +1,24 @@
+import { CHANNEL_ID } from '../core/accounts.ts';
+import { applyOpenClawAccountNameToChannelSection } from '../openclaw/sdk-helpers.ts';
+
+export const BNCR_SETUP_SURFACE = {
+  applyAccountName: ({ cfg, accountId, name }: any) =>
+    applyOpenClawAccountNameToChannelSection({
+      cfg,
+      channelKey: CHANNEL_ID,
+      accountId,
+      name,
+      alwaysUseAccounts: true,
+    }),
+  applyAccountConfig: ({ cfg, accountId }: any) => {
+    const next = { ...(cfg || {}) } as any;
+    next.channels = next.channels || {};
+    next.channels[CHANNEL_ID] = next.channels[CHANNEL_ID] || {};
+    next.channels[CHANNEL_ID].accounts = next.channels[CHANNEL_ID].accounts || {};
+    next.channels[CHANNEL_ID].accounts[accountId] = {
+      ...(next.channels[CHANNEL_ID].accounts[accountId] || {}),
+      enabled: true,
+    };
+    return next;
+  },
+};

package/src/plugin/status.ts

@@ -0,0 +1,38 @@
+import { BNCR_DEFAULT_ACCOUNT_ID, resolveAccount, resolveDefaultDisplayName } from '../core/accounts.ts';
+import { buildAccountStatusSnapshot } from '../core/status.ts';
+import { createOpenClawDefaultChannelRuntimeState } from '../openclaw/sdk-helpers.ts';
+
+export type BncrStatusBridge = {
+  getChannelSummary: (defaultAccountId: string) => unknown | Promise<unknown>;
+  getAccountRuntimeSnapshot: (accountId?: string) => unknown;
+  getStatusHeadline: (accountId?: string) => unknown;
+};
+
+export function createBncrStatusSurface(getBridge: () => BncrStatusBridge) {
+  return {
+    defaultRuntime: createOpenClawDefaultChannelRuntimeState(BNCR_DEFAULT_ACCOUNT_ID, {
+      mode: 'ws-offline',
+    }),
+    buildChannelSummary: async ({ defaultAccountId }: any) => {
+      return getBridge().getChannelSummary(defaultAccountId || BNCR_DEFAULT_ACCOUNT_ID);
+    },
+    buildAccountSnapshot: async ({ account, runtime }: any) => {
+      const runtimeBridge = getBridge();
+      const rt = runtime || runtimeBridge.getAccountRuntimeSnapshot(account?.accountId);
+      return buildAccountStatusSnapshot({
+        account,
+        runtime: rt,
+        healthSummary: runtimeBridge.getStatusHeadline(account?.accountId),
+        // default 名不可隐藏时，统一展示稳定默认值
+        displayName: resolveDefaultDisplayName(account?.name, account?.accountId),
+      });
+    },
+    resolveAccountState: ({ enabled, configured, account, cfg, runtime }: any) => {
+      if (!enabled) return 'disabled';
+      const resolved = resolveAccount(cfg, account?.accountId);
+      if (!(resolved.enabled && configured)) return 'not configured';
+      const rt = runtime || getBridge().getAccountRuntimeSnapshot(account?.accountId);
+      return (rt as any)?.connected ? 'linked' : 'configured';
+    },
+  };
+}

package/src/runtime/log-dedupe.ts

@@ -0,0 +1,56 @@
+export type LogDedupeStateEntry = {
+  at: number;
+  sig: string;
+};
+
+export type LogDedupeState = Map<string, LogDedupeStateEntry>;
+
+export const LOG_DEDUPE_STATE_TTL_MS = 10 * 60 * 1000;
+export const LOG_DEDUPE_STATE_MAX_ENTRIES = 1_000;
+
+export function pruneLogDedupeState(
+  state: LogDedupeState,
+  currentTime: number,
+  options?: {
+    ttlMs?: number;
+    maxEntries?: number;
+  },
+) {
+  const ttlMs = options?.ttlMs ?? LOG_DEDUPE_STATE_TTL_MS;
+  const maxEntries = options?.maxEntries ?? LOG_DEDUPE_STATE_MAX_ENTRIES;
+
+  for (const [key, entry] of state.entries()) {
+    if (currentTime - entry.at > ttlMs) {
+      state.delete(key);
+    }
+  }
+
+  while (state.size > maxEntries) {
+    const oldestKey = state.keys().next().value;
+    if (!oldestKey) break;
+    state.delete(oldestKey);
+  }
+}
+
+export function shouldEmitDedupLog(args: {
+  state: LogDedupeState;
+  key: string;
+  sig: string;
+  nowMs: number;
+  windowMs?: number;
+  ttlMs?: number;
+  maxEntries?: number;
+}) {
+  const windowMs = args.windowMs ?? 5 * 60 * 1000;
+  const pruneOptions = {
+    ttlMs: args.ttlMs,
+    maxEntries: args.maxEntries,
+  };
+
+  pruneLogDedupeState(args.state, args.nowMs, pruneOptions);
+  const prev = args.state.get(args.key) || null;
+  if (prev && prev.sig === args.sig && args.nowMs - prev.at < windowMs) return false;
+  args.state.set(args.key, { at: args.nowMs, sig: args.sig });
+  pruneLogDedupeState(args.state, args.nowMs, pruneOptions);
+  return true;
+}