@invago/mixin 1.0.17 → 1.0.19

package/README.md

@@ -10,11 +10,12 @@ Connect [Mixin Messenger](https://mixin.one/messenger) to [OpenClaw](https://ope
 
 MixinClaw is an OpenClaw channel plugin. It runs in the same process as the OpenClaw Gateway, receives inbound messages from Mixin Blaze WebSocket, and delivers outbound messages over the Mixin HTTP API.
 
-Important:
-
-- Install the plugin on the same machine where the OpenClaw Gateway runs.
-- OpenClaw config files use JSON5, so comments and trailing commas are allowed.
-- The proxy configured by this plugin only affects this plugin.
+Important:
+
+- Install the plugin on the same machine where the OpenClaw Gateway runs.
+- OpenClaw config files use JSON5, so comments and trailing commas are allowed.
+- The proxy configured by this plugin only affects this plugin.
+- Per confirmed Mixin platform behavior, user messages in group chats are delivered to the bot only when the bot is explicitly mentioned.
 
 ## Recommended Install
 
@@ -325,11 +326,11 @@ Mixin now supports formal group access controls in addition to direct-message `d
 
 Important delivery boundary:
 
-- In practice, Mixin group bots reliably receive messages when the bot is explicitly mentioned.
-- The most reliable format is `@<identity_number> your message`, for example `@7000103034 hello`.
+- Per confirmed Mixin platform behavior, group messages from users are delivered to the bot only when the bot is explicitly mentioned.
+- Use `@<identity_number> your message`, for example `@7000103034 hello`.
 - `requireMentionInGroup: false` only disables this plugin's own post-delivery filtering.
-- It does not guarantee that Mixin will deliver every non-mention group message to the bot.
-- If a non-mention group message produces no read receipt and no inbound log, the message most likely was not delivered to the plugin by Mixin in the first place.
+- It does not cause Mixin to forward non-mention user messages in groups to the bot.
+- If a non-mention user message produces no read receipt and no inbound log, the message was not delivered to the plugin by Mixin in the first place.
 - Group quote/reply interactions are currently not treated as a reliable bot trigger, because Mixin may not deliver those events to the bot over Blaze consistently.
 
 Example:

package/README.zh-CN.md

@@ -10,11 +10,12 @@
 
 MixinClaw 是一个 OpenClaw 频道插件。它运行在 OpenClaw Gateway 同一进程中，使用 Mixin Blaze WebSocket 接收入站消息，并通过 Mixin HTTP API 发送出站消息。
 
-重要说明：
-
-- 插件需要安装在 OpenClaw Gateway 所在的机器上。
-- OpenClaw 配置文件使用 JSON5，支持注释和尾逗号。
-- 这里配置的代理只作用于这个插件，不影响其他插件。
+重要说明：
+
+- 插件需要安装在 OpenClaw Gateway 所在的机器上。
+- OpenClaw 配置文件使用 JSON5，支持注释和尾逗号。
+- 这里配置的代理只作用于这个插件，不影响其他插件。
+- 根据 Mixin 官方确认，群内用户消息只有在显式 `@` 机器人的情况下才会投递给 bot。
 
 ## 推荐安装方式
 
@@ -317,12 +318,12 @@ OpenClaw 支持通过 `bindings[].match.accountId` 把不同的频道账号直
 
 关于群消息投递边界：
 
-- 目前从实际联调看，Mixin 群里稳定可用的触发方式仍然是显式 `@bot`。
-- 最稳的写法是 `@<identity_number> + 文本`，例如 `@7000103034 你好`。
+- 根据 Mixin 官方确认，群内用户消息只有在显式 `@bot` 时才会投递给机器人。
+- 推荐写法是 `@<identity_number> + 文本`，例如 `@7000103034 你好`。
 - `requireMentionInGroup: false` 只表示关闭插件自身的群消息二次过滤。
-- 它不能保证 Mixin 平台一定把所有未 `@` 的群消息投递给机器人。
-- 如果群里未 `@` 的消息既没有已读，也没有任何入站日志，通常说明这条消息根本没有被 Mixin 投递到插件。
-- 目前群内“引用回复”不应被当成稳定触发方式，因为 Mixin 不一定会把这类事件稳定投递给 bot。
+- 它不会让 Mixin 把未 `@` 的群内用户消息投递给 bot。
+- 如果一条未 `@` 的群内用户消息既没有已读，也没有任何入站日志，那不是插件过滤了它，而是 Mixin 根本没有把这条消息送到插件。
+- 目前群内“引用回复”也不应被当成稳定触发方式，因为 Mixin 不一定会把这类事件稳定投递给 bot。
 
 示例：
 

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "mixin",
   "name": "Mixin Messenger Channel",
   "description": "Mixin Messenger channel via Blaze WebSocket",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "channels": [
     "mixin"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invago/mixin",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "description": "Mixin Messenger channel plugin for OpenClaw",
   "type": "module",
   "main": "index.ts",

package/src/channel.ts

@@ -10,7 +10,7 @@ import { buildClient, sleep } from "./shared.js";
 import { MixinConfigSchema } from "./config-schema.js";
 import { describeAccount, isConfigured, listAccountIds, resolveAccount, resolveDefaultAccountId, resolveMediaMaxMb } from "./config.js";
 import type { MixinAccountConfig } from "./config-schema.js";
-import { handleMixinMessage, type MixinInboundMessage } from "./inbound-handler.js";
+import { handleMixinMessage, handleMixinSystemConversation, type MixinInboundMessage } from "./inbound-handler.js";
 import { getMixpayStatusSnapshot, startMixpayWorker } from "./mixpay-worker.js";
 import { mixinOnboardingAdapter } from "./onboarding.js";
 import { buildMixinOutboundPlanFromReplyPayload, executeMixinOutboundPlan } from "./outbound-plan.js";
@@ -459,8 +459,50 @@ export const mixinPlugin = {
               onSenderReady: (sender) => {
                 setMixinBlazeSender(accountId, sender);
               },
-              handler: {
-                onMessage: async (rawMsg: any) => {
+              handler: {
+                onConversation: async (rawMsg: any) => {
+                  if (stopped) {
+                    return;
+                  }
+                  if (!rawMsg || !rawMsg.message_id) {
+                    return;
+                  }
+
+                  const isDirect = await resolveIsDirectMessage({
+                    config,
+                    conversationId: rawMsg.conversation_id,
+                    userId: rawMsg.user_id,
+                    log,
+                  });
+                  const quoteMessageId = extractQuoteMessageId(rawMsg);
+                  const rawCategory = typeof rawMsg.category === "string" ? rawMsg.category : "SYSTEM_CONVERSATION";
+                  const rawData = typeof rawMsg.data_base64 === "string"
+                    ? rawMsg.data_base64
+                    : typeof rawMsg.data === "string"
+                      ? rawMsg.data
+                      : "";
+
+                  log.info(
+                    `[mixin] blaze inbound: messageId=${rawMsg.message_id}, conversationId=${rawMsg.conversation_id ?? ""}, userId=${rawMsg.user_id ?? ""}, category=${rawCategory}, isDirect=${isDirect}, quoteMessageId=${quoteMessageId ?? "none"}, dataLength=${rawData.length}`,
+                  );
+
+                  const msg: MixinInboundMessage = {
+                    conversationId: rawMsg.conversation_id ?? "",
+                    userId: rawMsg.user_id ?? "",
+                    messageId: rawMsg.message_id,
+                    category: rawCategory,
+                    data: rawData,
+                    createdAt: rawMsg.created_at ?? new Date().toISOString(),
+                    quoteMessageId,
+                  };
+
+                  try {
+                    await handleMixinSystemConversation({ cfg, accountId, msg, log });
+                  } catch (err) {
+                    log.error(`error handling system conversation ${msg.messageId}`, err);
+                  }
+                },
+                onMessage: async (rawMsg: any) => {
                   if (stopped) {
                     return;
                   }
@@ -471,24 +513,34 @@ export const mixinPlugin = {
                     return;
                   }
 
-                  const isDirect = await resolveIsDirectMessage({
-                    config,
-                    conversationId: rawMsg.conversation_id,
-                    userId: rawMsg.user_id,
-                    log,
-                  });
-                  log.info(
-                    `[mixin] inbound route context: messageId=${rawMsg.message_id}, conversationId=${rawMsg.conversation_id ?? ""}, userId=${rawMsg.user_id}, isDirect=${isDirect}`,
-                  );
-
+                  const isDirect = await resolveIsDirectMessage({
+                    config,
+                    conversationId: rawMsg.conversation_id,
+                    userId: rawMsg.user_id,
+                    log,
+                  });
+                  const quoteMessageId = extractQuoteMessageId(rawMsg);
+                  const rawCategory = typeof rawMsg.category === "string" ? rawMsg.category : "PLAIN_TEXT";
+                  const rawData = typeof rawMsg.data_base64 === "string"
+                    ? rawMsg.data_base64
+                    : typeof rawMsg.data === "string"
+                      ? rawMsg.data
+                      : "";
+                  log.info(
+                    `[mixin] blaze inbound: messageId=${rawMsg.message_id}, conversationId=${rawMsg.conversation_id ?? ""}, userId=${rawMsg.user_id}, category=${rawCategory}, isDirect=${isDirect}, quoteMessageId=${quoteMessageId ?? "none"}, dataLength=${rawData.length}`,
+                  );
+                  log.info(
+                    `[mixin] inbound route context: messageId=${rawMsg.message_id}, conversationId=${rawMsg.conversation_id ?? ""}, userId=${rawMsg.user_id}, isDirect=${isDirect}`,
+                  );
+
                   const msg: MixinInboundMessage = {
                     conversationId: rawMsg.conversation_id ?? "",
                     userId: rawMsg.user_id,
                     messageId: rawMsg.message_id,
-                    category: rawMsg.category ?? "PLAIN_TEXT",
-                    data: rawMsg.data_base64 ?? rawMsg.data ?? "",
+                    category: rawCategory,
+                    data: rawData,
                     createdAt: rawMsg.created_at ?? new Date().toISOString(),
-                    quoteMessageId: extractQuoteMessageId(rawMsg),
+                    quoteMessageId,
                   };
 
                   try {

package/src/inbound-handler.ts

@@ -8,11 +8,12 @@ import { getAccountConfig, resolveConversationPolicy } from "./config.js";
 import type { MixinAccountConfig } from "./config-schema.js";
 import { decryptMixinMessage } from "./crypto.js";
 import { getMixpayOrderStatusText, getRecentMixpayOrdersText, refreshMixpayOrderStatus } from "./mixpay-worker.js";
-import { buildMixinOutboundPlanFromReplyText, executeMixinOutboundPlan } from "./outbound-plan.js";
-import { getMixinRuntime } from "./runtime.js";
-import {
-  getOutboxStatus,
-  purgePermanentInvalidOutboxEntries,
+import { buildMixinOutboundPlanFromReplyText, executeMixinOutboundPlan } from "./outbound-plan.js";
+import { getMixinRuntime } from "./runtime.js";
+import { claimMixinInboundMessage, commitMixinInboundMessage, releaseMixinInboundMessage } from "./message-dedup.js";
+import {
+  getOutboxStatus,
+  purgePermanentInvalidOutboxEntries,
   sendTextMessage,
 } from "./send-service.js";
 import { buildClient } from "./shared.js";
@@ -28,13 +29,10 @@ export interface MixinInboundMessage {
   quoteMessageId?: string;
   publicKey?: string;
 }
-
-const processedMessages = new Set<string>();
-const processingMessages = new Set<string>();
-const MAX_DEDUP_SIZE = 2000;
-const unauthNotifiedUsers = new Map<string, number>();
-const unauthNotifiedGroups = new Map<string, number>();
-const loggedAllowFromAccounts = new Set<string>();
+
+const unauthNotifiedUsers = new Map<string, number>();
+const unauthNotifiedGroups = new Map<string, number>();
+const loggedAllowFromAccounts = new Set<string>();
 const UNAUTH_NOTIFY_INTERVAL = 20 * 60 * 1000;
 const MAX_UNAUTH_NOTIFY_USERS = 1000;
 const MAX_UNAUTH_NOTIFY_GROUPS = 1000;
@@ -47,10 +45,13 @@ const BOT_PROFILE_CACHE_TTL_MS = 10 * 60 * 1000;
 const SESSION_LABEL_MAX_LENGTH = 64;
 const requireFromHere = createRequire(import.meta.url);
 
-type CachedUserProfile = {
-  fullName: string;
-  expiresAt: number;
-};
+type CachedUserProfile = {
+  fullName: string;
+  identityNumber: string;
+  relationship: string;
+  senderKind: MixinSenderKind;
+  expiresAt: number;
+};
 
 type CachedGroupProfile = {
   name: string;
@@ -69,6 +70,15 @@ type CachedBotIdentity = {
   expiresAt: number;
 };
 
+type MixinSenderKind = "user" | "bot" | "system" | "self" | "unknown";
+
+type ResolvedMixinSenderProfile = {
+  fullName: string;
+  identityNumber: string;
+  relationship: string;
+  senderKind: MixinSenderKind;
+};
+
 type GroupAccessDecision = {
   allowed: boolean;
   groupPolicy: "open" | "allowlist" | "disabled";
@@ -162,30 +172,7 @@ function evaluateMixinSenderGroupAccess(params: {
   };
 }
 
-function markProcessing(messageId: string): boolean {
-  if (processedMessages.has(messageId) || processingMessages.has(messageId)) {
-    return false;
-  }
-  processingMessages.add(messageId);
-  return true;
-}
-
-function markProcessed(messageId: string): void {
-  processingMessages.delete(messageId);
-  if (processedMessages.size >= MAX_DEDUP_SIZE) {
-    const first = processedMessages.values().next().value;
-    if (first) {
-      processedMessages.delete(first);
-    }
-  }
-  processedMessages.add(messageId);
-}
-
-function clearProcessing(messageId: string): void {
-  processingMessages.delete(messageId);
-}
-
-function pruneUnauthNotifiedUsers(now: number): void {
+function pruneUnauthNotifiedUsers(now: number): void {
   for (const [userId, lastNotified] of unauthNotifiedUsers) {
     if (now - lastNotified > UNAUTH_NOTIFY_INTERVAL) {
       unauthNotifiedUsers.delete(userId);
@@ -240,9 +227,47 @@ function buildGroupProfileCacheKey(accountId: string, conversationId: string): s
   return `${accountId}:${conversationId.trim().toLowerCase()}`;
 }
 
-function buildBotProfileCacheKey(accountId: string): string {
-  return accountId.trim().toLowerCase();
-}
+function buildBotProfileCacheKey(accountId: string): string {
+  return accountId.trim().toLowerCase();
+}
+
+function isSystemConversationCategory(category: string): boolean {
+  return category === "SYSTEM_CONVERSATION";
+}
+
+function isRecallMessageCategory(category: string): boolean {
+  return category.trim().toUpperCase() === "MESSAGE_RECALL";
+}
+
+function isSystemSenderId(userId: string): boolean {
+  return userId.trim() === "00000000-0000-0000-0000-000000000000";
+}
+
+function isMixinBotIdentityNumber(identityNumber: string): boolean {
+  return /^700\d{7}$/.test(identityNumber.trim());
+}
+
+function classifyMixinSenderKind(params: {
+  userId: string;
+  identityNumber?: string;
+  category?: string;
+  selfUserId?: string;
+}): MixinSenderKind {
+  if (params.selfUserId && params.userId.trim() === params.selfUserId.trim()) {
+    return "self";
+  }
+  if (isSystemSenderId(params.userId) || isSystemConversationCategory(params.category ?? "")) {
+    return "system";
+  }
+  const normalizedIdentityNumber = normalizePresentationName(params.identityNumber ?? "");
+  if (normalizedIdentityNumber && isMixinBotIdentityNumber(normalizedIdentityNumber)) {
+    return "bot";
+  }
+  if (normalizedIdentityNumber) {
+    return "user";
+  }
+  return "unknown";
+}
 
 function pruneUserProfileCache(now: number): void {
   for (const [key, cached] of cachedUserProfiles) {
@@ -371,42 +396,87 @@ async function loadUpdateSessionStore(log: {
   }
 }
 
-async function resolveSenderName(params: {
-  accountId: string;
-  config: MixinAccountConfig;
-  userId: string;
-  log: { info: (m: string) => void; warn: (m: string) => void; error: (m: string, e?: unknown) => void };
-}): Promise<string> {
-  const userId = params.userId.trim();
-  if (!userId) {
-    return "";
-  }
-
-  const now = Date.now();
-  const cacheKey = buildUserProfileCacheKey(params.accountId, userId);
-  const cached = cachedUserProfiles.get(cacheKey);
-  if (cached && cached.expiresAt > now) {
-    return cached.fullName;
-  }
+async function resolveSenderProfile(params: {
+  accountId: string;
+  config: MixinAccountConfig;
+  userId: string;
+  category?: string;
+  log: { info: (m: string) => void; warn: (m: string) => void; error: (m: string, e?: unknown) => void };
+}): Promise<ResolvedMixinSenderProfile> {
+  const userId = params.userId.trim();
+  if (!userId) {
+    return {
+      fullName: "",
+      identityNumber: "",
+      relationship: "",
+      senderKind: "unknown",
+    };
+  }
+
+  if (isSystemSenderId(userId) || isSystemConversationCategory(params.category ?? "")) {
+    return {
+      fullName: "system",
+      identityNumber: "",
+      relationship: "",
+      senderKind: "system",
+    };
+  }
+
+  const now = Date.now();
+  const cacheKey = buildUserProfileCacheKey(params.accountId, userId);
+  const cached = cachedUserProfiles.get(cacheKey);
+  if (cached && cached.expiresAt > now) {
+    return {
+      fullName: cached.fullName,
+      identityNumber: cached.identityNumber,
+      relationship: cached.relationship,
+      senderKind: cached.senderKind,
+    };
+  }
 
   pruneUserProfileCache(now);
 
-  try {
-    const client = buildClient(params.config);
-    const user = await client.user.fetch(userId);
-    const fullName = typeof user.full_name === "string" && user.full_name.trim() ? user.full_name.trim() : userId;
-    cachedUserProfiles.set(cacheKey, {
-      fullName,
-      expiresAt: now + USER_PROFILE_CACHE_TTL_MS,
-    });
-    return fullName;
-  } catch (err) {
-    params.log.warn(
-      `[mixin] failed to resolve sender profile: accountId=${params.accountId}, userId=${userId}, error=${err instanceof Error ? err.message : String(err)}`,
-    );
-    return userId;
-  }
-}
+  try {
+    const client = buildClient(params.config);
+    const user = await client.user.fetch(userId);
+    const fullName = typeof user.full_name === "string" && user.full_name.trim() ? user.full_name.trim() : userId;
+    const identityNumber = typeof user.identity_number === "string" ? user.identity_number.trim() : "";
+    const relationship = typeof user.relationship === "string" ? user.relationship.trim() : "";
+    const senderKind = classifyMixinSenderKind({
+      userId,
+      identityNumber,
+      category: params.category,
+      selfUserId: params.config.appId,
+    });
+    cachedUserProfiles.set(cacheKey, {
+      fullName,
+      identityNumber,
+      relationship,
+      senderKind,
+      expiresAt: now + USER_PROFILE_CACHE_TTL_MS,
+    });
+    return {
+      fullName,
+      identityNumber,
+      relationship,
+      senderKind,
+    };
+  } catch (err) {
+    params.log.warn(
+      `[mixin] failed to resolve sender profile: accountId=${params.accountId}, userId=${userId}, error=${err instanceof Error ? err.message : String(err)}`,
+    );
+    return {
+      fullName: userId,
+      identityNumber: "",
+      relationship: "",
+      senderKind: classifyMixinSenderKind({
+        userId,
+        category: params.category,
+        selfUserId: params.config.appId,
+      }),
+    };
+  }
+}
 
 async function resolveGroupName(params: {
   accountId: string;
@@ -631,6 +701,129 @@ function buildQuotedMessageContextNote(params: {
   ];
 }
 
+function buildSenderContextNote(params: {
+  senderKind: MixinSenderKind;
+  senderIdentityNumber?: string;
+  senderRelationship?: string;
+}): string[] {
+  const lines = [`Sender kind: ${params.senderKind}`];
+  if (params.senderIdentityNumber) {
+    lines.push(`Sender identity number: ${params.senderIdentityNumber}`);
+  }
+  if (params.senderRelationship) {
+    lines.push(`Sender relationship: ${params.senderRelationship}`);
+  }
+  return lines;
+}
+
+function combineUntrustedContext(...parts: Array<string[] | undefined>): string[] | undefined {
+  const combined = parts.flatMap((part) => part ?? []);
+  return combined.length > 0 ? combined : undefined;
+}
+
+function decodeSystemConversationText(data: string): string {
+  try {
+    return Buffer.from(data, "base64").toString("utf-8").replace(/^\uFEFF/, "").trim();
+  } catch {
+    return data.trim();
+  }
+}
+
+function tryParseSystemConversationPayload(text: string): unknown {
+  if (!text) {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start >= 0 && end > start) {
+      try {
+        return JSON.parse(text.slice(start, end + 1));
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+}
+
+function collectSystemConversationStrings(value: unknown, depth = 0, output: string[] = []): string[] {
+  if (depth > 6 || value == null) {
+    return output;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed) {
+      output.push(trimmed);
+    }
+    return output;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectSystemConversationStrings(item, depth + 1, output);
+    }
+    return output;
+  }
+  if (typeof value === "object") {
+    for (const nested of Object.values(value as Record<string, unknown>)) {
+      collectSystemConversationStrings(nested, depth + 1, output);
+    }
+  }
+  return output;
+}
+
+function extractSystemConversationUserIds(value: unknown, depth = 0, output: string[] = []): string[] {
+  if (depth > 6 || value == null) {
+    return output;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      extractSystemConversationUserIds(item, depth + 1, output);
+    }
+    return output;
+  }
+  if (typeof value !== "object") {
+    return output;
+  }
+
+  const record = value as Record<string, unknown>;
+  for (const [key, nested] of Object.entries(record)) {
+    if (typeof nested === "string") {
+      const normalizedKey = key.toLowerCase();
+      const trimmed = nested.trim();
+      if (
+        trimmed &&
+        /^[0-9a-f-]{36}$/i.test(trimmed) &&
+        (normalizedKey.includes("user") || normalizedKey.includes("participant") || normalizedKey.includes("member"))
+      ) {
+        output.push(trimmed.toLowerCase());
+      }
+    }
+    extractSystemConversationUserIds(nested, depth + 1, output);
+  }
+  return output;
+}
+
+function isJoinLikeSystemConversation(text: string, payload: unknown): boolean {
+  const haystack = [text, ...collectSystemConversationStrings(payload)]
+    .join(" ")
+    .toLowerCase();
+  return /( join|joined|invite|invited|add|added|加入|进群|入群 )/.test(` ${haystack} `);
+}
+
+function formatMixinWelcomeMessage(names: string[]): string {
+  const uniqueNames = Array.from(new Set(names.map((name) => normalizePresentationName(name)).filter(Boolean)));
+  if (uniqueNames.length === 0) {
+    return "欢迎新朋友加入群聊。";
+  }
+  if (uniqueNames.length === 1) {
+    return `欢迎 ${uniqueNames[0]} 加入群聊。`;
+  }
+  return `欢迎 ${uniqueNames.join("、")} 加入群聊。`;
+}
+
 async function resolveInboundAttachment(params: {
   rt: ReturnType<typeof getMixinRuntime>;
   config: MixinAccountConfig;
@@ -991,18 +1184,42 @@ function evaluateMixinGroupAccess(params: {
 }
 
 export async function handleMixinMessage(params: {
-  cfg: OpenClawConfig;
-  accountId: string;
+  cfg: OpenClawConfig;
+  accountId: string;
   msg: MixinInboundMessage;
   isDirect: boolean;
   log: { info: (m: string) => void; warn: (m: string) => void; error: (m: string, e?: unknown) => void };
-}): Promise<void> {
+}): Promise<void> {
   const { cfg, accountId, msg, isDirect, log } = params;
   const rt = getMixinRuntime();
 
-  if (!markProcessing(msg.messageId)) {
+  const claim = await claimMixinInboundMessage({
+    accountId,
+    conversationId: msg.conversationId,
+    messageId: msg.messageId,
+    createdAt: msg.createdAt,
+    log,
+  });
+  if (!claim.ok) {
+    if (claim.reason === "duplicate") {
+      log.info(`[mixin] duplicate inbound suppressed: accountId=${accountId}, messageId=${msg.messageId}`);
+    } else if (claim.reason === "stale") {
+      log.info(`[mixin] stale inbound dropped: accountId=${accountId}, messageId=${msg.messageId}, createdAt=${msg.createdAt}`);
+    } else {
+      log.warn(`[mixin] invalid inbound dedupe key: accountId=${accountId}, messageId=${msg.messageId}`);
+    }
     return;
   }
+  const dedupeKey = claim.dedupeKey;
+  let committed = false;
+
+  const commit = async (): Promise<void> => {
+    if (committed) {
+      return;
+    }
+    committed = true;
+    await commitMixinInboundMessage(dedupeKey, log);
+  };
 
   try {
     const config = getAccountConfig(cfg, accountId);
@@ -1017,7 +1234,7 @@ export async function handleMixinMessage(params: {
         );
         if (!decrypted) {
           log.error(`[mixin] decryption failed for ${msg.messageId}`);
-          markProcessed(msg.messageId);
+          await commit();
           return;
         }
         log.info(`[mixin] decryption successful: messageId=${msg.messageId}, length=${decrypted.length}`);
@@ -1025,11 +1242,17 @@ export async function handleMixinMessage(params: {
         msg.category = "PLAIN_TEXT";
       } catch (err) {
         log.error(`[mixin] decryption exception for ${msg.messageId}`, err);
-        markProcessed(msg.messageId);
+        await commit();
         return;
       }
     }
 
+    if (isRecallMessageCategory(msg.category)) {
+      log.info(`[mixin] skip recall message: messageId=${msg.messageId}, category=${msg.category}`);
+      await commit();
+      return;
+    }
+
     let isTextMessage = msg.category.startsWith("PLAIN_TEXT") || msg.category.startsWith("PLAIN_POST");
     const isAttachmentMessage = msg.category === "PLAIN_DATA" || msg.category === "PLAIN_AUDIO";
 
@@ -1049,6 +1272,7 @@ export async function handleMixinMessage(params: {
       log.info(
         `[mixin] skip non-text message: messageId=${msg.messageId}, category=${msg.category}, quoteMessageId=${msg.quoteMessageId ?? "none"}`,
       );
+      await commit();
       return;
     }
 
@@ -1093,6 +1317,7 @@ export async function handleMixinMessage(params: {
   }
 
   if (!text) {
+    await commit();
     return;
   }
 
@@ -1105,9 +1330,17 @@ export async function handleMixinMessage(params: {
     botIdentity.userId,
   ].filter((value): value is string => Boolean(value && value.trim()));
   const groupMentioned = !isDirect && botAliases.some((alias) => hasBotMention(text, alias));
+  const shouldPassGroupTrigger = isDirect || !conversationPolicy || shouldPassGroupFilter(
+    {
+      ...config,
+      requireMentionInGroup: conversationPolicy?.requireMention ?? config.requireMentionInGroup,
+    },
+    text,
+    botAliases,
+  );
   if (!isDirect) {
     log.info(
-      `[mixin] group trigger check: messageId=${msg.messageId}, botName=${botIdentity.name}, botUserId=${botIdentity.userId}, botIdentityNumber=${botIdentity.identityNumber || "none"}, replyContext=${replyContext?.id ?? "none"}, mentioned=${groupMentioned}`,
+      `[mixin] group trigger check: messageId=${msg.messageId}, botName=${botIdentity.name}, botUserId=${botIdentity.userId}, botIdentityNumber=${botIdentity.identityNumber || "none"}, replyContext=${replyContext?.id ?? "none"}, mentioned=${groupMentioned}, requireMention=${conversationPolicy?.requireMention ?? config.requireMentionInGroup}, willPass=${shouldPassGroupTrigger}`,
     );
   }
 
@@ -1115,16 +1348,10 @@ export async function handleMixinMessage(params: {
     !isDirect &&
     conversationPolicy &&
     !(isAttachmentMessage && conversationPolicy.mediaBypassMention) &&
-    !shouldPassGroupFilter(
-      {
-        ...config,
-        requireMentionInGroup: conversationPolicy.requireMention,
-      },
-      text,
-      botAliases,
-    )
+    !shouldPassGroupTrigger
   ) {
     log.info(`[mixin] group message filtered: ${msg.messageId}`);
+    await commit();
     return;
   }
 
@@ -1153,11 +1380,11 @@ export async function handleMixinMessage(params: {
     if (!isDirect && isMixinGroupAuthCommand(text)) {
       const now = Date.now();
       const lastNotified = unauthNotifiedGroups.get(msg.conversationId) ?? 0;
-      const shouldNotify = lastNotified === 0 || now - lastNotified > UNAUTH_NOTIFY_INTERVAL;
-      if (!shouldNotify) {
-        markProcessed(msg.messageId);
-        return;
-      }
+      const shouldNotify = lastNotified === 0 || now - lastNotified > UNAUTH_NOTIFY_INTERVAL;
+      if (!shouldNotify) {
+        await commit();
+        return;
+      }
       pruneUnauthNotifiedGroups(now);
       unauthNotifiedGroups.set(msg.conversationId, now);
       const { code, created } = await rt.channel.pairing.upsertPairingRequest({
@@ -1171,9 +1398,9 @@ export async function handleMixinMessage(params: {
           userId: msg.userId,
         }),
       });
-      markProcessed(msg.messageId);
-      await sendTextMessage(
-        cfg,
+      await commit();
+      await sendTextMessage(
+        cfg,
         accountId,
         msg.conversationId,
         undefined,
@@ -1187,21 +1414,21 @@ export async function handleMixinMessage(params: {
       );
       return;
     }
-    if (isDirect) {
-      log.warn(`[mixin] user ${msg.userId} not authorized (dmPolicy=${dmPolicy})`);
+    if (isDirect) {
+      log.warn(`[mixin] user ${msg.userId} not authorized (dmPolicy=${dmPolicy})`);
     } else {
       log.warn(
         `[mixin] group sender ${msg.userId} blocked: conversationId=${msg.conversationId}, groupPolicy=${groupAccess?.groupPolicy ?? "unknown"}, reason=${groupAccess?.reason ?? "unknown"}`,
       );
     }
-    markProcessed(msg.messageId);
-    if (isDirect) {
-      await handleUnauthorizedDirectMessage({ rt, cfg, accountId, config, msg, log });
-    }
-    return;
-  }
-
-  markProcessed(msg.messageId);
+    await commit();
+    if (isDirect) {
+      await handleUnauthorizedDirectMessage({ rt, cfg, accountId, config, msg, log });
+    }
+    return;
+  }
+
+  await commit();
 
   if (isOutboxCommand(text)) {
     if (isOutboxPurgeInvalidCommand(text)) {
@@ -1315,10 +1542,10 @@ export async function handleMixinMessage(params: {
 
   log.info(`[mixin] route result: ${route ? "FOUND" : "NULL"} - agentId=${route?.agentId ?? "N/A"}`);
 
-  if (!route) {
-    log.warn(`[mixin] no agent route for ${msg.userId} (peerId: ${peerId})`);
-    return;
-  }
+  if (!route) {
+    log.warn(`[mixin] no agent route for ${msg.userId} (peerId: ${peerId})`);
+    return;
+  }
 
   const shouldComputeCommandAuthorized = rt.channel.commands.shouldComputeCommandAuthorized(text, cfg);
   const useAccessGroups = cfg.commands?.useAccessGroups !== false;
@@ -1340,12 +1567,14 @@ export async function handleMixinMessage(params: {
       })
     : undefined;
 
-  const senderName = await resolveSenderName({
+  const senderProfile = await resolveSenderProfile({
     accountId,
     config,
     userId: msg.userId,
+    category: msg.category,
     log,
   });
+  const senderName = senderProfile.fullName;
   const groupName = isDirect
     ? ""
     : await resolveGroupName({
@@ -1377,10 +1606,19 @@ export async function handleMixinMessage(params: {
     ReplyToBody: replyContext?.body,
     ReplyToSender: replyContext?.sender,
     ReplyToIsQuote: replyContext ? true : undefined,
-    UntrustedContext: replyContext?.id ? buildQuotedMessageContextNote({
-      quoteMessageId: replyContext.id,
-      found: replyContext.found,
-    }) : undefined,
+    SenderKind: senderProfile.senderKind,
+    SenderIdentityNumber: senderProfile.identityNumber || undefined,
+    UntrustedContext: combineUntrustedContext(
+      buildSenderContextNote({
+        senderKind: senderProfile.senderKind,
+        senderIdentityNumber: senderProfile.identityNumber,
+        senderRelationship: senderProfile.relationship,
+      }),
+      replyContext?.id ? buildQuotedMessageContextNote({
+        quoteMessageId: replyContext.id,
+        found: replyContext.found,
+      }) : undefined,
+    ),
     CommandAuthorized: commandAuthorized,
     OriginatingChannel: "mixin",
     OriginatingTo: isDirect ? msg.userId : msg.conversationId,
@@ -1431,8 +1669,76 @@ export async function handleMixinMessage(params: {
       },
     });
   } finally {
-    if (!processedMessages.has(msg.messageId)) {
-      clearProcessing(msg.messageId);
+    await releaseMixinInboundMessage(dedupeKey);
+  }
+}
+
+export async function handleMixinSystemConversation(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  msg: MixinInboundMessage;
+  log: { info: (m: string) => void; warn: (m: string) => void; error: (m: string, e?: unknown) => void };
+}): Promise<void> {
+  const { cfg, accountId, msg, log } = params;
+  const claim = await claimMixinInboundMessage({
+    accountId,
+    conversationId: msg.conversationId,
+    messageId: msg.messageId,
+    createdAt: msg.createdAt,
+    log,
+  });
+  if (!claim.ok) {
+    if (claim.reason === "duplicate") {
+      log.info(`[mixin] duplicate system conversation suppressed: accountId=${accountId}, messageId=${msg.messageId}`);
+    } else if (claim.reason === "stale") {
+      log.info(
+        `[mixin] stale system conversation dropped: accountId=${accountId}, messageId=${msg.messageId}, createdAt=${msg.createdAt}`,
+      );
+    } else {
+      log.warn(`[mixin] invalid system conversation dedupe key: accountId=${accountId}, messageId=${msg.messageId}`);
     }
+    return;
+  }
+  const dedupeKey = claim.dedupeKey;
+  let committed = false;
+
+  const commit = async (): Promise<void> => {
+    if (committed) {
+      return;
+    }
+    committed = true;
+    await commitMixinInboundMessage(dedupeKey, log);
+  };
+
+  try {
+    const config = getAccountConfig(cfg, accountId);
+    const text = decodeSystemConversationText(msg.data);
+    const payload = tryParseSystemConversationPayload(text);
+    const joinedUserIds = Array.from(new Set(extractSystemConversationUserIds(payload)))
+      .filter((userId) => userId && !isSystemSenderId(userId) && userId !== config.appId?.trim().toLowerCase());
+    const joinLike = isJoinLikeSystemConversation(text, payload);
+
+    log.info(
+      `[mixin] system conversation: messageId=${msg.messageId}, joinLike=${joinLike}, joinedUserIds=${joinedUserIds.join(",") || "none"}`,
+    );
+
+    await commit();
+
+    if (!joinLike) {
+      return;
+    }
+
+    const joinedProfiles = await Promise.all(
+      joinedUserIds.map((userId) => resolveSenderProfile({
+        accountId,
+        config,
+        userId,
+        log,
+      })),
+    );
+    const welcomeText = formatMixinWelcomeMessage(joinedProfiles.map((profile) => profile.fullName));
+    await sendTextMessage(cfg, accountId, msg.conversationId, undefined, welcomeText, log);
+  } finally {
+    await releaseMixinInboundMessage(dedupeKey);
   }
 }

package/src/message-dedup.ts

@@ -0,0 +1,462 @@
+import crypto from "node:crypto";
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { getMixinRuntime } from "./runtime.js";
+
+const DEDUP_STORE_VERSION = 1;
+const DEFAULT_TTL_MS = 12 * 60 * 60 * 1000;
+const DEFAULT_MAX_ENTRIES = 5000;
+const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+const DEFAULT_STALE_MESSAGE_MS = 30 * 60 * 1000;
+const PERSIST_DEBOUNCE_MS = 1000;
+const CLAIM_STALE_MS = 10 * 60 * 1000;
+
+type MixinInboundDedupStoreEntry = {
+  key: string;
+  seenAt: number;
+};
+
+type MixinInboundDedupStore = {
+  version: number;
+  entries: MixinInboundDedupStoreEntry[];
+};
+
+type MixinInboundDedupState = {
+  loaded: boolean;
+  seen: Map<string, number>;
+  pending: Set<string>;
+  persistChain: Promise<void>;
+  persistTimer: NodeJS.Timeout | null;
+  sweepTimer: NodeJS.Timeout | null;
+  dirty: boolean;
+  lastSweepAt: number;
+  lastLoadedAt: number;
+};
+
+type ClaimMixinInboundMessageParams = {
+  accountId: string;
+  conversationId?: string;
+  messageId: string;
+  createdAt?: string;
+  log?: {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+  };
+};
+
+type ClaimMixinInboundMessageResult =
+  | { ok: true; dedupeKey: string }
+  | { ok: false; dedupeKey: string; reason: "duplicate" | "stale" | "invalid" };
+
+type GlobalWithMixinInboundDedupState = typeof globalThis & {
+  __mixinInboundDedupState__?: MixinInboundDedupState;
+};
+
+function createDefaultState(): MixinInboundDedupState {
+  return {
+    loaded: false,
+    seen: new Map<string, number>(),
+    pending: new Set<string>(),
+    persistChain: Promise.resolve(),
+    persistTimer: null,
+    sweepTimer: null,
+    dirty: false,
+    lastSweepAt: 0,
+    lastLoadedAt: 0,
+  };
+}
+
+function getState(): MixinInboundDedupState {
+  const globalState = globalThis as GlobalWithMixinInboundDedupState;
+  if (!globalState.__mixinInboundDedupState__) {
+    globalState.__mixinInboundDedupState__ = createDefaultState();
+  }
+  return globalState.__mixinInboundDedupState__;
+}
+
+function resolveFallbackDedupDir(env: NodeJS.ProcessEnv = process.env): string {
+  const stateOverride = env.OPENCLAW_STATE_DIR?.trim() || env.CLAWDBOT_STATE_DIR?.trim();
+  if (stateOverride) {
+    return path.join(stateOverride, "mixin");
+  }
+  const openClawHome = env.OPENCLAW_HOME?.trim();
+  if (openClawHome) {
+    return path.join(openClawHome, ".openclaw", "mixin");
+  }
+  return path.join(os.homedir(), ".openclaw", "mixin");
+}
+
+function resolveDedupDir(): string {
+  try {
+    return path.join(getMixinRuntime().state.resolveStateDir(process.env, os.homedir), "mixin");
+  } catch {
+    return resolveFallbackDedupDir();
+  }
+}
+
+function resolveDedupPaths(): {
+  dedupDir: string;
+  dedupFile: string;
+  dedupTmpFile: string;
+  claimsDir: string;
+} {
+  const dedupDir = resolveDedupDir();
+  const dedupFile = path.join(dedupDir, "mixin-inbound-dedup.json");
+  return {
+    dedupDir,
+    dedupFile,
+    dedupTmpFile: `${dedupFile}.tmp`,
+    claimsDir: path.join(dedupDir, "claims"),
+  };
+}
+
+function hashDedupeKey(dedupeKey: string): string {
+  return crypto.createHash("sha1").update(dedupeKey).digest("hex");
+}
+
+function resolveClaimFilePath(dedupeKey: string): string {
+  const { claimsDir } = resolveDedupPaths();
+  return path.join(claimsDir, `${hashDedupeKey(dedupeKey)}.lock`);
+}
+
+function normalizeTimestamp(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return null;
+  }
+  const timestamp = Math.max(0, Math.floor(value));
+  return timestamp > 0 ? timestamp : null;
+}
+
+function buildDedupeScopeKey(params: {
+  accountId: string;
+  conversationId?: string;
+  messageId: string;
+}): string {
+  const accountId = params.accountId.trim().toLowerCase();
+  const conversationId = (params.conversationId ?? "").trim().toLowerCase();
+  const messageId = params.messageId.trim().toLowerCase();
+  return `${accountId}:${conversationId}:${messageId}`;
+}
+
+function parseCreatedAt(createdAt?: string): number | null {
+  if (!createdAt) {
+    return null;
+  }
+  const timestamp = Date.parse(createdAt);
+  if (!Number.isFinite(timestamp)) {
+    return null;
+  }
+  return timestamp;
+}
+
+function pruneSeenEntries(now: number): boolean {
+  const state = getState();
+  let changed = false;
+  const cutoff = now - DEFAULT_TTL_MS;
+
+  for (const [key, seenAt] of state.seen) {
+    if (seenAt <= cutoff) {
+      state.seen.delete(key);
+      changed = true;
+    }
+  }
+
+  while (state.seen.size > DEFAULT_MAX_ENTRIES) {
+    const oldestKey = state.seen.keys().next().value;
+    if (!oldestKey) {
+      break;
+    }
+    state.seen.delete(oldestKey);
+    changed = true;
+  }
+
+  if (changed) {
+    state.dirty = true;
+  }
+  state.lastSweepAt = now;
+  return changed;
+}
+
+function ensureSweepTimer(log?: { warn: (message: string) => void }): void {
+  const state = getState();
+  if (state.sweepTimer) {
+    return;
+  }
+  state.sweepTimer = setInterval(() => {
+    const now = Date.now();
+    const changed = pruneSeenEntries(now);
+    if (changed || state.dirty) {
+      void persistState(log);
+    }
+  }, DEFAULT_SWEEP_INTERVAL_MS);
+  state.sweepTimer.unref?.();
+}
+
+function schedulePersist(log?: { warn: (message: string) => void }): void {
+  const state = getState();
+  state.dirty = true;
+  if (state.persistTimer) {
+    return;
+  }
+  state.persistTimer = setTimeout(() => {
+    state.persistTimer = null;
+    void persistState(log);
+  }, PERSIST_DEBOUNCE_MS);
+  state.persistTimer.unref?.();
+}
+
+async function persistState(log?: { warn: (message: string) => void }): Promise<void> {
+  const state = getState();
+  if (!state.loaded || !state.dirty) {
+    return;
+  }
+
+  const now = Date.now();
+  pruneSeenEntries(now);
+  const { dedupDir, dedupFile, dedupTmpFile } = resolveDedupPaths();
+  const payload: MixinInboundDedupStore = {
+    version: DEDUP_STORE_VERSION,
+    entries: Array.from(state.seen.entries()).map(([key, seenAt]) => ({ key, seenAt })),
+  };
+
+  state.dirty = false;
+  state.persistChain = state.persistChain
+    .catch(() => {})
+    .then(async () => {
+      try {
+        await mkdir(dedupDir, { recursive: true });
+        await writeFile(dedupTmpFile, JSON.stringify(payload), "utf-8");
+        try {
+          await rename(dedupTmpFile, dedupFile);
+        } catch {
+          await writeFile(dedupFile, JSON.stringify(payload), "utf-8");
+        }
+      } catch (err) {
+        state.dirty = true;
+        log?.warn(
+          `[mixin] failed to persist inbound dedup store: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    });
+
+  await state.persistChain;
+}
+
+async function loadStateFromDisk(log?: { warn: (message: string) => void }): Promise<void> {
+  const state = getState();
+  const { dedupFile } = resolveDedupPaths();
+  state.seen.clear();
+  try {
+    const raw = await readFile(dedupFile, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<MixinInboundDedupStore>;
+    if (parsed.version === DEDUP_STORE_VERSION && Array.isArray(parsed.entries)) {
+      for (const entry of parsed.entries) {
+        if (!entry || typeof entry.key !== "string") {
+          continue;
+        }
+        const key = entry.key.trim();
+        const seenAt = normalizeTimestamp(entry.seenAt);
+        if (!key || seenAt === null) {
+          continue;
+        }
+        state.seen.set(key, seenAt);
+      }
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException | undefined)?.code !== "ENOENT") {
+      log?.warn(
+        `[mixin] failed to load inbound dedup store: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  state.loaded = true;
+  state.lastLoadedAt = Date.now();
+  pruneSeenEntries(Date.now());
+  ensureSweepTimer(log);
+}
+
+async function ensureLoaded(log?: { warn: (message: string) => void }): Promise<void> {
+  const state = getState();
+  if (state.loaded) {
+    return;
+  }
+  await loadStateFromDisk(log);
+}
+
+async function refreshStateFromDisk(log?: { warn: (message: string) => void }): Promise<void> {
+  const state = getState();
+  const { dedupFile } = resolveDedupPaths();
+  try {
+    const fileStat = await stat(dedupFile);
+    if (!state.loaded || fileStat.mtimeMs > state.lastLoadedAt) {
+      await loadStateFromDisk(log);
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException | undefined)?.code === "ENOENT") {
+      if (!state.loaded) {
+        state.loaded = true;
+        state.lastLoadedAt = Date.now();
+        ensureSweepTimer(log);
+      }
+      return;
+    }
+    log?.warn(
+      `[mixin] failed to refresh inbound dedup store: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+function shouldSweep(now: number): boolean {
+  const state = getState();
+  return now - state.lastSweepAt >= DEFAULT_SWEEP_INTERVAL_MS;
+}
+
+async function claimCrossProcessLock(
+  dedupeKey: string,
+  log?: { warn: (message: string) => void },
+): Promise<boolean> {
+  const { claimsDir } = resolveDedupPaths();
+  const claimFile = resolveClaimFilePath(dedupeKey);
+  await mkdir(claimsDir, { recursive: true });
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const handle = await open(claimFile, "wx");
+      try {
+        await handle.writeFile(JSON.stringify({ dedupeKey, claimedAt: Date.now(), pid: process.pid }), "utf-8");
+      } finally {
+        await handle.close();
+      }
+      return true;
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException | undefined)?.code;
+      if (code !== "EEXIST") {
+        log?.warn(
+          `[mixin] failed to create inbound dedup claim file: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        return false;
+      }
+      try {
+        const claimStat = await stat(claimFile);
+        if (Date.now() - claimStat.mtimeMs < CLAIM_STALE_MS) {
+          return false;
+        }
+        await rm(claimFile, { force: true });
+      } catch {
+        return false;
+      }
+    }
+  }
+
+  return false;
+}
+
+async function releaseCrossProcessLock(dedupeKey: string): Promise<void> {
+  const claimFile = resolveClaimFilePath(dedupeKey);
+  try {
+    await rm(claimFile, { force: true });
+  } catch (err) {
+    void err;
+  }
+}
+
+export async function claimMixinInboundMessage(params: ClaimMixinInboundMessageParams): Promise<ClaimMixinInboundMessageResult> {
+  const dedupeKey = buildDedupeScopeKey(params);
+  if (!dedupeKey.trim()) {
+    return {
+      ok: false,
+      dedupeKey,
+      reason: "invalid",
+    };
+  }
+
+  await ensureLoaded(params.log);
+  await refreshStateFromDisk(params.log);
+  const now = Date.now();
+  if (shouldSweep(now)) {
+    pruneSeenEntries(now);
+  }
+
+  const createdAtTs = parseCreatedAt(params.createdAt);
+  if (createdAtTs !== null && now - createdAtTs >= DEFAULT_STALE_MESSAGE_MS) {
+    return {
+      ok: false,
+      dedupeKey,
+      reason: "stale",
+    };
+  }
+
+  const state = getState();
+  const seenAt = state.seen.get(dedupeKey);
+  if (seenAt !== undefined && now - seenAt < DEFAULT_TTL_MS) {
+    return {
+      ok: false,
+      dedupeKey,
+      reason: "duplicate",
+    };
+  }
+
+  if (state.pending.has(dedupeKey)) {
+    return {
+      ok: false,
+      dedupeKey,
+      reason: "duplicate",
+    };
+  }
+
+  const claimed = await claimCrossProcessLock(dedupeKey, params.log);
+  if (!claimed) {
+    return {
+      ok: false,
+      dedupeKey,
+      reason: "duplicate",
+    };
+  }
+
+  state.pending.add(dedupeKey);
+  return {
+    ok: true,
+    dedupeKey,
+  };
+}
+
+export async function commitMixinInboundMessage(dedupeKey: string, log?: { warn: (message: string) => void }): Promise<void> {
+  const normalizedKey = dedupeKey.trim();
+  if (!normalizedKey) {
+    return;
+  }
+
+  await ensureLoaded(log);
+  const state = getState();
+  state.pending.delete(normalizedKey);
+  state.seen.delete(normalizedKey);
+  state.seen.set(normalizedKey, Date.now());
+  pruneSeenEntries(Date.now());
+  schedulePersist(log);
+  await persistState(log);
+}
+
+export async function releaseMixinInboundMessage(dedupeKey: string): Promise<void> {
+  const normalizedKey = dedupeKey.trim();
+  if (!normalizedKey) {
+    return;
+  }
+  const state = getState();
+  state.pending.delete(normalizedKey);
+  await releaseCrossProcessLock(normalizedKey);
+}
+
+export function buildMixinInboundDedupeKey(params: {
+  accountId: string;
+  conversationId?: string;
+  messageId: string;
+}): string {
+  return buildDedupeScopeKey(params);
+}
+
+export async function flushMixinInboundDedup(log?: { warn: (message: string) => void }): Promise<void> {
+  await ensureLoaded(log);
+  await persistState(log);
+}