@cohortapp/agent-sdk 2.3.0

package/lib/channels/whatsapp/adapter-baileys.test.mjs

@@ -0,0 +1,359 @@
+/**
+ * adapter-baileys.test.mjs — WhatsApp (Baileys) adapter as a BaseAdapter subclass.
+ * Run: node --test lib/channels/whatsapp/adapter-baileys.test.mjs
+ *
+ * Task #30 hardening: the WhatsApp adapter used to be a plain factory object that
+ * bypassed BaseAdapter, so outbound was UNGATED and a dropped socket died after
+ * one swallowed reconnect. It now extends BaseAdapter, inheriting:
+ *   - send() → the ONE shared outbound send-gate (banned-phrase / AI-disclosure /
+ *     barrier screening) BEFORE the transport _send runs;
+ *   - a bounded-backoff reconnect SUPERVISOR (a transport drop → notifyDown →
+ *     supervised reconnect; a dead channel turns healthCheck() red);
+ *   - the ownId / peerAgentIds bot-loop guard.
+ *
+ * These tests never build a real WhatsApp socket: a FAKE sock records
+ * sendMessage / sendPresenceUpdate, injected via the test-only `__setSock` seam,
+ * and the reconnect supervisor is injected so the lifecycle is deterministic
+ * with no real timers. Hermetic — no network, no baileys install.
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createBaileysWhatsAppChannel, BaileysWhatsAppAdapter } from "./adapter-baileys.mjs";
+import { CHANNEL_COUNTERS } from "../base-adapter.mjs";
+import { CONN_STATE } from "../../util/reconnect.mjs";
+import { getPlatform } from "../contract.mjs";
+
+async function makeRoot() {
+  const p = join(tmpdir(), `wa-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  await fsp.mkdir(p, { recursive: true });
+  return p;
+}
+async function rmRoot(p) { try { await fsp.rm(p, { recursive: true, force: true }); } catch { /* */ } }
+
+/** A fake Baileys socket recording sendMessage + presence + react. */
+function fakeSock(opts = {}) {
+  return {
+    user: opts.user || { id: "97150000@s.whatsapp.net" },
+    sent: [],
+    presence: [],
+    async sendMessage(jid, payload, quoted) {
+      this.sent.push({ jid, payload, quoted });
+      return { key: { id: `wamid-${this.sent.length}`, remoteJid: jid } };
+    },
+    async sendPresenceUpdate(state, jid) { this.presence.push({ state, jid }); },
+    end() {},
+  };
+}
+
+/**
+ * Build an adapter wired for hermetic tests: in-memory counters, an allow-all
+ * send-gate by default (override per-test to drive the REAL gate), and the
+ * reconnect supervisor off unless a test injects one.
+ */
+function makeAdapter(opts = {}) {
+  const counters = [];
+  const a = new BaileysWhatsAppAdapter({
+    agentRoot: opts.agentRoot,
+    bump: (name, attrs) => { counters.push({ name, attrs }); return 1; },
+    screenOutbound: opts.screenOutbound || (async () => ({ allow: true, reason: "" })),
+    supervise: opts.supervise === undefined ? false : opts.supervise,
+    superviseConnection: opts.superviseConnection,
+    ...opts,
+  });
+  return { a, counters, countOf: (name) => counters.filter((c) => c.name === name).length };
+}
+
+// ---------------------------------------------------------------------------
+// shape / registration
+// ---------------------------------------------------------------------------
+
+test("createBaileysWhatsAppChannel returns a BaileysWhatsAppAdapter (BaseAdapter subclass)", () => {
+  const ch = createBaileysWhatsAppChannel({ agentRoot: "/tmp/x" });
+  assert.ok(ch instanceof BaileysWhatsAppAdapter);
+  assert.equal(ch.name, "whatsapp");
+  assert.equal(ch.transport, "baileys");
+  assert.equal(typeof ch.start, "function");
+  assert.equal(typeof ch.send, "function");
+  assert.equal(typeof ch.startTypingHeartbeat, "function");
+});
+
+test("whatsapp self-registers as a platform with the right gate file", () => {
+  const def = getPlatform("whatsapp");
+  assert.ok(def, "whatsapp platform must be registered on import");
+  assert.equal(def.gateFile, "config/whatsapp.yaml");
+  const inst = def.factory({ agentRoot: "/tmp/x" });
+  assert.equal(inst.name, "whatsapp");
+});
+
+// ---------------------------------------------------------------------------
+// send-gate (P0-3) — every WhatsApp send passes the shared gate before _send
+// ---------------------------------------------------------------------------
+
+test("send() blocks a banned-phrase message before the transport and counts it", async () => {
+  const root = await makeRoot();
+  try {
+    // Drive the REAL send-gate so a banned AI-tell phrase is caught at the
+    // shared chokepoint. The recipient is a phone jid → external, but the
+    // banned-phrase rule fires before any policy-file read.
+    const { a, countOf } = makeAdapter({ agentRoot: root, screenOutbound: undefined });
+    a._screenOutbound = (await import("../../comms/send-gate.mjs")).screenOutbound;
+    const sock = fakeSock();
+    a.__setSock(sock);
+
+    const res = await a.send({
+      to: "97150000@s.whatsapp.net",
+      text: "Sure — as an AI I can help with that.",
+      source: { channel: "whatsapp", chatId: "97150000@s.whatsapp.net" },
+    });
+    assert.equal(res.ok, false);
+    assert.equal(res.blocked, true, "blocked flag set");
+    assert.match(res.reason, /banned AI-tell|As an AI/i);
+    assert.equal(sock.sent.length, 0, "the transport must never run for a blocked message");
+    assert.equal(countOf(CHANNEL_COUNTERS.SEND_GATE_BLOCKED), 1, "the block is counted");
+  } finally { await rmRoot(root); }
+});
+
+test("send() blocks a disclosure-violating message (denies being an AI)", async () => {
+  const root = await makeRoot();
+  try {
+    const { a } = makeAdapter({ agentRoot: root, screenOutbound: undefined });
+    a._screenOutbound = (await import("../../comms/send-gate.mjs")).screenOutbound;
+    const sock = fakeSock();
+    a.__setSock(sock);
+    const res = await a.send({
+      to: "97150000@s.whatsapp.net",
+      text: "No, I'm not a bot — I'm a real person.",
+      source: { channel: "whatsapp", chatId: "97150000@s.whatsapp.net" },
+    });
+    assert.equal(res.ok, false);
+    assert.equal(res.blocked, true);
+    assert.match(res.reason, /disclosure|denies AI/i);
+    assert.equal(sock.sent.length, 0);
+  } finally { await rmRoot(root); }
+});
+
+test("send() lets a clean message reach the Baileys transport", async () => {
+  const root = await makeRoot();
+  try {
+    const { a } = makeAdapter({ agentRoot: root }); // allow-all gate stub
+    const sock = fakeSock();
+    a.__setSock(sock);
+    const res = await a.send({ to: "97150000@s.whatsapp.net", text: "the memo is ready" });
+    assert.equal(res.ok, true);
+    assert.equal(sock.sent.length, 1, "transport ran once for a clean message");
+    assert.deepEqual(sock.sent[0].payload, { text: "the memo is ready" });
+    assert.match(res.message_id, /^wamid-/);
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// _send transport behaviour preserved (text / voice note / media / quoted)
+// ---------------------------------------------------------------------------
+
+test("_send: bare number `to` is normalised to a jid", async () => {
+  const a = makeAdapter().a;
+  const sock = fakeSock();
+  a.__setSock(sock);
+  await a._send({ to: "+971 50 000", text: "hi" });
+  assert.equal(sock.sent[0].jid, "97150000@s.whatsapp.net");
+});
+
+test("_send: a voice_note attachment sends PTT audio", async () => {
+  const a = makeAdapter().a;
+  const sock = fakeSock();
+  a.__setSock(sock);
+  const res = await a._send({
+    to: "97150000@s.whatsapp.net",
+    attachments: [{ type: "voice_note", buffer: Buffer.from("ogg"), mime: "audio/ogg; codecs=opus" }],
+  });
+  assert.equal(sock.sent[0].payload.ptt, true);
+  assert.equal(res.ok, true);
+});
+
+test("_send: thread_ref produces a quoted reply", async () => {
+  const a = makeAdapter().a;
+  const sock = fakeSock();
+  a.__setSock(sock);
+  await a._send({ to: "97150000@s.whatsapp.net", text: "re", thread_ref: "97150000@s.whatsapp.net:ABC:false" });
+  assert.deepEqual(sock.sent[0].quoted, { key: { remoteJid: "97150000@s.whatsapp.net", id: "ABC", fromMe: false } });
+});
+
+test("_send throws when not connected (no sock)", async () => {
+  const a = makeAdapter().a;
+  await assert.rejects(() => a._send({ to: "x", text: "hi" }), /not connected/);
+});
+
+test("_react sends a reaction payload", async () => {
+  const a = makeAdapter().a;
+  const sock = fakeSock();
+  a.__setSock(sock);
+  await a._react({ messageRef: "97150000@s.whatsapp.net:M1:false", emoji: "🎉" });
+  assert.deepEqual(sock.sent[0].payload.react, { text: "🎉", key: { remoteJid: "97150000@s.whatsapp.net", id: "M1", fromMe: false } });
+});
+
+// ---------------------------------------------------------------------------
+// _toEvent — normalised inbound is forwarded as a MessageEvent with a source
+// ---------------------------------------------------------------------------
+
+test("_toEvent forwards a normalised inbound object; null for junk", () => {
+  const a = makeAdapter().a;
+  const ev = { channel: "whatsapp", text: "hi", from: { id: "x" }, source: { channel: "whatsapp", chatId: "x" } };
+  assert.equal(a._toEvent(ev), ev);
+  assert.equal(a._toEvent(null), null);
+  assert.equal(a._toEvent("nope"), null);
+});
+
+// ---------------------------------------------------------------------------
+// reconnect supervisor (P0-5/P0-6) — a transport drop reconnects, not dies
+// ---------------------------------------------------------------------------
+
+test("a transport drop triggers a supervised reconnect (injected supervisor)", async () => {
+  const root = await makeRoot();
+  try {
+    // Inject a fake supervisor so the reconnect lifecycle is deterministic.
+    const connects = [];
+    let captured = null;
+    const fakeSupervise = (cfg) => {
+      captured = cfg;
+      const started = Promise.resolve().then(() => cfg.connect()).then(() => {
+        connects.push("up");
+        cfg.onState(CONN_STATE.UP, { attempt: 1, reconnected: false });
+      });
+      return {
+        notifyDown: (reason) => {
+          cfg.onState(CONN_STATE.DOWN, { attempt: 2, delayMs: 500, reason });
+          return Promise.resolve().then(() => cfg.connect()).then(() => {
+            connects.push("reconnect");
+            cfg.onState(CONN_STATE.UP, { attempt: 2, reconnected: true });
+          });
+        },
+        stop: () => {},
+        get state() { return CONN_STATE.UP; },
+        get connection() { return null; },
+        get attempts() { return 0; },
+        started,
+      };
+    };
+
+    const { a, countOf } = makeAdapter({
+      agentRoot: root,
+      supervise: true,
+      superviseConnection: fakeSupervise,
+    });
+    a.__setSock(fakeSock()); // pre-inject so _connect doesn't try to load baileys
+    // Isolate the supervisor wiring: stub the transport _connect to a no-op so
+    // this case tests only the drop → reconnect lifecycle, not socket plumbing.
+    a._connect = async () => {};
+
+    await a.start({ onInbound: () => {} });
+    assert.ok(captured, "supervisor was constructed in start()");
+    assert.equal(connects.filter((c) => c === "up").length, 1, "initial connect happened");
+
+    // Simulate the provider's close listener reporting a drop.
+    await a.notifyConnectionDown("socket-closed");
+    await new Promise((r) => setTimeout(r, 5));
+    assert.ok(connects.includes("reconnect"), "a drop triggered a reconnect attempt");
+    assert.equal(countOf(CHANNEL_COUNTERS.RECONNECT_DOWN), 1, "the drop was counted");
+    assert.equal(countOf(CHANNEL_COUNTERS.RECONNECT_RECOVERED), 1, "the recovery was counted");
+
+    await a.stop();
+  } finally { await rmRoot(root); }
+});
+
+test("the connection.update 'close' handler reports the drop to the supervisor (notifyDown)", async () => {
+  const root = await makeRoot();
+  try {
+    // Build a fake sock whose ev.on captures the connection.update handler so we
+    // can fire a 'close' and assert it routes into notifyConnectionDown.
+    const handlers = {};
+    const sock = {
+      user: { id: "97150000@s.whatsapp.net" },
+      ev: { on: (name, fn) => { handlers[name] = fn; } },
+      end() {},
+    };
+    const a = makeAdapter({ agentRoot: root, supervise: false }).a;
+    a.__setSock(sock);
+    let downReason = null;
+    a.notifyConnectionDown = (reason) => { downReason = reason; };
+
+    // Drive _connect directly (supervise off → start() calls _connect once).
+    await a._connect({ onRaw: () => {}, signal: undefined });
+    assert.equal(typeof handlers["connection.update"], "function", "connection.update wired");
+
+    // A non-logout close must report a drop.
+    handlers["connection.update"]({ connection: "close", lastDisconnect: { error: { output: { statusCode: 500 } } } });
+    assert.match(String(downReason), /whatsapp-close:500/, "a transport close reports a supervised drop");
+  } finally { await rmRoot(root); }
+});
+
+test("a logged-out close does NOT thrash the reconnect loop", async () => {
+  const root = await makeRoot();
+  try {
+    const handlers = {};
+    const sock = { user: {}, ev: { on: (name, fn) => { handlers[name] = fn; } }, end() {} };
+    const a = makeAdapter({ agentRoot: root, supervise: false }).a;
+    a.__setSock(sock);
+    let downCalls = 0;
+    a.notifyConnectionDown = () => { downCalls += 1; };
+    await a._connect({ onRaw: () => {}, signal: undefined });
+    // statusCode 401 == DisconnectReason.loggedOut → no reconnect.
+    handlers["connection.update"]({ connection: "close", lastDisconnect: { error: { output: { statusCode: 401 } } } });
+    assert.equal(downCalls, 0, "a logged-out socket must not be reconnected (auth is gone)");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// bot-loop guard (P0-5) — inbound from self / a peer agent is dropped
+// ---------------------------------------------------------------------------
+
+test("inbound from a peer agent is dropped (no auto-reply, counted)", async () => {
+  const root = await makeRoot();
+  try {
+    const { a, countOf } = makeAdapter({
+      agentRoot: root,
+      peerAgentIds: ["A-peer@s.whatsapp.net"],
+    });
+    a.__setSock(fakeSock());
+    let onRaw = null;
+    a._connect = async ({ onRaw: cb }) => { onRaw = cb; };
+    const received = [];
+    await a.start({ onInbound: (ev) => received.push(ev) });
+    onRaw({
+      channel: "whatsapp",
+      text: "ack from sibling",
+      from: { id: "A-peer@s.whatsapp.net" },
+      timestamp: "2026-01-01T00:00:00.000Z",
+      source: { channel: "whatsapp", chatId: "A-peer@s.whatsapp.net", userScope: "dm", peerId: "A-peer@s.whatsapp.net" },
+    });
+    assert.equal(received.length, 0, "a known peer-agent message must never be auto-replied");
+    assert.equal(countOf(CHANNEL_COUNTERS.PEER_AGENT_DROPPED), 1);
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// healthCheck / stop
+// ---------------------------------------------------------------------------
+
+test("healthCheck reports connected when the sock has a user (unsupervised)", async () => {
+  const a = makeAdapter({ supervise: false }).a;
+  a.__setSock(fakeSock({ user: { id: "u@x" } }));
+  const hc = await a.healthCheck();
+  assert.equal(hc.ok, true);
+  assert.match(hc.detail, /connected as u@x/);
+});
+
+test("stop() clears typing timers and tears down the socket", async () => {
+  const a = makeAdapter().a;
+  const sock = fakeSock();
+  a.__setSock(sock);
+  a.startTypingHeartbeat({ chatId: "97150000@s.whatsapp.net" });
+  assert.equal(a.__typingTimerCount(), 1);
+  await a.stop();
+  assert.equal(a.__typingTimerCount(), 0, "typing timers cleared on stop");
+});

package/lib/channels/whatsapp/adapter-twilio.mjs

@@ -0,0 +1,65 @@
+/**
+ * Maestro — WhatsApp (Twilio) channel adapter
+ *
+ * Wraps the existing scripts/whatsapp-handler.mjs (inbound webhook) and
+ * scripts/send-whatsapp.sh (outbound) so the channel registry can route
+ * WhatsApp identically to Slack/Gmail.
+ *
+ * The Baileys-based adapter (lib/channels/whatsapp/adapter-baileys.mjs)
+ * is a separate file because it pulls in a heavyweight optional dep.
+ * Operators pick one or the other in `config/channels/whatsapp.yaml`.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CHANNEL_CAPABILITIES } from "../channel.mjs";
+
+const TWILIO_CAPABILITIES = [
+  CHANNEL_CAPABILITIES.SEND,
+  CHANNEL_CAPABILITIES.MEDIA_IMAGE,
+  CHANNEL_CAPABILITIES.MEDIA_DOCUMENT,
+];
+
+export function createTwilioWhatsAppChannel(opts = {}) {
+  const agentRoot = resolve(opts.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+  const sendScript = opts.sendScript || join(agentRoot, "scripts/send-whatsapp.sh");
+
+  return {
+    name: "whatsapp",
+    transport: "twilio",
+    capabilities: TWILIO_CAPABILITIES,
+
+    async start({ onInbound }) {
+      if (typeof onInbound !== "function") throw new Error("WhatsApp(Twilio).start: onInbound required");
+      // Inbound delivery is via scripts/whatsapp-handler.mjs (webhook).
+      // Items land in state/inbox/whatsapp/ which the daemon already polls.
+    },
+
+    async send(msg) {
+      if (!msg?.to) throw new Error("WhatsApp.send: msg.to (E.164 phone) required");
+      if (!existsSync(sendScript)) throw new Error(`WhatsApp.send: ${sendScript} not found`);
+      const args = [msg.to, msg.text || ""];
+      if (msg.attachments?.length) {
+        for (const a of msg.attachments) {
+          if (a.url) args.push("--media", a.url);
+        }
+      }
+      const out = execFileSync(sendScript, args, {
+        encoding: "utf-8",
+        timeout: 30_000,
+        env: { ...process.env, AGENT_ROOT: agentRoot },
+      });
+      return { message_id: out.trim(), raw: { stdout: out } };
+    },
+
+    async healthCheck() {
+      const present = existsSync(sendScript);
+      return { ok: present, detail: present ? "send-whatsapp.sh present" : `missing ${sendScript}` };
+    },
+
+    async stop() {},
+  };
+}
+
+export default createTwilioWhatsAppChannel;

package/lib/channels/whatsapp/baileys-typing.test.mjs

@@ -0,0 +1,154 @@
+/**
+ * baileys-typing.test.mjs — WhatsApp (Baileys) presence-based typing heartbeat.
+ * Run: node --test lib/channels/whatsapp/baileys-typing.test.mjs
+ *
+ * The real heartbeat drives `sock.sendPresenceUpdate("composing"|"paused", jid)`.
+ * We never build a real WhatsApp socket: a FAKE sock records every
+ * sendPresenceUpdate call, injected through the test-only `__setSock` seam (the
+ * production path sets `sock` inside start(); the seam just lets a test stand in
+ * a fake without connecting). Timers are unref'd intervals — we assert the
+ * IMMEDIATE send + idempotency + clean stop rather than waiting 8 real seconds.
+ *
+ * Covers: start → "composing" for the jid; second start for the same jid does
+ * not stack timers; stop → timer cleared + "paused"; fully fail-open when sock
+ * is null (and when sendPresenceUpdate throws).
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { createBaileysWhatsAppChannel } from "./adapter-baileys.mjs";
+
+/** A fake Baileys socket that records presence updates. */
+function fakeSock(opts = {}) {
+  const calls = [];
+  return {
+    calls,
+    async sendPresenceUpdate(state, jid) {
+      calls.push({ state, jid });
+      if (opts.throwOn && opts.throwOn === state) throw new Error("boom");
+    },
+  };
+}
+
+test("startTypingHeartbeat: sends 'composing' immediately for the derived jid", () => {
+  const ch = createBaileysWhatsAppChannel({ agentRoot: "/tmp/x" });
+  const sock = fakeSock();
+  ch.__setSock(sock); // test seam — stands in for a connected socket
+
+  ch.startTypingHeartbeat({ channel: "whatsapp", chatId: "97150000@s.whatsapp.net" });
+  assert.equal(sock.calls.length, 1, "one immediate presence update");
+  assert.deepEqual(sock.calls[0], { state: "composing", jid: "97150000@s.whatsapp.net" });
+
+  ch.stopTypingHeartbeat({ chatId: "97150000@s.whatsapp.net" });
+});
+
+test("startTypingHeartbeat: derives the jid from a bare number (normaliseJid)", () => {
+  const ch = createBaileysWhatsAppChannel({ agentRoot: "/tmp/x" });
+  const sock = fakeSock();
+  ch.__setSock(sock);
+
+  ch.startTypingHeartbeat({ channel: "whatsapp", chatId: "+971 50 000" });
+  assert.equal(sock.calls[0].jid, "97150000@s.whatsapp.net", "E.164 → jid");
+  ch.stopTypingHeartbeat({ chatId: "+971 50 000" });
+});
+
+test("startTypingHeartbeat: accepts a bare string source (chatId directly)", () => {
+  const ch = createBaileysWhatsAppChannel({ agentRoot: "/tmp/x" });
+  const sock = fakeSock();
+  ch.__setSock(sock);
+
+  ch.startTypingHeartbeat("97150000@s.whatsapp.net");
+  assert.deepEqual(sock.calls[0], { state: "composing", jid: "97150000@s.whatsapp.net" });
+  ch.stopTypingHeartbeat("97150000@s.whatsapp.net");
+});
+
+test("startTypingHeartbeat: a second start for the same jid does NOT stack timers", () => {
+  const ch = createBaileysWhatsAppChannel({ agentRoot: "/tmp/x" });
+  const sock = fakeSock();
+  ch.__setSock(sock);
+  const jid = "97150000@s.whatsapp.net";
+
+  const h1 = ch.startTypingHeartbeat({ chatId: jid });
+  // Second start: idempotent — refreshes 'composing' but keeps ONE timer.
+  const h2 = ch.startTypingHeartbeat({ chatId: jid });
+
+  // Exactly one active timer is tracked for the jid.
+  assert.equal(ch.__typingTimerCount(), 1, "only one timer per jid");
+  // Both calls returned the same handle (the existing one).
+  assert.equal(h1, h2, "second start returns the existing handle (no new timer)");
+
+  ch.stopTypingHeartbeat({ chatId: jid });
+  assert.equal(ch.__typingTimerCount(), 0, "timer cleared after stop");
+});
+
+test("stopTypingHeartbeat: clears the timer and sends 'paused'", () => {
+  const ch = createBaileysWhatsAppChannel({ agentRoot: "/tmp/x" });
+  const sock = fakeSock();
+  ch.__setSock(sock);
+  const jid = "97150000@s.whatsapp.net";
+
+  ch.startTypingHeartbeat({ chatId: jid });
+  assert.equal(ch.__typingTimerCount(), 1);
+  sock.calls.length = 0; // ignore the composing send
+
+  ch.stopTypingHeartbeat({ chatId: jid });
+  assert.equal(ch.__typingTimerCount(), 0, "timer removed");
+  assert.deepEqual(sock.calls, [{ state: "paused", jid }], "paused presence sent on stop");
+});
+
+test("stopTypingHeartbeat: stopping an unknown jid is a clean no-op (still best-effort paused)", () => {
+  const ch = createBaileysWhatsAppChannel({ agentRoot: "/tmp/x" });
+  const sock = fakeSock();
+  ch.__setSock(sock);
+
+  // No prior start → no timer to clear; should not throw.
+  assert.doesNotThrow(() => ch.stopTypingHeartbeat({ chatId: "99999@s.whatsapp.net" }));
+  assert.equal(ch.__typingTimerCount(), 0);
+});
+
+test("fail-open: with no sock, start/stop are no-ops and never throw", () => {
+  const ch = createBaileysWhatsAppChannel({ agentRoot: "/tmp/x" });
+  // sock is null (start() never called).
+  assert.doesNotThrow(() => ch.startTypingHeartbeat({ chatId: "97150000@s.whatsapp.net" }));
+  assert.doesNotThrow(() => ch.stopTypingHeartbeat({ chatId: "97150000@s.whatsapp.net" }));
+  assert.equal(ch.__typingTimerCount(), 0, "no timer created without a sock");
+});
+
+test("fail-open: an empty/blank source is ignored", () => {
+  const ch = createBaileysWhatsAppChannel({ agentRoot: "/tmp/x" });
+  const sock = fakeSock();
+  ch.__setSock(sock);
+  assert.doesNotThrow(() => ch.startTypingHeartbeat({}));
+  assert.doesNotThrow(() => ch.startTypingHeartbeat(""));
+  assert.equal(sock.calls.length, 0, "no presence sent for a blank source");
+  assert.equal(ch.__typingTimerCount(), 0);
+});
+
+test("fail-open: a throwing sock.sendPresenceUpdate does not propagate", () => {
+  const ch = createBaileysWhatsAppChannel({ agentRoot: "/tmp/x" });
+  const sock = fakeSock({ throwOn: "composing" });
+  ch.__setSock(sock);
+  // Immediate composing send throws inside the adapter — must be swallowed, and
+  // the timer must still be tracked (or cleanly absent), never a thrown error.
+  assert.doesNotThrow(() => ch.startTypingHeartbeat({ chatId: "97150000@s.whatsapp.net" }));
+  assert.doesNotThrow(() => ch.stopTypingHeartbeat({ chatId: "97150000@s.whatsapp.net" }));
+});
+
+test("the platform factory does NOT override the real heartbeat with a no-op", async () => {
+  // createWhatsAppPlatform wraps the channel; it must expose the REAL methods so
+  // the typing registry drives presence (the old no-op override is removed).
+  const mod = await import("./adapter-baileys.mjs");
+  // Re-derive the platform factory via the registry (definePlatform side-effect).
+  const { getPlatform } = await import("../contract.mjs");
+  const platform = getPlatform("whatsapp");
+  assert.ok(platform, "whatsapp platform registered");
+  const ch = platform.factory({ agentRoot: "/tmp/x" });
+  const sock = fakeSock();
+  ch.__setSock(sock);
+  ch.startTypingHeartbeat({ chatId: "97150000@s.whatsapp.net" });
+  assert.equal(sock.calls.length, 1, "platform-wrapped channel still drives real presence");
+  assert.deepEqual(sock.calls[0], { state: "composing", jid: "97150000@s.whatsapp.net" });
+  ch.stopTypingHeartbeat({ chatId: "97150000@s.whatsapp.net" });
+});