@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/dist/src/runtime.js

@@ -0,0 +1,1254 @@
+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 { 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";
+import { runWithTerminalClawChatSendScope } from "./terminal-send.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 { deleteClawChatMemoryFile, readClawChatMemoryFile } from "./clawchat-memory.js";
+import { clearClawChatPromptInjectionForSession, stageClawChatPromptInjection, } from "./prompt-injection.js";
+import { createGroupMessageCoalescer } from "./group-message-coalescer.js";
+import { openclawLlmContextDebug } from "./llm-context-debug.js";
+const { setRuntime: setOpenclawClawlingRuntime, getRuntime: getOpenclawClawlingRuntime } = createPluginRuntimeStore("clawchat-plugin-openclaw 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 resolveChannelContextBuilder(rt) {
+    const channel = rt;
+    const buildContext = channel.inbound?.buildContext ?? channel.turn?.buildContext;
+    if (!buildContext) {
+        throw new Error("OpenClaw channel runtime missing inbound/turn buildContext");
+    }
+    return buildContext;
+}
+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;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const client = activeClients.get(accountId);
+        if (client && client.state === "connected") {
+            return client;
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`clawchat-plugin-openclaw client did not activate within ${timeoutMs}ms for account ${accountId}`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+}
+export function mapClawlingStateToStatus(state) {
+    const now = Date.now();
+    switch (state) {
+        case "connected":
+            return { connected: true, running: true, lastStartAt: now };
+        case "reconnecting":
+            return { connected: false, running: true };
+        case "disconnected":
+            return { connected: false, running: false, lastStopAt: now };
+        default:
+            return { connected: false, running: true };
+    }
+}
+export function classifyClawlingClientError(err) {
+    if (err instanceof AuthError)
+        return { kind: "auth", retry: false, message: err.message };
+    if (err instanceof TransportError)
+        return { kind: "transport", retry: true, message: err.message };
+    if (err instanceof AckTimeoutError)
+        return { kind: "ack-timeout", retry: false, message: err.message };
+    if (err instanceof ProtocolError)
+        return { kind: "protocol", retry: false, message: err.message };
+    if (err instanceof StateError)
+        return { kind: "state", retry: false, message: err.message };
+    return {
+        kind: "unknown",
+        retry: false,
+        message: err instanceof Error ? err.message : String(err),
+    };
+}
+function formatConversationSubject(peer) {
+    return peer.kind === "group" ? `group:${peer.id}` : peer.id;
+}
+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 ||
+        err.message.toLowerCase().includes("conversation not found");
+}
+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 withClawChatSessionScope(cfg) {
+    return {
+        ...cfg,
+        session: {
+            ...(cfg.session ?? {}),
+            dmScope: "per-account-channel-peer",
+        },
+    };
+}
+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: `clawchat-plugin-openclaw-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: `clawchat-plugin-openclaw-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?.("clawchat-plugin-openclaw 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;
+    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}] clawchat-plugin-openclaw 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),
+        maxDelayMs: account.reconnect.maxDelay,
+    });
+    const wsLogContext = () => {
+        const snapshot = reconnectTracker.snapshot();
+        return {
+            attempt: snapshot.attempt || 1,
+            reconnectCount: snapshot.reconnectCount,
+            state: snapshot.state === "connected" ? "ready" : snapshot.state,
+        };
+    };
+    const recordConnection = (action, fn) => {
+        try {
+            return fn();
+        }
+        catch {
+            log?.error?.(`[${accountId}] clawchat-plugin-openclaw 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;
+            if (!memoryRoot) {
+                await getConversationApiClient().getConversation(conversationId);
+                return;
+            }
+            const result = await pullGroupMetadata({
+                memoryRoot,
+                groupId: conversationId,
+                api: getConversationApiClient(),
+                skipUserIds: [account.userId, account.ownerUserId],
+            });
+            if (result.failures.length > 0) {
+                log?.error?.(`[${accountId}] clawchat-plugin-openclaw 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");
+        }
+        catch (err) {
+            if (isConversationNotFoundError(err)) {
+                if (options.memoryRoot) {
+                    await deleteClawChatMemoryFile(options.memoryRoot, {
+                        targetType: "group",
+                        targetId: conversationId,
+                    }).catch((deleteError) => {
+                        log?.error?.(`[${accountId}] clawchat-plugin-openclaw group metadata file delete failed conversation=${conversationId}: ${deleteError instanceof Error ? deleteError.message : String(deleteError)}`);
+                    });
+                }
+                return;
+            }
+            log?.error?.(`[${accountId}] clawchat-plugin-openclaw 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}] clawchat-plugin-openclaw behavior refresh failed source=${options.source} agent=${account.userId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const refreshConversationCacheAfterReady = async () => {
+        void store;
+    };
+    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}] clawchat-plugin-openclaw 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}] clawchat-plugin-openclaw 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,
+                accountUserId: account.userId,
+                accountOwnerUserId: account.ownerUserId,
+                conversationId: turn.peer.id,
+                api: getConversationApiClient(),
+                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: {},
+            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({
+                    event: "connect_sent",
+                    accountId,
+                    attempt: current.attempt,
+                    reconnectCount: current.reconnectCount,
+                    state: "handshaking",
+                    action: "await_hello",
+                    fields: [
+                        ["trace_id", lastConnectTraceId],
+                        ["device_id", deviceId],
+                    ],
+                }));
+            },
+        },
+    });
+    log?.info?.(`[${accountId}] clawchat-plugin-openclaw 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),
+        send: () => { },
+        context: wsLogContext,
+    });
+    const logAuthFailure = (reason) => {
+        if (authFailureLogged)
+            return;
+        authFailureLogged = true;
+        const current = wsLogContext();
+        log?.error?.(formatWsLog({
+            event: "auth_failed",
+            accountId,
+            attempt: current.attempt,
+            reconnectCount: current.reconnectCount,
+            state: "auth_failed",
+            action: "stop_reconnect",
+            fields: [
+                ["trace_id", lastHelloFailTraceId],
+                ["reason", reason || lastHelloFailReason],
+            ],
+        }));
+    };
+    let dispatchActivationBootstrap = async () => { };
+    client.on("state", ({ from, to }) => {
+        log?.info?.(`[${accountId}] clawchat-plugin-openclaw state ${from} -> ${to}`);
+        wsReady = to === "connected";
+        if (to === "connecting") {
+            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,
+                attempt: current.attempt,
+                reconnectCount: current.reconnectCount,
+                state: "connecting",
+                action: "connect",
+                fields: [
+                    ["url", account.websocketUrl],
+                    ["queue_size", getAlignedOutboundQueueSize(client)],
+                ],
+            }));
+        }
+        else if (to === "connected") {
+            const elapsedMs = Math.max(0, Date.now() - currentAttemptStartedAt);
+            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,
+                attempt: current.attempt,
+                reconnectCount: current.reconnectCount,
+                state: "ready",
+                action: "flush_queue",
+                fields: [
+                    ["trace_id", lastConnectTraceId],
+                    ["elapsed_ms", elapsedMs],
+                    ["queue_size", queueSize],
+                ],
+            }));
+            try {
+                flushAlignedOutboundQueue(client);
+            }
+            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();
+        }
+        const next = { ...getStatus(), ...mapClawlingStateToStatus(to) };
+        setStatus(next);
+    });
+    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",
+            accountId,
+            attempt: current.attempt,
+            reconnectCount: current.reconnectCount,
+            state: current.state,
+            action: "reconnect",
+            fields: [
+                ["code", code],
+                ["reason", reason],
+            ],
+        }));
+    });
+    client.on("reconnect:scheduled", ({ delay }) => {
+        reconnectTracker.scheduleReconnect("connection_lost", {
+            delayMs: delay,
+            maxDelayMs: account.reconnect.maxDelay,
+        });
+    });
+    client.on("raw", (env) => {
+        if (env.event === "connect.challenge") {
+            const payload = env.payload;
+            const current = wsLogContext();
+            log?.info?.(formatWsLog({
+                event: "challenge_received",
+                accountId,
+                attempt: current.attempt,
+                reconnectCount: current.reconnectCount,
+                state: "handshaking",
+                action: "send_connect",
+                fields: [
+                    ["challenge_trace_id", env.trace_id],
+                    ["has_nonce", typeof payload?.nonce === "string" && payload.nonce.length > 0],
+                ],
+            }));
+        }
+        if (env.event === "ping" || env.event === "pong") {
+            protocolControlLogger.handleInbound(env);
+        }
+        if (wsReady) {
+            const sender = env.sender;
+            const senderId = typeof sender?.id === "string" ? sender.id : "-";
+            if (env.event === "message.send" || env.event === "message.reply") {
+                const current = wsLogContext();
+                log?.info?.(formatWsLog({
+                    event: "inbound_dispatch",
+                    accountId,
+                    attempt: current.attempt,
+                    reconnectCount: current.reconnectCount,
+                    state: "ready",
+                    action: "dispatch",
+                    fields: [
+                        ["event_name", env.event],
+                        ["trace_id", env.trace_id],
+                        ["chat_id", env.chat_id],
+                        ["sender_id", senderId],
+                    ],
+                }));
+            }
+            else if (env.event === "message.ack") {
+                const current = wsLogContext();
+                log?.info?.(formatWsLog({
+                    event: "inbound_control",
+                    accountId,
+                    attempt: current.attempt,
+                    reconnectCount: current.reconnectCount,
+                    state: "ready",
+                    action: "ack",
+                    fields: [
+                        ["event_name", env.event],
+                        ["trace_id", env.trace_id],
+                    ],
+                }));
+            }
+            else if (env.event === "offline.batch" ||
+                env.event === "offline.ack" ||
+                env.event === "offline.done") {
+                const current = wsLogContext();
+                log?.info?.(formatWsLog({
+                    event: "inbound_control",
+                    accountId,
+                    attempt: current.attempt,
+                    reconnectCount: current.reconnectCount,
+                    state: "ready",
+                    action: "ignore_legacy",
+                    fields: [
+                        ["event_name", env.event],
+                        ["trace_id", env.trace_id],
+                    ],
+                }));
+            }
+            else if (env.event !== "ping" && env.event !== "pong") {
+                const current = wsLogContext();
+                log?.info?.(formatWsLog({
+                    event: "inbound_ignored",
+                    accountId,
+                    attempt: current.attempt,
+                    reconnectCount: current.reconnectCount,
+                    state: "ready",
+                    action: "ignore",
+                    fields: [
+                        ["event_name", env.event],
+                        ["trace_id", env.trace_id],
+                    ],
+                }));
+            }
+        }
+        if (env.event !== "hello-fail")
+            return;
+        lastHelloFailTraceId = env.trace_id;
+        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(),
+                connected: false,
+                configured: false,
+                running: false,
+                lastError: classified.message,
+            });
+        }
+        else if (classified.kind === "transport") {
+            finishCurrentConnection({ state: "transport_error", error: classified.message });
+            const current = wsLogContext();
+            log?.info?.(formatWsLog({
+                event: "connection_lost",
+                accountId,
+                attempt: current.attempt,
+                reconnectCount: current.reconnectCount,
+                state: current.state,
+                action: "reconnect",
+                fields: [
+                    ["code", "-"],
+                    ["reason", classified.message],
+                ],
+            }));
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw transport error (reconnecting): ${classified.message}`);
+            setStatus({ ...getStatus(), connected: false, running: true });
+        }
+        else if (classified.kind === "ack-timeout") {
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw ack timeout: ${classified.message}`);
+        }
+        else if (classified.kind === "protocol") {
+            log?.error?.(`[${accountId}] clawchat-plugin-openclaw protocol error: ${classified.message}`);
+        }
+        else if (classified.kind === "state") {
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw state error: ${classified.message}`);
+        }
+        else {
+            log?.error?.(`[${accountId}] clawchat-plugin-openclaw client error: ${classified.message}`);
+        }
+    });
+    const loadGroupParticipantsForPrompt = async (params) => {
+        const groupFile = await readClawChatMemoryFile(params.memoryRoot, {
+            targetType: "group",
+            targetId: params.groupId,
+        });
+        const participantIds = (groupFile.metadata.participant_ids ?? "")
+            .split(",")
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0);
+        const agentOwnerId = params.ownerMetadata?.agent_owner_id ?? account.ownerUserId;
+        const groupOwnerId = groupFile.metadata.group_owner_id;
+        const participants = [];
+        for (const userId of participantIds) {
+            let metadata = null;
+            try {
+                const file = await readClawChatMemoryFile(params.memoryRoot, {
+                    targetType: "user",
+                    targetId: userId,
+                });
+                metadata = file.exists ? file.metadata : null;
+            }
+            catch {
+                metadata = null;
+            }
+            const isAgentOwner = Boolean(agentOwnerId && userId === agentOwnerId);
+            const isGroupOwner = Boolean(groupOwnerId && userId === groupOwnerId);
+            const name = isAgentOwner
+                ? params.ownerMetadata?.agent_owner_nickname ?? metadata?.nickname ?? userId
+                : userId === account.userId
+                    ? params.ownerMetadata?.agent_nickname ?? metadata?.nickname ?? userId
+                    : isGroupOwner
+                        ? groupFile.metadata.group_owner_nickname ?? metadata?.nickname ?? userId
+                        : metadata?.nickname ?? userId;
+            const profileType = metadata?.profile_type ?? (userId === account.userId ? "agent" : "user");
+            participants.push({ id: userId, name, profileType, isAgentOwner, isGroupOwner });
+        }
+        return participants;
+    };
+    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");
+        const groupParticipants = turn.peer.kind === "group"
+            ? await loadGroupParticipantsForPrompt({
+                memoryRoot,
+                groupId: turn.peer.id,
+                ownerMetadata: promptMetadata.ownerMetadata,
+            })
+            : [];
+        return renderClawChatProfilePrompt({
+            basePrompt: turn.peer.kind === "group" ? getClawChatGroupPrompt() : getClawChatUserPrompt(),
+            ...promptMetadata,
+            ownerIdFallback: account.ownerUserId,
+            groupParticipants,
+            turn: {
+                chatType: promptChatType,
+                chatId: turn.peer.id,
+                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,
+                mentionedUsers: turn.mentionedUsers,
+                messageText: turn.rawBody,
+            },
+        });
+    };
+    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",
+            senderIsGroupOwner: turn.senderIsGroupOwner ?? false,
+        };
+    };
+    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}] clawchat-plugin-openclaw 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}] clawchat-plugin-openclaw 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 = resolveChannelContextBuilder(rt)({
+            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 = optionalString(ctxPayload.SessionKey) ?? route.sessionKey;
+        openclawLlmContextDebug.writeSnapshot({
+            visibility: "injected_only",
+            trace: {
+                traceId: turn.traceId,
+                messageId: turn.messageId,
+                chatId: turn.peer.id,
+                chatType: turn.peer.kind,
+                senderId: turn.senderId,
+                sessionKey: resolvedSessionKey,
+            },
+            input: {
+                injectedPrompt: turnPrompt,
+                eventText: turn.rawBody,
+            },
+        });
+        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}] clawchat-plugin-openclaw failed to record inbound session: ${String(err)}`);
+                    },
+                });
+            }
+            catch (err) {
+                log?.error?.(`[${accountId}] clawchat-plugin-openclaw failed to record inbound session: ${String(err)}`);
+            }
+            const replyCtx = turn.replyCtx;
+            const terminalSendScopeId = `${account.accountId}\0${turn.peer.id}\0${turn.messageId}`;
+            const { dispatcher, replyOptions, markDispatchIdle } = createOpenclawClawlingReplyDispatcher({
+                cfg,
+                runtime,
+                account,
+                client,
+                target: { chatId: turn.peer.id, chatType: turn.peer.kind },
+                ...(replyCtx ? { replyCtx } : {}),
+                inboundMessageId: turn.messageId,
+                terminalSendScopeId,
+                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,
+                        markMessageAcknowledged: (input) => store.markMessageAcknowledged?.(input) ?? null,
+                        updateMessageByIdentity: (input) => store.updateMessageByIdentity?.(input),
+                    }
+                    : null,
+                log,
+            });
+            const agentsConfigured = Object.keys(cfg.agents ?? {});
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw dispatching reply msg=${turn.messageId} session=${resolvedSessionKey} agent=${route.agentId} agentsConfigured=[${agentsConfigured.join(",")}]`);
+            try {
+                const dispatchResult = await rt.reply.withReplyDispatcher({
+                    dispatcher,
+                    onSettled: () => markDispatchIdle(),
+                    run: () => runWithTerminalClawChatSendScope(terminalSendScopeId, () => rt.reply.dispatchReplyFromConfig({ ctx: ctxPayload, cfg, dispatcher, replyOptions })),
+                });
+                const counts = dispatchResult?.counts ?? {};
+                const queuedFinal = Boolean(dispatchResult?.queuedFinal);
+                log?.info?.(`[${accountId}] clawchat-plugin-openclaw dispatch complete msg=${turn.messageId} queuedFinal=${queuedFinal} counts=${JSON.stringify(counts)}`);
+                if (!queuedFinal && Object.values(counts).every((n) => !n)) {
+                    log?.info?.(`[${accountId}] clawchat-plugin-openclaw 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}] clawchat-plugin-openclaw 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}] clawchat-plugin-openclaw coalesced group dispatch failed: ${String(err)}`);
+        },
+        onDrop: (chatId, count) => {
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw dropped pending group batch chat_id=${chatId} count=${count} reason=shutdown`);
+        },
+    });
+    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}] clawchat-plugin-openclaw group command dropped chat_id=${turn.peer.id} msg=${turn.messageId} mode=${commandMode} owner=${turn.senderIsOwner === true}`);
+                    return "skipped";
+                }
+                log?.info?.(`[${accountId}] clawchat-plugin-openclaw 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}] clawchat-plugin-openclaw dispatching mentioned group batch chat_id=${turn.peer.id} msg=${turn.messageId}`);
+                return "submitted";
+            }
+            groupCoalescer.enqueue(turn);
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw 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,
+                cfg,
+                runtime,
+                account,
+                log,
+                ingest: async (turn) => {
+                    ingestResult = await ingestTurn(turn);
+                },
+            });
+        }
+        catch (err) {
+            log?.error?.(`[${accountId}] clawchat-plugin-openclaw 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}] clawchat-plugin-openclaw 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 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
+    // restart us immediately in a tight loop).
+    try {
+        log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime calling client.connect()`);
+        await client.connect();
+        log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime client.connect() resolved`);
+    }
+    catch (err) {
+        const classified = classifyClawlingClientError(err);
+        setStatus({
+            ...getStatus(),
+            connected: false,
+            configured: classified.kind !== "auth",
+            running: false,
+            lastError: classified.message,
+        });
+        if (classified.kind === "auth") {
+            finishCurrentConnection({
+                state: "auth_failed",
+                error: lastHelloFailReason || classified.message,
+            });
+            logAuthFailure(classified.message);
+            return;
+        }
+        log?.error?.(`[${accountId}] clawchat-plugin-openclaw connect failed (${classified.kind}): ${classified.message}`);
+        return;
+    }
+    activeClients.set(accountId, client);
+    log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime active client registered`);
+    setStatus({
+        ...getStatus(),
+        connected: true,
+        running: true,
+        lastStartAt: Date.now(),
+    });
+    log?.info?.(`[${accountId}] clawchat-plugin-openclaw connected`);
+    await waitUntilAbort(abortSignal, async () => {
+        log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime abort received; closing client`);
+        activeClients.delete(accountId);
+        closingForAbort = true;
+        groupCoalescer.cancelAll();
+        finishCurrentConnection({
+            state: "disconnected",
+            closeCode: 1000,
+            closeReason: "client close",
+        });
+        client.close();
+        setStatus({
+            ...getStatus(),
+            connected: false,
+            running: false,
+            lastStopAt: Date.now(),
+        });
+        log?.info?.(`[${accountId}] clawchat-plugin-openclaw disconnected`);
+    });
+}