@clawdbot/zalouser 2026.1.16

package/src/monitor.ts

@@ -0,0 +1,372 @@
+import type { ChildProcess } from "node:child_process";
+
+import type { RuntimeEnv } from "../../../src/runtime.js";
+import {
+  isControlCommandMessage,
+  shouldComputeCommandAuthorized,
+} from "../../../src/auto-reply/command-detection.js";
+import { finalizeInboundContext } from "../../../src/auto-reply/reply/inbound-context.js";
+import { resolveCommandAuthorizedFromAuthorizers } from "../../../src/channels/command-gating.js";
+import { loadCoreChannelDeps, type CoreChannelDeps } from "./core-bridge.js";
+import { sendMessageZalouser } from "./send.js";
+import type { CoreConfig, ResolvedZalouserAccount, ZcaMessage } from "./types.js";
+import { runZcaStreaming } from "./zca.js";
+
+export type ZalouserMonitorOptions = {
+  account: ResolvedZalouserAccount;
+  config: CoreConfig;
+  runtime: RuntimeEnv;
+  abortSignal: AbortSignal;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+};
+
+export type ZalouserMonitorResult = {
+  stop: () => void;
+};
+
+const ZALOUSER_TEXT_LIMIT = 2000;
+
+function logVerbose(deps: CoreChannelDeps, runtime: RuntimeEnv, message: string): void {
+  if (deps.shouldLogVerbose()) {
+    runtime.log(`[zalouser] ${message}`);
+  }
+}
+
+function isSenderAllowed(senderId: string, allowFrom: string[]): boolean {
+  if (allowFrom.includes("*")) return true;
+  const normalizedSenderId = senderId.toLowerCase();
+  return allowFrom.some((entry) => {
+    const normalized = entry.toLowerCase().replace(/^(zalouser|zlu):/i, "");
+    return normalized === normalizedSenderId;
+  });
+}
+
+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,
+  });
+
+  proc.stderr?.on("data", (data: Buffer) => {
+    const text = data.toString().trim();
+    if (text) runtime.error(`[zalouser] zca stderr: ${text}`);
+  });
+
+  void promise.then((result) => {
+    if (!result.ok && !abortSignal.aborted) {
+      onError(new Error(result.stderr || `zca listen exited with code ${result.exitCode}`));
+    }
+  });
+
+  abortSignal.addEventListener(
+    "abort",
+    () => {
+      proc.kill("SIGTERM");
+    },
+    { once: true },
+  );
+
+  return proc;
+}
+
+async function processMessage(
+  message: ZcaMessage,
+  account: ResolvedZalouserAccount,
+  config: CoreConfig,
+  deps: CoreChannelDeps,
+  runtime: RuntimeEnv,
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void,
+): Promise<void> {
+  const { threadId, content, timestamp, metadata } = message;
+  if (!content?.trim()) return;
+
+  const isGroup = metadata?.isGroup ?? false;
+  const senderId = metadata?.fromId ?? threadId;
+  const senderName = metadata?.senderName ?? "";
+  const chatId = threadId;
+
+  const dmPolicy = account.config.dmPolicy ?? "pairing";
+  const configAllowFrom = (account.config.allowFrom ?? []).map((v) => String(v));
+  const rawBody = content.trim();
+  const shouldComputeAuth = shouldComputeCommandAuthorized(rawBody, config);
+  const storeAllowFrom =
+    !isGroup && (dmPolicy !== "open" || shouldComputeAuth)
+      ? await deps.readChannelAllowFromStore("zalouser").catch(() => [])
+      : [];
+  const effectiveAllowFrom = [...configAllowFrom, ...storeAllowFrom];
+  const useAccessGroups = config.commands?.useAccessGroups !== false;
+  const senderAllowedForCommands = isSenderAllowed(senderId, effectiveAllowFrom);
+  const commandAuthorized = shouldComputeAuth
+    ? resolveCommandAuthorizedFromAuthorizers({
+        useAccessGroups,
+        authorizers: [{ configured: effectiveAllowFrom.length > 0, allowed: senderAllowedForCommands }],
+      })
+    : undefined;
+
+  if (!isGroup) {
+    if (dmPolicy === "disabled") {
+      logVerbose(deps, runtime, `Blocked zalouser DM from ${senderId} (dmPolicy=disabled)`);
+      return;
+    }
+
+    if (dmPolicy !== "open") {
+      const allowed = senderAllowedForCommands;
+
+      if (!allowed) {
+        if (dmPolicy === "pairing") {
+          const { code, created } = await deps.upsertChannelPairingRequest({
+            channel: "zalouser",
+            id: senderId,
+            meta: { name: senderName || undefined },
+          });
+
+          if (created) {
+            logVerbose(deps, runtime, `zalouser pairing request sender=${senderId}`);
+            try {
+              await sendMessageZalouser(
+                chatId,
+                deps.buildPairingReply({
+                  channel: "zalouser",
+                  idLine: `Your Zalo user id: ${senderId}`,
+                  code,
+                }),
+                { profile: account.profile },
+              );
+              statusSink?.({ lastOutboundAt: Date.now() });
+            } catch (err) {
+              logVerbose(
+                deps,
+                runtime,
+                `zalouser pairing reply failed for ${senderId}: ${String(err)}`,
+              );
+            }
+          }
+        } else {
+          logVerbose(
+            deps,
+            runtime,
+            `Blocked unauthorized zalouser sender ${senderId} (dmPolicy=${dmPolicy})`,
+          );
+        }
+        return;
+      }
+    }
+  }
+
+  if (isGroup && isControlCommandMessage(rawBody, config) && commandAuthorized !== true) {
+    logVerbose(deps, runtime, `zalouser: drop control command from unauthorized sender ${senderId}`);
+    return;
+  }
+
+  const peer = isGroup ? { kind: "group" as const, id: chatId } : { kind: "group" as const, id: senderId };
+
+  const route = deps.resolveAgentRoute({
+    cfg: config,
+    channel: "zalouser",
+    accountId: account.accountId,
+    peer: {
+      // Use "group" kind to avoid dmScope=main collapsing all DMs into the main session.
+      kind: peer.kind,
+      id: peer.id,
+    },
+  });
+
+	  const rawBody = content.trim();
+	  const fromLabel = isGroup ? `group:${chatId}` : senderName || `user:${senderId}`;
+	  const body = deps.formatAgentEnvelope({
+	    channel: "Zalo Personal",
+	    from: fromLabel,
+    timestamp: timestamp ? timestamp * 1000 : undefined,
+    body: rawBody,
+  });
+
+  const ctxPayload = finalizeInboundContext({
+    Body: body,
+    RawBody: rawBody,
+    CommandBody: rawBody,
+    From: isGroup ? `zalouser:group:${chatId}` : `zalouser:${senderId}`,
+    To: `zalouser:${chatId}`,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: isGroup ? "group" : "direct",
+    ConversationLabel: fromLabel,
+    SenderName: senderName || undefined,
+    SenderId: senderId,
+    CommandAuthorized: commandAuthorized,
+    Provider: "zalouser",
+    Surface: "zalouser",
+    MessageSid: message.msgId ?? `${timestamp}`,
+    OriginatingChannel: "zalouser",
+    OriginatingTo: `zalouser:${chatId}`,
+  });
+
+  await deps.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg: config,
+    dispatcherOptions: {
+      deliver: async (payload) => {
+        await deliverZalouserReply({
+          payload: payload as { text?: string; mediaUrls?: string[]; mediaUrl?: string },
+          profile: account.profile,
+          chatId,
+          isGroup,
+          runtime,
+          deps,
+          statusSink,
+        });
+      },
+      onError: (err, info) => {
+        runtime.error(
+          `[${account.accountId}] Zalouser ${info.kind} reply failed: ${String(err)}`,
+        );
+      },
+    },
+  });
+}
+
+async function deliverZalouserReply(params: {
+  payload: { text?: string; mediaUrls?: string[]; mediaUrl?: string };
+  profile: string;
+  chatId: string;
+  isGroup: boolean;
+  runtime: RuntimeEnv;
+  deps: CoreChannelDeps;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+}): Promise<void> {
+  const { payload, profile, chatId, isGroup, runtime, deps, statusSink } = params;
+
+  const mediaList = payload.mediaUrls?.length
+    ? payload.mediaUrls
+    : payload.mediaUrl
+      ? [payload.mediaUrl]
+      : [];
+
+  if (mediaList.length > 0) {
+    let first = true;
+    for (const mediaUrl of mediaList) {
+      const caption = first ? payload.text : undefined;
+      first = false;
+      try {
+        logVerbose(deps, runtime, `Sending media to ${chatId}`);
+        await sendMessageZalouser(chatId, caption ?? "", {
+          profile,
+          mediaUrl,
+          isGroup,
+        });
+        statusSink?.({ lastOutboundAt: Date.now() });
+      } catch (err) {
+        runtime.error(`Zalouser media send failed: ${String(err)}`);
+      }
+    }
+    return;
+  }
+
+  if (payload.text) {
+    const chunks = deps.chunkMarkdownText(payload.text, ZALOUSER_TEXT_LIMIT);
+    logVerbose(deps, runtime, `Sending ${chunks.length} text chunk(s) to ${chatId}`);
+    for (const chunk of chunks) {
+      try {
+        await sendMessageZalouser(chatId, chunk, { profile, isGroup });
+        statusSink?.({ lastOutboundAt: Date.now() });
+      } catch (err) {
+        runtime.error(`Zalouser message send failed: ${String(err)}`);
+      }
+    }
+  }
+}
+
+export async function monitorZalouserProvider(
+  options: ZalouserMonitorOptions,
+): Promise<ZalouserMonitorResult> {
+  const { account, config, abortSignal, statusSink, runtime } = options;
+
+  const deps = await loadCoreChannelDeps();
+  let stopped = false;
+  let proc: ChildProcess | null = null;
+  let restartTimer: ReturnType<typeof setTimeout> | null = null;
+  let resolveRunning: (() => void) | null = null;
+
+  const stop = () => {
+    stopped = true;
+    if (restartTimer) {
+      clearTimeout(restartTimer);
+      restartTimer = null;
+    }
+    if (proc) {
+      proc.kill("SIGTERM");
+      proc = null;
+    }
+    resolveRunning?.();
+  };
+
+  const startListener = () => {
+    if (stopped || abortSignal.aborted) {
+      resolveRunning?.();
+      return;
+    }
+
+    logVerbose(
+      deps,
+      runtime,
+      `[${account.accountId}] starting zca listener (profile=${account.profile})`,
+    );
+
+    proc = startZcaListener(
+      runtime,
+      account.profile,
+      (msg) => {
+        logVerbose(deps, runtime, `[${account.accountId}] inbound message`);
+        statusSink?.({ lastInboundAt: Date.now() });
+        processMessage(msg, account, config, deps, runtime, statusSink).catch((err) => {
+          runtime.error(`[${account.accountId}] Failed to process message: ${String(err)}`);
+        });
+      },
+      (err) => {
+        runtime.error(`[${account.accountId}] zca listener error: ${String(err)}`);
+        if (!stopped && !abortSignal.aborted) {
+          logVerbose(deps, runtime, `[${account.accountId}] restarting listener in 5s...`);
+          restartTimer = setTimeout(startListener, 5000);
+        } else {
+          resolveRunning?.();
+        }
+      },
+      abortSignal,
+    );
+  };
+
+  // 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 };
+}

package/src/onboarding.ts

@@ -0,0 +1,312 @@
+import type { ChannelOnboardingAdapter, ChannelOnboardingDmPolicy } from "../../../src/channels/plugins/onboarding-types.js";
+import type { WizardPrompter } from "../../../src/wizard/prompts.js";
+
+import {
+  listZalouserAccountIds,
+  resolveDefaultZalouserAccountId,
+  resolveZalouserAccountSync,
+  normalizeAccountId,
+  checkZcaAuthenticated,
+} from "./accounts.js";
+import { runZcaInteractive, checkZcaInstalled } from "./zca.js";
+import { DEFAULT_ACCOUNT_ID, type CoreConfig } from "./types.js";
+
+const channel = "zalouser" as const;
+
+function setZalouserDmPolicy(
+  cfg: CoreConfig,
+  dmPolicy: "pairing" | "allowlist" | "open" | "disabled",
+): CoreConfig {
+  const allowFrom =
+    dmPolicy === "open"
+      ? [...(cfg.channels?.zalouser?.allowFrom ?? []), "*"].filter(
+          (v, i, a) => a.indexOf(v) === i,
+        )
+      : undefined;
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      zalouser: {
+        ...cfg.channels?.zalouser,
+        dmPolicy,
+        ...(allowFrom ? { allowFrom } : {}),
+      },
+    },
+  } as CoreConfig;
+}
+
+async function noteZalouserHelp(prompter: WizardPrompter): Promise<void> {
+  await prompter.note(
+    [
+      "Zalo Personal Account login via QR code.",
+      "",
+      "Prerequisites:",
+      "1) Install zca-cli",
+      "2) You'll scan a QR code with your Zalo app",
+      "",
+      "Docs: https://docs.clawd.bot/channels/zalouser",
+    ].join("\n"),
+    "Zalo Personal Setup",
+  );
+}
+
+async function promptZalouserAllowFrom(params: {
+  cfg: CoreConfig;
+  prompter: WizardPrompter;
+  accountId: string;
+}): Promise<CoreConfig> {
+  const { cfg, prompter, accountId } = params;
+  const resolved = resolveZalouserAccountSync({ cfg, accountId });
+  const existingAllowFrom = resolved.config.allowFrom ?? [];
+  const entry = await prompter.text({
+    message: "Zalouser allowFrom (user id)",
+    placeholder: "123456789",
+    initialValue: existingAllowFrom[0] ? String(existingAllowFrom[0]) : undefined,
+    validate: (value) => {
+      const raw = String(value ?? "").trim();
+      if (!raw) return "Required";
+      if (!/^\d+$/.test(raw)) return "Use a numeric Zalo user id";
+      return undefined;
+    },
+  });
+  const normalized = String(entry).trim();
+  const merged = [
+    ...existingAllowFrom.map((item) => String(item).trim()).filter(Boolean),
+    normalized,
+  ];
+  const unique = [...new Set(merged)];
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalouser: {
+          ...cfg.channels?.zalouser,
+          enabled: true,
+          dmPolicy: "allowlist",
+          allowFrom: unique,
+        },
+      },
+    } as CoreConfig;
+  }
+
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      zalouser: {
+        ...cfg.channels?.zalouser,
+        enabled: true,
+        accounts: {
+          ...(cfg.channels?.zalouser?.accounts ?? {}),
+          [accountId]: {
+            ...(cfg.channels?.zalouser?.accounts?.[accountId] ?? {}),
+            enabled: cfg.channels?.zalouser?.accounts?.[accountId]?.enabled ?? true,
+            dmPolicy: "allowlist",
+            allowFrom: unique,
+          },
+        },
+      },
+    },
+  } as CoreConfig;
+}
+
+async function promptAccountId(params: {
+  cfg: CoreConfig;
+  prompter: WizardPrompter;
+  label: string;
+  currentId: string;
+  listAccountIds: (cfg: CoreConfig) => string[];
+  defaultAccountId: string;
+}): Promise<string> {
+  const { cfg, prompter, label, currentId, listAccountIds, defaultAccountId } = params;
+  const existingIds = listAccountIds(cfg);
+  const options = [
+    ...existingIds.map((id) => ({
+      value: id,
+      label: id === defaultAccountId ? `${id} (default)` : id,
+    })),
+    { value: "__new__", label: "Create new account" },
+  ];
+
+  const selected = await prompter.select({
+    message: `${label} account`,
+    options,
+    initialValue: currentId,
+  });
+
+  if (selected === "__new__") {
+    const newId = await prompter.text({
+      message: "New account ID",
+      placeholder: "work",
+      validate: (value) => {
+        const raw = String(value ?? "").trim().toLowerCase();
+        if (!raw) return "Required";
+        if (!/^[a-z0-9_-]+$/.test(raw)) return "Use lowercase alphanumeric, dash, or underscore";
+        if (existingIds.includes(raw)) return "Account already exists";
+        return undefined;
+      },
+    });
+    return String(newId).trim().toLowerCase();
+  }
+
+  return selected as string;
+}
+
+const dmPolicy: ChannelOnboardingDmPolicy = {
+  label: "Zalo Personal",
+  channel,
+  policyKey: "channels.zalouser.dmPolicy",
+  allowFromKey: "channels.zalouser.allowFrom",
+  getCurrent: (cfg) => ((cfg as CoreConfig).channels?.zalouser?.dmPolicy ?? "pairing") as "pairing",
+  setPolicy: (cfg, policy) => setZalouserDmPolicy(cfg as CoreConfig, policy),
+};
+
+export const zalouserOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  dmPolicy,
+  getStatus: async ({ cfg }) => {
+    const ids = listZalouserAccountIds(cfg as CoreConfig);
+    let configured = false;
+    for (const accountId of ids) {
+      const account = resolveZalouserAccountSync({ cfg: cfg as CoreConfig, accountId });
+      const isAuth = await checkZcaAuthenticated(account.profile);
+      if (isAuth) {
+        configured = true;
+        break;
+      }
+    }
+    return {
+      channel,
+      configured,
+      statusLines: [`Zalo Personal: ${configured ? "logged in" : "needs QR login"}`],
+      selectionHint: configured ? "recommended · logged in" : "recommended · QR login",
+      quickstartScore: configured ? 1 : 15,
+    };
+  },
+  configure: async ({ cfg, prompter, accountOverrides, shouldPromptAccountIds, forceAllowFrom }) => {
+    // Check zca is installed
+    const zcaInstalled = await checkZcaInstalled();
+    if (!zcaInstalled) {
+      await prompter.note(
+        [
+          "The `zca` binary was not found in PATH.",
+          "",
+          "Install zca-cli, then re-run onboarding:",
+          "Docs: https://docs.clawd.bot/channels/zalouser",
+        ].join("\n"),
+        "Missing Dependency",
+      );
+      return { cfg, accountId: DEFAULT_ACCOUNT_ID };
+    }
+
+    const zalouserOverride = accountOverrides.zalouser?.trim();
+    const defaultAccountId = resolveDefaultZalouserAccountId(cfg as CoreConfig);
+    let accountId = zalouserOverride
+      ? normalizeAccountId(zalouserOverride)
+      : defaultAccountId;
+
+    if (shouldPromptAccountIds && !zalouserOverride) {
+      accountId = await promptAccountId({
+        cfg: cfg as CoreConfig,
+        prompter,
+        label: "Zalo Personal",
+        currentId: accountId,
+        listAccountIds: listZalouserAccountIds,
+        defaultAccountId,
+      });
+    }
+
+    let next = cfg as CoreConfig;
+    const account = resolveZalouserAccountSync({ cfg: next, accountId });
+    const alreadyAuthenticated = await checkZcaAuthenticated(account.profile);
+
+    if (!alreadyAuthenticated) {
+      await noteZalouserHelp(prompter);
+
+      const wantsLogin = await prompter.confirm({
+        message: "Login via QR code now?",
+        initialValue: true,
+      });
+
+      if (wantsLogin) {
+        await prompter.note(
+          "A QR code will appear in your terminal.\nScan it with your Zalo app to login.",
+          "QR Login",
+        );
+
+        // Run interactive login
+        const result = await runZcaInteractive(["auth", "login"], {
+          profile: account.profile,
+        });
+
+        if (!result.ok) {
+          await prompter.note(
+            `Login failed: ${result.stderr || "Unknown error"}`,
+            "Error",
+          );
+        } else {
+          const isNowAuth = await checkZcaAuthenticated(account.profile);
+          if (isNowAuth) {
+            await prompter.note("Login successful!", "Success");
+          }
+        }
+      }
+    } else {
+      const keepSession = await prompter.confirm({
+        message: "Zalo Personal already logged in. Keep session?",
+        initialValue: true,
+      });
+      if (!keepSession) {
+        await runZcaInteractive(["auth", "logout"], { profile: account.profile });
+        await runZcaInteractive(["auth", "login"], { profile: account.profile });
+      }
+    }
+
+    // Enable the channel
+    if (accountId === DEFAULT_ACCOUNT_ID) {
+      next = {
+        ...next,
+        channels: {
+          ...next.channels,
+          zalouser: {
+            ...next.channels?.zalouser,
+            enabled: true,
+            profile: account.profile !== "default" ? account.profile : undefined,
+          },
+        },
+      } as CoreConfig;
+    } else {
+      next = {
+        ...next,
+        channels: {
+          ...next.channels,
+          zalouser: {
+            ...next.channels?.zalouser,
+            enabled: true,
+            accounts: {
+              ...(next.channels?.zalouser?.accounts ?? {}),
+              [accountId]: {
+                ...(next.channels?.zalouser?.accounts?.[accountId] ?? {}),
+                enabled: true,
+                profile: account.profile,
+              },
+            },
+          },
+        },
+      } as CoreConfig;
+    }
+
+    if (forceAllowFrom) {
+      next = await promptZalouserAllowFrom({
+        cfg: next,
+        prompter,
+        accountId,
+      });
+    }
+
+    return { cfg: next, accountId };
+  },
+};