@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/group-message-coalescer.ts

@@ -0,0 +1,171 @@
+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;
+  senderIsGroupOwner?: boolean;
+  rawBody: string;
+  messageId: string;
+  traceId: string;
+  timestamp: number;
+  wasMentioned: boolean;
+  mentionedUserIds: string[];
+  mentionedUsers?: { id: string; display?: 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 formatMentionedUsers(turn: CoalescableGroupTurn): string {
+  const mentionedUsers: { id: string; display?: string }[] = turn.mentionedUsers && turn.mentionedUsers.length > 0
+    ? turn.mentionedUsers
+    : turn.mentionedUserIds.map((id) => ({ id }));
+  if (mentionedUsers.length === 0) return "-";
+  return mentionedUsers.map((mention) => {
+    const id = formatField(mention.id);
+    const display = mention.display?.trim();
+    return display ? `${id}(${formatField(display)})` : id;
+  }).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 senderIsAgentOwner = turn.senderIsOwner ?? formatSenderRelation(turn) === "owner";
+      return [
+        "[message]",
+        `sender_id: ${formatField(turn.senderId)}`,
+        `sender_name: ${formatField(senderName)}`,
+        `sender_profile_type: ${formatField(formatSenderProfileType(turn))}`,
+        `sender_is_agent_owner: ${senderIsAgentOwner ? "true" : "false"}`,
+        `sender_is_group_owner: ${turn.senderIsGroupOwner ? "true" : "false"}`,
+        `mentions_current_agent: ${turn.wasMentioned ? "true" : "false"}`,
+        `mentioned_users: ${formatMentionedUsers(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))),
+    mentionedUsers: Array.from(
+      new Map(
+        turns.flatMap((turn) => turn.mentionedUsers ?? turn.mentionedUserIds.map((id) => ({ id })))
+          .map((mention) => [mention.id, mention]),
+      ).values(),
+    ),
+    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

@@ -0,0 +1,508 @@
+import type { Envelope, MessagePayload } from "./protocol-types.ts";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
+import { describe, expect, it, vi } from "vitest";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+import { dispatchOpenclawClawlingInbound } from "./inbound.ts";
+
+function baseAccount(
+  overrides: Partial<ResolvedOpenclawClawlingAccount> = {},
+): ResolvedOpenclawClawlingAccount {
+  return {
+    accountId: DEFAULT_ACCOUNT_ID,
+    name: "clawchat-plugin-openclaw",
+    enabled: true,
+    configured: true,
+    websocketUrl: "ws://t",
+    baseUrl: "",
+    token: "tk",
+    agentId: "",
+    userId: "agent-1",
+    ownerUserId: "owner-1",
+    groupMode: "all",
+    groupCommandMode: "owner",
+    groups: {},
+    richInteractions: false,
+    forwardThinking: true,
+    forwardToolCalls: false,
+    allowFrom: [],
+    reconnect: {
+      initialDelay: 1000,
+      maxDelay: 30000,
+      jitterRatio: 0.3,
+      maxRetries: Number.POSITIVE_INFINITY,
+    },
+    heartbeat: { interval: 25000, timeout: 10000 },
+    ack: { timeout: 10000, autoResendOnTimeout: false },
+    ...overrides,
+  };
+}
+
+function buildSendEnvelope(
+  overrides: Partial<{
+    event: "message.send" | "message.reply";
+    text: string;
+    fragments: Array<Record<string, unknown>>;
+    chatType: "direct" | "group";
+    mentions: unknown[];
+    reply: unknown;
+    messageId: string;
+    chatId: string;
+    omitChatId: boolean;
+    senderId: string;
+  }> = {},
+): Envelope<MessagePayload> {
+  const chatId = overrides.chatId ?? "chat-1";
+  const chatType = overrides.chatType ?? "direct";
+  return {
+    version: "2",
+    event: overrides.event ?? "message.send",
+    trace_id: "trace-1",
+    emitted_at: 1776162600000,
+    ...(overrides.omitChatId ? {} : { chat_id: chatId }),
+    chat_type: chatType,
+    to: { id: chatId, type: chatType },
+    sender: {
+      id: overrides.senderId ?? "user-1",
+      type: "direct",
+      nick_name: "User One",
+    },
+    payload: {
+      message_id: overrides.messageId ?? "msg-1",
+      message_mode: "normal",
+      message: {
+        body: {
+          fragments: overrides.fragments ?? [{ kind: "text", text: overrides.text ?? "hello from user" }],
+        },
+        context: {
+          mentions: overrides.mentions ?? [],
+          reply: (overrides.reply ?? null) as never,
+        },
+        streaming: {
+          status: "static",
+          sequence: 0,
+          mutation_policy: "sealed",
+          started_at: null,
+          completed_at: null,
+        },
+      } as MessagePayload["message"],
+    },
+  } as Envelope<MessagePayload>;
+}
+
+function buildStreamEnvelope(
+  overrides: Partial<{
+    event: "message.created" | "message.add" | "message.done" | "message.failed";
+    fragments: Array<Record<string, unknown>>;
+    messageId: string;
+    sequence: number;
+    chatId: string;
+    chatType: "direct" | "group";
+  }> = {},
+): Envelope<unknown> {
+  const event = overrides.event ?? "message.done";
+  const sequence = overrides.sequence ?? 0;
+  const payload: Record<string, unknown> = {
+    message_id: overrides.messageId ?? "stream-1",
+  };
+  if (event === "message.add") {
+    payload.sequence = sequence;
+    payload.mutation = { type: "append", target_fragment_index: null };
+    payload.fragments = overrides.fragments ?? [{ kind: "text", text: "Hel", delta: "Hel" }];
+    payload.streaming = {
+      status: "streaming",
+      sequence,
+      mutation_policy: "append_text_only",
+      started_at: null,
+      completed_at: null,
+    };
+    payload.added_at = 1776162600001;
+  }
+  if (event === "message.done" || event === "message.failed") {
+    payload.fragments = overrides.fragments ?? [{ kind: "text", text: "Hello" }];
+    payload.streaming = {
+      status: event === "message.done" ? "done" : "failed",
+      sequence,
+      mutation_policy: "append_text_only",
+      started_at: null,
+      completed_at: 1776162600002,
+    };
+    payload.completed_at = 1776162600002;
+  }
+  return {
+    version: "2",
+    event,
+    trace_id: `trace-${event}`,
+    emitted_at: 1776162600000,
+    chat_id: overrides.chatId ?? "chat-1",
+    chat_type: overrides.chatType ?? "direct",
+    sender: { id: "user-1", type: "direct", nick_name: "User One" },
+    payload,
+  } as Envelope<unknown>;
+}
+
+describe("clawchat-plugin-openclaw inbound", () => {
+  it("dispatches a plain text message and flattens the body", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({ text: "hello there" }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount({ groupMode: "mention" }),
+      ingest,
+    });
+    expect(ingest).toHaveBeenCalledTimes(1);
+    const call = ingest.mock.calls[0]![0];
+    expect(call.channel).toBe("clawchat-plugin-openclaw");
+    expect(call.rawBody).toBe("hello there");
+    expect(call.peer).toEqual({ kind: "direct", id: "chat-1" });
+    expect(call.messageId).toBe("msg-1");
+  });
+
+  it("skips self-echo messages from the connected agent user", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    const log = { info: vi.fn(), error: vi.fn() };
+
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({ senderId: "agent-1", text: "my own echo" }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount({ userId: "agent-1" }),
+      ingest,
+      log,
+    });
+
+    expect(ingest).not.toHaveBeenCalled();
+    expect(log.info).toHaveBeenCalledWith(expect.stringContaining("self-echo"));
+  });
+
+  it("dispatches materialized message.send and message.reply inbound", async () => {
+    for (const event of ["message.send", "message.reply"] as const) {
+      const ingest = vi.fn().mockResolvedValue(undefined);
+      await dispatchOpenclawClawlingInbound({
+        envelope: buildSendEnvelope({ event, messageId: `msg-${event}` }),
+        cfg: {},
+        runtime: {} as never,
+        account: baseAccount(),
+        ingest,
+      });
+      expect(ingest).toHaveBeenCalledTimes(1);
+    }
+  });
+
+  it("does not dispatch stream lifecycle frames", async () => {
+    for (const event of ["message.created", "message.add", "message.done", "message.failed"] as const) {
+      const ingest = vi.fn().mockResolvedValue(undefined);
+      await dispatchOpenclawClawlingInbound({
+        envelope: buildStreamEnvelope({ event, messageId: `msg-${event}` }) as Envelope<MessagePayload>,
+        cfg: {},
+        runtime: {} as never,
+        account: baseAccount(),
+        ingest,
+      });
+      expect(ingest).not.toHaveBeenCalled();
+    }
+  });
+
+  it("marks wasMentioned=true when direct chat", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({ chatType: "direct" }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount({ groupMode: "mention" }),
+      ingest,
+    });
+    const { wasMentioned } = ingest.mock.calls[0]![0];
+    expect(wasMentioned).toBe(true);
+  });
+
+  it("detectMention returns true when context.mentions contains userId (forward-compat for group chat)", async () => {
+    const { detectMention } = await import("./inbound.ts");
+    expect(
+      detectMention({
+        mentions: ["agent-1"],
+        chatType: "group",
+        userId: "agent-1",
+      }),
+    ).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("preserves mention display labels and ordered mention text", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({
+        chatType: "group",
+        fragments: [
+          { kind: "text", text: "请 " },
+          { kind: "mention", user_id: "usr_bob_456", display: "Bob" },
+          { kind: "text", text: " 和 " },
+          { kind: "mention", user_id: "usr_xiaopang_789", display: "小胖" },
+          { kind: "text", text: " 下午处理" },
+        ],
+        mentions: [
+          { user_id: "usr_bob_456", display: "Bob" },
+          { user_id: "usr_xiaopang_789", display: "小胖" },
+        ],
+      }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount({ groupMode: "all" }),
+      ingest,
+    });
+
+    expect(ingest).toHaveBeenCalledTimes(1);
+    expect(ingest.mock.calls[0]![0].rawBody).toBe("请 @Bob 和 @小胖 下午处理");
+    expect(ingest.mock.calls[0]![0].mentionedUsers).toEqual([
+      { id: "usr_bob_456", display: "Bob" },
+      { id: "usr_xiaopang_789", display: "小胖" },
+    ]);
+  });
+
+  it("detectMention returns false for group chat when userId not mentioned", async () => {
+    const { detectMention } = await import("./inbound.ts");
+    expect(
+      detectMention({
+        mentions: ["user-2"],
+        chatType: "group",
+        userId: "agent-1",
+      }),
+    ).toBe(false);
+  });
+
+  it("skips unmentioned group messages in mention mode", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({ chatType: "group" }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount({ groupMode: "mention" }),
+      ingest,
+    });
+    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({
+      envelope: buildSendEnvelope({ text: "   " }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount(),
+      ingest,
+    });
+    expect(ingest).not.toHaveBeenCalled();
+  });
+
+  it("extracts replyCtx from message.reply envelopes", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    const replyRef = {
+      reply_to_msg_id: "m-orig",
+      reply_preview: {
+        id: "user-2",
+        nick_name: "User Two",
+        fragments: [{ kind: "text", text: "original text" }],
+      },
+    };
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({ event: "message.reply", reply: replyRef, chatId: "chat-1" }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount(),
+      ingest,
+    });
+    const { replyCtx } = ingest.mock.calls[0]![0];
+    expect(replyCtx).toEqual({
+      replyToMessageId: "m-orig",
+      replyPreviewChatId: "chat-1",
+      replyPreviewSenderId: "user-2",
+      replyPreviewNickName: "User Two",
+      replyPreviewText: "original text",
+    });
+  });
+
+  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({
+      envelope: env,
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount(),
+      ingest,
+    });
+    await dispatchOpenclawClawlingInbound({
+      envelope: env,
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount(),
+      ingest,
+    });
+    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; 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" },
+    ];
+    await dispatchOpenclawClawlingInbound({
+      envelope: env,
+      cfg: {} as never,
+      runtime: {} as never,
+      account: baseAccount(),
+      ingest,
+    });
+    const call = ingest.mock.calls[0]![0];
+    expect(call.mediaItems).toEqual([
+      { kind: "image", url: "https://cdn/x.png", mime: "image/png" },
+    ]);
+  });
+
+  it("dispatches image-only messages", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    const env = buildSendEnvelope({ text: "   " });
+    env.payload.message.body.fragments = [{ kind: "image", url: "https://cdn/x.png" }];
+    await dispatchOpenclawClawlingInbound({
+      envelope: env,
+      cfg: {} as never,
+      runtime: {} as never,
+      account: baseAccount(),
+      ingest,
+    });
+    expect(ingest).toHaveBeenCalledTimes(1);
+    const call = ingest.mock.calls[0]![0];
+    expect(call.rawBody).toBe("![image](https://cdn/x.png)");
+    expect(call.mediaItems).toEqual([{ kind: "image", url: "https://cdn/x.png" }]);
+  });
+
+  it("dispatches with canonical envelope.sender shape", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    const env = buildSendEnvelope({ text: "hello" });
+    await dispatchOpenclawClawlingInbound({
+      envelope: env,
+      cfg: {} as never,
+      runtime: {} as never,
+      account: baseAccount(),
+      ingest,
+    });
+    expect(ingest).toHaveBeenCalledTimes(1);
+    const call = ingest.mock.calls[0]![0];
+    expect(call.senderId).toBe("user-1");
+    expect(call.senderNickName).toBe("User One");
+    expect(call.peer).toEqual({ kind: "direct", id: "chat-1" });
+  });
+
+  it("skips business events without required chat_id", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({ omitChatId: true }),
+      cfg: {} as never,
+      runtime: {} as never,
+      account: baseAccount(),
+      ingest,
+    });
+    expect(ingest).not.toHaveBeenCalled();
+  });
+
+  it("ingest receives mediaItems = [] when body has only text", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({ text: "hi" }),
+      cfg: {} as never,
+      runtime: {} as never,
+      account: baseAccount(),
+      ingest,
+    });
+    const call = ingest.mock.calls[0]![0];
+    expect(call.mediaItems).toEqual([]);
+  });
+});