@newbase-clawchat/openclaw-clawchat 2026.4.15

package/src/channel.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import { openclawClawlingPlugin } from "./channel.ts";
+
+describe("openclaw-clawchat plugin", () => {
+  it("publishes openclaw-clawchat channel metadata", () => {
+    expect(openclawClawlingPlugin.meta.id).toBe("openclaw-clawchat");
+    expect(openclawClawlingPlugin.meta.label).toBe("Clawling Chat");
+    expect(openclawClawlingPlugin.capabilities.blockStreaming).toBe(true);
+  });
+
+  it("reloads on channel config changes", () => {
+    expect(openclawClawlingPlugin.reload?.configPrefixes).toContain("channels.openclaw-clawchat");
+  });
+
+  it("declares media capability", () => {
+    expect(openclawClawlingPlugin.capabilities.media).toBe(true);
+  });
+
+  it("setup.validateInput requires --code", () => {
+    const validate = openclawClawlingPlugin.setup?.validateInput as
+      | ((args: { cfg: unknown; accountId: string; input: Record<string, unknown> }) => string | null)
+      | undefined;
+    expect(validate).toBeDefined();
+    expect(validate!({ cfg: {}, accountId: "default", input: {} })).toMatch(
+      /--code \(invite code/,
+    );
+    expect(
+      validate!({ cfg: {}, accountId: "default", input: { code: "  " } }),
+    ).toMatch(/--code \(invite code/);
+  });
+
+  it("setup.validateInput passes when --code is present", () => {
+    const validate = openclawClawlingPlugin.setup?.validateInput as (args: {
+      cfg: unknown;
+      accountId: string;
+      input: Record<string, unknown>;
+    }) => string | null;
+    expect(
+      validate({ cfg: {}, accountId: "default", input: { code: "INV-XXXX" } }),
+    ).toBeNull();
+  });
+
+  it("setup.applyAccountConfig marks the channel enabled without touching credentials", () => {
+    const apply = openclawClawlingPlugin.setup?.applyAccountConfig as (args: {
+      cfg: unknown;
+      accountId: string;
+      input: Record<string, unknown>;
+    }) => Record<string, unknown>;
+    const next = apply({
+      cfg: {},
+      accountId: "default",
+      input: { code: "INV-XXXX" },
+    }) as { channels: Record<string, Record<string, unknown>> };
+    const section = next.channels["openclaw-clawchat"]!;
+    expect(section.enabled).toBe(true);
+    // Credentials are untouched — they arrive via runOpenclawClawlingLogin
+    // in the afterAccountConfigWritten hook.
+    expect(section.token).toBeUndefined();
+    expect(section.userId).toBeUndefined();
+    expect(section.websocketUrl).toBeUndefined();
+    expect(section.baseUrl).toBeUndefined();
+  });
+
+  it("publishes clawchat-specific agentPrompt hints", () => {
+    const hints = openclawClawlingPlugin.agentPrompt?.messageToolHints?.({
+      cfg: {} as never,
+      accountId: "default",
+    });
+    expect(Array.isArray(hints) && hints.length).toBeGreaterThan(0);
+    expect(hints!.some((h) => /ClawChat/.test(h))).toBe(true);
+  });
+});

package/src/channel.ts

@@ -0,0 +1,278 @@
+import { createTopLevelChannelConfigAdapter } from "openclaw/plugin-sdk/channel-config-helpers";
+import type { ChannelSetupInput } from "openclaw/plugin-sdk/channel-setup";
+import {
+  createChatChannelPlugin,
+  type ChannelPlugin,
+  type OpenClawConfig,
+} from "openclaw/plugin-sdk/core";
+import { createEmptyChannelDirectoryAdapter } from "openclaw/plugin-sdk/directory-runtime";
+import { chunkMarkdownText } from "openclaw/plugin-sdk/reply-runtime";
+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 { ChatType } from "./client.ts";
+import { sendOpenclawClawlingText } from "./outbound.ts";
+import { startOpenclawClawlingGateway, getOpenclawClawlingClient } from "./runtime.ts";
+
+/**
+ * Parse an agent-initiated outbound recipient string into the new-protocol
+ * `chat_id` + `chat_type` pair.
+ *
+ * Accepted forms (case-insensitive prefix):
+ *   - `cc:{chat_id}`                  → direct
+ *   - `clawchat:{chat_id}`            → direct
+ *   - `cc:direct:{chat_id}`           → direct
+ *   - `cc:group:{chat_id}`            → group
+ *   - `clawchat:direct:{chat_id}`     → direct
+ *   - `clawchat:group:{chat_id}`      → group
+ *   - bare `{chat_id}`                → direct (backward compat)
+ */
+export function parseOpenclawRecipient(to: string): { chatId: string; chatType: ChatType } {
+  const raw = (to ?? "").trim();
+  if (!raw) throw new Error("openclaw-clawchat: outbound `to` is empty");
+
+  // Split on the first ":" to detect the scheme. If no scheme, treat as a
+  // bare chat_id defaulting to direct.
+  const firstColon = raw.indexOf(":");
+  if (firstColon < 0) return { chatId: raw, chatType: "direct" };
+
+  const scheme = raw.slice(0, firstColon).toLowerCase();
+  const rest = raw.slice(firstColon + 1);
+  if (scheme !== "cc" && scheme !== "clawchat") {
+    // Unknown scheme — treat the whole string as the chat_id for robustness.
+    return { chatId: raw, chatType: "direct" };
+  }
+
+  // After the scheme we optionally accept `direct:` / `group:` type prefix.
+  const secondColon = rest.indexOf(":");
+  if (secondColon >= 0) {
+    const typeToken = rest.slice(0, secondColon).toLowerCase();
+    const chatId = rest.slice(secondColon + 1).trim();
+    if ((typeToken === "direct" || typeToken === "group") && chatId) {
+      return { chatId, chatType: typeToken };
+    }
+  }
+  // No explicit type token → default to direct, chat_id is `rest`.
+  const chatId = rest.trim();
+  if (!chatId) throw new Error(`openclaw-clawchat: missing chat_id in \"${to}\"`);
+  return { chatId, chatType: "direct" };
+}
+
+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",
+    "enabled",
+  ],
+  resolveAllowFrom: (account) => account.allowFrom,
+  formatAllowFrom: () => [],
+});
+
+/**
+ * `openclaw channels setup --channel openclaw-clawchat` adapter.
+ *
+ * Setup takes exactly ONE input: `code` (an invite code). URL + token +
+ * userId come from the login flow which is triggered automatically in
+ * `afterAccountConfigWritten`:
+ *
+ *   openclaw channels setup --channel openclaw-clawchat --code INV-XXXX
+ *
+ * `applyAccountConfig` itself only marks the section `enabled: true`;
+ * credentials are written by `runOpenclawClawlingLogin` which calls `writeConfigFile`
+ * on its own after the `/v1/agents/connect` response lands.
+ */
+const setupAdapter = {
+  resolveAccountId: () => DEFAULT_ACCOUNT_ID,
+  validateInput: ({ input }: { cfg: unknown; accountId: string; input: ChannelSetupInput }) => {
+    if (!input.code?.trim()) {
+      return "Clawling Chat setup requires --code (invite code from your admin).";
+    }
+    return null;
+  },
+  applyAccountConfig: ({
+    cfg,
+  }: {
+    cfg: OpenClawConfig;
+    accountId: string;
+    input: ChannelSetupInput;
+  }): OpenClawConfig => {
+    // Base config: just enable the channel. Credentials arrive via
+    // `afterAccountConfigWritten` → `runOpenclawClawlingLogin`.
+    const channels = (cfg.channels ?? {}) as Record<string, unknown>;
+    const current = (channels[CHANNEL_ID] ?? {}) as Record<string, unknown>;
+    return {
+      ...cfg,
+      channels: {
+        ...channels,
+        [CHANNEL_ID]: { ...current, enabled: true },
+      },
+    };
+  },
+  afterAccountConfigWritten: async ({
+    cfg,
+    input,
+    runtime,
+  }: {
+    cfg: OpenClawConfig;
+    accountId: string;
+    input: ChannelSetupInput;
+    runtime: { log: (message: string) => void };
+    previousCfg: OpenClawConfig;
+  }) => {
+    const code = input.code?.trim();
+    if (!code) return;
+    // Lazy-import the login runtime to keep @clack/prompts / readline /
+    // config-runtime off the plugin's cold-start path. `readInviteCode`
+    // feeds the fixed code so the stdin prompt is skipped entirely.
+    const { runOpenclawClawlingLogin } = await import("./login.runtime.ts");
+    await runOpenclawClawlingLogin({
+      cfg,
+      accountId: null,
+      runtime: { log: (message: string) => runtime.log(message) },
+      readInviteCode: async () => code,
+    });
+  },
+};
+
+export const openclawClawlingPlugin: ChannelPlugin<ResolvedOpenclawClawlingAccount> =
+  createChatChannelPlugin({
+    base: {
+      id: CHANNEL_ID,
+      meta: {
+        id: CHANNEL_ID,
+        label: "Clawling Chat",
+        selectionLabel: "Clawling Chat",
+        docsPath: "/channels/openclaw-clawchat",
+        docsLabel: "openclaw-clawchat",
+        blurb: "Clawling Protocol v2 over WebSocket (chat-sdk).",
+        order: 110,
+      },
+      capabilities: {
+        chatTypes: ["direct", "group"],
+        media: true,
+        reactions: false,
+        threads: false,
+        polls: false,
+        blockStreaming: true,
+      },
+      reload: {
+        configPrefixes: [`channels.${CHANNEL_ID}`],
+      },
+      configSchema: {
+        schema: openclawClawlingConfigSchema,
+      },
+      config: {
+        ...configAdapter,
+        isConfigured: (account) => account.configured,
+        describeAccount: (account) => ({
+          accountId: account.accountId,
+          name: account.name,
+          enabled: account.enabled,
+          configured: account.configured,
+        }),
+      },
+      directory: createEmptyChannelDirectoryAdapter(),
+      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,
+          },
+        }),
+      }),
+      auth: {
+        login: async ({ cfg, accountId, runtime }) => {
+          // Lazy-load login.runtime: it pulls in @clack/prompts and other
+          // heavy modules that have no business loading on every plugin
+          // boot. Only the rare `openclaw channels login --channel
+          // openclaw-clawchat` invocation pays the import cost.
+          const { runOpenclawClawlingLogin } = await import("./login.runtime.ts");
+          await runOpenclawClawlingLogin({
+            cfg,
+            accountId: accountId ?? null,
+            runtime: { log: (message: string) => runtime.log(message) },
+          });
+        },
+      },
+      gateway: {
+        startAccount: async (ctx) => {
+          const account = ctx.account ?? resolveOpenclawClawlingAccount(ctx.cfg);
+          if (!account.configured) {
+            throw new Error("Clawling Chat websocketUrl/token/userId are required");
+          }
+          return await startOpenclawClawlingGateway({
+            cfg: ctx.cfg,
+            account,
+            abortSignal: ctx.abortSignal,
+            setStatus: ctx.setStatus,
+            getStatus: ctx.getStatus,
+            log: ctx.log,
+          });
+        },
+      },
+      agentPrompt: {
+        messageToolHints: () => [
+          "To send an image or file to the current user, use the message tool with action='send' and set 'media' to a local file path or a remote URL. You do not need to specify 'to' — the current conversation recipient is used automatically.",
+          "When the user asks you to find an image from the web, use a web search or browser tool to find a suitable image URL, then send it using the message tool with 'media' set to that HTTPS image URL — do NOT download the image first.",
+          "- ClawChat targeting: omit `target` to reply to the current chat (auto-inferred). To send to a specific chat, use `cc:{chat_id}` (direct, default) or `cc:group:{chat_id}` (group). `clawchat:` is accepted as a synonym of `cc:`.",
+          "- ClawChat supports media fragments (image / file / audio / video) alongside text in the same message.",
+          "- ClawChat stream mode emits `message.created` → progressive `message.add` deltas → `message.done`, followed by a consolidated `message.reply` with the merged text.",
+        ],
+      },
+    },
+    outbound: {
+      deliveryMode: "direct",
+      chunker: (text, limit) => chunkMarkdownText(text, limit),
+      chunkerMode: "markdown",
+      textChunkLimit: 4000,
+      sendText: async ({ cfg, to, text }) => {
+        const account = resolveOpenclawClawlingAccount(cfg);
+        const client = getOpenclawClawlingClient(account.accountId);
+        if (!client) {
+          throw new Error(`openclaw-clawchat client not running for account ${account.accountId}`);
+        }
+        const recipient = parseOpenclawRecipient(to);
+        const result = await sendOpenclawClawlingText({
+          client,
+          account,
+          to: recipient,
+          text,
+        });
+        return {
+          channel: CHANNEL_ID,
+          to,
+          messageId: result?.messageId ?? `${account.userId}-${Date.now()}`,
+        };
+      },
+    },
+  });

package/src/client.test.ts

@@ -0,0 +1,174 @@
+import { MockTransport } from "@newbase-clawchat/sdk";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
+import { describe, expect, it } from "vitest";
+import {
+  createOpenclawClawlingClient,
+  emitStreamCreated,
+  emitStreamAdd,
+  emitStreamDone,
+  emitStreamFailed,
+} from "./client.ts";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+
+function baseAccount(): ResolvedOpenclawClawlingAccount {
+  return {
+    accountId: DEFAULT_ACCOUNT_ID,
+    name: "openclaw-clawchat",
+    enabled: true,
+    configured: true,
+    websocketUrl: "ws://test",
+    baseUrl: "",
+    token: "t",
+    userId: "agent-1",
+    replyMode: "static",
+    forwardThinking: true,
+    forwardToolCalls: false,
+    allowFrom: [],
+    stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+    reconnect: {
+      initialDelay: 1000,
+      maxDelay: 30000,
+      jitterRatio: 0.3,
+      maxRetries: Number.POSITIVE_INFINITY,
+    },
+    heartbeat: { interval: 25000, timeout: 10000 },
+    ack: { timeout: 10000, autoResendOnTimeout: false },
+  };
+}
+
+async function authenticate(transport: MockTransport) {
+  // Yield to allow MockTransport.connect's internal Promise.resolve() to fire
+  // onOpen (which transitions state: connecting -> challenging) before we send
+  // the challenge envelope.
+  await Promise.resolve();
+  // Challenge from server
+  transport.emitInbound(
+    JSON.stringify({
+      version: "2",
+      event: "connect.challenge",
+      trace_id: "t-challenge",
+      emitted_at: Date.now(),
+      payload: { nonce: "nonce-1" },
+    }),
+  );
+  // hello-ok
+  transport.emitInbound(
+    JSON.stringify({
+      version: "2",
+      event: "hello-ok",
+      trace_id: "t-hello",
+      emitted_at: Date.now(),
+      payload: {},
+    }),
+  );
+}
+
+describe("openclaw-clawchat client", () => {
+  it("connects via MockTransport and completes hello handshake", async () => {
+    const transport = new MockTransport();
+    const client = createOpenclawClawlingClient(baseAccount(), { transport });
+    const p = client.connect();
+    await authenticate(transport);
+    await p;
+    expect(client.state).toBe("connected");
+    client.close();
+  });
+
+  it("emitStreamCreated emits a minimal message.created envelope with just message_id", async () => {
+    const transport = new MockTransport();
+    const client = createOpenclawClawlingClient(baseAccount(), { transport });
+    const p = client.connect();
+    await authenticate(transport);
+    await p;
+    transport.sent.length = 0;
+
+    emitStreamCreated(client, {
+      messageId: "msg-1",
+      to: { id: "user-1", type: "direct" },
+      sender: { sender_id: "agent-1", type: "direct", display_name: "Clawling Assistant" },
+    });
+
+    expect(transport.sent).toHaveLength(1);
+    const env = JSON.parse(transport.sent[0]!);
+    expect(env.event).toBe("message.created");
+    expect(env.to).toEqual({ id: "user-1", type: "direct" });
+    // Payload is intentionally minimal: just message_id, no message body /
+    // context / sender / streaming metadata.
+    expect(env.payload).toEqual({ message_id: "msg-1" });
+    client.close();
+  });
+
+  it("emitStreamAdd emits message.add with fragments: [{ text: full, delta: new }]", async () => {
+    const transport = new MockTransport();
+    const client = createOpenclawClawlingClient(baseAccount(), { transport });
+    const p = client.connect();
+    await authenticate(transport);
+    await p;
+    transport.sent.length = 0;
+
+    emitStreamAdd(client, {
+      messageId: "msg-1",
+      to: { id: "user-1", type: "direct" },
+      sequence: 3,
+      fullText: "Hello, wor",
+      textDelta: "wor",
+    });
+
+    const env = JSON.parse(transport.sent[0]!);
+    expect(env.event).toBe("message.add");
+    expect(env.payload.sequence).toBe(3);
+    expect(env.payload.fragments).toEqual([
+      { kind: "text", text: "Hello, wor", delta: "wor" },
+    ]);
+    expect(env.payload.mutation).toEqual({ type: "append", target_fragment_index: null });
+    client.close();
+  });
+
+  it("emitStreamDone marks streaming.status = done with completed_at", async () => {
+    const transport = new MockTransport();
+    const client = createOpenclawClawlingClient(baseAccount(), { transport });
+    const p = client.connect();
+    await authenticate(transport);
+    await p;
+    transport.sent.length = 0;
+
+    emitStreamDone(client, {
+      messageId: "msg-1",
+      to: { id: "user-1", type: "direct" },
+      finalSequence: 3,
+      finalText: "Hello",
+    });
+
+    const env = JSON.parse(transport.sent[0]!);
+    expect(env.event).toBe("message.done");
+    expect(env.payload.message_id).toBe("msg-1");
+    expect(env.payload.fragments).toEqual([{ kind: "text", text: "Hello" }]);
+    expect(env.payload.streaming.status).toBe("done");
+    expect(env.payload.streaming.sequence).toBe(3);
+    expect(typeof env.payload.completed_at).toBe("number");
+    client.close();
+  });
+
+  it("emitStreamFailed emits message.failed with reason", async () => {
+    const transport = new MockTransport();
+    const client = createOpenclawClawlingClient(baseAccount(), { transport });
+    const p = client.connect();
+    await authenticate(transport);
+    await p;
+    transport.sent.length = 0;
+
+    emitStreamFailed(client, {
+      messageId: "msg-1",
+      to: { id: "user-1", type: "direct" },
+      sequence: 4,
+      reason: "upstream_error",
+    });
+
+    const env = JSON.parse(transport.sent[0]!);
+    expect(env.event).toBe("message.failed");
+    expect(env.payload.message_id).toBe("msg-1");
+    expect(env.payload.reason).toBe("upstream_error");
+    expect(env.payload.streaming.status).toBe("failed");
+    client.close();
+  });
+});