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

package/src/outbound.test.ts

@@ -1,8 +1,16 @@
-import type { ClawlingChatClient } from "@newbase-clawchat/sdk";
+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 { sendOpenclawClawlingMedia, sendOpenclawClawlingText } from "./outbound.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,
+  sendOpenclawClawlingText,
+} from "./outbound.ts";
 
 function baseAccount(
   overrides: Partial<ResolvedOpenclawClawlingAccount> = {},
@@ -16,6 +24,7 @@ function baseAccount(
     baseUrl: "",
     token: "tk",
     userId: "agent-1",
+    ownerUserId: "owner-1",
     replyMode: "static",
     forwardThinking: true,
     forwardToolCalls: false,
@@ -33,49 +42,120 @@ function baseAccount(
   };
 }
 
-function mockClient() {
-  return {
-    sendMessage: vi.fn().mockResolvedValue({
-      version: "2",
-      event: "message.ack",
-      trace_id: "trace-ack",
-      emitted_at: Date.now(),
-      payload: { message_id: "server-m1", accepted_at: 1234 },
-    }),
-    replyMessage: vi.fn().mockResolvedValue({
-      version: "2",
-      event: "message.ack",
-      trace_id: "trace-ack-r",
-      emitted_at: Date.now(),
-      payload: { message_id: "server-r1", accepted_at: 5678 },
+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(),
-  } as unknown as ClawlingChatClient;
+    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("openclaw-clawchat outbound", () => {
-  it("routes to sendMessage when no replyCtx", async () => {
+  it("sends message.send when no replyCtx", async () => {
     const client = mockClient();
-    const result = await sendOpenclawClawlingText({
+    const send = sendOpenclawClawlingText({
       client,
       account: baseAccount(),
       to: { chatId: "user-1", chatType: "direct" },
       text: "hello",
     });
-    expect((client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]).toMatchObject({
+    const frame = decodeSent(client)[0]!;
+    expect(frame).toMatchObject({
+      event: "message.send",
       chat_id: "user-1",
-      body: { fragments: [{ kind: "text", text: "hello" }] },
+      payload: {
+        message: { body: { fragments: [{ kind: "text", text: "hello" }] } },
+      },
     });
-    expect((client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]).not.toHaveProperty("chat_type");
-    expect(client.replyMessage).not.toHaveBeenCalled();
+    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("routes to replyMessage when replyCtx is provided", async () => {
+  it("sends message.reply when replyCtx is provided", async () => {
     const client = mockClient();
-    await sendOpenclawClawlingText({
+    const send = sendOpenclawClawlingText({
       client,
       account: baseAccount(),
       to: { chatId: "chat-1", chatType: "direct" },
@@ -88,18 +168,346 @@ describe("openclaw-clawchat outbound", () => {
         replyPreviewText: "original",
       },
     });
-    expect((client.replyMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]).toMatchObject({
+    const frame = decodeSent(client)[0]!;
+    expect(frame).toMatchObject({
+      event: "message.reply",
       chat_id: "chat-1",
-      replyTo: {
-        msgId: "m-orig",
-        senderId: "chat-1",
-        nickName: "Sender",
-        fragments: [{ kind: "text", text: "original" }],
+      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" }],
+              },
+            },
+          },
+        },
       },
-      body: { fragments: [{ kind: "text", text: "reply" }] },
     });
-    expect((client.replyMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]).not.toHaveProperty("chat_type");
-    expect(client.sendMessage).not.toHaveBeenCalled();
+    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 () => {
@@ -110,60 +518,48 @@ describe("openclaw-clawchat outbound", () => {
       to: { chatId: "u", chatType: "direct" },
       text: "   ",
     });
-    expect(client.sendMessage).not.toHaveBeenCalled();
-    expect(client.replyMessage).not.toHaveBeenCalled();
+    expect(client.sent).toHaveLength(0);
     expect(result).toBeNull();
   });
 
-  it("propagates SDK errors", async () => {
-    const client = {
-      ...mockClient(),
-      sendMessage: vi.fn().mockRejectedValue(new Error("boom")),
-    } as unknown as ClawlingChatClient;
-    await expect(
-      sendOpenclawClawlingText({
-        client,
-        account: baseAccount(),
-        to: { chatId: "u", chatType: "direct" },
-        text: "hi",
-      }),
-    ).rejects.toThrow("boom");
-  });
-
   it("appends mediaFragments after text in body.fragments", async () => {
     const client = mockClient();
-    await sendOpenclawClawlingText({
+    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 callArg = (client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0];
-    expect(callArg.body.fragments).toEqual([
+    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 result = await sendOpenclawClawlingText({
+    const send = sendOpenclawClawlingText({
       client,
       account: baseAccount(),
       to: { chatId: "user-1", chatType: "direct" },
       text: "",
       mediaFragments: [{ kind: "image", url: "https://cdn/x.png" }],
     });
-    const callArg = (client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0];
-    expect(callArg.body.fragments).toEqual([{ 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("downgrades replyCtx + media to sendMessage", async () => {
+  it("preserves replyCtx when media fragments are present", async () => {
     const client = mockClient();
     const log = { info: vi.fn(), error: vi.fn() };
-    await sendOpenclawClawlingText({
+    const send = sendOpenclawClawlingText({
       client,
       account: baseAccount(),
       to: { chatId: "user-1", chatType: "direct" },
@@ -177,9 +573,25 @@ describe("openclaw-clawchat outbound", () => {
       mediaFragments: [{ kind: "image", url: "https://cdn/x.png" }],
       log,
     });
-    expect(client.replyMessage).not.toHaveBeenCalled();
-    expect(client.sendMessage).toHaveBeenCalled();
-    expect(log.info).toHaveBeenCalledWith(
+    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/),
     );
   });
@@ -193,41 +605,45 @@ describe("openclaw-clawchat outbound", () => {
       text: "   ",
       mediaFragments: [],
     });
-    expect(client.sendMessage).not.toHaveBeenCalled();
+    expect(client.sent).toHaveLength(0);
     expect(result).toBeNull();
   });
 
   it("sendOpenclawClawlingMedia with image and caption sends both fragments", async () => {
     const client = mockClient();
-    const result = await sendOpenclawClawlingMedia({
+    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 callArg = (client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0];
-    expect(callArg.body.fragments).toEqual([
+    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 result = await sendOpenclawClawlingMedia({
+    const send = sendOpenclawClawlingMedia({
       client,
       account: baseAccount(),
       to: { chatId: "user-1", chatType: "direct" },
       mediaFragments: [{ kind: "image", url: "https://cdn/x.png" }],
     });
-    const callArg = (client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0];
-    expect(callArg.body.fragments).toEqual([{ 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 call SDK when mediaFragments is empty", async () => {
+  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({
@@ -237,11 +653,216 @@ describe("openclaw-clawchat outbound", () => {
       mediaFragments: [],
       log,
     });
-    expect(client.sendMessage).not.toHaveBeenCalled();
-    expect(client.replyMessage).not.toHaveBeenCalled();
+    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);
+  });
 });