@newbase-clawchat/openclaw-clawchat 2026.5.4 → 2026.5.12-13

package/src/reply-dispatcher.test.ts

@@ -1,9 +1,617 @@
-import type { ClawlingChatClient } from "@newbase-clawchat/sdk";
+import type { ClawlingChatClient } from "./ws-client.ts";
+import { EventEmitter } from "node:events";
 import { describe, expect, it, vi } from "vitest";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.ts";
+import {
+  flushAlignedOutboundQueue,
+  getAlignedOutboundQueueSize,
+} from "./outbound.ts";
+
+type SentFrame = {
+  event: string;
+  payload: Record<string, unknown>;
+  chat_id?: string;
+  trace_id?: string;
+};
+
+type TestClient = ClawlingChatClient & {
+  sent: SentFrame[];
+  typing: ReturnType<typeof vi.fn>;
+};
+
+function mockClient(
+  sent: SentFrame[] = [],
+  options: { transportState?: "open" | "closed"; state?: string; autoAck?: boolean } = {},
+): TestClient & { setTransportState: (state: "open" | "closed") => void; setState: (state: string) => void } {
+  let trace = 0;
+  let transportState = options.transportState ?? "open";
+  let clientState = options.state ?? "connected";
+  const autoAck = options.autoAck ?? true;
+  const client = Object.assign(new EventEmitter(), {
+    sent,
+    nextTraceId: vi.fn(() => `trace-${++trace}`),
+    sendWire: vi.fn((wire: string) => {
+      const env = JSON.parse(wire) as SentFrame & { trace_id?: string };
+      sent.push({ event: env.event, payload: env.payload, chat_id: env.chat_id, trace_id: env.trace_id });
+      if (autoAck && (env.event === "message.send" || env.event === "message.reply")) {
+        const payload = env.payload as { message_id?: string };
+        queueMicrotask(() => {
+          client.emit("raw", {
+            version: "2",
+            event: "message.ack",
+            trace_id: env.trace_id,
+            emitted_at: Date.now(),
+            payload: { message_id: payload.message_id ?? "server-m1", accepted_at: 1234 },
+          });
+        });
+      }
+    }),
+    emitRaw: vi.fn((event: string, payload: Record<string, unknown>, routing?: { chat_id?: string }) => {
+      sent.push({ event, payload, chat_id: routing?.chat_id });
+    }),
+    sendRawEnvelope: vi.fn((env: { event: string; payload: Record<string, unknown>; chat_id?: string; trace_id?: string }) => {
+      sent.push({ event: env.event, payload: env.payload, chat_id: env.chat_id, trace_id: env.trace_id });
+    }),
+    typing: vi.fn(),
+    setTransportState: (state: "open" | "closed") => {
+      transportState = state;
+    },
+    setState: (state: string) => {
+      clientState = state;
+    },
+  });
+  Object.defineProperty(client, "state", { get: () => clientState });
+  Object.defineProperty(client, "transportState", { get: () => transportState });
+  return client as unknown as TestClient & {
+    setTransportState: (state: "open" | "closed") => void;
+    setState: (state: string) => void;
+  };
+}
+
+function runtimeWithHooks(setHooks: (hooks: Record<string, unknown>) => void) {
+  return {
+    channel: {
+      reply: {
+        resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+        createReplyDispatcherWithTyping: vi.fn((options) => {
+          setHooks(options as Record<string, unknown>);
+          return { dispatcher: {}, replyOptions: {}, markDispatchIdle: vi.fn() };
+        }),
+      },
+    },
+  } as never;
+}
+
+function replyAccount(overrides: Record<string, unknown> = {}) {
+  return {
+    accountId: "default",
+    userId: "agent-1",
+    replyMode: "static",
+    forwardThinking: true,
+    forwardToolCalls: false,
+    richInteractions: false,
+    stream: { flushIntervalMs: 250, minChunkChars: 1, maxBufferChars: 2000 },
+    ack: { timeout: 10000, autoResendOnTimeout: false },
+    ...overrides,
+  } as never;
+}
+
+type TestStore = {
+  claimMessageOnce?: (input: unknown) => true | false | null;
+  updateMessageByIdentity?: (input: unknown) => void;
+  insertMessage?: (input: unknown) => unknown;
+};
+
+async function runStaticReplyWithStore(store: TestStore) {
+  let hooks: Record<string, unknown> = {};
+  const sent: SentFrame[] = [];
+  const client = mockClient(sent);
+
+  createOpenclawClawlingReplyDispatcher({
+    cfg: {} as never,
+    runtime: runtimeWithHooks((next) => {
+      hooks = next;
+    }),
+    account: replyAccount(),
+    client,
+    target: { chatId: "chat-1", chatType: "direct" },
+    store: store as never,
+    log: { info: vi.fn(), error: vi.fn() },
+  });
+
+  await (hooks.deliver as (payload: { text?: string }, info: { kind: string }) => Promise<void>)(
+    { text: "static reply" },
+    { kind: "final" },
+  );
+
+  return {
+    queuedFinal: sent.some((entry) => entry.event === "message.send" || entry.event === "message.reply"),
+    sent,
+  };
+}
+
+async function runStreamingReplyWithStore(store: TestStore, chunks: string[]) {
+  let hooks: Record<string, unknown> = {};
+  const sent: SentFrame[] = [];
+  const client = mockClient(sent);
+  const created = createOpenclawClawlingReplyDispatcher({
+    cfg: {} as never,
+    runtime: runtimeWithHooks((next) => {
+      hooks = next;
+    }),
+    account: replyAccount({ replyMode: "stream", forwardThinking: true }),
+    client,
+    target: { chatId: "chat-1", chatType: "direct" },
+    inboundMessageId: "inbound-1",
+    inboundForFinalReply: {
+      chatId: "chat-1",
+      senderId: "user-1",
+      senderNickName: "User 1",
+      bodyText: "hello",
+    },
+    store: store as never,
+    log: { info: vi.fn(), error: vi.fn() },
+  });
+
+  await (hooks.onReplyStart as (() => Promise<void>) | undefined)?.();
+  if (chunks[0]) {
+    await created.replyOptions.onPartialReply?.({ text: chunks[0] });
+  }
+  await (hooks.deliver as (payload: { text?: string }, info: { kind: string }) => Promise<void>)(
+    { text: chunks.at(-1) ?? "" },
+    { kind: "final" },
+  );
+  await (hooks.onIdle as () => Promise<void>)();
+
+  return {
+    sent,
+    streamingMessageId: sent.find((entry) => entry.event === "message.created")?.payload.message_id,
+  };
+}
 
 describe("openclaw-clawchat reply-dispatcher", () => {
-  it("uses chat_id, not sender_id, as the consolidated streaming reply marker", async () => {
+  it("claims static outbound before send and uses the claimed payload message_id", async () => {
+    const store = {
+      claimMessageOnce: vi.fn(() => true),
+      insertMessage: vi.fn(),
+    };
+
+    const result = await runStaticReplyWithStore(store);
+    const messageId = store.claimMessageOnce.mock.calls[0]![0].messageId;
+
+    expect(messageId).toEqual(expect.any(String));
+    expect(store.claimMessageOnce).toHaveBeenCalledWith(expect.objectContaining({
+      direction: "outbound",
+      kind: "message",
+      messageId,
+    }));
+    expect(result.sent[0]?.payload.message_id).toBe(messageId);
+    expect(store.insertMessage).not.toHaveBeenCalledWith(expect.objectContaining({ kind: "message" }));
+  });
+
+  it("does not send static outbound when the storage claim is duplicate or unavailable", async () => {
+    const duplicateStore = { claimMessageOnce: vi.fn(() => false), insertMessage: vi.fn() };
+    const unavailableStore = { claimMessageOnce: vi.fn(() => null), insertMessage: vi.fn() };
+
+    await expect(runStaticReplyWithStore(duplicateStore)).resolves.toMatchObject({ queuedFinal: false });
+    await expect(runStaticReplyWithStore(unavailableStore)).resolves.toMatchObject({ queuedFinal: false });
+    expect(duplicateStore.claimMessageOnce).toHaveBeenCalledWith(expect.objectContaining({
+      direction: "outbound",
+      kind: "message",
+    }));
+  });
+
+  it("claims static forwarded thinking before sending", async () => {
+    let hooks: Record<string, unknown> = {};
+    const store = { claimMessageOnce: vi.fn(() => true), insertMessage: vi.fn() };
+    const sent: SentFrame[] = [];
+    const client = mockClient(sent);
+
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: runtimeWithHooks((next) => {
+        hooks = next;
+      }),
+      account: replyAccount({ replyMode: "static", forwardThinking: true }),
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      store: store as never,
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    await (hooks.deliver as (payload: { text?: string; isReasoning?: boolean }) => Promise<void>)(
+      { text: "thinking text", isReasoning: true },
+    );
+    const messageId = store.claimMessageOnce.mock.calls[0]?.[0].messageId;
+
+    expect(store.claimMessageOnce).toHaveBeenCalledWith(expect.objectContaining({
+      kind: "message",
+      direction: "outbound",
+      eventType: "message.send",
+      messageId,
+      text: "thinking text",
+    }));
+    expect(sent[0]?.payload.message_id).toBe(messageId);
+    expect(store.insertMessage).toHaveBeenCalledWith(expect.objectContaining({
+      kind: "thinking",
+      messageId,
+      text: "thinking text",
+    }));
+  });
+
+  it("does not send static forwarded thinking when the storage claim is duplicate or unavailable", async () => {
+    for (const claimResult of [false, null] as const) {
+      let hooks: Record<string, unknown> = {};
+      const store = { claimMessageOnce: vi.fn(() => claimResult), insertMessage: vi.fn() };
+      const sent: SentFrame[] = [];
+      const client = mockClient(sent);
+
+      createOpenclawClawlingReplyDispatcher({
+        cfg: {} as never,
+        runtime: runtimeWithHooks((next) => {
+          hooks = next;
+        }),
+        account: replyAccount({ replyMode: "static", forwardThinking: true }),
+        client,
+        target: { chatId: "chat-1", chatType: "direct" },
+        store: store as never,
+        log: { info: vi.fn(), error: vi.fn() },
+      });
+
+      await (hooks.deliver as (payload: { text?: string; isReasoning?: boolean }) => Promise<void>)(
+        { text: "thinking text", isReasoning: true },
+      );
+
+      expect(store.claimMessageOnce).toHaveBeenCalledWith(expect.objectContaining({
+        kind: "message",
+        direction: "outbound",
+      }));
+      expect(sent).toHaveLength(0);
+      expect(store.insertMessage).not.toHaveBeenCalled();
+    }
+  });
+
+  it("claims a streaming outbound message once and updates the row on final reply", async () => {
+    const store = {
+      claimMessageOnce: vi.fn(() => true),
+      updateMessageByIdentity: vi.fn(),
+      insertMessage: vi.fn(),
+    };
+
+    const result = await runStreamingReplyWithStore(store, ["hello", "hello final"]);
+
+    expect(result.streamingMessageId).toEqual(expect.any(String));
+    expect(store.claimMessageOnce).toHaveBeenCalledTimes(1);
+    expect(store.claimMessageOnce).toHaveBeenCalledWith(expect.objectContaining({
+      direction: "outbound",
+      eventType: "message.created",
+      messageId: result.streamingMessageId,
+    }));
+    expect(store.updateMessageByIdentity).toHaveBeenCalledWith(expect.objectContaining({
+      direction: "outbound",
+      eventType: "message.reply",
+      messageId: result.streamingMessageId,
+      text: "hello final",
+    }));
+  });
+
+  it("queues the consolidated streaming final reply while disconnected and flushes it after reconnect", async () => {
+    let hooks: Record<string, unknown> = {};
+    const sent: SentFrame[] = [];
+    const client = mockClient(sent, { transportState: "closed", state: "reconnecting" });
+    const store = {
+      claimMessageOnce: vi.fn(() => true),
+      updateMessageByIdentity: vi.fn(),
+      insertMessage: vi.fn(),
+    };
+
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: runtimeWithHooks((next) => {
+        hooks = next;
+      }),
+      account: replyAccount({ replyMode: "stream", forwardThinking: true }),
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      inboundMessageId: "inbound-1",
+      inboundForFinalReply: {
+        chatId: "chat-1",
+        senderId: "user-1",
+        senderNickName: "User 1",
+        bodyText: "hello",
+      },
+      store: store as never,
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    await (hooks.deliver as (payload: { text?: string }, info: { kind: string }) => Promise<void>)(
+      { text: "final answer" },
+      { kind: "final" },
+    );
+    const streamingMessageId = sent.find((entry) => entry.event === "message.created")?.payload.message_id;
+    expect(streamingMessageId).toEqual(expect.any(String));
+
+    const idle = (hooks.onIdle as () => Promise<void>)();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(getAlignedOutboundQueueSize(client)).toBe(1);
+    expect(sent.filter((entry) => entry.event === "message.reply")).toHaveLength(0);
+
+    client.setTransportState("open");
+    client.setState("connected");
+    flushAlignedOutboundQueue(client);
+    await idle;
+
+    const finalReply = sent.find((entry) => entry.event === "message.reply");
+    expect(finalReply?.payload.message_id).toBe(streamingMessageId);
+    expect(finalReply?.payload).toMatchObject({
+      message: {
+        body: { fragments: [{ kind: "text", text: "final answer" }] },
+        context: {
+          reply: {
+            reply_to_msg_id: "inbound-1",
+            reply_preview: {
+              id: "user-1",
+              nick_name: "User 1",
+              fragments: [{ kind: "text", text: "hello" }],
+            },
+          },
+        },
+      },
+    });
+    expect(store.updateMessageByIdentity).toHaveBeenCalledWith(expect.objectContaining({
+      eventType: "message.reply",
+      messageId: streamingMessageId,
+      text: "final answer",
+    }));
+  });
+
+  it("requeues only the consolidated streaming final reply after disconnect before ack", async () => {
+    let hooks: Record<string, unknown> = {};
+    const sent: SentFrame[] = [];
+    const client = mockClient(sent, { autoAck: false });
+    const store = {
+      claimMessageOnce: vi.fn(() => true),
+      updateMessageByIdentity: vi.fn(),
+      insertMessage: vi.fn(),
+    };
+
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: runtimeWithHooks((next) => {
+        hooks = next;
+      }),
+      account: replyAccount({ replyMode: "stream", forwardThinking: true }),
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      inboundMessageId: "inbound-1",
+      inboundForFinalReply: {
+        chatId: "chat-1",
+        senderId: "user-1",
+        senderNickName: "User 1",
+        bodyText: "hello",
+      },
+      store,
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    await (hooks.deliver as (payload: { text?: string }, info: { kind: string }) => Promise<void>)(
+      { text: "final answer" },
+      { kind: "final" },
+    );
+
+    const idle = (hooks.onIdle as () => Promise<void>)();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    const streamingMessageId = sent.find((entry) => entry.event === "message.created")?.payload.message_id;
+    const firstFinalReply = sent.find((entry) => entry.event === "message.reply");
+    expect(streamingMessageId).toEqual(expect.any(String));
+    expect(firstFinalReply?.payload.message_id).toBe(streamingMessageId);
+    expect(firstFinalReply?.trace_id).toEqual(expect.any(String));
+
+    const lifecycleFramesBeforeReconnect = sent.filter((entry) =>
+      entry.event === "message.created" || entry.event === "message.add" || entry.event === "message.done"
+    );
+    const lifecycleCountsBeforeReconnect = {
+      created: lifecycleFramesBeforeReconnect.filter((entry) => entry.event === "message.created").length,
+      add: lifecycleFramesBeforeReconnect.filter((entry) => entry.event === "message.add").length,
+      done: lifecycleFramesBeforeReconnect.filter((entry) => entry.event === "message.done").length,
+    };
+    expect(lifecycleCountsBeforeReconnect.created).toBe(1);
+    expect(lifecycleCountsBeforeReconnect.add).toBeGreaterThanOrEqual(1);
+    expect(lifecycleCountsBeforeReconnect.done).toBe(1);
+    expect(lifecycleFramesBeforeReconnect.every((entry) => entry.payload.message_id === streamingMessageId)).toBe(true);
+
+    client.setTransportState("closed");
+    client.emit("close", { code: 1006, reason: "network lost" });
+    expect(getAlignedOutboundQueueSize(client)).toBe(1);
+
+    client.setTransportState("open");
+    client.setState("connected");
+    flushAlignedOutboundQueue(client);
+
+    expect({
+      created: sent.filter((entry) => entry.event === "message.created").length,
+      add: sent.filter((entry) => entry.event === "message.add").length,
+      done: sent.filter((entry) => entry.event === "message.done").length,
+    }).toEqual(lifecycleCountsBeforeReconnect);
+
+    const finalReplies = sent.filter((entry) => entry.event === "message.reply");
+    expect(finalReplies).toHaveLength(2);
+    expect(finalReplies[1]?.trace_id).toBe(firstFinalReply?.trace_id);
+    expect(finalReplies[1]?.payload.message_id).toBe(streamingMessageId);
+
+    client.emit("raw", {
+      version: "2",
+      event: "message.ack",
+      trace_id: firstFinalReply?.trace_id,
+      emitted_at: Date.now(),
+      payload: { message_id: streamingMessageId, accepted_at: 5678 },
+    });
+
+    await idle;
+    expect(store.updateMessageByIdentity).toHaveBeenCalledWith(expect.objectContaining({
+      eventType: "message.reply",
+      messageId: streamingMessageId,
+      text: "final answer",
+    }));
+  });
+
+  it("keeps thinking rows separate from outbound message claims", async () => {
+    let hooks: Record<string, unknown> = {};
+    const store = {
+      claimMessageOnce: vi.fn(() => true),
+      updateMessageByIdentity: vi.fn(),
+      insertMessage: vi.fn(),
+    };
+    const sent: SentFrame[] = [];
+    const client = mockClient(sent);
+    const created = createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: runtimeWithHooks((next) => {
+        hooks = next;
+      }),
+      account: replyAccount({ replyMode: "stream", forwardThinking: true }),
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      inboundMessageId: "inbound-1",
+      inboundForFinalReply: {
+        chatId: "chat-1",
+        senderId: "user-1",
+        senderNickName: "User 1",
+        bodyText: "hello",
+      },
+      store: store as never,
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    await created.replyOptions.onReasoningStream?.({ text: "thinking out loud" });
+    await (hooks.deliver as (payload: { text?: string }, info: { kind: string }) => Promise<void>)(
+      { text: "final answer" },
+      { kind: "final" },
+    );
+    await (hooks.onIdle as () => Promise<void>)();
+    const messageId = sent.find((entry) => entry.event === "message.created")?.payload.message_id;
+
+    expect(store.claimMessageOnce).toHaveBeenCalledTimes(1);
+    expect(store.insertMessage).toHaveBeenCalledTimes(1);
+    expect(store.insertMessage).toHaveBeenCalledWith(expect.objectContaining({
+      kind: "thinking",
+      messageId,
+      text: "thinking out loud",
+    }));
+  });
+
+  it("does not append a static message row after the pre-send claim", async () => {
+    let hooks: Record<string, unknown> = {};
+    const store = { claimMessageOnce: vi.fn(() => true), insertMessage: vi.fn() };
+    const client = mockClient();
+
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: runtimeWithHooks((next) => {
+        hooks = next;
+      }),
+      account: replyAccount(),
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      store,
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    await (hooks.deliver as (payload: { text?: string }, info: { kind: string }) => Promise<void>)(
+      { text: "static reply" },
+      { kind: "final" },
+    );
+
+    expect(store.claimMessageOnce).toHaveBeenCalledWith(expect.objectContaining({
+      kind: "message",
+      direction: "outbound",
+      eventType: "message.send",
+      text: "static reply",
+    }));
+    expect(store.insertMessage).not.toHaveBeenCalledWith(expect.objectContaining({ kind: "message" }));
+  });
+
+  it("persists streaming final outbound message and thinking with the same final message id", async () => {
+    let hooks: Record<string, unknown> = {};
+    const store = {
+      claimMessageOnce: vi.fn(() => true),
+      updateMessageByIdentity: vi.fn(),
+      insertMessage: vi.fn(),
+    };
+    const sent: SentFrame[] = [];
+    const client = mockClient(sent);
+
+    const created = createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: runtimeWithHooks((next) => {
+        hooks = next;
+      }),
+      account: replyAccount({ replyMode: "stream", forwardThinking: true }),
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      inboundMessageId: "inbound-1",
+      inboundForFinalReply: {
+        chatId: "chat-1",
+        senderId: "user-1",
+        senderNickName: "User 1",
+        bodyText: "hello",
+      },
+      store,
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    await created.replyOptions.onReasoningStream?.({
+      text: "reasoning text",
+    });
+    await (hooks.deliver as (payload: { text?: string }, info: { kind: string }) => Promise<void>)(
+      { text: "final answer" },
+      { kind: "final" },
+    );
+    await (hooks.onIdle as () => Promise<void>)();
+
+    expect(sent.map((entry) => entry.event)).toEqual([
+      "message.created",
+      "message.add",
+      "message.add",
+      "message.done",
+      "message.reply",
+    ]);
+    const messageId = sent.find((entry) => entry.event === "message.created")?.payload.message_id;
+    expect(store.claimMessageOnce).toHaveBeenCalledTimes(1);
+    expect(store.claimMessageOnce).toHaveBeenCalledWith(expect.objectContaining({
+      platform: "openclaw",
+      accountId: "default",
+      kind: "message",
+      direction: "outbound",
+      eventType: "message.created",
+      chatId: "chat-1",
+      messageId,
+    }));
+    expect(store.updateMessageByIdentity).toHaveBeenCalledWith(expect.objectContaining({
+      kind: "message",
+      direction: "outbound",
+      eventType: "message.reply",
+      messageId,
+      text: "final answer",
+    }));
+    expect(store.insertMessage).toHaveBeenCalledTimes(1);
+    const thinkingRow = store.insertMessage.mock.calls[0]![0];
+    expect(thinkingRow).toMatchObject({
+      platform: "openclaw",
+      accountId: "default",
+      kind: "thinking",
+      direction: "outbound",
+      eventType: "message.send",
+      chatId: "chat-1",
+      text: "reasoning text",
+    });
+    expect(thinkingRow.messageId).toBe(messageId);
+    expect(messageId).toEqual(expect.any(String));
+  });
+
+  it("uses the inbound sender id in consolidated streaming reply previews", async () => {
     let hooks:
       | {
           deliver?: (payload: { text?: string }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
@@ -11,18 +619,8 @@ describe("openclaw-clawchat reply-dispatcher", () => {
         }
       | undefined;
     const sent: Array<{ event: string; payload: Record<string, unknown> }> = [];
-    const client = {
-      opts: {
-        transport: {
-          send: (data: string) => {
-            const env = JSON.parse(data) as { event: string; payload: Record<string, unknown> };
-            sent.push({ event: env.event, payload: env.payload });
-          },
-        },
-        traceIdFactory: () => "trace-chat-marker",
-      },
-      typing: vi.fn(),
-    } as unknown as ClawlingChatClient;
+    const client = mockClient(sent);
+    const store = { claimMessageOnce: vi.fn(() => true), updateMessageByIdentity: vi.fn(), insertMessage: vi.fn() };
 
     createOpenclawClawlingReplyDispatcher({
       cfg: {} as never,
@@ -58,6 +656,7 @@ describe("openclaw-clawchat reply-dispatcher", () => {
         senderNickName: "User 1",
         bodyText: "hello",
       },
+      store: store as never,
       log: { info: vi.fn(), error: vi.fn() },
     });
 
@@ -70,7 +669,7 @@ describe("openclaw-clawchat reply-dispatcher", () => {
         context: {
           reply: {
             reply_preview: {
-              id: "chat-1",
+              id: "user-1",
               nick_name: "User 1",
             },
           },
@@ -79,7 +678,7 @@ describe("openclaw-clawchat reply-dispatcher", () => {
     });
   });
 
-  it("emits message.failed in stream mode even if execution errors before any stream chunk", async () => {
+  it("emits sanitized message.failed in stream mode even if execution errors before any stream chunk", async () => {
     let hooks:
       | {
           deliver?: (payload: { text?: string }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
@@ -88,18 +687,8 @@ describe("openclaw-clawchat reply-dispatcher", () => {
         }
       | undefined;
     const sent: Array<{ event: string; payload: Record<string, unknown> }> = [];
-    const client = {
-      opts: {
-        transport: {
-          send: (data: string) => {
-            const env = JSON.parse(data) as { event: string; payload: Record<string, unknown> };
-            sent.push({ event: env.event, payload: env.payload });
-          },
-        },
-        traceIdFactory: () => "trace-1",
-      },
-      typing: vi.fn(),
-    } as unknown as ClawlingChatClient;
+    const client = mockClient(sent);
+    const store = { claimMessageOnce: vi.fn(() => true), updateMessageByIdentity: vi.fn(), insertMessage: vi.fn() };
 
     createOpenclawClawlingReplyDispatcher({
       cfg: {} as never,
@@ -135,7 +724,11 @@ describe("openclaw-clawchat reply-dispatcher", () => {
 
     expect(sent).toHaveLength(1);
     expect(sent[0]!.event).toBe("message.failed");
-    expect(sent[0]!.payload.reason).toBe("Error: boom");
+    expect(sent[0]!.payload).not.toHaveProperty("reason");
+    expect(sent[0]!.payload.fragments).toEqual([
+      { kind: "text", text: "OpenClaw could not complete this reply." },
+    ]);
+    expect(JSON.stringify(sent[0]!.payload)).not.toContain("boom");
     expect((client.typing as ReturnType<typeof vi.fn>).mock.calls).toEqual([
       ["chat-1", false],
     ]);
@@ -150,18 +743,8 @@ describe("openclaw-clawchat reply-dispatcher", () => {
         }
       | undefined;
     const sent: Array<{ event: string; payload: Record<string, unknown> }> = [];
-    const client = {
-      opts: {
-        transport: {
-          send: (data: string) => {
-            const env = JSON.parse(data) as { event: string; payload: Record<string, unknown> };
-            sent.push({ event: env.event, payload: env.payload });
-          },
-        },
-        traceIdFactory: () => "trace-2",
-      },
-      typing: vi.fn(),
-    } as unknown as ClawlingChatClient;
+    const client = mockClient(sent);
+    const store = { claimMessageOnce: vi.fn(() => true), updateMessageByIdentity: vi.fn(), insertMessage: vi.fn() };
 
     createOpenclawClawlingReplyDispatcher({
       cfg: {} as never,
@@ -196,6 +779,7 @@ describe("openclaw-clawchat reply-dispatcher", () => {
         senderNickName: "User 1",
         bodyText: "hello",
       },
+      store: store as never,
       log: { info: vi.fn(), error: vi.fn() },
     });
 
@@ -212,20 +796,15 @@ describe("openclaw-clawchat reply-dispatcher", () => {
     expect(sent.find((entry) => entry.event === "message.done")).toBeUndefined();
   });
 
-  it("sends static error text when non-streaming reply execution fails", async () => {
+  it("does not send static error text when non-streaming reply execution fails", async () => {
     let hooks:
       | {
           onError?: (error: unknown, info: { kind: string }) => void;
         }
       | undefined;
-    const client = {
-      sendMessage: vi.fn().mockResolvedValue({
-        payload: { message_id: "server-m1", accepted_at: 1234 },
-      }),
-      replyMessage: vi.fn(),
-      typing: vi.fn(),
-    } as unknown as ClawlingChatClient;
+    const client = mockClient();
 
+    const logError = vi.fn();
     createOpenclawClawlingReplyDispatcher({
       cfg: {} as never,
       runtime: {
@@ -253,35 +832,27 @@ describe("openclaw-clawchat reply-dispatcher", () => {
       } as never,
       client,
       target: { chatId: "chat-1", chatType: "direct" },
-      log: { info: vi.fn(), error: vi.fn() },
+      log: { info: vi.fn(), error: logError },
     });
 
     hooks?.onError?.(new Error("boom"), { kind: "dispatch" });
     await new Promise((resolve) => setTimeout(resolve, 0));
 
-    expect(client.sendMessage).toHaveBeenCalledWith(
-      expect.objectContaining({
-        chat_id: "chat-1",
-        body: { fragments: [{ kind: "text", text: "Error: boom" }] },
-      }),
+    expect(client.sent).toHaveLength(0);
+    expect(logError).toHaveBeenCalledWith(
+      expect.stringContaining("openclaw-clawchat dispatch reply failed: Error: boom"),
     );
-    expect((client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]).not.toHaveProperty("chat_type");
-    expect(client.replyMessage).not.toHaveBeenCalled();
   });
 
-  it("strips delivery retry wrapper text before sending non-streaming errors", async () => {
+  it("does not attempt fallback static sends after non-streaming reply failures", async () => {
     let hooks:
       | {
           onError?: (error: unknown, info: { kind: string }) => void;
         }
       | undefined;
-    const client = {
-      sendMessage: vi.fn().mockResolvedValue({
-        payload: { message_id: "server-m1", accepted_at: 1234 },
-      }),
-      replyMessage: vi.fn(),
-      typing: vi.fn(),
-    } as unknown as ClawlingChatClient;
+    const logError = vi.fn();
+    const client = mockClient();
+    const store = { claimMessageOnce: vi.fn(() => true), insertMessage: vi.fn() };
 
     createOpenclawClawlingReplyDispatcher({
       cfg: {} as never,
@@ -310,7 +881,57 @@ describe("openclaw-clawchat reply-dispatcher", () => {
       } as never,
       client,
       target: { chatId: "chat-1", chatType: "direct" },
-      log: { info: vi.fn(), error: vi.fn() },
+      log: { info: vi.fn(), error: logError },
+    });
+
+    hooks?.onError?.(new Error("final delivery failed"), { kind: "final" });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(client.sent).toHaveLength(0);
+    expect(logError).toHaveBeenCalledWith(
+      expect.stringContaining(
+        "openclaw-clawchat final reply failed: Error: final delivery failed",
+      ),
+    );
+  });
+
+  it("strips delivery retry wrapper text before logging non-streaming errors", async () => {
+    let hooks:
+      | {
+          onError?: (error: unknown, info: { kind: string }) => void;
+        }
+      | undefined;
+    const client = mockClient();
+
+    const logError = vi.fn();
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: {
+        channel: {
+          reply: {
+            resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+            createReplyDispatcherWithTyping: vi.fn((options) => {
+              hooks = options;
+              return {
+                dispatcher: {},
+                replyOptions: {},
+                markDispatchIdle: vi.fn(),
+              };
+            }),
+          },
+        },
+      } as never,
+      account: {
+        accountId: "default",
+        userId: "agent-1",
+        replyMode: "static",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+      } as never,
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      log: { info: vi.fn(), error: logError },
     });
 
     hooks?.onError?.(
@@ -319,13 +940,11 @@ describe("openclaw-clawchat reply-dispatcher", () => {
     );
     await new Promise((resolve) => setTimeout(resolve, 0));
 
-    expect(client.sendMessage).toHaveBeenCalledWith(
-      expect.objectContaining({
-        chat_id: "chat-1",
-        body: { fragments: [{ kind: "text", text: "Error: boom" }] },
-      }),
+    expect(client.sent).toHaveLength(0);
+    expect(logError).toHaveBeenCalledWith(
+      expect.stringContaining("openclaw-clawchat dispatch reply failed: Error: boom"),
     );
-    expect((client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]).not.toHaveProperty("chat_type");
+    expect(logError).not.toHaveBeenCalledWith(expect.stringContaining("Retry failed"));
   });
 
   it("emits approval rich fragments with fallback_text when rich interactions are enabled", async () => {
@@ -344,14 +963,8 @@ describe("openclaw-clawchat reply-dispatcher", () => {
           }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
         }
       | undefined;
-    const client = {
-      sendMessage: vi.fn().mockResolvedValue({
-        payload: { message_id: "server-m1", accepted_at: 1234 },
-        trace_id: "trace-rich",
-      }),
-      replyMessage: vi.fn(),
-      typing: vi.fn(),
-    } as unknown as ClawlingChatClient;
+    const client = mockClient();
+    const store = { claimMessageOnce: vi.fn(() => true), insertMessage: vi.fn() };
 
     createOpenclawClawlingReplyDispatcher({
       cfg: {} as never,
@@ -374,9 +987,11 @@ describe("openclaw-clawchat reply-dispatcher", () => {
         forwardToolCalls: false,
         richInteractions: true,
         stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+        ack: { timeout: 10000, autoResendOnTimeout: false },
       } as never,
       client,
       target: { chatId: "chat-1", chatType: "direct" },
+      store: store as never,
       log: { info: vi.fn(), error: vi.fn() },
     });
 
@@ -401,8 +1016,8 @@ describe("openclaw-clawchat reply-dispatcher", () => {
       { kind: "final" },
     );
 
-    expect(client.sendMessage).toHaveBeenCalledWith(
-      expect.objectContaining({
+    expect(client.sent[0]?.payload).toMatchObject({
+      message: {
         body: {
           fragments: [
             {
@@ -417,8 +1032,8 @@ describe("openclaw-clawchat reply-dispatcher", () => {
             },
           ],
         },
-      }),
-    );
+      },
+    });
   });
 
   it("sends plain fallback text for presentations when rich interactions are disabled", async () => {
@@ -433,14 +1048,8 @@ describe("openclaw-clawchat reply-dispatcher", () => {
           }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
         }
       | undefined;
-    const client = {
-      sendMessage: vi.fn().mockResolvedValue({
-        payload: { message_id: "server-m1", accepted_at: 1234 },
-        trace_id: "trace-fallback",
-      }),
-      replyMessage: vi.fn(),
-      typing: vi.fn(),
-    } as unknown as ClawlingChatClient;
+    const client = mockClient();
+    const store = { claimMessageOnce: vi.fn(() => true), insertMessage: vi.fn() };
 
     createOpenclawClawlingReplyDispatcher({
       cfg: {} as never,
@@ -463,9 +1072,11 @@ describe("openclaw-clawchat reply-dispatcher", () => {
         forwardToolCalls: false,
         richInteractions: false,
         stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+        ack: { timeout: 10000, autoResendOnTimeout: false },
       } as never,
       client,
       target: { chatId: "chat-1", chatType: "direct" },
+      store: store as never,
       log: { info: vi.fn(), error: vi.fn() },
     });
 
@@ -480,13 +1091,115 @@ describe("openclaw-clawchat reply-dispatcher", () => {
       { kind: "final" },
     );
 
-    expect(client.sendMessage).toHaveBeenCalledWith(
-      expect.objectContaining({
+    expect(client.sent[0]?.payload).toMatchObject({
+      message: {
         body: {
           fragments: [{ kind: "text", text: expect.stringContaining("Delete /tmp/example.txt?") }],
         },
-      }),
+      },
+    });
+  });
+
+  it("prefers mediaUrls over legacy mediaUrl so one image is not sent twice", async () => {
+    let hooks:
+      | {
+          deliver?: (payload: {
+            text?: string;
+            mediaUrl?: string;
+            mediaUrls?: string[];
+          }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
+        }
+      | undefined;
+    const loadWebMedia = vi.fn(async (url: string) => ({
+      buffer: Buffer.from(`bytes:${url}`),
+      contentType: "image/png",
+      fileName: "image.png",
+    }));
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          code: 0,
+          msg: "ok",
+          data: {
+            kind: "image",
+            url: "https://cdn/uploaded.png",
+            name: "uploaded.png",
+            size: 12,
+            mime: "image/png",
+          },
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      ),
     );
+    const client = mockClient();
+    const store = { claimMessageOnce: vi.fn(() => true), insertMessage: vi.fn() };
+
+    try {
+      createOpenclawClawlingReplyDispatcher({
+        cfg: {} as never,
+        runtime: {
+          media: { loadWebMedia },
+          channel: {
+            reply: {
+              resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+              createReplyDispatcherWithTyping: vi.fn((options) => {
+                hooks = options;
+                return { dispatcher: {}, replyOptions: {}, markDispatchIdle: vi.fn() };
+              }),
+            },
+          },
+        } as never,
+        account: {
+          accountId: "default",
+          baseUrl: "https://api.example.com",
+          token: "tk",
+          userId: "agent-1",
+          replyMode: "static",
+          forwardThinking: true,
+          forwardToolCalls: false,
+          stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+          ack: { timeout: 10000, autoResendOnTimeout: false },
+        } as never,
+        client,
+        target: { chatId: "chat-1", chatType: "direct" },
+        store: store as never,
+        log: { info: vi.fn(), error: vi.fn() },
+      });
+
+      await hooks?.deliver?.(
+        {
+          text: "look",
+          mediaUrl: "https://cdn/legacy.png",
+          mediaUrls: ["https://cdn/image.png"],
+        },
+        { kind: "final" },
+      );
+
+      expect(loadWebMedia).toHaveBeenCalledTimes(1);
+      expect(loadWebMedia).toHaveBeenCalledWith("https://cdn/image.png", expect.any(Object));
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      expect(client.sent[0]).toMatchObject({
+        chat_id: "chat-1",
+        payload: {
+          message: {
+            body: {
+              fragments: [
+                { kind: "text", text: "look" },
+                {
+                  kind: "image",
+                  url: "https://cdn/uploaded.png",
+                  mime: "image/png",
+                  size: 12,
+                  name: "uploaded.png",
+                },
+              ],
+            },
+          },
+        },
+      });
+    } finally {
+      fetchMock.mockRestore();
+    }
   });
 
   it("includes rich interaction fragments in the consolidated streaming final reply", async () => {
@@ -507,18 +1220,8 @@ describe("openclaw-clawchat reply-dispatcher", () => {
         }
       | undefined;
     const sent: Array<{ event: string; payload: Record<string, unknown> }> = [];
-    const client = {
-      opts: {
-        transport: {
-          send: (data: string) => {
-            const env = JSON.parse(data) as { event: string; payload: Record<string, unknown> };
-            sent.push({ event: env.event, payload: env.payload });
-          },
-        },
-        traceIdFactory: () => "trace-stream-rich",
-      },
-      typing: vi.fn(),
-    } as unknown as ClawlingChatClient;
+    const client = mockClient(sent);
+    const store = { claimMessageOnce: vi.fn(() => true), updateMessageByIdentity: vi.fn(), insertMessage: vi.fn() };
 
     createOpenclawClawlingReplyDispatcher({
       cfg: {} as never,
@@ -551,6 +1254,7 @@ describe("openclaw-clawchat reply-dispatcher", () => {
         senderNickName: "User 1",
         bodyText: "hello",
       },
+      store: store as never,
       log: { info: vi.fn(), error: vi.fn() },
     });
 
@@ -601,14 +1305,8 @@ describe("openclaw-clawchat reply-dispatcher", () => {
           }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
         }
       | undefined;
-    const client = {
-      sendMessage: vi.fn().mockResolvedValue({
-        payload: { message_id: "server-m1", accepted_at: 1234 },
-        trace_id: "trace-block-rich",
-      }),
-      replyMessage: vi.fn(),
-      typing: vi.fn(),
-    } as unknown as ClawlingChatClient;
+    const client = mockClient();
+    const store = { claimMessageOnce: vi.fn(() => true), insertMessage: vi.fn() };
 
     createOpenclawClawlingReplyDispatcher({
       cfg: {} as never,
@@ -631,9 +1329,11 @@ describe("openclaw-clawchat reply-dispatcher", () => {
         forwardToolCalls: false,
         richInteractions: true,
         stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+        ack: { timeout: 10000, autoResendOnTimeout: false },
       } as never,
       client,
       target: { chatId: "chat-1", chatType: "direct" },
+      store: store as never,
       log: { info: vi.fn(), error: vi.fn() },
     });
 
@@ -650,8 +1350,8 @@ describe("openclaw-clawchat reply-dispatcher", () => {
       { kind: "block" },
     );
 
-    expect(client.sendMessage).toHaveBeenCalledWith(
-      expect.objectContaining({
+    expect(client.sent[0]?.payload).toMatchObject({
+      message: {
         body: {
           fragments: [
             {
@@ -663,7 +1363,7 @@ describe("openclaw-clawchat reply-dispatcher", () => {
             },
           ],
         },
-      }),
-    );
+      },
+    });
   });
 });