@newbase-clawchat/openclaw-clawchat 2026.5.4 → 2026.5.12-13

package/dist/src/runtime.js

@@ -1,13 +1,18 @@
-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 { 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 } from "./config.js";
 import { dispatchOpenclawClawlingInbound } from "./inbound.js";
 import { fetchInboundMedia } from "./media-runtime.js";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.js";
 import { sendStreamingText } from "./streaming.js";
-import { sendOpenclawClawlingText } from "./outbound.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";
 const { setRuntime: setOpenclawClawlingRuntime, getRuntime: getOpenclawClawlingRuntime } = createPluginRuntimeStore("openclaw-clawchat runtime not initialized");
 export { setOpenclawClawlingRuntime, getOpenclawClawlingRuntime };
 const activeClients = new Map();
@@ -62,6 +67,87 @@ 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 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 conversationUserProfileFromParticipant(participant, refreshedAt) {
+    const participantRecord = participant;
+    const userRecord = asRecord(participantRecord.user);
+    const source = userRecord ?? participantRecord;
+    const userId = optionalString(source.id) ?? optionalString(participantRecord.user_id);
+    if (!userId)
+        return null;
+    const profile = { userId, raw: source, lastRefreshedAt: refreshedAt };
+    const nickname = optionalString(source.nickname);
+    const avatarUrl = optionalString(source.avatar_url);
+    const bio = optionalString(source.bio);
+    if (nickname !== undefined)
+        profile.nickname = nickname;
+    if (avatarUrl !== undefined)
+        profile.avatarUrl = avatarUrl;
+    if (bio !== undefined)
+        profile.bio = bio;
+    return profile;
+}
+function buildConversationDetailsCacheInput(params) {
+    const { accountId, conversation, metadataVersion } = params;
+    const refreshedAt = Date.now();
+    const rawConversation = conversation;
+    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,
+        ...(conversation.type === "group"
+            ? {
+                groupProfile: {
+                    title: conversation.title,
+                    ...(optionalString(rawConversation.description) !== undefined
+                        ? { description: optionalString(rawConversation.description) }
+                        : {}),
+                    ...(metadataVersion !== undefined ? { metadataVersion } : {}),
+                    raw: conversation,
+                    lastRefreshedAt: refreshedAt,
+                },
+            }
+            : {}),
+        userProfiles: participants
+            .map((participant) => conversationUserProfileFromParticipant(participant, refreshedAt))
+            .filter((profile) => profile !== null),
+        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,
@@ -71,23 +157,496 @@ 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");
+}
+const CLAWCHAT_GROUP_SYSTEM_PROMPT = [
+    "When replying in a ClawChat group, treat the conversation as a shared space. Stay concise, respect the group topic, and avoid exposing hidden runtime context.",
+    "",
+    "**给 Agents**",
+    "你是群组里的伙伴。请理解我们在做的事，理解每一位成员。",
+    "也请通过群慢慢和每个人建立关系——你是我们的一员。",
+    "",
+    "**两条底线**",
+    "1. 被 @ 时必须回复",
+    "2. Agent 之间连续对话不超过 10 轮，除非有人类伙伴明确允许",
+].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;
+    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),
+        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}] 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 data = 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 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 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);
+        if (version !== undefined && store?.getCachedConversation) {
+            const cached = recordConnection("conversation cache read", () => store.getCachedConversation?.({ platform: "openclaw", accountId, conversationId }));
+            if (cached?.metadataVersion != null && version <= cached.metadataVersion) {
+                log?.info?.(`[${accountId}] openclaw-clawchat metadata invalidation stale conversation=${conversationId} version=${version} cached=${cached.metadataVersion}`);
+                return;
+            }
+        }
+        await refreshConversationDetails(conversationId, {
+            source: "metadata_invalidation",
+            ...(version !== undefined ? { metadataVersion: version } : {}),
+        });
+    };
+    const upsertMessagePathConversation = (env) => {
+        if (!store?.upsertConversationSummary)
+            return;
+        if (env.event !== "message.send" && env.event !== "message.reply" && env.event !== "message.done")
+            return;
+        const conversationId = typeof env.chat_id === "string" && env.chat_id.trim()
+            ? env.chat_id
+            : "";
+        if (!conversationId)
+            return;
+        const conversationType = env.chat_type === "direct" || env.chat_type === "group"
+            ? env.chat_type
+            : undefined;
+        recordConnection("conversation summary upsert", () => store.upsertConversationSummary?.({
+            platform: "openclaw",
+            accountId,
+            conversationId,
+            ...(conversationType ? { conversationType } : {}),
+            lastSeenAt: env.emitted_at,
+        }));
+    };
     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}] 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),
+        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}] openclaw-clawchat 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) {
+            upsertMessagePathConversation(env);
+            const sender = env.sender;
+            const senderId = typeof sender?.id === "string" ? sender.id : "-";
+            if (env.event === "message.send" || env.event === "message.reply" || env.event === "message.done") {
+                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") {
-            log?.error?.(`[${accountId}] openclaw-clawchat auth failed: ${classified.message}`);
+            finishCurrentConnection({
+                state: "auth_failed",
+                error: lastHelloFailReason || classified.message,
+            });
+            logAuthFailure(classified.message);
             setStatus({
                 ...getStatus(),
                 connected: false,
@@ -97,6 +656,20 @@ 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",
+                accountId,
+                attempt: current.attempt,
+                reconnectCount: current.reconnectCount,
+                state: current.state,
+                action: "reconnect",
+                fields: [
+                    ["code", "-"],
+                    ["reason", classified.message],
+                ],
+            }));
             log?.info?.(`[${accountId}] openclaw-clawchat transport error (reconnecting): ${classified.message}`);
             setStatus({ ...getStatus(), connected: false, running: true });
         }
@@ -110,10 +683,166 @@ 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}`);
         }
     });
-    client.on("message", async (env) => {
+    const ingestTurn = async (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";
+            }
+        }
+        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.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,
+                },
+            },
+            ...(turn.peer.kind === "group"
+                ? { supplemental: { groupSystemPrompt: CLAWCHAT_GROUP_SYSTEM_PROMPT } }
+                : {}),
+        });
+        // 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,
+            },
+            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=${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.`);
+            }
+            return "submitted";
+        }
+        catch (err) {
+            log?.error?.(`[${accountId}] openclaw-clawchat dispatch failed msg=${turn.messageId}: ${String(err)}`);
+            return "failed";
+        }
+    };
+    const handleInboundEnvelope = async (env) => {
+        let ingestResult;
         try {
             await dispatchOpenclawClawlingInbound({
                 envelope: env,
@@ -122,135 +851,66 @@ 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 ctxPayload = rt.reply.finalizeInboundContext({
-                        Body: body,
-                        BodyForAgent: turn.rawBody,
-                        RawBody: turn.rawBody,
-                        CommandBody: turn.rawBody,
-                        // Clawling v2 routes by chat_id. `senderId` is still preserved as
-                        // structured metadata, but the conversation target must be based on
-                        // `peer.id` so follow-up sends address the active chat, not merely
-                        // the human sender identity.
-                        From: `${CHANNEL_ID}:${formatConversationSubject(turn.peer)}`,
-                        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: `${CHANNEL_ID}:${account.userId}`,
-                    });
-                    // 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)}`);
-                        await sendOpenclawClawlingText({
-                            client,
-                            account: turn.account,
-                            to: {
-                                chatId: turn.peer.id,
-                                chatType: turn.peer.kind === "group" ? "group" : "direct",
-                            },
-                            text: String(err),
-                            ...(turn.replyCtx ? { replyCtx: turn.replyCtx } : {}),
-                        });
-                    }
+                    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 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
     // restart us immediately in a tight loop).
     try {
+        log?.info?.(`[${accountId}] openclaw-clawchat runtime calling client.connect()`);
         await client.connect();
+        log?.info?.(`[${accountId}] openclaw-clawchat runtime client.connect() resolved`);
     }
     catch (err) {
         const classified = classifyClawlingClientError(err);
@@ -261,10 +921,19 @@ export async function startOpenclawClawlingGateway(params) {
             running: false,
             lastError: classified.message,
         });
+        if (classified.kind === "auth") {
+            finishCurrentConnection({
+                state: "auth_failed",
+                error: lastHelloFailReason || classified.message,
+            });
+            logAuthFailure(classified.message);
+            return;
+        }
         log?.error?.(`[${accountId}] openclaw-clawchat connect failed (${classified.kind}): ${classified.message}`);
         return;
     }
     activeClients.set(accountId, client);
+    log?.info?.(`[${accountId}] openclaw-clawchat runtime active client registered`);
     setStatus({
         ...getStatus(),
         connected: true,
@@ -273,7 +942,14 @@ export async function startOpenclawClawlingGateway(params) {
     });
     log?.info?.(`[${accountId}] openclaw-clawchat connected`);
     await waitUntilAbort(abortSignal, async () => {
+        log?.info?.(`[${accountId}] openclaw-clawchat runtime abort received; closing client`);
         activeClients.delete(accountId);
+        closingForAbort = true;
+        finishCurrentConnection({
+            state: "disconnected",
+            closeCode: 1000,
+            closeReason: "client close",
+        });
         client.close();
         setStatus({
             ...getStatus(),