@jackle.dev/zalox-plugin 1.0.1

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@jackle.dev/zalox-plugin",
+  "version": "1.0.1",
+  "description": "OpenClaw channel plugin for Zalo via zca-js (in-process, single login)",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "zca-js": "^2.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": "*",
+    "zod": "^3.0.0"
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,57 @@
+/**
+ * ZaloX Plugin — Account resolution
+ * 
+ * No subprocess calls. Config-only resolution.
+ */
+
+import type { OpenClawConfig } from 'openclaw/plugin-sdk';
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from 'openclaw/plugin-sdk';
+import type { ZaloxConfig, ZaloxAccountConfig, ResolvedZaloxAccount } from './types.js';
+import { hasCredentials } from './client.js';
+
+export function listAccountIds(cfg: OpenClawConfig): string[] {
+  const accounts = (cfg.channels?.zalox as ZaloxConfig | undefined)?.accounts;
+  if (!accounts || typeof accounts !== 'object') return [DEFAULT_ACCOUNT_ID];
+  const ids = Object.keys(accounts).filter(Boolean);
+  return ids.length > 0 ? ids.toSorted((a, b) => a.localeCompare(b)) : [DEFAULT_ACCOUNT_ID];
+}
+
+export function resolveDefaultAccountId(cfg: OpenClawConfig): string {
+  const zaloxConfig = cfg.channels?.zalox as ZaloxConfig | undefined;
+  if (zaloxConfig?.defaultAccount?.trim()) return zaloxConfig.defaultAccount.trim();
+  const ids = listAccountIds(cfg);
+  return ids.includes(DEFAULT_ACCOUNT_ID) ? DEFAULT_ACCOUNT_ID : (ids[0] ?? DEFAULT_ACCOUNT_ID);
+}
+
+function mergeAccountConfig(cfg: OpenClawConfig, accountId: string): ZaloxAccountConfig {
+  const raw = (cfg.channels?.zalox ?? {}) as ZaloxConfig;
+  const { accounts: _ignored, defaultAccount: _ignored2, ...base } = raw;
+  const account = raw.accounts?.[accountId] as ZaloxAccountConfig | undefined;
+  return { ...base, ...account };
+}
+
+export function resolveProfile(config: ZaloxAccountConfig, accountId: string): string {
+  if (config.credentialsPath?.trim()) return config.credentialsPath.trim();
+  if (process.env.ZCA_PROFILE?.trim()) return process.env.ZCA_PROFILE.trim();
+  if (accountId !== DEFAULT_ACCOUNT_ID) return accountId;
+  return 'default';
+}
+
+export function resolveAccount(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): ResolvedZaloxAccount {
+  const accountId = normalizeAccountId(params.accountId);
+  const baseEnabled = (params.cfg.channels?.zalox as ZaloxConfig | undefined)?.enabled !== false;
+  const merged = mergeAccountConfig(params.cfg, accountId);
+  const accountEnabled = merged.enabled !== false;
+  const profile = resolveProfile(merged, accountId);
+
+  return {
+    accountId,
+    name: merged.name?.trim() || undefined,
+    enabled: baseEnabled && accountEnabled,
+    credentialsPath: profile,
+    config: merged,
+  };
+}

package/src/channel.ts

@@ -0,0 +1,349 @@
+/**
+ * ZaloX Plugin — Channel definition
+ * 
+ * Minimal but functional channel plugin for Zalo via zca-js.
+ * Key difference from zalouser: ALL operations use cached in-process API.
+ * No subprocess spawning. No login-per-command. One WebSocket per account.
+ */
+
+import type {
+  ChannelAccountSnapshot,
+  ChannelDock,
+  ChannelPlugin,
+  OpenClawConfig,
+} from 'openclaw/plugin-sdk';
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  buildChannelConfigSchema,
+  formatPairingApproveHint,
+  setAccountEnabledInConfigSection,
+  deleteAccountFromConfigSection,
+  applyAccountNameToChannelSection,
+} from 'openclaw/plugin-sdk';
+import { z } from 'zod';
+import type { ResolvedZaloxAccount } from './types.js';
+import {
+  listAccountIds,
+  resolveDefaultAccountId,
+  resolveAccount,
+  resolveProfile,
+} from './accounts.js';
+import { getOrCreateApi, getCachedApi, hasCredentials, clearApi } from './client.js';
+import { sendText, sendMedia } from './send.js';
+import { startInProcessListener } from './listener.js';
+
+// ── Metadata ─────────────────────────────────────────────────────────────────
+
+const meta = {
+  id: 'zalox',
+  label: 'Zalo (ZaloX)',
+  selectionLabel: 'Zalo Personal (ZaloX in-process)',
+  docsPath: '/channels/zalouser',
+  docsLabel: 'zalox',
+  blurb: 'Zalo personal account — in-process, single login, no session conflicts.',
+  aliases: ['zx'],
+  order: 84,
+  preferOver: ['zalouser'],
+  quickstartAllowFrom: true,
+};
+
+// ── Config Schema (Zod) ──────────────────────────────────────────────────────
+
+const allowFromEntry = z.union([z.string(), z.number()]);
+
+const zaloxAccountSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  credentialsPath: z.string().optional(),
+  dmPolicy: z.enum(['pairing', 'allowlist', 'open', 'disabled']).optional(),
+  allowFrom: z.array(allowFromEntry).optional(),
+  groupPolicy: z.enum(['disabled', 'allowlist', 'open']).optional(),
+  groups: z.object({}).catchall(z.object({
+    allow: z.boolean().optional(),
+    enabled: z.boolean().optional(),
+  })).optional(),
+});
+
+const ZaloxConfigSchema = zaloxAccountSchema.extend({
+  accounts: z.object({}).catchall(zaloxAccountSchema).optional(),
+  defaultAccount: z.string().optional(),
+  retryOnClose: z.boolean().optional(),
+});
+
+// ── Dock (lightweight interface) ─────────────────────────────────────────────
+
+export const zaloxDock: ChannelDock = {
+  id: 'zalox',
+  capabilities: {
+    chatTypes: ['direct', 'group'],
+    media: true,
+    blockStreaming: true,
+  },
+  outbound: { textChunkLimit: 2000 },
+  config: {
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveAccount({ cfg, accountId }).config.allowFrom ?? []).map(String),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom.map((e) => String(e).trim().toLowerCase()).filter(Boolean),
+  },
+  groups: {
+    resolveRequireMention: () => true,
+  },
+  threading: {
+    resolveReplyToMode: () => 'off',
+  },
+};
+
+// ── Channel Plugin ───────────────────────────────────────────────────────────
+
+export const zaloxPlugin: ChannelPlugin<ResolvedZaloxAccount> = {
+  id: 'zalox',
+  meta,
+  capabilities: {
+    chatTypes: ['direct', 'group'],
+    media: true,
+    reactions: false,
+    threads: false,
+    polls: false,
+    nativeCommands: false,
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ['channels.zalox'] },
+  configSchema: buildChannelConfigSchema(ZaloxConfigSchema),
+
+  // ── Config ────────────────────────────────────────────
+  config: {
+    listAccountIds: (cfg) => listAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg,
+        sectionKey: 'zalox',
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg,
+        sectionKey: 'zalox',
+        accountId,
+        clearBaseFields: ['name', 'dmPolicy', 'allowFrom', 'groupPolicy', 'groups', 'credentialsPath'],
+      }),
+    isConfigured: async (account) => {
+      // Offline check — just verify credentials file exists
+      const profile = resolveProfile(account.config, account.accountId);
+      return hasCredentials(profile);
+    },
+    describeAccount: (account): ChannelAccountSnapshot => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: undefined,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveAccount({ cfg, accountId }).config.allowFrom ?? []).map(String),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom.map((e) => String(e).trim().toLowerCase()).filter(Boolean),
+  },
+
+  // ── Security ──────────────────────────────────────────
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean((cfg.channels?.zalox as any)?.accounts?.[resolvedAccountId]);
+      const basePath = useAccountPath
+        ? `channels.zalox.accounts.${resolvedAccountId}.`
+        : 'channels.zalox.';
+      return {
+        policy: account.config.dmPolicy ?? 'pairing',
+        allowFrom: account.config.allowFrom ?? [],
+        policyPath: `${basePath}dmPolicy`,
+        allowFromPath: basePath,
+        approveHint: formatPairingApproveHint('zalox'),
+        normalizeEntry: (raw: string) => raw.replace(/^(zalox|zx):/i, ''),
+      };
+    },
+  },
+
+  // ── Groups ────────────────────────────────────────────
+  groups: {
+    resolveRequireMention: () => true,
+  },
+
+  // ── Threading ─────────────────────────────────────────
+  threading: {
+    resolveReplyToMode: () => 'off',
+  },
+
+  // ── Setup ─────────────────────────────────────────────
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({ cfg, channelKey: 'zalox', accountId, name }),
+    validateInput: () => null,
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg,
+        channelKey: 'zalox',
+        accountId,
+        name: input.name,
+      });
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...namedConfig,
+          channels: {
+            ...namedConfig.channels,
+            zalox: { ...namedConfig.channels?.zalox, enabled: true },
+          },
+        } as OpenClawConfig;
+      }
+      return {
+        ...namedConfig,
+        channels: {
+          ...namedConfig.channels,
+          zalox: {
+            ...namedConfig.channels?.zalox,
+            enabled: true,
+            accounts: {
+              ...(namedConfig.channels?.zalox as any)?.accounts,
+              [accountId]: {
+                ...(namedConfig.channels?.zalox as any)?.accounts?.[accountId],
+                enabled: true,
+              },
+            },
+          },
+        },
+      } as OpenClawConfig;
+    },
+  },
+
+  // ── Messaging ─────────────────────────────────────────
+  messaging: {
+    normalizeTarget: (raw) => raw?.trim()?.replace(/^(zalox|zx):/i, '') || undefined,
+    targetResolver: {
+      looksLikeId: (raw) => /^\d{3,}$/.test(raw.trim()),
+      hint: '<threadId>',
+    },
+  },
+
+  // ── Pairing ───────────────────────────────────────────
+  pairing: {
+    idLabel: 'zaloxUserId',
+    normalizeAllowEntry: (entry) => entry.replace(/^(zalox|zx):/i, ''),
+    notifyApproval: async ({ cfg, id }) => {
+      const account = resolveAccount({ cfg });
+      const profile = resolveProfile(account.config, account.accountId);
+      const result = await sendText(id, 'Your pairing request has been approved.', { profile });
+      if (!result.ok) throw new Error(result.error || 'Failed to notify');
+    },
+  },
+
+  // ── Outbound ──────────────────────────────────────────
+  outbound: {
+    deliveryMode: 'direct',
+    textChunkLimit: 2000,
+    sendText: async ({ to, text, accountId, cfg }) => {
+      const account = resolveAccount({ cfg, accountId });
+      const profile = resolveProfile(account.config, account.accountId);
+      const result = await sendText(to, text, { profile });
+      return {
+        channel: 'zalox',
+        ok: result.ok,
+        messageId: result.messageId ?? '',
+        error: result.error ? new Error(result.error) : undefined,
+      };
+    },
+    sendMedia: async ({ to, text, mediaUrl, accountId, cfg }) => {
+      const account = resolveAccount({ cfg, accountId });
+      const profile = resolveProfile(account.config, account.accountId);
+      const result = await sendMedia(to, text ?? '', mediaUrl ?? '', { profile });
+      return {
+        channel: 'zalox',
+        ok: result.ok,
+        messageId: result.messageId ?? '',
+        error: result.error ? new Error(result.error) : undefined,
+      };
+    },
+  },
+
+  // ── Status ────────────────────────────────────────────
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+    }),
+    probeAccount: async ({ account }) => {
+      // Probe by checking cached API — NO login, NO subprocess
+      const profile = resolveProfile(account.config, account.accountId);
+      const cached = getCachedApi(profile);
+      if (cached) {
+        return { ok: true, user: { userId: cached.ownId, displayName: cached.displayName } };
+      }
+      // Not running = not OK
+      return { ok: false, error: 'Listener not active' };
+    },
+    buildAccountSnapshot: async ({ account, runtime }) => {
+      const profile = resolveProfile(account.config, account.accountId);
+      const configured = hasCredentials(profile);
+      return {
+        accountId: account.accountId,
+        name: account.name,
+        enabled: account.enabled,
+        configured,
+        running: runtime?.running ?? false,
+        lastStartAt: runtime?.lastStartAt ?? null,
+        lastStopAt: runtime?.lastStopAt ?? null,
+        lastError: configured ? (runtime?.lastError ?? null) : 'No credentials found',
+        lastInboundAt: runtime?.lastInboundAt ?? null,
+        lastOutboundAt: runtime?.lastOutboundAt ?? null,
+        dmPolicy: account.config.dmPolicy ?? 'pairing',
+      };
+    },
+  },
+
+  // ── Gateway (start/stop) ──────────────────────────────
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      const profile = resolveProfile(account.config, account.accountId);
+
+      ctx.log?.info(`[${account.accountId}] ZaloX: logging in (profile=${profile})...`);
+
+      // Login once — cached for entire gateway lifetime
+      const entry = await getOrCreateApi(profile);
+      const userLabel = entry.displayName ? ` (${entry.displayName})` : '';
+
+      ctx.setStatus({
+        accountId: account.accountId,
+        user: { userId: entry.ownId, displayName: entry.displayName },
+      });
+
+      ctx.log?.info(`[${account.accountId}] ZaloX: logged in as ${entry.ownId}${userLabel}`);
+
+      // Start in-process listener
+      return startInProcessListener({
+        account,
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        api: entry.api,
+        ownId: entry.ownId,
+        profile,
+        abortSignal: ctx.abortSignal,
+        statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),
+      });
+    },
+  },
+};

package/src/client.ts

@@ -0,0 +1,131 @@
+/**
+ * ZaloX Plugin — In-process Zalo client
+ * 
+ * Single login, cached API instance. No subprocess spawning.
+ * Solves the "every zca command kills the listener" problem.
+ */
+
+import { Zalo, type API, type Credentials } from 'zca-js';
+import { existsSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import type { CachedApiEntry } from './types.js';
+
+/**
+ * Image metadata getter for zca-js 2.x
+ * Required for sending images via uploadAttachment.
+ */
+async function imageMetadataGetter(filePath: string): Promise<{ width: number; height: number; size: number } | null> {
+  try {
+    const sharp = (await import('sharp')).default;
+    const metadata = await sharp(filePath).metadata();
+    const stat = statSync(filePath);
+    return {
+      width: metadata.width || 0,
+      height: metadata.height || 0,
+      size: stat.size,
+    };
+  } catch {
+    // Fallback: just return file size with dummy dimensions
+    try {
+      const stat = statSync(filePath);
+      return { width: 1024, height: 768, size: stat.size };
+    } catch {
+      return null;
+    }
+  }
+}
+
+// Global API instance cache (per account/profile)
+const apiCache = new Map<string, CachedApiEntry>();
+
+/**
+ * Get or create an API instance for a profile.
+ * Reuses cached instance — only logs in once per profile.
+ */
+export async function getOrCreateApi(profile: string): Promise<CachedApiEntry> {
+  const cached = apiCache.get(profile);
+  if (cached) return cached;
+
+  const credentialsPath = resolveCredentialsPath(profile);
+  if (!existsSync(credentialsPath)) {
+    throw new Error(`No credentials found for profile "${profile}" at ${credentialsPath}`);
+  }
+
+  const credentials: Credentials = JSON.parse(readFileSync(credentialsPath, 'utf-8'));
+  if (!credentials.cookie || !credentials.imei || !credentials.userAgent) {
+    throw new Error(`Incomplete credentials for profile "${profile}"`);
+  }
+
+  const zalo = new Zalo({ logging: false, imageMetadataGetter } as any);
+  const api = await zalo.login(credentials);
+
+  // Get own user info
+  let ownId = '';
+  let displayName: string | undefined;
+  let avatar: string | undefined;
+  try {
+    const info = await api.fetchAccountInfo();
+    ownId = String((info as any).userId || '');
+    displayName = (info as any).displayName || (info as any).zaloName;
+    avatar = (info as any).avatar;
+  } catch {
+    // Try to get from context
+    try {
+      const ctx = await api.getContext();
+      ownId = String((ctx as any).uid || '');
+    } catch {}
+  }
+
+  const entry: CachedApiEntry = {
+    api,
+    ownId,
+    displayName,
+    avatar,
+    connectedAt: Date.now(),
+  };
+
+  apiCache.set(profile, entry);
+  return entry;
+}
+
+/**
+ * Get cached API instance (no login if not cached)
+ */
+export function getCachedApi(profile: string): CachedApiEntry | undefined {
+  return apiCache.get(profile);
+}
+
+/**
+ * Check if credentials exist for a profile (offline, no login)
+ */
+export function hasCredentials(profile: string): boolean {
+  return existsSync(resolveCredentialsPath(profile));
+}
+
+/**
+ * Clear cached API instance
+ */
+export function clearApi(profile: string): void {
+  apiCache.delete(profile);
+}
+
+function resolveOpenClawDir(): string {
+  return process.env.OPENCLAW_DIR || join(homedir(), '.openclaw');
+}
+
+export function resolveCredentialsPath(profile: string): string {
+  // 1. Persistent path inside .openclaw (survives container restarts)
+  const openclawPath = join(resolveOpenClawDir(), 'zalox', 'profiles', `${profile}.json`);
+  if (existsSync(openclawPath)) return openclawPath;
+
+  // 2. Legacy ZaloX config path
+  const zaloxPath = join(homedir(), '.config', 'zalox', 'profiles', `${profile}.json`);
+  if (existsSync(zaloxPath)) return zaloxPath;
+
+  // 3. Legacy zca-cli path
+  const zcaPath = join(homedir(), '.config', 'zca-cli-nodejs', 'profiles', `${profile}.json`);
+  if (existsSync(zcaPath)) return zcaPath;
+
+  return openclawPath; // Default to persistent .openclaw path
+}

package/src/listener.ts

@@ -0,0 +1,377 @@
+/**
+ * ZaloX Plugin — In-process message listener
+ *
+ * Uses zca-js API directly. Handles:
+ * - Message events (text, image, sticker)
+ * - DM policy
+ * - Pairing
+ * - Agent routing
+ * - Image downloading
+ */
+
+import { type API, Reactions, ThreadType } from 'zca-js';
+import type { OpenClawConfig, RuntimeEnv } from 'openclaw/plugin-sdk';
+import { mergeAllowlist } from 'openclaw/plugin-sdk';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join, extname } from 'path';
+import { randomUUID } from 'crypto';
+import { homedir } from 'os';
+import type { ResolvedZaloxAccount } from './types.js';
+import { sendText } from './send.js';
+import { resolveCredentialsPath } from './client.js';
+
+let pluginRuntime: any = null;
+
+export function setPluginRuntime(rt: any): void {
+  pluginRuntime = rt;
+}
+
+function getRuntime(): any {
+  if (!pluginRuntime) throw new Error('ZaloX runtime not initialized');
+  return pluginRuntime;
+}
+
+export type ListenerOptions = {
+  account: ResolvedZaloxAccount;
+  config: OpenClawConfig;
+  runtime: RuntimeEnv;
+  api: API;
+  ownId: string;
+  profile: string;
+  abortSignal: AbortSignal;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+};
+
+function isSenderAllowed(senderId: string, allowFrom: string[]): boolean {
+  if (allowFrom.includes('*')) return true;
+  const normalized = senderId.toLowerCase();
+  return allowFrom.some((entry) => {
+    const clean = entry.toLowerCase().replace(/^(zalox|zx):/i, '');
+    return clean === normalized;
+  });
+}
+
+function getInboundMediaDir(): string {
+  const dir = process.env.OPENCLAW_MEDIA_INBOUND || join(homedir(), '.openclaw', 'media', 'inbound');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+async function downloadZaloMedia(url: string, profile: string, filename?: string): Promise<string | null> {
+  try {
+    const credentialsPath = resolveCredentialsPath(profile);
+    const creds = JSON.parse(readFileSync(credentialsPath, 'utf-8'));
+    
+    // Zalo media URLs usually require cookies
+    const headers: Record<string, string> = {
+      'User-Agent': creds.userAgent || 'Mozilla/5.0',
+      'Cookie': typeof creds.cookie === 'object' ? JSON.stringify(creds.cookie) : String(creds.cookie),
+    };
+
+    const res = await fetch(url, { headers });
+    if (!res.ok) return null;
+
+    const buffer = await res.arrayBuffer();
+    const ext = extname(url).split('?')[0] || '.jpg';
+    const name = filename || `zalox-${Date.now()}-${randomUUID().slice(0, 8)}${ext}`;
+    const path = join(getInboundMediaDir(), name);
+    
+    writeFileSync(path, Buffer.from(buffer));
+    console.log(`[ZaloX] Downloaded media to ${path}`); // DEBUG
+    return path;
+  } catch (err) {
+    console.error(`[ZaloX] Download media failed: ${err}`); // DEBUG
+    return null;
+  }
+}
+
+async function processMessage(
+  message: { 
+    threadId: string; 
+    content: string; 
+    msgType: number;
+    timestamp?: number; 
+    msgId?: string; 
+    isGroup: boolean; 
+    senderId: string; 
+    senderName?: string; 
+    groupName?: string;
+    mediaUrl?: string;
+  },
+  account: ResolvedZaloxAccount,
+  config: OpenClawConfig,
+  runtime: RuntimeEnv,
+  profile: string,
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void,
+): Promise<void> {
+  const core = getRuntime();
+  const { threadId, content, msgType, timestamp, isGroup, senderId, senderName, groupName, mediaUrl } = message;
+
+  // Allow empty content if it's an image
+  if (!content?.trim() && !mediaUrl) return;
+
+  const chatId = threadId;
+  const rawBody = content.trim();
+
+  // Handle media download
+  let mediaPath: string | undefined;
+  if (mediaUrl) {
+    const downloaded = await downloadZaloMedia(mediaUrl, profile);
+    if (downloaded) mediaPath = downloaded;
+  }
+
+  // DM policy check
+  const configAllowFrom = (account.config.allowFrom ?? []).map(String);
+  const dmPolicy = account.config.dmPolicy ?? 'pairing';
+
+  const shouldComputeAuth = core.channel.commands.shouldComputeCommandAuthorized(rawBody, config);
+  const storeAllowFrom =
+    !isGroup && (dmPolicy !== 'open' || shouldComputeAuth)
+      ? await core.channel.pairing.readAllowFromStore('zalox').catch(() => [] as string[])
+      : [];
+  const effectiveAllowFrom = [...configAllowFrom, ...storeAllowFrom];
+  const senderAllowedForCommands = isSenderAllowed(senderId, effectiveAllowFrom);
+  const useAccessGroups = config.commands?.useAccessGroups !== false;
+  const commandAuthorized = shouldComputeAuth
+    ? core.channel.commands.resolveCommandAuthorizedFromAuthorizers({
+        useAccessGroups,
+        authorizers: [\n          { configured: effectiveAllowFrom.length > 0, allowed: senderAllowedForCommands },\n        ],\n      })
+    : undefined;
+
+  if (!isGroup) {
+    if (dmPolicy === 'disabled') {
+      runtime.log?.(`[zalox] Blocked DM from ${senderId} (dmPolicy=disabled)`);
+      return;
+    }
+    if (dmPolicy !== 'open') {
+      if (!senderAllowedForCommands) {
+        if (dmPolicy === 'pairing') {
+          const { code, created } = await core.channel.pairing.upsertPairingRequest({
+            channel: 'zalox',
+            id: senderId,
+            meta: { name: senderName || undefined },
+          });
+          if (created) {
+            runtime.log?.(`[zalox] pairing request sender=${senderId}`);
+            try {
+              await sendText(
+                chatId,
+                core.channel.pairing.buildPairingReply({
+                  channel: 'zalox',
+                  idLine: `Your Zalo user id: ${senderId}`,
+                  code,
+                }),
+                { profile },
+              );
+              statusSink?.({ lastOutboundAt: Date.now() });
+            } catch (err) {
+              runtime.error?.(`[zalox] pairing reply failed: ${String(err)}`);
+            }
+          }
+        }
+        return;
+      }
+    }
+  }
+
+  // Group command authorization
+  if (
+    isGroup &&
+    core.channel.commands.isControlCommandMessage(rawBody, config) &&
+    commandAuthorized !== true
+  ) {
+    return;
+  }
+
+  // Route to agent
+  const peer = isGroup
+    ? { kind: 'group' as const, id: chatId }
+    : { kind: 'dm' as const, id: senderId };
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: config,
+    channel: 'zalox',
+    accountId: account.accountId,
+    peer,
+  });
+
+  const fromLabel = isGroup ? `group:${chatId}` : senderName || `user:${senderId}`;
+  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: 'Zalo (ZaloX)',
+    from: fromLabel,
+    timestamp: timestamp ? timestamp * 1000 : undefined,
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: rawBody || (mediaPath ? '[Image]' : ''),
+  });
+
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: body,
+    RawBody: rawBody,
+    CommandBody: rawBody,
+    From: isGroup ? `zalox:group:${chatId}` : `zalox:${senderId}`,
+    To: `zalox:${chatId}`,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: isGroup ? 'group' : 'direct',
+    ConversationLabel: fromLabel,
+    SenderName: senderName || undefined,
+    SenderId: senderId,
+    CommandAuthorized: commandAuthorized,
+    Provider: 'zalox',
+    Surface: 'zalox',
+    MessageSid: message.msgId ?? `${timestamp}`,
+    OriginatingChannel: 'zalox',
+    OriginatingTo: `zalox:${chatId}`,
+    MediaPath: mediaPath, // Pass media path here
+  });
+
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (err: unknown) => {
+      runtime.error?.(`[zalox] session meta error: ${String(err)}`);
+    },
+  });
+
+  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg: config,
+    dispatcherOptions: {
+      deliver: async (payload: any) => {
+        const text = payload.text ?? '';
+        if (!text) return;
+
+        const tableMode = core.channel.text.resolveMarkdownTableMode({
+          cfg: config,
+          channel: 'zalox',
+          accountId: account.accountId,
+        });
+        const converted = core.channel.text.convertMarkdownTables(text, tableMode ?? 'code');
+        const chunkMode = core.channel.text.resolveChunkMode(config, 'zalox', account.accountId);
+        const chunks = core.channel.text.chunkMarkdownTextWithMode(converted, 2000, chunkMode);
+
+        for (const chunk of chunks) {
+          try {
+            await sendText(chatId, chunk, { profile, isGroup });
+            statusSink?.({ lastOutboundAt: Date.now() });
+          } catch (err) {
+            runtime.error?.(`[zalox] send failed: ${String(err)}`);
+          }
+        }
+      },
+      onError: (err: unknown, info: any) => {
+        runtime.error?.(`[${account.accountId}] ZaloX ${info.kind} reply failed: ${String(err)}`);
+      },
+    },
+  });
+}
+
+export async function startInProcessListener(
+  options: ListenerOptions,
+): Promise<{ stop: () => void }> {
+  const { account, config, runtime, api, ownId, profile, abortSignal, statusSink } = options;
+  let stopped = false;
+
+  const listener = api.listener;
+
+  // Handle incoming messages
+  listener.on('message', (msg: any) => {
+    if (stopped || abortSignal.aborted) return;
+
+    const data = msg.data || msg;
+    const isGroup = msg.type === 1;
+    const senderId = data.uidFrom ? String(data.uidFrom) : '';
+    
+    runtime.log?.(`[${account.accountId}] ZaloX: inbound raw data: ${JSON.stringify(data)}`); // DEBUG LOG
+
+    // Skip own messages
+    if (senderId === ownId) return;
+
+    // Determine message type and media
+    // zca-js: type 1=group text, direct text unknown (usually also content)
+    // Images often come with msgType=2 or data.url
+    const msgType = data.msgType || 0;
+    let mediaUrl = undefined;
+    
+    // DEBUG: Log image detection logic
+    if (data.url) runtime.log?.(`[${account.accountId}] ZaloX: found URL ${data.url} (msgType=${msgType})`);
+
+    if (msgType === 2 && data.url) { // Image
+      mediaUrl = data.url;
+    } else if (msgType === 3 && data.url) { // Sticker (treat as media if needed, but usually just url)
+      // mediaUrl = data.url; // Optional: download stickers?
+    } else if (data.url && (data.url.includes('.jpg') || data.url.includes('.png'))) {
+      mediaUrl = data.url;
+    }
+
+    // Group messages: only respond when bot is mentioned (@tagged)
+    // UNLESS it's a media message — we might want to analyze all images? 
+    // No, keep same policy for now to avoid spam.
+    if (isGroup) {
+      const mentions = data.mentions || data.mentionIds || [];
+      const content = typeof data.content === 'string' ? data.content : (data.msg || '');
+      
+      const isMentioned = Array.isArray(mentions)
+        ? mentions.some((m: any) => String(m.uid || m.id || m) === ownId)
+        : false;
+      const textMention = content.includes(`@${account.name || 'Tiệp Lê'}`);
+      
+      // If has media, we might want to check if the caption mentions bot
+      if (!isMentioned && !textMention) {
+        return;
+      }
+    }
+
+    statusSink?.({ lastInboundAt: Date.now() });
+
+    const threadId = isGroup
+      ? String(data.idTo || data.threadId || '')
+      : senderId;
+
+    const normalized = {
+      threadId,
+      msgId: String(data.msgId || data.cliMsgId || ''),
+      content: (() => {
+        let c = data.content || data.msg || '';
+        if (typeof c !== 'string') return '';
+        if (isGroup) {
+          c = c.replace(new RegExp(`@${account.name || 'Tiệp Lê'}\\s*`, 'gi'), '').trim();
+        }
+        return c;
+      })(),
+      msgType,
+      mediaUrl,
+      timestamp: data.ts ? Math.floor(data.ts / 1000) : Math.floor(Date.now() / 1000),
+      isGroup,
+      senderId,
+      senderName: data.dName || data.senderName || undefined,
+      groupName: data.threadName || data.groupName || undefined,
+    };
+
+    if (!normalized.content?.trim() && !normalized.mediaUrl) return;
+
+    runtime.log?.(`[${account.accountId}] ZaloX: inbound from ${senderId} (type=${msgType} media=${!!mediaUrl})`);
+
+    // React with ❤️
+    try {
+      const reactThreadType = isGroup ? ThreadType.Group : ThreadType.User;
+      api.addReaction(Reactions.HEART, {
+        threadId: normalized.threadId,
+        type: reactThreadType,
+        data: {
+          msgId: String(data.msgId || ''),\n          cliMsgId: String(data.cliMsgId || ''),
+        },
+      }).catch((err: any) => {
+        runtime.error?.(`[${account.accountId}] ZaloX reaction failed: ${String(err)}`);
+      });
+    } catch {}\n\n    processMessage(normalized, account, config, runtime, profile, statusSink).catch((err) => {\n      runtime.error?.(`[${account.accountId}] ZaloX process error: ${String(err)}`);\n    });\n  });\n\n  // Handle errors\n  listener.on('error', (err: any) => {\n    runtime.error?.(`[${account.accountId}] ZaloX listener error: ${err.message || err}`);\n  });\n\n  // Start WebSocket listener with retry\n  listener.start({ retryOnClose: true });\n  runtime.log?.(`[${account.accountId}] ZaloX: WebSocket listener started`);\n\n  const stop = () => {\n    stopped = true;\n    try {\n      listener.stop();\n    } catch {}\n  };\n\n  abortSignal.addEventListener('abort', stop, { once: true });\n\n  return { stop };\n}\n

package/src/send.ts

@@ -0,0 +1,121 @@
+/**
+ * ZaloX Plugin — Send messages via cached API
+ * 
+ * No subprocess spawning. Uses cached zca-js API instance directly.
+ * Supports text, images (local files + URLs), and other attachments.
+ */
+
+import { ThreadType } from 'zca-js';
+import { getCachedApi } from './client.js';
+import { existsSync, writeFileSync, unlinkSync } from 'fs';
+import { resolve } from 'path';
+
+export type SendResult = {
+  ok: boolean;
+  messageId?: string;
+  error?: string;
+};
+
+export async function sendText(
+  threadId: string,
+  text: string,
+  options: { profile: string; isGroup?: boolean } = { profile: 'default' },
+): Promise<SendResult> {
+  if (!threadId?.trim()) {
+    return { ok: false, error: 'No threadId provided' };
+  }
+  if (!text?.trim()) {
+    return { ok: false, error: 'No text provided' };
+  }
+
+  const cached = getCachedApi(options.profile);
+  if (!cached) {
+    return { ok: false, error: `No active API session for profile "${options.profile}". Listener may not be running.` };
+  }
+
+  try {
+    const type = options.isGroup ? ThreadType.Group : ThreadType.User;
+    const result = await cached.api.sendMessage(text.slice(0, 2000), threadId.trim(), type);
+    const msgId = result?.message?.msgId ? String(result.message.msgId) : undefined;
+    return { ok: true, messageId: msgId };
+  } catch (err: any) {
+    return { ok: false, error: err.message || String(err) };
+  }
+}
+
+export async function sendMedia(
+  threadId: string,
+  text: string,
+  mediaUrl: string,
+  options: { profile: string; isGroup?: boolean } = { profile: 'default' },
+): Promise<SendResult> {
+  if (!threadId?.trim()) {
+    return { ok: false, error: 'No threadId provided' };
+  }
+
+  const cached = getCachedApi(options.profile);
+  if (!cached) {
+    return { ok: false, error: `No active API session for profile "${options.profile}". Listener may not be running.` };
+  }
+
+  try {
+    const type = options.isGroup ? ThreadType.Group : ThreadType.User;
+
+    // Check if mediaUrl is a local file path
+    let filePath: string | null = null;
+    if (mediaUrl && !mediaUrl.startsWith('http')) {
+      const resolved = resolve(mediaUrl);
+      if (existsSync(resolved)) {
+        filePath = resolved;
+      }
+    }
+
+    if (filePath) {
+      // Send with local file attachment
+      const result = await cached.api.sendMessage(
+        { msg: text || '', attachments: [filePath] },
+        threadId.trim(),
+        type,
+      );
+      const msgId = result?.message?.msgId ? String(result.message.msgId) : undefined;
+      return { ok: true, messageId: msgId };
+    }
+
+    // If it's a URL, download first then send as attachment
+    if (mediaUrl?.startsWith('http')) {
+      let tmpPath: string | null = null;
+      try {
+        const response = await fetch(mediaUrl);
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        const buffer = Buffer.from(await response.arrayBuffer());
+        
+        const urlPath = new URL(mediaUrl).pathname;
+        const ext = urlPath.split('.').pop()?.toLowerCase() || 'jpg';
+        const filename = `zalox_attach_${Date.now()}.${ext}`;
+        tmpPath = `/tmp/${filename}`;
+        writeFileSync(tmpPath, buffer);
+        
+        const result = await cached.api.sendMessage(
+          { msg: text || '', attachments: [tmpPath] },
+          threadId.trim(),
+          type,
+        );
+        
+        const msgId = result?.message?.msgId ? String(result.message.msgId) : undefined;
+        return { ok: true, messageId: msgId };
+      } catch (dlErr: any) {
+        // Fallback: send text with URL as link
+        const fullText = text ? `${text}\n${mediaUrl}` : mediaUrl;
+        return sendText(threadId, fullText, options);
+      } finally {
+        if (tmpPath) try { unlinkSync(tmpPath); } catch {}
+      }
+    }
+
+    // Fallback: send text only
+    const fullText = text ? `${text}\n${mediaUrl}` : mediaUrl;
+    return sendText(threadId, fullText, options);
+  } catch (err: any) {
+    return { ok: false, error: err.message || String(err) };
+  }
+}

package/src/types.ts

@@ -0,0 +1,76 @@
+/**
+ * ZaloX Plugin — Type definitions
+ *
+ * Mirrors the zalouser types but adapted for in-process zca-js usage.
+ * No subprocess types needed — everything runs in-process.
+ */
+
+import type { API } from "zca-js";
+
+// ── Account config (per-account under channels.zalox.accounts.<id>) ──────────
+
+export type ZaloxAccountConfig = {
+  enabled?: boolean;
+  name?: string;
+  credentialsPath?: 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;
+};
+
+// ── Top-level config shape (channels.zalox) ──────────────────────────────────
+
+export type ZaloxConfig = {
+  enabled?: boolean;
+  name?: string;
+  credentialsPath?: 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, ZaloxAccountConfig>;
+};
+
+// ── Resolved account (after config merge) ────────────────────────────────────
+
+export type ResolvedZaloxAccount = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  credentialsPath: string;
+  config: ZaloxAccountConfig;
+};
+
+// ── Cached API instance per account ──────────────────────────────────────────
+
+export type CachedApiEntry = {
+  api: API;
+  ownId: string;
+  displayName?: string;
+  avatar?: string;
+  connectedAt: number;
+};
+
+// ── Inbound message (normalized from zca-js Message types) ───────────────────
+
+export type ZaloxInboundMessage = {
+  threadId: string;
+  msgId?: string;
+  content: string;
+  timestamp: number;
+  isGroup: boolean;
+  senderId: string;
+  senderName?: string;
+  groupName?: string;
+  isSelf: boolean;
+};