@invago/mixin 1.0.16 → 1.0.18

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,12 +29,10 @@ export interface MixinInboundMessage {
   quoteMessageId?: string;
   publicKey?: string;
 }
-
-const processedMessages = 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;
@@ -46,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;
@@ -68,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";
@@ -161,21 +172,7 @@ function evaluateMixinSenderGroupAccess(params: {
   };
 }
 
-function isProcessed(messageId: string): boolean {
-  return processedMessages.has(messageId);
-}
-
-function markProcessed(messageId: string): void {
-  if (processedMessages.size >= MAX_DEDUP_SIZE) {
-    const first = processedMessages.values().next().value;
-    if (first) {
-      processedMessages.delete(first);
-    }
-  }
-  processedMessages.add(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);
@@ -230,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) {
@@ -361,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;
@@ -621,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;
@@ -980,76 +1183,108 @@ function evaluateMixinGroupAccess(params: {
   };
 }
 
-export async function handleMixinMessage(params: {
-  cfg: OpenClawConfig;
-  accountId: string;
+export async function handleMixinMessage(params: {
+  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> {
-  const { cfg, accountId, msg, isDirect, log } = params;
-  const rt = getMixinRuntime();
-
-  if (isProcessed(msg.messageId)) {
-    return;
-  }
-
-  const config = getAccountConfig(cfg, accountId);
-
-  if (msg.category === "ENCRYPTED_TEXT" || msg.category === "ENCRYPTED_POST") {
-    log.info(`[mixin] decrypting encrypted message ${msg.messageId}, category=${msg.category}`);
-    try {
-      const decrypted = decryptMixinMessage(
-        msg.data,
-        config.sessionPrivateKey!,
-        config.sessionId!,
-      );
-      if (!decrypted) {
-        log.error(`[mixin] decryption failed for ${msg.messageId}`);
-        markProcessed(msg.messageId);
-        return;
-      }
-      log.info(`[mixin] decryption successful: messageId=${msg.messageId}, length=${decrypted.length}`);
-      msg.data = Buffer.from(decrypted).toString("base64");
-      msg.category = "PLAIN_TEXT";
-    } catch (err) {
-      log.error(`[mixin] decryption exception for ${msg.messageId}`, err);
-      markProcessed(msg.messageId);
-      return;
-    }
-  }
-
-  let isTextMessage = msg.category.startsWith("PLAIN_TEXT") || msg.category.startsWith("PLAIN_POST");
-  const isAttachmentMessage = msg.category === "PLAIN_DATA" || msg.category === "PLAIN_AUDIO";
+}): Promise<void> {
+  const { cfg, accountId, msg, isDirect, log } = params;
+  const rt = getMixinRuntime();
 
-  if (!isTextMessage && !isAttachmentMessage) {
-    const fallbackText = tryDecodeFallbackText(msg.data);
-    if (fallbackText) {
-      log.warn(
-        `[mixin] treating unexpected category as text: messageId=${msg.messageId}, category=${msg.category}, fallbackLength=${fallbackText.length}`,
-      );
-      msg.category = "PLAIN_TEXT";
-      msg.data = Buffer.from(fallbackText).toString("base64");
-      isTextMessage = true;
+  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}`);
     }
-  }
-
-  if (!isTextMessage && !isAttachmentMessage) {
-    log.info(
-      `[mixin] skip non-text message: messageId=${msg.messageId}, category=${msg.category}, quoteMessageId=${msg.quoteMessageId ?? "none"}`,
-    );
     return;
   }
+  const dedupeKey = claim.dedupeKey;
+  let committed = false;
 
-  const decodedBody = decodeContent(msg.category, msg.data);
-  let text = decodedBody.trim();
-  let mediaPayload: AgentMediaPayload | undefined;
-  if (isAttachmentMessage) {
-    const resolved = await resolveInboundAttachment({ rt, config, msg, log });
-    text = resolved.text.trim();
-    mediaPayload = resolved.mediaPayload;
-  }
-  log.info(`[mixin] decoded text: messageId=${msg.messageId}, category=${msg.category}, length=${text.length}`);
+  const commit = async (): Promise<void> => {
+    if (committed) {
+      return;
+    }
+    committed = true;
+    await commitMixinInboundMessage(dedupeKey, log);
+  };
+
+  try {
+    const config = getAccountConfig(cfg, accountId);
+
+    if (msg.category === "ENCRYPTED_TEXT" || msg.category === "ENCRYPTED_POST") {
+      log.info(`[mixin] decrypting encrypted message ${msg.messageId}, category=${msg.category}`);
+      try {
+        const decrypted = decryptMixinMessage(
+          msg.data,
+          config.sessionPrivateKey!,
+          config.sessionId!,
+        );
+        if (!decrypted) {
+          log.error(`[mixin] decryption failed for ${msg.messageId}`);
+          await commit();
+          return;
+        }
+        log.info(`[mixin] decryption successful: messageId=${msg.messageId}, length=${decrypted.length}`);
+        msg.data = Buffer.from(decrypted).toString("base64");
+        msg.category = "PLAIN_TEXT";
+      } catch (err) {
+        log.error(`[mixin] decryption exception for ${msg.messageId}`, err);
+        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";
+
+    if (!isTextMessage && !isAttachmentMessage) {
+      const fallbackText = tryDecodeFallbackText(msg.data);
+      if (fallbackText) {
+        log.warn(
+          `[mixin] treating unexpected category as text: messageId=${msg.messageId}, category=${msg.category}, fallbackLength=${fallbackText.length}`,
+        );
+        msg.category = "PLAIN_TEXT";
+        msg.data = Buffer.from(fallbackText).toString("base64");
+        isTextMessage = true;
+      }
+    }
+
+    if (!isTextMessage && !isAttachmentMessage) {
+      log.info(
+        `[mixin] skip non-text message: messageId=${msg.messageId}, category=${msg.category}, quoteMessageId=${msg.quoteMessageId ?? "none"}`,
+      );
+      await commit();
+      return;
+    }
+
+    const decodedBody = decodeContent(msg.category, msg.data);
+    let text = decodedBody.trim();
+    let mediaPayload: AgentMediaPayload | undefined;
+    if (isAttachmentMessage) {
+      const resolved = await resolveInboundAttachment({ rt, config, msg, log });
+      text = resolved.text.trim();
+      mediaPayload = resolved.mediaPayload;
+    }
+    log.info(`[mixin] decoded text: messageId=${msg.messageId}, category=${msg.category}, length=${text.length}`);
 
   const botIdentity = await resolveBotIdentity({
     accountId,
@@ -1082,6 +1317,7 @@ export async function handleMixinMessage(params: {
   }
 
   if (!text) {
+    await commit();
     return;
   }
 
@@ -1094,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}`,
     );
   }
 
@@ -1104,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;
   }
 
@@ -1142,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({
@@ -1160,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,
@@ -1176,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)) {
@@ -1304,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;
@@ -1329,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({
@@ -1366,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,
@@ -1397,26 +1646,103 @@ export async function handleMixinMessage(params: {
 
   log.info(`[mixin] dispatching ${msg.messageId} from ${msg.userId}`);
 
-  await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-    ctx,
-    cfg,
-    dispatcherOptions: {
-      deliver: async (payload) => {
-        const replyText = payload.text ?? "";
-        if (!replyText) {
-          return;
-        }
-        const recipientId = isDirect ? msg.userId : undefined;
-        await deliverMixinReply({
-          cfg,
-          accountId,
-          conversationId: msg.conversationId,
-          recipientId,
-          creatorId: msg.userId,
-          text: replyText,
-          log,
-        });
-      },
-    },
-  });
-}
+    await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+      ctx,
+      cfg,
+      dispatcherOptions: {
+        deliver: async (payload) => {
+          const replyText = payload.text ?? "";
+          if (!replyText) {
+            return;
+          }
+          const recipientId = isDirect ? msg.userId : undefined;
+          await deliverMixinReply({
+            cfg,
+            accountId,
+            conversationId: msg.conversationId,
+            recipientId,
+            creatorId: msg.userId,
+            text: replyText,
+            log,
+          });
+        },
+      },
+    });
+  } finally {
+    if (!committed) {
+      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 {
+    if (!committed) {
+      releaseMixinInboundMessage(dedupeKey);
+    }
+  }
+}