@wrongstack/telegram 0.293.0 → 0.295.1

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import { expectDefined as expectDefined2 } from "@wrongstack/core";
+import { expectDefined as expectDefined2 } from "@wrongstack/core/utils";
 
 // src/api-client.ts
 var TelegramApiClientError = class extends Error {
@@ -163,30 +163,34 @@ var TelegramApiClient = class {
     });
   }
   sendMessage(chatId, text, opts) {
+    const body = {
+      chat_id: String(chatId),
+      text,
+      disable_web_page_preview: true
+    };
+    if (opts?.parseMode) body.parse_mode = opts.parseMode;
     return this.request("sendMessage", {
-      body: {
-        chat_id: String(chatId),
-        text,
-        disable_web_page_preview: true
-      },
+      body,
       signal: composedSignal(opts?.signal)
     });
   }
   sendMessageWithKeyboard(chatId, text, buttons, opts) {
+    const body = {
+      chat_id: String(chatId),
+      text,
+      disable_web_page_preview: true,
+      reply_markup: {
+        inline_keyboard: [
+          buttons.map((button) => ({
+            text: button.text,
+            callback_data: button.callback_data
+          }))
+        ]
+      }
+    };
+    if (opts?.parseMode) body.parse_mode = opts.parseMode;
     return this.request("sendMessage", {
-      body: {
-        chat_id: String(chatId),
-        text,
-        disable_web_page_preview: true,
-        reply_markup: {
-          inline_keyboard: [
-            buttons.map((button) => ({
-              text: button.text,
-              callback_data: button.callback_data
-            }))
-          ]
-        }
-      },
+      body,
       signal: composedSignal(opts?.signal)
     });
   }
@@ -286,6 +290,7 @@ var TelegramBot = class _TelegramBot {
   /** Single-poller election across wstack instances sharing this token. */
   lock;
   standbyRetryMs;
+  getParseMode;
   standbyTimer = null;
   standbyAnnounced = false;
   // Circular buffer for incoming messages
@@ -306,6 +311,7 @@ var TelegramBot = class _TelegramBot {
     this.offsetStore = opts.offsetStore;
     this.lock = opts.lock;
     this.standbyRetryMs = opts.standbyRetryMs ?? 15e3;
+    this.getParseMode = opts.getParseMode;
     if (this.lock) {
       this.lock.onLost = () => this.handleLockLost();
     }
@@ -432,7 +438,8 @@ var TelegramBot = class _TelegramBot {
       try {
         const timeout = AbortSignal.timeout(1e4);
         const result = await this.api.sendMessage(chatId, text, {
-          signal: signal ? AbortSignal.any([signal, timeout]) : timeout
+          signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+          parseMode: this.getParseMode?.()
         });
         return { ok: true, result };
       } catch (err) {
@@ -468,7 +475,8 @@ var TelegramBot = class _TelegramBot {
       try {
         const timeout = AbortSignal.timeout(1e4);
         const result = await this.api.sendMessageWithKeyboard(chatId, text, buttons, {
-          signal: signal ? AbortSignal.any([signal, timeout]) : timeout
+          signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+          parseMode: this.getParseMode?.()
         });
         return { ok: true, result };
       } catch (err) {
@@ -529,7 +537,11 @@ var TelegramBot = class _TelegramBot {
       for (const upd of updates) {
         this.offset = upd.update_id + 1;
         if (upd.callback_query) {
-          void this.dispatchCallback(upd.callback_query);
+          void this.dispatchCallback(upd.callback_query).catch(
+            (err) => this.log.debug(
+              `Callback dispatch failed: ${err instanceof Error ? err.message : String(err)}`
+            )
+          );
           continue;
         }
         const raw = upd.message ?? upd.edited_message;
@@ -572,7 +584,11 @@ var TelegramBot = class _TelegramBot {
     const denialReason = this.inboundDenialReason(userId, chatId);
     if (denialReason === "user") {
       this.log.debug(`Ignoring message from user ${userId ?? "unknown"} (not in allowedUsers)`);
-      void this.sendMessage(chatId, "\u26D4 You are not authorized to interact with this bot.");
+      void this.sendMessage(chatId, "\u26D4 You are not authorized to interact with this bot.").catch(
+        (err) => this.log.debug(
+          `Failed to send denial notice: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
       return;
     }
     if (denialReason === "chat") {
@@ -736,7 +752,11 @@ var TelegramBot = class _TelegramBot {
     request.promptMessageId = promptMessageId;
     const pending = request.pendingCallbacks.splice(0);
     for (const callback of pending) {
-      void this.dispatchCallback(callback);
+      void this.dispatchCallback(callback).catch(
+        (err) => this.log.debug(
+          `Callback dispatch failed: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
     }
     return true;
   }
@@ -802,7 +822,9 @@ function truncateForTelegram(text, maxLen = 4e3) {
 }
 
 // src/config.ts
+import { resolvePluginConfig } from "@wrongstack/core/plugin";
 var PLUGIN_NAME = "telegram";
+var PLUGIN_CONFIG_ALIASES = ["@wrongstack/telegram"];
 var INBOUND_MODES = ["disabled", "paired", "allowlist", "public"];
 var DEFAULT_CONFIG = {
   inboundMode: "disabled",
@@ -816,7 +838,32 @@ var DEFAULT_CONFIG = {
   maxMessageLength: 4e3,
   singleInstanceLock: true,
   outboundQueuePerChat: 32,
-  outboundQueueConcurrency: 4
+  outboundQueueConcurrency: 4,
+  allowGroupApprovals: false,
+  rateLimitTokensPerSecond: 0.33,
+  rateLimitBurst: 4,
+  parseMode: ""
+};
+var TELEGRAM_CONFIG_FIELDS = {
+  botToken: { lifecycle: "restart", secret: true },
+  notifyChatId: { lifecycle: "restart" },
+  inboundMode: { lifecycle: "hot" },
+  allowedUsers: { lifecycle: "hot" },
+  allowedChats: { lifecycle: "hot" },
+  allowedOutboundChats: { lifecycle: "hot" },
+  allowGroupApprovals: { lifecycle: "hot" },
+  pollIntervalSec: { lifecycle: "hot" },
+  notifyOnSessionEnd: { lifecycle: "hot" },
+  longToolThresholdMs: { lifecycle: "hot" },
+  notifyOnDelegate: { lifecycle: "hot" },
+  maxMessageLength: { lifecycle: "hot" },
+  offsetStoragePath: { lifecycle: "immutable" },
+  singleInstanceLock: { lifecycle: "restart" },
+  outboundQueuePerChat: { lifecycle: "restart" },
+  outboundQueueConcurrency: { lifecycle: "restart" },
+  rateLimitTokensPerSecond: { lifecycle: "hot", description: "Per-chat rate limit (tokens/sec)" },
+  rateLimitBurst: { lifecycle: "hot", description: "Per-chat rate limit burst size" },
+  parseMode: { lifecycle: "hot", description: "Telegram parse mode: HTML, MarkdownV2, or empty for plain text" }
 };
 var telegramConfigSchema = {
   type: "object",
@@ -857,6 +904,7 @@ var telegramConfigSchema = {
     longToolThresholdMs: { type: "integer", minimum: 0 },
     notifyOnDelegate: { type: "boolean" },
     maxMessageLength: { type: "integer", minimum: 100, maximum: 4096 },
+    offsetStoragePath: { type: "string" },
     singleInstanceLock: {
       type: "boolean",
       description: "Elect a single getUpdates poller per bot token across wstack instances (default true)"
@@ -872,24 +920,37 @@ var telegramConfigSchema = {
       minimum: 1,
       maximum: 64,
       description: "Maximum concurrent outbound sends across all chats (default 4)"
+    },
+    allowGroupApprovals: { type: "boolean" },
+    rateLimitTokensPerSecond: {
+      type: "number",
+      minimum: 0.1,
+      maximum: 100,
+      description: "Per-chat rate limit in tokens per second (default: 0.33 \u224820 msg/min)"
+    },
+    rateLimitBurst: {
+      type: "integer",
+      minimum: 1,
+      maximum: 100,
+      description: "Per-chat burst size (default: 1)"
+    },
+    parseMode: {
+      type: "string",
+      enum: ["", "HTML", "MarkdownV2"],
+      description: "Telegram parse mode: HTML, MarkdownV2, or empty for plain text"
     }
   },
   required: ["botToken"]
 };
 function readTelegramConfig(api) {
-  const config = api.config;
-  const extensions = config.extensions;
-  const pluginEntries = config.plugins;
-  const legacyPlugins = pluginEntries;
-  const legacyOpts = legacyPlugins && !Array.isArray(legacyPlugins) ? legacyPlugins[PLUGIN_NAME] : void 0;
-  const entryOpts = pluginOptionsFromEntries(pluginEntries);
-  const extensionOpts = extensions?.[PLUGIN_NAME];
-  const opts = {
-    ...legacyOpts ?? entryOpts,
-    ...extensionOpts ?? {}
-  };
+  const resolution = resolvePluginConfig({
+    name: PLUGIN_NAME,
+    aliases: PLUGIN_CONFIG_ALIASES,
+    config: api.config
+  });
+  const opts = resolution.options;
   const inboundMode = resolveInboundMode(opts, {
-    configured: legacyOpts !== void 0 || entryOpts !== void 0 || extensionOpts !== void 0,
+    configured: resolution.configured,
     warn: api.log?.warn.bind(api.log)
   });
   return {
@@ -898,6 +959,9 @@ function readTelegramConfig(api) {
     inboundMode
   };
 }
+function readTelegramConfigFromConfig(cfg) {
+  return readTelegramConfig({ config: cfg });
+}
 function resolveInboundMode(opts, migration) {
   if (opts.inboundMode !== void 0) {
     if (!INBOUND_MODES.includes(opts.inboundMode)) {
@@ -927,13 +991,6 @@ function resolveInboundMode(opts, migration) {
 function hasEntries(values) {
   return Array.isArray(values) && values.length > 0;
 }
-function pluginOptionsFromEntries(entries) {
-  if (!Array.isArray(entries)) return void 0;
-  const found = entries.find(
-    (entry) => typeof entry === "object" && entry !== null && "name" in entry && (entry.name === "@wrongstack/telegram" || entry.name === PLUGIN_NAME)
-  );
-  return found?.options && typeof found.options === "object" ? found.options : void 0;
-}
 
 // src/redact.ts
 var SENSITIVE_FLAG_PATTERNS = [
@@ -965,7 +1022,7 @@ function redactSecrets(text) {
         delim = "=";
         delimIdx = eq;
       } else if (sp !== -1) {
-        delim = match[sp] ?? null;
+        delim = match[sp];
         delimIdx = sp;
       }
       if (delim !== null && delimIdx >= 0) {
@@ -1143,6 +1200,7 @@ var PollLock = class {
       const raw = readFileSync(this.lockPath, "utf8");
       const parsed = JSON.parse(raw);
       if (typeof parsed.id !== "string" || typeof parsed.pid !== "number") return null;
+      if (!Number.isFinite(parsed.heartbeatAt)) return null;
       return parsed;
     } catch {
       return null;
@@ -1246,7 +1304,8 @@ var OffsetStore = class {
 };
 
 // src/security/outbound.ts
-import { DefaultSecretScrubber, ToolValidationError } from "@wrongstack/core";
+import { DefaultSecretScrubber } from "@wrongstack/core/security";
+import { ToolValidationError } from "@wrongstack/core/types";
 var TELEGRAM_APPROVAL_CAPABILITY = "net.outbound.telegram.approval";
 var secretScrubber = new DefaultSecretScrubber();
 var RAW_TELEGRAM_BOT_TOKEN = /(?<![A-Za-z0-9])\d{5,15}:[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_-])/g;
@@ -1288,7 +1347,7 @@ function scrubTelegramOutboundText(text) {
 }
 
 // src/slash-commands/index.ts
-import { expectDefined } from "@wrongstack/core";
+import { expectDefined } from "@wrongstack/core/utils";
 function tgHealthCommand(bot, cfg) {
   return {
     name: "telegram-health",
@@ -1427,7 +1486,7 @@ function makeTelegramApproveTool(opts) {
       const timeoutMs = Math.min(Math.max(input.timeout_ms ?? 6e4, 1e3), 6e5);
       const configuredUserIds = opts.getAllowedUserIds?.().map(String) ?? [];
       const isGroup = String(chatId).startsWith("-");
-      if (isGroup && (opts.allowGroupApprovals !== true || configuredUserIds.length === 0)) {
+      if (isGroup && (opts.getAllowGroupApprovals?.() !== true || configuredUserIds.length === 0)) {
         throw new Error("Telegram group approvals require explicit per-user configuration.");
       }
       const expectedUserIds = configuredUserIds.length > 0 ? configuredUserIds : [String(chatId)];
@@ -1449,7 +1508,7 @@ _Reply by tapping a button. Auto-denies in ${Math.round(timeoutMs / 1e3)}s._`;
         sessionId: ctx?.session.id ?? "unknown-session",
         expectedChatId: chatId,
         expectedUserIds,
-        allowGroup: isGroup && opts.allowGroupApprovals === true,
+        allowGroup: isGroup && opts.getAllowGroupApprovals?.() === true,
         expiresAt: Date.now() + timeoutMs,
         signal: toolOpts?.signal
       });
@@ -1500,8 +1559,8 @@ var OutboundQueue = class {
   #failed = 0;
   #resolvers = /* @__PURE__ */ new Map();
   constructor(opts) {
-    const maxPerChat = opts.maxPerChat ?? DEFAULT_MAX_PER_CHAT;
-    const maxConcurrency = opts.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY;
+    const maxPerChat = Math.max(1, opts.maxPerChat ?? DEFAULT_MAX_PER_CHAT);
+    const maxConcurrency = Math.max(1, opts.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY);
     this.#opts = {
       maxPerChat,
       maxConcurrency,
@@ -1529,18 +1588,19 @@ var OutboundQueue = class {
     }
     if (entry.kind === "notification") {
       if (lane.pending.length >= this.#opts.maxPerChat) {
-        const dropped = lane.pending.shift();
-        if (dropped) {
+        const dropIndex = lane.pending.findIndex((e) => e.kind === "notification");
+        if (dropIndex === -1) {
           this.#dropped += 1;
-          const droppedResolver = this.#resolvers.get(dropped.id);
-          if (droppedResolver) {
-            this.#resolvers.delete(dropped.id);
-            droppedResolver.resolve(void 0);
-          }
           this.#opts.log?.debug(
-            `Telegram outbound queue dropped a notification for chat ${dropped.chatId} (per-chat limit ${this.#opts.maxPerChat})`
+            `Telegram outbound queue dropped an incoming notification for chat ${entry.chatId} (per-chat limit ${this.#opts.maxPerChat}; only manual entries pending)`
           );
+          return Promise.resolve(void 0);
         }
+        const dropped = lane.pending.splice(dropIndex, 1)[0];
+        this.#dropped += 1;
+        this.#opts.log?.debug(
+          `Telegram outbound queue dropped a notification for chat ${dropped.chatId} (per-chat limit ${this.#opts.maxPerChat})`
+        );
       }
     } else if (lane.pending.length + (lane.running ? 1 : 0) >= this.#opts.maxPerChat) {
       return Promise.reject(
@@ -1632,15 +1692,6 @@ var OutboundQueue = class {
   async #run(entry) {
     const key = String(entry.chatId);
     const lane = this.#lanes.get(key);
-    if (!lane) {
-      const resolver = this.#resolvers.get(entry.id);
-      if (resolver) {
-        this.#resolvers.delete(entry.id);
-        resolver.resolve(void 0);
-      }
-      this.#active -= 1;
-      return;
-    }
     try {
       const result = await this.#opts.send(entry.chatId, entry.text);
       this.#sent += 1;
@@ -1655,7 +1706,7 @@ var OutboundQueue = class {
       if (resolver) {
         this.#resolvers.delete(entry.id);
         resolver.reject(err);
-      } else if (entry.kind === "notification") {
+      } else {
         this.#opts.log?.debug(
           `Telegram outbound queue notification failed for chat ${entry.chatId}: ${err.message}`
         );
@@ -1663,31 +1714,115 @@ var OutboundQueue = class {
     } finally {
       this.#active -= 1;
       lane.running = false;
+      if (lane.pending.length === 0) {
+        this.#lanes.delete(key);
+      }
       this.#schedule();
     }
   }
 };
 
+// src/rate-limiter.ts
+function createTokenBucket(opts) {
+  const tokensPerSecond = opts?.tokensPerSecond ?? 0.33;
+  const burst = opts?.burst ?? 4;
+  const refillIntervalMs = 1e3 / tokensPerSecond;
+  let tokens = burst;
+  let lastRefill = Date.now();
+  return { waitForToken, fill, isFull };
+  async function waitForToken(timeoutMs) {
+    const deadline = timeoutMs !== void 0 ? Date.now() + timeoutMs : Infinity;
+    while (true) {
+      refill();
+      if (tokens >= 1) {
+        tokens -= 1;
+        return;
+      }
+      const now = Date.now();
+      if (now >= deadline) {
+        return;
+      }
+      const nextRefill = lastRefill + refillIntervalMs;
+      const delay = Math.min(
+        Math.max(nextRefill - now, 0),
+        deadline - now,
+        5e3
+        // safety cap: never sleep longer than 5s
+      );
+      await sleep(delay);
+    }
+  }
+  function refill() {
+    const now = Date.now();
+    const elapsed = now - lastRefill;
+    if (elapsed <= 0) return;
+    const newTokens = elapsed / 1e3 * tokensPerSecond;
+    tokens = Math.min(burst, tokens + newTokens);
+    lastRefill = now;
+  }
+  function fill() {
+    refill();
+    return tokens;
+  }
+  function isFull() {
+    refill();
+    return tokens >= burst;
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 // src/bot-queue.ts
+var BUCKET_SWEEP_INTERVAL_MS = 6e4;
 var TelegramBotOutbound = class {
   #queue;
   #bot;
   #log;
+  #buckets = /* @__PURE__ */ new Map();
+  #getRateTokensPerSecond;
+  #getRateBurst;
+  #bucketSweepTimer;
   #stopped = false;
   constructor(opts) {
     this.#bot = opts.bot;
     this.#log = opts.log;
+    this.#getRateTokensPerSecond = opts.getRateLimitTokensPerSecond ?? (() => 0.33);
+    this.#getRateBurst = opts.getRateLimitBurst ?? (() => 4);
     this.#queue = new OutboundQueue({
       maxPerChat: opts.maxPerChat,
       maxConcurrency: opts.maxConcurrency,
-      send: (chatId, text) => this.#bot.sendMessage(chatId, text).then((res) => {
-        if (!res.ok) {
-          throw new Error(`Telegram outbound send returned ok=false for chat ${chatId}`);
-        }
-        return res;
-      }),
+      send: (chatId, text) => this.#rateLimitedSend(chatId, text),
       log: opts.log
     });
+    this.#bucketSweepTimer = setInterval(() => this.#sweepIdleBuckets(), BUCKET_SWEEP_INTERVAL_MS);
+    this.#bucketSweepTimer.unref?.();
+  }
+  #sweepIdleBuckets() {
+    for (const [key, bucket] of this.#buckets) {
+      if (bucket.isFull()) this.#buckets.delete(key);
+    }
+  }
+  /** Per-chat rate-limited send: waits for a token, then delegates to the bot.
+   * Rate-limit values are resolved lazily when a new bucket is created via
+   * the constructor getters so a live config change applies to subsequent
+   * chats without rebuilding the queue. */
+  async #rateLimitedSend(chatId, text) {
+    const key = String(chatId);
+    let bucket = this.#buckets.get(key);
+    if (!bucket) {
+      bucket = createTokenBucket({
+        tokensPerSecond: this.#getRateTokensPerSecond(),
+        burst: this.#getRateBurst()
+      });
+      this.#buckets.set(key, bucket);
+    }
+    await bucket.waitForToken(5e3);
+    const res = await this.#bot.sendMessage(chatId, text);
+    if (!res.ok) {
+      throw new Error(`Telegram outbound send returned ok=false for chat ${chatId}`);
+    }
+    return res;
   }
   /** Manual send (telegram_send tool, /telegram:send): never silently dropped. */
   async sendManual(chatId, text) {
@@ -1711,17 +1846,14 @@ var TelegramBotOutbound = class {
       return;
     }
     const entry = { chatId, text, kind: "notification" };
-    this.#queue.enqueue(entry).catch((err) => {
-      this.#log.debug(
-        `Telegram outbound notification enqueue rejected for chat ${chatId}: ${err.message}`
-      );
-    });
+    void this.#queue.enqueue(entry);
   }
   stats() {
     return this.#queue.stats();
   }
   async stop() {
     this.#stopped = true;
+    clearInterval(this.#bucketSweepTimer);
     await this.#queue.stop();
   }
 };
@@ -1868,7 +2000,7 @@ function makeTelegramReadTool(opts) {
 }
 
 // src/tools/telegram-send.ts
-import { ToolCapabilities } from "@wrongstack/core";
+import { ToolCapabilities } from "@wrongstack/core/security";
 function makeTelegramSendTool(opts) {
   return {
     name: "telegram_send",
@@ -1912,6 +2044,19 @@ function makeTelegramSendTool(opts) {
   };
 }
 
+// src/config-classifier.ts
+import { diffPluginConfig } from "@wrongstack/core/plugin";
+function diffConfigKeys(previous, next) {
+  return diffPluginConfig(
+    previous,
+    next,
+    TELEGRAM_CONFIG_FIELDS
+  ).map((change) => ({
+    key: change.key,
+    classification: change.lifecycle === "hot" ? "hot" : "restart-required"
+  }));
+}
+
 // src/index.ts
 var teardownState = null;
 var DENY_ALL_INBOUND = "__wrongstack_telegram_inbound_disabled__";
@@ -1958,22 +2103,25 @@ function registerCommand(api, command, cleanups) {
     api.slashCommands.unregister(`${PLUGIN_NAME}:${command.name}`);
   });
 }
+function telegramDefaultConfig() {
+  return structuredClone(DEFAULT_CONFIG);
+}
 function telegramFromConfig(cfg) {
-  const ext = cfg.extensions?.[PLUGIN_NAME] ?? {};
+  const tg = readTelegramConfigFromConfig(cfg);
   return {
-    notifyChatId: ext.notifyChatId !== void 0 ? String(ext.notifyChatId) : void 0,
-    allowedOutboundChats: Array.isArray(ext.allowedOutboundChats) ? ext.allowedOutboundChats.filter(
-      (chatId) => typeof chatId === "string" || typeof chatId === "number"
-    ) : [],
-    allowedUserIds: Array.isArray(ext.allowedUsers) ? ext.allowedUsers.filter(
-      (userId) => typeof userId === "string" || typeof userId === "number"
-    ) : [],
-    allowGroupApprovals: ext.allowGroupApprovals === true,
-    notifyOnSessionEnd: ext.notifyOnSessionEnd === true,
-    notifyOnDelegate: ext.notifyOnDelegate !== false,
-    // default true
-    longToolThresholdMs: typeof ext.longToolThresholdMs === "number" ? ext.longToolThresholdMs : 3e4,
-    maxMessageLength: typeof ext.maxMessageLength === "number" ? ext.maxMessageLength : 4e3
+    notifyChatId: tg.notifyChatId !== void 0 ? String(tg.notifyChatId) : void 0,
+    allowedOutboundChats: [...tg.allowedOutboundChats ?? []],
+    allowedUserIds: [...tg.allowedUsers ?? []],
+    allowGroupApprovals: tg.allowGroupApprovals ?? false,
+    notifyOnSessionEnd: tg.notifyOnSessionEnd ?? false,
+    notifyOnDelegate: tg.notifyOnDelegate ?? true,
+    longToolThresholdMs: tg.longToolThresholdMs ?? 3e4,
+    maxMessageLength: tg.maxMessageLength ?? 4e3,
+    outboundQueuePerChat: tg.outboundQueuePerChat ?? 32,
+    outboundQueueConcurrency: tg.outboundQueueConcurrency ?? 4,
+    rateLimitTokensPerSecond: tg.rateLimitTokensPerSecond ?? 0.33,
+    rateLimitBurst: tg.rateLimitBurst ?? 1,
+    parseMode: tg.parseMode ?? ""
   };
 }
 var plugin = {
@@ -1986,31 +2134,29 @@ var plugin = {
     slashCommands: true,
     pipelines: []
   },
+  configAliases: [...PLUGIN_CONFIG_ALIASES],
+  configFields: TELEGRAM_CONFIG_FIELDS,
   configSchema: telegramConfigSchema,
-  defaultConfig: {
-    allowedOutboundChats: [],
-    pollIntervalSec: 2,
-    notifyOnSessionEnd: false,
-    longToolThresholdMs: 3e4,
-    maxMessageLength: 4e3
-  },
+  defaultConfig: telegramDefaultConfig(),
   async setup(api) {
     const log = api.log;
     disposeRuntime(log);
     const cfg = readTelegramConfig(api);
     log.info("Starting Telegram plugin...");
-    const rawCfg = cfg;
     const runtimeCfg = {
       notifyChatId: cfg.notifyChatId,
       allowedOutboundChats: [...cfg.allowedOutboundChats ?? []],
       allowedUserIds: [...cfg.allowedUsers ?? []],
-      allowGroupApprovals: rawCfg.allowGroupApprovals === true,
+      allowGroupApprovals: cfg.allowGroupApprovals ?? false,
       notifyOnSessionEnd: cfg.notifyOnSessionEnd ?? false,
       notifyOnDelegate: cfg.notifyOnDelegate ?? true,
       longToolThresholdMs: cfg.longToolThresholdMs ?? 3e4,
       maxMessageLength: cfg.maxMessageLength ?? 4e3,
       outboundQueuePerChat: cfg.outboundQueuePerChat ?? 32,
-      outboundQueueConcurrency: cfg.outboundQueueConcurrency ?? 4
+      outboundQueueConcurrency: cfg.outboundQueueConcurrency ?? 4,
+      rateLimitTokensPerSecond: cfg.rateLimitTokensPerSecond ?? 0.33,
+      rateLimitBurst: cfg.rateLimitBurst ?? 1,
+      parseMode: cfg.parseMode ?? ""
     };
     const lock = cfg.singleInstanceLock === false ? void 0 : new PollLock(lockPathForToken(cfg.botToken), { log });
     const offsetStore = cfg.offsetStoragePath === "" ? void 0 : new OffsetStore({ token: cfg.botToken, path: cfg.offsetStoragePath });
@@ -2022,8 +2168,24 @@ var plugin = {
       log,
       offsetStore,
       lock,
+      getParseMode: () => runtimeCfg.parseMode,
       onMessage(msg) {
         api.emitCustom("telegram:message_received", msg);
+        const mailbox = api.mailbox;
+        if (mailbox) {
+          mailbox.send({
+            from: "telegram",
+            to: "leader",
+            type: "note",
+            subject: scrubTelegramOutboundText(
+              `\u{1F4E8} Telegram from ${msg.userName ?? `user_${msg.userId ?? "unknown"}`}`
+            ),
+            body: scrubTelegramOutboundText(msg.text),
+            priority: "low"
+          }).catch((err) => {
+            log.debug(`Telegram\u2192mailbox bridge delivery failed: ${err.message}`);
+          });
+        }
         log.info(`\u{1F4E8} Telegram message received (${Math.min(bot.bufferCount, 50)} unread)`);
       }
     });
@@ -2042,7 +2204,9 @@ var plugin = {
         bot,
         log,
         maxPerChat: runtimeCfg.outboundQueuePerChat,
-        maxConcurrency: runtimeCfg.outboundQueueConcurrency
+        maxConcurrency: runtimeCfg.outboundQueueConcurrency,
+        getRateLimitTokensPerSecond: () => runtimeCfg.rateLimitTokensPerSecond,
+        getRateLimitBurst: () => runtimeCfg.rateLimitBurst
       });
       cleanups.push(() => {
         void outbound.stop();
@@ -2060,7 +2224,7 @@ var plugin = {
         getDefaultChatId: () => runtimeCfg.notifyChatId,
         getAllowedOutboundChatIds: () => runtimeCfg.allowedOutboundChats,
         getAllowedUserIds: () => runtimeCfg.allowedUserIds,
-        allowGroupApprovals: runtimeCfg.allowGroupApprovals,
+        getAllowGroupApprovals: () => runtimeCfg.allowGroupApprovals,
         maxMessageLength: runtimeCfg.maxMessageLength,
         log
       });
@@ -2128,6 +2292,8 @@ var plugin = {
             source: "session.end"
           }).then((r) => {
             if (!r.ok) log.warn(`session.ended notification delivery failed: ${r.error ?? "unknown"}`);
+          }).catch((err) => {
+            log.debug(`session.ended notification delivery threw: ${err.message}`);
           });
         })
       );
@@ -2148,6 +2314,8 @@ var plugin = {
             source: "tool.exec"
           }).then((r) => {
             if (!r.ok) log.warn(`tool.executed notification delivery failed: ${r.error ?? "unknown"}`);
+          }).catch((err) => {
+            log.debug(`tool.executed notification delivery threw: ${err.message}`);
           });
         })
       );
@@ -2168,33 +2336,81 @@ var plugin = {
             source: "delegate.completed"
           }).then((r) => {
             if (!r.ok) log.warn(`delegate.completed notification delivery failed: ${r.error ?? "unknown"}`);
+          }).catch((err) => {
+            log.debug(`delegate.completed notification delivery threw: ${err.message}`);
           });
         })
       );
       const unlistenConfig = api.onConfigChange((next, prev) => {
+        const nextTg = readTelegramConfigFromConfig(next);
+        const prevTg = readTelegramConfigFromConfig(prev);
+        const changedKeys = diffConfigKeys(prevTg, nextTg);
+        const hotKeys = changedKeys.filter((c) => c.classification === "hot").map((c) => c.key);
+        const restartKeys = changedKeys.filter((c) => c.classification === "restart-required").map((c) => c.key);
         const fresh = telegramFromConfig(next);
         const was = telegramFromConfig(prev);
-        runtimeCfg.notifyChatId = fresh.notifyChatId;
-        runtimeCfg.allowedOutboundChats = fresh.allowedOutboundChats;
-        runtimeCfg.allowedUserIds = fresh.allowedUserIds;
-        runtimeCfg.allowGroupApprovals = fresh.allowGroupApprovals;
-        runtimeCfg.notifyOnSessionEnd = fresh.notifyOnSessionEnd;
-        runtimeCfg.notifyOnDelegate = fresh.notifyOnDelegate;
-        runtimeCfg.longToolThresholdMs = fresh.longToolThresholdMs;
-        runtimeCfg.maxMessageLength = fresh.maxMessageLength;
-        if (fresh.notifyChatId !== was.notifyChatId || fresh.maxMessageLength !== was.maxMessageLength) {
-          notifyChannel = fresh.notifyChatId !== void 0 ? new TelegramNotificationChannel({
+        const hotSet = new Set(hotKeys);
+        const HOT_APPLIERS = /* @__PURE__ */ new Map([
+          ["allowedOutboundChats", (r, f) => {
+            r.allowedOutboundChats = f.allowedOutboundChats;
+          }],
+          ["allowedUsers", (r, f) => {
+            r.allowedUserIds = f.allowedUserIds;
+          }],
+          ["notifyOnSessionEnd", (r, f) => {
+            r.notifyOnSessionEnd = f.notifyOnSessionEnd;
+          }],
+          ["notifyOnDelegate", (r, f) => {
+            r.notifyOnDelegate = f.notifyOnDelegate;
+          }],
+          ["longToolThresholdMs", (r, f) => {
+            r.longToolThresholdMs = f.longToolThresholdMs;
+          }],
+          ["maxMessageLength", (r, f) => {
+            r.maxMessageLength = f.maxMessageLength;
+          }],
+          ["allowGroupApprovals", (r, f) => {
+            r.allowGroupApprovals = f.allowGroupApprovals;
+          }],
+          ["rateLimitTokensPerSecond", (r, f) => {
+            r.rateLimitTokensPerSecond = f.rateLimitTokensPerSecond;
+          }],
+          ["rateLimitBurst", (r, f) => {
+            r.rateLimitBurst = f.rateLimitBurst;
+          }],
+          ["parseMode", (r, f) => {
+            r.parseMode = f.parseMode;
+          }]
+        ]);
+        for (const [key, apply] of HOT_APPLIERS) {
+          if (hotSet.has(key)) apply(runtimeCfg, fresh);
+        }
+        if (hotSet.has("maxMessageLength") && fresh.maxMessageLength !== was.maxMessageLength) {
+          notifyChannel = runtimeCfg.notifyChatId !== void 0 ? new TelegramNotificationChannel({
             bot,
-            chatId: fresh.notifyChatId,
+            chatId: runtimeCfg.notifyChatId,
             maxMessageLength: fresh.maxMessageLength,
             enqueueNotification: (chatId, text) => outbound.enqueueNotification(chatId, text),
             log
           }) : void 0;
         }
-        log.debug("Telegram notification settings updated from config", {
+        if (restartKeys.length > 0) {
+          log.warn(
+            "Telegram config changed restart-required keys \u2014 restart the plugin for these to take effect",
+            { restartKeys, hotKeys }
+          );
+          api.emitCustom("telegram:restart_required", {
+            keys: restartKeys,
+            message: `Restart required for: ${restartKeys.join(", ")}`
+          });
+        }
+        log.debug("Telegram config updated", {
+          hotApplied: hotKeys,
+          restartRequired: restartKeys,
           notifyOnSessionEnd: runtimeCfg.notifyOnSessionEnd,
           notifyOnDelegate: runtimeCfg.notifyOnDelegate,
           longToolThresholdMs: runtimeCfg.longToolThresholdMs,
+          parseMode: runtimeCfg.parseMode,
           notifyChatId: runtimeCfg.notifyChatId ?? "not set"
         });
       });