talon-agent 1.3.0 → 1.4.0

package/src/core/tools/messaging.ts

@@ -0,0 +1,300 @@
+/**
+ * Messaging tools — send, react, edit, delete, forward, pin/unpin, stop poll.
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+
+export const messagingTools: ToolDefinition[] = [
+  // ── Telegram unified send ─────────────────────────────────────────────
+  {
+    name: "send",
+    description: `Send content to the current Telegram chat. Supports text, photos, videos, files, audio, voice, stickers, polls, locations, contacts, dice, and GIFs.
+
+Examples:
+  Text: send(type="text", text="Hello!")
+  Reply: send(type="text", text="Yes!", reply_to=12345)
+  With buttons: send(type="text", text="Pick one", buttons=[[{"text":"A","callback_data":"a"}]])
+  Photo: send(type="photo", file_path="/path/to/img.jpg", caption="Look!")
+  File: send(type="file", file_path="/path/to/report.pdf")
+  Audio: send(type="audio", file_path="/path/to/song.mp3", title="Song Name", performer="Artist")
+  Poll: send(type="poll", question="Best language?", options=["Rust","Go","TS"])
+  Dice: send(type="dice")
+  Location: send(type="location", latitude=37.7749, longitude=-122.4194)
+  Sticker: send(type="sticker", file_id="CAACAgI...")`,
+    schema: {
+      type: z
+        .enum([
+          "text",
+          "photo",
+          "file",
+          "video",
+          "voice",
+          "audio",
+          "animation",
+          "sticker",
+          "poll",
+          "location",
+          "contact",
+          "dice",
+        ])
+        .describe("Content type to send"),
+      text: z
+        .string()
+        .optional()
+        .describe("Message text (for type=text). Supports Markdown."),
+      reply_to: z.number().optional().describe("Message ID to reply to"),
+      file_path: z
+        .string()
+        .optional()
+        .describe("Workspace file path (for photo/file/video/voice/animation)"),
+      file_id: z.string().optional().describe("Telegram file_id (for sticker)"),
+      caption: z.string().optional().describe("Caption for media"),
+      buttons: z
+        .array(
+          z.array(
+            z.object({
+              text: z.string(),
+              url: z.string().optional(),
+              callback_data: z.string().optional(),
+            }),
+          ),
+        )
+        .optional()
+        .describe("Inline keyboard button rows"),
+      question: z.string().optional().describe("Poll question"),
+      options: z.array(z.string()).optional().describe("Poll options"),
+      is_anonymous: z.boolean().optional().describe("Anonymous poll"),
+      correct_option_id: z
+        .number()
+        .optional()
+        .describe("Quiz correct answer index"),
+      explanation: z.string().optional().describe("Quiz explanation"),
+      latitude: z.number().optional().describe("Location latitude"),
+      longitude: z.number().optional().describe("Location longitude"),
+      phone_number: z.string().optional().describe("Contact phone"),
+      first_name: z.string().optional().describe("Contact first name"),
+      last_name: z.string().optional().describe("Contact last name"),
+      title: z.string().optional().describe("Audio title (for type=audio)"),
+      performer: z
+        .string()
+        .optional()
+        .describe("Audio performer/artist (for type=audio)"),
+      emoji: z.string().optional().describe("Dice emoji (🎲🎯🏀⚽🎳🎰)"),
+      delay_seconds: z
+        .number()
+        .optional()
+        .describe("Schedule: delay before sending (1-3600)"),
+    },
+    execute: async (params, bridge) => {
+      const { type } = params;
+      switch (type) {
+        case "text": {
+          if (params.delay_seconds) {
+            return bridge("schedule_message", {
+              text: params.text,
+              delay_seconds: params.delay_seconds,
+            });
+          }
+          if (params.buttons) {
+            return bridge("send_message_with_buttons", {
+              text: params.text,
+              rows: params.buttons,
+              reply_to_message_id: params.reply_to,
+            });
+          }
+          return bridge("send_message", {
+            text: params.text,
+            reply_to_message_id: params.reply_to,
+          });
+        }
+        case "photo":
+          return bridge("send_photo", {
+            file_path: params.file_path,
+            caption: params.caption,
+            reply_to: params.reply_to,
+          });
+        case "file":
+          return bridge("send_file", {
+            file_path: params.file_path,
+            caption: params.caption,
+            reply_to: params.reply_to,
+          });
+        case "video":
+          return bridge("send_video", {
+            file_path: params.file_path,
+            caption: params.caption,
+            reply_to: params.reply_to,
+          });
+        case "voice":
+          return bridge("send_voice", {
+            file_path: params.file_path,
+            caption: params.caption,
+            reply_to: params.reply_to,
+          });
+        case "audio":
+          return bridge("send_audio", {
+            file_path: params.file_path,
+            caption: params.caption,
+            title: params.title,
+            performer: params.performer,
+            reply_to: params.reply_to,
+          });
+        case "animation":
+          return bridge("send_animation", {
+            file_path: params.file_path,
+            caption: params.caption,
+            reply_to: params.reply_to,
+          });
+        case "sticker":
+          return bridge("send_sticker", {
+            file_id: params.file_id,
+            reply_to: params.reply_to,
+          });
+        case "poll":
+          return bridge("send_poll", {
+            question: params.question,
+            options: params.options,
+            is_anonymous: params.is_anonymous,
+            correct_option_id: params.correct_option_id,
+            explanation: params.explanation,
+            type: params.correct_option_id !== undefined ? "quiz" : "regular",
+          });
+        case "location":
+          return bridge("send_location", {
+            latitude: params.latitude,
+            longitude: params.longitude,
+          });
+        case "contact":
+          return bridge("send_contact", {
+            phone_number: params.phone_number,
+            first_name: params.first_name,
+            last_name: params.last_name,
+          });
+        case "dice":
+          return bridge("send_dice", { emoji: params.emoji });
+        default:
+          return { ok: false, error: `Unknown type: ${type}` };
+      }
+    },
+    frontends: ["telegram"],
+    tag: "messaging",
+  },
+
+  // ── Teams send_message ────────────────────────────────────────────────
+  {
+    name: "send_message",
+    description: `Send a message to the Teams chat. Supports Markdown formatting.
+
+Examples:
+  send_message(text="Hello!")
+  send_message(text="Here's a **bold** message with \`code\`")`,
+    schema: {
+      text: z.string().describe("Message text. Supports Markdown."),
+    },
+    execute: (params, bridge) => bridge("send_message", params),
+    frontends: ["teams"],
+    tag: "messaging",
+  },
+
+  // ── Teams send_message_with_buttons ───────────────────────────────────
+  {
+    name: "send_message_with_buttons",
+    description: `Send a message with clickable link buttons. Buttons appear below the message as Adaptive Card actions.
+
+Example: send_message_with_buttons(text="Choose:", rows=[[{"text":"Docs","url":"https://..."}]])`,
+    schema: {
+      text: z.string().describe("Message text"),
+      rows: z
+        .array(
+          z.array(
+            z.object({
+              text: z.string().describe("Button label"),
+              url: z.string().optional().describe("URL to open when clicked"),
+            }),
+          ),
+        )
+        .describe("Button rows"),
+    },
+    execute: (params, bridge) => bridge("send_message_with_buttons", params),
+    frontends: ["teams"],
+    tag: "messaging",
+  },
+
+  // ── react ─────────────────────────────────────────────────────────────
+  {
+    name: "react",
+    description:
+      "Add an emoji reaction to a message. Valid: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉 🤩 🤮 💩 🙏 👌 🕊 🤡 🥱 🥴 😍 🐳 ❤‍🔥 🌚 🌭 💯 🤣 ⚡ 🍌 🏆 💔 🤨 😐 🍓 🍾 💋 🖕 😈 😴 😭 🤓 👻 👨‍💻 👀 🎃 🙈 😇 😨 🤝 ✍ 🤗 🫡 🎅 🎄 ☃ 💅 🤪 🗿 🆒 💘 🙉 🦄 😘 💊 🙊 😎 👾 🤷 🤷‍♂ 🤷‍♀ 😡",
+    schema: {
+      message_id: z.number().describe("Message ID"),
+      emoji: z.string().describe("Reaction emoji"),
+    },
+    execute: (params, bridge) => bridge("react", params),
+    frontends: ["telegram"],
+    tag: "messaging",
+  },
+
+  // ── edit_message ──────────────────────────────────────────────────────
+  {
+    name: "edit_message",
+    description: "Edit a previously sent message.",
+    schema: { message_id: z.number(), text: z.string() },
+    execute: (params, bridge) => bridge("edit_message", params),
+    frontends: ["telegram"],
+    tag: "messaging",
+  },
+
+  // ── delete_message ────────────────────────────────────────────────────
+  {
+    name: "delete_message",
+    description: "Delete a message.",
+    schema: { message_id: z.number() },
+    execute: (params, bridge) => bridge("delete_message", params),
+    frontends: ["telegram"],
+    tag: "messaging",
+  },
+
+  // ── forward_message ───────────────────────────────────────────────────
+  {
+    name: "forward_message",
+    description: "Forward a message within the chat.",
+    schema: { message_id: z.number() },
+    execute: (params, bridge) => bridge("forward_message", params),
+    frontends: ["telegram"],
+    tag: "messaging",
+  },
+
+  // ── pin_message ───────────────────────────────────────────────────────
+  {
+    name: "pin_message",
+    description: "Pin a message.",
+    schema: { message_id: z.number() },
+    execute: (params, bridge) => bridge("pin_message", params),
+    frontends: ["telegram"],
+    tag: "messaging",
+  },
+
+  // ── unpin_message ─────────────────────────────────────────────────────
+  {
+    name: "unpin_message",
+    description: "Unpin a message.",
+    schema: { message_id: z.number().optional() },
+    execute: (params, bridge) => bridge("unpin_message", params),
+    frontends: ["telegram"],
+    tag: "messaging",
+  },
+
+  // ── stop_poll ─────────────────────────────────────────────────────────
+  {
+    name: "stop_poll",
+    description:
+      "Stop an active poll and get the final results. Returns vote counts for each option.",
+    schema: {
+      message_id: z.number().describe("Message ID of the poll to stop"),
+    },
+    execute: (params, bridge) => bridge("stop_poll", params),
+    frontends: ["telegram"],
+    tag: "messaging",
+  },
+];

package/src/core/tools/scheduling.ts

@@ -0,0 +1,89 @@
+/**
+ * Scheduling tools — cron CRUD and scheduled message cancellation.
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+
+export const schedulingTools: ToolDefinition[] = [
+  {
+    name: "cancel_scheduled",
+    description: "Cancel a scheduled message.",
+    schema: { schedule_id: z.string() },
+    execute: (params, bridge) => bridge("cancel_scheduled", params),
+    frontends: ["telegram"],
+    tag: "scheduling",
+  },
+
+  {
+    name: "create_cron_job",
+    description: `Create a persistent recurring scheduled job. Jobs survive restarts.
+
+Cron format: "minute hour day month weekday" (5 fields)
+Examples:
+  "0 9 * * *"     = every day at 9:00 AM
+  "30 14 * * 1-5" = weekdays at 2:30 PM
+  "*/15 * * * *"  = every 15 minutes
+  "0 0 1 * *"     = first day of every month at midnight
+  "0 8 * * 1"     = every Monday at 8:00 AM
+
+Type "message" sends the content as a text message.
+Type "query" runs the content as a Claude prompt with full tool access (can search, create files, send messages, etc).`,
+    schema: {
+      name: z.string().describe("Human-readable name for the job"),
+      schedule: z
+        .string()
+        .describe("Cron expression (5-field: minute hour day month weekday)"),
+      type: z
+        .enum(["message", "query"])
+        .describe(
+          "Job type: 'message' sends text, 'query' runs a Claude prompt",
+        ),
+      content: z.string().describe("Message text or query prompt"),
+      timezone: z
+        .string()
+        .optional()
+        .describe(
+          "IANA timezone (e.g. 'America/New_York'). Defaults to system timezone.",
+        ),
+    },
+    execute: (params, bridge) => bridge("create_cron_job", params),
+    tag: "scheduling",
+  },
+
+  {
+    name: "list_cron_jobs",
+    description:
+      "List all cron jobs in the current chat with their status, schedule, run count, and next run time.",
+    schema: {},
+    execute: (_params, bridge) => bridge("list_cron_jobs", {}),
+    tag: "scheduling",
+  },
+
+  {
+    name: "edit_cron_job",
+    description:
+      "Edit an existing cron job. Only provide the fields you want to change.",
+    schema: {
+      job_id: z.string().describe("Job ID to edit"),
+      name: z.string().optional().describe("New name"),
+      schedule: z.string().optional().describe("New cron expression"),
+      type: z.enum(["message", "query"]).optional().describe("New job type"),
+      content: z.string().optional().describe("New content"),
+      enabled: z.boolean().optional().describe("Enable or disable the job"),
+      timezone: z.string().optional().describe("New IANA timezone"),
+    },
+    execute: (params, bridge) => bridge("edit_cron_job", params),
+    tag: "scheduling",
+  },
+
+  {
+    name: "delete_cron_job",
+    description: "Delete a cron job permanently.",
+    schema: {
+      job_id: z.string().describe("Job ID to delete"),
+    },
+    execute: (params, bridge) => bridge("delete_cron_job", params),
+    tag: "scheduling",
+  },
+];

package/src/core/tools/stickers.ts

@@ -0,0 +1,143 @@
+/**
+ * Sticker tools — browse, download, save, create, and manage sticker packs.
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+
+export const stickerTools: ToolDefinition[] = [
+  {
+    name: "get_sticker_pack",
+    description:
+      "Get all stickers in a sticker pack by its name. Returns emoji + file_id for each sticker so you can send them. Use when you see a sticker set name in chat history.",
+    schema: {
+      set_name: z
+        .string()
+        .describe(
+          "Sticker set name (e.g. 'AnimatedEmojis' or from sticker metadata)",
+        ),
+    },
+    execute: (params, bridge) => bridge("get_sticker_pack", params),
+    frontends: ["telegram"],
+    tag: "stickers",
+  },
+
+  {
+    name: "download_sticker",
+    description:
+      "Download a sticker image to workspace so you can view its contents. Returns the file path.",
+    schema: {
+      file_id: z
+        .string()
+        .describe("Sticker file_id from chat history or sticker pack listing"),
+    },
+    execute: (params, bridge) => bridge("download_sticker", params),
+    frontends: ["telegram"],
+    tag: "stickers",
+  },
+
+  {
+    name: "save_sticker_pack",
+    description:
+      "Save a sticker pack's file_ids to workspace for quick reuse. Once saved, you can read the JSON file to find stickers by emoji and send them instantly.",
+    schema: {
+      set_name: z.string().describe("Sticker set name"),
+    },
+    execute: (params, bridge) => bridge("save_sticker_pack", params),
+    frontends: ["telegram"],
+    tag: "stickers",
+  },
+
+  {
+    name: "create_sticker_set",
+    description: `Create a new sticker pack owned by a user. The bot will be the creator.
+Sticker images must be PNG/WEBP, max 512x512px for static stickers.
+The set name will automatically get "_by_<botname>" appended if needed.
+
+Example: create_sticker_set(user_id=123, name="cool_pack", title="Cool Stickers", file_path="/path/to/sticker.png", emoji_list=["😎"])`,
+    schema: {
+      user_id: z.number().describe("Telegram user ID who will own the pack"),
+      name: z
+        .string()
+        .describe(
+          "Short name for the pack (a-z, 0-9, underscores). Will get _by_<botname> appended.",
+        ),
+      title: z.string().describe("Display title for the pack (1-64 chars)"),
+      file_path: z
+        .string()
+        .describe("Path to the sticker image file (PNG/WEBP, 512x512 max)"),
+      emoji_list: z
+        .array(z.string())
+        .optional()
+        .describe("Emojis for this sticker (default: ['🎨'])"),
+      format: z
+        .enum(["static", "animated", "video"])
+        .optional()
+        .describe("Sticker format (default: static)"),
+    },
+    execute: (params, bridge) => bridge("create_sticker_set", params),
+    frontends: ["telegram"],
+    tag: "stickers",
+  },
+
+  {
+    name: "add_sticker_to_set",
+    description:
+      "Add a new sticker to an existing sticker pack created by the bot.",
+    schema: {
+      user_id: z.number().describe("Telegram user ID who owns the pack"),
+      name: z.string().describe("Sticker set name (including _by_<botname>)"),
+      file_path: z.string().describe("Path to the sticker image file"),
+      emoji_list: z
+        .array(z.string())
+        .optional()
+        .describe("Emojis for this sticker (default: ['🎨'])"),
+      format: z
+        .enum(["static", "animated", "video"])
+        .optional()
+        .describe("Sticker format (default: static)"),
+    },
+    execute: (params, bridge) => bridge("add_sticker_to_set", params),
+    frontends: ["telegram"],
+    tag: "stickers",
+  },
+
+  {
+    name: "delete_sticker_from_set",
+    description: "Remove a specific sticker from a pack by its file_id.",
+    schema: {
+      sticker_file_id: z
+        .string()
+        .describe(
+          "file_id of the sticker to remove (get from get_sticker_pack)",
+        ),
+    },
+    execute: (params, bridge) => bridge("delete_sticker_from_set", params),
+    frontends: ["telegram"],
+    tag: "stickers",
+  },
+
+  {
+    name: "set_sticker_set_title",
+    description: "Change the title of a sticker pack created by the bot.",
+    schema: {
+      name: z.string().describe("Sticker set name"),
+      title: z.string().describe("New title (1-64 chars)"),
+    },
+    execute: (params, bridge) => bridge("set_sticker_set_title", params),
+    frontends: ["telegram"],
+    tag: "stickers",
+  },
+
+  {
+    name: "delete_sticker_set",
+    description:
+      "Permanently delete an entire sticker pack created by the bot.",
+    schema: {
+      name: z.string().describe("Sticker set name to delete"),
+    },
+    execute: (params, bridge) => bridge("delete_sticker_set", params),
+    frontends: ["telegram"],
+    tag: "stickers",
+  },
+];

package/src/core/tools/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared types for the modular tool system.
+ *
+ * Tool definitions are pure data + execute logic — no MCP imports,
+ * no bridge coupling.  The MCP server consumes these via composeTools().
+ */
+
+import type { ZodRawShape } from "zod";
+
+/** Which frontends a tool is available on.  "all" = every frontend. */
+export type ToolFrontend = "telegram" | "teams" | "terminal" | "all";
+
+/** Domain tags for runtime filtering and grouping. */
+export type ToolTag =
+  | "messaging"
+  | "chat"
+  | "history"
+  | "members"
+  | "media"
+  | "stickers"
+  | "scheduling"
+  | "web";
+
+/** The bridge caller signature — injected into execute(). */
+export type BridgeFunction = (
+  action: string,
+  params: Record<string, unknown>,
+) => Promise<unknown>;
+
+/**
+ * A self-contained tool definition.
+ *
+ * Contains everything needed to register it with an MCP server
+ * AND to know which bridge action it maps to.
+ */
+export interface ToolDefinition {
+  /** MCP tool name (e.g. "send", "react", "fetch_url"). */
+  readonly name: string;
+
+  /** Human-readable description shown to the model. */
+  readonly description: string;
+
+  /** Zod schema shape for the tool's input parameters. */
+  readonly schema: ZodRawShape;
+
+  /**
+   * Execute the tool.  Receives validated params and a bridge caller.
+   * Returns the raw bridge result (wrapped by the MCP layer).
+   */
+  readonly execute: (
+    params: Record<string, unknown>,
+    bridge: BridgeFunction,
+  ) => Promise<unknown>;
+
+  /** Which frontends this tool appears on. Omit for all frontends. */
+  readonly frontends?: readonly ToolFrontend[];
+
+  /** Grouping tag. */
+  readonly tag: ToolTag;
+}

package/src/core/tools/web.ts

@@ -0,0 +1,26 @@
+/**
+ * Web tools — URL fetching.
+ *
+ * Platform-agnostic, available on all frontends.
+ * Web search is handled by the Brave Search MCP server (registered in
+ * src/backend/claude-sdk/index.ts) when configured. URL fetching is provided here via
+ * the `fetch_url` tool, so Claude Code's built-in WebSearch / WebFetch are
+ * disabled in favor of these project-specific replacements.
+ * These can be excluded via composeTools({ excludeTags: ["web"] }).
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+
+export const webTools: ToolDefinition[] = [
+  {
+    name: "fetch_url",
+    description:
+      "Fetch a URL — web pages return text content, image URLs are downloaded to workspace. Use to read articles, download images, or fetch any URL.",
+    schema: {
+      url: z.string().describe("The URL to fetch"),
+    },
+    execute: (params, bridge) => bridge("fetch_url", params),
+    tag: "web",
+  },
+];

package/src/frontend/telegram/actions.ts

@@ -278,7 +278,10 @@ export function createTelegramActionHandler(
       case "send_voice":
       case "send_audio": {
         const filePath = String(body.file_path ?? "");
-        const caption = body.caption ? String(body.caption) : undefined;
+        const caption = body.caption
+          ? markdownToTelegramHtml(String(body.caption))
+          : undefined;
+        const captionParseMode = caption ? ("HTML" as const) : undefined;
         gateway.incrementMessages(chatId);
         if (action === "send_file") {
           const stat = statSync(filePath);
@@ -294,6 +297,7 @@ export function createTelegramActionHandler(
             sent = await withRetry(() =>
               bot.api.sendDocument(chatId, file, {
                 caption,
+                parse_mode: captionParseMode,
                 reply_parameters: rp,
               }),
             );
@@ -302,6 +306,7 @@ export function createTelegramActionHandler(
             sent = await withRetry(() =>
               bot.api.sendPhoto(chatId, file, {
                 caption,
+                parse_mode: captionParseMode,
                 reply_parameters: rp,
               }),
             );
@@ -310,6 +315,7 @@ export function createTelegramActionHandler(
             sent = await withRetry(() =>
               bot.api.sendVideo(chatId, file, {
                 caption,
+                parse_mode: captionParseMode,
                 reply_parameters: rp,
               }),
             );
@@ -318,6 +324,7 @@ export function createTelegramActionHandler(
             sent = await withRetry(() =>
               bot.api.sendAnimation(chatId, file, {
                 caption,
+                parse_mode: captionParseMode,
                 reply_parameters: rp,
               }),
             );
@@ -326,6 +333,7 @@ export function createTelegramActionHandler(
             sent = await withRetry(() =>
               bot.api.sendAudio(chatId, file, {
                 caption,
+                parse_mode: captionParseMode,
                 reply_parameters: rp,
                 title: body.title as string | undefined,
                 performer: body.performer as string | undefined,
@@ -336,6 +344,7 @@ export function createTelegramActionHandler(
             sent = await withRetry(() =>
               bot.api.sendVoice(chatId, file, {
                 caption,
+                parse_mode: captionParseMode,
                 reply_parameters: rp,
               }),
             );