@xmoxmo/bncr 0.6.1 → 0.6.3

package/src/messaging/inbound/history-shard-worker.ts

@@ -0,0 +1,180 @@
+import { emitBncrLogLine } from '../../core/logging.ts';
+import type { BncrHistoryShardQueue, BncrHistoryShardRow } from '../../plugin/sqlite-state.ts';
+import type { BncrInboundContextPayload } from './contracts.ts';
+import type { BncrConversationHistoryMap } from './conversation-history.ts';
+import { removeBncrConversationHistoryMessageIds } from './conversation-history.ts';
+import {
+  getConversationHistorySerialOwner,
+  runConversationHistorySerial,
+} from './conversation-history-serial.ts';
+import type {
+  BncrInboundConversationResolution,
+  BncrInboundReplyRouteFact,
+  ParsedInbound,
+} from './dispatch-prep.ts';
+import type { BncrOutboundReplayCache } from './outbound-replay-cache.ts';
+import { removeBncrOutboundReplayMessageIds } from './outbound-replay-cache.ts';
+
+export type BncrHistoryShardDispatchPayload = {
+  parsed: ParsedInbound;
+  msgId?: string | null;
+  peer: ParsedInbound['peer'];
+  rawBody: string;
+  storePath: string;
+  ctxPayload: BncrInboundContextPayload;
+  resolution: BncrInboundConversationResolution;
+  replyRouteFact: BncrInboundReplyRouteFact;
+  senderIdForContext: string;
+  senderDisplayName: string;
+  shouldDispatch: boolean;
+  silentHistoryFlush?: boolean;
+  deliveryId?: string;
+};
+
+export type BncrHistoryShardPayloadEnvelope = {
+  version: 2;
+  historyKey: string;
+  accountId?: string;
+  messageIds: string[];
+  bufferKeys: string[];
+  dispatch: BncrHistoryShardDispatchPayload;
+};
+
+export const HISTORY_SHARD_LEASE_RENEW_INTERVAL_MS = 60_000;
+
+export async function runBncrHistoryShardWithLeaseRenewal<T>(args: {
+  shardId: number | null;
+  historyShardQueue?: BncrHistoryShardQueue;
+  task: () => Promise<T>;
+  intervalMs?: number;
+  owner?: string;
+}): Promise<T> {
+  if (args.shardId === null || !args.historyShardQueue?.renewHistoryShardLease) {
+    return args.task();
+  }
+  const renew = () => {
+    try {
+      args.historyShardQueue?.renewHistoryShardLease?.(args.shardId!, args.owner);
+    } catch {
+      // Lease renewal is best-effort; the claim itself protects against a stale lease.
+    }
+  };
+  const timer = setInterval(renew, args.intervalMs ?? HISTORY_SHARD_LEASE_RENEW_INTERVAL_MS);
+  timer.unref?.();
+  try {
+    return await args.task();
+  } finally {
+    clearInterval(timer);
+  }
+}
+
+export function parseBncrHistoryShardPayload(value: string): BncrHistoryShardPayloadEnvelope {
+  const parsed = JSON.parse(value) as Partial<BncrHistoryShardPayloadEnvelope>;
+  if (parsed?.version !== 2) {
+    throw new Error(`unsupported history shard payload version=${String(parsed?.version)}`);
+  }
+  if (!parsed.dispatch || !parsed.historyKey) {
+    throw new Error('invalid history shard payload: missing dispatch payload');
+  }
+  return parsed as BncrHistoryShardPayloadEnvelope;
+}
+
+export async function processBncrHistoryShardSlot(args: {
+  shard: BncrHistoryShardRow;
+  historyShardQueue: BncrHistoryShardQueue;
+  conversationHistories?: BncrConversationHistoryMap;
+  outboundReplayCache?: BncrOutboundReplayCache;
+  runDispatch: (payload: BncrHistoryShardDispatchPayload) => Promise<void>;
+  leaseRenewIntervalMs?: number;
+}) {
+  const shardOwner = args.shard.owner ?? getConversationHistorySerialOwner();
+  let payload: BncrHistoryShardPayloadEnvelope;
+  try {
+    payload = parseBncrHistoryShardPayload(args.shard.payloadJson);
+  } catch (error) {
+    try {
+      args.historyShardQueue.markHistoryShardFailed(args.shard.id, error, shardOwner);
+    } catch (markError) {
+      emitBncrLogLine(
+        'warn',
+        `[bncr] history shard failed mark failed|key=${args.shard.historyKey}|shard=${args.shard.id}|reason=${String(markError)}`,
+      );
+    }
+    throw error;
+  }
+  await runBncrHistoryShardWithLeaseRenewal({
+    shardId: args.shard.id,
+    historyShardQueue: args.historyShardQueue,
+    intervalMs: args.leaseRenewIntervalMs,
+    owner: shardOwner,
+    task: () =>
+      runConversationHistorySerial(
+        args.shard.historyKey,
+        async (handle) => {
+          handle.phase('snapshot');
+          if (
+            args.historyShardQueue.markHistoryShardProcessing(args.shard.id, shardOwner) === false
+          ) {
+            throw new Error(
+              `history shard activation lost|key=${args.shard.historyKey}|shard=${args.shard.id}`,
+            );
+          }
+          try {
+            await args.runDispatch({
+              ...payload.dispatch,
+              deliveryId: `bncr-history-shard:${args.shard.id}`,
+            });
+          } catch (error) {
+            try {
+              args.historyShardQueue.markHistoryShardFailed(args.shard.id, error, shardOwner);
+            } catch (markError) {
+              emitBncrLogLine(
+                'warn',
+                `[bncr] history shard failed mark failed|key=${args.shard.historyKey}|shard=${args.shard.id}|reason=${String(markError)}`,
+              );
+            }
+            throw error;
+          }
+          handle.phase('upload_end');
+          try {
+            args.historyShardQueue.markHistoryShardCompleted(args.shard.id, shardOwner);
+          } catch (error) {
+            // Completion marking is observability only; cleanup still deletes the
+            // shard-owned rows after the upload has settled.
+            emitBncrLogLine(
+              'warn',
+              `[bncr] history shard complete mark failed|key=${args.shard.historyKey}|shard=${args.shard.id}|reason=${String(error)}`,
+            );
+          }
+          handle.phase('cache_delete_start');
+          if (args.conversationHistories) {
+            removeBncrConversationHistoryMessageIds({
+              historyMap: args.conversationHistories,
+              historyKey: args.shard.historyKey,
+              messageIds: payload.messageIds,
+            });
+          }
+          if (args.outboundReplayCache && payload.bufferKeys.length > 0) {
+            removeBncrOutboundReplayMessageIds({
+              cache: args.outboundReplayCache,
+              parsed: payload.dispatch.parsed,
+              accountId: payload.dispatch.resolution.accountId,
+              messageIds: payload.messageIds,
+            });
+          }
+          handle.phase('cache_delete_done');
+          try {
+            args.historyShardQueue.completeHistoryShard(args.shard.id, shardOwner);
+          } catch (error) {
+            // A failed cleanup is recovered from the DB on restart. Do not retry
+            // the same shard here because the upload itself already succeeded.
+            emitBncrLogLine(
+              'warn',
+              `[bncr] history shard complete failed|key=${args.shard.historyKey}|shard=${args.shard.id}|reason=${String(error)}`,
+            );
+          }
+        },
+        { owner: shardOwner },
+      ),
+  });
+}

package/src/messaging/inbound/native-command.ts

@@ -11,12 +11,24 @@ export type ParseBncrNativeCommandOptions = {
   allowBareSessionReset?: boolean;
 };
 
+export function isBncrStopCommandText(rawBody: string): boolean {
+  const raw = String(rawBody || '')
+    .trim()
+    .toLowerCase();
+  return raw === '/stop';
+}
+
 export type NativeVerboseCommand = {
   handled: true;
   verboseLevel?: 'on' | 'off' | 'full';
   text: string;
 };
 
+export type NativeHelpCommandOptions = {
+  isAdmin?: boolean;
+  peerKind?: 'direct' | 'group';
+};
+
 export type NativeHelpCommand = {
   handled: true;
   text: string;
@@ -38,32 +50,6 @@ export type NativeSessionResetCommand = {
   text: string;
 };
 
-const BNCR_HELP_TEXT = [
-  '🦞 Bncr command usage',
-  '',
-  '📌 Bncr builtins',
-  '  • /bncr whoami',
-  '  • /bncr verbose on|off|full',
-  '',
-  '🛡 Scene approval',
-  '  • /bncr allow [<SceneId>]',
-  '  • /bncr deny [<SceneId>]',
-  '  • /bncr bind <agentId> [<SceneId>]',
-  '  • /bncr mode help',
-  '  • /bncr mode <admin|mention|hybrid|all|clear> [<SceneId>]',
-  '  • /bncr revoke [<SceneId>]',
-  '  • /bncr list pending [filters...]',
-  '  • /bncr list scenes [filters...]',
-  '',
-  '📋 Group history',
-  '  • /bncr history-help',
-  '  • /bncr history-limit [<number>|clear] [<SceneId>]',
-  '  • /bncr history-force on|off|clear [<SceneId>]',
-  '',
-  '🌐 Remote media',
-  '  • /bncr download-media on|off|clear|default on|off [<SceneId>]',
-].join('\n');
-
 const BNCR_NATIVE_COMMANDS = new Set([
   'help',
   'new',
@@ -120,7 +106,7 @@ export function parseBncrNativeCommand(
     return { command: 'whoami', raw, body: '/whoami', argsText: '' };
   }
   if (!raw.startsWith('/bncr')) return null;
-  const match = raw.match(/^\/bncr(?:@[A-Za-z0-9_]+)?(?:\s+([^\s]+)(?:\s+([\s\S]*))?)?$/i);
+  const match = raw.match(/^\/bncr(?:\s+([^\s]+)(?:\s+([\s\S]*))?)?$/i);
   if (!match) return null;
 
   const command = String(match[1] || 'help')
@@ -142,7 +128,7 @@ export function parseBncrUnsupportedDirectCommand(text: string): {
   const raw = String(text || '').trim();
   if (!raw.startsWith('/')) return null;
 
-  const bareMatch = raw.match(/^\/([A-Za-z0-9_]+)(?:@[A-Za-z0-9_]+)?(?:\s+.*)?$/);
+  const bareMatch = raw.match(/^\/([A-Za-z0-9_]+)(?:\s+.*)?$/);
   if (!bareMatch) return null;
   const bareCommand = String(bareMatch[1] || '')
     .trim()
@@ -150,7 +136,7 @@ export function parseBncrUnsupportedDirectCommand(text: string): {
   if (!bareCommand) return null;
 
   if (bareCommand === 'bncr') {
-    const subMatch = raw.match(/^\/bncr(?:@[A-Za-z0-9_]+)?(?:\s+([A-Za-z0-9_-]+))?/i);
+    const subMatch = raw.match(/^\/bncr(?:\s+([A-Za-z0-9_-]+))?/i);
     const subCommand =
       String(subMatch?.[1] || '')
         .trim()
@@ -163,9 +149,77 @@ export function parseBncrUnsupportedDirectCommand(text: string): {
   return { command: bareCommand, raw };
 }
 
-export function resolveBncrNativeHelpCommand(command: NativeCommand): NativeHelpCommand | null {
+const BNCR_HELP_SECTIONS = [
+  {
+    title: '📌 Bncr builtins',
+    audience: 'all',
+    commands: [
+      { label: '/bncr whoami', scopes: ['admin', 'direct', 'group'] },
+      { label: '/bncr status', scopes: ['admin', 'direct', 'group'] },
+      { label: '/bncr new', scopes: ['admin', 'direct'] },
+      { label: '/bncr reset', scopes: ['admin', 'direct'] },
+      { label: '/bncr verbose on|off|full', scopes: ['admin'] },
+    ],
+  },
+  {
+    title: '🛡 Scene approval',
+    audience: 'admin',
+    commands: [
+      { label: '/bncr allow [<SceneId>]', scopes: ['admin'] },
+      { label: '/bncr deny [<SceneId>]', scopes: ['admin'] },
+      { label: '/bncr bind <agentId> [<SceneId>]', scopes: ['admin'] },
+      { label: '/bncr mode help', scopes: ['admin'] },
+      {
+        label: '/bncr mode <admin|mention|hybrid|all|clear> [<SceneId>]',
+        scopes: ['admin'],
+      },
+      { label: '/bncr revoke [<SceneId>]', scopes: ['admin'] },
+      { label: '/bncr list pending [filters...]', scopes: ['admin'] },
+      { label: '/bncr list scenes [filters...]', scopes: ['admin'] },
+    ],
+  },
+  {
+    title: '📋 Conversation history',
+    audience: 'admin',
+    commands: [
+      { label: '/bncr history-help', scopes: ['admin'] },
+      { label: '/bncr history-limit [<number>|clear] [<SceneId>]', scopes: ['admin'] },
+      { label: '/bncr history-force on|off|clear [<SceneId>]', scopes: ['admin'] },
+    ],
+  },
+  {
+    title: '🌐 Remote media',
+    audience: 'admin',
+    commands: [
+      {
+        label: '/bncr download-media on|off|clear|default on|off [<SceneId>]',
+        scopes: ['admin'],
+      },
+    ],
+  },
+];
+
+export function resolveBncrNativeHelpCommand(
+  command: NativeCommand,
+  options?: NativeHelpCommandOptions,
+): NativeHelpCommand | null {
   if (command.command !== 'help') return null;
-  return { handled: true, text: BNCR_HELP_TEXT };
+
+  const isAdmin = options?.isAdmin === true;
+  const isGroup = options?.peerKind === 'group';
+  const audience = isAdmin ? 'admin' : isGroup ? 'group' : 'direct';
+  const sections: string[] = ['🦞 Bncr command usage', ''];
+
+  for (const section of BNCR_HELP_SECTIONS) {
+    if (section.audience !== 'all' && section.audience !== audience) continue;
+    const visible = section.commands.filter((item) => item.scopes.includes(audience));
+    if (visible.length === 0) continue;
+    sections.push(section.title);
+    for (const item of visible) sections.push(`  • ${item.label}`);
+    sections.push('');
+  }
+
+  return { handled: true, text: sections.join('\n') };
 }
 
 export function resolveBncrNativeWhoamiCommand(args: {
@@ -214,16 +268,18 @@ export function resolveBncrNativeStatusCommand(args: {
 
 export function resolveBncrNativeSessionResetCommand(args: {
   command: NativeCommand;
+  peerKind: 'direct' | 'group';
 }): NativeSessionResetCommand | null {
   if (args.command.command !== 'new' && args.command.command !== 'reset') return null;
   const reason = args.command.command === 'new' ? 'new' : 'reset';
+  const scope = args.peerKind === 'group' ? 'this group chat' : 'this private chat';
   return {
     handled: true,
     reason,
     text:
       reason === 'new'
-        ? 'Started a new session for this private chat.'
-        : 'Reset the current session for this private chat.',
+        ? `Started a new session for ${scope}.`
+        : `Reset the current session for ${scope}.`,
   };
 }
 

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

@@ -4,6 +4,15 @@ import type {
   BncrOutboundReplayStatus,
   OutboxEntry,
 } from '../../core/types.ts';
+import {
+  type BncrConversationHistoryMap,
+  buildBncrBotReplyMessageId,
+  buildBncrConversationHistoryKey,
+  buildBncrConversationHistoryKeyFromRoute,
+  readConversationHistoryVersion,
+  recordBncrBotReply,
+  resolveBncrHistoryLimit,
+} from './conversation-history.ts';
 import type { ParsedInbound } from './dispatch-prep.ts';
 
 export type {
@@ -83,19 +92,21 @@ function recordOutboundReplayEntry(args: {
   cache: BncrOutboundReplayCache;
   cacheKey: string;
   entry: BncrOutboundReplayEntry;
-}) {
+  historyLimit?: number;
+}): boolean {
   const msgId = String(args.entry.messageId || '').trim();
   const existing = args.cache.get(args.cacheKey) || [];
-  if (msgId && existing.some((entry) => entry.messageId === msgId)) return;
+  if (msgId && existing.some((entry) => entry.messageId === msgId)) return false;
 
-  const next = [...existing, cloneBncrOutboundReplayEntry(args.entry)].sort(
-    (a, b) => (a.timestamp ?? 0) - (b.timestamp ?? 0),
-  );
+  const next = [...existing, cloneBncrOutboundReplayEntry(args.entry)]
+    .sort((a, b) => (a.timestamp ?? 0) - (b.timestamp ?? 0))
+    .slice(-resolveBncrHistoryLimit(args.historyLimit));
 
   if (args.cache.has(args.cacheKey)) {
     args.cache.delete(args.cacheKey);
   }
   args.cache.set(args.cacheKey, next);
+  return true;
 }
 
 function inferMediaKind(args: {
@@ -150,20 +161,28 @@ function isAppMsg(type: string | undefined, msg: string): boolean {
   );
 }
 
+export type BncrOutboundReplayRecordResult = {
+  recorded: boolean;
+  historyOverflow: boolean;
+  historyVersion?: number;
+};
+
 export function recordBncrOutboundReplay(args: {
   cache: BncrOutboundReplayCache;
+  conversationHistories?: BncrConversationHistoryMap;
+  historyLimit?: number;
   entry: OutboxEntry;
   sender: string;
   senderId?: string;
   status?: BncrOutboundReplayStatus;
-}) {
+}): BncrOutboundReplayRecordResult {
   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;
+  if (!cacheKey) return { recorded: false, historyOverflow: false };
 
   const message =
     args.entry.payload?.message && typeof args.entry.payload.message === 'object'
@@ -178,17 +197,114 @@ export function recordBncrOutboundReplay(args: {
   const body = isAppMsg(type, rawBody)
     ? buildMediaBody('document')
     : normalizeTextBody(rawBody) || (isMedia ? buildMediaBody(kind) : '');
-  if (!body) return;
+  if (!body) return { recorded: false, historyOverflow: false };
+  const recordTimestamp = args.entry.lastPushAt ?? Date.now();
+  const historyKey = buildBncrConversationHistoryKeyFromRoute({
+    platform: args.entry.route?.platform,
+    groupId: args.entry.route?.groupId,
+    userId: args.entry.route?.userId,
+  });
+  const messageId = historyKey
+    ? buildBncrBotReplyMessageId({
+        historyKey,
+        sender: args.sender,
+        senderId: args.senderId,
+        body,
+        timestamp: recordTimestamp,
+        messageId: args.entry.messageId,
+        media: mediaUrl
+          ? [
+              {
+                path: mediaUrl,
+                kind,
+                messageId: args.entry.messageId,
+              },
+            ]
+          : undefined,
+      })
+    : undefined;
+  let historyOverflow = false;
+  let historyVersion: number | undefined;
 
-  recordOutboundReplayEntry({
+  if (args.conversationHistories) {
+    if (historyKey) {
+      recordBncrBotReply({
+        historyMap: args.conversationHistories,
+        historyKey,
+        sender: args.sender,
+        senderId: args.senderId,
+        body,
+        timestamp: recordTimestamp,
+        messageId,
+        historyLimit: args.historyLimit,
+        ...(mediaUrl
+          ? {
+              media: [
+                {
+                  path: mediaUrl,
+                  kind,
+                  messageId,
+                },
+              ],
+            }
+          : {}),
+      });
+      const entries = args.conversationHistories.get(historyKey) || [];
+      const limit = resolveBncrHistoryLimit(args.historyLimit);
+      // Overflow is decided by the current active window after the outbound
+      // event, not by whether this call newly wrote a row. A restored or
+      // repeated ack must still be able to force a flush.
+      historyOverflow = entries.length >= limit;
+      if (historyOverflow) {
+        historyVersion = readConversationHistoryVersion(args.conversationHistories, historyKey);
+      }
+      const cacheRecorded = recordOutboundReplayEntry({
+        cache: args.cache,
+        cacheKey,
+        historyLimit: args.historyLimit,
+        entry: {
+          sender: args.sender,
+          ...(args.senderId ? { senderId: args.senderId } : {}),
+          body,
+          timestamp: recordTimestamp,
+          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,
+                  },
+                ],
+              }
+            : {}),
+        },
+      });
+      return {
+        recorded: cacheRecorded,
+        historyOverflow,
+        ...(historyOverflow && historyVersion !== undefined ? { historyVersion } : {}),
+      };
+    }
+  }
+  const cacheRecorded = recordOutboundReplayEntry({
     cache: args.cache,
     cacheKey,
+    historyLimit: args.historyLimit,
     entry: {
       sender: args.sender,
       ...(args.senderId ? { senderId: args.senderId } : {}),
       body,
-      timestamp: Date.now(),
-      messageId: args.entry.messageId,
+      timestamp: recordTimestamp,
+      messageId: messageId || args.entry.messageId,
       accountId: args.entry.accountId,
       sessionKey: args.entry.sessionKey,
       route: { ...args.entry.route },
@@ -202,27 +318,67 @@ export function recordBncrOutboundReplay(args: {
               {
                 path: mediaUrl,
                 kind,
-                messageId: args.entry.messageId,
+                messageId: messageId || args.entry.messageId,
               },
             ],
           }
         : {}),
     },
   });
+  return {
+    recorded: cacheRecorded,
+    historyOverflow: false,
+  };
 }
 
 export function readBncrOutboundReplaySnapshot(args: {
   cache: BncrOutboundReplayCache;
+  conversationHistories?: BncrConversationHistoryMap;
   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);
+  const cacheKey = buildBncrOutboundReplayKey(args.parsed, args.accountId);
+  const legacyEntries = cacheKey
+    ? (args.cache.get(cacheKey) || [])
+        .filter((entry) => !excludedMessageId || entry.messageId !== excludedMessageId)
+        .map(cloneBncrOutboundReplayEntry)
+    : [];
+  if (!args.conversationHistories) return legacyEntries;
+
+  const historyKey = buildBncrConversationHistoryKey(args.parsed);
+  const historyEntries = historyKey
+    ? (args.conversationHistories.get(historyKey) || [])
+        .filter((entry) => entry.role === 'assistant')
+        .filter((entry) => !excludedMessageId || entry.messageId !== excludedMessageId)
+        .map((entry) => ({
+          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) => ({
+                  path: item.path,
+                  contentType: item.contentType,
+                  kind: item.kind,
+                  messageId: item.messageId,
+                })),
+              }
+            : {}),
+        }))
+    : [];
+  const knownMessageIds = new Set(
+    historyEntries
+      .map((entry) => entry.messageId)
+      .filter((messageId): messageId is string => Boolean(messageId)),
+  );
+  return [
+    ...historyEntries,
+    ...legacyEntries.filter((entry) => !entry.messageId || !knownMessageIds.has(entry.messageId)),
+  ].sort((a, b) => (a.timestamp ?? 0) - (b.timestamp ?? 0));
 }
 
 export function clearBncrOutboundReplay(args: {
@@ -234,3 +390,32 @@ export function clearBncrOutboundReplay(args: {
   if (!cacheKey) return;
   args.cache.delete(cacheKey);
 }
+
+export function removeBncrOutboundReplayMessageIds(args: {
+  cache: BncrOutboundReplayCache;
+  parsed: ParsedInbound;
+  accountId: string;
+  messageIds: ReadonlyArray<string | undefined | null>;
+}): number {
+  const cacheKey = buildBncrOutboundReplayKey(args.parsed, args.accountId);
+  if (!cacheKey) return 0;
+  const messageIds = new Set(
+    args.messageIds
+      .map((messageId) => String(messageId || '').trim())
+      .filter((messageId) => Boolean(messageId)),
+  );
+  if (messageIds.size === 0) return 0;
+  const current = args.cache.get(cacheKey) || [];
+  if (current.length === 0) return 0;
+  const next = current.filter(
+    (entry) =>
+      !String(entry.messageId || '').trim() || !messageIds.has(String(entry.messageId).trim()),
+  );
+  if (next.length === current.length) return 0;
+  if (next.length === 0) {
+    args.cache.delete(cacheKey);
+  } else {
+    args.cache.set(cacheKey, next);
+  }
+  return current.length - next.length;
+}