@xmoxmo/bncr 0.3.6 → 0.3.8

package/src/messaging/outbound/reply-enqueue-media.ts

@@ -0,0 +1,181 @@
+import { buildBncrDebugJsonMessage } from '../../core/logging.ts';
+import type { BncrRoute, OutboxEntry } from '../../core/types.ts';
+import { buildReplyMediaFallbackDebugInfo } from './diagnostics.ts';
+import type {
+  EnqueueSingleReplyMediaEntryParams,
+  NormalizedReplyPayload,
+  ReplyMediaEntriesParams,
+  ReplyMediaFallbackTextEntryParams,
+  ReplyMediaFileTransferParams,
+} from './reply-enqueue.ts';
+import type { OutboundReplyTargetPolicy } from './reply-target-policy.ts';
+
+export function enqueueReplyMediaFallbackTextEntry(
+  params: ReplyMediaFallbackTextEntryParams,
+  helpers: {
+    logInfo: (
+      scope: string | undefined,
+      message: string,
+      options?: { debugOnly?: boolean },
+    ) => void;
+    enqueueOutbound: (entry: OutboxEntry) => void;
+    buildTextOutboxEntry: (args: {
+      accountId: string;
+      sessionKey: string;
+      route: BncrRoute;
+      text: string;
+      kind?: 'tool' | 'block' | 'final';
+      replyToId?: string;
+      replyTargetPolicy?: OutboundReplyTargetPolicy;
+    }) => OutboxEntry;
+  },
+): void {
+  helpers.logInfo(
+    'outbound',
+    buildBncrDebugJsonMessage('media-dedupe-hit', buildReplyMediaFallbackDebugInfo(params)),
+    { debugOnly: true },
+  );
+  helpers.enqueueOutbound(
+    helpers.buildTextOutboxEntry({
+      accountId: params.accountId,
+      sessionKey: params.sessionKey,
+      route: params.route,
+      text: params.fallback.text,
+      kind: params.kind,
+      replyToId: params.replyToId || undefined,
+      replyTargetPolicy: params.replyTargetPolicy,
+    }),
+  );
+}
+
+export function enqueueReplyMediaFileTransferEntry(
+  params: ReplyMediaFileTransferParams,
+  helpers: {
+    enqueueOutbound: (entry: OutboxEntry) => void;
+    buildFileTransferOutboxEntry: (args: {
+      accountId: string;
+      sessionKey: string;
+      route: BncrRoute;
+      mediaUrl: string;
+      mediaLocalRoots?: readonly string[];
+      text: string;
+      asVoice: boolean;
+      audioAsVoice: boolean;
+      type?: string;
+      kind?: 'tool' | 'block' | 'final';
+      replyToId?: string;
+      replyTargetPolicy?: OutboundReplyTargetPolicy;
+    }) => OutboxEntry;
+    rememberRecentMediaSend: (args: {
+      sessionKey: string;
+      mediaUrl: string;
+      text: string;
+      replyToId: string;
+      createdAt: number;
+    }) => void;
+  },
+): void {
+  helpers.enqueueOutbound(
+    helpers.buildFileTransferOutboxEntry({
+      accountId: params.accountId,
+      sessionKey: params.sessionKey,
+      route: params.route,
+      mediaUrl: params.mediaUrl,
+      mediaLocalRoots: params.mediaLocalRoots,
+      text: params.text,
+      asVoice: params.asVoice,
+      audioAsVoice: params.audioAsVoice,
+      type: params.type,
+      kind: params.kind,
+      replyToId: params.replyToId || undefined,
+      replyTargetPolicy: params.replyTargetPolicy,
+    }),
+  );
+  helpers.rememberRecentMediaSend({
+    sessionKey: params.sessionKey,
+    mediaUrl: params.mediaUrl,
+    text: params.normalizedText,
+    replyToId: params.replyToId,
+    createdAt: params.createdAt,
+  });
+}
+
+export function enqueueSingleReplyMediaEntry(
+  params: EnqueueSingleReplyMediaEntryParams,
+  helpers: {
+    enqueueReplyMediaFallbackTextEntry: (params: ReplyMediaFallbackTextEntryParams) => void;
+    enqueueReplyMediaFileTransferEntry: (params: ReplyMediaFileTransferParams) => void;
+  },
+): void {
+  if (params.fallback !== null) {
+    helpers.enqueueReplyMediaFallbackTextEntry({
+      accountId: params.params.accountId,
+      sessionKey: params.params.sessionKey,
+      route: params.params.route,
+      mediaUrl: params.mediaUrl,
+      kind: params.params.payload.kind,
+      replyToId: params.params.payload.replyToId,
+      replyTargetPolicy: params.params.payload.replyTargetPolicy,
+      fallback: params.fallback,
+    });
+    return;
+  }
+
+  helpers.enqueueReplyMediaFileTransferEntry({
+    accountId: params.params.accountId,
+    sessionKey: params.params.sessionKey,
+    route: params.params.route,
+    mediaUrl: params.mediaUrl,
+    mediaLocalRoots: params.params.mediaLocalRoots,
+    text: params.text,
+    normalizedText: params.normalizedText,
+    asVoice: params.params.payload.asVoice,
+    audioAsVoice: params.params.payload.audioAsVoice,
+    type: params.params.payload.type,
+    kind: params.params.payload.kind,
+    replyToId: params.params.payload.replyToId,
+    replyTargetPolicy: params.params.payload.replyTargetPolicy,
+    createdAt: params.currentTime,
+  });
+}
+
+export function enqueueReplyMediaEntries(
+  params: ReplyMediaEntriesParams,
+  helpers: {
+    now: () => number;
+    normalizeMessageText: (text: string) => string;
+    tryBuildMediaDedupeFallback: (args: {
+      sessionKey: string;
+      mediaUrl: string;
+      text: string;
+      replyToId: string;
+      currentTime: number;
+    }) => { text: string; reason: string } | null;
+    enqueueSingleReplyMediaEntry: (params: EnqueueSingleReplyMediaEntryParams) => void;
+  },
+): void {
+  const currentTime = helpers.now();
+  const normalizedText = helpers.normalizeMessageText(params.payload.text);
+
+  for (const mediaUrl of params.payload.mediaList) {
+    const fallback = helpers.tryBuildMediaDedupeFallback({
+      sessionKey: params.sessionKey,
+      mediaUrl,
+      text: normalizedText,
+      replyToId: params.payload.replyToId,
+      currentTime,
+    });
+    helpers.enqueueSingleReplyMediaEntry({
+      params,
+      mediaUrl,
+      normalizedText,
+      text: params.payload.text,
+      fallback,
+      currentTime,
+    });
+  }
+}
+
+export function hasReplyMediaEntries(payload: NormalizedReplyPayload) {
+  return payload.mediaList.length > 0;
+}

package/src/messaging/outbound/reply-enqueue.ts

@@ -1,8 +1,15 @@
 import type { BncrRoute, OutboxEntry } from '../../core/types.ts';
-import { buildReplyMediaFallbackDebugInfo } from './diagnostics.ts';
+import { hasReplyMediaEntries } from './reply-enqueue-media.ts';
 import type { OutboundReplyTargetPolicy } from './reply-target-policy.ts';
 import { normalizeOutboundReplyToId } from './reply-target-policy.ts';
 
+const MEDIA_TEXT_SPLIT_THRESHOLD = 1020;
+
+export type ReplyEnqueuePlan =
+  | { kind: 'text-only' }
+  | { kind: 'media-only'; clearText: false }
+  | { kind: 'text-and-media'; clearText: true };
+
 export type { OutboundReplyTargetPolicy } from './reply-target-policy.ts';
 
 export type ReplyPayloadInput = {
@@ -11,6 +18,7 @@ export type ReplyPayloadInput = {
   mediaUrls?: string[];
   asVoice?: boolean;
   audioAsVoice?: boolean;
+  type?: string;
   kind?: 'tool' | 'block' | 'final';
   replyToId?: string;
 };
@@ -22,6 +30,7 @@ export type NormalizedReplyPayload = {
   mediaList: string[];
   asVoice: boolean;
   audioAsVoice: boolean;
+  type?: string;
   kind?: 'tool' | 'block' | 'final';
   replyToId: string;
   replyTargetPolicy: OutboundReplyTargetPolicy;
@@ -41,6 +50,7 @@ export type EnqueueNormalizedReplyPayloadParams = {
   route: BncrRoute;
   payload: NormalizedReplyPayload;
   mediaLocalRoots?: readonly string[];
+  replyToId?: string;
 };
 
 export type ReplyMediaFileTransferParams = {
@@ -53,6 +63,7 @@ export type ReplyMediaFileTransferParams = {
   normalizedText: string;
   asVoice: boolean;
   audioAsVoice: boolean;
+  type?: string;
   kind?: 'tool' | 'block' | 'final';
   replyToId: string;
   replyTargetPolicy: OutboundReplyTargetPolicy;
@@ -79,19 +90,25 @@ export type ReplyMediaFallbackTextEntryParams = {
   fallback: { text: string; reason: string };
 };
 
-const MEDIA_TEXT_SPLIT_THRESHOLD = 1020;
-
-export function hasReplyMediaEntries(payload: NormalizedReplyPayload) {
-  return payload.mediaList.length > 0;
-}
-
 export function shouldSplitReplyMediaText(payload: NormalizedReplyPayload) {
   if (!payload.text) return false;
   if (payload.mediaList.length > 1) return true;
   return payload.text.length > MEDIA_TEXT_SPLIT_THRESHOLD;
 }
 
-function withoutReplyMediaText(payload: NormalizedReplyPayload): NormalizedReplyPayload {
+export function buildReplyEnqueuePlan(payload: NormalizedReplyPayload): ReplyEnqueuePlan {
+  if (!hasReplyMediaEntries(payload)) {
+    return { kind: 'text-only' };
+  }
+
+  if (shouldSplitReplyMediaText(payload)) {
+    return { kind: 'text-and-media', clearText: true };
+  }
+
+  return { kind: 'media-only', clearText: false };
+}
+
+export function withoutReplyMediaText(payload: NormalizedReplyPayload): NormalizedReplyPayload {
   return {
     ...payload,
     text: '',
@@ -169,135 +186,6 @@ export function enqueueReplyTextEntry(
   );
 }
 
-export function enqueueReplyMediaFallbackTextEntry(
-  params: ReplyMediaFallbackTextEntryParams,
-  helpers: {
-    logInfo: (
-      scope: string | undefined,
-      message: string,
-      options?: { debugOnly?: boolean },
-    ) => void;
-    enqueueOutbound: (entry: OutboxEntry) => void;
-    buildTextOutboxEntry: (args: {
-      accountId: string;
-      sessionKey: string;
-      route: BncrRoute;
-      text: string;
-      kind?: 'tool' | 'block' | 'final';
-      replyToId?: string;
-      replyTargetPolicy?: OutboundReplyTargetPolicy;
-    }) => OutboxEntry;
-  },
-): void {
-  helpers.logInfo(
-    'outbound',
-    `media-dedupe-hit ${JSON.stringify(buildReplyMediaFallbackDebugInfo(params))}`,
-    { debugOnly: true },
-  );
-  helpers.enqueueOutbound(
-    buildReplyTextOutboxEntry(
-      {
-        accountId: params.accountId,
-        sessionKey: params.sessionKey,
-        route: params.route,
-        text: params.fallback.text,
-        kind: params.kind,
-        replyToId: params.replyToId,
-        replyTargetPolicy: params.replyTargetPolicy,
-      },
-      { buildTextOutboxEntry: helpers.buildTextOutboxEntry },
-    ),
-  );
-}
-
-export function enqueueReplyMediaFileTransferEntry(
-  params: ReplyMediaFileTransferParams,
-  helpers: {
-    enqueueOutbound: (entry: OutboxEntry) => void;
-    buildFileTransferOutboxEntry: (args: {
-      accountId: string;
-      sessionKey: string;
-      route: BncrRoute;
-      mediaUrl: string;
-      mediaLocalRoots?: readonly string[];
-      text: string;
-      asVoice: boolean;
-      audioAsVoice: boolean;
-      kind?: 'tool' | 'block' | 'final';
-      replyToId?: string;
-      replyTargetPolicy?: OutboundReplyTargetPolicy;
-    }) => OutboxEntry;
-    rememberRecentMediaSend: (args: {
-      sessionKey: string;
-      mediaUrl: string;
-      text: string;
-      replyToId: string;
-      createdAt: number;
-    }) => void;
-  },
-): void {
-  helpers.enqueueOutbound(
-    helpers.buildFileTransferOutboxEntry({
-      accountId: params.accountId,
-      sessionKey: params.sessionKey,
-      route: params.route,
-      mediaUrl: params.mediaUrl,
-      mediaLocalRoots: params.mediaLocalRoots,
-      text: params.text,
-      asVoice: params.asVoice,
-      audioAsVoice: params.audioAsVoice,
-      kind: params.kind,
-      replyToId: params.replyToId || undefined,
-      replyTargetPolicy: params.replyTargetPolicy,
-    }),
-  );
-  helpers.rememberRecentMediaSend({
-    sessionKey: params.sessionKey,
-    mediaUrl: params.mediaUrl,
-    text: params.normalizedText,
-    replyToId: params.replyToId,
-    createdAt: params.createdAt,
-  });
-}
-
-export function enqueueSingleReplyMediaEntry(
-  params: EnqueueSingleReplyMediaEntryParams,
-  helpers: {
-    enqueueReplyMediaFallbackTextEntry: (params: ReplyMediaFallbackTextEntryParams) => void;
-    enqueueReplyMediaFileTransferEntry: (params: ReplyMediaFileTransferParams) => void;
-  },
-): void {
-  if (params.fallback !== null) {
-    helpers.enqueueReplyMediaFallbackTextEntry({
-      accountId: params.params.accountId,
-      sessionKey: params.params.sessionKey,
-      route: params.params.route,
-      mediaUrl: params.mediaUrl,
-      kind: params.params.payload.kind,
-      replyToId: params.params.payload.replyToId,
-      replyTargetPolicy: params.params.payload.replyTargetPolicy,
-      fallback: params.fallback,
-    });
-    return;
-  }
-
-  helpers.enqueueReplyMediaFileTransferEntry({
-    accountId: params.params.accountId,
-    sessionKey: params.params.sessionKey,
-    route: params.params.route,
-    mediaUrl: params.mediaUrl,
-    mediaLocalRoots: params.params.mediaLocalRoots,
-    text: params.text,
-    normalizedText: params.normalizedText,
-    asVoice: params.params.payload.asVoice,
-    audioAsVoice: params.params.payload.audioAsVoice,
-    kind: params.params.payload.kind,
-    replyToId: params.params.payload.replyToId,
-    replyTargetPolicy: params.params.payload.replyTargetPolicy,
-    createdAt: params.currentTime,
-  });
-}
-
 export function enqueueNormalizedReplyPayload(
   params: EnqueueNormalizedReplyPayloadParams,
   helpers: {
@@ -307,7 +195,6 @@ export function enqueueNormalizedReplyPayload(
       route: BncrRoute;
       payload: NormalizedReplyPayload;
     }) => void;
-    hasReplyMediaEntries: (payload: NormalizedReplyPayload) => boolean;
     enqueueReplyMediaEntries: (params: ReplyMediaEntriesParams) => void;
     enqueueReplyTextEntry: (params: {
       accountId: string;
@@ -324,24 +211,26 @@ export function enqueueNormalizedReplyPayload(
     payload: params.payload,
   });
 
-  if (helpers.hasReplyMediaEntries(params.payload)) {
-    if (shouldSplitReplyMediaText(params.payload)) {
-      helpers.enqueueReplyTextEntry({
-        accountId: params.accountId,
-        sessionKey: params.sessionKey,
-        route: params.route,
-        payload: params.payload,
-      });
-      helpers.enqueueReplyMediaEntries({
-        accountId: params.accountId,
-        sessionKey: params.sessionKey,
-        route: params.route,
-        payload: withoutReplyMediaText(params.payload),
-        mediaLocalRoots: params.mediaLocalRoots,
-      });
-      return;
-    }
+  const plan = buildReplyEnqueuePlan(params.payload);
+
+  if (plan.kind === 'text-and-media') {
+    helpers.enqueueReplyTextEntry({
+      accountId: params.accountId,
+      sessionKey: params.sessionKey,
+      route: params.route,
+      payload: params.payload,
+    });
+    helpers.enqueueReplyMediaEntries({
+      accountId: params.accountId,
+      sessionKey: params.sessionKey,
+      route: params.route,
+      payload: withoutReplyMediaText(params.payload),
+      mediaLocalRoots: params.mediaLocalRoots,
+    });
+    return;
+  }
 
+  if (plan.kind !== 'text-only') {
     helpers.enqueueReplyMediaEntries({
       accountId: params.accountId,
       sessionKey: params.sessionKey,
@@ -370,6 +259,7 @@ export function normalizeReplyPayload(
   const mediaUrls = Array.isArray(payload?.mediaUrls)
     ? payload.mediaUrls.map((v) => helpers.asString(v || '').trim()).filter(Boolean)
     : undefined;
+  const type = helpers.asString(payload?.type || '').trim();
   return {
     text,
     mediaUrl,
@@ -377,6 +267,7 @@ export function normalizeReplyPayload(
     mediaList: mediaUrls?.length ? mediaUrls : mediaUrl ? [mediaUrl] : [],
     asVoice: payload?.asVoice === true,
     audioAsVoice: payload?.audioAsVoice === true,
+    ...(type ? { type } : {}),
     kind: payload?.kind,
     replyTargetPolicy: options?.replyTargetPolicy ?? 'agent-default',
     replyToId: normalizeOutboundReplyToId({

package/src/messaging/outbound/send-params.ts

@@ -9,6 +9,7 @@ export type NormalizedBncrSendParams = {
   mediaUrl?: string;
   asVoice: boolean;
   audioAsVoice: boolean;
+  type?: string;
 };
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -34,6 +35,7 @@ export function normalizeBncrSendParams(input: {
     readOpenClawStringParam(paramsObj, 'mediaUrl', { trim: false });
   const asVoice = readOpenClawBooleanParam(paramsObj, 'asVoice') ?? false;
   const audioAsVoice = readOpenClawBooleanParam(paramsObj, 'audioAsVoice') ?? false;
+  const type = readOpenClawStringParam(paramsObj, 'type') || undefined;
 
   if (asVoice && !mediaUrl) throw new Error('send voice requires media path');
 
@@ -52,5 +54,6 @@ export function normalizeBncrSendParams(input: {
     mediaUrl: mediaUrl || undefined,
     asVoice,
     audioAsVoice,
+    ...(type ? { type } : {}),
   };
 }

package/src/messaging/outbound/send.ts

@@ -1,20 +1,26 @@
+import type { BncrRoute } from '../../core/types.ts';
+
+function normalizeReplyKind(value: unknown): 'tool' | 'block' | 'final' | undefined {
+  return value === 'tool' || value === 'block' || value === 'final' ? value : undefined;
+}
+
 export async function sendBncrText(params: {
   channelId: string;
   accountId: string;
   to: string;
   text: string;
-  kind?: 'tool' | 'block' | 'final';
+  kind?: string;
   replyToId?: string;
   mediaLocalRoots?: readonly string[];
   resolveVerifiedTarget: (
     to: string,
     accountId: string,
-  ) => { sessionKey: string; route: any; displayScope: string };
-  rememberSessionRoute: (sessionKey: string, accountId: string, route: any) => void;
+  ) => { sessionKey: string; route: BncrRoute; displayScope: string };
+  rememberSessionRoute: (sessionKey: string, accountId: string, route: BncrRoute) => void;
   enqueueFromReply: (args: {
     accountId: string;
     sessionKey: string;
-    route: any;
+    route: BncrRoute;
     payload: {
       text?: string;
       mediaUrl?: string;
@@ -35,7 +41,7 @@ export async function sendBncrText(params: {
     route: verified.route,
     payload: {
       text: params.text,
-      kind: params.kind,
+      kind: normalizeReplyKind(params.kind),
       replyToId: params.replyToId,
     },
     mediaLocalRoots: params.mediaLocalRoots,
@@ -57,24 +63,26 @@ export async function sendBncrMedia(params: {
   mediaUrls?: string[];
   asVoice?: boolean;
   audioAsVoice?: boolean;
-  kind?: 'tool' | 'block' | 'final';
+  type?: string;
+  kind?: string;
   replyToId?: string;
   mediaLocalRoots?: readonly string[];
   resolveVerifiedTarget: (
     to: string,
     accountId: string,
-  ) => { sessionKey: string; route: any; displayScope: string };
-  rememberSessionRoute: (sessionKey: string, accountId: string, route: any) => void;
+  ) => { sessionKey: string; route: BncrRoute; displayScope: string };
+  rememberSessionRoute: (sessionKey: string, accountId: string, route: BncrRoute) => void;
   enqueueFromReply: (args: {
     accountId: string;
     sessionKey: string;
-    route: any;
+    route: BncrRoute;
     payload: {
       text?: string;
       mediaUrl?: string;
       mediaUrls?: string[];
       asVoice?: boolean;
       audioAsVoice?: boolean;
+      type?: string;
       kind?: 'tool' | 'block' | 'final';
       replyToId?: string;
     };
@@ -95,7 +103,8 @@ export async function sendBncrMedia(params: {
       mediaUrls: params.mediaUrls?.length ? params.mediaUrls : undefined,
       asVoice: params.asVoice === true ? true : undefined,
       audioAsVoice: params.audioAsVoice === true ? true : undefined,
-      kind: params.kind,
+      type: params.type,
+      kind: normalizeReplyKind(params.kind),
       replyToId: params.replyToId,
     },
     mediaLocalRoots: params.mediaLocalRoots,

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

@@ -1,3 +1,4 @@
+import type { ChannelOutboundSessionRoute } from 'openclaw/plugin-sdk/core';
 import {
   buildCanonicalBncrSessionKey,
   formatDisplayScope,
@@ -7,9 +8,23 @@ import {
 } from '../../core/targets.ts';
 import type { BncrRoute } from '../../core/types.ts';
 import { buildOpenClawChannelOutboundSessionRoute } from '../../openclaw/session-route-runtime.ts';
+import type { BncrChannelConfigRoot } from '../../plugin/channel-runtime-types.ts';
+
+type BncrChannelRouteRefFields = {
+  channel: string;
+  accountId?: string;
+  target: {
+    to: string;
+    rawTo: string;
+    chatType: 'direct' | 'group';
+  };
+  thread?: { id: string };
+};
+
+type BncrOutboundSessionRoute = ChannelOutboundSessionRoute & BncrChannelRouteRefFields;
 
 type ResolveBncrOutboundSessionRouteParams = {
-  cfg: any;
+  cfg: BncrChannelConfigRoot;
   channel: string;
   agentId: string;
   accountId?: string;
@@ -27,13 +42,13 @@ function asString(v: unknown, fallback = ''): string {
 }
 
 function attachBncrChannelRouteRefFields(args: {
-  built: Record<string, unknown>;
+  built: ChannelOutboundSessionRoute;
   channel: string;
   accountId?: string;
   to: string;
   chatType: 'direct' | 'group';
   threadId?: string;
-}) {
+}): BncrOutboundSessionRoute {
   const { built, channel, accountId, to, chatType, threadId } = args;
   return {
     ...built,

package/src/openclaw/channel-runtime-contracts.ts

@@ -0,0 +1,76 @@
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk/core';
+import type { BncrRoute } from '../core/types.ts';
+
+export type OpenClawChannelRuntimeContext = Record<string, unknown> & {
+  BodyForAgent?: string;
+  CommandBody?: string;
+};
+
+export type OpenClawChannelPeer = {
+  kind: 'direct' | 'group';
+  id: string;
+};
+
+export type OpenClawResolvedAgentRoute = {
+  sessionKey?: string;
+  mainSessionKey?: string;
+  route?: BncrRoute;
+  agentId?: string;
+  [key: string]: unknown;
+};
+
+export type OpenClawReplyDispatcherPayload = {
+  text?: string;
+  mediaUrl?: string;
+  mediaUrls?: string[];
+  audioAsVoice?: boolean;
+};
+
+export type OpenClawReplyDispatchInfo = { kind?: 'tool' | 'block' | 'final' };
+
+export type OpenClawInboundRuntimeIngested = {
+  id: string;
+  timestamp: number;
+  rawText: string;
+  textForAgent?: string;
+  textForCommands?: string;
+  raw: unknown;
+};
+
+export type OpenClawInboundRuntimeResolvedTurn = {
+  channel: string;
+  accountId: string;
+  routeSessionKey: string;
+  storePath: string;
+  ctxPayload: OpenClawChannelRuntimeContext;
+  recordInboundSession: (...args: unknown[]) => Promise<unknown> | unknown;
+  record: {
+    updateLastRoute: unknown;
+    onRecordError: (err: unknown) => void;
+  };
+  runDispatch: () => Promise<unknown> | unknown;
+};
+
+export type OpenClawInboundRuntimeAdapter = {
+  ingest: () => OpenClawInboundRuntimeIngested;
+  resolveTurn: () => OpenClawInboundRuntimeResolvedTurn;
+};
+
+export type OpenClawInboundRuntimeRunParams = {
+  channel: string;
+  accountId: string;
+  raw: unknown;
+  adapter: OpenClawInboundRuntimeAdapter;
+  onFinalize?: () => void;
+};
+
+export type OpenClawInboundRuntime = {
+  buildContext: (
+    params: unknown,
+  ) => OpenClawChannelRuntimeContext | Promise<OpenClawChannelRuntimeContext>;
+  run: (params: unknown) => Promise<unknown> | unknown;
+  runPreparedReply?: (params: unknown) => Promise<unknown> | unknown;
+  dispatchReply?: (params: unknown) => Promise<unknown> | unknown;
+};
+
+export type OpenClawChannelRuntimeApiHolder = OpenClawPluginApi;