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

package/src/runtime.ts

@@ -4,24 +4,58 @@ import {
   ProtocolError,
   StateError,
   TransportError,
-  type ClawlingChatClient,
-  type DownlinkMessageSendPayload,
+  EVENT,
   type Envelope,
   type Transport,
-} from "@newbase-clawchat/sdk";
+} from "./protocol-types.ts";
 import type { ChannelAccountSnapshot } from "openclaw/plugin-sdk/channel-contract";
 import { waitUntilAbort } from "openclaw/plugin-sdk/channel-lifecycle";
 import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/core";
 import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 import { createOpenclawClawlingClient } from "./client.ts";
+import { createOpenclawClawlingApiClient } from "./api-client.ts";
+import { ClawlingApiError, type ConversationDetails, type ConversationParticipant } from "./api-types.ts";
 import { CHANNEL_ID, type ResolvedOpenclawClawlingAccount } from "./config.ts";
-import { dispatchOpenclawClawlingInbound } from "./inbound.ts";
+import type { ClawlingChatClient } from "./ws-client.ts";
+import { dispatchOpenclawClawlingInbound, type IngestTurnParams } from "./inbound.ts";
 import { fetchInboundMedia } from "./media-runtime.ts";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.ts";
 import { sendStreamingText } from "./streaming.ts";
-import { sendOpenclawClawlingText } from "./outbound.ts";
+import {
+  flushAlignedOutboundQueue,
+  getAlignedOutboundQueueSize,
+  setAlignedOutboundLogContext,
+} from "./outbound.ts";
+import { formatWsLog } from "./ws-log.ts";
+import { createProtocolControlHandler, createReconnectTracker } from "./ws-alignment.ts";
+import {
+  clawChatDbPathForStateDir,
+  getClawChatStore,
+  type ClawChatStore,
+} from "./storage.ts";
 
 type Log = { info?: (m: string) => void; error?: (m: string) => void };
+type RuntimeConnectionStore = Pick<
+  ClawChatStore,
+  "startConnection" | "markConnectSent" | "markConnectionReady" | "finishConnection"
+> &
+  Partial<
+    Pick<
+      ClawChatStore,
+      | "insertMessage"
+      | "claimMessageOnce"
+      | "updateMessageByIdentity"
+      | "claimPendingActivationBootstrap"
+      | "releaseActivationBootstrapClaim"
+      | "markActivationBootstrapSent"
+      | "upsertConversationSummary"
+      | "upsertConversationDetails"
+      | "deleteConversationCache"
+      | "listCachedConversationIds"
+      | "getActivationConversation"
+      | "getCachedConversation"
+    >
+  >;
 
 const { setRuntime: setOpenclawClawlingRuntime, getRuntime: getOpenclawClawlingRuntime } =
   createPluginRuntimeStore<PluginRuntime>("openclaw-clawchat runtime not initialized");
@@ -107,6 +141,109 @@ function formatConversationSubject(peer: { kind: "direct" | "group"; id: string
   return peer.kind === "group" ? `group:${peer.id}` : peer.id;
 }
 
+function parseApiTimestamp(value: unknown): number | null {
+  if (typeof value !== "string") return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" ? value as Record<string, unknown> : null;
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function isConversationNotFoundError(err: unknown): boolean {
+  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: Envelope): number | undefined {
+  const payload = asRecord(env.payload);
+  const version = payload?.version;
+  return typeof version === "number" && Number.isFinite(version) ? version : undefined;
+}
+
+function conversationUserProfileFromParticipant(
+  participant: ConversationParticipant,
+  refreshedAt: number,
+): {
+  userId: string;
+  nickname?: string | null;
+  avatarUrl?: string | null;
+  bio?: string | null;
+  raw?: unknown;
+  lastRefreshedAt?: number | null;
+} | null {
+  const participantRecord = participant as Record<string, unknown>;
+  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: string;
+    nickname?: string | null;
+    avatarUrl?: string | null;
+    bio?: string | null;
+    raw?: unknown;
+    lastRefreshedAt?: number | null;
+  } = { 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: {
+  accountId: string;
+  conversation: ConversationDetails;
+  metadataVersion?: number;
+}): Parameters<NonNullable<RuntimeConnectionStore["upsertConversationDetails"]>>[0] {
+  const { accountId, conversation, metadataVersion } = params;
+  const refreshedAt = Date.now();
+  const rawConversation = conversation as Record<string, unknown>;
+  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 is NonNullable<typeof 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: OpenClawConfig): OpenClawConfig {
   return {
     ...cfg,
@@ -117,6 +254,65 @@ function withClawChatSessionScope(cfg: OpenClawConfig): OpenClawConfig {
   };
 }
 
+function buildActivationBootstrapText(): string {
+  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: {
+  account: ResolvedOpenclawClawlingAccount;
+  conversationId: string;
+}): Envelope {
+  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,
+        },
+      },
+    },
+  };
+}
+
 export interface StartGatewayParams {
   cfg: OpenClawConfig;
   account: ResolvedOpenclawClawlingAccount;
@@ -125,29 +321,493 @@ export interface StartGatewayParams {
   getStatus: () => ChannelAccountSnapshot;
   log?: Log;
   /** Test hook only. */
+  store?: RuntimeConnectionStore | null;
+  /** Test hook only. */
   transport?: Transport;
 }
 
+function resolveConnectionStore(
+  params: StartGatewayParams,
+  runtime: PluginRuntime,
+): RuntimeConnectionStore | null {
+  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: StartGatewayParams): Promise<void> {
   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: ReturnType<typeof createOpenclawClawlingApiClient> | undefined;
+  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: string | undefined;
+  let lastHelloOkDeliveryMode: string | undefined;
+  let currentAttemptStartedAt = 0;
+  let authFailureLogged = false;
+  let closingForAbort = false;
+  let wsReady = false;
+  let currentConnectionId: number | null = 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 = <T>(action: string, fn: () => T): T | undefined => {
+    try {
+      return fn();
+    } catch {
+      log?.error?.(`[${accountId}] openclaw-clawchat sqlite ${action} failed; continuing`);
+      return undefined;
+    }
+  };
+  const finishCurrentConnection = (input: {
+    state: string;
+    disconnectedAt?: number;
+    closeCode?: number | null;
+    closeReason?: string | null;
+    error?: string | null;
+  }) => {
+    if (!store || currentConnectionId == null || currentConnectionFinished) return;
+    const connectionId = currentConnectionId;
+    recordConnection("finish", () => store.finishConnection(connectionId, input));
+    currentConnectionFinished = true;
+    currentConnectionId = null;
+  };
+  const refreshConversationDetails = async (
+    conversationId: string,
+    options: { metadataVersion?: number; source: string },
+  ): Promise<void> => {
+    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 (): Promise<void> => {
+    if (!store) return;
+    const ids: string[] = [];
+    const seen = new Set<string>();
+    const addId = (id: unknown) => {
+      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: Envelope): Promise<void> => {
+    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: Envelope): void => {
+    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: Envelope) => {
+    const payload = env.payload && typeof env.payload === "object"
+      ? env.payload as { device_id?: unknown; delivery_mode?: unknown }
+      : {};
+    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: string) => {
+    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: () => Promise<void> = 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 as ClawlingState) };
     setStatus(next);
   });
 
+  client.on("close", ({ code, reason }: { code?: number; reason?: string }) => {
+    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 }: { delay?: number }) => {
+    reconnectTracker.scheduleReconnect("connection_lost", {
+      delayMs: delay,
+      maxDelayMs: account.reconnect.maxDelay,
+    });
+  });
+
+  client.on("raw", (env: Envelope) => {
+    if (env.event === "connect.challenge") {
+      const payload = env.payload as { nonce?: unknown } | undefined;
+      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 as { id?: unknown } | undefined;
+      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 as { reason?: unknown } | undefined;
+    lastHelloFailReason = typeof payload?.reason === "string" ? payload.reason : "";
+  });
+
+  client.on("metadata:invalidated", (env: Envelope) => {
+    void handleMetadataInvalidation(env);
+  });
+
   client.on("error", (err: unknown) => {
     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,
@@ -156,6 +816,22 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         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}] openclaw-clawchat transport error (reconnecting): ${classified.message}`,
       );
@@ -167,169 +843,270 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     } else if (classified.kind === "state") {
       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: Envelope) => {
-    try {
-      await dispatchOpenclawClawlingInbound({
-      envelope: env as Envelope<DownlinkMessageSendPayload>,
-      cfg,
-      runtime,
-      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,
+  type IngestTurnResult = "submitted" | "skipped" | "failed";
+
+  const ingestTurn = async (turn: IngestTurnParams): Promise<IngestTurnResult> => {
+    const env = turn.envelope;
+    if (store?.claimMessageOnce) {
+      const claimed = recordConnection("message claim", () =>
+        store.claimMessageOnce?.({
+          platform: "openclaw",
           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 as Record<string, unknown>).MediaPath = inboundPaths[0];
-          (ctxPayload as Record<string, unknown>).MediaPaths = inboundPaths;
-        }
+          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 as Record<string, unknown>).MediaPath = inboundPaths[0];
+      (ctxPayload as Record<string, unknown>).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) {
+    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 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 as { agents?: Record<string, unknown> }).agents ?? {});
+    const agentsConfigured = Object.keys((cfg as { agents?: Record<string, unknown> }).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 as { counts?: Record<string, number> } | undefined)?.counts ?? {};
+      const queuedFinal = Boolean(
+        (dispatchResult as { queuedFinal?: boolean } | undefined)?.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 dispatching reply msg=${turn.messageId} session=${ctxPayload.SessionKey ?? route.sessionKey} agent=${route.agentId} agentsConfigured=[${agentsConfigured.join(",")}]`,
+          `[${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.`,
         );
-        
-        try {
-          const dispatchResult = await rt.reply.withReplyDispatcher({
-            dispatcher,
-            onSettled: () => markDispatchIdle(),
-            run: () =>
-              rt.reply.dispatchReplyFromConfig({ ctx: ctxPayload, cfg, dispatcher, replyOptions }),
-          });
-          const counts = (dispatchResult as { counts?: Record<string, number> } | undefined)?.counts ?? {};
-          const queuedFinal = Boolean(
-            (dispatchResult as { queuedFinal?: boolean } | undefined)?.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 } : {}),
-          });
-        }
-      },
-      })
+      }
+      return "submitted";
+    } catch (err) {
+      log?.error?.(
+        `[${accountId}] openclaw-clawchat dispatch failed msg=${turn.messageId}: ${String(err)}`,
+      );
+      return "failed";
+    }
+  };
+
+  const handleInboundEnvelope = async (env: Envelope): Promise<IngestTurnResult | undefined> => {
+    let ingestResult: IngestTurnResult | undefined;
+    try {
+      await dispatchOpenclawClawlingInbound({
+        envelope: env as Envelope<unknown>,
+        cfg,
+        runtime,
+        account,
+        log,
+        ingest: async (turn) => {
+          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 (): Promise<void> => {
+    if (!store?.claimPendingActivationBootstrap || !store.markActivationBootstrapSent) return;
+    let bootstrap: { conversationId: string } | null | undefined;
+    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: Envelope) => {
+    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);
     setStatus({
@@ -339,12 +1116,21 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       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,
@@ -354,7 +1140,14 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   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(),