talon-agent 3.24.1 → 3.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.24.1",
+  "version": "3.25.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -110,6 +110,7 @@
     "@opencode-ai/sdk": "^1.17.4",
     "@playwright/mcp": "0.0.79",
     "@types/cross-spawn": "^6.0.6",
+    "baileys": "^7.0.0-rc14",
     "big-integer": "^1.6.52",
     "cheerio": "^1.2.0",
     "croner": "^10.0.1",
@@ -125,6 +126,7 @@
     "picocolors": "^1.1.1",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
+    "qrcode-terminal": "^0.12.0",
     "telegram": "^2.26.22",
     "tsx": "^4.21.0",
     "undici": "^8.0.2",
@@ -135,6 +137,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.0.0",
+    "@types/qrcode-terminal": "^0.12.2",
     "@types/write-file-atomic": "^4.0.3",
     "@vitest/coverage-v8": "^4.1.3",
     "dependency-cruiser": "^18.1.0",

package/prompts/whatsapp.md

@@ -0,0 +1,58 @@
+## WhatsApp Mode
+
+You are running on a personal WhatsApp account (multi-device link).
+Messages arrive as `[SenderName] msg_id:<id>: text`. Use names naturally,
+and use that `msg_id` when a tool asks for a message id — reactions,
+replies, edits, deletes and pins all address messages that way.
+
+How replies are delivered (end_turn / send_message and what counts as a
+valid turn) is defined in the **Response flow** section at the end of
+these instructions — that contract wins over anything here.
+
+### Formatting
+
+WhatsApp has its own markup, and Talon converts standard Markdown into it
+for you. Write normal Markdown; these are the shapes that survive:
+
+- `**bold**` → _bold_, `_italic_`, `~~strike~~` → ~~strike~~
+- `` `inline code` `` and fenced code blocks
+- Bullet and numbered lists, block quotes
+- Headings become bold lines — WhatsApp has no heading sizes
+- Links render as `label (https://url)`; bare URLs auto-link
+- Tables become an aligned monospace block; keep them narrow
+
+Long messages are split across bubbles automatically at 4096 characters.
+
+### What works here
+
+Text, replies, reactions, edits, deletes, forwards, pins, and typing
+indicators. Media: photos, video, GIFs, voice notes, audio, documents,
+stickers (.webp), round video notes, and albums. Also polls, locations,
+venues, and contact cards. In groups you can read metadata, list members
+and admins, change the subject and description, manage invite links,
+handle join requests, and add/remove/promote/demote members when you are
+an admin.
+
+Inbound media is downloaded to the workspace before your turn starts —
+the file path is in the message, so you can read it immediately.
+
+### What WhatsApp cannot do
+
+- No interactive buttons on a personal account — button rows are rendered
+  as a numbered list, and people reply with the number.
+- No ban list: removing someone from a group is the only eviction, and
+  they can rejoin with an invite link.
+- No per-member mute — a group is either open or admins-only.
+- No forum topics, no custom admin titles, no stopping a poll.
+- Pins expire (24h, 7d, or 30d) and only pins Talon placed are listable.
+
+### Staying silent
+
+Reactions work here, so a react is the light acknowledgement when a
+message needs no reply; otherwise close the turn silently as the contract
+describes.
+
+### Style
+
+Concise. This is a phone chat — short paragraphs, no filler, no walls of
+text. Match the sender's register.

package/src/backend/shared/delivery-contract.ts

@@ -67,6 +67,7 @@ const FRONTEND_TOOLS: Record<string, DeliveryToolNames> = {
   discord: { endTurn: "end_turn", send: "send", react: "react" },
   teams: { endTurn: "end_turn", send: "send_message" },
   native: { endTurn: "end_turn", send: "send_message", react: "react" },
+  whatsapp: { endTurn: "end_turn", send: "send_message" },
 };
 
 const DEFAULT_TOOLS: DeliveryToolNames = {

package/src/core/doctor.ts

@@ -73,6 +73,7 @@ export interface DoctorConfigSlice {
   botToken?: string;
   teamsWebhookUrl?: string;
   discord?: { botToken?: string };
+  whatsapp?: object;
   claudeBinary?: string;
   codexApiKey?: string;
   openaiApiKey?: string;
@@ -128,6 +129,10 @@ function unconfiguredFrontends(config: DoctorConfigSlice): string[] {
     if (fe === "telegram") return !config.botToken;
     if (fe === "teams") return !config.teamsWebhookUrl;
     if (fe === "discord") return !config.discord?.botToken;
+    // WhatsApp needs no stored credential — pairing is interactive (QR /
+    // pairing code at first start) — but the config block must exist so
+    // the JID allowlists were consciously set.
+    if (fe === "whatsapp") return !config.whatsapp;
     return fe !== "terminal" && fe !== "native";
   });
 }

package/src/core/frontend-runtime/builtins.ts

@@ -24,6 +24,7 @@ import {
   isTeamsChatId,
   isTelegramChatId,
   isTerminalChatId,
+  isWhatsAppChatId,
 } from "../../util/chat-id.js";
 
 function registerBuiltinFrontends(): void {
@@ -56,6 +57,13 @@ function registerBuiltinFrontends(): void {
     routePriority: 40,
     messaging: true,
   });
+  registerFrontend({
+    id: "whatsapp",
+    label: "WhatsApp",
+    ownsChatId: isWhatsAppChatId,
+    routePriority: 50,
+    messaging: true,
+  });
   registerFrontend({
     id: "telegram",
     label: "Telegram",

package/src/core/mcp-hub/talon-server.ts

@@ -25,6 +25,7 @@ export const VALID_TOOL_FRONTENDS: ReadonlySet<string> = new Set([
   "terminal",
   "discord",
   "native",
+  "whatsapp",
 ]);
 
 export type TalonServerOptions = {

package/src/core/prompt/embedded-prompts.ts

@@ -35,6 +35,7 @@ import asset21 from "../../../prompts/system/workspace.md" with { type: "file" }
 import asset22 from "../../../prompts/teams.md" with { type: "file" };
 import asset23 from "../../../prompts/telegram.md" with { type: "file" };
 import asset24 from "../../../prompts/terminal.md" with { type: "file" };
+import asset25 from "../../../prompts/whatsapp.md" with { type: "file" };
 
 /** rel path (posix, under prompts/) → embedded file path (/$bunfs/… when compiled). */
 const ASSETS: Record<string, string> = {
@@ -63,6 +64,7 @@ const ASSETS: Record<string, string> = {
   "teams.md": asset22,
   "telegram.md": asset23,
   "terminal.md": asset24,
+  "whatsapp.md": asset25,
 };
 
 /** Read an embedded prompt by its rel path (e.g. "system/cron.md"). */

package/src/core/tools/chat.ts

@@ -19,7 +19,7 @@ export const chatTools: ToolDefinition[] = [
     description: "List chat administrators.",
     schema: {},
     execute: (_params, bridge) => bridge("get_chat_admins", {}),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "chat",
   },
 
@@ -28,7 +28,7 @@ export const chatTools: ToolDefinition[] = [
     description: "Get total member count.",
     schema: {},
     execute: (_params, bridge) => bridge("get_chat_member_count", {}),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "chat",
   },
 
@@ -37,7 +37,7 @@ export const chatTools: ToolDefinition[] = [
     description: "Change chat title (admin).",
     schema: { title: z.string() },
     execute: (params, bridge) => bridge("set_chat_title", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "chat",
   },
 
@@ -46,7 +46,7 @@ export const chatTools: ToolDefinition[] = [
     description: "Change chat description (admin).",
     schema: { description: z.string() },
     execute: (params, bridge) => bridge("set_chat_description", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "chat",
   },
 ];

package/src/core/tools/history.ts

@@ -30,7 +30,7 @@ export const historyTools: ToolDefinition[] = [
         before: params.before,
         offset_id: params.offset_id,
       }),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "history",
   },
 
@@ -42,7 +42,7 @@ export const historyTools: ToolDefinition[] = [
       limit: z.number().optional(),
     },
     execute: (params, bridge) => bridge("search_history", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "history",
   },
 
@@ -54,7 +54,7 @@ export const historyTools: ToolDefinition[] = [
       limit: z.number().optional(),
     },
     execute: (params, bridge) => bridge("get_user_messages", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "history",
   },
 
@@ -63,7 +63,7 @@ export const historyTools: ToolDefinition[] = [
     description: "Get a specific message by ID.",
     schema: { message_id: snowflakeOrIdSchema },
     execute: (params, bridge) => bridge("get_message_by_id", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "history",
   },
 
@@ -77,7 +77,7 @@ export const historyTools: ToolDefinition[] = [
       ),
     },
     execute: (params, bridge) => bridge("download_media", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "history",
   },
 ];

package/src/core/tools/media.ts

@@ -17,7 +17,7 @@ export const mediaTools: ToolDefinition[] = [
         .describe("Number of entries (default 10, max 20)"),
     },
     execute: (params, bridge) => bridge("list_media", { limit: params.limit }),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "media",
   },
 ];

package/src/core/tools/members.ts

@@ -13,7 +13,7 @@ export const memberTools: ToolDefinition[] = [
     schema: { limit: z.number().optional() },
     execute: (params, bridge) =>
       bridge("list_known_users", { limit: params.limit }),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "members",
   },
 
@@ -22,7 +22,7 @@ export const memberTools: ToolDefinition[] = [
     description: "Get detailed info about a user by ID.",
     schema: { user_id: snowflakeOrIdSchema },
     execute: (params, bridge) => bridge("get_member_info", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "members",
   },
 
@@ -32,7 +32,7 @@ export const memberTools: ToolDefinition[] = [
       "Get how many members are currently online or recently active.",
     schema: {},
     execute: (_params, bridge) => bridge("online_count", {}),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "members",
   },
 
@@ -41,7 +41,7 @@ export const memberTools: ToolDefinition[] = [
     description: "Get all pinned messages in the current chat.",
     schema: {},
     execute: (_params, bridge) => bridge("get_pinned_messages", {}),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "members",
   },
 ];

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";