@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/reply-dispatcher.test.ts

@@ -0,0 +1,1324 @@
+import type { ClawlingChatClient } from "./ws-client.ts";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.ts";
+import {
+  clearTerminalClawChatSendsForTest,
+  markTerminalClawChatSend,
+} from "./terminal-send.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",
+    ownerUserId: "owner-1",
+    forwardThinking: true,
+    forwardToolCalls: false,
+    richInteractions: false,
+    ack: { timeout: 10000, autoResendOnTimeout: false },
+    ...overrides,
+  } as never;
+}
+
+function createDispatcherForTest(options: {
+  account?: Record<string, unknown>;
+  target?: { chatId: string; chatType: "direct" | "group" };
+  sent?: SentFrame[];
+}) {
+  let hooks: Record<string, unknown> = {};
+  const sent = options.sent ?? [];
+  const client = mockClient(sent);
+  const created = createOpenclawClawlingReplyDispatcher({
+    cfg: {} as never,
+    runtime: runtimeWithHooks((next) => {
+      hooks = next;
+    }),
+    account: replyAccount(options.account),
+    client,
+    target: options.target ?? { chatId: "group-1", chatType: "group" },
+    store: { claimMessageOnce: vi.fn(() => true), insertMessage: vi.fn(), updateMessageByIdentity: vi.fn() } as never,
+    log: { info: vi.fn(), error: vi.fn() },
+  });
+  return { created, hooks, client, sent };
+}
+
+type TestStore = {
+  claimMessageOnce?: (input: unknown) => true | false | null;
+  markMessageAcknowledged?: (input: unknown) => boolean | null;
+  updateMessageByIdentity?: (input: unknown) => void;
+  insertMessage?: (input: unknown) => unknown;
+};
+
+async function runStaticReplyWithStore(store: TestStore, text = "static reply") {
+  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 },
+    { kind: "final" },
+  );
+
+  return {
+    queuedFinal: sent.some((entry) => entry.event === "message.send" || entry.event === "message.reply"),
+    sent,
+  };
+}
+
+async function runCompleteReplyWithStore(store: TestStore, text: string) {
+  let hooks: Record<string, unknown> = {};
+  const sent: SentFrame[] = [];
+  const client = mockClient(sent);
+  createOpenclawClawlingReplyDispatcher({
+    cfg: {} as never,
+    runtime: runtimeWithHooks((next) => {
+      hooks = next;
+    }),
+    account: replyAccount({ 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)?.();
+  await (hooks.deliver as (payload: { text?: string }, info: { kind: string }) => Promise<void>)(
+    { text },
+    { kind: "final" },
+  );
+  await (hooks.onIdle as () => Promise<void>)();
+
+  return {
+    sent,
+    messageId: sent.find((entry) => entry.event === "message.send")?.payload.message_id,
+  };
+}
+
+describe("clawchat-plugin-openclaw reply-dispatcher", () => {
+  const debugRoots: string[] = [];
+
+  beforeEach(() => {
+    clearTerminalClawChatSendsForTest();
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    for (const root of debugRoots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  function enableLlmContextDebug(): string {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-llm-context-reply-"));
+    debugRoots.push(root);
+    vi.stubEnv("CLAWCHAT_LLM_CONTEXT_DEBUG", "1");
+    vi.stubEnv("CLAWCHAT_LLM_CONTEXT_SNAPSHOT_DIR", root);
+    return root;
+  }
+
+  function readOnlyDebugSnapshot(root: string): Record<string, unknown> {
+    const runsDir = path.join(root, "openclaw", "runs");
+    const files = fs.readdirSync(runsDir).filter((name) => name.endsWith(".json"));
+    expect(files).toHaveLength(1);
+    return JSON.parse(fs.readFileSync(path.join(runsDir, files[0]!), "utf8")) as Record<string, unknown>;
+  }
+
+  it("sends ClawChat typing updates for the OpenClaw reply lifecycle", async () => {
+    const { hooks, client } = createDispatcherForTest({
+      account: {},
+      target: { chatId: "chat-1", chatType: "direct" },
+    });
+
+    await (hooks.onReplyStart as () => Promise<void>)();
+    await (hooks.onIdle as () => Promise<void>)();
+
+    expect(client.typing.mock.calls).toEqual([
+      ["chat-1", true],
+      ["chat-1", false],
+    ]);
+  });
+
+  it("writes output snapshots for suppressed and delivered static replies", async () => {
+    const suppressedRoot = enableLlmContextDebug();
+    let result = await runStaticReplyWithStore({ claimMessageOnce: vi.fn(() => true) }, "<clawchat:no-reply/>");
+
+    expect(result.sent).toHaveLength(0);
+    expect(readOnlyDebugSnapshot(suppressedRoot)).toMatchObject({
+      source: "openclaw",
+      visibility: "host_event",
+      output: {
+        rawModelOutput: "<clawchat:no-reply/>",
+        adapterFilteredText: "",
+        suppressed: true,
+        suppressionReason: "no-reply token",
+      },
+    });
+
+    vi.unstubAllEnvs();
+    const deliveredRoot = enableLlmContextDebug();
+    result = await runStaticReplyWithStore({ claimMessageOnce: vi.fn(() => true) }, "visible reply");
+
+    expect(result.sent).toHaveLength(1);
+    expect(readOnlyDebugSnapshot(deliveredRoot)).toMatchObject({
+      source: "openclaw",
+      visibility: "host_event",
+      output: {
+        rawModelOutput: "visible reply",
+        adapterFilteredText: "visible reply",
+        suppressed: false,
+        suppressionReason: null,
+      },
+    });
+  });
+
+  it("forces group replies to suppress reasoning and tool deliveries even when forwarding is enabled", async () => {
+    const { hooks, sent } = createDispatcherForTest({
+      account: { forwardThinking: true, forwardToolCalls: true },
+    });
+
+    await (hooks.deliver as (payload: { text?: string; isReasoning?: boolean }, info: { kind: string }) => Promise<void>)(
+      { text: "private reasoning", isReasoning: true },
+      { kind: "block" },
+    );
+    await (hooks.deliver as (payload: { text?: string }, info: { kind: string }) => Promise<void>)(
+      { text: "tool result" },
+      { kind: "tool" },
+    );
+    await (hooks.deliver as (payload: { text?: string }, info: { kind: string }) => Promise<void>)(
+      { text: "visible answer" },
+      { kind: "final" },
+    );
+
+    expect(sent).toHaveLength(1);
+    expect(sent[0]).toMatchObject({
+      chat_id: "group-1",
+      payload: {
+        message: {
+          body: {
+            fragments: [{ kind: "text", text: "visible answer" }],
+          },
+        },
+      },
+    });
+  });
+
+  it("buffers direct tool deliveries and sends only the final complete message", async () => {
+    const { hooks, sent } = createDispatcherForTest({
+      account: { forwardToolCalls: true },
+      target: { chatId: "chat-1", chatType: "direct" },
+    });
+
+    await (hooks.deliver as (payload: { text?: string }, info: { kind: string }) => Promise<void>)(
+      { text: "tool result" },
+      { kind: "tool" },
+    );
+    expect(sent).toHaveLength(0);
+
+    await (hooks.deliver as (payload: { text?: string }, info: { kind: string }) => Promise<void>)(
+      { text: "final answer" },
+      { kind: "final" },
+    );
+
+    expect(sent.map((entry) => entry.event)).toEqual(["message.send"]);
+    expect(sent[0]).toMatchObject({
+      chat_id: "chat-1",
+      payload: {
+        message: {
+          body: {
+            fragments: [{ kind: "text", text: "final answer" }],
+          },
+        },
+      },
+    });
+  });
+
+  it("does not expose streaming reply hooks", () => {
+    const { created } = createDispatcherForTest({
+      account: { forwardThinking: true },
+      target: { chatId: "user-1", chatType: "direct" },
+    });
+
+    expect(created.replyOptions.onReasoningStream).toBeUndefined();
+    expect(created.replyOptions.onPartialReply).toBeUndefined();
+  });
+
+  it("routes group approval and action cards to owner direct chat instead of the group", async () => {
+    const { hooks, sent } = createDispatcherForTest({
+      account: { richInteractions: false },
+    });
+
+    await (hooks.deliver as (payload: {
+      text?: string;
+      presentation?: {
+        title?: string;
+        tone?: string;
+        blocks: Array<
+          | { type: "text"; text: string }
+          | { type: "buttons"; buttons: Array<{ label: string; value?: string; style?: string }> }
+        >;
+      };
+    }, info: { kind: string }) => Promise<void>)(
+      {
+        text: "Approve deploy?",
+        presentation: {
+          title: "Approval required",
+          tone: "warning",
+          blocks: [
+            { type: "text", text: "Deploy to production?" },
+            {
+              type: "buttons",
+              buttons: [
+                { label: "Approve", value: "approve", style: "primary" },
+                { label: "Deny", value: "deny", style: "danger" },
+              ],
+            },
+          ],
+        },
+      },
+      { kind: "final" },
+    );
+
+    expect(sent).toHaveLength(1);
+    expect(sent[0]?.chat_id).toBe("owner-1");
+    expect(sent[0]?.payload).toMatchObject({
+      message: {
+        body: {
+          fragments: [
+            { kind: "text", text: expect.stringContaining("ClawChat group group-1 requires owner attention.") },
+            {
+              kind: "approval_request",
+              title: "Approval required",
+              state: "pending",
+              actions: [
+                { id: "approve", label: "Approve" },
+                { id: "deny", label: "Deny" },
+              ],
+            },
+          ],
+        },
+      },
+    });
+  });
+
+  it("suppresses group runtime failures without sending them to any ClawChat client", async () => {
+    const { hooks, sent } = createDispatcherForTest({
+      account: {},
+    });
+
+    (hooks.onError as (error: unknown, info: { kind: string }) => void)(
+      new Error("secret stack"),
+      { kind: "dispatch" },
+    );
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(sent).toHaveLength(0);
+  });
+
+  it("forces complete block delivery and omits streaming hooks", () => {
+    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({}),
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      store: { claimMessageOnce: vi.fn(() => true), insertMessage: vi.fn() } as never,
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    expect(hooks).toBeTruthy();
+    expect((created.replyOptions as Record<string, unknown>).sourceReplyDeliveryMode).toBe("automatic");
+    expect((created.replyOptions as Record<string, unknown>).disableBlockStreaming).toBe(true);
+    expect(created.replyOptions.onPartialReply).toBeUndefined();
+    expect(created.replyOptions.onReasoningStream).toBeUndefined();
+  });
+
+  it("suppresses one static final reply after a terminal ClawChat tool send", async () => {
+    let hooks: Record<string, unknown> = {};
+    const sent: SentFrame[] = [];
+    const client = mockClient(sent);
+    const log = { info: vi.fn(), error: vi.fn() };
+
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: runtimeWithHooks((next) => {
+        hooks = next;
+      }),
+      account: replyAccount(),
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      terminalSendScopeId: "scope-1",
+      store: { claimMessageOnce: vi.fn(() => true), insertMessage: vi.fn() } as never,
+      log,
+    });
+
+    markTerminalClawChatSend({
+      accountId: "default",
+      chatId: "chat-1",
+      messageId: "msg-terminal",
+      scopeId: "scope-1",
+    });
+
+    await (hooks.deliver as (payload: { text?: string }, info: { kind: "final" }) => Promise<void>)(
+      { text: "already sent" },
+      { kind: "final" },
+    );
+
+    expect(sent).toHaveLength(0);
+    expect(log.info).toHaveBeenCalledWith(
+      expect.stringContaining("suppressing final reply after terminal tool send msg=msg-terminal"),
+    );
+
+    let nextHooks: Record<string, unknown> = {};
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: runtimeWithHooks((next) => {
+        nextHooks = next;
+      }),
+      account: replyAccount(),
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      terminalSendScopeId: "scope-2",
+      store: { claimMessageOnce: vi.fn(() => true), insertMessage: vi.fn() } as never,
+      log,
+    });
+
+    await (nextHooks.deliver as (payload: { text?: string }, info: { kind: "final" }) => Promise<void>)(
+      { text: "next turn" },
+      { kind: "final" },
+    );
+
+    expect(sent.some((entry) => entry.event === "message.send")).toBe(true);
+  });
+
+  it("suppresses complete final reply after a terminal ClawChat tool send", async () => {
+    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({}),
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      inboundMessageId: "inbound-1",
+      terminalSendScopeId: "scope-1",
+      inboundForFinalReply: {
+        chatId: "chat-1",
+        senderId: "user-1",
+        senderNickName: "User 1",
+        bodyText: "hello",
+      },
+      store: { claimMessageOnce: vi.fn(() => true), insertMessage: vi.fn() } as never,
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    expect(created.replyOptions.onPartialReply).toBeUndefined();
+    markTerminalClawChatSend({
+      accountId: "default",
+      chatId: "chat-1",
+      messageId: "msg-terminal",
+      scopeId: "scope-1",
+    });
+    await (hooks.deliver as (payload: { text?: string }, info: { kind: "final" }) => Promise<void>)(
+      { text: "partial final" },
+      { kind: "final" },
+    );
+    await (hooks.onIdle as () => Promise<void>)();
+
+    expect(sent.some((entry) => entry.event === "message.reply")).toBe(false);
+    expect(sent.some((entry) => entry.event === "message.send")).toBe(false);
+  });
+
+  it("buffers OpenClaw block deliveries and sends only the final complete message", async () => {
+    let hooks: Record<string, unknown> = {};
+    const sent: SentFrame[] = [];
+    const client = mockClient(sent);
+    const store = {
+      claimMessageOnce: vi.fn(() => true),
+      updateMessageByIdentity: vi.fn(),
+      insertMessage: vi.fn(),
+    };
+
+    const created = createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: runtimeWithHooks((next) => {
+        hooks = next;
+      }),
+      account: replyAccount({}),
+      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() },
+    });
+
+    expect(created.replyOptions.onPartialReply).toBeUndefined();
+    await (hooks.deliver as (payload: { text?: string }, info: { kind: "block" }) => Promise<void>)(
+      { text: "partial answer" },
+      { kind: "block" },
+    );
+    expect(sent).toHaveLength(0);
+    expect(store.claimMessageOnce).not.toHaveBeenCalled();
+
+    await (hooks.deliver as (payload: { text?: string }, info: { kind: "final" }) => Promise<void>)(
+      { text: "final answer" },
+      { kind: "final" },
+    );
+    await (hooks.onIdle as () => Promise<void>)();
+
+    expect(sent.map((entry) => entry.event)).toEqual(["message.send"]);
+    expect(sent[0]?.payload).toMatchObject({
+      message: {
+        body: { fragments: [{ kind: "text", text: "final answer" }] },
+      },
+    });
+    expect(store.claimMessageOnce).toHaveBeenCalledWith(expect.objectContaining({
+      eventType: "message.send",
+      text: "final answer",
+    }));
+  });
+
+  it("forces complete block delivery for explicit static mode", () => {
+    const client = mockClient();
+
+    const created = createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: runtimeWithHooks(() => {}),
+      account: replyAccount({}),
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      store: { claimMessageOnce: vi.fn(() => true), insertMessage: vi.fn() } as never,
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    expect((created.replyOptions as Record<string, unknown>).disableBlockStreaming).toBe(true);
+    expect(created.replyOptions.onPartialReply).toBeUndefined();
+    expect(created.replyOptions.onReasoningStream).toBeUndefined();
+  });
+
+  it("claims static outbound before send and uses the claimed payload message_id", async () => {
+    const store = {
+      claimMessageOnce: vi.fn(() => true),
+      markMessageAcknowledged: 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.markMessageAcknowledged).toHaveBeenCalledWith({
+      accountId: "default",
+      kind: "message",
+      direction: "outbound",
+      messageId,
+      protocolMessageId: messageId,
+      ackedAt: 1234,
+    });
+    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("buffers forwarded thinking and records it only with the final complete message", 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({ 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(sent).toHaveLength(0);
+    expect(store.claimMessageOnce).not.toHaveBeenCalled();
+
+    await (hooks.deliver as (payload: { text?: string }, info: { kind: "final" }) => Promise<void>)(
+      { text: "final answer" },
+      { kind: "final" },
+    );
+
+    const messageId = store.claimMessageOnce.mock.calls[0]?.[0].messageId;
+
+    expect(store.claimMessageOnce).toHaveBeenCalledWith(expect.objectContaining({
+      kind: "message",
+      direction: "outbound",
+      eventType: "message.send",
+      messageId,
+      text: "final answer",
+    }));
+    expect(sent[0]?.payload.message_id).toBe(messageId);
+    expect(store.insertMessage).toHaveBeenCalledWith(expect.objectContaining({
+      kind: "thinking",
+      messageId,
+      text: "thinking text",
+    }));
+  });
+
+  it("does not claim or send reasoning-only deliveries", 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({ 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).not.toHaveBeenCalled();
+      expect(sent).toHaveLength(0);
+      expect(store.insertMessage).not.toHaveBeenCalled();
+    }
+  });
+
+  it("claims outbound final messages before sending", async () => {
+    const store = {
+      claimMessageOnce: vi.fn(() => true),
+      updateMessageByIdentity: vi.fn(),
+      insertMessage: vi.fn(),
+    };
+
+    const result = await runCompleteReplyWithStore(store, "hello final");
+
+    expect(result.messageId).toEqual(expect.any(String));
+    expect(result.sent.map((entry) => entry.event)).toEqual(["message.send"]);
+    expect(store.claimMessageOnce).toHaveBeenCalledTimes(1);
+    expect(store.claimMessageOnce).toHaveBeenCalledWith(expect.objectContaining({
+      direction: "outbound",
+      eventType: "message.send",
+      messageId: result.messageId,
+      text: "hello final",
+    }));
+  });
+
+  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("does not emit lifecycle failure frames", async () => {
+    let hooks:
+      | {
+          deliver?: (payload: { text?: string }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
+          onIdle?: () => Promise<void>;
+          onError?: (error: unknown, info: { kind: string }) => void;
+        }
+      | undefined;
+    const sent: Array<{ event: string; payload: Record<string, unknown> }> = [];
+    const client = mockClient(sent);
+    const store = { claimMessageOnce: vi.fn(() => true), updateMessageByIdentity: vi.fn(), insertMessage: 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",
+        forwardThinking: true,
+        forwardToolCalls: false,
+      } as never,
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      inboundMessageId: "inbound-1",
+      inboundForFinalReply: {
+        senderId: "user-1",
+        senderNickName: "User 1",
+        bodyText: "hello",
+      },
+      store: store as never,
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    hooks?.onError?.(new Error("boom"), { kind: "dispatch" });
+    await hooks?.onIdle?.();
+
+    expect(sent).toHaveLength(0);
+    expect(sent.find((entry) => entry.event === "message.reply")).toBeUndefined();
+  });
+
+  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 = 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",
+        forwardThinking: true,
+        forwardToolCalls: false,
+      } as never,
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      log: { info: vi.fn(), error: logError },
+    });
+
+    hooks?.onError?.(new Error("boom"), { kind: "dispatch" });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(client.sent).toHaveLength(0);
+    expect(logError).toHaveBeenCalledWith(
+      expect.stringContaining("clawchat-plugin-openclaw dispatch reply failed: Error: boom"),
+    );
+  });
+
+  it("does not attempt fallback static sends after non-streaming reply failures", async () => {
+    let hooks:
+      | {
+          onError?: (error: unknown, info: { kind: string }) => void;
+        }
+      | undefined;
+    const logError = vi.fn();
+    const client = mockClient();
+    const store = { claimMessageOnce: vi.fn(() => true), insertMessage: 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",
+        forwardThinking: true,
+        forwardToolCalls: false,
+      } as never,
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      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(
+        "clawchat-plugin-openclaw 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",
+        forwardThinking: true,
+        forwardToolCalls: false,
+      } as never,
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      log: { info: vi.fn(), error: logError },
+    });
+
+    hooks?.onError?.(
+      new Error("Retry failed for delivery 123: Error: boom"),
+      { kind: "dispatch" },
+    );
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(client.sent).toHaveLength(0);
+    expect(logError).toHaveBeenCalledWith(
+      expect.stringContaining("clawchat-plugin-openclaw dispatch reply failed: Error: boom"),
+    );
+    expect(logError).not.toHaveBeenCalledWith(expect.stringContaining("Retry failed"));
+  });
+
+  it("emits approval rich fragments with fallback_text when rich interactions are enabled", async () => {
+    let hooks:
+      | {
+          deliver?: (payload: {
+            text?: string;
+            presentation?: {
+              title?: string;
+              tone?: string;
+              blocks: Array<
+                | { type: "text"; text: string }
+                | { type: "buttons"; buttons: Array<{ label: string; value?: string; style?: string }> }
+              >;
+            };
+          }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
+        }
+      | undefined;
+    const client = mockClient();
+    const store = { claimMessageOnce: vi.fn(() => true), insertMessage: 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",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        richInteractions: true,
+        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: "Approve file deletion?",
+        presentation: {
+          title: "Approval required",
+          tone: "warning",
+          blocks: [
+            { type: "text", text: "Delete /tmp/example.txt?" },
+            {
+              type: "buttons",
+              buttons: [
+                { label: "Approve", value: "approve", style: "primary" },
+                { label: "Deny", value: "deny", style: "danger" },
+              ],
+            },
+          ],
+        },
+      },
+      { kind: "final" },
+    );
+
+    expect(client.sent[0]?.payload).toMatchObject({
+      message: {
+        body: {
+          fragments: [
+            {
+              kind: "approval_request",
+              title: "Approval required",
+              fallback_text: expect.stringContaining("Delete /tmp/example.txt?"),
+              state: "pending",
+              actions: [
+                { id: "approve", label: "Approve", style: "primary", payload: { value: "approve" } },
+                { id: "deny", label: "Deny", style: "danger", payload: { value: "deny" } },
+              ],
+            },
+          ],
+        },
+      },
+    });
+  });
+
+  it("sends plain fallback text for presentations when rich interactions are disabled", async () => {
+    let hooks:
+      | {
+          deliver?: (payload: {
+            text?: string;
+            presentation?: {
+              title?: string;
+              blocks: Array<{ type: "text"; text: string }>;
+            };
+          }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
+        }
+      | undefined;
+    const client = mockClient();
+    const store = { claimMessageOnce: vi.fn(() => true), insertMessage: 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",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        richInteractions: false,
+        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: "Approve file deletion?",
+        presentation: {
+          title: "Approval required",
+          blocks: [{ type: "text", text: "Delete /tmp/example.txt?" }],
+        },
+      },
+      { kind: "final" },
+    );
+
+    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",
+          forwardThinking: true,
+          forwardToolCalls: false,
+          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: "draft",
+          mediaUrls: ["https://cdn/draft.png"],
+        },
+        { kind: "block" },
+      );
+
+      expect(loadWebMedia).not.toHaveBeenCalled();
+      expect(fetchMock).not.toHaveBeenCalled();
+      expect(client.sent).toHaveLength(0);
+
+      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("buffers non-final rich block payloads in static mode", async () => {
+    let hooks:
+      | {
+          deliver?: (payload: {
+            text?: string;
+            presentation?: {
+              title?: string;
+              blocks: Array<
+                | { type: "text"; text: string }
+                | { type: "buttons"; buttons: Array<{ label: string; value?: string }> }
+              >;
+            };
+          }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
+        }
+      | undefined;
+    const client = mockClient();
+    const store = { claimMessageOnce: vi.fn(() => true), insertMessage: 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",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        richInteractions: true,
+        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?.(
+      {
+        presentation: {
+          title: "Choose next step",
+          blocks: [
+            { type: "text", text: "Pick an action" },
+            { type: "buttons", buttons: [{ label: "Continue", value: "continue" }] },
+          ],
+        },
+      },
+      { kind: "block" },
+    );
+
+    expect(client.sent).toHaveLength(0);
+    expect(store.claimMessageOnce).not.toHaveBeenCalled();
+
+    await hooks?.deliver?.(
+      {
+        presentation: {
+          title: "Choose next step",
+          blocks: [
+            { type: "text", text: "Pick an action" },
+            { type: "buttons", buttons: [{ label: "Continue", value: "continue" }] },
+          ],
+        },
+      },
+      { kind: "final" },
+    );
+
+    expect(client.sent[0]?.payload).toMatchObject({
+      message: {
+        body: {
+          fragments: [
+            {
+              kind: "action_card",
+              title: "Choose next step",
+              fallback_text: expect.stringContaining("Pick an action"),
+              state: "pending",
+              actions: [{ id: "continue", label: "Continue", payload: { value: "continue" } }],
+            },
+          ],
+        },
+      },
+    });
+  });
+});