@openclaw/whatsapp 2026.5.1-beta.1

package/src/auto-reply/deliver-reply.ts

@@ -0,0 +1,279 @@
+import type { MarkdownTableMode } from "openclaw/plugin-sdk/config-types";
+import { chunkMarkdownTextWithMode, type ChunkMode } from "openclaw/plugin-sdk/reply-chunking";
+import type { ReplyPayload } from "openclaw/plugin-sdk/reply-chunking";
+import {
+  isReasoningReplyPayload,
+  sendMediaWithLeadingCaption,
+} from "openclaw/plugin-sdk/reply-payload";
+import { logVerbose, shouldLogVerbose } from "openclaw/plugin-sdk/runtime-env";
+import type { WhatsAppSendResult } from "../inbound/send-result.js";
+import { loadWebMedia } from "../media.js";
+import {
+  type DeliverableWhatsAppOutboundPayload,
+  normalizeWhatsAppOutboundPayload,
+  normalizeWhatsAppPayloadTextPreservingIndentation,
+  prepareWhatsAppOutboundMedia,
+  sendWhatsAppOutboundWithRetry,
+} from "../outbound-media-contract.js";
+import { buildQuotedMessageOptions, lookupInboundMessageMeta } from "../quoted-message.js";
+import { newConnectionId } from "../reconnect.js";
+import { formatError } from "../session.js";
+import { convertMarkdownTables } from "../text-runtime.js";
+import { markdownToWhatsApp } from "../text-runtime.js";
+import { whatsappOutboundLog } from "./loggers.js";
+import type { WebInboundMsg } from "./types.js";
+import { elide } from "./util.js";
+
+export type WhatsAppReplyDeliveryResult = {
+  results: WhatsAppSendResult[];
+  messageIds: string[];
+  providerAccepted: boolean;
+};
+
+export async function deliverWebReply(params: {
+  replyResult: ReplyPayload;
+  normalizedReplyResult?: DeliverableWhatsAppOutboundPayload<ReplyPayload>;
+  msg: WebInboundMsg;
+  mediaLocalRoots?: readonly string[];
+  maxMediaBytes: number;
+  textLimit: number;
+  chunkMode?: ChunkMode;
+  replyLogger: {
+    info: (obj: unknown, msg: string) => void;
+    warn: (obj: unknown, msg: string) => void;
+  };
+  connectionId?: string;
+  skipLog?: boolean;
+  tableMode?: MarkdownTableMode;
+}): Promise<WhatsAppReplyDeliveryResult> {
+  const { replyResult, msg, maxMediaBytes, textLimit, replyLogger, connectionId, skipLog } = params;
+  const replyStarted = Date.now();
+  const sendResults: WhatsAppSendResult[] = [];
+  const rememberSendResult = (result: WhatsAppSendResult | undefined) => {
+    if (result) {
+      sendResults.push(result);
+    }
+  };
+  const finishDelivery = (): WhatsAppReplyDeliveryResult => {
+    const messageIds = [...new Set(sendResults.flatMap((result) => result.messageIds))];
+    return {
+      results: sendResults,
+      messageIds,
+      providerAccepted: sendResults.some((result) => result.providerAccepted),
+    };
+  };
+  if (isReasoningReplyPayload(replyResult)) {
+    whatsappOutboundLog.debug(`Suppressed reasoning payload to ${msg.from}`);
+    return finishDelivery();
+  }
+  const tableMode = params.tableMode ?? "code";
+  const chunkMode = params.chunkMode ?? "length";
+  const normalizedReply =
+    params.normalizedReplyResult ??
+    normalizeWhatsAppOutboundPayload(replyResult, {
+      normalizeText: normalizeWhatsAppPayloadTextPreservingIndentation,
+    });
+  const convertedText = markdownToWhatsApp(
+    convertMarkdownTables(normalizedReply.text ?? "", tableMode),
+  );
+  const textChunks = chunkMarkdownTextWithMode(convertedText, textLimit, chunkMode);
+  const mediaList = normalizedReply.mediaUrls ?? [];
+
+  const getQuote = () => {
+    if (!replyResult.replyToId) {
+      return undefined;
+    }
+    // Use replyToId (not msg.id) so batched payloads quote the correct
+    // per-message target.  Look up cached metadata for the specific
+    // message being quoted — msg.body may be a combined batch body.
+    const cached = lookupInboundMessageMeta(msg.accountId, msg.chatId, replyResult.replyToId);
+    return buildQuotedMessageOptions({
+      messageId: replyResult.replyToId,
+      remoteJid: msg.chatId,
+      fromMe: cached?.fromMe ?? false,
+      participant: cached?.participant ?? (msg.chatType === "group" ? msg.senderJid : undefined),
+      messageText: cached?.body ?? "",
+    });
+  };
+
+  const sendWithRetry = async <T>(fn: () => Promise<T>, label: string, maxAttempts = 3) => {
+    return await sendWhatsAppOutboundWithRetry({
+      send: fn,
+      maxAttempts,
+      onRetry: ({ attempt, maxAttempts: retryMaxAttempts, backoffMs, errorText }) => {
+        logVerbose(
+          `Retrying ${label} to ${msg.from} after failure (${attempt}/${retryMaxAttempts - 1}) in ${backoffMs}ms: ${errorText}`,
+        );
+      },
+    });
+  };
+
+  // Text-only replies
+  if (mediaList.length === 0 && textChunks.length) {
+    const totalChunks = textChunks.length;
+    for (const [index, chunk] of textChunks.entries()) {
+      const chunkStarted = Date.now();
+      const quote = getQuote();
+      rememberSendResult(await sendWithRetry(() => msg.reply(chunk, quote), "text"));
+      if (!skipLog) {
+        const durationMs = Date.now() - chunkStarted;
+        whatsappOutboundLog.debug(
+          `Sent chunk ${index + 1}/${totalChunks} to ${msg.from} (${durationMs.toFixed(0)}ms)`,
+        );
+      }
+    }
+    const delivery = finishDelivery();
+    const logPayload = {
+      correlationId: msg.id ?? newConnectionId(),
+      connectionId: connectionId ?? null,
+      to: msg.from,
+      from: msg.to,
+      text: elide(replyResult.text, 240),
+      mediaUrl: null,
+      mediaSizeBytes: null,
+      mediaKind: null,
+      durationMs: Date.now() - replyStarted,
+    };
+    if (delivery.providerAccepted) {
+      replyLogger.info(logPayload, "auto-reply sent (text)");
+    } else {
+      replyLogger.warn(logPayload, "auto-reply text was not accepted by WhatsApp provider");
+    }
+    return delivery;
+  }
+
+  const remainingText = [...textChunks];
+
+  // Media (with optional caption on first item)
+  const leadingCaption = remainingText.shift() || "";
+  await sendMediaWithLeadingCaption({
+    mediaUrls: mediaList,
+    caption: leadingCaption,
+    send: async ({ mediaUrl, caption }) => {
+      const media = await prepareWhatsAppOutboundMedia(
+        await loadWebMedia(mediaUrl, {
+          maxBytes: maxMediaBytes,
+          localRoots: params.mediaLocalRoots,
+        }),
+        mediaUrl,
+      );
+      if (shouldLogVerbose()) {
+        logVerbose(
+          `Web auto-reply media size: ${(media.buffer.length / (1024 * 1024)).toFixed(2)}MB`,
+        );
+        logVerbose(`Web auto-reply media source: ${mediaUrl} (kind ${media.kind})`);
+      }
+      if (media.kind === "image") {
+        const quote = getQuote();
+        rememberSendResult(
+          await sendWithRetry(
+            () =>
+              msg.sendMedia(
+                {
+                  image: media.buffer,
+                  caption,
+                  mimetype: media.mimetype,
+                },
+                quote,
+              ),
+            "media:image",
+          ),
+        );
+      } else if (media.kind === "audio") {
+        const quote = getQuote();
+        rememberSendResult(
+          await sendWithRetry(
+            () =>
+              msg.sendMedia(
+                {
+                  audio: media.buffer,
+                  ptt: true,
+                  mimetype: media.mimetype,
+                },
+                quote,
+              ),
+            "media:audio",
+          ),
+        );
+        if (caption) {
+          rememberSendResult(
+            await sendWithRetry(() => msg.reply(caption, quote), "media:audio-text"),
+          );
+        }
+      } else if (media.kind === "video") {
+        const quote = getQuote();
+        rememberSendResult(
+          await sendWithRetry(
+            () =>
+              msg.sendMedia(
+                {
+                  video: media.buffer,
+                  caption,
+                  mimetype: media.mimetype,
+                },
+                quote,
+              ),
+            "media:video",
+          ),
+        );
+      } else {
+        const quote = getQuote();
+        rememberSendResult(
+          await sendWithRetry(
+            () =>
+              msg.sendMedia(
+                {
+                  document: media.buffer,
+                  fileName: media.fileName,
+                  caption,
+                  mimetype: media.mimetype,
+                },
+                quote,
+              ),
+            "media:document",
+          ),
+        );
+      }
+      whatsappOutboundLog.info(
+        `Sent media reply to ${msg.from} (${(media.buffer.length / (1024 * 1024)).toFixed(2)}MB)`,
+      );
+      replyLogger.info(
+        {
+          correlationId: msg.id ?? newConnectionId(),
+          connectionId: connectionId ?? null,
+          to: msg.from,
+          from: msg.to,
+          text: caption ?? null,
+          mediaUrl,
+          mediaSizeBytes: media.buffer.length,
+          mediaKind: media.kind,
+          durationMs: Date.now() - replyStarted,
+        },
+        "auto-reply sent (media)",
+      );
+    },
+    onError: async ({ error, mediaUrl, caption, isFirst }) => {
+      whatsappOutboundLog.error(`Failed sending web media to ${msg.from}: ${formatError(error)}`);
+      replyLogger.warn({ err: error, mediaUrl }, "failed to send web media reply");
+      if (!isFirst) {
+        return;
+      }
+      const warning = "⚠️ Media failed.";
+      const fallbackTextParts = [remainingText.shift() ?? caption ?? "", warning].filter(Boolean);
+      const fallbackText = fallbackTextParts.join("\n");
+      if (!fallbackText) {
+        return;
+      }
+      whatsappOutboundLog.warn(`Media skipped; sent text-only to ${msg.from}`);
+      rememberSendResult(
+        await sendWithRetry(() => msg.reply(fallbackText, getQuote()), "media:fallback-text"),
+      );
+    },
+  });
+
+  // Remaining text chunks after media
+  for (const chunk of remainingText) {
+    rememberSendResult(await sendWithRetry(() => msg.reply(chunk, getQuote()), "media:text"));
+  }
+  return finishDelivery();
+}

package/src/auto-reply/heartbeat-runner.runtime.ts

@@ -0,0 +1,33 @@
+export { appendCronStyleCurrentTimeLine } from "openclaw/plugin-sdk/agent-runtime";
+export {
+  canonicalizeMainSessionAlias,
+  loadSessionStore,
+  resolveSessionKey,
+  resolveStorePath,
+  updateSessionStore,
+} from "openclaw/plugin-sdk/session-store-runtime";
+export { getRuntimeConfig } from "openclaw/plugin-sdk/runtime-config-snapshot";
+export {
+  emitHeartbeatEvent,
+  resolveHeartbeatVisibility,
+  resolveIndicatorType,
+} from "openclaw/plugin-sdk/heartbeat-runtime";
+export {
+  hasOutboundReplyContent,
+  resolveSendableOutboundReplyParts,
+} from "openclaw/plugin-sdk/reply-payload";
+export {
+  DEFAULT_HEARTBEAT_ACK_MAX_CHARS,
+  HEARTBEAT_TOKEN,
+  getReplyFromConfig,
+  resolveHeartbeatPrompt,
+  resolveHeartbeatReplyPayload,
+  stripHeartbeatToken,
+} from "openclaw/plugin-sdk/reply-runtime";
+export { normalizeMainKey } from "openclaw/plugin-sdk/routing";
+export { getChildLogger } from "openclaw/plugin-sdk/runtime-env";
+export { redactIdentifier } from "openclaw/plugin-sdk/text-runtime";
+export { resolveWhatsAppHeartbeatRecipients } from "../runtime-api.js";
+export { sendMessageWhatsApp } from "../send.js";
+export { formatError } from "../session.js";
+export { whatsappHeartbeatLog } from "./loggers.js";

package/src/auto-reply/heartbeat-runner.test.ts

@@ -0,0 +1,214 @@
+import { redactIdentifier } from "openclaw/plugin-sdk/logging-core";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { sendMessageWhatsApp } from "../send.js";
+import type { getReplyFromConfig } from "./heartbeat-runner.runtime.js";
+
+const HEARTBEAT_TOKEN = "HEARTBEAT_OK";
+
+const state = vi.hoisted(() => ({
+  visibility: { showAlerts: true, showOk: true, useIndicator: false },
+  store: {} as Record<string, { updatedAt?: number; sessionId?: string }>,
+  snapshot: {
+    key: "k",
+    entry: { sessionId: "s1", updatedAt: 123 },
+    fresh: false,
+    resetPolicy: { mode: "none", atHour: null, idleMinutes: null },
+    dailyResetAt: null as number | null,
+    idleExpiresAt: null as number | null,
+  },
+  events: [] as unknown[],
+  loggerInfoCalls: [] as unknown[][],
+  loggerWarnCalls: [] as unknown[][],
+  heartbeatInfoLogs: [] as string[],
+  heartbeatWarnLogs: [] as string[],
+}));
+
+vi.mock("./heartbeat-runner.runtime.js", () => {
+  const logger = {
+    child: () => logger,
+    info: (...args: unknown[]) => state.loggerInfoCalls.push(args),
+    warn: (...args: unknown[]) => state.loggerWarnCalls.push(args),
+    error: vi.fn(),
+    debug: vi.fn(),
+  };
+  return {
+    DEFAULT_HEARTBEAT_ACK_MAX_CHARS: 32,
+    HEARTBEAT_TOKEN,
+    appendCronStyleCurrentTimeLine: (body: string) =>
+      `${body}\nCurrent time: 2026-02-15T00:00:00Z (mock)`,
+    canonicalizeMainSessionAlias: ({ sessionKey }: { sessionKey: string }) => sessionKey,
+    emitHeartbeatEvent: (event: unknown) => state.events.push(event),
+    formatError: (err: unknown) => `ERR:${String(err)}`,
+    getChildLogger: () => logger,
+    getReplyFromConfig: vi.fn(async () => undefined),
+    hasOutboundReplyContent: (payload: { text?: string } | undefined) =>
+      Boolean(payload?.text?.trim()),
+    loadConfig: () => ({ agents: { defaults: {} }, session: {} }),
+    loadSessionStore: () => state.store,
+    normalizeMainKey: () => null,
+    redactIdentifier,
+    resolveHeartbeatPrompt: (prompt?: string) => prompt || "Heartbeat",
+    resolveHeartbeatReplyPayload: (reply: unknown) => reply,
+    resolveHeartbeatVisibility: () => state.visibility,
+    resolveIndicatorType: (status: string) => `indicator:${status}`,
+    resolveSendableOutboundReplyParts: (payload: { text?: string }) => ({
+      text: payload.text ?? "",
+      hasMedia: false,
+    }),
+    resolveSessionKey: () => "k",
+    resolveStorePath: () => "/tmp/store.json",
+    resolveWhatsAppHeartbeatRecipients: () => [],
+    sendMessageWhatsApp: vi.fn(async () => ({ messageId: "m1" })),
+    stripHeartbeatToken: (text: string) => {
+      const trimmed = text.trim();
+      if (trimmed === HEARTBEAT_TOKEN) {
+        return { shouldSkip: true, text: "" };
+      }
+      return { shouldSkip: false, text: trimmed };
+    },
+    updateSessionStore: async (_path: string, updater: (store: typeof state.store) => void) => {
+      updater(state.store);
+    },
+    whatsappHeartbeatLog: {
+      info: (msg: string) => state.heartbeatInfoLogs.push(msg),
+      warn: (msg: string) => state.heartbeatWarnLogs.push(msg),
+    },
+  };
+});
+
+vi.mock("./session-snapshot.js", () => ({
+  getSessionSnapshot: () => state.snapshot,
+}));
+
+vi.mock("../reconnect.js", () => ({
+  newConnectionId: () => "run-1",
+}));
+
+describe("runWebHeartbeatOnce", () => {
+  let senderMock: ReturnType<typeof vi.fn>;
+  let sender: typeof sendMessageWhatsApp;
+  let replyResolverMock: ReturnType<typeof vi.fn>;
+  let replyResolver: typeof getReplyFromConfig;
+  let runWebHeartbeatOnce: typeof import("./heartbeat-runner.js").runWebHeartbeatOnce;
+
+  const buildRunArgs = (overrides: Record<string, unknown> = {}) => ({
+    cfg: { agents: { defaults: {} }, session: {} } as never,
+    to: "+123",
+    sender,
+    replyResolver,
+    ...overrides,
+  });
+
+  beforeAll(async () => {
+    ({ runWebHeartbeatOnce } = await import("./heartbeat-runner.js"));
+  });
+
+  beforeEach(() => {
+    state.visibility = { showAlerts: true, showOk: true, useIndicator: false };
+    state.store = { k: { updatedAt: 999, sessionId: "s1" } };
+    state.snapshot = {
+      key: "k",
+      entry: { sessionId: "s1", updatedAt: 123 },
+      fresh: false,
+      resetPolicy: { mode: "none", atHour: null, idleMinutes: null },
+      dailyResetAt: null,
+      idleExpiresAt: null,
+    };
+    state.events = [];
+    state.loggerInfoCalls = [];
+    state.loggerWarnCalls = [];
+    state.heartbeatInfoLogs = [];
+    state.heartbeatWarnLogs = [];
+
+    senderMock = vi.fn(async () => ({ messageId: "m1" }));
+    sender = senderMock as unknown as typeof sendMessageWhatsApp;
+    replyResolverMock = vi.fn(async () => undefined);
+    replyResolver = replyResolverMock as unknown as typeof getReplyFromConfig;
+  });
+
+  it("supports manual override body dry-run without sending", async () => {
+    await runWebHeartbeatOnce(buildRunArgs({ overrideBody: "hello", dryRun: true }));
+    expect(senderMock).not.toHaveBeenCalled();
+    expect(state.events).toHaveLength(0);
+  });
+
+  it("sends HEARTBEAT_OK when reply is empty and showOk is enabled", async () => {
+    await runWebHeartbeatOnce(buildRunArgs());
+    expect(senderMock).toHaveBeenCalledWith(
+      "+123",
+      HEARTBEAT_TOKEN,
+      expect.objectContaining({ verbose: false, cfg: expect.any(Object) }),
+    );
+    expect(state.events).toEqual(
+      expect.arrayContaining([expect.objectContaining({ status: "ok-empty", silent: false })]),
+    );
+  });
+
+  it("injects a cron-style Current time line into the heartbeat prompt", async () => {
+    await runWebHeartbeatOnce(
+      buildRunArgs({
+        cfg: { agents: { defaults: { heartbeat: { prompt: "Ops check" } } }, session: {} } as never,
+        dryRun: true,
+      }),
+    );
+    expect(replyResolver).toHaveBeenCalledTimes(1);
+    const ctx = replyResolverMock.mock.calls[0]?.[0];
+    expect(ctx?.Body).toContain("Ops check");
+    expect(ctx?.Body).toContain("Current time: 2026-02-15T00:00:00Z (mock)");
+  });
+
+  it("treats heartbeat token-only replies as ok-token and preserves session updatedAt", async () => {
+    replyResolverMock.mockResolvedValue({ text: HEARTBEAT_TOKEN });
+    await runWebHeartbeatOnce(buildRunArgs());
+    expect(state.store.k?.updatedAt).toBe(123);
+    expect(senderMock).toHaveBeenCalledWith(
+      "+123",
+      HEARTBEAT_TOKEN,
+      expect.objectContaining({ verbose: false, cfg: expect.any(Object) }),
+    );
+    expect(state.events).toEqual(
+      expect.arrayContaining([expect.objectContaining({ status: "ok-token", silent: false })]),
+    );
+  });
+
+  it("skips sending alerts when showAlerts is disabled but still emits a skipped event", async () => {
+    state.visibility = { showAlerts: false, showOk: true, useIndicator: true };
+    replyResolverMock.mockResolvedValue({ text: "ALERT" });
+    await runWebHeartbeatOnce(buildRunArgs());
+    expect(senderMock).not.toHaveBeenCalled();
+    expect(state.events).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ status: "skipped", reason: "alerts-disabled", preview: "ALERT" }),
+      ]),
+    );
+  });
+
+  it("emits failed events when sending throws and rethrows the error", async () => {
+    replyResolverMock.mockResolvedValue({ text: "ALERT" });
+    senderMock.mockRejectedValueOnce(new Error("nope"));
+    await expect(runWebHeartbeatOnce(buildRunArgs())).rejects.toThrow("nope");
+    expect(state.events).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ status: "failed", reason: "ERR:Error: nope" }),
+      ]),
+    );
+  });
+
+  it("redacts recipient and omits body preview in heartbeat logs", async () => {
+    replyResolverMock.mockResolvedValue({ text: "sensitive heartbeat body" });
+    await runWebHeartbeatOnce(buildRunArgs({ dryRun: true }));
+
+    const expected = redactIdentifier("+123");
+    const heartbeatLogs = state.heartbeatInfoLogs.join("\n");
+    const childLoggerLogs = state.loggerInfoCalls.map((entry) => JSON.stringify(entry)).join("\n");
+
+    expect(heartbeatLogs).toContain(expected);
+    expect(heartbeatLogs).not.toContain("+123");
+    expect(heartbeatLogs).not.toContain("sensitive heartbeat body");
+
+    expect(childLoggerLogs).toContain(expected);
+    expect(childLoggerLogs).not.toContain("+123");
+    expect(childLoggerLogs).not.toContain("sensitive heartbeat body");
+    expect(childLoggerLogs).not.toContain('"preview"');
+  });
+});