@xmoxmo/bncr 0.1.6 → 0.1.8

package/src/core/logging.ts

@@ -0,0 +1,65 @@
+export type BncrLogLevel = 'info' | 'warn' | 'error';
+export type BncrLogOptions = { debugOnly?: boolean };
+
+const BNCR_PREFIX = '[bncr]';
+
+type DebugGate = () => boolean;
+
+type ConsoleMethod = 'log' | 'warn' | 'error';
+
+function resolveConsoleMethod(level: BncrLogLevel): ConsoleMethod {
+  switch (level) {
+    case 'warn':
+      return 'warn';
+    case 'error':
+      return 'error';
+    default:
+      return 'log';
+  }
+}
+
+function emitConsole(method: ConsoleMethod, line: string) {
+  if (method === 'warn') {
+    console.warn(line);
+    return;
+  }
+  if (method === 'error') {
+    console.error(line);
+    return;
+  }
+  console.log(line);
+}
+
+export function normalizeBncrLogLine(raw: string | undefined) {
+  const text = String(raw || '').trim();
+  if (!text) return BNCR_PREFIX;
+  return text.startsWith(BNCR_PREFIX) ? text : `${BNCR_PREFIX} ${text}`;
+}
+
+export function formatBncrLogLine(scope: string | undefined, message: string | undefined) {
+  const normalizedScope = String(scope || '').trim();
+  const normalizedMessage = String(message || '').trim();
+  const prefix = normalizedScope ? `${BNCR_PREFIX} ${normalizedScope}` : BNCR_PREFIX;
+  return normalizedMessage ? `${prefix} ${normalizedMessage}` : prefix;
+}
+
+export function emitBncrLog(
+  level: BncrLogLevel,
+  scope: string | undefined,
+  message: string | undefined,
+  options?: BncrLogOptions,
+  isDebugEnabled?: DebugGate,
+) {
+  if (options?.debugOnly && !(isDebugEnabled?.() ?? false)) return;
+  emitConsole(resolveConsoleMethod(level), formatBncrLogLine(scope, message));
+}
+
+export function emitBncrLogLine(
+  level: BncrLogLevel,
+  line: string | undefined,
+  options?: BncrLogOptions,
+  isDebugEnabled?: DebugGate,
+) {
+  if (options?.debugOnly && !(isDebugEnabled?.() ?? false)) return;
+  emitConsole(resolveConsoleMethod(level), normalizeBncrLogLine(line));
+}

package/src/core/targets.ts

@@ -1,6 +1,24 @@
 import type { BncrRoute } from './types.ts';
 
 export type BncrSessionKind = 'direct' | 'group';
+export type BncrExplicitTarget = {
+  raw: string;
+  normalized: string;
+  source:
+    | 'display-scope'
+    | 'strict-session-key'
+    | 'legacy-session-key'
+    | 'hex-scope'
+    | 'route-scope';
+  kind: BncrSessionKind;
+  chatType: 'direct';
+  displayScope: string;
+  route: BncrRoute;
+  canonicalSessionKey?: string;
+  platform: string;
+  userId: string;
+  groupId?: string;
+};
 
 function asString(v: unknown, fallback = ''): string {
   if (typeof v === 'string') return v;
@@ -54,6 +72,85 @@ export function buildDisplayScopeCandidates(route: BncrRoute): string[] {
   return Array.from(new Set(candidates.map((x) => asString(x).trim()).filter(Boolean)));
 }
 
+export function formatTargetDisplay(
+  input: BncrRoute | BncrExplicitTarget | null | undefined,
+): string {
+  if (!input) return '';
+  const route = parseRouteLike((input as any)?.route) || parseRouteLike(input);
+  if (!route) return '';
+  return formatDisplayScope(route);
+}
+
+export function parseExplicitTarget(
+  input: string,
+  options?: { canonicalAgentId?: string | null },
+): BncrExplicitTarget | null {
+  const raw = asString(input).trim();
+  if (!raw) return null;
+
+  const canonicalAgentId = asString(options?.canonicalAgentId).trim() || undefined;
+  let route: BncrRoute | null = null;
+  let source: BncrExplicitTarget['source'] | null = null;
+
+  const strict = parseStrictBncrSessionKey(raw);
+  if (strict?.route) {
+    route = strict.route;
+    source = 'strict-session-key';
+  }
+
+  if (!route) {
+    const displayRoute = parseRouteFromDisplayScope(raw);
+    if (displayRoute) {
+      route = displayRoute;
+      source = 'display-scope';
+    }
+  }
+
+  if (!route) {
+    const legacy = parseLegacySessionKey(raw);
+    if (legacy?.route) {
+      route = legacy.route;
+      source = legacy.source === 'hex' ? 'hex-scope' : 'legacy-session-key';
+    }
+  }
+
+  if (!route) {
+    const hexRoute = parseRouteFromHexScope(raw);
+    if (hexRoute) {
+      route = hexRoute;
+      source = 'hex-scope';
+    }
+  }
+
+  if (!route) {
+    const scopedRoute = parseRouteFromScope(raw);
+    if (scopedRoute) {
+      route = scopedRoute;
+      source = 'route-scope';
+    }
+  }
+
+  if (!route || !source) return null;
+
+  const kind: BncrSessionKind = route.groupId === '0' ? 'direct' : 'group';
+  const displayScope = formatDisplayScope(route);
+  return {
+    raw,
+    normalized: displayScope,
+    source,
+    kind,
+    chatType: 'direct',
+    displayScope,
+    route,
+    ...(canonicalAgentId
+      ? { canonicalSessionKey: buildCanonicalBncrSessionKey(route, canonicalAgentId) }
+      : {}),
+    platform: route.platform,
+    userId: route.userId,
+    ...(route.groupId === '0' ? {} : { groupId: route.groupId }),
+  };
+}
+
 export function isLowerHex(input: string): boolean {
   const raw = asString(input).trim();
   return !!raw && /^[0-9a-fA-F]+$/.test(raw) && raw.length % 2 === 0;

package/src/messaging/inbound/commands.ts

@@ -1,3 +1,4 @@
+import { emitBncrLogLine } from '../../core/logging.ts';
 import {
   formatDisplayScope,
   normalizeInboundSessionKey,
@@ -78,7 +79,7 @@ export async function handleBncrNativeCommand(params: {
   const displayTo = formatDisplayScope(route);
   const body = command.body;
   if (!clientId) {
-    logger?.warn?.('bncr: missing clientId for inbound command identity');
+    emitBncrLogLine('warn', '[bncr] inbound missing clientId for native command identity');
     return { handled: false };
   }
   const senderIdForContext = clientId;
@@ -119,7 +120,7 @@ export async function handleBncrNativeCommand(params: {
     sessionKey,
     ctx: ctxPayload,
     onRecordError: (err: unknown) => {
-      logger?.warn?.(`bncr: record native command session failed: ${String(err)}`);
+      emitBncrLogLine('warn', `[bncr] inbound record native command session failed: ${String(err)}`);
     },
   });
 
@@ -155,6 +156,7 @@ export async function handleBncrNativeCommand(params: {
           payload: {
             ...payload,
             kind: kind as 'tool' | 'block' | 'final' | undefined,
+            replyToId: msgId || undefined,
           },
         });
       },

package/src/messaging/inbound/dispatch.ts

@@ -1,3 +1,4 @@
+import { emitBncrLogLine } from '../../core/logging.ts';
 import {
   formatDisplayScope,
   normalizeInboundSessionKey,
@@ -132,7 +133,7 @@ export async function dispatchBncrInbound(params: {
 
   const displayTo = formatDisplayScope(route);
   if (!clientId) {
-    logger?.warn?.('bncr: missing clientId for inbound chat identity');
+    emitBncrLogLine('warn', '[bncr] inbound missing clientId for chat identity');
     return {
       accountId,
       sessionKey,
@@ -171,7 +172,7 @@ export async function dispatchBncrInbound(params: {
     sessionKey,
     ctx: ctxPayload,
     onRecordError: (err: unknown) => {
-      logger?.warn?.(`bncr: record session failed: ${String(err)}`);
+      emitBncrLogLine('warn', `[bncr] inbound record session failed: ${String(err)}`);
     },
   });
 
@@ -207,7 +208,7 @@ export async function dispatchBncrInbound(params: {
         });
       },
       onError: (err: unknown) => {
-        logger?.error?.(`bncr reply failed: ${String(err)}`);
+        emitBncrLogLine('error', `[bncr] outbound reply failed: ${String(err)}`);
       },
     },
     replyOptions: {

package/src/messaging/outbound/media.ts

@@ -55,7 +55,8 @@ export function buildBncrMediaOutboundFrame(params: {
   mediaMsg: string;
   fileName: string;
   hintedType?: string;
-  kind?: 'block' | 'final';
+  kind?: 'tool' | 'block' | 'final';
+  replyToId?: string;
   now: number;
 }) {
   return {
@@ -63,6 +64,7 @@ export function buildBncrMediaOutboundFrame(params: {
     messageId: params.messageId,
     idempotencyKey: params.messageId,
     sessionKey: params.sessionKey,
+    replyToId: asString(params.replyToId || '').trim() || undefined,
     message: {
       platform: params.route.platform,
       groupId: params.route.groupId,

package/src/messaging/outbound/send.ts

@@ -3,6 +3,7 @@ export async function sendBncrText(params: {
   accountId: string;
   to: string;
   text: string;
+  replyToId?: string;
   mediaLocalRoots?: readonly string[];
   resolveVerifiedTarget: (
     to: string,
@@ -13,7 +14,12 @@ export async function sendBncrText(params: {
     accountId: string;
     sessionKey: string;
     route: any;
-    payload: { text?: string; mediaUrl?: string; mediaUrls?: string[] };
+    payload: {
+      text?: string;
+      mediaUrl?: string;
+      mediaUrls?: string[];
+      replyToId?: string;
+    };
     mediaLocalRoots?: readonly string[];
   }) => Promise<void>;
   createMessageId: () => string;
@@ -27,6 +33,7 @@ export async function sendBncrText(params: {
     route: verified.route,
     payload: {
       text: params.text,
+      replyToId: params.replyToId,
     },
     mediaLocalRoots: params.mediaLocalRoots,
   });
@@ -46,6 +53,7 @@ export async function sendBncrMedia(params: {
   mediaUrl?: string;
   asVoice?: boolean;
   audioAsVoice?: boolean;
+  replyToId?: string;
   mediaLocalRoots?: readonly string[];
   resolveVerifiedTarget: (
     to: string,
@@ -62,6 +70,7 @@ export async function sendBncrMedia(params: {
       mediaUrls?: string[];
       asVoice?: boolean;
       audioAsVoice?: boolean;
+      replyToId?: string;
     };
     mediaLocalRoots?: readonly string[];
   }) => Promise<void>;
@@ -79,6 +88,7 @@ export async function sendBncrMedia(params: {
       mediaUrl: params.mediaUrl || '',
       asVoice: params.asVoice === true ? true : undefined,
       audioAsVoice: params.audioAsVoice === true ? true : undefined,
+      replyToId: params.replyToId,
     },
     mediaLocalRoots: params.mediaLocalRoots,
   });

package/src/messaging/outbound/session-route.ts

@@ -0,0 +1,73 @@
+import { buildChannelOutboundSessionRoute } from 'openclaw/plugin-sdk/core';
+import {
+  buildCanonicalBncrSessionKey,
+  formatDisplayScope,
+  parseRouteFromDisplayScope,
+  parseStrictBncrSessionKey,
+  routeScopeToHex,
+} from '../../core/targets.ts';
+import type { BncrRoute } from '../../core/types.ts';
+
+type ResolveBncrOutboundSessionRouteParams = {
+  cfg: any;
+  channel: string;
+  agentId: string;
+  accountId?: string;
+  target: string;
+  resolvedTarget?: { to?: string } | null;
+  threadId?: string;
+  canonicalAgentId: string;
+  resolveRouteBySession?: (raw: string, accountId: string) => BncrRoute | null;
+};
+
+function asString(v: unknown, fallback = ''): string {
+  if (typeof v === 'string') return v;
+  if (v == null) return fallback;
+  return String(v);
+}
+
+export function resolveBncrOutboundSessionRoute(params: ResolveBncrOutboundSessionRouteParams) {
+  const raw = asString(params.resolvedTarget?.to || params.target).trim();
+  if (!raw) return null;
+
+  let route: BncrRoute | null = null;
+
+  const strict = parseStrictBncrSessionKey(raw);
+  if (strict) {
+    route = strict.route;
+  } else {
+    route = parseRouteFromDisplayScope(raw);
+    if (!route && params.accountId && params.resolveRouteBySession) {
+      route = params.resolveRouteBySession(raw, params.accountId);
+    }
+  }
+
+  if (!route) return null;
+
+  const canonicalAgentId =
+    asString(params.canonicalAgentId).trim() || asString(params.agentId).trim() || 'main';
+  const peerId = routeScopeToHex(route);
+  const sessionKey = buildCanonicalBncrSessionKey(route, canonicalAgentId);
+  const displayTo = formatDisplayScope(route);
+
+  const built = buildChannelOutboundSessionRoute({
+    cfg: params.cfg,
+    agentId: canonicalAgentId,
+    channel: params.channel,
+    accountId: params.accountId,
+    peer: {
+      kind: 'direct',
+      id: peerId,
+    },
+    chatType: 'direct',
+    from: displayTo,
+    to: displayTo,
+    ...(params.threadId !== undefined ? { threadId: params.threadId } : {}),
+  });
+
+  return {
+    ...built,
+    sessionKey,
+    baseSessionKey: sessionKey,
+  };
+}

package/src/messaging/outbound/target-resolver.ts

@@ -0,0 +1,56 @@
+import {
+  formatDisplayScope,
+  parseRouteFromDisplayScope,
+  parseStrictBncrSessionKey,
+} from '../../core/targets.ts';
+import type { BncrRoute } from '../../core/types.ts';
+
+type ResolveBncrOutboundTargetParams = {
+  target: string;
+  accountId?: string | null;
+  resolveRouteBySession?: (raw: string, accountId: string) => BncrRoute | null;
+};
+
+function asString(v: unknown, fallback = ''): string {
+  if (typeof v === 'string') return v;
+  if (v == null) return fallback;
+  return String(v);
+}
+
+export function looksLikeBncrExplicitTarget(input: string): boolean {
+  const raw = asString(input).trim();
+  if (!raw) return false;
+  return Boolean(parseRouteFromDisplayScope(raw) || parseStrictBncrSessionKey(raw));
+}
+
+export function resolveBncrOutboundTarget(params: ResolveBncrOutboundTargetParams): {
+  route: BncrRoute;
+  displayScope: string;
+  kind: 'user' | 'group';
+} | null {
+  const raw = asString(params.target).trim();
+  if (!raw) return null;
+
+  let route: BncrRoute | null = null;
+
+  const strict = parseStrictBncrSessionKey(raw);
+  if (strict?.route) {
+    route = strict.route;
+  }
+
+  if (!route) {
+    route = parseRouteFromDisplayScope(raw);
+  }
+
+  if (!route && params.accountId && params.resolveRouteBySession) {
+    route = params.resolveRouteBySession(raw, params.accountId);
+  }
+
+  if (!route) return null;
+
+  return {
+    route,
+    displayScope: formatDisplayScope(route),
+    kind: route.groupId === '0' ? 'user' : 'group',
+  };
+}