openzca 0.1.22 → 0.1.24

package/README.md

@@ -272,12 +272,38 @@ Listener resilience override:
 - `OPENZCA_LISTEN_DOWNLOAD_QUOTE_MEDIA`: download quoted attachment URLs (if present) into inbound media cache.
   - Default: enabled.
   - Set to `0` to keep only quote metadata/URLs without downloading.
+- `OPENZCA_LISTEN_ENFORCE_SINGLE_OWNER`: enforce one `listen` owner process per profile.
+  - Default: enabled.
+  - Set to `0` to allow multiple listeners on the same profile (not recommended).
+- `OPENZCA_LISTEN_IPC`: expose local IPC socket from `listen` so `msg upload` can reuse the active websocket session.
+  - Default: enabled.
+  - Set to `0` to disable IPC.
+- `OPENZCA_LISTEN_KEEPALIVE_RESTART_DELAY_MS`: when `--keep-alive` is on, restart listener after close code `1000`/`3000` with this delay.
+  - Default: `2000`.
+- `OPENZCA_LISTEN_KEEPALIVE_RESTART_ON_ANY_CLOSE`: force keepalive fallback restart for any close code.
+  - Default: disabled.
+  - Set to `1` if your environment closes with non-retry codes.
 
 Supervised mode notes:
 
 - Use `listen --supervised --raw` when an external process manager owns restart logic.
 - In supervised mode, internal websocket retry ownership is disabled (equivalent to forcing `retryOnClose=false`).
 
+Upload/listener coordination overrides:
+
+- `OPENZCA_UPLOAD_IPC`: try upload via active listener IPC first.
+  - Default: enabled.
+  - Set to `0` to disable IPC path.
+- `OPENZCA_UPLOAD_IPC_CONNECT_TIMEOUT_MS`: timeout for connecting to listener IPC socket.
+  - Default: `1000`.
+- `OPENZCA_UPLOAD_IPC_TIMEOUT_MS`: timeout waiting for listener IPC upload response.
+  - Default: `OPENZCA_UPLOAD_TIMEOUT_MS + 5000`.
+- `OPENZCA_UPLOAD_IPC_HANDLER_TIMEOUT_MS`: timeout applied by listener IPC while executing upload.
+  - Default: same as `OPENZCA_UPLOAD_TIMEOUT_MS` (120000 if unset).
+- `OPENZCA_UPLOAD_ENFORCE_SINGLE_OWNER`: when an active listener owner exists but IPC is unavailable, fail fast instead of starting a second listener.
+  - Default: enabled.
+  - Set to `0` to allow fallback listener startup (may disconnect active listener due duplicate websocket ownership).
+
 ### account — Multi-account profiles
 
 | Command | Description |

package/dist/cli.js

@@ -5,6 +5,7 @@ import { createRequire } from "module";
 import { spawn as spawn2 } from "child_process";
 import fsSync from "fs";
 import fs4 from "fs/promises";
+import net from "net";
 import os3 from "os";
 import path4 from "path";
 import util from "util";
@@ -739,6 +740,439 @@ function collectIdsFromCacheEntries(entries, keys) {
   }
   return ids;
 }
+function getListenerOwnerLockPath(profile) {
+  return path4.join(getProfileDir(profile), "listener-owner.json");
+}
+function getListenIpcSocketPath(profile) {
+  if (process.platform === "win32") {
+    const safe = profile.replace(/[^A-Za-z0-9_-]/g, "_");
+    return `\\\\.\\pipe\\openzca-listen-${safe}`;
+  }
+  return path4.join(getProfileDir(profile), "listen.sock");
+}
+function parsePositiveIntFromUnknown(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    return Math.trunc(value);
+  }
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number.parseInt(value.trim(), 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  return null;
+}
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    const code = error.code;
+    if (code === "EPERM") return true;
+    return false;
+  }
+}
+async function readListenerOwnerRecord(lockPath) {
+  try {
+    const raw = await fs4.readFile(lockPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const pid = parsePositiveIntFromUnknown(parsed.pid);
+    if (!pid) return null;
+    return {
+      pid,
+      profile: String(parsed.profile ?? ""),
+      sessionId: typeof parsed.sessionId === "string" ? parsed.sessionId : void 0,
+      startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : ""
+    };
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT") return null;
+    throw error;
+  }
+}
+async function readActiveListenerOwner(profile) {
+  const lockPath = getListenerOwnerLockPath(profile);
+  const record = await readListenerOwnerRecord(lockPath);
+  if (!record) {
+    await fs4.rm(lockPath, { force: true });
+    return null;
+  }
+  if (!isProcessAlive(record.pid)) {
+    await fs4.rm(lockPath, { force: true });
+    return null;
+  }
+  return record;
+}
+async function acquireListenerOwnerLock(profile, sessionId, command) {
+  await ensureProfile(profile);
+  const lockPath = getListenerOwnerLockPath(profile);
+  const record = {
+    pid: process.pid,
+    profile,
+    sessionId,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      await fs4.writeFile(lockPath, `${JSON.stringify(record, null, 2)}
+`, {
+        encoding: "utf8",
+        flag: "wx"
+      });
+      let released = false;
+      return {
+        lockPath,
+        release: async () => {
+          if (released) return;
+          released = true;
+          const current = await readListenerOwnerRecord(lockPath);
+          if (current && current.pid !== process.pid) return;
+          await fs4.rm(lockPath, { force: true });
+          writeDebugLine(
+            "listen.owner.released",
+            {
+              profile,
+              lockPath,
+              pid: process.pid
+            },
+            command
+          );
+        }
+      };
+    } catch (error) {
+      const code = error.code;
+      if (code !== "EEXIST") throw error;
+      const owner = await readActiveListenerOwner(profile);
+      if (owner) {
+        throw new Error(
+          `Another openzca listener already owns profile "${profile}" (pid ${owner.pid}).`
+        );
+      }
+      await fs4.rm(lockPath, { force: true });
+    }
+  }
+  throw new Error(`Unable to acquire listener ownership for profile "${profile}".`);
+}
+async function startListenerIpcServer(api, profile, sessionId, command) {
+  if (!parseBooleanFromEnv("OPENZCA_LISTEN_IPC", true)) {
+    writeDebugLine(
+      "listen.ipc.disabled",
+      {
+        profile
+      },
+      command
+    );
+    return null;
+  }
+  const socketPath = getListenIpcSocketPath(profile);
+  if (process.platform !== "win32") {
+    await fs4.rm(socketPath, { force: true });
+  }
+  const uploadTimeoutMs = parsePositiveIntFromEnv(
+    "OPENZCA_UPLOAD_IPC_HANDLER_TIMEOUT_MS",
+    parsePositiveIntFromEnv("OPENZCA_UPLOAD_TIMEOUT_MS", 12e4)
+  );
+  const server = net.createServer((socket) => {
+    socket.setEncoding("utf8");
+    let buffer = "";
+    let done = false;
+    const sendResponse = (response) => {
+      if (done) return;
+      done = true;
+      socket.end(`${JSON.stringify(response)}
+`);
+    };
+    const fail = (requestId, message) => {
+      sendResponse({
+        kind: "upload_result",
+        requestId,
+        ok: false,
+        error: message
+      });
+    };
+    const handleRequest = async (line) => {
+      if (done) return;
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        fail("", "Invalid JSON request.");
+        return;
+      }
+      if (parsed.kind !== "upload") {
+        fail(parsed.requestId || "", "Unsupported IPC request kind.");
+        return;
+      }
+      if (parsed.profile !== profile) {
+        fail(parsed.requestId, "Profile mismatch.");
+        return;
+      }
+      if (!parsed.threadId || !Array.isArray(parsed.attachments) || parsed.attachments.length === 0) {
+        fail(parsed.requestId, "Invalid upload payload.");
+        return;
+      }
+      const threadType = parsed.threadType === "group" ? ThreadType.Group : ThreadType.User;
+      const requestTimeoutMs = parsePositiveIntFromUnknown(parsed.uploadTimeoutMs) ?? uploadTimeoutMs;
+      writeDebugLine(
+        "listen.ipc.upload.start",
+        {
+          profile,
+          sessionId,
+          requestId: parsed.requestId,
+          threadId: parsed.threadId,
+          threadType: parsed.threadType,
+          attachmentCount: parsed.attachments.length,
+          timeoutMs: requestTimeoutMs
+        },
+        command
+      );
+      try {
+        const response = await withTimeout(
+          api.sendMessage(
+            {
+              msg: "",
+              attachments: parsed.attachments
+            },
+            parsed.threadId,
+            threadType
+          ),
+          requestTimeoutMs,
+          `Timed out waiting ${requestTimeoutMs}ms for IPC upload completion.`
+        );
+        sendResponse({
+          kind: "upload_result",
+          requestId: parsed.requestId,
+          ok: true,
+          response
+        });
+        writeDebugLine(
+          "listen.ipc.upload.done",
+          {
+            profile,
+            sessionId,
+            requestId: parsed.requestId,
+            threadId: parsed.threadId,
+            threadType: parsed.threadType
+          },
+          command
+        );
+      } catch (error) {
+        fail(parsed.requestId, toErrorText(error));
+        writeDebugLine(
+          "listen.ipc.upload.error",
+          {
+            profile,
+            sessionId,
+            requestId: parsed.requestId,
+            threadId: parsed.threadId,
+            threadType: parsed.threadType,
+            message: toErrorText(error)
+          },
+          command
+        );
+      }
+    };
+    socket.on("data", (chunk) => {
+      if (done) return;
+      buffer += chunk;
+      if (buffer.length > 2e6) {
+        fail("", "IPC request too large.");
+        return;
+      }
+      const newlineIndex = buffer.indexOf("\n");
+      if (newlineIndex === -1) return;
+      const line = buffer.slice(0, newlineIndex).trim();
+      buffer = "";
+      if (!line) {
+        fail("", "Empty IPC request.");
+        return;
+      }
+      void handleRequest(line);
+    });
+    socket.on("error", (error) => {
+      writeDebugLine(
+        "listen.ipc.socket_error",
+        {
+          profile,
+          sessionId,
+          message: toErrorText(error)
+        },
+        command
+      );
+    });
+  });
+  server.on("error", (error) => {
+    writeDebugLine(
+      "listen.ipc.server_error",
+      {
+        profile,
+        sessionId,
+        message: toErrorText(error)
+      },
+      command
+    );
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  writeDebugLine(
+    "listen.ipc.started",
+    {
+      profile,
+      sessionId,
+      socketPath
+    },
+    command
+  );
+  let closed = false;
+  return {
+    socketPath,
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      await new Promise((resolve) => {
+        server.close(() => resolve());
+      });
+      if (process.platform !== "win32") {
+        await fs4.rm(socketPath, { force: true });
+      }
+      writeDebugLine(
+        "listen.ipc.stopped",
+        {
+          profile,
+          sessionId,
+          socketPath
+        },
+        command
+      );
+    }
+  };
+}
+async function tryUploadViaListenerIpc(profile, threadId, threadType, attachments, command) {
+  if (!parseBooleanFromEnv("OPENZCA_UPLOAD_IPC", true)) {
+    return { handled: false, reason: "ipc_disabled" };
+  }
+  const socketPath = getListenIpcSocketPath(profile);
+  const requestId = `${Date.now().toString(36)}-${Math.random().toString(16).slice(2, 10)}`;
+  const connectTimeoutMs = parsePositiveIntFromEnv("OPENZCA_UPLOAD_IPC_CONNECT_TIMEOUT_MS", 1e3);
+  const requestTimeoutMs = parsePositiveIntFromEnv(
+    "OPENZCA_UPLOAD_IPC_TIMEOUT_MS",
+    parsePositiveIntFromEnv("OPENZCA_UPLOAD_TIMEOUT_MS", 12e4) + 5e3
+  );
+  writeDebugLine(
+    "msg.upload.ipc.try",
+    {
+      profile,
+      threadId,
+      threadType: threadType === ThreadType.Group ? "group" : "user",
+      attachmentCount: attachments.length,
+      socketPath,
+      requestId,
+      connectTimeoutMs,
+      requestTimeoutMs
+    },
+    command
+  );
+  return await new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    let connected = false;
+    let settled = false;
+    let responseBuffer = "";
+    let requestSent = false;
+    const finish = (result, error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(connectTimer);
+      clearTimeout(requestTimer);
+      if (!socket.destroyed) {
+        socket.destroy();
+      }
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve(result ?? { handled: false, reason: "unknown" });
+    };
+    const connectTimer = setTimeout(() => {
+      finish(void 0, new Error(`Timed out waiting ${connectTimeoutMs}ms to connect upload IPC.`));
+    }, connectTimeoutMs);
+    const requestTimer = setTimeout(() => {
+      finish(void 0, new Error(`Timed out waiting ${requestTimeoutMs}ms for upload IPC response.`));
+    }, requestTimeoutMs);
+    socket.setEncoding("utf8");
+    socket.on("connect", () => {
+      connected = true;
+      clearTimeout(connectTimer);
+      const payload = {
+        kind: "upload",
+        requestId,
+        profile,
+        threadId,
+        threadType: threadType === ThreadType.Group ? "group" : "user",
+        attachments
+      };
+      socket.write(`${JSON.stringify(payload)}
+`);
+      requestSent = true;
+    });
+    socket.on("data", (chunk) => {
+      responseBuffer += chunk;
+      const newlineIndex = responseBuffer.indexOf("\n");
+      if (newlineIndex === -1) return;
+      const line = responseBuffer.slice(0, newlineIndex).trim();
+      if (!line) {
+        finish(void 0, new Error("Upload IPC returned empty response."));
+        return;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        finish(void 0, new Error("Upload IPC returned invalid JSON."));
+        return;
+      }
+      if (parsed.kind !== "upload_result" || parsed.requestId !== requestId) {
+        finish(void 0, new Error("Upload IPC returned mismatched response."));
+        return;
+      }
+      if (!parsed.ok) {
+        finish(void 0, new Error(parsed.error || "Upload IPC failed."));
+        return;
+      }
+      finish({
+        handled: true,
+        response: parsed.response
+      });
+    });
+    socket.on("error", (error) => {
+      const code = error.code;
+      if (!connected && !requestSent && (code === "ENOENT" || code === "ECONNREFUSED")) {
+        finish({
+          handled: false,
+          reason: code.toLowerCase()
+        });
+        return;
+      }
+      finish(void 0, error);
+    });
+    socket.on("close", () => {
+      if (settled) return;
+      if (!connected && !requestSent) {
+        finish({
+          handled: false,
+          reason: "socket_closed_before_connect"
+        });
+        return;
+      }
+      finish(void 0, new Error("Upload IPC connection closed before response."));
+    });
+  });
+}
 async function resolveUploadThreadType(api, profile, threadId, groupFlag, command) {
   if (groupFlag) {
     return { type: ThreadType.Group, reason: "explicit_group_flag" };
@@ -2462,6 +2896,43 @@ msg.command("upload <arg1> [arg2]").option("-u, --url <url>", "File URL (repeata
           );
         }
         await assertFilesExist(attachments);
+        const ipcResult = await tryUploadViaListenerIpc(
+          profile,
+          threadId,
+          threadResolution.type,
+          attachments,
+          command
+        );
+        if (ipcResult.handled) {
+          writeDebugLine(
+            "msg.upload.ipc.done",
+            {
+              threadId,
+              threadType: threadResolution.type === ThreadType.Group ? "group" : "user"
+            },
+            command
+          );
+          output(ipcResult.response, false);
+          return;
+        }
+        writeDebugLine(
+          "msg.upload.ipc.fallback",
+          {
+            threadId,
+            threadType: threadResolution.type === ThreadType.Group ? "group" : "user",
+            reason: ipcResult.reason
+          },
+          command
+        );
+        const enforceSingleOwner = parseBooleanFromEnv("OPENZCA_UPLOAD_ENFORCE_SINGLE_OWNER", true);
+        if (enforceSingleOwner) {
+          const owner = await readActiveListenerOwner(profile);
+          if (owner && owner.pid !== process.pid) {
+            throw new Error(
+              `Active listener owner detected for profile "${profile}" (pid ${owner.pid}), but upload IPC is unavailable. Restart \`openzca listen\` with latest version or set OPENZCA_UPLOAD_ENFORCE_SINGLE_OWNER=0 to allow fallback listener startup.`
+            );
+          }
+        }
         const response = await withUploadListener(
           api,
           command,
@@ -3124,6 +3595,14 @@ program.command("listen").description("Listen for real-time incoming messages").
       ) ?? 3e4;
       const lifecycleEventsEnabled = supervised && Boolean(opts.raw);
       const recycleEnabled = !supervised && Boolean(opts.keepAlive) && recycleMs > 0;
+      const keepAliveRestartDelayMs = parsePositiveIntFromEnv(
+        "OPENZCA_LISTEN_KEEPALIVE_RESTART_DELAY_MS",
+        2e3
+      );
+      const keepAliveRestartOnAnyClose = parseBooleanFromEnv(
+        "OPENZCA_LISTEN_KEEPALIVE_RESTART_ON_ANY_CLOSE",
+        false
+      );
       const recycleExitCode = 75;
       const includeReplyContext = parseToggleDefaultTrue(
         process.env.OPENZCA_LISTEN_INCLUDE_QUOTE_CONTEXT
@@ -3145,212 +3624,229 @@ program.command("listen").description("Listen for real-time incoming messages").
           })
         );
       };
-      console.log("Listening... Press Ctrl+C to stop.");
-      if (supervised && opts.keepAlive) {
-        console.error("Warning: --supervised ignores internal --keep-alive reconnect ownership.");
-      }
-      writeDebugLine(
-        "listen.start",
-        {
-          profile,
-          mediaDir: resolveInboundMediaDir(profile),
-          maxMediaBytes: parseMaxInboundMediaBytes(),
-          maxMediaFiles: parseMaxInboundMediaFiles(),
-          includeMediaUrl: process.env.OPENZCA_LISTEN_INCLUDE_MEDIA_URL?.trim() ?? null,
-          keepAlive: Boolean(opts.keepAlive),
-          supervised,
-          lifecycleEventsEnabled,
-          heartbeatMs: lifecycleEventsEnabled ? heartbeatMs : void 0,
-          recycleMs: recycleEnabled ? recycleMs : void 0,
-          includeReplyContext,
-          downloadQuoteMedia,
-          sessionId
-        },
-        command
-      );
-      emitLifecycle("session_id");
-      async function emitWebhook(payload) {
-        if (!opts.webhook) return;
-        try {
-          const response = await fetch(opts.webhook, {
-            method: "POST",
-            headers: {
-              "content-type": "application/json"
+      const enforceSingleOwner = parseBooleanFromEnv("OPENZCA_LISTEN_ENFORCE_SINGLE_OWNER", true);
+      let ownerLock = null;
+      let ipcServer = null;
+      let ipcSocketPath;
+      let resourcesCleaned = false;
+      const cleanupListenResources = async () => {
+        if (resourcesCleaned) return;
+        resourcesCleaned = true;
+        if (ipcServer) {
+          await ipcServer.close();
+          ipcServer = null;
+        }
+        if (ownerLock) {
+          await ownerLock.release();
+          ownerLock = null;
+        }
+      };
+      const unregisterResourceCleanup = registerShutdownCallback(async () => {
+        await cleanupListenResources();
+      });
+      try {
+        if (enforceSingleOwner) {
+          ownerLock = await acquireListenerOwnerLock(profile, sessionId, command);
+          writeDebugLine(
+            "listen.owner.acquired",
+            {
+              profile,
+              lockPath: ownerLock.lockPath,
+              pid: process.pid,
+              sessionId
             },
-            body: JSON.stringify(payload)
-          });
-          if (!response.ok) {
-            console.error(`Webhook response: ${response.status}`);
-          }
-        } catch (error) {
-          console.error(
-            `Webhook failed: ${error instanceof Error ? error.message : String(error)}`
+            command
           );
         }
-      }
-      api.listener.on("connected", () => {
-        console.log("Connected to Zalo websocket.");
-        writeDebugLine(
-          "listen.connected",
-          {
-            profile,
-            sessionId
-          },
-          command
-        );
-        emitLifecycle("connected");
-      });
-      api.listener.on("message", async (message) => {
-        const messageData = message.data;
-        const rawContent = messageData.content;
-        const msgType = getStringCandidate(messageData, ["msgType"]);
-        let quote = normalizeQuoteContext(messageData.quote);
-        const parsedContent = normalizeStructuredContent(rawContent);
-        const hasParsedStructuredContent = parsedContent !== rawContent;
-        const rawText = typeof rawContent === "string" ? rawContent : "";
-        const mediaKind = detectInboundMediaKind(msgType, parsedContent);
-        const maxMediaFiles = parseMaxInboundMediaFiles();
-        const remoteMediaUrls = mediaKind && maxMediaFiles > 0 ? resolvePreferredMediaUrls(mediaKind, parsedContent).slice(0, maxMediaFiles) : [];
-        const quoteRemoteMediaUrls = quote && downloadQuoteMedia && maxMediaFiles > 0 ? (quote.mediaUrls ?? []).slice(0, maxMediaFiles) : [];
+        ipcServer = await startListenerIpcServer(api, profile, sessionId, command);
+        ipcSocketPath = ipcServer?.socketPath;
+        console.log("Listening... Press Ctrl+C to stop.");
+        if (supervised && opts.keepAlive) {
+          console.error("Warning: --supervised ignores internal --keep-alive reconnect ownership.");
+        }
         writeDebugLine(
-          "listen.media.detected",
+          "listen.start",
           {
             profile,
-            threadId: message.threadId,
-            msgType: msgType || void 0,
-            mediaKind,
-            hasParsedStructuredContent,
-            remoteMediaUrls,
-            hasQuote: Boolean(quote),
-            quoteOwnerId: quote?.ownerId,
-            quoteGlobalMsgId: quote?.globalMsgId,
-            quoteCliMsgId: quote?.cliMsgId,
-            quoteRemoteMediaUrls
+            mediaDir: resolveInboundMediaDir(profile),
+            maxMediaBytes: parseMaxInboundMediaBytes(),
+            maxMediaFiles: parseMaxInboundMediaFiles(),
+            includeMediaUrl: process.env.OPENZCA_LISTEN_INCLUDE_MEDIA_URL?.trim() ?? null,
+            keepAlive: Boolean(opts.keepAlive),
+            keepAliveRestartDelayMs: Boolean(opts.keepAlive) ? keepAliveRestartDelayMs : void 0,
+            keepAliveRestartOnAnyClose: Boolean(opts.keepAlive) ? keepAliveRestartOnAnyClose : void 0,
+            supervised,
+            lifecycleEventsEnabled,
+            heartbeatMs: lifecycleEventsEnabled ? heartbeatMs : void 0,
+            recycleMs: recycleEnabled ? recycleMs : void 0,
+            includeReplyContext,
+            downloadQuoteMedia,
+            sessionId,
+            singleOwner: enforceSingleOwner,
+            ipcSocketPath
           },
           command
         );
-        const [mediaEntries, quoteMediaEntries] = await Promise.all([
-          mediaKind ? cacheRemoteMediaEntries({
-            profile,
-            urls: remoteMediaUrls,
-            kind: mediaKind,
-            command,
-            warningLabel: "inbound media",
-            debugErrorEvent: "listen.media.cache_error",
-            debugUrlKey: "mediaUrl"
-          }) : Promise.resolve([]),
-          cacheRemoteMediaEntries({
-            profile,
-            urls: quoteRemoteMediaUrls,
-            kind: "file",
-            command,
-            warningLabel: "quoted media",
-            debugErrorEvent: "listen.quote_media.cache_error",
-            debugUrlKey: "quoteMediaUrl"
-          })
-        ]);
-        const localEntries = mediaEntries.filter((entry) => Boolean(entry.mediaPath));
-        const mediaPaths = localEntries.map((entry) => entry.mediaPath);
-        const mediaUrls = localEntries.length > 0 ? localEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value)) : mediaEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value));
-        const mediaTypes = localEntries.length > 0 ? localEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value)) : mediaEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value));
-        const mediaPath = mediaPaths[0];
-        const mediaUrl = mediaUrls[0];
-        const mediaType = mediaTypes[0];
-        const quoteLocalEntries = quoteMediaEntries.filter((entry) => Boolean(entry.mediaPath));
-        const quoteMediaPaths = quoteLocalEntries.map((entry) => entry.mediaPath);
-        const quoteMediaUrls = quoteLocalEntries.length > 0 ? quoteLocalEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value)) : quoteMediaEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value));
-        const quoteMediaTypes = quoteLocalEntries.length > 0 ? quoteLocalEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value)) : quoteMediaEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value));
-        const quoteMediaPath = quoteMediaPaths[0];
-        const quoteMediaUrl = quoteMediaUrls[0];
-        const quoteMediaType = quoteMediaTypes[0];
-        if (quote) {
-          quote = {
-            ...quote,
-            mediaPath: quoteMediaPath,
-            mediaPaths: quoteMediaPaths.length > 0 ? quoteMediaPaths : void 0,
-            mediaUrl: quoteMediaUrl,
-            mediaUrls: quoteMediaUrls.length > 0 ? quoteMediaUrls : quote.mediaUrls,
-            mediaType: quoteMediaType,
-            mediaTypes: quoteMediaTypes.length > 0 ? quoteMediaTypes : void 0
-          };
-        }
-        const replyContextText = includeReplyContext && quote ? buildReplyContextText(quote) : "";
-        const replyMediaText = includeReplyContext && quoteMediaEntries.length > 0 ? buildReplyMediaAttachedText({ mediaEntries: quoteMediaEntries }) : "";
-        const caption = rawText.trim().length > 0 && !hasParsedStructuredContent ? rawText.trim() : summarizeStructuredContent(msgType, parsedContent);
-        let processedText = mediaEntries.length ? buildMediaAttachedText({
-          mediaEntries,
-          fallbackKind: mediaKind,
-          caption
-        }) : rawText.trim().length > 0 && !hasParsedStructuredContent ? rawText : summarizeStructuredContent(msgType, parsedContent);
-        if (!processedText.trim() && !replyContextText && !replyMediaText) return;
-        if (opts.prefix && processedText.trim().length > 0) {
-          if (!processedText.startsWith(opts.prefix)) return;
-          processedText = processedText.slice(opts.prefix.length).trimStart();
+        emitLifecycle("session_id");
+        let keepAliveRestartTimer = null;
+        async function emitWebhook(payload) {
+          if (!opts.webhook) return;
+          try {
+            const response = await fetch(opts.webhook, {
+              method: "POST",
+              headers: {
+                "content-type": "application/json"
+              },
+              body: JSON.stringify(payload)
+            });
+            if (!response.ok) {
+              console.error(`Webhook response: ${response.status}`);
+            }
+          } catch (error) {
+            console.error(
+              `Webhook failed: ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
         }
-        if (replyMediaText) {
-          processedText = processedText.trim() ? `${processedText}
+        api.listener.on("connected", () => {
+          console.log("Connected to Zalo websocket.");
+          if (keepAliveRestartTimer) {
+            clearTimeout(keepAliveRestartTimer);
+            keepAliveRestartTimer = null;
+          }
+          writeDebugLine(
+            "listen.connected",
+            {
+              profile,
+              sessionId
+            },
+            command
+          );
+          emitLifecycle("connected");
+        });
+        api.listener.on("message", async (message) => {
+          const messageData = message.data;
+          const rawContent = messageData.content;
+          const msgType = getStringCandidate(messageData, ["msgType"]);
+          let quote = normalizeQuoteContext(messageData.quote);
+          const parsedContent = normalizeStructuredContent(rawContent);
+          const hasParsedStructuredContent = parsedContent !== rawContent;
+          const rawText = typeof rawContent === "string" ? rawContent : "";
+          const mediaKind = detectInboundMediaKind(msgType, parsedContent);
+          const maxMediaFiles = parseMaxInboundMediaFiles();
+          const remoteMediaUrls = mediaKind && maxMediaFiles > 0 ? resolvePreferredMediaUrls(mediaKind, parsedContent).slice(0, maxMediaFiles) : [];
+          const quoteRemoteMediaUrls = quote && downloadQuoteMedia && maxMediaFiles > 0 ? (quote.mediaUrls ?? []).slice(0, maxMediaFiles) : [];
+          writeDebugLine(
+            "listen.media.detected",
+            {
+              profile,
+              threadId: message.threadId,
+              msgType: msgType || void 0,
+              mediaKind,
+              hasParsedStructuredContent,
+              remoteMediaUrls,
+              hasQuote: Boolean(quote),
+              quoteOwnerId: quote?.ownerId,
+              quoteGlobalMsgId: quote?.globalMsgId,
+              quoteCliMsgId: quote?.cliMsgId,
+              quoteRemoteMediaUrls
+            },
+            command
+          );
+          const [mediaEntries, quoteMediaEntries] = await Promise.all([
+            mediaKind ? cacheRemoteMediaEntries({
+              profile,
+              urls: remoteMediaUrls,
+              kind: mediaKind,
+              command,
+              warningLabel: "inbound media",
+              debugErrorEvent: "listen.media.cache_error",
+              debugUrlKey: "mediaUrl"
+            }) : Promise.resolve([]),
+            cacheRemoteMediaEntries({
+              profile,
+              urls: quoteRemoteMediaUrls,
+              kind: "file",
+              command,
+              warningLabel: "quoted media",
+              debugErrorEvent: "listen.quote_media.cache_error",
+              debugUrlKey: "quoteMediaUrl"
+            })
+          ]);
+          const localEntries = mediaEntries.filter((entry) => Boolean(entry.mediaPath));
+          const mediaPaths = localEntries.map((entry) => entry.mediaPath);
+          const mediaUrls = localEntries.length > 0 ? localEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value)) : mediaEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value));
+          const mediaTypes = localEntries.length > 0 ? localEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value)) : mediaEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value));
+          const mediaPath = mediaPaths[0];
+          const mediaUrl = mediaUrls[0];
+          const mediaType = mediaTypes[0];
+          const quoteLocalEntries = quoteMediaEntries.filter((entry) => Boolean(entry.mediaPath));
+          const quoteMediaPaths = quoteLocalEntries.map((entry) => entry.mediaPath);
+          const quoteMediaUrls = quoteLocalEntries.length > 0 ? quoteLocalEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value)) : quoteMediaEntries.map((entry) => entry.mediaUrl).filter((value) => Boolean(value));
+          const quoteMediaTypes = quoteLocalEntries.length > 0 ? quoteLocalEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value)) : quoteMediaEntries.map((entry) => entry.mediaType).filter((value) => Boolean(value));
+          const quoteMediaPath = quoteMediaPaths[0];
+          const quoteMediaUrl = quoteMediaUrls[0];
+          const quoteMediaType = quoteMediaTypes[0];
+          if (quote) {
+            quote = {
+              ...quote,
+              mediaPath: quoteMediaPath,
+              mediaPaths: quoteMediaPaths.length > 0 ? quoteMediaPaths : void 0,
+              mediaUrl: quoteMediaUrl,
+              mediaUrls: quoteMediaUrls.length > 0 ? quoteMediaUrls : quote.mediaUrls,
+              mediaType: quoteMediaType,
+              mediaTypes: quoteMediaTypes.length > 0 ? quoteMediaTypes : void 0
+            };
+          }
+          const replyContextText = includeReplyContext && quote ? buildReplyContextText(quote) : "";
+          const replyMediaText = includeReplyContext && quoteMediaEntries.length > 0 ? buildReplyMediaAttachedText({ mediaEntries: quoteMediaEntries }) : "";
+          const caption = rawText.trim().length > 0 && !hasParsedStructuredContent ? rawText.trim() : summarizeStructuredContent(msgType, parsedContent);
+          let processedText = mediaEntries.length ? buildMediaAttachedText({
+            mediaEntries,
+            fallbackKind: mediaKind,
+            caption
+          }) : rawText.trim().length > 0 && !hasParsedStructuredContent ? rawText : summarizeStructuredContent(msgType, parsedContent);
+          if (!processedText.trim() && !replyContextText && !replyMediaText) return;
+          if (opts.prefix && processedText.trim().length > 0) {
+            if (!processedText.startsWith(opts.prefix)) return;
+            processedText = processedText.slice(opts.prefix.length).trimStart();
+          }
+          if (replyMediaText) {
+            processedText = processedText.trim() ? `${processedText}
 ${replyMediaText}` : replyMediaText;
-        }
-        if (replyContextText) {
-          processedText = processedText.trim() ? `${processedText}
+          }
+          if (replyContextText) {
+            processedText = processedText.trim() ? `${processedText}
 ${replyContextText}` : replyContextText;
-        }
-        const chatType = message.type === ThreadType.Group ? "group" : "user";
-        const senderId = getStringCandidate(messageData, ["uidFrom"]) || message.data.uidFrom;
-        const senderDisplayNameRaw = getStringCandidate(messageData, [
-          "dName",
-          "fromD",
-          "senderName",
-          "displayName"
-        ]);
-        const senderDisplayName = senderDisplayNameRaw || void 0;
-        const senderNameForMetadata = message.type === ThreadType.Group ? senderDisplayName : void 0;
-        const toId = getStringCandidate(messageData, ["idTo"]) || void 0;
-        const threadName = typeof messageData.threadName === "string" ? messageData.threadName : typeof messageData.tName === "string" ? messageData.tName : void 0;
-        const mentions = extractInboundMentions({
-          messageData,
-          parsedContent,
-          rawText
-        });
-        const mentionIds = mentions.map((item) => item.uid);
-        const timestamp = toEpochSeconds(message.data.ts);
-        const payload = {
-          threadId: message.threadId,
-          targetId: message.threadId,
-          conversationId: message.threadId,
-          msgId: message.data.msgId,
-          cliMsgId: message.data.cliMsgId,
-          content: processedText,
-          type: message.type,
-          timestamp,
-          msgType: msgType || void 0,
-          quote: quote ?? void 0,
-          quoteMediaPath,
-          quoteMediaPaths: quoteMediaPaths.length > 0 ? quoteMediaPaths : void 0,
-          quoteMediaUrl,
-          quoteMediaUrls: quoteMediaUrls.length > 0 ? quoteMediaUrls : void 0,
-          quoteMediaType,
-          quoteMediaTypes: quoteMediaTypes.length > 0 ? quoteMediaTypes : void 0,
-          mediaPath,
-          mediaPaths: mediaPaths.length > 0 ? mediaPaths : void 0,
-          mediaUrl,
-          mediaUrls: mediaUrls.length > 0 ? mediaUrls : void 0,
-          mediaType,
-          mediaTypes: mediaTypes.length > 0 ? mediaTypes : void 0,
-          mediaKind: mediaKind ?? void 0,
-          mentions: mentions.length > 0 ? mentions : void 0,
-          mentionIds: mentionIds.length > 0 ? mentionIds : void 0,
-          metadata: {
-            isGroup: message.type === ThreadType.Group,
-            chatType,
+          }
+          const chatType = message.type === ThreadType.Group ? "group" : "user";
+          const senderId = getStringCandidate(messageData, ["uidFrom"]) || message.data.uidFrom;
+          const senderDisplayNameRaw = getStringCandidate(messageData, [
+            "dName",
+            "fromD",
+            "senderName",
+            "displayName"
+          ]);
+          const senderDisplayName = senderDisplayNameRaw || void 0;
+          const senderNameForMetadata = message.type === ThreadType.Group ? senderDisplayName : void 0;
+          const toId = getStringCandidate(messageData, ["idTo"]) || void 0;
+          const threadName = typeof messageData.threadName === "string" ? messageData.threadName : typeof messageData.tName === "string" ? messageData.tName : void 0;
+          const mentions = extractInboundMentions({
+            messageData,
+            parsedContent,
+            rawText
+          });
+          const mentionIds = mentions.map((item) => item.uid);
+          const timestamp = toEpochSeconds(message.data.ts);
+          const payload = {
             threadId: message.threadId,
             targetId: message.threadId,
-            threadName,
-            senderName: senderNameForMetadata,
-            senderDisplayName,
-            senderId,
-            fromId: senderId,
-            toId,
+            conversationId: message.threadId,
+            msgId: message.data.msgId,
+            cliMsgId: message.data.cliMsgId,
+            content: processedText,
+            type: message.type,
+            timestamp,
             msgType: msgType || void 0,
             quote: quote ?? void 0,
             quoteMediaPath,
@@ -3359,7 +3855,6 @@ ${replyContextText}` : replyContextText;
             quoteMediaUrls: quoteMediaUrls.length > 0 ? quoteMediaUrls : void 0,
             quoteMediaType,
             quoteMediaTypes: quoteMediaTypes.length > 0 ? quoteMediaTypes : void 0,
-            timestamp,
             mediaPath,
             mediaPaths: mediaPaths.length > 0 ? mediaPaths : void 0,
             mediaUrl,
@@ -3369,147 +3864,222 @@ ${replyContextText}` : replyContextText;
             mediaKind: mediaKind ?? void 0,
             mentions: mentions.length > 0 ? mentions : void 0,
             mentionIds: mentionIds.length > 0 ? mentionIds : void 0,
-            mentionCount: mentions.length > 0 ? mentions.length : void 0
-          },
-          // Backward-compatible convenience fields.
-          chatType,
-          senderId,
-          senderName: senderDisplayName,
-          senderDisplayName,
-          toId,
-          ts: message.data.ts
-        };
-        if (opts.raw) {
-          console.log(JSON.stringify(payload));
-        } else {
-          console.log(
-            `[${chatType}] ${payload.senderName || payload.senderId} -> ${payload.threadId}: ${payload.content}`
-          );
-        }
-        await emitWebhook(payload);
-        if (opts.echo && rawText.trim().length > 0) {
-          try {
-            await api.sendMessage(
-              { msg: processedText },
-              message.threadId,
-              message.type
-            );
-          } catch (error) {
-            console.error(
-              `Echo failed: ${error instanceof Error ? error.message : String(error)}`
+            metadata: {
+              isGroup: message.type === ThreadType.Group,
+              chatType,
+              threadId: message.threadId,
+              targetId: message.threadId,
+              threadName,
+              senderName: senderNameForMetadata,
+              senderDisplayName,
+              senderId,
+              fromId: senderId,
+              toId,
+              msgType: msgType || void 0,
+              quote: quote ?? void 0,
+              quoteMediaPath,
+              quoteMediaPaths: quoteMediaPaths.length > 0 ? quoteMediaPaths : void 0,
+              quoteMediaUrl,
+              quoteMediaUrls: quoteMediaUrls.length > 0 ? quoteMediaUrls : void 0,
+              quoteMediaType,
+              quoteMediaTypes: quoteMediaTypes.length > 0 ? quoteMediaTypes : void 0,
+              timestamp,
+              mediaPath,
+              mediaPaths: mediaPaths.length > 0 ? mediaPaths : void 0,
+              mediaUrl,
+              mediaUrls: mediaUrls.length > 0 ? mediaUrls : void 0,
+              mediaType,
+              mediaTypes: mediaTypes.length > 0 ? mediaTypes : void 0,
+              mediaKind: mediaKind ?? void 0,
+              mentions: mentions.length > 0 ? mentions : void 0,
+              mentionIds: mentionIds.length > 0 ? mentionIds : void 0,
+              mentionCount: mentions.length > 0 ? mentions.length : void 0
+            },
+            // Backward-compatible convenience fields.
+            chatType,
+            senderId,
+            senderName: senderDisplayName,
+            senderDisplayName,
+            toId,
+            ts: message.data.ts
+          };
+          if (opts.raw) {
+            console.log(JSON.stringify(payload));
+          } else {
+            console.log(
+              `[${chatType}] ${payload.senderName || payload.senderId} -> ${payload.threadId}: ${payload.content}`
             );
           }
-        }
-      });
-      api.listener.on("error", (error) => {
-        writeDebugLine(
-          "listen.error",
-          {
-            profile,
-            message: error instanceof Error ? error.message : String(error),
-            sessionId
-          },
-          command
-        );
-        emitLifecycle("error", {
-          message: error instanceof Error ? error.message : String(error)
-        });
-        console.error(
-          `Listener error: ${error instanceof Error ? error.message : String(error)}`
-        );
-      });
-      await new Promise((resolve) => {
-        let settled = false;
-        let recycleTimer = null;
-        let recycleForceExitTimer = null;
-        let heartbeatTimer = null;
-        let recyclePendingExit = false;
-        let unregisterShutdown = () => {
-        };
-        const finish = () => {
-          if (settled) return;
-          settled = true;
-          if (recycleTimer) {
-            clearTimeout(recycleTimer);
-            recycleTimer = null;
-          }
-          if (recycleForceExitTimer && !recyclePendingExit) {
-            clearTimeout(recycleForceExitTimer);
-            recycleForceExitTimer = null;
-          }
-          if (heartbeatTimer) {
-            clearInterval(heartbeatTimer);
-            heartbeatTimer = null;
+          await emitWebhook(payload);
+          if (opts.echo && rawText.trim().length > 0) {
+            try {
+              await api.sendMessage(
+                { msg: processedText },
+                message.threadId,
+                message.type
+              );
+            } catch (error) {
+              console.error(
+                `Echo failed: ${error instanceof Error ? error.message : String(error)}`
+              );
+            }
           }
-          unregisterShutdown();
-          unregisterShutdown = () => {
-          };
-          resolve();
-        };
-        api.listener.on("closed", (code, reason) => {
-          console.log(`Listener closed (${code}) ${reason || ""}`);
+        });
+        api.listener.on("error", (error) => {
           writeDebugLine(
-            "listen.closed",
+            "listen.error",
             {
               profile,
-              code,
-              reason: reason || void 0,
+              message: error instanceof Error ? error.message : String(error),
               sessionId
             },
             command
           );
-          emitLifecycle("closed", {
-            code,
-            reason: reason || void 0
+          emitLifecycle("error", {
+            message: error instanceof Error ? error.message : String(error)
           });
-          if (!opts.keepAlive || supervised) {
-            finish();
-          }
+          console.error(
+            `Listener error: ${error instanceof Error ? error.message : String(error)}`
+          );
         });
-        const onSignal = () => {
-          try {
-            api.listener.stop();
-          } catch {
-          }
-          finish();
-        };
-        unregisterShutdown = registerShutdownCallback(onSignal);
-        if (lifecycleEventsEnabled && heartbeatMs > 0) {
-          heartbeatTimer = setInterval(() => {
-            emitLifecycle("heartbeat");
-          }, heartbeatMs);
-        }
-        if (recycleEnabled) {
-          recycleTimer = setTimeout(() => {
-            console.error(
-              `Listener recycle triggered after ${recycleMs}ms to prevent stale session.`
-            );
+        await new Promise((resolve) => {
+          let settled = false;
+          let recycleTimer = null;
+          let recycleForceExitTimer = null;
+          let heartbeatTimer = null;
+          let recyclePendingExit = false;
+          let unregisterShutdown = () => {
+          };
+          const finish = () => {
+            if (settled) return;
+            settled = true;
+            if (recycleTimer) {
+              clearTimeout(recycleTimer);
+              recycleTimer = null;
+            }
+            if (recycleForceExitTimer && !recyclePendingExit) {
+              clearTimeout(recycleForceExitTimer);
+              recycleForceExitTimer = null;
+            }
+            if (heartbeatTimer) {
+              clearInterval(heartbeatTimer);
+              heartbeatTimer = null;
+            }
+            if (keepAliveRestartTimer) {
+              clearTimeout(keepAliveRestartTimer);
+              keepAliveRestartTimer = null;
+            }
+            unregisterShutdown();
+            unregisterShutdown = () => {
+            };
+            resolve();
+          };
+          api.listener.on("closed", (code, reason) => {
+            console.log(`Listener closed (${code}) ${reason || ""}`);
             writeDebugLine(
-              "listen.recycle",
+              "listen.closed",
               {
                 profile,
-                recycleMs,
-                exitCode: recycleExitCode,
+                code,
+                reason: reason || void 0,
                 sessionId
               },
               command
             );
-            process.exitCode = recycleExitCode;
-            recyclePendingExit = true;
-            recycleForceExitTimer = setTimeout(() => {
-              recycleForceExitTimer = null;
-              process.exit(recycleExitCode);
-            }, 3e3);
-            recycleForceExitTimer.unref();
+            emitLifecycle("closed", {
+              code,
+              reason: reason || void 0
+            });
+            if (!opts.keepAlive || supervised) {
+              finish();
+              return;
+            }
+            const shouldRestart = keepAliveRestartOnAnyClose || code === 1e3 || code === 3e3;
+            if (!shouldRestart) return;
+            if (keepAliveRestartTimer) {
+              clearTimeout(keepAliveRestartTimer);
+            }
+            keepAliveRestartTimer = setTimeout(() => {
+              keepAliveRestartTimer = null;
+              writeDebugLine(
+                "listen.keepalive.restart",
+                {
+                  profile,
+                  code,
+                  reason: reason || void 0,
+                  delayMs: keepAliveRestartDelayMs,
+                  sessionId
+                },
+                command
+              );
+              try {
+                api.listener.start({ retryOnClose: true });
+              } catch (error) {
+                if (!isListenerAlreadyStarted(error)) {
+                  writeDebugLine(
+                    "listen.keepalive.restart_error",
+                    {
+                      profile,
+                      code,
+                      reason: reason || void 0,
+                      delayMs: keepAliveRestartDelayMs,
+                      message: toErrorText(error),
+                      sessionId
+                    },
+                    command
+                  );
+                }
+              }
+            }, keepAliveRestartDelayMs);
+          });
+          const onSignal = () => {
             try {
               api.listener.stop();
             } catch {
             }
             finish();
-          }, recycleMs);
-        }
-        api.listener.start({ retryOnClose: supervised ? false : Boolean(opts.keepAlive) });
-      });
+          };
+          unregisterShutdown = registerShutdownCallback(onSignal);
+          if (lifecycleEventsEnabled && heartbeatMs > 0) {
+            heartbeatTimer = setInterval(() => {
+              emitLifecycle("heartbeat");
+            }, heartbeatMs);
+          }
+          if (recycleEnabled) {
+            recycleTimer = setTimeout(() => {
+              console.error(
+                `Listener recycle triggered after ${recycleMs}ms to prevent stale session.`
+              );
+              writeDebugLine(
+                "listen.recycle",
+                {
+                  profile,
+                  recycleMs,
+                  exitCode: recycleExitCode,
+                  sessionId
+                },
+                command
+              );
+              process.exitCode = recycleExitCode;
+              recyclePendingExit = true;
+              recycleForceExitTimer = setTimeout(() => {
+                recycleForceExitTimer = null;
+                process.exit(recycleExitCode);
+              }, 3e3);
+              recycleForceExitTimer.unref();
+              try {
+                api.listener.stop();
+              } catch {
+              }
+              finish();
+            }, recycleMs);
+          }
+          api.listener.start({ retryOnClose: supervised ? false : Boolean(opts.keepAlive) });
+        });
+      } finally {
+        unregisterResourceCleanup();
+        await cleanupListenResources();
+      }
     }
   )
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openzca",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Open-source zca-compatible CLI to integrate Zalo with OpenClaw",
   "type": "module",
   "bin": {