talon-agent 1.3.0 → 1.5.0

package/src/core/tools/mcp-server.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * Unified MCP server — replaces per-backend tools.ts files.
+ *
+ * Reads TALON_FRONTEND env var to compose the right tool set,
+ * then registers them all on a single MCP server over stdio.
+ *
+ * Environment:
+ *   TALON_BRIDGE_URL  — HTTP bridge URL (default: http://127.0.0.1:19876)
+ *   TALON_CHAT_ID     — Current chat ID
+ *   TALON_FRONTEND    — Frontend type: "telegram" | "teams" | "terminal" (default: "telegram")
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { composeTools } from "./index.js";
+import { createBridge, textResult } from "./bridge.js";
+import type { ToolFrontend } from "./types.js";
+
+const VALID_FRONTENDS = new Set<ToolFrontend>([
+  "telegram",
+  "teams",
+  "terminal",
+]);
+const BRIDGE_URL = process.env.TALON_BRIDGE_URL || "http://127.0.0.1:19876";
+const CHAT_ID = process.env.TALON_CHAT_ID || "";
+const rawFrontend = (process.env.TALON_FRONTEND || "telegram") as ToolFrontend;
+
+if (!CHAT_ID) {
+  console.warn(
+    "TALON_CHAT_ID is not set — bridge calls will fail without a valid chat context.",
+  );
+}
+
+if (!VALID_FRONTENDS.has(rawFrontend)) {
+  console.error(
+    `Invalid TALON_FRONTEND: "${rawFrontend}". Must be one of: ${[...VALID_FRONTENDS].join(", ")}`,
+  );
+  process.exit(1);
+}
+const FRONTEND = rawFrontend;
+
+const bridge = createBridge(BRIDGE_URL, CHAT_ID);
+const serverName = `${FRONTEND}-tools`;
+const server = new McpServer({ name: serverName, version: "3.0.0" });
+
+// Compose and register all tools for the active frontend
+const tools = composeTools({ frontend: FRONTEND });
+
+for (const tool of tools) {
+  server.tool(tool.name, tool.description, tool.schema, async (params) =>
+    textResult(await tool.execute(params, bridge)),
+  );
+}
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("MCP server error:", err);
+  process.exit(1);
+});

package/src/core/tools/media.ts

@@ -0,0 +1,23 @@
+/**
+ * Media tools — list recent media in a chat.
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+
+export const mediaTools: ToolDefinition[] = [
+  {
+    name: "list_media",
+    description:
+      "List recent photos, documents, and other media in the current chat with file paths. Use this to find a previously sent photo or file to re-read or reference.",
+    schema: {
+      limit: z
+        .number()
+        .optional()
+        .describe("Number of entries (default 10, max 20)"),
+    },
+    execute: (params, bridge) => bridge("list_media", { limit: params.limit }),
+    frontends: ["telegram"],
+    tag: "media",
+  },
+];

package/src/core/tools/members.ts

@@ -0,0 +1,46 @@
+/**
+ * Member tools — list members, user info, online count, pinned messages.
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+
+export const memberTools: ToolDefinition[] = [
+  {
+    name: "list_chat_members",
+    description: "List chat members with names, IDs, online status, badges.",
+    schema: { limit: z.number().optional() },
+    execute: (params, bridge) =>
+      bridge("list_known_users", { limit: params.limit }),
+    frontends: ["telegram"],
+    tag: "members",
+  },
+
+  {
+    name: "get_member_info",
+    description: "Get detailed info about a user by ID.",
+    schema: { user_id: z.number() },
+    execute: (params, bridge) => bridge("get_member_info", params),
+    frontends: ["telegram"],
+    tag: "members",
+  },
+
+  {
+    name: "online_count",
+    description:
+      "Get how many members are currently online or recently active.",
+    schema: {},
+    execute: (_params, bridge) => bridge("online_count", {}),
+    frontends: ["telegram"],
+    tag: "members",
+  },
+
+  {
+    name: "get_pinned_messages",
+    description: "Get all pinned messages in the current chat.",
+    schema: {},
+    execute: (_params, bridge) => bridge("get_pinned_messages", {}),
+    frontends: ["telegram"],
+    tag: "members",
+  },
+];

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",
+  },
+];