@openclaw/zalouser 2026.1.29

package/src/status-issues.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+
+import { collectZalouserStatusIssues } from "./status-issues.js";
+
+describe("collectZalouserStatusIssues", () => {
+  it("flags missing zca when configured is false", () => {
+    const issues = collectZalouserStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        configured: false,
+        lastError: "zca CLI not found in PATH",
+      },
+    ]);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.kind).toBe("runtime");
+    expect(issues[0]?.message).toMatch(/zca CLI not found/i);
+  });
+
+  it("flags missing auth when configured is false", () => {
+    const issues = collectZalouserStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        configured: false,
+        lastError: "not authenticated",
+      },
+    ]);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.kind).toBe("auth");
+    expect(issues[0]?.message).toMatch(/Not authenticated/i);
+  });
+
+  it("warns when dmPolicy is open", () => {
+    const issues = collectZalouserStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        configured: true,
+        dmPolicy: "open",
+      },
+    ]);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.kind).toBe("config");
+  });
+
+  it("skips disabled accounts", () => {
+    const issues = collectZalouserStatusIssues([
+      {
+        accountId: "default",
+        enabled: false,
+        configured: false,
+        lastError: "zca CLI not found in PATH",
+      },
+    ]);
+    expect(issues).toHaveLength(0);
+  });
+});

package/src/status-issues.ts

@@ -0,0 +1,81 @@
+import type { ChannelAccountSnapshot, ChannelStatusIssue } from "openclaw/plugin-sdk";
+
+type ZalouserAccountStatus = {
+  accountId?: unknown;
+  enabled?: unknown;
+  configured?: unknown;
+  dmPolicy?: unknown;
+  lastError?: unknown;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value && typeof value === "object");
+
+const asString = (value: unknown): string | undefined =>
+  typeof value === "string" ? value : typeof value === "number" ? String(value) : undefined;
+
+function readZalouserAccountStatus(value: ChannelAccountSnapshot): ZalouserAccountStatus | null {
+  if (!isRecord(value)) return null;
+  return {
+    accountId: value.accountId,
+    enabled: value.enabled,
+    configured: value.configured,
+    dmPolicy: value.dmPolicy,
+    lastError: value.lastError,
+  };
+}
+
+function isMissingZca(lastError?: string): boolean {
+  if (!lastError) return false;
+  const lower = lastError.toLowerCase();
+  return lower.includes("zca") && (lower.includes("not found") || lower.includes("enoent"));
+}
+
+export function collectZalouserStatusIssues(
+  accounts: ChannelAccountSnapshot[],
+): ChannelStatusIssue[] {
+  const issues: ChannelStatusIssue[] = [];
+  for (const entry of accounts) {
+    const account = readZalouserAccountStatus(entry);
+    if (!account) continue;
+    const accountId = asString(account.accountId) ?? "default";
+    const enabled = account.enabled !== false;
+    if (!enabled) continue;
+
+    const configured = account.configured === true;
+    const lastError = asString(account.lastError)?.trim();
+
+    if (!configured) {
+      if (isMissingZca(lastError)) {
+        issues.push({
+          channel: "zalouser",
+          accountId,
+          kind: "runtime",
+          message: "zca CLI not found in PATH.",
+          fix: "Install zca-cli and ensure it is on PATH for the Gateway process.",
+        });
+      } else {
+        issues.push({
+          channel: "zalouser",
+          accountId,
+          kind: "auth",
+          message: "Not authenticated (no zca session).",
+          fix: "Run: openclaw channels login --channel zalouser",
+        });
+      }
+      continue;
+    }
+
+    if (account.dmPolicy === "open") {
+      issues.push({
+        channel: "zalouser",
+        accountId,
+        kind: "config",
+        message:
+          'Zalo Personal dmPolicy is "open", allowing any user to message the bot without pairing.',
+        fix: 'Set channels.zalouser.dmPolicy to "pairing" or "allowlist" to restrict access.',
+      });
+    }
+  }
+  return issues;
+}

package/src/tool.ts

@@ -0,0 +1,156 @@
+import { Type } from "@sinclair/typebox";
+
+import { runZca, parseJsonOutput } from "./zca.js";
+
+const ACTIONS = ["send", "image", "link", "friends", "groups", "me", "status"] as const;
+
+function stringEnum<T extends readonly string[]>(
+  values: T,
+  options: { description?: string } = {},
+) {
+  return Type.Unsafe<T[number]>({
+    type: "string",
+    enum: [...values],
+    ...options,
+  });
+}
+
+// Tool schema - avoiding Type.Union per tool schema guardrails
+export const ZalouserToolSchema = Type.Object({
+  action: stringEnum(ACTIONS, { description: `Action to perform: ${ACTIONS.join(", ")}` }),
+  threadId: Type.Optional(
+    Type.String({ description: "Thread ID for messaging" }),
+  ),
+  message: Type.Optional(Type.String({ description: "Message text" })),
+  isGroup: Type.Optional(Type.Boolean({ description: "Is group chat" })),
+  profile: Type.Optional(Type.String({ description: "Profile name" })),
+  query: Type.Optional(Type.String({ description: "Search query" })),
+  url: Type.Optional(Type.String({ description: "URL for media/link" })),
+}, { additionalProperties: false });
+
+type ToolParams = {
+  action: (typeof ACTIONS)[number];
+  threadId?: string;
+  message?: string;
+  isGroup?: boolean;
+  profile?: string;
+  query?: string;
+  url?: string;
+};
+
+type ToolResult = {
+  content: Array<{ type: string; text: string }>;
+  details: unknown;
+};
+
+function json(payload: unknown): ToolResult {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    details: payload,
+  };
+}
+
+export async function executeZalouserTool(
+  _toolCallId: string,
+  params: ToolParams,
+): Promise<ToolResult> {
+  try {
+    switch (params.action) {
+      case "send": {
+        if (!params.threadId || !params.message) {
+          throw new Error("threadId and message required for send action");
+        }
+        const args = ["msg", "send", params.threadId, params.message];
+        if (params.isGroup) args.push("-g");
+        const result = await runZca(args, { profile: params.profile });
+        if (!result.ok) {
+          throw new Error(result.stderr || "Failed to send message");
+        }
+        return json({ success: true, output: result.stdout });
+      }
+
+      case "image": {
+        if (!params.threadId) {
+          throw new Error("threadId required for image action");
+        }
+        if (!params.url) {
+          throw new Error("url required for image action");
+        }
+        const args = ["msg", "image", params.threadId, "-u", params.url];
+        if (params.message) args.push("-m", params.message);
+        if (params.isGroup) args.push("-g");
+        const result = await runZca(args, { profile: params.profile });
+        if (!result.ok) {
+          throw new Error(result.stderr || "Failed to send image");
+        }
+        return json({ success: true, output: result.stdout });
+      }
+
+      case "link": {
+        if (!params.threadId || !params.url) {
+          throw new Error("threadId and url required for link action");
+        }
+        const args = ["msg", "link", params.threadId, params.url];
+        if (params.isGroup) args.push("-g");
+        const result = await runZca(args, { profile: params.profile });
+        if (!result.ok) {
+          throw new Error(result.stderr || "Failed to send link");
+        }
+        return json({ success: true, output: result.stdout });
+      }
+
+      case "friends": {
+        const args = params.query
+          ? ["friend", "find", params.query]
+          : ["friend", "list", "-j"];
+        const result = await runZca(args, { profile: params.profile });
+        if (!result.ok) {
+          throw new Error(result.stderr || "Failed to get friends");
+        }
+        const parsed = parseJsonOutput(result.stdout);
+        return json(parsed ?? { raw: result.stdout });
+      }
+
+      case "groups": {
+        const result = await runZca(["group", "list", "-j"], {
+          profile: params.profile,
+        });
+        if (!result.ok) {
+          throw new Error(result.stderr || "Failed to get groups");
+        }
+        const parsed = parseJsonOutput(result.stdout);
+        return json(parsed ?? { raw: result.stdout });
+      }
+
+      case "me": {
+        const result = await runZca(["me", "info", "-j"], {
+          profile: params.profile,
+        });
+        if (!result.ok) {
+          throw new Error(result.stderr || "Failed to get profile");
+        }
+        const parsed = parseJsonOutput(result.stdout);
+        return json(parsed ?? { raw: result.stdout });
+      }
+
+      case "status": {
+        const result = await runZca(["auth", "status"], {
+          profile: params.profile,
+        });
+        return json({
+          authenticated: result.ok,
+          output: result.stdout || result.stderr,
+        });
+      }
+
+      default:
+        throw new Error(
+          `Unknown action: ${params.action}. Valid actions: send, image, link, friends, groups, me, status`,
+        );
+    }
+  } catch (err) {
+    return json({
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}

package/src/types.ts

@@ -0,0 +1,102 @@
+// zca-cli wrapper types
+export type ZcaRunOptions = {
+  profile?: string;
+  cwd?: string;
+  timeout?: number;
+};
+
+export type ZcaResult = {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+
+export type ZcaProfile = {
+  name: string;
+  label?: string;
+  isDefault?: boolean;
+};
+
+export type ZcaFriend = {
+  userId: string;
+  displayName: string;
+  avatar?: string;
+};
+
+export type ZcaGroup = {
+  groupId: string;
+  name: string;
+  memberCount?: number;
+};
+
+export type ZcaMessage = {
+  threadId: string;
+  msgId?: string;
+  cliMsgId?: string;
+  type: number;
+  content: string;
+  timestamp: number;
+  metadata?: {
+    isGroup: boolean;
+    threadName?: string;
+    senderName?: string;
+    fromId?: string;
+  };
+};
+
+export type ZcaUserInfo = {
+  userId: string;
+  displayName: string;
+  avatar?: string;
+};
+
+export type CommonOptions = {
+  profile?: string;
+  json?: boolean;
+};
+
+export type SendOptions = CommonOptions & {
+  group?: boolean;
+};
+
+export type ListenOptions = CommonOptions & {
+  raw?: boolean;
+  keepAlive?: boolean;
+  webhook?: string;
+  echo?: boolean;
+  prefix?: string;
+};
+
+export type ZalouserAccountConfig = {
+  enabled?: boolean;
+  name?: string;
+  profile?: string;
+  dmPolicy?: "pairing" | "allowlist" | "open" | "disabled";
+  allowFrom?: Array<string | number>;
+  groupPolicy?: "open" | "allowlist" | "disabled";
+  groups?: Record<string, { allow?: boolean; enabled?: boolean; tools?: { allow?: string[]; deny?: string[] } }>;
+  messagePrefix?: string;
+};
+
+export type ZalouserConfig = {
+  enabled?: boolean;
+  name?: string;
+  profile?: string;
+  defaultAccount?: string;
+  dmPolicy?: "pairing" | "allowlist" | "open" | "disabled";
+  allowFrom?: Array<string | number>;
+  groupPolicy?: "open" | "allowlist" | "disabled";
+  groups?: Record<string, { allow?: boolean; enabled?: boolean; tools?: { allow?: string[]; deny?: string[] } }>;
+  messagePrefix?: string;
+  accounts?: Record<string, ZalouserAccountConfig>;
+};
+
+export type ResolvedZalouserAccount = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  profile: string;
+  authenticated: boolean;
+  config: ZalouserAccountConfig;
+};

package/src/zca.ts

@@ -0,0 +1,208 @@
+import { spawn, type SpawnOptions } from "node:child_process";
+
+import type { ZcaResult, ZcaRunOptions } from "./types.js";
+
+const ZCA_BINARY = "zca";
+const DEFAULT_TIMEOUT = 30000;
+
+function buildArgs(args: string[], options?: ZcaRunOptions): string[] {
+  const result: string[] = [];
+  // Profile flag comes first (before subcommand)
+  const profile = options?.profile || process.env.ZCA_PROFILE;
+  if (profile) {
+    result.push("--profile", profile);
+  }
+  result.push(...args);
+  return result;
+}
+
+export async function runZca(
+  args: string[],
+  options?: ZcaRunOptions,
+): Promise<ZcaResult> {
+  const fullArgs = buildArgs(args, options);
+  const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+
+  return new Promise((resolve) => {
+    const spawnOpts: SpawnOptions = {
+      cwd: options?.cwd,
+      env: { ...process.env },
+      stdio: ["pipe", "pipe", "pipe"],
+    };
+
+    const proc = spawn(ZCA_BINARY, fullArgs, spawnOpts);
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      proc.kill("SIGTERM");
+    }, timeout);
+
+    proc.stdout?.on("data", (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    proc.stderr?.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        resolve({
+          ok: false,
+          stdout,
+          stderr: stderr || "Command timed out",
+          exitCode: code ?? 124,
+        });
+        return;
+      }
+      resolve({
+        ok: code === 0,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        exitCode: code ?? 1,
+      });
+    });
+
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({
+        ok: false,
+        stdout: "",
+        stderr: err.message,
+        exitCode: 1,
+      });
+    });
+  });
+}
+
+export function runZcaInteractive(
+  args: string[],
+  options?: ZcaRunOptions,
+): Promise<ZcaResult> {
+  const fullArgs = buildArgs(args, options);
+
+  return new Promise((resolve) => {
+    const spawnOpts: SpawnOptions = {
+      cwd: options?.cwd,
+      env: { ...process.env },
+      stdio: "inherit",
+    };
+
+    const proc = spawn(ZCA_BINARY, fullArgs, spawnOpts);
+
+    proc.on("close", (code) => {
+      resolve({
+        ok: code === 0,
+        stdout: "",
+        stderr: "",
+        exitCode: code ?? 1,
+      });
+    });
+
+    proc.on("error", (err) => {
+      resolve({
+        ok: false,
+        stdout: "",
+        stderr: err.message,
+        exitCode: 1,
+      });
+    });
+  });
+}
+
+function stripAnsi(str: string): string {
+  return str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "");
+}
+
+export function parseJsonOutput<T>(stdout: string): T | null {
+  try {
+    return JSON.parse(stdout) as T;
+  } catch {
+    const cleaned = stripAnsi(stdout);
+
+    try {
+      return JSON.parse(cleaned) as T;
+    } catch {
+      // zca may prefix output with INFO/log lines, try to find JSON
+      const lines = cleaned.split("\n");
+
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line.startsWith("{") || line.startsWith("[")) {
+          // Try parsing from this line to the end
+          const jsonCandidate = lines.slice(i).join("\n").trim();
+          try {
+            return JSON.parse(jsonCandidate) as T;
+          } catch {
+            continue;
+          }
+        }
+      }
+      return null;
+    }
+  }
+}
+
+export async function checkZcaInstalled(): Promise<boolean> {
+  const result = await runZca(["--version"], { timeout: 5000 });
+  return result.ok;
+}
+
+export type ZcaStreamingOptions = ZcaRunOptions & {
+  onData?: (data: string) => void;
+  onError?: (err: Error) => void;
+};
+
+export function runZcaStreaming(
+  args: string[],
+  options?: ZcaStreamingOptions,
+): { proc: ReturnType<typeof spawn>; promise: Promise<ZcaResult> } {
+  const fullArgs = buildArgs(args, options);
+
+  const spawnOpts: SpawnOptions = {
+    cwd: options?.cwd,
+    env: { ...process.env },
+    stdio: ["pipe", "pipe", "pipe"],
+  };
+
+  const proc = spawn(ZCA_BINARY, fullArgs, spawnOpts);
+  let stdout = "";
+  let stderr = "";
+
+  proc.stdout?.on("data", (data: Buffer) => {
+    const text = data.toString();
+    stdout += text;
+    options?.onData?.(text);
+  });
+
+  proc.stderr?.on("data", (data: Buffer) => {
+    stderr += data.toString();
+  });
+
+  const promise = new Promise<ZcaResult>((resolve) => {
+    proc.on("close", (code) => {
+      resolve({
+        ok: code === 0,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        exitCode: code ?? 1,
+      });
+    });
+
+    proc.on("error", (err) => {
+      options?.onError?.(err);
+      resolve({
+        ok: false,
+        stdout: "",
+        stderr: err.message,
+        exitCode: 1,
+      });
+    });
+  });
+
+  return { proc, promise };
+}