talon-agent 3.24.0 → 3.25.0

package/src/frontend/whatsapp/actions/chat-info.ts

@@ -0,0 +1,228 @@
+/**
+ * Chat- and member-inspection actions.
+ *
+ * Group data comes from `groupMetadata`, which WhatsApp serves per JID
+ * and Baileys caches; DMs have no metadata endpoint, so their answers are
+ * assembled from the registry and the profile endpoints.
+ */
+
+import { downloadMediaMessage } from "baileys";
+import { lookupMessage } from "../message-store.js";
+import { toUserJid, tryAction } from "./shared.js";
+import type { WhatsAppActionHandlers } from "./types.js";
+
+/** Render one participant the way the other frontends render members. */
+function describeParticipant(p: {
+  id: string;
+  admin?: string | null;
+  name?: string | null;
+}): string {
+  const role =
+    p.admin === "superadmin" ? " (owner)" : p.admin ? " (admin)" : "";
+  const handle = p.id.split("@")[0];
+  return p.name ? `${p.name} [${handle}]${role}` : `${handle}${role}`;
+}
+
+export const chatInfoHandlers: WhatsAppActionHandlers = {
+  get_chat_info: (_body, chatId, ctx) =>
+    tryAction("get_chat_info", async () => {
+      const chat = ctx.chat!;
+      if (!chat.isGroup) {
+        return {
+          ok: true,
+          id: chatId,
+          type: "private",
+          title: chat.title ?? chat.jid.split("@")[0],
+        };
+      }
+      const meta = await ctx.sock.groupMetadata(chat.jid);
+      return {
+        ok: true,
+        id: chatId,
+        type: "group",
+        title: meta.subject,
+        description: meta.desc ?? undefined,
+        member_count: meta.participants.length,
+        owner: meta.owner ?? undefined,
+        created: meta.creation ?? undefined,
+        announce_only: Boolean(meta.announce),
+      };
+    }),
+
+  get_chat_admins: (_body, _chatId, ctx) =>
+    tryAction("get_chat_admins", async () => {
+      const chat = ctx.chat!;
+      if (!chat.isGroup) {
+        return { ok: true, text: "Direct message — no admins." };
+      }
+      const meta = await ctx.sock.groupMetadata(chat.jid);
+      const admins = meta.participants.filter((p) => p.admin);
+      return {
+        ok: true,
+        text: admins.length
+          ? admins.map(describeParticipant).join("\n")
+          : "No admins.",
+      };
+    }),
+
+  get_chat_member_count: (_body, _chatId, ctx) =>
+    tryAction("get_chat_member_count", async () => {
+      const chat = ctx.chat!;
+      if (!chat.isGroup) return { ok: true, count: 2, text: "2" };
+      const meta = await ctx.sock.groupMetadata(chat.jid);
+      return {
+        ok: true,
+        count: meta.participants.length,
+        text: String(meta.participants.length),
+      };
+    }),
+
+  list_chat_members: (body, _chatId, ctx) =>
+    tryAction("list_chat_members", async () => {
+      const chat = ctx.chat!;
+      if (!chat.isGroup) {
+        return { ok: true, text: "Direct message — just the two of you." };
+      }
+      const limit = Math.min(500, Number(body.limit ?? 100));
+      const meta = await ctx.sock.groupMetadata(chat.jid);
+      return {
+        ok: true,
+        text: meta.participants
+          .slice(0, limit)
+          .map(describeParticipant)
+          .join("\n"),
+      };
+    }),
+
+  get_member_info: (body, _chatId, ctx) =>
+    tryAction("get_member_info", async () => {
+      const jid = toUserJid(body.user_id ?? body.user_name);
+      if (!jid)
+        return { ok: false, error: "get_member_info: user_id required" };
+      const chat = ctx.chat!;
+      const lines: string[] = [`jid: ${jid}`];
+      if (chat.isGroup) {
+        const meta = await ctx.sock.groupMetadata(chat.jid);
+        const participant = meta.participants.find(
+          (p) => p.id.split("@")[0] === jid.split("@")[0],
+        );
+        if (!participant) {
+          return { ok: false, error: `${jid} is not in this group` };
+        }
+        lines.push(
+          `role: ${participant.admin === "superadmin" ? "owner" : (participant.admin ?? "member")}`,
+        );
+      }
+      // Profile lookups are best-effort: privacy settings routinely hide
+      // both, and a missing status is not an error.
+      const status: unknown = await ctx.sock
+        .fetchStatus(jid)
+        .catch(() => undefined);
+      // fetchStatus has returned both a bare object and a one-element
+      // array across Baileys versions; accept either shape.
+      const entry = (Array.isArray(status) ? status[0] : status) as
+        { status?: string | { status?: string } } | undefined;
+      const statusText =
+        typeof entry?.status === "string"
+          ? entry.status
+          : entry?.status?.status;
+      if (statusText) lines.push(`about: ${statusText}`);
+      const picture = await ctx.sock
+        .profilePictureUrl(jid, "image")
+        .catch(() => undefined);
+      if (picture) lines.push(`photo: ${picture}`);
+      return { ok: true, text: lines.join("\n") };
+    }),
+
+  get_user_profile_photos: (body, _chatId, ctx) =>
+    tryAction("get_user_profile_photos", async () => {
+      const jid = toUserJid(body.user_id) ?? ctx.chat!.jid;
+      const url = await ctx.sock
+        .profilePictureUrl(jid, "image")
+        .catch(() => undefined);
+      return url
+        ? { ok: true, text: url }
+        : {
+            ok: true,
+            text: "No profile photo (or hidden by privacy settings).",
+          };
+    }),
+
+  /** WhatsApp exposes no presence roster; presence is per-subscription. */
+  online_count: (_body, _chatId, ctx) =>
+    tryAction("online_count", async () => {
+      const chat = ctx.chat!;
+      if (!chat.isGroup) {
+        return { ok: true, text: "Presence is only visible per contact." };
+      }
+      const meta = await ctx.sock.groupMetadata(chat.jid);
+      return {
+        ok: true,
+        text:
+          `WhatsApp does not report a group online count; ` +
+          `${meta.participants.length} members total.`,
+      };
+    }),
+
+  set_chat_title: (body, _chatId, ctx) =>
+    tryAction("set_chat_title", async () => {
+      const chat = ctx.chat!;
+      if (!chat.isGroup) {
+        return { ok: false, error: "Only group subjects can be changed" };
+      }
+      const title = String(body.title ?? "").trim();
+      if (!title) return { ok: false, error: "set_chat_title: title required" };
+      await ctx.sock.groupUpdateSubject(chat.jid, title);
+      chat.title = title;
+      return { ok: true };
+    }),
+
+  set_chat_description: (body, _chatId, ctx) =>
+    tryAction("set_chat_description", async () => {
+      const chat = ctx.chat!;
+      if (!chat.isGroup) {
+        return { ok: false, error: "Only groups have a description" };
+      }
+      await ctx.sock.groupUpdateDescription(
+        chat.jid,
+        String(body.description ?? ""),
+      );
+      return { ok: true };
+    }),
+
+  /**
+   * Re-download a message's media on demand. Inbound media is already
+   * saved to the workspace as it arrives; this covers anything the model
+   * wants to pull again by id.
+   */
+  download_media: (body, _chatId, ctx) =>
+    tryAction("download_media", async () => {
+      const raw = body.message_id;
+      const msgId = typeof raw === "number" ? raw : Number(raw);
+      const stored = Number.isFinite(msgId) ? lookupMessage(msgId) : undefined;
+      if (!stored || stored.chatId !== ctx.chat!.chatId) {
+        return { ok: false, error: `Unknown message_id ${String(raw)}` };
+      }
+      if (!stored.message) {
+        return {
+          ok: false,
+          error: `Message ${msgId} is no longer retained in full`,
+        };
+      }
+      const { saveInboundMedia } = await import("../media-store.js");
+      const saved = await saveInboundMedia(
+        stored.message,
+        ctx.chat!.chatId,
+        msgId,
+        stored.senderName,
+      );
+      return saved
+        ? { ok: true, text: saved.filePath, file_path: saved.filePath }
+        : {
+            ok: false,
+            error: `Message ${msgId} carries no downloadable media`,
+          };
+    }),
+};
+
+export { downloadMediaMessage };

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

@@ -0,0 +1,78 @@
+/**
+ * WhatsApp-specific action handlers.
+ *
+ * Handles the MCP tool actions that need the WhatsApp socket.
+ * Platform-agnostic actions (cron, fetch_url, in-memory history) are
+ * served by core/engine/gateway-actions before this is reached, and any
+ * action this module doesn't claim returns null so that fallback still
+ * applies — which is how `read_history` and friends work here without a
+ * WhatsApp-specific implementation.
+ *
+ * Split by responsibility (mirrors the telegram/discord actions/ layout):
+ *   - shared     — tryAction, media/quote resolution, send helpers
+ *   - messaging  — text, replies, reactions, edits, deletes, pins, presence
+ *   - media      — images, video, audio, documents, polls, locations, …
+ *   - chat-info  — group metadata, members, titles, media download
+ *   - moderation — the `moderate` op switch
+ */
+
+import type { WASocket } from "baileys";
+import type { Gateway } from "../../../core/engine/gateway.js";
+import type { ActionResult } from "../../../core/types.js";
+import { lookupWhatsAppChat } from "../registry.js";
+import { chatInfoHandlers } from "./chat-info.js";
+import { mediaHandlers } from "./media.js";
+import { messagingHandlers } from "./messaging.js";
+import { moderationHandlers } from "./moderation.js";
+import type { WhatsAppActionContext, WhatsAppActionHandlers } from "./types.js";
+
+// Null-prototype so a request `action` of "toString" / "constructor" can't
+// resolve an inherited Object.prototype method via `handlers[action]`.
+const handlers: WhatsAppActionHandlers = Object.assign(Object.create(null), {
+  ...messagingHandlers,
+  ...mediaHandlers,
+  ...chatInfoHandlers,
+  ...moderationHandlers,
+});
+
+/** Actions that operate on the store alone and need no resolved chat. */
+const CHATLESS_ACTIONS = new Set(["cancel_scheduled", "list_scheduled"]);
+
+export function createWhatsAppActionHandler(
+  getSock: () => WASocket | null,
+  gateway: Gateway,
+) {
+  const scheduledMessages = new Map<string, ReturnType<typeof setTimeout>>();
+
+  return async (
+    body: Record<string, unknown>,
+    chatId: number,
+  ): Promise<ActionResult | null> => {
+    const action = body.action as string;
+    const handler = handlers[action];
+    if (!handler) return null; // not a WhatsApp action — let the core try
+
+    const sock = getSock();
+    if (!sock) {
+      return { ok: false, error: "WhatsApp socket is not connected" };
+    }
+
+    const chat = lookupWhatsAppChat(chatId) ?? null;
+    if (!chat && !CHATLESS_ACTIONS.has(action)) {
+      return {
+        ok: false,
+        error:
+          `No WhatsApp chat known for id ${chatId} — Talon learns a chat's ` +
+          `JID from its first message.`,
+      };
+    }
+
+    const ctx: WhatsAppActionContext = {
+      sock,
+      gateway,
+      chat,
+      scheduledMessages,
+    };
+    return handler(body, chatId, ctx);
+  };
+}

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

@@ -0,0 +1,248 @@
+/**
+ * Media actions — images, video, GIFs, voice notes, audio, documents,
+ * stickers, round video notes, albums, polls, locations, venues,
+ * contacts, and dice.
+ *
+ * Every Telegram/Discord send type has a WhatsApp equivalent except the
+ * two noted inline (dice is synthesised, albums are sent as a run of
+ * messages because WhatsApp groups them client-side by timing).
+ */
+
+import type { AnyMessageContent } from "baileys";
+import { toWhatsAppText } from "../formatting.js";
+import {
+  guessMimetype,
+  resolveMediaUpload,
+  resolveQuoted,
+  sendContent,
+  sendText,
+  tryAction,
+} from "./shared.js";
+import type { WhatsAppActionHandlers } from "./types.js";
+
+/** Optional caption, translated to WhatsApp's dialect. */
+function caption(body: Record<string, unknown>): { caption?: string } {
+  const raw = body.caption ?? body.text;
+  const text = raw === undefined || raw === null ? "" : String(raw);
+  return text.trim() ? { caption: toWhatsAppText(text) } : {};
+}
+
+/**
+ * Build the media payload for one send action. Returns an error string
+ * when the source can't be resolved, so callers report it verbatim.
+ */
+function buildMediaContent(
+  action: string,
+  body: Record<string, unknown>,
+): AnyMessageContent | { error: string } {
+  const resolved = resolveMediaUpload(body, action);
+  if ("error" in resolved) return resolved;
+  const { media, fileName } = resolved;
+
+  switch (action) {
+    case "send_photo":
+      return { image: media, ...caption(body) };
+    case "send_video":
+      return { video: media, ...caption(body) };
+    case "send_animation":
+      // WhatsApp has no GIF type — a looping muted video is what its own
+      // client sends when you pick a GIF.
+      return { video: media, gifPlayback: true, ...caption(body) };
+    case "send_video_note":
+      // ptv = "picture-in-video": the round bubble.
+      return { video: media, ptv: true };
+    case "send_voice":
+      return {
+        audio: media,
+        ptt: true,
+        mimetype: guessMimetype(fileName, "audio/ogg; codecs=opus"),
+      };
+    case "send_audio":
+      return {
+        audio: media,
+        ptt: false,
+        mimetype: guessMimetype(fileName, "audio/mpeg"),
+      };
+    case "send_sticker":
+      return { sticker: media };
+    case "send_file":
+    default:
+      return {
+        document: media,
+        mimetype: guessMimetype(fileName, "application/octet-stream"),
+        fileName: String(body.file_name ?? fileName),
+        ...caption(body),
+      };
+  }
+}
+
+const sendMedia: WhatsAppActionHandlers[string] = (body, _chatId, ctx) => {
+  const action = String(body.action);
+  return tryAction(action, async () => {
+    const content = buildMediaContent(action, body);
+    if ("error" in content) return { ok: false, error: content.error };
+    const quoted = resolveQuoted(body, ctx.chat!.chatId);
+    return sendContent(ctx, ctx.chat!, content, quoted ? { quoted } : {});
+  });
+};
+
+export const mediaHandlers: WhatsAppActionHandlers = {
+  send_photo: sendMedia,
+  send_video: sendMedia,
+  send_animation: sendMedia,
+  send_video_note: sendMedia,
+  send_voice: sendMedia,
+  send_audio: sendMedia,
+  send_file: sendMedia,
+
+  /**
+   * A sticker needs a WhatsApp-format .webp, addressed by file_path or
+   * url. Talon's saved sticker packs are Telegram file ids, which this
+   * account cannot upload, so an emoji-only request sends the emoji as
+   * its own message instead — WhatsApp renders a lone emoji large, which
+   * is the native form of the same gesture.
+   */
+  send_sticker: (body, _chatId, ctx) =>
+    tryAction("send_sticker", async () => {
+      if (!body.file_path && !body.url) {
+        const emoji = String(body.emoji ?? "").trim();
+        if (!emoji) {
+          return {
+            ok: false,
+            error:
+              "send_sticker: provide file_path or url to a .webp sticker, or an emoji",
+          };
+        }
+        return sendText(ctx, ctx.chat!, emoji);
+      }
+      const content = buildMediaContent("send_sticker", body);
+      if ("error" in content) return { ok: false, error: content.error };
+      return sendContent(ctx, ctx.chat!, content);
+    }),
+
+  /**
+   * WhatsApp has no album envelope on the send path — its client groups
+   * consecutive media from one sender itself, so a run of sends is the
+   * native shape. The first item's id is reported, matching how the other
+   * frontends treat a media group.
+   */
+  send_media_group: (body, _chatId, ctx) =>
+    tryAction("send_media_group", async () => {
+      const items = (body.media ?? []) as Array<Record<string, unknown>>;
+      if (!Array.isArray(items) || items.length === 0) {
+        return { ok: false, error: "send_media_group: media[] is required" };
+      }
+      let first: Awaited<ReturnType<typeof sendContent>> | undefined;
+      for (const item of items) {
+        const action =
+          String(item.type ?? "photo") === "video"
+            ? "send_video"
+            : "send_photo";
+        const content = buildMediaContent(action, item);
+        if ("error" in content) return { ok: false, error: content.error };
+        const result = await sendContent(ctx, ctx.chat!, content);
+        first ??= result;
+      }
+      return first ?? { ok: true };
+    }),
+
+  send_poll: (body, _chatId, ctx) =>
+    tryAction("send_poll", async () => {
+      const values = (body.options ?? []) as unknown[];
+      const question = String(body.question ?? "");
+      if (!question || !Array.isArray(values) || values.length < 2) {
+        return {
+          ok: false,
+          error: "send_poll: question and at least 2 options are required",
+        };
+      }
+      return sendContent(ctx, ctx.chat!, {
+        poll: {
+          name: question,
+          values: values.map((v) => String(v)),
+          selectableCount: body.allows_multiple_answers ? values.length : 1,
+        },
+      });
+    }),
+
+  send_location: (body, _chatId, ctx) =>
+    tryAction("send_location", async () => {
+      const latitude = Number(body.latitude);
+      const longitude = Number(body.longitude);
+      if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) {
+        return {
+          ok: false,
+          error: "send_location: latitude and longitude are required",
+        };
+      }
+      return sendContent(ctx, ctx.chat!, {
+        location: { degreesLatitude: latitude, degreesLongitude: longitude },
+      });
+    }),
+
+  send_venue: (body, _chatId, ctx) =>
+    tryAction("send_venue", async () => {
+      const latitude = Number(body.latitude);
+      const longitude = Number(body.longitude);
+      if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) {
+        return {
+          ok: false,
+          error: "send_venue: latitude and longitude are required",
+        };
+      }
+      // A venue is a location carrying a name and address — WhatsApp's
+      // location message has both fields.
+      return sendContent(ctx, ctx.chat!, {
+        location: {
+          degreesLatitude: latitude,
+          degreesLongitude: longitude,
+          name: body.title ? String(body.title) : undefined,
+          address: body.address ? String(body.address) : undefined,
+        },
+      });
+    }),
+
+  send_contact: (body, _chatId, ctx) =>
+    tryAction("send_contact", async () => {
+      const phone = String(body.phone_number ?? "").replace(/[^0-9+]/g, "");
+      const first = String(body.first_name ?? "").trim();
+      const last = String(body.last_name ?? "").trim();
+      const displayName = [first, last].filter(Boolean).join(" ") || phone;
+      if (!phone) {
+        return { ok: false, error: "send_contact: phone_number is required" };
+      }
+      // vCard 3.0 is what WhatsApp's own client emits for a shared contact.
+      const vcard = [
+        "BEGIN:VCARD",
+        "VERSION:3.0",
+        `FN:${displayName}`,
+        `TEL;type=CELL;waid=${phone.replace(/\D/g, "")}:${phone}`,
+        "END:VCARD",
+      ].join("\n");
+      return sendContent(ctx, ctx.chat!, {
+        contacts: { displayName, contacts: [{ vcard }] },
+      });
+    }),
+
+  /**
+   * WhatsApp has no dice message. Rolling here and sending the result
+   * keeps the tool honest — the model asked for a random throw and gets
+   * one, rendered the way a person would type it.
+   */
+  send_dice: (body, _chatId, ctx) =>
+    tryAction("send_dice", async () => {
+      const emoji = String(body.emoji ?? "🎲");
+      const faces: Record<string, number> = {
+        "🎲": 6,
+        "🎯": 6,
+        "🏀": 5,
+        "⚽": 5,
+        "🎳": 6,
+        "🎰": 64,
+      };
+      const max = faces[emoji] ?? 6;
+      const value = 1 + Math.floor(Math.random() * max);
+      const result = await sendText(ctx, ctx.chat!, `${emoji} ${value}`);
+      return { ...result, value };
+    }),
+};