openclaw-mochat 2026.2.3

package/src/config-schema.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+
+export const MochatGroupSchema = z
+  .object({
+    requireMention: z.boolean().optional(),
+  })
+  .strict();
+
+export const MochatMentionSchema = z
+  .object({
+    requireInGroups: z.boolean().optional(),
+  })
+  .strict();
+
+const MochatConfigSchemaBase = z
+  .object({
+    name: z.string().optional(),
+    enabled: z.boolean().optional(),
+    baseUrl: z.string().optional(),
+    clawToken: z.string().optional(),
+    agentUserId: z.string().optional(),
+    sessions: z.array(z.string()).optional(),
+    panels: z.array(z.string()).optional(),
+    mention: MochatMentionSchema.optional(),
+    groups: z.record(z.string(), MochatGroupSchema.optional()).optional(),
+    socketUrl: z.string().optional(),
+    socketPath: z.string().optional(),
+    socketDisableMsgpack: z.boolean().optional(),
+    socketReconnectDelayMs: z.number().int().min(0).optional(),
+    socketMaxReconnectDelayMs: z.number().int().min(0).optional(),
+    socketConnectTimeoutMs: z.number().int().min(0).optional(),
+    refreshIntervalMs: z.number().int().min(1000).optional(),
+    watchTimeoutMs: z.number().int().positive().optional(),
+    watchLimit: z.number().int().positive().optional(),
+    retryDelayMs: z.number().int().min(0).optional(),
+    maxRetryAttempts: z.number().int().min(0).optional(),
+    replyDelayMode: z.enum(["off", "non-mention"]).optional(),
+    replyDelayMs: z.number().int().min(0).optional(),
+  })
+  .strict();
+
+export const MochatConfigSchema = MochatConfigSchemaBase.extend({
+  accounts: z.record(z.string(), MochatConfigSchemaBase.optional()).optional(),
+}).strict();
+
+export type MochatConfig = z.infer<typeof MochatConfigSchema>;

package/src/delay-buffer.test.ts

@@ -0,0 +1,81 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  clearDelayedEntries,
+  enqueueDelayedEntry,
+  flushDelayedEntries,
+  type MochatBufferedEntry,
+} from "./delay-buffer.js";
+
+const makeEntry = (rawBody: string, author = "user"): MochatBufferedEntry => ({
+  rawBody,
+  author,
+});
+
+describe("mochat delay buffer", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("flushes after delay and merges entries", async () => {
+    const key = "session:one";
+    const onFlush = vi.fn(async () => {});
+
+    await enqueueDelayedEntry({
+      key,
+      entry: makeEntry("first"),
+      delayMs: 1000,
+      onFlush,
+    });
+
+    await vi.advanceTimersByTimeAsync(500);
+
+    await enqueueDelayedEntry({
+      key,
+      entry: makeEntry("second", "user2"),
+      delayMs: 1000,
+      onFlush,
+    });
+
+    await vi.advanceTimersByTimeAsync(999);
+    expect(onFlush).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1);
+    expect(onFlush).toHaveBeenCalledTimes(1);
+    const entries = onFlush.mock.calls[0]?.[0] as MochatBufferedEntry[];
+    expect(entries.map((entry) => entry.rawBody)).toEqual(["first", "second"]);
+
+    clearDelayedEntries(key);
+  });
+
+  it("flushes immediately on mention and includes buffered entries", async () => {
+    const key = "session:two";
+    const onFlush = vi.fn(async () => {});
+
+    await enqueueDelayedEntry({
+      key,
+      entry: makeEntry("buffered"),
+      delayMs: 1000,
+      onFlush,
+    });
+
+    await flushDelayedEntries({
+      key,
+      entry: makeEntry("@bot", "user3"),
+      reason: "mention",
+      onFlush,
+    });
+
+    expect(onFlush).toHaveBeenCalledTimes(1);
+    const entries = onFlush.mock.calls[0]?.[0] as MochatBufferedEntry[];
+    expect(entries.map((entry) => entry.rawBody)).toEqual(["buffered", "@bot"]);
+
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(onFlush).toHaveBeenCalledTimes(1);
+
+    clearDelayedEntries(key);
+  });
+});

package/src/delay-buffer.ts

@@ -0,0 +1,123 @@
+export type MochatBufferedEntry = {
+  rawBody: string;
+  author: string;
+  senderName?: string;
+  senderUsername?: string;
+  timestamp?: number;
+  messageId?: string;
+  groupId?: string;
+};
+
+export type MochatDelayFlushReason = "mention" | "timer";
+
+export type MochatDelayFlushHandler = (
+  entries: MochatBufferedEntry[],
+  reason: MochatDelayFlushReason,
+) => Promise<void>;
+
+type BufferState = {
+  entries: MochatBufferedEntry[];
+  timer: NodeJS.Timeout | null;
+  queue: Promise<void>;
+  onFlush?: MochatDelayFlushHandler;
+};
+
+const buffers = new Map<string, BufferState>();
+
+function getState(key: string): BufferState {
+  const existing = buffers.get(key);
+  if (existing) {
+    return existing;
+  }
+  const created: BufferState = {
+    entries: [],
+    timer: null,
+    queue: Promise.resolve(),
+  };
+  buffers.set(key, created);
+  return created;
+}
+
+function enqueueTask(key: string, task: () => Promise<void>) {
+  const state = getState(key);
+  const previous = state.queue;
+  const next = previous.then(task, task);
+  state.queue = next.catch(() => undefined);
+  return next;
+}
+
+function clearTimer(state: BufferState) {
+  if (state.timer) {
+    clearTimeout(state.timer);
+    state.timer = null;
+  }
+}
+
+async function flushInternal(
+  key: string,
+  reason: MochatDelayFlushReason,
+  onFlush?: MochatDelayFlushHandler,
+) {
+  const state = buffers.get(key);
+  if (!state) {
+    return;
+  }
+  clearTimer(state);
+  if (onFlush) {
+    state.onFlush = onFlush;
+  }
+  const entries = state.entries.slice();
+  state.entries.length = 0;
+  if (entries.length === 0) {
+    return;
+  }
+  const handler = state.onFlush;
+  if (!handler) {
+    return;
+  }
+  await handler(entries, reason);
+}
+
+export async function enqueueDelayedEntry(params: {
+  key: string;
+  entry: MochatBufferedEntry;
+  delayMs: number;
+  onFlush: MochatDelayFlushHandler;
+}) {
+  const { key, entry, delayMs, onFlush } = params;
+  await enqueueTask(key, async () => {
+    const state = getState(key);
+    state.onFlush = onFlush;
+    state.entries.push(entry);
+    clearTimer(state);
+    state.timer = setTimeout(() => {
+      void enqueueTask(key, () => flushInternal(key, "timer"));
+    }, Math.max(0, delayMs));
+  });
+}
+
+export async function flushDelayedEntries(params: {
+  key: string;
+  entry?: MochatBufferedEntry;
+  reason: MochatDelayFlushReason;
+  onFlush: MochatDelayFlushHandler;
+}) {
+  const { key, entry, reason, onFlush } = params;
+  await enqueueTask(key, async () => {
+    const state = getState(key);
+    state.onFlush = onFlush;
+    if (entry) {
+      state.entries.push(entry);
+    }
+    await flushInternal(key, reason, onFlush);
+  });
+}
+
+export function clearDelayedEntries(key: string) {
+  const state = buffers.get(key);
+  if (!state) {
+    return;
+  }
+  clearTimer(state);
+  state.entries.length = 0;
+}

package/src/event-store.ts

@@ -0,0 +1,56 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getMochatRuntime } from "./runtime.js";
+
+type PanelEventRecord = {
+  ts: string;
+  accountId: string;
+  eventName: string;
+  payload: unknown;
+};
+
+const queues = new Map<string, Promise<void>>();
+
+function resolveEventFilePath(timestamp: Date): string {
+  const runtime = getMochatRuntime();
+  const stateDir = runtime.state.resolveStateDir();
+  const dateKey = timestamp.toISOString().slice(0, 10);
+  return path.join(stateDir, "mochat", "events", `${dateKey}.jsonl`);
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value, (_key, val) => (typeof val === "bigint" ? val.toString() : val));
+  } catch {
+    return JSON.stringify({ value: String(value), note: "non-serializable" });
+  }
+}
+
+async function appendLine(filePath: string, line: string) {
+  const previous = queues.get(filePath) ?? Promise.resolve();
+  const next = previous
+    .then(async () => {
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+      await fs.appendFile(filePath, line, "utf8");
+    })
+    .catch(() => undefined);
+  queues.set(filePath, next);
+  await next;
+}
+
+export async function recordPanelEvent(params: {
+  accountId: string;
+  eventName: string;
+  payload: unknown;
+}) {
+  const timestamp = new Date();
+  const filePath = resolveEventFilePath(timestamp);
+  const record: PanelEventRecord = {
+    ts: timestamp.toISOString(),
+    accountId: params.accountId,
+    eventName: params.eventName,
+    payload: params.payload,
+  };
+  const line = `${safeStringify(record)}\n`;
+  await appendLine(filePath, line);
+}

package/src/inbound.ts

@@ -0,0 +1,402 @@
+import type { ChannelLogSink, OpenClawConfig } from "openclaw/plugin-sdk";
+import { sendPanelMessage, sendSessionMessage, type MochatEvent } from "./api.js";
+import type { ResolvedMochatAccount } from "./accounts.js";
+import {
+  enqueueDelayedEntry,
+  flushDelayedEntries,
+  type MochatBufferedEntry,
+} from "./delay-buffer.js";
+import { getMochatRuntime } from "./runtime.js";
+
+export type MochatStatusSink = (patch: {
+  lastInboundAt?: number;
+  lastOutboundAt?: number;
+  lastError?: string | null;
+}) => void;
+
+function normalizeContent(content: unknown): string {
+  if (typeof content === "string") {
+    return content;
+  }
+  if (content === null || content === undefined) {
+    return "";
+  }
+  try {
+    return JSON.stringify(content);
+  } catch {
+    return String(content);
+  }
+}
+
+function parseTimestamp(value?: string): number | undefined {
+  if (!value) {
+    return undefined;
+  }
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function extractMentionIds(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const ids: string[] = [];
+  for (const entry of value) {
+    if (typeof entry === "string" && entry.trim()) {
+      ids.push(entry.trim());
+      continue;
+    }
+    if (entry && typeof entry === "object") {
+      const obj = entry as Record<string, unknown>;
+      const candidate =
+        (typeof obj.id === "string" ? obj.id : undefined) ??
+        (typeof obj.userId === "string" ? obj.userId : undefined) ??
+        (typeof obj._id === "string" ? obj._id : undefined);
+      if (candidate) {
+        ids.push(candidate);
+      }
+    }
+  }
+  return ids;
+}
+
+function resolveWasMentioned(payload: MochatEvent["payload"], agentUserId?: string): boolean {
+  const meta = payload?.meta as Record<string, unknown> | undefined;
+  if (meta) {
+    const directBool =
+      (typeof meta.mentioned === "boolean" && meta.mentioned) ||
+      (typeof meta.wasMentioned === "boolean" && meta.wasMentioned);
+    if (directBool) {
+      return true;
+    }
+
+    const mentionSources = [
+      meta.mentions,
+      meta.mentionIds,
+      meta.mentionedUserIds,
+      meta.mentionedUsers,
+    ];
+    for (const source of mentionSources) {
+      const ids = extractMentionIds(source);
+      if (agentUserId && ids.includes(agentUserId)) {
+        return true;
+      }
+    }
+  }
+
+  if (!agentUserId) {
+    return false;
+  }
+  const content = typeof payload?.content === "string" ? payload.content : "";
+  if (!content) {
+    return false;
+  }
+  return content.includes(`<@${agentUserId}>`) || content.includes(`@${agentUserId}`);
+}
+
+function resolveRequireMention(params: {
+  account: ResolvedMochatAccount;
+  sessionId: string;
+  groupId?: string;
+}): boolean {
+  const { account, sessionId, groupId } = params;
+  const groups = account.config.groups;
+  if (groups) {
+    if (groupId && typeof groups[groupId]?.requireMention === "boolean") {
+      return groups[groupId]?.requireMention ?? false;
+    }
+    const direct = groups[sessionId]?.requireMention;
+    if (typeof direct === "boolean") {
+      return direct;
+    }
+    const wildcard = groups["*"]?.requireMention;
+    if (typeof wildcard === "boolean") {
+      return wildcard;
+    }
+  }
+  return Boolean(account.config.mention?.requireInGroups);
+}
+
+function resolveSenderLabel(entry: MochatBufferedEntry): string {
+  return (
+    (entry.senderName && entry.senderName.trim()) ||
+    (entry.senderUsername && entry.senderUsername.trim()) ||
+    entry.author
+  );
+}
+
+function buildBufferedBody(entries: MochatBufferedEntry[], isGroup: boolean): string {
+  if (entries.length === 1) {
+    return entries[0]?.rawBody ?? "";
+  }
+  const lines: string[] = [];
+  for (const entry of entries) {
+    const body = entry.rawBody;
+    if (!body) {
+      continue;
+    }
+    if (isGroup) {
+      const label = resolveSenderLabel(entry);
+      if (label) {
+        lines.push(`${label}: ${body}`);
+        continue;
+      }
+    }
+    lines.push(body);
+  }
+  return lines.join("\n").trim();
+}
+
+async function dispatchBufferedEntries(params: {
+  account: ResolvedMochatAccount;
+  sessionId: string;
+  targetKind: "session" | "panel";
+  entries: MochatBufferedEntry[];
+  isGroup: boolean;
+  wasMentioned: boolean;
+  log?: ChannelLogSink;
+  statusSink?: MochatStatusSink;
+  markInboundAt?: boolean;
+}) {
+  const {
+    account,
+    sessionId,
+    targetKind,
+    entries,
+    isGroup,
+    wasMentioned,
+    log,
+    statusSink,
+  } = params;
+  if (entries.length === 0) {
+    return;
+  }
+  const rawBody = buildBufferedBody(entries, isGroup);
+  const lastEntry = entries[entries.length - 1];
+
+  const core = getMochatRuntime();
+  const config = core.config.loadConfig() as OpenClawConfig;
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: config,
+    channel: "mochat",
+    accountId: account.accountId,
+    peer: {
+      kind: isGroup ? "group" : "dm",
+      id: sessionId,
+    },
+  });
+
+  const fromLabel = isGroup
+    ? `group:${lastEntry.groupId ?? sessionId}`
+    : `user:${lastEntry.author}`;
+  const storePath = core.channel.session.resolveStorePath(config.session?.store, {
+    agentId: route.agentId,
+  });
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config);
+  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+  const body = core.channel.reply.formatAgentEnvelope({
+    channel: "Mochat",
+    from: fromLabel,
+    timestamp: lastEntry.timestamp,
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: rawBody,
+  });
+
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: body,
+    RawBody: rawBody,
+    CommandBody: rawBody,
+    From: `mochat:${lastEntry.author}`,
+    To: `mochat:${sessionId}`,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: isGroup ? "group" : "direct",
+    ConversationLabel: fromLabel,
+    SenderName: lastEntry.senderName || undefined,
+    SenderUsername: lastEntry.senderUsername || undefined,
+    SenderId: lastEntry.author,
+    WasMentioned: isGroup ? wasMentioned : undefined,
+    MessageSid: lastEntry.messageId,
+    Timestamp: lastEntry.timestamp,
+    GroupSubject: isGroup ? String(lastEntry.groupId ?? sessionId) : undefined,
+    Provider: "mochat",
+    Surface: "mochat",
+    OriginatingChannel: "mochat",
+    OriginatingTo: `mochat:${sessionId}`,
+  });
+
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (err) => {
+      log?.error?.(`mochat: failed updating session meta: ${String(err)}`);
+    },
+  });
+
+  if (params.markInboundAt !== false) {
+    statusSink?.({ lastInboundAt: Date.now(), lastError: null });
+  }
+
+  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg: config,
+    dispatcherOptions: {
+      deliver: async (payload: {
+        text?: string;
+        mediaUrls?: string[];
+        mediaUrl?: string;
+        replyToId?: string | null;
+      }) => {
+        const contentParts: string[] = [];
+        if (payload.text) {
+          contentParts.push(payload.text);
+        }
+        const mediaUrls = [
+          ...(payload.mediaUrls ?? []),
+          ...(payload.mediaUrl ? [payload.mediaUrl] : []),
+        ].filter(Boolean);
+        if (mediaUrls.length > 0) {
+          contentParts.push(...mediaUrls);
+        }
+        const content = contentParts.join("\n").trim();
+        if (!content) {
+          return;
+        }
+        if (targetKind === "panel") {
+          await sendPanelMessage({
+            baseUrl: account.config.baseUrl,
+            clawToken: account.config.clawToken ?? "",
+            panelId: sessionId,
+            content,
+            replyTo: payload.replyToId ?? null,
+          });
+        } else {
+          await sendSessionMessage({
+            baseUrl: account.config.baseUrl,
+            clawToken: account.config.clawToken ?? "",
+            sessionId,
+            content,
+            replyTo: payload.replyToId ?? null,
+          });
+        }
+        statusSink?.({ lastOutboundAt: Date.now(), lastError: null });
+      },
+      onError: (err, info) => {
+        log?.error?.(`mochat ${info.kind} reply failed: ${String(err)}`);
+      },
+    },
+  });
+}
+
+export async function handleInboundMessage(params: {
+  account: ResolvedMochatAccount;
+  sessionId: string;
+  event: MochatEvent;
+  targetKind?: "session" | "panel";
+  log?: ChannelLogSink;
+  statusSink?: MochatStatusSink;
+}) {
+  const { account, sessionId, event, log, statusSink } = params;
+  const targetKind = params.targetKind ?? "session";
+  const payload = event.payload;
+  if (!payload) {
+    return;
+  }
+  const author = payload.author ? String(payload.author) : "";
+  const authorInfo =
+    payload.authorInfo && typeof payload.authorInfo === "object"
+      ? (payload.authorInfo as {
+          nickname?: string | null;
+          email?: string | null;
+          agentId?: string | null;
+        })
+      : null;
+  const senderName =
+    (authorInfo?.nickname && authorInfo.nickname.trim()) ||
+    (authorInfo?.email && authorInfo.email.trim()) ||
+    "";
+  if (!author) {
+    return;
+  }
+  const agentUserId = account.config.agentUserId;
+  if (agentUserId && author === agentUserId) {
+    return;
+  }
+
+  const isGroup = Boolean(payload.groupId);
+  const wasMentioned = resolveWasMentioned(payload, agentUserId);
+  const requireMention =
+    targetKind === "panel" &&
+    isGroup &&
+    resolveRequireMention({ account, sessionId, groupId: String(payload.groupId ?? "") });
+  const replyDelayMode = account.config.replyDelayMode;
+  const useDelay = targetKind === "panel" && replyDelayMode === "non-mention";
+  if (requireMention && !wasMentioned && !useDelay) {
+    return;
+  }
+
+  const rawBody = normalizeContent(payload.content);
+  const timestamp = parseTimestamp(event.timestamp);
+  const entry: MochatBufferedEntry = {
+    rawBody,
+    author,
+    senderName: senderName || undefined,
+    senderUsername: authorInfo?.agentId || undefined,
+    timestamp,
+    messageId: payload.messageId ? String(payload.messageId) : undefined,
+    groupId: isGroup ? String(payload.groupId ?? sessionId) : undefined,
+  };
+
+  if (useDelay) {
+    statusSink?.({ lastInboundAt: Date.now(), lastError: null });
+    const delayKey = `${account.accountId}:${targetKind}:${sessionId}`;
+    const delayMs = account.config.replyDelayMs;
+    const onFlush = async (entries: MochatBufferedEntry[], reason: "mention" | "timer") => {
+      await dispatchBufferedEntries({
+        account,
+        sessionId,
+        targetKind,
+        entries,
+        isGroup,
+        wasMentioned: reason === "mention",
+        log,
+        statusSink,
+        markInboundAt: false,
+      });
+    };
+
+    if (wasMentioned) {
+      await flushDelayedEntries({
+        key: delayKey,
+        entry,
+        reason: "mention",
+        onFlush,
+      });
+    } else {
+      await enqueueDelayedEntry({
+        key: delayKey,
+        entry,
+        delayMs,
+        onFlush,
+      });
+    }
+    return;
+  }
+
+  await dispatchBufferedEntries({
+    account,
+    sessionId,
+    targetKind,
+    entries: [entry],
+    isGroup,
+    wasMentioned,
+    log,
+    statusSink,
+  });
+}