@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/runtime.ts

@@ -0,0 +1,1493 @@
+import {
+  AckTimeoutError,
+  AuthError,
+  ProtocolError,
+  StateError,
+  TransportError,
+  EVENT,
+  type Envelope,
+  type Transport,
+} from "./protocol-types.ts";
+import type { ChannelAccountSnapshot } from "openclaw/plugin-sdk/channel-contract";
+import { waitUntilAbort } from "openclaw/plugin-sdk/channel-lifecycle";
+import { hasControlCommand } from "openclaw/plugin-sdk/command-detection";
+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 } from "./api-types.ts";
+import {
+  CHANNEL_ID,
+  effectiveGroupCommandMode,
+  type ResolvedOpenclawClawlingAccount,
+} from "./config.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 { runWithTerminalClawChatSendScope } from "./terminal-send.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";
+import { getClawChatGroupPrompt, getClawChatUserPrompt } from "./plugin-prompts.ts";
+import {
+  loadClawChatPromptMetadata,
+  type ClawChatGroupParticipantPrompt,
+  type ClawChatPromptMetadata,
+  renderClawChatProfilePrompt,
+  resolveSenderRelation,
+} from "./profile-prompt.ts";
+import { refreshGroupProfile, syncFirstSeenClawChatProfiles } from "./profile-sync.ts";
+import { pullGroupMetadata, pullOwnerMetadata } from "./clawchat-metadata.ts";
+import { deleteClawChatMemoryFile, readClawChatMemoryFile } from "./clawchat-memory.ts";
+import {
+  clearClawChatPromptInjectionForSession,
+  stageClawChatPromptInjection,
+} from "./prompt-injection.ts";
+import { createGroupMessageCoalescer } from "./group-message-coalescer.ts";
+import { openclawLlmContextDebug } from "./llm-context-debug.ts";
+
+type Log = { info?: (m: string) => void; error?: (m: string) => void };
+type ChannelContextBuilder = (params: Record<string, unknown>) => unknown;
+type CompatibleChannelRuntime = PluginRuntime["channel"] & {
+  inbound?: { buildContext?: ChannelContextBuilder };
+  turn?: { buildContext?: ChannelContextBuilder };
+};
+type OpenClawReplyContext = Parameters<
+  PluginRuntime["channel"]["reply"]["dispatchReplyFromConfig"]
+>[0]["ctx"];
+type MutableOpenClawReplyContext = OpenClawReplyContext & Record<string, unknown>;
+type RuntimeConnectionStore = Pick<
+  ClawChatStore,
+  "startConnection" | "markConnectSent" | "markConnectionReady" | "finishConnection"
+> &
+  Partial<
+    Pick<
+      ClawChatStore,
+      | "insertMessage"
+      | "claimMessageOnce"
+      | "markMessageAcknowledged"
+      | "updateMessageByIdentity"
+      | "claimPendingActivationBootstrap"
+      | "releaseActivationBootstrapClaim"
+      | "markActivationBootstrapSent"
+      | "getActivationConversation"
+    >
+  >;
+
+const { setRuntime: setOpenclawClawlingRuntime, getRuntime: getOpenclawClawlingRuntime } =
+  createPluginRuntimeStore<PluginRuntime>("clawchat-plugin-openclaw runtime not initialized");
+
+export { setOpenclawClawlingRuntime, getOpenclawClawlingRuntime };
+
+const activeClients = new Map<string, ClawlingChatClient>();
+const CLAWCHAT_PLUGIN_SLASH_COMMANDS = new Set(["clawchat-activate"]);
+const CLAWCHAT_MEMORY_ROOT_UNAVAILABLE =
+  "ClawChat memory root unavailable: OpenClaw workspaceDir could not be resolved";
+const OPENCLAW_CONFIRM_SLASH_COMMANDS = new Set([
+  "approve",
+  "deny",
+  "always",
+  "cancel",
+  "yes",
+  "no",
+  "ok",
+  "confirm",
+  "remember",
+  "nevermind",
+]);
+
+function resolveChannelContextBuilder(rt: PluginRuntime["channel"]): ChannelContextBuilder {
+  const channel = rt as CompatibleChannelRuntime;
+  const buildContext = channel.inbound?.buildContext ?? channel.turn?.buildContext;
+  if (!buildContext) {
+    throw new Error("OpenClaw channel runtime missing inbound/turn buildContext");
+  }
+  return buildContext;
+}
+
+function parseSlashCommandName(rawBody: string): string | null {
+  const stripped = rawBody.trimStart();
+  if (!stripped.startsWith("/")) return null;
+  const token = stripped.split(/\s+/, 1)[0] ?? "";
+  const name = token.slice(1).replace(/_/g, "-").toLowerCase();
+  if (!name || name.includes("/")) return null;
+  return name;
+}
+
+function isKnownOpenClawGroupSlashCommand(rawBody: string, cfg: OpenClawConfig): boolean {
+  const name = parseSlashCommandName(rawBody);
+  if (!name) return false;
+  return hasControlCommand(rawBody, cfg)
+    || CLAWCHAT_PLUGIN_SLASH_COMMANDS.has(name)
+    || OPENCLAW_CONFIRM_SLASH_COMMANDS.has(name);
+}
+
+export function getOpenclawClawlingClient(accountId: string): ClawlingChatClient | undefined {
+  return activeClients.get(accountId);
+}
+
+export function resolveClawChatMemoryRoot(
+  runtime: PluginRuntime,
+  cfg: OpenClawConfig,
+  agentId: string,
+): string {
+  const resolver = runtime.agent?.resolveAgentWorkspaceDir;
+  if (typeof resolver !== "function") {
+    throw new Error(CLAWCHAT_MEMORY_ROOT_UNAVAILABLE);
+  }
+
+  let workspaceDir: string;
+  try {
+    workspaceDir = resolver(cfg, agentId);
+  } catch {
+    throw new Error(CLAWCHAT_MEMORY_ROOT_UNAVAILABLE);
+  }
+
+  const memoryRoot = typeof workspaceDir === "string" ? workspaceDir.trim() : "";
+  if (!memoryRoot) {
+    throw new Error(CLAWCHAT_MEMORY_ROOT_UNAVAILABLE);
+  }
+  return memoryRoot;
+}
+
+export async function waitForOpenclawClawlingClient(
+  accountId: string,
+  options: { timeoutMs?: number; pollMs?: number } = {},
+): Promise<ClawlingChatClient> {
+  const timeoutMs = options.timeoutMs ?? 15_000;
+  const pollMs = options.pollMs ?? 100;
+  const deadline = Date.now() + timeoutMs;
+
+  for (;;) {
+    const client = activeClients.get(accountId);
+    if (client && (client as { state?: string }).state === "connected") {
+      return client;
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `clawchat-plugin-openclaw client did not activate within ${timeoutMs}ms for account ${accountId}`,
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
+export type ClawlingState =
+  | "idle"
+  | "connecting"
+  | "challenging"
+  | "authenticating"
+  | "connected"
+  | "reconnecting"
+  | "disconnected";
+
+export function mapClawlingStateToStatus(state: ClawlingState): {
+  connected: boolean;
+  running: boolean;
+  lastStartAt?: number;
+  lastStopAt?: number;
+} {
+  const now = Date.now();
+  switch (state) {
+    case "connected":
+      return { connected: true, running: true, lastStartAt: now };
+    case "reconnecting":
+      return { connected: false, running: true };
+    case "disconnected":
+      return { connected: false, running: false, lastStopAt: now };
+    default:
+      return { connected: false, running: true };
+  }
+}
+
+export function classifyClawlingClientError(err: unknown): {
+  kind: "auth" | "transport" | "protocol" | "ack-timeout" | "state" | "unknown";
+  retry: boolean;
+  message: string;
+} {
+  if (err instanceof AuthError) return { kind: "auth", retry: false, message: err.message };
+  if (err instanceof TransportError)
+    return { kind: "transport", retry: true, message: err.message };
+  if (err instanceof AckTimeoutError)
+    return { kind: "ack-timeout", retry: false, message: err.message };
+  if (err instanceof ProtocolError) return { kind: "protocol", retry: false, message: err.message };
+  if (err instanceof StateError) return { kind: "state", retry: false, message: err.message };
+  return {
+    kind: "unknown",
+    retry: false,
+    message: err instanceof Error ? err.message : String(err),
+  };
+}
+
+function formatConversationSubject(peer: { kind: "direct" | "group"; id: string }): string {
+  return peer.kind === "group" ? `group:${peer.id}` : peer.id;
+}
+
+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 hasOwn(record: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+function optionalNullableString(record: Record<string, unknown>, key: string): string | null | undefined {
+  if (!hasOwn(record, key)) return undefined;
+  const value = record[key];
+  if (value === null) return null;
+  return optionalString(value);
+}
+
+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 ||
+    err.message.toLowerCase().includes("conversation not found");
+}
+
+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 metadataScopesFromEnvelope(env: Envelope): string[] {
+  const scope = asRecord(env.payload)?.scope;
+  return Array.isArray(scope) ? scope.filter((item): item is string => typeof item === "string") : [];
+}
+
+function shouldRefreshBehaviorForScopes(scopes: string[]): boolean {
+  return scopes.includes("behavior");
+}
+
+function shouldRefreshConversationForScopes(scopes: string[]): boolean {
+  if (scopes.length === 0) return true;
+  return scopes.some((scope) => scope === "title" || scope === "description" || scope !== "behavior");
+}
+
+function withClawChatSessionScope(cfg: OpenClawConfig): OpenClawConfig {
+  return {
+    ...cfg,
+    session: {
+      ...(cfg.session ?? {}),
+      dmScope: "per-account-channel-peer",
+    },
+  };
+}
+
+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");
+}
+
+function buildActivationBootstrapEnvelope(params: {
+  account: ResolvedOpenclawClawlingAccount;
+  conversationId: string;
+}): Envelope {
+  const text = buildActivationBootstrapText();
+  const now = Date.now();
+  return {
+    version: "2",
+    event: EVENT.MESSAGE_SEND,
+    trace_id: `clawchat-plugin-openclaw-bootstrap-${now}`,
+    emitted_at: now,
+    chat_id: params.conversationId,
+    chat_type: "direct",
+    to: { id: params.account.userId, type: "direct" },
+    sender: {
+      id: "clawchat-bootstrap",
+      type: "direct",
+      nick_name: "ClawChat Activation",
+    },
+    payload: {
+      message_id: `clawchat-plugin-openclaw-bootstrap-${params.conversationId}-${now}`,
+      message_mode: "normal",
+      message: {
+        body: { fragments: [{ kind: "text", text }] },
+        context: { mentions: [], reply: null },
+        streaming: {
+          status: "static",
+          sequence: 0,
+          mutation_policy: "sealed",
+          started_at: null,
+          completed_at: null,
+        },
+      },
+    },
+  };
+}
+
+export interface StartGatewayParams {
+  cfg: OpenClawConfig;
+  account: ResolvedOpenclawClawlingAccount;
+  abortSignal: AbortSignal;
+  setStatus: (next: ChannelAccountSnapshot) => void;
+  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?.("clawchat-plugin-openclaw 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}] clawchat-plugin-openclaw runtime start entered configured=${account.configured} enabled=${account.enabled} hasToken=${Boolean(account.token)} hasUserId=${Boolean(account.userId)} hasOwnerUserId=${Boolean(account.ownerUserId)} websocketUrl=${account.websocketUrl || "(empty)"}`,
+  );
+  let lastHelloFailTraceId = "-";
+  let lastHelloFailReason = "";
+  let lastConnectTraceId = "-";
+  let lastHelloOkDeviceId: 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}] clawchat-plugin-openclaw 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; memoryRoot?: string },
+  ): Promise<void> => {
+    try {
+      const memoryRoot = options.memoryRoot;
+      if (!memoryRoot) {
+        await getConversationApiClient().getConversation(conversationId);
+        return;
+      }
+      const result = await pullGroupMetadata({
+        memoryRoot,
+        groupId: conversationId,
+        api: getConversationApiClient(),
+        skipUserIds: [account.userId, account.ownerUserId],
+      });
+      if (result.failures.length > 0) {
+        log?.error?.(
+          `[${accountId}] clawchat-plugin-openclaw group participant metadata refresh partially failed: ${result.failures.map((failure) => `${failure.targetId}: ${failure.error}`).join("; ")}`,
+        );
+      }
+      if (!result.conversation) throw new Error("ClawChat conversation metadata response is missing conversation");
+    } catch (err) {
+      if (isConversationNotFoundError(err)) {
+        if (options.memoryRoot) {
+          await deleteClawChatMemoryFile(options.memoryRoot, {
+            targetType: "group",
+            targetId: conversationId,
+          }).catch((deleteError) => {
+            log?.error?.(
+              `[${accountId}] clawchat-plugin-openclaw group metadata file delete failed conversation=${conversationId}: ${
+                deleteError instanceof Error ? deleteError.message : String(deleteError)
+              }`,
+            );
+          });
+        }
+        return;
+      }
+      log?.error?.(
+        `[${accountId}] clawchat-plugin-openclaw metadata refresh failed source=${options.source} conversation=${conversationId}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  };
+  const refreshAgentBehavior = async (options: {
+    metadataVersion?: number;
+    source: string;
+    memoryRoot: string;
+  }): Promise<void> => {
+    try {
+      await pullOwnerMetadata({
+        memoryRoot: options.memoryRoot,
+        agentId: account.agentId,
+        accountUserId: account.userId,
+        accountOwnerUserId: account.ownerUserId,
+        api: getConversationApiClient(),
+      });
+    } catch (err) {
+      log?.error?.(
+        `[${accountId}] clawchat-plugin-openclaw behavior refresh failed source=${options.source} agent=${account.userId}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  };
+  const refreshConversationCacheAfterReady = async (): Promise<void> => {
+    void store;
+  };
+  const resolveMemoryRootForPeer = (peer: { kind: "direct" | "group"; id: string }): string | null => {
+    try {
+      const route = runtime.channel.routing.resolveAgentRoute({
+        cfg: withClawChatSessionScope(cfg),
+        channel: CHANNEL_ID,
+        accountId,
+        peer,
+      });
+      return resolveClawChatMemoryRoot(runtime, cfg, route.agentId);
+    } catch (err) {
+      log?.error?.(
+        `[${accountId}] clawchat-plugin-openclaw metadata refresh memory root unavailable: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return null;
+    }
+  };
+  const handleMetadataInvalidation = async (env: Envelope): Promise<void> => {
+    const conversationId = typeof env.chat_id === "string" && env.chat_id.trim()
+      ? env.chat_id
+      : "";
+    if (!conversationId) {
+      log?.info?.(`[${accountId}] clawchat-plugin-openclaw metadata invalidation missing chat_id trace=${env.trace_id}`);
+      return;
+    }
+
+    const version = metadataVersionFromEnvelope(env);
+    const scopes = metadataScopesFromEnvelope(env);
+    const refreshBehavior = shouldRefreshBehaviorForScopes(scopes);
+    const refreshConversation = shouldRefreshConversationForScopes(scopes);
+    if (!refreshBehavior && !refreshConversation) return;
+    const peer = {
+      kind: env.chat_type === "group" ? "group" as const : "direct" as const,
+      id: conversationId,
+    };
+    const memoryRoot = resolveMemoryRootForPeer(peer);
+    if (!memoryRoot) return;
+
+    if (refreshBehavior) {
+      await refreshAgentBehavior({
+        source: "metadata_invalidation",
+        ...(version !== undefined ? { metadataVersion: version } : {}),
+        memoryRoot,
+      });
+    }
+
+    if (!refreshConversation) return;
+
+    await refreshConversationDetails(conversationId, {
+      source: "metadata_invalidation",
+      ...(version !== undefined ? { metadataVersion: version } : {}),
+      memoryRoot,
+    });
+  };
+  const syncMessagePathProfiles = async (turn: IngestTurnParams, memoryRoot: string): Promise<void> => {
+    if (turn.senderId === "clawchat-bootstrap") {
+      await pullOwnerMetadata({
+        memoryRoot,
+        agentId: account.agentId,
+        accountUserId: account.userId,
+        accountOwnerUserId: account.ownerUserId,
+        api: getConversationApiClient(),
+      });
+      return;
+    }
+    if (turn.peer.kind === "direct" && (turn.senderId === account.ownerUserId || turn.senderId === account.userId)) {
+      await pullOwnerMetadata({
+        memoryRoot,
+        agentId: account.agentId,
+        accountUserId: account.userId,
+        accountOwnerUserId: account.ownerUserId,
+        api: getConversationApiClient(),
+      });
+      return;
+    }
+    if (turn.peer.kind === "group") {
+      await refreshGroupProfile({
+        platform: "openclaw",
+        accountId,
+        accountUserId: account.userId,
+        accountOwnerUserId: account.ownerUserId,
+        conversationId: turn.peer.id,
+        api: getConversationApiClient(),
+        store: {},
+        memoryRoot,
+        log: { error: (message) => log?.error?.(`[${accountId}] ${message}`) },
+      });
+      return;
+    }
+    await syncFirstSeenClawChatProfiles({
+      platform: "openclaw",
+      accountId,
+      accountUserId: account.userId,
+      accountOwnerUserId: account.ownerUserId,
+      chat: {
+        id: turn.peer.id,
+        type: "direct",
+        lastSeenAt: turn.timestamp,
+      },
+      sender: {
+        id: turn.senderId,
+        ...(turn.senderNickName ? { nickname: turn.senderNickName } : {}),
+      },
+      api: getConversationApiClient(),
+      store: {},
+      memoryRoot,
+      log: { error: (message) => log?.error?.(`[${accountId}] ${message}`) },
+    });
+  };
+  const client = createOpenclawClawlingClient(account, {
+    ...(params.transport ? { transport: params.transport } : {}),
+    wsLifecycle: {
+      onConnectFrameSent: (env) => {
+        lastConnectTraceId = typeof env.trace_id === "string" ? env.trace_id : "-";
+        if (store && currentConnectionId != null) {
+          const connectionId = currentConnectionId;
+          recordConnection("connect-sent", () => store.markConnectSent(connectionId));
+        }
+        const deviceId =
+          typeof env.payload?.device_id === "string" ? env.payload.device_id : "-";
+        const current = wsLogContext();
+        log?.info?.(
+          formatWsLog({
+            event: "connect_sent",
+            accountId,
+            attempt: current.attempt,
+            reconnectCount: current.reconnectCount,
+            state: "handshaking",
+            action: "await_hello",
+            fields: [
+              ["trace_id", lastConnectTraceId],
+              ["device_id", deviceId],
+            ],
+          }),
+        );
+      },
+    },
+  });
+  log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime client created`);
+
+  setAlignedOutboundLogContext(client, wsLogContext);
+  client.on("hello:ok", (env: 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}] clawchat-plugin-openclaw state ${from} -> ${to}`);
+    wsReady = to === "connected";
+    if (to === "connecting") {
+      reconnectTracker.connectStart();
+      currentAttemptStartedAt = Date.now();
+      const current = wsLogContext();
+      if (store) {
+        recordConnection("start", () => {
+          currentConnectionId = store.startConnection({
+            platform: "openclaw",
+            accountId,
+            attempt: current.attempt,
+            reconnectCount: current.reconnectCount,
+            connectStartedAt: currentAttemptStartedAt,
+          });
+          currentConnectionFinished = false;
+        });
+      }
+      log?.info?.(
+        formatWsLog({
+          event: "connect_start",
+          accountId,
+          attempt: current.attempt,
+          reconnectCount: current.reconnectCount,
+          state: "connecting",
+          action: "connect",
+          fields: [
+            ["url", account.websocketUrl],
+            ["queue_size", getAlignedOutboundQueueSize(client)],
+          ],
+        }),
+      );
+    } else if (to === "connected") {
+      const elapsedMs = Math.max(0, Date.now() - currentAttemptStartedAt);
+      const queueSize = getAlignedOutboundQueueSize(client);
+      reconnectTracker.markReady();
+      const current = wsLogContext();
+      if (store && currentConnectionId != null) {
+        const connectionId = currentConnectionId;
+        recordConnection("ready", () => {
+          if (lastHelloOkDeviceId === undefined && lastHelloOkDeliveryMode === undefined) {
+            store.markConnectionReady(connectionId);
+            return;
+          }
+          store.markConnectionReady(connectionId, {
+            ...(lastHelloOkDeviceId !== undefined ? { resolvedDeviceId: lastHelloOkDeviceId } : {}),
+            ...(lastHelloOkDeliveryMode !== undefined ? { deliveryMode: lastHelloOkDeliveryMode } : {}),
+          });
+        });
+      }
+      log?.info?.(
+        formatWsLog({
+          event: "handshake_ok",
+          accountId,
+          attempt: current.attempt,
+          reconnectCount: current.reconnectCount,
+          state: "ready",
+          action: "flush_queue",
+          fields: [
+            ["trace_id", lastConnectTraceId],
+            ["elapsed_ms", elapsedMs],
+            ["queue_size", queueSize],
+          ],
+        }),
+      );
+      try {
+        flushAlignedOutboundQueue(client);
+      } catch {
+        // The queue keeps the failed frame at the head and will retry after the next reconnect.
+      }
+      void refreshConversationCacheAfterReady();
+      void dispatchActivationBootstrap();
+    } else if (to === "disconnected") {
+      reconnectTracker.markClosed();
+    }
+    const next = { ...getStatus(), ...mapClawlingStateToStatus(to 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) {
+      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") {
+        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") {
+      finishCurrentConnection({
+        state: "auth_failed",
+        error: lastHelloFailReason || classified.message,
+      });
+      logAuthFailure(classified.message);
+      setStatus({
+        ...getStatus(),
+        connected: false,
+        configured: false,
+        running: false,
+        lastError: classified.message,
+      });
+    } else if (classified.kind === "transport") {
+      finishCurrentConnection({ state: "transport_error", error: classified.message });
+      const current = wsLogContext();
+      log?.info?.(
+        formatWsLog({
+          event: "connection_lost",
+          accountId,
+          attempt: current.attempt,
+          reconnectCount: current.reconnectCount,
+          state: current.state,
+          action: "reconnect",
+          fields: [
+            ["code", "-"],
+            ["reason", classified.message],
+          ],
+        }),
+      );
+      log?.info?.(
+        `[${accountId}] clawchat-plugin-openclaw transport error (reconnecting): ${classified.message}`,
+      );
+      setStatus({ ...getStatus(), connected: false, running: true });
+    } else if (classified.kind === "ack-timeout") {
+      log?.info?.(`[${accountId}] clawchat-plugin-openclaw ack timeout: ${classified.message}`);
+    } else if (classified.kind === "protocol") {
+      log?.error?.(`[${accountId}] clawchat-plugin-openclaw protocol error: ${classified.message}`);
+    } else if (classified.kind === "state") {
+      log?.info?.(`[${accountId}] clawchat-plugin-openclaw state error: ${classified.message}`);
+    } else {
+      log?.error?.(`[${accountId}] clawchat-plugin-openclaw client error: ${classified.message}`);
+    }
+  });
+
+  type IngestTurnResult = "submitted" | "skipped" | "failed";
+  type GroupIngestTurnParams = IngestTurnParams & { peer: { kind: "group"; id: string } };
+
+  const loadGroupParticipantsForPrompt = async (params: {
+    memoryRoot: string;
+    groupId: string;
+    ownerMetadata: ClawChatPromptMetadata | null;
+  }): Promise<ClawChatGroupParticipantPrompt[]> => {
+    const groupFile = await readClawChatMemoryFile(params.memoryRoot, {
+      targetType: "group",
+      targetId: params.groupId,
+    });
+    const participantIds = (groupFile.metadata.participant_ids ?? "")
+      .split(",")
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0);
+    const agentOwnerId = params.ownerMetadata?.agent_owner_id ?? account.ownerUserId;
+    const groupOwnerId = groupFile.metadata.group_owner_id;
+    const participants: ClawChatGroupParticipantPrompt[] = [];
+    for (const userId of participantIds) {
+      let metadata: ClawChatPromptMetadata | null = null;
+      try {
+        const file = await readClawChatMemoryFile(params.memoryRoot, {
+          targetType: "user",
+          targetId: userId,
+        });
+        metadata = file.exists ? file.metadata : null;
+      } catch {
+        metadata = null;
+      }
+      const isAgentOwner = Boolean(agentOwnerId && userId === agentOwnerId);
+      const isGroupOwner = Boolean(groupOwnerId && userId === groupOwnerId);
+      const name = isAgentOwner
+        ? params.ownerMetadata?.agent_owner_nickname ?? metadata?.nickname ?? userId
+        : userId === account.userId
+          ? params.ownerMetadata?.agent_nickname ?? metadata?.nickname ?? userId
+          : isGroupOwner
+            ? groupFile.metadata.group_owner_nickname ?? metadata?.nickname ?? userId
+            : metadata?.nickname ?? userId;
+      const profileType = metadata?.profile_type ?? (userId === account.userId ? "agent" : "user");
+      participants.push({ id: userId, name, profileType, isAgentOwner, isGroupOwner });
+    }
+    return participants;
+  };
+
+  const buildPromptForTurn = async (turn: IngestTurnParams, memoryRoot: string): Promise<string> => {
+    const senderRelation = resolveSenderRelation({
+      senderId: turn.senderId,
+      accountUserId: account.userId,
+      accountOwnerUserId: account.ownerUserId,
+      senderProfileType: turn.senderProfileType,
+    });
+    const promptChatType = turn.peer.kind === "group" ? "group" : "dm";
+    const promptMetadata = await loadClawChatPromptMetadata({
+      memoryRoot,
+      turn: {
+        chatType: promptChatType,
+        senderId: turn.senderId,
+        senderIsOwner: senderRelation === "owner",
+        groupId: turn.peer.kind === "group" ? turn.peer.id : null,
+      },
+      log: { error: (message) => log?.error?.(`[${accountId}] ${message}`) },
+    });
+    const metadataSenderProfileType = promptMetadata.userMetadata?.profile_type ?? null;
+    const promptSenderProfileType = metadataSenderProfileType ?? turn.senderProfileType ?? (
+      senderRelation === "self_agent" || senderRelation === "peer_agent" ? "agent" : "user"
+    );
+    const groupParticipants = turn.peer.kind === "group"
+      ? await loadGroupParticipantsForPrompt({
+          memoryRoot,
+          groupId: turn.peer.id,
+          ownerMetadata: promptMetadata.ownerMetadata,
+        })
+      : [];
+    return renderClawChatProfilePrompt({
+      basePrompt: turn.peer.kind === "group" ? getClawChatGroupPrompt() : getClawChatUserPrompt(),
+      ...promptMetadata,
+      ownerIdFallback: account.ownerUserId,
+      groupParticipants,
+      turn: {
+        chatType: promptChatType,
+        chatId: turn.peer.id,
+        senderId: turn.senderId,
+        senderName: promptMetadata.userMetadata?.nickname ?? (turn.senderNickName || turn.senderId),
+        senderProfileType: promptSenderProfileType,
+        senderIsOwner: senderRelation === "owner",
+        groupId: turn.peer.kind === "group" ? turn.peer.id : null,
+        coalescedGroupBatch: turn.coalescedGroupBatch === true,
+        wasMentioned: turn.wasMentioned,
+        mentionedUserIds: turn.mentionedUserIds,
+        mentionedUsers: turn.mentionedUsers,
+        messageText: turn.rawBody,
+      },
+    });
+  };
+
+  const resolveSenderNickNameForTurn = (turn: IngestTurnParams): string => {
+    if (turn.senderNickName && turn.senderNickName !== turn.senderId) return turn.senderNickName;
+    return turn.senderNickName || turn.senderId;
+  };
+
+  const resolveSenderBatchIdentityForTurn = (turn: IngestTurnParams): {
+    senderRelation: NonNullable<IngestTurnParams["senderRelation"]>;
+    senderProfileType: string;
+    senderIsOwner: boolean;
+    senderIsGroupOwner: boolean;
+  } => {
+    const senderRelation = resolveSenderRelation({
+      senderId: turn.senderId,
+      accountUserId: account.userId,
+      accountOwnerUserId: account.ownerUserId,
+      senderProfileType: turn.senderProfileType,
+    });
+    return {
+      senderRelation,
+      senderProfileType: turn.senderProfileType ??
+        (senderRelation === "self_agent" || senderRelation === "peer_agent" ? "agent" : "user"),
+      senderIsOwner: senderRelation === "owner",
+      senderIsGroupOwner: turn.senderIsGroupOwner ?? false,
+    };
+  };
+
+  const claimInboundTurn = (turn: IngestTurnParams): "claimed" | "skipped" => {
+    const env = turn.envelope;
+    if (store?.claimMessageOnce) {
+      const claimed = recordConnection("message claim", () =>
+        store.claimMessageOnce?.({
+          platform: "openclaw",
+          accountId,
+          kind: "message",
+          direction: "inbound",
+          eventType: String(env.event),
+          traceId: turn.traceId,
+          chatId: turn.peer.id,
+          messageId: turn.messageId,
+          text: turn.rawBody,
+          raw: env,
+        }),
+      );
+      if (claimed === false) {
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw skip duplicate stored msg=${turn.messageId}`,
+        );
+        return "skipped";
+      }
+    }
+    return "claimed";
+  };
+
+  const dispatchTurnToAgent = async (turn: IngestTurnParams): Promise<IngestTurnResult> => {
+    const rt = runtime.channel;
+    const storePath = rt.session.resolveStorePath(cfg.session?.store);
+    const routeCfg = withClawChatSessionScope(cfg);
+    const route = rt.routing.resolveAgentRoute({
+      cfg: routeCfg,
+      channel: CHANNEL_ID,
+      accountId,
+      peer: turn.peer,
+    });
+    const memoryRoot = resolveClawChatMemoryRoot(runtime, cfg, route.agentId);
+    const body = rt.reply.formatAgentEnvelope({
+      channel: "Clawling Chat",
+      from: formatConversationSubject(turn.peer),
+      body: turn.rawBody,
+      timestamp: turn.timestamp,
+      ...rt.reply.resolveEnvelopeFormatOptions(cfg),
+    });
+    try {
+      await syncMessagePathProfiles(turn, memoryRoot);
+    } catch (err) {
+      log?.error?.(
+        `[${accountId}] clawchat-plugin-openclaw message metadata refresh failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    const conversationTarget = `${CHANNEL_ID}:${formatConversationSubject(turn.peer)}`;
+    const turnPrompt = await buildPromptForTurn(turn, memoryRoot);
+    const ctxPayload = resolveChannelContextBuilder(rt)({
+      channel: CHANNEL_ID,
+      accountId: route.accountId ?? accountId,
+      provider: CHANNEL_ID,
+      surface: CHANNEL_ID,
+      messageId: turn.messageId,
+      messageIdFull: turn.messageId,
+      timestamp: turn.timestamp,
+      from: conversationTarget,
+      sender: {
+        id: turn.senderId,
+        name: turn.senderNickName || turn.senderId,
+        displayLabel: turn.senderNickName || turn.senderId,
+      },
+      conversation: {
+        kind: turn.peer.kind,
+        id: turn.peer.id,
+        label: formatConversationSubject(turn.peer),
+        routePeer: turn.peer,
+      },
+      route: {
+        agentId: route.agentId,
+        accountId: route.accountId ?? accountId,
+        routeSessionKey: route.sessionKey,
+      },
+      reply: {
+        to: `${CHANNEL_ID}:${account.userId}`,
+        originatingTo: conversationTarget,
+      },
+      message: {
+        body,
+        rawBody: turn.rawBody,
+        bodyForAgent: turn.rawBody,
+        commandBody: turn.rawBody,
+        envelopeFrom: conversationTarget,
+      },
+      access: {
+        mentions: {
+          canDetectMention: true,
+          wasMentioned: turn.wasMentioned,
+          hasAnyMention: turn.mentionedUserIds.length > 0,
+        },
+      },
+      ...(memoryRoot ? { extra: { memoryRoot } } : {}),
+      ...(turn.peer.kind === "group"
+        ? { supplemental: { groupSystemPrompt: turnPrompt } }
+        : {}),
+    }) as MutableOpenClawReplyContext;
+    if (memoryRoot) {
+      (ctxPayload as Record<string, unknown>).memoryRoot = memoryRoot;
+    }
+    if (turn.mentionedUserIds.length > 0) {
+      (ctxPayload as Record<string, unknown>).MentionedUserIds = turn.mentionedUserIds;
+    }
+    // Fetch any inbound media attachments and populate MediaPath/MediaPaths in context.
+    const inboundPaths =
+      turn.mediaItems.length > 0
+        ? await fetchInboundMedia(turn.mediaItems, {
+            runtime,
+            log,
+            maxBytes: 20 * 1024 * 1024,
+          })
+        : [];
+    if (inboundPaths.length > 0) {
+      (ctxPayload as Record<string, unknown>).MediaPath = inboundPaths[0];
+      (ctxPayload as Record<string, unknown>).MediaPaths = inboundPaths;
+    }
+
+    const resolvedSessionKey = optionalString(ctxPayload.SessionKey) ?? route.sessionKey;
+
+    openclawLlmContextDebug.writeSnapshot({
+      visibility: "injected_only",
+      trace: {
+        traceId: turn.traceId,
+        messageId: turn.messageId,
+        chatId: turn.peer.id,
+        chatType: turn.peer.kind,
+        senderId: turn.senderId,
+        sessionKey: resolvedSessionKey,
+      },
+      input: {
+        injectedPrompt: turnPrompt,
+        eventText: turn.rawBody,
+      },
+    });
+
+    clearClawChatPromptInjectionForSession(resolvedSessionKey);
+    const stagedDirectPrompt = turn.peer.kind !== "group";
+    if (stagedDirectPrompt) {
+      stageClawChatPromptInjection({
+        sessionKey: resolvedSessionKey,
+        prompt: turnPrompt,
+      });
+    }
+
+    try {
+      try {
+        await rt.session.recordInboundSession({
+          storePath,
+          sessionKey: resolvedSessionKey,
+          ctx: ctxPayload,
+          onRecordError: (err) => {
+            log?.error?.(
+              `[${accountId}] clawchat-plugin-openclaw failed to record inbound session: ${String(err)}`,
+            );
+          },
+        });
+      } catch (err) {
+        log?.error?.(
+          `[${accountId}] clawchat-plugin-openclaw failed to record inbound session: ${String(err)}`,
+        );
+      }
+
+      const replyCtx = turn.replyCtx;
+      const terminalSendScopeId = `${account.accountId}\0${turn.peer.id}\0${turn.messageId}`;
+      const { dispatcher, replyOptions, markDispatchIdle } =
+        createOpenclawClawlingReplyDispatcher({
+          cfg,
+          runtime,
+          account,
+          client,
+          target: { chatId: turn.peer.id, chatType: turn.peer.kind },
+          ...(replyCtx ? { replyCtx } : {}),
+          inboundMessageId: turn.messageId,
+          terminalSendScopeId,
+          inboundForFinalReply: {
+            chatId: turn.peer.id,
+            senderId: turn.senderId,
+            senderNickName: turn.senderNickName || turn.senderId,
+            bodyText: turn.rawBody,
+          },
+          store: store
+            ? {
+                insertMessage: (input) => store.insertMessage?.(input) ?? null,
+                claimMessageOnce: (input) => store.claimMessageOnce?.(input) ?? null,
+                markMessageAcknowledged: (input) => store.markMessageAcknowledged?.(input) ?? null,
+                updateMessageByIdentity: (input) => store.updateMessageByIdentity?.(input),
+              }
+            : null,
+          log,
+        });
+
+      const agentsConfigured = Object.keys((cfg as { agents?: Record<string, unknown> }).agents ?? {});
+      log?.info?.(
+        `[${accountId}] clawchat-plugin-openclaw dispatching reply msg=${turn.messageId} session=${resolvedSessionKey} agent=${route.agentId} agentsConfigured=[${agentsConfigured.join(",")}]`,
+      );
+
+      try {
+        const dispatchResult = await rt.reply.withReplyDispatcher({
+          dispatcher,
+          onSettled: () => markDispatchIdle(),
+          run: () =>
+            runWithTerminalClawChatSendScope(terminalSendScopeId, () =>
+              rt.reply.dispatchReplyFromConfig({ ctx: ctxPayload, cfg, dispatcher, replyOptions }),
+            ),
+        });
+        const counts = (dispatchResult as { counts?: Record<string, number> } | undefined)?.counts ?? {};
+        const queuedFinal = Boolean(
+          (dispatchResult as { queuedFinal?: boolean } | undefined)?.queuedFinal,
+        );
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw dispatch complete msg=${turn.messageId} queuedFinal=${queuedFinal} counts=${JSON.stringify(counts)}`,
+        );
+        if (!queuedFinal && Object.values(counts).every((n) => !n)) {
+          log?.info?.(
+            `[${accountId}] clawchat-plugin-openclaw NO reply was produced (no final / block / tool dispatched). ` +
+              `Likely causes: agent='${route.agentId}' not configured in cfg.agents (configured: [${agentsConfigured.join(",")}]); ` +
+              `or send-policy denied; or a plugin claimed the binding.`,
+          );
+        }
+        return "submitted";
+      } catch (err) {
+        log?.error?.(
+          `[${accountId}] clawchat-plugin-openclaw dispatch failed msg=${turn.messageId}: ${String(err)}`,
+        );
+        return "failed";
+      }
+    } finally {
+      if (stagedDirectPrompt) {
+        clearClawChatPromptInjectionForSession(resolvedSessionKey);
+      }
+    }
+  };
+
+  const groupCoalescer = createGroupMessageCoalescer<GroupIngestTurnParams>({
+    idleMs: 10_000,
+    maxWaitMs: 30_000,
+    dispatch: async (turn) => {
+      await dispatchTurnToAgent(turn);
+    },
+    onError: (err) => {
+      log?.error?.(
+        `[${accountId}] clawchat-plugin-openclaw coalesced group dispatch failed: ${String(err)}`,
+      );
+    },
+    onDrop: (chatId, count) => {
+      log?.info?.(
+        `[${accountId}] clawchat-plugin-openclaw dropped pending group batch chat_id=${chatId} count=${count} reason=shutdown`,
+      );
+    },
+  });
+
+  const ingestTurn = async (rawTurn: IngestTurnParams): Promise<IngestTurnResult> => {
+    const senderBatchIdentity = rawTurn.peer.kind === "group"
+      ? resolveSenderBatchIdentityForTurn(rawTurn)
+      : {};
+    const turn: IngestTurnParams = {
+      ...rawTurn,
+      senderNickName: resolveSenderNickNameForTurn(rawTurn),
+      ...senderBatchIdentity,
+    };
+    const claimed = claimInboundTurn(turn);
+    if (claimed === "skipped") return "skipped";
+    if (turn.peer.kind === "group") {
+      if (isKnownOpenClawGroupSlashCommand(turn.rawBody, cfg)) {
+        const commandMode = effectiveGroupCommandMode(account, turn.peer.id);
+        const commandAllowed = commandMode === "all"
+          || (commandMode === "owner" && turn.senderIsOwner === true);
+        if (!commandAllowed) {
+          log?.info?.(
+            `[${accountId}] clawchat-plugin-openclaw group command dropped chat_id=${turn.peer.id} msg=${turn.messageId} mode=${commandMode} owner=${turn.senderIsOwner === true}`,
+          );
+          return "skipped";
+        }
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw dispatching group command chat_id=${turn.peer.id} msg=${turn.messageId} mode=${commandMode}`,
+        );
+        return dispatchTurnToAgent(turn);
+      }
+      if (turn.wasMentioned) {
+        groupCoalescer.enqueue(turn as GroupIngestTurnParams);
+        groupCoalescer.flushNow(turn.peer.id);
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw dispatching mentioned group batch chat_id=${turn.peer.id} msg=${turn.messageId}`,
+        );
+        return "submitted";
+      }
+      groupCoalescer.enqueue(turn as GroupIngestTurnParams);
+      log?.info?.(
+        `[${accountId}] clawchat-plugin-openclaw queued group batch chat_id=${turn.peer.id} msg=${turn.messageId}`,
+      );
+      return "submitted";
+    }
+    return dispatchTurnToAgent(turn);
+  };
+
+  const handleInboundEnvelope = async (env: 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}] clawchat-plugin-openclaw 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}] clawchat-plugin-openclaw activation bootstrap failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  };
+
+  client.on("message", (env: Envelope) => {
+    void (async () => {
+      await handleInboundEnvelope(env);
+    })();
+  });
+
+  // `client.connect()` resolves on `hello-ok` or rejects on `hello-fail`
+  // (auth). Transport failures (server unreachable, DNS error, etc.) do
+  // NOT reject this promise — the local client handles them internally and
+  // drives its own exponential-backoff reconnect loop (`initialDelay * 2^attempt`
+  // capped at `maxDelay`, with jitter). So we never throw here on anything
+  // other than auth failure; on auth we tear the account down cleanly and
+  // return without throwing (which would make the gateway supervisor
+  // restart us immediately in a tight loop).
+  try {
+    log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime calling client.connect()`);
+    await client.connect();
+    log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime client.connect() resolved`);
+  } catch (err) {
+    const classified = classifyClawlingClientError(err);
+    setStatus({
+      ...getStatus(),
+      connected: false,
+      configured: classified.kind !== "auth",
+      running: false,
+      lastError: classified.message,
+    });
+    if (classified.kind === "auth") {
+      finishCurrentConnection({
+        state: "auth_failed",
+        error: lastHelloFailReason || classified.message,
+      });
+      logAuthFailure(classified.message);
+      return;
+    }
+    log?.error?.(
+      `[${accountId}] clawchat-plugin-openclaw connect failed (${classified.kind}): ${classified.message}`,
+    );
+    return;
+  }
+  activeClients.set(accountId, client);
+  log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime active client registered`);
+  setStatus({
+    ...getStatus(),
+    connected: true,
+    running: true,
+    lastStartAt: Date.now(),
+  });
+  log?.info?.(`[${accountId}] clawchat-plugin-openclaw connected`);
+
+  await waitUntilAbort(abortSignal, async () => {
+    log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime abort received; closing client`);
+    activeClients.delete(accountId);
+    closingForAbort = true;
+    groupCoalescer.cancelAll();
+    finishCurrentConnection({
+      state: "disconnected",
+      closeCode: 1000,
+      closeReason: "client close",
+    });
+    client.close();
+    setStatus({
+      ...getStatus(),
+      connected: false,
+      running: false,
+      lastStopAt: Date.now(),
+    });
+    log?.info?.(`[${accountId}] clawchat-plugin-openclaw disconnected`);
+  });
+}