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

package/src/outbound.ts

@@ -1,4 +1,5 @@
-import type { ClawlingChatClient, Envelope, Fragment, MessageAckPayload } from "@newbase-clawchat/sdk";
+import { MessageSendError, type Envelope, type Fragment, type MessageAckPayload, type MessageErrorPayload } from "./protocol-types.ts";
+import type { ClawlingChatClient } from "./ws-client.ts";
 import {
   createAttachedChannelResultAdapter,
   type ChannelOutboundAdapter,
@@ -14,6 +15,13 @@ import {
   getOpenclawClawlingRuntime,
   waitForOpenclawClawlingClient,
 } from "./runtime.ts";
+import {
+  clawChatDbPathForStateDir,
+  getClawChatStore,
+  type ClawChatStore,
+} from "./storage.ts";
+import { createAlignedWsQueue, type WsLogContext } from "./ws-alignment.ts";
+import { formatWsLog } from "./ws-log.ts";
 
 export interface OutboundTarget {
   chatId: string;
@@ -42,6 +50,7 @@ export interface SendParams {
   richFragments?: Fragment[];
   mediaFragments?: ClawlingMediaFragment[];
   mentions?: string[];
+  messageId?: string;
   log?: LogSink;
 }
 
@@ -50,6 +59,333 @@ export interface SendResult {
   acceptedAt: number;
 }
 
+const alignedOutboundQueues = new WeakMap<object, ReturnType<typeof createAlignedWsQueue>>();
+const alignedOutboundContexts = new WeakMap<object, () => WsLogContext>();
+const alignedOutboundMessageErrorTrackers = new WeakMap<object, {
+  pending: Set<string>;
+  listener: (env: Envelope) => void;
+}>();
+type AlignedOutboundClose = { code?: unknown; reason?: unknown } | undefined;
+type AlignedOutboundCloseHandler = (close?: AlignedOutboundClose) => void;
+type AlignedOutboundState = { to?: unknown } | undefined;
+type AlignedOutboundStateHandler = (state?: AlignedOutboundState) => void;
+const alignedOutboundCloseHandlers = new WeakMap<
+  object,
+  { handlers: Set<AlignedOutboundCloseHandler>; listener: AlignedOutboundCloseHandler }
+>();
+const alignedOutboundStateHandlers = new WeakMap<
+  object,
+  { handlers: Set<AlignedOutboundStateHandler>; listener: AlignedOutboundStateHandler }
+>();
+
+function addAlignedOutboundCloseHandler(
+  client: ClawlingChatClient,
+  handler: AlignedOutboundCloseHandler,
+): () => void {
+  const key = client as object;
+  let entry = alignedOutboundCloseHandlers.get(key);
+  if (!entry) {
+    const handlers = new Set<AlignedOutboundCloseHandler>();
+    const listener: AlignedOutboundCloseHandler = (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: ClawlingChatClient,
+  handler: AlignedOutboundStateHandler,
+): () => void {
+  const key = client as object;
+  let entry = alignedOutboundStateHandlers.get(key);
+  if (!entry) {
+    const handlers = new Set<AlignedOutboundStateHandler>();
+    const listener: AlignedOutboundStateHandler = (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: ClawlingChatClient,
+  account: ResolvedOpenclawClawlingAccount,
+  log: LogSink | undefined,
+) {
+  const existing = alignedOutboundQueues.get(client as object);
+  if (existing) return existing;
+  const queue = createAlignedWsQueue({
+    accountId: account.accountId,
+    log: (msg) => log?.info?.(msg),
+    maxSize: 128,
+    context: () => alignedOutboundContexts.get(client as object)?.() ?? {
+      attempt: 1,
+      reconnectCount: 0,
+      state: "ready",
+    },
+  });
+  alignedOutboundQueues.set(client as object, queue);
+  return queue;
+}
+
+function getAlignedMessageErrorTracker(
+  client: ClawlingChatClient,
+  account: ResolvedOpenclawClawlingAccount,
+  log: LogSink | undefined,
+) {
+  const key = client as object;
+  const existing = alignedOutboundMessageErrorTrackers.get(key);
+  if (existing) return existing;
+  const pending = new Set<string>();
+  const listener = (env: Envelope) => {
+    if (env.event !== "message.error") return;
+    if (pending.has(env.trace_id)) {
+      (client as { markMessageErrorHandled?: (traceId: string) => void }).markMessageErrorHandled?.(env.trace_id);
+      return;
+    }
+    if ((client as { hasPendingAckTrace?: (traceId: string) => boolean }).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 as { markMessageErrorHandled?: (traceId: string) => void }).markMessageErrorHandled?.(env.trace_id);
+    }
+  };
+  client.on("raw", listener);
+  const tracker = { pending, listener };
+  alignedOutboundMessageErrorTrackers.set(key, tracker);
+  return tracker;
+}
+
+export function setAlignedOutboundLogContext(
+  client: ClawlingChatClient,
+  context: () => WsLogContext,
+): void {
+  alignedOutboundContexts.set(client as object, context);
+}
+
+export function flushAlignedOutboundQueue(client: ClawlingChatClient): void {
+  const queue = alignedOutboundQueues.get(client as object);
+  queue?.flush((wire) => client.sendWire(wire));
+}
+
+export function getAlignedOutboundQueueSize(client: ClawlingChatClient): number {
+  return alignedOutboundQueues.get(client as object)?.snapshot().length ?? 0;
+}
+
+async function sendAlignedAckableEnvelope(params: {
+  client: ClawlingChatClient;
+  account: ResolvedOpenclawClawlingAccount;
+  eventName: "message.send" | "message.reply";
+  chatId: string;
+  payload: object;
+  log?: LogSink;
+}): Promise<Envelope<MessageAckPayload>> {
+  const traceId = params.client.nextTraceId();
+  const env = {
+    version: "2" as const,
+    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 as { state?: string }).state;
+    return params.client.transportState === "open" && (!state || state === "connected");
+  };
+  const isDisconnected = () => (params.client as { state?: string }).state === "disconnected";
+
+  type AckableSendState = "queued" | "written_waiting_ack" | "acked" | "failed";
+
+  return await new Promise<Envelope<MessageAckPayload>>((resolve, reject) => {
+    let state: AckableSendState = "queued";
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let rawListenerRegistered = false;
+    let removeCloseListener: (() => void) | undefined;
+    let removeStateListener: (() => void) | undefined;
+
+    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: Error) => {
+      if (state === "acked" || state === "failed") return;
+      state = "failed";
+      cleanup();
+      reject(err);
+    };
+
+    const logAck = (
+      event: "ack_received" | "ack_timeout",
+      action: "resolve" | "reject_no_reconnect",
+      fields: Array<[string, string | number | boolean | null | undefined]>,
+    ) => {
+      params.log?.info?.(
+        formatWsLog({
+          event,
+          accountId: params.account.accountId,
+          ...(
+            alignedOutboundContexts.get(params.client as object)?.() ?? {
+              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: Envelope) {
+      if (ack.trace_id !== traceId) return;
+      if (ack.event === "message.error") {
+        if (state === "acked" || state === "failed") return;
+        const payload = ack.payload as Partial<MessageErrorPayload>;
+        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 as MessageAckPayload;
+      logAck("ack_received", "resolve", [["message_id", payload.message_id]]);
+      resolve(ack as Envelope<MessageAckPayload>);
+    }
+
+    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: AlignedOutboundClose): boolean {
+      return close?.code === 1000 || close?.reason === "client close" || close?.reason === "auth failed";
+    }
+
+    function onClose(close?: AlignedOutboundClose) {
+      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?: AlignedOutboundState) {
+      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.
@@ -64,6 +400,8 @@ export interface SendResult {
  *   - `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: string): { chatId: string; chatType: ChatType } {
@@ -75,6 +413,11 @@ export function parseOpenclawRecipient(to: string): { chatId: string; chatType:
 
   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" };
   }
@@ -105,43 +448,68 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
 
   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] as Fragment[];
 
-  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: Envelope<MessageAckPayload>;
   let mode: "send" | "reply";
   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 },
-    } as Parameters<ClawlingChatClient["replyMessage"]>[0]);
+    };
+    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 },
-    } as Parameters<ClawlingChatClient["sendMessage"]>[0]);
+    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}`,
@@ -161,6 +529,7 @@ export interface SendMediaParams {
   text?: string;
   replyCtx?: OutboundReplyCtx;
   mentions?: string[];
+  messageId?: string;
   log?: LogSink;
 }
 
@@ -188,12 +557,57 @@ export async function sendOpenclawClawlingMedia(
     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 } : {}),
   });
 }
 
+type OutboundClaimStore = Pick<ClawChatStore, "claimMessageOnce">;
+
+function mintOutboundMessageId(account: ResolvedOpenclawClawlingAccount): string {
+  return `${account.userId}-msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function resolveChannelOutboundStore(): OutboundClaimStore | null {
+  try {
+    const runtime = getOpenclawClawlingRuntime();
+    const stateDir = runtime.state?.resolveStateDir?.();
+    return getClawChatStore({
+      ...(stateDir ? { dbPath: clawChatDbPathForStateDir(stateDir) } : {}),
+    });
+  } catch {
+    return null;
+  }
+}
+
+function claimChannelOutbound(params: {
+  account: ResolvedOpenclawClawlingAccount;
+  target: OutboundTarget;
+  messageId: string;
+  text: string;
+  raw: unknown;
+}): true | false | null {
+  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: ChannelOutboundAdapter = {
   deliveryMode: "direct",
   chunker: (text, limit) => chunkMarkdownText(text, limit),
@@ -206,18 +620,38 @@ export const openclawClawlingOutbound: ChannelOutboundAdapter = {
       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) ??
@@ -234,21 +668,40 @@ export const openclawClawlingOutbound: ChannelOutboundAdapter = {
       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/src/plugin-entry.test.ts

@@ -5,6 +5,7 @@ describe("openclaw-clawchat plugin entry", () => {
   it("registers the channel/tools and native activation command without bootstrap migration", () => {
     const mutateConfigFile = vi.fn();
     const api = {
+      registrationMode: "full",
       config: {},
       runtime: {
         config: {