@xmoxmo/bncr 0.3.5 → 0.3.7

package/src/openclaw/config-runtime.ts

@@ -1,6 +1,8 @@
+import type { BncrChannelConfigRoot } from '../plugin/channel-runtime-types.ts';
+
 type RuntimeConfigApi = {
-  current?: () => unknown;
-  get?: () => unknown;
+  current?: () => BncrChannelConfigRoot;
+  get?: () => BncrChannelConfigRoot;
   mutateConfigFile?: (params: {
     afterWrite?: { mode?: string };
     mutate: (draft: Record<string, unknown>) => void;
@@ -9,17 +11,21 @@ type RuntimeConfigApi = {
 
 type RuntimeApiHolder = {
   runtime?: {
-    config?: RuntimeConfigApi;
+    config?: unknown;
+    [key: string]: unknown;
   };
+  [key: string]: unknown;
 };
 
 function resolveConfigApi(api: RuntimeApiHolder): RuntimeConfigApi {
   const config = api?.runtime?.config;
-  if (!config) throw new Error('OpenClaw runtime config API is unavailable');
-  return config;
+  if (!config || typeof config !== 'object') {
+    throw new Error('OpenClaw runtime config API is unavailable');
+  }
+  return config as RuntimeConfigApi;
 }
 
-export function getOpenClawRuntimeConfig(api: RuntimeApiHolder): unknown {
+export function getOpenClawRuntimeConfig(api: RuntimeApiHolder): BncrChannelConfigRoot {
   const config = resolveConfigApi(api);
   if (typeof config.current === 'function') return config.current();
   if (typeof config.get === 'function') return config.get();
@@ -29,7 +35,7 @@ export function getOpenClawRuntimeConfig(api: RuntimeApiHolder): unknown {
 export function getOpenClawRuntimeConfigOrDefault<T>(
   api: RuntimeApiHolder,
   fallback: T,
-): unknown | T {
+): BncrChannelConfigRoot | T {
   try {
     return getOpenClawRuntimeConfig(api);
   } catch {

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

@@ -5,8 +5,12 @@ import {
   resolveStorePath as sdkResolveStorePath,
   updateSessionStoreEntry as sdkUpdateSessionStoreEntry,
 } from 'openclaw/plugin-sdk/session-store-runtime';
+import type { OpenClawChannelRuntimeApiHolder } from './channel-runtime-contracts.ts';
 
-type ResolveStorePathFn = (storeConfig: unknown, options: { agentId: string }) => string;
+type ResolveStorePathFn = (
+  storeConfig?: string,
+  options?: { agentId?: string; env?: NodeJS.ProcessEnv },
+) => string;
 type RecordInboundSessionFn = typeof sdkRecordInboundSession;
 type RecordSessionMetaFromInboundFn = typeof sdkRecordSessionMetaFromInbound;
 type UpdateSessionStoreEntryFn = typeof sdkUpdateSessionStoreEntry;
@@ -40,7 +44,7 @@ function resolveRuntime(): BncrInboundSessionRuntime {
 }
 
 export function resolveBncrInboundSessionStorePath(args: {
-  storeConfig: unknown;
+  storeConfig?: string;
   agentId: string;
 }): string {
   return resolveRuntime().resolveStorePath(args.storeConfig, { agentId: args.agentId });
@@ -65,7 +69,7 @@ export function updateBncrSessionStoreEntry(
 }
 
 export function readBncrSessionUpdatedAt(
-  api: { runtime?: { channel?: { session?: { readSessionUpdatedAt?: ReadSessionUpdatedAtFn } } } },
+  api: OpenClawChannelRuntimeApiHolder,
   params: { storePath: string; sessionKey: string },
 ): unknown {
   const runtime = resolveRuntime();

package/src/openclaw/ingress-runtime.ts

@@ -3,33 +3,23 @@ import {
   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);
+type StableChannelIngressIdentityParams = Parameters<
+  typeof sdkDefineStableChannelIngressIdentity
+>[0];
+
+type ResolveChannelMessageIngressParams = Parameters<typeof sdkResolveChannelMessageIngress>[0];
+type ResolveChannelMessageIngressResult = Awaited<
+  ReturnType<typeof sdkResolveChannelMessageIngress>
+>;
+
+export function defineOpenClawStableChannelIngressIdentity(
+  params: StableChannelIngressIdentityParams,
+) {
+  return sdkDefineStableChannelIngressIdentity(params);
 }
 
-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);
+export async function resolveOpenClawChannelMessageIngress(
+  params: ResolveChannelMessageIngressParams,
+): Promise<ResolveChannelMessageIngressResult> {
+  return sdkResolveChannelMessageIngress(params);
 }

package/src/openclaw/reply-runtime.ts

@@ -1,59 +1,32 @@
-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;
-    };
-  };
-};
+import type {
+  OpenClawChannelRuntimeApiHolder,
+  OpenClawChannelRuntimeContext,
+  OpenClawReplyDispatcherPayload,
+  OpenClawReplyDispatchInfo,
+} from './channel-runtime-contracts.ts';
 
-function resolveReplyApi(api: RuntimeApiHolder): RuntimeReplyApi {
+function resolveReplyApi(api: OpenClawChannelRuntimeApiHolder): Record<string, unknown> {
   const reply = api?.runtime?.channel?.reply;
-  if (!reply) throw new Error('OpenClaw channel reply API is unavailable');
-  return reply;
+  if (!reply || typeof reply !== 'object') {
+    throw new Error('OpenClaw channel reply API is unavailable');
+  }
+  return reply as Record<string, unknown>;
 }
 
-export function resolveOpenClawEnvelopeFormatOptions(api: RuntimeApiHolder, cfg: unknown): unknown {
+export function resolveOpenClawEnvelopeFormatOptions(
+  api: OpenClawChannelRuntimeApiHolder,
+  cfg: unknown,
+): unknown {
   const reply = resolveReplyApi(api);
-  if (typeof reply.resolveEnvelopeFormatOptions !== 'function') {
+  const resolveEnvelopeFormatOptions = reply.resolveEnvelopeFormatOptions;
+  if (typeof resolveEnvelopeFormatOptions !== 'function') {
     throw new Error('OpenClaw channel reply resolveEnvelopeFormatOptions API is unavailable');
   }
-  return reply.resolveEnvelopeFormatOptions(cfg);
+  return resolveEnvelopeFormatOptions(cfg);
 }
 
 export function formatOpenClawAgentEnvelope(
-  api: RuntimeApiHolder,
+  api: OpenClawChannelRuntimeApiHolder,
   params: {
     channel: string;
     from: string;
@@ -64,26 +37,31 @@ export function formatOpenClawAgentEnvelope(
   },
 ): string {
   const reply = resolveReplyApi(api);
-  if (typeof reply.formatAgentEnvelope !== 'function') {
+  const formatAgentEnvelope = reply.formatAgentEnvelope as
+    | ((params: {
+        channel: string;
+        from: string;
+        timestamp: number;
+        previousTimestamp?: unknown;
+        envelope?: unknown;
+        body: string;
+      }) => string)
+    | undefined;
+  if (typeof formatAgentEnvelope !== 'function') {
     throw new Error('OpenClaw channel reply formatAgentEnvelope API is unavailable');
   }
-  return reply.formatAgentEnvelope(params);
+  return formatAgentEnvelope(params);
 }
 
 export async function dispatchOpenClawReplyWithBufferedBlockDispatcher(
-  api: RuntimeApiHolder,
+  api: OpenClawChannelRuntimeApiHolder,
   params: {
-    ctx: unknown;
+    ctx: OpenClawChannelRuntimeContext;
     cfg: unknown;
     dispatcherOptions: {
       deliver: (
-        payload: {
-          text?: string;
-          mediaUrl?: string;
-          mediaUrls?: string[];
-          audioAsVoice?: boolean;
-        },
-        info?: { kind?: 'tool' | 'block' | 'final' },
+        payload: OpenClawReplyDispatcherPayload,
+        info?: OpenClawReplyDispatchInfo,
       ) => Promise<void> | void;
       onError?: (err: unknown) => void;
     };
@@ -94,10 +72,27 @@ export async function dispatchOpenClawReplyWithBufferedBlockDispatcher(
   },
 ): Promise<unknown> {
   const reply = resolveReplyApi(api);
-  if (typeof reply.dispatchReplyWithBufferedBlockDispatcher !== 'function') {
+  const dispatchReplyWithBufferedBlockDispatcher = reply.dispatchReplyWithBufferedBlockDispatcher as
+    | ((params: {
+        ctx: OpenClawChannelRuntimeContext;
+        cfg: unknown;
+        dispatcherOptions: {
+          deliver: (
+            payload: OpenClawReplyDispatcherPayload,
+            info?: OpenClawReplyDispatchInfo,
+          ) => Promise<void> | void;
+          onError?: (err: unknown) => void;
+        };
+        replyOptions?: {
+          disableBlockStreaming?: boolean;
+          shouldEmitToolResult?: () => boolean;
+        };
+      }) => Promise<unknown> | unknown)
+    | undefined;
+  if (typeof dispatchReplyWithBufferedBlockDispatcher !== 'function') {
     throw new Error(
       'OpenClaw channel reply dispatchReplyWithBufferedBlockDispatcher API is unavailable',
     );
   }
-  return reply.dispatchReplyWithBufferedBlockDispatcher(params);
+  return dispatchReplyWithBufferedBlockDispatcher(params);
 }

package/src/openclaw/routing-runtime.ts

@@ -1,37 +1,43 @@
+import { buildChannelOutboundSessionRoute } from 'openclaw/plugin-sdk/core';
 import { resolveInboundLastRouteSessionKey } from 'openclaw/plugin-sdk/routing';
+import type { BncrChannelConfigRoot } from '../plugin/channel-runtime-types.ts';
+import type {
+  OpenClawChannelRuntimeApiHolder,
+  OpenClawResolvedAgentRoute,
+} from './channel-runtime-contracts.ts';
 
-type RuntimeRoutingApi = {
+export type { OpenClawResolvedAgentRoute } from './channel-runtime-contracts.ts';
+
+type OpenClawRoutingApi = {
   resolveAgentRoute?: (params: {
-    cfg: any;
+    cfg: BncrChannelConfigRoot;
     channel: string;
     accountId: string;
     peer: unknown;
-  }) => any;
+  }) => OpenClawResolvedAgentRoute;
 };
 
-type RuntimeApiHolder = {
-  runtime?: {
-    channel?: {
-      routing?: RuntimeRoutingApi;
-    };
-  };
-};
+type BuildChannelOutboundSessionRouteParams = Parameters<
+  typeof buildChannelOutboundSessionRoute
+>[0];
 
-function resolveRoutingApi(api: RuntimeApiHolder): RuntimeRoutingApi {
+function resolveRoutingApi(api: OpenClawChannelRuntimeApiHolder): OpenClawRoutingApi {
   const routing = api?.runtime?.channel?.routing;
-  if (!routing) throw new Error('OpenClaw channel routing API is unavailable');
-  return routing;
+  if (!routing || typeof routing !== 'object') {
+    throw new Error('OpenClaw channel routing API is unavailable');
+  }
+  return routing as OpenClawRoutingApi;
 }
 
 export function resolveOpenClawAgentRoute(
-  api: RuntimeApiHolder,
+  api: OpenClawChannelRuntimeApiHolder,
   params: {
-    cfg: any;
+    cfg: BncrChannelConfigRoot;
     channel: string;
     accountId: string;
     peer: unknown;
   },
-): any {
+): OpenClawResolvedAgentRoute {
   const routing = resolveRoutingApi(api);
   if (typeof routing.resolveAgentRoute !== 'function') {
     throw new Error('OpenClaw channel routing resolveAgentRoute API is unavailable');
@@ -40,8 +46,19 @@ export function resolveOpenClawAgentRoute(
 }
 
 export function resolveOpenClawInboundLastRouteSessionKey(params: {
-  route: unknown;
+  route: { lastRoutePolicy?: 'main' | 'session'; mainSessionKey: string };
   sessionKey: string;
 }): string {
-  return resolveInboundLastRouteSessionKey(params as any);
+  return resolveInboundLastRouteSessionKey(
+    params as {
+      route: { lastRoutePolicy: 'main' | 'session'; mainSessionKey: string };
+      sessionKey: string;
+    },
+  );
+}
+
+export function buildOpenClawChannelOutboundSessionRoute(
+  params: BuildChannelOutboundSessionRouteParams,
+) {
+  return buildChannelOutboundSessionRoute(params);
 }

package/src/openclaw/runtime-surface.ts

@@ -1,4 +1,103 @@
+type RuntimeSurfaceContractKind = 'object' | 'function' | 'functionAnyOf';
+
+type RuntimeSurfaceContract = {
+  key: string;
+  kind: RuntimeSurfaceContractKind;
+  path?: readonly string[];
+  anyOf?: readonly (readonly string[])[];
+  parent?: readonly string[];
+};
+
+export const OPENCLAW_RUNTIME_SURFACE_CONTRACTS = [
+  { key: 'runtime.config', kind: 'object', path: ['runtime', 'config'] },
+  {
+    key: 'runtime.config.current|get',
+    kind: 'functionAnyOf',
+    anyOf: [
+      ['runtime', 'config', 'current'],
+      ['runtime', 'config', 'get'],
+    ],
+    parent: ['runtime', 'config'],
+  },
+  {
+    key: 'runtime.config.mutateConfigFile',
+    kind: 'function',
+    path: ['runtime', 'config', 'mutateConfigFile'],
+    parent: ['runtime', 'config'],
+  },
+  { key: 'runtime.media', kind: 'object', path: ['runtime', 'media'] },
+  {
+    key: 'runtime.media.loadWebMedia',
+    kind: 'function',
+    path: ['runtime', 'media', 'loadWebMedia'],
+    parent: ['runtime', 'media'],
+  },
+  { key: 'runtime.channel.inbound', kind: 'object', path: ['runtime', 'channel', 'inbound'] },
+  {
+    key: 'runtime.channel.inbound.buildContext',
+    kind: 'function',
+    path: ['runtime', 'channel', 'inbound', 'buildContext'],
+    parent: ['runtime', 'channel', 'inbound'],
+  },
+  {
+    key: 'runtime.channel.inbound.run',
+    kind: 'function',
+    path: ['runtime', 'channel', 'inbound', 'run'],
+    parent: ['runtime', 'channel', 'inbound'],
+  },
+  { key: 'runtime.channel.media', kind: 'object', path: ['runtime', 'channel', 'media'] },
+  {
+    key: 'runtime.channel.media.readRemoteMediaBuffer',
+    kind: 'function',
+    path: ['runtime', 'channel', 'media', 'readRemoteMediaBuffer'],
+    parent: ['runtime', 'channel', 'media'],
+  },
+  {
+    key: 'runtime.channel.media.saveMediaBuffer',
+    kind: 'function',
+    path: ['runtime', 'channel', 'media', 'saveMediaBuffer'],
+    parent: ['runtime', 'channel', 'media'],
+  },
+  { key: 'runtime.channel.reply', kind: 'object', path: ['runtime', 'channel', 'reply'] },
+  {
+    key: 'runtime.channel.reply.resolveEnvelopeFormatOptions',
+    kind: 'function',
+    path: ['runtime', 'channel', 'reply', 'resolveEnvelopeFormatOptions'],
+    parent: ['runtime', 'channel', 'reply'],
+  },
+  {
+    key: 'runtime.channel.reply.formatAgentEnvelope',
+    kind: 'function',
+    path: ['runtime', 'channel', 'reply', 'formatAgentEnvelope'],
+    parent: ['runtime', 'channel', 'reply'],
+  },
+  {
+    key: 'runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher',
+    kind: 'function',
+    path: ['runtime', 'channel', 'reply', 'dispatchReplyWithBufferedBlockDispatcher'],
+    parent: ['runtime', 'channel', 'reply'],
+  },
+  { key: 'runtime.channel.routing', kind: 'object', path: ['runtime', 'channel', 'routing'] },
+  {
+    key: 'runtime.channel.routing.resolveAgentRoute',
+    kind: 'function',
+    path: ['runtime', 'channel', 'routing', 'resolveAgentRoute'],
+    parent: ['runtime', 'channel', 'routing'],
+  },
+  { key: 'runtime.channel.session', kind: 'object', path: ['runtime', 'channel', 'session'] },
+  {
+    key: 'runtime.channel.session.readSessionUpdatedAt',
+    kind: 'function',
+    path: ['runtime', 'channel', 'session', 'readSessionUpdatedAt'],
+    parent: ['runtime', 'channel', 'session'],
+  },
+] as const satisfies readonly RuntimeSurfaceContract[];
+
 export type OpenClawChannelRuntimeSurfaceDiagnostics = {
+  runtime: {
+    config: boolean;
+    media: boolean;
+  };
   channel: {
     inbound: boolean;
     media: boolean;
@@ -6,24 +105,69 @@ export type OpenClawChannelRuntimeSurfaceDiagnostics = {
     routing: boolean;
     session: boolean;
   };
+  channelMedia: {
+    readRemoteMediaBuffer: boolean;
+    saveMediaBuffer: boolean;
+  };
+  contract: Record<string, boolean>;
   missing: string[];
 };
 
+function getPathValue(root: unknown, path: readonly string[] | undefined): unknown {
+  let current: unknown = root;
+  for (const key of path ?? []) {
+    if (!current || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+function hasObject(root: unknown, path: readonly string[] | undefined): boolean {
+  const value = getPathValue(root, path);
+  return Boolean(value && typeof value === 'object');
+}
+
+function hasFunction(root: unknown, path: readonly string[] | undefined): boolean {
+  return typeof getPathValue(root, path) === 'function';
+}
+
+function evaluateRuntimeSurfaceContract(root: unknown, spec: RuntimeSurfaceContract): boolean {
+  if (spec.parent && !hasObject(root, spec.parent)) return false;
+  if (spec.kind === 'object') return hasObject(root, spec.path);
+  if (spec.kind === 'function') return hasFunction(root, spec.path);
+  return Boolean(spec.anyOf?.some((path) => hasFunction(root, path)));
+}
+
 export function buildOpenClawChannelRuntimeSurfaceDiagnostics(
   api: unknown,
 ): OpenClawChannelRuntimeSurfaceDiagnostics {
-  const channelRuntime = (api as any)?.runtime?.channel;
-  const surfaces = {
-    inbound: Boolean(channelRuntime?.inbound),
-    media: Boolean(channelRuntime?.media),
-    reply: Boolean(channelRuntime?.reply),
-    routing: Boolean(channelRuntime?.routing),
-    session: Boolean(channelRuntime?.session),
-  };
+  const contract = Object.fromEntries(
+    OPENCLAW_RUNTIME_SURFACE_CONTRACTS.map((spec) => [
+      spec.key,
+      evaluateRuntimeSurfaceContract(api, spec),
+    ]),
+  ) as Record<string, boolean>;
+  const missing = OPENCLAW_RUNTIME_SURFACE_CONTRACTS.filter((spec) => !contract[spec.key]).map(
+    (spec) => spec.key,
+  );
+
   return {
-    channel: surfaces,
-    missing: Object.entries(surfaces)
-      .filter(([, present]) => !present)
-      .map(([name]) => name),
+    runtime: {
+      config: contract['runtime.config'],
+      media: contract['runtime.media'],
+    },
+    channel: {
+      inbound: contract['runtime.channel.inbound'],
+      media: contract['runtime.channel.media'],
+      reply: contract['runtime.channel.reply'],
+      routing: contract['runtime.channel.routing'],
+      session: contract['runtime.channel.session'],
+    },
+    channelMedia: {
+      readRemoteMediaBuffer: contract['runtime.channel.media.readRemoteMediaBuffer'],
+      saveMediaBuffer: contract['runtime.channel.media.saveMediaBuffer'],
+    },
+    contract,
+    missing,
   };
 }

package/src/openclaw/sdk-helpers.ts

@@ -10,14 +10,21 @@ import {
 } 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 type { ChannelToolSend } from 'openclaw/plugin-sdk/tool-send';
 import { extractToolSend as sdkExtractToolSend } from 'openclaw/plugin-sdk/tool-send';
 
+export type OpenClawChannelToolSend = ChannelToolSend;
+
 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 extractOpenClawToolSend = (
+  args: Record<string, unknown>,
+  fallbackAction?: string,
+): ChannelToolSend | null =>
+  (sdkExtractToolSend(args, fallbackAction) as ChannelToolSend | null) || null;
 export const openClawJsonResult = sdkJsonResult;
 export const applyOpenClawAccountNameToChannelSection = sdkApplyAccountNameToChannelSection;
 export const setOpenClawAccountEnabledInConfigSection = sdkSetAccountEnabledInConfigSection;

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

@@ -1,15 +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>;
+export type OpenClawChannelOutboundSessionRouteParams = Parameters<
+  typeof buildChannelOutboundSessionRoute
+>[0];
+
+export type OpenClawChannelOutboundSessionRouteResult = ReturnType<
+  typeof buildChannelOutboundSessionRoute
+>;
+
+export function buildOpenClawChannelOutboundSessionRoute(
+  params: OpenClawChannelOutboundSessionRouteParams,
+): OpenClawChannelOutboundSessionRouteResult {
+  return buildChannelOutboundSessionRoute(params);
 }