@newbase-clawchat/openclaw-clawchat 2026.5.12-2 → 2026.5.12-21

package/dist/src/runtime.js

@@ -1,8 +1,11 @@
-import { AckTimeoutError, AuthError, ProtocolError, StateError, TransportError, } from "@newbase-clawchat/sdk";
+import { AckTimeoutError, AuthError, ProtocolError, StateError, TransportError, EVENT, } from "./protocol-types.js";
 import { waitUntilAbort } from "openclaw/plugin-sdk/channel-lifecycle";
+import { hasControlCommand } from "openclaw/plugin-sdk/command-detection";
 import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 import { createOpenclawClawlingClient } from "./client.js";
-import { CHANNEL_ID } from "./config.js";
+import { createOpenclawClawlingApiClient } from "./api-client.js";
+import { ClawlingApiError } from "./api-types.js";
+import { CHANNEL_ID, effectiveGroupCommandMode, } from "./config.js";
 import { dispatchOpenclawClawlingInbound } from "./inbound.js";
 import { fetchInboundMedia } from "./media-runtime.js";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.js";
@@ -10,12 +13,69 @@ import { sendStreamingText } from "./streaming.js";
 import { flushAlignedOutboundQueue, getAlignedOutboundQueueSize, setAlignedOutboundLogContext, } from "./outbound.js";
 import { formatWsLog } from "./ws-log.js";
 import { createProtocolControlHandler, createReconnectTracker } from "./ws-alignment.js";
+import { clawChatDbPathForStateDir, getClawChatStore, } from "./storage.js";
+import { getClawChatGroupPrompt, getClawChatUserPrompt } from "./plugin-prompts.js";
+import { loadClawChatPromptMetadata, renderClawChatProfilePrompt, resolveSenderRelation, } from "./profile-prompt.js";
+import { refreshGroupProfile, syncFirstSeenClawChatProfiles } from "./profile-sync.js";
+import { pullGroupMetadata, pullOwnerMetadata } from "./clawchat-metadata.js";
+import { clearClawChatPromptInjectionForSession, stageClawChatPromptInjection, } from "./prompt-injection.js";
+import { createGroupMessageCoalescer } from "./group-message-coalescer.js";
 const { setRuntime: setOpenclawClawlingRuntime, getRuntime: getOpenclawClawlingRuntime } = createPluginRuntimeStore("openclaw-clawchat runtime not initialized");
 export { setOpenclawClawlingRuntime, getOpenclawClawlingRuntime };
 const activeClients = new Map();
+const CLAWCHAT_PLUGIN_SLASH_COMMANDS = new Set(["clawchat-activate"]);
+const CLAWCHAT_MEMORY_ROOT_UNAVAILABLE = "ClawChat memory root unavailable: OpenClaw workspaceDir could not be resolved";
+const OPENCLAW_CONFIRM_SLASH_COMMANDS = new Set([
+    "approve",
+    "deny",
+    "always",
+    "cancel",
+    "yes",
+    "no",
+    "ok",
+    "confirm",
+    "remember",
+    "nevermind",
+]);
+function parseSlashCommandName(rawBody) {
+    const stripped = rawBody.trimStart();
+    if (!stripped.startsWith("/"))
+        return null;
+    const token = stripped.split(/\s+/, 1)[0] ?? "";
+    const name = token.slice(1).replace(/_/g, "-").toLowerCase();
+    if (!name || name.includes("/"))
+        return null;
+    return name;
+}
+function isKnownOpenClawGroupSlashCommand(rawBody, cfg) {
+    const name = parseSlashCommandName(rawBody);
+    if (!name)
+        return false;
+    return hasControlCommand(rawBody, cfg)
+        || CLAWCHAT_PLUGIN_SLASH_COMMANDS.has(name)
+        || OPENCLAW_CONFIRM_SLASH_COMMANDS.has(name);
+}
 export function getOpenclawClawlingClient(accountId) {
     return activeClients.get(accountId);
 }
+export function resolveClawChatMemoryRoot(runtime, cfg, agentId) {
+    const resolver = runtime.agent?.resolveAgentWorkspaceDir;
+    if (typeof resolver !== "function") {
+        throw new Error(CLAWCHAT_MEMORY_ROOT_UNAVAILABLE);
+    }
+    let workspaceDir;
+    try {
+        workspaceDir = resolver(cfg, agentId);
+    }
+    catch {
+        throw new Error(CLAWCHAT_MEMORY_ROOT_UNAVAILABLE);
+    }
+    const memoryRoot = typeof workspaceDir === "string" ? workspaceDir.trim() : "";
+    if (!memoryRoot) {
+        throw new Error(CLAWCHAT_MEMORY_ROOT_UNAVAILABLE);
+    }
+    return memoryRoot;
+}
 export async function waitForOpenclawClawlingClient(accountId, options = {}) {
     const timeoutMs = options.timeoutMs ?? 15_000;
     const pollMs = options.pollMs ?? 100;
@@ -64,6 +124,74 @@ export function classifyClawlingClientError(err) {
 function formatConversationSubject(peer) {
     return peer.kind === "group" ? `group:${peer.id}` : peer.id;
 }
+function parseApiTimestamp(value) {
+    if (typeof value !== "string")
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function asRecord(value) {
+    return value && typeof value === "object" ? value : null;
+}
+function optionalString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function hasOwn(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key);
+}
+function optionalNullableString(record, key) {
+    if (!hasOwn(record, key))
+        return undefined;
+    const value = record[key];
+    if (value === null)
+        return null;
+    return optionalString(value);
+}
+function isConversationNotFoundError(err) {
+    if (!(err instanceof ClawlingApiError))
+        return false;
+    return err.meta?.status === 404 || err.meta?.status === 410 ||
+        err.meta?.code === 404 || err.meta?.code === 410 || err.meta?.code === 40401;
+}
+function metadataVersionFromEnvelope(env) {
+    const payload = asRecord(env.payload);
+    const version = payload?.version;
+    return typeof version === "number" && Number.isFinite(version) ? version : undefined;
+}
+function metadataScopesFromEnvelope(env) {
+    const scope = asRecord(env.payload)?.scope;
+    return Array.isArray(scope) ? scope.filter((item) => typeof item === "string") : [];
+}
+function shouldRefreshBehaviorForScopes(scopes) {
+    return scopes.includes("behavior");
+}
+function shouldRefreshConversationForScopes(scopes) {
+    if (scopes.length === 0)
+        return true;
+    return scopes.some((scope) => scope === "title" || scope === "description" || scope !== "behavior");
+}
+function buildConversationDetailsCacheInput(params) {
+    const { accountId, conversation, metadataVersion } = params;
+    const refreshedAt = Date.now();
+    const participants = Array.isArray(conversation.participants) ? conversation.participants : [];
+    return {
+        platform: "openclaw",
+        accountId,
+        conversationId: conversation.id,
+        conversationType: conversation.type,
+        ...(metadataVersion !== undefined ? { metadataVersion } : {}),
+        lastSeenAt: parseApiTimestamp(conversation.updated_at),
+        lastRefreshedAt: refreshedAt,
+        raw: conversation,
+        members: participants.map((participant) => ({
+            userId: participant.user_id,
+            role: participant.role,
+            raw: participant,
+            lastSeenAt: parseApiTimestamp(participant.joined_at),
+        })),
+        membersComplete: true,
+    };
+}
 function withClawChatSessionScope(cfg) {
     return {
         ...cfg,
@@ -73,19 +201,92 @@ function withClawChatSessionScope(cfg) {
         },
     };
 }
+function buildActivationBootstrapText() {
+    return [
+        "ClawChat activation bootstrap: You are now connected to this ClawChat direct conversation.",
+        "Please do both:",
+        "1. Send a brief, friendly greeting to the user in this ClawChat direct conversation.",
+        "2. If you have local profile information for yourself, such as display name, bio, or avatar, update the connected ClawChat account profile using the available ClawChat tools. Use `clawchat_update_account_profile` for display name/bio/avatar URL, and use `clawchat_upload_avatar_image` first if the avatar is only available as a local image path. If you do not have local profile information, skip profile updates and only greet the user.",
+        "Do not ask the user for profile information just for this bootstrap.",
+    ].join("\n");
+}
+function buildActivationBootstrapEnvelope(params) {
+    const text = buildActivationBootstrapText();
+    const now = Date.now();
+    return {
+        version: "2",
+        event: EVENT.MESSAGE_SEND,
+        trace_id: `openclaw-clawchat-bootstrap-${now}`,
+        emitted_at: now,
+        chat_id: params.conversationId,
+        chat_type: "direct",
+        to: { id: params.account.userId, type: "direct" },
+        sender: {
+            id: "clawchat-bootstrap",
+            type: "direct",
+            nick_name: "ClawChat Activation",
+        },
+        payload: {
+            message_id: `openclaw-clawchat-bootstrap-${params.conversationId}-${now}`,
+            message_mode: "normal",
+            message: {
+                body: { fragments: [{ kind: "text", text }] },
+                context: { mentions: [], reply: null },
+                streaming: {
+                    status: "static",
+                    sequence: 0,
+                    mutation_policy: "sealed",
+                    started_at: null,
+                    completed_at: null,
+                },
+            },
+        },
+    };
+}
+function resolveConnectionStore(params, runtime) {
+    if (params.store !== undefined)
+        return params.store;
+    if (params.transport)
+        return null;
+    try {
+        const stateDir = runtime.state?.resolveStateDir?.();
+        return getClawChatStore({
+            ...(stateDir ? { dbPath: clawChatDbPathForStateDir(stateDir) } : {}),
+            log: { error: (message) => params.log?.error?.(message) },
+        });
+    }
+    catch {
+        params.log?.error?.("openclaw-clawchat sqlite connection persistence unavailable; continuing.");
+        return null;
+    }
+}
 export async function startOpenclawClawlingGateway(params) {
     const { cfg, account, abortSignal, setStatus, getStatus, log } = params;
     // Obtain PluginRuntime from the stored runtime set via setOpenclawClawlingRuntime.
     const runtime = getOpenclawClawlingRuntime();
     const accountId = account.accountId;
-    log?.info?.(`[${accountId}] openclaw-clawchat runtime start entered configured=${account.configured} enabled=${account.enabled} hasToken=${Boolean(account.token)} hasUserId=${Boolean(account.userId)} websocketUrl=${account.websocketUrl || "(empty)"}`);
+    const store = resolveConnectionStore(params, runtime);
+    let conversationApiClient;
+    const getConversationApiClient = () => {
+        conversationApiClient ??= createOpenclawClawlingApiClient({
+            baseUrl: account.baseUrl,
+            token: account.token,
+            userId: account.userId,
+        });
+        return conversationApiClient;
+    };
+    log?.info?.(`[${accountId}] openclaw-clawchat runtime start entered configured=${account.configured} enabled=${account.enabled} hasToken=${Boolean(account.token)} hasUserId=${Boolean(account.userId)} hasOwnerUserId=${Boolean(account.ownerUserId)} websocketUrl=${account.websocketUrl || "(empty)"}`);
     let lastHelloFailTraceId = "-";
     let lastHelloFailReason = "";
     let lastConnectTraceId = "-";
+    let lastHelloOkDeviceId;
+    let lastHelloOkDeliveryMode;
     let currentAttemptStartedAt = 0;
     let authFailureLogged = false;
     let closingForAbort = false;
     let wsReady = false;
+    let currentConnectionId = null;
+    let currentConnectionFinished = false;
     const reconnectTracker = createReconnectTracker({
         accountId,
         log: (msg) => log?.info?.(msg),
@@ -99,11 +300,220 @@ export async function startOpenclawClawlingGateway(params) {
             state: snapshot.state === "connected" ? "ready" : snapshot.state,
         };
     };
+    const recordConnection = (action, fn) => {
+        try {
+            return fn();
+        }
+        catch {
+            log?.error?.(`[${accountId}] openclaw-clawchat sqlite ${action} failed; continuing`);
+            return undefined;
+        }
+    };
+    const finishCurrentConnection = (input) => {
+        if (!store || currentConnectionId == null || currentConnectionFinished)
+            return;
+        const connectionId = currentConnectionId;
+        recordConnection("finish", () => store.finishConnection(connectionId, input));
+        currentConnectionFinished = true;
+        currentConnectionId = null;
+    };
+    const refreshConversationDetails = async (conversationId, options) => {
+        try {
+            const memoryRoot = options.memoryRoot;
+            const data = memoryRoot
+                ? await (async () => {
+                    const result = await pullGroupMetadata({
+                        memoryRoot,
+                        groupId: conversationId,
+                        api: getConversationApiClient(),
+                    });
+                    if (result.failures.length > 0) {
+                        log?.error?.(`[${accountId}] openclaw-clawchat group participant metadata refresh partially failed: ${result.failures.map((failure) => `${failure.targetId}: ${failure.error}`).join("; ")}`);
+                    }
+                    if (!result.conversation)
+                        throw new Error("ClawChat conversation metadata response is missing conversation");
+                    return { conversation: result.conversation };
+                })()
+                : await getConversationApiClient().getConversation(conversationId);
+            if (!store?.upsertConversationDetails)
+                return;
+            recordConnection("conversation details upsert", () => store.upsertConversationDetails?.(buildConversationDetailsCacheInput({
+                accountId,
+                conversation: data.conversation,
+                ...(options.metadataVersion !== undefined ? { metadataVersion: options.metadataVersion } : {}),
+            })));
+        }
+        catch (err) {
+            if (isConversationNotFoundError(err)) {
+                if (store?.deleteConversationCache) {
+                    recordConnection("conversation cache delete", () => store.deleteConversationCache?.({
+                        platform: "openclaw",
+                        accountId,
+                        conversationId,
+                    }));
+                }
+                return;
+            }
+            log?.error?.(`[${accountId}] openclaw-clawchat metadata refresh failed source=${options.source} conversation=${conversationId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const refreshAgentBehavior = async (options) => {
+        try {
+            await pullOwnerMetadata({
+                memoryRoot: options.memoryRoot,
+                agentId: account.agentId,
+                accountUserId: account.userId,
+                accountOwnerUserId: account.ownerUserId,
+                api: getConversationApiClient(),
+            });
+        }
+        catch (err) {
+            log?.error?.(`[${accountId}] openclaw-clawchat behavior refresh failed source=${options.source} agent=${account.userId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const refreshConversationCacheAfterReady = async () => {
+        if (!store)
+            return;
+        const ids = [];
+        const seen = new Set();
+        const addId = (id) => {
+            if (typeof id !== "string" || !id || seen.has(id))
+                return;
+            seen.add(id);
+            ids.push(id);
+        };
+        const activation = store.getActivationConversation
+            ? recordConnection("activation conversation read", () => store.getActivationConversation?.({ platform: "openclaw", accountId }))
+            : null;
+        addId(activation?.conversationId);
+        const cachedIds = store.listCachedConversationIds
+            ? recordConnection("cached conversation ids read", () => store.listCachedConversationIds?.({ platform: "openclaw", accountId, limit: 20 })) ?? []
+            : [];
+        for (const id of cachedIds.slice(0, 20))
+            addId(id);
+        for (const id of ids) {
+            await refreshConversationDetails(id, { source: "reconnect" });
+        }
+    };
+    const resolveMemoryRootForPeer = (peer) => {
+        try {
+            const route = runtime.channel.routing.resolveAgentRoute({
+                cfg: withClawChatSessionScope(cfg),
+                channel: CHANNEL_ID,
+                accountId,
+                peer,
+            });
+            return resolveClawChatMemoryRoot(runtime, cfg, route.agentId);
+        }
+        catch (err) {
+            log?.error?.(`[${accountId}] openclaw-clawchat metadata refresh memory root unavailable: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    };
+    const handleMetadataInvalidation = async (env) => {
+        const conversationId = typeof env.chat_id === "string" && env.chat_id.trim()
+            ? env.chat_id
+            : "";
+        if (!conversationId) {
+            log?.info?.(`[${accountId}] openclaw-clawchat metadata invalidation missing chat_id trace=${env.trace_id}`);
+            return;
+        }
+        const version = metadataVersionFromEnvelope(env);
+        const scopes = metadataScopesFromEnvelope(env);
+        const refreshBehavior = shouldRefreshBehaviorForScopes(scopes);
+        const refreshConversation = shouldRefreshConversationForScopes(scopes);
+        if (!refreshBehavior && !refreshConversation)
+            return;
+        const peer = {
+            kind: env.chat_type === "group" ? "group" : "direct",
+            id: conversationId,
+        };
+        const memoryRoot = resolveMemoryRootForPeer(peer);
+        if (!memoryRoot)
+            return;
+        if (refreshBehavior) {
+            await refreshAgentBehavior({
+                source: "metadata_invalidation",
+                ...(version !== undefined ? { metadataVersion: version } : {}),
+                memoryRoot,
+            });
+        }
+        if (!refreshConversation)
+            return;
+        await refreshConversationDetails(conversationId, {
+            source: "metadata_invalidation",
+            ...(version !== undefined ? { metadataVersion: version } : {}),
+            memoryRoot,
+        });
+    };
+    const syncMessagePathProfiles = async (turn, memoryRoot) => {
+        if (turn.senderId === "clawchat-bootstrap") {
+            await pullOwnerMetadata({
+                memoryRoot,
+                agentId: account.agentId,
+                accountUserId: account.userId,
+                accountOwnerUserId: account.ownerUserId,
+                api: getConversationApiClient(),
+            });
+            return;
+        }
+        if (turn.peer.kind === "direct" && (turn.senderId === account.ownerUserId || turn.senderId === account.userId)) {
+            await pullOwnerMetadata({
+                memoryRoot,
+                agentId: account.agentId,
+                accountUserId: account.userId,
+                accountOwnerUserId: account.ownerUserId,
+                api: getConversationApiClient(),
+            });
+            return;
+        }
+        if (turn.peer.kind === "group") {
+            await refreshGroupProfile({
+                platform: "openclaw",
+                accountId,
+                conversationId: turn.peer.id,
+                api: getConversationApiClient(),
+                store: {
+                    ...(store?.upsertConversationDetails ? { upsertConversationDetails: store.upsertConversationDetails.bind(store) } : {}),
+                },
+                memoryRoot,
+                log: { error: (message) => log?.error?.(`[${accountId}] ${message}`) },
+            });
+            return;
+        }
+        await syncFirstSeenClawChatProfiles({
+            platform: "openclaw",
+            accountId,
+            accountUserId: account.userId,
+            accountOwnerUserId: account.ownerUserId,
+            chat: {
+                id: turn.peer.id,
+                type: "direct",
+                lastSeenAt: turn.timestamp,
+            },
+            sender: {
+                id: turn.senderId,
+                ...(turn.senderNickName ? { nickname: turn.senderNickName } : {}),
+            },
+            api: getConversationApiClient(),
+            store: {
+                ...(store?.getCachedConversation ? { getCachedConversation: store.getCachedConversation.bind(store) } : {}),
+                ...(store?.upsertConversationSummary ? { upsertConversationSummary: store.upsertConversationSummary.bind(store) } : {}),
+                ...(store?.upsertConversationDetails ? { upsertConversationDetails: store.upsertConversationDetails.bind(store) } : {}),
+            },
+            memoryRoot,
+            log: { error: (message) => log?.error?.(`[${accountId}] ${message}`) },
+        });
+    };
     const client = createOpenclawClawlingClient(account, {
         ...(params.transport ? { transport: params.transport } : {}),
         wsLifecycle: {
             onConnectFrameSent: (env) => {
                 lastConnectTraceId = typeof env.trace_id === "string" ? env.trace_id : "-";
+                if (store && currentConnectionId != null) {
+                    const connectionId = currentConnectionId;
+                    recordConnection("connect-sent", () => store.markConnectSent(connectionId));
+                }
                 const deviceId = typeof env.payload?.device_id === "string" ? env.payload.device_id : "-";
                 const current = wsLogContext();
                 log?.info?.(formatWsLog({
@@ -123,6 +533,13 @@ export async function startOpenclawClawlingGateway(params) {
     });
     log?.info?.(`[${accountId}] openclaw-clawchat runtime client created`);
     setAlignedOutboundLogContext(client, wsLogContext);
+    client.on("hello:ok", (env) => {
+        const payload = env.payload && typeof env.payload === "object"
+            ? env.payload
+            : {};
+        lastHelloOkDeviceId = typeof payload.device_id === "string" ? payload.device_id : undefined;
+        lastHelloOkDeliveryMode = typeof payload.delivery_mode === "string" ? payload.delivery_mode : undefined;
+    });
     const protocolControlLogger = createProtocolControlHandler({
         accountId,
         log: (msg) => log?.info?.(msg),
@@ -147,6 +564,7 @@ export async function startOpenclawClawlingGateway(params) {
             ],
         }));
     };
+    let dispatchActivationBootstrap = async () => { };
     client.on("state", ({ from, to }) => {
         log?.info?.(`[${accountId}] openclaw-clawchat state ${from} -> ${to}`);
         wsReady = to === "connected";
@@ -154,6 +572,18 @@ export async function startOpenclawClawlingGateway(params) {
             reconnectTracker.connectStart();
             currentAttemptStartedAt = Date.now();
             const current = wsLogContext();
+            if (store) {
+                recordConnection("start", () => {
+                    currentConnectionId = store.startConnection({
+                        platform: "openclaw",
+                        accountId,
+                        attempt: current.attempt,
+                        reconnectCount: current.reconnectCount,
+                        connectStartedAt: currentAttemptStartedAt,
+                    });
+                    currentConnectionFinished = false;
+                });
+            }
             log?.info?.(formatWsLog({
                 event: "connect_start",
                 accountId,
@@ -172,6 +602,19 @@ export async function startOpenclawClawlingGateway(params) {
             const queueSize = getAlignedOutboundQueueSize(client);
             reconnectTracker.markReady();
             const current = wsLogContext();
+            if (store && currentConnectionId != null) {
+                const connectionId = currentConnectionId;
+                recordConnection("ready", () => {
+                    if (lastHelloOkDeviceId === undefined && lastHelloOkDeliveryMode === undefined) {
+                        store.markConnectionReady(connectionId);
+                        return;
+                    }
+                    store.markConnectionReady(connectionId, {
+                        ...(lastHelloOkDeviceId !== undefined ? { resolvedDeviceId: lastHelloOkDeviceId } : {}),
+                        ...(lastHelloOkDeliveryMode !== undefined ? { deliveryMode: lastHelloOkDeliveryMode } : {}),
+                    });
+                });
+            }
             log?.info?.(formatWsLog({
                 event: "handshake_ok",
                 accountId,
@@ -191,6 +634,8 @@ export async function startOpenclawClawlingGateway(params) {
             catch {
                 // The queue keeps the failed frame at the head and will retry after the next reconnect.
             }
+            void refreshConversationCacheAfterReady();
+            void dispatchActivationBootstrap();
         }
         else if (to === "disconnected") {
             reconnectTracker.markClosed();
@@ -201,6 +646,11 @@ export async function startOpenclawClawlingGateway(params) {
     client.on("close", ({ code, reason }) => {
         if (closingForAbort || (code === 1000 && reason === "client close"))
             return;
+        finishCurrentConnection({
+            state: "disconnected",
+            closeCode: code ?? null,
+            closeReason: reason ?? null,
+        });
         const current = wsLogContext();
         log?.info?.(formatWsLog({
             event: "connection_lost",
@@ -315,9 +765,16 @@ export async function startOpenclawClawlingGateway(params) {
         const payload = env.payload;
         lastHelloFailReason = typeof payload?.reason === "string" ? payload.reason : "";
     });
+    client.on("metadata:invalidated", (env) => {
+        void handleMetadataInvalidation(env);
+    });
     client.on("error", (err) => {
         const classified = classifyClawlingClientError(err);
         if (classified.kind === "auth") {
+            finishCurrentConnection({
+                state: "auth_failed",
+                error: lastHelloFailReason || classified.message,
+            });
             logAuthFailure(classified.message);
             setStatus({
                 ...getStatus(),
@@ -328,6 +785,7 @@ export async function startOpenclawClawlingGateway(params) {
             });
         }
         else if (classified.kind === "transport") {
+            finishCurrentConnection({ state: "transport_error", error: classified.message });
             const current = wsLogContext();
             log?.info?.(formatWsLog({
                 event: "connection_lost",
@@ -354,10 +812,305 @@ export async function startOpenclawClawlingGateway(params) {
             log?.info?.(`[${accountId}] openclaw-clawchat state error: ${classified.message}`);
         }
         else {
-            log?.error?.(`[${accountId}] openclaw-clawchat sdk error: ${classified.message}`);
+            log?.error?.(`[${accountId}] openclaw-clawchat client error: ${classified.message}`);
+        }
+    });
+    const buildPromptForTurn = async (turn, memoryRoot) => {
+        const senderRelation = resolveSenderRelation({
+            senderId: turn.senderId,
+            accountUserId: account.userId,
+            accountOwnerUserId: account.ownerUserId,
+            senderProfileType: turn.senderProfileType,
+        });
+        const promptChatType = turn.peer.kind === "group" ? "group" : "dm";
+        const promptMetadata = await loadClawChatPromptMetadata({
+            memoryRoot,
+            turn: {
+                chatType: promptChatType,
+                senderId: turn.senderId,
+                senderIsOwner: senderRelation === "owner",
+                groupId: turn.peer.kind === "group" ? turn.peer.id : null,
+            },
+            log: { error: (message) => log?.error?.(`[${accountId}] ${message}`) },
+        });
+        const metadataSenderProfileType = promptMetadata.userMetadata?.profile_type ?? null;
+        const promptSenderProfileType = metadataSenderProfileType ?? turn.senderProfileType ?? (senderRelation === "self_agent" || senderRelation === "peer_agent" ? "agent" : "user");
+        return renderClawChatProfilePrompt({
+            basePrompt: turn.peer.kind === "group" ? getClawChatGroupPrompt() : getClawChatUserPrompt(),
+            ...promptMetadata,
+            turn: {
+                chatType: promptChatType,
+                senderId: turn.senderId,
+                senderName: promptMetadata.userMetadata?.nickname ?? (turn.senderNickName || turn.senderId),
+                senderProfileType: promptSenderProfileType,
+                senderIsOwner: senderRelation === "owner",
+                groupId: turn.peer.kind === "group" ? turn.peer.id : null,
+                coalescedGroupBatch: turn.coalescedGroupBatch === true,
+                wasMentioned: turn.wasMentioned,
+                mentionedUserIds: turn.mentionedUserIds,
+            },
+        });
+    };
+    const resolveSenderNickNameForTurn = (turn) => {
+        if (turn.senderNickName && turn.senderNickName !== turn.senderId)
+            return turn.senderNickName;
+        return turn.senderNickName || turn.senderId;
+    };
+    const resolveSenderBatchIdentityForTurn = (turn) => {
+        const senderRelation = resolveSenderRelation({
+            senderId: turn.senderId,
+            accountUserId: account.userId,
+            accountOwnerUserId: account.ownerUserId,
+            senderProfileType: turn.senderProfileType,
+        });
+        return {
+            senderRelation,
+            senderProfileType: turn.senderProfileType ??
+                (senderRelation === "self_agent" || senderRelation === "peer_agent" ? "agent" : "user"),
+            senderIsOwner: senderRelation === "owner",
+        };
+    };
+    const claimInboundTurn = (turn) => {
+        const env = turn.envelope;
+        if (store?.claimMessageOnce) {
+            const claimed = recordConnection("message claim", () => store.claimMessageOnce?.({
+                platform: "openclaw",
+                accountId,
+                kind: "message",
+                direction: "inbound",
+                eventType: String(env.event),
+                traceId: turn.traceId,
+                chatId: turn.peer.id,
+                messageId: turn.messageId,
+                text: turn.rawBody,
+                raw: env,
+            }));
+            if (claimed === false) {
+                log?.info?.(`[${accountId}] openclaw-clawchat skip duplicate stored msg=${turn.messageId}`);
+                return "skipped";
+            }
+        }
+        return "claimed";
+    };
+    const dispatchTurnToAgent = async (turn) => {
+        const rt = runtime.channel;
+        const storePath = rt.session.resolveStorePath(cfg.session?.store);
+        const routeCfg = withClawChatSessionScope(cfg);
+        const route = rt.routing.resolveAgentRoute({
+            cfg: routeCfg,
+            channel: CHANNEL_ID,
+            accountId,
+            peer: turn.peer,
+        });
+        const memoryRoot = resolveClawChatMemoryRoot(runtime, cfg, route.agentId);
+        const body = rt.reply.formatAgentEnvelope({
+            channel: "Clawling Chat",
+            from: formatConversationSubject(turn.peer),
+            body: turn.rawBody,
+            timestamp: turn.timestamp,
+            ...rt.reply.resolveEnvelopeFormatOptions(cfg),
+        });
+        try {
+            await syncMessagePathProfiles(turn, memoryRoot);
+        }
+        catch (err) {
+            log?.error?.(`[${accountId}] openclaw-clawchat message metadata refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const conversationTarget = `${CHANNEL_ID}:${formatConversationSubject(turn.peer)}`;
+        const turnPrompt = await buildPromptForTurn(turn, memoryRoot);
+        const ctxPayload = rt.turn.buildContext({
+            channel: CHANNEL_ID,
+            accountId: route.accountId ?? accountId,
+            provider: CHANNEL_ID,
+            surface: CHANNEL_ID,
+            messageId: turn.messageId,
+            messageIdFull: turn.messageId,
+            timestamp: turn.timestamp,
+            from: conversationTarget,
+            sender: {
+                id: turn.senderId,
+                name: turn.senderNickName || turn.senderId,
+                displayLabel: turn.senderNickName || turn.senderId,
+            },
+            conversation: {
+                kind: turn.peer.kind,
+                id: turn.peer.id,
+                label: formatConversationSubject(turn.peer),
+                routePeer: turn.peer,
+            },
+            route: {
+                agentId: route.agentId,
+                accountId: route.accountId ?? accountId,
+                routeSessionKey: route.sessionKey,
+            },
+            reply: {
+                to: `${CHANNEL_ID}:${account.userId}`,
+                originatingTo: conversationTarget,
+            },
+            message: {
+                body,
+                rawBody: turn.rawBody,
+                bodyForAgent: turn.rawBody,
+                commandBody: turn.rawBody,
+                envelopeFrom: conversationTarget,
+            },
+            access: {
+                mentions: {
+                    canDetectMention: true,
+                    wasMentioned: turn.wasMentioned,
+                    hasAnyMention: turn.mentionedUserIds.length > 0,
+                },
+            },
+            ...(memoryRoot ? { extra: { memoryRoot } } : {}),
+            ...(turn.peer.kind === "group"
+                ? { supplemental: { groupSystemPrompt: turnPrompt } }
+                : {}),
+        });
+        if (memoryRoot) {
+            ctxPayload.memoryRoot = memoryRoot;
+        }
+        if (turn.mentionedUserIds.length > 0) {
+            ctxPayload.MentionedUserIds = turn.mentionedUserIds;
+        }
+        // Fetch any inbound media attachments and populate MediaPath/MediaPaths in context.
+        const inboundPaths = turn.mediaItems.length > 0
+            ? await fetchInboundMedia(turn.mediaItems, {
+                runtime,
+                log,
+                maxBytes: 20 * 1024 * 1024,
+            })
+            : [];
+        if (inboundPaths.length > 0) {
+            ctxPayload.MediaPath = inboundPaths[0];
+            ctxPayload.MediaPaths = inboundPaths;
+        }
+        const resolvedSessionKey = ctxPayload.SessionKey ?? route.sessionKey;
+        clearClawChatPromptInjectionForSession(resolvedSessionKey);
+        const stagedDirectPrompt = turn.peer.kind !== "group";
+        if (stagedDirectPrompt) {
+            stageClawChatPromptInjection({
+                sessionKey: resolvedSessionKey,
+                prompt: turnPrompt,
+            });
+        }
+        try {
+            try {
+                await rt.session.recordInboundSession({
+                    storePath,
+                    sessionKey: resolvedSessionKey,
+                    ctx: ctxPayload,
+                    onRecordError: (err) => {
+                        log?.error?.(`[${accountId}] openclaw-clawchat failed to record inbound session: ${String(err)}`);
+                    },
+                });
+            }
+            catch (err) {
+                log?.error?.(`[${accountId}] openclaw-clawchat failed to record inbound session: ${String(err)}`);
+            }
+            const replyCtx = turn.replyCtx;
+            const { dispatcher, replyOptions, markDispatchIdle } = createOpenclawClawlingReplyDispatcher({
+                cfg,
+                runtime,
+                account,
+                client,
+                target: { chatId: turn.peer.id, chatType: turn.peer.kind },
+                ...(replyCtx ? { replyCtx } : {}),
+                inboundMessageId: turn.messageId,
+                inboundForFinalReply: {
+                    chatId: turn.peer.id,
+                    senderId: turn.senderId,
+                    senderNickName: turn.senderNickName || turn.senderId,
+                    bodyText: turn.rawBody,
+                },
+                store: store
+                    ? {
+                        insertMessage: (input) => store.insertMessage?.(input) ?? null,
+                        claimMessageOnce: (input) => store.claimMessageOnce?.(input) ?? null,
+                        updateMessageByIdentity: (input) => store.updateMessageByIdentity?.(input),
+                    }
+                    : null,
+                log,
+            });
+            const agentsConfigured = Object.keys(cfg.agents ?? {});
+            log?.info?.(`[${accountId}] openclaw-clawchat dispatching reply msg=${turn.messageId} session=${resolvedSessionKey} agent=${route.agentId} agentsConfigured=[${agentsConfigured.join(",")}]`);
+            try {
+                const dispatchResult = await rt.reply.withReplyDispatcher({
+                    dispatcher,
+                    onSettled: () => markDispatchIdle(),
+                    run: () => rt.reply.dispatchReplyFromConfig({ ctx: ctxPayload, cfg, dispatcher, replyOptions }),
+                });
+                const counts = dispatchResult?.counts ?? {};
+                const queuedFinal = Boolean(dispatchResult?.queuedFinal);
+                log?.info?.(`[${accountId}] openclaw-clawchat dispatch complete msg=${turn.messageId} queuedFinal=${queuedFinal} counts=${JSON.stringify(counts)}`);
+                if (!queuedFinal && Object.values(counts).every((n) => !n)) {
+                    log?.info?.(`[${accountId}] openclaw-clawchat NO reply was produced (no final / block / tool dispatched). ` +
+                        `Likely causes: agent='${route.agentId}' not configured in cfg.agents (configured: [${agentsConfigured.join(",")}]); ` +
+                        `or send-policy denied; or a plugin claimed the binding.`);
+                }
+                return "submitted";
+            }
+            catch (err) {
+                log?.error?.(`[${accountId}] openclaw-clawchat dispatch failed msg=${turn.messageId}: ${String(err)}`);
+                return "failed";
+            }
         }
+        finally {
+            if (stagedDirectPrompt) {
+                clearClawChatPromptInjectionForSession(resolvedSessionKey);
+            }
+        }
+    };
+    const groupCoalescer = createGroupMessageCoalescer({
+        idleMs: 10_000,
+        maxWaitMs: 30_000,
+        dispatch: async (turn) => {
+            await dispatchTurnToAgent(turn);
+        },
+        onError: (err) => {
+            log?.error?.(`[${accountId}] openclaw-clawchat coalesced group dispatch failed: ${String(err)}`);
+        },
+        onDrop: (chatId, count) => {
+            log?.info?.(`[${accountId}] openclaw-clawchat dropped pending group batch chat_id=${chatId} count=${count} reason=shutdown`);
+        },
     });
-    client.on("message", async (env) => {
+    const ingestTurn = async (rawTurn) => {
+        const senderBatchIdentity = rawTurn.peer.kind === "group"
+            ? resolveSenderBatchIdentityForTurn(rawTurn)
+            : {};
+        const turn = {
+            ...rawTurn,
+            senderNickName: resolveSenderNickNameForTurn(rawTurn),
+            ...senderBatchIdentity,
+        };
+        const claimed = claimInboundTurn(turn);
+        if (claimed === "skipped")
+            return "skipped";
+        if (turn.peer.kind === "group") {
+            if (isKnownOpenClawGroupSlashCommand(turn.rawBody, cfg)) {
+                const commandMode = effectiveGroupCommandMode(account, turn.peer.id);
+                const commandAllowed = commandMode === "all"
+                    || (commandMode === "owner" && turn.senderIsOwner === true);
+                if (!commandAllowed) {
+                    log?.info?.(`[${accountId}] openclaw-clawchat group command dropped chat_id=${turn.peer.id} msg=${turn.messageId} mode=${commandMode} owner=${turn.senderIsOwner === true}`);
+                    return "skipped";
+                }
+                log?.info?.(`[${accountId}] openclaw-clawchat dispatching group command chat_id=${turn.peer.id} msg=${turn.messageId} mode=${commandMode}`);
+                return dispatchTurnToAgent(turn);
+            }
+            if (turn.wasMentioned) {
+                groupCoalescer.enqueue(turn);
+                groupCoalescer.flushNow(turn.peer.id);
+                log?.info?.(`[${accountId}] openclaw-clawchat dispatching mentioned group batch chat_id=${turn.peer.id} msg=${turn.messageId}`);
+                return "submitted";
+            }
+            groupCoalescer.enqueue(turn);
+            log?.info?.(`[${accountId}] openclaw-clawchat queued group batch chat_id=${turn.peer.id} msg=${turn.messageId}`);
+            return "submitted";
+        }
+        return dispatchTurnToAgent(turn);
+    };
+    const handleInboundEnvelope = async (env) => {
+        let ingestResult;
         try {
             await dispatchOpenclawClawlingInbound({
                 envelope: env,
@@ -366,119 +1119,60 @@ export async function startOpenclawClawlingGateway(params) {
                 account,
                 log,
                 ingest: async (turn) => {
-                    const rt = runtime.channel;
-                    const storePath = rt.session.resolveStorePath(cfg.session?.store);
-                    const routeCfg = withClawChatSessionScope(cfg);
-                    const route = rt.routing.resolveAgentRoute({
-                        cfg: routeCfg,
-                        channel: CHANNEL_ID,
-                        accountId,
-                        peer: turn.peer,
-                    });
-                    const body = rt.reply.formatAgentEnvelope({
-                        channel: "Clawling Chat",
-                        from: formatConversationSubject(turn.peer),
-                        body: turn.rawBody,
-                        timestamp: turn.timestamp,
-                        ...rt.reply.resolveEnvelopeFormatOptions(cfg),
-                    });
-                    const conversationTarget = `${CHANNEL_ID}:${formatConversationSubject(turn.peer)}`;
-                    const ctxPayload = rt.reply.finalizeInboundContext({
-                        Body: body,
-                        BodyForAgent: turn.rawBody,
-                        RawBody: turn.rawBody,
-                        CommandBody: turn.rawBody,
-                        // Clawling v2 routes by chat_id. `OriginatingTo` is what the
-                        // message tool uses as the implicit current-chat target, so keep it
-                        // on the conversation id rather than the agent account user id.
-                        From: conversationTarget,
-                        To: `${CHANNEL_ID}:${account.userId}`,
-                        SessionKey: route.sessionKey,
-                        AccountId: route.accountId ?? accountId,
-                        ChatType: turn.peer.kind,
-                        ConversationLabel: formatConversationSubject(turn.peer),
-                        SenderId: turn.senderId,
-                        Provider: CHANNEL_ID,
-                        Surface: CHANNEL_ID,
-                        MessageSid: turn.messageId,
-                        MessageSidFull: turn.messageId,
-                        Timestamp: turn.timestamp,
-                        OriginatingChannel: CHANNEL_ID,
-                        OriginatingTo: conversationTarget,
-                    });
-                    // Fetch any inbound media attachments and populate MediaPath/MediaPaths in context.
-                    const inboundPaths = turn.mediaItems.length > 0
-                        ? await fetchInboundMedia(turn.mediaItems, {
-                            runtime,
-                            log,
-                            maxBytes: 20 * 1024 * 1024,
-                        })
-                        : [];
-                    if (inboundPaths.length > 0) {
-                        ctxPayload.MediaPath = inboundPaths[0];
-                        ctxPayload.MediaPaths = inboundPaths;
-                    }
-                    try {
-                        await rt.session.recordInboundSession({
-                            storePath,
-                            sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
-                            ctx: ctxPayload,
-                            onRecordError: (err) => {
-                                log?.error?.(`[${accountId}] openclaw-clawchat failed to record inbound session: ${String(err)}`);
-                            },
-                        });
-                    }
-                    catch (err) {
-                        log?.error?.(`[${accountId}] openclaw-clawchat failed to record inbound session: ${String(err)}`);
-                    }
-                    const replyCtx = turn.replyCtx;
-                    const { dispatcher, replyOptions, markDispatchIdle } = createOpenclawClawlingReplyDispatcher({
-                        cfg,
-                        runtime,
-                        account,
-                        client,
-                        target: { chatId: turn.peer.id, chatType: turn.peer.kind },
-                        ...(replyCtx ? { replyCtx } : {}),
-                        inboundMessageId: turn.messageId,
-                        inboundForFinalReply: {
-                            chatId: turn.peer.id,
-                            senderId: turn.senderId,
-                            senderNickName: turn.senderNickName || turn.senderId,
-                            bodyText: turn.rawBody,
-                        },
-                        log,
-                    });
-                    const agentsConfigured = Object.keys(cfg.agents ?? {});
-                    log?.info?.(`[${accountId}] openclaw-clawchat dispatching reply msg=${turn.messageId} session=${ctxPayload.SessionKey ?? route.sessionKey} agent=${route.agentId} agentsConfigured=[${agentsConfigured.join(",")}]`);
-                    try {
-                        const dispatchResult = await rt.reply.withReplyDispatcher({
-                            dispatcher,
-                            onSettled: () => markDispatchIdle(),
-                            run: () => rt.reply.dispatchReplyFromConfig({ ctx: ctxPayload, cfg, dispatcher, replyOptions }),
-                        });
-                        const counts = dispatchResult?.counts ?? {};
-                        const queuedFinal = Boolean(dispatchResult?.queuedFinal);
-                        log?.info?.(`[${accountId}] openclaw-clawchat dispatch complete msg=${turn.messageId} queuedFinal=${queuedFinal} counts=${JSON.stringify(counts)}`);
-                        if (!queuedFinal && Object.values(counts).every((n) => !n)) {
-                            log?.info?.(`[${accountId}] openclaw-clawchat NO reply was produced (no final / block / tool dispatched). ` +
-                                `Likely causes: agent='${route.agentId}' not configured in cfg.agents (configured: [${agentsConfigured.join(",")}]); ` +
-                                `or send-policy denied; or a plugin claimed the binding.`);
-                        }
-                    }
-                    catch (err) {
-                        log?.error?.(`[${accountId}] openclaw-clawchat dispatch failed msg=${turn.messageId}: ${String(err)}`);
-                    }
+                    ingestResult = await ingestTurn(turn);
                 },
             });
         }
         catch (err) {
             log?.error?.(`[${accountId}] openclaw-clawchat message handler error: ${err instanceof Error ? err.stack || err.message : String(err)}`);
+            return "failed";
         }
+        return ingestResult;
+    };
+    dispatchActivationBootstrap = async () => {
+        if (!store?.claimPendingActivationBootstrap || !store.markActivationBootstrapSent)
+            return;
+        let bootstrap;
+        const releaseBootstrap = () => {
+            if (!bootstrap || !store.releaseActivationBootstrapClaim)
+                return;
+            const claimedBootstrap = bootstrap;
+            recordConnection("activation bootstrap release", () => store.releaseActivationBootstrapClaim?.({
+                platform: "openclaw",
+                accountId,
+                conversationId: claimedBootstrap.conversationId,
+            }));
+        };
+        try {
+            bootstrap = recordConnection("activation bootstrap claim", () => store.claimPendingActivationBootstrap?.({ platform: "openclaw", accountId }));
+            if (!bootstrap)
+                return;
+            const claimedBootstrap = bootstrap;
+            const result = await handleInboundEnvelope(buildActivationBootstrapEnvelope({ account, conversationId: claimedBootstrap.conversationId }));
+            if (result !== "submitted") {
+                releaseBootstrap();
+                return;
+            }
+            recordConnection("activation bootstrap sent", () => store.markActivationBootstrapSent?.({
+                platform: "openclaw",
+                accountId,
+                conversationId: claimedBootstrap.conversationId,
+            }));
+        }
+        catch (err) {
+            releaseBootstrap();
+            log?.error?.(`[${accountId}] openclaw-clawchat activation bootstrap failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    client.on("message", (env) => {
+        void (async () => {
+            await handleInboundEnvelope(env);
+        })();
     });
     // `client.connect()` resolves on `hello-ok` or rejects on `hello-fail`
     // (auth). Transport failures (server unreachable, DNS error, etc.) do
-    // NOT reject this promise — the SDK catches them internally and drives
-    // its own exponential-backoff reconnect loop (`initialDelay * 2^attempt`
+    // NOT reject this promise — the local client handles them internally and
+    // drives its own exponential-backoff reconnect loop (`initialDelay * 2^attempt`
     // capped at `maxDelay`, with jitter). So we never throw here on anything
     // other than auth failure; on auth we tear the account down cleanly and
     // return without throwing (which would make the gateway supervisor
@@ -498,6 +1192,10 @@ export async function startOpenclawClawlingGateway(params) {
             lastError: classified.message,
         });
         if (classified.kind === "auth") {
+            finishCurrentConnection({
+                state: "auth_failed",
+                error: lastHelloFailReason || classified.message,
+            });
             logAuthFailure(classified.message);
             return;
         }
@@ -517,6 +1215,12 @@ export async function startOpenclawClawlingGateway(params) {
         log?.info?.(`[${accountId}] openclaw-clawchat runtime abort received; closing client`);
         activeClients.delete(accountId);
         closingForAbort = true;
+        groupCoalescer.cancelAll();
+        finishCurrentConnection({
+            state: "disconnected",
+            closeCode: 1000,
+            closeReason: "client close",
+        });
         client.close();
         setStatus({
             ...getStatus(),