@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/dist/src/outbound.js

@@ -0,0 +1,628 @@
+import { MessageSendError } from "./protocol-types.js";
+import { createAttachedChannelResultAdapter, } from "openclaw/plugin-sdk/channel-send-result";
+import { chunkMarkdownText } from "openclaw/plugin-sdk/reply-runtime";
+import { createOpenclawClawlingApiClient } from "./api-client.js";
+import { CHANNEL_ID, resolveOpenclawClawlingAccount } from "./config.js";
+import { applyTextMentionLabels, buildMentionMessageFragments, normalizeMentionTargets, textToFragments, } from "./message-mapper.js";
+import { uploadOutboundMedia } from "./media-runtime.js";
+import { isClawChatNoopResponseText } from "./profile-prompt.js";
+import { getOpenclawClawlingClient, getOpenclawClawlingRuntime, waitForOpenclawClawlingClient, } from "./runtime.js";
+import { clawChatDbPathForStateDir, getClawChatStore, } from "./storage.js";
+import { createAlignedWsQueue } from "./ws-alignment.js";
+import { formatWsLog } from "./ws-log.js";
+const alignedOutboundQueues = new WeakMap();
+const alignedOutboundContexts = new WeakMap();
+const alignedOutboundMessageErrorTrackers = new WeakMap();
+const alignedOutboundCloseHandlers = new WeakMap();
+const alignedOutboundStateHandlers = new WeakMap();
+function addAlignedOutboundCloseHandler(client, handler) {
+    const key = client;
+    let entry = alignedOutboundCloseHandlers.get(key);
+    if (!entry) {
+        const handlers = new Set();
+        const listener = (close) => {
+            for (const current of [...handlers])
+                current(close);
+        };
+        entry = { handlers, listener };
+        alignedOutboundCloseHandlers.set(key, entry);
+        client.on("close", listener);
+    }
+    entry.handlers.add(handler);
+    return () => {
+        entry?.handlers.delete(handler);
+    };
+}
+function addAlignedOutboundStateHandler(client, handler) {
+    const key = client;
+    let entry = alignedOutboundStateHandlers.get(key);
+    if (!entry) {
+        const handlers = new Set();
+        const listener = (state) => {
+            for (const current of [...handlers])
+                current(state);
+        };
+        entry = { handlers, listener };
+        alignedOutboundStateHandlers.set(key, entry);
+        client.on("state", listener);
+    }
+    entry.handlers.add(handler);
+    return () => {
+        entry?.handlers.delete(handler);
+    };
+}
+function getAlignedOutboundQueue(client, account, log) {
+    const existing = alignedOutboundQueues.get(client);
+    if (existing)
+        return existing;
+    const queue = createAlignedWsQueue({
+        accountId: account.accountId,
+        log: (msg) => log?.info?.(msg),
+        maxSize: 128,
+        context: () => alignedOutboundContexts.get(client)?.() ?? {
+            attempt: 1,
+            reconnectCount: 0,
+            state: "ready",
+        },
+    });
+    alignedOutboundQueues.set(client, queue);
+    return queue;
+}
+function getAlignedMessageErrorTracker(client, account, log) {
+    const key = client;
+    const existing = alignedOutboundMessageErrorTrackers.get(key);
+    if (existing)
+        return existing;
+    const pending = new Set();
+    const listener = (env) => {
+        if (env.event !== "message.error")
+            return;
+        if (pending.has(env.trace_id)) {
+            client.markMessageErrorHandled?.(env.trace_id);
+            return;
+        }
+        if (client.hasPendingAckTrace?.(env.trace_id)) {
+            return;
+        }
+        const context = alignedOutboundContexts.get(key)?.() ?? {
+            attempt: 1,
+            reconnectCount: 0,
+            state: client.transportState === "open" ? "ready" : "reconnecting",
+        };
+        if (log?.info) {
+            log.info(formatWsLog({
+                event: "ack_unmatched",
+                accountId: account.accountId,
+                attempt: context.attempt,
+                reconnectCount: context.reconnectCount,
+                state: context.state,
+                action: "ignore",
+                fields: [
+                    ["trace_id", env.trace_id],
+                    ["chat_id", env.chat_id],
+                ],
+            }));
+            client.markMessageErrorHandled?.(env.trace_id);
+        }
+    };
+    client.on("raw", listener);
+    const tracker = { pending, listener };
+    alignedOutboundMessageErrorTrackers.set(key, tracker);
+    return tracker;
+}
+export function setAlignedOutboundLogContext(client, context) {
+    alignedOutboundContexts.set(client, context);
+}
+export function flushAlignedOutboundQueue(client) {
+    const queue = alignedOutboundQueues.get(client);
+    queue?.flush((wire) => client.sendWire(wire));
+}
+export function getAlignedOutboundQueueSize(client) {
+    return alignedOutboundQueues.get(client)?.snapshot().length ?? 0;
+}
+async function sendAlignedAckableEnvelope(params) {
+    const traceId = params.client.nextTraceId();
+    const env = {
+        version: "2",
+        event: params.eventName,
+        trace_id: traceId,
+        emitted_at: Date.now(),
+        chat_id: params.chatId,
+        payload: params.payload,
+    };
+    const wire = JSON.stringify(env);
+    const queue = getAlignedOutboundQueue(params.client, params.account, params.log);
+    const messageErrorTracker = getAlignedMessageErrorTracker(params.client, params.account, params.log);
+    const isReady = () => {
+        const state = params.client.state;
+        return params.client.transportState === "open" && (!state || state === "connected");
+    };
+    const isDisconnected = () => params.client.state === "disconnected";
+    return await new Promise((resolve, reject) => {
+        let state = "queued";
+        let timer;
+        let rawListenerRegistered = false;
+        let removeCloseListener;
+        let removeStateListener;
+        const clearAckTimer = () => {
+            if (!timer)
+                return;
+            clearTimeout(timer);
+            timer = undefined;
+        };
+        const removeRawListener = () => {
+            if (!rawListenerRegistered)
+                return;
+            params.client.off("raw", onRaw);
+            rawListenerRegistered = false;
+        };
+        const cleanup = () => {
+            messageErrorTracker.pending.delete(traceId);
+            clearAckTimer();
+            removeRawListener();
+            removeCloseListener?.();
+            removeCloseListener = undefined;
+            removeStateListener?.();
+            removeStateListener = undefined;
+        };
+        const fail = (err) => {
+            if (state === "acked" || state === "failed")
+                return;
+            state = "failed";
+            cleanup();
+            reject(err);
+        };
+        const logAck = (event, action, fields) => {
+            params.log?.info?.(formatWsLog({
+                event,
+                accountId: params.account.accountId,
+                ...(alignedOutboundContexts.get(params.client)?.() ?? {
+                    attempt: 1,
+                    reconnectCount: 0,
+                    state: isReady() ? "ready" : "reconnecting",
+                }),
+                action,
+                fields: [
+                    ["event_name", params.eventName],
+                    ["trace_id", traceId],
+                    ["chat_id", params.chatId],
+                    ...fields,
+                ],
+            }));
+        };
+        function onRaw(ack) {
+            if (ack.trace_id !== traceId)
+                return;
+            if (ack.event === "message.error") {
+                if (state === "acked" || state === "failed")
+                    return;
+                const payload = ack.payload;
+                const code = typeof payload.code === "string" && payload.code ? payload.code : "unknown";
+                const message = typeof payload.message === "string" && payload.message ? payload.message : "message send failed";
+                fail(new MessageSendError(traceId, code, message, ack.chat_id));
+                return;
+            }
+            if (ack.event !== "message.ack")
+                return;
+            if (state === "acked" || state === "failed")
+                return;
+            state = "acked";
+            cleanup();
+            const payload = ack.payload;
+            logAck("ack_received", "resolve", [["message_id", payload.message_id]]);
+            resolve(ack);
+        }
+        const startAckTimer = () => {
+            if (state === "acked" || state === "failed")
+                return;
+            state = "written_waiting_ack";
+            messageErrorTracker.pending.add(traceId);
+            clearAckTimer();
+            removeRawListener();
+            params.client.on("raw", onRaw);
+            rawListenerRegistered = true;
+            timer = setTimeout(() => {
+                logAck("ack_timeout", "reject_no_reconnect", [["timeout_ms", params.account.ack.timeout]]);
+                fail(new Error(`ack timeout after ${params.account.ack.timeout}ms for trace_id=${traceId}`));
+            }, params.account.ack.timeout);
+        };
+        const item = {
+            eventName: params.eventName,
+            traceId,
+            chatId: params.chatId,
+            wire,
+            onWrite: startAckTimer,
+            onDrop: () => {
+                fail(new Error(`send queue full; dropped ${params.eventName} before write for trace_id=${traceId}`));
+            },
+        };
+        function isTerminalClose(close) {
+            return close?.code === 1000 || close?.reason === "client close" || close?.reason === "auth failed";
+        }
+        function onClose(close) {
+            if (state === "acked" || state === "failed")
+                return;
+            if (isTerminalClose(close)) {
+                const reason = typeof close?.reason === "string" && close.reason ? close.reason : "websocket closed";
+                queue.remove(item);
+                fail(new Error(`send cancelled because ${reason}`));
+                return;
+            }
+            if (state !== "written_waiting_ack")
+                return;
+            clearAckTimer();
+            removeRawListener();
+            state = "queued";
+            queue.enqueue(item);
+        }
+        function onState(next) {
+            if (state === "acked" || state === "failed" || next?.to !== "disconnected")
+                return;
+            queue.remove(item);
+            fail(new Error("send cancelled because client disconnected"));
+        }
+        removeCloseListener = addAlignedOutboundCloseHandler(params.client, onClose);
+        removeStateListener = addAlignedOutboundStateHandler(params.client, onState);
+        if (!isReady()) {
+            if (isDisconnected()) {
+                fail(new Error("send cancelled because client disconnected"));
+                return;
+            }
+            queue.enqueue(item);
+            return;
+        }
+        try {
+            queue.enqueue(item);
+            queue.flush((queuedWire) => params.client.sendWire(queuedWire));
+        }
+        catch {
+            // The queue keeps the failed frame at the head for reconnect retry, so
+            // keep this promise pending until the frame is written+acked, dropped, or timed out.
+        }
+    });
+}
+/**
+ * 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
+ *   - `clawchat-plugin-openclaw:{chat_id}`   → direct
+ *   - `cc:direct:{chat_id}`           → direct
+ *   - `cc:group:{chat_id}`            → group
+ *   - `clawchat:direct:{chat_id}`     → direct
+ *   - `clawchat:group:{chat_id}`      → group
+ *   - `clawchat-plugin-openclaw:direct:{chat_id}` → direct
+ *   - `clawchat-plugin-openclaw:group:{chat_id}`  → group
+ *   - `direct:{chat_id}`              → direct (host-normalized)
+ *   - `group:{chat_id}`               → group (host-normalized)
+ *   - bare `{chat_id}`                → direct (backward compat)
+ */
+export function parseOpenclawRecipient(to) {
+    const raw = (to ?? "").trim();
+    if (!raw)
+        throw new Error("clawchat-plugin-openclaw: outbound `to` is empty");
+    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 === "direct" || scheme === "group") {
+        const chatId = rest.trim();
+        if (!chatId)
+            throw new Error(`clawchat-plugin-openclaw: missing chat_id in "${to}"`);
+        return { chatId, chatType: scheme };
+    }
+    if (scheme !== "cc" && scheme !== "clawchat" && scheme !== CHANNEL_ID) {
+        return { chatId: raw, chatType: "direct" };
+    }
+    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 };
+        }
+    }
+    const chatId = rest.trim();
+    if (!chatId)
+        throw new Error(`clawchat-plugin-openclaw: missing chat_id in "${to}"`);
+    return { chatId, chatType: "direct" };
+}
+export async function sendOpenclawClawlingText(params) {
+    const text = (params.text ?? "").trim();
+    const richFragments = params.richFragments ?? [];
+    const mediaFragments = params.mediaFragments ?? [];
+    if (isClawChatNoopResponseText(text) &&
+        richFragments.length === 0 &&
+        mediaFragments.length === 0) {
+        params.log?.info?.(`[${params.account.accountId}] clawchat-plugin-openclaw outbound suppressed: silent response`);
+        return null;
+    }
+    if (!text && richFragments.length === 0 && mediaFragments.length === 0) {
+        params.log?.info?.(`[${params.account.accountId}] clawchat-plugin-openclaw outbound suppressed: empty text and no media`);
+        return null;
+    }
+    const mentions = params.mentions ?? [];
+    const textFragments = text ? textToFragments(text) : [];
+    // Each MediaItem object is structurally compatible
+    // with one of the local narrow Fragment members (ImageFragment / FileFragment /
+    // AudioFragment / VideoFragment) based on its runtime `kind`. The wide local
+    // shape lets us build a single uniform array without a per-kind switch.
+    const fragments = [...textFragments, ...richFragments, ...mediaFragments];
+    const useReply = Boolean(params.replyCtx?.replyPreviewSenderId
+        && params.replyCtx.replyPreviewNickName
+        && params.replyCtx.replyPreviewText);
+    const messageId = params.messageId;
+    let ack;
+    let mode;
+    if (useReply && params.replyCtx) {
+        mode = "reply";
+        const payload = {
+            ...(messageId ? { message_id: messageId } : {}),
+            message_mode: "normal",
+            message: {
+                body: { fragments },
+                context: {
+                    mentions,
+                    reply: {
+                        reply_to_msg_id: params.replyCtx.replyToMessageId,
+                        reply_preview: {
+                            id: params.replyCtx.replyPreviewSenderId,
+                            nick_name: params.replyCtx.replyPreviewNickName,
+                            fragments: [{ kind: "text", text: params.replyCtx.replyPreviewText }],
+                        },
+                    },
+                },
+            },
+        };
+        ack = await sendAlignedAckableEnvelope({
+            client: params.client,
+            account: params.account,
+            eventName: "message.reply",
+            chatId: params.to.chatId,
+            payload,
+            ...(params.log ? { log: params.log } : {}),
+        });
+    }
+    else {
+        mode = "send";
+        const reply = params.replyCtx
+            ? {
+                reply_to_msg_id: params.replyCtx.replyToMessageId,
+                reply_preview: null,
+            }
+            : null;
+        const payload = {
+            ...(messageId ? { message_id: messageId } : {}),
+            message_mode: "normal",
+            message: {
+                body: { fragments },
+                context: { mentions, reply },
+            },
+        };
+        ack = await sendAlignedAckableEnvelope({
+            client: params.client,
+            account: params.account,
+            eventName: "message.send",
+            chatId: params.to.chatId,
+            payload,
+            ...(params.log ? { log: params.log } : {}),
+        });
+    }
+    if (messageId && ack.payload.message_id !== messageId) {
+        throw new Error(`ack message_id mismatch: expected ${messageId} got ${ack.payload.message_id}`);
+    }
+    params.log?.info?.(`[${params.account.accountId}] clawchat-plugin-openclaw outbound mode=${mode} msg=${ack.payload.message_id} text_len=${text.length} media=${mediaFragments.length} trace=${ack.trace_id}`);
+    return {
+        messageId: ack.payload.message_id,
+        acceptedAt: ack.payload.accepted_at,
+    };
+}
+export async function sendOpenclawClawlingMentionMessage(params) {
+    const normalized = normalizeMentionTargets(params.mentions);
+    const prepared = applyTextMentionLabels(normalized, params.text);
+    const fragments = buildMentionMessageFragments({
+        mentions: prepared.mentions,
+        ...(prepared.text ? { text: prepared.text } : {}),
+    });
+    const contextMentions = prepared.mentions.map((mention) => ({
+        kind: "mention",
+        user_id: mention.userId,
+        ...(mention.display ? { display: mention.display } : {}),
+    }));
+    const mentionIds = prepared.mentions.map((mention) => mention.userId);
+    const result = await sendOpenclawClawlingText({
+        client: params.client,
+        account: params.account,
+        to: params.to,
+        text: "",
+        richFragments: fragments,
+        mentions: contextMentions,
+        ...(params.messageId ? { messageId: params.messageId } : {}),
+        ...(params.replyCtx ? { replyCtx: params.replyCtx } : {}),
+        ...(params.log ? { log: params.log } : {}),
+    });
+    if (!result)
+        return null;
+    return { ...result, mentions: mentionIds };
+}
+/**
+ * Send one or more media fragments (image / file / audio / video) to the
+ * given target, with an optional text caption.
+ *
+ * Validates that mediaFragments is non-empty (returns null + info log
+ * otherwise) and delegates to {@link sendOpenclawClawlingText} for the
+ * actual envelope construction. Reuses the existing replyCtx-downgrade,
+ * ack backfill, and log shape.
+ */
+export async function sendOpenclawClawlingMedia(params) {
+    if (params.mediaFragments.length === 0) {
+        params.log?.info?.(`[${params.account.accountId}] clawchat-plugin-openclaw sendMedia called with empty mediaFragments; suppressed`);
+        return null;
+    }
+    return await sendOpenclawClawlingText({
+        client: params.client,
+        account: params.account,
+        to: params.to,
+        text: params.text ?? "",
+        mediaFragments: params.mediaFragments,
+        ...(params.messageId ? { messageId: params.messageId } : {}),
+        ...(params.replyCtx ? { replyCtx: params.replyCtx } : {}),
+        ...(params.mentions ? { mentions: params.mentions } : {}),
+        ...(params.log ? { log: params.log } : {}),
+    });
+}
+function mintOutboundMessageId(account) {
+    return `${account.userId}-msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function resolveChannelOutboundStore() {
+    try {
+        const runtime = getOpenclawClawlingRuntime();
+        const stateDir = runtime.state?.resolveStateDir?.();
+        return getClawChatStore({
+            ...(stateDir ? { dbPath: clawChatDbPathForStateDir(stateDir) } : {}),
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function claimChannelOutbound(params) {
+    const store = resolveChannelOutboundStore();
+    if (!store)
+        return null;
+    try {
+        return store.claimMessageOnce({
+            platform: "openclaw",
+            accountId: params.account.accountId,
+            kind: "message",
+            direction: "outbound",
+            eventType: "message.send",
+            chatId: params.target.chatId,
+            messageId: params.messageId,
+            text: params.text,
+            raw: params.raw,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function markChannelOutboundAcknowledged(params) {
+    const store = resolveChannelOutboundStore();
+    if (!store || !params.result?.messageId)
+        return;
+    try {
+        store.markMessageAcknowledged?.({
+            accountId: params.account.accountId,
+            kind: "message",
+            direction: "outbound",
+            messageId: params.messageId,
+            protocolMessageId: params.result.messageId,
+            ackedAt: params.result.acceptedAt ?? Date.now(),
+        });
+    }
+    catch {
+        // Best-effort diagnostics only; ack has already succeeded.
+    }
+}
+export const openclawClawlingOutbound = {
+    deliveryMode: "direct",
+    chunker: (text, limit) => chunkMarkdownText(text, limit),
+    chunkerMode: "markdown",
+    textChunkLimit: 4000,
+    ...createAttachedChannelResultAdapter({
+        channel: CHANNEL_ID,
+        sendText: async ({ cfg, to, text }) => {
+            const account = resolveOpenclawClawlingAccount(cfg);
+            const client = getOpenclawClawlingClient(account.accountId) ??
+                (await waitForOpenclawClawlingClient(account.accountId));
+            const target = parseOpenclawRecipient(to);
+            const messageId = mintOutboundMessageId(account);
+            const trimmedText = text.trim();
+            if (!trimmedText) {
+                throw new Error("clawchat-plugin-openclaw sendText requires non-empty text");
+            }
+            const claimed = claimChannelOutbound({
+                account,
+                target,
+                messageId,
+                text: trimmedText,
+                raw: { target, mode: "channel-sendText" },
+            });
+            if (claimed === false) {
+                throw new Error("clawchat-plugin-openclaw outbound duplicate claim; message not sent");
+            }
+            if (claimed === null) {
+                throw new Error("clawchat-plugin-openclaw outbound message claim failed");
+            }
+            const result = await sendOpenclawClawlingText({
+                client,
+                account,
+                to: target,
+                text,
+                messageId,
+            });
+            markChannelOutboundAcknowledged({ account, messageId, result });
+            return {
+                to,
+                messageId: result?.messageId ?? messageId,
+            };
+        },
+        sendMedia: async ({ cfg, to, text, mediaUrl, mediaAccess, mediaLocalRoots, mediaReadFile }) => {
+            const account = resolveOpenclawClawlingAccount(cfg);
+            const client = getOpenclawClawlingClient(account.accountId) ??
+                (await waitForOpenclawClawlingClient(account.accountId));
+            if (!mediaUrl?.trim()) {
+                throw new Error("clawchat-plugin-openclaw sendMedia requires mediaUrl");
+            }
+            const runtime = getOpenclawClawlingRuntime();
+            const apiClient = createOpenclawClawlingApiClient({
+                baseUrl: account.baseUrl,
+                token: account.token,
+                userId: account.userId,
+            });
+            const mediaFragments = await uploadOutboundMedia([mediaUrl.trim()], {
+                apiClient,
+                runtime,
+                ...(mediaAccess ? { mediaAccess } : {}),
+                ...(mediaLocalRoots ? { mediaLocalRoots } : {}),
+                ...(mediaReadFile ? { mediaReadFile } : {}),
+            });
+            if (mediaFragments.length === 0) {
+                throw new Error(`clawchat-plugin-openclaw failed to upload media: ${mediaUrl}`);
+            }
+            const target = parseOpenclawRecipient(to);
+            const messageId = mintOutboundMessageId(account);
+            const claimText = (text ?? "").trim();
+            const claimed = claimChannelOutbound({
+                account,
+                target,
+                messageId,
+                text: claimText,
+                raw: { target, mode: "channel-sendMedia", mediaCount: mediaFragments.length },
+            });
+            if (claimed === false) {
+                throw new Error("clawchat-plugin-openclaw outbound duplicate claim; message not sent");
+            }
+            if (claimed === null) {
+                throw new Error("clawchat-plugin-openclaw outbound message claim failed");
+            }
+            const result = await sendOpenclawClawlingMedia({
+                client,
+                account,
+                to: target,
+                text,
+                mediaFragments,
+                messageId,
+            });
+            markChannelOutboundAcknowledged({ account, messageId, result });
+            return {
+                to,
+                messageId: result?.messageId ?? messageId,
+            };
+        },
+    }),
+};