@xmoxmo/bncr 0.3.6 → 0.3.8

package/src/plugin/bridge-extended-diagnostics-facade.ts

@@ -0,0 +1,149 @@
+import type { buildIntegratedDiagnostics as buildIntegratedDiagnosticsFromRuntime } from '../core/status.ts';
+import type {
+  BncrAckObservability,
+  BncrDeadLetterDiagnosticsSummary,
+  BncrOutboxQueueDiagnostics,
+} from '../core/types.ts';
+import type { OpenClawChannelRuntimeSurfaceDiagnostics } from '../openclaw/runtime-surface.ts';
+import {
+  buildConnectionRuntimeSnapshot,
+  buildOutboundRuntimeSnapshot,
+  buildRegisterRuntimeSnapshot,
+} from './bridge-surface-helpers.ts';
+import { createBncrExtendedDiagnosticsAssembler } from './runtime-diagnostics-snapshot.ts';
+
+type RuntimeStatusInput = Parameters<typeof buildIntegratedDiagnosticsFromRuntime>[0];
+type IntegratedDiagnostics = ReturnType<typeof buildIntegratedDiagnosticsFromRuntime>;
+type ExtendedDiagnosticsOptions = {
+  runtimeStatusInput?: RuntimeStatusInput;
+  integratedDiagnostics?: IntegratedDiagnostics;
+};
+
+export function createBncrBridgeExtendedDiagnosticsFacade(runtime: {
+  normalizeAccountId: (accountId: string) => string;
+  buildIntegratedDiagnostics: (
+    accountId: string,
+    runtimeStatusInput?: RuntimeStatusInput,
+  ) => IntegratedDiagnostics;
+  buildOutboxDiagnostics: (accountId: string) => BncrOutboxQueueDiagnostics;
+  buildRuntimeAckObservability: (accountId: string) => BncrAckObservability;
+  getCounter: (map: Map<string, number>, accountId: string) => number;
+  prePushGuardSkipCountByAccount: Map<string, number>;
+  lastPrePushGuardSkipAtByAccount: Map<string, number>;
+  lastPrePushGuardSkipReasonByAccount: Map<string, string>;
+  hasGatewayContext: () => boolean;
+  buildRuntimeSurfaceDiagnostics: () => OpenClawChannelRuntimeSurfaceDiagnostics;
+  getRegisterState: () => {
+    bridgeId: string;
+    gatewayPid: number;
+    pluginVersion: string | null;
+    pluginSource: string | null;
+    lastApiInstanceId: string | null;
+    lastRegistryFingerprint: string | null;
+    registerCount: number;
+    firstRegisterAt: number | null;
+    lastRegisterAt: number | null;
+    lastApiRebindAt: number | null;
+    apiGeneration: number;
+    registerTraceRecent: ReturnType<typeof buildRegisterRuntimeSnapshot>['registerTraceRecent'];
+    lastDriftSnapshot: ReturnType<typeof buildRegisterRuntimeSnapshot>['lastDriftSnapshot'];
+  };
+  buildRegisterTraceSummary: () => ReturnType<
+    typeof import('../core/register-trace.ts')['buildRegisterTraceSummary']
+  >;
+  activeConnectionCount: (accountId: string) => number;
+  getConnectionState: () => {
+    lastGatewayContextAt: number | null;
+    primaryLeaseId: string | null;
+    connectionEpoch: number;
+    acceptedConnections: number;
+    lastConnectAt: number | null;
+    lastDisconnectAt: number | null;
+    lastActivityAtGlobal: number | null;
+    lastInboundAtGlobal: number | null;
+    lastAckAtGlobal: number | null;
+    recentConnections: ReturnType<typeof buildConnectionRuntimeSnapshot>['recentConnections'];
+  };
+  getOutboundState: () => {
+    outboundEnqueueCountByAccount: Map<string, number>;
+    lastOutboundEnqueueAtByAccount: Map<string, number>;
+  };
+  buildDeadLetterDiagnostics: (accountId: string) => BncrDeadLetterDiagnosticsSummary;
+  bridgeVersion: number;
+  staleCounters: {
+    staleConnect: number;
+    staleInbound: number;
+    staleActivity: number;
+    staleAck: number;
+    staleFileInit: number;
+    staleFileChunk: number;
+    staleFileComplete: number;
+    staleFileAbort: number;
+    lastStaleAt: number | null;
+  };
+  now: () => number;
+}) {
+  const assemble = createBncrExtendedDiagnosticsAssembler({
+    normalizeAccountId: runtime.normalizeAccountId,
+    buildIntegratedDiagnostics: runtime.buildIntegratedDiagnostics,
+    buildOutboxDiagnostics: runtime.buildOutboxDiagnostics,
+    buildRuntimeAckObservability: runtime.buildRuntimeAckObservability,
+    getCounter: runtime.getCounter,
+    prePushGuardSkipCountByAccount: runtime.prePushGuardSkipCountByAccount,
+    lastPrePushGuardSkipAtByAccount: runtime.lastPrePushGuardSkipAtByAccount,
+    lastPrePushGuardSkipReasonByAccount: runtime.lastPrePushGuardSkipReasonByAccount,
+    hasGatewayContext: runtime.hasGatewayContext,
+    buildRuntimeSurfaceDiagnostics: runtime.buildRuntimeSurfaceDiagnostics,
+    getRegisterRuntime: () => {
+      const registerState = runtime.getRegisterState();
+      return buildRegisterRuntimeSnapshot({
+        bridgeId: registerState.bridgeId,
+        gatewayPid: registerState.gatewayPid,
+        pluginVersion: registerState.pluginVersion,
+        pluginSource: registerState.pluginSource,
+        lastApiInstanceId: registerState.lastApiInstanceId,
+        lastRegistryFingerprint: registerState.lastRegistryFingerprint,
+        registerCount: registerState.registerCount,
+        firstRegisterAt: registerState.firstRegisterAt,
+        lastRegisterAt: registerState.lastRegisterAt,
+        lastApiRebindAt: registerState.lastApiRebindAt,
+        apiGeneration: registerState.apiGeneration,
+        registerTraceRecent: registerState.registerTraceRecent,
+        lastDriftSnapshot: registerState.lastDriftSnapshot ?? null,
+      });
+    },
+    buildRegisterTraceSummary: runtime.buildRegisterTraceSummary,
+    activeConnectionCount: runtime.activeConnectionCount,
+    getConnectionRuntime: () => {
+      const connectionState = runtime.getConnectionState();
+      return buildConnectionRuntimeSnapshot({
+        lastGatewayContextAt: connectionState.lastGatewayContextAt,
+        primaryLeaseId: connectionState.primaryLeaseId,
+        connectionEpoch: connectionState.connectionEpoch,
+        acceptedConnections: connectionState.acceptedConnections,
+        lastConnectAt: connectionState.lastConnectAt,
+        lastDisconnectAt: connectionState.lastDisconnectAt,
+        lastActivityAtGlobal: connectionState.lastActivityAtGlobal,
+        lastInboundAtGlobal: connectionState.lastInboundAtGlobal,
+        lastAckAtGlobal: connectionState.lastAckAtGlobal,
+        recentConnections: connectionState.recentConnections,
+      });
+    },
+    getOutboundRuntime: () => {
+      const outboundState = runtime.getOutboundState();
+      return buildOutboundRuntimeSnapshot({
+        outboundEnqueueCountByAccount: outboundState.outboundEnqueueCountByAccount,
+        lastOutboundEnqueueAtByAccount: outboundState.lastOutboundEnqueueAtByAccount,
+      });
+    },
+    buildDeadLetterDiagnostics: runtime.buildDeadLetterDiagnostics,
+    bridgeVersion: runtime.bridgeVersion,
+    staleCounters: runtime.staleCounters,
+    now: runtime.now,
+  });
+
+  return {
+    buildExtendedDiagnostics: (accountId: string, options: ExtendedDiagnosticsOptions = {}) =>
+      assemble(accountId, options),
+  };
+}

package/src/plugin/bridge-file-transfer-push-facade.ts

@@ -0,0 +1,140 @@
+import {
+  buildFileTransferPushOkArgs,
+  buildFileTransferPushSuccessArgs,
+} from '../core/outbox-file-transfer-bookkeeping.ts';
+import {
+  buildFileTransferBroadcastPayload,
+  buildFileTransferRouteSelectArgs,
+} from '../core/outbox-file-transfer-success.ts';
+import type { BncrConnection, BncrRoute, OutboxEntry } from '../core/types.ts';
+
+export function createBncrBridgeFileTransferPushFacade(runtime: {
+  pushEvent: string;
+  getGatewayContext: () => {
+    broadcastToConnIds: (event: string, payload: unknown, connIds: ReadonlySet<string>) => void;
+  } | null;
+  transferMediaToBncrClient: (params: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    mediaUrl: string;
+    mediaLocalRoots?: readonly string[];
+  }) => Promise<{
+    mode: 'base64' | 'chunk';
+    mimeType?: string;
+    fileName?: string;
+    mediaBase64?: string;
+    path?: string;
+  }>;
+  buildFileTransferOutboundFrame: (params: {
+    entry: OutboxEntry;
+    meta: Record<string, unknown>;
+    media: { fileName?: string; mimeType?: string; path?: string; base64?: string; type?: string };
+    mediaUrl: string;
+  }) => Record<string, unknown>;
+  logOutboxRouteSelect: (args: {
+    messageId: string;
+    accountId: string;
+    kind?: 'file-transfer';
+    routeReason: string;
+    connIds: Iterable<string>;
+    ownerConnId: string;
+    ownerClientId: string;
+    recentInboundReachable: boolean;
+    event: string;
+  }) => void;
+  recordOutboxPushSuccess: (args: {
+    entry: OutboxEntry;
+    connIds: Iterable<string>;
+    ownerConnId?: string;
+    ownerClientId?: string;
+    clearLastError?: boolean;
+  }) => void;
+  logOutboxPushOkSummary: (messageId: string) => void;
+  logOutboxPushOk: (args: {
+    messageId: string;
+    accountId: string;
+    kind?: 'file-transfer';
+    connIds: Iterable<string>;
+    ownerConnId: string;
+    ownerClientId: string;
+    recentInboundReachable: boolean;
+    event: string;
+  }) => void;
+  handleFileTransferPushFailure: (args: { entry: OutboxEntry; error: unknown }) => void;
+  handleFileTransferPushGuardFailure: (args: {
+    entry: OutboxEntry;
+    guard: {
+      reason: 'media-url-missing' | 'no-gateway-context' | 'no-active-connection';
+      lastError: string;
+      recentInboundReachable?: boolean;
+    };
+  }) => void;
+}) {
+  const pushFileTransferSuccessPath = async (args: {
+    entry: OutboxEntry;
+    meta: Record<string, unknown>;
+    owner: BncrConnection | null;
+    connIds: Iterable<string>;
+    recentInboundReachable: boolean;
+    routeReason: string;
+    mediaUrl: string;
+  }): Promise<void> => {
+    const media = await runtime.transferMediaToBncrClient({
+      accountId: args.entry.accountId,
+      sessionKey: args.entry.sessionKey,
+      route: args.entry.route,
+      mediaUrl: args.mediaUrl,
+      mediaLocalRoots: Array.isArray(args.meta.mediaLocalRoots)
+        ? args.meta.mediaLocalRoots.filter((v): v is string => typeof v === 'string')
+        : undefined,
+    });
+    const frame = runtime.buildFileTransferOutboundFrame({
+      entry: args.entry,
+      meta: args.meta,
+      media,
+      mediaUrl: args.mediaUrl,
+    });
+
+    runtime.getGatewayContext()!.broadcastToConnIds(
+      runtime.pushEvent,
+      buildFileTransferBroadcastPayload({
+        frame,
+        messageId: args.entry.messageId,
+      }),
+      new Set(args.connIds),
+    );
+    runtime.logOutboxRouteSelect(
+      buildFileTransferRouteSelectArgs({
+        entry: args.entry,
+        connIds: args.connIds,
+        routeReason: args.routeReason,
+        recentInboundReachable: args.recentInboundReachable,
+        owner: args.owner,
+        event: runtime.pushEvent,
+      }),
+    );
+    runtime.recordOutboxPushSuccess(
+      buildFileTransferPushSuccessArgs({
+        entry: args.entry,
+        connIds: args.connIds,
+        owner: args.owner,
+      }),
+    );
+    runtime.logOutboxPushOkSummary(args.entry.messageId);
+    runtime.logOutboxPushOk(
+      buildFileTransferPushOkArgs({
+        entry: args.entry,
+        connIds: args.connIds,
+        recentInboundReachable: args.recentInboundReachable,
+        event: runtime.pushEvent,
+      }),
+    );
+  };
+
+  return {
+    pushFileTransferSuccessPath,
+    handleFileTransferPushFailure: runtime.handleFileTransferPushFailure,
+    handleFileTransferPushGuardFailure: runtime.handleFileTransferPushGuardFailure,
+  };
+}

package/src/plugin/bridge-lifecycle.ts

@@ -0,0 +1,156 @@
+import path from 'node:path';
+import type { OpenClawPluginServiceContext } from 'openclaw/plugin-sdk/core';
+import { BNCR_DEFAULT_ACCOUNT_ID } from '../core/accounts.ts';
+import type { BncrChannelPolicyConfig } from '../core/policy.ts';
+import { resolveBncrConfigWarnings } from '../core/policy.ts';
+import type { BncrChannelConfigRoot } from './channel-runtime-types.ts';
+
+export function buildBncrBridgeCleanupDebugInfo(args: {
+  bridgeId: string;
+  reason: string;
+  messageAckWaiters: number;
+  fileAckWaiters: number;
+  earlyFileAcks: number;
+  outbox: number;
+  runningDrainAccounts: number;
+  channelAccountWorkers: number;
+  hasSaveTimer: boolean;
+  hasPushTimer: boolean;
+}) {
+  return {
+    bridge: args.bridgeId,
+    reason: args.reason,
+    messageAckWaiters: args.messageAckWaiters,
+    fileAckWaiters: args.fileAckWaiters,
+    earlyFileAcks: args.earlyFileAcks,
+    outbox: args.outbox,
+    runningDrainAccounts: args.runningDrainAccounts,
+    channelAccountWorkers: args.channelAccountWorkers,
+    hasSaveTimer: args.hasSaveTimer,
+    hasPushTimer: args.hasPushTimer,
+  };
+}
+
+export function startBncrBridgeService(
+  runtime: {
+    bridgeId: string;
+    setStopped: (value: boolean) => void;
+    setStatePath: (value: string) => void;
+    getRuntimeConfig: () => BncrChannelConfigRoot;
+    initializeCanonicalAgentId: (cfg: BncrChannelConfigRoot) => void;
+    logWarn: (
+      scope: string | undefined,
+      message: string,
+      options?: { debugOnly?: boolean },
+    ) => void;
+    loadState: () => Promise<void>;
+    setDebugFlag: (value: boolean) => void;
+    refreshDebugFlagFromConfig: (options?: { forceLog?: boolean }) => Promise<void>;
+    buildIntegratedDiagnostics: (accountId: string) => {
+      regression: { totalKnownRoutes: number; ok: boolean };
+      health: { pending: number; deadLetter: number };
+    };
+    logInfo: (
+      scope: string | undefined,
+      message: string,
+      options?: { debugOnly?: boolean },
+    ) => void;
+    getChannelConfigRoot: (
+      cfg: BncrChannelConfigRoot,
+    ) => BncrChannelPolicyConfig | null | undefined;
+  },
+  ctx: OpenClawPluginServiceContext,
+  debug?: boolean,
+) {
+  runtime.setStopped(false);
+  runtime.setStatePath(path.join(ctx.stateDir, 'bncr-bridge-state.json'));
+  return (async () => {
+    try {
+      const cfg = runtime.getRuntimeConfig();
+      runtime.initializeCanonicalAgentId(cfg);
+      for (const warning of resolveBncrConfigWarnings(runtime.getChannelConfigRoot(cfg))) {
+        runtime.logWarn('config', warning);
+      }
+    } catch {
+      // ignore startup canonical agent initialization errors
+    }
+    await runtime.loadState();
+    if (typeof debug === 'boolean') runtime.setDebugFlag(debug);
+    await runtime.refreshDebugFlagFromConfig({ forceLog: true });
+    const bootDiag = runtime.buildIntegratedDiagnostics(BNCR_DEFAULT_ACCOUNT_ID);
+    runtime.logInfo(
+      'startup',
+      `bridge=${runtime.bridgeId} routes=${bootDiag.regression.totalKnownRoutes}`,
+    );
+    runtime.logInfo(
+      'debug',
+      `service started bridge=${runtime.bridgeId} diag.ok=${bootDiag.regression.ok} routes=${bootDiag.regression.totalKnownRoutes} pending=${bootDiag.health.pending} dead=${bootDiag.health.deadLetter}`,
+      { debugOnly: true },
+    );
+  })();
+}
+
+export function cleanupBncrBridgeRuntime(
+  runtime: {
+    bridgeId: string;
+    logInfo: (
+      scope: string | undefined,
+      message: string,
+      options?: { debugOnly?: boolean },
+    ) => void;
+    setStopped: (value: boolean) => void;
+    clearAllChannelAccountWorkers: (reason: string) => void;
+    getMessageAckWaiterCount: () => number;
+    getFileAckWaiterCount: () => number;
+    getEarlyFileAckCount: () => number;
+    getOutboxCount: () => number;
+    getRunningDrainAccountCount: () => number;
+    getChannelAccountWorkerCount: () => number;
+    hasSaveTimer: () => boolean;
+    hasPushTimer: () => boolean;
+    clearSaveTimer: () => void;
+    clearPushTimer: () => void;
+    clearAllMessageAckWaiters: (result: 'timeout') => void;
+    clearAllFileAckWaiters: (reason: string) => void;
+  },
+  reason: string,
+) {
+  runtime.logInfo(
+    'lifecycle',
+    `cleanup ${JSON.stringify(
+      buildBncrBridgeCleanupDebugInfo({
+        bridgeId: runtime.bridgeId,
+        reason,
+        messageAckWaiters: runtime.getMessageAckWaiterCount(),
+        fileAckWaiters: runtime.getFileAckWaiterCount(),
+        earlyFileAcks: runtime.getEarlyFileAckCount(),
+        outbox: runtime.getOutboxCount(),
+        runningDrainAccounts: runtime.getRunningDrainAccountCount(),
+        channelAccountWorkers: runtime.getChannelAccountWorkerCount(),
+        hasSaveTimer: runtime.hasSaveTimer(),
+        hasPushTimer: runtime.hasPushTimer(),
+      }),
+    )}`,
+    { debugOnly: true },
+  );
+  runtime.setStopped(true);
+  runtime.clearAllChannelAccountWorkers(reason);
+  runtime.clearSaveTimer();
+  runtime.clearPushTimer();
+  runtime.clearAllMessageAckWaiters('timeout');
+  runtime.clearAllFileAckWaiters(reason);
+}
+
+export async function stopBncrBridgeService(runtime: {
+  cleanupRuntime: (reason: string) => void;
+  flushState: () => Promise<void>;
+  logInfo: (scope: string | undefined, message: string, options?: { debugOnly?: boolean }) => void;
+}) {
+  runtime.cleanupRuntime('service stopped');
+  await runtime.flushState();
+  runtime.logInfo('debug', 'service stopped', { debugOnly: true });
+}
+
+export function shutdownBncrBridgeService(runtime: { cleanupRuntime: (reason: string) => void }) {
+  runtime.cleanupRuntime('shutdown');
+}

package/src/plugin/bridge-media-facade.ts

@@ -0,0 +1,241 @@
+import type { BncrRoute, FileSendTransferState } from '../core/types.ts';
+import type {
+  NormalizedReplyPayload,
+  OutboundReplyTargetPolicy,
+  ReplyMediaEntriesParams,
+  ReplyPayloadInput,
+} from '../messaging/outbound/reply-enqueue.ts';
+import type { OpenClawLoadedMedia } from '../openclaw/media-runtime.ts';
+import { loadOpenClawWebMedia } from '../openclaw/media-runtime.ts';
+
+type RuntimeMediaApiHolder = Parameters<typeof loadOpenClawWebMedia>[0];
+
+export function createBncrBridgeMediaFacade(runtime: {
+  getApi: () => RuntimeMediaApiHolder;
+  resolveOutboundFileName: (args: {
+    mediaUrl: string;
+    fileName?: string;
+    mimeType?: string;
+  }) => string;
+  outboxRoute: {
+    buildTransferRouteDiagnostics: (args: {
+      accountId: string;
+      recentInboundReachable: boolean;
+    }) => unknown;
+    selectTransferConnIds: (args: {
+      directConnIds: Set<string>;
+      recentConnIds: Set<string>;
+      recentInboundReachable: boolean;
+    }) => ReadonlySet<string>;
+  };
+  fileTransferOrchestrator: {
+    waitChunkAck: (params: {
+      transferId: string;
+      chunkIndex: number;
+      timeoutMs?: number;
+    }) => Promise<void>;
+    waitCompleteAck: (params: {
+      transferId: string;
+      timeoutMs?: number;
+    }) => Promise<{ path: string }>;
+    transferMediaToBncrClient: (params: {
+      accountId: string;
+      sessionKey: string;
+      route: BncrRoute;
+      mediaUrl: string;
+      mediaLocalRoots?: readonly string[];
+    }) => Promise<{
+      mode: 'base64' | 'chunk';
+      mimeType?: string;
+      fileName?: string;
+      mediaBase64?: string;
+      path?: string;
+    }>;
+  };
+  replyMediaOrchestrator: {
+    enqueueFromReply: (params: {
+      accountId: string;
+      sessionKey: string;
+      route: BncrRoute;
+      payload: ReplyPayloadInput;
+      mediaLocalRoots?: readonly string[];
+      replyTargetPolicy?: OutboundReplyTargetPolicy;
+    }) => void;
+    enqueueReplyMediaEntries: (params: ReplyMediaEntriesParams) => void;
+  };
+  logInfoJson: (
+    scope: string | undefined,
+    event: string,
+    payload: Record<string, unknown>,
+    options?: { debugOnly?: boolean },
+  ) => void;
+  buildEnqueueFromReplyDebugInfo: (args: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    payload: NormalizedReplyPayload;
+  }) => Record<string, unknown>;
+  fileTransferLogs: {
+    logFileChunkDiag: (args: {
+      accountId: string;
+      sessionKey: string;
+      mediaUrl: string;
+      hasGatewayContext: boolean;
+      activeConnectionKey: string | null;
+      ownerConnId?: string;
+      ownerClientId?: string;
+      directConnIds: Iterable<string>;
+      recentInboundReachable: boolean;
+      recentConnIds: Iterable<string>;
+      accountConnections: Array<{
+        connId: string;
+        clientId?: string;
+        connectedAt: number;
+        lastSeenAt: number;
+      }>;
+    }) => void;
+    logFileTransferStart: (args: {
+      transferId: string;
+      accountId: string;
+      sessionKey: string;
+      mediaUrl: string;
+      fileName: string;
+      mimeType?: string;
+      fileSize: number;
+      chunkSize: number;
+      totalChunks: number;
+      connIds: ReadonlySet<string>;
+      ownerConnId?: string;
+      ownerClientId?: string;
+    }) => void;
+    logFileTransferChunkSend: (args: {
+      transferId: string;
+      accountId: string;
+      chunkIndex: number;
+      attempt: number;
+      offset: number;
+      size: number;
+      connIds: ReadonlySet<string>;
+    }) => void;
+    logFileTransferChunkAck: (args: {
+      transferId: string;
+      accountId: string;
+      chunkIndex: number;
+      attempt: number;
+    }) => void;
+    logFileTransferChunkAckFail: (args: {
+      transferId: string;
+      accountId: string;
+      chunkIndex: number;
+      attempt: number;
+      error: unknown;
+    }) => void;
+    logFileTransferCompleteSend: (args: {
+      transferId: string;
+      accountId: string;
+      connIds: ReadonlySet<string>;
+    }) => void;
+    logFileTransferCompleteAck: (args: {
+      transferId: string;
+      accountId: string;
+      payload: { path: string };
+    }) => void;
+    buildInitialFileSendTransferState: (args: {
+      transferId: string;
+      accountId: string;
+      sessionKey: string;
+      route: BncrRoute;
+      fileName: string;
+      mimeType?: string;
+      fileSize: number;
+      chunkSize: number;
+      totalChunks: number;
+      fileSha256: string;
+      ownerConnId?: string;
+      ownerClientId?: string;
+      normalizeAccountId: (accountId: string) => string;
+    }) => FileSendTransferState;
+  };
+  normalizeAccountId: (accountId: string) => string;
+}) {
+  const loadOutboundTransferMedia = async (params: {
+    mediaUrl: string;
+    mediaLocalRoots?: readonly string[];
+  }): Promise<{
+    loaded: OpenClawLoadedMedia;
+    size: number;
+    mimeType?: string;
+    fileName: string;
+  }> => {
+    const loaded = await loadOpenClawWebMedia(runtime.getApi(), params.mediaUrl, {
+      localRoots: params.mediaLocalRoots,
+      maxBytes: 50 * 1024 * 1024,
+    });
+    const size = loaded.buffer.byteLength;
+    const mimeType = loaded.contentType;
+    const fileName = runtime.resolveOutboundFileName({
+      mediaUrl: params.mediaUrl,
+      fileName: loaded.fileName,
+      mimeType,
+    });
+    return { loaded, size, mimeType, fileName };
+  };
+
+  const logEnqueueFromReply = (args: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    payload: NormalizedReplyPayload;
+  }) => {
+    runtime.logInfoJson(
+      'outbound',
+      'enqueue-from-reply',
+      runtime.buildEnqueueFromReplyDebugInfo(args),
+      {
+        debugOnly: true,
+      },
+    );
+  };
+
+  return {
+    loadOutboundTransferMedia,
+    buildTransferRouteDiagnostics: (args: { accountId: string; recentInboundReachable: boolean }) =>
+      runtime.outboxRoute.buildTransferRouteDiagnostics(args),
+    selectTransferConnIds: (args: {
+      directConnIds: Set<string>;
+      recentConnIds: Set<string>;
+      recentInboundReachable: boolean;
+    }) => runtime.outboxRoute.selectTransferConnIds(args),
+    waitChunkAck: runtime.fileTransferOrchestrator.waitChunkAck,
+    waitCompleteAck: runtime.fileTransferOrchestrator.waitCompleteAck,
+    transferMediaToBncrClient: runtime.fileTransferOrchestrator.transferMediaToBncrClient,
+    enqueueFromReply: runtime.replyMediaOrchestrator.enqueueFromReply,
+    enqueueReplyMediaEntries: runtime.replyMediaOrchestrator.enqueueReplyMediaEntries,
+    logEnqueueFromReply,
+    logFileChunkDiag: runtime.fileTransferLogs.logFileChunkDiag,
+    logFileTransferStart: runtime.fileTransferLogs.logFileTransferStart,
+    logFileTransferChunkSend: runtime.fileTransferLogs.logFileTransferChunkSend,
+    logFileTransferChunkAck: runtime.fileTransferLogs.logFileTransferChunkAck,
+    logFileTransferChunkAckFail: runtime.fileTransferLogs.logFileTransferChunkAckFail,
+    logFileTransferCompleteSend: runtime.fileTransferLogs.logFileTransferCompleteSend,
+    logFileTransferCompleteAck: runtime.fileTransferLogs.logFileTransferCompleteAck,
+    buildInitialFileSendTransferState: (args: {
+      transferId: string;
+      accountId: string;
+      sessionKey: string;
+      route: BncrRoute;
+      fileName: string;
+      mimeType?: string;
+      fileSize: number;
+      chunkSize: number;
+      totalChunks: number;
+      fileSha256: string;
+      ownerConnId?: string;
+      ownerClientId?: string;
+    }) =>
+      runtime.fileTransferLogs.buildInitialFileSendTransferState({
+        ...args,
+        normalizeAccountId: runtime.normalizeAccountId,
+      }),
+  };
+}