@clawling/clawchat-plugin-openclaw 2026.10.9-3 → 2026.10.9-4

package/src/tools.ts

@@ -22,8 +22,10 @@ import {
   getClawChatStore,
   makeOwnerProfilePersister,
   type ClawChatStore,
+  type SeenMessage,
 } from "./storage.ts";
-import { sendOpenclawClawlingMentionMessage, sendOpenclawClawlingReaction } from "./outbound.ts";
+import { isPlausibleMessageId, sendOpenclawClawlingMentionMessage, sendOpenclawClawlingReaction } from "./outbound.ts";
+import { isValidChatId } from "./ws-client.ts";
 import {
   getOpenclawClawlingClient,
 } from "./runtime.ts";
@@ -43,7 +45,7 @@ import {
   resolveMemoryScope,
   type MemoryScope,
 } from "./memory-scope.ts";
-import { clawChatSessionAccountId, NON_OWNER_TOOL_ALLOWLIST } from "./turn-boundary.ts";
+import { clawChatSessionAccountId, NON_OWNER_TOOL_ALLOWLIST, normalizeToolChatId } from "./turn-boundary.ts";
 import {
   pullGroupMetadata,
   pullOwnerMetadata,
@@ -223,6 +225,16 @@ function validationError(message: string) {
   return jsonResponse({ error: "validation", message });
 }
 
+function reactionBlockedError(chatId: string, reason: "invalid_chat_id" | "chat_rejected_by_server") {
+  return jsonResponse({
+    error: "send_blocked",
+    reason,
+    message: reason === "invalid_chat_id"
+      ? `clawchat-plugin-openclaw: "${chatId}" is not a ClawChat chat id (expected cnv_…); the reaction was not sent`
+      : "clawchat-plugin-openclaw: this chat was rejected by the server; the reaction was not sent",
+  });
+}
+
 function genericError(err: unknown) {
   return jsonResponse({
     error: "unknown",
@@ -263,7 +275,15 @@ type ToolStore = Pick<
   ClawChatStore,
   "recordToolCall"
 > &
-  Partial<Pick<ClawChatStore, "lookupActivationIdentity" | "listRecentGroupMessages">>;
+  Partial<Pick<
+    ClawChatStore,
+    | "lookupActivationIdentity"
+    | "listRecentGroupMessages"
+    | "findSeenMessageInChat"
+    | "findStoredChatId"
+    | "claimMessageOnce"
+    | "markMessageAcknowledged"
+  >>;
 
 function toolDescription(...parts: string[]): string {
   return `${parts.join("")} ${DIRECT_TOOL_GUARD}`;
@@ -325,6 +345,13 @@ function planMomentImages(
   return { ok: true, entries };
 }
 
+const MESSAGE_ID_ECHO_LIMIT = 64;
+
+function notAMessageIdMessage(field: string, value: string): string {
+  const shown = value.length > MESSAGE_ID_ECHO_LIMIT ? `${value.slice(0, MESSAGE_ID_ECHO_LIMIT)}…` : value;
+  return `clawchat-plugin-openclaw: ${field} "${shown}" is not a message in this chat; use the real message id from this chat's message metadata (e.g. msg-…), or omit it`;
+}
+
 function validateMentionMessageParams(params: unknown):
   | { ok: true; params: ClawchatMentionMessageParams }
   | { ok: false; message: string } {
@@ -332,7 +359,8 @@ function validateMentionMessageParams(params: unknown):
     return { ok: false, message: "clawchat-plugin-openclaw: params are required" };
   }
   const p = params as Partial<ClawchatMentionMessageParams>;
-  if (typeof p.chatId !== "string" || !p.chatId.trim()) {
+  const chatId = normalizeToolChatId(p.chatId);
+  if (!chatId) {
     return { ok: false, message: "clawchat-plugin-openclaw: chatId is required" };
   }
   if (p.chatType !== undefined && p.chatType !== "group" && p.chatType !== "direct") {
@@ -368,11 +396,12 @@ function validateMentionMessageParams(params: unknown):
       ok: true,
       params: {
         ...p,
+        chatId,
         replyToMessageId,
       } as ClawchatMentionMessageParams,
     };
   }
-  return { ok: true, params: p as ClawchatMentionMessageParams };
+  return { ok: true, params: { ...p, chatId } as ClawchatMentionMessageParams };
 }
 
 /**
@@ -404,6 +433,18 @@ export function resolveOpenclawClawlingToolAccountId(ctx: OpenClawPluginToolCont
   return null;
 }
 
+/**
+ * True when the host says this tool call's run is a ClawChat run: every
+ * channel the trusted ctx names (`deliveryContext.channel`, `messageChannel`)
+ * is this channel, and at least one is present. Missing or foreign → false.
+ */
+export function isClawChatToolRun(ctx: OpenClawPluginToolContext): boolean {
+  const channels = [ctx.deliveryContext?.channel, ctx.messageChannel]
+    .map((channel) => (typeof channel === "string" ? channel.trim().toLowerCase() : ""))
+    .filter(Boolean);
+  return channels.length > 0 && channels.every((channel) => channel === CHANNEL_ID);
+}
+
 // Names this plugin registered through its wrapper below. The host-tool guard
 // lets an allowlisted `clawchat_*` name through only when it is in this set,
 // so another plugin's tool under a lookalike name is not trusted by prefix.
@@ -476,6 +517,94 @@ export function registerOpenclawClawlingTools(
     }
   }
 
+  let warnedMessageIdStore = false;
+  /**
+   * An explicit message id (react target, mention reply) must be one the
+   * plugin has stored for this chat; the stored chat id and message id (their
+   * real case) are what gets sent. When the store cannot answer, fall back to
+   * the message-id shape check rather than block every call, keep the ids as
+   * given, and warn once without ids or arguments.
+   */
+  function resolveExplicitMessageId(input: {
+    field: "targetMessageId" | "replyToMessageId";
+    value: string;
+    accountId: string;
+    chatId: string;
+  }): { ok: true; chatId: string; messageId: string } | { ok: false; error: ReturnType<typeof validationError> } {
+    let seen: SeenMessage | false | null = null;
+    try {
+      const store = resolveStore();
+      seen = store?.findSeenMessageInChat
+        ? store.findSeenMessageInChat({
+            platform: "openclaw",
+            accountId: input.accountId,
+            chatId: input.chatId,
+            messageId: input.value,
+          })
+        : null;
+    } catch {
+      seen = null;
+    }
+    if (seen) return { ok: true, chatId: seen.chatId, messageId: seen.messageId };
+    if (seen === null) {
+      if (!warnedMessageIdStore) {
+        warnedMessageIdStore = true;
+        api.logger.warn(
+          "clawchat-plugin-openclaw: message-id store check unavailable; falling back to the message-id shape check",
+        );
+      }
+      if (isPlausibleMessageId(input.value)) return { ok: true, chatId: input.chatId, messageId: input.value };
+    }
+    return { ok: false, error: validationError(notAMessageIdMessage(input.field, input.value)) };
+  }
+
+  /**
+   * The chat id in the case the ledger already stores for it, so a send, its
+   * terminal marker and its ledger row all name the chat as the inbound path
+   * does (a second case splits the chat for memory scope). The id as given
+   * when the ledger has no row for the chat or cannot answer.
+   */
+  function storedChatIdCase(accountId: string, chatId: string): string {
+    try {
+      const stored = resolveStore()?.findStoredChatId?.({ platform: "openclaw", accountId, chatId });
+      return typeof stored === "string" && stored ? stored : chatId;
+    } catch {
+      return chatId;
+    }
+  }
+
+  /**
+   * Best-effort ledger row for a sent mention, so its id can be reacted to or
+   * quoted later. Written after the ack; a store failure never affects the send.
+   */
+  function recordMentionSent(input: { accountId: string; chatId: string; messageId: string; text: string; acceptedAt?: number }): void {
+    try {
+      const store = resolveStore();
+      const claimed = store?.claimMessageOnce?.({
+        platform: "openclaw",
+        accountId: input.accountId,
+        kind: "message",
+        direction: "outbound",
+        eventType: "message.send",
+        chatId: input.chatId,
+        messageId: input.messageId,
+        text: input.text,
+        raw: { mode: "tool-mention" },
+      });
+      if (claimed !== true) return;
+      store?.markMessageAcknowledged?.({
+        accountId: input.accountId,
+        kind: "message",
+        direction: "outbound",
+        messageId: input.messageId,
+        protocolMessageId: input.messageId,
+        ackedAt: input.acceptedAt ?? Date.now(),
+      });
+    } catch {
+      // Diagnostics only; the mention has already been sent.
+    }
+  }
+
   function detailsError(details: unknown): string | null {
     if (!details || typeof details !== "object") return null;
     const raw = details as { error?: unknown; message?: unknown };
@@ -1288,7 +1417,7 @@ export function registerOpenclawClawlingTools(
             const built = buildClient(accountId);
             if (!built.ok) return built.error;
             try {
-              const data = await built.client.getConversation(p.conversationId);
+              const data = await built.client.getConversation(normalizeToolChatId(p.conversationId));
               return jsonResponse(data);
             } catch (err) {
               if (err instanceof ClawlingApiError) {
@@ -1358,7 +1487,7 @@ export function registerOpenclawClawlingTools(
             const built = buildClient(accountId);
             if (!built.ok) return built.error;
             try {
-              const data = await built.client.leaveConversation(p.conversationId);
+              const data = await built.client.leaveConversation(normalizeToolChatId(p.conversationId));
               return jsonResponse(data);
             } catch (err) {
               if (err instanceof ClawlingApiError) {
@@ -1393,7 +1522,7 @@ export function registerOpenclawClawlingTools(
             const built = buildClient(accountId);
             if (!built.ok) return built.error;
             try {
-              const data = await built.client.addConversationMember(p.conversationId, p.userId);
+              const data = await built.client.addConversationMember(normalizeToolChatId(p.conversationId), p.userId);
               return jsonResponse(data);
             } catch (err) {
               if (err instanceof ClawlingApiError) {
@@ -1434,6 +1563,19 @@ export function registerOpenclawClawlingTools(
             }
             try {
               const p = validated.params;
+              let chatId = isValidChatId(p.chatId) ? storedChatIdCase(account.accountId, p.chatId) : p.chatId;
+              let replyToMessageId = p.replyToMessageId;
+              if (replyToMessageId) {
+                const resolved = resolveExplicitMessageId({
+                  field: "replyToMessageId",
+                  value: replyToMessageId,
+                  accountId: account.accountId,
+                  chatId,
+                });
+                if (!resolved.ok) return resolved.error;
+                chatId = resolved.chatId;
+                replyToMessageId = resolved.messageId;
+              }
               const client = getOpenclawClawlingClient(account.accountId);
               if (!client) {
                 return configError("ClawChat websocket client is not ready");
@@ -1442,26 +1584,38 @@ export function registerOpenclawClawlingTools(
                 client,
                 account,
                 to: {
-                  chatId: p.chatId.trim(),
+                  chatId,
                   chatType: p.chatType ?? "group",
                 },
                 ...(p.text !== undefined ? { text: p.text } : {}),
                 mentions: p.mentions,
-                ...(p.replyToMessageId
+                ...(replyToMessageId
                   ? {
                       replyCtx: {
-                        replyToMessageId: p.replyToMessageId,
+                        replyToMessageId,
                       },
                     }
                   : {}),
                 log: api.logger,
               });
               if (!result) return jsonResponse(result);
-              markTerminalClawChatSend({
+              recordMentionSent({
                 accountId: account.accountId,
-                chatId: p.chatId.trim(),
+                chatId,
                 messageId: result.messageId,
+                text: p.text ?? "",
+                ...(result.acceptedAt !== undefined ? { acceptedAt: result.acceptedAt } : {}),
               });
+              // Same trust rule as the react defaults: only a ClawChat run's
+              // turn may have its follow-up reply suppressed.
+              if (isClawChatToolRun(ctx)) {
+                markTerminalClawChatSend({
+                  accountId: account.accountId,
+                  chatId,
+                  messageId: result.messageId,
+                  sessionKey: ctx.sessionKey,
+                });
+              }
               return jsonResponse({
                 sent: true,
                 terminal: true,
@@ -1505,9 +1659,31 @@ export function registerOpenclawClawlingTools(
             if (!account.configured) {
               return configError("clawchat-plugin-openclaw: account is not configured");
             }
-            const scope = getCurrentTerminalSendScope();
-            const chatId = p.chatId?.trim() || scope?.chatId;
-            const targetMessageId = p.targetMessageId?.trim() || scope?.messageId;
+            // Defaults come only from this call's own turn: the open turn in
+            // its async context registered for the same session key as the
+            // trusted tool ctx (see terminal-send.ts). Anything else fails as
+            // a validation error asking for explicit ids.
+            // The run must also be a ClawChat run: under a session key shared
+            // with another channel, that channel's turns never register or
+            // supersede a ClawChat turn, so its calls get no defaults.
+            const scope = isClawChatToolRun(ctx)
+              ? getCurrentTerminalSendScope({ sessionKey: ctx.sessionKey })
+              : null;
+            // Only a missing or blank chatId defaults. A given one that strips
+            // to nothing (`clawchat-plugin-openclaw:`, `group:`) stays as given
+            // so outbound refuses it as invalid_chat_id instead of it silently
+            // reaching the current turn's chat.
+            const rawChatId = typeof p.chatId === "string" ? p.chatId.trim() : "";
+            let chatId = rawChatId ? normalizeToolChatId(rawChatId) || rawChatId : scope?.chatId;
+            const explicitTargetMessageId = typeof p.targetMessageId === "string" ? p.targetMessageId.trim() : "";
+            // The default target is the current turn's message, so it applies
+            // only to that turn's chat: chatId omitted, or naming the scope's
+            // chat (any case, host target form). The send then goes to the
+            // scope's chat id. In any other chat that id names no message.
+            const defaultsToScopeChat = Boolean(scope)
+              && (!rawChatId || (chatId ?? "").toLowerCase() === scope!.chatId.toLowerCase());
+            let targetMessageId = explicitTargetMessageId || (defaultsToScopeChat ? scope!.messageId : undefined);
+            if (!explicitTargetMessageId && defaultsToScopeChat) chatId = scope!.chatId;
             if (!chatId) {
               return validationError(
                 "clawchat-plugin-openclaw: chatId is required (no current-turn chat to default from)",
@@ -1518,6 +1694,21 @@ export function registerOpenclawClawlingTools(
                 "clawchat-plugin-openclaw: targetMessageId is required (no current-turn message to default from)",
               );
             }
+            // Only an explicit id is checked; the current-turn default is the
+            // triggering message's own id. A chat id outbound would refuse is
+            // reported as that refusal first.
+            if (explicitTargetMessageId) {
+              if (!isValidChatId(chatId)) return reactionBlockedError(chatId, "invalid_chat_id");
+              const resolved = resolveExplicitMessageId({
+                field: "targetMessageId",
+                value: explicitTargetMessageId,
+                accountId: account.accountId,
+                chatId,
+              });
+              if (!resolved.ok) return resolved.error;
+              chatId = resolved.chatId;
+              targetMessageId = resolved.messageId;
+            }
             const client = getOpenclawClawlingClient(account.accountId);
             if (!client) {
               return configError("ClawChat websocket client is not ready");
@@ -1525,7 +1716,10 @@ export function registerOpenclawClawlingTools(
             const emoji = p.emoji.trim();
             const removed = p.remove === true;
             try {
-              sendOpenclawClawlingReaction({ client, chatId, targetMessageId, emoji, removed, log: api.logger });
+              const sent = sendOpenclawClawlingReaction({ client, chatId, targetMessageId, emoji, removed, log: api.logger });
+              // A locally refused reaction never left the plugin: report the
+              // refusal so the model does not tell the user it reacted.
+              if (!sent.sent) return reactionBlockedError(chatId, sent.reason);
               return jsonResponse({ reacted: true, targetMessageId, emoji, removed });
             } catch (err) {
               return genericError(err);
@@ -2136,7 +2330,7 @@ export function registerOpenclawClawlingTools(
         async execute(_callId, params) {
           return await recordClawchatToolCall(accountId, "clawchat_orchestrate_get_group", params, async () => {
             const p = params as ClawchatOrchGetGroupParams;
-            return await withClient(accountId, (c) => c.orchGetGroup(p.conversationId));
+            return await withClient(accountId, (c) => c.orchGetGroup(normalizeToolChatId(p.conversationId)));
           });
         },
       };
@@ -2169,7 +2363,7 @@ export function registerOpenclawClawlingTools(
             params,
             async () => {
               const p = params as ClawchatOrchSetGroupPromptParams;
-              return await withClient(accountId, (c) => c.orchSetGroupPrompt(p.conversationId, p.description));
+              return await withClient(accountId, (c) => c.orchSetGroupPrompt(normalizeToolChatId(p.conversationId), p.description));
             },
           );
         },
@@ -2219,7 +2413,7 @@ export function registerOpenclawClawlingTools(
             params,
             async () => {
               const p = params as ClawchatOrchGroupMemberParams;
-              return await withClient(accountId, (c) => c.orchAddGroupMember(p.conversationId, p.agentId));
+              return await withClient(accountId, (c) => c.orchAddGroupMember(normalizeToolChatId(p.conversationId), p.agentId));
             },
           );
         },
@@ -2246,7 +2440,7 @@ export function registerOpenclawClawlingTools(
             params,
             async () => {
               const p = params as ClawchatOrchGroupMemberParams;
-              return await withClient(accountId, (c) => c.orchRemoveGroupMember(p.conversationId, p.agentId));
+              return await withClient(accountId, (c) => c.orchRemoveGroupMember(normalizeToolChatId(p.conversationId), p.agentId));
             },
           );
         },
@@ -2276,7 +2470,7 @@ export function registerOpenclawClawlingTools(
             async () => {
               const p = params as ClawchatOrchSetGroupAgentSettingsParams;
               return await withClient(accountId, (c) =>
-                c.orchSetGroupAgentSettings(p.conversationId, p.agentId, {
+                c.orchSetGroupAgentSettings(normalizeToolChatId(p.conversationId), p.agentId, {
                   muted: p.muted,
                   replyMode: p.replyMode,
                   batchDelaySeconds: p.batchDelaySeconds,

package/src/turn-boundary.ts

@@ -16,6 +16,24 @@ export const NON_OWNER_TOOL_ALLOWLIST: readonly string[] = Object.freeze([
 
 const norm = (v: string | undefined | null) => (typeof v === "string" ? v.trim().toLowerCase() : "");
 
+// `<channel>:` then `direct:`/`group:`, each optional and stripped at most once.
+const TOOL_CHAT_ID_TARGET_PREFIX = new RegExp(`^(?:${CHANNEL_ID}:)?(?:(?:direct|group):)?`, "i");
+
+/**
+ * The bare ClawChat chat id a tool argument names. The host shows the model
+ * this chat's `chat_id` as the channel-prefixed origin target
+ * (`clawchat-plugin-openclaw:cnv_…` / `clawchat-plugin-openclaw:group:cnv_…`)
+ * and a group's label as `group:cnv_…`; models copy either form into tool
+ * arguments. Only that form is stripped; case is kept, and whatever remains is
+ * still validated by the send path (`isValidChatId`) or the server. Every tool
+ * that takes a ClawChat chat id, and the non-owner current-chat check, use
+ * this one helper so they agree on which chat an argument names.
+ */
+export function normalizeToolChatId(value: unknown): string {
+  if (typeof value !== "string") return "";
+  return value.trim().replace(TOOL_CHAT_ID_TARGET_PREFIX, "").trim();
+}
+
 /**
  * Host session keys (dmScope per-account-channel-peer):
  *   agent:<agent>:<channel>:<account>:direct:<chat>