@newbase-clawchat/openclaw-clawchat 2026.5.4 → 2026.5.12-13

package/dist/src/outbound.js

@@ -1,3 +1,4 @@
+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";
@@ -5,6 +6,280 @@ import { CHANNEL_ID, resolveOpenclawClawlingAccount } from "./config.js";
 import { textToFragments } from "./message-mapper.js";
 import { uploadOutboundMedia } from "./media-runtime.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.
@@ -19,6 +294,8 @@ import { getOpenclawClawlingClient, getOpenclawClawlingRuntime, waitForOpenclawC
  *   - `clawchat:group:{chat_id}`      → group
  *   - `openclaw-clawchat:direct:{chat_id}` → direct
  *   - `openclaw-clawchat: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) {
@@ -30,6 +307,12 @@ export function parseOpenclawRecipient(to) {
         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(`openclaw-clawchat: missing chat_id in "${to}"`);
+        return { chatId, chatType: scheme };
+    }
     if (scheme !== "cc" && scheme !== "clawchat" && scheme !== CHANNEL_ID) {
         return { chatId: raw, chatType: "direct" };
     }
@@ -56,41 +339,66 @@ export async function sendOpenclawClawlingText(params) {
     }
     const mentions = params.mentions ?? [];
     const textFragments = text ? textToFragments(text) : [];
-    // Cast at the SDK boundary: each MediaItem object is structurally compatible
-    // with one of the SDK's narrow Fragment members (ImageFragment / FileFragment /
+    // 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 = params.replyCtx && mediaFragments.length === 0;
-    if (params.replyCtx && mediaFragments.length > 0) {
-        params.log?.info?.(`[${params.account.accountId}] openclaw-clawchat replyCtx + media: downgraded to sendMessage`);
-    }
+    const useReply = Boolean(params.replyCtx);
+    const messageId = params.messageId;
     let ack;
     let mode;
     if (useReply && params.replyCtx) {
         mode = "reply";
-        ack = await params.client.replyMessage({
-            chat_id: params.to.chatId,
-            mode: "normal",
-            replyTo: {
-                msgId: params.replyCtx.replyToMessageId,
-                senderId: params.replyCtx.replyPreviewChatId ?? params.replyCtx.replyPreviewSenderId,
-                nickName: params.replyCtx.replyPreviewNickName,
-                fragments: [{ kind: "text", text: params.replyCtx.replyPreviewText }],
+        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 }],
+                        },
+                    },
+                },
             },
-            body: { fragments },
-            context: { mentions },
+        };
+        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";
-        ack = await params.client.sendMessage({
-            chat_id: params.to.chatId,
-            mode: "normal",
-            body: { fragments },
-            context: { mentions, reply: null },
+        const payload = {
+            ...(messageId ? { message_id: messageId } : {}),
+            message_mode: "normal",
+            message: {
+                body: { fragments },
+                context: { mentions, reply: null },
+            },
+        };
+        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}] openclaw-clawchat 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,
@@ -117,11 +425,48 @@ export async function sendOpenclawClawlingMedia(params) {
         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;
+    }
+}
 export const openclawClawlingOutbound = {
     deliveryMode: "direct",
     chunker: (text, limit) => chunkMarkdownText(text, limit),
@@ -133,18 +478,38 @@ export const openclawClawlingOutbound = {
             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("openclaw-clawchat sendText requires non-empty text");
+            }
+            const claimed = claimChannelOutbound({
+                account,
+                target,
+                messageId,
+                text: trimmedText,
+                raw: { target, mode: "channel-sendText" },
+            });
+            if (claimed === false) {
+                throw new Error("openclaw-clawchat outbound duplicate claim; message not sent");
+            }
+            if (claimed === null) {
+                throw new Error("openclaw-clawchat outbound message claim failed");
+            }
             const result = await sendOpenclawClawlingText({
                 client,
                 account,
-                to: parseOpenclawRecipient(to),
+                to: target,
                 text,
+                messageId,
             });
             return {
                 to,
-                messageId: result?.messageId ?? `${account.userId}-${Date.now()}`,
+                messageId: result?.messageId ?? messageId,
             };
         },
-        sendMedia: async ({ cfg, to, text, mediaUrl, mediaLocalRoots }) => {
+        sendMedia: async ({ cfg, to, text, mediaUrl, mediaAccess, mediaLocalRoots, mediaReadFile }) => {
             const account = resolveOpenclawClawlingAccount(cfg);
             const client = getOpenclawClawlingClient(account.accountId) ??
                 (await waitForOpenclawClawlingClient(account.accountId));
@@ -160,21 +525,40 @@ export const openclawClawlingOutbound = {
             const mediaFragments = await uploadOutboundMedia([mediaUrl.trim()], {
                 apiClient,
                 runtime,
+                ...(mediaAccess ? { mediaAccess } : {}),
                 ...(mediaLocalRoots ? { mediaLocalRoots } : {}),
+                ...(mediaReadFile ? { mediaReadFile } : {}),
             });
             if (mediaFragments.length === 0) {
                 throw new Error(`openclaw-clawchat 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("openclaw-clawchat outbound duplicate claim; message not sent");
+            }
+            if (claimed === null) {
+                throw new Error("openclaw-clawchat outbound message claim failed");
+            }
             const result = await sendOpenclawClawlingMedia({
                 client,
                 account,
-                to: parseOpenclawRecipient(to),
+                to: target,
                 text,
                 mediaFragments,
+                messageId,
             });
             return {
                 to,
-                messageId: result?.messageId ?? `${account.userId}-${Date.now()}`,
+                messageId: result?.messageId ?? messageId,
             };
         },
     }),

package/dist/src/protocol-types.js

@@ -0,0 +1,63 @@
+export const EVENT = {
+    CONNECT_CHALLENGE: "connect.challenge",
+    CONNECT: "connect",
+    HELLO_OK: "hello-ok",
+    HELLO_FAIL: "hello-fail",
+    MESSAGE_SEND: "message.send",
+    MESSAGE_ACK: "message.ack",
+    MESSAGE_ERROR: "message.error",
+    MESSAGE_REPLY: "message.reply",
+    MESSAGE_CREATED: "message.created",
+    MESSAGE_ADD: "message.add",
+    MESSAGE_DONE: "message.done",
+    MESSAGE_FAILED: "message.failed",
+    TYPING_UPDATE: "typing.update",
+    CHAT_METADATA_INVALIDATED: "chat.metadata.invalidated",
+    OFFLINE_BATCH: "offline.batch",
+    OFFLINE_ACK: "offline.ack",
+    OFFLINE_DONE: "offline.done",
+    PING: "ping",
+    PONG: "pong",
+};
+export class AuthError extends Error {
+    name = "AuthError";
+}
+export class TransportError extends Error {
+    name = "TransportError";
+}
+export class ProtocolError extends Error {
+    envelope;
+    name = "ProtocolError";
+    constructor(message, envelope) {
+        super(message);
+        this.envelope = envelope;
+    }
+}
+export class AckTimeoutError extends Error {
+    traceId;
+    timeoutMs;
+    name = "AckTimeoutError";
+    constructor(traceId, timeoutMs) {
+        super(`ack timeout after ${timeoutMs}ms for trace_id=${traceId}`);
+        this.traceId = traceId;
+        this.timeoutMs = timeoutMs;
+    }
+}
+export class MessageSendError extends Error {
+    traceId;
+    code;
+    chatId;
+    name = "MessageSendError";
+    constructor(traceId, code, message, chatId) {
+        super(`message.error ${code}: ${message} for trace_id=${traceId}`);
+        this.traceId = traceId;
+        this.code = code;
+        this.chatId = chatId;
+    }
+}
+export class StateError extends Error {
+    name = "StateError";
+}
+export function isBusinessDispatchEvent(event) {
+    return event === EVENT.MESSAGE_SEND || event === EVENT.MESSAGE_REPLY || event === EVENT.MESSAGE_DONE;
+}

package/dist/src/protocol-types.typecheck.js

@@ -0,0 +1 @@
+export {};

package/dist/src/protocol.js

@@ -1,8 +1,8 @@
 /**
  * Local narrow guards for inbound protocol envelopes.
  *
- * The SDK's `message` event hands us `Envelope<unknown>`. Before casting the
- * payload to `DownlinkMessageSendPayload` we run these cheap structural checks
+ * Raw client events hand us `Envelope<unknown>`. Before casting the
+ * payload to `MessagePayload` we run these cheap structural checks
  * so runtime errors surface as skipped messages, not crashes.
  */
 export function isInboundMessagePayload(payload) {
@@ -31,8 +31,3 @@ export function hasRenderableText(message) {
             typeof f.url === "string" &&
             f.url.trim().length > 0)));
 }
-export function isGroupSender(sender) {
-    if (!sender || typeof sender !== "object")
-        return false;
-    return sender.type === "group";
-}