@xmoxmo/bncr 0.2.6 → 0.2.8

package/src/openclaw/config-runtime.ts

@@ -0,0 +1,52 @@
+type RuntimeConfigApi = {
+  current?: () => unknown;
+  get?: () => unknown;
+  mutateConfigFile?: (params: {
+    afterWrite?: { mode?: string };
+    mutate: (draft: Record<string, unknown>) => void;
+  }) => Promise<unknown> | unknown;
+};
+
+type RuntimeApiHolder = {
+  runtime?: {
+    config?: RuntimeConfigApi;
+  };
+};
+
+function resolveConfigApi(api: RuntimeApiHolder): RuntimeConfigApi {
+  const config = api?.runtime?.config;
+  if (!config) throw new Error('OpenClaw runtime config API is unavailable');
+  return config;
+}
+
+export function getOpenClawRuntimeConfig(api: RuntimeApiHolder): unknown {
+  const config = resolveConfigApi(api);
+  if (typeof config.current === 'function') return config.current();
+  if (typeof config.get === 'function') return config.get();
+  throw new Error('OpenClaw runtime config read API is unavailable');
+}
+
+export function getOpenClawRuntimeConfigOrDefault<T>(
+  api: RuntimeApiHolder,
+  fallback: T,
+): unknown | T {
+  try {
+    return getOpenClawRuntimeConfig(api);
+  } catch {
+    return fallback;
+  }
+}
+
+export async function mutateOpenClawRuntimeConfigFile(
+  api: RuntimeApiHolder,
+  params: {
+    afterWrite?: { mode?: string };
+    mutate: (draft: Record<string, unknown>) => void;
+  },
+): Promise<unknown> {
+  const config = resolveConfigApi(api);
+  if (typeof config.mutateConfigFile !== 'function') {
+    throw new Error('OpenClaw runtime config mutate API is unavailable');
+  }
+  return config.mutateConfigFile(params);
+}

package/src/openclaw/inbound-session-runtime.ts

@@ -0,0 +1,94 @@
+import { recordInboundSession as sdkRecordInboundSession } from 'openclaw/plugin-sdk/conversation-runtime';
+import { resolvePinnedMainDmOwnerFromAllowlist as sdkResolvePinnedMainDmOwnerFromAllowlist } from 'openclaw/plugin-sdk/security-runtime';
+import {
+  recordSessionMetaFromInbound as sdkRecordSessionMetaFromInbound,
+  resolveStorePath as sdkResolveStorePath,
+  updateSessionStoreEntry as sdkUpdateSessionStoreEntry,
+} from 'openclaw/plugin-sdk/session-store-runtime';
+
+type ResolveStorePathFn = (storeConfig: unknown, options: { agentId: string }) => string;
+type RecordInboundSessionFn = typeof sdkRecordInboundSession;
+type RecordSessionMetaFromInboundFn = typeof sdkRecordSessionMetaFromInbound;
+type UpdateSessionStoreEntryFn = typeof sdkUpdateSessionStoreEntry;
+type ReadSessionUpdatedAtFn = (params: { storePath: string; sessionKey: string }) => unknown;
+type ResolvePinnedMainDmOwnerFromAllowlistFn = typeof sdkResolvePinnedMainDmOwnerFromAllowlist;
+
+type BncrInboundSessionRuntime = {
+  resolveStorePath: ResolveStorePathFn;
+  recordInboundSession: RecordInboundSessionFn;
+  recordSessionMetaFromInbound: RecordSessionMetaFromInboundFn;
+  updateSessionStoreEntry: UpdateSessionStoreEntryFn;
+  readSessionUpdatedAt?: ReadSessionUpdatedAtFn;
+  resolvePinnedMainDmOwnerFromAllowlist: ResolvePinnedMainDmOwnerFromAllowlistFn;
+};
+
+let testRuntimeOverride: Partial<BncrInboundSessionRuntime> | null = null;
+
+function resolveRuntime(): BncrInboundSessionRuntime {
+  return {
+    resolveStorePath: testRuntimeOverride?.resolveStorePath ?? sdkResolveStorePath,
+    recordInboundSession: testRuntimeOverride?.recordInboundSession ?? sdkRecordInboundSession,
+    recordSessionMetaFromInbound:
+      testRuntimeOverride?.recordSessionMetaFromInbound ?? sdkRecordSessionMetaFromInbound,
+    updateSessionStoreEntry:
+      testRuntimeOverride?.updateSessionStoreEntry ?? sdkUpdateSessionStoreEntry,
+    readSessionUpdatedAt: testRuntimeOverride?.readSessionUpdatedAt,
+    resolvePinnedMainDmOwnerFromAllowlist:
+      testRuntimeOverride?.resolvePinnedMainDmOwnerFromAllowlist ??
+      sdkResolvePinnedMainDmOwnerFromAllowlist,
+  };
+}
+
+export function resolveBncrInboundSessionStorePath(args: {
+  storeConfig: unknown;
+  agentId: string;
+}): string {
+  return resolveRuntime().resolveStorePath(args.storeConfig, { agentId: args.agentId });
+}
+
+export function recordBncrInboundSession(
+  params: Parameters<RecordInboundSessionFn>[0],
+): ReturnType<RecordInboundSessionFn> {
+  return resolveRuntime().recordInboundSession(params);
+}
+
+export function recordBncrSessionMetaFromInbound(
+  params: Parameters<RecordSessionMetaFromInboundFn>[0],
+): ReturnType<RecordSessionMetaFromInboundFn> {
+  return resolveRuntime().recordSessionMetaFromInbound(params);
+}
+
+export function updateBncrSessionStoreEntry(
+  params: Parameters<UpdateSessionStoreEntryFn>[0],
+): ReturnType<UpdateSessionStoreEntryFn> {
+  return resolveRuntime().updateSessionStoreEntry(params);
+}
+
+export function readBncrSessionUpdatedAt(
+  api: { runtime?: { channel?: { session?: { readSessionUpdatedAt?: ReadSessionUpdatedAtFn } } } },
+  params: { storePath: string; sessionKey: string },
+): unknown {
+  const runtime = resolveRuntime();
+  if (runtime.readSessionUpdatedAt) return runtime.readSessionUpdatedAt(params);
+  const readSessionUpdatedAt = api?.runtime?.channel?.session?.readSessionUpdatedAt;
+  if (typeof readSessionUpdatedAt !== 'function') {
+    throw new Error('OpenClaw channel session readSessionUpdatedAt API is unavailable');
+  }
+  return readSessionUpdatedAt(params);
+}
+
+export function resolveBncrPinnedMainDmOwnerFromAllowlist(
+  params: Parameters<ResolvePinnedMainDmOwnerFromAllowlistFn>[0],
+): ReturnType<ResolvePinnedMainDmOwnerFromAllowlistFn> {
+  return resolveRuntime().resolvePinnedMainDmOwnerFromAllowlist(params);
+}
+
+export function setBncrInboundSessionRuntimeForTest(
+  runtime: Partial<BncrInboundSessionRuntime> | null,
+): () => void {
+  const previous = testRuntimeOverride;
+  testRuntimeOverride = runtime;
+  return () => {
+    testRuntimeOverride = previous;
+  };
+}

package/src/openclaw/ingress-runtime.ts

@@ -0,0 +1,35 @@
+import {
+  defineStableChannelIngressIdentity as sdkDefineStableChannelIngressIdentity,
+  resolveChannelMessageIngress as sdkResolveChannelMessageIngress,
+} from 'openclaw/plugin-sdk/channel-ingress-runtime';
+
+export function defineOpenClawStableChannelIngressIdentity(params: {
+  key: string;
+  kind: string;
+  normalize: (value: string) => string | null;
+  sensitivity: 'public' | 'private' | 'pii' | string;
+  entryIdPrefix?: string;
+  aliases?: Array<{
+    key: string;
+    kind: string;
+    normalize: (value: string) => string | null;
+    sensitivity: 'public' | 'private' | 'pii' | string;
+  }>;
+}) {
+  return sdkDefineStableChannelIngressIdentity(params as any);
+}
+
+export async function resolveOpenClawChannelMessageIngress(params: {
+  channelId: string;
+  accountId: string;
+  identity: unknown;
+  subject: unknown;
+  conversation: unknown;
+  event: unknown;
+  policy: unknown;
+  allowFrom?: string[];
+  groupAllowFrom?: string[];
+  accessGroups?: unknown;
+}): Promise<any> {
+  return sdkResolveChannelMessageIngress(params as any);
+}

package/src/openclaw/media-runtime.ts

@@ -0,0 +1,73 @@
+type RuntimeMediaLoaded = {
+  buffer: Buffer;
+  contentType?: string;
+  fileName?: string;
+};
+
+type RuntimeMediaApi = {
+  loadWebMedia?: (
+    mediaUrl: string,
+    options?: { localRoots?: readonly string[]; maxBytes?: number },
+  ) => Promise<RuntimeMediaLoaded>;
+};
+
+type RuntimeChannelMediaApi = {
+  readRemoteMediaBuffer?: (options: {
+    url: string;
+    maxBytes?: number;
+  }) => Promise<RuntimeMediaLoaded>;
+  saveMediaBuffer?: (
+    buffer: Buffer,
+    mimeType: string | undefined,
+    direction: 'inbound' | 'outbound',
+    maxBytes: number,
+    fileName?: string,
+  ) => Promise<{ path: string }>;
+};
+
+type RuntimeApiHolder = {
+  runtime?: {
+    media?: RuntimeMediaApi;
+    channel?: {
+      media?: RuntimeChannelMediaApi;
+    };
+  };
+};
+
+export type OpenClawLoadedMedia = RuntimeMediaLoaded;
+
+export function isOpenClawRemoteHttpMediaUrl(mediaUrl: string): boolean {
+  return /^https?:\/\//i.test(String(mediaUrl || '').trim());
+}
+
+export async function loadOpenClawWebMedia(
+  api: RuntimeApiHolder,
+  mediaUrl: string,
+  options?: { localRoots?: readonly string[]; maxBytes?: number },
+): Promise<RuntimeMediaLoaded> {
+  const readRemoteMediaBuffer = api?.runtime?.channel?.media?.readRemoteMediaBuffer;
+  if (isOpenClawRemoteHttpMediaUrl(mediaUrl) && typeof readRemoteMediaBuffer === 'function') {
+    return readRemoteMediaBuffer({ url: mediaUrl, maxBytes: options?.maxBytes });
+  }
+
+  const loadWebMedia = api?.runtime?.media?.loadWebMedia;
+  if (typeof loadWebMedia !== 'function') {
+    throw new Error('OpenClaw runtime media loadWebMedia API is unavailable');
+  }
+  return loadWebMedia(mediaUrl, options);
+}
+
+export async function saveOpenClawChannelMediaBuffer(
+  api: RuntimeApiHolder,
+  buffer: Buffer,
+  mimeType: string | undefined,
+  direction: 'inbound' | 'outbound',
+  maxBytes: number,
+  fileName?: string,
+): Promise<{ path: string }> {
+  const saveMediaBuffer = api?.runtime?.channel?.media?.saveMediaBuffer;
+  if (typeof saveMediaBuffer !== 'function') {
+    throw new Error('OpenClaw channel media saveMediaBuffer API is unavailable');
+  }
+  return saveMediaBuffer(buffer, mimeType, direction, maxBytes, fileName);
+}

package/src/openclaw/reply-runtime.ts

@@ -0,0 +1,104 @@
+type RuntimeReplyApi = {
+  formatAgentEnvelope?: (params: {
+    channel: string;
+    from: string;
+    timestamp: number;
+    previousTimestamp?: unknown;
+    envelope?: unknown;
+    body: string;
+  }) => string;
+  resolveEnvelopeFormatOptions?: (cfg: unknown) => unknown;
+  dispatchReplyWithBufferedBlockDispatcher?: (params: {
+    ctx: unknown;
+    cfg: unknown;
+    dispatcherOptions: {
+      deliver: (
+        payload: {
+          text?: string;
+          mediaUrl?: string;
+          mediaUrls?: string[];
+          audioAsVoice?: boolean;
+        },
+        info?: { kind?: 'tool' | 'block' | 'final' },
+      ) => Promise<void> | void;
+      onError?: (err: unknown) => void;
+    };
+    replyOptions?: {
+      disableBlockStreaming?: boolean;
+      shouldEmitToolResult?: () => boolean;
+    };
+  }) => Promise<unknown> | unknown;
+};
+
+type RuntimeApiHolder = {
+  runtime?: {
+    channel?: {
+      reply?: RuntimeReplyApi;
+    };
+  };
+};
+
+function resolveReplyApi(api: RuntimeApiHolder): RuntimeReplyApi {
+  const reply = api?.runtime?.channel?.reply;
+  if (!reply) throw new Error('OpenClaw channel reply API is unavailable');
+  return reply;
+}
+
+export function resolveOpenClawEnvelopeFormatOptions(
+  api: RuntimeApiHolder,
+  cfg: unknown,
+): unknown {
+  const reply = resolveReplyApi(api);
+  if (typeof reply.resolveEnvelopeFormatOptions !== 'function') {
+    throw new Error('OpenClaw channel reply resolveEnvelopeFormatOptions API is unavailable');
+  }
+  return reply.resolveEnvelopeFormatOptions(cfg);
+}
+
+export function formatOpenClawAgentEnvelope(
+  api: RuntimeApiHolder,
+  params: {
+    channel: string;
+    from: string;
+    timestamp: number;
+    previousTimestamp?: unknown;
+    envelope?: unknown;
+    body: string;
+  },
+): string {
+  const reply = resolveReplyApi(api);
+  if (typeof reply.formatAgentEnvelope !== 'function') {
+    throw new Error('OpenClaw channel reply formatAgentEnvelope API is unavailable');
+  }
+  return reply.formatAgentEnvelope(params);
+}
+
+export async function dispatchOpenClawReplyWithBufferedBlockDispatcher(
+  api: RuntimeApiHolder,
+  params: {
+    ctx: unknown;
+    cfg: unknown;
+    dispatcherOptions: {
+      deliver: (
+        payload: {
+          text?: string;
+          mediaUrl?: string;
+          mediaUrls?: string[];
+          audioAsVoice?: boolean;
+        },
+        info?: { kind?: 'tool' | 'block' | 'final' },
+      ) => Promise<void> | void;
+      onError?: (err: unknown) => void;
+    };
+    replyOptions?: {
+      disableBlockStreaming?: boolean;
+      shouldEmitToolResult?: () => boolean;
+    };
+  },
+): Promise<unknown> {
+  const reply = resolveReplyApi(api);
+  if (typeof reply.dispatchReplyWithBufferedBlockDispatcher !== 'function') {
+    throw new Error('OpenClaw channel reply dispatchReplyWithBufferedBlockDispatcher API is unavailable');
+  }
+  return reply.dispatchReplyWithBufferedBlockDispatcher(params);
+}

package/src/openclaw/routing-runtime.ts

@@ -0,0 +1,48 @@
+import { resolveInboundLastRouteSessionKey } from 'openclaw/plugin-sdk/routing';
+
+type RuntimeRoutingApi = {
+  resolveAgentRoute?: (params: {
+    cfg: any;
+    channel: string;
+    accountId: string;
+    peer: unknown;
+  }) => any;
+};
+
+type RuntimeApiHolder = {
+  runtime?: {
+    channel?: {
+      routing?: RuntimeRoutingApi;
+    };
+  };
+};
+
+function resolveRoutingApi(api: RuntimeApiHolder): RuntimeRoutingApi {
+  const routing = api?.runtime?.channel?.routing;
+  if (!routing) throw new Error('OpenClaw channel routing API is unavailable');
+  return routing;
+}
+
+export function resolveOpenClawAgentRoute(
+  api: RuntimeApiHolder,
+  params: {
+    cfg: any;
+    channel: string;
+    accountId: string;
+    peer: unknown;
+  },
+): any {
+  const routing = resolveRoutingApi(api);
+  if (typeof routing.resolveAgentRoute !== 'function') {
+    throw new Error('OpenClaw channel routing resolveAgentRoute API is unavailable');
+  }
+  return routing.resolveAgentRoute(params);
+}
+
+export function resolveOpenClawInboundLastRouteSessionKey(params: {
+  route: unknown;
+  sessionKey: string;
+}): string {
+  return resolveInboundLastRouteSessionKey(params as any);
+}
+

package/src/openclaw/sdk-helpers.ts

@@ -0,0 +1,20 @@
+import { readBooleanParam as sdkReadBooleanParam } from 'openclaw/plugin-sdk/boolean-param';
+import {
+  applyAccountNameToChannelSection as sdkApplyAccountNameToChannelSection,
+  jsonResult as sdkJsonResult,
+  setAccountEnabledInConfigSection as sdkSetAccountEnabledInConfigSection,
+} from 'openclaw/plugin-sdk/core';
+import { readJsonFileWithFallback as sdkReadJsonFileWithFallback, writeJsonFileAtomically as sdkWriteJsonFileAtomically } from 'openclaw/plugin-sdk/json-store';
+import { readStringParam as sdkReadStringParam } from 'openclaw/plugin-sdk/param-readers';
+import { createDefaultChannelRuntimeState as sdkCreateDefaultChannelRuntimeState } from 'openclaw/plugin-sdk/status-helpers';
+import { extractToolSend as sdkExtractToolSend } from 'openclaw/plugin-sdk/tool-send';
+
+export const readOpenClawBooleanParam = sdkReadBooleanParam;
+export const readOpenClawStringParam = sdkReadStringParam;
+export const readOpenClawJsonFileWithFallback = sdkReadJsonFileWithFallback;
+export const writeOpenClawJsonFileAtomically = sdkWriteJsonFileAtomically;
+export const createOpenClawDefaultChannelRuntimeState = sdkCreateDefaultChannelRuntimeState;
+export const extractOpenClawToolSend = sdkExtractToolSend;
+export const openClawJsonResult = sdkJsonResult;
+export const applyOpenClawAccountNameToChannelSection = sdkApplyAccountNameToChannelSection;
+export const setOpenClawAccountEnabledInConfigSection = sdkSetAccountEnabledInConfigSection;

package/src/openclaw/session-route-runtime.ts

@@ -0,0 +1,15 @@
+import { buildChannelOutboundSessionRoute } from 'openclaw/plugin-sdk/core';
+
+export function buildOpenClawChannelOutboundSessionRoute(params: {
+  cfg: any;
+  agentId: string;
+  channel: string;
+  accountId?: string;
+  peer: unknown;
+  chatType: 'direct' | 'group';
+  from: string;
+  to: string;
+  threadId?: string;
+}): Record<string, unknown> {
+  return buildChannelOutboundSessionRoute(params as any) as Record<string, unknown>;
+}

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>',
+  };
+}