@clawling/clawchat-plugin-openclaw 2026.9.26-3 → 2026.10.7-1

package/src/mention-autolink.ts

@@ -0,0 +1,200 @@
+/**
+ * Text "@name" → structured mention, applied to outbound group messages just
+ * before they are sent.
+ *
+ * A model naturally writes "@Anne please check" in a group reply. Sent as plain
+ * text, that wakes nobody: the mentioned agent's mention-only gate never opens
+ * and clients draw no highlight. This module recognises roster names after `@`
+ * and splits the text into text / mention fragments (protocol §7.1 / §10.2);
+ * the caller sends the fragments in `body.fragments` and the same mentions in
+ * `context.mentions`.
+ *
+ * Rules (shared with the reference ClawChat client so both sides agree):
+ *  - `@` opens a mention unless the character before it belongs to an email
+ *    local part (ASCII alnum, `.`, `_`, `%`, `+`, `-`), so an email address is not a
+ *    mention but "让@大Q看" (CJK glued to the `@`) is.
+ *  - Longest roster name wins; at equal length an exact-case match beats an
+ *    ASCII-case-folded one; a tie between two different users selects nobody.
+ *  - A name ending in an ASCII alnum must not be followed by one ("@Bean" does
+ *    not match inside "@Beanstalk"); CJK names need no right boundary.
+ *  - Self and the `all` sentinel are never produced from text: auto-waking a
+ *    whole room is an echo-storm starter and stays an explicit tool action.
+ *  - Anything not recognised stays plain text. This step must never block the
+ *    message itself.
+ *
+ * Pure functions plus a per-account roster-resolver registry (the runtime
+ * registers one that reads the cached group metadata).
+ */
+import type { Fragment, MentionFragment } from "./protocol-types.ts";
+
+/** The `@everyone` sentinel user id; never auto-linked from text. */
+export const MENTION_ALL_SENTINEL = "all";
+
+export interface MentionRosterMember {
+  userId: string;
+  /** Display name the model sees for this member. */
+  name: string;
+}
+
+const AT = 0x40;
+
+function isAsciiAlnum(c: number): boolean {
+  return (c >= 0x30 && c <= 0x39) || (c >= 0x41 && c <= 0x5a) || (c >= 0x61 && c <= 0x7a);
+}
+
+function isEmailLocal(c: number): boolean {
+  return isAsciiAlnum(c) || c === 0x2e || c === 0x5f || c === 0x25 || c === 0x2b || c === 0x2d;
+}
+
+function openBoundary(text: string, at: number): boolean {
+  if (at === 0) return true;
+  return !isEmailLocal(text.charCodeAt(at - 1));
+}
+
+function lowerAscii(c: number): number {
+  return c >= 0x41 && c <= 0x5a ? c + 0x20 : c;
+}
+
+function matches(text: string, start: number, name: string, fold: boolean): boolean {
+  const end = start + name.length;
+  if (end > text.length) return false;
+  for (let k = 0; k < name.length; k += 1) {
+    let a = text.charCodeAt(start + k);
+    let b = name.charCodeAt(k);
+    if (fold) {
+      a = lowerAscii(a);
+      b = lowerAscii(b);
+    }
+    if (a !== b) return false;
+  }
+  if (end === text.length) return true;
+  return !(isAsciiAlnum(name.charCodeAt(name.length - 1)) && isAsciiAlnum(text.charCodeAt(end)));
+}
+
+function matchAt(text: string, start: number, targets: MentionRosterMember[]): MentionRosterMember | null {
+  let best: MentionRosterMember | null = null;
+  let bestExact = false;
+  let ambiguous = false;
+  for (const t of targets) {
+    const exact = matches(text, start, t.name, false);
+    const hit = exact || matches(text, start, t.name, true);
+    if (!hit) continue;
+    if (
+      !best ||
+      t.name.length > best.name.length ||
+      (t.name.length === best.name.length && exact && !bestExact)
+    ) {
+      best = t;
+      bestExact = exact;
+      ambiguous = false;
+    } else if (t.name.length === best.name.length && exact === bestExact && t.userId !== best.userId) {
+      ambiguous = true;
+    }
+  }
+  return ambiguous ? null : best;
+}
+
+function targetsOf(roster: MentionRosterMember[], ownUserId: string): MentionRosterMember[] {
+  const out: MentionRosterMember[] = [];
+  for (const m of roster) {
+    const name = typeof m.name === "string" ? m.name.trim() : "";
+    const userId = typeof m.userId === "string" ? m.userId.trim() : "";
+    if (!name || !userId) continue;
+    if (userId === ownUserId) continue;
+    if (userId === MENTION_ALL_SENTINEL) continue;
+    out.push({ userId, name });
+  }
+  return out;
+}
+
+/** Whether `text` has an `@` worth fetching the group roster for. */
+export function hasMentionCandidate(text: string): boolean {
+  for (let i = 0; i < text.length - 1; i += 1) {
+    if (text.charCodeAt(i) === AT && openBoundary(text, i)) return true;
+  }
+  return false;
+}
+
+/**
+ * Split `text` into text / mention fragments using `roster`. The `@` is
+ * consumed by the mention fragment (`display` is the bare name; clients
+ * render `@display`). With no hit the result is a single text fragment
+ * (or `[]` for empty text).
+ */
+export function autolinkMentions(
+  text: string,
+  roster: MentionRosterMember[],
+  options: { ownUserId: string },
+): Fragment[] {
+  if (!text) return [];
+  const targets = targetsOf(roster, options.ownUserId);
+  if (targets.length === 0) return [{ kind: "text", text }];
+  const out: Fragment[] = [];
+  let cursor = 0;
+  let i = 0;
+  while (i < text.length) {
+    if (text.charCodeAt(i) !== AT || !openBoundary(text, i)) {
+      i += 1;
+      continue;
+    }
+    const hit = matchAt(text, i + 1, targets);
+    if (!hit) {
+      i += 1;
+      continue;
+    }
+    if (i > cursor) out.push({ kind: "text", text: text.slice(cursor, i) });
+    out.push({ kind: "mention", user_id: hit.userId, display: hit.name });
+    i += 1 + hit.name.length;
+    cursor = i;
+  }
+  if (cursor < text.length) out.push({ kind: "text", text: text.slice(cursor) });
+  return out;
+}
+
+/** The `context.mentions` half: mention fragments de-duplicated by user id. */
+export function mentionsIn(fragments: Fragment[]): MentionFragment[] {
+  const seen = new Set<string>();
+  const out: MentionFragment[] = [];
+  for (const f of fragments) {
+    if (f.kind !== "mention") continue;
+    const id = typeof f.user_id === "string" ? f.user_id : "";
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    out.push({ kind: "mention", user_id: id, ...(f.display ? { display: f.display } : {}) });
+  }
+  return out;
+}
+
+export type MentionRosterResolver = (groupId: string) => Promise<MentionRosterMember[]>;
+
+const rosterResolvers = new Map<string, MentionRosterResolver>();
+
+/** Register the roster source for one account; returns an unregister function. */
+export function registerMentionRosterResolver(
+  accountId: string,
+  resolver: MentionRosterResolver,
+): () => void {
+  rosterResolvers.set(accountId, resolver);
+  return () => {
+    if (rosterResolvers.get(accountId) === resolver) rosterResolvers.delete(accountId);
+  };
+}
+
+/** Best-effort roster lookup: any failure or missing resolver yields `[]`. */
+export async function resolveMentionRoster(
+  accountId: string,
+  groupId: string,
+): Promise<MentionRosterMember[]> {
+  const resolver = rosterResolvers.get(accountId);
+  if (!resolver) return [];
+  try {
+    const roster = await resolver(groupId);
+    return Array.isArray(roster) ? roster : [];
+  } catch {
+    return [];
+  }
+}
+
+export function clearMentionRosterResolversForTest(): void {
+  rosterResolvers.clear();
+}

package/src/no-reply.ts

@@ -9,11 +9,12 @@
  * tolerated for free and must not be written into the pattern itself.
  *
  * RULE B — bare runtime silence markers (`NO_REPLY` / `[SILENT]` / `SILENT` /
- * `NO REPLY`), matched as a WHOLE STRING ONLY. OpenClaw itself has no such
- * convention; these are carried because other agent runtimes define them, so a
- * model may fall back to one instead of the `clawchat:` form. They are ordinary
- * English words — substring-matching them would swallow prose such as "there is
- * no reply from the server".
+ * `NO REPLY` / `HEARTBEAT_OK`), matched as a WHOLE STRING ONLY. These are
+ * carried because agent runtimes define them, so a model may fall back to one
+ * instead of the `clawchat:` form; `HEARTBEAT_OK` is the OpenClaw host's
+ * heartbeat acknowledgement, which some host versions let through as a reply.
+ * They are ordinary words — substring-matching them would swallow prose such as
+ * "there is no reply from the server".
  *
  * This module MUST stay a literal mirror of the Hermes plugin's equivalent
  * module. When one side changes, change the other in the same breath.
@@ -38,7 +39,7 @@ const DECORATION_CLOSE = "[/>\\]}`*_~]*";
 
 const STRIP_RE = new RegExp(DECORATION_OPEN + CORE + DECORATION_CLOSE, "gi");
 
-const HOST_MARKERS = new Set(["[SILENT]", "SILENT", "NO_REPLY", "NO REPLY"]);
+const HOST_MARKERS = new Set(["[SILENT]", "SILENT", "NO_REPLY", "NO REPLY", "HEARTBEAT_OK"]);
 const HOST_MARKER_MAX_LEN = 64;
 
 // General_Category=Punctuation, matching the host's `unicodedata.category()`

package/src/outbound.ts

@@ -21,6 +21,13 @@ import {
   uploadOutboundMedia,
   type ClawlingMediaFragment,
 } from "./media-runtime.ts";
+import {
+  autolinkMentions,
+  hasMentionCandidate,
+  mentionsIn,
+  resolveMentionRoster,
+  type MentionRosterMember,
+} from "./mention-autolink.ts";
 import { isClawChatNoopResponseText } from "./profile-prompt.ts";
 import { stripNoReplyTokens } from "./no-reply.ts";
 import {
@@ -64,9 +71,29 @@ export interface SendParams {
   mediaFragments?: ClawlingMediaFragment[];
   mentions?: MentionFragment[];
   messageId?: string;
+  /**
+   * Protocol §7.5 `payload.message_mode`. `"thinking"` marks process output
+   * (tool progress, runtime notices, reasoning) that agents skip as input and
+   * clients may fold; everything else is `"normal"` (the default).
+   */
+  messageMode?: OutboundMessageMode;
+  /**
+   * Group roster for text "@name" autolinking. When omitted, a group send
+   * whose text contains a candidate `@` looks the roster up via the
+   * per-account resolver the runtime registers (`mention-autolink.ts`).
+   */
+  mentionRoster?: MentionRosterMember[];
+  /**
+   * This send is the final of a reply stream and reuses its message_id. It
+   * goes out as `message.reply` (protocol §8.4 finalize-reply pattern) even
+   * when it quotes nothing; the reply context is unchanged.
+   */
+  finalizesStream?: boolean;
   log?: LogSink;
 }
 
+export type OutboundMessageMode = "normal" | "thinking";
+
 export interface SendResult {
   messageId: string;
   acceptedAt: number;
@@ -591,8 +618,31 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
     return null;
   }
 
-  const mentions = params.mentions ?? [];
-  const textFragments = text ? textToFragments(text) : [];
+  const messageMode: OutboundMessageMode = params.messageMode ?? "normal";
+  let mentions = params.mentions ?? [];
+  let textFragments = text ? textToFragments(text) : [];
+  // Text "@name" → structured mention (group, normal messages only). Process
+  // (thinking) output must not wake anyone. Best-effort: an unavailable roster
+  // leaves the text plain and never blocks the send.
+  if (
+    textFragments.length > 0
+    && params.to.chatType === "group"
+    && messageMode === "normal"
+    && hasMentionCandidate(text)
+  ) {
+    const roster = params.mentionRoster
+      ?? await resolveMentionRoster(params.account.accountId, params.to.chatId);
+    const linked = autolinkMentions(text, roster, { ownUserId: params.account.userId ?? "" });
+    const linkedMentions = mentionsIn(linked);
+    if (linkedMentions.length > 0) {
+      textFragments = linked;
+      const seen = new Set(mentions.map((m) => m.user_id).filter(Boolean));
+      mentions = [...mentions, ...linkedMentions.filter((m) => !seen.has(m.user_id))];
+      params.log?.info?.(
+        `[${params.account.accountId}] clawchat-plugin-openclaw outbound text mentions linked count=${linkedMentions.length} to=${params.to.chatId}`,
+      );
+    }
+  }
   // 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
@@ -617,7 +667,7 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
     mode = "reply";
     const payload = {
       message_id: messageId,
-      message_mode: "normal",
+      message_mode: messageMode,
       message: {
         body: { fragments },
         context: {
@@ -642,7 +692,8 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
       ...(params.log ? { log: params.log } : {}),
     });
   } else {
-    mode = "send";
+    // A stream's final is a message.reply (§8.4) whether or not it quotes.
+    mode = params.finalizesStream ? "reply" : "send";
     const reply = params.replyCtx
       ? {
           reply_to_msg_id: params.replyCtx.replyToMessageId,
@@ -651,7 +702,7 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
       : null;
     const payload = {
       message_id: messageId,
-      message_mode: "normal",
+      message_mode: messageMode,
       message: {
         body: { fragments },
         context: { mentions, reply },
@@ -660,7 +711,7 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
     ack = await sendAlignedAckableEnvelope({
       client: params.client,
       account: params.account,
-      eventName: "message.send",
+      eventName: mode === "reply" ? "message.reply" : "message.send",
       chatId: params.to.chatId,
       payload,
       ...(params.log ? { log: params.log } : {}),
@@ -672,7 +723,7 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
     );
   }
   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}`,
+    `[${params.account.accountId}] clawchat-plugin-openclaw outbound mode=${mode} message_mode=${messageMode} msg=${ack.payload.message_id} text_len=${text.length} media=${mediaFragments.length} trace=${ack.trace_id}`,
   );
   return {
     messageId: ack.payload.message_id,