@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/dist/src/ws-client.js

@@ -0,0 +1,588 @@
+import { EventEmitter } from "node:events";
+import { AckTimeoutError, AuthError, EVENT, MessageSendError, ProtocolError, StateError, TransportError, isBusinessDispatchEvent, } from "./protocol-types.js";
+export function createWebSocketTransport(WebSocketCtor = globalThis.WebSocket) {
+    let currentState = "closed";
+    let socket;
+    return {
+        get state() {
+            return currentState;
+        },
+        async connect(url, handlers) {
+            if (!WebSocketCtor) {
+                throw new TransportError("global WebSocket is not available");
+            }
+            currentState = "connecting";
+            const activeSocket = new WebSocketCtor(url);
+            socket = activeSocket;
+            const isCurrentSocket = () => socket === activeSocket;
+            await new Promise((resolve, reject) => {
+                let opened = false;
+                let settled = false;
+                const rejectBeforeOpen = (err) => {
+                    if (opened || settled)
+                        return;
+                    settled = true;
+                    reject(err);
+                };
+                activeSocket.addEventListener("open", () => {
+                    if (!isCurrentSocket())
+                        return;
+                    opened = true;
+                    settled = true;
+                    currentState = "open";
+                    handlers.onOpen();
+                    resolve();
+                });
+                activeSocket.addEventListener("message", (event) => {
+                    if (!isCurrentSocket())
+                        return;
+                    const data = event?.data;
+                    if (typeof data === "string" || Buffer.isBuffer(data)) {
+                        handlers.onMessage(data);
+                        return;
+                    }
+                    if (data instanceof ArrayBuffer) {
+                        handlers.onMessage(Buffer.from(data));
+                        return;
+                    }
+                    if (ArrayBuffer.isView(data)) {
+                        handlers.onMessage(Buffer.from(data.buffer, data.byteOffset, data.byteLength));
+                        return;
+                    }
+                    handlers.onMessage(String(data ?? ""));
+                });
+                activeSocket.addEventListener("close", (event) => {
+                    if (!isCurrentSocket())
+                        return;
+                    currentState = "closed";
+                    socket = undefined;
+                    const close = event;
+                    const code = typeof close?.code === "number" ? close.code : 1006;
+                    const reason = typeof close?.reason === "string" ? close.reason : "closed";
+                    handlers.onClose(code, reason);
+                    rejectBeforeOpen(new TransportError(reason));
+                });
+                activeSocket.addEventListener("error", (event) => {
+                    if (!isCurrentSocket())
+                        return;
+                    const err = event instanceof Error ? event : new Error("websocket error");
+                    handlers.onError(err);
+                    rejectBeforeOpen(err);
+                });
+            });
+        },
+        send(data) {
+            if (currentState !== "open" || !socket) {
+                throw new StateError(`cannot send while transport=${currentState}`);
+            }
+            socket.send(data);
+        },
+        close(code = 1000, reason = "client close") {
+            if (currentState === "closed")
+                return;
+            socket?.close(code, reason);
+        },
+    };
+}
+export class ClawChatClient extends EventEmitter {
+    opts;
+    currentState = "idle";
+    connectResolve;
+    connectReject;
+    heartbeatTimer;
+    pongTimer;
+    reconnectTimer;
+    reconnectAttempts = 0;
+    closing = false;
+    authFailed = false;
+    expectedConnectTraceId;
+    pending = new Map();
+    handledMessageErrorTraces = new Set();
+    sendQueue = [];
+    constructor(opts) {
+        super();
+        this.opts = opts;
+    }
+    get state() {
+        return this.currentState;
+    }
+    get transportState() {
+        return this.opts.transport.state;
+    }
+    nextTraceId() {
+        return this.opts.traceIdFactory();
+    }
+    hasPendingAckTrace(traceId) {
+        return this.pending.has(traceId);
+    }
+    markMessageErrorHandled(traceId) {
+        this.handledMessageErrorTraces.add(traceId);
+    }
+    async connect() {
+        this.closing = false;
+        this.authFailed = false;
+        const ready = new Promise((resolve, reject) => {
+            this.connectResolve = resolve;
+            this.connectReject = reject;
+        });
+        void this.openTransport();
+        return await ready;
+    }
+    close() {
+        this.closing = true;
+        this.clearTimers();
+        this.rejectPending(new StateError("client closed"));
+        this.sendQueue.length = 0;
+        if (this.opts.transport.state === "closed") {
+            this.transition("disconnected");
+            return;
+        }
+        this.opts.transport.close(1000, "client close");
+    }
+    typing(chatId, isTyping = true) {
+        this.sendRawEnvelope({
+            version: "2",
+            event: EVENT.TYPING_UPDATE,
+            trace_id: this.nextTraceId(),
+            emitted_at: Date.now(),
+            chat_id: chatId,
+            payload: { is_typing: isTyping },
+        });
+    }
+    emitRaw(event, payload, routing) {
+        this.sendRawEnvelope({
+            version: "2",
+            event,
+            trace_id: this.nextTraceId(),
+            emitted_at: Date.now(),
+            ...(routing?.chat_id ? { chat_id: routing.chat_id } : {}),
+            payload,
+        });
+    }
+    sendWire(wire, options = {}) {
+        if (!options.bypassReconnectQueue && this.shouldQueueOutboundWire()) {
+            this.sendQueue.push(wire);
+            return;
+        }
+        if (this.opts.transport.state !== "open") {
+            throw new StateError(`cannot send while transport=${this.opts.transport.state}`);
+        }
+        this.opts.transport.send(wire);
+    }
+    sendRawEnvelope(env) {
+        this.sendWire(JSON.stringify(env), { bypassReconnectQueue: env.event === EVENT.CONNECT });
+    }
+    async sendAckableEnvelope(params) {
+        const traceId = this.nextTraceId();
+        const env = {
+            version: "2",
+            event: params.eventName,
+            trace_id: traceId,
+            emitted_at: Date.now(),
+            chat_id: params.chatId,
+            payload: params.payload,
+        };
+        return await new Promise((resolve, reject) => {
+            const entry = {
+                timer: setTimeout(() => { }, 0),
+                resolve,
+                reject,
+            };
+            const armTimer = () => {
+                entry.timer = setTimeout(() => {
+                    if (this.opts.ack.autoResendOnTimeout && this.opts.transport.state === "open") {
+                        try {
+                            this.sendRawEnvelope(env);
+                            armTimer();
+                            return;
+                        }
+                        catch (err) {
+                            this.pending.delete(traceId);
+                            reject(err instanceof Error ? err : new Error(String(err)));
+                            return;
+                        }
+                    }
+                    this.pending.delete(traceId);
+                    reject(new AckTimeoutError(traceId, this.opts.ack.timeout));
+                }, this.opts.ack.timeout);
+            };
+            armTimer();
+            this.pending.set(traceId, entry);
+            try {
+                this.sendRawEnvelope(env);
+            }
+            catch (err) {
+                clearTimeout(entry.timer);
+                this.pending.delete(traceId);
+                reject(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+    }
+    async openTransport() {
+        this.transition("connecting");
+        try {
+            await this.opts.transport.connect(this.opts.url, {
+                onOpen: () => this.transition("challenging"),
+                onMessage: (data) => this.handleWireMessage(data),
+                onClose: (code, reason) => this.handleClose(code, reason),
+                onError: (err) => this.emitError(new TransportError(err.message)),
+            });
+        }
+        catch (err) {
+            const error = err instanceof Error ? new TransportError(err.message) : new TransportError(String(err));
+            this.emitError(error);
+            if (this.closing || this.authFailed || !this.opts.reconnect.enabled) {
+                this.transition("disconnected");
+                this.connectReject?.(error);
+                return;
+            }
+            this.scheduleReconnect(error.message);
+        }
+    }
+    transition(next) {
+        const from = this.currentState;
+        if (from === next)
+            return;
+        this.currentState = next;
+        this.emit("state", { from, to: next });
+    }
+    handleWireMessage(data) {
+        let env;
+        try {
+            const parsed = JSON.parse(String(data));
+            if (!parsed || typeof parsed !== "object") {
+                throw new ProtocolError("invalid envelope", parsed);
+            }
+            env = parsed;
+            if (env.version !== "2" ||
+                typeof env.event !== "string" ||
+                typeof env.trace_id !== "string" ||
+                typeof env.emitted_at !== "number" ||
+                !Object.prototype.hasOwnProperty.call(env, "payload")) {
+                throw new ProtocolError("invalid envelope", env);
+            }
+        }
+        catch (err) {
+            this.emitError(err instanceof Error ? err : new ProtocolError(String(err)));
+            if (this.isHandshaking()) {
+                this.failHandshake(err instanceof ProtocolError ? err : new ProtocolError(err instanceof Error ? err.message : String(err)), 4002, "protocol error");
+            }
+            return;
+        }
+        this.emit("raw", env);
+        this.dispatchInbound(env);
+    }
+    dispatchInbound(env) {
+        if (env.event === EVENT.CONNECT_CHALLENGE)
+            return this.onChallenge(env);
+        if (env.event === EVENT.HELLO_OK)
+            return this.onHelloOk(env);
+        if (env.event === EVENT.HELLO_FAIL)
+            return this.onHelloFail(env);
+        if (env.event === EVENT.PING)
+            return this.onPing(env);
+        if (env.event === EVENT.PONG)
+            return this.onPong();
+        if (env.event === EVENT.MESSAGE_ACK)
+            return this.onAck(env);
+        if (env.event === EVENT.MESSAGE_ERROR)
+            return this.onMessageError(env);
+        if (isBusinessDispatchEvent(env.event))
+            this.emit("message", env);
+        if (env.event === EVENT.MESSAGE_CREATED)
+            this.emit("message:created", env);
+        if (env.event === EVENT.MESSAGE_ADD)
+            this.emit("message:add", env);
+        if (env.event === EVENT.MESSAGE_DONE)
+            this.emit("message:done", env);
+        if (env.event === EVENT.MESSAGE_FAILED)
+            this.emit("message:failed", env);
+        if (env.event === EVENT.TYPING_UPDATE)
+            this.emit("typing", env);
+        if (env.event === EVENT.CHAT_METADATA_INVALIDATED)
+            this.emit("metadata:invalidated", env);
+        if (env.event === EVENT.OFFLINE_DONE)
+            this.emit("offline:done");
+    }
+    onChallenge(env) {
+        if (this.currentState !== "challenging") {
+            if (this.currentState === "connected" || this.currentState === "reconnecting")
+                return;
+            this.failHandshake(new ProtocolError("unexpected challenge", env), 4002, "protocol error");
+            return;
+        }
+        const payload = env.payload && typeof env.payload === "object" ? env.payload : {};
+        const nonce = payload.nonce;
+        if (typeof nonce !== "string" || !nonce) {
+            this.failHandshake(new ProtocolError("missing challenge nonce", env), 4002, "protocol error");
+            return;
+        }
+        this.transition("authenticating");
+        const connectPayload = {
+            token: this.opts.token,
+            nonce,
+            ...(this.opts.deviceId ? { device_id: this.opts.deviceId } : {}),
+            capabilities: { multi_device: true, device_replay: true, chat_meta_events: true },
+        };
+        const traceId = this.nextTraceId();
+        this.expectedConnectTraceId = traceId;
+        try {
+            this.sendRawEnvelope({
+                version: "2",
+                event: EVENT.CONNECT,
+                trace_id: traceId,
+                emitted_at: Date.now(),
+                payload: connectPayload,
+            });
+        }
+        catch (err) {
+            this.failHandshake(err instanceof Error ? err : new TransportError(String(err)), 4003, "connect send failed");
+        }
+    }
+    onHelloOk(env) {
+        const helloError = this.validateHelloEnvelope(env, "hello-ok");
+        if (helloError) {
+            this.failHandshake(helloError, 4002, "protocol error");
+            return;
+        }
+        this.expectedConnectTraceId = undefined;
+        this.emit("hello:ok", env);
+        this.transition("connected");
+        this.reconnectAttempts = 0;
+        this.startHeartbeat();
+        try {
+            this.flushSendQueue();
+        }
+        catch (err) {
+            this.emitError(err instanceof Error ? err : new TransportError(String(err)));
+            this.opts.transport.close(4000, "queued send failed");
+            return;
+        }
+        this.connectResolve?.();
+        this.connectResolve = undefined;
+        this.connectReject = undefined;
+    }
+    onHelloFail(env) {
+        const helloError = this.validateHelloEnvelope(env, "hello-fail");
+        if (helloError) {
+            this.failHandshake(helloError, 4002, "protocol error");
+            return;
+        }
+        const payload = env.payload && typeof env.payload === "object" ? env.payload : {};
+        const reason = payload.reason;
+        if (typeof reason !== "string" || !reason) {
+            this.failHandshake(new ProtocolError("invalid hello-fail payload", env), 4002, "protocol error");
+            return;
+        }
+        const err = new AuthError(typeof reason === "string" ? reason : "authentication failed");
+        this.authFailed = true;
+        this.expectedConnectTraceId = undefined;
+        this.sendQueue.length = 0;
+        this.clearTimers();
+        this.rejectPending(err);
+        this.connectReject?.(err);
+        this.connectResolve = undefined;
+        this.connectReject = undefined;
+        this.emitError(err);
+        this.transition("disconnected");
+        if (this.opts.transport.state !== "closed") {
+            this.opts.transport.close(4001, "auth failed");
+        }
+    }
+    onPing(env) {
+        this.sendRawEnvelope({
+            version: "2",
+            event: EVENT.PONG,
+            trace_id: env.trace_id,
+            emitted_at: env.emitted_at,
+            payload: {},
+        });
+    }
+    onPong() {
+        if (this.pongTimer)
+            clearTimeout(this.pongTimer);
+        this.pongTimer = undefined;
+    }
+    onAck(env) {
+        const entry = this.pending.get(env.trace_id);
+        if (!entry)
+            return;
+        clearTimeout(entry.timer);
+        this.pending.delete(env.trace_id);
+        entry.resolve(env);
+    }
+    onMessageError(env) {
+        const entry = this.pending.get(env.trace_id);
+        if (!entry) {
+            if (this.handledMessageErrorTraces.delete(env.trace_id))
+                return;
+            console.warn(`clawchat.ws unmatched message.error trace_id=${env.trace_id} chat_id=${env.chat_id ?? "-"}`);
+            return;
+        }
+        clearTimeout(entry.timer);
+        this.pending.delete(env.trace_id);
+        const payload = env.payload && typeof env.payload === "object" ? env.payload : undefined;
+        const code = typeof payload?.code === "string" && payload.code ? payload.code : "unknown";
+        const message = typeof payload?.message === "string" && payload.message ? payload.message : "message send failed";
+        entry.reject(new MessageSendError(env.trace_id, code, message, env.chat_id));
+    }
+    startHeartbeat() {
+        if (!this.opts.heartbeat.enabled)
+            return;
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = setInterval(() => {
+            try {
+                this.sendRawEnvelope({
+                    version: "2",
+                    event: EVENT.PING,
+                    trace_id: this.nextTraceId(),
+                    emitted_at: Date.now(),
+                    payload: {},
+                });
+            }
+            catch {
+                this.opts.transport.close(4000, "heartbeat send failed");
+                return;
+            }
+            if (this.pongTimer)
+                clearTimeout(this.pongTimer);
+            this.pongTimer = setTimeout(() => this.opts.transport.close(4000, "heartbeat timeout"), this.opts.heartbeat.timeout);
+        }, this.opts.heartbeat.interval);
+    }
+    handleClose(code, reason) {
+        if (this.currentState === "reconnecting" && this.reconnectTimer) {
+            if (this.heartbeatTimer)
+                clearInterval(this.heartbeatTimer);
+            if (this.pongTimer)
+                clearTimeout(this.pongTimer);
+            this.heartbeatTimer = undefined;
+            this.pongTimer = undefined;
+            this.emit("close", { code, reason });
+            return;
+        }
+        this.clearTimers();
+        this.emit("close", { code, reason });
+        const closeError = new TransportError(reason || "connection closed");
+        if (!this.closing)
+            this.rejectPending(closeError);
+        if (this.closing || this.authFailed || !this.opts.reconnect.enabled) {
+            this.transition("disconnected");
+            this.connectReject?.(closeError);
+            return;
+        }
+        this.scheduleReconnect(reason || `close ${code}`);
+    }
+    failHandshake(err, code, reason) {
+        this.clearTimers();
+        this.rejectPending(err);
+        this.expectedConnectTraceId = undefined;
+        this.sendQueue.length = 0;
+        this.connectReject?.(err);
+        this.connectResolve = undefined;
+        this.connectReject = undefined;
+        this.emitError(err);
+        this.transition("disconnected");
+        if (this.opts.transport.state !== "closed") {
+            this.closing = true;
+            this.opts.transport.close(code, reason);
+        }
+    }
+    scheduleReconnect(reason) {
+        if (this.reconnectTimer)
+            return;
+        if (this.reconnectAttempts >= this.opts.reconnect.maxRetries) {
+            this.sendQueue.length = 0;
+            this.transition("disconnected");
+            this.connectReject?.(new TransportError(reason));
+            return;
+        }
+        this.reconnectAttempts += 1;
+        const baseDelay = Math.min(this.opts.reconnect.maxDelay, this.opts.reconnect.initialDelay * 2 ** Math.max(0, this.reconnectAttempts - 1));
+        const jitter = baseDelay * this.opts.reconnect.jitterRatio * Math.random();
+        const delay = Math.round(baseDelay + jitter);
+        this.transition("reconnecting");
+        this.emit("reconnect:scheduled", { reason, delay });
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            void this.openTransport();
+        }, delay);
+    }
+    clearTimers() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        if (this.pongTimer)
+            clearTimeout(this.pongTimer);
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.heartbeatTimer = undefined;
+        this.pongTimer = undefined;
+        this.reconnectTimer = undefined;
+    }
+    rejectPending(err) {
+        for (const [traceId, entry] of this.pending) {
+            clearTimeout(entry.timer);
+            this.pending.delete(traceId);
+            entry.reject(err);
+        }
+    }
+    emitError(err) {
+        if (this.listenerCount("error") > 0)
+            this.emit("error", err);
+    }
+    shouldQueueOutboundWire() {
+        if (!this.opts.reconnect.enabled || this.closing || this.authFailed)
+            return false;
+        if (this.currentState === "reconnecting")
+            return true;
+        return this.reconnectAttempts > 0 && this.isHandshaking();
+    }
+    flushSendQueue() {
+        while (this.sendQueue.length > 0) {
+            const wire = this.sendQueue.shift();
+            try {
+                this.sendWire(wire);
+            }
+            catch (err) {
+                this.sendQueue.unshift(wire);
+                throw err;
+            }
+        }
+    }
+    isHandshaking() {
+        return this.currentState === "connecting" || this.currentState === "challenging" || this.currentState === "authenticating";
+    }
+    validateHelloEnvelope(env, eventName) {
+        if (this.currentState !== "authenticating" || env.trace_id !== this.expectedConnectTraceId) {
+            return new ProtocolError(`unexpected ${eventName}`, env);
+        }
+        if (!env.payload || typeof env.payload !== "object") {
+            return new ProtocolError(`invalid ${eventName} payload`, env);
+        }
+        return null;
+    }
+}
+export function createClawChatClient(options) {
+    return new ClawChatClient({
+        ...options,
+        transport: options.transport ?? createWebSocketTransport(),
+        traceIdFactory: options.traceIdFactory ??
+            (() => `trace-${Date.now()}-${Math.random().toString(36).slice(2)}`),
+        reconnect: {
+            enabled: options.reconnect?.enabled ?? true,
+            initialDelay: options.reconnect?.initialDelay ?? 500,
+            maxDelay: options.reconnect?.maxDelay ?? 15000,
+            maxRetries: options.reconnect?.maxRetries ?? Number.POSITIVE_INFINITY,
+            jitterRatio: options.reconnect?.jitterRatio ?? 0.3,
+        },
+        heartbeat: {
+            enabled: options.heartbeat?.enabled ?? true,
+            interval: options.heartbeat?.interval ?? 20000,
+            timeout: options.heartbeat?.timeout ?? 10000,
+        },
+        ack: {
+            timeout: options.ack?.timeout ?? 15000,
+            autoResendOnTimeout: options.ack?.autoResendOnTimeout ?? false,
+        },
+    });
+}

package/dist/src/ws-log.js

@@ -0,0 +1,19 @@
+export function optionalField(value) {
+    if (value === null || value === undefined || value === "")
+        return "-";
+    return String(value);
+}
+export function formatWsLog(input) {
+    const base = [
+        ["event", input.event],
+        ["account_id", input.accountId],
+        ["attempt", input.attempt],
+        ["reconnect_count", input.reconnectCount],
+        ["state", input.state],
+        ["action", input.action],
+    ];
+    return [...base, ...(input.fields ?? [])]
+        .map(([key, value]) => `${key}=${optionalField(value)}`)
+        .join(" ")
+        .replace(/^/, "clawchat.ws ");
+}

package/index.ts

@@ -0,0 +1,24 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { openclawClawlingPlugin } from "./src/channel.ts";
+import { registerOpenclawClawlingCommands } from "./src/commands.ts";
+import { openclawClawlingConfigSchema } from "./src/config.ts";
+import {
+  registerClawChatPromptInjection,
+  type ClawChatPromptInjectionApi,
+} from "./src/prompt-injection.ts";
+import { setOpenclawClawlingRuntime } from "./src/runtime.ts";
+import { registerOpenclawClawlingTools } from "./src/tools.ts";
+
+export default defineChannelPluginEntry({
+  id: "clawchat-plugin-openclaw",
+  name: "Clawling Chat",
+  description: "Clawling Chat Protocol v2 channel plugin",
+  plugin: openclawClawlingPlugin,
+  configSchema: { schema: openclawClawlingConfigSchema },
+  setRuntime: setOpenclawClawlingRuntime,
+  registerFull(api) {
+    registerOpenclawClawlingCommands(api);
+    registerClawChatPromptInjection(api as unknown as ClawChatPromptInjectionApi);
+    registerOpenclawClawlingTools(api);
+  },
+});