@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/outbound.test.ts

@@ -0,0 +1,1269 @@
+import { EventEmitter } from "node:events";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
+import { describe, expect, it, vi } from "vitest";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+import type { Envelope, MessageAckPayload } from "./protocol-types.ts";
+import { createClawChatClient, type ClawlingChatClient } from "./ws-client.ts";
+import { MockTransport } from "./mock-transport.ts";
+import {
+  flushAlignedOutboundQueue,
+  getAlignedOutboundQueueSize,
+  sendOpenclawClawlingMedia,
+  sendOpenclawClawlingMentionMessage,
+  sendOpenclawClawlingText,
+} from "./outbound.ts";
+
+function baseAccount(
+  overrides: Partial<ResolvedOpenclawClawlingAccount> = {},
+): ResolvedOpenclawClawlingAccount {
+  return {
+    accountId: DEFAULT_ACCOUNT_ID,
+    name: "clawchat-plugin-openclaw",
+    enabled: true,
+    configured: true,
+    websocketUrl: "ws://t",
+    baseUrl: "",
+    token: "tk",
+    agentId: "",
+    userId: "agent-1",
+    ownerUserId: "owner-1",
+    groupMode: "all",
+    groupCommandMode: "owner",
+    groups: {},
+    forwardThinking: true,
+    forwardToolCalls: false,
+    richInteractions: false,
+    allowFrom: [],
+    reconnect: {
+      initialDelay: 1000,
+      maxDelay: 30000,
+      jitterRatio: 0.3,
+      maxRetries: Number.POSITIVE_INFINITY,
+    },
+    heartbeat: { interval: 25000, timeout: 10000 },
+    ack: { timeout: 10000, autoResendOnTimeout: false },
+    ...overrides,
+  };
+}
+
+type MockOutboundClient = ClawlingChatClient & {
+  sent: string[];
+  setTransportState: (state: "open" | "closed") => void;
+  setState: (state: string | undefined) => void;
+};
+
+function mockClient(options: { transportState?: "open" | "closed"; state?: string } = {}): MockOutboundClient {
+  let transportState = options.transportState ?? "open";
+  let clientState = options.state;
+  let trace = 0;
+  const sent: string[] = [];
+  const client = Object.assign(new EventEmitter(), {
+    sent,
+    setTransportState: (state: "open" | "closed") => {
+      transportState = state;
+    },
+    setState: (state: string | undefined) => {
+      clientState = state;
+    },
+    nextTraceId: vi.fn(() => `trace-${++trace}`),
+    sendWire: vi.fn((wire: string) => {
+      if (transportState !== "open") throw new Error("socket closed");
+      sent.push(wire);
+    }),
+    typing: vi.fn(),
+    emitRaw: vi.fn(),
+    sendRawEnvelope: vi.fn(),
+  });
+  Object.defineProperty(client, "transportState", { get: () => transportState });
+  Object.defineProperty(client, "state", { get: () => clientState });
+  return client as unknown as MockOutboundClient;
+}
+
+function decodeSent(client: MockOutboundClient): Envelope[] {
+  return client.sent.map((wire) => JSON.parse(wire) as Envelope);
+}
+
+function emitAck(
+  client: MockOutboundClient,
+  traceId: string,
+  payload: MessageAckPayload = { message_id: "server-m1", accepted_at: 1234 },
+): void {
+  client.emit("raw", {
+    version: "2",
+    event: "message.ack",
+    trace_id: traceId,
+    emitted_at: Date.now(),
+    payload,
+  } satisfies Envelope<MessageAckPayload>);
+}
+
+function emitMessageError(client: MockOutboundClient, traceId: string): void {
+  client.emit("raw", {
+    version: "2",
+    event: "message.error",
+    trace_id: traceId,
+    emitted_at: Date.now(),
+    chat_id: "missing-chat",
+    payload: { code: "chat_not_found", message: "chat not resolvable" },
+  } satisfies Envelope);
+}
+
+function decodeTransportSent(transport: MockTransport): Envelope[] {
+  return transport.sent.map((wire) => JSON.parse(wire) as Envelope);
+}
+
+async function connectReady(transport: MockTransport, client: ReturnType<typeof createClawChatClient>) {
+  const connected = client.connect();
+  await Promise.resolve();
+  transport.emitInbound(JSON.stringify({
+    version: "2",
+    event: "connect.challenge",
+    trace_id: "challenge-1",
+    emitted_at: Date.now(),
+    payload: { nonce: "nonce-1" },
+  }));
+  const connectFrame = decodeTransportSent(transport).find((env) => env.event === "connect")!;
+  transport.emitInbound(JSON.stringify({
+    version: "2",
+    event: "hello-ok",
+    trace_id: connectFrame.trace_id,
+    emitted_at: Date.now(),
+    payload: { device_id: "agent-1", delivery_mode: "device_replay" },
+  }));
+  await connected;
+}
+
+describe("clawchat-plugin-openclaw outbound", () => {
+  it("sends the legacy silent response marker", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: "<clawchat:silent/>",
+    });
+    const frame = decodeSent(client)[0]!;
+    expect((frame.payload as { message: { body: { fragments: unknown[] } } }).message.body.fragments).toEqual([
+      { kind: "text", text: "<clawchat:silent/>" },
+    ]);
+    emitAck(client, frame.trace_id, { message_id: "msg-legacy-silent", accepted_at: Date.now() });
+    const result = await send;
+
+    expect(result?.messageId).toBe("msg-legacy-silent");
+  });
+
+  it("suppresses the quoted empty response marker", async () => {
+    const client = mockClient();
+    const result = await sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: '""',
+    });
+
+    expect(result).toBeNull();
+    expect(decodeSent(client)).toEqual([]);
+  });
+
+  it("suppresses the no-reply token", async () => {
+    const client = mockClient();
+    const result = await sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: "<clawchat:no-reply/>",
+    });
+
+    expect(result).toBeNull();
+    expect(decodeSent(client)).toEqual([]);
+  });
+
+  it("sends text wrapped in Chinese full-width parentheses", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: "（我保持沉默）",
+    });
+    const frame = decodeSent(client)[0]!;
+    expect((frame.payload as { message: { body: { fragments: unknown[] } } }).message.body.fragments).toEqual([
+      { kind: "text", text: "（我保持沉默）" },
+    ]);
+    emitAck(client, frame.trace_id, { message_id: "msg-chinese-parentheses", accepted_at: Date.now() });
+    const result = await send;
+
+    expect(result?.messageId).toBe("msg-chinese-parentheses");
+  });
+
+  it("sends text wrapped in ASCII parentheses", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: "(staying silent)",
+    });
+    const frame = decodeSent(client)[0]!;
+    expect((frame.payload as { message: { body: { fragments: unknown[] } } }).message.body.fragments).toEqual([
+      { kind: "text", text: "(staying silent)" },
+    ]);
+    emitAck(client, frame.trace_id, { message_id: "msg-ascii-parentheses", accepted_at: Date.now() });
+    const result = await send;
+
+    expect(result?.messageId).toBe("msg-ascii-parentheses");
+  });
+
+  it("sends nonempty quoted text", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: '"hello"',
+    });
+    const frame = decodeSent(client)[0]!;
+    expect((frame.payload as { message: { body: { fragments: unknown[] } } }).message.body.fragments).toEqual([
+      { kind: "text", text: '"hello"' },
+    ]);
+    emitAck(client, frame.trace_id, { message_id: "msg-quoted-text", accepted_at: Date.now() });
+    const result = await send;
+
+    expect(result?.messageId).toBe("msg-quoted-text");
+  });
+
+  it("does not suppress the silent response marker when media is present", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: "<clawchat:silent/>",
+      mediaFragments: [{ kind: "image", url: "https://cdn/x.png" }],
+    });
+    const frame = decodeSent(client)[0]!;
+    expect((frame.payload as { message: { body: { fragments: unknown[] } } }).message.body.fragments).toEqual([
+      { kind: "text", text: "<clawchat:silent/>" },
+      { kind: "image", url: "https://cdn/x.png" },
+    ]);
+    emitAck(client, frame.trace_id, { message_id: "msg-with-media", accepted_at: Date.now() });
+    const result = await send;
+
+    expect(result?.messageId).toBe("msg-with-media");
+  });
+
+  it("does not suppress text wrapped in Chinese full-width parentheses when media is present", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: "（我保持沉默）",
+      mediaFragments: [{ kind: "image", url: "https://cdn/x.png" }],
+    });
+    const frame = decodeSent(client)[0]!;
+    expect((frame.payload as { message: { body: { fragments: unknown[] } } }).message.body.fragments).toEqual([
+      { kind: "text", text: "（我保持沉默）" },
+      { kind: "image", url: "https://cdn/x.png" },
+    ]);
+    emitAck(client, frame.trace_id, { message_id: "msg-with-chinese-marker-media", accepted_at: Date.now() });
+    const result = await send;
+
+    expect(result?.messageId).toBe("msg-with-chinese-marker-media");
+  });
+
+  it("does not suppress text wrapped in ASCII parentheses when media is present", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: "(staying silent)",
+      mediaFragments: [{ kind: "image", url: "https://cdn/x.png" }],
+    });
+    const frame = decodeSent(client)[0]!;
+    expect((frame.payload as { message: { body: { fragments: unknown[] } } }).message.body.fragments).toEqual([
+      { kind: "text", text: "(staying silent)" },
+      { kind: "image", url: "https://cdn/x.png" },
+    ]);
+    emitAck(client, frame.trace_id, { message_id: "msg-with-ascii-marker-media", accepted_at: Date.now() });
+    const result = await send;
+
+    expect(result?.messageId).toBe("msg-with-ascii-marker-media");
+  });
+
+  it("sends text that only contains the silent response marker", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: "note: <clawchat:silent/>",
+    });
+    const frame = decodeSent(client)[0]!;
+    expect((frame.payload as { message: { body: { fragments: unknown[] } } }).message.body.fragments).toEqual([
+      { kind: "text", text: "note: <clawchat:silent/>" },
+    ]);
+    emitAck(client, frame.trace_id, { message_id: "msg-normal-text", accepted_at: Date.now() });
+    const result = await send;
+
+    expect(result?.messageId).toBe("msg-normal-text");
+  });
+
+  it("sends text that mentions the no-reply token", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: "note: <clawchat:no-reply/>",
+    });
+    const frame = decodeSent(client)[0]!;
+    expect((frame.payload as { message: { body: { fragments: unknown[] } } }).message.body.fragments).toEqual([
+      { kind: "text", text: "note: <clawchat:no-reply/>" },
+    ]);
+    emitAck(client, frame.trace_id, { message_id: "msg-normal-no-reply-text", accepted_at: Date.now() });
+    const result = await send;
+
+    expect(result?.messageId).toBe("msg-normal-no-reply-text");
+  });
+
+  it("sends message.send when no replyCtx", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "user-1", chatType: "direct" },
+      text: "hello",
+    });
+    const frame = decodeSent(client)[0]!;
+    expect(frame).toMatchObject({
+      event: "message.send",
+      chat_id: "user-1",
+      payload: {
+        message: { body: { fragments: [{ kind: "text", text: "hello" }] } },
+      },
+    });
+    expect(frame).not.toHaveProperty("chat_type");
+    emitAck(client, frame.trace_id);
+    const result = await send;
+    expect(result?.messageId).toBe("server-m1");
+    expect(result?.acceptedAt).toBe(1234);
+  });
+
+  it("sendOpenclawClawlingMentionMessage emits mention fragments and context mentions", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingMentionMessage({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: "请看这个",
+      mentions: [{ userId: "user-a", display: "Alice" }],
+    });
+
+    const frame = decodeSent(client).find((env) => env.event === "message.send")!;
+    emitAck(client, frame.trace_id, { message_id: "msg-mention-1", accepted_at: 1234 });
+
+    await expect(send).resolves.toEqual({
+      messageId: "msg-mention-1",
+      acceptedAt: 1234,
+      mentions: ["user-a"],
+    });
+
+    expect(frame.payload).toMatchObject({
+      message: {
+        body: {
+          fragments: [
+            { kind: "mention", user_id: "user-a", display: "Alice" },
+            { kind: "text", text: " 请看这个" },
+          ],
+        },
+        context: {
+          mentions: [{ kind: "mention", user_id: "user-a", display: "Alice" }],
+          reply: null,
+        },
+      },
+    });
+  });
+
+  it("sendOpenclawClawlingMentionMessage emits multiple mention fragments before text", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingMentionMessage({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: "一起看",
+      mentions: [
+        { userId: "user-a", display: "Alice" },
+        { userId: "user-b", display: "Bob" },
+      ],
+    });
+
+    const frame = decodeSent(client).find((env) => env.event === "message.send")!;
+    emitAck(client, frame.trace_id, { message_id: "msg-mention-2", accepted_at: 1234 });
+
+    await expect(send).resolves.toMatchObject({
+      messageId: "msg-mention-2",
+      mentions: ["user-a", "user-b"],
+    });
+    expect(frame.payload).toMatchObject({
+      message: {
+        body: {
+          fragments: [
+            { kind: "mention", user_id: "user-a", display: "Alice" },
+            { kind: "mention", user_id: "user-b", display: "Bob" },
+            { kind: "text", text: " 一起看" },
+          ],
+        },
+        context: {
+          mentions: [
+            { kind: "mention", user_id: "user-a", display: "Alice" },
+            { kind: "mention", user_id: "user-b", display: "Bob" },
+          ],
+        },
+      },
+    });
+  });
+
+  it("sendOpenclawClawlingMentionMessage sends mention-only messages without text", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingMentionMessage({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      mentions: [{ userId: "user-a", display: "Alice" }],
+    });
+
+    const frame = decodeSent(client).find((env) => env.event === "message.send")!;
+    emitAck(client, frame.trace_id, { message_id: "msg-mention-only-1", accepted_at: 1234 });
+
+    expect(frame.payload).toMatchObject({
+      message: {
+        body: {
+          fragments: [
+            { kind: "mention", user_id: "user-a", display: "Alice" },
+          ],
+        },
+        context: {
+          mentions: [{ kind: "mention", user_id: "user-a", display: "Alice" }],
+          reply: null,
+        },
+      },
+    });
+    await expect(send).resolves.toEqual({
+      messageId: "msg-mention-only-1",
+      acceptedAt: 1234,
+      mentions: ["user-a"],
+    });
+  });
+
+  it("sendOpenclawClawlingMentionMessage lifts text-only @label into mention display", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingMentionMessage({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: "@Alice",
+      mentions: [{ userId: "user-a" }],
+    });
+
+    const frame = decodeSent(client).find((env) => env.event === "message.send")!;
+    emitAck(client, frame.trace_id, { message_id: "msg-mention-label-1", accepted_at: 1234 });
+
+    expect(frame.payload).toMatchObject({
+      message: {
+        body: {
+          fragments: [
+            { kind: "mention", user_id: "user-a", display: "Alice" },
+          ],
+        },
+        context: {
+          mentions: [{ kind: "mention", user_id: "user-a", display: "Alice" }],
+          reply: null,
+        },
+      },
+    });
+    await expect(send).resolves.toMatchObject({
+      messageId: "msg-mention-label-1",
+      mentions: ["user-a"],
+    });
+  });
+
+  it("sendOpenclawClawlingMentionMessage keeps spaces in a text-only mention display label", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingMentionMessage({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      text: "@Super Zero",
+      mentions: [{ userId: "user-a" }],
+    });
+
+    const frame = decodeSent(client).find((env) => env.event === "message.send")!;
+    emitAck(client, frame.trace_id, { message_id: "msg-mention-label-2", accepted_at: 1234 });
+
+    expect(frame.payload).toMatchObject({
+      message: {
+        body: {
+          fragments: [
+            { kind: "mention", user_id: "user-a", display: "Super Zero" },
+          ],
+        },
+        context: {
+          mentions: [{ kind: "mention", user_id: "user-a", display: "Super Zero" }],
+          reply: null,
+        },
+      },
+    });
+    await expect(send).resolves.toMatchObject({
+      messageId: "msg-mention-label-2",
+      mentions: ["user-a"],
+    });
+  });
+
+  it("sendOpenclawClawlingMentionMessage preserves reply id without inventing preview", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingMentionMessage({
+      client,
+      account: baseAccount(),
+      to: { chatId: "group-1", chatType: "group" },
+      mentions: [{ userId: "user-a", display: "Alice" }],
+      replyCtx: { replyToMessageId: "m-orig" },
+    });
+
+    const frame = decodeSent(client)[0]!;
+    expect(frame).toMatchObject({
+      event: "message.send",
+      chat_id: "group-1",
+      payload: {
+        message: {
+          context: {
+            mentions: [{ kind: "mention", user_id: "user-a", display: "Alice" }],
+            reply: {
+              reply_to_msg_id: "m-orig",
+              reply_preview: null,
+            },
+          },
+        },
+      },
+    });
+    emitAck(client, frame.trace_id, { message_id: "msg-mention-reply", accepted_at: 1234 });
+    await expect(send).resolves.toMatchObject({
+      messageId: "msg-mention-reply",
+      mentions: ["user-a"],
+    });
+  });
+
+  it("sends message.reply when replyCtx is provided", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "chat-1", chatType: "direct" },
+      text: "reply",
+      replyCtx: {
+        replyToMessageId: "m-orig",
+        replyPreviewChatId: "chat-1",
+        replyPreviewSenderId: "user-2",
+        replyPreviewNickName: "Sender",
+        replyPreviewText: "original",
+      },
+    });
+    const frame = decodeSent(client)[0]!;
+    expect(frame).toMatchObject({
+      event: "message.reply",
+      chat_id: "chat-1",
+      payload: {
+        message: {
+          body: { fragments: [{ kind: "text", text: "reply" }] },
+          context: {
+            reply: {
+              reply_to_msg_id: "m-orig",
+              reply_preview: {
+                id: "user-2",
+                nick_name: "Sender",
+                fragments: [{ kind: "text", text: "original" }],
+              },
+            },
+          },
+        },
+      },
+    });
+    expect(frame).not.toHaveProperty("chat_type");
+    emitAck(client, frame.trace_id, { message_id: "server-r1", accepted_at: 5678 });
+    await expect(send).resolves.toMatchObject({ messageId: "server-r1", acceptedAt: 5678 });
+  });
+
+  it("sends static outbound with caller supplied payload message_id", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "chat-1", chatType: "direct" },
+      text: "hello",
+      messageId: "local-msg-1",
+    });
+    const frame = decodeSent(client)[0]!;
+    expect((frame.payload as { message_id?: string }).message_id).toBe("local-msg-1");
+    emitAck(client, frame.trace_id, { message_id: "local-msg-1", accepted_at: 1234 });
+    await expect(send).resolves.toMatchObject({ messageId: "local-msg-1" });
+  });
+
+  it("rejects static outbound when ack message_id does not match", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "chat-1", chatType: "direct" },
+      text: "hello",
+      messageId: "local-msg-1",
+    });
+    const frame = decodeSent(client)[0]!;
+    emitAck(client, frame.trace_id, { message_id: "other-msg", accepted_at: 1234 });
+    await expect(send).rejects.toThrow("ack message_id mismatch");
+  });
+
+  it("rejects aligned outbound sends from matching message.error", async () => {
+    vi.useFakeTimers();
+    try {
+      const client = mockClient();
+      const send = sendOpenclawClawlingText({
+        client,
+        account: baseAccount({ ack: { timeout: 1000, autoResendOnTimeout: false } }),
+        to: { chatId: "missing-chat", chatType: "direct" },
+        text: "hello",
+      });
+      const frame = decodeSent(client)[0]!;
+
+      emitMessageError(client, frame.trace_id);
+
+      await expect(send).rejects.toThrow(/chat_not_found.*chat not resolvable/);
+      await vi.advanceTimersByTimeAsync(1000);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("ignores unmatched message.error without rejecting unrelated aligned sends", async () => {
+    vi.useFakeTimers();
+    try {
+      const client = mockClient();
+      const logs: string[] = [];
+      const send = sendOpenclawClawlingText({
+        client,
+        account: baseAccount({ ack: { timeout: 1000, autoResendOnTimeout: false } }),
+        to: { chatId: "chat-1", chatType: "direct" },
+        text: "hello",
+        log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      });
+      const frame = decodeSent(client)[0]!;
+
+      emitMessageError(client, "trace-other");
+
+      expect(logs).toContain(
+        "clawchat.ws event=ack_unmatched account_id=default attempt=1 reconnect_count=0 state=ready action=ignore trace_id=trace-other chat_id=missing-chat",
+      );
+
+      await vi.advanceTimersByTimeAsync(999);
+      const pendingOutcome = await Promise.race([
+        send.then(() => "resolved", (err) => err),
+        Promise.resolve("pending"),
+      ]);
+      expect(pendingOutcome).toBe("pending");
+
+      emitAck(client, frame.trace_id, { message_id: "server-m1", accepted_at: 1234 });
+      await expect(send).resolves.toMatchObject({ messageId: "server-m1", acceptedAt: 1234 });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("rejects only the matching aligned send without per-send unmatched logs", async () => {
+    const client = mockClient();
+    const logs: string[] = [];
+    const log = { info: (msg: string) => logs.push(msg), error: (msg: string) => logs.push(msg) };
+    const account = baseAccount({ ack: { timeout: 1000, autoResendOnTimeout: false } });
+
+    const first = sendOpenclawClawlingText({
+      client,
+      account,
+      to: { chatId: "missing-chat", chatType: "direct" },
+      text: "first",
+      log,
+    });
+    const second = sendOpenclawClawlingText({
+      client,
+      account,
+      to: { chatId: "chat-2", chatType: "direct" },
+      text: "second",
+      log,
+    });
+    const [firstFrame, secondFrame] = decodeSent(client);
+
+    emitMessageError(client, firstFrame!.trace_id);
+
+    await expect(first).rejects.toThrow(/chat_not_found.*chat not resolvable/);
+    expect(logs.some((line) => line.includes("event=ack_unmatched"))).toBe(false);
+
+    emitAck(client, secondFrame!.trace_id, { message_id: "server-second", accepted_at: 1234 });
+    await expect(second).resolves.toMatchObject({ messageId: "server-second" });
+  });
+
+  it("does not let core websocket warn after aligned outbound handles message.error", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const transport = new MockTransport();
+      const client = createClawChatClient({
+        url: "ws://test",
+        token: "token-1",
+        deviceId: "agent-1",
+        transport,
+        traceIdFactory: vi.fn()
+          .mockReturnValueOnce("trace-connect")
+          .mockReturnValueOnce("trace-aligned"),
+        ack: { timeout: 1000, autoResendOnTimeout: false },
+        heartbeat: { enabled: false },
+      });
+      await connectReady(transport, client);
+
+      const send = sendOpenclawClawlingText({
+        client,
+        account: baseAccount({ ack: { timeout: 1000, autoResendOnTimeout: false } }),
+        to: { chatId: "missing-chat", chatType: "direct" },
+        text: "hello",
+      });
+      const frame = decodeTransportSent(transport).find((env) => env.event === "message.send")!;
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "message.error",
+        trace_id: frame.trace_id,
+        emitted_at: Date.now(),
+        chat_id: "missing-chat",
+        payload: { code: "chat_not_found", message: "chat not resolvable" },
+      }));
+
+      await expect(send).rejects.toThrow(/chat_not_found.*chat not resolvable/);
+      expect(warn).not.toHaveBeenCalledWith(expect.stringContaining("unmatched message.error"));
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("logs truly unmatched message.error once when aligned tracker is installed", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const transport = new MockTransport();
+      const client = createClawChatClient({
+        url: "ws://test",
+        token: "token-1",
+        deviceId: "agent-1",
+        transport,
+        traceIdFactory: vi.fn()
+          .mockReturnValueOnce("trace-connect")
+          .mockReturnValueOnce("trace-aligned"),
+        ack: { timeout: 1000, autoResendOnTimeout: false },
+        heartbeat: { enabled: false },
+      });
+      await connectReady(transport, client);
+      const logs: string[] = [];
+
+      const aligned = sendOpenclawClawlingText({
+        client,
+        account: baseAccount({ ack: { timeout: 1000, autoResendOnTimeout: false } }),
+        to: { chatId: "chat-aligned", chatType: "direct" },
+        text: "aligned",
+        log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      });
+
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "message.error",
+        trace_id: "trace-unmatched",
+        emitted_at: Date.now(),
+        chat_id: "missing-chat",
+        payload: { code: "chat_not_found", message: "chat not resolvable" },
+      }));
+
+      expect(logs.filter((line) => line.includes("event=ack_unmatched"))).toEqual([
+        "clawchat.ws event=ack_unmatched account_id=default attempt=1 reconnect_count=0 state=ready action=ignore trace_id=trace-unmatched chat_id=missing-chat",
+      ]);
+      expect(warn).not.toHaveBeenCalledWith(expect.stringContaining("unmatched message.error"));
+
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "message.ack",
+        trace_id: "trace-aligned",
+        emitted_at: Date.now(),
+        chat_id: "chat-aligned",
+        payload: { message_id: "server-aligned", accepted_at: 1234 },
+      }));
+      await expect(aligned).resolves.toMatchObject({ messageId: "server-aligned" });
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("does not swallow truly unmatched message.error when tracker was installed without log sink", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const transport = new MockTransport();
+      const client = createClawChatClient({
+        url: "ws://test",
+        token: "token-1",
+        deviceId: "agent-1",
+        transport,
+        traceIdFactory: vi.fn()
+          .mockReturnValueOnce("trace-connect")
+          .mockReturnValueOnce("trace-aligned"),
+        ack: { timeout: 1000, autoResendOnTimeout: false },
+        heartbeat: { enabled: false },
+      });
+      await connectReady(transport, client);
+
+      const aligned = sendOpenclawClawlingText({
+        client,
+        account: baseAccount({ ack: { timeout: 1000, autoResendOnTimeout: false } }),
+        to: { chatId: "chat-aligned", chatType: "direct" },
+        text: "aligned",
+      });
+
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "message.error",
+        trace_id: "trace-unmatched",
+        emitted_at: Date.now(),
+        chat_id: "missing-chat",
+        payload: { code: "chat_not_found", message: "chat not resolvable" },
+      }));
+
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining("unmatched message.error"));
+
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "message.ack",
+        trace_id: "trace-aligned",
+        emitted_at: Date.now(),
+        chat_id: "chat-aligned",
+        payload: { message_id: "server-aligned", accepted_at: 1234 },
+      }));
+      await expect(aligned).resolves.toMatchObject({ messageId: "server-aligned" });
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("does not log aligned unmatched when message.error matches a core pending send", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: vi.fn()
+        .mockReturnValueOnce("trace-connect")
+        .mockReturnValueOnce("trace-aligned")
+        .mockReturnValueOnce("trace-core"),
+      ack: { timeout: 1000, autoResendOnTimeout: false },
+      heartbeat: { enabled: false },
+    });
+    await connectReady(transport, client);
+    const logs: string[] = [];
+
+    const aligned = sendOpenclawClawlingText({
+      client,
+      account: baseAccount({ ack: { timeout: 1000, autoResendOnTimeout: false } }),
+      to: { chatId: "chat-aligned", chatType: "direct" },
+      text: "aligned",
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+    });
+    const core = client.sendAckableEnvelope({
+      eventName: "message.send",
+      chatId: "missing-chat",
+      payload: {
+        message_mode: "normal",
+        message: {
+          body: { fragments: [{ kind: "text", text: "core" }] },
+          context: { mentions: [], reply: null },
+        },
+      },
+    });
+
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "message.error",
+      trace_id: "trace-core",
+      emitted_at: Date.now(),
+      chat_id: "missing-chat",
+      payload: { code: "chat_not_found", message: "chat not resolvable" },
+    }));
+
+    await expect(core).rejects.toThrow(/chat_not_found.*chat not resolvable/);
+    expect(logs.some((line) => line.includes("event=ack_unmatched"))).toBe(false);
+
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "message.ack",
+      trace_id: "trace-aligned",
+      emitted_at: Date.now(),
+      chat_id: "chat-aligned",
+      payload: { message_id: "server-aligned", accepted_at: 1234 },
+    }));
+    await expect(aligned).resolves.toMatchObject({ messageId: "server-aligned" });
+  });
+
+  it("suppresses send when text is empty after trim", async () => {
+    const client = mockClient();
+    const result = await sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "u", chatType: "direct" },
+      text: "   ",
+    });
+    expect(client.sent).toHaveLength(0);
+    expect(result).toBeNull();
+  });
+
+  it("appends mediaFragments after text in body.fragments", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "user-1", chatType: "direct" },
+      text: "look",
+      mediaFragments: [{ kind: "image", url: "https://cdn/x.png", mime: "image/png", size: 12 }],
+    });
+    const frame = decodeSent(client)[0]!;
+    expect((frame.payload as { message: { body: { fragments: unknown[] } } }).message.body.fragments).toEqual([
+      { kind: "text", text: "look" },
+      { kind: "image", url: "https://cdn/x.png", mime: "image/png", size: 12 },
+    ]);
+    emitAck(client, frame.trace_id);
+    await send;
+  });
+
+  it("sends media-only message when text empty but mediaFragments present", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "user-1", chatType: "direct" },
+      text: "",
+      mediaFragments: [{ kind: "image", url: "https://cdn/x.png" }],
+    });
+    const frame = decodeSent(client)[0]!;
+    expect((frame.payload as { message: { body: { fragments: unknown[] } } }).message.body.fragments).toEqual([{ kind: "image", url: "https://cdn/x.png" }]);
+    emitAck(client, frame.trace_id);
+    const result = await send;
+    expect(result?.messageId).toBe("server-m1");
+  });
+
+  it("preserves replyCtx when media fragments are present", async () => {
+    const client = mockClient();
+    const log = { info: vi.fn(), error: vi.fn() };
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "user-1", chatType: "direct" },
+      text: "hi",
+      replyCtx: {
+        replyToMessageId: "m-orig",
+        replyPreviewSenderId: "user-2",
+        replyPreviewNickName: "Sender",
+        replyPreviewText: "original",
+      },
+      mediaFragments: [{ kind: "image", url: "https://cdn/x.png" }],
+      log,
+    });
+    const frame = decodeSent(client)[0]!;
+    const payload = frame.payload as {
+      message: {
+        body: { fragments: unknown[] };
+        context: { reply: { reply_to_msg_id: string; reply_preview: { id: string; nick_name: string } } };
+      };
+    };
+    expect(frame.event).toBe("message.reply");
+    expect(payload.message.context.reply).toMatchObject({
+      reply_to_msg_id: "m-orig",
+      reply_preview: { id: "user-2", nick_name: "Sender" },
+    });
+    expect(payload.message.body.fragments).toEqual([
+      { kind: "text", text: "hi" },
+      { kind: "image", url: "https://cdn/x.png" },
+    ]);
+    emitAck(client, frame.trace_id);
+    await send;
+    expect(log.info).not.toHaveBeenCalledWith(
+      expect.stringMatching(/replyCtx \+ media: downgraded to sendMessage/),
+    );
+  });
+
+  it("suppresses send when both text and mediaFragments are empty", async () => {
+    const client = mockClient();
+    const result = await sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "u", chatType: "direct" },
+      text: "   ",
+      mediaFragments: [],
+    });
+    expect(client.sent).toHaveLength(0);
+    expect(result).toBeNull();
+  });
+
+  it("sendOpenclawClawlingMedia with image and caption sends both fragments", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingMedia({
+      client,
+      account: baseAccount(),
+      to: { chatId: "user-1", chatType: "direct" },
+      text: "look at this",
+      mediaFragments: [{ kind: "image", url: "https://cdn/x.png", mime: "image/png", size: 12 }],
+    });
+    const frame = decodeSent(client)[0]!;
+    expect((frame.payload as { message: { body: { fragments: unknown[] } } }).message.body.fragments).toEqual([
+      { kind: "text", text: "look at this" },
+      { kind: "image", url: "https://cdn/x.png", mime: "image/png", size: 12 },
+    ]);
+    emitAck(client, frame.trace_id);
+    const result = await send;
+    expect(result?.messageId).toBe("server-m1");
+  });
+
+  it("sendOpenclawClawlingMedia with image only (no text) sends just the media fragment", async () => {
+    const client = mockClient();
+    const send = sendOpenclawClawlingMedia({
+      client,
+      account: baseAccount(),
+      to: { chatId: "user-1", chatType: "direct" },
+      mediaFragments: [{ kind: "image", url: "https://cdn/x.png" }],
+    });
+    const frame = decodeSent(client)[0]!;
+    expect((frame.payload as { message: { body: { fragments: unknown[] } } }).message.body.fragments).toEqual([{ kind: "image", url: "https://cdn/x.png" }]);
+    emitAck(client, frame.trace_id);
+    const result = await send;
+    expect(result?.messageId).toBe("server-m1");
+  });
+
+  it("sendOpenclawClawlingMedia returns null and does not send when mediaFragments is empty", async () => {
+    const client = mockClient();
+    const log = { info: vi.fn(), error: vi.fn() };
+    const result = await sendOpenclawClawlingMedia({
+      client,
+      account: baseAccount(),
+      to: { chatId: "u", chatType: "direct" },
+      mediaFragments: [],
+      log,
+    });
+    expect(client.sent).toHaveLength(0);
+    expect(result).toBeNull();
+    expect(log.info).toHaveBeenCalledWith(
+      expect.stringMatching(/sendMedia called with empty mediaFragments/),
+    );
+  });
+
+  it("starts ack timeout only after a queued ackable frame is written", async () => {
+    vi.useFakeTimers();
+    const logs: string[] = [];
+    const client = mockClient({ transportState: "closed" });
+
+    let rejected: unknown;
+    const promise = sendOpenclawClawlingText({
+      client,
+      account: baseAccount({ ack: { timeout: 15000, autoResendOnTimeout: false } }),
+      to: { chatId: "chat-1", chatType: "direct" },
+      text: "hello",
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+    });
+    promise.catch((err) => {
+      rejected = err;
+    });
+
+    await Promise.resolve();
+    await vi.advanceTimersByTimeAsync(15001);
+    expect(rejected).toBeUndefined();
+    expect(client.sent).toHaveLength(0);
+
+    client.setTransportState("open");
+    flushAlignedOutboundQueue(client);
+    expect(client.sent).toHaveLength(1);
+
+    await vi.advanceTimersByTimeAsync(14999);
+    expect(rejected).toBeUndefined();
+    await vi.advanceTimersByTimeAsync(1);
+
+    await expect(promise).rejects.toThrow(/ack timeout/);
+    expect(logs).toContain(
+      "clawchat.ws event=ack_timeout account_id=default attempt=1 reconnect_count=0 state=ready action=reject_no_reconnect event_name=message.send trace_id=trace-1 chat_id=chat-1 timeout_ms=15000",
+    );
+    vi.useRealTimers();
+  });
+
+  it("rejects an ackable send when queue overflow drops it before write", async () => {
+    const logs: string[] = [];
+    const client = mockClient({ transportState: "closed" });
+    const account = baseAccount();
+
+    const first = sendOpenclawClawlingText({
+      client,
+      account,
+      to: { chatId: "chat-1", chatType: "direct" },
+      text: "first",
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+    });
+
+    for (let i = 0; i < 128; i += 1) {
+      sendOpenclawClawlingText({
+        client,
+        account,
+        to: { chatId: "chat-1", chatType: "direct" },
+        text: `queued-${i}`,
+        log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      }).catch(() => {});
+    }
+
+    await Promise.resolve();
+
+    expect(getAlignedOutboundQueueSize(client)).toBe(128);
+    expect(client.listenerCount("close")).toBe(1);
+    await expect(first).rejects.toThrow(/send queue full/);
+    expect(logs.some((line) => line.includes("event=send_queue_drop"))).toBe(true);
+  });
+
+  it("cancels a queued ackable send on terminal close without later flushing it", async () => {
+    const client = mockClient({ transportState: "closed" });
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "chat-1", chatType: "direct" },
+      text: "hello",
+    });
+
+    await Promise.resolve();
+    expect(getAlignedOutboundQueueSize(client)).toBe(1);
+
+    client.emit("close", { code: 1000, reason: "client close" });
+
+    await expect(send).rejects.toThrow(/send cancelled because client close/);
+    expect(getAlignedOutboundQueueSize(client)).toBe(0);
+
+    client.setTransportState("open");
+    flushAlignedOutboundQueue(client);
+    expect(client.sent).toHaveLength(0);
+  });
+
+  it("cancels a queued ackable send on disconnected state without close event", async () => {
+    const client = mockClient({ transportState: "closed" });
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "chat-1", chatType: "direct" },
+      text: "hello",
+    });
+
+    await Promise.resolve();
+    expect(getAlignedOutboundQueueSize(client)).toBe(1);
+
+    client.emit("state", { from: "connected", to: "disconnected" });
+
+    await expect(send).rejects.toThrow(/send cancelled because client disconnected/);
+    expect(getAlignedOutboundQueueSize(client)).toBe(0);
+
+    client.setTransportState("open");
+    flushAlignedOutboundQueue(client);
+    expect(client.sent).toHaveLength(0);
+  });
+
+  it("rejects a new ackable send when the client is already disconnected", async () => {
+    const client = mockClient({ transportState: "closed", state: "disconnected" });
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "chat-1", chatType: "direct" },
+      text: "hello",
+    });
+
+    await expect(send).rejects.toThrow(/send cancelled because client disconnected/);
+    expect(getAlignedOutboundQueueSize(client)).toBe(0);
+    expect(client.sent).toHaveLength(0);
+  });
+
+  it("keeps ackable send pending when a ready-state write fails and resolves after retry", async () => {
+    const client = mockClient();
+    let attempts = 0;
+    client.sendWire = vi.fn((wire: string) => {
+      attempts += 1;
+      if (attempts === 1) throw new Error("socket closed");
+      client.sent.push(wire);
+    }) as ClawlingChatClient["sendWire"];
+
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "chat-1", chatType: "direct" },
+      text: "hello",
+    });
+    const observed = send.then(
+      (result) => ({ status: "resolved" as const, result }),
+      (err: unknown) => ({ status: "rejected" as const, err }),
+    );
+
+    await Promise.resolve();
+
+    expect(getAlignedOutboundQueueSize(client)).toBe(1);
+    expect(client.sent).toHaveLength(0);
+
+    flushAlignedOutboundQueue(client);
+    const frame = decodeSent(client)[0]!;
+    emitAck(client, frame.trace_id, { message_id: "server-retry", accepted_at: 1234 });
+
+    await expect(observed).resolves.toMatchObject({
+      status: "resolved",
+      result: { messageId: "server-retry", acceptedAt: 1234 },
+    });
+    expect(client.sendWire).toHaveBeenCalledTimes(2);
+  });
+
+  it("requeues a written ackable frame on disconnect before ack", async () => {
+    const logs: string[] = [];
+    const client = mockClient();
+
+    const send = sendOpenclawClawlingText({
+      client,
+      account: baseAccount(),
+      to: { chatId: "chat-1", chatType: "direct" },
+      text: "hello",
+      messageId: "local-msg-1",
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+    });
+
+    await Promise.resolve();
+    const firstFrame = decodeSent(client)[0]!;
+    expect(firstFrame.event).toBe("message.send");
+    expect(getAlignedOutboundQueueSize(client)).toBe(0);
+
+    client.setTransportState("closed");
+    client.emit("close", { code: 1006, reason: "network lost" });
+
+    expect(getAlignedOutboundQueueSize(client)).toBe(1);
+
+    client.setTransportState("open");
+    flushAlignedOutboundQueue(client);
+
+    const frames = decodeSent(client);
+    expect(frames).toHaveLength(2);
+    expect(frames[1]).toMatchObject({
+      event: firstFrame.event,
+      trace_id: firstFrame.trace_id,
+      chat_id: firstFrame.chat_id,
+      payload: firstFrame.payload,
+    });
+
+    emitAck(client, firstFrame.trace_id, { message_id: "local-msg-1", accepted_at: 2222 });
+
+    await expect(send).resolves.toMatchObject({
+      messageId: "local-msg-1",
+      acceptedAt: 2222,
+    });
+    expect(logs.some((line) => line.includes("event=send_queued") && line.includes(`trace_id=${firstFrame.trace_id}`))).toBe(true);
+  });
+});