@xmoxmo/bncr 0.2.6 → 0.2.7

package/src/messaging/outbound/durable-message-adapter.ts

@@ -0,0 +1,107 @@
+import { defineChannelMessageAdapter } from 'openclaw/plugin-sdk/channel-outbound';
+import type {
+  ChannelMessageAdapterShape,
+  ChannelMessageSendMediaContext,
+  ChannelMessageSendPayloadContext,
+  ChannelMessageSendResult,
+  ChannelMessageSendTextContext,
+} from 'openclaw/plugin-sdk/channel-outbound';
+
+import { buildFileTransferOutboxEntry, buildTextOutboxEntry } from '../../core/outbox-entry-builders.ts';
+import type { BncrRoute, OutboxEntry } from '../../core/types.ts';
+import { buildBncrDurableQueuedResult } from './durable-queue-adapter.ts';
+
+export type BncrDurableMessageQueuedAdapterDeps<TConfig = unknown> = {
+  enqueueText: (ctx: ChannelMessageSendTextContext<TConfig>) => Promise<OutboxEntry> | OutboxEntry;
+  enqueueMedia?: (ctx: ChannelMessageSendMediaContext<TConfig>) => Promise<OutboxEntry> | OutboxEntry;
+  enqueuePayload?: (ctx: ChannelMessageSendPayloadContext<TConfig>) => Promise<OutboxEntry> | OutboxEntry;
+  now?: () => number;
+};
+
+export type BncrDurableMessageQueuedAdapterBuilderDeps<TConfig = unknown> = {
+  createMessageId: () => string;
+  now: () => number;
+  normalizeAccountId: (accountId?: string | null) => string;
+  normalizeReplyToId: (value?: string | null) => string;
+  resolveTarget: (ctx: ChannelMessageSendTextContext<TConfig>) => {
+    route: BncrRoute;
+    sessionKey: string;
+    accountId?: string | null;
+  };
+  filePushEvent?: string;
+};
+
+// This adapter intentionally models only the OpenClaw -> bncr-plugin handoff.
+// Once a message is accepted into bncr's own outbox, OpenClaw should stop managing it;
+// client/platform ACK, retry, and deadLetter remain owned by the bncr service framework.
+export function createBncrDurableMessageQueuedAdapter<TConfig = unknown>(
+  deps: BncrDurableMessageQueuedAdapterDeps<TConfig>,
+): ChannelMessageAdapterShape<TConfig, ChannelMessageSendResult> {
+  return defineChannelMessageAdapter({
+    id: 'bncr-queued-outbox',
+    receive: {
+      defaultAckPolicy: 'manual',
+      supportedAckPolicies: ['manual'],
+    },
+    send: {
+      text: async (ctx) => toChannelMessageSendResult(await deps.enqueueText(ctx), deps.now),
+      media: deps.enqueueMedia
+        ? async (ctx) => toChannelMessageSendResult(await deps.enqueueMedia?.(ctx), deps.now)
+        : undefined,
+      payload: deps.enqueuePayload
+        ? async (ctx) => toChannelMessageSendResult(await deps.enqueuePayload?.(ctx), deps.now)
+        : undefined,
+    },
+  });
+}
+
+export function createBncrDurableMessageQueuedAdapterFromBuilders<TConfig = unknown>(
+  deps: BncrDurableMessageQueuedAdapterBuilderDeps<TConfig>,
+): ChannelMessageAdapterShape<TConfig, ChannelMessageSendResult> {
+  return createBncrDurableMessageQueuedAdapter<TConfig>({
+    now: deps.now,
+    enqueueText: (ctx) => {
+      const resolved = deps.resolveTarget(ctx);
+      return buildTextOutboxEntry({
+        createMessageId: deps.createMessageId,
+        now: deps.now,
+        normalizeAccountId: deps.normalizeAccountId,
+        normalizeReplyToId: deps.normalizeReplyToId,
+        accountId: resolved.accountId ?? ctx.accountId ?? undefined,
+        sessionKey: resolved.sessionKey,
+        route: resolved.route,
+        text: ctx.text,
+        kind: 'final',
+        replyToId: ctx.replyToId ?? undefined,
+      });
+    },
+    enqueueMedia: (ctx) => {
+      const resolved = deps.resolveTarget(ctx);
+      return buildFileTransferOutboxEntry({
+        createMessageId: deps.createMessageId,
+        now: deps.now,
+        normalizeAccountId: deps.normalizeAccountId,
+        pushEvent: deps.filePushEvent ?? 'bncr.file.push',
+        accountId: resolved.accountId ?? ctx.accountId ?? undefined,
+        sessionKey: resolved.sessionKey,
+        route: resolved.route,
+        mediaUrl: ctx.mediaUrl,
+        mediaLocalRoots: ctx.mediaLocalRoots,
+        text: ctx.text,
+        asVoice: ctx.audioAsVoice,
+        audioAsVoice: ctx.audioAsVoice,
+        kind: 'final',
+        replyToId: ctx.replyToId ?? undefined,
+      });
+    },
+  });
+}
+
+function toChannelMessageSendResult(entry: OutboxEntry | undefined, now?: () => number): ChannelMessageSendResult {
+  if (!entry) throw new Error('bncr durable message adapter did not receive an outbox entry');
+  const queued = buildBncrDurableQueuedResult({ entry, sentAt: now?.() });
+  return {
+    receipt: queued.receipt as any,
+    messageId: queued.receipt.primaryPlatformMessageId,
+  };
+}

package/src/messaging/outbound/durable-queue-adapter.ts

@@ -0,0 +1,157 @@
+import type { BncrRoute, OutboxEntry } from '../../core/types.ts';
+import { normalizeOutboundReplyToId } from './reply-target-policy.ts';
+
+export type BncrDurableQueuedReceipt = {
+  primaryPlatformMessageId: string;
+  platformMessageIds: string[];
+  parts: Array<{
+    platformMessageId: string;
+    kind: 'text' | 'media' | 'voice' | 'unknown';
+    index: number;
+    threadId?: string;
+    replyToId?: string;
+    raw: {
+      channel: 'bncr';
+      channelId: 'bncr';
+      messageId: string;
+      chatId: string;
+      conversationId: string;
+      timestamp: number;
+      meta: BncrDurableQueuedReceiptMeta;
+    };
+  }>;
+  threadId?: string;
+  replyToId?: string;
+  sentAt: number;
+  raw: Array<{
+    channel: 'bncr';
+    channelId: 'bncr';
+    messageId: string;
+    chatId: string;
+    conversationId: string;
+    timestamp: number;
+    meta: BncrDurableQueuedReceiptMeta;
+  }>;
+};
+
+export type BncrDurableQueuedReceiptMeta = {
+  status: 'accepted';
+  deliveryStage: 'queued';
+  queue: 'bncr.outbox';
+  finalAckManagedBy: 'bncr-outbox';
+  ackSemantics: 'plugin-accepted-not-client-acked';
+  accountId: string;
+  sessionKey: string;
+  route: BncrRoute;
+  outboxPayloadType?: string;
+};
+
+export type BncrDurableQueuedResult = {
+  status: 'sent';
+  results: Array<{
+    channel: 'bncr';
+    channelId: 'bncr';
+    messageId: string;
+    chatId: string;
+    conversationId: string;
+    timestamp: number;
+    meta: BncrDurableQueuedReceiptMeta;
+  }>;
+  receipt: BncrDurableQueuedReceipt;
+  payloadOutcomes: Array<{
+    index: number;
+    status: 'sent';
+    results: BncrDurableQueuedResult['results'];
+  }>;
+};
+
+export function buildBncrDurableQueuedResult(args: {
+  entry: OutboxEntry;
+  index?: number;
+  threadId?: string;
+  replyToId?: string;
+  sentAt?: number;
+}): BncrDurableQueuedResult {
+  const sentAt = Number.isFinite(args.sentAt) ? Number(args.sentAt) : args.entry.createdAt;
+  const platformMessageId = args.entry.messageId;
+  const replyToId = normalizeOutboundReplyToId({ replyToId: args.replyToId ?? extractReplyToId(args.entry) }) || undefined;
+  const chatId = formatQueuedReceiptChatId(args.entry.route);
+  const meta: BncrDurableQueuedReceiptMeta = {
+    status: 'accepted',
+    deliveryStage: 'queued',
+    queue: 'bncr.outbox',
+    finalAckManagedBy: 'bncr-outbox',
+    ackSemantics: 'plugin-accepted-not-client-acked',
+    accountId: args.entry.accountId,
+    sessionKey: args.entry.sessionKey,
+    route: args.entry.route,
+    outboxPayloadType: extractPayloadType(args.entry),
+  };
+  const result = {
+    channel: 'bncr' as const,
+    channelId: 'bncr' as const,
+    messageId: platformMessageId,
+    chatId,
+    conversationId: args.entry.sessionKey,
+    timestamp: sentAt,
+    meta,
+  };
+  const receipt: BncrDurableQueuedReceipt = {
+    primaryPlatformMessageId: platformMessageId,
+    platformMessageIds: [platformMessageId],
+    parts: [
+      {
+        platformMessageId,
+        kind: inferReceiptKind(args.entry),
+        index: args.index ?? 0,
+        threadId: args.threadId,
+        replyToId,
+        raw: result,
+      },
+    ],
+    threadId: args.threadId,
+    replyToId,
+    sentAt,
+    raw: [result],
+  };
+  return {
+    status: 'sent',
+    results: [result],
+    receipt,
+    payloadOutcomes: [
+      {
+        index: args.index ?? 0,
+        status: 'sent',
+        results: [result],
+      },
+    ],
+  };
+}
+
+function extractPayloadType(entry: OutboxEntry): string | undefined {
+  const payload = entry.payload as any;
+  return typeof payload?.type === 'string' ? payload.type : undefined;
+}
+
+function extractReplyToId(entry: OutboxEntry): string | undefined {
+  const payload = entry.payload as any;
+  const metaReply = payload?._meta?.replyToId;
+  const replyToId = payload?.replyToId ?? metaReply;
+  return typeof replyToId === 'string' ? replyToId : undefined;
+}
+
+function inferReceiptKind(entry: OutboxEntry): 'text' | 'media' | 'voice' | 'unknown' {
+  const payload = entry.payload as any;
+  if (payload?._meta?.kind === 'file-transfer') {
+    if (payload?._meta?.asVoice === true || payload?._meta?.audioAsVoice === true) return 'voice';
+    return 'media';
+  }
+  if (payload?.message?.type === 'text') return 'text';
+  return 'unknown';
+}
+
+function formatQueuedReceiptChatId(route: BncrRoute): string {
+  const platform = route.platform || 'unknown';
+  if (route.groupId) return `Bncr:${platform}:${route.groupId}:${route.userId}`;
+  return `Bncr:${platform}:${route.userId}`;
+}

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

@@ -1,4 +1,4 @@
-import { buildChannelOutboundSessionRoute } from 'openclaw/plugin-sdk/core';
+import { buildOpenClawChannelOutboundSessionRoute } from '../../openclaw/session-route-runtime.ts';
 import {
   buildCanonicalBncrSessionKey,
   formatDisplayScope,
@@ -72,7 +72,7 @@ export function resolveBncrOutboundSessionRoute(params: ResolveBncrOutboundSessi
   const sessionKey = buildCanonicalBncrSessionKey(route, canonicalAgentId);
   const displayTo = formatDisplayScope(route);
 
-  const built = buildChannelOutboundSessionRoute({
+  const built = buildOpenClawChannelOutboundSessionRoute({
     cfg: params.cfg,
     agentId: canonicalAgentId,
     channel: params.channel,

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);
+}
+