talon-agent 3.33.4 → 3.34.0

package/src/frontend/whatsapp/connection.ts

@@ -0,0 +1,280 @@
+/**
+ * The Baileys socket lifecycle: one socket per `connectOnce`, the
+ * reconnect/backoff loop around it, and the parked state a logged-out or
+ * never-paired account waits in until `/whatsapp pair` links it.
+ */
+
+import { rmSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve as resolvePath } from "node:path";
+import makeWASocket, { type AuthenticationState, type WASocket } from "baileys";
+import qrcode from "qrcode-terminal";
+import { log, logError, logWarn } from "../../util/log.js";
+import { dirs } from "../../util/paths.js";
+import { notifyAdmin } from "../../core/notify.js";
+import { useAtomicAuthState } from "./auth-state.js";
+import { bareId } from "./identity.js";
+import { handleInbound } from "./inbound.js";
+import { classifyClose, isPaired, REPLACED_BACKOFF_MS } from "./pairing.js";
+import { isManualPairingActive, onPairingComplete } from "./pairing-lock.js";
+import {
+  RECONNECT_BASE_MS,
+  RECONNECT_MAX_MS,
+  type WhatsAppRuntime,
+} from "./runtime.js";
+import { makeWaLogger } from "./wa-logger.js";
+
+/** What the connection loop should do after a socket ends. */
+type ConnectOutcome = "reconnect" | "logged-out" | "unpaired" | "stop";
+
+function bindInbound(runtime: WhatsAppRuntime, socket: WASocket): void {
+  socket.ev.on("messages.upsert", ({ messages, type }) => {
+    // "notify" is a live message. "append" is everything delivered out
+    // of band — chiefly messages QUEUED WHILE THE DAEMON WAS DOWN
+    // (Baileys marks offline-queued nodes as append), but also our own
+    // sends echoing back and newsletter posts, which handleInbound's
+    // fromMe/allowlist gates drop. Dropping append wholesale meant any
+    // message sent during a restart simply vanished: never recorded,
+    // never answered. Appends are processed as catch-up: always
+    // recorded, replied to only while fresh.
+    if (type !== "notify" && type !== "append") return;
+    const catchUp = type === "append";
+    for (const msg of messages) {
+      void handleInbound(runtime, msg, { catchUp }).catch((err) => {
+        logError(
+          "whatsapp",
+          `inbound handler failed: ${err instanceof Error ? err.message : err}`,
+        );
+      });
+    }
+  });
+}
+
+function onQr(runtime: WhatsAppRuntime, qr: string): void {
+  // The frontend NEVER requests pairing codes on its own — that
+  // loop once burned ~30 codes in 80 minutes and rate-limited
+  // the account. Pairing is on demand via /whatsapp pair
+  // (core/pairing-broker.ts). The terminal QR stays for
+  // foreground first-run setups without a Telegram admin.
+  log(
+    "whatsapp",
+    "Not linked — pair on demand with /whatsapp pair (Telegram), " +
+      "or scan below: WhatsApp → Linked devices → Link a device",
+  );
+  qrcode.generate(qr, { small: true });
+  if (!runtime.unpairedNotified) {
+    runtime.unpairedNotified = true;
+    void notifyAdmin(
+      "📱 WhatsApp is not linked. Send /whatsapp pair when you're " +
+        "ready and I'll reply with a QR to scan.",
+    );
+  }
+}
+
+function onOpen(runtime: WhatsAppRuntime, socket: WASocket): void {
+  // Both forms: a group can @-mention us by either.
+  runtime.selfIds = [socket.user?.id, socket.user?.lid]
+    .filter((id): id is string => Boolean(id))
+    .map(bareId);
+  runtime.reconnectDelay = RECONNECT_BASE_MS;
+  if (runtime.unpairedNotified) {
+    void notifyAdmin("✅ WhatsApp linked and connected.");
+  }
+  runtime.unpairedNotified = false;
+  log(
+    "whatsapp",
+    `Connected as ${socket.user?.name ?? "?"} (${runtime.selfIds.join("/") || "?"})`,
+  );
+}
+
+function onClose(
+  runtime: WhatsAppRuntime,
+  state: AuthenticationState,
+  code: number | undefined,
+): ConnectOutcome {
+  if (runtime.stopping) return "stop";
+  const disposition = classifyClose(code, state.creds.registered);
+  switch (disposition.kind) {
+    case "pairing-accepted":
+      // 515 right after a pairing code/QR is SUCCESS, not an
+      // error: WhatsApp requires one reconnect with the same
+      // credentials to complete the login.
+      log(
+        "whatsapp",
+        "Pairing accepted (515) — reconnecting to complete login",
+      );
+      runtime.reconnectDelay = RECONNECT_BASE_MS;
+      return "reconnect";
+    case "replaced":
+      // Another socket owns this session (440). Fighting it with
+      // an instant reconnect just steals the session back and
+      // forth; sit out a full minute instead.
+      logWarn(
+        "whatsapp",
+        "Connection replaced by another client (440) — backing off",
+      );
+      runtime.reconnectDelay = REPLACED_BACKOFF_MS;
+      return "reconnect";
+    case "logged-out":
+      return "logged-out";
+    default:
+      // A socket that died without ever completing a login is a
+      // pairing window that expired — reconnecting would just open QR
+      // session after QR session against WhatsApp's servers.
+      // Park instead; /whatsapp pair opens the next one.
+      //
+      // Test with isPaired, not creds.registered: a QR-linked session
+      // never sets that flag, so the flag alone parks a healthy
+      // session on its first ordinary disconnect.
+      if (!isPaired(state.creds)) return "unpaired";
+      log("whatsapp", `Connection closed (code ${code ?? "?"}) — reconnecting`);
+      return "reconnect";
+  }
+}
+
+/** One socket lifetime. Resolves with what the caller should do next. */
+async function connectOnce(runtime: WhatsAppRuntime): Promise<ConnectOutcome> {
+  // Atomic replacement for Baileys' useMultiFileAuthState — same disk
+  // format, torn-write-proof (see auth-state.ts for why that matters).
+  const { state, saveCreds } = await useAtomicAuthState(dirs.whatsappAuth);
+  const socket = makeWASocket({
+    auth: state,
+    logger: makeWaLogger(),
+    markOnlineOnConnect: false,
+    // The account is a bot: announcing "online" would suppress the
+    // phone's own notifications for the human who owns the number.
+    //
+    // 120s per QR/pairing ref — the default (60s + 20s refreshes) gave
+    // a ~2½-minute socket lifetime in pairing mode, shorter than it
+    // takes a human to pick up their phone and type the code.
+    qrTimeout: 120_000,
+    // OpenClaw's production timings: the Baileys 20s connect timeout
+    // is tight on a loaded box, and a slightly faster keepalive spots
+    // a dead transport sooner.
+    connectTimeoutMs: 60_000,
+    keepAliveIntervalMs: 25_000,
+  });
+  runtime.sock = socket;
+  socket.ev.on("creds.update", saveCreds);
+  bindInbound(runtime, socket);
+
+  return new Promise((resolve) => {
+    socket.ev.on("connection.update", (update) => {
+      const { connection, lastDisconnect, qr } = update;
+      if (qr && !state.creds.registered) onQr(runtime, qr);
+      if (connection === "open") onOpen(runtime, socket);
+      if (connection === "close") {
+        const code = (
+          lastDisconnect?.error as
+            { output?: { statusCode?: number } } | undefined
+        )?.output?.statusCode;
+        resolve(onClose(runtime, state, code));
+      }
+    });
+  });
+}
+
+/**
+ * Wait until a manual pairing completes (event from pairing-lock) or
+ * registered creds appear on disk, polling slowly. Resolves promptly
+ * when the frontend is stopping.
+ */
+async function parkUntilPaired(runtime: WhatsAppRuntime): Promise<void> {
+  while (!runtime.stopping) {
+    if (!isManualPairingActive()) {
+      try {
+        const raw = await readFile(
+          resolvePath(dirs.whatsappAuth, "creds.json"),
+          "utf-8",
+        );
+        // Same trap as above: waiting on `registered` alone means a QR
+        // re-link can never end the park, because that flag stays false.
+        if (
+          isPaired(
+            JSON.parse(raw) as {
+              registered?: boolean;
+              me?: { id?: string } | null;
+            },
+          )
+        )
+          return;
+      } catch {
+        /* no creds yet — stay parked */
+      }
+    }
+    const paired = await new Promise<boolean>((r) => {
+      const off = onPairingComplete(() => {
+        clearTimeout(timer);
+        off();
+        r(true);
+      });
+      const timer = setTimeout(() => {
+        off();
+        r(false);
+      }, 30_000);
+      timer.unref?.();
+    });
+    if (paired) return;
+  }
+}
+
+/** The frontend's whole `start()`: connect, reconnect, park, until stopped. */
+export async function runConnectionLoop(
+  runtime: WhatsAppRuntime,
+): Promise<void> {
+  log("whatsapp", "WhatsApp frontend starting (Baileys multi-device)");
+  while (!runtime.stopping) {
+    // A manual pairing attempt owns the auth dir: two sockets on one
+    // keypair corrupt it and burn rate-limited pairing attempts.
+    if (isManualPairingActive()) {
+      await new Promise((r) => setTimeout(r, 5_000));
+      continue;
+    }
+    let outcome: ConnectOutcome;
+    try {
+      outcome = await connectOnce(runtime);
+    } catch (err) {
+      logError(
+        "whatsapp",
+        `Socket error: ${err instanceof Error ? err.message : err}`,
+      );
+      outcome = "reconnect";
+    }
+    runtime.sock = null;
+    if (outcome === "stop" || runtime.stopping) break;
+    if (outcome === "logged-out") {
+      // These credentials are dead — WhatsApp unlinked the device.
+      // Wipe them and PARK. Re-pairing needs a human holding the
+      // phone, so it happens strictly on demand (Telegram's
+      // `/whatsapp pair`) — every automatic retry policy tried here,
+      // including a 30-minute backoff ladder, still burned codes
+      // against WhatsApp's rate limit until scans failed with
+      // "couldn't connect device" for everyone.
+      logWarn(
+        "whatsapp",
+        "Logged out by WhatsApp — parked until /whatsapp pair re-links",
+      );
+      void notifyAdmin(
+        "⚠️ WhatsApp unlinked this device. When you're ready to " +
+          "re-link, send /whatsapp pair and scan the QR I reply with. " +
+          "Nothing is retried until then.",
+      );
+      rmSync(dirs.whatsappAuth, { recursive: true, force: true });
+      await parkUntilPaired(runtime);
+      runtime.reconnectDelay = RECONNECT_BASE_MS;
+      continue;
+    }
+    if (outcome === "unpaired") {
+      log("whatsapp", "Not paired — parked until /whatsapp pair links");
+      await parkUntilPaired(runtime);
+      runtime.reconnectDelay = RECONNECT_BASE_MS;
+      continue;
+    }
+    await new Promise((r) => setTimeout(r, runtime.reconnectDelay));
+    runtime.reconnectDelay = Math.min(
+      runtime.reconnectDelay * 2,
+      RECONNECT_MAX_MS,
+    );
+  }
+  log("whatsapp", "WhatsApp connection loop ended");
+}

package/src/frontend/whatsapp/inbound.ts

@@ -0,0 +1,327 @@
+/**
+ * One inbound message, from `messages.upsert` to the model's turn:
+ * access gates → media saved to the workspace → history recorded →
+ * slash commands → catch-up policy → `execute()`.
+ */
+
+import { isJidGroup, type WAMessage } from "baileys";
+import type { AgentEvent } from "../../core/agent-runtime/events.js";
+import { log, logError } from "../../util/log.js";
+import { execute } from "../../core/engine/dispatcher.js";
+import { toolInputToRecord } from "../../core/agent-runtime/events.js";
+import { resolveChatBackend } from "../../core/engine/backend-controller/index.js";
+import { performSessionReset } from "../shared/session-status.js";
+import { appendDailyLog } from "../../storage/daily-log.js";
+import { pushMessage } from "../../storage/history.js";
+import {
+  recordMessageProcessed,
+  recordMessageReceived,
+} from "../../util/watchdog.js";
+import { isAddressedToSelf, isGroupAllowed } from "./access.js";
+import { sendText } from "./actions/shared.js";
+import {
+  bareId,
+  canonicalId,
+  identityAllowed,
+  resolveIdentity,
+  type Identity,
+} from "./identity.js";
+import { saveInboundMedia, type SavedMedia } from "./media-store.js";
+import { lookupByWaId, rememberMessage } from "./message-store.js";
+import { registerWhatsAppChat, type WhatsAppChatInfo } from "./registry.js";
+import type { WhatsAppRuntime } from "./runtime.js";
+import { runTurnWithRecovery, shouldReplyToCatchUp } from "./turn-recovery.js";
+
+export type InboundOptions = { catchUp?: boolean };
+
+/** A message that passed the access gates. */
+type AdmittedMessage = {
+  jid: string;
+  isGroup: boolean;
+  identity: Identity;
+};
+
+/** An admitted message with something to say, recorded in history. */
+type RecordedMessage = AdmittedMessage & {
+  chat: WhatsAppChatInfo;
+  msgId: number;
+  text: string;
+  media: SavedMedia | undefined;
+  senderName: string;
+  platformTs: number;
+};
+
+/** Plain text of an inbound message, across the wrappers WhatsApp uses. */
+function extractText(msg: WAMessage): string {
+  const m = msg.message;
+  if (!m) return "";
+  return (
+    m.conversation ??
+    m.extendedTextMessage?.text ??
+    m.imageMessage?.caption ??
+    m.videoMessage?.caption ??
+    m.documentMessage?.caption ??
+    m.documentWithCaptionMessage?.message?.documentMessage?.caption ??
+    ""
+  );
+}
+
+async function admitInbound(
+  runtime: WhatsAppRuntime,
+  msg: WAMessage,
+): Promise<AdmittedMessage | null> {
+  const jid = msg.key.remoteJid;
+  // `fromMe` covers our own sends echoing back; status@broadcast is the
+  // Stories feed, which is not a conversation.
+  if (!jid || jid === "status@broadcast" || msg.key.fromMe) return null;
+
+  const isGroup = Boolean(isJidGroup(jid));
+  // The sender may be addressed by phone number or by LID depending on
+  // their privacy settings; resolve both before matching an allowlist
+  // that is written in phone numbers.
+  const senderJid = msg.key.participant || jid;
+  const identity = await resolveIdentity(
+    runtime.sock,
+    senderJid,
+    msg.key.participantAlt ?? msg.key.remoteJidAlt,
+  );
+
+  // ── Access gates: the allowlists are the entire permission model ──
+  if (isGroup) {
+    if (!(await isGroupAllowed(runtime, jid))) return null;
+    if (
+      runtime.settings.respondMode === "mention" &&
+      !isAddressedToSelf(runtime.selfIds, msg)
+    )
+      return null;
+  } else if (!identityAllowed(identity, runtime.allowedDms)) {
+    log(
+      "whatsapp",
+      `Ignoring DM from unlisted ${identity.ids.join("/") || bareId(jid)}`,
+    );
+    return null;
+  }
+  return { jid, isGroup, identity };
+}
+
+async function recordInbound(
+  runtime: WhatsAppRuntime,
+  msg: WAMessage,
+  admitted: AdmittedMessage,
+): Promise<RecordedMessage | null> {
+  const { jid, isGroup, identity } = admitted;
+  const text = extractText(msg).trim();
+  // Group chats key on the group JID; DMs key on the person, so the
+  // thread survives WhatsApp switching addressing form.
+  const chat = registerWhatsAppChat(
+    jid,
+    undefined,
+    isGroup ? undefined : canonicalId(identity),
+  );
+  const senderName = msg.pushName || canonicalId(identity) || "user";
+  const msgId = rememberMessage({
+    key: msg.key,
+    chatId: chat.chatId,
+    message: msg,
+    text,
+    senderName,
+  });
+
+  // Media is saved before the turn so the model can open the file by
+  // path in the same turn it's told about it.
+  const media = await saveInboundMedia(msg, chat.chatId, msgId, senderName);
+  if (!text && !media) return null; // reaction, receipt, or an unsupported type
+
+  recordMessageReceived();
+  if (runtime.settings.sendReadReceipts) {
+    runtime.sock?.readMessages([msg.key]).catch(() => {});
+  }
+
+  // Recorded for read_chat_history / search_chat_history, which the core
+  // serves from this store for frontends without a platform history API.
+  const replyToWaId =
+    msg.message?.extendedTextMessage?.contextInfo?.stanzaId ?? undefined;
+  const replyTo = replyToWaId ? lookupByWaId(replyToWaId) : undefined;
+  const platformTs = Number(msg.messageTimestamp) * 1000;
+  pushMessage(chat.chatId, {
+    msgId,
+    senderId: Number(BigInt(canonicalId(identity) ?? "0") % 2147483647n),
+    senderName,
+    senderHandle: canonicalId(identity),
+    text,
+    // The platform timestamp, so a catch-up message recorded late still
+    // reads in true order; Date.now() only when Baileys omits it.
+    timestamp:
+      Number.isFinite(platformTs) && platformTs > 0 ? platformTs : Date.now(),
+    ...(replyTo ? { replyToMsgId: replyTo.msgId } : {}),
+    ...(media ? { mediaType: media.type, filePath: media.filePath } : {}),
+  });
+  return { ...admitted, chat, msgId, text, media, senderName, platformTs };
+}
+
+/** `/reset` and `/help`. True when the message was a command. */
+async function handleSlashCommand(
+  runtime: WhatsAppRuntime,
+  inbound: RecordedMessage,
+): Promise<boolean> {
+  const { chat, senderName } = inbound;
+  const { gateway } = runtime;
+  const trimmed = inbound.text.toLowerCase();
+  if (trimmed === "/reset") {
+    await performSessionReset(
+      chat.chatId,
+      resolveChatBackend(chat.chatId, gateway.backend),
+      // The local history store is WhatsApp's only chat record — a
+      // reset clears the model's session, not the conversation log.
+      { keepHistory: true },
+    );
+    log("whatsapp", `Session reset by ${senderName}`);
+    const sock = runtime.sock;
+    if (sock) {
+      await sendText({ sock, gateway }, chat, "Session cleared.").catch(
+        () => {},
+      );
+    }
+    recordMessageProcessed();
+    return true;
+  }
+  if (trimmed === "/help") {
+    const sock = runtime.sock;
+    if (sock) {
+      await sendText(
+        { sock, gateway },
+        chat,
+        "*Commands*\n/reset — start a fresh session (chat log kept)\n/help — this message",
+      ).catch(() => {});
+    }
+    recordMessageProcessed();
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Catch-up messages (queued while the daemon was down) get a reply
+ * turn only while fresh; stale ones are already recorded and the next
+ * live turn reads them from history.
+ */
+function catchUpDeservesReply(inbound: RecordedMessage): boolean {
+  const { chat, senderName } = inbound;
+  if (!shouldReplyToCatchUp(inbound.platformTs)) {
+    log(
+      "whatsapp",
+      `[${chat.chatId}] Recorded offline message from ${senderName} (history only — too old for a reply turn)`,
+    );
+    recordMessageProcessed();
+    return false;
+  }
+  log(
+    "whatsapp",
+    `[${chat.chatId}] Catch-up: replying to offline message from ${senderName}`,
+  );
+  return true;
+}
+
+async function onTurnEvent(
+  runtime: WhatsAppRuntime,
+  chat: WhatsAppChatInfo,
+  event: AgentEvent,
+): Promise<void> {
+  switch (event.type) {
+    case "tool_call": {
+      const input = toolInputToRecord(event.name, event.input);
+      const detail = (input.description ??
+        input.command ??
+        input.action ??
+        input.query ??
+        "") as string;
+      log(
+        "whatsapp",
+        `  tool: ${event.name}${detail ? ` — ${String(detail).slice(0, 100)}` : ""}`,
+      );
+      break;
+    }
+    // Progress prose and the end-of-turn trailing-text fallback.
+    // Without this, prose-only turns are silently dropped.
+    case "assistant_message": {
+      const sock = runtime.sock;
+      if (!event.text.trim() || !sock) break;
+      try {
+        await sendText({ sock, gateway: runtime.gateway }, chat, event.text);
+      } catch (err) {
+        logError(
+          "whatsapp",
+          `onEvent delivery failed: ${err instanceof Error ? err.message : err}`,
+        );
+      }
+      break;
+    }
+  }
+}
+
+async function runInboundTurn(
+  runtime: WhatsAppRuntime,
+  inbound: RecordedMessage,
+): Promise<void> {
+  const { chat, text, media, msgId, senderName, identity, isGroup, jid } =
+    inbound;
+  const preview = text || `(${media?.type ?? "media"})`;
+  log(
+    "whatsapp",
+    `[${chat.chatId}] [${senderName}]: ${preview.slice(0, 80)}${preview.length > 80 ? "..." : ""}`,
+  );
+  appendDailyLog(senderName, preview, {
+    chatTitle: chat.title,
+    username: canonicalId(identity) ?? bareId(jid),
+  });
+
+  // The model addresses messages by numeric id (react/reply/edit), so the
+  // id travels with the text the same way the other frontends do it.
+  const mediaNote = media
+    ? `\n[attached ${media.type}: ${media.filePath}]`
+    : "";
+  const prompt = `[${senderName}] msg_id:${msgId}: ${text}${mediaNote}`;
+
+  const runTurn = () =>
+    execute({
+      chatId: chat.chatId,
+      numericChatId: chat.numericChatId,
+      prompt,
+      senderName,
+      isGroup,
+      source: "message",
+      onEvent: (event) => onTurnEvent(runtime, chat, event),
+    });
+
+  await runTurnWithRecovery({
+    chatId: chat.chatId,
+    senderName,
+    runTurn,
+    sendErrorText: async (text) => {
+      const sock = runtime.sock;
+      if (!sock) return;
+      try {
+        await sendText({ sock, gateway: runtime.gateway }, chat, text);
+      } catch (sendErr) {
+        logError(
+          "whatsapp",
+          `error delivery failed: ${sendErr instanceof Error ? sendErr.message : sendErr}`,
+        );
+      }
+    },
+  });
+}
+
+export async function handleInbound(
+  runtime: WhatsAppRuntime,
+  msg: WAMessage,
+  options: InboundOptions = {},
+): Promise<void> {
+  const admitted = await admitInbound(runtime, msg);
+  if (!admitted) return;
+  const inbound = await recordInbound(runtime, msg, admitted);
+  if (!inbound) return;
+  if (await handleSlashCommand(runtime, inbound)) return;
+  if (options.catchUp && !catchUpDeservesReply(inbound)) return;
+  await runInboundTurn(runtime, inbound);
+}