fathom-mcp 0.4.12 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fathom-mcp",
-  "version": "0.4.12",
+  "version": "0.5.0",
   "description": "MCP server for Fathom — vault operations, search, rooms, and cross-workspace communication",
   "type": "module",
   "bin": {
@@ -23,7 +23,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.0",
+    "ws": "^8.18.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.3",

package/src/index.js

@@ -20,6 +20,7 @@ import {
 
 import { resolveConfig } from "./config.js";
 import { createClient } from "./server-client.js";
+import { createWSConnection } from "./ws-connection.js";
 import {
   handleVaultWrite,
   handleVaultAppend,
@@ -32,6 +33,7 @@ import {
 
 const config = resolveConfig();
 const client = createClient(config);
+let wsConn = null;
 
 // --- Tool definitions --------------------------------------------------------
 
@@ -227,9 +229,8 @@ const tools = [
       "to the latest message. Default: 60 minutes before the latest message. Use start to look " +
       "further back. Example: minutes=15, start=120 returns 15 minutes of conversation starting " +
       "2 hours before the latest message. Response includes window metadata with has_older flag " +
-      "for pseudo-pagination. For virtual rooms (dm:*, mentions:*), messages are consumed on read — " +
-      "deleted after being returned. Use mark_read=false to peek without consuming. " +
-      "For regular rooms, automatically marks as read unless mark_read=false.",
+      "for pseudo-pagination. All rooms are persistent — messages are never deleted on read. " +
+      "Automatically marks the room as read unless mark_read=false.",
     inputSchema: {
       type: "object",
       properties: {
@@ -246,8 +247,8 @@ const tools = [
     description:
       "List all rooms with activity summary — message count, last activity time, last sender, " +
       "description, and per-room unread_count for this workspace. Use to discover active rooms " +
-      "and see which have new messages. Virtual rooms (dm:{workspace}, mentions:{workspace}) " +
-      "appear only for the owning workspace and disappear when empty.",
+      "and see which have new messages. DM rooms (dm:a+b) are filtered by workspace param — " +
+      "only participants see them. Mention rooms (mentions:{workspace}) visible only to the target workspace.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -282,10 +283,9 @@ const tools = [
   {
     name: "fathom_send",
     description:
-      "Send a message to another workspace's agent instance — stored in their dm:{workspace} " +
-      "virtual room. Use fathom_workspaces first to discover valid targets. Recipients see DMs " +
-      "via fathom_room_list and consume them with fathom_room_read. " +
-      "Message format: 'Message from workspace ({from}): {message}'",
+      "Send a message to another workspace's agent instance — stored in a shared dm:a+b room " +
+      "visible to both participants. Use fathom_workspaces first to discover valid targets. " +
+      "DMs are persistent and appear in both participants' room lists via fathom_room_list.",
     inputSchema: {
       type: "object",
       properties: {
@@ -344,6 +344,99 @@ const tools = [
       required: [],
     },
   },
+  {
+    name: "fathom_routine_list",
+    description:
+      "List all ping routines for a workspace with their status, intervals, " +
+      "enabled state, and next fire time. Use this to see what routines exist " +
+      "before updating or deleting them.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace: WORKSPACE_PROP,
+      },
+      required: [],
+    },
+  },
+  {
+    name: "fathom_routine_update",
+    description:
+      "Update an existing ping routine. Only provided fields are changed — " +
+      "omitted fields keep their current values. Use fathom_routine_list first " +
+      "to find the routine_id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        routine_id: { type: "string", description: "The routine ID to update. Use fathom_routine_list to find IDs." },
+        name: { type: "string", description: "New routine name." },
+        enabled: { type: "boolean", description: "Enable or disable the routine." },
+        interval_minutes: { type: "integer", description: "New interval in minutes.", minimum: 1 },
+        single_fire: { type: "boolean", description: "Auto-disable after firing once." },
+        workspace: WORKSPACE_PROP,
+        context_sources: {
+          type: "object",
+          description: "What to inject on each ping.",
+          properties: {
+            time: { type: "boolean", description: "Include current time/date. Default: true." },
+            scripts: {
+              type: "array",
+              description: "Shell commands to run and inject output.",
+              items: {
+                type: "object",
+                properties: {
+                  label: { type: "string" },
+                  command: { type: "string" },
+                  enabled: { type: "boolean" },
+                },
+              },
+            },
+            texts: {
+              type: "array",
+              description: "Static text blocks to inject.",
+              items: {
+                type: "object",
+                properties: {
+                  label: { type: "string" },
+                  content: { type: "string" },
+                  enabled: { type: "boolean" },
+                },
+              },
+            },
+          },
+        },
+      },
+      required: ["routine_id"],
+    },
+  },
+  {
+    name: "fathom_routine_delete",
+    description:
+      "Delete a ping routine permanently. Use fathom_routine_list first to find " +
+      "the routine_id. This cannot be undone — create a new routine if needed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        routine_id: { type: "string", description: "The routine ID to delete." },
+        workspace: WORKSPACE_PROP,
+      },
+      required: ["routine_id"],
+    },
+  },
+  {
+    name: "fathom_routine_fire",
+    description:
+      "Fire a ping routine immediately, regardless of its schedule. Non-blocking — " +
+      "returns immediately while the routine fires in the background. The routine's " +
+      "next scheduled fire time is not affected.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        routine_id: { type: "string", description: "The routine ID to fire." },
+        workspace: WORKSPACE_PROP,
+      },
+      required: ["routine_id"],
+    },
+  },
 ];
 
 // --- Vault routing by mode ---------------------------------------------------
@@ -381,6 +474,77 @@ function resolveVault(args) {
   }
 }
 
+// --- Telegram tools (primary agent only) -------------------------------------
+
+const telegramTools = [
+  {
+    name: "fathom_telegram_contacts",
+    description:
+      "List Telegram contacts who have messaged. Returns name, username, chat_id, " +
+      "last_message time, and unread count.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "fathom_telegram_read",
+    description:
+      "Read recent Telegram messages from a contact. Same windowing as fathom_room_read — " +
+      "anchored to latest message, default 60 minutes. Use start to look further back.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        contact: { type: "string", description: "Contact name, @username, or chat_id" },
+        minutes: { type: "number", description: "Window duration in minutes. Default: 60." },
+        start: { type: "number", description: "Offset in minutes from latest message. Default: 0." },
+        mark_read: { type: "boolean", description: "Mark messages as read. Default: true." },
+      },
+      required: ["contact"],
+    },
+  },
+  {
+    name: "fathom_telegram_send",
+    description:
+      "Send a Telegram message to a contact via the persistent Telethon client.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        contact: { type: "string", description: "Contact name, @username, or chat_id" },
+        message: { type: "string", description: "Message text to send" },
+      },
+      required: ["contact", "message"],
+    },
+  },
+  {
+    name: "fathom_telegram_image",
+    description:
+      "Read a Telegram message's attached image and return it as base64 so Claude can perceive it. " +
+      "Use after fathom_telegram_read shows a message has media: true. " +
+      "Supports jpg, jpeg, png, gif, webp. Max 5MB.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        message_id: { type: "number", description: "The message ID from fathom_telegram_read results" },
+      },
+      required: ["message_id"],
+    },
+  },
+  {
+    name: "fathom_telegram_send_image",
+    description:
+      "Send an image to a Telegram contact via the persistent Telethon client. " +
+      "Provide an absolute file path to a local image. Optionally include a caption. " +
+      "Contact can be a name, @username, or chat_id number.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        contact: { type: "string", description: "Contact name, @username, or chat_id" },
+        file_path: { type: "string", description: "Absolute path to the image file to send" },
+        caption: { type: "string", description: "Optional caption text for the image (max 1024 chars)" },
+      },
+      required: ["contact", "file_path"],
+    },
+  },
+];
+
 // --- Server setup & dispatch -------------------------------------------------
 
 const server = new Server(
@@ -388,7 +552,19 @@ const server = new Server(
   { capabilities: { tools: {} } },
 );
 
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  // Telegram tools only visible to the primary (default) workspace
+  let isPrimary = false;
+  try {
+    const settings = await client.getSettings();
+    const primaryAgent = settings.default_workspace;
+    isPrimary = config.workspace === primaryAgent;
+  } catch {
+    // If settings unavailable, hide telegram tools
+  }
+  const allTools = [...tools, ...(isPrimary ? telegramTools : [])];
+  return { tools: allTools };
+});
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
@@ -543,6 +719,118 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       result = await client.createRoutine(routineParams, args.workspace || config.workspace);
       break;
     }
+    case "fathom_routine_list":
+      result = await client.listRoutines(args.workspace || config.workspace);
+      break;
+    case "fathom_routine_update": {
+      const updateParams = {};
+      if (args.name != null) updateParams.name = args.name;
+      if (args.enabled != null) updateParams.enabled = args.enabled;
+      if (args.interval_minutes != null) updateParams.intervalMinutes = args.interval_minutes;
+      if (args.single_fire != null) updateParams.singleFire = args.single_fire;
+      if (args.context_sources != null) updateParams.contextSources = args.context_sources;
+      result = await client.updateRoutine(args.routine_id, updateParams, args.workspace || config.workspace);
+      break;
+    }
+    case "fathom_routine_delete":
+      result = await client.deleteRoutine(args.routine_id, args.workspace || config.workspace);
+      break;
+    case "fathom_routine_fire":
+      result = await client.fireRoutine(args.routine_id, args.workspace || config.workspace);
+      break;
+    // --- Telegram ---
+    case "fathom_telegram_contacts":
+      result = await client.telegramContacts(config.workspace);
+      break;
+    case "fathom_telegram_read": {
+      // Resolve contact name to chat_id via contacts list
+      const contacts = await client.telegramContacts(config.workspace);
+      const contactList = contacts?.contacts || [];
+      const contactArg = (args.contact || "").trim();
+      let chatId = parseInt(contactArg, 10);
+      if (isNaN(chatId)) {
+        const lower = contactArg.toLowerCase().replace(/^@/, "");
+        const match = contactList.find(c =>
+          (c.username || "").toLowerCase() === lower ||
+          (c.first_name || "").toLowerCase() === lower ||
+          (c.first_name || "").toLowerCase().includes(lower)
+        );
+        chatId = match ? match.chat_id : null;
+      }
+      if (!chatId) {
+        result = { error: `Contact not found: ${contactArg}. Use fathom_telegram_contacts to list known contacts.` };
+      } else {
+        result = await client.telegramRead(
+          chatId, args.minutes, args.start,
+          args.mark_read !== false ? config.workspace : undefined,
+          args.mark_read,
+        );
+      }
+      break;
+    }
+    case "fathom_telegram_send": {
+      const sendContacts = await client.telegramContacts(config.workspace);
+      const sendList = sendContacts?.contacts || [];
+      const sendArg = (args.contact || "").trim();
+      let sendChatId = parseInt(sendArg, 10);
+      if (isNaN(sendChatId)) {
+        const lower = sendArg.toLowerCase().replace(/^@/, "");
+        const match = sendList.find(c =>
+          (c.username || "").toLowerCase() === lower ||
+          (c.first_name || "").toLowerCase() === lower ||
+          (c.first_name || "").toLowerCase().includes(lower)
+        );
+        sendChatId = match ? match.chat_id : null;
+      }
+      if (!sendChatId) {
+        result = { error: `Contact not found: ${sendArg}. Use fathom_telegram_contacts to list known contacts.` };
+      } else {
+        result = await client.telegramSend(sendChatId, args.message);
+      }
+      break;
+    }
+    case "fathom_telegram_image": {
+      const msgId = args.message_id;
+      if (!msgId) {
+        result = { error: "message_id is required" };
+      } else {
+        // Check local WebSocket cache first (avoids HTTP round-trip for pushed images)
+        const cached = wsConn?.getCachedImage(msgId);
+        if (cached) {
+          result = { _image: true, data: cached.data, mimeType: cached.mimeType };
+        } else {
+          result = await client.telegramImage(msgId);
+          if (result?.data && result?.mimeType) {
+            result = { _image: true, data: result.data, mimeType: result.mimeType };
+          }
+        }
+      }
+      break;
+    }
+    case "fathom_telegram_send_image": {
+      const imgContactArg = args.contact;
+      if (!imgContactArg) { result = { error: "contact is required" }; break; }
+      if (!args.file_path) { result = { error: "file_path is required" }; break; }
+
+      const imgContacts = await client.telegramContacts(config.workspace);
+      const imgList = imgContacts?.contacts || [];
+      let imgChatId = parseInt(imgContactArg, 10);
+      if (isNaN(imgChatId)) {
+        const lower = imgContactArg.toLowerCase().replace(/^@/, "");
+        const match = imgList.find(c =>
+          (c.username || "").toLowerCase() === lower ||
+          (c.first_name || "").toLowerCase() === lower ||
+          (c.first_name || "").toLowerCase().includes(lower)
+        );
+        imgChatId = match ? match.chat_id : null;
+      }
+      if (!imgChatId) {
+        result = { error: `Contact not found: ${imgContactArg}. Use fathom_telegram_contacts to list known contacts.` };
+      } else {
+        result = await client.telegramSendImage(imgChatId, args.file_path, args.caption);
+      }
+      break;
+    }
     default:
       result = { error: `Unknown tool: ${name}` };
   }
@@ -628,7 +916,12 @@ async function main() {
   // Startup sync for synced mode (fire-and-forget)
   startupSync().catch(() => {});
 
-  // Heartbeat — report liveness to server every 30s
+  // WebSocket push channel — receives server-pushed messages
+  if (config.server && config.workspace && config.apiKey) {
+    wsConn = createWSConnection(config);
+  }
+
+  // Heartbeat — report liveness to server every 30s (kept for backwards compat)
   if (config.server && config.workspace) {
     const beat = () =>
       client

package/src/server-client.js

@@ -205,6 +205,37 @@ export function createClient(config) {
     });
   }
 
+  async function listRoutines(ws) {
+    return request("GET", "/api/activation/ping/routines", {
+      params: { workspace: ws },
+    });
+  }
+
+  async function updateRoutine(routineId, params, ws) {
+    const body = {};
+    if (params.name != null) body.name = params.name;
+    if (params.enabled != null) body.enabled = params.enabled;
+    if (params.intervalMinutes != null) body.intervalMinutes = params.intervalMinutes;
+    if (params.singleFire != null) body.singleFire = params.singleFire;
+    if (params.contextSources != null) body.contextSources = params.contextSources;
+    return request("POST", `/api/activation/ping/routines/${encodeURIComponent(routineId)}`, {
+      params: { workspace: ws },
+      body,
+    });
+  }
+
+  async function deleteRoutine(routineId, ws) {
+    return request("DELETE", `/api/activation/ping/routines/${encodeURIComponent(routineId)}`, {
+      params: { workspace: ws },
+    });
+  }
+
+  async function fireRoutine(routineId, ws) {
+    return request("POST", `/api/activation/ping/routines/${encodeURIComponent(routineId)}/now`, {
+      params: { workspace: ws },
+    });
+  }
+
   // --- Heartbeat -------------------------------------------------------------
 
   async function heartbeat(ws, agent, vaultMode) {
@@ -214,6 +245,46 @@ export function createClient(config) {
     return request("POST", `/api/workspaces/${encodeURIComponent(ws)}/heartbeat`, { body });
   }
 
+  // --- Telegram --------------------------------------------------------------
+
+  async function telegramContacts(ws) {
+    return request("GET", "/api/telegram/contacts", {
+      params: { workspace: ws },
+    });
+  }
+
+  async function telegramRead(chatId, minutes, start, ws, markRead) {
+    return request("GET", `/api/telegram/messages/${chatId}`, {
+      params: { minutes, start, workspace: ws, mark_read: markRead },
+    });
+  }
+
+  async function telegramSend(chatId, message) {
+    return request("POST", `/api/telegram/send/${chatId}`, {
+      body: { message },
+    });
+  }
+
+  async function telegramImage(messageId) {
+    return request("GET", `/api/telegram/image/${messageId}`);
+  }
+
+  async function telegramSendImage(chatId, filePath, caption) {
+    return request("POST", `/api/telegram/send-image/${chatId}`, {
+      body: { file_path: filePath, caption: caption || "" },
+    });
+  }
+
+  async function telegramStatus() {
+    return request("GET", "/api/telegram/status");
+  }
+
+  // --- Settings --------------------------------------------------------------
+
+  async function getSettings() {
+    return request("GET", "/api/settings");
+  }
+
   // --- Auth ------------------------------------------------------------------
 
   async function getApiKey() {
@@ -254,7 +325,18 @@ export function createClient(config) {
     pushFile,
     syncManifest,
     createRoutine,
+    listRoutines,
+    updateRoutine,
+    deleteRoutine,
+    fireRoutine,
     heartbeat,
+    telegramContacts,
+    telegramRead,
+    telegramSend,
+    telegramImage,
+    telegramSendImage,
+    telegramStatus,
+    getSettings,
     getApiKey,
     healthCheck,
   };

package/src/ws-connection.js

@@ -0,0 +1,250 @@
+/**
+ * WebSocket push channel — receives server-pushed messages and handles them locally.
+ *
+ * Connects to fathom-server's /ws/agent/{workspace} endpoint. Receives:
+ *   - inject / ping_fire → tmux send-keys into local pane
+ *   - image → cache base64 data to .fathom/telegram-cache/
+ *   - ping → respond with pong
+ *
+ * Auto-reconnects with exponential backoff (1s → 60s cap).
+ * HTTP heartbeat still runs separately for backwards compat with old servers.
+ */
+
+import { execSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import WebSocket from "ws";
+
+const KEEPALIVE_INTERVAL_MS = 30_000;
+const INITIAL_RECONNECT_MS = 1_000;
+const MAX_RECONNECT_MS = 60_000;
+const IMAGE_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+/**
+ * @param {object} config — resolved config from config.js
+ * @returns {{ getCachedImage: (messageId: number) => {data: string, mimeType: string} | null, close: () => void }}
+ */
+export function createWSConnection(config) {
+  const workspace = config.workspace;
+  const agent = config.agents?.[0] || "unknown";
+  const vaultMode = config.vaultMode || "local";
+
+  // Derive WS URL from HTTP server URL
+  const serverUrl = config.server || "http://localhost:4243";
+  const wsUrl = serverUrl
+    .replace(/^http:/, "ws:")
+    .replace(/^https:/, "wss:")
+    + `/ws/agent/${encodeURIComponent(workspace)}`
+    + `?token=${encodeURIComponent(config.apiKey || "")}`;
+
+  // Image cache directory
+  const cacheDir = path.join(os.homedir(), ".fathom", "telegram-cache");
+
+  let ws = null;
+  let reconnectDelay = INITIAL_RECONNECT_MS;
+  let keepaliveTimer = null;
+  let closed = false;
+
+  // Clean up old cached images on startup
+  cleanupImageCache();
+
+  connect();
+
+  function connect() {
+    if (closed) return;
+
+    try {
+      ws = new WebSocket(wsUrl);
+    } catch {
+      scheduleReconnect();
+      return;
+    }
+
+    ws.on("open", () => {
+      reconnectDelay = INITIAL_RECONNECT_MS;
+
+      // Send hello handshake
+      ws.send(JSON.stringify({
+        type: "hello",
+        agent,
+        vault_mode: vaultMode,
+      }));
+
+      // Start keepalive pong timer
+      startKeepalive();
+    });
+
+    ws.on("message", (raw) => {
+      let msg;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+
+      switch (msg.type) {
+        case "welcome":
+          break;
+
+        case "inject":
+        case "ping_fire":
+          injectToTmux(msg.text || "");
+          break;
+
+        case "image":
+          cacheImage(msg);
+          break;
+
+        case "ping":
+          safeSend({ type: "pong" });
+          break;
+
+        case "error":
+          // Server rejected us — don't reconnect immediately
+          reconnectDelay = MAX_RECONNECT_MS;
+          break;
+      }
+    });
+
+    ws.on("close", () => {
+      stopKeepalive();
+      if (!closed) scheduleReconnect();
+    });
+
+    ws.on("error", () => {
+      // Error always followed by close event — reconnect handled there
+      stopKeepalive();
+    });
+  }
+
+  function safeSend(obj) {
+    try {
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify(obj));
+      }
+    } catch {
+      // Swallow — close event will trigger reconnect
+    }
+  }
+
+  function startKeepalive() {
+    stopKeepalive();
+    keepaliveTimer = setInterval(() => {
+      safeSend({ type: "pong" });
+    }, KEEPALIVE_INTERVAL_MS);
+  }
+
+  function stopKeepalive() {
+    if (keepaliveTimer) {
+      clearInterval(keepaliveTimer);
+      keepaliveTimer = null;
+    }
+  }
+
+  function scheduleReconnect() {
+    if (closed) return;
+    setTimeout(connect, reconnectDelay);
+    reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_MS);
+  }
+
+  // ── tmux injection ──────────────────────────────────────────────────────────
+
+  function injectToTmux(text) {
+    if (!text) return;
+    const pane = resolvePaneTarget();
+
+    try {
+      // Send the text literally, then press Enter
+      execSync(`tmux send-keys -t ${shellEscape(pane)} -l ${shellEscape(text)}`, {
+        timeout: 5000,
+        stdio: "ignore",
+      });
+      execSync(`tmux send-keys -t ${shellEscape(pane)} Enter`, {
+        timeout: 5000,
+        stdio: "ignore",
+      });
+    } catch {
+      // tmux not available or pane not found — non-fatal
+    }
+  }
+
+  function resolvePaneTarget() {
+    // Check for explicit pane ID file
+    const paneIdFile = path.join(os.homedir(), ".config", "fathom", `${workspace}-pane-id`);
+    try {
+      const paneId = fs.readFileSync(paneIdFile, "utf-8").trim();
+      if (paneId) return paneId;
+    } catch {
+      // Fall through to default
+    }
+    return `${workspace}_fathom-session`;
+  }
+
+  function shellEscape(s) {
+    // Escape for shell — wrap in single quotes, escape internal single quotes
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+  }
+
+  // ── Image cache ─────────────────────────────────────────────────────────────
+
+  function cacheImage(msg) {
+    if (!msg.message_id || !msg.data) return;
+
+    try {
+      fs.mkdirSync(cacheDir, { recursive: true });
+      const ext = (msg.filename || "").split(".").pop() || "jpg";
+      const filename = `${msg.message_id}.${ext}`;
+      const filePath = path.join(cacheDir, filename);
+      fs.writeFileSync(filePath, Buffer.from(msg.data, "base64"));
+    } catch {
+      // Cache write failure is non-fatal
+    }
+  }
+
+  function getCachedImage(messageId) {
+    try {
+      const dir = fs.readdirSync(cacheDir);
+      const match = dir.find(f => f.startsWith(`${messageId}.`));
+      if (!match) return null;
+
+      const filePath = path.join(cacheDir, match);
+      const data = fs.readFileSync(filePath);
+      const ext = path.extname(match).slice(1).toLowerCase();
+      const mimeMap = { jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif", webp: "image/webp" };
+      return {
+        data: data.toString("base64"),
+        mimeType: mimeMap[ext] || "image/jpeg",
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  function cleanupImageCache() {
+    try {
+      if (!fs.existsSync(cacheDir)) return;
+      const now = Date.now();
+      for (const file of fs.readdirSync(cacheDir)) {
+        const filePath = path.join(cacheDir, file);
+        const stat = fs.statSync(filePath);
+        if (now - stat.mtimeMs > IMAGE_CACHE_MAX_AGE_MS) {
+          fs.unlinkSync(filePath);
+        }
+      }
+    } catch {
+      // Cleanup failure is non-fatal
+    }
+  }
+
+  function close() {
+    closed = true;
+    stopKeepalive();
+    if (ws) {
+      try { ws.close(); } catch { /* ignore */ }
+      ws = null;
+    }
+  }
+
+  return { getCachedImage, close };
+}