talon-agent 3.24.1 → 3.25.1

package/src/core/tools/messaging.ts

@@ -110,7 +110,7 @@ Notes:
       // src/backend/claude-sdk/options.ts:turnTerminatorHook.
       return throwIfFailed(result, "end_turn");
     },
-    frontends: ["telegram", "teams", "discord", "native"],
+    frontends: ["telegram", "teams", "discord", "native", "whatsapp"],
     tag: "messaging",
     endsTurn: true,
     delivery: true,
@@ -473,7 +473,7 @@ Examples:
           return { ok: false, error: `Unknown type: ${type}` };
       }
     },
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "messaging",
     delivery: true,
   },
@@ -490,7 +490,7 @@ Examples:
       text: z.string().describe("Message text. Supports Markdown."),
     },
     execute: (params, bridge) => bridge("send_message", params),
-    frontends: ["teams", "native"],
+    frontends: ["teams", "native", "whatsapp"],
     tag: "messaging",
     delivery: true,
   },
@@ -515,7 +515,7 @@ Example: send_message_with_buttons(text="Choose:", rows=[[{"text":"Docs","url":"
         .describe("Button rows"),
     },
     execute: (params, bridge) => bridge("send_message_with_buttons", params),
-    frontends: ["teams", "native"],
+    frontends: ["teams", "native", "whatsapp"],
     tag: "messaging",
     delivery: true,
   },
@@ -572,7 +572,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
       const result = await bridge("react", rest);
       return throwIfFailed(result, "react");
     },
-    frontends: ["telegram", "discord", "native"],
+    frontends: ["telegram", "discord", "native", "whatsapp"],
     tag: "messaging",
     endsTurn: true,
     delivery: true,
@@ -592,7 +592,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
         .describe("Edit the media caption rather than message text (Telegram)"),
     },
     execute: (params, bridge) => bridge("edit_message", params),
-    frontends: ["telegram", "discord", "native"],
+    frontends: ["telegram", "discord", "native", "whatsapp"],
     tag: "messaging",
   },
 
@@ -609,7 +609,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
         .describe("Bulk delete these message IDs (Telegram)"),
     },
     execute: (params, bridge) => bridge("delete_message", params),
-    frontends: ["telegram", "discord", "native"],
+    frontends: ["telegram", "discord", "native", "whatsapp"],
     tag: "messaging",
   },
 
@@ -632,7 +632,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
         .describe("Destination chat (default: current chat)"),
     },
     execute: (params, bridge) => bridge("forward_message", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "messaging",
   },
 
@@ -648,7 +648,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
       to_chat_id: chatIdSchema.optional(),
     },
     execute: (params, bridge) => bridge("copy_message", params),
-    frontends: ["telegram"],
+    frontends: ["telegram", "whatsapp"],
     tag: "messaging",
   },
 
@@ -658,7 +658,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
     description: "Pin a message.",
     schema: { message_id: snowflakeOrIdSchema },
     execute: (params, bridge) => bridge("pin_message", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "messaging",
   },
 
@@ -668,7 +668,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
     description: "Unpin a message.",
     schema: { message_id: snowflakeOrIdSchema.optional() },
     execute: (params, bridge) => bridge("unpin_message", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "messaging",
   },
 
@@ -681,6 +681,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
       message_id: idSchema.describe("Message ID of the poll to stop"),
     },
     execute: (params, bridge) => bridge("stop_poll", params),
+    // No WhatsApp equivalent: its polls run until the message is deleted.
     frontends: ["telegram"],
     tag: "messaging",
   },

package/src/core/tools/moderation.ts

@@ -112,7 +112,7 @@ Forum topics (supergroups with topics):
         .describe("Target chat ID. Omit for the current chat."),
     },
     execute: (params, bridge) => bridge("moderate", params),
-    frontends: ["telegram"],
+    frontends: ["telegram", "whatsapp"],
     tag: "moderation",
   },
 
@@ -125,7 +125,7 @@ Forum topics (supergroups with topics):
       limit: z.number().optional().describe("Max photos to return (default 5)"),
     },
     execute: (params, bridge) => bridge("get_user_profile_photos", params),
-    frontends: ["telegram"],
+    frontends: ["telegram", "whatsapp"],
     tag: "moderation",
   },
 ];

package/src/core/tools/scheduling.ts

@@ -11,7 +11,7 @@ export const schedulingTools: ToolDefinition[] = [
     description: "Cancel a scheduled message.",
     schema: { schedule_id: z.string() },
     execute: (params, bridge) => bridge("cancel_scheduled", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "scheduling",
   },
 
@@ -21,7 +21,7 @@ export const schedulingTools: ToolDefinition[] = [
       "List pending scheduled messages in this chat (id, seconds until send, text). Scheduled messages persist across restarts.",
     schema: {},
     execute: (_params, bridge) => bridge("list_scheduled", {}),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "scheduling",
   },
 

package/src/core/tools/types.ts

@@ -9,7 +9,7 @@ import type { ZodRawShape } from "zod";
 
 /** Which frontends a tool is available on.  "all" = every frontend. */
 export type ToolFrontend =
-  "telegram" | "teams" | "terminal" | "discord" | "native" | "all";
+  "telegram" | "teams" | "terminal" | "discord" | "native" | "whatsapp" | "all";
 
 /** Domain tags for runtime filtering and grouping. */
 export type ToolTag =

package/src/frontend/factories.ts

@@ -12,4 +12,5 @@ import "./telegram/factory.js";
 import "./discord/factory.js";
 import "./teams/factory.js";
 import "./native/factory.js";
+import "./whatsapp/factory.js";
 import "./terminal/factory.js";

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