@newbase-clawchat/openclaw-clawchat 2026.4.15

package/src/client.ts

@@ -0,0 +1,279 @@
+import {
+  createWSClient,
+  type ClawlingChatClient,
+  type CreateWSClientOptions,
+  type Fragment,
+  type Transport,
+} from "@newbase-clawchat/sdk";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+
+export interface CreateClientOverrides {
+  /** Transport override — only intended for tests (e.g. MockTransport). */
+  transport?: Transport;
+  logger?: CreateWSClientOptions["logger"];
+}
+
+export function createOpenclawClawlingClient(
+  account: ResolvedOpenclawClawlingAccount,
+  overrides: CreateClientOverrides = {},
+): ClawlingChatClient {
+  // Only forward a finite `maxRetries` to the SDK — the SDK's own default
+  // is already unbounded, so omitting the field keeps that behavior. This
+  // avoids forcing the SDK to special-case `Infinity`.
+  const maxRetries = account.reconnect.maxRetries;
+  const reconnect: CreateWSClientOptions["reconnect"] = {
+    enabled: true,
+    initialDelay: account.reconnect.initialDelay,
+    maxDelay: account.reconnect.maxDelay,
+    jitterRatio: account.reconnect.jitterRatio,
+    ...(Number.isFinite(maxRetries) ? { maxRetries } : {}),
+  };
+
+  const options: CreateWSClientOptions = {
+    url: account.websocketUrl,
+    token: account.token,
+    reconnect,
+    heartbeat: {
+      enabled: true,
+      interval: account.heartbeat.interval,
+      timeout: account.heartbeat.timeout,
+    },
+    ack: {
+      timeout: account.ack.timeout,
+      autoResendOnTimeout: account.ack.autoResendOnTimeout,
+    },
+    // Buffer outbound sends during the tiny reconnect window so an inbound
+    // message isn't silently dropped while the socket is flapping.
+    queueWhileReconnecting: true,
+    ...(overrides.transport ? { transport: overrides.transport } : {}),
+    ...(overrides.logger ? { logger: overrides.logger } : {}),
+  };
+  return createWSClient(options);
+}
+
+export type ChatType = "direct" | "group";
+
+export interface StreamSender {
+  id: string;
+  type: ChatType;
+  nick_name: string;
+}
+
+export interface EnvelopeRouting {
+  chatId: string;
+  chatType: ChatType;
+}
+
+/**
+ * Emit a raw v2 envelope directly over the transport so we can carry
+ * `chat_id` + `chat_type` at envelope root (the new protocol). The SDK's
+ * `emitRaw` can't express `chat_type` and always writes `to`; we bypass it
+ * entirely for the events we construct ourselves (streaming lifecycle +
+ * message.reply finalize).
+ */
+function emitEnvelope(
+  client: ClawlingChatClient,
+  event: string,
+  payload: object,
+  routing: EnvelopeRouting,
+): void {
+  const inner = client as unknown as {
+    opts: {
+      transport: { send: (data: string) => void };
+      traceIdFactory: () => string;
+    };
+  };
+  const env = {
+    version: "2" as const,
+    event,
+    trace_id: inner.opts.traceIdFactory(),
+    emitted_at: Date.now(),
+    chat_id: routing.chatId,
+    chat_type: routing.chatType,
+    payload,
+  };
+  inner.opts.transport.send(JSON.stringify(env));
+}
+
+/**
+ * Emit a minimal `message.created` envelope to open a streaming message.
+ *
+ * Payload is intentionally just `{ message_id }`: the message body, context,
+ * sender, and streaming metadata are not transmitted here — they live on the
+ * envelope (`chat_id`, `chat_type`, optional `sender`) and on the subsequent
+ * `message.add` / `message.done` frames.
+ */
+export function emitStreamCreated(
+  client: ClawlingChatClient,
+  params: {
+    messageId: string;
+    routing: EnvelopeRouting;
+  },
+): void {
+  emitEnvelope(
+    client,
+    "message.created",
+    { message_id: params.messageId },
+    params.routing,
+  );
+}
+
+/**
+ * Emit a `message.add` frame with a `fragments` array carrying both the
+ * delta (newly appended text) and the full running text ("from the start
+ * up to now"). Clients rendering the stream can use `delta` for animations
+ * and `text` for the current snapshot.
+ *
+ * Shape: `fragments: [{ kind: "text", text: <cumulative>, delta: <new> }]`
+ */
+export function emitStreamAdd(
+  client: ClawlingChatClient,
+  params: {
+    messageId: string;
+    routing: EnvelopeRouting;
+    sequence: number;
+    /** Running cumulative text after this delta is applied. */
+    fullText: string;
+    /** The newly appended text for this frame. */
+    textDelta: string;
+  },
+): void {
+  const now = Date.now();
+  emitEnvelope(
+    client,
+    "message.add",
+    {
+      message_id: params.messageId,
+      sequence: params.sequence,
+      mutation: { type: "append", target_fragment_index: null },
+      fragments: [
+        { kind: "text", text: params.fullText, delta: params.textDelta },
+      ],
+      streaming: {
+        status: "streaming",
+        sequence: params.sequence,
+        mutation_policy: "append_text_only",
+        started_at: null,
+        completed_at: null,
+      },
+      added_at: now,
+    },
+    params.routing,
+  );
+}
+
+/**
+ * Emit a `message.done` frame with the final merged text included as a
+ * single-element `fragments` array so clients can settle the streamed
+ * message on the full text without re-accumulating deltas.
+ */
+export function emitStreamDone(
+  client: ClawlingChatClient,
+  params: {
+    messageId: string;
+    routing: EnvelopeRouting;
+    finalSequence: number;
+    finalText: string;
+  },
+): void {
+  const now = Date.now();
+  emitEnvelope(
+    client,
+    "message.done",
+    {
+      message_id: params.messageId,
+      fragments: [{ kind: "text", text: params.finalText }],
+      streaming: {
+        status: "done",
+        sequence: params.finalSequence,
+        mutation_policy: "append_text_only",
+        started_at: null,
+        completed_at: now,
+      },
+      completed_at: now,
+    },
+    params.routing,
+  );
+}
+
+/**
+ * Emit a `message.reply` envelope that finalizes a streamed reply, carrying
+ * the same `payload.message_id` as the preceding `message.created` /
+ * `message.add` / `message.done` frames.
+ *
+ * The SDK's high-level `client.replyMessage()` disallows `payload.message_id`
+ * on outbound replies (the server normally assigns one via ack); for the
+ * streaming-finalize use case the backend expects the correlated id, so we
+ * bypass the SDK validator and write directly to the transport.
+ */
+export function emitFinalStreamReply(
+  client: ClawlingChatClient,
+  params: {
+    /** The streaming message_id — must equal the id used on created/add/done. */
+    messageId: string;
+    routing: EnvelopeRouting;
+    /** The user message this stream is a reply to (usually the inbound turn). */
+    replyTo: {
+      msgId: string;
+      senderId: string;
+      nickName: string;
+      fragments: Fragment[];
+    };
+    body: { fragments: Fragment[] };
+    mentions?: string[];
+  },
+): void {
+  emitEnvelope(
+    client,
+    "message.reply",
+    {
+      message_id: params.messageId,
+      message_mode: "normal",
+      message: {
+        body: params.body,
+        context: {
+          mentions: params.mentions ?? [],
+          reply: {
+            reply_to_msg_id: params.replyTo.msgId,
+            reply_preview: {
+              id: params.replyTo.senderId,
+              nick_name: params.replyTo.nickName,
+              fragments: params.replyTo.fragments,
+            },
+          },
+        },
+      },
+    },
+    params.routing,
+  );
+}
+
+export function emitStreamFailed(
+  client: ClawlingChatClient,
+  params: {
+    messageId: string;
+    routing: EnvelopeRouting;
+    sequence: number;
+    reason?: string;
+  },
+): void {
+  const now = Date.now();
+  emitEnvelope(
+    client,
+    "message.failed",
+    {
+      message_id: params.messageId,
+      sequence: params.sequence,
+      reason: params.reason ?? "unknown",
+      streaming: {
+        status: "failed",
+        sequence: params.sequence,
+        mutation_policy: "append_text_only",
+        started_at: null,
+        completed_at: now,
+      },
+      failed_at: now,
+    },
+    params.routing,
+  );
+}

package/src/config.test.ts

@@ -0,0 +1,110 @@
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
+import { describe, expect, it } from "vitest";
+import {
+  CHANNEL_ID,
+  DEFAULT_STREAM,
+  resolveOpenclawClawlingAccount,
+  listOpenclawClawlingAccountIds,
+} from "./config.ts";
+
+describe("openclaw-clawchat config", () => {
+  it("uses correct channel id", () => {
+    expect(CHANNEL_ID).toBe("openclaw-clawchat");
+  });
+
+  it("resolves defaults when no config provided", () => {
+    const account = resolveOpenclawClawlingAccount({});
+    expect(account.accountId).toBe(DEFAULT_ACCOUNT_ID);
+    expect(account.enabled).toBe(true);
+    expect(account.configured).toBe(false);
+    expect(account.replyMode).toBe("static");
+    expect(account.forwardThinking).toBe(true);
+    expect(account.forwardToolCalls).toBe(false);
+    expect(account.stream).toEqual(DEFAULT_STREAM);
+  });
+
+  it("resolves required fields and marks configured=true", () => {
+    const cfg = {
+      channels: {
+        "openclaw-clawchat": {
+          websocketUrl: "wss://chat.example.com/ws",
+          token: "secret",
+          userId: "agent-1",
+          replyMode: "stream",
+          forwardThinking: false,
+          forwardToolCalls: true,
+          stream: { flushIntervalMs: 500, minChunkChars: 50, maxBufferChars: 3000 },
+        },
+      },
+    };
+    const account = resolveOpenclawClawlingAccount(cfg);
+    expect(account.configured).toBe(true);
+    expect(account.websocketUrl).toBe("wss://chat.example.com/ws");
+    expect(account.token).toBe("secret");
+    expect(account.userId).toBe("agent-1");
+    expect(account.replyMode).toBe("stream");
+    expect(account.forwardThinking).toBe(false);
+    expect(account.forwardToolCalls).toBe(true);
+    expect(account.stream.flushIntervalMs).toBe(500);
+    expect(account.stream.minChunkChars).toBe(50);
+    expect(account.stream.maxBufferChars).toBe(3000);
+  });
+
+  it("falls back to static replyMode for unknown values", () => {
+    const cfg = {
+      channels: {
+        "openclaw-clawchat": { websocketUrl: "w", token: "t", userId: "a", replyMode: "weird" },
+      },
+    };
+    const account = resolveOpenclawClawlingAccount(cfg);
+    expect(account.replyMode).toBe("static");
+  });
+
+  it("lists the default account id", () => {
+    expect(listOpenclawClawlingAccountIds()).toEqual([DEFAULT_ACCOUNT_ID]);
+  });
+
+  it("parses baseUrl when provided", () => {
+    const cfg = {
+      channels: {
+        "openclaw-clawchat": {
+          websocketUrl: "wss://w",
+          token: "t",
+          userId: "u",
+          baseUrl: "https://api.example.com",
+        },
+      },
+    };
+    const account = resolveOpenclawClawlingAccount(cfg);
+    expect(account.baseUrl).toBe("https://api.example.com");
+  });
+
+  it("falls back to the built-in DEFAULT_BASE_URL when unset", async () => {
+    const { DEFAULT_BASE_URL } = await import("./config.ts");
+    const account = resolveOpenclawClawlingAccount({});
+    expect(account.baseUrl).toBe(DEFAULT_BASE_URL);
+  });
+
+  it("falls back to the built-in DEFAULT_WEBSOCKET_URL when unset", async () => {
+    const { DEFAULT_WEBSOCKET_URL } = await import("./config.ts");
+    const account = resolveOpenclawClawlingAccount({});
+    expect(account.websocketUrl).toBe(DEFAULT_WEBSOCKET_URL);
+  });
+
+  it("does NOT include baseUrl in the configured predicate (channel still works without it)", async () => {
+    const { DEFAULT_BASE_URL } = await import("./config.ts");
+    const cfg = {
+      channels: {
+        "openclaw-clawchat": {
+          websocketUrl: "wss://w",
+          token: "t",
+          userId: "u",
+          // no baseUrl — resolver uses default
+        },
+      },
+    };
+    const account = resolveOpenclawClawlingAccount(cfg);
+    expect(account.configured).toBe(true);
+    expect(account.baseUrl).toBe(DEFAULT_BASE_URL);
+  });
+});

package/src/config.ts

@@ -0,0 +1,277 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
+
+export const CHANNEL_ID = "openclaw-clawchat" as const;
+
+/**
+ * Built-in defaults for the Clawling Chat endpoints so `openclaw channel
+ * login` works out of the box without requiring a prior `openclaw channel
+ * setup` call. Operators can still override either one via config.
+ *
+ * TODO: replace these placeholders with the production URLs.
+ */
+export const DEFAULT_BASE_URL = "https://api.clawling.chat" as const;
+export const DEFAULT_WEBSOCKET_URL = "wss://api.clawling.chat/ws" as const;
+
+export type ReplyMode = "static" | "stream";
+
+/**
+ * Group-chat trigger policy.
+ * - "mention" (default): only trigger a reply when the inbound `context.mentions`
+ *   list contains our `userId` (i.e. the sender @-mentioned us).
+ * - "all": trigger on every group message regardless of mentions (open listen).
+ */
+export type GroupMode = "mention" | "all";
+
+export const DEFAULT_STREAM = {
+  flushIntervalMs: 250,
+  minChunkChars: 40,
+  maxBufferChars: 2000,
+} as const;
+
+export const DEFAULT_RECONNECT = {
+  // Snappier first retry on transient drops (vs. 1_000).
+  initialDelay: 500,
+  // Cap exponential backoff at 15s — a background gateway reconnecting
+  // every 30s feels unresponsive; 15s is the common IM chat bar.
+  maxDelay: 15_000,
+  // Standard jitter ratio to avoid thundering herd on server restart.
+  jitterRatio: 0.3,
+  // Never give up — the gateway is a long-lived background process.
+  maxRetries: Number.POSITIVE_INFINITY,
+} as const;
+
+export const DEFAULT_HEARTBEAT = {
+  // 20s keeps NAT/firewall state warm without wasting bandwidth.
+  interval: 20_000,
+  // Pong must arrive within 10s or we tear down and reconnect.
+  timeout: 10_000,
+} as const;
+
+export const DEFAULT_ACK = {
+  // 15s tolerates a slow server + one retry without false timeouts.
+  timeout: 15_000,
+  // Keep false: auto-resend on timeout risks duplicate messages; the
+  // reconnect path re-queues via `queueWhileReconnecting` instead.
+  autoResendOnTimeout: false,
+} as const;
+
+export type OpenclawClawlingStreamConfig = {
+  flushIntervalMs?: number;
+  minChunkChars?: number;
+  maxBufferChars?: number;
+};
+
+export type OpenclawClawlingReconnectConfig = {
+  initialDelay?: number;
+  maxDelay?: number;
+  jitterRatio?: number;
+  /** Max reconnect attempts. Omit/Infinity = never give up. */
+  maxRetries?: number;
+};
+
+export type OpenclawClawlingHeartbeatConfig = {
+  interval?: number;
+  timeout?: number;
+};
+
+export type OpenclawClawlingAckConfig = {
+  timeout?: number;
+  autoResendOnTimeout?: boolean;
+};
+
+export type OpenclawClawlingConfig = {
+  enabled?: boolean;
+  websocketUrl?: string;
+  baseUrl?: string;
+  token?: string;
+  /** Refresh token persisted by `openclaw channels login --channel openclaw-clawchat` (paired with `token`). */
+  refreshToken?: string;
+  userId?: string;
+  replyMode?: ReplyMode;
+  groupMode?: GroupMode;
+  forwardThinking?: boolean;
+  forwardToolCalls?: boolean;
+  stream?: OpenclawClawlingStreamConfig;
+  reconnect?: OpenclawClawlingReconnectConfig;
+  heartbeat?: OpenclawClawlingHeartbeatConfig;
+  ack?: OpenclawClawlingAckConfig;
+};
+
+export const openclawClawlingConfigSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    enabled: { type: "boolean" },
+    websocketUrl: { type: "string" },
+    baseUrl: { type: "string" },
+    token: { type: "string" },
+    refreshToken: { type: "string" },
+    userId: { type: "string" },
+    replyMode: { type: "string", enum: ["static", "stream"] },
+    groupMode: { type: "string", enum: ["mention", "all"] },
+    forwardThinking: { type: "boolean" },
+    forwardToolCalls: { type: "boolean" },
+    stream: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        flushIntervalMs: { type: "integer", minimum: 10 },
+        minChunkChars: { type: "integer", minimum: 1 },
+        maxBufferChars: { type: "integer", minimum: 1 },
+      },
+    },
+    reconnect: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        initialDelay: { type: "integer", minimum: 100 },
+        maxDelay: { type: "integer", minimum: 100 },
+        jitterRatio: { type: "number", minimum: 0 },
+        maxRetries: { type: "integer", minimum: 0 },
+      },
+    },
+    heartbeat: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        interval: { type: "integer", minimum: 1000 },
+        timeout: { type: "integer", minimum: 1000 },
+      },
+    },
+    ack: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        timeout: { type: "integer", minimum: 100 },
+        autoResendOnTimeout: { type: "boolean" },
+      },
+    },
+  },
+} as const;
+
+export type ResolvedOpenclawClawlingAccount = {
+  accountId: string;
+  name: string;
+  enabled: boolean;
+  configured: boolean;
+  websocketUrl: string;
+  baseUrl: string;
+  token: string;
+  userId: string;
+  replyMode: ReplyMode;
+  groupMode: GroupMode;
+  forwardThinking: boolean;
+  forwardToolCalls: boolean;
+  allowFrom: string[];
+  stream: Required<OpenclawClawlingStreamConfig>;
+  reconnect: Required<OpenclawClawlingReconnectConfig>;
+  heartbeat: Required<OpenclawClawlingHeartbeatConfig>;
+  ack: Required<OpenclawClawlingAckConfig>;
+};
+
+function readChannelSection(cfg: OpenClawConfig): Record<string, unknown> {
+  const channels = (cfg.channels ?? {}) as Record<string, unknown>;
+  const channel = channels[CHANNEL_ID];
+  return channel && typeof channel === "object" ? (channel as Record<string, unknown>) : {};
+}
+
+function readOptionalString(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function readReplyMode(value: unknown): ReplyMode {
+  return value === "stream" ? "stream" : "static";
+}
+
+function readGroupMode(value: unknown): GroupMode {
+  return value === "all" ? "all" : "mention";
+}
+
+function readStream(raw: unknown): Required<OpenclawClawlingStreamConfig> {
+  const s = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+  return {
+    flushIntervalMs:
+      typeof s.flushIntervalMs === "number" ? s.flushIntervalMs : DEFAULT_STREAM.flushIntervalMs,
+    minChunkChars:
+      typeof s.minChunkChars === "number" ? s.minChunkChars : DEFAULT_STREAM.minChunkChars,
+    maxBufferChars:
+      typeof s.maxBufferChars === "number" ? s.maxBufferChars : DEFAULT_STREAM.maxBufferChars,
+  };
+}
+
+function readReconnect(raw: unknown): Required<OpenclawClawlingReconnectConfig> {
+  const s = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+  return {
+    initialDelay:
+      typeof s.initialDelay === "number" ? s.initialDelay : DEFAULT_RECONNECT.initialDelay,
+    maxDelay: typeof s.maxDelay === "number" ? s.maxDelay : DEFAULT_RECONNECT.maxDelay,
+    jitterRatio: typeof s.jitterRatio === "number" ? s.jitterRatio : DEFAULT_RECONNECT.jitterRatio,
+    maxRetries:
+      typeof s.maxRetries === "number" && Number.isFinite(s.maxRetries)
+        ? s.maxRetries
+        : DEFAULT_RECONNECT.maxRetries,
+  };
+}
+
+function readHeartbeat(raw: unknown): Required<OpenclawClawlingHeartbeatConfig> {
+  const s = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+  return {
+    interval: typeof s.interval === "number" ? s.interval : DEFAULT_HEARTBEAT.interval,
+    timeout: typeof s.timeout === "number" ? s.timeout : DEFAULT_HEARTBEAT.timeout,
+  };
+}
+
+function readAck(raw: unknown): Required<OpenclawClawlingAckConfig> {
+  const s = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+  return {
+    timeout: typeof s.timeout === "number" ? s.timeout : DEFAULT_ACK.timeout,
+    autoResendOnTimeout:
+      typeof s.autoResendOnTimeout === "boolean"
+        ? s.autoResendOnTimeout
+        : DEFAULT_ACK.autoResendOnTimeout,
+  };
+}
+
+export function resolveOpenclawClawlingAccount(
+  cfg: OpenClawConfig,
+): ResolvedOpenclawClawlingAccount {
+  const channel = readChannelSection(cfg);
+  // Apply built-in defaults so login/gateway work without prior setup.
+  const websocketUrl = readOptionalString(channel.websocketUrl) || DEFAULT_WEBSOCKET_URL;
+  const baseUrl = readOptionalString(channel.baseUrl) || DEFAULT_BASE_URL;
+  const token = readOptionalString(channel.token);
+  const userId = readOptionalString(channel.userId);
+  const enabled = typeof channel.enabled === "boolean" ? channel.enabled : true;
+  const replyMode = readReplyMode(channel.replyMode);
+  const groupMode = readGroupMode(channel.groupMode);
+  const forwardThinking =
+    typeof channel.forwardThinking === "boolean" ? channel.forwardThinking : true;
+  const forwardToolCalls =
+    typeof channel.forwardToolCalls === "boolean" ? channel.forwardToolCalls : false;
+
+  return {
+    accountId: DEFAULT_ACCOUNT_ID,
+    name: CHANNEL_ID,
+    enabled,
+    configured: Boolean(websocketUrl && token && userId),
+    websocketUrl,
+    baseUrl,
+    token,
+    userId,
+    replyMode,
+    groupMode,
+    forwardThinking,
+    forwardToolCalls,
+    allowFrom: [],
+    stream: readStream(channel.stream),
+    reconnect: readReconnect(channel.reconnect),
+    heartbeat: readHeartbeat(channel.heartbeat),
+    ack: readAck(channel.ack),
+  };
+}
+
+export function listOpenclawClawlingAccountIds(): string[] {
+  return [DEFAULT_ACCOUNT_ID];
+}
+