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

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,
@@ -1209,6 +1210,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   // `sendOwnerSkillMessage` below) — both live in this same function closure, so
   // the forward reference here just resolves to the fresh value at call time.
   let livewareSampleNotify: (text: string) => Promise<boolean> = async () => false;
+  // The supervisor this gateway call shares (new or adopted). The abort cleanup
+  // below awaits its stop() so the host's channel stop (which waits on this
+  // task) does not return while liveware children are still being killed.
+  let livewareSampleForShutdown: LivewareSampleSupervisor | null = null;
   if (store) {
     const stateDirForSample = runtime.state?.resolveStateDir?.();
     const livewareSampleDeps: LivewareSampleSupervisorDeps = {
@@ -1252,6 +1257,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     livewareSampleSupervisors.set(abortSignal, supervisorsForSignal);
     const supervisorKey = `openclaw:${accountId}`;
     const runningSupervisor = supervisorsForSignal.get(supervisorKey);
+    livewareSampleForShutdown = runningSupervisor ?? null;
     if (runningSupervisor) {
       // A gateway re-entry (refresh/backoff reconnect), not a fresh channel start:
       // hand the live supervisor this closure's token + REST client + notify path
@@ -1262,9 +1268,12 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       runningSupervisor.adoptDeps(livewareSampleDeps);
     } else {
       const livewareSampleSupervisor = new LivewareSampleSupervisor(livewareSampleDeps);
+      livewareSampleForShutdown = livewareSampleSupervisor;
       supervisorsForSignal.set(supervisorKey, livewareSampleSupervisor);
       abortSignal.addEventListener("abort", () => {
-        livewareSampleSupervisor.stop();
+        // Starts the SIGTERM → SIGKILL teardown at once; the gateway's own
+        // abort cleanup awaits the same (idempotent) stop() promise.
+        void livewareSampleSupervisor.stop();
         if (supervisorsForSignal.get(supervisorKey) === livewareSampleSupervisor) {
           supervisorsForSignal.delete(supervisorKey);
         }
@@ -1575,6 +1584,25 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   const persistOwnerProfile = upsertOwnerProfile
     ? makeOwnerProfilePersister({ upsertOwnerProfile }, { accountId })
     : undefined;
+  // The owner_profile row is where owner-language copy reads its locale
+  // (framework errors, greetings, liveware intros). It was only refreshed on
+  // owner metadata pulls, so an owner who switched app language kept getting
+  // the old one. friend.profile_updated also reaches the agent when the
+  // owner edits their profile; refetch just the owner row then.
+  const refreshOwnerProfileOnUpdate = (entityId: unknown): void => {
+    const subject = typeof entityId === "string" ? entityId.trim() : "";
+    if (!persistOwnerProfile || !subject || subject !== account.ownerUserId) return;
+    void (async () => {
+      try {
+        const owner = await getConversationApiClient().getAgentOwner();
+        persistOwnerProfile(owner as unknown as Record<string, unknown>);
+      } catch (err) {
+        log?.error?.(
+          `[${accountId}] clawchat-plugin-openclaw owner profile refresh failed source=friend.profile_updated: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    })();
+  };
   const refreshAgentBehavior = async (options: {
     metadataVersion?: number;
     source: string;
@@ -2790,6 +2818,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         if (type === "friend.added") {
           scheduleFriendGreeting(payload as Record<string, unknown> | undefined);
         }
+        if (type === "friend.profile_updated") {
+          refreshOwnerProfileOnUpdate(payload?.entity_id);
+        }
       }
     }
   });
@@ -2902,6 +2933,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
             ? groupFile.metadata.group_owner_nickname ?? metadata?.nickname ?? userId
             : metadata?.nickname ?? userId;
       const profileType = metadata?.profile_type ?? (userId === account.userId ? "agent" : "user");
+      if (name !== userId) knownNicknames.set(userId, name);
       participants.push({ id: userId, name, profileType, isAgentOwner, isGroupOwner });
     }
     return participants;
@@ -2940,6 +2972,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       basePrompt: turn.peer.kind === "group" ? getClawChatGroupPrompt() : getClawChatUserPrompt(),
       ...promptMetadata,
       ownerIdFallback: account.ownerUserId,
+      currentAgentIdFallback: account.userId,
       groupParticipants,
       turn: {
         chatType: promptChatType,
@@ -2960,8 +2993,76 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     });
   };
 
+  // Group frames often carry the sender's id as nick_name. Prefer the nickname
+  // already cached in ClawChat memory (owner.md for the owner and this agent,
+  // users/<id>.md for everyone else, the group's group_owner_nickname for its
+  // owner); keep the id when nothing is cached.
+  const cachedNicknameFor = async (memoryRoot: string, userId: string): Promise<string | null> => {
+    try {
+      if (userId === account.ownerUserId || userId === account.userId) {
+        const ownerFile = await readClawChatMemoryFile(memoryRoot, { targetType: "owner", targetId: "owner" });
+        const nickname = userId === account.userId
+          ? ownerFile.metadata.agent_nickname
+          : ownerFile.metadata.agent_owner_nickname;
+        if (nickname) return nickname;
+      }
+      const userFile = await readClawChatMemoryFile(memoryRoot, { targetType: "user", targetId: userId });
+      return userFile.exists && userFile.metadata.nickname ? userFile.metadata.nickname : null;
+    } catch {
+      return null;
+    }
+  };
+
+  // Nicknames seen while building group prompts, so ingest can label a
+  // coalesced batch's transcript ("Alice:" rather than "usr_…:") without
+  // touching disk.
+  const knownNicknames = new Map<string, string>();
+
+  const withCachedGroupSenderNames = async <T extends IngestTurnParams>(
+    turn: T,
+    memoryRoot: string | null,
+  ): Promise<T> => {
+    if (turn.peer.kind !== "group" || !memoryRoot) return turn;
+    const isBareId = (name: string | null | undefined, id: string): boolean => !name || name === id;
+    const cache = new Map<string, string | null>();
+    let groupOwner: { id?: string; nickname?: string } | null = null;
+    const lookup = async (userId: string): Promise<string | null> => {
+      if (!cache.has(userId)) {
+        let nickname = await cachedNicknameFor(memoryRoot, userId);
+        if (!nickname) {
+          if (!groupOwner) {
+            try {
+              const groupFile = await readClawChatMemoryFile(memoryRoot, { targetType: "group", targetId: turn.peer.id });
+              groupOwner = { id: groupFile.metadata.group_owner_id, nickname: groupFile.metadata.group_owner_nickname };
+            } catch {
+              groupOwner = {};
+            }
+          }
+          if (groupOwner.id === userId && groupOwner.nickname) nickname = groupOwner.nickname;
+        }
+        cache.set(userId, nickname);
+        if (nickname) knownNicknames.set(userId, nickname);
+      }
+      return cache.get(userId) ?? null;
+    };
+    const senderNickName = isBareId(turn.senderNickName, turn.senderId)
+      ? (await lookup(turn.senderId)) ?? turn.senderNickName
+      : turn.senderNickName;
+    const groupMessages = turn.groupMessages
+      ? await Promise.all(turn.groupMessages.map(async (message) =>
+          isBareId(message.senderName, message.senderId)
+            ? { ...message, senderName: (await lookup(message.senderId)) ?? message.senderName }
+            : message
+        ))
+      : turn.groupMessages;
+    return { ...turn, senderNickName, ...(groupMessages ? { groupMessages } : {}) };
+  };
+
   const resolveSenderNickNameForTurn = (turn: IngestTurnParams): string => {
     if (turn.senderNickName && turn.senderNickName !== turn.senderId) return turn.senderNickName;
+    // Synchronous on purpose: an await here would reorder same-group frames.
+    const known = turn.peer.kind === "group" ? knownNicknames.get(turn.senderId) : undefined;
+    if (known) return known;
     return turn.senderNickName || turn.senderId;
   };
 
@@ -2969,7 +3070,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     senderRelation: NonNullable<IngestTurnParams["senderRelation"]>;
     senderProfileType: string;
     senderIsOwner: boolean;
-    senderIsGroupOwner: boolean;
+    senderIsGroupOwner?: boolean;
   } => {
     const senderRelation = resolveSenderRelation({
       senderId: turn.senderId,
@@ -2982,7 +3083,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       senderProfileType: turn.senderProfileType ??
         (senderRelation === "self_agent" || senderRelation === "peer_agent" ? "agent" : "user"),
       senderIsOwner: senderRelation === "owner",
-      senderIsGroupOwner: turn.senderIsGroupOwner ?? false,
+      // Left undefined when the frame does not say, so the prompt falls back
+      // to the group metadata's group_owner_id instead of a forced false.
+      ...(turn.senderIsGroupOwner !== undefined ? { senderIsGroupOwner: turn.senderIsGroupOwner } : {}),
     };
   };
 
@@ -3061,6 +3164,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         `[${accountId}] clawchat-plugin-openclaw message metadata refresh failed: ${err instanceof Error ? err.message : String(err)}`,
       );
     }
+    turn = await withCachedGroupSenderNames(turn, memoryRoot);
     const conversationTarget = `${CHANNEL_ID}:${formatConversationSubject(turn.peer)}`;
     const turnPrompt = await buildPromptForTurn(turn, memoryRoot);
     const senderIsOwner = turn.senderIsOwner === true || turn.senderId === account.ownerUserId;
@@ -3201,6 +3305,8 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
           runtime,
           account,
           client,
+          resolveOwnerLocale: () =>
+            store?.getOwnerProfile?.({ platform: "openclaw", accountId })?.locale ?? null,
           target: { chatId: turn.peer.id, chatType: turn.peer.kind },
           ...(replyCtx ? { replyCtx } : {}),
           inboundMessageId: turn.messageId,
@@ -3831,6 +3937,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 +3964,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.
@@ -3854,6 +3976,17 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       closeReason: "client close",
     });
     client.close();
+    if (livewareSampleForShutdown) {
+      // SIGTERM, then SIGKILL after KILL_GRACE_MS (3 s): inside the host's
+      // 5 s wait for this task, so a stuck child no longer outlives the stop.
+      try {
+        await livewareSampleForShutdown.stop();
+      } catch (err) {
+        log?.error?.(
+          `[${accountId}] clawchat-plugin-openclaw liveware-sample stop failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
     setStatus({
       ...getStatus(),
       connected: false,

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.17.0";
 
 /** Refuse to treat an absurdly large response as a skill file (defence in depth). */
 export const MAX_SKILL_BYTES = 256 * 1024;

package/src/tools-schema.ts

@@ -328,7 +328,7 @@ export const ClawchatCreateMomentSchema = Type.Object({
   images: Type.Optional(
     Type.Array(
       Type.String({
-        description: "Image URL for the moment. Upload local files first; do not pass local paths.",
+        description: "An http(s) image URL, or an absolute local image path (the tool uploads it and uses the hosted URL).",
       }),
     ),
   ),