@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/ws-client.test.ts

@@ -0,0 +1,1217 @@
+import { describe, expect, it, vi } from "vitest";
+import { MockTransport } from "./mock-transport.ts";
+import { createClawChatClient, createWebSocketTransport } from "./ws-client.ts";
+import { AuthError, EVENT, ProtocolError, TransportError, type Envelope } from "./protocol-types.ts";
+
+function decodeSent(transport: MockTransport) {
+  return transport.sent.map((raw) => JSON.parse(raw) as Envelope);
+}
+
+async function connectReady(transport: MockTransport, client: ReturnType<typeof createClawChatClient>) {
+  const connected = client.connect();
+  const connectFrame = await completeHandshake(transport);
+  await connected;
+  return connectFrame;
+}
+
+async function completeHandshake(transport: MockTransport) {
+  transport.emitInbound(JSON.stringify({
+    version: "2",
+    event: "connect.challenge",
+    trace_id: "challenge-1",
+    emitted_at: Date.now(),
+    payload: { nonce: "nonce-1" },
+  }));
+  const connectFrame = decodeSent(transport).find((env) => env.event === 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" },
+  }));
+  return connectFrame;
+}
+
+describe("createWebSocketTransport", () => {
+  it("adapts a WebSocket constructor to the local transport interface", async () => {
+    class FakeWebSocket {
+      static instances: FakeWebSocket[] = [];
+      readonly listeners = new Map<string, Array<(event?: unknown) => void>>();
+      readonly send = vi.fn();
+      readonly close = vi.fn((code?: number, reason?: string) => {
+        this.emit("close", { code, reason });
+      });
+
+      constructor(readonly url: string) {
+        FakeWebSocket.instances.push(this);
+      }
+
+      addEventListener(type: string, listener: (event?: unknown) => void): void {
+        this.listeners.set(type, [...(this.listeners.get(type) ?? []), listener]);
+      }
+
+      emit(type: string, event?: unknown): void {
+        for (const listener of this.listeners.get(type) ?? []) listener(event);
+      }
+    }
+
+    const transport = createWebSocketTransport(FakeWebSocket);
+    const onOpen = vi.fn();
+    const onMessage = vi.fn();
+    const onClose = vi.fn();
+    const onError = vi.fn();
+    const connected = transport.connect("ws://test", { onOpen, onMessage, onClose, onError });
+    const socket = FakeWebSocket.instances[0]!;
+
+    expect(transport.state).toBe("connecting");
+    socket.emit("open");
+    await connected;
+    expect(transport.state).toBe("open");
+    expect(onOpen).toHaveBeenCalledTimes(1);
+
+    transport.send("frame-1");
+    expect(socket.send).toHaveBeenCalledWith("frame-1");
+
+    socket.emit("message", { data: "frame-2" });
+    expect(onMessage).toHaveBeenCalledWith("frame-2");
+
+    transport.close(1000, "done");
+    expect(onClose).toHaveBeenCalledWith(1000, "done");
+    expect(transport.state).toBe("closed");
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it("rejects when the socket closes before opening", async () => {
+    class FakeWebSocket {
+      static instances: FakeWebSocket[] = [];
+      readonly listeners = new Map<string, Array<(event?: unknown) => void>>();
+      readonly send = vi.fn();
+      readonly close = vi.fn();
+
+      constructor(readonly url: string) {
+        FakeWebSocket.instances.push(this);
+      }
+
+      addEventListener(type: string, listener: (event?: unknown) => void): void {
+        this.listeners.set(type, [...(this.listeners.get(type) ?? []), listener]);
+      }
+
+      emit(type: string, event?: unknown): void {
+        for (const listener of this.listeners.get(type) ?? []) listener(event);
+      }
+    }
+
+    const transport = createWebSocketTransport(FakeWebSocket);
+    const connected = transport.connect("ws://test", {
+      onOpen: vi.fn(),
+      onMessage: vi.fn(),
+      onClose: vi.fn(),
+      onError: vi.fn(),
+    });
+    FakeWebSocket.instances[0]!.emit("close", { code: 1006, reason: "dial failed" });
+
+    await expect(connected).rejects.toThrow("dial failed");
+    expect(transport.state).toBe("closed");
+  });
+});
+
+describe("createClawChatClient", () => {
+  it("sends the msghub connect payload from the protocol reference", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-connect",
+    });
+
+    const connectFrame = await connectReady(transport, client);
+    expect(connectFrame).toMatchObject({
+      version: "2",
+      event: "connect",
+      trace_id: "trace-connect",
+      payload: {
+        token: "token-1",
+        nonce: "nonce-1",
+        device_id: "agent-1",
+        capabilities: { multi_device: true, device_replay: true, chat_meta_events: true },
+      },
+    });
+    expect(client.state).toBe("connected");
+  });
+
+  it("answers JSON ping with JSON pong", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-1",
+    });
+    await connectReady(transport, client);
+    transport.sent.length = 0;
+
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "ping",
+      trace_id: "ping-1",
+      emitted_at: 1776162600000,
+      payload: {},
+    }));
+
+    expect(decodeSent(transport)).toContainEqual(expect.objectContaining({
+      event: "pong",
+      trace_id: "ping-1",
+      emitted_at: 1776162600000,
+      payload: {},
+    }));
+  });
+
+  it("emits hello-ok with resolved device id and delivery mode", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-configured",
+      transport,
+      traceIdFactory: () => "trace-connect",
+      heartbeat: { enabled: false },
+    });
+    const helloOk = vi.fn();
+    client.on("hello:ok", helloOk);
+
+    await connectReady(transport, client);
+
+    expect(helloOk).toHaveBeenCalledWith(expect.objectContaining({
+      event: "hello-ok",
+      payload: { device_id: "agent-1", delivery_mode: "device_replay" },
+    }));
+  });
+
+  it("emits metadata invalidation events", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-1",
+      heartbeat: { enabled: false },
+    });
+    const invalidated = vi.fn();
+    client.on("metadata:invalidated", invalidated);
+    await connectReady(transport, client);
+
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "chat.metadata.invalidated",
+      trace_id: "meta-1",
+      emitted_at: Date.now(),
+      chat_id: "group-1",
+      chat_type: "group",
+      payload: { scope: ["title"], version: 7, updated_at: 1776163000000 },
+    }));
+
+    expect(invalidated).toHaveBeenCalledWith(expect.objectContaining({
+      event: "chat.metadata.invalidated",
+      chat_id: "group-1",
+      payload: { scope: ["title"], version: 7, updated_at: 1776163000000 },
+    }));
+  });
+
+  it("tolerates presence events without presence-specific helper events", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-1",
+      heartbeat: { enabled: false },
+    });
+    const error = vi.fn();
+    const presence = vi.fn();
+    const presenceSnapshot = vi.fn();
+    const presenceUpdate = vi.fn();
+    client.on("error", error);
+    client.on("presence", presence);
+    client.on("presence:snapshot", presenceSnapshot);
+    client.on("presence:update", presenceUpdate);
+    await connectReady(transport, client);
+
+    for (const event of ["presence.snapshot", "presence.update"]) {
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event,
+        trace_id: `trace-${event}`,
+        emitted_at: Date.now(),
+        payload: { user_id: "usr_bob", online: true, last_seen_at: "2026-05-13T12:35:00Z" },
+      }));
+    }
+
+    expect(error).not.toHaveBeenCalled();
+    expect(presence).not.toHaveBeenCalled();
+    expect(presenceSnapshot).not.toHaveBeenCalled();
+    expect(presenceUpdate).not.toHaveBeenCalled();
+  });
+
+  it("emits materialized messages through the message event", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-1",
+    });
+    const messages: Envelope[] = [];
+    client.on("message", (env) => messages.push(env));
+    await connectReady(transport, client);
+
+    for (const event of [EVENT.MESSAGE_SEND, EVENT.MESSAGE_REPLY, EVENT.MESSAGE_DONE]) {
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event,
+        trace_id: `trace-${event}`,
+        emitted_at: Date.now(),
+        chat_id: "chat-1",
+        chat_type: "direct",
+        sender: { id: "user-1", type: "direct", nick_name: "User" },
+        payload: event === EVENT.MESSAGE_DONE
+          ? {
+              message_id: `msg-${event}`,
+              fragments: [{ kind: "text", text: "done text" }],
+              streaming: { status: "done", sequence: 1, mutation_policy: "append_text_only", started_at: null, completed_at: Date.now() },
+            }
+          : {
+              message_id: `msg-${event}`,
+              message_mode: "normal",
+              message: {
+                body: { fragments: [{ kind: "text", text: "hello" }] },
+                context: { mentions: [], reply: null },
+                streaming: { status: "static", sequence: 0, mutation_policy: "sealed", started_at: null, completed_at: null },
+              },
+            },
+      }));
+    }
+
+    expect(messages.map((env) => env.event)).toEqual([
+      EVENT.MESSAGE_SEND,
+      EVENT.MESSAGE_REPLY,
+    ]);
+  });
+
+  it("sends typing.update with is_typing", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-typing",
+    });
+    await connectReady(transport, client);
+    transport.sent.length = 0;
+
+    client.typing("chat-1", true);
+
+    expect(decodeSent(transport)).toContainEqual(expect.objectContaining({
+      event: "typing.update",
+      chat_id: "chat-1",
+      payload: { is_typing: true },
+    }));
+  });
+
+  it("resolves ackable sends from matching message.ack", 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-send"),
+      ack: { timeout: 1000, autoResendOnTimeout: false },
+    });
+    await connectReady(transport, client);
+
+    const send = client.sendAckableEnvelope({
+      eventName: "message.send",
+      chatId: "chat-1",
+      payload: {
+        message_mode: "normal",
+        message: {
+          body: { fragments: [{ kind: "text", text: "hello" }] },
+          context: { mentions: [], reply: null },
+        },
+      },
+    });
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "message.ack",
+      trace_id: "trace-send",
+      emitted_at: Date.now(),
+      chat_id: "chat-1",
+      payload: { message_id: "msg-1", accepted_at: 1776162600000 },
+    }));
+
+    await expect(send).resolves.toMatchObject({ payload: { message_id: "msg-1" } });
+  });
+
+  it("rejects ackable sends from matching message.error", async () => {
+    vi.useFakeTimers();
+    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-send"),
+        ack: { timeout: 1000, autoResendOnTimeout: false },
+        heartbeat: { enabled: false },
+      });
+      await connectReady(transport, client);
+
+      const send = client.sendAckableEnvelope({
+        eventName: "message.send",
+        chatId: "missing-chat",
+        payload: {
+          message_mode: "normal",
+          message: {
+            body: { fragments: [{ kind: "text", text: "hello" }] },
+            context: { mentions: [], reply: null },
+          },
+        },
+      });
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "message.error",
+        trace_id: "trace-send",
+        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/);
+      await vi.advanceTimersByTimeAsync(1000);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("ignores unmatched message.error without rejecting unrelated pending sends", async () => {
+    vi.useFakeTimers();
+    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-send"),
+        ack: { timeout: 1000, autoResendOnTimeout: false },
+        heartbeat: { enabled: false },
+      });
+      await connectReady(transport, client);
+
+      const send = client.sendAckableEnvelope({
+        eventName: "message.send",
+        chatId: "chat-1",
+        payload: {
+          message_mode: "normal",
+          message: {
+            body: { fragments: [{ kind: "text", text: "hello" }] },
+            context: { mentions: [], reply: null },
+          },
+        },
+      });
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "message.error",
+        trace_id: "trace-other",
+        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"));
+
+      await vi.advanceTimersByTimeAsync(999);
+      const pendingOutcome = await Promise.race([
+        send.then(() => "resolved", (err) => err),
+        Promise.resolve("pending"),
+      ]);
+      expect(pendingOutcome).toBe("pending");
+
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "message.ack",
+        trace_id: "trace-send",
+        emitted_at: Date.now(),
+        chat_id: "chat-1",
+        payload: { message_id: "msg-1", accepted_at: 1776162600000 },
+      }));
+      await expect(send).resolves.toMatchObject({ payload: { message_id: "msg-1" } });
+    } finally {
+      warn.mockRestore();
+      vi.useRealTimers();
+    }
+  });
+
+  it("resends ackable sends on timeout when explicitly enabled", async () => {
+    vi.useFakeTimers();
+    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-send"),
+        ack: { timeout: 50, autoResendOnTimeout: true },
+        heartbeat: { enabled: false },
+      });
+      await connectReady(transport, client);
+      transport.sent.length = 0;
+
+      const send = client.sendAckableEnvelope({
+        eventName: "message.send",
+        chatId: "chat-1",
+        payload: {
+          message_mode: "normal",
+          message: {
+            body: { fragments: [{ kind: "text", text: "hello" }] },
+            context: { mentions: [], reply: null },
+          },
+        },
+      });
+      await vi.advanceTimersByTimeAsync(50);
+      expect(transport.sent).toHaveLength(2);
+
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "message.ack",
+        trace_id: "trace-send",
+        emitted_at: Date.now(),
+        chat_id: "chat-1",
+        payload: { message_id: "msg-1", accepted_at: 1776162600000 },
+      }));
+      await expect(send).resolves.toMatchObject({ payload: { message_id: "msg-1" } });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("keeps reconnecting when the initial transport connect fails", async () => {
+    vi.useFakeTimers();
+    try {
+      class FailingOnceTransport extends MockTransport {
+        attempts = 0;
+
+        override async connect(url: string, handlers: Parameters<MockTransport["connect"]>[1]): Promise<void> {
+          this.attempts += 1;
+          if (this.attempts === 1) throw new Error("dial failed");
+          return await super.connect(url, handlers);
+        }
+      }
+      const transport = new FailingOnceTransport();
+      const client = createClawChatClient({
+        url: "ws://test",
+        token: "token-1",
+        deviceId: "agent-1",
+        transport,
+        traceIdFactory: () => "trace-1",
+        reconnect: { enabled: true, initialDelay: 50, maxDelay: 50, maxRetries: 2, jitterRatio: 0 },
+        heartbeat: { enabled: false },
+      });
+
+      const connected = client.connect();
+      await vi.advanceTimersByTimeAsync(50);
+      expect(transport.attempts).toBe(2);
+      await completeHandshake(transport);
+
+      await expect(connected).resolves.toBeUndefined();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("continues reconnecting after consecutive transport connect failures", async () => {
+    vi.useFakeTimers();
+    try {
+      class FailingTwiceTransport extends MockTransport {
+        attempts = 0;
+
+        override async connect(url: string, handlers: Parameters<MockTransport["connect"]>[1]): Promise<void> {
+          this.attempts += 1;
+          if (this.attempts <= 2) throw new Error(`dial failed ${this.attempts}`);
+          return await super.connect(url, handlers);
+        }
+      }
+      const transport = new FailingTwiceTransport();
+      const client = createClawChatClient({
+        url: "ws://test",
+        token: "token-1",
+        deviceId: "agent-1",
+        transport,
+        traceIdFactory: () => "trace-1",
+        reconnect: { enabled: true, initialDelay: 50, maxDelay: 50, maxRetries: 3, jitterRatio: 0 },
+        heartbeat: { enabled: false },
+      });
+
+      const connected = client.connect();
+      await vi.advanceTimersByTimeAsync(50);
+      expect(transport.attempts).toBe(2);
+      await vi.advanceTimersByTimeAsync(50);
+      expect(transport.attempts).toBe(3);
+      await completeHandshake(transport);
+
+      await expect(connected).resolves.toBeUndefined();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("queues raw sends while reconnecting and flushes them after reconnect", async () => {
+    vi.useFakeTimers();
+    try {
+      const transport = new MockTransport();
+      const client = createClawChatClient({
+        url: "ws://test",
+        token: "token-1",
+        deviceId: "agent-1",
+        transport,
+        traceIdFactory: vi.fn()
+          .mockReturnValueOnce("trace-connect-1")
+          .mockReturnValueOnce("trace-queued")
+          .mockReturnValueOnce("trace-connect-2"),
+        reconnect: { enabled: true, initialDelay: 50, maxDelay: 50, maxRetries: 2, jitterRatio: 0 },
+        heartbeat: { enabled: false },
+      });
+      await connectReady(transport, client);
+      transport.sent.length = 0;
+
+      transport.close(1006, "network lost");
+      expect(client.state).toBe("reconnecting");
+
+      expect(() => client.emitRaw("message.created", { message_id: "msg-1" }, { chat_id: "chat-1" })).not.toThrow();
+      expect(transport.sent).toHaveLength(0);
+
+      await vi.advanceTimersByTimeAsync(50);
+      await completeHandshake(transport);
+
+      expect(decodeSent(transport)).toEqual([
+        expect.objectContaining({ event: EVENT.CONNECT, trace_id: "trace-connect-2" }),
+        expect.objectContaining({
+          event: "message.created",
+          trace_id: "trace-queued",
+          chat_id: "chat-1",
+          payload: { message_id: "msg-1" },
+        }),
+      ]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("queues raw sends during reconnect handshake until hello-ok", async () => {
+    vi.useFakeTimers();
+    try {
+      const transport = new MockTransport();
+      const client = createClawChatClient({
+        url: "ws://test",
+        token: "token-1",
+        deviceId: "agent-1",
+        transport,
+        traceIdFactory: vi.fn()
+          .mockReturnValueOnce("trace-connect-1")
+          .mockReturnValueOnce("trace-queued")
+          .mockReturnValueOnce("trace-connect-2"),
+        reconnect: { enabled: true, initialDelay: 50, maxDelay: 50, maxRetries: 2, jitterRatio: 0 },
+        heartbeat: { enabled: false },
+      });
+      await connectReady(transport, client);
+      transport.sent.length = 0;
+
+      transport.close(1006, "network lost");
+      await vi.advanceTimersByTimeAsync(50);
+      expect(client.state).toBe("challenging");
+
+      expect(() => client.emitRaw("message.created", { message_id: "msg-1" }, { chat_id: "chat-1" })).not.toThrow();
+      expect(transport.sent).toHaveLength(0);
+
+      await completeHandshake(transport);
+
+      expect(decodeSent(transport)).toEqual([
+        expect.objectContaining({ event: EVENT.CONNECT, trace_id: "trace-connect-2" }),
+        expect.objectContaining({
+          event: "message.created",
+          trace_id: "trace-queued",
+          chat_id: "chat-1",
+          payload: { message_id: "msg-1" },
+        }),
+      ]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("schedules only one reconnect for websocket error followed by close before open", async () => {
+    vi.useFakeTimers();
+    try {
+      class FakeWebSocket {
+        static instances: FakeWebSocket[] = [];
+        readonly listeners = new Map<string, Array<(event?: unknown) => void>>();
+        readonly send = vi.fn();
+        readonly close = vi.fn();
+
+        constructor(readonly url: string) {
+          FakeWebSocket.instances.push(this);
+        }
+
+        addEventListener(type: string, listener: (event?: unknown) => void): void {
+          this.listeners.set(type, [...(this.listeners.get(type) ?? []), listener]);
+        }
+
+        emit(type: string, event?: unknown): void {
+          for (const listener of this.listeners.get(type) ?? []) listener(event);
+        }
+      }
+      const transport = createWebSocketTransport(FakeWebSocket);
+      const client = createClawChatClient({
+        url: "ws://test",
+        token: "token-1",
+        deviceId: "agent-1",
+        transport,
+        traceIdFactory: () => "trace-1",
+        reconnect: { enabled: true, initialDelay: 50, maxDelay: 50, maxRetries: 2, jitterRatio: 0 },
+        heartbeat: { enabled: false },
+      });
+      const scheduled = vi.fn();
+      client.on("reconnect:scheduled", scheduled);
+
+      void client.connect();
+      const socket = FakeWebSocket.instances[0]!;
+      socket.emit("error", new Error("dial failed"));
+      await Promise.resolve();
+      socket.emit("close", { code: 1006, reason: "dial failed" });
+
+      expect(scheduled).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("ignores stale close events from an old websocket after reconnect starts", async () => {
+    vi.useFakeTimers();
+    try {
+      class FakeWebSocket {
+        static instances: FakeWebSocket[] = [];
+        readonly listeners = new Map<string, Array<(event?: unknown) => void>>();
+        readonly sent: string[] = [];
+        readonly send = vi.fn((wire: string) => this.sent.push(wire));
+        readonly close = vi.fn();
+
+        constructor(readonly url: string) {
+          FakeWebSocket.instances.push(this);
+        }
+
+        addEventListener(type: string, listener: (event?: unknown) => void): void {
+          this.listeners.set(type, [...(this.listeners.get(type) ?? []), listener]);
+        }
+
+        emit(type: string, event?: unknown): void {
+          for (const listener of this.listeners.get(type) ?? []) listener(event);
+        }
+      }
+      const transport = createWebSocketTransport(FakeWebSocket);
+      const client = createClawChatClient({
+        url: "ws://test",
+        token: "token-1",
+        deviceId: "agent-1",
+        transport,
+        traceIdFactory: () => "trace-connect",
+        reconnect: { enabled: true, initialDelay: 50, maxDelay: 50, maxRetries: 2, jitterRatio: 0 },
+        heartbeat: { enabled: false },
+      });
+      const scheduled = vi.fn();
+      client.on("reconnect:scheduled", scheduled);
+      const connected = client.connect();
+      const oldSocket = FakeWebSocket.instances[0]!;
+      oldSocket.emit("open");
+      oldSocket.emit("message", { data: JSON.stringify({ version: "2", event: "connect.challenge", trace_id: "challenge-1", emitted_at: Date.now(), payload: { nonce: "nonce-1" } }) });
+      oldSocket.emit("message", { data: JSON.stringify({ version: "2", event: "hello-ok", trace_id: "trace-connect", emitted_at: Date.now(), payload: {} }) });
+      await connected;
+
+      oldSocket.emit("close", { code: 1006, reason: "network lost" });
+      await vi.advanceTimersByTimeAsync(50);
+      const newSocket = FakeWebSocket.instances[1]!;
+      newSocket.emit("open");
+      expect(transport.state).toBe("open");
+
+      oldSocket.emit("close", { code: 1006, reason: "late close" });
+
+      expect(transport.state).toBe("open");
+      expect(scheduled).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("ignores stale messages from a closed websocket during reconnect delay", async () => {
+    vi.useFakeTimers();
+    try {
+      class FakeWebSocket {
+        static instances: FakeWebSocket[] = [];
+        readonly listeners = new Map<string, Array<(event?: unknown) => void>>();
+        readonly sent: string[] = [];
+        readonly send = vi.fn((wire: string) => this.sent.push(wire));
+        readonly close = vi.fn();
+
+        constructor(readonly url: string) {
+          FakeWebSocket.instances.push(this);
+        }
+
+        addEventListener(type: string, listener: (event?: unknown) => void): void {
+          this.listeners.set(type, [...(this.listeners.get(type) ?? []), listener]);
+        }
+
+        emit(type: string, event?: unknown): void {
+          for (const listener of this.listeners.get(type) ?? []) listener(event);
+        }
+      }
+      const transport = createWebSocketTransport(FakeWebSocket);
+      const client = createClawChatClient({
+        url: "ws://test",
+        token: "token-1",
+        deviceId: "agent-1",
+        transport,
+        traceIdFactory: () => "trace-connect",
+        reconnect: { enabled: true, initialDelay: 50, maxDelay: 50, maxRetries: 2, jitterRatio: 0 },
+        heartbeat: { enabled: false },
+      });
+      const connected = client.connect();
+      const oldSocket = FakeWebSocket.instances[0]!;
+      oldSocket.emit("open");
+      oldSocket.emit("message", { data: JSON.stringify({ version: "2", event: "connect.challenge", trace_id: "challenge-1", emitted_at: Date.now(), payload: { nonce: "nonce-1" } }) });
+      oldSocket.emit("message", { data: JSON.stringify({ version: "2", event: "hello-ok", trace_id: "trace-connect", emitted_at: Date.now(), payload: {} }) });
+      await connected;
+
+      oldSocket.emit("close", { code: 1006, reason: "network lost" });
+      oldSocket.emit("message", { data: JSON.stringify({ version: "2", event: "hello-fail", trace_id: "trace-connect", emitted_at: Date.now(), payload: { reason: "late" } }) });
+      expect(client.state).toBe("reconnecting");
+
+      await vi.advanceTimersByTimeAsync(50);
+      expect(FakeWebSocket.instances).toHaveLength(2);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("ignores duplicate challenges after the client is connected", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-connect",
+      heartbeat: { enabled: false },
+    });
+    await connectReady(transport, client);
+    const sentCount = transport.sent.length;
+
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "connect.challenge",
+      trace_id: "challenge-late",
+      emitted_at: Date.now(),
+      payload: { nonce: "late-nonce" },
+    }));
+
+    expect(client.state).toBe("connected");
+    expect(transport.sent).toHaveLength(sentCount);
+  });
+
+  it("rejects connect when sending the challenge response fails", async () => {
+    class SendFailTransport extends MockTransport {
+      override send(data: string): void {
+        const env = JSON.parse(data) as Envelope;
+        if (env.event === EVENT.CONNECT) throw new Error("send failed");
+        super.send(data);
+      }
+    }
+    const transport = new SendFailTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-connect",
+      heartbeat: { enabled: false },
+    });
+    const connected = client.connect();
+
+    expect(() => transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "connect.challenge",
+      trace_id: "challenge-1",
+      emitted_at: Date.now(),
+      payload: { nonce: "nonce-1" },
+    }))).not.toThrow();
+    await expect(connected).rejects.toThrow("send failed");
+    expect(client.state).toBe("disconnected");
+  });
+
+  it("cleans up terminal hello-fail authentication failures", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-connect",
+      heartbeat: { enabled: false },
+    });
+    const connected = client.connect();
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "connect.challenge",
+      trace_id: "challenge-1",
+      emitted_at: Date.now(),
+      payload: { nonce: "nonce-1" },
+    }));
+
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "hello-fail",
+      trace_id: "trace-connect",
+      emitted_at: Date.now(),
+      payload: { reason: "authentication failed" },
+    }));
+
+    await expect(connected).rejects.toBeInstanceOf(AuthError);
+    expect(client.state).toBe("disconnected");
+    expect(transport.state).toBe("closed");
+  });
+
+  it("rejects malformed hello-fail payloads", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-connect",
+      heartbeat: { enabled: false },
+    });
+    const connected = client.connect();
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "connect.challenge",
+      trace_id: "challenge-1",
+      emitted_at: Date.now(),
+      payload: { nonce: "nonce-1" },
+    }));
+
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "hello-fail",
+      trace_id: "trace-connect",
+      emitted_at: Date.now(),
+      payload: null,
+    }));
+
+    await expect(connected).rejects.toBeInstanceOf(ProtocolError);
+    expect(client.state).toBe("disconnected");
+  });
+
+  it("rejects hello-ok before the connect frame is sent", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-connect",
+      heartbeat: { enabled: false },
+    });
+    const connected = client.connect();
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "hello-ok",
+      trace_id: "trace-connect",
+      emitted_at: Date.now(),
+      payload: {},
+    }));
+
+    await expect(connected).rejects.toBeInstanceOf(ProtocolError);
+    expect(client.state).toBe("disconnected");
+  });
+
+  it("rejects hello-ok with a mismatched connect trace", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-connect",
+      heartbeat: { enabled: false },
+    });
+    const connected = client.connect();
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "connect.challenge",
+      trace_id: "challenge-1",
+      emitted_at: Date.now(),
+      payload: { nonce: "nonce-1" },
+    }));
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "hello-ok",
+      trace_id: "wrong-trace",
+      emitted_at: Date.now(),
+      payload: {},
+    }));
+
+    await expect(connected).rejects.toBeInstanceOf(ProtocolError);
+    expect(client.state).toBe("disconnected");
+  });
+
+  it("rejects hello-ok with a malformed payload", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-connect",
+      heartbeat: { enabled: false },
+    });
+    const connected = client.connect();
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "connect.challenge",
+      trace_id: "challenge-1",
+      emitted_at: Date.now(),
+      payload: { nonce: "nonce-1" },
+    }));
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "hello-ok",
+      trace_id: "trace-connect",
+      emitted_at: Date.now(),
+      payload: null,
+    }));
+
+    await expect(connected).rejects.toBeInstanceOf(ProtocolError);
+    expect(client.state).toBe("disconnected");
+  });
+
+  it("rejects handshake envelopes missing required envelope fields", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-connect",
+      heartbeat: { enabled: false },
+    });
+    const connected = client.connect();
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "hello-ok",
+      emitted_at: Date.now(),
+      payload: {},
+    }));
+
+    const outcome = await Promise.race([
+      connected.then(() => "resolved", (err) => err),
+      new Promise((resolve) => setTimeout(() => resolve("pending"), 0)),
+    ]);
+    expect(outcome).toBeInstanceOf(ProtocolError);
+    expect(client.state).toBe("disconnected");
+  });
+
+  it("rejects malformed challenge frames instead of leaving connect pending", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-connect",
+      heartbeat: { enabled: false },
+    });
+    const connected = client.connect();
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "connect.challenge",
+      trace_id: "challenge-1",
+      emitted_at: Date.now(),
+      payload: {},
+    }));
+
+    const outcome = await Promise.race([
+      connected.then(() => "resolved", (err) => err),
+      new Promise((resolve) => setTimeout(() => resolve("pending"), 0)),
+    ]);
+    expect(outcome).toBeInstanceOf(ProtocolError);
+    expect(client.state).toBe("disconnected");
+  });
+
+  it("rejects null challenge payloads as protocol errors", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-connect",
+      heartbeat: { enabled: false },
+    });
+    const connected = client.connect();
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "connect.challenge",
+      trace_id: "challenge-1",
+      emitted_at: Date.now(),
+      payload: null,
+    }));
+
+    await expect(connected).rejects.toBeInstanceOf(ProtocolError);
+    expect(client.state).toBe("disconnected");
+  });
+
+  it("rejects invalid wire frames during handshake", async () => {
+    const transport = new MockTransport();
+    const client = createClawChatClient({
+      url: "ws://test",
+      token: "token-1",
+      deviceId: "agent-1",
+      transport,
+      traceIdFactory: () => "trace-connect",
+      heartbeat: { enabled: false },
+    });
+    const connected = client.connect();
+    transport.emitInbound("not json");
+
+    const outcome = await Promise.race([
+      connected.then(() => "resolved", (err) => err),
+      new Promise((resolve) => setTimeout(() => resolve("pending"), 0)),
+    ]);
+    expect(outcome).toBeInstanceOf(ProtocolError);
+    expect(client.state).toBe("disconnected");
+  });
+
+  it("rejects pending ackable sends on unexpected close", 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-send"),
+      ack: { timeout: 1000, autoResendOnTimeout: false },
+      heartbeat: { enabled: false },
+    });
+    await connectReady(transport, client);
+
+    const send = client.sendAckableEnvelope({
+      eventName: "message.send",
+      chatId: "chat-1",
+      payload: {
+        message_mode: "normal",
+        message: {
+          body: { fragments: [{ kind: "text", text: "hello" }] },
+          context: { mentions: [], reply: null },
+        },
+      },
+    });
+    transport.close(1006, "network lost");
+
+    await expect(send).rejects.toBeInstanceOf(TransportError);
+  });
+
+  it("rejects pending ackable sends on close when reconnect is disabled", 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-send"),
+      reconnect: { enabled: false },
+      ack: { timeout: 1000, autoResendOnTimeout: false },
+      heartbeat: { enabled: false },
+    });
+    await connectReady(transport, client);
+
+    const send = client.sendAckableEnvelope({
+      eventName: "message.send",
+      chatId: "chat-1",
+      payload: {
+        message_mode: "normal",
+        message: {
+          body: { fragments: [{ kind: "text", text: "hello" }] },
+          context: { mentions: [], reply: null },
+        },
+      },
+    });
+    transport.close(1006, "network lost");
+
+    const outcome = await Promise.race([
+      send.then(() => "resolved", (err) => err),
+      new Promise((resolve) => setTimeout(() => resolve("pending"), 0)),
+    ]);
+    expect(outcome).toBeInstanceOf(TransportError);
+  });
+
+  it("reconnects after a recoverable close", async () => {
+    vi.useFakeTimers();
+    try {
+      const transport = new MockTransport();
+      const client = createClawChatClient({
+        url: "ws://test",
+        token: "token-1",
+        deviceId: "agent-1",
+        transport,
+        traceIdFactory: () => "trace-1",
+        reconnect: { enabled: true, initialDelay: 50, maxDelay: 50, maxRetries: 1, jitterRatio: 0 },
+        heartbeat: { enabled: false },
+      });
+      const states: string[] = [];
+      client.on("state", ({ to }) => states.push(to));
+      await connectReady(transport, client);
+
+      transport.close(1006, "network lost");
+      expect(client.state).toBe("reconnecting");
+
+      await vi.advanceTimersByTimeAsync(50);
+      expect(states).toContain("connecting");
+      expect(transport.state).toBe("open");
+      await completeHandshake(transport);
+      expect(client.state).toBe("connected");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});