@newbase-clawchat/openclaw-clawchat 2026.5.12-2 → 2026.5.12-21

package/src/group-message-coalescer.ts

@@ -0,0 +1,154 @@
+export type CoalescableGroupTurn = {
+  peer: { kind: "group"; id: string };
+  senderId: string;
+  senderNickName: string;
+  senderRelation?: "self_agent" | "owner" | "peer_agent" | "peer_user";
+  senderProfileType?: string | null;
+  senderIsOwner?: boolean;
+  rawBody: string;
+  messageId: string;
+  traceId: string;
+  timestamp: number;
+  wasMentioned: boolean;
+  mentionedUserIds: string[];
+  coalescedGroupBatch?: boolean;
+  mediaItems: unknown[];
+  replyCtx?: unknown;
+  envelope: unknown;
+};
+
+type PendingBatch<T extends CoalescableGroupTurn> = {
+  turns: T[];
+  idleTimer: ReturnType<typeof setTimeout>;
+  maxWaitTimer: ReturnType<typeof setTimeout>;
+};
+
+type CoalescedGroupTiming = {
+  idleSeconds: number;
+  maxWaitSeconds: number;
+};
+
+function formatTurnTime(timestamp: number): string {
+  if (!Number.isFinite(timestamp)) return "unknown-time";
+  const time = new Date(timestamp);
+  if (Number.isNaN(time.getTime())) return "unknown-time";
+  return time.toISOString();
+}
+
+function formatSenderRelation(turn: CoalescableGroupTurn): string {
+  return turn.senderRelation || "peer_user";
+}
+
+function formatSenderProfileType(turn: CoalescableGroupTurn): string {
+  if (turn.senderProfileType) return turn.senderProfileType;
+  const relation = formatSenderRelation(turn);
+  return relation === "self_agent" || relation === "peer_agent" ? "agent" : "user";
+}
+
+function formatMessageBody(rawBody: string): string {
+  return rawBody || "(empty message)";
+}
+
+function formatField(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/\r/g, "\\r").replace(/\n/g, "\\n");
+}
+
+function formatMentionedUserIds(turn: CoalescableGroupTurn): string {
+  return turn.mentionedUserIds.length ? turn.mentionedUserIds.join(",") : "-";
+}
+
+export function formatCoalescedGroupBody(
+  turns: CoalescableGroupTurn[],
+  timing: CoalescedGroupTiming = { idleSeconds: 10, maxWaitSeconds: 30 },
+): string {
+  const header = `ClawChat group batch (${turns.length} ${turns.length === 1 ? "message" : "messages"}, ${timing.idleSeconds}s idle, ${timing.maxWaitSeconds}s max):`;
+  return [
+    header,
+    turns.map((turn) => {
+      const senderName = turn.senderNickName || turn.senderId;
+      const senderIsOwner = turn.senderIsOwner ?? formatSenderRelation(turn) === "owner";
+      return [
+        "[message]",
+        `sender_id: ${formatField(turn.senderId)}`,
+        `sender_name: ${formatField(senderName)}`,
+        `sender_profile_type: ${formatField(formatSenderProfileType(turn))}`,
+        `sender_is_owner: ${senderIsOwner ? "true" : "false"}`,
+        `mentions_current_agent: ${turn.wasMentioned ? "true" : "false"}`,
+        `mentioned_user_ids: ${formatField(formatMentionedUserIds(turn))}`,
+        "text:",
+        formatMessageBody(turn.rawBody),
+      ].join("\n");
+    }).join("\n\n"),
+  ].join("\n");
+}
+
+export function mergeGroupTurns<T extends CoalescableGroupTurn>(
+  turns: T[],
+  timing: CoalescedGroupTiming = { idleSeconds: 10, maxWaitSeconds: 30 },
+): T {
+  if (turns.length === 0) throw new Error("cannot merge empty group turn batch");
+  const latest = turns[turns.length - 1]!;
+  return {
+    ...latest,
+    rawBody: formatCoalescedGroupBody(turns, timing),
+    mediaItems: turns.flatMap((turn) => turn.mediaItems) as T["mediaItems"],
+    wasMentioned: turns.some((turn) => turn.wasMentioned),
+    mentionedUserIds: Array.from(new Set(turns.flatMap((turn) => turn.mentionedUserIds))),
+    coalescedGroupBatch: true,
+  };
+}
+
+export function createGroupMessageCoalescer<T extends CoalescableGroupTurn>(params: {
+  idleMs: number;
+  maxWaitMs: number;
+  dispatch: (turn: T) => Promise<void>;
+  onError?: (error: unknown) => void;
+  onDrop?: (chatId: string, count: number) => void;
+}) {
+  const pending = new Map<string, PendingBatch<T>>();
+  const timing = {
+    idleSeconds: Math.round(params.idleMs / 1000),
+    maxWaitSeconds: Math.round(params.maxWaitMs / 1000),
+  };
+
+  const flush = (chatId: string) => {
+    const batch = pending.get(chatId);
+    if (!batch) return;
+    pending.delete(chatId);
+    clearTimeout(batch.idleTimer);
+    clearTimeout(batch.maxWaitTimer);
+    void params.dispatch(mergeGroupTurns(batch.turns, timing)).catch((error) => {
+      params.onError?.(error);
+    });
+  };
+
+  return {
+    enqueue(turn: T): void {
+      const chatId = turn.peer.id;
+      const existing = pending.get(chatId);
+      if (existing) {
+        existing.turns.push(turn);
+        clearTimeout(existing.idleTimer);
+        existing.idleTimer = setTimeout(() => flush(chatId), params.idleMs);
+        return;
+      }
+      const idleTimer = setTimeout(() => flush(chatId), params.idleMs);
+      const maxWaitTimer = setTimeout(() => flush(chatId), params.maxWaitMs);
+      pending.set(chatId, { turns: [turn], idleTimer, maxWaitTimer });
+    },
+    flushNow(chatId: string): void {
+      flush(chatId);
+    },
+    cancelAll(): void {
+      for (const [chatId, batch] of pending) {
+        clearTimeout(batch.idleTimer);
+        clearTimeout(batch.maxWaitTimer);
+        params.onDrop?.(chatId, batch.turns.length);
+      }
+      pending.clear();
+    },
+    pendingCount(chatId: string): number {
+      return pending.get(chatId)?.turns.length ?? 0;
+    },
+  };
+}

package/src/inbound.test.ts

@@ -1,8 +1,8 @@
-import type { Envelope, DownlinkMessageSendPayload } from "@newbase-clawchat/sdk";
+import type { Envelope, MessagePayload } from "./protocol-types.ts";
 import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
-import { dispatchOpenclawClawlingInbound, _resetDedupForTest } from "./inbound.ts";
+import { dispatchOpenclawClawlingInbound } from "./inbound.ts";
 
 function baseAccount(
   overrides: Partial<ResolvedOpenclawClawlingAccount> = {},
@@ -16,7 +16,12 @@ function baseAccount(
     baseUrl: "",
     token: "tk",
     userId: "agent-1",
+    ownerUserId: "owner-1",
     replyMode: "static",
+    groupMode: "all",
+    groupCommandMode: "owner",
+    groups: {},
+    richInteractions: false,
     forwardThinking: true,
     forwardToolCalls: false,
     allowFrom: [],
@@ -38,13 +43,13 @@ function buildSendEnvelope(
     event: "message.send" | "message.reply";
     text: string;
     chatType: "direct" | "group";
-    mentions: string[];
+    mentions: unknown[];
     reply: unknown;
     messageId: string;
     chatId: string;
     omitChatId: boolean;
   }> = {},
-): Envelope<DownlinkMessageSendPayload> {
+): Envelope<MessagePayload> {
   const chatId = overrides.chatId ?? "chat-1";
   const chatType = overrides.chatType ?? "direct";
   return {
@@ -78,9 +83,9 @@ function buildSendEnvelope(
           started_at: null,
           completed_at: null,
         },
-      } as DownlinkMessageSendPayload["message"],
+      } as MessagePayload["message"],
     },
-  } as Envelope<DownlinkMessageSendPayload>;
+  } as Envelope<MessagePayload>;
 }
 
 function buildStreamEnvelope(
@@ -135,10 +140,6 @@ function buildStreamEnvelope(
 }
 
 describe("openclaw-clawchat inbound", () => {
-  beforeEach(() => {
-    _resetDedupForTest();
-  });
-
   it("dispatches a plain text message and flattens the body", async () => {
     const ingest = vi.fn().mockResolvedValue(undefined);
     await dispatchOpenclawClawlingInbound({
@@ -177,7 +178,7 @@ describe("openclaw-clawchat inbound", () => {
         event: "message.done",
         messageId: "stream-1",
         fragments: [{ kind: "text", text: "completed stream" }],
-      }) as Envelope<DownlinkMessageSendPayload>,
+      }) as Envelope<MessagePayload>,
       cfg: {},
       runtime: {} as never,
       account: baseAccount(),
@@ -207,7 +208,7 @@ describe("openclaw-clawchat inbound", () => {
       }),
     ]) {
       await dispatchOpenclawClawlingInbound({
-        envelope: envelope as Envelope<DownlinkMessageSendPayload>,
+        envelope: envelope as Envelope<MessagePayload>,
         cfg: {},
         runtime: {} as never,
         account: baseAccount(),
@@ -231,7 +232,7 @@ describe("openclaw-clawchat inbound", () => {
           { kind: "mention", user_id: "agent-1", display: "@bot" },
           { kind: "text", text: " please help" },
         ],
-      }) as Envelope<DownlinkMessageSendPayload>,
+      }) as Envelope<MessagePayload>,
       cfg: {},
       runtime: {} as never,
       account: baseAccount({ groupMode: "mention" }),
@@ -255,7 +256,7 @@ describe("openclaw-clawchat inbound", () => {
     (envelope.payload as { streaming: { status: string } }).streaming.status = "failed";
 
     await dispatchOpenclawClawlingInbound({
-      envelope: envelope as Envelope<DownlinkMessageSendPayload>,
+      envelope: envelope as Envelope<MessagePayload>,
       cfg: {},
       runtime: {} as never,
       account: baseAccount(),
@@ -269,7 +270,7 @@ describe("openclaw-clawchat inbound", () => {
     for (const event of ["message.created", "message.add", "message.failed"] as const) {
       const ingest = vi.fn().mockResolvedValue(undefined);
       await dispatchOpenclawClawlingInbound({
-        envelope: buildStreamEnvelope({ event, messageId: `msg-${event}` }) as Envelope<DownlinkMessageSendPayload>,
+        envelope: buildStreamEnvelope({ event, messageId: `msg-${event}` }) as Envelope<MessagePayload>,
         cfg: {},
         runtime: {} as never,
         account: baseAccount(),
@@ -303,6 +304,41 @@ describe("openclaw-clawchat inbound", () => {
     ).toBe(true);
   });
 
+  it("detects object-shaped context mentions in group mention mode", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({
+        chatType: "group",
+        mentions: [{ user_id: "agent-1", display: "@bot" }],
+      }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount({ groupMode: "mention" }),
+      ingest,
+    });
+
+    expect(ingest).toHaveBeenCalledTimes(1);
+    expect(ingest.mock.calls[0]![0].wasMentioned).toBe(true);
+  });
+
+  it("preserves mentioned user ids when groupMode all mentions another user", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({
+        chatType: "group",
+        mentions: ["other-user"],
+      }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount({ groupMode: "all" }),
+      ingest,
+    });
+
+    expect(ingest).toHaveBeenCalledTimes(1);
+    expect(ingest.mock.calls[0]![0].wasMentioned).toBe(false);
+    expect(ingest.mock.calls[0]![0].mentionedUserIds).toEqual(["other-user"]);
+  });
+
   it("detectMention returns false for group chat when userId not mentioned", async () => {
     const { detectMention } = await import("./inbound.ts");
     expect(
@@ -326,6 +362,57 @@ describe("openclaw-clawchat inbound", () => {
     expect(ingest).not.toHaveBeenCalled();
   });
 
+  it("uses exact per-group mention mode for matching group chat_id", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({ chatType: "group", chatId: "group-quiet" }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount({
+        groupMode: "all",
+        groups: { "group-quiet": { groupMode: "mention", groupCommandMode: "owner" } },
+      }),
+      ingest,
+    });
+
+    expect(ingest).not.toHaveBeenCalled();
+  });
+
+  it("uses wildcard per-group mention mode when exact group is absent", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({ chatType: "group", chatId: "group-any" }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount({
+        groupMode: "all",
+        groups: { "*": { groupMode: "mention", groupCommandMode: "owner" } },
+      }),
+      ingest,
+    });
+
+    expect(ingest).not.toHaveBeenCalled();
+  });
+
+  it("lets exact per-group all mode override wildcard mention mode", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({ chatType: "group", chatId: "group-open" }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount({
+        groupMode: "mention",
+        groups: {
+          "group-open": { groupMode: "all", groupCommandMode: "owner" },
+          "*": { groupMode: "mention", groupCommandMode: "owner" },
+        },
+      }),
+      ingest,
+    });
+
+    expect(ingest).toHaveBeenCalledTimes(1);
+  });
+
   it("skips messages with empty renderable text", async () => {
     const ingest = vi.fn().mockResolvedValue(undefined);
     await dispatchOpenclawClawlingInbound({
@@ -365,7 +452,7 @@ describe("openclaw-clawchat inbound", () => {
     });
   });
 
-  it("deduplicates repeat message_ids", async () => {
+  it("does not own duplicate suppression when the same message_id is parsed twice", async () => {
     const ingest = vi.fn().mockResolvedValue(undefined);
     const env = buildSendEnvelope({ messageId: "dup-1" });
     await dispatchOpenclawClawlingInbound({
@@ -382,13 +469,13 @@ describe("openclaw-clawchat inbound", () => {
       account: baseAccount(),
       ingest,
     });
-    expect(ingest).toHaveBeenCalledTimes(1);
+    expect(ingest).toHaveBeenCalledTimes(2);
   });
 
   it("passes mediaItems extracted from body fragments to ingest", async () => {
     const ingest = vi.fn().mockResolvedValue(undefined);
     const env = buildSendEnvelope({});
-    // Replace the body's fragments with text + image (SDK 0.2.0 typed union accepts these directly)
+    // Replace the body's fragments with text + image; the local fragment union accepts these directly.
     env.payload.message.body.fragments = [
       { kind: "text", text: "hello" },
       { kind: "image", url: "https://cdn/x.png", mime: "image/png" },

package/src/inbound.ts

@@ -2,9 +2,9 @@ import {
   EVENT,
   type ChatType,
   type Envelope,
-} from "@newbase-clawchat/sdk";
+} from "./protocol-types.ts";
 import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/core";
-import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+import { effectiveGroupMode, type ResolvedOpenclawClawlingAccount } from "./config.ts";
 import type { MediaItem } from "./media-runtime.ts";
 import { extractMediaFragments, fragmentsToText } from "./message-mapper.ts";
 import { hasRenderableText, isInboundMessagePayload } from "./protocol.ts";
@@ -20,11 +20,16 @@ export interface IngestTurnParams {
   peer: { kind: "direct" | "group"; id: string };
   senderId: string;
   senderNickName: string;
+  senderRelation?: "self_agent" | "owner" | "peer_agent" | "peer_user";
+  senderProfileType?: string | null;
+  senderIsOwner?: boolean;
   rawBody: string;
   messageId: string;
   traceId: string;
   timestamp: number;
   wasMentioned: boolean;
+  mentionedUserIds: string[];
+  coalescedGroupBatch?: boolean;
   mediaItems: MediaItem[];
   replyCtx?: {
     replyToMessageId: string;
@@ -48,23 +53,20 @@ export interface DispatchInboundParams {
   log?: { info?: (m: string) => void; error?: (m: string) => void };
 }
 
-const DEDUP_MAX = 256;
-const dedupSeen: string[] = [];
-const dedupSet = new Set<string>();
-
 type SenderLike = {
   id?: unknown;
   nick_name?: unknown;
   type?: unknown;
 };
 
-function normalizeSender(sender: unknown): { id: string; nickName: string } | null {
+function normalizeSender(sender: unknown): { id: string; nickName: string; profileType: string | null } | null {
   if (!sender || typeof sender !== "object") return null;
   const s = sender as SenderLike;
   const id = typeof s.id === "string" ? s.id : "";
   if (!id) return null;
   const nickName = typeof s.nick_name === "string" ? s.nick_name : id;
-  return { id, nickName };
+  const profileType = s.type === "agent" || s.type === "user" ? s.type : null;
+  return { id, nickName, profileType };
 }
 
 function isStreamDonePayload(payload: unknown): payload is {
@@ -93,20 +95,17 @@ function extractMentionIds(fragments: Array<Record<string, unknown>>): string[]
     .filter((userId): userId is string => typeof userId === "string" && userId.length > 0);
 }
 
-export function _resetDedupForTest(): void {
-  dedupSeen.length = 0;
-  dedupSet.clear();
-}
-
-function rememberAndCheck(messageId: string): boolean {
-  if (dedupSet.has(messageId)) return true;
-  dedupSet.add(messageId);
-  dedupSeen.push(messageId);
-  if (dedupSeen.length > DEDUP_MAX) {
-    const evict = dedupSeen.shift();
-    if (evict) dedupSet.delete(evict);
-  }
-  return false;
+function normalizeMentionIds(mentions: unknown[]): string[] {
+  return mentions
+    .map((mention) => {
+      if (typeof mention === "string") return mention;
+      if (mention && typeof mention === "object") {
+        const userId = (mention as { user_id?: unknown }).user_id;
+        return typeof userId === "string" ? userId : undefined;
+      }
+      return undefined;
+    })
+    .filter((userId): userId is string => typeof userId === "string" && userId.length > 0);
 }
 
 /**
@@ -114,12 +113,12 @@ function rememberAndCheck(messageId: string): boolean {
  * group chats require a mention unless config opts into all group messages.
  */
 export function detectMention(params: {
-  mentions: string[];
+  mentions: unknown[];
   chatType: "direct" | "group";
   userId: string;
 }): boolean {
   if (params.chatType === "direct") return true;
-  return params.mentions.includes(params.userId);
+  return normalizeMentionIds(params.mentions).includes(params.userId);
 }
 
 export async function dispatchOpenclawClawlingInbound(
@@ -167,7 +166,7 @@ export async function dispatchOpenclawClawlingInbound(
       }) as {
     body: { fragments: Array<Record<string, unknown>> };
     context: {
-      mentions: string[];
+      mentions: unknown[];
       reply: {
         reply_to_msg_id: string;
         reply_preview: {
@@ -200,19 +199,13 @@ export async function dispatchOpenclawClawlingInbound(
     );
     return;
   }
-  if (rememberAndCheck(payload.message_id)) {
-    log?.info?.(
-      `[${account.accountId}] openclaw-clawchat skip duplicate msg=${payload.message_id}`,
-    );
-    return;
-  }
-
+  const mentionIds = normalizeMentionIds(message.context.mentions);
   const rawBody = fragmentsToText(message.body.fragments as never, {
-    mentionFallbackIds: message.context.mentions,
+    mentionFallbackIds: mentionIds,
   });
   const mediaItems = extractMediaFragments(message.body.fragments as never);
   const wasMentioned = detectMention({
-    mentions: message.context.mentions,
+    mentions: mentionIds,
     chatType,
     userId: account.userId,
   });
@@ -220,7 +213,8 @@ export async function dispatchOpenclawClawlingInbound(
   // Group trigger policy: in "mention" mode we only handle group messages
   // that @-mention us; "all" listens open and processes every group msg.
   // Direct chats are unaffected (detectMention returns true).
-  if (isGroup && account.groupMode === "mention" && !wasMentioned) {
+  const groupMode = isGroup ? effectiveGroupMode(account, chatId) : account.groupMode;
+  if (isGroup && groupMode === "mention" && !wasMentioned) {
     log?.info?.(
       `[${account.accountId}] openclaw-clawchat skip group (no mention) msg=${payload.message_id}`,
     );
@@ -247,11 +241,13 @@ export async function dispatchOpenclawClawlingInbound(
     peer: { kind: isGroup ? "group" : "direct", id: chatId },
     senderId: sender.id,
     senderNickName: sender.nickName,
+    ...(sender.profileType ? { senderProfileType: sender.profileType } : {}),
     rawBody,
     messageId: payload.message_id,
     traceId: envelope.trace_id,
     timestamp: envelope.emitted_at,
     wasMentioned,
+    mentionedUserIds: mentionIds,
     mediaItems,
     ...(replyCtx ? { replyCtx } : {}),
     cfg: params.cfg,