talon-agent 3.24.0 → 3.25.0

package/src/frontend/whatsapp/message-store.ts

@@ -0,0 +1,140 @@
+/**
+ * Message-key store — the bridge between Talon's numeric message ids and
+ * WhatsApp's opaque string ones.
+ *
+ * Every Talon messaging tool addresses a message by number (`react`,
+ * `edit_message`, `delete_message`, `reply_to`, …), but WhatsApp ids look
+ * like `3EB0C767D26B8F3A1B2C` and the operations that act on a message
+ * need a whole `WAMessageKey` (id + remoteJid + fromMe + participant),
+ * not just the id. So each message Talon sees — inbound or sent — is
+ * assigned a monotonic numeric id here and remembered alongside its key.
+ *
+ * `forward_message` needs the full message, not only its key, so the
+ * proto is retained too. The map is bounded and evicts oldest-first: a
+ * long-running daemon must not accumulate every message it ever saw, and
+ * a model addressing a message thousands of turns back is not a case
+ * worth holding memory for.
+ */
+
+import type { WAMessage, WAMessageKey } from "baileys";
+
+export type StoredMessage = {
+  /** Talon-facing numeric id. */
+  msgId: number;
+  /** What WhatsApp needs to act on the message. */
+  key: WAMessageKey;
+  /** Talon chat id (wa_dm_… / wa_group_…). */
+  chatId: string;
+  /** Retained for forward_message, which re-sends the whole message. */
+  message?: WAMessage;
+  /** Plain text at the time it was stored (copy_message, previews). */
+  text: string;
+  senderName: string;
+  timestamp: number;
+};
+
+/**
+ * Ids start high so they can't be confused with a small ordinal the model
+ * might invent, and stay well inside 2^53.
+ */
+const ID_BASE = 1_000_000;
+const MAX_TRACKED = 2_000;
+
+let nextId = ID_BASE;
+const byMsgId = new Map<number, StoredMessage>();
+const byWaId = new Map<string, number>();
+
+function evictOldest(): void {
+  while (byMsgId.size > MAX_TRACKED) {
+    // Map iteration is insertion-ordered, so the first key is the oldest.
+    const oldest = byMsgId.keys().next();
+    if (oldest.done) return;
+    const stored = byMsgId.get(oldest.value);
+    byMsgId.delete(oldest.value);
+    if (stored?.key.id) byWaId.delete(stored.key.id);
+  }
+}
+
+/**
+ * Record a message and return its Talon numeric id. Re-recording a
+ * WhatsApp id already seen returns the original number, so the same
+ * message never gets two identities (Baileys can re-deliver on reconnect).
+ */
+export function rememberMessage(entry: {
+  key: WAMessageKey;
+  chatId: string;
+  message?: WAMessage;
+  text?: string;
+  senderName?: string;
+  timestamp?: number;
+}): number {
+  const waId = entry.key.id;
+  if (waId) {
+    const existing = byWaId.get(waId);
+    if (existing !== undefined) return existing;
+  }
+  const msgId = nextId++;
+  const stored: StoredMessage = {
+    msgId,
+    key: entry.key,
+    chatId: entry.chatId,
+    text: entry.text ?? "",
+    senderName: entry.senderName ?? "",
+    timestamp: entry.timestamp ?? Date.now(),
+    ...(entry.message ? { message: entry.message } : {}),
+  };
+  byMsgId.set(msgId, stored);
+  if (waId) byWaId.set(waId, msgId);
+  evictOldest();
+  return msgId;
+}
+
+/** Look up a stored message by its Talon numeric id. */
+export function lookupMessage(msgId: number): StoredMessage | undefined {
+  return byMsgId.get(msgId);
+}
+
+/** Look up by WhatsApp's own id (reply resolution on inbound). */
+export function lookupByWaId(waId: string): StoredMessage | undefined {
+  const msgId = byWaId.get(waId);
+  return msgId === undefined ? undefined : byMsgId.get(msgId);
+}
+
+/**
+ * Resolve a tool-supplied message id (number or digit string) to the
+ * WhatsApp key it names, scoped to one chat so a stale id from another
+ * conversation can't act on this one.
+ */
+export function resolveKey(
+  value: unknown,
+  chatId: string,
+): { key: WAMessageKey; stored: StoredMessage } | { error: string } {
+  const msgId =
+    typeof value === "number"
+      ? value
+      : typeof value === "string"
+        ? Number(value)
+        : NaN;
+  if (!Number.isFinite(msgId)) {
+    return { error: `Invalid message_id: ${String(value)}` };
+  }
+  const stored = byMsgId.get(msgId);
+  if (!stored) {
+    return {
+      error:
+        `Unknown message_id ${msgId} — WhatsApp message ids are assigned ` +
+        `when Talon sees the message; only recent ones can be acted on.`,
+    };
+  }
+  if (stored.chatId !== chatId) {
+    return { error: `Message ${msgId} belongs to a different chat` };
+  }
+  return { key: stored.key, stored };
+}
+
+/** Test seam: drop every tracked message and restart the id counter. */
+export function resetMessageStore(): void {
+  byMsgId.clear();
+  byWaId.clear();
+  nextId = ID_BASE;
+}

package/src/frontend/whatsapp/pins.ts

@@ -0,0 +1,52 @@
+/**
+ * Pinned-message bookkeeping.
+ *
+ * WhatsApp lets a client pin a message but exposes no query for what is
+ * pinned in a chat, so `get_pinned_messages` would have nothing to answer
+ * with. This records the pins Talon itself places — the set the model put
+ * there and may want to revisit or clear — and is deliberately honest
+ * about its scope: pins made from someone's phone are invisible here.
+ */
+
+import type { StoredMessage } from "./message-store.js";
+
+export type PinnedMessage = {
+  msgId: number;
+  text: string;
+  senderName: string;
+  pinnedAt: number;
+};
+
+/** Per-chat pins, newest last. Bounded — WhatsApp shows few pins anyway. */
+const MAX_PINS_PER_CHAT = 25;
+const pinsByChat = new Map<string, PinnedMessage[]>();
+
+export function recordPin(chatId: string, message: StoredMessage): void {
+  const pins = pinsByChat.get(chatId) ?? [];
+  if (pins.some((pin) => pin.msgId === message.msgId)) return;
+  pins.push({
+    msgId: message.msgId,
+    text: message.text,
+    senderName: message.senderName,
+    pinnedAt: Date.now(),
+  });
+  while (pins.length > MAX_PINS_PER_CHAT) pins.shift();
+  pinsByChat.set(chatId, pins);
+}
+
+export function forgetPin(chatId: string, msgId: number): void {
+  const pins = pinsByChat.get(chatId);
+  if (!pins) return;
+  const remaining = pins.filter((pin) => pin.msgId !== msgId);
+  if (remaining.length) pinsByChat.set(chatId, remaining);
+  else pinsByChat.delete(chatId);
+}
+
+export function listPins(chatId: string): PinnedMessage[] {
+  return pinsByChat.get(chatId) ?? [];
+}
+
+/** Test seam: forget every recorded pin. */
+export function resetPins(): void {
+  pinsByChat.clear();
+}

package/src/frontend/whatsapp/registry.ts

@@ -0,0 +1,92 @@
+/**
+ * Chat-registry accessors — map between Talon chat ids (string and
+ * numeric) and the WhatsApp JID the socket needs to post back.
+ *
+ * Populated on first inbound message from a chat; consulted by the
+ * action handler (send_message routes by Talon chat id) and by the
+ * Frontend contract's numeric-keyed sendMessage/sendTyping (cron,
+ * pulse, heartbeat outbound).
+ */
+
+import { isJidGroup, jidNormalizedUser } from "baileys";
+import { deriveNumericChatId } from "../../util/chat-id.js";
+import { bareId } from "./identity.js";
+
+export type WhatsAppChatInfo = {
+  /** Talon chat id: wa_dm_<number> or wa_group_<id>. */
+  chatId: string;
+  /** Stable 32-bit hash of chatId (dispatcher/gateway key). */
+  numericChatId: number;
+  /** The JID the socket sends to: <number>@s.whatsapp.net or <id>@g.us. */
+  jid: string;
+  isGroup: boolean;
+  title?: string;
+};
+
+const byNumeric = new Map<number, WhatsAppChatInfo>();
+const byString = new Map<string, WhatsAppChatInfo>();
+
+/**
+ * Talon chat id for a WhatsApp JID.
+ *
+ * `canonical` is the identity's preferred id (phone number when known),
+ * so a DM keeps ONE chat id even when WhatsApp switches the conversation
+ * between phone-number and LID addressing mid-thread.
+ */
+export function chatIdForJid(jid: string, canonical?: string): string {
+  // `||`, not `??`: an empty canonical id must fall back to the JID
+  // rather than produce the id every DM would share.
+  const bare = canonical || bareId(jidNormalizedUser(jid)) || "unknown";
+  return isJidGroup(jid) ? `wa_group_${bare}` : `wa_dm_${bare}`;
+}
+
+/**
+ * Record (or refresh) a chat's identity, returning its info.
+ *
+ * The send target (`jid`) is always the address the message arrived on —
+ * that is what WhatsApp routes — while the chat id comes from the stable
+ * canonical identity. A chat already known under one addressing form has
+ * its send target refreshed rather than being duplicated.
+ */
+export function registerWhatsAppChat(
+  jid: string,
+  title?: string,
+  canonical?: string,
+): WhatsAppChatInfo {
+  const chatId = chatIdForJid(jid, canonical);
+  const sendJid = isJidGroup(jid) ? jid : jidNormalizedUser(jid);
+  const existing = byString.get(chatId);
+  if (existing) {
+    if (title) existing.title = title;
+    existing.jid = sendJid;
+    return existing;
+  }
+  const info: WhatsAppChatInfo = {
+    chatId,
+    numericChatId: deriveNumericChatId(chatId),
+    jid: sendJid,
+    isGroup: Boolean(isJidGroup(jid)),
+    ...(title ? { title } : {}),
+  };
+  byNumeric.set(info.numericChatId, info);
+  byString.set(info.chatId, info);
+  return info;
+}
+
+export function lookupWhatsAppChat(
+  numericChatId: number,
+): WhatsAppChatInfo | undefined {
+  return byNumeric.get(numericChatId);
+}
+
+export function lookupWhatsAppChatByString(
+  chatId: string,
+): WhatsAppChatInfo | undefined {
+  return byString.get(chatId);
+}
+
+/** Test seam: forget every registered chat. */
+export function resetWhatsAppRegistry(): void {
+  byNumeric.clear();
+  byString.clear();
+}

package/src/util/chat-id.ts

@@ -45,6 +45,11 @@ export function isTeamsChatId(chatId: string): boolean {
   return chatId.startsWith("teams_chat_");
 }
 
+/** Check if a chat ID belongs to a WhatsApp session. */
+export function isWhatsAppChatId(chatId: string): boolean {
+  return chatId.startsWith("wa_");
+}
+
 /** Check if a chat ID belongs to a Discord session. */
 export function isDiscordChatId(chatId: string): boolean {
   return chatId.startsWith("discord_");

package/src/util/config.ts

@@ -142,6 +142,7 @@ const frontendEnum = z.enum([
   "teams",
   "discord",
   "native",
+  "whatsapp",
 ]);
 
 /**
@@ -226,6 +227,41 @@ const discordConfigSchema = z
   })
   .strict();
 
+const whatsappConfigSchema = z
+  .object({
+    /**
+     * JIDs or bare phone numbers (digits only, country code included)
+     * allowed to DM the bot. Empty array disables DM access.
+     */
+    allowedJids: z.array(z.string()).default([]),
+    /** Group JIDs (…@g.us) the bot may always respond in. */
+    allowedGroups: z.array(z.string()).default([]),
+    /**
+     * Which groups the bot serves beyond `allowedGroups`:
+     *   - "listed"            only the groups named above (default)
+     *   - "with-allowed-user" any group containing someone from
+     *                         `allowedJids` — "the groups I'm in"
+     *   - "all"               every group the account belongs to
+     */
+    groupPolicy: z
+      .enum(["listed", "with-allowed-user", "all"])
+      .default("listed"),
+    /**
+     * In groups, when does the bot reply?
+     *   - "mention"  reply only when @mentioned or quoted (default)
+     *   - "all"      reply to every message in allowedGroups
+     */
+    respondMode: z.enum(["mention", "all"]).default("mention"),
+    /**
+     * Pair by phone-number code instead of QR: the account's number in
+     * E.164 digits without the plus (e.g. "353871234567"). Omit for QR.
+     */
+    pairingNumber: z.string().optional(),
+    /** Mark handled inbound messages as read (blue ticks). */
+    sendReadReceipts: z.boolean().default(true),
+  })
+  .strict();
+
 const playwrightConfigSchema = z.object({
   enabled: z.boolean().default(false),
   /** Browser engine: chromium (default), chrome, firefox, webkit, msedge */
@@ -502,6 +538,7 @@ const configSchema = z.object({
 
   // Discord — discord.js v14-based frontend
   discord: discordConfigSchema.optional(),
+  whatsapp: whatsappConfigSchema.optional(),
 
   // Native — local bridge for the Electron companion app (apps/desktop)
   native: nativeConfigSchema.optional(),
@@ -709,6 +746,12 @@ export function loadConfig(): TalonConfig {
         `Teams frontend requires "teamsWebhookUrl" in ${CONFIG_FILE}. Run "talon setup" to configure.`,
       );
     }
+    if (fe === "whatsapp" && !parsed.whatsapp) {
+      throw new Error(
+        `WhatsApp frontend requires a "whatsapp" config block in ${CONFIG_FILE} ` +
+          `(set allowedJids / allowedGroups; pairing happens interactively on first start).`,
+      );
+    }
   }
 
   const activeFrontend = frontends[0];

package/src/util/log.ts

@@ -52,6 +52,7 @@ export type LogComponent =
   | "plugin"
   | "teams"
   | "discord"
+  | "whatsapp"
   | "native"
   | "mesh"
   | "config"

package/src/util/paths.ts

@@ -56,6 +56,8 @@ export const dirs = {
   uploads: resolve(TALON_ROOT, "workspace", "uploads"),
   /** Daily logs: ~/.talon/workspace/logs/ */
   logs: resolve(TALON_ROOT, "workspace", "logs"),
+  /** Baileys multi-file auth state: ~/.talon/whatsapp-auth/ */
+  whatsappAuth: resolve(TALON_ROOT, "whatsapp-auth"),
   /** Memory: ~/.talon/workspace/memory/ */
   memory: resolve(TALON_ROOT, "workspace", "memory"),
   /** Daily memory notes: ~/.talon/workspace/memory/daily/ */