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

package/dist/src/reply-stream.js

@@ -0,0 +1,208 @@
+/**
+ * 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.js";
+import { isClawChatNoopResponseText } from "./profile-prompt.js";
+import { isNoReplyTokenPrefix } from "./no-reply.js";
+/** 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;
+/**
+ * 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) {
+    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 function createReplyStream(options) {
+    const now = options.now ?? Date.now;
+    const prefix = options.logPrefix ?? "clawchat-plugin-openclaw";
+    let messageId = null;
+    let closed = false;
+    let poisoned = false;
+    let diverged = false;
+    let sent = "";
+    let sequence = -1;
+    let lastAddAt = 0;
+    let startedAt = 0;
+    const canSend = () => {
+        const client = options.client;
+        if (client.transportState !== undefined && client.transportState !== "open")
+            return false;
+        if (client.state !== undefined && client.state !== "connected")
+            return false;
+        return true;
+    };
+    const emit = (event, payload) => {
+        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, completedAt) => ({
+        status,
+        sequence: Math.max(sequence, 0),
+        mutation_policy: "append_text_only",
+        started_at: startedAt,
+        completed_at: completedAt,
+    });
+    const sendAdd = (next, at) => {
+        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) => {
+        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) {
+            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) {
+            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) {
+            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/dist/src/runtime.js

@@ -33,6 +33,7 @@ import { loadClawChatPromptMetadata, renderClawChatProfilePrompt, resolveSenderR
 import { refreshGroupProfile, syncFirstSeenClawChatProfiles } from "./profile-sync.js";
 import { pullGroupMetadata, pullOwnerMetadata } from "./clawchat-metadata.js";
 import { deleteClawChatMemoryFile, readClawChatMemoryFile } from "./clawchat-memory.js";
+import { registerMentionRosterResolver } from "./mention-autolink.js";
 import { clearClawChatPromptInjectionForSession, stageClawChatPromptInjection, } from "./prompt-injection.js";
 import { createGroupMessageCoalescer } from "./group-message-coalescer.js";
 import { openclawLlmContextDebug } from "./llm-context-debug.js";
@@ -858,6 +859,10 @@ export async function startOpenclawClawlingGateway(params) {
     // `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 = 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 = null;
     if (store) {
         const stateDirForSample = runtime.state?.resolveStateDir?.();
         const livewareSampleDeps = {
@@ -900,6 +905,7 @@ export async function startOpenclawClawlingGateway(params) {
         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
@@ -909,9 +915,12 @@ export async function startOpenclawClawlingGateway(params) {
         }
         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);
                 }
@@ -1187,6 +1196,25 @@ export async function startOpenclawClawlingGateway(params) {
     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) => {
+        const subject = typeof entityId === "string" ? entityId.trim() : "";
+        if (!persistOwnerProfile || !subject || subject !== account.ownerUserId)
+            return;
+        void (async () => {
+            try {
+                const owner = await getConversationApiClient().getAgentOwner();
+                persistOwnerProfile(owner);
+            }
+            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) => {
         try {
             await pullOwnerMetadata({
@@ -2304,6 +2332,9 @@ export async function startOpenclawClawlingGateway(params) {
                 if (type === "friend.added") {
                     scheduleFriendGreeting(payload);
                 }
+                if (type === "friend.profile_updated") {
+                    refreshOwnerProfileOnUpdate(payload?.entity_id);
+                }
             }
         }
     });
@@ -2408,6 +2439,8 @@ export async function startOpenclawClawlingGateway(params) {
                         ? 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;
@@ -2443,6 +2476,7 @@ export async function startOpenclawClawlingGateway(params) {
             basePrompt: turn.peer.kind === "group" ? getClawChatGroupPrompt() : getClawChatUserPrompt(),
             ...promptMetadata,
             ownerIdFallback: account.ownerUserId,
+            currentAgentIdFallback: account.userId,
             groupParticipants,
             turn: {
                 chatType: promptChatType,
@@ -2462,9 +2496,76 @@ export async function startOpenclawClawlingGateway(params) {
             },
         });
     };
+    // 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, userId) => {
+        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();
+    const withCachedGroupSenderNames = async (turn, memoryRoot) => {
+        if (turn.peer.kind !== "group" || !memoryRoot)
+            return turn;
+        const isBareId = (name, id) => !name || name === id;
+        const cache = new Map();
+        let groupOwner = null;
+        const lookup = async (userId) => {
+            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) => {
         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;
     };
     const resolveSenderBatchIdentityForTurn = (turn) => {
@@ -2479,7 +2580,9 @@ export async function startOpenclawClawlingGateway(params) {
             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 } : {}),
         };
     };
     const claimInboundTurn = (turn) => {
@@ -2549,6 +2652,7 @@ export async function startOpenclawClawlingGateway(params) {
         catch (err) {
             log?.error?.(`[${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;
@@ -2679,6 +2783,7 @@ export async function startOpenclawClawlingGateway(params) {
                 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,
@@ -3229,6 +3334,23 @@ export async function startOpenclawClawlingGateway(params) {
         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 = 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(),
@@ -3240,6 +3362,7 @@ export async function startOpenclawClawlingGateway(params) {
     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.
@@ -3251,6 +3374,16 @@ export async function startOpenclawClawlingGateway(params) {
             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/dist/src/skill-update.js

@@ -66,7 +66,7 @@ export const OFFICIAL_SKILLS_BASE = "https://raw.githubusercontent.com/clawling/
  * 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;
 /** This adapter's host target inside `skills/manifest.json`. */

package/dist/src/tools-schema.js

@@ -205,7 +205,7 @@ export const ClawchatCreateMomentSchema = Type.Object({
         description: "Moment text. At least one of text or images is required.",
     })),
     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).",
     }))),
 });
 export const ClawchatDeleteMomentSchema = Type.Object({

package/dist/src/tools.js

@@ -28,6 +28,15 @@ function extractRequestId(err) {
     }
     return undefined;
 }
+/**
+ * What the agent must do with the later `permission_result` receipt
+ * (agent-protocol §2.8): on approval the SERVER executes the gated call, so a
+ * second call would duplicate it or raise a fresh card. Only `approved_retry`
+ * (reads, which are never replayed) asks for exactly one more call.
+ */
+const PERMISSION_RECEIPT_RULE = "When the result arrives: outcome \"approved\" (or \"auto_allowed\") means the server has already done it for you — do not call this tool again; " +
+    "only outcome \"approved_retry\" means call this same tool once more with the same arguments. " +
+    "Anything the server produced (a new id, a code, read data) comes in that message's Result line.";
 function permissionGateResult(err) {
     const code = err.meta?.code;
     const requestId = extractRequestId(err);
@@ -38,7 +47,8 @@ function permissionGateResult(err) {
             "This operation requires the owner's approval and has been submitted for review" +
                 (requestId ? ` (request_id=${requestId})` : "") +
                 ". It has NOT failed. Do not retry — the result will arrive later as a normal " +
-                "chat message; wait for it instead of calling this tool again.";
+                "chat message; wait for it instead of calling this tool again. " +
+                PERMISSION_RECEIPT_RULE;
         status = "pending";
     }
     else {
@@ -120,6 +130,46 @@ function inferMimeFromPath(filePath) {
     const ext = path.extname(filePath).toLowerCase();
     return MIME_BY_EXT[ext] ?? "application/octet-stream";
 }
+/**
+ * Classify `clawchat_create_moment` image entries: http(s) URLs pass through;
+ * an existing absolute local regular file (≤ 20MB) is marked for upload; any
+ * other value is a validation error naming the offending index.
+ */
+function planMomentImages(images) {
+    const entries = [];
+    for (const [i, raw] of images.entries()) {
+        const where = `clawchat-plugin-openclaw: images[${i}]`;
+        const value = typeof raw === "string" ? raw.trim() : "";
+        if (!value) {
+            return { ok: false, message: `${where} must be an http(s) image URL or an absolute local image path` };
+        }
+        if (/^https?:\/\/\S+$/i.test(value)) {
+            entries.push({ kind: "url", url: value });
+            continue;
+        }
+        if (!path.isAbsolute(value)) {
+            return {
+                ok: false,
+                message: `${where} (${JSON.stringify(value)}) is neither an http(s) URL nor an absolute local file path; no moment was created`,
+            };
+        }
+        let stat;
+        try {
+            stat = fs.statSync(value);
+        }
+        catch {
+            return { ok: false, message: `${where}: local file ${value} does not exist; no moment was created` };
+        }
+        if (!stat.isFile()) {
+            return { ok: false, message: `${where}: ${value} is not a regular file; no moment was created` };
+        }
+        if (stat.size > MAX_UPLOAD_BYTES) {
+            return { ok: false, message: `${where}: ${value} is too large (${stat.size} bytes; max 20MB)` };
+        }
+        entries.push({ kind: "local", path: value });
+    }
+    return { ok: true, entries };
+}
 function validateMentionMessageParams(params) {
     if (!params || typeof params !== "object") {
         return { ok: false, message: "clawchat-plugin-openclaw: params are required" };
@@ -285,6 +335,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
             ok: true,
             client: createOpenclawClawlingApiClient({
                 baseUrl: acct.baseUrl,
+                mediaBaseUrl: acct.mediaBaseUrl,
                 token: acct.token,
                 userId: acct.userId,
             }),
@@ -329,8 +380,16 @@ export function registerOpenclawClawlingTools(api, options = {}) {
                             ? rawData
                             : {};
                         const outcome = mapGateOutcome(code, gateData);
-                        if (outcome !== null)
-                            return jsonResponse(outcome);
+                        if (outcome !== null) {
+                            // `next_step` is added here, not in mapGateOutcome: that mapping
+                            // is pinned byte-for-byte against the Hermes parity fixtures.
+                            return jsonResponse(outcome.status === "pending_owner_approval"
+                                ? {
+                                    ...outcome,
+                                    next_step: "Waiting for the owner's approval; do not call this tool again now. " + PERMISSION_RECEIPT_RULE,
+                                }
+                                : outcome);
+                        }
                     }
                     return apiError(err);
                 }
@@ -1100,7 +1159,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
             label: "Create ClawChat Moment",
             description: toolDescription("Create a new ClawChat moment/dynamic for the configured ClawChat account. " +
                 "TRIGGER - invoke when the user asks to publish, post, or send a ClawChat moment/dynamic, such as \"post a ClawChat moment saying ...\", \"publish a dynamic ...\", or \"send a friend moment ...\". " +
-                "At least one of text or images must be present. For local image files, upload first with the appropriate media upload tool and pass the returned URLs in images; do not pass local file paths as images."),
+                "At least one of text or images must be present. Each images entry is either an http(s) image URL (used as-is) or an absolute local image path (max 20MB) — for a local path this tool uploads it to ClawChat media itself and uses the hosted URL, so no separate upload step is needed. Any other value (relative path, file:// or data: URI, missing file) is rejected and no moment is created."),
             parameters: ClawchatCreateMomentSchema,
             async execute(_callId, params) {
                 return await recordClawchatToolCall(accountId, "clawchat_create_moment", params, async () => {
@@ -1110,10 +1169,33 @@ export function registerOpenclawClawlingTools(api, options = {}) {
                     if (!text && (!images || images.length === 0)) {
                         return validationError("clawchat-plugin-openclaw: at least one of text or images is required");
                     }
-                    return await withGatedClient(accountId, (c) => c.createMoment({
-                        ...(text !== undefined ? { text } : {}),
-                        ...(images !== undefined ? { images } : {}),
-                    }));
+                    // Validate every entry before touching the network, so a bad value
+                    // never leaves a half-uploaded batch or a moment with a broken image.
+                    const plan = images !== undefined ? planMomentImages(images) : { ok: true, entries: [] };
+                    if (!plan.ok)
+                        return validationError(plan.message);
+                    return await withGatedClient(accountId, async (c) => {
+                        const resolved = [];
+                        for (const entry of plan.entries) {
+                            if (entry.kind === "url") {
+                                resolved.push(entry.url);
+                                continue;
+                            }
+                            const uploaded = await c.uploadMedia({
+                                buffer: fs.readFileSync(entry.path),
+                                filename: path.basename(entry.path),
+                                mime: inferMimeFromPath(entry.path),
+                            });
+                            if (uploaded.kind !== "image") {
+                                throw new Error(`clawchat-plugin-openclaw: ${entry.path} is not an image (media service classified it as ${uploaded.kind}); no moment was created`);
+                            }
+                            resolved.push(uploaded.url);
+                        }
+                        return await c.createMoment({
+                            ...(text !== undefined ? { text } : {}),
+                            ...(images !== undefined ? { images: resolved } : {}),
+                        });
+                    });
                 });
             },
         };
@@ -1449,11 +1531,18 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         return {
             name: "clawchat_orchestrate_set_agent_behavior",
             label: "Rewrite A Sibling's System Prompt",
-            description: toolDescription("Replace the WHOLE system prompt (behavior) of one of the owner's other agents. " +
+            description: toolDescription("Stage/room speaking rules go in the group description, not here; for a stage, append the stage sentence below to off-desktop members (clawchat-orchestration skill). " +
+                "Replace the WHOLE system prompt (behavior) of one of the owner's other agents. " +
                 "TRIGGER — invoke when the owner asks to change how another agent behaves, talks, or what it is for. " +
                 "This REPLACES the entire field — call clawchat_orchestrate_get_agent first, edit the text you got back, and send the full new value. " +
                 "Sending a fragment deletes everything else and the owner cannot recover it. Max 3000 runes. " +
-                "Nickname and bio cannot be changed here."),
+                "Nickname and bio cannot be changed here. " +
+                "Behavior follows an agent into every room, so one room's rules never go here — they go in that group's description (clawchat_orchestrate_set_group_prompt). " +
+                "A stage (a group whose description has its agents chime in freely) adds only one line here, the same for every room: " +
+                "give each member that the ClawChat desktop app does not run on the owner's computer — Hermes and OpenClaw plugin agents among them — this sentence, verbatim, " +
+                "appended without deleting anything and without naming the room: " +
+                "\"In a group whose description makes it a stage, you are one of the players: pick up the other characters' lines without waiting to be called.\" " +
+                "Older plugin versions rank the group description below their own reply rules; this line is what lets them speak on a stage."),
             parameters: ClawchatOrchSetAgentBehaviorSchema,
             async execute(_callId, params) {
                 return await recordClawchatToolCall(accountId, "clawchat_orchestrate_set_agent_behavior", params, async () => {
@@ -1497,11 +1586,15 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         return {
             name: "clawchat_orchestrate_set_group_prompt",
             label: "Rewrite A Group's System Prompt",
-            description: toolDescription("Replace the WHOLE system prompt (description) of a group the owner administers. " +
+            description: toolDescription("Stage/room speaking rules go here, in the group description; for a stage, also append the stage sentence to off-desktop members' behavior (clawchat-orchestration skill). " +
+                "Replace the WHOLE system prompt (description) of a group the owner administers. " +
                 "TRIGGER — invoke when the owner asks to change how a group behaves as a whole. " +
                 "This REPLACES the entire field — call clawchat_orchestrate_get_group first and send the full new value. " +
                 "Sending a fragment deletes everything else and the owner cannot recover it. Max 3000 runes. " +
-                "The group title cannot be changed here."),
+                "The group title cannot be changed here. " +
+                "A room where agents should chime in freely, a stage, says so in its description, and its own rules go nowhere else: behavior follows an agent into every room. " +
+                "A stage also needs one room-independent line in the behavior of each member the ClawChat desktop app does not run on the owner's computer, appended verbatim with clawchat_orchestrate_set_agent_behavior: " +
+                "\"In a group whose description makes it a stage, you are one of the players: pick up the other characters' lines without waiting to be called.\""),
             parameters: ClawchatOrchSetGroupPromptSchema,
             async execute(_callId, params) {
                 return await recordClawchatToolCall(accountId, "clawchat_orchestrate_set_group_prompt", params, async () => {