talon-agent 1.2.0 → 1.4.0

package/src/core/tools/history.ts

@@ -0,0 +1,80 @@
+/**
+ * Chat history tools — read, search, get messages, download media.
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+
+export const historyTools: ToolDefinition[] = [
+  {
+    name: "read_chat_history",
+    description:
+      "Read messages from the chat. Use 'before' to go back in time (e.g. '2026-03-13').",
+    schema: {
+      limit: z
+        .number()
+        .optional()
+        .describe("Number of messages (default 30, max 100)"),
+      before: z
+        .string()
+        .optional()
+        .describe("Fetch messages before this date (ISO format)"),
+      offset_id: z.number().optional().describe("Fetch before this message ID"),
+    },
+    execute: (params, bridge) =>
+      bridge("read_history", {
+        limit: params.limit ?? 30,
+        before: params.before,
+        offset_id: params.offset_id,
+      }),
+    frontends: ["telegram"],
+    tag: "history",
+  },
+
+  {
+    name: "search_chat_history",
+    description: "Search messages by keyword.",
+    schema: {
+      query: z.string(),
+      limit: z.number().optional(),
+    },
+    execute: (params, bridge) => bridge("search_history", params),
+    frontends: ["telegram"],
+    tag: "history",
+  },
+
+  {
+    name: "get_user_messages",
+    description: "Get messages from a specific user.",
+    schema: {
+      user_name: z.string(),
+      limit: z.number().optional(),
+    },
+    execute: (params, bridge) => bridge("get_user_messages", params),
+    frontends: ["telegram"],
+    tag: "history",
+  },
+
+  {
+    name: "get_message_by_id",
+    description: "Get a specific message by ID.",
+    schema: { message_id: z.number() },
+    execute: (params, bridge) => bridge("get_message_by_id", params),
+    frontends: ["telegram"],
+    tag: "history",
+  },
+
+  {
+    name: "download_media",
+    description:
+      "Download a photo, document, or other media from a message by its ID. Saves the file to the workspace and returns the file path so you can read/analyze it. Use this when you see a [photo] or [document] in chat history but don't have the file.",
+    schema: {
+      message_id: z
+        .number()
+        .describe("Message ID containing the media to download"),
+    },
+    execute: (params, bridge) => bridge("download_media", params),
+    frontends: ["telegram"],
+    tag: "history",
+  },
+];

package/src/core/tools/index.ts

@@ -0,0 +1,82 @@
+/**
+ * Tool registry — compose filtered tool sets at runtime.
+ *
+ * Import domain modules, expose a single composeTools() API
+ * that backends and the MCP server use to get the right tool set.
+ */
+
+import type { ToolDefinition, ToolFrontend, ToolTag } from "./types.js";
+
+import { messagingTools } from "./messaging.js";
+import { chatTools } from "./chat.js";
+import { historyTools } from "./history.js";
+import { memberTools } from "./members.js";
+import { mediaTools } from "./media.js";
+import { stickerTools } from "./stickers.js";
+import { schedulingTools } from "./scheduling.js";
+import { webTools } from "./web.js";
+
+/** All built-in tool definitions. */
+export const ALL_TOOLS: readonly ToolDefinition[] = [
+  ...messagingTools,
+  ...chatTools,
+  ...historyTools,
+  ...memberTools,
+  ...mediaTools,
+  ...stickerTools,
+  ...schedulingTools,
+  ...webTools,
+];
+
+/** Filter options for composing a tool set. */
+export interface ComposeOptions {
+  /** Include only tools available on this frontend. */
+  frontend?: ToolFrontend;
+  /** Include only tools with these tags. */
+  tags?: ToolTag[];
+  /** Exclude tools with these tags. */
+  excludeTags?: ToolTag[];
+  /** Exclude specific tools by name. */
+  excludeNames?: string[];
+}
+
+/**
+ * Compose a filtered set of tools at runtime.
+ *
+ * When no options are provided, returns ALL_TOOLS unchanged.
+ * Callers describe what they need and get back matching definitions.
+ */
+export function composeTools(options: ComposeOptions = {}): ToolDefinition[] {
+  let tools = [...ALL_TOOLS];
+
+  if (options.frontend) {
+    tools = tools.filter(
+      (t) =>
+        !t.frontends ||
+        t.frontends.includes("all") ||
+        t.frontends.includes(options.frontend!),
+    );
+  }
+
+  if (options.tags?.length) {
+    tools = tools.filter((t) => options.tags!.includes(t.tag));
+  }
+
+  if (options.excludeTags?.length) {
+    tools = tools.filter((t) => !options.excludeTags!.includes(t.tag));
+  }
+
+  if (options.excludeNames?.length) {
+    tools = tools.filter((t) => !options.excludeNames!.includes(t.name));
+  }
+
+  return tools;
+}
+
+// Re-export types for convenience
+export type {
+  ToolDefinition,
+  ToolFrontend,
+  ToolTag,
+  BridgeFunction,
+} from "./types.js";

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