talon-agent 1.2.0 → 1.4.0

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

package/src/frontend/telegram/handlers.ts

@@ -5,11 +5,7 @@
 
 import type { Bot, Context } from "grammy";
 import type { TalonConfig } from "../../util/config.js";
-import {
-  splitMessage,
-  markdownToTelegramHtml,
-  escapeHtml,
-} from "./formatting.js";
+import { markdownToTelegramHtml, escapeHtml } from "./formatting.js";
 import { execute } from "../../core/dispatcher.js";
 import { classify, friendlyMessage } from "../../core/errors.js";
 import {
@@ -391,7 +387,6 @@ const messageQueues = new Map<
     messages: QueuedMessage[];
     timer: ReturnType<typeof setTimeout>;
     bot: Bot;
-    config: TalonConfig;
     numericChatId: number;
     queuedReactionMsgIds: number[];
   }
@@ -446,7 +441,6 @@ function isUserRateLimited(senderId: number): boolean {
  */
 function enqueueMessage(
   bot: Bot,
-  config: TalonConfig,
   chatId: string,
   numericChatId: number,
   msg: QueuedMessage,
@@ -474,7 +468,6 @@ function enqueueMessage(
     messages: [msg],
     timer: setTimeout(() => flushQueue(chatId), DEBOUNCE_MS),
     bot,
-    config,
     numericChatId,
     queuedReactionMsgIds: [] as number[],
   };
@@ -486,7 +479,7 @@ async function flushQueue(chatId: string): Promise<void> {
   if (!entry) return;
   messageQueues.delete(chatId);
 
-  const { messages, bot, config, numericChatId, queuedReactionMsgIds } = entry;
+  const { messages, bot, numericChatId, queuedReactionMsgIds } = entry;
 
   // Clear hourglass reactions on queued messages now that we're processing
   for (const msgId of queuedReactionMsgIds) {
@@ -516,7 +509,6 @@ async function flushQueue(chatId: string): Promise<void> {
   try {
     await processAndReply({
       bot,
-      config,
       chatId,
       numericChatId,
       replyToId: last.replyToId,
@@ -550,7 +542,6 @@ async function flushQueue(chatId: string): Promise<void> {
         await new Promise((r) => setTimeout(r, delayMs));
         await processAndReply({
           bot,
-          config,
           chatId,
           numericChatId,
           replyToId: last.replyToId,
@@ -621,7 +612,6 @@ async function sendHtml(
  */
 type ProcessAndReplyParams = {
   bot: Bot;
-  config: TalonConfig;
   chatId: string | number;
   numericChatId: number;
   replyToId: number;
@@ -692,7 +682,6 @@ function createStreamCallbacks(
 async function processAndReply(params: ProcessAndReplyParams): Promise<void> {
   const {
     bot,
-    config,
     chatId,
     numericChatId,
     replyToId,
@@ -864,7 +853,7 @@ async function handleMediaMessage(
 
     const prompt = promptParts.join("\n");
 
-    enqueueMessage(bot, config, chatId, ctx.chat.id, {
+    enqueueMessage(bot, chatId, ctx.chat.id, {
       prompt,
       replyToId: ctx.message.message_id,
       messageId: ctx.message.message_id,
@@ -920,7 +909,7 @@ export async function handleTextMessage(
   );
   const prompt = fwdCtx + replyCtx + replyPhotoCtx + (ctx.message.text ?? "");
 
-  enqueueMessage(bot, config, chatId, ctx.chat.id, {
+  enqueueMessage(bot, chatId, ctx.chat.id, {
     prompt,
     replyToId: ctx.message.message_id,
     messageId: ctx.message.message_id,
@@ -1040,7 +1029,7 @@ export async function handleStickerMessage(
     .filter(Boolean)
     .join("\n");
 
-  enqueueMessage(bot, config, chatId, ctx.chat.id, {
+  enqueueMessage(bot, chatId, ctx.chat.id, {
     prompt,
     replyToId: ctx.message.message_id,
     messageId: ctx.message.message_id,
@@ -1185,7 +1174,6 @@ export async function handleCallbackQuery(
 
     await processAndReply({
       bot,
-      config,
       chatId,
       numericChatId,
       replyToId,

package/src/plugins/github/index.ts

@@ -0,0 +1,106 @@
+/**
+ * GitHub plugin — GitHub API access via the official GitHub MCP server.
+ *
+ * Registers the GitHub MCP server (Docker image: ghcr.io/github/github-mcp-server),
+ * giving the agent access to repository management, issues, PRs, code search, etc.
+ *
+ * Configuration in ~/.talon/config.json:
+ *   "github": {
+ *     "enabled": true,
+ *     "token": "ghp_..."      // optional, defaults to `gh auth token` output
+ *   }
+ */
+
+import { execFileSync } from "node:child_process";
+import type { TalonPlugin } from "../../core/plugin.js";
+import { log, logWarn } from "../../util/log.js";
+
+/**
+ * Resolve a GitHub personal access token.
+ * Priority: explicit config > `gh auth token` CLI.
+ */
+function resolveToken(configToken?: string): string | undefined {
+  const trimmed = configToken?.trim();
+  if (trimmed) return trimmed;
+  try {
+    return execFileSync("gh", ["auth", "token"], {
+      timeout: 5_000,
+      stdio: ["pipe", "pipe", "pipe"],
+    })
+      .toString("utf-8")
+      .trim();
+  } catch {
+    return undefined;
+  }
+}
+
+export function createGitHubPlugin(config: { token?: string }): TalonPlugin {
+  const token = resolveToken(config.token);
+
+  return {
+    name: "github",
+    description: "GitHub API access via the official GitHub MCP server",
+    version: "1.0.0",
+
+    mcpServer: {
+      command: "docker",
+      args: [
+        "run",
+        "--rm",
+        "-i",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server",
+      ],
+    },
+
+    validateConfig() {
+      const errors: string[] = [];
+
+      if (!token) {
+        errors.push(
+          'No GitHub token found. Set "token" in github config or run `gh auth login`.',
+        );
+      }
+
+      // Check Docker is available
+      try {
+        execFileSync("docker", ["info"], {
+          timeout: 10_000,
+          stdio: "pipe",
+        });
+      } catch {
+        errors.push(
+          "Docker is not available or not running. The GitHub MCP server requires Docker.",
+        );
+      }
+
+      return errors.length > 0 ? errors : undefined;
+    },
+
+    async init() {
+      // Verify the Docker image exists locally
+      try {
+        execFileSync(
+          "docker",
+          ["image", "inspect", "ghcr.io/github/github-mcp-server"],
+          { timeout: 10_000, stdio: "pipe" },
+        );
+        log("github", "Docker image verified");
+      } catch {
+        logWarn(
+          "github",
+          "Docker image not found locally — will pull on first use (may be slow)",
+        );
+      }
+
+      log("github", "Ready");
+    },
+
+    getEnvVars() {
+      return {
+        ...(token ? { GITHUB_PERSONAL_ACCESS_TOKEN: token } : {}),
+      };
+    },
+  };
+}

package/src/plugins/mempalace/index.ts

@@ -0,0 +1,147 @@
+/**
+ * MemPalace plugin — structured long-term memory with vector search.
+ *
+ * Registers the mempalace Python MCP server, giving the agent access to
+ * semantic memory search, knowledge graph operations, and diary entries.
+ *
+ * Configuration in ~/.talon/config.json:
+ *   "mempalace": {
+ *     "enabled": true,
+ *     "palacePath": "/path/to/palace",   // optional, defaults to ~/.talon/workspace/palace/
+ *     "pythonPath": "/path/to/python"     // optional, defaults to mempalace venv python (bin/python on Unix, Scripts/python.exe on Windows)
+ *   }
+ */
+
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { execFile as execFileCb, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+import type { TalonPlugin } from "../../core/plugin.js";
+import { log, logWarn } from "../../util/log.js";
+import { dirs } from "../../util/paths.js";
+
+const execFile = promisify(execFileCb);
+
+/** Load from ~/.talon/prompts/ (user-customisable, seeded on first run) */
+const PROMPT_PATH = resolve(dirs.prompts, "mempalace.md");
+
+/**
+ * Create a mempalace plugin instance with resolved paths.
+ * Uses a factory because MCP server command/args depend on runtime config.
+ */
+export function createMempalacePlugin(config: {
+  pythonPath: string;
+  palacePath: string;
+}): TalonPlugin {
+  const { pythonPath, palacePath } = config;
+
+  return {
+    name: "mempalace",
+    description:
+      "Memory palace — structured long-term memory with vector search",
+    version: "1.0.0",
+
+    mcpServer: {
+      command: pythonPath,
+      args: ["-m", "mempalace.mcp_server", "--palace", palacePath],
+    },
+
+    validateConfig() {
+      const errors: string[] = [];
+      if (!existsSync(pythonPath)) {
+        errors.push(
+          `Python binary not found at ${pythonPath}. Create or select a Python environment, set "pythonPath" to that interpreter, then run: ${pythonPath} -m pip install mempalace`,
+        );
+        return errors;
+      }
+
+      // Verify mempalace.mcp_server is importable (the actual module spawned by MCP)
+      try {
+        execFileSync(pythonPath, ["-c", "import mempalace.mcp_server"], {
+          timeout: 15_000,
+          stdio: "pipe",
+        });
+      } catch (err: unknown) {
+        const execErr =
+          err && typeof err === "object"
+            ? (err as {
+                code?: string;
+                signal?: string;
+                killed?: boolean;
+                stderr?: string | Buffer;
+              })
+            : undefined;
+        const code = execErr?.code;
+        if (code === "ENOENT" || code === "EACCES" || code === "EPERM") {
+          errors.push(
+            `Cannot execute Python at ${pythonPath} (${code}). Check that the path is correct and the binary is executable.`,
+          );
+        } else if (code === "ETIMEDOUT" || execErr?.killed || execErr?.signal) {
+          errors.push(
+            `Python import check timed out or was killed. The interpreter at ${pythonPath} may be unresponsive.`,
+          );
+        } else {
+          const stderr =
+            typeof execErr?.stderr === "string"
+              ? execErr.stderr.trim()
+              : Buffer.isBuffer(execErr?.stderr)
+                ? execErr.stderr.toString("utf-8").trim()
+                : "";
+          errors.push(
+            `mempalace package not installed or mcp_server submodule missing. Run: ${pythonPath} -m pip install mempalace${stderr ? `. Details: ${stderr}` : ""}`,
+          );
+        }
+      }
+
+      return errors.length > 0 ? errors : undefined;
+    },
+
+    async init() {
+      // Ensure palace directory exists
+      if (!existsSync(palacePath)) {
+        mkdirSync(palacePath, { recursive: true });
+        log("mempalace", `Created palace directory: ${palacePath}`);
+      }
+
+      // Quick smoke test — verify mempalace can import and access the palace path
+      try {
+        const { stdout } = await execFile(
+          pythonPath,
+          [
+            "-c",
+            `import mempalace; print(f"mempalace {mempalace.__version__}" if hasattr(mempalace, "__version__") else "mempalace ok")`,
+          ],
+          { timeout: 15_000 },
+        );
+        log("mempalace", stdout.trim() || "Module verified");
+      } catch {
+        // Non-fatal — MCP server handles lazy init
+        log(
+          "mempalace",
+          "Module import check skipped — MCP server will initialize on first use",
+        );
+      }
+
+      log("mempalace", `Ready (palace: ${palacePath})`);
+    },
+
+    getEnvVars() {
+      return {
+        MEMPALACE_PALACE_PATH: palacePath,
+      };
+    },
+
+    getSystemPromptAddition() {
+      try {
+        const template = readFileSync(PROMPT_PATH, "utf-8");
+        return template.replace(/\{\{palacePath\}\}/g, palacePath);
+      } catch (err) {
+        logWarn(
+          "mempalace",
+          `Failed to load prompt from ${PROMPT_PATH}: ${err instanceof Error ? err.message : err}`,
+        );
+        return `## MemPalace — Long-term Memory\n\nPalace location: \`${palacePath}\``;
+      }
+    },
+  };
+}