@openclaw/zalouser 2026.2.25 → 2026.3.2

package/src/monitor.ts

@@ -1,4 +1,3 @@
-import type { ChildProcess } from "node:child_process";
 import type {
   MarkdownTableMode,
   OpenClawConfig,
@@ -6,9 +5,12 @@ import type {
   RuntimeEnv,
 } from "openclaw/plugin-sdk";
 import {
+  createTypingCallbacks,
+  createScopedPairingAccess,
   createReplyPrefixOptions,
   resolveOutboundMediaUrls,
   mergeAllowlist,
+  resolveMentionGatingWithBypass,
   resolveOpenProviderRuntimeGroupPolicy,
   resolveDefaultGroupPolicy,
   resolveSenderCommandAuthorization,
@@ -16,10 +18,26 @@ import {
   summarizeMapping,
   warnMissingProviderGroupPolicyFallbackOnce,
 } from "openclaw/plugin-sdk";
+import {
+  buildZalouserGroupCandidates,
+  findZalouserGroupEntry,
+  isZalouserGroupEntryAllowed,
+} from "./group-policy.js";
+import { formatZalouserMessageSidFull, resolveZalouserMessageSid } from "./message-sid.js";
 import { getZalouserRuntime } from "./runtime.js";
-import { sendMessageZalouser } from "./send.js";
-import type { ResolvedZalouserAccount, ZcaFriend, ZcaGroup, ZcaMessage } from "./types.js";
-import { parseJsonOutput, runZca, runZcaStreaming } from "./zca.js";
+import {
+  sendDeliveredZalouser,
+  sendMessageZalouser,
+  sendSeenZalouser,
+  sendTypingZalouser,
+} from "./send.js";
+import type { ResolvedZalouserAccount, ZaloInboundMessage } from "./types.js";
+import {
+  listZaloFriends,
+  listZaloGroups,
+  resolveZaloGroupContext,
+  startZaloListener,
+} from "./zalo-js.js";
 
 export type ZalouserMonitorOptions = {
   account: ResolvedZalouserAccount;
@@ -61,131 +79,133 @@ function logVerbose(core: ZalouserCoreRuntime, runtime: RuntimeEnv, message: str
   }
 }
 
-function isSenderAllowed(senderId: string, allowFrom: string[]): boolean {
+function isSenderAllowed(senderId: string | undefined, allowFrom: string[]): boolean {
   if (allowFrom.includes("*")) {
     return true;
   }
-  const normalizedSenderId = senderId.toLowerCase();
+  const normalizedSenderId = senderId?.trim().toLowerCase();
+  if (!normalizedSenderId) {
+    return false;
+  }
   return allowFrom.some((entry) => {
     const normalized = entry.toLowerCase().replace(/^(zalouser|zlu):/i, "");
     return normalized === normalizedSenderId;
   });
 }
 
-function normalizeGroupSlug(raw?: string | null): string {
-  const trimmed = raw?.trim().toLowerCase() ?? "";
-  if (!trimmed) {
-    return "";
-  }
-  return trimmed
-    .replace(/^#/, "")
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-}
-
 function isGroupAllowed(params: {
   groupId: string;
   groupName?: string | null;
-  groups: Record<string, { allow?: boolean; enabled?: boolean }>;
+  groups: Record<string, { allow?: boolean; enabled?: boolean; requireMention?: boolean }>;
 }): boolean {
   const groups = params.groups ?? {};
   const keys = Object.keys(groups);
   if (keys.length === 0) {
     return false;
   }
-  const candidates = [
-    params.groupId,
-    `group:${params.groupId}`,
-    params.groupName ?? "",
-    normalizeGroupSlug(params.groupName ?? ""),
-  ].filter(Boolean);
-  for (const candidate of candidates) {
-    const entry = groups[candidate];
-    if (!entry) {
-      continue;
-    }
-    return entry.allow !== false && entry.enabled !== false;
-  }
-  const wildcard = groups["*"];
-  if (wildcard) {
-    return wildcard.allow !== false && wildcard.enabled !== false;
-  }
-  return false;
+  const entry = findZalouserGroupEntry(
+    groups,
+    buildZalouserGroupCandidates({
+      groupId: params.groupId,
+      groupName: params.groupName,
+      includeGroupIdAlias: true,
+      includeWildcard: true,
+    }),
+  );
+  return isZalouserGroupEntryAllowed(entry);
 }
 
-function startZcaListener(
-  runtime: RuntimeEnv,
-  profile: string,
-  onMessage: (msg: ZcaMessage) => void,
-  onError: (err: Error) => void,
-  abortSignal: AbortSignal,
-): ChildProcess {
-  let buffer = "";
-
-  const { proc, promise } = runZcaStreaming(["listen", "-r", "-k"], {
-    profile,
-    onData: (chunk) => {
-      buffer += chunk;
-      const lines = buffer.split("\n");
-      buffer = lines.pop() ?? "";
-      for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed) {
-          continue;
-        }
-        try {
-          const parsed = JSON.parse(trimmed) as ZcaMessage;
-          onMessage(parsed);
-        } catch {
-          // ignore non-JSON lines
-        }
-      }
-    },
-    onError,
-  });
+function resolveGroupRequireMention(params: {
+  groupId: string;
+  groupName?: string | null;
+  groups: Record<string, { allow?: boolean; enabled?: boolean; requireMention?: boolean }>;
+}): boolean {
+  const entry = findZalouserGroupEntry(
+    params.groups ?? {},
+    buildZalouserGroupCandidates({
+      groupId: params.groupId,
+      groupName: params.groupName,
+      includeGroupIdAlias: true,
+      includeWildcard: true,
+    }),
+  );
+  if (typeof entry?.requireMention === "boolean") {
+    return entry.requireMention;
+  }
+  return true;
+}
 
-  proc.stderr?.on("data", (data: Buffer) => {
-    const text = data.toString().trim();
-    if (text) {
-      runtime.error(`[zalouser] zca stderr: ${text}`);
-    }
+async function sendZalouserDeliveryAcks(params: {
+  profile: string;
+  isGroup: boolean;
+  message: NonNullable<ZaloInboundMessage["eventMessage"]>;
+}): Promise<void> {
+  await sendDeliveredZalouser({
+    profile: params.profile,
+    isGroup: params.isGroup,
+    message: params.message,
+    isSeen: true,
   });
-
-  void promise.then((result) => {
-    if (!result.ok && !abortSignal.aborted) {
-      onError(new Error(result.stderr || `zca listen exited with code ${result.exitCode}`));
-    }
+  await sendSeenZalouser({
+    profile: params.profile,
+    isGroup: params.isGroup,
+    message: params.message,
   });
-
-  abortSignal.addEventListener(
-    "abort",
-    () => {
-      proc.kill("SIGTERM");
-    },
-    { once: true },
-  );
-
-  return proc;
 }
 
 async function processMessage(
-  message: ZcaMessage,
+  message: ZaloInboundMessage,
   account: ResolvedZalouserAccount,
   config: OpenClawConfig,
   core: ZalouserCoreRuntime,
   runtime: RuntimeEnv,
   statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void,
 ): Promise<void> {
-  const { threadId, content, timestamp, metadata } = message;
-  if (!content?.trim()) {
+  const pairing = createScopedPairingAccess({
+    core,
+    channel: "zalouser",
+    accountId: account.accountId,
+  });
+
+  const rawBody = message.content?.trim();
+  if (!rawBody) {
     return;
   }
 
-  const isGroup = metadata?.isGroup ?? false;
-  const senderId = metadata?.fromId ?? threadId;
-  const senderName = metadata?.senderName ?? "";
-  const groupName = metadata?.threadName ?? "";
-  const chatId = threadId;
+  const isGroup = message.isGroup;
+  const chatId = message.threadId;
+  const senderId = message.senderId?.trim();
+  if (!senderId) {
+    logVerbose(core, runtime, `zalouser: drop message ${chatId} (missing senderId)`);
+    return;
+  }
+  const senderName = message.senderName ?? "";
+  const configuredGroupName = message.groupName?.trim() || "";
+  const groupContext =
+    isGroup && !configuredGroupName
+      ? await resolveZaloGroupContext(account.profile, chatId).catch((err) => {
+          logVerbose(
+            core,
+            runtime,
+            `zalouser: group context lookup failed for ${chatId}: ${String(err)}`,
+          );
+          return null;
+        })
+      : null;
+  const groupName = configuredGroupName || groupContext?.name?.trim() || "";
+  const groupMembers = groupContext?.members?.slice(0, 20).join(", ") || undefined;
+
+  if (message.eventMessage) {
+    try {
+      await sendZalouserDeliveryAcks({
+        profile: account.profile,
+        isGroup,
+        message: message.eventMessage,
+      });
+    } catch (err) {
+      logVerbose(core, runtime, `zalouser: delivery/seen ack failed for ${chatId}: ${String(err)}`);
+    }
+  }
 
   const defaultGroupPolicy = resolveDefaultGroupPolicy(config);
   const { groupPolicy, providerMissingFallbackApplied } = resolveOpenProviderRuntimeGroupPolicy({
@@ -197,8 +217,9 @@ async function processMessage(
     providerMissingFallbackApplied,
     providerKey: "zalouser",
     accountId: account.accountId,
-    log: (message) => logVerbose(core, runtime, message),
+    log: (entry) => logVerbose(core, runtime, entry),
   });
+
   const groups = account.config.groups ?? {};
   if (isGroup) {
     if (groupPolicy === "disabled") {
@@ -216,7 +237,6 @@ async function processMessage(
 
   const dmPolicy = account.config.dmPolicy ?? "pairing";
   const configAllowFrom = (account.config.allowFrom ?? []).map((v) => String(v));
-  const rawBody = content.trim();
   const { senderAllowedForCommands, commandAuthorized } = await resolveSenderCommandAuthorization({
     cfg: config,
     rawBody,
@@ -225,7 +245,7 @@ async function processMessage(
     configuredAllowFrom: configAllowFrom,
     senderId,
     isSenderAllowed,
-    readAllowFromStore: () => core.channel.pairing.readAllowFromStore("zalouser"),
+    readAllowFromStore: pairing.readAllowFromStore,
     shouldComputeCommandAuthorized: (body, cfg) =>
       core.channel.commands.shouldComputeCommandAuthorized(body, cfg),
     resolveCommandAuthorizedFromAuthorizers: (params) =>
@@ -240,11 +260,9 @@ async function processMessage(
 
     if (dmPolicy !== "open") {
       const allowed = senderAllowedForCommands;
-
       if (!allowed) {
         if (dmPolicy === "pairing") {
-          const { code, created } = await core.channel.pairing.upsertPairingRequest({
-            channel: "zalouser",
+          const { code, created } = await pairing.upsertPairingRequest({
             id: senderId,
             meta: { name: senderName || undefined },
           });
@@ -282,11 +300,8 @@ async function processMessage(
     }
   }
 
-  if (
-    isGroup &&
-    core.channel.commands.isControlCommandMessage(rawBody, config) &&
-    commandAuthorized !== true
-  ) {
+  const hasControlCommand = core.channel.commands.isControlCommandMessage(rawBody, config);
+  if (isGroup && hasControlCommand && commandAuthorized !== true) {
     logVerbose(
       core,
       runtime,
@@ -310,7 +325,46 @@ async function processMessage(
     },
   });
 
-  const fromLabel = isGroup ? `group:${chatId}` : senderName || `user:${senderId}`;
+  const requireMention = isGroup
+    ? resolveGroupRequireMention({
+        groupId: chatId,
+        groupName,
+        groups,
+      })
+    : false;
+  const mentionRegexes = core.channel.mentions.buildMentionRegexes(config, route.agentId);
+  const explicitMention = {
+    hasAnyMention: message.hasAnyMention === true,
+    isExplicitlyMentioned: message.wasExplicitlyMentioned === true,
+    canResolveExplicit: message.canResolveExplicitMention === true,
+  };
+  const wasMentioned = isGroup
+    ? core.channel.mentions.matchesMentionWithExplicit({
+        text: rawBody,
+        mentionRegexes,
+        explicit: explicitMention,
+      })
+    : true;
+  const mentionGate = resolveMentionGatingWithBypass({
+    isGroup,
+    requireMention,
+    canDetectMention: mentionRegexes.length > 0 || explicitMention.canResolveExplicit,
+    wasMentioned,
+    implicitMention: message.implicitMention === true,
+    hasAnyMention: explicitMention.hasAnyMention,
+    allowTextCommands: core.channel.commands.shouldHandleTextCommands({
+      cfg: config,
+      surface: "zalouser",
+    }),
+    hasControlCommand,
+    commandAuthorized: commandAuthorized === true,
+  });
+  if (isGroup && mentionGate.shouldSkip) {
+    logVerbose(core, runtime, `zalouser: skip group ${chatId} (mention required, not mentioned)`);
+    return;
+  }
+
+  const fromLabel = isGroup ? groupName || `group:${chatId}` : senderName || `user:${senderId}`;
   const storePath = core.channel.session.resolveStorePath(config.session?.store, {
     agentId: route.agentId,
   });
@@ -322,7 +376,7 @@ async function processMessage(
   const body = core.channel.reply.formatAgentEnvelope({
     channel: "Zalo Personal",
     from: fromLabel,
-    timestamp: timestamp ? timestamp * 1000 : undefined,
+    timestamp: message.timestampMs,
     previousTimestamp,
     envelope: envelopeOptions,
     body: rawBody,
@@ -339,12 +393,24 @@ async function processMessage(
     AccountId: route.accountId,
     ChatType: isGroup ? "group" : "direct",
     ConversationLabel: fromLabel,
+    GroupSubject: isGroup ? groupName || undefined : undefined,
+    GroupChannel: isGroup ? groupName || undefined : undefined,
+    GroupMembers: isGroup ? groupMembers : undefined,
     SenderName: senderName || undefined,
     SenderId: senderId,
+    WasMentioned: isGroup ? mentionGate.effectiveWasMentioned : undefined,
     CommandAuthorized: commandAuthorized,
     Provider: "zalouser",
     Surface: "zalouser",
-    MessageSid: message.msgId ?? `${timestamp}`,
+    MessageSid: resolveZalouserMessageSid({
+      msgId: message.msgId,
+      cliMsgId: message.cliMsgId,
+      fallback: `${message.timestampMs}`,
+    }),
+    MessageSidFull: formatZalouserMessageSidFull({
+      msgId: message.msgId,
+      cliMsgId: message.cliMsgId,
+    }),
     OriginatingChannel: "zalouser",
     OriginatingTo: `zalouser:${chatId}`,
   });
@@ -364,12 +430,24 @@ async function processMessage(
     channel: "zalouser",
     accountId: account.accountId,
   });
+  const typingCallbacks = createTypingCallbacks({
+    start: async () => {
+      await sendTypingZalouser(chatId, {
+        profile: account.profile,
+        isGroup,
+      });
+    },
+    onStartError: (err) => {
+      logVerbose(core, runtime, `zalouser typing failed for ${chatId}: ${String(err)}`);
+    },
+  });
 
   await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
     ctx: ctxPayload,
     cfg: config,
     dispatcherOptions: {
       ...prefixOptions,
+      typingCallbacks,
       deliver: async (payload) => {
         await deliverZalouserReply({
           payload: payload as { text?: string; mediaUrls?: string[]; mediaUrl?: string },
@@ -461,10 +539,6 @@ export async function monitorZalouserProvider(
   const { abortSignal, statusSink, runtime } = options;
 
   const core = getZalouserRuntime();
-  let stopped = false;
-  let proc: ChildProcess | null = null;
-  let restartTimer: ReturnType<typeof setTimeout> | null = null;
-  let resolveRunning: (() => void) | null = null;
 
   try {
     const profile = account.profile;
@@ -473,147 +547,144 @@ export async function monitorZalouserProvider(
       .filter((entry) => entry && entry !== "*");
 
     if (allowFromEntries.length > 0) {
-      const result = await runZca(["friend", "list", "-j"], { profile, timeout: 15000 });
-      if (result.ok) {
-        const friends = parseJsonOutput<ZcaFriend[]>(result.stdout) ?? [];
-        const byName = buildNameIndex(friends, (friend) => friend.displayName);
-        const additions: string[] = [];
-        const mapping: string[] = [];
-        const unresolved: string[] = [];
-        for (const entry of allowFromEntries) {
-          if (/^\d+$/.test(entry)) {
-            additions.push(entry);
-            continue;
-          }
-          const matches = byName.get(entry.toLowerCase()) ?? [];
-          const match = matches[0];
-          const id = match?.userId ? String(match.userId) : undefined;
-          if (id) {
-            additions.push(id);
-            mapping.push(`${entry}→${id}`);
-          } else {
-            unresolved.push(entry);
-          }
+      const friends = await listZaloFriends(profile);
+      const byName = buildNameIndex(friends, (friend) => friend.displayName);
+      const additions: string[] = [];
+      const mapping: string[] = [];
+      const unresolved: string[] = [];
+      for (const entry of allowFromEntries) {
+        if (/^\d+$/.test(entry)) {
+          additions.push(entry);
+          continue;
+        }
+        const matches = byName.get(entry.toLowerCase()) ?? [];
+        const match = matches[0];
+        const id = match?.userId ? String(match.userId) : undefined;
+        if (id) {
+          additions.push(id);
+          mapping.push(`${entry}→${id}`);
+        } else {
+          unresolved.push(entry);
         }
-        const allowFrom = mergeAllowlist({ existing: account.config.allowFrom, additions });
-        account = {
-          ...account,
-          config: {
-            ...account.config,
-            allowFrom,
-          },
-        };
-        summarizeMapping("zalouser users", mapping, unresolved, runtime);
-      } else {
-        runtime.log?.(`zalouser user resolve failed; using config entries. ${result.stderr}`);
       }
+      const allowFrom = mergeAllowlist({ existing: account.config.allowFrom, additions });
+      account = {
+        ...account,
+        config: {
+          ...account.config,
+          allowFrom,
+        },
+      };
+      summarizeMapping("zalouser users", mapping, unresolved, runtime);
     }
 
     const groupsConfig = account.config.groups ?? {};
     const groupKeys = Object.keys(groupsConfig).filter((key) => key !== "*");
     if (groupKeys.length > 0) {
-      const result = await runZca(["group", "list", "-j"], { profile, timeout: 15000 });
-      if (result.ok) {
-        const groups = parseJsonOutput<ZcaGroup[]>(result.stdout) ?? [];
-        const byName = buildNameIndex(groups, (group) => group.name);
-        const mapping: string[] = [];
-        const unresolved: string[] = [];
-        const nextGroups = { ...groupsConfig };
-        for (const entry of groupKeys) {
-          const cleaned = normalizeZalouserEntry(entry);
-          if (/^\d+$/.test(cleaned)) {
-            if (!nextGroups[cleaned]) {
-              nextGroups[cleaned] = groupsConfig[entry];
-            }
-            mapping.push(`${entry}→${cleaned}`);
-            continue;
+      const groups = await listZaloGroups(profile);
+      const byName = buildNameIndex(groups, (group) => group.name);
+      const mapping: string[] = [];
+      const unresolved: string[] = [];
+      const nextGroups = { ...groupsConfig };
+      for (const entry of groupKeys) {
+        const cleaned = normalizeZalouserEntry(entry);
+        if (/^\d+$/.test(cleaned)) {
+          if (!nextGroups[cleaned]) {
+            nextGroups[cleaned] = groupsConfig[entry];
           }
-          const matches = byName.get(cleaned.toLowerCase()) ?? [];
-          const match = matches[0];
-          const id = match?.groupId ? String(match.groupId) : undefined;
-          if (id) {
-            if (!nextGroups[id]) {
-              nextGroups[id] = groupsConfig[entry];
-            }
-            mapping.push(`${entry}→${id}`);
-          } else {
-            unresolved.push(entry);
+          mapping.push(`${entry}→${cleaned}`);
+          continue;
+        }
+        const matches = byName.get(cleaned.toLowerCase()) ?? [];
+        const match = matches[0];
+        const id = match?.groupId ? String(match.groupId) : undefined;
+        if (id) {
+          if (!nextGroups[id]) {
+            nextGroups[id] = groupsConfig[entry];
           }
+          mapping.push(`${entry}→${id}`);
+        } else {
+          unresolved.push(entry);
         }
-        account = {
-          ...account,
-          config: {
-            ...account.config,
-            groups: nextGroups,
-          },
-        };
-        summarizeMapping("zalouser groups", mapping, unresolved, runtime);
-      } else {
-        runtime.log?.(`zalouser group resolve failed; using config entries. ${result.stderr}`);
       }
+      account = {
+        ...account,
+        config: {
+          ...account.config,
+          groups: nextGroups,
+        },
+      };
+      summarizeMapping("zalouser groups", mapping, unresolved, runtime);
     }
   } catch (err) {
     runtime.log?.(`zalouser resolve failed; using config entries. ${String(err)}`);
   }
 
+  let listenerStop: (() => void) | null = null;
+  let stopped = false;
+
   const stop = () => {
-    stopped = true;
-    if (restartTimer) {
-      clearTimeout(restartTimer);
-      restartTimer = null;
-    }
-    if (proc) {
-      proc.kill("SIGTERM");
-      proc = null;
+    if (stopped) {
+      return;
     }
-    resolveRunning?.();
+    stopped = true;
+    listenerStop?.();
+    listenerStop = null;
   };
 
-  const startListener = () => {
-    if (stopped || abortSignal.aborted) {
-      resolveRunning?.();
-      return;
-    }
+  const listener = await startZaloListener({
+    accountId: account.accountId,
+    profile: account.profile,
+    abortSignal,
+    onMessage: (msg) => {
+      if (stopped) {
+        return;
+      }
+      logVerbose(core, runtime, `[${account.accountId}] inbound message`);
+      statusSink?.({ lastInboundAt: Date.now() });
+      processMessage(msg, account, config, core, runtime, statusSink).catch((err) => {
+        runtime.error(`[${account.accountId}] Failed to process message: ${String(err)}`);
+      });
+    },
+    onError: (err) => {
+      if (stopped || abortSignal.aborted) {
+        return;
+      }
+      runtime.error(`[${account.accountId}] Zalo listener error: ${String(err)}`);
+    },
+  });
 
-    logVerbose(
-      core,
-      runtime,
-      `[${account.accountId}] starting zca listener (profile=${account.profile})`,
-    );
+  listenerStop = listener.stop;
 
-    proc = startZcaListener(
-      runtime,
-      account.profile,
-      (msg) => {
-        logVerbose(core, runtime, `[${account.accountId}] inbound message`);
-        statusSink?.({ lastInboundAt: Date.now() });
-        processMessage(msg, account, config, core, runtime, statusSink).catch((err) => {
-          runtime.error(`[${account.accountId}] Failed to process message: ${String(err)}`);
-        });
+  await new Promise<void>((resolve) => {
+    abortSignal.addEventListener(
+      "abort",
+      () => {
+        stop();
+        resolve();
       },
-      (err) => {
-        runtime.error(`[${account.accountId}] zca listener error: ${String(err)}`);
-        if (!stopped && !abortSignal.aborted) {
-          logVerbose(core, runtime, `[${account.accountId}] restarting listener in 5s...`);
-          restartTimer = setTimeout(startListener, 5000);
-        } else {
-          resolveRunning?.();
-        }
-      },
-      abortSignal,
+      { once: true },
     );
-  };
-
-  // Create a promise that stays pending until abort or stop
-  const runningPromise = new Promise<void>((resolve) => {
-    resolveRunning = resolve;
-    abortSignal.addEventListener("abort", () => resolve(), { once: true });
   });
 
-  startListener();
-
-  // Wait for the running promise to resolve (on abort/stop)
-  await runningPromise;
-
   return { stop };
 }
+
+export const __testing = {
+  processMessage: async (params: {
+    message: ZaloInboundMessage;
+    account: ResolvedZalouserAccount;
+    config: OpenClawConfig;
+    runtime: RuntimeEnv;
+    statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  }) => {
+    await processMessage(
+      params.message,
+      params.account,
+      params.config,
+      getZalouserRuntime(),
+      params.runtime,
+      params.statusSink,
+    );
+  },
+};