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

package/src/channel.outbound.test.ts

@@ -1,10 +1,46 @@
+import { EventEmitter } from "node:events";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { Envelope, MessageAckPayload } from "./protocol-types.ts";
 
 const getClientMock = vi.hoisted(() => vi.fn());
 const getRuntimeMock = vi.hoisted(() => vi.fn());
 const waitForClientMock = vi.hoisted(() => vi.fn());
 const uploadOutboundMediaMock = vi.hoisted(() => vi.fn());
 const createApiClientMock = vi.hoisted(() => vi.fn());
+const getStoreMock = vi.hoisted(() => vi.fn());
+const clawChatDbPathForStateDirMock = vi.hoisted(() => vi.fn((stateDir: string) => `${stateDir}/clawchat.sqlite`));
+
+function mockClient() {
+  let trace = 0;
+  const sent: string[] = [];
+  const client = Object.assign(new EventEmitter(), {
+    sent,
+    state: "connected",
+    nextTraceId: vi.fn(() => `trace-${++trace}`),
+    sendWire: vi.fn((wire: string) => {
+      sent.push(wire);
+    }),
+    typing: vi.fn(),
+    emitRaw: vi.fn(),
+    sendRawEnvelope: vi.fn(),
+  });
+  Object.defineProperty(client, "transportState", { get: () => "open" });
+  return client;
+}
+
+function emitAck(
+  client: ReturnType<typeof mockClient>,
+  traceId: string,
+  payload: MessageAckPayload,
+) {
+  client.emit("raw", {
+    version: "2",
+    event: "message.ack",
+    trace_id: traceId,
+    emitted_at: Date.now(),
+    payload,
+  } satisfies Envelope<MessageAckPayload>);
+}
 
 vi.mock("./runtime.ts", () => ({
   getOpenclawClawlingClient: getClientMock,
@@ -21,28 +57,44 @@ vi.mock("./api-client.ts", () => ({
   createOpenclawClawlingApiClient: createApiClientMock,
 }));
 
+vi.mock("./storage.ts", () => ({
+  clawChatDbPathForStateDir: clawChatDbPathForStateDirMock,
+  getClawChatStore: getStoreMock,
+}));
+
+function configureClaim(result: true | false | null, runtimeExtras: Record<string, unknown> = {}) {
+  const claimMessageOnce = vi.fn(() => result);
+  const runtime = {
+    ...runtimeExtras,
+    state: { resolveStateDir: vi.fn(() => "/state") },
+  };
+  getRuntimeMock.mockReturnValue(runtime);
+  getStoreMock.mockReturnValue({ claimMessageOnce });
+  return { claimMessageOnce, runtime };
+}
+
 describe("openclaw-clawchat channel outbound", () => {
   beforeEach(() => {
+    vi.useRealTimers();
     vi.resetModules();
     getClientMock.mockReset();
     getRuntimeMock.mockReset();
     waitForClientMock.mockReset();
     uploadOutboundMediaMock.mockReset();
     createApiClientMock.mockReset();
+    getStoreMock.mockReset();
+    clawChatDbPathForStateDirMock.mockClear();
+    clawChatDbPathForStateDirMock.mockImplementation((stateDir: string) => `${stateDir}/clawchat.sqlite`);
   });
 
-  it("sendText waits for client activation when no active client exists yet", async () => {
-    const client = {
-      sendMessage: vi.fn().mockResolvedValue({
-        payload: { message_id: "m-2", accepted_at: 456 },
-        trace_id: "trace-2",
-      }),
-    };
+  it("sendText claims a local message_id before sending", async () => {
+    const client = mockClient();
     getClientMock.mockReturnValue(undefined);
     waitForClientMock.mockResolvedValue(client);
+    const { claimMessageOnce } = configureClaim(true);
 
     const { openclawClawlingOutbound } = await import("./outbound.ts");
-    const result = await openclawClawlingOutbound.sendText!({
+    const send = openclawClawlingOutbound.sendText!({
       cfg: {
         channels: {
           "openclaw-clawchat": {
@@ -58,39 +110,119 @@ describe("openclaw-clawchat channel outbound", () => {
       text: "hello",
     });
 
+    await vi.waitFor(() => expect(client.sent).toHaveLength(1));
+    const frame = JSON.parse(client.sent[0]!) as Envelope;
+    const claimedInput = claimMessageOnce.mock.calls[0]?.[0] as { messageId?: string } | undefined;
+    const claimedMessageId = claimedInput?.messageId ?? "server-id";
+    emitAck(client, frame.trace_id, { message_id: claimedMessageId, accepted_at: 456 });
+    const result = await send;
+
     expect(waitForClientMock).toHaveBeenCalledWith("default");
-    expect(client.sendMessage).toHaveBeenCalledWith(
-      expect.objectContaining({
-        chat_id: "user-1",
-        body: { fragments: [{ kind: "text", text: "hello" }] },
-      }),
-    );
-    expect(client.sendMessage.mock.calls[0][0]).not.toHaveProperty("chat_type");
+    expect(getStoreMock).toHaveBeenCalledWith({ dbPath: "/state/clawchat.sqlite" });
+    expect(claimedInput).toEqual(expect.objectContaining({
+      kind: "message",
+      direction: "outbound",
+      eventType: "message.send",
+      messageId: claimedMessageId,
+      text: "hello",
+    }));
+    expect(frame).toMatchObject({
+      event: "message.send",
+      chat_id: "user-1",
+      payload: {
+        message_id: claimedMessageId,
+        message: { body: { fragments: [{ kind: "text", text: "hello" }] } },
+      },
+    });
+    expect(frame).not.toHaveProperty("chat_type");
     expect(result).toEqual({
       channel: "openclaw-clawchat",
       to: "cc:user-1",
-      messageId: "m-2",
+      messageId: claimedMessageId,
     });
   });
 
-  it("sendMedia uploads mediaUrl and sends resulting fragments", async () => {
-    const client = {
-      sendMessage: vi.fn().mockResolvedValue({
-        payload: { message_id: "m-1", accepted_at: 123 },
-        trace_id: "trace-1",
-      }),
-    };
-    const runtime = { media: { loadWebMedia: vi.fn() } };
+  it("sendText rejects empty text instead of returning an unsent message id", async () => {
+    const client = mockClient();
+    getClientMock.mockReturnValue(client);
+    const { claimMessageOnce } = configureClaim(true);
+
+    const { openclawClawlingOutbound } = await import("./outbound.ts");
+    const send = openclawClawlingOutbound.sendText!({
+      cfg: {
+        channels: {
+          "openclaw-clawchat": {
+            enabled: true,
+            websocketUrl: "ws://t",
+            baseUrl: "https://api.example.com",
+            token: "tk",
+            userId: "agent-1",
+          },
+        },
+      } as never,
+      to: "cc:user-1",
+      text: "   ",
+    });
+
+    await expect(send).rejects.toThrow("openclaw-clawchat sendText requires non-empty text");
+    expect(claimMessageOnce).not.toHaveBeenCalled();
+    expect(client.sent).toHaveLength(0);
+  });
+
+  it("sendText rejects when the storage claim is duplicate or unavailable", async () => {
+    for (const [claimResult, errorMessage] of [
+      [false, "openclaw-clawchat outbound duplicate claim; message not sent"],
+      [null, "openclaw-clawchat outbound message claim failed"],
+    ] as const) {
+      const client = mockClient();
+      getClientMock.mockReturnValue(client);
+      const { claimMessageOnce } = configureClaim(claimResult);
+      const { openclawClawlingOutbound } = await import("./outbound.ts");
+
+      const send = openclawClawlingOutbound.sendText!({
+        cfg: {
+          channels: {
+            "openclaw-clawchat": {
+              enabled: true,
+              websocketUrl: "ws://t",
+              baseUrl: "https://api.example.com",
+              token: "tk",
+              userId: "agent-1",
+            },
+          },
+        } as never,
+        to: "cc:user-1",
+        text: "hello",
+      });
+      await expect(send).rejects.toThrow(errorMessage);
+
+      expect(claimMessageOnce).toHaveBeenCalledWith(expect.objectContaining({
+        kind: "message",
+        direction: "outbound",
+      }));
+      expect(client.sent).toHaveLength(0);
+      vi.resetModules();
+      getClientMock.mockReset();
+      getRuntimeMock.mockReset();
+      getStoreMock.mockReset();
+    }
+  });
+
+  it("sendMedia claims a local message_id before sending resulting fragments", async () => {
+    const client = mockClient();
+    const runtimeExtras = { media: { loadWebMedia: vi.fn() } };
     const apiClient = { uploadMedia: vi.fn() };
     getClientMock.mockReturnValue(client);
-    getRuntimeMock.mockReturnValue(runtime);
+    const { claimMessageOnce, runtime } = configureClaim(true, runtimeExtras);
     createApiClientMock.mockReturnValue(apiClient);
     uploadOutboundMediaMock.mockResolvedValue([
       { kind: "image", url: "https://cdn/uploaded.png", mime: "image/png" },
     ]);
+    const mediaReadFile = vi.fn(async () => Buffer.from("host-read"));
+    const mediaAccess = { localRoots: ["/tmp"], workspaceDir: "/workspace" };
 
     const { openclawClawlingOutbound } = await import("./outbound.ts");
-    const result = await openclawClawlingOutbound.sendMedia!({
+    const send = openclawClawlingOutbound.sendMedia!({
       cfg: {
         channels: {
           "openclaw-clawchat": {
@@ -105,9 +237,18 @@ describe("openclaw-clawchat channel outbound", () => {
       to: "cc:group:room-1",
       text: "caption",
       mediaUrl: "/tmp/photo.png",
+      mediaAccess,
       mediaLocalRoots: ["/tmp"],
+      mediaReadFile,
     });
 
+    await vi.waitFor(() => expect(client.sent).toHaveLength(1));
+    const frame = JSON.parse(client.sent[0]!) as Envelope;
+    const claimedInput = claimMessageOnce.mock.calls[0]?.[0] as { messageId?: string } | undefined;
+    const claimedMessageId = claimedInput?.messageId ?? "server-id";
+    emitAck(client, frame.trace_id, { message_id: claimedMessageId, accepted_at: 123 });
+    const result = await send;
+
     expect(createApiClientMock).toHaveBeenCalledWith({
       baseUrl: "https://api.example.com",
       token: "tk",
@@ -116,29 +257,91 @@ describe("openclaw-clawchat channel outbound", () => {
     expect(uploadOutboundMediaMock).toHaveBeenCalledWith(["/tmp/photo.png"], {
       apiClient,
       runtime,
+      mediaAccess,
       mediaLocalRoots: ["/tmp"],
+      mediaReadFile,
     });
-    expect(client.sendMessage).toHaveBeenCalledWith(
-      expect.objectContaining({
-        chat_id: "room-1",
-        body: {
-          fragments: [
-            { kind: "text", text: "caption" },
-            { kind: "image", url: "https://cdn/uploaded.png", mime: "image/png" },
-          ],
+    expect(claimedInput).toEqual(expect.objectContaining({
+      kind: "message",
+      direction: "outbound",
+      eventType: "message.send",
+      messageId: claimedMessageId,
+      text: "caption",
+    }));
+    expect(frame).toMatchObject({
+      event: "message.send",
+      chat_id: "room-1",
+      payload: {
+        message_id: claimedMessageId,
+        message: {
+          body: {
+            fragments: [
+              { kind: "text", text: "caption" },
+              { kind: "image", url: "https://cdn/uploaded.png", mime: "image/png" },
+            ],
+          },
         },
-      }),
-    );
-    expect(client.sendMessage.mock.calls[0][0]).not.toHaveProperty("chat_type");
+      },
+    });
+    expect(frame).not.toHaveProperty("chat_type");
     expect(result).toEqual({
       channel: "openclaw-clawchat",
       to: "cc:group:room-1",
-      messageId: "m-1",
+      messageId: claimedMessageId,
     });
   });
 
+  it("sendMedia rejects when the storage claim is duplicate or unavailable", async () => {
+    for (const [claimResult, errorMessage] of [
+      [false, "openclaw-clawchat outbound duplicate claim; message not sent"],
+      [null, "openclaw-clawchat outbound message claim failed"],
+    ] as const) {
+      const client = mockClient();
+      const runtimeExtras = { media: { loadWebMedia: vi.fn() } };
+      const apiClient = { uploadMedia: vi.fn() };
+      getClientMock.mockReturnValue(client);
+      const { claimMessageOnce } = configureClaim(claimResult, runtimeExtras);
+      createApiClientMock.mockReturnValue(apiClient);
+      uploadOutboundMediaMock.mockResolvedValue([
+        { kind: "image", url: "https://cdn/uploaded.png", mime: "image/png" },
+      ]);
+      const { openclawClawlingOutbound } = await import("./outbound.ts");
+
+      const send = openclawClawlingOutbound.sendMedia!({
+        cfg: {
+          channels: {
+            "openclaw-clawchat": {
+              enabled: true,
+              websocketUrl: "ws://t",
+              baseUrl: "https://api.example.com",
+              token: "tk",
+              userId: "agent-1",
+            },
+          },
+        } as never,
+        to: "cc:group:room-1",
+        text: "caption",
+        mediaUrl: "/tmp/photo.png",
+      });
+      await expect(send).rejects.toThrow(errorMessage);
+
+      expect(uploadOutboundMediaMock).toHaveBeenCalled();
+      expect(claimMessageOnce).toHaveBeenCalledWith(expect.objectContaining({
+        kind: "message",
+        direction: "outbound",
+      }));
+      expect(client.sent).toHaveLength(0);
+      vi.resetModules();
+      getClientMock.mockReset();
+      getRuntimeMock.mockReset();
+      getStoreMock.mockReset();
+      uploadOutboundMediaMock.mockReset();
+      createApiClientMock.mockReset();
+    }
+  });
+
   it("sendMedia rejects missing mediaUrl", async () => {
-    getClientMock.mockReturnValue({ sendMessage: vi.fn() });
+    getClientMock.mockReturnValue(mockClient());
     const { openclawClawlingOutbound } = await import("./outbound.ts");
     await expect(
       openclawClawlingOutbound.sendMedia!({
@@ -160,24 +363,19 @@ describe("openclaw-clawchat channel outbound", () => {
   });
 
   it("sendMedia waits for client activation when no active client exists yet", async () => {
-    const client = {
-      sendMessage: vi.fn().mockResolvedValue({
-        payload: { message_id: "m-3", accepted_at: 789 },
-        trace_id: "trace-3",
-      }),
-    };
-    const runtime = { media: { loadWebMedia: vi.fn() } };
+    const client = mockClient();
+    const runtimeExtras = { media: { loadWebMedia: vi.fn() } };
     const apiClient = { uploadMedia: vi.fn() };
     getClientMock.mockReturnValue(undefined);
     waitForClientMock.mockResolvedValue(client);
-    getRuntimeMock.mockReturnValue(runtime);
+    const { claimMessageOnce, runtime } = configureClaim(true, runtimeExtras);
     createApiClientMock.mockReturnValue(apiClient);
     uploadOutboundMediaMock.mockResolvedValue([
       { kind: "image", url: "https://cdn/uploaded.png", mime: "image/png" },
     ]);
 
     const { openclawClawlingOutbound } = await import("./outbound.ts");
-    const result = await openclawClawlingOutbound.sendMedia!({
+    const send = openclawClawlingOutbound.sendMedia!({
       cfg: {
         channels: {
           "openclaw-clawchat": {
@@ -195,23 +393,34 @@ describe("openclaw-clawchat channel outbound", () => {
       mediaLocalRoots: ["/tmp"],
     });
 
+    await vi.waitFor(() => expect(client.sent).toHaveLength(1));
+    const frame = JSON.parse(client.sent[0]!) as Envelope;
+    const claimedInput = claimMessageOnce.mock.calls[0]?.[0] as { messageId?: string } | undefined;
+    const claimedMessageId = claimedInput?.messageId ?? "server-id";
+    emitAck(client, frame.trace_id, { message_id: claimedMessageId, accepted_at: 789 });
+    const result = await send;
+
     expect(waitForClientMock).toHaveBeenCalledWith("default");
-    expect(client.sendMessage).toHaveBeenCalledWith(
-      expect.objectContaining({
-        chat_id: "room-1",
-        body: {
-          fragments: [
-            { kind: "text", text: "caption" },
-            { kind: "image", url: "https://cdn/uploaded.png", mime: "image/png" },
-          ],
+    expect(frame).toMatchObject({
+      event: "message.send",
+      chat_id: "room-1",
+      payload: {
+        message_id: claimedMessageId,
+        message: {
+          body: {
+            fragments: [
+              { kind: "text", text: "caption" },
+              { kind: "image", url: "https://cdn/uploaded.png", mime: "image/png" },
+            ],
+          },
         },
-      }),
-    );
-    expect(client.sendMessage.mock.calls[0][0]).not.toHaveProperty("chat_type");
+      },
+    });
+    expect(frame).not.toHaveProperty("chat_type");
     expect(result).toEqual({
       channel: "openclaw-clawchat",
       to: "cc:group:room-1",
-      messageId: "m-3",
+      messageId: claimedMessageId,
     });
   });
 });

package/src/channel.setup.ts

@@ -0,0 +1,146 @@
+import { createTopLevelChannelConfigAdapter } from "openclaw/plugin-sdk/channel-config-helpers";
+import type { ChannelSetupInput } from "openclaw/plugin-sdk/channel-setup";
+import type { ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { mutateConfigFile } from "openclaw/plugin-sdk/config-mutation";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
+import {
+  createComputedAccountStatusAdapter,
+  createDefaultChannelRuntimeState,
+} from "openclaw/plugin-sdk/status-helpers";
+import {
+  CHANNEL_ID,
+  listOpenclawClawlingAccountIds,
+  openclawClawlingConfigSchema,
+  resolveOpenclawClawlingAccount,
+  type ResolvedOpenclawClawlingAccount,
+} from "./config.ts";
+import type { OpenclawClawchatMutateConfigFile } from "./login.runtime.ts";
+
+const configAdapter = createTopLevelChannelConfigAdapter<ResolvedOpenclawClawlingAccount>({
+  sectionKey: CHANNEL_ID,
+  resolveAccount: (cfg) => resolveOpenclawClawlingAccount(cfg),
+  listAccountIds: () => listOpenclawClawlingAccountIds(),
+  defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+  deleteMode: "clear-fields",
+  clearBaseFields: [
+    "websocketUrl",
+    "baseUrl",
+    "token",
+    "userId",
+    "replyMode",
+    "forwardThinking",
+    "forwardToolCalls",
+    "richInteractions",
+    "enabled",
+  ],
+  resolveAllowFrom: (account) => account.allowFrom,
+  formatAllowFrom: () => [],
+});
+
+/**
+ * Invite-code setup adapter used by OpenClaw setup surfaces.
+ *
+ * `channels add --token` passes the invite code as setup input. The setup
+ * write leaves channel config unchanged; `afterAccountConfigWritten` exchanges
+ * the invite code and persists token/userId through the host runtime mutator.
+ */
+const setupAdapter: NonNullable<ChannelPlugin<ResolvedOpenclawClawlingAccount>["setup"]> = {
+  resolveAccountId: () => DEFAULT_ACCOUNT_ID,
+  validateInput: ({ input }: { cfg: OpenClawConfig; accountId: string; input: ChannelSetupInput }) => {
+    const inviteCode =
+      typeof input.code === "string" && input.code.trim()
+        ? input.code.trim()
+        : typeof input.token === "string"
+          ? input.token.trim()
+          : "";
+    if (!inviteCode) {
+      return "ClawChat invite code is required.";
+    }
+    return null;
+  },
+  applyAccountConfig: ({ cfg }: {
+    cfg: OpenClawConfig;
+    accountId: string;
+    input: ChannelSetupInput;
+  }) => cfg,
+  afterAccountConfigWritten: async ({ cfg, input, runtime }) => {
+    runtime.log("[default] openclaw-clawchat setup afterAccountConfigWritten invoked");
+    const code =
+      typeof input.code === "string" && input.code.trim()
+        ? input.code.trim()
+        : typeof input.token === "string"
+          ? input.token.trim()
+          : "";
+    if (!code) {
+      runtime.log("[default] openclaw-clawchat setup afterAccountConfigWritten skipped: empty invite code");
+      return;
+    }
+    const { runOpenclawClawlingLogin } = await import("./login.runtime.ts");
+    await runOpenclawClawlingLogin({
+      cfg,
+      accountId: null,
+      runtime: { log: (message: string) => runtime.log(message) },
+      readInviteCode: async () => code,
+      mutateConfigFile: mutateConfigFile as OpenclawClawchatMutateConfigFile,
+    });
+    runtime.log("[default] openclaw-clawchat setup afterAccountConfigWritten completed");
+  },
+};
+
+type OpenclawClawlingSetupPlugin = Pick<
+  ChannelPlugin<ResolvedOpenclawClawlingAccount>,
+  "id" | "meta" | "capabilities" | "configSchema" | "config" | "setup" | "status"
+>;
+
+export const openclawClawlingSetupPlugin: OpenclawClawlingSetupPlugin = {
+  id: CHANNEL_ID,
+  meta: {
+    id: CHANNEL_ID,
+    label: "Clawling Chat",
+    selectionLabel: "Clawling Chat",
+    docsPath: "/channels/openclaw-clawchat",
+    docsLabel: "openclaw-clawchat",
+    blurb: "ClawChat Protocol v2 over WebSocket.",
+    order: 110,
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+    reactions: false,
+    threads: false,
+    polls: false,
+    blockStreaming: true,
+  },
+  configSchema: {
+    schema: openclawClawlingConfigSchema,
+  },
+  config: {
+    ...configAdapter,
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+    }),
+  },
+  setup: setupAdapter,
+  status: createComputedAccountStatusAdapter<ResolvedOpenclawClawlingAccount>({
+    defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID, {
+      connected: false,
+      lastInboundAt: null,
+      lastOutboundAt: null,
+    }),
+    resolveAccountSnapshot: ({ account }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      extra: {
+        websocketUrl: account.websocketUrl || null,
+        baseUrl: account.baseUrl || null,
+        userId: account.userId || null,
+      },
+    }),
+  }),
+};