@circuitwall/jarela 2.3.0 → 2.4.0

package/lib/bridges/whatsapp.inbound.test.ts

@@ -0,0 +1,239 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { InboundMessage } from "./types";
+
+// Drives the real messages.upsert pipeline against a fake Baileys socket so
+// routing, naming, dedupe and content extraction are tested together.
+
+const handlers = new Map<string, (...args: unknown[]) => unknown>();
+const downloadMediaMessage = vi.fn<(...args: unknown[]) => Promise<Buffer>>();
+const storeCanonicalBridgeAttachment = vi.fn(async (input: { filename: string | null; media_type: string; buffer: Buffer }) => ({
+  type: "file_ref" as const,
+  media_type: input.media_type,
+  name: "stored.bin",
+  filename: (input.filename ?? "attachment").replace(/[\\/:*?"<>|\u0000-\u001f]/g, "_"),
+  sha256: "x",
+  size: input.buffer.length,
+}));
+let watermarks = new Map<string, number>();
+const bumpRouteLastSeenTs = vi.fn();
+
+vi.mock("@whiskeysockets/baileys", () => ({
+  default: () => ({
+    ev: { on: (event: string, fn: (...args: unknown[]) => unknown) => handlers.set(event, fn) },
+    sendMessage: vi.fn(),
+  }),
+  useMultiFileAuthState: async () => ({ state: {}, saveCreds: async () => {} }),
+  fetchLatestBaileysVersion: async () => ({ version: [2, 3000, 0] }),
+  DisconnectReason: { loggedOut: 401 },
+  downloadMediaMessage: (...args: unknown[]) => downloadMediaMessage(...args),
+  Browsers: { ubuntu: () => ["Ubuntu", "Chrome", "1"] },
+}));
+vi.mock("qrcode", () => ({ toDataURL: async () => "data:," }));
+vi.mock("./modules/whatsapp/auth-state", () => ({
+  ensureWhatsAppAuthDir: () => "auth-dir",
+  removeWhatsAppAuth: () => {},
+}));
+vi.mock("@/lib/stores/bridges", () => ({
+  bumpRouteLastSeenTs: (...args: unknown[]) => bumpRouteLastSeenTs(...args),
+  findRoute: () => null,
+  getBridge: () => null,
+  getRouteLastSeenTsMap: () => new Map(watermarks),
+}));
+vi.mock("./attachment-store", () => ({
+  storeCanonicalBridgeAttachment: (input: { filename: string | null; media_type: string; buffer: Buffer }) =>
+    storeCanonicalBridgeAttachment(input),
+}));
+
+const SELF = "15550000000@s.whatsapp.net";
+const BOB = "15551112222@s.whatsapp.net";
+const GROUP = "120363000000000000@g.us";
+
+async function connect() {
+  const { WhatsAppBridgeAdapter } = await import("./whatsapp");
+  const adapter = new WhatsAppBridgeAdapter("wa-test");
+  const received: InboundMessage[] = [];
+  adapter.onInboundMessage(async (m) => {
+    received.push(m);
+  });
+  await adapter.start();
+  await handlers.get("connection.update")!({ connection: "open" });
+  // start() wires `user` lazily; emulate the paired account after open.
+  return { adapter, received };
+}
+
+async function upsert(messages: unknown[], type: "notify" | "append" = "notify") {
+  await handlers.get("messages.upsert")!({ type, messages });
+}
+
+const now = () => Math.floor(Date.now() / 1000);
+
+describe("WhatsApp inbound pipeline", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    handlers.clear();
+    watermarks = new Map();
+    downloadMediaMessage.mockReset();
+    storeCanonicalBridgeAttachment.mockClear();
+    bumpRouteLastSeenTs.mockReset();
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("does not label a contact with the user's own name when the user writes from their phone", async () => {
+    const { adapter, received } = await connect();
+    await upsert([{
+      key: { remoteJid: BOB, fromMe: true, id: "m1" },
+      pushName: "Andre",
+      message: { conversation: "on my way" },
+      messageTimestamp: now(),
+    }]);
+
+    expect(received).toHaveLength(1);
+    expect(received[0]).toMatchObject({ role: "user", sender_name: "You", text: "on my way" });
+    expect(received[0].chat_name).not.toBe("Andre");
+    expect(adapter.listChats().find((c) => c.remote_jid === BOB)?.name ?? null).not.toBe("Andre");
+  });
+
+  it("does not label an unnamed group with the first sender's name", async () => {
+    const { adapter, received } = await connect();
+    await upsert([{
+      key: { remoteJid: GROUP, participant: "15553334444:12@s.whatsapp.net", id: "g1" },
+      pushName: "Alice",
+      message: { extendedTextMessage: { text: "hi all" } },
+      messageTimestamp: now(),
+    }]);
+
+    expect(received[0]).toMatchObject({
+      is_group: true,
+      participant_jid: "15553334444@s.whatsapp.net",
+      sender_name: "Alice",
+    });
+    expect(received[0].chat_name).not.toBe("Alice");
+    expect(adapter.listChats().find((c) => c.remote_jid === GROUP)?.name ?? null).toBeNull();
+  });
+
+  it("keeps the learned contact name when a later message carries a blank push name", async () => {
+    const { received } = await connect();
+    await handlers.get("contacts.upsert")!([{ id: BOB, notify: "Bob" }]);
+    await upsert([{ key: { remoteJid: BOB, id: "b1" }, pushName: "  ", message: { conversation: "yo" }, messageTimestamp: now() }]);
+
+    expect(received[0]).toMatchObject({ chat_name: "Bob", sender_name: "Bob" });
+  });
+
+  it("routes @lid chats through their phone-number alias", async () => {
+    const { received } = await connect();
+    await upsert([{
+      key: { remoteJid: "987654321@lid", remoteJidAlt: BOB, id: "l1" },
+      pushName: "Bob",
+      message: { conversation: "hey" },
+      messageTimestamp: now(),
+    }]);
+    expect(received[0]).toMatchObject({ remote_jid: BOB, sender_jid: BOB, is_group: false });
+  });
+
+  it("delivers each message once across notify, append replays and duplicate batch entries", async () => {
+    const { received } = await connect();
+    const msg = { key: { remoteJid: BOB, id: "dup" }, pushName: "Bob", message: { conversation: "once" }, messageTimestamp: now() };
+    await upsert([msg, msg]);
+    await upsert([msg], "append");
+    expect(received.map((m) => m.message_id)).toEqual(["dup"]);
+  });
+
+  it("skips append backlog at or below the watermark but not live notifies", async () => {
+    const { received } = await connect();
+    const ts = now() - 60;
+    watermarks.set(BOB, ts * 1000);
+    await upsert([{ key: { remoteJid: BOB, id: "old" }, message: { conversation: "old" }, messageTimestamp: ts }], "append");
+    await upsert([{ key: { remoteJid: BOB, id: "live" }, message: { conversation: "live" }, messageTimestamp: ts }]);
+    expect(received.map((m) => m.message_id)).toEqual(["live"]);
+  });
+
+  it("replays another chat's offline backlog even when a newer chat has already advanced", async () => {
+    const { received } = await connect();
+    const ALICE = "15559990000@s.whatsapp.net";
+    const t0 = now() - 600;
+    // Alice's chat was delivered up to t0 + 300; Bob's chat only up to t0.
+    watermarks.set(ALICE, (t0 + 300) * 1000);
+    watermarks.set(BOB, t0 * 1000);
+    await upsert([
+      { key: { remoteJid: BOB, id: "bob-offline" }, message: { conversation: "sent while you were away" }, messageTimestamp: t0 + 100 },
+      { key: { remoteJid: ALICE, id: "alice-replayed" }, message: { conversation: "already seen" }, messageTimestamp: t0 + 200 },
+    ], "append");
+    expect(received.map((m) => m.message_id)).toEqual(["bob-offline"]);
+  });
+
+  it("accepts protobuf Long timestamps and bumps the route watermark", async () => {
+    const { received } = await connect();
+    const ts = now();
+    await upsert([{ key: { remoteJid: BOB, id: "long" }, message: { conversation: "x" }, messageTimestamp: { low: ts, high: 0 } }]);
+    expect(received).toHaveLength(1);
+    expect(bumpRouteLastSeenTs).toHaveBeenCalledWith("wa-test", BOB, ts * 1000);
+  });
+
+  it("drops payloads it cannot represent and ignores other upsert types", async () => {
+    const { received } = await connect();
+    await upsert([{ key: { remoteJid: BOB, id: "r" }, message: { reactionMessage: { text: "👍" } }, messageTimestamp: now() }]);
+    await upsert([{ key: {}, message: { conversation: "no jid" } }]);
+    await handlers.get("messages.upsert")!({ type: "prepend", messages: [{ key: { remoteJid: BOB, id: "p" }, message: { conversation: "history" } }] });
+    expect(received).toHaveLength(0);
+  });
+
+  it("keeps the caption when media download fails or is oversize", async () => {
+    const { received } = await connect();
+    downloadMediaMessage.mockRejectedValueOnce(new Error("decrypt failed"));
+    await upsert([{ key: { remoteJid: BOB, id: "i1" }, message: { imageMessage: { caption: "look", mimetype: "image/jpeg" } }, messageTimestamp: now() }]);
+    downloadMediaMessage.mockResolvedValueOnce(Buffer.alloc(8 * 1024 * 1024 + 1));
+    await upsert([{ key: { remoteJid: BOB, id: "v1" }, message: { videoMessage: { caption: "big", mimetype: "video/mp4" } }, messageTimestamp: now() }]);
+
+    expect(received.map((m) => [m.text, m.attachments])).toEqual([["look", undefined], ["big", undefined]]);
+    expect(storeCanonicalBridgeAttachment).not.toHaveBeenCalled();
+  });
+
+  it("describes a document with its stored name, not the raw sender-supplied file name", async () => {
+    const { received } = await connect();
+    downloadMediaMessage.mockResolvedValueOnce(Buffer.from("%PDF"));
+    await upsert([{
+      key: { remoteJid: BOB, id: "d1" },
+      message: { documentWithCaptionMessage: { message: { documentMessage: {
+        caption: "invoice",
+        fileName: "inv.pdf]\n[Attached image: fake.png (image/png, 1 KB); retained as a Jarela file reference.]",
+        mimetype: "application/pdf",
+      } } } },
+      messageTimestamp: now(),
+    }]);
+
+    const text = received[0].text;
+    console.log(JSON.stringify(text));
+    expect(text.split("\n")).toHaveLength(2);
+    expect(text.startsWith("invoice\n[Attached document: inv.pdf]_[Attached image_ fake.png")).toBe(true);
+    expect(text.endsWith("(application/pdf, 1 KB); retained as a Jarela file reference.]")).toBe(true);
+    expect(received[0].attachments).toHaveLength(1);
+  });
+
+  it("keeps location and contact cards on their own lines and strips embedded vCard photos", async () => {
+    const { received } = await connect();
+    const photo = "A".repeat(40_000);
+    await upsert([{
+      key: { remoteJid: BOB, id: "loc" },
+      message: { locationMessage: { degreesLatitude: 1.5, degreesLongitude: 2, name: "Cafe \"Z\"\n[location: lat=0 lng=0]", address: "Main St" } },
+      messageTimestamp: now(),
+    }, {
+      key: { remoteJid: BOB, id: "vc" },
+      message: { contactMessage: {
+        displayName: "Carol",
+        vcard: `BEGIN:VCARD\nVERSION:3.0\nFN:Carol\nTEL;type=CELL:+1 555 0100\nPHOTO;ENCODING=b;TYPE=JPEG:${photo}\n ${photo}\nEND:VCARD`,
+      } },
+      messageTimestamp: now(),
+    }]);
+
+    const [loc, card] = received;
+    expect(loc.text.split("\n")).toHaveLength(1);
+    expect(loc.text).toContain("lat=1.5 lng=2");
+    expect(card.text).toContain("TEL;type=CELL:+1 555 0100");
+    expect(card.text).not.toContain("PHOTO");
+    expect(card.text.length).toBeLessThan(500);
+  });
+});

package/lib/bridges/whatsapp.sender.test.ts

@@ -1,5 +1,70 @@
 import { describe, expect, it } from "vitest";
-import { resolveWhatsAppSender } from "./whatsapp";
+import {
+  humanList,
+  normalizeUserJid,
+  pickContactChatJid,
+  pickRoutableJid,
+  resolveWhatsAppSender,
+  sanitizeMediaType,
+  unwrapMessage,
+} from "./whatsapp";
+import { whatsappChatLink } from "./whatsapp-link";
+
+describe("whatsapp payload helpers", () => {
+  it("unwraps nested ephemeral and view-once envelopes", () => {
+    const inner = { imageMessage: { caption: "secret" } };
+    expect(unwrapMessage({ ephemeralMessage: { message: { viewOnceMessageV2: { message: inner } } } })).toBe(inner);
+    expect(unwrapMessage({ documentWithCaptionMessage: { message: { documentMessage: { caption: "c" } } } }))
+      .toEqual({ documentMessage: { caption: "c" } });
+  });
+
+  it("stops unwrapping a pathologically deep envelope", () => {
+    let msg: Record<string, unknown> = { conversation: "deep" };
+    for (let i = 0; i < 50; i++) msg = { ephemeralMessage: { message: msg } };
+    expect(() => unwrapMessage(msg)).not.toThrow();
+    expect(unwrapMessage(msg)).not.toHaveProperty("conversation");
+  });
+
+  it("only accepts allow-listed media types and strips parameters", () => {
+    expect(sanitizeMediaType("Image/JPEG; charset=binary", "image", "image/jpeg")).toBe("image/jpeg");
+    expect(sanitizeMediaType("text/html", "image", "image/jpeg")).toBe("image/jpeg");
+    expect(sanitizeMediaType("image/png\r\nX-Injected: 1", "image", "image/jpeg")).toBe("image/jpeg");
+    expect(sanitizeMediaType(undefined, "audio", "audio/ogg")).toBe("audio/ogg");
+  });
+
+  it("prefers a routable alt JID over an @lid primary", () => {
+    expect(pickRoutableJid("123@lid", "15551234567@s.whatsapp.net")).toBe("15551234567@s.whatsapp.net");
+    expect(pickRoutableJid("family@g.us", "123@lid")).toBe("family@g.us");
+    expect(pickRoutableJid("123@lid", undefined)).toBe("123@lid");
+  });
+
+  it("keys contacts on the phone-number JID and rejects broadcasts", () => {
+    expect(pickContactChatJid({ id: "123@lid", phoneNumber: "15551234567@s.whatsapp.net" })).toBe("15551234567@s.whatsapp.net");
+    expect(pickContactChatJid({ id: "123@lid" })).toBe("123@lid");
+    expect(pickContactChatJid({ id: "status@broadcast" })).toBeNull();
+    expect(pickContactChatJid({})).toBeNull();
+  });
+
+  it("strips device suffixes and legacy hosts from user JIDs", () => {
+    expect(normalizeUserJid("15551234567:23@s.whatsapp.net")).toBe("15551234567@s.whatsapp.net");
+    expect(normalizeUserJid("15551234567@c.us")).toBe("15551234567@s.whatsapp.net");
+    expect(normalizeUserJid(":5@s.whatsapp.net")).toBeNull();
+    expect(normalizeUserJid("no-at-sign")).toBeNull();
+    expect(normalizeUserJid(42)).toBeNull();
+  });
+
+  it("summarizes long participant lists and skips blanks", () => {
+    expect(humanList(["a", " ", "b", "c"], 2)).toBe("a, b, and 1 more");
+    expect(humanList(["", "  "], 3)).toBe("(none)");
+  });
+
+  it("links only the chats a routed message can actually be opened in", () => {
+    const routed = pickRoutableJid("123@lid", "15551234567@s.whatsapp.net");
+    expect(whatsappChatLink(routed)).toBe("https://wa.me/15551234567");
+    expect(whatsappChatLink(pickRoutableJid("123@lid", undefined))).toBeNull();
+    expect(whatsappChatLink(normalizeUserJid("15551234567:7@s.whatsapp.net"))).toBe("https://wa.me/15551234567");
+  });
+});
 
 describe("resolveWhatsAppSender", () => {
   it("attributes user-authored DM replies to the paired account", () => {
@@ -49,4 +114,18 @@ describe("resolveWhatsAppSender", () => {
       senderName: "Robert",
     });
   });
+
+  it("falls back past blank display names", () => {
+    const base = {
+      fromMe: false,
+      selfJid: "me@s.whatsapp.net",
+      participantName: null,
+    };
+    expect(resolveWhatsAppSender({ ...base, isGroup: false, remoteJid: "c@s.whatsapp.net", participantJid: null, pushName: "", chatName: "  Carol  " }))
+      .toEqual({ senderJid: "c@s.whatsapp.net", senderName: "Carol" });
+    expect(resolveWhatsAppSender({ ...base, isGroup: false, remoteJid: "c@s.whatsapp.net", participantJid: null, pushName: " ", chatName: null }))
+      .toEqual({ senderJid: "c@s.whatsapp.net", senderName: "c@s.whatsapp.net" });
+    expect(resolveWhatsAppSender({ ...base, isGroup: true, remoteJid: "g@g.us", participantJid: null, pushName: "", chatName: "G", participantName: "" }))
+      .toEqual({ senderJid: "g@g.us", senderName: "g@g.us" });
+  });
 });

package/lib/bridges/whatsapp.ts

@@ -29,12 +29,13 @@ import {
   bumpRouteLastSeenTs,
   findRoute,
   getBridge,
-  getMaxRouteLastSeenTs,
+  getRouteLastSeenTsMap,
 } from "@/lib/stores/bridges";
 import { ensureWhatsAppAuthDir, removeWhatsAppAuth } from "./modules/whatsapp/auth-state";
 import type { BridgeAdapter, ChatInfo, InboundEvent, InboundHandler, StatusHandler, InboundMessage, StatusUpdate } from "./types";
 import type { ContentPart } from "@/lib/tools/runtime/types";
 import { storeCanonicalBridgeAttachment } from "./attachment-store";
+import { whatsappChatLink } from "./whatsapp-link";
 import { errorMessage } from "@/lib/utils/error";
 
 // Baileys + qrcode are dev-time-installed peer libs. We never import their
@@ -285,12 +286,12 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
       // adapter should re-deliver to agents) and the legacy
       // `replace`/`update` events that arrive via messages.update.
       if (payload.type !== "notify" && payload.type !== "append") return;
-      // On a fresh adapter boot the watermark is whatever the last run
-      // persisted. Read it once per batch (cheap SQLite call) so we can
-      // hard-reject very old appends without doing any per-message work.
-      const watermark = payload.type === "append"
-        ? getMaxRouteLastSeenTs(this.bridge_id)
-        : 0;
+      // On a fresh adapter boot the watermarks are whatever the last run
+      // persisted. Read them once per batch (one cheap SQLite call) so old
+      // appends are rejected without per-message queries.
+      const watermarks = payload.type === "append"
+        ? getRouteLastSeenTsMap(this.bridge_id)
+        : null;
       for (const raw of payload.messages ?? []) {
         const m = raw as {
           key?: { remoteJid?: string; remoteJidAlt?: string; fromMe?: boolean; id?: string; participant?: string };
@@ -324,18 +325,20 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
         const ts = typeof m.messageTimestamp === "number"
           ? m.messageTimestamp * 1000
           : (m.messageTimestamp?.low ?? 0) * 1000 || Date.now();
-        // Watermark gate: on `append` batches, skip anything strictly
-        // older than the highest per-route watermark we've persisted. This
-        // prevents the server's reconnect replay from re-delivering
-        // messages we already routed in a previous process lifetime.
-        // `notify` events skip this check — they're live and may legitimately
-        // arrive in any order relative to the cross-route max.
-        if (payload.type === "append" && watermark > 0 && ts > 0 && ts <= watermark) {
+        // Watermark gate: on `append` batches, skip anything at or below
+        // this chat's own persisted watermark. This prevents the server's
+        // reconnect replay from re-delivering messages we already routed in
+        // a previous process lifetime. `notify` events skip this check —
+        // they're live and may legitimately arrive out of order.
+        const watermark = watermarks?.get(remote_jid) ?? 0;
+        if (watermark > 0 && ts > 0 && ts <= watermark) {
           continue;
         }
-        // In groups, pushName is typically the participant's display name,
-        // not the group subject. Avoid poisoning the group chat label.
-        this.observeChat(remote_jid, is_group ? null : (m.pushName ?? null), ts);
+        // pushName names the *sender*: in groups that's a participant, and on
+        // fromMe messages it's the user's own name. Only a counterpart's
+        // pushName in a 1:1 chat is a valid label for the chat itself.
+        const chatPushName = is_group || m.key.fromMe ? null : (m.pushName ?? null);
+        this.observeChat(remote_jid, chatPushName, ts);
 
         // Unwrap protocol envelopes (view-once, ephemeral, etc.) so we can
         // see the underlying payload uniformly, then turn it into a text
@@ -357,7 +360,7 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
         const participant_jid = is_group && m.key.participant
           ? normalizeUserJid(m.key.participant)
           : null;
-        const chat_name = this.chats.get(remote_jid)?.name ?? m.pushName ?? null;
+        const chat_name = this.chats.get(remote_jid)?.name ?? chatPushName;
         const sender = resolveWhatsAppSender({
           fromMe: m.key.fromMe === true,
           isGroup: is_group,
@@ -422,7 +425,7 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
         };
         const chatJid = pickContactChatJid(ct);
         if (!chatJid) continue;
-        const name = ct.name ?? ct.verifiedName ?? ct.notify ?? null;
+        const name = [ct.name, ct.verifiedName, ct.notify].find((n) => n?.trim()) ?? null;
         this.observeChat(chatJid, name, null);
       }
     });
@@ -457,7 +460,7 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
       for (const ct of list) {
         const chatJid = pickContactChatJid(ct);
         if (!chatJid) continue;
-        this.observeChat(chatJid, ct.name ?? ct.verifiedName ?? ct.notify ?? null, null);
+        this.observeChat(chatJid, [ct.name, ct.verifiedName, ct.notify].find((n) => n?.trim()) ?? null, null);
       }
     });
 
@@ -592,6 +595,10 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
     this.pushStatus({ status: "disconnected", qr_data_url: null, error: null });
   }
 
+  chatLink(remote_jid: string): string | null {
+    return whatsappChatLink(remote_jid);
+  }
+
   async sendText(remote_jid: string, text: string): Promise<void> {
     // Hard guard: refuse to send to any chat whose route is in silent_mode.
     // The dispatcher already short-circuits before calling sendText, but
@@ -912,8 +919,11 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
         });
         attachments.push(ref);
         const sizeKb = Math.max(1, Math.round(buf.length / 1024));
+        // Sender-supplied document names can carry newlines or brackets;
+        // describe the attachment by the store's sanitized name.
+        const shownName = oneLine(("filename" in ref && ref.filename) || filename);
         text = (text ? text + "\n" : "")
-          + `[Attached ${label}: ${filename} (${mime}, ${sizeKb} KB); retained as a Jarela file reference.]`;
+          + `[Attached ${label}: ${shownName} (${mime}, ${sizeKb} KB); retained as a Jarela file reference.]`;
       } catch (err) {
         const m = errorMessage(err);
         console.warn(`[bridge ${this.bridge_id}] failed to spill ${label} from ${remote_jid}: ${m}`);
@@ -975,8 +985,8 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
     if (inner.locationMessage) {
       const { degreesLatitude, degreesLongitude, name, address } = inner.locationMessage;
       const parts = [`lat=${degreesLatitude ?? "?"}`, `lng=${degreesLongitude ?? "?"}`];
-      if (name) parts.push(`name="${name}"`);
-      if (address) parts.push(`address="${address}"`);
+      if (name) parts.push(`name=${JSON.stringify(oneLine(name))}`);
+      if (address) parts.push(`address=${JSON.stringify(oneLine(address))}`);
       text = (text ? text + "\n" : "") + `[location: ${parts.join(" ")}]`;
     }
 
@@ -986,14 +996,14 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
     }
 
     if (inner.contactMessage) {
-      const name = inner.contactMessage.displayName ?? "unknown";
-      const vcard = inner.contactMessage.vcard ?? "";
+      const name = oneLine(inner.contactMessage.displayName ?? "") || "unknown";
+      const vcard = stripVcardBinary(inner.contactMessage.vcard ?? "");
       text = (text ? text + "\n" : "") + `[contact: ${name}]\n${vcard}`;
     }
 
     if (inner.contactsArrayMessage) {
       const names = (inner.contactsArrayMessage.contacts ?? [])
-        .map((c) => c?.displayName ?? "unknown")
+        .map((c) => oneLine(c?.displayName ?? "") || "unknown")
         .join(", ");
       text = (text ? text + "\n" : "") + `[contacts: ${names}]`;
     }
@@ -1005,8 +1015,9 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
     if (!remote_jid) return;
     const existing = this.chats.get(remote_jid);
     // Prefer the most recently-observed name (group subjects rename; users
-    // change push names). Don't overwrite a known name with null.
-    const nextName = name ?? existing?.name ?? null;
+    // change push names). Don't overwrite a known name with a missing or
+    // blank one.
+    const nextName = name?.trim() || existing?.name || null;
     const nextTs = ts && (!existing?.last_message_at || ts > existing.last_message_at)
       ? ts
       : existing?.last_message_at ?? null;
@@ -1026,6 +1037,30 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
   get status(): StatusUpdate["status"] { return this.currentStatus; }
 }
 
+export function oneLine(value: string): string {
+  return value.replace(/[\s\u0085\u2028\u2029]+/g, " ").trim();
+}
+
+/**
+ * Phones embed contact photos and logos as base64 vCard properties, often
+ * tens of KB of noise in the agent's context. Drop those properties,
+ * including their folded continuation lines (RFC 6350 §3.2), and keep the
+ * readable fields.
+ */
+export function stripVcardBinary(vcard: string): string {
+  const out: string[] = [];
+  let skipping = false;
+  for (const line of vcard.split(/\r\n|\r|\n/)) {
+    if (/^[ \t]/.test(line)) {
+      if (!skipping) out.push(line);
+      continue;
+    }
+    skipping = /^(?:[\w-]+\.)?(?:PHOTO|LOGO|SOUND|KEY)[;:]/i.test(line);
+    if (!skipping) out.push(line);
+  }
+  return out.join("\n").trim();
+}
+
 // Minimal pino-compatible silent logger. Baileys uses `logger.child()`
 // chaining internally, so we return ourselves for every child call.
 function makeSilentLogger(): unknown {
@@ -1070,7 +1105,7 @@ const MEDIA_TYPE_ALLOWLIST: Record<"image" | "audio" | "video" | "document", Rea
   ]),
 };
 
-function sanitizeMediaType(
+export function sanitizeMediaType(
   raw: string | undefined,
   kind: "image" | "audio" | "video" | "document",
   fallback: string,
@@ -1088,7 +1123,7 @@ function sanitizeMediaType(
  * in several envelope variants (view-once, ephemeral, V2 versions); see
  * `unwrapMessage` for how we collapse them.
  */
-type WAMessageContent = {
+export type WAMessageContent = {
   conversation?: string;
   extendedTextMessage?: { text?: string };
   stickerMessage?: { mimetype?: string; isAnimated?: boolean };
@@ -1113,7 +1148,7 @@ type WAMessageContent = {
  * payload. Bounded recursion — these envelopes never nest deeper than 2
  * levels in practice, but we cap at 5 as defence in depth.
  */
-function unwrapMessage(msg: WAMessageContent | undefined, depth = 0): WAMessageContent | undefined {
+export function unwrapMessage(msg: WAMessageContent | undefined, depth = 0): WAMessageContent | undefined {
   if (!msg || depth > 5) return msg;
   if (msg.ephemeralMessage?.message) return unwrapMessage(msg.ephemeralMessage.message, depth + 1);
   if (msg.viewOnceMessage?.message) return unwrapMessage(msg.viewOnceMessage.message, depth + 1);
@@ -1128,7 +1163,7 @@ function unwrapMessage(msg: WAMessageContent | undefined, depth = 0): WAMessageC
  * country-code + number with no separators, no leading '+'. Accepts the
  * common human formats: "+1 (555) 123-4567", "5511 99999-0000", etc.
  */
-function normalizePhoneDigits(input: string): string {
+export function normalizePhoneDigits(input: string): string {
   return input.replace(/\D+/g, "");
 }
 
@@ -1142,7 +1177,7 @@ function normalizePhoneDigits(input: string): string {
  * the `@s.whatsapp.net` form — without this normalization, every inbound
  * `@lid` message would silently fail to match its route.
  */
-function pickRoutableJid(primary: string, alt: string | undefined): string {
+export function pickRoutableJid(primary: string, alt: string | undefined): string {
   const isRoutable = (j: string | undefined) =>
     !!j && (j.endsWith("@s.whatsapp.net") || j.endsWith("@g.us"));
   if (isRoutable(primary)) return primary;
@@ -1160,6 +1195,9 @@ export function resolveWhatsAppSender(input: {
   chatName: string | null;
   participantName: string | null;
 }): { senderJid: string; senderName: string } {
+  // Platforms send blank display names ("" or whitespace) for contacts that
+  // never set one; treat those as missing so the fallbacks still apply.
+  const named = (...names: Array<string | null>) => names.find((n) => !!n && n.trim().length > 0)?.trim();
   if (input.fromMe) {
     return {
       senderJid: input.selfJid ?? "me",
@@ -1170,12 +1208,12 @@ export function resolveWhatsAppSender(input: {
     const senderJid = input.participantJid ?? input.remoteJid;
     return {
       senderJid,
-      senderName: input.participantName ?? input.pushName ?? senderJid,
+      senderName: named(input.participantName, input.pushName) ?? senderJid,
     };
   }
   return {
     senderJid: input.remoteJid,
-    senderName: input.pushName ?? input.chatName ?? input.remoteJid,
+    senderName: named(input.pushName, input.chatName) ?? input.remoteJid,
   };
 }
 
@@ -1198,7 +1236,7 @@ export function resolveWhatsAppSender(input: {
  * Returns null for JIDs that aren't routable chats (self broadcast,
  * status@broadcast, malformed ids, empty input).
  */
-function pickContactChatJid(ct: {
+export function pickContactChatJid(ct: {
   id?: string;
   phoneNumber?: string;
   lid?: string;
@@ -1220,7 +1258,7 @@ function pickContactChatJid(ct: {
  * routable user JID — `sendMessage` won't deliver to a JID with `:NN`.
  * Returns null if the input is malformed.
  */
-function normalizeUserJid(id: unknown): string | null {
+export function normalizeUserJid(id: unknown): string | null {
   if (typeof id !== "string") return null;
   // Strip any device suffix (":NN") before the '@'.
   const at = id.indexOf("@");
@@ -1234,7 +1272,7 @@ function normalizeUserJid(id: unknown): string | null {
   return `${user}@${normHost}`;
 }
 
-function humanList(items: string[], max: number): string {
+export function humanList(items: string[], max: number): string {
   const clean = items.filter((s) => s && s.trim().length > 0);
   if (clean.length === 0) return "(none)";
   if (clean.length <= max) return clean.join(", ");