openzca 0.1.9 → 0.1.11

package/README.md

@@ -71,7 +71,7 @@ You can also open the saved file manually (for example: `open qr.png` on macOS).
 | `openzca msg send <threadId> <message>` | Send text message |
 | `openzca msg image <threadId> [file]` | Send image(s) from file or URL |
 | `openzca msg video <threadId> [file]` | Send video(s) from file or URL |
-| `openzca msg voice <threadId> [file]` | Send voice message from local file or URL |
+| `openzca msg voice <threadId> [file]` | Send voice message from local file or URL (`.aac`, `.mp3`, `.m4a`, `.wav`, `.ogg`) |
 | `openzca msg sticker <threadId> <stickerId>` | Send a sticker |
 | `openzca msg link <threadId> <url>` | Send a link |
 | `openzca msg card <threadId> <contactId>` | Send a contact card |
@@ -84,6 +84,39 @@ You can also open the saved file manually (for example: `open qr.png` on macOS).
 | `openzca msg recent <threadId>` | List recent messages (`-n`, `--json`) |
 
 Media commands accept local files, `file://` paths, and repeatable `--url` options. Add `--group` for group threads.
+Local paths using `~` are expanded automatically (for positional file args, `--url`, and `OPENZCA_LISTEN_MEDIA_DIR`).
+
+### Debug Logging
+
+Use debug mode to write copyable logs for support/debugging:
+
+```bash
+# One-off debug run
+openzca --debug msg image <threadId> ~/Desktop/screenshot.png
+
+# Custom debug log path
+openzca --debug --debug-file ~/Desktop/openzca-debug.log msg image <threadId> ~/Desktop/screenshot.png
+
+# Or enable by environment
+OPENZCA_DEBUG=1 openzca listen --raw
+```
+
+Default debug log file:
+
+```text
+~/.openzca/logs/openzca-debug.log
+```
+
+Useful command to copy recent debug logs:
+
+```bash
+tail -n 200 ~/.openzca/logs/openzca-debug.log
+```
+
+For media debugging, grep these events in the debug log:
+
+- `listen.media.detected`
+- `listen.media.cache_error`
 
 ### group — Group management
 
@@ -160,13 +193,15 @@ Media commands accept local files, `file://` paths, and repeatable `--url` optio
 | `openzca listen --raw` | Output raw JSON per line |
 | `openzca listen --keep-alive` | Auto-reconnect on disconnect |
 
-`listen --raw` now includes inbound media metadata when available:
+`listen --raw` includes inbound media metadata when available:
 
 - `mediaPath`, `mediaPaths`
 - `mediaUrl`, `mediaUrls`
 - `mediaType`, `mediaTypes`
 - `mediaKind`
 
+`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:
 
 ```text

package/dist/cli.js

@@ -3,6 +3,7 @@
 // src/cli.ts
 import { createRequire } from "module";
 import { spawn as spawn2 } from "child_process";
+import fsSync from "fs";
 import fs4 from "fs/promises";
 import os3 from "os";
 import path4 from "path";
@@ -456,31 +457,65 @@ import path3 from "path";
 import { fileURLToPath } from "url";
 var CONTENT_TYPE_EXT = {
   "image/jpeg": ".jpg",
+  "image/jpg": ".jpg",
   "image/png": ".png",
   "image/webp": ".webp",
   "image/gif": ".gif",
+  "image/heic": ".heic",
+  "image/heif": ".heif",
   "video/mp4": ".mp4",
+  "video/quicktime": ".mov",
+  "video/webm": ".webm",
   "audio/mpeg": ".mp3",
   "audio/mp3": ".mp3",
+  "audio/aac": ".aac",
+  "audio/x-aac": ".aac",
   "audio/mp4": ".m4a",
   "audio/x-m4a": ".m4a",
-  "audio/wav": ".wav"
+  "audio/wav": ".wav",
+  "audio/ogg": ".ogg",
+  "audio/webm": ".webm",
+  "application/pdf": ".pdf",
+  "application/msword": ".doc",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+  "application/vnd.ms-excel": ".xls",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+  "application/vnd.ms-excel.sheet.binary.macroenabled.12": ".xlsb",
+  "application/vnd.ms-excel.sheet.macroenabled.12": ".xlsm",
+  "application/vnd.ms-powerpoint": ".ppt",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
+  "application/json": ".json",
+  "application/zip": ".zip",
+  "application/gzip": ".gz",
+  "text/plain": ".txt",
+  "text/csv": ".csv",
+  "text/tab-separated-values": ".tsv",
+  "text/markdown": ".md"
 };
 function collectValues(value, previous) {
   previous.push(value);
   return previous;
 }
+function expandLeadingTilde(value) {
+  if (value === "~") {
+    return os2.homedir();
+  }
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return path3.join(os2.homedir(), value.slice(2));
+  }
+  return value;
+}
 function normalizeMediaInput(value) {
   const trimmed = value.trim();
   if (!trimmed) return "";
   if (/^file:\/\//i.test(trimmed)) {
     try {
-      return fileURLToPath(trimmed);
+      return expandLeadingTilde(fileURLToPath(trimmed));
     } catch {
-      return trimmed.replace(/^file:\/\//i, "");
+      return expandLeadingTilde(trimmed.replace(/^file:\/\//i, ""));
     }
   }
-  return trimmed;
+  return expandLeadingTilde(trimmed);
 }
 function normalizeInputList(values) {
   if (!values || values.length === 0) return [];
@@ -556,12 +591,88 @@ var EMOJI_REACTION_MAP = {
   "\u{1F62D}": Reactions.CRY,
   "\u{1F621}": Reactions.ANGRY
 };
+var DEBUG_COMMAND_START = /* @__PURE__ */ new WeakMap();
+function parseDebugFlag(value) {
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+function getActionCommand(args) {
+  for (let index = args.length - 1; index >= 0; index -= 1) {
+    const item = args[index];
+    if (item instanceof Command) {
+      return item;
+    }
+  }
+  return void 0;
+}
+function commandPathLabel(command) {
+  if (!command) return void 0;
+  const names = [];
+  let current = command;
+  while (current) {
+    const name = current.name();
+    if (name) {
+      names.unshift(name);
+    }
+    current = current.parent ?? null;
+  }
+  return names.join(" ");
+}
+function getDebugOptions(command) {
+  if (command) {
+    if (typeof command.optsWithGlobals === "function") {
+      return command.optsWithGlobals();
+    }
+    return command.opts();
+  }
+  if (typeof program.optsWithGlobals === "function") {
+    return program.optsWithGlobals();
+  }
+  return program.opts();
+}
+function resolveDebugEnabled(command) {
+  if (parseDebugFlag(process.env.OPENZCA_DEBUG)) {
+    return true;
+  }
+  return Boolean(getDebugOptions(command).debug);
+}
+function resolveDebugFilePath(command) {
+  const options = getDebugOptions(command);
+  const configured = options.debugFile?.trim() || process.env.OPENZCA_DEBUG_FILE?.trim() || path4.join(APP_HOME, "logs", "openzca-debug.log");
+  const normalized = normalizeMediaInput(configured);
+  return path4.isAbsolute(normalized) ? normalized : path4.resolve(process.cwd(), normalized);
+}
+function writeDebugLine(event, details, command) {
+  if (!resolveDebugEnabled(command)) {
+    return;
+  }
+  const payload = details ? JSON.stringify(details) : "";
+  const line = `${(/* @__PURE__ */ new Date()).toISOString()} ${event}${payload ? ` ${payload}` : ""}
+`;
+  const filePath = resolveDebugFilePath(command);
+  try {
+    fsSync.mkdirSync(path4.dirname(filePath), { recursive: true });
+    fsSync.appendFileSync(filePath, line, "utf8");
+  } catch {
+  }
+}
 function wrapAction(handler) {
   return async (...args) => {
+    const command = getActionCommand(args);
     try {
       await handler(...args);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
+      writeDebugLine(
+        "command.error",
+        {
+          command: commandPathLabel(command),
+          message,
+          stack: error instanceof Error ? error.stack : void 0
+        },
+        command
+      );
       console.error(`Error: ${message}`);
       process.exitCode = 1;
     }
@@ -835,6 +946,44 @@ function normalizeMessageType(value) {
   if (typeof value !== "string") return "";
   return value.trim().toLowerCase();
 }
+function looksLikeStructuredJsonString(value) {
+  const trimmed = value.trim();
+  if (trimmed.length < 2) return false;
+  const first = trimmed[0];
+  const last = trimmed[trimmed.length - 1];
+  if (first === "{" && last === "}") return true;
+  if (first === "[" && last === "]") return true;
+  return false;
+}
+function normalizeStructuredContent(value, depth = 0) {
+  if (depth > 5 || value === null || value === void 0) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!looksLikeStructuredJsonString(trimmed)) {
+      return value;
+    }
+    try {
+      const parsed = JSON.parse(trimmed);
+      return normalizeStructuredContent(parsed, depth + 1);
+    } catch {
+      return value;
+    }
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => normalizeStructuredContent(entry, depth + 1));
+  }
+  const record = asObject(value);
+  if (!record) {
+    return value;
+  }
+  const normalized = {};
+  for (const [key, nested] of Object.entries(record)) {
+    normalized[key] = normalizeStructuredContent(nested, depth + 1);
+  }
+  return normalized;
+}
 function detectInboundMediaKind(msgType, content) {
   const normalizedType = normalizeMessageType(msgType);
   if (normalizedType.includes("photo") || normalizedType.includes("gif") || normalizedType.includes("sticker")) {
@@ -846,7 +995,9 @@ function detectInboundMediaKind(msgType, content) {
   if (normalizedType.includes("link") || normalizedType.includes("location")) return null;
   const record = asObject(content);
   if (!record) return null;
-  if (getStringCandidate(record, ["voiceUrl", "m4aUrl"])) return "audio";
+  if (getStringCandidate(record, ["voiceUrl", "m4aUrl", "audioUrl", "voice_url", "m4a_url", "audio_url"])) {
+    return "audio";
+  }
   if (getStringCandidate(record, ["videoUrl"])) return "video";
   if (getStringCandidate(record, [
     "hdUrl",
@@ -859,15 +1010,22 @@ function detectInboundMediaKind(msgType, content) {
   ])) {
     return "image";
   }
-  if (getStringCandidate(record, ["fileUrl", "fileName", "fileId"])) return "file";
+  if (getStringCandidate(record, ["fileUrl", "fileName", "fileId", "href", "url"])) return "file";
   return null;
 }
 function collectHttpUrls(value, sink, depth = 0) {
   if (depth > 5 || sink.size >= 16) return;
   if (typeof value === "string") {
-    const trimmed = value.trim();
-    if (isHttpUrl(trimmed)) {
-      sink.add(trimmed);
+    const escapedNormalized = value.replace(/\\\//g, "/");
+    const matches = escapedNormalized.match(/https?:\/\/[^\s"'<>`]+/gi) ?? [];
+    for (const match of matches) {
+      const cleaned = match.replace(/[)\],.;"'`]+$/g, "").trim();
+      if (isHttpUrl(cleaned)) {
+        sink.add(cleaned);
+      }
+      if (sink.size >= 16) {
+        return;
+      }
     }
     return;
   }
@@ -894,6 +1052,8 @@ function preferredMediaKeys(kind) {
         "rawUrl",
         "oriUrl",
         "imageUrl",
+        "photoUrl",
+        "fileUrl",
         "thumbUrl",
         "thumb",
         "href",
@@ -901,11 +1061,48 @@ function preferredMediaKeys(kind) {
         "src"
       ];
     case "video":
-      return ["videoUrl", "fileUrl", "href", "url", "src"];
+      return [
+        "videoUrl",
+        "video_url",
+        "mediaUrl",
+        "streamUrl",
+        "playUrl",
+        "fileUrl",
+        "rawUrl",
+        "href",
+        "url",
+        "src"
+      ];
     case "audio":
-      return ["voiceUrl", "m4aUrl", "audioUrl", "fileUrl", "href", "url", "src"];
+      return [
+        "voiceUrl",
+        "m4aUrl",
+        "audioUrl",
+        "voice_url",
+        "m4a_url",
+        "audio_url",
+        "mediaUrl",
+        "downloadUrl",
+        "streamUrl",
+        "playUrl",
+        "fileUrl",
+        "rawUrl",
+        "href",
+        "url",
+        "src"
+      ];
     case "file":
-      return ["fileUrl", "href", "url", "src"];
+      return [
+        "fileUrl",
+        "downloadUrl",
+        "rawUrl",
+        "normalUrl",
+        "oriUrl",
+        "fileLink",
+        "href",
+        "url",
+        "src"
+      ];
   }
 }
 function resolvePreferredMediaUrls(kind, content) {
@@ -939,27 +1136,49 @@ function mediaExtFromTypeOrUrl(mediaType, mediaUrl, kind) {
   const normalizedType = mediaType?.split(";")[0]?.trim().toLowerCase() ?? "";
   const byType = {
     "image/jpeg": ".jpg",
+    "image/jpg": ".jpg",
     "image/png": ".png",
     "image/webp": ".webp",
     "image/gif": ".gif",
+    "image/heic": ".heic",
+    "image/heif": ".heif",
     "video/mp4": ".mp4",
+    "video/quicktime": ".mov",
+    "video/webm": ".webm",
     "audio/mpeg": ".mp3",
     "audio/mp3": ".mp3",
+    "audio/aac": ".aac",
+    "audio/x-aac": ".aac",
     "audio/mp4": ".m4a",
     "audio/x-m4a": ".m4a",
     "audio/wav": ".wav",
     "audio/ogg": ".ogg",
+    "audio/webm": ".webm",
     "application/pdf": ".pdf",
     "text/plain": ".txt",
+    "text/markdown": ".md",
     "text/csv": ".csv",
+    "text/tab-separated-values": ".tsv",
     "application/json": ".json",
+    "application/xml": ".xml",
+    "text/xml": ".xml",
     "application/zip": ".zip",
+    "application/gzip": ".gz",
+    "application/x-tar": ".tar",
+    "application/x-7z-compressed": ".7z",
+    "application/vnd.rar": ".rar",
     "application/vnd.ms-excel": ".xls",
     "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+    "application/vnd.ms-excel.sheet.binary.macroenabled.12": ".xlsb",
+    "application/vnd.ms-excel.sheet.macroenabled.12": ".xlsm",
     "application/msword": ".doc",
     "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
     "application/vnd.ms-powerpoint": ".ppt",
-    "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx"
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
+    "application/rtf": ".rtf",
+    "application/vnd.oasis.opendocument.text": ".odt",
+    "application/vnd.oasis.opendocument.spreadsheet": ".ods",
+    "application/vnd.oasis.opendocument.presentation": ".odp"
   };
   const fromType = byType[normalizedType];
   if (fromType) return fromType;
@@ -993,8 +1212,9 @@ function resolveOpenClawMediaDir() {
   return path4.join(stateDir, "media");
 }
 function resolveInboundMediaDir(profile) {
-  const configured = process.env.OPENZCA_LISTEN_MEDIA_DIR?.trim();
-  if (configured) {
+  const configuredRaw = process.env.OPENZCA_LISTEN_MEDIA_DIR?.trim();
+  if (configuredRaw) {
+    const configured = normalizeMediaInput(configuredRaw);
     return path4.isAbsolute(configured) ? configured : path4.resolve(process.cwd(), configured);
   }
   const legacyRequested = process.env.OPENZCA_LISTEN_MEDIA_LEGACY_DIR?.trim() === "1";
@@ -1039,8 +1259,11 @@ function summarizeStructuredContent(msgType, content) {
       "msg",
       "message",
       "text",
+      "caption",
       "title",
       "description",
+      "fileName",
+      "name",
       "href",
       "url",
       "src"
@@ -1161,7 +1384,38 @@ function toEpochSeconds(input) {
   }
   return Math.floor(numeric);
 }
-program.name("openzca").description("Open-source zca-cli compatible wrapper powered by zca-js").version(PKG_VERSION).option("-p, --profile <name>", "Profile name").showHelpAfterError();
+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)) {
+    return;
+  }
+  DEBUG_COMMAND_START.set(actionCommand, Date.now());
+  writeDebugLine(
+    "command.start",
+    {
+      command: commandPathLabel(actionCommand),
+      argv: process.argv.slice(2),
+      cwd: process.cwd(),
+      profileFlag: getDebugOptions(actionCommand).profile ?? null,
+      envProfile: process.env.ZCA_PROFILE ?? null
+    },
+    actionCommand
+  );
+});
+program.hook("postAction", (_parent, actionCommand) => {
+  if (!resolveDebugEnabled(actionCommand)) {
+    return;
+  }
+  const startedAt = DEBUG_COMMAND_START.get(actionCommand);
+  writeDebugLine(
+    "command.done",
+    {
+      command: commandPathLabel(actionCommand),
+      durationMs: typeof startedAt === "number" ? Date.now() - startedAt : void 0
+    },
+    actionCommand
+  );
+});
 var account = program.command("account").description("Multi-account profile management");
 account.command("list").alias("ls").alias("l").description("List all account profiles").action(
   wrapAction(async () => {
@@ -1248,7 +1502,7 @@ auth.command("login").description("Login with QR code").option("-q, --qr-path <p
 auth.command("login-cred [file]").alias("login-creds").description("Login using credential JSON file").action(
   wrapAction(async (file, command) => {
     const profile = await currentProfile(command);
-    const credentials = file ? await parseCredentialFile(path4.resolve(file)) : toCredentials(
+    const credentials = file ? await parseCredentialFile(path4.resolve(normalizeMediaInput(file))) : toCredentials(
       await loadCredentials(profile) ?? (() => {
         throw new Error(
           `No saved credentials for profile "${profile}". Run: openzca auth login`
@@ -1333,9 +1587,20 @@ msg.command("image <threadId> [file]").option("-u, --url <url>", "Image URL (rep
   wrapAction(
     async (threadId, file, opts, command) => {
       const { api } = await requireApi(command);
-      const files = [file, ...normalizeInputList(opts.url)].filter(Boolean);
+      const normalizedFile = file ? normalizeMediaInput(file) : void 0;
+      const files = [normalizedFile, ...normalizeInputList(opts.url)].filter(Boolean);
       const urlInputs = files.filter((entry) => isHttpUrl(entry));
       const localInputs = files.filter((entry) => !isHttpUrl(entry));
+      writeDebugLine(
+        "msg.image.inputs",
+        {
+          threadId,
+          isGroup: Boolean(opts.group),
+          localInputs,
+          urlInputs
+        },
+        command
+      );
       const downloaded = await downloadUrlsToTempFiles(urlInputs);
       try {
         const attachments = [...localInputs, ...downloaded.files];
@@ -1362,9 +1627,20 @@ msg.command("video <threadId> [file]").option("-u, --url <url>", "Video URL (rep
   wrapAction(
     async (threadId, file, opts, command) => {
       const { api } = await requireApi(command);
-      const files = [file, ...normalizeInputList(opts.url)].filter(Boolean);
+      const normalizedFile = file ? normalizeMediaInput(file) : void 0;
+      const files = [normalizedFile, ...normalizeInputList(opts.url)].filter(Boolean);
       const urlInputs = files.filter((entry) => isHttpUrl(entry));
       const localInputs = files.filter((entry) => !isHttpUrl(entry));
+      writeDebugLine(
+        "msg.video.inputs",
+        {
+          threadId,
+          isGroup: Boolean(opts.group),
+          localInputs,
+          urlInputs
+        },
+        command
+      );
       const downloaded = await downloadUrlsToTempFiles(urlInputs);
       try {
         const attachments = [...localInputs, ...downloaded.files];
@@ -1392,12 +1668,23 @@ msg.command("voice <threadId> [file]").option("-u, --url <url>", "Voice URL (rep
     async (threadId, file, opts, command) => {
       const { api } = await requireApi(command);
       const type = asThreadType(opts.group);
-      const files = [file, ...normalizeInputList(opts.url)].filter(Boolean);
+      const normalizedFile = file ? normalizeMediaInput(file) : void 0;
+      const files = [normalizedFile, ...normalizeInputList(opts.url)].filter(Boolean);
       if (files.length === 0) {
         throw new Error("Provide a voice file or --url.");
       }
       const urlInputs = files.filter((entry) => isHttpUrl(entry));
       const localInputs = files.filter((entry) => !isHttpUrl(entry));
+      writeDebugLine(
+        "msg.voice.inputs",
+        {
+          threadId,
+          isGroup: Boolean(opts.group),
+          localInputs,
+          urlInputs
+        },
+        command
+      );
       const downloaded = await downloadUrlsToTempFiles(urlInputs);
       try {
         const attachments = [...localInputs, ...downloaded.files];
@@ -1411,7 +1698,7 @@ msg.command("voice <threadId> [file]").option("-u, --url <url>", "Voice URL (rep
         }
         if (results.length === 0) {
           throw new Error(
-            "No valid voice attachment generated. Use an audio file (e.g. .mp3, .m4a, .wav, .ogg)."
+            "No valid voice attachment generated. Use an audio file (e.g. .aac, .mp3, .m4a, .wav, .ogg)."
           );
         }
         output(results, false);
@@ -1547,7 +1834,18 @@ msg.command("upload <arg1> [arg2]").option("-u, --url <url>", "File URL (repeata
       const urlInputs = inputs.filter((entry) => isHttpUrl(entry));
       const localInputs = inputs.filter((entry) => !isHttpUrl(entry));
       const [threadId, file] = arg2 ? [arg2, arg1] : [arg1, void 0];
-      const localFiles = [file, ...localInputs].filter(Boolean);
+      const normalizedFile = file ? normalizeMediaInput(file) : void 0;
+      const localFiles = [normalizedFile, ...localInputs].filter(Boolean);
+      writeDebugLine(
+        "msg.upload.inputs",
+        {
+          threadId,
+          isGroup: Boolean(opts.group),
+          localFiles,
+          urlInputs
+        },
+        command
+      );
       const downloaded = await downloadUrlsToTempFiles(urlInputs);
       try {
         const attachments = [...localFiles, ...downloaded.files];
@@ -1679,8 +1977,9 @@ group.command("rename <groupId> <name>").description("Rename group").action(
 group.command("avatar <groupId> <file>").description("Change group avatar").action(
   wrapAction(async (groupId, file, command) => {
     const { api } = await requireApi(command);
-    await assertFilesExist([file]);
-    const response = await api.changeGroupAvatar(file, groupId);
+    const normalizedFile = normalizeMediaInput(file);
+    await assertFilesExist([normalizedFile]);
+    const response = await api.changeGroupAvatar(normalizedFile, groupId);
     output(response, false);
   })
 );
@@ -2081,8 +2380,9 @@ me.command("update").option("--name <name>", "Display name").option("--gender <g
 me.command("avatar <file>").description("Change profile avatar").action(
   wrapAction(async (file, command) => {
     const { api } = await requireApi(command);
-    await assertFilesExist([file]);
-    output(await api.changeAccountAvatar(file), false);
+    const normalizedFile = normalizeMediaInput(file);
+    await assertFilesExist([normalizedFile]);
+    output(await api.changeAccountAvatar(normalizedFile), false);
   })
 );
 me.command("avatars").option("-j, --json", "JSON output").description("List avatars").action(
@@ -2124,6 +2424,17 @@ program.command("listen").description("Listen for real-time incoming messages").
     async (opts, command) => {
       const { profile, api } = await requireApi(command);
       console.log("Listening... Press Ctrl+C to stop.");
+      writeDebugLine(
+        "listen.start",
+        {
+          profile,
+          mediaDir: resolveInboundMediaDir(profile),
+          maxMediaBytes: parseMaxInboundMediaBytes(),
+          maxMediaFiles: parseMaxInboundMediaFiles(),
+          includeMediaUrl: process.env.OPENZCA_LISTEN_INCLUDE_MEDIA_URL?.trim() ?? null
+        },
+        command
+      );
       async function emitWebhook(payload) {
         if (!opts.webhook) return;
         try {
@@ -2150,10 +2461,24 @@ program.command("listen").description("Listen for real-time incoming messages").
         const messageData = message.data;
         const rawContent = messageData.content;
         const msgType = getStringCandidate(messageData, ["msgType"]);
+        const parsedContent = normalizeStructuredContent(rawContent);
+        const hasParsedStructuredContent = parsedContent !== rawContent;
         const rawText = typeof rawContent === "string" ? rawContent : "";
-        const mediaKind = detectInboundMediaKind(msgType, rawContent);
+        const mediaKind = detectInboundMediaKind(msgType, parsedContent);
         const maxMediaFiles = parseMaxInboundMediaFiles();
-        const remoteMediaUrls = mediaKind && maxMediaFiles > 0 ? resolvePreferredMediaUrls(mediaKind, rawContent).slice(0, maxMediaFiles) : [];
+        const remoteMediaUrls = mediaKind && maxMediaFiles > 0 ? resolvePreferredMediaUrls(mediaKind, parsedContent).slice(0, maxMediaFiles) : [];
+        writeDebugLine(
+          "listen.media.detected",
+          {
+            profile,
+            threadId: message.threadId,
+            msgType: msgType || void 0,
+            mediaKind,
+            hasParsedStructuredContent,
+            remoteMediaUrls
+          },
+          command
+        );
         const mediaEntries = [];
         for (const mediaUrl2 of remoteMediaUrls) {
           let mediaPath2;
@@ -2170,6 +2495,15 @@ program.command("listen").description("Listen for real-time incoming messages").
             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,
@@ -2184,12 +2518,12 @@ program.command("listen").description("Listen for real-time incoming messages").
         const mediaPath = mediaPaths[0];
         const mediaUrl = mediaUrls[0];
         const mediaType = mediaTypes[0];
-        const caption = rawText.trim().length > 0 ? rawText.trim() : summarizeStructuredContent(msgType, rawContent);
+        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 ? rawText : summarizeStructuredContent(msgType, rawContent);
+        }) : rawText.trim().length > 0 && !hasParsedStructuredContent ? rawText : summarizeStructuredContent(msgType, parsedContent);
         if (!processedText.trim()) return;
         if (opts.prefix) {
           if (!processedText.startsWith(opts.prefix)) return;

package/package.json

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