talon-agent 1.0.0 → 1.2.0

package/src/frontend/telegram/middleware.ts

@@ -110,7 +110,8 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
         mediaType: "animation",
       });
     } else if ("audio" in ctx.message && ctx.message.audio) {
-      const title = ctx.message.audio.title || ctx.message.audio.file_name || "audio";
+      const title =
+        ctx.message.audio.title || ctx.message.audio.file_name || "audio";
       pushMessage(chatId, {
         msgId,
         senderId,
@@ -140,7 +141,12 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
         timestamp,
       });
     } else if ("contact" in ctx.message && ctx.message.contact) {
-      const name = [ctx.message.contact.first_name, ctx.message.contact.last_name].filter(Boolean).join(" ");
+      const name = [
+        ctx.message.contact.first_name,
+        ctx.message.contact.last_name,
+      ]
+        .filter(Boolean)
+        .join(" ");
       pushMessage(chatId, {
         msgId,
         senderId,
@@ -171,7 +177,11 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
   bot.on("message:voice", (ctx) => handleVoiceMessage(ctx, bot, config));
   bot.on("message:sticker", (ctx) => handleStickerMessage(ctx, bot, config));
   bot.on("message:video", (ctx) => handleVideoMessage(ctx, bot, config));
-  bot.on("message:animation", (ctx) => handleAnimationMessage(ctx, bot, config));
+  bot.on("message:animation", (ctx) =>
+    handleAnimationMessage(ctx, bot, config),
+  );
   bot.on("message:audio", (ctx) => handleAudioMessage(ctx, bot, config));
-  bot.on("message:video_note", (ctx) => handleVideoNoteMessage(ctx, bot, config));
+  bot.on("message:video_note", (ctx) =>
+    handleVideoNoteMessage(ctx, bot, config),
+  );
 }

package/src/frontend/telegram/userbot.ts

@@ -418,7 +418,9 @@ export async function downloadMessageMedia(params: {
     if (!buffer || buffer.length === 0) return "Download returned empty data.";
 
     // Use the original filename if available, otherwise generate one
-    const doc = (m.media as { document?: { attributes?: Array<{ fileName?: string }> } }).document;
+    const doc = (
+      m.media as { document?: { attributes?: Array<{ fileName?: string }> } }
+    ).document;
     const originalName = doc?.attributes?.find((a) => a.fileName)?.fileName;
     const filename = originalName
       ? `${Date.now()}-${originalName.replace(/[^a-zA-Z0-9._-]/g, "_")}`
@@ -431,7 +433,10 @@ export async function downloadMessageMedia(params: {
     const filePath = resolve(uploadsDir, filename);
     writeFileSync(filePath, buffer);
 
-    log("userbot", `Downloaded media from msg:${params.messageId} → ${filename} (${buffer.length} bytes)`);
+    log(
+      "userbot",
+      `Downloaded media from msg:${params.messageId} → ${filename} (${buffer.length} bytes)`,
+    );
     return `Downloaded to: ${filePath} (${buffer.length} bytes). Use the Read tool on this path to view the content.`;
   } catch (err) {
     return `Download failed: ${err instanceof Error ? err.message : err}`;
@@ -446,7 +451,15 @@ export async function saveStickerPack(params: {
   bot: unknown;
 }): Promise<string> {
   try {
-    const bot = params.bot as { api: { getStickerSet: (name: string) => Promise<{ title: string; name: string; stickers: Array<{ emoji?: string; file_id: string }> }> } };
+    const bot = params.bot as {
+      api: {
+        getStickerSet: (name: string) => Promise<{
+          title: string;
+          name: string;
+          stickers: Array<{ emoji?: string; file_id: string }>;
+        }>;
+      };
+    };
     const stickerSet = await bot.api.getStickerSet(params.setName);
 
     const stickers = stickerSet.stickers.map((s) => ({
@@ -543,4 +556,3 @@ export async function getOnlineCount(params: {
     return `Failed: ${err instanceof Error ? err.message : err}`;
   }
 }
-

package/src/frontend/terminal/renderer.ts

@@ -184,10 +184,7 @@ export function createRenderer(cols?: number, displayName = "Talon"): Renderer {
     tools: number,
     info: StatusBarInfo,
   ): void {
-    const p = [
-      `${(ms / 1000).toFixed(1)}s`,
-      info.model,
-    ];
+    const p = [`${(ms / 1000).toFixed(1)}s`, info.model];
     if (info.sessionName) p.push(`"${info.sessionName}"`);
     p.push(
       `${info.turns} turn${info.turns !== 1 ? "s" : ""}`,

package/src/index.ts

@@ -15,6 +15,11 @@ import { flushHistory } from "./storage/history.js";
 import { flushMediaIndex } from "./storage/media-index.js";
 import { getActiveCount } from "./core/dispatcher.js";
 import { startPulseTimer, stopPulseTimer } from "./core/pulse.js";
+import {
+  startHeartbeatTimer,
+  stopHeartbeatTimer,
+  awaitCurrentRun as awaitHeartbeat,
+} from "./core/heartbeat.js";
 import { startCronTimer, stopCronTimer } from "./core/cron.js";
 import { startWatchdog, stopWatchdog } from "./util/watchdog.js";
 import { log, logError, logWarn } from "./util/log.js";
@@ -30,7 +35,11 @@ import { files as pathFiles } from "./util/paths.js";
 const { config } = await bootstrap();
 
 // Write PID file for daemon management
-try { writeFileSync(pathFiles.pid, String(process.pid)); } catch { /* ok */ }
+try {
+  writeFileSync(pathFiles.pid, String(process.pid));
+} catch {
+  /* ok */
+}
 
 // ── Create gateway + frontend ─────────────────────────────────────────────────
 
@@ -40,7 +49,8 @@ const selectedFrontend = getFrontends(config)[0]; // use first configured fronte
 let frontend: Frontend;
 
 if (selectedFrontend === "terminal") {
-  const { createTerminalFrontend } = await import("./frontend/terminal/index.js");
+  const { createTerminalFrontend } =
+    await import("./frontend/terminal/index.js");
   frontend = createTerminalFrontend(config, gateway);
   log("bot", "Frontend: Terminal");
 } else if (selectedFrontend === "teams") {
@@ -48,7 +58,8 @@ if (selectedFrontend === "terminal") {
   frontend = createTeamsFrontend(config, gateway);
   log("bot", "Frontend: Teams");
 } else {
-  const { createTelegramFrontend } = await import("./frontend/telegram/index.js");
+  const { createTelegramFrontend } =
+    await import("./frontend/telegram/index.js");
   frontend = createTelegramFrontend(config, gateway);
   log("bot", "Frontend: Telegram");
 }
@@ -91,6 +102,8 @@ async function gracefulShutdown(signal: string): Promise<void> {
     await destroyPlugins();
   }
   stopPulseTimer();
+  stopHeartbeatTimer();
+  await awaitHeartbeat();
   stopCronTimer();
   stopWatchdog();
   stopUploadCleanup();
@@ -99,7 +112,11 @@ async function gracefulShutdown(signal: string): Promise<void> {
   flushCronJobs();
   flushHistory();
   flushMediaIndex();
-  try { unlinkSync(pathFiles.pid); } catch { /* ok */ }
+  try {
+    unlinkSync(pathFiles.pid);
+  } catch {
+    /* ok */
+  }
   log("shutdown", "State saved");
   process.exit(0);
 }
@@ -108,6 +125,12 @@ process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
 process.on("SIGINT", () => gracefulShutdown("SIGINT"));
 
 process.on("uncaughtException", (err) => {
+  // EPIPE errors from network sockets (e.g. Telegram MTProto) are transient —
+  // gramjs will reconnect; crashing the process here is wrong.
+  if ((err as NodeJS.ErrnoException).code === "EPIPE") {
+    logWarn("bot", `Suppressed transient EPIPE error: ${err.message}`);
+    return;
+  }
   logError("bot", "Uncaught exception", err);
   flushSessions();
   flushChatSettings();
@@ -131,6 +154,7 @@ async function main(): Promise<void> {
   log("bot", "Starting Talon...");
 
   if (config.pulse) startPulseTimer(config.pulseIntervalMs);
+  if (config.heartbeat) startHeartbeatTimer(config.heartbeatIntervalMinutes);
   startCronTimer();
   startWatchdog(config.workspace);
   startUploadCleanup(config.workspace);

package/src/storage/chat-settings.ts

@@ -6,8 +6,10 @@
 import { existsSync, readFileSync, mkdirSync } from "node:fs";
 import writeFileAtomic from "write-file-atomic";
 import { dirname } from "node:path";
-import { log } from "../util/log.js";
+import { log, logError } from "../util/log.js";
+import { recordError } from "../util/watchdog.js";
 import { files } from "../util/paths.js";
+import { registerCleanup } from "../util/cleanup-registry.js";
 
 export type EffortLevel = "off" | "low" | "medium" | "high" | "max";
 
@@ -41,7 +43,9 @@ export function loadChatSettings(): void {
         store = JSON.parse(readFileSync(bakFile, "utf-8"));
         log("settings", "Loaded from backup (primary was corrupt)");
       }
-    } catch { /* backup also corrupt */ }
+    } catch {
+      /* backup also corrupt */
+    }
   }
   // Migrate legacy maxThinkingTokens → effort
   let migrated = 0;
@@ -85,17 +89,24 @@ function save(): void {
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     const data = JSON.stringify(store, null, 2) + "\n";
     if (existsSync(STORE_FILE)) {
-      try { writeFileAtomic.sync(STORE_FILE + ".bak", readFileSync(STORE_FILE)); } catch { /* best effort */ }
+      try {
+        writeFileAtomic.sync(STORE_FILE + ".bak", readFileSync(STORE_FILE));
+      } catch {
+        /* best effort */
+      }
     }
     writeFileAtomic.sync(STORE_FILE, data);
     dirty = false;
-  } catch {
-    // Non-fatal
+  } catch (err) {
+    logError("settings", "Failed to persist chat settings", err);
+    recordError(
+      `Settings save failed: ${err instanceof Error ? err.message : err}`,
+    );
   }
 }
 
 const autoSaveTimer = setInterval(save, 10_000);
-process.on("exit", save);
+registerCleanup(save);
 
 /** Flush settings to disk and stop the auto-save timer. */
 export function flushChatSettings(): void {
@@ -109,12 +120,22 @@ export function getChatSettings(chatId: string): ChatSettings {
 
 function cleanupEmpty(chatId: string): void {
   const s = store[chatId];
-  if (s && !s.model && !s.effort && s.pulse === undefined && s.pulseIntervalMs === undefined && s.pulseLastCheckMsgId === undefined) {
+  if (
+    s &&
+    !s.model &&
+    !s.effort &&
+    s.pulse === undefined &&
+    s.pulseIntervalMs === undefined &&
+    s.pulseLastCheckMsgId === undefined
+  ) {
     delete store[chatId];
   }
 }
 
-export function setPulseLastCheckMsgId(chatId: string, msgId: number | undefined): void {
+export function setPulseLastCheckMsgId(
+  chatId: string,
+  msgId: number | undefined,
+): void {
   if (!store[chatId]) store[chatId] = {};
   if (msgId !== undefined) {
     store[chatId].pulseLastCheckMsgId = msgId;
@@ -214,5 +235,7 @@ export const MODEL_ALIASES: Record<string, string> = {
 
 export function resolveModelName(input: string): string {
   const lower = input.trim().toLowerCase();
-  return Object.hasOwn(MODEL_ALIASES, lower) ? MODEL_ALIASES[lower] : input.trim();
+  return Object.hasOwn(MODEL_ALIASES, lower)
+    ? MODEL_ALIASES[lower]
+    : input.trim();
 }

package/src/storage/cron-store.ts

@@ -4,11 +4,14 @@
  */
 
 import { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import writeFileAtomic from "write-file-atomic";
 import { dirname } from "node:path";
 import { Cron } from "croner";
-import { log } from "../util/log.js";
+import { log, logError } from "../util/log.js";
+import { recordError } from "../util/watchdog.js";
 import { files } from "../util/paths.js";
+import { registerCleanup } from "../util/cleanup-registry.js";
 
 export type CronJobType = "message" | "query";
 
@@ -52,14 +55,45 @@ export function loadCronJobs(): void {
     try {
       if (existsSync(bakFile)) {
         const raw = JSON.parse(readFileSync(bakFile, "utf-8"));
-        store = Array.isArray(raw) ? Object.fromEntries(raw.map((j: CronJob) => [j.id, j])) : raw;
+        store = Array.isArray(raw)
+          ? Object.fromEntries(raw.map((j: CronJob) => [j.id, j]))
+          : raw;
         log("cron", "Loaded from backup (primary was corrupt)");
       }
-    } catch { /* backup also corrupt */ }
+    } catch {
+      /* backup also corrupt */
+    }
+  }
+  // Validate and strip invalid IANA timezone strings so Cron() doesn't throw at runtime
+  let invalidTz = 0;
+  for (const job of Object.values(store)) {
+    if (job.timezone && !isValidTimezone(job.timezone)) {
+      log(
+        "cron",
+        `Job "${job.name}" has invalid timezone "${job.timezone}" — clearing`,
+      );
+      job.timezone = undefined;
+      dirty = true;
+      invalidTz++;
+    }
   }
+
   const count = Object.keys(store).length;
   if (count > 0) {
-    log("cron", `Loaded ${count} cron job(s)`);
+    log(
+      "cron",
+      `Loaded ${count} cron job(s)${invalidTz > 0 ? ` (cleared ${invalidTz} invalid timezone(s))` : ""}`,
+    );
+  }
+}
+
+/** Check if an IANA timezone string is valid using the Intl API. */
+export function isValidTimezone(tz: string): boolean {
+  try {
+    Intl.DateTimeFormat(undefined, { timeZone: tz });
+    return true;
+  } catch {
+    return false;
   }
 }
 
@@ -70,17 +104,24 @@ function save(): void {
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     const data = JSON.stringify(store, null, 2) + "\n";
     if (existsSync(STORE_FILE)) {
-      try { writeFileAtomic.sync(STORE_FILE + ".bak", readFileSync(STORE_FILE)); } catch { /* best effort */ }
+      try {
+        writeFileAtomic.sync(STORE_FILE + ".bak", readFileSync(STORE_FILE));
+      } catch {
+        /* best effort */
+      }
     }
     writeFileAtomic.sync(STORE_FILE, data);
     dirty = false;
-  } catch {
-    // Non-fatal
+  } catch (err) {
+    logError("cron", "Failed to persist cron jobs", err);
+    recordError(
+      `Cron save failed: ${err instanceof Error ? err.message : err}`,
+    );
   }
 }
 
 const autoSaveTimer = setInterval(save, 10_000);
-process.on("exit", save);
+registerCleanup(save);
 
 /** Flush cron jobs to disk and stop the auto-save timer. */
 export function flushCronJobs(): void {
@@ -90,8 +131,9 @@ export function flushCronJobs(): void {
 
 // ── ID generation ───────────────────────────────────────────────────────────
 
+/** Generate a collision-free cron job ID using the platform's CSPRNG. */
 export function generateCronId(): string {
-  return `cron_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+  return `cron_${randomUUID()}`;
 }
 
 // ── Validation ──────────────────────────────────────────────────────────────
@@ -105,12 +147,12 @@ export function validateCronExpression(
     const nextDate = cron.nextRun();
     return {
       valid: true,
-      next: nextDate ? nextDate.toISOString() : undefined,
+      next: (nextDate as Date).toISOString(),
     };
   } catch (err) {
     return {
       valid: false,
-      error: err instanceof Error ? err.message : String(err),
+      error: (err as Error).message,
     };
   }
 }

package/src/storage/daily-log.ts

@@ -3,10 +3,17 @@
  * Claude can reference these via the Read tool for continuity across sessions.
  */
 
-import { existsSync, mkdirSync, appendFileSync, readdirSync, unlinkSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  appendFileSync,
+  readdirSync,
+  unlinkSync,
+} from "node:fs";
 import { resolve } from "node:path";
 import { log as logInfo, logError } from "../util/log.js";
 import { dirs } from "../util/paths.js";
+import { toYMD } from "../util/time.js";
 
 const LOGS_DIR = dirs.logs;
 const MAX_LOG_DAYS = 30; // Keep last 30 days of logs
@@ -24,7 +31,11 @@ function ensureLogsDir(): void {
  * @param text - Message content
  * @param chatContext - Optional chat context (group title, username, etc.)
  */
-export function appendDailyLog(chatName: string, text: string, chatContext?: { chatTitle?: string; username?: string }): void {
+export function appendDailyLog(
+  chatName: string,
+  text: string,
+  chatContext?: { chatTitle?: string; username?: string },
+): void {
   try {
     ensureLogsDir();
     const now = new Date();
@@ -44,7 +55,11 @@ export function appendDailyLog(chatName: string, text: string, chatContext?: { c
  * Append a bot response entry to today's daily log.
  * Format: ## HH:MM -- [botName] in chatTitle\nresponse text\n
  */
-export function appendDailyLogResponse(botName: string, text: string, chatContext?: { chatTitle?: string }): void {
+export function appendDailyLogResponse(
+  botName: string,
+  text: string,
+  chatContext?: { chatTitle?: string },
+): void {
   try {
     ensureLogsDir();
     const now = new Date();
@@ -52,7 +67,9 @@ export function appendDailyLogResponse(botName: string, text: string, chatContex
     const timeStr = now.toTimeString().slice(0, 5); // HH:MM
     const logFile = resolve(LOGS_DIR, `${dateStr}.md`);
 
-    const label = chatContext?.chatTitle ? `${botName} in ${chatContext.chatTitle}` : botName;
+    const label = chatContext?.chatTitle
+      ? `${botName} in ${chatContext.chatTitle}`
+      : botName;
     const entry = `## ${timeStr} -- [${label}]\n${text}\n\n`;
     appendFileSync(logFile, entry);
   } catch (err) {
@@ -61,7 +78,10 @@ export function appendDailyLogResponse(botName: string, text: string, chatContex
 }
 
 /** Format a log label with optional chat title and username. */
-function formatLabel(name: string, ctx?: { chatTitle?: string; username?: string }): string {
+function formatLabel(
+  name: string,
+  ctx?: { chatTitle?: string; username?: string },
+): string {
   const userPart = ctx?.username ? `${name} (@${ctx.username})` : name;
   if (ctx?.chatTitle) return `${userPart} in ${ctx.chatTitle}`;
   return userPart;
@@ -72,26 +92,59 @@ export function getLogsDir(): string {
   return LOGS_DIR;
 }
 
+/** Matches YYYY-MM-DD.md filenames strictly. */
+const DAILY_FILE_RE = /^\d{4}-\d{2}-\d{2}\.md$/;
+
 /** Remove daily logs older than MAX_LOG_DAYS. Called on startup. */
 export function cleanupOldLogs(): void {
   try {
-    if (!existsSync(LOGS_DIR)) return;
-    const cutoff = new Date();
-    cutoff.setDate(cutoff.getDate() - MAX_LOG_DAYS);
-    const cutoffStr = cutoff.toISOString().slice(0, 10);
+    if (existsSync(LOGS_DIR)) {
+      const cutoff = new Date();
+      cutoff.setDate(cutoff.getDate() - MAX_LOG_DAYS);
+      const cutoffStr = cutoff.toISOString().slice(0, 10);
 
-    let deleted = 0;
-    for (const file of readdirSync(LOGS_DIR)) {
-      // Log files are named YYYY-MM-DD.md
-      if (file.endsWith(".md") && file < cutoffStr) {
+      let deleted = 0;
+      for (const file of readdirSync(LOGS_DIR)) {
+        if (DAILY_FILE_RE.test(file) && file < cutoffStr) {
+          try {
+            unlinkSync(resolve(LOGS_DIR, file));
+            deleted++;
+          } catch {
+            /* skip */
+          }
+        }
+      }
+      if (deleted > 0) {
+        logInfo("workspace", `Cleaned up ${deleted} old daily log(s)`);
+      }
+    }
+  } catch {
+    /* skip */
+  }
+
+  // Clean up old daily memory files (independent of logs dir)
+  try {
+    const dailyMemDir = dirs.dailyMemory;
+    if (!existsSync(dailyMemDir)) return;
+    const cutoffDate = new Date();
+    cutoffDate.setDate(cutoffDate.getDate() - MAX_LOG_DAYS);
+    const cutoffMem = toYMD(cutoffDate);
+
+    let deletedMem = 0;
+    for (const file of readdirSync(dailyMemDir)) {
+      if (DAILY_FILE_RE.test(file) && file < cutoffMem) {
         try {
-          unlinkSync(resolve(LOGS_DIR, file));
-          deleted++;
-        } catch { /* skip */ }
+          unlinkSync(resolve(dailyMemDir, file));
+          deletedMem++;
+        } catch {
+          /* skip */
+        }
       }
     }
-    if (deleted > 0) {
-      logInfo("workspace", `Cleaned up ${deleted} old daily log(s)`);
+    if (deletedMem > 0) {
+      logInfo("workspace", `Cleaned up ${deletedMem} old daily memory file(s)`);
     }
-  } catch { /* skip */ }
+  } catch {
+    /* skip */
+  }
 }

package/src/storage/history.ts

@@ -11,8 +11,10 @@ import { existsSync, readFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { log, logError } from "../util/log.js";
+import { recordError } from "../util/watchdog.js";
 import { files } from "../util/paths.js";
-import { formatSmartTimestamp } from "../util/time.js";
+import { formatSmartTimestamp, formatRelativeAge } from "../util/time.js";
+import { registerCleanup } from "../util/cleanup-registry.js";
 
 export type HistoryMessage = {
   msgId: number;
@@ -61,15 +63,26 @@ export function loadHistory(): void {
     const bakFile = STORE_FILE + ".bak";
     try {
       if (existsSync(bakFile)) {
-        const raw = JSON.parse(readFileSync(bakFile, "utf-8")) as Record<string, HistoryMessage[]>;
+        const raw = JSON.parse(readFileSync(bakFile, "utf-8")) as Record<
+          string,
+          HistoryMessage[]
+        >;
         for (const [chatId, messages] of Object.entries(raw)) {
           chatHistories.set(chatId, messages.slice(-MAX_HISTORY_PER_CHAT));
         }
-        logError("sessions", "Loaded history from backup (primary was corrupt)");
+        logError(
+          "sessions",
+          "Loaded history from backup (primary was corrupt)",
+        );
         return;
       }
-    } catch { /* backup also corrupt */ }
-    logError("sessions", "History data corrupt and no valid backup — starting fresh");
+    } catch {
+      /* backup also corrupt */
+    }
+    logError(
+      "sessions",
+      "History data corrupt and no valid backup — starting fresh",
+    );
   }
 }
 
@@ -85,18 +98,25 @@ function saveHistory(): void {
     const data = JSON.stringify(obj) + "\n";
     // Write backup of current file before overwriting
     if (existsSync(STORE_FILE)) {
-      try { writeFileAtomic.sync(STORE_FILE + ".bak", readFileSync(STORE_FILE)); } catch { /* best effort */ }
+      try {
+        writeFileAtomic.sync(STORE_FILE + ".bak", readFileSync(STORE_FILE));
+      } catch {
+        /* best effort */
+      }
     }
     writeFileAtomic.sync(STORE_FILE, data);
     dirty = false;
   } catch (err) {
-    logError("sessions", "Failed to persist history", err);
+    logError("history", "Failed to persist history", err);
+    recordError(
+      `History save failed: ${err instanceof Error ? err.message : err}`,
+    );
   }
 }
 
 // Auto-save every 30 seconds (less frequent than sessions since history is larger)
 const autoSaveTimer = setInterval(saveHistory, 30_000);
-process.on("exit", saveHistory);
+registerCleanup(saveHistory);
 
 export function flushHistory(): void {
   clearInterval(autoSaveTimer);
@@ -114,8 +134,7 @@ export function pushMessage(chatId: string, msg: HistoryMessage): void {
       const iter = chatHistories.keys();
       for (let i = 0; i < evictCount; i++) {
         const oldest = iter.next();
-        if (oldest.done) break;
-        chatHistories.delete(oldest.value);
+        chatHistories.delete(oldest.value as string);
       }
       // Mark dirty so evicted chats are removed from disk on next save
       dirty = true;
@@ -137,11 +156,18 @@ export function getRecentHistory(chatId: string, limit = 50): HistoryMessage[] {
 }
 
 /** Update a message's file path after media download. */
-export function setMessageFilePath(chatId: string, msgId: number, filePath: string): void {
+export function setMessageFilePath(
+  chatId: string,
+  msgId: number,
+  filePath: string,
+): void {
   const history = chatHistories.get(chatId);
   if (!history) return;
   const msg = history.find((m) => m.msgId === msgId);
-  if (msg) { msg.filePath = filePath; dirty = true; }
+  if (msg) {
+    msg.filePath = filePath;
+    dirty = true;
+  }
 }
 
 export function clearHistory(chatId: string): void {
@@ -230,20 +256,12 @@ export function getKnownUsers(chatId: string): string {
   const lines = [...users.entries()]
     .sort((a, b) => b[1].lastSeen - a[1].lastSeen)
     .map(([id, u]) => {
-      const ago = formatTimeAgo(u.lastSeen);
+      const ago = formatRelativeAge(u.lastSeen);
       return `${u.name} (user_id: ${id}) — ${u.messageCount} msgs, last seen ${ago}`;
     });
   return lines.join("\n");
 }
 
-function formatTimeAgo(ts: number): string {
-  const diff = Date.now() - ts;
-  if (diff < 60_000) return "just now";
-  if (diff < 3_600_000) return `${Math.floor(diff / 60_000)}m ago`;
-  if (diff < 86_400_000) return `${Math.floor(diff / 3_600_000)}h ago`;
-  return `${Math.floor(diff / 86_400_000)}d ago`;
-}
-
 export function getRecentBySenderId(
   chatId: string,
   senderId: number,