@xmoxmo/bncr 0.6.0 → 0.6.1

package/README.md

@@ -81,6 +81,13 @@ openclaw devices approve --latest
 - 状态诊断
 - 文件互传
 
+### 0.6.1 新增说明
+
+- `bncr.outbound.recent`：本地 bridge 方法，可直接查询最近的出站记录；该记录来自出站重放缓存，不额外维护一份独立最近出站存储。
+- 出站重放缓存：最近出站消息会在下轮入站上下文回灌时带给 agent，用于让 agent 知道自己刚发过什么；查询和回灌共享同一份 `outboundReplayCache`。
+- bridge 方法调用：`message` 工具支持传入 `bridgeMethod`，可调用插件本地方法（如 `bncr.status.*`、`bncr.outbound.recent`）或转发到 OpenClawClient RPC。
+- unsend / delete：`message` 工具支持撤回/删除动作，按发送缓存映射回真实平台消息，不需要业务侧单独拼平台 message id。
+
 补充口径：
 
 - 入站会话按正式 scene / route 语义接入 OpenClaw，区分私聊与群聊会话。
@@ -285,6 +292,7 @@ npm pack
 - `npm run typecheck`：执行 `tsconfig.typecheck.json`，确保类型边界与 OpenClaw surface 对齐
 - `npm run selfcheck`：检查插件骨架是否完整，并验证关键 OpenClaw SDK subpath 可解析
 - `npm run check-pack`：执行 `npm pack --dry-run --json`，确认发布包包含关键入口与 OpenClaw adapter 文件
+- `tests/integrity/source-manifest.test.mjs`：确保 `selfcheck` / `check-pack` 的源文件清单与当前 `src/**/*.ts` 一致，新增源文件不会漏进发布清单
 - `npm run format:check`：执行 Biome `format` 只读检查（不带 `--write`），防止格式漂移混进发布门禁
 - `npm pack`：确认当前版本可正常打包
 - `npm run check-register-drift -- --duration-sec 300 --interval-sec 15`：静置采样 `bncr.diagnostics`，观察 `registerCount / apiGeneration / postWarmupRegisterCount` 是否在 warmup 后继续增长

package/dist/index.js

@@ -626,6 +626,7 @@ function createBncrRegisterRuntime() {
     "bncr.diagnostics": (bridge, opts) => bridge.handleDiagnostics(opts),
     "bncr.deadLetter.inspect": (bridge, opts) => bridge.handleDeadLetterInspect(opts),
     "bncr.deadLetter.prune": (bridge, opts) => bridge.handleDeadLetterPrune(opts),
+    "bncr.rpc.response": (bridge, opts) => bridge.handleRpcResponse(opts),
     "bncr.file.init": (bridge, opts) => bridge.handleFileInit(opts),
     "bncr.file.chunk": (bridge, opts) => bridge.handleFileChunk(opts),
     "bncr.file.complete": (bridge, opts) => bridge.handleFileComplete(opts),
@@ -936,6 +937,7 @@ var plugin = {
     ensureGatewayMethodRegistered(api, "bncr.diagnostics", debugLog);
     ensureGatewayMethodRegistered(api, "bncr.deadLetter.inspect", debugLog);
     ensureGatewayMethodRegistered(api, "bncr.deadLetter.prune", debugLog);
+    ensureGatewayMethodRegistered(api, "bncr.rpc.response", debugLog);
     ensureGatewayMethodRegistered(api, "bncr.file.init", debugLog);
     ensureGatewayMethodRegistered(api, "bncr.file.chunk", debugLog);
     ensureGatewayMethodRegistered(api, "bncr.file.complete", debugLog);

package/index.ts

@@ -208,6 +208,7 @@ const plugin = {
     ensureGatewayMethodRegistered(api, 'bncr.diagnostics', debugLog);
     ensureGatewayMethodRegistered(api, 'bncr.deadLetter.inspect', debugLog);
     ensureGatewayMethodRegistered(api, 'bncr.deadLetter.prune', debugLog);
+    ensureGatewayMethodRegistered(api, 'bncr.rpc.response', debugLog);
     ensureGatewayMethodRegistered(api, 'bncr.file.init', debugLog);
     ensureGatewayMethodRegistered(api, 'bncr.file.chunk', debugLog);
     ensureGatewayMethodRegistered(api, 'bncr.file.complete', debugLog);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmoxmo/bncr",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -62,5 +62,8 @@
     "runtimeExtensions": [
       "./dist/index.js"
     ]
+  },
+  "dependencies": {
+    "typebox": "^1.3.10"
   }
 }

package/scripts/check-pack.mjs

@@ -48,7 +48,6 @@ const requiredSourceFiles = [
   'src/core/outbox-summary.ts',
   'src/core/outbox-text-push-failure.ts',
   'src/core/outbox-text-push-guards.ts',
-  'src/core/outbox-text-push-prep.ts',
   'src/core/outbox-text-push-success.ts',
   'src/core/permissions.ts',
   'src/core/persisted-outbox-entry.ts',
@@ -68,6 +67,7 @@ const requiredSourceFiles = [
   'src/messaging/inbound/media-url-download.ts',
   'src/messaging/inbound/native-command.ts',
   'src/messaging/inbound/native-reply-delivery.ts',
+  'src/messaging/inbound/outbound-replay-cache.ts',
   'src/messaging/inbound/parse.ts',
   'src/messaging/inbound/remote-media.ts',
   'src/messaging/inbound/reply-config.ts',
@@ -109,6 +109,8 @@ const requiredSourceFiles = [
   'src/plugin/channel-runtime-types.ts',
   'src/plugin/channel-send.ts',
   'src/plugin/channel-utils.ts',
+  'src/plugin/bridge-call.ts',
+  'src/plugin/client-rpc-runtime.ts',
   'src/plugin/config.ts',
   'src/plugin/connection-handlers.ts',
   'src/plugin/connection-state.ts',
@@ -168,6 +170,44 @@ const requiredSourceFiles = [
   'src/runtime/register-trace-runtime.ts',
   'src/runtime/status-snapshots.ts',
   'src/runtime/status-worker.ts',
+  'src/bootstrap/register-runtime-gateway.ts',
+  'src/bootstrap/register-runtime-singleton.ts',
+  'src/core/value-sanitize.ts',
+  'src/messaging/inbound/contracts.ts',
+  'src/messaging/inbound/group-history.ts',
+  'src/messaging/inbound/native-command-runtime.ts',
+  'src/messaging/inbound/reply-dispatch-serial.ts',
+  'src/messaging/inbound/scene-admin.ts',
+  'src/messaging/inbound/session-meta-task.ts',
+  'src/messaging/outbound/marker-parser.ts',
+  'src/messaging/outbound/normalize-outbound-send.ts',
+  'src/messaging/outbound/reply-enqueue-media.ts',
+  'src/openclaw/channel-runtime-contracts.ts',
+  'src/plugin/bridge-ack-facade.ts',
+  'src/plugin/bridge-connection-facade.ts',
+  'src/plugin/bridge-diagnostics-facade.ts',
+  'src/plugin/bridge-drain-facade.ts',
+  'src/plugin/bridge-extended-diagnostics-facade.ts',
+  'src/plugin/bridge-lifecycle.ts',
+  'src/plugin/bridge-media-facade.ts',
+  'src/plugin/bridge-outbox-facade.ts',
+  'src/plugin/bridge-runtime-helpers.ts',
+  'src/plugin/bridge-runtime-snapshots.ts',
+  'src/plugin/bridge-runtime-surface-facade.ts',
+  'src/plugin/bridge-status-facade.ts',
+  'src/plugin/bridge-status-worker-facade.ts',
+  'src/plugin/bridge-support-runtime.ts',
+  'src/plugin/channel-runtime-builders-delivery.ts',
+  'src/plugin/channel-runtime-builders-status.ts',
+  'src/plugin/connection-handlers-helpers.ts',
+  'src/plugin/connection-state-helpers.ts',
+  'src/plugin/error-message.ts',
+  'src/plugin/file-transfer-orchestrator-chunk.ts',
+  'src/plugin/outbox-unified-push-flow.ts',
+  'src/plugin/runtime-diagnostics-assembler.ts',
+  'src/plugin/runtime-diagnostics-helpers.ts',
+  'src/plugin/runtime-diagnostics-payload-builders.ts',
+  'src/plugin/scene-registry.ts',
 ];
 
 const requiredPackFiles = [

package/scripts/selfcheck.mjs

@@ -69,6 +69,7 @@ const requiredSourceFiles = [
   'src/messaging/inbound/native-command-runtime.ts',
   'src/messaging/inbound/native-command.ts',
   'src/messaging/inbound/native-reply-delivery.ts',
+  'src/messaging/inbound/outbound-replay-cache.ts',
   'src/messaging/inbound/parse.ts',
   'src/messaging/inbound/remote-media.ts',
   'src/messaging/inbound/reply-config.ts',
@@ -106,6 +107,7 @@ const requiredSourceFiles = [
   'src/openclaw/session-route-runtime.ts',
   'src/plugin/ack-outbox-runtime-group.ts',
   'src/plugin/bridge-ack-facade.ts',
+  'src/plugin/bridge-call.ts',
   'src/plugin/bridge-connection-facade.ts',
   'src/plugin/bridge-diagnostics-facade.ts',
   'src/plugin/bridge-drain-facade.ts',
@@ -133,6 +135,7 @@ const requiredSourceFiles = [
   'src/plugin/channel-runtime-types.ts',
   'src/plugin/channel-send.ts',
   'src/plugin/channel-utils.ts',
+  'src/plugin/client-rpc-runtime.ts',
   'src/plugin/config.ts',
   'src/plugin/connection-handlers-helpers.ts',
   'src/plugin/connection-handlers.ts',

package/src/bootstrap/register-runtime-gateway.ts

@@ -23,6 +23,7 @@ export type BncrGatewayMethodName =
   | 'bncr.diagnostics'
   | 'bncr.deadLetter.inspect'
   | 'bncr.deadLetter.prune'
+  | 'bncr.rpc.response'
   | 'bncr.file.init'
   | 'bncr.file.chunk'
   | 'bncr.file.complete'

package/src/bootstrap/register-runtime.ts

@@ -97,6 +97,7 @@ export function createBncrRegisterRuntime() {
     'bncr.diagnostics': (bridge, opts) => bridge.handleDiagnostics(opts),
     'bncr.deadLetter.inspect': (bridge, opts) => bridge.handleDeadLetterInspect(opts),
     'bncr.deadLetter.prune': (bridge, opts) => bridge.handleDeadLetterPrune(opts),
+    'bncr.rpc.response': (bridge, opts) => bridge.handleRpcResponse(opts),
     'bncr.file.init': (bridge, opts) => bridge.handleFileInit(opts),
     'bncr.file.chunk': (bridge, opts) => bridge.handleFileChunk(opts),
     'bncr.file.complete': (bridge, opts) => bridge.handleFileComplete(opts),

package/src/channel.ts

@@ -4,7 +4,12 @@ import type {
   OpenClawPluginApi,
   OpenClawPluginServiceContext,
 } from 'openclaw/plugin-sdk/core';
-import { BNCR_DEFAULT_ACCOUNT_ID, CHANNEL_ID, normalizeAccountId } from './core/accounts.ts';
+import {
+  BNCR_DEFAULT_ACCOUNT_ID,
+  CHANNEL_ID,
+  normalizeAccountId,
+  resolveAccount,
+} from './core/accounts.ts';
 import {
   countInvalidOutboxSessionKeys as countInvalidOutboxSessionKeysFromRuntime,
   countLegacyAccountResidue as countLegacyAccountResidueFromRuntime,
@@ -39,6 +44,7 @@ import type {
   OutboxEntry,
 } from './core/types.ts';
 import type { BncrGroupHistoryMap } from './messaging/inbound/group-history.ts';
+import type { BncrOutboundReplayCache } from './messaging/inbound/outbound-replay-cache.ts';
 import type { parseBncrInboundParams } from './messaging/inbound/parse.ts';
 import { buildEnqueueFromReplyDebugInfo } from './messaging/outbound/diagnostics.ts';
 import { buildBncrMediaOutboundFrame } from './messaging/outbound/media.ts';
@@ -160,6 +166,7 @@ import {
   now,
   resolveOutboundFileName,
 } from './plugin/channel-utils.ts';
+import { createBncrClientRpcRuntime } from './plugin/client-rpc-runtime.ts';
 import { BNCR_CONFIG_SURFACE } from './plugin/config.ts';
 import { createBncrConnectionStateRuntimeGroup } from './plugin/connection-state-runtime-group.ts';
 import type { FileAckPayloadState } from './plugin/file-ack-runtime.ts';
@@ -287,6 +294,7 @@ class BncrBridgeRuntime {
     return this.sceneRegistry;
   }
   private groupHistories: BncrGroupHistoryMap = new Map();
+  private outboundReplayCache: BncrOutboundReplayCache = new Map();
   private routeAliases = new Map<
     string,
     { accountId: string; route: BncrRoute; updatedAt: number }
@@ -373,6 +381,14 @@ class BncrBridgeRuntime {
   >();
   private earlyFileAcks = new Map<string, FileAckPayloadState>();
 
+  private readonly clientRpcRuntime = createBncrClientRpcRuntime({
+    resolvePushConnIds: (accountId) => this.resolvePushConnIds(accountId),
+    broadcastToConnIds: (event, payload, connIds) =>
+      this.gatewayContext?.broadcastToConnIds(event, payload, connIds),
+    now,
+    logInfo: (scope, message, options) => this.logInfo(scope, message, options),
+  });
+
   private readonly bridgeSupportRuntime = createBridgeSupportRuntime({
     isStopped: () => this.stopped,
     hasSaveTimer: () => Boolean(this.saveTimer),
@@ -851,6 +867,7 @@ class BncrBridgeRuntime {
   }
 
   private cleanupRuntimeWaitersAndTimers(reason: string) {
+    this.clientRpcRuntime.shutdown();
     cleanupBncrBridgeRuntime(
       {
         bridgeId: this.bridgeId,
@@ -1759,6 +1776,7 @@ class BncrBridgeRuntime {
     setOutboxEntry: (messageId, entry) => this.outbox.set(messageId, entry),
     resolveMessageAck: (messageId, result) => this.resolveMessageAck(messageId, result),
     moveToDeadLetter: (entry, reason) => this.moveToDeadLetter(entry, reason),
+    markRecentOutboundAcked: (entry) => this.markRecentOutboundAcked(entry),
     recordAckTimeoutTelemetry: (accountId) => this.recordAckTimeoutTelemetry(accountId),
     degradeOutboundCapability: (args) => this.degradeOutboundCapability(args),
     flushPushQueueBestEffort: (args) => this.flushPushQueueBestEffort(args),
@@ -1884,6 +1902,7 @@ class BncrBridgeRuntime {
     maxAccountActivityEntries: MAX_ACCOUNT_ACTIVITY_ENTRIES,
     sceneRegistry: this.sceneRegistry,
     groupHistories: this.groupHistories,
+    outboundReplayCache: this.outboundReplayCache,
     outbox: this.outbox,
     getDeadLetter: () => this.deadLetter,
     setDeadLetter: (entries) => {
@@ -2148,6 +2167,16 @@ class BncrBridgeRuntime {
     lastPrePushGuardSkipReasonByAccount: this.lastPrePushGuardSkipReasonByAccount,
     deadLetterSinceStartByAccount: this.deadLetterSinceStartByAccount,
     lastOutboundByAccount: this.lastOutboundByAccount,
+    outboundReplayCache: this.outboundReplayCache,
+    resolveOutboundSender: (entry) => {
+      try {
+        const account = resolveAccount(getOpenClawRuntimeConfig(this.api), entry.accountId);
+        return { sender: account.name, senderId: entry.accountId };
+      } catch {
+        return { sender: 'OpenClaw', senderId: entry.accountId };
+      }
+    },
+    isOutboundAckRequired: (accountId) => this.isOutboundAckRequired(accountId),
     scheduleSave: () => this.scheduleSave(),
     flushPushQueueBestEffort: (args) => this.flushPushQueueBestEffort(args),
     logInfo: (scope, message, options) => this.logInfo(scope, message, options),
@@ -2722,6 +2751,18 @@ class BncrBridgeRuntime {
     return this.bridgeMediaFacade.enqueueFromReply(params);
   }
 
+  listRecentOutbound(sessionKey: string) {
+    return this.bridgeOutboxFacade.listRecentOutbound(sessionKey);
+  }
+
+  listRecentOutboundByAccount(accountId: string) {
+    return this.bridgeOutboxFacade.listRecentOutboundByAccount(accountId);
+  }
+
+  private markRecentOutboundAcked(entry: OutboxEntry) {
+    this.bridgeOutboxFacade.markRecentOutboundAcked(entry);
+  }
+
   private logEnqueueFromReply(args: {
     accountId: string;
     sessionKey: string;
@@ -2853,6 +2894,7 @@ class BncrBridgeRuntime {
       defaultPublicAgentId: () => this.defaultPublicAgentId(),
       sceneRegistry: this.sceneRegistry,
       groupHistories: this.groupHistories,
+      outboundReplayCache: this.outboundReplayCache,
       prepareInboundAcceptance: (args) => this.prepareInboundAcceptance(args),
       logInboundSummary: (args) => this.logInboundSummary(args),
       flushPushQueueBestEffort: (args) => this.flushPushQueueBestEffort(args),
@@ -2922,6 +2964,12 @@ class BncrBridgeRuntime {
   handleDeadLetterPrune = async (ctx: GatewayRequestHandlerOptions) =>
     this.diagnosticsHandlers.handleDeadLetterPrune(ctx);
 
+  handleRpcResponse = async (ctx: GatewayRequestHandlerOptions) =>
+    this.clientRpcRuntime.handleResponse(ctx);
+
+  callClientRpc = async (method: string, args: Record<string, unknown>, accountId: string) =>
+    this.clientRpcRuntime.call(method, args, normalizeAccountId(accountId));
+
   handleFileInit = async (ctx: GatewayRequestHandlerOptions) =>
     this.fileInboundHandlers.handleFileInit(ctx);
 
@@ -3024,6 +3072,7 @@ export function createBncrChannelPlugin(getBridge: () => BncrBridgeRuntime) {
     getStatusBridge: bridgeGroup.getStatusBridge,
     getToolActionBridge: bridgeGroup.getToolActionBridge,
     getGatewayBridge: bridgeGroup.getGatewayBridge,
+    getBridgeCallBridge: bridgeGroup.getBridgeCallBridge,
     channelMeta: BNCR_CHANNEL_META,
     channelCapabilities: BNCR_CHANNEL_CAPABILITIES,
     gatewayMethods: BNCR_GATEWAY_METHODS,

package/src/core/types.ts

@@ -118,6 +118,47 @@ export type OutboxEntry = {
   awaitingRetryPush?: boolean;
 };
 
+export type BncrRecentOutboundEntry = {
+  messageId: string;
+  accountId: string;
+  sessionKey: string;
+  route: BncrRoute;
+  type?: string;
+  kind?: string;
+  text: string;
+  mediaUrl?: string;
+  createdAt: number;
+  lastPushAt?: number;
+  lastError?: string;
+  ackedAt?: number;
+  status: 'queued' | 'pushed' | 'failed' | 'acked';
+};
+
+export type BncrOutboundReplayMediaEntry = {
+  path?: string;
+  contentType?: string;
+  kind?: 'image' | 'video' | 'audio' | 'document' | 'unknown';
+  messageId?: string;
+};
+
+export type BncrOutboundReplayStatus = 'pushed' | 'acked';
+
+export type BncrOutboundReplayEntry = {
+  sender: string;
+  senderId?: string;
+  body: string;
+  timestamp?: number;
+  messageId?: string;
+  media?: BncrOutboundReplayMediaEntry[];
+  accountId?: string;
+  sessionKey?: string;
+  route?: BncrRoute;
+  type?: string;
+  mediaUrl?: string;
+  createdAt?: number;
+  status?: BncrOutboundReplayStatus;
+};
+
 export type BncrDiagnosticsSummary = {
   health: {
     connected: boolean;

package/src/messaging/inbound/dispatch.ts

@@ -27,6 +27,12 @@ import {
   recordBncrPendingGroupMedia,
   recordBncrPendingGroupText,
 } from './group-history.ts';
+import {
+  type BncrOutboundReplayCache,
+  type BncrOutboundReplayEntry,
+  clearBncrOutboundReplay,
+  readBncrOutboundReplaySnapshot,
+} from './outbound-replay-cache.ts';
 import { runBncrInboundReplyDispatch } from './reply-dispatch.ts';
 import { buildBncrInboundTurnContext } from './turn-context.ts';
 
@@ -48,6 +54,7 @@ export async function dispatchBncrInbound(params: {
   resolvedAgentId?: string;
   sceneRegistry: Map<string, BncrSceneRecord>;
   groupHistories: BncrGroupHistoryMap;
+  outboundReplayCache?: BncrOutboundReplayCache;
   defaultAdminAgentId: string;
   defaultPublicAgentId: string;
   now: () => number;
@@ -68,6 +75,7 @@ export async function dispatchBncrInbound(params: {
     resolvedAgentId,
     sceneRegistry = new Map(),
     groupHistories = new Map(),
+    outboundReplayCache = new Map(),
     defaultAdminAgentId,
     defaultPublicAgentId,
     now,
@@ -193,7 +201,7 @@ export async function dispatchBncrInbound(params: {
     }
   }
 
-  if (shouldDispatch && !silentHistoryFlush && parsed.peer.kind === 'group') {
+  if (shouldDispatch && !silentHistoryFlush) {
     pendingHistoryEntries = readBncrPendingGroupHistorySnapshot({
       historyMap: groupHistories,
       parsed,
@@ -208,6 +216,21 @@ export async function dispatchBncrInbound(params: {
     }
   }
 
+  let outboundReplayEntries: BncrOutboundReplayEntry[] = [];
+  if (shouldDispatch && !silentHistoryFlush) {
+    outboundReplayEntries = readBncrOutboundReplaySnapshot({
+      cache: outboundReplayCache,
+      parsed,
+      accountId,
+      excludeMessageId: msgId,
+    });
+    clearBncrOutboundReplay({
+      cache: outboundReplayCache,
+      parsed,
+      accountId,
+    });
+  }
+
   const ctxPayload = await buildBncrInboundTurnContext({
     api,
     cfg,
@@ -227,6 +250,7 @@ export async function dispatchBncrInbound(params: {
     shouldDispatch,
     silentHistoryFlush,
     pendingHistoryEntries,
+    outboundReplayEntries,
   });
 
   await runBncrInboundReplyDispatch({
@@ -250,13 +274,7 @@ export async function dispatchBncrInbound(params: {
     enqueueFromReply,
   });
 
-  if (shouldDispatch && pendingHistoryEntries.length === 0) {
-    clearBncrPendingGroupHistory({
-      historyMap: groupHistories,
-      parsed,
-      historyLimit: resolvedHistoryLimit,
-    });
-  }
+  scheduleSave();
 
   return {
     accountId,

package/src/messaging/inbound/outbound-replay-cache.ts

@@ -0,0 +1,236 @@
+import type {
+  BncrOutboundReplayEntry,
+  BncrOutboundReplayMediaEntry,
+  BncrOutboundReplayStatus,
+  OutboxEntry,
+} from '../../core/types.ts';
+import type { ParsedInbound } from './dispatch-prep.ts';
+
+export type {
+  BncrOutboundReplayEntry,
+  BncrOutboundReplayMediaEntry,
+  BncrOutboundReplayStatus,
+} from '../../core/types.ts';
+
+export type BncrOutboundReplayCache = Map<string, BncrOutboundReplayEntry[]>;
+
+function normalizeTextBody(value: string): string {
+  return String(value || '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function cloneMediaEntry(entry: BncrOutboundReplayMediaEntry): BncrOutboundReplayMediaEntry {
+  return {
+    ...(entry?.path ? { path: entry.path } : {}),
+    ...(entry?.contentType ? { contentType: entry.contentType } : {}),
+    ...(entry?.kind ? { kind: entry.kind } : {}),
+    ...(entry?.messageId ? { messageId: entry.messageId } : {}),
+  };
+}
+
+export function cloneBncrOutboundReplayEntry(
+  entry: BncrOutboundReplayEntry,
+): BncrOutboundReplayEntry {
+  return {
+    sender: entry.sender,
+    ...(entry.senderId ? { senderId: entry.senderId } : {}),
+    body: entry.body,
+    ...(typeof entry.timestamp === 'number' ? { timestamp: entry.timestamp } : {}),
+    ...(entry.messageId ? { messageId: entry.messageId } : {}),
+    ...(Array.isArray(entry.media)
+      ? { media: entry.media.map((item) => cloneMediaEntry(item)) }
+      : {}),
+    ...(entry.accountId ? { accountId: entry.accountId } : {}),
+    ...(entry.sessionKey ? { sessionKey: entry.sessionKey } : {}),
+    ...(entry.route ? { route: { ...entry.route } } : {}),
+    ...(entry.type ? { type: entry.type } : {}),
+    ...(entry.mediaUrl ? { mediaUrl: entry.mediaUrl } : {}),
+    ...(typeof entry.createdAt === 'number' ? { createdAt: entry.createdAt } : {}),
+    ...(entry.status ? { status: entry.status } : {}),
+  };
+}
+
+export function buildBncrOutboundReplayKeyFromRoute(args: {
+  accountId?: string;
+  platform?: string;
+  groupId?: string;
+  userId?: string;
+}): string | null {
+  const accountId = String(args.accountId || '').trim() || 'default';
+  const platform = String(args.platform || '').trim();
+  const groupId = String(args.groupId || '0').trim() || '0';
+  const userId = String(args.userId || '0').trim() || '0';
+  if (!platform) return null;
+  if (groupId !== '0') return `${accountId}:${platform}:${groupId}`;
+  if (userId !== '0') return `${accountId}:${platform}:${userId}`;
+  return null;
+}
+
+export function buildBncrOutboundReplayKey(
+  parsed: ParsedInbound,
+  accountId: string,
+): string | null {
+  return buildBncrOutboundReplayKeyFromRoute({
+    accountId,
+    platform: parsed.platform,
+    groupId: parsed.groupId,
+    userId: parsed.userId,
+  });
+}
+
+function recordOutboundReplayEntry(args: {
+  cache: BncrOutboundReplayCache;
+  cacheKey: string;
+  entry: BncrOutboundReplayEntry;
+}) {
+  const msgId = String(args.entry.messageId || '').trim();
+  const existing = args.cache.get(args.cacheKey) || [];
+  if (msgId && existing.some((entry) => entry.messageId === msgId)) return;
+
+  const next = [...existing, cloneBncrOutboundReplayEntry(args.entry)].sort(
+    (a, b) => (a.timestamp ?? 0) - (b.timestamp ?? 0),
+  );
+
+  if (args.cache.has(args.cacheKey)) {
+    args.cache.delete(args.cacheKey);
+  }
+  args.cache.set(args.cacheKey, next);
+}
+
+function inferMediaKind(args: {
+  msgType?: string;
+  contentType?: string;
+  mediaUrl?: string;
+  type?: string;
+}): NonNullable<BncrOutboundReplayMediaEntry['kind']> {
+  const msgType = String(args.msgType || '')
+    .trim()
+    .toLowerCase();
+  const type = String(args.type || '')
+    .trim()
+    .toLowerCase();
+  const contentType = String(args.contentType || '')
+    .trim()
+    .toLowerCase();
+  const mediaUrl = String(args.mediaUrl || '')
+    .trim()
+    .toLowerCase();
+
+  if (msgType === 'image' || type === 'image' || contentType.startsWith('image/')) return 'image';
+  if (msgType === 'video' || type === 'video' || contentType.startsWith('video/')) return 'video';
+  if (
+    msgType === 'audio' ||
+    msgType === 'voice' ||
+    type === 'audio' ||
+    type === 'voice' ||
+    contentType.startsWith('audio/')
+  ) {
+    return 'audio';
+  }
+  if (type === 'file' || type === 'document' || msgType === 'file' || msgType === 'document') {
+    return 'document';
+  }
+  if (/\.(png|jpe?g|gif|webp|bmp|svg)$/.test(mediaUrl)) return 'image';
+  if (/\.(mp4|mov|webm|mkv|avi)$/.test(mediaUrl)) return 'video';
+  if (/\.(mp3|ogg|oga|silk|amr|wav|m4a|aac|flac)$/.test(mediaUrl)) return 'audio';
+  if (contentType) return 'document';
+  return 'unknown';
+}
+
+function buildMediaBody(kind: NonNullable<BncrOutboundReplayMediaEntry['kind']>): string {
+  return `<media:${kind}>`;
+}
+
+function isAppMsg(type: string | undefined, msg: string): boolean {
+  return (
+    String(type || '')
+      .trim()
+      .toLowerCase() === 'appmsg' || /^<appmsg/i.test(msg)
+  );
+}
+
+export function recordBncrOutboundReplay(args: {
+  cache: BncrOutboundReplayCache;
+  entry: OutboxEntry;
+  sender: string;
+  senderId?: string;
+  status?: BncrOutboundReplayStatus;
+}) {
+  const cacheKey = buildBncrOutboundReplayKeyFromRoute({
+    accountId: args.entry.accountId,
+    platform: args.entry.route?.platform,
+    groupId: args.entry.route?.groupId,
+    userId: args.entry.route?.userId,
+  });
+  if (!cacheKey) return;
+
+  const message =
+    args.entry.payload?.message && typeof args.entry.payload.message === 'object'
+      ? (args.entry.payload.message as Record<string, unknown>)
+      : {};
+  const type = typeof message.type === 'string' ? message.type : undefined;
+  const rawBody = typeof message.msg === 'string' ? message.msg : '';
+  const mediaUrl = typeof message.mediaUrl === 'string' ? message.mediaUrl.trim() : '';
+  const kind = inferMediaKind({ type, mediaUrl });
+  const isMedia =
+    message.transferMode === 'media' || Boolean(mediaUrl) || (!!type && type !== 'text');
+  const body = isAppMsg(type, rawBody)
+    ? buildMediaBody('document')
+    : normalizeTextBody(rawBody) || (isMedia ? buildMediaBody(kind) : '');
+  if (!body) return;
+
+  recordOutboundReplayEntry({
+    cache: args.cache,
+    cacheKey,
+    entry: {
+      sender: args.sender,
+      ...(args.senderId ? { senderId: args.senderId } : {}),
+      body,
+      timestamp: Date.now(),
+      messageId: args.entry.messageId,
+      accountId: args.entry.accountId,
+      sessionKey: args.entry.sessionKey,
+      route: { ...args.entry.route },
+      ...(type ? { type } : {}),
+      ...(mediaUrl ? { mediaUrl } : {}),
+      createdAt: args.entry.createdAt,
+      ...(args.status ? { status: args.status } : {}),
+      ...(mediaUrl
+        ? {
+            media: [
+              {
+                path: mediaUrl,
+                kind,
+                messageId: args.entry.messageId,
+              },
+            ],
+          }
+        : {}),
+    },
+  });
+}
+
+export function readBncrOutboundReplaySnapshot(args: {
+  cache: BncrOutboundReplayCache;
+  parsed: ParsedInbound;
+  accountId: string;
+  excludeMessageId?: string | null;
+}): BncrOutboundReplayEntry[] {
+  const cacheKey = buildBncrOutboundReplayKey(args.parsed, args.accountId);
+  if (!cacheKey) return [];
+  const excludedMessageId = String(args.excludeMessageId || '').trim();
+  return (args.cache.get(cacheKey) || [])
+    .filter((entry) => !excludedMessageId || entry.messageId !== excludedMessageId)
+    .map(cloneBncrOutboundReplayEntry);
+}
+
+export function clearBncrOutboundReplay(args: {
+  cache: BncrOutboundReplayCache;
+  parsed: ParsedInbound;
+  accountId: string;
+}) {
+  const cacheKey = buildBncrOutboundReplayKey(args.parsed, args.accountId);
+  if (!cacheKey) return;
+  args.cache.delete(cacheKey);
+}