@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/inbound.ts

@@ -0,0 +1,278 @@
+import {
+  EVENT,
+  type ChatType,
+  type Envelope,
+} from "./protocol-types.ts";
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/core";
+import { effectiveGroupMode, type ResolvedOpenclawClawlingAccount } from "./config.ts";
+import type { MediaItem } from "./media-runtime.ts";
+import { extractMediaFragments, fragmentsToText, type MentionedUser } from "./message-mapper.ts";
+import { hasRenderableText, isInboundMessagePayload } from "./protocol.ts";
+
+export interface IngestTurnParams {
+  channel: "clawchat-plugin-openclaw";
+  accountId: string;
+  /**
+   * The conversational subject. `peer.id` mirrors the inbound envelope's
+   * `chat_id` (new-protocol routing key); `peer.kind` is `chat_type`
+   * (direct / group).
+   */
+  peer: { kind: "direct" | "group"; id: string };
+  senderId: string;
+  senderNickName: string;
+  senderRelation?: "self_agent" | "owner" | "peer_agent" | "peer_user";
+  senderProfileType?: string | null;
+  senderIsOwner?: boolean;
+  senderIsGroupOwner?: boolean;
+  rawBody: string;
+  messageId: string;
+  traceId: string;
+  timestamp: number;
+  wasMentioned: boolean;
+  mentionedUserIds: string[];
+  mentionedUsers: MentionedUser[];
+  coalescedGroupBatch?: boolean;
+  mediaItems: MediaItem[];
+  replyCtx?: {
+    replyToMessageId: string;
+    replyPreviewChatId: string;
+    replyPreviewSenderId: string;
+    replyPreviewNickName: string;
+    replyPreviewText: string;
+  };
+  cfg: OpenClawConfig;
+  runtime: PluginRuntime;
+  account: ResolvedOpenclawClawlingAccount;
+  envelope: Envelope<unknown>;
+}
+
+export interface DispatchInboundParams {
+  envelope: Envelope<unknown>;
+  cfg: OpenClawConfig;
+  runtime: PluginRuntime;
+  account: ResolvedOpenclawClawlingAccount;
+  ingest: (params: IngestTurnParams) => Promise<void>;
+  log?: { info?: (m: string) => void; error?: (m: string) => void };
+}
+
+type SenderLike = {
+  id?: unknown;
+  nick_name?: unknown;
+  type?: unknown;
+};
+
+function normalizeSender(sender: unknown): { id: string; nickName: string; profileType: string | null } | null {
+  if (!sender || typeof sender !== "object") return null;
+  const s = sender as SenderLike;
+  const id = typeof s.id === "string" ? s.id : "";
+  if (!id) return null;
+  const nickName = typeof s.nick_name === "string" ? s.nick_name : id;
+  const profileType = s.type === "agent" || s.type === "user" ? s.type : null;
+  return { id, nickName, profileType };
+}
+
+function requireChatId(envelope: Envelope<unknown>): string | null {
+  const chatId = (envelope as Envelope<unknown> & { chat_id?: unknown }).chat_id;
+  return typeof chatId === "string" && chatId.trim() ? chatId : null;
+}
+
+function mentionIdFromRecord(record: Record<string, unknown>): string | undefined {
+  const userId = record.user_id ?? record.userId ?? record.id;
+  return typeof userId === "string" && userId.length > 0 ? userId : undefined;
+}
+
+function mentionDisplayFromRecord(record: Record<string, unknown>): string | undefined {
+  const display = record.display ?? record.label ?? record.name ?? record.nick_name ?? record.nickname;
+  return typeof display === "string" && display.trim() ? display.trim().replace(/^@/, "") : undefined;
+}
+
+function extractMentionUsers(fragments: Array<Record<string, unknown>>): MentionedUser[] {
+  return fragments
+    .filter((fragment) => fragment.kind === "mention")
+    .map((fragment) => {
+      const id = mentionIdFromRecord(fragment);
+      if (!id) return null;
+      const display = mentionDisplayFromRecord(fragment);
+      return display ? { id, display } : { id };
+    })
+    .filter((mention): mention is MentionedUser => mention !== null);
+}
+
+function normalizeMentionUsers(mentions: unknown[]): MentionedUser[] {
+  return mentions
+    .map((mention) => {
+      if (typeof mention === "string" && mention.length > 0) return { id: mention };
+      if (mention && typeof mention === "object") {
+        const record = mention as Record<string, unknown>;
+        const id = mentionIdFromRecord(record);
+        if (!id) return null;
+        const display = mentionDisplayFromRecord(record);
+        return display ? { id, display } : { id };
+      }
+      return null;
+    })
+    .filter((mention): mention is MentionedUser => mention !== null);
+}
+
+function mergeMentionUsers(...sources: MentionedUser[][]): MentionedUser[] {
+  const merged = new Map<string, MentionedUser>();
+  for (const source of sources) {
+    for (const mention of source) {
+      const existing = merged.get(mention.id);
+      if (!existing || (!existing.display && mention.display)) {
+        merged.set(mention.id, mention);
+      }
+    }
+  }
+  return Array.from(merged.values());
+}
+
+function mentionedUserIds(mentions: MentionedUser[]): string[] {
+  return mentions.map((mention) => mention.id);
+}
+
+/**
+ * Exported for direct unit testing. Direct chats always count as addressed;
+ * group chats require a mention unless config opts into all group messages.
+ */
+export function detectMention(params: {
+  mentions: unknown[];
+  chatType: "direct" | "group";
+  userId: string;
+}): boolean {
+  if (params.chatType === "direct") return true;
+  return mentionedUserIds(normalizeMentionUsers(params.mentions)).includes(params.userId);
+}
+
+export async function dispatchOpenclawClawlingInbound(
+  params: DispatchInboundParams,
+): Promise<void> {
+  const { envelope, account, log } = params;
+  const isMaterializedMessage = envelope.event === EVENT.MESSAGE_SEND || envelope.event === EVENT.MESSAGE_REPLY;
+  if (!isMaterializedMessage) {
+    log?.info?.(
+      `[${account.accountId}] clawchat-plugin-openclaw skip non-business event=${envelope.event} trace=${envelope.trace_id}`,
+    );
+    return;
+  }
+  if (isMaterializedMessage && !isInboundMessagePayload(envelope.payload)) {
+    log?.info?.(
+      `[${account.accountId}] clawchat-plugin-openclaw skip: invalid payload trace=${envelope.trace_id}`,
+    );
+    return;
+  }
+  const chatId = requireChatId(envelope);
+  if (!chatId) {
+    log?.info?.(
+      `[${account.accountId}] clawchat-plugin-openclaw skip: missing chat_id trace=${envelope.trace_id}`,
+    );
+    return;
+  }
+  const payload = envelope.payload as {
+    message_id: string;
+    message_mode?: string;
+    message?: unknown;
+  };
+  const message = payload.message as {
+    body: { fragments: Array<Record<string, unknown>> };
+    context: {
+      mentions: unknown[];
+      reply: {
+        reply_to_msg_id: string;
+        reply_preview: {
+          id?: string;
+          nick_name?: string;
+          fragments: Array<Record<string, unknown>>;
+        };
+      } | null;
+    };
+  };
+
+  const sender = normalizeSender(envelope.sender);
+  if (!sender) {
+    log?.info?.(
+      `[${account.accountId}] clawchat-plugin-openclaw skip: missing sender trace=${envelope.trace_id}`,
+    );
+    return;
+  }
+  if (account.userId && sender.id === account.userId) {
+    log?.info?.(
+      `[${account.accountId}] clawchat-plugin-openclaw skip self-echo msg=${payload.message_id} user=${sender.id}`,
+    );
+    return;
+  }
+  const chatType: ChatType = envelope.chat_type === "group" ? "group" : "direct";
+  const isGroup = chatType === "group";
+  if (isMaterializedMessage && payload.message_mode !== "normal") {
+    log?.info?.(
+      `[${account.accountId}] clawchat-plugin-openclaw skip non-normal mode=${payload.message_mode}`,
+    );
+    return;
+  }
+  if (!hasRenderableText(message)) {
+    log?.info?.(
+      `[${account.accountId}] clawchat-plugin-openclaw skip empty msg=${payload.message_id}`,
+    );
+    return;
+  }
+  const fragmentMentionUsers = extractMentionUsers(message.body.fragments as Array<Record<string, unknown>>);
+  const contextMentionUsers = normalizeMentionUsers(message.context.mentions);
+  const mentionedUsers = mergeMentionUsers(fragmentMentionUsers, contextMentionUsers);
+  const mentionIds = mentionedUserIds(mentionedUsers);
+  const rawBody = fragmentsToText(message.body.fragments as never, {
+    mentionFallbackIds: mentionIds,
+  });
+  const mediaItems = extractMediaFragments(message.body.fragments as never);
+  const wasMentioned = detectMention({
+    mentions: mentionIds,
+    chatType,
+    userId: account.userId,
+  });
+
+  // Group trigger policy: in "mention" mode we only handle group messages
+  // that @-mention us; "all" listens open and processes every group msg.
+  // Direct chats are unaffected (detectMention returns true).
+  const groupMode = isGroup ? effectiveGroupMode(account, chatId) : account.groupMode;
+  if (isGroup && groupMode === "mention" && !wasMentioned) {
+    log?.info?.(
+      `[${account.accountId}] clawchat-plugin-openclaw skip group (no mention) msg=${payload.message_id}`,
+    );
+    return;
+  }
+
+  log?.info?.(
+    `[${account.accountId}] clawchat-plugin-openclaw inbound event=${envelope.event} msg=${payload.message_id} from=${sender.id} text_len=${rawBody.length} mentioned=${wasMentioned}`,
+  );
+
+  const replyCtx = message.context.reply
+    ? {
+        replyToMessageId: message.context.reply.reply_to_msg_id,
+        replyPreviewChatId: chatId,
+        replyPreviewSenderId: message.context.reply.reply_preview.id ?? "",
+        replyPreviewNickName: message.context.reply.reply_preview.nick_name ?? "",
+        replyPreviewText: fragmentsToText(message.context.reply.reply_preview.fragments as never),
+      }
+    : undefined;
+
+  await params.ingest({
+    channel: "clawchat-plugin-openclaw",
+    accountId: account.accountId,
+    peer: { kind: isGroup ? "group" : "direct", id: chatId },
+    senderId: sender.id,
+    senderNickName: sender.nickName,
+    ...(sender.profileType ? { senderProfileType: sender.profileType } : {}),
+    rawBody,
+    messageId: payload.message_id,
+    traceId: envelope.trace_id,
+    timestamp: envelope.emitted_at,
+    wasMentioned,
+    mentionedUserIds: mentionIds,
+    mentionedUsers,
+    mediaItems,
+    ...(replyCtx ? { replyCtx } : {}),
+    cfg: params.cfg,
+    runtime: params.runtime,
+    account,
+    envelope,
+  });
+}

package/src/llm-context-debug.test.ts

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { createOpenclawLlmContextDebug } from "./llm-context-debug.ts";
+
+const dirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function tempDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-llm-context-"));
+  dirs.push(dir);
+  return dir;
+}
+
+describe("OpenClaw LLM context debug", () => {
+  it("is disabled by default and writes no snapshot", () => {
+    const root = tempDir();
+    const debug = createOpenclawLlmContextDebug({ env: {}, defaultSnapshotRoot: root });
+
+    expect(debug.enabled).toBe(false);
+    expect(debug.writeSnapshot({
+      visibility: "injected_only",
+      trace: { messageId: "m1" },
+      input: { injectedPrompt: "p", eventText: "e" },
+    })).toBeNull();
+    expect(fs.existsSync(path.join(root, "openclaw"))).toBe(false);
+  });
+
+  it("writes a v1 snapshot when enabled", () => {
+    const root = tempDir();
+    const debug = createOpenclawLlmContextDebug({
+      env: {
+        CLAWCHAT_LLM_CONTEXT_DEBUG: "1",
+        CLAWCHAT_LLM_CONTEXT_SNAPSHOT_DIR: root,
+      },
+      defaultSnapshotRoot: root,
+    });
+
+    const filePath = debug.writeSnapshot({
+      visibility: "injected_only",
+      trace: { messageId: "m1", chatType: "dm" },
+      input: { injectedPrompt: "prompt", eventText: "hello" },
+    });
+
+    expect(filePath).toMatch(/openclaw\/runs\/.*\.json$/);
+    const raw = JSON.parse(fs.readFileSync(filePath!, "utf8"));
+    expect(raw.schemaVersion).toBe(1);
+    expect(raw.source).toBe("openclaw");
+    expect(raw.input.injectedPrompt).toBe("prompt");
+  });
+});

package/src/llm-context-debug.ts

@@ -0,0 +1,139 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export type OpenclawLlmContextVisibility =
+  | "full_llm_input"
+  | "host_event"
+  | "host_descriptor"
+  | "injected_only"
+  | "static_only";
+
+export type OpenclawLlmContextSnapshotInput = {
+  visibility: OpenclawLlmContextVisibility;
+  trace: Record<string, unknown>;
+  input: {
+    injectedPrompt?: string;
+    eventText?: string;
+    fullLlmInput?: unknown;
+    sections?: unknown[];
+  };
+  context?: {
+    promptParts?: unknown[];
+    tools?: unknown[];
+    skills?: unknown[];
+  };
+  output?: {
+    rawModelOutput?: string | null;
+    streamChunks?: unknown[];
+    toolCalls?: unknown[];
+    toolResults?: unknown[];
+    finalAssistantText?: string | null;
+    adapterFilteredText?: string | null;
+    outboundClawChatMessage?: unknown;
+    suppressed?: boolean;
+    suppressionReason?: string | null;
+  };
+  warnings?: string[];
+};
+
+export type OpenclawLlmContextDebug = {
+  enabled: boolean;
+  captureFullInput: boolean;
+  captureOutput: boolean;
+  reloadPrompts: boolean;
+  snapshotRoot: string;
+  writeSnapshot(snapshot: OpenclawLlmContextSnapshotInput): string | null;
+};
+
+function envEnabled(value: string | undefined): boolean {
+  return ["1", "true", "yes", "on"].includes(String(value ?? "").trim().toLowerCase());
+}
+
+function safeId(value: unknown): string {
+  const text = String(value ?? "unknown").replace(/[^A-Za-z0-9_.-]+/g, "-");
+  return text.length > 0 ? text.slice(0, 80) : "unknown";
+}
+
+export function createOpenclawLlmContextDebug(params: {
+  env?: Record<string, string | undefined>;
+  defaultSnapshotRoot?: string;
+} = {}): OpenclawLlmContextDebug {
+  const env = params.env ?? process.env;
+  const enabled = envEnabled(env.CLAWCHAT_LLM_CONTEXT_DEBUG);
+  const snapshotRoot = path.resolve(
+    env.CLAWCHAT_LLM_CONTEXT_SNAPSHOT_DIR || params.defaultSnapshotRoot || ".clawchat-llm-context-debug",
+  );
+
+  return {
+    enabled,
+    captureFullInput: envEnabled(env.CLAWCHAT_LLM_CONTEXT_CAPTURE_FULL_INPUT),
+    captureOutput: envEnabled(env.CLAWCHAT_LLM_CONTEXT_CAPTURE_OUTPUT),
+    reloadPrompts: envEnabled(env.CLAWCHAT_LLM_CONTEXT_RELOAD_PROMPTS),
+    snapshotRoot,
+    writeSnapshot(snapshot) {
+      if (!enabled) return null;
+      const createdAt = new Date().toISOString();
+      const targetRoot = path.join(snapshotRoot, "openclaw");
+      const runsRoot = path.join(targetRoot, "runs");
+      fs.mkdirSync(runsRoot, { recursive: true });
+      const messageId = safeId(snapshot.trace.messageId);
+      const traceId = safeId(snapshot.trace.traceId);
+      const filePath = path.join(runsRoot, `${createdAt.replace(/[:.]/g, "-")}-${messageId}-${traceId}.json`);
+      const body = {
+        schemaVersion: 1,
+        source: "openclaw",
+        visibility: snapshot.visibility,
+        createdAt,
+        trace: snapshot.trace,
+        context: {
+          promptParts: snapshot.context?.promptParts ?? [],
+          tools: snapshot.context?.tools ?? [],
+          skills: snapshot.context?.skills ?? [],
+        },
+        input: {
+          injectedPrompt: snapshot.input.injectedPrompt ?? "",
+          eventText: snapshot.input.eventText ?? "",
+          fullLlmInput: snapshot.input.fullLlmInput ?? null,
+          sections: snapshot.input.sections ?? [],
+        },
+        output: {
+          rawModelOutput: snapshot.output?.rawModelOutput ?? null,
+          streamChunks: snapshot.output?.streamChunks ?? [],
+          toolCalls: snapshot.output?.toolCalls ?? [],
+          toolResults: snapshot.output?.toolResults ?? [],
+          finalAssistantText: snapshot.output?.finalAssistantText ?? null,
+          adapterFilteredText: snapshot.output?.adapterFilteredText ?? null,
+          outboundClawChatMessage: snapshot.output?.outboundClawChatMessage ?? null,
+          suppressed: snapshot.output?.suppressed ?? false,
+          suppressionReason: snapshot.output?.suppressionReason ?? null,
+        },
+        warnings: snapshot.warnings ?? [],
+      };
+      const text = `${JSON.stringify(body, null, 2)}\n`;
+      fs.writeFileSync(filePath, text, "utf8");
+      fs.writeFileSync(path.join(targetRoot, "latest.json"), text, "utf8");
+      return filePath;
+    },
+  };
+}
+
+export const openclawLlmContextDebug: OpenclawLlmContextDebug = {
+  get enabled() {
+    return createOpenclawLlmContextDebug().enabled;
+  },
+  get captureFullInput() {
+    return createOpenclawLlmContextDebug().captureFullInput;
+  },
+  get captureOutput() {
+    return createOpenclawLlmContextDebug().captureOutput;
+  },
+  get reloadPrompts() {
+    return createOpenclawLlmContextDebug().reloadPrompts;
+  },
+  get snapshotRoot() {
+    return createOpenclawLlmContextDebug().snapshotRoot;
+  },
+  writeSnapshot(snapshot) {
+    return createOpenclawLlmContextDebug().writeSnapshot(snapshot);
+  },
+};