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

package/src/reply-dispatcher.ts

@@ -25,12 +25,14 @@ import {
 import {
   mintMessageId,
   sendOpenclawClawlingText,
+  type OutboundMessageMode,
   type OutboundReplyCtx,
   type SendResult,
 } from "./outbound.ts";
 import { isClawChatNoopResponseText } from "./profile-prompt.ts";
 import type { ClawChatStore } from "./storage.ts";
 import { consumeTerminalClawChatSend } from "./terminal-send.ts";
+import { createReplyStream, type ReplyStream } from "./reply-stream.ts";
 import { openclawLlmContextDebug } from "./llm-context-debug.ts";
 
 export interface ReplyDispatcherOptions {
@@ -85,8 +87,11 @@ type TypedReplyDispatcherResult = ReturnType<
 type ClawChatReplyOptions = TypedReplyDispatcherResult["replyOptions"] &
   {
     sourceReplyDeliveryMode: "automatic";
+    /** Newer hosts: disable the host typing keepalive; the plugin runs its own. */
+    typingKeepalive?: boolean;
     disableBlockStreaming: boolean;
     suppressDefaultToolProgressMessages: boolean;
+    onPartialReply?: (payload: { text?: string }) => void | Promise<void>;
     allowProgressCallbacksWhenSourceDeliverySuppressed?: boolean;
     onReasoningStream?: (payload: ReplyPayload) => void | Promise<void>;
     onToolStart?: (payload: {
@@ -120,6 +125,15 @@ type RichInteractionFragment = {
   actions: RichAction[];
 };
 
+/**
+ * Re-send cadence for `typing.update {is_typing:true}` while a reply is in
+ * flight: at most half of the client's typing display window (6 s), so a single
+ * lost frame never lets the indicator lapse.
+ */
+export const TYPING_KEEPALIVE_MS = 3_000;
+/** Safety cap for one reply's typing keepalive (15 min). */
+export const TYPING_KEEPALIVE_MAX_MS = 15 * 60_000;
+
 const GROUP_OWNER_ATTENTION_TITLE = "requires owner attention";
 const APPROVAL_FALLBACK_COMMAND_RE = /(?:^|\s)\/(?:approve|deny)\b/i;
 
@@ -479,6 +493,39 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
   const outboundEventType = () => (replyCtx ? "message.reply" : "message.send");
   const outboundRaw = () => ({ target, replyCtx: replyCtx ?? null });
   const terminalSendScopeId = options.terminalSendScopeId ?? null;
+  // ----- Reply streaming (experimental, `streamReplies`) -----------------
+  //
+  // One open stream previews the assistant text being generated. The next
+  // normal materialized send claims it (`message.done` with the final text,
+  // then the final as `message.reply` reusing the stream's message_id, §8.4);
+  // a final that does not extend the preview, a no-reply, a terminal tool
+  // send, or an idle run with nothing delivered fails it. Host partials are snapshots of
+  // the current assistant message that may be rewritten, so a snapshot that no
+  // longer extends the preview fails the old stream and starts a new one.
+  const streamEnabled = account.streamReplies === true;
+  let replyStream: ReplyStream | null = null;
+  const failStream = (reason: string) => {
+    replyStream?.fail(reason);
+    replyStream = null;
+  };
+  const claimStreamMessageId = (finalText: string): string | null => {
+    const id = replyStream?.finish(finalText) ?? null;
+    replyStream = null;
+    return id;
+  };
+  const onStreamPartial = (text: string) => {
+    if (runDone || terminalReplySuppressed) return;
+    if (replyStream?.diverges(text)) failStream("superseded");
+    replyStream ??= createReplyStream({
+      client,
+      chatId: target.chatId,
+      mintMessageId,
+      log,
+      logPrefix: `[${account.accountId}] clawchat-plugin-openclaw`,
+    });
+    replyStream.update(text);
+  };
+
   const consumeTerminalSend = (reason: string): boolean => {
     if (terminalReplySuppressed) return true;
     if (!terminalSendScopeId) return false;
@@ -489,6 +536,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     });
     if (!terminal) return false;
     terminalReplySuppressed = true;
+    failStream("terminal-send");
     log?.info?.(
       `[${account.accountId}] clawchat-plugin-openclaw suppressing ${reason} reply after terminal tool send msg=${terminal.messageId} to=${target.chatId}`,
     );
@@ -571,8 +619,9 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
       if (url && !bufferedOutputUrls.includes(url)) bufferedOutputUrls.push(url);
     }
   };
-  const fullSegmentKey = (text: string, urls: string[]): string =>
+  const fullSegmentKey = (text: string, urls: string[], mode: OutboundMessageMode): string =>
     JSON.stringify({
+      mode,
       text: text.replace(/\s+/g, " ").trim(),
       urls: urls.filter(Boolean),
     });
@@ -606,6 +655,39 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     }
   };
 
+  // Plugin-owned typing keepalive. The client lights "typing" for a fixed
+  // window per `is_typing:true` frame, so the sender must re-send at no more
+  // than half that window (TYPING_KEEPALIVE_MS) for as long as the reply is in
+  // flight, and send `false` exactly once at the end. The host's own keepalive
+  // (default 6 s, global config only) equals the client window, so one lost or
+  // late frame makes the indicator flash; we ask the host to turn it off
+  // (`typingKeepalive: false`, honoured by newer hosts) and ignore its repeated
+  // `onReplyStart` ticks on older hosts.
+  let typingTimer: ReturnType<typeof setInterval> | null = null;
+  let typingCapTimer: ReturnType<typeof setTimeout> | null = null;
+  let typingFinished = false;
+  const stopTyping = () => {
+    if (typingTimer) clearInterval(typingTimer);
+    if (typingCapTimer) clearTimeout(typingCapTimer);
+    typingTimer = null;
+    typingCapTimer = null;
+    typingFinished = true;
+    emitTyping(false);
+  };
+  const startTyping = () => {
+    if (typingFinished || typingTimer) return;
+    emitTyping(true);
+    typingTimer = setInterval(() => emitTyping(true), TYPING_KEEPALIVE_MS);
+    typingTimer.unref?.();
+    typingCapTimer = setTimeout(() => {
+      log?.info?.(
+        `[${account.accountId}] clawchat-plugin-openclaw typing keepalive cap reached; stopping to=${target.chatId}`,
+      );
+      stopTyping();
+    }, TYPING_KEEPALIVE_MAX_MS);
+    typingCapTimer.unref?.();
+  };
+
   const sendOwnerAttention = async (
     fallbackText: string,
     richFragment: Fragment | null = null,
@@ -637,14 +719,16 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     text: string,
     mediaFragments: ClawlingMediaFragment[] = [],
     richFragments: Fragment[] = [],
-    options: { recordMessage?: boolean } = {},
+    options: { recordMessage?: boolean; messageMode?: OutboundMessageMode } = {},
   ): Promise<SendResult | null> => {
+    const messageMode = options.messageMode ?? "normal";
     if (
       isClawChatNoopResponseText(text) &&
       mediaFragments.length === 0 &&
       richFragments.length === 0
     ) {
       log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw outbound suppressed: no-reply token`);
+      if (messageMode === "normal") failStream("no-reply");
       openclawLlmContextDebug.writeSnapshot({
         visibility: "host_event",
         trace: {
@@ -667,12 +751,13 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     if (!text.trim() && mediaFragments.length === 0 && richFragments.length === 0) return null;
     if (consumeTerminalSend("static")) return null;
     log?.info?.(
-      `[${account.accountId}] clawchat-plugin-openclaw sending static text_len=${text.length} media=${mediaFragments.length} rich=${richFragments.length} to=${target.chatId}`,
+      `[${account.accountId}] clawchat-plugin-openclaw sending static mode=${messageMode} text_len=${text.length} media=${mediaFragments.length} rich=${richFragments.length} to=${target.chatId}`,
     );
-    const messageId = mintStaticMessageId();
+    const streamMessageId = messageMode === "normal" ? claimStreamMessageId(text) : null;
+    const messageId = streamMessageId ?? mintStaticMessageId();
     const raw = { target, replyCtx: replyCtx ?? null, mode: "static" };
     const claimed = options.recordMessage
-      ? claimOutbound(outboundEventType(), messageId, text, raw)
+      ? claimOutbound(streamMessageId ? "message.reply" : outboundEventType(), messageId, text, raw)
       : true;
     if (claimed === false) {
       log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw outbound duplicate skipped msg=${messageId}`);
@@ -691,10 +776,14 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
       ...(replyCtx ? { replyCtx } : {}),
       ...(richFragments.length > 0 ? { richFragments } : {}),
       ...(mediaFragments.length > 0 ? { mediaFragments } : {}),
+      ...(messageMode !== "normal" ? { messageMode } : {}),
+      ...(streamMessageId ? { finalizesStream: true } : {}),
       log,
     });
     recordOutboundAck("message", messageId, result);
-    if (result) outboundDeliveredCount += 1;
+    // Process (thinking) messages are not replies: they must not make a
+    // bootstrap greeting look delivered.
+    if (result && messageMode === "normal") outboundDeliveredCount += 1;
     log?.info?.(
       `[${account.accountId}] clawchat-plugin-openclaw send complete to=${target.chatId}`,
     );
@@ -722,7 +811,11 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     return result;
   };
 
-  const emitFullSegment = async (text: string, urls: string[] = []): Promise<void> => {
+  const emitFullSegment = async (
+    text: string,
+    urls: string[] = [],
+    messageMode: OutboundMessageMode = "normal",
+  ): Promise<void> => {
     if (outputVisibility !== "full" && !splitNormalBlockOutput) {
       appendBufferedText(text);
       appendBufferedUrls(urls);
@@ -735,11 +828,11 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     }
     const trimmed = text.trim();
     if (!trimmed && urls.length === 0) return;
-    const segmentKey = fullSegmentKey(trimmed, urls);
+    const segmentKey = fullSegmentKey(trimmed, urls, messageMode);
     if (emittedFullSegmentSet.has(segmentKey)) return;
     emittedFullSegmentSet.add(segmentKey);
     const mediaFragments = await uploadMediaUrls(urls);
-    await sendStatic(trimmed, mediaFragments, [], { recordMessage: true });
+    await sendStatic(trimmed, mediaFragments, [], { recordMessage: true, messageMode });
   };
 
   const emitFullRuntimeText = async (
@@ -749,15 +842,19 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
   ): Promise<void> => {
     const summary = summarizeValue(text);
     if (!summary && urls.length === 0) return;
-    await emitFullSegment(summary ? `[${label}] ${summary}` : "", urls);
+    await emitFullSegment(summary ? `[${label}] ${summary}` : "", urls, "thinking");
   };
 
+  /** Process output (tool / command / patch / compaction / reasoning): `message_mode: "thinking"`. */
+  const emitProcessSegment = (text: string, urls: string[] = []): Promise<void> =>
+    emitFullSegment(text, urls, "thinking");
+
   // ----- Dispatcher -------------------------------------------------------
 
   const base = runtime.channel.reply.createReplyDispatcherWithTyping({
     humanDelay,
     onReplyStart: async () => {
-      emitTyping(true);
+      startTyping();
     },
     deliver: async (payload: ReplyPayload, info?: { kind: "tool" | "block" | "final" }) => {
       if (consumeTerminalSend(info?.kind ?? "unknown")) return;
@@ -786,7 +883,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
 
       if (payload.isReasoning) {
         if (outputVisibility !== "full") return;
-        await emitFullSegment(text, urls);
+        await emitProcessSegment(text, urls);
         const trimmed = text.trim();
         if (trimmed) reasoningText = reasoningText ? `${reasoningText}\n${trimmed}` : trimmed;
         return;
@@ -816,6 +913,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
         finalDeliverySeen = true;
         if (isClawChatNoopResponseText(text) && !richFragment && urls.length === 0) {
           log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw final suppressed: no-reply token`);
+          failStream("no-reply");
           openclawLlmContextDebug.writeSnapshot({
             visibility: "host_event",
             trace: {
@@ -843,6 +941,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
           finalUrls.length === 0
         ) {
           log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw final suppressed: no-reply token`);
+          failStream("no-reply");
           return;
         }
         const mediaFragments = await uploadMediaUrls(finalUrls);
@@ -866,19 +965,24 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
       if (outputVisibility === "full") void emitFullRuntimeText("error", errorText);
     },
     onIdle: async () => {
-      emitTyping(false);
+      stopTyping();
       if (runDone) return;
       runDone = true;
-      if (finalDeliverySeen) return;
-      const fallbackText = bufferedOutputText.trim();
-      const fallbackUrls = bufferedOutputUrls.slice();
-      if (!fallbackText && fallbackUrls.length === 0) return;
-      const mediaFragments = await uploadMediaUrls(fallbackUrls);
-      const result = await sendStatic(fallbackText, mediaFragments, [], { recordMessage: true });
-      if (result?.messageId) recordThinkingIfLinked(result.messageId);
+      try {
+        if (finalDeliverySeen) return;
+        const fallbackText = bufferedOutputText.trim();
+        const fallbackUrls = bufferedOutputUrls.slice();
+        if (!fallbackText && fallbackUrls.length === 0) return;
+        const mediaFragments = await uploadMediaUrls(fallbackUrls);
+        const result = await sendStatic(fallbackText, mediaFragments, [], { recordMessage: true });
+        if (result?.messageId) recordThinkingIfLinked(result.messageId);
+      } finally {
+        // A preview nothing materialized must not linger as an open stream.
+        failStream("undelivered");
+      }
     },
     onCleanup: () => {
-      emitTyping(false);
+      stopTyping();
     },
   });
 
@@ -888,7 +992,15 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     replyOptions: {
       ...base.replyOptions,
       sourceReplyDeliveryMode: "automatic",
-      disableBlockStreaming: !splitNormalBlockOutput,
+      typingKeepalive: false,
+      // Streaming previews the assistant message and the final materializes it,
+      // so host block chunks (which split one message arbitrarily) stay off.
+      disableBlockStreaming: streamEnabled ? true : !splitNormalBlockOutput,
+      onPartialReply: streamEnabled
+        ? (payload: { text?: string }) => {
+            onStreamPartial(typeof payload?.text === "string" ? payload.text : "");
+          }
+        : undefined,
       suppressDefaultToolProgressMessages: true,
       allowProgressCallbacksWhenSourceDeliverySuppressed: splitFullOutput ? true : undefined,
       onReasoningStream: splitFullOutput
@@ -903,7 +1015,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
       onToolStart: splitFullOutput
         ? async (payload) => {
             if (consumeTerminalSend("tool-start")) return;
-            await emitFullSegment(formatToolStartSummary(payload));
+            await emitProcessSegment(formatToolStartSummary(payload));
           }
         : undefined,
       onToolResult: splitFullOutput
@@ -930,25 +1042,25 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
       onCommandOutput: splitFullOutput
         ? async (payload: Record<string, unknown>) => {
             if (consumeTerminalSend("command-output")) return;
-            await emitFullSegment(formatCommandOutputSummary(payload));
+            await emitProcessSegment(formatCommandOutputSummary(payload));
           }
         : undefined,
       onPatchSummary: splitFullOutput
         ? async (payload: Record<string, unknown>) => {
             if (consumeTerminalSend("patch-summary")) return;
-            await emitFullSegment(formatPatchSummary(payload));
+            await emitProcessSegment(formatPatchSummary(payload));
           }
         : undefined,
       onCompactionStart: splitFullOutput
         ? async () => {
             if (consumeTerminalSend("compaction-start")) return;
-            await emitFullSegment("[compaction] started");
+            await emitProcessSegment("[compaction] started");
           }
         : undefined,
       onCompactionEnd: splitFullOutput
         ? async () => {
             if (consumeTerminalSend("compaction-end")) return;
-            await emitFullSegment("[compaction] finished");
+            await emitProcessSegment("[compaction] finished");
           }
         : undefined,
     },

package/src/reply-stream.ts

@@ -0,0 +1,244 @@
+/**
+ * Outbound reply streaming (protocol §8) for one assistant message.
+ *
+ * Lifecycle on the wire (§8.4 finalize-reply pattern):
+ *
+ *   message.created(M) → message.add(M, seq 0..n)* → message.done(M)
+ *   → message.reply (message_id = M, the polished final)
+ *
+ * `message.done` carries the FINAL text, not the last partial: adds are
+ * throttled, so the last one that went out can be well short of the answer,
+ * and the server materializes its merged reply from the stream. `finish`
+ * therefore takes the final text, sends whatever tail of it the throttle held
+ * back as one last add, and closes with the whole text. A final that does not
+ * extend what was shown cannot be appended (§8.2) — the stream is failed and
+ * the final goes out under its own id.
+ *
+ * or, when the reply turns out not to be sendable (no-reply token, run
+ * aborted, nothing delivered): message.created(M) → … → message.failed(M),
+ * which aborts the stream without materializing anything.
+ *
+ * Streaming frames get no ack (§8.5) and no server-side mention repair, so the
+ * stream only ever carries plain text; mentions, media and rich fragments ride
+ * on the final materialized message, which reuses M so the stored row collapses
+ * to the final reply.
+ *
+ * No-reply guard. A partial must never show something that later turns out to
+ * be a no-reply: nothing is opened until the text is at least
+ * STREAM_HOLD_CHARS long and is not a no-reply / silence marker; a trailing
+ * fragment that could be the start of a no-reply token is held back; and if a
+ * token shows up later the stream stops growing and is failed at finalize.
+ */
+import { EVENT } from "./protocol-types.ts";
+import { isClawChatNoopResponseText } from "./profile-prompt.ts";
+import { isNoReplyTokenPrefix } from "./no-reply.ts";
+import type { ClawlingChatClient } from "./ws-client.ts";
+
+/** Minimum visible (trimmed) length before a stream is opened. */
+export const STREAM_HOLD_CHARS = 32;
+/** Minimum spacing between two `message.add` frames for one stream. */
+export const STREAM_MIN_ADD_INTERVAL_MS = 250;
+/** How far back from the end a partial no-reply token is looked for. */
+const TOKEN_TAIL_WINDOW = 40;
+
+export type StreamableText =
+  | { kind: "hold" }
+  | { kind: "poisoned" }
+  | { kind: "ok"; text: string };
+
+/**
+ * Decide how much of a cumulative partial `text` may be shown.
+ *  - `poisoned`: the text is (or contains) a no-reply token; never show it.
+ *  - `hold`: too short to be sure yet.
+ *  - `ok`: `text` with any trailing possible-token prefix cut off.
+ */
+export function streamableText(text: string): StreamableText {
+  if (isClawChatNoopResponseText(text)) return { kind: "poisoned" };
+  let safe = text;
+  for (let i = Math.max(0, text.length - TOKEN_TAIL_WINDOW); i < text.length; i += 1) {
+    const ch = text[i]!;
+    if (/\s/.test(ch)) continue;
+    if (isNoReplyTokenPrefix(text.slice(i))) {
+      safe = text.slice(0, i);
+      break;
+    }
+  }
+  if (safe.trim().length < STREAM_HOLD_CHARS) return { kind: "hold" };
+  return { kind: "ok", text: safe };
+}
+
+export interface ReplyStreamOptions {
+  client: ClawlingChatClient;
+  chatId: string;
+  mintMessageId: () => string;
+  now?: () => number;
+  log?: { info?: (m: string) => void; error?: (m: string) => void };
+  logPrefix?: string;
+}
+
+export interface ReplyStream {
+  /** Feed the cumulative text of the current assistant message. */
+  update(text: string): void;
+  /**
+   * True when `text` is showable but does not extend what this open stream
+   * already shows: a new assistant message or a host rewrite. The caller then
+   * fails this stream and starts a new one. Held / poisoned text never
+   * diverges (nothing new would be shown).
+   */
+  diverges(text: string): boolean;
+  /** True once `message.created` went out and the stream is not closed. */
+  isOpen(): boolean;
+  /** Text the recipient currently sees for this stream. */
+  shownText(): string;
+  /**
+   * Close the stream with the final reply text: an unthrottled last
+   * `message.add` for any tail not yet shown, then `message.done` carrying
+   * `finalText`. Returns the message_id for the final materialized message to
+   * reuse. Returns null — the final then uses a fresh id — when no stream is
+   * open, or when `finalText` does not extend the shown text (or is a no-reply),
+   * in which case the stream is failed instead.
+   */
+  finish(finalText: string): string | null;
+  /** Abort an open stream with `message.failed`. No-op when nothing is open. */
+  fail(reason: string): void;
+}
+
+export function createReplyStream(options: ReplyStreamOptions): ReplyStream {
+  const now = options.now ?? Date.now;
+  const prefix = options.logPrefix ?? "clawchat-plugin-openclaw";
+  let messageId: string | null = null;
+  let closed = false;
+  let poisoned = false;
+  let diverged = false;
+  let sent = "";
+  let sequence = -1;
+  let lastAddAt = 0;
+  let startedAt = 0;
+
+  const canSend = (): boolean => {
+    const client = options.client as { transportState?: string; state?: string };
+    if (client.transportState !== undefined && client.transportState !== "open") return false;
+    if (client.state !== undefined && client.state !== "connected") return false;
+    return true;
+  };
+
+  const emit = (event: string, payload: Record<string, unknown>): boolean => {
+    try {
+      options.client.emitRaw(event, payload, { chat_id: options.chatId });
+      return true;
+    } catch (error) {
+      options.log?.error?.(`${prefix} stream ${event} failed msg=${messageId}: ${String(error)}`);
+      return false;
+    }
+  };
+
+  const streamingState = (status: "streaming" | "done" | "failed", completedAt: number | null) => ({
+    status,
+    sequence: Math.max(sequence, 0),
+    mutation_policy: "append_text_only",
+    started_at: startedAt,
+    completed_at: completedAt,
+  });
+
+  const sendAdd = (next: string, at: number): boolean => {
+    sequence += 1;
+    const ok = emit(EVENT.MESSAGE_ADD, {
+      message_id: messageId,
+      sequence,
+      mutation: { type: "append", target_fragment_index: 0 },
+      fragments: [{ kind: "text", text: next, delta: next.slice(sent.length) }],
+      streaming: streamingState("streaming", null),
+      added_at: at,
+    });
+    if (!ok) {
+      sequence -= 1;
+      return false;
+    }
+    sent = next;
+    lastAddAt = at;
+    return true;
+  };
+
+  const fail = (reason: string): void => {
+    if (!messageId || closed) return;
+    closed = true;
+    const at = now();
+    emit(EVENT.MESSAGE_FAILED, {
+      message_id: messageId,
+      fragments: [{ kind: "text", text: sent }],
+      streaming: streamingState("failed", at),
+      completed_at: at,
+    });
+    options.log?.info?.(`${prefix} stream failed msg=${messageId} reason=${reason}`);
+  };
+
+  return {
+    update(text: string) {
+      if (closed || poisoned || diverged) return;
+      const decision = streamableText(text);
+      if (decision.kind === "poisoned") {
+        poisoned = true;
+        options.log?.info?.(`${prefix} stream halted: no-reply token in partial msg=${messageId ?? "-"}`);
+        return;
+      }
+      if (decision.kind === "hold") return;
+      const next = decision.text;
+      if (messageId && !next.startsWith(sent)) {
+        // §8.2 delta invariant cannot hold for a rewrite; stop growing the
+        // stream and let the final message (same id) carry the real text.
+        diverged = true;
+        return;
+      }
+      if (next === sent) return;
+      if (!canSend()) return;
+      if (!messageId) {
+        const id = options.mintMessageId();
+        startedAt = now();
+        if (!emit(EVENT.MESSAGE_CREATED, { message_id: id, message_mode: "normal" })) return;
+        messageId = id;
+        options.log?.info?.(`${prefix} stream opened msg=${id} to=${options.chatId}`);
+      } else if (now() - lastAddAt < STREAM_MIN_ADD_INTERVAL_MS) {
+        return;
+      }
+      sendAdd(next, now());
+    },
+    diverges(text: string) {
+      if (!messageId || closed) return false;
+      const decision = streamableText(text);
+      return decision.kind === "ok" && !decision.text.startsWith(sent);
+    },
+    isOpen() {
+      return messageId !== null && !closed;
+    },
+    shownText() {
+      return sent;
+    },
+    finish(finalText: string) {
+      if (!messageId || closed) return null;
+      if (streamableText(finalText).kind === "poisoned") {
+        fail("no-reply");
+        return null;
+      }
+      // Trailing whitespace a partial carried may be trimmed off the final.
+      if (!finalText.startsWith(sent.trimEnd())) {
+        fail("superseded");
+        return null;
+      }
+      if (finalText.length > sent.length && finalText.startsWith(sent)) {
+        // Past the throttle: this is the last frame before done.
+        sendAdd(finalText, now());
+      }
+      closed = true;
+      const at = now();
+      emit(EVENT.MESSAGE_DONE, {
+        message_id: messageId,
+        fragments: [{ kind: "text", text: finalText }],
+        streaming: streamingState("done", at),
+        completed_at: at,
+      });
+      options.log?.info?.(`${prefix} stream done msg=${messageId} text_len=${finalText.length}`);
+      return messageId;
+    },
+    fail,
+  };
+}

package/src/runtime.ts

@@ -96,6 +96,7 @@ import {
 import { refreshGroupProfile, syncFirstSeenClawChatProfiles } from "./profile-sync.ts";
 import { pullGroupMetadata, pullOwnerMetadata } from "./clawchat-metadata.ts";
 import { deleteClawChatMemoryFile, readClawChatMemoryFile } from "./clawchat-memory.ts";
+import { registerMentionRosterResolver } from "./mention-autolink.ts";
 import {
   clearClawChatPromptInjectionForSession,
   stageClawChatPromptInjection,
@@ -3831,6 +3832,21 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     return;
   }
   activeClients.set(accountId, client);
+  // Text "@name" autolinking on outbound group sends reads the same cached
+  // roster (participant ids + nicknames) the group prompt shows the model.
+  const unregisterMentionRoster = registerMentionRosterResolver(accountId, async (groupId) => {
+    const memoryRoot = resolveMemoryRootForPeer({ kind: "group", id: groupId });
+    if (!memoryRoot) return [];
+    let ownerMetadata: ClawChatPromptMetadata | null = null;
+    try {
+      const ownerFile = await readClawChatMemoryFile(memoryRoot, { targetType: "owner", targetId: "owner" });
+      ownerMetadata = ownerFile.exists ? ownerFile.metadata : null;
+    } catch {
+      ownerMetadata = null;
+    }
+    const participants = await loadGroupParticipantsForPrompt({ memoryRoot, groupId, ownerMetadata });
+    return participants.map((participant) => ({ userId: participant.id, name: participant.name }));
+  });
   log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime active client registered`);
   setStatus({
     ...getStatus(),
@@ -3843,6 +3859,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   await waitUntilAbort(abortSignal, async () => {
     log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime abort received; closing client`);
     activeClients.delete(accountId);
+    unregisterMentionRoster();
     closingForAbort = true;
     clearBootstrapRetry();
     // §A.1 — stop the proactive refresh timer on shutdown.

package/src/skill-update.ts

@@ -71,7 +71,7 @@ export const OFFICIAL_SKILLS_BASE =
  * in the install-cli repo, bump this constant, ship it. `liveware-sample.ts`
  * imports the same ref, so the `livewares` tree at that tag is pinned too.
  */
-export const DEFAULT_SKILLS_REF = "skills-v1.15.2";
+export const DEFAULT_SKILLS_REF = "skills-v1.16.0";
 
 /** Refuse to treat an absurdly large response as a skill file (defence in depth). */
 export const MAX_SKILL_BYTES = 256 * 1024;