talon-agent 3.24.1 → 3.25.0

package/src/frontend/whatsapp/actions/types.ts

@@ -0,0 +1,34 @@
+/**
+ * WhatsApp action-handler types.
+ *
+ * Each domain module exports a `WhatsAppActionHandlers` map keyed by
+ * action name. Handlers receive the request body, the numeric chat id,
+ * and a shared context carrying the live socket, the gateway, the chat
+ * resolved from the id, and the per-handler scheduled-send timers.
+ *
+ * `chat` is non-null for every action the dispatcher routes here except
+ * the store-only scheduling ones, so handlers can use `ctx.chat!`.
+ */
+
+import type { WASocket } from "baileys";
+import type { Gateway } from "../../../core/engine/gateway.js";
+import type { ActionResult } from "../../../core/types.js";
+import type { WhatsAppChatInfo } from "../registry.js";
+
+export interface WhatsAppActionContext {
+  /** The connected socket. Reconnects replace it, so never capture it. */
+  sock: WASocket;
+  gateway: Gateway;
+  /** Chat resolved from the numeric id; null only for store-only actions. */
+  chat: WhatsAppChatInfo | null;
+  /** Active scheduled-message timers, keyed by schedule id. */
+  scheduledMessages: Map<string, ReturnType<typeof setTimeout>>;
+}
+
+export type WhatsAppActionHandler = (
+  body: Record<string, unknown>,
+  chatId: number,
+  ctx: WhatsAppActionContext,
+) => Promise<ActionResult | null> | ActionResult | null;
+
+export type WhatsAppActionHandlers = Record<string, WhatsAppActionHandler>;

package/src/frontend/whatsapp/factory.ts

@@ -0,0 +1,12 @@
+/**
+ * WhatsApp frontend factory — attaches the create half of the registry
+ * entry (descriptor registered in core/frontend-runtime). The
+ * implementation (Baileys socket) loads only when created.
+ */
+
+import { attachFrontendCreate } from "../../core/frontend-runtime/index.js";
+
+attachFrontendCreate("whatsapp", async (config, gateway) => {
+  const { createWhatsAppFrontend } = await import("./index.js");
+  return createWhatsAppFrontend(config, gateway);
+});

package/src/frontend/whatsapp/formatting.ts

@@ -0,0 +1,172 @@
+/**
+ * Markdown → WhatsApp text.
+ *
+ * The model writes standard Markdown; WhatsApp renders its own dialect
+ * (*bold*, _italic_, ~strike~, `code`, ```blocks```, "> " quotes, and
+ * "- "/"1. " lists). Translating between them by running regexes over the
+ * raw string is how you end up bolding the asterisks inside a code block
+ * or eating the underscores in a URL, so this walks marked's token tree
+ * instead: code spans and fenced blocks are separate token types by the
+ * time we see them, and emphasis is structural rather than textual.
+ *
+ * WhatsApp has no escape syntax, so literal delimiters in the source
+ * survive as themselves — there is nothing to escape into.
+ */
+
+import { marked, type Token, type Tokens } from "marked";
+import { splitMessage } from "../telegram/formatting.js";
+
+/** WhatsApp accepts far more, but long bubbles read badly on a phone. */
+export const WHATSAPP_MAX_TEXT = 4096;
+
+/** Rendered width of a table cell, for the monospace fallback. */
+const MAX_TABLE_CELL = 24;
+
+function renderInline(tokens: Token[] | undefined): string {
+  if (!tokens) return "";
+  return tokens.map(renderInlineToken).join("");
+}
+
+function renderInlineToken(token: Token): string {
+  switch (token.type) {
+    case "strong":
+      return `*${renderInline((token as Tokens.Strong).tokens)}*`;
+    case "em":
+      return `_${renderInline((token as Tokens.Em).tokens)}_`;
+    case "del":
+      return `~${renderInline((token as Tokens.Del).tokens)}~`;
+    case "codespan":
+      // WhatsApp renders single-backtick spans as inline monospace.
+      return `\`${(token as Tokens.Codespan).text}\``;
+    case "link": {
+      const link = token as Tokens.Link;
+      const label = renderInline(link.tokens);
+      // WhatsApp auto-links bare URLs but renders no anchor text, so a
+      // labelled link has to show both halves or the destination is lost.
+      return !label || label === link.href
+        ? link.href
+        : `${label} (${link.href})`;
+    }
+    case "image": {
+      const image = token as Tokens.Image;
+      return image.text ? `${image.text} (${image.href})` : image.href;
+    }
+    case "br":
+      return "\n";
+    case "escape":
+      return (token as Tokens.Escape).text;
+    case "html":
+      // Inline HTML has no WhatsApp equivalent — emit the source text.
+      return (token as Tokens.HTML).raw;
+    default:
+      return (token as { text?: string }).text ?? "";
+  }
+}
+
+function renderListItems(list: Tokens.List, depth: number): string {
+  const indent = "  ".repeat(depth);
+  return list.items
+    .map((item, index) => {
+      const marker = list.ordered ? `${Number(list.start || 1) + index}.` : "-";
+      // A task item's checkbox is structural in Markdown and cosmetic in
+      // WhatsApp; render it as a box so the state still reads.
+      const check = item.task ? (item.checked ? "[x] " : "[ ] ") : "";
+      const body = renderBlocks(item.tokens ?? [], depth + 1).trimEnd();
+      const [first = "", ...rest] = body.split("\n");
+      const head = `${indent}${marker} ${check}${first}`;
+      // Continuation lines of a wrapped item line up under its text.
+      const tail = rest.map((line) => `${indent}  ${line}`);
+      return [head, ...tail].join("\n");
+    })
+    .join("\n");
+}
+
+/**
+ * Tables have no WhatsApp equivalent. A monospace block keeps the columns
+ * aligned, which is the part that carries the meaning.
+ */
+function renderTable(table: Tokens.Table): string {
+  const clip = (s: string): string =>
+    s.length > MAX_TABLE_CELL ? `${s.slice(0, MAX_TABLE_CELL - 1)}…` : s;
+  const header = table.header.map((cell) => clip(renderInline(cell.tokens)));
+  const rows = table.rows.map((row) =>
+    row.map((cell) => clip(renderInline(cell.tokens))),
+  );
+  const widths = header.map((cell, i) =>
+    Math.max(cell.length, ...rows.map((row) => (row[i] ?? "").length)),
+  );
+  const line = (cells: string[]): string =>
+    cells
+      .map((cell, i) => cell.padEnd(widths[i] ?? 0))
+      .join("  ")
+      .trimEnd();
+  const separator = widths.map((width) => "─".repeat(width)).join("  ");
+  return ["```", line(header), separator, ...rows.map(line), "```"].join("\n");
+}
+
+function renderBlockToken(token: Token, depth: number): string {
+  switch (token.type) {
+    case "heading":
+      // WhatsApp has no headings; bold is the only emphasis that reads
+      // as a title in a chat bubble.
+      return `*${renderInline((token as Tokens.Heading).tokens)}*`;
+    case "paragraph":
+      return renderInline((token as Tokens.Paragraph).tokens);
+    case "text": {
+      const text = token as Tokens.Text;
+      return text.tokens ? renderInline(text.tokens) : text.text;
+    }
+    case "code": {
+      const code = token as Tokens.Code;
+      return `\`\`\`\n${code.text}\n\`\`\``;
+    }
+    case "blockquote": {
+      const quote = renderBlocks((token as Tokens.Blockquote).tokens, depth);
+      return quote
+        .split("\n")
+        .map((line) => `> ${line}`.trimEnd())
+        .join("\n");
+    }
+    case "list":
+      return renderListItems(token as Tokens.List, depth);
+    case "table":
+      return renderTable(token as Tokens.Table);
+    case "hr":
+      return "──────────";
+    case "html":
+      return (token as Tokens.HTML).raw.trim();
+    case "space":
+      return "";
+    default:
+      return (token as { text?: string }).text ?? "";
+  }
+}
+
+function renderBlocks(tokens: Token[], depth = 0): string {
+  const parts: string[] = [];
+  for (const token of tokens) {
+    const rendered = renderBlockToken(token, depth);
+    if (rendered !== "") parts.push(rendered);
+  }
+  // Inside a list item, blocks stack tightly; at top level they get the
+  // blank line that separates paragraphs in a bubble.
+  return parts.join(depth > 0 ? "\n" : "\n\n");
+}
+
+/**
+ * Translate Markdown into WhatsApp's formatting dialect. Falls back to
+ * the original text if the Markdown can't be parsed — an unformatted
+ * message beats a dropped one.
+ */
+export function toWhatsAppText(text: string): string {
+  try {
+    return renderBlocks(marked.lexer(text)).trim();
+  } catch {
+    return text;
+  }
+}
+
+/** Translate to the WhatsApp dialect, then split into sendable chunks. */
+export function toWhatsAppChunks(text: string): string[] {
+  return splitMessage(toWhatsAppText(text), WHATSAPP_MAX_TEXT);
+}

package/src/frontend/whatsapp/identity.ts

@@ -0,0 +1,150 @@
+/**
+ * Identity resolution — the LID/phone-number duality.
+ *
+ * WhatsApp addresses people two ways. The historical form is the phone
+ * number (`353834733284@s.whatsapp.net`, "PN"); the newer privacy form
+ * is a linked identity (`180753715482747@lid`, "LID") that hides the
+ * number. Which one arrives depends on the sender's privacy settings and
+ * the chat's addressing mode, and neither is derivable from the other —
+ * they are looked up.
+ *
+ * This matters because every allowlist a human writes is phone numbers.
+ * Matching those against a raw `remoteJid` silently ignores anyone whose
+ * messages arrive as a LID — which is exactly what happened on the first
+ * real message to the live account.
+ *
+ * So every identity resolves to BOTH forms and matches on either.
+ * Baileys carries the counterpart on the message key (`remoteJidAlt` /
+ * `participantAlt`) when it knows it, and its signal store can look one
+ * up otherwise; results are cached because the mapping is stable.
+ */
+
+import { isLidUser, jidNormalizedUser, type WASocket } from "baileys";
+
+export type Identity = {
+  /** Phone-number form, digits only, when known: "353834733284". */
+  phone?: string;
+  /** LID form, digits only, when known: "180753715482747". */
+  lid?: string;
+  /** Every bare id this person is known by — what allowlists match on. */
+  ids: string[];
+};
+
+/**
+ * Bare identity of a JID or phone string: strips server, device, and
+ * "+". Returns undefined for anything that leaves no digits — WhatsApp
+ * hands out empty `participant` fields on DMs, and an empty id that
+ * flows onward silently collapses every conversation into one.
+ */
+export function bareId(jidOrNumber: string | null | undefined): string {
+  return jidOrNumber?.split("@")[0].split(":")[0].replace(/^\+/, "") ?? "";
+}
+
+/** Bare id, or undefined when there is nothing usable to key on. */
+function usableId(jidOrNumber: string | null | undefined): string | undefined {
+  const bare = bareId(jidOrNumber).trim();
+  return bare.length > 0 ? bare : undefined;
+}
+
+/** LID ↔ PN is stable for the life of an account; cache both directions. */
+const cache = new Map<string, Identity>();
+
+function remember(identity: Identity): Identity {
+  // Nothing to key on means nothing worth caching — the next message
+  // gets a fresh attempt at resolving this person.
+  for (const id of identity.ids) cache.set(id, identity);
+  return identity;
+}
+
+type LidStore = {
+  getPNForLID(lid: string): Promise<string | null>;
+  getLIDForPN(pn: string): Promise<string | null>;
+};
+
+function lidStore(
+  sock: Pick<WASocket, "signalRepository"> | null,
+): LidStore | undefined {
+  return (
+    sock?.signalRepository as unknown as { lidMapping?: LidStore } | undefined
+  )?.lidMapping;
+}
+
+/**
+ * Resolve a user JID into every form they can be addressed by.
+ *
+ * `altJid` is Baileys' counterpart hint from the message key — free when
+ * present. Otherwise the signal store is asked, a local lookup that can
+ * still miss (the mapping is learned, not computed). A one-sided answer
+ * is returned rather than failing, so matching degrades to the form we
+ * do have instead of dropping the message.
+ */
+export async function resolveIdentity(
+  sock: Pick<WASocket, "signalRepository"> | null,
+  jid: string,
+  altJid?: string | null,
+): Promise<Identity> {
+  const bare = usableId(jid);
+  const cached = bare ? cache.get(bare) : undefined;
+  if (cached) return cached;
+
+  const isLid = Boolean(isLidUser(jid));
+  const identity: Identity = isLid
+    ? { lid: bare, ids: [] }
+    : { phone: bare, ids: [] };
+
+  const altBare = usableId(altJid);
+  if (altBare) {
+    if (isLid) identity.phone = altBare;
+    else identity.lid = altBare;
+  } else {
+    const store = lidStore(sock);
+    if (store) {
+      try {
+        const counterpart = isLid
+          ? await store.getPNForLID(jidNormalizedUser(jid))
+          : await store.getLIDForPN(jidNormalizedUser(jid));
+        const counterpartId = usableId(counterpart);
+        if (counterpartId) {
+          if (isLid) identity.phone = counterpartId;
+          else identity.lid = counterpartId;
+        }
+      } catch {
+        // A miss is normal before the mapping is learned — match on the
+        // form we have rather than failing the message.
+      }
+    }
+  }
+
+  identity.ids = [identity.phone, identity.lid].filter((id): id is string =>
+    Boolean(id),
+  );
+  return remember(identity);
+}
+
+/**
+ * True when an identity is on an allowlist of bare ids. Either form
+ * counts: the allowlist is written in phone numbers, the message may
+ * arrive as a LID, and both name the same person.
+ */
+export function identityAllowed(
+  identity: Identity,
+  allowed: ReadonlySet<string>,
+): boolean {
+  return identity.ids.some((id) => allowed.has(id));
+}
+
+/**
+ * The stable, human-meaningful id for a person: their phone number when
+ * known, else the LID. Chat ids are built from this so a conversation
+ * keeps one identity even as WhatsApp switches addressing form.
+ */
+export function canonicalId(identity: Identity): string | undefined {
+  // Deliberately not `??`: an empty string is "no id", not a value, and
+  // letting one through builds a chat id every DM would share.
+  return identity.phone || identity.lid || undefined;
+}
+
+/** Test seam: forget every resolved identity. */
+export function resetIdentityCache(): void {
+  cache.clear();
+}