talon-agent 1.3.0 → 1.5.0

package/src/core/gateway-actions.ts

@@ -1,7 +1,7 @@
 /**
  * Shared gateway actions — platform-agnostic handlers that work with any frontend.
  *
- * Handles: cron CRUD, fetch_url, in-memory history queries.
+ * Handles: cron CRUD, fetch_url, plugin reload, in-memory history queries.
  * Returns null if the action isn't recognized (so the gateway delegates to the frontend).
  */
 
@@ -87,93 +87,6 @@ export async function handleSharedAction(
         ),
       };
 
-    // ── Web search (SearXNG) ────────────────────────────────────────────
-
-    case "web_search": {
-      const query = String(body.query ?? "");
-      if (!query) return { ok: false, error: "Missing query" };
-      const limit = Math.min(10, Number(body.limit ?? 5));
-
-      // Try Brave first (if API key configured), fall back to SearXNG
-      const braveKey = process.env.TALON_BRAVE_API_KEY;
-      const searxUrl = process.env.TALON_SEARXNG_URL || "http://localhost:8080";
-
-      type SearchResult = { title: string; url: string; snippet: string };
-      let results: SearchResult[] = [];
-      let provider = "";
-
-      // Brave Search API
-      if (braveKey) {
-        try {
-          const resp = await fetch(
-            `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${limit}`,
-            {
-              signal: AbortSignal.timeout(8_000),
-              headers: {
-                "X-Subscription-Token": braveKey,
-                Accept: "application/json",
-              },
-            },
-          );
-          if (resp.ok) {
-            const data = (await resp.json()) as {
-              web?: {
-                results?: Array<{
-                  title: string;
-                  url: string;
-                  description: string;
-                }>;
-              };
-            };
-            results = (data.web?.results ?? []).map((r) => ({
-              title: r.title,
-              url: r.url,
-              snippet: r.description ?? "",
-            }));
-            provider = "Brave";
-          }
-        } catch {
-          /* fall through to SearXNG */
-        }
-      }
-
-      // SearXNG fallback
-      if (results.length === 0) {
-        try {
-          const resp = await fetch(
-            `${searxUrl}/search?q=${encodeURIComponent(query)}&format=json`,
-            { signal: AbortSignal.timeout(10_000) },
-          );
-          if (resp.ok) {
-            const data = (await resp.json()) as {
-              results?: Array<{ title: string; url: string; content: string }>;
-            };
-            results = (data.results ?? []).slice(0, limit).map((r) => ({
-              title: r.title,
-              url: r.url,
-              snippet: r.content ?? "",
-            }));
-            provider = "SearXNG";
-          }
-        } catch {
-          /* both failed */
-        }
-      }
-
-      if (results.length === 0)
-        return { ok: true, text: `No results for "${query}".` };
-      const formatted = results
-        .map(
-          (r, i) =>
-            `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.snippet.slice(0, 200)}`,
-        )
-        .join("\n\n");
-      return {
-        ok: true,
-        text: `Search results for "${query}" (via ${provider}):\n\n${formatted}`,
-      };
-    }
-
     // ── Web fetch ────────────────────────────────────────────────────────
 
     case "fetch_url": {
@@ -397,6 +310,47 @@ export async function handleSharedAction(
       return { ok: true, text: `Deleted cron job "${job.name}" (${jobId})` };
     }
 
+    // ── Plugin hot-reload ──────────────────────────────────────────────
+    case "reload_plugins": {
+      try {
+        const { reloadPlugins, getPluginPromptAdditions } =
+          await import("./plugin.js");
+        const { rebuildSystemPrompt } = await import("../util/config.js");
+
+        // reloadPlugins reads + validates config internally — no double read.
+        // Frontends are derived from config if not explicitly provided.
+        const { names, config: freshConfig } = await reloadPlugins();
+
+        // Rebuild system prompt on the freshConfig, then update the backend's
+        // live config reference so subsequent messages use the new prompt
+        rebuildSystemPrompt(freshConfig, getPluginPromptAdditions());
+        try {
+          const { updateSystemPrompt } =
+            await import("../backend/claude-sdk/index.js");
+          updateSystemPrompt(freshConfig.systemPrompt);
+        } catch (err) {
+          // Non-fatal — OpenCode backend doesn't expose updateSystemPrompt
+          log(
+            "gateway",
+            `reload_plugins: could not update backend prompt: ${err instanceof Error ? err.message : err}`,
+          );
+        }
+
+        log("gateway", `reload_plugins: ${names.length} plugins loaded`);
+        return {
+          ok: true,
+          text:
+            `Plugins reloaded successfully.\n` +
+            `Loaded (${names.length}): ${names.length > 0 ? names.join(", ") : "(none)"}`,
+        };
+      } catch (err) {
+        return {
+          ok: false,
+          error: `Plugin reload failed: ${err instanceof Error ? err.message : err}`,
+        };
+      }
+    }
+
     default:
       return null; // not a shared action — delegate to frontend
   }

package/src/core/heartbeat.ts

@@ -3,7 +3,7 @@
  *
  * Runs at a configurable interval (default: 60 minutes).
  * The agent reads instructions from ~/.talon/workspace/heartbeat-instructions.md
- * and executes them using filesystem-only tools (no Telegram/MCP access).
+ * and executes them using filesystem tools and all loaded MCP plugins.
  *
  * Modeled after dream.ts but more general-purpose.
  */
@@ -17,6 +17,7 @@ import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
 import { files as pathFiles, dirs } from "../util/paths.js";
 import { log, logError, logWarn } from "../util/log.js";
 import { toYMD } from "../util/time.js";
+import { getPluginMcpServers } from "./plugin.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -282,15 +283,15 @@ async function runHeartbeatAgent(
   const options = {
     model,
     systemPrompt:
-      "You are a background heartbeat agent for Talon. Use only filesystem tools. Follow the user-defined instructions precisely. Be efficient — you have limited time.",
+      "You are a background heartbeat agent for Talon. You have access to filesystem tools and all registered MCP plugins. Follow the user-defined instructions precisely. Be efficient — you have limited time.",
     cwd: workspace,
     permissionMode: "bypassPermissions" as const,
     allowDangerouslySkipPermissions: true,
     ...(configRef.claudeBinary
       ? { pathToClaudeCodeExecutable: configRef.claudeBinary }
       : {}),
-    // No MCP servers — filesystem tools only
-    mcpServers: {},
+    // Load all registered plugin MCP servers (excludes frontend-specific tools like telegram)
+    mcpServers: getPluginMcpServers("", "heartbeat"),
     disallowedTools: [
       "EnterPlanMode",
       "ExitPlanMode",
@@ -315,10 +316,12 @@ async function runHeartbeatAgent(
   // running lock is not released while the subprocess is still active.
   let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
   const timeoutPromise = new Promise<never>((_, reject) => {
-    timeoutHandle = setTimeout(
+    const t = setTimeout(
       () => reject(new Error("Heartbeat agent timed out")),
       HEARTBEAT_TIMEOUT_MS,
     );
+    t.unref(); // Don't prevent Node.js from exiting cleanly during shutdown
+    timeoutHandle = t;
   });
 
   const agentPromise = (async () => {

package/src/core/plugin.ts

@@ -18,6 +18,7 @@ import { resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { log, logError, logWarn } from "../util/log.js";
 import type { ActionResult } from "./types.js";
+import type { TalonConfig } from "../util/config.js";
 
 // ── Plugin interfaces ──────────────────────────────────────────────────────
 
@@ -158,6 +159,18 @@ class PluginRegistry {
       }
     }
   }
+
+  /** Destroy all plugins, clean up env vars, and clear the registry. Used by hot-reload. */
+  async destroyAndClear(): Promise<void> {
+    // Clean up env vars set by plugins before destroying
+    for (const { envVars } of this.plugins) {
+      for (const key of Object.keys(envVars)) {
+        delete process.env[key];
+      }
+    }
+    await this.destroyAll();
+    this.plugins.length = 0;
+  }
 }
 
 // Module-level singleton
@@ -359,6 +372,140 @@ export async function destroyPlugins(): Promise<void> {
   await registry.destroyAll();
 }
 
+/**
+ * Load built-in plugins (GitHub, MemPalace, Playwright) based on config flags.
+ * Shared by both bootstrap and hot-reload to avoid duplication.
+ */
+export async function loadBuiltinPlugins(config: TalonConfig): Promise<void> {
+  const github = config.github;
+  if (github?.enabled) {
+    try {
+      const { createGitHubPlugin } = await import("../plugins/github/index.js");
+      const gh = createGitHubPlugin({ token: github.token });
+      const ghConfig = github as unknown as Record<string, unknown>;
+      registerPlugin(gh, ghConfig);
+      if (registry.getByName("github")) {
+        await Promise.race([
+          gh.init?.(ghConfig),
+          new Promise((_, reject) =>
+            setTimeout(
+              () => reject(new Error("GitHub init timed out after 15s")),
+              15_000,
+            ),
+          ),
+        ]);
+      }
+    } catch (err) {
+      logError(
+        "plugin",
+        `GitHub init: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+
+  const mempalace = config.mempalace;
+  if (mempalace?.enabled) {
+    try {
+      const { createMempalacePlugin } =
+        await import("../plugins/mempalace/index.js");
+      const { dirs, files: pf } = await import("../util/paths.js");
+      const pythonPath = mempalace.pythonPath ?? pf.mempalacePython;
+      const palacePath = mempalace.palacePath ?? dirs.palace;
+      const mp = createMempalacePlugin({ pythonPath, palacePath });
+      const mpConfig = mempalace as unknown as Record<string, unknown>;
+      registerPlugin(mp, mpConfig);
+      if (registry.getByName("mempalace")) {
+        await Promise.race([
+          mp.init?.(mpConfig),
+          new Promise((_, reject) =>
+            setTimeout(
+              () => reject(new Error("MemPalace init timed out after 30s")),
+              30_000,
+            ),
+          ),
+        ]);
+      }
+    } catch (err) {
+      logError(
+        "plugin",
+        `MemPalace init: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+
+  const playwright = config.playwright;
+  if (playwright?.enabled) {
+    try {
+      const { createPlaywrightPlugin } =
+        await import("../plugins/playwright/index.js");
+      const pw = createPlaywrightPlugin({
+        browser: playwright.browser,
+        headless: playwright.headless,
+      });
+      const pwConfig = playwright as unknown as Record<string, unknown>;
+      registerPlugin(pw, pwConfig);
+      if (registry.getByName("playwright")) {
+        await Promise.race([
+          pw.init?.(pwConfig),
+          new Promise((_, reject) =>
+            setTimeout(
+              () => reject(new Error("Playwright init timed out after 15s")),
+              15_000,
+            ),
+          ),
+        ]);
+      }
+    } catch (err) {
+      logError(
+        "plugin",
+        `Playwright init: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+}
+
+/**
+ * Hot-reload all plugins: destroy current plugins, re-read config via
+ * the validated loadConfig() path, re-load everything (external + built-in).
+ * Returns the loaded plugin names and the config that was used.
+ *
+ * Throws on config parse/validation failure so the gateway can report an error.
+ *
+ * Does NOT restart the main process, Claude session, or bot connection.
+ * Active conversations continue uninterrupted — new MCP servers spawn
+ * automatically on the next tool call.
+ */
+export async function reloadPlugins(
+  activeFrontends?: string[],
+): Promise<{ names: string[]; config: TalonConfig }> {
+  // Validate config BEFORE tearing down existing plugins.
+  // If the config is malformed the error propagates and current plugins stay intact.
+  const { loadConfig, getFrontends } = await import("../util/config.js");
+  const config = loadConfig();
+
+  // Derive frontends from config if not explicitly provided
+  const frontends = activeFrontends ?? getFrontends(config);
+
+  // Config is valid — safe to destroy current plugins now
+  log("plugin", "Hot-reload: destroying current plugins...");
+  await registry.destroyAndClear();
+
+  // Re-load external plugins
+  if (config.plugins.length > 0) {
+    await loadPlugins(config.plugins, frontends);
+  }
+
+  // Re-load built-in plugins using shared helper
+  await loadBuiltinPlugins(config);
+
+  const names = registry.all.map((p) => p.plugin.name);
+  log(
+    "plugin",
+    `Hot-reload complete: ${names.length} plugins loaded [${names.join(", ")}]`,
+  );
+  return { names, config };
+}
+
 /**
  * Register a built-in plugin directly (bypasses filesystem loader).
  * Used for tightly-integrated plugins like mempalace that are configured

package/src/core/tools/admin.ts

@@ -0,0 +1,22 @@
+/**
+ * Admin tools — plugin management and system operations.
+ *
+ * These tools operate on the Talon runtime itself rather than
+ * messaging or content. Available on all frontends.
+ */
+
+import type { ToolDefinition } from "./types.js";
+
+export const adminTools: ToolDefinition[] = [
+  {
+    name: "reload_plugins",
+    description: `Hot-reload all MCP plugins without restarting the bot or disrupting active sessions. Re-reads ~/.talon/config.json, tears down current plugin instances, cleans up their env vars, and loads fresh ones.
+
+Use this after editing the plugin config (adding, removing, or updating plugin entries) to apply changes without downtime. Active conversations continue uninterrupted — new plugin tools become available on the next tool call.
+
+Returns the list of successfully loaded plugins.`,
+    schema: {},
+    execute: (_params, bridge) => bridge("reload_plugins", {}),
+    tag: "admin",
+  },
+];

package/src/core/tools/bridge.ts

@@ -0,0 +1,40 @@
+/**
+ * Bridge utilities — shared by the unified MCP server.
+ *
+ * Extracted from the old per-backend tools.ts files so there's
+ * exactly one copy of callBridge / textResult.
+ */
+
+import type { BridgeFunction } from "./types.js";
+
+/** Create a bridge caller bound to a specific URL and chat. */
+export function createBridge(
+  bridgeUrl: string,
+  chatId: string,
+): BridgeFunction {
+  return async (action, params) => {
+    const resp = await fetch(`${bridgeUrl}/action`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ action, ...params, _chatId: chatId }),
+      signal: AbortSignal.timeout(120_000),
+    });
+    if (!resp.ok) {
+      const text = await resp.text();
+      throw new Error(`Bridge error (${resp.status}): ${text}`);
+    }
+    return resp.json();
+  };
+}
+
+/** Wrap a bridge result into the MCP content format. */
+export function textResult(result: unknown): {
+  content: Array<{ type: "text"; text: string }>;
+} {
+  const r = result as { text?: string; error?: string };
+  return {
+    content: [
+      { type: "text" as const, text: r.text ?? JSON.stringify(result) },
+    ],
+  };
+}

package/src/core/tools/chat.ts

@@ -0,0 +1,52 @@
+/**
+ * Chat info tools — metadata, admins, settings.
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+
+export const chatTools: ToolDefinition[] = [
+  {
+    name: "get_chat_info",
+    description: "Get chat title, type, member count.",
+    schema: {},
+    execute: (_params, bridge) => bridge("get_chat_info", {}),
+    tag: "chat",
+  },
+
+  {
+    name: "get_chat_admins",
+    description: "List chat administrators.",
+    schema: {},
+    execute: (_params, bridge) => bridge("get_chat_admins", {}),
+    frontends: ["telegram"],
+    tag: "chat",
+  },
+
+  {
+    name: "get_chat_member_count",
+    description: "Get total member count.",
+    schema: {},
+    execute: (_params, bridge) => bridge("get_chat_member_count", {}),
+    frontends: ["telegram"],
+    tag: "chat",
+  },
+
+  {
+    name: "set_chat_title",
+    description: "Change chat title (admin).",
+    schema: { title: z.string() },
+    execute: (params, bridge) => bridge("set_chat_title", params),
+    frontends: ["telegram"],
+    tag: "chat",
+  },
+
+  {
+    name: "set_chat_description",
+    description: "Change chat description (admin).",
+    schema: { description: z.string() },
+    execute: (params, bridge) => bridge("set_chat_description", params),
+    frontends: ["telegram"],
+    tag: "chat",
+  },
+];

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,84 @@
+/**
+ * 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";
+import { adminTools } from "./admin.js";
+
+/** All built-in tool definitions. */
+export const ALL_TOOLS: readonly ToolDefinition[] = [
+  ...messagingTools,
+  ...chatTools,
+  ...historyTools,
+  ...memberTools,
+  ...mediaTools,
+  ...stickerTools,
+  ...schedulingTools,
+  ...webTools,
+  ...adminTools,
+];
+
+/** 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";