@newbase-clawchat/openclaw-clawchat 2026.4.15

package/src/inbound.test.ts

@@ -0,0 +1,264 @@
+import type { Envelope, DownlinkMessageSendPayload } from "@newbase-clawchat/sdk";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+import { dispatchOpenclawClawlingInbound, _resetDedupForTest } from "./inbound.ts";
+
+function baseAccount(
+  overrides: Partial<ResolvedOpenclawClawlingAccount> = {},
+): ResolvedOpenclawClawlingAccount {
+  return {
+    accountId: DEFAULT_ACCOUNT_ID,
+    name: "openclaw-clawchat",
+    enabled: true,
+    configured: true,
+    websocketUrl: "ws://t",
+    baseUrl: "",
+    token: "tk",
+    userId: "agent-1",
+    replyMode: "static",
+    forwardThinking: true,
+    forwardToolCalls: false,
+    allowFrom: [],
+    stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+    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;
+    senderType: "direct" | "group";
+    mentions: string[];
+    reply: unknown;
+    messageId: string;
+  }> = {},
+): Envelope<DownlinkMessageSendPayload> {
+  return {
+    version: "2",
+    event: overrides.event ?? "message.send",
+    trace_id: "trace-1",
+    emitted_at: 1776162600000,
+    to: { id: "agent-1", type: overrides.senderType ?? "direct" },
+    sender: {
+      sender_id: "user-1",
+      type: overrides.senderType ?? "direct",
+      display_name: "User One",
+    },
+    payload: {
+      message_id: overrides.messageId ?? "msg-1",
+      message_mode: "normal",
+      message: {
+        body: {
+          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,
+        },
+        sender: {
+          sender_id: "user-1",
+          type: overrides.senderType ?? "direct",
+          display_name: "User One",
+        },
+      } as DownlinkMessageSendPayload["message"],
+    },
+  } as Envelope<DownlinkMessageSendPayload>;
+}
+
+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({
+      envelope: buildSendEnvelope({ text: "hello there" }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount(),
+      ingest,
+    });
+    expect(ingest).toHaveBeenCalledTimes(1);
+    const call = ingest.mock.calls[0]![0];
+    expect(call.channel).toBe("openclaw-clawchat");
+    expect(call.rawBody).toBe("hello there");
+    expect(call.peer).toEqual({ kind: "direct", id: "user-1" });
+    expect(call.messageId).toBe("msg-1");
+  });
+
+  it("marks wasMentioned=true when direct chat", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({ senderType: "direct" }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount(),
+      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"],
+        senderType: "group",
+        userId: "agent-1",
+      }),
+    ).toBe(true);
+  });
+
+  it("detectMention returns false for group chat when userId not mentioned", async () => {
+    const { detectMention } = await import("./inbound.ts");
+    expect(
+      detectMention({
+        mentions: ["user-2"],
+        senderType: "group",
+        userId: "agent-1",
+      }),
+    ).toBe(false);
+  });
+
+  it("skips group messages entirely", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({ senderType: "group" }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount(),
+      ingest,
+    });
+    expect(ingest).not.toHaveBeenCalled();
+  });
+
+  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: {
+        sender_id: "user-2",
+        display_name: "User Two",
+        fragments: [{ kind: "text", text: "original text" }],
+      },
+    };
+    await dispatchOpenclawClawlingInbound({
+      envelope: buildSendEnvelope({ event: "message.reply", reply: replyRef }),
+      cfg: {},
+      runtime: {} as never,
+      account: baseAccount(),
+      ingest,
+    });
+    const { replyCtx } = ingest.mock.calls[0]![0];
+    expect(replyCtx).toEqual({
+      replyToMessageId: "m-orig",
+      replyPreviewSenderId: "user-2",
+      replyPreviewDisplayName: "User Two",
+      replyPreviewText: "original text",
+    });
+  });
+
+  it("deduplicates repeat message_ids", 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(1);
+  });
+
+  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)
+    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 when sender is only on envelope.sender (real wire, no message.sender)", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    const env = buildSendEnvelope({ text: "hello" });
+    // Real chat-sdk envelopes carry sender on the envelope, not inside the message.
+    delete (env.payload.message as unknown as { sender?: unknown }).sender;
+    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.senderDisplayName).toBe("User One");
+    expect(call.peer).toEqual({ kind: "direct", id: "user-1" });
+  });
+
+  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([]);
+  });
+});

package/src/inbound.ts

@@ -0,0 +1,201 @@
+import {
+  EVENT,
+  type ChatType,
+  type DownlinkMessageSendPayload,
+  type Envelope,
+} from "@newbase-clawchat/sdk";
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/core";
+import 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";
+
+export interface IngestTurnParams {
+  channel: "openclaw-clawchat";
+  accountId: string;
+  /**
+   * The conversational subject. `peer.id` mirrors the inbound envelope's
+   * `chat_id` (new-protocol routing key); `peer.kind` is `chat_type`
+   * (direct / group).
+   */
+  peer: { kind: "direct" | "group"; id: string };
+  senderId: string;
+  senderNickName: string;
+  rawBody: string;
+  messageId: string;
+  traceId: string;
+  timestamp: number;
+  wasMentioned: boolean;
+  mediaItems: MediaItem[];
+  replyCtx?: {
+    replyToMessageId: string;
+    replyPreviewSenderId: string;
+    replyPreviewNickName: string;
+    replyPreviewText: string;
+  };
+  cfg: OpenClawConfig;
+  runtime: PluginRuntime;
+  account: ResolvedOpenclawClawlingAccount;
+  envelope: Envelope<DownlinkMessageSendPayload>;
+}
+
+export interface DispatchInboundParams {
+  envelope: Envelope<DownlinkMessageSendPayload>;
+  cfg: OpenClawConfig;
+  runtime: PluginRuntime;
+  account: ResolvedOpenclawClawlingAccount;
+  ingest: (params: IngestTurnParams) => Promise<void>;
+  log?: { info?: (m: string) => void; error?: (m: string) => void };
+}
+
+const DEDUP_MAX = 256;
+const dedupSeen: string[] = [];
+const dedupSet = new Set<string>();
+
+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;
+}
+
+/**
+ * Exported for direct unit testing. Group-sender messages currently never
+ * reach this function (filtered in dispatchOpenclawClawlingInbound), but the
+ * `mentions` branch is exercised by tests now so the group-enable change is
+ * a one-line filter removal later.
+ */
+export function detectMention(params: {
+  mentions: string[];
+  senderType: "direct" | "group";
+  userId: string;
+}): boolean {
+  if (params.senderType === "direct") return true;
+  return params.mentions.includes(params.userId);
+}
+
+export async function dispatchOpenclawClawlingInbound(
+  params: DispatchInboundParams,
+): Promise<void> {
+  const { envelope, account, log } = params;
+  if (!isInboundMessagePayload(envelope.payload)) {
+    log?.info?.(
+      `[${account.accountId}] openclaw-clawchat skip: invalid payload trace=${envelope.trace_id}`,
+    );
+    return;
+  }
+  const payload = envelope.payload;
+  const message = payload.message as unknown as {
+    body: { fragments: Array<Record<string, unknown>> };
+    context: {
+      mentions: string[];
+      reply: {
+        reply_to_msg_id: string;
+        reply_preview: {
+          id: string;
+          nick_name: string;
+          fragments: Array<Record<string, unknown>>;
+        };
+      } | null;
+    };
+    /** Legacy fallback: older fixtures carried sender inside payload.message. */
+    sender?: { id: string; nick_name: string };
+  };
+
+  // v2 envelopes carry sender on the envelope (RoutingSender); the legacy
+  // message.sender shape is accepted as a fallback for older fixtures.
+  const sender = envelope.sender ?? message.sender;
+  if (!sender || typeof sender.id !== "string" || !sender.id) {
+    log?.info?.(
+      `[${account.accountId}] openclaw-clawchat skip: missing sender trace=${envelope.trace_id}`,
+    );
+    return;
+  }
+  // `chat_type` is on the envelope in the new protocol. Default to "direct"
+  // if the server didn't include it (defensive; shouldn't happen in practice).
+  const chatType: ChatType = envelope.chat_type ?? "direct";
+  const isGroup = chatType === "group";
+  if (payload.message_mode !== "normal") {
+    log?.info?.(
+      `[${account.accountId}] openclaw-clawchat skip non-normal mode=${payload.message_mode}`,
+    );
+    return;
+  }
+  if (!hasRenderableText(message)) {
+    log?.info?.(`[${account.accountId}] openclaw-clawchat skip empty msg=${payload.message_id}`);
+    return;
+  }
+  if (rememberAndCheck(payload.message_id)) {
+    log?.info?.(
+      `[${account.accountId}] openclaw-clawchat skip duplicate msg=${payload.message_id}`,
+    );
+    return;
+  }
+
+  const rawBody = fragmentsToText(message.body.fragments as never, {
+    mentionFallbackIds: message.context.mentions,
+  });
+  const mediaItems = extractMediaFragments(message.body.fragments as never);
+  const wasMentioned = detectMention({
+    mentions: message.context.mentions,
+    senderType: chatType,
+    userId: account.userId,
+  });
+
+  // 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) {
+    log?.info?.(
+      `[${account.accountId}] openclaw-clawchat skip group (no mention) msg=${payload.message_id}`,
+    );
+    return;
+  }
+
+  const replyCtx = message.context.reply
+    ? {
+        replyToMessageId: message.context.reply.reply_to_msg_id,
+        replyPreviewSenderId: message.context.reply.reply_preview.id,
+        replyPreviewNickName: message.context.reply.reply_preview.nick_name,
+        replyPreviewText: fragmentsToText(message.context.reply.reply_preview.fragments as never),
+      }
+    : undefined;
+
+  log?.info?.(
+    `[${account.accountId}] openclaw-clawchat inbound event=${envelope.event === EVENT.MESSAGE_REPLY ? "reply" : "send"} msg=${payload.message_id} from=${sender.id} text_len=${rawBody.length} mentioned=${wasMentioned}`,
+  );
+
+  // New protocol: `chat_id` is the routing primary; `to` is deprecated.
+  // Fall back to sender.id if neither is present (defensive).
+  const chatId =
+    (envelope as Envelope<DownlinkMessageSendPayload> & { chat_id?: string }).chat_id ??
+    sender.id;
+
+  await params.ingest({
+    channel: "openclaw-clawchat",
+    accountId: account.accountId,
+    peer: { kind: isGroup ? "group" : "direct", id: chatId },
+    senderId: sender.id,
+    senderNickName: sender.nick_name,
+    rawBody,
+    messageId: payload.message_id,
+    traceId: envelope.trace_id,
+    timestamp: envelope.emitted_at,
+    wasMentioned,
+    mediaItems,
+    ...(replyCtx ? { replyCtx } : {}),
+    cfg: params.cfg,
+    runtime: params.runtime,
+    account,
+    envelope,
+  });
+}