@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/channel.outbound.test.ts

@@ -0,0 +1,433 @@
+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>);
+}
+
+async function waitForSentFrame(client: ReturnType<typeof mockClient>) {
+  for (let i = 0; i < 10 && client.sent.length === 0; i++) {
+    await Promise.resolve();
+  }
+  expect(client.sent).toHaveLength(1);
+}
+
+vi.mock("./runtime.ts", () => ({
+  getOpenclawClawlingClient: getClientMock,
+  getOpenclawClawlingRuntime: getRuntimeMock,
+  waitForOpenclawClawlingClient: waitForClientMock,
+  startOpenclawClawlingGateway: vi.fn(),
+}));
+
+vi.mock("./media-runtime.ts", () => ({
+  uploadOutboundMedia: uploadOutboundMediaMock,
+}));
+
+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("clawchat-plugin-openclaw 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 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 send = openclawClawlingOutbound.sendText!({
+      cfg: {
+        channels: {
+          "clawchat-plugin-openclaw": {
+            enabled: true,
+            websocketUrl: "ws://t",
+            baseUrl: "https://api.example.com",
+            token: "tk",
+            userId: "agent-1",
+          },
+        },
+      } as never,
+      to: "cc:user-1",
+      text: "hello",
+    });
+
+    await waitForSentFrame(client);
+    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(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: "clawchat-plugin-openclaw",
+      to: "cc:user-1",
+      messageId: claimedMessageId,
+    });
+  });
+
+  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: {
+          "clawchat-plugin-openclaw": {
+            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("clawchat-plugin-openclaw 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, "clawchat-plugin-openclaw outbound duplicate claim; message not sent"],
+      [null, "clawchat-plugin-openclaw 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: {
+            "clawchat-plugin-openclaw": {
+              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);
+    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 send = openclawClawlingOutbound.sendMedia!({
+      cfg: {
+        channels: {
+          "clawchat-plugin-openclaw": {
+            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",
+      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",
+      userId: "agent-1",
+    });
+    expect(uploadOutboundMediaMock).toHaveBeenCalledWith(["/tmp/photo.png"], {
+      apiClient,
+      runtime,
+      mediaAccess,
+      mediaLocalRoots: ["/tmp"],
+      mediaReadFile,
+    });
+    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(frame).not.toHaveProperty("chat_type");
+    expect(result).toEqual({
+      channel: "clawchat-plugin-openclaw",
+      to: "cc:group:room-1",
+      messageId: claimedMessageId,
+    });
+  });
+
+  it("sendMedia rejects when the storage claim is duplicate or unavailable", async () => {
+    for (const [claimResult, errorMessage] of [
+      [false, "clawchat-plugin-openclaw outbound duplicate claim; message not sent"],
+      [null, "clawchat-plugin-openclaw 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: {
+            "clawchat-plugin-openclaw": {
+              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(mockClient());
+    const { openclawClawlingOutbound } = await import("./outbound.ts");
+    await expect(
+      openclawClawlingOutbound.sendMedia!({
+        cfg: {
+          channels: {
+            "clawchat-plugin-openclaw": {
+              enabled: true,
+              websocketUrl: "ws://t",
+              baseUrl: "https://api.example.com",
+              token: "tk",
+              userId: "agent-1",
+            },
+          },
+        } as never,
+        to: "cc:user-1",
+        text: "caption",
+      }),
+    ).rejects.toThrow(/requires mediaUrl/);
+  });
+
+  it("sendMedia waits for client activation when no active client exists yet", async () => {
+    const client = mockClient();
+    const runtimeExtras = { media: { loadWebMedia: vi.fn() } };
+    const apiClient = { uploadMedia: vi.fn() };
+    getClientMock.mockReturnValue(undefined);
+    waitForClientMock.mockResolvedValue(client);
+    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 send = openclawClawlingOutbound.sendMedia!({
+      cfg: {
+        channels: {
+          "clawchat-plugin-openclaw": {
+            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",
+      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(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(frame).not.toHaveProperty("chat_type");
+    expect(result).toEqual({
+      channel: "clawchat-plugin-openclaw",
+      to: "cc:group:room-1",
+      messageId: claimedMessageId,
+    });
+  });
+});

package/src/channel.setup.ts

@@ -0,0 +1,145 @@
+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",
+    "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] clawchat-plugin-openclaw 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] clawchat-plugin-openclaw 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] clawchat-plugin-openclaw 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/clawchat-plugin-openclaw",
+    docsLabel: "clawchat-plugin-openclaw",
+    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,
+      },
+    }),
+  }),
+};