talon-agent 4.3.2 → 4.4.0

package/src/frontend/telegram/actions/moderation/members.ts

@@ -0,0 +1,77 @@
+/**
+ * Member ops — ban / unban / mute / unmute / promote / demote /
+ * set_admin_title, plus the join-request trio. Every op here except
+ * `list_join_requests` needs a `user_id`; the router has already checked
+ * that, so `userId!` is safe.
+ */
+
+import { clearJoinRequest, listJoinRequests } from "../../join-requests.js";
+import {
+  DEFAULT_ADMIN_RIGHTS,
+  FULL_MEMBER_PERMISSIONS,
+  untilDate,
+} from "./permissions.js";
+import type { ModerationOps } from "./types.js";
+
+export const memberOps: ModerationOps = {
+  ban: async ({ body, chatId, ctx: { bot }, userId }) => {
+    await bot.api.banChatMember(chatId, userId!, {
+      until_date: untilDate(body.minutes),
+      revoke_messages: body.delete_messages === true || undefined,
+    });
+    return { ok: true };
+  },
+  unban: async ({ chatId, ctx: { bot }, userId }) => {
+    // only_if_banned keeps this from kicking a current member.
+    await bot.api.unbanChatMember(chatId, userId!, {
+      only_if_banned: true,
+    });
+    return { ok: true };
+  },
+  mute: async ({ body, chatId, ctx: { bot }, userId }) => {
+    await bot.api.restrictChatMember(
+      chatId,
+      userId!,
+      { can_send_messages: false },
+      { until_date: untilDate(body.minutes) },
+    );
+    return { ok: true };
+  },
+  unmute: async ({ chatId, ctx: { bot }, userId }) => {
+    await bot.api.restrictChatMember(chatId, userId!, FULL_MEMBER_PERMISSIONS);
+    return { ok: true };
+  },
+  promote: async ({ chatId, ctx: { bot }, userId }) => {
+    await bot.api.promoteChatMember(chatId, userId!, DEFAULT_ADMIN_RIGHTS);
+    return { ok: true };
+  },
+  demote: async ({ chatId, ctx: { bot }, userId }) => {
+    const revoked = Object.fromEntries(
+      Object.keys(DEFAULT_ADMIN_RIGHTS).map((k) => [k, false]),
+    );
+    await bot.api.promoteChatMember(chatId, userId!, revoked);
+    return { ok: true };
+  },
+  set_admin_title: async ({ body, chatId, ctx: { bot }, userId }) => {
+    await bot.api.setChatAdministratorCustomTitle(
+      chatId,
+      userId!,
+      String(body.title ?? ""),
+    );
+    return { ok: true };
+  },
+  approve_join_request: async ({ chatId, ctx: { bot }, userId }) => {
+    await bot.api.approveChatJoinRequest(chatId, userId!);
+    clearJoinRequest(chatId, userId!);
+    return { ok: true };
+  },
+  decline_join_request: async ({ chatId, ctx: { bot }, userId }) => {
+    await bot.api.declineChatJoinRequest(chatId, userId!);
+    clearJoinRequest(chatId, userId!);
+    return { ok: true };
+  },
+  list_join_requests: async ({ chatId }) => ({
+    ok: true,
+    requests: listJoinRequests(chatId),
+  }),
+};

package/src/frontend/telegram/actions/moderation/permissions.ts

@@ -0,0 +1,69 @@
+/**
+ * Permission vocabulary shared by the member and chat ops.
+ */
+
+import type { ChatPermissions } from "grammy/types";
+
+/** Seconds-from-now → Telegram until_date, honouring "omit = forever". */
+export function untilDate(minutes: unknown): number | undefined {
+  const n = Number(minutes);
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  return Math.floor(Date.now() / 1000) + Math.round(n * 60);
+}
+
+/**
+ * Friendly permission names → ChatPermissions. `send_media` fans out to all
+ * the per-kind media flags; raw `can_*` keys pass through untouched so the
+ * full API surface stays reachable.
+ */
+export function toChatPermissions(
+  raw: Record<string, boolean>,
+): ChatPermissions {
+  const out: Record<string, boolean> = {};
+  const alias: Record<string, string[]> = {
+    send_messages: ["can_send_messages"],
+    send_media: [
+      "can_send_audios",
+      "can_send_documents",
+      "can_send_photos",
+      "can_send_videos",
+      "can_send_video_notes",
+      "can_send_voice_notes",
+    ],
+    send_polls: ["can_send_polls"],
+    send_other: ["can_send_other_messages"],
+    web_previews: ["can_add_web_page_previews"],
+    change_info: ["can_change_info"],
+    invite_users: ["can_invite_users"],
+    pin_messages: ["can_pin_messages"],
+    manage_topics: ["can_manage_topics"],
+  };
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value !== "boolean") continue;
+    for (const target of alias[key] ?? (key.startsWith("can_") ? [key] : [])) {
+      out[target] = value;
+    }
+  }
+  return out;
+}
+
+/** Everything a mute takes away; unmute grants it back. */
+export const FULL_MEMBER_PERMISSIONS: ChatPermissions = toChatPermissions({
+  send_messages: true,
+  send_media: true,
+  send_polls: true,
+  send_other: true,
+  web_previews: true,
+});
+
+/** The workaday admin kit `promote` grants; demote sets all of these false. */
+export const DEFAULT_ADMIN_RIGHTS = {
+  can_manage_chat: true,
+  can_delete_messages: true,
+  can_restrict_members: true,
+  can_pin_messages: true,
+  can_invite_users: true,
+  can_change_info: true,
+  can_manage_topics: true,
+  can_manage_video_chats: true,
+};

package/src/frontend/telegram/actions/moderation/topics.ts

@@ -0,0 +1,48 @@
+/**
+ * Forum-topic ops — create / edit / close / reopen / delete.
+ */
+
+import type { Bot } from "grammy";
+import { toPositiveId } from "../coerce.js";
+import type { ModerationOp, ModerationOps } from "./types.js";
+
+/** An op on an existing topic: validates `thread_id`, then runs `call`. */
+function topicOp(
+  call: (
+    api: Bot["api"],
+    chatId: number,
+    threadId: number,
+    body: Record<string, unknown>,
+  ) => Promise<unknown>,
+): ModerationOp {
+  return async ({ op, body, chatId, ctx: { bot } }) => {
+    const threadId = toPositiveId(body.thread_id);
+    if (threadId === undefined)
+      return { ok: false, error: `${op}: thread_id required` };
+    await call(bot.api, chatId, threadId, body);
+    return { ok: true };
+  };
+}
+
+export const topicOps: ModerationOps = {
+  create_topic: async ({ body, chatId, ctx: { bot } }) => {
+    if (!body.title)
+      return { ok: false, error: "create_topic: title required" };
+    const topic = await bot.api.createForumTopic(chatId, String(body.title));
+    return { ok: true, thread_id: topic.message_thread_id };
+  },
+  edit_topic: topicOp((api, chatId, threadId, body) =>
+    api.editForumTopic(chatId, threadId, {
+      name: body.title ? String(body.title) : undefined,
+    }),
+  ),
+  close_topic: topicOp((api, chatId, threadId) =>
+    api.closeForumTopic(chatId, threadId),
+  ),
+  reopen_topic: topicOp((api, chatId, threadId) =>
+    api.reopenForumTopic(chatId, threadId),
+  ),
+  delete_topic: topicOp((api, chatId, threadId) =>
+    api.deleteForumTopic(chatId, threadId),
+  ),
+};

package/src/frontend/telegram/actions/moderation/types.ts

@@ -0,0 +1,16 @@
+import type { ActionResult } from "../../../../core/types.js";
+import type { TelegramActionContext } from "../types.js";
+
+/** One `moderate` call, pre-parsed: the op name, the raw body, and the
+ * `user_id` the router already validated for ops that need one. */
+type ModerationRequest = {
+  op: string;
+  body: Record<string, unknown>;
+  chatId: number;
+  ctx: TelegramActionContext;
+  userId: number | undefined;
+};
+
+export type ModerationOp = (req: ModerationRequest) => Promise<ActionResult>;
+
+export type ModerationOps = Record<string, ModerationOp>;

package/src/frontend/telegram/actions/rich-messages.ts

@@ -0,0 +1,51 @@
+/**
+ * Rich Messages capability probe — whether native Rich Markdown delivery is
+ * worth attempting on this Bot API server, latched off on the first
+ * "method not found".
+ */
+
+import { logWarn } from "../../../util/log.js";
+
+/**
+ * Rich Messages arrived in Bot API 10.2. A self-hosted Bot API server (or a
+ * deployment pinned to an older release) rejects `sendRichMessage` outright,
+ * and retrying it per message would cost a doomed round-trip plus a warning
+ * line on every single send. Probe once and latch, mirroring the
+ * `draftsSupported` capability probe in `handlers/delivery.ts`.
+ */
+let richMessagesSupported = true;
+
+/** Telegram's shape for "this build doesn't have that method". */
+const METHOD_UNAVAILABLE_RE =
+  /method not found|not supported|unknown method|unsupported method/i;
+
+/** True while native Rich Markdown delivery is still worth attempting. */
+export function richMessagesAvailable(): boolean {
+  return richMessagesSupported;
+}
+
+/**
+ * Log a failed Rich Message call and latch the capability off when the failure
+ * says the method itself is missing. Payload-level rejections (a markdown
+ * string Telegram won't parse) stay one-off — the next message may be fine.
+ */
+export function noteRichMessageFailure(err: unknown, context: string): void {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (METHOD_UNAVAILABLE_RE.test(msg)) {
+    richMessagesSupported = false;
+    logWarn(
+      "bot",
+      `Rich Messages unavailable on this Bot API server — using legacy HTML from now on (${context}): ${msg}`,
+    );
+    return;
+  }
+  logWarn(
+    "bot",
+    `Rich Markdown failed; falling back to HTML (${context}): ${msg}`,
+  );
+}
+
+/** Test seam: re-arm the capability probe between cases. */
+export function resetRichMessageSupport(): void {
+  richMessagesSupported = true;
+}

package/src/frontend/telegram/actions/{shared.ts → send.ts}

@@ -1,6 +1,7 @@
 /**
- * Shared helpers for Telegram action handlers: reply-parameter extraction and
- * native Rich Markdown delivery with legacy fallbacks.
+ * Outbound Telegram sends: reply-parameter extraction, delivery modifiers,
+ * and text delivery with native Rich Markdown and legacy HTML / plain-text
+ * fallbacks.
  */
 
 import type { Bot } from "grammy";
@@ -8,6 +9,11 @@ import { markdownToTelegramHtml } from "../formatting.js";
 import { logWarn } from "../../../util/log.js";
 import { ambientThreadId, resolveThreadId } from "../topics.js";
 import { TELEGRAM_MAX_TEXT } from "./types.js";
+import { toPositiveId } from "./coerce.js";
+import {
+  noteRichMessageFailure,
+  richMessagesAvailable,
+} from "./rich-messages.js";
 
 export function replyParams(
   body: Record<string, unknown>,
@@ -62,62 +68,6 @@ export function sendOpts(
   };
 }
 
-/**
- * Telegram/GramJS APIs expect numeric IDs. `snowflakeOrIdSchema` normalizes IDs
- * to digit-strings (so 17-19 digit Discord snowflakes survive validation), so a
- * Telegram message/reply/offset ID can arrive here as a string. Coerce it back
- * to a positive integer: Telegram IDs are well within 2^53, so this is lossless.
- * Returns undefined for missing / non-positive / non-integer values.
- */
-export function toPositiveId(v: unknown): number | undefined {
-  const n = typeof v === "number" ? v : typeof v === "string" ? Number(v) : NaN;
-  return Number.isInteger(n) && n > 0 ? n : undefined;
-}
-
-/**
- * Rich Messages arrived in Bot API 10.2. A self-hosted Bot API server (or a
- * deployment pinned to an older release) rejects `sendRichMessage` outright,
- * and retrying it per message would cost a doomed round-trip plus a warning
- * line on every single send. Probe once and latch, mirroring the
- * `draftsSupported` capability probe in `handlers/delivery.ts`.
- */
-let richMessagesSupported = true;
-
-/** Telegram's shape for "this build doesn't have that method". */
-const METHOD_UNAVAILABLE_RE =
-  /method not found|not supported|unknown method|unsupported method/i;
-
-/** True while native Rich Markdown delivery is still worth attempting. */
-export function richMessagesAvailable(): boolean {
-  return richMessagesSupported;
-}
-
-/**
- * Log a failed Rich Message call and latch the capability off when the failure
- * says the method itself is missing. Payload-level rejections (a markdown
- * string Telegram won't parse) stay one-off — the next message may be fine.
- */
-export function noteRichMessageFailure(err: unknown, context: string): void {
-  const msg = err instanceof Error ? err.message : String(err);
-  if (METHOD_UNAVAILABLE_RE.test(msg)) {
-    richMessagesSupported = false;
-    logWarn(
-      "bot",
-      `Rich Messages unavailable on this Bot API server — using legacy HTML from now on (${context}): ${msg}`,
-    );
-    return;
-  }
-  logWarn(
-    "bot",
-    `Rich Markdown failed; falling back to HTML (${context}): ${msg}`,
-  );
-}
-
-/** Test seam: re-arm the capability probe between cases. */
-export function resetRichMessageSupport(): void {
-  richMessagesSupported = true;
-}
-
 export async function sendText(
   bot: Bot,
   chatId: number,
@@ -141,7 +91,7 @@ export async function sendText(
     message_thread_id: ambientThreadId(chatId),
   };
 
-  if (richMessagesSupported) {
+  if (richMessagesAvailable()) {
     try {
       const sent = await bot.api.sendRichMessage(
         chatId,

package/src/frontend/telegram/admin/background.ts

@@ -0,0 +1,66 @@
+/**
+ * `/admin cron` / `pulse` — the background-job subcommands.
+ */
+
+import type { Bot, Context } from "grammy";
+import { escapeHtml } from "../formatting.js";
+import {
+  getAllCronJobs,
+  describeSchedule,
+  nextRunAt,
+} from "../../../storage/cron.js";
+import { getPulseStatus } from "../../../core/background/pulse.js";
+import { replyHtmlChunked } from "./chunked-reply.js";
+
+export async function replyCronJobs(ctx: Context): Promise<void> {
+  const jobs = getAllCronJobs();
+  if (jobs.length === 0) {
+    await ctx.reply("No cron jobs.");
+    return;
+  }
+  const lines = jobs.map((j) => {
+    const nextMs = nextRunAt(j);
+    const last = j.lastRunAt
+      ? new Date(j.lastRunAt).toISOString().slice(0, 16).replace("T", " ")
+      : "never";
+    const next = nextMs
+      ? new Date(nextMs).toISOString().slice(0, 16).replace("T", " ")
+      : "?";
+    return `${j.enabled ? "✓" : "✗"} <b>${escapeHtml(j.name)}</b>\n  <code>${escapeHtml(describeSchedule(j))}</code> | ${j.type} | runs: ${j.runCount} | last: ${last} | next: ${next}`;
+  });
+  await replyHtmlChunked(
+    ctx,
+    `<b>Cron Jobs (${jobs.length})</b>\n\n` + lines.join("\n\n"),
+  );
+}
+
+export async function replyPulseStatus(
+  ctx: Context,
+  _rest: string[],
+  bot: Bot,
+): Promise<void> {
+  const chats = getPulseStatus();
+  if (chats.length === 0) {
+    await ctx.reply("No pulse chats.");
+    return;
+  }
+  const lines = await Promise.all(
+    chats.map(async (p) => {
+      let title = p.chatId;
+      try {
+        const id = parseInt(p.chatId, 10);
+        if (!isNaN(id)) {
+          const chat = await bot.api.getChat(id);
+          title = "title" in chat ? (chat.title ?? p.chatId) : p.chatId;
+        }
+      } catch {
+        /* skip */
+      }
+      return `${p.enabled ? "✓" : "✗"} ${escapeHtml(title)}`;
+    }),
+  );
+  await replyHtmlChunked(
+    ctx,
+    `<b>Pulse (${chats.length})</b>\n\n` + lines.join("\n"),
+  );
+}

package/src/frontend/telegram/admin/chunked-reply.ts

@@ -0,0 +1,20 @@
+import type { Context } from "grammy";
+import { splitMessage } from "../formatting.js";
+import { TELEGRAM_MAX_TEXT } from "../actions/types.js";
+
+/**
+ * Reply with an HTML listing, split across messages when it outgrows
+ * Telegram's 4096-char cap. The per-item listings (chats, cron, pulse)
+ * scale with the daemon's chat count, and a single oversized
+ * `ctx.reply` fails the whole command with 400 "message is too long".
+ * Entries are `\n\n`-separated and each carries balanced tags, so the
+ * paragraph-first splitter never cuts through markup.
+ */
+export async function replyHtmlChunked(
+  ctx: Context,
+  text: string,
+): Promise<void> {
+  for (const chunk of splitMessage(text, TELEGRAM_MAX_TEXT)) {
+    await ctx.reply(chunk, { parse_mode: "HTML" });
+  }
+}

package/src/frontend/telegram/admin/health.ts

@@ -0,0 +1,81 @@
+/**
+ * `/admin stats` / `errors` / `logs` / `daily` — the daemon-health
+ * subcommands.
+ */
+
+import type { Context } from "grammy";
+import { readFileSync } from "node:fs";
+import { files, dirs } from "../../../util/paths.js";
+import { tailFile } from "../../../util/tail-file.js";
+import { escapeHtml } from "../formatting.js";
+import { getAllSessions } from "../../../storage/sessions.js";
+import { todayLogDate } from "../../../storage/daily-log.js";
+import { getActiveCount } from "../../../core/engine/dispatcher.js";
+import { getHealthStatus, getRecentErrors } from "../../../util/watchdog.js";
+import { formatDuration } from "../helpers/index.js";
+
+export async function replyStats(ctx: Context): Promise<void> {
+  const h = getHealthStatus();
+  const sessions = getAllSessions();
+  const turns = sessions.reduce((s, x) => s + x.info.turns, 0);
+  const mem = process.memoryUsage();
+  await ctx.reply(
+    [
+      `<b>🦅 Talon Stats</b>`,
+      "",
+      `<b>Uptime:</b> ${formatDuration(h.uptimeMs)}`,
+      `<b>Messages:</b> ${h.totalMessagesProcessed}`,
+      `<b>Sessions:</b> ${sessions.length}`,
+      `<b>Turns:</b> ${turns}`,
+      `<b>Last active:</b> ${h.msSinceLastMessage < 60000 ? "now" : formatDuration(h.msSinceLastMessage) + " ago"}`,
+      "",
+      `<b>Memory:</b> ${(mem.heapUsed / 1024 / 1024).toFixed(1)}MB heap / ${(mem.rss / 1024 / 1024).toFixed(1)}MB rss`,
+      `<b>Queue:</b> ${getActiveCount()}`,
+      `<b>Errors:</b> ${h.recentErrorCount}`,
+    ].join("\n"),
+    { parse_mode: "HTML" },
+  );
+}
+
+export async function replyRecentErrors(ctx: Context): Promise<void> {
+  const errors = getRecentErrors(5);
+  if (errors.length === 0) {
+    await ctx.reply("No recent errors.");
+    return;
+  }
+  const lines = errors.map(
+    (e) =>
+      `<code>[${new Date(e.timestamp).toISOString().slice(11, 19)}]</code> ${escapeHtml(e.message.slice(0, 200))}`,
+  );
+  await ctx.reply(
+    `<b>Recent Errors (${errors.length})</b>\n\n` + lines.join("\n\n"),
+    { parse_mode: "HTML" },
+  );
+}
+
+export async function replyLogTail(ctx: Context): Promise<void> {
+  const logPath = files.log;
+  try {
+    const lines = tailFile(logPath);
+    await ctx.reply(`<pre>${escapeHtml(lines.slice(0, 3800))}</pre>`, {
+      parse_mode: "HTML",
+    });
+  } catch {
+    await ctx.reply(`Could not read ${logPath}`);
+  }
+}
+
+export async function replyDailyLog(ctx: Context): Promise<void> {
+  const today = todayLogDate();
+  const logPath = `${dirs.logs}/${today}.md`;
+  try {
+    const content = readFileSync(logPath, "utf-8");
+    const lines = content.trim().split("\n").slice(-30).join("\n");
+    await ctx.reply(
+      `<b>Daily log (${today})</b>\n\n<pre>${escapeHtml(lines.slice(0, 3800))}</pre>`,
+      { parse_mode: "HTML" },
+    );
+  } catch {
+    await ctx.reply(`No daily log for ${today}.`);
+  }
+}

package/src/frontend/telegram/admin/sessions.ts

@@ -0,0 +1,105 @@
+/**
+ * `/admin chats` / `broadcast` / `kill` — the session-level subcommands.
+ */
+
+import type { Bot, Context } from "grammy";
+import type { TalonConfig } from "../../../core/config/index.js";
+import { escapeHtml } from "../formatting.js";
+import { resetSession, getAllSessions } from "../../../storage/sessions.js";
+import { clearHistory } from "../../../storage/history.js";
+import { getChatSettings } from "../../../storage/chat-settings.js";
+import { formatModelLabel } from "../helpers/index.js";
+import { replyHtmlChunked } from "./chunked-reply.js";
+
+/** `/admin chats` — every active session, newest first, titled via getChat. */
+export async function replyActiveChats(
+  ctx: Context,
+  _rest: string[],
+  bot: Bot,
+  config: TalonConfig,
+): Promise<void> {
+  const sessions = getAllSessions();
+  if (sessions.length === 0) {
+    await ctx.reply("No active sessions.");
+    return;
+  }
+  sessions.sort((a, b) => (b.info.lastActive || 0) - (a.info.lastActive || 0));
+
+  const titles = new Map<string, string>();
+  await Promise.all(
+    sessions.map(async (s) => {
+      try {
+        const id = parseInt(s.chatId, 10);
+        if (isNaN(id)) return;
+        const chat = await bot.api.getChat(id);
+        titles.set(
+          s.chatId,
+          "title" in chat
+            ? (chat.title ?? "DM")
+            : "first_name" in chat
+              ? (chat.first_name ?? "DM")
+              : "DM",
+        );
+      } catch {
+        /* inaccessible */
+      }
+    }),
+  );
+
+  const lines = sessions.map((s) => {
+    const age = s.info.lastActive
+      ? `${Math.round((Date.now() - s.info.lastActive) / 60000)}m ago`
+      : "?";
+    const title = titles.get(s.chatId) ?? s.chatId;
+    const model = formatModelLabel(
+      getChatSettings(s.chatId).model ?? config.model,
+    );
+    // `model` is a catalog id (OpenRouter/Kilo ids are free-form), so
+    // it gets the same escaping the title already had.
+    return `<b>${escapeHtml(title)}</b> <code>${s.chatId}</code>\n  ${s.info.turns} turns | ${age} | ${escapeHtml(model)}`;
+  });
+  await replyHtmlChunked(
+    ctx,
+    `<b>Active chats (${sessions.length})</b>\n\n` + lines.join("\n\n"),
+  );
+}
+
+export async function broadcast(
+  ctx: Context,
+  rest: string[],
+  bot: Bot,
+): Promise<void> {
+  const text = rest.join(" ");
+  if (!text) {
+    await ctx.reply("Usage: /admin broadcast <text>");
+    return;
+  }
+  const sessions = getAllSessions();
+  let sent = 0,
+    failed = 0;
+  for (const s of sessions) {
+    const id = parseInt(s.chatId, 10);
+    if (isNaN(id)) continue;
+    try {
+      await bot.api.sendMessage(id, text);
+      sent++;
+      await new Promise((r) => setTimeout(r, 40));
+    } catch {
+      failed++;
+    }
+  }
+  await ctx.reply(
+    `Broadcast: ${sent} sent, ${failed} failed (${sessions.length} total).`,
+  );
+}
+
+export async function killSession(ctx: Context, rest: string[]): Promise<void> {
+  const target = rest[0];
+  if (!target) {
+    await ctx.reply("Usage: /admin kill <chatId>");
+    return;
+  }
+  resetSession(target);
+  clearHistory(target);
+  await ctx.reply(`Session ${target} reset.`);
+}