openzca 0.1.13 → 0.1.14

package/README.md

@@ -207,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:
@@ -243,6 +255,8 @@ 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:
@@ -254,6 +268,12 @@ Listener resilience override:
 - `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:
 

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 = [];
@@ -2453,6 +2609,12 @@ program.command("listen").description("Listen for real-time incoming messages").
       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;
@@ -2484,6 +2646,8 @@ program.command("listen").description("Listen for real-time incoming messages").
           lifecycleEventsEnabled,
           heartbeatMs: lifecycleEventsEnabled ? heartbeatMs : void 0,
           recycleMs: recycleEnabled ? recycleMs : void 0,
+          includeReplyContext,
+          downloadQuoteMedia,
           sessionId
         },
         command
@@ -2524,12 +2688,14 @@ program.command("listen").description("Listen for real-time incoming messages").
         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",
           {
@@ -2538,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));
@@ -2581,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"]);
@@ -2610,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,
@@ -2629,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,

package/package.json

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