openzca 0.1.12 → 0.1.14

package/README.md

@@ -192,6 +192,8 @@ For media debugging, grep these events in the debug log:
 | `openzca listen --webhook <url>` | POST message payload to a webhook URL |
 | `openzca listen --raw` | Output raw JSON per line |
 | `openzca listen --keep-alive` | Auto-reconnect on disconnect |
+| `openzca listen --supervised --raw` | Supervisor mode with lifecycle JSON events (`session_id`, `connected`, `heartbeat`, `error`, `closed`) |
+| `openzca listen --keep-alive --recycle-ms <ms>` | Periodically recycle listener process to avoid stale sessions |
 
 `listen --raw` includes inbound media metadata when available:
 
@@ -205,9 +207,21 @@ It also includes stable routing fields for downstream tools:
 - `threadId`, `targetId`, `conversationId`
 - `senderId`, `toId`, `chatType`, `msgType`, `timestamp`
 - `metadata.threadId`, `metadata.targetId`, `metadata.senderId`, `metadata.toId`
+- `quote` and `metadata.quote` when the inbound message is a reply to a previous message
+  - Includes parsed `quote.attach` and extracted `quote.mediaUrls` when attachment URLs are present.
+- `quoteMediaPath`, `quoteMediaPaths`, `quoteMediaUrl`, `quoteMediaUrls`, `quoteMediaType`, `quoteMediaTypes`
+  - Present when quoted attachment URLs can be resolved/downloaded.
 
 For direct messages, `metadata.senderName` is intentionally omitted so consumers can prefer numeric IDs for routing instead of display-name targets.
 
+When a reply/quoted message is detected, `content` also appends a compact line:
+
+```text
+[reply context: <sender-or-owner-id>: <quoted summary>]
+```
+
+This helps downstream consumers that only read `content` (without parsing `quote`) still see reply context.
+
 `listen` also normalizes JSON-string message payloads (common for `chat.voice` and `share.file`) so media URLs are extracted/cached instead of being forwarded as raw JSON text.
 
 For non-text inbound messages (image/video/audio/file), `content` is emitted as a media note:
@@ -241,8 +255,31 @@ Optional overrides:
 - `OPENZCA_LISTEN_MEDIA_DIR`: explicit inbound media cache directory
 - `OPENZCA_LISTEN_MEDIA_MAX_BYTES`: max bytes per inbound media file (default `20971520`, 20MB)
 - `OPENZCA_LISTEN_MEDIA_MAX_FILES`: max inbound media files extracted per message (default `4`, max `16`)
+- `OPENZCA_LISTEN_MEDIA_FETCH_TIMEOUT_MS`: max download time per inbound media URL (default `10000`)
+  - Set to `0` to disable timeout.
 - `OPENZCA_LISTEN_MEDIA_LEGACY_DIR=1`: use legacy storage at `~/.openzca/profiles/<profile>/inbound-media`
 
+Listener resilience override:
+
+- `OPENZCA_LISTEN_RECYCLE_MS`: when `listen --keep-alive` is used, force listener recycle after N milliseconds.
+  - Default: `1800000` (30 minutes) if not set.
+  - Set to `0` to disable auto recycle.
+  - On recycle, `openzca` exits with code `75` so external supervisors (like OpenClaw Gateway) can auto-restart it.
+- `OPENZCA_LISTEN_HEARTBEAT_MS`: heartbeat interval for `listen --supervised --raw` lifecycle events.
+  - Default: `30000` (30 seconds).
+  - Set to `0` to disable heartbeat events.
+- `OPENZCA_LISTEN_INCLUDE_QUOTE_CONTEXT`: include reply context/quoted-media helper lines in `content`.
+  - Default: enabled.
+  - Set to `0` to disable.
+- `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.
+
+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`).
+
 ### account — Multi-account profiles
 
 | Command | Description |

package/dist/cli.js

@@ -1207,6 +1207,13 @@ function parseMaxInboundMediaFiles() {
   if (!Number.isFinite(parsed) || parsed <= 0) return 4;
   return Math.min(Math.max(Math.trunc(parsed), 1), 16);
 }
+function parseInboundMediaFetchTimeoutMs() {
+  const raw = process.env.OPENZCA_LISTEN_MEDIA_FETCH_TIMEOUT_MS?.trim();
+  if (!raw) return 1e4;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) return 1e4;
+  return Math.trunc(parsed);
+}
 function resolveOpenClawMediaDir() {
   const stateDir = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim() || path4.join(os3.homedir(), ".openclaw");
   return path4.join(stateDir, "media");
@@ -1225,7 +1232,22 @@ function resolveInboundMediaDir(profile) {
 }
 async function cacheInboundMediaToProfile(profile, mediaUrl, kind) {
   const maxBytes = parseMaxInboundMediaBytes();
-  const response = await fetch(mediaUrl);
+  const timeoutMs = parseInboundMediaFetchTimeoutMs();
+  const controller = timeoutMs > 0 ? new AbortController() : void 0;
+  const timeoutId = controller && timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : null;
+  let response;
+  try {
+    response = await fetch(mediaUrl, controller ? { signal: controller.signal } : void 0);
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error(`Timed out downloading inbound media: ${mediaUrl} (${timeoutMs}ms)`);
+    }
+    throw error;
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+  }
   if (!response.ok) {
     throw new Error(`Failed to download inbound media: ${mediaUrl} (${response.status})`);
   }
@@ -1247,6 +1269,40 @@ async function cacheInboundMediaToProfile(profile, mediaUrl, kind) {
   await fs4.writeFile(mediaPath, data);
   return { mediaPath, mediaType };
 }
+async function cacheRemoteMediaEntries(params) {
+  if (params.urls.length === 0) return [];
+  return Promise.all(
+    params.urls.map(async (mediaUrl) => {
+      let mediaPath;
+      let mediaType = null;
+      try {
+        const cached = await cacheInboundMediaToProfile(params.profile, mediaUrl, params.kind);
+        if (cached) {
+          mediaPath = cached.mediaPath;
+          mediaType = cached.mediaType;
+        }
+      } catch (error) {
+        console.error(
+          `Warning: failed to cache ${params.warningLabel} (${error instanceof Error ? error.message : String(error)})`
+        );
+        writeDebugLine(
+          params.debugErrorEvent,
+          {
+            profile: params.profile,
+            [params.debugUrlKey]: mediaUrl,
+            message: error instanceof Error ? error.message : String(error)
+          },
+          params.command
+        );
+      }
+      return {
+        mediaPath,
+        mediaUrl,
+        mediaType: mediaType ?? void 0
+      };
+    })
+  );
+}
 function summarizeStructuredContent(msgType, content) {
   const normalizedType = normalizeMessageType(msgType);
   const record = asObject(content);
@@ -1303,6 +1359,106 @@ ${params.caption.trim()}`;
   }
   return mediaNote;
 }
+function parseToggleDefaultTrue(value) {
+  if (value === void 0) return true;
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  return true;
+}
+function truncatePreview(value, maxLength = 220) {
+  const normalized = value.trim();
+  if (normalized.length <= maxLength) return normalized;
+  return `${normalized.slice(0, Math.max(maxLength - 3, 1))}...`;
+}
+function normalizeQuoteContext(value) {
+  const normalized = normalizeStructuredContent(value);
+  const record = asObject(normalized);
+  if (!record) return null;
+  const ownerId = getStringCandidate(record, [
+    "ownerId",
+    "uidFrom",
+    "fromId",
+    "senderId",
+    "uid"
+  ]);
+  const senderName = getStringCandidate(record, [
+    "fromD",
+    "senderName",
+    "dName",
+    "displayName",
+    "name"
+  ]);
+  const msg2 = getStringCandidate(record, [
+    "msg",
+    "message",
+    "text",
+    "content",
+    "title",
+    "description"
+  ]);
+  const cliMsgId = getStringCandidate(record, ["cliMsgId"]);
+  const globalMsgId = getStringCandidate(record, ["globalMsgId", "msgId", "realMsgId"]);
+  const cliMsgType = typeof record.cliMsgType === "number" && Number.isFinite(record.cliMsgType) ? Math.trunc(record.cliMsgType) : void 0;
+  const attach = record.attach === void 0 ? void 0 : normalizeStructuredContent(record.attach);
+  const mediaUrlSet = /* @__PURE__ */ new Set();
+  if (attach !== void 0) {
+    collectHttpUrls(attach, mediaUrlSet);
+  }
+  const tsRaw = record.ts;
+  const tsNumeric = typeof tsRaw === "number" ? tsRaw : typeof tsRaw === "string" ? Number(tsRaw) : Number.NaN;
+  const ts = Number.isFinite(tsNumeric) ? Math.trunc(tsNumeric) : void 0;
+  if (!ownerId && !senderName && !msg2 && !cliMsgId && !globalMsgId && attach === void 0) {
+    return null;
+  }
+  return {
+    ownerId: ownerId || void 0,
+    senderName: senderName || void 0,
+    msg: msg2 || void 0,
+    attach,
+    mediaUrls: mediaUrlSet.size > 0 ? [...mediaUrlSet] : void 0,
+    ts,
+    cliMsgId: cliMsgId || void 0,
+    globalMsgId: globalMsgId || void 0,
+    cliMsgType
+  };
+}
+function buildReplyContextText(quote) {
+  const from = quote.senderName || quote.ownerId || "unknown";
+  const messageText = quote.msg?.trim() || "";
+  const attachText = quote.attach !== void 0 ? summarizeStructuredContent("quote", quote.attach) : "";
+  let summary = messageText || attachText;
+  if (!summary || summary === "<non-text:quote>" || summary === "<non-text-message>") {
+    if (quote.mediaUrls && quote.mediaUrls.length > 0) {
+      summary = quote.mediaUrls.length > 1 ? `${quote.mediaUrls[0]} (+${quote.mediaUrls.length - 1} more)` : quote.mediaUrls[0];
+    } else {
+      summary = "<quoted-message>";
+    }
+  }
+  return `[reply context: ${from}: ${truncatePreview(summary.replace(/\s+/g, " "))}]`;
+}
+function buildReplyMediaAttachedText(params) {
+  const entries = params.mediaEntries.map((entry) => ({
+    pathOrUrl: entry.mediaPath ?? entry.mediaUrl,
+    mediaPath: entry.mediaPath,
+    mediaUrl: entry.mediaUrl,
+    mediaType: entry.mediaType
+  })).filter((entry) => Boolean(entry.pathOrUrl));
+  if (entries.length === 0) return "";
+  const multiple = entries.length > 1;
+  const lines = [];
+  if (multiple) {
+    lines.push(`[reply media attached: ${entries.length} files]`);
+  }
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index];
+    const typePart = entry.mediaType?.trim() ? ` (${entry.mediaType.trim()})` : "";
+    const urlPart = entry.mediaPath && entry.mediaUrl ? ` | ${entry.mediaUrl}` : "";
+    const prefix = multiple ? `[reply media attached ${index + 1}/${entries.length}: ` : "[reply media attached: ";
+    lines.push(`${prefix}${entry.pathOrUrl}${typePart}${urlPart}]`);
+  }
+  return lines.join("\n");
+}
 function normalizeFriendLookupRows(value) {
   const queue = [value];
   const rows = [];
@@ -1384,6 +1540,14 @@ function toEpochSeconds(input) {
   }
   return Math.floor(numeric);
 }
+function parseNonNegativeIntOption(label, value) {
+  if (!value || !value.trim()) return void 0;
+  const parsed = Number(value.trim());
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`${label} must be a non-negative number.`);
+  }
+  return Math.trunc(parsed);
+}
 program.name("openzca").description("Open-source zca-cli compatible wrapper powered by zca-js").version(PKG_VERSION).option("-p, --profile <name>", "Profile name").option("--debug", "Enable debug logging").option("--debug-file <path>", "Debug log file path").showHelpAfterError();
 program.hook("preAction", (_parent, actionCommand) => {
   if (!resolveDebugEnabled(actionCommand)) {
@@ -2419,11 +2583,56 @@ me.command("last-online <userId>").description("Get last online of a user").acti
     output(await api.lastOnline(userId), false);
   })
 );
-program.command("listen").description("Listen for real-time incoming messages").option("-e, --echo", "Echo incoming text message").option("-p, --prefix <prefix>", "Only process text starting with prefix").option("-w, --webhook <url>", "POST message payload to webhook").option("-r, --raw", "Output JSON line payload").option("-k, --keep-alive", "Auto restart listener on disconnect").action(
+program.command("listen").description("Listen for real-time incoming messages").option("-e, --echo", "Echo incoming text message").option("-p, --prefix <prefix>", "Only process text starting with prefix").option("-w, --webhook <url>", "POST message payload to webhook").option("-r, --raw", "Output JSON line payload").option("-k, --keep-alive", "Auto restart listener on disconnect").option(
+  "--supervised",
+  "Supervisor mode (disable internal retry ownership; emit lifecycle events in --raw)"
+).option(
+  "--heartbeat-ms <ms>",
+  "Lifecycle heartbeat interval in --supervised mode (default: 30000, 0 disables)"
+).option(
+  "--recycle-ms <ms>",
+  "Force recycle listener after N ms (or use OPENZCA_LISTEN_RECYCLE_MS)"
+).action(
   wrapAction(
     async (opts, command) => {
       const { profile, api } = await requireApi(command);
+      const supervised = Boolean(opts.supervised);
+      const defaultRecycleMs = 30 * 60 * 1e3;
+      const recycleMs = parseNonNegativeIntOption("--recycle-ms", opts.recycleMs) ?? parseNonNegativeIntOption(
+        "OPENZCA_LISTEN_RECYCLE_MS",
+        process.env.OPENZCA_LISTEN_RECYCLE_MS
+      ) ?? defaultRecycleMs;
+      const heartbeatMs = parseNonNegativeIntOption("--heartbeat-ms", opts.heartbeatMs) ?? parseNonNegativeIntOption(
+        "OPENZCA_LISTEN_HEARTBEAT_MS",
+        process.env.OPENZCA_LISTEN_HEARTBEAT_MS
+      ) ?? 3e4;
+      const lifecycleEventsEnabled = supervised && Boolean(opts.raw);
+      const recycleEnabled = !supervised && Boolean(opts.keepAlive) && recycleMs > 0;
+      const recycleExitCode = 75;
+      const includeReplyContext = parseToggleDefaultTrue(
+        process.env.OPENZCA_LISTEN_INCLUDE_QUOTE_CONTEXT
+      );
+      const downloadQuoteMedia = parseToggleDefaultTrue(
+        process.env.OPENZCA_LISTEN_DOWNLOAD_QUOTE_MEDIA
+      );
+      const sessionId = `${Date.now().toString(36)}-${Math.random().toString(16).slice(2, 10)}`;
+      const emitLifecycle = (event, fields) => {
+        if (!lifecycleEventsEnabled) return;
+        console.log(
+          JSON.stringify({
+            kind: "lifecycle",
+            event,
+            session_id: sessionId,
+            profile,
+            timestamp: Math.floor(Date.now() / 1e3),
+            ...fields
+          })
+        );
+      };
       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",
         {
@@ -2431,10 +2640,19 @@ program.command("listen").description("Listen for real-time incoming messages").
           mediaDir: resolveInboundMediaDir(profile),
           maxMediaBytes: parseMaxInboundMediaBytes(),
           maxMediaFiles: parseMaxInboundMediaFiles(),
-          includeMediaUrl: process.env.OPENZCA_LISTEN_INCLUDE_MEDIA_URL?.trim() ?? null
+          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 {
@@ -2456,17 +2674,28 @@ program.command("listen").description("Listen for real-time incoming messages").
       }
       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) : [];
         writeDebugLine(
           "listen.media.detected",
           {
@@ -2475,42 +2704,35 @@ program.command("listen").description("Listen for real-time incoming messages").
             msgType: msgType || void 0,
             mediaKind,
             hasParsedStructuredContent,
-            remoteMediaUrls
+            remoteMediaUrls,
+            hasQuote: Boolean(quote),
+            quoteOwnerId: quote?.ownerId,
+            quoteGlobalMsgId: quote?.globalMsgId,
+            quoteCliMsgId: quote?.cliMsgId,
+            quoteRemoteMediaUrls
           },
           command
         );
-        const mediaEntries = [];
-        for (const mediaUrl2 of remoteMediaUrls) {
-          let mediaPath2;
-          let mediaType2 = null;
-          try {
-            if (mediaKind) {
-              const cached = await cacheInboundMediaToProfile(profile, mediaUrl2, mediaKind);
-              if (cached) {
-                mediaPath2 = cached.mediaPath;
-                mediaType2 = cached.mediaType;
-              }
-            }
-          } catch (error) {
-            console.error(
-              `Warning: failed to cache inbound media (${error instanceof Error ? error.message : String(error)})`
-            );
-            writeDebugLine(
-              "listen.media.cache_error",
-              {
-                profile,
-                mediaUrl: mediaUrl2,
-                message: error instanceof Error ? error.message : String(error)
-              },
-              command
-            );
-          }
-          mediaEntries.push({
-            mediaPath: mediaPath2,
-            mediaUrl: mediaUrl2,
-            mediaType: mediaType2 ?? void 0
-          });
-        }
+        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));
@@ -2518,17 +2740,45 @@ program.command("listen").description("Listen for real-time incoming messages").
         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()) return;
-        if (opts.prefix) {
+        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}
+${replyContextText}` : replyContextText;
+        }
         const chatType = message.type === ThreadType.Group ? "group" : "user";
         const senderId = getStringCandidate(messageData, ["uidFrom"]) || message.data.uidFrom;
         const senderDisplayNameRaw = getStringCandidate(messageData, ["dName"]);
@@ -2547,6 +2797,13 @@ program.command("listen").description("Listen for real-time incoming messages").
           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,
@@ -2566,6 +2823,13 @@ program.command("listen").description("Listen for real-time incoming messages").
             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,
@@ -2606,20 +2870,62 @@ program.command("listen").description("Listen for real-time incoming messages").
         }
       });
       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;
         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;
+          }
           resolve();
         };
         api.listener.on("closed", (code, reason) => {
           console.log(`Listener closed (${code}) ${reason || ""}`);
-          if (!opts.keepAlive) {
+          writeDebugLine(
+            "listen.closed",
+            {
+              profile,
+              code,
+              reason: reason || void 0,
+              sessionId
+            },
+            command
+          );
+          emitLifecycle("closed", {
+            code,
+            reason: reason || void 0
+          });
+          if (!opts.keepAlive || supervised) {
             finish();
           }
         });
@@ -2630,8 +2936,42 @@ program.command("listen").description("Listen for real-time incoming messages").
           }
           finish();
         };
+        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);
+        }
         process.once("SIGINT", onSigint);
-        api.listener.start({ retryOnClose: Boolean(opts.keepAlive) });
+        api.listener.start({ retryOnClose: supervised ? false : Boolean(opts.keepAlive) });
       });
     }
   )

package/package.json

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