@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/config.ts

@@ -0,0 +1,404 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
+
+export const CHANNEL_ID = "clawchat-plugin-openclaw" as const;
+export const CLAWCHAT_TOKEN_ENV = "CLAWCHAT_TOKEN" as const;
+export const CLAWCHAT_AGENT_ID_ENV = "CLAWCHAT_AGENT_ID" as const;
+export const CLAWCHAT_USER_ID_ENV = "CLAWCHAT_USER_ID" as const;
+export const CLAWCHAT_OWNER_USER_ID_ENV = "CLAWCHAT_OWNER_USER_ID" as const;
+export const CLAWCHAT_REFRESH_TOKEN_ENV = "CLAWCHAT_REFRESH_TOKEN" as const;
+export const CLAWCHAT_BASE_URL_ENV = "CLAWCHAT_BASE_URL" as const;
+export const CLAWCHAT_WEBSOCKET_URL_ENV = "CLAWCHAT_WEBSOCKET_URL" as const;
+
+/**
+ * Built-in defaults for the Clawling Chat endpoints so `openclaw channel
+ * login` works out of the box without requiring a prior `openclaw channel
+ * setup` call. Operators can still override either one via config.
+ *
+ */
+export const DEFAULT_BASE_URL = "https://app.clawling.com" as const;
+export const DEFAULT_WEBSOCKET_URL = "wss://app.clawling.com/ws" as const;
+
+/**
+ * Group-chat trigger policy.
+ * - "all" (default): trigger on every group message regardless of mentions (open listen).
+ * - "mention": only trigger a reply when the inbound `context.mentions`
+ *   list includes our `userId` (i.e. the sender @-mentioned us).
+ */
+export type GroupMode = "mention" | "all";
+export type GroupCommandMode = "owner" | "all" | "off";
+
+export const DEFAULT_RECONNECT = {
+  // Snappier first retry on transient drops (vs. 1_000).
+  initialDelay: 500,
+  // Cap exponential backoff at 15s — a background gateway reconnecting
+  // every 30s feels unresponsive; 15s is the common IM chat bar.
+  maxDelay: 15_000,
+  // Standard jitter ratio to avoid thundering herd on server restart.
+  jitterRatio: 0.3,
+  // Never give up — the gateway is a long-lived background process.
+  maxRetries: Number.POSITIVE_INFINITY,
+} as const;
+
+export const DEFAULT_HEARTBEAT = {
+  // 20s keeps NAT/firewall state warm without wasting bandwidth.
+  interval: 20_000,
+  // Pong must arrive within 10s or we tear down and reconnect.
+  timeout: 10_000,
+} as const;
+
+export const DEFAULT_ACK = {
+  // 15s tolerates a slow server + one retry without false timeouts.
+  timeout: 15_000,
+  // Keep false: auto-resend on timeout risks duplicate messages; the
+  // reconnect path re-queues via `queueWhileReconnecting` instead.
+  autoResendOnTimeout: false,
+} as const;
+
+export type OpenclawClawlingGroupConfig = {
+  groupMode: GroupMode;
+  groupCommandMode: GroupCommandMode;
+};
+
+export type OpenclawClawlingReconnectConfig = {
+  initialDelay?: number;
+  maxDelay?: number;
+  jitterRatio?: number;
+  /** Max reconnect attempts. Omit/Infinity = never give up. */
+  maxRetries?: number;
+};
+
+export type OpenclawClawlingHeartbeatConfig = {
+  interval?: number;
+  timeout?: number;
+};
+
+export type OpenclawClawlingAckConfig = {
+  timeout?: number;
+  autoResendOnTimeout?: boolean;
+};
+
+export type OpenclawClawlingConfig = {
+  enabled?: boolean;
+  websocketUrl?: string;
+  baseUrl?: string;
+  token?: string;
+  /** Refresh token persisted by ClawChat activation/login (paired with `token`). */
+  refreshToken?: string;
+  /** Server agent id used with `/v1/agents/{id}`. */
+  agentId?: string;
+  userId?: string;
+  ownerUserId?: string;
+  groupMode?: GroupMode;
+  groupCommandMode?: GroupCommandMode;
+  groups?: Record<string, Partial<OpenclawClawlingGroupConfig>>;
+  forwardThinking?: boolean;
+  forwardToolCalls?: boolean;
+  /** Emit approval/action rich fragments instead of plain fallback text. */
+  richInteractions?: boolean;
+  reconnect?: OpenclawClawlingReconnectConfig;
+  heartbeat?: OpenclawClawlingHeartbeatConfig;
+  ack?: OpenclawClawlingAckConfig;
+};
+
+export const openclawClawlingConfigSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    enabled: { type: "boolean" },
+    websocketUrl: { type: "string" },
+    baseUrl: { type: "string" },
+    token: { type: "string" },
+    refreshToken: { type: "string" },
+    agentId: { type: "string" },
+    userId: { type: "string" },
+    ownerUserId: { type: "string" },
+    groupMode: { type: "string", enum: ["mention", "all"] },
+    groupCommandMode: { type: "string", enum: ["owner", "all", "off"] },
+    groups: {
+      type: "object",
+      additionalProperties: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          groupMode: { type: "string", enum: ["mention", "all"] },
+          groupCommandMode: { type: "string", enum: ["owner", "all", "off"] },
+        },
+      },
+    },
+    forwardThinking: { type: "boolean" },
+    forwardToolCalls: { type: "boolean" },
+    richInteractions: { type: "boolean" },
+    reconnect: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        initialDelay: { type: "integer", minimum: 100 },
+        maxDelay: { type: "integer", minimum: 100 },
+        jitterRatio: { type: "number", minimum: 0 },
+        maxRetries: { type: "integer", minimum: 0 },
+      },
+    },
+    heartbeat: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        interval: { type: "integer", minimum: 1000 },
+        timeout: { type: "integer", minimum: 1000 },
+      },
+    },
+    ack: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        timeout: { type: "integer", minimum: 100 },
+        autoResendOnTimeout: { type: "boolean" },
+      },
+    },
+  },
+} as const;
+
+function isOpenclawClawchatToolAllowEntry(entry: unknown): boolean {
+  return entry === CHANNEL_ID || entry === "group:plugins";
+}
+
+function mergeToolPolicyEntryAlsoAllow(
+  cfg: OpenClawConfig,
+  entry: string,
+  isAlreadyCovered: (value: unknown) => boolean,
+): OpenClawConfig {
+  const currentTools = ((cfg as { tools?: Record<string, unknown> }).tools ?? {}) as Record<
+    string,
+    unknown
+  >;
+  const currentAlsoAllow = Array.isArray(currentTools.alsoAllow)
+    ? currentTools.alsoAllow.slice()
+    : [];
+  const currentAllow = Array.isArray(currentTools.allow) ? currentTools.allow.slice() : [];
+  const alreadyCovered = [...currentAllow, ...currentAlsoAllow].some(isAlreadyCovered);
+  if (alreadyCovered) {
+    return {
+      ...cfg,
+      tools: {
+        ...currentTools,
+        ...(Array.isArray(currentTools.allow) ? { allow: currentAllow } : {}),
+        ...(Array.isArray(currentTools.alsoAllow) ? { alsoAllow: currentAlsoAllow } : {}),
+      },
+    } as OpenClawConfig;
+  }
+  return {
+    ...cfg,
+    tools: {
+      ...currentTools,
+      alsoAllow: [...currentAlsoAllow, entry],
+    },
+  } as OpenClawConfig;
+}
+
+export function mergeOpenclawClawchatToolAllow(cfg: OpenClawConfig): OpenClawConfig {
+  return mergeToolPolicyEntryAlsoAllow(cfg, CHANNEL_ID, isOpenclawClawchatToolAllowEntry);
+}
+
+function readRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export function mergeOpenclawClawchatRuntimePluginActivation(
+  cfg: OpenClawConfig,
+): OpenClawConfig {
+  const currentPlugins = readRecord((cfg as { plugins?: unknown }).plugins);
+  const currentEntries = readRecord(currentPlugins.entries);
+  const currentEntry = readRecord(currentEntries[CHANNEL_ID]);
+  const currentAllow = Array.isArray(currentPlugins.allow) ? currentPlugins.allow.slice() : [];
+  const nextPlugins: Record<string, unknown> = {
+    ...currentPlugins,
+    entries: {
+      ...currentEntries,
+      [CHANNEL_ID]: {
+        ...currentEntry,
+        enabled: true,
+      },
+    },
+  };
+  if (!currentAllow.includes(CHANNEL_ID)) {
+    nextPlugins.allow = [...currentAllow, CHANNEL_ID];
+  }
+  return {
+    ...cfg,
+    plugins: nextPlugins,
+  } as OpenClawConfig;
+}
+
+export type ResolvedOpenclawClawlingAccount = {
+  accountId: string;
+  name: string;
+  enabled: boolean;
+  configured: boolean;
+  websocketUrl: string;
+  baseUrl: string;
+  token: string;
+  agentId: string;
+  userId: string;
+  ownerUserId: string;
+  groupMode: GroupMode;
+  groupCommandMode: GroupCommandMode;
+  groups: Record<string, OpenclawClawlingGroupConfig>;
+  forwardThinking: boolean;
+  forwardToolCalls: boolean;
+  richInteractions: boolean;
+  allowFrom: string[];
+  reconnect: Required<OpenclawClawlingReconnectConfig>;
+  heartbeat: Required<OpenclawClawlingHeartbeatConfig>;
+  ack: Required<OpenclawClawlingAckConfig>;
+};
+
+function readChannelSection(cfg: OpenClawConfig): Record<string, unknown> {
+  const channels = (cfg.channels ?? {}) as Record<string, unknown>;
+  const channel = channels[CHANNEL_ID];
+  return channel && typeof channel === "object" ? (channel as Record<string, unknown>) : {};
+}
+
+function readOptionalString(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function readEnvString(env: Record<string, string | undefined>, key: string): string {
+  return readOptionalString(env[key]);
+}
+
+function readGroupMode(value: unknown): GroupMode {
+  return value === "mention" ? "mention" : "all";
+}
+
+function readGroupCommandMode(value: unknown): GroupCommandMode {
+  return value === "all" || value === "off" ? value : "owner";
+}
+
+function readGroups(value: unknown): Record<string, OpenclawClawlingGroupConfig> {
+  const rawGroups = value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+  const groups: Record<string, OpenclawClawlingGroupConfig> = {};
+  for (const [chatId, rawGroup] of Object.entries(rawGroups)) {
+    if (!chatId) continue;
+    const group = rawGroup && typeof rawGroup === "object" && !Array.isArray(rawGroup)
+      ? (rawGroup as Record<string, unknown>)
+      : {};
+    groups[chatId] = {
+      groupMode: readGroupMode(group.groupMode),
+      groupCommandMode: readGroupCommandMode(group.groupCommandMode),
+    };
+  }
+  return groups;
+}
+
+export function effectiveGroupMode(
+  account: Pick<ResolvedOpenclawClawlingAccount, "groupMode" | "groups">,
+  chatId: string,
+): GroupMode {
+  return account.groups[chatId]?.groupMode
+    ?? account.groups["*"]?.groupMode
+    ?? account.groupMode;
+}
+
+export function effectiveGroupCommandMode(
+  account: Pick<ResolvedOpenclawClawlingAccount, "groupCommandMode" | "groups">,
+  chatId: string,
+): GroupCommandMode {
+  return account.groups[chatId]?.groupCommandMode
+    ?? account.groups["*"]?.groupCommandMode
+    ?? account.groupCommandMode;
+}
+
+function readReconnect(raw: unknown): Required<OpenclawClawlingReconnectConfig> {
+  const s = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+  return {
+    initialDelay:
+      typeof s.initialDelay === "number" ? s.initialDelay : DEFAULT_RECONNECT.initialDelay,
+    maxDelay: typeof s.maxDelay === "number" ? s.maxDelay : DEFAULT_RECONNECT.maxDelay,
+    jitterRatio: typeof s.jitterRatio === "number" ? s.jitterRatio : DEFAULT_RECONNECT.jitterRatio,
+    maxRetries:
+      typeof s.maxRetries === "number" && Number.isFinite(s.maxRetries)
+        ? s.maxRetries
+        : DEFAULT_RECONNECT.maxRetries,
+  };
+}
+
+function readHeartbeat(raw: unknown): Required<OpenclawClawlingHeartbeatConfig> {
+  const s = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+  return {
+    interval: typeof s.interval === "number" ? s.interval : DEFAULT_HEARTBEAT.interval,
+    timeout: typeof s.timeout === "number" ? s.timeout : DEFAULT_HEARTBEAT.timeout,
+  };
+}
+
+function readAck(raw: unknown): Required<OpenclawClawlingAckConfig> {
+  const s = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+  return {
+    timeout: typeof s.timeout === "number" ? s.timeout : DEFAULT_ACK.timeout,
+    autoResendOnTimeout:
+      typeof s.autoResendOnTimeout === "boolean"
+        ? s.autoResendOnTimeout
+        : DEFAULT_ACK.autoResendOnTimeout,
+  };
+}
+
+export function resolveOpenclawClawlingAccount(
+  cfg: OpenClawConfig,
+  env: Record<string, string | undefined> = process.env,
+): ResolvedOpenclawClawlingAccount {
+  const channel = readChannelSection(cfg);
+  // Apply built-in defaults so login/gateway work without prior setup.
+  const websocketUrl =
+    readOptionalString(channel.websocketUrl) ||
+    readEnvString(env, CLAWCHAT_WEBSOCKET_URL_ENV) ||
+    DEFAULT_WEBSOCKET_URL;
+  const baseUrl =
+    readOptionalString(channel.baseUrl) ||
+    readEnvString(env, CLAWCHAT_BASE_URL_ENV) ||
+    DEFAULT_BASE_URL;
+  const token = readOptionalString(channel.token) || readEnvString(env, CLAWCHAT_TOKEN_ENV);
+  const agentId = readOptionalString(channel.agentId) || readEnvString(env, CLAWCHAT_AGENT_ID_ENV);
+  const userId = readOptionalString(channel.userId) || readEnvString(env, CLAWCHAT_USER_ID_ENV);
+  const ownerUserId =
+    readOptionalString(channel.ownerUserId) || readEnvString(env, CLAWCHAT_OWNER_USER_ID_ENV);
+  const enabled = typeof channel.enabled === "boolean" ? channel.enabled : true;
+  const groupMode = readGroupMode(channel.groupMode);
+  const groupCommandMode = readGroupCommandMode(channel.groupCommandMode);
+  const groups = readGroups(channel.groups);
+  const forwardThinking =
+    typeof channel.forwardThinking === "boolean" ? channel.forwardThinking : true;
+  const forwardToolCalls =
+    typeof channel.forwardToolCalls === "boolean" ? channel.forwardToolCalls : false;
+  const richInteractions =
+    typeof channel.richInteractions === "boolean" ? channel.richInteractions : false;
+
+  return {
+    accountId: DEFAULT_ACCOUNT_ID,
+    name: CHANNEL_ID,
+    enabled,
+    configured: Boolean(websocketUrl && token && userId && ownerUserId),
+    websocketUrl,
+    baseUrl,
+    token,
+    agentId,
+    userId,
+    ownerUserId,
+    groupMode,
+    groupCommandMode,
+    groups,
+    forwardThinking,
+    forwardToolCalls,
+    richInteractions,
+    allowFrom: [],
+    reconnect: readReconnect(channel.reconnect),
+    heartbeat: readHeartbeat(channel.heartbeat),
+    ack: readAck(channel.ack),
+  };
+}
+
+export function listOpenclawClawlingAccountIds(): string[] {
+  return [DEFAULT_ACCOUNT_ID];
+}

package/src/group-message-coalescer.test.ts

@@ -0,0 +1,237 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  createGroupMessageCoalescer,
+  formatCoalescedGroupBody,
+  type CoalescableGroupTurn,
+} from "./group-message-coalescer.ts";
+
+function turn(overrides: Partial<CoalescableGroupTurn> = {}): CoalescableGroupTurn {
+  return {
+    peer: { kind: "group", id: "room-1" },
+    senderId: "user-a",
+    senderNickName: "Alice",
+    rawBody: "hello",
+    messageId: "msg-1",
+    traceId: "trace-1",
+    timestamp: 1000,
+    wasMentioned: false,
+    mentionedUserIds: [],
+    mediaItems: [],
+    envelope: { event: "message.send", trace_id: "trace-1", emitted_at: 1000 },
+    ...overrides,
+  };
+}
+
+beforeEach(() => vi.useFakeTimers());
+afterEach(() => vi.useRealTimers());
+
+describe("group message coalescer", () => {
+  it("flushes after ten seconds of group inactivity", async () => {
+    const dispatched: CoalescableGroupTurn[] = [];
+    const coalescer = createGroupMessageCoalescer({
+      idleMs: 10000,
+      maxWaitMs: 30000,
+      dispatch: async (merged) => {
+        dispatched.push(merged);
+      },
+    });
+
+    coalescer.enqueue(turn({ messageId: "msg-1", rawBody: "one" }));
+    await vi.advanceTimersByTimeAsync(9999);
+
+    coalescer.enqueue(
+      turn({
+        messageId: "msg-2",
+        senderId: "user-b",
+        senderNickName: "Bob",
+        rawBody: "two",
+      }),
+    );
+
+    await vi.advanceTimersByTimeAsync(9999);
+    expect(dispatched).toEqual([]);
+
+    await vi.advanceTimersByTimeAsync(1);
+    expect(dispatched).toHaveLength(1);
+    expect(dispatched[0]?.messageId).toBe("msg-2");
+    expect(dispatched[0]?.rawBody).toContain("ClawChat group batch (2 messages, 10s idle, 30s max)");
+    expect(dispatched[0]?.rawBody).toContain("[message]\nsender_id: user-a\nsender_name: Alice\nsender_profile_type: user\nsender_is_agent_owner: false\nsender_is_group_owner: false\nmentions_current_agent: false\nmentioned_users: -\ntext:\none");
+    expect(dispatched[0]?.rawBody).toContain("[message]\nsender_id: user-b\nsender_name: Bob\nsender_profile_type: user\nsender_is_agent_owner: false\nsender_is_group_owner: false\nmentions_current_agent: false\nmentioned_users: -\ntext:\ntwo");
+    expect(dispatched[0]?.rawBody).not.toContain("sender_relation");
+    expect(dispatched[0]?.rawBody).not.toContain("[msg-");
+  });
+
+  it("flushes at thirty seconds even while group messages keep arriving", async () => {
+    const dispatched: CoalescableGroupTurn[] = [];
+    const coalescer = createGroupMessageCoalescer({
+      idleMs: 10000,
+      maxWaitMs: 30000,
+      dispatch: async (merged) => {
+        dispatched.push(merged);
+      },
+    });
+
+    coalescer.enqueue(turn({ messageId: "msg-1", rawBody: "one" }));
+    await vi.advanceTimersByTimeAsync(9000);
+    coalescer.enqueue(turn({ messageId: "msg-2", rawBody: "two" }));
+    await vi.advanceTimersByTimeAsync(9000);
+    coalescer.enqueue(turn({ messageId: "msg-3", rawBody: "three" }));
+    await vi.advanceTimersByTimeAsync(9000);
+    coalescer.enqueue(turn({ messageId: "msg-4", rawBody: "four" }));
+
+    await vi.advanceTimersByTimeAsync(2999);
+    expect(dispatched).toEqual([]);
+
+    await vi.advanceTimersByTimeAsync(1);
+    expect(dispatched).toHaveLength(1);
+    expect(dispatched[0]?.messageId).toBe("msg-4");
+    expect(dispatched[0]?.rawBody).toContain("ClawChat group batch (4 messages, 10s idle, 30s max)");
+    expect(dispatched[0]?.rawBody).toContain("[message]\nsender_id: user-a\nsender_name: Alice\nsender_profile_type: user\nsender_is_agent_owner: false\nsender_is_group_owner: false\nmentions_current_agent: false\nmentioned_users: -\ntext:\nfour");
+    expect(dispatched[0]?.rawBody).not.toContain("[msg-");
+  });
+
+  it("flushes one merged turn per group after the idle window", async () => {
+    const dispatched: CoalescableGroupTurn[] = [];
+    const coalescer = createGroupMessageCoalescer({
+      idleMs: 10000,
+      maxWaitMs: 30000,
+      dispatch: async (merged) => {
+        dispatched.push(merged);
+      },
+    });
+
+    const latestEnvelope = { event: "message.send", trace_id: "trace-2", emitted_at: 2000 };
+
+    coalescer.enqueue(
+      turn({
+        messageId: "msg-1",
+        senderNickName: "Alice",
+        rawBody: "one",
+        mentionedUserIds: ["other-user"],
+      }),
+    );
+    coalescer.enqueue(
+      turn({
+        messageId: "msg-2",
+        senderId: "user-b",
+        senderNickName: "Bob",
+        rawBody: "two",
+        traceId: "trace-2",
+        timestamp: 2000,
+        envelope: latestEnvelope,
+      }),
+    );
+
+    await vi.advanceTimersByTimeAsync(9999);
+    expect(dispatched).toEqual([]);
+
+    await vi.advanceTimersByTimeAsync(1);
+    expect(dispatched).toHaveLength(1);
+    expect(dispatched[0]?.messageId).toBe("msg-2");
+    expect(dispatched[0]?.senderId).toBe("user-b");
+    expect(dispatched[0]?.traceId).toBe("trace-2");
+    expect(dispatched[0]?.timestamp).toBe(2000);
+    expect(dispatched[0]?.envelope).toBe(latestEnvelope);
+    expect(dispatched[0]?.mentionedUserIds).toEqual(["other-user"]);
+    expect(dispatched[0]?.rawBody).toContain("ClawChat group batch (2 messages, 10s idle, 30s max)");
+    expect(dispatched[0]?.rawBody).toContain("[message]\nsender_id: user-a\nsender_name: Alice\nsender_profile_type: user\nsender_is_agent_owner: false\nsender_is_group_owner: false\nmentions_current_agent: false\nmentioned_users: other-user\ntext:\none");
+    expect(dispatched[0]?.rawBody).toContain("[message]\nsender_id: user-b\nsender_name: Bob\nsender_profile_type: user\nsender_is_agent_owner: false\nsender_is_group_owner: false\nmentions_current_agent: false\nmentioned_users: -\ntext:\ntwo");
+    expect(dispatched[0]?.rawBody).not.toContain("[msg-");
+  });
+
+  it("keeps independent timers per group", async () => {
+    const dispatched: CoalescableGroupTurn[] = [];
+    const coalescer = createGroupMessageCoalescer({
+      idleMs: 10000,
+      maxWaitMs: 30000,
+      dispatch: async (merged) => dispatched.push(merged),
+    });
+
+    coalescer.enqueue(turn({ peer: { kind: "group", id: "room-1" }, messageId: "r1-a" }));
+    await vi.advanceTimersByTimeAsync(1000);
+
+    coalescer.enqueue(turn({ peer: { kind: "group", id: "room-2" }, messageId: "r2-a" }));
+
+    await vi.advanceTimersByTimeAsync(8999);
+    expect(dispatched).toEqual([]);
+
+    await vi.advanceTimersByTimeAsync(1);
+    expect(dispatched.map((item) => item.peer.id)).toEqual(["room-1"]);
+
+    await vi.advanceTimersByTimeAsync(999);
+    expect(dispatched.map((item) => item.peer.id)).toEqual(["room-1"]);
+
+    await vi.advanceTimersByTimeAsync(8001);
+    expect(dispatched.map((item) => item.peer.id)).toEqual(["room-1", "room-2"]);
+  });
+
+  it("drops pending batches on cancel without dispatching after shutdown", async () => {
+    const dispatched: CoalescableGroupTurn[] = [];
+    const coalescer = createGroupMessageCoalescer({
+      idleMs: 10000,
+      maxWaitMs: 30000,
+      dispatch: async (merged) => dispatched.push(merged),
+    });
+
+    coalescer.enqueue(turn());
+    coalescer.cancelAll();
+    await vi.advanceTimersByTimeAsync(30000);
+
+    expect(dispatched).toEqual([]);
+  });
+});
+
+describe("formatCoalescedGroupBody", () => {
+  it("keeps sender name and sender identity visible without message ids", () => {
+    expect(
+      formatCoalescedGroupBody([
+        turn({ messageId: "msg-1", senderId: "u1", senderNickName: "Ann", rawBody: "first" }),
+        turn({
+          messageId: "msg-2",
+          senderId: "u2",
+          senderNickName: "Ben",
+          senderIsOwner: true,
+          senderProfileType: "user",
+          rawBody: "second",
+        }),
+      ]),
+    ).toBe(
+      [
+        "ClawChat group batch (2 messages, 10s idle, 30s max):",
+        "[message]",
+        "sender_id: u1",
+        "sender_name: Ann",
+        "sender_profile_type: user",
+        "sender_is_agent_owner: false",
+        "sender_is_group_owner: false",
+        "mentions_current_agent: false",
+        "mentioned_users: -",
+        "text:",
+        "first",
+        "",
+        "[message]",
+        "sender_id: u2",
+        "sender_name: Ben",
+        "sender_profile_type: user",
+        "sender_is_agent_owner: true",
+        "sender_is_group_owner: false",
+        "mentions_current_agent: false",
+        "mentioned_users: -",
+        "text:",
+        "second",
+      ].join("\n"),
+    );
+  });
+
+  it("formats mentioned users with display labels", () => {
+    expect(
+      formatCoalescedGroupBody([
+        turn({
+          rawBody: "请 @Bob 下午处理",
+          mentionedUserIds: ["usr_bob_456"],
+          mentionedUsers: [{ id: "usr_bob_456", display: "Bob" }],
+        }),
+      ]),
+    ).toContain("mentioned_users: usr_bob_456(Bob)");
+  });
+});