talon-agent 3.24.1 → 3.25.1

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

@@ -0,0 +1,231 @@
+/**
+ * Group administration — the `moderate` tool's op switch.
+ *
+ * WhatsApp's admin model is narrower than Telegram's: there is no ban
+ * list (removal is the only eviction), no per-member mute (a group is
+ * either open or admins-only), and no forum topics. Ops that have a
+ * faithful WhatsApp equivalent are mapped to it; the rest report what
+ * WhatsApp actually offers instead, so the model can pick another route
+ * rather than retrying something the platform cannot do.
+ */
+
+import { toUserJid, tryAction } from "./shared.js";
+import type { WhatsAppActionHandlers } from "./types.js";
+
+/** Ops that act on one member. */
+const PARTICIPANT_OPS: Record<string, "remove" | "add" | "promote" | "demote"> =
+  {
+    ban: "remove",
+    kick: "remove",
+    remove: "remove",
+    unban: "add",
+    add: "add",
+    promote: "promote",
+    demote: "demote",
+  };
+
+export const moderationHandlers: WhatsAppActionHandlers = {
+  moderate: (body, _chatId, ctx) =>
+    tryAction("moderate", async () => {
+      const op = String(body.op ?? "");
+      const chat = ctx.chat!;
+      const { sock } = ctx;
+
+      const participantOp = PARTICIPANT_OPS[op];
+      if (participantOp) {
+        if (!chat.isGroup) {
+          return { ok: false, error: `moderate(${op}) only applies to groups` };
+        }
+        const jid = toUserJid(body.user_id);
+        if (!jid) {
+          return { ok: false, error: `moderate(${op}) requires user_id` };
+        }
+        const [result] = await sock.groupParticipantsUpdate(
+          chat.jid,
+          [jid],
+          participantOp,
+        );
+        // Baileys reports per-participant status codes rather than throwing:
+        // 403 is "privacy settings blocked the add", 408 "not on WhatsApp".
+        const status = String(result?.status ?? "200");
+        if (status !== "200") {
+          return {
+            ok: false,
+            error: `WhatsApp refused ${op} for ${jid} (status ${status})`,
+          };
+        }
+        return {
+          ok: true,
+          text:
+            op === "ban"
+              ? `Removed ${jid} — WhatsApp has no ban list, so they can rejoin via an invite.`
+              : `${op} applied to ${jid}`,
+        };
+      }
+
+      switch (op) {
+        case "mute":
+        case "set_permissions": {
+          if (!chat.isGroup) {
+            return {
+              ok: false,
+              error: `moderate(${op}) only applies to groups`,
+            };
+          }
+          if (body.user_id) {
+            return {
+              ok: false,
+              error:
+                "WhatsApp has no per-member mute — mute the whole group " +
+                "(admins-only mode) or remove the member.",
+            };
+          }
+          // Announcement mode is WhatsApp's whole-group mute.
+          const permissions = (body.permissions ?? {}) as {
+            send_messages?: boolean;
+          };
+          const open =
+            op === "mute" ? false : permissions.send_messages !== false;
+          await sock.groupSettingUpdate(
+            chat.jid,
+            open ? "not_announcement" : "announcement",
+          );
+          return {
+            ok: true,
+            text: open
+              ? "All members can send messages."
+              : "Only admins can send messages.",
+          };
+        }
+
+        case "unmute": {
+          if (!chat.isGroup) {
+            return {
+              ok: false,
+              error: "moderate(unmute) only applies to groups",
+            };
+          }
+          await sock.groupSettingUpdate(chat.jid, "not_announcement");
+          return { ok: true, text: "All members can send messages." };
+        }
+
+        case "create_invite_link": {
+          if (!chat.isGroup) {
+            return { ok: false, error: "Only groups have invite links" };
+          }
+          const code = await sock.groupInviteCode(chat.jid);
+          return { ok: true, text: `https://chat.whatsapp.com/${code}` };
+        }
+
+        case "revoke_invite_link": {
+          if (!chat.isGroup) {
+            return { ok: false, error: "Only groups have invite links" };
+          }
+          const code = await sock.groupRevokeInvite(chat.jid);
+          return {
+            ok: true,
+            text: `Old link revoked. New link: https://chat.whatsapp.com/${code}`,
+          };
+        }
+
+        case "list_join_requests": {
+          if (!chat.isGroup) {
+            return { ok: false, error: "Only groups have join requests" };
+          }
+          const requests = await sock.groupRequestParticipantsList(chat.jid);
+          return {
+            ok: true,
+            text: requests.length
+              ? requests
+                  .map(
+                    (r) =>
+                      `${String(r.jid).split("@")[0]} (${r.request_method ?? "?"})`,
+                  )
+                  .join("\n")
+              : "No pending join requests.",
+          };
+        }
+
+        case "approve_join_request":
+        case "decline_join_request": {
+          if (!chat.isGroup) {
+            return { ok: false, error: "Only groups have join requests" };
+          }
+          const jid = toUserJid(body.user_id);
+          if (!jid) {
+            return { ok: false, error: `moderate(${op}) requires user_id` };
+          }
+          await sock.groupRequestParticipantsUpdate(
+            chat.jid,
+            [jid],
+            op === "approve_join_request" ? "approve" : "reject",
+          );
+          return { ok: true };
+        }
+
+        case "set_chat_photo": {
+          const source = body.file_path ?? body.url;
+          if (!source) {
+            return {
+              ok: false,
+              error: "moderate(set_chat_photo) requires file_path or url",
+            };
+          }
+          await sock.updateProfilePicture(chat.jid, { url: String(source) });
+          return { ok: true };
+        }
+
+        case "delete_chat_photo":
+          await sock.removeProfilePicture(chat.jid);
+          return { ok: true };
+
+        case "leave_chat": {
+          if (!chat.isGroup) {
+            return {
+              ok: false,
+              error:
+                "Cannot leave a direct message — block the contact instead",
+            };
+          }
+          await sock.groupLeave(chat.jid);
+          return { ok: true };
+        }
+
+        case "unpin_all": {
+          // WhatsApp unpins individually; clear the ones Talon placed.
+          const { listPins } = await import("../pins.js");
+          const pins = listPins(chat.chatId);
+          return {
+            ok: true,
+            text:
+              pins.length === 0
+                ? "No Talon-placed pins to clear."
+                : `WhatsApp unpins one message at a time — call unpin_message for: ${pins
+                    .map((p) => p.msgId)
+                    .join(", ")}`,
+          };
+        }
+
+        case "set_admin_title":
+          return {
+            ok: false,
+            error: "WhatsApp has no custom admin titles",
+          };
+
+        case "create_topic":
+        case "edit_topic":
+        case "close_topic":
+        case "reopen_topic":
+        case "delete_topic":
+          return {
+            ok: false,
+            error:
+              "WhatsApp groups have no topics — use separate groups, or a " +
+              "community with sub-groups (not manageable from this account).",
+          };
+
+        default:
+          return { ok: false, error: `Unknown moderate op: ${op}` };
+      }
+    }),
+};

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

@@ -0,0 +1,196 @@
+/**
+ * Shared helpers for the WhatsApp action handlers: uniform error
+ * capture, media-source resolution, quoted-reply resolution, and the
+ * JID coercion the member-facing actions need.
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { basename, extname } from "node:path";
+import type { AnyMessageContent, WAMessage, WASocket } from "baileys";
+import { expandFsPath } from "../../../util/fs-path.js";
+import { log, logError } from "../../../util/log.js";
+import type { ActionResult } from "../../../core/types.js";
+import { toWhatsAppChunks } from "../formatting.js";
+import { lookupMessage, rememberMessage } from "../message-store.js";
+import type { WhatsAppChatInfo } from "../registry.js";
+
+/** WhatsApp's own ceiling for a media upload. */
+const MAX_MEDIA_BYTES = 64 * 1024 * 1024;
+
+/**
+ * Run an action, converting a throw into a structured failure. WhatsApp
+ * errors arrive as Boom objects whose message is the useful part; the
+ * model gets that text so it can adapt rather than retry blindly.
+ */
+export async function tryAction(
+  label: string,
+  fn: () => Promise<ActionResult>,
+): Promise<ActionResult> {
+  try {
+    return await fn();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logError("whatsapp", `${label} failed: ${msg}`);
+    return { ok: false, error: `${label}: ${msg}` };
+  }
+}
+
+/** Baileys accepts a Buffer, a stream, or `{ url }` for local paths and HTTP. */
+export type MediaUpload = { url: string };
+
+/**
+ * Resolve one media input to something Baileys can upload. Two sources:
+ * a public URL (WhatsApp's uploader fetches it) or a workspace file path
+ * (streamed from disk). `file_id` is a Telegram concept with no WhatsApp
+ * equivalent — say so instead of failing obscurely.
+ */
+export function resolveMediaUpload(
+  src: { file_path?: unknown; url?: unknown; file_id?: unknown },
+  label: string,
+): { media: MediaUpload; fileName: string } | { error: string } {
+  if (src.url) {
+    const url = String(src.url);
+    return {
+      media: { url },
+      fileName: basename(new URL(url).pathname) || "file",
+    };
+  }
+  if (src.file_id) {
+    return {
+      error:
+        `${label}: WhatsApp has no file_id — re-send by url (public) or ` +
+        `file_path (workspace file)`,
+    };
+  }
+  if (!src.file_path) {
+    return {
+      error: `${label}: provide file_path (workspace file) or url (public)`,
+    };
+  }
+  const filePath = expandFsPath(String(src.file_path));
+  if (!existsSync(filePath)) {
+    return {
+      error: `File not found: ${filePath} — check the workspace path, or send by url instead`,
+    };
+  }
+  if (statSync(filePath).size > MAX_MEDIA_BYTES) {
+    return { error: `${label}: file exceeds WhatsApp's 64MB limit` };
+  }
+  return { media: { url: filePath }, fileName: basename(filePath) };
+}
+
+/** Extension → mimetype for the document/audio paths that require one. */
+const MIME_BY_EXT: Record<string, string> = {
+  ".pdf": "application/pdf",
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".json": "application/json",
+  ".csv": "text/csv",
+  ".zip": "application/zip",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".mp4": "video/mp4",
+  ".mov": "video/quicktime",
+  ".mp3": "audio/mpeg",
+  ".m4a": "audio/mp4",
+  ".ogg": "audio/ogg",
+  ".opus": "audio/ogg; codecs=opus",
+  ".wav": "audio/wav",
+};
+
+export function guessMimetype(fileName: string, fallback: string): string {
+  return MIME_BY_EXT[extname(fileName).toLowerCase()] ?? fallback;
+}
+
+/**
+ * Resolve a `reply_to` message id into the quoted message Baileys wants.
+ * An unknown id quotes nothing rather than failing the send — the reply
+ * link is a nicety, the message itself is the point.
+ */
+export function resolveQuoted(
+  body: Record<string, unknown>,
+  chatId: string,
+): WAMessage | undefined {
+  const raw = body.reply_to ?? body.reply_to_message_id;
+  if (raw === undefined || raw === null) return undefined;
+  const msgId = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(msgId)) return undefined;
+  const stored = lookupMessage(msgId);
+  if (!stored || stored.chatId !== chatId) return undefined;
+  return (
+    stored.message ?? {
+      key: stored.key,
+      message: { conversation: stored.text },
+    }
+  );
+}
+
+/**
+ * Send one content payload, remember the resulting message so later
+ * tool calls can address it, and report its Talon numeric id.
+ */
+export async function sendContent(
+  ctx: { sock: WASocket; gateway: { incrementMessages: (id: number) => void } },
+  chat: WhatsAppChatInfo,
+  content: AnyMessageContent,
+  options: { quoted?: WAMessage } = {},
+): Promise<ActionResult> {
+  const sent = await ctx.sock.sendMessage(chat.jid, content, options);
+  ctx.gateway.incrementMessages(chat.numericChatId);
+  if (!sent?.key) return { ok: true };
+  const msgId = rememberMessage({
+    key: sent.key,
+    chatId: chat.chatId,
+    message: sent,
+    text: "text" in content ? String(content.text ?? "") : "",
+    senderName: "bot",
+  });
+  return { ok: true, message_id: msgId };
+}
+
+/**
+ * Send text, split across bubbles when it exceeds WhatsApp's limit. The
+ * reported message id is the FIRST chunk's: it is the one a reply or
+ * reaction should attach to, and the one Talon's callers treat as "the"
+ * message.
+ */
+export async function sendText(
+  ctx: { sock: WASocket; gateway: { incrementMessages: (id: number) => void } },
+  chat: WhatsAppChatInfo,
+  text: string,
+  quoted?: WAMessage,
+): Promise<ActionResult> {
+  const chunks = toWhatsAppChunks(text);
+  let first: ActionResult | undefined;
+  for (const [index, chunk] of chunks.entries()) {
+    const result = await sendContent(
+      ctx,
+      chat,
+      { text: chunk },
+      // Only the first chunk quotes — a quoted block on every bubble of a
+      // long answer is noise.
+      index === 0 && quoted ? { quoted } : {},
+    );
+    first ??= result;
+  }
+  log(
+    "whatsapp",
+    `Sent ${chunks.length} chunk(s) to ${chat.chatId} (${text.length} chars)`,
+  );
+  return first ?? { ok: true };
+}
+
+/**
+ * Coerce a user reference the model supplied — bare number, JID, or the
+ * numeric id from a member listing — into a WhatsApp user JID.
+ */
+export function toUserJid(value: unknown): string | null {
+  const raw = String(value ?? "").trim();
+  if (!raw) return null;
+  if (raw.includes("@")) return raw;
+  const digits = raw.replace(/[^0-9]/g, "");
+  return digits ? `${digits}@s.whatsapp.net` : null;
+}

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);
+}